Skip to main content

​
Docs Spine: Agents → Droids → Humans

​
Purpose

This spine defines where active documentation lives and how it is maintained.

​
Canonical Keepers (do not move)

  • docs/DOCS_INDEX.md
  • docs/DEPLOYMENT_RUNBOOK.md
  • docs/KNOWN_ISSUES.md
  • docs/DEPLOYMENT.md
  • docs/PHASE_8E_DEPLOYMENT_SUMMARY.md (kept canonical due inbound references)

​
Topology

  • docs/runbooks/ (agents) — execution/checklist/runbook docs.
  • docs/reference/ (droids) — contracts, invariants, schemas, and technical references.
  • docs/guides/ (humans) — onboarding, walkthroughs, and operational guides.
  • docs/_audit/ — internal audit metadata.
  • docs/archive/ — historical and closed-phase artifacts.

​
Mapping (old → new)

Old pathNew path
docs/BACKEND_DEPLOYMENT_METHOD.mddocs/runbooks/BACKEND_DEPLOYMENT_METHOD.md
docs/DASHBOARD_BIGQUERY_PLAYBOOK.mddocs/runbooks/DASHBOARD_BIGQUERY_PLAYBOOK.md
docs/DASHBOARD_SMOKE_TEST.mddocs/runbooks/DASHBOARD_SMOKE_TEST.md
docs/P0_DISCOVERY_DEPLOYMENT_RUNBOOK.mddocs/runbooks/P0_DISCOVERY_DEPLOYMENT_RUNBOOK.md
docs/SHADOW_MODE_EXECUTION_GUIDE.mddocs/runbooks/SHADOW_MODE_EXECUTION_GUIDE.md
docs/BQ_CONTRACT.mddocs/reference/BQ_CONTRACT.md
docs/NO_CODE_DATA_CONTRACT.mddocs/reference/NO_CODE_DATA_CONTRACT.md
docs/agent_view_schema.mddocs/reference/agent_view_schema.md
docs/business_identity_resolution.mddocs/reference/business_identity_resolution.md
docs/system_metadata_extraction.mddocs/reference/system_metadata_extraction.md
docs/AI_UX_DEVELOPER_ONBOARDING.mddocs/guides/AI_UX_DEVELOPER_ONBOARDING.md
docs/FULL_ENV_SETUP.mddocs/guides/FULL_ENV_SETUP.md
docs/BROWSER_TEST_INSTRUCTIONS.mddocs/guides/BROWSER_TEST_INSTRUCTIONS.md
docs/MASTER_ROADMAP_v3_1.mddocs/guides/MASTER_ROADMAP_v3_1.md
docs/PHASES.mddocs/guides/PHASES.md

​
Scripted execution plan

# 1) create destinations
mkdir -p docs/runbooks docs/reference docs/guides

# 2) move docs with history-preserving renames
git mv docs/<runbook-file>.md docs/runbooks/
git mv docs/<reference-file>.md docs/reference/
git mv docs/<guide-file>.md docs/guides/

# 3) after each batch: rewrite links + run link scan before next batch
python3 scripts/docs_rewrite_links.py  # optional local helper
python3 scripts/docs_check_links.py    # optional local helper

# 4) cleanup empty legacy folders
find docs -type d -empty -delete

​
Ongoing rules

  • Keep new active docs in one of: runbooks, reference, guides.
  • Archive completed/obsolete phase docs to docs/archive/phases/.
  • Keep _audit internal-only.