Handbook maintenance (native `/docs`)

The handbook is native SvelteKit: MDX files under docs/ are the single source of truth, rendered at `/docs/** by routes in **src/routes/docs/**. There is no Mintlify export, no edge middleware for handbook paths, and no separate static **static/docs/`** tree.

Architecture (PostHog-inspired)

Layer	Role
`docs//*.mdx`**	Content source of truth (frontmatter + Mint-style components)
docs/docs.json	Navigation, branding metadata, footer links
src/lib/docs/components/	Shared Svelte components (Card, Steps, Note, …) — same names as Mint MDX tags
vite/handbook-mdx-scope.ts	Auto-imports components into every handbook MDX file
src/routes/docs/	Prerendered SvelteKit routes (+layout, [...slug])
scripts/check-handbook.mjs	Validates nav slugs ↔ on-disk MDX

Content can later be embedded elsewhere (in-app help, agent context) by importing the same MDX modules or summaries from src/lib/server/docs.ts.

When you must update (triggers)

Change	Action
New handbook page	Add docs/.../*.mdx, add slug to docs/docs.json → navigation, run pnpm docs:check
Rename/remove page	Update MDX path, docs.json, and internal links in other MDX files
New MDX component tag	Add Svelte component under src/lib/docs/components/, export from index.ts, add to vite/handbook-mdx-scope.ts imports
Copy-only edits inside existing MDX	No nav changes
Appearance/footer/search strings in docs.json only	No route changes

Verification checklist

pnpm docs:check
pnpm check
pnpm lint
pnpm build
pnpm preview

Spot-check in the browser:

• /docs and /docs/quickstart
• At least one nested page per tab (e.g. /docs/configuration/environment-variables)
• Client navigation between handbook pages (sidebar links)

Lofting upstream only

When navigation structure or the native docs contract changes, append a block to .lofting/for-agents.md.

Downstream brand repos

When porting Lofting handbook changes:

1. Reconcile docs/ MDX and docs.json for your brand.
2. Port src/routes/docs/, src/lib/docs/, src/lib/server/docs*.ts, and vite/handbook-mdx-scope.ts when they appear in the Lofting diff — not MDX-only.
3. Run the verification commands above before advancing last_emulated_lofting_commit.

Related

• Quick start — local dev includes /docs on the same origin
• Deploy to Vercel — pnpm build prerender handbook routes
• docs/README.md — authoring conventions