feat(docs): docs-management pipeline

[interacsean]

What this does

Replaces hand-maintained docs with a one-way source → generated output pipeline, and ships a consumer skill and a browsable docs site generated from the same sources. Resolves tailor-inc/platform-planning#1549.

Before: ~90 docs under docs/ were edited by hand, with no link between a component's source and its doc and no drift detection. A bot (docs-update.lock.yml) patched drift post-merge, heuristically.

After: authored intent lives in docs-src/; everything under docs/ (bar four root guides) is generated and gated in CI.

New packages / trees

• packages/docs-kit/ — the pipeline (private, unpublished, no version): a ts-morph type-surface extractor/hasher, coverage reconciler, markdown assembler, consumer-skill emitter, and a no-LLM check / sync CLI. Exposed as the docs-kit workspace bin; the root docs:sync / docs:check scripts build it via Turbo (cached) and invoke the bin. See its README.
• docs-src/ — the only hand-editable surface: *.docs.outline.md (prose + sources/frontmatter) and sibling *.docs.examples.tsx (runnable examples), by category (components, hooks, concepts, patterns, pages, skill).
• docs-browser/ — an AppShell app that renders the generated docs with live in-place examples. Routing is declarative: App.tsx derives the defineModule() / defineResource() tree from the manifest at runtime (nesting /-slugs such as guards/hidden under a grouping resource), so a new unit needs zero wiring and docs-kit emits no browser route stubs. This gives the declarative routing API a real application consumer; file-based routing stays exercised by examples/vite-app.

Repo-root files

• docs-kit.config.json — docs-kit's only config, grouped by data flow: inputs (outline roots, API tsconfig/entrypoint, snapshots) → outputs (document mappings, manifest path, skill) → policy (coverage enforcement + exclusions). There is no browser-route output: docs-kit produces documentation artifacts, docs-browser consumes them.
• docs-manifest.json — the pipeline's integrity baseline (per-unit outline/output/sources paths and hashes). It lives at the root, alongside the config, because it spans docs-src/, packages/core/, docs/, and the skill rather than being a document itself.

Pipeline behaviour

• Closed outline schema — frontmatter is validated up front; every unit declares kind: code-backed | prose (never inferred). sources is required on code-backed, forbidden on prose.
• Coverage reconciler — reconciles index.ts exports both ways: forward (uncovered export → advisory while policy.coverage.enforce is false), reverse (a unit owning zero exports, or documenting a non-exported symbol → always block). This is the check that catches the class of bug the un-exported Timeline once was.
• Opt-in API tables — an <!-- api --> token renders auto prop tables (Prop / Type / Default / Description) from the type surface; defaults come from cva defaultVariants, destructuring, and @default. Declared type annotations are preferred over resolved types.
• Deterministic gate — docs:sync regenerates .md + manifest hashes (byte-idempotent); docs:check blocks on interface drift, outline drift, hand-edited generated files, orphaned outputs, and skill drift.

Migrated content

42 components, 25 hooks/functions, 9 UX patterns, 1 page pattern (document-detail), and 8 concepts — prose retained verbatim.

Consumer skill (app-shell-patterns)

Now generated by docs-kit sync (was the catalogue package, retired) into the git-ignored packages/core/skills/, shipped via core's files: ["skills/**"]. It bundles the generated concepts, components, hooks, patterns, and pages plus migrations.md; changeset:publish runs docs:sync so it lands in the tarball.

• The erp-kit "fundamentals" became first-class concepts: design-system.md merged into the styling-theming concept, graphql and custom-components are new concepts, and components.md was retired (superseded by the per-component docs).

CI / enforcement

• pnpm docs:check runs in CI (uncached) as the blocking drift gate; pre-commit runs it in warn mode.
• The post-merge docs-update bot is deleted.
• Migrated docs preserve git log --follow lineage (git mv).

Docs

decisions/documentation-management-overhaul.md records the design; CLAUDE.md and the resync-docs skill point authors at docs-src/ (never hand-edit docs/).

Revisions since review

Per @IzumiSy's review:

• docs-browser switched to declarative, manifest-derived routing; pages.ts, pagesDir, and the generated page.tsx stubs are removed.
• docs-manifest.json moved to the repo root.
• Config renamed docs.config.json → docs-kit.config.json and restructured as inputs / outputs / policy.
• docs-kit gained a README and dropped version; the root scripts invoke the docs-kit workspace bin instead of packages/docs-kit/dist, and --root . is gone.
• Stale route-stub / file-based-routing comments and the unused appShellPageProps on the docs-browser home page were cleaned up.

🤖 Generated with Claude Code

[interacsean]

/review

[github-actions]

✅ API Design Review completed successfully!

API Design Review complete — no files matching packages//*.ts, packages//*.tsx, or packages/**/package.json were changed in this PR. The PR adds docs infrastructure (docs-kit concept, .agents/skills, docs-browser, decisions/) but makes no changes to the core packages/ library. No API design issues to report.

[IzumiSy]

If my rememberance is correct, we can omit even version from here because this package is private.

And can you add small README in docs-kit for better introduction to internal devs like us?

[interacsean]

Addressed in update

[IzumiSy]

Great work overall — this is a thoughtful and substantial documentation overhaul.

I think there is an opportunity to simplify the docs pipeline and clarify its boundaries.

1. Prefer declarative routing for docs-browser

The generated page.tsx files differ only by document slug and title. Since the browser already consumes the manifest, it should be able to derive a defineModule() / defineResource() tree directly from the manifest entries and render each resource as <DocPage slug={...} />.

File-based routing is already exercised by examples/vite-app, while this would give the declarative API a real application consumer as well. It would also let us remove the docs-browser-specific generation from docs-kit:

• packages/docs-kit/src/pages.ts
• pagesDir configuration
• generated docs-browser/src/pages/**/page.tsx stubs

The only additional handling needed is building a nested resource tree for slugs such as api/guards/hidden.

2. Move docs-manifest.json to the repository root

The manifest is not generated documentation content. It is pipeline metadata and an integrity baseline spanning the repository:

• authored inputs under docs-src/
• public type sources under packages/core/
• generated Markdown under docs/
• generated consumer skill files

Its outline, output, and sources fields are all repository-relative paths, so placing it at the root better reflects its role. It is closer to a committed build/integrity manifest than to a document. docs-manifest.json alongside docs-kit.config.json would make that distinction clearer.

3. Rename and structure the docs-kit configuration

docs.config.json is currently only consumed by docs-kit, so docs-kit.config.json would be more precise. The current flat structure also mixes inputs, outputs, and validation policy.

A structure along these lines would make the data flow explicit:

{
  "inputs": {
    "outlines": { "roots": ["docs-src"] },
    "api": {
      "tsconfig": "packages/core/tsconfig.json",
      "entrypoint": "packages/core/src/index.ts"
    },
    "snapshots": { "dir": "packages/core/__snapshots__" }
  },
  "outputs": {
    "documents": {
      "mappings": [
        { "match": "docs-src/components/**", "dir": "docs/components" }
      ]
    },
    "manifest": "docs-manifest.json",
    "skill": {}
  },
  "policy": {
    "coverage": {
      "enforce": false,
      "exclusions": []
    }
  }
}

If we adopt declarative routing, there should be no docs-browser route output in this config: docs-kit generates documentation artifacts, while docs-browser consumes the manifest and renders them.

[IzumiSy]

Minor suggestion: since docs-kit already declares a docs-kit binary, could we expose it as a root workspace dev dependency and invoke that binary instead of reaching into packages/docs-kit/dist directly?

The current commands already run from the repository root, so the explicit --root . is redundant. This would make the docs-kit build prerequisite explicit while keeping the CLI invocation rooted at the workspace.

{
  "devDependencies": {
    "@tailor-platform/app-shell-docs-kit": "workspace:*"
  },
  "scripts": {
    "docs:check": "turbo run build --filter=@tailor-platform/app-shell-docs-kit && docs-kit check",
    "docs:sync": "turbo run build --filter=@tailor-platform/app-shell-docs-kit && docs-kit sync"
  }
}

The targeted build remains Turbo-cached, while check and sync still run against the actual working tree every time.

[interacsean]

Addressed in update

[interacsean]

All feedback has been addressed now @IzumiSy