Skip to main content

Maya Documentation Scaffold

This documentation tree captures the package, developer-experience, security, and agent-native contracts that are intentionally kept outside the root README.

Documents​

  • architecture/workspace-composition.md: current and planned headless composition, module-instance, render-runtime, and Claude workspace package architecture.
  • architecture/workspace-composition-decisions.md: canonical decision register for locked workspace composition v0 decisions.
  • architecture/docs-web-decisions.md: canonical decision register for the Docusaurus and Cloudflare Pages documentation website.
  • architecture/docs-web-ia.md: public Docusaurus route, sidebar, and publish/omit map for docs.mayadev.cloud.
  • architecture/docs-web-source-policy.md: source-of-truth, generated-view, and migration policy for apps/docs.
  • architecture/docs-web-api-reference-runway.md: deferred API reference generator inputs, outputs, package inclusion criteria, and reopen conditions.
  • architecture/workspace-composition-module-authoring.md: canonical trusted npm module package, factory, render pack, CSS, fixture, module conformance, and WCP-022 checklist spec.
  • architecture/workspace-composition-security-trust.md: canonical build-time trust, UI activation grant, secret handling, redaction, prohibited code loading, and host/backend enforcement spec.
  • architecture/workspace-composition-namespace-diagnostics-versioning.md: canonical namespace, structured diagnostics, diagnostic code, version field, and fixture matrix spec.
  • architecture/workspace-composition-kernel.md: canonical headless composition kernel, policy, result shape, fallback, and fixture map spec.
  • architecture/workspace-composition-react-render-runtime.md: canonical scoped client/test React render runtime, render pack, handle coverage, fallback, ErrorBoundary, preload, diagnostics bridge, and deferred SSR boundary spec.
  • architecture/workspace-composition-surface-migration-map.md: WCP-014 source-level migration map from current Claude UI surfaces to contribution descriptors, explicit gaps, risk ranking, and the first safe visual parity milestone.
  • architecture/workspace-composition-v0-roadmap.md: executable v0 roadmap grouped by specs, packages, migration, tests, docs, and DX.
  • architecture/workspace-composition-linear-backlog.md: Linear project and issue backlog source for the v0 platform plan.
  • guides/workspace-composition-10-minute-developer-happy-path.md: current developer happy path for trusted build-time React module wiring through Claude product-kit defaults.
  • packages/assistant-composition.md: public headless contract guide for the @maya/assistant-composition package boundary.
  • packages/assistant-ui.md: user-facing guide for the React component library.
  • packages/claude-workspace.md: private product-kit boundary for @maya/claude-workspace, including WCP-019 exports, ownership, dependencies, runtime builder, deferred React entries, and migration map.
  • packages/data-lab-module.md: private first-party sample module boundary for WCP-021 trusted module authoring, render-pack, CSS, fixtures, and multi-instance proof.
  • packages/assistant-protocol.md: protocol package guide for official-shaped request, response, and SSE helpers.
  • verification.md: canonical build, verification, evidence, and release-gate guide.
  • release-governance.md: root release readiness, versioning, changelog, security, and package-artifact policy.
  • ops/cloudflare-pages-docs.md: Cloudflare Pages configuration and rollback runbook for docs.mayadev.cloud.
  • ops/cloudflare-pages-storybook.md: standalone Storybook Pages configuration and rollback runbook for storybook.mayadev.cloud.
  • ops/release-deploy-runbook.md: deploy ordering, failure handling, and release note rules for docs and Storybook.
  • ops/secrets-and-environments.md: docs and Storybook secret-handling rules.
  • ops/smoke-checks.md: production and preview smoke checks for docs and Storybook.
  • agent-native/capability-map.md: UI controller callback map to protocol helpers, backend routes, evidence, and implementation status.
  • security/supply-chain.md: static supply-chain rules for package metadata, dependency specs, package contents, and lifecycle scripts.
  • ../SECURITY.md: repository-level vulnerability reporting and security fix coordination policy.
  • ../CHANGELOG.md: workspace-level change history for release, security, governance, and user-facing changes.
  • ../.github/CODEOWNERS: repository ownership routing for package, release, security, and verification changes.

Verification And DX Debug Commands​

Run these from the workspace root while debugging documentation, package classification, or consumer wiring. This section is not the release-readiness checklist; release readiness lives in release-governance.md and the final release command remains pnpm release:gate.

pnpm verify:docs-dx
pnpm verify:docs-site
pnpm verify:verification-docs
pnpm build:packages
pnpm verify:package-registry
pnpm smoke:consumer
node tools/verify-docs-structure.mjs
node tools/verify-docs-api-parity.mjs
pnpm verify:surface-migration-map
node tools/verify-agent-capability-map.mjs
pnpm security:supply-chain

pnpm verify:docs-dx is the preferred aggregate docs gate; the individual commands are the expanded checks to run while debugging. pnpm verify:docs-site checks the Docusaurus source-of-truth boundary and builds the static docs site. The docs and package metadata verifiers are static and offline. They make pass/fail decisions from committed source, package metadata, and Markdown files; they do not install packages, run browsers, hit the network, or mutate evidence. Run pnpm build:packages before standalone pnpm smoke:consumer from a clean workspace. pnpm smoke:consumer is the package and guide consumer gate: composition/protocol/UI are checked as packed tarball consumers, while the WCP-023 guide consumer and WCP-025 product-kit consumer use workspace-private Claude workspace and Data Lab package entrypoints until their publishability is explicitly opened. pnpm pack:dry-run, pnpm security:supply-chain, and pnpm release:gate are release decision points documented in release-governance.md, not duplicated here as a second checklist. Summaries can include checkedAt timestamps for audit logs, and supply-chain verification also writes an ignored CI report under .tmp/reports.

Package Documentation Rule​

@maya/assistant-composition, @maya/assistant-ui, and @maya/assistant-protocol keep "files": ["dist", "LICENSE"] so package tarballs stay focused on build output and license metadata. tools/workspace-package-registry.mjs is the machine-readable package classification source for npmPublishable and publicAbiSnapshot. @maya/claude-workspace is a private product-kit package with WCP-019 descriptors, runtime builder, and WCP-025 workspace-private consumer smoke; it is not a tarball promise until publishability is explicitly opened. @maya/data-lab-module is a private WCP-021 sample module and is not a marketplace or publishability promise. The .docs tree is the only package documentation source in this repository; package tarballs intentionally exclude package-root README.md, dist/docs/*, and docs/* copies so release artifacts do not carry a second documentation truth.

v0 Package Support Matrix​

In v0, only @maya/assistant-composition, @maya/assistant-protocol, and @maya/assistant-ui are registry-publishable packages.

@maya/claude-workspace and @maya/data-lab-module are workspace-private validation/example packages. Their entrypoints are tested from built workspace output and are not npm artifact promises until npmPublishable: true is set in tools/workspace-package-registry.mjs.

@maya/assistant-backend, @maya/assistant-web, and @maya/docs are app-private host packages.

Root release governance, security policy, changelog, and ownership files document repository operations only. They must link to canonical package guides instead of copying package install matrices, export tables, or API inventories.