feat(docs): docs-management pipeline POC (docs-kit + outlines + AppShell renderer)

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

@@ -0,0 +1,64 @@
+---
+name: resync-docs
+description: Regenerate component/pattern documentation when docs-kit reports drift. Use when `docs-kit check` (or CI) fails with interface-drift, outline-changed, or missing-output findings, or when the user asks to "resync docs", "update the docs for X", or "/resync-docs". This is the ONLY sanctioned way to change generated docs — never hand-edit files under docs/.
+---
+
+# Resync docs
+
+The docs pipeline is one-way: **outlines + source → generated docs**. Humans (and this skill) edit only two things — the `*.docs-outline.md` (intent) and the `*.examples.tsx` (runnable examples). Everything under `docs/` is generated by `docs-kit` and must never be hand-edited. See [decisions/documentation-management-overhaul.md](../../../decisions/documentation-management-overhaul.md).
+
+## When to run
+
+- `docs-kit check` fails (locally or in CI) with a blocking finding.
+- A component's interface changed and its docs need to catch up.
+- The user asks to add or revise a documented example.
+
+## Inputs
+
+An optional list of unit slugs. If omitted, run `docs-kit check` first and act on every blocking unit it names.
+
+## Procedure
+
+For each drifting unit:
+
+1. **Identify what changed.** Run the gate and read the finding:
+
+   ```bash
+   node packages/docs-kit/dist/cli.mjs check --root .
+   ```
+
+   - `interface (type surface) drifted` → the exported API changed. Re-read the unit's `sources` and update the outline prose + `examples.tsx` so they still match. Check whether any example now uses a removed/renamed prop.
+   - `outline edited` → expected after you edit the outline; just resync.
+   - `… was hand-edited or is stale` → someone edited a generated file directly. Do **not** keep that edit; move the intent into the outline/examples, then regenerate.
+
+2. **Edit intent only** — the two authorable surfaces:
+   - `*.docs-outline.md` (colocated with the component, or under `docs-src/` for concepts/patterns/references): prose is copied verbatim; example segments are keyed English tokens `<!-- example: kebab-key | instruction -->`.
+   - `*.examples.tsx` (under `docs/<category>/`): one exported component per token, named in PascalCase matching the token (`basic-usage` → `BasicUsage`). Keep every example **compiling against `@tailor-platform/app-shell`** and minimal. When iterating, treat the current file as the baseline and change only what the interface change forces — do not rewrite untouched examples.
+
+3. **Regenerate deterministically** (no hand-editing of `.md`):
+
+   ```bash
+   node packages/docs-kit/dist/cli.mjs sync --root .
+   ```
+
+   This rewrites the `.md`, extracts fences from `examples.tsx`, refreshes the API section, and updates `docs/docs-manifest.json` hashes.
+
+4. **Verify green:**
+
+   ```bash
+   node packages/docs-kit/dist/cli.mjs check --root .   # expect exit 0
+   ```
+
+5. **Review the diff.** Confirm prose reads well, examples are idiomatic, and the manifest changes are limited to the units you touched.
+
+## Rules
+
+- Never edit files under `docs/` by hand — only outlines and `examples.tsx`.
+- 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`.
+- Also refresh the generated `app-shell-patterns` consumer skill when component interfaces change (future: `docs-kit sync` will emit it).
+
+## Related
+
+- `packages/docs-kit` — the extractor / gate / assembler.
+- `docs.config.json` — roots, categories, coverage enforcement, exclusions.