@sabaiway/agent-workflow-kit 14.19.1 → 14.21.0

package/bridges/codex-cli-bridge/references/driving-codex.md

@@ -18,26 +18,29 @@ judgment.
 4. Let codex run; then **review its diff yourself** and re-run the project's gates.
 5. **Commit yourself** — codex never commits (a git-write shim enforces it; see below).
 
-## Quality-first: model & effort are pinned
-
-Delegated codex work ALWAYS runs on the PINNED model at the pinned effort: `gpt-6-astra` / `high` are **pinned**
-and a non-default `CODEX_MODEL`/`CODEX_EFFORT` is **refused** (exit 2). That the pinned id is still the
-strongest selectable model is a hand-checked claim with no automated gate and no recorded date — see
-SKILL.md. Do not try to "tune down" the
-model or effort for a real run — the wrapper will stop you. Quota is metered in **messages** (rolling
-5h + weekly), so economy comes from removing waste (clean capture, the precomputed review diff, resume),
-never from a downgrade. The only opt-out is a throwaway, effort-independent probe: `CODEX_PROBE=1`
-(loud) — never use its output as real work.
+## Model & effort: the host posture
+
+Delegated codex work runs on the host posture: `CODEX_MODEL` / `CODEX_EFFORT` from the bridge settings
+file, else the built-in default `gpt-6.1-sol` / `high`, checked against the installed CLI's catalog
+before any spend. `/agent-workflow-kit bridge-settings` shows the models the installed codex offers and
+sets the host posture. An environment value off the host posture is a one-off and is **refused** (exit 2)
+with the settings-file remedy unless `CODEX_PROBE=1` — do not "tune down" the model or effort per call;
+a weaker model is the user's choice in the setting. Whether the default is the strongest selectable
+model is a hand-checked claim with no automated gate and no recorded date — see SKILL.md. Quota is
+metered in **messages** (rolling 5h + weekly), so economy comes from removing waste (clean capture, the
+precomputed review diff, resume), never from a per-call downgrade. A probe (`CODEX_PROBE=1`, loud) is
+the one route to a one-off — never use its output as real work; its review receipt never attests.
 
 ## Posture banners — quote them verbatim
 
 Every dispatch states its ACTUAL posture on ONE stderr line: `codex-exec` emits
-`exec posture: model=… effort=… tier=… sandbox=workspace-write session=fresh|resume:<id> timeout=…`
+`exec posture: model=… effort=… tier=… sandbox=workspace-write session=fresh|resume:<id> source=… timeout=…`
 (fresh and resume alike, only after the resume id is resolved and validated), `codex-review` emits
-`review posture: model=… effort=… tier=… timeout=…`. When you label a dispatch for a user or a
+`review posture: model=… effort=… tier=… source=… timeout=…`. When you label a dispatch for a user or a
 record, **quote the posture banner verbatim** — the banner is the machine-stated posture; a prose
-re-type drifts. The `timeout=` field is **banner-only** (exactly the duration handed to
-`timeout(1)`; on exec `uncapped` when no capping binary is on PATH, while `codex-review` fails
+re-type drifts. The `source=` field (`model:<s>,effort:<s>`, each `default`, `setting` or
+`environment`) and the `timeout=` field are **banner-only** (`timeout=` is exactly the duration handed
+to `timeout(1)`; on exec `uncapped` when no capping binary is on PATH, while `codex-review` fails
 CLOSED pre-spend there) — informational, never part of a receipt or the banner↔receipt parity.
 
 ## Exec vs review
@@ -92,7 +95,7 @@ codex-exec --resume <session-id> <file|->  # explicit session id
 
 Resume continues the SAME codex session, so you avoid re-sending the original context. It runs through
 the wrapper, which **re-establishes every invariant** (subscription-only `*_API_KEY` scrub,
-`--ignore-user-config`, the pinned `gpt-6-astra`/`high`) and **restates the full posture via `-c`** —
+`--ignore-user-config`, the host posture's model/effort) and **restates the full posture via `-c`** —
 because `codex exec resume` resets the sandbox/approval/network posture and rejects `-s`/`--add-dir`/`-C`,
 the wrapper passes `-c sandbox_mode=workspace-write -c approval_policy=never -c
 sandbox_workspace_write.network_access=false` explicitly. A resume takes no passthrough flags and an

package/bridges/codex-cli-bridge/references/sandbox-and-flags.md

@@ -47,7 +47,7 @@ carries the session id) into the run trace, with stderr merged into it; `--color
 `--color`, which stays on the fresh lane), so the resume lane is no longer the odd one out: it used
 to print its final message straight to stdout with the event stream nowhere, which left the very
 mode a nested-sandbox incident fired on without a structured evidence surface. Net effect: the wrapper prints just the final answer. **Reasoning still runs at
-the pinned effort** — quality is unchanged; only the *noise* is dropped. On success `codex-exec` extracts the
+the run's effort** — quality is unchanged; only the *noise* is dropped. On success `codex-exec` extracts the
 session id from the trace and records it to `${CODEX_SESSION_FILE:-./.codex-last-session}` (so
 `--resume-last` can find it) and echoes `session: <id>` to stderr. On a missing/empty final-message
 file it falls back to the trace tail (loud, never silent).
@@ -61,13 +61,16 @@ well-formed item is simply not evidence, never a parse error. See the dual polic
 its loose whole-trace rule, and the successful-run arm demands both tokens inside ONE item whose
 failure is proven.
 
-## Quality-first guard (pinned model & effort)
+## Host posture (model & effort)
 
-The wrappers default `CODEX_MODEL=gpt-6-astra` and `CODEX_EFFORT=high` and **refuse** (exit 2, loud) any
-non-default — delegated work always uses the PINNED model at the pinned effort; quality is never traded for
-quota. (Whether the pinned id is still the strongest selectable model is a hand-checked claim with no
-automated gate — see SKILL.md.) `CODEX_PROBE=1` relaxes this for a throwaway, effort-independent probe only (echoed loudly), and
-a probe still runs on the subscription, in the sandbox, with clean capture.
+The wrappers run on the host posture: `CODEX_MODEL` / `CODEX_EFFORT` from the bridge settings file, else
+the built-in default `gpt-6.1-sol` / `high`, checked pre-spend against the installed CLI's catalog
+(`codex debug models`); `/agent-workflow-kit bridge-settings` shows the models offered and sets one. A model or effort the catalog does not offer, and an environment value off the
+host posture (a one-off), are **refused** (exit 2, loud) with the settings-file remedy; a weaker model
+is the user's choice in the setting, never a per-call downgrade. (Whether the default is the strongest
+selectable model is a hand-checked claim with no automated gate — see SKILL.md.) `CODEX_PROBE=1` is the
+one route to a one-off, for a throwaway probe only (echoed loudly; a nonced `codex-exec` probe one-off
+is refused), and a probe still runs on the subscription, in the sandbox, with clean capture.
 
 ## Passthrough guard (two tiers, after a literal `--`)
 
@@ -75,7 +78,7 @@ a probe still runs on the subscription, in the sandbox, with clean capture.
 
 - **Tier 1 — ALWAYS rejected, even under `CODEX_PROBE=1`:** anything that would defeat the policy or the
   capture — `-c`/`--config`, `-s`/`--sandbox`, `--full-auto`, `--dangerously-bypass-*`, `--oss`,
-  `--local-provider`, `-p`/`--profile`, `-m`/`--model` (the model is pinned via `CODEX_MODEL`), and the
+  `--local-provider`, `-p`/`--profile`, `-m`/`--model` (the model is the host posture or `CODEX_MODEL`), and the
   capture flags `-o`/`--output-last-message`/`--json`/`--color`/`--output-schema`/`--ephemeral`.
 - **Tier 2 — context/discovery knobs, rejected for a real run but allowed under `CODEX_PROBE=1`:**
   `--add-dir`, `-C`/`--cd`, `--skip-git-repo-check`, `--ignore-rules`, `--enable`/`--disable`.
@@ -155,7 +158,7 @@ run starts, so the failure is loud and costs no quota; the wrapper's own test pi
 (`RESUME_ACCEPTED_FLAGS`) precisely because the hermetic fake CLI accepts any argv and cannot answer
 this question. The `codex-exec --resume`/`--resume-last` entrypoint handles the reset: it restates
 the entire policy via `-c` (`sandbox_mode=workspace-write`, `approval_policy=never`,
-`sandbox_workspace_write.network_access=false`) plus the pinned `-m`/effort and
+`sandbox_workspace_write.network_access=false`) plus the host posture's `-m`/effort and
 `--ignore-user-config`, reads the session id from the sidecar (or an argument), and applies the same
 EVIDENCE posture as a fresh run — `-o` for the final message, `--json` into the trace. Only a *raw*
 `codex exec resume` outside the wrapper loses the posture.
@@ -164,7 +167,7 @@ EVIDENCE posture as a fresh run — `-o` for the final message, `--json` into th
 
 A backgrounded/hung run survives otherwise, so both wrappers wrap codex in `timeout`/`gtimeout`
 (`--kill-after=15s`): `CODEX_HARD_TIMEOUT` defaults to **3600s (exec)** / **1800s (review)**, sized for a
-slow run at the pinned effort. Exit 124/137 ⇒ "exceeded the hard cap" (raise the cap or narrow the task). If neither
+slow run at the host posture's effort. Exit 124/137 ⇒ "exceeded the hard cap" (raise the cap or narrow the task). If neither
 `timeout` nor `gtimeout` is on `PATH`, `codex-exec` **warns loudly and runs uncapped** — never a silent
 no-op — while `codex-review` **refuses pre-spend** (the fail-closed hard-timeout preflight).
 
@@ -205,8 +208,9 @@ exec` over the precomputed diff instead, keeping every invariant intact.
 | `-o, --output-last-message <f>` | write ONLY the final message (clean capture) |
 | `--json` | structured event stream (`thread.started` ⇒ session id) |
 | `--output-schema <f>` | constrain output to a JSON schema (`CODEX_REVIEW_SCHEMA=1`) |
-| `-m <model>` | model (wrapper default `gpt-6-astra`, pinned via `CODEX_MODEL`) |
-| `-c model_reasoning_effort=<effort>` | reasoning effort (wrapper default `high`, pinned via `CODEX_EFFORT`) |
+| `-m <model>` | model (the host posture: the `CODEX_MODEL` setting, else `gpt-6.1-sol`) |
+| `-c model_reasoning_effort=<effort>` | reasoning effort (the host posture: the `CODEX_EFFORT` setting, else `high`) |
+| `codex debug models` | the model catalog as JSON `models[]` (`slug`, `visibility`, `priority`, `supported_reasoning_levels`, `default_reasoning_level`) — the wrappers' pre-spend check; reads no stdin (probed on 0.160.0) |
 | `--ignore-user-config` | do NOT load `$CODEX_HOME/config.toml`; auth still uses `CODEX_HOME` |
 | `--color never` | disable ANSI colour in output |
 

package/bridges/codex-cli-bridge/setup/README.md

@@ -70,9 +70,9 @@ if it reports a missing git work tree or root `AGENTS.md`, run it from a project
 
 - The wrappers are **subscription-only** by design and will not use api-key billing.
 - `codex-exec` runs a **workspace-write** sandbox with **network OFF**; `codex-review` runs
-  **read-only**. They also pin the model/effort (refusing ANY non-pinned model or effort, a stronger
-  one included; whether the pinned id is still the strongest selectable model is a hand-checked claim
-  with no gate — see `../SKILL.md`), enforce a hard
+  **read-only**. They also run on the host posture — `CODEX_MODEL` / `CODEX_EFFORT` from the
+  bridge settings file, else `gpt-6.1-sol` / `high` — checked against the installed CLI's catalog,
+  and refuse a one-off model or effort unless `CODEX_PROBE=1` (see `../SKILL.md`), enforce a hard
   timeout, capture only codex's final message, and block codex from writing git via a shim — see
   [`../references/sandbox-and-flags.md`](../references/sandbox-and-flags.md) and the knob table in
   [`../SKILL.md`](../SKILL.md#environment-knobs). No setup is needed to enable these — they are on by

package/capability.json

@@ -3,7 +3,7 @@
   "schema": 1,
   "name": "agent-workflow-kit",
   "kind": "composition-root",
-  "version": "14.19.1",
+  "version": "14.21.0",
   "provides": [],
   "roles": {},
   "detect": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sabaiway/agent-workflow-kit",
-  "version": "14.19.1",
+  "version": "14.21.0",
   "description": "Portable, cross-agent memory & workflow for AI coding agents — Claude Code, Codex, Cursor, Devin Desktop. One command deploys an AGENTS.md entry point + docs/ai context with cap/archive/index enforcement into any repo.",
   "keywords": [
     "ai-agents",

package/references/modes/bridge-settings.md

@@ -4,11 +4,14 @@
 
 The reader + consent-gated **writer** for the **host-level** bridge settings file — the answer to *"turn on the codex Fast tier (or another bridge knob) once, predictably, so it survives kit upgrades."* The four bridge wrappers read `${XDG_CONFIG_HOME:-~/.config}/agent-workflow/bridge-settings.conf` (`KEY=VALUE` lines, **parsed never sourced**); this is the ONLY writer for it. The file lives **outside every kit-managed tree**, so a kit refresh never writes or clobbers it — upgrade-survival is structural (D2). It **previews by default**; `--apply` writes. Hand-editing the file stays fully supported — this is an offered convenience, never a lock.
 
-**The knobs are the bundled bridges' own `settings` blocks** (manifest-as-source, D6) — the tool never invents a key or a value rule, and what it writes always passes the wrappers' own validation. Model/effort are **NOT** settable here (the wrappers' quality-first guard is untouched, D4). Run **`node ${CLAUDE_SKILL_DIR}/tools/bridge-settings.mjs`** to see the live list; today:
+**The knobs are the bundled bridges' own `settings` blocks** (manifest-as-source, D6) — the tool never invents a key or a value rule, and what it writes always passes the wrappers' own validation. **The model keys set each bridge's host posture** — the model every run of that bridge uses (codex: and its effort); a set one is checked against the models the installed CLI offers **before anything is written**. Run **`/agent-workflow-kit bridge-settings`** (`node ${CLAUDE_SKILL_DIR}/tools/bridge-settings.mjs`) to see the live list and the models on offer; today:
 
 | key | bridge | values | note |
 |---|---|---|---|
-| `CODEX_SERVICE_TIER` | codex | `priority` | **SPEND KNOB** — the "Fast" tier: "2x speed, **increased usage**" in the codex catalog's own words for gpt-6-astra (cache fetched 2026-09-05); it states no credit-rate figure; quality-neutral (same model). Default unset ⇒ standard tier. |
+| `CODEX_MODEL` | codex | a model the installed codex offers | the host posture's model; default `gpt-6.1-sol`. |
+| `CODEX_EFFORT` | codex | an effort that model offers | the host posture's reasoning effort; default `high`. |
+| `AGY_MODEL` | agy | a display string the installed agy offers | the host posture's model; default `Gemini 3.8 Flash (High)`. |
+| `CODEX_SERVICE_TIER` | codex | `priority` | **SPEND KNOB** — the "Fast" tier: "2x speed, **increased usage**" in the codex catalog's own words for gpt-6.1-sol (cache fetched 2026-10-03); it states no credit-rate figure; quality-neutral (same model). Default unset ⇒ standard tier. |
 | `CODEX_HARD_TIMEOUT` | codex | integer `1..86400` | hard wall-clock cap (seconds) via `timeout(1)`. |
 | `CODEX_REVIEW_MAX_TOTAL_BYTES` | codex | integer `1..100000000` | codex-review payload size above which the diff rides a temp file (never truncated). |
 | `AGY_HARD_TIMEOUT` | agy | duration `5m`/`30m`/`90s` (unit required, nonzero) | hard wall-clock cap via `timeout(1)`. |
@@ -17,16 +20,16 @@ The reader + consent-gated **writer** for the **host-level** bridge settings fil
 
 **Invocations:**
 
-1. **Read** — `node ${CLAUDE_SKILL_DIR}/tools/bridge-settings.mjs [--json]` prints every knob's **effective value + source** (`env` / `file` / `default`) and flags any unknown/duplicate/malformed lines. Read-only.
+1. **Read** — `node ${CLAUDE_SKILL_DIR}/tools/bridge-settings.mjs [--json]` prints every knob's **effective value + source** (`env` / `file` / `default`; a model key's `environment` / `setting` / `default`, as the wrappers' banner names it), each bridge's host posture with the models its installed CLI offers (read with `codex debug models` / `agy models`, never a model run; an unreadable or missing CLI is one stated line, exit 0), and flags any unknown/duplicate/malformed lines. Read-only.
 2. **Preview a change** — `--set KEY=VALUE` (or `--unset KEY`) prints `before → after` and writes **nothing**. Re-run with **`--apply`** to write. Multiple `--set`/`--unset` ops apply in one atomic write.
 3. **`--apply`** writes via the hardened out-of-tree atomic writer (creates the dir + file on first use; symlink/parent/TOCTOU-safe; last-writer-wins). It touches **only** the `KEY=` line it owns — every comment / blank / other line is preserved verbatim.
 
-**Precedence at run time:** explicit env (even empty — `KEY=` disables the knob for one run) **>** this file **>** the wrapper's built-in default. So an operator can always override one run without editing the file; the reader shows which source wins.
+**Precedence at run time:** explicit env (even empty — `KEY=` disables the knob for one run) **>** this file **>** the wrapper's built-in default. So an operator can always override one run without editing the file; the reader shows which source wins. A model key is the exception: an environment value off the host posture is a one-off, which `codex-exec`, `codex-review` and `agy-review` refuse unless it is a probe (the bridge-model contract).
 
-**Refusals (the guarded contract):** an **unknown key** or an **invalid / out-of-range value** → exit `2` (nothing read of the file, nothing written). A file that already carries **duplicate keys** → exit `1`, named and left **byte-untouched** (fix the duplicates by hand first — the writer never edits blindly around them). A **symlinked / non-regular / unreadable** settings file → exit `1` (refuses to write through it). `--apply` with `--dry-run`, a duplicate op for one key, or a malformed `--set` → usage exit `2`.
+**Refusals (the guarded contract):** an **unknown key** or an **invalid / out-of-range value** (a model key: empty, padded with whitespace, or carrying a control byte) → exit `2` (nothing read of the file, nothing written). A **model the catalog does not offer**, or a codex **effort that model does not offer**, → exit `2` with the offered list, nothing written; an unreadable catalog leaves the value unchecked and says so. A file that already carries **duplicate keys** → exit `1`, named and left **byte-untouched** (fix the duplicates by hand first — the writer never edits blindly around them). A **symlinked / non-regular / unreadable** settings file → exit `1` (refuses to write through it). `--apply` with `--dry-run`, a duplicate op for one key, or a malformed `--set` → usage exit `2`.
 
-**Spend consent (D4):** enabling `CODEX_SERVICE_TIER=priority` costs **increased usage** (the catalog states no credit-rate figure) — a per-host, consented act, never a default. The preview shows the caveat (from the manifest `effect`); confirm with the user before `--apply`. The tool also warns when an env var currently shadows the key you are writing (the env value wins for that session until unset).
+**Spend consent (D4):** enabling `CODEX_SERVICE_TIER=priority` costs **increased usage** (the catalog states no credit-rate figure) — a per-host, consented act, never a default. The preview shows the caveat (from the manifest `effect`); confirm with the user before `--apply`. The tool also warns when an env var currently shadows the key you are writing (the env value wins for that session until unset; for a model key, an environment value off the host posture is a one-off, which `codex-exec`, `codex-review` and `agy-review` refuse unless it is a probe).
 
 Output is **English/structured** — **localize it to the user's conversational language** when you narrate.
 
-**Invariants:** writer (writes only the host settings file — outside any project/kit tree) · never commits · never runs a subscription CLI · previews by default · allowlist + value rules from the bundled manifests · model/effort never settable · the host file survives every kit refresh.
+**Invariants:** writer (writes only the host settings file — outside any project/kit tree) · never commits · never runs a model (only the two read-only catalog commands) · previews by default · allowlist + value rules from the bundled manifests · a model key is judged against its bridge's catalog before any write · the host file survives every kit refresh.

package/references/modes/jev.md

@@ -1,14 +1,15 @@
 ### Mode: jev
 
 <!-- opt-in-capability: jev-connect -->
+<!-- opt-in-capability: jev-skill -->
 
-Read-only. The Jev guide: what Jev (TypeSafe) is, why it pays in this workflow, what it is not, the two steps to a set key and three prompts where it pays. The guide writes no file, opens no connection, never prints the key's value and never commits.
+Read-only. The Jev guide: what Jev (TypeSafe) is, why it pays in this workflow, what it is not, the two steps — a set key and the vendor skill installed by the kit, pinned — and three prompts where it pays. The guide writes no file, opens no connection, never prints the key's value and never commits.
 
 Run `node ${CLAUDE_SKILL_DIR}/tools/jev-guide.mjs --dir <project> --json`.
 
 Render the returned envelope compactly in the user's conversational language. Never paste the JSON. Keep every path and every command verbatim, each command on its own line so it runs as printed; translate only the prose around them. Keep the one vendor-quoted text verbatim and in quotes, never translated or reflowed: the not-a-replacement sentence. The `Run it in <place>:` line, when the guide printed one, stays directly before the connect line and is never folded into it; the restart step is relayed whole.
 
-The connect line is the user's: hand it over as printed and never run it — the command refuses without a terminal, and a terminal is not consent. The install lines are the user's too: they change the agent's own configuration outside the project. No command the guide prints is run by the agent.
+The connect line and the skill's apply line are the user's: hand each over as printed and never run it — the connect command refuses without a terminal, and a terminal is not consent for either. Only when the user asks to see the plan, run the skill command without `--apply` yourself: a read-only dry run that writes nothing. The vendor's install lines are the user's too: they change the agent's own configuration outside the project. No command the guide prints is run by the agent.
 
 Keep this order: the fixed text (WHAT, WHY HERE, NOT, SOURCES); then the two steps — the key with its connect line and its mark, the vendor skill with its install lines, its mark and its first prompt; then the three prompts where it pays.
 

package/references/modes/recipes.md

@@ -12,7 +12,7 @@ The five recipes (defined over each bridge's `provides` roles — `codex`: execu
 - **Delegated** — you hand a **bounded** execution sub-task to a backend (`codex exec`), then review the returned diff and commit.
 - **Subagent** — a **full-tool frontier subagent**, dispatched from the placed executor vehicle (`.claude/agents/executor.md`), carries a **bounded, file-disjoint** slice — of execution, of plan/contract authoring, of an authoring fold, of routine work, of an epic brief (`epic.author`), of a task brief from one ledger row (`task.author`), or of one stamped task brief run inside its Files (`task.execute`); you verify the returned slice by running its suites yourself and you make the commit. It is **never a review backend**, **never a bridge substitute**, and is **never told to commit**; it **degrades to Solo** when the vehicle is `missing` or `unusable`, with the reason. Readiness here is the **vehicle FILE, never the host** — a **Claude Code lane**, like the `agents` writer itself: on a host that cannot dispatch the vehicle, the rendered dispatch form is an instruction you follow by hand and report as such, never as a subagent dispatch.
 
-1. Run **`node ${CLAUDE_SKILL_DIR}/tools/recipes.mjs`** (the read-only planner; `--json` for the structured form). It runs the backend detector, lists the five recipes, and prints — for the current environment — a **per-recipe dispatch plan that degrades with a stated reason** when a carrier isn't `ready` (Council → Reviewed → Solo; Delegated → Solo; Subagent → Solo when the executor vehicle is `missing`/`unusable`), plus advisory **quota/health notes** (prefer the cheapest model; Council spends two backends' quota; `agy` may stall on substantive prompts — Issue-001, prefer `codex`).
+1. Run **`node ${CLAUDE_SKILL_DIR}/tools/recipes.mjs`** (the read-only planner; `--json` for the structured form). It runs the backend detector, lists the five recipes, and prints — for the current environment — a **per-recipe dispatch plan that degrades with a stated reason** when a carrier isn't `ready` (Council → Reviewed → Solo; Delegated → Solo; Subagent → Solo when the executor vehicle is `missing`/`unusable`), plus advisory **quota/health notes** (each bridge runs the host posture the user set — a weaker model is the user's bridge setting, never a per-call choice; Council spends two backends' quota; `agy` may stall on substantive prompts — Issue-001, prefer `codex`).
 2. **Offer the choice** via **`AskUserQuestion` where your agent supports it** (`AskUserQuestion` in Claude Code) — one option per recipe, the `recommendRecipe` choice listed **first** — otherwise in prose. Then print `planRecipe(chosen, detection)` (the per-stage dispatch + degradation reasons + quota/health notes) so the user sees exactly what running it entails.
 3. **Availability = `readiness === ready`, full stop.** Every other readiness supplies the human reason (needs-skill → "not installed — `/agent-workflow-kit setup`"; needs-cli → "install the CLI"; needs-credentials → "log in"; degraded → "wrapper not on PATH — `/agent-workflow-kit setup`"). This is set-up state only — **never** a claim that a backend's service is responsive (the detector cannot observe a runtime stall; `agy`'s Issue-001 is a *standing advisory*, not a readiness signal).
 

package/references/modes/recommendations.md

@@ -4,7 +4,7 @@
 
 Requires: ${CLAUDE_SKILL_DIR}/references/shared/report-footer.md
 
-The **read-only deployment advisor** — the deterministic section every `upgrade` run ends with, also invocable on its own. It computes what in THIS deployment is configured sub-optimally (allowlist not seeded, autonomy render drifted, sandbox unavailable, gates undeclared, a declared gate matrix that verifies nothing, bridge friction, sandbox-mask clutter, an unacknowledged sandbox recipe, a configured `subagent` carrier whose executor vehicle cannot carry it, a difference from the reference profile the project has not declined, Jev not connected on this host) and renders **verdict-first**: one composed verdict line, then each item as **{severity · what is sub-optimal · the benefit in ONE plain line · an optional `recipe:` line (the `sandbox-lane` live recipe — egress hosts + resolved writable dirs — the `worktrees-dir` hand-apply-first grant advice, or the `agents` / `executor-vehicle` hidden-mode reconcile follow-up) · the exact consent-gated apply one-liner}**. The tool computes deterministic English DATA; **you PRESENT the section in the user's conversational language** — every fact, count and item from the tool, nothing added or dropped; commands, paths, hosts and rule strings stay **byte-exact**; show the raw tool block on request (the AD-032 report-contract lane — the tool cannot know the dialogue language, so the language rendering is your presentation layer).
+The **read-only deployment advisor** — the deterministic section every `upgrade` run ends with, also invocable on its own. It computes what in THIS deployment is configured sub-optimally (allowlist not seeded, autonomy render drifted, sandbox unavailable, gates undeclared, a declared gate matrix that verifies nothing, bridge friction, sandbox-mask clutter, an unacknowledged sandbox recipe, a configured `subagent` carrier whose executor vehicle cannot carry it, a difference from the reference profile the project has not declined, Jev not connected on this host, the Jev skill not installed for every agent) and renders **verdict-first**: one composed verdict line, then each item as **{severity · what is sub-optimal · the benefit in ONE plain line · an optional `recipe:` line (the `sandbox-lane` live recipe — egress hosts + resolved writable dirs — the `worktrees-dir` hand-apply-first grant advice, or the `agents` / `executor-vehicle` hidden-mode reconcile follow-up) · the exact consent-gated apply one-liner}**. The tool computes deterministic English DATA; **you PRESENT the section in the user's conversational language** — every fact, count and item from the tool, nothing added or dropped; commands, paths, hosts and rule strings stay **byte-exact**; show the raw tool block on request (the AD-032 report-contract lane — the tool cannot know the dialogue language, so the language rendering is your presentation layer).
 
 **Live host/session facts are tool-composed only.** Every fact this section states about the current
 host or session — prompts fired, sandbox scope, whether a bypass was needed, network reachability,
@@ -39,6 +39,7 @@ Run `node ${CLAUDE_SKILL_DIR}/tools/recommendations.mjs --cwd <project-root> [--
 - `spec-adoption` — the feature-spec layer's ADOPTION STATE, judged from `docs/ai/specs/` alone through the same census `spec-check --all` runs, so a store the checker would refuse to observe is never counted here either. Both arms are OFFERS (`optional`) — the layer is opt-in, and `attention` stays reserved for a configured declaration that is broken. **`not-adopted`** (no store): every plan then cites zero governing specs by default and nothing says adoption never started; its apply is the spec-layer ensure one-liner (`ensure-configs --reconcile --only specs`, the same seed `upgrade` runs — it writes the reader/checker pairs and the store root, create-only, and skips with a stated reason where no Node evidence exists), and its `recipe:` line carries a NAMED **HAND-APPLY alternative** — the DECLINE preview (`ack-write --lane spec-adoption`, a dry-run that prints the exact `--apply`), which records `specAdoptionAck` in the family-owned `docs/ai/acks.json`. **The two are exclusive, and the order is part of the contract:** ask which the maintainer wants BEFORE the confirmation; on "seed" run the apply; on "decline" run NOTHING — hand over the preview line and let them run it and its printed `--apply`; never run the seed after a decline was chosen, and never run the decline preview for them. **`adopting`** (a store with no live contract): an optional item naming the draft count; its apply is that same decline preview (a dry-run; after the SAME confirmation you run the `--apply` it prints), and the honest remedy is authoring a contract from the skill's `SPEC_TEMPLATE.md`. A recorded decline silences BOTH arms and shows on `status` as ` — declined`; one live contract makes the decline moot. An unreadable store is a stated skip, never `flow optimal`. Risk profile: the seed writes only create-only files under `scripts/` and `docs/ai/specs/`; the decline writes one key into the ack store; nothing here authors a spec or blocks a plan.
 - `profile-gap` — each item's apply is a PREVIEW that writes nothing, and consent takes two steps: the confirmed pick runs the preview and you relay every line it prints (the environment-resolved slot values, each checker `entry:` line with its trust-chain disclosure, a Communication region the insert plans in the same run); the same line with ` --apply` appended runs only on a SECOND yes over those lines, never carried by the first. Items whose apply lines are byte-equal are one writer and take one answer: the tier preview's `--apply` writes the absent slots, the store seed and the queue seed together; the checker verb writes only its own entries; the insert writes every region it plans, all or nothing, so a `communication-absent` skip beside a declined `story-sessions-section` gets its own ask after the insert's full preview. A no records nothing and the item stays on the screen. A DECLINE is asked apart from later, before anything runs, and runs `node ${CLAUDE_SKILL_DIR}/tools/tier-preview.mjs --decline --cwd <project-root>` only when the user refuses EVERY item the tier preview then reports offered: it records each of them at the shipped lineage, and a declined item leaves the screen until a lineage step changes the profile. An undecidable entry is a stated skip naming its reason, the remedy by reason: a prior → the upgrade's `lens` reconcile; an absent region → the insert; a customized region → a hand edit only (the lens preserves it), so that skip stands and withholds `flow optimal`. Risk profile: the tier preview's `--apply` rewrites `docs/ai/orchestration.json` in canonical form with the `_README` note and creates `docs/ai/epics/.gitkeep` and `docs/plans/queue.md` create-only; the insert adds regions to `docs/ai/agent_rules.md`; the checker verb adds entries to the PRIVILEGED `docs/ai/gates.json`; the decline writes `docs/ai/profile-declines.json`; nothing here commits.
 - `jev-connect` — the apply is HAND-APPLY: the user runs the connect command in a terminal of their own, never the agent (the command refuses without a terminal, and a terminal is not consent); when the recipe line opens with `run the apply in <place>`, that place is the terminal to name. The command reads the key with no echo, makes one network call to api.typesafe.ai with the vendor's sample text only on the user's own run, and writes the key in plain text — as managed export lines in the shell's startup files (bash: ~/.bashrc and the login file, created as ~/.bash_profile when none exists; zsh: ~/.zshrc), as the kit's own file ~/.config/fish/conf.d/typesafe-api-key.fish for fish, or on Windows as the user environment variable TYPESAFE_API_KEY, stored in the Windows user environment; a process already running at the save can keep its old environment and hand it to what it starts — the guide's key mark confirms the agent sees it (a file is readable by any process running as that user, and by other local accounts when one is world-readable in a traversable home); the vendor keeps data under its processing agreement and offers zero retention only to enterprise accounts. The item reads the environment the agent's commands run in: a host setting that filters it shows the item while the key is set in the user's shell. The decline is the HAND-APPLY alternative on the recipe line, asked apart BEFORE the confirmation (the `spec-adoption` order): on "connect" hand over the apply line, on "decline" run nothing and hand over the recipe line; the decline is recorded per project as `jevConnectAck` in `docs/ai/acks.json`. Risk profile: a plain-text key in the user's startup files or the Windows user environment, written by a command the user runs; one network call from that run.
+- `jev-skill` — the apply is HAND-APPLY: the user runs the skill command in a terminal of their own, never the agent (a terminal is not consent); when the recipe line opens with `run the apply in <place>`, that place is the terminal to name. The skill is third-party text — the vendor's, MIT — that the kit ships pinned and installs as a verified copy into three agent skill roots: `~/.agents/skills`, the Claude Code skills dir (`CLAUDE_CONFIG_DIR` or `~/.claude`) and `~/.gemini/config/skills`. It is never updated silently: a copy at an earlier pin is replaced only by that command, and a foreign copy is left untouched and named on the recipe line. A copy the vendor's `skills` CLI wrote with the same bytes reads current, and a later pin move replaces it like a kit copy; a vendor plugin install is invisible to the file check, so the Claude Code root may read absent while the plugin serves it. Only when the user asks to see the plan does the agent run the command without `--apply` (a read-only dry run). The decline is the HAND-APPLY alternative on the recipe line, asked apart BEFORE the confirmation: on "install" hand over the apply line, on "decline" run nothing and hand over the recipe line; the decline is recorded per project as `jevSkillAck` in `docs/ai/acks.json`. Risk profile: third-party text written into the user's agent skill roots by a command the user runs; no network.
 - `adr-store-migration` — other items write project files too; what is unique here is that the crossing **overwrites and deletes files the project already has**: it replaces the deployed enforcement scripts in `scripts/` (the directional subset — only basenames the project already has; a locally-edited copy is snapshotted first, never silently clobbered) and, where a retired archive file exists, DELETES it once conservation has been proven. That is why it is **HAND-APPLY** and why the command shown in the apply slot is a **`--dry-run`** — it writes nothing and prints the whole plan. `--apply` is a SEPARATE step, run only after that plan has been shown and **fresh consent** obtained for it; the consent flow executes only the apply slot, so an item that needs consent AFTER its preview cannot use that lane at all. Every write is idempotent and the run is re-runnable to completion after any interruption, so a re-run repairs rather than double-applies. It never commits. Risk profile: overwrite + delete of existing project files, gated on a preview you have actually read.
 
 **Sandbox lanes (what to DO with the `sandbox-lane` recipe, per host class):**

package/references/modes/review-state.md

@@ -7,7 +7,7 @@ Read-only **review-receipt checker** (AD-038) — it makes *"reviewed ≠ shippe
 Run `node ${CLAUDE_SKILL_DIR}/tools/review-state.mjs [--check] [--json]`:
 
 1. Plain run → the human report: resolved recipe + source, plan-in-flight, tree fingerprint, the `held session: <id> — <n> fold(s) rode it` / `none` / substitution line when configured delegated execution arms it (with a task `code` thread of backend `codex` in the commit epoch and no unresolved substitution, `held sessions: <k> chain(s) — <label>: <id> (<n>) · …` is printed instead, one entry per chain, labelled by its brief or `untasked`, with `none` for a chain with no held session), and per-backend receipt state (current / stale / ungrounded / probe / rejected / missing) with verdict + grounding + timestamp.
-2. **`--check`** → the gate exit code. Before the review-recipe early return, a configured `plan-execution.execute` or `task.execute` of `delegated` (each read on its own) with a plan in flight and a dirty, fingerprintable tree audits the delegation ledger and refuses a substituted held session; an absent ledger is inert, while an unreadable, malformed, foreign, audit-refused ledger or failed HEAD read fails closed with its own reason. For a head-base thread, the accepted-replacement escape is a `codex-exec` degrade at the substituted return's tree, standing after every later fold, never the review receipt id `codex`. A checkpoint-based thread's substitution closes only by its own ledger `degrade` (which also withdraws the expectation, so the next fold establishes HELD) — no core-evidence degrade lifts it, and the report's recovery hint says so. The remaining **normative exit contract lives in the tool header** (the single home — do not re-enumerate it elsewhere): exit 0 for a CONFIGURED solo recipe (after the held-session arm above) (a computed readiness-degrade NEVER silently becomes solo — it needs the explicit degrade record below), no plan in flight (the `docs/plans` naming convention: `queue.md` and `EXECUTE-`/`FEEDBACK-`/`TASK-`-prefixed or `PROMPT`/`prompt`/`handoff`-carrying names are scratch), a clean tree, a cwd where git ITSELF answers not-a-repository under both discoveries (the ONLY non-work-tree location that passes — `error`, `redirected`, `no-work-tree` and `env-only` refuse by their state name once a receipt could be required), or every recipe-named backend SATISFIED for the current tree. **A clean-tree PASS under a NON-SOLO review obligation is never silent about a latent arm:** when a `reviewed` or `council` recipe is configured, it NAMES every plan in flight and states that this gate arms as soon as the tree is dirty — the condition is discoverable BEFORE it blocks, instead of surfacing at the worst moment (a pending commit, or the landing of a feature worktree when main first turns dirty). Nothing is announced under a configured `solo` recipe or a not-a-repository cwd, where the gate can never arm. **Satisfaction is ship-class-only on the LATEST NORMAL receipt (D3(b)):** per backend, the latest probe-free current-fingerprint receipt is selected FIRST and THEN verdict-checked — only the recognized ship-class vocabulary (`ship` / `ship with nits`) satisfies; a recognized NEGATIVE (`revise` / `rethink` / `rework`) is an authoritative VETO (an earlier ship never survives a later revise); an UNRECOGNIZED verdict (e.g. `unknown` from a dead run) fails CLOSED unconditionally — a later `unknown` never lets an earlier SHIP stand, and a fresh normal re-run supersedes it. **The ONLY review-backend escape is an explicit degrade RECORD** (`core-evidence.mjs degrade --backend <name> --reason "…"`, fingerprint-bound to the current tree) — and never all backends: ≥1 non-degraded ship-class receipt is required whenever ≥1 backend is configured; a malformed evidence store denies the escape fail-closed but never fails an independently-satisfied tree. Exit 1 otherwise — missing, **stale** (every edit the payload can see moves the fingerprint, and no more), ungrounded, vetoed, or unrecognized. Plan/diff receipts and continuations (`agy-review --continue`) are **informational-only**: after a fold, only a **fresh grounded re-run** (`codex-review code`; `agy-review code --facts @f`) restores green. **Probe receipts never attest either:** a `CODEX_PROBE=1` / `AGY_PROBE=1` review runs with the frontier-model/max-effort guard OFF, so the wrapper stamps `probe:true` and this checker excludes it — per receipt, so a real review at the same fingerprint still satisfies. **Silence is not a declaration:** a malformed *or* absent probe marker is rejected fail-closed and stated in the check line. Honest bound: receipts are **not authenticated** (a forger could write `probe:false` as easily as any other field) — like the rest of the receipt this is a self-discipline mechanism, not a security boundary.
+2. **`--check`** → the gate exit code. Before the review-recipe early return, a configured `plan-execution.execute` or `task.execute` of `delegated` (each read on its own) with a plan in flight and a dirty, fingerprintable tree audits the delegation ledger and refuses a substituted held session; an absent ledger is inert, while an unreadable, malformed, foreign, audit-refused ledger or failed HEAD read fails closed with its own reason. For a head-base thread, the accepted-replacement escape is a `codex-exec` degrade at the substituted return's tree, standing after every later fold, never the review receipt id `codex`. A checkpoint-based thread's substitution closes only by its own ledger `degrade` (which also withdraws the expectation, so the next fold establishes HELD) — no core-evidence degrade lifts it, and the report's recovery hint says so. The remaining **normative exit contract lives in the tool header** (the single home — do not re-enumerate it elsewhere): exit 0 for a CONFIGURED solo recipe (after the held-session arm above) (a computed readiness-degrade NEVER silently becomes solo — it needs the explicit degrade record below), no plan in flight (the `docs/plans` naming convention: `queue.md` and `EXECUTE-`/`FEEDBACK-`/`TASK-`-prefixed or `PROMPT`/`prompt`/`handoff`-carrying names are scratch), a clean tree, a cwd where git ITSELF answers not-a-repository under both discoveries (the ONLY non-work-tree location that passes — `error`, `redirected`, `no-work-tree` and `env-only` refuse by their state name once a receipt could be required), or every recipe-named backend SATISFIED for the current tree. **A clean-tree PASS under a NON-SOLO review obligation is never silent about a latent arm:** when a `reviewed` or `council` recipe is configured, it NAMES every plan in flight and states that this gate arms as soon as the tree is dirty — the condition is discoverable BEFORE it blocks, instead of surfacing at the worst moment (a pending commit, or the landing of a feature worktree when main first turns dirty). Nothing is announced under a configured `solo` recipe or a not-a-repository cwd, where the gate can never arm. **Satisfaction is ship-class-only on the LATEST NORMAL receipt (D3(b)):** per backend, the latest probe-free current-fingerprint receipt is selected FIRST and THEN verdict-checked — only the recognized ship-class vocabulary (`ship` / `ship with nits`) satisfies; a recognized NEGATIVE (`revise` / `rethink` / `rework`) is an authoritative VETO (an earlier ship never survives a later revise); an UNRECOGNIZED verdict (e.g. `unknown` from a dead run) fails CLOSED unconditionally — a later `unknown` never lets an earlier SHIP stand, and a fresh normal re-run supersedes it. **The ONLY review-backend escape is an explicit degrade RECORD** (`core-evidence.mjs degrade --backend <name> --reason "…"`, fingerprint-bound to the current tree) — and never all backends: ≥1 non-degraded ship-class receipt is required whenever ≥1 backend is configured; a malformed evidence store denies the escape fail-closed but never fails an independently-satisfied tree. Exit 1 otherwise — missing, **stale** (every edit the payload can see moves the fingerprint, and no more), ungrounded, vetoed, or unrecognized. Plan/diff receipts and continuations (`agy-review --continue`) are **informational-only**: after a fold, only a **fresh grounded re-run** (`codex-review code`; `agy-review code --facts @f`) restores green. **Probe receipts never attest either:** a `CODEX_PROBE=1` / `AGY_PROBE=1` review is the one route to a one-off model or effort, so the wrapper stamps `probe:true` and this checker excludes it — per receipt, so a real review at the same fingerprint still satisfies. **Silence is not a declaration:** a malformed *or* absent probe marker is rejected fail-closed and stated in the check line. Honest bound: receipts are **not authenticated** (a forger could write `probe:false` as easily as any other field) — like the rest of the receipt this is a self-discipline mechanism, not a security boundary.
 3. **Wire it as a gate by hand OR via the explicit-consent init preview — never without consent (AD-021/D9).** The candidate line for your own `docs/ai/gates.json`: `{ "id": "review-state", "title": "Review receipts current for the uncommitted tree", "cmd": "node <path-to-this-skill>/tools/review-state.mjs --check" }` — with the path your project actually reaches the kit by, QUOTED so a path with spaces survives, executable from the project root. The consent-gated gates-init preview — `node ${CLAUDE_SKILL_DIR}/tools/gates-init.mjs --cwd <project>` (dry-run: it prints the derived entries and writes NOTHING; `--apply --only review-state` writes exactly this one on your explicit yes) — offers exactly this entry, path resolved and quoted, ONLY when your `docs/ai/orchestration.json` declares `reviewed`/`council` on `plan-execution.review` (the slot this checker enforces). The full consent-fill contract is in `${CLAUDE_SKILL_DIR}/references/modes/gates.md`. Once declared, the opt-in `${CLAUDE_SKILL_DIR}/references/modes/hook.md` auto-approves it like any other declared gate — and `run-gates --final` requires this check among its canonical core gates.
 4. **`--await [--timeout <s>]`** (BUGFREE-3 / AD-049) → BLOCK until every recipe-named backend is SATISFIED for the current tree (i.e. until `--check` would PASS), or the bounded timeout elapses (a loud exit 1; default 900s). Run it after dispatching the review bridges to WAIT for their receipts to land instead of hand-polling a pid: the durable completion signal is the **receipt**, never a process event (a harness "completed" notification fires early; a bridge's output late-flushes). It inherits the `--check` decision whole — a backend with a current-tree degrade RECORD stops being waited on (the shared decideCheck), so you never hand-`--await` around a known degrade. A held-session refusal and an **AUTHORITATIVE veto terminate the wait loudly BEFORE the deadline**: neither can be moved by waiting; only the held-session retry/degrade lane or a fresh review can move its corresponding refusal. Still read-only (it re-reads the receipts + the evidence store); solo / no-plan / clean-tree resolve instantly. For waiting on **one dispatch's arrival** (never obligation satisfaction) use the receipt-arrival deadline runner, `${CLAUDE_SKILL_DIR}/references/modes/receipt-deadline.md`.
 

package/references/vendor/typesafe-ai/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 TypeSafe AI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/references/vendor/typesafe-ai/SKILL.md.pinned

@@ -0,0 +1,149 @@
+---
+name: typesafe-ai
+license: MIT
+description: >
+  Build AI-powered software with TypeSafe: small units of AI intelligence you
+  can use like programming primitives. Its System One models, including Jev,
+  turn natural language and application state into typed judgments and
+  probabilities that code can combine. Use when a feature needs programmable
+  common sense, when brainstorming what AI could make possible in an app, or
+  when an LLM prompt-and-parse step could become a structured decision.
+  Applications include routing, ranking, extraction, verification, and
+  interactive experiences; these are starting points, not the limits.
+  Read live docs and cookbooks to find useful patterns and discover new combinations.
+---
+
+# Build with TypeSafe
+
+TypeSafe makes units of AI intelligence usable like programming primitives: small
+judgments you can compose into larger capabilities. Its **System One models** return
+fast, focused judgments that software can consume directly. **Jev** is TypeSafe's
+flagship and first System One model. It understands natural language and returns
+typed answers and probabilities rather
+than generating text or reasoning explanations. Code owns the workflow; the model
+supplies programmable common sense where ordinary code needs semantic understanding.
+
+## Read the live docs
+
+**The live TypeSafe docs are the source of truth. Read them as part of the task.**
+This skill gives direction; the docs carry current concepts, prompting guidance,
+API contracts, SDK usage, models, limits, and worked examples.
+
+- Start with the [documentation index](https://docs.typesafe.ai/llms.txt) to discover
+  relevant pages and cookbooks. Use targeted reads rather than loading the entire site.
+- Mintlify serves Markdown by appending `.md` to a page path, for example
+  [how to build with TypeSafe](https://docs.typesafe.ai/concepts/how-to-build-with-system-one.md).
+  Follow links from the index; convert extensionless documentation page links to
+  `.md` when useful. Resolve relative links against `https://docs.typesafe.ai`.
+- Before writing an integration, read the current API or chosen SDK page and the
+  question guidance relevant to the design. For a new workflow, also inspect the
+  closest cookbook: it often shows a better decomposition than a generic classifier.
+- If the index is unavailable, use the direct links below or the site's navigation.
+  If Markdown fetching fails, try the normal page. If live access is unavailable,
+  use available local docs or installed SDK types, state that limitation, and avoid
+  inventing version-dependent details.
+
+| Task | Start here; follow the relevant details |
+| --- | --- |
+| Understand the programming model | [System One](https://docs.typesafe.ai/concepts/system-one.md), [building guide](https://docs.typesafe.ai/concepts/how-to-build-with-system-one.md) |
+| Explore what to build | [Use-case map](https://docs.typesafe.ai/concepts/use-case-map.md), then relevant cookbooks from the index |
+| Prepare inputs and questions | [State](https://docs.typesafe.ai/concepts/state.md), [primitives](https://docs.typesafe.ai/primitives.md), then the chosen primitive's page |
+| Decide how to handle uncertainty | [Confidence](https://docs.typesafe.ai/confidence.md) |
+| Write API code | [HTTP API](https://docs.typesafe.ai/api.md), [Python SDK](https://docs.typesafe.ai/sdk/python.md), or [JavaScript SDK](https://docs.typesafe.ai/sdk/javascript.md) |
+| Update an older integration | [Migration guide](https://docs.typesafe.ai/migrating-to-v1.md) and the installed SDK's current reference |
+
+## Find the useful shape
+
+Start from the behavior the user wants: what will the application show, select,
+change, or hand off? Work backward to the judgments it needs. Keep known rules,
+calculations, exact lookups, and execution in code. Preserve the user's chosen stack
+and scope; add TypeSafe where semantic understanding helps.
+
+When brainstorming or choosing an architecture, consider more than classification.
+The patterns below are starting points: combine primitives around the user's goal,
+including ideas that do not fit an established recipe.
+
+- **Route and fill known arguments.** A request can select a handler and its typed
+  parameters. Ask useful branch-specific questions up front and consume only the
+  relevant answers. Explore [function calling](https://docs.typesafe.ai/cookbooks/function_calling.md)
+  and [speculative fan-out](https://docs.typesafe.ai/patterns/fan-out.md).
+- **Select instead of generate.** Find candidate values or source spans in code,
+  use a judgment to select the intended one, then copy or normalize it. Code can
+  also assemble source text into a formatted document or reading guide. Explore
+  [value extraction](https://docs.typesafe.ai/cookbooks/pre_parsed_value_extraction_cookbook.md)
+  and [structure recovery](https://docs.typesafe.ai/cookbooks/autoformat.md).
+- **Find and judge evidence.** Retrieve candidates, compare their relevance to a
+  query, and select useful context. Explore [reranking](https://docs.typesafe.ai/cookbooks/rerank_typesafe.md)
+  and [hierarchical classification](https://docs.typesafe.ai/cookbooks/hierarchical_classification.md).
+- **Turn judgments into reusable data.** Score dimensions once, then let code or
+  user controls change weights, thresholds, rankings, and views. With labeled
+  outcomes, those signals can become classical ML features. Explore
+  [composite scoring](https://docs.typesafe.ai/patterns/composite-scoring.md) and
+  [feature discovery](https://docs.typesafe.ai/cookbooks/autoresearch_feature_discovery.md).
+- **Verify and escalate.** Check specific claims or fields against their evidence;
+  send uncertain or failing cases to a person or reasoning model. Explore
+  [citation checks](https://docs.typesafe.ai/cookbooks/citation_check.md) and
+  [extraction cascades](https://docs.typesafe.ai/cookbooks/sde_cascade.md).
+- **Respond to changing state.** Code can retain goals and observations while fresh
+  judgments guide the next bounded step. Keep inferred state distinct from observed
+  facts, and check freshness before applying a result to a changed situation.
+
+For open-ended requests, offer the few directions that best serve the user's goal
+and recommend a starting point. For a concrete request, choose the relevant pattern
+and build; a brainstorm is not a mandatory detour.
+
+## Design the judgments
+
+Choose by what the answer means, then read the relevant primitive page:
+
+| Need | Primitive | Important distinction |
+| --- | --- | --- |
+| One of a defined set | [Choice](https://docs.typesafe.ai/primitives/choice.md) | Picks one option; its distribution compares competing options |
+| Whether a condition holds | [Noul](https://docs.typesafe.ai/primitives/noul.md) | Probability of yes; no separate confidence; use one per label when several may apply |
+| Degree along a described dimension | [Score](https://docs.typesafe.ai/primitives/score.md) | Probability-weighted position on ordered levels; use comparable per-item Scores for graded ranking |
+
+Give each question enough relevant **state** to answer: source text, identities,
+relationships, policies, and current facts. Prefer named JSON fields when context
+has several parts. Put the judgment in **instructions** and define its possible
+answers in **criteria**. Question IDs are for code and are not sent to the model;
+include complete meaning in the question. Reference nested state with backticked
+paths such as `ticket.messages[0].text`.
+
+Ask one narrow, coherent judgment per question. Split independently useful dimensions,
+without destroying the relationship being judged. A bounded action selection or
+contextual interpretation is valid; atomic does not mean literal fact extraction
+or a one-sentence limit. Strings work for simple questions. Use structured objects
+or arrays when definitions, contrasts, exclusions, or examples clarify instructions
+or criteria. Score levels must describe concrete situations and stand on their own.
+
+Keep the needed answers available. Include a no-match outcome when nothing may fit;
+use a separate presence judgment when it is independently useful. For source-value
+selection, check candidate coverage: the model cannot choose an omitted value.
+
+## Compose and verify
+
+**Ask independent questions over the same state together**, including useful
+speculative questions. They run in parallel and cannot see one another's answers.
+State each speculative premise explicitly; code consumes the applicable answers.
+A second request is warranted when an earlier answer is needed to fetch evidence,
+construct new state, or determine the next options. Extra questions still use tokens;
+measure actual request budgets, cost, and end-to-end latency.
+
+Use probabilities and confidence to guide behavior, with thresholds evaluated on
+the user's data and consequences. Choice/Score confidence summarizes distribution
+concentration, not overall workflow correctness or permission to act. A Noul near
+0.5 means similar probability for yes and no, not medium intensity. Several
+acceptable alternatives can also spread probability; low confidence need not
+invalidate a harmless preference choice. Ignore uncertainty on unused branches.
+
+Keep policy explicit and raw judgments reusable. Weighted scores suit compensating
+preferences; an “any serious violation” rule needs separate conditions. Changing a
+weight or display filter need not rerun inference when evidence and question meanings
+are unchanged. Typed output guarantees the interface, not truth. System One models
+are trained for calibrated decisions; validate their performance in the target domain.
+
+Test representative cases and the resulting application behavior. For failures,
+inspect the exact state, questions, candidates, answers, composition, and observed
+outcome. Separate missing evidence, model errors, code errors, and service failures.
+Treat cookbook thresholds and demo results as examples to evaluate, not universal
+rules or permanent model limitations. Keep API credentials server-side in web apps.

package/tools/ack-store.mjs

@@ -15,6 +15,7 @@ export const ACKS_COVERAGE_DOMAIN_KEY = 'coverageDomainAck';
 export const ACKS_SOURCE_SIZE_COPY_KEY = 'sourceSizeCopyAck';
 export const ACKS_SPEC_ADOPTION_KEY = 'specAdoptionAck';
 export const ACKS_JEV_CONNECT_KEY = 'jevConnectAck';
+export const ACKS_JEV_SKILL_KEY = 'jevSkillAck';
 
 // The CLOSED-WORLD ack-lane registry: the lane name an advisor item renders on the writer's command line ->
 // the store key that writer sets. A lane the registry does not name is a usage refusal at the writer.
@@ -25,6 +26,7 @@ export const ACK_LANES = Object.freeze({
   'source-size-copy': ACKS_SOURCE_SIZE_COPY_KEY,
   'spec-adoption': ACKS_SPEC_ADOPTION_KEY,
   'jev-connect': ACKS_JEV_CONNECT_KEY,
+  'jev-skill': ACKS_JEV_SKILL_KEY,
 });
 
 export const FINGERPRINT_LENGTH = 16;