docs: reorganize documentation structure and freshness cleanup

- Move docs to proper folders: THE_CLOSED_LOOP.md → architecture/,
  CI/CD docs → guides/ and integrations/
- Archive 71-day-old HN planning docs to archive/2025-10-planning/
- Archive draft automation docs (MCP, N8N, Google Drive)
- Add SECURITY.md (standard for open source projects)
- Add docs/README.md navigation index
- Fix broken CORE_THESIS.md links
- Update AI tools list (remove aider, add jules/droid/opencode)
- Standardize tool count to 145 across documentation

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

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

Author: jacopone

CHANGELOG.md

@@ -1,7 +1,7 @@
 ---
 status: active
 created: 2024-06-01
-updated: 2025-10-08
+updated: 2025-12-18
 type: reference
 lifecycle: persistent
 ---
@@ -20,6 +20,8 @@ Format based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 - `LICENSE` file (MIT) - previously only mentioned in README
 - `INSTALL.md` - comprehensive installation guide extracted from README
 - `CONTRIBUTING.md` - fork-friendly contribution guidelines
+- `SECURITY.md` - security policy (standard for open source projects)
+- `docs/README.md` - documentation navigation index
 - GitHub repository topics (16 tags for discoverability)
 - Demo GIF (`docs/assets/rebuild-demo.gif`) showing closed-loop workflow
 
@@ -31,11 +33,18 @@ Format based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 - Key Features table highlights permission learning, analytics, suggestions
 - Added "How It Works" section explaining claude-nixos-automation integration
 - Ecosystem table expanded with better descriptions of each repo's role
+- AI Tools list updated (removed aider, added jules/droid/opencode)
+- Tool count standardized to 145 across all documentation
 
 ### Documentation
 - Improved repository structure for GitHub discoverability
 - Added ecosystem table linking related repositories
 - Consolidated features into scannable tables
+- Moved `THE_CLOSED_LOOP.md` to `docs/architecture/`
+- Moved CI/CD docs to proper folders (`docs/guides/`, `docs/integrations/`)
+- Archived 71-day-old HN planning docs to `docs/archive/2025-10-planning/`
+- Archived draft automation docs (MCP, N8N, Google Drive)
+- Fixed broken link to non-existent `CORE_THESIS.md`
 
 ### Planned
 - User policies merge refactoring for claude-automation

README.md

@@ -98,7 +98,7 @@ The intelligence comes from [claude-nixos-automation](https://github.com/jacopon
 
 - **Claude Code** - Anthropic's CLI with auto-sync
 - **Cursor** - AI editor with quality gates
-- **Aider** - AI pair programming
+- **Gemini CLI / Jules** - Google's AI coding assistants
 - **Serena MCP** - Semantic code analysis
 
 ### Development Environment
@@ -125,7 +125,7 @@ The intelligence comes from [claude-nixos-automation](https://github.com/jacopon
 
 **Quality**: `shellcheck`, `shfmt`, `ruff`, `semgrep`, `tokei`, `lizard`
 
-**AI Tools**: `claude-code`, `cursor`, `aider`, `gemini-cli`, `serena`, `mcp-nixos`
+**AI Tools**: `claude-code`, `cursor`, `gemini-cli`, `jules`, `droid`, `opencode`, `serena`, `mcp-nixos`
 
 See [`modules/core/packages.nix`](modules/core/packages.nix) for the complete list.
 

SECURITY.md

@@ -0,0 +1,75 @@
+---
+status: active
+created: 2025-12-18
+updated: 2025-12-18
+type: reference
+lifecycle: persistent
+---
+
+# Security Policy
+
+## Supported Versions
+
+This is a personal NixOS configuration. Security updates are applied via:
+- NixOS unstable channel (rolling updates)
+- Weekly `nix flake update` via automated maintenance
+
+| Component | Version | Supported |
+|-----------|---------|-----------|
+| NixOS | 25.11 (unstable) | Yes |
+| Flake inputs | Latest | Yes |
+
+## Reporting a Vulnerability
+
+If you discover a security issue in this configuration:
+
+1. **Do not open a public issue** for security vulnerabilities
+2. Email the maintainer directly or use GitHub's private vulnerability reporting
+3. Include:
+   - Description of the vulnerability
+   - Steps to reproduce
+   - Potential impact
+   - Suggested fix (if any)
+
+### Response Timeline
+
+- **Acknowledgment**: Within 48 hours
+- **Initial assessment**: Within 1 week
+- **Fix (if applicable)**: Depends on severity
+
+## Security Considerations
+
+### What This Repository Contains
+
+- NixOS system configuration (declarative, reproducible)
+- Home Manager user configuration
+- Fish shell aliases and abbreviations
+- Development environment setup
+
+### What This Repository Does NOT Contain
+
+- Secrets, passwords, or API keys
+- SSH keys or certificates
+- Personal data or credentials
+
+### Security Best Practices Used
+
+1. **No hardcoded secrets** - All sensitive data via environment variables or external secret managers
+2. **Declarative configuration** - Full system state tracked in git
+3. **Reproducible builds** - Nix ensures build reproducibility
+4. **Minimal attack surface** - Only necessary packages installed
+5. **Regular updates** - Automated weekly flake updates
+
+## Dependency Security
+
+Dependencies are managed through Nix flakes with locked versions in `flake.lock`. Security updates are applied via:
+
+```bash
+nix flake update  # Updates all inputs
+./rebuild-nixos   # Applies changes with safety checks
+```
+
+## Contact
+
+- GitHub Issues: For non-security bugs and feature requests
+- Private: Use GitHub's security advisory feature for vulnerabilities

docs/README.md

@@ -0,0 +1,80 @@
+---
+status: active
+created: 2025-12-18
+updated: 2025-12-18
+type: reference
+lifecycle: persistent
+---
+
+# Documentation Index
+
+Navigation guide for all documentation in this repository.
+
+## Quick Links
+
+| Need | Go To |
+|------|-------|
+| Daily commands | [Common Tasks](guides/COMMON_TASKS.md) |
+| System architecture | [The Closed Loop](architecture/THE_CLOSED_LOOP.md) |
+| Tool configuration | [Tool Guides](#tool-guides) |
+| CI/CD setup | [CI/CD Quick Start](guides/CICD_QUICK_START.md) |
+
+---
+
+## Architecture
+
+System design and how things work.
+
+| Document | Description |
+|----------|-------------|
+| [The Closed Loop](architecture/THE_CLOSED_LOOP.md) | How system state auto-syncs to AI knowledge |
+| [Claude Orchestration](architecture/CLAUDE_ORCHESTRATION.md) | Multi-agent AI coordination system |
+
+## Guides
+
+Step-by-step instructions for common tasks.
+
+| Document | Description |
+|----------|-------------|
+| [Common Tasks](guides/COMMON_TASKS.md) | Daily commands and workflows |
+| [GitHub Workflow](guides/GITHUB_WORKFLOW.md) | Git conventions and PR process |
+| [CI/CD Quick Start](guides/CICD_QUICK_START.md) | 5-minute CI/CD setup |
+| [CI/CD Implementation](guides/CICD_IMPLEMENTATION_GUIDE.md) | Full CI/CD implementation details |
+
+## Tool Guides
+
+Configuration and optimization for specific tools.
+
+| Document | Description |
+|----------|-------------|
+| [Enhanced Tools](tools/enhanced-tools-guide.md) | Modern CLI tools deep dive |
+| [Fish Shell](tools/fish-smart-commands.md) | Fish abbreviations and smart commands |
+| [Kitty Terminal](tools/kitty-optimization-guide.md) | Terminal optimization guide |
+| [Yazi File Manager](tools/yazi-file-associations.md) | File associations and keybindings |
+
+## Integrations
+
+External tool integrations.
+
+| Document | Description |
+|----------|-------------|
+| [Cursor AI Quality](integrations/CURSOR_AI_QUALITY_INTEGRATION.md) | AI editor quality gates |
+| [CI/CD Assessment](integrations/CICD_DEVOPS_ASSESSMENT.md) | DevOps maturity assessment |
+
+## Archive
+
+Historical documentation (kept for reference, may be outdated).
+
+| Document | Description |
+|----------|-------------|
+| [2025-10 Planning](archive/2025-10-planning/) | HN launch planning docs |
+| [Documentation Audit](archive/DOCUMENTATION_AUDIT_2025-10-06.md) | October 2025 audit report |
+
+---
+
+## Related
+
+- [README](../README.md) - Project overview
+- [INSTALL](../INSTALL.md) - Installation guide
+- [CONTRIBUTING](../CONTRIBUTING.md) - Contribution guidelines
+- [CHANGELOG](../CHANGELOG.md) - Version history

docs/THE_CLOSED_LOOP.md docs/architecture/THE_CLOSED_LOOP.mddocs/THE_CLOSED_LOOP.md renamed to docs/architecture/THE_CLOSED_LOOP.md

@@ -160,7 +160,7 @@ def parse_packages(self, path: str) -> List[PackageInfo]:
 ```python
 def generate(self) -> str:
     """
-    1. Parse packages.nix → get 122 tools
+    1. Parse packages.nix → get 145 tools
     2. Parse base.nix → get 58 Fish abbreviations
     3. Render Jinja2 template with data
     4. Write to ~/.claude/CLAUDE.md
@@ -191,7 +191,7 @@ def generate(self) -> str:
 - cat → bat (ALWAYS use bat for file viewing, except when piping)
 - grep → rg (ALWAYS use ripgrep for text search)
 
-## Available Command Line Tools (122)
+## Available Command Line Tools (145)
 
 ### AI Tools
 - aider - AI Development Enhancement Tools
@@ -218,7 +218,7 @@ def generate(self) -> str:
 ```
 
 **Purpose:** Claude reads this on session start and knows:
-- What tools are available (122 tools)
+- What tools are available (145 tools)
 - How to use them (descriptions + commands)
 - What substitutions to use (modern > legacy)
 - What abbreviations exist (Fish shell)
@@ -242,7 +242,7 @@ def generate(self) -> str:
 
 ## Project Structure
 - flake.nix - Main configuration entry point
-- modules/core/packages.nix - System-wide packages (122 tools)
+- modules/core/packages.nix - System-wide packages (145 tools)
 - modules/home-manager/base.nix - User configurations
 
 ## System Status
@@ -373,7 +373,7 @@ claude
 4. Hope you don't forget
 5. Hope you spell it correctly
 6. Hope you update when tool is removed
-7. Repeat for 122 tools 😩
+7. Repeat for 145 tools 😩
 
 **Problems:**
 - ❌ Manual updates (tedious, error-prone)
@@ -621,7 +621,7 @@ def generate_claude_md(self, packages: List[Package]) -> str:
 ```markdown
 # System-Level CLAUDE.md
 
-## Available Command Line Tools (122)
+## Available Command Line Tools (145)
 
 ### AI Tools
 - `aider` - AI Development Enhancement Tools
@@ -718,7 +718,7 @@ def validate_claude_md(content: str) -> ValidationResult:
 |--------|--------|-----------|-------------|
 | **Time to document new tool** | 5-10 min | 0 seconds | ∞ |
 | **Documentation accuracy** | ~70% | 100% | +43% |
-| **Tools documented** | ~40 | 122 | +205% |
+| **Tools documented** | ~40 | 145 | +263% |
 | **Sync errors per month** | 10-15 | 0 | -100% |
 | **Maintenance time per month** | 2-3 hours | 0 seconds | ∞ |
 
@@ -885,6 +885,5 @@ With it: AI always knows system state, zero maintenance, maximum productivity.
 ---
 
 **Learn more:**
-- [Core Thesis](CORE_THESIS.md) - Why this works
 - [Architecture](architecture/CLAUDE_ORCHESTRATION.md) - System design
 - [claude-nixos-automation](https://github.com/jacopone/claude-nixos-automation) - Source code