Generate operator documentation, status, and recovery projections

[chrisdoc]

Outcome

Consumer, self-hosting, deployment, upgrade, and recovery documentation stays synchronized with executable capability, product, topology, and validation models.

Ownership seam

Documentation generators/projectors own factual tables, command references, compatibility matrices, and validated examples. Hand-written documentation owns rationale and tutorials.

Scope

• Generate/validate surface selection, version requirements, auth/config, endpoints, commands, readiness, and release compatibility tables.
• Separate consumer onboarding from maintainer deployment internals.
• Publish task-oriented Wrangler and Docker preflight/deploy/smoke/rollback/teardown runbooks.
• Publish one upgrade/migration/rollback index per surface and safe hosted build/status metadata.
• Document credential rotation, OAuth revocation, client reset, uninstall, cache cleanup, and telemetry opt-out.
• Validate links, commands, examples, and skill instructions against executable models.

Non-goals

• Generating narrative rationale.
• Embedding live credentials in examples.
• Treating prose as the source of executable facts.
• Claiming deployment success without downstream verification.

Portfolio placement

Wave 4 — proof and enforcement

Primary priority: Human operator ergonomics

Dependencies

• Centralize repository topology, artifact provenance, and validation lanes
• Project MCP contracts from canonical capability descriptors
• Deepen the CLI adapter and add safe mutation ergonomics
• Serve dual-era MCP protocols through one primitive factory
• Build the versioned operator contract and doctor interface
• Normalize Worker routing and make OAuth the hosted-only production path
• Apply one validation model to CI, artifacts, coverage, and releases

Migration and release policy

Documentation may describe upcoming major behavior only when clearly versioned. Current and next-major instructions must remain distinguishable through cutover.

Acceptance criteria

• Root, package, CLI, Docker, Worker, and skill documentation agree on current supported behavior.
• Canonical hosted naming and alias lifetime are explicit.
• Every deployment runbook includes preflight, authenticated smoke, readiness, logs, rollback, and teardown.
• Every major public change links old-to-new mappings and rollback instructions.
• A drift gate fails stale commands, links, compatibility tables, and executable examples.

Validation

• npm run check
• npm run check:types
• npm run check:server-manifest
• npm run test:pack
• npm run test:pack:cli
• npm run check:changeset

Stopping conditions

• Do not delete useful rationale merely because tables become generated.
• Stop if current users cannot distinguish released behavior from planned major behavior.

Roadmap source

Portfolio decision: Choose the improvement portfolio and breaking-change migration policy

Architecture source: Synthesize deep-module boundaries and cross-cutting opportunities

[coderabbitai]

🔗 Related PRs

#289 - Docs: Overhaul README.md with better structure and guides [merged]
#636 - chore: add mcp server skills [merged]
#679 - docs: improve README onboarding and add demo [merged]
#681 - docs: promote hosted Cloudflare endpoint [merged]
#744 - docs: update hosted MCP endpoint [merged]

---

📝 Issue Planner

_{Check the box below or use the @coderabbitai plan command to generate an implementation plan and prompts that you can use with your favorite coding assistant.}

• Create Plan

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!