# Operations Runbook — עוזר משפטי > תוכן תפעולי-עומק שהוצא מ-[`CLAUDE.md`](../CLAUDE.md) כדי לרזות את ההקשר הנטען בכל סשן (TaskMaster #107.1). > ה-CLAUDE.md מחזיק את **הכללים הקריטיים בקצרה**; כאן נמצאים הפרטים המלאים, הפקודות, וטבלאות-הייחוס. > כשעובדים על Deploy, Paperplip-ops, או adapters — לקרוא את הסעיף הרלוונטי כאן. --- ## שרת Nautilus (158.178.131.193) | שירות | תפקיד | כתובת | |-------|--------|-------| | Coolify | ניהול containers | `http://158.178.131.193:8000` | | PostgreSQL + pgvector | בסיס נתונים ראשי | `legal-ai-postgres` (`localhost:5433`, user `legal_ai`) | | Redis | תור משימות | `legal-ai-redis` | | Gitea | מאגר קוד | `gitea.nautilus.marcusgroup.org/ezer-mishpati` | | ezer-mishpati-web | ממשק העלאת מסמכים (Docker/Coolify) | `legal-ai.nautilus.marcusgroup.org` | | Paperclip | סוכן AI — מריץ Claude Code agents (pm2, מקומי) | `localhost:3100` | | legal-chat-service | גשר claude CLI לטאב הצ'אט ב-/training (pm2, loopback) | `127.0.0.1:8770` | | Infisical | ניהול סודות | `secret.dev.marcus-law.co.il` | --- ## ארכיטקטורת Deploy — חובה לקרוא שלושה מודלי-הרצה דרים יחד. ערבוב ביניהם הוא הטעות הנפוצה ביותר. ### עוזר משפטי (Legal-AI) — Docker container דרך Coolify - UUID: `gyjo0mtw2c42ej3xxvbz8zio` (build_pack: `dockerimage`, **לא** `dockerfile`) - שינוי קוד ב-`web/` או `web-ui/` **לא נכנס לתוקף** עד ש: 1. עושים `git commit` + `git push origin main` 2. Gitea Actions בונה image → דוחף ל-registry → מפעיל redeploy ב-Coolify (`mcp__coolify__deploy`) 3. ממתינים ~2-4 דקות לבנייה - **אסור** לנסות להריץ uvicorn / `next dev` מקומית — אין סביבת Python על המכונה - ה-container מריץ Next.js (`:3000`, חשוף) + FastAPI (`:8000`, פנימי) - בדיקה: `curl https://legal-ai.nautilus.marcusgroup.org/api/health` - runbook מלא של ה-pipeline: `~/CI-CD-MIGRATION-GUIDE.md` ### Paperclip — מקומית דרך pm2 - פורט: `localhost:3100`, DB: `localhost:54329` (Postgres embedded) - שינויי קוד נכנסים לתוקף אחרי `pm2 restart paperclip` - **אין צורך ב-Docker או Coolify** (מיגרציה ל-Coolify נוסתה 2026-04-04 והוחזרה 2026-04-08) - תרגום/RTL: `~/.paperclip/hebrew/` → `bash ~/.paperclip/hebrew/apply-hebrew.sh && pm2 restart paperclip` ### legal-chat-service — מקומית דרך pm2 (מאפריל 2026) - פורט: `127.0.0.1:8770` (loopback בלבד) - שירות aiohttp קצר שעוטף את `claude` CLI ב-streaming + session continuation, ומשרת את הטאב "שיחה" בדף `/training`. הקונטיינר משדל אליו proxy דרך `host.docker.internal:8770`. - קוד: [`mcp-server/src/legal_mcp/chat_service/`](../mcp-server/src/legal_mcp/chat_service/) - התקנה: `pm2 start /home/chaim/legal-ai/scripts/legal-chat-service.config.cjs && pm2 save` - בריאות: `curl http://127.0.0.1:8770/health` → `{"ok":true,...}` - שינויי קוד: `pm2 restart legal-chat-service` - **אפס עלות API** — claude CLI משתמש ב-claude.ai subscription של chaim. הנחת היסוד של `claude_session.py` (claude CLI מקומי בלבד) נשמרת. - Coolify dependency: ה-Service Definition של legal-ai חייב להכיל `extra_hosts: host.docker.internal:host-gateway` (אחרת ה-proxy יקבל ConnectError). --- ## מבנה תיקיות ``` /home/chaim/legal-ai/ ├── CLAUDE.md ← אינדקס דק (כללים קריטיים + מצביעים) ├── docs/operations-runbook.md ← הקובץ הזה (עומק תפעולי) ├── Dockerfile ← Docker build ├── docs/ ← תיעוד + לקחים │ ├── architecture.md ארכיטקטורה │ ├── block-schema.md 12 בלוקים (המסמך החשוב ביותר) │ ├── migration-plan.md תוכנית מעבר vault → DB │ ├── legal-decision-lessons.md לקחים מ-3 החלטות │ └── memory.md הקשר כללי — skills, פרויקטים ├── skills/ ← כלי עבודה ומדריכים │ ├── decision/ מדריך סגנון + references + 12 בלוקים │ ├── assistant/ קטלוג מסמכים │ ├── docx/ עיצוב DOCX │ ├── dafna-decision-template/ export DOCX לפי תבנית Word של דפנה │ └── new-company-setup/ blueprint הוספת חברה חדשה ├── .claude/ │ └── agents/ ← הוראות סוכנים + HEARTBEAT.md (symlinks ב-Paperclip) │ ├── HEARTBEAT.md checklist הפעלה משותף לכל הסוכנים │ ├── legal-ceo.md תזמורן + בקרת זרימה │ ├── legal-writer.md כתיבת בלוקים בסגנון דפנה │ ├── legal-analyst.md ניתוח משפטי + חילוץ טענות │ ├── legal-researcher.md חיפוש תקדימים │ ├── legal-qa.md 7 שערי איכות │ ├── legal-proofreader.md תיקון OCR │ ├── legal-exporter.md ייצוא DOCX סופי │ └── hermes-curator.md סוכן Hermes לניתוח סגנון post-export ├── data/ │ ├── training/ ← 4 החלטות לאימון (DOCX) │ ├── exports/ ← טיוטות DOCX מיוצאות │ └── cases/{case-number}/ ← תיקי עררים (מבנה שטוח, סטטוס ב-DB) ├── web/ ← FastAPI backend (Python): 75+ API endpoints │ ├── app.py ← API ראשי │ ├── paperclip_api.py ← אינטגרציית Paperclip: `pc_request()` + `emit_case_status_webhook()` │ ├── paperclip_client.py ← legacy client (ישן — השתמש ב-paperclip_api.py) │ └── gitea_client.py ← אינטגרציית Gitea ├── web-ui/ ← Next.js frontend (TypeScript/React): ממשק המשתמש │ └── next.config.ts ← proxy: /api/* → FastAPI :8000 ├── mcp-server/ ← MCP server + services + tools ├── adapters/ ← Paperclip external adapters │ └── deepseek-paperclip-adapter/ ← `deepseek_local` (Hermes-pinned ל-DeepSeek profile) └── scripts/ ← סקריפטים וכלי עזר (ראה scripts/SCRIPTS.md) └── .archive/ ← סקריפטים שהושלמו (לא להריץ) ``` --- ## Paperclip — כללי אינטגרציה (פירוט מלא) > הכללים הקריטיים בתמצית נמצאים ב-[`CLAUDE.md`](../CLAUDE.md). כאן הפירוט המלא, הדוגמאות, וה-"למה". ### Wakeup API — תמיד דרך API, לעולם לא דרך DB - **הנתיב הנכון**: `POST /api/agents/{agent-id}/wakeup` (לא `/wake`!) - **⚠️ אסור**: `INSERT INTO agent_wakeup_requests` ישירות — זה יוצר רק רשומה בלי `heartbeat_run`, והסוכן **לא יתעורר לעולם** - **⚠️ חובה לשלוח `payload` עם `issueId`** — בלי זה הסוכן מתעורר בלי הקשר (בלי תיק, בלי issue, בלי cwd נכון) - דוגמה נכונה: ```json {"source": "automation", "triggerDetail": "system", "reason": "...", "payload": {"issueId": "...", "mutation": "comment", "commentId": "..."}} ``` - **Board API Key**: שמור ב-DB (`board_api_keys`), auth: `Authorization: Bearer pbk_...` ### ניתוב comments דרך CEO - כשמשתמש כותב תגובה על issue ב-Paperclip, הפלאגין (`plugin-legal-ai`) מעיר את ה-CEO דרך `ctx.agents.invoke()` - ה-CEO קורא את ה-comment, מחליט על ניתוב, ויוצר issue לסוכן המתאים - כל הסוכנים חייבים לקרוא comments אחרונים לפני שהם מתחילים לעבוד (HEARTBEAT שלבים 2b-2c) ### קריאות API — תמיד דרך helper, לעולם לא `curl` ישיר - **bash (סוכנים):** `~/legal-ai/scripts/pc.sh [BODY_JSON]` — מוסיף Authorization, X-Paperclip-Run-Id, Content-Type, base URL. ראה `HEARTBEAT.md §0`. - **Python (FastAPI):** `from web.paperclip_api import pc_request; await pc_request("POST", "/api/...", json={...})` — שימוש ב-board API key. - **אסור** `curl ... $PAPERCLIP_API_URL` ישיר ב-bash; **אסור** `httpx.AsyncClient` ישיר ל-Paperclip ב-Python. - **למה:** ה-skill הרשמי דורש `X-Paperclip-Run-Id` בכל קריאה משנה issue. אצלנו ה-audit trail עבד ממילא דרך JWT claims (`runId: runIdHeader || claims.run_id`), אבל ה-helper מבטיח עקביות + תאימות ל-board API keys (long-lived) שלא נושאות JWT claims. ### Cross-company agent sync — אחרי כל שינוי הגדרות - יש 14 סוכנים = 7 × 2 חברות (CMP=1xxx, CMPA=8xxx). Paperclip מחייב `agents.company_id NOT NULL` — אין shared agents. - **Master = CMP (1xxx)**, **Mirror = CMPA (8xxx)**. - אחרי כל שינוי ב-`adapter_config`, `runtime_config`, `budget_monthly_cents`, או skills של סוכן ב-master (UI, SQL, או API), **חובה להריץ:** ```bash PAPERCLIP_BOARD_API_KEY=$(...infisical...) \ python ~/legal-ai/scripts/sync_agents_across_companies.py --verify # לבדיקה PAPERCLIP_BOARD_API_KEY=$(...) \ python ~/legal-ai/scripts/sync_agents_across_companies.py --apply # לסנכרן ``` - הסקריפט מסנן local skills שלא קיימים ב-CMPA (מציג אזהרה), משתמש ב-API (לא DB ישיר), יוצר revisions, idempotent. - שאלות ה-skill הרשמי של Paperclip — `paperclip` skill תחת `paperclipai/paperclip`. ### Webhook יוצא — עדכון סטטוס תיק לפלאגין כשסטטוס תיק משתנה דרך `PUT /api/cases/{case_number}`, הבקאנד שולח webhook אסינכרוני לפלאגין: ``` PUT /api/cases/{case_number} → emit_case_status_webhook() [BackgroundTask] → POST /api/plugins/marcusgroup.legal-ai/webhooks/case-status → plugin-legal-ai/onWebhook() → comment בעברית על issue + CEO wakeup (כשסטטוס = qa_failed) ``` - הקוד ב-`web/paperclip_api.py` (`emit_case_status_webhook`), fire-and-forget, timeout 5s - הפלאגין שומר idempotency key ב-state עם TTL 5 דקות למניעת spam על retry - `GET /api/cases/stale?days=N` — תיקים שלא עודכנו N ימים; מוחרגים: `new`, `final`, `exported` - `GET /api/chair-feedback/weekly-summary` — סיכום פידבק YU"R לשבוע האחרון ### Scheduled Jobs (plugin-legal-ai) | Job | לוח זמנים | מה עושה | |-----|-----------|---------| | `stale-case-reminder` | יומי 08:00 | שולח comment אזהרה על תיקים תקועים >3 ימים | | `weekly-feedback-analysis` | ראשון 19:00 | מעיר CEO לניתוח פידבק YU"R ועדכון `docs/legal-decision-lessons.md` | | `sync-case-status` | כל 30 דק' | מסנכרן סטטוסי תיקים בין legal-ai ל-Paperclip | CEO שמתעורר מ-`weekly-feedback-job` כותב לקובץ בלבד — **אין לו issueId, אל תנסה לפרסם comment או לסגור issue**. ### External adapters — `deepseek_local` - מיקום ה-package: [`adapters/deepseek-paperclip-adapter/`](../adapters/deepseek-paperclip-adapter/) (לא ב-`node_modules`). - רישום ב-Paperclip: רשומה ב-`~/.paperclip/adapter-plugins.json` (נטען אוטומטית ב-startup דרך `buildExternalAdapters`). אין צורך בעריכת `node_modules`. - **מה ה-adapter עושה**: spawnל-`hermes chat` עם `HERMES_HOME=/home/chaim/.hermes/profiles/deepseek` כך שה-CLI טוען את `config.yaml` (`base_url=https://api.deepseek.com/v1`, `provider=custom`, `key_env=DEEPSEEK_API_KEY`) ואת `.env` (שמכיל את ה-key). - **מודלים זמינים** (lookup ב-DeepSeek `/v1/models`): `deepseek-v4-pro` (default), `deepseek-v4-flash`. יופיעו כדרופ-דאון ב-UI. - **התקנה מחדש / עדכון**: `curl -X POST -H "Authorization: Bearer pcapi_legal_install_key_2026" -H "Content-Type: application/json" -d '{"packageName":"/home/chaim/legal-ai/adapters/deepseek-paperclip-adapter","isLocalPath":true}' http://localhost:3100/api/adapters/install`. לעדכון hot — `POST /api/adapters/deepseek_local/reload`. - **⚠ Cross-company sync**: `sync_agents_across_companies.py` **מדלג** על סוכנים עם `adapter_type` שונה בין CMP ל-CMPA. כשעוברים סוכן ל-`deepseek_local` חובה להחיל ידנית בשתי החברות לפני sync. - **תוספת adapters עתידיים** (OpenAI ישיר, Anthropic ישיר, וכו'): אותו דפוס. ה-package הראשי חייב לייצא `createServerAdapter()` שמחזיר `{ type, label, models, agentConfigurationDoc, execute, testEnvironment, sessionCodec, listSkills, syncSkills, ... }`. ראה את [`adapters/deepseek-paperclip-adapter/dist/index.js`](../adapters/deepseek-paperclip-adapter/dist/index.js) כתבנית. ### External adapters — Hermes Curator (`curator-cmp` / `curator-cmpa`) - פרופילי Hermes נפרדים לסוכן `hermes-curator` — מנתח החלטות סופיות ומציע עדכוני SKILL.md/lessons.md - מיקום: `~/.hermes/profiles/curator-cmp/` + `~/.hermes/profiles/curator-cmpa/` - מופעל אחרי export סופי; אינו מעדכן קבצים ישירות - **תהליך אישור הצעות:** הצעות ה-curator מגיעות כ-comment ב-Paperclip → חיים בוחן ומאשר ידנית → commits ל-`SKILL.md` ו-`docs/legal-decision-lessons.md` --- ## הערות יו"ר (Chair Feedback) מנגנון לתיעוד הערות דפנה על טיוטות: - **DB**: טבלת `chair_feedback` (case_id, block_id, feedback_text, category, lesson_extracted) - **API**: `GET/POST /api/feedback`, `PATCH /api/feedback/{id}/resolve` - **MCP tools**: `record_chair_feedback`, `list_chair_feedback` - **UI**: דף ניהול ב-`/feedback` (ב-Next.js) - **קטגוריות**: missing_content, wrong_tone, wrong_structure, factual_error, style, other --- ## ניהול משימות — TaskMaster AI (פירוט) - קובץ המשימות הקנוני: `~/legal-ai/.taskmaster/tasks/tasks.json` (יחסי ל-project root, **לא** `~/.taskmaster/tasks/tasks.json`). מכיל את כל ה-tags של legal-ai (`master`, `legal-ai`). - פקודות עיקריות: `get_tasks`, `next_task`, `add_task`, `update_task`, `expand_task` - לפני התחלת עבודה → `next_task`; אחרי סיום → `update_task` עם status=done; משימה מורכבת → `expand_task` - **⚠️ מלכוד cwd ב-CLI:** הדגל `--tag` בוחר קבוצה לוגית *בתוך* הקובץ — הוא **לא** בוחר לאיזה `tasks.json` לכתוב. ה-CLI מאתר את הקובץ לפי ה-cwd. תמיד `cd ~/legal-ai` לפני `task-master add-task` או כל פקודה משנה, ואז אמת ב-MCP `get_tasks`. כשלא בטוחים — לערוך את `~/legal-ai/.taskmaster/tasks/tasks.json` ישירות.