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.
live: heartbeat sync 2026-10-19T13:20:41-07:00 (Refs #11 )
2026-10-19 13:28:24 -07:00 · 2026-10-19 13:20:41 -07:00 · 2026-10-19 12:43:48 -07:00 · 2026-10-19 12:38:28 -07:00 · 2026-10-19 12:19:36 -07:00 · 2026-10-19 11:18:41 -07:00
51 changed files with 1408 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
- 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.
- 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.
- Open the Gitea issue first (multi-moving-parts law).
+## Frame
+- Read `omp-docs/references/okf-spec.md` + root `omp-docs/index.md` first; inventory with `find omp-docs -name '*.md' | wc -l`.
+- Run `scripts/kb-lint.sh omp-docs` baseline; index-coverage gate is `scripts/kb-coverage.py omp-docs` (each dir's `index.md` must link every sibling file/subdir).
+- Branch off fresh `origin/main` in a NEW worktree (`git -C ~/.omp worktree add ~/.omp/wt/<name> -b docs/<issue>-slug origin/main`) — workspace policy blocks `git checkout -b` in session worktrees.
+- Open the Gitea issue first (multi-moving-parts law); branch name `docs/<issue#>-<slug>`.

-## 2. Scout fan-out (overlap detection)
- One `task` batch, `agent: scout`, one task per doc cluster + one cross-cutting sweep (cap 2 concurrent; rest queue).
- 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.
- 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.
+## Scout fleet (overlap detection)
+- One `task` call, `tasks[]` batch, agent `scout`, read-only; one cluster per task (skills trees, llama trees, pi vs packages, niri, sleep/power, core, gitea, gitea+cross-cutting sweep). Cap 2 concurrent; queue rest.
+- Ledger format per cluster → `local://dedupe/<cluster>.md`: inventory table (file | lines | verdict KEEP|MERGE|DELETE|VENDOR|UPDATE), overlaps, facts-to-keep, inbound links, staleness.
+- **Scouts lie.** Verified misses in the 2026-10-19 campaign: fabricated ledger entries ("peer-reviewed BrowseComp" claim that exists in no file), a DELETE verdict for a generated artifact that is checked in by design AND under test (`tools/niri/keybindings.md`, see `scripts/gen-keybinds.sh` + `tests/gen-keybinds.bats`), and a KEEP for a leftover the scout misread its own changelog about. NEVER apply a scout verdict without re-checking the file, the tests, and the changelog yourself.

-## 3. Verify fleet facts live (never trust doc dates)
- 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.
- 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).
+## Fact verification
+- Fleet facts: read-only probes over `ssh -o BatchMode=yes dankclaw|dankserver` (podman ps/inspect/top, stat, /etc/os-release, curl localhost APIs, `podman exec <c> <tool> --version`). Live state beats docs even when docs claim recent verification — the 2026-10-18 "audit" still drifted (zealot 27B→9B, build 10754→10777, container census 14→32).
+- External claims: web_search/web read yourself (no subagents per Frank's rule). Kill fabrications outright (invented distro `FreeToken`, nonexistent `ornith-llama-cpp-setup` tree, unattributable "44.5% peer-reviewed CUA") — delete/drop with an explicit note, never keep "plausible" numbers.
+- Policy drift (live ≠ tuned docs): flag in the doc + PR body as an operator decision; NEVER silently re-apply policy.

-## 4. Verify external claims via direct web research (no subagents)
- 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.
- 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.
+## Log compaction (log.md)
+- Entry law: dated entry = what changed + durable lesson + concept-page pointer; narratives recoverable via `git log --follow`. Record the law at the top of the log. Tag historical-era entries.

-## 5. Log compaction law
- 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)".
+## Gates + landing
+- Gate every commit: `bash scripts/kb-lint.sh omp-docs && python3 scripts/kb-coverage.py omp-docs && bats tests/`. Pre-commit hook prints `error: command not found: caddy` on Caddyfile-touching commits — warning only, commit still lands.
+- Before opening the PR: `git diff --stat origin/main..HEAD | grep -i 'tmp\|scratch\|\.bak'` — scaffolding merged under a `.tmp-` name in the 2026-10-19 campaign and needed a follow-up PR to promote.
+- PR via API (skill `gitea-api-pr-operations` for token-extraction + merge payload); `xdg-open` the PR the moment it opens; comment the campaign ledger on the issue.
+- After Frank's merge OK: propagate deployment `git -C ~/.omp fetch && git merge --ff-only origin/main`; reap campaign worktree (`git worktree remove --force`) + delete branch local/remote; close issue with landing comment.

-## 6. Gates + landing
- 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.
- 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.
- 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.
+## Line-edit op syntax trap (bit three times)
+- Valid ops: `PUT N.=M:` (body `+text` lines), `CUT N.=M` / `CUT N.=M @reg`, `PUT <N @reg`, `PUT >N:` / `PUT <N:`. There is NO `PUT N+=:` form — it lands in the file as a literal garbage line and shifts the insert to the wrong position. For gap-insert use a lone `PUT >N:` or `PUT <N:` per call; pre-compute line numbers against the file map (ops reference original lines within one call, but a failed op poisons positions).
+- Recovery recipe when a literal op line lands: read exact bounds, `CUT N.=N` (junk), `CUT A.=B @block` (misplaced section), then `PUT <M @block` at the true anchor, re-read tail, add spacing blank if a `---` now abuts a list line.
@@ -0,0 +1,70 @@
+---
+name: docs-point-of-use-destruction
+description: "Documentation exists for point of use, not archival. Use before any dedupe/compact/verify-docs job, and whenever a census or \"only copy\" argument is being used to KEEP documentation: apply the purpose test and destroy obsolete measurements. Supersedes the preservation conclusions of vault-one-fact-one-owner-dedupe §3/§12."
+---
+
+# Documentation exists for point of use
+
+**Supersedes** `vault-one-fact-one-owner-dedupe` §3 ("port before cut") and §12
+("expect docs flat") wherever those conclude a page must be *kept*. Sole custody of a
+useless fact is still useless.
+
+## The test, before you write and again before you keep
+
+- Would the reader, doing a real task tomorrow, **act differently** because of this
+  line? No → delete it.
+- Is it a measured rate (t/s, tok/s, ms, MiB-of-pool, acceptance %, a bench ladder) for
+  a model / runtime / layout that is **not running now and not being compared now**?
+  Destroy it. Not "file it in an Eras row", not "preserve it for history". AI moves
+  faster than the vault: the number is wrong before anyone reads it, and a wrong number
+  in a runbook gets believed.
+- Keep the **law** the measurement taught; drop the measurement. Qualitative causal
+  stories survive; numbers do not.
+- What survives: live config and its exact numbers, procedures, failure signatures,
+  security posture, interface contracts, rollback pointers.
+- **Losing information is an acceptable, usually correct outcome.** Frank said so
+  explicitly on 2026-10-19 after rejecting a PR that had preserved 53 ledgers.
+
+## Traps that lead agents to preserve junk
+
+- **A census cannot decide what to keep.** `port-census.py`-style tools answer "where
+  does this fact live", never "does anyone need it". "14–63 sole-record lines per page"
+  was read as *irreplaceable* when the fact was *obsolete*. Ask usefulness, not custody.
+- **A census that includes the file under test proves the page is held by itself.**
+  Exclude it, print the corpus size, assert absence; treat `0 unheld` on a long page as
+  a tool bug until proven otherwise.
+- **"One fact, one owner" is a placement rule, not a preservation rule.** It says where
+  a surviving fact lives; it never says the fact must survive.
+- **A change diary (`log.md`) is the largest archive in most vaults** (this one: 2,380
+  lines, ~8 % of the vault). Git holds the chronology; a causal law belongs on the page
+  that owns the thing it governs. Retire the diary.
+
+## Execution that worked (2026-10-19, −13.7k lines)
+
+1. Write the kill list as a reviewed artifact, one path per line, grouped by *why it is
+   dead* — that list becomes the PR's argument and the trash manifest.
+2. Destroy whole pages first (`scripts/destroy-vault.py <list>`): move to
+   `.AGENTTRASH/<date>-destruction/`, then delete every reference from survivors, whole
+   line included when the dead link was its only content. Do not compare link targets
+   with `pathlib.Path.stem` — it strips real suffixes (`sd.cpp`).
+3. Then strip numbers from what remains (`scripts/axe-measurements.py`): delete ledger
+   sections (noun-LEDS the heading, nothing instructional after it), blank any table cell
+   reporting a rate, fold Eras older than the current one into a single row pointing at
+   git. Never touch a shape number or a Laws/Wire/Rollback section.
+4. Sweep indices (generator must exclude the trash dir, drop rows whose page cell became
+   empty), re-lint, re-check links.
+5. Rewrite the governing policy in the same PR, or the next agent re-grows the vault:
+   project `AGENTS.md` *Documentation Policy* + the global agent settings.
+
+## Report honestly, per area
+
+docs / scripts / operator-doc separately, measured against the merge-base. The tools are
+a cost that must be named, not hidden inside a headline "net" number — that is what got
+the previous pass rejected.
+
+## Verify the repair tools themselves
+
+One repair pass matched "line ends with a comma" and deleted the trailing comma from 660
+wrapped prose lines. Restore by matching lines that are byte-identical to `HEAD` except
+for trailing punctuation (`restore-punctuation.py`), keep the destructive rule out of the
+tool, and record the incident in its docstring.
@@ -0,0 +1,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
-name prefixes another's (`frank-medium` inside `frank-medium-rocmfpx`) then silently never
-gets a row. Test the wikilink form `[[<stem>]]`.
+Generator bugs to check for: presence tested as a **bare stem substring** — a page whose name
+prefixes another's (`frank-medium` inside `frank-medium-rocmfpx`) then silently never gets a
+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,89 @@ timestamp: 2026-10-19

 # dankvoice

-`agent/extensions/dankvoice.ts` adds cloned-voice speech to the interactive
-harness: `/say` opens the options menu, `/say <text>` speaks through the
-speakers and `/say on` narrates the assistant's thinking and final answer
-after every turn. The words are first rewritten into natural spoken prose by
-the **@tiny** role model (exactly what the built-in vocalizer's
-`speech.enhanced` does), and everything is served by **frank-tts**
-(Dankclaw :7772, the `speech` model role in [agent/models.yml](/core/index.md)).
+Voice output lives in the **`dank/dankvoice` package**:
+`pi install git:http://192.168.0.143:3000/dank/dankvoice.git`. This page owns
+only fleet integration and the cutover. The package README
+(<http://192.168.0.143:3000/dank/dankvoice>) owns the `/say` command
+reference, the settings/env knob list, the segmentation state machine, the
+enhancer port, and mood control — never duplicate those facts here.

-## 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 |
-|---|---|---|
-| 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 |
+## Cutover (Refs #34)

-`dankvoice` is not a patch to that vocalizer (harness code, not ours); it is a
-second transport that happens to speak, so Kokoro stays available for quick
-local speech and the cloned voices carry the real narration.
+The `agent/extensions/dankvoice.ts` drop-in and its 26-test bats suite are
+retired here (the package suite is a strict superset; test names ported 1:1).
+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 |
-|---|---|
-| `/say` \| `/say menu` | options menu (`ctx.ui.select`): auto-speak toggle, voice, output device, player, spoken cap, thinking-narration toggle, humanize toggle, test phrase |
-| `/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 survive the cutover: both transports persist to the same
+gitignored settings file, `~/.omp/cache/dankvoice.json`
+(`DANKVOICE_CONFIG` relocates it).

-Menu choices persist to `~/.omp/cache/dankvoice.json` (runtime state, never
-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.
+## Why not the built-in vocalizer

-Auto-speak is skipped in `print`/`json` mode so benches and pipelines stay
-silent. Each spoken unit — thinking first when narrated, then the answer —
-is first rewritten into spoken prose by the @tiny model; when the enhancer
-(below) declines, the text goes to segmentation as-is, where fenced code and
-tables vanish, links collapse to their label and bullets and table pipes
-disappear. A long answer is never one monolithic synthesis request; see
-[Segmentation](#segmentation) for how utterances are cut and played.
+The harness speak-aloud path (`speech.enabled` / `speech.voice`, `omp say`)
+synthesizes with bundled Kokoro ONNX against a **compile-time voice enum** —
+cloned voices can never reach it, and no setting routes it to frank-tts.
+`dankvoice` is a second transport beside it, not a patch: Kokoro stays for
+quick local speech, the package carries cloned-voice narration. The `tts`
+tool / `xd://tts` device reach frank-tts too, but produce files, not audio
+playback.

-## Segmentation
+## Arming auto-speak

-Utterances are cut by a state machine ported from the harness's own
-speak-aloud vocalizer (the minified `fHe` class in the agent bundle's
-`dist/cli.js`), kept deliberately in lockstep with the stock path:
+Arming is **session-scoped by design**: `/say on` arms the running session and
+is deliberately never persisted. A session that starts silent is a config
+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
-  `!!!!!` and `...` are one boundary, never a pile of cuts.
-* Boundaries after `e.g.`, `etc.`, `Mr.` and friends, or inside inline
-  code, don't count; decimals (`3.5`, `1,5`) survive because a boundary
-  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`.
+Two checks prove the chain, in order: `/say status` must report
+`auto-speak on` with a real endpoint (not `NO ENDPOINT`), and `pgrep -a pw-play`
+during a turn must show one player per spoken segment, `--target` set to the
+saved sink. Thinking narration rides the same arming (`thinking: true`).

 ## Limits

-* The TUI's own speak-aloud feature still narrates in Kokoro: its voice list is
-  a compile-time enum in the harness bundle, and no setting routes it to
-  frank-tts. Cloned voices live only on this file-producing/speaking path and
-  on the `tts` tool. See [Handy](/tools/handy.md) for the STT half.
-* `agent_end` narrates thinking blocks and the final message only — mid-turn
-  tool chatter is never spoken. Thinking covers the last assistant message;
-  tool-loop gaps in earlier messages are skipped by design.
-* Humanized narration is serial: audio starts only after the @tiny rewrite
-  returns (≤ 6 s per unit, then frank-tts synthesis). Say `/say off`-grade
-  latency is the price of prose; `DANKVOICE_REWRITE=0` trades it back for
-  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.
+* Auto-speak narrates thinking and the final message only — mid-turn tool
+  chatter is never spoken; skipped in `print`/`json` modes so benches stay
+  silent.
+* frank-tts deployment, voice packs and the registry are owned by the
+  `serverAppConfigs` repo (`serverAppConfigs-docs/Dankclaw/Frank TTS.md`).

 ## Citations

-* Live probes on the workstation, 2026-10-18: `omp say --voice narrator1 …`,
-  `curl http://192.168.0.143:7772/health`, `/v1/audio/voices`,
-  `/v1/audio/…/speech` (invalid voice), `ffprobe` on the produced WAVs.
-* `omp --help` (extension discovery flags, `say`, `plugin`) and
-  `@earendil-works/pi-coding-agent` `dist/core/extensions/types.d.ts`
-  (`ExtensionAPI.on/registerCommand`, `ExtensionMode = "tui" | "rpc" | "json" | "print"`).
-* 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).
+* Package repo `dank/dankvoice` (README, `docs/decisions/`) — behaviour and
+  knob truth.
+* Gitea issues #21, #23, #27, #32 (drop-in history) and #34 (this cutover)
+  on `dank/command-center`.
+* Live endpoint probes 2026-10-18/19 documented in those issues.

 ## 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,33 @@ 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`. 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.
+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	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}`