Debugging magusfilesDrop into an interactive Buzz REPL with magusfile bindings preloaded, or set magus\pry() breakpoints mid-target to inspect frames, locals, and state. DependenciesThe two dependency mechanisms in magus - magus\needs (target-level, imperative) and depends_on (project-level, declarative) - how they interact, and how a cross-project needs folds into both. EnginesUnderstand the small engine.Engine seam that lets magus run magusfiles on the embedded Buzz VM and how a new scripting language would plug in. Getting startedA linear, CLI-first walkthrough from installing magus to running your first spell-composed target and a ci pipeline. MGS1001: no ci target definedFires when magus ci runs but no project in the selected scope declares a ci target, meaning the CI anchor would silently do nothing. MGS1002: spell import shadowedFires when a spells/<name> in a nested project is shadowed by a same-named spell higher in the tree, because spell imports resolve root-wins so the deeper definition is dead. MGS1003: bespoke phase-fragment target nameDoctor advice, not a failure. Notes a target named after a static-analysis or formatting subset (typecheck, vet, audit, style, prettify) that would usually be better composed into lint or format. MGS1004: unreached footprint declarationFires when a ctx.readsFiles or ctx.writesFiles call is not statically reachable from a target body, so the declared glob never enters a cache key. MGS1005: redundant footprint globFires when a per-target magus\outputs glob is already declared project-wide, making it redundant. MGS1006: unknown targetFires when a magusfile references a target that no project declares, whether run from the CLI or wired via a dependency like magus\needs. MGS1007: target dependency cycleFires when target dependencies form a cycle, so a target would have to run before itself. Detected across projects during cross-project dispatch. MGS1008: target missing its context parameterFires when an exported magusfile function is not a valid target because its first parameter is not a magus\Context. The signature is the contract magus reads statically to build the graph. MGS1009: target never replays from cacheFires when a target has executed many times and never once replayed from cache, which almost always means its declared footprint is wider than what it actually reads. MGS1010: affected set could not be computedFires when magus cannot derive a changed-file set from the VCS and selects every project as a safety net, turning an incremental run into a full build. MGS1011: cross-project output names an unusable ownerFires at load when a target declares ctx.writesFiles into another project that magus cannot resolve or did not discover, so nothing would own, clean, or regenerate the file. MGS1012: cross-project output forms a dependency cycleFires at load when one target both reads from and writes into the same project, because a cross-project input and a cross-project output imply opposite build-order edges. MGS1013: cross-project output glob escapes its ownerFires at load when the glob half of a cross-project ctx.writesFiles is absolute or contains .., so it would resolve outside the project that owns it. MGS1014: cross-project output was never producedFires when a target declares an output into another project's tree but the run produced no file matching it, so the cache would record an incomplete result. MGS1015: cross-project dependency names an unresolvable projectFires at load when ctx.needs references a target through a project import whose path does not resolve to a path in this workspace, so the dependency edge would be dropped and the affected set would silently under-report. MGS1016: workspace-local Go replace directives driftedFires when a Go module requires another module in the same magus workspace but its go.mod does not replace it at the workspace-relative path. MGS1017: magusfile is not a spellFires when a magusfile imports magus/spell/magusfile or lists magusfile among its spells. Magus binds that driver to every project automatically, so declaring it does nothing. MGS1018: dead output globA project declares an output glob that matches nothing while its other outputs match files. A target that inherits the glob fails its snapshot on a cold cache, long after the mistake was made. MGS1019: committed output records its own commitFires when a committed generated file contains the repository's own HEAD commit, so regenerating after a commit always reports drift and the build can never be clean. MGS1020: output owned by two targetsFires when two targets in the same project declare the same output glob, so whichever runs last wins and the other target's drift gate fails on the next run. MGS1021: workspace requires a newer magusFires when magus.yaml declares a required_version floor the running binary does not satisfy. Upgrade the binary, or raise the pinned version in CI. MGS1022: member only callable from a magusfileFires when a spell or a magus buzz script calls a magus namespace member that declares into, or reads from, the workspace magus is loading. The rest of the namespace still works there. MGS1023: workspace provider reported an unusable project pathFires when a workspace provider's list_projects returns a path magus cannot accept as a project - empty, absolute, escaping the workspace root, the root itself, or not an existing directory. MGS1024: workspace provider project shadowed by a magusfileFires when a workspace provider reports a project at a path that already has a magusfile. The magusfile wins and the provider's configuration for that path is ignored. MGS1025: magusfile calls an API that was removedFires when a magusfile calls a magus function that no longer exists, such as magus.needs or magus.glob. Buzz reads a missing member as null, so these used to fail only at run time and to drop dependency edges from the target graph. MGS1026: a cacheable target reaches for a credentialFires when a target body calls magus.secret.read or magus.secret.endpoint but the target can still replay from cache. A credential is not part of the cache key, so rotating or repointing it invalidates nothing and the target reports success without ever authenticating. MGS1027: a secret grant is malformedFires when magus.secret.endpoint is handed a declaration that cannot safely scope a credential - a missing field, a wildcard or non-ASCII host, an illegal header name. The declaration decides where a credential is forwarded, so magus refuses it rather than guessing. MGS1028: a changed file seeds a project it does not keyA changed file no project declares still pulls its containing project into the affected set. The targets it reruns could not have produced a different answer, and the file that would change the answer is the same one nothing is watching. MGS1029: source glob reaches into a pruned directoryFires when a declared source glob's static prefix lands inside a directory the expansion walk skips, so the pattern matches nothing and contributes no cache key. MGS1031: a project's output is another project's sourceA file one project declares as an output is claimed by a different project's source glob. Nothing is wrong until the bytes change, and then the write is reported against the project that did not make it. MGS3002: VCS unavailableA vcs host-module call could not resolve a version control system, or the VCS command it ran failed, so the value it was asked for does not exist. MGS3003: tool not on PATHproc.which could not resolve a command against PATH, so the tool a target depends on is not installed or not visible to this run. MGS3004: tool not readyA tool is installed but the service it talks to is unreachable, so a spell's readiness probe failed before the op was allowed to run. MGS3005: tool too oldA tool reports a version below the declared minimum, so magus refuses before the run does any work rather than letting the tool fail on an unrecognized flag. MGS3006: tool too newA tool reports a version at or above the declared ceiling, so magus refuses before the run does any work rather than running against a release nobody has qualified. Profiling a magusfileFind which line of a magusfile is filling memory, read the low-headroom warning magus streams before a machine dies, and fix the string-building pattern that costs gigabytes. SpellsA spell is a library of tool-native ops (go-build, cargo-clippy, eslint) plus cache metadata that your magusfile composes into runnable targets. TargetsA Target is the addressable unit of work in magus, keyed by project Path and operation Name, with charms layered on top for execution modifiers. Workspace and projectsA workspace is the discovered root; a project is a directory whose magusfile registers it, and depends_on wires the two into an ordered, cache-aware graph. archive moduleArchive creation and extraction with automatic format detection. base64 moduleBase64 text codec (standard and URL-safe, both padded). charm moduleConstructors for charm values: RFC 6902 JSON Patches over a target's argv (see docs/charms.md). crypto moduleContent digests (SHA-256/512; SHA-1 and MD5 for legacy-checksum interop) and Ed25519 signing. csv moduleDelimiter-separated tabular text (CSV, TSV) parsing and rendering. diff moduleUnified line diffs, for reporting what drifted rather than only that something did. env moduleProcess environment variable access. fmt moduleString formatting (printf-style). fs moduleFilesystem and path primitives. hex moduleHex text codec. http moduleHTTP client. ini moduleINI/properties config parsing and rendering (.npmrc, .gitconfig, .editorconfig). json moduleJSON encode/decode. lcov moduleLCOV coverage reports: the percentage a badge or a floor gate shows, and the line-level merge that keeps it true across multiple test processes. log moduleEmit a message at a level through magus's own logger, so it honors -q/-v/-vv, renders in the run's format, is redacted, and is captured in the run log. magus initBootstrap a magus workspace with a magus.yaml config, magusfile stub, and VCS merge driver; supports global, local, and non-interactive modes. magus moduleMagus core primitives. magus stdlibReference for every magus stdlib module - fs, os, http, json, yaml, crypto, and the rest of the magusfile API surface. magusfile diagnosticsLanding page for MGS1xxx diagnostics that flag authoring mistakes in a workspace's magusfile, such as missing targets or unresolved declarations. markdown moduleGitHub-Flavored Markdown to semantic HTML. math moduleRounding to a decimal place, clamping, and aggregation over a list of numbers. net moduleTCP readiness and port allocation: wait for a service to accept connections, and find a free port. os moduleThe machine and this process: platform triple, CPU count, hostname, the running magus binary, and the two members that shadow Buzz's own (exit, sleep). path modulePure path-string math: abs, rel, clean, is_abs, expand_user, and glob matching. platform moduleNormalize OS/architecture identifiers across naming conventions (aarch64<->arm64, Darwin<->darwin). proc moduleRun other processes. semver moduleSemantic version parsing and comparison (SemVer 2.0.0). sort moduleOrdering for string lists: lexicographic, natural (digit-aware), and semver. strings moduleString helpers Buzz's builtins lack: case conversion, comparison, affix trimming, padding, and splitting into lines or fields. template moduleLogic-less Mustache templating (Mustache spec, via github.com/cbroglie/mustache). term moduleTerminal interaction: capability probes, an interactive picker, and styled output. time moduleTimestamp formatting/parsing and duration parsing (Go time, UTC). toml moduleTOML parse and stringify (TOML 1.0 via pelletier/go-toml/v2). url moduleURL percent-encoding, parsing, and building. uuid moduleUnique identifiers and random tokens (v4 random, v7 time-ordered, plus raw random hex/tokens). vcs moduleVersion-control queries for the current working tree. xml moduleBuild, serialize, and parse XML/SVG. yaml moduleYAML parse and stringify (YAML 1.2 via gopkg.in/yaml.v3).