🗂️ ORGANIZE: Reorganize root directory structure

Moved 25 files from root to organized subdirectories while keeping
essential scripts (install.sh, setup.sh, start*.sh, stop*.sh) in root.

## Changes:

### New Directory Structure:
- Created `/scripts/` for utility scripts
- Created `/docs/guides/` for user guides
- Created `/docs/development/` for dev documentation
- Created `/docs/archive/` for historical/legacy docs

### Moved Files:

**To `/scripts/` (7 files):**
- backup_claude_os.sh
- restore_claude_os.sh
- run_tests.sh
- setup_native.sh
- start_mcp_server.sh
- start_redis_workers.sh
- entrypoint.sh

**To `/docs/guides/` (7 files):**
- AUTH_SETUP.md
- BACKUP_RESTORE_GUIDE.md
- HOOK_SETUP_QUICK_START.md
- SHARING_GUIDE.md
- START_SCRIPTS_GUIDE.md
- PORTS_GUIDE.md
- WHAT_IS_CLAUDE_OS.md

**To `/docs/development/` (4 files):**
- COMPREHENSIVE_REVIEW.md
- SECURITY_FIXES.md
- CLAUDE_OS_DEVELOPER_GUIDE.md
- PROJECT_SETUP_AND_COMMANDS.md

**To `/docs/archive/` (10 files):**
- HYBRID_INDEXING_COMPLETE.md
- INITIALIZE_PROJECT_HOOKS_FIX.md
- INSTALL_ENHANCEMENTS.md
- INSTALL_FIXES.md
- PISTN_TEST_RESULTS.md
- SESSION_SUMMARY.md
- TEST_COVERAGE.md
- TEST_RESULTS.md
- TESTING_STATUS.md
- README_TESTING.md

### Updated References:

**Fixed broken documentation links in:**
- docs/QUICK_REFERENCE.md
- docs/PRODUCTION_DEPLOYMENT.md
- docs/SCRIPTS_GUIDE.md
- docs/development/SECURITY_FIXES.md
- docs/guides/BACKUP_RESTORE_GUIDE.md
- docs/development/CLAUDE_OS_DEVELOPER_GUIDE.md
- tests/TESTING_GUIDE.md
- tests/TEST_COVERAGE.md

**Script references updated to:**
- `./scripts/backup_claude_os.sh`
- `./scripts/restore_claude_os.sh`
- `./scripts/run_tests.sh`
- `./scripts/setup_native.sh`
- `./scripts/start_mcp_server.sh`
- `./scripts/start_redis_workers.sh`

### Remaining in Root (9 essential files):
- install.sh
- setup.sh
- start.sh
- start_all_services.sh
- stop_all_services.sh
- restart_services.sh
- README.md
- CLAUDE.md
- requirements.txt (+ GEMINI_DIAGRAM_PROMPT.md)

## Benefits:
✅ Cleaner root directory (9 files vs 34 files)
✅ Organized documentation by purpose
✅ Scripts grouped in dedicated directory
✅ Essential startup commands still in root
✅ All references updated and verified
✅ No broken links

Version: 2.0.2

docs/PRODUCTION_DEPLOYMENT.md

@@ -198,7 +198,7 @@ Visit `https://staging.pistn.com/login` and use your configured email/password.
 
 **Note:** If you don't configure these variables, authentication is disabled and the frontend is open access.
 
-See [`AUTH_SETUP.md`](/AUTH_SETUP.md) for detailed authentication documentation.
+See [`AUTH_SETUP.md`](/docs/guides/AUTH_SETUP.md) for detailed authentication documentation.
 
 ### 6. Update PISTN Rails App
 

docs/QUICK_REFERENCE.md

@@ -415,7 +415,7 @@ When you say these, Claude automatically saves to memories:
 
 - **Full README**: `README.md`
 - **Deployment Guide**: `docs/DEPLOYMENT_GUIDE.md`
-- **Sharing Guide**: `SHARING_GUIDE.md`
+- **Sharing Guide**: `docs/guides/SHARING_GUIDE.md`
 
 ---
 

docs/SCRIPTS_GUIDE.md

@@ -6,7 +6,7 @@ Quick reference for managing Claude OS services on macOS.
 
 ```bash
 # First time setup (installs dependencies)
-./setup_native.sh
+./scripts/setup_native.sh
 
 # Start all services
 ./start_all_services.sh
@@ -40,7 +40,7 @@ Quick reference for managing Claude OS services on macOS.
 
 **Usage:**
 ```bash
-./setup_native.sh
+./scripts/setup_native.sh
 ```
 
 **Output:**
@@ -223,7 +223,7 @@ git clone <repo>
 cd claude-os
 
 # 2. Run setup
-./setup_native.sh
+./scripts/setup_native.sh
 
 # 3. Start services
 ./start_all_services.sh
@@ -345,7 +345,7 @@ cp data/claude-os.db.backup data/claude-os.db
 rm data/claude-os.db
 
 # Re-setup
-./setup_native.sh
+./scripts/setup_native.sh
 
 # Start fresh
 ./start_all_services.sh
@@ -453,7 +453,7 @@ tail -50 logs/frontend.log
 For issues:
 1. Check logs
 2. Try `./restart_services.sh`
-3. Try `./setup_native.sh` again
+3. Try `./scripts/setup_native.sh` again
 4. Check if Ollama is running: `ollama ps`
 
 ---

docs/development/CLAUDE_OS_DEVELOPER_GUIDE.md

@@ -317,10 +317,10 @@ for row in cursor.fetchall():
 
 ```bash
 # Start just MCP Server
-./start_mcp_server.sh
+./scripts/start_mcp_server.sh
 
 # Start just Redis Workers
-./start_redis_workers.sh
+./scripts/start_redis_workers.sh
 
 # Restart everything
 ./restart_services.sh
@@ -988,7 +988,7 @@ rq info          # Should show 3 workers
 redis-cli LLEN rq:queue:claude-os:learning
 
 # Restart workers if needed
-./start_redis_workers.sh
+./scripts/start_redis_workers.sh
 ```
 
 ### "Ingest is timing out"

docs/development/SECURITY_FIXES.md

@@ -341,9 +341,9 @@ done
 ## 📚 Related Documentation
 
 - [Comprehensive Review](COMPREHENSIVE_REVIEW.md) - Full analysis of findings
-- [API Reference](docs/API_REFERENCE.md) - Complete API documentation
-- [Auth Setup Guide](AUTH_SETUP.md) - Authentication configuration
-- [Production Deployment](docs/PRODUCTION_DEPLOYMENT.md) - Deployment best practices
+- [API Reference](../API_REFERENCE.md) - Complete API documentation
+- [Auth Setup Guide](../guides/AUTH_SETUP.md) - Authentication configuration
+- [Production Deployment](../PRODUCTION_DEPLOYMENT.md) - Deployment best practices
 
 ---
 

docs/guides/BACKUP_RESTORE_GUIDE.md

@@ -7,7 +7,7 @@ This guide explains how to safely backup and restore your Claude OS installation
 ### 1. Backup Your Current Setup
 
 ```bash
-./backup_claude_os.sh
+./scripts/backup_claude_os.sh
 ```
 
 This creates a timestamped backup in `backups/backup_YYYYMMDD_HHMMSS/` containing:
@@ -24,7 +24,7 @@ Backup size: 125M
 Backup timestamp: 20251101_135211
 
 To restore this backup later:
-  ./restore_claude_os.sh 20251101_135211
+  ./scripts/restore_claude_os.sh 20251101_135211
 ```
 
 ### 2. Test Fresh Installation
@@ -44,7 +44,7 @@ Now you can safely test the installation process:
 If you need to restore your backup:
 
 ```bash
-./restore_claude_os.sh 20251101_135211
+./scripts/restore_claude_os.sh 20251101_135211
 ```
 
 Replace `20251101_135211` with your actual backup timestamp.
@@ -96,7 +96,7 @@ Replace `20251101_135211` with your actual backup timestamp.
 ### Backup Command
 
 ```bash
-./backup_claude_os.sh
+./scripts/backup_claude_os.sh
 ```
 
 **What it does:**
@@ -111,16 +111,16 @@ Replace `20251101_135211` with your actual backup timestamp.
 ### Restore Command
 
 ```bash
-./restore_claude_os.sh <timestamp>
+./scripts/restore_claude_os.sh <timestamp>
 ```
 
 **Examples:**
 ```bash
 # Restore specific backup
-./restore_claude_os.sh 20251101_135211
+./scripts/restore_claude_os.sh 20251101_135211
 
 # List available backups
-./restore_claude_os.sh
+./scripts/restore_claude_os.sh
 ```
 
 **What it does:**
@@ -140,7 +140,7 @@ Replace `20251101_135211` with your actual backup timestamp.
 
 1. **Backup first:**
    ```bash
-   ./backup_claude_os.sh
+   ./scripts/backup_claude_os.sh
    ```
 
 2. **Stop all services:**
@@ -183,7 +183,7 @@ Replace `20251101_135211` with your actual backup timestamp.
 
 6. **If something goes wrong, restore:**
    ```bash
-   ./restore_claude_os.sh 20251101_135211
+   ./scripts/restore_claude_os.sh 20251101_135211
    ./start.sh
    ```
 
@@ -195,7 +195,7 @@ Replace `20251101_135211` with your actual backup timestamp.
 
 ```bash
 # 1. Backup everything
-./backup_claude_os.sh
+./scripts/backup_claude_os.sh
 
 # 2. Clean installation (keep data, test scripts)
 rm -rf venv
@@ -206,7 +206,7 @@ rm ~/.claude/skills/{memory,initialize-project,remember-this}
 ./install.sh
 
 # 4. Restore your data (database, configs)
-./restore_claude_os.sh <timestamp>
+./scripts/restore_claude_os.sh <timestamp>
 ./start.sh
 ```
 
@@ -214,7 +214,7 @@ rm ~/.claude/skills/{memory,initialize-project,remember-this}
 
 ```bash
 # 1. Backup everything
-./backup_claude_os.sh
+./scripts/backup_claude_os.sh
 
 # 2. Full clean (simulate fresh machine)
 ./stop_all_services.sh
@@ -229,7 +229,7 @@ rm ~/.claude/skills/{memory,initialize-project,remember-this}
 ./start_all_services.sh
 
 # 4. Restore your data
-./restore_claude_os.sh <timestamp>
+./scripts/restore_claude_os.sh <timestamp>
 ./start.sh
 ```
 
@@ -237,7 +237,7 @@ rm ~/.claude/skills/{memory,initialize-project,remember-this}
 
 ```bash
 # 1. Backup current state
-./backup_claude_os.sh
+./scripts/backup_claude_os.sh
 
 # 2. Create test project
 cd ~/test-project
@@ -245,7 +245,7 @@ cd ~/test-project
 
 # 3. If something breaks, restore
 cd ~/Projects/claude-os
-./restore_claude_os.sh <timestamp>
+./scripts/restore_claude_os.sh <timestamp>
 ```
 
 ---
@@ -281,9 +281,9 @@ tar -czf backups_archive_2025.tar.gz backups/
 The backup script creates **new backups** each time - it never overwrites:
 
 ```bash
-./backup_claude_os.sh  # Creates backup_20251101_135211
-./backup_claude_os.sh  # Creates backup_20251101_140530
-./backup_claude_os.sh  # Creates backup_20251101_141005
+./scripts/backup_claude_os.sh  # Creates backup_20251101_135211
+./scripts/backup_claude_os.sh  # Creates backup_20251101_140530
+./scripts/backup_claude_os.sh  # Creates backup_20251101_141005
 ```
 
 You can safely run it multiple times!
@@ -299,14 +299,14 @@ You can safely run it multiple times!
 ls -1 backups/ | grep backup_
 
 # Use exact timestamp from list
-./restore_claude_os.sh 20251101_135211
+./scripts/restore_claude_os.sh 20251101_135211
 ```
 
 ### "Permission denied"
 
 ```bash
 # Make scripts executable
-chmod +x backup_claude_os.sh restore_claude_os.sh
+chmod +x scripts/backup_claude_os.sh scripts/restore_claude_os.sh
 ```
 
 ### "Database locked" during backup
@@ -316,7 +316,7 @@ chmod +x backup_claude_os.sh restore_claude_os.sh
 ./stop_all_services.sh
 
 # Then backup
-./backup_claude_os.sh
+./scripts/backup_claude_os.sh
 ```
 
 ### Restore doesn't fix everything
@@ -329,7 +329,7 @@ The restore script restores **data** but not:
 
 **Full recovery process:**
 ```bash
-./restore_claude_os.sh <timestamp>
+./scripts/restore_claude_os.sh <timestamp>
 ./install.sh  # Recreate symlinks
 ./start.sh    # Start services
 ```
@@ -420,12 +420,12 @@ openssl enc -aes-256-cbc -pbkdf2 -d -in backup_encrypted.tar.gz.enc | \
 
 1. Your backup is ready: `backups/backup_20251101_135211/`
 2. You can safely test `./install.sh`
-3. If anything breaks: `./restore_claude_os.sh 20251101_135211`
+3. If anything breaks: `./scripts/restore_claude_os.sh 20251101_135211`
 4. Test away with confidence! 🚀
 
 ---
 
 **Questions?**
 - Check `backups/backup_*/MANIFEST.txt` for backup contents
-- Run `./restore_claude_os.sh` with no arguments to list backups
+- Run `./scripts/restore_claude_os.sh` with no arguments to list backups
 - Backups are fast (30 seconds) - backup often!

tests/TESTING_GUIDE.md

@@ -27,7 +27,7 @@ This guide provides comprehensive information about testing Claude OS, a product
 ### Run All Tests
 
 ```bash
-./run_tests.sh
+./scripts/run_tests.sh
 ```
 
 That's it! The script will:
@@ -77,32 +77,32 @@ tests/
 
 ```bash
 # All tests
-./run_tests.sh
+./scripts/run_tests.sh
 
 # With coverage report
-./run_tests.sh --coverage
+./scripts/run_tests.sh --coverage
 
 # Verbose output
-./run_tests.sh --verbose
+./scripts/run_tests.sh --verbose
 ```
 
 ### By Category
 
 ```bash
 # Unit tests only (fast)
-./run_tests.sh --unit
+./scripts/run_tests.sh --unit
 
 # Integration tests
-./run_tests.sh --integration
+./scripts/run_tests.sh --integration
 
 # Vector operations
-./run_tests.sh --vector
+./scripts/run_tests.sh --vector
 
 # RAG engine
-./run_tests.sh --rag
+./scripts/run_tests.sh --rag
 
 # API endpoints
-./run_tests.sh --api
+./scripts/run_tests.sh --api
 ```
 
 ### Advanced Usage
@@ -213,7 +213,7 @@ See `.github/workflows/tests.yml` for configuration.
 ```bash
 # .git/hooks/pre-commit
 #!/bin/bash
-./run_tests.sh --unit
+./scripts/run_tests.sh --unit
 if [ $? -ne 0 ]; then
     echo "Tests failed! Commit aborted."
     exit 1
@@ -270,7 +270,7 @@ psql -d codeforge_test -f app/core/schema.sql
 ### Generate HTML Report
 
 ```bash
-./run_tests.sh --coverage
+./scripts/run_tests.sh --coverage
 open htmlcov/index.html  # macOS
 xdg-open htmlcov/index.html  # Linux
 ```
@@ -300,7 +300,7 @@ xdg-open htmlcov/index.html  # Linux
 - [ ] Test happy path
 - [ ] Test edge cases
 - [ ] Test error handling
-- [ ] Run `./run_tests.sh`
+- [ ] Run `./scripts/run_tests.sh`
 - [ ] Verify >80% coverage
 - [ ] Update documentation
 

tests/TEST_COVERAGE.md

@@ -95,29 +95,29 @@ Comprehensive test suite for Claude OS RAG system covering all critical componen
 
 ### All tests:
 ```bash
-./run_tests.sh
+./scripts/run_tests.sh
 ```
 
 ### Unit tests only (fast):
 ```bash
-./run_tests.sh --unit
+./scripts/run_tests.sh --unit
 ```
 
 ### Integration tests:
 ```bash
-./run_tests.sh --integration
+./scripts/run_tests.sh --integration
 ```
 
 ### Specific category:
 ```bash
-./run_tests.sh --vector
-./run_tests.sh --rag
-./run_tests.sh --api
+./scripts/run_tests.sh --vector
+./scripts/run_tests.sh --rag
+./scripts/run_tests.sh --api
 ```
 
 ### With coverage:
 ```bash
-./run_tests.sh --coverage
+./scripts/run_tests.sh --coverage
 ```
 
 ---