Docs Maintenance
How to add, structure, verify, and release Kunai documentation.
The docs website lives in apps/docs and uses Next.js, Fumadocs, MDX, and Tailwind CSS. User and developer content lives in the repository-level docs/ folder so it can serve both the website and source readers.
Docs build is separate from CLI release
The CLI release path builds @kitsunekode/kunai without requiring the docs website. Docs CI/build is its own task — keep it that way.
Adding a page
Author content
Add an .md or .mdx file under docs/users/ or docs/developer/ with title and description frontmatter.
Register navigation
Add the slug to the nearest meta.json. Section hubs use index.mdx as the first page in each folder.
Prefer truthful MDX primitives
Use Callout, Steps, Tabs, and Card for procedural content. Reserve codegen components (ProviderTable, CliFlagsTable) for reference pages.
Verify
bun run --cwd apps/docs generate
bun run --cwd apps/docs typecheck
bun run --cwd apps/docs test
bun run --cwd apps/docs buildgenerate must run before typecheck and build when invoking scripts directly. Turborepo runs it once via apps/docs/turbo.json task dependencies.
Content rules
- Document user-visible behavior before internal implementation details.
- State when a feature is local-only, cached-only, opt-in, or live-provider backed.
- Keep provider traffic and Discord live checks manual unless a test is explicitly named as live smoke.
- Prefer reusable command examples over prose-only explanations.
- Keep security boundaries visible: no stream URLs in support bundles, no provider probing during docs rendering, no autoplay from imported playlists.
Codegen and drift tests
apps/docs/scripts/sync-code-metadata.ts writes lib/generated-metadata.json from the CLI registry. Drift tests in apps/docs/test/drift.test.ts and apps/docs/test/seo.test.ts guard provider order, command counts, link hygiene, SEO uniqueness, and fingerprint parity.
Run bun run --cwd apps/docs generate after changing commands, providers, help text, or docs/feature-status.yaml.
Truth layers (L0–L4)
| Layer | Source | Guard |
|---|---|---|
| L0 Codegen | bootstrap-providers.ts, manifests, command registry, cli-args | generate, check-codegen-freshness.ts, fingerprint drift tests |
| L1 Editorial | docs/feature-status.yaml | enum tests, <FeatureStatusTable /> |
| L2 Prose | docs/users/*.mdx | link hygiene, promotion manifest, no hardcoded provider lists |
| L3 Agent | .docs/*, .plans/* | never link from published docs; promote via docs/promotion-manifest.yaml |
| L4 Release | CHANGELOG, .release/ | release-checklist.mdx, release:notes:check |
Rule: Code wins for behavior. YAML wins for product posture. Prose explains — it does not duplicate L0 tables.
Freshness gate
bun run --cwd apps/docs scripts/check-codegen-freshness.tsCI runs generate once, then typecheck:app, test, and build:app (skipping redundant MDX/codegen passes). The freshness gate compares fingerprints and registry payloads, not volatile syncedAt / cliSourceRevision stamps.
Troubleshooting emits FAQPage JSON-LD from docs/troubleshooting-symptoms.yaml and the matching MDX sections.
Local Lighthouse (optional)
bun run --cwd apps/docs lighthouse:docsNot gated in CI. Set DOCS_SITE_URL to production when auditing canonical URLs before deploy.
Hub pages
| Route | File | Purpose |
|---|---|---|
/docs | docs/index.mdx | Documentation home with section cards |
/docs/users | docs/users/index.mdx | User guide library overview |
/docs/developer | docs/developer/index.mdx | Contributor entry |
Shared card data lives in apps/docs/lib/doc-hub.ts. MDX components: DocsRootCards, DocSectionCards, ScopeCallout, QuickStartSteps.
Build boundaries
Root scripts should delegate through Turborepo filters instead of hiding package logic in root commands. The docs app must not become a hard dependency of packaging the CLI binary.
Last updated on