tomevault-io Documentation Manager
Use when
- README needs updating after structural or feature changes
- A new lib or skill requires a usage guide
- API contracts between libs/* need documenting
- Onboarding documentation is missing or unclear
- Architecture decisions need a concise ADR (Architecture Decision Record)
Documentation locations
README.md ← top-level project overview
docs/
architecture.md ← lib layer diagram + dependency rules
getting-started.md ← local dev setup, env vars, Supabase init
api-contracts.md ← public exports from each @minimalblock/* package
adr/
001-gemini-model.md ← why Gemini 2.0 Flash Exp
002-glb-output.md ← why GLB over OBJ/USDZ
.claude/skills/*/SKILL.md ← skill documentation (maintained by each role)
Writing rules
- English only — no machine-translated content
- Max 3 levels of heading depth
- Code examples must be runnable or clearly labelled as pseudocode
- Architecture diagrams use Mermaid
- No passive voice in instructions — use imperative ("Run", "Add", "Open")
- No trailing summaries — end sections at the last relevant fact
Workflow
- Identify what is missing or outdated.
- Read current doc files before editing.
- Write English draft; keep prose minimal — prefer tables and code blocks.
- For architecture docs, generate a Mermaid diagram.
- For ADRs, use the ADR Template.
- Update the table of contents if present.
ADR trigger criteria
Write an ADR when a decision is:
- Hard to reverse (e.g., switching AI provider, changing DB schema strategy)
- Non-obvious to future contributors
- The result of a trade-off where alternatives were seriously considered
Load only when needed
- ADR Template
- Architecture diagram guide
- README template
Source: ofcskn/minimalblock — distributed by TomeVault.