Bring the remaining docs in line with docs/WRITING.md
The first screens are done: README.md, docs/README.md, and the openings of STUDIO, APPS, ORIGINS, CREW, ARCHITECTURE, OPERATING, DEVELOP and TOUR. The bodies and all other documents are not.
How to work
One small pull per document, in the order below. A document over 3,000 words may take one pull per section.
Follow docs/WRITING.md. Check each claim against the code or a test. Fix or cut what you cannot confirm.
Move technical substance; do not delete it. Keep headings stable where other documents link to them, or update those links.
Change no code behavior. A doc that disagrees with the code gets corrected. If the code looks wrong, file an issue.
Order
docs/STATUS.md, docs/SECURITY-RUNBOOK.md, docs/THREATS.md: what readers trust most.
docs/STUDIO.md: remove the "dev mode" and ?mode=dev sections' stale framing. Modes are gone.
docs/APPS.md, docs/CREW.md, docs/ORIGINS.md: the core concepts, one section per pull.
docs/RECOVERY.md, docs/RESTORE.md, docs/SNAPSHOT.md, docs/DOMAINS.md. Keep what test/recovery-doc.test.ts requires.
docs/REFERENCE.md: split it by topic into the documents above. It stays the list of every document.
docs/features/*.md: a batch of about 10 per pull.
All other top-level documents. Design records and research may be marked as records instead of rewritten.
Do not rewrite documents the owner is reviewing for removal or privacy. Ask on this issue first.
Done when
Each pull:
The document opens with what it covers, who it is for and the key idea, in under 120 words.
It adds no em dashes: git diff -U0 docs/<file> | grep '^+' | grep -c '—' prints 0.
Its opening and prose for newcomers contain no issue numbers: sed -n 1,12p docs/<file> | grep -c '#[0-9]' prints 0.
It has no references to removed README sections: grep -n "README's" docs/<file> prints nothing.
Each file, route, flag and test it names exists at the pull's commit.
bun test test/readme-front-door.test.ts test/readme-cap.test.ts test/dependencies-named.test.ts test/design-lint.test.ts passes, with any test that reads the document.
The whole issue: grep -rlE 'magic|boring|at 3 a\.m\.' docs/*.md prints nothing, and each listed document has landed.
Bring the remaining docs in line with docs/WRITING.md
The first screens are done:
README.md,docs/README.md, and the openings of STUDIO, APPS, ORIGINS, CREW, ARCHITECTURE, OPERATING, DEVELOP and TOUR. The bodies and all other documents are not.How to work
docs/WRITING.md. Check each claim against the code or a test. Fix or cut what you cannot confirm.Order
docs/STATUS.md,docs/SECURITY-RUNBOOK.md,docs/THREATS.md: what readers trust most.docs/STUDIO.md: remove the "dev mode" and?mode=devsections' stale framing. Modes are gone.docs/APPS.md,docs/CREW.md,docs/ORIGINS.md: the core concepts, one section per pull.docs/ARCHITECTURE.md,docs/OPERATING.md,docs/DEVELOP.md,docs/TOUR.md.docs/MCP.md,docs/CLI.md,docs/GIT.md,docs/ON-YOUR-MACHINE.md,docs/METRICS.md.docs/RECOVERY.md,docs/RESTORE.md,docs/SNAPSHOT.md,docs/DOMAINS.md. Keep whattest/recovery-doc.test.tsrequires.docs/REFERENCE.md: split it by topic into the documents above. It stays the list of every document.docs/features/*.md: a batch of about 10 per pull.Do not rewrite documents the owner is reviewing for removal or privacy. Ask on this issue first.
Done when
Each pull:
git diff -U0 docs/<file> | grep '^+' | grep -c '—'prints 0.sed -n 1,12p docs/<file> | grep -c '#[0-9]'prints 0.grep -n "README's" docs/<file>prints nothing.bun test test/readme-front-door.test.ts test/readme-cap.test.ts test/dependencies-named.test.ts test/design-lint.test.tspasses, with any test that reads the document.The whole issue:
grep -rlE 'magic|boring|at 3 a\.m\.' docs/*.mdprints nothing, and each listed document has landed.