Refactor media transformation logic into reusable utility

CLAUDE.md

@@ -49,6 +49,210 @@ npm start                    # DEPLOYS code changes
 
 ---
 
+## 💾 DATABASE BACKUP SYSTEM
+
+**Automatic backups prevent catastrophic data loss**
+
+### The Safety Net (Implemented 2025-11-18)
+
+All destructive database operations now AUTOMATICALLY create backups:
+- `npm run data:reseed` → creates backup BEFORE clearing
+- `npm run data:clear` → creates backup BEFORE clearing
+- `npm run data:restore` → creates backup BEFORE restoring
+
+**Manual backup/restore commands:**
+```bash
+npm run data:backup           # Create timestamped backup
+npm run data:restore          # Interactive: select from backup list
+npm run data:restore -- filename.sqlite  # Direct restore
+```
+
+**How it works:**
+- Backups stored in: `examples/widget-ui/.continuum/jtag/backups/`
+- Timestamped filenames: `database-backup-2025-11-19T01-46-12.sqlite`
+- Automatic cleanup: keeps last 10 backups
+- Pre-restore safety: creates backup of current DB before restoring
+
+**Why this exists:**
+Lesson learned from 2025-11-18: I ran `npm run data:reseed` to fix a simple bug and destroyed hours of irreplaceable training data. Now that can never happen again.
+
+**For updating existing data (preferred over reseed):**
+```bash
+# Example: Update Grok user's model
+GROK_ID=$(./jtag data/list --collection=users | jq -r '.data[] | select(.displayName == "Grok") | .id')
+./jtag data/update --collection=users --id="$GROK_ID" \
+  --updates='{"modelConfig.model":"grok-3"}'
+```
+
+---
+
+## 🔧 GIT WORKFLOW: STASH FIRST, NEVER REVERT
+
+**The correct git workflow: STASH → TEST → COMMIT or UNSTASH**
+
+### Use git stash, NOT git checkout/revert
+
+**WRONG (destroys your work)**:
+```bash
+# Made changes, something broke
+git checkout HEAD -- file.ts  # ❌ DESTROYS YOUR CHANGES FOREVER
+git revert <commit>           # ❌ Creates messy revert commits
+```
+
+**CORRECT (preserves your work)**:
+```bash
+# Made changes, want to test clean state
+git stash                     # ✅ Saves changes temporarily
+npm start && ./jtag ping      # Test clean state
+
+# If clean state works, your changes broke it:
+git stash pop                 # Restore your changes
+# Debug and fix
+
+# If clean state is also broken, it wasn't your changes:
+git stash pop                 # Restore your changes, continue working
+```
+
+### Complete stash workflow
+
+```bash
+# 1. Save current work
+git stash push -m "WIP: image autonomy changes"
+
+# 2. Verify clean state
+npm start && sleep 120
+./jtag ping
+
+# 3. Decision point:
+# If broken in clean state: Not your fault
+git stash pop  # Restore work, investigate system issue
+
+# If working in clean state: Your changes broke it
+git stash pop  # Restore work
+git diff       # See what you changed
+# Fix the issue
+
+# 4. When ready to try again:
+# Edit files
+npm start && sleep 120
+# Test
+
+# 5. Only commit when verified working
+git add .
+git commit -m "fix: ..."
+```
+
+### View and manage stashes
+
+```bash
+# List all stashes
+git stash list
+
+# Show what's in a stash
+git stash show -p stash@{0}
+
+# Apply stash without removing it
+git stash apply
+
+# Apply specific stash
+git stash apply stash@{1}
+
+# Drop a stash you don't need
+git stash drop stash@{0}
+
+# Clear all stashes (careful!)
+git stash clear
+```
+
+### Why stash > revert
+
+1. **Non-destructive**: Your work is saved, not deleted
+2. **Reversible**: Can pop/apply/drop stashes freely
+3. **Clean history**: No "revert X" commits polluting git log
+4. **Fast**: Stash/pop is instant, revert requires commit
+5. **Multiple stashes**: Can save multiple WIP states
+
+### When to use git reset (advanced)
+
+**ONLY use reset if you committed too early**:
+```bash
+# Made commit, but tests fail
+git reset --soft HEAD~1   # Undo commit, keep changes staged
+# Fix issues
+git add .
+git commit -m "fix: corrected version"
+
+# OR keep changes unstaged:
+git reset HEAD~1          # Undo commit, unstage changes
+```
+
+**NEVER use `git reset --hard`** (destroys work permanently)
+
+---
+
+## 🚫 CRITICAL: NEVER COMMIT BEFORE TESTING
+
+**The iron rule of development: STASH → TEST → VERIFY → COMMIT**
+
+### What Went Wrong (2025-11-18 - Lesson Learned)
+
+**My mistake:**
+1. Read summary saying "PersonaToolExecutor needs refactoring"
+2. Read the actual file - saw it was already clean (210 lines)
+3. **COMMITTED ANYWAY** without testing
+4. Then deployed and hoped it worked
+
+**Why this was insane:**
+- Committed code I didn't verify worked
+- Polluted git history with untested changes
+- If it broke, would need to revert/reset (harder recovery)
+- Violated basic QA discipline
+
+**The correct order:**
+```bash
+# 1. Make changes to code
+# 2. TEST first
+npm start && sleep 120 && ./jtag ping
+./jtag chat/send --room="general" --message="Testing new feature..."
+
+# 3. VERIFY it works
+./jtag chat/export --room="general" --limit=10  # Check responses
+
+# 4. ONLY THEN commit
+git add system/user/server/modules/PersonaToolExecutor.ts
+git commit -m "Fix: Verified working refactor"
+```
+
+**The fundamental error in thinking:**
+- Trusted old summary context over current codebase state
+- Never asked: "What's ACTUALLY broken right now?"
+- Assumed task from summary was still valid without verification
+- Committed based on intention, not evidence
+
+**What I should have done when file looked already refactored:**
+1. **STOP** - This doesn't match the summary
+2. **ASK** - Is this already fixed? What's the real problem?
+3. **TEST CURRENT STATE** - Does it actually work right now?
+4. **DIAGNOSE ACTUAL ISSUE** - Don't fix what isn't broken
+
+**The AI team's response** (they were right):
+- "Show us a specific failing command"
+- "What error are you seeing?"
+- "The code looks clean already"
+- They forced me to actually understand the problem
+
+**Turns out:** PersonaToolExecutor was fine. Real issue was XML routing for some AIs, not the core code.
+
+### Golden Rules
+
+1. **ALWAYS test before committing** - no exceptions
+2. **Question discrepancies** - if summary says X but code shows Y, investigate
+3. **Commit = "this works"** - never commit hope, commit evidence
+4. **Ask "what's broken NOW?"** - not "what did summary say to fix?"
+5. **Use git properly** - it's version control, not a backup drive
+
+---
+
 ## 🚨 CONSTANTS: SINGLE SOURCE OF TRUTH
 
 **CRITICAL**: ALL system constants MUST be in ONE file: `system/shared/Constants.ts`
@@ -300,6 +504,8 @@ max-width: calc(100vw - var(--sidebar-width) - 100px);  /* ← 100px is brittle
 ---
 
 ### Chat Commands
+
+**Basic Usage:**
 ```bash
 # Send message to chat room (direct DB, no UI)
 ./jtag chat/send --room="general" --message="Hello team"
@@ -311,6 +517,30 @@ max-width: calc(100vw - var(--sidebar-width) - 100px);  /* ← 100px is brittle
 ./jtag chat/export --limit=100 --includeSystem=true               # All rooms with system messages
 ```
 
+**Interactive Workflow - Working WITH the AI Team:**
+
+When you send a message, `chat/send` returns a message ID. Use this to track responses:
+
+```bash
+# 1. Send message (captures the JSON response with messageId)
+RESPONSE=$(./jtag chat/send --room="general" --message="Deployed new tool error visibility fix. Can you see errors clearly now?")
+
+# 2. Extract message ID (using jq if available, or manual)
+MESSAGE_ID=$(echo "$RESPONSE" | jq -r '.shortId')
+echo "My message ID: $MESSAGE_ID"
+
+# 3. Wait for AI responses (they typically respond in 5-10 seconds)
+sleep 10
+
+# 4. Check their responses
+./jtag chat/export --room="general" --limit=20
+
+# 5. Reply to specific AI feedback
+./jtag chat/send --room="general" --replyToId="<their-message-id>" --message="Good catch! Let me fix that..."
+```
+
+**CRITICAL**: Don't just broadcast to the AI team - WORK WITH THEM. Use their feedback, reply to their questions, iterate based on what they're saying. The chat export shows message IDs as `#abcd123` - use those to reply.
+
 ### Debug Commands
 ```bash
 ./jtag debug/logs --tailLines=50 --includeErrorsOnly=true
@@ -644,7 +874,7 @@ Local PersonaUsers (Helper AI, Teacher AI, CodeReview AI, Local Assistant, and 5
 
 ```bash
 # STEP 1: Ask a question in the general room (no room ID needed!)
-./jtag debug/chat-send --room="general" --message="How should I implement connection pooling for websockets?"
+./jtag chat/send --room="general" --message="How should I implement connection pooling for websockets?"
 
 # STEP 2: Wait 5-10 seconds for responses
 
@@ -658,7 +888,7 @@ Local PersonaUsers (Helper AI, Teacher AI, CodeReview AI, Local Assistant, and 5
 
 ```bash
 # 1. Send your question and capture the message ID
-MESSAGE_ID=$(./jtag debug/chat-send --room="general" --message="What's the best way to handle rate limiting?" | jq -r '.messageId')
+MESSAGE_ID=$(./jtag chat/send --room="general" --message="What's the best way to handle rate limiting?" | jq -r '.messageId')
 
 # 2. Wait for AI responses (they respond within 5-10 seconds)
 sleep 10
@@ -1043,4 +1273,6 @@ Commands.execute() and Events.subscribe()/emit() - the two primitives everything
 ---
 
 **File reduced from 61k to ~20k characters**
-- if you only edit a test, and not the api itself, you don't need to redeploy with npm start, just edit and test again e.g npx tsx tests/integration/genome-fine-tuning-e2e.test.ts
+- if you only edit a test, and not the api itself, you don't need to redeploy with npm start, just edit and test again e.g npx tsx tests/integration/genome-fine-tuning-e2e.test.ts
+- need to remember to npm run build:ts before deploying with npm start, just to make sure there's no compilation issues
+- ./jtag chat/export --room="general" --limit=30 will let you see ai opinions after chat/send to ask