@sabaiway/agent-workflow-kit 1.24.0 → 1.26.0

package/CHANGELOG.md

@@ -4,6 +4,75 @@ Semantically versioned ([semver](https://semver.org)), newest first. The `versio
 is the current release. `upgrade` mode reads a project's `docs/ai/.workflow-version` and applies
 every `migrations/<version>-<slug>.md` newer than it, in semver order.
 
+## 1.26.0 — Deterministic bridge freshness & delivery; machine-composed status line; honest installer messaging
+
+A **feature** release (ships the bundled bridges unchanged at **2.1.0**). One architecture across
+four fixes: **the registry computes, the tools speak, the agent pastes** — no factual line on these
+surfaces is agent-composed anymore.
+
+- **Bridge freshness is now visible.** `family-registry` compares each placed bridge against the
+  kit-bundled mirror (both local files — nothing checks npm): behind → a plain caveat + the runnable
+  `/agent-workflow-kit setup` recommend + `refresh.behind:true` in `--json`, reaching the
+  bootstrap/upgrade footers and the welcome mat (priority 1 is now caveat-generic and quotes the
+  firing note's OWN recovery verbatim); uncheckable → an explicit unknown note (never "current",
+  never "behind"); zero-behind → the TOOL prints a checked-scope verdict (`all N checked members are
+  current` — any unknown blocks the all-current claim). New dependency-free `tools/semver-lite.mjs`.
+- **Placed bridges refresh on `init` and `upgrade`.** A refresh-only driver in `setup-backends.mjs`
+  (`--refresh-placed`) refreshes proven-managed placed bridges and NEVER places an absent one —
+  placement stays opt-in via `/agent-workflow-kit setup`. `npx … init` calls it best-effort (a miss
+  is a loud warning + a recovery command composed from the resolved install target + exit 0;
+  `--no-bridges` opts out; win32 is a stated skip); `Mode: upgrade` runs it as a fourth
+  stamp-independent reconcile and pastes the output verbatim. **Never-downgrade:** a placed bridge
+  NEWER than the bundle is a stated keep + "update the kit", enforced at both the plan and the write
+  boundary (TOCTOU re-inspect at apply); an unparseable version is treated as legacy repair, stated.
+- **The one-line backend status is machine-composed.** `tools/recipes.mjs --status-line` emits the
+  exact line (deterministic order, one alias table; additive `statusLine` in `--json`; strict argv —
+  an unknown flag exits loudly instead of masquerading as the human render); SKILL.md now says run
+  the tool and paste its line verbatim — the realistic example that once got echoed as fact is
+  replaced by an explicitly-placeholder template.
+- **The installer speaks facts.** The final verb is keyed on the OBSERVED version comparison
+  (installed / updated / refreshed-the-already-current / downgraded-under-`--allow-downgrade`); the
+  same-version note states that the copy ran (a re-run repairs locally modified files) + a
+  CONDITIONAL `@latest` hint; the false "npx likely served a cached build" accusation is gone. One
+  message contract with the engine installer (engine `1.9.0`).
+- Lens sync everywhere — "placed by `setup` (opt-in), refreshed by `init`/`upgrade` once placed" —
+  across SKILL.md, both READMEs and `family-members.mjs`, guarded by the new region+token
+  `test/init-refresh-lens.test.mjs` (non-vacuous, injected red→green proven).
+
+## 1.25.0 — The bridge driving contract at the point of use (advisor render + wrapper `--help`)
+
+A **feature** release (additive; ships the bundled bridges at **2.1.0**). An agent told to run a
+bridge no longer re-derives the invocation from wrapper source — where it missed documented levers
+(agy's `--facts`/`--decided` grounding, the `agy-review --continue` round-2 delta) and wasted
+subscription runs on ungrounded reviews. The contract is now **delivered at the moment a recipe
+dispatches a backend**, from ONE machine-readable source:
+
+- **Manifest as source.** Each bridge `capability.json` dispatchable role (`review`, `execute`) now
+  carries a structured `contract`: exact copy-pasteable **invocation descriptors** (operands and
+  alternatives included), the **grounding** note, the closed **flag** set (agy-review), the
+  **round-2 / resume** descriptors, and codex-exec's **tiered guarded passthrough**
+  (always-blocked vs `CODEX_PROBE=1`-relaxable). Documented in `tools/manifest/schema.md`.
+- **Advisor renders it at the point of use.** `/agent-workflow-kit procedures <activity>` prints,
+  under every dispatched backend of every slot (review recipes AND `execute=delegated`), the full
+  driving contract VERBATIM — e.g. council shows `agy-review code [--facts @f] [--decided @f] …`
+  plus the `agy-review --continue` delta beside `codex-review plan|code`. `--json` carries the same
+  in an **additive** `slots[*].contracts` field (`backends: string[]` unchanged).
+- **Every wrapper answers `--help`/`-h`** — pre-preflight (no CLI, no login, no git tree, no
+  AGENTS.md needed); keyed on the FIRST argument only, so an open wrapper's passthrough payload
+  (`codex-exec - -- --help`) is never intercepted. The three **dispatchable** wrappers
+  (`codex-review`, `agy-review`, `codex-exec`) print the manifest contract; `agy-run` (probe role —
+  never dispatched by a recipe slot) ships a lightweight wrapper-authored help, pinned for
+  pre-preflight reachability only, with no manifest pivot by design.
+- **Drift-guarded in both directions (test-as-spec), for the dispatchable wrappers.** The kit
+  registry mirror (`wrapperContractFor`) deep-equals each manifest; the advisor's rendered
+  descriptor set set-EQUALS the manifest (a missing AND a stale-extra descriptor both fail); each
+  dispatchable wrapper's `--help` set-EQUALS the manifest; and a **source-level reverse guard**
+  extracts each dispatchable wrapper's real parser arms (mode/flag/resume/passthrough-tier `case`
+  arms, heredocs excluded) and pins them to the manifest — adding a wrapper mode or flag without
+  updating the surfaced contract fails a test.
+- Stale "unguarded codex flags" wording in the codex bridge docs corrected to the real **guarded**
+  passthrough contract.
+
 ## 1.24.0 — Humanize the deploy/version report: hide the internal structure number in the happy path
 
 A **feature** release (report-contract only — no logic, migration, or lineage change; the

package/README.md

@@ -139,8 +139,9 @@ npx @sabaiway/agent-workflow-kit@latest init
 ```
 
 `init` installs/refreshes the skill at `~/.claude/skills/agent-workflow-kit/` and wires launchers for
-any Claude Code / Codex / Devin Desktop it finds. It **does not** deploy into a project, and **does
-not** install the optional bridges.
+any Claude Code / Codex / Devin Desktop it finds. It **does not** deploy into a project, and **never
+places** the optional bridges — **once placed** (by `/agent-workflow-kit setup`) it **refreshes** them
+from its bundled copies (never a downgrade; skip with `--no-bridges`).
 
 ### 2. Deploy into a project — once per repo
 
@@ -202,11 +203,13 @@ refreshes the other npm core members so a returning `init` leaves **no stale cor
 | `~/.claude/skills/agent-workflow-kit/` | the kit itself (refreshed on every `init`) |
 | `~/.claude/skills/agent-workflow-memory/` | the **memory substrate**, refreshed via `npx @sabaiway/agent-workflow-memory@latest init` — **best-effort:** a failure is a **loud degraded success** (warning + the exact recovery command + exit 0), never silent; skip with `--no-memory` |
 | `~/.claude/skills/agent-workflow-engine/` | the **methodology engine** the kit reads live, refreshed via `npx @sabaiway/agent-workflow-engine@latest init` — **required** (the live read STOPs without it); skip with `--no-engine` |
+| `~/.claude/skills/{codex,antigravity}-cli-bridge/` | the placed **bridges**, refreshed from the kit's bundled copies (local files, no network) — **only if `/agent-workflow-kit setup` already placed them**: an absent bridge is never placed, a newer one never downgraded; skip with `--no-bridges` |
 | `~/.codex/skills/agent-workflow-kit` | a symlink — only if you have Codex |
 | `…/global_workflows/agent-workflow-kit.md` | a managed file — only if you have Devin Desktop |
 
-The **execution-backend bridges** (`codex` / `agy`) are **not** installed by `init` — set one up on
-demand with `/agent-workflow-kit setup`. Your other Codex skills and Devin Desktop workflows are
+The **execution-backend bridges** (`codex` / `agy`) are never first **placed** by `init` — set one up
+on demand with `/agent-workflow-kit setup`; after that, a returning `init` keeps the placed copy
+fresh (the table row above). Your other Codex skills and Devin Desktop workflows are
 never touched. If one of those exact slots already holds a file the kit didn't write, it is **left
 alone** and you're told — re-run with `--force` to replace it (the original is first copied to
 `*.bak.<timestamp>` and the restore command is printed).
@@ -222,13 +225,13 @@ file), or run the guarded `/agent-workflow-kit uninstall`.
 | Command | When | What happens |
 |---------|------|--------------|
 | `/agent-workflow-kit` | new / empty project | recon → **asks visible-or-hidden** + **conversational language** + **agent attribution** (default off) → deploys `AGENTS.md` + `docs/ai/` filled with real recon data → installs enforcement → **asks before committing** |
-| `/agent-workflow-kit upgrade` | existing deployment | reads `docs/ai/.workflow-version`, shows the changelog diff, preserves your authored memory, applies migrations, re-stamps — then prints a **read-only** one-line backend-status line (what's set up vs missing); never installs a bridge — set one up with `/agent-workflow-kit setup` |
+| `/agent-workflow-kit upgrade` | existing deployment | reads `docs/ai/.workflow-version`, shows the changelog diff, preserves your authored memory, applies migrations, re-stamps — then prints a **read-only** one-line backend-status line (what's set up vs missing); refreshes the already-placed bridges from the kit's bundled copies (never installs a new one — set one up with `/agent-workflow-kit setup`) |
 | `/agent-workflow-kit help` | any time | **read-only command index** — every command, grouped (Inspect / Configure / Orchestrate / Lifecycle) and tagged read-only / writer / guarded. The discoverable entry point, and where any unrecognized invocation lands (always read-only — a garbage invocation never writes). Never writes, never commits, never runs a subscription CLI. |
 | `/agent-workflow-kit backends` | any time | **read-only** check of the optional execution-backends (the `codex` / `agy` bridges): what's set up vs missing and the next step. Never writes, never commits, never runs a subscription CLI (credentials = marker-file presence, not a live login). |
 | `/agent-workflow-kit setup [backend]` | opt-in, any time | **link-only** auto-setup of a bridge: places the bundled bridge skill (only into an absent / empty / managed dir — never overwrites an unmanaged one) + links its wrappers onto `PATH` via managed symlinks (idempotent; refuses to clobber a non-symlink; try `--dry-run` to preview). The binary install + the one-time subscription login stay **manual**: it prints the exact **login** command and points the binary install at each bridge's `setup/README.md`. POSIX wrappers — on Windows use WSL. Never commits, never runs a subscription CLI. |
 | `/agent-workflow-kit status` | any time | **read-only** single view of **versions + deployment + settings + bridges**: which members (kit / memory / engine / the two bridges) are installed and at what version (with an honest "installed on this machine" note when one is behind) and — in a project — what's deployed (`docs/ai`, the version stamps, and the **visibility**: visible / hidden / unclear), plus your settings (orchestration recipes, attribution, velocity) and the bridges' readiness. The two version axes (package number vs deployment-structure head) stay decoupled. Never writes, never commits, never runs a subscription CLI. |
 | `/agent-workflow-kit recipes` | any time | **read-only** orchestration advisor: presents four named recipes for composing the bridges into plan → execute → review — **Solo / Reviewed / Council / Delegated** — plans + recommends one for your environment (degrading with a stated reason when a backend isn't ready), and offers the choice. The orchestrator runs it via the bridge skills and **always commits**; the kit never executes a recipe, never runs a subscription CLI, never commits. |
-| `/agent-workflow-kit procedures <activity>` | any time | **read-only** activity-procedures advisor: prints a named activity's ordered steps (`plan-authoring` / `plan-execution`) read **live** from the engine, plus the **resolved recipe per slot** from your `docs/ai/orchestration.json` (agent-writable via `set-recipe`, or hand-edited) + backend readiness (default Reviewed when a backend is ready, Council on request, slot-aware incl. Delegated). `--override <slot>=<recipe>` adjusts one slot per run. Composes with `recipes`; never writes, never commits, never runs a subscription CLI. |
+| `/agent-workflow-kit procedures <activity>` | any time | **read-only** activity-procedures advisor: prints a named activity's ordered steps (`plan-authoring` / `plan-execution`) read **live** from the engine, plus the **resolved recipe per slot** from your `docs/ai/orchestration.json` (agent-writable via `set-recipe`, or hand-edited) + backend readiness (default Reviewed when a backend is ready, Council on request, slot-aware incl. Delegated) — and, for every dispatched backend, the **full driving contract at the point of use** (exact copy-pasteable invocation, grounding levers like agy's `--facts`/`--decided`, the round-2 `--continue` delta, guarded passthrough), verbatim from the bridge manifests (drift-guarded; each wrapper's `--help` prints the same). `--override <slot>=<recipe>` adjusts one slot per run. Composes with `recipes`; never writes, never commits, never runs a subscription CLI. |
 | `/agent-workflow-kit set-recipe` | any time | **config writer** for `docs/ai/orchestration.json`: tell the agent your preference in plain language and it maps it to explicit `--set <activity>.<slot>=<recipe>` / `--unset` ops; the kit validates, **previews by default**, and writes only on `--write` (deployment-gated, atomic, symlink/TOCTOU-safe), resolving the effective recipe vs live readiness. Writes **only** that file — **never runs a backend, never commits**; hand-editing stays fully supported. |
 | `/agent-workflow-kit uninstall` | opt-in, any time | **guarded teardown** — the inverse of `init` / `setup`. Removes only what's **provably ours** (managed skill dirs + bridge wrappers; in a project, the hidden-mode git-ignore block it added + the pre-commit hook it installed); **never deletes** your `docs/ai` / `AGENTS.md` (prints the exact `rm` to run by hand) or your `.claude/settings.json` (prints an **edit** — remove the attribution key, review any velocity `permissions.*` — never an `rm`). Always `--dry-run` first; preflight-then-mutate; never commits. |
 | `/agent-workflow-kit velocity` | Claude Code · opt-in | **onboarding velocity profile** — seeds a fixed, audited **read-only** allowlist into `.claude/settings.json` so routine read-only commands stop idling on approval prompts while you're away; opt-in `acceptEdits`; plus a **read-only advisory** of likely project gate commands to add by hand. Writes **only** `.claude/settings.json` — **never** allowlists commit/push/publish, never writes `settings.local.json`, never commits. A seeded entry is a **trust posture, not a sandbox** (a redirection/command-substitution residual remains, closed by a deferred hook); a direct commit/push/publish still asks. `--dry-run` first. |
@@ -274,8 +277,9 @@ agent-workflow-kit  —  the composition root (installed via npx … init)
   **orchestration recipes** (Solo / Reviewed / Council / Delegated) — read **live** from the installed
   **`agent-workflow-engine`** (the canonical narrative; a published member, never one of the shipped
   backends). `/agent-workflow-kit recipes` surfaces + plans a recipe for your environment, read-only.
-- **Detects & (opt-in) sets up** the optional `codex` / `agy` **bridges** — agent skills (not npm, not
-  installed by `init`). They plug into the workflow's **execute** and **review** phases — for *what
+- **Detects & (opt-in) sets up** the optional `codex` / `agy` **bridges** — agent skills (not npm;
+  never first placed by `init` — `setup` places them, and once placed `init`/`upgrade` refresh
+  them). They plug into the workflow's **execute** and **review** phases — for *what
   each adds and why*, see the
   [family front door](https://github.com/sabaiway/agent-workflow#readme). `/agent-workflow-kit backends`
   reports readiness **read-only**;

package/SKILL.md

@@ -3,7 +3,7 @@ name: agent-workflow-kit
 description: Deploy or upgrade a portable AI-agent memory-and-workflow system in any project. Use when the user wants to bootstrap `docs/ai/` + an entry-point `AGENTS.md` (+ `CLAUDE.md` alias) + cap/archive/index enforcement in a new or existing repo, set up the Memory Map and session protocols, install the docs-rotation pre-commit hook, or run `/agent-workflow-kit` / `/agent-workflow-kit upgrade`. Triggers on phrases like "set up the memory system", "deploy the AI workflow here", "bootstrap docs/ai", "upgrade the workflow".
 disable-model-invocation: true
 metadata:
-  version: '1.24.0'
+  version: '1.26.0'
 ---
 
 # agent-workflow-kit
@@ -31,7 +31,10 @@ runtime dependency placed by `init` and read live; see *Methodology slot reconci
 `init` also **refreshes the installed memory substrate** (best-effort — a miss is a loud DEGRADED
 success: a warning with the exact recovery command + exit 0, never silent, never the engine's hard
 STOP; `--no-memory` skips it), so a returning `init` leaves **no stale core member**. The
-execution-backend bridges are still **not** installed by `init` (placed on demand by `setup`).
+execution-backend bridges are still never **placed** by `init` (placed on demand by `setup`, opt-in);
+**once placed**, `init` **refreshes** them from the kit's own bundled copies (refresh-only, local
+files, never a downgrade; `--no-bridges` skips it) — so a returning `init` leaves no stale placed
+bridge either.
 
 **Detection (kit-owned, decided BEFORE any project write).** Run the kit's **own shipped**
 validator — `node ${CLAUDE_SKILL_DIR}/tools/manifest/validate.mjs <memory-skill-dir>` — never a
@@ -108,10 +111,10 @@ Pick the mode from the user's invocation. Auto-detect an existing `docs/ai/` to
 - **`/agent-workflow-kit upgrade`** — upgrade an existing deployment to the skill's current `version`.
 - **`/agent-workflow-kit help`** — read-only **command index**: enumerate every command, grouped (Inspect / Configure / Orchestrate / Lifecycle) and tagged read-only / writer / guarded. The single discoverable entry point, and the landing spot for any unrecognized invocation. Never writes, never commits, never runs a subscription CLI.
 - **`/agent-workflow-kit backends`** — read-only environment check: which optional **execution-backends** (the `codex` / `agy` bridges) are set up vs missing. Never writes, never commits, never runs a subscription CLI.
-- **`/agent-workflow-kit setup [backend]`** — the **link-only**, opt-in companion to `backends`: place the bundled bridge skill + link its wrappers onto `PATH`. **In-agent only** — `init` (npx) never places bridges. The binary install + the interactive subscription login stay **manual** (it prints the exact commands); idempotent; refuses to clobber a non-symlink; never commits, never runs a subscription CLI.
+- **`/agent-workflow-kit setup [backend]`** — the **link-only**, opt-in companion to `backends`: place the bundled bridge skill + link its wrappers onto `PATH`. **In-agent only** — `init` (npx) never *places* bridges; once placed, `init`/`upgrade` refresh them (refresh-only). The binary install + the interactive subscription login stay **manual** (it prints the exact commands); idempotent; refuses to clobber a non-symlink; never commits, never runs a subscription CLI.
 - **`/agent-workflow-kit status`** — read-only view of the **whole family**: which members (kit / memory / engine / the two bridges) are installed, at what version, and — in a project — what is deployed (`docs/ai`, the version stamps, the hidden-mode fence). Never writes, never commits, never runs a subscription CLI.
 - **`/agent-workflow-kit recipes`** — read-only **orchestration advisor**: present the four recipes (Solo / Reviewed / Council / Delegated) over the bridges' role vocabulary, plan + recommend one for the current environment, and offer the choice. **The orchestrator executes the chosen recipe via the bridge skills and always commits** — the kit only surfaces/selects/plans it; it never executes a recipe, never runs a subscription CLI, never commits.
-- **`/agent-workflow-kit procedures <activity>`** — read-only **activity-procedures advisor**: print the ordered steps of a named activity (`plan-authoring` / `plan-execution`) read **live** from the installed engine (`references/procedures.md`), and the **resolved effective recipe per slot** from the per-project `docs/ai/orchestration.json` (strict JSON; agent-writable via `set-recipe` or hand-edit) + backend readiness (default = Reviewed when a backend is ready, Council on request, slot-aware incl. Delegated; graceful default vs loud override degradation). A per-run `--override <slot>=<recipe>` overrides one slot. Composes with `recipes` (which stays read-only); never writes, never commits, never runs a subscription CLI.
+- **`/agent-workflow-kit procedures <activity>`** — read-only **activity-procedures advisor**: print the ordered steps of a named activity (`plan-authoring` / `plan-execution`) read **live** from the installed engine (`references/procedures.md`), and the **resolved effective recipe per slot** from the per-project `docs/ai/orchestration.json` (strict JSON; agent-writable via `set-recipe` or hand-edit) + backend readiness (default = Reviewed when a backend is ready, Council on request, slot-aware incl. Delegated; graceful default vs loud override degradation) — plus, for every dispatched backend, the **full driving contract at the point of use**: the exact copy-pasteable invocation descriptor(s), the grounding levers (agy `--facts`/`--decided`), the round-2 `--continue` delta, and the guarded passthrough tiers, rendered verbatim from the bridge manifests (drift-guarded; each wrapper's `--help` prints the same contract). A per-run `--override <slot>=<recipe>` overrides one slot. Composes with `recipes` (which stays read-only); never writes, never commits, never runs a subscription CLI.
 - **`/agent-workflow-kit set-recipe`** — the **config writer** for `docs/ai/orchestration.json`: turn the user's plain language into explicit `--set <activity>.<slot>=<recipe>` / `--unset` ops; the kit validates, merges, **previews by default**, and writes only on `--write` (deployment-gated, atomic, symlink/TOCTOU-safe). Resolves the effective recipe vs live readiness (degradation honesty on both paths). **Writes only `docs/ai/orchestration.json`; never runs a backend, never commits.** Hand-editing the file stays fully supported.
 - **`/agent-workflow-kit uninstall`** — the **guarded teardown** companion to `init`/`setup`. Removes what they placed — installed skill dirs + the bridge wrappers — and, in a project, reverses the hidden-mode fence + the marker pre-commit hook. **Never deletes user-authored content**: it prints the exact `rm` for `docs/ai` / `AGENTS.md` and an **edit** for `.claude/settings.json` (the `includeCoAuthoredBy` key + any velocity `permissions.*`), for you to run by hand. `--dry-run` first, always; preflight-then-mutate; never commits.
 - **`/agent-workflow-kit velocity`** — opt-in onboarding **velocity profile**: seed a fixed, audited **read-only** Claude Code allowlist into `.claude/settings.json` so routine read-only commands stop idling on approval prompts; opt-in `acceptEdits`; plus a **read-only advisory** of likely project gate commands to add by hand. **Writes only `.claude/settings.json`, never allowlists commit/push/publish, never writes `settings.local.json`, never commits.** `--dry-run` first.
@@ -137,29 +140,32 @@ Before acting, read `docs/ai/.workflow-version` (the project's stamp) to decide
 ### The one-line backend-status line (shared by bootstrap + upgrade)
 
 Bootstrap (step 11) and **every** successful `upgrade` exit (steps 4 + 8) print the **same**
-read-only, one-line summary of the optional execution-backends. Run the **backend detector** —
-`node ${CLAUDE_SKILL_DIR}/tools/detect-backends.mjs` — and compose one line from its per-backend
-readiness, then **append an actionable recipe recommendation** from the recipe planner
-(`node ${CLAUDE_SKILL_DIR}/tools/recipes.mjs --json` → `recommendation.clause`, P2-rich). Canonical format:
-`backends: codex ✓ ready · antigravity ✗ needs-credentials — run /agent-workflow-kit backends · recipes: Reviewed available (via codex) — see /agent-workflow-kit recipes`
-
+read-only, one-line summary of the optional execution-backends. The line is **machine-composed** —
+run the status-line composer and **paste its single emitted line verbatim**:
+`node ${CLAUDE_SKILL_DIR}/tools/recipes.mjs --status-line`
+The tool runs the backend detector and appends the recipe recommendation itself
+(`composeStatusLine`); the agent **composes nothing factual** — no readiness token, no glyph, no
+recipe clause of its own, ever.
+
+- **Placeholder template (structure only — never copy this example; paste the tool's line):**
+  `backends: <alias> <✓|✗> <readiness> · <alias> <✓|✗> <readiness> — run /agent-workflow-kit backends · recipes: <recommendation clause> — see /agent-workflow-kit recipes`
 - The **`recipes:` clause is appended after** the `— run /agent-workflow-kit backends` pointer (never
   replacing it) and routes to the read-only `recipes` mode (`see /agent-workflow-kit recipes`). It is
   **never blank**: both backends ready → *"Council available, Reviewed the everyday default"*; one
   ready → *"Reviewed available (via …)"*; **none installed → *"Solo — run /agent-workflow-kit setup to
   add a backend"***; a backend present-but-not-ready → Solo with that backend's specific remedy.
-  (Matches `recommendRecipe`.)
+  (Composed by `recommendRecipe` inside the same tool run — never by the agent.)
 - **Invariants:** **read-only · never blocks the commit gate · never runs a subscription CLI · the
   pointer is the in-agent `backends` mode, never a network fetch · the appended `recipes:` clause
-  routes to the in-agent `recipes` mode the same way · `init`/npx is unaffected (it never places
-  bridges, AD-011 §5).**
-- **Detector unavailable → skip with a stated reason, never silently.** The detector is a Node script
+  routes to the in-agent `recipes` mode the same way · `init`/npx never *places* bridges (it
+  refreshes only what `setup` already placed, AD-011 §5).**
+- **Composer unavailable → skip with a stated reason, never silently.** The composer is a Node script
   the **agent host** runs (not the target project), so the only skip condition is "**the agent host
-  can't run it**" — `node` is not on the agent's PATH, or the detector itself errors — **not** "the
+  can't run it**" — `node` is not on the agent's PATH, or the tool itself errors — **not** "the
   project has no Node runtime". On that condition, skip the line and say so **with the concrete
-  reason**, e.g. *"Couldn't run the backend detector here (node is not on the agent host PATH), so
-  I'm skipping the backend-status line."* — never a silent skip (Hard Constraint — no silent
-  failures).
+  reason**, e.g. *"Couldn't run the backend status-line composer here (node is not on the agent host
+  PATH), so I'm skipping the backend-status line."* — never a silent skip (Hard Constraint — no
+  silent failures).
 
 ### The version block + welcome mat (shared by bootstrap + upgrade)
 
@@ -206,8 +212,12 @@ the rest of the report — and the commit gate — proceeds.
 line, print *"Run `/agent-workflow-kit help` to see every command."* then **one** recommended next
 step, chosen **caveat-aware** from signals already in hand (the version block's notes + the
 backend-status line — no new helper call) in this priority order:
-1. a member is **behind** (an `installed[].notes` caveat fired — memory/engine) → *refresh the behind
-   member first* (its `npx …@latest init` + restart the session);
+1. a member is **behind** (a behind-class `installed[].notes` caveat fired — any member, the bridges
+   included) → *refresh the behind member first*, quoting **that note's own recovery command
+   verbatim** (a memory/engine note carries its `npx …@latest init` + restart the session; a bridge
+   note carries `/agent-workflow-kit setup`). An **uncheckable** member ("couldn't be checked" — an
+   unknown-freshness note) is **never** a refresh trigger: only a behind note fires this step — the
+   uncheckable note already appears in the version block, add nothing more;
 2. else **no backend is ready** (the backend-status line shows none ready) → *set one up with
    `/agent-workflow-kit setup`*;
 3. else **a backend is ready but the orchestration config is still all-Solo** (no `reviewed` /
@@ -316,15 +326,27 @@ Fill strategy:
    **Hidden-mode footprint reconcile — stamp-independent, same gate, BEFORE the equal-head short-circuit (D9 / AD-014).** A deployment does not record whether it chose `hidden`, so first **infer visibility**: `node ${CLAUDE_SKILL_DIR}/tools/hide-footprint.mjs --dir <project> --reconcile --dry-run` (writes **zero bytes**). It reports one of — **visible** (the entry point is tracked) → nothing to do; **ambiguous** (untracked but not ignored — could be a fresh uncommitted repo, or a hide that broke) → **ASK** the user which it is, never guess; **hidden** → re-run without `--dry-run` to migrate any older **machine-global** hide to the **project-local** `.git/info/exclude` (one managed block; folds in the legacy `.claude/skills/` line), idempotently (a clean re-run is zero-diff). Handle its surfaced paths exactly as bootstrap step 9 (already-committed → show `git rm --cached`, ask before `--include`; generic-name present file → ask; **leftover machine-wide ignore block → ASK before `--remove-global`**, default keep + report). No Node on the agent host / Windows → as step 9. This runs on **every** hidden upgrade, like the methodology slot — no lineage-head bump, no migration file.
 
    **Orchestration config ensure (seed-or-refresh) — stamp-independent, same gate, BEFORE the equal-head short-circuit.** Ensure `docs/ai/orchestration.json` exists **and its onboarding note is current**: **create it from the template if missing**; **if it already exists, preserve every activity/slot the user set, and refresh ONLY the `_README` note when the existing one still matches a known prior canonical** — the tested `refreshIfCanonical` / `refreshReadme` in `tools/orchestration-config.mjs` is the source of truth for that decision (normalize CRLF/whitespace before comparing; a *customized* `_README` is preserved verbatim; a *malformed* existing config is **preserved + a loud warning**, never clobbered or silently skipped). The current note points at `/agent-workflow-kit set-recipe` (the config is now agent-writable — no more "never written for you"). **The refresh helper is kit-owned** — in the **delegated** path memory only seeds/preserves the file (memory upgrade step 2) and the **kit** then applies the `_README` refresh; in the **fallback** path the kit seeds-or-refreshes directly from `${CLAUDE_SKILL_DIR}/references/templates/orchestration.json`. (Memory stays standalone — it never depends on this helper.) Like the pointer slots + the footprint reconcile, this reaches an equal-head (`1.3.0`) deployment **without a lineage-head bump or a migration file** (it is a `.json`, inherently outside the docs cap-validator). Report it in the step 4 / step 8 success report (config *seeded* / *note refreshed* / *already current* / *customized — preserved*).
+
+   **Placed-bridge refresh — stamp-independent, same gate, BEFORE the equal-head short-circuit.** Run
+   `node ${CLAUDE_SKILL_DIR}/tools/setup-backends.mjs --refresh-placed` and **paste its per-bridge
+   output lines verbatim** — every outcome line is composed by the tool (*refreshed* / *already
+   current* / *skipped — not placed* / *could not refresh* + its recovery); you compose nothing
+   factual. It is **refresh-only**: it refreshes a bridge **`setup` already placed** from this kit's
+   bundled copies and re-links its wrappers; an **absent** bridge is a stated skip, **never a first
+   placement** (placement stays the opt-in *Mode: setup* — AD-009/AD-011 honesty intact), and a
+   placed bridge **newer** than the bundled copy is a stated skip naming the kit update (**never a
+   downgrade**). Like the other three reconciles it runs on **every** upgrade — including an
+   equal-head one — with no lineage-head bump. A *could not refresh* line is non-fatal: relay it
+   plainly with its recovery and continue the upgrade.
 4. **Equal-head exit — a real successful-exit report, not a bare stop.** If the stamp **equals** the head, the lineage is up to date — but step 3 (the methodology-slot **and** hidden-mode footprint reconciles) ran first and may have changed things, so this is a proper exit report, not a no-op:
-   - **Report step 3's outcome in plain language** — for **each** pointer (workflow-methodology and orchestration-recipes) whether it was *added*, was *already present* (nothing changed), or was *skipped because the entry point is over its line limit* (the cap-refusal soft-skip from step 3, with its reason); whether the `docs/ai/orchestration.json` config was *seeded* (created from the template), had its onboarding note *refreshed*, was *already current*, or carried a *customized note that was preserved* (a user edit is never clobbered); and, for a hidden deployment, whether the hidden-mode footprint was *moved to project-local*, was *already project-local* (nothing changed), or needed a question (ambiguous visibility / a leftover machine-wide block). Plain wording only — never the reconcile/slot/anchor/marker terms (Gotcha: never leak kit internals).
+   - **Report step 3's outcome in plain language** — for **each** pointer (workflow-methodology and orchestration-recipes) whether it was *added*, was *already present* (nothing changed), or was *skipped because the entry point is over its line limit* (the cap-refusal soft-skip from step 3, with its reason); whether the `docs/ai/orchestration.json` config was *seeded* (created from the template), had its onboarding note *refreshed*, was *already current*, or carried a *customized note that was preserved* (a user edit is never clobbered); the **placed-bridge refresh** outcome — paste the tool's per-bridge lines verbatim (they are already plain: *refreshed* / *already current* / *skipped — not placed* / *could not refresh* + recovery); and, for a hidden deployment, whether the hidden-mode footprint was *moved to project-local*, was *already project-local* (nothing changed), or needed a question (ambiguous visibility / a leftover machine-wide block). Plain wording only — never the reconcile/slot/anchor/marker terms (Gotcha: never leak kit internals).
    - **Never surface the structure number on this exit.** Whatever step 3 did, do **not** recite the `docs/ai` structure version, the internal versioning vocabulary, or the two-axes note here — the number is inert on an equal-head exit; it belongs to *Version disclosure* (shown at the never-downgrade STOP, the explicit status view, or on an explicit ask). Frame the success itself per the final bullet: if step 3 changed anything, say **what changed** in plain human terms; only a pure zero-diff no-op is *settings already current — no update needed*.
    - **Print the report footer** in the canonical order (version block → one-line backend-status line → welcome mat — the shared contracts above; rendered from the helpers, same host-can't-run skip-with-reason). The welcome mat closes on **one** caveat-aware next step (a behind member first, else `setup` / `recipes` / `velocity`).
    - **Then ask before committing — never auto-commit.** If step 3 added the slot (or anything else changed), report it and ask. If step 3 was a pure zero-diff no-op and nothing else changed, give the plain **settings already current — no update needed** message (the *Success state* contract) and still print the read-only version block (installed package versions) + backend line — but **no `docs/ai` structure version and no two-axes note** (nothing changed, so the number is inert here).
 5. Show the relevant `${CLAUDE_SKILL_DIR}/CHANGELOG.md` diff (entries newer than the project's stamp).
 6. Apply `${CLAUDE_SKILL_DIR}/migrations/<version>-<slug>.md` in **semver order**, only those newer than the project's stamp. Migrations are **idempotent** — safe to re-run.
 7. Reconcile drift: add any kernel files/scripts the project is missing; never clobber project-authored content (their `decisions.md`, `known_issues.md`, page specs stay). Any user question a migration raises follows the same rule as bootstrap — **structured multiple-choice where supported** (`AskUserQuestion` in Claude Code), otherwise prose. If `AGENTS.md` has no *Communication language* block (pre-1.1.0 deployment), **ask the user their conversational language** and insert the block — see `migrations/1.1.0-communication-language.md`. If it has no *Attribution* block (pre-1.2.0 deployment), **ask whether the agent may attribute work to itself / AI** and insert the block (defaulting to `off`) — see `migrations/1.2.0-agent-attribution.md`.
-8. Re-stamp `docs/ai/.workflow-version` to the **deployment-lineage head** (`1.3.0`, not the package version — mechanics unchanged: the atomic write to the stamp file). In the report, **describe what the upgrade changed in plain human terms** — which parts of their `docs/ai` are now different (the migrations that ran) — rather than reciting a version number; **omit the raw structure number**, and do **not** print the two-axes note here (it belongs to *Version disclosure*, on demand only). Then **print the report footer** in the canonical order (version block → one-line backend-status line → welcome mat — the shared contracts above; rendered from the helpers, same host-can't-run skip-with-reason; the welcome mat closes on one caveat-aware next step). Then **ask before committing**.
+8. Re-stamp `docs/ai/.workflow-version` to the **deployment-lineage head** (`1.3.0`, not the package version — mechanics unchanged: the atomic write to the stamp file). In the report, **describe what the upgrade changed in plain human terms** — which parts of their `docs/ai` are now different (the migrations that ran), plus the step-3 **placed-bridge refresh** lines (pasted verbatim) — rather than reciting a version number; **omit the raw structure number**, and do **not** print the two-axes note here (it belongs to *Version disclosure*, on demand only). Then **print the report footer** in the canonical order (version block → one-line backend-status line → welcome mat — the shared contracts above; rendered from the helpers, same host-can't-run skip-with-reason; the welcome mat closes on one caveat-aware next step). Then **ask before committing**.
 
 ### Mode: backends
 
@@ -338,13 +360,19 @@ Read-only. Answers *"which optional execution-backends are set up vs missing, an
 
 ### Mode: setup
 
-The **only writer** among the backend modes, and **opt-in / in-agent only** — it is **never** part of `init`. The npx installer deploys the *kit* and bundles the bridge skills in its tarball, but **does not place** them (that honesty claim is load-bearing — see `decisions.md` AD-009 / AD-011). `setup` owns exactly the two deterministic, secret-free steps and **guides** the rest. It **never commits and never runs a subscription CLI**.
+The **only writer** among the backend modes, and **opt-in / in-agent only** — **placement** is **never** part of `init`. The npx installer deploys the *kit* and bundles the bridge skills in its tarball, but **does not place** them (that honesty claim is load-bearing — see `decisions.md` AD-009 / AD-011); **once placed** by `setup`, `init` and *Mode: upgrade* keep the placed copy fresh via the refresh-only `--refresh-placed` (below) — **never a first placement, never a downgrade**. `setup` owns exactly the two deterministic, secret-free steps and **guides** the rest. It **never commits and never runs a subscription CLI**.
 
 Run `node ${CLAUDE_SKILL_DIR}/tools/setup-backends.mjs [<backend>] [--bindir <path>] [--dry-run]`:
 
 - `<backend>` — `codex` | `agy` | `antigravity` | `codex-cli-bridge` | `antigravity-cli-bridge`; omit for **all**.
 - `--bindir <path>` — where to link the wrappers (default `~/.local/bin`).
 - `--dry-run` — print the per-backend plan and change **nothing** (run this first).
+- `--refresh-placed` — the **refresh-only** mode (what `init` runs automatically and *Mode: upgrade*
+  runs as its fourth stamp-independent reconcile): refresh every bridge `setup` **already placed**
+  from the kit's bundled copies + re-link its wrappers; an absent bridge is a stated skip (**never**
+  placed), a placed bridge newer than the bundle is a stated skip naming the kit update (**never**
+  downgraded), and every outcome line is composed by the tool — paste verbatim. Does not combine
+  with `--dry-run`.
 - `--help`, `-h` — usage.
 
 For each backend it:
@@ -367,7 +395,7 @@ Read-only. The **single answer to "versions + deployment + settings + bridges"**
 
 Run `node ${CLAUDE_SKILL_DIR}/tools/family-registry.mjs --json [--dir <project>]` and render it **compact**, in the user's conversational language — **never paste the JSON or any internal field name** (no-leak rule). Map the **`installed[].state`** token via the value→plain-language map under *The version block + welcome mat* (the `visibility` and wrapper states have their own phrasings, below). Present, each area on its own line(s), routing detail to its domain mode:
 
-1. **Versions — a status-only render from `installed[]` + `deploymentHead`** (this is **NOT** the shared notes-based version block — see the separation note below): the **`docs/ai` structure version** (named as such, never "lineage head"), then each member by its `display` showing its `version` (or, when there is no version, the plain phrase for its `state`, mapped above), plus the two-axes disambiguation. **Freshness comes from `installed[].refresh`, not from `notes`:** for each member whose **`refresh.behind`** is `true`, show a **localized "needs refresh"** label and the **verbatim `refresh.recommend`** command **exactly once** (the command/package name stays source-language; **do not also paste the English `notes` caveats** — `refresh.recommend` is the single source of the recovery step, so the command is never duplicated on this surface). Lead with a one-line **headline count** derived from `installed[].state` + `refresh.behind` (e.g. *"5 members installed · 1 needs a refresh"*).
+1. **Versions — a status-only render from `installed[]` + `deploymentHead`** (this is **NOT** the shared notes-based version block — see the separation note below): the **`docs/ai` structure version** (named as such, never "lineage head"), then each member by its `display` showing its `version` (or, when there is no version, the plain phrase for its `state`, mapped above), plus the two-axes disambiguation. **Freshness comes from `installed[].refresh`, not from `notes`:** for each member whose **`refresh.behind`** is `true`, show a **localized "needs refresh"** label and the **verbatim `refresh.recommend`** command **exactly once** (the command/package name stays source-language; **do not also paste the English `notes` caveats** — `refresh.recommend` is the single source of the recovery step, so the command is never duplicated on this surface). A member whose **`refresh.freshness`** is **`unknown`** is surfaced too — a localized *"couldn't be checked"* label; it is **never counted as current and never as behind** (its `notes` caveat carries the detail on the notes-based surfaces; here the label is enough). Lead with a one-line **headline count** derived from `installed[].state` + `refresh.behind` + `refresh.freshness` (e.g. *"5 members installed · 1 needs a refresh · 1 couldn't be checked"* — omit a zero count).
 
 > **Status reads `refresh`; the shared version block + the bootstrap/upgrade footers stay `notes`-based (unchanged this release).** *Mode: status* has its OWN status-only render (above), keyed on `installed[].refresh.behind` / `refresh.recommend`. The shared **version block** (under *The version block + welcome mat*) and the bootstrap (step 11) + every upgrade (steps 4 / 8) report footer still consume `installed[].notes` verbatim — that wiring is deliberately **untouched** here (their migration onto `refresh` is deferred). Do not rewrite those footers onto `refresh`.
 2. **Deployment (`--dir`)** (from `project`): whether `docs/ai/` is deployed + the deploy stamps by `display`; and **visibility** — render `project.visibility.state` in **user-safe words only**: *visible (tracked)* / *hidden (git-ignored, local-only)* / *unclear (uncommitted or partially set up)* — **never** the words "hidden fence" or any marker term. A `visibility.error` → surface it plainly.
@@ -554,6 +582,6 @@ Deploy these into `AGENTS.md`; remove rows that don't apply to the stack.
 - [`references/scripts/`](references/scripts/) — the Node enforcement scripts (caps + staleness + index-freshness gate, 3-tier archive, hook installer) and their unit tests.
 - [`migrations/`](migrations/) — per-version upgrade steps; see `migrations/README.md`.
 - [`launchers/`](launchers/) — run the bootstrapper from non-Claude agents (`SKILL.md` is a native Codex skill; a Devin Desktop workflow launcher + install script). See `launchers/README.md`.
-- [`tools/`](tools/) — the family-wide tooling the kit **owns and ships**: `manifest/{schema.md,validate.mjs}` (the `capability.json` schema + the validator the kit runs as the memory detector, and root CI invokes), `commands.mjs` (the canonical **command catalog** + the pure `routeInvocation` router behind `/agent-workflow-kit help` and the safe unknown-invocation routing rule — one source of truth for the command surface, drift-guarded against the `### Mode:` headers), `delegation.mjs` (the executable delegate/fallback decision + hand-off plan), `inject-methodology.mjs` + `engine-source.mjs` (the bounded **two-slot** reconciliation — ensure-slot / inject-if-empty / cap for the `workflow:methodology` **and** `workflow:orchestration` pointers; both fragments read **live** from the installed `agent-workflow-engine` via `engine-source.mjs` (`deps.rel` selects which) — the family's one source of truth, no bundled mirror; fail-loud when the engine is needed but absent, orchestration soft-skipped when it would bust the cap), `detect-backends.mjs` (the read-only **backend detector** behind `/agent-workflow-kit backends`, plus the axis-aware `guideFor`; exports the readiness consts the planner reuses), `recipes.mjs` (the read-only **recipe planner** behind `/agent-workflow-kit recipes` — `RECIPES` / `planRecipe` / `recommendRecipe` over the bridges' role vocabulary, drift-guarded against `provides`/`cost`/`quota` + an engine↔kit recipe-name parity guard; pure, never runs a subscription CLI; also exports the pure `ACTIVITIES` / `resolveActivityRecipe` activity-procedures resolver), `procedures.mjs` (the read-only **activity-procedures advisor** behind `/agent-workflow-kit procedures` — reads `references/procedures.md` live from the engine via `engine-source.mjs`, reads + validates the agent-writable `docs/ai/orchestration.json` via `orchestration-config.mjs`, and prints the steps + the resolved effective recipe per slot; drift-guarded activity/slot table vs the canon; read-only, never imports the writer, never runs a subscription CLI), `orchestration-config.mjs` (the config **schema/read/pure-transform core** — `loadConfig`/`validateConfig`/the shared slot-recipe validity + `parseOp`/`applySetOps`/`serializeConfig`/the canonical-refresh helpers; no fs writes), `orchestration-write.mjs` (the **only** config fs-writer — a deployment-gated, atomic, symlink/TOCTOU-safe `writeConfig`; imported by `set-recipe` alone, never by `procedures`), `set-recipe.mjs` (the **config writer** behind `/agent-workflow-kit set-recipe` — validate → merge → preview-by-default → write; never runs a backend, never commits), `setup-backends.mjs` (the **link-only** backend setup behind `/agent-workflow-kit setup` — place the bundled bridge + link wrappers), `fs-safe.mjs` (the shared symlink-traversal-safe copy/link/**remove/unlink** primitives that `setup-backends`, the npx installer, and the uninstaller use), `known-footprint.mjs` + `hide-footprint.mjs` (the **hidden-mode** registry + the single hide-writer behind step 9 / the upgrade reconcile — one managed block in the **project-local** `.git/info/exclude` covering the full AI/agent footprint; pinned by `known-footprint.test.mjs` drift-guard + `hide-footprint.test.mjs` / `.integration.test.mjs`), `family-registry.mjs` (the **unified family registry** behind `/agent-workflow-kit status` — aggregates every member's `capability.json`; pinned by a `family-registry.test.mjs` drift-guard), `uninstall.mjs` (the **guarded teardown** behind `/agent-workflow-kit uninstall` — classify each surface, preflight-then-mutate, never delete user-authored content), and `release-scan.mjs` (the attribution-off release gate). The bundled bridge skill mirrors live under [`bridges/`](bridges/) (byte-identical to the repo-root bridges, pinned by `test/bridges-mirror.test.mjs`). See [`tools/manifest/schema.md`](tools/manifest/schema.md).
+- [`tools/`](tools/) — the family-wide tooling the kit **owns and ships**: `manifest/{schema.md,validate.mjs}` (the `capability.json` schema + the validator the kit runs as the memory detector, and root CI invokes), `commands.mjs` (the canonical **command catalog** + the pure `routeInvocation` router behind `/agent-workflow-kit help` and the safe unknown-invocation routing rule — one source of truth for the command surface, drift-guarded against the `### Mode:` headers), `delegation.mjs` (the executable delegate/fallback decision + hand-off plan), `inject-methodology.mjs` + `engine-source.mjs` (the bounded **two-slot** reconciliation — ensure-slot / inject-if-empty / cap for the `workflow:methodology` **and** `workflow:orchestration` pointers; both fragments read **live** from the installed `agent-workflow-engine` via `engine-source.mjs` (`deps.rel` selects which) — the family's one source of truth, no bundled mirror; fail-loud when the engine is needed but absent, orchestration soft-skipped when it would bust the cap), `detect-backends.mjs` (the read-only **backend detector** behind `/agent-workflow-kit backends`, plus the axis-aware `guideFor`; exports the readiness consts the planner reuses), `recipes.mjs` (the read-only **recipe planner** behind `/agent-workflow-kit recipes` — `RECIPES` / `planRecipe` / `recommendRecipe` over the bridges' role vocabulary, drift-guarded against `provides`/`cost`/`quota` + an engine↔kit recipe-name parity guard; pure, never runs a subscription CLI; also exports the pure `ACTIVITIES` / `resolveActivityRecipe` activity-procedures resolver and the machine-composed one-line backend status — `composeStatusLine` behind `--status-line`, pasted verbatim by the bootstrap/upgrade report footers), `procedures.mjs` (the read-only **activity-procedures advisor** behind `/agent-workflow-kit procedures` — reads `references/procedures.md` live from the engine via `engine-source.mjs`, reads + validates the agent-writable `docs/ai/orchestration.json` via `orchestration-config.mjs`, and prints the steps + the resolved effective recipe per slot; drift-guarded activity/slot table vs the canon; read-only, never imports the writer, never runs a subscription CLI), `orchestration-config.mjs` (the config **schema/read/pure-transform core** — `loadConfig`/`validateConfig`/the shared slot-recipe validity + `parseOp`/`applySetOps`/`serializeConfig`/the canonical-refresh helpers; no fs writes), `orchestration-write.mjs` (the **only** config fs-writer — a deployment-gated, atomic, symlink/TOCTOU-safe `writeConfig`; imported by `set-recipe` alone, never by `procedures`), `set-recipe.mjs` (the **config writer** behind `/agent-workflow-kit set-recipe` — validate → merge → preview-by-default → write; never runs a backend, never commits), `setup-backends.mjs` (the **link-only** backend setup behind `/agent-workflow-kit setup` — place the bundled bridge + link wrappers), `fs-safe.mjs` (the shared symlink-traversal-safe copy/link/**remove/unlink** primitives that `setup-backends`, the npx installer, and the uninstaller use), `known-footprint.mjs` + `hide-footprint.mjs` (the **hidden-mode** registry + the single hide-writer behind step 9 / the upgrade reconcile — one managed block in the **project-local** `.git/info/exclude` covering the full AI/agent footprint; pinned by `known-footprint.test.mjs` drift-guard + `hide-footprint.test.mjs` / `.integration.test.mjs`), `family-registry.mjs` (the **unified family registry** behind `/agent-workflow-kit status` — aggregates every member's `capability.json`; pinned by a `family-registry.test.mjs` drift-guard), `uninstall.mjs` (the **guarded teardown** behind `/agent-workflow-kit uninstall` — classify each surface, preflight-then-mutate, never delete user-authored content), and `release-scan.mjs` (the attribution-off release gate). The bundled bridge skill mirrors live under [`bridges/`](bridges/) (byte-identical to the repo-root bridges, pinned by `test/bridges-mirror.test.mjs`). See [`tools/manifest/schema.md`](tools/manifest/schema.md).
 - [`capability.json`](capability.json) — the kit's own `agent-workflow` family manifest (`kind: composition-root`).
 - [`CHANGELOG.md`](CHANGELOG.md) — version history of this kernel.

package/bin/install.mjs

@@ -23,8 +23,10 @@
 // member — the memory substrate (`npx @sabaiway/agent-workflow-memory@latest init`, best-effort: a
 // failure is a loud DEGRADED success, never silent — skippable with `--no-memory`) and the
 // methodology engine the kit reads live (`npx @sabaiway/agent-workflow-engine@latest init`, fatal —
-// the live read STOPs without it — skippable with `--no-engine`). The bridges are NOT installed by
-// `init` (placed by `/agent-workflow-kit setup`). No tracking either way.
+// the live read STOPs without it — skippable with `--no-engine`). The bridges are never PLACED by
+// `init` (first placement stays `/agent-workflow-kit setup`, opt-in); once placed, `init` REFRESHES
+// them from this package's own bundled copies — a purely LOCAL copy, no third server contact —
+// skippable with `--no-bridges`. No tracking either way.
 //
 // Dependency-free, Node >= 18.
 
@@ -35,11 +37,22 @@ import { fileURLToPath } from 'node:url';
 import { homedir } from 'node:os';
 import { spawnSync } from 'node:child_process';
 import { copyTreeRefresh } from '../tools/fs-safe.mjs';
+// Dependency-free semver, shared with the family registry's bridge freshness probe (one leaf, no
+// second drifting copy). The null-on-unparseable contract is load-bearing here: legacy installs
+// predate any version stamp, so an unparseable side means "no gate", never a false ordering.
+import { compareSemver } from '../tools/semver-lite.mjs';
 // The ONE registry of family members (npm packages, kinds). The init-refresh cascade derives its
 // membership from this table — no second source of "who gets refreshed" — so it can't drift from the
 // manifests (a drift-guard test pins the derivation). Imported from the DATA LEAF (family-members.mjs),
-// NOT family-registry.mjs, so the npx cold-start path stays lean (no status/presenter graph pulled in).
+// NOT family-registry.mjs. Leanness note: the bridge-refresh driver below does pull in the backend
+// detector + the manifest validator (setup-backends' imports), but still NOT the status/presenter
+// graph (family-registry, renderers, recipes) — the npx cold-start path stays presenter-free.
 import { FAMILY_MEMBERS } from '../tools/family-members.mjs';
+// The refresh-only bridge driver (shared with `/agent-workflow-kit setup --refresh-placed` and the
+// upgrade reconcile): refreshes ONLY a bridge `setup` already placed — an absent bridge is a stated
+// skip (never a first placement, AD-009/AD-011) and a placed bridge newer than this kit's bundled
+// mirror is a stated skip too (never a downgrade). Every line it returns is tool-composed.
+import { refreshPlacedBridges } from '../tools/setup-backends.mjs';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const PKG_ROOT = resolve(__dirname, '..');
@@ -81,22 +94,6 @@ const readVersion = async () => {
   }
 };
 
-// Dependency-free semver: parse the leading `x.y.z` (prerelease/build ignored — kit versions are
-// plain). compareSemver returns -1 | 0 | 1, or null when either side is unparseable (legacy installs
-// predate any version stamp). No `let`: a small functional comparison (AGENTS.md §2.3).
-const parseSemver = (str) => {
-  const m = typeof str === 'string' ? str.trim().match(/^(\d+)\.(\d+)\.(\d+)/) : null;
-  return m ? [Number(m[1]), Number(m[2]), Number(m[3])] : null;
-};
-
-const compareSemver = (a, b) => {
-  const pa = parseSemver(a);
-  const pb = parseSemver(b);
-  if (!pa || !pb) return null;
-  const firstDiff = [0, 1, 2].map((i) => (pa[i] === pb[i] ? 0 : pa[i] < pb[i] ? -1 : 1)).find((c) => c !== 0);
-  return firstDiff ?? 0;
-};
-
 // Extract the version that is a DIRECT child of the top-level `metadata:` key — never a top-level
 // or deeper-nested decoy `version:` (mirrors the manifest validator's rigor; the kit ships manifest
 // fixtures that probe exactly those decoys). Pure string walk over the frontmatter block, no deps.
@@ -157,6 +154,7 @@ const parseArgs = (argv) => {
     noLaunchers: argv.includes('--no-launchers'),
     noMemory: argv.includes('--no-memory'),
     noEngine: argv.includes('--no-engine'),
+    noBridges: argv.includes('--no-bridges'),
     force: argv.includes('--force'),
     allowDowngrade: argv.includes('--allow-downgrade'),
     dir: dirFlag >= 0 ? argv[dirFlag + 1] : undefined,
@@ -278,7 +276,7 @@ const printHelp = (version) => {
   console.log(`agent-workflow-kit ${version}
 
 Usage:
-  npx @sabaiway/agent-workflow-kit@latest init [--dir <path>] [--no-launchers] [--no-memory] [--no-engine] [--force] [--allow-downgrade]
+  npx @sabaiway/agent-workflow-kit@latest init [--dir <path>] [--no-launchers] [--no-memory] [--no-engine] [--no-bridges] [--force] [--allow-downgrade]
   npx @sabaiway/agent-workflow-kit@latest --version
   npx @sabaiway/agent-workflow-kit@latest --help
 
@@ -294,8 +292,10 @@ Installs/refreshes the kit at ~/.claude/skills/agent-workflow-kit
   stale, refresh it yourself + restart — a miss is otherwise a non-fatal degraded success,
   never the engine's hard STOP); --no-engine skips the engine install (the live methodology
   read then STOPs until you install it by hand); --force replaces a pre-existing non-kit
-  launcher file (backed up first). The bridges are NOT installed by init (placed by
-  /agent-workflow-kit setup). init is additive — it never deletes your settings. If the
+  launcher file (backed up first). The bridges are never PLACED by init (first placement
+  stays /agent-workflow-kit setup, opt-in); once placed, init refreshes them from the kit's
+  own bundled copies — local files only, never a downgrade — and --no-bridges skips that
+  refresh. init is additive — it never deletes your settings. If the
   installed kit is newer than the version you ran, init refuses (no network — it compares
   the version on disk) and points you at @latest; --allow-downgrade overrides that
   refusal (distinct from --force, which is launcher-only).
@@ -376,15 +376,26 @@ const main = async () => {
       console.log(`[agent-workflow-kit] removed retired file ${tildify(retired)} (now read live from the engine).`);
     }
   }
-  console.log(`[agent-workflow-kit] ${wasPresent ? 'updated the kit to' : 'installed'} v${version} -> ${tildify(target)}`);
-
-  // No-op re-run: the install just refreshed the skill with the SAME version it already had. For a
-  // user who ran `init` expecting an upgrade, that almost always means npx reused a cached build —
-  // say so explicitly and point at @latest (the no-network signal that catches the reported scenario).
+  // Verb keyed on the OBSERVED version relation (cmp), never on mere presence: null (fresh install,
+  // or a legacy/unstamped one whose prior version is unknowable) → "installed"; -1 → a real update;
+  // 0 → already current (the copy still ran — see the note below); 1 is reachable only under
+  // --allow-downgrade (the gate above refused otherwise) and says so plainly. One message contract
+  // with the engine installer (same shapes, member noun differs).
+  const verb =
+    cmp === 0 ? 'refreshed the already-current kit'
+    : cmp === 1 ? 'downgraded the kit to'
+    : cmp === -1 ? 'updated the kit to'
+    : 'installed';
+  console.log(`[agent-workflow-kit] ${verb} v${version} -> ${tildify(target)}`);
+
+  // Same-version re-run: state observable facts only. The copy DID run (repair-on-rerun is a feature —
+  // it restores locally modified/deleted files), and whether npx served a cached build is NOT
+  // observable here (no network), so the note never claims it; the @latest hint is conditional.
   if (cmp === 0) {
     console.log(
-      `[agent-workflow-kit] note: no version change — the kit was already v${version}. If you expected ` +
-        `an update, npx likely served a cached build; re-run bypassing the cache:\n` +
+      `[agent-workflow-kit] note: the kit was already v${version} — the copy still ran, restoring ` +
+        `any locally modified or deleted kit file to this version's packaged contents. If you ` +
+        `expected a NEWER version, invoke the @latest tag explicitly:\n` +
         `    npx @sabaiway/agent-workflow-kit@latest init`,
     );
   }
@@ -404,6 +415,40 @@ const main = async () => {
     }
   }
 
+  // Placed-bridge refresh — AFTER the kit copy (the bundled bridges/ just landed), BEFORE the two
+  // network cascade steps (this one is LOCAL files only: bundle → placed copy). Refresh-only, so the
+  // AD-009/AD-011 honesty claim survives as "init never PLACES bridges; it refreshes what setup
+  // already placed" — an absent bridge is a stated skip, a placed-newer one a stated skip too (never
+  // a downgrade). Best-effort in the memory DEGRADED shape: any miss is a loud warning + a
+  // host-runnable recovery composed from the RESOLVED target (a --dir / AGENT_WORKFLOW_KIT_DIR
+  // install must get a line that runs) + exit 0 — never silent, never the engine's hard STOP.
+  const bridgeRefreshCmd = `node ${tildify(resolve(target, 'tools/setup-backends.mjs'))} --refresh-placed`;
+  if (args.noBridges) {
+    console.log(
+      `[agent-workflow-kit] --no-bridges: skipped refreshing the placed bridges. If one is stale, ` +
+        `refresh it yourself:\n    ${bridgeRefreshCmd}`,
+    );
+  } else if (process.platform === 'win32') {
+    console.log('[agent-workflow-kit] Windows: skipped the placed-bridge refresh (POSIX wrappers — refresh under WSL).');
+  } else {
+    console.log('[agent-workflow-kit] refreshing the bridges setup already placed (an absent bridge is never placed here):');
+    try {
+      const results = refreshPlacedBridges();
+      for (const r of results) console.log(r.line);
+      if (results.some((r) => r.outcome === 'failed')) {
+        console.warn(
+          `[agent-workflow-kit] could not refresh every placed bridge — continuing; the kit itself IS ` +
+            `installed and works. Re-run the refresh yourself:\n    ${bridgeRefreshCmd}`,
+        );
+      }
+    } catch (err) {
+      console.warn(
+        `[agent-workflow-kit] could not refresh the placed bridges (${err.message}) — continuing; the ` +
+          `kit itself IS installed and works. Re-run the refresh yourself:\n    ${bridgeRefreshCmd}`,
+      );
+    }
+  }
+
   // Memory substrate refresh — AFTER the kit + launchers, BEFORE the (fatal) engine and the success
   // block, so a returning `init` leaves no stale memory. Unlike the engine, a memory miss is a
   // DEGRADED success: warn with the exact recovery command + the on-disk version (read crash-proof)

package/bridges/antigravity-cli-bridge/SKILL.md

@@ -2,7 +2,7 @@
 name: antigravity-cli-bridge
 description: Delegate work to Google's Antigravity CLI (`agy`) — the successor to Gemini CLI — to reach Gemini, Claude, and GPT-OSS models under a Google AI Pro/Ultra subscription from the terminal. Use when the user wants to run a headless `agy` prompt, hand a focused task or second-opinion review to `agy`, install or authenticate Antigravity CLI, check or economise its quota/models, bridge project context into `agy`, set up a second delegated-execution backend beside Codex, or troubleshoot `agy` flags, models, auth, conversations, or its no-JSON headless behaviour.
 metadata:
-  version: '2.0.0'
+  version: '2.1.0'
 ---
 
 # antigravity-cli-bridge

package/bridges/antigravity-cli-bridge/bin/agy-review.sh

@@ -44,6 +44,41 @@
 #                            staging dir and pass it via --add-dir (re-enables Issue-001 stall risk)
 set -euo pipefail
 
+# --- --help / -h (pre-preflight: no agy, no login, no git tree needed) ---------
+# Keyed ONLY on the FIRST argument — never a scan of all args (uniform rule across
+# the four wrappers). Drift-guarded against capability.json roles.review.contract.
+case "${1:-}" in
+  --help|-h)
+    cat <<'HELP'
+agy-review — grounded read-only ADVISORY review by Google's Antigravity CLI (agy; subscription-only).
+
+Usage:
+  agy-review code [--facts @f] [--decided @f] [--focus "…"] [extra focus…]
+  agy-review plan <plan-file> [--facts @f] [--decided @f] [--focus "…"]
+  agy-review diff <diff-file> [--facts @f] [--decided @f] [--focus "…"]
+
+Flags:
+  --facts @f — verified facts the review runs AGAINST (omit ⇒ loud ungrounded-review warning)
+  --decided @f — already-decided / already-addressed list; do NOT re-raise (anti-circling; the round-2 payload)
+  --focus "…" — extra focus (repeatable; code mode also takes trailing focus words)
+
+Grounding:
+  grounded review — agy reads NOTHING by default, an ungrounded review GUESSES:
+  --facts @f = the verified facts to review AGAINST; --decided @f = decisions
+  already made, do NOT re-raise (anti-circling)
+
+Round-2 / resume:
+  agy-review --continue [--decided @f] [--focus "…"]
+  agy-review --conversation <id> [--decided @f] [--focus "…"]
+  (a continuation sends a small delta — agy holds the artifact server-side; --facts is invalid on a continuation)
+
+Closed grammar: unknown flags are rejected; no '--' passthrough (the only escapes are AGY_PROBE=1 and AGY_REVIEW_ALLOW_ADDDIR=1).
+Requires at run time: the agy CLI on PATH + a Google AI subscription login (--help needs neither).
+HELP
+    exit 0
+    ;;
+esac
+
 DEFAULT_AGY_REVIEW_MODEL="Gemini 3.1 Pro (High)"
 # `-` not `:-` so an EXPLICIT empty AGY_MODEL= survives (drop --model, use settings.json — agy.sh:52).
 AGY_MODEL="${AGY_MODEL-$DEFAULT_AGY_REVIEW_MODEL}"