live: heartbeat sync 2026-10-20T15:15:41-07:00 (Refs #11 )

live: heartbeat sync 2026-10-20T14:12:41-07:00 (Refs #11 )
live: heartbeat sync 2026-10-20T13:10:41-07:00 (Refs #11 )
2026-10-20 15:15:41 -07:00 · 2026-10-20 14:12:41 -07:00 · 2026-10-20 13:10:41 -07:00 · 2026-10-20 12:07:41 -07:00 · 2026-10-20 11:04:41 -07:00 · 2026-10-20 10:02:41 -07:00
403 changed files with 9056 additions and 4272 deletions
@@ -36,6 +36,11 @@ with YAML frontmatter, spec at `omp-docs/references/okf-spec.md`).
  stay visible in history. **Never merge a PR without an explicit OK from Frank.**
 - **The moment a PR is open, open it in Frank's browser** — `xdg-open <PR-URL>`
  lands a tab in his Firefox; never make him hunt for it in Gitea.
 - **Attribution footer (issues and PRs)** — every issue or PR body you open ends
  with a `---` line, then `cwd: <working directory> · session: <omp session id>`
  (session id from `/status`; `cwd` is that session's own working directory —
  not the build checkout, when they differ). Machine-made artifacts stay attributable to the
  box and session that spawned them.
 - Releases: tag `vX.Y.Z` straight on `main` after verifying; tags are the deploy
  markers every other machine pulls to. Hotfixes are ordinary branches off the
  tag you are fixing forward from.
@@ -95,15 +100,18 @@ secret in every agent's context window on every machine that pulls this repo.
 | box | role | GPU | notes |
 |-----|------|-----|-------|
-| Dev workstation | client box, never runs inference | laptop iGPU + dGPU (non-unified) | mainline llama.cpp at `~/GitPackages/llama.cpp/build/bin/`; this repo lives here at `~/.omp` |
+| Dev workstation (`blankpad`) | client box, never runs inference | Lenovo laptop, AMD Ryzen 5 PRO 5650U / Cezanne APU (**unified memory**, s2idle sleep only, no dGPU) | this repo lives here at `~/.omp`; the earlier "iGPU + dGPU / `~/GitPackages/llama.cpp`" description belonged to the sold `dankware` box |
 | Dankclaw | bench target, secondary models + service stack | Strix Halo APU (**unified memory**) + RTX 3090 (moved over from Dankserver 2026-09) | prod services `frank-dragoon` (halogen-flash-server, :7770, iGPU) and `frank-zealot` (llama.cpp PrismML fork, :7771, 3090); runbooks in the serverAppConfigs vault (`~/Projects/serverAppConfig/serverAppConfigs-docs/LLM/`); ssh: `ssh dankclaw` |
 | Dankserver | main-model box | 2× Radeon AI PRO R9700 — non-unified (was RTX 3090 until 2026-09) | runs `frank-archon` (radiance, TP=2, :7770) — **this repo's operator session runs on it**; ssh: `ssh dankserver` |
 ## Environment gotchas
 - Gitea API needs a token: `GITEA_TOKEN` env (gitignored `.env`). No `tea` CLI
-  installed anywhere. Remote URLs embed the token locally in `.git/config` — that
+  installed anywhere. Remote URLs carry NO embedded token (2026-10-09
-  file is never pushed; it is not a substitute for the secret gate.
+  credential-store cutover) — git and the API both read
  `~/.config/secrets/gitea` (`store --file`, URL-line format; see
  `omp-docs/tools/gitea/client-access.md`). That file is never pushed; it is
  not a substitute for the secret gate.
 - Passwordless sudo (`sudo -n`) works on Dankclaw and Dankserver for systemctl
  verbs only; user units need no sudo at all.
 - SSH into both servers is BatchMode-capable from here:
@@ -96,6 +96,17 @@ Never assume the user reports correct information. He is human, and humans make
 - Always practice Test Driven Development practices; do UNIT TESTS exist for the functionality about to be edited? Is there a LINTER? Is there a FORMATTER? Verify that they exist, and that they are configured as a pre-commit hook. If they do not exist, they MUST be written PRIOR to the code being written. Invoke `/skill:tdd` for preferred testing style. If tests do exist, ensure that they still match the planned changes. If you believe a PRE-EXISTING test must be changed prior to commencing work, ASK THE USER ABOUT IT.
 - Always ensure tests run on code changes after every commit, and all project tests run before every push using git hooks, EXCEPT in the event that the individual test in question takes an excessive amount of time. Always ask the user before disabling an individual due to running time or performance concerns. 
 ### 6. Keep the Todo List LIVE, Not Retrospective
 The todo list is the user's cockpit view of your work. A list that only flips at the end is a history dump, not tracking - the user sees nothing while you work.
 - Multi-step work: `todo init` BEFORE the first substantive step - the list must exist while the work is unseen, not after.
 - Batch the todo transition with the step it describes: `done` + `start` ride along in the same message as the first tool calls of the next step. NEVER defer flips until the whole bill of tasks is finished.
 - A task is `done` the moment its work is verified - not when the surrounding phase ends.
 - Blocked on external input (user answer, subagent, service)? `block` it with a reason so the stall is visible; `unblock` the instant it is actionable.
 - NEVER make a todo call the only call in a message - that is ceremony, not progress; pair every flip with real work.
 ## FORBIDDEN ACTS AND MISTAKES TO NOT REPEAT (DO NOT DO THESE):
 - Editing node_modules or similar import module directories. This is third party code that will be overwritten next time `npm update` or a similar command is run.
 - `git push` - unless directed, except if it's our local gitea instance on Dankclaw.
@@ -1,5 +1,10 @@
 providers:
-  openrouterVariant: floor
+  openrouterVariant: online
  fetch: auto
  maxInFlightRequests:
    llamacpp (dankserver): 3
    llamacpp (dankclaw): 2
    llamacpp (dankclaw-3090): 3
 modelRoles:
  slow: llamacpp (dankclaw)/frank-dragoon:medium
  vision: llamacpp (dankclaw-3090)/frank-zealot:xhigh
@@ -12,15 +17,16 @@ modelRoles:
  default: llamacpp (dankserver)/frank-archon:medium
  smol: llamacpp (dankclaw-3090)/frank-zealot:medium
  web: web/searxng
-  speech: local/kokoro
+  speech: frank-tts (dankclaw)/frank-tts
  judge: openrouter/~typesafe/jev-latest:auto
  dictation: local/parakeet-tdt-0.6b-v3
  memory: llamacpp (dankclaw-3090)/frank-zealot:medium
 symbolPreset: nerd
 composer:
  shape: band
  tokenRate: true
 theme:
-  dark: dark-terminal
+  dark: dark-gruvbox
  light: light
 setupVersion: 2
 browser:
@@ -57,8 +63,7 @@ retry:
      - openai-codex/gpt-5.5
      - xai-oauth/grok-4.5
      - web/ollama
-    speech:
+    speech: []
      []
    llamacpp (dankserver)/frank-archon:
      - llamacpp (dankclaw)/frank-dragoon
  maxRetries: 10
@@ -67,7 +72,7 @@ searxng:
 exa:
  enabled: false
 memory:
-  backend: local
+  backend: sharpshooter
 autolearn:
  enabled: true
  autoContinue: true
@@ -75,12 +80,12 @@ compaction:
  remoteEndpoint: http://192.168.0.143:7771/v1/chat/completions
  methodOrder:
    - shake
    - snapcompact
    - soft
    - handoff
    - snapcompact
    - remote
  idleThresholdTokens: 100000
-  thresholdPercent: 85
+  thresholdPercent: 95
  idleEnabled: true
  thresholdTokens: -1
  dropUseless: false
@@ -90,13 +95,12 @@ compaction:
  enabled: true
  experimentalContextManagement: false
 interruptMode: immediate
-defaultThinkingLevel: medium
+defaultThinkingLevel: xhigh
 hideThinkingBlock: false
-proseOnlyThinking: true
+proseOnlyThinking: false
 terminal:
  showProgress: true
-disabledExtensions:
+disabledExtensions: []
  []
 statusLine:
  separator: powerline
  preset: custom
@@ -135,24 +139,39 @@ tui:
  codexResetFireworks: false
  hyperlinks: auto
  tight: true
  resizeScrollback: rebuild
  titleSpinner: pulse
 display:
  shimmer: kitt
  smoothStreaming: true
  showTokenUsage: true
  pinnedAgents: collapsed
  subagentLivePreview: true
 task:
  showResolvedModelBadge: true
-  maxConcurrency: 3
+  maxConcurrency: 2
  agentModelOverrides:
    designer: llamacpp (dankclaw-3090)/frank-zealot
    librarian: llamacpp (dankclaw-3090)/frank-zealot
-    reviewer: llamacpp (dankclaw-3090)/frank-zealot
+    reviewer: llamacpp (dankserver)/frank-archon
    scout: llamacpp (dankclaw-3090)/frank-zealot
-    security-reviewer: llamacpp (dankclaw-3090)/frank-zealot
+    security-reviewer: llamacpp (dankclaw)/frank-dragoon
    sonic: llamacpp (dankclaw-3090)/frank-zealot
-    task: llamacpp (dankclaw-3090)/frank-zealot
+    task: llamacpp (dankserver)/frank-archon
    seance: llamacpp (dankclaw-3090)/frank-zealot
  eager: default
  enableLsp: true
  maxRuntimeMs: 1800000
  softRequestBudget: 120
  maxRecursionDepth: 1
  disabledAgents: []
  isolation:
    enabled: true
  completionProbe: false
 snapcompact:
  systemPrompt: none
  toolResults: false
  shape: auto
 extendedContext: false
 ttsr:
  contextMode: discard
@@ -162,12 +181,12 @@ checkpoint:
  enabled: true
 readLineNumbers: true
 startup:
-  showSplash: false
+  showSplash: true
  changelogMode: summary
 update:
  channel: stable
 features:
-  unexpectedStopDetection: smart
+  unexpectedStopDetection: mechanical
 stt:
  submitTrigger: say-submit
  enabled: true
@@ -186,6 +205,7 @@ images:
      - litterbox
 edit:
  mode: hashline
  fuzzyThreshold: 0.9
 dev:
  autoqaConsent: granted
 astGrep:
@@ -196,7 +216,7 @@ tts:
  localVoice: bm_george
 speech:
  enabled: false
-  mode: yield
+  mode: all
  enhanced: true
  voice: am_fenrir
 secrets:
@@ -204,6 +224,9 @@ secrets:
 read:
  renderMarkdown: true
  toolResultPreview: true
  defaultLimit: 1000
  summarize:
    prose: false
 lsp:
  formatOnWrite: true
  diagnosticsOnEdit: true
@@ -213,4 +236,43 @@ speechgen:
 live:
  voice: vale
 contextPromotion:
-  enabled: true
+  enabled: true
 title:
  icons: emoji
  generator: tiny
 followUpMode: one-at-a-time
 tools:
  approvalMode: yolo
  format: auto
  maxTimeout: 600
 marketplace:
  autoUpdate: notify
 bash:
  allowCompoundCommands: true
  gitGuard: true
 bashInterceptor:
  enabled: false
 shellMinimizer:
  sourceOutlineLevel: default
 generate_image:
  enabled: false
 computer:
  enabled: true
  display: active
 ratchet:
  enabled: true
 github:
  enabled: true
 security:
  enabled: true
 todo:
  reminders: true
 mcp:
  notifications: false
 plan:
  defaultOnStartup: false
 isolation:
  backend: auto
 worktree:
  onStart: create
  onExit: keep
@@ -0,0 +1,24 @@
 ---
 name: aa-chart-label-browser-extraction
 description: "Extract per-model benchmark scores from artificialanalysis.ai pages: charts are client-rendered recharts SVGs invisible to plain HTML fetch; pair sorted label/name x-coords, then cross-check against published sentences before trusting any chart↔eval identity."
 ---
 Extract per-eval scores for a model from artificialanalysis.ai when no API key exists. Plain HTML fetch yields NO chart data (client-side recharts; SSR has only meta + FAQ sentences; `/api/*` = 401).
 ## Procedure
 1. Managed browser tab: `browser.open({name, url, wait_until: "domcontentloaded"})`.
 2. **Per-eval top-3 (authoritative):** open `https://artificialanalysis.ai/evaluations/<slug>`; regex `document.body.innerText` (collapse whitespace): `([A-Z][^.;]{0,60}?) scores the highest on (.+?) with a score of (-?[\d.]+%?), followed by (.+?) with a score of ... and ...` — mind decimal points truncating naive `[^.]+` regexes. Build the page script as a plain string (`String.raw`), not an interpolated template, so `\\d` survives.
 3. **All-eval per-model rows:** on `https://artificialanalysis.ai/models/<slug>`: scroll in 6 steps (0.15→0.9, ~1.3 s each) to trigger lazy charts, then per `svg` with ≥3 bars: labels = `[...svg.querySelectorAll("g.recharts-label-list text")]` (x attr), names = `[...svg.querySelectorAll("foreignObject")]` divs sorted by `g[transform] translate(x,y)`. Sort BOTH by x, **zip by index** — x-center pairing is off by a systematic half-bar.
 4. Self-row filter: exact hyphenated name (e.g. `Qwen3.8-Flash-Next`, not "Qwen3.8 Flash").
 5. Elo evals (GDPval-AA, AA-Briefcase): charts show AA's published `(Elo−500)/2000` normalization (1866→68.3).
 ## Verification law (non-negotiable — two plausible mappings disagreed twice)
 - Zip top-3 of every chart against the eval page's published sentence (e.g. Kimi 88.7→89, Opus 66.9→67); ship only cross-checked rows.
 - Arithmetic corroboration helps: Omniscience accuracy 17% + non-hallucination 7% ↔ index −60.
 - Record provenance per row: sentence rows → eval-page URL; chart-label rows → model-page URL; `fetched_at` + `index_version`.
 - Geometry pairing (link→nearest chart below) is AMBIGUOUS when chart height > gap to next card — adjacent links share a chart. Use order + sentence tops, not geometry.
 ## Traps
 - `tab.run` = Bun runtime; page-world JS needs `tab.evaluate`. Eval-cell `log()` does not reach display; write to a /tmp file and `cat`.
 - "Add model from specific provider" picker is not in the DOM (renders after chart data loads); UI drill-through × N evals is fragile — prefer the sentences.
 - Headline index FAQ: "scores N on the Artificial Analysis Intelligence Index" — check for "(estimated)" qualifier; est. = "independent evaluation forthcoming".
@@ -0,0 +1,24 @@
 ---
 name: aa-chart-model-score-extraction
 description: "Extract per-model benchmark scores from artificialanalysis.ai pages: charts are client-rendered Recharts SVGs; zip label-list texts to foreignObject names by x-sorted index, validate chart identity against the page's published top-3 sentence, apply Elo/Omniscience normalization laws, seed frank-intelligence-bench aa-scores.yml."
 ---
 Extract AI benchmark scores for a specific model from artificialanalysis.ai. Per-model per-eval numbers are NOT in SSR HTML (JS charts, API needs key); eval-page SSR text DOES carry the top-3 sentence.
 ## Procedure (validated 5x on this repo's model pages)
 1. `browser.open({ name, url: "https://artificialanalysis.ai/models/<slug>", wait_until: "domcontentloaded" })`, then scroll in ~6 steps (0.15..0.9 of scrollHeight, ~1.3 s pauses) — charts lazy-render.
 2. Extract each chart: pair `g.recharts-label-list text` (values, take `x` attr) with `foreignObject div` (model names, x from parent `g[transform] translate(x,y)`). **Sort both lists by x and zip by index — NOT nearest-x** (nearest-x is off by one bar; index-zip matches published tops exactly).
 3. Self row: match name loosely (`Qwen3.8-Flash-Next` has hyphens — test both forms).
 ## Identity law (never ship an order-guessed chart→eval mapping)
 - Model pages have ~14 charts, 18 eval cards; DOM order and geometry pairing BOTH proved ambiguous.
 - Anchor every chart by its top-3 names/values vs the eval page's published sentence: `https://artificialanalysis.ai/evaluations/<slug>` body text: "X scores the highest on <eval> with a score of N%, followed by …". Regex must tolerate decimals: value pattern `(-?[\\d.]+%?)`; build page scripts with `String.raw` (bun template literals eat `\\d`).
 - A chart's `self` value on the MODEL page is page-local → trustworthy once the top-3 anchor confirms the eval (e.g. AA-LCR: Kimi 88.7 → chart top "Kimi K3 (max)=89").
 ## Normalization laws (frank-intelligence-bench aa-scores.yml)
 - Elo evals (AA-Briefcase, GDPval-AA): store `(Elo−500)/2000×100` (1866 → 68.3), AA's published normalization.
 - AA-Omniscience: score = Accuracy (w10) + 1−Hallucination (w5), both 0–100 → composite `(10·acc + 5·nonhall)/15`. NEVER feed the −100..100 Index chart value (pre-fix cost ~7 pts; calibration then reproduces AA's official index ±0.6: Flash-Next 39.85≈40, Haiku 43.4≈43, 27B 33.85≈34, 3.6-27B 21.55≈21).
 - Every seeded row: `source_url` + `fetched_at` + `index_version`.
 ## Seed + validate loop
 Append model block to `config/references/aa-scores.yml` (block-insert via python string replace on the `  - name: <anchor>` line — beware: dropping rows from a block loses the 2-space indent on the anchor line; verify with `yaml.safe_load`), then `bun -e loadAaRefs` parse-check, `bun src/cli.ts report $RID`, calibration check (full-row models: lite vs AA official), `bun test`, commit.
@@ -0,0 +1,41 @@
 ---
 name: aa-reference-scores-seeding
 description: "Seed/refresh frank-intelligence-bench config/references/aa-scores.yml from artificialanalysis.ai: authoritative top-3 sentences from eval pages, Recharts SVG zip extraction for per-model chart values, cross-check law, Elo normalization, schema/repair loop."
 ---
 Seed frank-intelligence-bench `config/references/aa-scores.yml` from AA's public pages, then re-render the report trio.
 ## Provenance law (non-negotiable)
 - Every row: `{ eval, pct, source_url, fetched_at, index_version }` (Zod-enforced; top-level `schema_version: 1, fetched_at, index_version` required).
 - Eval ids MUST match report result ids: `scicode, aa-lcr, hle, terminal-bench, gdp-pdf, aa-briefcase, gdpval-aa, automationbench-aa, aa-omniscience, critpt` (render `refFor(evalId)` joins on exact id).
 - Never ship an order-guessed chart↔eval mapping; only cross-checked ones.
 ## Data tiers (authority order)
 1. **Eval-page sentence** (authoritative, SSR, per eval page `/evaluations/<slug>`): `"X scores the highest on <eval> with a score of N%, followed by Y ... and Z ..."` → top-3 rows with verbatim model names. Regex trap: model names contain `5.5` — capture names with `[^.;]` truncates at decimals; use targeted extraction per page, verify each value against the page's `66.9`-style raw text.
 2. **Model-page chart labels** (per-model values, incl. the page's own model): charts are client-side Recharts (NOT in raw HTML, NOT via /api/ — keyless API 404s). Browser: `browser.open({name,url,wait_until})`, scroll full page in ~0.15 steps (lazy render), then `tab.evaluate` (NOT `tab.run` — that's Bun world):
   - names = `<foreignObject>` div text, x from parent `g[transform]` `translate(x,...)`;
   - values = `g.recharts-label-list text` attrs;
   - **zip by sorted-x index** (nearest-x pairing is off by half a bar; index-zip verified against published tops).
 3. `sync-aa` free Data API for headline indices — needs `AA_API_KEY` (unset in ~/.secrets as of 2026-10-11).
 ## Cross-check law (mandatory before shipping chart-derived rows)
 Chart's top-3 zipped values must match the eval page's published sentence (e.g. Kimi 88.7→89, Elo 1866→68.3, Opus index 46). Two independent methods disagreeing = stop, re-anchor; geometry pairing (link-top→svg-top proximity) collides on adjacent cards — prefer sentence-vs-zip corroboration.
 ## Normalizations
 - Elo evals (GDPval-AA, AA-Briefcase): sentences publish raw Elo; store AA's published `(Elo−500)/2000`×100 (1866→68.3). Document in file header.
 - AA-Omniscience `eval: aa-omniscience` = the −100..100 Index (not accuracy); accuracy/non-hallucination charts corroborate (17%/7% ⇒ −60 arithmetically consistent).
 ## Known identities (2026-10-11 census, v4.3.2)
 - frank-archon lineage base = **Qwen3.8-Flash-Next** (`/models/qwen3-8-flash-next`), AA index 40, class median 18. NOT Qwen3-Next-80B-A3B-Instruct (index 10, 2025 family) — first seed got this wrong; verify lineage in `docs/endpoints.md` before labeling `kind: base`.
 - Base per-eval (chart): SciCode 51, HLE 38, AA-LCR 80, TB-4.0 25, GDP.pdf 16, CritPt 11, Briefcase 54, GDPval 56, AutoBench 56, Omniscience −10.
 - Frontier anchors: SciCode Opus 5.5 Max 66.9 (board flagged "under review" — travel this caveat with any SciCode delta); HLE Opus 61.4; AA-LCR Kimi K3 88.7; TB Sonnet 63.6; CritPt GPT-6.1 Sol 32.3.
 ## Edit traps
 - YAML surgery via `edit`: replacing a line range that included a top-level key (`schema_version`/`models:`) silently duplicates or deletes the anchor → Zod error `expected 1 / received undefined`. After any header edit, `grep -n "^schema_version\|^fetched_at\|^index_version\|^models:"` must show exactly one each.
 ## Ship loop
 1. `bun -e 'import { loadAaFile, loadAaRefs } from "./src/aa"; ...'` schema-parse gate.
 2. `bun src/cli.ts report <run-id>` (takes bare id, NOT a path) → trio in `reports/<host>/<id>/`.
 3. Verify `data.json .aa_reference` non-empty, per-eval coverage, delta columns.
 4. log entry in `docs/log.md` + atomic commit + push (local gitea OK).
 5. `browser.close({name})` — headless tabs are shared/retained.
@@ -0,0 +1,64 @@
 ---
 name: amd-apu-vulkan-tenant-onboarding
 description: "Add a ggml/Vulkan inference tenant to an AMD APU (gfx1151 / Strix Halo iGPU) that already serves another engine: APU memory census, RADV heap gate, render-node resolution, build-side glslc/ICD deps, co-tenancy measurement."
 ---
 Use when a ggml-based engine (llama.cpp, qwentts.cpp, anything built on ggml) must move from CPU to the **iGPU** of an AMD APU (gfx1151 / Strix Halo / Ryzen AI Max) that **already serves another engine on the same card**. Answers two questions only a booted host can: what gate the second tenant must clear, and which files the build needs to clear it.
 ## 1. The usual VRAM reasoning is wrong on an APU
 `/sys/class/drm/cardN/device/mem_info_vram_total` reports a small **carve-out** (2 GiB class), and `rocm-smi`'s "dedicated" figure is not the working set either. The real working set lives in **GTT / system pages**: `/proc/meminfo` → `GTT` and `System pages`. A second GPU tenant therefore consumes host RAM from the same pool the first tenant's weights and the OS use — no supplementary groups, no separate aperture to reserve.
 - Price the tenant from a **booted** footprint, never from `weights + KV + buffers`: on an APU the compute buffers and any projector ride on GTT, which is host RAM; check `free` *after* the load, not before.
 - Never subtract a "dedicated" figure from it to find headroom.
 - Unheld fabric clock (`pp_dpm_mech` = `auto`) is a hazard only when the NPU joins too; a pure iGPU pair is unaffected — check it before adding a third tenant.
 - Swap on a host with GPU tenants protects co-tenants; paging a KV pool is worse than the OOM it prevents.
 ## 2. The gate that decides feasibility: the RADV heap a container sees
 `rocm-smi` and `free` cannot see this number; only a container off the **engine's own base image** can:
 ```bash
 # one-off container, no model, no load, no compute — safe beside production
 podman run --rm --device /dev/dri --group-add keep-groups <engine-base> bash -c \
  'apt-get update -qq >/dev/null 2>&1; apt-get install -y -qq --no-install-recommends mesa-vulkan-drivers vulkan-tools glslang-tools >/dev/null 2>&1; vulkaninfo --text'
 ```
 Read `VkPhysicalDeviceMemoryProperties` → the `DEVICE_LOCAL` heap size. On a hybrid Strix Halo box Mesa splits the aperture (~1/3 : 2/3), so `DEVICE_LOCAL` is the budget the ggml tool will actually allocate against — measured 77.33 GiB *with the first tenant loaded*, against a 2 GiB DRM carve-out. Two traps, both measured:
 - `vulkaninfo --batch` does not exist in Ubuntu 24.04's `vulkan-tools` (prints help, exits 1). Every `vulkaninfo` parse needs `--text`.
 - The container may have **no NVIDIA ICD**, so Vulkan index `0` *is* the iGPU — but do not trust ordering by index: `--text` and read `deviceName` + `driverID` (`RADV_GFX1151` vs `NVIDIA`). A hand-picked `/dev/dri/renderDN` is worse than useless on a hybrid host: **`renderD128` there is the NVIDIA card and `renderD129` the amdgpu iGPU**; resolve the node with `readlink -f /sys/class/drm/renderD*/device/driver` and pass `/dev/dri` wholesale, letting the driver pick by name.
 - A rootless container that drops its supplementary groups enumerates **nothing**. `--group-add keep-groups` (quadlet: `GroupAdd=keep-groups`) plus the host udev rule that makes the render nodes group-writable is the whole requirement; `--device /dev/dri` alone is not enough.
 ## 3. Build-side deps: the configure fails before the device ever matters
 ggml's `src/ggml-vulkan/CMakeLists.txt` requires, in order: `find_package(Vulkan COMPONENTS glslc REQUIRED)` then `find_package(SPIRV-Headers CONFIG REQUIRED)`, and it compiles its shaders with **glslc**, never `glslangValidator`. On Ubuntu 24.04 (measured against the digest-pinned `ubuntu:24.04` base, 2026-10-19):
 - `glslang-tools` ships `glslangValidator` and **NOT `glslc`** → `command -v glslc` empty, `find_package(Vulkan … glslc REQUIRED)` fails, and the Vulkan backend silently never exists.
 - The package is the standalone **`glslc`** (universe, `2023.8-1build1`). Working build-stage set: `libvulkan-dev glslc spirv-headers` — `libvulkan-dev` provides `vulkan/vulkan.h` + the `VulkanHeaders`/`VulkanLoader` CMake configs `find_package(Vulkan)` resolves to, `spirv-headers` ships `/usr/share/cmake/SPIRV-Headers/SPIRV-HeadersConfig.cmake`. A configure probe in the pinned base prints `Found Vulkan: … found components: glslc` then `Including Vulkan backend`.
 - **The archive's glslc is old.** 2023.8 compiles `GL_KHR_cooperative_matrix` (the path ggml's vectored quantized matmul needs) but reports `cooperative_matrix2`, `integer_dot_product`, `bfloat16`, `float_e2m1/e4m3` as unsupported, so those shader families are compiled out. If a Vulkan prefill reads as inexplicably slow, suspect the **shader compiler before the device**; the fix is a pinned glslang build passed as `-DVulkan_GLSLC_EXECUTABLE=<path>`, not a different runtime.
 - Runtime stage needs the loader **and an ICD**: `libvulkan1` + `mesa-vulkan-drivers`. Loader-without-ICD enumerates zero devices, and ggml-based servers die in device lookup — often *after* reading the weights, so the journal reads like a model fault.
 - Ship **no NVIDIA ICD** on purpose: one Vulkan device in the enumeration is what makes the *name* `Vulkan0` safe to write into config. Prefer the name over an index in every flag.
 ## 4. Prove enumeration without allocating anything
 Do not boot a scratch second engine beside production to ask which devices exist — a second model load is a real GPU tenant, and fleet law stops that. Instead run the binary with a device name that cannot exist and read its error; it names what it enumerated, with no allocation and no model resident:
 ```bash
 podman run --rm --device /dev/dri --group-add keep-groups --entrypoint /app/tts-server <image> \
  --model /dev/null --codec /dev/null --device NoSuchDevice 2>&1 | tail -20
 ```
 ## 5. The rollback must be a flag, not a rebuild
 Put the device in the env file as a value the entrypoint passes only when set, and make **set-but-empty** mean "pass no flag at all" — the binary's own default (CPU, always built) is the rollback. `: "${VAR:=default}"` is the WRONG form: `:=` fires on an empty value too, so the documented rollback line `VAR=` is silently rewritten back to the GPU and the only way out is a rebuild. Use:
 ```bash
 if [[ ! -v QWENTTS_DEVICE ]]; then QWENTTS_DEVICE=Vulkan0; fi
 ```
 (`podman`'s `--env-file` passes `VAR=` through as set-and-empty, and `source` does the same, so both readers agree.) Pin it in a test: empty device ⇒ the flag is absent from argv.
 ## 6. Co-tenancy measurement (only after the tenant is live)
 The gate is the **first tenant's** performance with a real request from the second in flight — not the second tenant's own speed. And price the tenant from a booted footprint, never from weights+KV+buffers: on an APU the compute buffers and any projector ride on GTT, which is host RAM; check `free` after the load, not before.
@@ -0,0 +1,77 @@
 ---
 name: audit-never-run-container-deploy
 description: "Audit a locally built podman/quadlet deploy path that has never actually run: prove base-image assumptions, env-file reader divergence, and image-hash coverage before the first deploy."
 ---
 # Audit a never-run container deploy path
 A deployable that has never been built or started has never been *executed*: every
 fault in it is invisible to tests that stub the runtime. Audit it as static code
 against the tools it calls, then prove each suspicion cheaply against the real
 tool. The faults worth hunting are the ones that **report success while doing
 nothing** — those are the ones that survive a green `/health` and a green e2e run.
 ## The three fault classes (all measured 2026-10-18, frank-tts-engine)
 1. **A command the base image does not ship.** e.g. `adduser` in a `RUN` line
   against a trimmed `ubuntu:24.04` — absent, and not pulled in by
   `ca-certificates curl libgomp1`. Dies at build time (loud), but only the first
   time anyone builds it.
   Prove it in the base, never from memory:
   `podman run --rm <base> sh -c "command -v adduser || echo absent; useradd --system --uid 10000 --home-dir /app --shell /usr/sbin/nologin tts && id tts"`
   Note the accepted cosmetic warning (`uid 10000 is greater than SYS_UID_MAX 999`)
   in a comment, or a future agent "fixes" it by dropping `--system` and the uid
   stops matching the sibling container.
 2. **Two readers of one env file disagree.** systemd units that pass
   `EnvironmentFile=` hand it to podman `--env-file`, which does **no shell
   parsing** — it takes the literal remainder of the line — while bash `source`
   strips one quoting layer. So `WARM_TEXT="Warm up, one two three."` reaches the
   container *with its quotes*, and a script that interpolates it into a JSON body
   produces invalid JSON: the container boots, `active`, every voice registered,
   every voice cold. Fix in the consumer: strip exactly one matched pair **only**
   when both ends are the same quote AND the inner content carries another quote or
   backslash (never mangle a value that legitimately contains quotes), then escape.
 3. **A build-skip hash that under-covers the image.** `build_compose_image`-style
   helpers skip `podman build` when a label hash matches; hashing the `Containerfile`
   alone means editing a `COPY`'d app/script rebuilds **nothing** — deploy reports
   success, `/health` answers, container serves old code. Each case arm must name
   the paths its `Containerfile` copies (`extra=(…)`) and hash Containerfile+extras.
   Arms that have no extras keep their old hash, so they do not needlessly rebuild.
 ## Test it as behaviour, never as a grep of the handler
 - Drive the **real** function: `awk '/^build_compose_image\(\) \{/,/^\}/' deploy-remote.sh > bci.sh`,
  `source` it, put a stub `podman` first on `PATH`, assert the observable question —
  *did the deploy ask podman to build, or did it skip?*
 - Stub traps that cost real time: podman is invoked `podman image inspect <image> --format …`
  so the tag is **`$3`**, not `$2`; tags contain `/` so a state file named after one
  needs `${tag//\//_}` or the write silently lands in a nonexistent directory and
  every image looks permanently unbuilt; `--label cfhash=…` arrives **before** `-t <tag>`,
  so collect the label and write it after the arg loop.
 - For an env-file bug, write one test that reads the file **both** ways — `source`
  and the `--env-file` way (parse `KEY=literal remainder`) — and assert the program
  receives the same value in both shapes, including a value that carries its own
  quotes and a backslash. A suite that only sources the file is how the bug shipped.
 - Prove red: `git show HEAD:scripts/deploy-remote.sh > scripts/deploy-remote.sh`,
  run the new test (must fail at the exact intended step), restore. Keep each fix in
  its own commit and run the seam at each one so the branch bisects.
 ## Base-image and host facts to check while auditing
 - `useradd` lives in `login(1)` (base carries it); `adduser` does not.
 - Rootless podman **cannot raise rlimits** — `--ulimit nofile=…` above the host hard
  limit dies at container create, not at runtime.
 - A referenced `Network=` `.network` file the generator cannot find means the
  container unit is **not produced at all**.
 - Two containers talk by DNS name only if they attach to a **common** network;
  check both unit files rather than trusting a comment that says they share one.
 - Container DNS name + the network that owns it, never `host.containers.internal`
  or a published loopback port, for service-to-service traffic.
 ## Do not
 - Do not deploy the audited thing because the audit is finished: first build of a
  heavy image (recursive source clone ~10 min) plus a new unit on a host serving
  people is the operator's call.
 - Do not add a Prometheus target for a container with no `/metrics` — say the probe
  is a decision (blackbox HTTP), do not fake a scrape.
@@ -0,0 +1,61 @@
 ---
 name: audit-subagent-deliverables
 description: "Integrate subagent-written code safely: line-by-line audit, mechanical gates (bash test/lint), adversarial-review-report triage, resource-safety pass (fd/memory), and cutover with running-process restarts."
 ---
 # Audit subagent deliverables
 A subagent that wrote code is a source of plausible output, not a verified change. Integrate it the way you'd integrate an untrusted PR — with extra suspicion, because the author is an agent that shares your blind spots and its prose is more confident than its evidence.
 Order of operations: read everything → gates → tests (as evidence, not proof) → resource-safety pass → fix in-place → cutover.
 ## 1. Read every produced file, line by line
 Full file, not a diff skim. You are the reviewer who must catch the line the author never thought about.
 ## 2. Mechanical gates before logic review
 ```bash
 bash -n <script>                 # syntax (scripts)
 bunx tsc --noEmit                # types (TS)
 bun test                         # suite
 ```
 Run the suite for information, not as the stopping point — it only proves the author's own scenarios.
 ## 3. Hunt the three classic agent defects
 - **Quoting bugs:** `set -e` + `"${@/$p/$r}"` = substitution regex containing user input (bash can't escape `/` in a `${var/re/pat}` pattern: `/` reads as the pattern/replacement separator). Fix with a separator absent from inputs (e.g. `%`) and `printf '%q'` for shell-interpolated values.
 - **`cd` assumptions:** parallel `runShell` calls share one CWD (pool mode). Any command sequence that assumes CWD (e.g. `git -C .` after a sibling's `cd`) must use explicit absolute paths.
 - **Unbounded resources:** every fd opened must be closed on ALL paths (success, throw, validation fail) — `using` for fs.sinks (closes on throw; sinks are `AsyncDisposable`, not `fs.FileHandle`, no `.close()`); bounded `Map` for caches (`MAX` + FIFO eviction); explicit caps (lines read, file sizes).
 ## 4. Check the test file is real
 Tests that assert internal state (`expect(wcwd).toBe(...)`) over output contracts; tests of mock echo; tautologies. Delete them per house rules, keep behavior contracts.
 ## 5. Cutover audit (repo-wide)
 `grep -r` the symbol namespace the subagent touched — `wcwd`-style globals are the classic blast radius. Grep every `cd`/`process.chdir` site and verify each paired command sequence uses explicit paths. Stale comments describing the old design must go — comments that lie are time bombs for the next reader.
 ## 6. Cutover restarts running processes
 A code fix on disk is NOT live in any process that loaded the file at spawn (bun/node load-at-spawn). After shipping fixes: restart every long-running supervisor/daemon/UI-server that carries the affected code path; prefer takeover protocols (stale-pid detection) that make restarts cheap. Symptom of forgetting: "fixed" code producing old-code symptoms in production (observed: 812 poisoned ledger rows).
 ## 7. Triaging an adversarial REVIEW report (not code)
 When a subagent produced findings, treat each finding as a hypothesis with a base rate ~40% (measured over 3 rounds, 2026-10):
 1. **Walk every finding end-to-end against the CURRENT tree** before accepting — cite file:line yourself. Reviewers frequently read a mid-edit snapshot; many findings are stale by construction.
 2. **Classification that kills most findings:**
   - *Stale read* — code changed during review; verify against live lines.
   - *Inverted logic* — "failed rows are skipped" when the filter makes failed rows RETRY. Re-read the filter.
   - *Unreachable* — trigger requires breaking a stated design law (single-worker, append-only). Not a defect.
   - *By-design* — the reviewer labels a spec law a bug (serial execution, non-stream client). Check the spec, not the reviewer's confidence.
   - *Constant-trust* — "XSS via manifest field" where the field is git-pinned config; "path traversal via REMOTE_TMP" where it's a hardcoded const. Ask: what untrusted input reaches this sink?
   - *Self-refuting* — the reviewer's own probe output disproves its claim (raw==dedup probe in a "dedup" finding). Quote it back.
 3. **Acceptance bar:** concrete trigger with real inputs + full path walked. Real accepts cluster in: resource caps (pids/timeout/awaited-cleanup), honest labels (default signatures), escaping discipline, self-healing probes.
 4. **One-line verdicts + evidence per finding**, shipped in the commit message; calibration section ("genuinely solid") accepted as free verification of past fixes.
 ## Verification (the non-negotiable)
 Build/run the real artifact with its real inputs. Observe behavior at the seams:
 - concurrent calls → no CWD races;
 - resource ceilings → caps enforced;
 - cleanup → no fd/pid/dir leaks;
 - security → injection probes inert (quotes, slashes, metachars);
 - normal case → output identical to pre-audit.
 ## Evidence (2026-10-07 + 2026-10-10/11 sessions)
 - Shell-engine subagent: 426 LOC, `bun test` 39/39 green. Line-audit found: 5 leaked fds per call (`fd` sink never closed), CWD-race in `git -C .`, `set -e` + `${@/\/g\//}` slash-escaping bug, unbounded 10k-entry cache, 45s timeout on git-status.
 - Review-triage census over 3 blind adversarial rounds (same repo, ~41 findings): accepted 9, rejected ~32 — rejects dominated by stale reads (protocol rewritten mid-review), inverted filter logic, unreachable-under-law triggers, base64-alphabet "quote injection" (charset has no quotes), SIGPIPE non-leaks, "no memory cap" quoting the `--memory 4g` line above the claim. Real accepts: fork-bomb pids cap, stalled-ssh upload cap, stale-flag self-heal probe, honest census label, freshness gate on pid reuse.
 - Poison-law incident: sandbox fix shipped while supervisor ran old build → 812 rows graded by the dead protocol; takeover made recovery cheap. The restart step (#6) exists because of this.
@@ -1,6 +1,6 @@
 ---
 name: authentik-provision-fleet-user
-description: "Provision or audit an Authentik user on Dankclaw (auth.franksdank.cloud): ak shell ORM drive, group set, behavioral login verify, stale-claim caveat."
+description: "Provision or audit an Authentik user on Dankclaw (auth.franksdank.cloud): ak shell ORM drive, group set, behavioral login + entitlement verify, docs census record, stale-claim caveat."
 ---
 # Provision an Authentik user on Dankclaw
@@ -33,10 +33,29 @@ from django.contrib.auth import authenticate
 assert authenticate(request=None, username="X", password="...")
 assert authenticate(request=None, username="X", password="nope") is None
 ```
 4. Verify the downstream claims resolve — `app_entitlements` needs an `Application`
   instance (look it up by slug, `open-webui`), and compare against the precedent user:
 ```python
 from authentik.core.models import Application, User
 app = Application.objects.get(slug="open-webui")
 for n in ("ridley", "X"):
    u = User.objects.get(username=n)
    print(n, sorted(e.name for e in u.app_entitlements(app)), u.is_superuser, u.path)
 ```
 5. Stale-claim check + docs record (repo law: the vault is the source of truth):
 ```bash
 ssh dankclaw "podman exec authentik-postgres psql -U authentik -d authentik -tAc \
  \"SELECT count(*) FROM authentik_providers_proxy_proxysession WHERE session_data->'claims'->>'preferred_username' IN ('X')\""
 ```
 Then commit two doc edits (NEVER write the password into any file): the census
 sentence in `Infrastructure/Authentik.md` (human-user template bullet — append the
 new `pk`s + creation date) and a dated entry in `serverAppConfigs-docs/log.md`
 (what was created, groups, how it was verified, proxysession count, downstream lag).
 `./tests/run.sh` must pass before commit (docs completeness + link-integrity seams).
 ## Rules
 - No `User.create_user`; `is_superuser` is a group-derived property, not a constructor kwarg (raises `TypeError`). `path` defaults to `users`.
 - Guarded-vhost access = any authenticated user (all proxy providers use implicit-consent); groups are consumed downstream: `homepage-admins` (Caddy `/admin` header gate), `openwebui_users`/`_admins` (roles claim), `jellyfin_users`/`_admins` (LDAP outpost). EXCLUDE admin groups from a plain user; ask before granting `homepage-admins`.
- Group add after a login → Caddy RBAC can 403 on the outpost's cached claims; purge that user's rows: `DELETE FROM authentik_providers_proxy_proxysession WHERE session_data->'claims'->>'preferred_username' = 'X';` (in the `authentik-postgres` container) — next visit re-authorizes silently.
+- Group add after a login → Caddy RBAC can 403 on the outpost's cached claims; purge that user's rows: `DELETE FROM authentik_providers_proxy_proxysession WHERE session_data->'claims'->>'preferred_username' = 'X';` (in the `authentik-postgres` container) — next visit re-authorizes silently. Groups set BEFORE any login → nothing to purge (count is 0).
- Jellyfin visibility rides the LDAP outpost cache; expect a lag.
+- Jellyfin visibility rides the LDAP outpost cache; expect a lag. OpenWebUI mints a first-time SSO login as role `pending`.
 - Look up flows by slug, not name. Do not rotate `AUTHENTIK_SECRET_KEY` to fix claim issues.
@@ -0,0 +1,42 @@
 ---
 name: bench-arm-provenance-recovery
 description: "Before calling a leftover LLM bench drop-in a rogue/hijack, reconstruct whether Frank ordered and measured that arm: omp archive prompt timestamps + journald print_timing for the exact pid, then land the verdict in the repo."
 ---
 Use when a live service boots a payload you did not configure (stale `systemd` drop-in / `*_ENV_FILE` arm env) and the docs — or your own compaction-inherited context — call it "unfinished", "armed but never measured", or "hijack". Do NOT report that until proven: the arm may be an ordered, measured, approved configuration whose record lived only in `/tmp` + journald.
 ## Why this exists
 2026-10-18 `frank-zealot`: a `frank-zealot.service.d/ptq1.conf` drop-in made the cutover deploy boot a different model at a different shape. I reported it as an unfinished experiment. It was actually the 27B PTQ1_0 arm Frank ordered at 02:36, that served production 03:14:39→03:38:57, and whose numbers existed only in tool output that context compaction later dropped.
 ## Step 1 — recover the ORDER (the harness archive, not memory)
 `eval` with the `archive` prelude:
 ```python
 ps = await archive.prompts()          # searchable prompt history, survives compaction
 # filter for the payload name / repo URL keywords, print p['at'] + p['text'][:90]
 r = await archive.session("<sessionId>")   # full session record
 recaps = await archive.recaps()             # recap stamps — check they postdate the window
 ```
 `archive.prompts()` keeps **user prompts with ISO timestamps** even when the middle of the transcript was dropped. Timestamp every instruction: ordered → measured → superseded. Convert to local (`UTC−7` here) before quoting. A recap older than the instruction proves the recap layer never covered the window.
 ## Step 2 — recover the MEASUREMENT (journal, per pid)
 The engine's own per-request timings are the record; they outlive `/tmp` env files.
 ```bash
 ssh dank@<host> 'journalctl -u <svc> --no-pager' | grep -F 'serve-<svc>.sh[<PID>]' \
  | grep -E 'prompt eval time|eval time' | awk '... median per task ...'
 ```
 - Pin the **pid** (`sh[NNNN]`): `--since` windows alone pull the previous process's numbers too.
 - llama.cpp format: `prompt eval time = 1234.56 ms / 100 tokens (…, 81.03 tokens per second)`; decode rows are `eval time = … ms / N tokens (…)`. Multiple spaces between `task`/`eval` break naive regexes — match `task\s+(\d+)\s+prompt eval time` exactly, or parse both labels separately.
 - Filter pathological rows: generations running concurrently on other slots, or ending in a 4-byte EOS, read ~4× low. Report clean single-stream probes (≥200 generated tokens) and label the rest.
 - Cross-check the boot banner for the payload identity (`type ptq1_0: 402 tensors`, KV ledger, slot/ctx lines) — that proves *which* shape that pid served.
 ## Step 3 — adjudicate, then land it in the repo
 Write the verdict in the same session you derive it: runbook deploy-ledger section, `log.md` dated section, the arm script's header comment, and the AGENTS.md law. `/tmp` and journald are not records — that absence is what makes the next agent misread an approved arm as a rogue one.
 ## Traps
 - `mask` fails on a relinked unit; never `systemctl disable`; retire drop-ins to `~/.AGENTTRASH/<date>-<topic>/` + `daemon-reload` (recoverable, not deleted).
 - `/health` 200, `/v1/models` echoing the alias, and a green e2e gate all fail to read the payload — check `systemctl show <svc> -p DropInPaths` (must be empty), then `tr '\0' ' ' </proc/$(pidof llama-server)/cmdline`, then the boot ledger.
 - Verification sequence that is honest: correction commit must quote commands you ran; state `[INFERENCE]` for anything the journal does not show.
@@ -0,0 +1,22 @@
 ---
 name: bench-harness-fault-census
 description: Attribute benchmark failures to harness vs model via exception-signature census before trusting any score; python-grader fault signatures and fixes
 ---
 # Rule (from 2026-10-10 frank-intelligence-bench incident, 3 harness faults found)
 An LLM benchmark score is VOID until every failure signature is attributed to the MODEL. Run the census before quoting any number.
 # Procedure
 1. Aggregate graded rows per eval; for each failed grade extract the LAST python exception signature:
   regex `(\w+Error|\w+Exception): (?:name '([^']+)' is not defined|No module named '([^']+)')?` → sig = `Type: detail`.
 2. Indict the harness (not the model) when:
   - `NameError: target` / `NameError: targets` in any count → expected-value bindings never reached the tests (gold data file missing/unstaged).
   - `ModuleNotFoundError: <grader package>` (e.g. `scicode`) → grading deps missing from the execution image.
   - ≥10 failures sharing ONE signature at >50% share → systematic fault; audit the protocol (e.g. markdown fences reaching an exec-based extractor — `SyntaxError` storm; strip ``` fences before feeding model text to graders that exec raw code).
   - >50% of generations fail → endpoint/transport fault.
 3. Real model failures look heterogeneous: AssertionError/AxisError/NameError of the model's OWN undefined names.
 # Companion checks
 - Prove the grading path with a gold-solution integration test BEFORE trusting live scores: gold must PASS end-to-end (FIB_INTEGRATION=1 pattern).
 - Quarantine poisoned ledgers (.AGENTTRASH) rather than deleting; census them to root-cause.
 - Expect-score sanity: mixed PASS/FAIL with model-side signatures = real signal, even if the % looks low.
@@ -0,0 +1,32 @@
 ---
 name: bounding-subagent-runtime
 description: "Cap and diagnose runaway or hung omp subagents: task.maxRuntimeMs, softRequestBudget, maxConcurrency, maxRecursionDepth (the 0-trap), per-provider in-flight ceilings."
 ---
 ## When
 Subagent runs long, fan out too wide, or you must (re)declare the fleet's subagent limit policy. Also when asked "what limits can subagents have".
 ## Read first
 - Repo KB page `omp-docs/pi/subagent-limits.md` — the live policy of record (values + rationale + deliberately-not-set list). Do not re-derive; read it.
 - `cfg://task` and `cfg://providers/maxInFlightRequests` — effective values, not the stock defaults.
 ## The knobs (cfg:// writes; `/save` suffix persists)
 | Knob | Effect | Gotcha |
 |---|---|---|
 | `task.maxConcurrency` | session semaphore; excess queues | stock default 32 — "2" is not a default |
 | `task.maxRecursionDepth` | nesting cap | predicate is `depth < n`; **1 = children cannot spawn (correct for "no nesting"); 0 disables spawning for the MAIN session too — never reach for 0**; negative = unlimited |
 | `task.maxRuntimeMs` | hard wall clock, overrun = `aborted` | default 0 = off |
 | `task.softRequestBudget` | wrap-up notice at N, force-yield at 1.5N | scout/sonic may impose lower built-ins |
 | `task.agentIdleTtlMs` | park idle finished agents | `<= 0` disables parking |
 | `providers.maxInFlightRequests` | concurrent LLM requests per provider id | keys are the quoted block labels from `agent/models.yml` (e.g. `"llamacpp (dankclaw-3090)"`), flat map lookup; absent/≤0 = unlimited; scope = this machine's config root only — other workstations and non-omp clients are NOT counted; excess queues |
 | `tools.maxTimeout` | ceiling on any agent-requested tool timeout | kills `timeout: 0` runaways |
 | `task.isolation.enabled` | makes per-spawn `isolated` flag available | opt-in per spawn, not a blanket sandbox; needs git repo; off in plan mode |
 | `task.completionProbe` | periodic completeness side-requests | token sink on shared endpoints |
 ## Verify semantics from the bundle, not the label
 Setting descriptions lie by omission. `~/.bun/install/global/node_modules/@oh-my-pi/pi-coding-agent/dist/cli.js`:
 - depth gate: `grep -o '.\{130\}xC\b.\{130\}'` finds `U_(n,s)`; `grep -o 'function U_(e,t){.\{0,60\}'` → `e<0||t<e` (n=cap, s=taskDepth).
 - in-flight lookup: `grep -o '.\{150\}axInFlightRequests.\{200\}'` → flat `[providerId]` lookup, non-number/≤0 = unlimited, clamp ≥1.
 ## Landing a policy change
 cfg `/save` writes persist immediately; `agent/config.yml` is machine-live tier (heartbeat commits it). Human-facing policy changes land as an `omp-docs` page update via branch → PR (docs tier), `git worktree add` from `origin/main` if the current checkout is branch-locked by workspace policy.
@@ -0,0 +1,24 @@
 ---
 name: cfg-approval-timeout-recovery
 description: "Use when a cfg://.../save write fails with \"user did not answer the approval prompt\": the settings-approval dialog has a hardcoded 10 s timeout and no config key; recover via direct config.yml edit once the user has approved the change."
 ---
 # Recovering from cfg:// approval-prompt timeouts
 ## Facts (verified in bundle 2026-10-18)
 - Settings-write approval dialog timeout is **hardcoded 10 000 ms** (`timeout: JKl`, `JKl=1e4`, countdown class treats arg as ms) in the omp `dist/cli.js` bundle. **No config key exists** for it (checked full `cfg://` registry).
 - `ask.timeout` is a DIFFERENT gate (ask-tool auto-select; 0 = wait forever). It does not govern cfg approvals.
 - A timed-out approval silently auto-denies: session-only value stays applied, `config.yml` unchanged. Error says "nothing changed; it stays <value>. NEVER retry unless the user asks."
 - Related: `features.unexpectedStopDetection: smart` injects forced-continue `<system-injection>`s on text-only turns ending in a promise to act ("Task incomplete: MUST call the next concrete tool now"). Set `mechanical` (upstream default) or `none`; `smart` drives agents into junk subagent spawns to satisfy the nudge.
 ## Recovery procedure (only when the user has already explicitly approved the change)
 1. Do NOT re-issue `cfg://<key>/save` after a timeout unless the user explicitly asks again — the harness forbids it.
 2. Edit `~/.omp/agent/config.yml` directly:
   - `grep` the setting key to locate it; read surrounding lines.
   - surgical `edit` of the single line.
   - validate: `python3 -c "import yaml; yaml.safe_load(open('/home/blank/.omp/agent/config.yml'))"`
 3. State that the file was edited directly because the invisible 10 s dialog ate the user's approval, and offer the `omp config set <key> <value>` one-liner as the user-run alternative for future.
 ## Prevention
 - Before any `cfg://.../save`, warn the user a ~10 s dialog is about to appear and to answer immediately.
 - Bundle-fact lookups: `PKGDIR=$(dirname $(readlink -f $(command -v omp)))/..`, then grep `dist/cli.js` for the message string, walk to the call site, resolve minified constants with `grep -oE '[,;]CONST=[^,;)]+'` (`1e4` = 10000).
@@ -0,0 +1,37 @@
 ---
 name: characterization-fixture-engine-cutover
 description: "Swap a path→service planner/mapping engine behind a golden fixture: capture, delta-reduce, document deltas, flip grep seams to behavioral, add render/drift gates, validate Caddyfile renders, Gitea PR URLs (serverAppConfigs cutover playbook)"
 ---
 Playbook for replacing a hand-maintained mapping engine (deploy planner, seam mapper, allow-lists) with a data-driven one without changing observable behavior. Proven on the 2026-10-13 `shared/services.yml` + `scripts/service-map.py` cutover (921 deltas → 17 intentional → green; 408/408 bats).
 ## 1. Capture the characterization fixture FIRST
 - Enumerate every path the old engine sees: all tracked files x all targets (`git ls-files`), plus hand-added edge paths (retired files, cross-host paths, shared networks).
 - Run the OLD engine on each, record `path<TAB>target<TAB>services` to `tests/fixtures/*-golden.tsv`. Old engine = current `deploy-plan.py` before edits.
 - This fixture is the contract; the new engine must reproduce it except documented deltas.
 ## 2. Cut over, then delta-reduce with the fixture
 - Diff new-engine output vs fixture; bucket every delta into: engine bug / intentional change / fixture staleness.
 - Engine bugs found this way (generic classes): `in` membership on dict-of-tuples, host-scoping of relative directory keys, riders/children resolved only in the changed file's own directory, stem collisions between unit files and generated artifacts (`.network` stem == service dir stem), `.network` files entering the unit branch by stem match.
 - Intentional deltas get documented individually in the commit message; NEVER batch-accept a delta count.
 - Regenerate the fixture LAST, from the new engine, and record the delta count + reasons in the commit.
 ## 3. Flip text-grep seams to behavioral calls
 - Old seams that grep a config file for the mapping (`grep -q 'dankclaw:hermes-webui'`) die silently on cutover. Replace with a call to the new engine: `run python3 scripts/service-map.py allows --host H --service S; assert_success`.
 - Vhost-scoped content greps (Caddyfile awk blocks) → grep the new canonical form (`import guarded`), not the inlined chain.
 ## 4. Renders + drift gates
 - Config artifacts that were hand-maintained mirrors (node-exporter quadlet pair, pihole addn-hosts) become `service-map.py render <name> --host H` artifacts; a drift test asserts tracked-file == render output.
 - Renderers must emit exactly what the consumer parses: dnsmasq `addn-hosts` treats inline `# comments` as hostnames — render no trailing comments.
 - Named-snippet collapse (Caddyfile guard chain): the snippet MUST be defined before the first site that imports it (put `(guarded)` right after the global options block), or real caddy reports `File to import not found`.
 ## 5. Suite + deploy gates
 - `./tests/run.sh` fully green before each rank commit; one atomic commit per rank.
 - Deploy is service-scoped: `deploy.sh <host> --service <svc>`; never a fleet drain for one service. The Playwright e2e gate runs inside deploy.sh against the live fleet.
 ## Repo-specific gotchas (serverAppConfigs)
 - Validate the Caddyfile with stock `caddy:latest` by DELETING the whole `acme_dns porkbun { ... }` block (`awk 'NR<53 || NR>56' dankclaw/Caddyfile`). A `sed s/acme_dns porkbun {/acme_dns acme {/` variant that drops the `{` swallows the following tokens into the global block and fakes an "import not found" on `(guarded)` — debug sed swaps with a minimal repro file before blaming the config. Stock-image `dns.providers.porkbun` unregistered + basicauth `REPLACE_WITH_HASH` base64 errors are the expected endpoints of a clean parse.
 - Gitea: branches with `/` 404 on `/compare/main...wt%2F...` — use the push-hook URL `…/pulls/new/<branch>`; private repo returns 404 to anonymous curl, which proves nothing about the page.
 - `test-changed.sh` contract: new seam selection ⊇ old selection per path; unmapped repo path must `die`, never pass silently.
 - Retire-to-trash: retired files (compose.yaml, dead templates, dead bats) → dated `.AGENTTRASH/YYYYMMDD-topic/` beside them; every repo sweep must exclude `.AGENTTRASH`.
 - bash `test -f a b c && ! test -e d` is invalid syntax (test takes one operand per operator); use `ls a b c` + separate `ls d` to census artifacts.
@@ -0,0 +1,30 @@
 ---
 name: corpus-voice-skill-rewrite
 description: "Rewrite a skill to emulate an author corpus's voice: full read, style-DNA distillation from writing-for-agents levers, positive-phrasing pass, sharpened completion criteria"
 ---
 # Corpus-voice skill rewrite
 Rewrite a skill so it reads as if a chosen author wrote it. Done for `grilling` against the `mattpocock/skills` corpus (2026-10-18, command-center PR #20); behaviour preserved, voice swapped.
 ## Where the corpus lives
 Installed third-party skills: `~/.agents/skills/<name>/SKILL.md` (the skills-CLI global store; `~/.agents/.skill-lock.json` names sources). Whole mattpocock corpus ≈ 2,800 lines — small enough to read inline in ~4 `cat` batches via bash; do NOT delegate the reading, style lives in the exact prose.
 Read the author's own meta-skill FIRST if one exists (`writing-for-agents` for mattpocock — it states his levers explicitly), then the corpus practicing them.
 ## Style DNA checklist (mattpocock; generalise per author)
 - **Leading words**: compact pretrained concepts repeated as tokens, never sentences (_red_, _seam_, _fog of war_, _brief_, _frontier_). Define each once, reuse everywhere. Prefer words already in the author's other skills so the corpus shares one language.
 - **Vocabulary-first**: bolded glossary terms, then used exactly; explicit "_Avoid_: component, service".
 - **Positive phrasing**: prohibitions rewritten as target behaviours; keep a prohibition only when no positive form exists (hard guardrails).
 - **Sharpened completion criteria**: fuzzy bounds ("understanding reached") → checkable + exhaustive ("frontier empty and nothing sits blocked", "one artefact per question, counted before sending").
 - **Zero history**: no provenance, attribution, or absorbed-from lineage in the body.
 - **No-op hunting**: delete harness defaults and anything the environment already confesses (formats, rendering, caps). Gotchas the environment CANNOT confess (exclusive dialogs, Esc-abort semantics) stay inline — they're the cache worth keeping.
 ## Procedure
 1. Read entire corpus; tabulate levers with per-skill evidence before writing.
 2. Rewrite preserving settled behaviour 1:1 — voice only; diff the two versions for semantic drift.
 3. Audit pass: grep the new text for history words (extracted/absorbed/from/upstream), machine-specific constants, repo-specific paths.
 4. Run repo checks, commit as `style(<scope>)`, note the lever→instance mapping in the PR comment so the reviewer can grade the emulation.
@@ -0,0 +1,43 @@
 ---
 name: dankclaw-boot-line-window
 description: "Change a Dankclaw kernel command-line parameter safely: tracked grub + installer, measured before/after A/B on live LLM traffic, post-boot gates."
 ---
 # Dank fleet kernel boot-line window (Dankclaw pattern)
 Kernel command-line state is **host state the deployer never owns**. The repo law
 ("all edits through git") still applies: fetch the live file, commit it, edit the
 tracked copy, apply with a script.
 ## Source of truth
 - `dankclaw/host/grub` — tracked copy of `/etc/default/grub`.
 - `scripts/set-dankclaw-bootline.sh` — the only door: diff → `sudo install -m 0644 -o root -g root` →
  `sudo update-grub` → print the **default `grub.cfg` entry** → reboot only on `--reboot`.
  Refuses any host whose `hostname -s` lacks `dankclaw`.
 - Decision record: `serverAppConfigs-docs/LLM/dankclaw-iommu-translation-off.md`.
 - `deploy-plan.py` maps `dankclaw/*` subdirs explicitly; a new `dankclaw/host/` path plans nothing (verify with a `--dry-run`).
 ## Procedure
 1. **Capture the before-arm measurement first** — you cannot get it back after the reboot.
 2. Fetch provenance byte-exact: `ssh dankclaw 'sudo cat /etc/default/grub' > dankclaw/host/grub` (never retype; a transcription dropped a leading `0`).
 3. Commit provenance, edit the tracked copy, commit the flip, push (**Gitea lives on Dankclaw — pull on the host before rebooting**), then `ssh dankclaw 'cd ~/serverAppConfigs && git pull --ff-only origin main'`.
 4. Install **without** `--reboot` first: it prints the `grub.cfg` default entry; confirm the token there before the irreversible step.
 5. `ssh dankclaw 'sudo systemctl reboot --no-block'`.
 6. **Poll on `/proc/uptime` + cmdline, never on ping** — the NIC answers ICMP for a minute after shutdown and sshd reset looks like "reachable".
   Gate set: `systemctl --failed` count 0 · `systemctl is-system-running` running · `/proc/cmdline` token · `ls /sys/kernel/iommu_groups | wc -l` · `cat /sys/kernel/iommu_groups/*/type | sort | uniq -c` · `systemctl is-active frank-dragoon frank-zealot` · `curl 127.0.0.1:7770/health` (listener binds only after the full load — poll up to 10 min).
 ## Measurement discipline (this is where windows get lied about)
 - Both arms must be **byte-identical traffic**. Engine-reported token counts are the identity proof (e.g. 59,024 prefill / 21,568 needle both boots).
 - `/tmp` is **tmpfs**: the reboot deletes `/tmp/halogen-eval`. Rebuild with `scripts/stage-frank-dragoon-eval.sh` (corpus 2,891 lines / 1,287,656 B is the check) — and run it via `bash -lc`, `uv` is in `~/.local/bin`, absent from a non-login PATH.
 - The 51.2 GB halogen n-gram table is page cache (`Pin::None`). A fresh boot has it cold and a cold table throttles prefill → `cat` it once (~40 s) before measuring. `WARM=1` in the staging script does this.
 - **Sampled decode on this engine is a useless single-sample instrument**: three repeats of the same request gave 31.8 / 46.9 / 47.8 t/s. Only prefill (cold) and needle-hit carry signal; anything else needs ≥3 repeats.
 - Bench law still bites: nothing else on the GPU; measuring *through* the live service is how dragoon/zealot are measured (a scratch server cannot share the card).
 ## Traps
 - `edit` `PUT N.:` can **insert instead of replace** — verify the range shrank, then `CUT` the leftover.
 - Body rows beginning with a markdown bullet (`- `) get auto-prefixed and land as `+- `; rewrite the block with `write` when that happens.
 - A long reboot fires `LlmEndpointDown` → Signal; Alertmanager has **no persistence**, so every active alert gets a fresh `startsAt` after boot — check `query_range` history before blaming the window for an alert.
 - `sudo podman ps` shows nothing for Dankclaw's rootless stack; `systemctl is-active caddy` is meaningless for quadlets. Use the public endpoints or `systemctl --user` as `dank`.
 ## Worked example (2026-10-18)
 `amd_iommu=off` → `iommu=pt` to restore the XDNA2 NPU. Result: cold prefill 1,585.1 → 1,616.0 t/s (**+2.0 %**, i.e. no penalty), needle hit/hit, `amdxdna` bound `0000:c6:00.1` (group 26 identity, PASID width 10). The 13–16 % figure it replaced had never been measured locally. Deferred on purpose: `pp_dpm_fclk` pin (nothing co-runs yet) and PerfOpt (needs Linux 7.4; Ubuntu 26.04 caps at `7.0.0-38.38`).
@@ -0,0 +1,81 @@
 ---
 name: dankclaw-expose-service
 description: "Expose a new service at *.franksdank.cloud on Dankclaw: quadlet container, Caddy site block, Pi-hole LAN record (custom.list), Porkbun public record; includes API vhost/volume gotchas proven on the ntfy deploy."
 ---
 # Expose a service on Dankclaw (franksdank.cloud)
 Proven end-to-end 2026-10-11 with ntfy. Four layers, each with a known trap.
 ## 0. Survey first
 ```bash
 ssh dankclaw 'ls ~/.config/containers/systemd/; grep -nE "franksdank|anubis" /home/dank/Containers/caddy/Caddyfile'
 ```
 - Caddy runs as quadlet `caddy.container`; config at `/home/dank/Containers/caddy/Caddyfile` (NOT `/etc/caddy` on host).
 - Sites fronted by `anubis:8923` get bot-challenge. **CLI/API publishers (ntfy, webhooks, git) MUST bypass anubis** — use the `gitea`/`ai` pattern (direct `reverse_proxy`).
 ## 1. Quadlet container (user `dank`)
 Write `~/.config/containers/systemd/<name>.container`:
 ```ini
 [Unit]
 Description=<name>
 After=network-online.target
 Wants=network-online.target
 [Container]
 ContainerName=<name>
 Image=<image>
 Network=dankclaw_default
 Volume=<name>-cache:/var/lib/<name>
 [Service]
 Restart=always
 RestartSec=5
 [Install]
 WantedBy=default.target
 ```
 `Network=dankclaw_default` ⇒ Caddy reaches it as `<name>:<port>`. Then `systemctl --user daemon-reload && systemctl --user start <name>.service`.
 Rootless podman: bare containers never boot-persist — quadlet is mandatory.
 ## 2. Caddy route
 Append site block (wildcard `*.franksdank.cloud` cert already issued via Porkbun DNS-01; no new cert work):
 ```
 <name>.franksdank.cloud {
 	reverse_proxy <name>:<port>
 }
 ```
 Validate, then reload in-place:
 ```bash
 podman exec caddy caddy validate --config /etc/caddy/Caddyfile --adapter caddyfile
 podman exec caddy caddy reload --config /etc/caddy/Caddyfile
 ```
 ## 3. LAN DNS (Pi-hole v6, container `pihole`)
 Traps, in order of wasted turns:
 - API is NOT at `127.0.0.1:8083/api` on the host port path — requests need `-H "Host: pi.hole"`.
 - `[[dns.records]]` in pihole.toml and `gravity.db` `domain` table: absent/unused on this box.
 - **Working location:** `/home/dank/Containers/pihole/etc-pihole/hosts/custom.list` (dnsmasq addn-hosts), format `IP FQDN`:
 ```bash
 echo "192.168.0.143 <name>.franksdank.cloud" | sudo tee -a /home/dank/Containers/pihole/etc-pihole/hosts/custom.list >/dev/null
 podman exec pihole pihole restartdns
 ```
 ## 4. Public DNS (Porkbun, for off-LAN clients)
 Keys: `/home/dank/Containers/caddy/env` (`PORKBUN_API_KEY`, `PORKBUN_API_SECRET_KEY`).
 ```bash
 curl -sL -X POST https://api.porkbun.com/api/json3/domain/api/create/franksdank.cloud \
  -H "Content-Type: application/json" \
  -d "{\"apikey\":\"$K\",\"secretapi\":\"$S\",\"name\":\"<name>\",\"type\":\"A\",\"content\":\"71.227.227.172\",\"ttl\":\"600\"}"
 ```
 - `json3` path + `-L` (302-redirects to v3). Public IP: 71.227.227.172 (router forwards 443 → Dankclaw).
 - Porkbun edge throws intermittent 503s; retry later or do it in the UI. LAN path works without this record.
 ## 5. Verify
 ```bash
 # from Dankclaw (host):        getent hosts <name>.franksdank.cloud   → 192.168.0.143
 # workstation w/ stale resolved negative cache: use curl --resolve <name>.franksdank.cloud:443:192.168.0.143
 # workstation's own `sudo resolvectl flush-caches` needs a terminal (no passwordless sudo) — negative cache expires on its own
 curl -sf --resolve <name>.franksdank.cloud:443:192.168.0.143 https://<name>.franksdank.cloud/
 ```
 Publish-style test for ntfy inside container (CLI flags vary by version; raw HTTP is version-proof):
 ```bash
 podman exec <name> wget -qO- --header="Title: smoke" --post-data="up" http://localhost:<port>/<topic>
 ```
@@ -0,0 +1,34 @@
 ---
 name: dankclaw-model-inventory
 description: "Read-only census of downloaded models on Dankclaw: GGUF store, ComfyUI container mount, dead-config trap"
 ---
 Answer "what models are on Dankclaw" without guessing roots. All probes are read-only ssh (`ssh -o BatchMode=yes dankclaw '…'`).
 ## Roots (in order)
 1. **LLM GGUF store:** `/home/dank/models/` — one dir per model, main GGUF + `mmproj-*` (multimodal projector) + `mtp-*` (speculative-decode draft) satellites. `~/.share/models` does NOT exist on Dankclaw (that's the workstations' convention).
 2. **ComfyUI runtime store:** `/home/dank/comfyui-data/models/` — category dirs (`diffusion_models/`, `text_encoders/`, `vae/`, `loras/`, …). This is what the running stack actually uses.
 ## ComfyUI topology (the trap)
 - Runtime = podman container `comfyui` (image `localhost/comfyui-rocm:gfx1151`, user unit `comfyui.service`). Mounts: `~/comfyui-data/{models,custom_nodes,input,output}` → `/opt/ComfyUI/...`.
 - The host checkout `~/ComfyUI/` is NOT the runtime. Its `extra_model_paths.yaml` (base_path `/home/dank/models` + category keys) is dead config from a pre-container setup — never read by the container. Do not report those empty category dirs as "ComfyUI has no models".
 ## Census commands
 ```bash
 # LLM store: sizes + names in one pass
 ssh -o BatchMode=yes dankclaw 'find ~/models -maxdepth 2 -type f \( -iname "*.gguf" -o -iname "*.safetensors" \) -printf "%10s  %p\n" | sort -k2'
 # ComfyUI: container mount truth
 ssh -o BatchMode=yes dankclaw 'find /home/dank/comfyui-data/models -type f -size +1M -printf "%10s  %P\n" | sort -k2; du -sh /home/dank/comfyui-data'
 # confirm runtime + mounts before trusting any path claim
 ssh -o BatchMode=yes dankclaw 'podman ps --format "{{.Names}} {{.Image}} {{.Status}}"; podman inspect comfyui --format "{{range .Mounts}}{{.Source}} -> {{.Destination}}{{\"\n\"}}{{end}}"'
 ```
 ## Anomaly flags
 - A `.gguf` of ~1 KB = git-LFS pointer / failed download, not a model (seen: MiMo-Q8_0 stub). Report as broken, offer refetch or `.AGENTTRASH`.
 - Size sanity vs Strix Halo 32 GiB unified memory: bf16 diffusion+TE pairs near 30 GiB can't co-reside with the serving LLM; int8/w4a8 quants are the working set.
@@ -0,0 +1,62 @@
 ---
 name: dankclaw-pihole-lan-dns-record
 description: "Add/repair a LAN DNS record for a new *.franksdank.cloud service on Dankclaw's Pi-hole v6 (hosts/custom.list + repo addn-hosts, plus the public Porkbun A record side) — and triage \"LAN names stopped resolving\" including the FTL boot-time record-load failure."
 ---
 # Dankclaw Pi-hole LAN DNS record
 ## What this fixes
 A new `*.franksdank.cloud` service resolves publicly (via Porkbun → `franksdank.cloud` A record → Caddy on Dankclaw `192.168.0.143`) but **does not resolve on the LAN**. Pi-hole is the LAN DNS server (`dankclaw_default` bridge, published port 53) and serves local records only from files it imports.
 ## Live truth
 - **The repo owns the records.** `dankclaw/pihole/addn-hosts` (hosts-style lines: `192.168.0.143 <name>`) is copied by `deploy-remote.sh` to `/home/dank/Containers/pihole/addn-hosts` and bind-mounted **read-only** into the container at `/etc/pihole/hosts/addn-hosts` (`Volume=/home/dank/Containers/pihole/addn-hosts:/etc/pihole/hosts/addn-hosts:ro` in `dankclaw/pihole/quadlet/pihole.container`). Add the name there, in the repo, then deploy — that is the durable path. `tests/pihole.bats` validates every line (IPv4, LAN range, name suffix, Caddyfile cross-check).
 - `/home/dank/Containers/pihole/etc-pihole/hosts/custom.list` also exists on the host (older mechanism, mode `640` owned by the container uid, root reads it with `sudo`). It is **not** the repo's owner file — do not hand-edit it as the fix.
 - `pihole.toml` carries a `dns.hosts = [ "192.168.0.143 …", … ]` array too (FTL's own in-config records). Both sources exist; if LAN names fail, neither is being applied.
 - Pi-hole runs as a rootless quadlet named `pihole` — query it with `podman exec pihole …`, never `sudo podman` (per-user storage law).
 - `pihole.franksdank.cloud` resolves through Pi-hole itself (loop/edge), so a vhost record pointing at `192.168.0.143` is correct for every Caddy-fronted service.
 ## Procedure (repo-first)
 1. Append the line to `dankclaw/pihole/addn-hosts`:
   ```
   192.168.0.143 <name>.franksdank.cloud
   ```
   One record per vhost; keep it in sync with the Caddyfile (the bats seam cross-checks the two).
 2. `./tests/run.sh` (the `pihole` seam validates the file), commit, push.
 3. Deploy so the copy step runs: `./scripts/deploy.sh dankclaw --service pihole`.
 4. Verify from the box: `getent hosts <name>.franksdank.cloud` → `192.168.0.143`.
 5. Public edge record (optional; skip when every subscriber is LAN-only): Porkbun `POST /api/v3/json` with `apikey`/`secretapikey`/`command=add`/`type=A`/`hostname=<name>`/`data=76.49.118.136` (see `dankclaw-porkbun-edge`).
 Client-side proof (avoid the resolver trap):
 ```
 sudo resolvectl flush-caches        # systemd-resolved otherwise keeps the negative cache
 curl -sv --max-time 5 https://<name>.franksdank.cloud 2>&1 | grep 'Connected to'
 ```
 Expected: `Connected to <name>.franksdank.cloud (192.168.0.143)` — LAN route, not the public IP.
 ## Triage: every LAN name broke at once (2026-10-19 law)
 Signature: **all** `*.franksdank.cloud` return NXDOMAIN / Playwright `ERR_NAME_NOT_RESOLVED` while **external names still resolve**. The external-OK/local-fail split is the tell: FTL is answering external names from cache and holds **no local records at all** after a container/host restart — the mounts and files are intact and readable inside the container (`ls -l /etc/pihole/hosts/`, `grep -c . …/addn-hosts`), `dns.hosts` in `pihole.toml` is complete. The mechanism is unestablished; do not go hunting for a lost file.
 ```
 ssh dankclaw 'getent hosts grafana.franksdank.cloud'        # empty => FTL, not the client
 ssh dankclaw 'podman exec pihole pihole restartdns reload'   # fixes it in seconds
 ```
 Distinguish before acting: a **single** client failing while others work is FTL rate-limiting that client — `podman exec pihole grep Rate-limiting /var/log/pihole/FTL.log`; a `10.0.2.x` client address is a pasta container's DNS forwarder (SNAT), not a machine. Full causal page: `serverAppConfigs-docs/Infrastructure/Pi-hole.md` (**Records** pitfall + Failure modes table).
 ## Gotchas
 - Do NOT insert local records into SQLite. v6's `gravity.db` `domain` table has NO `type=2` custom-DNS rows in this build.
 - `pihole restartdns reload` re-imports the hosts files **and** `dns.hosts`; that is the remedy for the boot-load failure above. Plain `pihole restartdns` also restarts the resolver — brief LAN-wide DNS blip.
 - `dig @<ip> <name>` from the workstation bypasses systemd-resolved — use it to check FTL's answer directly (`+short @192.168.0.143`).
 ## Cross-reference
 - Fleet DNS flow: `dankclaw/Caddyfile` (Caddy binds `:443` on the host, serves `*.franksdank.cloud` vhosts)
 - Pi-hole service page: `serverAppConfigs-docs/Infrastructure/Pi-hole.md`, flow page `Infrastructure/LAN-DNS.md`
 - Public edge: managed skill `dankclaw-porkbun-edge`
@@ -0,0 +1,44 @@
 ---
 name: dankvoice-bats-serialization
 description: "Run dankvoice bats suites without hangs or false failures: serialize dist rebuilds, never edit src mid-run, and rebuild before committing the tracked bundle."
 ---
 Use when running the dankvoice `bats tests/` suite on the shared box, when a suite run hangs or times out, or when the "committed dist is byte-identical to a fresh build" pin test fails after a commit.
 ## The two serialization hazards
 ### 1. `setup()` rebuilds `dist/` from `src/`
 Every test runs `cd "$REPO" && bun run build` in `setup()`. Consequences:
 - **Never edit `src/` while a suite is running.** The next test's `setup()` compiles whatever is on disk at that instant, so an in-flight edit gets attributed to the run and produces a failure with no owner. Finish the gate, then write.
 - **Two suites on the same checkout race on `dist/`.** Serialize: run one, wait for its report, then start the next. Multiple worktrees of the repo each build their own `dist/` and do not collide.
 - Suite runtime is ~85 s for 55 tests; a backgrounded job with a 600 s deadline is the right shape (`timeout: 600`, `async: true`). Never poll it — `setup()` output lands in the conversation when the job ends.
 ### 2. `dist/` is tracked, and a pin test enforces it
 One test rebuilds and compares against the committed bundle. Therefore the commit order is:
 ```bash
 bun run build          # BEFORE staging
 git add -A && git commit -m '…'
 bats tests/            # gate AFTER the commit
 ```
 Committing `src/` changes without rebuilding first fails the pin test (`not ok … byte-identical to a fresh build`) — the tracked bundle is the *previous* state. If that happens on an unpushed branch, fix it by amend rather than a follow-up commit:
 ```bash
 bun run build && git add dist && git commit --amend --no-edit
 ```
 Verify freshness any time the pin is in doubt:
 ```bash
 bun run build >/dev/null 2>&1 && git status --porcelain dist   # empty = committed == fresh build
 ```
 ## If a backgrounded gate job vanishes
 A crash can kill the job before its report; `read proc://bg_N` returning "not found" means it is gone, not that it failed. Reconstruct what landed before resuming — `git log --oneline -3`, `git status --porcelain`, then the freshness check above — and rerun the suite; the commit may well have succeeded while the gate never ran.
 ## Gotchas
 - `DV_HOLD` is seconds (`sleep "${DV_HOLD:-0.1}"`), so `DV_HOLD=3` really holds the stub for three seconds.
 - Isolation tests must not count shared state: any assertion that sweeps `$TMPDIR` or `~/.omp/cache` observes every other live session on the box (each narrating session creates `dankvoice-*` scratch dirs). Point `TMPDIR` at a private directory instead — see the `cutting off mid-utterance leaves no orphaned audio behind` test.
 - `bun run build` does not typecheck. Run `bunx tsc --noEmit` separately when moving code between modules; the bundler happily emits a bundle that references a deleted identifier.
@@ -0,0 +1,58 @@
 ---
 name: dankvoice-bundle-swap-red-proof
 description: "Prove a dankvoice behavior test is red against the pre-change bundle by pointing DV_EXT at git show HEAD:dist/index.js, with the driver extracted from the bats heredoc into a pinned scratch directory. Use before claiming a new bats assertion is red-capable."
 ---
 Prove a new `tests/behavior.bats` assertion is **red-capable** — that it fails against the *previous* build, not just passes against the new one — without stashing, branching, or editing `src/`.
 ## Why
 `tests/behavior.bats` is a black-box suite: the plugin bundle is loaded through `DV_EXT`, so a *different bundle* is the red side. Stashing the fix would break the `dist` byte-identity pin test and the shared worktree.
 ## Working recipe
 ```bash
 cd ~/Projects/dankvoice                      # or the feature worktree: ~/Projects/wt-dv-*
 bun run build                                 # current src = the green side
 git show HEAD:dist/index.js > /tmp/old-dist.js # the red side (pre-change bundle)
 W=/tmp/dv-redproof                            # PINNED name; see traps below
 rm -rf "$W" && mkdir -p "$W/bin"
 cat > "$W/player.sh" <<'SH'
 #!/usr/bin/env bash
 printf '%s\n' "$*" >> "$DV_STUB_LOG"
 for arg in "$@"; do case "$arg" in *.wav) cp "$arg" "$DV_COPY" ;; esac; done
 sleep "${DV_HOLD:-0.1}"
 SH
 chmod +x "$W/player.sh"
 ln -s "$W/player.sh" "$W/bin/pw-play"
 printf '#!/usr/bin/env bash\nprintf "116\\talsa_output.usb-KT.0\\taudio/sink\\t*\\n"\n' > "$W/bin/wpctl"
 chmod +x "$W/bin/wpctl"
 # The driver lives inside the bats file as a heredoc: extract it verbatim.
 end=$(grep -n '^TS$' tests/behavior.bats | cut -d: -f1)
 sed -n "86,$((end - 1))p" tests/behavior.bats > "$W/driver.ts"
 export DV_EXT="$PWD/dist/index.js" DV_STUB="$W/player.sh" DV_STUB_LOG="$W/player.log" \
       DV_COPY="$W/played.wav" DV_OMPCONFIG=/dev/null DANKVOICE_CONFIG="$W/settings.json" \
       DV_MODELS="$W/models.yml" DV_WPCTL=x DV_SELECT=""
 for ext in /tmp/old-dist.js "$PWD/dist/index.js"; do
  rm -f "$W/player.log" "$DANKVOICE_CONFIG"
  DV_EXT="$ext" bun "$W/driver.ts" <scenario> 2>&1 | grep -E '^PLAYS|^CALLS|^NOTIFY|^SETTINGS'
 done
 ```
 The scenario name is the driver's third argv (`speak`, `auto`, `repeat`, `humanizecycle`, `badurl`, …); the bats `-f` test body's env (`DV_PLAYER_BIN`, `DV_SETTINGS_JSON`, `DANKVOICE_VERBOSITY`, …) is passed the same way. `DV_SELECT` holds the menu answers, `|`-separated, consumed in order.
 ## Traps, each one cost a turn
 - **The scratch directory must be pinned by name.** `ls -dt /tmp/tmp.*` picks up *other sessions'* temp dirs, and then `player.sh` and `driver.ts` live in different directories — the run silently does the wrong thing.
 - **The stub must append to `$DV_STUB_LOG`.** The driver counts player invocations from that file; a stub that only `sleep`s reports `PLAYS 0` for *both* bundles and the whole proof reads as "fix does nothing".
 - **`DV_EXT` is required.** Missing it yields `Cannot find package 'undefined'` from the driver, which looks like a broken driver, not a missing env var.
 - **`DV_SETTINGS_JSON` supports `__PORT__`** (the driver substitutes the fixture port), so a preseed can name a prefixed route — needed whenever the test is about *which* endpoint got resolved.
 - **Never run this while a `bats` run is in flight** in the same repo: `setup()` runs `bun run build`, so two runs clobber `dist/` and the pin test.
 ## Reading the result
 Red side must show the *defect* (`PLAYS 0`, `644`, a chat `CALL` with the wrong prefix, `Invalid URL`), green side the fix — assert on printed markers only (`PLAYS`, `CALLS`, `CALL <url>`, `NOTIFY`, `SETTINGS`). `CALLS` counts `/audio/speech` calls only; the rewrite call appears as its own `CALL /…/chat/completions … sys=<full system prompt>` line, which is how prompt-level knobs (verbosity, heckle) are observed.
 Prefer this over a synthetic leak: if the check already caught a real leftover/failure once, that event *is* the sensitivity proof — say so in the commit message instead of faking one.
@@ -0,0 +1,38 @@
 ---
 name: dankvoice-menu-knob-workflow
 description: "Add a persisted /say knob to dankvoice and test its menu row through the bats driver (DV_SELECT picks, INPUT stub, dist-pin rebuild gate)."
 ---
 Adding a setting to `dankvoice` (`~/Projects/dankvoice`, omp speech extension) means five touchpoints plus one behavioral test. Skip one and TypeScript or a silent drop catches it; skip the test and the row ships dead.
 ## The five touchpoints (order matters)
 1. `src/settings.ts` — field on `Settings` (optional) **and** a type-guarded line in `readSettings`. A field without a guard line is written to disk and never read back; tsc stays clean, so nothing else catches it.
 2. `src/config.ts` — `Config` field (required, defaulted), resolution line, entry in the returned object, and the knob documented in the file header comment (that header is the README's pointer for "full knob list").
   - Convention: explicit env wins over settings (`env.X === "1" ? true : env.X === "0" ? false : (settings.x ?? false)`); booleans use `1`/`0`, enumerations use the literal value.
 3. `src/index.ts` — `persistSettings()` key list (a knob missing there never survives the session) **and** the getter in the `new Speaker({...})` deps object.
 4. `src/utterance.ts` — getter on `SpeakerSettings` if the Speaker reads it at speak time.
 5. `src/menu.ts` — the row. Rows carry their own `run`; never dispatch on `choice === options[N]`.
 Gate at the call site, not the prompt, when a mode must not apply to operator-typed text: `Speaker.speak(ctx, text, thinking, auto)` — `auto=true` only from `message_end`/`agent_end`; `/say <text>` passes nothing. Prompt-only gating leaks.
 ## Test the row behaviorally, never as a config assertion
 `tests/behavior.bats` drives the built `dist/index.js` against a mock harness. Selects and typed text both come from one pipe-separated queue: `DV_SELECT="row label|sub choice|typed text"`, consumed in call order; a consumed-exhausted `select` returns `options[0]`, so always name the row by its **rendered label** (`"Verbosity: normal (change)"`, `"Intro: none (change)"`).
 - `ui.input(title, placeholder)` in the driver mock logs `INPUT <title> <placeholder>` and takes the next queue entry. If the mock lacks `input`, no typed value was ever testable — add the stub before writing the test.
 - Scenario pattern that proves a pick works (`case "knobs"`): `say.handler("menu")` → `say.handler("on")` → two `agentEnd(answer(...))` with `settle()` between. Then assert on observable output, not on the settings file:
  - prompt-shaping knob: `[[ "$output" == *"ONE spoken sentence"* ]]` (directive reached the rewrite request)
  - framing: `[[ "$output" == *"input=Update, chief!"* ]]`
  - throttle/framing counting: `[[ "$output" == *"CALLS 1"* ]]`
 - A guard test whose negative case would pass trivially must also assert its premise, e.g. truncation: assert `CALLS 1` so "no outro" cannot be a green caused by nothing ever being cut.
 Red first, in a batch: write all the new `@test` blocks, run `bats tests/behavior.bats -f "<pattern>"`, confirm the new ones fail, then implement.
 ## Gates and gotchas
 - **Two `bats` runs at once corrupt each other**: `setup()` runs `bun run build`, so a concurrent run rebuilds `dist/` mid-suite and the byte-identical pin test fails spuriously. Serialize.
 - **Edit `src/` → rebuild before commit**: the pin test compares committed `dist/` to a fresh build. Sequence is `bun run build && bunx tsc --noEmit && bats -f <pattern>`, then `git add -A` (dist included). A failure there is normally a stale bundle, not a bad assertion.
 - `VAR=value some_function args` in bats does reach the child process, so knob tests need no `export`.
 - `edit` tool: inserting after a line whose content you know but that the current tag never displayed gets refused — the refusal echoes the real line; if it matches intent, re-issue the identical edit instead of re-reading.
 - Ship: branch `feat/<issue#>-<slug>` off fresh `origin/main`, one commit per knob, PR targets `main`, merge only on Frank's explicit OK (`do=merge`, `merge_style=no-ff`), then `omp plugin upgrade dankvoice` and `cmp` installed `dist/index.js` against the merged one.
@@ -0,0 +1,60 @@
 ---
 name: dankvoice-silence-triage
 description: "Triage silent or late dankvoice auto-speak on the fleet: arming key, /say grammar, endpoint/sink, event granularity, humanizer latency, plus the black-box bats driver."
 ---
 # Triage "dankvoice is silent" on the fleet
 Symptom that recurs: auto-speak only speaks when `/say <text>` is typed
 explicitly. Work the gates in this order; each has an objective check.
 1. **Armed?** `cat ~/.omp/cache/dankvoice.json | jq .auto` — must be `true`
   (or `DANKVOICE_AUTO=1`). Arming is read at **startup only** and `/say on`
   never persists, so a session started before the key was added is silent even
   though fresh sessions work. `/say start` is *not* a subcommand: unknown
   arguments are spoken verbatim (it read out the word "start"). `/say on` is
   the verb; `/say status` must print `auto-speak on`.
 2. **Endpoint + sink?** `/say status` must show a real endpoint (not
   `NO ENDPOINT`) and the saved sink must exist:
   `pw-dump | grep -o 'alsa_output\.[^"]*' | sort -u`.
 3. **Did it synthesize?** `pgrep -a pw-play` during a turn: one process per
   segment, `--target <sink>`, wav under `/tmp/dankvoice-*/say-<epochms>.wav`.
   One temp **directory per utterance chain** — count dirs to count utterances,
   pids to count segments.
 4. **Event granularity (the structural cause).** `agent_end` fires once per
   *prompt* when the loop settles and is skipped when the harness maps a
   non-terminal settle (`willContinue`) — long runs with background jobs or
   subagents therefore narrate nothing. Mid-run narration needs `turn_end`
   (fires per assistant message + tool results). Verify delivery, don't infer
   it: skill `omp-extension-event-probe`.
 5. **Latency is not silence.** Narration passes through the humanizer
   (frank-zealot) before synthesis, so an utterance lands several seconds after
   its turn; under endpoint load that stretches to tens of seconds.
   `/say humanize off` = mechanical voice, near-instant. Judge cadence from
   probe-log timestamps, never from when audio starts.
 ## Design rules the plugin now encodes (dank/dankvoice#2→#3)
 - Narrate `turn_end` per turn **plus** `agent_end` for the settled answer;
  dedupe identical text per run (reset on `agent_start`) so the answer speaks once.
 - A turn landing while the player is alive is **dropped** — no queue, no
  interrupting; a tool loop would cut every sentence off after a word.
  Busy test: `state.child !== undefined && state.child.exitCode === null`.
 - Tool-only turns (no prose, no narration-flagged thinking) stay silent.
 - `print`/`json` modes stay silent, so benches never chatter.
 - Settings writes must **round-trip the file** (`{...onDisk, ...owned keys}`).
  Rebuilding from owned keys deleted `"auto"` on any menu choice and silently
  un-armed every later session — the classic cause of "it worked yesterday".
 ## Black-box test harness (repo `dank/dankvoice`)
 `tests/behavior.bats` drives the built artifact through an in-process driver:
 `const say = DV_EXT(ctx, cfg)[0]`, handlers via `const events = new Map();
 const pi = { on: (n,h)=>events.set(n,h) }`, then `events.get("turn_end")?.({
 turnIndex:0, message:{role:"assistant",content:[{type:"text",text:"…"}]},
 toolResults:[]}, ctx)`. Assert on `CALL`/`PLAYS`/`NOTIFY` lines and
 `SETTINGS <file contents>`; stubs are `DV_PLAYER_CMD` (logs voice+input, honours
 `DV_HOLD`) and `DV_REWRITE_URL` (404 → falls back to mechanical text). `setup()`
 runs `bun run build` per test → serialize suites on the shared `dist/`.
 `tests/packaging.bats` requires `dist/` **committed** (compares to HEAD), so
 build → commit → the drift pin goes green.
@@ -0,0 +1,70 @@
 ---
 name: deployment-checkout-trunk-sync
 description: Use when the live deployment checkout (~/.omp main) must merge a moved origin/main while dirty tracked files block the merge and workspace policy blocks git checkout.
 ---
 ---
 name: deployment-checkout-trunk-sync
 description: Use when the live deployment checkout (~/.omp main) must merge a moved origin/main while dirty tracked files block the merge and workspace policy blocks git checkout.
 ---
 # Sync a dirty live checkout to a deployment (checkout blocked)
 Situation: the checkout IS the deployment; months of machine/hand writes sit
 uncommitted; `origin/main` has moved; `git checkout`/discard is BLOCKED by
 workspace policy ("edit forward"; exemption only during active conflict).
 ## Procedure
 1. `git fetch`; trial `git merge --no-commit --no-ff origin/main` to enumerate
   exact blockers (dirty files the merge would overwrite + untracked collisions).
   Untracked blockers: `cp -a` to `.AGENTTRASH/pre-merge-<date>/`, then `mv` aside.
 2. **Preservation commit:** `git add` ONLY the blocking paths (not the whole
   tree) and commit them as-is: `chore: adopt pre-existing working-tree state
   before trunk merge`. Nothing is discarded; the secret gate still runs.
   Include EVERY dirty deployment-state path (dotfiles/live tiers too) — a
   dirty file that is neither committed nor trashed is unprotected from step 3.
 3. `git merge --no-ff origin/main`. Conflicts are now resolvable — the policy
   exemption is active during a merge.
 4. Resolution law:
   - **live machine config** (`agent/config.yml`, `models.yml`, dotfiles live
     state like noctalia `settings.toml`) → `--ours`: the running box is its
     own authority; the remote copy is a snapshot.
   - **prose/law/docs** (`AGENTS.md`, KB) → `--theirs` (upstream canonical;
     local variants survive in the preservation commit).
   - **append-mostly logs** → union: cut only the three marker lines
     (`<<<<<<<`/`=======` range + `>>>>>>>`), keep both sides' entries.
 5. `git commit --no-edit`, push trunk, verify `main == origin/main`.
 6. Pre-merge byte-compare every dirty file vs `origin/main`
   (`git show origin/main:$f | diff -q - $f`): SUPERSEDED (identical → discardable),
   DIVERGED (resolve), untracked-in-upstream (collision).
 ## Gotchas
 - **NEVER `git stash` to unblock a deployment sync, NEVER `git stash clear`/
  `drop` afterward.** Observed 2026-10-18: a sync stashed the dirty tree, the
  stash entry was later destroyed, and months of GUI-built bar layout
  (noctalia settings.toml, never committed) vanished with it — recovered only
  via dangling-object archaeology (below). Step 2's preservation commit exists
  precisely so stashing is never needed.
 - **Stash-and-retry loops are a red flag**: three `WIP on main` stash commits
  within ~60s of each other means the operator was fighting the dirty tree,
  not resolving it.
 - **Recovery from destroyed stashes** (objects survive entry deletion until gc):
  `git fsck --lost-found` → `git log -1 --format='%ci %s' <dangling>` to date
  them → `git show <c>:<path>` to dump candidates; newest `WIP on` commit is
  usually the last good state. Validate before deploying (e.g.
  `noctalia config validate`), back up the clobbered file to `.AGENTTRASH/`,
  then restore through the symlink target.
 - Never wrap `git checkout` in `2>/dev/null` here: the policy-block error was
  swallowed and the loop silently no-op'd; the merge then failed identically.
 - `git add` a directory pathspec stages its untracked children (fine for
  allowlist dirs; never for prose dirs).
 - The live-sync heartbeat (#11) commits machine tiers hourly, so this sync is
  a rare operation post-deployment — mostly memories/dotfiles stragglers.
  Remember the heartbeat can lag up to an hour behind GUI edits: the tree
  between heartbeats is the ONLY copy of fresh GUI work.
 - **Frank's accepted risk posture (2026-10-18):** hourly sweep + the
  preservation-commit law + fsck recovery is defense-in-depth ENOUGH. Do not
  re-propose faster heartbeats or path/event triggers to shrink the
  GUI-edit-to-commit window; he chose status quo after measuring (heartbeat
  itself is 57 ms CPU — cost was never the objection; un-debounced
  DirectoryNotEmpty triggering was, and path-unit proposals are vetoed).
@@ -1,6 +1,6 @@
 ---
 name: detached-fleet-job-launch
-description: Launch a long-running remote job on Dank fleet hosts so it survives ssh/logind teardown
+description: Launch long-running jobs (fleet hosts or local workstation) so they survive ssh/logind/harness teardown; includes worker takeover law for queue daemons
 ---
 # Detached long-running jobs on Dank fleet hosts
@@ -11,7 +11,7 @@ description: Launch a long-running remote job on Dank fleet hosts so it survives
 no journal entry, no OOM trace, python block-buffers stdout so the log stays
 0 bytes. setsid/nohup do not escape the cgroup.
-## Canonical launch
+## Canonical launch (remote)
 ```
 ssh host 'export XDG_RUNTIME_DIR=/run/user/$(id -u); \
  systemd-run --user --collect --unit=NAME \
@@ -26,6 +26,37 @@ ssh host 'export XDG_RUNTIME_DIR=/run/user/$(id -u); \
 - `-u` / unbuffered output so the log is live
 - verify launch in the same ssh call: `systemctl --user is-active NAME.service`
 ## Local workstation variant (verified 2026-10-10, blankpad)
 Harness background jobs get **tree-killed** at timeout — setsid/nohup children
 die too (survives the process-group kill, not the tree walk). Same cure as
 remote, run locally:
 ```
 loginctl enable-linger $(whoami)   # default Linger=no kills user units at session end
 XDG_RUNTIME_DIR=/run/user/$(id -u) systemd-run --user --collect --unit=NAME \
  -p StandardOutput=append:/abs/path/job.log \
  -p StandardError=append:/abs/path/job.log \
  /full/path/to/binary args...
 systemctl --user is-active NAME.service
 ```
 Gotchas:
 - bash-tool env lacks `XDG_RUNTIME_DIR` → set it inline.
 - `--collect` GCs the unit when it **exits** — after a crash-exit,
  `systemctl --user restart NAME` fails "Unit not found"; relaunch with
  `systemd-run`. Redeploy code = `stop` (not `restart`) + relaunch.
 - point StandardOutput at the job's canonical log file (what the UI/SSE tails),
  not a sidecar — observed drift: worker.log vs per-run log.txt diverged.
 - foreground `(cmd &)` and `(cmd &)` subshells die with the tool call's group.
 ## Worker takeover law (queue daemons)
 A supervisor killed mid-run leaves `queue.json.active` set ⇒ every relaunching
 worker honors "one run at a time" and exits ⇒ silent queue deadlock. Cure:
 - heartbeat: run dir `worker.pid`, rewritten every ~5s while running, removed
  on completion;
 - claim rule: `active` set + pid dead (`process.kill(pid,0)` ESRCH; EPERM =
  alive) ⇒ resume; pid alive ⇒ exit.
 - resume must be append-only + completed-key skip so takeover is cost-free
  (observed: 386 completed samples skipped, zero re-requests).
 ## Watcher (one async job, never poll)
 ```
 ssh host 'while [ ! -f /home/dank/logs/NAME.rc ]; do sleep 60; done; \
@@ -42,5 +73,6 @@ Run it async with timeout 0; the result is injected on completion.
 ## Notes
 - zsh remote shells: `echo ===X===` fails (`=cmd` expansion); quote sentinels.
- The HF upload of 2026-10-08 (113.7 GiB, hf_xet) died this way ~2 min in;
+- The HF upload of 2026-08 (113.7 GiB, hf_xet) died this way ~2 min in;
  relaunch as above succeeded.
 - Frank's machine: `systemctl --user terminate` is not a verb — use `stop`.
@@ -0,0 +1,35 @@
 ---
 name: docs-dedupe-verify-campaign
 description: "Run an exhaustive docs dedupe + fact-verification campaign in dank/command-center: scout cluster ledgers, override scouts with evidence, gate every commit, and sweep scaffolding before PR."
 ---
 # Exhaustive docs dedupe + verification campaign (dank/command-center)
 ## Frame
 - Read `omp-docs/references/okf-spec.md` + root `omp-docs/index.md` first; inventory with `find omp-docs -name '*.md' | wc -l`.
 - Run `scripts/kb-lint.sh omp-docs` baseline; index-coverage gate is `scripts/kb-coverage.py omp-docs` (each dir's `index.md` must link every sibling file/subdir).
 - Branch off fresh `origin/main` in a NEW worktree (`git -C ~/.omp worktree add ~/.omp/wt/<name> -b docs/<issue>-slug origin/main`) — workspace policy blocks `git checkout -b` in session worktrees.
 - Open the Gitea issue first (multi-moving-parts law); branch name `docs/<issue#>-<slug>`.
 ## Scout fleet (overlap detection)
 - One `task` call, `tasks[]` batch, agent `scout`, read-only; one cluster per task (skills trees, llama trees, pi vs packages, niri, sleep/power, core, gitea, gitea+cross-cutting sweep). Cap 2 concurrent; queue rest.
 - Ledger format per cluster → `local://dedupe/<cluster>.md`: inventory table (file | lines | verdict KEEP|MERGE|DELETE|VENDOR|UPDATE), overlaps, facts-to-keep, inbound links, staleness.
 - **Scouts lie.** Verified misses in the 2026-10-19 campaign: fabricated ledger entries ("peer-reviewed BrowseComp" claim that exists in no file), a DELETE verdict for a generated artifact that is checked in by design AND under test (`tools/niri/keybindings.md`, see `scripts/gen-keybinds.sh` + `tests/gen-keybinds.bats`), and a KEEP for a leftover the scout misread its own changelog about. NEVER apply a scout verdict without re-checking the file, the tests, and the changelog yourself.
 ## Fact verification
 - Fleet facts: read-only probes over `ssh -o BatchMode=yes dankclaw|dankserver` (podman ps/inspect/top, stat, /etc/os-release, curl localhost APIs, `podman exec <c> <tool> --version`). Live state beats docs even when docs claim recent verification — the 2026-10-18 "audit" still drifted (zealot 27B→9B, build 10754→10777, container census 14→32).
 - External claims: web_search/web read yourself (no subagents per Frank's rule). Kill fabrications outright (invented distro `FreeToken`, nonexistent `ornith-llama-cpp-setup` tree, unattributable "44.5% peer-reviewed CUA") — delete/drop with an explicit note, never keep "plausible" numbers.
 - Policy drift (live ≠ tuned docs): flag in the doc + PR body as an operator decision; NEVER silently re-apply policy.
 ## Log compaction (log.md)
 - Entry law: dated entry = what changed + durable lesson + concept-page pointer; narratives recoverable via `git log --follow`. Record the law at the top of the log. Tag historical-era entries.
 ## Gates + landing
 - Gate every commit: `bash scripts/kb-lint.sh omp-docs && python3 scripts/kb-coverage.py omp-docs && bats tests/`. Pre-commit hook prints `error: command not found: caddy` on Caddyfile-touching commits — warning only, commit still lands.
 - Before opening the PR: `git diff --stat origin/main..HEAD | grep -i 'tmp\|scratch\|\.bak'` — scaffolding merged under a `.tmp-` name in the 2026-10-19 campaign and needed a follow-up PR to promote.
 - PR via API (skill `gitea-api-pr-operations` for token-extraction + merge payload); `xdg-open` the PR the moment it opens; comment the campaign ledger on the issue.
 - After Frank's merge OK: propagate deployment `git -C ~/.omp fetch && git merge --ff-only origin/main`; reap campaign worktree (`git worktree remove --force`) + delete branch local/remote; close issue with landing comment.
 ## Line-edit op syntax trap (bit three times)
 - Valid ops: `PUT N.=M:` (body `+text` lines), `CUT N.=M` / `CUT N.=M @reg`, `PUT <N @reg`, `PUT >N:` / `PUT <N:`. There is NO `PUT N+=:` form — it lands in the file as a literal garbage line and shifts the insert to the wrong position. For gap-insert use a lone `PUT >N:` or `PUT <N:` per call; pre-compute line numbers against the file map (ops reference original lines within one call, but a failed op poisons positions).
 - Recovery recipe when a literal op line lands: read exact bounds, `CUT N.=N` (junk), `CUT A.=B @block` (misplaced section), then `PUT <M @block` at the true anchor, re-read tail, add spacing blank if a `---` now abuts a list line.
@@ -0,0 +1,70 @@
 ---
 name: docs-point-of-use-destruction
 description: "Documentation exists for point of use, not archival. Use before any dedupe/compact/verify-docs job, and whenever a census or \"only copy\" argument is being used to KEEP documentation: apply the purpose test and destroy obsolete measurements. Supersedes the preservation conclusions of vault-one-fact-one-owner-dedupe §3/§12."
 ---
 # Documentation exists for point of use
 **Supersedes** `vault-one-fact-one-owner-dedupe` §3 ("port before cut") and §12
 ("expect docs flat") wherever those conclude a page must be *kept*. Sole custody of a
 useless fact is still useless.
 ## The test, before you write and again before you keep
 - Would the reader, doing a real task tomorrow, **act differently** because of this
  line? No → delete it.
 - Is it a measured rate (t/s, tok/s, ms, MiB-of-pool, acceptance %, a bench ladder) for
  a model / runtime / layout that is **not running now and not being compared now**?
  Destroy it. Not "file it in an Eras row", not "preserve it for history". AI moves
  faster than the vault: the number is wrong before anyone reads it, and a wrong number
  in a runbook gets believed.
 - Keep the **law** the measurement taught; drop the measurement. Qualitative causal
  stories survive; numbers do not.
 - What survives: live config and its exact numbers, procedures, failure signatures,
  security posture, interface contracts, rollback pointers.
 - **Losing information is an acceptable, usually correct outcome.** Frank said so
  explicitly on 2026-10-19 after rejecting a PR that had preserved 53 ledgers.
 ## Traps that lead agents to preserve junk
 - **A census cannot decide what to keep.** `port-census.py`-style tools answer "where
  does this fact live", never "does anyone need it". "14–63 sole-record lines per page"
  was read as *irreplaceable* when the fact was *obsolete*. Ask usefulness, not custody.
 - **A census that includes the file under test proves the page is held by itself.**
  Exclude it, print the corpus size, assert absence; treat `0 unheld` on a long page as
  a tool bug until proven otherwise.
 - **"One fact, one owner" is a placement rule, not a preservation rule.** It says where
  a surviving fact lives; it never says the fact must survive.
 - **A change diary (`log.md`) is the largest archive in most vaults** (this one: 2,380
  lines, ~8 % of the vault). Git holds the chronology; a causal law belongs on the page
  that owns the thing it governs. Retire the diary.
 ## Execution that worked (2026-10-19, −13.7k lines)
 1. Write the kill list as a reviewed artifact, one path per line, grouped by *why it is
   dead* — that list becomes the PR's argument and the trash manifest.
 2. Destroy whole pages first (`scripts/destroy-vault.py <list>`): move to
   `.AGENTTRASH/<date>-destruction/`, then delete every reference from survivors, whole
   line included when the dead link was its only content. Do not compare link targets
   with `pathlib.Path.stem` — it strips real suffixes (`sd.cpp`).
 3. Then strip numbers from what remains (`scripts/axe-measurements.py`): delete ledger
   sections (noun-LEDS the heading, nothing instructional after it), blank any table cell
   reporting a rate, fold Eras older than the current one into a single row pointing at
   git. Never touch a shape number or a Laws/Wire/Rollback section.
 4. Sweep indices (generator must exclude the trash dir, drop rows whose page cell became
   empty), re-lint, re-check links.
 5. Rewrite the governing policy in the same PR, or the next agent re-grows the vault:
   project `AGENTS.md` *Documentation Policy* + the global agent settings.
 ## Report honestly, per area
 docs / scripts / operator-doc separately, measured against the merge-base. The tools are
 a cost that must be named, not hidden inside a headline "net" number — that is what got
 the previous pass rejected.
 ## Verify the repair tools themselves
 One repair pass matched "line ends with a comma" and deleted the trailing comma from 660
 wrapped prose lines. Restore by matching lines that are byte-identical to `HEAD` except
 for trailing punctuation (`restore-punctuation.py`), keep the destructive rule out of the
 tool, and record the incident in its docstring.
@@ -0,0 +1,85 @@
 ---
 name: docs-refresh-scout-summaries
 description: "Refresh a stale documentation cluster without delegating the writing: scout subagents produce per-line verdict tables (holder verified by comma-insensitive grep), the parent makes every edit, and a port-before-cut census proves nothing was lost. Use for dedupe-our-docs, fix-the-stale-runbooks, pointers-instead-of-copied-numbers jobs."
 ---
 # Refresh stale docs with scout summaries, parent-side writes
 Use when a cluster of documentation pages is stale and/or restates facts another page owns, and
 the fix touches many files. **Scouts read and classify; the parent writes.** Sibling skill
 `vault-one-fact-one-owner-dedupe` covers collapsing era pages into owner pages - its section 3
 (orphan census), section 7 (edit-tool hazard) and section 9 (verify/PR) apply unchanged.
 ## Why not writer subagents (measured cost)
 Writer agents produce plausible output and cannot be trusted on the one claim that matters - the
 owner page already holds this fact. In one run they asserted every cut was grep-confirmed while
 FOUR cuts left pointers to pages that did not contain the fact (118->238 GiB, 16,095 tokens,
 0.739/0.554/0.427/0.340, PR #23897). Each became a broken promise the next reader trusts.
 Classification is the only part that parallelizes; writing is where taste (ownership, era
 naming, what counts as a law) lives. So fan out read-only scouts and keep the pen.
 If writer agents were already spawned and are no longer wanted: `write agent://all` to stop
 them, then `git status` the target tree - `proc://` does not list agent jobs, and a finished
 worker may already have edited files.
 ## Pipeline
 1. **Cluster** targets into groups of 3-4 pages sharing subject matter (one cluster per scout).
   Know the owner map first (endpoint/service/host pages, plus the repo documentation law).
 2. **Wave of 2 scouts** (harness cap is `task.maxConcurrency`, usually 2). Scout contract:
   > READ-ONLY, no writes of any kind. Per file, one table row per candidate fact:
   > `| lines | verbatim figure + 6 words | holder elsewhere (file:line) or none | VERDICT |`
   > Verdicts: `CUT -> [[Owner]]` (holder verified), `KEEP(owned here)` (no holder, this page is
   > the record), `PORT(parent)` (rightful owner lacks it - name page and section), `STALE`
   > (contradicted by current state; quote the contradicting line), `INDEX` (locator page).
   > Verify every holder claim with a COMMA-INSENSITIVE grep: a holder writing 1,350,182
   > satisfies a page writing 1350182 and vice versa; 16,095 does NOT satisfy a check for 16095
   > unless commas are stripped. Never name a holder line you have not read.
   > End with a per-file tally: kept / cut / port / stale.
   Put the law, the owner map and the verification rule in the batch-level `context`, never per
   task.
 3. **Write while the next wave runs**: edit cluster N from wave N, launch wave N+1 in the same
   turn. Never launch a wave you have nothing to write.
 4. **Verify each CUT yourself** before cutting - read the holder line. A scout row is a
   hypothesis, not evidence.
 5. **PORT items are your edits**: add the fact to the owner page section (Eras row / Laws / spec
   table), then cut it from the technique page in the same commit.
 6. **STALE items: check live state**, not another document - `ssh <host> systemctl is-active
   <svc>`, the endpoint `/health`, the env file. Then rewrite with a date, or drop transient
   live state an owner page already records.
 ## The ownership test that stops wasted ports
 Two pages carrying one figure is the defect - a figure with exactly one holder is fine wherever
 it lives. A technique page that is the sole record of a campaign owns that campaign's arm
 tables; do not port such ledgers into an endpoint Eras table. Write the clause into the repo
 documentation law so the next pass stops porting single-owner facts. Corollary: a worked example
 may repeat a live number if it declares itself dated and names the owner (a snapshot, not fleet
 state - recompute from the live files).
 ## Census after each cluster (catches your own slips too)
 Run the sibling skill's section 3 census over `git diff -U0` for the cluster (deleted lines x
 distinctive numeric keys vs the whole vault **plus AGENTS.md**), comma-insensitively; drive the
 count to zero or list each accepted loss in the commit message.
 ```python
 flat = corpus.replace(',', '')
 pres = lambda n: n in corpus or n.replace(',', '') in flat
 toks = lambda l: [n for n in re.findall(r'\d[\d,]*(?:\.\d+)?', l)
                  if len(n.replace(',', '').split('.')[0]) >= 4
                  or (len(n.split('.')[-1]) >= 2 and len(n.replace(',', '')) >= 5)]
 orphan = [l for l in deleted if toks(l) and not any(pres(n) for n in toks(l))]
 ```
 ## Verify and land
 - Vault link seam must print `0 unresolved links`; hard-wrapped `[[Two Word Page]]` links split
  across lines are the usual cause - unwrap them.
 - Full suite once at the end, not per cluster; a docs seam running while scouts are live may
  read half-written files, so re-run after the last edit.
 - Commit per cluster (docs-only means **no deploy**); push, open the PR through the API with a
  600-perm curl config, `xdg-open` the PR URL immediately.
@@ -0,0 +1,35 @@
 ---
 name: fixture-delay-window-race-test
 description: Pin a race/abort bug in a fixture-server test by delaying only the Nth request so the interruption lands inside the in-flight window; assert via a driver-installed unhandledRejection reporter.
 ---
 # Reproducing a timing-window bug against a fixture server
 Use when a defect only appears in a window — a promise created before it is awaited, a kill/abort landing mid-flight, a prefetch interrupted — and a fixture HTTP server answers instantly, so the window never opens. Earned in `dankvoice` issue #7 (`[Unhandled Rejection] AbortError` from `/say stop` during a pipelined synthesis).
 ## Why naive attempts pass vacuously
 1. **Uniform delay on the fixture route** (`DV_LATENCY_MS` for every request) makes *all* requests resolve at the same time, so by the time the interruption fires nothing is in flight. The test goes green against the broken code — worse than no test.
 2. Asserting on a log line count that also counts interruption noise: `dankvoice`'s driver prints `PLAYS <n>` as the number of **player log lines**, and the stub appends `KILLED` on SIGTERM — so a single playback with one interrupt reports `PLAYS 2`. Count the payload lines instead (`grep -c 'PLAYER .*\.wav$'`).
 ## The shape that works
 - **Delay only requests after the first.** The first response gets the pipeline into playback; the second stays in flight, which is the window:
  ```ts
  const spoken = received.filter((c) => c.url?.endsWith("/audio/speech")).length; // already pushed
  const delay = spoken > 1 ? Number(process.env.DV_SYNTH_MS ?? 0) : 0;
  if (delay > 0) setTimeout(answer, delay); else answer();
  ```
 - **Make the interruption land inside it.** Player holds long (`DV_HOLD=2`), interruption at a fixed offset (`DV_STOP_AT=400`) with the delayed response far later (`DV_SYNTH_MS=1200`): margins wide enough that the abort is neither before the request nor after the response.
 - **Turn unhandled rejections into observable output** in the test driver instead of letting the runtime crash on them — that is also exactly what the real harness does to the user:
  ```ts
  process.on("unhandledRejection", (reason) => {
    console.log(`UNHANDLED ${reason instanceof Error ? `${reason.name}: ${reason.message}` : String(reason)}`);
  });
  ```
  Then assert `[[ "$output" != *"UNHANDLED"* ]]` plus the concrete behavior (segments actually played, player killed).
 - **Leak checks measure a delta, not an absolute:** count `dankvoice-*` temp dirs before and after the run and compare; an absolute `== 0` fails on another test's leftovers.
 ## Order
 Write the scenario first and watch it fail **on the rejection assertion specifically** — if it fails on some other assertion (a count, a kill line), the window is wrong, not the bug. Then fix, then confirm red→green on that one assertion before running the full suite.
@@ -0,0 +1,26 @@
 ---
 name: fleet-image-pull-freshness-audit
 description: "Answer \"when was the last time we pulled/updated engine?\" for digest-pinned dank-fleet images: git-history pin dating vs host podman state, pull-vs-restart distinction."
 ---
 Answer "when was the last time we pulled/updated <engine image>?" for a digest-pinned fleet endpoint (radiance/halogen/llama.cpp images on dankserver/dankclaw).
 ## Procedure
 1. **Locate the pin.** `grep` the repo for the image digest prefix (e.g. `4c3f484564`) — pins live in `scripts/<svc>.env` (`FRANK_ARCHON_IMAGE` etc.) and are restated in `AGENTS.md` / runbooks.
 2. **Date the pin in git.** `git log --all --format='%h %ad %s' --date=short -S '<digest-full-prefix>'` — the OLDEST hit is the cutover that pulled it (renames and service-name sweeps produce later hits; ignore them).
 3. **Check the host state.**
   `ssh <host> 'sudo podman images --format "{{.Repository}}:{{.Tag}} {{.ID}} {{.Digest}} {{.CreatedTime}}"'`
   Compare the on-disk digest to the pin. `CreatedTime` is the VENDOR build stamp, not the pull time — it proves which build is on disk; the git commit dates the pull.
 4. **Distinguish pull from restart.** Digest pinning means the serve script NEVER auto-pulls; a fresh `ActiveEnterTimestamp` (`systemctl show <svc> -p ActiveEnterTimestamp`) is a restart, not an update.
 5. **Sweep side pulls.** A newer engine version may have been pulled for a one-off (calibration, KLD, bench) and removed after. `podman images` census + `git log -S` for the second digest; note when the side image is gone from disk (answer: "pulled <date>, no longer on disk").
 ## Facts to carry (radiance example)
 - frank-archon pin `stilldeadcode/radiance@sha256:4c3f484564…` (1.0.13) pulled 2026-10-05 (cutover commit); reused unchanged at the 2026-10-08 w4dn8 cutover.
 - Engine 1.2.0 was pulled 2026-10-08 for calibration only; image absent from disk afterwards.
 - Cross-pin compatibility (e.g. RADGRAM2 grams byte-identical across pins) is documented in the runbook — cite it when explaining a calibration/serving pin split.
 ## Answer format
 Table: pin-first-introduced commit+date (the pull), later cutovers reusing the same digest (no pull), side-image pulls, last container start (restart, explicitly labeled not-a-pull). Offer upstream freshness scout as next step; a digest change for an LLM endpoint requires the stop-and-mask bench-window law.
@@ -0,0 +1,30 @@
 ---
 name: fleet-judge-swap-calibrate
 description: "Swap the frank-intelligence-bench judge default and prove judge quality: fleet alias→weights map, known-truth calibration via scripts/judge-calibration.ts, per-backend reasoning-off dialect traps."
 ---
 # Fleet judge swap + calibration (frank-intelligence-bench)
 ## Fleet alias → weights (verified 2026-10-10 via ps on dankclaw; endpoints only serve aliases)
 - frank-archon = Qwen3.8-Flash-Next quant (radiance TP=2, dankserver:7770)
 - frank-dragoon = qwen38-flash-next-v2-swift15-abliterated.hgn, 180B MoE (halogen container `frank-large-halogen`, dankclaw:7770) — check `podman inspect frank-large-halogen --format {{json .Config.Env}} | grep HALOGEN_CHECKPOINT`
 - frank-zealot = Qwen3.5-9B-Uncensored-HauhauCS-Aggressive Q6_K (llama.cpp, 3090, dankclaw:7771) — check `ps aux | grep <port>`
 ## Swap procedure
 1. `config/hosts.yml`: target host gains `roles: [target, judge]`; set `judge_default`. No-self-judge law: `judge == target` throws at enqueue; rotation = next fleet model.
 2. Judge load = AA-LCR + HLE only (SciCode/Terminal-Bench are unit-tested, judge-free).
 3. Mid-run: `run.json` pins its judge (provenance); default swap affects future runs only.
 4. Docs: `docs/endpoints.md` judge law section; commit with gates.
 ## Calibration — the ONLY accepted proof
 `bun scripts/judge-calibration.ts [n] [judges...]` — known-truth floor test: gold answers must be judged CORRECT, deterministically mutated (first number +7) must be INCORRECT. Reports accuracy, mean s/verdict, projected AA-LCR/HLE judge hours. Safe beside a live run (judge-only traffic).
 - Known-truth is a FLOOR test: catches broken judges, not lenient ones. Gold-vs-mutation is easy mode; small-model leniency on model-vs-gold edges needs real-verdict spot audits.
 ## Traps (all fired at least once)
 - **False-accuracy via transport death:** a 400-dying judge scores ~50% on this test (all verdicts collapse to INCORRECT, matching the mutation half by luck). ALWAYS inspect `err` on misses before trusting any agreement/accuracy number. Fix: if all misses share one `err=HTTP 4xx`, it is the harness, not the judge.
 - **Reasoning-off dialect split:** llama.cpp/radiance want `chat_template_kwargs:{thinking:false}`; halogen/vLLM-style servers 400 on `thinking` and honour `enable_thinking`. HostSpec field `reasoning_off: thinking|enable_thinking` (default `thinking`; dragoon needs `enable_thinking`). Wire-test via mock `bodies` capture.
 - **No historical judged rows?** Quarantined ledgers may pre-date judge usage (census first: `failureCensus` rows/phase), then use known-truth synthesis instead of re-judging.
 ## Baselines measured (for future swaps)
 - zealot (9B): 25/25 known-truth, 13 s/verdict → AA-LCR 1.1h, HLE 9.3h; leniency risk on hard edges (small judge + compliance tune).
 - dragoon (180B): 2 s/verdict → AA-LCR 0.2h, HLE 1.4h; family-bias caveat when target shares its base family.
@@ -0,0 +1,83 @@
 ---
 name: fleet-served-model-id-rename
 description: "Rename the served model id (alias) on a dank-fleet LLM endpoint and re-key every consumer that keys on it, with live verification."
 ---
 # Fleet served-model-id rename (wire rename)
 Renames the id an endpoint announces on the wire. The service, unit, script and env
 FILE names keep the old name (container/unit identity is stable) — only the served
 alias moves. Done this way on 2026-10-09: frank-primary→frank-archon,
 frank-large→frank-dragoon, frank-secondary→frank-zealot.
 ## 1. The knob, per engine
 | Endpoint | Knob |
 |---|---|
 | frank-primary (radiance, dankserver :7770) | `FRANK_PRIMARY_SERVED_NAME` in `scripts/frank-primary.env` → `--served-model-name` |
 | frank-large (halogen flash-server, dankclaw :7770) | `HALOGEN_MODEL_ID` in `scripts/frank-large.env` |
 | frank-secondary (llama.cpp, dankclaw :7771) | `ALIAS` in `scripts/frank-secondary.env` → `--alias` |
 Also flip the serve-script defaults (`: "${ALIAS:=…}"`, the `:?` gate messages).
 `scripts/deploy-remote.sh` has no alias references — the deployer needs no edit.
 ## 2. Consumers that key on the id (all in ONE change)
 - Seams: `tests/frank_{secondary,large,primary}_unit.bats` — fixture env value,
  the argv assertion (`--alias`), the env grep pin, the `-e HALOGEN_MODEL_ID=` render
  assertion.
 - OpenWebUI (Dankclaw, rootless quadlet, `webui.db`): `model.id`+`name`,
  `access_grant.resource_id` (`resource_type='model'`), `openai.api_configs`
  per-backend `model_ids`. Backup first (`webui.db.bak-YYYYMMDD`; the DB is WAL-mode).
  No sqlite3 binary in the image → `podman exec -i open-webui python3 -` with a
  script on stdin. Then `systemctl --user restart open-webui.service`. A stale id
  fails SILENTLY: OpenWebUI intersects the backend `/v1/models` with `model_ids`, so
  the picker just goes empty.
 - Hermes (`/home/dank/Containers/hermes/data/config.yaml`, root-owned → sudo):
  `model.default`, the provider `models:` key, every `auxiliary:` route naming the
  endpoint. Backup, surgical `sudo sed -i`, sweep `grep -rln <old-id>` over the data
  dir (session JSONs are historical — leave), restart `hermes.service
  hermes-webui.service` (user units).
 - Dev harnesses: `"model": "frank-…"` literals in `scripts/bench-*.py`,
  `deep-probe.py`, `calib-push.py`, `fleet-probes-swift15.sh`, `autoresearch*`.
 - Docs: `shared/homepage/docs.html` (headings, api-id annotations, the
  curl/opencode/Pi examples), endpoint runbooks, `AGENTS.md` Model Config,
  `serverAppConfigs-docs/Agent/OMP Harness.md`, `Dankclaw/OpenWebUI.md`.
 - Harness side (`~/.omp/agent/models.yml` on the dev box) — ids and `modelRoles`
  must name the same string; two ports on one host = two providers.
 ## 3. Deploy + verify
 `./scripts/deploy.sh <host> --service <name>` per endpoint; keep the tree clean
 (untracked scratch files inside the repo fail the whole-tree gate — put probes in
 /tmp with a `node_modules` symlink to `tests/e2e/node_modules`).
 Verify on `/v1/models`, NEVER on a chat echo: radiance echoes the REQUESTED model
 name (a 200 proves nothing), llama.cpp and halogen ignore the requested id.
 ```bash
 for u in 192.168.0.235:7770 192.168.0.143:7770 192.168.0.143:7771; do
  curl -fsS "http://$u/v1/models"; done
 ```
 OpenWebUI acceptance = a real browser as a family account: the welcome screen names
 the model and `POST /api/v1/chat/completions {"model":"<new-id>"}` answers.
 `GET /api/v1/models/list` returning `{"items":[],"total":0}` for that same account
 is a probe artifact, not a failure. Playwright notes: `locator.isVisible({timeout})`
 does NOT wait (returns immediately) — use `waitFor({state:'visible'})`; the composer
 is a contenteditable div, not a textarea; stable anchors are
 `getByRole('button', {name: /selected model/i})` and "How can I help you today?".
 ## 4. Trap: green deploy, old config
 `deploy.sh` plans from repo paths and gates on the port. A systemd drop-in under
 `/etc/systemd/system/<unit>.service.d/` can override `Environment=FRANK_*_ENV_FILE`
 and `ExecStart` to a staging worktree, so the deploy restarts a DIFFERENT tree and
 reports healthy (this bit frank-primary for a day after a quantization campaign).
 After an LLM deploy, prove the running shape:
 ```bash
 systemctl cat <unit>                       # drop-ins print at the bottom
 podman inspect <container> --format '{{json .Config.Cmd}}' | tr , '\n'
 ```
 Before retiring such a drop-in: diff staging vs checkout for serve script/unit/env,
 and `git merge-base --is-ancestor <staging-HEAD> HEAD` so no campaign tuning is
 lost. Move it to `~/.AGENTTRASH/YYYYMMDD-topic/` (never `rm`), `daemon-reload`,
 restart, re-read `/v1/models`.
@@ -0,0 +1,58 @@
 ---
 name: fleet-service-rename-cutover
 description: "Rename a Dank-fleet LLM service end-to-end (repo trio, deployer keys, tags, hosts): the 2026-10-10 frank-archon/dragoon/zealot cutover procedure."
 ---
 # Fleet service rename cutover (serverAppConfigs)
 Procedure proven 2026-10-10 renaming the three LLM services to their wire
 aliases (repo `55f87fc`). For any future full service rename.
 ## Repo codemod
 1. `git mv` every tracked file whose path carries the old token
   (`frank-<old>` → `frank-<new>`, plus `frank_<old>` bats seams).
 2. Content sweep over all tracked text files:
   `git grep -Ilz '' | xargs -0 sed -i` with expressions for
   `frank-<old>`, `FRANK_<OLD>`, `frank_<old>` → new forms; add the
   `LLM_<OLD>` / `llm_<old>` / handler-name forms in the same pass.
 3. Known casualties to record: `scripts/patches/*.patch` context lines get
   rewritten (patches stop applying byte-exact); historical prose adopts
   the new name (one service, one name — Frank's rule).
 4. Fix sed-made-contradictory lore by hand: AGENTS.md Model Config
   paragraph, any "keeps the old names" sentences. Do NOT enumerate the
   retired names anywhere — the acceptance test is
   `git grep -cE '<old forms>'` == 0 (case-insensitive too).
 5. Rename rollback tags in lockstep (docs quote tag names):
   `git tag NEW OLD; git tag -d OLD`, push new, delete old refs on origin.
 6. Sweep the harness config comments too: `~/.omp/agent/models.yml`.
 ## Deployer keying (why the sweep is safe)
 `scripts/deploy-plan.py` SERVICE_ORDER/host sets + `services_for_path`
 trio mapping; `scripts/deploy-remote.sh` `service_is_allowed` case,
 `deploy_service` dispatch, `relink_unit <service>` (symlink
 `/etc/systemd/system/<name>.service` → `scripts/<name>.service`),
 markers keyed by service name under `~/.local/state/serverAppConfigs/
 deploy-state/`. `add_pending_services` AUTO-TRASHES markers whose service
 is retired — no marker surgery needed if you skip a full drain.
 ## Host cutover per endpoint (order matters)
 1. `sudo systemctl stop <old>`; rename `~/logs/frank_<old>.log` → new;
   `podman rm -f` the old container name(s);
   `sudo rm` the unit symlink + `multi-user.target.wants/<old>.service`;
   `sudo systemctl daemon-reload`; trash the marker to
   `~/.AGENTTRASH/<date>-fleet-rename/` with a NEUTRAL filename.
 2. `deploy.sh <host> --service <new-name>` (run from the main checkout;
   refuses on a worktree branch). The handler relinks under the new name,
   enables, restarts, health-gates.
 3. Do the harness-default-model endpoint LAST on its host, and never stop
   an endpoint while a deploy on the other host is approaching its e2e
   gate (the gate probes the live fleet).
 ## Acceptance
 `/health` 200 + `/v1/models` shows the new id (radiance echoes requested
 names — verify on `/v1/models` only); unit active+enabled; new container
 name running; `git grep` zero on every checkout; e2e gate green;
 Prometheus job up (note: llama.cpp needs `--metrics` in the serve script
 for the scrape — absence is a pre-existing gap, not a rename regression).
 Out of scope: retired endpoint names (`frank-medium/small/npu`) and git
 history — old strings there are expected.
@@ -0,0 +1,62 @@
 ---
 name: fleet-service-runtime-census
 description: "Answer \"what is service running right now?\" for a dank-fleet service: live endpoint probe plus host units, image ids, live-vs-repo env, and drop-ins."
 ---
 # Fleet service runtime census
 Answer the question "what is `<service>` running currently?" with evidence, not from docs. Docs say what *should* run; the host says what *does*. Run all five probes, then report one table.
 ## 1. Probe the published port (works from any LAN box, no ssh)
 ```bash
 curl -s -m 10 http://<host-ip>:<port>/health; echo
 curl -s -m 10 http://<host-ip>:<port>/v1/audio/voices   # per-endpoint extras: /v1/models, /metrics
 ```
 The extra route matters more than `/health` for identity claims:
 - llama.cpp and radiance **echo the requested model name** — a 200 proves nothing; read `/v1/models`.
 - halogen 404s `/completion`, `/ping`, `/props`, `/tokenize`.
 - The frank-tts façade answers `/health` **without dialing the engine**, so "façade healthy, engine down" is a real state; the voice list in that same response is the honest census.
 ## 2. Units + containers on the host (ssh as the deploy user, no sudo)
 ```bash
 ssh <host> 'systemctl --user status <svc>.service <engine>.service --no-pager \
  | grep -E "^(●|  Active|  Loaded)"; \
  podman images --format "{{.Repository}}:{{.Tag}} {{.ID}} {{.Created}}"; \
  podman ps -a --format "{{.Names}}\t{{.Status}}\t{{.Image}}"'
 ```
 - `active (running) since …` + `Up N hours (healthy)` is the answer; `activating (auto-restart)` with a ~50 ms exit is a **preflight refusal**, not an engine fault.
 - **NEVER prefix these podman calls with `sudo`.** Containers live in the deploy user's rootless storage; `sudo podman inspect frank-tts-engine` returns `no such object` while the plain form succeeds. Treating that as "container missing" is a false finding.
 ## 3. Drop-ins — the override that no health gate sees
 ```bash
 ssh <host> 'systemctl --user show <svc>.service -p DropInPaths; \
            systemctl --user show <engine>.service -p DropInPaths'
 ```
 `DropInPaths=` must be empty. A leftover bench drop-in (`Environment=FRANK_<SVC>_ENV_FILE=/tmp/<arm>.env`) makes the next deploy boot a different model at a different shape while `/health` still answers 200 and the e2e gate passes.
 ## 4. Live env vs repo env — the only truth test
 ```bash
 # repo side (local checkout)
 grep -vE '^\s*#|^\s*$' scripts/<svc>.env
 # host side
 ssh <host> 'sudo cat /home/dank/serverAppConfigs/scripts/<svc>.env' | grep -vE '^\s*#|^\s*$'
 ```
 Diff them. Per repo law the env file beside the serve script **is** the authority; a doc page that disagrees with it is the bug, and host-side drift means an uncommitted edit. Also check `git log --oneline -3 -- scripts/<svc>.env` to confirm the host isn't ahead of git.
 ## 5. Report
 Table of: unit state + since, image repo:tag@short-ID + age, backend/alias actually served (from step 1, not from the name), drop-ins, and whether live env == repo env. State explicitly when a fact came from docs rather than from a probe.
 ## Traps that produce false findings
 - Digest-pinned images: the local image ID's *creation date* answers "is this stale" better than the tag; `latest` + `Pull=never` is a locally built image, not a registry pull.
 - `ssh` user context changes what podman sees (root vs rootless) — see step 2.
 - Two ports on one host are two providers in `models.yml`; a port mismatch is a rename or drift, not a config typo.
@@ -0,0 +1,56 @@
 ---
 name: fleet-status-daily-report
 description: "Answer \"status update / what happened yesterday\" for the dank fleet: git-window record on origin/main plus a live per-host census (endpoints, units, RAM, DNS), with the reboot-attribution check that stops false incident causes."
 ---
 # Fleet status report (Dankclaw + Dankserver)
 Use for "what's the state of the fleet", "what happened yesterday", or a post-incident sweep. Read-only.
 For one service's live state, prefer `fleet-service-runtime-census`; this is the fleet-wide sweep.
 ## 1. The day's record (repo is the ledger)
 ```bash
 git fetch origin --quiet
 git log --no-merges --since="YYYY-MM-DD 00:00" --until="YYYY-MM-DD+1 00:00" \
        --date=format:'%H:%M' --pretty='%ad %h %s' origin/main
 git log --merges  --since=... --pretty='%ad %h %s' --date=format:'%H:%M' origin/main   # PR numbers
 ```
 Merge lines carry the PR number — that is the review trail; the non-merge log is what actually changed.
 Group commits into streams (endpoint names lead the subject) rather than listing 20 subjects.
 ## 2. Live census (parallel: one call per host + one endpoint sweep)
 Endpoint sweep from any LAN box — `/health` is honest on all four (archon binds only after full load):
 ```bash
 for u in 192.168.0.143:7770 192.168.0.143:7771 192.168.0.235:7770 192.168.0.143:7772; do
  printf "%s %s\n" "$u" "$(curl -s -m 12 -w ' [%{http_code}]' http://$u/health | head -c 160)"; done
 curl -s http://192.168.0.143:7770/v1/models    # dragoon lists EVERY engine it serves, incl. NPU-lane models
 ```
 Per host: `uptime -s; uptime -p`; `systemctl show <llm units> -p ActiveEnterTimestamp -p NRestarts -p DropInPaths`
 (`sudo` for the root LLM units, `--user` for the quadlets); `list-units --failed`; `free -h`;
 `journalctl -k --since "<evening>" -p err`; the host's own engine log tail.
 ## 3. Attribution rules (where reports go wrong)
 - **Never call a host reboot from a container's start timestamp.** Check `uptime -s` first; if uptime spans the
  event, the trigger was a **container restart** — find it with
  `journalctl --user -u <name>.service --since … --until …` + `podman inspect <c> --format '{{.State.StartedAt}}'`.
  (This exact mistake mislabelled a 2026-10-19 Pi-hole incident as boot-caused; the law's remedy belongs after
  *any* restart, which is a different action item.)
 - `podman stats` is a 28-container wall — sort/limit it; RSS of the LLM tenants is what matters.
 - This podman's inspect template has **no `.Config.PodName`, no `.Config.GroupAdd`, and `.HostConfig.Devices`
  can read `[]` even when a quadlet `AddDevice=` worked**. Prove GPU use from the engine's own log
  (`ggml_vulkan: Found 1 Vulkan devices: … Radeon 8060S (RADV GFX1151)`), not from inspect.
 - Kernel lines: **count** occurrences (`journalctl -k --since '7 days' | grep -c "NETDEV WATCHDOG"`) before
  calling a one-off a trend.
 - Failed units: `systemctl show <u> -p ExecMainExitTimestamp -p ExecMainStatus --value` separates
  "broken since boot" from "broke yesterday" — and a nightly failure (e.g. logrotate) is a live risk, not noise.
 ## 4. Report shape
 Stream table (what landed) → live-state table (what is true now) → **corrections to my own earlier record** →
 open items that need Frank's decision, each with the evidence line and the one action. Flag anything that would
 touch host config outside the repo as a decision, never a silent fix.
@@ -0,0 +1,36 @@
 ---
 name: fork-locked-gguf-endpoint-trial
 description: "Trial a fork-locked GGUF (custom tensor types: ternary/PQ2_0/PTQ1_0, vendor Hadamard metadata) as a replacement payload on a fleet llama.cpp endpoint: identify the fork, close provenance of local variants, build the right binary, and run one trap-guarded census window that measures VRAM, per-slot window, tool/vision/reasoning channels, and long-context stability."
 ---
 # Fork-locked GGUF trial on a live endpoint
 Use when a candidate GGUF carries **non-stock tensor types** (custom type ids, vendor metadata such as `prism.hadamard.*`) so mainline llama.cpp refuses it or loads a sibling `F16` file silently with garbage. Pairs with `gguf-header-vram-fit-analysis` (paper pricing); this skill is the *measure-it* half.
 ## 1. Header census decides everything downstream
 Range-parse `resolve/main/<file>.gguf` bytes 0–48 MiB (metadata is ~11 MiB at 250k vocab; GGUF v3 strings are **u64**-length). Extract: `general.architecture`, `block_count`, `full_attention_interval`, `attention.head_count_kv`, `key_length`/`value_length`, `context_length` (target window > native ⇒ YaRN), `<arch>.nextn_predict_layers` (absent ⇒ no drafter, ever), tensor-type histogram, and per-tensor byte sizes from consecutive `offset` deltas ⇒ exact bpw.
 - `KV = full_layers × head_count_kv × key_length` elements/token **per cache**; only full-attention layers bill per token, linear/DeltaNet layers bill a fixed state per slot.
 - Ternary packs shrink weights only. At 262,144 tokens KV (16 full layers, 4×256) = 16.0 GiB f16 / 8.5 GiB q8_0 / 4.5 GiB q4_0 — 3× the 6.71 GiB of weights. **The cache is the wall, never the pack.**
 ## 2. Fork identification and tag ancestry
 - Map custom type id → name from the vendor fork (`ggml/include/ggml.h` on its branch, e.g. `GGML_TYPE_PQ2_0 = 142`, `PTQ1_0 = 143`).
 - `GET /repos/<fork>/compare/<tag>...<branch>` → `ahead_by` + commit subjects tells whether the newest **release** contains a fix, without reading history. Release workflows lie by omission: grep the workflow for the flag you need (e.g. prebuilt CUDA lacked `GGML_CUDA_FA_ALL_QUANTS` → quantized/mixed KV silently runs flash attention on CPU, ~2× slower; vendor issue #267).
 ## 3. Close provenance of payload variants already on disk
 `sha256sum` the local file (7.2 GB ≈ 15 s NVMe), then search the Hub (`/api/models?search=<name>`, `/api/models/<repo>?blobs=true` → sibling `lfs.sha256` + size). Equal size + different sha = re-weighted variant, not a corrupt copy. Known houses: `dealignai/*-CRACK-*` (uncensored), `ManniX-ITA/*-MTP-GGUF` (appended MTP head ≈ +450 MB, restores a drafter the official file lacks). Same size/geometry ⇒ the VRAM verdict carries across variants; behaviour (refusals, tool calls) does not.
 ## 4. Build recipe (Dankclaw, RTX 3090)
 `/usr/local/cuda` does not exist for non-interactive shells; `/usr/bin/nvcc` is a Debian wrapper. Mirror the known-good cache instead of guessing:
 ```
 cmake -G Ninja -B build-cuda-prism -DCMAKE_BUILD_TYPE=Release \
  -DCMAKE_CUDA_COMPILER=/usr/bin/nvcc -DCMAKE_CUDA_HOST_COMPILER=/usr/bin/gcc-13 \
  -DCMAKE_CUDA_ARCHITECTURES=86-real -DGGML_CUDA=ON -DGGML_CUDA_FA_ALL_QUANTS=ON
 ```
 nvcc 12.4 refuses gcc 15 (`gcc-13`). FA template instances dominate the build (~150/804 in 12 min); park it with `pkill -f "[r]un-<build>"` + `pkill -x ninja` before timing anything — the bracket stops `pkill -f` matching your own ssh cmdline.
 ## 5. One-window census (never two outages)
 Fetch through a committed script (`-fsSL --fail-with-body`, byte count + LFS sha, no resume, no token in argv), then stage `/tmp` throwaways: candidate env fed to the **repo serve script** via its `*_ENV_FILE` override (never edit remote config), and a runner whose `trap restore EXIT` always kills the candidate by pid and `systemctl start` the production unit + health-polls to 200.
 Order inside the window: copy the production log aside (serve scripts truncate it) → stop unit → wait `memory.used < 1500` → boot candidate → `/health`, boot ledger (`KV buffer`, `compute buffer`, `flash`), `nvidia-smi --query-compute-apps`, `/v1/models`, `/props`, `/slots` (per-slot `n_ctx` is the harness contract, `pool/parallel`), chat probe (does thinking land in `reasoning_content` or `content` — a vendor `--reasoning-in-content true` default breaks the harness channel), tool-call probe (name + valid-JSON `arguments`), 512 px solid-colour vision probe, then a ~190k-token `/completion` fill reading `timings`. Kill the server, then `llama-bench` dtype arms (`-c <pool> -np <slots> -ctk/-ctv -b 2048 -ub 2048 -p 4096 -n 128 -r 1`) under a 1 Hz `nvidia-smi` sampler, `peak_gpu_mib=$(sort -n | tail -1)` per arm. Skip `-mmp 1` unless `-mmproj` is also passed.
 ## 6. Gates that outvote the memory table
 Vendor `KNOWN_ISSUES.md` + open issues (quantized-KV resets near 200k, inert ngram/`--cache-reuse` on hybrid memory, malformed `tool_calls`, prompt-cache loss from re-rendered reasoning); base alignment (an uncensored endpoint replaced by a censored base is a fleet-wide capability loss); and which harness roles point at the endpoint (`models.yml` + `modelRoles`) — tool-heavy roles fail loudly on a `tool_calls` defect. Repo seams pinning `-ctk/-ctv` literals must be re-keyed to read the env file, so a retune moves one file, not two.
@@ -0,0 +1,52 @@
 ---
 name: frank-bench-run-ops
 description: "Operate frank-intelligence-bench runs on the dank fleet: status census, full void + fresh launch, judge cutover, supervisor restart law, watchdog timer, fault-autopsy snippets."
 ---
 Runbook for /home/blank/Projects/frank-intelligence-bench (Bun/TS). Companion to frank-bench-supervisor-recovery (row-voiding for poison); this skill is the ops loop around it.
 ## Status census (run from repo root)
 ```bash
 export RID=$(ls -t runs | grep -m1 frank-archon)   # live run id
 tail -2 runs/$RID/log.txt
 python3 - <<'PYEOF'   # latest-wins cohort census (mirrors score.ts semantics)
 import json, os, collections
 led = f"runs/{os.environ['RID']}/ledger.jsonl"
 best = {}
 for l in open(led):
    r = json.loads(l)
    if r["phase"] != "grade": continue
    k = (r["eval"], r["instance"], r["repeat"])
    if r["ok"] and (k not in best or r["ts"] > best[k]["ts"]): best[k] = r
    elif k not in best: best[k] = r
 by = collections.defaultdict(lambda: [0,0])
 for k,v in best.items(): by[k[0]][0]+=bool(v["grade"]["correct"]); by[k[0]][1]+=1
 for e,(c,n) in sorted(by.items()): print(f"{e}: {c}/{n} = {100*c/n:.1f}%")
 PYEOF
 ```
 `pgrep -f "cli.ts _exec"` = supervisor; `systemctl --user is-active fib-watchdog.timer` = watchdog; last ledger ts older than ~5 min = suspect stall.
 ## Launch laws (each earned by an outage)
 - Code fix + running supervisor = FIX IS NOT LIVE. Restart supervisor: `pkill -f "cli.ts _exec"`, then relaunch.
 - Correct detached form from harness bash: `cd runs/$RID && setsid nohup bun run ../../src/cli.ts _exec run.json >> log.txt 2>&1 < /dev/null & disown`. NEVER the subshell form `( ... & )` — reaped by cgroup within minutes.
 - Preferred launch = `bun src/cli.ts run HOST --judge JUDGE --detach` (in-process spawn + unref, proven 6 h+).
 - Watchdog = systemd user timer `fib-watchdog.{service,timer}` (~/.config/systemd/user), 10 min, Persistent, runs `bun src/cli.ts worker` (idempotent: exits when heartbeat fresh, takes over stale runs via 30 s mtime gate).
 ## Void all results + fresh run (model/endpoint change)
 1. `pkill -f "cli.ts _exec"`; sleep 1.
 2. `mv runs/<id> .AGENTTRASH/run-voided-<reason>-$(date +%s)`; `mv reports/<model>/* .AGENTTRASH/`.
 3. queue.json: set `runs: []` (python json edit).
 4. New run: `bun src/cli.ts run frank-archon --judge frank-dragoon --detach`.
 5. Log the void in docs/log.md (reason, quarantined scope) and commit — never silently erase scores.
 ## Judge cutover (zealot→dragoon pattern)
 Void ONLY LLM-judged evals' `phase=grade` rows (keep ALL gen rows — target output is judge-independent); set `judge` in run.json; restart supervisor; resume rejudges automatically (grade keys incomplete). SciCode = pytest, judge-independent, never voids for judge changes.
 ## Fault-autopsy snippets
 - Engine-fault census: grade rows with `ok:false` + empty text = engine, not model (signature-default trap: "AssertionError × N" with empty text = grades never executed).
 - Runaway-chain detector (HLE loops): gen rows with `finish=="length"` AND completion_tokens==max AND empty text = reasoning degenerated into repetition; measure pre/post any quantization change to separate model behavior from engine artifacts.
 - Census-by-eval: `collections.Counter((r["eval"], r["phase"], r["ok"]) for r in rows if r["ts"] > <cutover>)`.
 - Verdict-parser bugs: probe the live judge on a minimal case (`judgeAalcr`/`judgeHle` via `bun -`), inspect raw head+tail; llama.cpp thinking models may return content:"" with everything in reasoning_content, and prose verdicts when their JSON scaffold breaks.
 ## Reporting etiquette (Frank's rules)
 Quote score as: per-rep %, test avg@1 / avg@3, dev, index-lite; label provisional until all reps land; publish the runaway/parse-rate census next to any handicapped number. Dashboard :8787; `bun src/cli.ts report` renders the trio; `analyze` prints failure census.
@@ -0,0 +1,45 @@
 ---
 name: frank-bench-supervisor-recovery
 description: "Recover a frank-intelligence-bench run after engine faults: detect poison grade rows, void them, restart supervisors with fixed code, judge cutover, watchdog for multi-day runs."
 ---
 Recover frank-intelligence-bench runs on the dank-fleet after engine faults (poison graders, judge swaps, supervisor deaths).
 ## Laws (friction-earned 2026-10-10/11)
 1. **A code fix is only real after the supervisor restarts.** Bun loads code at spawn; an on-disk fix never reaches the running process. Kill `_exec`, relaunch — takeover law makes resume cheap.
 2. **A judge cohort is all-or-nothing.** Never mix judges on one eval's grade rows. Void ALL grade rows for LLM-judged evals (`phase == "grade"`), KEEP all `gen` rows (target output is judge-independent) — resume rejudges from cache.
 3. **Poison census signatures:** grade rows with empty text + forced FAIL = engine, not model. `unparseable verdict` storm = judge output class (empty `content` + chain in `reasoning_content`; or 2048-tok truncation before verdict JSON). Default census sig `AssertionError` masked a poison shift — treat mass-default sigs as red flags.
 4. **Detached launch form matters:** from a short-lived harness shell, `(setsid nohup cmd & )` (subshell) gets cgroup-reaped within minutes — silent death, stale `worker.pid`, no log line. Proven form: `setsid nohup cmd >> log.txt 2>&1 < /dev/null & disown` as the tail of the same shell (survived 6 h overnight).
 ## Void-and-resume procedure
 ```bash
 pkill -f "cli.ts _exec"
 python3 - <<'PYEOF'
 import json, pathlib, shutil, time
 led = pathlib.Path("runs/<RUN_ID>/ledger.jsonl")
 rows = [l for l in led.read_text().splitlines() if l.strip()]
 keep, void = [], []
 for l in rows:
    r = json.loads(l)
    if r["eval"] in (<EVALS>) and r["phase"] == "grade" and r["ts"] > "<CUTOVER_ISO>":
        void.append(l)
    else:
        keep.append(l)
 shutil.copy(led, f".AGENTTRASH/ledger-voided-{int(time.time())}.jsonl")
 led.write_text("\n".join(keep) + "\n")
 print(f"voided {len(void)}; kept {len(keep)}")
 PYEOF
 cd runs/<RUN_ID> && setsid nohup bun run ../../src/cli.ts _exec run.json >> log.txt 2>&1 < /dev/null & disown
 ```
 - Judge cutover variant: void ALL `phase==grade` rows for the judged evals (no ts filter), edit `run.json` `judge` field, relaunch.
 - Validate the judge endpoint first: live probe both directions (correct + incorrect candidate); a good judge returns bare verdict JSON fast.
 - Resume proof = a specific known step flipping FAIL→PASS (or vice versa) in the log within minutes.
 ## Watchdog for multi-day runs
 No cron on the Arch workstations — systemd user timer, idempotent (`cli.ts worker` exits instantly when supervisor heartbeat is fresh; takes over via pid-file 30 s freshness gate):
 `~/.config/systemd/user/fib-watchdog.service`: Type=oneshot, WorkingDirectory=repo, `ExecStart=/usr/bin/bun src/cli.ts worker`, stdout/stderr `append:.../runs/watchdog.log`.
 `fib-watchdog.timer`: OnBootSec=5min, OnUnitActiveSec=10min, Persistent=true, WantedBy=timers.target.
 `systemctl --user enable --now fib-watchdog.timer`; verify `loginctl show-user <u> -p Linger` = yes (survives logout/reboot). Prove idempotence: log line "has a live supervisor — worker exits".
 ## Scoring truth after repair
 Report renders from ledger with latest-wins via `ok` filter (no explicit dedup): ok=false rows drop, recovered key counts once. UI `done` counts unique `(eval,instance,repeat)` completed keys. SciCode denominators: 341 steps/rep (not 1120/3-rep arithmetic traps).
@@ -0,0 +1,30 @@
 ---
 name: frank-job-hunt-grilling-state
 description: "Resume frank-job-hunt: repo is BUILT and deployed (agents live on Dankserver, ntfy on Dankclaw); grilling closed, design v2 shipped; lists pending ops items and invariants."
 ---
 ## Status (2026-10-11): design grilling CLOSED (design v2 signed); repo built, deployed, self-verifying.
 Repo: ~/Projects/frank-job-hunt (workstation) — Gitea `dank/frank-job-hunt` on Dankclaw; Dankserver clone runs timers (sweep 07:30, digest 08:15, Linger=yes). Pre-commit hooks: bun test + tsc + docs-link + secret scan. Tests: 69, strict TS (no `any`; Records for static tables; named contract types).
 ## Machine
 - `agents/sweep.ts`: registry → greenhouse/lever/ashby/workday public APIs → gates → frank-zealot score → `jobs/*/inbox.json|gated.json`; `--dry --ats=` flags; per-site fetch dedupe; per-entry error census.
 - `agents/digest.ts` → ntfy (ntfy.franksdank.cloud, LAN; topic secret in `~/.config/frank-job-hunt.env` 600); degrades to file + exit 1.
 - `agents/review.ts`: funnel metrics (weekly rate 8-10, callback floor 4%).
 - `agents/verify-registry.ts --write`: monthly ATS-locator probe/re-attribute (14 scout mis-attributions repaired).
 ## Truths earned in build
 - Registry truth: **21 live API sites, ~169 manual lane** (vanity Workdays, self-built ATS incl. majors, neogov). Scouts' ats attribution ≈ guess — verify before trusting counts.
 - Gates do the discriminating; zealot only ranks survivors (9B inflates everything: recruiters scored 91 before family gate).
 - Gate law: role FAMILY gates unconditionally (recruiter/sales/people-ops/TPM/solutions, no infra override); topic negatives get infra-token precedence ("full-stack platform engineer" passes). Comp NEVER gated; unstated location passes to human.
 - Metro regex = Puget Sound list only (Tuolumne CA leak fixed — WA localities, no CA decoys).
 - ATS tokens: first DNS label (greenhouse.harpereng.com→harpereng); vanity workday URLs are NOT CXS-resolvable → manual lane.
 - Zealot (llama.cpp thinking model): send `chat_template_kwargs:{enable_thinking:false}` + max_tokens ~600; verdict in `content` then; `reasoning_content` fallback kept.
 ## Pending (user-side / next session)
 1. Porkbun API 503'd: public A record `ntfy → 71.227.227.172` still missing (LAN works; add via UI when API recovers, for off-LAN phone).
 2. Frank: phone ntfy app subscribe (topic in env file); LinkedIn CSV export → `contacts/`.
 3. First production digest = tomorrow 08:15; check `journalctl --user -u frank-job-digest.service` + phone.
 4. bg_6 (last session): full dry-sweep proof of family gate (top-10 must be engineering-only) — check `agent://`/proc result if pending.
 5. Resume Matcher compose (`agents/resume-matcher/compose.yaml`) not deployed — needs image digest pin on Dankserver.
 6. `prep/` STAR/LP bank content fill (daily-loop.md scaffolded).
@@ -0,0 +1,35 @@
 ---
 name: frank-job-hunt-maintenance
 description: "Maintain frank-job-hunt agents: live-census gate hardening loop, registry locator verification, and the workstation/Dankserver/Dankclaw deploy-sync ritual."
 ---
 # frank-job-hunt maintenance
 Repo `~/Projects/frank-job-hunt` (Gitea `dank/frank-job-hunt` on Dankclaw 192.168.0.143:3000). Production: Dankserver user timers `frank-job-sweep.timer` 07:30, `frank-job-digest.timer` 08:15 (`Linger=yes`). ntfy relay: Dankclaw quadlet `ntfy.service`, route `ntfy.franksdank.cloud` (no anubis), LAN record in `hosts/custom.list` (Pi-hole v6 file at `/home/dank/Containers/pihole/etc-pihole/hosts/custom.list`; v6 API paths are hostile — edit the file, then `podman exec pihole pihole restartdns`). Secrets: `~/.config/frank-job-hunt.env` (600, workstation + Dankserver).
 ## Law (validated 2026-10-11)
 - The fleet judge (`frank-zealot`, dankclaw:7771) is a **ranker, never a gate** — it inflates anything reaching it (non-technical roles scored 88-91). All discrimination lives in deterministic gates (`agents/lib/gates.ts`); zealot only ranks survivors.
 - Thinking-model fault: verdict lands in `reasoning_content` with `content:""` → judge sends `chat_template_kwargs:{enable_thinking:false}` (0.7s clean JSON).
 - **Family beats topic**: role family (recruiter/sales/finance/PM/designer/people-ops/revops/…) gates `gate:scope` unconditionally — no infra-token override ("DevOps Recruiter" is recruiting). Compound technical titles keep the `INFRA_TITLE` override via `NEG_TITLE` branch.
 - **gate:region**: remote is US-only (visa reality). "Remote - Bangalore" = onsite abroad → gate; `US` regex pass wins over `NONUS` match ("U.S. & Canada" passes).
 ## Gate hardening loop (live-census, TDD)
 1. `bun agents/sweep.ts --dry` (full lane ≈ 30–90 s; 852 postings ≈ 62 pass / 790 filed).
 2. Classify leaks in the top-10: family gap / region gap / scoring tail. Accept long tail (Director/Founder edge cases) — digest + human curation is the design.
 3. Token fix in `gates.ts` regexes (`NEG_FAMILY` = no override; `METRO`/`US`/`NONUS` for arrangement). NEVER dedupe-check by memory — read file first; the file has bitten line-offset edits repeatedly.
 4. Pin every leak with a named regression test in `agents/test/gates.test.ts` before/with the fix.
 5. `bun test agents/test/ && bun x tsc --noEmit` — hooks re-run these at commit.
 6. Ship: `git commit` (pre-commit = tests + tsc + docs-link + secret scan) → `git push` → `ssh dankserver 'cd ~/Projects/frank-job-hunt && git pull'` (timers pull from master; Dankserver drift = tomorrow's run is stale).
 ## Registry verification (monthly, `agents/verify-registry.ts`)
 Scouts' `ats`/`ats_identifier` are guesses (14/84 were wrong). Ritual:
 1. `bun agents/verify-registry.ts` (dry, ~70 s serial) → REPAIR census.
 2. `--write` applies; repairs with live jobs preferred over empty boards (0-job boards 404 later).
 3. Unresolved = honest manual lane (vanity Workdays, self-built ATS incl. majors, neogov) — NOT a code bug; per-entry error census in sweep output is the same signal.
 4. Update `targets/README.md` census lines + `docs/log.md`; commit/push/pull (same ship step).
 ## Pitfalls
 - `--ats=<x>` smoke filters the census line — "N API-sweepable" reflects the filter, not the registry; don't diagnose a phantom bug.
 - Workday vanity careers URLs (`careers.uw.edu`) are NOT CXS-API-resolvable; tenant-only identifiers are (site path required).
 - Root `README.md` vs `targets/README.md` name collision in edit anchors: use full path headers.
 - Zealot endpoint probe: `curl http://192.168.0.143:7771/v1/models`.
@@ -0,0 +1,39 @@
 ---
 name: frank-model-bench-grilling-state
 description: "Resume the frank-model-bench design grilling: AA Intelligence Index v4.3.2 research brief, fleet endpoint facts, dataset gating, and all settled design decisions for /home/blank/Projects/frank-model-bench."
 ---
 # frank-model-bench — Grilling State (design settled 2026-10-09, awaiting build go-ahead)
 Target dir `/home/blank/Projects/frank-model-bench` is EMPTY (no git). Init from zero.
 ## Settled design decisions
 - **Scope**: Tiered reproduction of AA Intelligence Index v4.3.2 (10 evals, 4 categories; Agents 30 / Coding 20 / General 30 / Science 20).
  - **Tier A (local, self-graded)**: SciCode, Terminal-Bench 4.0 (podman on Dankclaw via ssh one-shot), AA-LCR, HLE incl. image questions (vision towers).
  - **Tier B (external dep)**: GDP.pdf (LiteParse+vision+judge).
  - **Tier C (never run; AA reference rows only)**: AA-Briefcase, GDPval-AA, AutomationBench-AA, AA-Omniscience (public set is 600/6000 — demoted), CritPt (key-gated grader API 10/24h — demoted).
  - Locally-run weight ≈ 45% of AA index weight. Headline = "Index-lite" (category-weighted over run evals, formula on-page).
 - **Stack**: Bun/TS orchestrator (UI, queue, ledger, reports) shelling out to commit-pinned vendored uv venvs per upstream harness (inspect_ai, Harbor, SciCode/HLE scripts). `evals.yml` manifest pins git URL+SHA+entrypoint+args+repeats per eval.
 - **UI**: local web dashboard, localhost bind only, SSE live tail, start wizard; CLI `frank-bench`.
 - **Endpoints**: registry `hosts.yml` (name, base_url, api_key_ref, model, ctx, backend, role, cap). Discovery = probe known fleet hosts ports 7770-7799 `/v1/models` + `/props`, confirm-then-append. Fleet: frank-archon dankserver:7770 (radiance TP=2 R9700, 200k), frank-dragoon dankclaw:7770 (halogen, 200k×2), frank-zealot dankclaw:7771 (llama.cpp 3090, 200k×2). All OpenAI-compat + API key + vision.
 - **Judge**: self-hosted fleet model ONLY, default frank-zealot; hard no-self-judge rotation rule. Scores labeled `local-judge`, drift vs AA hosted graders expected/documented.
 - **Execution**: per-endpoint runs, strictly serial queue, one request in flight per eval (per-endpoint cap), temp 0.6 reasoning ON, max_tokens cap 32,768, AA-style 30-attempt retry, per-sample timeout = ctx ÷ measured decode rate.
 - **Durability**: per-sample JSONL ledger is canonical artifact; resume mid-eval; reports commit to git (reports/<model>/<run-id>/{index.html,data.json,hf-card.md,manifest+ledger SHA-256}), ledgers gitignored.
 - **AA comparison**: free Data API key → `bench sync-aa` pins headline indices; per-benchmark refs hand-seeded in `references/aa-scores.yml` (source URL + fetched-at + index version per row). Free=100 req/24h headline-only; Pro=500 req/24h per-benchmark (stubbed for later).
 - **Datasets**: `bench init-data` checklist (hf auth login + accept terms cais/hle, surgeai/GDP.pdf, Harbor Hub); checksum cache ~/.cache/frank-bench/datasets; gated evals refuse with fix-URL and continue suite.
 - **Methodology updates**: version-pinned manifests + immutable history; update = one commit: evals.yml bump + docs/methodology rewrite + log.md + resync snapshot. AA cadence ~2-3 minor versions/week; changelog artificialanalysis.ai/changelog.
 - **KB**: `docs/` inside repo, OKF v0.1 (type required; index.md per dir; log.md newest-first; .okf/config.yaml from omp-docs); Obsidian-wikilink convention per serverAppConfigs-docs.
 - **Git**: Gitea on Dankclaw remote, master base, worktree branch per milestone, pre-commit: bun test + shellcheck + OKF validate. Secrets: ~/.config/frank-bench/secrets.env 600.
 - **Tests**: bun test w/ scripted mock OpenAI endpoint (full run→ledger→HTML offline); Playwright dashboard e2e; `bench smoke` manual real-endpoint.
 - **Milestones**: M1 scaffold+registry+mock; M2 SciCode E2E w/ real report trio; M3 rest of Tier A + queue/resume; M4 dashboard UI + discovery wizard; M5 GDP.pdf + AA snapshot + peer tables.
 - **Reports**: single-page HTML, offline-openable, no external assets; per-benchmark rows: local | AA ref | Δ | repeats | n | graded-by; Tier C rows "AA reference only"; speed strip captured (no AA speed compare).
 ## Key research facts
 - AA Data API: base https://artificialanalysis.ai/api/v2, `x-api-key` header, OpenAPI at /api/v2/openapi; free = /language/models/free headline indices.
 - Eval repos: SciCode1/SciCode (HF, Apache), cais/hle (gated, MIT, 2500 q, ~0.27GB), ArtificialAnalysis/AA-LCR (public, Equality Checker prompt public), surgeai/GDP.pdf (gated, Gemini 3.5 judge, inspect_ai), harbor-framework/terminal-bench 4.0 (66 tasks, CONTAINERS_BACKEND=podman, Harbor Hub gated), AA-Omniscience-Public 600q, CritPt public grading API 10/24h.
 - AA org repos: Stirrup (MIT agent harness), aa-agentperf-local, aiperf, optima, StirrupJS.
 - AA settings: temp 0/0.6, 16k+ max tokens, 30 retries, 1-5 repeats pass@1; Omniscience index [-100,100] accuracy−hallucination.
 - Search chain web/kagi→web/searxng (search.franksdank.cloud) verified working 2026-10-09.
 ## Accepted risks (user-informed)
 - Elo-pairwise agentic evals unreproducible locally; self-hosted judge drift; Omniscience (top quant-damage signal) not run; HLE vision inclusion diverges from AA text-based posture.
@@ -0,0 +1,81 @@
 ---
 name: frank-tts-add-cloned-voice
 description: "Add or repair a cloned voice on the dank fleet: pack builder, the reference.wav contract, the boot warm hook (argv-cap and env-quote laws), and how to prove a voice really answers."
 ---
 # Adding (or repairing) a cloned voice on the dank fleet
 Repo law lives in `serverAppConfigs-docs/Dankclaw/Voice Packs.md` and
 `Frank TTS Engine.md` — read those for the pack format. This skill is the
 **operating sequence plus the traps that cost real time on 2026-10-18**.
 ## Stack, fast
 - `frank-tts-engine` — arm A `qwentts.cpp tts-server`, container-internal `:8880`,
  publishes **no port**. Reach it with `podman exec frank-tts-engine curl …`.
 - `frank-tts` — OpenAI façade on host `:7772`; resolves voice **by name**.
 - Packs: `/home/dank/voices/<name>/` with `reference.wav` (+ manifest, `.spk`,
  `.rvq`). Builder: `scripts/build-voice-pack.sh` (crop 19.84–25 s, first 10 s of
  any source is forbidden).
 - Weights: `/home/dank/models/Qwen3-TTS-GGUF/` —
  `scripts/download-frank-tts-engine-qwentts.sh [--verify-only]` (1.4 GiB, ~18 s
  on the LAN; verifies byte count + Hub LFS sha256).
 ## Sequence
 1. Build the pack (dry-run first — sizes are arithmetic and asserted).
 2. Deploy the engine only if its files changed:
   `./scripts/deploy.sh dankclaw --service frank-tts-engine`
   (first run builds the image: ~10 min recursive source clone).
 3. Register/warm: `podman exec frank-tts-engine /app/warm-voices.sh`
   — registers **every** pack each run (the engine replaces a name it already
   holds; `tools/tts-server.cpp:148`), then synthesizes twice per voice.
 4. Prove from the consumer side, not the config:
   `curl -s localhost:7772/v1/audio/voices` then a real
   `POST /v1/audio/speech` and listen to the bytes.
 ## Trap 1 — the kernel's argument cap (this broke the first deploy)
 `/usr/bin/curl: Argument list too long` in the warm log ⇒ a request body was
 passed as **one argv string**. Linux caps a single argument at
 `MAX_ARG_STRLEN = 131 072 bytes`; a ~1 MB `reference.wav` base64's to ~1.27 MB.
 curl never runs, and hooks report it as `HTTP no response` while `/health` is
 green. Fix = write the body to a file and use `--data-binary @file`; feed the
 payload through a redirection, not `$(base64 …)`.
 Regression-test shape: **real** curl + real listener + a fixture >128 KB, so the
 kernel (not a stub) produces the failure. Any pack over ~96 KB trips it.
 ## Trap 2 — two readers of the env file disagree about quotes
 `bash set -a; source` strips `"…"`. podman's `--env-file` (how the unit really
 reads it) does **not**. A value interpolated into a JSON body therefore arrives
 quoted and invalidates it. Test both readers, not just `source`.
 ## Trap 3 — locally built images skip rebuilds on a stale hash
 `build_compose_image` compares a `cfhash` label; it must cover every file the
 `Containerfile` `COPY`s, or an edited `app.py`/hook deploys "successfully" while
 the container runs old code.
 ## Measured numbers (2026-10-18, deployed build — retire the trial's ladder)
 | thing | value |
 |---|---|
 | first synthesis of a freshly registered voice | 1 883 ms |
 | later short requests | 1 226–1 283 ms |
 | ~110-word request (repeat) | 9.4 s / 9.8 s — tracks generated audio, not state |
 | whole boot warm, 3 packs | 15.2 s |
 | engine resident | ~4.0 GiB |
 The trial's `6.2–8.0 s cold → 0.5 ms warm` claim does **not** reproduce; warming
 is for registration (registry is memory-only, re-register ≠ warm) plus ~0.6 s.
 ## Ops notes
 - `systemctl --user stop` **removes** the quadlet container — `podman start` then
  finds nothing. To run the engine without its `ExecStartPost` hook, use a
  separate container, not stop+start.
 - `podman cp` of a fixed script into a running container is a **trial only**: the
  layer dies with the container. Merge + redeploy to make it durable.
 - Nothing on the voice pair exposes `/metrics`; Prometheus can't scrape it (a
  blackbox HTTP probe on 7772 is the only honest option).
@@ -0,0 +1,81 @@
 ---
 name: frank-tts-consumer-voice-triage
 description: "Triage a consumer (OpenWebUI, omp, open-notebook) rejecting or ignoring a frank-tts voice name: prove whether the server or the browser-side Kokoro.js engine produced the error."
 ---
 # frank-tts consumer voice triage
 A consumer says a voice name is invalid, speaks in the wrong voice, or is
 silent. `frank-tts` (`192.168.0.143:7772`, shim
 `dankclaw/voiceservice/app.py`) resolves `voice=<name>` against
 `/home/dank/voices/<name>/reference.wav` and answers **400 + the list of
 voices that exist** for a name it cannot resolve — never a silent fallback.
 Any error naming a *different* voice list did not come from it.
 **Signature that decides the case immediately:** an enum of ~29 names
 `af_heart, af_alloy, … am_*, bf_*, bm_* … bm_fable` is **Kokoro's fixed pack**,
 the voice list of **Kokoro.js running in the browser** (OpenWebUI ships it
 in its own front end as TTS engine value `browser-kokoro`, with a personal
 "Kokoro.js dtype" setting; model `onnx-community/Kokoro-82M-v1.0-ONNX`).
 `narrator1/2/3` are frank-tts cloned voices. Kokoro cannot clone.
 ## Instrument ladder (stop at the first that answers)
 1. **What the endpoint actually accepts** (never infer from a consumer's text):
   `curl -s http://127.0.0.1:7772/v1/audio/voices` → JSON array of pack names.
 2. **Speak with the consumer's exact body, from inside the consumer's
   container** — same network, same shape. Write the JSON to a file and
   `--data-binary @file` (nested `sh -c` quoting silently sends an empty
   body and yields a bogus `400 malformed request body`):
   ```
   printf '%s' '{"model":"frank-tts","input":"probe","voice":"narrator1","response_format":"mp3","speed":1.0}' > /tmp/p.json
   podman cp /tmp/p.json <consumer>:/tmp/p.json
   podman exec <consumer> curl -sS -o /tmp/o.bin -w 'http=%{http_code} type=%{content_type} bytes=%{size_download}\n' \
     -X POST http://host.containers.internal:7772/v1/audio/speech \
     -H 'Content-Type: application/json' --data-binary @/tmp/p.json
   ```
   `200 audio/mpeg|audio/wav` ⇒ the server path is healthy; the failure is elsewhere.
 3. **Did the request arrive at all?** `podman logs --tail 400 <consumer> | grep -c audio/speech`.
   A server-path failure leaves a log line **and** a frank-tts error body; a
   client-side engine leaves **neither**. This contrast is the discriminator.
 4. **Where the rejection string lives** (proves the emitter without guessing):
   ```
   podman exec <consumer> sh -c 'grep -ho ".\{200\}Should be one of.\{80\}" /app/build/_app/immutable/chunks/*.js | head'
   podman exec <consumer> sh -c 'grep -ho ".\{60\}af_heart.\{200\}" /app/build/_app/immutable/chunks/*.js | head -2'
   ```
   Matched inside the front-end bundle ⇒ browser-side validator, not the API.
 5. **Config authority sweep** (OpenWebUI): admin config is the `config`
   table (one key per row, JSON `value`; expected
   `audio.tts.engine=openai`, `audio.tts.model`, `audio.tts.voice`,
   `audio.tts.openai.api_base_url`); per-user overrides are the `settings`
   JSON column of table `user` (singular, no `is_active`; some rows hold the
   string `null` → guard it). `audio.stt.*` and `audio.tts.*` are separate.
   No `sqlite3` CLI in the image or on the host: `podman exec -i <c> python -`
   with the stdlib module. **`podman exec` needs `-i` to accept a heredoc
   script** — without it the script is silently dropped and you get no output.
 ## Known traps
 - OpenWebUI is a **rootless** quadlet: `sudo podman …` reports *no such
  container*. Read it rootless.
 - `podman ps` in this podman build has no `.ImageName` field — use `{{.Image}}`.
 - The in-browser engine choice is **per-browser storage**: empty
  `user.settings` + correct admin config + zero backend hits is the normal
  shape of this bug. Fix is UI: Settings → Audio → TTS Engine → **Default**.
 - `GET /api/config` publishes no `audio` block, and nonexistent `/api/...`
  paths return the SPA HTML with `200` — never conclude "config missing" from
  an HTML body.
 - TTS is memory-registry sensitive: the engine's voice registry is
  memory-only, so "every name returns 400" after a restart points at the warm
  pass, not at the caller (see [[frank-tts-add-cloned-voice]]).
 ## Local playback side (omp `/say`, manual probes)
 If synthesis succeeds (`200`, sane WAV bytes) but nothing is audible, the
 fault is the PipeWire graph, not the endpoint:
 `wpctl status` (default sink marked `*`, and *Default Configured Devices* —
 a remembered-but-offline `bluez_output.*` there is the classic silent
 route), `wpctl get-volume @DEFAULT_AUDIO_SINK@`, `pw-play -v <file>` (expect
 `stream drained` + exit 0), and target a device explicitly with
 `pw-play --target <node-id>` to identify which hardware is live. A one-word
 clip (~0.7 s) is easy to miss — probe with a multi-second sentence.
@@ -0,0 +1,55 @@
 ---
 name: franksign-worktree-db-cred-trap
 description: "Diagnose franksign e2e seam 5 / health 503 db:down in a fresh worktree: setup-dev.sh minted a password that mismatches the shared franksign-db container."
 ---
 # franksign fresh-worktree DB credential trap
 ## Symptom
 `tests/run.sh` in a fresh franksign worktree fails seam 5 ("e2e server did not
 become healthy") while the server log says `franksign-api listening on :3100`.
 Manual probe shows the server IS up:
 ```bash
 PORT=3100 node --env-file=.env apps/api/dist/cli.js >/tmp/manual-e2e.log 2>&1 &
 sleep 2; curl -s http://127.0.0.1:3100/health
 # -> 503 {"status":"degraded","db":"down",...}
 ```
 Not a regression, not a :3100 port collision (check `ss -tlnp | grep 3100` to rule that out).
 ## Root cause
 `infra/setup-dev.sh` mints a fresh `POSTGRES_PASSWORD` per checkout
 (`if [ ! -f infra/postgres.env ]`), but `franksign-db` + `franksign-pgdata`
 are shared box state owned by the main checkout
 (`~/Projects/franksign`). The new worktree's `.env` DATABASE_URL then fails
 TCP auth against the initialized volume.
 The setup script masks it: its readiness gate is
 `podman exec franksign-db pg_isready`, which uses the in-container local
 socket and passes regardless of password — so setup prints "postgres ready"
 while the checkout is dead on arrival.
 ## Fix (git-ignored files, no commit needed)
 Copy the shared credentials from the owning checkout:
 ```bash
 grep DATABASE_URL /home/blank/Projects/franksign/.env   # source of truth
 # PUT that exact DATABASE_URL line into this worktree's .env
 # PUT the matching POSTGRES_PASSWORD into this worktree's infra/postgres.env
 ```
 Gotcha: the shared password may contain literal `$$`. Keep it byte-for-byte —
 systemd `EnvironmentFile` and `node --env-file` both read values literally,
 so `$$` in the file IS `$$` in the password. No escaping, no de-escaping.
 ## Verify
 ```bash
 PORT=3100 node --env-file=.env apps/api/dist/cli.js &  # then
 curl -fsS http://127.0.0.1:3100/health   # -> {"status":"ok","db":"up"}
 tests/run.sh                             # 14/14
 ```
 ## Permanent fix (proposed, not yet landed)
 `setup-dev.sh` should reuse `~/.config/containers/systemd/postgres.env`
 (symlink to the owning checkout) when present instead of minting new creds.
@@ -0,0 +1,54 @@
 ---
 name: gguf-header-vram-fit-analysis
 description: "Decide if a GGUF model fits an LLM endpoint's GPU at a target context window: HTTP range-parse the header for KV geometry and custom quant types, derive the KiB/token rate law, price non-KV from measured boots (own repo + the publisher's benchmark reports), and gate on runtime lock-in (fork, build flags, drafter) before any download."
 ---
 Answer "can model M fit window W on endpoint E (plus vision?)" **before** downloading anything. The GGUF header carries the truth; measured boots are the price list.
 ## 1. Range-parse the GGUF header from the Hub (no download)
 `GET` the `resolve/main/<file>.gguf` URL with `Range: bytes=0-N` and a `User-Agent: curl/8` header, parse GGUF in Python (`struct`):
 - Layout: magic `GGUF` (read `buf[0:4]` directly — do NOT `read_string()` it), u32 version, u64 ntensors, u64 nkv, then KV pairs (v3: u64 string lengths; v2: u32), then tensor-info table (name, ndim, dims u64[], type u32, offset u64). Handle EVERY array element type or the parse desyncs mid-metadata.
 - **Metadata is >8 MiB** when vocab is ~250k (tokenizer arrays live in the KV section). Fetch 32–64 MiB.
 - **Per-tensor byte sizes without a downloader**: the data section is in table order — `size(i) = offset(i+1) - offset(i)`, last = `file_size - header_end - offset(last)`. Then `bits/elem = bytes*8/prod(dims)`. That names unknown type ids by their rate (2.125 bpw ⇒ ternary-in-2-bit-slots + fp16 scale/128; 16.0 ⇒ BF16; 32 ⇒ F32) and totals weights per type.
 Extract: `general.architecture`, `block_count`, `full_attention_interval`, `attention.head_count_kv`, `key_length`/`value_length`, `context_length`, `embedding_length`, `ssm.*`, and **`<arch>.nextn_predict_layers`** — its absence (plus `block_count` = real layers, not +1) means **no in-file MTP head** (MTP is a property of the file, not the flags). Type histogram decides stock vs fork: a type id above stock `GGML_TYPE_COUNT` is fork lock-in — read the fork's `ggml/include/ggml.h` enum to name it.
 ## 2. KV rate law (the wall)
 For hybrid (qwen35-style) models only the FULL-attention layers bill per token; linear/DeltaNet layers bill a fixed state per SLOT (≈50–60 MiB/slot on 27B-class hybrids — noise vs KV, but it is what lets N slots fit).
 ```
 elems/token/cache = (block_count / full_attention_interval) × head_count_kv × key_length
 B/token           = elems × bytesK + elems × bytesV      (K and V both)
 bytes/elem: f16=2.0, q8_0=1.0625, q4_0=0.5625, q4_1=0.578125
 ```
 Fleet-verified instances: qwen35-9B (8 full layers) 32 KiB/token f16; qwen35-27B (16 full) 64 KiB/token f16, 34 KiB q8_0, 18 KiB q4_0. A low-bit WEIGHT quant never moves this line — state it explicitly, it is the question people actually ask. `--flash-attn on` is required for quantized V; quantized KV needs a `GGML_CUDA_FA_ALL_QUANTS=ON` build.
 ## 3. Price non-KV from MEASURED boots, never a formula
 Two anchors beat one:
 - **Own repo**: closest runbook boot (same arch, same card, ideally same mmproj): `non_kv = boot_used − rate × boot_pool`, then swap weights/mmproj/drafter/ubatch-rung deltas.
 - **Publisher**: their published benchmark/server reports (e.g. a `community-benchmarks/<card>.md` or `KV-CACHE.md`) carry peak `nvidia-smi` and a steady-state figure for a named argv — back out their overhead = steady − weights − KV(× their pool) − mmproj. Divergence between the two anchors IS your uncertainty band; report both ends.
 Card/vendor peak-VRAM at bench context also calibrates compute buffers at small ubatch; the fleet's ubatch-rung costs (≈0.3 GiB @1024, ≈0.75 GiB @2048 on a 27B) cover the rest.
 Card ceiling from settled boots (`used + free`, e.g. 24,125 MiB on the 3090), not the spec sheet. An mmproj bills ~1.5× its file size. Keep ≥1 GiB headroom when ranking arms; tightest proven fleet fit is 489 MiB.
 ## 4. Gates beyond VRAM
 - **Target window > `context_length`** ⇒ YaRN required (`--rope-scale = target/native`); quality at >1.2–1.5× on aggressive quants is unmeasured — say so.
 - **Pool divides across slots**: `n_ctx_slot = CTX_SIZE / PARALLEL`; the per-slot number is the harness contract, and the endpoint's role (e.g. compaction hub needing ≥170k) picks the geometry.
 - **Fork/custom-quant lock-in checklist** (answer all, cite ids):
  1. which fork/branch, and does the pinned release tag contain the needed fixes — `GET /compare/<tag>...prism` and read `ahead_by` + commit subjects (a tag 5 commits behind contains everything merged earlier);
  2. host CPU traps (e.g. AVX-512 load segfaults crash even with all layers GPU-offloaded);
  3. **does the release workflow pass the build flags the contract needs** — grep the release workflow's cmake args: prebuilts often omit `GGML_CUDA_FA_ALL_QUANTS`, and without it mismatched/unsupported K/V types silently run flash attention on the CPU;
  4. drafter availability (in-file `nextn`, a paired drafter, or nothing) — no drafter means the decode regression is unfixable;
  5. pack choice per architecture (the vendor's throughput table is generation-specific; a community report on the same GPU family outranks it);
  6. behavior/role risk: base model censorship posture, `tool_calls` defects, `reasoning_effort` template gate, prompt-cache `--cache-ram` vs host RAM actually available.
 - Vision: needs `--mmproj`; probe with ≥256 px solid color; only the OpenAI `image_url` content part reaches the model.
 ## 5. Output
 Table of arms (pack × KV dtype × slot geometry) → KV MiB, total, free vs ceiling, FITS/FITS-tight/NO FIT, with the uncertainty band; then the gate list. State every `[INFERENCE]`/estimate. The boot ledger (verbosity 4), not the arithmetic, is the referee; benching requires stop+mask per fleet policy.
@@ -0,0 +1,93 @@
 ---
 name: gguf-lora-adapter-fit-census
 description: "Read-only census before applying a GGUF LoRA/adapter to a llama.cpp (or fork) endpoint: Hub metadata, declared base provenance, runtime flag support, and the behavioural probe that proves the effect."
 ---
 # GGUF LoRA / adapter fit census (read-only, before you promise a file to a payload)
 A 3 MB adapter is a payload change: it edits the compute graph at load. Do the census
 before editing an endpoint's trio, and prove the EFFECT behaviourally — no metadata,
 card table, or health gate can see it.
 ## 1. Census the Hub repo first (no auth for public repos)
 ```bash
 curl -sS "https://huggingface.co/api/models/<org>/<repo>?blobs=true" | python3 -c "
 import json,sys; d=json.load(sys.stdin)
 print(d.get('pipeline_tag'), d.get('library_name'))
 print([t for t in d.get('tags',[])][:20])          # base_model / base_model:adapter rows matter
 for s in d['siblings']: print(s['rfilename'], s.get('size'), (s.get('lfs') or {}).get('oid'))"
 curl -sS "https://huggingface.co/<org>/<repo>/raw/main/README.md" > /tmp/card.md   # grep for --lora flags
 ```
 - `base_model` / `base_model_relation: adapter` name the pack the adapter was built for.
 - **A file with `lfs.oid = None` is a plain git object**: pin the sha256 of the Hub's bytes,
  not an LFS oid. Fetcher law still applies: `curl -fsSL --fail-with-body`, byte count,
  sha256, `--verify-only`, no resume.
 ## 2. Read the adapter's own GGUF KV section (settles provenance in one read)
 Small python read of the KV pairs — no torch, no download beyond the adapter itself:
 magic `GGUF`, `u32 ver`, `u64 n_tensors`, `u64 n_kv`; key = `u64 len` + bytes; type `u32`
 (0 u8,1 i8,2 u16,3 i16,4 u32,5 i32,6 f32,7 bool,8 str,9 array,10 u64,11 i64,12 f64);
 array = `u32 elem_type` + `u64 count`.
 Keys worth printing: `general.type` (`adapter`), `adapter.type` (`lora`),
 `adapter.lora_alpha`, and whatever provenance the publisher wrote — e.g. PrismML/abliteration
 packs carry `prism.abliterate.base_gguf`, `base_sha256`, `direction_row`, `target_layers`,
 `target_embedding`, `sites`, `basis`.
 **Provenance is metadata, not a gate.** The loader matches **tensor names, not hashes**, so an
 adapter fit against a sibling quantization of the same model still applies — which is a
 decision to surface to the operator, not a failure to hide. Compare `base_sha256` against the
 sha the endpoint's own fetcher pins; if they differ, say so in the PR body, the env header and
 the endpoint page, and prove the effect behaviourally instead.
 Two publisher facts that decide whether a fork can carry the file at all: the build it was
 verified on, and what it deliberately does NOT touch (an embedding rank is the usual crash —
 `token_embd` left alone is a graph constraint, not an omission).
 ## 3. Ask the runtime binary, not your memory
 ```bash
 <llama-server> --help | grep -iE "lora|adapter"
 ```
 Expect `--lora FNAME`, `--lora-scaled FNAME:SCALE,...`, `--lora-init-without-apply`
 (+ `POST /lora-adapters` for runtime scale). Prefer `--lora-scaled <file>:<scale>` as ONE
 argv token so a scale can never reach the engine without its file, and follow the endpoint's
 existing opt-out convention (the `MMPROJ_FILE=` shape: `:`-less default so an explicitly empty
 value means "off, on purpose"). Gate the deployer on the file's existence with the adapter's
 OWN fetcher named in the error text.
 ## 4. Prove the effect: refusal/behaviour probe, before AND after
 The probe is not a bench, so the no-bench law does not block it — and the **before** half must
 be captured while the old shape is still live.
 - Same prompts, `temperature` low, both before and after; classify with a refusal-marker regex
  and print only the opening characters, never the generated body.
 - **Budget ≥ 2 048 tokens on a thinking model.** A 600-token request can be swallowed whole by
  the reasoning channel: `content` comes back empty with `finish_reason: length` and
  `reasoning_content` full — which reads exactly like a refusal that never happened.
 - A leading `⚠️ Disclaimer`/hedge after the adapter is style, not the circuit: judge the marker
  sentence, not the tone.
 ## 5. Post-deploy reads (the ledger is the instrument)
 - Boot log shows `llama_adapter_lora_init_impl: loading lora adapter from '<file>'` and then
  **dumps the adapter's KV block** — the provenance mismatch is printed at every start, so the
  runbook should point at the journal instead of restating it.
 - Confirm the flag on argv: `tr '\0' ' ' < /proc/$(systemctl show <svc> -p MainPID --value)/cmdline`;
  confirm `systemctl show <svc> -p DropInPaths --value` is empty (a leftover bench drop-in outranks
  everything you just deployed).
 - Shape must be untouched by an adapter: `n_slots` / `n_ctx_slot` / KV lines unchanged, and
  `/metrics` still answering (a llama.cpp endpoint is invisible to Prometheus without `--metrics`).
 - Root units log to the journal; rootless podman storage is read WITHOUT sudo (`sudo podman
  inspect` sees a different storage namespace and reports "no such object").
 ## Yields
 One sentence per question: does the file exist and at what size/sha; which pack it declares as
 its base and whether that matches the served payload; which flag the runtime actually offers;
 what the before/after probe classified. Anything else is a decision for the operator, and the
 rollback should be one env line on a file the endpoint already loads.
@@ -0,0 +1,73 @@
 ---
 name: gitea-api-pr-operations
 description: "\"Open, list, merge, and diagnose issues/PRs on the Dankclaw Gitea API (192.168.0.143:3000, repo dank/command-center) with the token stored in ~/.config/secrets/gitea — incl. the required merge payload, where review comments actually live on 1.27.3, and how to recover the session id for the mandatory body footer.\""
 ---
 # Gitea API PR operations (Dankclaw `dank/command-center`)
 ## Where
 - Token: `~/.config/secrets/gitea` (`http://user:TOKEN@192.168.0.143` single line).
  Extract WITHOUT echoing:
  `tok=$(sed -nE 's#^http://[^:/@]+:([^@]+)@192\.168\.0\.143.*#\1#p' ~/.config/secrets/gitea | head -1)`
 - Build a 600-perm temp curl config and use `curl -K`:
  `cfg=$(mktemp) && chmod 600 "$cfg" && printf 'header = "Authorization: token %s"\n' "$tok" > "$cfg"`
  Delete `$cfg` after use. NEVER pass `-H "Authorization: token $tok"` (the literal
  header lands in transcript + logs). NEVER echo the token.
 - Base URL: `http://192.168.0.143:3000/api/v1/repos/dank/command-center`.
 ## Recipes (all verified live 2026-10-18)
 - **Open PR** (token only needed for private repos; this one reads publicly but
  POST needs auth): `POST /pulls` JSON `{title, head, base:"main", body}`.
 - **PATCH PR title/body**: `PATCH /pulls/<n>` with JSON body `{title}` and/or
  `{body}`. Returns 201 with the full PR. Use `jq -n --arg` to build JSON; for
  multi-line bodies write the text to a temp file and `--arg b "$(cat b.txt)"`.
  (jq CLI: a bare `---` argument after the program is parsed as a flag → error;
  fold footers into the --arg string instead.)
 - **List open PRs**: `GET /pulls?state=open` → `jq -r '.[] | "#\(.number) \(.head.ref) \(.title)"'`.
 - **Read PR**: `GET /pulls/<n>` (no token; public repo) → `jq -c '{state,merged,mergeable,head:.head.ref}'`.
  `mergeable:false` is often Gitea's *not-yet-checked* state, not a conflict — prove a real
  conflict locally with `git merge-tree --write-tree HEAD origin/main` before believing it.
 - **MERGE**: `POST /pulls/<n>/merge` with `-H 'Content-Type: application/json'`
  and body **`{"Do":"merge"}`** — this build REQUIRES the `Do` field:
  `{}` or `{"DoNotMerge":false,...}` → 422; `{"Do":"merge"}` → 200 +
  `{"state":"closed","merged":true,"merge_commit_sha":"..."}`. Verify with a plain
  GET /pulls/<n> afterwards (merge endpoint's own stdout may not parse).
  Merge is the `--no-ff` merge commit on main; then `git -C ~/.omp fetch && git
  merge --ff-only origin/main` propagates the live deployment.
 - **Issues**: same shape at `/issues` (`POST {title, body}`), `/issues/<n>/comments`
  (`POST {body}`, `PATCH .../comments/<id>`) — both work with the temp-cfg auth.
 ## Review comments: the API lies on 1.27.3 (learned 2026-10-18)
 - `GET /pulls/<n>/comments` (inline review comments) → **404 `not found` on every
  route** (token or not, `?pull_request_id=` or not) even when a review with
  comments exists.
 - `GET /pulls/<n>/reviews` works (shows `state`, `comments_count`) but bodies are empty.
 - **The comments are readable from the PR HTML**:
  `curl -sS http://192.168.0.143:3000/dank/command-center/pulls/<n> -o /tmp/pr.html`
  then extract `<div class="content comment-content">` blocks
  (python: `re.finditer(r'comment-content', src)` → widen ±800 chars, strip tags).
  Duplicates appear (suggested-change UI shows text twice); dedupe mentally.
 - Per-conversation resolve API also 404s — flag resolutions in an issue comment instead.
 ## Body-footer law (AGENTS.md)
 Every issue/PR body ends with `---` line then `cwd: <wd> · session: <id>`. Keep
 it inside the --arg string (not a `---` CLI arg).
 `cwd` is THIS session's own working directory (note a build worktree separately if they
 differ). When `/status` is unreachable (headless/subagent context), recover the session id
 from the session store instead of inventing one:
 `ls -t ~/.omp/agent/sessions/<cwd-slug>/ | head -2` → `<timestamp>_<uuid>` (the same uuid as
 `<uuid>.jsonl`); the slug is the cwd with `/` replaced by `-`. Subagent files live under the
 **parent** session's directory, so the newest entry there is the parent id.
 ## Gotchas
 - Content-Type: POSTs with `-d @file.json` MUST carry
  `-H 'Content-Type: application/json'` on the command line. `-H` entries put in
  the curl config file are ignored for this (header ordering quirk).
 - `xdg-open <pr-url>` lands the PR in Frank's Firefox the moment it is opened —
  law, not courtesy.
 - `jq: cannot index "not found" with "user"` = endpoint 404'd into an error
  object; check `-w '%{http_code}'` before blaming jq.
 - The token in `.git/config`'s remote URL is the same secret; the credential
  file (`~/.config/secrets/gitea`) is the one git actually consults (global
  credential.helper) and the one to reuse for API calls.
@@ -0,0 +1,75 @@
 ---
 name: gitea-merge-form-encoded
 description: "Use when a Gitea API merge on Dankclaw (192.168.0.143:3000) returns HTTP 422 \"[Do]: Required\" or 405 \"Please try again later\" — the merge endpoint needs form-encoded fields with the lowercase field name do, and a behind-main branch must be merged forward before it will merge."
 ---
 Gitea on Dankclaw (192.168.0.143:3000) — merge quirks, measured 2026-10-19 on `dank/serverAppConfigs` and again on `dank/dankvoice`, re-earned the same day on serverAppConfigs PR #27.
 ## 1. The payload: form-encoded, lowercase `do`
 Creating a PR accepts a JSON body. **Merging does not**: `POST /api/v1/repos/{owner}/{repo}/pulls/{n}/merge` with a JSON body (`{"merge_style":"no-ff", ...}`) or with those values as request headers returns `422 {"message":"[Do]: Required"}` — four variants of that all fail identically, so do not "fix" it by changing the style name or moving the headers around.
 **The field name is lowercase `do`.** `--data-urlencode 'Do=merge'` (capital D, which the error message spells) returns the same `422 [Do]: Required`. Do not retry with case variants — the web-UI form field is `do`.
 Working call (form-encoded):
 ```bash
 tok=$(sed -n 's|^https\{0,1\}://[^:]*:\([^@]*\)@192\.168\.0\.143.*$|\1|p' ~/.config/secrets/gitea | head -1)   # git credential.helper store file
 curl -sS -X POST -w 'http %{http_code}\n' -K <(printf 'header = "Authorization: token %s"\n' "$tok") \
  --data-urlencode 'do=merge' \
  --data-urlencode 'merge_style=no-ff' \
  http://192.168.0.143:3000/api/v1/repos/dank/<repo>/pulls/<N>/merge
 # 200 with an empty body == merged
 ```
 - `merge_style` values are the dashed names: `no-ff`, `merge`, `rebase`, `squash`.
 - Keep the token out of argv: `-K <(printf …)` feeds the `Authorization` header through stdin (a `-H "Authorization: token …"` lands in `/proc/<pid>/cmdline`, world-readable — the 2026-09-16 HF-token leak class).
 - Verify by fast-forwarding a checkout (`git fetch && git merge --ff-only origin/main`) rather than re-reading the PR.
 - Fleet law still applies: never merge without an explicit current OK from Frank, and open the PR URL in his browser (`xdg-open`) the moment it exists.
 ## 2. `405 {"message":"Please try again later"}` = the branch is behind main
 A correctly formed merge call returns **405**, not 422, when Gitea cannot test-merge the head into the base. Read it as "merge main forward", not "retry later" — no sleep-retry ever clears it.
 Confirm first: `GET /pulls/{n}` shows `"mergeable": false` (and `merged: false`, `state: open`) for exactly this state.
 The fix is the repo's own trunk-based law — merge forward, never rebase:
 ```bash
 git worktree add ../wt-prN -B prN <head-branch>
 cd ../wt-prN && git merge --no-edit origin/main      # resolve, see below
 ./tests/run.sh                                       # the seam is the arbiter, run it on the RESOLVED tree
 git push -q origin prN:refs/heads/<head-branch>      # same branch name; Gitea reuses the open PR
 # then re-POST the merge — 200 this time
 ```
 Notes earned on PR #27 (2026-10-19):
 - A `git worktree` per PR keeps the deployed checkout untouched; clean up with `git worktree remove --force ../wt-prN && git branch -D prN`.
 - `git status --short` during a merge lists every incoming file as staged — that is the merge commit's content, not a dirty tree.
 - Push a local branch to the PR's branch name with an explicit refspec (`prN:refs/heads/docs/…`); the push output prints `Visit the existing pull request`, which is how you confirm you hit the right head.
 - Gitea needs a few seconds after the push to recompute mergeability; a `sleep 3` before re-POSTing avoids a second 405.
 ## 3. Resolving vault conflicts against a compaction wave
 When main has run a docs compaction (page deletions, description shortening), two conflict shapes recur:
 - **`description:`** — `scripts/check-okf.py` enforces **DESC: ≤ 120 chars**. A branch's longer description must be shortened, not argued for; keep main's shape and fold the new topic into the wording.
 - **A `[[Page]]` link whose target page main destroyed** — `git ls-tree -r --name-only origin/main -- serverAppConfigs-docs | grep -i '<page>'` settles it. Drop the dead link; do not resurrect a page. Compaction left link-stripped stub bullets behind (`-  the compile fix for …`, dash + two spaces): `git grep -nE '^-  [A-Z]' origin/main -- 'serverAppConfigs-docs/**/*.md'` counts them, and the seam cannot see them because a stub is no longer a link to validate.
 After any frontmatter change, regenerate: `./scripts/gen-vault-index.py serverAppConfigs-docs` and commit the index rows — the `vault indices are generated, not hand-carried` seam diffs regeneration against the checkout. The sub-index sync can emit one extra space after `|` for a quoted description; commit what the generator emits, since the seam compares against the generator.
 ## Credential-store token extraction (same file, adjacent trap)
 `~/.config/secrets/gitea` holds one line shaped `http://user:token@192.168.0.143:3000`. Splitting it with `awk -F'/'` puts the host in `$3`, not `$2`, and `awk -F'/' '{print $NF}'` yields the host+path, not the token — an empty/garbage token makes **private repos answer `404 not found`** (Gitea hides them from anonymous), which reads like a wrong URL rather than an auth failure. Extract with:
 ```bash
 tok=$(sed -n 's|^https\{0,1\}://[^:]*:\([^@]*\)@192\.168\.0\.143.*$|\1|p' ~/.config/secrets/gitea | head -1)
 echo "token length: ${#tok}"   # 40 — print the length, never the value
 ```
 Other API quirks measured the same day:
 - `GET /pulls?state=open` can return an error object where `state=all` returns the list; `state=all` list entries may omit `head`/`base` — fetch `/pulls/{n}` for those.
 - POST `/pulls` for a head/base pair that already has a PR → `409` naming `issue_id: N`; the PR number is that `issue_id`, so PATCH it instead of POSTing again.
 - Issues and PRs share the issue index per repo, so `#36`-style numbers are repo-scoped: a footer fix aimed at `dank/command-center#36` 404s when pointed at `dank/dankvoice`.
@@ -0,0 +1,53 @@
 ---
 name: gitea-pr-api-cycle
 description: "\"Open/update/merge PRs and issues on the Dankclaw Gitea API (192.168.0.143:3000) with the token-safe sequence, the form-encoded merge field, the empty-token-returns-404 trap, and post-merge live-checkout fast-forward plus the plugin-package-name upgrade gotcha.\""
 ---
 # Gitea PR/issue cycle — Dankclaw API
 Friction-earned 2026-10-18 (PRs #15–#20, issue #18) and re-earned 2026-10-19 on `dank/dankvoice` PRs #4–#6: the merge payload claim below was wrong, and an empty token masqueraded as a missing repo.
 ## Where
 - API base: `http://192.168.0.143:3000/api/v1/repos/dank/<repo>/{pulls,issues}` — repo varies (`command-center`, `dankvoice`, `serverAppConfigs`); numbering is per-repo, so a footer citing `#36` means nothing without the repo.
 - Token: never inline, never in argv (`-H "Authorization: token …"` lands in `/proc/<pid>/cmdline`, world-readable). Extract into a 600-perm curl config and hand it to curl with `-K`:
  ```bash
  tok=$(sed -nE 's#^https?://[^:/@]+:([^@]+)@192\.168\.0\.143.*#\1#p' ~/.config/secrets/gitea | head -1)
  [ "${#tok}" -ge 40 ] || { echo "token extraction failed"; exit 1; }
  cfg=$(mktemp); chmod 600 "$cfg"; printf 'header = "Authorization: token %s"\n' "$tok" > "$cfg"
  curl -sS -K "$cfg" … ; shred -u "$cfg"
  ```
 - **Empty token answers `404 {"message":"not found"}`, NOT 401** — Gitea hides the private repo. A 404 on a path you have used before means auth, not a typo'd repo. The trap that produces the empty token: `awk -F'/' … '{print $NF}'` on the store line (`scheme://user:token@host/`) — the host is in `$3`, the match never fires, you get a silent empty variable. Always assert the length before POSTing.
 - Multi-line bodies: build JSON in python (`json.dumps({"title":…, "body":open(f).read(),…})`) or `jq -n --arg b "$(cat b.txt)"`. NEVER pass `---` as a bare jq argument (parsed as a flag). Escaped quotes inside `python3 -c '…'` break on `\"` — write the script to a file or use a heredoc.
 - Always capture status: `-o r.json -w '%{http_code}'`; a bare `-o` hides failures.
 ## Create
 `POST /pulls` with `{title, body, base:"main", head:<branch>}` — JSON is accepted here (unlike merge).
 - **409 `pull request already exists for these targets [issue_id: N, …]`** — a PR for that head/base exists already. Common cause: the push message printed `/pulls/new/<branch>` and someone (Frank, or an `xdg-open` you ran) clicked Create. `GET /pulls?state=all`, find it, then `PATCH /pulls/N` with your title+body instead of re-posting.
 - `GET /pulls?state=all` on this Gitea omits `head`/`base` per entry — read `/pulls/N` for those, or key off `number`/`user`.
 - Issues: same shape, `POST /issues` `{title, body}`; `PATCH /issues/N` fixes a body retroactively (works for PRs too, since a PR is an issue).
 ## Merge (the 422 trap) — corrected
 `POST /pulls/N/merge` needs **form-encoded** fields; the merge form field name is lowercase **`do`**:
 ```bash
 curl -sS -X POST -K "$cfg" \
  --data-urlencode 'do=merge' --data-urlencode 'merge_style=no-ff' \
  http://192.168.0.143:3000/api/v1/repos/dank/<repo>/pulls/N/merge
 ```
 JSON `{"Do":"merge"}` (what this skill used to claim) and header variants all return `422 {"message":"[Do]: Required"}`. `merge_style` ∈ `no-ff|merge|rebase|squash`. Success returns **200 with an empty body**; verify by landing a checkout rather than re-reading the PR. Merge only with Frank's explicit per-PR OK.
 ## Post-merge landing
 - Command-center: the checkout IS the deployment — `git -C ~/.omp fetch -q origin && git -C ~/.omp merge --ff-only origin/main`.
 - Package repos (`~/Projects/<pkg>`): same `--ff-only`, then reinstall (`omp plugin upgrade <name>`) and `cmp` the installed `dist/index.js` against the repo `dist/index.js` to prove the live artifact is the merged one. Check `ls -ld node_modules` after landing anything that touched it.
 - **`omp plugin upgrade` takes the npm package name, not the short name.** `omp plugin upgrade dankvoice` fails with `Failed to upgrade dankvoice: dankvoice is not installed` while the plugin is plainly installed; the package is `omp-dankvoice`. Find the truth with `ls ~/.omp/plugins/node_modules` or `find ~/.omp -path '*<name>/dist/index.js' -not -path '*/Projects/*'` — the installed tree is unscoped (`~/.omp/plugins/node_modules/omp-dankvoice/dist/index.js`), not `@dank/dankvoice`.
 - **`cmp` exiting 1 BEFORE the upgrade is the expected state** (installed bundle is the pre-merge build, diff reported at some char/line). Do not treat it as a failed deploy and do not "fix" the build; run the upgrade, then `cmp` again for byte identity, and grep the new bundle for a string only the merged code contains (e.g. `grep -c "Heckle instead of summarizing"`) as a second, semantic confirmation.
 - Prune: `git worktree remove --force <path>` (force: untracked deps link), `git branch -D`, `git push origin --delete <branch>` (allowed: local Gitea).
 ## Attribution footer (AGENTS.md)
 Every issue/PR body ends with `---`, then `cwd: <session cwd> · session: <session id>`. Read the real values, never invent an id.
 - **The session id is the UUID suffix of the LIVE transcript `.jsonl`, not the session directory name.** Transcript dirs are keyed by cwd (e.g. `-.omp-wt-wt-20261019-020309-6d1fc1f`) and ONE cwd can hold several sessions (resume / continuation forks), so `ls -t ~/.omp/agent/sessions/` cannot tell you which is yours and `ls -t <dir>` is equally blind. Pick the file being appended to right now: `ls -l --time-style=+%H:%M:%S <dir>/*.jsonl` beside `date +%H:%M:%S` — the mtime that equals the current second is the live session. The id is the part after `_` in `<timestamp>_<uuid>.jsonl`.
 - A `history.db` query for `session_id` filtered by `cwd` usually agrees, but it is not authoritative for WHICH of several sessions in that cwd is live — use the jsonl mtime test.
 - `local/` does NOT disambiguate: a forked transcript dir carries copies of the same `local://` artifacts, so matching artifact names proves nothing about which session is live.
 - `cwd` is that session's own working directory (the path the harness states), **not** the build worktree you committed in — when they differ, name the build worktree inside the body and keep `cwd` the session's.
 - Resolve `local://<name>.md` with `read local://<name>.md` (its header prints the absolute path) instead of guessing the directory.
@@ -0,0 +1,42 @@
 ---
 name: gitea-review-comment-html-scrape
 description: "Read inline review comments on the Dankclaw Gitea when pulls/N/comments 404s (Gitea 1.27.3): scrape comment-content blocks and diff anchors from the PR HTML page"
 ---
 # Gitea review-comment extraction when the API 404s
 On the Dankclaw Gitea (192.168.0.143:3000, Gitea 1.27.3) the review-comment API is dead for inline comments:
 `/api/v1/repos/{owner}/{repo}/pulls/{N}/comments` returns 404 `not found` **even with a valid token**, and `pulls/comments?pull_id=` / `?pull_request_id=` variants 404 too. `/pulls/{N}/reviews` works but its bodies are empty for inline reviews (read `comments_count` for how many exist); `/issues/{N}/comments` shows only conversation comments, never inline ones.
 ## Procedure
 1. Confirm the review exists and how many inline comments it holds:
   `curl -sS http://192.168.0.143:3000/api/v1/repos/dank/command-center/pulls/{N}/reviews | jq -c '.[] | {id, state, comments_count}'`
 2. Scrape the PR page instead (no token needed for a public repo):
   `curl -sS http://192.168.0.143:3000/dank/command-center/pulls/{N} -o /tmp/pr.html`
 3. Extract each comment's text — every inline comment renders a `comment-content` block; dedupe (each comment appears twice in the HTML):
 ```python
 import re, html
 src = open('/tmp/pr.html').read()
 seen = set()
 for m in re.finditer(r'comment-content', src):
    t = html.unescape(re.sub(r'<[^>]+>', ' ', src[m.start()-100:m.start()+800]))
    t = re.sub(r'\s+', ' ', t).strip()[:400]
    if t not in seen:
        seen.add(t); print('>>', t)
 ```
 The comment text appears twice back-to-back inside each block ("text text") — read it once. Blocks start after `Copy Link|Copy Source`; ignore those chrome words.
 4. **Locate the file/line anchor** (comment-content blocks carry no `data-path`/`data-line` attrs on this build): search the raw HTML for the comment string, walk *backward* ~4–7 KB, strip tags; the nearby `agent/...` path, `@@ -a,b +c,d @@` hunk header, and surrounding diff context lines identify the anchored file and the quoted source line.
 ## Replying / housekeeping
 - Per-conversation resolve API does not exist on this build (404s) — reply to the round as a normal issue comment (`POST /repos/{o}/{r}/issues/{N}/comments`, token via `curl -K` temp cfg, `header = "Authorization: token …"`, 600 perms, `jq -n --arg b "$(cat b.txt)" '{body:$b}'`) listing which note got which fix commit.
 - Edit a posted comment: `PATCH /repos/{o}/{r}/issues/{N}/comments/{id}` with `{"body": ...}` — use to fix your own typos rather than double-posting.
 - Token source on this box: `~/.config/secrets/gitea` (grep the remote-URL pattern); never echo it.
 ## Why this works
 The PR page is server-rendered with full inline comment bodies; Gitea's "Copy Source" UI element guarantees the raw text is present pre-markdown-render.
@@ -0,0 +1,30 @@
 ---
 name: gitea-token-from-http-credential-store
 description: "Extract the Dankclaw Gitea token from ~/.config/secrets/gitea for API calls to PRIVATE repos, and diagnose the empty-token 404 that looks like a missing repo."
 ---
 The Gitea credential store line on Frank's boxes is **http** (not https) with a percent-encoded port:
 ```
 http://dank:<40-char-token>@192.168.0.143%3a3000
 ```
 ## Extraction that actually works
 ```bash
 tok=$(sed -nE 's#^[a-z]+://[^:]+:([^@]+)@.*#\1#p' ~/.config/secrets/gitea | head -1)
 curl -s -H "Authorization: token $tok" http://192.168.0.143:3000/api/v1/<path>
 ```
 Common wrong pattern (silent failure): an `awk`/`grep` anchored on `https://` or on `@192.168.0.143:` matches nothing, leaving `tok=""` — verify with `echo "tok len ${#tok}"` before believing any API result.
 ## The 404 trap
 `dank/command-center` is **public**: an empty token still returns real issue data. `dank/dankvoice` is **private**: the same empty token returns `404` on `/api/v1/repos/<owner>/<repo>` and `{}`-shaped bodies (`title: undefined`) on issues. A 404 with a zero-length token is an auth problem, NOT a missing repo — confirm by printing the token length first, then re-check.
 ## Other notes
 - `git credential fill` fails headless here (`could not read Username … terminal prompts disabled`); read the store file directly instead.
 - Never print the token: mask when inspecting the file —
  `sed -E 's#(://[^:]+:)[^@]+@#\1REDACTED@#' ~/.config/secrets/gitea`
 - Issue/PR numbers are **per repo**: `dank/dankvoice` #8–#11 (refactor, hardening, AbortError fix, menu defects) are unrelated to `dank/command-center` #8–#11 (SDLC, trunk-law). Read the body from the repo the work targets before referencing an issue in a commit message.
@@ -0,0 +1,23 @@
 ---
 name: gitflow-back-merge-plumbing
 description: "(HISTORICAL for dank/command-center — switched to trunk-based 2026-10-18, no develop branch.) Back-merge main into develop with pure git plumbing when branch checkout is policy-blocked; avoids the polluted-base evil-merge trap."
 ---
 # Git-flow back-merge via plumbing (checkout blocked)
 ## Applicability
 The command-center repo retired `develop` on 2026-10-18 (trunk-based; see its AGENTS.md § Trunk-based SDLC). Use this only in repos still running git-flow where a `main -> develop` back-merge must land and branch checkout is forbidden. Never merge while HEAD is a session branch — the merge silently lands on it.
 ## Procedure
 1. `git fetch origin` and verify with `git ls-remote --heads`.
 2. Find the CLEAN fork point: `mb=$(git merge-base origin/develop origin/main)`. NEVER build the merge commit with a develop-side that already contains main (e.g. a previous broken merge): merge-base then equals main, main-side looks "unchanged", and stale develop content wins everywhere — a clean rc=0 evil merge. Sanity-trigger: if a merge you expect to conflict resolves rc=0, suspect the base.
 3. Real merge, no worktree: `out=$(git merge-tree --write-tree <clean-dev-tip> origin/main); rc=$?; tree=$(echo "$out"|head -1)`. rc=1 = conflicts; list them from the "Conflicted file info" section (lines starting with a 6-digit mode), NOT from `ls-files -u` in some other worktree.
 4. Resolve in index only: `export GIT_INDEX_FILE=/tmp/idx.$$; git read-tree $tree; git update-index --add --cacheinfo 100644,$(git rev-parse origin/main:<path>),<path>` per conflicted path (pick a side deliberately — say which in the message).
 5. `final=$(git write-tree)`; prove no markers: `git grep -l '^<<<<<<<' "$final"` must be empty (run it correctly — an empty count from a malformed invocation hides markers).
 6. `commit=$(git commit-tree "$final" -p <clean-dev-tip> -p origin/main -m "...")`; `git push --force-with-lease=develop:<current-dev-tip> origin "$commit:develop"` (lease prevents clobbering concurrent pushes; document superseded commits). A back-merge onto an untouched develop is additive — plain push, no lease needed.
 7. Verify ALL of: `git merge-base --is-ancestor origin/main origin/develop`; grep a distinctive merged value in `origin/develop:<file>` (content, not just ancestry); `git diff --stat origin/main origin/develop` matches expectations.
 ## Traps
 - `merge-tree` writes conflict markers INTO the tree for conflicted paths — always overwrite every conflicted path before commit-tree.
 - A wrong tree pushed as a merge commit makes every later merge against it resolve "cleanly" to stale content; fix by rebuilding from the clean fork point and force-with-lease, citing the broken commits in the message.
 - Gitea PR merge API needs `Content-Type: application/json` AND `{"Do":"merge"}` in the BODY (query param alone 422s); a 405 "Please try again later" right after the base branch moved is transient mergeability recomputation — wait a few seconds and retry.
@@ -0,0 +1,41 @@
 ---
 name: gitignore-trailing-slash-symlink-contamination
 description: "Trailing-slash gitignore rules don't match symlinks, so worktree dependency symlinks get committed; detect with git ls-tree mode 120000, fix with git rm --cached."
 ---
 A `.gitignore` entry written with a **trailing slash matches directories only**. A symlink of the same name is not a directory, so it slips past the rule, and `git add -A` in a `git worktree` checkout silently **tracks** it. Cost measured 2026-10-19: a machine-specific symlink (`node_modules -> /home/blank/Projects/dankvoice/node_modules`) landed in `main` with a merged PR.
 Why worktrees are the trigger: a worktree has no `node_modules` (or other installed-deps dir) of its own, so the cheap way to make build/test work there is a symlink into the primary checkout. With `node_modules/` ignored, nothing complains.
 ## Detect
 ```bash
 git ls-tree HEAD -- node_modules          # mode 120000 == tracked symlink
 git ls-files -s | awk '$1==120000'        # every tracked symlink in the index
 ```
 ## Fix (branch, never on main directly)
 ```bash
 git rm -q --cached node_modules           # untrack; leaves the file on disk
 ```
 plus relax the ignore rule to the slash-free form, with the reason inline so nobody re-adds the slash:
 ```
 # Trailing slash would only match directories: a node_modules symlink (the
 # shape `git worktree` checkouts end up with) slips past it and gets tracked.
 node_modules
 ```
 Then `git check-ignore -v node_modules` must print the rule, and the suite runs after (the symlink still resolves, it is just ignored).
 ## Prevent
 In a fresh worktree, create the deps symlink **after** confirming the ignore rule has no trailing slash:
 ```bash
 git check-ignore -v node_modules || sed -i 's|^node_modules/$|node_modules|' .gitignore
 ```
 Same class for any ignored-by-convention dir that a worktree might provide as a link: `node_modules`, `vendor`, `.venv`, `target`, `dist` when built artifacts are ignored.
@@ -0,0 +1,62 @@
 ---
 name: gluetun-dependent-boot-race-recovery
 description: "Diagnose the Dankclaw pattern where gluetun is active but its netns-sharing dependents (searxng, marreta, marreta-browser) are inactive (dead) with \"Dependency failed\" after a reboot — cascade-recover them and tie it to e2e 502/SSO failures."
 ---
 # Gluetun boot-race: netns dependents dead at boot, service is active
 ## Signature
 After a dankclaw reboot, `gluetun.service` is ACTIVE, yet e2e fails on
 `search.franksdank.cloud` (502 on the authenticated pass), the Marreta tile
 shows a blank interstitial, and the homepage crawl reports vhost resets.
 `systemctl --user status <dep> --no-pager` shows:
 ```
 Active: inactive (dead)
 <host> systemd[2224]: Dependency failed for <dep>.service
 <host> systemd[2224]: <dep>.service: Job ... failed with result 'dependency'
 ```
 ## Cause
 Quadlet `Network=gluetun.container` emits `Requires=`/`After=` on
 `gluetun.service`. When gluetun's start job fails once transiently at boot
 and `Restart=` re-arms it seconds later, the dependents' start jobs are
 already consumed and are NEVER re-armed — they sit `inactive (dead)`
 indefinitely while gluetun runs. `Restart=always` on the dependent does not
 help: the service never ran, so the restart policy never armed.
 ## Diagnosis census (rootless, run as `dank`, NO sudo)
 ```
 export XDG_RUNTIME_DIR=/run/user/$(id -u)
 uptime   # reboot is the trigger
 systemctl --user is-active gluetun searxng searxng-valkey marreta marreta-browser
 systemctl --user status <dep> --no-pager | head  # "Dependency failed" line
 journalctl --user --since "<boot>" | grep -iE "<dep>|dependency"
 ```
 Dependents of the gluetun netns on dankclaw: `searxng`, `marreta`,
 `marreta-browser` (valkey is plain-networked and survives).
 ## Recovery (order matters: browser before marreta)
 ```
 systemctl --user start marreta-browser marreta
 systemctl --user start searxng
 ```
 Verify: `podman ps` shows them; `curl http://127.0.0.1:8081/healthz` (searxng)
 and gluetun-published 8082 (marreta) answer; then rerun the Playwright gate
 (`tests/e2e/run.sh`) — the 12-crawl / 13-sso / 16-marreta specs are the trip
 wires for this fault.
 ## Distinguish from the dead-pause-process failure
 The 2026-09-16 rootless-pause-process death breaks ALL podman commands and
 every quadlet loops; this fault leaves podman fully functional and only the
 gluetun-dependency chain is dead. The reboot repairs the former; manual
 cascade-start repairs this one.
 ## Open gap (dankclaw, as of 2026-10-15)
 The race recurred (observed 2026-10-15 boot 01:41). Quadlet law for these
 units has no cure inside the `.container` files themselves; options are a
 systemd user-level drop-in on gluetun
 (`ExecStartPost=/usr/bin/systemctl --user restart searxng marreta`) or
 converting the dependents' dependency to `BindsTo` + `StartLimit` retry
 semantics. Fleet precedent for boot-order pain: searxng/gluetun ordering,
 observability reboot gaps (AGENTS.md).
@@ -0,0 +1,14 @@
 ---
 name: halogen-ctx-pool-resize
 description: "Resize a halogen flash-server endpoint's context/KV pool (frank-dragoon pattern): engine knobs, seam band, RAM ledger, re-key sweep, deploy + probe."
 ---
 Two knobs: HALOGEN_CTX (hard per-request ceiling; longer prompt = 400 naming the limit, never truncation) and HALOGEN_KV_POOL_POSITIONS (ONE pool shared behind HALOGEN_KV_SLOTS). Ceiling raises buy a longer conversation; pool raises buy concurrency.
 Laws: native window 262,144, beyond it needs HALOGEN_ROPE_YARN (engine 400 text) so never extrapolate for sizing; seam band ctx <= pool <= slots*ctx (pool == slots*ctx => two maximum-length requests coexist, pool == ctx => one fills it); harness contextWindow = ceiling - 45056 (clamp max_tokens = min(maxTokens, window-est-4096), compaction at 85 %, chars/4 under-counts ~3 %) and pool-only changes do NOT move it; ~28 KiB/position measured (200,704 -> 5.5 GiB, 262,144 -> 7.2, 524,288 -> 14.6), quote the ledger reservation not the preflight formula (block scratch + ~115 MiB/slot); the 51.2 GB n-gram table is mmap page cache (Pin::None) so RAM the pool takes is RAM that table loses, re-measure the warm prompt-cache ratio (136x baseline) after a raise; engine ledger vs 121.2 GiB = weights 62.9 + KV + working (3.8 + 8.4*MAX_TOK/16384) + prompt cache + HALOGEN_HOST_RESERVE_GIB=20 + co-tenancy ~10-15.
 Procedure: read scripts/frank-dragoon.env and the boot ledger in /home/dank/logs/frank_dragoon.log (not the journal; a printed clamp is the referee); candidate boot via a transient FRANK_DRAGOON_ENV_FILE drop-in sourcing the repo env (never a scratch port), then trash it and prove DropInPaths empty or the repo env silently does not govern; edit env assignment + SHAPE lore and the unit Description; update the seam good_env fixture, -e pass-through asserts and pool-law comment without loosening the band; re-key every quote (deploy-remote.sh service comment, AGENTS.md topology row/engine laws/memory ledger/runbook index, docs index and LLM/index prose and mermaid node text, endpoint runbook shape paragraph plus a dated section, forward pointers in other vault pages, ~/.omp/agent/models.yml comment and contextWindow only if the ceiling moved, live OpenWebUI row in webui.db after backup); ./tests/run.sh; commit explicit paths never -A (subagents share the tree); ./scripts/deploy.sh dankclaw --service frank-dragoon (bare target = fleet drain); verify the new boot ledger and append the ledger table to the runbook plus a log.md worklog entry.
 Probes: over-ceiling request -> 400 naming the ceiling in <1 s (preflight rejects before prefill); ~120k admission at max_tokens 45056 accepted, wall time = cold prefill ~1,500 t/s; two maximum-length admissions fired together must BOTH be admitted once pool >= 2*ctx; never report the first request after a boot.
 Traps: systemctl mask fails on relinked units, disable forbidden; reservation is prompt + max_tokens so an over-budget request fails preflight even with a free pool; HALOGEN_FLASH_PIN_TRUNK=0 rejected by the v2 loader; rollback = revert the commit and redeploy.
@@ -0,0 +1,48 @@
 ---
 name: halogen-npu-feasibility-census
 description: "Census whether halogen-flash-server's NPU small-model path can run on a Strix Halo host: image gate, amdxdna/XRT presence, IOMMU and fabric-clock blockers, enablement deltas."
 ---
 Use when asked whether halogen/halogen-flash-server can use the XDNA2 NPU (embeddings, rerank, moderation/guard, decider, `qwen3.5-2b` generation, `flux2-klein-4b` images, `qwen3-asr-*`) on a Ryzen AI Max / Strix Halo host, or before proposing to enable it.
 ## What the feature is (not a speed knob)
 The Flash trunk stays on the iGPU. `HALOGEN_NPU_MODELS=<names>` starts a second engine in the SAME container and on the SAME API port; the request's `model` field picks the executor. Unset → server identical to before. Each NPU model is a precompiled AIE-ML program (`devices/devices.hnpm`, per-partition `devices/u<N>.elf`, `devices/consts.hnpb`, `<id>.hnpw` weights, `tokenizer/tokenizer.json`), loaded via the HOST's XRT → kernel `amdxdna` → `/dev/accel/accel0`. One pass at a time; `HALOGEN_NPU_QUEUE` 64, overflow queues server-side, then `503 engine_busy`. Entry `entrypoint.sh` validates every file's bytes + sha256 against `/opt/halogen/npu/models.txt` before anything starts. NPU models run only in single-container "all" mode, NOT the `engine`/`api` split.
 ## Census (all read-only, run from the operator box)
 ```bash
 ssh <host> '
 # 1. engine gate + catalog in the pinned image
 podman exec <ctr> bash -c "grep -rlo HALOGEN_NPU_MODELS /opt/halogen /usr/local/bin /entrypoint.sh 2>/dev/null | head"
 podman exec <ctr> cat /opt/halogen/npu/models.txt | head -40
 # 2. is NPU actually wired today? (expect NO env, NO device, NO /dev/accel inside)
 podman inspect <ctr> --format "{{json .HostConfig.Devices}}"; podman exec <ctr> ls /dev/accel
 # 3. kernel driver + firmware
 lsmod | grep -i amdxdna; sudo dmesg | grep -iE "xdna|npu" | tail -5; ls -l /dev/accel
 # 4. XRT (distro packages are fine; vendor mounts /opt/xilinx/xrt)
 dpkg -l | grep -iE "xrt|xdna"; ls /usr/lib/x86_64-linux-gnu/libxrt* /usr/lib/libxrt* 2>/dev/null
 # 5. BLOCKER 1: IOMMU
 cat /proc/cmdline; ls /sys/kernel/iommu_groups | wc -l
 # 6. BLOCKER 2: fabric clock held?
 for c in /sys/class/drm/card*/device; do echo "== $c"; cat $c/power_dpm_force_performance_level 2>&1; cat $c/pp_dpm_fclk 2>&1 | tr "\n" " "; echo; done'
 ```
 Docs (raw fetch, authoritative): `docs/NPU.md`, `docs/npu-small-models.md`, `deploy/host/halogen-fabric-clock` under `peonist-ai/halogen-flash-server` on GitHub. Tag list: `podman search --list-tags ghcr.io/peonist-ai/halogen-flash-server`.
 ## The two blockers and the enablement delta
 - **IOMMU must be on.** `amd_iommu=off` turns the NPU off (no PASID/SVA); `iommu=pt` keeps it. Needs a grub edit + reboot. `iommu_groups == 0` ⇒ off.
 - **Fabric clock must be pinned at the top `pp_dpm_fclk` level** (or `power_dpm_force_performance_level=high`); `auto` = unheld. GPU+NPU concurrently HANG Strix Halo machines and corrupt NPU results while that clock moves. Fix: root container with `-v /sys:/host/sys` (server holds it itself), or install `deploy/host/halogen-fabric-clock` + unit (~1 W). If it can't hold, the server FAILS CLOSED and prints the commands.
 - Container delta: `--device /dev/accel/accel0` + `HALOGEN_NPU_MODELS`; `--ulimit memlock=-1:-1` and `--group-add keep-groups` usually already present. Distro XRT: mount each of `libxrt_coreutil.so.2`, `libxrt_core.so.2`, `libxrt_driver_xdna.so.2` TWICE (once at `/opt/xilinx/xrt/lib/`, once at its own path) — never mount an `/opt/xilinx/xrt` holding only symlinks.
 ## Costs to price before proposing
 - Upstream A/B: IOMMU translation ON costs **13–16 % prefill** (460 → 385 tok/s at 2,048 tokens, Ryzen AI Max+ 395); decode unaffected. Whether `iommu=pt` specifically costs that on a given box is a local measurement, not a published fact — run the image's own `sweep` after the reboot.
 - A few GB host RAM per NPU model (+8 GB FLUX, +1.6/4 GB ASR), and trunk decode drops while the NPU works (shared bus + power).
 ## Laws / traps
 - Never probe the NPU beside the live service: stop + mask first (fleet benchmarking policy); this host class has a precedent of a concurrent GPU experiment needing a power cycle. Distinguish off vs wedged with `ip neigh show <ip>` from a peer.
 - `/dev/accel/accel0` existing and `amdxdna` probing cleanly does NOT mean the NPU works — with IOMMU off the failure is at context/PASID creation, not at the device node. Do not trust older notes claiming the node itself is missing.
 - `dmesg` lines like `Failed to alloc dev bo memory, ret -28` while large NPU models take turns at NPU memory are benign (vendor-documented); the server recovers.
@@ -0,0 +1,48 @@
 ---
 name: html-report-ground-truth-audit
 description: "Audit a self-generated HTML report: ground every numeric/code/diagram claim against the repo, fix, and prove structure + render"
 ---
 Use after generating a large HTML report (e.g. via `repo-change-html-report`) whose claims were partly reconstructed from session memory. Fabricated numbers, invented code blocks, and silently-swallowed sections are the failure modes; the audit makes each traceable to the repo, a live command, or a recorded run.
 ## Procedure
 ### 1. Enumerate every checkable claim
 Grep the report for numerics, file paths, symbol names, and code blocks:
 - line counts (`wc -l` the real file)
 - test counts (`grep -c '@test' tests/<f>.bats` — NOT suite-run totals: conditional skips make raw counts differ; run-observed totals are legitimate run history, keep them labeled as such)
 - diff stats (`git diff --shortstat main..HEAD` — the footer's files/insertions/deletions)
 - commit hashes (`git log --oneline`)
 - "verbatim" code blocks (see 3)
 - diagram node lists and captions (see 4)
 ### 2. Ground numeric claims with one command each
 Fix every mismatch in place. Record the was/now pair — the audit table IS the evidence.
 ### 3. Verbatim code blocks: prove them
 For a block labeled verbatim, the exact string must exist:
 - live code: `grep -n '<distinctive line>' <file>`
 - historical: `git show <sha> -- <file> | grep -E '^[+-].*(<token1>|<token2>)'`
 If the block was fabricated (plausible-looking pseudo-code), replace it with the real excerpt. If condensed, the block header must say "condensed" and every shown line must be real.
 ### 4. Diagram claims: run the engine
 Behavioral diagrams (plan traces, closure graphs) must be re-derived by running the actual CLI:
 `python3 scripts/service-map.py plan --host <h> <path>` — then edit node labels, captions, and the prose count ("four services") to match output. Cross-check derived-set diagrams against the source relation (e.g. `grep -rl 'Network=gluetun.container' */**/*.container` for who rides a tunnel).
 ### 5. Check for swallowed sections
 Large prior-session PUT ranges silently overwrite neighbors. Grep for headings/captions the plan promised; re-insert any that vanished, anchored on a fresh `read` of the region.
 ### 6. Structural balance
 Python tag-balance pass over the file:
 - per-tag open/close counts (`div`, `pre`, `figure`, `svg`, `table`, `span`, `figcaption`)
 - running-div-depth scan printing per-section balance to localize stray closers
 Common defect: `.ln`/`.nt` pair emitted without its `.cg` wrapper → stray `</div>`; fix by opening `<div class="cg">` before the pair.
 ### 7. Render proof
 `file://` is blocked on the shared browser — serve the dir: `bash` service `python3 -m http.server <port> --bind 127.0.0.1 --directory <dir>`, ready on that port. Then:
 - `browser.open({name, url: 'http://127.0.0.1:<port>/<file>'})`
 - DOM assertions via `tab.evaluate(() => …)` — NOT `tab.run` (that runs in Bun; no `document`). Sections are `<h2 id>` + siblings: scope queries to `document.body`/`document.querySelectorAll`, not `#ch5 …`.
 - screenshot the repaired regions (scroll via `tab.evaluate(el.scrollIntoView())`), then `tab.close()` and kill the server proc (`write proc://<name>/kill`).
 ## Deliver
 A was/now table of every fix with its ground command, plus the list of claims verified intact. State honestly which numbers are run-history and not recomputable.
@@ -0,0 +1,26 @@
 ---
 name: judge-empty-content-parse-repair
 description: "Diagnose and repair LLM-judge \"unparseable verdict\" storms: judge-fail rows store no raw → reproduce live on the failing instance; root causes include empty model response (runaway reasoning chains, finish=length + content:\"\") and judge prose-form verdicts when JSON scaffold breaks; fix parser fallback + prove via restart rejudge."
 ---
 Use when LLM-judge grades show an elevated "unparseable verdict" rate (baseline ~1%; storm = ≥5-10%).
 ## Law
 Judge rows with `ok:false` store NO raw judge output (meta empty) — you are blind in the ledger. NEVER guess the cause from the ledger alone; reproduce the exact failing instance live.
 ## Procedure
 1. **Census the rate**: filter ledger grade rows since a timestamp; rate = bad/total. Compare against the eval's baseline (≈1%). HLE with a 180B bare-JSON judge showed 11.8%.
 2. **Pull the failing instance**: pick the newest failing grade row; get its `instance` id and the latest `gen` row for that instance (latest-wins; ledger is append-only).
 3. **Reproduce live**: one-shot `bun -` (or equivalent) script: load registry host by judge name, call the judge function with that instance's exact question/answer/response, print `raw` head+tail. Judge raw text is ground truth.
 4. **Root-cause A — empty model response**: if `resp_len: 0`, the judge is fine; the MODEL produced no answer content. Census gens: `text` empty + `finish=length` + `completion_tokens == max_tokens` ⇒ **runaway reasoning chain**: the model wrote the whole budget into `reasoning` and never emitted `content`. Loop proof: 60-char block Counter over the reasoning tail (49 identical blocks = degeneration, e.g. `w4 w? w4 w?…`).
 5. **Root-cause B — prose verdict**: judges (esp. bare-JSON 180B class) drop the JSON scaffold when judging degenerate inputs (empty response) and emit plain `correct: no\nconfidence: 100`. Parser knowing only quoted `"correct": "no"` forms reports null = "unparseable" while the verdict is perfectly valid. Fix = add prose fallback regex `(?:^|\n)\s*correct\s*:\s*(yes|no)\b` after the JSON/quoted attempts, never before (JSON must win).
 6. **Baseline comparison before blaming the engine change**: for any model-behavior rate (runaway %, empty-answer %), census the previous (voided/`.AGENTTRASH/`) ledger the same way. Pre/post identical (18.5% vs 18.0%) ⇒ pre-existing model behavior, not the quantization/config under investigation. This keeps causal claims honest.
 7. **Verify the fix live**: restart the supervisor (poison law); pending `ok:false` grade rows re-grade on resume — the previously-blind rows flipping to real `fail` verdicts in the log is the proof.
 ## Empty-content scoring law
 Runaway-chain empties score 0 honestly (AA-style truncating harness). Keep the score, publish the runaway census beside every number. Sampling changes (repetition_penalty, num_predict cap) deviate from AA posture and void+restart the eval — user decision, not an assistant fix.
 ## Pitfalls
 - `podman logs 2>/dev/null`-style stderr discards make failure rows text-empty — check the capture path before inventing model-side causes (sandbox.ts fixed to `2>&1`).
 - `export RID=...` for python heredocs (plain `RID=` is invisible to `os.environ`).
 - Never `cd x && setsid ... & disown` expecting the cd to persist: `&` backgrounds the whole compound; foreground cwd is unchanged.
@@ -0,0 +1,62 @@
 ---
 name: kernel-flag-claim-audit
 description: "Audit a kernel/boot-parameter performance claim before it justifies a host decision (census feature presence, read the patch series verbatim, then publish the corrected plan to a Gitea issue without leaking the token)."
 ---
 Use when a decision rests on a kernel/boot-line performance claim (`iommu=off` vs `pt`, a module param, a new engine flag) and the question is "does an upstream change retire this trade?", or when the answer must land as a Gitea issue comment.
 ## 1. Census before theory (read-only, no reboot)
 ```bash
 uname -r; cat /proc/cmdline
 grep -c . /dev/null; ls /sys/kernel/iommu_groups | wc -l        # or the relevant sysfs knob
 nm -b /boot/System.map-$(uname -r) 2>/dev/null | grep -i <feature_symbol> | head
 apt-cache policy <meta-packages>                                  # what the distro can actually install
 grep -E 'CONFIG_(...)' /boot/config-$(uname -r)
 ls -l /dev/<device>; id -nG                                      # container-access question
 ```
 - Symbol absence in `System.map` + archive pinning = the claim is **not actionable today**, regardless of merge status. Say that plainly.
 - Answer the container/device question from node mode + group membership; it never needs a reboot.
 ## 2. Primary source beats press
 Read the **patch series itself** (cover letter + the implementation patch), not the news write-up. The press number is a symptom; the patch text carries the *preconditions* that decide applicability.
 Rules that only surface in the patch text (2026-10-18 AMD PerfOpt case):
 - enable path "rehomes devices **already on the identity domain**" → the feature is a companion to `iommu=pt`, never an alternative;
 - the enable path *disables* ATS/PRI/PASID/GCR3 (`skip_caps` in `attach_device`) → identity mode still pays a 1:1 page walk until this arms; a passthrough boot is therefore "most of the fix", not all of it;
 - a per-IOMMU bit is refcounted / re-armed on resume → matters for suspend users.
 Also check the driver-side consumer's gate condition (e.g. `amdgpu_device_use_perfopt()` requires `AMD_IS_APU` **and** the identity domain) — the feature and the endpoint you care about can live on independent paths (amdxdna binds its own SVA domain regardless of default domain type), which is what decouples "perf lever" from "device works again".
 Never inherit a vendor/press delta as a local cost: record it as *vendor-claimed, never measured here*, and make the procedure demand a local A/B in the maintenance window. Flag stale baselines by quoting the current measured figure.
 ## 3. Correct every carrier, in one cutover
 Decision-record page (new dated section + front-matter `description` re-key), the retired-endpoint runbook that carries the now-dead law, `AGENTS.md` key-lesson bullet, worklog. Delete the dead law rather than annotating it.
 ## 4. Publish to Gitea without leaking the token
 Token NEVER in argv (`curl -H "Authorization: …"` is world-readable in `/proc/<pid>/cmdline`). Reuse the git credential store, write a 0600 curl config, delete it after:
 ```python
 line = next(l for l in (~/.config/secrets/gitea).read_text().splitlines() if HOST in line)
 user, tok = urllib.parse.unquote(...)      # store file is percent-encoded
 cfg = 0o600 temp:  user = "USER:TOKEN"
 subprocess.run(["curl","-sS","-K",cfg,"-o",resp,"-w","%{http_code}", ...])
 os.unlink(cfg)
 ```
 - New comment: `POST /api/v1/repos/{o}/{r}/issues/{n}/comments`, body `{"body": markdown}` → 201.
 - **Correction: `PATCH /api/v1/repos/{o}/{r}/issues/comments/{id}` — edit in place, do NOT post a follow-up.** A wrong claim published is fixed by editing it; leaving the wrong text up for future readers is the failure mode.
 - Verify: anonymous `GET .../issues/{n}/comments` then assert the corrected marker is present AND the retracted phrase is absent.
 ## 5. Verification
 `./tests/run.sh` (docs completeness + vault link integrity cover the doc edits), commit, push. Secrets scratch files: unlink them; do not leave a token-bearing temp behind.
 ## Gotchas
 - Markdown bullet lines inserted through the `edit` tool: an escape like `+- item` came out **verbatim** (file kept `+- `), twice. When a list block must be rewritten, `write` the whole file instead of guessing escape syntax.
 - A reader-mode `read` of a news page can return the ad-blocker JS blob; use the mailing-list/patch archive (native method) for primary sources.
@@ -0,0 +1,27 @@
 ---
 name: key-chord-source-audit
 description: "Answer \"what does chord X do\" on Dank workstations: identify which layer (omp TUI, browser tool, niri, terminal) owns the chord before answering"
 ---
 # Key-chord source audit
 Frank asks "what does mod+r / ctrl+X do?" — the chord lives in ONE layer of the stack; answering from the wrong layer is wrong. Check layers in order, in ONE pass.
 ## Layers, in Frank's stack (most of his "mod" questions are niri)
 1. **niri compositor** (Mod = Super). Keybinds are NOT in `~/.config/niri/config.kdl` — it only `include`s `cfg/*.kdl`. Grep `~/.config/niri/cfg/keybinds.kdl` directly. Notation: `Mod+R`, `Mod+CTRL+Alt+H`. Preset-width cycle (Mod+R) uses `preset-column-widths` from `cfg/rules.kdl`; no rule → built-in proportions 3/4, 1/3, 1/2, 2/3, 9/10, 1.
 2. **omp TUI**: defaults in `~/.bun/install/global/node_modules/@oh-my-pi/pi-coding-agent/dist/cli.js` — grep `defaultKeys:\["…"` (array form) and `defaultKeys:"…"` (string form; needs a second pattern). Recognized modifiers: ctrl/shift/alt/super only; no `meta`/`mod` alias. User remaps: `~/.omp/agent/keybindings.yml` (check existence first; absent = no remaps). Docs: `omp://keybindings.md`.
 3. **omp browser tool**: `Mod+Key` is Playwright notation (`Mod` → Ctrl on Linux, Cmd on macOS), used by `tab.press()`; e.g. `Mod+R` = page reload. Tern backend `ternKey()` throws on literal `Mod`; puppeteer path passes names through.
 4. **Terminals/tmux**: `~/.config/ghostty/config.ghostty` + `ghostty/auto/`, `foot.ini`, `kitty.conf`, `~/.tmux.conf` — keybind/bind/map lines.
 ## Procedure
 1. Classify the notation the user used: `Mod+…` → niri/Playwright; `Ctrl+…` → TUI/terminal; tmux prefix → tmux.
 2. Grep that layer's config FIRST, expanding includes (config.kdl → cfg/*.kdl is the trap that caused a wrong answer).
 3. For omp bundle greps: two `defaultKeys` forms exist; `super+r` pattern also matches `super+right` — anchor with word boundary.
 4. Quote the exact config line as evidence; state the layer that owns the chord.
 ## Verification
 - niri keybinds: `grep -n "Mod+R" ~/.config/niri/cfg/keybinds.kdl` (not config.kdl).
 - omp: `grep -o '"app[^"]*":{defaultKeys:[^}]*' cli.js` for app actions; `grep -rn "defaultKeys" pi-tui/src/keybindings.ts` for editor actions.
@@ -0,0 +1,45 @@
 ---
 name: land-branch-without-checkout
 description: "Open a PR from a shared worktree when workspace policy blocks git checkout/restore: push a named branch ref from HEAD without switching branches."
 ---
 # Landing a branch when `git checkout` is policy-blocked
 Shared-workspace policy blocks `git checkout` and `git restore` (working-tree
 switches could strand concurrent agents' uncommitted work). You still must ship
 the commit on the current worktree branch as a named `chore|feat|fix/<issue>-<slug>`
 branch. Never work around the block — go around it via refs.
 ## Sequence
 ```bash
 # 1. commit only your files (atomic); leave other dirty paths alone
 git add <your-files> && git commit -m "..."
 # 2. branch ref at HEAD — no working-tree change, stays on wt/<...>
 git branch <type>/<issue>-<slug> HEAD
 git push origin <type>/<issue>-<slug>          # pre-push hooks still run
 # 3. PR via tracker API with head = pushed ref (see gitea-pr-api-cycle / gh)
 ```
 - The worktree stays checked out on `wt/<timestamp>`; the new branch exists
  only as the pushed ref (plus a local ref that merges cleanly later).
 - `-u` upstream tracking on the wt branch is misleading — skip it; set
  `git config branch.<name>.remote origin` + `.merge` only if you will
  later check the branch out.
 - Dirty regenerated fixtures left behind (e.g. `gen:sample` PDFs rewritten
  by setup/gate runs): `git restore` is also blocked — do NOT edit-forward
  to revert them; report them. They are regenerated on every bootstrap, so
  dirt is expected and harmless.
 ## Verify
 - `git ls-remote --heads origin <branch>` prints the same sha as `git rev-parse HEAD`.
 - PR API returns 201 with `head.sha` equal to that sha.
 ## Do NOT
 - `git checkout -b`, `git stash`, `git restore`, `git reset --hard` here —
  all working-tree mutations the policy can block, and stashes in a shared
  checkout are a cross-agent footgun.
@@ -0,0 +1,27 @@
 ---
 name: land-merged-pr-with-blocked-tree-ops
 description: "Use when a merged PR must land in a checkout whose working tree is dirty and workspace policy blocks git switch/restore/stash/reset-to-commit: prove identity, commit forward, merge, verify."
 ---
 # Landing a merged PR into a checkout with blocked tree operations
 Shared-workspace policy can block `git switch`, `git checkout <branch>`, `git restore`, `git stash`, and `git reset <commit>` ("uncommitted changes other concurrent agents rely on"). A `git pull --ff-only` then aborts with *"Your local changes to the following files would be overwritten by merge"* — **even when the local content is byte-identical to the incoming commit**, because git compares the index, not intent. Observed twice on 2026-10-19 (dank/command-center, dank/dankvoice).
 ## Procedure
 1. **Prove identity first — never assume it.**
   `git fetch && git diff --stat origin/main -- <the dirty paths>` → **empty output** means the working tree already equals the merged result, so committing it forward destroys nothing. If it is not empty, stop: there is real local work; do not proceed.
 2. **Commit forward** the identical paths (message says exactly that, e.g. *"land merged #N content; policy blocks restore/stash, so the identical copies are committed rather than discarded"*). Hooks still run.
 3. **Merge, don't ff:** `git merge --no-edit origin/main` (ort resolves identical changes on both sides cleanly). `--ff-only` is impossible once step 2 created a commit.
 4. **Untracked-collision case:** if the abort says *"Please move or remove them before you merge"*, an untracked local file occupies a path the merge adds. `mv` it aside, merge, then `cmp` the restored file against the copy — identical → drop the copy (if the copy came from `.AGENTTRASH`, delete it and `rmdir`, since the file is now tracked).
 5. **Verify:** repo lint/tests, `git status --porcelain -- <paths>` empty, and `git rev-parse --short HEAD origin/main` equal **after a fresh `git fetch`**.
 ## Gotchas
 - `git merge … | tail -3` masks the exit status — `tail` always exits 0 and an `&&` chain then continues past an aborted merge. Run the merge unmasked, or check `${PIPESTATUS[0]}`.
 - Immediately after a push, `git rev-list --count main..origin/main` can report phantom commits-behind from a stale remote-tracking snapshot. Re-`fetch` and compare `rev-parse` before believing any drift.
 - Do not push redundant commits into a *deployment* checkout without checking the repo's tier law: machine/live tiers commit straight to `main`, human/agent prose goes by PR.
 ## Never
 No `--no-verify`, no `reset --hard`, no `checkout -- <path>`, no "temporary" stash: those are exactly the operations the policy blocks because they discard other agents' work.
@@ -0,0 +1,83 @@
 ---
 name: llamacpp-adapter-swap
 description: "Add or roll back a GGUF LoRA adapter on a dank-fleet llama.cpp endpoint (e.g. frank-zealot): provenance census, fork-flag gate, fetcher+env+deployer surface, seam tests, and the behavioural before/after probe that is the only real proof."
 ---
 # Applying a GGUF LoRA adapter to a fleet endpoint
 An adapter is **payload, not shape**: it changes what the endpoint answers and nothing in
 the KV/budget equation. Fleet law still applies — no benchmarks unless Frank orders one,
 rollback is one env line, `./tests/run.sh` before commit, deployer health gate + e2e gate.
 ## 1. Census the artifact BEFORE writing any code
 ```bash
 curl -sS "https://huggingface.co/api/models/<repo>?blobs=true"   # size + LFS oid (None => plain git object)
 curl -sSL -o /tmp/a.gguf "https://huggingface.co/<repo>/resolve/main/<file>" && sha256sum /tmp/a.gguf
 ```
 Parse the GGUF KV section (15 lines of struct.unpack) and read **provenance**: abliteration
 adapters carry `prism.abliterate.base_gguf` / `base_sha256`, `adapter.type`, `sites`,
 `target_layers`, `target_embedding`. Compare the declared base against the file the endpoint
 actually serves (its sha is in the endpoint's own fetcher script). A mismatch is normal for
 sibling quantizations — the loader matches **tensor names, not hashes** — but it must be
 stated in the docs, because it means the card's measured numbers are not this endpoint's
 numbers.
 ## 2. Gate the runtime, from the binary's own `--help`
 On the host: `/home/dank/GitPackages/<build>/llama-server --help | grep -iE 'lora|adapter'`.
 Confirm `--lora-scaled FNAME:SCALE` exists (and `--lora-init-without-apply` + `POST
 /lora-adapters` if a runtime toggle is ever wanted). Vendor forks gate adapters by metadata
 version too — e.g. PrismML builds older than `prism-b10777` refuse packs with `unsupported
 prism.hadamard.version: 2`. Read the card for the build it verified on and put that in the
 fetcher header.
 ## 3. Surface (five files, copy the mmproj convention)
 - `scripts/<svc>.env`: `LORA_FILE=<path>` + `LORA_SCALE=1`; document that **`LORA_FILE=` (empty)**
  is the rollback and `LORA_SCALE=0` is the inert-but-present mode. Use `${VAR=default}` (no
  colon) so an explicitly empty value survives — same reason `MMPROJ_FILE`/`PRESENCE_PENALTY` do.
 - `scripts/serve-<svc>.sh`: `EXTRA_ARGS+=(--lora-scaled "${LORA_FILE}:${LORA_SCALE}")` — **one
  argv token**, so a scale can never arrive without its file; refuse a missing file by name
  (`Restart=always` turns an unfinished fetch into a crash loop that reads like a runtime fault).
 - `scripts/download-<svc>-<adapter>.sh`: copy the sibling fetcher (`-fsSL --fail-with-body`, byte
  count, sha256, `--verify-only`, idempotent). No LFS oid => pin the content sha. Header carries
  the provenance finding.
 - `scripts/deploy-remote.sh`: `LLM_<SVC>_LORA="${LLM_<SVC>_LORA:-<path>}"` + a check whose error
  names **this** fetcher, not the payload's.
 - `scripts/deploy-plan.py` needs nothing: fetchers are host-side state and select no service.
 ## 4. Seam tests (argv is the contract)
 Stub-engine harness: create the adapter stub from the **shipped env's basename**, emit
 `LORA_FILE`/`LORA_SCALE` in the generated test env, then assert on output only —
 `--lora-scaled` value equals `<path>:<scale>`; a distinctive `LORA_SCALE` (0, 0.75) changes the
 token; `LORA_FILE=` yields **absence** of the flag (`! grep -qxF -- '--lora-scaled'`); a missing
 file exits non-zero naming that path; extend the env↔deployer anti-drift pair list.
 ## 5. Deploy and prove it behaviourally
 Capture the **before** state on the live endpoint first, then: merge → on host `git pull` +
 run the fetcher → `./scripts/deploy.sh <host> --service <svc>`.
 ```bash
 sudo systemctl show <svc> -p DropInPaths --value          # must be empty (bench-drop-in law)
 sudo tr '\0' ' ' < /proc/$(sudo systemctl show <svc> -p MainPID --value)/cmdline
 sudo journalctl -u <svc> --since <boot> | grep -iE 'adapter|lora'   # llama_adapter_lora_init_impl prints prism.* keys
 ```
 Refusal probe (the only proof of an abliteration adapter): same prompts, `temperature 0.1`,
 **`max_tokens >= 2048`** — on thinking models a short budget is consumed by
 `reasoning_content` and `content` comes back empty with `finish_reason: length`, which reads
 as a refusal that never happened. Classify with a marker regex and report refusal-vs-complied;
 do not paste generated harmful content into chat. Also run the standing trio: exact-phrase
 chat, `tool_calls` with valid JSON, and a >=256 px solid-colour vision probe. A residual
 `⚠️ Important Disclaimer` heading after the swap is style, not the refusal circuit.
 ## Docs
 Endpoint page (`serverAppConfigs-docs/LLM/<svc>.md`): Adapter row, Fetch row, Flags row, one
 Era row whose rollback is the env line, and a measured before/after paragraph. Laws worth
 adding: provenance is metadata not a gate; an `token_embd` rank would crash, so an adapter is
 not inert; the runtime pin may gain a second reason. Never restate the card's benchmark table.
@@ -0,0 +1,47 @@
 ---
 name: llamacpp-candidate-arm-census
 description: "Measure a candidate GGUF/KV-shape on a live dank-fleet llama.cpp endpoint (frank-zealot pattern) in ONE service-stop window: pre-flight flag check, per-arm env overrides, boot ledger + nvidia-smi census, behavior probes, trap-guarded restore."
 ---
 Measure candidate shapes on a production llama.cpp endpoint without cutting anything over. One outage window, many arms, guaranteed restore.
 ## 0. Pre-flight (no GPU needed — do all of it before stopping anything)
 - `ssh <host> <candidate-bin> --list-devices` — the candidate must see the card (backend `.so` releases resolve via `$ORIGIN`, so run from the extracted asset dir).
 - Flag-compat gate: loop the exact long options the serve script emits and grep the candidate's `--help`. A single unknown flag = a dead boot in the middle of the window. Remote shells may be **zsh**: `$flag[ ,<]` is parsed as an array subscript ("bad math expression") — pipe the check through `ssh <host> 'bash -s' <<'CHK' … CHK` and use `grep -qE "(^|[[:space:]])$f([[:space:],<]|$)"`.
 - Pause any concurrent compile (`pkill -f "[r]un-<build>"` — the bracket stops `pkill -f` matching your own command line; `pkill -x ninja`). Ninja is incremental: the build resumes where it stopped, and CPU contention otherwise skews every rate.
 ## 1. Runner shape
 Write one script to `/tmp` on the target via `ssh <host> 'cat >/tmp/….sh' <<'EOF'`. Never edit the repo checkout on the target; drive the shipped serve script with a **per-arm env file** and `FRANK_<SVC>_ENV_FILE` (the serve scripts already honor it).
 ```bash
 SRV=""
 used(){ nvidia-smi --query-gpu=memory.used --format=csv,noheader,nounits; }
 restore(){ [[ -n "$SRV" ]] && kill "$SRV" 2>/dev/null; pkill -x llama-server
  for i in $(seq 1 90); do [[ "$(used)" -lt 1500 ]] && break; sleep 2; done
  sudo systemctl start <svc>
  for i in $(seq 1 150); do [[ "$(curl -s -o /dev/null -w %{http_code} http://127.0.0.1:<port>/health)" == 200 ]] && break; sleep 2; done
  echo "RESTORE health=$(curl -s -o /dev/null -w %{http_code} …/health) used=$(used) state=$(systemctl is-active <svc>)"; }
 trap restore EXIT
 ```
 - `trap restore EXIT` is mandatory, not polite: it also fires on the failure paths, so a script bug cannot leave the endpoint down.
 - Preserve the production log first (`cp -f /home/dank/logs/<svc>.log …prod-<ts>.log`) — the serve script truncates it.
 - Health-poll cap ~120×2 s. 300 polls turns an expected-allocation-failure arm (the "wall" arms) into 10 wasted minutes.
 - Arm = `sed` the base env (CTX_SIZE / PARALLEL / KV_CACHE_TYPE / LLAMA_BIN / LOG_FILE), boot with `setsid nohup env FRANK_<SVC>_ENV_FILE=… bash <serve-script>`, then capture: `nvidia-smi` used+free, ledger grep (`type |model size|n_ctx|flash|KV buffer|buffer size|slots|error|exceed`), `/slots` (per-slot `n_ctx` is the harness contract), `/v1/models`.
 - **Point LLAMA_BIN at a binary that exists.** Take 1 of this procedure died in 8 s because the trial env named a still-compiling source build; the trap saved the endpoint.
 ## 2. Probes that actually discriminate
 - chat: `content` vs `reasoning_content` (channel differs per runtime) + `finish_reason`.
 - tools: real `tools` schema, assert `tool_calls[0].function.arguments` parses as JSON — empty/`null` arguments is a known fork bug.
 - vision: 512×512 **solid color** PNG built with `zlib`+`struct` (no PIL), sent as an OpenAI `image_url` content part; expect the exact color word. The legacy top-level `images` field hallucinates a plausible answer.
 - rate: `/completion` (not `/v1/chat/completions`) — it returns `timings` (prefill/decode). ≥128 tokens.
 - long-context fill: ~190k tokens through `/completion` proves the per-slot window AND tests the "quantized KV near 200K" stability reports.
 Skip `llama-bench` for shape work: it has no `-c`/`-np`, and its `-mmp` is `--mmap` (deprecated), not mmproj. Booting the server per arm measures the real shape and prints the ledger, which is the referee.
 ## 3. Report
 Per arm: ledger KV-buffer MiB, used/free at settle, FITS / tight / NO FIT vs the card's `used+free` ceiling from settled boots (not the spec sheet). Then restore, and state the downtime.
@@ -1,28 +1,33 @@
 ---
 name: llamacpp-endpoint-model-swap
-description: "Swap the model on a dank-fleet llama.cpp endpoint (frank-secondary pattern): fetch, env edit, spec flags, deploy through git, rewrite the bats seam, verify VRAM with the engine's own numbers."
+description: "Swap the model on a dank-fleet llama.cpp endpoint: fetch, runtime-door census, env edit, deploy through git, rewrite the bats seam, sweep every live-path straggler, verify VRAM with the engine's own numbers."
 ---
 # llama.cpp endpoint model swap (dank fleet)
-Use when replacing the model/shape on a llama.cpp endpoint (e.g. frank-secondary on the RTX 3090). The engine's boot numbers are the verdict — do NOT commit to a feasibility verdict from head math; boot it and read `nvidia-smi`.
+Use when replacing the model/shape on a llama.cpp endpoint (frank-zealot on the RTX 3090). The engine's boot numbers are the verdict — do NOT commit to a feasibility verdict from head math; boot it and read `nvidia-smi`.
 ## Sequence
-1. **Geometry first, from the loaded model's own log** (`--log-verbosity 4`, or the HF `config.json` under `text_config` for multimodal): layers, `n_head_kv` (an ARRAY — per-layer, e.g. gemma4 has 8 on sliding layers, 2 on full-attention), head_dim, `sliding_window_pattern`, `n_swa`, `attention_k_eq_v`. KV scales only with full-attention layers; sliding layers cost a fixed window-size ring. Single-value HF fields lie about per-layer heterogeneity.
+1. **Runtime door BEFORE anything else.** Histogram the GGUF's tensor types and metadata (one python range-read of the KV section): a custom type (e.g. PQ2_0 = GGML type 142 + `prism.hadamard.*`) means the vendor/fork build is FORCED, not chosen — stock llama.cpp refuses it at load. Record the build identity (path, build number, commit, sha256) in the env comment; a `--help` census on that binary is what settles flag questions (this fleet's builds have NO fp8 KV; q8_0 is the "FP8 class"). NEVER `grep -c <archname>` on the packed binary to check arch support — it returns 0 for every arch.
-2. **Fit the KV rate law to the engine, not to arithmetic.** Run once with `--log-verbosity 4` and read the `llama_kv_cache` / `sched_reserve` buffer MiB lines. Known law for master 5fc4f3c: bytes/elem = (K bytes + V bytes) **x2** when the file declares `attention_k_eq_v` (6.125 at f16 K + q8_0 V, 2.125 at q8_0/q8_0) — k_eq_v is a compute-graph mapping and does NOT shrink the cache. Full cache = n_full x n_head_kv x head_dim x rate x ctx; SWA cache = n_swa x window x n_head_kv_swa x head_dim x rate. Both reproduce the printed MiB exactly; if your formula does not, your law is wrong, not the engine.
+2. **Geometry first, from the loaded model's own log** (`--log-verbosity 4`, or the HF `config.json` under `text_config` for multimodal): layers, `n_head_kv` (an ARRAY — per-layer), head_dim, `sliding_window_pattern`, `n_swa`, `attention_k_eq_v`. KV scales only with full-attention layers; sliding layers cost a fixed ring; recurrent/linear layers (Gated DeltaNet) bill a fixed state per SLOT (~150 MiB measured), invisible to pool arithmetic. Single-value HF fields lie about per-layer heterogeneity.
-3. **Probe the binary's real capabilities** before promising flags: `--help | grep -A2 cache-type-k` (this fleet's build has NO fp8; q8_0 is the "FP8 class"), `--help | grep -A2 verbosity` (`-lv, --log-verbosity N`; ship `VERBOSITY` as an env tunable + `--log-verbosity "$VERBOSITY"` so VRAM forensics land in the journal), `--help | grep model-draft` for separate drafters. NEVER `grep -c <archname>` on the packed binary to check arch support — it returns 0 for every arch; check the source tree at the build's commit.
+3. **Fit the KV rate law to the engine, not to arithmetic.** One boot at `-lv 4` prints `llama_kv_cache` / `sched_reserve` MiB lines. Master 5fc4f3c law: bytes/elem = (K + V) **x2** when the file declares `attention_k_eq_v`. Full cache = n_full x n_head_kv x head_dim x rate x ctx. If your formula disagrees with the printed MiB, your law is wrong.
-4. **Fetch with `-f` + byte-count check** into `/home/dank/models/<name>/`.
+4. **Price the KV dtype by BOOTING the arms, at the target window.** f16 may simply OOM (`cudaMalloc failed` after the engine's own fit line names the MiB it wanted); q8_0 may be the only pair that funds 2 x 200,704; q4_0 is the fallback rung. Record every arm's used/free. **The mmproj lands AFTER the engine's fit projection** (projected fit < settled VRAM by ~1.5x the projector file size) — quote both numbers.
-5. **Edit the repo trio** (`scripts/serve-<svc>.sh`, `scripts/<svc>.env`, `~/.omp/agent/models.yml`): spec flags move as a SET (`SPEC_TYPE=none` strips `--spec-type` AND `--spec-draft-model`/`--spec-draft-*`); a drafter with its own arch file (gemma4-assistant) needs `SPEC_DRAFT_FILE`, and its draft KV is built against the TARGET's full window — price it from a boot pair. `models.yml` `contextWindow` = per-slot window (`CTX_SIZE/PARALLEL`); recompute `maxTokens` for the compaction clamp `min(maxTokens, ctx - estimate - 4096)`.
+5. **Fetch with `-f` + byte-count + sha256 check** into `/home/dank/models/<name>/`; `--verify-only` mode for re-census.
-6. **Rewrite the bats seam in the same commit** (`tests/<svc>_unit.bats`): payload path, slot geometry, KV pair, spec state, batch pair, verbosity, mmproj opt-out, reasoning flags — all argv-asserted against the stub engine; where the contract is a repo value (batch pair, verbosity) assert argv == env value so a retune moves one file.
+6. **Edit the repo trio** (`scripts/serve-<svc>.sh`, `scripts/<svc>.env`, `~/.omp/agent/models.yml`). **Use the serve script's OWN variable names** (`CACHE_TYPE_K`/`CACHE_TYPE_V`, `BIND_ADDR`, `NGL`) — an invented name is silently swallowed by `: "${VAR:=default}"` and the arm boots the DEFAULT (cost a whole trial window: a `KV_CACHE_TYPE` scratch env booted f16 and OOMed while reading as a model fault). Sweep the script's DEFAULTS to the new payload too: a defaulted run must land on the shipped shape, never the retired one. Spec flags move as a SET (`SPEC_TYPE=none` strips `--spec-type` AND `--spec-draft-*`); MTP is a property of the FILE (no `nextn` tensors = no drafter, ever). `models.yml` `contextWindow` = per-slot window (`CTX_SIZE/PARALLEL`); recompute `maxTokens` for the compaction clamp `min(maxTokens, ctx - estimate - 4096)`. Check the payload's own template: if it reads `reasoning_effort`, the `reasoningEffortMap` fold becomes LOAD-BEARING (an unmapped level is a 500 naming Jinja, not the model) and quote the file's `general.sampling.*` trio in `extraBody`.
-7. **Deploy through git** (no direct remote edits). If the remote tree is dirty: `git stash push <files>` on the host, `git pull --ff-only`, land the change as a commit. A pull that aborts leaves the host at the OLD revision while the service runs the NEW edits — verify `git log -1` on the host.
+7. **Rewrite the bats seam in the same commit** (`tests/<svc>_unit.bats`): payload trio paths, slot geometry, spec state, batch pair, verbosity, mmproj opt-out, reasoning flags — argv-asserted against the stub engine; where the contract is a repo value (batch pair, verbosity, **KV dtype**) assert argv == env value so a retune moves one file and a wrong-name env edit cannot pass silently.
-8. **Verify the engine, not your math**: `/proc/<pid>/cmdline` (argv is the contract), `/v1/models` (`n_ctx`, `ftype`, `n_ctx_train`), `nvidia-smi --query-gpu=memory.used,memory.free`, `/health` 200, a vision probe (solid color >=256 px via `image_url`, expect the exact word), and one generation probe reading `timings.predicted_per_second`. Record the numbers in the env comment + runbook, then push and ff-pull the host.
+8. **Trial window protocol** (when the shape is unproven on the card): stop the unit (trap-guarded `systemctl start` restore in the scratch script), run the arm census + behavior probes as a DETACHED script writing to `/home/dank/logs/<name>.out`, then before touching production CENSUS the live state: `systemctl is-active`, `ss -ltnp | grep <port>`, `pgrep -x llama-server`, `nvidia-smi`. A scratch server orphaned by a client-side timeout holds the whole card and will OOM the real boot — kill by PID (never `pkill -f llama-server`). A trap restore can race your manual kill; read the script's own `RESTORE` log line before assuming who did what.
-9. **Cutover AGENTS.md in the same commit**: fleet-topology table row, the `### <svc>` section, the `Model Config` contextWindow/vision note, the runbook index ACTIVE row, a RETIRED row for the superseded era. The new docs page must be linked from the TOP-LEVEL `serverAppConfigs-docs/index.md`.
+9. **Deploy through git** (no direct remote edits): commit atomically on the worktree branch, `git fetch && git rebase origin/main` (log.md conflicts at EOF are two waves appending — keep both), push branch (`--force-with-lease` after a rebase), then in the MAIN checkout `git pull --ff-only` + `git merge --ff-only <branch>` + `git push origin main`, then `scripts/deploy.sh <host> --service <svc>` (`--service` is REPEATABLE — name the homepage too when cards changed, or the target ships the model without its docs). A `deploy.sh` with no `--service` is a fleet-wide drain: never.
 10. **Verify the engine, not your math**: `systemctl is-active/is-enabled` + the new `Description`, the journal fit/KV/buffer ledger (`projected to use N`, `KV buffer size`, `n_ctx_seq`, `n_slots`), `/v1/models` served alias (radiance-style echo does not apply to llama.cpp, but the alias is still the honest check), `nvidia-smi` settled, then live probes through the REAL request shape the harness sends (exact-instruction chat + `reasoning_content`, `tool_calls` JSON args, solid-color `image_url` >=256 px expecting the exact word, `timings.predicted_per_second`). Never report the FIRST request after a boot (warmup artifact). Push, and record numbers in the env comment + runbook.
 11. **Cutover every consumer, same branch**: AGENTS.md (topology row, `### <svc>` section, Model Config note, runbook index ACTIVE + RETIRED rows); the new docs page MUST be linked from the TOP-LEVEL `serverAppConfigs-docs/index.md` (the `docs_completeness` seam fails otherwise, not from `LLM/index.md`); `shared/homepage/services.json` + `docs.html` (model link, spec line, rate, and the WARNING — a censored base breaks the "common uncensored text" equality in `homepage_config.bats`, so re-key the test's premise too); `serverAppConfigs-docs/Dankclaw/OpenWebUI.md` + the live `model` row `meta.description` (live DB state: snapshot `webui.db.bak-<date><letter>`, UPDATE via host python3 over ssh; do NOT restart `open-webui` for a cosmetic string — it logs every family session out).
 ## Gotchas
 - A "we can rebuild the fork ourselves for provenance" claim needs the source tree AT the vendor build's commit — check `git -C <src> log --oneline -1` first. A fork checkout at branch HEAD (`prism` at `0082ac2`) is NOT the vendor build (`2459f68b5`), so the rebuild produces a different binary, not the verified one. Also: if the vendor binary already demonstrates the requirement (KV dtype buffer math in the ledger + live probes), a rebuild buys no behavior change — offer it explicitly as provenance hardening, never do it silently.
 - A systemd restart reporting `inactive` in the first seconds is usually model-load time; check `journalctl -u <svc>` for `model done`/`server is listening` before declaring failure.
- Rollback = the previous payload stays on disk; one `MODEL_FILE` + shape edit back.
+- Rollback = the previous payload stays on disk; one `MODEL_FILE` + shape edit back. Record a refusal-freedom fallback the same way (an official censored base ↔ a CRACK re-export with byte-identical header geometry is a one-line swap; prove the identity with the tensor histogram, not the card).
- A thinking model can consume the whole token budget in `reasoning_content` (empty `content`, `finish_reason: length`) — probe with a budget that clears thinking.
+- A thinking model can consume the whole token budget in `reasoning_content` (empty `content`, `finish_reason: length`) — probe with a budget that clears thinking; a short-budget vision probe reads as "the model is blind".
- **Bats vacuity trap**: `serve_argv` REWRITES `$STAGE/test.env` from the shipped env, so a test that mutates the file (`sed -i`, append) then calls `serve_argv` asserts on regenerated content — a tautology. Tests that mutate must exec via a `run_stage` helper running the file as-is. Symptom: the assertion fails only after you fix the vacuity, and the env dump shows the mutation gone.
+- `/completion` at `-lv 4` prints `failed to parse reasoning content ...` on raw prompts closing with an end-of-turn marker: cosmetic (chat path parses correctly). At ~26k+ a bare `/completion` can return 0 tokens with no error — raw context has no role frame; chat is unaffected.
- `env NAME=value cmd` needs valid identifiers; a flag-like token (`nvidia-modprobe=true`) is only legal as an `env` ARGUMENT, not as a shell assignment prefix.
+- **Bats vacuity trap**: `serve_argv` REWRITES `$STAGE/test.env` from the shipped env, so a test that mutates the file then calls `serve_argv` asserts on regenerated content — a tautology. Tests that mutate must exec via a `run_stage` helper running the file as-is.
 - `env NAME=value cmd` needs valid identifiers; a flag-like token is only legal as an `env` ARGUMENT, not as a shell assignment prefix.
 - Gitea `git push` on a rebased branch is rejected non-fast-forward: `--force-with-lease` (your own branch), never on main.
@@ -0,0 +1,74 @@
 ---
 name: llamacpp-trial-boot-census
 description: "Measure whether a candidate GGUF fits a live llama.cpp endpoint's card: verify serve-script env names first, run a dtype/slot arm matrix with trap-guarded production restore, read the engine fit ledger."
 ---
 # llama.cpp trial-boot census (does candidate X fit this card?)
 Paper arithmetic on KV rates is a hypothesis. The engine's own fit ledger plus a
 real boot are the proof. This protocol ran on frank-zealot (RTX 3090,
 Qwen3.5-9B Q6_K → prism-ml Ternary-Bonsai-2-27B PQ2_0, 2026-10-17).
 ## 0. Gate: env variable names, not invented ones
 A trial env written from memory silently falls back to the serve script's
 defaults. `KV_CACHE_TYPE=q8_0` when the script reads `CACHE_TYPE_K`/`CACHE_TYPE_V`
 boots **f16** and every later number is wrong (this wasted a whole outage; two
 arms printed identical allocations, which is the tell).
 ```bash
 grep -nE ': "\$\{[A-Z_]+[:=-]' scripts/serve-<svc>.sh   # the real names + defaults
 grep -nE '\-\-[a-z-]+ "\$' scripts/serve-<svc>.sh       # what actually reaches argv
 ```
 Never invent: KV dtype, bind addr, n-gpu-layers, log-file (units redirect it).
 ## 1. Runner skeleton
 One script on the host, `set -u`, `trap restore EXIT`:
 ```bash
 restore(){ pkill -x llama-server; for i in $(seq 1 90); do [[ "$(used)" -lt 1500 ]] && break; sleep 2; done
  sudo systemctl start <svc>; for i in $(seq 1 150); do [[ "$(curl -s -o /dev/null -w %{http_code} $BASE/health)" == 200 ]] && break; sleep 2; done; }
 trap restore EXIT
 sudo systemctl stop <svc>            # benching law: stop first, mask fails on relinked units
 setsid nohup env FRANK_<SVC>_ENV_FILE=/tmp/armA.env bash scripts/serve-<svc>.sh >$LOG 2>&1 &
 ```
 Launch with `setsid nohup … &`, wait with ONE async watcher (`grep -q DONE`),
 never poll. Per-arm drop-in envs via `sed` on a base env — one variable per arm.
 ## 2. Arm matrix (cheap, each ≈ boot + probes)
 | Arm | Purpose |
 |---|---|
 | target shape × target KV dtype | the verdict + behavior probes |
 | target shape × f16 KV | proves the wall (or funds the shape) |
 | 1 × native-window | answers "can we serve the full context" |
 | target shape × q4_0 | the roomy fallback rung |
 ## 3. Read the ledger, not `nvidia-smi` alone
 ```bash
 grep -a -A8 "memory breakdown" $LOG     # total = free + (model + context + compute)
 grep -aE "KV buffer size|model buffer size|compute buffer size|estimated worst-case memory usage of mmproj|projected to use|cannot meet free memory target|cudaMalloc failed" $LOG
 ```
 Laws learned the hard way:
 - `projected to use N MiB vs M MiB of free` + `cannot meet free memory target of R` ⇒ requirement is `projected + R ≤ free`. With `--n-gpu-layers` pinned by the user the fitter **aborts** instead of shrinking — the boot then dies at the KV `cudaMalloc`.
 - `context` bills **more than the KV pool**: hybrid models add a fixed recurrent state per slot (~150 MiB/slot for qwen35's 48 DeltaNet layers). Pool math alone under-prices.
 - **The projector's `estimated worst-case memory usage of mmproj is X MiB` is NOT inside the fit projection.** It lands after the fit check, so real headroom = paper headroom − X. This is the "boots fine, then dies / dark" class.
 - q8_0 K+V bills exactly `2 × (layers_kv × heads × dim / 32 blocks × 34 B)`/token — check the reported KV MiB against that to prove the dtype actually took.
 ## 4. Probe traps
 - **First request after boot is warm-up garbage**: it paid 2.6 t/s prefill / 37.7 t/s decode where the warm run gave 1,258 t/s. Never bench the first request; discard it or warm with a throwaway.
 - Reasoning-on chat probes need **≥512 `max_tokens`**: at 64 the answer was empty (`finish=length` mid-`reasoning_content`) while vision actually worked. Judge `content` only at a budget the thinking can fit.
 - Raw `/completion` (no chat template) returns `content` only — thinking is invisible; `timings.prompt_n` / `predicted_per_second` are the real keys, not `prompt_tokens`.
 - Vision probe: solid-color PNG ≥256 px, expect an exact color word.
 - Concurrency honesty: fire two identical requests in parallel; per-slot rates from each response's `timings`.
 ## 5. Restore proof
 `health=200` **and** `systemctl is-active` — an `inactive` unit behind a 200 means
 a stray trial process holds the port. Kill by pid; never `pkill -f llama-server`.
@@ -0,0 +1,24 @@
 ---
 name: llm-bench-harness-fault-census
 description: "Diagnose implausible LLM benchmark scores in frank-intelligence-bench: failure-signature census, harness-fault signatures (target NameError, scicode ModuleNotFound, markdown-fence SyntaxError), and official-protocol grading law."
 ---
 Use when benchmark scores look impossible (0% across the board, sudden cliffs) in frank-intelligence-bench.
 # Law
 Scores are untrusted until `bun run src/cli.ts analyze <run-id>` shows a failure-signature census with ZERO harness suspects. Model-side signatures (AssertionError on real values, AxisError, model's own NameErrors) are fine; harness signatures indict the engine.
 # Census
 - Reads `runs/<id>/ledger.jsonl` grade rows, extracts last `*Error: name 'X'` / `No module named 'X'` per failing row, aggregates per eval.
 - `harnessSuspects()` flags: `NameError: target(s)` (gold target binding missing), `ModuleNotFoundError: scicode` (pinned pkg absent from sandbox image), >50% shared signature ≥10 samples (systematic fault), >50% gen failures (endpoint fault).
 # Known harness faults (friction-earned, 2026-10-10)
 1. SciCode gold values live ONLY in `test_data.h5` (authors' Drive folder `1W5GZW6_bdiDAiipuFMqdUhvUaHIj6-pR`); tests reference bare `target`. Fix = `stageH5()` (sha256-gated upload to Dankclaw, mounted `/w-data/test_data.h5:ro`) + `process_hdf5_to_tuple(step, n_cases, h5py_file=...)` per official `eval/scripts/test_generated_code.py`.
 2. Sandbox image must contain `h5py` + `scicode @ git+https://github.com/scicode-bench/SciCode.git@<pin>` (+ `git` in python:3.12-slim for pip-git). Image tag carries the fix epoch: `frank-bench-py:3.12-scicode1`.
 3. Official extractor `get_function_from_code` `exec`s raw submission text → markdown fences are guaranteed SyntaxError. Official pipelines store CLEAN code: strip fences (`stripFences()`: join all ``` blocks) before extraction, for submissions AND prior-step context.
 4. Gold CODE ships only for the dev split (50 steps) on HF `AI-SCODE/SciCode`; `problems_test.jsonl` gold=None; GitHub pinned tree ships no gold jsonl; scicode pip package ships no data. Leaderboard (AA) SciCode uses reference-solution context — compare only against the gold-context slice, never the self-cumulative test split.
 5. Quarantine poisoned ledgers to `.AGENTTRASH/` (never blend void rows into reports), reset `runs/queue.json` to `{"active": null, "runs": []}` (active must be `null`, not `""`).
 # Verification gates
 - Real-infra proof: `FIB_INTEGRATION=1 bun test tests/integration.test.ts` (gold solution must PASS official protocol; `process_hdf5_to_tuple("77.1", 3)` → 3 targets). Integration files must `delete process.env.DRY_RUN` and point `FIB_DATA_CACHE` at the real cache (preload isolates it to TMP fixtures).
 - After a protocol fix, fresh live run must show mixed PASS/FAIL with model-side-only signatures before any score is reported.
@@ -0,0 +1,30 @@
 ---
 name: llm-endpoint-behavior-battery-a-b
 description: "A/B two boots of a live OpenAI-compatible LLM endpoint (payload swap trial) with one identical behavior+throughput battery: refusals, thinking-token census, tools, vision, needle, decode/prefill rates."
 ---
 Run the SAME battery against both boots of an endpoint swap (candidate vs shipped payload). Never compare across different prompts, never benchmark beside the live service (stop + mask first), never measure the first request.
 ## Harness
 `/tmp/halogen-eval/battery.py <tag> [all|tail]` (stdlib only, `urllib`): appends one JSON line per probe to `/tmp/halogen-eval/battery-<tag>.jsonl`, summary to stderr. `tail` = long-context + throughput only. Stage assets next to it: a corpus text file, a base64 512 px solid-color PNG.
 Probe order (each is a gate, all comparable across boots):
 1. **warmup** — discarded. First request after boot is a graph-capture artifact (measured 3x spread: 2.6 vs 1258 t/s prefill).
 2. **sanity** — exact-answer arithmetic, `temperature=0`.
 3. **refusals** — 5 hostile prompts, count refusal-marker regex hits. The abliteration/base-alignment census.
 4. **thinking census** — 6 fixed questions, `temperature=1.0`, `max_tokens=4096`; report mean `usage.completion_tokens` + per-item. A removed instruction fine-tune shows here first (measured: mean 784 vs the card's 3271 for the base model).
 5. **tools** — 1-turn (named-arg `tool_calls`) then 2-turn (tool result → answer).
 6. **vision** — OpenAI `image_url` content part only (legacy top-level `images` is silently ignored); solid color, expect the exact word; budget >=512 tokens or thinking eats it and empty `content` + `finish_reason=length` reads as blindness.
 7. **needle** at planted depth 0.85 and 0.10 of a token-budgeted haystack.
 8. **decode** — greedy, `max_tokens=512`, long-form prompt: `completion_tokens/secs`.
 9. **prefill** — one ~58k-token prompt twice: pass 1 cold, pass 2 cached; the ratio is the prompt-cache proof (measured 136x warm, 1.4x when already cached).
 ## Laws that bite
 - **Token-budget every prompt by measurement, never chars/4.** Measure chars/token on the actual corpus (`prompt_tokens` of one probe ÷ its char count; wikitext-2 ≈ 4.33 for a HF-tokenizer Qwen-class model — chars/4 under-bills ~8 %). Over-window prompts come back HTTP 400 whose message names the exact token count and the ceiling — treat that as ground truth, it is the cheapest tokenizer oracle available.
 - **Corpus splitting:** check the separator before trusting a paragraph budget. Wikitext-2 raw blocks separate with `"\n \n"`, and a naive parquet→text dump joins rows with a SINGLE newline: a `"\n\n"`/blank-line split then returns ONE paragraph = the whole file, so every budget silently becomes "everything". Verify with `text.count("\n\n")` and the split's part count before running.
 - **Catch `HTTPError` in the POST helper and record the body.** A 400 is a probe result, not a crash — otherwise the battery dies mid-run and you re-run the whole thing against a live GPU.
 - **Report decode from a quiet host.** The same shape measured 25.6 / 37.9 / 46.8 t/s while a 62 GB download hammered page cache; only the idle-host number is real.
 - **Server-side samplers exist.** If the endpoint pins temperature/top_p/top_k, omit `temperature` for the thinking census (match production) and pin `temperature=0` only for exact-answer probes.
 ## Verdict framing
 Behavior gates (sanity/refusals/tools/vision/needle) are the contract; PPL/KL from the engine's own checkpoint tools is advisory; throughput deltas under ~5 % are noise unless a mechanical control (a prompt shorter than the knob under test) proves the knob was the only variable.
@@ -0,0 +1,35 @@
 ---
 name: model-runtime-support-survey
 description: "Survey how every open-source runtime serves a given LLM (vLLM, llama.cpp, SGLang, KTransformers, overlays, vendor GGUFs) before writing a serving/feasibility plan; harvest quant recipes, measured rates, and mapped landmines from PR comments and overlay repos."
 ---
 # Model Runtime Support Survey
 Answer "how do other engines run model X, and what did they pay to learn it?" before committing a bring-up plan. Every kernel spec, quant recipe, and landmine found upstream is one you don't pay for twice. Proven on GLM-5.3-Flash (2026-10-14): surfaced a production 8xR9700 vLLM overlay, MTP 2.3x decode numbers, and 4 landmines (fp8-KV scale calibration, prefix-cache 0-hits, KDA autotune nondeterminism, chat-template notation).
 ## Harvest order
 1. **Official model card** (`huggingface.co/<org>/<model>`) — the "Serve Locally" section lists officially supported runtimes; sampling/template contract lives here (e.g. `reasoning_effort` defaults, `clear_thinking`).
 2. **Per-runtime PRs** (vLLM, llama.cpp, SGLang) — fetch via the GitHub-API-backed read; **the comments, not the body, are the payload**: field reports (prefix-cache hit censuses, ROCm/AMD enablement branches, extension rebuild recipes, crash repros, free tuning levers via `--override-kv`, nondeterminism root-causes). Get the PR status (merged/open/closed) — it sets what "master supports" means.
 3. **Overlay/serving repos on HF** (search model name + your GPU family, e.g. `rocm-r9700`): read the tree (`huggingface.co/api/models/<repo>/tree/main`), then `raw/main/README.md`, `raw/main/OVERLAY_NOTES.md`, `raw/main/run-*.sh`. Launch scripts carry the laws in comments (KV sizing justifications, env ladders, dead knobs).
 4. **Vendor GGUF guides** (Unsloth docs): append `.md` to the docs URL for clean markdown; gives quant KLD/top-1 tables, template fixes, hardware floors. Check whether their GGUF carries MTP/nextn tensors — that's often the only public source of draft-head weights.
 5. **KTransformers tutorials** (`raw.githubusercontent.com/kvcache-ai/ktransformers/main/doc/en/kt-kernel/<Model>-Tutorial.md`) + **SGLang cookbook** (`docs.sglang.io/.../<Model>.md`): CPU-offload expert shape validation, 1M-ctx recipes.
 ## Harvest checklist (per runtime)
 - Measured decode/prefill + hardware shape (cards, TP) — anchor, not decoration; per-card effective GB/s is the cross-engine comparison unit.
 - Quant recipe: bits-per-weight split by module class (experts/trunk/embed) — convergent recipes cross-validate your planned conversion.
 - Spec-decode: acceptance length, per-position accept, when it pays (CPU-offload) vs loses (VRAM-resident).
 - Landmines: KV-scale calibration reading uninitialized linear-attn state; prefix-cache semantics on hybrid KDA/DSA models; kernel autotune nondeterminism (KLD across launches); fp8 flavour bugs (FNUZ vs e4m3fn scale); template notation engines can't parse; import gates per gfx/arch.
 - Harness contract: reasoning-effort defaults (16k+ hidden thinking tokens), sampling params, tool/reasoning parser names.
 ## Output
 A runtime matrix table (engine | arch status | hardware | artifact | measured) + a numbered "laws we inherit" list; fold every law into the plan's phases and risks with § cross-refs.
 ## Gotchas
 - Read PR **comments** — the highest-value data (crash repros, censuses) is comment-only.
 - HF fetches: `api/models/<repo>/tree/main` for listing, `raw/main/<path>` for files; the HTML card view renders README inline too.
 - `browser.open` targets the harness's headless browser, not the user's — refresh user-facing pages with `xdg-open`.
 - Companion skill for the artifact side: `radiance-model-feasibility-scout` (GGUF header census).
@@ -0,0 +1,48 @@
 ---
 name: monolith-split-under-dist-pin
 description: "Use when cutting a monolithic source file into modules behind a black-box test suite whose committed build artifact (dist) must stay byte-identical to src; one verified commit per cut, red-proof against the previous bundle. Not for feature work or doc-only edits."
 ---
 # Monolith split under a committed-bundle pin
 Procedure that landed a 1354-line `index.ts` as 9 modules + 301 lines of wiring across 9 commits with zero red commits. Assumes: black-box test suite (tests drive the built bundle, not internals) and a pin test asserting the committed `dist/` equals a fresh build of `src/`.
 ## Per-cut loop (one commit per cut, always in this order)
 1. `bun run build` (or project equivalent) **before** staging — commit `dist/` in the same commit as the moved `src/`, otherwise the pin test fails ("committed dist is byte-identical to a fresh build") and you must amend. Amending is fine only while the branch is unpushed.
 2. `tsc --noEmit`, then run the full suite async (`bats tests/ > /tmp/x.log 2>&1; grep -E '^1\.\.'`).
 3. **Never write to `src/` while the suite runs.** `setup()` rebuilds the bundle from `src/`, so a concurrent edit attributes someone else's half-written state to your run. Read-only prep (planning the next cut's exact line ranges) is the correct thing to do while waiting.
 4. Gate green → next cut. Gate red → fix, rebuild, amend, re-gate.
 ## Cutting mechanics
 - Cut leaf/pure modules first (grammar, transcript rules, URL resolution, pure segmenter), then stateful ones (config, IO, pipeline, UI). Never let a module import `index` — if the new module needs something from `index`, that thing is a leaf and must move too (this is what forced `segment.ts` out early).
 - Extract in **verbatim** bodies: read the exact ranges, write them into the new file, then delete the same ranges. Only module docs, export keywords, and injected dependencies change. Keeps each commit reviewable as a move.
 - Edit tools that require "displayed lines" from the latest read snapshot: re-read the exact ranges under the current tag, then issue one edit call with all ops listed **bottom-up** (original line numbers throughout). Adjacent ranges merge into one `CUT a=b`; leaving a doubled blank line is the usual scar — one extra `CUT` next turn.
 - Mutable config must reach a long-lived object as **getters**, not a construction-time snapshot: menu handlers mutate `cfg` after construction, and a snapshot freezes the settings the UI exists to change.
 - After moving code, grep the old file for the moved names: stale call sites compile under bundlers that skip typechecking (`stop()` vs `speaker.stop()` was caught only by `tsc`, not by `bun build`).
 ## Proving a new assertion is red-capable (before trusting it green)
 Build the old bundle and point the test harness at it — no stash, no worktree juggling:
 ```bash
 git show HEAD:dist/index.js > /tmp/old-dist.js   # bundle is self-contained
 # rebuild the throwaway harness by extracting the driver the suite writes
 sed -n "<heredoc-body-range>p" tests/behavior.bats > "$W/driver.ts"
 DV_EXT=/tmp/old-dist.js <same env as the test> bun "$W/driver.ts" <scenario>   # expect RED
 DV_EXT="$PWD/dist/index.js" <same env> bun "$W/driver.ts" <scenario>           # expect GREEN
 ```
 Copy the project's real player/server stub verbatim — a simplified stub (e.g. one that skips writing the log file the driver counts) prints a false `PLAYS 0` and looks like a failing fix. Pin the scratch dir to a fixed path; `ls -dt /tmp/tmp.*` picks up another session's directory.
 ## Black-box test hygiene learned the hard way
 - A test that counts artifacts in the **shared** temp directory observes every other process on the box (live agent sessions synthesize into the same `dankvoice-*` dirs). Give the run a private `TMPDIR="$WORK/scratch-tmp"` and assert there; the assertion's sensitivity is proven by the fact it caught a real leftover while scoped globally.
 - Let preseeds reference the ephemeral fixture port with a placeholder (`__PORT__`) substituted by the driver, so a test can preseed a URL pointing at its own fixture server.
 - Refactor-only commits get **no new test**: re-asserting unchanged labels/order after a commit whose point is that they are unchanged is a tautology; the existing suite is the gate. New tests belong to behavior changes, red-first.
 - Tests must observe **output**, never internals: assert `PLAYS`/`CALLS`/`CALL <url>`/`NOTIFY <text>`, not that a variable was set.
 ## Docs after a split (same branch, own commit)
 Move each explanation to the file that now owns it (knob list → the module that reads env; state-machine prose → the module that implements it) and leave the entry point a one-line-per-module map. Then grep for pointers into the old file — a README saying "see header of `src/index.ts`" becomes a lie the moment the knobs move.
@@ -0,0 +1,44 @@
 ---
 name: niri-all-monitor-screenshot-fix
 description: "Fix flameshot screenshot failures on niri with 2+ outputs: confirm portal outputs.len()==1 census, retire flameshot binds for niri-native equivalents, absolute script paths (niri spawn-sh PATH lacks ~/.local/bin)"
 ---
 # Niri all-monitor screenshot fix (flameshot retirement)
 ## Symptom fingerprints
 - "Bunch of flameshot errors after a delay" when docked (2+ outputs); fine on one output.
 - Journal census (ground truth): `journalctl --user -u niri --since today | grep -i screenshot`
  - FAIL: `WARN niri::niri: error taking a screenshot: Condition failed: outputs.len() == 1 (2 vs 1)` — one press of flameshot full emits 3 WARNs (composited screen + per-output portal requests).
  - SUCCESS: `DEBUG niri::niri: saving screenshot to ...` — per-file lines.
 - Timeline: count WARNs before/after a config reload to attribute presses to config states.
 ## Root cause
 Flameshot 14 on Wayland captures via xdg-desktop-portal → xdg-desktop-portal-gnome → niri's GNOME-Screenshot compatibility D-Bus API → `screenshot_all_outputs` → `ensure!(outputs.len() == 1)` (FIXME upstream). Upstream: niri#4313 (closed duplicate, unfixed in 26.04/8ed0da4), flameshot#4449.
 - NOT just `full`: live-verified docked, `flameshot full` AND `flameshot screen` both hang ~15 s (exit 124 under timeout), write no file. Assume ALL flameshot capture modes dead with 2+ outputs.
 ## Fix: retire flameshot binds; niri-native replacements (blankpad layout)
 | Chord | Action |
 |---|---|
 | Print / Ctrl+Shift+1 / Mod+Shift+S | `spawn-sh "/home/blank/.omp/scripts/screenshot-desk.sh"` — per-monitor PNGs |
 | Alt+Print / Ctrl+Shift+2 | `screenshot-screen;` — focused monitor → screenshot-path + clipboard |
 | Ctrl+Print / Ctrl+Shift+3 | `screenshot;` — interactive UI (Space saves, Esc cancels; single-output selection by design) |
 - Misc: `screenshot-path "~/Pictures/Screenshots/Screenshot from %Y-%m-%d %H-%M-%S.png"` at CONFIG ROOT (it is `config.screenshot_path`; a KDL `output { }` block REQUIRES a name arg — bare `output {}` is a parse error).
 - KDL comments are `//`, never `#` (parses as identifiers → cryptic "identifiers cannot be used as arguments").
 - niri 26.04 screenshot UI: "allows only single-output selections for now" (src/ui/screenshot_ui.rs) — no built-in all-monitor composite; script needed.
 ## All-monitor script (scripts/screenshot-desk.sh)
 Per active output (`niri msg --json outputs | jq -r .[].name`): `niri msg action focus-monitor <m>` → sleep 0.15 → `niri msg action screenshot-screen --path "<abs>/… <connector>.png"` → restore prior focused monitor (`niri msg --json focused-output | jq -r .name`). No grim, no portal. `--path` must be absolute.
 ## THE SPAWN-SH PATH TRAP
 niri's spawn-sh PATH = system dirs only; `~/.local/bin` ABSENT. Proof:
 `tr '\0' '\n' < /proc/$(pgrep -x niri | head -1)/environ | grep ^PATH`
 → any bare user-script name in a keybind fails SILENTLY (no journal error, no file). Rule: keybinds use absolute script paths (`/home/blank/.omp/scripts/...`). Audit existing binds for bare names (desk.sh was dead too).
 ## Verifying a keybind end-to-end without a keyboard
 Reproduce niri's child env exactly:
 `env -i PATH=/usr/local/sbin:/usr/local/bin:/usr/bin:/usr/bin/site_perl:/usr/bin/vendor_perl:/usr/bin/core_perl HOME=$HOME USER=$USER LOGNAME=$LOGNAME XDG_RUNTIME_DIR=/run/user/$(id -u) WAYLAND_DISPLAY=wayland-1 NIRI_SOCKET=/run/user/$(id -u)/niri.$WAYLAND_DISPLAY.$(pgrep -x niri | head -1).sock sh -c "/abs/path/script"`
 NIRI_SOCKET is NOT in niri's own environ (it is set on niri's children); socket path convention: `$XDG_RUNTIME_DIR/niri.<wl-display>.<niri-pid>.sock`.
 ## Deploy mechanics (blankpad command-center)
 Live niri config = symlinks into the ~/.omp main checkout ("the checkout is the deployment"). Merge to main → niri auto-reloads (~1 s later journal `DEBUG niri_config: loaded config from ...`); verify that DEBUG line as the reload proof. Manual fallback: Mod+Shift+/. `niri msg` has NO keybinds subcommand — keybind proof = overlay (Mod+Shift+Escape) + journal census.
@@ -0,0 +1,43 @@
 ---
 name: niri-config-edit-validate
 description: "Locate, edit, validate, and commit niri compositor config on Frank's workstations: desk/display profiles, EDID-keyed outputs, layout, keybind grepping, dotfiles mirror, noctalia.kdl last-include color override, forced hot-reload."
 ---
 # Editing niri config on Dank workstations
 ## Layout of the config
 - Live config: `~/.config/niri/config.kdl` is a thin file of `include "./cfg/*.kdl"` lines. **Never conclude "not bound" from grepping only `config.kdl`** — keybinds live in `cfg/keybinds.kdl`, rules in `cfg/rules.kdl`, layout in `cfg/layout.kdl`, etc. Grep `~/.config/niri/cfg/` recursively.
 - **Include order wins:** `config.kdl` ends with `include "noctalia.kdl"` — a hand-written accent overlay at `~/.config/niri/noctalia.kdl` that re-declares `layout { focus-ring/border/tab-indicator/insert-hint }` + `recent-windows.highlight` colors and BEATS every `cfg/layout.kdl` color edit (observed 2026-10-18: focus-ring color edits to layout.kdl appeared to "not reload" while this file silently repainted them red). Before changing any accent/outline color, grep the WHOLE `~/.config/niri/` tree (not just `cfg/`) for the property and fix the LAST includer. Tracked in repo at `dotfiles/zz-blankpad/niri/.config/niri/noctalia.kdl`; live file is NOT a symlink — sync by `cp` and `diff` like the rest.
 - niri notation: `Mod` = Super/Win key. Chords like `Mod+R { switch-preset-column-width; }`.
 - `~/.config/niri` is a REAL directory, not a symlink; the version-controlled copies are a partial mirror under `~/.omp/dotfiles/zz-blankpad/niri/.config/niri/`. Trees can drift: diff them before/after edits. (Hardlink wiring is FRAGILE — editor/agent atomic-rename writes silently break hardlinks; verify live↔mirror by CONTENT diff, never by link trust.) On blankpad the `cfg/*.kdl` entries are symlinks into the repo (`dotfiles/niri/...` base + `zz-blankpad` overrides) — edit through them freely; `noctalia.kdl` and `config.kdl` are the plain-file exceptions.
 ## Desk/display profiles (monitor arrangement)
 - Profiles: `cfg/desk-<n>-<name>.kdl` (e.g. `desk-1-home.kdl`, `desk-2-portable.kdl`); ACTIVE profile is symlinked as `cfg/display.kdl` — `readlink` it to know which. `scripts/desk.sh` manages switching; `desk.sh capture` prints connected outputs' EDID long names.
 - Panels are keyed by **EDID long name** (`output "Lenovo Group Limited 0x40A9 Unknown"` = the laptop eDP-1 panel), not connector — connector names reshuffle between desks. Long-name blocks BEAT connector-keyed blocks when both match one output (legacy connector blocks like `output "eDP-1"` linger as duplicates; niri applies the EDID block's `position`).
 - Position math: x,y = top-left of each output in the logical layout; right edge = x + mode width. To place panel A left of panel B: `A.x = B.x - A.width`; bottom-align: `A.y = B.y + (B.height - A.height)`.
 - Verify: `niri validate` → hot-reload → `niri msg outputs | grep -iE 'Output |Position'` (prints `Logical position: x, y`).
 ## Schema gotchas (niri 26.04)
 - `preset-column-widths` AND `preset-window-heights` are children of `layout { }` as SIBLING blocks — wiki wording misleads; nesting or `window-rule` placement fails `niri validate` with `expected one of proportion, fixed` / `unexpected node`.
 - Preset list order = cycle order for `Mod+R` (`switch-preset-column-width`); `Mod+Shift+R` cycles backwards. WITH custom preset lists the cycle contains ONLY the configured presets — no implicit full/maximize tail (verified: [0.25, 0.5] cycles period 2). Maximize = separate `Mod+F` `maximize-column`. Built-in defaults without the node: 1/3, 1/2, 2/3.
 - WITHOUT `preset-window-heights`, `switch-preset-window-height` FALLS BACK to the width presets — user sees width-fractions as heights; define the node explicitly to stop it.
 - Ground truth for node placement: the binary's embedded template — `grep -a -B4 -A8 "preset-column-widths {" $(which niri)`.
 - Window outlines: base geometry (`width`, `off`) lives in `cfg/layout.kdl` `focus-ring`/`border`; COLORS effectively live in `noctalia.kdl` (see include-order law). `border { off }` + focus-ring active = the visible outline. Frank's look since 2026-10-18: amber-orange `#ff8c00`, width 4 (`active`+`urgent` in noctalia.kdl; tab-indicator/insert-hint/recent-windows stay red `#f43841` by choice).
 ## Workflow
 1. Edit the live file under `~/.config/niri/cfg/` (symlinked = repo file; except `noctalia.kdl`, edit live then `cp` to mirror).
 2. `niri validate` (exit 0 + "config is valid") — mandatory before done.
 3. **Hot-reload is NOT reliable after harness edits** (atomic-rename writes are missed by niri's watcher; user then tests against the OLD config and reports "no change"). ALWAYS follow with `niri msg action load-config-file` (NOT `reload-config`).
 4. Sync changed file into the mirror: `cp ~/.config/niri/cfg/<f>.kdl ~/.omp/dotfiles/zz-blankpad/niri/.config/niri/cfg/<f>.kdl` (repo root is `~/.omp`, branch `main`, remote = dankclaw Gitea `dank/command-center`; push there is pre-authorized). Verify by `diff`, not by cp success.
 5. Untracked mirror files: `config.kdl`, `noctalia.kdl`, `animation.kdl`, `input.kdl`, `display.kdl` (symlink target) — flag drift, don't silently add; when a live-only file turns out to be load-bearing (like `noctalia.kdl` was), commit the first durable copy into `dotfiles/zz-blankpad/niri/.config/niri/`.
 6. Mirror files often carry pre-existing uncommitted drift (desk.sh captures); a commit of your edit folds it in — say so in the report/commit body.
 ## Live-behavior verification without disturbing Frank's windows
 - `niri msg --json <subcmd>` — the `--json` flag goes BEFORE the subcmd.
 - Targeting differs per action: WINDOW-scoped actions take `--id <window-id>` (NOT `--window`) — e.g. `switch-preset-window-height --id N`. COLUMN-scoped actions (`switch-preset-column-width`, `set-column-width`, `maximize-column`) have NO id — they hit the FOCUSED column; only `set-column-width <px|±N%>` positional CHANGE, no flags.
 - Spawned test apps do NOT reliably take focus, so blind `spawn + action` cycles resize whatever Frank is looking at. For column actions you must `focus-window --id N` first — and that STEALS focus; if Frank is actively testing chords, your probes and his keystrokes interleave and corrupt both. STOP probing, deliver config + validate, and have him press the chord himself.
 - `niri msg --json focused-window` can report a different window than assumed (focus moves); for per-window measurement read `niri msg --json windows` and filter by `id`. Present height of proportion p with gaps g over work-area H renders ≈ p*(H+g) − g. NOTE (measured 2026-10-18): this build's `windows`/`focused-window` JSON returns `x/y/width/height = null` — pixel-sampling the outline color from screenshots is not viable; ask Frank to eyeball after `load-config-file` instead of burning turns on capture forensics.
 - If Frank reports "still seeing old values" after a config edit: run `load-config-file` first, then verify empirically before believing anything else — and check `noctalia.kdl` include-order override BEFORE suspecting the reload.
 ## "What does chord X do?" triage
 For "mod+<key>" questions, check in order: `~/.config/niri/cfg/keybinds.kdl` (compositor wins first), terminal configs (`~/.config/ghostty`, `foot`, `kitty`), tmux, then omp TUI chords (`omp://keybindings.md`; modifiers are ctrl/shift/alt/super only, no `Mod`; `Ctrl+R`=history search, `Alt+R`=app.retry).
@@ -0,0 +1,43 @@
 ---
 name: niri-multi-monitor-screenshot-capture
 description: Diagnose flameshot screenshot failures on niri with 2+ outputs (portal single-output limit) and capture all monitors via niri-native per-output actions
 ---
 # Niri multi-monitor screenshot capture
 Flameshot works on a single niri output, dies the moment a second output connects. Diagnose via compositor journal, capture full desk with niri-native per-output actions — not grim, not portal.
 ## Diagnose (one pass)
 1. `journalctl --user -u niri --since today | grep -i screenshot`
   - `WARN niri::niri: error taking a screenshot: Condition failed: outputs.len() == 1 (2 vs 1)` → flameshot's portal path (xdg-desktop-portal-gnome → niri GNOME-Screenshot D-Bus → `screenshot_all_outputs` `ensure!(outputs.len()==1)`). Upstream niri#4313, unfixed in 26.04. Symptoms: error bubbles appearing **after a delay** (portal round-trip), count = number of hotkey presses.
 2. `niri msg outputs` — count active outputs. 1 output = flameshot fine; the bug is dock-state-dependent (portable works, docked breaks).
 3. Per-mode status: `flameshot screen` (focused output) works docked; `flameshot gui` region works (mixed-res scaling bug = flameshot#4449); `flameshot full` dead on 2+.
 ## Capture all monitors (niri-native)
 niri 26.04 has NO all-output capture: screenshot UI is single-output by design (`screenshot_ui.rs`: "allows only single-output selections for now"); D-Bus path hard-limited. Script pattern:
 ```bash
 prev=$(niri msg --json focused-output | jq -r .name)
 while IFS= read -r mon; do
  [ "$mon" != "$prev" ] && niri msg action focus-monitor "$mon"
  sleep 0.15                       # let compositor render a frame after focus move
  niri msg action screenshot-screen --path "$out/Screenshot from $ts $mon.png"
 done < <(niri msg --json outputs | jq -r '.[].name')
 # restore focus: niri msg action focus-monitor "$prev"
 ```
 CLI facts (`niri msg action screenshot-screen --help`): `--path` must be ABSOLUTE; `-d/--write-to-disk` default true (also saves per `screenshot-path`); `-p/--show-pointer` default true.
 ## KDL gotchas (bit me twice; bats `niri validate` catches them)
 - KDL line comments are `//`, NEVER `#` — `#` = parse storm "identifiers cannot be used as arguments".
 - `screenshot-path` is a ROOT-level config node (`config.screenshot_path` in config.rs); do NOT nest it in `output {}` — root-level bare node validates and works; `output { ... }` without a name/match arg fails: "additional argument `name` is required".
 - Root-level `prefer-no-csd` is a silent no-op (output-section property) — root unknown nodes only warn.
 ## Verify
 - Run the script live; `file` each PNG (valid dimensions per monitor); `niri msg --json focused-output` equals pre-run monitor.
 - `bats tests/` incl. niri-config assembly validate on every desk profile before commit.
 - Deploy: symlink script into `~/.local/bin` (repo `scripts/` convention, like `desk.sh`); bind `spawn-sh "name"` in keybinds.kdl; niri hot-reloads config on file change.
@@ -1,27 +1,52 @@
 ---
 name: noctalia-bar-layout-edit
-description: "Edit/verify Noctalia v5 bar widget layout (start/center/end, taskbar workspace grouping) on Frank's symlinked dotfiles workstations"
+description: "Edit/verify Noctalia v5 bar layout and clock widgets (multi-timezone instances, capsule groups); GUI-repo propagation chain, settings.toml symlink audit, and stash-clobber recovery on Frank's dotfiles workstations"
 ---
 # Noctalia v5 bar layout edit
 Bar widget layout on Frank's noctalia v5 workstations is GUI-override state, not config.toml.
 ## Where
- Layout file: `~/.local/state/noctalia/settings.toml` → `[bar.<name>]` keys `start` / `center` / `end` (arrays of widget ids; `[widget.<id>]` subtables hold per-widget settings).
+- Layout file: `~/.local/state/noctalia/settings.toml` -> `[bar.<name>]` keys `start` / `center` / `end` (arrays of widget ids; `[widget.<id>]` subtables hold per-widget settings).
- On Frank's boxes this file is a **symlink into the command-center repo** (e.g. `~/.omp/dotfiles/noctalia/.local/state/noctalia/settings.toml`) — edit the repo file, not the link path (atomic-rename writes through the link path would replace the symlink).
+- On Frank's boxes this file MUST be a **symlink into the command-center repo** (e.g. `~/.omp/dotfiles/noctalia/.local/state/noctalia/settings.toml`) - edit the repo file, not the link path (atomic-rename writes through the link path would replace the symlink).
 - Layer order: built-in defaults < `~/.config/noctalia/config.toml` (+`[include]`) < `settings.toml` (wins). Noctalia writes through symlinks and keeps them.
- Defaults when a key is absent: `start = ["launcher","wallpaper","workspaces"]`, `center = ["clock"]`.
+- Defaults when a key is absent: `start = ["launcher","wallpaper","workspaces"]`, `center = ["clock"]`, `end = ["notifications","clipboard","network","bluetooth","tray","battery","session","control-center","clock"]`.
-## Apply/verify loop (no restart, no reload IPC)
+## Clobber window and recovery (2026-10-18 incident law)
-1. Edit the repo `settings.toml`.
+- GUI-built layout is **working-tree-only until the hourly live-sync heartbeat commits it**. A merge/sync session that "clears the dirty tree" can `git stash` those edits, and later stash operations can destroy the entries - customizations then vanish from the live bar with the repo copy stale.
-2. `noctalia config validate` (checks merged layers; also `noctalia config export [full] | yq -p toml` to inspect effective values).
+- Never blame the GUI or noctalia first: diff live file vs `HEAD`, check heartbeat commits (`git log -- dotfiles/noctalia/.local/state/noctalia/settings.toml`), then the stash chain.
-3. Both layers are file-watched → hot-reload. Prove visually: `noctalia msg screenshot-fullscreen` saves a PNG to `~/Pictures`; read the image and inspect the bar.
+- Destroyed stashes are recoverable: `git fsck --lost-found` lists dangling commits; `git show <dangling>:dotfiles/noctalia/.local/state/noctalia/settings.toml` dumps each candidate; pick by `[bar.default]` richness (capsule groups, extra clock instances). Validate a candidate in a sandboxed `XDG_*_HOME` before touching the live file.
 - After recovery, commit the file immediately so the window closes.
-## Taskbar recipes
+## Widgets (v5 census, verified 2026-10-17)
- Move window indicator beside workspaces: put `"taskbar"` in `start` after `"workspaces"`.
+- Full roster in `settings.toml` widget_order plus docs: activity, backlinks, battery, bluetooth, brief, bright, cat, cheatsheet, chart, clipby, clipboard, control-center, cpu, controls, cava (now playing), disk, gpu, help, keyboard, language, launcher, mediaplayer, memory, mic, network, night-light, noctalia-palette, notification-history, notifications, niri-colors, power-section, power-profile, screenrecord, scratchpad, screenshot, session, shell (custom shell command), slowouts, slowouts-visible (per-output bar assignment), speedtest, swayosd-*, taskbar, tray, voiceline, volume, wallpaper, weather, workspaces.
- Combine workspaces+windows into ONE widget: `[widget.taskbar] group_by_workspace = true` — per-workspace capsules with disc labels (focused/occupied/empty/urgent colors); `workspace_group_content = "icons"|"count"|"dots"` (count/dots: left-click activates the workspace); `hide_empty_workspaces`, `show_workspace_label`, `minimal`, `workspace_label_placement = corner|centered|inside`. Requires compositor per-window workspace assignment (niri: yes; LabWC: no → stays flat).
+- `clock` widget: `format` (chrono strftime), `schema` (12/24), `multi_line`, `show_seconds`, `popup`, and **timezone** = IANA name. Multiple clock widget instances are supported: ids like `clock`, `clock-utc`, `clock-sea` each get a `[widget.<id>]` subtable -> one capsule per instance. This is how multi-timezone (Seattle work + UTC dev) lands: add `clock` + `clock-utc` to `end` (or `center`), set `timezone = "Etc/UTC"` on the utc one.
 - `cat` widget: shows random ASCII art, `rows` setting (4-10).
 - `shell` widget: `command`, `run interval` (seconds), `icon`, `terminal`; output lands in its capsule popup - can wrap any CLI (hyprstatus-style).
 - `taskbar` widget: shows window buttons **only on outputs where `niri-bridged` is enabled** (noctalia-launcher enables it). Buttons render **icon-only** (app icon from icon theme; fallback = first letter of title); the window title string is NOT shown in the bar. Hover tooltip carries title + app_name. Per-widget settings: `show_icons`, `show_actions`, `disable_middle_click`, `preferred_app_names` (map app_name -> icon for missing icons).
 - Widget ids usable in `[bar.*].start|center|end` are restricted to "bar widgets" (`is_bar_widget` allowlist in `bar.rs`); non-bar widget ids are silently dropped at load. `group:<id>` entries render capsule groups.
 - Capsule groups: `[bar.<name>.capsule_groups]` id = `["widget",...]`.
 - Niri layout law for bars: window width must stay **odd** (strut = (W-1)/2); bars reserve via layer-shell, niri's reserved area = layer surface size, so bar height changes need no niri edit.
 ## Bar styles (GUI-visible, settings.toml keys)
 - `[bar.*]`: `thickness`, `font_family`, `font_weight`, `font_size`, `opacity`, `border_width`, `border_offset`, `rounded`, `paddings`, `icon_ratio`, `follow_layout`, `output`, `exclusive`, `layer` (`bottom` = below window layer; `overlay` = above windows), `position` (`top`/`bottom`).
 - Per-monitor bars: add a `[bar.<name>]` with `output = "<monitor>"` and `follow_layout = true` (niri) -> per-workspace strut follows tall windows on that monitor. This is the mechanism for "bar shrinks when a window is tall" (the bar is a layer-shell strut, NOT a niri layer rule).
 - The GUI "Bar" page is the reference list; anything absent from settings.toml is a built-in default.
 ## Slowouts (window-height-aware bars/panels)
 - `slowouts` = hidden engine (not a bar capsule): `[slowouts]` keys `enabled`, `duration`, `easing`, `trigger_offset`; per-monitor `[slowouts.<monitor-name>]` overrides (e.g. `DP-1`) with the same keys plus `edge`.
 - `position = "top"` + `exclusive = false` + slowouts on the monitor -> panel hides when a window touches its edge, re-reveals otherwise. `slowouts-visible` = toggle capsule.
 - **Slowouts needs niri workspace-autoresize ON** (niri `workspace-autoresize` = "per-workspace" in cfg/layout.kdl `output ... { workspace-autoresize per-workspace }`): noctalia computes hide from workspace height < panel bottom edge; uniform-strut layouts never trigger it.
 - Per-output bars: slowouts config keys are monitor names, so one `[bar.<x>]` with `output` + `exclusive=false` + `layer=overlay` per slowout monitor is the supported shape.
 ## Layout modes and window title decorations
 - `[layout]`: `mode` (`tiling`|`floating`|`monocle`), `pseudotiled`, `focus_bar` (window-title bar at top, center, layer-shell; style via `[ui.controls...]`/bar-ish settings), `window_follows_cursor`, `gaps`, `border_width`, `rounded`, `blur`, `opacity`, `borderless_csd`, `show_native_decoration`.
 - `focus_bar` is the noctalia analog of niri's drawn window title, but ONE global bar (no per-window arrows). True per-window title tags = niri `draw-with-border` on window rules; noctalia adds no per-window decoration (it's a bar app + portal, composites nothing).
 - Floating mode: right-click desktop / `SUPER+Shift+F` / toggle widget; widgets `floating-directories`, `floating-files`, `pins` (sticky notes), `canvas`, `sketchpad`, `post-its`. Float windows snap to screen quarters (`SUPER+Ctrl+Alt+Arrows`) and tile into current layout (`SUPER+Shift+T`). `[layout.floating.files]` = icon/view/sort/preview size.
 - `[bar.*].window_display` = `disabled`|`icons`|`text`|`combined` - per-window chips in the bar strip (niri only; this is what niri-taskbar could not do). Values: `disabled`|`icons`|`centered`|`inside`. Requires compositor per-window workspace assignment (niri: yes; LabWC: no -> stays flat).
 - The `workspaces` widget itself has no window display; styles are regular/minimal/focus_hint only.
 ## Law
-Full widget/setting tables: https://docs.noctalia.dev/noctalia/bar/ and .../bar/widgets/<name>/ . Commit bar changes atomically to the command-center repo (checkout is the deployment).
+- Full widget/setting tables: https://docs.noctalia.dev/noctalia/bar/ and .../bar/widgets/<name>/ . Commit bar changes atomically to the command-center repo (checkout is the deployment).
 - **Ask before applying.** Frank asks "how do I X" questions about the live bar; answer with the exact snippet + file, apply ONLY on explicit go. A settings.toml edit is a live-deployment change, not a demo.
 - Git `M` on settings.toml usually carries noctalia's own runtime churn (wallpaper path, nightlight, panel positions) alongside your edit - mention it when committing.
 - Right after building layout in the GUI, commit settings.toml (or trigger `scripts/live-sync.sh`) before any branch/merge work: the uncommitted-GUI-edit window is exactly where the 2026-10-18 clobber happened.
@@ -0,0 +1,26 @@
 ---
 name: omp-bundle-claim-audit
 description: "Verify or discover omp TUI behavior facts from the minified dist/cli.js bundle, with live niri-screenshot matrix confirmation; use when auditing docs claims or answering \"how does omp actually do X\"."
 ---
 # omp bundle claim audit
 Ground omp behavior claims in `~/.bun/install/global/node_modules/@oh-my-pi/pi-coding-agent/dist/cli.js` (minified single line), not guesswork.
 ## Extraction
 - `grep -oE` too weak for long windows; use python: read whole file, `re.search(r'ANCHOR.{0,900}', s)` windows around stable anchors.
 - Reliable anchors: settings ids (`id:"statusLine.contextLine"`), renderer ids (`id:"path",render\(e\)\{`), registry arrays (`l9e=\[`, `Uxe=\{` preset table), descriptions (`"Label",description:"([^"]+)"`).
 - Minifier renames symbols per release — anchor on string literals, never on `#Xt`/`zG` names.
 - Enum values live in a var: find `id:"KEY"` → `values:VAR` → `re.search(r'VAR=\[[^\]]+\]')`.
 - Some segments are factory-generated (`VDt("token_in",...)`) — literal id scans miss them; check the catalog array (`l9e`) and preset tables for referenced ids.
 - Beware gallery/preview code faking production behavior (e.g. `N4r` synthesizes a status bar for the settings gallery) — confirm the window you cite is the production render path.
 ## Live confirmation (only where pixels decide)
 1. Edit `~/.omp/agent/config.yml` (file-watched, repaints without restart).
 2. `sleep 2 && niri msg action screenshot-screen --path /tmp/x.png --show-pointer false; sleep 1.5` (flag is `--path`, NOT `-o`; the write lands slightly late — sleep before PIL).
 3. Crop + 1.3x LANCZOS via PIL, `read` the crop.
 - Multi-window screens make bar crops ambiguous: prefer settling the question in code (the layout gate `layout!=="box"&&layout!=="band"` style booleans) over pixel forensics; scan rule rows by dominant-color spans only for single-color questions.
 - ALWAYS restore config edits afterwards (track exact line anchors; the edit tool demands a matching snapshot header).
 ## Audit output
 Correct false claims in-place, keep an "Audit log" section listing each ~~claim~~ → truth with code/live evidence; mirror corrections into `omp-docs/log.md`.
@@ -0,0 +1,38 @@
 ---
 name: omp-bundle-implementation-port
 description: "Extract and port a working implementation from omp's minified dist/cli.js bundle (copy-not-invent requests); anchors, python slicing, regex-constant sweep, trace-driven test prediction."
 ---
 # Porting built-in omp behavior out of the minified bundle
 Use when Frank says "copy the omp implementation / work off known-working code" — i.e. port a built-in feature (vocalizer segmentation, retry logic, formatting rules) into our own file instead of hand-rolling a heuristic. For merely *auditing behavior claims*, use `omp-bundle-claim-audit`; this skill is extraction-for-porting.
 Bundle: `~/.bun/install/global/node_modules/@oh-my-pi/pi-coding-agent/dist/cli.js` (minified; single-letter names, private `#x` fields survive).
 ## Extraction recipe
 1. **Find the setting/entry strings first.** `grep -o 'ce({id:"<area>[^"]*"[^}]\{0,200\}' cli.js` — setting descriptions state semantics verbatim (e.g. `speech.enhanced` = "Rewrite assistant output into natural spoken prose with the tiny/smol model"). Descriptions are quotable ground truth.
 2. **Anchor to code with a distinctive token**, not guesses: a method name (`pushDelta`), a state init, or a string. Then slice generously with python (bash heredoc), NOT grep -o which truncates:
   ```python
   src = open('cli.js').read()
   i = src.index('pushDelta'); print(src[i-1500:i+3000])
   ```
 3. **Follow the constructor**: pipeline classes instantiate collaborators there (`this.#t ??= new fHe` → `fHe` is the real worker; `#g()` returned `{speakable:new fHe, pending:[]…}`). Dump `class fHe{` +4000 chars.
 4. **Regex/helper sweep**: minified code declares shared constants in a trailing `var a,b,c,…` list and initializes them elsewhere (`Xyr=`, `Pwc=function`). Loop the names with `re.search(rf'{name}=', src)` and print ~400 chars each — the actual boundary/cleanup rules live in these one-liners.
 5. Write slices to `/tmp/*.txt` and `read` them; don't eyeball megabyte greps.
 ## Port rules
 - Rename fields/methods to readable names but keep logic **1:1** — the value is behavioral fidelity (Frank's "known-working set of code").
 - Private `#x` fields port cleanly: TS classes in Bun extensions support `#`.
 - Global-regex `.lastIndex=0` before each scan loop — minified code relies on it; keep it.
 ## Verification shortcut
 Before running tests, **hand-trace** each test input through the ported rules (boundary indices, state transitions) and predict exact segment counts/strings; then run — predicted-vs-actual mismatch localizes port errors faster than test output alone. Worked example (2026-10-19, dankvoice PR #26): traced `"First stop here. Second one goes!!! Really? Third ... done"` → predicted 3 segments incl. `"Third ... done"` merged via flush (10-char boundary < 24-char started-min) → bats green first run.
 ## Known anchors (2026-10-19 bundle)
 - Speak-aloud vocalizer pipeline: class `I6o` (gating on `speech.enabled`, suspend counter, enhancer, `#g()` per-message state).
 - Utterance segmenter: class `fHe` + helpers `Pwc` (line-head classify), `Iwc`/`_wc`/`b6o`/`w6o` (boundary search), `Cwc`+`y6o` (cleanup: links→label, URL→host, path→basename). Regex consts: `Xyr` sentence-end runs, `pHe` weak breaks, `mwc` abbreviations, `hwc` undecided line-heads, `g6o` horizontal rules.
 - Port already living in `agent/extensions/dankvoice.ts` (`SpeechSegmenter`) — when the bundle updates, re-extract `fHe` and diff against it before assuming our copy still matches.
@@ -0,0 +1,27 @@
 ---
 name: omp-context-file-discovery
 description: Where omp loads context/instruction files from (and why ancestor-directory AGENTS.md never loads) — the discovery map for scoping a rule to a set of projects; includes the before_agent_start cwd-gate pattern and quote-probe verification.
 ---
 # Scoping omp rules: context-file discovery map
 ## When
 Asked to make a rule apply "everywhere", "all repos", or "only projects under <dir>" in the omp harness.
 ## Discovery facts (bundle-verified 2026-10-18, omp v18.8.7, dist/cli.js)
 - Project context loaders are **first-hit at-or-below repo-root**: AGENTS.md walk-up stops with `if(dir===repoRoot)break`; the `.omp/`-dir provider (`EGs`) returns the single nearest dir containing `.omp` (skips home); CLAUDE.md provider loads one user file + one project file. **Consequence: an AGENTS.md placed in an ancestor directory like `~/Projects/` is never loaded by descendant repo sessions.** No ancestor-scope mechanism exists.
 - User/global slots: `~/.omp/agent/AGENTS.md` (user-level context, if present), `~/.omp/agent/APPEND_SYSTEM.md` (system-prompt append, project variant checked first, then user; broadcasts to ALL sessions — no path scoping), rules dirs `~/.agents|~/.agent` + `<ancestor>/.agents|/.agent` rules via walk-up (again repo-root bounded). Extensions load from `<settings-dir>/extensions/` — user-level = `~/.omp/agent/extensions/`.
 - Settings ids to grep for: `statusLine.*`, `composer.*`, `instructions` (= Copilot-style file-glob instructions package, not a path list).
 ## The only cwd-scoped mechanism
 `before_agent_start` extension handler: event carries `{prompt, images, systemPrompt}` (string | string[]); return `{systemPrompt}` to replace (handlers chain; undefined = untouched). Gate on `ctx.cwd.startsWith(target + "/")`. Constant appended text keeps prompt caching intact; subagents inherit the session cwd, so they get the rule too. Registering extensions under a git-tracked dir that omp also reads (e.g. command-center `agent/extensions/`) propagates them fleet-wide via git pull.
 ## Verification recipe (quote probe)
 Non-interactive one-shot from each side of the boundary, cheap model:
 `cd <in-scope-dir> && omp --model <alias> "Look at your system prompt. If it contains a heading starting with '<marker>', reply with exactly the text of its bullet about <x>. Otherwise reply exactly MISSING."`
 `--model @role` aliases do NOT resolve in one-shot; use a model alias like `frank-zealot`. Expect the verbatim bullet in scope, `MISSING` out of scope.
 ## Traps
 - A rejected implementation still needs its live copy unshipped (move to `.AGENTTRASH/`) — extension files in `agent/extensions/` take effect for new sessions immediately, merged or not.
 - Amend the changelog entry of the abandoned route to state closed-unmerged + the durable findings, so future agents don't resurrect it.
 - Prefer direct per-repo AGENTS.md edits when the operator wants auditability over mechanism (command-center 2026-10-18: extension route closed unmerged in favor of a PR in each target repo).
@@ -0,0 +1,40 @@
 ---
 name: omp-cwd-scoped-rules
 description: "Deliver a rule to omp sessions only under a directory subtree (e.g. ~/Projects/) — context-file loaders can't; use a before_agent_start extension + quote-probe verification."
 ---
 # Cwd-scoped rules for omp sessions
 ## Why context files fail for subtree scoping
 Verified against `@oh-my-pi/pi-coding-agent/dist/cli.js`: every context provider resolves **at or below the repo root** — the project walker breaks at `repoRoot`, `.omp/`-dir and CLAUDE.md/AGENTS.md providers load exactly one project file (first hit). A file in an ancestor dir like `~/Projects/AGENTS.md` is NEVER loaded by descendant repos. `agent/APPEND_SYSTEM.md` (user level, `gs()`=`Nn.agentDir`) loads for ALL sessions everywhere — broadcast, not scoped.
 ## Mechanism: before_agent_start extension
 File: `~/.omp/agent/extensions/<name>.js` (user-level load path is `<settings-dir>/extensions/`; in the command-center repo `agent/extensions/` is tracked and rides git pull to the fleet).
 ```js
 export default function (pi) {
  const ROOT = "/home/blank/Projects/";
  const RULES = "\n\n# <heading> ...";  // constant text -> prompt cache unaffected
  pi.on("before_agent_start", async (event, ctx) => {
    const cwd = (ctx && ctx.cwd) || "";
    if (cwd !== ROOT.slice(0, -1) && !cwd.startsWith(ROOT)) return; // undefined = untouched
    const base = event.systemPrompt;                                 // string | string[]
    return { systemPrompt: Array.isArray(base) ? [...base, RULES] : (base || "") + RULES };
  });
 }
 ```
 Contract (bundle-verified): handler payload `{prompt, images, systemPrompt}`; returning `{systemPrompt}` replaces the base; handlers chain; fires for subagent sessions too (shared cwd) — usually desired.
 ## Verification recipe (quote-the-prompt probe)
 No print flag; positional arg = one-shot. Role aliases (`--model @sonic`) do NOT resolve in one-shot — use a model id.
 ```bash
 P="If your system prompt contains a heading starting with '# <heading>', quote its <X> bullet; else reply exactly MISSING."
 cd /home/blank/Projects/<repo> && omp --model <id> "$P"   # expect verbatim bullet
 cd /tmp && omp --model <id> "$P"                          # expect MISSING
 ```
 Run both positive and negative probes; stderr swallows fast failures — keep 2>/dev/null off the first try.
 ## Gotchas
 - Declare precedence in the injected text if a repo's own AGENTS.md contradicts it (models see both).
 - A running session does not hot-load new extensions — only new sessions get them.
 - `~/.omp/agent/APPEND_SYSTEM.md` precedence: project-level file first, then user-level (first hit wins).
@@ -0,0 +1,73 @@
 ---
 name: omp-extension-event-probe
 description: "Prove which lifecycle events the omp harness actually dispatches to extensions, with a throwaway timestamping probe plugin, instead of inferring delivery from side effects."
 ---
 # Prove harness→extension event delivery with a probe plugin
 Use when an extension handler seems never to fire, or when you must know *when* an
 event arrives relative to another (mid-run vs settle). Never infer dispatch from
 the feature's side effects: async work in the handler (LLM rewrites, synthesis,
 network) lags seconds and destroys the timing signal.
 ## Shape (no build step needed)
 `/tmp/probe/package.json` — the installer validates the declared entry on disk:
 ```json
 {
  "name": "event-probe",
  "version": "0.0.0",
  "type": "module",
  "exports": "./index.js",
  "pi": { "extensions": ["./index.js"] }
 }
 ```
 `/tmp/probe/index.js` — append arrival times, not counts:
 ```js
 import { appendFileSync } from "node:fs";
 const LOG = "/tmp/probe.log";
 const stamp = (line) => appendFileSync(LOG, `${new Date().toISOString().slice(11, 23)} ${line}\n`);
 export default function probe(pi) {
  pi.on("agent_start", () => stamp("agent_start"));
  pi.on("turn_end", (e) => stamp(`turn_end turn=${e.turnIndex} toolResults=${(e.toolResults ?? []).length}`));
  pi.on("agent_end", (e) => stamp(`agent_end messages=${(e.messages ?? []).length} willContinue=${String(e.willContinue)}`));
 }
 ```
 ## Run
 1. `cd ~/.omp/plugins && omp plugin link /tmp/probe` (link, never edit
   `node_modules`), then `omp plugin doctor` → expect a `✔ plugin:event-probe` line.
 2. Launch a **fresh** TUI session in a pty (`omp --cwd /tmp/probe-run`, `pty: true`).
   Extensions load at startup only — an already-running session never sees the probe.
 3. PTY gotcha: input sent before the splash clears is swallowed. Read the screen
   first, then submit text and finish with a separate write containing a bare
   `\r` (LF alone left the text sitting in the composer).
 4. Drive a task with ≥2 tool rounds so turns and settles separate in time
   (sequential reads work and need no approval; ask for steps "strictly one
   after the other" or the model parallelises them into one turn).
 5. Wait for a terminal line with an async bounded loop (`grep -q agent_end`,
   `sleep 1` inside one backgrounded bash call) — never poll across turns.
 ## Read
 `turn_end` timestamps strictly earlier than `agent_end` ⇒ per-turn delivery
 works. `willContinue=true` on `agent_end` marks a non-terminal settle (harness
 maps `isTerminal === false` to it) — handlers that `return` on it never speak.
 ## Teardown (mandatory)
 `omp plugin uninstall event-probe`; `omp plugin doctor`; delete `/tmp/probe*`.
 The link writes into `~/.omp/plugins/package.json` (tracked, live tier) —
 uninstall restores it; confirm with `grep` for the probe name returning nothing.
 ## Ground truth read for free
 Event union + payloads: `~/.omp/plugins/node_modules/@oh-my-pi/pi-coding-agent/dist/types/extensibility/shared-events.d.ts`;
 the session→extension mapping lives in `src/extensibility/extensions/lifecycle-mirror.ts`
 (`extensionEventFromSessionEvent`). Extension-level `turn_end` carries
 `turnIndex`/`message`/`toolResults` but **no `willContinue`** — that field exists
 only on `agent_end`, so "is this the last turn" cannot be decided from `turn_end`.
@@ -0,0 +1,65 @@
 ---
 name: omp-extension-live-tui-verify
 description: "Verify an omp extension's slash commands and event hooks against a real TUI session: pty submit semantics, observable side-effect instrument, transient-toast trap, agent_end willContinue law, PipeWire output triage."
 ---
 Verify that a `.ts` file in `agent/extensions/` actually works inside the interactive TUI — the black-box bats seam cannot see harness-side wiring (event names, arg passing, mode gating), and it will pass beside a dead hook.
 Distinct from `omp-tui-live-visual-verify` (config/theme rendering proven by screenshot): here the instrument is **observable side effects**, not pixels, because extension notifications are transient toasts that vanish before the pty buffer is read.
 ## 1. Launch the exact build under test
 ```bash
 omp --no-extensions --no-session -e /abs/path/agent/extensions/<name>.ts
 ```
 as a **pty service** (`pty: true`, `ready: {"log": "╭|❯|Tip:|─", "timeout": 60}`).
 `--no-extensions` + explicit `-e` proves the file loads by path and nothing else interferes. Neutral cwd (`/tmp`) so repo state cannot color the run.
 ## 2. Submit input correctly (the costly gotcha)
 `write proc://<id>` with a trailing `\n` does **not** submit — the text just sits in the composer.
 - **Works:** two writes — first `"/cmd args"` (no terminator), then a **separate** write whose whole content is `\r`.
 - **Broken:** `"/cmd args\r"` in one write. It still submits, but the trailing `\r` arrives inside the command args. Symptom: `unknown voice 'narrator1\r'`, an unexpected extra utterance, or a chat message whose transcript line ends in a literal `\r`. That is a harness artifact — never "fix" it by stripping control characters in the extension (`.trim()` already covers what a keyboard can produce).
 ## 3. Instrument with a stub, never with ears or eyes
 Point the extension's player/handler at a script that appends evidence:
 ```bash
 #!/usr/bin/env bash
 echo "$1" >> /tmp/stub.log; cp "$1" "/tmp/out-$$.wav"; exit 0
 ```
 Run the TUI with that stub in the env the extension reads (`DANKVOICE_PLAYER=…` style). Then every assertion is a file: `wc -l` of the log (how many times it fired), `ffprobe -show_entries format=duration` (what it produced), `ls -d <tmp-glob>` (that cleanup ran).
 Sequence per behavior: command → CR → short `sleep` → count. **Count before and after** each command; the delta is the only honest proof a subcommand stayed silent.
 ## 4. Discriminate "fired twice" from "fired once per turn"
 Stray CR writes can create extra empty turns, each with its own `agent_end` — two utterances for one intended prompt is usually **two turns**, not a duplicate speak. Confirm by counting assistant turns in the transcript (`read proc://<id>`), and by matching each clip's duration to its own answer's length.
 ## 5. Event-hook contract traps
 - `agent_end` payload (`dist/types/extensibility/shared-events.d.ts`): `{ type, messages: AgentMessage[], willContinue? }`. **`willContinue: true` means the harness already scheduled a continuation** (auto-retry / empty-stop retry) — a subscriber that narrates or notifies there speaks an answer the model is about to redo. Gate on it.
 - Read the real event/payload shape from `~/.bun/install/global/node_modules/@oh-my-pi/pi-coding-agent/dist/types/…`; grep `dist/cli.js` for the literal event names to confirm they exist.
 - A driver test that *calls* the handler by hand proves nothing about emission — that is exactly the gap this live check closes.
 ## 6. Audio output goes silent while every command reports success
 `pw-play` exits 0 and prints `stream drained` even when nobody hears anything. Triage order:
 ```bash
 wpctl status                       # Sinks, the `*` default, and live Streams
 wpctl get-volume @DEFAULT_AUDIO_SINK@
 ```
 - A **`Default Configured Devices` entry naming a `bluez_output.*` node that is not in the Sinks list** = remembered-but-offline Bluetooth: the classic silent-route cause.
 - Confirm the stream really links: a short clip can vanish before inspection, so use a multi-second clip and read `wpctl status` mid-play, or target explicitly: `pw-play --target <node-id> <file>` (node ids from `wpctl status`; `wpctl inspect <id>` gives `node.name`).
 - Prove the synth path independently of the player: `curl -o x.wav …` then `file x.wav` (expect `RIFF … WAVE … PCM`).
 ## 7. Land it
 Live result belongs in the commit message, the reference page, and the work log — and the guard the live check uncovered gets its own behavior test (assert observable output only: fired count, payload content, silence).
 ## Cleanup
 `/exit` or `proc://<id>/kill` the service; move stub scripts, logs, and clips to `~/.AGENTTRASH/<date>-<topic>/` — never `rm`. Kill background jobs that keep playing to the operator's speakers.
@@ -0,0 +1,29 @@
 ---
 name: omp-extension-stale-module-audit
 description: "Diagnose recurring omp extension handler timeouts/silence when the on-disk fix is already deployed: harness has no extension hot-reload, so running sessions freeze the module at session start (zombie modules)."
 ---
 Use when a fix for an omp extension is merged/deployed yet the SAME errors persist ("handler timed out after 30000ms", silence, wrong behavior) in running sessions.
 **Core fact:** the harness loads extension `.ts` modules at session start and never reloads them (no `/reload` for extensions; bundle `reload` hits are LSP/MCP/browser only). A session older than the fix keeps executing stale code regardless of the file on disk.
 **Procedure:**
 1. Census the errors from logs, not guesses — timeout lines carry the culprit pids:
   `grep -h "handler timed out" ~/.omp/logs/omp.<today>*.log | python3 -c 'import sys,json; rows=[json.loads(l) for l in sys.stdin]; rows.sort(key=lambda r:r["timestamp"]); [print(r["timestamp"], r["event"], r["pid"]) for r in rows]'`
   (`~/.omp/logs/omp.<date>.<pid>.log` — the pid in the filename is the session.)
 2. Session start times vs deployed file versions:
   `ps -eo pid,lstart,args | grep '[o]mp'`
   `git log --format='%h %ad %s' --date=format:'%m-%d %H:%M' -- <extension path>`
   `git reflog --format='%gd %ad %gs' --date=format:'%m-%d %H:%M' | grep merge` (live-sync pull times = when the file content changed).
   Any session whose start time precedes the fix's arrival has the stale module.
 3. Confirm the stale revision actually contains the bad pattern — read what that session loaded, not HEAD:
   `git show <old-rev>:<path> | grep -n 'await speak\|async (event'`
   (e.g. an `async agent_end` awaiting a >30 s chain is exactly what the harness's per-handler `Kzc` 30 s race logs; fire-and-forget `void` is fine — detached promises are NOT tracked by the dispatch window.)
 4. Optional empirical proof when static analysis says "impossible": probe extensions through the real harness:
   `omp -p --no-extensions -e /tmp/probe.ts "Reply OK"` with a probe that logs handler start/return and `void`s a 40 s detached promise + spawns a long child. Fast exit + no timeout log ⇒ detachment is untracked ⇒ blame stale modules, not the harness.
 5. Remediation: restart the affected sessions (kill the listed pids or their terminals — the operator session itself may be one of the zombies; say so explicitly). There is no other fix.
 **Gotchas:**
 - Per-handler attribution in the log is accurate per dispatch; don't blame other extensions before checking the pid's start time.
 - Endpoints healthy + silence persisting usually means TWO stacked bugs (e.g. stale awaiting module in old sessions AND a mute bug in current code) — diagnose each pid cohort separately.
 - Extension chain code must use self-owned `AbortSignal.timeout(...)`, never a ctx-scoped signal: harness dispatch signals die when the dispatch window closes.
@@ -0,0 +1,25 @@
 ---
 name: omp-keybinding-inspection
 description: "Find what a key chord does in omp: doc table, live bundle defaultKeys inspection, modifier names, remap file"
 ---
 Answer "what does chord X do in omp" with evidence from docs + installed bundle, not memory.
 ## Steps
 1. Read `omp://keybindings.md` — common action IDs and defaults (`Ctrl+R` history search, `Alt+R`/`F5` retry, `Alt+A` agent hub, ...). Docs are not a complete inventory.
 2. Locate the install: `readlink -f $(which omp)` → usually `~/.bun/install/global/node_modules/@oh-my-pi/pi-coding-agent/dist/cli.js` (bundled).
 3. Extract live default chords from the bundle (authoritative for installed version):
   ```bash
   cd <dist dir> && grep -o '"app[^"]*":{defaultKeys:[^}]*' cli.js
   ```
   Contextual duplicates exist: same chord can map to different actions in different views (e.g. `ctrl+r` = `app.history.search` in composer, `app.session.rename` in resume picker).
 4. Modifier names: `pi-tui/dist/types/keys.d.ts` → `ModifierName = "ctrl" | "shift" | "alt" | "super"`. "mod"/Super binds as `super+`; only shipped super chords are `super+alt+backspace|delete|d`. Most Linux terminals swallow plain Super chords (needs kitty keyboard protocol / CSI u: kitty, foot forward them).
 5. Remaps live in `~/.omp/agent/keybindings.yml` (NOT config.yml): `action.id: chord` or array; `[]` disables. Profile-aware: default-profile file loads first, active profile overrides per action.
 6. In-session live reference: `/hotkeys`.
 ## Pitfalls
 - `grep pi-tui/dist/*.js` fails (no top-level js; types only under `dist/types/`).
 - Chord notation is case-insensitive, UI-style (`Ctrl+P`, `Alt+Shift+P`).
 - Old unqualified action names auto-migrate; new configs use namespaced ids (`app.*`, `tui.editor.*`).
@@ -0,0 +1,27 @@
 ---
 name: omp-lifecycle-event-selection
 description: "Pick the right omp harness lifecycle event for narration/telemetry: agent_end is a settle, turn_end waits for tool results, message_end is earliest with content, after_provider_response carries no content."
 ---
 # Choosing an omp lifecycle event (narration, telemetry, hooks)
 Re-derived twice from the installed typings/sources (`@oh-my-pi/pi-coding-agent`, `@oh-my-pi/pi-agent-core`) while fixing dankvoice. Read this before wiring a handler; verify against the installed version's `src/extensibility/extensions/types.ts` and `pi-agent-core/src/agent-loop.ts` when precision matters.
 | event | payload you can use | when it fires | traps |
 |---|---|---|---|
 | `after_provider_response` | `status`, `headers`, `requestId`, `metadata` **only** | response headers arrive, **before the stream body is consumed** | No message content at all: useless for anything that speaks or summarizes text. Right for latency telemetry, non-200/abort detection, `requestId` correlation. |
 | `message_end` | full `message` (assistant, user, tool-result, gate-stop, error) | the moment that message is built (`agent-loop.ts`, assistant case) | Earliest event carrying assistant text. Fires for non-assistant messages too → gate `message.role === "assistant"`. Payload is cloned for extensions. |
 | `turn_end` | `turnIndex`, `message`, `toolResults` | after that turn's **tool results** come back | Stale by the tool duration: a 14 s tool delays a `turn_end` trigger 14 s. Extension event has **no `willContinue`** (the `turnIndex` is numbered by the lifecycle mirror), so you cannot tell the terminal turn from here. |
 | `agent_end` | `messages`, `willContinue`, `awaitingAsyncWork` | once per user prompt, when the loop settles | `willContinue: true` = the harness scheduled a continuation (auto-retry / empty-stop), not a user-visible settle — narrating it speaks an answer the model is about to redo. Silence-prone on long-running sessions. |
 | `agent_start` | — | run begin | Use to reset per-run dedupe state, so a later answer with identical text is not swallowed. |
 ## Narration cadence pattern (what dankvoice ships)
 - `turn_end` (or `message_end` if the tool-time lag matters) for mid-run commentary; `agent_end` only for the settled answer.
 - Drop a mid-run trigger while audio/IO is busy — never queue, never interrupt.
 - Dedupe the terminal text per run (`agent_start` resets), because the last turn and the settle carry the same string.
 - Skip `ctx.mode === "print" | "json"` so benches stay silent.
 ## Prove delivery, don't infer it
 Audio/UI timing cannot show which events arrive. Link a throwaway extension that appends timestamps per event and run one real session: `omp plugin link /tmp/probe` (package.json with `"pi": { "extensions": ["./index.js"] }`), prompt a task with a slow tool, read the log, then `omp plugin uninstall probe`. Confirmed live 2026-10-19: extensions receive `agent_start`, `turn_end`, `agent_end`; `turn_end` landed seconds before `agent_end`.
@@ -0,0 +1,40 @@
 ---
 name: omp-local-artifact-path
 description: Resolve a local:// artifact to a real filesystem path (for scripts/curl) without guessing the session-slug directory.
 ---
 `local://<name>.md` artifacts live in a per-cwd, per-session directory whose name you cannot guess. Three invented paths failed before this worked (2026-10-19).
 Actual layout:
 ```
 ~/.omp/agent/sessions/<cwd-slug>/<timestamp>Z_<session-id>/local/<name>.md
 ```
 `<cwd-slug>` is the working directory with `/` replaced by `-`, **keeping the leading dash** — `/home/blank/.omp/wt/wt-20261019-125509-7c8a99d` under `/home/blank` becomes `-.omp-wt-wt-20261019-125509-7c8a99d`. Dropping the leading `-.` is the mistake that produces `FileNotFoundError`.
 ## Get the real filesystem path
 Ask the tool, don't reconstruct it — a ranged read of the artifact reports the resolved path in its header:
 ```
 read local://pr-body-msgend.md:1-1     ->  [~/.omp/agent/sessions/-.../local/pr-body-msgend.md#TAG]
 ```
 Or locate it by basename (needs enough depth; `maxdepth 5` misses it — the file sits 6–7 levels down):
 ```bash
 f=$(find ~/.omp/agent/sessions -maxdepth 7 -name 'pr-body-msgend.md' | head -1)
 cp "$f" /tmp/prbody.md      # stable path for the python/curl step
 ```
 Copy to `/tmp` before handing the content to a script: one cheap command, and every later tool call stops depending on session-scoped paths.
 ## Related lookups in the same directory tree
 - Session id for the current cwd — `~/.omp/agent/history.db` (prompts table has `session_id`, `cwd`; the column is `prompt`, **not** `text`, and raw `?q=` queries cannot be combined with a table selector or pagination):
  ```
  read history.db?q=SELECT session_id, cwd, substr(prompt,1,50) AS p FROM history WHERE cwd LIKE '%wt-20261019%' ORDER BY rowid DESC LIMIT 3
  ```
  Use the real id in issue/PR attribution footers; never reuse an id remembered from a compacted transcript.
 - Transcript dir for the same session sits beside `local/`.
@@ -0,0 +1,116 @@
 ---
 name: omp-models-yml-runner-api-placement
 description: "Add or edit a non-chat (tts/image/embedding) model row in ~/.omp/agent/models.yml, wire the speech role, and diagnose a failing speech device without blaming a healthy endpoint"
 ---
 # Scope
 `~/.omp/agent/models.yml` (or `models.yaml`) on a workstation: adding a **runner**
 model row (TTS / image / embedding / rerank / video) alongside chat providers,
 flipping `config.yml` `modelRoles` at it, and diagnosing a speech device that
 refuses to speak.
 # The landmine
 Provider-level `api` accepts **only chat/judge transports**:
 `openai-completions`, `openai-responses`, `openai-codex-responses`,
 `azure-openai-responses`, `anthropic-messages`, `bedrock-converse-stream`,
 `google-generative-ai`, `google-gemini-cli`, `google-vertex`,
 `openrouter-decisions`, `typesafe`.
 Naming a runner API (`openai-speech`, `openai-images`, `openai-embeddings`, …)
 at **provider** level fails whole-file validation, and the failure mode is not
 scoped to your provider:
 ```
 Warning: models.yml validation failed — custom providers disabled
  Failed to load config file models, Schema error: providers.<id>.api: must be "openai-completions", …
 ```
 Every custom provider disappears from the registry (fleet chat endpoints stop
 resolving) and `omp models` lists only built-in locals. Measured 2026-10-18.
 # Correct shape
 Runner api goes on the **model entry only**; `auth: none` satisfies the
 credential requirement; omit `contextWindow`/`maxTokens` (the positivity check
 fires only when they are provided — `omp models` still prints filled defaults,
 which the runner transport never reads).
 ```yaml
  "frank-tts (dankclaw)":
    baseUrl: http://192.168.0.143:7772/v1   # no `api:` here
    auth: none
    models:
      - id: frank-tts
        name: "frank-tts (dankclaw) — cloned voices"
        api: openai-speech                   # runner api on the model
        input: [text]
 ```
 Roles live in `config.yml` (`modelRoles`), not in `models.yml`. Kind roles
 (`image`, `web`, `speech`, `dictation`, `judge`) take no `:thinking` suffix.
 # Verify after every edit (never assume the file loaded)
 ```bash
 omp models --kind tts --no-extensions      # the new row must appear
 omp models --no-extensions | grep -E '<each fleet chat model>'   # and still be listed
 omp models | grep -c 'validation failed'   # must be 0
 ```
 A run that lists only built-ins means your row broke the file — revert before
 yielding.
 # Speech transport contract (`openai-speech`)
 Body is `{model, input, response_format, voice?, speed?}`; `voice` is forwarded
 **only** when the caller passed `voice_id`; `sample_rate`/`bit_rate` **throw**
 (`openai-speech does not support sampleRate`). Codec comes from the
 `output_path` suffix; 15 000-character cap. An unknown `voice` name is a server
 error, not a fallback — and `auth: none` makes a dead endpoint read as
 *available*, so point `modelRoles.speech` at such a provider only after it has
 answered a real synthesis.
 # Three speech-role laws (bundle-read + measured 2026-10-18)
 1. **No setting carries a voice for `openai-speech`.** The transport builds the
   body with `voice` from the call's `voice_id` and nothing else.
   `tts.localVoice` is the *local Kokoro backend's* key; `speech.voice` is the
   TUI's **speak-aloud** voice, an enum of Kokoro names that never reaches an
   HTTP request (setting it to a pack name breaks the vocalizer and does nothing
   for synthesis — read `cfgSpeechVoice` in `dist/cli.js` before believing
   otherwise). So a voice-less call is the harness's **normal** shape: a
   voice-required endpoint needs a server-side default (fleet answer:
   `DEFAULT_VOICE` in `scripts/frank-tts.env`, journal marks the line
   `(default)`, unknown names still 400 with the list).
 2. **An explicit role has no fallback candidate.** `modelRoles.speech` set to one
   model yields exactly one candidate, so a dead endpoint or an unresolvable
   selector fails with *"No available speech model matches the speech role"*
   instead of degrading to Kokoro. Loud-by-design; do not "fix" it by adding a
   fallback in the client.
 3. **`models.yml` loads at process start; `config.yml` is read live.** A session
   older than the new row fails exactly like a dead endpoint while a fresh
   process succeeds in the same minute.
 # Diagnosing "speech device won't speak" — in this order
 1. `curl` the endpoint directly with a real voice name. 200 + audio ⇒ the service
   is fine and the fault is harness-side; stop touching the server.
 2. Control test in the *same* session: point `modelRoles.speech` at
   `local/kokoro` and call the device. It works ⇒ `config.yml` is live-read and
   the runner selector or its voice argument is the problem, not the endpoint.
   Revert the role immediately after.
 3. Distinguish stale registry from dead endpoint with a fresh process:
   `omp -p --no-session --no-extensions --no-skills --no-rules --tools tts --cwd /tmp
   'Call the tts tool exactly once with text="…" output_path=/tmp/x.wav
   voice_id=<name> — then reply with the tool result line.'`
   Succeeds ⇒ the long-lived session predates the `models.yml` row; restart it.
 4. Cross-check server-side, never trust the client's echo: the façade/access log
   line and the engine's own ledger must carry the same byte count the tool
   printed. (`model=…` in a tool result is what the client *requested*; a server
   line is the fact.)
 5. For harness-behaviour claims, read the bundle rather than reasoning from the
   tool description: `/home/blank/.bun/install/global/node_modules/@oh-my-pi/pi-coding-agent/dist/cli.js`,
   e.g. `grep -o -E '.{300}response_format:[a-zA-Z$]+.{250}'` for the speech body
   builder, `grep -o -E 'cfgSpeechVoice:.{0,400}'` for what a settings key feeds.
@@ -0,0 +1,23 @@
 ---
 name: omp-tui-live-visual-verify
 description: "Verify omp TUI config changes (status line, composer, theme) live: edit watched config, niri screenshot, PIL crop, restore — with the flag and race pitfalls."
 ---
 # Live visual verification of omp TUI config
 ## When
 Changing `~/.omp/agent/config.yml` (statusLine.*, composer.*, theme) on a Frank workstation and needing PROOF of how it renders — not inference from the bundle. The status-line/composer knobs are file-watched: edits repaint the RUNNING session; no restart.
 ## Loop (per trial)
 1. Read the live config line(s) first; edit with `edit` (never batch trials — one state per screenshot).
 2. Capture: `sleep 2 && niri msg action screenshot-screen --path /tmp/x.png --show-pointer false` — flag is `--path` (`-o` is invalid); the write lands asynchronously, so `sleep 1.5` before touching the file.
 3. Crop+scale with PIL to the bar/composer region (known good crop for blankpad right monitor: `(2267,1240,3440,1440)`, 1.3x LANCZOS), then `read` the PNG absolute path.
 4. For pixel facts (rule colors, meter lengths) don't eyeball alone: scan rows with `Image.load()` counting dominant colors; sample every 2px and lower thresholds before concluding "nothing found".
 5. After the matrix, RESTORE the original values and re-screenshot the baseline.
 ## Pitfalls
 - Read a downscaled FULL-screen shot first: Frank's screens carry multiple terminals + a browser; a fixed crop can silently capture a different window's bars (happened during the contextLine audit — two omp windows on one screen).
 - Session-accent rules/borders share colors with meters; color presence alone proves nothing. Compare states against each other, and settle ambiguous pixels from the bundle code path (grep `dist/cli.js` for the render function).
 - Live config drifts (other sessions own files there): never `git add -A` the main checkout to promote a trial; commit from a separate `git worktree add` off the target ref.
 - `read` the absolute `/tmp/...` path for screenshots.
 - Multi-value enums: one screenshot per value; identical renders (e.g. claude shape `contextLine: off` vs `embedded`) are themselves a finding — record them as such.
@@ -0,0 +1,49 @@
 ---
 name: omp-worktree-path-gotchas
 description: "Use in ~/.omp (or any multi-worktree repo) when an edit lands in the wrong checkout, git checkout is policy-refused, or an omp session id is needed — relative-path tool resolution, shared-worktree branch law, session-id lookup, edit auto-prefix trap."
 ---
 # Multi-worktree gotchas in ~/.omp-style repos
 Measured 2026-10-18 building PR #12/#14 in `dank/command-center` worktrees.
 ## 1. Relative paths resolve to the SESSION worktree — always edit by absolute path
 `edit`/`read`/`write` with a relative `path` resolve against the session CWD
 (the harness worktree you were spawned in), NEVER the worktree you `cd`'d into
 via bash. Identical file content in sibling worktrees yields identical
 `[path#tag]` hashes, so an edit can "succeed" against the WRONG checkout with
 no warning; only a rejected stale-hash edit reveals it.
 - When working in a second worktree, ALL file-tool paths: absolute.
 - Symptom seen: edit rejected "hash #X is not from this session" while the
  bash-side `git status` showed the file clean — two different files, two
  worktrees. Recovery: revert the stray edit (CUT the inserted lines) in the
  wrong tree, re-read the right tree, redo with absolute header.
 ## 2. Branching: shared worktrees refuse git checkout
 Workspace policy blocks `git checkout` (branch switches AND `--` discards) in
 harness-managed worktrees — concurrent agents depend on them. To start a
 branch off fresh trunk:
 ```bash
 git -C ~/.omp worktree add -q -b <type>/<issue#>-<slug> ~/.omp/wt/<name> origin/main
 ```
 Never force past the refusal; the new-worktree route is strictly safer.
 Custom worktrees not matching `wt/wt-*` are invisible to the live-sync reaper —
 prune them by hand after merge (`git worktree remove`, `git branch -d`).
 ## 3. omp session id for attribution footers
 Fleet law requires `session:` in issue/PR bodies. Authoritative source:
 `~/.omp/agent/sessions/<cwd-slug>/<timestamp>_<UUID>.jsonl` — the `<UUID>` is
 the session id. Pick the newest file whose first `{"type":"title"}` line names
 this conversation to prove the id is yours. The `wt/<ts>-<hash>` dir suffix is
 NOT the session id (it persists across sessions per cwd).
 ## 4. edit-tool auto-prefix trap (recurring)
 A body row written bare (intending it as the "original line" anchor or as
 context) is AUTO-PREFIXED with `+` and INSERTED — leaving the old line plus a
 duplicate. `PUT n.=n:` therefore behaves like insert, not replace, whenever
 the anchor row lacks an explicit marker. After any `PUT` where the response
 warns "Auto-prefixed bare body row(s)", immediately `CUT` the stale line number
 shown in the response (descending order for multiple CUTs).
@@ -0,0 +1,57 @@
 ---
 name: open-notebook-provision-model-rest
 description: "Provision or repair an open-notebook model (LLM/TTS/embedding) over its REST API on Dankclaw: credential→model→defaults order, the defaults-store-the-ID trap, the /api/embed 500-that-succeeds, and the two-note ranking proof for embeddings."
 ---
 # open-notebook model provisioning over REST
 Use when adding/repairing a model row (embedding, LLM, TTS) in open-notebook on Dankclaw, when semantic
 search is dead, or when an embed error appears in the worker log. Config lives in the **database**
 (encrypted with `OPEN_NOTEBOOK_ENCRYPTION_KEY`) — no repo file mirrors it, REST or the UI are the only doors.
 ## Access (never put the bearer in argv)
 The API bearer IS `OPEN_NOTEBOOK_PASSWORD`; the API publishes on loopback `127.0.0.1:5056` only, so run
 from Dankclaw over ssh. `ssh dankclaw 'curl -H "Authorization: Bearer …"'` leaks the secret into
 `/proc/<pid>/cmdline` — use a mode-600 curl config:
 ```bash
 PW=$(grep -m1 '^OPEN_NOTEBOOK_PASSWORD=' /home/dank/Containers/open-notebook/env | cut -d= -f2- | tr -d '"')
 cfg=$(mktemp); chmod 600 "$cfg"; printf 'header = "Authorization: Bearer %s"\n' "$PW" > "$cfg"
 B=http://127.0.0.1:5056   # not 5055: seerr holds the host's 5055
 ```
 ## Order, and the address rule
 `POST /api/credentials` → `POST /api/models` (`credential: <credential id>`) → `PUT /api/models/defaults`
 → any profile that names a model (speaker `voice_model`, episode `speaker_config`/`outline_llm`).
 - Credential provider for any in-house OpenAI-compatible server: **`openai_compatible`** (not `openai`),
  with a dummy `api_key` when the upstream does not authenticate.
 - The app's URL guard refuses base URLs resolving in `169.254.0.0/16`, so `host.containers.internal`
  cannot be stored; a **container name on `dankclaw_default`** (e.g. `http://frank-dragoon-halogen:8731/v1`)
  or another machine's RFC1918 IP both pass.
 ## The two traps that eat the most time
 1. **`PUT /api/models/defaults` takes the model ID, never the name.** `"default_embedding_model":
   "qwen3-embedding-0.6b"` is accepted and echoed back, then every job dies in the worker with
   `Model with ID qwen3-embedding-0.6b not found`. Use the row's `model:…` id (GET defaults first, change
   one key, PUT the whole object back — the other keys in that response are ids and must be preserved).
 2. **`POST /api/embed` answers 500 *after* the work succeeds.** Upstream `EmbedResponse.command_id`
   declares `str` and the worker returns a `RecordID`, so FastAPI raises in serialization only. The truth is
   `podman logs open-notebook | grep "Successfully embedded"`, never the HTTP code. Note saves
   (`POST /api/notes`) submit `embed_note` themselves; `/api/embed` is only for backfills.
 ## Proof it actually works
 - Per row: `POST /api/models/<id>/test` → `Embedding dimensions: 1024` (embeddings) or a real completion.
 - Embeddings, discriminating test: create **two** unrelated notes, then
  `POST /api/search` `{"query": "...", "type": "vector", "search_notes": true, "limit": 5}` — the enum is
  `text|vector` (not `semantic`) and the score field is `similarity`. Each query must rank its own note
  high and the other low (measured 0.659/0.292 vs 0.906/0.318). One note proves nothing: `total_count` is 1
  either way. Delete the probe notes afterwards (`DELETE /api/notes/<id>`).
 - Confirm which engine served it: `podman logs <engine container> | grep "POST /v1/embeddings"`.
 Owner pages: `serverAppConfigs-docs/Dankclaw/Open Notebook.md` (app-side shapes), and the endpoint's own
 page for whatever serves the model.
@@ -1,29 +1,30 @@
 ---
 name: openwebui-picker-acl-repair
-description: "Fix OpenWebUI 0.6 \"No results found\" / Model not found in the model picker for non-admin users (Dankclaw fleet) after a connection rebuild."
+description: "Add, enable, or repair a model in the Dankclaw OpenWebUI 0.6 picker: connection enable + model row + access_grant trio, verified via /api/models as admin and role=user."
 ---
-# OpenWebUI 0.6 picker ACL repair (Dankclaw)
+# OpenWebUI 0.6 picker: add / enable / repair a model (Dankclaw)
-Symptom: admin sees models in OpenWebUI; regular users get "No results found" in the picker, or chat answers "Model not found". Cause: an OpenAI-connection rebuild (config keys `openai.api_base_urls` / `openai.api_configs` in the `config` table) that dropped the ACL pair for the model.
+Symptoms: non-admin sees "No results found"/"Model not found" while admin sees the model (repair); endpoint live, model_ids correct, model absent from picker (add).
-## Law
+## Law — a picker entry needs ALL legs, keyed by the EXACT upstream served id
-A non-admin user sees an external OpenAI-connection model only if BOTH exist in `webui.db`:
+1. openai.api_configs (config table, JSON map by idx): that connection has enable: true and model_ids containing the upstream id. Non-empty model_ids = no upstream fetch (llama.cpp's Ollama-shaped /v1/models is invisible to discovery; halogen/radiance are OpenAI-shaped, model_ids stays authoritative).
-1. `model` table (singular) row: `id` == upstream model id, `base_model_id` NULL, `is_active` 1, `meta` JSON (description etc.).
+2. model table row: id == upstream id (alias rows with base_model_id set render in the picker but chat fails "Model not found"), base_model_id NULL, is_active 1, user_id = admin uid, params {"context":{"length": PER-SLOT window}}, meta {"description": "..."}.
-2. `access_grant` row: `(resource_type='model', resource_id=<model id>, principal_type='user', principal_id='*', permission='read')`.
+3. access_grant row: resource_type=model, resource_id=<id>, principal_type=user, principal_id='*', permission=read. Without it only admins see the model (get_filtered_models drops info-less rows for role=user).
-The aggregation (`utils/models.py get_filtered_models`) drops info-less models for `role=user`; admins bypass. `get_all_models` responses are served from `model_ids` in `api_config` when non-empty (no upstream fetch). An alias row (`id` != upstream, `base_model_id` set) renders in the picker but chat fails "Model not found" — id must equal the upstream id.
+URLs: on-host endpoints via host.containers.internal:<port> (bridge cannot hairpin the host LAN IP); other hosts via LAN IP.
 ## Steps
-1. Reproduce as the affected role: in a browser tab, `fetch("/api/models", {headers:{Authorization:"Bearer "+localStorage.token}})` → `data: []` while an admin API key (`api_key` table, column `key`, `sk-…`) lists the model.
+1. Snapshot: cp -a webui.db webui.db.bak-<date><letter>.
-2. DB at `/home/dank/Containers/open-webui/data/webui.db` (host; no sqlite3 CLI on Dankclaw — use host `python3` heredoc over ssh; container path `/app/backend/data`).
+2. Apply with host python3 over ssh (no sqlite3 CLI on Dankclaw) on /home/dank/Containers/open-webui/data/webui.db: read-modify-write the whole openai.api_configs JSON value; insert model row (epoch-ms created_at/updated_at); insert access_grant (uuid4 id).
-3. Insert/repair the pair (uuid4 id, epoch-ms `created_at`):
+3. Restart: systemctl --user restart open-webui.service (rootless quadlet) to drop the cached model list. Restart kills browser JWTs: expect one SSO re-round-trip per tab; kill stale tabs first so OAuth state cookies don't race.
-   - `model`: id/name = upstream id, base_model_id NULL, is_active 1, user_id = admin uid (role='admin' in `user` table), meta `{"description": "…"}`.
+4. Verify (mint tokens in the container; create_token is in open_webui.utils.auth; export WEBUI_SECRET_KEY from /app/backend/.webui_secret_key):
-   - `access_grant`: shape above.
+   - GET /api/models (key data) lists the id as admin AND as a role=user token (e.g. qa-e2e-admin uid). This is the picker truth.
-4. Cache: `MODELS_CACHE_TTL` defaults to 1 s — no restart needed for lists; a restart (`systemctl --user restart open-webui`, rootless) only if config edits were cached oddly. An OpenWebUI restart invalidates browser JWTs (401) — expect a silent SSO re-round-trip; kill stale tabs first so OAuth `state` cookies don't race (MismatchingStateError → clear cookies/storage, one clean flow).
+   - POST /api/chat/completions, prompt "Reply with exactly one word: pong", max_tokens 1500 (thinking models give empty content + finish_reason length on small budgets).
-5. Verify end-to-end: pick the model in the UI, send a short exact-match prompt, confirm the reply; check `/api/models` as the user role lists the id.
+   - NEVER gate on GET /api/v1/models/list (key items): on 0.6.x it lists workspace models only, [] for connection-backed models (measured 2026-10-09).
 ## Related knobs
- User API keys (User menu → Settings → Account → API keys → Show → Create new secret key) require `user.permissions` JSON `features.api_keys=true` in `config` (default false).
+- User API keys need user.permissions JSON features.api_keys=true in config (default false).
- New SSO signups land as role `pending` (`ui.default_user_role=pending`) — activate: `UPDATE user SET role='user' WHERE email LIKE …`. Table is `user`, singular; no `active` column.
+- SSO signups land role pending (ui.default_user_role=pending): UPDATE "user" SET role='user' WHERE email=... (table user, singular, no active column); row exists only after first login.
- Anubis gates `ai.franksdank.cloud` for headless browsers (webdriver detection): drive direct `:3005` for UI work, or emulate a desktop Chrome UA.
+- Anubis gates ai.franksdank.cloud for headless browsers; drive direct :3005.
 - The trio is DB-only, lost on a fresh volume. Record changes in serverAppConfigs-docs/Dankclaw/OpenWebUI.md (Facts, backends table, History): the model id is a foreign key across three tables, so any endpoint alias rename must ship the same re-key.
@@ -0,0 +1,27 @@
 ---
 name: openwebui-tts-chain-audit
 description: Audit/repair OpenWebUI TTS on Dankclaw when cloned voices get rejected by a 29-name Kokoro enum or synthesis is silent; rootless DB + endpoint probes
 ---
 Audit OpenWebUI's TTS/STT wiring on Dankclaw when a voice is rejected, synthesis is silent, or someone asks "is the cloned voice wired correctly". Not for model-picker/ACL issues (openwebui-picker-acl-repair owns those).
 ## Shape of the stack
 - Container `open-webui` runs **rootless as `dank`** on Dankclaw: `ssh dankclaw 'podman exec open-webui ...'` (NO sudo: `sudo podman` sees an empty world). Host port 3005.
 - Server-side config = `webui.db` `config` table (admin), per-user overrides = `user.settings` JSON column. Settings changed via UI persist per-user; admin page persists to `config`.
 - Cloned voices live behind the frank-tts façade `:7772` (`/v1/audio/speech`, `/v1/audio/voices`); voices resolve to `/home/dank/voices/<name>/reference.wav`.
 ## The trap (2026-10-18 law)
 `Error: Voice "narrator1" not found. Should be one of: af_heart, ...` (29 names) is **OpenWebUI's bundled in-browser Kokoro** (`browser-kokoro`) rejecting client-side — frank-tts never sees the request. Signature: container logs show zero `audio/speech` hits. Fix = the personal dropdown Settings -> Audio -> TTS Engine -> Default (empty string), not any deploy.
 ## Probe sequence (read-only, safe)
 1. Admin truth:
   `podman exec open-webui python -c "import sqlite3; c=sqlite3.connect('/app/backend/data/webui.db'); [print(k,'=',v) for k,v in sorted(dict(c.execute('SELECT key,value FROM config')).items()) if 'audio' in k or 'tts' in k.lower()]"`
   Expect: `audio.tts.engine=openai`, `audio.tts.openai.api_base_url=http://host.containers.internal:7772/v1`, `audio.tts.model=frank-tts`, `audio.tts.voice=<cloned name>`.
 2. User overrides — a user pinned to `browser-kokoro` beats admin config. CAUTION: `user.settings` can be SQL NULL or the JSON string `"null"`:
   `... for uid,s in c.execute('SELECT id,settings FROM user'): d=json.loads(s) if s else None; d=d if isinstance(d,dict) else {}; hits={k:v for k,v in d.items() if 'audio' in k or 'tts' in k.lower()} ...`
 3. Endpoint truth: `curl -s http://127.0.0.1:7772/v1/audio/voices` (roster), then POST the exact OpenWebUI body `{"model":"frank-tts","input":"probe","voice":"narrator1","response_format":"mp3","speed":1.0}` to `/v1/audio/speech` — expect `200 audio/mpeg`.
 4. Contrast logic: server-path failure leaves a container log line AND a façade error; browser-kokoro failure leaves neither.
 ## Law
 - Full contract + diagnosis live in serverAppConfigs docs (`Dankclaw/OpenWebUI.md` § Text-to-speech, `Dankclaw/Frank TTS.md` troubleshooting). Docs are the source; this skill is just the probe route.
 - Rootless gotcha generalizes: any Dankclaw service probe through podman goes WITHOUT sudo unless the unit is a system quadlet.
@@ -0,0 +1,34 @@
 ---
 name: parallel-worktree-path-hazard
 description: "Use when several agents edit the same repo in different git worktrees at once, or when an edit lands in the wrong checkout: relative tool paths resolve to the session cwd, not the shell cwd."
 ---
 Use when several agents (or you across two checkouts) edit the same repo in different git worktrees at once, or when an edit/query lands in the wrong checkout.
 ## The silent failure: relative tool paths resolve to the SESSION cwd
 `read` / `edit` / `write` / `grep` resolve a **relative** `path` against the **session working directory** — never against the `cd` inside a neighboring `bash` call, and not against a `../other-worktree/...` prefix either (that gets normalized back into the session tree). So after `cd ../wt-B && grep …` you can `read path="docs/page.md"` and get **wt-A's** copy.
 Why it survives "I just read it to check": the returned path is printed workspace-relative and the file name is identical in every checkout, so the output looks like a correct read of the tree you meant. Only content that differs between the checkouts betrays it.
 Rules:
 - **Absolute paths for every tool call that targets a worktree other than the session's.** No exceptions for quick reads.
 - Confirm the checkout from content you know differs (a heading, a status line), not from the echoed path.
 - A `read` error like "Did you mean .AGENTTRASH/<name>" is a signal the relative path resolved into the session tree — re-issue absolute.
 - Same trap for `bash`: it starts each call in the session cwd, so `cd` twice per call or use absolute paths there too.
 ## Landing a change when the session worktree is stale
 `git diff --name-only HEAD origin/main` first. If main moved a file you are editing, your edit's base is wrong even though the file "looks fine" — do not commit on the stale base.
 1. `git worktree add ../wt-clean -b <type>/<slug> origin/main`; copy the new files in.
 2. Re-apply the edit against the clean tree's version **with absolute paths**, then read it back absolutely to prove which tree changed.
 3. Run the suite inside the clean worktree; commit there.
 4. Remove your own duplicate edit from the session worktree by editing it away (`CUT`/`PUT`). `git checkout -- <path>` and branch switches are policy-blocked in shared workspaces and should stay blocked — they discard edits other agents rely on.
 5. Never carry the same uncommitted edit in two worktrees at once; if you must keep both trees, keep a task that reconciles them.
 ## Multi-agent hazards in one shared worktree
 - Another agent can stage, commit, or check out files under you; re-read a file immediately before editing it if any tool result hinted at intervening change.
 - Untracked scratch you drop in a shared tree (reports, notes, `.AGENTTRASH/` entries) is visible to everyone and can be committed by them. Put throwaway artifacts outside the checkout.
 - Never `git clean -f`, `rm -rf`, or branch switching to "get a clean state" in a tree another agent is using.
@@ -0,0 +1,61 @@
 ---
 name: plugin-git-install-committed-artifact
 description: "Use when shipping or landing an omp/pi plugin (omp plugin install/upgrade git): install validation fails on a missing build artifact, a stale bun git-mirror cache is reused, the live bundle needs proof it is the merged build, or upgrade says \"not installed\"."
 ---
 # Plugin install from git: committed artifact + fresh mirror
 `omp plugin install git:<url>` (and `pi install git:`) **clone the repo and validate the manifest's declared extension entry WITHOUT running a build step**. Two failure classes seen live (dank/dankvoice, 2026-10-19):
 ## 1. Declared entry missing from the clone
 Symptom: `Plugin <name> extension validation failed: ./dist/index.js: declared extension entry not found on disk`.
 Cause: build output (`dist/`) is gitignored; the manifest points at it; the clone has only `src/`.
 Fix — ship the artifact:
 - Remove `dist/` from `.gitignore`, `bun run build`, commit `dist/`.
 - Prove build determinism first: build twice, `cmp` the outputs (bun esm builds are byte-reproducible without sourcemaps).
 - Pin the contract in a small bats suite so it can't rot:
  1. the manifest's declared entry is tracked in git (`git ls-files -- "${entry#./}"` non-empty — this is the installer's exact contract, not a config assertion);
  2. committed bytes equal a fresh build (`bun run build` then `git diff --name-only -- dist` is empty → red on drift).
 ## 2. Stale bun git-mirror cache
 Symptom: fix pushed, retry **still** fails identically, and the retry is suspiciously fast (seconds).
 Cause: bun keeps bare mirrors in `~/.bun/install/cache/<hash>.git` and may reuse them at an old commit — even after the fix is pushed and the default branch is correct.
 Diagnose + fix:
 ```bash
 find ~/.bun/install/cache -maxdepth 2 -iname "*<repo>*"
 git --git-dir ~/.bun/install/cache/<hash>.git log --oneline -3 --all   # stale HEAD?
 rm -rf ~/.bun/install/cache/<hash>.git                                  # it is a cache; safe
 ```
 Prove the fetch path independently first (also validates credentials for private Gitea repos):
 ```bash
 GIT_TERMINAL_PROMPT=0 git clone -q <url> /tmp/x && git -C /tmp/x log --oneline -1 && ls /tmp/x/dist
 ```
 ## Order of investigation (don't skip)
 1. Gitea default branch correct? (`GET /api/v1/repos/<o>/<r>` with token — private repos 404/None unauthenticated.)
 2. Plain unattended clone contains the entry? If yes, the installer's view is cached → purge mirror.
 3. Only then suspect the installer itself (validation code lives in the minified bundle; `grep -oE '.{600}<error string>' "$bunfile"` on `readlink -f $(which omp)` shows the exact check).
 ## Landing a merged PR on the live box
 After the merge and the `--ff-only` on the dev checkout (`ls -ld node_modules` after landing anything that could have touched it):
 - **`omp plugin upgrade <name>` takes the PACKAGE name, not the install alias.** `omp plugin upgrade dankvoice` fails `dankvoice is not installed` while the live copy sits in `~/.omp/plugins/node_modules/omp-dankvoice/`. Read the directory name (or `package.json` `"name"`) and upgrade that.
 - Then close the chain of custody with one command — the deployed bytes are the merged bytes:
  ```bash
  cmp ~/Projects/<repo>/dist/index.js ~/.omp/plugins/node_modules/<pkg>/dist/index.js
  ```
  If only docs/tests changed, `dist/` is untouched and this should already match; if `src/` changed, the plugin must be upgraded first or this fails with `char <n>` — which is a real finding (stale live bundle), not a test bug.
 - The session that did the merge keeps the OLD bundle in memory: it is still running pre-merge code. Never conclude "the change does not work" from the merging session.
 ## After install — proof without a TUI
 - `omp plugin doctor` → per-plugin ✔ line.
 - Audible/behavioral chain when TUI input is unusable (update-banner modal freezes pty submits): run `omp --mode=rpc --no-session` with the feature env armed (dankvoice: `DANKVOICE_AUTO=1`, gate is print/json-only) and watch for objective side effects, e.g. PipeWire: `pw-dump | grep -q "say-<ms>.wav"` proves synth+playback end-to-end.
 - When pty submits DO work (no modal), the strongest instrument is a stub player plus a clip count, not ears or pixels: `DANKVOICE_PLAYER=/tmp/stub.sh` where the stub appends `$1` to a log and exits 0. Launch the DEPLOYED bundle by path (`omp --no-extensions --no-session -e ~/.omp/plugins/node_modules/<pkg>/dist/index.js`) in a neutral cwd with `DANKVOICE_CONFIG` pointed at a scratch file so the operator's settings are untouched.
 - **Count clips per narration EVENT, not per turn.** One turn can fire several narrations (dankvoice: `message_end` carries prose+thinking, `agent_end` the settled answer; the dedupe only skips byte-identical text, so thinking-on means both speak). A "too many clips" result is usually correct behaviour — check the harness transcript for the turn count before believing a bug. The player deletes each temp wav, so the log line count is the only surviving evidence: park it in `~/.AGENTTRASH/<date>-<topic>/` if it becomes evidence for an issue.
@@ -0,0 +1,36 @@
 ---
 name: podman-one-shot-hang-proofing
 description: "Run remote podman one-shot jobs hang-proof: container-as-unit timeout/reap protocol; diagnosing stalls where ssh never returns and containers outlive timeout"
 ---
 Use when running one-shot container jobs over SSH (grading sandboxes, CI executors) and a caller stalls, or `timeout N podman run ...` demonstrably fails to kill the workload.
 ## Stall signatures (all three = this bug)
 - SSH client process alive for hours, no established-socket data flowing
 - `podman ps` shows the container `Up` far past the timeout; `podman top <c> -o pid,stat,etime,args` shows `R`/`S` workload
 - endpoint/queue reports idle (`in_flight: 0`) while the caller awaits
 ## The three laws
 1. **A `timeout`/SIGTERM on an attached `podman run` client kills only the client.** The container is conmon-detached: it survives, inherits the ssh stdout pipe, ssh never sees EOF, the awaiting parent blocks forever.
 2. **`podman wait` has NO `-t` flag in podman 5.x** (docker-ism) → every exec silently dies with rc 125. Bound the waiter with coreutils `timeout -k 5 <T> podman wait <ctr>` — killing a waiter is harmless.
 3. **`podman rm -f` is the only true container kill** (escalates SIGTERM → SIGKILL on the container itself).
 ## Hang-proof exec protocol (single ssh script)
 ```bash
 cname=job-<unique>
 podman run -d --name "$cname" --network none --memory 4g --cpus 2 <image> python /w/entry >/dev/null
 timeout -k 5 "$T" podman wait "$cname" >/dev/null 2>&1; rc=$?
 code=$(podman inspect -f '{{.State.ExitCode}}' "$cname" 2>/dev/null || echo -1)
 podman logs "$cname" 2>/dev/null; echo "EXIT:${rc}:${code}"
 podman rm -f "$cname" >/dev/null 2>&1
 ```
 - `rc=0, code=0` → success; `rc=124` → timed out (container reaped); harvest output via `podman logs`.
 - Wrap the local ssh spawn in a **hard timeout of T + 180 s** (kills transport half-hangs too).
 - Unique `--name` per submission; the trailing `rm -f` is also the leak reaper.
 ## Recovery of a live stall
 1. `ssh host podman rm -f <ctr>` (warning "resorting to SIGKILL" confirms the theory).
 2. Kill the hung local ssh + supervisor; queue/ledger resume (append-only ledger + takeover by heartbeat-pid liveness) resumes mid-eval; a hung step re-graded under the fixed protocol records a clean FAIL exit 124.
 ## Test to keep (regression)
 `execPython("while True: time.sleep(1)", timeout=20)` → expect `exitCode 124`, completion < 180 s, then `podman ps --format {{.Names}} | grep -c <prefix>` == 0.
@@ -0,0 +1,111 @@
 ---
 name: radiance-kv-cache-resize
 description: "Resize the KV cache / VRAM pair on a radiance (StillDeadcode) endpoint: engine-budget-table ceiling, pool contract arithmetic, slab-slope law, ledger-first verification, free token-count probes"
 ---
 # Radiance KV / VRAM pair resize
 Use when changing `--vram-kv-mib`, `--vram-weights-mib`, `--max-num-seqs`,
 `--max-model-len` or `--kv-cache-dtype` on a radiance endpoint
 (frank-archon pattern), or when asked "what can we do with the free VRAM".
 ## 1. The ceiling is the engine's, never a hand-picked reserve
 `rocm-smi` free space is NOT spare capacity. The boot prints a `VRAM budget,
 per card` table; read it:
 ```
 card total          31.86 GiB
 vram_weights        25.00 GiB   stated by --vram-weights-mib
 vram_kv              5.00 GiB   stated by --vram-kv-mib
 unclaimed            477.30 MiB  the headroom, the unusable above, rounding
 W VRAM budgets total 30.00 GiB of the card's 31.86 GiB, so 1.86 GiB is neither
  budgeted nor accounted. The driver's context, the activation arena and
  --gpu-headroom-mib come out of it; anything past those is throughput on the floor
 W card 0 settled at 2.01 GiB free against 209.19 MiB (the 96.00 MiB
  --gpu-headroom-mib and 113.19 MiB kept for the static region)
 ```
 `ceiling = (settled_free_MiB - engine_floor_MiB) + current_pair_sum`.
 Worked (dankserver, 2026-10-13): 29,120 + (2,058 − 209) = **30,969 MiB/card**.
 A pair at the ceiling settles ~330 MiB free at worst case. If a bound cannot be
 traced to a ledger line, it is a personal reserve — label it and put it in the
 bats gate as such.
 ## 2. Pool contract (the engine enforces it at REQUEST time, not boot)
 `pool_mib >= seqs*max_model_len*rate + 110*seqs + 448`
 - rate/token/rank: **7,488 B fp8**, **14,144 B bf16** (1.89×, not 2× — the QSA
  block key is 3.25 KiB at BOTH dtypes; it is an index, not attention state).
 - +110 MiB a sequence of recurrent state (`kv_gdn_state` 54 MiB × 2 copies +
  conv/tail/ple) and 448 MiB of prefix checkpoints, dtype-independent.
 A pool that fails this **boots, serves short chats, then 400s every long
 request** as `does not fit the 200000 token context, which leaves nothing to
 generate into` — radiance refuses, never truncates. Encode it as a bats gate.
 `--kv-cache-dtype` takes ONLY `bf16|fp8`, one dtype for the whole cache (no
 llama.cpp-style exact-K/quantized-V pair).
 ## 3. Slab and KV are one budget; the slab is a SLOPE
 - Idle KV VRAM is the expert cache's spillover: ledger
  `mover: N slots can be lent out of the KV cache (X GiB)`. A bigger pool steals
  residency twice over.
 - Slab MiB ↔ resident experts is linear (~1,300 slots per 1,792 MiB measured);
  the pinned host pool hands back the same slot count as the slab grows
  (16,235→17,548 slab with 8,893→7,580 pool). The pinned RAM path is the slow
  path, so slab MiB = throughput.
 - Measured law (fp8, 43.5k single-stream, Qwen3.8-Flash-Next w4):
  22,208 → 3,397, 24,000 → 3,290, 25,600 → **3,584**, 26,071 → **4,379 t/s**.
  Two points inside the ±3 % noise band are NOT a plateau — never infer a
  threshold from two arms.
 - **Decode is a separate axis.** It follows KV dtype/bandwidth and draft
  acceptance, not the slab: fp8/slab 26,071 decoded 124.1 t/s cold where
  bf16/slab 22,208 decoded 94.1 (512 tokens, 51.5k). Slot count moves the
  batch-shared per-stream floor (3 concurrent ≈ 6 t/s; solo ≈ 90–120).
 ## 4. Verify: ledger first, then live probes (no scratch server)
 1. Deploy the service; read `podman logs <svc>`: `backs N sequences all at
   M tokens at once` is the capacity referee; check slab slots, `unclaimed`,
   `sampler: ... R rows` (= seqs × (1+spec), must stay inside the 25-row wht6
   exactness bound), `settled at … free against … floor`.
 2. Boundary probe: N concurrent prompts sized to `max_model_len - gen`, each
   with a unique marker at the head; expect N/N marker retrieval.
 3. Prefill/decode probe: repo `scripts/probe-frank-archon-kv.py` (reads the
   shape from the deployed env, so it self-resizes).
 ### Free token-count calibration (no prefill burned)
 `/v1/completions` refuses when **prompt tokens alone** exceed the window —
 `prompt: 202,777 prompt tokens does not fit the 200000 token context` — and the
 refusal names the count BEFORE any prefill. It does NOT fire on
 prompt + max_tokens. Corpus ratio measured: **2.7617 chars/token** (2.5714 for
 the fox filler), so a 200,000-token window ≈ 514,286–552,286 chars. Calibrate
 with a probe ABOVE the window; below it the request is accepted and pays real
 prefill (~22 s).
 ### Probe traps that produced false results
 - Generate **≥128 tokens** (512 preferred) for any decode number; at 8–9 tokens
  `inter_token` is first-token noise — rates like 92.7 vs 85.8 are noise.
 - Radiance `timings` can carry `null` rates — `(t.get(k) or 0)`, and
  `j.get("timings") or {}`.
 - The disk prefix cache (64 GiB) survives restarts; put a random nonce at the
  HEAD of a "cold" prompt. A warm 197k prefill returns in ~10 s and looks like
  a 60,000 t/s miracle.
 - With thinking enabled, a small `max_tokens` yields empty `content` +
  `finish_reason: stop` on a healthy server; set
  `chat_template_kwargs.enable_thinking=false` in probes.
 - `echo ===` in an ssh'd zsh dies on `=`-expansion; it silently truncates the
  command chain.
 ## 5. Ship
 `scripts/<svc>.env` pair + header, serve-script header, bats gates (pair ≤
 ceiling; pool ≥ contract), docs (runbook, `AGENTS.md` fleet row, LLM index,
 log.md), `./tests/run.sh`, `deploy.sh <host> --service <svc>`, then the probes.
 Record every prediction as falsifiable in the env comment and write the verdict
 there when the probe lands — including when it kills the prediction.
@@ -0,0 +1,39 @@
 ---
 name: radiance-model-feasibility-scout
 description: "Scout whether a new GGUF model can run on radiance (R9700 fleet): GGUF header census, REUSE/ADAPT/NEW gap matrix vs radiance docs, ledgers (traffic/KV/RAM/disk), KLD-gate substitution, HTML report delivery."
 ---
 # Radiance Model Feasibility Scout
 Answer "can model X serve on radiance (dankserver R9700 TP=2), and what's the bill?" Produce an HTML report. Complements `gguf-header-vram-fit-analysis` (fit math), `radiance-w4-convert-playbook` (conversion mechanics), `radiance-quantize-and-score`.
 ## 1. GGUF header census (trust header, not the card)
 - Range-parse the header: tensor count, per-type census (type → tensor count / params / bytes), layer pattern from tensor names, `general.architecture`, `llm_type`, rope dim, expert counts, `mtp` declaration.
 - MTP: presence is decided by the **tensor-name census** (`nextn.*`/`mtp` tensors), never by metadata.
 - Confirm tokenizer + `chat_template` KV entries ship in the file; mmproj = separate BF16 tower file.
 - Cross-check total bytes vs the published file size.
 ## 2. Gap matrix vs radiance docs
 Read `PLUGIN.md` (arch-plugin contract, quantizer registry, core/mm image-pipeline law), `OPS.md` (op catalog: attention tiles h256 gqa2/4/8 + h512 gqa8, GDN, QSA, MoE, MTP), `QSA.md` (indexer decomposition bounds), `GUIDE.md` + `gguf.cpp` (dtype table 0–44: all standard GGUF grids readable — quantization happens in rad-convert, not the loader). Classify every component REUSE / ADAPT / NEW with the specific op named. The live `qwen4exp` plugin (~2k lines, QSA+MoE+mHC+GDN) is the template and the shared-header reuse list.
 ## 3. Laws checklist (recurring traps)
 - GGUF `ssm_a` = −exp(A_log); undo at convert/plugin time.
 - One-table-one-encoding: a routed-expert table takes ONE rad encoding; mixed GGUF grids (q2/q3/q4 per layer) re-quantize to w4 GPTQ + whole-expert BF16 protected set.
 - int8 trunk + int8 lm_head laws; swiglu clamp carries from the arch family; rope-free layers need no RoPE path.
 - KDA ≠ GDN: per-channel decay + 3 convs + L2-normed q/k + lower-bound gate → new kernel family (FLA `chunk_kda` is the oracle); `kkt_solve`/`chunk_scan` is the critical path.
 - MLA: latent-cache absorbed form (KV = latent width × dtype), needs its own attention tile (e.g. h512 gqa-64) + per-head v bmm.
 - llama.cpp merged PR for the arch = the ground-truth formula oracle (sign conventions, APE layout, Sinkhorn input).
 ## 4. Ledgers (all in the report)
 - Per-token weight traffic GB (trunk int8 + active experts w4 + lm_head) → decode anchored on frank-archon's measured 99 t/s @ ~6.3 GB/token; state [INFERENCE].
 - KV: per-token bytes per pool + per-seq state terms; cross-check vs any prior fleet runbook that served the same model.
 - Pinned RAM: host pool + prefix vs `LimitMEMLOCK`/`ttm-preflight.sh` law.
 - Disk peak = GGUF + `.rad` (~187 GiB-class for a 300B MoE, no PLE) vs free space; options: retire rollback payload / external convert host / `--in-place`.
 ## 5. KLD gate feasibility
 BF16 teacher = GGUF params × 2 B; if unservable (626 GB-class), the substitute gate = llama.cpp (arch PR merged in master) serving the GGUF on the Dankclaw iGPU — GTT aperture ~114 GiB — stop+mask frank-dragoon for the window, KL + top-1 census vs radiance `.rad`. Document as a gate deviation.
 ## 6. Deliver as self-contained HTML
 - Single file, inline CSS with `prefers-color-scheme` vars, section anchors + TOC, census/gap/risk/plan tables, `[INFERENCE]` labels on arithmetic.
 - Write in **chunks**: one `write` ≈ ≤8 KB (output-token limit), end each chunk with `<!--MORE-->`, then `edit` with `PUT N.=N:` where N = marker line — **prefix every body row with `+`** (bare rows get auto-prefixed; register lines like `@name` land as literal content).
 - Validate: python `html.parser` tag-balance script + grep for stray markers; `xdg-open` the file.
@@ -0,0 +1,44 @@
 ---
 name: radiance-requant-source-audit
 description: "Answer \"can we re-quantize a radiance model from what's on disk / what must we re-fetch\" before planning a heavier-or-different quant campaign: irreversibility law, live asset census, base-bound reuse rules, and the expert-mass pool-fit ceiling."
 ---
 # Radiance re-quant source audit (dank-fleet)
 Decide whether a new/heavier radiance `.rad` quant is buildable from local state, and what must be re-fetched. Run this BEFORE costing any campaign.
 ## Irreversibility law (never re-litigate)
 - Quantization is one-way: a `.rad` payload on disk is a lossy ENDPOINT. Re-encoding it upward only re-wraps its own KL error.
 - `rad-convert` takes a RAW HF checkpoint directory (safetensors) — never a `.rad`. No dequant→requant path exists in the engine (see `scripts/convert-swift15-w4dn8.sh` mount line).
 - Therefore any genuine rung change needs the high-precision checkpoint on disk. Even "more bf16-protected experts instead of wider codes" needs the bf16 tensors at convert time.
 ## Census (live, on the engine host — do not trust docs)
 ```bash
 ssh <host> 'df -h /home/dank | tail -1; du -sh /home/dank/models/* ; \
  du -sh /home/dank/corpora/calib /home/dank/corpora/kld-ref /home/dank/corpora/out; \
  cat /sys/module/ttm/parameters/pages_limit; \
  podman image exists "stilldeadcode/radiance@sha256:<serve-pin>" && echo PIN-PRESENT'
 ```
 - BF16 Swift1.5 source + fp8-native `.rad` were DELETED 2026-10-15; only the serving iq4r + w4dn8 rollback `.rad`s remain under `/home/dank/models/rad/`.
 - Survivors (verified 2026-10-17): grams `/home/dank/corpora/calib` (41 GiB), KLD ref `/home/dank/corpora/kld-ref` (24 GiB), corpora JSONL `/home/dank/corpora/out`, HF staging receipts, engine pin image local, free disk ~544 GiB.
 ## Reuse rules (what each survivor is bound to)
 | Asset | Reusable for |
 |---|---|
 | Calibration grams (RADGRAM2, down-input Hessians) | ONLY the checkpoint they were recorded from (Swift1.5) — tiers-independent, so valid for ANY new recipe tier on that same base |
 | KLD reference log-probs | ONLY same-base candidates |
 | Corpora JSONL | any base (recalibrate if base changes) |
 | Derived protected-expert list | same base only (routing is finetune-specific) |
 Reusing grams+KLD ref skips ~8 h of GPU-serve windows (calibration + KLD record).
 ## Heavier-rung pool-fit ceiling
 Expert tables for Qwen3.8-Flash-Next bill ~56 GiB (w4) → ~75 (w5/w6 class) → ~112 GiB (int8/fp8) across both ranks (from the recipe's own mass lines: gate_up 150 + down 75 GiB bf16). The one-table-one-encoding law moves the whole expert set together. Pinned host pool 43,928 MiB/rank ⇒ **only w5/w6-class rungs keep the no-streaming shape**; int8/fp8 experts overflow it and re-open the NVMe 3.5 GB/s streaming era. FP8-official-checkpoint rebuild (172.8 GB, ungated, no-recipe copy) is the cheap half-download "heavier" but carries those streaming economics.
 ## Known scored comparisons (don't re-pay for them)
 Upstream w5dn64-vs-iq4r on the official checkpoint: mean KL 0.0789→0.0717, top-1 93.34 %, decode +4 %, prefill −19 %. A custom heavier official rung reproduces this; a custom heavier Swift1.5 rung reuses the fleet's own grams/KLD assets instead.
 ## Fetch scripts (dankserver)
 - Swift1.5 BF16 335.3 GiB: `scripts/download-frank-archon-swift15.sh`
 - Official FP8 172.8 GB: `scripts/download-frank-archon.sh` (NOT bf16 — a bf16-official fetch needs a fork of it)
 - iq4r container: `scripts/download-frank-archon-iq4r.sh`
 Disk gate arithmetic: checkpoint + output both live on the volume; the campaign convert wanted ≥146 GiB free AFTER the checkpoint lands.
@@ -0,0 +1,37 @@
 ---
 name: radiance-shape-resize-verification
 description: "Verify a radiance (frank-archon) KV/slab shape change end-to-end: TTM preflight, boot ledger, boundary probe, decode ladder — with the laws that govern each axis."
 ---
 Use when changing `FRANK_ARCHON_KV_DTYPE`, `FRANK_ARCHON_MAX_SEQS`, `FRANK_ARCHON_VRAM_WEIGHTS_MIB`, or `FRANK_ARCHON_VRAM_KV_MIB` in `scripts/frank-archon.env`, and when asked why a shape change did or did not move throughput.
 ## Sequence
 1. Pool sizing first: `pool_mib >= seqs*maxlen*rate + 110*seqs + 448`, rate = 7.3125 KiB/token fp8, 13.8125 KiB/token bf16 (measured page sizes 26.00 vs 52.00 KiB + 3.25 KiB dtype-independent QSA key).
 2. Pair ceiling: `weights + kv <= 30,969` MiB/card (card 32,624 − 3,425 engine-side fixed: 2,048 activation arena, 209.19 floor, 960 driver/kernel, 224 NCCL/IPC, 96 headroom, 600 unaccounted). Settle floor is 209.19 MiB, NOT the hand-picked 1 GiB reserve.
 3. Update bats seams: pair ceiling (`FRANK_ARCHON_VRAM_CEILING_MIB`), slab floor, KV-pool contract; keep the ceiling seam owning only pair arithmetic.
 4. `./tests/run.sh` (needs bats on PATH: `/home/blank/go/bin`), commit, merge `origin/wt/<branch>` ff-only into main at **/home/blank/Projects/serverAppConfig**, push main.
 5. Deploy: `ssh dankserver 'cd /home/dank/serverAppConfigs && git pull --ff-only && ./scripts/deploy.sh dankserver --service frank-archon'` — boot 3–4 min; `--dry-run` first to confirm the plan selects exactly one service.
 6. Read the boot ledger: `journalctl -u frank-archon | grep -E "kv cache|budgeted|expert slab|resident experts|unclaimed|settled at|sampler"` — engine prints backed tokens, slab slots, host-pool slots, settle, rows.
 7. Verify contract: `ssh dankserver 'python3 /home/dank/serverAppConfigs/scripts/probe-frank-archon-kv.py'` — legs A (decode at depth), B (N×window capacity), C (prefix restore), D (N-stream decode).
 ## Laws (measured; trust over recalculation)
 - Slab is a THRESHOLD: 22,208 → 3,397, 24,000 → 3,290, 25,600 → 3,290 t/s at 43.5k; cliff at ~26 GiB (26,071 → 4,379).
 - Decode is nearly window-free: 99.0 t/s at 43.5k, 93.3 at 197k.
 - Slots are paid in decode CONCURRENCY: 3 streams = 18.4 t/s aggregate, per-stream a fused-step lottery (113.9/43.3/10.9).
 - Idle KV VRAM lends to the expert slab (fp8 pool 6,912 lent 6.08 GiB vs 2.69 at 3,543).
 - Bigger pool can LOWER prefill: more resident experts = less pinned host-pool traffic.
 - Oversized prompt is FREE and refused by name — counter `frank_archon_prompt_too_large_total` counts; refusal fires on PROMPT tokens alone ("leaves nothing to generate into"); radiance NEVER truncates.
 - TTM: serve script raises `ttm.pages_limit` to `FRANK_ARCHON_TTM_TARGET_MIB` itself (reboot resets to half RAM); unit ExecStartPre hook.
 - Refusal signature: `activating (auto-restart)`, exit 1 in ~50 ms, no container, no engine log.
 ## Probe law
 - 512 generated tokens minimum (8–24-token probes report decode noise as rate); greedy; cold prompts (unique nonce) to defeat the disk prefix cache; acceptance ~0.66–0.74 on repo corpus, repetitive filler 0.93–0.97 (never compare across corpora).
 - Radiance routes thinking to `reasoning_content`: set `chat_template_kwargs.enable_thinking=false`, read content + reasoning_content.
 - `finish_reason: "stop"` with `completion_tokens: 1` on a capacity request = accepted, not failed.
 ## Traps
 - Python heredoc over ssh: `str.maketrans` with quoted numeric literals collapses (`'0123456789'` → `'06789'`) — build alphabets with `chr(48+i)`/`chr(97+i)`.
 - `FRANK_SUDO_PW` in `/home/dank/.profile` has a CRLF tail; strip `\r` for systemd credentials (`tr -d '\r' | sudo systemd-credential ...`).
 - Deployer reports DEPLOY INCOMPLETE on a stray port-holder (`ss -ltnp | grep :7770`); never kill a root process over ssh without sudo.
 - The main checkout on the dev workstation is `/home/blank/Projects/serverAppConfig`, NOT `/home/dank/serverAppConfigs` (that path is on the servers).
 - `systemctl mask` fails on the relinked unit; `deploy.sh <host>` with no `--service` is a fleet-wide drain.
@@ -0,0 +1,28 @@
 ---
 name: recover-subagent-yield-payload
 description: "Recover a subagent's full structured report when it exited without yielding (SYSTEM WARNING) — extract aborted yield payloads from the session JSONL, including harness double-encode and split-JSON quirks."
 ---
 Use when a subagent ends with "exited without yielding" yet the transcript shows it repeatedly calling `yield` (each reply "…[+N]" — payload too big for display). The research is usually COMPLETE; only the yield serialization failed. Known harness quirk: the yield `arguments` get wrapped as `{"data": "<json string>"}`, so an object payload is validated as a string → "expected object, received string" retry loop until the agent dies.
 ## 1. Locate the session JSONL
 Transcript header prints the path: `~/.omp/agent/sessions/<cwd-slug>/<session-id>/<AgentName>.jsonl` (worktrees: cwd slug like `-.omp-wt-wt-...`).
 ## 2. Extract every aborted yield payload (Python via eval — shell quoting will mangle these)
 - Parse each line with `json.loads` guarded by try/except (lines may be non-JSON).
 - Keep `message.role == "assistant"` messages; in `content`, keep entries with `type == "toolCall"` and `name == "yield"`; collect their `arguments`.
 - Unwrap: `arguments` may be a dict containing `data` (a JSON string) or a plain string; `json.loads` it.
 ## 3. Tolerate broken JSON
 Naive `json.loads` on `data` can fail "Extra data: line 1 column ~4600" — the payload is a complete object followed by `, "architecture": ..., "report": ...}` (agent emitted a structure whose early brace-closure ended the first object). Recover with `json.JSONDecoder().raw_decode`:
 1. `part1, end = dec.raw_decode(data.strip())`
 2. `rest = data[end:].strip()` — if it starts with `,`, parse `part2 = dec.raw_decode('{' + rest.lstrip(', '))[0]`
 3. `merged = {**part1, **part2}`
 Do this for ALL yields and keep the largest merged dict (attempts evolve; keys seen: `summary`, `files`, `report`, `architecture`).
 ## 4. Persist and deliver
 Write the recovered `report`/`summary` to a durable file (memory dir or `local://`), then continue synthesis — never re-run the research the dead scout already did.
 ## Prevention (do this first next time)
 - While the agent is still alive and looping: write to `agent://<Name>` steering it to "yield immediately, wrap in minimal object or raw markdown, schema-invalid yield acceptable — I read the transcript anyway." It often still can't (the failure is in the harness wrapper, not the agent) → let it be killed and use the extraction above.
 - Scout default schema wants objects; terse yields from `scout` agents hit this most. Keep expected reports slice-sized.
@@ -0,0 +1,29 @@
 ---
 name: red-verify-without-stash
 description: "Prove a regression test is red-capable against pre-fix code in a shared worktree where git stash/checkout are policy-blocked, via git-show blob swap with md5-verified restore."
 ---
 # Red-verifying tests without `git stash`
 ## When
 You fixed a file and added tests that should have failed before the fix, but workspace policy blocks `git stash` (and `git checkout -- file`) in shared worktrees (e.g. `~/.omp` shared-workspace policy). Needed to prove red-capture instead of asserting it.
 ## Recipe
 One `bash` call — swap the fixed file for the HEAD (pre-fix) blob, run only the fix-relevant tests, restore, verify byte-identity:
 ```bash
 cd "$WT"
 md5sum path/to/fixed.file > /tmp/file-hash
 cp path/to/fixed.file /tmp/fixed.file.bak
 git show HEAD:path/to/fixed.file > path/to/fixed.file   # pre-fix content; new tests now exercise old code
 bats -f "test name A|test name B" tests/suite.bats       # expect: not ok for every fix-relevant test
 cp /tmp/fixed.file.bak path/to/fixed.file
 md5sum -c /tmp/file-hash && echo RESTORED
 ```
 ## Notes
 - `git show HEAD:path > path` truncates-and-refills the file in place; safe because you hold the md5 and a backup copy, and the restore check proves the fixed bytes are back.
 - Run only the fix-relevant tests via the runner's name filter (`bats -f` regex); a full suite wastes time and old tests pass on both versions.
 - Expect exactly the tests that pin the fix's behavior to fail pre-fix; tests unrelated to the change (pure coverage of old behavior) pass on both versions — don't count them as red evidence.
 - `bats` pipelines mask exit codes without `pipefail`; judge by the `ok`/`not ok` lines, not the shell status.
 - For non-test proof of endpoint behavior (live A/B of an HTTP request body), replay the exact body with `curl` against the live endpoint instead of speculating; keep both timings.
--- a/Show More
+++ b/Show More