@sabaiway/agent-workflow-kit 1.15.2 → 1.16.0

package/CHANGELOG.md

@@ -4,6 +4,40 @@ 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.16.0 — Onboarding & discoverability: `help`, honest versioning, an enriched `status` (kit)
+
+A **feature** release (additive, backward-compatible). Makes the kit self-explanatory: a discoverable
+command surface, honest installed-on-this-machine version legibility, and one `status` that answers
+"versions + deployment + settings + bridges". The deployment-lineage head stays **`1.3.0`** — nothing
+in the deployed `docs/ai` *structure* changed, so there is **no migration**. The kit **package**
+version is a separate axis from that head.
+
+- **`/agent-workflow-kit help` + safe unknown-invocation routing.** New `tools/commands.mjs`: a frozen
+  command catalog (grouped Inspect / Configure / Orchestrate / Lifecycle, each tagged read-only /
+  writer / guarded) + a pure `routeInvocation` router. A discoverable index, and the read-only landing
+  spot for any unrecognized invocation — **no unrecognized/garbage token ever reaches a writer/guarded
+  mode** (only an explicit known token, or the acknowledged bare-bootstrap exception). Drift-guarded
+  against the `### Mode:` headers.
+- **Honest version legibility.** `tools/family-registry.mjs` gains a no-leak `--json` envelope (user-safe
+  field names only — never the internal manifest/stamp terms) feeding a shared **version block**:
+  deployment-structure head · installed package versions per member · the two-axes disambiguation when
+  the numbers coincide. An **offline caveat** flags a memory install too old to ship the current
+  orchestration template ("installed on this machine", no network). Bootstrap/upgrade now print a
+  **welcome mat** (success → version block → backend line → one caveat-aware next step) and bootstrap
+  opens with a one-line first-contact orientation.
+- **Settings & bridges in `status`.** `status` is now the single answer to "versions + deployment +
+  settings + bridges": orchestration recipes (effective per slot), attribution
+  (`includeCoAuthoredBy`), velocity (`defaultMode`), the bridges (readiness + wrapper PATH presence,
+  no model claim), and **visibility** (visible / hidden / unclear, via `inferVisibility`) — each in
+  plain language, **localized-on-error** (a malformed file surfaces its own error, the rest still
+  renders). `loadConfig` is shared with the procedures advisor (one strict-JSON reader).
+- **Surgical delegation gate.** `references/templates/orchestration.json` joins the memory
+  required-asset set: a memory too old to seed `docs/ai/orchestration.json` now **falls back** to the
+  kit's bundled substrate (which seeds it) instead of being delegate-classified — closing the
+  stale-memory trap the read-only note only informs about.
+- **Tarball guard `69 → 70`** (the new shipped `tools/commands.mjs`); `npm pack --dry-run --json`
+  re-verified. No `docs/ai` structural change → lineage head unchanged.
+
 ## 1.15.2 — Strip the package's own tests + fixtures from the npm tarball (kit)
 
 Packaging only — no API/behaviour change; removed the package's own colocated tests + fixtures from

package/README.md

@@ -218,9 +218,10 @@ command is printed).
 |---------|------|--------------|
 | `/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 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** view of the whole family: which members (kit / memory / engine / the two bridges) are installed and at what version, and — with a project — what's deployed (`docs/ai`, the version stamps, and whether the AI files are git-ignored for hidden mode). Never writes, 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 hand-edited `docs/ai/orchestration.json` + 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 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. |

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.15.2'
+  version: '1.16.0'
 ---
 
 # agent-workflow-kit
@@ -35,9 +35,11 @@ validator shipped by the candidate (which could itself be broken). Delegate only
 hold:
 - result is **valid** and `kind` is `memory-substrate`;
 - **every required asset is present** in the candidate, at its real path:
-  `references/templates/`, `references/contracts.md`, `references/scripts/`,
-  `scripts/stamp-takeover.mjs`, `migrations/`, `capability.json`. A partial install (manifest +
-  `SKILL.md` only) is treated as **invalid**.
+  `references/templates/`, **`references/templates/orchestration.json`** (the orchestration-config
+  template — a memory too old to ship it, pre-`1.2.0`, can't seed `docs/ai/orchestration.json`, so it
+  falls back to the kit's own bundled substrate, which does), `references/contracts.md`,
+  `references/scripts/`, `scripts/stamp-takeover.mjs`, `migrations/`, `capability.json`. A partial
+  install (manifest + `SKILL.md` only) is treated as **invalid**.
 
 On **unsupported** (unknown schema), **invalid**, **unavailable**, **wrong-family**, or
 **wrong-name**, **use the bundled copy** — never block. The fallback decision is final once
@@ -96,10 +98,11 @@ ever deleted.
 
 ## Modes
 
-Pick the mode from the user's invocation. Auto-detect an existing `docs/ai/` to guard against bootstrapping over a live system, but the user makes the final call.
+Pick the mode from the user's invocation. Auto-detect an existing `docs/ai/` to guard against bootstrapping over a live system, but the user makes the final call. The invocation→mode mapping is pinned by `tools/commands.mjs` `routeInvocation` (unit-tested): a **known** subcommand routes to its mode; the **bare/empty** invocation routes to `bootstrap`; **any unrecognized/ambiguous** token routes to `help`, which is **read-only** — so a garbage invocation never triggers a write (see the safe-routing rule under *Version status & the two axes*).
 
 - **`/agent-workflow-kit`** (default) — bootstrap a new or empty project. If `docs/ai/` already exists, stop and ask whether they meant `upgrade`.
 - **`/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 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.
@@ -110,6 +113,8 @@ Pick the mode from the user's invocation. Auto-detect an existing `docs/ai/` to
 
 ### Version status & the two axes — surface this on every invocation
 
+**Safe-routing rule (which mode did the user invoke?).** Map the invocation token with `tools/commands.mjs` `routeInvocation`: a **known** subcommand → its mode; the **bare/empty** invocation → `bootstrap` — the one writer reachable without a token, and only on an undeployed project (if `docs/ai/` already exists, **ask upgrade-vs-bootstrap**, never overwrite); **any unrecognized/ambiguous** token → `help`, which is **read-only**. The invariant: **no unrecognized/garbage invocation ever triggers a write** (only an explicit known token or the acknowledged bare-bootstrap exception can). The mapping is unit-tested, so it is not left to interpretation.
+
 Before acting, read `docs/ai/.workflow-version` (the project's stamp), state a one-line status, then route:
 
 - **absent** → bootstrap (a fresh deployment).
@@ -151,6 +156,67 @@ readiness, then **append an actionable recipe recommendation** from the recipe p
   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)
+
+Bootstrap (step 11) and **every** successful `upgrade` exit (steps 4 + 8) close with the same
+**report footer**, in this **canonical order**: success state → **version block** → the **one-line
+backend-status line** → **welcome mat**. Only the version block comes from
+`node ${CLAUDE_SKILL_DIR}/tools/family-registry.mjs --json` (add `--dir <project>` for the deploy
+axis) — **never hardcoded semver**; the backend-status line is its own shared contract (above), and
+the welcome mat **composes signals already gathered** (the version block's notes + the backend-status
+line), not a fresh helper call. Present everything in the user's conversational language; never paste
+the JSON or any internal field name.
+
+**Version block — three plain lines, fed from `--json`:**
+- **`Deployment structure: <deploymentHead> (current)`** — the deployed `docs/ai` structure version
+  (the envelope's `deploymentHead`); **the only axis `upgrade` compares**.
+- **`Installed on this machine — package versions:`** `kit <v> · memory <v> · engine <v> ·
+  codex-bridge <v> · antigravity-bridge <v>` — one per `installed[]` entry, labelled by its `display`
+  and showing its `version`, or, when there is no version, the plain phrase for its `state` (map
+  below). Append any `installed[].notes` **in plain words** (e.g. the memory-behind refresh+restart
+  line).
+- **The two axes are different — say so even when the numbers coincide:** an installed *package*
+  version (e.g. engine `1.3.0`) is a package number, **not** the deployment-structure version on line
+  one (which is also `1.3.0` today). The head advances only when the deployed `docs/ai` structure
+  changes, so a higher package number on npm/GitHub is **not** a newer deployment.
+
+**`state` → plain language** (map the envelope's `installed[].state` token; never show the raw token):
+`installed` → its version · `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)".
+
+**Helper-failure contract (mirror the backend-status line).** The version block needs the
+family-registry helper, which the **agent host** runs. If the host can't run it (`node` not on the
+agent's PATH, or the helper errors), **skip the version block and say so with the concrete reason** —
+e.g. *"Couldn't run the family-registry helper here (node is not on the agent host PATH), so I'm
+skipping the installed-versions block."* — never a silent skip (Hard Constraint). It is non-essential:
+the rest of the report — and the commit gate — proceeds.
+
+**Welcome mat — the last line(s) of the footer.** After the version block and the backend-status
+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);
+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` /
+   `council` / `delegated` slot anywhere — inspect `docs/ai/orchestration.json`, or read the
+   procedures advisor's resolved recipes) → *put it to work with `/agent-workflow-kit recipes`*;
+4. else (a backend is ready **and** a backend-backed recipe is already selected) → the optional
+   *`/agent-workflow-kit velocity`* opt-in (never run it without a yes).
+
+Keep it compact — a few short lines, plain language, no kit-internal terms.
+
+### Mode: help
+
+Read-only. The single discoverable **command index** — it answers *"what can `/agent-workflow-kit` do, and which commands change things?"* It **never writes, never commits, and never runs a subscription CLI**.
+
+Run `node ${CLAUDE_SKILL_DIR}/tools/commands.mjs` (add `--json` for the machine-readable catalog) and present its grouped index — **Inspect / Configure / Orchestrate / Lifecycle**, each command tagged **read-only / writer / guarded** — in the user's conversational language. That catalog is the **single source of truth** for the command surface (the same one the bootstrap / upgrade report footers point at); `routeInvocation(token)` in the same file is the executable contract for which invocation maps to which mode.
+
+`help` is also the landing spot for any **unrecognized or ambiguous** invocation — and that path is **always read-only** (the safe-routing rule under *Version status & the two axes*). When you arrive here that way, render the index and, in plain language, note that the invocation wasn't recognized so nothing was changed.
+
 ### Mode: bootstrap
 
 > Bundled sources below (templates, scripts) live in **this skill's own directory** — `${CLAUDE_SKILL_DIR}/` in Claude Code, or the folder containing this `SKILL.md` in Codex / other agents. Use that as the copy/read source; the working directory is the **target project**, not the skill.
@@ -164,6 +230,7 @@ readiness, then **append an actionable recipe recommendation** from the recipe p
    - `src/` (or equivalent) 2–3 levels deep → modules, routes/pages, components, services, types.
    - Tests (framework, location, E2E?) and linter rules.
    - Record: stack, package manager, daily commands (`dev`/`test`/`lint`/`type-check`), routes/pages, architecture layers.
+   - **First-contact orientation — say this before the first question (read-only).** In 1–2 plain lines, tell the user what this is — a portable memory & workflow system for this repo, so future sessions boot from a small structured memory instead of re-reading everything — and that they can run **`/agent-workflow-kit help`** any time to see every command. This is the "start here"; keep it to a sentence or two, then ask the visibility question.
 2. **Choose visibility — ASK the user explicitly and wait for the answer, before writing anything.** This decides what gets tracked and is hard to reverse after a commit, so never assume the default silently: `visible` (committed — canonical, recommended) or `hidden` (in-tree, git-ignored via the **project-local** `.git/info/exclude` — one managed block covering the full AI/agent footprint, never the machine-global excludes). See [Visibility contract](references/contracts.md#visibility-contract).
 3. **Choose conversational language — ASK the user explicitly and wait for the answer.** Which language should the agent *talk to them* in — questions, explanations, summaries, status updates? Offer the language they're already writing in as the default. Carry the answer into the `{{COMM_LANGUAGE}}` slot of the *Communication language* block when `AGENTS.md` is created (step 5). See [Communication contract](references/contracts.md#communication-contract). This sets the **dialogue** language only — never the files.
 4. **Choose agent attribution — ASK the user explicitly and wait for the answer.** May the agent attribute work to itself / to AI — `Co-Authored-By` trailers, "Generated with …" footers, "AI"/agent/model mentions in code, comments, commit messages, PR titles/bodies, or docs? **Default to `off`** (no agent/AI mention anywhere) unless they opt in — people are routinely surprised to find an AI listed as a repo contributor. Carry the answer into the `{{AGENT_ATTRIBUTION}}` slot of the *Attribution* block when `AGENTS.md` is created (step 5). **If `off` and the project uses Claude Code**, also set `"includeCoAuthoredBy": false` in the project's `.claude/settings.json` (create it if absent) — the trailer is added by the harness, so a doc directive alone won't stop it. See [Attribution contract](references/contracts.md#attribution-contract).
@@ -186,7 +253,7 @@ readiness, then **append an actionable recipe recommendation** from the recipe p
     independent axes: a packaging-only release bumps the package but leaves the lineage head until a
     migration actually changes the deployed `docs/ai` structure. A stamp greater than the head →
     STOP (never downgrade).
-11. **Report & ask.** Show `tree docs/ai/`, 2–3 lines on what was filled with real data vs left as TODO, then print the **one-line backend-status line** (the shared contract above — same detector, format, invariants, and detector-unavailable skip-with-reason). Then **ask before committing** — never auto-commit. Finally, offer the optional, opt-in **velocity profile** in one line — `/agent-workflow-kit velocity` seeds a read-only allowlist so routine read-only commands stop prompting (*Mode: velocity*); never run it without a yes.
+11. **Report & ask.** Show `tree docs/ai/`, 2–3 lines on what was filled with real data vs left as TODO, 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 ends on **one** recommended next step — including the optional, opt-in `/agent-workflow-kit velocity` (a read-only allowlist so routine read-only commands stop prompting; *Mode: velocity*) when nothing more pressing applies, never run without a yes. Then **ask before committing** — never auto-commit.
 
 Fill strategy:
 
@@ -220,12 +287,12 @@ Fill strategy:
 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* or was *already present* (a user edit is preserved); 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).
    - **Name the version axis so the package number isn't mistaken for a newer release.** When you state the deployment is up to date, say it is current at the **deployment-lineage head** (`1.3.0`) and add one plain line: this head versions the deployed `docs/ai` structure and is a **separate axis** from the kit **package** version published on npm/GitHub (the larger number users see on the repo/npm page). A packaging-only release can bump that package version **without** moving the head — the head advances only when the deployed `docs/ai` structure changes — so an equal-head report is **not** a stale deployment even though GitHub shows a higher package number. (This is the only place the two axes meet the user in `upgrade`; surfacing it here prevents the recurring "but GitHub shows a higher version" confusion.)
-   - **Print the one-line backend-status line** — the shared contract above (run `node ${CLAUDE_SKILL_DIR}/tools/detect-backends.mjs`; same format, invariants, and detector-unavailable skip-with-reason).
-   - **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, say **"already up to date"** and still print the read-only backend line.
+   - **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, say **"already up to date"** and still print the read-only version block + backend line.
 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). Report changes — and when you report the stamp, **name the axis**: the head versions the deployed `docs/ai` structure and is a separate axis from the kit **package** version on npm/GitHub (the larger number users see there), so the user doesn't read the bigger package number as a newer deployment (same framing as the step 4 equal-head exit). Then **print the one-line backend-status line** (the shared contract above — same detector, format, invariants, and detector-unavailable skip-with-reason). Then **ask before committing**.
+8. Re-stamp `docs/ai/.workflow-version` to the **deployment-lineage head** (`1.3.0`, not the package version). Report changes — and when you report the stamp, **name the axis**: the head versions the deployed `docs/ai` structure and is a separate axis from the kit **package** version on npm/GitHub (the larger number users see there), so the user doesn't read the bigger package number as a newer deployment (same framing as the step 4 equal-head exit). 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
 
@@ -259,14 +326,22 @@ For each backend it:
 
 ### Mode: status
 
-Read-only. Answers *"which family members are installed (and at what version), and what is deployed in this project?"* across the **whole family** — the unified registry behind it (`tools/family-registry.mjs`) aggregates every member's `capability.json`. It **never writes, never commits, and never runs a subscription CLI**.
+Read-only. The **single answer to "versions + deployment + settings + bridges"** across the whole family — `tools/family-registry.mjs` aggregates every member's `capability.json` and surveys the project. It **never writes, never commits, and never runs a subscription CLI**.
+
+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:
 
-Run `node ${CLAUDE_SKILL_DIR}/tools/family-registry.mjs [--dir <project>]` and present its two-axis table:
+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.
+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.
+   - **attribution** — `includeCoAuthoredBy` effective; call out a **local override** only when `local` is non-null **and** differs from `project` (a `null` `local` means the key is absent there, so the project value stands — that is not an override).
+   - **velocity** — the effective `permissions.defaultMode` + whether an allowlist is seeded (detail → `/agent-workflow-kit velocity`).
+   - Any area's **`error`** field → surface it **loudly** in plain language; the rest of `status` still renders (never a crash).
+4. **Bridges (host, one line)** (from `bridges[]`): per bridge — readiness + wrapper PATH-presence; render each wrapper's `state` as *on PATH* (`present`) / *not on PATH* (`missing`) / *couldn't check* (`unknown`) (detail → `/agent-workflow-kit backends` / `setup`). **No default-model claim.** "credentials present" means a marker file exists, not a live login.
 
-1. **Skill axis (always):** per member — `installed` + the manifest health (`ok` / `not-installed` / `foreign` / `stub` / `invalid-manifest` / `unsupported-schema`, the same precedence the backend detector uses) + the installed version (read from the member's own `SKILL.md`, the authoritative source).
-2. **Deploy axis (`--dir <project>`):** the deployment stamps (`docs/ai/.workflow-version`, `.memory-version`), whether `docs/ai/` exists, and whether the hidden-mode managed fence is present.
+Restate the **two-axes honesty** — an installed *package* version is not a project's deployment-lineage stamp (see *Version status & the two axes*); the installed version is whatever is on disk under `~/.claude/skills/…`, so a stale install shows its real (older) version, honestly. A host that can't run the helper → **skip with the concrete reason** (the helper-failure contract), never silently.
 
-State plainly that the two version axes stay decoupled (an installed *skill* version is not a project's deployment-lineage stamp — see *Version status & the two axes*). The installed version reflects whatever is on disk under `~/.claude/skills/…`; a stale install shows its real (older) version, honestly.
+**Invariants:** read-only · never writes · never commits · never runs a subscription CLI · plain language only, no leaked internal terms.
 
 ### Mode: recipes
 
@@ -354,6 +429,7 @@ The non-obvious traps — scan these before bootstrapping or upgrading. Each is
 - **Hidden mode is project-local, and the hide tool owns the known footprint.** `tools/hide-footprint.mjs` writes **one managed block** in the **project-local `.git/info/exclude`** — never the machine-global `core.excludesFile` (which would silently affect every repo on the host; **AD-014** amends **AD-006**). It hides the kit's own artifacts **and** the known external AI/agent footprint (the `KNOWN_FOOTPRINT` table in [contracts](references/contracts.md#visibility-contract)). A **tracked** file is **never silently un-tracked** — the tool prints the `git rm --cached` it will not run. Never leak its internal marker / asks terms to the user; translate every outcome to plain language.
 - **`CLAUDE.md` is a symlink, not a copy.** `ln -s AGENTS.md CLAUDE.md` — single source, no duplication. A copy drifts; a symlink can't.
 - **Never overwrite an existing entry point or hook.** If `AGENTS.md` / `CLAUDE.md` already exist, or the installer reports a pre-existing non-marker git hook, **stop and ask** the user to merge vs replace — don't clobber.
+- **Unrecognized invocations are read-only.** Only a **known** subcommand reaches its mode; the **bare** invocation bootstraps (and an existing `docs/ai/` makes it ask upgrade-vs-bootstrap first, never overwrite); **any other / ambiguous** token routes to `help` (read-only). A garbage invocation never writes. The mapping is pinned by `tools/commands.mjs` `routeInvocation` (unit-tested) — don't hand-route around it.
 - **No Node runtime → skip enforcement.** If the project has no Node (recon step 1), skip bootstrap steps 8–9 (scripts + hook) and follow the cap/archive/index policy manually, or port the scripts to the project's language.
 - **Conversational language never translates artifacts.** It governs *dialogue only*. Code, identifiers, paths, commands, log output, abbreviations, and every deployed `docs/ai/` / `AGENTS.md` file stay in their source language. See [Communication contract](references/contracts.md#communication-contract).
 - **Never auto-commit.** Report quality-gate results and wait for explicit approval — in both modes.
@@ -415,6 +491,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), `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 hand-edited `docs/ai/orchestration.json`, and prints the steps + the resolved effective recipe per slot; drift-guarded activity/slot table vs the canon; read-only, never runs a subscription CLI), `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), `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 hand-edited `docs/ai/orchestration.json`, and prints the steps + the resolved effective recipe per slot; drift-guarded activity/slot table vs the canon; read-only, never runs a subscription CLI), `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/capability.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sabaiway/agent-workflow-kit",
-  "version": "1.15.2",
+  "version": "1.16.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/tools/commands.mjs

@@ -0,0 +1,206 @@
+#!/usr/bin/env node
+// commands.mjs — the kit's canonical command catalog + the pure invocation router behind the
+// `/agent-workflow-kit help` index and the safe unknown-invocation routing rule.
+//
+// Until now the modes existed only as `### Mode:` headers in SKILL.md, never enumerated for the user:
+// there was no discoverable command surface and no executable answer to "what did the user actually
+// invoke?". This module is the SINGLE source of truth for both — one frozen catalog (one entry per
+// mode, grouped + tagged read-only/writer/guarded with a plain-language one-liner) that the `help`
+// mode renders and the report footers point at, plus `routeInvocation(token)` that maps a raw
+// subcommand token to its mode.
+//
+// Safety invariant (pinned by the tests): `bootstrap` is a writer and the BARE/EMPTY invocation maps
+// to it — that is the ONE acknowledged exception, itself guarded downstream by the existing
+// "docs/ai/ exists → ask upgrade-vs-bootstrap" check (SKILL.md Mode: bootstrap). The invariant is
+// therefore: NO unrecognized/garbage token ever maps to a writer/guarded mode — every such token
+// routes to `help`, which is read-only.
+//
+// Source of truth = the COMMANDS table below; a drift-guard test (commands.test.mjs) pins its keys to
+// the `### Mode:` headers in SKILL.md, so the catalog cannot silently drift from the documented modes.
+// Pure, dependency-free, Node >= 18. No side effects on import (the isDirectRun idiom).
+
+import { pathToFileURL } from 'node:url';
+
+const SKILL_NAME = 'agent-workflow-kit';
+const BARE_INVOCATION = `/${SKILL_NAME}`;
+const invocationOf = (token) => `${BARE_INVOCATION}${token ? ` ${token}` : ''}`;
+
+// ── kinds ────────────────────────────────────────────────────────────────────────
+// read-only — never writes, never commits, never runs a subscription CLI.
+// writer    — writes files (a project deployment or a settings/skill placement).
+// guarded   — a destructive teardown gated behind a mandatory dry-run-first + explicit consent.
+// `writer` and `guarded` are the "acts on the system" kinds; only an explicit known token may reach
+// one (plus the bare bootstrap exception). Garbage routes to `help` (read-only) — see routeInvocation.
+export const READ_ONLY = 'read-only';
+export const WRITER = 'writer';
+export const GUARDED = 'guarded';
+const KINDS = new Set([READ_ONLY, WRITER, GUARDED]);
+
+// ── groups (fixed render order) ────────────────────────────────────────────────────
+export const GROUP_ORDER = Object.freeze(['Inspect', 'Configure', 'Orchestrate', 'Lifecycle']);
+
+// ── the canonical catalog ──────────────────────────────────────────────────────────
+// One entry per `### Mode:` in SKILL.md. `key` is the mode (and, for every non-bootstrap mode, the
+// routable subcommand token — bootstrap is the bare invocation, so it has no token). `oneLine` is
+// plain-language: NO internal terms (no reconcile/fence/stamp/manifest/anchor) a third-party user
+// hasn't read SKILL.md for. The drift-guard test pins these keys to the SKILL.md headers.
+const CATALOG = [
+  {
+    key: 'bootstrap',
+    invocation: BARE_INVOCATION,
+    group: 'Lifecycle',
+    kind: WRITER,
+    oneLine: 'Deploy the memory & workflow system into a new or empty project (asks visibility, language, and attribution first).',
+  },
+  {
+    key: 'upgrade',
+    invocation: invocationOf('upgrade'),
+    group: 'Lifecycle',
+    kind: WRITER,
+    oneLine: 'Bring an existing deployment up to the current version — your authored notes are preserved.',
+  },
+  {
+    key: 'uninstall',
+    invocation: invocationOf('uninstall'),
+    group: 'Lifecycle',
+    kind: GUARDED,
+    oneLine: 'Remove only what setup placed; it never deletes your notes and always previews before changing anything.',
+  },
+  {
+    key: 'status',
+    invocation: invocationOf('status'),
+    group: 'Inspect',
+    kind: READ_ONLY,
+    oneLine: 'Show what is installed and at what version, your settings and backends, and what is deployed in this project.',
+  },
+  {
+    key: 'backends',
+    invocation: invocationOf('backends'),
+    group: 'Inspect',
+    kind: READ_ONLY,
+    oneLine: 'Check which optional review/execute backends (codex, agy) are set up versus missing, and the next step.',
+  },
+  {
+    key: 'help',
+    invocation: invocationOf('help'),
+    group: 'Inspect',
+    kind: READ_ONLY,
+    oneLine: 'List every command, grouped, marking each as read-only or as one that makes changes.',
+  },
+  {
+    key: 'setup',
+    invocation: invocationOf('setup'),
+    group: 'Configure',
+    kind: WRITER,
+    oneLine: 'Set up an optional backend — place its helper and link its commands onto your PATH (opt-in; preview first).',
+  },
+  {
+    key: 'velocity',
+    invocation: invocationOf('velocity'),
+    group: 'Configure',
+    kind: WRITER,
+    oneLine: 'Seed a read-only command allowlist so routine read-only commands stop prompting (Claude Code; opt-in; preview first).',
+  },
+  {
+    key: 'recipes',
+    invocation: invocationOf('recipes'),
+    group: 'Orchestrate',
+    kind: READ_ONLY,
+    oneLine: 'See the orchestration recipes (Solo / Reviewed / Council / Delegated) and which one fits this environment.',
+  },
+  {
+    key: 'procedures',
+    invocation: invocationOf('procedures'),
+    group: 'Orchestrate',
+    kind: READ_ONLY,
+    oneLine: 'Show a named activity’s steps and which recipe applies at each stage here.',
+  },
+];
+
+// Deep-freeze: freeze the array AND every entry, so the catalog is genuinely immutable at runtime
+// (Object.freeze on the array alone leaves the entry objects writable).
+export const COMMANDS = Object.freeze(CATALOG.map((c) => Object.freeze(c)));
+
+// The mode every garbage/unrecognized token routes to. Read-only by contract (see routeInvocation).
+export const UNKNOWN_INVOCATION_MODE = 'help';
+// The mode the bare/empty invocation maps to — the one writer reachable without an explicit token,
+// guarded downstream by the docs/ai upgrade-vs-bootstrap check.
+export const BARE_INVOCATION_MODE = 'bootstrap';
+
+const byKey = new Map(COMMANDS.map((c) => [c.key, c]));
+// Routable subcommand tokens = every mode except bootstrap (whose invocation is the bare default).
+const ROUTABLE_TOKENS = new Set(COMMANDS.filter((c) => c.key !== BARE_INVOCATION_MODE).map((c) => c.key));
+
+export const commandFor = (key) => byKey.get(key) ?? null;
+export const kindOf = (key) => byKey.get(key)?.kind ?? null;
+
+// ── the pure router ────────────────────────────────────────────────────────────────
+// routeInvocation(token) → a mode key. `token` is the subcommand the user typed — either the raw word
+// (`upgrade`) OR the full slash form (`/agent-workflow-kit upgrade`); the first word is significant
+// and trailing args are ignored. Precise semantics:
+//   undefined / null / '' / whitespace-only / the exact bare invocation → 'bootstrap'
+//   a known first token (upgrade/status/setup/backends/recipes/procedures/velocity/uninstall/help)
+//     → that mode
+//   anything else (unrecognized / ambiguous) → 'help'  (read-only — NEVER a writer/guarded mode)
+export const routeInvocation = (token) => {
+  if (token == null) return BARE_INVOCATION_MODE;
+  const trimmed = String(token).trim();
+  if (trimmed === '' || trimmed === BARE_INVOCATION) return BARE_INVOCATION_MODE;
+  // Accept either the raw subcommand token OR the full slash invocation the user types — strip a
+  // leading `/agent-workflow-kit ` prefix so `/agent-workflow-kit upgrade` routes like `upgrade`.
+  const rest = trimmed.startsWith(`${BARE_INVOCATION} `)
+    ? trimmed.slice(BARE_INVOCATION.length).trim()
+    : trimmed;
+  if (rest === '') return BARE_INVOCATION_MODE;
+  const first = rest.split(/\s+/)[0];
+  return ROUTABLE_TOKENS.has(first) ? first : UNKNOWN_INVOCATION_MODE;
+};
+
+// ── render ──────────────────────────────────────────────────────────────────────────
+
+const KIND_TAG = { [READ_ONLY]: '[read-only]', [WRITER]: '[writer]   ', [GUARDED]: '[guarded]  ' };
+const pad = (s, n) => (s.length >= n ? s : s + ' '.repeat(n - s.length));
+
+// formatHelp() → the grouped, kind-tagged human index. Deterministic; groups in GROUP_ORDER, modes in
+// catalog order within each group. The header states the index itself is read-only.
+export const formatHelp = () => {
+  const invocWidth = Math.max(...COMMANDS.map((c) => c.invocation.length));
+  const lines = [
+    `${SKILL_NAME} — command index (this list is read-only)`,
+    '',
+    'Each command is tagged read-only · writer (makes changes) · guarded (destructive, previews first).',
+  ];
+  for (const group of GROUP_ORDER) {
+    const inGroup = COMMANDS.filter((c) => c.group === group);
+    if (!inGroup.length) continue;
+    lines.push('', group);
+    for (const c of inGroup) {
+      lines.push(`  ${pad(c.invocation, invocWidth)}  ${KIND_TAG[c.kind] ?? c.kind}  ${c.oneLine}`);
+    }
+  }
+  return lines.join('\n');
+};
+
+// The machine form behind `--json`: the flat catalog (machines group by `group` themselves) plus the
+// two routing anchors, so a consumer can reproduce routeInvocation without re-deriving the rules.
+export const buildJson = () => ({
+  skill: SKILL_NAME,
+  groupOrder: [...GROUP_ORDER],
+  unknownInvocationMode: UNKNOWN_INVOCATION_MODE,
+  bareInvocationMode: BARE_INVOCATION_MODE,
+  commands: COMMANDS.map(({ key, invocation, group, kind, oneLine }) => ({ key, invocation, group, kind, oneLine })),
+});
+
+// ── CLI ──────────────────────────────────────────────────────────────────────────────
+const main = (argv) => {
+  if (argv.includes('--json')) {
+    console.log(JSON.stringify(buildJson(), null, 2));
+    return;
+  }
+  console.log(formatHelp());
+};
+
+const isDirectRun = process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href;
+if (isDirectRun) main(process.argv.slice(2));
+
+export { KINDS, SKILL_NAME, BARE_INVOCATION };

package/tools/delegation.mjs

@@ -20,8 +20,16 @@ export const EXPECTED_MEMORY_NAME = 'agent-workflow-memory';
 // The assets a memory candidate must carry, AND their required type. A partial install (manifest +
 // SKILL.md only) is missing these → invalid → fallback. Checking the type (not just existence)
 // rejects a wrong-shaped install (e.g. a file where a dir is expected) BEFORE any project write.
+//
+// `references/templates/orchestration.json` (Step 2.4) is a SURGICAL gate: a memory too old to ship
+// the orchestration-config template (pre-1.2.0, e.g. v1.0.0) can't seed `docs/ai/orchestration.json`,
+// so it must NOT be delegate-classified — the kit then falls back to its OWN bundled substrate, which
+// DOES seed orchestration.json (Mode: upgrade step 3). This closes the stale-memory trap that the
+// read-only family-registry note (MEMORY_ORCH_TEMPLATE_REL) only INFORMS about — the gate ACTS. The
+// two key on the same asset; a cross-tool parity test pins them in lockstep.
 export const REQUIRED_MEMORY_ASSETS = [
   { path: 'references/templates', type: 'dir' },
+  { path: 'references/templates/orchestration.json', type: 'file' },
   { path: 'references/contracts.md', type: 'file' },
   { path: 'references/scripts', type: 'dir' },
   { path: 'scripts/stamp-takeover.mjs', type: 'file' },

package/tools/family-registry.mjs

@@ -16,14 +16,29 @@
 // Pure, dependency-injectable (fs/env/home/validator are deps), dependency-free, Node >= 18. No
 // side effects on import (the isDirectRun idiom) — tests import the helpers with nothing run.
 
-import { existsSync, statSync, readFileSync } from 'node:fs';
+import { existsSync, statSync, readFileSync, lstatSync } from 'node:fs';
 import { join, resolve } from 'node:path';
 import { pathToFileURL } from 'node:url';
 import os from 'node:os';
-import { resolveDir } from './detect-backends.mjs';
+import { resolveDir, detectBackends, findOnPath } from './detect-backends.mjs';
 import { validateManifest, readAuthoritativeVersion, UNSUPPORTED, INVALID } from './manifest/validate.mjs';
-import { START_MARKER, excludePath } from './hide-footprint.mjs';
+import { START_MARKER, excludePath, inferVisibility } from './hide-footprint.mjs';
 import { readEngineFragment, ORCHESTRATION_FRAGMENT_REL, PROCEDURES_FRAGMENT_REL } from './engine-source.mjs';
+import { ACTIVITIES, resolveActivityRecipe } from './recipes.mjs';
+import { loadConfig } from './procedures.mjs';
+// The deployment-lineage head + the shared settings readers are reused from velocity-profile so the
+// `--json` envelope/settings-survey has ONE implementation each, never a drifting copy:
+//   EXPECTED_WORKFLOW_VERSION — the head literal (drift-guarded vs memory LINEAGE_HEAD)
+//   readSettingsFile / resolveEffectiveMode — the loud `.claude/settings.*` reader + mode precedence
+// (No import cycle: velocity-profile / recipes / procedures import only node builtins + siblings, none
+// import family-registry, and none has a side effect on import — every CLI is isDirectRun-guarded.)
+import {
+  EXPECTED_WORKFLOW_VERSION,
+  SETTINGS_FILE,
+  SETTINGS_LOCAL_FILE,
+  readSettingsFile,
+  resolveEffectiveMode,
+} from './velocity-profile.mjs';
 
 // ── manifestState values (the detect-backends precedence, generalized to any member kind) ──────────
 export const NOT_INSTALLED = 'not-installed';
@@ -93,14 +108,14 @@ export const FAMILY_MEMBERS = [
 export const isGlobalSkill = (member) => member.kind !== undefined; // every member is a global skill today
 
 // ── pure probes ──────────────────────────────────────────────────────────────────
-// Wrapped marker probe → 'present' (a regular file) | 'absent' (ENOENT / not a file) | 'unknown' (a
-// non-ENOENT fs error, e.g. EACCES). 'unknown' is NOT collapsed to 'absent': a permission error must
-// surface, never be masked as not-installed (no silent failure) — and uninstall then leaves it alone.
+// Wrapped marker probe → 'present' (a regular file) | 'absent' (ENOENT / not a regular file) |
+// 'unknown' (a non-ENOENT fs error, e.g. EACCES). STAT-FIRST on purpose: `existsSync()` SWALLOWS an
+// EACCES into a bare `false`, which would mask a permission error as 'absent' (a silent failure);
+// `statSync` THROWS the EACCES so it surfaces as 'unknown'. 'unknown' is never collapsed to 'absent' —
+// classifyMember reports it (uninstall then leaves the dir alone) and the memory caveat skips it.
 const probeMarker = (path, deps = {}) => {
-  const exists = deps.exists ?? existsSync;
   const stat = deps.stat ?? statSync;
   try {
-    if (!exists(path)) return 'absent';
     return stat(path).isFile() ? 'present' : 'absent';
   } catch (err) {
     return err && err.code === 'ENOENT' ? 'absent' : 'unknown';
@@ -158,6 +173,17 @@ const ENGINE_FRAGMENT_CAVEATS = [
   { rel: PROCEDURES_FRAGMENT_REL, caveat: 'engine present but does not ship the activity-procedures canon (too old / incomplete) — run `npx @sabaiway/agent-workflow-engine@latest init`' },
 ];
 
+// The orchestration-config TEMPLATE a current memory ships (added in memory 1.2.0; absent in older
+// installs such as v1.0.0). It is the SAME asset Step 2.4 adds to delegation.mjs's
+// REQUIRED_MEMORY_ASSETS: the read-only note here INFORMS, the delegation gate ACTS. Step 2.4 also
+// adds a parity drift-guard tying this path to that required-asset set, so the note and the gate can
+// never key on different files (until then they are kept in lockstep by review).
+export const MEMORY_ORCH_TEMPLATE_REL = 'references/templates/orchestration.json';
+// Worded as an honest OBSERVATION, not a diagnosis (absence can mean old OR incomplete), and it makes
+// NO claim about an orchestration.json seeding outcome (that depends on delegate-vs-fallback).
+const MEMORY_BEHIND_NOTE =
+  "the memory installed here doesn't include the current orchestration template — refresh it with `npx @sabaiway/agent-workflow-memory@latest init`, then restart the session.";
+
 export const surveyFamily = (deps = {}) =>
   FAMILY_MEMBERS.map((member) => {
     const row = classifyMember(member, deps);
@@ -173,6 +199,14 @@ export const surveyFamily = (deps = {}) =>
       const caveats = ENGINE_FRAGMENT_CAVEATS.filter((f) => !fragmentUsable(f.rel)).map((f) => f.caveat);
       if (caveats.length) row.caveats = caveats;
     }
+    // Memory offline caveat (Step 2.2): a distinct probe — the orchestration TEMPLATE file's existence.
+    // Only attach when it is provably ABSENT (a non-ENOENT probe error → 'unknown' → skip, never a
+    // false "missing" claim). Mirrors the engine-caveat SHAPE; keyed on the Step-2.4 required asset.
+    if (row.kind === 'memory-substrate' && row.manifestState === OK && row.skillDir) {
+      if (probeMarker(join(row.skillDir, MEMORY_ORCH_TEMPLATE_REL), deps) === 'absent') {
+        row.caveats = [...(row.caveats ?? []), MEMORY_BEHIND_NOTE];
+      }
+    }
     return row;
   });
 
@@ -234,13 +268,41 @@ export const surveyProject = (projectDir, deps = {}) => {
 // ── report ───────────────────────────────────────────────────────────────────────
 const pad = (s, n) => (s.length >= n ? s : s + ' '.repeat(n - s.length));
 
-export const formatStatus = (family, project = null) => {
+// 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) {
@@ -250,16 +312,197 @@ export const formatStatus = (family, project = null) => {
         lines.push(`  ${pad(s.file, 26)}${s.version ?? '—'}`);
       }
       lines.push(`  ${pad('docs/ai present', 26)}${project.docsAiPresent ? 'yes' : 'no'}`);
-      lines.push(`  ${pad('hidden-mode fence', 26)}${project.hiddenFence ? 'present' : 'absent'}`);
+      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 no-leak --json envelope ──────────────────────────────────────────────────
+// A machine-readable view with USER-SAFE field names only — NEVER the internal manifestState /
+// hiddenFence terms or the raw stamp FILENAMES. The render (SKILL.md version block + Mode: status)
+// 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;
+
+// ── 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,
+// never a crash): a malformed/unreadable file in ONE area must not break the rest of `status`. The
+// readers are REUSED (one implementation each): loadConfig (procedures.mjs), readSettingsFile /
+// resolveEffectiveMode (velocity-profile.mjs), resolveActivityRecipe (recipes.mjs), inferVisibility
+// (hide-footprint.mjs). Engine-free throughout (the effective-recipe view never reads the engine).
+
+// A localized, user-safe error string. The reused readers already build cwd-relative `path: reason`
+// messages (loadConfig / velocity), so this just normalizes to a string — never a raw stack/abs path.
+const localizeError = (err) => (err && err.message ? String(err.message) : String(err));
+
+const hasOwn = (o, k) => o != null && Object.prototype.hasOwnProperty.call(o, k);
+
+// The backend detector is a SECONDARY input to the survey — a corrupt bridge must never break the
+// read-only view, but the failure must NOT be silent (Hard Constraint). Run it defensively: a throw →
+// { detection: [], error: <localized> } so callers floor gracefully (recipes → solo, bridges →
+// 'unknown') AND can surface the concrete reason. Returns a value so callers stay `const`.
+const detectSafe = (deps) => {
+  try {
+    return { detection: (deps.detect ?? detectBackends)(deps), error: null };
+  } catch (err) {
+    return { detection: [], error: localizeError(err) };
+  }
+};
+
+// 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' };
+export const surveyVisibility = (dir, deps = {}) => {
+  try {
+    const vis = inferVisibility(deps, resolve(dir));
+    return { state: VISIBILITY_PUBLIC[vis.visibility] ?? 'unclear' };
+  } catch (err) {
+    return { error: localizeError(err) };
+  }
+};
+
+// orchestration recipes: the EFFECTIVE recipe per slot (config · default · effective), engine-free —
+// shared loadConfig + resolveActivityRecipe + the read-only backend detector. A malformed config → a
+// localized error field; a detection failure floors at solo (a corrupt bridge must not break the view).
+export const surveyRecipes = (dir, deps = {}) => {
+  // A detector failure floors recipes at solo (mirrors procedures) but is surfaced as `detectError`, so
+  // the render says "couldn't check backends" instead of letting a real solo-default look identical.
+  const { detection, error: detectError } = detectSafe(deps);
+  try {
+    const { config, source } = loadConfig(resolve(dir), deps.readFile ?? readFileSync, deps.lstat ?? lstatSync);
+    const activities = {};
+    for (const [activity, def] of Object.entries(ACTIVITIES)) {
+      activities[activity] = {};
+      for (const slot of Object.keys(def.slots)) {
+        const r = resolveActivityRecipe({ config: config ?? {}, readiness: detection, activity, slot });
+        activities[activity][slot] = { recipe: r.recipe, source: r.source, degradedFrom: r.degradedFrom ?? null };
+      }
+    }
+    return { configSource: source, activities, ...(detectError ? { detectError } : {}) };
+  } catch (err) {
+    return { error: localizeError(err) };
+  }
+};
+
+// attribution: includeCoAuthoredBy across .claude/settings.json + settings.local.json as
+// project · local override · effective (local WINS only when it actually sets the key — presence-based,
+// mirroring resolveEffectiveMode). Reuses the loud readSettingsFile; the precedence read is new code.
+export const surveyAttribution = (dir, deps = {}) => {
+  try {
+    const d = resolve(dir);
+    const project = readSettingsFile(join(d, SETTINGS_FILE), { ...deps, cwd: d });
+    const local = readSettingsFile(join(d, SETTINGS_LOCAL_FILE), { ...deps, cwd: d });
+    const projVal = project.present && hasOwn(project.data, 'includeCoAuthoredBy') ? project.data.includeCoAuthoredBy : null;
+    const localHasKey = local.present && hasOwn(local.data, 'includeCoAuthoredBy');
+    const localVal = localHasKey ? local.data.includeCoAuthoredBy : null;
+    return { project: projVal, local: localVal, effective: localHasKey ? localVal : projVal };
+  } catch (err) {
+    return { error: localizeError(err) };
+  }
+};
+
+// velocity: the effective permissions.defaultMode (local > project, via resolveEffectiveMode) + the
+// per-source count of allowlist entries — a read-only view of what the velocity profile may have seeded.
+export const surveyVelocity = (dir, deps = {}) => {
+  try {
+    const d = resolve(dir);
+    const project = readSettingsFile(join(d, SETTINGS_FILE), { ...deps, cwd: d });
+    const local = readSettingsFile(join(d, SETTINGS_LOCAL_FILE), { ...deps, cwd: d });
+    const { effectiveMode } = resolveEffectiveMode(project.data, local.data);
+    const allowOf = (s) => (s.present && Array.isArray(s.data?.permissions?.allow) ? s.data.permissions.allow.length : 0);
+    return { defaultMode: effectiveMode ?? null, allowEntries: { project: allowOf(project), local: allowOf(local) } };
+  } catch (err) {
+    return { error: localizeError(err) };
+  }
+};
+
+// the project-scoped settings survey (needs a project dir). Each area is independently localized-on-error.
+export const surveySettings = (dir, deps = {}) => ({
+  recipes: surveyRecipes(dir, deps),
+  attribution: surveyAttribution(dir, deps),
+  velocity: surveyVelocity(dir, deps),
+});
+
+// bridges: HOST-scoped (no project needed). Wrapper command NAMES come from FAMILY_MEMBERS[].wrapperCmds
+// (static, always present), their PATH-presence is probed DIRECTLY via findOnPath over those names (NOT
+// detect-backends' wrappers[], which is [] when the bridge isn't ok — the onboarding case), and the
+// readiness summary comes from the detector. NO default-model claim (a negative drift-guard asserts it).
+export const surveyBridges = (deps = {}) => {
+  const { detection } = detectSafe(deps); // a detector failure → every readiness reads 'unknown' (honest)
+  const probe = deps.findOnPath ?? findOnPath;
+  return FAMILY_MEMBERS.filter((m) => m.kind === 'execution-backend').map((m) => {
+    const det = detection.find((d) => d.name === m.name);
+    // Preserve findOnPath's THREE-state result (present | missing | unknown): an `unknown` (EACCES,
+    // "cannot confirm") must stay distinct from a real `missing` — never flattened to a false boolean.
+    const wrappers = m.wrapperCmds.map((cmd) => ({ cmd, state: probe(cmd, deps).state }));
+    return { member: m.name, display: displayOf(m.name), readiness: det?.readiness ?? 'unknown', wrappers };
+  });
+};
+
+export const buildEnvelope = (family, project = null, extras = {}) => {
+  const installed = family.map((m) => {
+    const entry = {
+      member: m.name,
+      display: displayOf(m.name),
+      version: m.version ?? null,
+      state: STATE_PUBLIC[m.manifestState] ?? STATE_PUBLIC[UNKNOWN],
+    };
+    if (m.caveats?.length) entry.notes = m.caveats; // plain-language observations (Steps 2.2 / engine)
+    return entry;
+  });
+  const envelope = { deploymentHead: EXPECTED_WORKFLOW_VERSION, installed };
+  if (extras.bridges) envelope.bridges = extras.bridges; // HOST-scoped (no project needed)
+  if (project) {
+    envelope.project = {
+      dir: project.dir,
+      deployed: project.deployed,
+      docsAi: project.docsAiPresent,
+      // member + display + version only — never the internal stamp FILENAME (s.file).
+      deployStamps: project.stamps.map((s) => ({ member: s.name, display: displayOf(s.name), version: s.version ?? null })),
+    };
+    // project-scoped Phase-3 additions (visibility from inferVisibility, not the hiddenFence bit).
+    if (extras.visibility) envelope.project.visibility = extras.visibility;
+    if (extras.settings) envelope.project.settings = extras.settings;
+  }
+  return envelope;
+};
+
 // ── CLI ────────────────────────────────────────────────────────────────────────
 const parseArgs = (argv) => {
   const dirFlag = argv.indexOf('--dir');
-  return { help: argv.includes('--help') || argv.includes('-h'), dir: dirFlag >= 0 ? argv[dirFlag + 1] : undefined };
+  return {
+    help: argv.includes('--help') || argv.includes('-h'),
+    json: argv.includes('--json'),
+    dir: dirFlag >= 0 ? argv[dirFlag + 1] : undefined,
+  };
 };
 
 const main = (argv) => {
@@ -268,14 +511,21 @@ const main = (argv) => {
     console.log(`family-registry — read-only view of the agent-workflow family.
 
 Usage:
-  node family-registry.mjs [--dir <project>]   # skill axis always; deploy axis when --dir is given
+  node family-registry.mjs [--dir <project>] [--json]
+    # skill axis always; deploy axis when --dir is given; --json = the no-leak machine envelope
 
 Detection only — never writes, never commits, never runs a subscription CLI.`);
     return;
   }
   const family = surveyFamily();
+  const bridges = surveyBridges();
   const project = args.dir ? surveyProject(args.dir) : null;
-  console.log(formatStatus(family, project));
+  const extras = { bridges };
+  if (args.dir) {
+    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 isDirectRun = process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href;

package/tools/procedures.mjs

@@ -141,7 +141,9 @@ const validateConfig = (config) => {
 // Load + validate the config from <cwd>/docs/ai/orchestration.json. Absent FILE → computed defaults
 // (NOT an error): { config: null, source: 'none' }. Malformed JSON / schema-invalid / unreadable →
 // loud `path: reason` (exit 1). The resolver receives the parsed+validated object (§2.2 IO/resolver split).
-const loadConfig = (cwd, readFile = readFileSync, lstat = lstatSync) => {
+// Exported so the read-only status settings-survey (family-registry.mjs) reuses ONE config reader —
+// same strict-JSON + loud-on-malformed contract, no second drifting implementation (Plan 3.1).
+export const loadConfig = (cwd, readFile = readFileSync, lstat = lstatSync) => {
   const full = join(cwd, CONFIG_REL);
   // Distinguish a TRULY-absent config (no entry at all → computed defaults) from a present-but-
   // unreadable one (a directory, a DANGLING SYMLINK, a permission error → loud exit 1). lstat does NOT