Skip to main content

Docs Web Decision Register

This register freezes the v0 decisions for the Maya online documentation website.

The non-drifting split is:

.docs owns canonical project, package, architecture, verification, release, and security content.
.docs/ops owns Cloudflare Pages and Storybook deployment runbooks.
apps/docs owns the Docusaurus website shell, navigation, visual presentation, static assets, headers, and generated view.
Storybook owns executable component examples and deploys separately.
API reference generation is planned but not implemented in docs web v0.

Reopening a locked decision requires one of these triggers:

  • a Docusaurus implementation blocker that cannot be solved through normal Docusaurus configuration
  • a Cloudflare Pages deployment blocker for a static site
  • a source-of-truth conflict that would create stale committed documentation
  • a security or secret-handling issue in the deployment model
  • an accepted product requirement that cannot be represented by static docs plus external Storybook links

Locked Decisions​

DOCS-ADR-001: Docusaurus App Boundary​

Decision: the online documentation site lives in apps/docs and uses Docusaurus, MDX, React, and TypeScript.

Why locked: this gives Maya a static documentation platform with MDX authoring, React extension points, and straightforward Cloudflare Pages output.

Forbidden drift: do not turn v0 into a custom Next.js site, a bespoke Vite docs shell, a CMS-backed runtime, or package-local documentation renderers.

Reopen only if: Docusaurus blocks a required v0 documentation behavior that cannot be solved with configuration, a local plugin, or scoped React components.

DOCS-ADR-002: Docs Production Domain​

Decision: the Docusaurus static site deploys to Cloudflare Pages at docs.mayadev.cloud.

Why locked: the deployment target matches the desired hosting stack and keeps the v0 site static.

Forbidden drift: do not add a backend runtime, server-rendering requirement, alternate production host, or account-specific deployment state in v0.

Reopen only if: Cloudflare Pages cannot support the required build, routing, headers, domain, or preview deployment behavior.

DOCS-ADR-003: Storybook Standalone Domain​

Decision: Storybook deploys separately at storybook.mayadev.cloud.

Why locked: Storybook is executable component documentation and should not be bundled into the Docusaurus artifact.

Forbidden drift: do not iframe Storybook into Docusaurus, publish it inside the docs build output, or duplicate Storybook story content as hand-written Docusaurus pages.

Reopen only if: a future unified portal decision preserves separate build artifacts and failure domains.

DOCS-ADR-004: API Reference Runway​

Decision: v0 reserves API reference routes and generator contracts but does not implement TypeDoc or a custom declaration parser.

Why locked: API documentation should be generated from package exports or declaration output only after package surfaces are stable enough to publish.

Forbidden drift: do not hand-write disposable API reference pages, install a generator as a side quest, or claim generated API docs exist before the generator is implemented.

Reopen only if: package export stability and generator input/output contracts are accepted in a dedicated follow-up.

DOCS-ADR-005: Static Site V0​

Decision: docs web v0 is a static Docusaurus build.

Why locked: static output keeps preview deployments, caching, local verification, and Cloudflare Pages operation simple.

Forbidden drift: no auth wall, server-side docs service, dynamic CMS, search backend, or runtime personalization in v0.

Reopen only if: the public docs launch requires behavior that static Docusaurus cannot reasonably provide.

DOCS-ADR-006: Explicit Source Of Truth​

Decision: .docs is the canonical authored source for current project, package, architecture, verification, release, and security docs. apps/docs consumes that source through a deterministic generated view.

Why locked: the repo already has canonical docs and verification around .docs; silently copying those files into the website would create stale parallel truth.

Forbidden drift: do not commit a second hand-maintained copy of package or architecture docs under apps/docs.

Reopen only if: ownership intentionally moves to apps/docs and the old .docs source is removed or reduced to redirects/indexes in the same change.

DOCS-ADR-007: No Committed Cloudflare Secrets​

Decision: Cloudflare Pages settings, custom domains, variables, and deployment commands are documented without committing account secrets or tokens.

Why locked: the docs platform must be reproducible without leaking account-level credentials.

Forbidden drift: no checked-in Cloudflare API tokens, account IDs treated as secrets, local machine deployment state, or .env files.

Reopen only if: a secure managed secret flow is introduced and documented.

DOCS-ADR-008: Apps Docs Owns Presentation Only​

Decision: apps/docs owns website chrome, Docusaurus configuration, generated content preparation, sidebars, homepage, styling, static assets, and headers. .docs/ops owns Cloudflare Pages and Storybook deployment runbooks. Package truth remains in .docs or future generated API inputs.

Why locked: package authors and verification scripts already treat .docs as the authored documentation boundary.

Forbidden drift: do not rewrite package install matrices, API inventories, or release rules as new canonical pages under apps/docs.

Reopen only if: package owners agree that specific docs move into the website app and verification is updated in the same change.

Reopen Process​

A reopened decision must record:

  • decision ID
  • reopening trigger
  • affected files and packages
  • proposed replacement
  • migration impact
  • deployment impact
  • verification impact
  • owner approval

Until a decision is reopened, implementation issues must treat forbidden drift as out of scope.