Fix agent wakeup: /wake → /wakeup, remove broken DB fallback

The agents used /api/agents/{id}/wake (404) with a fallback of INSERT
INTO agent_wakeup_requests. The DB insert creates only the wakeup
record without a heartbeat_run, so the Paperclip dispatcher never
processes it — agents get stuck in queued forever.

Fix:
- All agents: /wake → /wakeup (correct Paperclip API endpoint)
- Remove all DB INSERT fallbacks, replace with warning
- Document the rule in CLAUDE.md: always API, never DB insert
- Save to memory for future conversations

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

.claude/agents/HEARTBEAT.md

@@ -106,22 +106,10 @@ curl -s -X PATCH -H "Authorization: Bearer $PAPERCLIP_API_KEY" \
 ```bash
 curl -s -X POST -H "Authorization: Bearer $PAPERCLIP_API_KEY" \
   -H "Content-Type: application/json" \
-  "$PAPERCLIP_API_URL/api/agents/752cebdd-6748-4a04-aacd-c7ab0294ef33/wake" \
+  "$PAPERCLIP_API_URL/api/agents/752cebdd-6748-4a04-aacd-c7ab0294ef33/wakeup" \
   -d '{"reason": "סוכן [שמך] סיים משימה [issue-id] בסטטוס [done/blocked]. נדרשת בדיקה והחלטה על הצעד הבא."}'
 ```
-אם ה-API הזה לא עובד, השתמש ב-DB ישירות:
+**⚠️ אסור להשתמש ב-INSERT INTO agent_wakeup_requests ישירות!** הכנסה ישירה ל-DB יוצרת רק את הבקשה בלי heartbeat_run — והסוכן לא יתעורר לעולם. **תמיד להשתמש ב-API בלבד.**
-```bash
-PGPASSWORD="paperclip" psql -h 127.0.0.1 -p 54329 -U paperclip -d paperclip -c "
-INSERT INTO agent_wakeup_requests (company_id, agent_id, source, reason, status, requested_by_actor_type)
-VALUES (
-  (SELECT company_id FROM agents WHERE id = '$PAPERCLIP_AGENT_ID'),
-  '752cebdd-6748-4a04-aacd-c7ab0294ef33',
-  'agent_completion',
-  'סוכן סיים משימה — נדרשת בדיקה והחלטה על הצעד הבא',
-  'queued',
-  'agent'
-);"
-```
 
 ## 5. התראת מייל — כשנדרשת תשובה אנושית
 

.claude/agents/legal-analyst.md

@@ -210,21 +210,11 @@ FROM documents d WHERE d.case_id = '{case_id}' AND d.doc_type IN ('appeal', 'res
 ```bash
 curl -s -X POST -H "Authorization: Bearer $PAPERCLIP_API_KEY" \
   -H "Content-Type: application/json" \
-  "$PAPERCLIP_API_URL/api/agents/752cebdd-6748-4a04-aacd-c7ab0294ef33/wake" \
+  "$PAPERCLIP_API_URL/api/agents/752cebdd-6748-4a04-aacd-c7ab0294ef33/wakeup" \
   -d '{"reason": "מנתח משפטי סיים משימה [issue-id] בסטטוס [done/blocked]"}'
 ```
 אם ה-API לא עובד:
-```bash
+**⚠️ אסור להשתמש ב-INSERT INTO agent_wakeup_requests ישירות!** הכנסה ישירה ל-DB יוצרת רק את הבקשה בלי heartbeat_run — והסוכן לא יתעורר לעולם. **תמיד להשתמש ב-API בלבד.**
-PGPASSWORD="paperclip" psql -h 127.0.0.1 -p 54329 -U paperclip -d paperclip -c "
-INSERT INTO agent_wakeup_requests (company_id, agent_id, source, reason, status, requested_by_actor_type)
-VALUES (
-  (SELECT company_id FROM agents WHERE id = '\$PAPERCLIP_AGENT_ID'),
-  '752cebdd-6748-4a04-aacd-c7ab0294ef33',
-  'agent_completion',
-  'מנתח משפטי סיים משימה — נדרשת בדיקה',
-  'queued', 'agent'
-);"
-```
 
 **אם בדיקות שלב 6 נכשלו** — סטטוס issue = "blocked", פרסם comment עם פירוט מה נכשל, שלח מייל לחיים.
 
@@ -379,7 +369,7 @@ X שאלות עומדות להכרעה:
    ```bash
    curl -s -X POST -H "Authorization: Bearer $PAPERCLIP_API_KEY" \
      -H "Content-Type: application/json" \
-     "$PAPERCLIP_API_URL/api/agents/752cebdd-6748-4a04-aacd-c7ab0294ef33/wake" \
+     "$PAPERCLIP_API_URL/api/agents/752cebdd-6748-4a04-aacd-c7ab0294ef33/wakeup" \
      -d '{"reason": "מנתח משפטי סיים העמקת ניתוח (pass 2) [issue-id] בסטטוס [done/blocked]"}'
    ```
    אם ה-API לא עובד:

.claude/agents/legal-exporter.md

@@ -78,21 +78,11 @@ tools:
 ```bash
 curl -s -X POST -H "Authorization: Bearer $PAPERCLIP_API_KEY" \
   -H "Content-Type: application/json" \
-  "$PAPERCLIP_API_URL/api/agents/752cebdd-6748-4a04-aacd-c7ab0294ef33/wake" \
+  "$PAPERCLIP_API_URL/api/agents/752cebdd-6748-4a04-aacd-c7ab0294ef33/wakeup" \
   -d '{"reason": "מייצא טיוטה סיים משימה [issue-id] בסטטוס [done/blocked]"}'
 ```
 אם ה-API לא עובד:
-```bash
+**⚠️ אסור להשתמש ב-INSERT INTO agent_wakeup_requests ישירות!** הכנסה ישירה ל-DB יוצרת רק את הבקשה בלי heartbeat_run — והסוכן לא יתעורר לעולם. **תמיד להשתמש ב-API בלבד.**
-PGPASSWORD="paperclip" psql -h 127.0.0.1 -p 54329 -U paperclip -d paperclip -c "
-INSERT INTO agent_wakeup_requests (company_id, agent_id, source, reason, status, requested_by_actor_type)
-VALUES (
-  (SELECT company_id FROM agents WHERE id = '\$PAPERCLIP_AGENT_ID'),
-  '752cebdd-6748-4a04-aacd-c7ab0294ef33',
-  'agent_completion',
-  'מייצא טיוטה סיים משימה — נדרשת בדיקה',
-  'queued', 'agent'
-);"
-```
 
 ## כללים קריטיים
 

.claude/agents/legal-proofreader.md

@@ -62,60 +62,4 @@ tools:
 1. **גיבוי**: העתק את הקובץ המקורי מ-`extracted/` לתיקיית `documents/backup/` עם סיומת `.pre-proofread.txt`
 2. **כתוב** את הגרסה המתוקנת לתיקיית `documents/proofread/` (עם אותו שם קובץ כמו ב-`extracted/`)
 3. עדכן את מסד הנתונים — שנה `extraction_status` ל-`proofread`:
-```bash
+**⚠️ אסור להשתמש ב-INSERT INTO agent_wakeup_requests ישירות!** הכנסה ישירה ל-DB יוצרת רק את הבקשה בלי heartbeat_run — והסוכן לא יתעורר לעולם. **תמיד להשתמש ב-API בלבד.**
-PGPASSWORD="${PGPASSWORD:-$(grep DB_PASSWORD /home/chaim/.env | cut -d= -f2)}" \
-psql -h localhost -p 5432 -U "${DB_USER:-legal_ai}" -d "${DB_NAME:-legal_ai}" \
--c "UPDATE documents SET extraction_status = 'proofread', extracted_text = pg_read_file('/path/to/file.txt') WHERE id = '{doc_id}';"
-```
-אם עדכון DB לא אפשרי, עדכן רק את הקובץ ודווח.
-
-### שלב 5: עדכון סטטוס ודיווח
-
-1. **עדכן סטטוס**: `case_update(case_number, status='proofread')`
-
-2. פרסם comment ב-Paperclip עם:
-```
-## דוח הגהת מסמכים — תיק {case_number}
-
-### סיכום
-- **מסמכים שנבדקו:** {count}
-- **מסמכים שתוקנו:** {fixed_count}
-- **סה"כ תיקונים:** {total_fixes}
-
-### פירוט לכל מסמך
-| מסמך | ראשי תיבות | שגיאות OCR | הערות |
-|------|------------|-----------|-------|
-| {title} | {abbr_count} | {ocr_count} | {notes} |
-
-### מקומות לא ברורים
-- {document}: סעיף {n} — [?] "{problematic_text}"
-```
-
-## כללים קריטיים
-
-1. **אל תשנה תוכן משפטי** — רק תיקוני OCR. אם מילה נראית מוזרה אבל היא מונח משפטי — אל תגע
-2. **אל תדרוס בלי גיבוי** — תמיד העתק ל-`backup/` לפני שינוי
-3. **ראשי תיבות ארוכים קודם** — `נתבייע` (5 תווים) לפני `עייד` (3 תווים)
-4. **דווח מקומות מסופקים** — סמן `[?]` ותן לאדם להחליט
-5. **אל תמציא טקסט** — אם חסר משהו, סמן `[...]` ואל תנחש
-6. **קרא את כל המסמך** — לפעמים הקשר ממסמך שלם עוזר להבין מילה שבורה
-
-### העֵר את העוזר המשפטי (CEO) — חובה!
-```bash
-curl -s -X POST -H "Authorization: Bearer $PAPERCLIP_API_KEY" \
-  -H "Content-Type: application/json" \
-  "$PAPERCLIP_API_URL/api/agents/752cebdd-6748-4a04-aacd-c7ab0294ef33/wake" \
-  -d '{"reason": "מגיה מסמכים סיים משימה [issue-id] בסטטוס [done/blocked]"}'
-```
-אם ה-API לא עובד:
-```bash
-PGPASSWORD="paperclip" psql -h 127.0.0.1 -p 54329 -U paperclip -d paperclip -c "
-INSERT INTO agent_wakeup_requests (company_id, agent_id, source, reason, status, requested_by_actor_type)
-VALUES (
-  (SELECT company_id FROM agents WHERE id = '\$PAPERCLIP_AGENT_ID'),
-  '752cebdd-6748-4a04-aacd-c7ab0294ef33',
-  'agent_completion',
-  'מגיה מסמכים סיים משימה — נדרשת בדיקה',
-  'queued', 'agent'
-);"
-```

.claude/agents/legal-qa.md

@@ -109,18 +109,8 @@ tools:
 ```bash
 curl -s -X POST -H "Authorization: Bearer $PAPERCLIP_API_KEY" \
   -H "Content-Type: application/json" \
-  "$PAPERCLIP_API_URL/api/agents/752cebdd-6748-4a04-aacd-c7ab0294ef33/wake" \
+  "$PAPERCLIP_API_URL/api/agents/752cebdd-6748-4a04-aacd-c7ab0294ef33/wakeup" \
   -d '{"reason": "בודק איכות סיים משימה [issue-id] בסטטוס [done/blocked]"}'
 ```
 אם ה-API לא עובד:
-```bash
+**⚠️ אסור להשתמש ב-INSERT INTO agent_wakeup_requests ישירות!** הכנסה ישירה ל-DB יוצרת רק את הבקשה בלי heartbeat_run — והסוכן לא יתעורר לעולם. **תמיד להשתמש ב-API בלבד.**
-PGPASSWORD="paperclip" psql -h 127.0.0.1 -p 54329 -U paperclip -d paperclip -c "
-INSERT INTO agent_wakeup_requests (company_id, agent_id, source, reason, status, requested_by_actor_type)
-VALUES (
-  (SELECT company_id FROM agents WHERE id = '\$PAPERCLIP_AGENT_ID'),
-  '752cebdd-6748-4a04-aacd-c7ab0294ef33',
-  'agent_completion',
-  'בודק איכות סיים משימה — נדרשת בדיקה',
-  'queued', 'agent'
-);"
-```

.claude/agents/legal-researcher.md

@@ -98,21 +98,11 @@ python3 /home/chaim/legal-ai/scripts/notify.py \
 ```bash
 curl -s -X POST -H "Authorization: Bearer $PAPERCLIP_API_KEY" \
   -H "Content-Type: application/json" \
-  "$PAPERCLIP_API_URL/api/agents/752cebdd-6748-4a04-aacd-c7ab0294ef33/wake" \
+  "$PAPERCLIP_API_URL/api/agents/752cebdd-6748-4a04-aacd-c7ab0294ef33/wakeup" \
   -d '{"reason": "חוקר תקדימים סיים משימה [issue-id] בסטטוס [done/blocked]"}'
 ```
 אם ה-API לא עובד:
-```bash
+**⚠️ אסור להשתמש ב-INSERT INTO agent_wakeup_requests ישירות!** הכנסה ישירה ל-DB יוצרת רק את הבקשה בלי heartbeat_run — והסוכן לא יתעורר לעולם. **תמיד להשתמש ב-API בלבד.**
-PGPASSWORD="paperclip" psql -h 127.0.0.1 -p 54329 -U paperclip -d paperclip -c "
-INSERT INTO agent_wakeup_requests (company_id, agent_id, source, reason, status, requested_by_actor_type)
-VALUES (
-  (SELECT company_id FROM agents WHERE id = '\$PAPERCLIP_AGENT_ID'),
-  '752cebdd-6748-4a04-aacd-c7ab0294ef33',
-  'agent_completion',
-  'חוקר תקדימים סיים משימה — נדרשת בדיקה',
-  'queued', 'agent'
-);"
-```
 
 ## כללים
 - **דיוק** — ציין מספרי סעיפים, תאריכים, שמות שופטים

.claude/agents/legal-writer.md

@@ -160,21 +160,11 @@ case_update(case_number, status="drafted")
 ```bash
 curl -s -X POST -H "Authorization: Bearer $PAPERCLIP_API_KEY" \
   -H "Content-Type: application/json" \
-  "$PAPERCLIP_API_URL/api/agents/752cebdd-6748-4a04-aacd-c7ab0294ef33/wake" \
+  "$PAPERCLIP_API_URL/api/agents/752cebdd-6748-4a04-aacd-c7ab0294ef33/wakeup" \
   -d '{"reason": "כותב החלטה סיים משימה [issue-id] בסטטוס [done/blocked]"}'
 ```
 אם ה-API לא עובד:
-```bash
+**⚠️ אסור להשתמש ב-INSERT INTO agent_wakeup_requests ישירות!** הכנסה ישירה ל-DB יוצרת רק את הבקשה בלי heartbeat_run — והסוכן לא יתעורר לעולם. **תמיד להשתמש ב-API בלבד.**
-PGPASSWORD="paperclip" psql -h 127.0.0.1 -p 54329 -U paperclip -d paperclip -c "
-INSERT INTO agent_wakeup_requests (company_id, agent_id, source, reason, status, requested_by_actor_type)
-VALUES (
-  (SELECT company_id FROM agents WHERE id = '\$PAPERCLIP_AGENT_ID'),
-  '752cebdd-6748-4a04-aacd-c7ab0294ef33',
-  'agent_completion',
-  'כותב החלטה סיים משימה — נדרשת בדיקה',
-  'queued', 'agent'
-);"
-```
 
 **אם לא תעדכן סטטוס ל-drafted — בודק האיכות לא יוכל לרוץ!**
 

CLAUDE.md

@@ -103,6 +103,21 @@
 
 ---
 
+## Paperclip — כללי אינטגרציה קריטיים
+
+### Wakeup API — תמיד דרך API, לעולם לא דרך DB
+- **הנתיב הנכון**: `POST /api/agents/{agent-id}/wakeup` עם `{"source": "...", "reason": "..."}`
+- **⚠️ אסור**: `INSERT INTO agent_wakeup_requests` ישירות — זה יוצר רק את הרשומה בטבלה בלי `heartbeat_run`, והסוכן **לא יתעורר לעולם**
+- **הסיבה**: ה-dispatcher של Paperclip מעבד `heartbeat_runs`, לא `agent_wakeup_requests`. רק ה-API יוצר את שניהם אטומית
+- **Board API Key**: שמור ב-DB (`board_api_keys`), מאפשר גישה ל-API מ-CLI
+
+### ניתוב comments דרך CEO
+- כשמשתמש כותב תגובה על issue ב-Paperclip, הפלאגין (`plugin-legal-ai`) מעיר את ה-CEO דרך `ctx.agents.invoke()`
+- ה-CEO קורא את ה-comment, מחליט על ניתוב, ויוצר issue לסוכן המתאים
+- כל הסוכנים חייבים לקרוא comments אחרונים לפני שהם מתחילים לעבוד (HEARTBEAT שלבים 2b-2c)
+
+---
+
 ## עקרונות כתיבה קריטיים
 
 1. **"מבחן השופט"** — כל החלטה חייבת להיות קריאה לשופט שלא מכיר את התיק