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

live: heartbeat sync 2026-10-20T12:07:41-07:00 (Refs #11 )
live: heartbeat sync 2026-10-20T11:04:41-07:00 (Refs #11 )
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 · 2026-10-20 08:59:41 -07:00 · 2026-10-20 07:57:45 -07:00
39 changed files with 1274 additions and 174 deletions
@@ -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.
@@ -1,49 +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 path), plus the public Porkbun A record step and client cache gotchas."
+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."
 ---

-Use when a new `*.franksdank.cloud` service resolves publicly/LAN-needs a local address, on Dankclaw (Pi-hole v6 container, quadlet `pihole.container`).
+# Dankclaw Pi-hole LAN DNS record

-## Ground truth layout (verified 2026-10-11)
+## What this fixes

- Quadlet: `~/.config/containers/systemd/pihole.container`; volumes `/home/dank/Containers/pihole/{etc-pihole,etc-dockers,addn-hosts}`.
- **LAN records live in `/home/dank/Containers/pihole/etc-pihole/hosts/custom.list`** — plain hosts format: `192.168.0.143 gitea.franksdank.cloud`. This is the boring, working path.
- `pihole.toml` `[[dns.records]]` array is EMPTY on this host — do not expect v6 UI-style records there.
- `gravity.db` exists but has NO `domain` table (v6 layout) — do not insert local records into SQLite.
+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.

-## Procedure (30 s, proven)
+## Live truth

-```bash
-ssh dankclaw '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'
-ssh dankclaw 'getent hosts <name>.franksdank.cloud'   # must resolve
-dig +short <name>.franksdank.cloud @192.168.0.143     # from any LAN box
+- **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'
 ```

-Hosts files are read-only-readable only via sudo (dir owned by uid 100999). `sudo -n` works on dankclaw.
+Expected: `Connected to <name>.franksdank.cloud (192.168.0.143)` — LAN route, not the public IP.

-## API maze — DON'T re-explore
+## Triage: every LAN name broke at once (2026-10-19 law)

- FTL API base is `/api` at the web port (8083) **with `Host: pi.hole` header**; `/admin/api/*` → bad_request hint; bare 127.0.0.1 without the vhost → 404 `not_found`.
- Login: `POST /api/login {"password": <WEBPASSWORD from /home/dank/Containers/pihole/env>}` → session in `X-Cors` header/cookie.
- `POST /api/apps/domains/custom` → **404 on this build** (FTL version predates it); `/api/customdns/custom` also absent. There is no container sqlite3. Use custom.list.
+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.

-## Public record (off-LAN reachability)
-
-Porkbun API, keys in `/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\"}"
+```
+ssh dankclaw 'getent hosts grafana.franksdank.cloud'        # empty => FTL, not the client
+ssh dankclaw 'podman exec pihole pihole restartdns reload'   # fixes it in seconds
 ```

- `json3` path 302-redirects → **`-L` required**; no-`-s` to see status.
- Porkbun edge (openresty) intermittently 503s — transient; retry later, don't burn turns. Public record is OPTIONAL when LAN-only subscribers exist.
- Wildcard `*.franksdank.cloud` TLS is already covered: Caddy + Porkbun DNS-01 (caddy-porkbun image), so a new subdomain needs NO new cert work — just the Caddyfile site block + reload.
+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).

-## Client-side cache gotchas
+## Gotchas

- Workstation (systemd-resolved): negative cache survives Pi-hole changes; `sudo resolvectl flush-caches` needs a TTY (faillock-sensitive — no `-S` guessing). Non-interactive proof: `curl --resolve <name>.franksdank.cloud:443:192.168.0.143 https://<name>.franksdank.cloud/...`; cache self-expires (SOA negative TTL).
- Dankclaw/Dankserver resolve via Pi-hole directly — verify there first.
+- 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`
@@ -1,44 +1,44 @@
 ---
 name: dankvoice-bats-serialization
-description: "Run dankvoice bats suites without hangs: serialize builds on shared dist/, DV_HOLD is seconds, stub needs sleep&wait trap before hold, timing tests assert CALLS/at not tail PLAYS."
+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."
 ---

-# Dankvoice bats: serialization and hang-proofing
+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.

-## Serialize builds on the shared artifact
-`tests/behavior.bats` setup runs `bun run build` into the repo's shared `dist/index.js`
-before EVERY test (`DV_EXT="$REPO/dist/index.js"`). Any second concurrent bats run,
-`bun run build`, or `bun run typecheck` racing the same repo contends on that file and
-can stall single tests past 60 s. NEVER run two bats processes (or bats + build) against
-`~/Projects/dankvoice` at the same time — including harness background jobs. If a suite
-gets backgrounded, kill it before launching any other repo command; re-run serially.
+## The two serialization hazards

-## The stub player's units and traps
- `DV_HOLD` is in **seconds** (`sleep "${DV_HOLD:-0.1}"`), not ms. `DV_HOLD=1500`
-  means a 25-minute "hung" test. Use `DV_HOLD=2` for multi-second holds.
- The stub must sleep as `sleep "${DV_HOLD:-0.1}" &` + `wait $!`, with
-  `trap 'printf "KILLED\n" >> "$DV_STUB_LOG"; exit 143' TERM` installed **before** the
-  sleep: a foreground `sleep` defers the trap until the sleep finishes, so SIGTERM-kill
-  tests (shutdown/interrupt pins) stay red and every kill test eats the full hold.
- Keep the `cp *.wav "$DV_COPY"` loop when editing the stub — the byte-equality test
-  depends on it.
+### 1. `setup()` rebuilds `dist/` from `src/`
+Every test runs `cd "$REPO" && bun run build` in `setup()`. Consequences:

-## Timing-sensitive assertions
-The driver prints `PLAYS` from the stub log at scenario end (~800 ms settle), so with a
-long `DV_HOLD` in-flight playback is UNDERCOUNTED — assert `CALLS`/arrival timestamps,
-not tail `PLAYS`. The fixture stamps every request with `at=` (ms since driver start,
-comparable between CALL lines); prefetch overlap = `t2 - t1 < 1500` with `DV_HOLD=2`
-(sequential chain cannot answer inside 2000 ms).
+- **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.

-## Diagnosing a hung bats test (deterministic recipe)
-1. `timeout 45 bats -f "<name>" tests/behavior.bats; echo rc=$?` — rc=124 confirms hang.
-2. Launch the same test as a background job, then probe live:
-   `pgrep -af "driver.ts|bats"` and `ps afx | grep -E "sleep|stub"` — a `sleep <N>` child
-   with N seconds in the stub log names the culprit (usually DV_HOLD misuse).
-3. Detached `(cmd &)` inside a temp shell is KILLED when the shell exits — use the
-   harness background jobs for anything you must probe.
-4. Direct driver repro: extract the heredoc with
-   `sed -n '/cat > "$WORK\/driver.ts" <<.TS./,/^TS$/p' tests/behavior.bats | sed '1d;$d' > $W/driver.ts`,
-   build a fresh ext, then run `bun $W/driver.ts <scenario>` with the env the setup block
-   exports. Caveat: hand-made fixture env can yield different segment counts than bats —
-   trust in-bats numbers for assertions.
+### 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,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,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,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.
@@ -1,27 +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\" — the merge endpoint needs form-encoded fields, not the JSON body that PR creation accepts."
+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, `dank/serverAppConfigs`) — merge quirk, measured 2026-10-19.
+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.

-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", "Do-Not-Reply-From":…, "Reply-To":…}`) 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.
+## 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|http://[^:]*:\([^@]*\)@.*|\1|p' ~/.config/secrets/gitea | head -1)   # git credential.helper store file
-curl -sS -X POST -K <(printf 'header = "Authorization: token %s"\n' "$tok") \
+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' \
-  --data-urlencode 'Do-Not-Reply-From=chief@franksdank.cloud' \
-  --data-urlencode 'Reply-To=chief@franksdank.cloud' \
-  http://192.168.0.143:3000/api/v1/repos/dank/serverAppConfigs/pulls/<N>/merge
+  http://192.168.0.143:3000/api/v1/repos/dank/<repo>/pulls/<N>/merge
 # 200 with an empty body == merged
 ```

- `do=merge` is the field the 422 was demanding (the web-UI form field name, not an API doc field).
 - `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`.
@@ -1,29 +1,53 @@
 ---
 name: gitea-pr-api-cycle
-description: "Open/update/merge PRs and issues on the Dankclaw Gitea API (192.168.0.143:3000, dank/command-center) with the token-safe curl+jq sequence, including the {\"Do\":\"merge\"} merge payload and post-merge live-checkout fast-forward."
+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 — dank/command-center
+# Gitea PR/issue cycle — Dankclaw API

-Friction-earned 2026-10-18 across PRs #15–#20 and issue #18: three separate fumbles (jq trailer flag, 422 merge payload, silent -o/-w swallowing) codified once.
+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/command-center/{pulls,issues}`
- Token: never inline, never echoed. Extract from the git credential file into a 600-perm temp curl config:
-  `tok=$(sed -nE 's#^http://[^:/@]+:([^@]+)@192\.168\.0\.143.*#\1#p' ~/.config/secrets/gitea | head -1)`
-  `cfg=$(mktemp); chmod 600 "$cfg"; printf 'header = "Authorization: token %s"\n' "$tok" > "$cfg"` → `curl -K "$cfg"`; `rm -f "$cfg"` when done.
- Unauthenticated GET works for state reads (`GET /pulls/N` → `jq -c '{state,merged,merge_commit_sha}'`).
+- 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.

-## Body construction (the two traps)
- Build JSON with `jq -n --arg t <title> --arg b "$(cat b.txt)" '{title:$t, head:<branch>, base:"main", body:$b}'`; write the body to a temp file first (`printf '%s' … > b.txt`). NEVER pass `---` as a bare jq argument — jq parses it as a flag (`unknown flag: ---`). The AGENTS.md attribution trailer (`---` + `cwd: … · session: …`) goes INSIDE the body string.
- Always capture status explicitly: `-o r.json -w '%{http_code}'` and print it; a bare `-o` hides failures (a 422 looked like success-with-no-output once).
+## 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)
-`POST /pulls/N/merge` requires body `{"Do":"merge"}` — `Do` is the Required field on this Gitea. `{}`, `{"DoNotMerge":false}`, `{"merge_style":…}` all return 422 (`"[Do]: Required"`). Success may return an EMPTY body — verify by GET afterwards (`state=closed, merged=true`), not by the POST response.
- Merge only with Frank's explicit per-PR OK (repo law).
- Post-merge the live deployment must follow: `git -C ~/.omp fetch -q origin && git -C ~/.omp merge --ff-only origin/main` (the checkout IS the deployment; branch is `main`).
+## Merge (the 422 trap) — corrected
+`POST /pulls/N/merge` needs **form-encoded** fields; the merge form field name is lowercase **`do`**:

-## PR etiquette per AGENTS.md
- Immediately after opening: `xdg-open <PR-URL>` lands it in Frank's Firefox.
- Redesign mid-review: amend + `git push -f` the branch, then PATCH the PR body (`/pulls/N`, `{"body":…}`) so title/body match the net diff — verify `{number,state,mergeable}` in the response.
- Issue creation identical shape: `POST /issues` with `{title, body}`, expect 201; PATCH same endpoint `/issues/N` to fix bodies retroactively, then GET-readback verify.
+```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,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,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,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,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,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,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,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,68 +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/read may have landed in the wrong checkout: which path forms bind where, how to detect with git -C status, and the repair protocol (cp + git show HEAD blob write-back) because git checkout/restore is policy-blocked in a shared workspace.\""
+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."
 ---

-# Concurrent-worktree path hazard (shared repo, many agents)
+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.

-Measured 2026-10-18 on `serverAppConfigs` with two agents live at once. The
-failure is **silent**: the tool reports success, the diff looks right, and the
-change lives in a *different* worktree.
+## The silent failure: relative tool paths resolve to the SESSION cwd

-## Which path form binds where
- **Parent/top-level session**: a **relative** `path` resolves against the
-  session CWD — its own worktree — never against the worktree named in the
-  prompt. This is how a change meant for `wt-tts-trial-docs` landed in
-  `wt-20261017-…`.
- **Subagent**: an **absolute** path to its own assigned worktree can resolve
-  into the parent's worktree when the same *relative* path exists there
-  (`edit` twice onto `dankclaw/.env.example`). Its `write` with the same
-  absolute path was fine — the bug is `edit`/`read` path resolution, not `write`.
+`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.

-Rules that hold:
-1. A subagent passes paths as `../<its-worktree>/<rel>` (relative to the parent
-   worktree) for `read` **and** `edit`; the parent passes **absolute** paths to
-   any worktree that is not its own CWD.
-2. After every edit batch, prove the landing site, do not trust the tool's echo:
-   `git -C <intended-worktree> status --short` must list the file. A file you
-   edited that is missing from that list went somewhere else.
-3. Keep each work item on its own branch/worktree, and keep ONE integration
-   owner (the parent) for shared files — `scripts/deploy-remote.sh`,
-   `scripts/deploy-plan.py`, `tests/`, `serverAppConfigs-docs/index.md`,
-   `AGENTS.md` are the collision hot spots in this repo. Never rebase a
-   sibling's branch.
+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.

-## Repair protocol (no `git checkout`, no `git restore`)
-`git checkout -- <path>` and `git restore <path>` are **policy-blocked** in a
-shared workspace ("overwriting working-tree files … discards changes other
-concurrent agents rely on"). Unstaging (`git reset [<path>]`,
-`git restore --staged <path>`) is allowed but does not undo content. So:
+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.

-```bash
-F="path/with spaces if any"
-# 1. move the change to the worktree that should own it (both at the same base commit)
-cp "<wrong-wt>/$F" "<right-wt>/$F"
-# 2. undo in the wrong worktree by writing the committed blob back
-git -C "<wrong-wt>" show "HEAD:$F" | tee "<wrong-wt>/$F" > /dev/null
-# 3. prove both sides
-md5sum <(git -C "<wrong-wt>" show "HEAD:$F") "<wrong-wt>/$F" "<right-wt>/$F"
-git -C "<wrong-wt>" status --short          # must be empty for that file
-git -C "<right-wt>" diff --stat             # must show the intended delta
-```
+## Landing a change when the session worktree is stale

-Never fix it blind: if the wrong worktree had its own uncommitted edits to that
-file, `cp`/blob-write-back would destroy them — check
-`git -C <wrong-wt> status --short` FIRST and reconcile content, don't overwrite.
+`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.

-## Tidy after a cancelled sibling
-A killed subagent can leave a worktree plus an empty branch. Removing them is
-safe only when verified empty: `git -C <main> log --oneline -3 <branch>` (no
-unique commits) and `git -C <wt> status --short` (clean), then
-`git worktree remove <wt>` + `git branch -D <branch>`. An orphan worktree at a
-stale commit is the same class of trap as a leftover bench drop-in: the next
-agent reads it as unfinished work.
+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.

-## Report it
-File the misresolution to `xd://report_issue` (false positives are fine) and
-record the incident in the repo worklog — a repair nobody wrote down looks like
-a hijack later.
+## 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.
@@ -1,6 +1,6 @@
 ---
 name: plugin-git-install-committed-artifact
-description: "Use when shipping an omp/pi plugin for omp plugin install git: — the installer clone fails validation (missing build artifact) or silently reuses a stale bun git-mirror cache; recipes for committing dist + drift pins + cache purge."
+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
@@ -42,6 +42,20 @@ GIT_TERMINAL_PROMPT=0 git clone -q <url> /tmp/x && git -C /tmp/x log --oneline -
 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.
@@ -28,14 +28,14 @@ site-packages/flexml/flexml_extras/lib : site-packages/onnxruntime/capi : site-p
 1. `ldd <deployment>/lib/libonnxruntime_providers_ryzenai.so | grep -E "libxrt_coreutil|libryzen_mm"` — the resolved path settles it alone: `/opt/xilinx/xrt/lib` = good, `.../voe/lib` = this bug.
 2. `XILINX_XRT=/opt/xilinx/xrt /opt/xilinx/xrt/bin/xrt-smi examine` → `RyzenAI-npu5 | aie2p | 6x8` + `NPU Firmware Version`. Needs `libboost_filesystem1.83.0`, `libboost_program_options1.83.0`, `libuuid1` (26.04 names; the 24.04 docs' 1.74.0 does not exist). A "No such file or directory" for a file that exists = missing interpreter/dep, not a missing binary.
 3. `strace -f -e trace=openat` — `/dev/accel/accel0` never opened ⇒ failure is pre-device ⇒ loader-level.
-4. `gdb -q -batch -x <(echo 'catch throw'; echo run; echo 'bt 10')` style catch-throw loop → names `shim_loader` / `Allocator::Alloc`.
+4. `gdb -q -batch` with `catch throw` + `bt 10` loop → names `shim_loader` / `Allocator::Alloc`.

-Known dead ends (each costs one run to rule out, then stop): `--ulimit memlock`, XRT INI verbosity, `DD_LOG_LEVEL` / `RYZENAI_TRACE` / `RYZENAI_EP_TRACING` (print nothing before the throw), byte-scanning XRT `.so` for PCI IDs (ambiguous), libboost presence for the OGA path (only `xrt-smi` needs it), flag-by-flag container matrices (`--memory`, `--security-opt`, `--name`, extra mounts — all innocent).
+Known dead ends (one run each, then stop): `--ulimit memlock`; XRT INI verbosity; `DD_LOG_LEVEL` / `RYZENAI_TRACE` / `RYZENAI_EP_TRACING` (print nothing before the throw); byte-scanning XRT `.so` for PCI IDs (ambiguous); libboost presence for the OGA path (only `xrt-smi` needs it); flag-by-flag container matrices (`--memory`, `--security-opt`, `--name`, extra mounts — all innocent).

 ## Verified facts on this stack

- Vendor XRT 2.25.37 userspace (`dpkg-deb -x`, never dpkg-installed) works against Ubuntu's **in-tree `amdxdna` 0.7.0`; no DKMS module needed. `1022:17f0` rev 11 = XDNA2, handled as `aie2p 6x8`.
+- Vendor XRT 2.25.37 userspace (`dpkg-deb -x`, never dpkg-installed) works against Ubuntu's in-tree `amdxdna` 0.7.0; no DKMS module needed. PCI `1022:17f0` rev 11 = XDNA2, reported as `aie2p 6x8`.
 - AMD's `quicktest` passing does **not** prove NPU use (it can silently run on CPU); trust `xrt-smi` + logits, not "it didn't crash".
 - `/dev/accel/accel0` is `root:render 0660`; rootless podman cannot read it (userns drops the gid; `keep-groups`, `keep-id:gid=990`, `--group-add render` all fail) → rootful container, or a udev rule like the GPU nodes'.
 - OGA 0.14 (RAI 1.8) contract: `GeneratorParams` has only `set_search_options` (no `input_ids`, no `model.generate`); feed with `Generator.append_tokens(ids)`, loop `generate_next_token()`, read `get_sequence(0)`; `max_length` counts **prompt + generated**. Full Fusion (`*_npu_4K`) caps input+output at 4096.
- Validate the *content*, not just the exit code: `np.argsort(logits[0])[-8:]`. `append_tokens` returning a real logits tensor proves the graph ran; if argmax is the sequence terminator (`
+- Validate content, not just exit code: `np.argsort(logits[0])[-8:]`. A real logits tensor after `append_tokens` proves the graph executed (prefill is folded into step 1, so a sub-millisecond first step + a 1-token sequence means it did not); if argmax is the sequence terminator (`
@@ -1,6 +1,6 @@
 ---
 name: ryzenai-npu-oga-linux-spike
-description: "Run a vendor-compiled AMD Ryzen AI (XDNA2) ONNX-GenAI model on a Linux Strix Halo host from public artifacts: staging, rootless NPU device-access wall, container recipe, and the NuTTS-air speech-token contract."
+description: "Run an AMD-precompiled AMD Ryzen AI (XDNA2) ONNX-GenAI model on a Linux Strix Halo host from public artifacts: staging, rootless NPU device-access wall, container recipe, and the NuTTS-air speech-token contract (65,536-code vocab, 50 codes/s real-time line)."
 ---

 Run an AMD-precompiled XDNA2 model (OGA / onnxruntime-genai) on a Linux Strix Halo host (Dankclaw-class) without installing the vendor stack on the host.
@@ -19,10 +19,12 @@ Tarball has 30 top-level entries: cp312/linux_x86_64 wheels (`onnxruntime_genai_
 - **Rootless containers cannot read `/dev/accel/accel0`** (`root:render 0660`): the host gid never enters the userns gid map, so `--device` yields `nobody:nogroup`. Verified failing 2026-10-19: `--group-add keep-groups`, `--userns=keep-id`, `--userns=keep-id:gid=990` (process gets gid 990, node still unreadable), `--group-add render`, `--group-add gid:990` (both error). Options: run rootful (`sudo podman`, separate storage → rebuild the image rootful, ~1 min), or add a world-writable udev rule for `accel0` (the fleet already does exactly this for `kfd`/`renderD*` in `99-comfyui-gpu-access.rules`, whose header explains why: systemd user-unit spawns carry no supplementary groups).
 - **Rootless image build trap:** the vendor installer's `tar -xf` preserves recorded uids (95777 etc.) and aborts under `set -e` with `Cannot change ownership ... Invalid argument`, silently skipping the `deployment`/`onnxruntime` extraction. Patch it in the Containerfile: `sed -i 's/tar -xf/tar --no-same-owner -xf/g' install_ryzen_ai.sh`.
 - Installer usage: `./install_ryzen_ai.sh -a yes -p /opt/rai -c /opt/rai` (python **3.12** required; base `python:3.12-slim`; needs `linux-libc-dev zip pciutils patch libgomp1`). It builds a venv from the local wheels, reinstalls `onnxruntime-vitisai` then `--no-deps onnxruntime-genai-ryzenai`, installs `requirements_extras.txt` (transformers 4.57.6), patches `bin/activate` (sets `RYZEN_AI_INSTALLATION_PATH=$VIRTUAL_ENV` + `LD_LIBRARY_PATH` into site-packages), and untars `LLM/deployment/onnxruntime/voe/quicktest` into the cpp path.
+- `xrt-smi` in a container needs `libboost-filesystem1.83.0` + `libboost-program-options1.83.0` (**hyphenated** Ubuntu names) and `apt update` first; boost is **only** needed by `xrt-smi`, never by the OGA/EP path.

 ## HF artifact staging

 - Gated (401 on API, 403 on git) for a plain account: `neuphonic/neucodec` (the **only** NeuCodec encoder), `neuphonic/neucodec-onnx-decoder`, `neuphonic/neucodec-onnx-decoder-int8`, `neuphonic/neutts-air`. `amd/neutts-air_rai_1.8.0_npu_4K` is public. Public mirrors of the codec exist (`eugenehp/neucodec` has the full 1.16 GB `pytorch_model.bin`) — treat a mirror of a gated release as a licensing decision for the operator, not a workaround to take silently.
+- Gated-repo loader trap: `HF_HUB_OFFLINE=1` + `HF_HOME` pointed at a cache laid out as `hub/models--<org>--<repo>/snapshots/<rev>/…` works, but `NeuCodec._from_pretrained` **asserts the repo id** is in `["neuphonic/neucodec", "neuphonic/distill-neucodec"]` — a local directory path is refused outright, so pass the repo id and satisfy it from the cache.
 - `github.com/neuphonic/neutts` is public and ships `samples/{dave,emily,greta,jo}.{pt,txt,wav}` = **pre-encoded reference codes + transcripts** → a spike needs zero gated bytes.
 - Auth without leaking the token into `ps`: build a 600-perm credential file with a shell builtin and point git at it —
  `umask 077; printf 'https://oauth2:%s@huggingface.co\n' "$(cat ~/.cache/huggingface/token)" > ~/.git-credentials-hf`
@@ -30,14 +32,30 @@ Tarball has 30 top-level entries: cp312/linux_x86_64 wheels (`onnxruntime_genai_

 ## NuTTS-air on XDNA2 (the model-side contract)

- The package is an OGA model dir: `genai_config.json` (`type: qwen2`, 24 layers, hidden 896, 14 heads / 2 KV, ctx 32768, `provider_options: [{"RyzenAI": {"hybrid_opt_token_backend": "npu"}}]`), plus `dd_metastate_*` AIE artifacts and `model.onnx` + `model.onnx.data`.
- **Speech tokens live in the text vocab**: `<|speech_0|>` = id 151671 (10 001 codes), with `<|TEXT_PROMPT_START|>` 151666, `<|TEXT_PROMPT_END|>` 151667, `<|TEXT_REPLACE|>` 151665, `<|SPEECH_REPLACE|>` 151668, `<|SPEECH_GENERATION_START|>` 151669, `<|SPEECH_GENERATION_END|>` 151670. Generation is a plain `og.Generator` loop; the graph's own `eos_token_id` is `[151645, 151643]`, so pass 151670 as an extra eos or stop on it manually.
- **Real-time line = 50 speech tokens/s** (`sample_rate=24000`, `hop_length=480`). Judge any NPU/iGPU TTS number against 50.
+- The package is an OGA model dir: `genai_config.json` (`type: qwen2`, 24 layers, hidden 896, 14 heads / 2 KV, ctx 32768, `vocab_size` **217,652**, `provider_options: [{"RyzenAI": {"hybrid_opt_token_backend": "npu"}}]`), plus `dd_metastate_*` AIE artifacts and `model.onnx` + `model.onnx.data`.
+- **Speech tokens live in the text vocab, and the codebook is 65,536 — not 10,001.** `tokenizer.json` `added_tokens` holds exactly 65,536 `<|speech_N|>` entries, ids **151,671–217,206** contiguous, over a base BPE vocab of 151,643; specials are 151,644–151,670 (`<|SPEECH_GENERATION_END|>` = 151,670). The vendor template maps a codec index straight to its id: `"".join(f"<|speech_{i}|>" for i in ref_codes)`. An encoded reference really does contain codes in the 60k range, so a 10k assumption silently truncates the space.
+- The graph's own `eos_token_id` is `[151645, 151643]` (the **chat turn** stop) and `search.eos_token_ids` is unset — pass 151,670 as an extra eos or speech ends after one token.
+- **Real-time line = 50 speech codes/s** — NeuCodec `sample_rate 24000 / hop_length 480`, measured exactly (49.96–50.00 across three 20–25 s references). Judge any NPU/iGPU TTS number against 50. (Qwen3-TTS, the fleet's deployed arm, is 12.5 codes/s — do not conflate the two bars.)
+- Reference encode is cheap and cacheable: `librosa.load(sr=16000, mono=True)` → `[1,1,T]` float tensor → `codec.encode_code(audio_or_path=…)` (mirrors `NeuTTS.encode_reference`); CPU encoder RTF 0.28–0.38 on 8 threads. `neucodec` needs `torchtune` (`RotaryPositionalEmbeddings`) — install both `--no-deps --target <dir>` so a second torch never shadows the venv's.
 - Build the prompt by *importing* the vendor function, never by copying the template:
  `sys.path.insert(0, <neutts repo>); from neutts.neutts import NeuTTS`, then
  `NeuTTS._apply_chat_template(SimpleNamespace(tokenizer=hf_tok, input_format="text"), ref_codes, ref_text, text, None)` — works on a duck-typed `self`, so no backbone/codec load. Template: `user\n<|TEXT_REPLACE|>\nassistant\n<|SPEECH_REPLACE|>`; splice `TEXT_PROMPT_START + encode(f"{ref_text} {text}") + TEXT_PROMPT_END` at TEXT_REPLACE, then truncate at SPEECH_REPLACE and append `[SPEECH_GENERATION_START] + encode("".join(f"<|speech_{i}|>"))`.
- Voice identity = reference codes + transcript (request-time conditioning). No trained artifact exists to preserve; packs holding only `reference.wav` require the gated encoder once, offline.
+- Voice identity = reference codes + transcript (request-time conditioning). No trained artifact exists to preserve; packs holding only `reference.wav` require the gated encoder once, offline — **and** a transcript, which a voice pack does not carry (`manifest.json` holds provenance/crop geometry only) and a host without ASR cannot produce.
+- Full-Fusion input ceiling: 4096 tokens **total**, input + output.

-## Status caveat
+## Status caveat (2026-10-19)

-Measured on 2026-10-19 up to and including: staged artifacts, image build, device-access matrix, prompt contract. The token-rate measurement (does the vendor userspace drive the in-tree 0.7.0 driver, and does it clear 50 tok/s) is **not** captured here — re-measure, never trust a remembered rate.
+Staged artifacts, image build, device-access matrix, prompt contract, reference pre-encode:
+**done and reproducible.** Token generation on the NPU: **NO-GO, and the loader is the
+wall.** The device is healthy (`xrt-smi validate` PASSED incl. `throughput`,
+`RyzenAI-npu5 / aie2p / 6×8`, `pyxrt.device(0)` constructs), and `strace` shows the
+failing load reading `genai_config.json`, opening `model.onnx`, loading
+`libxrt_driver_xdna.so.2` and opening `/dev/accel/accel0` with successful GEM ioctls —
+then the RyzenAI EP **declines the graph before touching any `dd_metastate_*`**, silently:
+`GENAI_ORT_VERBOSE_LOGGING`, `GENAI_LOG_ORT_LIB`, `set_log_options`,
+`set_log_callback(callable)`, `RYZENAI_EP_TRACING`, `RYZENAI_LLM_PROFILE_INIT` all emit
+zero lines. Hardlinked mirror dirs of the model tree were ruled out as shadowing. One run
+loaded and produced finite logits; byte-identical runs never reproduced it. **No token rate
+was ever measured, so quote none**, and remember `quicktest` success ≠ NPU residency (that
+build falls back to CPU silently — prove residency via
+`/sys/class/accel/accel0/device/mem_usage`).
@@ -0,0 +1,116 @@
+---
+name: ryzenai-oga-model-dir-and-eos-override
+description: "Debug OGA on XDNA2 when the RyzenAI EP never claims the If-rooted graph (shadow model dirs, bind-mounted configs, missing device), or a TTS/LLM graph stops on the wrong eos token."
+---
+
+# OGA on XDNA2: graph not claimed, or generation stops at once
+
+Two independent failure families in the AMD `onnxruntime-genai` (OGA) + RyzenAI EP stack on
+Linux XDNA2 (Strix Halo / Ryzen AI Max). Diagnose them in this order — they are separate
+gates and each has its own instrument.
+
+## Gate 0 — is the NPU path alive at all?
+
+Run the vendor's own instrument before touching anything else:
+
+```bash
+cd /opt/rai/quicktest && RYZEN_AI_INSTALLATION_PATH=/opt/rai python quicktest.py
+# want: "Setting environment for STX/KRK" ... "Session successfully initialized" ... "Test Finished"
+```
+
+It finds the device by shelling out to `lspci -nn` and grepping `1022:17f0`, so it also
+proves `lspci` is present in the container. Pass ⇒ the in-tree `amdxdna` driver and the
+extracted userspace pair correctly; stop blaming the host.
+
+Separate **XRT enumeration** from **OGA's device probe** — they are not the same check:
+
+```python
+import sys; sys.path.insert(0, "/opt/xilinx/xrt/python")
+import pyxrt; dev = pyxrt.device(0)   # constructs => XRT sees the device
+```
+
+`pyxrt.device(0)` succeeding while OGA says `No RyzenAI devices detected` means the
+refusal is OGA's own predicate, inside `libonnxruntime-genai.so` (the string lives there,
+next to `RyzenAI`, `max_length_for_kv_cache`, `library_path`). EP-side env levers worth
+pulling: `RYZENAI_EP_TRACING`, `RYZENAI_EP_PERFORMANCE_COUNTERS`, `RYZENAI_LLM_ASYNC_INIT`,
+`RYZENAI_LLM_PROFILE_INIT`.
+
+## Gate 1 — `invalid model … Node (If) cond_full`
+
+This is **ONNX Runtime verifying the raw graph**, which happens when no provider claimed
+it: the EP registered nothing and the CPU provider was left holding an `If` whose branches
+mismatch. It is never a corrupted model.
+
+```bash
+LD_DEBUG=files LD_DEBUG_OUTPUT=/tmp/ld python loadprobe.py
+grep -a "calling init:.*ryzenai\|undefined symbol" /tmp/ld.*
+# observed: libonnxruntime_providers_ryzenai.so loaded, then
+#   symbol lookup error: undefined symbol: GetProvider (fatal)
+```
+
+`GetProvider` is not a dynamic symbol in the ORT cores, the shared-provider stub, or the
+EP (`nm -D` shows neither defines nor wants it), so the failure is registration, not an
+ELF mismatch. Confirm the cores are identical before chasing versions: both shipped
+`libonnxruntime.so.1.27.0` copies hash equal.
+
+Separate the two gates with an explicit global-scope load before importing OGA:
+
+```python
+import ctypes
+ctypes.CDLL("/opt/rai/deployment/lib/libonnxruntime_providers_ryzenai.so",
+            mode=ctypes.RTLD_GLOBAL)
+import onnxruntime_genai as og
+og.Model(MODEL)   # registration fixed => error MOVES to "No RyzenAI devices detected"
+```
+
+An error that **moves** proves you cleared one gate and exposes the next. Silence in the
+first form means the provider list was empty.
+
+### Dead ends (measured, do not retry)
+
+- **Shadow model dirs never work.** Hardlink mirror, symlink mirror, and even a
+  read-only single-file bind mount of a patched `genai_config.json` over the export's own
+  `genai_config.json` all produce the same `If` rejection. The graph is only claimable
+  when loaded from the export's own directory, and there is no config-path override in
+  `0.14.0-dev`: the only env names in the shipped binaries are `GENAI_LOG_ORT_LIB`,
+  `GENAI_ORT_VERBOSE_LOGGING`, `OG_ORT_LIB`. Carrying a config change therefore means
+  either editing the download in place or a **single-file bind mount over the real dir**
+  (`-v file.json:/spike/<model>/genai_config.json:ro`) — and if the EP still refuses, the
+  gate is not the config.
+- **Bisect the image before believing "environment drift".** Run the same load probe
+  against every local tag; three tags failing identically rules the image out.
+- **Rule out host state with instruments, not memory:** `fuser -v /dev/accel/accel0`,
+  `dmesg | grep -i xdna`, `stat -c "%i %y"` on the model files, `df -h`, `free -g`.
+- `sysfs` class is `accel`, not `misc`: glob `/sys/class/accel*/*`. An empty
+  `/sys/class/misc/accel*` is your glob, not a missing device.
+- `GENAI_ORT_VERBOSE_LOGGING=1` and `og.set_log_options(...)` produce nothing useful in
+  this build; `set_log_options` is a pybind builtin (no `inspect.signature`) and rejects
+  `severity` as an int. Don't burn turns trying to make it talk — use `LD_DEBUG`.
+- `strace` is absent from the RAI image and `apt` may have no mirror: `LD_DEBUG=files` is
+  the loader tracer that needs nothing installed.
+
+## Gate 2 — generation stops after one token
+
+OGA reads its stop list from the **model** section: `model.eos_token_id`. Chat exports
+carry the chat-turn-close id (e.g. 151645) there, so the model emits it first and the
+speech/tool budget is never spent — while `search` has **no** eos key: writing
+`search.eos_token_id` is a parse refusal (`Unknown value "eos_token_id"`), not a no-op.
+
+- Fix: rewrite `model.eos_token_id` to only the task's own end token (TTS: the
+  speech-generation-end id), or pass it through `set_search_options` if the build accepts
+  that key name.
+- A sub-millisecond `generate_next_token()` **with finite, high-confidence logits** means
+  the graph ran and chose a stop token — it is not evidence of a CPU fallback.
+- Verify a token-range census against the export's `added_tokens.json`, not against a
+  guessed vocabulary size: NeuCodec codes reach 65,536 entries (ids 151671…217206), and a
+  census bounded at 10k silently miscounts every code as a text token.
+- A hardlinked run dir is a loaded gun: `open(dst, "w")` on a hardlink truncates the
+  **original** through the shared inode. `os.unlink` the link before writing a patched
+  file. Also skip `.git/` and mirror directories when walking an HF checkout.
+
+## Rate measurement
+
+Once a load succeeds, measure at ≥300 steps with a host-side `%CPU` sampler beside the
+container (`ps -C python -o pid=,pcpu=,rss=` every 2 s): a device-bound decode waits on
+`accel0` and stays under one core, a silent CPU fallback pegs at least one. Never report
+request #1 after a boot — graph capture makes it a warmup artifact.
@@ -1,13 +1,13 @@
 ---
 name: strix-halo-npu-readiness-census
-description: "Engine-agnostic census of whether an AMD Strix Halo / Ryzen AI host can run anything on its XDNA2 NPU: driver bind, firmware, device perms, IOMMU, distro XRT, missing AIE compiler, fabric clock, RAM headroom."
+description: "Engine-agnostic census of whether an AMD Strix Halo / Ryzen AI host can run anything on its XDNA2 NPU: driver bind, firmware, device perms, IOMMU, distro XRT, missing AIE compiler, fabric clock, RAM headroom — plus the strace test that separates a dead device from a runtime that declines the graph."
 ---

 Use when asked "can we run <engine/model> on the Strix Halo / Ryzen AI NPU?" for a runtime that is **not** halogen (halogen has its own gate + vendor catalog: use `halogen-npu-feasibility-census` for that). This answers only: is the *host* able, and what is missing.

 ## Why it is usually the wrong door first

-XDNA2 executes **precompiled AIE partition programs** loaded through XRT → `amdxdna`. There is no generic tensor dispatch: an engine built on ggml/llama.cpp (or any GGUF loader) cannot "enable" the NPU — the port must be a re-export + vendor compile, not a flag. So pair this census with the accelerator the same engine *can* select by build flag (Vulkan/HIP on the gfx1151 iGPU) before proposing NPU work.
+XDNA2 executes **precompiled AIE partition programs** loaded through XRT → `amdxdna`. There is no generic tensor dispatch: an engine built on ggml/llama.cpp (or any GGUF loader) cannot "enable" the NPU — the port must be a re-export + vendor compile, not a flag. So pair this census with the accelerator the same engine *can* select by build flag (Vulkan/HIP on the gfx1151 iGPU) before proposing NPU work. On Dankclaw the iGPU flag was ours to flip all along (`-DGGML_VULKAN=OFF` written out in the fleet's own engine Containerfile) — check the engine's own build file before treating the NPU as the only hardware door.

 ## Census (all read-only, over ssh from the operator box)

@@ -37,8 +37,20 @@ nproc; free -g | head -2                                      # RAM headroom + t
 - No `ryzenai-compile`/ONNX Ryzen AI EP ⇒ nothing on the host can produce a partition program. That is the enablement delta, and it is a toolchain install + a model-specific export/quantize/compile project, not a config change.
 - `free` headroom matters: NPU partitions want a few GB of host RAM each and can log benign `Failed to alloc dev bo memory, ret -28` under pressure.

+## Device healthy, load still fails? Classify before blaming the hardware
+
+Two different failures, one call apart. Run the load under `strace -f -e trace=openat`:
+
+- **Never opens `/dev/accel/accel0`** ⇒ pre-device: loader/shim/env (see `ryzenai-npu-oga-linux-run` — the `Generic Failure` in ~2 ms is this class).
+- **Opens `/dev/accel/accel0`, GEM ioctls succeed, then the EP declines** ⇒ post-device: the *runtime* rejects the graph. The device is innocent; stop the hardware investigation and fix the last file it opened (`model.onnx` = graph rejected; `dd_metastate_*` = partition artifact problem).
+
+Ground truth that the device itself is sound, inside the container: `xrt-smi examine` (expect `RyzenAI-npu5 | aie2p | 6x8` + firmware version) then `xrt-smi validate` — `PASSED` incl. `throughput`. Needs `libboost-filesystem1.83.0` + `libboost-program-options1.83.0` (**hyphenated** Ubuntu names, after `apt update`); boost is required by `xrt-smi` only, never by the OGA/EP path. Vendor `quicktest` printing success does **not** prove NPU residency (that build falls back to CPU silently) — sample `/sys/class/accel/accel0/device/mem_usage` during generation instead.
+
+When the vendor runtime declines silently, exhaust its own levers and then say so: `GENAI_ORT_VERBOSE_LOGGING`, `GENAI_LOG_ORT_LIB`, `set_log_options`, `set_log_callback(callable)`, `RYZENAI_EP_TRACING`, `RYZENAI_LLM_PROFILE_INIT` all produced zero lines on the 2026-10-19 NuTTS-Air decline. Rule out shadowed artifacts by moving hardlinked mirror copies out of the scanned tree (glob-based sibling scans) — if the failure is byte-identical afterwards, that theory is dead. **If a load ever succeeded once and the byte-identical command never reproduces it (files pristine by inode+mtime), that is a NO-GO, not a lead: no rate may be quoted for a run that cannot be repeated.**
+
 ## Laws / traps

 - Read state only. Never probe or load the NPU beside a live inference service — stop + mask the service first (fleet benching policy); this host class has a precedent of a concurrent GPU/NPU experiment needing a power cycle.
 - `sudo podman ...` finds nothing (per-user rootless storage); run podman as the deploy user.
 - `/dev/accel/accel0` existing does not mean a context/PASID can be created; with IOMMU off the failure is at context creation, not at the node.
+- Rootless containers cannot read `accel0` (`root:render 0660`) by any documented flag combination — rootful, or a world-writable udev rule.
@@ -0,0 +1,31 @@
+---
+name: tts-endpoint-parameter-capability-audit
+description: "Determine which request parameters a fleet TTS endpoint actually honors by probing façade and engine separately, with a nondeterminism control, instead of trusting docs or byte diffs."
+---
+
+Use when asked whether a TTS (or other OpenAI-compatible shim) endpoint supports a parameter — mood, tone, instructions, speed, seed — or when a request "seems to" change the audio. Docs and single-request comparisons both lie; audit the layers.
+
+## Why the naive checks fail
+- **Byte-size diffs are meaningless.** Synthesis is nondeterministic: three byte-identical requests to frank-tts came back 107564 / 134444 / 111404 bytes (~±15 % length). "The mood file differs from the baseline" proves nothing.
+- **HTTP 200 proves nothing.** A shim that rebuilds its own payload answers 200 to `speed:"banana"` because it never looks at the field.
+- **A façade can drop fields the engine supports**, so testing only the published port under-reports capability.
+
+## Procedure
+1. **Read the shim's parse block** (which request keys it reads) — not its docstring:
+   `ssh -o BatchMode=yes dankclaw 'podman exec frank-tts grep -nE "body\.get|payload = |json\.loads" /app/app.py'`
+   Whatever keys appear there (plus what it forwards in its own `payload = {...}` dict) is the real published contract.
+2. **Enumerate the engine's key table from the binary** (works with no `strings` in the image):
+   `podman exec <engine> sh -c 'grep -aoE ".{60}instructions.{60}" /app/tts-server | head -2'`
+   Adjacent tokens come out as a run — that run IS the accepted-key list (`...instructions response_formatspeedseedmax_new_tokensrepetition_penalty subtalker_top_k subtalker_temperature ...`). Also `podman exec <engine> /app/tts-server --help`, and `podman inspect <c> --format "{{json .Config.Entrypoint}}"` to find the binary.
+3. **Reach the engine directly** when its port is unpublished: `TTS_UPSTREAM` in `podman inspect <shim>` gives the real in-network address (`http://frank-tts-engine:8880`, not `host.containers.internal`). No curl/python on the host? Pipe a script into the container that has one: `podman exec -i frank-tts python3 - <<'PY' ... PY`.
+4. **Control for nondeterminism before claiming an effect**: repeat the identical request twice as the control; only compare conditions separated by far more than the jitter, and prefer an error response (a 400 naming the unsupported flag) as the decisive evidence.
+
+## Findings for the dank fleet (verify before trusting — they move)
+- Published façade `:7772` reads only `model`, `input`, `voice`/`voice_id`, `response_format`; it rebuilds the payload, so `speed` and every unknown field are dropped before the engine.
+- Engine (`frank-tts-engine`, qwentts.cpp, qwen-talker-1.7b-**base**, Vulkan) accepts `instructions`, `speed`, `seed`, `max_new_tokens`, `repetition_penalty`, `subtalker_top_k/_temperature/_top_p`, but answers `400 "--instruct is not supported for base models"` for `instructions` on the base checkpoint. `seed` does not make output reproducible.
+- Therefore tone/mood must be produced in the **text layer** (prompt directives), not the TTS request; and `speed` needs a two-line façade fix if tempo control is ever wanted.
+
+## Verification habits
+- POST with a wrong *type* (`speed:"banana"`) to learn whether anything validates, and with a bogus `voice` to see the error shape (`available_voices` came from the engine, not the shim).
+- Plain GET of `/v1/audio/voices` for the roster.
+- Read-only probes of the fleet are always allowed; synthesis requests are transient GPU work, keep them to a handful.
@@ -0,0 +1,4 @@
+{
+	"v": 1,
+	"lastConsolidatedAt": 1792441535971
+}
@@ -0,0 +1,4 @@
+{
+	"v": 1,
+	"lastConsolidatedAt": 1792441746823
+}
@@ -0,0 +1,4 @@
+{
+	"v": 1,
+	"lastConsolidatedAt": 1792443092036
+}
@@ -1,4 +1,4 @@
 {
 	"v": 1,
-	"lastConsolidatedAt": 1792401025778
+	"lastConsolidatedAt": 1792526055797
 }
@@ -1,4 +1,4 @@
 {
 	"v": 1,
-	"lastConsolidatedAt": 1792439491829
+	"lastConsolidatedAt": 1792469747088
 }
@@ -1,6 +1,6 @@
 {
 	"v": 1,
-	"lastConsolidatedAt": 1792440990901,
+	"lastConsolidatedAt": 1792524715562,
 	"lastResult": {
 		"at": 1792433353188,
 		"sessions": 1,
@@ -0,0 +1,6 @@
+## Agent Output Patterns
+
+- Typed intro: "Update, [randomly generated epithet]!"
+- Heckle mode option
+- Typed outro: "More later, over and out!"
+- Generation frequency control
@@ -1,4 +1,10 @@
 {
 	"v": 1,
-	"lastConsolidatedAt": 1792441029706
+	"lastConsolidatedAt": 1792524641573,
+	"lastResult": {
+		"at": 1792452243238,
+		"sessions": 1,
+		"deltas": 4,
+		"model": "frank-zealot"
+	}
 }
@@ -0,0 +1,4 @@
+{
+	"v": 1,
+	"lastConsolidatedAt": 1792527016734
+}
@@ -275,13 +275,13 @@ transition = [ "fade" ]
    interval_seconds = 1200

    [wallpaper.default]
-    path = "/home/blank/.local/share/noctalia/wallpapers/wallhaven_v9w8r5.jpg"
+    path = "/home/blank/.local/share/noctalia/wallpapers/wallhaven_6kzekl.jpg"

    [wallpaper.last]
-    path = "/home/blank/.local/share/noctalia/wallpapers/wallhaven_v9w8r5.jpg"
+    path = "/home/blank/.local/share/noctalia/wallpapers/wallhaven_6kzekl.jpg"

    [wallpaper.monitors.DP-1]
-    path = "/home/blank/.local/share/noctalia/wallpapers/wallhaven_v9w8r5.jpg"
+    path = "/home/blank/.local/share/noctalia/wallpapers/wallhaven_6kzekl.jpg"

    [wallpaper.monitors.DP-2]
    path = "/home/blank/.local/share/noctalia/wallpapers/wallhaven_oxex69.jpg"
@@ -290,7 +290,7 @@ transition = [ "fade" ]
    path = "/home/blank/.local/share/noctalia/wallpapers/wallhaven_v9e2w3.jpg"

    [wallpaper.monitors.eDP-1]
-    path = "/home/blank/.local/share/noctalia/wallpapers/wallhaven_v9w8r5.jpg"
+    path = "/home/blank/.local/share/noctalia/wallpapers/wallhaven_6kzekl.jpg"

 [weather]
 unit = "imperial"
Author	SHA1	Message	Date
Frank	37ef4897ae	live: heartbeat sync 2026-10-20T13:10:41-07:00 (Refs #11 )	2026-10-20 13:10:41 -07:00
Frank	06e549cb27	live: heartbeat sync 2026-10-20T12:07:41-07:00 (Refs #11 )	2026-10-20 12:07:41 -07:00
Frank	c96741794a	live: heartbeat sync 2026-10-20T11:04:41-07:00 (Refs #11 )	2026-10-20 11:04:41 -07:00
Frank	e14d0906ea	live: heartbeat sync 2026-10-20T10:02:41-07:00 (Refs #11 )	2026-10-20 10:02:41 -07:00
Frank	d5be16127b	live: heartbeat sync 2026-10-20T08:59:41-07:00 (Refs #11 )	2026-10-20 08:59:41 -07:00
Frank	b7aef40266	live: heartbeat sync 2026-10-20T07:57:45-07:00 (Refs #11 )	2026-10-20 07:57:45 -07:00
Frank	fafdaa2617	live: heartbeat sync 2026-10-20T06:56:41-07:00 (Refs #11 )	2026-10-20 06:56:41 -07:00
Frank	7213068d91	live: heartbeat sync 2026-10-20T05:55:41-07:00 (Refs #11 )	2026-10-20 05:55:41 -07:00
Frank	05dbe8c5c1	live: heartbeat sync 2026-10-20T04:54:41-07:00 (Refs #11 )	2026-10-20 04:54:41 -07:00
Frank	806352f8f6	live: heartbeat sync 2026-10-20T03:51:41-07:00 (Refs #11 )	2026-10-20 03:51:41 -07:00
Frank	34a7af2847	live: heartbeat sync 2026-10-20T02:50:41-07:00 (Refs #11 )	2026-10-20 02:50:41 -07:00
Frank	635c64d773	live: heartbeat sync 2026-10-20T01:48:41-07:00 (Refs #11 )	2026-10-20 01:48:41 -07:00
Frank	64d9c54657	live: heartbeat sync 2026-10-20T00:45:41-07:00 (Refs #11 )	2026-10-20 00:45:41 -07:00
Frank	aec7f0f068	live: heartbeat sync 2026-10-19T23:44:41-07:00 (Refs #11 )	2026-10-19 23:44:41 -07:00
Frank	4023b21365	live: heartbeat sync 2026-10-19T22:41:41-07:00 (Refs #11 )	2026-10-19 22:41:41 -07:00
Frank	e14fc884a3	live: heartbeat sync 2026-10-19T21:40:41-07:00 (Refs #11 )	2026-10-19 21:40:41 -07:00
Frank	b3a84c5bb8	live: heartbeat sync 2026-10-19T20:37:41-07:00 (Refs #11 )	2026-10-19 20:37:41 -07:00
Frank	9e6254108a	live: heartbeat sync 2026-10-19T19:34:41-07:00 (Refs #11 )	2026-10-19 19:34:41 -07:00
Frank	ce87958b77	live: heartbeat sync 2026-10-19T18:31:41-07:00 (Refs #11 )	2026-10-19 18:31:41 -07:00
Frank	802014fea9	live: heartbeat sync 2026-10-19T17:29:41-07:00 (Refs #11 )	2026-10-19 17:29:41 -07:00
Frank	e22acf4913	live: heartbeat sync 2026-10-19T16:27:41-07:00 (Refs #11 )	2026-10-19 16:27:41 -07:00
Frank	c14c64d6c0	live: heartbeat sync 2026-10-19T15:24:41-07:00 (Refs #11 )	2026-10-19 15:24:41 -07:00
Frank	6e3e5594eb	live: heartbeat sync 2026-10-19T14:21:41-07:00 (Refs #11 )	2026-10-19 14:21:41 -07:00
dank	36ff3742b4	Merge pull request 'docs: auto-speak narrates every turn' (#38 ) from docs/dankvoice-narration-cadence into main	2026-10-19 13:33:42 -07:00