docs-builder

docs-builder

Keep project docs current, complete and findable, and split a file when it outgrows its row in docs/index.md. Why it works this way, measured numbers and history: docs/product/docs-builder-README.md.

This does NOT make docs cheaper to read — never sell it as a token saving. Every mechanical step is the docs-builder.cjs script beside this file, the $DB path below (vanilla Node, zero deps). A model does two things only: classify and propose themes, and write pages.

• Heavy model work always spawns a worker, tier stated explicitly (an omitted tier inherits the parent's). Never name a vendor model. Hand the worker its inputs — it has no skill text of its own — and it does the work itself, no sub-spawning. Anything that asks the user stays in the main session. Fall back to inline only if your tool cannot spawn.

Setup

docs-builder.cjs sits next to this file in docs-builder/, installed or run from the package. Never search the target repo for it, never reconstruct it from this spec; if it exists nowhere, say so and stop. Set DB to its ABSOLUTE path, then cd to the target repo root:

DB=<absolute path to docs-builder.cjs>
cd <target repo root>

Every command below is node $DB …. Everything the script writes (docs/.docs-builder/* state, docs/index.md, docs/log.md, the ledger, the config pointer) lands under the target repo; REPO= is only needed when not running from its root.

Hard rules

• Only .md files are ever opened, read, edited or listed — a non-.md file is never touched, not even to report a mention.
• Never moved, enforced in code: README.md, index.md, log.md, CHANGELOG.md, LICENSE.md, CONTRIBUTING.md, CODE_OF_CONDUCT.md, SECURITY.md, CLAUDE.md, AGENTS.md, AGENT.md (case-insensitive, any depth), every dot-dir, node_modules/.
• Nothing moves before the user approves the table. Only after approval does apply-reorg run; it refuses while any row's bucket is empty.
• Never split N files in one shot on a list the user has not seen.
• reorg never splits. cleanup <file.md> is the ONLY entry to the split pipeline: exactly one .md file, refuses a missing or protected one.
• cleanup-apply refuses without a labels.json that has exactly one core: true theme.
• The original is always archived byte-identical (git mv into docs/archive/); every cleanup output is a new file, nothing edits a source doc.
• docs/index.md has exactly one writer: index-flat — never hand-edit it.
• Never rewrite CHANGELOG.md or log.md links (any depth). Nothing under docs/archive/ is ever a rewrite target; links elsewhere that point at an archived file are still repaired.
• Commit only through the printed pathspec recipe; never git add -A, git add -u or git commit -a.