docs(links): five See Also links had no text at all

A generated See Also pass left `- ](index.md)` style links on the gitea pages, tools/cachyos.md, and tools/applications.md. Rendered, an empty-text link is a bullet with nothing clickable in it, so it reads as a formatting quirk and never as the broken reference it is. All five now name the page they point at and use the absolute bundle path the spec recommends; the grep that finds them is recorded in the log so the sweep is repeatable. Refs #64
docs(log): one dated section per day, and the sweep's lesson learned
2026-10-21 02:43:15 -07:00 · 2026-10-21 02:40:59 -07:00 · 2026-10-21 02:26:24 -07:00 · 2026-10-21 02:25:56 -07:00 · 2026-10-21 02:25:14 -07:00 · 2026-10-21 02:24:11 -07:00
149 changed files with 5171 additions and 989 deletions
@@ -1,3 +1,13 @@
+# LFS routing for image types. Measured 2026-10-21: this repo tracks ZERO LFS files
+# (`git lfs ls-files` = 0) — the wallpaper library became live theme state and is gitignored
+# (omp-docs/tools/dotfiles-deploy.md), so these four rules match nothing today. They are kept
+# because tracked media is a plausible future and idle filters cost nothing; deleting the file
+# is a pruning call for a session with Frank, not a cleanup an agent runs alone.
+#
+# Do not cite this file as the reason `git-lfs` is installed on a box. The manifest carries its
+# own justification (packages/common.pkgs), and a tool justified by dead config is a tool nobody
+# can defend when the config goes.
+
 *.jpg filter=lfs diff=lfs merge=lfs -text
 *.jpeg filter=lfs diff=lfs merge=lfs -text
 *.png filter=lfs diff=lfs merge=lfs -text
@@ -34,24 +34,36 @@ placeholders='changeme|change[-_]|placeholder|redacted|example|sample|dummy|noke
 # how a gate gets permanently overridden.
 assign_exempt='(_FILE|_PATH|_DIR|_URL|_ENDPOINT|_SOCKET)[[:space:]]*[:=]|[:=][[:space:]]*["'"'"']?(/|\.\./)'
 # Fail closed: a gate that cannot read the staged diff must not report success.
-if ! files=$(git diff --cached --diff-filter=ACM --name-only 2>&1); then
+#
+# `-z`, and the list lives in a file. Two traps decide this: git quotes any path it cannot print
+# as UTF-8 (core.quotePath is on by default), and a quoted name handed back to
+# `git diff -- <path>` matches nothing — the file is skipped, and a skipped file used to be a
+# silent pass. Command substitution cannot hold the list either, because $() deletes NUL bytes,
+# so the names go to a temp file and the loop reads them with a NUL delimiter.
+TMPD=$(mktemp -d) || TMPD=""
+if [ -z "$TMPD" ]; then
+  echo "SECRET GATE: cannot create a temp dir — refusing to commit." >&2
+  [ -n "${ALLOW_SECRETS:-}" ] && exit 0
+  exit 1
+fi
+trap 'rm -rf "$TMPD"' EXIT
+if ! git diff --cached --diff-filter=ACM --name-only -z > "$TMPD/files" 2> "$TMPD/err"; then
  {
    echo "SECRET GATE: cannot read the staged diff — refusing to commit."
-    printf '  %s\n' "$files"
+    sed 's/^/  /' "$TMPD/err"
    echo "Override deliberately: ALLOW_SECRETS=1 git commit ..."
  } >&2
  [ -n "${ALLOW_SECRETS:-}" ] && exit 0
  exit 1
 fi
-# stderr is captured so the failure branch can quote it; on success it must not
-# leak a `warning:` line into the file list and have it mistaken for a path.
-files=$(printf '%s\n' "$files" | grep -vE '^(warning|fatal|error):' || true)
-[ -z "${files//[[:space:]]/}" ] && exit 0
+# git's stderr stays out of the name list on purpose: a `warning:` line mistaken for a path
+# becomes a file that "cannot be read", which is how a gate starts skipping the real ones.
+[ -s "$TMPD/files" ] || exit 0

 report=""
 exempt=""
 count=0
-while IFS= read -r f; do
+while IFS= read -r -d '' f; do
  [ -z "$f" ] && continue
  # Self-exemption, deliberately an exact filename list and not `tests/`: the
  # gate's fixtures must contain credential-shaped strings or there is nothing to
@@ -67,17 +79,48 @@ while IFS= read -r f; do
  # gate refused the redaction of the password it exists to catch.
  added=$(printf '%s\n' "$diff" | grep -E '^\+' | grep -vE '^\+\+\+' | sed 's/^+//' || true)
  [ -z "$added" ] && continue
-  hits=$(printf '%s\n' "$added" | grep -Ei "$shapes" || true)
+  # Shape hits are judged on the MATCHED TOKEN, not on the whole line. Documentation about
+  # credentials quotes vendor placeholders — AWS publishes an all-zeros access-key id that ends
+  # in EXAMPLE for exactly this purpose — and
+  # a gate that blocks prose over an inert example gets worked around until it means nothing:
+  # the live-sync heartbeat failed three ticks on 2026-10-21 because a managed skill page quotes
+  # exactly that id. A line is exempted only when EVERY shape on it is inert, so one live token
+  # sharing the file with a documented fake still blocks.
+  hits=$(printf '%s\n' "$added" | while IFS= read -r line; do
+           live=0
+          while IFS= read -r m; do
+            # The shape regexes carry fixed quantifiers, so the match they return is TRUNCATED:
+            # `AKIA` + exactly 16 characters stops inside the word EXAMPLE and the placeholder
+            # disappears from what is judged. Judge the match plus what follows it instead.
+            ctx=$(printf '%s' "$line" | awk -v m="$m" '{ i = index($0, m); print (i > 0 ? substr($0, i, length(m) + 8) : m) }')
+            printf '%s' "$ctx" | grep -Eiq 'EXAMPLE|X{4,}|Y{4,}|Z{4,}|_{4,}|REDACTED|CHANGEME|PLACEHOLDER' || live=1
+          done < <(printf '%s\n' "$line" | grep -Eio "$shapes" || true)
+           [ "$live" = 1 ] && printf '%s\n' "$line"
+         done)
  if [ "${f##*.}" != "md" ]; then
-    assigns=$(printf '%s\n' "$added" | grep -Ei "$assign" | grep -Ev "$assign_exempt" | grep -Eiv "$placeholders" || true)
+    # The placeholder filter reads the VALUE, never the whole line. A trailing comment that
+    # says `# example` says nothing about the token the same line assigns; scoping the filter
+    # to what follows the separator is what keeps `API_TOKEN=<real>  # placeholder` a block.
+    assigns=$(printf '%s\n' "$added" | grep -Ei "$assign" | grep -Ev "$assign_exempt" \
+      | while IFS= read -r line; do
+          # The judged value is the assigned token alone: it ends at whitespace or `#`, so a
+          # trailing comment cannot vouch for it. Truncating a quoted value early only ever errs
+          # toward blocking, which is the safe direction for a gate that can be overridden.
+          value=${line#*[:=]}
+          value=${value#"${value%%[![:space:]]*}"}
+          value=${value%%[[:space:]]*}
+          value=${value%%#*}
+          printf '%s\n' "$value" | grep -Eiq "$placeholders" && continue
+          printf '%s\n' "$line"
+        done)
    hits=$(printf '%s\n%s\n' "$hits" "$assigns" | sed '/^[[:space:]]*$/d')
  fi
  if [ -n "$hits" ]; then
    n=$(printf '%s\n' "$hits" | wc -l)
    count=$((count + n))
-    report+="  $f"$'\n'"$(printf '%s\n' "$hits" | cut -c1-100 | sed 's/^/    /')"
+    report+="  $f"$'\n'"$(printf '%s\n' "$hits" | cut -c1-100 | sed 's/^/    /')"$'\n'
  fi
-done <<< "$files"
+done < "$TMPD/files"

 # Say so out loud: an exemption that prints nothing is how a carve-out becomes
 # invisible, and invisible is the property a secret wants.
@@ -86,15 +86,27 @@ agent/memories/--home-blank-.omp-wt-*
 # 2026-10-20), so this path in the repo was a duplicate of it, not its source — and
 # note that untracking deletes the copy in every other checkout regardless of
 # `git rm --cached` on the branch. A fresh box starts with an empty library; every
-# filename carries its wallhaven ID, so `curl -L -o <name> https://wallhaven.cc/w/<id>`
-# puts it back. Law: omp-docs/tools/dotfiles-deploy.md
+# filename carries its wallhaven ID; `/w/<id>` answers `text/html`, so resolve the CDN URL at
+# `https://wallhaven.cc/api/v1/w/<id>` and download `data.path` — the recipe, with the reason it
+# is not a plain `curl -L`, is on omp-docs/tools/dotfiles-deploy.md
 dotfiles/noctalia/.local/share/noctalia/wallpapers/

 # --- generated theme output: machine-written, never reviewable, never deployed ---
 # noctalia/matugen rewrite these in place; a tracked copy is a stale snapshot that
-# deploy.sh would push back over a live palette. Patterns match the exclusion list in
-# scripts/deploy.sh. Law: omp-docs/inventory/home-config-census.md, Refs #42
+# deploy.sh would push back over a live palette. These patterns are the ignore half of the
+# exclusion list in `deploy_file` (scripts/deploy.sh): change one, change the other, or a
+# generated file becomes tracked-but-never-deployed — the fiction class #41 removed. The
+# capital-N rule is noctalia's own palette-directory naming, and it was in deploy.sh only.
+# Law: omp-docs/inventory/home-config-census.md, Refs #42, #60
 dotfiles/**/themes/noctalia*
 dotfiles/**/colors/noctalia*
 dotfiles/**/noctalia.*
 dotfiles/**/noctalia-*
+dotfiles/**/Noctalia*
+
+# --- harness natives: unpacked runtime payloads, never configuration ----------
+# 2.4 MB of tree-sitter grammars the harness unpacks into the repo root on first use (measured
+# on blankpad 2026-10-21). Regenerable, unreviewable, not config — every clause of AGENTS.md's
+# runtime-state doctrine applies, and it sat unnamed in the root, one `git add -A` away from
+# being committed as if it were configuration.
+natives/
@@ -94,19 +94,16 @@ knowledge base. Those pages own their facts; this is only the pointer.

 ### Issue tracker

-Work items are Gitea issues on `dank/command-center` (Dankclaw,
-`192.168.0.143:3000`) — no `gh`, no `tea`. See
-[`omp-docs/skills/issue-tracker.md`](omp-docs/skills/issue-tracker.md).
+See [`omp-docs/skills/issue-tracker.md`](omp-docs/skills/issue-tracker.md).

 ### Triage labels

-The five canonical roles, each label string equal to its name. See
-[`omp-docs/skills/triage-labels.md`](omp-docs/skills/triage-labels.md).
+See [`omp-docs/skills/triage-labels.md`](omp-docs/skills/triage-labels.md).

 ### Domain docs

-Single-context, inside the existing knowledge base: `omp-docs/glossary.md` and
-`omp-docs/decisions/`. See [`omp-docs/skills/domain-docs.md`](omp-docs/skills/domain-docs.md).
+ADRs: `omp-docs/decisions/`. `omp-docs/glossary.md` is intentionally not created.
+See [`omp-docs/skills/domain-docs.md`](omp-docs/skills/domain-docs.md).

 ## Secret gate (HARD rule)

@@ -54,13 +54,27 @@ Suggest these tools or languages as possible solutions to problems if they are a

 ### 1. Maintain your projects source of truth.

-The knowledge base at `docs/` is the source of truth for your project. Your training is out of date. Default to the documentation and the code before you assume anything. Maintain a work log of actions taken and their result. Refer to the work log to remember the progress of your tasks.
+Documentation exists for ONE reason: **point of use**. A page earns its bytes only if it helps you perform a task at the moment you perform it — the shape to deploy, the flag that must be passed, the failure mode to recognise, the rollback to run. It is NOT a museum, NOT a lab notebook, and NOT a place to keep track of numbers.
+
+**THE PURPOSE TEST — apply it before you write, and again before you keep:**
+- Would an agent or Frank, doing a real task tomorrow, read this line and act differently because of it? If no: **delete it.**
+- Is this a measured number (t/s, tokens, ms, MiB, %, bench ladder, acceptance rate) for a model, runtime, or hardware configuration that is NOT currently deployed and NOT currently being compared? Then it is **dead weight — destroy it**, do not archive it, do not "preserve it in an Eras row", do not cite it. AI advances make such a figure wrong within weeks, and a wrong number in a runbook is worse than no number: it gets believed.
+- "It is the only copy of that fact" is NOT a reason to keep it. Sole custody of a useless fact is still useless. Losing information is an acceptable — often correct — outcome; do not hesitate to lose it.
+- What survives the test: live configuration and its exact numbers, the procedure that must be followed, the law/causal story that prevents a repeat failure, security posture, and the interface contract a consumer depends on. Qualitative laws outlive the measurement that taught them — keep the law, drop the numbers.
+- Never let a tool's "this is duplicated / this is the only record" census decide what to keep. That is a question of USEFULNESS, which only the operator answers.

 1. Read the relevant `index.md` before you touch a topic.
 2. Follow `omp-docs/references/okf-spec.md` for every doc you create or edit.
 3. Read the target file completely before you edit it.
-4. Always update the documentation when you've completed a task.
-5. Compact the work log when necessary.
+4. Always update the documentation when you've completed a task — and when updating means deleting a page or a paragraph, delete it.
+5. Compact the work log when necessary; a work log holds laws and incidents, never bookkeeping.
+
+#### THE WORK LOG IS ONE FILE.
+The work log is a single page in the knowledge base: `omp-docs/log.md` in this repo, or whichever change-log page the repo's docs index names. Write the entry when the change lands — in the same commit as the change — and read that page to recover where things stand before starting. It follows its own entry law: a dated entry is what changed plus the durable lesson, a few lines.
+
+- NEVER create a second log: not per directory, not per project, feature, branch or run, not `NOTES.md` / `PROGRESS.md` / `STATUS.md` / `worklog/`, not a dated diary. In `dank/command-center` the KB linter reports any `log.md` that is not the bundle root's; the rule and its reasoning are owned by `omp-docs/references/okf-spec.md`.
+- A log holds laws and incidents, never bookkeeping: no per-file inventories, no run-by-run numbers, no transcripts. A number in a log still has to pass the purpose test above.
+- If a knowledge base has no log page, add one at its root and list it in the index. That is the fix — never a log somewhere else.

 #### USE PROGRESSIVE DISCLOSURE.
 Always ensure that all produced documentation is laid out in files following WIKI conventions: start with a top level README.md index file that provides a brief, concise introduction to the item being documented, and then SPLIT OFF individual aspects, features, or arguments into their own interlinked pages so that future agents can read the documentation in a piecewise fashion, only taking in the details they need. Where relevant, crosslink any created documentation with other relevant documentation. This structure may also be nested, if necessary.
@@ -90,6 +104,7 @@ Never assume the user reports correct information. He is human, and humans make
 - Before starting new work, `git pull` from the remote, and start a new branch in a separate worktree using `master` or `main` as the base branch.
 - Commit atomically: after every change that forms a complete functional unit, commit. Do so early and often.
 - When the work is complete, ask the user if they would like to open a pull request.
+- **Report a pull request as link AND title, every time.** A bare `#54` is not a reference: numbers are per-repository, so a number alone does not say which work, in which repo, is being reported. Give the PR's web URL on that forge — on the Dankclaw Gitea that is `https://gitea.franksdank.cloud/<owner>/<repo>/pulls/N` — together with the PR's title. Applies everywhere a PR is mentioned: chat replies, status summaries, issue and commit bodies, alerts. Another forge (GitHub, GitLab, …): the equivalent URL its web UI serves, same pairing.

 ### 5. Test Driven Development

@@ -68,7 +68,7 @@ retry:
      - llamacpp (dankclaw)/frank-dragoon
  maxRetries: 10
 searxng:
-  endpoint: search.franksdank.cloud
+  endpoint: http://192.168.0.143:8081
 exa:
  enabled: false
 memory:
@@ -0,0 +1,113 @@
+---
+name: authentik-rp-sso-login-diagnosis
+description: "Diagnose/repair a dead OAuth2 relying-party login against authentik (Grafana-style): authorize 500, missing email claim, Grafana /emails fallback. Live probe harness + ak-shell gotchas."
+---
+
+# Authentik OAuth2 relying-party (RP) SSO login diagnosis
+
+Use when a vhost authenticates through authentik via the OIDC authorization-code
+flow (Grafana, Seerr OIDC, any "Sign in with <authentik>" button) and the login
+fails — even though the guard-chain e2e (Anubis + outpost) passes green.
+
+## Key insight: the edge test lies
+
+The outpost-guard spec (e.g. `13-sso`) only proves an authenticated session
+reaches the app's *login page*. It never follows the RP OAuth button. So the RP
+login can be 100% dead and the suite still passes. **Always drive the real RP
+round-trip** to get ground truth (harness below).
+
+## Symptom → cause map (all verified live on 2026-10-20, grafana)
+
+| Signature | Root cause | Fix |
+|---|---|---|
+| Browser hits `…/application/o/authorize/?client_id=…` → "Server Error — Powered by authentik" (500), traceback `AttributeError: 'NoneType' object has no attribute 'slug'` in `flows/planner.py` | provider `authorization_flow` is NULL (raw `ak shell` `create()` leaves it unset) | set `authorization_flow = default-provider-authorization-implicit-consent` |
+| Grafana log `logger=oauth.generic_oauth level=error msg="Error getting email address" url=<api_url>/emails … 404/403` | the granted scope mapping returns a **bare string**, not a dict → no `email` claim emitted | fix the ScopeMapping expression to `return {"email": user.email, "email_verified": True}` |
+| authorize 500 on scope-overlap, log `Application requested scopes not configured` for a scope like `user:email` | client requested a scope authentik doesn't define (GitLab-ism) | client must request authentik's real scopes: `openid email profile` |
+| Grafana `?api=1` on API URL → GET `<…>/userinfo/?api=1/emails` → 403 | Grafana v13 appends `/emails` to a `?api=1` URL | use the standard `…/userinfo/` with **no `?api=1`** |
+
+Crucial causal note: **Grafana v13 GETs `<api_url>/emails` for the address ONLY
+when the token carries no `email` claim.** So the `/emails` 404 is a *symptom of
+the missing claim*, not a Grafana misconfig. Do NOT chase it with `USE_ID_TOKEN`
+or attribute paths; fix the claim. `USE_ID_TOKEN=true` does NOT stop the
+`/emails` fetch. Once the claim exists, standard userinfo carries `email` and no
+`USE_ID_TOKEN` is needed.
+
+## Live RP-login probe harness (ground truth)
+
+A `qa-e2e` authentik session storage state exists at
+`tests/e2e/.auth/qa-e2e.json` after an e2e run; the e2e node_modules live in the
+main checkout (`tests/e2e/`). Throwaway probe:
+
+```js
+// node _p.cjs  (run from a checkout with node_modules + .auth)
+const { chromium } = require('playwright');
+(async () => {
+  const b = await chromium.launch({ headless: true });
+  const ctx = await b.newContext({ storageState: '.auth/qa-e2e.json',
+    userAgent: "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/139.0.0.0 Safari/537.36" });
+  const p = await ctx.newPage();
+  await p.goto('https://<vhost>/', { waitUntil: 'domcontentloaded' });
+  for (let i=0;i<30;i++){ const t=await p.locator('body').innerText().catch(()=>''); if(!t.includes('not a bot')) break; await p.waitForTimeout(3000);}
+  await p.goto('https://<vhost>/login/generic_oauth', { waitUntil: 'domcontentloaded' });
+  await p.waitForTimeout(9000);
+  const r = await ctx.request.get('https://<vhost>/api/user');
+  console.log(p.url(), r.status(), (await r.text()).slice(0,200));
+  await b.close();
+})();
+```
+
+Success = final URL on the app host (not `/login`) AND `/api/user` 200 with an
+email. Before the fix it is `/login` + 401. Move the throwaway to
+`~/.AGENTTRASH/…` after (never `rm`).
+
+## ak-shell census: operational traps (authentik 2026.8)
+
+- **Run it via `ssh dankclaw bash -s <<'EOF' … EOF`, NEVER direct
+  `ssh host '… "{{…}}"'`.** Direct ssh eats inner quotes locally; `podman inspect
+  --format '{{…}}'` and multi-line `ak shell -c "…"` only survive inside a quoted
+  heredoc. Authentik runs **rootless** (`podman exec authentik-server …`, no sudo).
+- `OAuth2Provider` has **no `properties` attribute** in 2026.8; scopes are derived
+  from `p.property_mappings`. Accessing `.properties` raises and silently aborts
+  the whole `-c` payload.
+- `ScopeMapping` is **not importable** from `authentik.core.models`. To read
+  scopes: iterate `p.property_mappings.all()`, then `m.scopemapping.scope_name`
+  (reverse one-to-one; the base `PropertyMapping` row has no `scope_name`).
+- Introspect before guessing: `[f.name for f in Model._meta.get_fields()]`. Don't
+  trial-and-error attribute names — that wastes turns.
+- Claims-into-id_token field is `include_claims_in_id_token`.
+- Provider census that works:
+```
+from authentik.providers.oauth2.models import OAuth2Provider
+for p in OAuth2Provider.objects.all():
+    af=p.authorization_flow
+    print(p.name, af.slug if af else None)
+# email mapping shape (the real bug):
+p=OAuth2Provider.objects.filter(name='grafana').first()
+for m in p.property_mappings.all():
+    print(m.name, getattr(getattr(m,'scopemapping',None),'scope_name',None), repr(getattr(m,'expression','')))
+```
+
+## Repair = idempotent script (DB state, not deployable)
+
+Authentik config lives in its DB, not in any repo file; a blueprint re-import or
+an `ak shell` re-creation reverts provider fields silently. Ship an idempotent
+`scripts/authentik-<svc>-sso-fix.sh` that `ssh HOST 'podman exec -i
+authentik-server ak shell' <<'PYEOF' … PYEOF` and re-applies each fact guarded by
+"already set?" checks. Match the style of
+`scripts/authentik-set-login-session-duration.sh`; add a header note "DB state —
+re-run after a rebuild". Reference it from the service page. Grafana's half
+(env) lives in `grafana.container` and deploys normally.
+
+## Repo test-seam gotchas this triggers
+
+- **literal-secret seam** (`observability_quadlet.bats`, "no literal secret")
+  globs keys `*_SECRET|*_PASSWORD|*_TOKEN|*_API_KEY` and demands a `${VAR}`
+  value. A boolean env ending in `_TOKEN` (`…_USE_ID_TOKEN=true`) is a **false
+  positive**. Prefer not to set such a key (drop `USE_ID_TOKEN`); otherwise the
+  seam must be refined (ask the owner before editing a pre-existing test).
+- Quadlet `Environment=` **word-splits on spaces** (systemd semantics) — a spaced
+  list must be quoted: `Environment="KEY=a b c"`, else it truncates to `a`. The
+  repo already uses this (`open-webui.container` OAUTH_SCOPES).
+- **OKF conformance gate** rejects a page frontmatter `timestamp` in the future.
+  The fleet host clock reads UTC (often a day ahead of local "today") — set the
+  timestamp to the repo's today, not the host's UTC date.
@@ -0,0 +1,34 @@
+---
+name: authentik-session-ttl-query
+description: "Query or change authentik login-session TTL on Dankclaw via ak shell — the string-typed UserLoginStage.session_duration trap, the apply logic, and why SESSION_SAVE_EVERY_REQUEST is unavailable."
+---
+
+Change or audit how long an authentik login session lives (Dankclaw `authentik-server`, build 2026.x). The real knob is a DB stage row, not env — and the field format will bite you.
+
+## Where the TTL actually lives
+- Run program through raw stdin: `ssh dankclaw 'podman exec -i authentik-server ak shell' <<'EOF' ... EOF 2>&1 | sed -n '/objects imported/,$p'`.
+- Get models by label, NOT import paths (`from authentik.core.models.setting import ...` fails; `authentik.core.models` is not a package; GlobalSettings is NOT a model in 2026.x):
+  `from django.apps import apps; ULS = apps.get_model("authentik_stages_user_login", "UserLoginStage")`
+- The password sign-in path is flow `default-authentication-flow` → stage `default-authentication-login` (FlowStageBinding FK is `target`, not `flow`). Other stages `default-source-authentication-login` / `default-source-enrollment-login` govern external-IdP/enrollment logins only.
+
+## THE FORMAT TRAP (will break login if wrong)
+`UserLoginStage.session_duration` is **string-typed** in authentik's own idiom: `"days=7"` / `"seconds=2"`.
+- Assigning a `datetime.timedelta` stores Python's `str(timedelta)` = `'7 days, 0:00:00'`, which authentik's parser `authentik.lib.utils.time.timedelta_from_string` **REJECTS** (`ValueError: not enough values to unpack`). Left like that, login crashes computing the expiry.
+- Correct write: `s.session_duration = "days=7"; s.save(update_fields=["session_duration"])`
+- Verify it parses: `from authentik.lib.utils.time import timedelta_from_string as P; P(s2.session_duration)` → `7 days, 0:00:00`. A single `key=value` token only; `"days=7 seconds=0"` also errors.
+
+## How it applies (stage.py:77-87, verified)
+`delta = timedelta_from_string(session_duration)`; `if remember: delta += remember_me_offset`; then `set_expiry(0) if delta==0 else set_expiry(delta)`. So any positive duration applies to EVERY login (remember-me only adds on top), and `set_expiry(<positive>)` overrides `SESSION_EXPIRE_AT_BROWSER_CLOSE` → persistent cookie. Existing sessions keep their old expiry; new logins only.
+
+## SESSION_SAVE_EVERY_REQUEST (sliding window) is NOT available
+`/authentik/root/settings.py` reads `SESSION_COOKIE_AGE` from `CONFIG.get("sessions.unauthenticated_age","days=1")`, sets `SESSION_EXPIRE_AT_BROWSER_CLOSE=True`, and references **`SESSION_SAVE_EVERY_REQUEST` nowhere** → no `AUTHENTIK_*` env or config.yml key can flip it. Enabling a sliding window means patching the vendor image; instead raise the login-stage duration (absolute, supported).
+
+## Audit the rest of the expiry surface (live values)
+- framework: `settings.SESSION_COOKIE_AGE`, `SESSION_SAVE_EVERY_REQUEST`
+- OAuth2 RPs: `apps.get_model("authentik_providers_oauth2","OAuth2Provider")` → `access_token_validity` / `refresh_token_validity` (this fleet: access 1h [embedded-outpost 24h], refresh 30d)
+- proxy claim cache: `authentik_providers_proxy.ProxySession.expires` (observed ~1–24h; silent re-auth, not a logout)
+- tenant: `authentik_tenants.Tenant.default_token_duration` (hand API tokens, not sessions)
+
+## Notes
+- These stage/provider rows are DB state, NOT repo-managed → a blueprint re-import or fresh rebuild reverts them; drop a setup script/blueprint in the repo if reproducibility matters.
+- Don't probe the guarded vhost for the agent API and don't confuse Anubis' 168h challenge cookie with the authentik login session.
@@ -0,0 +1,28 @@
+---
+name: bash-cwd-drift-multi-worktree
+description: "Diagnose \"files keep reverting / phantom edits\" in multi-worktree sessions: the persistent bash shell's cwd silently reverted to another checkout, so probes and git commands ran against different files."
+---
+
+# Multi-worktree bash cwd drift
+
+## Symptom (all of these at once, in one session)
+- A file "keeps reverting" to an older version between edits (esp. test files).
+- `grep -n` line numbers disagree with the tool/test output (e.g. bats reports `line 637`, grep says the match is at 519).
+- `wc -l`/`md5sum` stable when sampled back-to-back, but state "flaps" across the session.
+- `git status` clean in one call, surprising in the next.
+- Probes against `src/` show code that doesn't exist in the branch you think you're on.
+
+## Root cause
+The persistent bash shell resets to the session's ORIGINAL cwd when a call omits `cwd` (e.g. after a shell respawn at a turn boundary). With several git worktrees of the same repo checked out, consecutive calls silently alternate between two full copies of the tree — half the reads land in the old branch's files. Nothing is rewriting anything; two files are being inspected.
+
+## Decision
+- In multi-worktree work, pass an **explicit `cwd` on EVERY bash call**. Never rely on persistence.
+- Use **absolute paths** for `read`/`edit`/`write` (already required) — file tools don't drift; only bash does.
+
+## Check
+When state seems to flap: `pwd` in the same call as the probe. If two calls to the same relative path report different content, `git worktree list` and census each checkout separately — you have two files, not a gremlin.
+
+## Repair pattern (if corruption got committed via the wrong tree)
+1. `git log --oneline --all -- <file>`; per candidate commit print `wc -l` + counts of a few marker strings to classify clean vs corrupted blobs.
+2. Restore the good blob with `git show <commit>:<path> > <path>` (no checkout — safe under worktree policies).
+3. Re-apply the intended additions as surgical edits; verify with targeted tests before the full suite.
@@ -0,0 +1,57 @@
+---
+name: bats-assertion-trust
+description: "When writing or reviewing bats shell tests, catch vacuously-passing assertions: grep -vq, sed range boundaries, unanchored section slices, and fixtures too small to trigger pipefail/SIGPIPE bugs."
+---
+
+Prove a bats assertion can actually fail before trusting that it passes. These four traps each made a green suite lie in real work.
+
+## 1. `grep -vq` proves nothing
+
+`some_list | grep -vq 'x'` succeeds when ANY line lacks `x` — nearly always true. To assert absence, capture the text and test it:
+
+```bash
+s="$(report_section)"
+[[ "$s" != *libfoo* ]]          # absence
+[[ "$s" == *bun* ]]             # presence
+```
+
+Same trap in reverse: bash `[[ $s == *A*B* ]]` — `*` crosses newlines, so a substring check spanning two lines matches the wrong lines. Slice to one line first, then assert.
+
+## 2. Section slicing helpers must have explicit boundary semantics
+
+A helper used to scope assertions to one report section must define, and comment, both ends. The default you want: **start inclusive** (labels carry the count/names), **terminator exclusive** (a `sed -n "/A/,/B/p"` range includes B and leaks the next section's first line):
+
+```bash
+# Call sites pass a bare anchored regex; both ends documented.
+section() { printf '%s\n' "$output" | awk -v s="$1" -v e="$2" '$0 ~ e {on=0} $0 ~ s {on=1} on'; }
+```
+
+Two bugs this shape hides:
+- Helper prepends `^` while call sites already pass `^name` → pattern `/^^name/` → never matches → empty slice.
+- An **unanchored start address** matches the first line and the range runs to end-of-output, so every absence assertion becomes a vacuous pass. Symptom: tests that "verify X is not in section A" pass while X is printed later in the same output.
+
+After fixing a helper like this, re-run the whole suite: tests that were passing vacuously suddenly fail, and that is the fix working.
+
+## 3. Fixtures too small hide pipefail bugs
+
+`set -euo pipefail` + `sort | head -1`: `head` exits, closes the pipe, `sort` dies of SIGPIPE, the command substitution returns `141`, `set -e` aborts the script. Small fixtures never overflow the 64 KiB pipe buffer, so the suite stays green and the first run against real data fails with no output.
+
+- Take a minimum in one pass: `awk '{ if (m=="" || $1<m) m=$1 } END { print m }' file`
+- `awk 'NR==1{print; exit}'` is **not** a fix — exiting early closes the pipe exactly like `head`.
+- Pin it with a fixture larger than the pipe buffer: `seq 1 20000 | awk '{print "[2026-01-01T10:00:00-0700] [ALPM] installed pkgfiller (1-1)"}' > big.log` (use `seq`, not `yes | head`, or the fixture itself SIGPIPEs).
+
+## 4. `tr` swallows the final newline and downstream tools preserve that
+
+`tr '\n' ' ' < file` emits no trailing newline; `fold`, `sed`, and `cat` faithfully preserve the absence, so the *next* output line gets glued on. Breaks any tool that later slices output by line-start labels.
+
+```bash
+{ tr '\n' ' ' < file; echo; } | fold -s -w 88 | sed 's/^/  /'
+```
+
+Pin with: assert the following section's label does NOT appear inside the preceding section's slice.
+
+## Debugging order when a bats assertion fails but the script output looks right
+
+1. Reproduce the exact command outside bats (`bash -x` against the script under test) — if it works there, the bug is in the *test helper*, not the script.
+2. Dump the constructed argument: `printf '%s' "$sed_script" | od -An -c` inside the helper. That is how `/^^ repo /` (double anchor) got found.
+3. Keep stubs faithful to the real interface: if the stub answers `-Sqq` but the script calls `-Sl`, the test measures nothing. Make the stub exit `64` on unhandled args so a new real query fails loudly instead of silently returning empty.
@@ -0,0 +1,51 @@
+---
+name: bats-output-glob-red-proof-traps
+description: "Write red bats tests over command output: [[ ]] glob adjacency (quoted * is literal), run-capture vs test stdout in failure dumps, and proving red against pre-fix code before trusting green."
+---
+
+Three traps hit while writing red-then-green bats tests for `remote-job.sh` (Refs #60, `dank/command-center` PR #61). Each one cost a detour because it makes a test look like a bug report when it is an assertion bug.
+
+## 1. In `[[ $s == pat ]]` a quoted `*` is LITERAL — and it eats the wildcard beside it
+
+```bash
+s='  x*                   DONE   rc=0  1 lines'
+[[ "$s" == *"x*"DONE*"rc=0"* ]]   # NOMATCH — and it looks like the tool under test broke
+[[ "$s" == "  x*"*"DONE   rc=0"* ]]   # MATCH — quoted literals, UNQUOTED separators
+```
+
+`*"x*"DONE*` means: anything, then the literal substring `x*DONE`, then anything. Quoting only makes the `*` inside the quotes literal; it does **not** keep the next unquoted token from butting up against it. When the subject has whitespace between the two facts, the pattern must carry an **unquoted** `*` between the quoted literals:
+
+```
+"literal-a"*"literal-b"      # a, then anything, then b
+```
+
+Existing suites in the repo write `*"a"*DONE*rc=0*` — unquoted separators throughout — precisely for this reason. Copy that shape; do not quote for "clarity".
+
+Discriminate before believing the test: run the pattern against BOTH the expected line and the line the buggy code produced (`correct-red` / `NOMATCH` on the second is the pass condition). A pattern that matches the old output was never a regression test.
+
+## 2. A bats failure dump prints the TEST's stdout, not `$output`
+
+```
+not ok 1 status treats a job name as a name, not a pattern
+#   `[[ "$output" == *"x*"DONE* ]]` failed
+# started x*
+```
+
+`started x*` is the stdout the test body itself printed (from a `start` call several lines earlier), **not** what `run` captured. Reading it as the captured value sends you to debug the tool. To see the real capture, echo it:
+
+```bash
+run some-command
+echo "CAP:[${output}]"
+```
+
+in a scratch copy of the test (`/tmp/dbg.bats`, same `setup`/harness) rather than adding diagnostics to the committed test.
+
+## 3. Reproduce outside bats when green refuses to arrive
+
+When a test fails but the same command works by hand, replicate the *exact* bats call shape in `/tmp` with the same env exports (`REMOTE_JOBS_DIR` etc.) and the same `run bash -c '…' _ "$A" "$B" "$C"` argument mapping. If the scratch copy passes and the committed one fails, the difference is the assertion, not the system — go back to trap 1.
+
+## Red-proof rule
+
+Run the new test against the pre-fix code and read *why* it failed. Both traps above produced a failure that looked meaningful while proving nothing (one matched the buggy output; one printed the wrong stream). Keep the test only when the failure reason is the defect you set out to pin.
+
+Related: `bats-assertion-trust` (vacuous assertions), `red-verify-without-stash` (proving red in a shared worktree).
@@ -0,0 +1,32 @@
+---
+name: dankvoice-epithet-pool-audit
+description: "Grow or audit the dankvoice 1000-name epithet pool: gender classes, individual eviction, typo sweep, safe regeneration into framing.ts."
+---
+
+# Dankvoice epithet pool audit
+
+Use when adding names to, reclassifying, or cleaning `src/framing.ts` `EPITHETS_*` in `dank/dankvoice`. The pool is law: exactly 1000 distinct names, curated at build time, never user-editable, "the commons, never the characters".
+
+## Classification rules (proven traps in parentheses)
+- **man**: gendered lexicon (king, lord, priest, uncle...) + tokens ending `man|men|master` — but never `human|inhuman|nonhuman`. Compounds like `quartermaster`, `hangwoman` are single tokens: token-equality checks miss them, use suffix rules.
+- **woman**: lexicon (queen, sister, daughter...) + tokens ending `woman` + an EXPLICIT `-ess` title list (baroness, countess, prioress, canoness, chartress, heiress, priestess...). Never a bare `-ess` suffix match: `endless`, `harmless`, `fortress` all end in "ess".
+- **Possessives follow the head noun**: `lieutenant of the king's hull` is a lieutenant → neutral commons; `count's armsman` is an armsman → man. Do not gender by words inside `'s` phrases.
+- Modern-neutral offices stay commons: hero, governor, wizard. `witch/lass/bride` are female-coded; `warlock` male-coded.
+- Regex trap for absence checks: `he\b` matches inside `the`; token-split before matching.
+
+## Individual eviction law
+Evict: named fictional/historical individuals (duke caladan, uncle toby, pyrrhus, usul, endymion, skynet, moya-born, medusa), named protagonist ships (rocinante), and real authors in universe clothing (strugatsky, niven).
+Keep: species, orders, houses, orgs/companies (sardaukar, jedi, cyberdyne), places (kessel; `falconer of the caladan eyries` is fine — the person problem was only `duke caladan`), institutions (zekma, karass).
+Replace each eviction with the generic office beside it, class-stable, and unique against the pool.
+
+## Invariants tests pin (breaking any of these goes red)
+- 1000 names, all distinct.
+- Sentinel literals must survive: `hangman of the holiday` (man), `high priestess of the ear moon` (woman), `comrade operator` (other).
+- Pool firsts feed pool[0] probe tests — union order is MAN-first / WOMAN-first / OTHER; keep source order within classes so firsts stay: `chairman of the presidium of processors` / `hangwoman of the public convenience` / `comrade operator`.
+- Class counts (86/15/899 as of 2026-10) may churn but must be reported; tests never pin them.
+
+## Regeneration
+Pool lives as three generated arrays between markers `/** Male-coded` and `/** The unions` in `src/framing.ts`. Splice new arrays between those markers (python splice of a generated `const NAME = [ "x", ... ] as const;` block is fine; do not hand-edit 1000 lines). Then `bun run build` (dist pin test byte-compares), `bun run typecheck`, and the full `bats tests/` — the class sweeps are exhaustive `Math.random`-cycled walks (each ~200 s; suite ~17 min; never two bats processes at once).
+
+## Fleet cutover after merge
+main checkout ff-only → `omp plugin upgrade omp-dankvoice` → `cmp` `~/.omp/plugins/node_modules/omp-dankvoice/dist/index.js` against merged `dist/index.js`.
@@ -0,0 +1,49 @@
+---
+name: docker-pin-latest-census
+description: "Prove a Docker Hub / lscr.io image pin is the latest version before bumping it: registry-API tag census plus digest-equals-latest verification, no docker CLI needed."
+---
+
+# Is my pinned image actually the latest?
+
+Use when bumping a pinned container image tag (e.g. `lscr.io/linuxserver/*` quadlet `Image=` lines) and "latest" must be PROVEN, not assumed. Works from any box with curl — no podman/docker daemon required. `lscr.io` fronts Docker Hub; its tags are NOT on quay.io (querying quay returns nothing and reads like "no newer tags exist" — false).
+
+## 1. Full tag census via the registry API
+
+```bash
+tok=$(curl -s "https://auth.docker.io/token?service=registry.docker.io&scope=repository:<owner>/<repo>:pull" \
+      | python3 -c "import json,sys;print(json.load(sys.stdin)['token'])")
+curl -s "https://registry-1.docker.io/v2/<owner>/<repo>/tags/list?n=2000" \
+      -H "Authorization: Bearer $tok" | python3 - <<'PY'
+import json,sys,re
+tags=json.load(sys.stdin).get('tags') or []
+# linuxserver form: <version>-<sha>-ls<N>; group by version, keep newest ls per version
+v={}
+for t in tags:
+    m=re.match(r'^(\d+(?:\.\d+)+)-([0-9a-f]+)-ls(\d+)$',t)
+    if m: v.setdefault(tuple(map(int,m.group(1).split('.'))),[]).append((int(m.group(3)),t))
+for k in sorted(v)[-5:]:
+    print('.'.join(map(str,k)),'-> newest:',max(v[k])[1])   # max on (ls#, tag) tuple
+PY
+```
+
+- Sort versions as **tuples of ints**, never strings (`1.4.10 < 1.4.9` lexicographically).
+- Keep the max `ls` build per version, then the newest version — both can lag independently.
+- Trap already eaten: joining the tuple key to a string mid-loop then re-looking-it-up → `KeyError`. Keep keys as tuples; format only when printing.
+- Some channels have NO `latest` tag in `/tags/list` (or the endpoint truncates) — absence there is not evidence.
+
+## 2. Digest-proof the candidate against `latest`
+
+```bash
+for t in latest <candidate-tag>; do
+  curl -sI "https://registry-1.docker.io/v2/<owner>/<repo>/manifests/$t" \
+    -H "Authorization: Bearer $tok" \
+    -H "Accept: application/vnd.oci.image.index.v1+json,application/vnd.docker.distribution.manifest.list.v2+json,application/vnd.docker.distribution.manifest.v2+json" \
+    | grep -i '^docker-content-digest'
+done
+```
+
+Equal digests ⇒ the pinned tag IS what `latest` serves right now — the strongest "ensure latest" evidence, and recordable in the endpoint page's pin note (the dank-fleet law: *pinned; verified == the registry's `latest` manifest digest at pin time*). A multi-arch index digest matches only if both requests send the same Accept set — send all three types above.
+
+## 3. Bump through git, not by hand
+
+Edit the quadlet/unit `Image=` line + the vault page's pin row (one owner each), run the repo suite, PR, deploy `--service <svc>` only. Rollback stays "revert one line".
@@ -0,0 +1,88 @@
+---
+name: dotfiles-adoption-audit
+description: "Use when deciding which userspace configs on a Dank box belong in the command-center dotfiles tier — separates tracked intent from generated expansion, app state, secrets, and config owned by another repo. Not for deploying one known file."
+---
+
+# Dotfiles adoption audit
+
+Decides, with evidence, which files under `~/.config` (and top-level dotfiles) belong in
+`dank/command-center`'s `dotfiles/` tier. The repo law being applied: **config in, state
+out**, and **one fact, one owner**.
+
+## The four gates (all four must pass)
+
+1. **Installed?** `command -v <prog>` — config for software absent from the box is a prune
+   candidate, never an adoption target. This eliminates most of the clutter.
+2. **Authored, or the expansion of something else?** Generated files must stay out even
+   though they look like config.
+3. **Does another repo or installer already write it?** If a script or package owns the
+   file, tracking it here creates a second owner that loses every argument.
+4. **Could a secret ever live in it?** If yes: template + quarantine, or leave it out.
+
+## Gate 2 is the one people get wrong — prove generation from mtime
+
+A generator walking the app list writes dozens of files in the same sub-second window.
+Compare timestamps across unrelated programs:
+
+```bash
+cd ~/.config && stat -c '%y  %n' */themes/noctalia* */noctalia.* */colors/noctalia* 2>/dev/null | sort
+```
+
+Identical seconds + microsecond progression across ten different programs = generated.
+Re-check one file days later: a new mtime with no human edit proves regeneration, so the
+tracked file must be the *source* (palette/config the generator reads), never its output.
+The correct pattern is a tracked config that *imports* the generated path.
+
+## Classify the whole tree per file, not per directory
+
+The tracked unit is the **file symlink**, so a directory can be "real" while containing only
+tracked symlinks. Never classify by directory:
+
+```bash
+cd ~/.config && for d in */; do d=${d%/}; tr=0; rl=0; rlfiles=""
+  while IFS= read -r f; do
+    case "$(readlink -f "$f" 2>/dev/null)" in
+      */.omp/dotfiles/*) tr=$((tr+1));;
+      *) rl=$((rl+1)); rlfiles="$rlfiles ${f#./}";;
+    esac
+  done < <(find "$d" -maxdepth 2 \( -type f -o -type l \) 2>/dev/null \
+           | grep -vE 'Cache|cache|Cookies|storage|sessions|Crashpad|Default|thumbnails|extensions')
+  [ $((tr+rl)) -eq 0 ] && continue
+  printf '%-22s tracked=%-3s box-only=%-3s %s\n' "$d" "$tr" "$rl" "$(echo $rlfiles | cut -c1-90)"
+done
+```
+
+Then read the headers of suspicious files — installers often confess ("Installed by
+`infra/setup-dev.sh` into `~/.config/containers/systemd/`") and unit files name another
+project's `WorkingDirectory`/`ExecStart`, which means that project owns them.
+
+## Ownership before adoption
+
+```bash
+git -C ~/.omp ls-files dotfiles                  # packages deploy.sh sees
+grep -rl "<unit-or-file-name>" ~/Projects/<proj> # does a project repo own it?
+systemctl --user is-active <unit>                # dead config is not load-bearing
+```
+
+## Secret-gap check (do this before adopting anything env-shaped)
+
+The ignore list may cover only `.env`, so `frank-job-hunt.env` / `postgres.env` fall
+through, and a token-shape secret gate (`sk-`, `ghp_`, PEM, JWT) does not match a
+low-entropy `POSTGRES_PASSWORD=…`. Test both explicitly:
+
+```bash
+cd ~/.omp && git check-ignore -v --no-index 'dotfiles/x/postgres.env' || echo "NOT IGNORED"
+sed -n 's/^patterns=//p' .githooks/pre-commit
+```
+
+Fix = add `*.env` to the quarantine block **and** a password-assignment pattern to the gate,
+with a red test that stages a fake `POSTGRES_PASSWORD=` file.
+
+## Land it
+
+Packages are home-relative trees under `dotfiles/<pkg>/`; per-host overrides go in
+`zz-$(hostname)` (stowed last). `dconf` is loaded via `dconf load /`, `systemd-user` gets
+`daemon-reload` + conditional `enable --now`. Sequence: `scripts/deploy.sh --check` (dry run,
+reports divergents) → adopt → `deploy.sh` → confirm live paths are symlinks into the repo →
+`bats tests/` (includes the real-bundle `kb-lint`/coverage gate) → branch off `origin/main`,
+PR to `main`, never merge without Frank's OK.
@@ -0,0 +1,76 @@
+---
+name: dotfiles-deployment-truth-audit
+description: "Answer \"is my X config actually tracked and deployed?\" per package: classify every file by readlink, expose tracked-then-ignored debt, and re-derive census numbers from the command printed on the page."
+---
+
+Answer to "does this repo still track my <pkg> settings?" must be a measurement, never a remembered count. The tracked unit is the **file**, not the directory: a live directory can be a real directory and still be fully tracked, because every file inside it is a symlink into the repo.
+
+Run in the deployment checkout (the checkout IS the deployment).
+
+## 1. Tracked set, per package, both tiers
+
+```bash
+cd ~/.omp                      # or the repo that owns dotfiles/
+git ls-files dotfiles/<pkg>    # base tier
+git ls-files dotfiles/zz-$(hostname) | grep <pkg>   # host override tier — counted separately
+```
+
+The `zz-*` tier overrides base files by the same relative path, so a per-package count
+that ignores it under-reports what a machine actually runs.
+
+## 2. Live wiring — classify every tracked file (never by directory)
+
+```bash
+for f in $(git ls-files dotfiles/<pkg>); do
+  rel=${f#dotfiles/<pkg>/}; live="$HOME/$rel"
+  if [ -L "$live" ]; then printf 'link %-50s -> %s\n' "$rel" "$(readlink "$live")"
+  elif [ -e "$live" ]; then printf 'REAL %-50s (NOT a link)\n' "$rel"
+  else printf 'absent %s\n' "$rel"; fi
+done
+```
+
+- `REAL` = the repo copy is a fiction: live state diverged, deployment never reached it.
+- `absent` = tracked relic, nothing consumes it (candidate for `git rm --cached`).
+- Spaces in filenames break the `for` loop (`palettes/Gruber Red.json` splits into two
+  rows). Use `git ls-files -z | tr '\0' '\n'` + `while read -r` when names can hold spaces.
+- Reverse direction finds untracked-but-load-bearing files:
+  `find ~/.config/<pkg> -maxdepth 2 \( -type f -o -type l \) | while read -r p; do case "$(realpath "$p")" in $PWD/dotfiles/*) ;; *) echo "not from repo: $p";; esac; done`
+
+## 3. Live state that must stay untracked
+
+Generated palette output and app state are expansion, not authorship. Distinguish by
+mtime cluster, not by name: `find ~/.local/state/<app> -type f -printf '%TY-%Tm-%Td %p\n'` —
+a same-second mass write is a generator; single later re-stamps are re-runs. Pointers a
+switcher script writes (e.g. `cfg/display.kdl -> desk-1-home.kdl`) are machine state too.
+
+Then check the hazard this creates: grep the entrypoint for includes of those generated
+files. A **non-optional** include of a correctly-untracked generated file bricks a fresh
+box (`include "noctalia.kdl"` with no `optional=true` = niri cannot start until the theme
+pipeline has run once). Report it as a fresh-box failure, not a style note.
+
+## 4. Tracked-then-ignored debt (invisible to every normal check)
+
+```bash
+git ls-files dotfiles | grep AGENTTRASH         # trash committed inside the tree
+git check-ignore --no-index -v <that path>      # does an ignore rule match it?
+```
+
+`.gitignore` patterns without an interior slash (`.AGENTTRASH/`) match at **any depth**, so
+the rule was fine all along — the file simply entered history *before* the rule existed, and
+an ignore rule never reaches an already-tracked path. Only repair: `git rm --cached <path>`
+plus moving the working copy to the root `.AGENTTRASH/` (never `rm`). `git check-ignore`
+without `--no-index` prints nothing for tracked paths and reads as "not ignored" — that
+false negative is the trap.
+
+## 5. A census number is only valid with its command
+
+If a page prints a classifier command, every number on it must be reproducible by running
+that command. A row that the command does not reproduce was written from memory — wrong, not
+merely stale. Fix the row, and state the correction in the commit message rather than
+silently editing the number.
+
+## Verification before landing
+
+`bats tests/`, `scripts/kb-lint.sh omp-docs`, `scripts/kb-coverage.py omp-docs`, and
+`scripts/deploy.sh --check` **from the worktree** — `--check` is read-only; never run the
+real deploy from a worktree, it repoints live symlinks into the worktree the heartbeat reaps.
@@ -0,0 +1,80 @@
+---
+name: dotfiles-tier-live-audit
+description: "Audit the command-center dotfiles tier before running deploy.sh: prove per-file tracked/deployed state, refuse generated theme output, catch stale zz overrides, wrong-box dconf keys, and unresolvable systemd ExecStart specifiers."
+---
+
+# Deploy-tier audit (`~/.omp` command center)
+
+Run **before** any real `scripts/deploy.sh` on a box with a live session, and whenever a
+symlink, palette, wallpaper or unit behaves oddly. Facts and laws live in
+`omp-docs/tools/dotfiles-deploy.md` + `omp-docs/inventory/home-config-census.md` — this page
+is only the probe order. Do not restate the laws in new files; the vault owns them.
+
+## 0. Classify per file, never per directory
+
+```bash
+cd ~/.omp
+for f in $(git ls-files dotfiles/<pkg>); do t=$(readlink -f "$HOME/${f#dotfiles/<pkg>/}")
+  printf '%-50s %s\n' "${f#dotfiles/<pkg>/}" "$([ -L "$HOME/${f#dotfiles/<pkg>/}" ] && echo LINK || echo real)"
+done
+```
+A live directory can be real and still fully tracked (every file a symlink). `niri` 8/2,
+`gtk-3.0` 3/0. `zz-$HOST` files count in the `zz` tier's row, not the base package's.
+
+## 1. The plan, and how to read it
+
+```bash
+./scripts/deploy.sh --check    # writes nothing; read the last line, not the RELINK lines
+```
+`--check` prints `RELINK` for **every** path the `zz` tier carries even when the live link
+already points at the override (base is walked first, intermediate owner change reported).
+Only `actions=0` is a real summary; confirm a pending change with `readlink`.
+
+## 2. Generated theme output must never be tracked or deployed
+
+```bash
+git ls-files dotfiles | grep -Ei 'noctalia\.(kdl|toml|json|conf|css)|themes/noctalia'
+```
+Hit = generated palette output (same-millisecond mtime cluster proves it). Untrack
+(`git rm --cached` + `.gitignore` patterns); `deploy.sh` refuses the class (`SKIP … generated
+theme output`). Tracking one means the next sync quarantines the user's live palette and
+restores the committed colours.
+
+## 3. Stale `zz` overrides
+
+For each path present in both base and `zz-$HOST`: `diff` them, then compare each file's
+`git log -1 --date=short`. A `zz` copy older than the base change is a time bomb — sync
+relinks cross-package owners **silently** (`nothing to quarantine`). Delete the `zz` copy in
+the same commit that base absorbed.
+
+## 4. dconf: compare key by key, never with `diff`
+
+`dconf load /` writes only keys present, so a text diff misleads both ways. Parse both sides
+into `[section]/key → value` and report: value conflicts, keys the dump would newly write,
+and any value containing `/home/` (foreign-box state). File-chooser `last-folder-path`,
+`window-state`, `picture-uri*` are state, not preferences — delete them from the dump and
+clear the live keys if they were already deployed here.
+
+## 5. Units: state, then resolvability
+
+```bash
+for u in <units in dotfiles/systemd-user>; do printf '%s %s %s\n' "$u" \
+  "$(systemctl --user is-enabled $u)" "$(systemctl --user is-active $u)"; done
+```
+`is-enabled` exits **1** for `linked` exactly as for `disabled` — read the printed word.
+Never start a unit that is already installed: `swayidle-lock` sits `enabled`/`inactive` and
+`--now` arms a screen lock mid-session. Specifiers are systemd's, not the shell's: probe
+`command -v "${bin//%h/$HOME}"` before believing `ExecStart … absent on this host` — the
+literal `%h/…` string made this repo's own heartbeat look foreign on every box.
+
+## 6. Landing it
+
+`bats tests/` (deploy contract runs `scripts/deploy.sh` in a scratch repo with `DEPLOY_REPO`,
+`DEPLOY_HOST`, stub `HOME`, stub `systemctl` on `PATH`) + `scripts/kb-lint.sh omp-docs` +
+`scripts/kb-coverage.py omp-docs`. Branch off `origin/main`, PR, never merge without Frank's
+OK (`gitea-merge-form-encoded`: form-encoded `do=merge`, `merge_style=no-ff`).
+
+Then deploy from the **deployment root** `~/.omp` only — never from a worktree (live symlinks
+would point into a checkout the heartbeat reaps in 7 days). Acceptance: `actions=N
+quarantined=0`, two consecutive `--check` runs both `actions=0`, no `ENABLE … started` for a
+unit that was already installed.
@@ -0,0 +1,34 @@
+---
+name: e2e-port-squat-triage
+description: "When an e2e seam on a fixed port fails weirdly (404s on routes that exist, stale behavior, health probe passes but app seems ancient), audit for leftover dev/debug servers squatting the port before believing any red or green."
+---
+
+# E2E fixed-port squat triage
+
+## Symptom classes (all seen with a stale server squatting the seam's fixed port)
+- Routes that exist in current `dist`/source return 404 ("Cannot POST /api/...") while unit tests through the same app factory pass.
+- A seam that is *green* but exercises old code: its setup curls `http://host:PORT/health` and gets a response from **whoever owns the port** — a leftover server, not the one it just spawned (the spawned one dies or idles with EADDRINUSE, sometimes still showing in `pgrep`).
+- Behavior matches an older build (missing mounts/guards) despite a fresh build step.
+
+## Triage recipe (before touching code)
+1. Who owns the port:
+   ```bash
+   ss -tlnp 2>/dev/null | grep :PORT
+   ```
+2. List every server process with **start times**:
+   ```bash
+   for p in $(pgrep -f "path/to/server-entry"); do ps -o pid,lstart,cmd -p $p --no-headers; done
+   ```
+3. Compare start times against the build artifact timestamps (`ls -la dist/...`). A server older than the dist you just built is a liar — its in-memory modules predate the code under test.
+4. Kill all leftovers, then re-check: `pgrep -f "server-entry" || echo all-dead`.
+5. Rerun the seam. Only now is red/red and green/green meaningful.
+
+## Why it happens
+- `kill %1` in **non-interactive** bash fails silently (no job control) — use explicit PIDs or `pkill -f <pattern>`.
+- Seam setups that "wait for health" cannot distinguish their own server from a squatter on the same port; a pre-flight "port must be free" assertion is the permanent fix (assert *before* spawn).
+
+## Hardening (if you own the seam)
+Add to setup, before spawning: fail fast if the port is already listening — turns the silent liar into a loud error:
+```bash
+ss -tln "sport = :PORT" | grep -q LISTEN && { echo "port PORT busy — kill leftovers first" >&2; return 1; }
+```
@@ -0,0 +1,39 @@
+---
+name: fleet-host-process-service-wiring
+description: "Add a host-process (non-quadlet) systemd USER service/exporter to serverAppConfigs — every file that must change together, with the signal-relay precedent and the Prometheus gateway/LAN reach rules."
+---
+
+A host-process service (runs `python3`/a binary on the host, NOT a container) is the right shape when the thing must read host-only state (DRM/cgroup sysfs, `shells to nvidia-smi`, signal-cli) that a container cannot reach without passthrough. Precedent to mirror: `scripts/signal-relay.{py,service}` + `install_signal_relay` in `deploy-remote.sh`. A new one landed 2026-10-20: `scripts/gpu-exporter.{py,service}` + `deploy_gpu_exporter`.
+
+## The unit is a USER unit, not a quadlet
+- Hand-written `scripts/<svc>.service`: `[Service]` `ExecStart=/usr/bin/python3 /home/dank/serverAppConfigs/scripts/<svc>.py` (runs straight from the git checkout — a pull updates it, no copy step), `Restart=always`, `[Install] WantedBy=default.target`.
+- It CAN be `systemctl --user enable`-ed (generated quadlet units cannot on this host's podman generator). With `Linger=yes` for `dank`, `[Install]`+`enable` is the whole boot story.
+
+## Every file that MUST change together (a lone change on one side fails silently)
+1. `scripts/<svc>.service` — the unit. Base binds **loopback only**; the LAN address is added by a deploy **drop-in**, so the checked-in unit is never a wildcard.
+2. `scripts/deploy-remote.sh`:
+   - a `deploy_<svc>()` function: `cp` the unit to `~/.config/systemd/user/`, write a `<svc>.service.d/bind.conf` drop-in with the per-host `Environment=..._BINDS=127.0.0.1,<lan>` (map LAN from `$TARGET`: dankclaw=192.168.0.143, dankserver=192.168.0.235 — do NOT hardcode one host if it runs on both), `daemon-reload`, `systemctl --user enable`+`restart`, then a **loop health gate** (`for i in $(seq 1 15); curl -fsS -m5 http://127.0.0.1:<port>/metrics && return; sleep 1`) — a one-shot curl races the bind and once failed a healthy deploy.
+   - a dispatcher branch `<svc>) deploy_<svc> ;;` in the central `case "$service"` (near the observability branch).
+   - an **allowlist entry on EVERY target** it runs on: `dankclaw:<svc>` and/or `dankserver:<svc>` (the allowlist `case` around the top of the file).
+3. `scripts/deploy-plan.py`: add `"<svc>"` to `SERVICE_ORDER`, to `DANKCLAW_SERVICES`/`DANKSERVER_SERVICES` (whichever it runs on), and a `scripts/<svc>.*` path-map in the `parts[0] == "scripts"` block: `if name in {"<svc>.py","<svc>.service"}: _add(services, "<svc>")`. `target_services` then filters per target.
+4. `scripts/test-changed.sh`: a `case` routing `scripts/<svc>.py|scripts/<svc>.service` → its seam + `deployment_scoping.bats` (place before the generic fallbacks). `tests/run.sh` runs all `*.bats` regardless, so the mandatory gate is covered even if this route is missing — but add it for focused runs.
+5. `shared/prometheus/prometheus.yml`: one scrape job per host, using the **reach rules** (below).
+6. Dashboard JSON + the owning page under `serverAppConfigs-docs/Infrastructure/Observability.md` (one owner per fact).
+
+## Prometheus reach rules (the whole cross-file contract)
+Prometheus is a **bridge container**. On this netavark host a bridge container CANNOT dial the host's own LAN IP at a host-bind (only at a *published* port). Therefore:
+- **Same host (Dankclaw):** scrape `host.containers.internal:<port>` (netavark delivers it to the host LAN bind). Scraping `192.168.0.143:<port>` reads DOWN forever even though the endpoint is healthy.
+- **Different host (Dankserver):** plain LAN `192.168.0.235:<port>` reaches it.
+- Never target a `*.franksdank.cloud` vhost — Prometheus cannot solve an Anubis challenge; it is red by construction.
+- The exporter must bind BOTH loopback and the host LAN (like `node-exporter`/`cadvisor`), so `host.containers.internal` and the LAN both land.
+
+## Firewall
+Leave it LAN-open like node-exporter/cadvisor (unauthenticated metrics on the LAN is the repo's exporter posture). Only signal-relay gets an iptables allowlist (loopback+host+`10.89.0.0/16`+DROP) because it is an unauthenticated message-SENDING webhook — do not copy that lock onto a read-only exporter.
+
+## Seam test (tests/<svc>.bats) pattern
+- Black-box the binary with injectable inputs (fixture dirs / stub commands), assert only consumer-visible output; assert **absent means absent** (anchor guards to a sample line `^metric{`, not the always-emitted `# TYPE` header — grepping the bare family name matches the header and false-fails).
+- Cross-file contracts (grep the other files): the unit's `ExecStart`/bind posture, the deploy function + allowlist + dispatch + health gate, the planner selection (run `deploy-plan.py --target T --paths scripts/<svc>.py`, assert output == `<svc>` per target), the prometheus targets, the dashboard `json.load` + that its `targets[].expr` reference the emitted families.
+
+## Gotchas hit while building gpu-exporter
+- Values are float-normalised (`397.40`→`397.4`); a test pinning the literal fails — assert the normalised value. Derive expected byte counts from real units (MiB×1048576, sysfs µW/1e6, temp1_input/1000), don't guess the multiply.
+- `xdg-open <PR-URL>` after opening the PR (repo law) — don't make Frank hunt in Gitea.
@@ -0,0 +1,53 @@
+---
+name: frank-tts-repoint-voice-consumers
+description: "Rotate/rename a frank-tts voice across all consumers (repo DEFAULT_VOICE, Open Notebook speaker profiles over REST, docs) after packs change."
+---
+
+## When
+frank-tts voice packs on `/home/dank/voices` (Dankclaw) changed — packs added, removed, or renamed — and old voice names (e.g. `narrator1/2/3`) no longer resolve. Consumers still sending a dead name now 400 with `unknown voice 'x'; available voices: ...`. This is a maintenance sweep, NOT a bug; confirm with the operator whether the change is intentional before "fixing".
+
+## Facts that make this non-obvious
+- frank-tts (:7772) resolves a voice as a **directory**: `<name>/reference.wav` must exist. `model` field is ignored; the voice comes solely from `voice`/`voice_id`.
+- Live census: `curl -s http://127.0.0.1:7772/v1/audio/voices` (and `/health` returns the same list). This is the truth; the vault docs may be stale.
+- Two consumers carry voice names, in **different stores**:
+  - **repo**: `scripts/frank-tts.env` `DEFAULT_VOICE=` — answers a voice-less request (the omp harness's normal shape). Deploy via git.
+  - **app-side**: Open Notebook speaker profiles (SurrealDB) and OpenWebUI `audio.tts` voice — NOT repo files.
+
+## Step 1 — repo: DEFAULT_VOICE
+Edit `scripts/frank-tts.env` `DEFAULT_VOICE=<new real voice>`. Trunk-based: this worktree can't `git checkout -b` (shared-workspace policy); commit on HEAD and `git push origin HEAD:refs/heads/<branch>`, open PR vs `main`. No bats test pins the DEFAULT_VOICE value (the tts bats use `narrator1` as a self-contained fixture that builds its own `reference.wav` — mechanism test, leave it).
+
+## Step 2 — Open Notebook speaker profiles (REST, host-side, takes effect immediately)
+Voice ID is **free text passed to the TTS request untouched** (no enum/whitelist). The active fleet profile is `dank-duo` (episode profile `dank-daily` → speaker_config). PW is the host `OPEN_NOTEBOOK_PASSWORD`.
+
+```bash
+ssh dankclaw bash -s <<'REMOTE'
+PW=$(grep -m1 '^OPEN_NOTEBOOK_PASSWORD=' /home/dank/Containers/open-notebook/env | cut -d= -f2- | tr -d '"')
+cfg=$(mktemp); chmod 600 "$cfg"; printf 'header = "Authorization: Bearer %s"\n' "$PW" > "$cfg"
+base=http://127.0.0.1:5056/api/speaker-profiles
+# census: name -> speaker/voice_id
+curl -s -K "$cfg" "$base" | jq -c '.[]|{name,speakers:[.speakers[]|{name,voice_id}]}'
+# repoint by NAME (GET-by-name returns full record incl id; PUT whole transformed object to /{id})
+curl -s -K "$cfg" "$base/dank-duo" > /tmp/s.json
+id=$(jq -r .id /tmp/s.json)
+jq '(.speakers[].voice_id) |= ({"OLD1":"NEW1","OLD2":"NEW2"}[.] // .)' /tmp/s.json > /tmp/s2.json
+curl -s -K "$cfg" -X PUT -H 'Content-Type: application/json' -d @/tmp/s2.json "$base/$id" -w ' HTTP %{http_code}\n'
+curl -s -K "$cfg" "$base/dank-duo" | jq -c '[.speakers[]|{name,voice_id}]'   # verify
+rm -f "$cfg" /tmp/s.json /tmp/s2.json
+REMOTE
+```
+- A duo has only 2 speakers — an extra voice is available-but-unassigned, not missing.
+- Upstream's seeded profiles (`business_panel`, `solo_expert`, `tech_experts`) use OpenAI names + `voice_model:null`; they aren't wired to frank-tts — leave them.
+
+## Step 3 — OpenWebUI (check before touching)
+`curl -s http://127.0.0.1:<webui-port>/api/config | jq '.audio.tts'` (port from `podman ps`). If `engine`/`openai.*` are null, the active path is `browser-kokoro` (synthesizes in-browser) and the stored voice is **dormant, not broken** — flag, don't edit a live UI unasked.
+
+## Step 4 — docs (point of use, one owner)
+Update the census + speaker-mapping lines in `serverAppConfigs-docs/Dankclaw/Frank TTS.md` and `Open Notebook.md` to the live packs. Leave DATED measurement logs (e.g. a `2026-10-19` `/health` probe) as history. Do NOT chase `scripts/voice-packs.env` / `Voice Packs.md` narrator builder defs — ask the operator whether those packs are being rebuilt or retired.
+
+## Verify (behavior, not config text)
+Synthesize each new voice and expect 200 + distinct bytes:
+```bash
+curl -s -o /dev/null -w '%{http_code} %{size_download}B\n' -X POST http://127.0.0.1:7772/v1/audio/speech \
+  -H 'Content-Type: application/json' -d '{"model":"voxcpm2","input":"test","voice":"<name>"}'
+```
+`tests/run.sh` EXIT=0 before commit. `DEFAULT_VOICE` only lands after merge + `./scripts/deploy.sh dankclaw --service frank-tts`; run that from the dev `main` checkout (`/home/blank/Projects/serverAppConfig`), NOT the agent worktree (deploy.sh refuses a non-`main` branch and pushes `main` forward — it must run on the dev box, not the target).
@@ -0,0 +1,25 @@
+---
+name: frank-tts-voice-locate
+description: "Answer fleet-voice questions (where voices are stored, add a voice) by jumping straight to the serverAppConfig vault pages and the live 7772 roster probe, instead of re-searching Gitea for a frank-tts repo that does not exist."
+---
+
+# Frank-TTS voice facts: skip the search, go to the owners
+
+Questions like "how do I add a voice?", "where are voices stored?", "why is narratorN missing?" are already answered elsewhere. The frank-tts code does NOT live in a Gitea repo named frank-tts (repo search finds nothing; it is `dank/serverAppConfigs`), and the engine repo is upstream qwentts.cpp pinned at `5916bf7c`.
+
+## Resolution order (one grep, no repo search)
+
+1. **Vault pages (canonical, all of it lives here)** in the local checkout `~/Projects/serverAppConfig`:
+   - `serverAppConfigs-docs/Dankclaw/Voice Packs.md` — pack anatomy, the builder, the 10-second source invariant, "Adding a fourth voice" steps, engine-bump arithmetic.
+   - `serverAppConfigs-docs/Dankclaw/Frank TTS Engine.md` — registry law (memory-only; warm hook), routes, Vulkan device law, troubleshooting table.
+   - `serverAppConfigs-docs/Dankclaw/Frank TTS.md` — the 7772 facade contract.
+   - Code/seam: `dankclaw/voiceservice/`, `scripts/build-voice-pack.sh`, `scripts/voice-packs.env`, `tests/voice_pack_unit.bats`.
+2. **Live roster** (authoritative over any doc census): `curl -s http://192.168.0.143:7772/v1/audio/voices` (bare JSON array; `/health` also echoes `voices`). A missing name = its dir lacks `reference.wav` or the name is not lowercase — check `/home/dank/voices/<name>/` via `ssh dankclaw`.
+
+## Facts that cost turns to re-derive
+
+- Voice storage: `/home/dank/voices/<name>/` on Dankclaw (host state, never git; RO mount at `/voices`). Files: `reference.wav` (24 kHz mono, 18–25 s, existence gate), `reference.spk` (8192 B), `reference.rvq` (5456–6864 B), `manifest.json`.
+- Roster = facade directory scan; engine registry is in-memory, filled by `podman exec frank-tts-engine /app/warm-voices.sh` (boot `ExecStartPost`; re-register replaces, restart costs 6–8 s/voice).
+- Clients (omp-dankvoice, OpenWebUI) store NO voices — they GET `/v1/audio/voices`; only the chosen name persists client-side (`~/.omp/cache/dankvoice.json` `voice`).
+- Crop law: past first 10 s (hard invariant), 20–25 s preferred, floor 19.84 s for `.rvq`; sources pinned by sha256 in `scripts/voice-packs.env`; sample media live on workstations (`/home/blank/audiosample*`) and must be copied to `/home/dank/voice-sources` before a build.
+- Engine `GET /v1/audio/voices` returns `{}` at the pinned commit — always ask the 7772 facade, never 8880, for the list.
@@ -0,0 +1,47 @@
+---
+name: frank-tts-voice-pack-audit
+description: Census live frank-tts voice packs against scripts/voice-packs.env to catch name-drift (renamed/retired packs) and untracked CLI-built packs; use after any voice add/rename when reconciling the builder recipe with what is actually on disk.
+---
+
+# frank-tts voice-pack audit (builder ↔ live census)
+
+Read-only census answering: *does `scripts/voice-packs.env` still describe the packs that actually exist, and is every live pack reproducible from the repo?* Run it after anyone adds or renames a voice. The runtime being healthy (all voices synthesize) does NOT mean the builder is honest — the gap is reproducibility, not serving.
+
+## Why this exists
+Packs are host state under `/home/dank/voices` (never in git). A voice can be:
+- **built by the env** (a `VOICE_PACK_<NAME>_*` block exists), or
+- **built by CLI override** (`build-voice-pack.sh <name> <dir> --source --offset --duration --sha256` with NO env block) — then its only provenance is `/home/dank/voices/<name>/manifest.json`, and `--all` silently skips it.
+
+Renaming a pack directory (e.g. `narrator1` → `wilwheaton`) preserves the crop bytes and its source sha256, so the env recipe stays *correct but keyed under a dead name*. `build-voice-pack.sh --all` then rebuilds the dead names and skips the live ones.
+
+## Procedure (on Dankclaw)
+
+1. **Live set + which builder made each** — the manifest `kind` field tells them apart:
+   - `kind: "voice-pack"` → built by `scripts/build-voice-pack.sh` (env or CLI override).
+   - `kind: "voice-reference-pack"` → the older trial `pipeline.sh`.
+   ```
+   for d in /home/dank/voices/*/; do n=$(basename "$d"); [ -f "$d/reference.wav" ] \
+     && printf '%-16s %8sB  %s\n' "$n" "$(stat -c%s "$d/reference.wav")" "$(stat -c %y "$d/reference.wav" | cut -d. -f1)"; done
+   ```
+2. **Per-voice provenance** — `manifest.json` is the sole record for CLI-built packs. Read `name/voice`, `kind`, `source.path`, `source.sha256`, `crop.offset_seconds`, `crop.duration_seconds`. Use `python3 -c 'import json,...'`, NOT a `jq '{a,b,c}'` object — the brace form gets brace-expanded by the remote zsh and errors.
+3. **Builder tracked list**:
+   ```
+   grep -E '^VOICE_PACKS=|^VOICE_PACK_[A-Z0-9_]+_(SOURCE|OFFSET|DURATION|SHA256)=' /home/dank/serverAppConfigs/scripts/voice-packs.env
+   ```
+   Diff the names in `VOICE_PACKS` against the live dirs. Three findings to report:
+   - env keys that have **no live dir** (renamed/retired),
+   - live dirs with **no env block** (CLI-built, unreproducible from repo),
+   - matching source **sha256** between a dead env key and a live dir = that live pack is the renamed crop (safe to re-key the env, don't recompute).
+4. **Distinguish CLI-built from uncommitted env drift** — check the deployed env matches the repo:
+   ```
+   cd /home/dank/serverAppConfigs && git diff --stat HEAD -- scripts/voice-packs.env   # empty = no drift
+   ```
+   Empty diff + a `kind: "voice-pack"` manifest with no env block ⇒ built via CLI overrides (correct, just untracked), NOT a rogue remote edit.
+
+## Repoint the consumers (separate concern)
+If voices were renamed/retired, the runtime consumers still point at dead names — see the `frank-tts-repoint-voice-consumers` skill. Consumers that name a voice: `scripts/frank-tts.env` `DEFAULT_VOICE`, Open Notebook `dank-duo` speaker profile (`voice_id`, app-side REST), OpenWebUI `audio.tts.voice` (config DB). A voice-less request to frank-tts 400s naming `DEFAULT_VOICE`, so a dead default is a live break, not just cosmetic.
+
+## Gotchas
+- **A published port is reachable at `host.containers.internal` too.** OpenWebUI's docs say use the LAN IP because that name "doesn't resolve on the bridge" — true only for *non-published* ports. frank-tts 7772 IS published, so `host.containers.internal:7772` answers 200 from the open-webui container. Verify before calling a URL the cause; the real break is usually the dead voice name.
+- **Source custody is split**: `audiosample*.mp3/m4b` live on the workstation (`/home/blank`), newer sources on Dankclaw (`/home/dank/voice-sources`). `--all` is only reproducible once each env SOURCE path points at where the file actually is.
+- Do NOT edit `voice-packs.env` to add CLI-built voices without confirming each source path + offset + sha against its manifest, then run `./tests/run.sh` (the pack-list invariant in `voice_pack_unit.bats` walks `VOICE_PACKS`).
@@ -0,0 +1,50 @@
+---
+name: franksign-demo-inspection-stack
+description: "Boot franksign's prod-shaped stack, seed all assignment lifecycle states through the real API, and open a headed inspection tour (platform + storybook) without squatting the e2e port."
+---
+
+Visual-inspection recipe for the franksign repo (Dank boxes). Proven 2026-10-20; use when asked to "show/open the platform" or tour a new slice.
+
+## Boot (do NOT squat :3100 — the e2e seam curls whoever owns that port)
+```bash
+node --env-file=.env apps/api/dist/cli.js        # binds :3000 by default; use named service
+cd apps/web/storybook-static && python3 -m http.server 6007   # gate seam 12 already built it
+curl -s http://127.0.0.1:3000/health              # {"status":"ok","db":"up"}
+```
+
+## Seed lifecycle states through the real API (cookie jar, NOT bearer)
+better-auth sign-up returns a bearer `token`, but the org routes resolve sessions
+from **cookies only** (`Authorization: Bearer …` → get-session null → 401). Use
+`-c /tmp/jar` at sign-up and `-b /tmp/jar` after; state-changing calls need an
+`origin:` header. Keep auth headers out of argv via `curl -K <file>`.
+
+1. `POST /api/auth/sign-up/email` `{"email","password"(>=8 chars),"name"}` → save cookies (`-c`)
+2. `POST /api/orgs` `{"name"}` → `org.id`
+3. `POST /api/orgs/:org/templates` `{"name","baseTemplateId":"sample"}` → `template.id`
+4. `POST /api/orgs/:org/templates/:tpl/assignments` `{"email"}` → `{token, signUrl}` (repeat per demo signer)
+5. signed state: `POST /api/releases/:token` `{"values":{"name":…,"date":…,"agreement":true},"signatureName":…}` — no auth needed (token seam)
+6. voided state: `POST /api/orgs/:org/assignments/:assignmentId/void` (cookie session)
+Remaining pending assignment → three inspectable pages: `/app/sign/:token` renders form / already-signed / cancelled.
+
+## Byte-identity spot check (reconstruction contract, issue #18)
+Fetch `GET /api/releases/:token/pdf` twice with `sleep 1.5` **between** fetches
+and sha256-compare, plus the org door `GET /api/orgs/:org/assignments/:aid/pdf`
+(cookie jar). Same-second-only comparisons are blind to clock leaks
+(pdf-lib's `PDFDocument.load` restamps `/ModDate` unless `updateMetadata:false`).
+To see printed text: inflate the content streams and unescape `\(`, `\)` —
+pdf-lib writes hex-string `Tj` operands.
+
+## Inspection browser (managed Chromium via browser eval)
+- `viewport` must be `{width, height}` — string fails
+- `tab.waitFor(ms)` does NOT exist (ms is parsed as selector) → `await Bun.sleep(900)`
+- open with `headed: true, persist: true`; window lands on the desktop — confirm with `niri msg windows | grep -i chrome`
+
+## Teardown (hard gate hazard)
+A live demo API on :3000 **hangs the full `tests/run.sh` gate for ~10 minutes**
+(observed 2026-10-21: >600s kill with the service up; 14/14 in ~15s without
+it). Always `proc://franksign-demo-api/kill` BEFORE running the gate; verify
+`pgrep -f apps/api/dist/cli.js` is empty so the next `tests/run.sh` e2e seam
+owns :3100 honestly.
+
+## Adjacent Gitea quirk (same fleet)
+Closing an issue/PR: `PATCH {"state":"closed"}` → 201; `POST` → 405. Merging needs form-encoded lowercase `do=merge` (see gitea-merge-form-encoded). Label assignment: `PATCH /issues/N` with `labels:[id]` silently clears labels — use `POST /issues/N/labels` `{"labels":[id]}`.
@@ -0,0 +1,59 @@
+---
+name: git-secret-gate-hook
+description: "Write a fail-closed pre-commit secret-gate hook (staged-content scan) with the grep/ERE traps that kill naive versions, plus its bats fixture test."
+---
+
+# Git secret-gate pre-commit hook
+
+Use when a repo promises a "pre-commit secret gate" but none exists, or when porting the gate to another dank repo. Ships with three traps already paid for.
+
+## Shape
+
+- Track the hook at `hooks/pre-commit` (chmod +x). Git never self-installs hooks — wire per clone:
+  `git config core.hooksPath hooks` — run it in the MAIN checkout once; `core.hooksPath` lives in the
+  **common** git dir config, so every linked worktree inherits it.
+- Do NOT put `hooks` in `package.json` `files` — an installed plugin under node_modules never runs git.
+- Scan **staged** content (`git show ":$f"`), not the working tree: that is what lands in history.
+- Denylist by path (README, docs/, tests/, `.env.example`) — files whose job is naming secrets or holding
+  fixture dummies produce theatre, not safety.
+- Never echo the matched secret; print file + line number only.
+- Red-first test: fixture repo + `cp` the real hook in + `git config core.hooksPath hooks`, then drive
+  REAL `git commit` attempts: credential-shaped file must exit non-zero AND `git log` must show no new
+  commit (block, not warn); clean commit passes; hook must survive committing itself.
+
+## The three traps (each cost a red test)
+
+1. **`--` is a ONE-SHOT end-of-options marker.** `grep -nE -- 'p1' -- 'p2'` treats everything after the
+   first `--` as FILE NAMES: `grep: --: No such file or directory`, rc=2. Multi-pattern = repeat `-e`:
+   `grep -nE -e 'p1' -e 'p2'`.
+2. **`if hits=$(grep ...)` is fail-OPEN on rc>=2** (rc=2 is truthy, hits empty). Capture `rc=$?`
+   explicitly: `rc>=2` must BLOCK with "pattern error, refusing to pass unchecked" — a gate whose regex
+   silently dies is worse than none.
+3. **POSIX ERE (`grep -E`) gotchas:** no `(?:...)` groups (use plain `(...)`); a `[:-]` inside a bracket
+   starts a collating element `[:` and dies with "repetition-operator operand invalid" — put `-` FIRST
+   in every class (`[-A-Za-z0-9/+=_.:+]`). Also `-----BEGIN` literals: prefer printf-safe fixtures in tests.
+
+## Pattern set (shapes, not entropy — say so in the header comment)
+
+```
+-----BEGIN[ A-Z0-9]*(OPENSSH|RSA|DSA|EC|PGP)? ?PRIVATE KEY-----
+AKIA[0-9A-Z]{16}
+gh[pousr]_[A-Za-z0-9]{36,}|github_pat_[A-Za-z0-9_]{50,}
+xox[baprs]-[A-Za-z0-9-]{10,}
+https://hooks\.slack\.com/services/[A-Za-z0-9/]+
+(aws_secret_access_key|secret(_access)?_key|(api|access|auth)[_-]?key|[a-z_]*token|passwd|password|credential)[[:space:]"']?[[:space:]]*[:=][[:space:]]*["']?[-A-Za-z0-9/+=_.:+]{16,}
+(Bearer|token|authorization)[[:space:]]*[:=][[:space:]]*["']?[-A-Za-z0-9._+/]{20,}
+```
+
+## Test fixture hygiene
+
+Fake secrets must be inert (RFC 2606 domains, all-zero ids, `AKIA0000000000000EXAMPLE`) AND must not
+match the hook's own self-scan. Single quotes in ERE patterns: write `'"'"'`.
+
+## Wiring gotcha (dank worktree policy)
+
+Set `core.hooksPath` AFTER the merge that lands `hooks/` into main — with the config set but the path
+missing, git fails every commit in worktrees lacking `hooks/` ("cannot run hooks/pre-commit: No such
+file or directory"). Order: merge -> land -> `git config core.hooksPath hooks` from main checkout.
+
+Reference implementation: `dank/dankvoice` `hooks/pre-commit` (PR #19), pinned by `tests/gate.bats`.
@@ -0,0 +1,42 @@
+---
+name: gitea-credential-store-url-format
+description: "Auth to the Dankclaw Gitea API without the empty-header trap: ~/.config/secrets/gitea is a git-credential-store URL file, so awk '/^password=/' returns empty; resolve the token via git credential fill, and Gitea writes need Authorization: token (reads pass anonymously on a public repo)."
+---
+
+# Gitea auth on Dankclaw: the URL-format credential store
+
+`~/.config/secrets/gitea` is `git config credential.helper = store --file ~/.config/secrets/gitea`, i.e. a **git-credential-store URL file**:
+
+```
+http://dank:<40hex-token>@192.168.0.143:3000
+```
+
+It does NOT contain `username=`/`password=` lines. So:
+
+```bash
+# WRONG — silently returns empty string
+p=$(awk -F= '/^password=/{print substr($0,10)}' ~/.config/secrets/gitea)
+```
+
+An empty `$p` makes every curl send `Authorization: token ` (blank) → Gitea replies `{"message":"token is required"}` on **writes**, while **reads still return 200** (the repo is public-readable, so a green `GET /labels` or `/issues` proves nothing about auth). Symptom: PR-create returns `token is required` even though a `GET` just "worked".
+
+## Resolve the real token via git
+
+```bash
+p=$(printf 'protocol=http\nhost=192.168.0.143:3000\n\n' \
+     | git credential fill 2>/dev/null \
+     | awk -F= '/^password=/{print substr($0,10)}')   # 40-hex token
+```
+
+## Write auth = token scheme, via a 600-perm -K file
+
+```bash
+cfg=$(mktemp); chmod 600 "$cfg"
+printf 'header = "Authorization: token %s"\n' "$p" > "$cfg"
+curl -s -K "$cfg" http://192.168.0.143:3000/api/v1/user   # confirms identity
+curl -s -K "$cfg" -X POST -H 'Content-Type: application/json' --data @body.json "$API/pulls"
+```
+
+- Never pass the token with `-H` — it lands in `/proc/<pid>/cmdline`, world-readable.
+- Confirm identity with `GET /user` before trusting a write path; a `token is required` there means the token never authenticated.
+- Merges are a separate shape (form-encoded `do=merge`, auth-only cfg, NO `Content-Type` header) — see the gitea-merge-form-encoded skill.
@@ -0,0 +1,53 @@
+---
+name: gitea-issue-labels-and-pr-curl-traps
+description: "Dankclaw Gitea API curl traps: PR create needs Content-Type application/json (fake \"[Head]: Required\"), issue labels only via POST /issues/N/labels (PATCH labels silently dropped), token from URL-format secret file."
+---
+
+Operate Dankclaw Gitea (`http://192.168.0.143:3000`, repo `dank/franksign` and siblings) with curl without the three traps that produce misleading errors.
+
+## Token extraction (URL-format store, NOT key=value)
+
+`~/.config/secrets/gitea` is one line: `http://user:TOKEN@192.168.0.143:3000`. `cat`-ing it yields the whole URL, not the token.
+
+```bash
+TOK=$(sed -n 's|.*://[^:]*:\([^@]*\)@.*|\1|p' ~/.config/secrets/gitea | head -1)
+```
+
+Never pass the token as a `-H` argument (world-readable in `/proc/<pid>/cmdline`). Write a 600-perm curl config:
+
+```bash
+printf 'header = "Authorization: token %s"\n' "$TOK" > /tmp/g.cfg
+```
+
+## Trap 1 — PR create answers `"[Head]: Required"` when the body is the problem
+
+Two independent causes, both look like a missing field:
+
+1. No `Content-Type: application/json` header → Gitea parses the raw JSON as form data, sees no `head`, returns 422 `[Head]: Required`.
+2. Putting `data = "@/tmp/body.json"` inside a `-K` curl config does **not** expand the `@`.
+
+Fix: add `header = "Content-Type: application/json"` to the config and pass `--data @/tmp/body.json` on the command line:
+
+```bash
+curl -s -K /tmp/g.cfg -X POST --data @/tmp/pr.json \
+  "http://192.168.0.143:3000/api/v1/repos/dank/franksign/pulls"
+```
+
+## Trap 2 — issue label assignment via PATCH /issues/N is silently dropped
+
+`PATCH /api/v1/repos/{o}/{r}/issues/{n}` with `{"labels":[id]}` returns **200/201 with the issue JSON**, yet a follow-up GET shows `labels: []` (it can even clear existing labels). Labels are a subresource:
+
+```bash
+curl -s -K /tmp/g.cfg -X POST --data '{"labels":[4]}' \
+  "http://192.168.0.143:3000/api/v1/repos/dank/franksign/issues/18/labels"
+```
+
+200 returns the assigned label array. Resolve label names→ids via `GET /repos/{o}/{r}/labels` (franksign canonical five: ids 2–6; `ready-for-agent` = 4).
+
+## Verification law
+
+Both traps fail *successfully*. After any label/PR write, GET the resource and check the field changed; never trust the status code alone.
+
+## Cleanup
+
+`rm -f` the temp config + body files (config holds the token).
@@ -1,75 +1,26 @@
 ---
 name: gitea-merge-form-encoded
-description: "Use when a Gitea API merge on Dankclaw (192.168.0.143:3000) returns HTTP 422 \"[Do]: Required\" or 405 \"Please try again later\" — the merge endpoint needs form-encoded fields with the lowercase field name do, and a behind-main branch must be merged forward before it will merge."
+description: "Merge a Dankclaw Gitea PR with form-encoded do=merge — and the two body failures: 422 [Do]: Required (JSON body) and jsontext invalid character 'd' (form body with Content-Type: application/json header)."
 ---

-Gitea on Dankclaw (192.168.0.143:3000) — merge quirks, measured 2026-10-19 on `dank/serverAppConfigs` and again on `dank/dankvoice`, re-earned the same day on serverAppConfigs PR #27.
+# Gitea merge on Dankclaw: form-encoded, and nothing else

-## 1. The payload: form-encoded, lowercase `do`
+`POST /api/v1/repos/<owner>/<repo>/pulls/<n>/merge` with `-d 'do=merge&merge_style=no-ff'`.

-Creating a PR accepts a JSON body. **Merging does not**: `POST /api/v1/repos/{owner}/{repo}/pulls/{n}/merge` with a JSON body (`{"merge_style":"no-ff", ...}`) or with those values as request headers returns `422 {"message":"[Do]: Required"}` — four variants of that all fail identically, so do not "fix" it by changing the style name or moving the headers around.
+## The two body failures

-**The field name is lowercase `do`.** `--data-urlencode 'Do=merge'` (capital D, which the error message spells) returns the same `422 [Do]: Required`. Do not retry with case variants — the web-UI form field is `do`.
+1. **JSON body** → `422 {"message":"[Do]: Required"}`. The endpoint reads FORM fields, not JSON.
+2. **Form body but a `Content-Type: application/json` header** (e.g. left over in the curl `-K` config file from an earlier PR-body PATCH on the same request setup) → `422 {"message":"[]: jsontext: invalid character 'd' at start of value"}` — Gitea tries to parse `do=merge...` as JSON.

-Working call (form-encoded):
+## Working pattern

-```bash
-tok=$(sed -n 's|^https\{0,1\}://[^:]*:\([^@]*\)@192\.168\.0\.143.*$|\1|p' ~/.config/secrets/gitea | head -1)   # git credential.helper store file
-curl -sS -X POST -w 'http %{http_code}\n' -K <(printf 'header = "Authorization: token %s"\n' "$tok") \
-  --data-urlencode 'do=merge' \
-  --data-urlencode 'merge_style=no-ff' \
-  http://192.168.0.143:3000/api/v1/repos/dank/<repo>/pulls/<N>/merge
-# 200 with an empty body == merged
+Keep TWO curl config files when a session both patches PR bodies (JSON) and merges (form):
 ```
-
- `merge_style` values are the dashed names: `no-ff`, `merge`, `rebase`, `squash`.
- Keep the token out of argv: `-K <(printf …)` feeds the `Authorization` header through stdin (a `-H "Authorization: token …"` lands in `/proc/<pid>/cmdline`, world-readable — the 2026-09-16 HF-token leak class).
- Verify by fast-forwarding a checkout (`git fetch && git merge --ff-only origin/main`) rather than re-reading the PR.
- Fleet law still applies: never merge without an explicit current OK from Frank, and open the PR URL in his browser (`xdg-open`) the moment it exists.
-
-## 2. `405 {"message":"Please try again later"}` = the branch is behind main
-
-A correctly formed merge call returns **405**, not 422, when Gitea cannot test-merge the head into the base. Read it as "merge main forward", not "retry later" — no sleep-retry ever clears it.
-
-Confirm first: `GET /pulls/{n}` shows `"mergeable": false` (and `merged: false`, `state: open`) for exactly this state.
-
-The fix is the repo's own trunk-based law — merge forward, never rebase:
-
-```bash
-git worktree add ../wt-prN -B prN <head-branch>
-cd ../wt-prN && git merge --no-edit origin/main      # resolve, see below
-./tests/run.sh                                       # the seam is the arbiter, run it on the RESOLVED tree
-git push -q origin prN:refs/heads/<head-branch>      # same branch name; Gitea reuses the open PR
-# then re-POST the merge — 200 this time
+# merge.cfg — auth ONLY, no Content-Type
+header = "Authorization: token $TOKEN"
 ```
+`curl -s -K merge.cfg -X POST -d 'do=merge&merge_style=no-ff' http://192.168.0.143:3000/api/v1/repos/<o>/<r>/pulls/<n>/merge`

-Notes earned on PR #27 (2026-10-19):
-
- A `git worktree` per PR keeps the deployed checkout untouched; clean up with `git worktree remove --force ../wt-prN && git branch -D prN`.
- `git status --short` during a merge lists every incoming file as staged — that is the merge commit's content, not a dirty tree.
- Push a local branch to the PR's branch name with an explicit refspec (`prN:refs/heads/docs/…`); the push output prints `Visit the existing pull request`, which is how you confirm you hit the right head.
- Gitea needs a few seconds after the push to recompute mergeability; a `sleep 3` before re-POSTing avoids a second 405.
-
-## 3. Resolving vault conflicts against a compaction wave
-
-When main has run a docs compaction (page deletions, description shortening), two conflict shapes recur:
-
- **`description:`** — `scripts/check-okf.py` enforces **DESC: ≤ 120 chars**. A branch's longer description must be shortened, not argued for; keep main's shape and fold the new topic into the wording.
- **A `[[Page]]` link whose target page main destroyed** — `git ls-tree -r --name-only origin/main -- serverAppConfigs-docs | grep -i '<page>'` settles it. Drop the dead link; do not resurrect a page. Compaction left link-stripped stub bullets behind (`-  the compile fix for …`, dash + two spaces): `git grep -nE '^-  [A-Z]' origin/main -- 'serverAppConfigs-docs/**/*.md'` counts them, and the seam cannot see them because a stub is no longer a link to validate.
-
-After any frontmatter change, regenerate: `./scripts/gen-vault-index.py serverAppConfigs-docs` and commit the index rows — the `vault indices are generated, not hand-carried` seam diffs regeneration against the checkout. The sub-index sync can emit one extra space after `|` for a quoted description; commit what the generator emits, since the seam compares against the generator.
-
-## Credential-store token extraction (same file, adjacent trap)
-
-`~/.config/secrets/gitea` holds one line shaped `http://user:token@192.168.0.143:3000`. Splitting it with `awk -F'/'` puts the host in `$3`, not `$2`, and `awk -F'/' '{print $NF}'` yields the host+path, not the token — an empty/garbage token makes **private repos answer `404 not found`** (Gitea hides them from anonymous), which reads like a wrong URL rather than an auth failure. Extract with:
-
-```bash
-tok=$(sed -n 's|^https\{0,1\}://[^:]*:\([^@]*\)@192\.168\.0\.143.*$|\1|p' ~/.config/secrets/gitea | head -1)
-echo "token length: ${#tok}"   # 40 — print the length, never the value
-```
-
-Other API quirks measured the same day:
-
- `GET /pulls?state=open` can return an error object where `state=all` returns the list; `state=all` list entries may omit `head`/`base` — fetch `/pulls/{n}` for those.
- POST `/pulls` for a head/base pair that already has a PR → `409` naming `issue_id: N`; the PR number is that `issue_id`, so PATCH it instead of POSTing again.
- Issues and PRs share the issue index per repo, so `#36`-style numbers are repo-scoped: a footer fix aimed at `dank/command-center#36` 404s when pointed at `dank/dankvoice`.
+- Success = **HTTP 200 with an empty body**; verify by landing a checkout (`git ls-remote origin main`), never by re-reading the PR.
+- PATCH `/pulls/<n>` (title/body) is the opposite: JSON body WITH the Content-Type header.
+- Token from `~/.config/secrets/gitea` via a 600-perm `-K` file, never `-H` (`/proc/<pid>/cmdline` is world-readable).
@@ -1,30 +1,36 @@
 ---
 name: gitea-pr-api-cycle
-description: "\"Open/update/merge PRs and issues on the Dankclaw Gitea API (192.168.0.143:3000) with the token-safe sequence, the form-encoded merge field, the empty-token-returns-404 trap, and post-merge live-checkout fast-forward plus the plugin-package-name upgrade gotcha.\""
+description: "\"Open/update/comment/merge PRs and issues on the Dankclaw Gitea API (192.168.0.143:3000) with the token-safe sequence (POST /pulls rejects Basic with 'token is required'), numeric label ids, the form-encoded merge field, the async 405 'try again later' merge trap, the empty-token-returns-404 trap, and post-merge live-checkout fast-forward plus the plugin-package-name upgrade gotcha.\""
 ---

 # Gitea PR/issue cycle — Dankclaw API

-Friction-earned 2026-10-18 (PRs #15–#20, issue #18) and re-earned 2026-10-19 on `dank/dankvoice` PRs #4–#6: the merge payload claim below was wrong, and an empty token masqueraded as a missing repo.
+Friction-earned 2026-10-18 (PRs #15–#20, issue #18), re-earned 2026-10-19 on `dank/dankvoice` PRs #4–#6 (the merge payload claim was wrong; an empty token masqueraded as a missing repo), and re-earned 2026-10-20 on `dank/command-center` PRs #55…#57 (the 405 recalculation trap). Re-earned again 2026-10-20 on `dank/dankvoice` #25 (merge gate loop worked; suite verdict delivered as an issue comment). Re-earned 2026-10-21 on `dank/command-center` issue #58 / PR #59 (issue labels are numeric ids; the `<type>/<issue#>-<slug>` branch name has to be right *before* the first push). Same day on `dank/serverAppConfigs` #64: the Basic-vs-token split below cost two wasted POSTs.

 ## Where
 - API base: `http://192.168.0.143:3000/api/v1/repos/dank/<repo>/{pulls,issues}` — repo varies (`command-center`, `dankvoice`, `serverAppConfigs`); numbering is per-repo, so a footer citing `#36` means nothing without the repo.
+- Web UI pages under `/dank/<repo>/pulls/N` are session-auth private: a plain URL fetch answers **404** even when the API and `xdg-open` work. Merge state questions go through the API (`GET /pulls/N` → `state`, `merged`, `merge_commit_sha`) — never conclude from a failed page fetch.
+- **Basic vs token split**: the `username=`/`password=` fields of `~/.config/secrets/gitea` as `Authorization: Basic …` work for **reads and issue/PR comment writes**, but `POST /pulls` refuses them with `403 token is required`. Pull-request lifecycle writes need the **token** header. Use the token for everything PR-shaped; never conclude "API is broken" from a Basic 403 on `/pulls`.
 - Token: never inline, never in argv (`-H "Authorization: token …"` lands in `/proc/<pid>/cmdline`, world-readable). Extract into a 600-perm curl config and hand it to curl with `-K`:
  ```bash
  tok=$(sed -nE 's#^https?://[^:/@]+:([^@]+)@192\.168\.0\.143.*#\1#p' ~/.config/secrets/gitea | head -1)
-  [ "${#tok}" -ge 40 ] || { echo "token extraction failed"; exit 1; }
+  echo "tok len ${#tok}"   # 40 — assert before use
  cfg=$(mktemp); chmod 600 "$cfg"; printf 'header = "Authorization: token %s"\n' "$tok" > "$cfg"
-  curl -sS -K "$cfg" … ; shred -u "$cfg"
+  curl -sS -K "$cfg" http://192.168.0.143:3000/api/v1/repos/dank/<repo>/labels
+  rm -f "$cfg"
  ```
 - **Empty token answers `404 {"message":"not found"}`, NOT 401** — Gitea hides the private repo. A 404 on a path you have used before means auth, not a typo'd repo. The trap that produces the empty token: `awk -F'/' … '{print $NF}'` on the store line (`scheme://user:token@host/`) — the host is in `$3`, the match never fires, you get a silent empty variable. Always assert the length before POSTing.
 - Multi-line bodies: build JSON in python (`json.dumps({"title":…, "body":open(f).read(),…})`) or `jq -n --arg b "$(cat b.txt)"`. NEVER pass `---` as a bare jq argument (parsed as a flag). Escaped quotes inside `python3 -c '…'` break on `\"` — write the script to a file or use a heredoc.
- Always capture status: `-o r.json -w '%{http_code}'`; a bare `-o` hides failures.
+- Always capture status: `-o r.json -w '%{http_code}'`; a bare `-o` hides failures. A `201` response piped straight into `python3 -c` that prints `None None` means you parsed an **error** body (missing `number`) — print `message` too.

 ## Create
-`POST /pulls` with `{title, body, base:"main", head:<branch>}` — JSON is accepted here (unlike merge).
+`POST /pulls` with `{title, body, base:"main", head:<branch>}` — JSON is accepted here (unlike merge). Plain `<branch>` works; the `owner:branch` fork form is unnecessary on same-repo branches.
 - **409 `pull request already exists for these targets [issue_id: N, …]`** — a PR for that head/base exists already. Common cause: the push message printed `/pulls/new/<branch>` and someone (Frank, or an `xdg-open` you ran) clicked Create. `GET /pulls?state=all`, find it, then `PATCH /pulls/N` with your title+body instead of re-posting.
 - `GET /pulls?state=all` on this Gitea omits `head`/`base` per entry — read `/pulls/N` for those, or key off `number`/`user`.
- Issues: same shape, `POST /issues` `{title, body}`; `PATCH /issues/N` fixes a body retroactively (works for PRs too, since a PR is an issue).
+- Issues: same shape, `POST /issues` `{title, body}`; `PATCH /issues/N` fixes a body retroactively (works for PRs too, since a PR is an issue) — used to correct a false verification claim in a PR that had already been merged. Body update returns **201**, not 200; confirm by reading `body` back, not by status code.
+- **Issue labels are numeric ids, not names.** `POST /issues` with `"labels":["ready-for-human"]` answers `422 {"message":"[]: json: cannot unmarshal JSON string into Go int64 within \"/labels/0\""}`. Resolve first: `GET /labels` → pick `id` by `name` → post `"labels":[20]`. (PRs take no `labels` field on create; label afterwards via `/issues/N/labels` with `{"labels":[id]}`.)
+- Comments (the channel for late-arriving evidence, e.g. a test-suite verdict posted after PR creation): `POST /issues/N/comments` with JSON `{body}` — works for PRs too, returns **201**.
+- **Open the issue before the first commit**, so `Refs #N` fits the message, and get the branch name right before the first push. `git branch -m <new>` + `git push -u origin <new>` + `git push origin --delete <old>` is a clean rename with no PR yet; do it rather than ship a branch that violates `<type>/<issue#>-<slug>` (a `docs/…` branch carrying a `fix:` commit is the common slip, and `git grep` on the old name still shows it).

 ## Merge (the 422 trap) — corrected
 `POST /pulls/N/merge` needs **form-encoded** fields; the merge form field name is lowercase **`do`**:
@@ -32,22 +38,49 @@ Friction-earned 2026-10-18 (PRs #15–#20, issue #18) and re-earned 2026-10-19 o
 ```bash
 curl -sS -X POST -K "$cfg" \
  --data-urlencode 'do=merge' --data-urlencode 'merge_style=no-ff' \
-  http://192.168.0.143:3000/api/v1/repos/dank/<repo>/pulls/N/merge
+  http://192.168.0.143:3000/api/v1/repos/dank/command-center/pulls/N/merge
 ```

 JSON `{"Do":"merge"}` (what this skill used to claim) and header variants all return `422 {"message":"[Do]: Required"}`. `merge_style` ∈ `no-ff|merge|rebase|squash`. Success returns **200 with an empty body**; verify by landing a checkout rather than re-reading the PR. Merge only with Frank's explicit per-PR OK.

+### The async 405 when several PRs merge in a row
+Merge #55, then #56 and #57 back-to-back, and #56/#57 answered:
+
+```
+405 {"message":"Please try again later","url":"http://dankclaw:3000/api/swagger"}
+```
+
+That is not a failure and not rate limiting: merging one PR moves `main`, which invalidates every other PR's cached mergeability, and Gitea recalculates it asynchronously. A merge attempt during recalculation is refused. Remedy — bounded poll on the PR, merge when the flag is true:
+
+```bash
+for attempt in 1 2 3 4 5 6 7 8 9 10; do
+  m=$(curl -sS -K "$cfg" "$api/pulls/$n" | python3 -c \
+      'import json,sys;d=json.load(sys.stdin);print(d.get("mergeable"),d.get("merged"))')
+  case "$m" in *True*) <merge POST>; break ;; *) sleep 4 ;; esac
+done
+```
+
+All three landed within ~5 s of retrying. Treat `mergeable` as a readiness gate, not a report. Match `*True*` on the pair defensively: `False True` means already merged — stop, don't merge again.
+
+### Verifying a merge without touching the deployment
+`GET /pulls/N` → `state: closed`, `merged: true`, `merge_commit_sha`. Then prove content from the bare repo, not the working tree: `git fetch -q origin && git show origin/main:<path> | grep -n <key line>` and `git log --oneline --graph -4 origin/main` (two parents = the `--no-ff` Frank asks for). A number you deliberately destroyed can legitimately reappear once — quoted in `omp-docs/log.md` as the wrong value; `git grep -c <badvalue> origin/main` naming only the log page is the pass condition, not a leftover. `Closes #N` in the PR body auto-closes the issue; confirm with `GET /issues/N` → `state`.
+
+## Stacked PRs (no rebase)
+When two open branches edit the same section of the same file, merge the sibling branch into the later one (`git merge docs/other-branch`) instead of rebasing — Frank rejects the history rewrite. Consequences to state in the PR body: merging the lower PR first reduces the upper diff to just its own work; merging the upper first makes the lower an already-contained no-op. Either order is clean; `git branch -d` on the lower branch refuses until its commits reach `main`, because `-d` checks against the current HEAD.
+
 ## Post-merge landing
- Command-center: the checkout IS the deployment — `git -C ~/.omp fetch -q origin && git -C ~/.omp merge --ff-only origin/main`.
+- Command-center: the checkout IS the deployment — `git -C ~/.omp fetch -q origin && git -C ~/.omp merge --ff-only origin/main`. This refuses if **any** incoming path is dirty in the worktree — see `land-merged-pr-with-blocked-tree-ops` for the shared-workspace case where `checkout` and `stash` are both policy-blocked.
+- serverAppConfigs: `deploy.sh` pushes the dev checkout's branch first — if the checkout's `main` is behind a merge you just made (via the API), the deploy dies with `error: failed to push some refs`. `git merge --ff-only origin/main` in the deploy checkout BEFORE running `deploy.sh` after any externally-merged PR.
+- **A PR that changes a path you edited live adds that path to the discard list.** Tonight: the live dotfile fix was dirty *and* incoming, so landing needed `git -C ~/.omp checkout -- <that file>` as well as the usual file. Discard is content-free only when you proved byte identity first (`cmp` the branch file against the live one before merging) — say so in the PR body, and note that if `live-sync.sh` commits the dirty file first the merge stays clean because both sides hold identical bytes.
 - Package repos (`~/Projects/<pkg>`): same `--ff-only`, then reinstall (`omp plugin upgrade <name>`) and `cmp` the installed `dist/index.js` against the repo `dist/index.js` to prove the live artifact is the merged one. Check `ls -ld node_modules` after landing anything that touched it.
 - **`omp plugin upgrade` takes the npm package name, not the short name.** `omp plugin upgrade dankvoice` fails with `Failed to upgrade dankvoice: dankvoice is not installed` while the plugin is plainly installed; the package is `omp-dankvoice`. Find the truth with `ls ~/.omp/plugins/node_modules` or `find ~/.omp -path '*<name>/dist/index.js' -not -path '*/Projects/*'` — the installed tree is unscoped (`~/.omp/plugins/node_modules/omp-dankvoice/dist/index.js`), not `@dank/dankvoice`.
 - **`cmp` exiting 1 BEFORE the upgrade is the expected state** (installed bundle is the pre-merge build, diff reported at some char/line). Do not treat it as a failed deploy and do not "fix" the build; run the upgrade, then `cmp` again for byte identity, and grep the new bundle for a string only the merged code contains (e.g. `grep -c "Heckle instead of summarizing"`) as a second, semantic confirmation.
- Prune: `git worktree remove --force <path>` (force: untracked deps link), `git branch -D`, `git push origin --delete <branch>` (allowed: local Gitea).
+- Prune: `git worktree remove --force <path>` (force: untracked deps link), `git branch -D`, `git push origin --delete <branch>` (allowed: local Gitea). Before removing a worktree, check no live process has a cwd inside it (`ls -l /proc/*/cwd | grep -c "wt/<name>"`) — same guard `live-sync.sh` uses — and copy any file you moved into a gitignored `.AGENTTRASH/` there to its permanent home first, or the removal destroys the only copy.

 ## Attribution footer (AGENTS.md)
 Every issue/PR body ends with `---`, then `cwd: <session cwd> · session: <session id>`. Read the real values, never invent an id.
 - **The session id is the UUID suffix of the LIVE transcript `.jsonl`, not the session directory name.** Transcript dirs are keyed by cwd (e.g. `-.omp-wt-wt-20261019-020309-6d1fc1f`) and ONE cwd can hold several sessions (resume / continuation forks), so `ls -t ~/.omp/agent/sessions/` cannot tell you which is yours and `ls -t <dir>` is equally blind. Pick the file being appended to right now: `ls -l --time-style=+%H:%M:%S <dir>/*.jsonl` beside `date +%H:%M:%S` — the mtime that equals the current second is the live session. The id is the part after `_` in `<timestamp>_<uuid>.jsonl`.
- A `history.db` query for `session_id` filtered by `cwd` usually agrees, but it is not authoritative for WHICH of several sessions in that cwd is live — use the jsonl mtime test.
+- A `history.db` query for `session_id` filtered by `cwd` usually agrees, but it is not authoritative for WHICH of several sessions in this cwd is live — use the jsonl mtime test.
 - `local/` does NOT disambiguate: a forked transcript dir carries copies of the same `local://` artifacts, so matching artifact names proves nothing about which session is live.
 - `cwd` is that session's own working directory (the path the harness states), **not** the build worktree you committed in — when they differ, name the build worktree inside the body and keep `cwd` the session's.
 - Resolve `local://<name>.md` with `read local://<name>.md` (its header prints the absolute path) instead of guessing the directory.
@@ -1,9 +1,9 @@
 ---
 name: gitea-token-from-http-credential-store
-description: "Extract the Dankclaw Gitea token from ~/.config/secrets/gitea for API calls to PRIVATE repos, and diagnose the empty-token 404 that looks like a missing repo."
+description: "Extract the Dankclaw Gitea token from ~/.config/secrets/gitea (it is the URL password, not key=value lines) for API calls, and diagnose the silent empty-token trap that makes public-repo reads pass while writes fail."
 ---

-The Gitea credential store line on Frank's boxes is **http** (not https) with a percent-encoded port:
+The Gitea credential store line on Frank's boxes is **http** (not https) with a percent-encoded port, and the **token is the URL password** — there are NO `username=`/`password=` lines:

 ```
 http://dank:<40-char-token>@192.168.0.143%3a3000
@@ -13,14 +13,27 @@ http://dank:<40-char-token>@192.168.0.143%3a3000

 ```bash
 tok=$(sed -nE 's#^[a-z]+://[^:]+:([^@]+)@.*#\1#p' ~/.config/secrets/gitea | head -1)
-curl -s -H "Authorization: token $tok" http://192.168.0.143:3000/api/v1/<path>
+curl -s -K <600-perm cfg file> http://192.168.0.143:3000/api/v1/<path>
 ```

-Common wrong pattern (silent failure): an `awk`/`grep` anchored on `https://` or on `@192.168.0.143:` matches nothing, leaving `tok=""` — verify with `echo "tok len ${#tok}"` before believing any API result.
+## `git credential-store --file … fill` answers EMPTY — do not debug it

-## The 404 trap
+Tried 2026-10-21 while opening `dank/command-center` PR #61: the obvious extraction

-`dank/command-center` is **public**: an empty token still returns real issue data. `dank/dankvoice` is **private**: the same empty token returns `404` on `/api/v1/repos/<owner>/<repo>` and `{}`-shaped bodies (`title: undefined`) on issues. A 404 with a zero-length token is an auth problem, NOT a missing repo — confirm by printing the token length first, then re-check.
+```bash
+printf 'protocol=http\nhost=192.168.0.143\nport=3000\n\n' | git credential-store --file ~/.config/secrets/gitea fill
+```
+
+prints **nothing**, with no error. It is not a permissions problem and not a wrong path: the stored line encodes the port inside the host field (`@192.168.0.143%3a3000`), so a `host=`+`port=` query can never match it. Add `path=` or drop `port=` and it still answers empty. Read the file with `sed` (recipe above) and move on — the chain `TOKEN=$(…) && [ -n "$TOKEN" ] && …` fails silently at the test, which reads like a curl failure if the `&&` hides it.
+
+## The silent-empty-token trap (bit 2026-10-21, cost a debug detour)
+
+An `awk -F= '/^username=/{...}'` parse of this file yields `tok=""` **silently** — and reads still appear to work when the repo is **public**: `dank/serverAppConfigs` and `dank/command-center` return real issue/label data unauthenticated, so every census "passes" until the first **write** (issue comment, label, PR create/merge) fails with `{"message":"token is always required"}`-style errors or 404s (private repos 404 on an empty token — that is an auth problem, NOT a missing repo).
+
+- `echo "tok len ${#tok}"` (must be 40) before believing ANY API result — reads included.
+- `curl -s -K <600-perm file>` carrying `header = "Authorization: token $tok"` — never `-H` on argv (`/proc/<pid>/cmdline` is world-readable; this leaked an HF token once).
+- Prove auth once per session: `GET /api/v1/user` → `"login":"dank"`.
+- The temp `-K` config holds a live token: `rm -f` it in the same session that made the calls, and never `cat` it.

 ## Other notes

@@ -0,0 +1,44 @@
+---
+name: grafana-provisioned-dashboard-verify
+description: "Author and verify repo-provisioned Grafana dashboards on Dankclaw live: staging to the host provider path, the Grafana-13 unified-storage false-negative on grafana.db, the authenticated /api/search check, per-panel PromQL/LogQL validation before shipping, and the Loki $__auto shell-expansion trap in test harnesses."
+---
+
+Verify or ship Grafana dashboards that are provisioned from the repo (`shared/grafana/provisioning/dashboards/*.json`, auto-loaded by the `fleet` file provider). Use when adding/staging a dashboard, or when asked to confirm provisioned dashboards actually load.
+
+## Paths (Dankclaw)
+- Repo source: `shared/grafana/provisioning/dashboards/` (git is the owner).
+- Host provider dir: `/opt/grafana/provisioning/dashboards` (root-owned), bind-mounted `:ro` into the container at `/etc/grafana/provisioning/dashboards` (from `dankclaw/observability/quadlet/grafana.container`: `Volume=/opt/grafana/provisioning:/etc/grafana/provisioning:ro`).
+- Provider reload interval = 30s, so a staged file appears within ~35s.
+
+## Stage on the host (canonical install is `deploy.sh dankclaw --service grafana` after merge)
+```
+scp -q <files>.json dankclaw:/tmp/
+ssh dankclaw 'for f in <names>; do sudo install -m644 -o root -g root /tmp/$f.json /opt/grafana/provisioning/dashboards/$f.json; done'
+```
+
+## Verification — what DOES and DOESN'T work
+
+**DO NOT trust the sqlite `dashboard` table.** Grafana 13 uses **unified storage**: file-provisioned dashboards do NOT live in the legacy `dashboard` table. Reading `grafana.db` (`sudo python3 - <<PY ... select ... from dashboard`) returns **total dashboards: 0** even when everything is provisioned correctly — a false negative. There is also no `sqlite3` binary in the grafana image or on the host. Grafana logs **no** line on a successful provider load (only errors), so a clean `podman logs grafana` proves only "no error", not "loaded".
+
+**The authoritative check is `/api/search` through an authenticated browser session.** No admin password is configured and anonymous is off — do NOT reset the Grafana admin to do a read check. Drive the RP SSO login with the Playwright `qa-e2e` storage state, then GET the API:
+```js
+const ctx = await b.newContext({ storageState: '.auth/qa-e2e.json', userAgent: "<chrome UA>" });
+const p = await ctx.newPage();
+await p.goto('https://grafana.franksdank.cloud/', { waitUntil: 'domcontentloaded' });
+for (let i=0;i<30;i++){ const t=await p.locator('body').innerText(); if(!t.includes('not a bot')) break; await p.waitForTimeout(3000);}   // clear Anubis PoW
+await p.goto('https://grafana.franksdank.cloud/login/generic_oauth', { waitUntil: 'domcontentloaded' });
+await p.waitForTimeout(6000);
+const r = await ctx.request.get('https://grafana.franksdank.cloud/api/search?type=dash-db&limit=50');  // 200 + [{uid,title}...] = provisioned
+```
+Run it from the checkout that has `tests/e2e/node_modules` + `.auth` + `.env.local` (a fresh worktree lacks them; symlink `node_modules` and copy `.auth` + `.env.local`). Throwaway `_*.cjs`, then move to `.AGENTTRASH/`.
+
+## Validate every panel query BEFORE shipping (catch empty / mis-scaled panels)
+Query Prometheus (`http://127.0.0.1:9090/api/v1/query`) and Loki (`http://127.0.0.1:3100/loki/api/v1/query`) on Dankclaw loopback and confirm non-empty. Real traps found here:
+- **Unit mislabel**: `sum by(job,mode)(rate(node_cpu_seconds_total{mode!="idle"}[5m]))` returns **cores per mode** (up to #cores) — unit `short`, NOT `percentunit`. For a per-host busy fraction use `1 - avg by(job)(rate(node_cpu_seconds_total{mode="idle"}[5m]))`.
+- **Missing metrics**: `scrape_duration_seconds_bucket` and `prometheus_*`-prefixed self metrics may be absent — confirm from `/api/v1/label/__name__/values?match[]=<metric>` before building a panel; `prometheus_target_interval_length_seconds` (a summary with a `quantile` label) exists.
+- **Alertmanager** runs on :9093 but is **NOT a Prometheus scrape target** → its metrics are unavailable; don't build panels on it (they read empty).
+- **Loki streams**: journal arrives as `{job="systemd-journal"}`; `container_name` is a **parsed JSON field, not a stream label** → group at query time: `sum by (container_name)(count_over_time({job="systemd-journal"} | json [$__auto]))`.
+- **Shell trap in test harnesses**: `$__auto` inside a double-quoted ssh/curl string is eaten by the local shell → empty query → Loki returns empty (looks like a broken panel, is a harness bug). For live validation substitute a concrete `[5m]` window, and drive Loki queries with an on-host Python `urllib` client to avoid quoting hell entirely.
+
+## Datasource uids
+`prometheus` (uid `prometheus`), `loki` (uid `loki`); reference as `"datasource": {"type":"prometheus","uid":"prometheus"}` in panel JSON.
@@ -0,0 +1,51 @@
+---
+name: grep-secret-gate-hook-traps
+description: "Write a zero-dependency grep-based pre-commit secret gate that fails closed: the GNU grep -- one-shot trap, POSIX ERE limits, bracket collating elements, and rc=2-as-success in command substitution."
+---
+
+# Fail-closed grep secret gate (pre-commit hook)
+
+Use when writing/auditing a bash pre-commit hook (or any CI tripwire) that scans
+staged content with `grep -E` for credential shapes — no gitleaks available.
+
+## The four traps (all personally earned; each silently PASSES bad content)
+
+1. **`--` is a ONE-SHOT end-of-options marker.** `grep -nE -- 'p1' -- 'p2' 'p3'`
+   takes the later `--` and patterns as FILE names → rc=2, errors on stderr.
+   Correct multi-pattern form: repeat `-e` for every pattern; never `--`.
+2. **`if hits=$(... | grep ...)` treats rc=2 as success.** Any non-zero-but-not-1
+   (broken pattern, unreadable file) enters the `then` branch with EMPTY output.
+   Never branch on the substitution's truthiness. Capture rc explicitly:
+   `hits=$(...); rc=$?` then: `rc>=2` → BLOCK (fail closed — a dead regex is
+   worse than none), `rc==1` → clean, `rc==0` → hits.
+3. **POSIX ERE (`grep -E`) has no `(?:...)` groups.** Use plain `(...)`.
+4. **`[:-]` inside a bracket expression starts a collating element** →
+   `grep: repetition-operator operand invalid` (rc=2, see trap 2). Put `-` FIRST
+   in every class: `[-A-Za-z0-9/+=_.:+]`.
+
+## Gate structure that works
+
+- Scan **staged content**, not the working tree: `git show ":$f"` over
+  `git diff --cached --name-only --diff-filter=ACM`.
+- Denylist doc/fixture paths (`README`, `docs?/`, `tests?/`, `*.example`) — else
+  the hook blocks its own patterns and every test fixture.
+- Report `BLOCKED <file>:<line>` only — never echo the matched secret.
+- Wire with tracked `hooks/pre-commit` + `git config core.hooksPath hooks`
+  (lives in the COMMON git dir config → one set in the main checkout covers
+  every worktree). Fresh clones are unprotected until it's set; document it.
+- Worktrees lacking `hooks/` while `core.hooksPath` is set: git dies on commit
+  (`cannot run ... No such file or directory`) — merge main in, don't unset.
+- Do NOT ship the hook in an npm plugin artifact (`files`): node_modules never
+  runs git; pin its ABSENCE in the pack test instead.
+
+## Test it red-first through the real seam (bats)
+
+`git init` a fixture repo, `cp` the real hook in, `git config core.hooksPath hooks`,
+then drive REAL `git commit` and assert:
+- credential-shaped `.env` (RFC-2606 domains / all-zero ids as inert fixtures) →
+  non-zero AND `git log` count unchanged (blocks, not warns);
+- PEM header line → blocked;
+- clean prose → passes;
+- the hook committing ITSELF → passes (trap 1/3/4 usually die here);
+- exit-code masking: `bats ... | tail` returns tail's rc — never `&& commit`
+  behind a piped suite, or you commit on red.
@@ -1,48 +1,53 @@
 ---
 name: halogen-npu-feasibility-census
-description: "Census whether halogen-flash-server's NPU small-model path can run on a Strix Halo host: image gate, amdxdna/XRT presence, IOMMU and fabric-clock blockers, enablement deltas."
+description: "Census whether halogen-flash-server's NPU small-model path can run and swap models on a Strix Halo host: image gate, amdxdna/XRT presence, IOMMU and fabric-clock blockers, enablement deltas, boot-set-only model loading (no live reload), and the silent-fallback-to-Flash trap for unarmed chat-class NPU models."
 ---

-Use when asked whether halogen/halogen-flash-server can use the XDNA2 NPU (embeddings, rerank, moderation/guard, decider, `qwen3.5-2b` generation, `flux2-klein-4b` images, `qwen3-asr-*`) on a Ryzen AI Max / Strix Halo host, or before proposing to enable it.
+Use when asked whether halogen/halogen-flash-server can use the XDNA2 NPU (embeddings, rerank, moderation/guard, decider, `qwen3.5-2b` generation, `flux2-klein-4b` images, `qwen3-asr-*`) on a Ryzen AI Max / Strix Halo host, before proposing to enable it, or when asked whether it can **hot-swap / live-reload** NPU models like FastFlowLM does.

 ## What the feature is (not a speed knob)

-The Flash trunk stays on the iGPU. `HALOGEN_NPU_MODELS=<names>` starts a second engine in the SAME container and on the SAME API port; the request's `model` field picks the executor. Unset → server identical to before. Each NPU model is a precompiled AIE-ML program (`devices/devices.hnpm`, per-partition `devices/u<N>.elf`, `devices/consts.hnpb`, `<id>.hnpw` weights, `tokenizer/tokenizer.json`), loaded via the HOST's XRT → kernel `amdxdna` → `/dev/accel/accel0`. One pass at a time; `HALOGEN_NPU_QUEUE` 64, overflow queues server-side, then `503 engine_busy`. Entry `entrypoint.sh` validates every file's bytes + sha256 against `/opt/halogen/npu/models.txt` before anything starts. NPU models run only in single-container "all" mode, NOT the `engine`/`api` split.
+The Flash trunk stays on the iGPU. `HALOGEN_NPU_MODELS=<names>` starts a second engine in the SAME container and on the SAME API port; the request's `model` field picks the executor. Unset -> server identical to before. Each NPU model is a precompiled AIE-ML program (`devices/devices.hnpm`, per-partition `devices/u<N>.elf`, `devices/consts.hnpb`, `<id>.hnpw` weights, `tokenizer/tokenizer.json`), loaded via the HOST's XRT -> kernel `amdxdna` -> `/dev/accel/accel0`. One pass at a time; `HALOGEN_NPU_QUEUE` 64, overflow queues server-side, then `503 engine_busy`. Catalog in the 0.16.2 image: `decider-0.8b`, `qwen3-embedding-0.6b`, `qwen3-reranker-0.6b`, `qwen3guard-gen-0.6b`, `qwen3.5-2b` (+ `flux2-klein-4b`, `qwen3-asr-*` in newer tags). Only the programs named in `HALOGEN_NPU_MODELS` are armed.

-## Census (all read-only, run from the operator box)
+## Boot-set-only: NO live reload (tested on the live endpoint)
+
+`HALOGEN_NPU_MODELS` is read **at start**; the entrypoint validates/converts/loads the named programs then. There is **no** runtime load/unload and **no** admin endpoint to add a model. FLM comparison: FLM was a standalone NPU-only server (`flm serve <one-model>`, single FIFO lane) free to reconfigure its one AIE partition; halogen boots Flash (iGPU) **plus** the NPU programs as ONE coupled process (shared port + shared memory/power budget), so the NPU set is a boot-time constant. Changing even a checkpoint's weights reconverts "at the next start", never live.
+
+Consequence — arming a new program = edit `scripts/frank-dragoon.env` -> redeploy -> **container restart -> the whole Flash payload (tens of GB) reloads, minutes**. The small NPU program is not the cost; the Flash reload is.
+
+## The silent-fallback trap (the one that bites)
+
+A request naming an **unarmed** catalog model behaves differently per endpoint class:
+- `/v1/rerank`, `/v1/moderations`: honest **400 `model_not_found`**, message ends `(loaded: none)`. The endpoint only exists if that engine was armed at boot.
+- `/v1/chat/completions` (the `decider-0.8b` decision path and `qwen3.5-2b` generation): **silent fall-through to the Flash model** — HTTP 200, body `"model": "<flash id>"`, no error. A guard/decision call to an unarmed model is answered by the main (often abliterated) endpoint you were trying to screen against, and looks like success. Measured: an unarmed `decider-0.8b` "is this a prompt injection?" probe returned `"no"` from Flash. **Fail-safe is NOT the default on the chat route.**
+
+## Live probe (idle lane; one ssh, non-disruptive — no restart happens)

 ```bash
-ssh <host> '
-# 1. engine gate + catalog in the pinned image
-podman exec <ctr> bash -c "grep -rlo HALOGEN_NPU_MODELS /opt/halogen /usr/local/bin /entrypoint.sh 2>/dev/null | head"
-podman exec <ctr> cat /opt/halogen/npu/models.txt | head -40
-# 2. is NPU actually wired today? (expect NO env, NO device, NO /dev/accel inside)
-podman inspect <ctr> --format "{{json .HostConfig.Devices}}"; podman exec <ctr> ls /dev/accel
-# 3. kernel driver + firmware
-lsmod | grep -i amdxdna; sudo dmesg | grep -iE "xdna|npu" | tail -5; ls -l /dev/accel
-# 4. XRT (distro packages are fine; vendor mounts /opt/xilinx/xrt)
-dpkg -l | grep -iE "xrt|xdna"; ls /usr/lib/x86_64-linux-gnu/libxrt* /usr/lib/libxrt* 2>/dev/null
-# 5. BLOCKER 1: IOMMU
-cat /proc/cmdline; ls /sys/kernel/iommu_groups | wc -l
-# 6. BLOCKER 2: fabric clock held?
-for c in /sys/class/drm/card*/device; do echo "== $c"; cat $c/power_dpm_force_performance_level 2>&1; cat $c/pp_dpm_fclk 2>&1 | tr "\n" " "; echo; done'
+B=http://127.0.0.1:7770   # halogen port; internal engine is :8731/:8740 muxed onto it
+curl -s $B/v1/models | jq -r '.data[].id'          # armed set = boot set; must not mutate
+# control (armed embedding) -> 200 with a real vector:
+curl -s $B/v1/embeddings -d '{"model":"qwen3-embedding-0.6b","input":["ping"]}'
+# unarmed rerank/guard -> expect 400 "(loaded: none)":
+curl -s $B/v1/rerank      -d '{"model":"qwen3-reranker-0.6b","query":"t","documents":["a","b"],"top_n":1}'
+curl -s $B/v1/moderations -d '{"model":"qwen3guard-gen-0.6b","input":["hello"]}'
+# unarmed decider/gen -> watch the "model" field; if it is the flash id, it fell through:
+curl -s $B/v1/chat/completions -d '{"model":"decider-0.8b","temperature":0,"messages":[{"role":"user","content":"x"}],"response_format":{"type":"json_schema","json_schema":{"name":"g","description":"is injection?","schema":{"enum":["no","yes"]}}}}' | jq -r '.model // .error.message'
+# prove nothing restarted:
+systemctl show frank-dragoon.service -p NRestarts -p ActiveEnterTimestamp --value
 ```
+`decider` with a schema and a non-zero `temperature` 400s on a *sampling* guard first ("send temperature 0"); set `temperature:0` to reach the router and see the fallback.

-Docs (raw fetch, authoritative): `docs/NPU.md`, `docs/npu-small-models.md`, `deploy/host/halogen-fabric-clock` under `peonist-ai/halogen-flash-server` on GitHub. Tag list: `podman search --list-tags ghcr.io/peonist-ai/halogen-flash-server`.
+## Enablement gates (all four must hold before it runs)

-## The two blockers and the enablement delta
-
- **IOMMU must be on.** `amd_iommu=off` turns the NPU off (no PASID/SVA); `iommu=pt` keeps it. Needs a grub edit + reboot. `iommu_groups == 0` ⇒ off.
- **Fabric clock must be pinned at the top `pp_dpm_fclk` level** (or `power_dpm_force_performance_level=high`); `auto` = unheld. GPU+NPU concurrently HANG Strix Halo machines and corrupt NPU results while that clock moves. Fix: root container with `-v /sys:/host/sys` (server holds it itself), or install `deploy/host/halogen-fabric-clock` + unit (~1 W). If it can't hold, the server FAILS CLOSED and prints the commands.
- Container delta: `--device /dev/accel/accel0` + `HALOGEN_NPU_MODELS`; `--ulimit memlock=-1:-1` and `--group-add keep-groups` usually already present. Distro XRT: mount each of `libxrt_coreutil.so.2`, `libxrt_core.so.2`, `libxrt_driver_xdna.so.2` TWICE (once at `/opt/xilinx/xrt/lib/`, once at its own path) — never mount an `/opt/xilinx/xrt` holding only symlinks.
-
-## Costs to price before proposing
-
- Upstream A/B: IOMMU translation ON costs **13–16 % prefill** (460 → 385 tok/s at 2,048 tokens, Ryzen AI Max+ 395); decode unaffected. Whether `iommu=pt` specifically costs that on a given box is a local measurement, not a published fact — run the image's own `sweep` after the reboot.
- A few GB host RAM per NPU model (+8 GB FLUX, +1.6/4 GB ASR), and trunk decode drops while the NPU works (shared bus + power).
+1. Kernel `amdxdna` loaded + `/dev/accel/accel0` present; the node must be world-open (`0666` via a udev rule) or a **rootless** container cannot open it — `serve-frank-dragoon.sh` refuses if the mode bit 02 is clear.
+2. Host XRT with the NPU plugin (`libxrt_coreutil.so.2`, `libxrt_core.so.2`, `libxrt_driver_xdna.so.2`); on Arch/CachyOS mount each lib twice (image XRT path + its own `/usr/lib` path), never an `/opt/xilinx/xrt` of dangling links.
+3. **Fabric clock held at top** (`halogen-fabric-clock` root unit) — GPU+NPU at once can hang Strix Halo / corrupt NPU results while that clock changes; the server refuses to start if it can't hold it.
+4. **IOMMU on**: `amd_iommu=off` kills the NPU; `iommu=pt` keeps it.

 ## Laws / traps

- Never probe the NPU beside the live service: stop + mask first (fleet benchmarking policy); this host class has a precedent of a concurrent GPU experiment needing a power cycle. Distinguish off vs wedged with `ip neigh show <ip>` from a peer.
- `/dev/accel/accel0` existing and `amdxdna` probing cleanly does NOT mean the NPU works — with IOMMU off the failure is at context/PASID creation, not at the device node. Do not trust older notes claiming the node itself is missing.
+- Never probe the NPU beside the live service: stop + mask first (fleet benchmarking policy); this host class has a precedent of a concurrent GPU experiment needing a power cycle. Distinguish off vs wedged with `ip neigh show <ip>` from a peer. A single embedding/decision request on an already-armed idle production lane is a normal request, not a benchmark — safe.
+- `/dev/accel/accel0` existing and `amdxdna` probing cleanly does NOT mean the NPU works - with IOMMU off the failure is at context/PASID creation, not at the device node. Do not trust older notes claiming the node itself is missing.
 - `dmesg` lines like `Failed to alloc dev bo memory, ret -28` while large NPU models take turns at NPU memory are benign (vendor-documented); the server recovers.
+- NPU model RSS is host-side, bypassing the container cgroup (GTT/shared pool), like all Strix Halo GPU memory — container stats under-report the true footprint.
@@ -0,0 +1,60 @@
+---
+name: harden-precommit-secret-gate
+description: "Fix or build a pre-commit secret-scan hook that actually blocks leaks: scope hole, fail-closed, quarantine list, and the self-trip that kills an automated committer."
+---
+
+Fix or build a pre-commit secret-scan hook that actually blocks leaks: scope hole, fail-closed, quarantine list, and the self-trip that kills an automated committer. Use when a secret gate is wrong (misses a leak) or too right (rejects an inert example and bricks the heartbeat).
+
+## The two failure directions
+
+A gate can be **too weak** (misses a real key) or **too strong** (rejects its own documentation and takes down an automated committer). Both are outages; the second is silent.
+
+## Audit recipe for an existing gate
+
+1. Read the hook and list what it actually inspects. The classic scope hole: `git diff --cached -- '*.env' '*.pem'` — an extension whitelist. A credential in `agent/config.yml`, a quadlet unit, or a SKILL.md is then invisible to the gate. The rule that survives: scan **the entire staged diff**, every path, and let only binary content out.
+2. Test fail-closed behaviour: can the hook be made to print nothing and still exit 0? Common escapes — running outside a git repo, unreadable staged diff, a hook that pipes through `grep` and inherits `grep`'s exit code from the wrong stage, or `set -e` swallowing the verdict. Verdict must be: unknown ⇒ **block**.
+3. Quarantine list, never tracked: `.env`, `auth.json`, `trust.json`, `*.pem`, `*.key`, `identity*` — and the `.gitignore` policy must quarantine env files **at any depth under any name** (`**/.env*`, not `.env`), or `config/prod.env` slips past.
+4. Escape hatch must be explicit, per-commit, and loud: `ALLOW_SECRETS=1 git commit …`, and the hook says so when it honours it.
+5. Gate the gate: a test that commits a fixture repo through the hook and asserts it blocks. `tests/secret_gate.bats` here covers: shape in an unexpected extension, bcrypt hash, JWT, placeholder/indirection allowed, prose allowed, binary ignored, unreadable diff refused, deletion of a credential never blocked, `ALLOW_SECRETS` override.
+
+## Self-trip: the gate rejects its own example (live 2026-10-21)
+
+Symptom: a systemd timer that commits machine-written files fails **every hour**, and the journal shows the gate's own refusal:
+
+```
+SECRET GATE: staged diff contains 1 secret-shaped string(s):
+  agent/managed-skills/git-secret-gate-hook/SKILL.md
+    Fake secrets must be inert (RFC 2606 domains, all-zero ids, `AKIA0000000000000EXAMPLE`) AND must not
+```
+
+The offender is the AWS **documentation** example key — entirely inert — and `AKIA[0-9A-Z]{16}` cannot tell it from a leak. So the gate's own advice about writing an inert fake is uncommittable by the gate. Auto-learned skills describe credential shapes for a living, so this recurs by construction, and an automated committer cannot use `ALLOW_SECRETS=1`: that would blind the gate for the *other* 64 staged files.
+
+Diagnose, in this order:
+
+```bash
+journalctl --user -u live-sync.service -b --no-pager | tail -25   # which file, which line
+git -C ~/.omp status --short | head                                # how much is queued behind it
+# then scan the WHOLE staged queue, not just the reported file:
+git diff --cached -U0 | awk '/^diff --git/{f=$3;sub("^a/","",f)} /^\+/ && !/^\+\+\+/ {
+  l=substr($0,2)
+  if (l ~ /sk-[A-Za-z0-9]{16,}|ghp_[A-Za-z0-9]{20,}|github_pat_[A-Za-z0-9_]{20,}|glpat-[A-Za-z0-9_-]{16,}|AKIA[0-9A-Z]{16}|xox[baprs]-[A-Za-z0-9-]{10,}|eyJ[A-Za-z0-9_-]{20,}\.[A-Za-z0-9_-]{10,}\.|-----BEGIN [A-Z ]*PRIVATE KEY-----/)
+    print f": "substr(l,1,90) }'
+```
+
+The second count is the decision input: one hit ⇒ fix the line; many ⇒ the gate needs an exemption channel before anything lands.
+
+Fixes, in order of preference:
+
+1. **Describe the shape instead of printing a matching literal** — `AKIA` followed by zeroes and `EXAMPLE`, spelled out in prose, cannot match. One line, the gate stays strict, the next timer run drains the queue.
+2. **Per-line allow marker** honoured by the hook (e.g. a trailing `secret-gate: allow` on the flagged line) — durable, keeps documentation honest, still fail-closed everywhere else. Needs a test both ways: a marked line passes, an unmarked one still blocks. Note the risk honestly: an attacker-adjacent string can self-authorise, so the marker belongs in review-able prose tiers, not in a diff that also touches secrets config.
+3. Never widen the regex to skip markdown, never run the automation with the override env var set.
+
+Inert-fake rule for anything that must *show* a credential shape: RFC 2606 domains, all-zero ids, the word `EXAMPLE` — and if the shape itself trips the gate, describe it in prose rather than print it.
+
+## Prose must not be collaterally blocked
+
+Markdown explaining credential handling is the bulk of what a knowledge repo commits. `xox` inside a sentence about Slack token prefixes, or a `sk-` prefix discussed abstractly, must pass; the shapes are anchored long-suffix patterns for exactly that reason. When a gate fires on prose, that is a bug in the gate — but if the prose contains a *literal* matching token, the fix is the prose (option 1 above), not the pattern.
+
+## Verifying a gate change
+
+Write the fixture repo in a temp dir, commit through the hook, assert block/allow for each case. Do not test the regex by grepping the hook's source for the pattern — a copy of the pattern in a comment is not a gate that runs.
@@ -0,0 +1,31 @@
+---
+name: harness-model-config-wire-capture
+description: "Verify what the omp harness actually sends to a local inference endpoint (reasoning_effort, sampler keys, thinking-off) by pointing a scratch HOME at a logging proxy, instead of inferring it from models.yml comments."
+---
+
+A `models.yml` comment claiming "the wire sends X" is a claim about the harness, not the engine, and the harness rewrites between the two: compat maps pass unmapped values through, effort ladders clamp before the map applies, and a "disable reasoning" role flag can be implemented as *send the lowest effort* rather than a switch. Read only the wire.
+
+## Recipe (minutes, no production state touched)
+
+1. **Logging proxy** — python `ThreadingHTTPServer` on `127.0.0.1:7799` forwarding body+path to the real engine and appending the request body's interesting keys (`model, reasoning_effort, max_tokens, temperature, top_p, top_k, chat_template_kwargs`) as one JSON line per request. Run it as a named bash service with `ready.port` so the port is proven before use.
+2. **Scratch HOME** — `mkdir -p /tmp/omph/.omp/agent`, copy the *candidate* `models.yml` + `config.yml` there, rewrite that provider's `baseUrl` to `http://127.0.0.1:7799/v1`. Never edit `~/.omp/agent/` — in `dank/command-center` the checkout is the deployment.
+3. **One-shot runs** — `HOME=/tmp/omph omp --model '<provider>/<id>:<effort>' --no-tools --no-session --no-skills --no-rules --no-extensions --no-pty --no-lsp -p 'Reply with exactly: OK'`, once per effort (`off minimal low medium high xhigh max`). Add `--print-thoughts` when the question is "did thinking actually happen".
+4. Read the log, and assert the value **after** the change. A config edit that never engaged is the failure mode this exists to catch.
+
+## Traps found doing this on frank-dragoon (2026-10-21)
+
+- `--model X:off` does **not** mean `reasoning_effort: off` on the wire. Reasoning is switched through `compat.reasoningDisableMode` (enum includes `lowest-effort`, `none-effort`, `qwen-enable-thinking-false`, `qwen-template-false`, `chat-template-thinking-false`); the default derives from `thinkingFormat`, and `lowest-effort` quietly keeps thinking alive (`:off` arrived as `"minimal"`, with a canned 26-token thinking block on every "off" request). `none-effort` sent `"none"` → `reasoning_tokens: 0`.
+- Effort levels are clamped to the harness's per-model ladder **before** `reasoningEffortMap` applies, so a map row for a level the ladder lacks is inert (`:max` arrived as `xhigh` even with `max: max`). Capture before promising a level works.
+- Map lookup is `compat.reasoningEffortMap?.[effort] ?? thinking?.effortMap?.[effort] ?? effort` — removing a row is a pass-through, never a 400. Claims about rejection must be proven against the engine.
+- Engine-side claims: ask for a deliberately bad value and read its 400 — the engine prints its own accepted set (`reasoning_effort 'maximum' unsupported; use minimal|low|medium|high|xhigh|max|none`).
+
+## Engine-side probes that transfer to any OpenAI-compatible endpoint
+
+- **Accepted parameters**: `{model, messages, max_tokens:1, <param>:<value>}` → status + `error.message`. Acceptance is not honouring: report it as acceptance.
+- **Level honoured?** same prompt at `max_tokens 2048` per level, compare `usage.completion_tokens_details.reasoning_tokens`. Equal values across levels = the parameter is ignored; `reasoning_closed_at` reveals a per-level thinking ceiling.
+- **Thinking off**: `chat_template_kwargs {"enable_thinking": false}` and top-level `enable_thinking: false` → expect `reasoning_tokens: 0`.
+- **Vision**: build a solid-colour PNG in-script (`zlib`+`struct`, no PIL), 512×512, ask for the colour in one word **with thinking disabled** — otherwise the answer is cut off by the thinking block and the probe is inconclusive. A 1×1 image only proves token accounting.
+
+## Teardown
+
+Kill the proxy service, remove the scratch HOME, the proxy script and its log. Never leave copies of `config.yml`/`models.yml` in `/tmp`: they carry provider endpoints and sometimes tokens.
@@ -1,27 +1,50 @@
 ---
 name: land-merged-pr-with-blocked-tree-ops
-description: "Use when a merged PR must land in a checkout whose working tree is dirty and workspace policy blocks git switch/restore/stash/reset-to-commit: prove identity, commit forward, merge, verify."
+description: "Use when a merged PR must land in a checkout whose working tree is dirty and workspace policy blocks checkout/stash — prove the delta content-free, hand the operator the two-liner, verify via live config meanwhile."
 ---

-# Landing a merged PR into a checkout with blocked tree operations
+Landing a merged PR when the deployment checkout is dirty **and** workspace policy blocks `git checkout`/`git stash`. Use when `git merge --ff-only origin/main` aborts with "Please commit your changes or stash them before you merge" in a SHARED workspace where other agents have work in flight. Earned 2026-10-20 on `dank/command-center` (the checkout IS the deployment).

-Shared-workspace policy can block `git switch`, `git checkout <branch>`, `git restore`, `git stash`, and `git reset <commit>` ("uncommitted changes other concurrent agents rely on"). A `git pull --ff-only` then aborts with *"Your local changes to the following files would be overwritten by merge"* — **even when the local content is byte-identical to the incoming commit**, because git compares the index, not intent. Observed twice on 2026-10-19 (dank/command-center, dank/dankvoice).
+# Land a merged PR with blocked tree ops
+
+## Why it blocks
+
+`--ff-only` refuses when **any** incoming path is dirty in the worktree — it checks dirtiness against the *old* HEAD, not whether your content matches the target. Proven: overwriting the file so it is **byte-identical to the target commit** (`cmp` clean against `git show origin/main:<path>`) still aborts with the same message. So "make the file match main" is not a way in, and neither is `git merge` from another worktree (the branch is checked out in the dirty one).
+
+The blocking set is what you must know, exactly:
+
+```bash
+comm -12 <(git diff --name-only HEAD..origin/main | LC_ALL=C sort -u) \
+         <(git status --porcelain | awk '{print $NF}' | LC_ALL=C sort -u)
+```
+
+`LC_ALL=C sort` matters — git's own output order trips `comm: file N is not in sorted order` and you get garbage overlap lists. In the case this was earned on, 12 incoming paths and 57 dirty ones intersected in exactly **one** file.

 ## Procedure

-1. **Prove identity first — never assume it.**
-   `git fetch && git diff --stat origin/main -- <the dirty paths>` → **empty output** means the working tree already equals the merged result, so committing it forward destroys nothing. If it is not empty, stop: there is real local work; do not proceed.
-2. **Commit forward** the identical paths (message says exactly that, e.g. *"land merged #N content; policy blocks restore/stash, so the identical copies are committed rather than discarded"*). Hooks still run.
-3. **Merge, don't ff:** `git merge --no-edit origin/main` (ort resolves identical changes on both sides cleanly). `--ff-only` is impossible once step 2 created a commit.
-4. **Untracked-collision case:** if the abort says *"Please move or remove them before you merge"*, an untracked local file occupies a path the merge adds. `mv` it aside, merge, then `cmp` the restored file against the copy — identical → drop the copy (if the copy came from `.AGENTTRASH`, delete it and `rmdir`, since the file is now tracked).
-5. **Verify:** repo lint/tests, `git status --porcelain -- <paths>` empty, and `git rev-parse --short HEAD origin/main` equal **after a fresh `git fetch`**.
+1. **Fetch, don't merge yet.** List incoming commits (`git log --oneline HEAD..origin/main`) so you can show what is waiting.
+2. **Compute the blocking set** with the `comm` above (both inputs `LC_ALL=C sort -u`).
+3. **Prove the local delta is content-free**, in the direction that matters — lines the working tree has that `main` does not:
+   ```bash
+   diff <(git show origin/main:<path>) <path> | grep -c '^>'   # local-unique lines
+   ```
+   Zero means the working tree is a strict subset of what was merged: discarding loses nothing.
+4. **Preserve before you touch:** copy the current file to `~/.AGENTTRASH/` (snapshot), and copy anything you had moved into a gitignored `.AGENTTRASH/` inside a build worktree to its permanent home in the deployment — otherwise pruning the worktree destroys the only copy of a quarantined page.
+5. **Do NOT work around the policy.** `git checkout -- <path>`, `git stash`, and `git stash push -- <path>` are all blocked in a shared workspace and the block is correct: it protects other agents' in-flight work. Do not reach for `git reset --soft` + `git restore --staged` to slide the pointer past it either — that leaves the index holding staged *reverts* of every incoming path, one careless `git commit -a` away from undoing the merge.
+6. **Hand the operator the two-liner** and keep working on what does not depend on it:
+   ```bash
+   git -C ~/.omp checkout -- <path> && git -C ~/.omp merge --ff-only origin/main
+   ```
+   Say why it is safe (step 3's number, plus where the snapshots live) and what it unblocks.

-## Gotchas
+## Why waiting is not free

- `git merge … | tail -3` masks the exit status — `tail` always exits 0 and an `&&` chain then continues past an aborted merge. Run the merge unmasked, or check `${PIPESTATUS[0]}`.
- Immediately after a push, `git rev-list --count main..origin/main` can report phantom commits-behind from a stale remote-tracking snapshot. Re-`fetch` and compare `rev-parse` before believing any drift.
- Do not push redundant commits into a *deployment* checkout without checking the repo's tier law: machine/live tiers commit straight to `main`, human/agent prose goes by PR.
+`scripts/live-sync.sh` merges with a plain `git merge --no-edit origin/main` (its line ~88), so the hourly heartbeat hits the identical wall and raises its ntfy alert `merge conflict with origin/main — local commit kept; needs you at the keyboard`. Report that consequence: the dirt is not merely untidy, it alerts.

-## Never
+Also note for later: `git branch -d <merged-branch>` **refuses until the commits reach `main`** — `-d` checks against the current HEAD, not `origin/main` — so local branch deletion goes on the post-landing list, not the pruning list.

-No `--no-verify`, no `reset --hard`, no `checkout -- <path>`, no "temporary" stash: those are exactly the operations the policy blocks because they discard other agents' work.
+## What you CAN do while it waits
+
+- **Verify the merged behaviour through the live config, not the branch pointer.** Merged prompt/config changes take effect from the deployment's files: spawn a fresh session/subagent and have it read and quote the changed file back. That proves the change is live even while `main` is behind.
+- Prune your own build worktrees, but check nothing is running inside them first: `ls -l /proc/*/cwd 2>/dev/null | grep -c "wt/<name>"` (the same guard `live-sync.sh` uses).
+- Delete the merged remote branches (`git push origin --delete <branch>`, allowed on the local Gitea).
@@ -0,0 +1,69 @@
+---
+name: locale-c-multibyte-awk-silent-loss
+description: "Debug generated output that silently loses data under LC_ALL=C — a regex quantifier on a multibyte character in awk/grep, plus the locale-dependent red test it produces."
+---
+
+# LC_ALL=C kills multibyte regex quantifiers — silently
+
+Symptom: a generator emits a **complete, exit-0, missing-a-third-of-the-page** artifact in
+cron / systemd user units / agent shells, and the same command looks perfect in the user's
+terminal. Companion symptom: a repo test is red for the agent and green for the operator.
+
+## Probe (do these in order, they are 5 seconds apart)
+
+```bash
+echo "LANG=[$LANG] LC_ALL=[$LC_ALL]"   # LC_ALL overrides LANG — en_US.UTF-8 + LC_ALL=C is byte-wise
+locale -a | grep -iE 'utf-?8' | head    # which UTF-8 locale actually exists on this box
+```
+
+Then test the suspect pattern alone, under both locales, with the literal character:
+
+```bash
+printf '%s\n' '    // ─── Applications ───' | awk '/─+ / { print "QUANT MATCHED" }'
+printf '%s\n' '    // ─── Applications ───' | awk '/─/    { print "LITERAL MATCHED" }'
+printf '%s\n' '    // ─── Applications ───' | LC_ALL=C.utf8 awk '/─+ / { print "QUANT MATCHED under UTF-8" }'
+```
+
+Literal matches everywhere; the quantifier matches only under a UTF-8 locale. That asymmetry IS
+the bug: gawk under `LC_ALL=C` matches bytes, so `─+` means "the last byte of U+2500, repeated" —
+a byte sequence that never occurs. mawk/busybox/Go regexp have the same class of failure
+(quantifier or bracket class spanning a multibyte char).
+
+## Fix
+
+Match and strip the multibyte literal with no quantifier:
+
+```awk
+/^[[:space:]]*\/\/[[:space:]]*─/ {          # literal gate
+  s = $0; sub(/^[[:space:]]*\/\/[[:space:]]*/, "", s); sub(/[[:space:]]+$/, "", s)
+  if (s ~ /─ .*─/) { gsub(/─/, "", s); gsub(/[[:space:]]+/, " ", s); sub(/^ /, "", s); ... }
+  next
+}
+```
+
+**Never pin `LC_ALL=en_US.UTF-8` to "fix" it** — that locale often does not exist (a CachyOS box
+here shipped only `C.utf8`), so the script then breaks on another machine. Make the matcher
+byte-safe instead.
+
+## Pin it with a test
+
+`run env LC_ALL=C "$GEN" "$IN"` + assert the lost content is present. The operator's UTF-8 terminal
+can never catch this class of bug, so the explicit C-locale run is the only durable guard.
+
+## Suite-verification law (how this got missed)
+
+NEVER judge `bats tests/` from `tail` output — a failure at test 28 is invisible in a 25-line
+window ending at test 109. Always:
+
+```bash
+out=$(bats tests/ 2>&1); echo "$out" | grep -cE '^ok'; echo "$out" | grep -E '^not ok' || echo GREEN
+```
+
+Run it under `LC_ALL=C` too: that is the environment every automated caller inherits. Same rule
+for `| grep -c` on a multi-line JSON field — count what you claim to have counted.
+
+## Related, do not confuse
+
+- `bats-assertion-trust` — vacuously-passing assertions (green that proves nothing). This skill is
+  the mirror case: correct assertions that are only red in one locale.
+- `gitea-pr-api-cycle` — unrelated; landed here only because the PR work is where this surfaced.
@@ -0,0 +1,36 @@
+---
+name: new-fleet-service-checklist
+description: "Add a new deployable service to serverAppConfigs: the four registration touch-points (two allowlists, planner, router) whose drift breaks the first-ever deploy."
+---
+
+# Adding a new service to the serverAppConfigs deployer
+
+A new `--service <name>` target must be registered in **four** files or the first deploy fails at a gate. Two fleet services (cadvisor, gpu-exporter) shipped with the client gate missed within a day of each other; the failure mode is `Service 'X' is not deployed on <target>` from `deploy.sh`, exit 2 — before SSH.
+
+## The four touch-points (per target host)
+
+1. `scripts/deploy.sh` → `valid_service()` case: add `<target>:<svc>`. **Client gate** — the one people forget.
+2. `scripts/deploy-remote.sh` → `service_is_allowed()` case: add `<target>:<svc>`, **and** the dispatcher `case` branch `<svc>) deploy_<svc> ;;`.
+3. `scripts/deploy-plan.py`: the name in the target's service set (`DANKCLAW_SERVICES` / `DANKSERVER_SERVICES`) + `SERVICE_ORDER`, plus a path map so edits to the service's own files select it (for `scripts/<svc>.*` host processes, map the exact filenames like the signal-relay/gpu-exporter maps do).
+4. `scripts/test-changed.sh`: route the service's files to its seam, else focused test runs skip it (full `tests/run.sh` still covers).
+
+Sanctioned exception: `dankclaw:searxng-network` is client-only (network unit, no remote handler) — the drift test exempts it.
+
+## Enforcement + local verification
+
+`tests/deployment_flow.bats` test "the client and remote allowlists agree per target" diffs the two extracted lists. Verify before pushing:
+
+```bash
+grep -oE 'dank(claw|server):[a-z0-9-]+' <(sed -n '/^valid_service()/,/^}/p' scripts/deploy.sh) \
+  | grep -v dankclaw:searxng-network | sort -u > /tmp/cli
+grep -oE 'dank(claw|server):[a-z0-9-]+' <(sed -n '/^service_is_allowed()/,/^}/p' scripts/deploy-remote.sh) \
+  | sort -u > /tmp/rem
+diff /tmp/cli /tmp/rem   # must be empty
+```
+
+Also: a `# comment` after a trailing `\` inside a bash `case` pattern list **breaks line continuation** (syntax error) — annotate on its own line above.
+
+## Gotchas
+
+- Merge ≠ deploy: `deploy.sh <host> --service <svc>` must still be run per host; a merged service is dead code until then (GPU stats "not showing" was exactly this).
+- `deploy.sh` refuses to run anywhere but a clean `main` checkout: the canonical dev checkout is `/home/blank/Projects/serverAppConfig` (not the session `~/.omp/wt/...` worktree, not the build worktree).
@@ -0,0 +1,64 @@
+---
+name: niri-monitor-flap-refresh-triage
+description: "Diagnose niri/amdgpu monitor failures on blankpad — panel dropping, wrong refresh rate, black/flickering output — and fix the refresh without reloading the compositor or logging Frank out."
+---
+
+# niri monitor triage: flaps, phantom modes, 60 Hz fallback
+
+Frank's reaction to a broken display is immediate and loud; the fix must never log him out.
+Box: `blankpad` (Cezanne APU, `card1`, s2idle only), compositor `niri --session` as a user unit.
+
+## Step 1 — separate three different diseases (do this before touching anything)
+
+```bash
+niri msg outputs                          # name, mode, position, full mode list per output
+for c in /sys/class/drm/card*-*/status; do echo "$(basename $(dirname $c)) $(cat $c)"; done
+systemctl --user show niri.service -p ExecMainStartTimestamp -p NRestarts   # did niri restart?
+journalctl --user -b --no-pager | grep -iE 'disconnecting connector|new connector|Page flip commit failed|DMCUB|falling back to preferred'
+journalctl -k -b --no-pager  | grep -iE 'amdgpu|PM: suspend exit|\*ERROR\*'
+```
+
+Reading it:
+
+- `disconnecting connector: "X"` then `new connector: X` → **link-level drop** (cable/dock/monitor/driver). Count them: `grep -c 'disconnecting connector'`.
+- `Page flip commit failed … EINVAL` bursts + kernel `dc_dmub_srv_log_diagnostic_data: DMCUB error` right after `PM: suspend exit` → **amdgpu display-engine state broken by s2idle resume**. Only a reboot clears it; never reboot without an explicit per-run OK.
+- `configured mode M could not be found, falling back to preferred` → **config asks for a mode the panel does not offer**; the panel silently runs at EDID-preferred (usually 60 Hz). This is the one you can fix instantly.
+- Config mtimes older than the symptom + no `niri` restart ⇒ the config did not cause it. Say so explicitly; agents get blamed for display problems they didn't cause.
+
+## Step 2 — the phantom-mode trap (niri fails soft, so it looks like hardware)
+
+`output { mode "…" }` with a refresh the EDID never advertised does **not** error. niri logs a WARN and drops to `preferred` on every connect → janky 60 Hz ultrawide, blamed on the monitor.
+
+Compare the requested mode against the panel's real list:
+
+```bash
+niri msg outputs | sed -n '/<monitor name>/,/^$/p' | grep -E '^\s+[0-9]+'
+```
+
+## Step 3 — apply the mode WITHOUT a config reload (the no-logout path)
+
+```bash
+niri msg output "<EDID output name from niri msg outputs>" mode "WxH@refresh"
+niri msg outputs | grep -A1 '<monitor>'      # confirm the new mode
+pgrep -c niri                                # compositor still alive, same PID
+```
+
+`niri msg output …` is documented as temporary ("not saved into the config file") — it changes one output and cannot log the session out. Avoid `niri action reload-config` when Frank is working: it reloads his whole config.
+
+## Step 4 — persist, and check you edited the file that is actually live
+
+Live niri config is a symlink chain: `~/.config/niri/config.kdl` → `cfg/display.kdl` → `cfg/desk-<profile>.kdl`, and `cfg/desk-*.kdl` are symlinks into the repo:
+
+```bash
+ls -l ~/.config/niri/cfg/display.kdl          # -> desk-1-home.kdl
+grep -n '239\|180' ~/.config/niri/cfg/display.kdl   # prove YOUR edit is in the live chain
+niri validate                                  # parses the live config; touches nothing
+```
+
+`dotfiles/` is on the `live-sync.sh` heartbeat allowlist, so an edited tracked dotfile stays dirty until the hourly heartbeat commits it — that is the designed state, do not commit it on `main` yourself.
+
+Desk config law (its own header): panels keyed by **EDID identity**, not connector name — but connector-keyed leftovers (`DP-1`, `DP-2`) survive in `desk-1-home.kdl`, and a reconnect that comes back without an EDID string hits those instead. Align them to the same mode, or a flap silently changes your refresh rate.
+
+## Escalate honestly
+
+Reboot clears DMCUB/EINVAL state → schedule it, don't take it. Persistent drops after a reboot → cable / dock / monitor DP-version setting, i.e. hardware, not config. Report which of the three diseases you found and which you did **not** fix.
@@ -0,0 +1,45 @@
+---
+name: observability-stack-live-census
+description: "Census the Dankclaw observability stack (Prometheus/Grafana/Loki/Alloy/Alertmanager/signal-relay) live and audit per-endpoint alert coverage; reconcile against the owner page and rule-file comments, which go stale."
+---
+
+# Observability stack — live census + alert-coverage audit
+
+Use when asked "status of the observability stack" on Dankclaw, or before claiming a service is/isn't monitored. Everything runs rootless on Dankclaw: `ssh dankclaw bash -s <<'EOF' … EOF`. Verify live; the owner page (`serverAppConfigs-docs/Infrastructure/Observability.md`) and `shared/prometheus/rules/llm-fleet.yml` comments go stale.
+
+## Loopback ports (do NOT probe the wrong one)
+- Prometheus `127.0.0.1:9090` · Alertmanager `127.0.0.1:9093` · Loki `127.0.0.1:3100` · Alloy `127.0.0.1:12345` · signal-relay `192.168.0.143:18093`
+- **Grafana host port is `127.0.0.1:3002`** (→ container :3000). Host `:3000` is a `rootlessport` for some *other* rootless container and answers 200-on-`/` but 404-on-`/api/health`. Probing :3000 and seeing 404 is a false alarm — always use 3002 for Grafana. `GF_SERVER_ROOT_URL=https://grafana.franksdank.cloud`.
+
+## Units + containers
+`for u in prometheus grafana loki alloy alertmanager node-exporter blackbox signal-relay; do systemctl --user is-active $u.service; systemctl --user is-enabled $u.service; done`
+- Quadlet units report `generated` (healthy), not `enabled`; signal-relay is a real host unit (`enabled`).
+- `blackbox` = `not-found`/inactive → the known gap (no blackbox exporter).
+- `podman ps` for `Up N days (healthy)`.
+
+## Prometheus — targets / rules / alerts
+- Targets: `GET :9090/api/v1/targets` → `.data.activeTargets[] | .health, .labels.job, .lastError`. Expect ~8 up / 4 down. **The 4 downs are structural, not outages:** `comfyui` + two `services` (HTML content-type, no real /metrics) and `gitea` (404, metrics disabled). Root remedy = deploy a blackbox exporter (not yet present).
+- Rules: `GET :9090/api/v1/rules` → count `.data.groups[].rules`. The `llm-fleet` group is **4 alert + 2 recording** (6 total). **AGENTS.md saying "5 alert + 1 recording" is wrong** — trust the rule file.
+- Firing: `GET :9090/api/v1/alerts`; Alertmanager: `GET :9093/api/v2/alerts` and `/api/v2/silences`.
+
+## Alert-coverage per runtime — the sharp step (catches real blind spots)
+The `llm-fleet` perf alerts (`LlmRequestsQueueing`/`LlmPrefixCacheCollapse`/`LlmSpecDecodeOff`) key on the **`llamacpp:*`** family. Which endpoints actually emit it:
+```
+GET :9090/api/v1/query?query=count by (job)({__name__=~"llamacpp:.+"})
+GET :9090/api/v1/query?query=up{job=~"frank-.*"}
+GET :9090/api/v1/query?query=count by (__name__)({job="frank-archon"})   # what archon really exports
+```
+Ground truth (2026-10-20):
+- **frank-zealot** (llama.cpp) → `llamacpp:*` (17 series) → perf alerts cover it.
+- **frank-dragoon** (halogen) → still emits `llamacpp:*` (10 series; halogen re-uses the names) → perf alerts cover it.
+- **frank-archon** (radiance) → exports the **`vllm:*`** family (`vllm:num_requests_waiting`, `vllm:gpu_prefix_cache_hit_rate`, `vllm:num_preemptions_total`, **`vllm:time_to_first_token_seconds_bucket`** = a real latency histogram), **not `llamacpp:*`** → **NO perf alert fires on archon**; only `LlmEndpointDown` (`up{job=~"frank-.*"}`) catches it. Up/down yes, perf/queueing/prefix/p95 = collected but unalerted.
+- The rule-file header comment claims "frank-archon LEFT the scrape set 2026-10-05, FreeToken exports no /metrics" — **stale/false**: archon (radiance) is `up` and exports `vllm:*`. `LlmEndpointDown`'s description repeats the same stale claim. Never assert coverage from a comment; query the families.
+
+## Log pipeline emptiness test
+Loki is "configured, healthy, empty": `GET :3100/loki/api/v1/labels` → `{"status":"success"}` with **no `data` array** = 0 label names = 0 streams. Confirm: `find /opt/loki/data -name '*.tsm' -o -name 'chunks-*' | wc -l` → 0 chunks (≈8 WAL/bookkeeping files only). Alloy ships 0 lines (journal counter 0, both file globs refused per the page — a config bug, not capacity). No Loki datasource in Grafana. Report the log half as non-functional, not merely "healthy."
+
+## Reporting posture
+- Metrics half works (up/down for all 3 endpoints + node-exporter + self-scrape); log half dead-on-arrival; blackbox + archon-perf-alerts + Loki-datasource + Alertmanager-vhost are the open gaps.
+- Grafana provisioning is file-based — check `podman exec grafana ls /etc/grafana/provisioning/{datasources,dashboards}` (expect `prometheus.yml`, `llm-fleet.json`) rather than fighting the API for creds.
+- Alertmanager has no persistence: a reboot re-stamps `startsAt` on long-firing alerts.
+- Flag stale facts (AGENTS.md rule split, archon-rejoin comments) but let the user decide whether to fix docs.
@@ -0,0 +1,41 @@
+---
+name: omp-background-job-deadline-debug
+description: "Diagnose a background bash job/service killed mid-run (\"Command timed out after Ns\") in omp: find which deadline owned it (tools.maxTimeout cap vs async default), prove it from the bundle, and launch long jobs uncapped as ready-log services."
+---
+
+# Omp background-job deadline forensics
+
+Symptom: an async `bats`/build job dies with `[Command timed out after 300s|600s]`
+while the same launch once ran 18+ min ("no deadline").
+
+## Cause map (proven against the pinned bundle)
+Resolver in `dist/cli.js`: `let v=n??300, R=v===0, k=R?void 0:ep("bash",v,x)` where
+`qx.bash={default:300,min:1,max:3600}` and `x` = config key `tools.maxTimeout`
+("Maximum timeout in seconds the agent can set for any tool", default 0).
+- Request absent → `qx.bash.default` 300 s.
+- Request > 0 → clamped by `tools.maxTimeout` when set (e.g. 600 caps a 1800 request).
+- Request 0 → meant "no deadline", but `0` sometimes arrives as missing (falsy drop
+  upstream of the resolver) → silently 300 s. Filed as tool issue; treat any
+  async job over ~5 min as untrustworthy.
+
+## Diagnose in three moves
+1. `grep -o 'qx={bash:{[^}]*}' <omp bundle>` — policy table (`command -v omp` →
+   `readlink -f` → `dist/cli.js`).
+2. `read cfg://tools` — live `maxTimeout` (value ≠ 0 explains any hard cap).
+3. Compare kill notices: the number in "killed once it has run Ns" is the resolved
+   deadline; 300 = default reached (request dropped), other values = your request
+   or the config cap.
+
+## Launching jobs longer than the cap
+- Named **services are not deadline-capped**: `bash(name:"x", pty:false, command:"…; echo DONE >> log", ready:{log:"DONE", timeout:900})`.
+  Readiness fires on the log pattern; result does NOT auto-deliver — `wait` on it or read `proc://x` after the supervisor notice.
+- NEVER end the service command with `echo "EXIT $?" >> log` and trust the
+  supervisor's exit code — the trailing echo masks it (supervisor reports 0 while
+  the log says EXIT 1). The log line is the truth; grep the log for the recorded
+  code and `^not ok` before believing any "exit code 0".
+- Do not raise `tools.maxTimeout` unasked: session-scoped `write cfg://tools/maxTimeout`
+  needs user approval and may be declined — respect it, use the service route.
+
+## Multi-suite hazard
+Suites that rebuild shared artifacts per test (e.g. dankvoice bats rebuilds `dist/`)
+must not run concurrently — one suite at a time, or per-worktree copies only.
@@ -1,29 +1,48 @@
 ---
 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)."
+description: "Diagnose omp extension misbehavior (handler timeouts/silence, cross-instance arbitration failures like simultaneous speech) when the on-disk fix is already deployed: running sessions hold pre-upgrade in-memory bundles; compare ps lstart against artifact mtimes and merge dates."
 ---

-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.
+# Stale in-memory omp extension bundles

-**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.
+Symptom class: an extension behaves as if unfixed even though the disk artifact
+contains the fix — recurring handler timeouts, silence, or (multi-instance
+coordination features) arbitration failures that look like code bugs. Root
+cause: **omp loads the bundle at session start; `omp plugin upgrade` on disk
+does not touch the code already running in live sessions.**

-**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.
+## Recipe 1: date the sessions against the artifact

-**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.
+```bash
+date
+stat -c '%y %n' ~/.omp/plugins/node_modules/<pkg>/dist/index.js   # last upgrade
+ps -eo pid,lstart,etime,args | grep 'omp' | grep -v grep          # each session's boot
+```
+
+Any session whose START predates the artifact mtime holds an older bundle —
+for it, the "fix" never shipped. When the feature landed in git, compare
+against the merge date, not the last upgrade (`git log --format='%h %cI %s'
+main | grep -i <feature>`): a session can predate the feature *existing*.
+
+Fix is always: restart (`/quit`, then `omp --resume <id>`) — resume is
+lossless. It is the user's live session; never kill it yourself.
+
+## Recipe 2: cross-process arbitration — a bypasser explains "simultaneous X"
+
+When a feature serializes across sessions via files (e.g. dankvoice stage:
+`~/.cache/dankvoice/stage/` with `lease.json` = `{holder,pid,expires}`, one
+`<ISO>-<session>.json` entry per queued item, FIFO = filename order, lease TTL
+6 s), overlap between two actors proves **at least one actor never consults
+the directory** — the mechanism can't serialize against a bypasser. Census the
+queue live (`watch -g -d 'ls <dir>; cat <dir>/lease.json'`): a live, renewing
+lease proves the new sessions coordinate; then Recipe 1 finds the bypasser.
+
+Known residual hazard to note, not silently fix: a lease heartbeat is a timer
+on the holder's own event loop; a stall longer than the TTL lets a peer steal
+the lease mid-action. Mitigation = pid-liveness check in the steal path.
+
+## Verification
+
+After restarts, the symptom must vanish while the queue shows traffic. If it
+persists, look for actors on OTHER hosts (file arbitration is per-box), or
+the TTL-steal hazard above.
@@ -0,0 +1,78 @@
+---
+name: omp-search-provider-fallback-debug
+description: "Diagnose why the omp harness web_search silently uses a fallback provider (e.g. Kagi) instead of the configured primary (SearXNG): the fallbackChains masking pattern, the searxng.endpoint base-URL scheme/guard-chain trap, and the cli.js + content-type probes that prove it."
+---
+
+# omp web_search silently using the wrong provider
+
+Symptom: agent searches return results from a fallback provider (e.g. **Kagi**) even though
+`modelRoles.web` is set to the intended primary (e.g. `web/searxng`). The primary errors
+every time and the failure is invisible because a fallback answers successfully.
+
+## The masking mechanism (always check this first)
+
+`~/.omp/agent/config.yml`:
+- `modelRoles.web:` is the primary (e.g. `web/searxng`).
+- `retry.fallbackChains.web:` is an ordered list tried when the primary throws. The FIRST
+  entry silently serves whenever the primary errors. In this fleet it is `web/kagi`, so any
+  SearXNG error == Kagi answers and you never see an error.
+
+So "searches go through Kagi" almost always means "SearXNG is failing", not a routing mistake.
+
+## The SearXNG endpoint trap (the usual root cause here)
+
+`searxng.endpoint` in config.yml must be a **full base URL pointing at the direct JSON port**,
+used **verbatim** by omp (no scheme auto-added, no normalize — confirmed in `cli.js`). Two ways
+it breaks:
+
+1. **Bare host** (e.g. `search.franksdank.cloud`, no scheme): omp does `new URL(\`${endpoint}/search\`)`
+   → **throws** immediately (URL needs a scheme). SearXNG never contacted.
+2. **The guarded vhost** (`https://search.franksdank.cloud`): returns Anubis' **"Making sure
+   you're not a bot!"** challenge page at HTTP **200 `text/html`**. omp calls `o.json()`
+   unconditionally regardless of content-type → throws on the leading `<`. There is
+   deliberately NO API path through the guard chain (JS challenge + UA denylist).
+
+**Correct value** (direct published port, http scheme preserved — reachable from the LAN only):
+
+```yaml
+searxng:
+  endpoint: http://192.168.0.143:8081   # Dankclaw; NOT the vhost, NOT schemeless
+```
+
+The published port source (192.168.x/loopback/LAN) is in SearXNG's `pass_ip`, so it bypasses
+the JSON rate limiter (hardcoded `API_MAX=4`/IP/hr, not settable except via `pass_ip`).
+
+## Prove it (don't guess)
+
+1. Content-type probe, both paths — the decisive check:
+   ```
+   curl -sk -o /tmp/vh -w "vhost ct=%{content_type}\n" "https://search.franksdank.cloud/search?q=test&format=json"   # expect text/html (Anubis)
+   curl -s  -o /tmp/dp -w "direct ct=%{content_type}\n" "http://192.168.0.143:8081/search?q=test&format=json"          # expect application/json
+   ```
+   vhost = `text/html` + direct = `application/json` confirms the trap.
+2. Code path, in the installed omp dist (NOT a worktree):
+   `/home/blank/.bun/install/global/node_modules/@oh-my-pi/pi-coding-agent/dist/cli.js`
+   (find install: `dirname $(readlink -f $(which omp))`). Grep the SearXNG provider:
+   - `searxng.endpoint` config def → description "Base URL of a self-hosted SearXNG instance".
+   - the request builder `...=e.replace(/\/+$/,""),new URL(\`${r}/search\`)...` → endpoint is
+     verbatim, scheme NOT added.
+   - `X2c`/`J2c` → `if(!o.ok)throw` then `return await o.json()` → HTML 200 passes `.ok` and
+     blows up in `.json()`.
+
+## Apply + verify
+
+- Fix is a harness config edit (`cfg://searxng/endpoint` prompts the user, or edit config.yml).
+  Confirm with the user first — it is their live harness config.
+- Verification after applying: fire a real `web_search` and confirm it returns
+  `provider:"searxng"` (not `"searxng"`-then-fallback / not `"kagi"`).
+
+## Related gotcha (same masking, different cause)
+
+If SearXNG answers JSON but returns empty `results` with `unresponsive_engines` (VPN-exit-IP
+CAPTCHA/429 on google/brave), omp's `vcs` throws a 503 → Kagi again. That's an engine-health
+problem, fix in `[[SearXNG]]`/`[[SearXNG Providers]]`, not the endpoint.
+
+## Hardening option
+
+Drop or reorder `web/kagi` / `web/perplexity` in `retry.fallbackChains.web` so primary failures
+surface instead of silently spending a paid Kagi credit. Flag to user before editing.
@@ -1,49 +1,22 @@
 ---
 name: omp-worktree-path-gotchas
-description: "Use in ~/.omp (or any multi-worktree repo) when an edit lands in the wrong checkout, git checkout is policy-refused, or an omp session id is needed — relative-path tool resolution, shared-worktree branch law, session-id lookup, edit auto-prefix trap."
+description: "Multi-worktree edits/tests land in the wrong checkout: bash persistent-cwd drift, phantom file reverts, which tree a tool really touched"
 ---

-# Multi-worktree gotchas in ~/.omp-style repos
+## Purpose
+Answer "why did my file/tests revert or behave differently than what I just wrote?" in repos with several worktrees (e.g. `~/.omp`, `~/Projects/wt-*`, `~/.omp/wt/*`).

-Measured 2026-10-18 building PR #12/#14 in `dank/command-center` worktrees.
+## Failure modes and fixes

-## 1. Relative paths resolve to the SESSION worktree — always edit by absolute path
-`edit`/`read`/`write` with a relative `path` resolve against the session CWD
-(the harness worktree you were spawned in), NEVER the worktree you `cd`'d into
-via bash. Identical file content in sibling worktrees yields identical
-`[path#tag]` hashes, so an edit can "succeed" against the WRONG checkout with
-no warning; only a rejected stale-hash edit reveals it.
+1. **Bash tool persistent-cwd drift** (the expensive one): the persistent shell keeps its cwd across calls; a call *without* an explicit `cwd` runs in whatever the *previous* call left, which after interleaved work may be a DIFFERENT worktree. Result: reads/greps/appends hit tree A while `git`/`bats` hit tree B — symptoms are "file keeps reverting to HEAD", duplicate test names at shifting line numbers, scenario `CALLS 0` for scenarios that exist, mismatched `grep -n` vs tool-reported line numbers.
+   - **Diagnose:** `pwd` in the same call as the failing command; `wc -l <file>` in BOTH candidate worktrees; compare md5s. The file is not flapping — two files exist and commands alternate between them.
+   - **Fix/prevent:** pass an explicit `cwd` on EVERY bash call once two or more checkouts are in play; never trust a read taken without one as evidence about "the" file.

- When working in a second worktree, ALL file-tool paths: absolute.
- Symptom seen: edit rejected "hash #X is not from this session" while the
-  bash-side `git status` showed the file clean — two different files, two
-  worktrees. Recovery: revert the stray edit (CUT the inserted lines) in the
-  wrong tree, re-read the right tree, redo with absolute header.
+2. **Symlinked or stale `git` state**: `git status` in a worktree shows a clean tree while the disk file differs from what you intended — the corruption is already committed. Audit committed blobs (`git log --oneline -- <file>`; per-commit `git show <c>:<path> | grep -c <sentinel>`) instead of re-reading the disk copy repeatedly.

-## 2. Branching: shared worktrees refuse git checkout
-Workspace policy blocks `git checkout` (branch switches AND `--` discards) in
-harness-managed worktrees — concurrent agents depend on them. To start a
-branch off fresh trunk:
+3. **Same-name files across worktrees** (`tests/behavior.bats` exists in each): a `find`/`grep` rooted above the worktrees mixes copies; anchor the search path to one worktree root.

-```bash
-git -C ~/.omp worktree add -q -b <type>/<issue#>-<slug> ~/.omp/wt/<name> origin/main
-```
-
-Never force past the refusal; the new-worktree route is strictly safer.
-Custom worktrees not matching `wt/wt-*` are invisible to the live-sync reaper —
-prune them by hand after merge (`git worktree remove`, `git branch -d`).
-
-## 3. omp session id for attribution footers
-Fleet law requires `session:` in issue/PR bodies. Authoritative source:
-`~/.omp/agent/sessions/<cwd-slug>/<timestamp>_<UUID>.jsonl` — the `<UUID>` is
-the session id. Pick the newest file whose first `{"type":"title"}` line names
-this conversation to prove the id is yours. The `wt/<ts>-<hash>` dir suffix is
-NOT the session id (it persists across sessions per cwd).
-
-## 4. edit-tool auto-prefix trap (recurring)
-A body row written bare (intending it as the "original line" anchor or as
-context) is AUTO-PREFIXED with `+` and INSERTED — leaving the old line plus a
-duplicate. `PUT n.=n:` therefore behaves like insert, not replace, whenever
-the anchor row lacks an explicit marker. After any `PUT` where the response
-warns "Auto-prefixed bare body row(s)", immediately `CUT` the stale line number
-shown in the response (descending order for multiple CUTs).
+## Repair recipe for a corrupted-but-committed test file
+- Inventory both versions: `grep -o '@test "[^"]*"' | sort` and `grep -o 'case "[a-z]*":' | sort -u`; `comm` the sets to find lost scenarios and duplicate tests.
+- Rebuild from the committed copy (`git show HEAD:<path> > <path>`, no checkout), then re-apply only the true deltas: restore missing scenario blocks from the last clean base, dedupe imports, rename scratch-dir mkdtemp prefixes that collide with a test's own orphan-census glob (e.g. `dankvoice-stage-` matching `dankvoice-*`).
+- Re-run the targeted tests, then the full suite single-process.
@@ -0,0 +1,41 @@
+---
+name: parallel-suite-shared-db-flake
+description: "Diagnose test suites that pass isolated but fail only under concurrent/uncached runs against a shared database: cross-file teardown wipes, FK-cascaded sessions, wildcard LIKE deletes."
+---
+
+# Flaky only under concurrency on a shared DB
+
+Symptom: a suite passes `vitest run <file>` alone, fails under `turbo run test --force`
+(or any concurrent uncached runner) with impossible errors — 401 where 404 was
+expected, rows vanishing mid-test, sessions dying between two awaited requests.
+
+## Procedure
+
+1. **Reproduce the concurrency, not the file.** Isolated runs prove nothing.
+   `bun x turbo run test --force --output-logs=errors-only` (or run the two suspect
+   files simultaneously). Never conclude "flake" from one green isolated run.
+2. **Map the impossible state to a vanished row.** 401/auth failures where the
+   session was created milliseconds earlier = the session/user row was DELETED
+   under the test, not expired. Look for writers, not readers.
+3. **Grep every suite's teardown for shared-namespace deletes:**
+   `grep -rn "TRUNCATE\|DELETE FROM\|LIKE" <pkg>/src/*.test.*`
+   The classic killer: two test files sign users up under the same domain
+   (`%@studio.test`) and each `afterAll` runs a wildcard `DELETE ... LIKE '%@...'`.
+   With parallel files on one DB, whichever file finishes first cascades away the
+   other's live rows (user FK cascades kill sessions mid-flight).
+4. **Fix = scope, never coordinate.** Each suite deletes only rows it created:
+   per-file email/id prefixes (`auth*` vs `rel*`), or track created keys and
+   `WHERE email = ANY(...)`. Timing tricks (sleeps, retry) hide the collision.
+5. **Prove stability:** 3 consecutive `--force` uncached runs green, then the
+   full gate. Cache makes everything look green; only uncached concurrent runs
+   re-exercise the collision window.
+
+## Gotchas
+
+- Error signatures lie: `expected 401 to be 404` reads as an auth bug but is a
+  deleted-row cascade.
+- Supertest `cookieOf`-style helpers that THROW on missing cookies prove signup
+  succeeded — so the session died after creation; keep hunting for the deleter.
+- Shared dev DBs (one Postgres for all workspaces/worktrees) make every wildcard
+  teardown a cross-suite weapon. Suite teardowns on a shared box MUST scope to
+  rows the suite created.
@@ -0,0 +1,37 @@
+---
+name: pdf-lib-determinism-moddate-leak
+description: "Diagnose pdf-lib output that isn't byte-identical across fetches: PDFDocument.load restamps /ModDate; fake-clock determinism test; inflate object streams to diff."
+---
+
+# pdf-lib byte-identical output: the /ModDate clock leak
+
+## Symptom
+A "reconstruct-on-read, byte-identical forever" PDF endpoint passes its back-to-back refetch test but returns **different bytes when fetches cross a wall-clock second**. Same-second fetches match; a fetch 1s later differs (often a different stream `/Length`, e.g. object stream 411→420 bytes).
+
+## Root cause
+`PDFDocument.load()` has its own `updateMetadata` option (**defaults true**) and stamps `/Info /ModDate` from the wall clock **at load time**, not just at save. `doc.save({updateMetadata:false})` on its own is not enough (and in pdf-lib 1.17 `updateMetadata` isn't even in the `SaveOptions` type — only in `PDFOptions` on `load`); passing it to `save` also fails typecheck.
+
+## Fix
+```ts
+const doc = await PDFDocument.load(templateBytes, { updateMetadata: false });
+// ... fill, stamp print layer ...
+return doc.save(); // save never stamps when load didn't
+```
+Output becomes a pure function of (template bytes, values).
+
+## Determinism test law
+A determinism test MUST straddle a time boundary. Back-to-back fetches/fills are structurally blind to per-second stamping.
+- Unit: fake the clock (`@sinonjs/fake-timers` or `vi.useFakeTimers`) → fill → jump +2 months → re-fill → `expect(Buffer.from(second)).toEqual(first)`. No sleeps, no flake window. Faking `Date` outside a test framework requires patching `globalThis.Date` BEFORE the module import that uses it.
+- Prove it red first against the old code (expect the byte/length drift).
+
+## Byte-diff forensics (when lengths differ)
+1. Dump the differing region raw: `Buffer.subarray(idx-60, idx+60)` rendered latin1 with non-printables stripped — locate the exact field (`D:YYYYMMDDHHmmss` = clock leak).
+2. If the diff is inside a compressed object stream, inflate and compare streams:
+```ts
+import { inflateSync } from "node:zlib";
+// find /Type /ObjStm ... stream chunks, inflateSync each, string-compare
+```
+3. pdf-lib escapes text-show operands — inflate + unescape `\\(\\[()\\\\]\\)` before substring-asserting printed values.
+
+## Live proof recipe
+Seed a submission, then fetch both retrieval doors at t, t+1.5s, t+3s; `sha256sum` all three → one hash. Same-second comparisons prove nothing. And kill any long-running dev service holding the app port first — a live :3000-style stack can hang or false-fail an e2e gate.
@@ -0,0 +1,60 @@
+---
+name: pdf-widget-layer-census
+description: "Census a real-world \"flat\" PDF before assuming it needs field injection: Quartz/Preview exports often already carry an AcroForm widget layer under underscore rules; also audits pdf-lib flatten residue."
+---
+
+# Real-PDF census (widget-first, then judge)
+
+A PDF that *looks* flat (`pdftotext` shows `____` fill rules) may already contain a
+full AcroForm widget layer — macOS Preview/Quartz exports write widgets with
+transparent rects under drawn underscores. Injecting fields into such a file
+duplicates/shadows widgets. Always census before touching the pipeline.
+
+## Steps
+
+1. **Surface facts** (host):
+   ```bash
+   pdfinfo file.pdf            # "Form: AcroForm" hints at a widget layer
+   pdftotext -layout file.pdf -  # label lines + underscore rules = intended fields
+   ```
+2. **Widget census** — authoritative check. With the franksign sidecar image,
+   the image ENTRYPOINT *is* `inject_fields.py`; override it:
+   ```bash
+   podman run --rm --entrypoint python -v ~/Downloads:/in:z \
+     localhost/franksign-pdf-field-sidecar:local -c "
+   import pymupdf
+   d = pymupdf.open('/in/file.pdf')
+   for p in d.pages():
+       for w in p.widgets():
+           print(w.field_name, w.field_type_string, [round(v) for v in w.rect])
+   print('widgets:', sum(1 for p in d.pages() for _ in p.widgets()),
+         'annots:', sum(1 for p in d.pages() for _ in p.annots()))
+   "
+   ```
+3. **Fill test**: if widgets exist, `fillTemplate()` (pdf-lib) consumes the file
+   AS-IS — spec.json + sidecar are unnecessary for it. Flatten-verify below.
+
+## Flatten audit gotchas
+
+- `pdfinfo` prints `Form: AcroForm` even on correctly flattened pdf-lib output —
+  pdf-lib `flatten()` removes every *widget/annotation* but leaves the field
+  *dictionary*. Truth = MuPDF widget enumeration (0), not the pdfinfo line.
+- `describeForm(bytes, specJson)` in `packages/pdf` parses the SPEC, not the
+  PDF, for the field list — pass a spec or skip it; calling it spec-less throws
+  `JSON Parse error`.
+
+## Decision rule
+
+- widgets > 0 → the widget layer IS the spec (names/types/rects, flip y to
+  bottom-left origin); NEVER run `inject_fields.py` over it.
+- widgets = 0 → genuine flat form: sidecar injection with a spec (position
+  detection = issue #14 territory: underscore-run rects, label-derived names).
+- Missing signature widget is normal ("please sign" is prose); franksign
+  decision 19: the typed full name is the signature.
+
+## Privacy
+
+Real documents are personal: scratch copies in /tmp, placeholder fill values,
+destroy scratch (`rm /tmp/*` is fine OUTSIDE the repo; repo deletions still go
+to `.AGENTTRASH/`). Never commit the document, a spike script touching it, or
+its extracted text into the vault.
@@ -0,0 +1,51 @@
+---
+name: radiance-decode-prefill-interference-census
+description: "Diagnose decode collapsing while another session prefills on a radiance endpoint: phase-ratio step counters, lag test, metric-prefix and scrape traps, and which knob acts on the measured mechanism."
+---
+
+Read `core/config.cpp` (help table + validator) in the PINNED image source before writing any radiance flag, enum member, or metric name into a runbook: `config_parse` refuses unknown enum values at boot, so a remembered name can make the recorded arm undeployable. Enumerate members from the validator's error string, never from memory.
+
+**Run the census on the pinned build's own metric set.** An older pin ranks the wrong mechanism: on radiance 1.0.13 the bucket table put a "collapse" on a shape whose counters did not exist yet, because every counter resets at a restart and the metric set changes with the build. Prove the window is one shape (`up`, or the first sample of a counter only the current build exports) before ranking buckets.
+
+## Step ledger first, knobs second
+
+Three counters decide which mechanism you are looking at, and none of them is a rate:
+
+- `radiance:engine_step_seconds_decode_total / engine_steps_decode_total` = mean **decode-only** step.
+- `(engine_step_seconds_total - engine_step_seconds_decode_total) / (engine_steps_total - engine_steps_decode_total)` = mean **chunk step** (a chunk alone, or a chunk with decode rows beside it).
+- `engine_steps_held_total` — if it is zero, nothing is protecting decoders.
+
+If decode-only steps stay ~15 ms while the rate collapses, the mechanism is **step-time sharing** (a decode row in a chunk step waits the chunk's whole time), and any eviction/residency story is worth ~10 % of one step. The residency half is not censusable: the arena / expert slab / heat engine / prefill stager have **no metric at all** — they are read from the boot ledger, `/stats`, and `/diagnostics`.
+
+## Bucket, then lag-test, before believing a cause
+
+Bucket `radiance:decode_tokens_per_second` by `radiance:prefill_tokens_per_second` from the *same* scrape, step ≤ 30 s (a 15 s scrape against a 120 s step samples one in eight). Per-stream rate = decode gauge ÷ `vllm:num_requests_running`; the tps gauges are ~1 s decayed batch-pooled windows.
+
+Then shift the prefill series by lags and re-bucket:
+
+- lag-0-only ⇒ step-time sharing — the chunk is holding the device.
+- a lagged tail (2–14 min) ⇒ something evicted (arena loan, expert slab, KV).
+- bursts in `vllm:num_preemptions_total` ⇒ a preempted sequence stopped and is re-prefilling from token 0: a stall, not sludge.
+
+Also bucket TTFT (`histogram_quantile` over `vllm:time_to_first_token_seconds_bucket`) by the same series: the decode gauge only sees sequences already running, so an arriving request pays the same steps and shows in no decode number.
+
+## Metric traps
+
+- **Latency is `vllm:`, cadence is `radiance:`.** TTFT / inter-token / per-output-token / e2e / decode-time histograms and the running/waiting gauges exist only under the vLLM compatibility prefix. Preemption is `vllm:num_preemptions_total` (counter); `radiance:num_requests_preempted` is the *instant* depth. A `radiance:`-only query finds no latency and no preemption and reads as "the endpoint never stalls anyone".
+- **A 2-minute mean step time dilutes the chunk** — if ~5 % of steps carry a third of the step time, `step_seconds/steps` cannot move. Use the phase ratio.
+- **`prefix_hit_cut_tokens_total` is prefill load you created yourself**: on a hybrid (linear + paged) model a hit reuses only to the last linear-state checkpoint, so cached tokens replay as prefill. A high prefill rate is not always a client sending new tokens.
+- Radiance's own step-detail histograms (`prefill_steps_duration`, `prefill_step_tokens`, `token_queue_wait`) may be exported but unscraped; per-request forensics then mean `curl localhost:7770/stats` on the endpoint's host, and `/diagnostics` answers "is the *box* the limit" in one call (configuration drift, VRAM split, per-card link chain and clocks, findings with fixes).
+- Rootless container logs: read as the deploy user (`podman logs <svc>`), never `sudo podman logs`; check where the serve script redirects before trusting a log file.
+- In a temporary/remote shell, zsh aborts on a non-matching glob — quote or guard `/sys/...` wildcards.
+
+## Knob semantics (radiance 1.8.x, GUIDE §4.5; pinned source is referee)
+
+- `--prefill-interleave N` — the **decoder dial**: N decode-only steps follow any chunk step taken beside decoders; held steps admit nothing. Costs the prefilling prompt's TTFT and a queued request its first step. Counts as `engine_steps_held_total`.
+- `--busy-prefill-chunk` — a **prefill-speed dial**, not decoder protection: `auto` reserves 1+spec rows per decoding sequence and 1/8 of the budget per waiting request, and the source refuses to halve for decode rows alone. Never below the prefill stager's smallest pass (named on the boot line) — below it every routed layer reads its pooled experts synchronously.
+- `--prefill-span N` — needs `--max-num-batched-tokens` = N intervals; re-funds a *lone* prefill only, so it cannot buy back held steps while decoders run, and its extra intervals land on the arena that the expert slab loses.
+- `--checkpoint-policy` — retention only, three names (`geometric-backoff` | `tip-only` | `keep-all`); snapshot writes happen at every interval whatever the policy says (only `--prefill-span` skips them), so `keep-all` buys a bounded replay for pinned host RAM and no extra PCIe. Shortening `--checkpoint-interval` does NOT fix deep divergence: the geometric ladder's coarsest scale is the largest `interval × 2^k` under the depth, so the deepest gap stays ≈ half the prompt while every cut multiplies the writes.
+- `--checkpoint-slots` is a **total**, `auto` = policy `held()` + 1, per `--max-num-seqs`, within an eighth of host RAM; `--max-num-batched-tokens` is the blunt rung — it raises the arena the slab loses and its resonance on an expert-tiered payload can be violent.
+
+## Verify an arm, don't assume it
+
+Flags may be passed conditionally by the serve script, so prove the flag reached argv (`tr '\0' ' ' < /proc/$(pidof <engine>)/cmdline`), then the counter the knob moves (`engine_steps_held_total` must leave zero), then the bucket pair. A deploy is not evidence a knob engaged. Rollback for each of these is its env line, not a rebuild.
@@ -0,0 +1,52 @@
+---
+name: radiance-flag-truth-from-pinned-source
+description: "Before writing a radiance flag, value, or metric name into a runbook, prove it against the pinned image's source and the engine's own boot ledger — catches invented option names and stale defaults."
+---
+
+# Radiance flag truth from the pinned source
+
+Use when a radiance (`codeberg.org/StillDeadcode/radiance`) flag, its admitted values, a resolved
+default, or a `/metrics` name is about to go into a vault page, env comment, or arm proposal — or when
+a claim about one is being repeated from memory. Docs and old vault pages go stale; the pinned tree and
+the boot ledger do not.
+
+## Procedure
+
+1. **Get the tree at the running version, not at master.** Read the pin:
+   `grep -E 'FRANK_ARCHON_IMAGE' scripts/frank-archon.env` (digest), then
+   `ssh dank@192.168.0.235 'podman images --no-trunc | grep radiance'`.
+   `git clone --branch <ver>` (or checkout the tag) into `/tmp/rad-<ver>`. A `--depth 1` clone makes
+   every `git log -S` report its own tip — never date a flag's introduction from a shallow clone.
+2. **Flag table is the admitted set.** `core/config.cpp` holds the help strings (each option's legal
+   names/units live in the value column) and the validator branch refuses anything else at boot, e.g.
+   `--checkpoint-policy` → `geometric-backoff | tip-only | keep-all`. `core/rad_core.h` carries the
+   struct with the compiled-in defaults. `tests/config_test.cpp` asserts the admitted set — it is the
+   fastest oracle for "is `lru` a policy?".
+3. **Live argv beats the repo env.** `sudo tr '\0' '\n' < /proc/$(pidof radiance)/cmdline` — proves the
+   knob actually reached the engine (an env var typo is invisible from the repo).
+4. **Boot ledger is the referee for every resolved number.** The engine prints its own arithmetic:
+   `ssh dank@192.168.0.235 'podman logs frank-archon 2>&1 | grep -iE "checkpoint|chunk geometry|pools|arena|stager"'`
+   (root unit, but podman storage is dank's — **no sudo**, sudo reads empty root storage). Lines like
+   *"checkpoint slots: auto: 20 … geometric-backoff keeps 9 for a 200000-token session at a 2048-token
+   interval"* are exact; quote them.
+5. **Reproduce the engine's arithmetic to check you understood it.** Reimplement the policy/geometry
+   function in a throwaway Python eval (`select()` / `held()` in `core/mem/prefix.cpp`, `plan_chunk` in
+   `core/sched/scheduler.cpp`) and confirm the numbers match the ledger line from step 4. Agreement
+   means the rule is understood; disagreement means the read is wrong. Delete the scratch after.
+6. **Metric names: query the live target, not the guide.** Latency histograms and preemption live under
+   the **`vllm:`** compatibility prefix, cadence under **`radiance:`**; preemption is the counter
+   `vllm:num_preemptions_total` while `radiance:num_requests_preempted` is an instant gauge. Enumerate
+   with `curl -s localhost:7770/metrics | grep '^# HELP'` on Dankserver, or
+   Prometheus `/api/v1/label/__name__/values?match[]={job="frank-archon"}`.
+
+## Traps that produced real errors here
+
+- A policy name invented from prose (`--checkpoint-policy floor`) would be a boot refusal; a stale
+  resolved default (`auto` = 512) had been copied between pages. Both survived only in the vault.
+- `--checkpoint-policy` governs **retention only**; snapshots are written at every interval regardless
+  (only `--prefill-span` skips writes). Read the call site (`retain()` in `core/mem/prefix.cpp`), not
+  the flag help.
+- Guide/`GUIDE.md` inside an image can be newer or older than the binary; `/diagnostics`
+  `configuration` and the ledger print the running truth.
+- Facts belong to the vault page that owns the endpoint (`serverAppConfigs-docs/LLM/frank-archon.md`) —
+  this skill owns the *procedure*, not the numbers.
@@ -0,0 +1,59 @@
+---
+name: radiance-knob-arm-live-verify
+description: "Arm a radiance scheduler/cadence knob on a live endpoint and prove it engaged: per-knob /metrics meter, argv-vs-default truth, the three behaviour probes, no bench."
+---
+
+# Arming a radiance knob on a live endpoint (no bench)
+
+Use for a one-flag change on a radiance endpoint (e.g. `PREFILL_INTERLEAVE=0→1`,
+`BUSY_PREFILL_CHUNK`, `CHECKPOINT_POLICY`) under the "swap, don't instrument" law:
+edit the trio → deploy the one service → prove the flag reached the engine, the
+engine's own counter moved, and behaviour survived. Never a bench unless Frank orders one.
+
+## Before you set a value
+- **Unset means default, and the engine prints what it resolved.** Grep
+  `/proc/$(pidof radiance)/cmdline` (`sudo tr '\0' ' ' < …`) *and* the container ledger
+  (`podman logs <svc>` as the deploy user — rootless storage, `sudo podman` finds nothing).
+  The ledger line names the resolved value and whether a budget clamped it
+  (`--checkpoint-slots 20 [auto] … of a budget of 31.5 GiB, bound by None`).
+- **Prove the flag exists in the pinned build** before promising it: `--help` from the
+  running container image, not from a vendored tree. Inventing a name (`floor`) cost a
+  doc rewrite; `config_parse` refuses unknown enums at boot.
+- Some flags are conditional in the serve script (e.g. `--prefill-interleave` is passed
+  only when the env value is `> 0`), so a zero→nonzero arm adds argv; re-check argv after deploy.
+
+## Meter map (`/metrics`, names carry the `radiance:` prefix)
+| change | meter that must move |
+|---|---|
+| `--prefill-interleave` | `engine_steps_held_total` (read 0 for a 34.7 h boot while the knob sat at 0; 126 within 4 min of arming) |
+| `--busy-prefill-chunk` | `engine_prefill_chunks_capped_total` |
+| step-time contention generally | decode-only `engine_step_seconds_decode_total/engine_steps_decode_total` vs `(step_seconds_total − step_seconds_decode_total)/(steps_total − steps_decode_total)` |
+| prefix retention | `prefix_hit_cut_tokens_total` (labels: `no_snapshot`), `vllm:num_preemptions_total` |
+
+Trap: **latency lives under `vllm:`, cadence under `radiance:`.** A `radiance:`-only query
+finds no TTFT/ITP and no preemption and reads as "nothing stalls". The arena / expert slab /
+heat engine / prefill stager have **no metric at all** — that half is boot ledger + `/stats`.
+
+## Post-deploy proof, in order
+1. argv contains the flag (or the ledger shows the resolved value).
+2. `/health` 200 (`in_flight`, `queue_cap` come back in the body).
+3. Three probes on the endpoint itself: exact-reply chat (`temperature 0`, expect the
+   literal word — reasoning tokens are normal in `reasoning_content`); a `tools` call
+   expecting a real `tool_calls` object; a **solid-colour PNG via `image_url`** (never the
+   legacy top-level `images` field) with `max_tokens ≥ 512` or thinking eats the budget and
+   a thinking model reads as blind.
+4. The knob's meter left zero-state. If it didn't move, the arm did nothing — say so.
+5. Effect is judged later from real traffic buckets, not from a synthetic load.
+
+## Deploy cycle gotchas that cost the most time
+- `deploy.sh` must run from the dev checkout literally on `main`, tree clean including
+  untracked files; it pushes its own `main`. Never from an agent worktree or the target.
+- Name the service (`--service <svc>`); a bare `deploy.sh <host>` is a fleet-wide drain.
+- Health binds only after the full load (~100 s here, gate budget much larger) — 503 during
+  load is not a fault.
+- Post-deploy for a recently-benched LLM service: `systemctl show <svc> -p DropInPaths`
+  must be empty before believing anything.
+
+## Rollback
+One env line back to the previous value + redeploy the same service. Write the meter and
+the rollback into the endpoint's vault page (that page is the owner), never into a new page.
@@ -1,111 +1,39 @@
 ---
 name: radiance-kv-cache-resize
-description: "Resize the KV cache / VRAM pair on a radiance (StillDeadcode) endpoint: engine-budget-table ceiling, pool contract arithmetic, slab-slope law, ledger-first verification, free token-count probes"
+description: "Resize a radiance endpoint's KV cache/VRAM: the resolver's funding formula, which knob actually moves the carve, the pinned-RAM ledger to recompute, and the boot-ledger lines that referee the result."
 ---

-# Radiance KV / VRAM pair resize
-
-Use when changing `--vram-kv-mib`, `--vram-weights-mib`, `--max-num-seqs`,
-`--max-model-len` or `--kv-cache-dtype` on a radiance endpoint
-(frank-archon pattern), or when asked "what can we do with the free VRAM".
-
-## 1. The ceiling is the engine's, never a hand-picked reserve
-
-`rocm-smi` free space is NOT spare capacity. The boot prints a `VRAM budget,
-per card` table; read it:
+## Method
+- The endpoint is sized by ONE env file (`scripts/<svc>.env`) plus the serve script; the boot ledger prints the split before allocating anything: `VRAM budget, per card` → `claimable` → `elastic` → `experts / kv cache`, then `kv: the cache can grow to X a card -- N tokens of context, M sessions at W`.
+- **`--vram-weights-mib` / `--vram-kv-mib` no longer exist (1.8.1).** The engine REFUSES to start on them (`core/config.cpp`), so this skill has no direct KV knob; the budget resolver derives everything from the cache bound (`--max-num-seqs` x `--max-model-len`), `--gpu-headroom-mib` and `--host-pool-mib`.

+## The funding formula (radiance 1.8.1, source-cited — re-read the pinned tree before trusting it against another build)
 ```
-card total          31.86 GiB
-vram_weights        25.00 GiB   stated by --vram-weights-mib
-vram_kv              5.00 GiB   stated by --vram-kv-mib
-unclaimed            477.30 MiB  the headroom, the unusable above, rounding
-W VRAM budgets total 30.00 GiB of the card's 31.86 GiB, so 1.86 GiB is neither
-  budgeted nor accounted. The driver's context, the activation arena and
-  --gpu-headroom-mib come out of it; anything past those is throughput on the floor
-W card 0 settled at 2.01 GiB free against 209.19 MiB (the 96.00 MiB
-  --gpu-headroom-mib and 113.19 MiB kept for the static region)
+capacity = card_total - already_held - drift - headroom - arena - step_staging - hw_queues - prefetch
+elastic  = capacity - static_weights
+expert_floor = min(plane+spare, max(plane + 2*unit_max - host_room, 0))   # planner.cpp expert_vram_floor
+host_room  = host_pool_mib * MiB  (less the file tier's staging when disk tiering is on)
+kv_cap     = max_num_seqs * max_model_len          # DEMAND, in tokens
+kv         = min(kv_cap, elastic - expert_floor)   # what it actually gets
+tokens     = min over paged groups of n_blocks*block_size   # the printed number
 ```
+Read consequence: **`--max-num-seqs` raises demand, `--host-pool-mib` raises supply, and both are the same lever** — every MiB added to the host pool lowers the expert floor one-for-one and the cache takes it (up to `kv_cap`); the leftover returns to the experts. `--max-num-seqs` alone does nothing to capacity: it raises demand while the floor is unchanged, so the printed tokens stay put. The page's "funds ~91 % of demand" table rows are that cap, not a policy percentage.
+- Derive the plane from a live ledger instead of guessing: `plane + 2*unit ≈ printed_experts + host_pool_bytes`.
+- `--gpu-headroom-mib` lowers go to the cache but the engine's settle floor is built from it — 48 MiB measured decode-neutral, 24 untested. 48 is the first rung.

-`ceiling = (settled_free_MiB - engine_floor_MiB) + current_pair_sum`.
-Worked (dankserver, 2026-10-13): 29,120 + (2,058 − 209) = **30,969 MiB/card**.
-A pair at the ceiling settles ~330 MiB free at worst case. If a bound cannot be
-traced to a ledger line, it is a personal reserve — label it and put it in the
-bats gate as such.
+## Procedure
+1. Read `scripts/<svc>.env` for the current pool: `GPU_HEADROOM_MIB` (96), `HOST_POOL_MIB` (44,928 per rank), `MAX_SEQS` x `MAX_MODEL_LEN` (demand), `HOST_POOL_MIB`, `PLACEMENT`.
+2. Compute the target as tokens: tokens x bytes/token-per-card, where bytes/token = (cache_given_bytes / tokens) from the latest ledger. If the target exceeds `elastic - expert_floor`, ALSO lower `expert_floor` via `--host-pool-mib` (up = more room = fewer resident experts) — a bigger host pool buys cache only while experts remain on the card; once the host absorbs the whole plane, more host RAM buys nothing (measured: +640 MiB moved `vram_kv` byte-identical).
+3. Edit ONE knob (`GPU_HEADROOM_MIB`), deploy service-scoped: `./scripts/deploy.sh <host> --service <svc>`. The engine reloads everything (~2-4 min); the deployer's `LLM_WAIT` covers it.
+4. Re-read the ledger: `vram_kv` must be the new number, byte-exact or the knob lost to another claim; `mover: N slots can be lent` tells what the expert slab re-borrowed from the enlarged pool — that steal is the decode cost of the resize.
+5. Re-run the probe (`scripts/probe-frank-archon-kv.py`): depth 1.75x tokens, then the 2x refusal. Update `<svc>.md` Laws with the measured pair (tokens, given, backing %).
+6. Under-funded? Raise `HOST_POOL_MIB` in 1,024-MiB steps and redeploy; never touch demand to fake the number.

-## 2. Pool contract (the engine enforces it at REQUEST time, not boot)
+## Pinned-RAM ledger to recompute BEFORE booting (this is where a resize kills the host)
+`total_pin = tp * HOST_POOL_MIB + PLE/n-gram table + PREFIX_CACHE_MIB + (statics + arena ~2,048) + checkpoint_store`, with `checkpoint_store = slots * 111.98 MiB` and `--checkpoint-slots auto` = `max_num_seqs * (1 + what the retention policy keeps)` — **it grows with the slot count**, so a slot bump raises the pin ledger twice (state + store). The repo's bats guard recomputes this and asserts `TTM_MIN_MIB >= ledger`; when you change pool or slots, update `TTM_MIN_MIB` (and that guard) in the same commit, or the seam fails. The serve script's own gate refuses to start below `TTM_MIN_MIB`; `ttm-preflight.sh` raises the knob to `TTM_TARGET_MIB`, so the target must clear the new floor with slack.

-`pool_mib >= seqs*max_model_len*rate + 110*seqs + 448`
-
- rate/token/rank: **7,488 B fp8**, **14,144 B bf16** (1.89×, not 2× — the QSA
-  block key is 3.25 KiB at BOTH dtypes; it is an index, not attention state).
- +110 MiB a sequence of recurrent state (`kv_gdn_state` 54 MiB × 2 copies +
-  conv/tail/ple) and 448 MiB of prefix checkpoints, dtype-independent.
-
-A pool that fails this **boots, serves short chats, then 400s every long
-request** as `does not fit the 200000 token context, which leaves nothing to
-generate into` — radiance refuses, never truncates. Encode it as a bats gate.
-
-`--kv-cache-dtype` takes ONLY `bf16|fp8`, one dtype for the whole cache (no
-llama.cpp-style exact-K/quantized-V pair).
-
-## 3. Slab and KV are one budget; the slab is a SLOPE
-
- Idle KV VRAM is the expert cache's spillover: ledger
-  `mover: N slots can be lent out of the KV cache (X GiB)`. A bigger pool steals
-  residency twice over.
- Slab MiB ↔ resident experts is linear (~1,300 slots per 1,792 MiB measured);
-  the pinned host pool hands back the same slot count as the slab grows
-  (16,235→17,548 slab with 8,893→7,580 pool). The pinned RAM path is the slow
-  path, so slab MiB = throughput.
- Measured law (fp8, 43.5k single-stream, Qwen3.8-Flash-Next w4):
-  22,208 → 3,397, 24,000 → 3,290, 25,600 → **3,584**, 26,071 → **4,379 t/s**.
-  Two points inside the ±3 % noise band are NOT a plateau — never infer a
-  threshold from two arms.
- **Decode is a separate axis.** It follows KV dtype/bandwidth and draft
-  acceptance, not the slab: fp8/slab 26,071 decoded 124.1 t/s cold where
-  bf16/slab 22,208 decoded 94.1 (512 tokens, 51.5k). Slot count moves the
-  batch-shared per-stream floor (3 concurrent ≈ 6 t/s; solo ≈ 90–120).
-
-## 4. Verify: ledger first, then live probes (no scratch server)
-
-1. Deploy the service; read `podman logs <svc>`: `backs N sequences all at
-   M tokens at once` is the capacity referee; check slab slots, `unclaimed`,
-   `sampler: ... R rows` (= seqs × (1+spec), must stay inside the 25-row wht6
-   exactness bound), `settled at … free against … floor`.
-2. Boundary probe: N concurrent prompts sized to `max_model_len - gen`, each
-   with a unique marker at the head; expect N/N marker retrieval.
-3. Prefill/decode probe: repo `scripts/probe-frank-archon-kv.py` (reads the
-   shape from the deployed env, so it self-resizes).
-
-### Free token-count calibration (no prefill burned)
-
-`/v1/completions` refuses when **prompt tokens alone** exceed the window —
-`prompt: 202,777 prompt tokens does not fit the 200000 token context` — and the
-refusal names the count BEFORE any prefill. It does NOT fire on
-prompt + max_tokens. Corpus ratio measured: **2.7617 chars/token** (2.5714 for
-the fox filler), so a 200,000-token window ≈ 514,286–552,286 chars. Calibrate
-with a probe ABOVE the window; below it the request is accepted and pays real
-prefill (~22 s).
-
-### Probe traps that produced false results
-
- Generate **≥128 tokens** (512 preferred) for any decode number; at 8–9 tokens
-  `inter_token` is first-token noise — rates like 92.7 vs 85.8 are noise.
- Radiance `timings` can carry `null` rates — `(t.get(k) or 0)`, and
-  `j.get("timings") or {}`.
- The disk prefix cache (64 GiB) survives restarts; put a random nonce at the
-  HEAD of a "cold" prompt. A warm 197k prefill returns in ~10 s and looks like
-  a 60,000 t/s miracle.
- With thinking enabled, a small `max_tokens` yields empty `content` +
-  `finish_reason: stop` on a healthy server; set
-  `chat_template_kwargs.enable_thinking=false` in probes.
- `echo ===` in an ssh'd zsh dies on `=`-expansion; it silently truncates the
-  command chain.
-
-## 5. Ship
-
-`scripts/<svc>.env` pair + header, serve-script header, bats gates (pair ≤
-ceiling; pool ≥ contract), docs (runbook, `AGENTS.md` fleet row, LLM index,
-log.md), `./tests/run.sh`, `deploy.sh <host> --service <svc>`, then the probes.
-Record every prediction as falsifiable in the env comment and write the verdict
-there when the probe lands — including when it kills the prediction.
+## Traps
+- The cache is ELASTIC: the ledger's `kv cache` line is the ceiling, and `mover: ... slots can be lent out of the activation arena` (987 MiB) means the slab borrows arena first, then cache blocks. A bigger ceiling only helps if the heat engine stops re-borrowing it — check `flex_bytes`/`flex_capacity` movement after load, not just the budget line.
+- A resize that shrinks the pool mid-session preempts live sequences (`vllm:num_preemptions_total` jumps); a resize that grows it cannot retroactively un-preempt. Deploy at low traffic.
+- Do not resize the KV pool AND the expert placement in one deploy: the `experts` and `kv cache` lines move together and the attribution dies.
+- The `claimable` arithmetic (`capacity`) is computed ONCE before allocation; `card total` differs per card (26.0 vs 26.68 GiB on dankserver), so the SLOWER card's number is the budget — read the `[0]` and `[1]` `pools:` lines separately, not just the shared budget table.
@@ -0,0 +1,60 @@
+---
+name: react-prod-state-mismatch-bisection
+description: Diagnose React SPA prod-build state mismatches (state-derived props update but sibling output stays stale) by driving a real browser and bisecting per-render state via throwaway source instrumentation.
+---
+
+# Prod React state-mismatch bisection
+
+Use when a built SPA shows an internally inconsistent DOM — e.g. `aria-current` flips
+while a sibling conditional slot stays stale, a click handler runs with zero network
+activity, jsdom tests pass but the prod journey fails. Reasoning from source fails
+here; only per-render state truth resolves it.
+
+## Steps
+
+1. **Drive the real browser, not tests.** Throwaway `@playwright/test` chromium script
+   beside the package that installs it (e.g. `tests/`), seeded via direct API calls +
+   cookie injection:
+   ```js
+   import { chromium } from "@playwright/test";   // resolve from tests/ node_modules
+   const ctx = await browser.newContext();
+   await ctx.addCookies([{ name, value, domain: "127.0.0.1", path: "/" }]);
+   page.on("console", ...); page.on("pageerror", ...); page.on("request", ...);
+   ```
+   Run it from that directory; a script at repo root or /tmp hits
+   `ERR_MODULE_NOT_FOUND` for workspace deps.
+
+2. **Fiber prop probe** — call the handler outside React events to split
+   "delegation dead" from "handler wrong", and read the props the fiber holds:
+   ```js
+   await page.evaluate(() => {
+     const el = document.querySelector('[data-testid^="thing-"]');
+     const key = Object.keys(el).find((k) => k.startsWith("__reactProps$"));
+     el[key].onClick();          // or .onChange({target:{value:"x"}})
+   });
+   ```
+
+3. **If props updated but output is inconsistent, suspect falsy-equality, not React.**
+   `undefined === undefined` yields `"true"` for `el.id === selectedId` highlights —
+   a fake "state updated" signal. Dump the slot's raw `innerHTML`, don't trust the
+   derived attribute.
+
+4. **Instruments beats deduction:** insert temporary `console.log`s in the component
+   source (one in each state-mutating callback, one at render logging the state),
+   rebuild, restart the server, re-run the script. Compare *per-render* values — the
+   render where the value is `undefined` instead of the id names the root cause
+   (usually a server payload keyed differently than the client type, e.g. DB row key
+   `orgId` crossing HTTP where the contract says `id`).
+
+5. **Also grep every suite teardown for broad `DELETE ... LIKE`/`TRUNCATE` on the
+   shared DB when a test flakes only under uncached concurrent runs
+   (`turbo run test --force`) and passes isolated:** parallel vitest files on one DB —
+   the suite that finishes first FK-cascades away the other's live sessions; the
+   symptom is a spurious 401 (or missing row) in the still-running file. Fix by
+   namespacing emails/ids per suite and scoping teardowns to rows the suite created.
+
+## Cleanup
+
+Remove instrumentation, move the throwaway script to `.AGENTTRASH/`, never commit the
+debug script. Verified on franksign: `GET /api/orgs` leaked `orgId` where the client
+contract was `id` (fake aria-current true, silent auto-select failure).
@@ -0,0 +1,35 @@
+---
+name: real-pdf-acroform-census
+description: "Census a real-world PDF before running it through a flat→AcroForm pipeline: check for hidden widget layers, prove fill/flatten, avoid the pdfinfo ghost."
+---
+
+Census recipe for a real-world PDF arriving at a flat-form pipeline (e.g. franksign's sidecar that injects AcroForm widgets). Run BEFORE assuming the document is flat.
+
+## Sequence
+
+1. **Metadata**: `pdfinfo file.pdf` — note `Form:` line, producer (`macOS ... Quartz PDFContext` = Preview/Preview-era export), page size.
+2. **Text layer**: `pdftotext -layout file.pdf -` — underscore rules (`____`) look "flat".
+3. **Widget census (the decisive probe)** — never trust the looks:
+   ```bash
+   podman run --rm --entrypoint python -v ~/Downloads:/in:z <sidecar-image>:local -c "
+   import pymupdf
+   d = pymupdf.open('/in/file.pdf')
+   for p in d.pages():
+       for w in p.widgets():
+           print(w.field_name, w.field_type_string, [round(v) for v in w.rect])
+   print('annots:', sum(1 for p in d.pages() for _ in p.annots()))
+   ```
+   Traps: a custom ENTRYPOINT script swallows `python` as argv — override with `--entrypoint python`. Mount a directory, not a single file (MuPDF atomic-save EBUSY).
+4. **Fill live-fire**: pass the file through the fill step as-is with placeholder values; verify with `pdftotext -layout` that values land on the rules.
+5. **Flatten audit**: re-run the widget census on the output (expect 0) — do NOT read `pdfinfo`.
+
+## Laws learned
+
+- macOS Preview/Quartz exports (and most print-to-PDF paths) **already embed AcroForm widgets** under transparent rects over their drawn underscore rules. Field names are human-meaningful (`date_today`, ...). Injecting widgets over them duplicates/shadows fields — the design-time injection stage must be skipped when a widget layer exists (widget-first detection).
+- pdf-lib `flatten()` removes every **widget** but leaves the AcroForm **field dictionary**: `pdfinfo` keeps printing `Form: AcroForm` on a fully flattened file. Widget enumeration (MuPDF) is the only truth; pdfinfo is the ghost.
+- Underscore rules in the text layer are drawings, not fields; the text layer alone cannot tell flat from widget-bearing.
+
+## Verdicts
+
+- Widgets present → fill as-is; detection spec = widget layer (names, types, rects; flip top-left→bottom-left origin if the pipeline spec uses bottom-left).
+- Zero widgets → true flat form; needs position detection (underscore runs + nearest preceding label) before injection.
@@ -0,0 +1,49 @@
+---
+name: recover-externally-reverted-file
+description: "Rebuild a worktree file that an external process (stale editor buffer, watcher) keeps reverting mid-session: idempotent script rebuild, verify, immediate commit, cat-file restore instead of checkout."
+---
+
+# Recovering a File an External Process Keeps Reverting
+
+Symptom: edits to one file flip-flop under you — grep/wc/read return two different
+versions minutes apart; tool edit warnings say "file modified externally" repeatedly;
+committed content disagrees with reads of the same path. Typical cause on Frank's
+boxes: an IDE window with a stale buffer auto-saving the old version, or another
+agent's git operation in a sibling worktree.
+
+## Procedure
+
+1. **Stop editing surgically.** Line-anchored `edit` calls are unsafe when the disk
+   identity of the file is unstable. Take one snapshot:
+   `cp <file> /tmp/obs1.bats` (twice, a few seconds apart; differing hashes confirm the flapping).
+2. **Write an idempotent rebuild script** (`/tmp/rebuild-*.py`) that transforms
+   whichever known version is on disk into the target:
+   - every patch is `sub_if_present(pattern, exact_replacement)` /
+     `insert_before(anchor, block)` / `insert_after(anchor, block)`;
+   - each helper first checks whether the block is already present and skips;
+   - anchors must be taken from the committed/original file text, re-grepped,
+     never from memory of an edit that may have been reverted;
+   - print `ok/skip/FAIL` per patch so a mismatch is visible.
+3. **Apply + verify + commit in ONE bash invocation**:
+   `python3 /tmp/rebuild.py && <syntax check e.g. bats -c / tsc> && git add <file> && git commit ...`
+   The commit is the stable artifact; the disk is not.
+4. **Restore from git without checkout** (workspace policy blocks `git checkout/reset`
+   in shared checkouts): `git cat-file blob HEAD:<path> > <path>`.
+   Never `git checkout -- <path>` blindly — it silently nukes uncommitted work.
+5. **Run consumers immediately after the restore/commit** (tests etc. in the same
+   invocation where practical); re-check content with one hash compare
+   (`md5sum <path>; git cat-file blob HEAD:<path> | md5sum`) when results look impossible.
+6. If duplicates crept in from double-application (flapping + reruns), dedupe by
+   occurrence span (`src.find(marker)` twice, cut the second span) — full-block dedupe
+   fails when the two copies differ in a byte of comment text.
+
+## Distinguishing real failure from flapping evidence
+
+If a test fails, re-run the exact command once before believing it: the failing read
+may have run against the reverted file, not the committed one. Verify what the runner
+saw (`git hash-object <path>` vs `git rev-parse HEAD:<path>`).
+
+## Afterward
+
+Flag the reverter to the user (open editor buffer / watcher / sibling agent); do not
+fight it — commits and cat-file restores make it harmless.
@@ -1,28 +1,27 @@
 ---
 name: recover-subagent-yield-payload
-description: "Recover a subagent's full structured report when it exited without yielding (SYSTEM WARNING) — extract aborted yield payloads from the session JSONL, including harness double-encode and split-JSON quirks."
+description: "Recover or salvage subagent deliverables: missing yields, payloads misrouted to xd://report_issue, and degraded TAKEN-list echoes."
 ---

-Use when a subagent ends with "exited without yielding" yet the transcript shows it repeatedly calling `yield` (each reply "…[+N]" — payload too big for display). The research is usually COMPLETE; only the yield serialization failed. Known harness quirk: the yield `arguments` get wrapped as `{"data": "<json string>"}`, so an object payload is validated as a string → "expected object, received string" retry loop until the agent dies.
+# Recovering subagent deliverables

-## 1. Locate the session JSONL
-Transcript header prints the path: `~/.omp/agent/sessions/<cwd-slug>/<session-id>/<AgentName>.jsonl` (worktrees: cwd slug like `-.omp-wt-wt-...`).
+Three failure modes seen with scout bulk-content tasks, in order of frequency.

-## 2. Extract every aborted yield payload (Python via eval — shell quoting will mangle these)
- Parse each line with `json.loads` guarded by try/except (lines may be non-JSON).
- Keep `message.role == "assistant"` messages; in `content`, keep entries with `type == "toolCall"` and `name == "yield"`; collect their `arguments`.
- Unwrap: `arguments` may be a dict containing `data` (a JSON string) or a plain string; `json.loads` it.
+## 1. Misrouted payload: scout wrote the deliverable to `xd://report_issue`
+Symptom: yield summary says "delivered to `xd://report_issue`" instead of containing the content. That device is write-only (a bug-report channel); the response "Noted, thanks!" fooled the scout into thinking delivery worked.

-## 3. Tolerate broken JSON
-Naive `json.loads` on `data` can fail "Extra data: line 1 column ~4600" — the payload is a complete object followed by `, "architecture": ..., "report": ...}` (agent emitted a structure whose early brace-closure ended the first object). Recover with `json.JSONDecoder().raw_decode`:
-1. `part1, end = dec.raw_decode(data.strip())`
-2. `rest = data[end:].strip()` — if it starts with `,`, parse `part2 = dec.raw_decode('{' + rest.lstrip(', '))[0]`
-3. `merged = {**part1, **part2}`
-Do this for ALL yields and keep the largest merged dict (attempts evolve; keys seen: `summary`, `files`, `report`, `architecture`).
+**Salvage path (often impossible — decide fast, ≤2 probes):**
+- Transcript jsonl: `~/.omp/agent/sessions/*/*/Tan-*/Tan-*.jsonl` (glob by agent id).
+- Streamed `toolCall` blocks store only **partial arg fragments** of big writes (`arguments.content` is chunked/empty; `partialArgs` holds deltas). Reassembly of a 140-line write across ~100 fragment rows has never worked — if `content` on the toolCall rows is empty or truncated, **abandon salvage**.
+- Only reliable in-file content: final assistant text blocks — walk rows for `message.role=="assistant"`, `content[].type=="text"`, filter lines against the delivery contract regex.

-## 4. Persist and deliver
-Write the recovered `report`/`summary` to a durable file (memory dir or `local://`), then continue synthesis — never re-run the research the dead scout already did.
+**Prevention (put in scout prompts for bulk content):** "Return the deliverable as plain lines in your FINAL OUTPUT TEXT. NEVER write it to `xd://report_issue`, files, or eval state."

-## Prevention (do this first next time)
- While the agent is still alive and looping: write to `agent://<Name>` steering it to "yield immediately, wrap in minimal object or raw markdown, schema-invalid yield acceptable — I read the transcript anyway." It often still can't (the failure is in the harness wrapper, not the agent) → let it be killed and use the extraction above.
- Scout default schema wants objects; terse yields from `scout` agents hit this most. Keep expected reports slice-sized.
+## 2. Degenerate echo: scout returns the TAKEN/dedupe examples verbatim
+Symptom: candidate lines repeat the "already used" examples given in the prompt, in looping blocks. Write off that batch entirely — do not re-prompt (it repeats). Cover the cluster inline yourself.
+
+## 3. No yield at all (hung/force-stopped)
+`history://<agent-id>` renders the transcript but compresses tool payloads to "1 line" — useless for payloads, fine for status. Try `write agent://<id>` with a one-line re-emit instruction ("end your turn by yielding the lines verbatim; do not re-research") exactly once; if the reply is garbage, abandon.
+
+## Rule of thumb for bulk creative content
+Scouts add value for *terminology research* (search the universe's rank/offices vocabulary, 2-5 searches), not for drafting hundreds of lines — models echo, spin variants ("dune-mentat of the X" ×14), and misroute. Pattern: scout researches → parent drafts.
@@ -0,0 +1,44 @@
+---
+name: rescue-loose-home-scripts
+description: "Promote a durable loose $HOME script into dank/command-center: archive-first, black-box bats red-first with env seams, docs page + index + log entry, one atomic commit per instrument, PR to main."
+---
+
+Rescue a throwaway-looking `$HOME` script into the command-center repo as a maintained instrument. Used for `remote-job.sh` + `scripts/probes/*.hip` (PR #54, Refs #53); the archive still holds ~120 candidates.
+
+## 1. Archive first, never delete
+
+Loose scripts at `$HOME` root move to `~/.AGENTTRASH/home-scripts-<date>/` (`rm` is forbidden; deletion is a pruning session with Frank). Consolidate bulk media separately (`~/audiosamples`). Then check the archive for **instruments**, not convenience: something that answers a question you will ask again, or that carries a trap you paid for.
+
+## 2. Tests first, and black-box
+
+Write `tests/<name>.bats` before the script; confirm red (`bats tests/<name>.bats` → all `not ok` because the script is absent).
+
+- Assert **output, exit codes, and on-disk ordering** only — never internals, never "variable X equals Y".
+- A test that asserts a race outcome (file exists immediately after a detached `start`) is wrong: assert the *contract* instead (`status` reports RUN/PENDING and exits 1). Rewrite the test, not the code, when the failure is your own assumption.
+- Design env seams **so the untestable path becomes testable off the target hardware**: `*_SYSFS`, `*_KFD`, `*_HIPCC`, `*_SRC`, `*_BUILD`. A refusal that can only be exercised on a card box is an untested refusal. Stub the toolchain in `$PATH`/via env to drive build-failure and busy-device paths.
+
+## 3. Safety law in the tool, not the docs
+
+Anything that measures a GPU must **refuse before it builds or runs** when the device is busy (`gpu_busy_percent` over threshold, or any process holding `/dev/kfd`) and must **stop nothing**: unloading a production endpoint is a human decision (`--force`). Pin the refusal-before-build ordering in a test — otherwise a reordered guard silently reintroduces contention beside a live service.
+
+Exit-code taxonomy worth reusing: `0` did the work · `2` usage/missing inputs · `3` refused (would have contended) · `4` toolchain/build failure. A client box without the SDK must exit 4 loudly, never report an empty success.
+
+## 4. An instrument that crashes is not an instrument
+
+`hipGetDeviceProperties` **segfaults** on the fleet's ROCm build while `hipGetDeviceCount` works fine. The shipped probes called it only to print device name + PCI bus id — replaced by the sysfs topology block the driver prints (`current_link_width`/`current_link_speed` vs `max_*`). Record the trap as a comment in the sources so it is not reintroduced.
+
+## 5. Docs, three places, in the same commit as the code
+
+- `omp-docs/tools/<name>.md` — frontmatter per OKF (`type: reference`, title, description, tags, `verified`, `timestamp`); sections: contract (command table + exit status), the law + why, how to read the output, failure-modes table, test seams. Point-of-use only: measured numbers do **not** live here (they belong with the endpoint's runbook vault).
+- `omp-docs/tools/index.md` — one alphabetical bullet per page.
+- `omp-docs/log.md` — dated entry above the newest one: what changed + the durable laws, a few lines.
+
+Gates before commit: `bash scripts/kb-lint.sh` (0 violations) and full `bats tests/` green.
+
+## 6. Land it
+
+One commit per instrument (stage that page's index line only — re-add the next page's line for its own commit), message = imperative what + why + `Refs #N`, hooks armed (never `--no-verify`). Push to the local Gitea, open the PR with `gitea-pr-api-cycle` (token from `~/.config/secrets/gitea` via curl `-K`; body ends with `---` then `cwd: <session cwd> · session: <live transcript UUID>`), then `xdg-open <PR-URL>`. **Never merge without Frank's explicit OK.**
+
+## 7. Report the gap you could not close
+
+Verification on a client box proves the guard/refusal/usage paths only. If compile-or-run needs the hardware box, say so in the PR under "Not done here" and offer the exact low-risk command rather than implying the artifact is proven.
@@ -0,0 +1,39 @@
+---
+name: rng-pool-sweep-blackbox-test
+description: "Prove membership/absence in a randomly sampled pool (epithets-style) from black-box tests: prime-cycled Math.random sweeps every index; pool-first probe for setting precedence."
+---
+
+# Deterministic pool sweeps for random-sampling black-box tests
+
+When a built bundle samples uniformly at random from a curated pool (epithet-style) and tests must prove a setting admits/excludes whole classes of pool entries, do NOT write probabilistic sampling tests. Two proven designs:
+
+## 1. Full-pool sweep (class membership, distinct counts)
+
+In the test driver (the process that imports the built bundle), before firing utterances:
+
+```ts
+let seed = 0;
+Math.random = () => (seed++ % PRIME) / PRIME; // PRIME > pool size, e.g. 1009
+```
+
+The extension calls `Math.random()` at speak time, so the patch applies regardless of import order. Picks are `floor(random * poolSize)`; with N=PRIME samples the step is `< 1`, so **every index of every pool ≤ PRIME is visited exactly once**. Observable per-utterance text (e.g. the fixture server logs the synthesized `input=`) then reveals the entire sampling pool:
+
+- distinct picks == pool size exactly (pin the total only if it is itself law);
+- a sentinel name from class X appears / must never appear per mode — deterministic, zero flake;
+- absence proofs are exhaustive, not lucky.
+
+Drive one narration per iteration and gate the loop on the fixture's call counter advancing (`while (speechCount() < before + expected) await nap(2)`), otherwise typed/coalescing paths collapse iterations and counts drift.
+
+**Wall-clock budget:** one sweep ≈ 20–40 s per pool; bats serializes and jobs cap at 600 s — run at most two sweeps per backgrounded bats `-f` selection, or launch full suites with `timeout: 0`.
+
+## 2. Pool-first probe (setting precedence, milliseconds)
+
+With the same patched RNG, the FIRST pick is `pool[0]`. Run each config mode with exactly one utterance and compare the first spoken name:
+
+- mode-A setting vs env-mode-A → equal (settings key honored);
+- env-X overriding file-Y → equals env-X's pick (precedence law);
+- pick strings are pool literals that live in exactly one class (e.g. `comrade operator`).
+
+Avoid: regex scans over spoken text (possessives/compounds false-fire), probabilistic "absent in 300 samples" tests (flake floor unless the block is contiguous), and reading source internals (white-box).
+
+Red-first check: the sweep test for a not-yet-filtered pool must fail by SPEAKING the forbidden sentinel — if a "new mode" test passes pre-implementation, the probe accidentally tautologized (e.g. old pool[0] == new pool[0]); pick probe literals whose values differ between old and new behavior. Beware bats `setup()` rebuilding the bundle per test file: a long first sweep lets mid-session src edits leak into later tests' "red" proof — prove red from a pristine tree before implementing.
@@ -0,0 +1,65 @@
+---
+name: rootless-to-root-quadlet-journal-read
+description: "Convert a rootless Podman Quadlet (e.g. Alloy) to a ROOT system service so it can read the host journal — the machine-id mount, Network=host for loopback-published Loki, root image mirror, and the user-unit cutover. Use when an sd_journal/loki.source.journal reader ships zero lines with a green health check."
+---
+
+# Rootless→root Quadlet so a container can read the host journal
+
+Symptom: a rootless Quadlet that scrapes the systemd journal (`loki.source.journal`,
+any `sd_journal` reader) ships **zero** lines — silently, `health` green,
+`loki_source_journal_*_lines_total 0`, no error in the log.
+
+## Why (proven)
+- Journal files are `root:systemd-journal 0640` (`group:adm`, `other::---`). A rootless
+  container spawns with no supplementary groups → `sd_journal` opens an empty view.
+  Proof a rootless read is denied: `podman run --rm -v /var/log/journal:...:ro busybox
+  cat /var/log/journal/*/*.journal` → `DENIED`.
+- Rootless Quadlet **container** logs also live in `user-<uid>.journal` (journald log
+  driver), not `ctr.log`. A system-journal-only read misses them.
+
+## The shape that works (root, not rootless)
+Run it as a **root system Quadlet** (`/etc/containers/systemd/<svc>.container`,
+`WantedBy=multi-user.target`). Root's DAC override opens every journal file, so one
+`loki.source.journal` reads `system.journal` **and** `user-*.journal` together.
+
+Four load-bearing bits (all validated on Dankclaw Alloy 2026-10-20):
+1. **`Volume=/etc/machine-id:/etc/machine-id:ro`** — the single biggest gotcha.
+   `sd_journal` locates the journal dir by the *local* machine id; without it the
+   container opens **nothing** and reads exactly 0 lines, health green. A root probe
+   without it = 0; with it = 31,825 lines in 20s.
+2. **`Network=host`** — if the sink (Loki) publishes `127.0.0.1:3100` (loopback), no
+   bridge container (root or rootless) can reach the host loopback; `host.containers.internal`
+   and the LAN IP are both refused. Host network + push to `http://127.0.0.1:3100`.
+   Side effect: bind the app UI to `127.0.0.1` (no `PublishPort`) so it stays loopback-only.
+3. **`/var/log/journal` + `/run/log/journal`** mounted `:ro`.
+4. **Image must be in the ROOT store.** A root `podman build` runs in the build
+   container's own resolver and fails DNS here. Build rootless, then mirror:
+   `podman save -o t.tar <ref> && sudo podman load -i t.tar`. Compare image ids so a
+   rebuild actually re-lands (stale root tag is a silent footgun).
+
+## Deployer cutover (retire the rootless unit FIRST)
+Both the user and system managers generate `<svc>.service`; two containers named
+`<svc>` both binding the same loopback port cannot coexist. Before starting the system
+unit: `systemctl --user stop <svc>.service`; `mv` the user quadlet out of
+`~/.config/containers/systemd/` (it regenerates from there) to `~/.AGENTTRASH/<date>-<svc>-root-cutover/`;
+`systemctl --user daemon-reload`. Then install to `/etc/containers/systemd/`,
+`sudo systemctl daemon-reload`, `sudo systemctl restart <svc>.service`. Generated
+(system) units cannot be `enable`d here — boot persistence is the `[Install]` section.
+
+## Probe the exact command BEFORE writing the unit
+`sudo podman run --rm --net=host -v /etc/machine-id:...:ro -v journal mounts
+  <image> run --server.http.listen-addr=127.0.0.1:<free-port> <config>` — pick a FREE UI
+port (the deployed instance already owns the real one; a bind conflict reads as
+"reads 0 lines", not "port in use"). A squashed one-line River/HCL block is invalid —
+attributes need newline terminators, or the probe dies before reading anything.
+
+## Verify (query gotchas that caused false "empty" reads)
+- `loki_source_journal_target_lines_total` must climb.
+- Loki `/loki/api/v1/query_range` returns `values` as `["<ts_ns>","<line>"]` **arrays** —
+  grep `"ts"` finds nothing; the data is there. `/series` defaults to a short index window
+  and can read empty while recent data is queryable. Use a wide `start`/`end`, no `direction`.
+- A fresh journal reader replays the whole persistent journal from the oldest; Loki
+  `reject_old_samples` + the per-tenant rate limit discard old/throttled entries
+  (`loki_discarded_samples_total{reason="rate_limited"}`) without counting as writer
+  drops. It self-clears once it reaches the tail; raise the ingestion rate to speed it or
+  start at the head to skip.
@@ -0,0 +1,41 @@
+---
+name: rotate-fleet-service-host-secret
+description: "Rotate a Dank-fleet rootless-quadlet service's host-side secret (e.g. open-notebook OPEN_NOTEBOOK_PASSWORD) safely: confirm the deployer's secret seeder is idempotent first so a future deploy won't clobber the new value, change ONLY the target line while holding encryption keys byte-identical, then restart the user unit and prove the rotation (new token 200, old token 401, no token 401). Not for git/Gitea tokens or LLM endpoint secrets."
+---
+
+# Rotate a fleet service's host-side secret safely
+
+Host secrets live OUTSIDE the repo, in `/home/dank/Containers/<svc>/env` (mode 600). The repo only holds the knobs (`scripts/<svc>.env`, secrets declared EMPTY). Changing a secret = edit the host file, never the repo.
+
+## 1. First: prove the deployer won't clobber it (MANDATORY)
+`deploy-remote.sh` seeds some secrets from `dankclaw/.env`. Confirm the seed fn is **idempotent** before editing, or a later `deploy.sh` overwrites your value. In `scripts/deploy-remote.sh`, `seed_<svc>_env` must look like open-notebook's:
+
+```bash
+for var in A B C D; do grep -q "^${var}=." "$dest" 2>/dev/null || missing=1; done
+[[ "$missing" == 0 ]] && return 0          # all present → leaves the file untouched
+if [[ ! -e "$dest" ]]; then ...seed from dankclaw/.env...; fi
+```
+
+If it returns-early on all-present, editing `$dest` directly is deploy-safe. If it seeds unconditionally, edit BOTH the host file and `dankclaw/.env` instead.
+
+## 2. Read, then rewrite only the target line
+`read ssh://<host>/home/dank/Containers/<svc>/env` (never print secrets to chat — they leak into the transcript). Then `write ssh://...` overwriting with **all** lines, changing only the one secret. **Hold encryption keys byte-identical** (e.g. `OPEN_NOTEBOOK_ENCRYPTION_KEY`): a DB-encrypted credential store is unreadable if that key changes. Then `chmod 600`.
+- ssh:// `read` emits NO edit tag, so the `edit` tool can't target it — use `write` (full overwrite) with the exact values from the read.
+
+## 3. Restart the right unit
+Rootless quadlets are USER units: `ssh <host> systemctl --user restart <svc>.service`. (systemctl --user works over plain ssh here — linger + bus are set up.) Restart only the app unit; DB password unchanged means the DB unit needs no restart.
+
+## 4. Prove the rotation behaviorally (this is the smoke test)
+Hit a protected API route three ways, expecting **new=200 / old=401 / none=401**. Pass the bearer via a mode-600 curl config + `-K` (never `-H "Bearer …"` — argv leak):
+
+```bash
+ssh <host> 'cfg=$(mktemp); chmod 600 "$cfg"
+printf "header = \"Authorization: Bearer %s\"\n" "<new-or-old>" > "$cfg"
+curl -s -o /dev/null -w "%{http_code}\n" -K "$cfg" http://127.0.0.1:5056/api/<protected>'
+```
+
+## Gotchas that bit
+- **Health is on the API loopback port, not the web port.** open-notebook: `/health` answers on **127.0.0.1:5056** (the FastAPI), NOT `:8502` (Next.js, which 404s `/health`). Probing the wrong port reads as "service failed" when it's up and `healthy`. Excluded/auth-free paths (`/`, `/health`, `/docs`, `/openapi.json`, `/redoc`) — everything else needs the bearer.
+- **`OPEN_NOTEBOOK_PASSWORD` unset = auth OFF** for anything that can reach the port (other containers dial it by name on `dankclaw_default`), so it's mandatory, not cosmetic; deployer refuses to start on blank.
+- Browser/clients keep the old secret in localStorage → they 401 on next call and re-prompt. Expected.
+- **Harness command-parser gotcha:** adjacent/interleaved single+double quotes in one bash line (`'...'"$x"'...'`) crash `pi-natives:command: unterminated quote`. Build a curl-config `header=` line with the proven single-quoted printf (`printf 'header = "Authorization: token %s"\n' "$tok"`) and put long bodies in a file via the `write` tool + `jq --rawfile`, not a giant inline `$(printf …)`.
@@ -0,0 +1,61 @@
+---
+name: run-e2e-specs-from-isolated-worktree
+description: "Run serverAppConfigs Playwright e2e specs against the live fleet from a feature branch when git checkout is workspace-policy-blocked — isolated worktree + symlinked deps, with the variadic --project and gitignored-auth traps."
+---
+
+## When
+
+You are authoring/verifying a `tests/e2e/*.spec.ts` change for `dank/serverAppConfigs` and the shared workspace blocks `git checkout` / branch switch (concurrent-agent safety). You must run the new specs against the LIVE fleet (they are guard-chain tests: Anubis PoW + authentik outpost + app) but a fresh worktree has no `node_modules`, no `.auth`, and no `.env.local`.
+
+This is NOT `deploy.sh` (which runs the full e2e gate itself from the main-tracking checkout — see `serverappconfigs-deploy-execution-context`). Use this to iterate/verify individual specs on a branch before opening a PR.
+
+## Setup the worktree
+
+The main deploy checkout (has the deps + auth state) is `/home/blank/Projects/serverAppConfig`. Branch off `origin/main` into a throwaway worktree:
+
+```bash
+git -C <repo> worktree add -b feat/<topic> /tmp/wt-<topic> origin/main
+ME=/home/blank/Projects/serverAppConfig/tests/e2e
+ln -sfn "$ME/node_modules" /tmp/wt-<topic>/tests/e2e/node_modules
+cp -r "$ME/.auth"          /tmp/wt-<topic>/tests/e2e/.auth
+cp    "$ME/.env.local"     /tmp/wt-<topic>/tests/e2e/.env.local   # gitignored
+```
+
+- **`.env.local` is mandatory** — without it the config throws `missing E2E_STANDARD_USER — set it in tests/e2e/.env.local or the environment` at load, even for `--list`. It is gitignored (a bats seam forbids tracking it), so a fresh worktree never has it.
+- `.auth` holds `qa-e2e.json` / `qa-e2e-admin.json` (the `standard`/`admin`/`guest` storage states); copying it avoids re-login, though the `setup` project refreshes it anyway.
+- The node_modules symlink resolves fine for playwright.
+
+## Validate wiring before running
+
+```bash
+cd /tmp/wt-<topic>/tests/e2e && npx playwright test --list
+```
+
+Confirms your new spec's NUMBER PREFIX is matched into a project. **A spec whose prefix is not in any project's `testMatch` silently never runs** — a green suite with a test that does not exist. The gate is the bats seam `tests/e2e_scaffold.bats` → "every e2e spec is matched by a playwright project". So a new spec `21-foo.spec.ts` MUST also edit `playwright.config.ts`'s `standard` (or other) `testMatch: /(10|12|...|21)-.*\.spec\.ts/`.
+
+## Running — the `--project` trap
+
+`--project` is **variadic**: the space form swallows the positional filters as extra project names.
+
+```bash
+# WRONG: "21-notebook" parsed as a second project → Project(s) not found
+npx playwright test --project standard 21-notebook 22-foo
+
+# RIGHT: equals form, then positional title/file filters
+npx playwright test --project=standard 21-notebook 22-foo
+npx playwright test --project=guest 14-guard -g "notebook.franksdank.cloud is gated"
+```
+
+`standard`/`admin`/`guest`/`frankbook` all `dependencies: ["setup"]`, so `00-auth.setup.ts` runs first and logs in the qa-e2e accounts (~24 s each). Expect ~50 s wall for a couple of specs.
+
+## Verify the spec is meaningful, not vacuous
+
+These specs prove the guard chain handed off to the **app**, so assert a positive app marker (title / app content string / the app's own API returning `status:"success"`), never just `status < 500` or "not the IdP shell" — the latter passes on a 404 or a parked login wall (the 13-sso / 17-hermes class of silent-green bug).
+
+## Cleanup
+
+```bash
+git -C <repo> worktree remove --force /tmp/wt-<topic>   # symlink + copied auth are throwaway; branch already pushed
+```
+
+Full `./tests/run.sh` (bats, incl. `e2e_scaffold`) must pass before commit; the deploy's own Playwright gate is the canonical live run after merge.
@@ -0,0 +1,30 @@
+---
+name: serverappconfigs-deploy-execution-context
+description: "Run scripts/deploy.sh for serverAppConfigs from the correct checkout: must be a clean dev-side main branch, never a feature worktree, and how to get there when the session worktree sits on another branch."
+---
+
+# Run scripts/deploy.sh from the correct checkout
+
+`deploy.sh` hard-refuses outside a clean `main` checkout (`FAIL: deploy.sh must run from the main branch.`, exit non-zero) — and this box has several serverAppConfigs checkouts.
+
+## The map (dev box, verified 2026-10-21)
+
+- **Canonical dev main checkout: `/home/blank/Projects/serverAppConfig`** — the ONLY place `deploy.sh` may run. It holds the `main` branch worktree (git refuses the same branch checked out twice, so session worktrees can never satisfy the gate).
+- `~/.omp/wt/wt-<...>` session worktrees: often parked on unrelated feature branches with uncommitted work — never deploy from here; do not `git checkout` here (workspace policy blocks it in shared trees).
+- `/tmp/wt-*` build worktrees: correct place to edit/test/PR, wrong place to deploy (branch != main by design).
+
+## Procedure
+
+```bash
+cd /home/blank/Projects/serverAppConfig
+git pull --ff-only origin main          # deployer must carry the merged commit
+./scripts/deploy.sh <target> --service <svc>
+```
+
+Merge lands on origin/main first — deploy runs AFTER the PR is merged (ff-pull picks it up). Each invocation costs ~2 min (e2e gate ≈ 1 min + health gates); chaining several `--service` runs in one bash call is fine, but background it (`| tail` per service) so the harness doesn't stall the turn.
+
+## Gotchas
+
+- `worktree add -b main /tmp/...` fails (`a branch named 'main' already exists` / `already used by worktree at /home/blank/Projects/serverAppConfig`) — that IS the answer: don't mint a main clone, use the canonical path. Prune leftovers: `git -C /home/blank/Projects/serverAppConfig worktree prune`.
+- The remote runner updates its OWN checkout (embedded ff-only pull before dispatch), so shipping a brand-new service handler works: the remote gate is evaluated against freshly pulled code. Only the CLIENT gate (deploy.sh `valid_service`) can veto a first-ever deploy — see skill `new-fleet-service-checklist`.
+- Bare `deploy.sh <target>` = fleet-wide drain (restarts every lagging service marker). Always `--service`.
@@ -0,0 +1,73 @@
+---
+name: shell-suite-green-locale-proof
+description: "Proving a bats/shell suite is actually green (grep, never tail) and debugging generated output that silently loses content under LC_ALL=C (multibyte quantifiers in awk/grep). Use when reporting \"suite green\", or when a generator emits partial output with exit 0."
+---
+
+# Proving a suite is green, and locale-blind generators
+
+Two failure modes earned on `dank/command-center` (2026-10-20): a false "all tests pass"
+report, and a generator that silently dropped a third of its output.
+
+## 1. Never report green from a `tail` window
+
+`bats tests/ | tail -25` shows the last tests, not the failures — `not ok` lines print
+inline at their position and vanish off the top. A "109 ok, 0 failures" claim built this
+way was wrong; the claim had to be corrected in the merged PR's body.
+
+```bash
+out=$(bats tests/ 2>&1)
+printf '%s\n' "$out" | grep -cE '^ok'        # passing count
+printf '%s\n' "$out" | grep -E '^not ok'     # THIS is the claim; empty == green
+```
+
+Also: a suite can be green under the operator's terminal and red under a C locale, so
+run both before writing "green" in a PR body:
+
+```bash
+env -u LC_ALL bats tests/    # operator's locale (LANG from the desktop session)
+LC_ALL=C bats tests/         # cron, systemd user units, agent shells
+```
+
+State which locale each number came from. Agent shells in this fleet run `LC_ALL=C`
+even when `LANG=en_US.UTF-8` — `LC_ALL` overrides everything.
+
+## 2. Multibyte quantifiers silently truncate generated output
+
+A quantifier on a multibyte character (`─+`, `━+`, `→*`) breaks under `LC_ALL=C`: gawk
+matches byte-wise, so `─+` means "the last byte of U+2500, repeated", which never occurs
+in real text. Symptom: output loses *every* match — sections, headers, rows — with
+**exit status 0**. No error, no partial-write warning.
+
+```bash
+# broken under C
+awk '/^[[:space:]]*\/\/[[:space:]]*─+ (.+) ─+[[:space:]]*$/'
+# byte-safe in every locale: match the multibyte char as a LITERAL, no quantifier
+/^[[:space:]]*\/\/[[:space:]]*─/ {
+  s = $0; sub(/^[[:space:]]*\/\/[[:space:]]*/, "", s)
+  if (s ~ /─ .*─/) { gsub(/─/, "", s); gsub(/[[:space:]]+/, " ", s) }
+}
+```
+
+Do NOT "fix" it by pinning a locale (`LC_ALL=en_US.UTF-8`) — that locale may not be
+installed; a CachyOS box here shipped only `C.utf8`. Make the matcher locale-independent.
+
+## 3. Prove the loss, don't infer it
+
+Diff old vs new against real input in both locales, with counts, before claiming a fix:
+
+```bash
+git show origin/main:scripts/gen-keybinds.sh > /tmp/old.sh
+for L in C C.utf8; do
+  printf '%s: old=' "$L"; LC_ALL=$L bash /tmp/old.sh "$REAL" | grep -c '^## '
+  printf        ' new=';       LC_ALL=$L scripts/gen-keybinds.sh "$REAL" | grep -c '^## '
+done   # old printed 0 sections vs 12 under C, 120 rows intact, exit 0
+```
+
+Check whether a *committed generated artifact* was produced by a bad run — if it has the
+full content, it came from a UTF-8 shell and needs no regeneration.
+
+## 4. Gates must not demand deletion
+
+Repo linters walking `.AGENTTRASH/` (quarantined, gitignored) turn green only once the
+quarantined page is deleted — an incentive to destroy history. Skip any path containing
+`.AGENTTRASH` in both the linter and the coverage checker, and pin it with a test.
@@ -0,0 +1,48 @@
+---
+name: single-work-log-bundle-rule
+description: "A bundle keeps ONE work log — the entry law, the one-file rule, and the kb-lint gate that fails a second log.md. Use before writing any log entry or creating log.md/NOTES.md/PROGRESS.md/worklog anywhere."
+---
+
+A bundle keeps ONE work log. Before writing any log entry, or creating any file named `log.md` / `NOTES.md` / `PROGRESS.md` / `STATUS.md` / `worklog/`, use this: the entry law, the one-file rule, and the `kb-lint.sh` gate that fails a second log. Law earned 2026-10-20 on `dank/command-center` PR #57, after an agent had once kept logs in fifty-odd files and none of them was the place to look.
+
+# One work log per bundle
+
+## The rule
+
+- **One file, at the bundle root.** In `dank/command-center` that is `omp-docs/log.md`. In another repo, the change-log page its docs index names. A subdirectory NEVER keeps its own log, and no run/branch/feature gets a private one.
+- **Write it in the same commit as the change it describes; read it before starting** to recover where things stand.
+- **Entry = what changed + the durable lesson, a few lines.** No per-file inventories, no run-by-run numbers, no transcripts, no re-expanding an old entry in place — `git log --follow <log>` is the transcript.
+- **No log page in the KB?** Add one at its root and list it in the index. That is the fix — never a log somewhere else.
+- Measured numbers in a log still have to pass the purpose test (`agent/APPEND_SYSTEM.md` § 1): a figure for a model/runtime/hardware config that is neither deployed nor being compared is dead weight — delete it, do not archive it.
+
+## The gate
+
+`scripts/kb-lint.sh` reports any `log.md` that is not the bundle root's:
+
+```
+a bundle has one work log, log.md, at the bundle root; found: core/log.md, log.md
+```
+
+`scripts/kb-coverage.py` enforces the other half of "one place to look": every directory has an `index.md` and that index links its siblings. Both gates skip any path containing `.AGENTTRASH` — quarantined pages are not bundle content, and a gate that only goes green once the quarantined copy is deleted is a gate that deletes history.
+
+Run both before committing a docs change:
+
+```bash
+bash scripts/kb-lint.sh omp-docs && python3 scripts/kb-coverage.py omp-docs
+```
+
+## Folding a second log in (the procedure)
+
+1. **Prove it is redundant, don't assert it.** Read the candidate: its entries are usually migration bookkeeping (file moved, directory created, log created) — every one recoverable from `git log`, so it carries no fact git lacks.
+2. **Check whether the copies disagree.** The two logs in command-center gave the same OKF conversion two different dates (2026-07-15 vs 2026-01-15) while git dated the rebuild 2026-08-28: duplicated logs do not preserve facts, they multiply errors.
+3. **Fix what pointed at it.** The stale page stays in circulation because an index links it — repoint `core/index.md` (or whichever index) at the root log in the same change.
+4. **Quarantine, never `rm`:** `mkdir -p <dir>/.AGENTTRASH && mv <dir>/log.md <dir>/.AGENTTRASH/log.md`, then `git add -A <dir>` so git records the deletion while the copy waits for a pruning session with Frank.
+5. **Write the entry in the surviving log**, law-first: what changed, then the durable lesson, then links to the spec pages now carrying the law.
+
+## Traps
+
+- The spec called `log.md` a *reserved* name and maintenance said every bundle "has one" — which reads as "any directory may have one". Reserved ≠ replicable; say **exactly one, at the root** wherever the spec is stated, or the sprawl regrows from the spec itself.
+- An OKF maintenance page teaching "one line per change with file path" (exampled as `/docs/ghostty.md — Updated keybind table`) produces manifests that duplicate git and absolute links the linter cannot resolve. Replace the instruction; do not add a second, conflicting one beside it.
+- Trashing a page turns gates red if they walk `.AGENTTRASH/` (frontmatter demanded of a quarantined page, an index demanded *for the trash dir*). Fix the gates; never delete the quarantined copy to go green.
+- Deleting the log file in a worktree does not preserve it: a copy moved into a gitignored `.AGENTTRASH/` inside a worktree is destroyed when the worktree is removed. Copy it to the deployment (or `~/.AGENTTRASH/`) before pruning.
+- Verify the rule is actually live in a fresh session — a subagent reading `~/.omp/agent/APPEND_SYSTEM.md` and quoting the law back proves the deployment, which the current session cannot do for itself (its prompt was built before the change).
@@ -0,0 +1,21 @@
+---
+name: verify-subagent-review-findings
+description: "Before presenting subagent code-review findings, mechanically verify each claim against the repo; scouts fabricate confident findings (fake spec quotes, misread listings, pre-diff code called new)."
+---
+
+# Verify subagent review findings before aggregating
+
+Parallel review subagents (standards/spec axes) return confident, fabricated findings. Never launder them into the report unverified. Observed failures: listing existing story files "as the missing ones"; quoting an unrelated log line as "the spec line"; flagging an endpoint that predates the diff range as scope creep.
+
+## Recipe (per finding, cheap mechanical checks first)
+
+1. **Existence claims** (missing file, missing story, missing endpoint): `ls` the directory / grep the route table. A passing repo seam that enforces the law (e.g. a pairing-law test that ran green today) disproves any "law violated" claim outright.
+2. **Newness claims** ("the diff introduced X"): `git log <fixed-point>..HEAD -S "symbol" --oneline` — empty result means the code predates the diff; the finding is out of scope. Also `git show <fixed-point>:<path> | grep -c symbol`.
+3. **Spec-quote claims**: the quoted text must appear in the actual issue/spec body fetched from the tracker. Fabricated citations discredit the whole finding — discard.
+4. **Behavioral claims** (X differs from Y): check for existing live proof (sha comparisons, test runs) before reporting.
+
+## Aggregate honestly
+
+- Report surviving findings only; list refuted claims in a marked "REFUTED" block with the disproving check — do not silently drop them (the user may have acted on the raw scout output).
+- If an earlier artifact of yours (issue comments, docs) repeated a now-refuted claim, correct it in place and note the correction.
+- Refutation cost is minutes: one `ls`, one `git log -S`, one grep of the spec body. Do it before, not after, the user trusts the report.
@@ -0,0 +1,41 @@
+---
+name: xdg-open-tab-proof-niri
+description: "Prove an xdg-open URL actually landed a tab in Frank's Firefox on niri, instead of reporting the law-compliant \"opened in your browser\" blind."
+---
+
+AGENTS.md (`dank/command-center`) requires opening every PR in Frank's browser with `xdg-open <PR-URL>`. `xdg-open` exits 0 whether or not a tab appeared, and its stderr is easy to swallow (`>/dev/null 2>&1 &`), so "opened in your browser" is normally an unverified claim. Prove it before saying it.
+
+## The proof that works
+
+```bash
+export XDG_RUNTIME_DIR=/run/user/$(id -u)
+export WAYLAND_DISPLAY=${WAYLAND_DISPLAY:-wayland-1}
+niri msg windows | grep -iA2 'firefox\|gitea\|pull'
+```
+
+Expected — the tab title is the page title, so it doubles as confirmation you opened the right object:
+
+```
+Title: "#61 - fix(#60): checks that lied… - command-center - Frank's Dank Gitea… — Mozilla Firefox"
+  App ID: "firefox"
+  PID: 1150647
+```
+
+## Why the obvious checks fail here
+
+- **The computer/AX window list does not list Firefox.** `computer.windows()` on this Wayland backend returned only ghostty windows — Firefox exposes no ATSPI top-level unless accessibility is already active inside it — so an empty list is **not** evidence the tab is missing.
+- `capture: false`, `displayCount: 0` in `computer.capabilities()` mean screenshots are unavailable (display asleep); a blank screenshot proves nothing either way.
+- `wmctrl -l` / `hyprctl` do not exist on niri. `niri msg windows` is the window census, and `niri msg outputs` is the output census.
+- `pgrep -af firefox` only shows the process tree (one parent + `-contentproc` children); a tab never appears there.
+- The web page itself is not proof: Gitea's `/dank/<repo>/pulls/N` HTML answers **404** without a session cookie even though the API and the browser both work.
+
+## Dispatch recipe (when nothing is running, or nothing landed)
+
+```bash
+XDG_RUNTIME_DIR=/run/user/$(id -u) WAYLAND_DISPLAY="${WAYLAND_DISPLAY:-wayland-1}" \
+  xdg-open https://gitea.franksdank.cloud/dank/<repo>/pulls/N
+```
+
+Give it the **`https://gitea.franksdank.cloud/…`** form, not the LAN `192.168.0.143:3000` form the API returns — that is the host Frank's bookmarks and cert expectations use. A running Firefox receives the URL as a new tab in the existing instance; re-dispatching opens a second tab, which is a cheap, idempotent way to recover from a swallowed failure.
+
+Related: `gitea-pr-api-cycle` (the API cycle whose final step this verifies), `omp-tui-live-visual-verify` (same rule for terminal UIs: observe the real surface).
@@ -1,4 +1,4 @@
 {
 	"v": 1,
-	"lastConsolidatedAt": 1792526055797
+	"lastConsolidatedAt": 1792557324990
 }
@@ -7,4 +7,8 @@

 ## Documentation Flow

- Put any created docs in the existing knowledgebase instead of creating a new one
+- Put any created docs in the existing knowledgebase instead of creating a new one
+
+## Log Organization
+
+- Logs kept explicitly to one file inside the knowledge base
@@ -1,8 +1,8 @@
 {
 	"v": 1,
-	"lastConsolidatedAt": 1792538189166,
+	"lastConsolidatedAt": 1792572225299,
 	"lastResult": {
-		"at": 1792537233005,
+		"at": 1792557082020,
 		"sessions": 1,
 		"deltas": 1,
 		"model": "frank-zealot"
@@ -0,0 +1,4 @@
+## Admin Side
+- Endpoints reside on the admin side
+- Loki is reachable
+- Ensure that prometheus is not firing off any more alerts
@@ -1,2 +1,6 @@
-## Handoff Location
- put it at ~/Projects
+## Variables
+- narrator1 = wilwheaton, narrator2 = vaati, narrator3 = dr.kern
+- frank-dragoon context = 200k
+
+## Dashboard
+- Dashboard includes GPU metrics
@@ -1,8 +1,8 @@
 {
 	"v": 1,
-	"lastConsolidatedAt": 1792538116812,
+	"lastConsolidatedAt": 1792572021650,
 	"lastResult": {
-		"at": 1792537164207,
+		"at": 1792571693973,
 		"sessions": 1,
 		"deltas": 1,
 		"model": "frank-zealot"
@@ -0,0 +1,4 @@
+## Templates
+- Template submissions proceed as an agentically-assisted process.
+## Agent Skills
+- 16 is a project level agent skill, rather than a strict application thing
@@ -1,4 +1,10 @@
 {
 	"v": 1,
-	"lastConsolidatedAt": 1792537985341
+	"lastConsolidatedAt": 1792572038693,
+	"lastResult": {
+		"at": 1792556461435,
+		"sessions": 1,
+		"deltas": 1,
+		"model": "frank-zealot"
+	}
 }
@@ -1,3 +1,7 @@
-## Documentation structure
+## Data flow
+- Information is dropped, not queued
+- Compaction applied
+- The suite shouldn't loop through every epithet

- Store agent-related docs in `dankvoice-docs`
+## Testing behavior
+- Tests play ONE random Epithet
@@ -1,10 +1,10 @@
 {
 	"v": 1,
-	"lastConsolidatedAt": 1792538005214,
+	"lastConsolidatedAt": 1792572210019,
 	"lastResult": {
-		"at": 1792537052571,
+		"at": 1792566095222,
 		"sessions": 1,
-		"deltas": 2,
+		"deltas": 1,
 		"model": "frank-zealot"
 	}
 }
@@ -0,0 +1,3 @@
+## Product Scope
+
+* allocate 4 slots with exactly 700k pool budget
@@ -0,0 +1 @@
+{"v":1,"kind":"correction","statement":"stop it! it works!","source":"explicit_user","evidence":"stop it! it works!","friction":{"corrective":true,"regression":true,"subtle":false},"sessionId":"01a15cbe-157e-7527-b4b5-22f3d2feea00","ts":1792563942225}
@@ -0,0 +1,10 @@
+{
+	"v": 1,
+	"lastConsolidatedAt": 1792563926234,
+	"lastResult": {
+		"at": 1792562981651,
+		"sessions": 1,
+		"deltas": 1,
+		"model": "frank-zealot"
+	}
+}
@@ -16,7 +16,7 @@ providers:
    auth: none
    models:
      - id: frank-archon
-        # Model id renamed from frank-archon on 2026-10-08 (official
+        # Model id renamed from frank-medium on 2026-10-08 (official
        # unit-name scheme; the systemd service, scripts and runbooks keep
        # the frank-archon name — service names are unchanged).
        # Server-side compaction routes to compaction.remoteEndpoint in
@@ -82,9 +82,11 @@ providers:
    auth: none
    models:
      - id: frank-dragoon
-        # Model id renamed from frank-dragoon on 2026-10-08 (official
+        # Model id renamed from frank-large on 2026-10-08 (official
        # unit-name scheme; the service/unit/scripts keep the frank-dragoon
-        # name — service names are unchanged).
+        # name — service names are unchanged). The pre-rename id is
+        # `frank-large`, recorded here because the callsign rename overwrote
+        # its own explanation and left "renamed from frank-dragoon".
        name: "frank-dragoon (dankclaw-gpu)"
        # Server-side compaction runs on the compaction.remoteEndpoint in
        # config.yml (192.168.0.143:7771 — frank-zealot's 3090); this steers the
@@ -111,31 +113,80 @@ providers:
        maxTokens: 45056
        reasoning: true
        # VISION ON as of 2026-10-06: the v2 vision tower loads beside the
-        # checkpoint (HALOGEN_VISION_TOWER; red-PNG probe verified on the
-        # card). image_url content parts only — the legacy top-level
-        # images field is the frank-zealot trap, do not repeat it here.
+        # checkpoint (HALOGEN_VISION_TOWER; priced at 0.8 GiB in the boot
+        # ledger, and re-probed 2026-10-21 — a 512 px solid-red PNG comes back
+        # "Red" at 282 prompt tokens). image_url content parts only — the
+        # legacy top-level images field is the frank-zealot trap, do not
+        # repeat it here.
        input: [text, image]
        compat:
          # flash-server emits thinking as `reasoning_content` — same
          # field as every engine this endpoint has run, no harness
          # change needed.
          reasoningContentField: "reasoning_content"
-          # Same Qwen3.8 template family (it ships inside the tokenizer
-          # bundle): any reasoning_effort outside {xhigh, medium, low} is
-          # rejected, not clamped — the fold stays mandatory.
+          # flash-server validates reasoning_effort against its own list and
+          # 400s anything else, naming it: "reasoning_effort 'maximum'
+          # unsupported; use minimal|low|medium|high|xhigh|max|none" (measured
+          # 2026-10-21). Every omp level is already spelled by the engine, so
+          # the map is identity — it exists to record that, not to fold. An
+          # earlier version rewrote high->xhigh and minimal->low to stop
+          # rejections that do not exist, and the rewrite asked the engine for
+          # a different thinking budget than the caller named. Levels really do
+          # differ here: thinking length on one prompt at max_tokens 2048
+          # measured low 766 tokens, xhigh 614, max 1049 with the block closed
+          # at 1024 (reasoning_closed_at). The harness passes an unmapped level
+          # through verbatim (`compat.reasoningEffortMap?.[effort] ?? effort`),
+          # so removing an entry is a pass-through, never a 400.
+          #
+          # `max` still does not reach the engine, and the map is not why: the
+          # harness clamps the requested effort to the model's own effort ladder
+          # before the map applies, and its ladder for this model tops out at
+          # xhigh — captured on the wire 2026-10-21, `:max` left as
+          # `reasoning_effort: "xhigh"` with this identity map in place. The
+          # `max` row below is the engine-side half of the contract; it takes
+          # effect the moment the harness ladder gains `max`, and nothing here
+          # can force it sooner.
+          #
+          # Thinking OFF needs an explicit mode. The default disable mode sends
+          # the LOWEST effort rather than a switch — `:off` left the wire as
+          # `reasoning_effort: "minimal"` (captured), and minimal still thinks:
+          # a canned 26-token block on every "off" request. `none-effort` makes
+          # the harness send `reasoning_effort: "none"`, which this engine
+          # honours as a real switch: `reasoning_tokens: 0`, answer only, no
+          # thinking block in the rendered output (both verified 2026-10-21).
+          #
+          # Re-measure before changing any of it. The allow-list, in the
+          # engine's own words:
+          #   curl -s :7770/v1/chat/completions -H 'content-type: application/json' \
+          #     -d '{"model":"frank-dragoon","messages":[{"role":"user","content":"x"}],
+          #          "reasoning_effort":"maximum"}'
+          #   -> 400 "reasoning_effort 'maximum' unsupported; use
+          #      minimal|low|medium|high|xhigh|max|none"
+          # and read usage.completion_tokens_details.reasoning_tokens at
+          # max_tokens 2048 to see the levels separate. The wire itself is
+          # settled by pointing a scratch HOME at a logging proxy on :7799 that
+          # forwards to :7770 and running `omp --model …:off` — config claims
+          # are worth exactly what their last capture says.
+          reasoningDisableMode: none-effort
          reasoningEffortMap:
-            minimal: low
+            minimal: minimal
            low: low
            medium: medium
-            high: xhigh
-            max: xhigh
-          # The card's thinking recipe, on the wire. The flash-server
-          # engine HAS a server-side sampler (HALOGEN_TEMPERATURE/TOP_P/
-          # TOP_K = 1.0 / 0.95 / 20 in frank-dragoon.env) — these match it,
-          # so per-request values are consistent, not load-bearing.
+            high: high
+            xhigh: xhigh
+            max: max
+          # The card's thinking recipe, on the wire. The flash-server engine
+          # HAS a server-side sampler (HALOGEN_TEMPERATURE/TOP_P/TOP_K =
+          # 1.0 / 0.95 / 20 in frank-dragoon.env), but an omitted parameter is
+          # the engine's choice, not a pinned one: top_k is sent explicitly so
+          # the recipe survives someone editing HALOGEN_TOP_K. The engine
+          # accepts top_k, min_p, presence_penalty and repetition_penalty
+          # (measured 2026-10-21, all 200) — only the values this endpoint is
+          # meant to run are pinned here.
          extraBody:
            temperature: 1.0
            top_p: 0.95
+            top_k: 20

  "llamacpp (dankclaw-3090)":
    baseUrl: http://192.168.0.143:7771/v1
@@ -143,7 +194,7 @@ providers:
    auth: none
    models:
      - id: frank-zealot
-        # Model id renamed from frank-zealot on 2026-10-08 (official
+        # Model id renamed from frank-small on 2026-10-08 (official
        # unit-name scheme; the service/unit/scripts keep the
        # frank-zealot name — service names are unchanged).
        name: "frank-zealot (dankclaw-3090)"
@@ -275,13 +275,13 @@ transition = [ "fade" ]
    interval_seconds = 1200

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

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

    [wallpaper.monitors.DP-1]
-    path = "/home/blank/.local/share/noctalia/wallpapers/wallhaven_v93dk3.jpg"
+    path = "/home/blank/.local/share/noctalia/wallpapers/wallhaven_g7r3vd.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_v93dk3.jpg"
+    path = "/home/blank/.local/share/noctalia/wallpapers/wallhaven_g7r3vd.jpg"

 [weather]
 unit = "imperial"
@@ -1,5 +1,5 @@
 [Unit]
-Description=swayidle idle lock (locks via noctalia-shell IPC, suspends on lid)
+Description=swayidle idle lock watcher (arms the idle lock via noctalia-shell IPC; suspend is covered by noctalia's sleep inhibitor)
 Documentation=https://github.com/swaywm/swayidle
 After=graphical-session.target
 # Restart together with the session, not merely at boot: this unit is wanted by
@@ -7,8 +7,16 @@
 // requires: Lenovo Group Limited 0x40A9 Unknown
 // optional: HDMI-A-1 (PM1601, dock-dependent)

+// The panel offers 3440x1440@239.998 as well as @180.000 (`niri msg outputs`, 2026-10-21), and
+// 180 is driven DELIBERATELY: the link trained at x8 32.0 GT/s against a max of x16 and the
+// display engine is throwing DMCUB errors with EINVAL page flips after s2idle, so the 240-class
+// mode stays undriven until a reboot clears that state. niri matches mode strings VERBATIM and
+// does not round: "@239.999" is not "@239.998", and a mode it cannot find does not fail — it
+// logs "could not be found, falling back to preferred" and drops the panel to 60 Hz on every
+// reconnect, which is how this desk ran for weeks. Copy the string from `niri msg outputs`.
+// Reasoning and triage: omp-docs/tools/niri/displays.md ("The config pattern", rules 4 and 5).
 output "Sceptre Tech Inc Sceptre M34 Unknown" {
-    mode "3440x1440@239.999"
+    mode "3440x1440@180.000"
    scale 1
    transform "normal"
    position x=1581 y=-600
@@ -47,7 +55,7 @@ output "eDP-1" {
    position x=-339 y=-240
 }
 output "DP-1" {
-    mode "3440x1440@120.000"
+    mode "3440x1440@180.000"

    scale 1.0

@@ -96,13 +96,11 @@ Pi already runs a similar model with its parallel `researcher` and `scout` subag

 ## The Finish Rule

-Research must end. Stop when any one is true:
-
-1. Two or more independent sources agree on the answer.
-2. The retrieval budget is spent.
-3. The required confidence is met for every claim.
-
-Report gaps honestly. Do not invent a source to fill one.
+The rule itself — stop when independent sources agree, when the retrieval budget is spent, or
+when every claim has the required confidence, and report the gaps instead of inventing a source —
+is owned by [Agentic Search Best Practices](agentic-search-best-practices.md#the-finish-rule),
+the page an agent reads before it starts a loop. What belongs here is the measurement: unbounded
+loops are why "infinite re-search" is a named failure mode in the next section.

 ## Failure Modes and Guardrails

@@ -8,40 +8,43 @@ tags:
  - privacy
  - configuration
  - unverified
-verified: 2026-10-19
+verified: 2026-10-21
 timestamp: 2026-08-11
 resource: https://docs.searxng.org
 ---

 # SearXNG Tuning

-SearXNG is a metasearch engine. It aggregates hundreds of upstream search
-services into one result set (upstream `settings.yml` defines 388 engine
-entries at master, probed 2026-10-19; the live fleet instance loads 262).
-Configuration lives in `settings.yml`. The recommended deployment is Docker
-Compose (or Podman Quadlet) with a Valkey container.
+SearXNG is a metasearch engine: it aggregates upstream search services into one result set.
+Upstream ships several hundred engine entries (385 in `settings.yml` at master, read
+2026-10-21 — the count drifts every week, so treat it as an order of magnitude, not a fact);
+what your instance actually loads is what `/config` reports, and the fleet's loads **262**
+(re-read 2026-10-21). Configuration lives in `settings.yml`. The recommended deployment is
+Docker Compose (or Podman Quadlet) with a Valkey container.

 This page lists the settings that matter for speed, privacy, and useful results.

-> **Fleet instance:** the harness `web/searxng` provider calls the instance at
-> `192.168.0.143:8081` (UI) / `:8082` (JSON API) on dankclaw. The pi-era
-> [Pi Web Access](../pi/packages/pi-web-access.md) called the same host.
+> **Fleet instance:** the harness `web/searxng` provider calls
+> `192.168.0.143:8081` on dankclaw — HTML **and** JSON on that one port
+> (`/search?q=…&format=json`, re-probed 2026-10-21). Port **8082 is not a second SearXNG
+> API**: it publishes container port 8085, which is Marreta's nginx (moved off 8080 because
+> SearXNG owns it in that namespace). Both ports show up against four container names because
+> `searxng`, `searxng-valkey`, `gluetun` and the `marreta` pair share one network namespace.
+> The pi-era [Pi Web Access](../pi/packages/pi-web-access.md) called the same host.

-## Live instance (probed 2026-10-19)
+## Live instance (probed 2026-10-21)

 User Quadlet stack on dankclaw: `searxng.container`
 (`ghcr.io/searxng/searxng:latest`) + `searxng-valkey.container`
-(`docker.io/valkey/valkey:9-alpine`) + `gluetun.container` (VPN egress; the
-containers share its network namespace, which is why `podman ps` shows :8081/
-:8082 on several names) + `marreta`/`marreta_browser`. `limiter.toml`: enabled,
-`pass_searxng_org: true`.
+(`docker.io/valkey/valkey:9-alpine`) + `gluetun.container` (VPN egress; the other containers
+join its network namespace, hence the shared port list) + `marreta`/`marreta_browser`.
+`limiter.toml`: enabled, `pass_searxng_org: true`.

-**Policy drift flag:** this page's tuned engine policy (google and bing
-disabled; DuckDuckGo/Wikipedia/Google News enabled — verified via `/config` on
-2026-08-16) is NOT live: `/config` on 2026-10-19 reports all 262 engines
-enabled, google and bing included. Either the settings override was lost in
-the 2026-10 stack reinstatement or the policy was deliberately dropped.
-Confirm with Frank before re-applying.
+**Policy drift flag:** this page's tuned engine policy (google and bing disabled;
+DuckDuckGo/Wikipedia/Google News enabled — verified via `/config` on 2026-08-16) is NOT live.
+`/config` re-read 2026-10-21: 262 engines, **zero disabled**, google and bing included —
+unchanged since 2026-10-19. Either the override was lost in the 2026-10 stack reinstatement or
+the policy was deliberately dropped. Confirm with Frank before re-applying.


 ## Plan the Deployment
@@ -8,7 +8,7 @@ tags:
  - networking
  - proxy
  - unverified
-verified: 2026-08-28
+verified: 2026-10-21
 timestamp: 2026-08-19
 resource: https://docs.searxng.org/admin/settings/settings_outgoing.html
 ---
@@ -19,7 +19,10 @@ SearXNG talks to many upstream engines. Some of them rate-limit or block the sou

 This page gives four working patterns. Choose the one that matches how you run SearXNG.

-> **Your setup:** SearXNG runs on another host at `192.168.0.143:8081` (dankclaw). Apply the Docker patterns on that host. The proxy pattern works from any host.
+> **Fleet instance:** SearXNG runs on dankclaw (`192.168.0.143:8081`, HTML and JSON alike)
+> inside gluetun's network namespace — Pattern 2 below, in Quadlet rather than Compose. The
+> live shape is in [Fleet instance on dankclaw](#fleet-instance-on-dankclaw), read 2026-10-21.
+> The proxy pattern (1) works from any host.

 ## The Goal

@@ -156,11 +159,33 @@ This pattern places the whole SearXNG process inside the tunnel namespace. The h
 | Dedicated network | Medium | High | No |
 | Inside VPN container | Medium | Highest | No |

+## Fleet instance on dankclaw
+
+Read from the running container 2026-10-21 (`podman inspect gluetun`, `podman ps`):
+
+* **`VPN_SERVICE_PROVIDER=custom` with `VPN_TYPE=wireguard`.** The provider is Proton VPN,
+   configured as *manual* WireGuard: the single-peer `WIREGUARD_*` names
+   (`WIREGUARD_PRIVATE_KEY`, `WIREGUARD_PEER_PUBLIC_KEY`, `WIREGUARD_ENDPOINT_IP`) are what
+   gluetun reads. `VPN_SERVICE_PROVIDER=protonvpn` is wrong here, and so is the plural
+   `WIREGUARD_PEERS_*` family — that shape belongs to a different gluetun major.
+* **One namespace, four names.** `searxng`, `searxng-valkey`, `marreta` and `marreta_browser`
+   join gluetun's network namespace, so `podman ps` prints the same published-port list against
+   all of them: `8081→8080` is SearXNG, `8082→8085` is Marreta's nginx, which moved off 8080
+   because SearXNG owns it inside that namespace.
+* **`FIREWALL_ENABLED_DISABLING_IT_SHOOTS_YOU_IN_YOUR_FOOT=on`.** The name is the warning:
+   turning it off sends the container's egress out the plain internet while every "VPN is
+   configured" check keeps passing — results then quietly come from the host IP.
+* **Health:** tunnel presence is `podman exec gluetun sh -c 'test -e /sys/class/net/tun0'`
+  (true on this box). gluetun ships no curl, so an egress-IP check needs a companion container
+  on its network — see [Verify the Route](#verify-the-route).
+
 ## Decisions That Matter

 - A SOCKS proxy keeps the per-engine control. Use Pattern 1.
 - Gluetun gives the cleanest full-tunnel setup. Use Pattern 2.
- Mullvad ships its own WireGuard keys for Gluetun.
+* Copying an upstream example? Read the provider and env shape from
+   [Fleet instance on dankclaw](#fleet-instance-on-dankclaw) first: the mullvad-shaped block in
+   Pattern 2 is an illustration, not this fleet's config.
 - An OpenVPN-only provider works with Pattern 3 or 4.

 ## Verify the Route
@@ -1,13 +1,13 @@
 ---
 type: reference
 title: Caddyfile Syntax
-description: Caddy Caddyfile reference — directive and matcher syntax, named matchers, directive sorting, and the handle/route order rule. Grounded in caddyserver.com (fetched 2026-08-28).
+description: Caddy Caddyfile reference — the syntax that bites (matchers, directive sorting, handle vs route), plus where the fleet's live Caddyfile actually is and how to validate it.
 resource: https://caddyserver.com/docs/caddyfile
 tags:
  - caddy
  - caddyfile
  - reverse-proxy
-verified: 2026-08-28
+verified: 2026-10-21
 ---

 # Caddyfile Syntax
@@ -17,13 +17,28 @@ port). Directives inside the block control how Caddy serves requests. Matchers
 classify requests. This page records the syntax that trips people up, grounded
 in the official docs.

-Sources: [caddyfile-tutorial](https://caddyserver.com/docs/caddyfile-tutorial),
-[matchers](https://caddyserver.com/docs/caddyfile/matchers),
-[rewrite](https://caddyserver.com/docs/caddyfile/directives/rewrite),
-[handle](https://caddyserver.com/docs/caddyfile/directives/handle),
-[forward_auth](https://caddyserver.com/docs/caddyfile/directives/forward_auth),
-[reverse_proxy](https://caddyserver.com/docs/caddyfile/directives/reverse_proxy),
-[concepts](https://caddyserver.com/docs/caddyfile/concepts).
+The syntax below is the parts that bite; the sources are listed under
+`# Citations` at the end.
+
+## Where the live Caddyfile is
+
+Caddy runs as a **rootless Quadlet container** on Dankclaw
+(`~/.config/containers/systemd/caddy.container`, unit `caddy.service`). It is a *user* unit:
+`systemctl is-active caddy` as root answers `inactive` and means nothing — ask the user
+manager (`systemctl --user`). Its config path lives inside the container, so there is **no
+`/etc/caddy` on the host**: a host-side search for a Caddyfile comes up empty, and
+`pgrep -a caddy` prints `--config /etc/caddy/Caddyfile` for a path that does not exist
+locally. Everything about it goes through `podman exec`:
+
+```bash
+ssh dankclaw podman exec caddy cat /etc/caddy/Caddyfile
+ssh dankclaw podman exec caddy caddy version      # v2.11.7, read 2026-10-21
+ssh dankclaw systemctl --user restart caddy
+```
+
+The live file's own header says what it fronts (both hosts, `franksdank.cloud` names,
+Pi-hole-resolved); its deployment history belongs to the serverAppConfigs vault
+(`Infrastructure/Caddy.md`), not to this syntax page.

 ## Directive and matcher syntax

@@ -116,9 +131,10 @@ Use `handle` for mutually exclusive branches (for example, per-path pages). Use
 rewrite [<matcher>] <to>
 ```

-`<to>` is the new URI (path or query). If `<to>` starts with `/`, Caddy 2.8.0+
-parses it directly. Before 2.8.0, a leading `/` was confused with a path
-matcher, so a `*` disambiguator was needed: `rewrite * /index.html`.
+`<to>` is the new URI (path or query). If `<to>` starts with `/`, Caddy 2.8.0+ parses it
+directly. Before 2.8.0 a leading `/` was confused with a path matcher, so a `*`
+disambiguator was needed: `rewrite * /index.html`. The fleet runs v2.11.7, so write the
+plain form.

 `try_files <files...>` rewrites to the first listed file that exists. It is the
 clean way to serve a named file for a path prefix:
@@ -244,6 +260,22 @@ wins). Put the specific `handle /admin*` before the catch-all `handle`.

 ## Validate before you deploy

-Run `caddy validate --config <file> --adapter caddyfile` before loading a
-Caddyfile. A placeholder hash (not a real bcrypt hash) fails validation with
-`base64-decoding password`. Render the real hashes first, then validate.
+Run `caddy validate --config <file> --adapter caddyfile` before loading a Caddyfile. A
+placeholder hash (not a real bcrypt hash) fails validation with `base64-decoding password`.
+Render the real hashes first, then validate. On the fleet's Caddy the file is inside the
+container — run the validator there, see
+[Where the live Caddyfile is](#where-the-live-caddyfile-is).
+
+# Citations
+
+- [Caddyfile tutorial](https://caddyserver.com/docs/caddyfile-tutorial) and
+  [concepts](https://caddyserver.com/docs/caddyfile/concepts) — directive form, the three
+  matcher token forms, and the canonical sort order behind the `handle`/`route` rule.
+- [matchers](https://caddyserver.com/docs/caddyfile/matchers) — exact vs `*` prefix path
+  matching, named matchers, `matcher is defined more than once`.
+- [rewrite](https://caddyserver.com/docs/caddyfile/directives/rewrite),
+  [handle](https://caddyserver.com/docs/caddyfile/directives/handle) and
+  [reverse_proxy](https://caddyserver.com/docs/caddyfile/directives/reverse_proxy) — the
+  2.8.0 leading-`/` change, `handle` vs `route` semantics, `trusted_proxies`.
+- [forward_auth](https://caddyserver.com/docs/caddyfile/directives/forward_auth) — the
+  outpost-before-gate ordering and `copy_headers`.
@@ -16,6 +16,4 @@ These files define the structural conventions that govern the agent system itsel
 * [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)

-## Change Tracking
-
-* [Bundle Change Log](log.md) — Chronological update history.
+**Change log:** the bundle keeps exactly one, one level up — [Bundle Change Log](../log.md). A directory here never has its own.
@@ -1,21 +0,0 @@
---
-type: changelog
-title: Core Bundle Change Log
-description: Change log for the core documentation directory — tracks migrations and structural changes.
-tags:
-  - core
-  - changelog
-  - okf
-timestamp: 2026-07-18
---
-
-# Core Bundle Change Log
-
-## 2026-07-18
- **Migration**: Converted `index.md` (root) to `core/index-doc.md` — moved root bundle index into core domain
- **Migration**: Converted `agents-md-format.md` (root) to `core/agents-md-format.md` — agents-md format belongs in core
- **Creation**: Established `core/` directory with `index.md` as the domain entry point
- **Creation**: This change log for tracking core directory modifications
-
-## 2026-07-15
- **Initialization**: OKF v0.1 conversion of the entire docs bundle — frontmatter applied, structure established, first `log.md` entries created
@@ -187,7 +187,7 @@ Currently configured providers:
 | `llamacpp (dankserver)` | `http://192.168.0.235:7770/v1` | `frank-default-small` (Qwen3.6-35B-A3B FP8, moe-cache 2048) | RTX 3090 |
 | `llamacpp (dankclaw)` | `http://192.168.0.143:7770/v1` | `frank-default-large` (Qwen3.8-Flash-Next Q4_0 ROCmFP4 Strix) | RTX 4070 Max-Q |

-See [[models|models]] for the complete `models.json` reference.
+See [models](/pi/models.md) for the complete `models.json` reference.

 ---

@@ -235,6 +235,6 @@ When `lastChangelogVersion` is behind pi's internal version, pi prompts for migr
 ## See Also

 - [pi](../pi/index.md) — Pi configuration overview
- [[models|models]] — Provider and model definitions
+- [models](/pi/models.md) — Provider and model definitions
 - [Pi Packages](/pi/packages/index.md) — Installed package documentation
- [[skills|skills]] — Installed skill documentation
+- [skills](/pi/skills.md) — Installed skill documentation
@@ -1,8 +1,8 @@
 # Architecture decision records

 Decisions this repo has made and will not silently revisit. One file per
-decision, named `NNN-<slug>.md`, listed here — an unlisted page fails `kb-lint`
-and does not exist as far as any agent is concerned.
+decision, named `NNN-<slug>.md`, listed here — an unlisted page fails
+`scripts/kb-coverage.py` and does not exist as far as any agent is concerned.

 **No ADRs yet.** The first one lands the moment a decision stops being
 reversible.
@@ -12,4 +12,4 @@ Current (2025/2026) best practices for infrastructure as code, containers, orche
 ## See Also

 * [Engineering](../index.md) - The parent area.
-* [SDLC and Tooling](../sdlc.md)
+* [SDLC and Tooling](../sdlc.md) - git, CI/CD, testing, review, versioning, and dev environments.
@@ -57,8 +57,8 @@ search practices, open models, MCP.

 ## [Inventory](inventory/index.md)

-Pre-pruning census of every userspace config on this box — the input for the
-pruning session.
+Per-file tracked-vs-box-only census of `~/.config` on blankpad — the input for the
+dotfiles pruning/adoption session.

 ## [Decisions](decisions/index.md)

@@ -1,5 +1,7 @@
 # Inventory Index

-Census of all userspace program configuration on the workstation.
+Tracked-vs-box-only census of userspace configuration on blankpad. Read the scope before
+trusting coverage: these pages measure `~/.config`, not `~/.local/share`, not system package
+state, not the servers.

- [home-config-census.md](home-config-census.md) — Complete inventory of top-level dotfiles, ~/.config, ~/.local/share state, and special directories (~/.pi, ~/.omp)
+- [home-config-census.md](home-config-census.md) — Per-file tracked-vs-box-only census of ~/.config on blankpad — the input for the dotfiles pruning/adoption session.
@@ -6,7 +6,7 @@ tags:
  - okf
  - maintenance
  - changelog
-timestamp: 2026-10-19
+timestamp: 2026-10-21
 ---

 # Bundle Change Log
@@ -16,357 +16,409 @@ 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.

+This is the bundle's only work log; [references/okf-spec.md](references/okf-spec.md) owns the
+one-log rule and `scripts/kb-lint.sh` enforces it. A law that a concept page already owns is
+not restated here — entry, then pointer. That is what the 2026-10-21 audit pass did to the
+newest twelve entries: the facts stayed, the duplicates went, `git log --follow` keeps the
+long form.
+
+## 2026-10-21
+
+### reviewing a day of work, and finding checks that lie
+
+Two-axis review (Standards / Spec) of 51 commits, 30 findings, on `fix/60-review-findings`.
+Refs #60, merged PR #61. The findings were one shape: **a check that reports confidence it did
+not earn.**
+
+- A guard that loses half its condition when a tool is missing must refuse, not narrow —
+  `pcie-probe.sh` measured beside a live endpoint while its own LAW said not to
+  ([tools/pcie-probe.md](tools/pcie-probe.md)).
+- A deployer that prints `ENABLE` for a unit systemd refuses to enable (`live-sync.service` has
+  no `[Install]`; its timer arms it) reports a belief, not an outcome, and walking `*.service`
+  only left the heartbeat unarmed on a rebuilt box
+  ([tools/dotfiles-deploy.md](tools/dotfiles-deploy.md)).
+- A gate handed git's quoted path reads an empty diff and passes. Fail closed means `-z`
+  (`.githooks/pre-commit`, `tests/secret-gate.bats`).
+
+Two laws no other page owns: **a stub that echoes its environment instead of its argument
+cannot see the bug** — the probe suite asserted the mask was set and never read what the tool
+passed, so per-card bandwidth stayed unobtainable; and **a name is data — split it, never let
+the shell expand it** (`remote-job.sh status` globbed its own arguments, so job `x*` was
+reported as whatever matched in the caller's directory: [tools/remote-job.md](tools/remote-job.md)).
+
+The heartbeat's three missed ticks were this gate firing on a managed skill that documents the
+vendor's all-zeros placeholder id: prose about credentials *is* the machine tier, and a gate
+that blocks it gets worked around — the workaround is the hole. Placeholder judgement reads the
+matched token and what follows it (a fixed quantifier truncates `EXAMPLE` to `EXA`), never the
+whole line. `ALLOW_SECRETS` stays the only override.
+
+The rest of #60 was claims the machine had stopped honouring: `.gitignore` and `deploy.sh`'s
+exclusion list drifted apart, `.gitattributes` justified installing `git-lfs` for wallpapers
+that same week's diff untracked, and the one-log rule had four owners. A coverage claim names
+what was measured; a tool justified by dead config cannot survive the config.
+
+### an effort map folding against rejections that never existed
+
+Refs #62. `agent/models.yml` rewrote `minimal→low`, `high→xhigh`, `max→xhigh` for frank-dragoon
+to dodge 400s the engine does not send — flash-server's own error names its allow-list and the
+harness passes an unmapped level through verbatim, so the fold only asked for a different
+thinking budget than the caller named. The map is identity now, and
+`reasoningDisableMode: none-effort` was added because the default disable mode does not disable:
+`:off` still sends `reasoning_effort: "minimal"` and pays for a canned thinking block. Contract
+owner: [pi/models.md](pi/models.md). Law: **a claim about what the harness sends is worth
+exactly its last capture** — settle it through a logging proxy, not by reading config. The same
+pass restored the three pre-callsign model ids the 2026-10-08 rename had overwritten inside its
+own explanatory comments.
+
+### a documented mode the panel never had
+
+The home ultrawide ran at 60 Hz for weeks because `desk-1-home.kdl` asked for
+`3440x1440@239.999` and the panel advertises `@239.998`. One character: niri matches mode
+strings verbatim, does not round, and a mode it cannot find does not fail — it falls back to the
+EDID preferred mode, 60 Hz, on every connector drop. The page that owns the file documented the
+same phantom mode, so every reader trusted it. Laws, triage table and probes:
+[tools/niri/displays.md](tools/niri/displays.md). Durable: **a number in a page is a claim, not
+a measurement** — mode strings, refresh rates and tool availability were wrong on several pages
+at once (`wlr-randr` listed as installed while `pacman -Qs wlr` matches nothing). Read the
+hardware, then destroy the stale copies. A correction is itself a measurement: this entry's
+first pass published a second wrong hardware fact, with a `verified:` date stamped on it.
+
+### a dedupe sweep, and scouts whose ledgers did not survive contact with the files
+
+Refs #64. Owners moved, not words. The ghostty and Gitea indexes stopped carrying second copies of
+the pages they route to — Gitea's index restated the container table, the boot-persistence law, the
+management commands, and the data layout while its own See Also list named the four pages that own
+them, and an index that restates an operational table becomes the second authority, which is the
+one that goes stale. The llama.cpp overview handed Docker and the `LLAMA_ARG_*` rule back to the
+setup page that had always promised them; the search finish rule has one owner again; fleet
+hardware and the SearXNG engine count were re-read from the boxes rather than re-derived, and the
+count is now stated as a size class because it moves weekly.
+
+Two laws no other page owns:
+
+- **A scout's ledger is a claim, not a finding.** The checkable-false share of the returned rows
+  was large: three pages "missing an H1" that have one; a 215-line `omp-docs/AGENTS.md` that does
+  not exist; a wikilink-and-wall defect in `core/settings.md` that a commit from that same morning
+  had already removed; `core/subagent-limits.md` called superseded while `agent/config.yml` still
+  carries `maxRecursionDepth: 1` and `maxRuntimeMs: 1800000` on the very lines the page cites.
+  Nothing entered the diff until it was re-read against the file it accused.
+- **A ledger written to a file is not delivered.** One scout yielded against a zero-byte file;
+  three more wrote their path with the tool-call parameter block embedded in the filename, so their
+  ledgers exist under names no caller can ask for. Ask for the ledger as the yield text, then read
+  it before repeating it.
+
+Fan-out, measured the hard way: seven audit subagents on one local endpoint produced nothing for
+seventeen minutes. `task.maxConcurrency` is 2, so five were queued while two thrashed, and
+`proc://` labels a queued task `running` — which is not the claim it sounds like. Cancelling five
+let the survivors land within minutes.
+
+One mechanical find worth keeping: a generated See Also block had left **five links with empty
+text** (`- ](index.md)`) across the gitea pages, `tools/cachyos.md`, and `tools/applications.md` —
+rendered, that is a bullet with nothing in it to click, so it reads as a style choice rather than a
+broken reference. `grep -rnE '(^|[ ,])\]\('` finds them in one pass.
+
+The day's three `## 2026-10-21` sections are now one section with four subsections, which is what
+the spec's one-dated-section-per-day rule always meant; [references/okf-maintenance.md](references/okf-maintenance.md)
+says so explicitly now.
+
+## 2026-10-20 — one work log per bundle
+
+The bundle had two: this page and `core/log.md` — two entries of pure migration bookkeeping and
+a conversion date that neither this page nor git agreed with (2026-07-15 there, 2026-01-15 here,
+`git log` dates the OKF rebuild 2026-08-28); `core/index.md` still pointed readers at it, which
+is how a stale page stays alive. Trashed to `omp-docs/core/.AGENTTRASH/`. The rule lives in
+[references/okf-spec.md](references/okf-spec.md) and
+[references/okf-maintenance.md](references/okf-maintenance.md) and is gated by
+`scripts/kb-lint.sh`; the agent-side duty is `agent/APPEND_SYSTEM.md` § 1.
+
+## 2026-10-20 — two instruments rescued from `$HOME` script sediment
+
+Refs #53. `$HOME` had accumulated 123 loose scripts (archived to
+`.AGENTTRASH/home-scripts-2026-10-20`; ~1.8 GiB of stray audio consolidated into `~/audiosamples`).
+Two were durable instruments and now live in the repo with black-box tests and pages:
+[tools/remote-job](tools/remote-job.md) — a readiness pattern in a log is not evidence of
+completion, the pattern can match a header printed before the work starts, and `sed -n /x/q`
+exits the moment it matches, tearing down the job it was watching — and
+[tools/pcie-probe](tools/pcie-probe.md) — never benchmark beside a live service, never let a
+tool decide to stop one, and an instrument that segfaults is not an instrument.
+
 ## 2026-10-20 — the secret gate was reading the wrong files, and one credential had already escaped

-Found while deciding what else belongs in `dotfiles/`. (1) The gate whitelisted
-extensions (`*.md *.yml *.json *.toml *.sh *.ts *.js`), so a `.env`, `.container`,
-`.ini` or extension-less dotfile was never read — exactly the shapes the dotfiles
-tier is made of. It now scans the whole staged diff for token shapes and, in
-non-prose files, for credential assignments, and it fails closed when `git diff`
-itself errors. That last clause earned its place: the rewrite's first attempt
-passed `-I` to `git diff`, which is not valid there, got an empty file list, and
-reported success on every commit — that is what a blind gate looks like, and it
-looks identical to a clean tree. (2) A live credential had already escaped into
-tracked content: a Caddy basicauth bcrypt hash, its plaintext password, and the
-Pi-hole internal password, in an auto-learned memory file. Redacted — but both
-credentials need **rotation**, because redaction does not un-leak history that
-every machine has already pulled. (3) `home/dank/.omp/dotfiles/**` and
-`.pre-pull-backup/**` were tracked fiction invisible to `deploy.sh`, and 23
-wallpaper JPEGs (80 MiB) rode along in every clone. Laws: a gate must fail closed,
-since a silently-passing gate is worse than none — it buys the belief of safety;
-auto-learned memory is written by a process that has read your terminal, so it is
-a leak surface and gets gated like any config; `systemctl --user enable`
-snapshots an absolute path, so enabling from a worktree means the seven-day reap
+Found while deciding what else belongs in `dotfiles/`. The gate whitelisted extensions, so
+`.env`, `.container`, `.ini` and extension-less dotfiles — the shapes the dotfiles tier is made
+of — were never read. It now scans the whole staged diff for token shapes and, in non-prose
+files, for credential assignments, and fails closed when `git diff` itself errors; the rewrite's
+first attempt passed an invalid flag to `git diff`, got an empty file list, and reported success
+on every commit — which is what a blind gate looks like, and it looks identical to a clean tree.
+Bcrypt hashes and Basic-auth headers joined the shape list (issue #40) because the audit found
+a live Caddy basicauth hash, its plaintext password, and the Pi-hole internal password in a
+tracked auto-learned memory file. **Redaction does not un-leak history that every machine has
+already pulled: both credentials needed rotation.** Auto-learned memory is written by a process
+that has read your terminal, so it is a leak surface and gets gated like any config. Also
+removed: tracked fiction invisible to `deploy.sh` (`home/dank/.omp/dotfiles/**`,
+`.pre-pull-backup/**`) and 23 wallpaper JPEGs (80 MiB) riding in every clone. Mechanism:
+`.githooks/pre-commit` and its tests; details in
+[dotfiles-deploy](tools/dotfiles-deploy.md) and
+[home-config-census](inventory/home-config-census.md). Law no other page owns: **`systemctl
+--user enable` snapshots an absolute path** — enabling from a worktree means the seven-day reap
 silently kills the unit while `is-enabled` goes on saying `enabled`
-(`blankpad-desk-autoswitch.service` was dangling that way). Details:
-[dotfiles-deploy](tools/dotfiles-deploy.md),
-[home-config-census](inventory/home-config-census.md).
+(`blankpad-desk-autoswitch.service` was dangling that way).

 ## 2026-10-20 — engineering skills configured against this KB

-`setup-matt-pocock-skills` ran, and its output moved out of the skill's default
-`docs/agents/` into the knowledge base: [issue tracker](skills/issue-tracker.md)
-(Gitea on Dankclaw is the tracker — no `gh`, no `tea`, token via a `600` curl
-config), [triage labels](skills/triage-labels.md) (the five canonical roles,
-created on the repo, which carried zero labels before), [domain
-docs](skills/domain-docs.md) (single-context; glossary withheld until a term has
-no other owner), plus an empty [decisions](decisions/index.md) with its format
-rule. `AGENTS.md` gained an `## Agent skills` pointer block. Law: this repo has
-one knowledge base, so per-tool configuration is a concept page in `omp-docs/` —
-a second `docs/` tree means a second set of index rules, which is where
-documentation starts disagreeing with itself. Known cost: re-running that setup
-skill will not recognise `omp-docs/skills/*` and will offer to recreate
-`docs/agents/`; the `AGENTS.md` pointer is the thing that stops it.
+`setup-matt-pocock-skills` ran and its output moved out of the skill's default `docs/agents/`
+into the knowledge base: [issue tracker](skills/issue-tracker.md),
+[triage labels](skills/triage-labels.md), [domain docs](skills/domain-docs.md), and an empty
+[decisions](decisions/index.md) with its format rule. `AGENTS.md` gained the `## Agent skills`
+pointer block. Law: this repo has one knowledge base, so per-tool configuration is a concept
+page in `omp-docs/` — a second `docs/` tree means a second set of index rules, which is where
+documentation starts disagreeing with itself. Known cost: re-running that setup skill will not
+recognise `omp-docs/skills/*` and will offer to recreate `docs/agents/`; the `AGENTS.md` pointer
+is what stops it.

 ## 2026-10-19 — dankvoice auto-speak armed at startup

-Sessions spoke only on explicit `/say`: the settings file carried no `auto`
-key, and arming is session-scoped by design (`/say on` never persists). Set
-`"auto": true` in `~/.omp/cache/dankvoice.json`. Same report, second half:
-auto-speak listened only to `agent_end` — a settle that fires once per prompt
-and is skipped outright when the harness schedules a continuation — so nothing
-was narrated while an agent worked; fixed in dank/dankvoice#3, which narrates
-`turn_end` as well. Law: silence at session start is a config state — read
-`/say status` for `auto-speak on`, then watch `pgrep -a pw-play` for one player
-per segment, before blaming the endpoint. Law: whether the harness delivers an
-event to extensions is settled in minutes by a throwaway probe extension that
-timestamps `turn_end`/`agent_end` — never inferred from audio timing, which the
-humanizer lags by seconds. Details: [dankvoice](core/dankvoice.md).
+Nothing spoke because the settings file carried no `auto` key (arming is session-scoped by
+design) and narration rode only `agent_end`, a settle that a scheduled continuation skips; fixed
+upstream in dank/dankvoice#3. Law: silence at session start is a config state — read `/say
+status`, then watch `pgrep -a pw-play` for one player per segment — before blaming the endpoint.
+Law: whether the harness delivers an event to extensions is settled in minutes by a throwaway
+probe extension that timestamps `turn_end`/`agent_end`, never inferred from audio timing.
+Details: [core/dankvoice.md](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).
+`lazyvim` had never been installed here: shell history shows the command typed twice and
+dropped, and `~/.config/nvim` held only an orphaned `matugen.lua` palette nothing loaded. Now the
+starter lives in `dotfiles/lazyvim/` symlinked to `~/.config/lazyvim`, a `lazyvim` zsh function
+reaches it, and the wallpaper palette applies through `RRethy/base16-nvim` on `ColorScheme`.
+Law: the distribution stays out of `~/.config/nvim` so bare `nvim` keeps working as a vanilla
+quick-edit editor. Details: [tools/neovim.md](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.
+Drop-in `agent/extensions/dankvoice.ts` and its 26-test suite retired; the package carries the
+behaviour (41/41 black-box suite) and installs 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.
-enable_thinking: false`, so the Qwen35 hybrid *thought* instead of answering:
-6.9 s of `reasoning_content`, `content: ""` — timing out the rewrite twice
-(12 s dead air) and, when it did answer inside the window, speaking silence.
-Root-caused by replaying the exact wire body against the live endpoint.
-Fix: pin the kwarg in the request body; treat empty-content-with-reasoning as
-failure (mechanical voice), not "nothing worth saying"; the menu's test phrase
-fires without blocking its handler. Lesson: the harness injects thinking-off
-for managed roles, but raw HTTP callers must set it themselves — 26/26 green
-with three red-captured regressions.
+The humanizer's raw `fetch` omitted `chat_template_kwargs.enable_thinking: false`, so the Qwen35
+hybrid *thought* instead of answering: 6.9 s of `reasoning_content`, `content: ""` — dead air
+twice, and when it answered inside the window it spoke silence. Root-caused by replaying the
+exact wire body against the live endpoint. Fix: pin the kwarg, treat empty-content-with-reasoning
+as failure, fire the menu's test phrase without blocking its handler. Lesson: the harness injects
+thinking-off for managed roles; raw HTTP callers must set it themselves.
+[core/dankvoice.md](core/dankvoice.md).

-## 2026-10-19 — dankvoice: humanized narration and thinking aloud (Refs #27)
+## 2026-10-19 — dankvoice: humanized narration, segmented speech, `/say` menu (Refs #27, #23, #21)

-Spoken units are rewritten by the `@tiny` role (frank-zealot) under the
-bundle's speech budgets before synthesis, with mechanical cleanup as fallback;
-auto-speak narrates the last message's thinking blocks first; all toggles
-persist. 7 new scenarios, 22 green; live smoke through real zealot + frank-tts.
-
-## 2026-10-19 — dankvoice: segmented sequential speech
-
-`agent_end` awaiting one whole-answer synthesis hit the harness's 30 s
-extension-handler timeout — lesson: extensions must never await work that can
-exceed 30 s. Ported the built-in vocalizer's utterance-splitting state machine
-(boundary = `[.!?…]+` + whitespace, abbreviation/code guards, per-answer
-segment budget); segments synthesize strictly sequentially. `DANKVOICE_MAX` is
-now a segment budget. 17/17 in `tests/dankvoice.bats`.
-
-## 2026-10-18 — dankvoice: `/say` options menu with output-device routing (Refs #23)
-
-`/say menu` (pi-peon-style): auto-speak, voice, PipeWire output device
-(`wpctl` → `pw-play --target`), player, char cap, test phrase. Precedence
-env > `~/.omp/cache/dankvoice.json` > defaults — born from the incident where
-PipeWire's remembered Bluetooth route played answers into nowhere.
-
-## 2026-10-18 — dankvoice: the cloned voices finally speak in the TUI (Refs #21)
-
-The harness gates `--voice` against the bundled Kokoro enum, so frank-tts's
-cloned voices were unreachable in-TUI. Added `agent/extensions/dankvoice.ts`
-(`/say …`) synthesizing over the OpenAI speech route, endpoint read from the
-`api: openai-speech` row of `agent/models.yml` (no host or secret in code).
+Spoken units are rewritten by the `@tiny` role under the bundle's speech budgets with mechanical
+cleanup as fallback; the utterance-splitting state machine synthesizes segments strictly
+sequentially because `agent_end` awaiting one whole-answer synthesis hit the harness's 30 s
+extension-handler timeout — **extensions must never await work that can exceed 30 s**. `/say menu`
+routes output device (`wpctl` → `pw-play --target`) with precedence env > settings file >
+defaults, born from PipeWire's remembered Bluetooth route playing answers into nowhere. The
+extension exists at all because the harness gates `--voice` against the bundled Kokoro enum, so
+frank-tts's cloned voices were unreachable in-TUI. [core/dankvoice.md](core/dankvoice.md).

 ## 2026-10-18 — Noctalia bar layout clobbered by trunk-sync stash, recovered

-GUI-built bar customizations existed only in the working tree; a trunk-sync
-stash-then-drop destroyed them. Recovery: `git fsck --lost-found` surfaced the
-dropped stash as a dangling commit; validated in a sandboxed `XDG_*_HOME`
-before restore. Lesson: GUI-written config is only durable once committed —
-the motivation for the live-sync heartbeat below.
-
-## 2026-10-18 — Fleet law: issue/PR attribution footers
-
-Every agent-opened issue/PR body ends with `cwd:` + `session:` footer, in both
-`dank/command-center` and `dank/serverAppConfigs` AGENTS.md: machine-made
-artifacts must trace to the box and session that produced them.
+GUI-built bar customizations existed only in the working tree; a trunk-sync stash-then-drop
+destroyed them. Recovery: `git fsck --lost-found` surfaced the dropped stash as a dangling
+commit, validated in a sandboxed `XDG_*_HOME` before restore. Lesson: GUI-written config is
+durable only once committed — the motivation for the heartbeat below.
+[tools/dotfiles-deploy.md](tools/dotfiles-deploy.md).

 ## 2026-10-18 — live-sync heartbeat for machine-written paths (Refs #11)

-A month of silent divergence in the live checkout proved the checkout-is-
-deployment model needs a committer: `scripts/live-sync.sh` + systemd user
-timer auto-commits allowlisted tiers (memories, managed-skills, live config,
-dotfiles) with hooks armed, merges `origin/main`, pushes, reaps stale `wt/*`.
-Non-allowlist dirt never staged; conflicts abort-and-alert. See
-[tools/live-sync.md](tools/live-sync.md); tier law in AGENTS.md.
+A month of silent divergence in the live checkout proved the checkout-is-deployment model needs
+a committer: `scripts/live-sync.sh` + a systemd user timer auto-commits the allowlisted tiers
+with hooks armed, merges `origin/main`, pushes, and reaps stale `wt/*`. Non-allowlist dirt is
+never staged; conflicts abort and alert. [tools/live-sync.md](tools/live-sync.md); tier law in
+`AGENTS.md`. Same day, two fleet laws into both repos' `AGENTS.md`: every agent-opened issue or
+PR body ends with a `cwd:` + `session:` footer, so machine-made artifacts trace to the box that
+spawned them; and `xdg-open <PR-URL>` the moment a PR opens, so Frank never hunts for it in
+Gitea.

-## 2026-10-18 — Fleet law: filed PRs open in Frank's browser immediately
+## 2026-10-18 — SDLC switched to trunk-based development; extension route closed unmerged

-`xdg-open <PR-URL>` the moment a PR opens — codified in both repos' git rules.
-
-## 2026-10-18 — Trunk law: extension route closed unmerged; direct repo alignment
-
-Operator closed PR #9 (cwd-scoped `before_agent_start` extension) in favor of
-editing each repo's AGENTS.md. Durable findings: every context-file provider
-(AGENTS.md walk-up, `.omp/` dirs, CLAUDE.md) resolves at or below the repo
-root — ancestor-scope files can never load; user-level `APPEND_SYSTEM.md`
-broadcasts to all sessions; serverAppConfigs never had git-flow.
-
-## 2026-10-18 — SDLC switched to trunk-based development
-
-`develop` retired (single-dev repo). Law in AGENTS.md § Trunk-based SDLC:
-branch off freshest `origin/main`, PRs target `main`, `--no-ff` merges, tags
-`vX.Y.Z` on main. Managed skill `gitflow-back-merge-plumbing` is historical.
+`develop` retired (single-dev repo): branch off freshest `origin/main`, PRs target `main`,
+`--no-ff` merges, tags `vX.Y.Z` on main — law in `AGENTS.md` § Trunk-based SDLC, managed skill
+`gitflow-back-merge-plumbing` marked historical. The operator also closed PR #9 (cwd-scoped
+`before_agent_start` extension) in favour of editing each repo's `AGENTS.md`. Durable finding:
+every context-file provider (AGENTS.md walk-up, `.omp/` dirs, CLAUDE.md) resolves at or below
+the repo root, so ancestor-scope files can never load; user-level `APPEND_SYSTEM.md` broadcasts
+to all sessions.

 ## 2026-10-18 — Sibling-vault overlap census; system docs realigned to live ground truth

-Census of `omp-docs/` vs `serverAppConfigs-docs` (subagents + live-ssh probes)
-found four contradicting pairs; ours fixed, theirs flagged for their PR flow.
-Recorded then: RTX 3090 moved Dankserver→Dankclaw 2026-09; dankserver = 2×
-Radeon AI PRO R9700 (the "board swap" story was false); served models per
-live units. Current state always: [/system/index.md](/system/index.md)
-(27B-era zealot figures here are historical; live census 2026-10-19 below).
+Census of `omp-docs/` vs `serverAppConfigs-docs` (subagents + live-ssh probes) found four
+contradicting pairs; ours fixed, theirs flagged for their PR flow. Recorded then: the RTX 3090
+moved Dankserver→Dankclaw 2026-09; dankserver is 2× Radeon AI PRO R9700 (the "board swap" story
+was false); served models per live units. Current state always:
+[/system/index.md](/system/index.md).

 ## 2026-10-18 — Status line rebuilt on custom segments; full-source audit

-New page [core/statusline.md](core/statusline.md) with an audit log — four
-first-pass claims were false and corrected against the minified bundle + a
-live screenshot matrix (context meter is `box`/`band` only; `composer.shape`
-routes segment arrays; `mode` states = Plan/Prewalk/Goal/Vibe/Loop). Bar
-rebuilt on `band` + custom segments; frank-archon display name slimmed in
-models.yml.
+[core/statusline.md](core/statusline.md) carries the audit log — four first-pass claims were
+false and corrected against the minified bundle plus a live screenshot matrix (context meter is
+`box`/`band` only; `composer.shape` routes segment arrays; `mode` states =
+Plan/Prewalk/Goal/Vibe/Loop). Bar rebuilt on `band` + custom segments.

 ## 2026-10-09 — Blankpad DE redesign: desk profiles, keybinds, Handy wiring

-Per-desk niri profiles keyed by EDID long name (connector names reshuffle
-between docks; identity travels) + `scripts/desk.sh`; niri 26.04 has **no
-hotplug event** (`OutputConfigChanged` is only an ACK per niri-ipc) — the
-autoswitch daemon diffs output sets on `WorkspacesChanged`. Keybind cheat
-sheet now generated (`scripts/gen-keybinds.sh`); noctalia docs corrected to
-the v5 `noctalia msg` API. Handy: niri owns autostart; open breaker —
-frank-secondary answers in `reasoning_content` with empty `content`, and
-Handy cannot send `chat_template_kwargs.enable_thinking=false`. 27/27 green.
+Per-desk niri profiles keyed by EDID long name (connector names reshuffle between docks;
+identity travels) + `scripts/desk.sh`. niri 26.04 has **no hotplug event** (`OutputConfigChanged`
+is only an ACK per niri-ipc), so the autoswitch daemon diffs output sets on `WorkspacesChanged`.
+Keybind cheat sheet generated by `scripts/gen-keybinds.sh`; noctalia docs corrected to the v5
+`noctalia msg` API. Handy: niri owns autostart; open breaker — frank-secondary answers in
+`reasoning_content` with empty `content`, and Handy cannot send
+`chat_template_kwargs.enable_thinking=false`. [tools/niri/displays.md](tools/niri/displays.md),
+[tools/handy.md](tools/handy.md).

 ## 2026-10-09 — Incident: agent sudo-loop tripped pam_faillock, locked out the operator

-A subagent retried `sudo yay` (no TTY) for ~15 min; `pam_faillock` deny=3
-locked user `blank` — correct-password sudo failed, mimicking a password
-change. Recovery: `faillock --user blank --reset`. Law: agents never run
-`sudo`/`yay`/`pacman`/`pkexec`; root steps go to the operator as exact
-commands. Skill `faillock-sudo-lockout-recovery`.
+A subagent retried `sudo yay` (no TTY) for ~15 min; `pam_faillock` deny=3 locked user `blank`,
+and correct-password sudo then failed, mimicking a password change. Recovery:
+`faillock --user blank --reset`. Law: agents never run `sudo`/`yay`/`pacman`/`pkexec`; root steps
+go to the operator as exact commands. Skill `faillock-sudo-lockout-recovery`.

 ## 2026-10-09 — Full secret audit of the command-center repo: clean

-Five layers (live-value scan across 77 revs/765 blobs, whole object store
-incl. dangling, shape triage, entropy ≥4.3, LFS payloads) — no secret in any
-reachable or dangling object; quarantine list holds. Fixed `hf_token_write`
-0644→0600. Open gap: the pre-commit gate lacks `hf_`/`npm_`/`pypi-`/`AIza`/
-Stripe/Telegram shapes and basic-auth URLs — widening it is an open decision.
+Five layers (live-value scan across 77 revs/765 blobs, whole object store including dangling,
+shape triage, entropy ≥4.3, LFS payloads) found no secret in any reachable or dangling object;
+the quarantine list holds. Fixed `hf_token_write` 0644→0600. Open gap: the gate lacks
+`hf_`/`npm_`/`pypi-`/`AIza`/Stripe/Telegram shapes and basic-auth URLs — widening it is an open
+decision.

 ## 2026-10-09 — Gitea token moved out of every remote URL

 Remotes bare; credential in `~/.config/secrets/gitea` (0600) behind a global
-`credential.helper store`. Trap (git 2.56.0, measured): `git
-credential-store` rejects the `protocol=`/`host=` block shape the man page
-shows — the store file must be one URL per line, port included. Verified with
-`GIT_TERMINAL_PROMPT=0`. Details: [tools/gitea/client-access.md](tools/gitea/client-access.md).
+`credential.helper store`. Trap (git 2.56.0, measured): `git credential-store` rejects the
+`protocol=`/`host=` block shape the man page shows — the store file must be one URL per line,
+port included. Verified with `GIT_TERMINAL_PROMPT=0`.
+[tools/gitea/client-access.md](tools/gitea/client-access.md).

 ## 2026-10-09 — Working tree reconciled: callsign renames, compaction move, gitignore quarantine

-200-entry dirty tree committed as seven atomic units. Harness model ids
-renamed `frank-{medium,large,small}` → `frank-{archon,dragoon,zealot}` —
-**services keep old names on the wire**; the engines accept any request model
-id, so renames are harness-side only. Server-side compaction moved to
-zealot's 3090 (threshold 70→85 %). `.gitignore` quarantine for worktree-keyed
-memory buckets and runtime dirs. Skill renames are not losses: git renders
-directory renames as mass delete+add; pre-cutover content intact at `12c5e88`.
+200-entry dirty tree committed as seven atomic units. Harness model ids renamed
+`frank-{medium,large,small}` → `frank-{archon,dragoon,zealot}` — **services keep old names on the
+wire**; the engines accept any request model id, so renames are harness-side only. Server-side
+compaction moved to zealot (threshold 70→85 %). `.gitignore` quarantine for worktree-keyed memory
+buckets and runtime dirs. Skill renames are not losses: git renders directory renames as mass
+delete+add; pre-cutover content intact at `12c5e88`.

 ## 2026-09-28 — Retired workstation purged from the knowledge base

-Sold box: hostname, both LAN addresses, Wi-Fi SSID gone bundle-wide; the
-knowledge distilled into [system/network.md](system/network.md) (multi-link
-resolver law: a static resolver must be pinned on each *connection*) and
-[tools/niri/displays.md](tools/niri/displays.md) (portrait transforms, the
-three ways a multi-monitor rig breaks). Hostname stays only where it is a
-lookup key (install.sh `--host`, `packages/<hostname>.pkgs`).
+Sold box: hostname, both LAN addresses, Wi-Fi SSID gone bundle-wide; the knowledge distilled
+into [system/network.md](system/network.md) (multi-link resolver law: a static resolver must be
+pinned on each *connection*) and [tools/niri/displays.md](tools/niri/displays.md) (portrait
+transforms, the three ways a multi-monitor rig breaks). Hostname stays only where it is a lookup
+key (install.sh `--host`, `packages/<hostname>.pkgs`).

 ## 2026-09-01 — Retry backoff and thinking default (pi era)

-Pi `settings.json`: 10 s base retry backoff (10/20/40 s), `defaultThinkingLevel:
-medium` (no per-model thinking field exists in `models.json`).
+Pi `settings.json`: 10 s base retry backoff (10/20/40 s), `defaultThinkingLevel: medium` (no
+per-model thinking field exists in `models.json`).

 ## 2026-08-28 — KB rebuilt to OKF v0.1; live-verified fleet facts

-`omp-docs/` copied from legacy `~/.pi/agent/docs`, rebuilt as git-tracked OKF
-v0.1 (checkout *is* the deployment); unverifiable claims tagged `unverified`.
-Conformance pass promoted concept-in-disguise indexes, stripped index
-frontmatter, resolved all links; `scripts/kb-lint.sh` exits 0. Hardware facts
-were corrected *then* (3090-on-dankserver since moved — see 2026-10-18).
+`omp-docs/` copied from legacy `~/.pi/agent/docs`, rebuilt as git-tracked OKF v0.1 (checkout *is*
+the deployment); unverifiable claims tagged `unverified`. Conformance pass promoted
+concept-in-disguise indexes, stripped index frontmatter, resolved all links; `scripts/kb-lint.sh`
+exits 0. Hardware facts were corrected *then* (3090-on-dankserver since moved — see 2026-10-18).
 Inventory census recorded under `inventory/` for the pruning session.

 ## 2026-08-23 — Homepage deployed to production; Caddy KB doc

-Homepage live on Dankclaw via `scripts/deploy.sh` (status checker timer,
-deployed.js, rendered basicauth hashes, health check). Hard-won Caddy lesson:
-top-level directives are *sorted*, so `rewrite` runs before `basicauth` and
-auth matchers saw rewritten paths — serve each page from its own `handle`
-block to preserve order; a `handle` inline matcher is a single token; a
-leading `@name <directive>` parses as a matcher definition. Now documented on
-[caddy/caddyfile.md](caddy/caddyfile.md). A compose mount change needs a
-container *recreate*, not a reload. 116 tests green.
+Homepage live on Dankclaw via `scripts/deploy.sh` (status checker timer, `deployed.js`, rendered
+basicauth hashes, health check). Hard-won Caddy law, now on
+[caddy/caddyfile.md](caddy/caddyfile.md): top-level directives are *sorted*, so `rewrite` runs
+before `basicauth` and auth matchers saw rewritten paths — serve each page from its own `handle`
+block; a `handle` inline matcher is a single token; a leading `@name <directive>` parses as a
+matcher definition. A compose mount change needs a container *recreate*, not a reload.

 ## 2026-08-23 — Homepage design settled (grilling complete)

 All 38 open questions answered; full record lives in serverAppConfigs
-(`docs/Infrastructure/Homepage Design Grilling.md`). Key deltas: per-service
-tcp/http probes, 5 s timeout, TUI-style panel grid, no client auto-refresh,
-git-driven deploy, full TDD. Correction recorded: the Dankserver media stack
-runs as bare processes, not containers — never probe it as a compose stack.
+(`docs/Infrastructure/Homepage Design Grilling.md`). Key deltas: per-service tcp/http probes, 5 s
+timeout, TUI-style panel grid, no client auto-refresh, git-driven deploy, full TDD. Correction
+recorded: the Dankserver media stack runs as bare processes, not containers — never probe it as a
+compose stack.

 ## 2026-08-22 — vllmScripts merged into serverAppConfigs

-Full-history two-parent import; one repo, one checkout per host, one
-`deploy.sh`. The plaintext sudo password from old docs was NOT carried over
-(a bats leak-check guards it); it remains in both repos' history on the LAN
-Gitea — rotation recommended.
+Full-history two-parent import; one repo, one checkout per host, one `deploy.sh`. The plaintext
+sudo password from old docs was NOT carried over (a bats leak-check guards it); it remains in
+both repos' history on the LAN Gitea — rotation recommended.

 ## 2026-08-21 — Fleet ops: passwordless sudo, Hermes SSH keys

-`/etc/sudoers.d/dank-nopasswd` on both servers (per-command drop-ins remain);
-dedicated ed25519 key for the Hermes container, verified into all three
-machines.
+`/etc/sudoers.d/dank-nopasswd` on both servers (per-command drop-ins remain); dedicated ed25519
+key for the Hermes container, verified into all three machines.

-## 2026-08-19 — pi-web-access: SearXNG endpoint re-pointed to dankclaw (pi era)
+## 2026-08-19 — SearXNG + Gluetun bring-up; pi endpoint re-pointed

-`searxngBaseUrl` moved off dead `.235:8081` to `.143:8081`; pi caches
-`web-search.json` per process — new endpoint needs a new session. `yt-dlp`
-installed (2026.07.04).
-
-## 2026-08-19 — SearXNG + Gluetun bring-up on dankclaw
-
-Durable field notes (now on concept pages — see
+`searxngBaseUrl` moved off the dead `.235:8081` to `.143:8081`; pi caches `web-search.json` per
+process, so a new endpoint needs a new session. Durable field notes now on concept pages —
 [agentic-web-research/vpn-routing.md](agentic-web-research/vpn-routing.md),
 [searxng-tuning.md](agentic-web-research/searxng-tuning.md),
-[engineering/infra/containers.md](engineering/infra/containers.md)):
-manual-WireGuard Proton needs `VPN_SERVICE_PROVIDER=custom` + the single-peer
-`WIREGUARD_*` env names (not `protonvpn`, not `WIREGUARD_PEERS_*`); gluetun
-ships no curl and `:8000` is the control server, not health; the limiter's
-JSON cap (`API_MAX=4`/hour) is hardcoded Python — `pass_ip` is the only
-bypass; rootless podman strips client IPs on published ports, so SearXNG must
-sit behind Caddy for XFF; quadlet generator rejects `CapAdd=`/`Device=` and
-generated units enable via `[Install] WantedBy=default.target`. ComfyUI on
-gfx1151: build on AMD's ROCm base and filter the torch family out of
-ComfyUI's requirements or you clobber the gfx1151 kernels.
+[engineering/infra/containers.md](engineering/infra/containers.md): manual-WireGuard Proton needs
+`VPN_SERVICE_PROVIDER=custom` + the single-peer `WIREGUARD_*` env names (not `protonvpn`, not
+`WIREGUARD_PEERS_*`); gluetun ships no curl and `:8000` is the control server, not health; the
+limiter's JSON cap is hardcoded Python and `pass_ip` is the only bypass; rootless podman strips
+client IPs on published ports, so SearXNG must sit behind Caddy for XFF; the quadlet generator
+rejects `CapAdd=`/`Device=` and generated units enable via `[Install] WantedBy=default.target`.
+ComfyUI on gfx1151: build on AMD's ROCm base and filter the torch family out of ComfyUI's
+requirements or you clobber the gfx1151 kernels.

 ## 2026-08-17 — Fleet redo + vLLM tool calling (pi era)

-Fleet moved off the pipeline-parallel + NPU topology; Quark W8A8 quant chosen
-over the Avesed INT8 for clean Qwen3 XML tool calls.
+Fleet moved off the pipeline-parallel + NPU topology; Quark W8A8 quant chosen over the Avesed
+INT8 for clean Qwen3 XML tool calls.

 ## 2026-08-16 — Gitea boot-persistence fix (dankclaw)

-`unattended-upgrades` reboot exposed that the compose-era Gitea had no
-systemd units (~1 h down). Stack rewritten as quadlet (names, `systemd-gitea`
-network, linger + `WantedBy=default.target`, app.ini env-override gotcha, UID
-100999 ownership) across `tools/gitea/*`; `podman generate systemd` marked
-deprecated in [engineering/infra/containers.md](engineering/infra/containers.md).
+`unattended-upgrades` reboot exposed that the compose-era Gitea had no systemd units (~1 h down).
+Stack rewritten as quadlet (names, `systemd-gitea` network, linger + `WantedBy=default.target`,
+app.ini env-override gotcha, UID 100999 ownership) across `tools/gitea/*`; `podman generate
+systemd` marked deprecated in [engineering/infra/containers.md](engineering/infra/containers.md).

 ## 2026-08-13 — Pi subagent limits recorded (pi era)

-Effective caps: globalConcurrencyLimit 2, parallel.maxTasks 8 / concurrency 4,
-maxSubagentDepth 2, turnBudget 30; no per-model limit. See
+Effective caps: `globalConcurrencyLimit` 2, `parallel.maxTasks` 8 / concurrency 4,
+`maxSubagentDepth` 2, `turnBudget` 30; no per-model limit.
 [pi/packages/pi-subagents.md](pi/packages/pi-subagents.md).

-## 2026-08-11 — Engineering research area; skills leaderboard verified
+## 2026-08-11 — Engineering research area; agentic web research section

-Created `engineering/` (SDLC, agent instruction files, stacks, infra,
-plugins, skills ecosystem, Signal remote) via parallel research fleet.
-Skills leaderboard replaced with the ranked list from the skills.sh API
-(zero-based pagination, 200-skill pages).
-
-## 2026-08-11 — Agentic web research section; exhaustive bundle audit
-
-Created `agentic-web-research/` (8 pages) and rewrote them on 2025/2026
-evidence (SearXNG valkey deployment, real engine defaults, limiter budgets,
-Gluetun pattern, open-model claim triage, MCP transports). Audit: 154+
-wikilinks resolved, dead external links fixed, `MemorySleepMode=deep`
-verified valid (systemd 256+), ASD-STE100 style pass. `AGENTS.md` created as
-the system behavior contract.
+Created `engineering/` (SDLC, agent instruction files, stacks, infra, plugins, skills ecosystem,
+Signal remote) and `agentic-web-research/` (8 pages), the latter rewritten on 2025/2026 evidence
+(SearXNG valkey deployment, real engine defaults, limiter budgets, Gluetun pattern, open-model
+claim triage, MCP transports). Skills leaderboard replaced with the ranked list from the skills.sh
+API (zero-based pagination, 200-skill pages). Same pass: 154+ wikilinks resolved, dead external
+links fixed, `MemorySleepMode=deep` verified valid (systemd 256+), ASD-STE100 style pass,
+`AGENTS.md` created as the system behavior contract.

 ## 2026-08-06 — Link fixes; ComfyUI docs; major documentation overhaul

-Fixed 15 broken wikilinks (missing frontmatter) + title mismatches → zero
-broken. Added ComfyUI pages, per-host system docs, pi config tree, tools
-entries; orphaned root duplicates moved to `.AGENTTRASH/`.
+Fixed 15 broken wikilinks (missing frontmatter) + title mismatches → zero broken. Added ComfyUI
+pages, per-host system docs, pi config tree, tools entries; orphaned root duplicates moved to
+`.AGENTTRASH/`.

 ## 2026-07-18 — Maintenance tooling

-Expanded `references/okf-maintenance.md` (cross-links, health metrics,
-troubleshooting); created `core/log.md` and `.okf/config.yaml`.
+Expanded `references/okf-maintenance.md` (cross-links, health metrics, troubleshooting); created
+`core/log.md` (retired 2026-10-20, above) and `.okf/config.yaml`.

 ## 2026-01-15 — OKF conversion

-Docs bundle converted to OKF v0.1; files migrated into `core/`, `tools/`,
-`packages/`, `references/` with frontmatter on all files.
+Docs bundle converted to OKF v0.1; files migrated into `core/`, `tools/`, `packages/`,
+`references/` with frontmatter on all files.

 ## 2025-08-05 — Gitea documentation

-Added [tools/gitea/index.md](tools/gitea/index.md) (topology, management,
-data persistence) to the tools index.
+Added [tools/gitea/index.md](tools/gitea/index.md) (topology, management, data persistence) to
+the tools index — legacy tree, predating the OKF conversion above.
@@ -31,7 +31,7 @@ Current providers in `models.json` (verified 2026-08-27, after the
 | **Base URL** | `http://192.168.0.235:7770/v1` |
 | **API** | `openai-completions` |
 | **Auth** | None (EMPTY) |
-| **Host** | [[dankserver|dankserver]] |
+| **Host** | [dankserver](/system/dankserver.md) |

 #### Models

@@ -52,7 +52,7 @@ value succeed.
 | **Base URL** | `http://192.168.0.143:7770/v1` |
 | **API** | `openai-completions` |
 | **Auth** | None (EMPTY) |
-| **Host** | [[dankclaw|dankclaw]] |
+| **Host** | [dankclaw](/system/dankclaw.md) |

 > 2026-08-22: `frank-default-large` moved from `:52625` to `:7770` on
 > Dankclaw (operator request: the primary inference server sits on the
@@ -142,6 +142,6 @@ The subagent model IDs (`frank-default-small`, `frank-default-large`) resolve ag

 ## See Also

- [[settings|settings]] — Main configuration file
- [[dankserver|dankserver]] — Primary llama.cpp server
- [[dankclaw|dankclaw]] — Secondary llama.cpp server
+- [settings](/core/settings.md) — Main configuration file
+- [dankserver](/system/dankserver.md) — Primary llama.cpp server
+- [dankclaw](/system/dankclaw.md) — Secondary llama.cpp server
@@ -64,5 +64,5 @@ No per-model limit exists. All caps are global to a run or a session. They do no

 ## See Also

- [[settings|settings]] — Subagent configuration
- [[models|models]] — Model definitions
+- [settings](/core/settings.md) — Subagent configuration
+- [models](/pi/models.md) — Model definitions
@@ -21,32 +21,49 @@ Knowledge bundles rot. It is the nature of knowledge to attract cobwebs, much li

 ## Change Tracking with `log.md`

-Every OKF bundle has a `log.md` file. It is not optional. It is the bundle's memory.
+Exactly one `log.md` per bundle, at the bundle root — [okf-spec.md](okf-spec.md) owns that rule
+and `scripts/kb-lint.sh` enforces it, reporting any `log.md` that is not the root's. The
+maintenance action is collapse, never coexistence: when a second log turns up (`core/log.md`,
+`notes.md`, a per-run diary), move its entries into the root log under their own dates, delete
+the file, and re-run the linter.

-**Format:** Date-grouped entries, newest first. One line per change with timestamp, file path, and what changed.
+**Format:** one dated section per day, newest first; a few lines per change — what
+happened, and the durable lesson. It is not a file manifest.

 ```markdown
 # Bundle Change Log

-## 2026-01-15
- `/docs/ghostty.md` — Updated keybind table after v1.2 release
- `/docs/pi-permission-system/` — Added `policy.md` and `audit.md`
- `/docs/index.md` — Synced with directory contents
+## 2026-01-15 — the gate was reading the wrong files
+
+A gate that gets an empty file list reports success. Law: a check MUST fail closed;
+a silently-passing gate is worse than none, because it buys the belief of safety.
+Details: [secret gate](/tools/index.md).
 ```

 **Rules:**
- **Newest entries first.** Putting old entries at the top inverts the timeline and makes it impossible to see what just happened.
- **One line per change.** A single line is sufficient. The git history is there if someone wants the gory details.
- **Group by date.** Batch all changes from the same day together.
- **Always date-stamp the section.** Use `## YYYY-MM-DD`.
- **Mention `index.md` whenever you change a bundle.** If you added or removed a file, update the index and note it in the log.
+- **Newest entries first.** Old entries at the top invert the timeline.
+- **What changed + the durable lesson, a few lines.** Full narratives are recoverable
+  from git (`git log --follow log.md`); never re-expand one in place.
+- **Laws and incidents, never bookkeeping.** No per-file inventories, no run-by-run
+  numbers, no transcripts. Measured numbers still have to pass the purpose test.
+- **Link, do not duplicate.** Knowledge that outlives the entry belongs on its concept
+  page; the entry points there.
+- **One dated section per day** (`## YYYY-MM-DD`), and mention `index.md` whenever a
+  file is added or removed. Several campaigns on one day share the section: a single
+  `##` date, one `###` per campaign — three `## 2026-10-21` headings is three logs
+  wearing one date. The entry law is also restated in the repo's `AGENTS.md` (the
+  always-loaded tier); change one, change the other.

 ### Common Mistakes

- ❌ Writing `"Updated ghostty.md"` — Updated it with what? Be specific.
- ❌ Forgetting to write to `log.md` — This is the equivalent of doing surgery without keeping a record.
- ❌ Using relative paths — Use absolute paths (`/docs/ghostty.md`).
- ❌ Leaving stale entries from manual edits — The log is the single source of truth.
+- ❌ `Updated ghostty.md` — updated it with what, and what did it teach?
+- ❌ Forgetting the entry — the change lands undocumented and the next agent rediscovers
+  the failure the hard way.
+- ❌ Starting a second log in a subdirectory — the sprawl that makes logging useless.
+- ❌ Invented paths in links — the RECOMMENDED form is an absolute bundle path
+  (`/tools/index.md`), resolved against the bundle root; the mistake is a path that
+  names no file there, and that is what the linter reports.
+- ❌ Re-expanding an old entry in place — the entry is a pointer; git is the transcript.

 ---

@@ -84,6 +101,14 @@ OKF is built on the principle that a file is one concept.
 - ❌ Don't create a file called `misc.md` — `misc` is a graveyard, not a category.
 - ❌ Don't use `# Other` or `# Additional Notes` sections — these are taping things to the wall.

+## Quarantine, Not Deletion
+
+A page is never deleted outright: it moves to `.AGENTTRASH/` beside where it lived and
+waits for a pruning session with Frank present. The quarantine is not part of the
+bundle — `scripts/kb-lint.sh` and `scripts/kb-coverage.py` skip any path containing
+`.AGENTTRASH`. That exemption is deliberate: a gate that goes green only once the
+quarantined copy is gone is a gate that deletes history.
+
 ---

 ## Auto-Generation Strategies
@@ -20,8 +20,13 @@ timestamp: 2026-01-15
 > optional trust/lifecycle fields (`verified: { by, at }`, `status`,
 > `stale_after`) and the `Attested Computation` type, and permits `okf_version:`
 > frontmatter in a bundle-root `index.md`. This bundle stays on v0.1 semantics
-> (kb-lint enforces them); the bundle-local `verified:` date stamp and `tags`
-> discipline are producer extensions compatible with both versions.
+> (`kb-lint` enforces them). What the optional fields mean HERE, measured 2026-10-21:
+> `description` on every concept page; `tags` on 22 of 76 concept pages and no tool reads
+> them; `resource` only where the page describes an external thing; `verified: YYYY-MM-DD`
+> = "the facts on this page were re-checked against the fleet that day", and a page with no
+> `verified` has never been re-checked. House link style is bundle-absolute
+> (`/tools/niri/tips.md`) for anything crossing a directory. `[[wikilinks]]` are not OKF
+> links — this bundle's 53 of them were converted to markdown links on 2026-10-21.

 # Open Knowledge Format (OKF) v0.1

@@ -42,7 +47,7 @@ An OKF knowledge bundle is a directory tree. Every concept is one file. The file
 ```
 my-bundle/
 ├── index.md                      # Optional directory listing
-├── log.md                        # Optional update history
+├── log.md                        # The bundle's ONE update history — root only
 ├── concept-one.md                # A concept at the root level
 └── subdirectory/
    ├── index.md                  # Optional subdirectory listing
@@ -55,7 +60,13 @@ my-bundle/
 | Filename | Purpose |
 |----------|---------|
 | `index.md` | Directory listing for progressive disclosure |
-| `log.md` | Chronological update history |
+| `log.md` | Chronological update history — **exactly one, at the bundle root** |
+
+**One work log per bundle.** `log.md` is reserved, and it is reserved for a single
+file: the bundle root's. A subdirectory never keeps its own change log — a bundle
+that logs in fifty places has no log, because the entry is never where the next
+reader looks and every copy re-dates the same event. `scripts/kb-lint.sh` reports
+any `log.md` that is not the root's.

 ---

@@ -161,3 +172,9 @@ Everything else is soft guidance. Consumers MUST NOT reject a bundle because of

 - [OKF Bundle Maintenance](okf-maintenance.md) — How to keep your bundle from rotting.
 - [Root Index](/index.md) — This bundle's structure and navigation.
+
+# Citations
+
+- [GoogleCloudPlatform/open-knowledge-format](https://github.com/GoogleCloudPlatform/open-knowledge-format)
+  — upstream repository: the v0.1 specification this page summarizes and `SPEC.md` for v0.2
+  (read 2026-10-19).
--- a/Show More
+++ b/Show More
				`@@ -0,0 +1 @@`
				`{"v":1,"kind":"correction","statement":"stop it! it works!","source":"explicit_user","evidence":"stop it! it works!","friction":{"corrective":true,"regression":true,"subtle":false},"sessionId":"01a15cbe-157e-7527-b4b5-22f3d2feea00","ts":1792563942225}`