Add deployment safeguards to prevent code mismatch issues

- Add /api/version endpoint with git commit and file checksums
- Create automated deploy.ps1 script with pre-flight checks
- Document file dependencies to prevent partial deployments
- Add version verification before and after deployment

Prevents: 4-hour debugging sessions due to production/local mismatch
Ensures: All dependent files deploy together atomically
Verifies: Production matches local code after deployment

FILE_DEPENDENCIES.md

@@ -0,0 +1,143 @@
+# ClaudeTools File Dependencies
+
+**CRITICAL:** These files must be deployed together. Deploying only some files will cause runtime errors.
+
+## Context Recall System
+
+**Router Layer:**
+- `api/routers/conversation_contexts.py`
+
+**Service Layer (MUST deploy with router):**
+- `api/services/conversation_context_service.py`
+
+**Model Layer (MUST deploy if schema changes):**
+- `api/models/conversation_context.py`
+- `api/models/context_tag.py`
+- `api/models/__init__.py`
+
+**Why they're coupled:**
+- Router calls service layer methods with specific parameters
+- Service layer returns model objects
+- Changing router parameters requires matching service changes
+- Model changes affect both service and router serialization
+
+**Symptom of mismatch:**
+```
+Failed to retrieve recall context: get_recall_context() got an unexpected keyword argument 'search_term'
+```
+
+---
+
+## Version System
+
+**Router:**
+- `api/routers/version.py`
+
+**Main App (MUST deploy with version router):**
+- `api/main.py`
+
+**Why they're coupled:**
+- Main app imports and registers version router
+- Missing import causes startup failure
+
+---
+
+## Deployment Rules
+
+### Rule 1: Always Deploy Related Files Together
+
+When modifying:
+- Router → Also deploy matching service file
+- Service → Check if router uses it, deploy both
+- Model → Deploy router, service, and model files
+
+### Rule 2: Use Automated Deployment
+
+```powershell
+# This script handles dependencies automatically
+.\deploy.ps1
+```
+
+### Rule 3: Verify Version Match
+
+```powershell
+# Check local version
+git rev-parse --short HEAD
+
+# Check production version
+curl http://172.16.3.30:8001/api/version | jq .git_commit_short
+```
+
+### Rule 4: Test After Deploy
+
+```powershell
+# Test recall endpoint
+curl -H "Authorization: Bearer $JWT" \
+  "http://172.16.3.30:8001/api/conversation-contexts/recall?search_term=test&limit=1"
+```
+
+---
+
+## Complete File Dependency Map
+
+```
+api/main.py
+├── api/routers/version.py (REQUIRED)
+├── api/routers/conversation_contexts.py (REQUIRED)
+│   ├── api/services/conversation_context_service.py (REQUIRED)
+│   │   └── api/models/conversation_context.py (REQUIRED)
+│   └── api/schemas/conversation_context.py (REQUIRED)
+└── ... (other routers)
+
+api/services/conversation_context_service.py
+├── api/models/conversation_context.py (REQUIRED)
+├── api/models/context_tag.py (if using normalized tags)
+└── api/utils/context_compression.py (REQUIRED)
+```
+
+---
+
+## Checklist Before Deploy
+
+- [ ] All local changes committed to git
+- [ ] Local tests pass
+- [ ] Identified all dependent files
+- [ ] Verified version endpoint exists
+- [ ] Deployment script ready
+- [ ] Database migrations applied (if any)
+- [ ] Backup of current production code (optional)
+
+---
+
+## Recovery from Bad Deploy
+
+If deployment fails:
+
+1. **Check service status:**
+```bash
+systemctl status claudetools-api
+```
+
+2. **Check logs:**
+```bash
+journalctl -u claudetools-api -n 50
+```
+
+3. **Verify files deployed:**
+```bash
+ls -lh /opt/claudetools/api/routers/
+md5sum /opt/claudetools/api/services/conversation_context_service.py
+```
+
+4. **Rollback (if needed):**
+```bash
+# Restore from backup or redeploy last known good version
+git checkout <previous-commit>
+.\deploy.ps1 -Force
+```
+
+---
+
+**Generated:** 2026-01-18
+**Last Updated:** After 4-hour debugging session due to code mismatch
+**Purpose:** Prevent deployment issues that waste development time