@r1z4x/tezgah 1.0.0

package/docs/operations.md

@@ -0,0 +1,666 @@
+# Operations: install, upgrade, repair
+
+This is the operator's page: how to arm tezgah, prove each
+[host](glossary.md#host) is wired, and what to check first when one is not.
+`bin/tezgah-setup` is the one entry point; what a host receives is
+[hosts.md](hosts.md), what a session is told is [contract.md](contract.md), and
+every environment variable the installer and the hooks read is
+[environment.md](environment.md).
+
+## Installer flags
+
+The parser's own arguments (`bin/tezgah-setup::main`); a bare run with no
+argument prints the wizard on a terminal and the report on a pipe (`bin/tezgah-setup::report`).
+Lines below are of `bin/tezgah-setup`; the early branches (`bin/tezgah-setup::main`) return
+before an install is considered.
+
+| Flag | What it does |
+|---|---|
+| `--install` | Arm the `--hosts` (default: every detected host): writes `~/.config/tezgah/config.json`, the contract hash, the `~/.config/tezgah/bin` symlinks and every host file, then prints the report. Installs the missing optional tools first unless `--no-deps`; third-party host CLIs (cursor-agent, pnpm, dsh) only with `--host-deps`, otherwise their exact install command is printed. Exits 1 when a requested tool is still missing, naming the cause (`installer failed with exit N`, or `exited 0 but not on PATH`) (`bin/tezgah-setup::main`, `bin/tezgah-setup::install_all`, `bin/tezgah-setup::install_deps`). It also exits 1 when a planned host is left unarmed, and names it under `not armed:`. Only the arming rows count: hooks wired, the contract current, and the row a host's own CLI arms where that CLI exists: omp's extension row with an omp CLI, Claude's `plugin copy current` with a `claude` CLI. Codex `hooks trusted` and the provider-key rows stay out, because a correct fresh install leaves them MISS (`ARMING_ROWS`, `arming_miss()`). A host config that does not parse as a JSON object is refused: the run names the file and the parse error, never writes it, and exits 1 (`read_config()`); tezgah's own `config.json` is refused the same way. Claude is registered through its own CLI (`register_claude_plugin()`): the run renders `.claude-plugin/{plugin,marketplace}.json` from the release version into the tree it runs from (untracked; a pair under another marketplace name is kept), runs `claude plugin marketplace add <tree>` (a directory source pinned to that tree) and `claude plugin install tezgah@tezgah-local`, and skips both when any `tezgah@*` row is already in `installed_plugins.json`, because a second row fires every hook twice. `--reply-lang tr|en|any` stores `reply_lang` in `config.json`; without it the stored value stays, and a config with none reads as `tr`. |
+| `--wizard` | Ask the install questions and write only after the final yes; the other flags supply the defaults, so `--wizard --hosts omp` asks only the rest (`bin/tezgah-setup::wizard`). |
+| `--report` | Print what is armed, per host, and stop (`bin/tezgah-setup::main`, `bin/tezgah-setup::report`). |
+| `--report --live` | Proves the hooks run, not only that they are written (audit Phase 1.2). For each host, one synthetic PostToolUse (`true`) goes through that host's own wiring: the command in `~/.codex/hooks.json`, `~/.cursor/hooks.json`, the enabled Claude plugin copy's `hooks/hooks.json` (with `CLAUDE_PLUGIN_ROOT`), the hooks.json named by dsh's `cordis.patch.yml`; the opencode plugin is imported with node the way opencode imports it; the omp extension `.ts` is loaded with node `--experimental-strip-types` after checking it is in omp's `extensions` list. A ledger row for a dedicated `tezgah-live-<pid>-<ms>` session must appear; the event runs against a throwaway root (`TEZGAH_ROOTS`) and every cache file named for that session is deleted afterwards. A second probe per host proves the gate: one PreToolUse for `git commit --no-verify -m x` through the same wiring must come back as that host's deny (Claude, Codex and dsh `permissionDecision: deny`, Cursor `permission: deny`, omp `block: true`, opencode a throw) and leave a `deny` row in the ledger; under `pretooluse-off` or `verify-off` it reads UNVERIFIED and names the switch (`live_probe()`, `LIVE_DENY_COMMAND`). The omp bridge must also match a fresh render byte for byte, from the renderer the install writes with (`omp_bridge()`). Rows read `ok live <host>` / `ok live <host> deny`, `MISS live <host>: <cause>` (no tezgah command in the host file, the command wrote no row, no deny envelope or no deny row, a hand-edited omp bridge, Codex does not trust tezgah's group) or `UNVERIFIED live <host>: <why>` (node missing or older than 22.6, the omp CLI did not answer, a switch that stands the refusal down). It exits 1 when any host is MISS; UNVERIFIED never fails the run and is never shown as ok. No model is called. |
+| `--refresh` | Re-render every always-on contract artifact of the armed hosts - the managed blocks of `CLAUDE.md`, Codex's `AGENTS.md` and omp's `RULES.md`, opencode's contract and skill routers - after a policy edit or a kill switch; prints the paths it refreshed, else `contract is current`. Before the first install there is no hash record, so it changes nothing (`refresh_contract`, `bin/tezgah-setup::refresh_contract`). |
+| `--uninstall` | Remove everything tezgah installed — per host the wiring it wrote, plus (a full run) the Claude plugin copy with its registry rows, the generated config state, the kill switches, the caches and the versioned install tree — then verify the removal; nonzero exit while anything tezgah wrote survives (`bin/tezgah-setup::verify_uninstall`, `bin/tezgah-setup::uninstall`). |
+| `--adopt` | Move pre-tezgah wiring aside instead of deleting it; alone it stops there, with `--install` it runs first (`bin/tezgah-setup::main`, `bin/tezgah-setup::adopt`). |
+| `--sync` | Copy this checkout over every installed Claude plugin [copy](glossary.md#plugin-copy) (`bin/tezgah-setup::sync`). Each copy is built in a staging tree beside the plugin cache and swapped in with two renames, its `.git` carried over, so a failed or killed sync leaves the previous copy whole (`bin/tezgah-setup::_swap`). Every copied file is 0644, or 0755 when the tree marks it executable, whatever mode the source has (`bin/tezgah-setup::_copy_normalised`). |
+| `--hook-entries` | Print, as JSON, the tezgah-owned hook entries this tree arms per armed host - what `tezgah update` asks the new tree for (`bin/tezgah-setup::hook_entries`). |
+| `--status [PATH]` | Print the armed/used checklist for PATH (default cwd) and stop — the same line as `bin/tezgah-status` (`bin/tezgah-setup::main`, `hooks/tezgah_context.py::health_lines`). It also prints the report's `config.json hosts (...) match the hosts wired (...)` row when the recorded list and the wiring on disk disagree (`hosts_row`), and nothing when they agree: install health is checked here, not only in a full report. |
+| `--agents [PATH]` | Regenerate PATH's per-repo subagent set (default cwd); outside a [root](glossary.md#root) it prints `no agents generated` (`bin/tezgah-setup::main`). |
+| `--write-manifest` | Regenerate the tracked `MANIFEST` from `git ls-files` and stop — the release step, its only writer, and it says so on a tree with no `.git` rather than writing an empty listing (`bin/tezgah-setup::write_manifest`, `bin/tezgah-setup::plugin_files`). |
+| `--write-plugin-agents` | Re-render the plugin's tracked `agents/*.md` from the role bodies `hooks/tezgah_agents.py` generates per repo, and stop — the release step that keeps the shipped reviewer from drifting from the generated one; `tests/test_agents.py` fails until it has run (`write_plugin_agents`, `plugin_agents`). |
+| `--deps` | Install the missing optional tools and stop; with `--install` the install already does it. Like `--install` and `--enable`, it exits 1 when a requested tool is still missing (`bin/tezgah-setup::main`). |
+| `--host-deps` | With `--install` or `--deps`, also install the missing third-party host CLIs (cursor-agent, pnpm, dsh). They are opt-in because each one is a vendor `curl \| sh` that uninstall does not take back. Every installer runs with a 600 s timeout, each `curl` with `--max-time 300` and each pipeline under `pipefail`, so a stalled or refused download fails instead of hanging or reading as success (audit M-9). |
+| `--mcp-schemas` | Measure the MCP tool-schema band by asking each registered server (`initialize` + `tools/list`) and stop (`bin/tezgah-setup::main`, `bin/tezgah-setup::mcp_schema_report`). |
+| `--no-deps` | Skip the optional-tool install; `TEZGAH_NO_DEPS` is the same switch for CI (`bin/tezgah-setup::main`, `bin/tezgah-setup::install_deps`). |
+| `--devtools` | Also wire the optional Chrome DevTools MCP (`bin/tezgah-setup::DEVTOOLS_FEATURE`). |
+| `--features` | Print every feature id with its default, its selection and its dependency state; an unmet one names why and the command that would satisfy it (`features_report`, `bin/tezgah-setup::features_report`). |
+| `--enable ID[,ID]`, `--disable ID[,ID]` | Select or deselect features and persist the choice in `config.json`. An enable satisfies the named features' dependencies in the same run (an embedding id fetches and converts its model, see [below](#opt-in-embedding-relevance)); a disable runs no installer and removes only a file tezgah made for the row (`select_features`, `bin/tezgah-setup::select_features`). |
+| `--dry-run` | Print what the optional-tool install would run, and run none of it (`bin/tezgah-setup::install_deps`). |
+| `--prefix DIR` | Set the install prefix for this run: where a released artifact unpacks, and the second root a farm link may resolve into along with the checkout. It wins over `TEZGAH_PREFIX`, which wins over `$XDG_DATA_HOME/tezgah`, which wins over `~/.local/share/tezgah` (`bin/tezgah-setup::main`, `bin/tezgah-setup::INSTALL_PREFIX`). |
+| `--upgrade [VERSION]` | Move the install tree to VERSION (default: the newest release): `packaging/upgrade.sh` fetches it, checksum-verifies it, checks its build provenance with `gh attestation verify` when `gh` is on PATH (and says `provenance not checked` when it is not), unpacks `<prefix>/<VERSION>` and flips `current`, then the installer re-runs **from the new tree** after the hook-entry change is printed; `--dry-run` prints every step and runs none (`bin/tezgah-setup::upgrade`). |
+| `update` | `tezgah update [--dry-run]` moves this install to the newest release through the channel it came from, then re-arms the hosts from the new tree. A release prefix goes through `--upgrade`. A Homebrew keg runs `brew upgrade r1z4x/tezgah/tezgah`, an npm tree runs `npm install -g @r1z4x/tezgah@latest`, and a git checkout runs `git pull --ff-only` (`update()`, `hooks/tezgah_update.py`). Before re-arming it prints every tezgah hook entry the new tree adds, removes or changes, per host. Paths compare with the tree root taken out, so a move to the new release's own path is no change. A real change on a terminal waits for a yes; Enter is no. A piped run goes on without asking (decision 12; `hooks/tezgah_update.py::confirm_rearm`). A no exits 1 after the fetch and says what it left. A checkout or an npm package is replaced in place, and the prefix's `current` already points at the new tree, so there the hooks run the new code and only the changed entries wait. A Homebrew keg is new beside the old one, so hooks wired to the old keg's path run the old code until the re-arm (`NOT_REARMED`, `hooks/tezgah_update.py::NOT_REARMED`). |
+| `--version` | Print the plugin version and exit (`bin/tezgah-setup::main`, `hooks/tezgah_context.py::version`). |
+| `--roots R` | Set the roots for this install, `os.pathsep`-separated. Without `--install` it exits 1: `--roots only means something with --install` (`bin/tezgah-setup::main`). |
+| `--hosts H` | Comma-separated subset of `claude,codex,opencode,cursor,dsh,omp`; an unknown name exits 1 before anything is written, and naming hosts switches off the re-detection that follows a tool install (`bin/tezgah-setup::main`, `bin/tezgah-setup::install_all`). |
+| `-h`, `--help` | Usage and the list above (`bin/tezgah-setup::main`). |
+
+A green `--report` says the wiring is on disk; `--report --live` says it ran. What it cannot cover is the host binary itself: it runs the command the host would run, not the host, so a host that refuses to load its own config (a Claude plugin disabled in the UI after the check, a dsh build whose bridge drops the event) still needs a real session to show.
+
+
+## Install from the artifact
+
+What a user receives is a release tarball, not this checkout:
+`dist/tezgah-<version>.tar.gz` beside `dist/tezgah-<version>.tar.gz.sha256`,
+built by `packaging/build.sh` from the tracked `MANIFEST` plus a generated
+`VERSION`, both written into the payload (`packaging/build.sh:4`,
+`packaging/build.sh:61`, `packaging/build.sh:137`). A version unpacks at
+`<prefix>/<version>` and `<prefix>/current` is a symlink to the active one, so a
+team can stay on one version and a rollback is one tree away: the older version is
+never removed, and going back is
+`ln -sfn <prefix>/<previous> <prefix>/current` (`packaging/upgrade.sh:9-11`,
+`packaging/upgrade.sh:118-137`). The prefix is `~/.local/share/tezgah` unless
+`TEZGAH_PREFIX` or `$XDG_DATA_HOME` says otherwise (`packaging/upgrade.sh:63`),
+and `bin/tezgah-setup --prefix DIR` wins over both (`bin/tezgah-setup::INSTALL_PREFIX`).
+A farm link counts as tezgah's when it resolves into the checkout **or** into the
+install root, which is what keeps an upgrade from orphaning the wiring
+(`is_tezgah_link()`, `bin/tezgah-setup::is_tezgah_link`).
+
+| Step | Command |
+|---|---|
+| first install, POSIX | `curl -fsSL https://raw.githubusercontent.com/r1z4x/tezgah/v<version>/packaging/install.sh \| sh -s -- --version <version>` |
+| from a tarball you hold | unpack it, then `sh packaging/install.sh --version <version>` — it finds `upgrade.sh` beside itself (`packaging/install.sh:30-32`) |
+| first install, Windows | `$env:TEZGAH_VERSION = '<version>'; irm https://raw.githubusercontent.com/r1z4x/tezgah/v<version>/packaging/install.ps1 \| iex` |
+| upgrade | `tezgah update` (any channel), `bin/tezgah-setup --upgrade [VERSION]` from the installed tree, or `sh packaging/upgrade.sh --version X.Y.Z` |
+
+`packaging/install.sh` is a bootstrap, never a second implementation: it runs
+`packaging/upgrade.sh` — the one place a version is fetched, checksum-verified,
+unpacked and made current — and then starts `bin/tezgah-setup --install` from the
+tree that just became current (`packaging/install.sh:44-56`). `upgrade.sh`
+compares the digest it fetched against the artifact before unpacking anything and
+stops, printing both, on a mismatch (`packaging/upgrade.sh:88-96`). It then
+checks the tarball's build provenance with `gh attestation verify` when `gh` is
+on PATH. Without `gh` it prints `provenance not checked`, and a `gh` that cannot
+answer is a warning: the checksum stays the gate.
+`TEZGAH_DIST` points `upgrade.sh` and `install.ps1` at a directory holding
+`tezgah-<version>.tar.gz` + `.sha256` instead of the release URL — the seam that
+installs a locally built artifact with no published release, which is what CI
+uses (`packaging/upgrade.sh:17-21`, `packaging/upgrade.sh:74-78`).
+
+Windows goes through `packaging/install.ps1`, which assumes no `sh`, no `python3`
+and no symlink privilege: it unpacks with the `tar.exe` that Windows 10 1803+
+ships, materialises `current` as a directory junction, copies the tree where a
+junction is refused, and starts the installer with the first of `py -3`,
+`python`, `python3` it finds, passing `--prefix` on (`packaging/install.ps1:12-23`,
+`packaging/install.ps1:128-163`). The installer knows both shapes of `current`
+(`bin/tezgah-setup::running_prefix`). A junction answers to
+`os.path.isjunction`, or to its reparse tag below Python 3.12. A copy is the
+running tree at `<prefix>/current` with no `.git`, whose `VERSION` names a
+version tree beside it. A checkout cloned as `current` is not a copy. So
+`tezgah update` finds the release prefix and `--uninstall` removes it.
+`--upgrade` on Windows runs `install.ps1 -NoInstall` in place of
+`packaging/upgrade.sh` and then re-arms from the new tree. A missing `bash` (or
+`powershell`) is a refusal that names it (`bin/tezgah-setup::upgrade`).
+
+An unpacked tree lists itself without git. `plugin_files()` reads `git ls-files`
+in a checkout and falls back to the tracked `MANIFEST` where there is no `.git`; a
+missing or empty manifest answers `None`, which is what makes `--sync` refuse
+instead of emptying a copy it cannot refill (`plugin_files()`,
+`bin/tezgah-setup::plugin_files`). `MANIFEST` is written by `--write-manifest`, its
+only writer, from the same filter the reader applies — `managed()` — so the
+listing and its reader cannot disagree (`managed()`, `bin/tezgah-setup::managed`,
+`write_manifest()`, `bin/tezgah-setup::write_manifest`). The payload also carries
+`VERSION`, which is what a tree with no `.claude-plugin/` answers from
+(`version()`, `hooks/tezgah_context.py::version`).
+
+## A first install from a checkout
+
+```bash
+git clone https://github.com/r1z4x/tezgah.git ~/Projects/tezgah
+cd ~/Projects/tezgah && bin/tezgah-setup --install
+```
+
+`--install` arms every host it detects; the optional integrations belong to the
+[README's Install section](../README.md#install). On a terminal the bare
+`bin/tezgah-setup` is the wizard: it asks which hosts, the roots, whether to
+install the missing optional tools (host CLIs only with `--host-deps`) and whether to wire the DevTools MCP, prints
+the plan, and writes only after a yes (`bin/tezgah-setup::wizard`). A pre-tezgah setup is
+named under `predecessor wiring still present` and retired by `--adopt`
+(`bin/tezgah-setup::adopt`); narrow it with `--hosts omp`, `--roots ~/work:~/oss`, `--dry-run`.
+
+An install from a checkout is a live symlink into that working tree, so a half-finished edit or a branch switch there crashes the sessions running on it (the `crash` ledger rows of 09-20..09-21 were names removed mid-edit) - do tezgah maintenance in a `git worktree`, never in the installed checkout.
+
+The `~/.config/tezgah/bin` farm carries `tezgah-mcp` and `tezgah-design` beside the other CLIs; two are left out on purpose: `tezgah-dsh` is wired as `~/.local/bin/dsh` (`dsh_launcher`), and `tezgah-import-ai-research` is dev-time only (its docstring). The report's `config.json hosts (...) match the hosts wired (...)` row (`hosts_row`) reads `MISS` when the recorded host list differs from the hosts whose wiring is on disk; `--upgrade`, `--enable`/`--disable` and a full uninstall act on the recorded list, so the row only reports it - `--install --hosts ...` records the list you choose.
+
+A successful run prints, in order: `dependencies:`, a line per missing optional
+tool with the vendor command it runs — over the network, no sudo
+(`bin/tezgah-setup::install_deps`) — or `all optional tools present` (the run is appended to
+`~/.config/tezgah/install.log`, `bin/tezgah-setup::_dep_log`); `installing for: <hosts>`
+(`bin/tezgah-setup::install_all`); the common block — config and roots, the contract sha, one `ok` line
+per `~/.config/tezgah/bin` symlink, the app artifacts dir (`bin/tezgah-setup::install_common`);
+`openresearch (orx):`, a line per host orx has a harness for (`bin/tezgah-setup::install_openresearch`); one
+`ok` line per link or write inside each host's block (`bin/tezgah-setup::INSTALLERS` — a write that
+met a real file in the way says so instead, `bin/tezgah-setup::link`); then the report and the
+context budget table (`bin/tezgah-setup::report`, `bin/tezgah-setup::context_budget_report`). Its tail:
+
+```text
+omp:
+    ok   status line answers
+context budget (always-on text; ~tokens = chars/4):
+     MCP tool schemas                   run --mcp-schemas to measure
+```
+
+## Verify: the report and `--status`
+
+`--report` (or a piped bare run) answers one question per host: is it wired? It
+prints the checkout, the roots and where they came from (`TEZGAH_ROOTS`, `config`
+or `default`), a common block (config, the code-graph binary, the consult options, a codegen key,
+`orx`, `npx`, the artifacts dir, `git`, the manifest, a stale-contract line), one
+block per host, then the budget (`bin/tezgah-setup::report`). Each block is
+`host_checks_<host>` (`bin/tezgah-setup::HOST_CHECKS`), and those rows are the source of truth for
+"is this host armed" (`AGENTS.md:136-137`) — not the presence of a directory, and
+not the status line. A row can read ` MISS ` too: claude's `plugin copy current`
+row fails on a machine with no copy at all, because an absent copy is not a
+current one (`bin/tezgah-setup::host_checks_claude`).
+
+`--status [PATH]` answers a different question — which rules are in force in that
+repo — as one line of marks rendered by the same code every status line uses
+(`hooks/tezgah_context.py::health_lines`, `hooks/tezgah_context.py::render_line`). Mark meanings are in
+[status-line.md](status-line.md); `bin/tezgah-status` is that checklist with
+`--json`, `--legend` and `--observable=`. It carries the report's host-list row
+too, from the same `hosts_row`, so the mismatch reaches the surface a session
+checks its own health with. Two places deliberately do not: the status line's
+marks are the armed/used checklist and are redrawn by a fresh process on every
+host (omp re-renders per tool result), while "wired" is `HOST_CHECKS`, the
+installer's own reading of six host files — a second reading of it in `hooks/`
+would be the drift `AGENTS.md` names as the report's source of truth; and
+`bin/tezgah-doctor` accounts for the bytes the hosts' stores hold and never reads
+a host's config, so a wiring row there would belong to a different tool.
+
+## Upgrading
+
+The version lives in `.claude-plugin/plugin.json` when that untracked local
+manifest is present, else in the newest `## [x.y.z]` heading of `CHANGELOG.md`
+(`hooks/tezgah_context.py::version`); `.gitignore:16-19` is why it is not in the repository, and
+`RELEASING.md:19-24` is how a release bumps it. A `--install` that registers
+Claude renders the pair into its tree. The version comes from `VERSION` or that
+heading, never from the pair itself. A pair the install rendered follows the
+version when it moves.
+
+An installed version moves with one command, and nothing moves it on tezgah's own
+initiative: a session may not install, upgrade or restart tezgah's own
+installation (`hooks/tezgah_policy.py::CORE`). `bin/tezgah-setup --upgrade
+[VERSION]` runs `packaging/upgrade.sh --version V --prefix P`, then re-runs the
+installer **from the new tree** — this process started from the old one, so its
+farm links would point back into it — with the hosts and roots already in
+`config.json`, so the install questions are not asked twice; the previous version
+stays installed, so a rollback is a `current` flip (`upgrade()`,
+`bin/tezgah-setup::upgrade`). It is the flag's only caller: no other flag
+upgrades tezgah as a side effect of another. `--upgrade --dry-run` prints the
+fetch, the flip and the re-arm and runs none of the three
+(`bin/tezgah-setup::upgrade`).
+
+The status line says when a newer release is out. A `↑X.Y.Z` chip sits beside
+the logo, in the version's own group, on every surface (`notice_segments()`,
+`hooks/tezgah_update.py`). A redraw only reads `~/.cache/tezgah/update.json`.
+When that file is a day old, the redraw stamps it and starts one detached
+check against the GitHub releases endpoint. An offline check writes nothing,
+and the next day asks again. `tezgah update` is the command the chip points
+at, and it is the only thing that moves the install. The
+`~/.config/tezgah/update-check-off` switch stops both the check and the chip.
+`tezgah` is also a farm link and a Homebrew name, so the command reads the same
+on npm, Homebrew and a checkout.
+The chip offers the public release to an install on any retired 0.x (0.1.0 to
+0.33.0, `hooks/tezgah_update.py::RETIRED`), and reads `↑1.0.0 (line reset)`.
+
+After a change to the contract text (`hooks/tezgah_policy.py`,
+`hooks/tezgah_context.py`, `skills/tezgah-contract/SKILL.md`):
+
+- `--install` re-renders every host file, the opencode contract and the skill
+  router, and rewrites `~/.config/tezgah/contract.sha256`, which holds one
+  `<sha>  <path>` line per rendered artifact - the managed blocks of
+  `CLAUDE.md`, `AGENTS.md` and `RULES.md`, `opencode-contract.md` and the
+  `opencode-skills*.md` routers - rather than one hash over the sources
+  (`bin/tezgah-setup::record_shas`, `bin/tezgah-setup::contract_artifacts`).
+- `--refresh` does that without a reinstall, for every armed host's static
+  block and not only opencode's (`refresh_contract`). opencode has no
+  session-start hook, so its plugin runs it once per session
+  (`hosts/opencode/plugins/tezgah.js:2633-2637`). Until 2026-10-02 it
+  re-rendered opencode's files alone and reset the one shared hash, so a rule
+  edit left the other static files stale while `--report` went green (audit
+  M-5).
+- `--report` compares each artifact's bytes with a fresh render and prints
+  `always-on contract stale: <path>` for each one that differs; the
+  "carries the contract" rows make the same byte comparison.
+- A global kill switch (`adhd-off`, `verify-off`, `spec-off`, `consult-off`,
+  `research-off`, `exec-mode.off`, `ponytail-auto.off`, `lang-off`,
+  `workspace-off`) removes its paragraph from the static files on the next
+  `--refresh` or `--install`; a per-repo `.no-*` mark leaves the global files
+  alone, because they serve every repository (audit L-1).
+- `--sync` copies the checkout over the Claude plugin copy, because Claude Code
+  runs `~/.claude/plugins/cache/<owner>/tezgah/<version>/` and never this
+  checkout (`bin/tezgah-setup::sync`); `--install` refreshes a stale copy itself
+  (`bin/tezgah-setup::refresh_plugin_copy`). Then restart Claude — hooks are read once per session.
+
+From the user's side a stale copy looks like this: Claude keeps applying the old
+rules while `--report` shows ` MISS plugin copy current (every copied file
+matches)`. That row compares a sha256 over every tracked file `sync` copies —
+not the version number both trees report, and not a single file: a one-file hash
+cannot see a change to another hook, which is how a gate change once left the
+installed copy running the previous rules while `--install` printed `ok`
+(`bin/tezgah-setup::plugin_copy_current`, `bin/tezgah-setup::tree_sha`). Recognising a copy
+at all is still the presence of one file (`bin/tezgah-setup::plugin_copies`).
+
+## Uninstall and adopt
+
+`--uninstall` removes everything tezgah installed, then proves the removal. The
+run is **full** when it covers every host `config.json` records as armed, and
+**partial** otherwise (`uninstall()`, `bin/tezgah-setup::uninstall`). Both runs
+take the host wiring back - the skill symlinks, hook entries, managed blocks,
+MCP rows and status-line keys each host's own installer wrote
+(`bin/tezgah-setup::UNINSTALLERS`), plus the farm links and the generated repo agent
+files (`bin/tezgah-setup::remove_generated_state`, `bin/tezgah-setup::_marker_agents_files`). A link — or an entry the installer
+materialised where a platform refuses symlinks — counts as tezgah's only when it
+resolves inside this checkout or the install root, so a file you put in the same
+place is kept (`is_tezgah_entry()`, `bin/tezgah-setup::is_tezgah_entry`), and
+`~/.claude/settings.json` loses only the keys tezgah added
+(`bin/tezgah-setup::unwire_claude_settings`).
+
+A **full** run also takes everything the wiring was serving from:
+
+- the Claude plugin copy under `~/.claude/plugins/cache` and its rows in
+  `installed_plugins.json` — the tree Claude actually runs and the registry row
+  that makes it keep loading both outlived every other removal, which is how an
+  uninstalled tezgah kept applying its rules (`remove_plugin_copies()`,
+  `bin/tezgah-setup::remove_plugin_copies`). A marketplace row sourced from a tezgah tree
+  goes with them once nothing else installs from it.
+- the `~/.config/tezgah` generated state: config, contract hash, install log,
+  materialised ledger, the generated opencode files, and every kill switch —
+  the canonical ones with the dir, the legacy `~/.claude` ones by name
+  (`remove_generated_state()`, `bin/tezgah-setup::remove_generated_state`;
+  `sweep_legacy_switches()`, `bin/tezgah-setup::sweep_legacy_switches`).
+- both state caches (`~/.cache/tezgah` and the sandbox fallback).
+- the versioned install tree: every `<prefix>/<version>` carrying
+  `bin/tezgah-setup` plus the `current` flip (`remove_install_tree()`,
+  `bin/tezgah-setup::remove_install_tree`).
+
+Kept in every run: the user's own files, every `.tezgah-bak` backup
+outside the config dir (the timestamped ones too), `~/.config/tezgah/adopted/` (the only copy of the
+predecessor wiring adopt moved aside), and every repository's `.tezgah/`
+research state. A **partial** run also keeps config.json and the install tree,
+because the hosts still armed read both at runtime, and says so. It also leaves
+the gate armed: only a full run writes `pretooluse-off` while it removes the
+hooks. A partial run used to write it too and never take it back, so the hosts
+still armed lost the whole gate (audit H-2, ENV-01). The orx skill
+shims come from orx's own installer, so they are never listed for removal
+(`bin/tezgah-setup::install_openresearch`).
+
+Every run ends in a verify pass that re-derives the removal from the filesystem
+alone — one line per claim, and the exit code is 1 while anything tezgah wrote
+survives (`verify_uninstall()`, `bin/tezgah-setup::verify_uninstall`), so a leftover can
+never read as a clean uninstall. It ends by naming what needs a restart and, in
+a git checkout whose own `.mcp.json` registers the tezgah MCP server, saying that
+that file is the source tree's dev config, not an install artifact. An npm or
+artifact install does not ship `.mcp.json` (it is neither in package.json
+`files` nor in `MANIFEST`), so it never prints that note (audit L-12).
+`tests/e2e_docker_cycle.py` makes the same claim in a clean container with an
+independent path scan that imports nothing of tezgah's.
+
+`--adopt` moves, never deletes: `~/.codex/projects-harness`, the old codex bin
+shims that exec'd it, the older harness's `~/.claude/hooks/cbm-*` files (a
+name that predates tezgah's own graph engine; the probe stays because
+those files are the thing adopt has to retire), the hook entries in
+`~/.codex/hooks.json` and `~/.claude/settings.json` that called them, and the
+projects-harness marker block in a root's `AGENTS.md` — a block that points
+every session at a POLICY.md inside the moved harness, so leaving it is leaving
+a dead pointer — all go to `~/.config/tezgah/adopted/<timestamp>/`
+(`bin/tezgah-setup::adopt`). `predecessors()` is what
+the report prints and what adopt retires (`bin/tezgah-setup::predecessors`). Under the wizard adopt
+waits for the yes: a declined plan leaves the predecessor wiring exactly where it
+was (`bin/tezgah-setup::wizard`).
+
+## Migrate legacy state: `tezgah-migrate`
+
+Per-project tezgah state lives only under `<repo>/.tezgah/`, ignored by the
+project and versioned by its own private repository at `.tezgah/.git`. Older
+installs left it elsewhere: a `.tezgah/` the project tracked, a root `plans/`,
+`analysis/` or `research/`. `bin/tezgah-migrate` finds those and moves them
+(`bin/tezgah-migrate::make_plan`):
+
+- a tracked `.tezgah/` is untracked with `git rm -r --cached` and stays on disk;
+- a root `plans/` in tezgah plan format (an `open/` or `done/` directory, or a
+  README with the status markers, `bin/tezgah-migrate::is_plan_tree`) goes into
+  `.tezgah/plans/`, `analysis/` into `.tezgah/analysis/`, and `research/` into
+  `.tezgah/analysis/imported-research/`; a tracked source is removed from the
+  index, an untracked one is moved;
+- project-owned knowledge (`CLAUDE.md`, `AGENTS.md`, nested rule files,
+  `docs/research/`, `.claude/agents|skills|commands`, `.agents/`, `skills/`)
+  stays where it is and is indexed in `.tezgah/analysis/project-knowledge.md`
+  with its file count and first heading (`bin/tezgah-migrate::knowledge_index`);
+- the workspace is ensured (`/.tezgah/` and `/.codegraph/` in `.gitignore`,
+  `git init` in `.tezgah`) and its content committed there as `import from
+  project history <short sha>`.
+
+A file whose name already exists at the destination with other content is
+reported as `skip` and left in place; an identical duplicate only loses its
+source (`bin/tezgah-migrate::plan_move`).
+
+With no `--repo` it walks every repository directly under each configured root
+whose `.git` is a directory, skipping the tezgah checkout
+(`bin/tezgah-migrate::discover`). It is a dry run by default: one `would` line per
+action and a `=` summary per repo. `--apply` first writes every path it will
+touch to `~/.config/tezgah/backups/<repo>-<UTC stamp>.tar.gz`
+(`bin/tezgah-migrate::write_backup`), then performs the actions. It never commits in the
+project repository and never pushes: the result is an uncommitted change to
+review. A second `--apply` finds nothing to do.
+
+```sh
+tezgah-migrate                      # dry run over every root
+tezgah-migrate --apply --repo ~/Projects/app
+```
+
+## Health pass: `tezgah-doctor`
+
+`bin/tezgah-doctor` reports the stores that grow without bound — opencode's SQLite
+session/event database and each indexed repository's `.codegraph` database — and
+the hosts' own state, which it never touches (`bin/tezgah-doctor:2-31`), read-only
+by default, with `--json` for a script and `--coverage` for the files the graph
+does not hold.
+
+| Invocation | What it does |
+|---|---|
+| `tezgah-doctor` | nothing: sizes, session and event counts, whether opencode is running, the two context-hygiene settings, the `.codegraph` bytes and index presence per repository, and the three host state dirs (`bin/tezgah-doctor::collect`, `bin/tezgah-doctor::report`) |
+| `tezgah-doctor --clean` | vacuums opencode's database, and only when opencode is not running (`bin/tezgah-doctor::vacuum_db`, `bin/tezgah-doctor::main`); and deletes tezgah's own hook state not modified for `--retention-days` (default 30) - the ledgers under `evidence/`, `turns/`, `sessions/`, `classify.log`, `context-drops.log` and `debug.log`, in the cache and its sandbox fallback - keeping the current session's (`$TEZGAH_SESSION`) files whatever their age (`sweep_state`) |
+| `tezgah-doctor --coverage` | every tracked file the codegraph index does not hold, in two classes — a supported extension the index is missing, and a shebang-only script with no `.py` twin — with the file counts it read, so an empty result cannot read as "everything is covered" |
+| `tezgah-doctor --prune-sessions DAYS` | deletes sessions idle longer than DAYS through `opencode session delete`, then vacuums; skipped when opencode is running or its CLI is missing (`bin/tezgah-doctor::prune_sessions`, `bin/tezgah-doctor::main`) |
+
+`VACUUM` alone cannot shrink that database — its pages are all live — so
+`--prune-sessions` is the action that actually reclaims space
+(`bin/tezgah-doctor:19-21`).
+
+The coverage report exists because codegraph ships none: its `status` counts what
+it parsed, never what it skipped, and the two ways a file goes missing are an
+extension the engine has no parser for and an extensionless script it cannot key
+on at all. The extensionless case is why `bin/*` carries `.py` twins, and the
+report counts a tracked `bin/x` as covered when the index holds `bin/x.py`.
+
+## Opt-in taste capture
+
+Phase 1 of a coding-taste learner stores the signals tezgah already receives.
+It learns nothing and injects nothing yet. It stays off until the user arms it
+with a `taste-on` file in `~/.config/tezgah/` (`enabled`,
+`hooks/tezgah_taste.py::enabled`). The off path costs two stats. Armed, it writes
+only into a repository that already has a `.tezgah/` directory. A `.no-taste`
+mark turns it off for one repository (`hooks/tezgah_context.py::repo_marks`).
+A workspace of repo-provided data gets nothing.
+
+Rows go to `<repo>/.tezgah/taste/signals.jsonl` through the ledger's own writer
+(`_write`, `hooks/tezgah_taste.py::_write`). A user turn adds a `prompt` row,
+redacted and cut to 2000 characters (`hooks/tezgah_taste.py::note_prompt`).
+A landed write adds an `edit` row with its redacted old and new text, cut to
+4000, under the ledger row's id. Each written file also adds an `after` row.
+It names a snapshot that holds the bytes the write left (`note_write`,
+`hooks/tezgah_taste.py::note_write`, called from `note_tool`,
+`hooks/tezgah_integrity.py::note_tool`). The after blob shares the snapshot
+store's limits and eviction. Armed, each landed write therefore keeps two blobs,
+and a session rollback reaches about half as far back. The after blob writes no
+ledger row. A rollback therefore never reads it as a pre-state (`capture_after`,
+`hooks/tezgah_snapshot.py::capture_after`). A file outside the repository gets no
+after blob.
+opencode reaches the same call through a process (`noteTaste`,
+`hosts/opencode/plugins/tezgah.js:2310-2319`).
+
+```sh
+touch ~/.config/tezgah/taste-on               # arm; rm it to disarm
+bin/tezgah-taste mine --host omp --stats      # sessions, writes, prompts after a writing turn
+bin/tezgah-taste mine --out mined.jsonl       # one row per such prompt, redacted
+bin/tezgah-taste measure --samples S --labels L   # judge precision/recall against labels
+bin/tezgah-taste rate --in mined.jsonl        # preference corrections per writing turn
+```
+
+`mine` reads the host transcripts already on disk, so it needs no capture. It
+reads omp's top-level session files and Claude's top-level transcripts whose cwd
+is under `--root` (`cmd_mine`, `bin/tezgah-taste::cmd_mine`). `measure` and `rate`
+send the sample text to the judge seam's provider ([judge](judge.md)), redacted
+first (`classify`, `bin/tezgah-taste::classify`). They use a fixed labelling rule
+(`RULE`, `bin/tezgah-taste::RULE`). Without a credential they send nothing.
+
+## Tidying the lessons ledger
+
+`.tezgah/lessons.md` is the user's file, so tezgah only proposes changes to it.
+
+```sh
+bin/tezgah-lessons                              # proposals for the repo in the cwd
+bin/tezgah-lessons --root DIR --fixture FX.json # plus recall@5 before and after the merges
+```
+
+It prints three kinds of line and writes nothing. `rewrite N` is a rule-first
+text for a line with no ` - ` in its first 120 characters (`rewrite`,
+`bin/tezgah-lessons::rewrite`). `merge A, B` names lines whose word-Jaccard is at
+least 0.2 (`clusters`, `bin/tezgah-lessons::clusters`). `retire N` names a line a gate
+rule or a test already enforces and the `|| enforced_by:` suffix for it
+(`RETIRE`, `bin/tezgah-lessons::RETIRE`). A rewrite is a heuristic over clause
+boundaries, so read it before applying it. With `--fixture`, it remaps the ground
+truth to the merged numbering and exits 1 when the merges would lower recall@5.
+
+The per-turn ranking passes BM25 a cap that the docs fallback does not
+(`LESSON_MAX_DF`, `hooks/tezgah_context.py::LESSON_MAX_DF`). English and Turkish function
+words rank nothing (`STOPWORDS`, `hooks/tezgah_rank.py::STOPWORDS`). On ten lines or
+more, neither does a word in more than half of them. On the private 12-prompt
+fixture over the 47-line ledger, recall@5 went from 0.647 to 0.675 with the cap.
+That is a figure about this ranker on that fixture, not production recall.
+
+## Opt-in embedding relevance
+
+The per-turn lessons block and the `tezgah-docs` fallback rank by shared words
+(BM25, `hooks/tezgah_rank.py`); the docs index also carries a Turkish phrasing of
+every title and answer (`title_tr`, `answers_tr`), so a Turkish question meets an
+English page. Two opt-in feature ids add a static embedding model - one vector
+per token, mean-pooled, read by a stdlib reader. The lessons block keeps BM25's
+order and adds a line by meaning only when its cosine reaches the model's floor
+(`fuse`, `hooks/tezgah_embed.py::fuse`). The docs fallback ranks pages by
+meaning alone (`nearest`, `hooks/tezgah_embed.py::nearest`). Both are off by
+default and a plain `--install` never fetches one (`feature_deps`,
+`bin/tezgah-setup::feature_deps`).
+
+```sh
+bin/tezgah-setup --enable embed-mrl    # fetch, convert, verify; then selected
+bin/tezgah-setup --features            # embed-mrl ... dep met
+bin/tezgah-setup --disable embed-mrl   # deselected, and the model file removed
+```
+
+| id | model (license) | download, then file | enable, measured | turn, measured |
+|---|---|---|---|---|
+| `embed-mrl` | `sentence-transformers/static-similarity-mrl-multilingual-v1`, first 128 of 1024 dims, int8 (Apache-2.0) | ~436 MB, then 15.1 MB | 24 s (download + 1 s conversion) | 0.24 s |
+| `embed-m2v` | `minishlab/potion-multilingual-128M`, base vocabulary, PCA to 128 dims, int8 (MIT) | ~531 MB, then 41.8 MB | 106 s (download + 75 s conversion) | 0.49 s |
+
+Measured 2026-10-03 on one Apple-silicon Mac, Python 3.10: the turn is a cold
+`bin/tezgah-context user_prompt` process over a 42-line ledger, median of five
+(0.155-0.19 s with the feature off), far inside the hooks' 8 s budget. The
+research line's own figure for `embed-mrl`, 0.13 s, is its median turn on its
+fixture, not this process.
+
+An enable downloads the pinned source files over HTTPS - repository, commit and
+sha256 of each are in `MODELS` (`hooks/tezgah_embed.py::MODELS`) - converts them
+with the standard library alone (`convert`, `hooks/tezgah_embed.py::convert`),
+checks the result against its own pinned sha256 and only then writes
+`~/.cache/tezgah/embed/<id>.bin`, mode 0600 in a 0700 directory; a mismatch at
+either end writes nothing (`fetch`, `hooks/tezgah_embed.py::fetch`). A fetch
+killed outright (the installer's timeout, Ctrl-C) skips that cleanup and leaves
+its partial download in a `.fetch-*` directory; the next `--enable` or
+`--disable` of either id deletes those directories (`_sweep`,
+`hooks/tezgah_embed.py::_sweep`).
+While it runs, each download and each conversion pass prints a progress line -
+`downloaded 212/436 MB 48%`, `quantised 7/13 chunks 53%` - rewritten in place
+on a terminal and printed once per 10% into a log (`_Progress`,
+`hooks/tezgah_embed.py::_Progress`).
+The conversion is bit-reproducible: the same bytes under Python 3.10 and 3.12 for
+both ids (and 3.9 for `embed-mrl`), and for `embed-mrl` byte-identical vectors to
+the research's numpy export.
+
+At hook time the model is read only when its id is selected and the file is the
+pinned one (`reader`, `hooks/tezgah_embed.py::reader`); a missing, altered or
+unreadable file, or any error, is BM25 exactly as before, and nothing at hook time
+touches the network. With both ids selected, `embed-mrl` is the one read: the
+registry lists it first. A ledger with no line older than the session block's
+last five never loads the model at all. With the feature on, a lesson that
+shares no word with the prompt joins only at a cosine of at least the model's
+floor. The floor is 0.30 for `embed-mrl` and 0.50 for `embed-m2v`. The docs fallback always
+prints three pages. `os.pread` is POSIX-only, so on Windows the feature reads as
+BM25. The uninstall's cache sweep removes the file with the rest of
+`~/.cache/tezgah`, and `--enable` fetches it anew.
+
+Measured by an internal research line on one Apple-silicon Mac. The
+prompts were 200 real ones over a 46-line ledger, and two blind raters labelled
+them. The old reciprocal-rank fusion put three lessons on every prompt with no
+topic, and 94% of what it injected was irrelevant. With the floor, 5 of the 29
+no-topic prompts get a lesson with `embed-mrl` (BM25 alone 3 to 4). Its recall@3
+is at most 0.02 above BM25's, with a lower bound of 0. With `embed-m2v` the
+floored ranking is close to BM25 itself. So the embedding buys the lessons block
+little, and it costs a model load on every prompt. With `embed-mrl` on the
+46-line ledger the landed hook still costs about 70 ms more than with the
+feature off. With `embed-m2v` it costs about 320 ms more. On a 2-line ledger the
+old hook cost 35 ms (`embed-mrl`) and 237 ms (`embed-m2v`) more for nothing. Now
+it costs nothing there. On held-out Turkish phrasings of the docs index,
+meaning alone found the page in the top three for 0.91 with `embed-mrl` and 0.78
+with `embed-m2v`. The fusion found it for 0.75 and 0.74, BM25 for 0.68.
+
+## Troubleshooting
+
+| Symptom | First check | Likely cause |
+|---|---|---|
+| A host shows no status line | `bin/tezgah-setup --report --hosts claude`, then `readlink ~/.claude/statusline.py` | that host's own rows read ` MISS `: the `statusline.py` symlink or the `statusLine` key (`bin/tezgah-setup::host_checks_claude`). For omp the row `status line answers` runs `hosts/omp/hook.py`, so it fails whenever the Python half cannot start (`bin/tezgah-setup::host_checks_omp`). codex has no status-line row at all — its surface is hooks, skills and MCP (`bin/tezgah-setup::host_checks_codex`) |
+| A skill is missing in one host | `ls ~/.codex/skills/*/SKILL.md` (the host's skills dir is in [hosts.md](hosts.md)) | the link was never made: that host was not in the last `--hosts`. `bin/tezgah-setup --install --hosts codex` relinks it. Claude has no skills directory — it reads the plugin copy, so the row to read there is `plugin copy current` (`bin/tezgah-setup::host_checks_claude`) |
+| A skill link dangles | `ls -lL ~/.omp/agent/skills/*/SKILL.md` | the link resolves to nothing: its source was renamed or removed, or the checkout moved. `skills_linked` asks for a readable `SKILL.md` precisely so this cannot read as linked (`bin/tezgah-setup::skills_linked`); `--install` relinks from what exists now |
+| A rule still fires after its kill switch | `ls ~/.config/tezgah/*.off`, then `bin/tezgah-context user_prompt . < /dev/null` | the switch was flipped mid-session: the rule leaves the text injected from the next turn on, but text already in the context is not retracted (`hooks/tezgah_context.py::switches`). The static files (`CLAUDE.md`, `AGENTS.md`, `RULES.md`, `opencode-contract.md`) drop a global switch's paragraph only when they are re-rendered, so run `tezgah-setup --refresh` (or `--install`) after flipping one. A per-repo `.no-*` mark does the same job as a switch file for the injected text, but it never edits the global static files (`hooks/tezgah_paths.py::OFF_DIRS`, `hooks/tezgah_context.py::repo_marks`) |
+| The status line is thinner outside the roots | `bin/tezgah-setup --status "$PWD"`, then `bin/tezgah-context session_start .` | by design, mostly: the line is global and only the per-repo `idx` and `plans` marks appear inside a root (`hooks/tezgah_context.py::health_segments`), while the injected contract text is exactly what goes silent off-root (`bin/tezgah-context:27-28`). A line that is empty everywhere is wiring: see the first row |
+| An agent cannot see the graph tools | `bin/tezgah-setup --report` — the common row `codegraph on PATH` and the host's own MCP row; then `which codegraph` | the binary is missing (it is the user's to install; `TEZGAH_CODEGRAPH_BIN` or `config.json`'s `codegraph_bin` can point at it, `hooks/tezgah_paths.py::codegraph_bin`), or the host's MCP row was overwritten and `--install --hosts <host>` rewrites it. `.no-graph` in a repo turns the code-graph rule off there (`hooks/tezgah_context.py::switches`) |
+| Claude keeps applying old rules | `bin/tezgah-setup --report --hosts claude` — the `plugin copy current` row; then `bin/tezgah-setup --sync` | the copy lags HEAD: Claude runs the copy, not the checkout. `--install` refreshes it too; restart Claude after either (`bin/tezgah-setup::install_all`, `bin/tezgah-setup::restart_hint`) |
+
+## Safety
+
+Reversible and safe to repeat: every link and settings key it writes is
+idempotent and re-created by `--install`. A write that changes a file first
+copies it to `<file>.<timestamp>.tezgah-bak`. The oldest of those copies is
+always kept, beside the newest four (`backup()`, `BACKUP_CAP`). The oldest is
+the file before tezgah's first timestamped write, which is tezgah's own content
+for a file tezgah created. On an upgraded install the pre-tezgah copy is the
+bare `<file>.tezgah-bak` an older release wrote, and the cap never prunes it.
+An unchanged write lays no backup. The installer
+never replaces a host config that does not parse (`read_config()`).
+`--adopt` moves and prints the destination
+(`bin/tezgah-setup::adopt`); `--uninstall` removes only tezgah's own entries — a
+symlink resolving into this checkout or the install tree, or an entry the
+installer materialised (`bin/tezgah-setup::materialised_paths`, `bin/tezgah-setup::is_tezgah_entry`) — and prints
+a verify pass whose nonzero exit says when anything survived; a bad write is
+undone with
+`bin/tezgah-rollback <snapshot-id> [--force]`, reaching the pre-write bytes
+through the id on the ledger's snapshot row (`bin/tezgah-rollback:1-13`,
+[evidence.md](evidence.md)).
+
+Not reversible, so do them deliberately: `--sync` deletes the plugin copy's
+contents (bar `.git`) and copies the checkout over it (`bin/tezgah-setup::_swap`) — it refuses
+a copy that holds this very checkout (`bin/tezgah-setup::sync`) — and
+`--prune-sessions` and `--clean` delete session rows and index logs. Two things
+this tool never does. It never force-pushes, rewrites pushed history, deletes a
+repo or branch, applies a migration to a live database, deploys, or touches a
+live account. And it never upgrades itself,
+or its optional tools and config, on its own initiative
+(`hooks/tezgah_policy.py::CORE`).
+
+## Triage: `tezgah-triage` and the `judge-off` switch
+
+One judgement seam serves five callers, each of them asking TypeSafe a batched
+question instead of paying an agent to read a page: the analyze-app loop's snapshot
+triage (`bin/tezgah-triage`), `bin/tezgah-docs` for a query its keyword index
+cannot place, and the prompt-path skill hint (`hooks/tezgah_skill_pick.py`), the
+one caller no shell row sees, `bin/tezgah-route`, the tier router
+([models](models.md)), and `bin/tezgah-taste`'s `measure` and `rate`
+([above](#opt-in-taste-capture)). All five go through the same stdlib-only seam,
+which returns `None` rather than raising because a hook may import it
+(`available()`, `hooks/tezgah_judge.py::available`); the request is
+one batched call, and the credential resolves per call (`ask()`,
+`hooks/tezgah_judge.py::ask`; `key()`, `hooks/tezgah_judge.py::key`).
+
+A transient failure is retried once, and only once: a timeout, a connection error
+or a 5xx gets a second identical request, while a 4xx (a refused credential, a
+rejected body) and a reply that parsed malformed are never retried, so a call that
+worked is never billed twice. The rate was measured rather than assumed - 184 live
+calls this round (60 at a small payload, 124 at the `--states` shape, 64 of those
+eight-way concurrent) returned `None` zero times for $0.0105, against 2 of 50 seen
+in one earlier `--states` run whose cells answered the same on retry; 0 of 184
+bounds the steady rate at 1.6% (95%) and puts that earlier pair down to a transient
+epoch rather than something this path meets every run, so the retry is there for
+the epoch and costs the normal call nothing.
+
+| Invocation | What it does |
+|---|---|
+| `tezgah-triage --select FILE --task "TEXT"` | flattens a `browser_snapshot` result (or the flattened text of one), takes the repeating units the tree marks - a row, a cell, a control on its own, and any line the tree does not mark standing alone (`units()`, `bin/tezgah-triage::units`) - asks one Noul per unit in one request, and prints the line ids under the selected units with their original `ref=` values, the unselected count and the characters that may now be skipped (`select()`, `bin/tezgah-triage::select`) |
+| `tezgah-triage --states FILE [--component T]` | one judgement per state over a component's subtree - the 13 states the analyze-app contract names (`STATES`, `bin/tezgah-triage::STATES`), each question carrying what counts as shown, with the interactive pair (`focus`, `active`) asked as one three-way Choice (`neither` / `focus` / `pressed`) whose answer decides both rows, because an aria snapshot marks the focused element `[active]` and carries no separate mark for a press - so a state the tree does not show is a finding, and the five an aria snapshot cannot carry at all (default, hover, active, skeleton, long-text) are printed on their own `unmarked:` line instead of being counted as missing (`states()`, `bin/tezgah-triage::states`) |
+
+The judgement is an aid, not the finding: it ranks units, the agent reads the
+selected refs and still owns the claim. Its recall was measured this round rather
+than assumed, on two reproduced screens: the unit selection kept 100% of the
+control lines at a 94% read on a 356-line 40-row table and 100% at a 74% read on a
+31-line 20-button screen, against 73.5% at a 26% read for one question per line.
+The threshold those numbers were taken at is `SELECTED_AT` (`bin/tezgah-triage::SELECTED_AT`),
+and the tool prints the measurement with every run. Exit 1 means no judgement was
+made - no credential, the switch below, or a failed call - and the loop reads the
+tree directly instead.
+
+The state leaves the machine. A judgement sends the state and the questions to
+`api.typesafe.ai` (`ask()`, `hooks/tezgah_judge.py::ask`) - for the triage that is
+the snapshot's own text, so a screen carrying personal data is read by a third
+party, and for the docs fallback it is the reader's query. Nothing else goes: no
+session id, no workspace path, no credential beyond the bearer header, and the
+state is not redacted because sending it is the point; the module docstring says
+the same, and `tests/test_judge.py` pins the wire (`Egress`) so the prose and the
+request cannot drift. That is why the two shell callers are on-demand - an agent
+asks for a judgement, no gate does - while the skill hint asks only with its own
+marker armed, and why the switch below is the off button for the whole path.
+
+The credential resolves from `TYPESAFE_API_KEY`, else from
+`~/.config/typesafe/key` (`credential()`, `hooks/tezgah_judge.py::credential`), and when
+neither resolves the same questions go to the OpenRouter fallback, whose key rides
+`OPENROUTER_API_KEY` and then `~/.config/openrouter/key`
+(`openrouter_key()`, `hooks/tezgah_judge.py::openrouter_key`). The file is the channel that
+matters on a machine exporting the variable from `~/.zshenv`: a hook or a bin tool
+runs in a non-interactive shell, where that export never ran, so the file is what a
+judgement actually resolves. Cost is input tokens alone - $0.042 per
+1M, output billed at $0 - and every run prints the arithmetic it paid; the model
+that answered is printed beside it, because the fallback answers with a chat model
+rather than Jev (`result["model"]`, `bin/tezgah-triage::record`).
+
+`judge-off` in `~/.config/tezgah` disarms all of it without touching the callers:
+the snapshot is read the way the loop always read it, and a docs query matching no
+page exits 1 with the message it always printed (`available()`,
+`hooks/tezgah_judge.py::available`). A host whose files predate this tool is relinked by
+`--install`, which links every `~/.config/tezgah/bin` entry including
+`tezgah-triage` (`bin/tezgah-setup::install_common`).
+
+## Source of truth
+
+- `bin/tezgah-setup` — the parser, the install path, the per-host check rows,
+  `--refresh`, `--sync`, `--adopt`, the uninstallers, the wizard, `--upgrade`.
+- `packaging/build.sh`, `packaging/install.sh`, `packaging/upgrade.sh`,
+  `packaging/install.ps1` — the artifact itself: the build from `MANIFEST` plus
+  `VERSION`, the two installers, and the one fetch/verify/unpack/flip step.
+  `tests/e2e_packaged_install.py` and `.github/workflows/ci.yml` install from the
+  built tarball rather than the checkout, so the released shape is what CI proves.
+- `bin/tezgah-doctor`, `bin/tezgah-rollback`, `bin/tezgah-status`,
+  `bin/tezgah-context` — the health pass, the rollback, the checklist CLI, the
+  injected text.
+- `bin/tezgah-triage`, `hooks/tezgah_judge.py`, `bin/tezgah-docs` — the snapshot
+  triage, the judgement seam all five callers share (the others are
+  `hooks/tezgah_skill_pick.py`, `bin/tezgah-route` and `bin/tezgah-taste`), and the docs fallback that uses it;
+  `tests/test_judge.py`, `tests/test_triage.py` pin them against a loopback
+  endpoint.
+- `hooks/tezgah_embed.py`, `hooks/tezgah_apps.py` — the opt-in embedding model:
+  its pins, the fetch and conversion, the reader and `fuse`; the `embed-mrl` and
+  `embed-m2v` registry rows that `--enable`, `--disable` and `--features` read.
+  `tests/test_embed.py` builds tiny models in the test and pins the rest.
+- `hooks/tezgah_paths.py`, `hooks/tezgah_context.py` — the paths and `off()`; the
+  marks and the kill-switch filtering.
+- `RELEASING.md`, `README.md`, `AGENTS.md`, `.gitignore`, `tests/test_setup.py` —
+  the version rule, the install and configuration sections, the layer map, what
+  stays untracked, and the behaviour these checks pin.