magus v0.4.2 is out. See what's new
¶ View generated markdown
5 min read

magus-docs-lookup

The --simple permutation is 19% smaller: 2956 of 3670 bytes.

Traverse magus's own documentation to answer a "how does magus do X / what does Y mean / where is Z documented" question, instead of guessing an answer or a URL. Use when you need authoritative magus behavior (a CLI flag, a spell op, a diagnostic code, a config key, a stdlib module) and the workspace graph cannot give it. Do NOT use for facts about THIS workspace (use magus-query) or to run work (use magus-run).

Install it, rather than copying from this page:

magus agent install .claude/skills   # writes both forms below

An installed copy carries a provenance stamp, so magus doctor can tell you when a magus upgrade has made it stale. Text copied from this page carries none.

What an installed copy carries

magus agent install writes this frontmatter above the body. magus doctor reads it to report whether your installed skills are current.

field value
license GPL-3.0-or-later
compatibility any-agent
source magus
agent-skill-version 51
knowledge-schema-version 10
skill-content 0fb7b622ba6e
skill-variant full

The skill-content digest covers this skill alone, and both permutations below report it: they go stale together, never one silently, and a change to another skill does not move it.

Full form

Every mechanical step spelled out, plus the rationale for each. Installed as the <name>-full twin: loaded by name rather than always, so a reader who needs the long form can ask for it without every session carrying it.

# Navigating the magus docs

magus ships one official documentation corpus. It is a static site, so its
structure is fixed and machine-readable: this skill teaches HOW to move through
it; the pages themselves carry the WHAT. Reach for it when a magus-domain fact
is not derivable from the workspace graph - the docs are the source of truth for
magus's own behavior, so read them rather than guessing.

Two places serve the same pages:

- In the magus repo (a `magusfile.buzz` at the root, a `docs/` tree): read `docs/<name>.md`
  directly. This is where the skill is dogfooded, so prefer it here.
- Published: the deployed site at `https://eli.gladman.cc/magus/`. Every page is
  also emitted as raw Markdown at `<page-url>index.md` for clean fetching.

## FAST PATH: start from the index, do not guess URLs

Two files at the docs root turn "find the right page" into a lookup, not a guess:

- `llms.txt` - one titled link per page, each pointing at that page's raw
  Markdown (`<url>index.md`), with a one-line description. Read this FIRST to
  locate a page, then fetch its `index.md`.
- `search-index.json` - a flat array of `{url, title, text, tags, description}`,
  one record per page. Grep it for a keyword when you do not know the page name.

WRONG: guess `https://.../go-spell` or grep the open web.
CORRECT: read `llms.txt` (or `docs/` locally), find the entry, fetch its Markdown.

## URL scheme

Pages use extensionless directory URLs; append `index.md` for the raw source.

| You have                     | Page URL             | Raw Markdown                |
| ---------------------------- | -------------------- | --------------------------- |
| the `go` spell               | `/spells/go/`        | `/spells/go/index.md`       |
| the `magus run` command      | `/manpage/magus-run/`| `/manpage/magus-run/index.md`|
| diagnostic MGS2001           | `/codes/sandbox/MGS2001/` | `.../MGS2001/index.md` |

## Where things live (stable IDs route straight to a page)

magus mints stable IDs; each maps to a fixed section, so you jump without searching:

| Looking for                        | Go to                        |
| ---------------------------------- | ---------------------------- |
| a CLI command / flag               | `/manpage/magus-<cmd>/`      |
| a spell and its ops                | `/spells/<name>/`            |
| a diagnostic `MGSxxxx`             | `/codes/` (grouped by family)|
| a stdlib module (fs, os, http, ...)| `/buzz/modules/<name>/`      |
| a core concept (targets, cache, charms, sandbox, affected, ...) | `/<concept>/` |
| install / download                 | `/download/` and its children|
| the whole map                      | `/documentation/`            |

## Traversing within the docs

Every page gives you three axes, so from one page you can reach its whole area:

- Breadcrumb (up): the trail back to `/documentation/`.
- "In this section" (siblings + children): the other pages under this page's
  section landing. A `page_type: overview` page IS a section landing.
- Prev / next (pager): the adjacent pages in the same section.

So: land via `llms.txt`, read the page, then use "In this section" to sweep its
siblings - do not re-search for each one.

## In the magus repo

The `docs/` Markdown is the source of truth; `docs/gen/` is generated output
(never edit it - change the source and regenerate). MAGUS.md is a routing index
generated for HUMAN readers, so do not answer from it: it is true only as of the
last regeneration, and every fact in it has a live command. The knowledge graph
carries every page as a `doc` node, so `magus query "kind=doc"` (see the
magus-query skill) lists them from the graph.

Short form

The enumeration dropped, the judgment kept - for the most capable readers, not the least; the bar under the heading above shows by how much. This is the always-loaded primary. Both are hand-authored from one source body; see Skills for the difference.

Show the short form 
# Navigating the magus docs

magus ships one official documentation corpus. Reach for it when a magus-domain fact
is not derivable from the workspace graph - they are the source of
truth for magus's own behavior.

Two places serve the same pages:

- In the magus repo (a `magusfile.buzz` at the root, a `docs/` tree): read `docs/<name>.md`
  directly.
- Published: the deployed site at `https://eli.gladman.cc/magus/`. Every page is
  also emitted as raw Markdown at `<page-url>index.md` for clean fetching.

## FAST PATH: start from the index, do not guess URLs

Two files at the docs root turn "find the right page" into a lookup, not a guess:

- `llms.txt` - one titled link per page, each pointing at that page's raw
  Markdown (`<url>index.md`), with a one-line description. Read this FIRST to
  locate a page, then fetch its `index.md`.
- `search-index.json` - a flat array of `{url, title, text, tags, description}`,
  one record per page. Search it when you do not know the page name.

## URL scheme

Pages use extensionless directory URLs; append `index.md` for the raw source.

| You have                     | Page URL             | Raw Markdown                |
| ---------------------------- | -------------------- | --------------------------- |
| the `go` spell               | `/spells/go/`        | `/spells/go/index.md`       |
| the `magus run` command      | `/manpage/magus-run/`| `/manpage/magus-run/index.md`|
| diagnostic MGS2001           | `/codes/sandbox/MGS2001/` | `.../MGS2001/index.md` |

## Where things live (stable IDs route straight to a page)

magus mints stable IDs; each maps to a fixed section:

| Looking for                        | Go to                        |
| ---------------------------------- | ---------------------------- |
| a CLI command / flag               | `/manpage/magus-<cmd>/`      |
| a spell and its ops                | `/spells/<name>/`            |
| a diagnostic `MGSxxxx`             | `/codes/` (grouped by family)|
| a stdlib module (fs, os, http, ...)| `/buzz/modules/<name>/`      |
| a core concept (targets, cache, charms, sandbox, affected, ...) | `/<concept>/` |
| install / download                 | `/download/` and its children|
| the whole map                      | `/documentation/`            |

## Traversing within the docs

Every page gives you three axes:

- Breadcrumb (up): the trail back to `/documentation/`.
- "In this section" (siblings + children): the other pages under this page's
  section landing.
- Prev / next (pager): the adjacent pages in the same section.

Land via `llms.txt`, then sweep siblings via "In this section".

## In the magus repo

The `docs/` Markdown is the source of truth; `docs/gen/` is generated output
(never edit it - change the source and regenerate). MAGUS.md is a routing index
generated for HUMAN readers, so do not answer from it: true only as of its last
regeneration. `magus query "kind=doc"` lists every
page from the graph.
Agent skillsEvery skill magus installs, in both curated permutations, generated from the embedded bodies. ChangelogEvery released change to magus, newest first, in Keep a Changelog format. Generated from releases/*.yaml. ScopeThe claim magus is built on - that a correct incremental build already requires a precise model of your repo, and everything else is a read of it. Includes the test for what belongs, the boundaries, and where the claim is strained. magus-queryQuery the magus knowledge graph to find and relate entities (projects, targets, spells, ops, charms, modules, diagnostics, docs).
generatedinternal/agent/skills/magus-docs-lookup/SKILL.mdagentsskillsmagus-docs-lookup
Last updated (77dde07d)
Earlier changes on this page (7)

Full history ↗ · Blame source ↗

Glossary

Workspace

The magus root directory that owns a set of projects and shared config; the unit magus operates over. See workspace.

Magusfile

The magusfile.buzz that declares a project's targets (as export funs) and binds its spells. See targets.

Target

A named operation (build, test, ...) you invoke with magus run <target>; it may compose a spell's tool-native operations and depend on other targets. See targets.

Op

A single tool-native command a target composes (long form: operation); the middle of the work hierarchy (Spell to Op to Target). See operations.

Spell

A language/runtime adapter (e.g. go, md) that maps generic targets onto a toolchain's real commands. See spells.

Charm

An execution modifier attached with : (lint:rw) that changes how a target runs, not which one; the built-in rw flips a check-only target to mutate in place, and ci always strips it. See charms.

Module

A magus stdlib namespace a magusfile imports for host capabilities: filesystem, exec, vcs, and more. See the module reference.

Buzz

The language magusfiles are written in (the .buzz engine). See engines.

Cache

The content-addressed store magus consults before running a target, so unchanged work is skipped. See cache.

Affected

The set of projects touched by a change; magus affected <target> runs a target only over them. See affected.

Sandbox

The restricted filesystem and environment a target runs in, so builds stay reproducible and side-effect-free. See sandbox.

CI

An ordinary magusfile-defined target you compose yourself with magus\needs - magus does not hardcode its stages. Magus.RunCI treats it specially only in that it strips the rw charm, it is the anchor magus affected ci keys off, and a selected scope with no project declaring it is a load error rather than a silent no-op. See targets.

Knowledge graph

The queryable graph of a workspace's spells, targets, docs, and code relationships; query it with magus query/explain/path. See knowledge.

MAGUS.md

The committed routing index at a workspace root, regenerated from the knowledge graph: it lists every node and points at the exact query for a given question, so it is the entry point an agent reads first. See knowledge.

Diagnostic code

A stable MGSxxxx identifier attached to a magus warning or error, so it can be referenced and looked up; some are guardrails (see wards), others hard errors.

Session

One magus process's recorded facts - the targets it finished, their outcomes, and the lease it acted as - kept in a repo-scoped store every worktree shares. magus session lists them; the store prunes itself by last-fact age.

Conventions

Placeholders

Angle brackets mark a value you replace with your own - never type the brackets:

magus run <target>
magus completion <shell>    # e.g. bash, zsh, fish

<target>, <path>, <shell>, <name> and the like are stand-ins, not literal text.