/nai-document — staged documentation, checked before it publishes

You type /nai-document <target>. The command “document[s] this workspace from its own files” — resolving that one slug to a lane by five tests applied in order, where “First match wins”; assembling the source list that lane calls for; then running three waves. doc-scoper inventories the sources and writes the scoping brief “the rest of the run is grounded in”. One generator writes a staged page — doc-surveyor in the survey lane, doc-renderer in the blog lane, and in the editorial lane “no generator runs”. Then doc-checker re-opens every cited file and verdicts each claim. Generators “write to 12 Documentation/runs/<target>/proposed/”, never to docs/; promotion — “copying 12 Documentation/runs/<target>/proposed/<file> to the page path” — is “the only publishing act in this system”.

%%{init: {'theme':'neutral', 'flowchart':{'htmlLabels':false,'nodeSpacing':45,'rankSpacing':55}}}%%
flowchart TD
    H["Human types<br/>/nai-document &lt;target&gt;"] --> C

    subgraph L1 ["1 - Orchestrator (.claude/commands)"]
        C["/nai-document<br/>5 ordered tests, first match wins<br/>then assembles the source list"]
    end

    C -->|"no match"| E1["STOP<br/>missing: no target named &lt;target&gt;"]
    C -->|"more than one test matches"| E3["STOP<br/>ask the human which they meant"]

    C -->|"Wave 1"| S["doc-scoper<br/>inventory + create/update mode"]
    S -.->|"working/scope.md"| C

    subgraph L2 ["2 - Wave 2: one generator, chosen by lane"]
        G1["doc-surveyor<br/>survey lane"]
        G2["doc-renderer<br/>blog lane"]
        G3["editorial lane<br/>no generator runs"]
    end

    C -->|"survey"| G1
    C -->|"blog"| G2
    C -->|"editorial"| G3

    G1 -.->|"proposed/ page + claims.json"| K
    G2 -.->|"proposed/ page + claims.json"| K
    G3 -.->|"scoper's claims.json"| K

    subgraph L3 ["3 - Wave 3: every lane, every run"]
        K["doc-checker<br/>re-opens each cited file<br/>CONFIRMED / UNSUPPORTED, terminal"]
    end

    K -.->|"working/verdicts.json"| GD
    GD["Publish guard<br/>orchestrator itself, no subagent<br/>serve path / reachable / links resolve"]
    GD -->|"create + all CONFIRMED + all &check;"| P["Promote: copy proposed/ file<br/>to the page path"]
    GD -->|"otherwise"| ST["Staged, not published<br/>STOP and tell the human which condition failed"]
    GD ==> R["12 Documentation/runs/&lt;target&gt;/report.md"]

    classDef orch fill:#dcefe9,stroke:#0f6f63,stroke-width:2px
    classDef tool fill:#f4f1ea,stroke:#8a7a5a
    classDef human fill:#fdf3e0,stroke:#8a5a00,stroke-width:2px
    classDef agent fill:#fff,stroke:#555
    class C,GD orch
    class S,G1,G2,G3,K agent
    class H,E1,E3,P,ST,R human

Resolving a target to a lane

The command applies its five tests in order, and “First match wins”. Test 1: “11 Blog/<target>.md exists → lane blog, page docs/blog/<target>.html”. Test 2: “<target> is a key in the system map below → lane survey, page as mapped”. Test 3: “docs/architecture/concept-<target>.html exists → lane survey, page is that file”. Test 4: “<target> is in the editorial list below → lane editorial, page none”. Test 5: “No match → STOP. Report missing: no target named <target>. Write nothing.”

The system map is a table, not a rule: “Page names do not derive from command names. This table is the truth; never construct a filename from a slug.” This page is one of its rows — | `document` | `docs/architecture/system-document.html` |. The map also carries a deliberate mismatch: “system-monthly-tax.html is stale naming left from the 2026-07-31 rename of the command to nai-tax-theo. The map records reality. Do not rename the file — renaming a live URL is a deletion by another name.”

The editorial lane has no pattern fallback either: “Exactly these targets, and no pattern fallback: index, features, user-guide, claude-md, verification-patterns, agent-conventions, and readme-<NN> for each numbered section folder (e.g. readme-06).”

The source list, per lane

The four subagents

Each row's tools: column is copied exactly from that agent file's frontmatter. No agent in this system has a web tool: “It uses no web tools, and neither does any agent it dispatches.”

The scoper decides the run's mode: “Determine mode: update if page names a file that exists, create if it does not, and update is never assumed for page: none — the editorial lane is always mode update, because its page always already exists.” And the checker runs regardless of what came before it: “The checker runs in every lane, every run, including when there are zero claims. Its absence is never silent.”

The guardrails, each from the file that enforces it

Promotion, and the guard before it

The publish guard is the orchestrator's own work: “You do this yourself. No subagent. Record each line as ✓ or ✗ in the report.” Three lines. “Serve path — is the page's path re-included in .vercelignore? Read the file and check.” “Reachable — for a page being created, is it linked from docs/index.html, docs/architecture.html, or another page already reachable? If not, ✗ with the reason.” “Links resolve — for every relative href and src in the staged page, does the target file exist? List each broken one.” In the editorial lane, “there is no page, so record all three lines as n/a.”

Promotion is conjunctive — “Promote automatically only if all three hold: mode is create (the page does not already exist), and every verdict is CONFIRMED, and every publish-guard line is ✓.” Otherwise: “Otherwise do not promote. Report what is staged and STOP, telling the human exactly which of the three conditions failed and how to promote it afterwards.” The editorial lane is outside this entirely: “The editorial lane never promotes anything — it has no page. Its report is the deliverable.”

What the output looks like

The staged page differs by lane. The surveyor's must cover “what it does, in one paragraph”, “the flow, as a <pre class="mermaid"> block whose source is editable text, never a pre-rendered SVG”, “a table of every subagent with its exact tools: grant, copied from the agent file”, “the guardrails, each one quoted from the file that enforces it”, and “what the output looks like” — matching a sibling's house style rather than inventing one: “Match the house style; do not invent a new one.” The renderer's is “a complete, self-contained HTML document, styles inline in a <style> block, no external stylesheet, no external script”, taking its design language from docs/index.html.

verdicts.json is strict about shape: “Every id in claims.json appears exactly once, in the same order. verdict is exactly CONFIRMED or UNSUPPORTED; there is no third value.” An empty run is still a run — “An empty claims array is not missing. Process it normally and produce an empty verdicts array.”

report.md carries the lane, the mode, the outcome (“<promoted|staged, not published>”), a verdicts table, a publish-guard table, the open questions (“Anything the generator could not anchor to a quote, verbatim as it reported it”), and what to do next. The last instruction in the command is about honesty in the summary: “Never claim a page is published when it was only staged.”