docs: sync 2026-08-29

[JulienMartel]

Docs sweep — reconciled 9 commits here, and carries the findings for four repos whose docs needed nothing.

scruff got a tree on hausfold.co yesterday (hausfold.co #183) and cut its README down to a door (scruff #92), deleting docs/lifecycle.md and docs/reference.md. Two places here still say the opposite, and one of them is the routing table the next sweep reads.

Corrected

• AGENTS.md ▸ Where a write-up goes — was: "haus, pounce and perch each have one" tree, and "scruff, snug and nebelung have no tree at all, so their README is the front page … never cut one of those down to a door." Both halves are now wrong about scruff, and the second is an instruction to undo what scruff notes: Phase 3 mostly done — light mode, keys.*, and the readiness test passing #92 did. scruff joins the first group; the second is snug and nebelung. Also names the two things that legitimately stayed in scruff's repo, since the first group's rule is "what a contributor needs": docs/releasing.md, and SPEC.md, which sits at the root rather than in docs/.
• .agents/skills/docs-sync/SKILL.md ▸ Step 2 — the scruff/ row said "scruff has no site tree, so 'the docs' for it are the repo's", which would send every future sweep to the wrong surface. It now routes to the tree and names what stays behind, plus the three-file rule scruff's own AGENTS.md states (a verb, flag, exit code or --json key moves the code, ai/SKILL.md and the page together). The org-profile row's "only the four trees" is five.

Left alone (deliberately)

• bench status nesting a spawned lane under its parent (status: nest a spawned lane under the lane that spawned it #494) landed with its own docs/workflows.md edit in the same commit. Nothing to add.
• The factory / night shift (factory: level 0 — the night shift merges tier-1 PRs under a lease #491) shipped docs/factory.md, the /nightshift skill and its README and AGENTS.md rows in one go. Reconciled by construction.
• org-profile had no commits in range, so its README was not re-audited — but one thing is worth naming rather than fixing: it lists seven repos and snug is not one of them. Its own AGENTS.md says the README is "one line per repo, in the family's order (house → apps → theme → substrate → bench)", and snug is a public family repo that this repo's README already carries. Not written, because nothing in the range put it there and I can't tell from the history whether the omission is a decision. Would change on a word either way.
• The holt spellings that survive (scruff's SPEC.md, sdk docs, .github/copilot-instructions.md, haus/AGENTS.md's two-release migration note, /release's SKILL.md) are all provenance for immutable published artifacts — Go proxy paths and PyPI names that resolve forever at the tags published under them — or the named pattern for the next prefix move. Kept, per the "names a shape rather than narrating a file's past" carve-out.

Needs code, not docs

• haus: a haus user cannot reach pounce's stage or ranking settings. modules/launcher/default.nix:1470 writes ~/.config/pounce/config.json from a fixed key list with neither block in it and no passthrough; pounce config init refuses inside haus and the Settings window opens read-only. pounce docs: wt park / wt unpark — the stash-free way to set work aside #123/docs: swap layouts are Alt [ / Alt ], and now work locked #124 added four ranking.* switches, all defaulting on, all of which change what ⌘Space shows before you type — and hausfold.co#187 now documents them for a machine that has no way to set them. Wants haus.launcher.* options, or one escape hatch, in haus.
• hausfold.co: content/docs/haus/rooms/ai.mdx holds 40 em dashes against that repo's own "no em dashes in reader-facing copy, anywhere" rule. hausfold.co#187 leaves them (its own added lines carry none) because a 40-instance sweep of one page is its own change, and the same repo's "sweep a spelling everywhere at once, or not at all" says not to do it per-page.

Where the rest of the range went

• hausfold.co — #187: the background-lane behaviour reverted under the site's description of it, and pounce's whole new ranking surface.
• pounce, perch, trill, nebelung, snug — nothing. Each landed its own docs in the same commits as the code (README doors, assets/README.md, docs/rules.md, snug's README/AGENTS.md for the SIGINT contract), and the site absorbed the rest.
• homebrew-tap — one CI-written version stamp. No doc consequence by design.
• ops could not be cloned (private; the container has no credentials for it), so its half of the sweep did not run. Its watermark is untouched, so the next run with credentials picks the range up whole.

---

Generated by Claude Code