Docs Migration Status

Migration strategy

• /docs: external-ready and shared product documentation.
• /internal: operational and governance content for the team.
• Source repo docs remain valid during migration; each section is rewritten and promoted with audience tags.

Current status

Already migrated to Fumadocs

• Internal runbooks set (incident-response, secrets-rotation, purchase-lifecycle).
• Docs information architecture strategy.
• Audience tagging workflow and badge rendering.

Migrated in this pass

• Starter CLI workflows
• Runtime feature flags (OpenFeature)
• UI library hardening
• Performance guidelines
• @athas/shared-api package guide
• @athas/contracts package guide
• AI-assisted docs workflow
• @athas/db package guide
• @athas/auth-core package guide
• @athas/shared-utils package guide
• concise architecture pages (backend-patterns, frontend-patterns, api-interfaces, modular-composition)
• guide migration pages (getting-started, feature-scaffolding, backend-module-workflow, module-composition-guide)

Next batches

1. Enable check:docs-canonical in PR/CI docs workflow.
2. Audit remaining non-pointer legacy docs and decide keep vs migrate.
3. Add optional report output for migration coverage deltas.

Legacy docs redirect status

• Legacy guides/packages now include canonical Fumadocs pointers.
• Root docs/README.md quick links now prioritize canonical Fumadocs page paths for migrated content.
• Selected legacy guide files have been trimmed to pointer-only stubs to reduce duplicate maintenance.
• Additional legacy pages (creating-a-module, package docs, performance guidelines) were trimmed to pointer-only stubs in pruning batch 2.
• Core legacy architecture files (23-backend-patterns, 25-frontend-patterns, 32-api-architecture, 40-modular-composition) were trimmed to pointer-only stubs in pruning batch 3.
• Additional legacy guides (feature-flags-openfeature, starter-cli-workflows, ui-library-hardening) were trimmed to pointer-only stubs in pruning batch 4.

Exit criteria

Use Migration Complete Checklist before declaring migration complete.

Maintenance checks

• Run bun run check:docs-canonical to validate:
  • required legacy pointer stubs are present and have canonical targets
  • /docs pages include audience frontmatter and do not use internal
• CI and pre-commit hooks now execute this check automatically for docs integrity.
• Run bun run check:docs-canonical:report for maintenance coverage snapshots.