Documentation Migration Map

Date: 2026-02-08 Status: Phase 1 complete (legacy structure removed)

This map transitions the current documentation into a stable, spec-driven structure that supports both humans and coding agents.

Target Structure

• 01-vision: why we exist, north star, design principles
• 02-domain: canonical concepts, vocabulary, invariants
• 03-architecture: service boundaries, deployment, runtime architecture
• 04-contracts: API/event/data contracts and compatibility rules
• 05-specs: capability/feature specs and implementation slices
• 06-decisions: ADRs and major trade-off records
• 07-operations: runbooks, deployment flags, incident and observability workflows
• 08-traceability: requirement-to-contract-to-test ownership mapping
• 09-agent-operations: agent autonomy playbooks and guardrails

File-by-File Mapping

Current file	Target file	Notes
docs/README.md	docs/index.md and docs/01-vision/README.md	Split orientation vs vision content
docs/founding concept.md	docs/01-vision/founding-concept.md	Rename to remove space; keep same content initially
docs/principles/product.md	docs/01-vision/product-principles.md	Direct move
docs/principles/architecture.md	docs/03-architecture/engineering-principles.md	Direct move
docs/glossary.md	docs/02-domain/glossary.md	Direct move
docs/contracts/canonical-model.md	docs/04-contracts/canonical-model.md	Keep versioning section and schema links
docs/contracts/connector-spec.md	docs/04-contracts/connector-spec.md	Keep SDK interface + output semantics
docs/diagrams/architecture.mmd	docs/03-architecture/diagrams/architecture.mmd	Move under architecture
docs/diagrams/data-model.mmd	docs/02-domain/diagrams/data-model.mmd	Move under domain
docs/specs/discovery-onboarding.md	docs/05-specs/discovery-onboarding.md	Add traceability IDs
docs/specs/authentication-iam.md	docs/05-specs/authentication-iam.md	Add state flows and error model
docs/specs/iam-roadmap.md	docs/05-specs/iam-roadmap.md	Keep roadmap as non-contractual supporting spec
docs/specs/deployment-aws.md	docs/03-architecture/deployment-aws.md	Runtime architecture concern
docs/specs/tenancy-deployment-model.md	docs/03-architecture/tenancy-model.md	Architecture concern
docs/specs/connectors/discovery-aws.md	docs/05-specs/connectors/discovery-aws.md	Provider-specific behavior spec
docs/specs/slices/slice-000-audit-platform.md	docs/05-specs/slices/slice-000-audit-platform.md	Keep as delivery slice
docs/specs/slices/slice-001-integrations-and-connections.md	docs/05-specs/slices/slice-001-integrations-and-connections.md	Keep as delivery slice
docs/specs/slices/slice-001-api-and-data.md	docs/04-contracts/integrations-api-and-data.md	Convert to explicit contract and version policy
docs/specs/slices/slice-002-discovery-runs.md	docs/05-specs/slices/slice-002-discovery-runs.md	Keep as delivery slice
docs/specs/slices/slice-003-access-explorer.md	docs/05-specs/slices/slice-003-access-explorer.md	Keep as delivery slice
docs/decisions/0001-*.md ... 0005-*.md	docs/06-decisions/0001-*.md ... 0005-*.md	Direct move
docs/structure.md	docs/08-traceability/service-to-doc-ownership.md	Replace with explicit ownership + test links

Migration Plan

1. Create target directories and README index pages. (done)
2. Copy and normalize content into new numbered structure. (done)
3. Switch MkDocs navigation to new paths. (done)
4. Remove legacy directories and duplicate files. (done)
5. Continue iterative content refinement with traceability IDs and richer contracts/tests. (in progress)

Done Criteria

• Every feature in 05-specs links to required contracts in 04-contracts, design principles, and ADRs.
• Every requirement has at least one acceptance test reference.
• Every service has a clear doc owner and operational runbook.
• Agent runbooks exist for logs, deploys, and safe git workflow.