@r1z4x/tezgah 1.0.0 → 1.1.0

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

@@ -466,6 +466,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"
+      ]
     }
   ]
-}
+}

package/docs/judge.md

@@ -1,8 +1,8 @@
 # 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
+The judgement seam is `hooks/tezgah_judge.py`. It asks the session's own model,
+through the host's CLI, 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
@@ -11,7 +11,7 @@ the kill-switch paragraph and nothing else (`CORE`,
 
 ## What it is
 
-One seam, five callers, one credential, one egress boundary, one price, one
+One seam, five callers, one provider order, 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
@@ -21,12 +21,12 @@ are module constants (`URL`, `hooks/tezgah_judge.py::URL`; `KEY_FILE`,
 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.
+attempt. A 4xx, a session CLI's non-zero exit 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`).
+A session CLI answers in 4-10 s (measured 2026-10-07), so the skill hint's
+4 s deadline usually ends first. `TEZGAH_TYPESAFE_URL`, `TEZGAH_OPENROUTER_URL`
+and `TEZGAH_OMP_BIN`/`TEZGAH_CLAUDE_BIN` are the test seams.
 
 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
@@ -39,13 +39,13 @@ 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
+The state leaves the machine. By default it goes to the session's own vendor,
+through the session's own CLI and credential ([below](#the-providers-and-their-order)).
+A third party - `api.typesafe.ai` or `openrouter.ai` (`OPENROUTER_URL`,
+`hooks/tezgah_judge.py::OPENROUTER_URL`) - reads it only as the `fallback`
+setting allows. For the triage the state is the screen's own text, so whoever
+answers reads any personal data on it. For the docs fallback it is the query.
+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`,
@@ -77,37 +77,42 @@ caches one answer per `(session, prompt)` (`_remember`,
 `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 providers and their order
+
+`providers()` (`hooks/tezgah_judge.py::providers`) is the order `ask()` tries.
+The next one is asked only when the previous failed. First comes the session's own
+CLI (`tp.session_cli`, `hooks/tezgah_paths.py::session_cli`): `omp` when
+`OMPCODE` is set, else `claude` when `CLAUDECODE` is. It runs headless with no
+tools, rules, skills, extensions, MCP servers or settings (`SESSION_ARGV`,
+`hooks/tezgah_judge.py::SESSION_ARGV`). Measured 2026-10-07, a call cost $0.007
+on claude and $0.015 on omp. The session's own credential pays, OAuth subscription
+included. The model and usage are read from the CLI's JSON output
+(`_session_request`, `hooks/tezgah_judge.py::_session_request`). Then come the
+third parties. TypeSafe reads `TYPESAFE_API_KEY`, else `~/.config/typesafe/key`
+(`key`, `hooks/tezgah_judge.py::key`). OpenRouter reads `OPENROUTER_API_KEY`, else
+`~/.config/openrouter/key` (`openrouter_key`, `hooks/tezgah_judge.py::openrouter_key`).
+It asks the table's cheap row unless `TEZGAH_JUDGE_MODEL` names another
+(`fallback_model`, `hooks/tezgah_judge.py::fallback_model`). The key file is
+read because a hook runs where `~/.zshenv` never did. A chat answer is asked for in prose
+(`CHAT_SYSTEM`, `hooks/tezgah_judge.py::CHAT_SYSTEM`) and filtered to the ids
+asked, a wrongly typed answer dropped (`_chat_answers`,
+`hooks/tezgah_judge.py::_chat_answers`).
+
+`fallback` in `~/.config/tezgah/config.json` (`fallback_policy`,
+`hooks/tezgah_paths.py::fallback_policy`) decides who may stand in:
+
+| `fallback` | Session CLI present | No session CLI |
+|---|---|---|
+| `vendor` (default) | the session CLI only; when it fails, no judgement | TypeSafe, then OpenRouter |
+| `any` | the session CLI, then TypeSafe, then OpenRouter | TypeSafe, then OpenRouter |
+| `none` | the session CLI only | nobody: `available()` is false |
+
+Nothing that stands in is silent. A result carries `provider`, the `model`
+the reply named and `fallback` - None when the session answered, else why it did
+not. That answer, and a refusal with its failures, is said on stderr as one
+`tezgah-judge:` line. It is also kept as the last-use record (`_record`,
+`hooks/tezgah_judge.py::_record`), which `tezgah-status --judge` prints. The skill
+hint's cost row and the router's `route` row also carry `judge=<provider>/<model>`.
 
 ## The switches
 
@@ -152,11 +157,11 @@ known (`note`, `hooks/tezgah_integrity.py::note`), counted by the row's kind
 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 would make two runs of the same command disagree. Beside the last-use
+   record, the seam keeps a failure marker (`DOWN_FOR`, 300 s, in `hooks/tezgah_judge.py`). A
+   call that ends on a 401, 402, 5xx or a session CLI's non-zero exit marks that
+   provider, endpoint and credential down for five minutes. Until the marker
+   expires, that provider is skipped and sent 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
@@ -185,8 +190,9 @@ known (`note`, `hooks/tezgah_integrity.py::note`), counted by the row's kind
 - `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.
+  receives; `hooks/tezgah_paths.py` — where a switch file is read, the session CLI
+  and the `fallback` setting, and the redirect guard (`guarded_opener`) the seam,
+  consult and codegen share; `bin/tezgah-status --judge` — the last-use record.
 - `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` —

package/docs/models.md

@@ -20,7 +20,12 @@ and every slot a model per family (`SLOTS`, `hooks/tezgah_models.py::SLOTS`). Th
 three tier workers - `tezgah-cheap`, `tezgah-standard`, `tezgah-frontier` - are
 generated in every tezgah root because routing needs no capability (`ROLES`,
 `hooks/tezgah_agents.py::ROLES`; their brief, `_worker_body`,
-`hooks/tezgah_agents.py::_worker_body`). A cheaper worker that meets work above its tier
+`hooks/tezgah_agents.py::_worker_body`). So are the five specialists:
+`tezgah-tester`, `tezgah-docs`, `tezgah-security`, `tezgah-ui` and
+`tezgah-researcher` (`hooks/tezgah_agents.py::SPECIALISTS`). A specialist's
+description names its slot from `AGENT_SLOT`. The tier a host shows and the
+model line it runs therefore cannot disagree, and `tezgah-agents --list` prints
+both. A cheaper worker that meets work above its tier
 answers `ESCALATE: <why>`, and the router restarts the task on `tezgah-frontier`
 with the original brief rather than handing the failed trajectory up: continuing a
 cheap trajectory on a frontier model was the most expensive option measured
@@ -30,10 +35,10 @@ cheap trajectory on a frontier model was the most expensive option measured
 
 | slot | agents | anthropic | zai (omp's own provider) | openai | any (OpenRouter id) |
 |---|---|---|---|---|
-| cheap | tezgah-cheap | Opus 5.5 @low | `zai/glm-5.3-flash` | GPT-6.1 Sol @low | GLM-5.3 Flash |
+| cheap | tezgah-cheap, tezgah-tester | Opus 5.5 @low | `zai/glm-5.3-flash` | GPT-6.1 Sol @low | GLM-5.3 Flash |
 | explore | omp's bundled `scout` | Opus 5.5 @medium | `zai/glm-5.3-flash` | GPT-6.1 Sol @low | DeepSeek V4.1 Flash |
-| standard | tezgah-standard | Opus 5.5 @medium | `zai/glm-5.3` | GPT-6.1 Sol @high | GPT-6.1 Sol @high |
-| frontier | tezgah-frontier, tezgah-reviewer | Opus 5.5 @high | `zai/glm-5.3` | GPT-6 Astra @high | Opus 5.5 @high |
+| standard | tezgah-standard, tezgah-docs, tezgah-ui | Opus 5.5 @medium | `zai/glm-5.3` | GPT-6.1 Sol @high | GPT-6.1 Sol @high |
+| frontier | tezgah-frontier, tezgah-reviewer, tezgah-security, tezgah-researcher | Opus 5.5 @high | `zai/glm-5.3` | GPT-6 Astra @high | Opus 5.5 @high |
 
 Why these, briefly. Inside the Anthropic family the lever is effort, not model:
 Opus 5.5 and Sonnet 5.5 read cache at the same $0.20 per 1M tokens, and on
@@ -56,7 +61,7 @@ invoices).
 | Claude Code | anthropic | the agent file's alias and `effort:` (`_model_lines`): an alias follows the provider and keeps the main session's variant, where a full id breaks on Bedrock, Vertex and a gateway (code.claude.com/docs/en/sub-agents) |
 | Codex | openai | `model` and `model_reasoning_effort` in `.codex/agents/*.toml` |
 | opencode | any | a selector `--refresh` found in `opencode models` for the slot's model under any configured provider (`resolve_opencode`); none found, no model line, so the agent inherits. The slot's effort rides the JSON agent config as `reasoningEffort` (opencode.ai/docs/agents) |
-| omp | anthropic when the session default is an Anthropic model, any otherwise (`omp_mode`); a non-Anthropic default is `any`, never a silent fall back to the Anthropic column | `task.agentModelOverrides`, which omp resolves before the agent or bundled model (omp's own docs: `omp://task-agent-discovery.md`, *Model and structured-output precedence*); every slot is written, the frontier row included, so no agent in the row runs on the session default; each override is a **cross-family fallback chain** (`omp_overrides`): the mode's family first, then every other family this machine holds a credential for (`funded_families` reads omp's auth store and the provider env keys; a family it cannot see is left out, never guessed in) - omp splits the chain into per-spawn patterns (omp's own docs: `omp://settings.md (its `retry.fallbackChains` section)`), so one provider's 429 falls through instead of killing the spawn, measured before this: 24 of 26 post-routing 429s hit a subagent's first request, all on one Opus account every slot shared; `apply_omp` also writes `modelRoles.plan` and `.slow` on that frontier row (same record, same ownership) so plan mode designs on it, and their fallbacks go to `retry.fallbackChains.<role>`, the only chain keys tezgah owns (`default` and provider-keyed chains stay the user's); `apply_omp` writes through the installer's own binary and agent dir, from HOME so a repository's `.omp/config.yml` never leaks machine-wide, and touches only the entries tezgah wrote (recorded in `~/.config/tezgah/models.json` as `omp_written`; a machine written before that record is adopted by its value, `_ours_by_shape`) |
+| omp | anthropic when the session default is an Anthropic model, any otherwise (`omp_mode`); a non-Anthropic default is `any`, never a silent fall back to the Anthropic column | `task.agentModelOverrides`, which omp resolves before the agent or bundled model (omp's own docs: `omp://task-agent-discovery.md`, *Model and structured-output precedence*); every slot is written, the frontier row included, so no agent in the row runs on the session default; each override is a **fallback chain** (`omp_overrides`, `_chain`): the mode's family first, then what `fallback` in `~/.config/tezgah/config.json` allows (`tp.fallback_policy`) over the families this machine holds a credential for (`funded_families` reads omp's auth store and the provider env keys; a family it cannot see is left out, never guessed in) - `vendor`, the default, keeps only the session vendor's model (`openrouter/anthropic/claude-opus-5.5:<effort>` behind an Anthropic session, `OPENROUTER_ID`), so a 429 never moves an Opus session's subagent onto GPT or GLM; `any` adds every other funded family, rotated per agent; `none` writes the first entry alone - omp splits the chain into per-spawn patterns (omp's own docs: `omp://settings.md (its `retry.fallbackChains` section)`), so one provider's 429 falls through instead of killing the spawn, measured before this: 24 of 26 post-routing 429s hit a subagent's first request, all on one Opus account every slot shared; `apply_omp` also writes `modelRoles.plan` and `.slow` on that frontier row (same record, same ownership) so plan mode designs on it, and their fallbacks go to `retry.fallbackChains.<role>` under the same `fallback` rule, the only chain keys tezgah owns (`default` and provider-keyed chains stay the user's); `apply_omp` writes through the installer's own binary and agent dir, from HOME so a repository's `.omp/config.yml` never leaks machine-wide, and touches only the entries tezgah wrote (recorded in `~/.config/tezgah/models.json` as `omp_written`; a machine written before that record is adopted by its value, `_ours_by_shape`); a changed `fallback` reaches omp on the next `tezgah-route --refresh` or `tezgah-setup --install` |
 | dsh | - | none: no model setting was found to write |
 
 The orchestrator agent keeps `model: inherit`: it is the main thread's own agent.
@@ -88,11 +93,12 @@ fixed:
    undone on. A 12-brief fixture pins it: 8 high-stakes briefs route to
    frontier, 4 near-miss controls do not (`tests/test_models.py`).
 2. Otherwise the brief - redacted with the ledger's own reader
-   (`redact`, `hooks/tezgah_integrity.py::redact`) - goes to Jev as one Choice over three tiers (`TIER_QUESTION`,
-   `hooks/tezgah_models.py::TIER_QUESTION`). Measured on 40 English briefs labelled by
+   (`redact`, `hooks/tezgah_integrity.py::redact`) - goes to the judge as one Choice over three tiers (`TIER_QUESTION`,
+   `hooks/tezgah_models.py::TIER_QUESTION`). The judge asks the session's own model first ([judge](judge.md)).
+   Measured with Jev on 40 English briefs labelled by
    the same session that wrote the rubric (2026-09-30, twice): under-route 0.025,
    accuracy 0.925 and 0.900, 392 ms median, about 656 input tokens per call; a
-   keyword rule on the same set under-routed 0.100.
+   keyword rule on the same set under-routed 0.100. The session model was not measured on that set.
 3. With no judgement (`judge-off`, no key, a failed call) `--phase` picks the tier
    from the static table (`PHASE_TIER`, `hooks/tezgah_models.py::PHASE_TIER`), and
    with no phase the middle tier is used.

package/docs/operations.md

@@ -23,7 +23,7 @@ before an install is considered.
 | `--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`). |
+| `--sync` | Copy this checkout over the Claude plugin [copy](glossary.md#plugin-copy) `installed_plugins.json` names, or over every copy when it names none (`bin/tezgah-setup::sync`, `bin/tezgah-setup::live_plugin_copies`). An older version dir is Claude's cache to collect, so it is left alone. 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`). |
@@ -158,7 +158,7 @@ or `default`), a common block (config, the code-graph binary, the consult option
 `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
+"is this host armed" (`AGENTS.md:147-148`) — 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`).
@@ -284,8 +284,8 @@ A **full** run also takes everything the wiring was serving from:
   `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
+Kept in every run: the user's own files, every host-file backup under
+`~/.config/tezgah/backups/` (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
@@ -372,6 +372,7 @@ does not hold.
 | `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 --stack` | per host: the context files in load order, the skill dirs and which copy wins, the hook rows per event with their owner, the MCP servers, and every conflict; exits 1 on one ([hosts](hosts.md#precedence-what-each-host-loads-and-in-which-order), `hooks/tezgah_stack.py::report`) |
 | `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
@@ -541,7 +542,11 @@ with `embed-m2v`. The fusion found it for 0.75 and 0.74, BM25 for 0.68.
 
 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
+copies it to `<file>.<timestamp>.tezgah-bak`. A host file's copy goes under
+`~/.config/tezgah/backups/` (`bin/tezgah-setup::backup_base`). A host lists the
+files in its own dirs. tezgah's own state dir
+keeps its copies beside the file. `--install` moves the copies an older release
+left in a host dir (`bin/tezgah-setup::sweep_backups`). 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

package/docs/orca.md

@@ -0,0 +1,126 @@
+# Orca: what it owns, what tezgah owns, where they meet
+
+Orca is an IDE that runs agent sessions in its own terminals and worktrees.
+This page is for a maintainer or an agent working inside Orca. Read it when a
+session asks how tezgah and Orca share a machine. It describes Orca 1.4.221 and
+1.4.222 as observed on 2026-10-07. Each Orca claim names the command or file
+behind it, so a reader can check it again after a later release.
+
+## How a process knows it runs in Orca
+
+Every terminal Orca starts exports its own markers. The table lists the ones
+tezgah reads, as `env` printed them inside an Orca terminal.
+
+| Variable | Value shape | Read by |
+|---|---|---|
+| `ORCA_WORKTREE_ID` | `<repoId>::<absolute path>` of the Orca worktree | `hooks/tezgah_orca.py::session` |
+| `ORCA_TERMINAL_HANDLE` | `term_<uuid>`, the handle `orca terminal` commands take | `hooks/tezgah_orca.py::session` |
+| `ORCA_PANE_KEY` | `<tab>:<pane>` | `hooks/tezgah_orca.py::session` |
+| `TERM_PROGRAM` | `Orca` | `hooks/tezgah_orca.py::session` |
+| `ORCA_APP_VERSION` | `1.4.221` | `hooks/tezgah_orca.py::session` |
+| `ORCA_CLI_COMMAND` | the wrapper Orca exports for WSL sessions (orca-cli skill) | `hooks/tezgah_orca.py::cli` |
+| `ORCA_CLI_BIN_DIR` | `/Applications/Orca.app/Contents/Resources/bin` | `hooks/tezgah_orca.py::cli` |
+| `CODEX_HOME`, `ORCA_CODEX_HOME` | `~/Library/Application Support/orca/codex-accounts/<id>/home` | `hooks/tezgah_paths.py::HOST_DIRS` (CODEX_HOME only) |
+
+Orca also exports `ORCA_AGENT_HOOK_*` for its hook endpoint, port and token.
+It exports `ORCA_OMP_*` for its omp status extension. tezgah reads none of
+them and writes no `ORCA_*` variable. The marker set in `MARKERS` is the whole
+contract.
+
+A shell started from an Orca terminal inherits the variables. A subagent whose
+working directory is a raw worktree still reports the parent's
+`ORCA_WORKTREE_ID`. So the marker says "inside Orca", not "inside this
+checkout".
+
+## What Orca owns
+
+| Surface | What Orca keeps | Evidence |
+|---|---|---|
+| Worktrees | a git worktree plus a card (status, comment, lineage, links), by default under `~/orca/workspaces/<repo>/<name>` | `orca worktree create --help`; `orca repo show` lists paths under `~/orca/workspaces/tezgah/` |
+| Terminals | live PTYs with handles, read/send/wait | `orca terminal list --json` |
+| Agent sessions | agent type and state per pane, shown in `orca worktree ps` | `agents[].agentType`, `agents[].state` in `orca worktree ps --json` |
+| Orchestration | runs, tasks, dispatch, supervised workers, decision gates | `orca --help`, section Orchestration |
+| Embedded browser | tabs per worktree, snapshot and element refs | `orca --help`, section Browser Automation |
+| Artifacts | public HTML or Markdown links, off until a human enables them in Settings | `orca skills get orca-cli`, section Artifacts |
+| Codex accounts | one codex home per account, marked by `.orca-managed-home` | the account home's directory listing |
+| Its hooks | `~/.orca/agent-hooks/`, plus entries tagged `orca-agent-hook-form=1` in each managed codex `hooks.json` | the account home's `hooks.json` |
+| omp extensions | `orca-agent-status.ts`, `orca-prefill.ts` and `orca-titlebar-spinner.ts` in `~/.omp/agent/extensions/` | that directory's listing |
+
+The `orca-cli` skill is a stub. The full guide comes from the binary itself:
+`orca skills get orca-cli`. Run it before any Orca command a session has not
+run before.
+
+## What tezgah owns
+
+tezgah owns the contract text, the gate, the evidence ledger and the status
+line. It also owns its own hook entries in each host config
+([architecture](architecture.md), [hosts](hosts.md)). It does not create
+worktrees or terminals in code. A parallel slice is an instruction to the
+session: the `Tier 1` paragraph of `hooks/tezgah_policy.py::ORCHESTRATE`,
+mirrored in `skills/tezgah-contract/SKILL.md`, and the orchestrator agent body
+`hooks/tezgah_agents.py::_orch_body`.
+
+## Where they meet
+
+| Point | Behaviour | Code |
+|---|---|---|
+| Session start inside Orca | one `Orca:` line names the worktree and tells the session to use `orca worktree create`, `orca terminal create` and `orca worktree ps`. It reads env only and starts no process. | `hooks/tezgah_orca.py::context_line`, called from `hooks/tezgah_context.py::context_for` |
+| Slice checkouts | inside Orca, `orca worktree create --name <slug> --parent-worktree active --json`, else `git worktree add` | `hooks/tezgah_policy.py::ORCHESTRATE`, `hooks/tezgah_agents.py::_orch_body` |
+| Tracking | `tezgah-status --orca` lists each checkout Orca tracks (card, state, live terminals, agent states) and each git worktree Orca does not list | `bin/tezgah-status::print_orca`, `hooks/tezgah_orca.py::checkouts` |
+| Install report | `tezgah-setup --status` prints one `orca:` line where Orca is present. The line names the runtime, the terminal and an Orca-managed CODEX_HOME. | `hooks/tezgah_orca.py::summary`, `bin/tezgah-setup::main` |
+| Codex hooks | tezgah drops only entries holding `tezgah` and appends its own groups, so Orca's entries stay | `bin/tezgah-setup::install_codex` |
+| Cursor hooks | the same merge | `bin/tezgah-setup::install_cursor` |
+| Claude status line | tezgah's wrapper runs Orca's `~/.orca/agent-hooks/claude-statusline.sh` first and appends its own segment | `statusline.py::ORCA`, `bin/tezgah-setup::wire_claude_statusline` |
+| Codex rules file | Orca links the account home's `AGENTS.md` to `~/.codex/AGENTS.md`. tezgah writes the managed block through that link with a plain `open`, so the link stays. | `bin/tezgah-setup::set_managed_md` |
+
+### The collision this fixes
+
+On 2026-10-07 the tezgah repository had eleven git checkouts and Orca listed
+one. `git worktree list` printed the main checkout and ten under
+`~/Projects/tezgah-wt/`, and `orca worktree list --repo path:<main> --json`
+returned `totalCount: 1`. The ten came from raw `git worktree add`, so Orca
+showed no card, terminal or agent state for them. `tezgah-status --orca` now
+prints that gap.
+
+A smoke run on the live runtime closed the loop. It ran `orca worktree create
+--name tezgah-orca-smoke --parent-worktree active --setup skip --json` from the
+main checkout. `tezgah-status --orca --json` then listed the new checkout as
+tracked, with one terminal. `orca worktree rm --force` removed it, its branch
+included.
+
+### CODEX_HOME inside Orca
+
+Inside Orca, CODEX_HOME names an Orca-managed account home. A `tezgah-setup
+--install` run from an Orca terminal arms that home, and a run from another
+terminal arms `~/.codex` (`hooks/tezgah_paths.py::HOST_DIRS`). On this machine
+both homes carry tezgah's seven hook events. The Orca home keeps
+Orca's own entries beside them. Orca also keeps
+`.orca-hook-trust-provenance.json` there, keyed by event and entry index.
+tezgah appends after Orca's entries, so Orca's index does not move. Whether
+Orca re-trusts a changed tezgah entry on its own is not verified.
+
+## What the Orca CLI does not offer
+
+- No command adopts an existing raw git worktree as an Orca worktree. The
+  `Worktrees` section of `orca --help` lists `list`, `show`, `current`,
+  `create`, `set`, `rm` and `ps` only. `orca repo set --repo <sel>
+  --external-worktree-visibility show` makes non-Orca worktrees visible in the
+  sidebar. It does not give them cards.
+- An agent cannot turn on artifact publishing. A human enables it in Settings
+  (the `Artifacts` section of `orca skills get orca-cli`).
+
+## Tests
+
+`tests/test_orca.py` runs with no real Orca. A fake `orca` on disk answers
+`worktree ps` and `status`, and every marker is a fixture. `tests/support.py`
+strips the developer's own `ORCA_*` markers and `TERM_PROGRAM=Orca`, and pins
+`TEZGAH_ORCA_BIN` to a missing path. Without that, a suite run inside Orca
+would reach the live runtime.
+
+## Source of truth
+
+- `hooks/tezgah_orca.py`: detection, CLI resolution, the listing and both report lines
+- `hooks/tezgah_context.py`: where the session line joins the session-start block
+- `hooks/tezgah_policy.py`, `skills/tezgah-contract/SKILL.md`, `hooks/tezgah_agents.py`: the slice rule
+- `bin/tezgah-status`, `bin/tezgah-setup`: the two report surfaces
+- `tests/test_orca.py`, `tests/support.py`

package/docs/research.md

@@ -65,7 +65,7 @@ nothing recorded the ask and `close --limit` accepted any string.
 `state.json` `rules` is the line's format version. `init` writes `RULES`, the
 newest set (`hooks/tezgah_research.py::RULES`). Each set keeps its own gate. Rules 2
 are the standards rules. Rules 3 add the ask contract. Rules 4 add the protocol
-sections below. A bump never weakens an older set.
+sections below. Rules 5 add the scope lock. A bump never weakens an older set.
 
 A `rules` above `RULES` means a later tezgah wrote the line. `check` then reports
 one error that names both numbers and reads nothing else. The writers refuse the
@@ -110,14 +110,49 @@ it. The rules come from the gortex/SoL-Pi adoption's ideas 3 and 4 and from the
 layer audit's P2 probe (`_check_protocol_sections`, `_token_claim_problem`).
 Older lines keep the word rule.
 
+## Scope lock (rules 5)
+
+The owner reported on 2026-10-07 that research turned every question into
+metrics. It also grew past the ask, stayed shallow, and drifted off topic. The
+rule text pushed each of these. The injected rule sent every research task to
+orx's experiment tree. The skill locked a metric at bootstrap. `check` refused a
+line past `bootstrap` without one. An analysis owed three compared variants. The
+ideation moves had no fence. Rules 5 lock a line to its question:
+
+- `init --in "<covered>" --out "<left alone>"` (repeatable) write `state.json`
+  `scope`. The in-scope items are `S1`, `S2`, ... in order. `--method
+  qualitative|measured` writes `method`. `scope_problems`
+  (`hooks/tezgah_research.py::scope_problems`) names an empty `scope.in`, an
+  empty `scope.out` and a missing method. `check` refuses them past `bootstrap`
+  and warns at it.
+- A claim's `trace` names the in-scope item it answers (`S<n>` or the item's
+  text). `claim_problems` and `_check_claims` both call `trace_problem`
+  (`hooks/tezgah_research.py::trace_problem`). The writer and the checker refuse
+  the same off-topic claim.
+- A `qualitative` line owes no metric. `_check_evaluation`
+  (`hooks/tezgah_research.py::_check_evaluation`) skips it. `_check_scope`
+  refuses one that records `results.jsonl`. A measured question says `measured`
+  and locks its evaluation first.
+- An `analysis` deliverable owes no variants (`deliverable_problems` takes the
+  line's rules). A design, plan or code still does. Older lines keep three.
+
+The session reads the same lock in the research rule
+(`hooks/tezgah_policy.py::RESEARCH` and the paragraph `**Research: route it to
+OpenResearch.**`). Restate the question verbatim. Name what is in and out of
+scope. Drop a finding that answers nothing asked. Pick the method from the
+question. Answer a plain factual question in the reply from primary sources, with
+no line. Cite each finding's source with a confidence. The host-subagent fallback
+gets the question, its scope and its method in its brief. The research skill's
+"Scope and method" section is the long form.
+
 ## One line, one directory
 
 | Path | Holds |
 |---|---|
-| `state.json` | the question, the phase (`bootstrap`/`inner`/`outer`/`concluded`), the direction, the locked evaluation and its optional second gate (`capability_tolerance`, `counter_metric`), the session events (`PHASES`, `hooks/tezgah_research.py::PHASES`), `rules` (the rule set `init` opened it under, `RULES`), `deliverable` (`kind`, `path`, `ask`, `min_variants`), `supersedes` for a new version of an older line, and `closed` once `close` records a deliberate limit. The phase is the author's declaration; `derived_phase` (`hooks/tezgah_research.py::derived_phase`) reads the *other* authority beside it from the line's own artifacts, and the checker names the two disagreeing |
+| `state.json` | the question, the phase (`bootstrap`/`inner`/`outer`/`concluded`), the direction, `method` and `scope` (rules 5, see "Scope lock"), the locked evaluation and its optional second gate (`capability_tolerance`, `counter_metric`), the session events (`PHASES`, `hooks/tezgah_research.py::PHASES`), `rules` (the rule set `init` opened it under, `RULES`), `deliverable` (`kind`, `path`, `ask`, `min_variants`), `supersedes` for a new version of an older line, and `closed` once `close` records a deliberate limit. The phase is the author's declaration; `derived_phase` (`hooks/tezgah_research.py::derived_phase`) reads the *other* authority beside it from the line's own artifacts, and the checker names the two disagreeing |
 | `log.md` | the decision log, newest last: one line per decision, experiment, dead end or pivot, with the evidence that drove it |
 | `findings.md` | the four sections every line answers, named by `FINDINGS_SECTIONS` (`hooks/tezgah_research.py::FINDINGS_SECTIONS`) |
-| `claims.jsonl` | one JSON object per row: `statement`, `falsification`, `proof`, `provenance`, `status`, `kind`, `scope` (what the claim's numbers were measured on, which may not be wider than the rows it rests on), and `supersedes` when the row replaces an earlier claim |
+| `claims.jsonl` | one JSON object per row: `statement`, `falsification`, `proof`, `provenance`, `status`, `kind`, `trace` (the in-scope item, rules 5), `scope` (what the claim's numbers were measured on, which may not be wider than the rows it rests on), and `supersedes` when the row replaces an earlier claim |
 | `predictions.jsonl` | one JSON object per row: `commit` (a 40-character sha the row is bound to), `claim` (an id the line holds, or empty when the prediction stands alone), `metric`, `value_before`, `value_after`, `falsifier`, `components` (the keys of the components the change touches, read from `hooks/tezgah_components.py`), and `granted_by` when a human granted what the frozen paths below forbid |
 | `experiments/<hypothesis>/protocol.md` | what the change is, what it predicts, what result would falsify it, why - committed before the run |
 | `experiments/<hypothesis>/results.jsonl` | the rows the run produced, one JSON object per non-blank line, each carrying a non-empty `source` and, once declared, a `scope` of `real`, `fixture` or `derived`, and - when that scope is `fixture` - a `fixture` description of what was generated |