diff --git a/docs/PRODUCTION_DEPLOYMENT.md b/docs/PRODUCTION_DEPLOYMENT.md
index 1c8852b..411199a 100644
--- a/docs/PRODUCTION_DEPLOYMENT.md
+++ b/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
 
diff --git a/docs/QUICK_REFERENCE.md b/docs/QUICK_REFERENCE.md
index 1e0e6fc..eb6029b 100644
--- a/docs/QUICK_REFERENCE.md
+++ b/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`
 
 ---
 
diff --git a/docs/SCRIPTS_GUIDE.md b/docs/SCRIPTS_GUIDE.md
index 49e03f5..94eeabe 100644
--- a/docs/SCRIPTS_GUIDE.md
+++ b/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`
 
 ---
diff --git a/HYBRID_INDEXING_COMPLETE.md b/docs/archive/HYBRID_INDEXING_COMPLETE.md
similarity index 100%
rename from HYBRID_INDEXING_COMPLETE.md
rename to docs/archive/HYBRID_INDEXING_COMPLETE.md
diff --git a/INITIALIZE_PROJECT_HOOKS_FIX.md b/docs/archive/INITIALIZE_PROJECT_HOOKS_FIX.md
similarity index 100%
rename from INITIALIZE_PROJECT_HOOKS_FIX.md
rename to docs/archive/INITIALIZE_PROJECT_HOOKS_FIX.md
diff --git a/INSTALL_ENHANCEMENTS.md b/docs/archive/INSTALL_ENHANCEMENTS.md
similarity index 100%
rename from INSTALL_ENHANCEMENTS.md
rename to docs/archive/INSTALL_ENHANCEMENTS.md
diff --git a/INSTALL_FIXES.md b/docs/archive/INSTALL_FIXES.md
similarity index 100%
rename from INSTALL_FIXES.md
rename to docs/archive/INSTALL_FIXES.md
diff --git a/PISTN_TEST_RESULTS.md b/docs/archive/PISTN_TEST_RESULTS.md
similarity index 100%
rename from PISTN_TEST_RESULTS.md
rename to docs/archive/PISTN_TEST_RESULTS.md
diff --git a/README_TESTING.md b/docs/archive/README_TESTING.md
similarity index 100%
rename from README_TESTING.md
rename to docs/archive/README_TESTING.md
diff --git a/SESSION_SUMMARY.md b/docs/archive/SESSION_SUMMARY.md
similarity index 100%
rename from SESSION_SUMMARY.md
rename to docs/archive/SESSION_SUMMARY.md
diff --git a/TESTING_STATUS.md b/docs/archive/TESTING_STATUS.md
similarity index 100%
rename from TESTING_STATUS.md
rename to docs/archive/TESTING_STATUS.md
diff --git a/TEST_COVERAGE.md b/docs/archive/TEST_COVERAGE.md
similarity index 100%
rename from TEST_COVERAGE.md
rename to docs/archive/TEST_COVERAGE.md
diff --git a/TEST_RESULTS.md b/docs/archive/TEST_RESULTS.md
similarity index 100%
rename from TEST_RESULTS.md
rename to docs/archive/TEST_RESULTS.md
diff --git a/CLAUDE_OS_DEVELOPER_GUIDE.md b/docs/development/CLAUDE_OS_DEVELOPER_GUIDE.md
similarity index 99%
rename from CLAUDE_OS_DEVELOPER_GUIDE.md
rename to docs/development/CLAUDE_OS_DEVELOPER_GUIDE.md
index beb21a1..cf17184 100644
--- a/CLAUDE_OS_DEVELOPER_GUIDE.md
+++ b/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"
diff --git a/COMPREHENSIVE_REVIEW.md b/docs/development/COMPREHENSIVE_REVIEW.md
similarity index 100%
rename from COMPREHENSIVE_REVIEW.md
rename to docs/development/COMPREHENSIVE_REVIEW.md
diff --git a/PROJECT_SETUP_AND_COMMANDS.md b/docs/development/PROJECT_SETUP_AND_COMMANDS.md
similarity index 100%
rename from PROJECT_SETUP_AND_COMMANDS.md
rename to docs/development/PROJECT_SETUP_AND_COMMANDS.md
diff --git a/SECURITY_FIXES.md b/docs/development/SECURITY_FIXES.md
similarity index 97%
rename from SECURITY_FIXES.md
rename to docs/development/SECURITY_FIXES.md
index 299f57d..e679c07 100644
--- a/SECURITY_FIXES.md
+++ b/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
 
 ---
 
diff --git a/AUTH_SETUP.md b/docs/guides/AUTH_SETUP.md
similarity index 100%
rename from AUTH_SETUP.md
rename to docs/guides/AUTH_SETUP.md
diff --git a/BACKUP_RESTORE_GUIDE.md b/docs/guides/BACKUP_RESTORE_GUIDE.md
similarity index 88%
rename from BACKUP_RESTORE_GUIDE.md
rename to docs/guides/BACKUP_RESTORE_GUIDE.md
index 55de2da..62d0ca2 100644
--- a/BACKUP_RESTORE_GUIDE.md
+++ b/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!
diff --git a/HOOK_SETUP_QUICK_START.md b/docs/guides/HOOK_SETUP_QUICK_START.md
similarity index 100%
rename from HOOK_SETUP_QUICK_START.md
rename to docs/guides/HOOK_SETUP_QUICK_START.md
diff --git a/PORTS_GUIDE.md b/docs/guides/PORTS_GUIDE.md
similarity index 100%
rename from PORTS_GUIDE.md
rename to docs/guides/PORTS_GUIDE.md
diff --git a/SHARING_GUIDE.md b/docs/guides/SHARING_GUIDE.md
similarity index 100%
rename from SHARING_GUIDE.md
rename to docs/guides/SHARING_GUIDE.md
diff --git a/START_SCRIPTS_GUIDE.md b/docs/guides/START_SCRIPTS_GUIDE.md
similarity index 100%
rename from START_SCRIPTS_GUIDE.md
rename to docs/guides/START_SCRIPTS_GUIDE.md
diff --git a/WHAT_IS_CLAUDE_OS.md b/docs/guides/WHAT_IS_CLAUDE_OS.md
similarity index 100%
rename from WHAT_IS_CLAUDE_OS.md
rename to docs/guides/WHAT_IS_CLAUDE_OS.md
diff --git a/backup_claude_os.sh b/scripts/backup_claude_os.sh
similarity index 100%
rename from backup_claude_os.sh
rename to scripts/backup_claude_os.sh
diff --git a/entrypoint.sh b/scripts/entrypoint.sh
similarity index 100%
rename from entrypoint.sh
rename to scripts/entrypoint.sh
diff --git a/restore_claude_os.sh b/scripts/restore_claude_os.sh
similarity index 100%
rename from restore_claude_os.sh
rename to scripts/restore_claude_os.sh
diff --git a/run_tests.sh b/scripts/run_tests.sh
similarity index 100%
rename from run_tests.sh
rename to scripts/run_tests.sh
diff --git a/setup_native.sh b/scripts/setup_native.sh
similarity index 100%
rename from setup_native.sh
rename to scripts/setup_native.sh
diff --git a/start_mcp_server.sh b/scripts/start_mcp_server.sh
similarity index 100%
rename from start_mcp_server.sh
rename to scripts/start_mcp_server.sh
diff --git a/start_redis_workers.sh b/scripts/start_redis_workers.sh
similarity index 100%
rename from start_redis_workers.sh
rename to scripts/start_redis_workers.sh
diff --git a/tests/TESTING_GUIDE.md b/tests/TESTING_GUIDE.md
index f165abe..8858abc 100644
--- a/tests/TESTING_GUIDE.md
+++ b/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
 
diff --git a/tests/TEST_COVERAGE.md b/tests/TEST_COVERAGE.md
index 6159c40..59da2ba 100644
--- a/tests/TEST_COVERAGE.md
+++ b/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
 ```
 
 ---