Documentation state audit — dashecorp rig (2026-04-18)

Related

• Referenced by:
  • Stage A — Compiled AGENTS.md with Schema Validation

Docs state audit — dashecorp rig (2026-04-18)

One-paragraph summary

~57 markdown docs across 7 active repos. ~70% frontmatter compliance by file count, ~55% when weighted by repo. Worst offender: rig-agent-runtime/docs/ at 33% (8 of 12 docs have only title:). Only rig-memory-mcp has a CLAUDE.md; 5 repos have AGENTS.md; rig-tools has neither (the outlier). Three architecture docs live side-by-side with no supersedes: chain. The CI check enforces 4 of the 5 frontmatter fields (skips queries) — confirming queries is dead weight. docs-site/ is generated by scripts/build-docs.sh, not duplicated.

Per-repo findings

Repo	CLAUDE.md	AGENTS.md	docs/	.md count	Frontmatter compliance	Notes
conductor-e	—	✓	6 + diagrams/	8	33%	api.md, index.md missing type/queries/updated
rig-agent-runtime	—	✓	12 + images/	14	33%	Worst; 8/12 docs have only title:
rig-gitops	—	✓	7 + whitepaper/19	31	96%	Exemplar
review-e	—	✓	1	3	0%	Single doc, zero frontmatter
rig-tools	—	—	1	2	0%	Only repo with NEITHER agent file. Stub starts mid-document.
rig-memory-mcp	✓	—	1	4	100%	Only repo with CLAUDE.md
infra	—	✓	(none)	4	N/A	No docs/ dir; root files only

Top 5 broken patterns

1. Three architecture docs side by side. rig-gitops/docs/architecture-current.md (10 KB), architecture-proposed.md (9 KB), architecture-proposed-v2.md (24 KB). All updated: 2026-04-16. None links to the others as superseded. Worse: scripts/build-docs.sh:24-26 only copies -current and -proposed to the published site — proposed-v2.md is invisible to readers of rig-docs.pages.dev.

2. rig-agent-runtime/docs/ frontmatter collapse. 8 of 12 files carry only title:. The 16 KB configuration.md has only title + updated.

3. rig-tools/docs/agent-workflow.md starts at ## Workflow (no H1, no frontmatter) and references the old Stig-Johnny/rig-tools namespace — contradicts the rig’s “no personal namespace deps” posture.

4. Empty stub directories. rig-gitops/docs/cost-dashboard/ contains only data.json + index.html (no .md). docs-site/docs/components/dev-e/ still published despite dev-e archived 2026-04-17.

5. CI checks 4 of 5 frontmatter fields. .github/workflows/docs-check.yml validates title description type updated but skips queries. The standard requires all 5; the CI is a subset of the standard it cites.

Findings that contradicted prior assumptions

• docs-site/ is not a duplicate — it is generated by scripts/build-docs.sh. Deleting docs-site/ loses nothing because the script reconstructs it. (Running manually; no CI step.)
• AGENTS.md is dominant (5 repos) vs CLAUDE.md (1 repo). The “CLAUDE.md everywhere” recommendation should be inverted.
• Three repos run mkdocs.yml (conductor-e, rig-agent-runtime, rig-gitops) — each can publish its own site independently, in addition to the aggregated rig-docs.pages.dev. Three publication surfaces, not one.

Method

Audit ran via gh api against GitHub’s contents + trees APIs on 2026-04-18. No local checkout; no destructive action. Results are a point-in-time snapshot; state changes with every PR merge.