## 4. L3 Provider Chain | Provider order | Source | Runtime details | |---|---|---| | **Codex CLI** | `/var/www/syncrovanis/engine/lib/llm-classify.sh:128-133` | First choice, `gpt-5.4-mini`, reasoning `low`, timeout `8s` | | **Gemini CLI** | `/var/www/syncrovanis/engine/lib/llm-classify.sh:134-139` | Second choice, `gemini-2.5-flash`, `-s false`, `--allowed-mcp-server-names none`, timeout `20s` | | **Copilot CLI** | `/var/www/syncrovanis/engine/lib/llm-classify.sh:141-145` | Last resort, explicit `--model "$_l3_model"` and reasoning effort, timeout `30s` | | **Provider cooldown** | `/var/www/syncrovanis/engine/lib/llm-classify.sh:27-42` | Failed providers are skipped for 10 minutes | Provider flow: `Codex CLI -> Gemini CLI -> Copilot CLI` --- ## 5. Known Gotchas & Fixes **SYNCROVANIS-01: L3 Classification Was Completely Non-Functional** - **Symptom:** L3 consistently logged `miss(no-result)` and never enriched high-level prompts. - **Cause:** Unsupported Codex model pinning, Gemini sandbox/MCP startup cost, too-short timeouts, and wrong provider order. - **Fix:** Keep the current chain and flags in `/var/www/syncrovanis/engine/lib/llm-classify.sh:7-12` and `/var/www/syncrovanis/engine/lib/llm-classify.sh:128-145`. **SYNCROVANIS-02: Shared Workspace Context File Caused Cross-Session Leakage** - **Symptom:** One session received another chat's context. - **Cause:** All sessions wrote the same workspace file while global config used to `@-include` it. - **Fix:** Treat workspace files as fallback/audit only; runtime delivery is stdout-first. **SYNCROVANIS-03: Domain Fallback Could Prefer Generic Noise Over Real Entities** - **Symptom:** Specific prompts like service names returned generic, irrelevant context. - **Cause:** Generic domain-term fallback ran before entity lookup. - **Fix:** Preserve entity-first fallback in `/var/www/syncrovanis/engine/hooks/user-prompt-context-engine.sh` before generic term search. **SYNCROVANIS-04: Bash State Bugs Can Fail The Hook Silently** - **Symptom:** No context is delivered and the hook exits quietly. - **Cause:** `set -u` plus unbound temp vars or invalid `local` placement in shell code. - **Fix:** Keep hook-side shell changes minimal and verify with context archive + JSONL logging after edits. **SYNCROVANIS-05: Symlink-Based Hook Launches Can Misreport Runtime Version** - **Symptom:** Banner shows `v0.0.0` or another stale version. - **Cause:** `dirname "${BASH_SOURCE[0]}"` resolves the hook symlink, not the real engine path. - **Fix:** Use `readlink -f` before resolving `VERSION`; see `/var/www/syncrovanis/engine/hooks/user-prompt-context-engine.sh:20-22`. **SYNCROVANIS-06: `save_state()` Could Re-Enable L3 And Burn Extra Quota** - **Symptom:** A later prompt in the same session escalates to L3 again after an earlier L3 hit. - **Cause:** `save_state()` used to overwrite `l3_used` while writing the next classification. - **Fix:** Preserve the previous sticky flag at `/var/www/syncrovanis/engine/lib/state.sh:57-64`. **SYNCROVANIS-07: Repeated Misses Waste Quota Without Gate Layering** - **Symptom:** Short confirmations or repeated prompts still consume L3 budget. - **Cause:** Heuristics alone do not block trivial prompts, repeats, or burst traffic. - **Fix:** Keep `l3-gate.sh` wired into the hook loop at `/var/www/syncrovanis/engine/hooks/user-prompt-context-engine.sh:70-72` and the escalation chain at `/var/www/syncrovanis/engine/hooks/user-prompt-context-engine.sh:113-136`. **SYNCROVANIS-08: Transcript Handoffs Can Lag Live Code** - **Symptom:** Session notes describe a missing Copilot `--model` flag or older runtime version. - **Cause:** Handoff text captured an intermediate state. - **Fix:** When transcript and code disagree, trust live source files first; current Copilot invocation is `/var/www/syncrovanis/engine/lib/llm-classify.sh:141-145` and current version is `0.4.0`. **SYNCROVANIS-10: GAP System Replaces BACKLOG.md for Tier 2/3 Items** SQLite-based gap tracking integrated into the Syncrovanis dashboard. | Component | Path | Purpose | |---|---|---| | **gap_reader.py** | `/var/www/syncrovanis/dashboard/gap_reader.py` | CRUD for `gaps` table in `coordination/knowledge.db` | | **gap-cli.sh** | `/var/www/syncrovanis/gap-cli.sh` (symlinked globally) | CLI wrapper for gap_reader — used by `/avslutt` Tier 2/3 implementation | | **gaps.html** | `dashboard/templates/gaps.html` | Dashboard view with filters, charts, status management | Workspace-scoped: each workspace has its own `gaps` table in its local `knowledge.db`. Usage: `gap-cli.sh add --workspace syncrovanis --tier 2 --title "..." --description "..."` **Sources:** Ad-hoc session 2026-03-20 (GAP-system implementation) **SYNCROVANIS-09: L3 Recovery Was Verified In Parts, Not End-To-End** - **Symptom:** Gates look correct in code, but behavior after reactivation is still uncertain. - **Cause:** The 2026-03-19 handoff explicitly noted no live post-reactivation L3 test was run in that session. - **Fix:** Before changing budgets or model choices, validate against fresh JSONL rows and dashboard provider stats rather than assuming the handoff covered runtime behavior.

## 2. Classification Pipeline | Stage | Source | Current behavior | |---|---|---| | **Prompt cleaning** | `/var/www/syncrovanis/engine/hooks/user-prompt-context-engine.sh:38-48` | Removes `<ide_opened_file>`, `<ide_selection>`, and `<task-notification>` before routing | | **Quiet mode** | `/var/www/syncrovanis/engine/hooks/user-prompt-context-engine.sh:50-67` | Titles and slash commands still classify/write files, but do not emit stdout context | | **State preload** | `/var/www/syncrovanis/engine/hooks/user-prompt-context-engine.sh:94-98`, `/var/www/syncrovanis/engine/lib/state.sh:43-73` | Loads `prompt_count`, `delivered_count`, `l3_used`, and sticky session domains | | **Heuristic pass** | `/var/www/syncrovanis/engine/hooks/user-prompt-context-engine.sh:107-111` | Runs L0 + L1 + L2 before any L3 escalation | | **L3 escalation gate** | `/var/www/syncrovanis/engine/hooks/user-prompt-context-engine.sh:113-136` | Gate order is `l3_used -> trivial -> ratelimit -> cache -> escalation` | | **Context emission** | `/var/www/syncrovanis/engine/hooks/user-prompt-context-engine.sh:545-560` | Emits onboarding or scope-update context only when there is net new value | | **Telemetry** | `/var/www/syncrovanis/engine/hooks/user-prompt-context-engine.sh:656-699` | JSONL captures `trace`, `l3_model`, `l3_effort`, `l3_gate`, `l3_budget`, prompt number, KB token estimate, and maturity | --- ## 3. L3 Budget Controls | Control | Source | Current behavior | |---|---|---| | **Trivial prompt filter** | `/var/www/syncrovanis/engine/lib/l3-gate.sh:12-35` | Skips short acknowledgements, single-word confirmations, and short IDE-only payloads | | **Cache lookup/store** | `/var/www/syncrovanis/engine/lib/l3-gate.sh:37-77` | Workspace + prompt MD5 cache in `/tmp/syncrovanis-l3-cache`, 4h TTL, prunes over 200 files | | **Global rate limit** | `/var/www/syncrovanis/engine/lib/l3-gate.sh:79-125` | `flock`-guarded budget file `/tmp/syncrovanis-l3-budget`, default max `10` L3 calls per hour | | **Sticky per-session guard** | `/var/www/syncrovanis/engine/lib/state.sh:57-64`, `/var/www/syncrovanis/engine/hooks/user-prompt-context-engine.sh:113-130` | Once an L3 escalation succeeds, `l3_used` blocks more L3 in the same session | | **Budget logging** | `/var/www/syncrovanis/engine/hooks/user-prompt-context-engine.sh:662-693` | Remaining hourly budget is written to JSONL as `l3_budget`; gate outcome is written as `l3_gate` | Operational rule: analyze L3 spend from `~/.claude/logs/syncrovanis.jsonl` by grouping `l3_gate`, `provider`, `trace`, and `kb_tok`. Raw provider counts alone under-report cache and rate-limit wins. ---

# Infrastructure Expert: Syncrovanis (Agent Context Engine) **Version:** 1.1 **Date:** 2026-03-19 **Parent:** `coordination/experts/operations/magitek-ops/CURRENT.md` **Load:** `coordination/experts/operations/magitek-ops/core-systems/CURRENT-syncrovanis.md` **Sources:** Session 599b291f (2026-03-18), session-context b7663763-0ed5-48b2-95d5-3c8a45829459 (2026-03-19), local source verification 2026-03-19 --- ## 1. Identity & Runtime | Property | Value | |---|---| | **System** | Syncrovanis | | **Location** | `/var/www/syncrovanis` | | **Purpose** | Dynamic agent context delivery system for Claude Code workspaces | | **Runtime version** | `0.4.0` from `/var/www/syncrovanis/VERSION:1` and `/var/www/syncrovanis/composer.json:3` | | **Dashboard inputs** | `/var/www/syncrovanis/dashboard/app.py:8-12` reads `~/.claude/logs/syncrovanis.jsonl`, workspace KB DBs, `kb-workspace.json`, and engine symlinks | | **Key scripts** | `/var/www/syncrovanis/engine/hooks/user-prompt-context-engine.sh:20-143`, `/var/www/syncrovanis/engine/lib/classify.sh`, `/var/www/syncrovanis/engine/lib/llm-classify.sh:1-149`, `/var/www/syncrovanis/engine/lib/l3-gate.sh:1-125`, `/var/www/syncrovanis/engine/lib/state.sh:33-145` | Classification flow: `User prompt -> user-prompt-context-engine.sh -> classify.sh -> kb_context()/kb_query_rich() -> stdout system-reminder -> model` Delivery flow: `stdout additionalContext -> conversation` and `workspace .claude/syncrovanis-context.md -> /tmp/syncrovanis/latest-{workspace}.md` for fallback/audit only. --- ## 1b. Dashboard Architecture (Blueprint Refactor) Dashboard refactored to Flask blueprints in v0.4.0. Entry point is `/var/www/syncrovanis/dashboard/app.py`. | Module | Path | LOC | Responsibility | |---|---|---|---| | **app.py** | `dashboard/app.py` | ~128 | Flask app init, filters, context processor, blueprint registration | | **monitor.py** | `dashboard/routes/monitor.py` | ~254 | Activity feed, logs, context archive, sessions view | | **intelligence.py** | `dashboard/routes/intelligence.py` | ~344 | Analytics, learning, quality metrics, gaps, audits | | **data_views.py** | `dashboard/routes/data_views.py` | ~79 | Workspace list, KB browser | | **system.py** | `dashboard/routes/system.py` | ~176 | System config, engine status, ingest trigger | **Sources:** Ad-hoc session 2026-03-20 (blueprint refactor) ---

### v1.2 — 2026-03-18 - Added Classification Pipeline section (`CLEAN_PROMPT`, layer trace, quiet-mode) - Added kb-workspace keyword maintenance notes - Added gotchas SYN-DEPLOY-05 through SYN-DEPLOY-08 ### v1.1 — 2026-03-18 - Added software versioning section - Added SYN-DEPLOY-04 for symlink-safe version lookup ### v1.0 — 2026-03-18 - Initial deployment topology and workspace coverage document

### SYN-DEPLOY-14: KB FTS5 parser fails on hyphens in search terms - Symptom: `vendor/bin/kb query "monitoring-k"` crashes with "no such column: k". - Cause: SQLite FTS5 tokenizer treats hyphen as a column separator, parsing `monitoring-k` as `monitoring` MINUS column `k`. - Fix: Quote the search term or replace hyphens with spaces before querying: `"monitoring k"` instead of `"monitoring-k"`. ### SYN-DEPLOY-15: L3 ran on every prompt without gate, burning Copilot quota - Symptom: GitHub Copilot premium quota consumed rapidly despite light session usage. - Cause: L3 LLM classification ran on every prompt (including trivial ones) and `l3_used` state was overwritten on each state update. - Fix: Deployed `l3-gate.sh` (trivial filter + cache + rate limit) and fixed `state.sh:64` to preserve `l3_used` across updates. ### SYN-DEPLOY-16: GAP-system erstatter BACKLOG.md for Tier 2+3 audit-items - Symptom: `/avslutt` Tier 2/3 items forblir i BACKLOG.md og mister workspace-kontekst. - Cause: BACKLOG.md er et flatt globalt register uten workspace-scope eller status-tracking. - Fix: Bruk `gap-cli.sh` for alle Tier 2/3 audit-items. GAP-tabellen i `knowledge.db` er workspace-scopet og integrert i Syncrovanis dashboard under Intelligence → Gaps. - Kilde: Ad-hoc session 2026-03-20 ### SYN-DEPLOY-13: Runtime version and composer version can drift - Symptom: Hook banner and package metadata disagree. - Cause: Runtime reads `/var/www/syncrovanis/VERSION`, while `composer.json` may not be bumped at the same time. - Fix: Treat `VERSION` as runtime truth and update both files on release. --- ## Changelog ### v1.5 — 2026-03-19 - Added L3 Cost Control Gate section documenting l3-gate.sh (trivial filter, cache, rate limit) - Updated VERSION runtime truth from 0.2.1 to 0.4.0 - Fixed state.sh l3_used preservation bug documentation - Added gotchas SYN-DEPLOY-14 (KB FTS5 hyphen parsing) and SYN-DEPLOY-15 (L3 Copilot quota burn) ### v1.3 — 2026-03-18 - Corrected runtime versioning to reflect `VERSION=0.2.1` and documented the current composer drift - Added Delivery Topology section with stdout-first architecture and shared-file race analysis - Added L3 Runtime Behavior section with verified provider order, flags, cooldowns, and timeouts - Added entity-first KB fallback details for domain alias mismatch recovery - Added gotchas SYN-DEPLOY-09 through SYN-DEPLOY-13

### SYN-DEPLOY-09: L3 looks dead when provider defaults are wrong - Symptom: JSONL shows repeated `L3:miss(no-result)` even on substantial prompts. - Cause: Unsupported Codex model pinning, Gemini sandbox/MCP startup cost, and too-short timeouts. - Fix: Keep the current provider chain and flags in `llm-classify.sh:7-12` and `llm-classify.sh:115-127`. ### SYN-DEPLOY-10: Domain alias mismatch returns empty `kb_context()` - Symptom: `kb_context --domain=ops/services` returns zero excerpts while `kb query "postiz"` finds the right expert. - Cause: Workspace aliases like `ops/services` do not always match the deeper domain paths stored in KB rows. - Fix: Entity-first fallback must stay ahead of generic domain-term fallback; see `user-prompt-context-engine.sh:228-252`, `user-prompt-context-engine.sh:305-330`, and `user-prompt-context-engine.sh:354-364`. ### SYN-DEPLOY-11: Shared `.claude/syncrovanis-context.md` contaminates parallel chats - Symptom: Session-start or compaction can load another chat's context from the same workspace. - Cause: The file is shared per workspace and overwritten on every prompt. - Fix: Do not `@-include` it; rely on stdout for live delivery and `/tmp` only for SessionStart fallback. Global policy is in `/home/heine/.claude/CLAUDE.md:88-92`. ### SYN-DEPLOY-12: Syncrovanis source comments can lag behind runtime policy - Symptom: Hook comments or `/var/www/syncrovanis/CLAUDE.md` still describe the workspace file as primary delivery. - Cause: Documentation lag after the race-condition fix. - Fix: For operations, trust `~/.claude/CLAUDE.md` and the hook code path, not stale comments. ### SYN-DEPLOY-14: "Onboardet av Syncrovanis" og INSTRUKS-boilerplate er debug-stillas, ikke varig runtime-UX - **Symptom:** Gjentatte `Onboardet av Syncrovanis...`-linjer og `INSTRUKS`-blokker vises i chatflyt på hvert prompt - **Årsak:** Disse linjene ble innført under tidlig trigger-verifikasjon og ble aldri fjernet fra delta-output - **Kostnad:** ~200 tokens per prompt i boilerplate — i en 12-prompt-sesjon ga dette ~2400 tokens uten verdi - **Løsning:** Fjern `Onboardet av`-footer og `INSTRUKS`-blokk fra delta-leveranser. Behold kun en kort statuslinje og nyttig faginnhold - **Verifikasjon:** Bruk JSONL-logg (`~/.claude/logs/syncrovanis.jsonl`) og konteksthistorikk (`~/.claude/logs/syncrovanis-context/`) for trigger-verifikasjon i stedet for chat-output - **Kilde:** Knowledge audit 0013 (2026-03-19), Syncrovanis-audit 0013 (2026-03-19)

## Adding or Expanding a Workspace 1. Create `{workspace}/.claude` and `{workspace}/coordination`. 2. Add `coordination/kb-workspace.json` with real domain keywords. 3. Install `magitek/kb-system` from `/var/www/kb-system`. 4. Build `coordination/knowledge.db` with `vendor/bin/kb ingest --project-root={workspace}`. 5. Verify hook visibility by checking the next prompt adds a `Layers:` line in context and a row in `~/.claude/logs/syncrovanis.jsonl`. Rule: new service names must be queryable both from `kb-workspace.json` and from expert text. If either side is missing, service prompts degrade to generic FTS. --- ## Gotchas ### SYN-DEPLOY-04: VERSION file path resolution in hooks - Symptom: Hook banner shows `v0.0.0` or blank. - Cause: `BASH_SOURCE[0]` resolves to the symlink under `~/.claude/hooks/`, not the engine path. - Fix: Use `readlink -f` before walking to `../../VERSION`; see `user-prompt-context-engine.sh:20-22` and `session-start-syncrovanis.sh:12-14`. ### SYN-DEPLOY-05: IDE tags pollute L1 keyword classification - Symptom: A prompt about `postiz` routes to `claude/syncrovanis` or `claude/expert`. - Cause: IDE metadata in the raw prompt contains file paths and keywords that L1 matches first. - Fix: Always classify `CLEAN_PROMPT`; see `user-prompt-context-engine.sh:38-48`. ### SYN-DEPLOY-06: Missing service keywords cause silent misclassification - Symptom: Service prompts get weak or irrelevant context. - Cause: The service name is absent from `coordination/kb-workspace.json`, so L1 never matches it. - Fix: Add service keywords when deploying new VMs, containers, or products. ### SYN-DEPLOY-07: QUIET_MODE false-positive on IDE-prefixed prompts - Symptom: L3 never runs for a real question. - Cause: Quiet-mode checks the wrong prompt body or a title/slash command consumes the wrong state. - Fix: Quiet-mode must use `CLEAN_PROMPT`, while L3 gating uses `l3_used`; see `user-prompt-context-engine.sh:50-67` and `user-prompt-context-engine.sh:96-121`. ### SYN-DEPLOY-08: L2 skipped when L1 matches wrong domains - Symptom: L1 returns a wrong domain and L2 never gets a chance to recover. - Cause: L2 is fallback only; any L1 hit suppresses it. - Fix: Prevent bad L1 input by cleaning IDE tags first.

## KB Retrieval and Domain Mismatch Handling The important behavior is no longer just `kb_context(domain)`. The hook now resolves domain mismatch with targeted entity fallback before generic FTS. | Step | Source | Behavior | |---|---|---| | Entity extraction | `/var/www/syncrovanis/engine/hooks/user-prompt-context-engine.sh:228-252` | Extracts VM IDs, hostnames, service names, and IPs from `CLEAN_PROMPT` | | Initial entity-first fallback | `/var/www/syncrovanis/engine/hooks/user-prompt-context-engine.sh:287-331` | `kb_context(domain)` -> `kb_query_rich(PROMPT_ENTITIES)` -> `kb_query_rich(domain_terms)` -> raw prompt | | Delta entity-first fallback | `/var/www/syncrovanis/engine/hooks/user-prompt-context-engine.sh:342-366` | Same logic for scope updates | Why this matters: `coordination/kb-workspace.json` can classify to short aliases such as `ops/services`, while indexed KB entries may live under deeper domains such as `operations/magitek-server-ops/hjemme/services`. The entity-first step is what makes a prompt like `postiz` resolve the right expert even when `kb_context --domain=ops/services` returns zero excerpts. --- ## Workspace Coverage | Workspace | Path | Type | kb-workspace.json | .claude/ | CLAUDE.md | KB ingest | |---|---|---|---|---|---|---| | reportmaker | `/var/www/reportmaker` | laravel | yes | yes | yes | yes | | skymirror | `/var/www/skymirror` | laravel | yes | yes | yes | yes | | suitecrm-dev | `/var/www/suitecrm-dev` | laravel | yes | yes | yes | yes | | magitek-ops | `/var/www/magitek-ops` | ops | yes | yes | yes | yes | | dam | `/var/www/dam` | standalone | yes | yes | yes | yes | | syncrovanis | `/var/www/syncrovanis` | engine | yes | yes | yes | yes | | todo-app | `/var/www/todo-app` | laravel | yes | yes | `claude.md` | yes | | hostclone | `/var/www/hostclone` | laravel | yes | yes | yes | yes | | mcp-servers | `/var/www/mcp-servers` | monorepo | yes | yes | yes | yes | | kb-system | `/var/www/kb-system` | package | yes | yes | yes | yes | ---

## L3 Runtime Behavior | Provider order | Source | Why | |---|---|---| | `codex-cli` first | `/var/www/syncrovanis/engine/lib/llm-classify.sh:115-118` | Fastest working provider in this environment | | `gemini-cli` second | `/var/www/syncrovanis/engine/lib/llm-classify.sh:120-123` | Works only with `-s false --allowed-mcp-server-names none` | | `copilot-cli` last | `/var/www/syncrovanis/engine/lib/llm-classify.sh:125-127` | Startup is slow, kept as last resort | | Runtime guard | Source | Value | |---|---|---| | Per-provider cooldown | `/var/www/syncrovanis/engine/lib/llm-classify.sh:27-42` | 10 minutes | | Codex timeout | `/var/www/syncrovanis/engine/lib/llm-classify.sh:117-118` | 8 seconds | | Gemini timeout | `/var/www/syncrovanis/engine/lib/llm-classify.sh:122-123` | 15 seconds | | Copilot timeout | `/var/www/syncrovanis/engine/lib/llm-classify.sh:126-127` | 30 seconds | The working recovery from this session was: remove unsupported Codex model pinning, disable Gemini sandbox/MCP loading, extend timeouts, and run Codex first. --- ## L3 Cost Control Gate ALL external CLI providers (Codex, Gemini, Copilot) cost subscription quota. The gate system prevents unnecessary L3 calls. | Component | Source | Purpose | |---|---|---| | Gate script | `/var/www/syncrovanis/engine/lib/l3-gate.sh` | Trivial filter + cache + rate limit | | Cache dir | `/tmp/syncrovanis-l3-cache/` | MD5-keyed JSON cache per workspace+prompt | | Budget file | `/tmp/syncrovanis-l3-budget` | Hourly call counter | | Cache TTL | 4 hours (env `SYNCROVANIS_L3_CACHE_TTL`) | Configurable via env var | | Rate limit | 10/hour (env `SYNCROVANIS_L3_MAX_HOUR`) | Global across all sessions | | Max cache entries | 200 | Oldest pruned on write | Gate pipeline: `prompt -> l3_is_trivial() -> l3_cache_lookup() -> l3_budget_check() -> L3 provider chain -> l3_cache_store()` Trivial filter rejects: prompts <20 chars, known acknowledgment words (ja/ok/nei/yes/no/fortsett/etc.), IDE-only context without user text. State.sh fix: `l3_used` is now preserved across state updates (`state.sh:64`), preventing the bug where L3 was re-enabled on every prompt when state was overwritten. ---

## Delivery Topology | Path | Scope | Primary use | Race risk | References | |---|---|---|---|---| | Hook stdout | Per session, per prompt | Primary delivery into conversation context | No | `/var/www/syncrovanis/engine/hooks/user-prompt-context-engine.sh:426-437`, `/home/heine/.claude/CLAUDE.md:88-92` | | `{workspace}/.claude/syncrovanis-context.md` | Shared per workspace | Debugging and audit artifact | Yes | `/var/www/syncrovanis/engine/hooks/user-prompt-context-engine.sh:439-446`, `/home/heine/.claude/CLAUDE.md:90-92` | | `/tmp/syncrovanis/latest-{workspace}.md` | Shared per workspace | SessionStart fallback | Yes | `/var/www/syncrovanis/engine/hooks/user-prompt-context-engine.sh:448-467`, `/var/www/syncrovanis/engine/hooks/session-start-syncrovanis.sh:21-47` | | `~/.claude/logs/syncrovanis-context/{date}/` | Per session, per prompt | Forensics of actual delivered context | No | `/var/www/syncrovanis/engine/hooks/user-prompt-context-engine.sh:470-490` | The shared workspace file is no longer part of the read path in global Claude config. The session that discovered parallel-chat contamination removed the `@-include` from `/home/heine/.claude/CLAUDE.md:88-92`. --- ## Classification Pipeline 4-layer chain: `L0 prompt structure -> L1 keyword match -> L2 FTS fallback -> L3 LLM enrichment` | Stage | Source | What it does | |---|---|---| | Prompt cleaning | `/var/www/syncrovanis/engine/hooks/user-prompt-context-engine.sh:38-48` | Strips `<ide_opened_file>`, `<ide_selection>`, and `<task-notification>` before routing | | Quiet-mode gate | `/var/www/syncrovanis/engine/hooks/user-prompt-context-engine.sh:50-67` | Suppresses stdout on titles/slash commands but still classifies and writes files | | State preload | `/var/www/syncrovanis/engine/hooks/user-prompt-context-engine.sh:90-94` | Reads `prompt_count`, `delivered_count`, and `l3_used` | | L3 gate | `/var/www/syncrovanis/engine/hooks/user-prompt-context-engine.sh:96-121` | Enables L3 once per session for the first substantial non-quiet prompt, with escalation if L0+L1+L2 all fail | | Layer trace | `/var/www/syncrovanis/engine/hooks/user-prompt-context-engine.sh:132-137`, `/var/www/syncrovanis/engine/hooks/user-prompt-context-engine.sh:411-415`, `/var/www/syncrovanis/engine/hooks/user-prompt-context-engine.sh:520-542` | Emits `L0:...|L1:...|L2:...|L3:...` to context and JSONL | Important split: - `l3_used` controls whether L3 may run again in the same session. - `delivered_count` controls whether the next real prompt is treated as `initial` or `delta`. That separation fixed the old failure mode where quiet prompts consumed the onboarding slot. ---

# Syncrovanis — Deployment Topology & Workspace Coverage **Version:** 1.5 | **Date:** 2026-03-19 | **Scope:** All Magitek workspaces on 172.20.0.94 **Sources:** agent-meta session 2026-03-18 (10/10 expansion), infra-ops session 2026-03-18 (L3 recovery + shared-context race), infra-ops session 2026-03-19 (L3 gate + Copilot overuse fix), local source verification 2026-03-19 --- ## Overview Syncrovanis is the global context-delivery engine for Claude Code across Magitek workspaces under `/var/www/`. | Component | Value | |---|---| | Engine repo | `/var/www/syncrovanis/` | | Dashboard | `https://syncrovanis.magitek.no` | | Hooks | `~/.claude/hooks/user-prompt-context-engine.sh`, `~/.claude/hooks/session-start-syncrovanis.sh` | | Core libs | `/var/www/syncrovanis/engine/lib/classify.sh`, `/var/www/syncrovanis/engine/lib/llm-classify.sh`, `/var/www/syncrovanis/engine/lib/state.sh` | | Workspace output | `{workspace}/.claude/syncrovanis-context.md` | | Session archive | `~/.claude/logs/syncrovanis-context/{date}/` | | JSONL log | `~/.claude/logs/syncrovanis.jsonl` | Data flow: `UserPromptSubmit -> user-prompt-context-engine.sh -> classify_prompt() -> kb_context()/kb_query_rich() -> stdout system-reminder -> model` Fallback flow: `user-prompt-context-engine.sh -> {workspace}/.claude/syncrovanis-context.md -> /tmp/syncrovanis/latest-{workspace}.md -> session-start-syncrovanis.sh` --- ## Runtime Truth | Item | Source | Current value | Notes | |---|---|---|---| | Runtime version | `/var/www/syncrovanis/VERSION:1` | `0.4.0` | Hook banner follows this value | | Composer metadata | `/var/www/syncrovanis/composer.json` | `0.4.0` | Drifted from runtime version | | UserPrompt version lookup | `/var/www/syncrovanis/engine/hooks/user-prompt-context-engine.sh:20-22` | `readlink -f` + `../../VERSION` | Fixed symlink-path bug | | SessionStart version lookup | `/var/www/syncrovanis/engine/hooks/session-start-syncrovanis.sh:12-14` | `readlink -f` + `../../VERSION` | Same fix | | Global runtime policy | `/home/heine/.claude/CLAUDE.md:88-92` | stdout-first | No `@.claude/syncrovanis-context.md` include | Operational rule: trust `VERSION` and hook output for runtime truth. Treat `composer.json` version as packaging metadata until the drift is corrected. ---

## Changelog ### v1.3 — 2026-03-20 - Updated session-audit runtime truth to the verified Gemini-first pipeline - Added provider-specific launch behavior for Gemini sandbox disable, Codex sandbox bypass, and Copilot `/tmp` execution - Documented `--truncate-results 2000`, Agent Summary stderr output, and partial-success verification rules - Added new gotchas PIPE-06 through PIPE-09 for current audit failure modes ### v1.2 — 2026-03-19 - Updated `expert-training.sh` version to `1.2.0` and documented the file-path composition model - Corrected session-audit from 4 analyses to 5 analyses and added Syncrovanis - Corrected report path layout to per-analysis subdirectories ### v1.1 — 2026-03-18 - Initial documentation of the external model delegation pipeline

### PIPE-04: `audit-combined-prompt.md` is legacy-only - Symptom: an old combined prompt file still exists under `~/.claude/scripts/`. - Cause: it was left behind after the pipeline split into per-analysis prompts. - Fix: active templates are `audit-prompt-{shared,meta,mcp-selfbuild,mcp-usage,knowledge,syncrovanis}.md`. ### PIPE-05: Expert-training session context must stay file-based - Symptom: `expert-training.sh --session-context latest` regresses to `Argument list too long`. - Cause: large session content was inlined into the dispatcher prompt instead of referenced by path. - Fix: keep the current file-path pattern in `expert-training.sh:161-193` and `:268-281`. ### PIPE-06: Copilot CLI still blows its budget if launched from the workspace - Symptom: Copilot workers stall or fail before doing useful work on large repos. - Cause: workspace launch triggers repo auto-indexing of roughly `103K` tokens in `magitek-ops`; the transcript then pushes total input past Copilot’s limit. - Fix: keep the `/tmp` launch wrapper with `--add-dir "$workspace"` at `select-model.sh:144-153`. ### PIPE-07: Full audit transcripts still need explicit tool-result truncation - Symptom: `session-audit.sh` spends time chunk-reading very large transcripts and agents run out of context before writing reports. - Cause: full-mode transcript extraction keeps tool results verbatim unless `--truncate-results` is supplied. - Fix: preserve `session-audit.sh:255` and `session-to-transcript.sh:221-226`; current standard is `--truncate-results 2000`. ### PIPE-08: Gemini sandboxing can block transcript/log access - Symptom: Gemini can write inside the workspace but fails to read or update needed audit artifacts. - Cause: Gemini CLI sandboxing restricts filesystem access outside its allowed scope. - Fix: use `--sandbox false --approval-mode yolo` for audit/external-agent launches as in `select-model.sh:125-131`. ### PIPE-09: Partial audit success can still return a failing wrapper exit code - Symptom: `session-audit.sh` exits non-zero even though several reports were created successfully. - Cause: one timed-out analysis keeps the wrapper in failure state while other report files remain valid. - Fix: verify file creation with `find coordination/maintenance/audits/ -name "*.md" -mmin -10 | sort` and commit the reports that exist. ---

## Expert Training Expert-training remains file-path based and Codex-first in `/avslutt`. Expert flow: `--session-context latest` → `session-to-transcript.sh --compact` → `.expert-training-temp/session-context.md` → `expert-training-prompt.md` with `{SESSION_CONTEXT_PATH}` / `{TASK_BRIEF_PATH}` → composed dispatcher prompt → external agent | Mode | Verified path:line | Behavior | |------|--------------------|----------| | Session context | `~/.claude/scripts/expert-training.sh:161-193` | Extracts compact transcript into workspace temp dir | | Task brief | `~/.claude/scripts/expert-training.sh:205-231` | Reads metadata from path without inlining full brief | | Prompt composition | `~/.claude/scripts/expert-training.sh:268-281` | Replaces placeholders with file paths | | Template contract | `~/.claude/scripts/expert-training-prompt.md:117-129` | External agent must open the referenced file on disk | Design boundary: `expert-training.sh` may write large inputs to disk, but `select-model.sh` still forwards the final dispatcher prompt as a CLI argument. Do not re-inline transcripts into that prompt. --- ## Gotchas ### PIPE-01: Audit model labels reflect the effective model after fallback - Symptom: logs show `codex:gpt-5.4` even though the requested tier was Copilot. - Cause: `select_model()` returns the actual provider/model after context-limit fallback. - Fix: treat `~/.claude/logs/external-model-usage.log` as runtime truth and check for `FALLBACK=yes`. ### PIPE-02: `select_model()` warnings can be missing from per-agent logs - Symptom: per-agent output file lacks the reason a fallback happened. - Cause: fallback warnings are emitted before the provider-specific log capture starts. - Fix: inspect `~/.claude/logs/external-model-usage.log`, not only `agent-output-*.log`. ### PIPE-03: GitHub’s Copilot usage UI is not a reliable audit source - Symptom: web UI shows little or no Copilot activity despite real CLI runs. - Cause: CLI usage is not reflected consistently in GitHub’s web reporting. - Fix: use `external-model-usage.log` plus session-audit Agent Summary instead.

## Session Audit Session audit is a 5-analysis Gemini-first pipeline. Audit flow: `session id` → `session-to-transcript.sh --truncate-results 2000` → workspace transcript copy → Syncrovanis log extract → per-analysis prompt composition → 5 parallel external agents → report verification | Analysis | Prompt family | Effective model | Output directory | |----------|---------------|-----------------|------------------| | `meta` | `audit-prompt-meta.md` | `gemini:gemini-2.5-pro` | `coordination/maintenance/audits/meta/` | | `mcp-selfbuild` | `audit-prompt-mcp-selfbuild.md` | `gemini:gemini-2.5-flash` | `coordination/maintenance/audits/mcp-selfbuild/` | | `mcp-usage` | `audit-prompt-mcp-usage.md` | `gemini:gemini-2.5-flash` | `coordination/maintenance/audits/mcp-usage/` | | `knowledge` | `audit-prompt-knowledge.md` | `gemini:gemini-2.5-flash` | `coordination/maintenance/audits/knowledge/` | | `syncrovanis` | `audit-prompt-syncrovanis.md` | `gemini:gemini-2.5-pro` | `coordination/maintenance/audits/syncrovanis/` | Verified behavior: | Behavior | Verified path:line | Notes | |----------|--------------------|-------| | Full transcripts are truncated at 2000 chars per tool result | `~/.claude/scripts/session-audit.sh:255`, `~/.claude/scripts/session-to-transcript.sh:221-226` | Keeps audit transcripts smaller without switching to compact mode | | Transcript is copied into workspace temp dir | `~/.claude/scripts/session-audit.sh:270-274` | Compatible with external agents that cannot read `/tmp` safely | | Syncrovanis log extracted separately | `~/.claude/scripts/session-audit.sh:277-294` | Gives `syncrovanis` audit a second input stream | | One external process per analysis | `~/.claude/scripts/session-audit.sh:600-613` | Internal parallelism handled by the script, not by the caller | | Agent Summary emitted on stderr | `~/.claude/scripts/session-audit.sh:628-655` | Contains analysis, model, effort, time, status, log size | | File existence decides report success | `~/.claude/scripts/session-audit.sh:658-670` | Missing files still matter even if some agents succeeded | Operational verification rule: after any timeout or non-zero exit, run `find coordination/maintenance/audits/ -name "*.md" -mmin -10 | sort` and trust the files found over the wrapper exit code alone. ---

## Runtime Truth | Provider | Verified path:line | Current launch mode | Operational consequence | |----------|--------------------|---------------------|-------------------------| | Gemini CLI | `~/.claude/scripts/select-model.sh:125-131` | `gemini -m ... --sandbox false --approval-mode yolo` | Gemini can read `.session-audit-temp/` transcript/log files directly | | Codex CLI | `~/.claude/scripts/select-model.sh:133-142` | `codex exec ... --dangerously-bypass-approvals-and-sandbox` | Avoids `bwrap` failure on this server | | Copilot CLI | `~/.claude/scripts/select-model.sh:144-153` | `(cd /tmp && copilot ... --add-dir "$workspace")` | Avoids repo auto-index blow-up while preserving workspace access | Dispatcher flow: `tier or provider:model` → `select_model()` → `spawn_external_agent()` → provider-specific wrapper → per-agent log + usage log Usage log: `~/.claude/logs/external-model-usage.log` --- ## Model Tiers | Tier | Effective model | Context shape | Current main use | |------|-----------------|---------------|------------------| | budget | `gemini:gemini-2.5-flash` | ~1M | Default audit worker for `mcp-selfbuild`, `mcp-usage`, `knowledge` | | standard | `gemini:gemini-2.5-pro` | ~1M | `meta`, `syncrovanis`, CREATE-capable expert training minimum | | codex | `codex:gpt-5.4` | 250K | Expert training, code-heavy external work | | premium | `copilot:claude-sonnet-4.6` | ~100K | Fallback/high-quality non-audit use | | ultra | `copilot:claude-opus-4.6` | ~100K | Deep fallback/architecture use | `session-audit.conf` runtime mapping: | Analysis | Tier source | Effective model | |----------|-------------|-----------------| | `meta` | `TIER_OVERRIDE_meta=standard` | `gemini:gemini-2.5-pro` | | `mcp-selfbuild` | `DEFAULT_TIER=budget` | `gemini:gemini-2.5-flash` | | `mcp-usage` | `DEFAULT_TIER=budget` | `gemini:gemini-2.5-flash` | | `knowledge` | `DEFAULT_TIER=budget` | `gemini:gemini-2.5-flash` | | `syncrovanis` | `TIER_OVERRIDE_syncrovanis=standard` | `gemini:gemini-2.5-pro` | Fallback chain from `select_model()` still exists: `copilot:*` → `codex:gpt-5.4` → Gemini when estimated input exceeds provider context limits. ---

# Agent Pipeline — External Model Delegation & Audit Infrastructure **Version:** 1.3 | **Date:** 2026-03-20 | **Scope:** Global Claude external-agent pipeline used from `magitek-ops` **Sources:** MP-0009 (Session Audit Pipeline), Infra-ops session 2026-03-18 (model usage logging, audit parallelization), Debugging session 2026-03-19 (expert-training ARG_MAX fix), Debugging session 2026-03-19 (Copilot context blow-up, Gemini switchover), Session context 2026-03-20 (`/avslutt` parallel auto-run, post-audit hard gate) --- ## Overview Primary audit flow: `/avslutt` or `/session-chat-audit` → `session-audit.sh` → `session-to-transcript.sh` → `select-model.sh` → 5 external agents → `coordination/maintenance/audits/{meta,mcp-selfbuild,mcp-usage,knowledge,syncrovanis}/` Primary expert flow: `/expert-training` or `/avslutt` expert step → `expert-training.sh` → `.expert-training-temp/session-context.md` or task brief → composed dispatcher prompt → external agent → `coordination/experts/*` Current design rule: large artifacts stay on disk, short dispatcher prompts travel through CLI arguments. | Component | Verified path:line | Current role | |-----------|--------------------|--------------| | Provider dispatcher | `~/.claude/scripts/select-model.sh:124-153` | Provider-specific launch behavior for Gemini, Codex, and Copilot | | Audit config | `~/.claude/scripts/session-audit.conf:4-22` | Default Gemini Flash, Gemini Pro overrides for `meta` and `syncrovanis` | | Transcript extraction | `~/.claude/scripts/session-audit.sh:248-301` | Builds workspace-local transcript and Syncrovanis log inputs | | Audit fan-out | `~/.claude/scripts/session-audit.sh:399-423`, `:438-460`, `:600-655` | Per-analysis model selection, 5-way parallel spawn, stderr Agent Summary | | Transcript truncation | `~/.claude/scripts/session-to-transcript.sh:12-16`, `:38-44`, `:114-131`, `:221-226` | `--truncate-results` support for full transcripts | | Expert-training file-path mode | `~/.claude/scripts/expert-training.sh:161-193`, `:268-281` | Keeps large session/task payloads on disk | ---

- Symptom: expert-training via Codex fails with bubblewrap startup errors such as `bwrap: loopback: Failed RTM_NEWADDR` - Cause: Codex `--full-auto` relies on bubblewrap network-namespace setup; this KVM host does not support that path. The live workaround is documented inline in `~/.claude/scripts/select-model.sh:131-138` - Fix: use `codex exec ... --dangerously-bypass-approvals-and-sandbox` for server-side automation. `select-model.sh` already does this for provider `codex` ---

- Symptom: `~/.claude/agents/session-audit.md` still offers the older 4-analysis menu-driven flow while `/session-chat-audit` and `/avslutt` run a 5-analysis Gemini-first pipeline - Cause: rebuilding command parts does not touch the standalone agent definition, so agent docs drift separately from generated commands and scripts - Fix: when session-audit semantics change, update all three layers together: shared command parts, generated commands, and `~/.claude/agents/session-audit.md`

- Symptom: generated wrappers still carry stale wording such as `4 parallelle analyser` or `brukeren velger tier` even though the shared parts now define a Gemini-only auto-run flow - Cause: shared-part rebuilds do not automatically refresh manual frontmatter/heading text outside the injected blocks (`session-chat-audit.md:2-3`, `avslutt/core.md:104`) - Fix: after semantic command changes, audit frontmatter, wrapper headings, and generated descriptions in addition to the shared parts

- Symptom: pre-v1.2.0 `expert-training.sh --session-context latest` failed with `Argument list too long` once the transcript reached ~169K chars - Cause: the composed prompt embedded full session/task content instead of passing stable file paths; `select-model.sh:124-153` still forwards the final prompt as a CLI argument, so oversized prompts remain unsafe - Fix: keep the v1.2.0 pattern in `expert-training.sh:161-193` and `:268-281`: copy large inputs into `.expert-training-temp/`, substitute `{SESSION_CONTEXT_PATH}` / `{TASK_BRIEF_PATH}` in `expert-training-prompt.md:117-129`, and send only the short dispatcher prompt - Status as of 2026-03-19: FIXED and verified by a real `--session-context latest` run

- Symptom: a small change intended for `/avslutt` also changes `/session-chat-audit` - Cause: both commands import `~/.claude/command-parts/shared/session-audit/01-tier-menu.md` through `build-command.sh` - Fix: when changing session-audit launch behavior, rebuild and verify BOTH generated commands, not just the one you touched

- `~/.claude/commands/avslutt.md` and `~/.claude/commands/session-chat-audit.md` are auto-generated - Pre-tool-use hook `pre-tool-use-generated-agent-guard.sh` blocks Write/Edit attempts and shows rebuild command - Cause: direct edits get overwritten on next `build-command.sh` run - Fix: edit the source parts in `~/.claude/command-parts/`, then run `build-command.sh {command}` - Exception: if the behavior change touches shared parts (see G-024), update and verify the shared source FIRST before rebuilding

- `orchestrator-ops` was ReportMaker-specific: only understood RM coordination, didn't detect workspace - `agent-ops` uses **router + context files** pattern: detects $PWD, loads `context-{workspace}.md` - 5 workspace contexts exist: reportmaker, skymirror, dam, magitek-ops, mcp-servers (agent-ops contexts) - Syncrovanis `kb-workspace.json` coverage: 10/10 workspaces (reportmaker, skymirror, suitecrm-dev, magitek-ops, dam, syncrovanis, todo-app, hostclone, mcp-servers, kb-system) - agent-ops has **self-maintenance capability** -- can update its own context files when state changes - `/fix-orchestrator` command is also deprecated -- use `/agent-ops` instead - `orchestrator.md` has been updated: all delegation references point to `agent-ops` (not `orchestrator-ops`) - Key difference: orchestrator-ops was a separate agent file; agent-ops is one agent with per-workspace context

- Symptom: Brukeren forventer at memories, masterplans, handoffs, audits, commands, scripts og session-state påvirker onboarding, men konteksten speiler nesten bare eksperter - Cause: Hooken leser direkte bare `coordination/kb-workspace.json` og KB-funksjonene i `/var/www/syncrovanis/engine/lib/kb-query.sh:1-180`; magitek-ops KB har eksperter som hovedkilde og mangler de fleste andre kunnskapsfamiliene - Fix: Utvid ingest-dekning for manglende kilder og/eller bygg sideindekser som kan hentes direkte før kontekstmontering på første prompt

- Symptom: Korte oppfølgingsprompt som "Sjekk en gang til" kan utløse irrelevant `scope-update` fra feil domene - Cause: `classify.sh:59-80` reduserer promptet til noen få FTS-token; ett generisk ord kan bli hele spørringen, og `user-prompt-context-engine.sh:91-111` behandler nye L2-domener som reell scope-endring - Fix: Avvis lav-entropi FTS-spørringer, krev confidence før L2 kan trigge delta, og la L3 kunne veto-e domenehopp fra korte/generiske prompt

- Symptom: Old references to `/prompt-agent-chat-mcp-audit` break after agent renames it to `mcp-selfbuild` - Cause: Agent interpreted "create a new separate analysis" as "rename existing + create new" instead of "add new alongside existing" - Fix: When adding new commands/analyses, always do it additively. If renaming is needed, create deprecation stubs that point to the new name. Never delete the original in the same session without explicit migration instructions from the user. - Sources: Agent-meta session 2026-03-18 (MCP usage audit, audit pipeline 3→4)

- Symptom: Naturlige prompt som "Vi må jobbe med `/avslutt` kommandoen" gir ingen eller for grunn onboarding selv om temaet er agent-systemet - Cause: `coordination/kb-workspace.json:3-18` har ingen kommandospesifikk domene-routing, `classify.sh:129-188` kan bare returnere/berike domener som finnes i den listen, og magitek-ops KB har `0` rader fra `.claude/commands/*` - Fix: Legg til command-aware routing og komposisjon: `command docs -> agent-system expert -> relevante KB-utdrag`, enten via KB-ingest av `.claude/commands/*` eller en egen lettvektsindeks for kommandoer

- Symptom: Delegert agent (Gemini/Codex/Copilot) mangler detaljer fra sesjonen, produserer ufullstendige ekspertfiler - Cause: `expert-training.sh` sender kun `composed-prompt.md` (template + task brief). Agenten arver IKKE chathistorikk, memories, eller CLAUDE.md - Fix: Alt relevant MÅ inkluderes i task briefen — SSH-output, nye gotchas, korreksjoner, sources - Kostnadsparadoks: Ekstern modus bruker ~5K tokens i main chat (skrive detaljert brief) vs ~700 for in-session subagent. Men ekstern agent (Gemini/Codex) er gratis, så totalkostnad er lavere

- Copilot CLI is not limited to Claude models — it exposes GPT, Gemini, and Claude models via GitHub's backend - Full model list includes: claude-sonnet-4.6, claude-opus-4.6, gpt-5.4, gpt-5.4-mini, gemini-3-pro-preview, and 13 more - This makes Copilot CLI the most versatile external provider for model diversity - Caveat: all Copilot CLI models share the same ~100K context limit regardless of the underlying provider's native limit

- Symptom: external agent (Gemini/Codex/Copilot) cannot SSH to remote servers - Cause: misunderstanding — external CLI agents run as the same user on the same host, so they inherit `~/.ssh/config` and all SSH keys - Status: Gemini CLI and Copilot CLI confirmed working with SSH. Codex CLI also works in the live server-side path, but only after switching from `--full-auto` to sandbox bypass in `~/.claude/scripts/select-model.sh:131-138` - Implication: expert-training.sh can safely delegate SSH-based discovery tasks to external agents

- Symptom: model names drift between scripts; some use old names, others new - Cause: model names were hardcoded in each script/command independently - Fix: ALL model references live in `~/.claude/scripts/external-models.conf`. When providers release new models or rename existing ones, update ONLY this file. All scripts source `select-model.sh` which reads `external-models.conf`, so changes auto-propagate - Exception: orchestrator agent files may reference model names in documentation/descriptions, but runtime model selection always goes through `select-model.sh`

- Symptom: session-audit produces empty reports -- external agent cannot read transcript or write output - Cause: All three CLI tools (Gemini CLI, Codex CLI, Copilot CLI) respect `.gitignore` patterns and silently skip matching files/directories - Fix: NEVER gitignore `.session-audit-temp/` or any working directory used by external CLI agents. Script cleans up temp dir after completion instead - Also: `session-audit.conf` config variables must use `OPT_X` pattern (`VERBOSE="${OPT_VERBOSE:-${VERBOSE:-false}}"`) so CLI flags are not overwritten by config `source` - Also: `audit-combined-prompt.md` must include explicit "CRITICAL: File Writing Rules" section -- external agents default to stdout, not file writes

- Files in `~/.claude/agents/` define agents but are NOT accessible as `/command` slash commands - To expose an agent as a slash command, create a wrapper in `~/.claude/commands/{name}.md` that references the agent - Example: `~/.claude/commands/magitek-server-infra-ops.md` wraps `~/.claude/agents/magitek-server-infra-ops.md` - Without wrapper: agent only usable via `--agent` flag or Agent tool, not as `/command`

- SQLite FTS5 treats hyphens as token separators; queries like `npm-kontoret` crash with "fts5: syntax error" - Fix in `classify.sh` and `kb-query.sh`: sanitize FTS5 input by stripping hyphens/special chars before querying - Norwegian stopwords (og, i, er, en, et, for, av, til, med, på, det, som, har, var, den) must be filtered from FTS queries -- they match too broadly - FTS OR-logikk: multiple search terms must use `OR` operator, not implicit AND (which returns zero results for multi-word queries)

- Users can instruct ANY agent (`/solo-dev-light`, `/ui-redesign`, `/suitecrm`, etc.) to edit agent files, expert files, CLAUDE.md, or skills - Router-level protection (in agent-ops, expert-training) only covers those specific agents - Fix: Three-layer Write-Guard system protects against accidental overwrites: - **Layer 1:** `~/.claude/CLAUDE.md` global rule -- applies to ALL agents in ALL workspaces - **Layer 2:** `agent-ops.md` router Safety Rules -- applies to all agent-ops variants - **Layer 3:** `expert-training.md` router -- applies to all expert-training variants - Core rule: Read file before edit, verify paths, check for duplicates, use Edit tool (not Write) for existing files - Layer 1 is the critical layer -- it catches cases where non-meta agents receive meta-file edit instructions

- Files in `/etc/cron.d/` MUST be owned by `root:root` -- cron ignores non-root-owned files silently - The `user` field in the cron line (e.g., `heine`) controls which user the job runs as - This differs from user crontab (`crontab -e`) which is user-owned and has no user field - Fix: use `sudo` when creating/editing files in `/etc/cron.d/`; verify with `ls -la /etc/cron.d/`

- All agents and audit/harvest prompts show `[Anbefalt: {model} · {effort} · {thinking}]` - Timing: after `/command` execution or agent file loading, NOT on the initial window-title response - Source: CLAUDE.md "Model & Effort Recommendations" section - Audit prompts add a confirmation gate: show recommendation + "vent på bekreftelse" before starting analysis

- `/prompt-agent-chat-meta-audit`, `/prompt-agent-chat-mcp-selfbuild`, `/prompt-agent-chat-mcp-usage-audit`, `/prompt-agent-chat-knowledge-harvest` - These analyze the CURRENT conversation context -- switching agent first loses that context - Wrong: finish work -> switch to audit agent -> run audit (loses conversation history) - Right: finish work -> run `/prompt-agent-chat-meta-audit` in same session -> audit sees full context - Each prompt shows `[Anbefalt:]` and gates on user confirmation before starting

- Orchestrators have their own shutdown: worktree cleanup, branch merge, coordination updates - `/avslutt` assumes main branch, no worktrees, single-agent work - Using `/avslutt` from orchestrator risks: committing to wrong branch, missing worktree cleanup, pushing incomplete orchestration state - Fix: orchestrators use their built-in shutdown steps; `/avslutt` only for solo commands

- `coordination/experts/README.md` lists all sub-experts with locations - After moving files between locations, README must be updated - Current README still shows old hjemme locations for freshtomato and webhuset-dns (needs fix)

- Named `generic-{quality}-perf{N}-cost{M}x` where perf=quality score, cost=relative cost - Agents should pick the cheapest tier that meets task complexity - haiku (1x-4x) for simple tasks, sonnet (8x-33x) for moderate, opus (38x-163x) for complex

- `orchestrator`: Production task orchestrator (spawns sub-agents for masterplan phases) - `orchestrator-ops`: **DEPRECATED 2026-03-14** -- was meta-agent for orchestration system (fix stuck orchestrator, evolve agents) - These were NOT router variants -- they had fundamentally different purposes - orchestrator-ops was ReportMaker-specific and did not work correctly in other workspaces - **Replaced by: `agent-ops`** -- see G-007

- Claude Code reads YAML frontmatter (name, description, model, skills) to present agent options - Router agent MUST keep same frontmatter as original -- changing it breaks agent discovery - Skills in frontmatter are loaded for ALL variants (router loads them before delegating)

- Infrastructure experts MUST be placed by IP range: 172.20.0.x -> kontoret/, 192.168.86.x -> hjemme/, external -> shared/ - March 1 incident: px1 (kontoret/172.20.0.x) placed under hjemme/proxmox/, freshtomato placed under hjemme/network/ - Fix: expert-training-ops has mandatory placement validation table - Files corrected March 5: px1 deleted from hjemme, freshtomato moved to kontoret, webhuset-dns moved to shared

- Agents that operate in both reportmaker AND magitek-ops MUST use router pattern - Without it: agent assumes wrong directory structure (e.g., flat expert domains vs location-based hierarchy) - Fix: Convert base agent to router, create workspace-specific variants

### What Ny scanner-modul `tools/dam_indexer/scanner_gdrive.py` som bruker `rclone lsjson` for å indeksere Google Drive-kontoer. ### Rclone Config - Location: `/var/www/.config/rclone/rclone.conf` (www-data bruker) - Bruk: `RCLONE_CONFIG=/var/www/.config/rclone/rclone.conf rclone lsjson <remote>: --recursive` - Verifisert: `rclone lsd gdrive:` fungerer ### Google Drive Accounts (fra SkyMirror DB) Hovedkontoene som bør indekseres: | rclone_remote | email | name | |---------------|-------|--...

- DAM indexer: `tools/dam_indexer/` — fullt operativ - 1.46M filer indeksert (nc-magitek, nc-hsal, nc-nativja, truenas x3, orion, hermes) - Cron: daglig 04:30 med `--smart` flag - Audits: A- (implementation + quality) - Config endret: orion har nå ekstra scan_roots (C:\scan, C:\stock-photo, C:\Vector, C:\video) og exclude-patterns for NC sync + IDE caches — IKKE rescannet ennå

MP-0002 (DAM SQLite Catalog) er ferdig implementert og i produksjon. Alle 8 storage-lokasjoner scanner OK. Nå trengs en ny scanner-modul for Google Drive via rclone.

- `kontoret/services/CURRENT-pihole-kontoret.md` → v1.1 - `kontoret/network/CURRENT-pfsense.md` → v1.1 - `shared/CURRENT-cloudflare.md` → v1.2 - `kontoret/services/CURRENT-npm-kontoret.md` → v1.3