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 spell definition can never be the one that runs without magus.yaml saying so: a spells/<name> shadowed by a same-named one higher in the tree, a workspace spell carrying an embedded spell's name, or a workspace directory at a declared remote path. 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. MGS1033: a cacheable target composes an op that reaches outside the treeFires when a cacheable target composes a spell op declaring reads-external or mutates-external. A replay then reports a verdict that has expired, or a side effect that never happened, and both look green. MGS1034: a target reads a file it declares as its own outputFires when one target names the same path in ctx.readsFiles and ctx.writesFiles. The cache restores an output before the target runs, so the bytes keying the target are the bytes the cache wrote and an edit to that file is invisible. MGS1035: a target writes the tree when it was given no rw charmFires when a target branches on the rw charm but calls fs\writeFile outside that branch. The run that was meant only to judge the tree edits it first, reports the edit as a finding, and leaves it behind. MGS1036: a narrowed footprint dropped the files its own ops readA target declares ctx.readsFiles, which replaces the project baseline, and then runs a spell op over file kinds that footprint never names. The op replays instead of running, and the gate stays green. MGS1037: a tool's observation is keyed as its versionFires when a spell declares one command as both a tool's version probe and its observation probe without a VersionKey. The two probes reach different targets, so the feed's identity ends up keying targets that never run the tool. MGS1038: a magus.project option was removedFires when a magusfile sets a magus.project key that an older magus accepted and this one removed. Load stops and names the key, because the value it declared is no longer honored. MGS1039: magus is called without being importedFires when a magusfile, spell or Buzz script calls magus\ without importing it. magus was bound implicitly until v0.5.0 made it an ordinary host module. MGS1041: a remote spell import is not declaredFires when a magusfile imports a registry path that magus.yaml does not declare. The declaration names the tag magus.lock pins, so without it there is no digest to verify and nothing loads. MGS1042: a remote spell does not match its digestFires when a registry serves a manifest or layer for a pinned spell whose bytes do not hash to the digest magus.lock names, or when an offline load finds a cached copy that no longer matches. The import does not load. MGS1043: a remote spell's lock entry is missing or staleFires when magus.yaml declares a remote spell that magus.lock does not pin, or pins for a different tag than magus.yaml now tracks. Only the update charm resolves a tag, so an ordinary run refuses instead of resolving it. MGS1044: a spell override replaces nothing usableFires when a magus.yaml spell override points at a directory holding no spell, at a spell carrying another name than the embedded one it replaces, or at an embedded spell this magus does not ship. MGS1045: a magus\guard.spawn, command or write registration is unusableFires when magus\guard.spawn, magus\guard.command or magus\guard.write is handed something other than a function, is called twice in one load, or is called from a magusfile other than the root one. The workspace does not load. 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. MGS3016: workspace failed to loadThe server refused a call because the workspace it targets failed to load, usually a magusfile that does not compile. The server holds the failure until a workspace source changes. 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. flags moduleParse a script's argv against the flags it declares. 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. magus\guard.commandRegister one Buzz function the agent guard calls on every agent shell command, to add a deny or an advisory from your repository's own rules. magus ships the seam and no rules. magus\guard.spawnRegister one Buzz function the agent guard calls on every subagent spawn and continuation, to add a deny or an advisory from your own rules. magus ships the seam and no rules. 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. pipe moduleRead the records a magus stage upstream in a pipe writes, and write records for the stage downstream. 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).