name: docs description: Write, rewrite or check a page of knotless's docs (docs/, README.md) against the code. Use when a change alters what a doc page says, when asked to write or rewrite a page, or to audit pages for drift. Facts come from the code first; the page is then written from the reader's questions, never by editing old prose.

Writing knotless's docs

Rewriting a page by editing it keeps its shape and its mistakes. These pages are written from facts instead: gather what the code does, decide what the reader asks, and write the page fresh with no old prose in view. Then check it against the facts.

docs/ is a small wiki, one kind of page per directory:

• docs/design/: why it works the way it does. One mechanism per page, each explained as the answer to a problem.
• docs/guide/: how to do one thing, in steps.
• docs/reference/: every flag, method, field and message, to look up.

The map from code to pages is in AGENTS.md, under Docs.

Which job

• A small change to what a page says (a new flag, a changed limit): edit the page and the reference that lists it, in the pull that makes the change. Check the edit against the code it describes. Steps 1 and 4 below are enough.
• A page to write or rewrite: all four steps.
• An audit (are these pages still true?): steps 1 and 4 for each page, then fix what is wrong, or file an issue when the code is what's wrong. The docs-audit workflow does steps 1 and 4 on the runner when the owner asks (knotless run rerun <repo> --ref refs/heads/main --workflow docs-audit), one session per page, and reports at the end of its log; it costs model usage, so ask first. Verify each finding against the code before acting on it.

1. Facts

Have an agent read the code the page covers, and the page as it stands, and write a fact inventory to a scratch file. Each fact is one line, tagged:

• [code] read in the code (name the file and function)
• [doc] said by a page, not found in the code
• [both]
• [DOC WRONG] a page says something the code contradicts: give both

A section headed Quirks lists what looks like a bug, with file and line. Those are filed as issues (knotless issue create), not written up as design. Drop [doc] facts the code does not bear out.

2. Context

Write a short context file for the writer:

• The reader: who they are, what they already know (git, CI, roughly what atproto is), and why they came to this page.
• knotless in three lines (see context.md beside this file).
• A glossary of only the atproto and knotless terms the facts use.
• The pages it may link to, by path.
• The questions the page answers, in the order a reader asks them. The lists for the design pages are in questions.md beside this file; start from those and add what the facts raise.

3. Write

Give a fresh agent only the facts and the context, and tell it not to read docs/, README.md or AGENTS.md. It may read code to settle a doubt, and says so. The brief, with the style rules, is writer.md beside this file.

It reports the facts it left off and where each belongs. Place those in the reference pages and guides yourself (or with another agent), checking each against the code as you go: details belong there, not on a design page.

4. Check

• Every fact on the page against the inventory, and any doubt against the code. Agents drop true facts no source stated, and keep false ones a page did: read the diff of what was there before.
• Pages that state the same thing agree. security.md and the overview draw on the others, so check them last.
• just docs: links, anchors, and every Mermaid block draws with Pele (npm ci in web/ first). The docs check runs it on the pull.
• Read the page once as its reader would, top to bottom.