| name | doc-index |
| description | Regenerate and query the Mycelium agent code index (docs/api-index/), and validate doc_refs entries in issues.yaml. Use when you need to regenerate the committed agent index, query it for symbol locations, or check doc_refs validity. |
| when_to_use | Use when regenerating docs/api-index/ after a public-API change, when querying for a symbol's location in source, when validating doc_refs: entries in issues.yaml, or when checking whether the committed index is current. |
| allowed-tools | Bash(python3:*), Bash(just:*), Read, Grep, Glob |
/doc-index — Regenerate & Query the Agent Code Index
Regenerate
just docs-index
bash scripts/checks/doc-index.sh
The drift gate is also wired into just check (after api). It runs skip-graceful
when python3 is absent.
Query
docs/api-index/INDEX.md — grep-friendly table grouped by crate (for agent context)docs/api-index/index.json — machine-structured: symbol, file, line, summary
Example lookup: grep "binary::bits_to_int" docs/api-index/INDEX.md
doc_refs grammar
In tools/github/issues.yaml, a doc_refs: list entry may be:
api:<crate>::<path> — a symbol in docs/api-index/index.json (checked against items)corpus:<DOC>[#<anchor>] — a doc/section in docs/Doc-Index.md; the anchor is a heading
slug heuristic (Empirical/Declared — may miss atypical headings)src:<path>[:<line>] — a source file location relative to repo root; if :<line> given,
line must exist in the file
Validate all refs:
python3 tools/github/doc_refs_check.py --issues-yaml tools/github/issues.yaml
The validator also runs as part of python3 tools/github/manifest-check.py.
Honesty
The index is Empirical/Declared — a line/regex heuristic. Source is always ground truth.
Items the heuristic can't locate appear in the flagged section of index.json and
INDEX.md (G2: never silently dropped). This includes re-exports (pub use),
macro-generated items, and cfg-gated items.
Never claim the index is exact. Use it to find where to Read, then verify in source.
Ownership
docs/api-index/ is orchestrator-owned — it is REGENERATED (never hand-merged) by the
integrating parent after any octopus merge that touched a public API, before pushing.
