docs: reorganize documentation with clear category separation

Phase 2 documentation cleanup - restructured docs/ directory for better
organization and discoverability.

New Structure:
- docs/architecture/ - System architecture documentation
  - Moved CLAUDE_ORCHESTRATION.md from root to architecture/

- docs/guides/ - User guides and how-tos
  - Contains COMMON_TASKS.md for quick reference

- docs/integrations/ - External system integrations
  - Moved CURSOR_AI_QUALITY_INTEGRATION.md from docs/ root

- docs/automation/ - Automation systems documentation
  - Contains claude-automation-system.md and refactoring plans

- docs/planning/ - Future plans and proposals
  - active/ - Active planning documents (HN_LAUNCH_PLAN.md)
  - archive/ - Completed plans (empty for now)

- docs/tools/ - Tool-specific guides (unchanged)
  - fish-smart-commands.md, enhanced-tools-guide.md, etc.

- docs/archive/ - Historical documentation
  - Moved DOCUMENTATION_AUDIT_2025-10-06.md here
  - Contains claude-automation-system-OLD.md

Link Updates:
- Updated README.md:
  - Repository structure diagram reflects new organization
  - Documentation section reorganized with new categories
  - Added User Guides subsection
  - Removed obsolete scripts/ section from diagram

- Updated docs/automation/claude-automation-system.md:
  - Fixed link to CLAUDE_ORCHESTRATION.md (now in architecture/)

- Updated templates/README.md:
  - Fixed link to CURSOR_AI_QUALITY_INTEGRATION.md (now in integrations/)

Benefits:
- Clear separation of concerns (architecture vs guides vs planning)
- Easier to find relevant documentation
- Scalable structure for future docs
- Active vs archived planning documents separated
- Historical documentation preserved but segregated

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

Author: jacopone

CHANGELOG.md

@@ -26,11 +26,26 @@ Format based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 - Fish abbreviations increased to 58
 
 ### Documentation
-- Updated CLAUDE_ORCHESTRATION.md to reflect claude-automation extraction (2025-10-03)
-- Updated README.md automation reference to external repository
-- Deprecated docs/automation/claude-automation-system.md with redirect to external repo
-- Created docs/archive/ directory for historical documentation
-- Deleted empty templates/ai-quality-devenv/ directory (superseded by ai-project-orchestration)
+- **Phase 1: Fixed Stale References**
+  - Updated CLAUDE_ORCHESTRATION.md to reflect claude-automation extraction (2025-10-03)
+  - Updated README.md automation reference to external repository
+  - Deprecated docs/automation/claude-automation-system.md with redirect to external repo
+  - Deleted empty templates/ai-quality-devenv/ directory (superseded by ai-project-orchestration)
+  - Added comprehensive documentation audit report
+
+- **Phase 2: Documentation Reorganization**
+  - Restructured docs/ with clear category separation:
+    - `docs/architecture/` - System architecture (CLAUDE_ORCHESTRATION.md)
+    - `docs/guides/` - User guides (COMMON_TASKS.md)
+    - `docs/integrations/` - External integrations (CURSOR_AI_QUALITY_INTEGRATION.md)
+    - `docs/automation/` - Automation systems
+    - `docs/planning/active/` - Active plans (HN_LAUNCH_PLAN.md)
+    - `docs/planning/archive/` - Completed plans
+    - `docs/tools/` - Tool-specific guides
+    - `docs/archive/` - Historical documentation
+  - Updated all internal markdown links to reflect new structure
+  - Updated README.md repository structure diagram
+  - Added User Guides section to documentation index
 
 ---
 

README.md

@@ -101,30 +101,33 @@ nixos-config/
 │   ├── deprecated/              # Postmortems and cost savings
 │   ├── automation/              # Cost calculator and review scripts
 │   └── chrome-profiles/         # Chrome multi-profile strategy
-├── 📁 scripts/
-│   ├── claude-automation/       # CRITICAL: Claude Code auto-generation system
-│   │   ├── generators/          # System and project CLAUDE.md generators
-│   │   ├── parsers/             # Nix configuration parsers
-│   │   ├── templates/           # Jinja2 templates for auto-generation
-│   │   ├── validators/          # Content validation
-│   │   └── README.md            # DO NOT DELETE - see CLAUDE_ORCHESTRATION.md
-│   ├── update-system-claude-v2.py   # System-level Claude Code automation engine
-│   ├── update-project-claude-v2.py  # Project-level CLAUDE.md automation
-│   ├── update-claude-configs-v2.sh  # Standalone script for both CLAUDE.md files
-│   └── devenv.nix               # DevEnv automation environment
+├── 📁 overlays/                 # Custom package overlays
+│   └── jules.nix                # Google Jules integration
 ├── 📁 docs/                     # Organized documentation
-│   ├── automation/
-│   │   └── claude-automation-system.md
-│   ├── tools/
-│   │   ├── fish-smart-commands.md
+│   ├── architecture/            # System architecture documentation
+│   │   └── CLAUDE_ORCHESTRATION.md
+│   ├── automation/              # Automation system docs
+│   │   ├── claude-automation-system.md
+│   │   └── REFACTORING_PLAN_USER_POLICIES_MERGE.md
+│   ├── guides/                  # User guides and how-tos
+│   │   └── COMMON_TASKS.md
+│   ├── integrations/            # External system integrations
+│   │   └── CURSOR_AI_QUALITY_INTEGRATION.md
+│   ├── planning/                # Future plans and proposals
+│   │   ├── active/              # Active planning documents
+│   │   │   └── HN_LAUNCH_PLAN.md
+│   │   └── archive/             # Completed plans
+│   ├── tools/                   # Tool-specific guides
 │   │   ├── enhanced-tools-guide.md
+│   │   ├── fish-smart-commands.md
 │   │   ├── kitty-optimization-guide.md
 │   │   └── yazi-file-associations.md
-│   └── CURSOR_AI_QUALITY_INTEGRATION.md
+│   └── archive/                 # Historical documentation
+│       ├── claude-automation-system-OLD.md
+│       └── DOCUMENTATION_AUDIT_2025-10-06.md
 ├── 🔧 rebuild-nixos             # Interactive rebuild script
 ├── 📋 flake.nix                 # Flake configuration
-├── 📚 CLAUDE.md                 # Project-level AI agent instructions (auto-generated)
-└── 🤖 CLAUDE_ORCHESTRATION.md   # Three-level Claude Code orchestration architecture
+└── 📚 CLAUDE.md                 # Project-level AI agent instructions (auto-generated)
 ```
 
 ## 🚀 Setup Instructions
@@ -806,9 +809,13 @@ The system detects:
 ### Core System Documentation
 
 - **[CLAUDE.md](CLAUDE.md)** - Project-level AI agent instructions (auto-generated)
-- **[CLAUDE_ORCHESTRATION.md](CLAUDE_ORCHESTRATION.md)** - Three-level Claude Code orchestration architecture (System/Project/Template)
+- **[docs/architecture/CLAUDE_ORCHESTRATION.md](docs/architecture/CLAUDE_ORCHESTRATION.md)** - Three-level Claude Code orchestration architecture
 - **[templates/README.md](templates/README.md)** - Enterprise-grade development templates with Cursor AI integration
 
+### User Guides
+
+- **[docs/guides/COMMON_TASKS.md](docs/guides/COMMON_TASKS.md)** - Quick reference for frequent operations
+
 ### Major Systems
 
 - **[basb-system/README.md](basb-system/README.md)** - Building a Second Brain knowledge management implementation
@@ -817,8 +824,9 @@ The system detects:
 
 ### AI Development Integration
 
-- **[docs/CURSOR_AI_QUALITY_INTEGRATION.md](docs/CURSOR_AI_QUALITY_INTEGRATION.md)** - Cursor AI and quality gates integration guide
+- **[docs/integrations/CURSOR_AI_QUALITY_INTEGRATION.md](docs/integrations/CURSOR_AI_QUALITY_INTEGRATION.md)** - Cursor AI and quality gates integration
 - **[Claude NixOS Automation](https://github.com/jacopone/claude-nixos-automation)** - Claude Code auto-generation system (external flake)
+- **[docs/automation/claude-automation-system.md](docs/automation/claude-automation-system.md)** - Integration guide (deprecated, redirects to external repo)
 
 ### Tools & Configuration Guides
 

CLAUDE_ORCHESTRATION.md docs/architecture/CLAUDE_ORCHESTRATION.mdCLAUDE_ORCHESTRATION.md renamed to docs/architecture/CLAUDE_ORCHESTRATION.md

@@ -12,7 +12,7 @@
 
 ### For High-Level Architecture
 
-See **[CLAUDE_ORCHESTRATION.md](../../CLAUDE_ORCHESTRATION.md)** for:
+See **[docs/architecture/CLAUDE_ORCHESTRATION.md](../architecture/CLAUDE_ORCHESTRATION.md)** for:
 - Three-level Claude Code orchestration system (System/Project/Template)
 - How auto-generation integrates with `./rebuild-nixos`
 - Manual trigger commands

docs/DOCUMENTATION_AUDIT_2025-10-06.md …rchive/DOCUMENTATION_AUDIT_2025-10-06.mddocs/DOCUMENTATION_AUDIT_2025-10-06.md renamed to docs/archive/DOCUMENTATION_AUDIT_2025-10-06.md docs/DOCUMENTATION_AUDIT_2025-10-06.md renamed to docs/archive/DOCUMENTATION_AUDIT_2025-10-06.md

@@ -245,7 +245,7 @@ gitleaks           # Secret detection
 
 - **Main README**: `~/ai-project-orchestration/README.md`
 - **Installation Guide**: `~/ai-project-orchestration/INSTALLATION_COMPLETE.md`
-- **Quality Integration**: `~/nixos-config/docs/CURSOR_AI_QUALITY_INTEGRATION.md`
+- **Quality Integration**: `~/nixos-config/docs/integrations/CURSOR_AI_QUALITY_INTEGRATION.md`
 
 ## 🎯 **Use Cases**