@r1z4x/tezgah 1.0.0 → 1.2.0

package/docs/clarity-baseline.json

@@ -18,10 +18,10 @@
     "semicolons": 9
   },
   "docs/contract.md": {
-    "long_sentences": 40,
+    "long_sentences": 43,
     "passive": 26,
     "replace_words": 0,
-    "semicolons": 30
+    "semicolons": 31
   },
   "docs/environment.md": {
     "long_sentences": 3,
@@ -45,7 +45,7 @@
     "long_sentences": 67,
     "passive": 32,
     "replace_words": 1,
-    "semicolons": 46
+    "semicolons": 45
   },
   "docs/glossary.md": {
     "long_sentences": 51,
@@ -60,10 +60,10 @@
     "semicolons": 18
   },
   "docs/judge.md": {
-    "long_sentences": 28,
+    "long_sentences": 23,
     "passive": 15,
     "replace_words": 0,
-    "semicolons": 17
+    "semicolons": 14
   },
   "docs/layers.md": {
     "long_sentences": 20,
@@ -90,10 +90,10 @@
     "semicolons": 77
   },
   "docs/skills.md": {
-    "long_sentences": 31,
-    "passive": 16,
+    "long_sentences": 36,
+    "passive": 18,
     "replace_words": 0,
-    "semicolons": 14
+    "semicolons": 16
   },
   "docs/status-line.md": {
     "long_sentences": 44,
@@ -111,6 +111,6 @@
     "long_sentences": 9,
     "passive": 7,
     "replace_words": 1,
-    "semicolons": 12
+    "semicolons": 11
   }
 }

package/docs/contract.md

@@ -17,12 +17,24 @@ host says the same thing (`hooks/tezgah_policy.py:14-15`); path placeholders
 
 | Surface | Text | Paid |
 |---|---|---|
-| always-on core | `CORE` (`hooks/tezgah_policy.py::CORE`) minus the five conditional paragraphs, plus the pointer line | once per session: `session_start` and `post_compact` |
-| conditional paragraph | one of the five keyed by `CONDITIONAL_KEYS` (`hooks/tezgah_policy.py::CONDITIONAL_KEYS`) | in full on the first turn of a session whose prompt matches its task class; a later match pays one line (`hooks/tezgah_context.py::armed_again`) until a compaction or `ARMED_RESURFACE` turns (`hooks/tezgah_context.py::ARMED_RESURFACE`) bring the full text back |
+| always-on core | `CORE` (`hooks/tezgah_policy.py::CORE`) minus the six conditional paragraphs, plus the pointer line | once per session: `session_start` and `post_compact` |
+| conditional paragraph | one of the six keyed by `CONDITIONAL_KEYS` (`hooks/tezgah_policy.py::CONDITIONAL_KEYS`) | in full on the first turn of a session whose prompt matches its task class; a later match pays one line (`hooks/tezgah_context.py::armed_again`) until a compaction or `ARMED_RESURFACE` turns (`hooks/tezgah_context.py::ARMED_RESURFACE`) bring the full text back |
 | per-turn reminder | `PROMPT_REMINDER` (`hooks/tezgah_policy.py::PROMPT_REMINDER`) | every user prompt |
-| skill suggestion | one `<skill_relevance>` line naming at most one installed skill, written by `suggest` (`hooks/tezgah_skill_pick.py::suggest`); off unless `skill-suggest-on` is armed | only on a turn the judgement answers with a skill |
+| skill suggestion | one `<skill_relevance>` line naming at most one installed skill and the SECTION of it that matches the turn (`skill://<name>:<start>-<end>` plus the absolute path), written by `suggest` (`hooks/tezgah_skill_pick.py::suggest`) when `skill-suggest-on` is armed, else by the model-free section search (`hooks/tezgah_skill_pick.py::section_hint`), default on | only on a turn the judgement answers with a skill, or whose prompt one section covers (each section once per session) |
 | on-demand full contract | the long-form blocks of `hooks/tezgah_policy.py` (`EXEC`, `CONSULT`, `RESEARCH`, …), shipped hand-kept as `skills/tezgah-contract/SKILL.md` | only when the session loads that skill |
 
+Two paragraphs of the core are complete statements of their rule, not
+summaries the session must upgrade: **Ponytail** and **Output shape:
+ADHD-friendly** carry every operative clause of their skills (the runnable-check
+rule, the lazy-version-and-question reply, the evidence-gated cause, the
+three-still-broken stop, the pre-send delete pass) from the first turn of every
+session, because "on the first non-trivial task, read the full skill" armed a
+rule only when the model chose to load it. What the skills still hold is the
+level table, the reasoning and the worked examples (`skills/ponytail/SKILL.md`,
+`skills/i-have-adhd/SKILL.md`), and the pointer says so. The kill switches drop
+the paragraphs whole (`ponytail-auto.off`/`.no-ponytail`, `adhd-off`/`.no-adhd`),
+rules and all.
+
 The skill suggestion is the one surface a judgement writes rather than a constant.
 The roster reaches a session as an index of host-truncated one-liners, so which
 entry to look at first is the turn's own weak spot; one batched judgement request
@@ -33,8 +45,10 @@ asking whether the turn wants a skill at all - and the winner is appended after
 the armed paragraphs as a hint to look at first, never as an instruction to load
 (`hooks/tezgah_skill_pick.py:41-75` is the whole configuration, wired into
 `context_for` at `hooks/tezgah_context.py::context_for`). Measured cost of the line
-itself: 305-317 characters, about 78 tokens of prompt. Measured cost of the
-judgement: one call per unanswered prompt, 909-915 input tokens, 0.77-0.81 s,
+itself: 455-523 characters, about 115-130 tokens of prompt (the section address
+added ~150 characters over the name-only line; `bin/tezgah-skill` is the same
+ranking without the call). Measured cost of the judgement: one call per
+unanswered prompt, 909-915 input tokens, 0.77-0.81 s,
 $0.000038 at $0.042/1M on three live judgements. It is OFF UNLESS ARMED -
 `skill-suggest-on` in `~/.config/tezgah`, the same place the kill switches live -
 because a labelled set of 28 prompts through an independent chooser was measured
@@ -47,6 +61,19 @@ session is never paid for twice (`tests/test_skill_pick.py`). The host's own
 roster text is left untouched: that is what a session matches on and what its
 prefix cache covers, which is the whole reason the upstream recipe keeps it.
 
+When the judgement gives no line, the local section search may write one. It
+uses no model and is on by default (`hooks/tezgah_skill_pick.py::section_hint`,
+[skills](skills.md)). Its SQLite index lives in the tezgah cache dir and
+rebuilds only when a SKILL.md's stat moves. The line needs a top section that
+carries 60% of the prompt's distinct content terms, and at least three. It
+names each section once per session and drops the absolute path on omp, whose
+read tool resolves `skill://`. Measured on this machine: 6-15 ms warm, and
+1.36 s for the one cold rebuild over 7 502 sections. The line costs 196-239
+bytes on omp and 245-320 elsewhere. It is not a judgement, so `judge-off` leaves it on,
+and `reminder-off` drops it with the per-turn text. The always-on core also
+sends every session to the same search by hand. Run `tezgah-skill <words>`
+before working a topic a skill covers, then read only the returned range.
+
 `context_for(event, …)` is the one dispatcher (`hooks/tezgah_context.py::context_for`):
 `session_start`/`post_compact` build core plus live state, `user_prompt` builds
 the reminder, whatever was armed and any skill hint, `subagent_start` builds a short brief
@@ -142,23 +169,26 @@ research lines with a written flip; everything else keeps one fresh reviewer
 Paragraphs are concatenated in the order they appear in `CORE` and identified by
 the bold label each starts with (`CORE_RULES`, `hooks/tezgah_context.py::CORE_RULES`).
 That order, with the line each label sits on in `hooks/tezgah_policy.py`:
-`**{REPLY_LANG}, BLUF.**` :637, `**Ponytail (minimal code).**` :645, `**Output shape:
-ADHD-friendly.**` :656, `**Deliver the whole ask; never the shortcut.**` :670,
-`**Integrity: evidence, or "doğrulanmadı".**` :684, `**Loop discipline.**` :700,
-`**Spec before building.**` :709 *(conditional)*, `**Lessons ledger: stop
-repeating mistakes.**` :723, `**Code discovery: graph first.**` :731
-*(conditional)*, `**Consult before irreversible.**` :740 *(conditional)*,
-`**Research: route it to OpenResearch.**` :756 *(conditional)*, `**Product
-analysis: five axes, one evidence class per finding.**` :772 *(conditional)*,
-`**No AI attribution, ever, on any host.**` :805, `**Identifiers and messages
-stay English.**` :815, `**Session scope: the user's repo, not tezgah.**` :821,
-`**Kill switches:**` :837. The first label renders as `**Turkish, BLUF.**` under
+`**{REPLY_LANG}, BLUF.**` :649, `**Ponytail (minimal code).**` :657, `**Output shape:
+ADHD-friendly.**` :668, `**Deliver the whole ask; never the shortcut.**` :682,
+`**Integrity: evidence, or "doğrulanmadı".**` :696, `**Loop discipline.**` :713,
+`**Spec before building.**` :722 *(conditional)*, `**Lessons ledger: stop
+repeating mistakes.**` :736, `**Code discovery: graph first.**` :744
+*(conditional)*, `**Consult before irreversible.**` :753 *(conditional)*,
+`**Research: route it to OpenResearch.**` :769 *(conditional)*, `**Product
+analysis: five axes, one evidence class per finding.**` :785 *(conditional)*,
+`**No AI attribution, ever, on any host.**` :818, `**Identifiers and messages
+stay English.**` :828, `**Session scope: the user's repo, not tezgah.**` :834,
+``**Workspace: `.tezgah/` only.**`` :843, `**Parallel by default: fan out
+independent items.**` :850 *(conditional)*,
+`**Kill switches:**` :865. The first label renders as `**Turkish, BLUF.**` under
 the default `reply_lang`.
 
-`always_on_core()` (`hooks/tezgah_context.py::always_on_core`) drops the five
+`always_on_core()` (`hooks/tezgah_context.py::always_on_core`) drops the six
 conditional paragraphs and appends `POINTERS` (`hooks/tezgah_policy.py::POINTERS`):
 one line each saying the rule exists and where its full text lives — spec-first,
-a second opinion, OpenResearch routing, product analysis, the code graph, and the
+a second opinion, OpenResearch routing, product analysis, the code graph, parallel
+fan-out, and the
 per-repo design contract `bin/tezgah-design` checks a UI change against (the one
 pointer with no conditional paragraph behind it, because the Stop rule's `no
 ui_ok` class is what asks for the check). That is
@@ -234,13 +264,17 @@ sentence of the rule.
 | consult | The owner removed the consent rule on 2026-09-26 ([gate.md](gate.md#what-the-gate-deliberately-does-not-catch)). The per-turn reminder carries the clause instead. |
 | research | Owner decision ADR 010 (2026-10-05): no new research rule until plan 062 reports. |
 | product | Owner decision ADR 010 (2026-10-05): no new research rule until plan 062 reports. The product rule is the research route. |
+| fanout | A refusal cannot see a serial run that should have been parallel: nothing is called that a gate could deny. The prompt-shape arming (`hooks/tezgah_context.py::PROMPT_HINTS`) and the generated specialists line are the mechanism. |
 | scope | no decision |
 
 ## Arming the conditional paragraphs, and the per-turn reminder
 
 `PROMPT_HINTS` (`hooks/tezgah_context.py::PROMPT_HINTS`) is one compiled pattern per key
-— `spec`, `consult`, `research`, `product`, `graph` — and `classify_prompt()` returns the keys
-a prompt matches (`hooks/tezgah_context.py::classify_prompt`). On that turn only, the
+— `spec`, `consult`, `research`, `product`, `graph`, `fanout` — and `classify_prompt()` returns the keys
+a prompt matches (`hooks/tezgah_context.py::classify_prompt`). `fanout` arms on the
+shape of the request, not a word. Two or more list entries on their own lines
+arm it, and so does an explicit subagent, parallel or worktree ask. The owner
+no longer has to say "do it with subagents, in parallel". On that turn only, the
 matching paragraphs are appended after the reminder
 (`hooks/tezgah_context.py::context_for`); a session that never asks such a question
 pays the one-line pointer instead. The patterns carry Turkish stems because the
@@ -300,7 +334,7 @@ a keyword match, not intent: "don't touch `verify-off`" names the switch too.
 | `verify-off` | `**Integrity: evidence…**`, and the per-turn evidence-scope line with it | `hooks/tezgah_context.py::switches`, `hooks/tezgah_context.py::context_for` |
 | `consult-off` | `**Consult before irreversible.**` | `hooks/tezgah_context.py::switches` |
 | `research-off` | `**Research: route it to OpenResearch.**` | `hooks/tezgah_context.py::switches` |
-| `orchestrate-off` | the orchestration section of the on-demand skill (there is no core paragraph) | `hooks/tezgah_context.py::switches` disables it, `hooks/tezgah_context.py::context_for` injects "Orchestration is off", and the skill-ignore note is `hooks/tezgah_context.py::context_for` |
+| `orchestrate-off` | `**Parallel by default: fan out independent items.**`, and the orchestration section of the on-demand skill | `hooks/tezgah_context.py::switches` drops the paragraph, `hooks/tezgah_context.py::context_for` injects "Orchestration is off" and drops the specialists line, and the skill-ignore note is `hooks/tezgah_context.py::context_for` |
 | `reminder-off` | the per-turn reminder | `hooks/tezgah_context.py::context_for` returns `None` |
 | `judge-off` | the judgement seam: the snapshot triage, the docs page fallback and the skill hint | `hooks/tezgah_judge.py::available` — `available()` is asked before any call, so an armed switch makes no request at all |
 | `triage-off` | the snapshot triage alone (`bin/tezgah-triage`), leaving the docs fallback and the skill hint armed | `bin/tezgah-triage::off_reason` — `off_reason()` answers this switch before the seam's, so the analyze-app loop reads the tree instead of paying for a judgement |
@@ -378,11 +412,19 @@ brief carries the same caller-list floor (`hooks/tezgah_agents.py`), and
 
 ## When the injected text grows too large
 
-Each event has a byte budget: `session_start` and `post_compact` 12000,
-`user_prompt` 6000, `subagent_start` 5500, anything else 12000
+Each event has a byte budget: `session_start` and `post_compact` 13000,
+`user_prompt` 6000, `subagent_start` 5500, anything else 13000
 (`hooks/tezgah_context.py::CONTEXT_BUDGET`). The rationale and the measured
-sizes sit beside it. A fixture repo builds 10066 B at `session_start` and about
-5150 B at `subagent_start`. A `user_prompt` that arms all five conditional rules
+sizes sit beside it. In an empty fixture repo, `session_start` with the core
+builds 9842 B before the ponytail and ADHD rules went inline and 10884 B after
+(+1042 B). The fan-out pointer adds 112 B and the `tezgah-skill` sentence
+113 B, so the always-on band is 10499 B (`tests/test_setup.py`). The healthy
+fixture with a lesson and a plan then built 12059 B. At the old 12000 B budget
+it lost its lessons and sibling checkouts to pay for core rules, so the budget
+moved to 13000 B. The subagent brief and the reminder stay the same size.
+`SkillRulesInForceAtSessionStart` (`tests/test_context.py`) pins the rules
+themselves, not the size. A
+`user_prompt` that arms all five conditional rules
 for the first time builds 7503 B. That is over its budget on purpose: an armed paragraph
 is never dropped, and every later match in the session pays one line. The
 budget is a byte count, not a token estimate.
@@ -390,7 +432,7 @@ budget is a byte count, not a token estimate.
 Over budget, `budgeted()` gives up blocks in `DROP_ORDER`, lowest value
 first — the text another surface already carries (project knowledge, the
 sibling-checkout line, lessons), the skill hint (a suggestion, never an
-instruction), the per-turn relevant lessons and the plan table first, then the tooling-availability lines and the live graph
+instruction), the per-turn relevant lessons and the plan table first, then the Orca line, the tooling-availability lines and the live graph
 glance, then the resume state (it outlives those because it is the only one that
 says what this session was doing, and it still yields to a rule), then the
 evidence-scope warning, the task phase, the delta, and the skill pointer last

package/docs/environment.md

@@ -44,6 +44,7 @@ the kill switches are files, not variables, and live in
 | `TEZGAH_NO_EXCLUDE` | `hooks/tezgah_agents.py::ensure_exclude` | unset | `1` stops tezgah adding its generated-agent dirs to the repository's `.git/info/exclude`. |
 | `CODEX_HOME` | `hooks/tezgah_paths.py::HOST_DIRS` | `~/.codex` | The Codex home tezgah installs into and checks; the same variable Codex itself reads. |
 | `DSH_HOME` | `hooks/tezgah_paths.py::HOST_DIRS`, `bin/tezgah-dsh`, `bin/tezgah-dsh.cmd` | `~/.dsh` | The dsh home tezgah installs into, and where `tezgah-dsh` looks for the CLI. |
+| `ORCA_WORKTREE_ID`, `ORCA_TERMINAL_HANDLE`, `ORCA_PANE_KEY`, `TERM_PROGRAM=Orca` | `hooks/tezgah_orca.py::session` | unset | Exported by an Orca terminal. Any one marks the session as inside Orca: the session-start block gains the `Orca:` line and `tezgah-setup --status` an `orca:` line ([orca](orca.md)). tezgah never writes them. |
 | `TEZGAH_OPENCODE_DATA` | `bin/tezgah-setup::OPENCODE_DATA`, `bin/tezgah-doctor` | `~/.local/share/opencode` | opencode's data dir: its session database for `tezgah-doctor` and the installer. |
 
 ## Which binary runs
@@ -52,8 +53,9 @@ the kill switches are files, not variables, and live in
 |---|---|---|---|
 | `TEZGAH_CODEGRAPH_BIN` | `hooks/tezgah_paths.py::codegraph_bin` | the config file, then `codegraph` on PATH | The codegraph executable the index and the graph marks use. |
 | `TEZGAH_ORX_BIN` | `hooks/tezgah_paths.py::orx_bin` | `orx` on PATH | The OpenResearch CLI the research rule routes to. |
-| `TEZGAH_OMP_BIN` | `hooks/tezgah_paths.py::omp_bin` | `omp` on PATH | The omp binary the installer, the model table and consult's session-model lookup run. |
-| `TEZGAH_CLAUDE_BIN` | `claude_bin`, `hooks/tezgah_paths.py::claude_bin` | `claude` on PATH | The Claude Code CLI `--install` registers the plugin with (`claude plugin`); the test suite points it at a path that does not exist. |
+| `TEZGAH_ORCA_BIN` | `hooks/tezgah_orca.py::cli` | `ORCA_CLI_COMMAND`, then `$ORCA_CLI_BIN_DIR/orca`, then `orca` on PATH (`orca-ide` on Linux outside Orca), then the macOS app's CLI | The Orca CLI `tezgah-status --orca` and `tezgah-setup --status` ask. A missing path is no CLI, never a fallback: the test suite points it at one. |
+| `TEZGAH_OMP_BIN` | `hooks/tezgah_paths.py::omp_bin` | `omp` on PATH | The omp binary the installer, the model table, consult's session-model lookup and the judgement seam's session call run; tests point it at a stand-in. |
+| `TEZGAH_CLAUDE_BIN` | `claude_bin`, `hooks/tezgah_paths.py::claude_bin` | `claude` on PATH | The Claude Code CLI `--install` registers the plugin with (`claude plugin`) and the judgement seam asks in a Claude Code session; the test suite points it at a path that does not exist, or at a stand-in. |
 | `TEZGAH_DSH_BIN` | `bin/tezgah-setup::reconcile_json_servers` | the profile-local entry, then `bin/tezgah-dsh`, then npx | How the installer invokes the dsh CLI. |
 | `TEZGAH_INDEX_BIN` | `bin/tezgah-dsh:19`, `bin/tezgah-dsh.cmd` | `~/.config/tezgah/bin/tezgah-index` | The index worker `tezgah-dsh` warms before it starts dsh. |
 | `TEZGAH_STATUS_BIN` | `hosts/dsh/statusline/lib/index.js:24`, `hosts/opencode/tui/tezgah-tui.tsx` | `~/.config/tezgah/bin/tezgah-status` | The status renderer the dsh status line and the opencode TUI call. |
@@ -71,7 +73,8 @@ the kill switches are files, not variables, and live in
 
 | Variable | Read by | Default | Effect |
 |---|---|---|---|
-| `TYPESAFE_API_KEY` | `hooks/tezgah_judge.py::key`, `hooks/tezgah_paths.py` | `~/.config/typesafe/key` | The judgement seam's first credential; omp also reads it for its own judge. |
+| `OMPCODE`, `CLAUDECODE` | `hooks/tezgah_paths.py::session_cli`, `bin/consult`, `hooks/tezgah_models.py::worker_model` | set by the host | Name the host session: the judgement seam asks that host's CLI first (`OMPCODE` wins, omp sets both). The test suite unsets both. |
+| `TYPESAFE_API_KEY` | `hooks/tezgah_judge.py::key`, `hooks/tezgah_paths.py` | `~/.config/typesafe/key` | The judgement seam's first third-party credential, used as `fallback` in `config.json` allows ([judge](judge.md)); omp also reads it for its own judge. |
 | `OPENROUTER_API_KEY` | `hooks/tezgah_judge.py::openrouter_key`, `bin/consult`, `bin/codegen`, `hooks/tezgah_models.py` | `~/.config/openrouter/key` | The seam's chat fallback, consult's and codegen's `openrouter` provider, and omp's `any` family. |
 | `DEEPSEEK_API_KEY`, `INCEPTION_API_KEY` | `bin/consult`, `bin/codegen`, `hooks/tezgah_replay.py::label_model` | `~/.config/deepseek/key`, `~/.config/inception/key` | The `deepseek` and `inception` providers of consult and codegen; `DEEPSEEK_API_KEY` alone is also the replay sheet's `--provider deepseek` rater. |
 | `ANTHROPIC_OAUTH_TOKEN`, `ANTHROPIC_API_KEY`, `ZAI_API_KEY` | `hooks/tezgah_models.py::OMP_AUTH` | omp's own auth store | Read as presence only: whether omp can run the `anthropic` or `zai` model family, so the model table can pick a row omp will run. |

package/docs/evidence.md

@@ -313,6 +313,13 @@ The four shape classes share their switches with the text they enforce: `adhd-of
    has only its words as the trigger. There a claim word inside a question or under a negation in
    its own clause is no claim (`asserted_claims`). Examples: "testler geçti mi?", "is it done?",
    "not tested yet", "tamamlandı değil". "Tamamlandı, push edeyim mi?" still claims.
+   A prose edit is no step and no change (`hooks/tezgah_integrity.py::_prose_edit`,
+   `hooks/tezgah_integrity.py::_work_row`). Such an `edit` row has a real `target` ending in
+   `.md`, `.markdown`, `.rst` or `.adoc`. It owes no check and does not stale a pass. An agent
+   instruction file is not prose: `SKILL.md`, `AGENTS.md`, `CLAUDE.md` and anything under
+   `skills/`, `prompts/`, `agents/`, `commands/` or a host directory stay a change. A reply that
+   claims a test ran ("tested", "tüm testler geçti") still needs a pass after a prose-only turn.
+   A comment-only edit to code is still a change: the row carries no text to tell it apart.
 10. **no external read** — the reply states the state of a system tezgah does not own — a registry,
    a release, a tag, a formula, a CI run — and no read of that system ran in the same turn
    (`hooks/tezgah_integrity.py::_external_claim`, over `EXTERNAL_SYSTEM`/`EXTERNAL_STATE`

package/docs/gate.md

@@ -244,13 +244,19 @@ failures. Under `verify-off` (`hooks/tezgah_gate.py::decision`).
 Trigger: the same call has been attempted more than `RETRY_CEILING = 3` times in the session, whatever those attempts returned (`hooks/tezgah_gate.py::RETRY_CEILING`, `retry_reason`
 `hooks/tezgah_gate.py::retry_reason`). Told: an unchanged repeat is not a retry (`hooks/tezgah_gate.py::loop_reason`). Standing. Under `verify-off` (`hooks/tezgah_gate.py::decision`). Both guards read only the ledger tail.
 
-### Nudge — the first identifier-shaped search of a session
-
-Trigger: a `Grep` whose pattern, or a `grep`/`rg` argument (`hooks/tezgah_gate.py::BASH_SEARCH`), matches `IDENT` (`^[A-Za-z_][A-Za-z0-9_]{2,}$`, `hooks/tezgah_gate.py::IDENT`), in a repo whose
-codegraph index exists (`<repo>/.codegraph/codegraph.db`; `searched_identifier`
-`hooks/tezgah_gate.py::searched_identifier`). Told: the runnable command built from the denied search (`codegraph explore <X>`, `codegraph callers <X>`, `codegraph impact <X>`), and that an omp subagent uses this CLI because omp's MCP device refuses concurrent writes
-(`hooks/tezgah_gate.py::nudge_reason`).
+### Nudge — the first code-symbol search of a session, then a line beside every later one
+
+Trigger: a search for a code symbol, in a repo whose codegraph index exists (`<repo>/.codegraph/codegraph.db`) and that has no `.no-graph` (`hooks/tezgah_gate.py::index_slug`).
+A code symbol has an inner underscore or a lower-to-upper step, or sits in a `def x` or `x\(` pattern (`hooks/tezgah_gate.py::symbol_in`).
+A plain word such as `TODO` is literal text and never matches.
+The search is the pattern of a `grep`, `search` or `ast_grep` tool, a term of omp's `find`, or a `grep`/`rg` argument (`hooks/tezgah_gate.py::searched_symbol`, `hooks/tezgah_gate.py::BASH_SEARCH`).
+omp's bridge sends `find`, `search` and `ast_grep` to the gate, because omp's own prompt sends code discovery to `find` first (`hosts/omp/tezgah-hook.ts.in`).
+Told: the host's graph tool (`hooks/tezgah_gate.py::graph_tool`) and the runnable command built from the denied search (`codegraph explore <X>`, `codegraph callers <X>`, `codegraph impact <X>`).
+An omp subagent uses this CLI, because omp's MCP device refuses concurrent writes (`hooks/tezgah_gate.py::nudge_reason`).
 Once-only: the mark in `cache_dir()/nudged/<sha1(session)[:16]>` is written *before* the refusal, so re-issuing the search passes (`hooks/tezgah_gate.py::first_nudge`). opencode's `oncePerSession` writes the same name (`hooks/tezgah_gate.py::nudge_mark`).
+After that, every later symbol search passes with one line naming the graph tool, while the index stamp equals HEAD (`hooks/tezgah_gate.py::graph_advice`).
+Claude reads the line as PreToolUse `additionalContext` (`hooks/projects-pretooluse.py`), and omp reads it with the call's `tool_result` (`hosts/omp/tezgah-hook.ts.in`).
+Codex and Cursor read it with their PostToolUse result (`hosts/codex/hook.py`, `hosts/cursor/hook.py`).
 
 ### Drift — a long turn loses the rules it started with
 
@@ -395,7 +401,7 @@ rule's triggers are the classes `_stop_block` returns, the four `_shape_block` a
 ## Source of truth
 
 - `hooks/tezgah_gate.py` — `hooks/tezgah_gate.py::decision`; every rule constant and refusal text `hooks/tezgah_gate.py:162-2157`; `attribution`/`attribution_edit` `hooks/tezgah_gate.py::attribution`, `hooks/tezgah_gate.py::attribution_edit`; `explored`
-  `hooks/tezgah_gate.py::explored`; `hooks/tezgah_gate.py::searched_identifier`, `hooks/tezgah_gate.py::index_slug`, `hooks/tezgah_gate.py::first_nudge`, `hooks/tezgah_gate.py::nudge_reason`; `hooks/tezgah_gate.py::LOOP_ATTEMPTS`, `hooks/tezgah_gate.py::loop_reason`,
+  `hooks/tezgah_gate.py::explored`; `hooks/tezgah_gate.py::searched_symbol`, `hooks/tezgah_gate.py::index_slug`, `hooks/tezgah_gate.py::first_nudge`, `hooks/tezgah_gate.py::nudge_reason`, `hooks/tezgah_gate.py::graph_advice`; `hooks/tezgah_gate.py::LOOP_ATTEMPTS`, `hooks/tezgah_gate.py::loop_reason`,
   `hooks/tezgah_gate.py::RETRY_CEILING`, `hooks/tezgah_gate.py::retry_reason`; `hooks/tezgah_gate.py::secret_command`, `hooks/tezgah_gate.py::race_reason`,
   `hooks/tezgah_gate.py::drift_reason`, `hooks/tezgah_gate.py::effectful`, `hooks/tezgah_gate.py::_deny`; the plan rule's own section `hooks/tezgah_gate.py:1391-1588` — `hooks/tezgah_gate.py::plan_reason`, `hooks/tezgah_gate.py::_branch`, `hooks/tezgah_gate.py::_checkout`, `hooks/tezgah_gate.py::_product`, `hooks/tezgah_gate.py::PLAN_DENY`; `hooks/tezgah_gate.py::write_paths`, `hooks/tezgah_gate.py::shell_target`, `hooks/tezgah_gate.py::SHELL_AS_WRITE`; the `capture` call `hooks/tezgah_gate.py::decision` (a write tool's target, and a shell write's)
 - `hooks/projects-pretooluse.py` — the Claude and dsh envelope; `hooks/tezgah_paths.py` — `off`, `root_for`, `cache_dir`

package/docs/glossary.md

@@ -86,7 +86,7 @@ One measured row of always-on context the installer reports in bytes: the core c
 `output-styles/tezgah.md`, a by-hand duplicate of `always_on_core()` kept for the host path that is hookless, which a test holds to the generator (`tests/test_context.py::OutputStyleMirrorsCore`). Not generated: an edit to [CORE](#core) must be carried into it by hand - a lesson the local `.tezgah/lessons.md` ledger holds; that file is untracked by design, so it carries no `path:line` here.
 
 ### nudge
-The one-time hint that sends a first identifier-shaped search to the code graph, `first_nudge()` consuming a per-session mark before the grep is denied (`hooks/tezgah_gate.py::first_nudge`) with the text naming the graph tools (`nudge_reason()`, `hooks/tezgah_gate.py::nudge_reason`). Not a deny: it is spent by being delivered, and the identical call passes on the retry.
+The one-time hint that sends a first code-symbol search to the code graph, `first_nudge()` consuming a per-session mark before the grep is denied (`hooks/tezgah_gate.py::first_nudge`) with the text naming the graph tools (`nudge_reason()`, `hooks/tezgah_gate.py::nudge_reason`). Not a deny: it is spent by being delivered, and the identical call passes on the retry. Every later symbol search gets a non-blocking line naming the graph tool (`hooks/tezgah_gate.py::graph_advice`).
 
 ### observable measure
 A used-mark a surface is able to see at all, so it can say "armed, not used yet" without inventing it: `health_segments(observable=...)` (`hooks/tezgah_context.py::health_segments`) with the five tool-use measures in `TOOL_USE_MEASURES` (`hooks/tezgah_context.py::TOOL_USE_MEASURES`), a measure outside the set rendering as `info` rather than `ready`. Which host can see a skill read is [hosts](hosts.md)'s.

package/docs/hosts.md

@@ -141,6 +141,52 @@ An installed host whose core line is missing is a health check's business
 (`host_checks_<host>`), not a second copy: two delivery paths for one host is the
 same rules paid twice per session.
 
+## Precedence: what each host loads, and in which order
+
+Several host dirs are read by more than one host. The table gives each host's
+documented order. "First wins" means the host keeps the first copy of a name
+and drops the later ones.
+
+| concern | host | order | tezgah's part |
+|---|---|---|---|
+| context | claude | `~/.claude/CLAUDE.md`, then the repo's `CLAUDE.md`, `.claude/CLAUDE.md`, `CLAUDE.local.md`; all load | block in the first |
+| context | codex | `$CODEX_HOME/AGENTS.override.md`, else `AGENTS.md`, then the repo's `AGENTS.md` | block in the first |
+| context | cursor | the `sessionStart` hook context, the repo's `AGENTS.md`, `.cursor/rules/*.mdc`, `.cursorrules` | the hook |
+| context | opencode | `~/.config/opencode/AGENTS.md`, `opencode.json` `instructions`, the repo's `AGENTS.md` | the contract and router files in `instructions` |
+| context | omp | `SYSTEM.md`, `APPEND_SYSTEM.md`, `RULES.md` (sticky), the repo's `.omp/AGENTS.md`, `AGENTS.md`, `CLAUDE.md`; another host's user files only with `enabledProviders` | block in `RULES.md`, the extension at session start |
+| skills | omp | `skills.customDirectories`, then `.omp/skills` and `~/.omp/agent/skills`, Claude's project dir (user dir opt-in), `.agents/skills` and `~/.agents/skills`; first wins, identical copies collapse, a differing copy is renamed `<namespace>/<name>` | links in `~/.omp/agent/skills` |
+| skills | claude | `.claude/skills`, `~/.claude/skills`; plugin skills are namespaced `tezgah:<name>` | the plugin copy |
+| skills | codex | `.agents/skills` from the cwd up to the repo root, `~/.agents/skills`, `$CODEX_HOME/skills`; one name in two dirs is listed twice, not merged | links in `$CODEX_HOME/skills` |
+| skills | cursor | `.agents/skills`, `.cursor/skills`, `~/.agents/skills`, `~/.cursor/skills`, then Claude's and Codex's project and user dirs; no documented winner | links in `~/.cursor/skills` |
+| skills | opencode | its own skill tool is denied; the router lists `~/.config/opencode/skills`, `~/.claude/skills`, `~/.agents/skills`, first wins (`bin/tezgah-setup::skill_groups`) | links and the router |
+| hooks | claude | user `settings.json` rows (Orca's), project rows, the plugin's `hooks/hooks.json` (tezgah's); every matching row runs, none is ordered before another | plugin rows |
+| hooks | codex, cursor | `hooks.json` array order, then the repo's `.codex/` or `.cursor/hooks.json`; Codex runs a row only once its hash is trusted | own rows after Orca's |
+| hooks | opencode | every `*.js`/`*.ts` in `plugins/` and `plugin/`; `tezgah.js` is linked into both, and its `globalThis.__tezgahPluginLoaded` guard makes the second load return `{}` | the plugin |
+| hooks | omp | `~/.omp/agent/extensions/` first, then `config.yml` `extensions:`, one load per absolute path; per event in that order, and the first `block` ends a tool call | the bridge in `hooks/pre/` |
+| mcp | each | omp: project `.omp/mcp.json`, then `~/.omp/agent/mcp.json`, first name wins; claude: `~/.claude.json`, the repo's `.mcp.json`, the plugin's `.mcp.json`; codex: `$CODEX_HOME/config.toml`; cursor: `~/.cursor/mcp.json`; opencode: `opencode.json` `mcp` | one `tezgah` and one `codegraph` row per host |
+
+Orca is a launcher, not a host. It starts omp with its own `--extension`. It
+gives each Codex account its own `CODEX_HOME` under
+`~/Library/Application Support/orca/codex-accounts/<id>/home`. It adds its
+status rows to Claude's `settings.json`, to Cursor's `hooks.json`, to that
+Codex home's `hooks.json` and to opencode's `plugins/`. Its rows sit beside
+tezgah's. The installer arms the `CODEX_HOME` it runs under
+(`hooks/tezgah_paths.py::HOST_DIRS`). An install from a plain terminal and one
+from an Orca pane therefore arm two different Codex homes.
+
+`tezgah-doctor --stack [--repo PATH] [--json]` prints this stack as it stands
+on the machine (`hooks/tezgah_stack.py::host_stack`). It exits 1 on a conflict
+(`hooks/tezgah_stack.py::conflicts`). The kinds are `skill-differs`, `skill-dup`,
+`skill-stale`, `rule-twice`, `hook-twice`, `mcp-twice`, `backup-in-scan` and
+`orphan-copy`. `skill-differs` names the copy that wins. `skill-stale` is a
+tezgah copy that is not this tree's bytes. `orphan-copy` is a Claude plugin
+copy that `installed_plugins.json` no longer names.
+
+A backup tezgah writes never lands in a host dir. It goes under
+`~/.config/tezgah/backups/` (`bin/tezgah-setup::backup_base`), because omp
+lists every file in `hooks/pre/` as a hook. `--install` moves the backups older
+releases left in host dirs (`bin/tezgah-setup::sweep_backups`).
+
 ## The model wire
 
 The matrix above is about events. This is about the other side of a host: which
@@ -196,7 +242,7 @@ In order, each step verified by the one below it:
    (`hosts/omp/tezgah-hook.ts.in` rendered at `hooks/tezgah_attest.py::omp_bridge`).
 3. `install_<host>()` writing that host's files, registered in `INSTALLERS`
    (`bin/tezgah-setup::INSTALLERS`), and `uninstall_<host>()` removing only
-   tezgah-managed links and blocks (`bin/tezgah-setup:3286-3418`).
+   tezgah-managed links and blocks (`bin/tezgah-setup:3287-3419`).
 4. `host_checks_<host>()` returning `(label, bool)` rows over what was actually
    written, registered in `HOST_CHECKS` (`bin/tezgah-setup::HOST_CHECKS`); the
    `--report` output is that list (`bin/tezgah-setup::report`). Give the row a home-qualified
@@ -398,3 +444,4 @@ In order, each step verified by the one below it:
 - `hosts/opencode/plugins/tezgah.js`, `hosts/opencode/tui/tezgah-tui.tsx`
 - `statusline.py`, `bin/tezgah-status`, `hooks/tezgah_context.py`
 - `hooks/tezgah_models.py` - the per-host model surface in `## The model wire`
+- `hooks/tezgah_stack.py`, `bin/tezgah-doctor` `--stack` - the order in `## Precedence`

package/docs/index.json

@@ -368,7 +368,8 @@
         "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"
+        "how do I turn on taste signal capture and measure my corrections",
+        "how does taste learn my coding preferences and inject them"
       ],
       "answers_tr": [
         "bunu bir makineye nasıl kurar, doğrular ve yükseltirim",
@@ -376,7 +377,8 @@
         "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"
+        "zevk sinyali kaydını nasıl açar ve düzeltmelerimi nasıl ölçerim",
+        "taste kodlama tercihlerimi nasıl öğrenir ve oturuma nasıl ekler"
       ],
       "sources": [
         "bin/tezgah-setup",
@@ -390,6 +392,7 @@
         "README.md",
         "hooks/tezgah_embed.py",
         "hooks/tezgah_taste.py",
+        "hooks/tezgah_taste_ledger.py",
         "bin/tezgah-taste"
       ]
     },
@@ -466,6 +469,34 @@
         "docs/testing.md",
         "AGENTS.md"
       ]
+    },
+    {
+      "path": "docs/orca.md",
+      "title": "Orca: what it owns, what tezgah owns, where they meet",
+      "title_tr": "Orca: neyin sahibi, tezgah neyin sahibi, nerede kesişirler",
+      "audience": "maintainer, agent working inside Orca",
+      "answers": [
+        "how does a session know it runs inside Orca",
+        "should a slice use orca worktree create or git worktree add",
+        "which checkouts of this repo does Orca track",
+        "does tezgah overwrite Orca's codex home or hooks"
+      ],
+      "answers_tr": [
+        "bir oturum Orca içinde çalıştığını nasıl anlar",
+        "bir dilim orca worktree create mi yoksa git worktree add mi kullanmalı",
+        "Orca bu deponun hangi çalışma kopyalarını izliyor",
+        "tezgah Orca'nın codex dizinini veya hook'larını ezer mi"
+      ],
+      "sources": [
+        "hooks/tezgah_orca.py",
+        "hooks/tezgah_context.py",
+        "hooks/tezgah_policy.py",
+        "hooks/tezgah_agents.py",
+        "bin/tezgah-status",
+        "bin/tezgah-setup",
+        "skills/tezgah-contract/SKILL.md",
+        "statusline.py"
+      ]
     }
   ]
-}
+}