DOCUMENTATION_REORGANIZATION_PLAN.md

Documentation Reorganization Plan

Created: April 7, 2026 Status: Draft - Pending Review

Current State

• 141 markdown files in docs/ root (too many)
• 18 subdirectories already exist (good foundation)
• Multiple redundant/overlapping documents
• Legacy implementation docs mixed with current docs
• Missing documentation for recent features

Reorganization Strategy

Phase 1: File Categorization

Move files from docs/ root to appropriate subdirectories:

1. Agent System → docs/agents/

• AGENT_GOVERNANCE.md → agents/governance.md
• AGENT_GOVERNANCE_LEARNING_INTEGRATION.md → agents/governance-learning.md
• AGENT_GRADUATION_GUIDE.md → agents/graduation.md
• AGENT_GUIDANCE_IMPLEMENTATION.md → agents/guidance-system.md
• AGENT_MARKETPLACE.md → agents/marketplace.md
• AGENTS.md → agents/overview.md
• STUDENT_AGENT_TRAINING_IMPLEMENTATION.md → agents/training.md

2. AI & Intelligence → docs/intelligence/

• AI_DEBUG_QUICK_START.md → intelligence/debug-quickstart.md
• AI_DEBUG_SYSTEM.md → intelligence/debug-system.md
• EPISODIC_MEMORY_IMPLEMENTATION.md → intelligence/episodic-memory.md
• WORLD_MODEL_IMPLEMENTATION.md → intelligence/world-model.md
• GRAPHRAG_AND_ENTITY_TYPES.md → intelligence/graphrag.md
• ai-world-model.md → intelligence/world-model-guide.md

3. Canvas & Presentations → docs/canvas/

• CANVAS_AGENT_LEARNING_INTEGRATION.md → canvas/agent-learning.md
• CANVAS_AI_ACCESSIBILITY.md → canvas/ai-accessibility.md
• CANVAS_FEEDBACK_EPISODIC_MEMORY.md → canvas/feedback-memory.md
• CANVAS_QUICK_REFERENCE.md → canvas/quick-reference.md
• CANVAS_RECORDING_IMPLEMENTATION.md → canvas/recording.md
• CANVAS_STATE_API.md → canvas/state-api.md
• LLM_CANVAS_SUMMARIES.md → canvas/llm-summaries.md

4. Integration & Automation → docs/integrations/

• ADVANCED_SKILL_EXECUTION.md → integrations/advanced-skills.md
• ATOM_OPENCLAW_FEATURES.md → integrations/openclaw-features.md
• BROWSER_AUTOMATION.md → integrations/browser-automation.md
• BROWSER_QUICK_START.md → integrations/browser-quickstart.md
• COMMUNITY_SKILLS.md → integrations/community-skills.md
• DEVICE_CAPABILITIES.md → integrations/device-capabilities.md
• INTEGRATIONS.md → integrations/overview.md
• ATOM_CLI_SKILLS_GUIDE.md → integrations/cli-skills.md

5. Marketplace → docs/marketplace/

• MARKETPLACE_CONNECTION_GUIDE.md → marketplace/connection.md
• MARKETPLACE_UPDATE_SUMMARY.md → marketplace/update-summary.md
• MARKETPLACE_ANALYTICS.md → marketplace/analytics.md
• SKILL_MARKETPLACE_GUIDE.md → marketplace/skills.md

6. Testing & Quality → docs/testing/

• TESTING_INDEX.md → testing/index.md
• TESTING_ONBOARDING.md → testing/onboarding.md
• TESTING_IMPLEMENTATION_PROGRESS.md → testing/progress.md
• E2E_TESTING_GUIDE.md → testing/e2e.md
• MOBILE_TESTING_GUIDE.md → testing/mobile.md
• PROPERTY_TESTING_PATTERNS.md → testing/property-testing.md
• CROSS_PLATFORM_COVERAGE.md → testing/cross-platform.md
• CROSS_PLATFORM_PROPERTY_TESTING.md → testing/cross-platform-property.md
• DESKTOP_COVERAGE.md → testing/desktop.md
• DESKTOP_TESTING_GUIDE.md → testing/desktop-guide.md

7. Deployment & Operations → docs/operations/

• DEPLOYMENT.md → operations/deployment.md
• DEPLOYMENT_GUIDE.md → operations/deployment-guide.md
• PERSONAL_EDITION.md → operations/personal-edition.md
• MONITORING_GUIDE.md → operations/monitoring.md
• PERFORMANCE_TUNING.md → operations/performance.md
• PRODUCTION_READINESS.md → operations/production-readiness.md
• ROLLBACK_PROCEDURE.md → operations/rollback.md

8. Platform & Architecture → docs/platform/

• ARCHITECTURE.md → platform/architecture.md
• TECHNICAL_OVERVIEW.md → platform/technical-overview.md
• DATABASE_ARCHITECTURE.md → platform/database.md
• SINGLE_TENANT.md → platform/single-tenant.md
• PLATFORM.md → platform/overview.md

9. API Reference → docs/api/

• API.md → api/overview.md
• API_DOCUMENTATION_INDEX.md → api/index.md
• API_TYPE_GENERATION.md → api/type-generation.md
• FRONTEND_TO_BACKEND_API.md → api/frontend-backend.md

10. Development → docs/development/

• DEVELOPMENT.md → development/overview.md
• DEVELOPMENT_SETUP.md → development/setup.md
• CODE_QUALITY_GUIDE.md → development/code-quality.md
• BUILD.md → development/build.md

11. Security → docs/security/

• PACKAGE_SECURITY.md → security/packages.md
• PYTHON_PACKAGES_DEPLOYMENT.md → security/python-packages.md
• NPM_PACKAGE_SUPPORT.md → security/npm-packages.md

12. Features & Use Cases → docs/features/

• ATOM_VS_OPENCLAW.md → features/atom-vs-openclaw.md
• USE_CASES.md → features/use-cases.md
• FEATURE_MATRIX.md → features/matrix.md

Phase 2: Consolidation & Deduplication

Consolidate Redundant Docs:

1. Agent Governance (3 files → 1)

   • AGENT_GOVERNANCE.md
   • AGENT_GOVERNANCE_LEARNING_INTEGRATION.md
   • Merge into agents/governance.md with sections

2. Canvas Documentation (6 files → 3)

   • CANVAS_QUICK_REFERENCE.md + CANVAS_STATE_API.md → canvas/reference.md
   • Keep separate: canvas/implementation.md, canvas/ai-features.md

3. Testing Documentation (10 files → 5)

   • Merge coverage docs into testing/coverage.md
   • Merge property testing into testing/property-testing.md
   • Keep guides separate

4. Deployment (3 files → 2)

   • Merge DEPLOYMENT.md + DEPLOYMENT_GUIDE.md → operations/deployment.md
   • Keep operations/personal-edition.md separate

Phase 3: Archive Legacy Docs

Move to docs/archive/legacy/:

• ATOM_SAAS_SYNC_DEPLOYMENT.md (SaaS-specific)
• CITATION_SYSTEM_GUIDE.md (superseded by world-model docs)
• DEEPLINK_IMPLEMENTATION.md (implementation detail, not user-facing)
• MEMORY_INTEGRATION_GUIDE.md (superseded)
• MENUBAR_* files (platform-specific, move to archive/menubar/)
• MOBILE_* implementation files (move to archive/mobile/)
• NATIVE_SETUP.md (outdated)
• PHASE_* files (implementation history)
• PROPERTY_TESTING_PATTERNS.md (if duplicated in testing/)
• PYTHON_PACKAGES.md → consolidate with security/python-packages.md
• All *_IMPLEMENTATION.md files (unless actively referenced)

Phase 4: Add Missing Documentation

Recent Features (from git history):

1. WhatsApp Multi-Tenant OAuth → integrations/whatsapp-oauth.md
2. Marketplace Sync & Analytics → marketplace/sync-analytics.md
3. Meta-Agent Routing → agents/meta-agent.md
4. Fleet Admiral → agents/fleet-admiral.md
5. Intent Classifier → intelligence/intent-classifier.md
6. Single-Tenant Architecture → platform/single-tenant.md (exists, verify)

Missing User Guides:

1. Troubleshooting Guide → guides/troubleshooting.md
2. FAQ → guides/faq.md
3. Migration Guide (for updates) → guides/migration.md
4. Configuration Reference → reference/configuration.md

Phase 5: Update Cross-References

1. Update all markdown links to new paths
2. Update README.md documentation section
3. Update docs/README.md index
4. Update docs/INDEX.md if it exists
5. Update CLAUDE.md documentation references

Proposed Final Structure

docs/
├── README.md                          # Main documentation hub
├── USER_GUIDE_INDEX.md               # User documentation index
├── INDEX.md                          # Complete documentation index
│
├── agents/                           # Agent System
│   ├── overview.md
│   ├── governance.md
│   ├── graduation.md
│   ├── training.md
│   ├── guidance-system.md
│   ├── meta-agent.md
│   ├── fleet-admiral.md
│   └── marketplace.md
│
├── intelligence/                     # AI & Memory
│   ├── episodic-memory.md
│   ├── world-model.md
│   ├── graphrag.md
│   ├── intent-classifier.md
│   ├── debug-system.md
│   └── cognitive-tiers.md
│
├── canvas/                           # Canvas & Presentations
│   ├── overview.md
│   ├── implementation.md
│   ├── ai-features.md
│   ├── state-api.md
│   └── reference.md
│
├── integrations/                     # Integrations
│   ├── overview.md
│   ├── browser-automation.md
│   ├── community-skills.md
│   ├── cli-skills.md
│   ├── device-capabilities.md
│   └── whatsapp-oauth.md
│
├── marketplace/                      # Marketplace
│   ├── connection.md
│   ├── skills.md
│   ├── analytics.md
│   └── sync.md
│
├── testing/                          # Testing & Quality
│   ├── index.md
│   ├── onboarding.md
│   ├── e2e.md
│   ├── mobile.md
│   ├── desktop.md
│   ├── property-testing.md
│   └── coverage.md
│
├── operations/                       # Operations & Deployment
│   ├── deployment.md
│   ├── personal-edition.md
│   ├── monitoring.md
│   ├── performance.md
│   └── production-readiness.md
│
├── platform/                         # Platform Architecture
│   ├── architecture.md
│   ├── technical-overview.md
│   ├── database.md
│   └── single-tenant.md
│
├── api/                              # API Reference
│   ├── overview.md
│   ├── index.md
│   ├── type-generation.md
│   └── frontend-backend.md
│
├── development/                      # Development
│   ├── overview.md
│   ├── setup.md
│   ├── code-quality.md
│   └── build.md
│
├── security/                         # Security
│   ├── packages.md
│   ├── python-packages.md
│   └── npm-packages.md
│
├── features/                         # Features & Comparisons
│   ├── atom-vs-openclaw.md
│   ├── use-cases.md
│   └── matrix.md
│
├── guides/                           # User Guides
│   ├── QUICKSTART.md
│   ├── USER_GUIDE.md
│   ├── troubleshooting.md
│   ├── faq.md
│   └── migration.md
│
├── reference/                        # Reference Materials
│   ├── configuration.md
│   ├── environment-vars.md
│   └── cli-commands.md
│
└── archive/                          # Archived Documentation
    ├── legacy/
    ├── menubar/
    ├── mobile/
    └── phases/

Implementation Checklist

Phase 1: Categorization (Move files)

• Create new directory structure
• Move Agent System docs
• Move Intelligence docs
• Move Canvas docs
• Move Integration docs
• Move Marketplace docs
• Move Testing docs
• Move Operations docs
• Move Platform docs
• Move API docs
• Move Development docs
• Move Security docs
• Move Features docs

Phase 2: Consolidation

• Consolidate Agent Governance docs (3→1)
• Consolidate Canvas docs (6→3)
• Consolidate Testing docs (10→5)
• Consolidate Deployment docs (3→2)
• Review and merge other redundant docs

Phase 3: Archive

• Move legacy implementation docs
• Move SaaS-specific docs
• Move platform-specific docs
• Move phase completion docs
• Update archive index

Phase 4: Add Missing Docs

• Add WhatsApp OAuth guide
• Add Marketplace Sync guide
• Add Meta-Agent documentation
• Add Fleet Admiral guide
• Add Intent Classifier docs
• Add Troubleshooting guide
• Add FAQ
• Add Migration guide
• Add Configuration reference

Phase 5: Update References

• Update README.md links
• Update docs/README.md links
• Update docs/INDEX.md links
• Update CLAUDE.md references
• Verify all internal links work

Success Metrics

• Root docs folder: 141 files → ~20 files (hubs and indexes)
• Clear navigation: User can find any doc in <3 clicks
• No redundancy: Each topic documented once
• Complete coverage: All recent features documented
• Working links: All internal links verified

Notes

• Preserve all file history using git mv
• Create redirect pages for commonly-accessed moved docs
• Update all documentation indexes after moves
• Run link checker to verify no broken links
• Archive rather than delete to preserve history