create-docs

name: create-docs description: Create or update .meridian/docs/ knowledge files for a module or directory. Produces reference docs with frontmatter for context routing.

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?