@sabaiway/agent-workflow-kit 1.15.1 → 1.16.0

package/CHANGELOG.md

@@ -4,6 +4,63 @@ 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
+the published tarball, deploy/mirror payload tests retained. The deployment-lineage head stays
+**`1.3.0`** (no `docs/ai` structural change, no migration file). The kit **package** version is a
+separate axis.
+
+- **`files[]` scoped negation.** Appended `!bin/*.test.mjs`, `!tools/**/*.test.mjs`, and
+  `!tools/manifest/fixtures/**` to the package allowlist (npm ignores a root `.npmignore` when
+  `files[]` is present, so negation entries in `files[]` are the mechanism). Tarball **115 → 69
+  files**: 18 of the package's own colocated tests + 28 manifest fixtures no longer ship.
+- **Deploy/mirror payload tests retained.** `references/scripts/*.test.mjs` (deployed into a
+  consumer repo's `scripts/` with the docs-rotation scripts) and
+  `bridges/antigravity-cli-bridge/bin/agy.test.mjs` (part of the byte-identical bridge mirror the
+  installed kit links from) still ship — a blanket `!**/*.test.mjs` would have silently broken
+  installs, so the negation is deliberately scoped. **Never broaden it to `!references/**` or
+  `!bridges/**`.**
+- **New tarball guard.** `test/package-content.test.mjs` (dev-only; outside `files[]`, never ships)
+  pins the exact shape via `npm pack --dry-run --json`: no own-test/fixture leak, payload tests +
+  runtime files present, exact file count `=== 69`.
+- Test files stay on disk; the gate + publish CI run them from the checkout, unchanged. This is a
+  tarball-only exclusion.
+
 ## 1.15.1 — Version-axis clarity, hidden-mode invariant, lineage-head drift guard (kit)
 
 Patch: documentation + a regression guard; no behaviour change to shipped tooling, and the

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.1'
+  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.1",
+  "version": "1.16.0",
   "provides": [],
   "roles": {},
   "detect": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sabaiway/agent-workflow-kit",
-  "version": "1.15.1",
+  "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",
@@ -50,7 +50,10 @@
     "launchers/",
     "migrations/",
     "tools/",
-    "bridges/"
+    "bridges/",
+    "!bin/*.test.mjs",
+    "!tools/**/*.test.mjs",
+    "!tools/manifest/fixtures/**"
   ],
   "engines": {
     "node": ">=18"

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' },