Docs Content Model

The docs app grows from curated, stable pages instead of automatically publishing every Markdown file in the repository. It is now a live static site at https://docs.wavemap.app, so the migration policy must protect the public publishing boundary as much as the information architecture.

For day-to-day page placement, figure handling, and maintenance conventions, use Docs Authoring And Maintenance.

Audience Spine

• Admin / Content: Content concepts, CMS workflows, and role explanations for non-platform operators.
• Developer: Architecture, testing, release identity, package/app guidance, ADRs, and docs-site maintenance.
• Operations / Platform: Deployment, runbooks, recovery, runtime config, generated artifacts, and approval gates.

Roadmaps, ADRs, generated projections, and docs-site policy should support those reader jobs instead of becoming a separate top-level trunk by default.

Content Classes

Class	Default Handling	Examples
Durable reference	Move or summarize into the docs app as stable pages.	Testing conventions, auth architecture, release identity vocabulary.
Operations and runbooks	Publish only the safe, reviewed operator path. Keep sensitive command evidence out.	SOPs, deployed-dev operator recipes, backup or reset policy.
Living roadmaps	Keep as source planning docs in working-notes/ until sections become stable enough to extract.	Dev deployment roadmap, auth push roadmap, feature roadmaps.
App-local implementation notes	Leave near the owning code until the pattern is durable across surfaces.	Add Artist media notes, component notes, temporary page roadmaps.
Generated projections	Publish only reviewed, sanitized outputs after deterministic artifact capture and human review.	Reviewed topology SVG figures and source sidecars.
Raw artifacts	Keep private by default.	Pulumi exports, live AWS inventory, workflow evidence, topology snapshots.
Working notes	Keep outside the published docs build.	apps/wavemap-docs/working-notes planning files and scratch implementation.

Initial Migration Rules

• Start with audience landing pages that summarize the reader job and link back to the current source documents.
• Decompose large documents only when a section has become stable enough to be useful outside the roadmap.
• Preserve working roadmap checklists in apps/wavemap-docs/working-notes/ until the project no longer needs them as active planning surfaces.
• Keep source-of-truth operational contracts in the code, manifests, scripts, Pulumi outputs, and validators that enforce them.
• Treat docs pages as explanations and navigation, not as hand-maintained replacements for deterministic artifacts.
• Keep path-filtered docs deploys from publishing working-note churn by itself.
• Promote stable roadmap decisions into modular pages, then cut the duplicated material from the roadmap.

Public-Readiness Checklist

• Keep working-notes/ outside the generated site unless a section has been reviewed and intentionally promoted.
• Avoid secret values, credential material, account-specific proof, raw logs, and live cloud evidence.
• Avoid raw cloud inventory, raw Pulumi exports, and unsanitized topology in curated pages.
• Name approval gates beside any operator path that could mutate live infrastructure, permissions, deployments, or data.
• Prefer stable concepts, code-owned contracts, and sanitized summaries over transient proof from a single run.
• Publish generated diagrams only after a sanitized review decision approves the figure slot and promoted asset path.

Figure Asset Strategy

Docs figures should make their provenance obvious from their storage lane:

Figure class	Public asset path	Source and review model
Generated topology projections	src/content/docs/figures/topology/fig-*.svg	Reviewed generated figure with .mmd sidecar, candidate provenance, and topology figure-slot ledger entry.
Authored conceptual diagrams	src/content/docs/figures/concepts/fig-*.svg	Human-authored explanatory diagram with .mmd sidecar and no generated-topology candidate or ledger slot.
Screenshots or bitmap figures	src/content/docs/figures/screenshots/fig-*.<format>	Purpose-specific visual evidence; prefer refreshed captures over hand-edited screenshots.
Raw or private artifacts	Outside the published docs tree, usually under private workflow outputs or local operator paths.	Never publish directly; promote only sanitized derivatives into one of the public lanes.

Prefer SVG for diagrams because it stays readable, diffable, and friendly to Astro image handling. Keep Mermaid source beside any Mermaid-derived figure so readers can inspect intent without treating the rendered asset as the only editable surface. Use the topology figure-slot ledger only for deterministic generated topology projections; authored conceptual diagrams should instead be reviewed like normal docs content.

Deferred

• Pull request docs previews.
• Versioned docs.
• Generated API docs publishing.
• Automated generated topology publishing.
• Access-control policy for private docs.
• Automated migration from repo Markdown into Starlight content.