docs-steward — the right docs, at the right scope

Package scope and prerequisites

This catalog ships instructions, not the executable runtime. Python modules, scripts, local services and optional tools named below must be installed separately from the upstream project. Check their availability before running commands; if they are missing, explain the prerequisite instead of claiming execution or results. The host agent may use model tokens while following these instructions.

A monorepo accumulates docs at several scopes: global docs at the root, and component docs inside each component's folder. When an LLM coder is bounded to one component (e.g. the server), loading every other component's docs wastes tokens every turn. The steward builds a scoped map so each bounded coder loads only its own docs + links to the relevant global docs.

python -m skills.docs_steward.cli map   .                 # the scoped docs map
python -m skills.docs_steward.cli index . --component server   # preview server/DOCS.md
python -m skills.docs_steward.cli index . --write         # write a DOCS.md per component
python -m skills.docs_steward.cli tasks .                 # lifecycle: finished tasks + report sprawl
python -m skills.docs_steward.cli prune . --write         # strip done tasks (archived, not lost)
python -m skills.docs_steward.cli reports . --keep 5 --archive   # tidy .botte reports
python -m skills.docs_steward.cli review .                # annual review due list (preview)
python -m skills.docs_steward.cli review-prompt . AGENTS.md --tier local
python -m skills.docs_steward.cli review-apply . result.json      # preview verified result
python -m skills.docs_steward.cli audience .              # read-only Markdown/HTML audit
python -m skills.docs_steward.cli knowledge-audit .       # Wiki/second-brain proposals

How it maps

1. Detect components — top-level dirs with a manifest (package.json, pyproject.toml, go.mod, …), known names (server/client/api/tools/…), or code; monorepo containers (apps/, packages/, services/) expand to their children. Pure-doc/asset dirs are never components.
2. Classify docs — every .md/.mdx/.rst/.txt/.html is assigned to the deepest component it lives under, else it's global.
3. Scope + frame — each component gets its local docs, links to the global (LLM-facing) docs, and a token cost: scoped load (local + globals) vs all project docs. .md = load; .html = human reference (linked, not loaded).
4. Index (confirm-gated) — index --write drops a DOCS.md in each component telling a bounded coder exactly what to load. Preview by default; --write to commit the files.

Expected upstream output: a JSON map. Confirm the runtime and actual result. Exposed via [[llm-mcp]] as docs_map. Related: [[directives-audit]] (agent-guidance file health), [[metrics]] (per-component cost), [[checkup]].

Docs lifecycle (finished tasks + report sprawl)

Finished work shouldn't keep costing tokens. lifecycle.py adds two confirm-gated jobs (preview by default, act only on --write/--archive):

• tasks/plans — scan_tasks finds checkbox markdown (- [ ] / - [x]) and counts open vs done + the token waste of done items still in-file. prune strips done items (preserving them in .botte/archive/<name>.done.md — nothing is lost) and moves fully-done plans out of the working tree.
• reports — report_hygiene/reports --archive keep the N most recent of each .botte report and move the rest to .botte/reports/archive/.

Read-only summary via the docs_lifecycle MCP tool (lifecycle_report); the prune/archive actions stay CLI-only and confirm-gated.

Recurring Markdown review

review.py turns periodic instruction cleanup into a fail-closed contract:

• 365 days by default — override with --interval-days or copy configs/docs-review.example.json to the local, Git-ignored .botte/docs-review.json. The config controls include/exclude/focus globs, review-on-change, model hints, and explicit upgrade notes.
• Local inventory — review computes hashes, due dates, priority, token estimates, and evidence-labelled model references. A textual reference is never reported as proof that a model is active. No network/model call occurs.
• Bounded prompt — review-prompt reviews one file. Cloud tier returns full updated_md; local tier returns exact unique find/replace edits. Both bind the result to the source SHA-256 and preserve project facts, preferences, safety, architecture, APIs, commands, and provenance.
• Verified application — review-apply previews by default. --write rejects stale hashes and unsafe paths, archives the exact prior bytes under .botte/archive/docs-review/<timestamp>/, writes atomically, then records the review in Git-ignored .botte-cache/docs-review-state-v1.json.
• Small-model tolerance — the result parser accepts raw JSON, one strict botte-llm provenance line, and one bare json fence. Any other surrounding prose still fails closed before application.
• No-change review — review-mark records an explicit human/model review; it also requires --write to change local state.

The tool never schedules an OS task and never calls a cloud provider. Cron, Task Scheduler, CI, or an agent may invoke the read-only review command at a user-selected cadence.

/checkup now includes due/current counts. Never-reviewed bootstrap files are informational; only elapsed intervals or explicitly watched content changes become drift.

trends snapshot persists only aggregate review counts (due/current, overdue/changed, never-reviewed); paths, content, prompts, and model responses remain outside the historical journal.

Wiki and second-brain integrity

knowledge_integrity.py detects a project Wiki, memory files, daily notes, or the governed Memory Hub only when one is present. The deterministic audit checks entry points, authority/precedence, provenance, freshness, state-versus-event write rules, human approval, project/privacy boundaries, and the declared or inferred always-loaded surface.

knowledge-audit is preview-only and uses 0 LLM tokens. Every gap becomes a bounded proposal with a priority, target file, and suggested change; it never rewrites the knowledge base. Use repeatable --always-loaded <file> arguments to replace filename inference with explicit runtime knowledge. /checkup includes the score and turns P1/P2 gaps into an actionable drift item.

The coverage boundary is explicit: this pass verifies mechanisms, not the truth of every claim. Semantic contradictions still require comparing current-sounding claims with the freshest evidence. A report with zero proposals is therefore not a guarantee that no stale fact exists.

Markdown/HTML audience policy

audience.py makes the format boundary enforceable without taking ownership of the user's publishing workflow:

• Markdown is canonical for LLMs — .md/.mdx/.markdown are editable sources. .html is an optional human rendering or standalone interface.
• HTML never inflates context budgets — maps still list HTML as a human reference, but global, local, scoped, and total token counts include only LLM-facing documents.
• Freshness needs provenance — a renderer can embed <!-- botte-docs-source: path=docs/guide.md; sha256=<source-sha256> -->. audience then reports current or stale from content hashes. A same-stem pair without the marker stays unverified; standalone HTML is informational.
• Read-only and optional — audience never converts, rewrites, deletes, or requires an HTML copy for Markdown. Root MEMORY.md, local agent state, and symlinked documents are excluded from discovery.