@r1z4x/tezgah 1.0.0

package/docs/index.json

@@ -0,0 +1,471 @@
+{
+  "version": 1,
+  "about": "The machine-readable index of docs/. bin/tezgah-docs reads this; tests/test_docs.py keeps it in step with the directory. Every path is repo-relative.",
+  "pages": [
+    {
+      "path": "docs/architecture.md",
+      "title": "Architecture: the layers and what runs when",
+      "title_tr": "Mimari: katmanlar ve ne zaman ne çalışır",
+      "audience": "maintainer, agent new to the repo",
+      "answers": [
+        "what are the layers and what does each own",
+        "what runs when from session start to Stop",
+        "what does a session pay for and what is on demand",
+        "where is state kept and who writes each store"
+      ],
+      "answers_tr": [
+        "katmanlar nelerdir ve her biri neyin sahibidir",
+        "oturum başlangıcından Stop'a kadar ne zaman ne çalışır",
+        "bir oturum neyin bedelini öder ve ne isteğe bağlıdır",
+        "durum nerede tutulur ve her depoya kim yazar"
+      ],
+      "sources": [
+        "hooks/tezgah_context.py",
+        "hooks/tezgah_rank.py",
+        "hooks/tezgah_policy.py",
+        "hooks/tezgah_paths.py",
+        "bin/tezgah-setup",
+        "hosts/codex/hook.py",
+        "hosts/omp/hook.py",
+        "statusline.py",
+        "hooks/tezgah_embed.py"
+      ]
+    },
+    {
+      "path": "docs/layers.md",
+      "title": "Layers: the four layers, and which one tezgah is",
+      "title_tr": "Katmanlar: dört katman ve tezgah hangisi",
+      "audience": "agent, maintainer, anyone writing a claim that says harness",
+      "answers": [
+        "which layer is tezgah and which one is the harness",
+        "is tezgah an agent harness",
+        "what is the boundary against host, framework, SDK, IDE plugin, eval harness, orchestrator and MCP",
+        "which of the three senses of harness a sentence is using",
+        "what does the gate see of an MCP call"
+      ],
+      "answers_tr": [
+        "tezgah hangi katman ve harness hangisi",
+        "tezgah bir ajan harness'i mi",
+        "host, framework, SDK, IDE eklentisi, değerlendirme harness'i, orkestratör ve MCP ile sınır nerede",
+        "bir cümle harness kelimesinin üç anlamından hangisini kullanıyor",
+        "gate bir MCP çağrısından ne görür"
+      ],
+      "sources": [
+        "docs/glossary.md",
+        "docs/hosts.md",
+        "hooks/tezgah_policy.py",
+        "hooks/tezgah_gate.py",
+        "hooks/tezgah_integrity.py",
+        "hooks/tezgah_apps.py",
+        "hooks/tezgah_paths.py",
+        "bin/tezgah-setup",
+        "skills/harness/SKILL.md"
+      ]
+    },
+    {
+      "path": "docs/hosts.md",
+      "title": "Hosts: what each one gets and what each one can see",
+      "title_tr": "Hostlar: her biri ne alır ve ne görebilir",
+      "audience": "maintainer, agent adding a host or a mark",
+      "answers": [
+        "what does each host get and where is it written",
+        "which host can observe what",
+        "what is a host adapter responsible for",
+        "what does it take to add a host"
+      ],
+      "answers_tr": [
+        "her host ne alır ve nereye yazılır",
+        "hangi host neyi gözlemleyebilir",
+        "bir host adaptörü neden sorumludur",
+        "yeni bir host eklemek için ne gerekir"
+      ],
+      "sources": [
+        "hooks/tezgah_paths.py",
+        "bin/tezgah-setup",
+        "hosts/codex/hook.py",
+        "hosts/cursor/hook.py",
+        "hosts/omp/hook.py",
+        "hosts/omp/tezgah-hook.ts.in",
+        "hosts/opencode/plugins/tezgah.js",
+        "hosts/dsh/hooks.json",
+        "hosts/dsh/statusline/lib/index.js",
+        "statusline.py"
+      ]
+    },
+    {
+      "path": "docs/contract.md",
+      "title": "Contract: what a session is told, and how a rule is disarmed",
+      "title_tr": "Sözleşme: oturuma ne söylenir ve bir kural nasıl devre dışı bırakılır",
+      "audience": "agent, maintainer adding a rule",
+      "answers": [
+        "what exactly is a session told and from which file",
+        "how is a rule disarmed",
+        "how is a rule added and what keeps the copies in step",
+        "what happens when the injected text grows too large"
+      ],
+      "answers_tr": [
+        "oturuma tam olarak ne söylenir ve hangi dosyadan",
+        "bir kural nasıl kapatılır, devre dışı bırakılır",
+        "bir kural nasıl eklenir ve kopyaları eşit tutan nedir",
+        "enjekte edilen metin çok büyüdüğünde ne olur"
+      ],
+      "sources": [
+        "hooks/tezgah_policy.py",
+        "hooks/tezgah_context.py",
+        "bin/tezgah-setup",
+        "skills/tezgah-contract/SKILL.md",
+        "output-styles/tezgah.md",
+        "tests/test_context.py"
+      ]
+    },
+    {
+      "path": "docs/gate.md",
+      "title": "Gate: every way a tool call can be refused",
+      "title_tr": "Gate: bir araç çağrısının reddedilebileceği her yol",
+      "audience": "agent, reviewer, maintainer",
+      "answers": [
+        "why was my command denied",
+        "why was my write refused by the active task",
+        "which commands run without an ask and why the consent rule was removed",
+        "what does the gate not catch on purpose",
+        "how do I add a gate rule"
+      ],
+      "answers_tr": [
+        "komutum neden reddedildi, engellendi",
+        "yazmam aktif görev tarafından neden reddedildi",
+        "hangi komutlar onay sormadan çalışır ve onay kuralı neden kaldırıldı",
+        "gate bilerek neyi yakalamaz",
+        "gate kuralı nasıl eklerim"
+      ],
+      "sources": [
+        "hooks/tezgah_gate.py",
+        "hooks/projects-pretooluse.py",
+        "hosts/opencode/plugins/tezgah.js",
+        "tests/test_gate.py"
+      ]
+    },
+    {
+      "path": "docs/evidence.md",
+      "title": "Evidence: the ledger, the Stop rule, snapshots",
+      "title_tr": "Kanıt: defter, Stop kuralı, anlık görüntüler",
+      "audience": "agent, maintainer",
+      "answers": [
+        "what stops an unverified done",
+        "what does the ledger hold and what never reaches it",
+        "how does a check get recorded as passed versus merely run",
+        "how do I undo a bad write"
+      ],
+      "answers_tr": [
+        "doğrulanmamış bir bitti iddiasını ne durdurur",
+        "defter neyi tutar ve oraya asla ne ulaşmaz",
+        "bir kontrol yalnızca çalıştı yerine geçti olarak nasıl kaydedilir",
+        "kötü bir yazmayı nasıl geri alırım"
+      ],
+      "sources": [
+        "hooks/tezgah_integrity.py",
+        "hooks/projects-posttooluse.py",
+        "hooks/projects-stop.py",
+        "hooks/tezgah_snapshot.py",
+        "hooks/tezgah_untrusted.py",
+        "bin/tezgah-rollback",
+        "bin/tezgah-capture"
+      ]
+    },
+    {
+      "path": "docs/status-line.md",
+      "title": "Status line: what each mark means and how it is drawn",
+      "title_tr": "Durum satırı: her işaret ne anlama gelir ve nasıl çizilir",
+      "audience": "agent, maintainer adding a mark",
+      "answers": [
+        "what does each status mark mean and why is it in that state",
+        "how does a surface draw the line",
+        "how do I see or debug the line for a session"
+      ],
+      "answers_tr": [
+        "her durum işareti ne anlama gelir ve neden o durumda",
+        "bir yüzey satırı nasıl çizer",
+        "bir oturumun durum satırını nasıl görürüm veya hata ayıklarım"
+      ],
+      "sources": [
+        "hooks/tezgah_context.py",
+        "bin/tezgah-status",
+        "statusline.py",
+        "hooks/projects-posttooluse.py",
+        "hosts/omp/tezgah-hook.ts.in",
+        "hosts/opencode/tui/tezgah-tui.tsx",
+        "hosts/dsh/statusline/lib/index.js"
+      ]
+    },
+    {
+      "path": "docs/judge.md",
+      "title": "Judge: the judgement seam, its five callers and its switches",
+      "title_tr": "Yargıç: yargı noktası, beş çağıranı ve anahtarları",
+      "audience": "agent, maintainer adding a caller",
+      "answers": [
+        "what is the judgement seam and is it a rule",
+        "which callers ask for a judgement and what is each for",
+        "where does the credential come from and what leaves the machine",
+        "how do I switch the judgement off",
+        "what does a judgement cost and how was that measured",
+        "what will the seam never be used for"
+      ],
+      "answers_tr": [
+        "yargı noktası nedir ve bir kural mı",
+        "hangi çağıranlar yargı ister ve her biri ne için",
+        "kimlik bilgisi nereden gelir ve makineden ne çıkar",
+        "yargıyı nasıl kapatırım",
+        "bir yargının maliyeti nedir ve nasıl ölçüldü",
+        "yargı noktası asla ne için kullanılmayacak"
+      ],
+      "sources": [
+        "hooks/tezgah_judge.py",
+        "bin/tezgah-triage",
+        "bin/tezgah-docs",
+        "hooks/tezgah_rank.py",
+        "hooks/tezgah_skill_pick.py",
+        "hooks/tezgah_policy.py",
+        "hooks/tezgah_paths.py",
+        "tests/test_judge.py",
+        "tests/test_triage.py",
+        "tests/test_docs_router.py",
+        "hooks/tezgah_embed.py"
+      ]
+    },
+    {
+      "path": "docs/models.md",
+      "title": "Models: which model runs which delegated task, and how the table stays current",
+      "title_tr": "Modeller: hangi model hangi devredilen görevi çalıştırır ve tablo nasıl güncel kalır",
+      "audience": "agents and maintainers",
+      "answers": [
+        "which model does each subagent run on each host",
+        "how does tezgah-route pick a tier worker",
+        "why Opus effort levels and not Sonnet inside the Anthropic family",
+        "how is the model table kept current"
+      ],
+      "answers_tr": [
+        "her alt ajan her hostta hangi modelde çalışır",
+        "tezgah-route bir kademe işçisini nasıl seçer",
+        "Anthropic ailesinde neden Sonnet değil de Opus efor seviyeleri",
+        "model tablosu nasıl güncel tutulur"
+      ],
+      "sources": [
+        "hooks/tezgah_models.py",
+        "bin/tezgah-route",
+        "hooks/tezgah_agents.py",
+        "hooks/tezgah_policy.py",
+        "bin/tezgah-setup"
+      ]
+    },
+    {
+      "path": "docs/research.md",
+      "title": "Research: the line in the repository, the CLI that checks it, the mark it lights",
+      "title_tr": "Araştırma: depodaki hat, onu denetleyen CLI, yaktığı işaret",
+      "audience": "agent, maintainer adding or checking a research line",
+      "answers": [
+        "where does a research line live and what does it hold",
+        "what does tezgah-research check refuse and what does it only warn about",
+        "what do init, claim, migrate and source write",
+        "how does a session learn that a research line is broken",
+        "what lights the research mark and how is the layer switched off",
+        "why may a new research line not be opened while another is unfinished"
+      ],
+      "answers_tr": [
+        "bir araştırma hattı nerede yaşar ve ne tutar",
+        "tezgah-research check neyi reddeder ve neyi yalnızca uyarır",
+        "init, claim, migrate ve source ne yazar",
+        "bir oturum bir araştırma hattının bozuk olduğunu nasıl öğrenir",
+        "araştırma işaretini ne yakar ve katman nasıl kapatılır",
+        "başka biri bitmemişken neden yeni bir araştırma hattı açılamaz"
+      ],
+      "sources": [
+        "hooks/tezgah_research.py",
+        "bin/tezgah-research",
+        "hooks/tezgah_policy.py",
+        "hooks/tezgah_context.py",
+        "skills/research/SKILL.md",
+        "tests/test_research.py"
+      ]
+    },
+    {
+      "path": "docs/skills.md",
+      "title": "Skills: what ships, and how one reaches a host",
+      "title_tr": "Beceriler: ne gönderilir ve bir beceri hosta nasıl ulaşır",
+      "audience": "maintainer, agent adding a skill",
+      "answers": [
+        "what is a skill here and how does it reach a host",
+        "which skills ship and what does each do",
+        "how do I add a skill without breaking the router or the install report"
+      ],
+      "answers_tr": [
+        "burada beceri nedir ve bir hosta nasıl ulaşır",
+        "hangi beceriler gelir ve her biri ne yapar",
+        "yönlendiriciyi veya kurulum raporunu bozmadan nasıl beceri eklerim"
+      ],
+      "sources": [
+        "bin/tezgah-setup",
+        "skills/",
+        "skills/design-library/SOURCE",
+        "tests/routing-fixtures.md",
+        "commands/",
+        "NOTICE",
+        "tests/test_setup.py",
+        "tests/test_skills.py"
+      ]
+    },
+    {
+      "path": "docs/feature-audit.md",
+      "title": "Feature audit: one feature, every layer",
+      "title_tr": "Özellik denetimi: tek özellik, her katman",
+      "audience": "agent auditing an existing feature; maintainer of the product rule",
+      "answers": [
+        "what does a feature-level audit cover that a screen review misses",
+        "what are the five matrices and the capability-change proposal",
+        "how is the feature-audit skill reached and what evidence backs it"
+      ],
+      "answers_tr": [
+        "özellik düzeyinde bir denetim, ekran incelemesinin kaçırdığı neyi kapsar",
+        "beş matris ve yetenek değişikliği önerisi nedir",
+        "özellik denetimi becerisine nasıl ulaşılır ve onu hangi kanıt destekler"
+      ],
+      "sources": [
+        "skills/feature-audit/SKILL.md",
+        "hooks/tezgah_policy.py",
+        "hooks/tezgah_context.py"
+      ]
+    },
+    {
+      "path": "docs/testing.md",
+      "title": "Testing: the checks, the probes, the e2e scripts",
+      "title_tr": "Test: kontroller, sondalar, e2e betikleri",
+      "audience": "maintainer",
+      "answers": [
+        "how do I check this repo and what does each check catch",
+        "how do I write a test here that will not be deleted later",
+        "what do the probes and the e2e scripts need to run"
+      ],
+      "answers_tr": [
+        "bu depoyu nasıl kontrol ederim ve her kontrol neyi yakalar",
+        "burada sonradan silinmeyecek bir testi nasıl yazarım",
+        "sondalar ve e2e betikleri çalışmak için neye ihtiyaç duyar"
+      ],
+      "sources": [
+        "AGENTS.md",
+        ".github/workflows/ci.yml",
+        "tests/support.py",
+        "tests/e2e_analyze_wiring.py",
+        "tests/e2e_omp_statusline.py",
+        "tests/e2e_dsh_statusline.py"
+      ]
+    },
+    {
+      "path": "docs/operations.md",
+      "title": "Operations: install, upgrade, repair",
+      "title_tr": "İşletim: kurulum, yükseltme, onarım",
+      "audience": "operator, maintainer",
+      "answers": [
+        "how do I install verify and upgrade this on a machine",
+        "what does each installer flag do",
+        "how do I install or upgrade a released version without a git checkout",
+        "where does an installed version unpack and how do I roll back",
+        "something is broken what do I check first",
+        "how do I turn on taste signal capture and measure my corrections"
+      ],
+      "answers_tr": [
+        "bunu bir makineye nasıl kurar, doğrular ve yükseltirim",
+        "her kurulum bayrağı ne yapar",
+        "git deposu olmadan yayımlanmış bir sürümü nasıl kurar veya yükseltirim",
+        "kurulu bir sürüm nereye açılır ve nasıl geri alırım",
+        "bir şey bozuk, önce neyi kontrol etmeliyim",
+        "zevk sinyali kaydını nasıl açar ve düzeltmelerimi nasıl ölçerim"
+      ],
+      "sources": [
+        "bin/tezgah-setup",
+        "bin/tezgah-doctor",
+        "bin/tezgah-rollback",
+        "packaging/build.sh",
+        "packaging/install.sh",
+        "packaging/upgrade.sh",
+        "packaging/install.ps1",
+        "RELEASING.md",
+        "README.md",
+        "hooks/tezgah_embed.py",
+        "hooks/tezgah_taste.py",
+        "bin/tezgah-taste"
+      ]
+    },
+    {
+      "path": "docs/environment.md",
+      "title": "Environment variables: every one tezgah reads",
+      "title_tr": "Ortam değişkenleri: tezgah'ın okuduğu her biri",
+      "audience": "user pinning an install or CI job, maintainer adding a variable, test author repointing an endpoint",
+      "answers": [
+        "which environment variables does tezgah read",
+        "what does each variable default to and change",
+        "how do I repoint an endpoint or a binary in a test",
+        "which variable picks the python a hook runs"
+      ],
+      "answers_tr": [
+        "tezgah hangi ortam değişkenlerini okur",
+        "her değişkenin varsayılanı nedir ve neyi değiştirir",
+        "bir testte bir uç noktayı veya ikili dosyayı nasıl başka yere yönlendiririm",
+        "hangi değişken bir hook'un çalıştırdığı python'u seçer"
+      ],
+      "sources": [
+        "hooks/tezgah_paths.py",
+        "hooks/tezgah_judge.py",
+        "hooks/tezgah_index.py",
+        "bin/tezgah-setup",
+        "bin/consult",
+        "bin/codegen",
+        "packaging/install.sh",
+        "packaging/upgrade.sh",
+        "statusline.py"
+      ]
+    },
+    {
+      "path": "docs/glossary.md",
+      "title": "Glossary: one term per concept",
+      "title_tr": "Sözlük: her kavram için tek terim",
+      "audience": "everyone",
+      "answers": [
+        "what does this word mean in this repository"
+      ],
+      "answers_tr": [
+        "bu kelime bu depoda ne anlama geliyor"
+      ],
+      "sources": [
+        "hooks/tezgah_context.py",
+        "hooks/tezgah_gate.py",
+        "hooks/tezgah_integrity.py",
+        "hooks/tezgah_paths.py",
+        "hooks/tezgah_policy.py"
+      ]
+    },
+    {
+      "path": "docs/vision.md",
+      "title": "Vision: how a tezgah session is meant to run",
+      "title_tr": "Vizyon: bir tezgah oturumunun nasıl çalışması amaçlanır",
+      "audience": "maintainer, agent changing the check cadence, the review loop, routing or the research layer",
+      "answers": [
+        "what the operating model is behind the rules",
+        "what each check tier costs and when it runs",
+        "why every agent gets a cross-family fallback chain",
+        "what the research layer requires of a line"
+      ],
+      "answers_tr": [
+        "kuralların arkasındaki işletim modeli nedir",
+        "her kontrol kademesinin maliyeti nedir ve ne zaman çalışır",
+        "neden her ajana aileler arası bir yedek zincir verilir",
+        "araştırma katmanı bir hattan ne ister"
+      ],
+      "sources": [
+        "hooks/tezgah_policy.py",
+        "hooks/tezgah_models.py",
+        "hooks/tezgah_research.py",
+        "tests/impacted.py",
+        "docs/testing.md",
+        "AGENTS.md"
+      ]
+    }
+  ]
+}

package/docs/judge.md

@@ -0,0 +1,193 @@
+# Judge: the judgement seam, its five callers and its switches
+
+The judgement seam is `hooks/tezgah_judge.py`: one module that asks TypeSafe
+(Jev) for a batched structured judgement over a state tezgah would otherwise pay
+an agent to read. Read this page when you are about to call one of its four
+callers, when you need to say what leaves the machine, or when you have to tell a
+user how to switch it off. It is an on-demand capability, not a rule: no paragraph
+of it is injected into a session, and a session that never asks pays one clause in
+the kill-switch paragraph and nothing else (`CORE`,
+`hooks/tezgah_policy.py::CORE`).
+
+## What it is
+
+One seam, five callers, one credential, one egress boundary, one price, one
+redirect guard. The module is stdlib only and total - a failure is a `None`, never
+an exception, because a hook imports it and a hook that raises takes a session
+down (`_request`, `hooks/tezgah_judge.py::_request`). One endpoint and one key path
+are module constants (`URL`, `hooks/tezgah_judge.py::URL`; `KEY_FILE`,
+`hooks/tezgah_judge.py::KEY_FILE`), one opener is shared by every call (`OPENER`,
+`hooks/tezgah_judge.py::OPENER`), and it refuses a redirect that leaves the
+endpoint's host, so a `Location` cannot carry the bearer (`guarded_opener`,
+`hooks/tezgah_paths.py`, the one copy `bin/consult` and `bin/codegen` use too). A
+transient failure - a timeout, a connection error, a 5xx - gets exactly one more
+attempt; a 4xx and a malformed reply never do (`_transient`,
+`hooks/tezgah_judge.py::_transient`). A hook caller asks for one attempt and a
+wall-clock `deadline` instead (`ask`, `hooks/tezgah_judge.py::ask`).
+urllib's timeout bounds one socket operation, not the whole call.
+`TEZGAH_TYPESAFE_URL` repoints the endpoint and `TEZGAH_OPENROUTER_URL` the
+fallback's; both are test seams, not fallbacks.
+
+Every caller reads an answer through the same two accessors rather than reaching
+into the raw reply, so a Choice and a Noul are read one way for all five
+(`choice`, `hooks/tezgah_judge.py::choice`; `noul`,
+`hooks/tezgah_judge.py::noul`). Both are total: a missing or wrongly-typed
+answer is a `None`, never an exception.
+
+A judgement is an aid, never the claim. It ranks units or names a page; the agent
+still reads the selected refs and owns the finding, and the ledger's step kinds
+are untouched, so a model answer can never license a "done" (`STEP_KINDS`,
+`hooks/tezgah_integrity.py::STEP_KINDS`).
+
+The state leaves the machine. A judgement sends the state and the questions to
+`api.typesafe.ai` - for the triage that is the screen'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. When no TypeSafe key resolves, the same state goes to
+`openrouter.ai` instead (`OPENROUTER_URL`, `hooks/tezgah_judge.py::OPENROUTER_URL`), which is
+the price of a machine that has no Jev credential still having a judge at all:
+the destination changes, not what is sent. Nothing else goes: no session id, no
+workspace path, no environment. The seam does not rewrite the state, because
+sending it is the point. Two callers rewrite what they send. `bin/tezgah-route`
+sends its brief through the ledger's own redactor (`redact`,
+`hooks/tezgah_integrity.py::redact`), because a delegation brief can quote an error
+message or a token. A brief that matches the router's override vocabulary never
+leaves the machine. That vocabulary names stored data, credentials, keys and
+certificates, destructive data or history operations, privilege and security.
+The prompt-path skill hint sends the user's prompt through the same redactor. It
+also cuts the prompt at 2,000 characters (`PROMPT_MAX`,
+`hooks/tezgah_skill_pick.py::PROMPT_MAX`), because a prompt can quote a token and
+nobody chose to send it. Four of the callers are explicit -
+a person runs the tool - and the fifth, `bin/tezgah-route`, is what the
+ORCHESTRATE paragraph tells the router to run before every delegation, which is
+why its redaction is not optional. The switches below are the off buttons.
+
+## The five callers
+
+| Caller | What it asks, and what it is for | On failure |
+|---|---|---|
+| `bin/tezgah-triage` | the analyze-app snapshot triage. `--select FILE --task T` asks one question per repeating unit of the screen in one request and prints the line ids under the selected units with their refs (`select_request`, `bin/tezgah-triage::select_request`; the units are the tree's own repeating pieces, `units`, `bin/tezgah-triage::units`). `--states` asks one judgement per state over a component's subtree (`states`, `bin/tezgah-triage::states`) | exit 1 with one reason (`no_judgement`, `bin/tezgah-triage::no_judgement`), and the loop reads the tree directly |
+| `bin/tezgah-docs` | the docs page fallback: only when the keyword index placed nothing, one Choice over the pages with `none` offered (`judge_pick`, `bin/tezgah-docs::judge_pick`; the question wording is `ASK`, `bin/tezgah-docs::ASK`) | reads as no judgement; with none (no credential, `judge-off`, `docs-judge-off`, or a call that failed or came back without one of its options) the pages are ranked by shared words instead (`ranked`, BM25 in `hooks/tezgah_rank.py` over each page's title and answers and their Turkish phrasings) and the top three printed; a query sharing no word with any page, or a judged `none`, exits 1. With the opt-in embedding feature on, the ranking is fused with a static embedding (`hooks/tezgah_embed.py`), which places every page, so only a judged `none` exits 1 |
+| `hooks/tezgah_skill_pick.py` | the prompt-path skill hint: a Choice over the roster skills plus one Noul (`judge`, `hooks/tezgah_skill_pick.py::judge`, with the criteria cut from each skill's own clauses, `clause`, `hooks/tezgah_skill_pick.py::clause`), behind a threshold (`GATE`, `hooks/tezgah_skill_pick.py::GATE`), one attempt and a 4 s wall-clock deadline (`ASK_DEADLINE`, `hooks/tezgah_skill_pick.py::ASK_DEADLINE`), the prompt redacted and cut at 2,000 characters | returns `""`; the turn loses the hint |
+| `bin/tezgah-route` | the tier router: after the deterministic overrides, one Choice over the three tiers for a delegation brief (`route`, `hooks/tezgah_models.py::route`; `TIER_QUESTION`, `hooks/tezgah_models.py::TIER_QUESTION`) - see [models](models.md) | the static phase table, else the middle tier |
+| `bin/tezgah-taste` | the coding-taste measurement: `measure` and `rate` label the prompts a user sent after a writing turn, one Choice per prompt batched into one request, each prompt redacted first (`classify`, `bin/tezgah-taste::classify`) | with no credential or `judge-off` it exits 2 before any request; a failed call leaves its prompts unlabelled |
+
+The third caller is the one no shell row can see: it runs on the prompt path,
+caches one answer per `(session, prompt)` (`_remember`,
+`hooks/tezgah_skill_pick.py::_remember`; `suggest`,
+`hooks/tezgah_skill_pick.py::suggest`), and asks at all only when its own marker is
+armed. The other four are bin tools a session runs by name.
+
+## The credential's channels
+
+The credential resolves from `TYPESAFE_API_KEY`, else from the key file the module
+names (`KEY_FILE`, `hooks/tezgah_judge.py::KEY_FILE`). The environment variable is the
+channel an interactive shell has; the file is the channel that matters, because a
+hook or a bin tool a host starts runs in a non-interactive shell where a
+`~/.zshenv` export never ran, so the variable is absent exactly where a judgement
+runs. That is why the file is read rather than the environment trusted. The
+install report's health row reads its own pair of channels ([hosts](hosts.md)),
+which is a different question from the one the seam asks.
+
+When neither channel resolves, the same two channels are read again for the
+fallback provider - `OPENROUTER_API_KEY`, then `~/.config/openrouter/key`
+(`openrouter_key()`, `hooks/tezgah_judge.py::openrouter_key`) - and the request goes to an
+OpenAI-compatible chat endpoint instead (`OPENROUTER_URL`,
+`hooks/tezgah_judge.py::OPENROUTER_URL`). TypeSafe wins whenever it resolves, so the fallback
+cannot move a machine that already judges with Jev (`credential()`,
+`hooks/tezgah_judge.py::credential`). The chat model is asked for the same shapes in prose
+(`CHAT_SYSTEM`, `hooks/tezgah_judge.py::CHAT_SYSTEM`), at temperature 0
+(`_chat_body()`, `hooks/tezgah_judge.py::_chat_body`), and its reply is filtered to the ids
+that were asked for, dropping any answer whose type does not match its question
+(`_chat_answers()`, `hooks/tezgah_judge.py::_chat_answers`; `_clean_answer()`,
+`hooks/tezgah_judge.py::_clean_answer`) - so a dropped answer reads the same as no answer at
+all, which is what the callers already handled. The model is the table's cheap row
+(`cheap_model`, `hooks/tezgah_models.py`) unless `TEZGAH_JUDGE_MODEL` names
+another, and a table that cannot be read falls back to its own literal
+(`fallback_model()`, `hooks/tezgah_judge.py::fallback_model`). The result carries the provider
+that answered and the model the reply names. The requested model stands only
+when the reply names none, so a silent upgrade behind `jev-latest` shows. The
+skill hint's cost row and the router's `route` row print both as one
+`judge=<provider>/<model>` word.
+
+## The switches
+
+`judge-off` is the master: with it armed `available()` is false and no caller
+makes a request at all, so the triage loop reads the tree and the docs fallback
+ranks the pages by shared words instead. Each caller also names its own switch, so one
+capability can be disarmed without the others - `triage-off` for
+`bin/tezgah-triage` and `docs-judge-off` for `bin/tezgah-docs`. The third caller's
+channel is an opt-in marker rather than a kill switch: it is off until
+`skill-suggest-on` is armed (`ARM`, `hooks/tezgah_skill_pick.py::ARM`). Every
+switch is listed in the `**Kill switches:**` paragraph every session receives
+(`CORE`, `hooks/tezgah_policy.py::CORE`), mirrored into `tezgah-contract`, and
+pinned by `tests/test_skills.py`.
+
+## What a judgement costs
+
+Input tokens are billed per million and output at zero, and `bin/tezgah-triage`
+computes and prints the arithmetic it paid on every run (`PRICE_PER_MILLION`,
+`bin/tezgah-triage::PRICE_PER_MILLION`; `judge_line`, `bin/tezgah-triage::judge_line`). The
+unit-selection shape it ships was measured on two reproduced screens: 100% of the
+control lines at a 94% read on a 356-line table, and 100% at a 74% read on a
+31-line screen, against 73.5% at a 26% read for the per-line shape it replaced.
+The threshold those numbers were taken at is `SELECTED_AT`, and the tool prints
+the measurement with every run (`MEASURED`, `bin/tezgah-triage::MEASURED`;
+`SELECTED_AT`, `bin/tezgah-triage::SELECTED_AT`). The retry covers a rate that was
+measured rather than assumed - 0 of 184 live calls returned `None` - so the second
+attempt costs a healthy call nothing (`_transient`,
+`hooks/tezgah_judge.py::_transient`); `docs/operations.md` records the run. Each
+caller also records one `judge` row of cost on the ledger when a session id is
+known (`note`, `hooks/tezgah_integrity.py::note`), counted by the row's kind
+(`counters`, `hooks/tezgah_integrity.py::counters`).
+
+## What the seam never does
+
+1. **No always-on rule paragraph.** It is on-demand, and the conditional keys
+   exist exactly so a session that never asks does not carry the text
+   (`CONDITIONAL_KEYS`, `hooks/tezgah_policy.py::CONDITIONAL_KEYS`). Naming it buys discovery
+   for one clause; a paragraph would cost the always-on block.
+2. **Nothing in the gate, the Stop rule, the shortcut parser or
+   the PreToolUse hot path.** Refusal reproducibility is an invariant with tests
+   behind it, and a probabilistic answer on a denial path is a policy bug.
+3. **No seam-level answer cache, and no caller cache beyond the prompt-keyed one
+   that exists** (`_remember`, `hooks/tezgah_skill_pick.py::_remember`). A judgement
+   costs a fraction of a cent, so a cache is not worth its state file, and a naive
+   one would make two runs of the same command disagree. The one state the seam
+   keeps is a failure marker (`DOWN_FOR`, 300 s, in `hooks/tezgah_judge.py`). A
+   call that ends on a 401, 402 or 5xx marks that provider, endpoint and
+   credential down for five minutes. Until the marker expires, every call returns
+   no judgement and sends no request. A dead key or an empty account then costs
+   one refusal per five minutes, not one per prompt. A rotated key gets a new
+   marker, so the seam asks it at once.
+4. **No SDK, no `requests`, no async, no local model.** Each would trade one of
+   the seam's three load-bearing properties - total, stdlib-only,
+   dependency-free - for a saving nobody measured.
+5. **No `criteria` on the triage's `--select` question.** The task sits in the
+   shared state on purpose so the per-unit question does not repeat it dozens of
+   times (`select_request`, `bin/tezgah-triage::select_request`).
+6. **No rename of the module and no new tool.** It is cited across the docs and
+   the tools' own docstrings, and the user-facing surface is already the two tool
+   names.
+7. **A judgement never counts as a check or a step.** The step kinds stay as they
+   are (`STEP_KINDS`, `hooks/tezgah_integrity.py::STEP_KINDS`); the cost row is a
+   counter, not evidence.
+
+## Source of truth
+
+- `hooks/tezgah_judge.py` — the seam: endpoint, key path, `available()`, `ask()`,
+  the answer accessors, the retry class and the provider-down marker.
+- `bin/tezgah-triage` — the snapshot triage and the per-state matrix; prints the
+  unit it selected, the characters it saved and the cost it paid.
+- `bin/tezgah-docs` — the page router; its index match, then its one fallback
+  Choice, then the word ranking (`hooks/tezgah_rank.py`, fused with
+  `hooks/tezgah_embed.py` when that opt-in feature is on) when the judge gives
+  no judgement.
+- `hooks/tezgah_skill_pick.py` — the prompt-path skill hint, its threshold, its
+  per-prompt cache and its `skill-suggest-on` marker.
+- `hooks/tezgah_policy.py` — the `**Kill switches:**` paragraph the session
+  receives; `hooks/tezgah_paths.py` — where a switch file is read, and the
+  redirect guard (`guarded_opener`) the seam, consult and codegen share.
+- `hooks/tezgah_integrity.py` — the ledger and the `judge` counter;
+  `hooks/tezgah_context.py` — the status mark and the class carve-out.
+- `tests/test_judge.py`, `tests/test_triage.py`, `tests/test_docs_router.py` —
+  the wire, the callers and the index criteria.