@sabaiway/agent-workflow-kit 1.18.0 → 1.20.0

package/CHANGELOG.md

@@ -4,6 +4,47 @@ 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.20.0 — Fallback-template lens + the cross-package lens-mirror guard (kit)
+
+A **feature** release. The kit's fallback `agent_rules.md` template gains the **§2.5 Right-altitude &
+code-grounded** lens (byte-identical to memory's §2.6 block), and a new cross-package
+`test/lens-mirror.test.mjs` ties the shared lens vocabulary across the engine canon (`planning.md` +
+`procedures.md`) AND both `agent_rules.md` templates: each distinctive token must survive in every file's
+lens **region**, and the two template blocks must stay byte-identical apart from the heading number. The
+deployment-lineage head stays **`1.3.0`** (no `docs/ai` structural change, no migration); the kit
+**package** version is a separate axis.
+
+- **Non-vacuous guard.** Deleting the lens block (or a distinctive token) from any of the four files
+  fails the guard — proven by an injected-divergence dry-run.
+
+## 1.19.0 — One-command freshness: `init` refreshes memory too, and a capability-adaptive `status` (kit)
+
+A **feature** release that closes the returning-user gap and modernizes the status surface. The
+deployment-lineage head stays **`1.3.0`** (no `docs/ai` structural change, no migration); the kit
+**package** version is a separate axis.
+
+- **`init` now leaves no stale core member.** After installing/refreshing the kit, `npx
+  @sabaiway/agent-workflow-kit@latest init` also refreshes the **memory substrate** and the
+  **methodology engine** over npm — so a returning user is no longer left with silently stale memory.
+  The memory refresh is **best-effort: a miss is a loud DEGRADED success** — a warning with the exact
+  recovery command (and the on-disk version) plus **exit 0**, never a silent skip and never the engine's
+  hard STOP. New **`--no-memory`** flag skips it for air-gapped/scripted installs. The cascade
+  membership is derived from the one family registry and drift-guarded; bridges are still placed by
+  `setup`, never by `init`.
+- **Capability-adaptive `status` output.** The direct-CLI status view (`node tools/family-registry.mjs`)
+  is rebuilt as a `surface → view-model → renderers` pipeline: it auto-detects the terminal (plain vs
+  ANSI, color via `NO_COLOR`/`FORCE_COLOR`, width with a 40-col floor, ASCII-glyph fallback) and renders
+  all four blocks (members · bridges · project deploy/visibility · settings). `--format=<auto|plain|ansi|json>`
+  (with `--json` as sugar) selects the surface; unknown flags and a missing `--dir` value now **reject
+  loudly** instead of being silently ignored.
+- **Additive `--json` freshness signal.** Each `installed[]` entry gains a structural `refresh`
+  `{ behind, recommend }` object (derived from the registry, never parsed from a caveat). The
+  agent-mediated `/agent-workflow-kit status` reads it to show a localized "needs refresh" label + the
+  exact command **once**; every existing envelope field is unchanged.
+- **Docs.** Install help + READMEs document the memory/engine refresh, `--no-memory`, the degraded-success
+  recovery, and that bridges are not installed by `init`. Tarball **75 → 81** (the pure member-table leaf
+  + five status-presenter modules).
+
 ## 1.18.0 — Agent-writable orchestration config (`set-recipe`), version-aware setup, durable session contracts (kit)
 
 A **feature** release. The per-project recipe config (`docs/ai/orchestration.json`) is no longer

package/README.md

@@ -194,20 +194,25 @@ other agent). The manual path works identically but **isn't reflected in install
 <details>
 <summary><b>What <code>init</code> touches — and how to undo it</b></summary>
 
-`init` is **additive — it never deletes your settings.** It writes only its own namespaced slots:
+`init` is **additive — it never deletes your settings.** It writes its own namespaced slots, then
+refreshes the other npm core members so a returning `init` leaves **no stale core member**:
 
 | Path | What |
 |------|------|
 | `~/.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` |
 | `~/.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 |
 
-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).
+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
+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).
 
-**Uninstall:** delete the slots above (the kit folder, the symlink, the workflow file).
+**Uninstall:** delete the slots above (the kit / memory / engine folders, the symlink, the workflow
+file), or run the guarded `/agent-workflow-kit uninstall`.
 </details>
 
 ---

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.18.0'
+  version: '1.20.0'
 ---
 
 # agent-workflow-kit
@@ -28,6 +28,10 @@ when it is present and healthy, and otherwise uses its **own bundled copy** (`re
 memory substrate**. (The methodology slot is a separate axis: its fragment is read **live from the
 installed `agent-workflow-engine`**, which `npx @sabaiway/agent-workflow-kit@latest init` installs — a
 runtime dependency placed by `init` and read live; see *Methodology slot reconciliation* below.)
+`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`).
 
 **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
@@ -336,7 +340,9 @@ 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 — the version block** (from `installed[]` + `deploymentHead`): the deployment-structure head, the installed package versions by `display`, the two-axes disambiguation, plus any member `notes` (e.g. a behind member's refresh+restart line). This is the shared version block above.
+1. **Versions — a status-only render from `installed[]` + `deploymentHead`** (this is **NOT** the shared notes-based version block — see the separation note below): the deployment-structure 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"*).
+
+> **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.
 3. **Settings (`--dir`, one line each)** (from `project.settings`):
    - **recipes** — the effective recipe per slot (detail → `/agent-workflow-kit procedures` / `recipes`); a `recipes.detectError` → say the backends couldn't be checked, so recipes floored at solo.

package/bin/install.mjs

@@ -18,9 +18,13 @@
 // compares the version already on disk (the installed SKILL.md) against this runner's own version,
 // never the registry — which is why `@latest` (above) is the documented form: a bare `npx … init`
 // can reuse an OLDER cached build of this installer, so a returning user must bypass the cache to
-// actually upgrade (see decisions.md AD-012). One step DOES contact a server: `init` fetches and
-// installs the methodology engine the kit reads live (`npx @sabaiway/agent-workflow-engine@latest
-// init`), skippable with `--no-engine` (Plan 3D / AD-016). No tracking either way.
+// actually upgrade (see decisions.md AD-012). Two steps DO contact a server: after the kit copy,
+// `init` cascades the other npm-installable CORE members so a returning run leaves NO stale core
+// 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.
 //
 // Dependency-free, Node >= 18.
 
@@ -31,6 +35,11 @@ import { fileURLToPath } from 'node:url';
 import { homedir } from 'node:os';
 import { spawnSync } from 'node:child_process';
 import { copyTreeRefresh } from '../tools/fs-safe.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).
+import { FAMILY_MEMBERS } from '../tools/family-members.mjs';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const PKG_ROOT = resolve(__dirname, '..');
@@ -146,6 +155,7 @@ const parseArgs = (argv) => {
     help: argv.includes('--help') || argv.includes('-h'),
     version: argv.includes('--version') || argv.includes('-v'),
     noLaunchers: argv.includes('--no-launchers'),
+    noMemory: argv.includes('--no-memory'),
     noEngine: argv.includes('--no-engine'),
     force: argv.includes('--force'),
     allowDowngrade: argv.includes('--allow-downgrade'),
@@ -153,47 +163,72 @@ const parseArgs = (argv) => {
   };
 };
 
-// Mandatory engine install (Plan 3D / AD-016). The kit reads the methodology fragment LIVE from the
-// installed agent-workflow-engine, so init places it as a CORE part of the kit (not an optional
-// execution-backend — this deliberately diverges from AD-011 §5). It is fetched over npm, consistent
-// with the kit's own npx install context; NO engine canon is bundled into the kit (that would
-// re-create the mirror Plan 3D deletes). --no-engine skips it for air-gapped/scripted installs.
-export const ENGINE_PACKAGE = '@sabaiway/agent-workflow-engine';
-
-// The exact command + argv to install the engine. Windows resolution: spawn `npx.cmd` on win32,
-// `npx` elsewhere, WITHOUT shell:true (no shell-parse overhead/inconsistency; the repo has no
-// npx-spawn precedent to inherit a shell from). Pure → unit-tested in-process, no network.
-export const engineInstallArgv = (platform) => ({
+// Init-refresh cascade (Plan 3D / AD-016 for the engine; the memory cascade closes the
+// returning-user "no stale core member" journey). After the kit copy, init refreshes the OTHER
+// npm-installable CORE members — the memory substrate + the methodology engine — each over npm,
+// consistent with the kit's own npx install context (NO engine/memory canon is bundled into the kit;
+// that would re-create the mirror Plan 3D deletes). The npm package names are read from the ONE
+// registry (FAMILY_MEMBERS) so there is no second source of truth. --no-memory / --no-engine skip
+// each for air-gapped/scripted installs.
+const npmFor = (name) => {
+  const member = FAMILY_MEMBERS.find((m) => m.name === name);
+  if (!member?.npm) throw new Error(`[agent-workflow-kit] no npm package registered for ${name}`);
+  return member.npm;
+};
+export const ENGINE_PACKAGE = npmFor('agent-workflow-engine');
+export const MEMORY_PACKAGE = npmFor('agent-workflow-memory');
+
+// The npm-installable core members the cascade refreshes, DERIVED from FAMILY_MEMBERS (every npm
+// member that is neither the kit — the composition root this very runner installs — nor an
+// execution-backend, which `setup` places, not init). Order + policy are part of the contract:
+// NON-FATAL first (memory — a miss is a degraded success), then FATAL (engine — the live methodology
+// read STOPs without it), so a hard engine failure never pre-empts the best-effort memory refresh.
+// A drift-guard test pins this derivation, so adding a future npm core member can't silently bypass
+// the cascade. Per-member messaging stays explicit in main() (the degraded-vs-STOP wording differs).
+const FATAL_KINDS = new Set(['methodology-engine']);
+export const cascadePlan = () =>
+  FAMILY_MEMBERS
+    .filter((m) => m.npm && m.kind !== 'execution-backend' && m.name !== 'agent-workflow-kit')
+    .map((m) => ({ name: m.name, npm: m.npm, fatal: FATAL_KINDS.has(m.kind) }))
+    .sort((a, b) => Number(a.fatal) - Number(b.fatal)); // non-fatal (memory) before fatal (engine)
+
+// The exact command + argv to install a member over npx. Windows resolution: spawn `npx.cmd` on
+// win32, `npx` elsewhere, WITHOUT shell:true (no shell-parse overhead/inconsistency; the repo has no
+// npx-spawn precedent to inherit a shell from). `@latest` exactly — never a pinned version, so the
+// cascade always fetches the newest published member. Pure → unit-tested in-process, no network.
+export const memberInstallArgv = (npmPackage, platform) => ({
   command: platform === 'win32' ? 'npx.cmd' : 'npx',
-  args: [`${ENGINE_PACKAGE}@latest`, 'init'],
+  args: [`${npmPackage}@latest`, 'init'],
   options: { stdio: 'inherit' }, // note: no `shell: true`
 });
+export const engineInstallArgv = (platform) => memberInstallArgv(ENGINE_PACKAGE, platform);
+export const memoryInstallArgv = (platform) => memberInstallArgv(MEMORY_PACKAGE, platform);
 
 // The default runner — the only place that actually spawns. Injected in tests so the suite never
 // hits the network.
-const spawnEngine = ({ command, args, options }) => spawnSync(command, args, options);
+const spawnMember = ({ command, args, options }) => spawnSync(command, args, options);
 
 // Synchronous backoff before the single retry. The common first-attempt failure is a TRANSIENT
 // npm/network blip (rate-limit, registry hiccup, momentary DNS) — an immediate retry tends to hit the
 // same blip, so wait briefly first. Atomics.wait is a dependency-free sync sleep (the install flow is
 // already synchronous here). Injected in tests as a 0ms no-op so the suite never actually sleeps.
-const ENGINE_RETRY_DELAY_MS = 1500;
+const RETRY_DELAY_MS = 1500;
 const sleepSync = (ms) => {
   if (ms > 0) Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
 };
 
 // D1 failure policy: attempt → wait → retry-once → fail. Retry exactly once before giving up. Pure
 // aside from the injected runner/sleep; returns { ok } so the caller prints the loud manual-recovery
-// message + nonzero exit on a hard failure (the kit is already on disk — recovery is one step; never
-// a silent skip).
-export const installEngine = (platform, runner, { sleep = sleepSync, retryDelayMs = ENGINE_RETRY_DELAY_MS } = {}) => {
-  const descriptor = engineInstallArgv(platform);
-  const ranOk = (label) => {
+// message (the engine's nonzero exit, the memory's degraded warning) on a hard failure (the kit is
+// already on disk — recovery is one step; never a silent skip). `label` names the member in the
+// per-attempt warning (e.g. "methodology engine", "memory substrate").
+const installMember = (label, descriptor, runner, { sleep = sleepSync, retryDelayMs = RETRY_DELAY_MS } = {}) => {
+  const ranOk = (attempt) => {
     const res = runner(descriptor);
     const ok = (res?.status ?? 1) === 0 && !res?.error;
     if (!ok) {
       const why = res?.error ? `: ${res.error.message}` : ` (exit ${res?.status ?? 'unknown'})`;
-      console.warn(`[agent-workflow-kit] methodology engine install ${label} failed${why}.`);
+      console.warn(`[agent-workflow-kit] ${label} install ${attempt} failed${why}.`);
     }
     return ok;
   };
@@ -203,17 +238,47 @@ export const installEngine = (platform, runner, { sleep = sleepSync, retryDelayM
   return { ok: false };
 };
 
+export const installEngine = (platform, runner, opts = {}) =>
+  installMember('methodology engine', engineInstallArgv(platform), runner, opts);
+export const installMemory = (platform, runner, opts = {}) =>
+  installMember('memory substrate', memoryInstallArgv(platform), runner, opts);
+
 const resolveTarget = (dirArg) => {
   if (dirArg) return resolve(dirArg);
   if (process.env.AGENT_WORKFLOW_KIT_DIR) return resolve(process.env.AGENT_WORKFLOW_KIT_DIR);
   return resolve(homedir(), '.claude/skills/agent-workflow-kit');
 };
 
+// Where the memory substrate lives — its env override else its home-relative default, both read from
+// the ONE registry (FAMILY_MEMBERS), expanding a leading `~/`. Used only by the DEGRADED warning to
+// report the on-disk memory version after a refresh miss (init never WRITES here — that is memory's
+// own installer's job). getenv/home injectable for hermetic tests.
+const resolveMemoryTarget = (getenv = process.env, home = homedir()) => {
+  const member = FAMILY_MEMBERS.find((m) => m.name === 'agent-workflow-memory');
+  const envDir = getenv[member.installed.env];
+  if (envDir) return resolve(envDir);
+  const dflt = member.installed.default;
+  return dflt.startsWith('~/') ? resolve(home, dflt.slice(2)) : resolve(dflt);
+};
+
+// Crash-proof on-disk version read for the degraded memory warning: readInstalledVersion returns null
+// for an ABSENT SKILL.md and THROWS for a present-but-UNREADABLE one — but the warning must NEVER
+// become fatal, so any throw is swallowed to null here. Both branches (absent → null directly,
+// unreadable → caught → null) keep the warning best-effort and exit 0 (degraded success, no silent
+// skip). Returns the semver string or null.
+export const readMemberVersionSafe = async (dir) => {
+  try {
+    return await readInstalledVersion(dir);
+  } catch {
+    return null;
+  }
+};
+
 const printHelp = (version) => {
   console.log(`agent-workflow-kit ${version}
 
 Usage:
-  npx @sabaiway/agent-workflow-kit@latest init [--dir <path>] [--no-launchers] [--no-engine] [--force] [--allow-downgrade]
+  npx @sabaiway/agent-workflow-kit@latest init [--dir <path>] [--no-launchers] [--no-memory] [--no-engine] [--force] [--allow-downgrade]
   npx @sabaiway/agent-workflow-kit@latest --version
   npx @sabaiway/agent-workflow-kit@latest --help
 
@@ -222,11 +287,15 @@ Use the @latest form: a bare \`npx … init\` (no @latest) can reuse an OLDER ca
 
 Installs/refreshes the kit at ~/.claude/skills/agent-workflow-kit
   (override with --dir <path> or AGENT_WORKFLOW_KIT_DIR), then wires any
-  Codex / Devin Desktop you have, then installs the methodology engine the kit reads
-  live (npx ${ENGINE_PACKAGE}@latest init). --no-launchers skips the
-  launcher wiring; --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). init is additive — it never deletes your settings. If the
+  Codex / Devin Desktop you have, then refreshes the other npm core members so no stale
+  one is left behind: the memory substrate (npx ${MEMORY_PACKAGE}@latest init)
+  and the methodology engine the kit reads live (npx ${ENGINE_PACKAGE}@latest init).
+  --no-launchers skips the launcher wiring; --no-memory skips the memory refresh (if it is
+  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
   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).
@@ -335,9 +404,35 @@ const main = async () => {
     }
   }
 
-  // Mandatory engine install — AFTER the kit + launchers but BEFORE the success block, so a failure
-  // never first claims everything succeeded. The kit reads the methodology fragment live from the
-  // installed engine; this places it (over npm, no canon bundled into the kit). --no-engine opts out.
+  // 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)
+  // and keep exit 0 — never silently skip (Hard Constraint), never the engine's hard STOP.
+  const memoryCmd = `npx ${MEMORY_PACKAGE}@latest init`;
+  if (args.noMemory) {
+    console.log(
+      `[agent-workflow-kit] --no-memory: skipped refreshing the memory substrate. If it is stale, ` +
+        `refresh it yourself and restart the session:\n    ${memoryCmd}`,
+    );
+  } else {
+    console.log(`[agent-workflow-kit] refreshing the memory substrate: ${memoryCmd}`);
+    const memory = installMemory(process.platform, spawnMember);
+    if (memory.ok) {
+      console.log('[agent-workflow-kit] memory substrate refreshed.');
+    } else {
+      const onDisk = await readMemberVersionSafe(resolveMemoryTarget());
+      const where = onDisk ? `on disk: v${onDisk}` : 'not found on disk';
+      console.warn(
+        `[agent-workflow-kit] could not refresh the memory substrate (${where}) — continuing; the ` +
+          `kit itself IS installed and works. To get the latest memory, run it yourself and restart ` +
+          `the session:\n    ${memoryCmd}`,
+      );
+    }
+  }
+
+  // Mandatory engine install — AFTER the kit + launchers + memory but BEFORE the success block, so a
+  // failure never first claims everything succeeded. The kit reads the methodology fragment live from
+  // the installed engine; this places it (over npm, no canon bundled into the kit). --no-engine opts out.
   const engineCmd = `npx ${ENGINE_PACKAGE}@latest init`;
   if (args.noEngine) {
     console.log(
@@ -347,7 +442,7 @@ const main = async () => {
     );
   } else {
     console.log(`[agent-workflow-kit] installing the methodology engine the kit reads live: ${engineCmd}`);
-    const engine = installEngine(process.platform, spawnEngine);
+    const engine = installEngine(process.platform, spawnMember);
     if (!engine.ok) {
       // D1: two attempts failed → loud error + concrete recommendations + nonzero exit. The kit IS on
       // disk, so recovery is one step. Never a silent skip (Hard Constraint: no silent failures).

package/capability.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sabaiway/agent-workflow-kit",
-  "version": "1.18.0",
+  "version": "1.20.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/templates/agent_rules.md

@@ -61,6 +61,11 @@ Before proposing changes or committing, review against:
 ### 2.4. Quality Gates
 - Always run type-checker, linter, and all tests before committing.
 
+### 2.5. Right-altitude & code-grounded (planning + review)
+- **Fold by code, not prose.** Before folding a code-touching finding into a plan or change, read the cited `file:line` and cite it — a prose fold drifts from the code and seeds the next bug.
+- **Right altitude.** Pin intent + invariants + acceptance criteria (named tests); leave fine code-mechanics to Execute, where prose cannot diverge from reality.
+- **Convergence heuristic.** When a review round keeps finding mechanism issues on a stable architecture, stop refining prose — raise the altitude or hand it to Execute. (Full canon: the project's planning methodology / workflow-methodology canon.)
+
 ---
 
 ## 3. Token & Session Optimization

package/tools/family-members.mjs

@@ -0,0 +1,67 @@
+// family-members.mjs — the pure DATA LEAF: the one authoritative table of agent-workflow family members.
+//
+// Extracted from family-registry.mjs so the two consumers that only need the static table — the npx
+// installer (bin/install.mjs, which derives its init-refresh cascade from it) and family-registry
+// itself — can import the DATA without dragging in the whole status/presenter graph
+// (detect-backends, the manifest validator, hide-footprint, engine-source, recipes, the renderers …).
+// install.mjs runs on the npx cold-start hot path, so the leaner import matters; single-source-of-truth
+// + the drift-guard (family-registry.test.mjs pins FAMILY_MEMBERS to the 5 in-repo capability.json)
+// are preserved — the table just lives in a dependency-free leaf now.
+//
+// Pure data, no imports, no side effects, Node >= 18.
+
+// ── the unified registry ───────────────────────────────────────────────────────
+// One entry per family member. `installed` is the detect.installed spec (env + home-relative default
+// + marker file); `deployed` is the project-relative stamp a deploy writes (kit + memory only);
+// `npm` is the install package (null for the bridges, which are placed by `setup`, not npm);
+// `wrapperCmds` is the deduped roles[].cmd set the `setup` linker creates on PATH (bridges only).
+// Kept in lockstep with the 5 in-repo capability.json by the drift-guard test. The two release skills
+// (release-engineering / release-marketing) are deliberately NOT here — they are not family members
+// (AD-013): no capability.json, not in the kit tarball, not in the role vocabulary.
+export const FAMILY_MEMBERS = [
+  {
+    name: 'agent-workflow-kit',
+    kind: 'composition-root',
+    installed: { env: 'AGENT_WORKFLOW_KIT_DIR', default: '~/.claude/skills/agent-workflow-kit', file: 'SKILL.md' },
+    deployed: { file: 'docs/ai/.workflow-version' },
+    npm: '@sabaiway/agent-workflow-kit',
+    wrapperCmds: [],
+  },
+  {
+    name: 'agent-workflow-memory',
+    kind: 'memory-substrate',
+    installed: { env: 'AGENT_WORKFLOW_MEMORY_DIR', default: '~/.claude/skills/agent-workflow-memory', file: 'SKILL.md' },
+    deployed: { file: 'docs/ai/.memory-version' },
+    npm: '@sabaiway/agent-workflow-memory',
+    wrapperCmds: [],
+  },
+  {
+    name: 'agent-workflow-engine',
+    kind: 'methodology-engine',
+    installed: { env: 'AGENT_WORKFLOW_ENGINE_DIR', default: '~/.claude/skills/agent-workflow-engine', file: 'SKILL.md' },
+    deployed: null,
+    npm: '@sabaiway/agent-workflow-engine',
+    wrapperCmds: [],
+  },
+  {
+    name: 'codex-cli-bridge',
+    kind: 'execution-backend',
+    installed: { env: 'CODEX_CLI_BRIDGE_DIR', default: '~/.claude/skills/codex-cli-bridge', file: 'SKILL.md' },
+    deployed: null,
+    npm: null,
+    wrapperCmds: ['codex-exec', 'codex-review'],
+  },
+  {
+    name: 'antigravity-cli-bridge',
+    kind: 'execution-backend',
+    installed: { env: 'ANTIGRAVITY_CLI_BRIDGE_DIR', default: '~/.claude/skills/antigravity-cli-bridge', file: 'SKILL.md' },
+    deployed: null,
+    npm: null,
+    wrapperCmds: ['agy-run'],
+  },
+];
+
+// A GLOBAL skill (lives under ~/.claude/skills) may be shared by other projects on the host — the
+// uninstaller warns before removing one (there is no cross-project dependency tracking). All current
+// members are global skills; the field is explicit so the warning is data-driven, not hardcoded.
+export const isGlobalSkill = (member) => member.kind !== undefined; // every member is a global skill today

package/tools/family-registry.mjs

@@ -41,73 +41,52 @@ import {
   readSettingsFile,
   resolveEffectiveMode,
 } from './velocity-profile.mjs';
-
-// ── manifestState values (the detect-backends precedence, generalized to any member kind) ──────────
-export const NOT_INSTALLED = 'not-installed';
-export const UNSUPPORTED_SCHEMA = 'unsupported-schema';
-export const INVALID_MANIFEST = 'invalid-manifest';
-export const STUB = 'stub';
-export const FOREIGN = 'foreign';
-export const OK = 'ok';
-// The marker could not be probed (a non-ENOENT fs error — EACCES/EIO). Surfaced explicitly instead of
-// being masked as not-installed (no silent failure); uninstall treats it as "do not touch" (skip).
-export const UNKNOWN = 'unknown';
+// The status vocabulary (manifestState constants, internal→public maps, display names, the no-leak
+// forbidden set) lives in the frozen labels.mjs LEAF (Plan §4.2 B1) so the import graph is acyclic —
+// nothing imports family-registry for vocabulary. Imported here for internal use; the public subset is
+// re-exported below.
+import {
+  NOT_INSTALLED,
+  UNSUPPORTED_SCHEMA,
+  INVALID_MANIFEST,
+  STUB,
+  FOREIGN,
+  OK,
+  UNKNOWN,
+  STATE_PUBLIC,
+  VISIBILITY_PUBLIC,
+  DISPLAY_NAMES,
+  displayOf,
+} from './labels.mjs';
+// The capability-adaptive direct-CLI presenter (Plan §4.2/§4.5): the surface detector, the
+// envelope→ViewModel transform, and the plain/ansi renderers. main() composes them; the agent-mediated
+// `status` surface ignores them (it consumes --json). These are leaves — no import cycle.
+import { detectSurface } from './surface.mjs';
+import { toViewModel } from './view-model.mjs';
+import { render } from './renderers.mjs';
+
+// ── manifestState values — re-export the EXACT public subset family-registry exported before B1 ─────
+// (the 7 state constants + DISPLAY_NAMES) so every existing importer (uninstall.mjs, the test suites)
+// stays green. STATE_PUBLIC / VISIBILITY_PUBLIC / displayOf were private here and are NOT re-exported.
+export {
+  NOT_INSTALLED,
+  UNSUPPORTED_SCHEMA,
+  INVALID_MANIFEST,
+  STUB,
+  FOREIGN,
+  OK,
+  UNKNOWN,
+  DISPLAY_NAMES,
+};
 
 // ── the unified registry ───────────────────────────────────────────────────────
-// One entry per family member. `installed` is the detect.installed spec (env + home-relative default
-// + marker file); `deployed` is the project-relative stamp a deploy writes (kit + memory only);
-// `npm` is the install package (null for the bridges, which are placed by `setup`, not npm);
-// `wrapperCmds` is the deduped roles[].cmd set the `setup` linker creates on PATH (bridges only).
-// Kept in lockstep with the 5 in-repo capability.json by the drift-guard test. The two release skills
-// (release-engineering / release-marketing) are deliberately NOT here — they are not family members
-// (AD-013): no capability.json, not in the kit tarball, not in the role vocabulary.
-export const FAMILY_MEMBERS = [
-  {
-    name: 'agent-workflow-kit',
-    kind: 'composition-root',
-    installed: { env: 'AGENT_WORKFLOW_KIT_DIR', default: '~/.claude/skills/agent-workflow-kit', file: 'SKILL.md' },
-    deployed: { file: 'docs/ai/.workflow-version' },
-    npm: '@sabaiway/agent-workflow-kit',
-    wrapperCmds: [],
-  },
-  {
-    name: 'agent-workflow-memory',
-    kind: 'memory-substrate',
-    installed: { env: 'AGENT_WORKFLOW_MEMORY_DIR', default: '~/.claude/skills/agent-workflow-memory', file: 'SKILL.md' },
-    deployed: { file: 'docs/ai/.memory-version' },
-    npm: '@sabaiway/agent-workflow-memory',
-    wrapperCmds: [],
-  },
-  {
-    name: 'agent-workflow-engine',
-    kind: 'methodology-engine',
-    installed: { env: 'AGENT_WORKFLOW_ENGINE_DIR', default: '~/.claude/skills/agent-workflow-engine', file: 'SKILL.md' },
-    deployed: null,
-    npm: '@sabaiway/agent-workflow-engine',
-    wrapperCmds: [],
-  },
-  {
-    name: 'codex-cli-bridge',
-    kind: 'execution-backend',
-    installed: { env: 'CODEX_CLI_BRIDGE_DIR', default: '~/.claude/skills/codex-cli-bridge', file: 'SKILL.md' },
-    deployed: null,
-    npm: null,
-    wrapperCmds: ['codex-exec', 'codex-review'],
-  },
-  {
-    name: 'antigravity-cli-bridge',
-    kind: 'execution-backend',
-    installed: { env: 'ANTIGRAVITY_CLI_BRIDGE_DIR', default: '~/.claude/skills/antigravity-cli-bridge', file: 'SKILL.md' },
-    deployed: null,
-    npm: null,
-    wrapperCmds: ['agy-run'],
-  },
-];
-
-// A GLOBAL skill (lives under ~/.claude/skills) may be shared by other projects on the host — the
-// uninstaller warns before removing one (there is no cross-project dependency tracking). All current
-// members are global skills; the field is explicit so the warning is data-driven, not hardcoded.
-export const isGlobalSkill = (member) => member.kind !== undefined; // every member is a global skill today
+// FAMILY_MEMBERS (+ isGlobalSkill) is the one authoritative member table. It moved to the
+// dependency-free DATA LEAF family-members.mjs so the npx installer can derive its init-refresh cascade
+// from the table WITHOUT importing this whole status/presenter graph (a leaner npx cold-start path).
+// Re-exported here so every existing importer (uninstall.mjs, the test suites) stays green, and the
+// drift-guard (family-registry.test.mjs) still pins the table to the 5 in-repo capability.json.
+export { FAMILY_MEMBERS, isGlobalSkill } from './family-members.mjs';
+import { FAMILY_MEMBERS } from './family-members.mjs';
 
 // ── pure probes ──────────────────────────────────────────────────────────────────
 // Wrapped marker probe → 'present' (a regular file) | 'absent' (ENOENT / not a regular file) |
@@ -268,62 +247,10 @@ export const surveyProject = (projectDir, deps = {}) => {
 };
 
 // ── report ───────────────────────────────────────────────────────────────────────
-const pad = (s, n) => (s.length >= n ? s : s + ' '.repeat(n - s.length));
-
-// The human (non-JSON) settings render. A dev view — the agent consumes `--json` + renders in plain
-// language (Mode: status). Each area shows its `error` field loudly when one fired.
-const formatSettings = (s) => {
-  const out = ['', 'settings'];
-  if (s.recipes?.error) out.push(`  ${pad('recipes', 14)}error: ${s.recipes.error}`);
-  else {
-    const parts = [];
-    for (const [act, slots] of Object.entries(s.recipes?.activities ?? {})) {
-      for (const [slot, r] of Object.entries(slots)) parts.push(`${act}.${slot}=${r.recipe}`);
-    }
-    out.push(`  ${pad('recipes', 14)}${parts.join(' · ') || '—'}`);
-    if (s.recipes?.detectError) out.push(`  ${pad('', 14)}↳ couldn't check backends (${s.recipes.detectError}); recipes floored at solo`);
-  }
-  if (s.attribution?.error) out.push(`  ${pad('attribution', 14)}error: ${s.attribution.error}`);
-  else out.push(`  ${pad('attribution', 14)}includeCoAuthoredBy effective=${String(s.attribution?.effective)}`);
-  if (s.velocity?.error) out.push(`  ${pad('velocity', 14)}error: ${s.velocity.error}`);
-  else out.push(`  ${pad('velocity', 14)}defaultMode=${String(s.velocity?.defaultMode)} · allow project/local=${s.velocity?.allowEntries?.project}/${s.velocity?.allowEntries?.local}`);
-  return out;
-};
-
-export const formatStatus = (family, project = null, extras = {}) => {
-  const lines = ['agent-workflow family — installed skills (skill axis)', ''];
-  for (const m of family) {
-    const ver = m.version ? `v${m.version}` : '—';
-    lines.push(`  ${pad(m.name, 26)}[${pad(m.manifestState, 16)}] ${pad(ver, 10)} ${m.kind}`);
-    for (const c of m.caveats ?? []) lines.push(`      ↳ ${c}`);
-  }
-  if (extras.bridges) {
-    const WRAP_MARK = { present: '✓', missing: '✗', unknown: '?' };
-    lines.push('', 'execution backends (host)', '');
-    for (const b of extras.bridges) {
-      const w = b.wrappers.map((x) => `${x.cmd} ${WRAP_MARK[x.state] ?? '?'}`).join(', ') || '—';
-      lines.push(`  ${pad(b.display, 20)}${pad(b.readiness, 18)}wrappers: ${w}`);
-    }
-  }
-  if (project) {
-    lines.push('', `project deployment (${project.dir})`, '');
-    if (!project.deployed) {
-      lines.push('  no agent-workflow deployment detected here (no docs/ai, no version stamp).');
-    } else {
-      for (const s of project.stamps) {
-        lines.push(`  ${pad(s.file, 26)}${s.version ?? '—'}`);
-      }
-      lines.push(`  ${pad('docs/ai present', 26)}${project.docsAiPresent ? 'yes' : 'no'}`);
-      if (extras.visibility) {
-        lines.push(`  ${pad('visibility', 26)}${extras.visibility.error ? `error: ${extras.visibility.error}` : extras.visibility.state}`);
-      } else {
-        lines.push(`  ${pad('hidden-mode fence', 26)}${project.hiddenFence ? 'present' : 'absent'}`);
-      }
-    }
-    if (extras.settings) lines.push(...formatSettings(extras.settings));
-  }
-  return lines.join('\n');
-};
+// The direct-CLI human render (formatStatus + formatSettings) was REPLACED by the capability-adaptive
+// presenter pipeline (surface → view-model → renderers, Plan §4.2/§4.5): main() builds the no-leak
+// envelope once, then renders it via toViewModel + render (plain/ansi) or prints it as JSON. ONE data
+// source for both surfaces — the agent-mediated `status` consumes `--json`, the direct CLI renders it.
 
 // ── the no-leak --json envelope ──────────────────────────────────────────────────
 // A machine-readable view with USER-SAFE field names only — NEVER the internal manifestState /
@@ -331,28 +258,8 @@ export const formatStatus = (family, project = null, extras = {}) => {
 // consumes THIS, never the human table verbatim. An envelope-shape test pins its shape so later phases
 // (the settings/visibility block) can't silently break the Phase-2 version consumer.
 
-// internal manifestState → a STABLE, user-safe token (SKILL.md owns the value→plain-language phrasing).
-// Deliberately NOT the internal literals (foreign/stub/…): those must never leak past this boundary.
-const STATE_PUBLIC = {
-  [OK]: 'installed',
-  [NOT_INSTALLED]: 'absent',
-  [FOREIGN]: 'other-tool',
-  [STUB]: 'placeholder',
-  [INVALID_MANIFEST]: 'invalid',
-  [UNSUPPORTED_SCHEMA]: 'unsupported',
-  [UNKNOWN]: 'uncheckable',
-};
-
-// Short, user-facing labels for the version block (kit · memory · engine · codex-bridge · …), so the
-// render is deterministic and the agent never invents a label.
-export const DISPLAY_NAMES = {
-  'agent-workflow-kit': 'kit',
-  'agent-workflow-memory': 'memory',
-  'agent-workflow-engine': 'engine',
-  'codex-cli-bridge': 'codex-bridge',
-  'antigravity-cli-bridge': 'antigravity-bridge',
-};
-const displayOf = (name) => DISPLAY_NAMES[name] ?? name;
+// STATE_PUBLIC (internal→public token map) + DISPLAY_NAMES + displayOf now live in labels.mjs (B1) —
+// imported at the top of this file. They are used below exactly as before.
 
 // ── the settings survey (Phase 3) — read-only, honest, localized-on-error ──────────
 // Each sub-survey returns a small user-safe object OR a single `{ error }` field (a localized message,
@@ -380,8 +287,8 @@ const detectSafe = (deps) => {
 };
 
 // visibility: the THREE honest states from inferVisibility (NOT the single hiddenFence bit) → user-safe
-// words. Never the internal "hidden fence" / marker terms. A git/probe error → a localized error field.
-const VISIBILITY_PUBLIC = { visible: 'visible', hidden: 'hidden', ambiguous: 'unclear' };
+// words (VISIBILITY_PUBLIC, from labels.mjs). Never the internal "hidden fence" / marker terms. A
+// git/probe error → a localized error field.
 export const surveyVisibility = (dir, deps = {}) => {
   try {
     const vis = inferVisibility(deps, resolve(dir));
@@ -469,6 +376,20 @@ export const surveyBridges = (deps = {}) => {
   });
 };
 
+// INV-2 (structural refresh — additive, derived, never parsed from a caveat string). A member is
+// `behind` when it is a refreshable CORE member (memory / engine) carrying a refresh-recommending
+// caveat — surveyFamily attaches caveats ONLY to those two kinds, and today every such caveat is
+// refresh-recommending. `recommend` is composed from the member's npm package in the ONE registry
+// (FAMILY_MEMBERS[].npm), never extracted from the caveat text. The kit (composition-root) + the two
+// bridges (execution-backend) never carry such a caveat, so they derive { behind:false, recommend:null }
+// — gated by the CAVEAT, not by npm-nullness (the kit's npm is non-null; only the bridges are null).
+const REFRESHABLE_KINDS = new Set(['memory-substrate', 'methodology-engine']);
+const npmOf = (name) => FAMILY_MEMBERS.find((m) => m.name === name)?.npm ?? null;
+const refreshOf = (m) => {
+  const behind = REFRESHABLE_KINDS.has(m.kind) && Boolean(m.caveats?.length);
+  return { behind, recommend: behind ? `npx ${npmOf(m.name)}@latest init` : null };
+};
+
 export const buildEnvelope = (family, project = null, extras = {}) => {
   const installed = family.map((m) => {
     const entry = {
@@ -478,6 +399,7 @@ export const buildEnvelope = (family, project = null, extras = {}) => {
       state: STATE_PUBLIC[m.manifestState] ?? STATE_PUBLIC[UNKNOWN],
     };
     if (m.caveats?.length) entry.notes = m.caveats; // plain-language observations (Steps 2.2 / engine)
+    entry.refresh = refreshOf(m); // additive (INV-1): always present; { behind, recommend } (INV-2)
     return entry;
   });
   const envelope = { deploymentHead: EXPECTED_WORKFLOW_VERSION, installed };
@@ -498,27 +420,72 @@ export const buildEnvelope = (family, project = null, extras = {}) => {
 };
 
 // ── CLI ────────────────────────────────────────────────────────────────────────
-const parseArgs = (argv) => {
-  const dirFlag = argv.indexOf('--dir');
-  return {
-    help: argv.includes('--help') || argv.includes('-h'),
-    json: argv.includes('--json'),
-    dir: dirFlag >= 0 ? argv[dirFlag + 1] : undefined,
-  };
+// Parse contract (Plan §4.5, grounded): the old parseArgs SILENTLY ignored unknown args + a missing
+// --dir value. With the explicit format surface added, the parse now rejects LOUDLY (no silent
+// failure): an unknown flag, a `--dir` with no value, and an invalid `--format` (validated by
+// resolveFormat) all throw. `--json` vs `--format=*` precedence is deterministic (last-wins, in
+// surface.mjs). Returns only { dir } — help is handled first, the format/mode comes from the surface.
+const HELP_FLAGS = new Set(['--help', '-h']);
+// --dir and --format carry/consume a value, so they are handled explicitly below — only the valueless
+// flags live in KNOWN_FLAGS.
+const KNOWN_FLAGS = new Set(['--help', '-h', '--json']);
+// Single left-to-right pass (functional reduce, no `let`): EVERY `--dir` must carry a value — a
+// trailing or REPEATED `--dir` with no value rejects loudly, never silently (a first-occurrence-only
+// check let `--dir /p --dir` slip through as a "known flag"). The token right after a `--dir` is its
+// value (skipped), so a path is never mistaken for an unknown flag; the last `--dir` wins.
+export const parseArgs = (argv) => {
+  const { dir } = argv.reduce(
+    (state, a, i) => {
+      if (state.skip) return { dir: state.dir, skip: false }; // this token was the preceding --dir value
+      if (a === '--dir') {
+        const value = argv[i + 1];
+        if (value === undefined || value.startsWith('-')) {
+          throw new Error('[agent-workflow-kit] --dir needs a value: --dir <project>');
+        }
+        return { dir: value, skip: true }; // consume the value; last --dir wins
+      }
+      if (KNOWN_FLAGS.has(a) || a === '--format' || a.startsWith('--format=')) return state;
+      throw new Error(`[agent-workflow-kit] unknown argument: ${a}`);
+    },
+    { dir: undefined, skip: false },
+  );
+  return { dir };
 };
 
-const main = (argv) => {
-  const args = parseArgs(argv);
-  if (args.help) {
-    console.log(`family-registry — read-only view of the agent-workflow family.
+const HELP = `family-registry — read-only view of the agent-workflow family.
 
 Usage:
-  node family-registry.mjs [--dir <project>] [--json]
-    # skill axis always; deploy axis when --dir is given; --json = the no-leak machine envelope
+  node family-registry.mjs [--dir <project>] [--format=<auto|plain|ansi|json>] [--json]
+    # skill axis always; deploy axis when --dir is given.
+    # --format: auto (default — ansi on a TTY, plain otherwise) | plain | ansi | json.
+    #   --json is sugar for --format=json (the no-leak machine envelope). AGENT_WORKFLOW_FORMAT
+    #   sets the default; a flag beats it. Width/color follow the terminal (NO_COLOR / FORCE_COLOR).
 
-Detection only — never writes, never commits, never runs a subscription CLI.`);
+Detection only — never writes, never commits, never runs a subscription CLI.`;
+
+const main = (argv) => {
+  if (argv.some((a) => HELP_FLAGS.has(a))) {
+    console.log(HELP);
     return;
   }
+  // Validate args + resolve the output surface BEFORE any survey work; a bad flag/format → loud exit 1.
+  const args = (() => {
+    try {
+      const parsed = parseArgs(argv);
+      const surface = detectSurface({
+        argv,
+        env: process.env,
+        isTTY: Boolean(process.stdout.isTTY),
+        columns: process.stdout.columns,
+        platform: process.platform,
+      });
+      return { ...parsed, surface };
+    } catch (err) {
+      console.error(err?.message ?? String(err));
+      process.exit(1);
+    }
+  })();
+
   const family = surveyFamily();
   const bridges = surveyBridges();
   const project = args.dir ? surveyProject(args.dir) : null;
@@ -527,7 +494,10 @@ Detection only — never writes, never commits, never runs a subscription CLI.`)
     extras.visibility = surveyVisibility(args.dir);
     extras.settings = surveySettings(args.dir);
   }
-  console.log(args.json ? JSON.stringify(buildEnvelope(family, project, extras), null, 2) : formatStatus(family, project, extras));
+  const envelope = buildEnvelope(family, project, extras);
+  // Two surfaces, one data source: JSON prints the envelope verbatim; plain/ansi render it through the
+  // capability-adaptive presenter pipeline (view-model → renderers). No-leak inherited from the envelope.
+  console.log(args.surface.mode === 'json' ? JSON.stringify(envelope, null, 2) : render(toViewModel(envelope), args.surface));
 };
 
 const isDirectRun = process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href;

package/tools/labels.mjs

@@ -0,0 +1,81 @@
+// labels.mjs — the frozen vocabulary LEAF of the status surface (Plan: One-init-freshness §4.2 B1).
+//
+// This module owns the internal↔public token vocabulary that used to live inline in
+// family-registry.mjs: the manifestState constants, the internal→public state map, the visibility
+// map, the short display names, and the no-leak forbidden-term set. It is a LEAF — it imports
+// nothing from the family (only the language is here), so the import graph stays acyclic: nobody
+// imports family-registry for vocabulary, and family-registry imports + re-exports the public subset
+// it exported before (the 7 state constants + DISPLAY_NAMES), so every existing importer stays green.
+//
+// Pure data, no side effects, Node >= 18. Every export is frozen — this is a contract, not a mutable.
+
+// ── manifestState values (internal; the detect-backends precedence, generalized to any member) ──────
+// These are INTERNAL — they must never reach a user surface verbatim (mapped through STATE_PUBLIC
+// first). The two surfaces are pinned separately; the no-leak guard (INTERNAL_RENDER_FORBIDDEN) keeps
+// the internal literals out of the serialized envelope.
+export const NOT_INSTALLED = 'not-installed';
+export const UNSUPPORTED_SCHEMA = 'unsupported-schema';
+export const INVALID_MANIFEST = 'invalid-manifest';
+export const STUB = 'stub';
+export const FOREIGN = 'foreign';
+export const OK = 'ok';
+// The marker could not be probed (a non-ENOENT fs error — EACCES/EIO). Surfaced explicitly instead of
+// being masked as not-installed (no silent failure). NOTE: 'unknown' is ALSO a PUBLIC value — it is a
+// bridge wrappers[].state ("couldn't check"), so it is deliberately EXCLUDED from the no-leak set.
+export const UNKNOWN = 'unknown';
+
+// internal manifestState → a STABLE, user-safe token. SKILL.md owns the value→plain-language phrasing;
+// presentation.mjs owns the direct-CLI English phrasing. Deliberately NOT the internal literals
+// (foreign/stub/…): those must never leak past this boundary.
+export const STATE_PUBLIC = Object.freeze({
+  [OK]: 'installed',
+  [NOT_INSTALLED]: 'absent',
+  [FOREIGN]: 'other-tool',
+  [STUB]: 'placeholder',
+  [INVALID_MANIFEST]: 'invalid',
+  [UNSUPPORTED_SCHEMA]: 'unsupported',
+  [UNKNOWN]: 'uncheckable',
+});
+
+// visibility: the THREE honest states from inferVisibility → user-safe words. Never the internal
+// "hidden fence" / marker terms. ('hidden' here is the PUBLIC visibility word, not the internal fence.)
+export const VISIBILITY_PUBLIC = Object.freeze({ visible: 'visible', hidden: 'hidden', ambiguous: 'unclear' });
+
+// Short, user-facing labels for the version block (kit · memory · engine · codex-bridge · …), so the
+// render is deterministic and the agent never invents a label.
+export const DISPLAY_NAMES = Object.freeze({
+  'agent-workflow-kit': 'kit',
+  'agent-workflow-memory': 'memory',
+  'agent-workflow-engine': 'engine',
+  'codex-cli-bridge': 'codex-bridge',
+  'antigravity-cli-bridge': 'antigravity-bridge',
+});
+export const displayOf = (name) => DISPLAY_NAMES[name] ?? name;
+
+// ── the no-leak forbidden set (Plan §4.3 INV-4) ────────────────────────────────────────────────────
+// The terms that must NEVER appear in the serialized buildEnvelope output (the agent reads the JSON
+// directly, so the no-leak boundary is the envelope, not just the rendered text). The INV-4 test
+// iterates this set over JSON.stringify(envelope). Deliberately EXCLUDES:
+//   • 'unknown' — also a PUBLIC bridge wrappers[].state value (a `state:"unknown"` fixture must pass);
+//   • 'ok'      — too generic to forbid as a substring, and not sensitive (its public form is 'installed').
+// Sourced here as the ONE definition so the guard can't drift from a hand-copied list in the test.
+export const INTERNAL_RENDER_FORBIDDEN = Object.freeze([
+  // internal manifestState literals that must never reach a surface
+  NOT_INSTALLED,
+  UNSUPPORTED_SCHEMA,
+  INVALID_MANIFEST,
+  STUB,
+  FOREIGN,
+  // internal field names (the structural keys of the surveys, never the envelope)
+  'manifestState',
+  'hiddenFence',
+  // the hidden-mode marker / fence jargon (the SKILL communication firewall) — never the public
+  // visibility words ('hidden' / 'visible' / 'unclear'), only the internal compound terms + operations
+  'hidden fence',
+  'hidden-mode fence',
+  'reconcile',
+  'ensureSlot',
+  // raw deployment-stamp FILENAMES (the envelope exposes member/display/version, never the file)
+  '.workflow-version',
+  '.memory-version',
+]);

package/tools/presentation.mjs

@@ -0,0 +1,55 @@
+// presentation.mjs — the frozen ENGLISH/neutral vocabulary the direct-CLI renderers use to draw the
+// four status blocks (members · bridges · project deploy/visibility · settings). Plan §4.2.
+//
+// This is the DIRECT-CLI surface only (`node tools/family-registry.mjs` in a terminal). The
+// agent-mediated surface (`/agent-workflow-kit status`) consumes the `--json` envelope and localizes
+// in the user's language per SKILL.md §4.4 — it never reads this file. Keeping the vocabulary here (a
+// frozen leaf) means the renderers carry no inline strings and the phrasing is pinned by tests.
+//
+// Pure data, no side effects, Node >= 18. Every export frozen.
+
+// public state token (STATE_PUBLIC value) → the direct-CLI English phrase. `installed` is null because
+// an installed member shows its VERSION, not a phrase (the renderer special-cases it). Mirrors the
+// SKILL.md value→plain-language map so the two surfaces stay semantically aligned.
+export const STATE_PHRASING = Object.freeze({
+  installed: null, // → show the version instead
+  absent: 'not installed',
+  'other-tool': 'a different tool occupies that skill slot',
+  placeholder: 'a placeholder, not a working install',
+  invalid: "installed but its manifest didn't validate",
+  unsupported: 'installed but its manifest schema is too new for this kit',
+  uncheckable: "couldn't be checked (a permission error)",
+});
+
+// public visibility (VISIBILITY_PUBLIC value) → phrase. Never the internal "fence"/marker terms.
+export const VISIBILITY_PHRASING = Object.freeze({
+  visible: 'visible (tracked)',
+  hidden: 'hidden (git-ignored, local-only)',
+  unclear: 'unclear (uncommitted or partially set up)',
+});
+
+// Block titles. `project` is a function of the resolved dir.
+export const BLOCK_TITLES = Object.freeze({
+  members: 'agent-workflow family — installed members (skill axis)',
+  bridges: 'execution backends (host)',
+  project: (dir) => `project deployment (${dir})`,
+  settings: 'settings',
+});
+
+// Per-area settings row labels (the left column of the settings block).
+export const SETTINGS_LABELS = Object.freeze({
+  recipes: 'recipes',
+  attribution: 'attribution',
+  velocity: 'velocity',
+});
+
+// Glyph sets — Unicode for a capable terminal, an ASCII fallback for a narrow / Windows-legacy one.
+// The renderer picks one set by the resolved surface's `ascii` flag (surface.mjs).
+export const GLYPHS = Object.freeze({
+  unicode: Object.freeze({ note: '↳', present: '✓', missing: '✗', unknown: '?', bullet: '•' }),
+  ascii: Object.freeze({ note: '->', present: '+', missing: 'x', unknown: '?', bullet: '*' }),
+});
+export const glyphsFor = (ascii) => (ascii ? GLYPHS.ascii : GLYPHS.unicode);
+
+// The "no deployment here" line for an undeployed project.
+export const NO_DEPLOYMENT = 'no agent-workflow deployment detected here (no docs/ai, no version stamp).';

package/tools/renderers.mjs

@@ -0,0 +1,119 @@
+// renderers.mjs — the direct-CLI presenters (plain + ansi) for the four status blocks. Plan §4.2/§4.5.
+//
+// Input: the ViewModel (view-model.mjs, built from the no-leak envelope) + a resolved surface
+// (surface.mjs: { mode, width, color, ascii }). Output: a single string. `mode` selects plain vs ansi;
+// the JSON mode is handled by the caller (it prints the envelope, not a render). The renderers do
+// LAYOUT + GLYPHS only — phrasing + headline counts already live in the ViewModel.
+//
+// Pure, no side effects, Node >= 18.
+
+import { BLOCK_TITLES, SETTINGS_LABELS, glyphsFor, NO_DEPLOYMENT } from './presentation.mjs';
+
+const MEMBER_COL = 20;
+const VERSION_COL = 12;
+const READINESS_COL = 14;
+const STAMP_COL = 26;
+const SETTINGS_COL = 14;
+
+const SGR = Object.freeze({ bold: '\x1b[1m', reset: '\x1b[0m' });
+const ANSI_RE = /\x1b\[[0-9;]*m/g;
+export const visibleLength = (s) => s.replace(ANSI_RE, '').length;
+
+const pad = (s, n) => (s.length >= n ? s : s + ' '.repeat(n - s.length));
+// A styled span only when color is on — so color:false emits ZERO SGR (plain output, byte-clean).
+const heading = (text, color) => (color ? `${SGR.bold}${text}${SGR.reset}` : text);
+
+const renderMembers = (vm, { color, glyph }) => {
+  const lines = [heading(BLOCK_TITLES.members, color), ''];
+  for (const m of vm.members) {
+    const ver = m.version ? `v${m.version}` : '—';
+    const tail = m.statePhrase == null ? '' : m.statePhrase; // installed → the version IS the info
+    lines.push(`  ${pad(m.display, MEMBER_COL)}${pad(ver, VERSION_COL)}${tail}`.trimEnd());
+    for (const note of m.notes) lines.push(`      ${glyph.note} ${note}`); // verbatim caveats (INV-3)
+  }
+  // refresh.behind drives a HEADLINE COUNT only — the recovery command stays in the verbatim notes
+  // above (the direct CLI never dedupes, never re-prints it). Omitted when nothing is behind.
+  if (vm.headline.behind > 0) {
+    lines.push(`  ${vm.headline.behind} member(s) need a refresh (see the ${glyph.note} notes above).`);
+  }
+  return lines;
+};
+
+const renderBridges = (vm, { glyph, color }) => {
+  if (!vm.bridges) return [];
+  const lines = ['', heading(BLOCK_TITLES.bridges, color), ''];
+  for (const b of vm.bridges) {
+    const wrappers = b.wrappers.map((w) => `${w.cmd} ${glyph[w.state] ?? glyph.unknown}`).join(', ') || '—';
+    lines.push(`  ${pad(b.display, MEMBER_COL)}${pad(b.readiness, READINESS_COL)}wrappers: ${wrappers}`);
+  }
+  return lines;
+};
+
+const renderProject = (vm, { color }) => {
+  const p = vm.project;
+  if (!p) return [];
+  const lines = ['', heading(BLOCK_TITLES.project(p.dir), color), ''];
+  if (!p.deployed) {
+    lines.push(`  ${NO_DEPLOYMENT}`);
+    return lines;
+  }
+  for (const s of p.deployStamps) lines.push(`  ${pad(s.display, STAMP_COL)}${s.version ?? '—'}`);
+  lines.push(`  ${pad('docs/ai present', STAMP_COL)}${p.docsAi ? 'yes' : 'no'}`);
+  if (p.visibility) {
+    const v = p.visibility.error ? `error: ${p.visibility.error}` : p.visibility.phrase;
+    lines.push(`  ${pad('visibility', STAMP_COL)}${v}`);
+  }
+  return lines;
+};
+
+const renderSettings = (vm, { color, glyph }) => {
+  const s = vm.project?.settings;
+  if (!s) return [];
+  const lines = ['', heading(BLOCK_TITLES.settings, color)];
+  // recipes — the effective recipe per slot, or a loud error; a detector floor adds a sub-line.
+  if (s.recipes?.error) lines.push(`  ${pad(SETTINGS_LABELS.recipes, SETTINGS_COL)}error: ${s.recipes.error}`);
+  else if (s.recipes) {
+    const joined = s.recipes.pairs.map((p) => `${p.key}=${p.recipe}`).join(' · ') || '—';
+    lines.push(`  ${pad(SETTINGS_LABELS.recipes, SETTINGS_COL)}${joined}`);
+    if (s.recipes.detectError) {
+      lines.push(`  ${pad('', SETTINGS_COL)}${glyph.note} couldn't check backends (${s.recipes.detectError}); recipes floored at solo`);
+    }
+  }
+  // attribution — effective includeCoAuthoredBy; a real local override is called out.
+  if (s.attribution?.error) lines.push(`  ${pad(SETTINGS_LABELS.attribution, SETTINGS_COL)}error: ${s.attribution.error}`);
+  else if (s.attribution) {
+    const override = s.attribution.override ? ' (local override)' : '';
+    lines.push(`  ${pad(SETTINGS_LABELS.attribution, SETTINGS_COL)}includeCoAuthoredBy effective=${String(s.attribution.effective)}${override}`);
+  }
+  // velocity — effective defaultMode + per-source allow counts.
+  if (s.velocity?.error) lines.push(`  ${pad(SETTINGS_LABELS.velocity, SETTINGS_COL)}error: ${s.velocity.error}`);
+  else if (s.velocity) {
+    lines.push(`  ${pad(SETTINGS_LABELS.velocity, SETTINGS_COL)}defaultMode=${String(s.velocity.defaultMode)} · allow project/local=${s.velocity.allow.project}/${s.velocity.allow.local}`);
+  }
+  return lines;
+};
+
+// Pad each NON-empty line UP to the surface width (by VISIBLE length, so SGR codes don't count); empty
+// separator lines stay empty. `width` is a MIN target for a consistent block, NOT a hard max: a long
+// content line — a verbatim caveat `↳`, a long recipe row — is left INTACT and is NEVER truncated,
+// because truncating could hide part of a recovery command (a no-silent-failure violation). The
+// terminal soft-wraps an over-width line; data integrity wins over a perfectly rectangular block.
+const padLineTo = (line, width) => {
+  if (line === '') return '';
+  const vis = visibleLength(line);
+  return vis < width ? line + ' '.repeat(width - vis) : line;
+};
+
+export const render = (vm, surface = {}) => {
+  const glyph = glyphsFor(Boolean(surface.ascii));
+  const color = surface.mode === 'ansi' && Boolean(surface.color); // color applies in ansi mode only
+  const ctx = { color, glyph };
+  const lines = [
+    ...renderMembers(vm, ctx),
+    ...renderBridges(vm, ctx),
+    ...renderProject(vm, ctx),
+    ...renderSettings(vm, ctx),
+  ];
+  if (surface.mode === 'ansi') return lines.map((l) => padLineTo(l, surface.width ?? 80)).join('\n');
+  return lines.join('\n');
+};

package/tools/surface.mjs

@@ -0,0 +1,75 @@
+// surface.mjs — capability detection for the kit's OWN stdout (the direct CLI). Plan §4.5.
+//
+// Resolves how `node tools/family-registry.mjs` should render: the requested format, the effective
+// render mode (json | plain | ansi), whether to emit color, the terminal width, and whether to fall
+// back to ASCII glyphs. This governs ONLY the kit's direct-CLI output — the agent-mediated
+// `/agent-workflow-kit status` surface always consumes `--json` and localizes itself.
+//
+// Pure + fully injectable (argv / env / isTTY / columns / platform are inputs), no side effects on
+// import, Node >= 18. Tested in isolation against the §4.5 table.
+
+export const FORMATS = Object.freeze(['auto', 'plain', 'ansi', 'json']);
+export const FORMAT_ENV = 'AGENT_WORKFLOW_FORMAT';
+export const MIN_WIDTH = 40; // below this, force plain ASCII (a box can't lay out under ~40 cols)
+export const DEFAULT_WIDTH = 80;
+const FORMAT_FLAG = '--format=';
+
+// Resolve the requested format. A FLAG (--json or --format=X) beats the AGENT_WORKFLOW_FORMAT env;
+// among flags the LAST on argv wins (deterministic, standard last-wins). `--json` is exact sugar for
+// `--format=json`. A bare `--format` (no value), an empty value, or an unknown value → a LOUD reject
+// (never a silent fallback — Hard Constraint). Absent everywhere → 'auto'.
+export const resolveFormat = (argv = [], env = {}) => {
+  let fromFlag = null;
+  for (const a of argv) {
+    if (a === '--json') fromFlag = 'json';
+    else if (a === '--format') throw new Error(`[agent-workflow-kit] --format needs a value: --format=<${FORMATS.join('|')}>`);
+    else if (a.startsWith(FORMAT_FLAG)) fromFlag = a.slice(FORMAT_FLAG.length);
+  }
+  const requested = fromFlag ?? env[FORMAT_ENV] ?? 'auto';
+  if (!FORMATS.includes(requested)) {
+    throw new Error(`[agent-workflow-kit] invalid format "${requested}" — expected one of ${FORMATS.join(', ')}`);
+  }
+  return requested;
+};
+
+// Terminal width: stdout.columns (>0) wins, else $COLUMNS (>0), else the 80-col default. A garbage /
+// zero / undefined value falls through to the next source — never NaN.
+export const resolveWidth = ({ columns, env = {} } = {}) => {
+  const fromStdout = Number(columns);
+  if (Number.isFinite(fromStdout) && fromStdout > 0) return fromStdout;
+  const fromEnv = Number(env.COLUMNS);
+  if (Number.isFinite(fromEnv) && fromEnv > 0) return fromEnv;
+  return DEFAULT_WIDTH;
+};
+
+// Color is ORTHOGONAL to the render mode (the ansi renderer applies it; plain ignores it). Precedence:
+// CLICOLOR_FORCE / FORCE_COLOR present → on (unless explicitly '0'/'false'); else NO_COLOR present
+// (incl. empty value) → off; else follow isTTY. FORCE beats NO_COLOR.
+export const resolveColor = ({ env = {}, isTTY = false } = {}) => {
+  if ('CLICOLOR_FORCE' in env || 'FORCE_COLOR' in env) {
+    const v = 'CLICOLOR_FORCE' in env ? env.CLICOLOR_FORCE : env.FORCE_COLOR;
+    return !(v === '0' || String(v).toLowerCase() === 'false');
+  }
+  if ('NO_COLOR' in env) return false; // any value, incl. empty, disables (the NO_COLOR spec)
+  return Boolean(isTTY);
+};
+
+const isUtf8Env = (env = {}) => /utf-?8/i.test(env.LC_ALL || env.LC_CTYPE || env.LANG || '');
+
+// The full resolved surface. mode: 'json' (machine envelope) | 'plain' | 'ansi'. For a non-json
+// format: an explicit plain/ansi is honored; 'auto' detects a tier (plain when NOT a TTY, or TERM=dumb,
+// or any CI env; else ansi). A width below MIN_WIDTH FORCES plain. ascii glyphs when narrow, or on a
+// Windows TTY without a UTF-8 locale (shallow — deeper Windows/UTF-8 depth is deferred, Plan §9).
+export const detectSurface = ({ argv = [], env = {}, isTTY = false, columns, platform = 'linux' } = {}) => {
+  const format = resolveFormat(argv, env);
+  const width = resolveWidth({ columns, env });
+  if (format === 'json') return { format, mode: 'json', width, color: false, ascii: false };
+
+  const autoTier = !isTTY || env.TERM === 'dumb' || 'CI' in env ? 'plain' : 'ansi';
+  const requestedMode = format === 'auto' ? autoTier : format; // 'plain' | 'ansi'
+  const narrow = width < MIN_WIDTH;
+  const mode = narrow ? 'plain' : requestedMode; // the width floor wins over an ansi request
+  const ascii = narrow || (platform === 'win32' && !isUtf8Env(env));
+  const color = resolveColor({ env, isTTY }); // orthogonal — the ansi renderer gates on mode + color
+  return { format, mode, width, color, ascii };
+};

package/tools/view-model.mjs

@@ -0,0 +1,89 @@
+// view-model.mjs — transform the no-leak `--json` envelope (buildEnvelope output) into a render-ready
+// ViewModel for the direct-CLI renderers. Plan §4.2 / §4.5: surface → VIEW-MODEL → renderers.
+//
+// One data source: the renderers never touch the raw surveys, only this VM, which is built from the
+// ENVELOPE — so the renderers inherit the envelope's no-leak guarantee (internal manifestState / stamp
+// filenames never reach them). This module resolves public tokens → English phrases (presentation.mjs)
+// and computes the headline counts; the renderers do layout + glyphs only.
+//
+// Pure, no side effects, Node >= 18.
+
+import { STATE_PHRASING, VISIBILITY_PHRASING } from './presentation.mjs';
+
+const memberVm = (m) => {
+  const refresh = m.refresh ?? { behind: false, recommend: null };
+  return {
+    display: m.display,
+    version: m.version ?? null,
+    state: m.state,
+    // 'installed' → null (the renderer shows the version instead); every other public token → a phrase.
+    statePhrase: m.state in STATE_PHRASING ? STATE_PHRASING[m.state] : m.state,
+    notes: m.notes ?? [], // the verbatim caveats — printed as ↳ sub-lines (INV-3: no dedupe)
+    behind: Boolean(refresh.behind), // used ONLY for the headline count on the direct CLI (INV-3)
+    recommend: refresh.recommend ?? null,
+  };
+};
+
+const bridgeVm = (b) => ({
+  display: b.display,
+  readiness: b.readiness,
+  // preserve the three-state wrapper status (present | missing | unknown) — the renderer maps to a glyph.
+  wrappers: (b.wrappers ?? []).map((w) => ({ cmd: w.cmd, state: w.state })),
+});
+
+const visibilityVm = (v) => {
+  if (!v) return null;
+  if (v.error) return { error: v.error };
+  return { phrase: v.state in VISIBILITY_PHRASING ? VISIBILITY_PHRASING[v.state] : v.state };
+};
+
+const recipesVm = (r) => {
+  if (!r) return null;
+  if (r.error) return { error: r.error };
+  const pairs = [];
+  for (const [activity, slots] of Object.entries(r.activities ?? {})) {
+    for (const [slot, v] of Object.entries(slots)) pairs.push({ key: `${activity}.${slot}`, recipe: v.recipe });
+  }
+  return { pairs, detectError: r.detectError ?? null };
+};
+
+const attributionVm = (a) => {
+  if (!a) return null;
+  if (a.error) return { error: a.error };
+  // A local OVERRIDE only when local actually set the key (non-null) AND it differs from project — a
+  // null local means the key is absent there, so the project value stands (that is not an override).
+  const override = a.local != null && a.local !== a.project;
+  return { effective: a.effective ?? null, override };
+};
+
+const velocityVm = (v) => {
+  if (!v) return null;
+  if (v.error) return { error: v.error };
+  return { defaultMode: v.defaultMode ?? null, allow: { project: v.allowEntries?.project ?? 0, local: v.allowEntries?.local ?? 0 } };
+};
+
+const settingsVm = (s) =>
+  s ? { recipes: recipesVm(s.recipes), attribution: attributionVm(s.attribution), velocity: velocityVm(s.velocity) } : null;
+
+const projectVm = (p) =>
+  p
+    ? {
+        dir: p.dir,
+        deployed: p.deployed,
+        docsAi: p.docsAi,
+        deployStamps: (p.deployStamps ?? []).map((st) => ({ display: st.display, version: st.version ?? null })),
+        visibility: visibilityVm(p.visibility),
+        settings: settingsVm(p.settings),
+      }
+    : null;
+
+export const toViewModel = (envelope = {}) => {
+  const members = (envelope.installed ?? []).map(memberVm);
+  return {
+    deploymentHead: envelope.deploymentHead ?? null,
+    members,
+    headline: { total: members.length, behind: members.filter((m) => m.behind).length },
+    bridges: envelope.bridges ? envelope.bridges.map(bridgeVm) : null,
+    project: projectVm(envelope.project),
+  };
+};