# DOCS-GUIDE.md

How documentation in this repo is organized and written. The primary consumer of these docs is an **LLM coding agent** — the rules below are tuned for that, not for human browsing.

## Why this matters

LLM agents pay a real cost for every token they read. Documentation that is duplicated, buried, or scattered forces the agent to load more context than the task needs, which slows it down, blows the cache, and lets stale copies drift out of sync. The structure below exists to keep one fact in one place and let the agent reach it through the shortest path.

## The three-layer structure

```
<repo-root>/
  CLAUDE.md           # layer 1: thin index, pointers only
  DOCS-GUIDE.md       # this file
  <tool>/
    README.md         # layer 2: tool entry point, router into deep docs
    CLAUDE.md         # (optional) tool-specific agent guide
    AGENTS.md         # (optional) coding-agent rules for this tool
    <doc-area>/...    # layer 3: deep documentation, one file per concept
```

Each layer has a strict job. If a piece of content fits two layers, it belongs in the deeper one — only the deeper layer is allowed to grow.

### Layer 1 — root `CLAUDE.md`: thin index only

`CLAUDE.md` answers exactly one question for the agent: **"Given this task, which tool's documentation do I open?"** Nothing else.

Allowed content:

- One paragraph: what this repo is.
- A `Layout` section: each tool folder, one line, with a link to its `README.md`.
- A `Tool / resource index` table: task → tool, where each cell links into the tool's `README.md` (or a specific deep doc when that's clearly the right entry point).
- Repo-wide conventions and a pointer to this `DOCS-GUIDE.md`.

Disallowed content:

- Tool-specific gotchas, API details, build commands, workflow steps, code samples, schema notes, incident histories.
- Any per-doc fan-out (long bulleted lists of every file inside a tool — that belongs in the tool's `README.md`).
- Anything that would have to change when a tool's internals change. Per-tool churn must stay inside the tool folder.

If the agent has to read `CLAUDE.md` past the index to answer a tool-specific question, `CLAUDE.md` is too fat. Push the answer down a layer.

**Rule of thumb:** if `CLAUDE.md` exceeds ~150 lines or repeats facts that already live inside a tool folder, refactor.

### Layer 2 — `<tool>/README.md`: tool entry point

Every top-level folder under the repo root is a "tool" — a discrete bundle of code, reference material, or both. **Every tool MUST have a `README.md` at its own root.** That README is a router, not a manual.

Required sections, in this order:

1. **One-sentence identification.** What the tool is, what it's for.
2. **Hard constraints / prerequisites.** Anything that, if missed, invalidates the rest of the doc — runtime, architecture, auth, admin requirements, vendor installs. Front-load these.
3. **Layout.** The folder shape with one-line descriptions of each immediate child. Don't catalog deeply; the agent can `ls`.
4. **Resource index.** Task → file table covering the tool's deep docs and any sibling agent guides (`CLAUDE.md`, `AGENTS.md`).
5. **Maintenance.** Pointer back to this `DOCS-GUIDE.md` and to `../CLAUDE.md`, with a note that both must be updated when the tool's surface changes.

Disallowed: long prose tutorials, full API references, schema dumps, workflow walkthroughs. The README routes; the deep docs explain.

### Layer 3 — deep documentation

Workflow guides, API references, sample projects, incident notes, schema captures. The bulk of the bytes lives here.

Rules:

- **One file per cohesive concept.** Don't merge unrelated topics into a kitchen-sink doc. Don't fragment a single concept across five files because each step felt small.
- **Lead with a one-sentence summary** at the top of every file. Agents grep headers.
- **Cross-link explicitly** with `[label](relative/path.md)`. Bare filenames in prose are invisible to the renderer and to the agent's link-following.
- **Date and status time-sensitive material** (incident notes, regression tracking, "active defect" docs). Stale undated content is worse than no content.
- **Code samples must be runnable as stated.** If a snippet only works under a specific platform constraint, say so inline — don't rely on the reader having read the README first.

## Writing conventions

- Prefer **tables** for catalogs (task → resource, type → meaning), **numbered lists** for ordered procedures, **prose** for "why".
- **Don't duplicate content.** If the same fact would naturally live in two files, designate one canonical home and have the other link to it. Duplication is the #1 cause of doc drift.
- **Use relative paths** that resolve from the file's own location. Avoid absolute filesystem paths in cross-references.
- **No decorative chrome.** Skip emojis, banner art, "Welcome to..." intros, and trailing summaries that restate the doc.
- **Be concrete.** Name the file, the function, the command, the constraint. Vague guidance ("be careful with COM") wastes tokens.
- **Mark uncertainty.** If something is provisional or unverified, say so. Confident-sounding wrong content is the worst outcome for LLM consumers.

## What goes where — quick test

| Content | Goes in |
| --- | --- |
| "Which tool handles X?" | root `CLAUDE.md` index row |
| "What is this tool and what constrains it?" | `<tool>/README.md` |
| "How do I do task X with this tool?" | `<tool>/<doc-area>/<task>.md` |
| Tool API reference / type catalog | `<tool>/<reference>/...` |
| Coding rules for an agent working in this tool | `<tool>/AGENTS.md` or `<tool>/CLAUDE.md` |
| Active incident / regression / defect | `<tool>/<dated-incident>.md`, linked from the tool README |
| Cross-tool architectural rule | root `CLAUDE.md`, only if it can be violated without entering a tool folder |

If you can answer the question by reading only the root `CLAUDE.md` index plus one `<tool>/README.md`, the structure is working.

## Maintenance discipline

- **New tool added →** create `<tool>/README.md` first, then add **one** row to the root `CLAUDE.md` index pointing to that README. Resist adding a per-file fan-out at the root.
- **Tool removed →** delete the row in `CLAUDE.md` in the same change. Orphaned index rows are worse than missing ones.
- **Doc renamed or moved →** grep the repo for the old path and fix every reference in the same change. Stale paths are the largest single source of LLM confusion in this repo.
- **Tool internals change →** update the tool's own README and deep docs; touch the root `CLAUDE.md` only if the task → tool mapping changed.
- **`CLAUDE.md` exceeds ~150 lines, or starts repeating tool-internal facts →** refactor. Pull content down into the appropriate tool's README.md or deep docs.

When in doubt, ask: *would a different tool's agent ever need this?* If no, it doesn't belong at the root.
