Documentation Cleanup Plan
Date: 2026-01-09 Status: Ready to Execute Context: We have 132 .md files (should be ~40-50 active files)
📊 Current State
Total: 132 markdown files (excluding node_modules)
Breakdown:
Root level: ~15 status/completion files
/docs/archive/2026-01/: 36 files (completed work from January)
/docs/archive/ (older): ~35 files (historical phases)
/docs/archive/future/: 2 files (AI GTM, AI Roadmap)
Active docs: ~50 files (guides, architecture, setup)
Component READMEs: ~5 files
Other: ~9 files (database, services, verify-app)
Problem: Too much historical/duplicate documentation cluttering the project
🎯 Goal
Target: 40-50 active .md files Reduction: Delete or archive ~80 files Principle: Keep ONLY actionable, current documentation
📋 Cleanup Strategy
Phase 1: Archive Root-Level Completion Reports (15 mins)
Move to /docs/archive/2026-01/:
FLEETOS_FINAL_COMPLETE.md
FLEETOS_FINAL_MIGRATION_PLAN.md
FLEETOS_CLEANUP_PLAN.md
FLEETOS_PHASE_1_2_COMPLETE.md
FLEETOS_ROUTING_ACCESS_MAPPING.md
TEST_ALIGNMENT_IMPLEMENTATION.md
TESTING_GUIDE.md (duplicate - better version in /docs/)
Rationale: These are completion reports, not active docs. Archive preserves history.
Phase 2: Delete Truly Obsolete Archive Files (30 mins)
Files to DELETE (completed work, no future value):
In /docs/archive/2026-01/:
AUTHENTICATION_UX_FLOW_AUDIT.md (work complete)
CLEANUP_COMPLETE.md (meta-documentation)
FAST_PATH_IMPLEMENTATION.md (completed)
FAST_PATH_WEEK1_COMPLETE.md (completed)
FIGMA_UX_WIREFRAMES.md (wireframes likely outdated)
FLEETOS_CLEAN_COMPLETE.md (superseded by FINAL)
FLEETOS_MIGRATION_PLAN.md (work complete)
FLEETOS_REFACTOR_ANALYSIS.md (analysis complete)
IMPLEMENTATION_ROADMAP.md (outdated)
IMPLEMENTATION_STATUS.md (outdated)
MVP_TEST_GUIDE.md (test complete)
PHASE_1_1_DATABASE_COMPLETE.md (completed)
PHASE_1_2_TEST_RESULTS.md (test results)
READY_TO_USE.md (status doc)
RESTART_NOTE_2026-01-04.md (restart notes)
RESTART_NOTE_2026-01-04_v2.md (restart notes)
VIRAL_ENGINE_DEPLOYMENT.md (deployment complete)
VIRAL_ENGINE_TEST_REPORT.md (test complete)
VIRAL_ONBOARDING_COMPLETE.md (completed)
ZERO_SIGNUP_FLOW.md (implementation complete)
ZERO_SIGNUP_IMPLEMENTATION.md (implementation complete)
In /docs/archive/ (older):
ALL_DRAWERS_FIXED.md (fixed)
CODE_QUALITY_AUDIT.md (audit complete)
CRITICAL_FIXES_SUMMARY.md (fixes done)
DEPIN_FLOW_COMPLETE.md (completed)
DRAWER_FIX_COMPLETE.md (fixed)
PHASE_0_BACKEND_INTEGRATION.md (completed)
PHASE_1_IMPLEMENTATION.md (completed)
PHASE_1_INTEGRATION_GUIDE.md (completed)
PHASE_1_MVP_COMPLETE.md (completed)
PHASE_1_SUMMARY.md (completed)
PHASE_2_TONE_AUDIT_COMPLETE.md (completed)
PHASE_2A_COMPLETE.md (completed)
PHASE_2C_PDF_EXTRACTION_COMPLETE.md (completed)
PHASE_3_VIRAL_ENGINE_COMPLETE.md (completed)
PRODUCT_CONSTITUTION_AUDIT.md (audit complete)
QUICK_TEST_STEPS.md (outdated)
ROBO_DAPP_DRAWER_FIXES.md (fixed)
ROBO_DAPP_STATUS.md (outdated status)
SIGNUP_LOOPS_COMPLETE.md (completed)
SIGNUP_LOOPS_READY_TO_TEST.md (tested)
SUPPLIER_IMPLEMENTATION_STATUS.md (outdated)
SUPPLIER_VIEW_IMPLEMENTATION.md (implemented)
SUPPLIER_VISUAL_WALKTHROUGH.md (outdated)
TEST_WHATSAPP_INVITE_LOOP.md (tested)
TEST_WHATSAPP_NOW.md (tested)
TESTING_GUIDE.md (duplicate)
TESTING_NEW_FEATURES.md (outdated)
TESTING_PHASE_1.md (completed)
TONE_AUDIT_VIOLATIONS.md (violations fixed)
TWO_SIDED_MARKETPLACE_COMPLETE.md (completed)
USER_STATE_FIX.md (fixed)
Also in /Robo-Dapp/:
DRAWER_DARK_MODE_COMPLETE.md (completed)
LIGHT_MODE_CONTRAST_FIX.md (completed)
Rationale: These are completion reports with no future reference value. Keeping them clutters the project.
Result: Delete ~55 obsolete files
Phase 3: Consolidate Product Documentation (45 mins)
Current State (Too Many Overlapping Guides):
/docs/FLEETOS_GUIDE.md (231 lines) - good
/docs/FLEETOS_README.md (246 lines) - overlaps with GUIDE
/docs/FLEETOS_PRODUCT_OVERVIEW.md (1,006 lines) - HUGE, mixed FleetOS + Robo-Hub
/docs/ROBO_HUB_GUIDE.md (100+ lines) - different product
Action:
Split FLEETOS_PRODUCT_OVERVIEW.md:
Extract FleetOS sections → Keep in /docs/FLEETOS_GUIDE.md (expand it)
Extract Robo-Hub marketplace sections → /docs/robo-hub/PRODUCT_OVERVIEW.md
DELETE the original mixed file
Merge FLEETOS_README.md into FLEETOS_GUIDE.md:
Consolidate overlapping content
DELETE FLEETOS_README.md (redundant)
Keep:
/docs/FLEETOS_GUIDE.md (consolidated FleetOS product guide)
/docs/FLEETOS_TONE_GUIDELINES.md (copy guidance)
/docs/fleetos/ directory (architecture, viral engine)
Result: 3 FleetOS docs instead of 4, clearer separation from Robo-Hub
Phase 4: Move Robo-Hub Docs to Proper Location (15 mins)
Move to /docs/robo-hub/:
/ARCHITECTURE.md → /docs/robo-hub/ARCHITECTURE.md (Shepherd/Supplier marketplace)
/docs/ROBO_HUB_GUIDE.md → /docs/robo-hub/PRODUCT_GUIDE.md
Update:
Add header to each: "# Robo-Hub Product (NOT FleetOS)"
Rationale: Prevents confusion - FleetOS is NOT a marketplace
Phase 5: Organize Root-Level Architecture Docs (15 mins)
Current root-level files that should move:
ARCHITECTURE_MIGRATION_PLAN.md → /docs/archive/2026-01/ (work complete)
PROGRESSIVE_AUTH_ARCHITECTURE.md → /docs/fleetos/architecture/
T420_ECOSYSTEM_MASTER_ARCHITECTURE.md → /docs/ (keep at docs level)
Keep in root:
README.md (project overview)
QUICK_START.md (getting started)
DEPLOYMENT.md (deployment guide)
SECURITY_CREDENTIALS.md (credentials)
USER_FLOWS.md (UX flows)
Phase 6: Verify Organized Structure (15 mins)
Final structure should be:
Total Active Files: ~40-45 .md files ✅
🗑️ Deletion Summary
Files to DELETE: ~55 obsolete completion reports Files to MOVE to archive: ~7 root-level completion files Files to CONSOLIDATE: 2 (merge README into GUIDE, split PRODUCT_OVERVIEW) Files to REORGANIZE: 5 (move to proper directories)
Net Result: 132 files → 40-45 active files (~65% reduction)
✅ Execution Order
Phase 1 - Archive root completions (15 mins)
Phase 4 - Move Robo-Hub docs (15 mins)
Phase 5 - Organize architecture (15 mins)
Phase 2 - Delete obsolete archives (30 mins)
Phase 3 - Consolidate product docs (45 mins)
Phase 6 - Verify structure (15 mins)
Total Time: 2 hours 15 minutes
🚨 Safety
Before deleting anything:
Commit current state (backup)
Review each file before deletion
Keep /docs/archive/ARCHIVE_INDEX.md updated
Rollback: Git reset if needed
📝 Notes
Why we didn't do this before:
Got sidetracked with FleetOS Final migration (fleetos-clean → fleetos)
This cleanup was planned in Section 12 of the alignment plan
Now is the right time (codebase stable, migration complete)
What this achieves:
Clearer project structure
Easier onboarding for new devs
Reduced cognitive load
Better separation of FleetOS vs Robo-Hub docs
Ready to execute? Awaiting approval.
Last updated
Was this helpful?