Docs

Document a module so future agents (and humans) understand it without re-reading the code. Every doc must be worth the context window space it occupies.

Process

1. Scope

Identify the module or directory the user specified. Verify it exists. If ambiguous, clarify before proceeding.

2. Check existing docs

Search .meridian/docs/ for docs already covering this area — grep for the module name, read matches. Understand what's documented, what's missing, what's stale.

3. Explore the module

Launch Explore agents to build deep understanding:

• Entry points — what starts execution? Exports, routes, handlers, CLI commands
• Data flow — what comes in, how it transforms, where it goes
• Dependencies — what this module uses, what depends on it
• Patterns — conventions, unusual approaches, implicit contracts
• Gotchas — non-obvious behavior that would trip someone up
• Integration points — connections to other modules, services, external APIs

Spawn multiple Explore agents in parallel for different aspects. Follow up on findings — expect 2+ rounds.

4. Identify topics

Each doc covers one topic a future agent would need. Split by topic, not by file. Common categories:

• Architecture/overview — how the module works as a whole
• Integration guide — external API, service, or cross-module connection
• Non-obvious behavior — gotchas, sharp edges, implicit contracts
• Complex workflow — multi-step process, state machine, async flow

Small modules might produce one doc. Large modules might produce three or four.

5. Write docs

For each topic, create a file in .meridian/docs/:

• Filename: kebab-case reflecting the topic (billing-architecture.md, stripe-webhook-handling.md)
• Frontmatter: summary (one line) and read_when (2-5 keywords matching task contexts where an agent would need this)
• Content: what it is, how it works, why it's designed this way, gotchas
• References: point at code with file:line, not code snippets (snippets go stale)
• Length: under ~100 lines per doc — if longer, split into multiple topics

If a doc already exists for a topic, update it. Don't create duplicates.

6. Validate read_when keywords

For each keyword, ask: "What would someone be doing when they need this?" Good keywords describe tasks, not topics:

• "modifying billing logic" — specific, matches real tasks
• "debugging webhook failures" — describes a situation
• "working with code" — too vague, matches everything

What NOT to document

• Function signatures and parameter lists — that's what code is for
• What the code already says clearly — focus on the non-obvious
• Every file in the module — only what's worth context window space
• Style or formatting conventions — that's for linters and CLAUDE.md

Checklist

• Every doc has summary and read_when frontmatter?
• read_when keywords match real task contexts?
• Content is non-obvious knowledge, not code restated in English?
• File:line references instead of code snippets?
• Each doc covers one focused topic?
• Existing docs updated rather than duplicated?