docs: auto-speak narrates every turn, not only the final answer (Refs #36 )

The Limits bullet still described the pre-fix behaviour ("thinking and the final message only"), which dank/dankvoice#3 just retired: narration rides `turn_end`, so the assistant's prose and thinking are spoken while the agent works. Records the two rules an operator needs when audio seems missing — arming is read at startup only, and a turn landing during playback is dropped rather than queued — plus where the design rationale lives. kb-lint 0 violations, index-coverage 0 issues.
Merge remote-tracking branch 'origin/main'
2026-10-19 13:31:01 -07:00 · 2026-10-19 13:29:52 -07:00 · 2026-10-19 13:29:52 -07:00 · 2026-10-19 13:29:28 -07:00 · 2026-10-19 13:28:24 -07:00 · 2026-10-19 13:20:41 -07:00
51 changed files with 1420 additions and 1905 deletions
@@ -0,0 +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."
 ---
 # Dankvoice bats: serialization and hang-proofing
 ## 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 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.
 ## 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).
 ## 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.
@@ -1,36 +1,35 @@
 ---
 name: docs-dedupe-verify-campaign
-description: "Run an exhaustive docs dedupe + fact-verification campaign in dank/command-center: scout cluster ledgers, evidence-overridden merges, live fleet probes, log compaction law, and landing via Gitea PR."
+description: "Run an exhaustive docs dedupe + fact-verification campaign in dank/command-center: scout cluster ledgers, override scouts with evidence, gate every commit, and sweep scaffolding before PR."
 ---
-Campaign procedure for deduping + fact-checking `omp-docs/` in dank/command-center (proven on Refs #29, 2026-10-19: 8 commits, -2,229 lines, 0 lint/coverage/bats failures).
+# Exhaustive docs dedupe + verification campaign (dank/command-center)
-## 1. Recon
+## Frame
- Fresh branch off `origin/main` in a new worktree (`git worktree add ~/.omp/wt/<name> -b docs/<issue>-<slug> origin/main`); the session worktree's `git checkout -b` is policy-blocked.
+- Read `omp-docs/references/okf-spec.md` + root `omp-docs/index.md` first; inventory with `find omp-docs -name '*.md' | wc -l`.
- Run `scripts/kb-lint.sh omp-docs` baseline; write a throwaway index-coverage checker (each dir's `index.md` must link every subdir/file) — mechanical, no scout needed.
+- Run `scripts/kb-lint.sh omp-docs` baseline; index-coverage gate is `scripts/kb-coverage.py omp-docs` (each dir's `index.md` must link every sibling file/subdir).
- Open the Gitea issue first (multi-moving-parts law).
+- Branch off fresh `origin/main` in a NEW worktree (`git -C ~/.omp worktree add ~/.omp/wt/<name> -b docs/<issue>-slug origin/main`) — workspace policy blocks `git checkout -b` in session worktrees.
 - Open the Gitea issue first (multi-moving-parts law); branch name `docs/<issue#>-<slug>`.
-## 2. Scout fan-out (overlap detection)
+## Scout fleet (overlap detection)
- One `task` batch, `agent: scout`, one task per doc cluster + one cross-cutting sweep (cap 2 concurrent; rest queue).
+- One `task` call, `tasks[]` batch, agent `scout`, read-only; one cluster per task (skills trees, llama trees, pi vs packages, niri, sleep/power, core, gitea, gitea+cross-cutting sweep). Cap 2 concurrent; queue rest.
- Each scout writes a ledger to `local://dedupe/<cluster>.md`: inventory table (file, lines, purpose, verdict KEEP/MERGE/DELETE/UPDATE), overlaps, facts-to-keep ledger, inbound links, staleness, claims-needing-verification.
+- Ledger format per cluster → `local://dedupe/<cluster>.md`: inventory table (file | lines | verdict KEEP|MERGE|DELETE|VENDOR|UPDATE), overlaps, facts-to-keep, inbound links, staleness.
- Scouts are LEADS, not truth. Observed failures: fabricated ledger entries (claims about text that does not exist in any file), a DELETE verdict on a generated artifact that is under test (`tools/niri/keybindings.md` is generated by `scripts/gen-keybinds.sh` and tested by `tests/gen-keybinds.bats` — keep), and a KEEP based on misreading a changelog leftover. Re-derive every consequential verdict from the files/repo yourself.
+- **Scouts lie.** Verified misses in the 2026-10-19 campaign: fabricated ledger entries ("peer-reviewed BrowseComp" claim that exists in no file), a DELETE verdict for a generated artifact that is checked in by design AND under test (`tools/niri/keybindings.md`, see `scripts/gen-keybinds.sh` + `tests/gen-keybinds.bats`), and a KEEP for a leftover the scout misread its own changelog about. NEVER apply a scout verdict without re-checking the file, the tests, and the changelog yourself.
-## 3. Verify fleet facts live (never trust doc dates)
+## Fact verification
- Read-only BatchMode probes: `ssh -o BatchMode=yes dankclaw '...'` (podman ps/inspect, systemctl status, curl localhost, os-release, cpuinfo). `sudo -n` only has systemctl verbs — use `podman exec <ctr> grep/cat` for in-container files.
+- Fleet facts: read-only probes over `ssh -o BatchMode=yes dankclaw|dankserver` (podman ps/inspect/top, stat, /etc/os-release, curl localhost APIs, `podman exec <c> <tool> --version`). Live state beats docs even when docs claim recent verification — the 2026-10-18 "audit" still drifted (zealot 27B→9B, build 10754→10777, container census 14→32).
- Update docs with dated drift banners ("probed 2026-10-19") for policy divergence; NEVER silently re-apply a policy — flag as operator decision (e.g. SearXNG engine policy).
+- External claims: web_search/web read yourself (no subagents per Frank's rule). Kill fabrications outright (invented distro `FreeToken`, nonexistent `ornith-llama-cpp-setup` tree, unattributable "44.5% peer-reviewed CUA") — delete/drop with an explicit note, never keep "plausible" numbers.
 - Policy drift (live ≠ tuned docs): flag in the doc + PR body as an operator decision; NEVER silently re-apply policy.
-## 4. Verify external claims via direct web research (no subagents)
+## Log compaction (log.md)
- Version/protocol/benchmark claims: primary source only (upstream README, raw.githubusercontent, /api/v1/version, arxiv). If a number cannot be re-attributed to a published benchmark, drop it with an explicit note in the doc.
+- Entry law: dated entry = what changed + durable lesson + concept-page pointer; narratives recoverable via `git log --follow`. Record the law at the top of the log. Tag historical-era entries.
 - Fabrication hunt: invented distros/projects/model names (found: "FreeToken" distro, ornith-llama-cpp-setup tree, Intel CPU on an AMD box) — delete the artifact, not just the line.
-## 5. Log compaction law
+## Gates + landing
- Changelog entry = date + what changed + durable lesson + concept-page pointer, few lines. Full narratives live in git (`git log --follow`). Record the law at the top of `log.md`. Never re-expand an entry in place. Keep pi-era entries tagged "(pi era)".
+- Gate every commit: `bash scripts/kb-lint.sh omp-docs && python3 scripts/kb-coverage.py omp-docs && bats tests/`. Pre-commit hook prints `error: command not found: caddy` on Caddyfile-touching commits — warning only, commit still lands.
 - Before opening the PR: `git diff --stat origin/main..HEAD | grep -i 'tmp\|scratch\|\.bak'` — scaffolding merged under a `.tmp-` name in the 2026-10-19 campaign and needed a follow-up PR to promote.
 - PR via API (skill `gitea-api-pr-operations` for token-extraction + merge payload); `xdg-open` the PR the moment it opens; comment the campaign ledger on the issue.
 - After Frank's merge OK: propagate deployment `git -C ~/.omp fetch && git merge --ff-only origin/main`; reap campaign worktree (`git worktree remove --force`) + delete branch local/remote; close issue with landing comment.
-## 6. Gates + landing
+## Line-edit op syntax trap (bit three times)
- Gate every commit: `bash scripts/kb-lint.sh omp-docs` + index-coverage + `bats tests/` (67 tests). Pre-commit hook prints `error: command not found: caddy` on Caddyfile-touching commits — warning only, commit still lands.
+- Valid ops: `PUT N.=M:` (body `+text` lines), `CUT N.=M` / `CUT N.=M @reg`, `PUT <N @reg`, `PUT >N:` / `PUT <N:`. There is NO `PUT N+=:` form — it lands in the file as a literal garbage line and shifts the insert to the wrong position. For gap-insert use a lone `PUT >N:` or `PUT <N:` per call; pre-compute line numbers against the file map (ops reference original lines within one call, but a failed op poisons positions).
- Gitea API auth: `~/.config/secrets/gitea` is **URL-form** (`http://dank:<token>@host`), not a raw token. Extract: `T=$(sed -n 's|.*://[^:]*:\([^@]*\)@.*|\1|p' ~/.config/secrets/gitea | head -1)`; raw `cat` as bearer token → 401.
+- Recovery recipe when a literal op line lands: read exact bounds, `CUT N.=N` (junk), `CUT A.=B @block` (misplaced section), then `PUT <M @block` at the true anchor, re-read tail, add spacing blank if a `---` now abuts a list line.
 - PR body ends with `---` + `cwd: <wd> · session: <id>` footer; then `xdg-open <PR-URL>` immediately; comment the campaign ledger summary on the issue. NEVER merge without Frank's explicit OK.
 ## Edit-tool field notes (recurring traps)
 - `PUT N+=:` is invalid syntax — it inserts the literal text. One insert-op per edit call; recompute line numbers per call.
 - File hash tag changes after every edit — re-`read` before each subsequent edit call to the same file; reusing a stale tag is rejected.
@@ -0,0 +1,70 @@
 ---
 name: docs-point-of-use-destruction
 description: "Documentation exists for point of use, not archival. Use before any dedupe/compact/verify-docs job, and whenever a census or \"only copy\" argument is being used to KEEP documentation: apply the purpose test and destroy obsolete measurements. Supersedes the preservation conclusions of vault-one-fact-one-owner-dedupe §3/§12."
 ---
 # Documentation exists for point of use
 **Supersedes** `vault-one-fact-one-owner-dedupe` §3 ("port before cut") and §12
 ("expect docs flat") wherever those conclude a page must be *kept*. Sole custody of a
 useless fact is still useless.
 ## The test, before you write and again before you keep
 - Would the reader, doing a real task tomorrow, **act differently** because of this
  line? No → delete it.
 - Is it a measured rate (t/s, tok/s, ms, MiB-of-pool, acceptance %, a bench ladder) for
  a model / runtime / layout that is **not running now and not being compared now**?
  Destroy it. Not "file it in an Eras row", not "preserve it for history". AI moves
  faster than the vault: the number is wrong before anyone reads it, and a wrong number
  in a runbook gets believed.
 - Keep the **law** the measurement taught; drop the measurement. Qualitative causal
  stories survive; numbers do not.
 - What survives: live config and its exact numbers, procedures, failure signatures,
  security posture, interface contracts, rollback pointers.
 - **Losing information is an acceptable, usually correct outcome.** Frank said so
  explicitly on 2026-10-19 after rejecting a PR that had preserved 53 ledgers.
 ## Traps that lead agents to preserve junk
 - **A census cannot decide what to keep.** `port-census.py`-style tools answer "where
  does this fact live", never "does anyone need it". "14–63 sole-record lines per page"
  was read as *irreplaceable* when the fact was *obsolete*. Ask usefulness, not custody.
 - **A census that includes the file under test proves the page is held by itself.**
  Exclude it, print the corpus size, assert absence; treat `0 unheld` on a long page as
  a tool bug until proven otherwise.
 - **"One fact, one owner" is a placement rule, not a preservation rule.** It says where
  a surviving fact lives; it never says the fact must survive.
 - **A change diary (`log.md`) is the largest archive in most vaults** (this one: 2,380
  lines, ~8 % of the vault). Git holds the chronology; a causal law belongs on the page
  that owns the thing it governs. Retire the diary.
 ## Execution that worked (2026-10-19, −13.7k lines)
 1. Write the kill list as a reviewed artifact, one path per line, grouped by *why it is
   dead* — that list becomes the PR's argument and the trash manifest.
 2. Destroy whole pages first (`scripts/destroy-vault.py <list>`): move to
   `.AGENTTRASH/<date>-destruction/`, then delete every reference from survivors, whole
   line included when the dead link was its only content. Do not compare link targets
   with `pathlib.Path.stem` — it strips real suffixes (`sd.cpp`).
 3. Then strip numbers from what remains (`scripts/axe-measurements.py`): delete ledger
   sections (noun-LEDS the heading, nothing instructional after it), blank any table cell
   reporting a rate, fold Eras older than the current one into a single row pointing at
   git. Never touch a shape number or a Laws/Wire/Rollback section.
 4. Sweep indices (generator must exclude the trash dir, drop rows whose page cell became
   empty), re-lint, re-check links.
 5. Rewrite the governing policy in the same PR, or the next agent re-grows the vault:
   project `AGENTS.md` *Documentation Policy* + the global agent settings.
 ## Report honestly, per area
 docs / scripts / operator-doc separately, measured against the merge-base. The tools are
 a cost that must be named, not hidden inside a headline "net" number — that is what got
 the previous pass rejected.
 ## Verify the repair tools themselves
 One repair pass matched "line ends with a comma" and deleted the trailing comma from 660
 wrapped prose lines. Restore by matching lines that are byte-identical to `HEAD` except
 for trailing punctuation (`restore-punctuation.py`), keep the destructive rule out of the
 tool, and record the incident in its docstring.
@@ -0,0 +1,27 @@
 ---
 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."
 ---
 Gitea on Dankclaw (192.168.0.143:3000, `dank/serverAppConfigs`) — merge quirk, measured 2026-10-19.
 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.
 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") \
  --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
 # 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.
@@ -0,0 +1,29 @@
 ---
 name: omp-extension-stale-module-audit
 description: "Diagnose recurring omp extension handler timeouts/silence when the on-disk fix is already deployed: harness has no extension hot-reload, so running sessions freeze the module at session start (zombie modules)."
 ---
 Use when a fix for an omp extension is merged/deployed yet the SAME errors persist ("handler timed out after 30000ms", silence, wrong behavior) in running sessions.
 **Core fact:** the harness loads extension `.ts` modules at session start and never reloads them (no `/reload` for extensions; bundle `reload` hits are LSP/MCP/browser only). A session older than the fix keeps executing stale code regardless of the file on disk.
 **Procedure:**
 1. Census the errors from logs, not guesses — timeout lines carry the culprit pids:
   `grep -h "handler timed out" ~/.omp/logs/omp.<today>*.log | python3 -c 'import sys,json; rows=[json.loads(l) for l in sys.stdin]; rows.sort(key=lambda r:r["timestamp"]); [print(r["timestamp"], r["event"], r["pid"]) for r in rows]'`
   (`~/.omp/logs/omp.<date>.<pid>.log` — the pid in the filename is the session.)
 2. Session start times vs deployed file versions:
   `ps -eo pid,lstart,args | grep '[o]mp'`
   `git log --format='%h %ad %s' --date=format:'%m-%d %H:%M' -- <extension path>`
   `git reflog --format='%gd %ad %gs' --date=format:'%m-%d %H:%M' | grep merge` (live-sync pull times = when the file content changed).
   Any session whose start time precedes the fix's arrival has the stale module.
 3. Confirm the stale revision actually contains the bad pattern — read what that session loaded, not HEAD:
   `git show <old-rev>:<path> | grep -n 'await speak\|async (event'`
   (e.g. an `async agent_end` awaiting a >30 s chain is exactly what the harness's per-handler `Kzc` 30 s race logs; fire-and-forget `void` is fine — detached promises are NOT tracked by the dispatch window.)
 4. Optional empirical proof when static analysis says "impossible": probe extensions through the real harness:
   `omp -p --no-extensions -e /tmp/probe.ts "Reply OK"` with a probe that logs handler start/return and `void`s a 40 s detached promise + spawns a long child. Fast exit + no timeout log ⇒ detachment is untracked ⇒ blame stale modules, not the harness.
 5. Remediation: restart the affected sessions (kill the listed pids or their terminals — the operator session itself may be one of the zombies; say so explicitly). There is no other fix.
 **Gotchas:**
 - Per-handler attribution in the log is accurate per dispatch; don't blame other extensions before checking the pid's start time.
 - Endpoints healthy + silence persisting usually means TWO stacked bugs (e.g. stale awaiting module in old sessions AND a mute bug in current code) — diagnose each pid cohort separately.
 - Extension chain code must use self-owned `AbortSignal.timeout(...)`, never a ctx-scoped signal: harness dispatch signals die when the dispatch window closes.
@@ -0,0 +1,47 @@
 ---
 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."
 ---
 # Plugin install from git: committed artifact + fresh mirror
 `omp plugin install git:<url>` (and `pi install git:`) **clone the repo and validate the manifest's declared extension entry WITHOUT running a build step**. Two failure classes seen live (dank/dankvoice, 2026-10-19):
 ## 1. Declared entry missing from the clone
 Symptom: `Plugin <name> extension validation failed: ./dist/index.js: declared extension entry not found on disk`.
 Cause: build output (`dist/`) is gitignored; the manifest points at it; the clone has only `src/`.
 Fix — ship the artifact:
 - Remove `dist/` from `.gitignore`, `bun run build`, commit `dist/`.
 - Prove build determinism first: build twice, `cmp` the outputs (bun esm builds are byte-reproducible without sourcemaps).
 - Pin the contract in a small bats suite so it can't rot:
  1. the manifest's declared entry is tracked in git (`git ls-files -- "${entry#./}"` non-empty — this is the installer's exact contract, not a config assertion);
  2. committed bytes equal a fresh build (`bun run build` then `git diff --name-only -- dist` is empty → red on drift).
 ## 2. Stale bun git-mirror cache
 Symptom: fix pushed, retry **still** fails identically, and the retry is suspiciously fast (seconds).
 Cause: bun keeps bare mirrors in `~/.bun/install/cache/<hash>.git` and may reuse them at an old commit — even after the fix is pushed and the default branch is correct.
 Diagnose + fix:
 ```bash
 find ~/.bun/install/cache -maxdepth 2 -iname "*<repo>*"
 git --git-dir ~/.bun/install/cache/<hash>.git log --oneline -3 --all   # stale HEAD?
 rm -rf ~/.bun/install/cache/<hash>.git                                  # it is a cache; safe
 ```
 Prove the fetch path independently first (also validates credentials for private Gitea repos):
 ```bash
 GIT_TERMINAL_PROMPT=0 git clone -q <url> /tmp/x && git -C /tmp/x log --oneline -1 && ls /tmp/x/dist
 ```
 ## Order of investigation (don't skip)
 1. Gitea default branch correct? (`GET /api/v1/repos/<o>/<r>` with token — private repos 404/None unauthenticated.)
 2. Plain unattended clone contains the entry? If yes, the installer's view is cached → purge mirror.
 3. Only then suspect the installer itself (validation code lives in the minified bundle; `grep -oE '.{600}<error string>' "$bunfile"` on `readlink -f $(which omp)` shows the exact check).
 ## 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.
@@ -0,0 +1,29 @@
 ---
 name: red-verify-without-stash
 description: "Prove a regression test is red-capable against pre-fix code in a shared worktree where git stash/checkout are policy-blocked, via git-show blob swap with md5-verified restore."
 ---
 # Red-verifying tests without `git stash`
 ## When
 You fixed a file and added tests that should have failed before the fix, but workspace policy blocks `git stash` (and `git checkout -- file`) in shared worktrees (e.g. `~/.omp` shared-workspace policy). Needed to prove red-capture instead of asserting it.
 ## Recipe
 One `bash` call — swap the fixed file for the HEAD (pre-fix) blob, run only the fix-relevant tests, restore, verify byte-identity:
 ```bash
 cd "$WT"
 md5sum path/to/fixed.file > /tmp/file-hash
 cp path/to/fixed.file /tmp/fixed.file.bak
 git show HEAD:path/to/fixed.file > path/to/fixed.file   # pre-fix content; new tests now exercise old code
 bats -f "test name A|test name B" tests/suite.bats       # expect: not ok for every fix-relevant test
 cp /tmp/fixed.file.bak path/to/fixed.file
 md5sum -c /tmp/file-hash && echo RESTORED
 ```
 ## Notes
 - `git show HEAD:path > path` truncates-and-refills the file in place; safe because you hold the md5 and a backup copy, and the restore check proves the fixed bytes are back.
 - Run only the fix-relevant tests via the runner's name filter (`bats -f` regex); a full suite wastes time and old tests pass on both versions.
 - Expect exactly the tests that pin the fix's behavior to fail pre-fix; tests unrelated to the change (pure coverage of old behavior) pass on both versions — don't count them as red evidence.
 - `bats` pipelines mask exit codes without `pipefail`; judge by the `ok`/`not ok` lines, not the shell status.
 - For non-test proof of endpoint behavior (live A/B of an HTTP request body), replay the exact body with `curl` against the live endpoint instead of speculating; keep both timings.
@@ -0,0 +1,41 @@
 ---
 name: ryzenai-generic-failure-loader-order
 description: "Debug AMD Ryzen AI OGA \"Exception during initialization: Generic Failure\" on Linux XDNA2 — the LD_LIBRARY_PATH-vs-activate ordering trap, its proof instruments, and the OGA 0.14 run contract."
 ---
 Symptom (any `onnxruntime_genai` run on a Ryzen AI NPU, container or bare):
 ```
 [E:onnxruntime:, inference_session.cc:2811 operator()] Exception during initialization: Generic Failure
 ```
 Fails ~2 ms after `og.Model()`. No `openat` of `/dev/accel/accel0`, **nothing in the kernel log**, no XRT log (the INI logger is not built into AMD's shipped XRT), no core dump. It is NOT a platform, model-export, or driver-ABI failure.
 ## Root cause
 `source <venv>/bin/activate` from `install_ryzen_ai.sh` **prepends** to `LD_LIBRARY_PATH`:
 ```
 site-packages/flexml/flexml_extras/lib : site-packages/onnxruntime/capi : site-packages/voe/lib
 ```
 `voe/lib` is the **compiler-side** bundle: it ships its own `libxrt_coreutil.so.2` and `libryzen_mm.so.1`. Set the path *before* activating and those copies win, XRT's XDNA shim binds against the wrong coreutil, `xrt_core::shim_loader::shim_loader()` → `get_userpf_device()` → `xrt::device(0)` throws, `ryzenai::Allocator::Alloc` throws next, and ORT flattens both into the bare string above.
 **Rule: activate first, THEN set `LD_LIBRARY_PATH`, with `/opt/xilinx/xrt/lib` first.** Passing the var via `podman -e` and sourcing activate afterwards in the same `bash -lc` is the broken shape — that is exactly how a runner script differs from a hand-typed probe, and it is why diagnostics pass while the runner fails. Mounting XRT is not enough either: the tree must be **on** the path.
 ## Proof instruments, cheapest first
 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`.
 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).
 ## 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`.
 - 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 (`
@@ -0,0 +1,49 @@
 ---
 name: ryzenai-npu-oga-linux-run
 description: "Run an AMD vendor-compiled Ryzen AI (XDNA2) model — OGA/onnxruntime-genai — on a Linux Ryzen AI host with the in-tree amdxdna driver, without installing the vendor driver or touching the host driver; includes the triage for ORT \"Exception during initialization: Generic Failure\"."
 ---
 Run a vendor-compiled Ryzen AI (XDNA2) model on Linux with the **in-tree** amdxdna driver: no vendor kernel module, no `dpkg -i`, host driver untouched.
 ## Preconditions
 - Host: Strix Point / Strix Halo / Krackan (PCI `1022:17f0`), in-tree `amdxdna` bound to the NPU function (`readlink /sys/bus/pci/devices/<bdf>/driver` → `amdxdna`), `/dev/accel/accel0` present.
 - `ryzen_ai-<ver>.tgz` installed into a venv (`install_ryzen_ai.sh -a yes -p <venv>`; it hard-codes `python3.12` — put a uv-managed 3.12 **bin dir** on PATH, never a symlink: a symlinked shim breaks venv creation with `No module named 'encodings'`).
 - Model artifact MUST match the RAI version: `<name>_rai_<ver>_npu_<ctx>`. Other versions load and emit garbage.
 - Vendor XRT userspace: `dpkg-deb -x` the debs from `RAI_<ver>_Linux_NPU_XRT.zip` (base + npu + `xrt_plugin…amdxdna.deb` — the plugin is what ships `libxrt_driver_xdna.so.*`) into a host dir, bind-mount it at `/opt/xilinx/xrt`.
 ## Container run line (the part that is easy to get wrong)
 ```
 --device /dev/accel/accel0                      # root:render 0660 → rootful, or a world-writable udev rule
 -v <xrt-root>/opt/xilinx/xrt:/opt/xilinx/xrt:ro
 -e RYZEN_AI_INSTALLATION_PATH=<venv> -e XILINX_XRT=/opt/xilinx/xrt
 -e LD_LIBRARY_PATH=/opt/xilinx/xrt/lib:<venv>/onnxruntime/lib:<venv>/deployment/lib
 # cwd MUST be <venv>/deployment/lib — the RyzenAI EP is dlopen'd by bare name and the
 #   only place ORT looks is the working directory.
 # Activate the venv explicitly; a login shell (`bash -lc`) re-sources the profile and
 #   can put a numpy-less base python first on PATH.
 ```
 ## LAW: mounting XRT is not enough — `/opt/xilinx/xrt/lib` must be ON `LD_LIBRARY_PATH`
 The RyzenAI EP reaches the XDNA shim through XRT's own loader. With the tree bind-mounted
 but off the loader path, `xrt::device(0)` throws in `xrt_core::shim_loader`, the RMM
 allocator fails next, and ORT flattens all of it into
 ```
 [E:onnxruntime:, inference_session.cc:2811] Exception during initialization: Generic Failure
 ```
 Signature that distinguishes this from a real device/driver fault: fails in ~2 ms, **never
 opens `/dev/accel/accel0`**, nothing in `dmesg`/`journalctl -k`, no XRT log (the INI logger
 is not built into the vendor build — `XRT_INI_PATH` + `[Common] verbosity` writes nothing).
 ## Triage recipe for "Generic Failure" (in this order — each step is one call)
 1. `strace -f -e trace=openat` → does it open `/dev/accel/accel0`? If **no**, the failure is pre-device: loader/shim, not the driver. Also note the last file it opens (`genai_config.json` = config parsed, then provider setup fails).
 2. `gdb -q -batch -x cmds --args python driver.py` with `catch throw` + `bt 10` + `continue`. Frames `xrt_core::shim_loader::shim_loader` / `get_userpf_device` / `xrt::device::device` then `ryzenai::Allocator::Alloc` ⇒ the shim never loaded ⇒ fix `LD_LIBRARY_PATH`.
 3. Prove it with a two-arm run in ONE container (toggle only the suspect) before writing the law down. Both arms passing ⇒ that variable was never the cause.
 4. Ground truth on device visibility: `xrt-smi examine` → `RyzenAI-npu5 | aie2p | 6x8` + `NPU Firmware Version`. If xrt-smi dies on `libboost_filesystem.so.1.83.0`, install `libboost_filesystem1.83.0`+`libboost_program_options1.83.0` — **boost is only needed by xrt-smi, not by the OGA/EP path** (verified by purging it and still loading the model).
 5. `voe` in site-packages is a *compiler* toolkit (passes/patterns), not a runtime — swapping `LD_LIBRARY_PATH` to `voe/lib` fixes nothing.
 6. Byte-scanning XRT `.so` files for supported PCI IDs is inconclusive (2-byte ID patterns collide constantly) — don't bother.
 ## Distrust "it ran" on this stack
 - Vendor `quicktest` can print success while computing on CPU (missing peano lib ⇒ silent CPU fallback). Prove NPU residency per run: sample `/sys/class/accel/accel0/device/mem_usage` (needs root) during generation, or read the EP's `Actually running on NPU` line.
 - Never report request #1 after a boot as a rate — first pass includes graph/init cost.
@@ -0,0 +1,43 @@
 ---
 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."
 ---
 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.
 ## Where the bits actually live (both public, no AMD account)
 - Runtime tarball: `https://download.amd.com/opendownload/RyzenAI/1.8.0/ryzen_ai-1.8.0.tgz` (~7.28 GiB). Verify with a ranged GET — first bytes `1f 8b 08`.
 - NPU driver/XRT zip: `https://download.amd.com/opendownload/RyzenAI/Driver/RAI_1.8_Linux_NPU_XRT.zip` (90 MB).
 - Dead ends (404, do not re-probe): `download.amd.com/driver/linux/RAI_1.8_Linux_NPU_XRT.zip`, `.../opendownload/RyzenAI/ryzen_ai-1.8.0.tgz`, `www.xilinx.com/bin/public/openDownload?filename=...` (301 → 404). The login-walled EULA *form* is not the gate; the `opendownload` tree is the real file host.
 Tarball has 30 top-level entries: cp312/linux_x86_64 wheels (`onnxruntime_genai_ryzenai-0.14.0`, `onnxruntime_vitisai-1.27.0`, `vitis_mllib`, `flexml*`, `device_essentials_strx`, `model_generate`, `voe-1.8.0`), plus `deployment.tar.gz` (contains `lib/libonnxruntime-genai.so`, `lib/libonnxruntime_providers_ryzenai.so`, AIE compiler libs), `onnxruntime.tar.gz`, `quicktest.tar.gz` (VitisAI-EP install validator), `LLM.tar.gz` (text-only OGA examples: `run_model.py`, `tokenizer_factory.py`), `install_ryzen_ai.sh`. `voe-4.0-linux_x86_64.tar.gz` is only `vaip_config.json` — no TTS xclbins. **AMD ships no TTS runner and no TTS example.**
 ## Host rules
 - **Never `dpkg -i` the vendor XRT.** `dpkg-deb -x <deb> <dir>` and bind-mount `<dir>/opt/xilinx/xrt` at the same path in the container. The plugin deb would install a DKMS `amdxdna` that replaces the distro in-tree driver; the in-tree driver on Ubuntu 26.04 is `amdxdna 0.7.0` and already loads `amdnpu/17f0_11/npu_7.sbin` at boot (`dmesg | grep amdxdna`).
 - **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.
 ## 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.
 - `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`
  then `git -c credential.helper="store --file ~/.git-credentials-hf" clone ...`. Never `git clone https://oauth2:$TOKEN@...`.
 ## 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.
 - 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.
 ## Status caveat
 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.
@@ -0,0 +1,77 @@
 ---
 name: ryzenai-venv-dependency-triangle
 description: "Debug the torchao/torchtune/transformers import triangle inside an AMD Ryzen AI (ryzen_ai-*.tgz) venv under torch 2.6, including the masked \"cannot import name\" failures and the port-the-one-symbol escape."
 ---
 # Ryzen AI venv dependency triangle (torch 2.6 era)
 Symptom that starts it all — and it never names the culprit:
 ```
 ImportError: cannot import name 'HubertModel' from 'transformers'
 ```
 The named symbol is healthy. `import torchao` alone reproduces the failure; `import transformers` alone does not. transformers imports its **torchao integration** whenever the real modelling path loads, and the failure is re-raised two frames deep by the lazy loader as a missing name.
 ## Instruments
 Never conclude from `grep -c Symbol transformers/__init__.py` — 4.5x generates its lazy `__init__`, so an absent literal proves nothing. Get the real exception:
 ```python
 import traceback, torch, transformers
 try:
    __import__("transformers.models.hubert.modeling_hubert")
 except Exception:
    traceback.print_exc()
 ```
 That prints the truth, e.g. `AttributeError: module 'torchao.quantization' has no attribute 'Float8WeightOnlyConfig'` from `transformers/modeling_layers.py`.
 Also probe the order matrix (`import X; from transformers import Y` for each suspect): only the poisoned order fails, which isolates the culprit without reading vendor code.
 ## The triangle (measured 2026-10-19, ryzen_ai 1.8.0, torch 2.6.0+cpu, transformers 4.57.6)
 | Option | Result |
 |---|---|
 | torchao absent | `from transformers import HubertModel` -> OK |
 | torchao 0.7.0+cpu | `ImportError: Float8WeightOnlyConfig` (masked as missing symbol) |
 | torchao 0.8.0+cpu | imports (warns `No module named 'triton'`), still lacks `Float8WeightOnlyConfig` |
 | torchao >= 0.9 | has the symbol, requires torch >= 2.7 -> impossible in this venv |
 | torchtune, ANY version (0.6.1 … 0.1.1) | guard `torchao not installed`, or `pyarrow requires NumPy 2.0 or newer, found 1.26.4` |
 Two independent dead ends: torchtune's package init pulls `datasets` -> **the pyarrow AMD ships in its own venv refuses that venv's own numpy 1.26.4**. So `import torchtune` is structurally dead, and torchao (the only thing that satisfies its guard) breaks transformers. **Never "just upgrade" torch/numpy: the vendor's ONNX runtime and torch build are what the NPU EP is loaded against.**
 ## Escape: port the one symbol, pin both absent
 Ask what the third-party package is actually used for before fighting the resolver. In `neucodec` it was one symbol (`RotaryPositionalEmbeddings`, ~40 lines, copied verbatim from `torchtune/modules/position_embeddings.py`, BSD-3) used by two files. Apply it in the image with a transform that **asserts** each import line exists, so a vendor update fails the build instead of shipping a half-patched package:
 ```dockerfile
 COPY patches/rope_local.py /opt/patch/rope_local.py
 RUN python - <<'PY'
 import pathlib
 from importlib.util import find_spec
 pkg = pathlib.Path(find_spec("neucodec").origin).parent   # find_spec: importing it is what is impossible yet
 (pkg / "rope_local.py").write_text(pathlib.Path("/opt/patch/rope_local.py").read_text())
 old, new = "from torchtune.modules import RotaryPositionalEmbeddings", "from .rope_local import RotaryPositionalEmbeddings"
 for name in ("bs_roformer5.py", "codec_decoder_vocos.py"):
    p = pkg / name; s = p.read_text()
    assert old in s, name + ": import line moved - re-read the vendor source"
    p.write_text(s.replace(old, new))
 PY
 ```
 Gate both absences at build time so nobody re-adds them and inherits a three-week-later mystery:
 ```dockerfile
 RUN ... import-check \
    && python -c "import importlib.util as u; assert u.find_spec('torchao') is None; assert u.find_spec('torchtune') is None"
 ```
 Prove a ported numeric kernel with the vendor's own fixtures, not with faith: `neucodec` ships `samples/jo.wav` *and* its own encoding `samples/jo.pt`, so re-encoding the WAV and comparing integer codes is a pass/fail correctness test of the RoPE port.
 ## Rules of thumb
 - `--no-deps` for anything adjacent to torch/onnxruntime/numpy; check the vendor pins by reading them out of the venv (`python -c "import torch; print(torch.__version__)"`), never from docs.
 - A `--dry-run` install that resolves without touching torch/numpy/onnxruntime is the licence to install *with* deps.
 - `uv pip install --target DIR` / a nested venv does **not** layer over a parent venv: a venv created from `/opt/rai/bin/python` resolves "system site-packages" to the base interpreter, and uv's resolver ignores `.pth` paths and will pull a second numpy that breaks the vendor C extensions.
 - Ephemeral `podman run --rm` probes discard everything you installed in them — build a throwaway tag (truncate the Containerfile before the failing step) instead of re-hypothesising.
@@ -0,0 +1,44 @@
 ---
 name: sigterm-kill-test-stub
 description: "Pin \"code kills its child process\" behavior with a bash stub player: make the stub SIGTERM-reactive via sleep&wait, log KILLED via trap; diagnose deferred-trap failures."
 ---
 Use when a test must prove production code sends SIGTERM to a spawned child (player, worker, server stub) and the test asserts the kill happened — or when such a test mysteriously fails with `KILLED` missing and wall time equal to the stub's sleep duration.
 ## The trap-during-sleep gotcha
 A bash stub that sleeps in the **foreground** does NOT run its TERM trap when signalled: bash defers traps until the current foreground command completes. The stub dies (or logs) only after the sleep finishes — long after the test read the evidence file.
 Symptoms:
 - Assertion on a `KILLED` marker line fails although production code demonstrably calls `child.kill("SIGTERM")`.
 - Test wall time equals the stub's full sleep (the kill "had no effect").
 ## Fix: reactive stub skeleton
 ```bash
 #!/usr/bin/env bash
 printf '%s\n' "$*" >> "$STUB_LOG"                       # call record
 trap 'printf "KILLED\n" >> "$STUB_LOG"; exit 143' TERM  # BEFORE the sleep
 for arg in "$@"; do case "$arg" in *.wav) cp "$arg" "$COPY" ;; esac; done
 sleep "${STUB_HOLD:-0.1}" &                             # background sleep…
 wait $!                                                  # …wait is interruptible
 printf 'DONE\n' >> "$STUB_LOG"
 ```
 - `sleep N & wait $!` is the idiom: a signal makes builtin `wait` return immediately, the trap runs at once, `exit` inside the trap prevents fallthrough to `DONE`.
 - Tune duration per test via the env knob (`STUB_HOLD=5`) so the child is provably still alive when the kill is triggered.
 - Put the trap BEFORE any long command; a trap registered after the sleep never guards it.
 ## Harness wiring (black-box driver pattern)
 - Scenario: start the long work → settle (>spawn latency, <hold) → trigger the killer (shutdown event, second invocation, `/stop`) → settle → read log.
 - Expose the stub log lines on the driver's stdout (`LOG <line>` per line) so tests grep output, not files: black-box seam stays output-only.
 - Assert `KILLED` present; for interrupt-semantics also count (`kills -eq 1`) and total call lines (`PLAYS 3` = call, KILLED, call).
 ## Orphan hygiene
 Second child still sleeping when the driver exits: spawn with `stdio: "ignore"` so the orphan holds no capture pipe — it SIGPIPEs/quiets at teardown; do not lengthen tests waiting for it.
 ## Verify before trusting
 Run the pair separately: kill-tests green while a byte-equality test (`cp` of the payload before sleep) stays green — the reactive rewrite must not drop the copy step (it sits between trap and sleep).
@@ -1,6 +1,6 @@
 ---
 name: vault-one-fact-one-owner-dedupe
-description: "\"Collapse per-payload/per-attempt vault pages into one owner page per endpoint without losing a fact: port-before-cut orphan census, doubled-page repair, trash-aware tools, delegated-write verification, index regeneration, and the merge-resolution order.\""
+description: "\"Collapse per-payload/per-attempt vault pages into one owner page per endpoint without losing a fact: port-before-cut orphan census (corpus must exclude the file under test), doubled-page repair, trash-aware tools, delegated-write verification, honest per-area line accounting, index regeneration, and the merge-resolution order.\""
 ---
 # One fact, one owner: dedupe the vault without losing a fact
@@ -37,12 +37,19 @@ file being rewritten. Any line with **no** surviving key is an orphan → port,
 deliberately and say so. Use `scripts/port-census.py <new-dir> <git-HEAD:path|file>` (numbers
 with ≥ 4 int digits, decimals, flags, paths, backticked spans, `--`, ALL-CAPS, or ≥ 2 hyphens).
-Two calibration traps:
+Three calibration traps:
 - **Prose words are not facts.** A hyphen or trailing period inside a word (`long-standing`,
  `deployed:`) was counted as a tracked token while real identifiers hid behind it; that noise
  buried 300 real lines under 979 fake ones. Strip punctuation, require fact shape.
 - **The corpus decides the question.** Corpus = the new file only → "what did this rewrite
  drop?" Corpus = whole vault → "is the dropped fact orphaned repo-wide?" Ask one at a time.
 - **The corpus MUST exclude the file under test, and you must assert it.** A census pointed at
  the directory that *contains* the page proves the page is held by itself: ten era pages
  reported `0 sole-record lines`, which reads as "pure duplication, trash it". With the file
  excluded, the same pages held **14–63 sole-record lines each** — campaign ledgers that exist
  nowhere else. A tool's own docstring promise ("excluding it") is not a check: print the
  corpus size, assert the target is absent, and treat `0 unheld` on a long page as a tool bug
  until proven otherwise. A mechanical census is a scout: its verdict is a lead, not a finding.
 Also grep `AGENTS.md` separately — a fact it carries is not an orphan.
@@ -52,7 +59,7 @@ Signature: a page whose `wc -l` is ~2× its `HEAD` size, with a **second frontma
 the body** whose closing `---` is glued onto the end of a body/timestamp line. Cause chain: a
 frontmatter rewrite that re-reads the file it just wrote (so its own output becomes the body),
 then a fence-repair pass keyed on `line == "---"` that cannot see a glued fence and inserts a
-fence mid-page, so the next pass treats the tail as a new document.
+fence mid-page, so the next page-tail becomes a new document.
 Un-double rule that worked: find the first frontmatter's close (accepting a glued fence), then
 the first `type:` line after it that has more keys (`title|description|tags|timestamp`) behind
@@ -82,9 +89,10 @@ grep -rnoE "\((page-a|page-b|...)\.md\)"  --include="*.md" serverAppConfigs-docs
 Both wikilinks and markdown path refs must be repointed (Research `See Also` lists and bench
 pages are where path refs hide). Then **regenerate** index rows with a script, never by hand.
-The generator bug to check for: presence tested as a **bare stem substring** — a page whose
+Generator bugs to check for: presence tested as a **bare stem substring** — a page whose name
-name prefixes another's (`frank-medium` inside `frank-medium-rocmfpx`) then silently never
+prefixes another's (`frank-medium` inside `frank-medium-rocmfpx`) then silently never gets a
-gets a row. Test the wikilink form `[[<stem>]]`.
+row (test the wikilink form `[[<stem>]]`); and **no dead-row sweep**, so deleting a page leaves
 an index row that fails the link check — the generator must drop rows for absent pages too.
 ## 7. Enforce the law with a seam
@@ -96,6 +104,12 @@ re-created era page then cannot pass tests. For the length hint, prefer **derive
 owned by the page that measured it) plus one documented per-page opt-out; never let a size
 ceiling force a ledger to be split across two owners.
 Splitting an over-long page to satisfy a ceiling is usually line-NEGATIVE: one measured split
 turned a 700-line page into 488 + 306 across five files (+23 for the folder net of stub
 deletions), because frontmatter blocks, pointer sections and connective prose are charged per
 file while the facts move for free. Roll the split back, carry `okf-exempt: length` with the
 reason, and keep the stub pages deleted.
 ## 8. Edit-tool hazard (costs the most time)
 Body rows beginning with `-` or `+` are op markers. The documented `+-` escape **writes a
@@ -104,6 +118,10 @@ line untouched and PUT only the indented continuation lines, or convert the note
 bullet whose body lines start with two/four spaces. If a wrapped `[[Two Word Page]]` shows up
 as an unresolved link, the target was hard-wrapped across lines — unwrap it.
 A `PUT` that spans a multi-line statement can silently drop neighbouring assignments
 (auto-repaired boundary echo); after editing a constants block, `grep -n "^[A-Z_]* = "` and
 run a syntax probe before executing.
 ## 9. Delegated writes: verify bytes, never narrative
 Measured in one campaign, all four failure modes live:
@@ -146,7 +164,24 @@ matter how concrete they read; and re-read the source bullet before trusting a t
 - Open the PR through the API with a 600-perm curl config (managed skill
  `gitea-api-pr-operations`), end the body with the `cwd:` / `session:` footer, then
  `xdg-open <PR-URL>` the instant it exists. Never merge without Frank's current explicit OK.
  Push with an explicit refspec (`HEAD:refs/heads/<pr-branch>`) — a worktree's own branch name
  is not the PR branch, and `git push origin HEAD` opens a stray branch.
 - Docs-only change ⇒ **no deploy**. Fast-forward the deploy checkout only
  (`git -C ~/Projects/serverAppConfig merge --ff-only origin/main`).
 - Say what was NOT done, in the PR body: soft lint tallies left (missing `## Citations`),
  conflicts left standing, repo config that was never installed on a host.
 ## 12. Report line counts per area, never one net
 "Compaction" measured against the merge-base **per area**: docs / `scripts/` / `AGENTS.md`.
 A single headline number hides that tooling and prose move in opposite directions — one
 campaign reported "−1,849 vault lines" while the vault was flat and the growth was the two
 enforcement scripts that made the law mechanical. Expect a mature one-owner vault to land
 **docs flat**: the reductions available are deletions of *restatement* (duplicated pages,
 transient deploy chatter in `log.md`, `AGENTS.md` bullets whose numbers an endpoint page owns)
 and they are roughly cancelled by the cost of the citations the verification pass adds. When
 asked to shrink further, show the menu — drop the tools, drop the citations, or accept content
 loss — instead of inventing cuts. `log.md` compaction rule that survived census: drop a line
 only when it matches a transient shape (`/health`, `deployed`, `restart`, `systemctl start`)
 **and** every fact token in it is held by an owner page; a token-held line can still be the
 only record of *when* an incident happened.
@@ -0,0 +1,4 @@
 {
 	"v": 1,
 	"lastConsolidatedAt": 1792440454430
 }
@@ -1,6 +1,6 @@
 {
 	"v": 1,
-	"lastConsolidatedAt": 1792398332410,
+	"lastConsolidatedAt": 1792439707623,
 	"lastResult": {
 		"at": 1791599865775,
 		"sessions": 1,
@@ -1,4 +1,4 @@
 {
 	"v": 1,
-	"lastConsolidatedAt": 1792398289746
+	"lastConsolidatedAt": 1792439491829
 }
@@ -1,6 +1,6 @@
 {
 	"v": 1,
-	"lastConsolidatedAt": 1792400453482,
+	"lastConsolidatedAt": 1792439324791,
 	"lastResult": {
 		"at": 1792398531282,
 		"sessions": 1,
@@ -1 +0,0 @@
 {"v":1,"kind":"product_decision","statement":"Documentation links to @~/Projects/serverAppConfig/serverAppConfigs-docs/","source":"explicit_user","evidence":"correct our documentation to just link to @~/Projects/serverAppConfig/serverAppConfigs-docs/","friction":{"corrective":false,"regression":false,"subtle":false},"sessionId":"01a1531d-3e48-70b0-8ee0-6d48a197cae3","ts":1792397374946}
@@ -1,4 +1,10 @@
 {
 	"v": 1,
-	"lastConsolidatedAt": 1792397349857
+	"lastConsolidatedAt": 1792439315327,
 	"lastResult": {
 		"at": 1792439315327,
 		"sessions": 1,
 		"deltas": 1,
 		"model": "frank-zealot"
 	}
 }
@@ -1,8 +1,8 @@
 {
 	"v": 1,
-	"lastConsolidatedAt": 1792426412619,
+	"lastConsolidatedAt": 1792439612626,
 	"lastResult": {
-		"at": 1792401456699,
+		"at": 1792439612626,
 		"sessions": 1,
 		"deltas": 1,
 		"model": "frank-zealot"
@@ -1,10 +1,10 @@
 {
 	"v": 1,
-	"lastConsolidatedAt": 1792426569902,
+	"lastConsolidatedAt": 1792440990901,
 	"lastResult": {
-		"at": 1792402864677,
+		"at": 1792433353188,
 		"sessions": 1,
-		"deltas": 8,
+		"deltas": 1,
 		"model": "frank-zealot"
 	}
 }
@@ -1,10 +1,10 @@
 {
 	"v": 1,
-	"lastConsolidatedAt": 1792426408958,
+	"lastConsolidatedAt": 1792434572397,
 	"lastResult": {
-		"at": 1792401394555,
+		"at": 1792432178813,
 		"sessions": 1,
-		"deltas": 1,
+		"deltas": 2,
 		"model": "frank-zealot"
 	}
 }
@@ -0,0 +1,4 @@
 {
 	"v": 1,
 	"lastConsolidatedAt": 1792441029706
 }
@@ -0,0 +1,8 @@
 tt.*
 .tests
 doc/tags
 debug
 .repro
 foo.*
 *.log
 data
@@ -0,0 +1,15 @@
 {
  "neodev": {
    "library": {
      "enabled": true,
      "plugins": true
    }
  },
  "neoconf": {
    "plugins": {
      "lua_ls": {
        "enabled": true
      }
    }
  }
 }
@@ -0,0 +1,201 @@
                                 Apache License
                           Version 2.0, January 2004
                        http://www.apache.org/licenses/
   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
   1. Definitions.
      "License" shall mean the terms and conditions for use, reproduction,
      and distribution as defined by Sections 1 through 9 of this document.
      "Licensor" shall mean the copyright owner or entity authorized by
      the copyright owner that is granting the License.
      "Legal Entity" shall mean the union of the acting entity and all
      other entities that control, are controlled by, or are under common
      control with that entity. For the purposes of this definition,
      "control" means (i) the power, direct or indirect, to cause the
      direction or management of such entity, whether by contract or
      otherwise, or (ii) ownership of fifty percent (50%) or more of the
      outstanding shares, or (iii) beneficial ownership of such entity.
      "You" (or "Your") shall mean an individual or Legal Entity
      exercising permissions granted by this License.
      "Source" form shall mean the preferred form for making modifications,
      including but not limited to software source code, documentation
      source, and configuration files.
      "Object" form shall mean any form resulting from mechanical
      transformation or translation of a Source form, including but
      not limited to compiled object code, generated documentation,
      and conversions to other media types.
      "Work" shall mean the work of authorship, whether in Source or
      Object form, made available under the License, as indicated by a
      copyright notice that is included in or attached to the work
      (an example is provided in the Appendix below).
      "Derivative Works" shall mean any work, whether in Source or Object
      form, that is based on (or derived from) the Work and for which the
      editorial revisions, annotations, elaborations, or other modifications
      represent, as a whole, an original work of authorship. For the purposes
      of this License, Derivative Works shall not include works that remain
      separable from, or merely link (or bind by name) to the interfaces of,
      the Work and Derivative Works thereof.
      "Contribution" shall mean any work of authorship, including
      the original version of the Work and any modifications or additions
      to that Work or Derivative Works thereof, that is intentionally
      submitted to Licensor for inclusion in the Work by the copyright owner
      or by an individual or Legal Entity authorized to submit on behalf of
      the copyright owner. For the purposes of this definition, "submitted"
      means any form of electronic, verbal, or written communication sent
      to the Licensor or its representatives, including but not limited to
      communication on electronic mailing lists, source code control systems,
      and issue tracking systems that are managed by, or on behalf of, the
      Licensor for the purpose of discussing and improving the Work, but
      excluding communication that is conspicuously marked or otherwise
      designated in writing by the copyright owner as "Not a Contribution."
      "Contributor" shall mean Licensor and any individual or Legal Entity
      on behalf of whom a Contribution has been received by Licensor and
      subsequently incorporated within the Work.
   2. Grant of Copyright License. Subject to the terms and conditions of
      this License, each Contributor hereby grants to You a perpetual,
      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
      copyright license to reproduce, prepare Derivative Works of,
      publicly display, publicly perform, sublicense, and distribute the
      Work and such Derivative Works in Source or Object form.
   3. Grant of Patent License. Subject to the terms and conditions of
      this License, each Contributor hereby grants to You a perpetual,
      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
      (except as stated in this section) patent license to make, have made,
      use, offer to sell, sell, import, and otherwise transfer the Work,
      where such license applies only to those patent claims licensable
      by such Contributor that are necessarily infringed by their
      Contribution(s) alone or by combination of their Contribution(s)
      with the Work to which such Contribution(s) was submitted. If You
      institute patent litigation against any entity (including a
      cross-claim or counterclaim in a lawsuit) alleging that the Work
      or a Contribution incorporated within the Work constitutes direct
      or contributory patent infringement, then any patent licenses
      granted to You under this License for that Work shall terminate
      as of the date such litigation is filed.
   4. Redistribution. You may reproduce and distribute copies of the
      Work or Derivative Works thereof in any medium, with or without
      modifications, and in Source or Object form, provided that You
      meet the following conditions:
      (a) You must give any other recipients of the Work or
          Derivative Works a copy of this License; and
      (b) You must cause any modified files to carry prominent notices
          stating that You changed the files; and
      (c) You must retain, in the Source form of any Derivative Works
          that You distribute, all copyright, patent, trademark, and
          attribution notices from the Source form of the Work,
          excluding those notices that do not pertain to any part of
          the Derivative Works; and
      (d) If the Work includes a "NOTICE" text file as part of its
          distribution, then any Derivative Works that You distribute must
          include a readable copy of the attribution notices contained
          within such NOTICE file, excluding those notices that do not
          pertain to any part of the Derivative Works, in at least one
          of the following places: within a NOTICE text file distributed
          as part of the Derivative Works; within the Source form or
          documentation, if provided along with the Derivative Works; or,
          within a display generated by the Derivative Works, if and
          wherever such third-party notices normally appear. The contents
          of the NOTICE file are for informational purposes only and
          do not modify the License. You may add Your own attribution
          notices within Derivative Works that You distribute, alongside
          or as an addendum to the NOTICE text from the Work, provided
          that such additional attribution notices cannot be construed
          as modifying the License.
      You may add Your own copyright statement to Your modifications and
      may provide additional or different license terms and conditions
      for use, reproduction, or distribution of Your modifications, or
      for any such Derivative Works as a whole, provided Your use,
      reproduction, and distribution of the Work otherwise complies with
      the conditions stated in this License.
   5. Submission of Contributions. Unless You explicitly state otherwise,
      any Contribution intentionally submitted for inclusion in the Work
      by You to the Licensor shall be under the terms and conditions of
      this License, without any additional terms or conditions.
      Notwithstanding the above, nothing herein shall supersede or modify
      the terms of any separate license agreement you may have executed
      with Licensor regarding such Contributions.
   6. Trademarks. This License does not grant permission to use the trade
      names, trademarks, service marks, or product names of the Licensor,
      except as required for reasonable and customary use in describing the
      origin of the Work and reproducing the content of the NOTICE file.
   7. Disclaimer of Warranty. Unless required by applicable law or
      agreed to in writing, Licensor provides the Work (and each
      Contributor provides its Contributions) on an "AS IS" BASIS,
      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
      implied, including, without limitation, any warranties or conditions
      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
      PARTICULAR PURPOSE. You are solely responsible for determining the
      appropriateness of using or redistributing the Work and assume any
      risks associated with Your exercise of permissions under this License.
   8. Limitation of Liability. In no event and under no legal theory,
      whether in tort (including negligence), contract, or otherwise,
      unless required by applicable law (such as deliberate and grossly
      negligent acts) or agreed to in writing, shall any Contributor be
      liable to You for damages, including any direct, indirect, special,
      incidental, or consequential damages of any character arising as a
      result of this License or out of the use or inability to use the
      Work (including but not limited to damages for loss of goodwill,
      work stoppage, computer failure or malfunction, or any and all
      other commercial damages or losses), even if such Contributor
      has been advised of the possibility of such damages.
   9. Accepting Warranty or Additional Liability. While redistributing
      the Work or Derivative Works thereof, You may choose to offer,
      and charge a fee for, acceptance of support, warranty, indemnity,
      or other liability obligations and/or rights consistent with this
      License. However, in accepting such obligations, You may act only
      on Your own behalf and on Your sole responsibility, not on behalf
      of any other Contributor, and only if You agree to indemnify,
      defend, and hold each Contributor harmless for any liability
      incurred by, or claims asserted against, such Contributor by reason
      of your accepting any such warranty or additional liability.
   END OF TERMS AND CONDITIONS
   APPENDIX: How to apply the Apache License to your work.
      To apply the Apache License to your work, attach the following
      boilerplate notice, with the fields enclosed by brackets "[]"
      replaced with your own identifying information. (Don't include
      the brackets!)  The text should be enclosed in the appropriate
      comment syntax for the file format. We also recommend that a
      file or class name and description of purpose be included on the
      same "printed page" as the copyright notice for easier
      identification within third-party archives.
   Copyright [yyyy] [name of copyright owner]
   Licensed under the Apache License, Version 2.0 (the "License");
   you may not use this file except in compliance with the License.
   You may obtain a copy of the License at
       http://www.apache.org/licenses/LICENSE-2.0
   Unless required by applicable law or agreed to in writing, software
   distributed under the License is distributed on an "AS IS" BASIS,
   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   See the License for the specific language governing permissions and
   limitations under the License.
@@ -0,0 +1,4 @@
 # 💤 LazyVim
 A starter template for [LazyVim](https://github.com/LazyVim/LazyVim).
 Refer to the [documentation](https://lazyvim.github.io/installation) to get started.
@@ -0,0 +1,2 @@
 -- bootstrap lazy.nvim, LazyVim and your plugins
 require("config.lazy")
@@ -0,0 +1,35 @@
 {
  "LazyVim": { "branch": "main", "commit": "999700997f72227187d49d8b92667183dc7fc809" },
  "base16-nvim": { "branch": "master", "commit": "7183774e90841f4bd27a47cb6e75cf532fd1192d" },
  "blink.cmp": { "branch": "main", "commit": "78336bc89ee5365633bcf754d93df01678b5c08f" },
  "bufferline.nvim": { "branch": "main", "commit": "655133c3b4c3e5e05ec549b9f8cc2894ac6f51b3" },
  "catppuccin": { "branch": "main", "commit": "edefef779ab08ce1a4a404713e3012b0d202bd35" },
  "conform.nvim": { "branch": "master", "commit": "016802de402556da54c36bd7359b441266b01cdd" },
  "flash.nvim": { "branch": "main", "commit": "5f0f270fdc7c5b0c21d903ee85b9cb06f2ac636a" },
  "friendly-snippets": { "branch": "main", "commit": "b4d01b0fdf3c9a549961c2f9ffe8dc09be166219" },
  "gitsigns.nvim": { "branch": "main", "commit": "fd780920613e541cbdfac41bf711583ed49f9249" },
  "grug-far.nvim": { "branch": "main", "commit": "bbde8ef5ae46ceee2c3bd8b21fc048c5f8ffbfc0" },
  "lazy.nvim": { "branch": "main", "commit": "85c7ff3711b730b4030d03144f6db6375044ae82" },
  "lazydev.nvim": { "branch": "main", "commit": "ff2cbcba459b637ec3fd165a2be59b7bbaeedf0d" },
  "lualine.nvim": { "branch": "master", "commit": "221ce6b2d999187044529f49da6554a92f740a96" },
  "mason-lspconfig.nvim": { "branch": "main", "commit": "00b5473cca4db5b410ff4bae724e3b6e21f2687f" },
  "mason.nvim": { "branch": "main", "commit": "2a6940af80375532e5e9e7c1f2fc6319a1b7a69d" },
  "mini.ai": { "branch": "main", "commit": "d0c4987a1ead2bcf4eb22cc9815c662d76677c08" },
  "mini.icons": { "branch": "main", "commit": "f916635dc5ae2f479fbb9ab8184bb9444b62e86c" },
  "mini.pairs": { "branch": "main", "commit": "03eb1f0062a2cee5314d1ac3939246e4bb21352e" },
  "noice.nvim": { "branch": "main", "commit": "7bfd942445fb63089b59f97ca487d605e715f155" },
  "nui.nvim": { "branch": "main", "commit": "10fc361835c856ba4233ef5ea135b919bf3dce97" },
  "nvim-lint": { "branch": "master", "commit": "f6230a5c06ba59e6059c14637f1dbe29a7978b9b" },
  "nvim-lspconfig": { "branch": "master", "commit": "45a3a444b710511c39abca3b60bb6e23a21e3de5" },
  "nvim-treesitter": { "branch": "main", "commit": "29212d826054bb2948fa9d3a99eca9bf6a050eb2" },
  "nvim-treesitter-textobjects": { "branch": "main", "commit": "5c7b0263797dfd1bd6202f2b219f3b53a80b2187" },
  "nvim-ts-autotag": { "branch": "main", "commit": "d7220b55e16ed3c04e88086256def5d282429493" },
  "persistence.nvim": { "branch": "main", "commit": "b20b2a7887bd39c1a356980b45e03250f3dce49c" },
  "plenary.nvim": { "branch": "master", "commit": "74b06c6c75e4eeb3108ec01852001636d85a932b" },
  "snacks.nvim": { "branch": "main", "commit": "882c996cf28183f4d63640de0b4c02ec886d01f2" },
  "todo-comments.nvim": { "branch": "main", "commit": "31e3c38ce9b29781e4422fc0322eb0a21f4e8668" },
  "tokyonight.nvim": { "branch": "main", "commit": "cdc07ac78467a233fd62c493de29a17e0cf2b2b6" },
  "trouble.nvim": { "branch": "main", "commit": "bd67efe408d4816e25e8491cc5ad4088e708a69a" },
  "ts-comments.nvim": { "branch": "main", "commit": "a59d6092213447450191122c9346f309161504cb" },
  "which-key.nvim": { "branch": "main", "commit": "3aab2147e74890957785941f0c1ad87d0a44c15a" }
 }
@@ -0,0 +1,10 @@
 {
  "extras": [
  ],
  "install_version": 8,
  "news": {
    "NEWS.md": "11866"
  },
  "version": 8
 }
@@ -0,0 +1,8 @@
 -- Autocmds are automatically loaded on the VeryLazy event
 -- Default autocmds that are always set: https://github.com/LazyVim/LazyVim/blob/main/lua/lazyvim/config/autocmds.lua
 --
 -- Add any additional autocmds here
 -- with `vim.api.nvim_create_autocmd`
 --
 -- Or remove existing autocmds by their group name (which is prefixed with `lazyvim_` for the defaults)
 -- e.g. vim.api.nvim_del_augroup_by_name("lazyvim_wrap_spell")
@@ -0,0 +1,3 @@
 -- Keymaps are automatically loaded on the VeryLazy event
 -- Default keymaps that are always set: https://github.com/LazyVim/LazyVim/blob/main/lua/lazyvim/config/keymaps.lua
 -- Add any additional keymaps here
@@ -0,0 +1,53 @@
 local lazypath = vim.fn.stdpath("data") .. "/lazy/lazy.nvim"
 if not (vim.uv or vim.loop).fs_stat(lazypath) then
  local lazyrepo = "https://github.com/folke/lazy.nvim.git"
  local out = vim.fn.system({ "git", "clone", "--filter=blob:none", "--branch=stable", lazyrepo, lazypath })
  if vim.v.shell_error ~= 0 then
    vim.api.nvim_echo({
      { "Failed to clone lazy.nvim:\n", "ErrorMsg" },
      { out, "WarningMsg" },
      { "\nPress any key to exit..." },
    }, true, {})
    vim.fn.getchar()
    os.exit(1)
  end
 end
 vim.opt.rtp:prepend(lazypath)
 require("lazy").setup({
  spec = {
    -- add LazyVim and import its plugins
    { "LazyVim/LazyVim", import = "lazyvim.plugins" },
    -- import/override with your plugins
    { import = "plugins" },
  },
  defaults = {
    -- By default, only LazyVim plugins will be lazy-loaded. Your custom plugins will load during startup.
    -- If you know what you're doing, you can set this to `true` to have all your custom plugins lazy-loaded by default.
    lazy = false,
    -- It's recommended to leave version=false for now, since a lot the plugin that support versioning,
    -- have outdated releases, which may break your Neovim install.
    version = false, -- always use the latest git commit
    -- version = "*", -- try installing the latest stable version for plugins that support semver
  },
  install = { colorscheme = { "tokyonight", "habamax" } },
  checker = {
    enabled = true, -- check for plugin updates periodically
    notify = false, -- notify on update
  }, -- automatically check for plugin updates
  performance = {
    rtp = {
      -- disable some rtp plugins
      disabled_plugins = {
        "gzip",
        -- "matchit",
        -- "matchparen",
        -- "netrwPlugin",
        "tarPlugin",
        "tohtml",
        "tutor",
        "zipPlugin",
      },
    },
  },
 })
@@ -0,0 +1,3 @@
 -- Options are automatically loaded before lazy.nvim startup
 -- Default options that are always set: https://github.com/LazyVim/LazyVim/blob/main/lua/lazyvim/config/options.lua
 -- Add any additional options here
@@ -0,0 +1,70 @@
 local M = {}
 function M.setup()
  require('base16-colorscheme').setup({
    base00 = '#181818',
    base01 = '#282828',
    base02 = '#323232',
    base03 = '#646464',
    base04 = '#95a99f',
    base05 = '#e4e4ef',
    base06 = '#e4e4ef',
    base07 = '#e4e4ef',
    base08 = '#f43841',
    base09 = '#9e95c7',
    base0A = '#96a6c8',
    base0B = '#f43841',
    base0C = '#a596e9',
    base0D = '#f8868c',
    base0E = '#96b0e9',
    base0F = '#becff4',
  })
  local hi = function(group, opts)
    vim.api.nvim_set_hl(0, group, opts)
  end
  -- telescope.nvim
  hi('TelescopeNormal',         { fg = '#e4e4ef',          bg = '#181818' })
  hi('TelescopeBorder',         { fg = '#646464',             bg = '#181818' })
  hi('TelescopePromptNormal',   { fg = '#e4e4ef',          bg = '#181818' })
  hi('TelescopePromptBorder',   { fg = '#646464',             bg = '#181818' })
  hi('TelescopePromptPrefix',   { fg = '#f43841',             bg = '#181818' })
  hi('TelescopePromptCounter',  { fg = '#95a99f',  bg = '#181818' })
  hi('TelescopePromptTitle',    { fg = '#181818',             bg = '#f43841' })
  hi('TelescopePreviewTitle',   { fg = '#181818',             bg = '#96a6c8' })
  hi('TelescopeResultsTitle',   { fg = '#181818',             bg = '#9e95c7' })
  hi('TelescopeSelection',      { fg = '#e4e4ef',          bg = '#323232' })
  hi('TelescopeSelectionCaret', { fg = '#f43841',             bg = '#323232' })
  hi('TelescopeMatching',       { fg = '#f43841',             bold = true })
  -- mini.pick
  hi('MiniPickNormal',         { fg = '#e4e4ef',          bg = '#181818' })
  hi('MiniPickBorder',         { fg = '#646464',             bg = '#181818' })
  hi('MiniPickPrompt',   { fg = '#e4e4ef',          bg = '#181818' })
  hi('MiniPickPromptPrefix',   { fg = '#f43841',             bg = '#181818' })
  hi('MiniPickBorderText',    { fg = '#181818',             bg = '#f43841' })
  hi('MiniPickMatchCurrent',      { fg = '#e4e4ef',          bg = '#323232' })
  hi('MiniPickPromptCaret', { fg = '#f43841',             bg = '#323232' })
  hi('MiniPickMatchRanges',       { fg = '#f43841',             bold = true })
 end
 -- Register a signal handler for SIGUSR1 (matugen updates).
 -- The handler re-requires this module, which re-runs the code below, so the
 -- previous handle is stopped first; otherwise handlers double on every signal.
 if _G.__matugen_signal then
  _G.__matugen_signal:stop()
  _G.__matugen_signal:close()
 end
 local signal = vim.uv.new_signal()
 _G.__matugen_signal = signal
 signal:start(
  'sigusr1',
  vim.schedule_wrap(function()
    package.loaded['matugen'] = nil
    require('matugen').setup()
  end)
 )
 return M
@@ -0,0 +1,197 @@
 -- since this is just an example spec, don't actually load anything here and return an empty spec
 -- stylua: ignore
 if true then return {} end
 -- every spec file under the "plugins" directory will be loaded automatically by lazy.nvim
 --
 -- In your plugin files, you can:
 -- * add extra plugins
 -- * disable/enabled LazyVim plugins
 -- * override the configuration of LazyVim plugins
 return {
  -- add gruvbox
  { "ellisonleao/gruvbox.nvim" },
  -- Configure LazyVim to load gruvbox
  {
    "LazyVim/LazyVim",
    opts = {
      colorscheme = "gruvbox",
    },
  },
  -- change trouble config
  {
    "folke/trouble.nvim",
    -- opts will be merged with the parent spec
    opts = { use_diagnostic_signs = true },
  },
  -- disable trouble
  { "folke/trouble.nvim", enabled = false },
  -- override nvim-cmp and add cmp-emoji
  {
    "hrsh7th/nvim-cmp",
    dependencies = { "hrsh7th/cmp-emoji" },
    ---@param opts cmp.ConfigSchema
    opts = function(_, opts)
      table.insert(opts.sources, { name = "emoji" })
    end,
  },
  -- change some telescope options and a keymap to browse plugin files
  {
    "nvim-telescope/telescope.nvim",
    keys = {
      -- add a keymap to browse plugin files
      -- stylua: ignore
      {
        "<leader>fp",
        function() require("telescope.builtin").find_files({ cwd = require("lazy.core.config").options.root }) end,
        desc = "Find Plugin File",
      },
    },
    -- change some options
    opts = {
      defaults = {
        layout_strategy = "horizontal",
        layout_config = { prompt_position = "top" },
        sorting_strategy = "ascending",
        winblend = 0,
      },
    },
  },
  -- add pyright to lspconfig
  {
    "neovim/nvim-lspconfig",
    ---@class PluginLspOpts
    opts = {
      ---@type lspconfig.options
      servers = {
        -- pyright will be automatically installed with mason and loaded with lspconfig
        pyright = {},
      },
    },
  },
  -- add tsserver and setup with typescript.nvim instead of lspconfig
  {
    "neovim/nvim-lspconfig",
    dependencies = {
      "jose-elias-alvarez/typescript.nvim",
      init = function()
        require("lazyvim.util").lsp.on_attach(function(_, buffer)
          -- stylua: ignore
          vim.keymap.set( "n", "<leader>co", "TypescriptOrganizeImports", { buffer = buffer, desc = "Organize Imports" })
          vim.keymap.set("n", "<leader>cR", "TypescriptRenameFile", { desc = "Rename File", buffer = buffer })
        end)
      end,
    },
    ---@class PluginLspOpts
    opts = {
      ---@type lspconfig.options
      servers = {
        -- tsserver will be automatically installed with mason and loaded with lspconfig
        tsserver = {},
      },
      -- you can do any additional lsp server setup here
      -- return true if you don't want this server to be setup with lspconfig
      ---@type table<string, fun(server:string, opts:_.lspconfig.options):boolean?>
      setup = {
        -- example to setup with typescript.nvim
        tsserver = function(_, opts)
          require("typescript").setup({ server = opts })
          return true
        end,
        -- Specify * to use this function as a fallback for any server
        -- ["*"] = function(server, opts) end,
      },
    },
  },
  -- for typescript, LazyVim also includes extra specs to properly setup lspconfig,
  -- treesitter, mason and typescript.nvim. So instead of the above, you can use:
  { import = "lazyvim.plugins.extras.lang.typescript" },
  -- add more treesitter parsers
  {
    "nvim-treesitter/nvim-treesitter",
    opts = {
      ensure_installed = {
        "bash",
        "html",
        "javascript",
        "json",
        "lua",
        "markdown",
        "markdown_inline",
        "python",
        "query",
        "regex",
        "tsx",
        "typescript",
        "vim",
        "yaml",
      },
    },
  },
  -- since `vim.tbl_deep_extend`, can only merge tables and not lists, the code above
  -- would overwrite `ensure_installed` with the new value.
  -- If you'd rather extend the default config, use the code below instead:
  {
    "nvim-treesitter/nvim-treesitter",
    opts = function(_, opts)
      -- add tsx and treesitter
      vim.list_extend(opts.ensure_installed, {
        "tsx",
        "typescript",
      })
    end,
  },
  -- the opts function can also be used to change the default opts:
  {
    "nvim-lualine/lualine.nvim",
    event = "VeryLazy",
    opts = function(_, opts)
      table.insert(opts.sections.lualine_x, {
        function()
          return "😄"
        end,
      })
    end,
  },
  -- or you can return new options to override all the defaults
  {
    "nvim-lualine/lualine.nvim",
    event = "VeryLazy",
    opts = function()
      return {
        --[[add your custom lualine config here]]
      }
    end,
  },
  -- use mini.starter instead of alpha
  { import = "lazyvim.plugins.extras.ui.mini-starter" },
  -- add jsonls and schemastore packages, and setup treesitter for json, json5 and jsonc
  { import = "lazyvim.plugins.extras.lang.json" },
  -- add any tools you want to have installed below
  {
    "williamboman/mason.nvim",
    opts = {
      ensure_installed = {
        "stylua",
        "shellcheck",
        "shfmt",
        "flake8",
      },
    },
  },
 }
@@ -0,0 +1,22 @@
 -- Applies the hand-kept wallpaper palette (lua/matugen.lua) on top of LazyVim's
 -- colorscheme instead of living with tokyonight defaults.
 --
 -- base16-colorscheme writes highlights directly and never touches v:colors_name,
 -- so LazyVim keeps thinking tokyonight is loaded and its plugin-specific tweaks
 -- still run; ours is the last word on the UI groups.
 return {
  "RRethy/base16-nvim",
  lazy = false,
  priority = 900,
  config = function()
    -- LazyVim loads its colorscheme after plugin configs, so re-apply on every
    -- ColorScheme event: that also makes `:colorscheme foo` land on our palette.
    vim.api.nvim_create_autocmd("ColorScheme", {
      desc = "Re-apply the matugen base16 palette after any colorscheme",
      callback = function()
        require("matugen").setup()
      end,
    })
    require("matugen").setup()
  end,
 }
@@ -0,0 +1,3 @@
 indent_type = "Spaces"
 indent_width = 2
 column_width = 120
@@ -275,13 +275,13 @@ transition = [ "fade" ]
    interval_seconds = 1200
    [wallpaper.default]
-    path = "/home/blank/.local/share/noctalia/wallpapers/wallhaven_ymp267.jpg"
+    path = "/home/blank/.local/share/noctalia/wallpapers/wallhaven_v9w8r5.jpg"
    [wallpaper.last]
-    path = "/home/blank/.local/share/noctalia/wallpapers/wallhaven_ymp267.jpg"
+    path = "/home/blank/.local/share/noctalia/wallpapers/wallhaven_v9w8r5.jpg"
    [wallpaper.monitors.DP-1]
-    path = "/home/blank/.local/share/noctalia/wallpapers/wallhaven_y8ewzk.jpg"
+    path = "/home/blank/.local/share/noctalia/wallpapers/wallhaven_v9w8r5.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_ymp267.jpg"
+    path = "/home/blank/.local/share/noctalia/wallpapers/wallhaven_v9w8r5.jpg"
 [weather]
 unit = "imperial"
@@ -4,3 +4,8 @@ source /usr/share/cachyos-zsh-config/cachyos-config.zsh
 [ -f ~/.config/secrets/hf_token ] && export HF_TOKEN="$(cat ~/.config/secrets/hf_token)"
 [ -d "$HOME/.bun/bin" ] && export PATH="$HOME/.bun/bin:$PATH"
 # LazyVim lives in its own NVIM_APPNAME profile (~/.config/lazyvim), so plain
 # `nvim` stays a vanilla quick-edit editor. NVIM_APPNAME swaps config, data,
 # state and cache dirs wholesale — no shared plugin tree between the two.
 lazyvim() { NVIM_APPNAME=lazyvim nvim "$@"; }
@@ -1,7 +1,7 @@
 ---
 type: reference
 title: dankvoice
-description: omp extension that speaks assistant output with the fleet's cloned voices through frank-tts.
+description: Voice output ships as the dank/dankvoice package; this page keeps only the fleet integration facts and the cutover procedure.
 tags:
  - omp
  - extension
@@ -15,244 +15,95 @@ timestamp: 2026-10-19
 # dankvoice
-`agent/extensions/dankvoice.ts` adds cloned-voice speech to the interactive
+Voice output lives in the **`dank/dankvoice` package**:
-harness: `/say` opens the options menu, `/say <text>` speaks through the
+`pi install git:http://192.168.0.143:3000/dank/dankvoice.git`. This page owns
-speakers and `/say on` narrates the assistant's thinking and final answer
+only fleet integration and the cutover. The package README
-after every turn. The words are first rewritten into natural spoken prose by
+(<http://192.168.0.143:3000/dank/dankvoice>) owns the `/say` command
-the **@tiny** role model (exactly what the built-in vocalizer's
+reference, the settings/env knob list, the segmentation state machine, the
-`speech.enhanced` does), and everything is served by **frank-tts**
+enhancer port, and mood control — never duplicate those facts here.
 (Dankclaw :7772, the `speech` model role in [agent/models.yml](/core/index.md)).
-## Why it exists
+## Fleet wiring
-Nothing built into the harness can pronounce Frank's cloned voices.
+* **TTS endpoint** — resolved from the provider block whose model row carries
  `api: openai-speech` in [agent/models.yml](/core/index.md):
  **frank-tts** on Dankclaw `:7772`. LAN-only — no Caddy vhost fronts it.
 * **Narration humanizer** — the harness `@tiny` role
  (`modelRoles.tiny` in `agent/config.yml`), on this fleet **frank-zealot**
  (Dankclaw `:7771`).
 * **Hybrid-endpoint trap (load-bearing)** — a raw `fetch` to a
  thinking-by-default model spends the token budget on `reasoning_content`
  and answers `content: ""`. The package pins
  `chat_template_kwargs: { enable_thinking: false }` on the rewrite call; do
  not remove it. On a hybrid endpoint, empty content beside non-empty
  `reasoning_content` means the flag was ignored — that is a failed rewrite
  (fall back to the mechanical text), never the legitimate "nothing to say".
 * **Voice contract** — omitting `voice` is legal: frank-tts fills its
  `DEFAULT_VOICE` (2026-10-18 voice-pack work). `GET {base}/v1/audio/voices`
  answers a bare JSON array; an unknown voice answers 400 with
  `available_voices`, which the package uses as roster fallback. On this shim
  `GET /v1/voices` and `GET /v1/models` are 404.
-| Surface | Engine | Verdict |
+## Cutover (Refs #34)
 |---|---|---|
 | TUI speak-aloud (`speech.enabled`, `speech.voice`) | bundled Kokoro ONNX worker, `synthesizeStream(voice, speed, signal)` | Kokoro voice enum only; never consults `models.yml` or the speech role |
 | `omp say [TEXT]` | same local backend (`--model` = *local* model key) | `omp say --voice narrator1 "test"` → `error: Expected --voice to be one of: af_heart, af_bella, af_nicole, af_kore, af_sarah, am_michael, am_fenrir, am_puck, bf_emma, bm_george, bm_fable` (verified 2026-10-18) |
 | `tts` tool / `xd://tts` device (`modelRoles.speech`) | frank-tts over OpenAI `/v1/audio/speech` | cloned voices work, but only as a **file** — nothing plays them |
-`dankvoice` is not a patch to that vocalizer (harness code, not ours); it is a
+The `agent/extensions/dankvoice.ts` drop-in and its 26-test bats suite are
-second transport that happens to speak, so Kokoro stays available for quick
+retired here (the package suite is a strict superset; test names ported 1:1).
-local speech and the cloned voices carry the real narration.
+Per box:
-## Commands
+1. `pi install git:http://192.168.0.143:3000/dank/dankvoice.git`
 2. `/say status`, then "Speak a test phrase" from the `/say` menu — the
   audible proof a silent session needs.
 3. Pull `main` (the drop-in disappears with it) and restart the session.
-| Command | Effect |
+Menu choices survive the cutover: both transports persist to the same
-|---|---|
+gitignored settings file, `~/.omp/cache/dankvoice.json`
-| `/say` \| `/say menu` | options menu (`ctx.ui.select`): auto-speak toggle, voice, output device, player, spoken cap, thinking-narration toggle, humanize toggle, test phrase |
+(`DANKVOICE_CONFIG` relocates it).
 | `/say <text>` | synthesize once and play; interrupts whatever is playing |
 | `/say on` \| `/say off` | arm/disarm auto-speak of the thinking blocks and final text at `agent_end`; the footer shows `🔊 <voice>` while armed |
 | `/say voice <name>` | pick a voice; an empty name defers to the server's own default |
 | `/say voices` | list what frank-tts reports |
 | `/say stop` | cut the current utterance |
 | `/say status` \| `/say help` | endpoint, voice, player, device, cap, thinking, humanize |
-Menu choices persist to `~/.omp/cache/dankvoice.json` (runtime state, never
+## Why not the built-in vocalizer
 tracked); the environment overrides the file, the file overrides defaults.
 "Speak a test phrase" synthesizes a short line through the current voice,
 player and device — the audible proof whenever a session "has say on" but
 stays silent.
-Auto-speak is skipped in `print`/`json` mode so benches and pipelines stay
+The harness speak-aloud path (`speech.enabled` / `speech.voice`, `omp say`)
-silent. Each spoken unit — thinking first when narrated, then the answer —
+synthesizes with bundled Kokoro ONNX against a **compile-time voice enum** —
-is first rewritten into spoken prose by the @tiny model; when the enhancer
+cloned voices can never reach it, and no setting routes it to frank-tts.
-(below) declines, the text goes to segmentation as-is, where fenced code and
+`dankvoice` is a second transport beside it, not a patch: Kokoro stays for
-tables vanish, links collapse to their label and bullets and table pipes
+quick local speech, the package carries cloned-voice narration. The `tts`
-disappear. A long answer is never one monolithic synthesis request; see
+tool / `xd://tts` device reach frank-tts too, but produce files, not audio
-[Segmentation](#segmentation) for how utterances are cut and played.
+playback.
-## Segmentation
+## Arming auto-speak
-Utterances are cut by a state machine ported from the harness's own
+Arming is **session-scoped by design**: `/say on` arms the running session and
-speak-aloud vocalizer (the minified `fHe` class in the agent bundle's
+is deliberately never persisted. A session that starts silent is a config
-`dist/cli.js`), kept deliberately in lockstep with the stock path:
+state, not a fault — set `"auto": true` in `~/.omp/cache/dankvoice.json` (this
 fleet does) or export `DANKVOICE_AUTO=1` to start armed. Editing the settings
 file mid-session does nothing; the plugin reads it at startup.
-* A strong boundary is a run of `[.!?…]` followed by whitespace — so
+Two checks prove the chain, in order: `/say status` must report
-  `!!!!!` and `...` are one boundary, never a pile of cuts.
+`auto-speak on` with a real endpoint (not `NO ENDPOINT`), and `pgrep -a pw-play`
-* Boundaries after `e.g.`, `etc.`, `Mr.` and friends, or inside inline
+during a turn must show one player per spoken segment, `--target` set to the
-  code, don't count; decimals (`3.5`, `1,5`) survive because a boundary
+saved sink. Thinking narration rides the same arming (`thinking: true`).
  requires trailing whitespace.
 * Line starts are classified: table rows and fenced code are swallowed
  whole (their content is never read aloud), heading and bullet markers
  vanish, ordered-list markers speak their number ("1, …"), quote markers
  strip.
 * Per segment, markdown is cleaned: links collapse to their label, URLs
  to their host, deep paths to their last segment; emphasis markup dies.
 * Segments aim for one sentence; run-ons break at commas or word wraps
  before 280 characters.
 Playback is strictly sequential: segment N+1 is synthesized only after
 segment N's player process exited, so audio never stacks. The chain runs
 detached from `agent_end` (fire-and-forget) and may legitimately outlive
 the harness's 30 s handler timeout — the old awaiting design produced a
 "handler timed out after 30000ms" toast on long answers. A new utterance,
 `/say stop`, or disarming auto-speak retires the live chain through a run
 token: the current player is killed and pending segments are skipped.
 `DANKVOICE_MAX` is a per-answer character budget: the leading whole
 segments that fit are spoken, the rest are dropped — the thinking unit
 draws on it before the answer does.
 ## Endpoint resolution
 The base URL is **read from `agent/models.yml`**, from the provider block whose
 model row carries `api: openai-speech` — the same row the `speech` role
 resolves, so no host address and no credential appears in this file. From
 `baseUrl: http://192.168.0.143:7772/v1` it derives
 `POST …/v1/audio/speech`, `GET …/v1/audio/voices` and `GET …/health`.
 | Environment | Default | Meaning |
 |---|---|---|
 | `DANKVOICE_URL` | models.yml | speech base URL (`…/v1`), bypasses the YAML read |
 | `DANKVOICE_MODEL` | the id in that block (`frank-tts`) | model named in the request body |
 | `DANKVOICE_CONFIG` | `~/.omp/cache/dankvoice.json` | persisted menu choices (voice, player, sink, cap, auto) |
 | `DANKVOICE_VOICE` | empty (server default) | default voice name |
 | `DANKVOICE_AUTO=1` | off | start with auto-speak armed |
 | `DANKVOICE_MAX` | `700` | spoken-character budget per answer (whole leading segments, shared by the thinking and answer units) |
 | `DANKVOICE_PLAYER` | detect | player binary, skipping detection |
 | `DANKVOICE_MODELS` | `~/.omp/agent/models.yml` | YAML to read the endpoint from |
 | `DANKVOICE_REWRITE_URL` | the @tiny role | chat base URL (`…/v1`) for the enhancer, bypassing role resolution |
 | `DANKVOICE_REWRITE_MODEL` | the @tiny role's model | chat model named in the rewrite body |
 | `DANKVOICE_REWRITE=0` | enhancer on when a route resolves | speak mechanical text |
 | `DANKVOICE_THINKING` | settings file, default on | `0`/`1` force thinking narration off/on |
 | `DANKVOICE_OMPCONFIG` | `~/.omp/agent/config.yml` | YAML to read the `modelRoles.tiny` role from |
 Player detection order is `pw-play` → `paplay` → `ffplay` (PipeWire first:
 the workstations run WirePlumber). A saved output device routes the player
 explicitly — `pw-play --target <sink>` or `paplay --device=<sink>`; ffplay
 has no device concept and ignores it — while an unset device leaves the
 player's own default. Sinks are enumerated with `wpctl list audio sinks`;
 if wireplumber is unreachable the menu offers only "system default". Each
 utterance is written to `$TMPDIR/dankvoice-*/say-<ms>.wav` and the file plus
 its directory are removed when the player process exits.
 ## Humanized narration (the @tiny role)
 The built-in vocalizer never reads answers aloud verbatim when
 `speech.enhanced` is on: a small model rewrites each utterance into words a
 person would say. `dankvoice` ports that enhancer — same system prompt
 (verbatim from the bundle), same budgets (1536 max tokens, 6 s timeout,
 4000-char input window), same contract (a failed rewrite falls back to the
 mechanically cleaned text; an empty rewrite skips the unit as "nothing to
 say"). The target model is the harness's `@tiny` role, resolved the way the
 harness resolves it: `modelRoles.tiny` in `agent/config.yml` reads
 `provider (host)/model:effort`; the provider block in `agent/models.yml`
 supplies the `baseUrl`; the request is `POST {base}/chat/completions`. On
 this fleet that is **frank-zealot** (`llamacpp (dankclaw-3090)`,
 `:7771`) — the 6 s abort keeps a slow tiny model off the critical path.
 The request body pins `chat_template_kwargs: { enable_thinking: false }`,
 and that field is load-bearing: the harness injects it for managed roles,
 but a raw `fetch` gets the model's default — thinking on — so the Qwen35
 hybrid spends the budget on `reasoning_content` and answers `content: ""`
 (measured: 6.9 s / 6893 reasoning chars / empty content without the flag;
 0.55 s / 369 clean chars with it). For a hybrid endpoint, empty content
 beside non-empty `reasoning_content` means the flag was ignored — a failed
 rewrite (mechanical fallback), never the legitimate "nothing to say".
 Thinking blocks ride the same path: at `agent_end` the last assistant
 message's true `thinking` parts are narrated (rewritten first, as their own
 unit, before the answer), while blocks flagged `narration: true` — which
 providers use to address the user through the thinking channel — count as
 answer text. The menu, `/say status`, and `DANKVOICE_THINKING` toggle it;
 the choice persists in the settings file.
 ## Verified facts (2026-10-18, extended 2026-10-19)
 * **Extension discovery** — any `.ts` file in `~/.omp/agent/extensions/` loads
  at startup: a probe file there printed `loaded 2026-10-19T02:36:55Z` from a
  fresh `omp -p` run. `omp --help` documents `--no-extensions` (discovery off,
  explicit `-e/--extension` and `--hook` still load) and `plugin install|link`.
 * **Endpoint** — resolving the live `agent/models.yml` yields
  `speechUrl http://192.168.0.143:7772/v1/audio/speech`,
  `voicesUrl …/v1/audio/voices`, `healthUrl …/health`, `model frank-tts`.
 * **Roster** — `GET /v1/audio/voices` answers the bare JSON array
  `["narrator1","narrator2","narrator3"]`; `/health` answers
  `{"status":"ok","backend":"omni-http","voices":[…]}`. `GET /v1/voices` and
  `GET /v1/models` are **404** on this shim, and an unknown voice answers
  `400 unknown voice 'zzz'; available voices: …` with `available_voices` in the
  body — which is the fallback the extension uses if the roster route ever
  disappears.
 * **Omitting `voice` is legal** — frank-tts fills its `DEFAULT_VOICE` since the
  2026-10-18 voice-pack work, so an unset voice synthesizes instead of failing.
 * **Speech** — `/say "dankvoice live smoke test"` produced a 99,884 B / 2.08 s
  WAV and `/say voice narrator2` + `/say "cloned voice check"` a 69,164 B /
  1.44 s WAV (durations from `ffprobe`), each handed to the player; temp
  directories were gone afterwards.
 * **Auto-speak** — verified in a real TUI session: `/say on` armed the footer
  (`🔊 narrator1`), the next finished turn synthesized and played the answer
  (1.20 s WAV), and an unknown voice name answers with the roster instead of
  speaking. An `agent_end` carrying `willContinue` (the harness scheduled an
  auto-retry) is never narrated — only the terminal settle speaks.
 * **Menu** — verified via driver scenarios 2026-10-18 (Refs #23): the menu
  lists auto-speak/voice/device/player/cap/test-phrase; a voice chosen in the
  menu is used by later utterances and survives a fresh load via the settings
  file; a device chosen in the menu appears in the player invocation as
  `--target <sink>`.
 * **Segmented playback** — driver scenarios 2026-10-19: "First stop here.
  Second one goes!!! Really? Third ... done" produced exactly 3 sequential
  requests and 3 plays; "Model 3.5 ships today. Version 1,5 too." produced
  exactly 2 (decimals never split); the markdown fixture's fenced code and
  URL never reached the fixture endpoint; with `DANKVOICE_MAX=60` only the
  leading segment was spoken.
 * **Humanize + thinking (2026-10-19, Refs #27)** — driver scenarios cover the
  rewrite round-trip (fixture chat route), the 404 → mechanical fallback,
  thinking narrated as its own unit before the answer, `DANKVOICE_THINKING=0`
  silencing it, and `narration: true` spoken once as the answer; the endpoint
  status line shows the resolved humanize model from the @tiny role. Live
  smoke against the real services: a markdown `/say` became 3 sequential
  prose segments (mechanical cleanup of that text yields at most 2), and a
  thinking+answer `agent_end` played thinking first. 22 green in
  `tests/dankvoice.bats`.
 * **Thinking-off fix (2026-10-19, Refs #32)** — replaying the exact rewrite
  body against live frank-zealot: without `chat_template_kwargs.
  enable_thinking: false` the reply arrives as 6893 `reasoning_content`
  characters with `content: ""` in 6.9 s (twice the 6 s abort); with it,
  369 clean characters in 0.55 s. Driver fixtures now pin the flag
  (`thinkoff=false` on the recorded chat call), turn reasoning-only replies
  into mechanical speech instead of silence, and time the menu's test
  phrase (~0 ms handler). 26 green in `tests/dankvoice.bats`.
 ## Limits
-* The TUI's own speak-aloud feature still narrates in Kokoro: its voice list is
+* Auto-speak narrates **each turn** — the assistant's prose and thinking while
-  a compile-time enum in the harness bundle, and no setting routes it to
+  the agent is still working — plus the settled final answer, spoken once. A
-  frank-tts. Cloned voices live only on this file-producing/speaking path and
+  turn that lands while audio is still playing is dropped, not queued or
-  on the `tts` tool. See [Handy](/tools/handy.md) for the STT half.
+  interrupting; tool-only turns stay silent; `print`/`json` modes never speak,
-* `agent_end` narrates thinking blocks and the final message only — mid-turn
+  so benches stay quiet. Narration goes through the humanizer, so it lags its
-  tool chatter is never spoken. Thinking covers the last assistant message;
+  turn by a rewrite round trip; `/say humanize off` removes the lag.
-  tool-loop gaps in earlier messages are skipped by design.
+* Arming is read at startup only — see **Arming auto-speak** above. A session
-* Humanized narration is serial: audio starts only after the @tiny rewrite
+  that never speaks is unarmed, not broken; `/say on` before debugging.
-  returns (≤ 6 s per unit, then frank-tts synthesis). Say `/say off`-grade
+* frank-tts deployment, voice packs and the registry are owned by the
-  latency is the price of prose; `DANKVOICE_REWRITE=0` trades it back for
+  `serverAppConfigs` repo (`serverAppConfigs-docs/Dankclaw/Frank TTS.md`).
  instant mechanical speech.
 * frank-tts is LAN-only: no Caddy vhost fronts :7772, so this extension is
  usable on the home network.
 * Deployment, packs and the voice registry are owned by the
  `serverAppConfigs` repo (`serverAppConfigs-docs/Dankclaw/Frank TTS.md`), not
  by this one.
 ## Citations
-* Live probes on the workstation, 2026-10-18: `omp say --voice narrator1 …`,
+* Package repo `dank/dankvoice` (README, `docs/decisions/`) — behaviour and
-  `curl http://192.168.0.143:7772/health`, `/v1/audio/voices`,
+  knob truth. `docs/decisions/2026-10-19-turn-narration.md` records why
-  `/v1/audio/…/speech` (invalid voice), `ffprobe` on the produced WAVs.
+  narration rides `turn_end` and not only `agent_end`.
-* `omp --help` (extension discovery flags, `say`, `plugin`) and
+* Gitea issues #21, #23, #27, #32 (drop-in history) and #34 (this cutover)
-  `@earendil-works/pi-coding-agent` `dist/core/extensions/types.d.ts`
+  on `dank/command-center`.
-  (`ExtensionAPI.on/registerCommand`, `ExtensionMode = "tui" | "rpc" | "json" | "print"`).
+* Live endpoint probes 2026-10-18/19 documented in those issues.
 * The stock speak-aloud implementation — vocalizer pipeline `I6o`, utterance
  segmenter `fHe` and speech enhancer `Qyr` with its prompt `T6o` — in
  `@oh-my-pi/pi-coding-agent`'s `dist/cli.js`, read off the minified bundle
  2026-10-19: dankvoice ports the mechanical and the enhanced halves, so an
  LLM rewrite does happen before frank-tts.
 * Gitea issue #21 on `dank/command-center` (the work item this page ships with).
 * Gitea issue #23 on `dank/command-center` (the options-menu work item).
 * Gitea issue #27 on `dank/command-center` (the enhanced-narration work item).
 * Gitea issue #32 on `dank/command-center` (the latency/silence fix work item).
 ## See Also
 * [Core Documentation](/core/index.md) — the live harness configuration.
 * [Handy](/tools/handy.md) — offline speech-to-text, the input half of voice.
 * `serverAppConfigs-docs/Dankclaw/Frank TTS.md` — the frank-tts service runbook.
@@ -12,7 +12,7 @@ These files define the structural conventions that govern the agent system itsel
 * [AGENTS.md Format Specification](agents-md-format.md) — Canonical structure and conventions for the system-level instruction file that governs agent behavior.
 * [Pi Settings System](settings.md) — pi-era `settings.json` record (archive): providers, models, packages, subagent overrides.
-* [dankvoice](dankvoice.md) — Cloned-voice vocalization extension: `/say` and auto-speak over frank-tts, endpoint read from `agent/models.yml`.
+* [dankvoice](dankvoice.md) — Voice output is the `dank/dankvoice` package (`pi install git:`); this page keeps fleet wiring and the cutover procedure.
 * [OMP Status Line Customization](statusline.md) — How presets, composer shapes, and segment arrays actually interact; the fleet's tuned bar. (moved from /pi/, 2026-10-19)
 * [OMP Subagent Limits & Fan-out Policy](subagent-limits.md) — Live caps: concurrency 2, no nested spawns (the `maxRecursionDepth: 0` trap), per-endpoint in-flight ceilings, isolation policy. (moved from /pi/, 2026-10-19)
@@ -16,6 +16,39 @@ lesson, a few lines. Full incident narratives are recoverable from git
 (`git log --follow omp-docs/log.md`); knowledge that outlives an entry lives
 on its concept page, linked here. Never re-expand an entry in place.
 ## 2026-10-19 — dankvoice auto-speak armed at startup
 Sessions spoke only on explicit `/say`: the settings file carried no `auto`
 key, and arming is session-scoped by design (`/say on` never persists). Set
 `"auto": true` in `~/.omp/cache/dankvoice.json`. Same report, second half:
 auto-speak listened only to `agent_end` — a settle that fires once per prompt
 and is skipped outright when the harness schedules a continuation — so nothing
 was narrated while an agent worked; fixed in dank/dankvoice#3, which narrates
 `turn_end` as well. Law: silence at session start is a config state — read
 `/say status` for `auto-speak on`, then watch `pgrep -a pw-play` for one player
 per segment, before blaming the endpoint. Law: whether the harness delivers an
 event to extensions is settled in minutes by a throwaway probe extension that
 timestamps `turn_end`/`agent_end` — never inferred from audio timing, which the
 humanizer lags by seconds. Details: [dankvoice](core/dankvoice.md).
 ## 2026-10-19 — LazyVim installed as an NVIM_APPNAME profile
 `lazyvim` had never been installed here — shell history shows the command typed
 twice and dropped; `~/.config/nvim` held only an orphaned `matugen.lua` palette
 that nothing loaded. Now: LazyVim starter in `dotfiles/lazyvim/` symlinked to
 `~/.config/lazyvim`, a `lazyvim` zsh function, and the palette applied through
 `RRethy/base16-nvim` on `ColorScheme`. Law: the distro stays out of
 `~/.config/nvim` so bare `nvim` keeps working as a vanilla quick-edit editor.
 Details: [neovim](tools/neovim.md).
 ## 2026-10-19 — dankvoice cut over to the `dank/dankvoice` package (Refs #34)
 Drop-in `agent/extensions/dankvoice.ts` and its 26-test suite retired; the
 package carries the behaviour (41/41 black-box suite) and is installed with
 `pi install git:`. Law: install and prove `/say status` speaks on a box
 *before* pulling the cutover commit — the shared settings file keeps menu
 state across both transports, so the swap is stateless once installed.
 ## 2026-10-19 — dankvoice: silence and timeouts, root-caused (Refs #32)
 The humanizer's raw `fetch` to frank-zealot omitted `chat_template_kwargs.
@@ -19,11 +19,11 @@ Applications that ship with or are configured on CachyOS with Niri on the workst
 | Application | Version | Purpose |
 |-------------|---------|---------|
-| ](ghostty/index.md) | 1.3.1 | Terminal emulator |
+| [Ghostty](ghostty/index.md) | 1.3.1 | Terminal emulator |
 | **Firefox** | 153.0 | Primary browser |
 | **Chromium** | 150.0 | Secondary browser |
 | **Nautilus** | 50.2.2 | File manager |
-| **Neovim** | 0.12.4 | Text editor |
+| [Neovim](neovim.md) | 0.12.6 | Text editor — vanilla `nvim` plus the `lazyvim` profile |
 | **Steam** | 1.0.0.86 | Gaming platform |
 ## System Utilities
@@ -15,6 +15,7 @@ Configuration guides and reference material for installed software. Each tool ha
 * [live-sync](live-sync.md) — Heartbeat daemon committing machine-written paths (memories, managed-skills, live config, dotfiles) in the command-center checkout; systemd user timer, alerts via ntfy.
 * [llama.cpp](llama-cpp/index.md) — Local LLM inference server supporting GGUF models with OpenAI-compatible API.
 * [linux-power-management](linux-power-management.md) — Sleep/wake troubleshooting, NVIDIA GPU power management, and diagnostics for Linux systems.
 * [neovim](neovim.md) — Two editors in one binary: vanilla `nvim` for quick edits and the `lazyvim` NVIM_APPNAME profile, with the base16 wallpaper-palette hook and fresh-box install.
 * [niri](niri/index.md) — Scrollable-tiling Wayland compositor — configuration, keybindings, and architecture for the workstation.
 * [noctalia-shell](noctalia-shell.md) — Native desktop environment for Niri — launcher, control center, settings, lock screen, session menu, hotkey overlay, media controls, and system management.
 * [tmux](tmux.md) — Terminal multiplexer configuration, extended-keys setup, keyboard input best practices, and reload/restart procedures.
@@ -0,0 +1,77 @@
 ---
 type: reference
 title: Neovim and LazyVim
 description: Two nvim entry points on the workstations — vanilla `nvim` and the `lazyvim` NVIM_APPNAME profile — plus the wallpaper palette hook and the fresh-box install procedure.
 tags:
  - editor
  - nvim
  - lazyvim
  - dotfiles
  - blankpad
 verified: 2026-10-19
 timestamp: 2026-10-19
 ---
 # Neovim and LazyVim
 Two editors share one binary. Plain `nvim` is **vanilla** (no user config at
 all — quick edits, agent-spawned edits, `git commit` buffers). The LazyVim
 distribution lives in a **separate `NVIM_APPNAME` profile**, reached with the
 `lazyvim` shell function. Keeping them apart is deliberate: a distro in
 `~/.config/nvim` would slow down and surprise every throwaway `nvim file` call.
 | | vanilla | LazyVim |
 |---|---|---|
 | command | `nvim` | `lazyvim` (= `NVIM_APPNAME=lazyvim nvim`) |
 | config | `~/.config/nvim` (empty) | `~/.config/lazyvim` → tracked at `dotfiles/lazyvim/` |
 | plugins/state | none | `~/.local/share/lazyvim`, `~/.local/state/lazyvim`, `~/.cache/lazyvim` — runtime, **never tracked** |
 | vim (not nvim) | `~/.vimrc` absent → Vim 9.2 stock defaults | — |
 The function is defined in `dotfiles/zz-blankpad/zsh/.zshrc`; `vim` and bare
 `nvim` stay untouched on purpose.
 ## Fresh box
 1. `git clone http://192.168.0.143:3000/dank/command-center.git ~/.omp` — the
   profile arrives as `dotfiles/lazyvim/` (dotfiles tier, see
   [live-sync](live-sync.md)).
 2. `ln -s ~/.omp/dotfiles/lazyvim ~/.config/lazyvim` — files, not the whole
   directory, are the repo convention elsewhere, but this tree is nvim-only and
   the plugin manager rewrites `lazy-lock.json` in place.
 3. `NVIM_APPNAME=lazyvim nvim --headless "+Lazy! sync" +qa` — bootstraps
   lazy.nvim, then every plugin. Needs network (GitHub) once.
 4. `:LazyHealth` inside `lazyvim` to confirm.
 Requirements met on blankpad: nvim ≥ 0.11 with LuaJIT, git, ripgrep, `fd`,
 `fzf`, `lazygit`, a Nerd Font. `tree-sitter` CLI is **not** installed and is
 **not** needed — nvim-treesitter downloads/compiles parsers with `cc` on the
 first real session. Language servers install on demand through mason.
 ## The wallpaper palette (`lua/matugen.lua`)
 LazyVim's colorscheme is overridden by a base16 palette kept in
 `lua/matugen.lua`, applied through `RRethy/base16-nvim` on every `ColorScheme`
 event (`lua/plugins/matugen.lua`) — so `:colorscheme <anything>` still lands on
 the palette, and `v:colors_name` keeps reporting the underlying theme, which
 LazyVim's own plugin tweaks depend on.
 The module also registers a `SIGUSR1` handler that re-requires itself: a real
 `matugen` install (theme generator, not installed here) writing this file from
 a template can hot-retheme a live editor with `pkill -USR1 -x nvim`. Without
 matugen the palette is a static snapshot — the file is the source of truth.
 To recolor by hand: edit the `base00`–`base0F` table, then send `SIGUSR1` (or
 restart). Highlight groups for pickers live below the table; unlisted groups are
 harmless no-ops.
 ## Do not
 * Do not clone `LazyVim/starter` over `~/.config/nvim` — the official recipe,
  but it destroys the vanilla quick-edit path this box relies on.
 * Do not commit `~/.local/share/lazyvim` (≈200 MB of checkouts). `lazy-lock.json`
  inside the profile *is* tracked: it pins plugin revisions.
 ## See Also
 * [applications](applications.md) — the editor's place in the CachyOS/Niri stack.
 * [tmux](tmux.md) — extended-keys setup that the same terminals need.
@@ -1,472 +0,0 @@
 #!/usr/bin/env bats
 # tests/dankvoice.bats — black-box tests for agent/extensions/dankvoice.ts
 #
 # The extension's contract, from outside: it registers a `say` command and an
 # `agent_end` listener; what is observable is (a) the JSON it POSTs to the
 # speech route, (b) the file it hands to the player, and (c) the notifications
 # and select-lists it renders. A fixture HTTP server stands in for frank-tts
 # (it answers the speech route with a fixed WAV, the roster route with a JSON
 # array, and everything else with 404), a stub player stands in for pw-play
 # (it records its full argv and copies the .wav it was given), and a fixture
 # `wpctl` in $WORK/bin stands in for wireplumber's sink enumeration.
 #
 # Driven by env: DV_EXT (extension under test), DV_STUB / DV_STUB_LOG / DV_COPY
 # (player fixture), DV_PWPLAY (stub aliased as pw-play), DV_WPCTL (the sink
 # name the fixture wpctl reports), DV_MODELS (models.yml fixture),
 # DANKVOICE_CONFIG (settings file), DV_PLAYER_BIN (player command override),
 # DV_MODE (the harness mode reported to the extension), DV_REWRITE (fixture
 # behavior for the humanizer route: prose | echo | reasoning | stall, with
 # DV_STALL_MS).
 setup() {
  REPO="$(cd "$BATS_TEST_DIRNAME/.." && pwd)"
  WORK="$(mktemp -d)"
  export DV_EXT="$REPO/agent/extensions/dankvoice.ts"
  export DV_STUB="$WORK/player.sh"
  export DV_STUB_LOG="$WORK/player.log"
  export DV_COPY="$WORK/played.wav"
  export DV_EMPTY_BIN="$WORK/emptybin"
  mkdir -p "$DV_EMPTY_BIN"
  cat > "$DV_STUB" <<'SH'
 #!/usr/bin/env bash
 printf '%s\n' "$*" >> "$DV_STUB_LOG"
 if [ -n "${DV_TIMING_LOG:-}" ]; then printf 'START %s\n' "$(date +%s%3N)" >> "$DV_TIMING_LOG"; fi
 for arg in "$@"; do case "$arg" in *.wav) cp "$arg" "$DV_COPY" ;; esac; done
 sleep "${DV_HOLD:-0.1}"
 if [ -n "${DV_TIMING_LOG:-}" ]; then printf 'END %s\n' "$(date +%s%3N)" >> "$DV_TIMING_LOG"; fi
 SH
  chmod +x "$DV_STUB"
  # the same stub reachable under the canonical player names, plus a fixture
  # wpctl so output-device enumeration is deterministic on any machine
  mkdir -p "$WORK/bin"
  ln -s "$DV_STUB" "$WORK/bin/pw-play"
  export DV_PWPLAY="$WORK/bin/pw-play"
  export DV_WPCTL="alsa_output.usb-KT.0"
  cat > "$WORK/bin/wpctl" <<'WPC'
 #!/usr/bin/env bash
 printf '57\talsa_output.pci-0000_07_00.6.HiFi__Speaker__sink\taudio/sink\t\n116\t%s\taudio/sink\t*\n' "$DV_WPCTL"
 WPC
  chmod +x "$WORK/bin/wpctl"
  # settings live in an isolated file so menu choices never leak between tests
  export DANKVOICE_CONFIG="$WORK/settings.json"
  # models.yml fixture: a chat provider first, the speech provider second
  export DV_MODELS="$WORK/models.yml"
  cat > "$DV_MODELS" <<'YML'
 providers:
  "chat (box)":
    baseUrl: http://10.0.0.1:9999/v1
    models:
      - id: chatmodel
        api: openai-completions
  "speech (box)":
    baseUrl: http://127.0.0.1:1/v1
    auth: none
    models:
      - id: speechmodel
        api: openai-speech
 YML
  # omp config.yml fixture: the @tiny role points at the chat provider above
  export DV_OMPCONFIG="$WORK/ompconfig.yml"
  cat > "$DV_OMPCONFIG" <<'CFY'
 modelRoles:
  tiny: chat (box)/chatmodel:off
 CFY
  cat > "$WORK/driver.ts" <<'TS'
 // Black-box driver: stand up the frank-tts fixture, load the extension against
 // it, invoke one scenario, print what the endpoint received and what got played.
 import { createServer } from "node:http";
 import { existsSync, readFileSync, statSync } from "node:fs";
 import { dirname } from "node:path";
 const scenario = process.argv[2] ?? "speak";
 const AUDIO = Buffer.from([0x52, 0x49, 0x46, 0x46, 8, 0, 0, 0, 0x57, 0x41, 0x56, 0x45, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12]);
 const started = Date.now();
 interface Call {
  url: string | undefined;
  body: string;
  at: number;
 }
 const received: Call[] = [];
 const server = createServer((req, res) => {
  const chunks: Buffer[] = [];
  req.on("data", (chunk: Buffer) => chunks.push(chunk));
  req.on("end", () => {
    const at = Date.now() - started;
    const body = Buffer.concat(chunks).toString("utf8");
    received.push({ url: req.url, body, at });
    if (req.url?.endsWith("/audio/voices")) {
      res.setHeader("content-type", "application/json");
      res.end(JSON.stringify(["narrator1", "narrator2"]));
      return;
    }
    if (req.url?.endsWith("/audio/speech")) {
      res.setHeader("content-type", "audio/wav");
      res.end(AUDIO);
      return;
    }
    if (process.env.DV_REWRITE && req.url?.endsWith("/chat/completions")) {
      const respond = () => {
        res.setHeader("content-type", "application/json");
        const spoken = process.env.DV_REWRITE === "echo"
          ? String(JSON.parse(body).messages?.[1]?.content ?? "")
          : "Spoken, humanized words.";
        const verdict = process.env.DV_REWRITE === "reasoning"
          ? { choices: [{ message: { content: "", reasoning_content: "Long internal deliberation that never reaches the reply field." } }] }
          : { choices: [{ message: { content: spoken } }] };
        res.end(JSON.stringify(verdict));
      };
      if (process.env.DV_REWRITE === "stall") setTimeout(respond, Number(process.env.DV_STALL_MS ?? 200));
      else respond();
      return;
    }
    res.statusCode = 404;
    res.end("{}");
  });
 });
 await new Promise<void>((resolve) => server.listen(0, "127.0.0.1", resolve));
 const port = (server.address() as { port: number }).port;
 if (scenario === "endpoint") {
  process.env.DANKVOICE_MODELS = process.env.DV_MODELS;
 } else {
  process.env.DANKVOICE_URL = `http://127.0.0.1:${port}/v1`;
 }
 process.env.DANKVOICE_OMPCONFIG = process.env.DV_OMPCONFIG;
 if (scenario !== "endpoint") process.env.DANKVOICE_REWRITE_URL = `http://127.0.0.1:${port}/v1`;
 if (scenario === "noplayer") process.env.PATH = process.env.DV_EMPTY_BIN ?? "/nonexistent-bin";
 else process.env.PATH = `${dirname(process.env.DV_STUB ?? ".")}/bin:${process.env.PATH ?? ""}`;
 process.env.DANKVOICE_PLAYER = scenario === "noplayer" ? "" : process.env.DV_PLAYER_BIN ?? process.env.DV_STUB;
 const extension = await import(process.env.DV_EXT as string);
 const commands = new Map<string, { handler: (args: string, ctx: unknown) => Promise<void> }>();
 const events = new Map<string, (event: unknown, ctx: unknown) => Promise<void> | void>();
 extension.default({
  registerCommand: (name: string, options: { handler: (args: string, ctx: unknown) => Promise<void> }) => commands.set(name, options),
  on: (event: string, handler: (event: unknown, ctx: unknown) => Promise<void> | void) => events.set(event, handler),
 });
 const answers = (process.env.DV_SELECT ?? "").split("|").filter((answer) => answer !== "");
 let answerIndex = 0;
 const ctx = {
  mode: process.env.DV_MODE ?? "tui",
  ui: {
    notify: (message: string, level?: string) => console.log(`NOTIFY ${level ?? "info"} ${message}`),
    setStatus: (key: string, text?: string) => console.log(`STATUS ${key} ${text ?? ""}`),
    select: (title: string, options: string[]) => {
      console.log(`SELECT ${title} ${options.join("|")}`);
      const answer = answerIndex < answers.length ? answers[answerIndex] : undefined;
      answerIndex += 1;
      return Promise.resolve(answer ?? options[0]);
    },
  },
 };
 const say = commands.get("say");
 const agentEnd = events.get("agent_end");
 const answer = (text: string) => ({ messages: [{ role: "assistant", content: [{ type: "text", text }] }] });
 const settle = () => new Promise((resolve) => setTimeout(resolve, 800));
 if (!say) {
  console.log("COMMANDS none");
 } else {
  console.log(`COMMANDS ${[...commands.keys()].join(",")} EVENTS ${[...events.keys()].join(",")}`);
  switch (scenario) {
    case "speak":
      await say.handler("hello world", ctx);
      break;
    case "voice":
      await say.handler("voice narrator2", ctx);
      await say.handler("good morning", ctx);
      break;
    case "menu":
      await say.handler("menu", ctx);
      break;
    case "empty":
      await say.handler("", ctx);
      break;
    case "devicemenu":
      await say.handler("menu", ctx);
      await say.handler("hello world", ctx);
      break;
    case "auto":
      await say.handler("on", ctx);
      await agentEnd?.(answer("the answer"), ctx);
      await settle();
      await say.handler("off", ctx);
      await agentEnd?.(answer("the second answer"), ctx);
      break;
    case "continuation":
      await say.handler("on", ctx);
      await agentEnd?.({ ...answer("not yet"), willContinue: true }, ctx);
      await settle();
      await agentEnd?.(answer("the settled answer"), ctx);
      break;
    case "printmode":
      await say.handler("on", ctx);
      await agentEnd?.(answer("quiet"), ctx);
      break;
    case "voices":
      await say.handler("voices", ctx);
      break;
    case "endpoint":
      await say.handler("status", ctx);
      break;
    case "markdown":
      await say.handler("## Title\n\nUse `pw-play` here.\n\n```bash\nnpm i x\n```\n\nsee [docs](http://example.test) and **bold**\n- a\n- b", ctx);
      break;
    case "truncate":
      await say.handler("Sentence one is here. ".repeat(40), ctx);
      break;
    case "sentences":
      await say.handler("First stop here. Second one goes!!! Really? Third ... done", ctx);
      break;
    case "decimals":
      await say.handler("Model 3.5 ships today. Version 1,5 too.", ctx);
      break;
    case "rewrite":
      await say.handler("The deploy failed because a secret was missing.", ctx);
      break;
    case "thinking":
      await say.handler("on", ctx);
      await agentEnd?.({ messages: [{ role: "assistant", content: [{ type: "thinking", thinking: "Considering the wiring." }, { type: "text", text: "The answer is nine." }] }] }, ctx);
      break;
    case "testphrase": {
      const startedAt = Date.now();
      await say.handler("menu", ctx);
      console.log(`HANDLER_MS ${Date.now() - startedAt}`);
      break;
    }
    case "narration":
      await say.handler("on", ctx);
      await agentEnd?.({ messages: [{ role: "assistant", content: [{ type: "thinking", thinking: "Here is the result.", narration: true }] }] }, ctx);
      break;
    case "noplayer":
      await say.handler("speak anyway", ctx);
      break;
  }
  await settle();
 }
 for (const call of received) {
  const parsed: unknown = JSON.parse(call.body === "" ? "{}" : call.body);
  const field = (key: string): string => {
    if (parsed && typeof parsed === "object" && key in parsed) {
      const value = parsed[key];
      if (typeof value === "string") return value;
    }
    return "-";
  };
  const kwargs = parsed && typeof parsed === "object" && "chat_template_kwargs" in parsed
    ? (parsed as { chat_template_kwargs?: { enable_thinking?: unknown } }).chat_template_kwargs
    : undefined;
  const think = kwargs && typeof kwargs === "object" && "enable_thinking" in kwargs ? String(kwargs.enable_thinking) : "absent";
  console.log(`CALL ${call.url} model=${field("model")} format=${field("response_format")} voice=${field("voice")} input=${field("input")}${call.url?.endsWith("/chat/completions") ? ` thinkoff=${think}` : ""}`);
 }
 console.log(`CALLS ${received.filter((call) => call.url?.endsWith("/audio/speech")).length}`);
 const log = process.env.DV_STUB_LOG && existsSync(process.env.DV_STUB_LOG) ? readFileSync(process.env.DV_STUB_LOG, "utf8").trim() : "";
 console.log(`PLAYS ${log === "" ? 0 : log.split("\n").length}`);
 if (log !== "") for (const line of log.split("\n")) console.log(`PLAYER ${line}`);
 if (process.env.DV_COPY && existsSync(process.env.DV_COPY)) console.log(`COPIED ${statSync(process.env.DV_COPY).size}`);
 server.close();
 TS
  export DV_DRIVER="$WORK/driver.ts"
 }
 teardown() {
  rm -rf "$WORK"
 }
 say_run() {
  run env DV_SELECT="${2:-}" bun "$DV_DRIVER" "$1"
 }
@test "the extension registers the say command and an agent_end listener" {
  say_run speak
  [ "$status" -eq 0 ]
  [[ "$output" == *"COMMANDS say EVENTS agent_end"* ]]
 }
@test "speaking posts the text to the speech route" {
  say_run speak
  [ "$status" -eq 0 ]
  [[ "$output" == *"CALL /v1/audio/speech model=frank-tts format=wav voice=- input=hello world"* ]]
 }
@test "one utterance is played once, as exactly the bytes the endpoint sent" {
  say_run speak
  [[ "$output" == *"PLAYS 1"* ]]
  [[ "$output" == *"COPIED 24"* ]]
 }
@test "the voice is named in the request only when the user chose one" {
  say_run speak
  [[ "$output" == *"voice=- input=hello world"* ]]
  say_run voice
  [[ "$output" == *"voice=narrator2 input=good morning"* ]]
  [[ "$output" == *"NOTIFY info dankvoice: voice = narrator2"* ]]
 }
@test "auto-speak narrates the final answer once and stays silent after it is disarmed" {
  say_run auto
  [[ "$output" == *"PLAYS 1"* ]]
  [[ "$output" == *"input=the answer"* ]]
  [[ "$output" != *"the second answer"* ]]
  [[ "$output" == *"STATUS dankvoice 🔊"* ]]
 }
@test "auto-speak stays silent outside the interactive modes" {
  DV_MODE=print say_run printmode
  [[ "$output" == *"PLAYS 0"* ]]
  [[ "$output" != *"input=quiet"* ]]
 }
@test "the voice list comes from the endpoint roster route" {
  say_run voices
  [[ "$output" == *"CALL /v1/audio/voices"* ]]
  [[ "$output" == *"dankvoice voices: narrator1, narrator2"* ]]
 }
@test "the endpoint is taken from the speech row of the models file, never the chat provider" {
  say_run endpoint
  [[ "$output" == *"http://127.0.0.1:1/v1/audio/speech"* ]]
  [[ "$output" == *"humanize chatmodel"* ]]
  [[ "$output" != *"10.0.0.1"* ]]
 }
@test "markdown never reaches the speech engine" {
  say_run markdown
  [[ "$output" == *"input=Title"* ]]
  [[ "$output" == *"input=Use pw-play here."* ]]
  [[ "$output" == *"input=see docs and bold"* ]]
  [[ "$output" != *"npm i x"* ]]
  [[ "$output" != *"example.test"* ]]
 }
@test "the spoken budget keeps only the leading whole segments" {
  DANKVOICE_MAX=60 say_run truncate
  [[ "$output" == *"CALLS 1"* ]]
  [[ "$output" == *"PLAYS 1"* ]]
  [[ "$output" == *"input=Sentence one is here."* ]]
 }
@test "a long answer is spoken as sequential sentence-sized requests" {
  say_run sentences
  [[ "$output" == *"CALLS 3"* ]]
  [[ "$output" == *"PLAYS 3"* ]]
  [[ "$output" == *"input=First stop here."* ]]
  [[ "$output" == *"input=Second one goes!!! Really?"* ]]
  [[ "$output" == *"input=Third ... done"* ]]
 }
@test "decimals and comma-decimals never split a sentence" {
  say_run decimals
  [[ "$output" == *"CALLS 2"* ]]
  [[ "$output" == *"input=Model 3.5 ships today."* ]]
  [[ "$output" == *"input=Version 1,5 too."* ]]
 }
@test "an answer is rewritten into spoken prose before synthesis" {
  DV_REWRITE=prose say_run rewrite
  [[ "$output" == *"CALL /v1/chat/completions"* ]]
  [[ "$output" == *"input=Spoken, humanized words."* ]]
  [[ "$output" == *"CALLS 1"* ]]
 }
@test "a failed rewrite speaks the mechanical text unchanged" {
  say_run speak
  [[ "$output" == *"input=hello world"* ]]
 }
@test "thinking is narrated before the answer as its own segment" {
  DV_REWRITE=echo say_run thinking
  [[ "$output" == *"input=Considering the wiring."* ]]
  [[ "$output" == *"input=The answer is nine."* ]]
  [[ "$output" == *"CALLS 2"* ]]
  local first second
  first=$(grep -n "input=Considering the wiring\." <<<"$output" | head -1 | cut -d: -f1)
  second=$(grep -n "input=The answer is nine\." <<<"$output" | head -1 | cut -d: -f1)
  [ -n "$first" ] && [ -n "$second" ] && [ "$first" -lt "$second" ]
 }
@test "thinking narration can be switched off" {
  DANKVOICE_THINKING=0 DV_REWRITE=echo say_run thinking
  [[ "$output" == *"input=The answer is nine."* ]]
  [[ "$output" != *"input=Considering the wiring."* ]]
  [[ "$output" == *"CALLS 1"* ]]
 }
@test "narration-flagged thinking is spoken once as the answer" {
  DV_REWRITE=echo say_run narration
  [[ "$output" == *"input=Here is the result."* ]]
  [[ "$output" == *"CALLS 1"* ]]
 }
@test "a missing player is reported, not swallowed" {
  say_run noplayer
  [[ "$output" == *"NOTIFY error dankvoice: no audio player found"* ]]
  [[ "$output" == *"PLAYS 0"* ]]
 }
@test "a scheduled continuation is never narrated as the final answer" {
 say_run continuation
 [[ "$output" == *"PLAYS 1"* ]]
 [[ "$output" == *"input=the settled answer"* ]]
 [[ "$output" != *"input=not yet"* ]]
 }
@test "the menu lists every knob and a plain /say opens it" {
  say_run menu
  [[ "$output" == *"SELECT dankvoice — options Auto-speak: off (toggle)|Voice: server default (change)|Output device: system default (change)|Player: $DV_STUB (change)|Spoken cap: 700 chars (change)|Thinking narration: on (toggle)|Humanize answers: on (tiny) (toggle)|Speak a test phrase"* ]]
  [[ "$output" == *"NOTIFY info dankvoice: auto-speak armed (server default @ http://127.0.0.1:"* ]]
  say_run empty
  [[ "$output" == *"SELECT dankvoice — options"* ]]
 }
@test "a voice picked from the menu is spoken by every later request" {
  say_run menu "Voice: server default (change)|narrator2"
  [[ "$output" == *"SELECT dankvoice — voice server default|narrator1|narrator2"* ]]
  [[ "$output" == *"NOTIFY info dankvoice: voice = narrator2"* ]]
  say_run speak
  [[ "$output" == *"voice=narrator2 input=hello world"* ]]
 }
@test "a device chosen from the menu becomes the player's output target" {
  DV_PLAYER_BIN="$DV_PWPLAY" say_run menu "Output device: system default (change)|$DV_WPCTL"
  [[ "$output" == *"SELECT dankvoice — output device system default|alsa_output.pci-0000_07_00.6.HiFi__Speaker__sink|$DV_WPCTL"* ]]
  [[ "$output" == *"NOTIFY info dankvoice: output device = $DV_WPCTL"* ]]
  DV_PLAYER_BIN="$DV_PWPLAY" say_run speak
  [[ "$output" == *"PLAYER --target $DV_WPCTL"* ]]
 }
@test "the rewrite asks the humanizer with thinking explicitly off" {
  DV_REWRITE=prose say_run rewrite
  [[ "$output" == *"input=- thinkoff=false"* ]]
 }
@test "an answer hiding in reasoning_content speaks the mechanical text, not silence" {
  DV_REWRITE=reasoning say_run rewrite
  [[ "$output" == *"input=The deploy failed because a secret was missing."* ]]
  [[ "$output" == *"CALLS 1"* ]]
  [[ "$output" == *"PLAYS 1"* ]]
 }
@test "a rewrite slower than a breath but under the timeout still speaks" {
  DV_REWRITE=stall DV_STALL_MS=300 say_run rewrite
  [[ "$output" == *"input=Spoken, humanized words."* ]]
  [[ "$output" == *"CALLS 1"* ]]
 }
@test "the menu test phrase speaks in the background instead of blocking the menu" {
  DV_REWRITE=stall DV_STALL_MS=1500 say_run testphrase "Speak a test phrase"
  [[ "$output" == *"NOTIFY info dankvoice: speaking the test phrase"* ]]
  local ms
  ms=$(grep -o 'HANDLER_MS [0-9]*' <<<"$output" | cut -d' ' -f2)
  [ -n "$ms" ] && [ "$ms" -lt 1200 ]
 }
Author	SHA1	Message	Date
Frank	fd6a07bb58	docs: auto-speak narrates every turn, not only the final answer (Refs #36 ) The Limits bullet still described the pre-fix behaviour ("thinking and the final message only"), which dank/dankvoice#3 just retired: narration rides `turn_end`, so the assistant's prose and thinking are spoken while the agent works. Records the two rules an operator needs when audio seems missing — arming is read at startup only, and a turn landing during playback is dropped rather than queued — plus where the design rationale lives. kb-lint 0 violations, index-coverage 0 issues.	2026-10-19 13:31:01 -07:00
Frank	1921d76319	Merge remote-tracking branch 'origin/main'	2026-10-19 13:29:52 -07:00
Frank	d302151a8d	docs: land merged #37 content in the live checkout The same bytes are already in origin/main via PR #37; the workspace policy here blocks restore/stash/switch, so the identical working-tree copies are committed rather than discarded, letting the deployment take the merge commit.	2026-10-19 13:29:52 -07:00
dank	5b6f4381b0	Merge pull request 'docs: LazyVim profile page + auto-speak arming rule' (#37 ) from docs/36-voice-and-editor-truth into main	2026-10-19 13:29:28 -07:00
Frank	cae49fcd09	docs: record the LazyVim profile and the auto-speak arming rule (Refs #36 ) Neither setting did what it looked like it did, and the knowledge base had no page for either, so both were invisible until the operator asked. tools/neovim.md: the two entry points (vanilla `nvim`, `lazyvim` as an NVIM_APPNAME profile), the fresh-box install, the base16 wallpaper-palette hook with its SIGUSR1 contract, and the trap that matters — the official recipe clones over ~/.config/nvim and destroys the vanilla quick-edit path. tools/applications.md gets the editor row (Ghostty's row had lost its label) and Neovim's verified version. core/dankvoice.md gains the arming rule: arming is session-scoped, a silent session start is a config state, and the two checks — `/say status` then `pgrep -a pw-play` — prove the chain without blaming the endpoint. kb-lint 0 violations, index-coverage 0 issues.	2026-10-19 13:28:24 -07:00
Frank	ee292ffd10	live: heartbeat sync 2026-10-19T13:20:41-07:00 (Refs #11 )	2026-10-19 13:20:41 -07:00
dank	dd4713fa81	Merge pull request 'chore: retire dankvoice drop-in for the dank/dankvoice package' (#35 ) from feat/34-dankvoice-cutover into main	2026-10-19 12:43:48 -07:00
Frank	a8727ddf0b	chore: retire dankvoice drop-in for the dank/dankvoice package The extension's full behaviour now lives in dank/dankvoice (41/41 black-box suite against the built artifact; this branch's 26 drop-in tests are a strict subset, names ported 1:1). Delete the drop-in and its bats suite; repoint omp-docs/core/dankvoice.md at the package, keeping only fleet wiring (frank-tts + @tiny resolution, the enable_thinking hybrid law, voice/roster contract) and the cutover procedure. kb-lint 0 violations; bats tests/ 45/45. Refs #34	2026-10-19 12:38:28 -07:00
Frank	2faeab665a	live: heartbeat sync 2026-10-19T12:19:36-07:00 (Refs #11 )	2026-10-19 12:19:36 -07:00
Frank	62b3b92e69	live: heartbeat sync 2026-10-19T11:18:41-07:00 (Refs #11 )	2026-10-19 11:18:41 -07:00
dank	ec6a707fe4	Merge pull request 'fix(dankvoice): pin thinking off in rewrite, fix silent and timeout modes' (#33 ) from fix/32-dankvoice-latency into main	2026-10-19 11:12:50 -07:00
Frank	ac5b377750	live: heartbeat sync 2026-10-19T10:17:52-07:00 (Refs #11 )	2026-10-19 10:17:52 -07:00
		`@@ -1 +0,0 @@`
			`{"v":1,"kind":"product_decision","statement":"Documentation links to @~/Projects/serverAppConfig/serverAppConfigs-docs/","source":"explicit_user","evidence":"correct our documentation to just link to @~/Projects/serverAppConfig/serverAppConfigs-docs/","friction":{"corrective":false,"regression":false,"subtle":false},"sessionId":"01a1531d-3e48-70b0-8ee0-6d48a197cae3","ts":1792397374946}`
		`@@ -0,0 +1,2 @@`
							`-- bootstrap lazy.nvim, LazyVim and your plugins`
							`require("config.lazy")`