fix(docs-kit): block unmanaged files in docs/; make the root guides ordinary units

[interacsean]

Follow-up to #396, prompted by @IzumiSy's observation on #559: an agent wrote docs/components/toolbar.md straight into the generated tree and pnpm docs:check said nothing.

The gap

check only walked the things it already knew about — outlines→outputs and manifest→outlines. A file that was neither was invisible rather than rejected. The "never hand-edit docs/" rule was enforced for files the pipeline generates, but nothing enforced that only those files exist.

Reproduced on main: a hand-written docs/components/toolbar.md passes with ✓ no blocking issues.

Removing the last exceptions

Closing this cleanly meant getting rid of the four hand-authored root docs, since a tree check with a four-file allowlist just moves the ambiguity.

They are now ordinary kind: prose units in docs-src/guides/, mapped to dir: "docs" so they still publish at docs/introduction.md, docs/quickstart.md, docs/design-philosophy.md, docs/migrations.md. Published content is unchanged apart from the two-line generated-by banner — frontmatter and body are byte-identical.

One authoring mechanism, no exceptions. And because they're units, their code fences can later become tokenised, type-checked examples (quickstart carries five) — incrementally, since literal fences stay literal, which matters for migrations.md whose snippets are historical and must not compile against current APIs.

The gate

With no exceptions left, check needs no special cases: every .md under an output root must be a unit's output, and anything else blocks:

✖ BLOCK  [docs/components/toolbar.md] docs/components/toolbar.md has no source —
         everything under docs/ is generated. Author an outline under `docs-src/` and run sync.

Two docs-browser bugs this surfaced

• Category derivation — entry.output.split("/")[1] yields "quickstart.md" for a root-level output. Root outputs now group under guides.
• Relative link resolution — links are authored against the generated tree, but routes are a different shape (docs/api/guards/hidden.md is served at /api/guards/hidden). They were resolved against the route, so a guide linking ./concepts/x.md would have reached /guides/concepts/x. They are now resolved in doc-space against the unit's output and then mapped to a route — correct in general, not just for guides.

Verification

• The feat: add generic toolbar #559 repro now blocks; clean tree passes; sync idempotent.
• 20 docs-kit tests pass (5 new, against an extracted pure unmanagedOutputs).
• docs-kit + docs-browser lint, type-check and build clean.
• In the browser: /guides/quickstart renders and its ./concepts/modules-and-resources.md link navigates to /concepts/modules-and-resources.

Docs

CLAUDE.md, CONTRIBUTING, the decision record and the resync-docs skill drop the four-file exception. CLAUDE.md's gate claim was also overstated — it promised docs:check "blocks on any hand edit or drift", which did not cover a newly created file; it now says so accurately.

Agent-instruction hardening (AGENTS.md / .github/copilot-instructions.md, so non-Claude agents see the rule at all) is deliberately not here — tracked separately.

🤖 Generated with Claude Code

[github-actions]

Code Metrics Report

	main (486607c)	#561 (e23e15e)	+/-
Coverage	87.5%	87.5%	0.0%
Test Execution Time	2m8s	1m24s	-44s

Details

  |                     | main (486607c) | #561 (e23e15e) | +/-  |
  |---------------------|----------------|----------------|------|
  | Coverage            |          87.5% |          87.5% | 0.0% |
  |   Files             |            206 |            206 |    0 |
  |   Lines             |           6082 |           6082 |    0 |
  |   Covered           |           5323 |           5323 |    0 |
+ | Test Execution Time |           2m8s |          1m24s | -44s |

---

Reported by octocov