Contributing

Roadmap

The milestone arc from renderer skeleton to beta, the open questions still in play, and what's explicitly out of scope for v1.

Milestones

M0 — Foundations (renderer skeleton)

Single-tenant happy path: read a local docs.json + MDX folder, render the nav tree, pages, core components, and Shiki highlighting. No multi-tenancy yet. Proves the rendering core.

M1 — docs.json parity + components

Full schema parser/validator, recursive navigation, theming from colors, the full v1 component library, dark mode, per-page TOC, and frontmatter.

M2 — Multi-tenancy + Git sync

Middleware host → tenant resolution, subdomains, GitHub App connect, sync workers, compiled-bundle storage, and cache invalidation. Now it’s a SaaS.

M3 — Search

Orama index, the ⌘K command palette, and /api/search. Slice 1 is done: full-text search over page titles + per-heading sections (hits jump to the right #anchor), with prefix/typo tolerance; hidden/noindex pages excluded; built per request (memoized) so it stays fresh in papervine dev. Next: index at sync time per tenant, an “Ask AI” toggle, and recent/suggested terms. See search.

M4 — API Playground

OpenAPI → reference pages, a “Try it” panel, code samples, and auth. Slice 1 is done: a docs.json openapi on a nav division auto-generates in-theme, in-nav endpoint pages (params and schemas via ParamField/ResponseField/Expandable, static cURL). Next: interactive request execution with auth + proxy, per-operation MDX stubs, multi-language code samples (x-codeSamples), and AsyncAPI. See API playground.

M5 — AI Assistant

Agentic retrieval (Claude + tool calling over search_docs / read_page / list_pages / search_api) via the Vercel AI SDK; a slide-out “Ask Assistant” panel with streamed answers + citations; ⌘I, navbar button, and ?assistant= deep link; current-page context; unanswered-question analytics. Embeddings (pgvector) are an optional later upgrade, not a v1 blocker. See AI assistant.

M6 — Dashboard + Domains + Analytics

Org / auth / RBAC, custom domains + TLS, and analytics views. Beta-ready.

Open questions

These are unresolved (or recently resolved and worth recording). Several earlier ones have since been decided — captured here as the rationale.

Compile-on-sync vs. on-request. The design assumes compile-on-sync for performance and predictability. Does that block any dynamic features we care about (e.g. live Twoslash)?

Versioning & i18n. docs.json supports versions + languages in the nav tree. In v1 scope, or fast-follow?

License & governance. MIT vs. Apache-2.0; CLA; and what (if anything) is SaaS-only (open-core) vs. fully open.

Pricing & limits for the hosted version. The current plan is feature-complete by default: auth, RBAC, AI, custom domains, MCP, analytics, preview deployments, and workflows are available from Free onward, with paid plans based on scale. Detailed pricing research and go-to-market planning stay outside the public docs.

Decided — built the web editor now, agent-native. Rather than defer, we shipped the three-panel editor (editing agent · navigation · multi-modal MDX) on a shared authoring backend, alongside the authoring MCP. The editable Visual mode keeps MDX as the source of truth (no lossy block-store round-trip), so Git stays canonical.

Decided — build from scratch (not on Fumadocs). Multi-tenancy and full architectural control outweigh the head start. M0 is a single Next.js app; it refactors into monorepo packages at M2 when multi-tenancy lands.

Decided — code to portable interfaces, not vendors. Better Auth owns its schema in Postgres, and storage is the S3 API (hosted default R2, local MinIO, and S3_ENDPOINT can point anywhere). Domains/TLS use a host-platform wildcard cert plus a SaaS-domains proxy for custom domains; that proxy can be swapped for Caddy on-demand TLS directly.