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

.agents/skills/resync-docs/SKILL.md

@@ -53,6 +53,7 @@ For each drifting unit:
 
 ## Rules
 
+- The root guides (`introduction`, `quickstart`, `design-philosophy`, `migrations`) are ordinary prose units in `docs-src/guides/` that output to the `docs/` root — edit the outline, not the generated file.
 - Never edit files under `docs/` by hand — only `*.docs.outline.md` and `*.docs.examples.tsx`. docs-browser derives its routes from `docs-manifest.json` (declarative `modules` in `App.tsx`); there are no generated route stubs.
 - One example export per token; keep them runnable (they are type-checked in CI).
 - Regenerate only what changed; a clean tree must produce a zero-diff `sync`.

CLAUDE.md

@@ -17,8 +17,8 @@ Tailor Platform AppShell - A React-based framework for building ERP applications
 ## Documentation
 
 Everything under [`docs/`](./docs/) is **generated** by the `docs-kit` pipeline and must **never be
-hand-edited** — the pre-commit hook warns and `pnpm docs:check` in CI blocks on any hand edit or
-drift. See [decisions/documentation-management-overhaul.md](./decisions/documentation-management-overhaul.md)
+hand-edited** — the pre-commit hook warns and `pnpm docs:check` in CI blocks on any hand edit,
+drift, or file created under `docs/` with no source. See [decisions/documentation-management-overhaul.md](./decisions/documentation-management-overhaul.md)
 and the [`resync-docs`](./.agents/skills/resync-docs/SKILL.md) skill.
 
 To change or add a doc, edit the authored **source** under `docs-src/`, then run `pnpm docs:sync`:
@@ -34,9 +34,10 @@ units also declare a `sources:` glob binding them to the exports they document,
 reconciles that against `index.ts` both ways. Frontmatter is a closed schema: an unrecognised key is
 an error, not a silent no-op.
 
-The only hand-authored files under `docs/` are the four root guides — `introduction.md`,
-`quickstart.md`, `design-philosophy.md`, `migrations.md` — which have no `docs-src/` source and are
-edited in place (`migrations.md` is also copied into the generated skill).
+There are **no exceptions**: every file under `docs/` comes from an outline. The root guides
+(`introduction`, `quickstart`, `design-philosophy`, `migrations`) are `kind: prose` units in
+`docs-src/guides/` that happen to output to the `docs/` root. Creating a file under `docs/` that no
+outline produces is a blocking `docs:check` failure.
 
 ## Key Architecture Points (LLM Orientation)
 

CONTRIBUTING.md

@@ -63,18 +63,18 @@ repo publishes via changesets (§6) — you won't run `changeset:publish` by han
 
 ### Repository layout
 
-| Path                   | What it is                                                                        |
-| ---------------------- | --------------------------------------------------------------------------------- |
-| `packages/core`        | `@tailor-platform/app-shell` — the published library (components, hooks, layouts) |
-| `packages/vite-plugin` | `@tailor-platform/vite-plugin-app-shell` — file-based routing                     |
-| `packages/sdk-plugin`  | `@tailor-platform/sdk-plugin-app-shell` — Tailor SDK plugin                       |
-| `examples/`            | `vite-app` reference app and consolidated showcase (what `pnpm dev` runs)         |
-| `e2e/`                 | Playwright suite + a real Tailor backend definition                               |
-| `docs-src/`            | Authored doc sources — outlines + runnable examples (the only hand-edited docs)   |
-| `docs/`                | **Generated** user-facing documentation — never hand-edited (`pnpm docs:sync`)    |
-| `docs-browser/`        | AppShell app that renders `docs/` with live examples                              |
-| `.agents/skills/`      | **Contributor procedures** — the source of truth for how to do the work           |
-| `.github/`             | Agents, prompts, and workflows (CI + agentic bots)                                |
+| Path                   | What it is                                                                                        |
+| ---------------------- | ------------------------------------------------------------------------------------------------- |
+| `packages/core`        | `@tailor-platform/app-shell` — the published library (components, hooks, layouts)                 |
+| `packages/vite-plugin` | `@tailor-platform/vite-plugin-app-shell` — file-based routing                                     |
+| `packages/sdk-plugin`  | `@tailor-platform/sdk-plugin-app-shell` — Tailor SDK plugin                                       |
+| `examples/`            | `vite-app` reference app and consolidated showcase (what `pnpm dev` runs)                         |
+| `e2e/`                 | Playwright suite + a real Tailor backend definition                                               |
+| `docs-src/`            | Authored doc sources — outlines (incl. `guides/`) + runnable examples (the only hand-edited docs) |
+| `docs/`                | **Generated** user-facing documentation — never hand-edited (`pnpm docs:sync`)                    |
+| `docs-browser/`        | AppShell app that renders `docs/` with live examples                                              |
+| `.agents/skills/`      | **Contributor procedures** — the source of truth for how to do the work                           |
+| `.github/`             | Agents, prompts, and workflows (CI + agentic bots)                                                |
 
 ---