@sabaiway/agent-workflow-kit 1.4.0 → 1.5.1

package/CHANGELOG.md

@@ -4,6 +4,47 @@ Semantically versioned ([semver](https://semver.org)), newest first. The `versio
 is the current release. `upgrade` mode reads a project's `docs/ai/.workflow-version` and applies
 every `migrations/<version>-<slug>.md` newer than it, in semver order.
 
+## 1.5.1 — README hero fix (docs)
+
+Docs-only patch. The hero showed a hardcoded `v1.4.0` chip while the kit was 1.5.0; the chip is
+removed (the shields.io npm-version badge already shows the live version). A repo test
+(`test/readme-no-stale-version.test.mjs`, dev-only — not shipped) now asserts no published README
+hero carries a pinned `vX.Y.Z` chip, so the drift can't recur. No code, schema, or deployed-payload
+change; the deployment-lineage head stays `1.3.0` (no migration).
+
+## 1.5.0 — Backend detection (detect + guide)
+
+The kit's onboarding can now **see the optional execution-backends** — the thin bridges to
+subscription CLIs (`codex-cli-bridge` → `codex`, `antigravity-cli-bridge` → `agy`) — instead of
+being blind to everything but the memory substrate. **Additive and read-only**: no `capability.json`
+schema change, no validator change, no auto-install. Since nothing in the deployed `docs/ai/`
+structure changes, **no migration is needed** and the deployment-lineage head stays `1.3.0`
+(`upgrade` reconciles and re-stamps with nothing to apply).
+
+- **`tools/detect-backends.mjs` — the read-only detector.** Pure, dependency-injectable,
+  dependency-free (Node ≥ 18), and already shipped (it lives under `tools/`, which is in the
+  package `files` + the installer `PAYLOAD`). It reports two **decoupled** axes so a healthy
+  manifest is never confused with a usable backend: `manifestState` (health of the bridge *skill*:
+  `not-installed | unsupported-schema | invalid-manifest | foreign | stub | ok`) and the readiness
+  signals `cli` / `credentials` / `wrappers`, probed **independently** for every registry entry even
+  when the skill is absent — so "the `codex` CLI is installed and signed in, but the bridge skill
+  isn't" reads as `needs-skill`, with the setup pointer. Every fs probe is wrapped → an explicit
+  `unknown` + reason, never a throw and never a nameless failure.
+- **Detection is read-only — it never runs a subscription CLI.** "credentials present/missing" is
+  the existence of the credential-marker **file**, never a live `codex login status` / `agy` check
+  (which would spawn a paid, slow, networked CLI). The report deliberately never says
+  "authenticated" (a unit test asserts the word's absence).
+- **Kit-owned registry (`KNOWN_BACKENDS`), not a schema change.** A missing bridge has no manifest
+  on disk and no `setup/README.md` in the kit tarball, so the per-backend facts (`bin`, credential
+  marker, stable setup URL) must live in the detector. A **drift-guard** test keeps the registry in
+  lockstep with the in-repo manifests (set equality with every `kind:execution-backend` dir, unique
+  names, `detect.installed` match, `setup/README.md` exists).
+- **Two surfaces.** A new **`/agent-workflow-kit backends`** mode presents the table and, for any
+  backend that is not `ready`, points to its setup (local `setup/README.md` when installed, else the
+  setup URL). Bootstrap **step 11** also prints a one-line backends summary — read-only, and it
+  **never blocks the commit gate**. Honest about Windows: detection works, but the bridges' POSIX
+  `.sh` wrappers are not promised to run there.
+
 ## 1.4.0 — Delegation-aware composition root (agent-workflow family, Plan 1)
 
 The kit becomes the **composition root** of the new `agent-workflow` family. **Additive** — the

package/README.md

@@ -12,7 +12,7 @@ instead of re-reading your whole repo.*
 [![license](https://img.shields.io/npm/l/@sabaiway/agent-workflow-kit)](./LICENSE)
 [![node](https://img.shields.io/node/v/@sabaiway/agent-workflow-kit)](https://nodejs.org)
 
-`v1.4.0`  ·  `Node ≥ 18`  ·  `kernel-only`
+`Node ≥ 18`  ·  `dependency-free`  ·  `kernel-only`
 
 **Works with any tool that reads `AGENTS.md`** — Claude Code · Codex · Cursor · Devin Desktop (formerly Windsurf) · GitHub Copilot · Gemini CLI · Cline · Aider · and 20+ more.
 
@@ -181,6 +181,7 @@ 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, applies migrations, re-stamps |
+| `/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). |
 
 It **never auto-commits** and **never overwrites** an existing `AGENTS.md` without asking.
 
@@ -223,7 +224,7 @@ agent-workflow-kit/
     ├── scripts/     ← caps / archive / index + tests
     ├── contracts.md ← visibility / language / attribution rules
     └── planning.md  ← plan lifecycle + continuity
-├── tools/           ← family tooling: manifest schema + validator, methodology-slot injection
+├── tools/           ← family tooling: manifest schema + validator, methodology-slot injection, backend detector (detect-backends)
 ├── launchers/       ← Codex / Devin Desktop / Cursor entries
 └── migrations/      ← per-version upgrade steps
 ```

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.4.0'
+  version: '1.5.1'
 ---
 
 # agent-workflow-kit
@@ -72,12 +72,13 @@ ever deleted.
 
 ---
 
-## Two modes
+## 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.
 
 - **`/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 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.
 
 ### Mode: bootstrap
 
@@ -106,7 +107,7 @@ Pick the mode from the user's invocation. Auto-detect an existing `docs/ai/` to
     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 **ask before committing** — never auto-commit.
+11. **Report & ask.** Show `tree docs/ai/`, 2–3 lines on what was filled with real data vs left as TODO, then run the **backend detector** (`node ${CLAUDE_SKILL_DIR}/tools/detect-backends.mjs`) and print a one-line summary of the optional execution-backends (e.g. `backends: codex ✓ ready · antigravity ✗ needs-credentials — run /agent-workflow-kit backends`). This is **read-only and never blocks the commit gate**. Then **ask before committing** — never auto-commit.
 
 Fill strategy:
 
@@ -127,6 +128,16 @@ Fill strategy:
 5. 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`.
 6. Re-stamp `docs/ai/.workflow-version` to the **deployment-lineage head** (`1.3.0`, not the package version). Report changes; **ask before committing**.
 
+### Mode: backends
+
+Read-only. Answers *"which optional execution-backends are set up vs missing, and what's the next step?"* — for the family's subscription-CLI bridges (`codex-cli-bridge` → `codex`, `antigravity-cli-bridge` → `agy`). It **never writes, never commits, and never runs a subscription CLI**.
+
+1. Run `node ${CLAUDE_SKILL_DIR}/tools/detect-backends.mjs` and present its table verbatim. Each row reports two **decoupled** axes: `manifestState` (health of the bridge *skill* — `not-installed | unsupported-schema | invalid-manifest | foreign | stub | ok`) and the readiness signals `cli` / `credentials` / `wrappers`, probed independently — so a CLI that is installed and signed in but whose bridge *skill* is absent reads `needs-skill`, not "missing".
+2. For any backend that is not `ready`, point to its setup: the local `setup/README.md` when the bridge is installed, otherwise the backend's setup URL (both are in the report).
+3. State plainly to the user that this is **detection only**:
+   - **"credentials present"** means the credential-marker **file** exists — it is **not** a live login check. The detector never runs `codex login status` / `agy` (that would spawn a paid, slow, networked subscription CLI).
+   - The bridges' wrappers are **POSIX `.sh`** scripts. On Windows the detector still works, but the bridges themselves are **not promised to run** — say so rather than implying they will.
+
 ---
 
 ## Gotchas
@@ -196,6 +207,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` + `methodology-slot.md` (the bounded slot injection), and `release-scan.mjs` (the attribution-off release gate). 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), `delegation.mjs` (the executable delegate/fallback decision + hand-off plan), `inject-methodology.mjs` + `methodology-slot.md` (the bounded slot injection), `detect-backends.mjs` (the read-only **backend detector** behind `/agent-workflow-kit backends`), and `release-scan.mjs` (the attribution-off release gate). 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.4.0",
+  "version": "1.5.1",
   "provides": [],
   "roles": {},
   "detect": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sabaiway/agent-workflow-kit",
-  "version": "1.4.0",
+  "version": "1.5.1",
   "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/detect-backends.mjs

@@ -0,0 +1,310 @@
+#!/usr/bin/env node
+// Backend detector — read-only detection of the family's optional execution-backends (the bridges
+// to subscription CLIs: codex-cli-bridge → `codex`, antigravity-cli-bridge → `agy`). Surfaced as
+// `/agent-workflow-kit backends` and a one-line bootstrap summary. It answers "what is set up vs
+// missing" WITHOUT running any subscription CLI: "credentials present" means the credential-marker
+// FILE exists, never a live `codex login` / `agy` check (which spawns a paid/slow/networked CLI).
+//
+// Two orthogonal axes are reported independently (a healthy manifest ≠ a usable backend):
+//   manifestState — health of the bridge SKILL: not-installed | unsupported-schema |
+//                   invalid-manifest | foreign | stub | ok.
+//   readiness     — cli + credentials + wrappers, probed for EVERY registry entry even when the
+//                   skill is absent, so we can say "the CLI is installed but the bridge skill isn't".
+//
+// Source of truth is the in-tool KNOWN_BACKENDS registry (Option B / AD-008): a missing bridge has
+// no manifest on disk and no setup/README in the kit tarball, so the per-backend facts (bin,
+// credential marker, stable setup URL) must live here. A drift-guard test keeps the registry in
+// lockstep with the in-repo manifests.
+//
+// Pure, dependency-injectable (fs/env/validator are deps), dependency-free, Node >= 18. Every fs
+// probe is wrapped → an explicit `unknown` + reason, never a throw and never a nameless failure.
+
+import { existsSync, statSync, accessSync, realpathSync, readFileSync, constants } from 'node:fs';
+import { join } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import os from 'node:os';
+import { validateManifest, UNSUPPORTED, INVALID } from './manifest/validate.mjs';
+
+// Probe states. `unknown` (a wrapped fs error) NEVER counts as present in any readiness rule.
+const PRESENT = 'present';
+const MISSING = 'missing';
+const UNKNOWN = 'unknown';
+
+// manifestState values.
+const NOT_INSTALLED = 'not-installed';
+const UNSUPPORTED_SCHEMA = 'unsupported-schema';
+const INVALID_MANIFEST = 'invalid-manifest';
+const STUB = 'stub';
+const FOREIGN = 'foreign';
+const OK = 'ok';
+
+// readiness values.
+const READY = 'ready';
+const NEEDS_SKILL = 'needs-skill';
+const NEEDS_CLI = 'needs-cli';
+const NEEDS_CREDENTIALS = 'needs-credentials';
+const DEGRADED = 'degraded';
+
+const EXPECTED_KIND = 'execution-backend';
+
+// The kit-owned registry: the per-backend facts the detector needs even when a bridge is NOT
+// installed (no manifest on disk to read). Kept in lockstep with the in-repo manifests by the
+// drift-guard test. `credential.env: null` → no env override exists (do not invent one).
+export const KNOWN_BACKENDS = [
+  {
+    name: 'codex-cli-bridge',
+    installed: { env: 'CODEX_CLI_BRIDGE_DIR', default: '~/.claude/skills/codex-cli-bridge', file: 'SKILL.md' },
+    bin: 'codex',
+    credential: { env: 'CODEX_HOME', default: '~/.codex', file: 'auth.json' },
+    setupUrl: 'https://github.com/sabaiway/agent-workflow/blob/main/codex-cli-bridge/setup/README.md',
+    setupPathLocal: 'setup/README.md',
+  },
+  {
+    name: 'antigravity-cli-bridge',
+    installed: { env: 'ANTIGRAVITY_CLI_BRIDGE_DIR', default: '~/.claude/skills/antigravity-cli-bridge', file: 'SKILL.md' },
+    bin: 'agy',
+    credential: { env: null, default: '~/.gemini/antigravity-cli', file: 'antigravity-oauth-token' },
+    setupUrl: 'https://github.com/sabaiway/agent-workflow/blob/main/antigravity-cli-bridge/setup/README.md',
+    setupPathLocal: 'setup/README.md',
+  },
+];
+
+// ── pure helpers ─────────────────────────────────────────────────────────────
+
+// Expand a leading "~" / "~/x" against home; absolute and relative paths pass through untouched.
+export const expandTilde = (p, home = os.homedir()) => {
+  if (p === '~') return home;
+  if (p.startsWith('~/')) return join(home, p.slice(2));
+  return p;
+};
+
+// Resolve a {env, default} dir spec: a non-empty env var wins as-is, else the (tilde-expanded)
+// default. Same resolver for the skill dir AND the credential dir.
+export const resolveDir = ({ env, default: dflt }, getenv = process.env, home = os.homedir()) => {
+  const fromEnv = env ? getenv[env] : undefined;
+  if (typeof fromEnv === 'string' && fromEnv.length > 0) return fromEnv;
+  return expandTilde(dflt, home);
+};
+
+const defaultAccessX = (p) => accessSync(p, constants.X_OK);
+const defaultRealpath = (p) => realpathSync(p);
+
+// FS-only PATH scan — never a subprocess/shell. POSIX → one candidate per dir, checked with
+// accessSync(file, X_OK); Windows → bin+ext for each PATHEXT entry. A symlinked binary still passes
+// X_OK (access follows symlinks) and is reported at its realpath. ENOENT → keep scanning; any other
+// fs error (e.g. EACCES) means we cannot confirm → `unknown`.
+export const findOnPath = (bin, deps = {}) => {
+  const getenv = deps.getenv ?? process.env;
+  const platform = deps.platform ?? process.platform;
+  const access = deps.access ?? defaultAccessX;
+  const realpath = deps.realpath ?? defaultRealpath;
+  const isWin = platform === 'win32';
+  const rawPath = (isWin ? getenv.PATH ?? getenv.Path : getenv.PATH) ?? '';
+  const dirs = rawPath.split(isWin ? ';' : ':').filter(Boolean);
+  const exts = isWin ? (getenv.PATHEXT ?? '.COM;.EXE;.BAT;.CMD').split(';').filter(Boolean) : [''];
+  let sawUnknown = false;
+  for (const dir of dirs) {
+    for (const ext of exts) {
+      const candidate = join(dir, bin + ext);
+      try {
+        access(candidate);
+        let resolved = candidate;
+        try {
+          resolved = realpath(candidate);
+        } catch {
+          // realpath failed (race / broken symlink) — keep the candidate path, still present.
+        }
+        return { bin, state: PRESENT, path: resolved };
+      } catch (err) {
+        if (err && err.code === 'ENOENT') continue;
+        sawUnknown = true; // EACCES or other → cannot confirm absence
+      }
+    }
+  }
+  return { bin, state: sawUnknown ? UNKNOWN : MISSING, path: null };
+};
+
+// Wrapped file-existence probe: present (a regular file) | missing (absent or not a file) |
+// unknown (a non-ENOENT fs error). Never reads contents.
+const probeFile = (file, deps = {}) => {
+  const exists = deps.exists ?? existsSync;
+  const stat = deps.stat ?? statSync;
+  try {
+    if (!exists(file)) return MISSING;
+    return stat(file).isFile() ? PRESENT : MISSING;
+  } catch (err) {
+    return err && err.code === 'ENOENT' ? MISSING : UNKNOWN;
+  }
+};
+
+// "authed?" = existence of the credential-marker file (read-only). NEVER runs the subscription CLI.
+// Report wording is "credentials present/missing/unknown", never "authenticated".
+export const probeCredential = (entry, deps = {}) => {
+  const dir = resolveDir(
+    { env: entry.credential.env, default: entry.credential.default },
+    deps.getenv ?? process.env,
+    deps.home ?? os.homedir(),
+  );
+  const file = join(dir, entry.credential.file);
+  return { state: probeFile(file, deps), path: file };
+};
+
+const defaultReadManifest = (skillDir, deps = {}) => {
+  const read = deps.readFile ?? readFileSync;
+  try {
+    return JSON.parse(read(join(skillDir, 'capability.json'), 'utf8'));
+  } catch {
+    return null;
+  }
+};
+
+// The bridge's PATH wrapper names = the deduped `roles[].cmd` set (codex's review + execute roles
+// are two cmds; antigravity's review + probe roles share one `agy-run`).
+const wrapperCmds = (manifest) => {
+  const roles = manifest && typeof manifest.roles === 'object' && !Array.isArray(manifest.roles) ? manifest.roles : {};
+  const seen = new Set();
+  const out = [];
+  for (const role of Object.values(roles)) {
+    const cmd = role && typeof role.cmd === 'string' ? role.cmd : null;
+    if (cmd && !seen.has(cmd)) {
+      seen.add(cmd);
+      out.push(cmd);
+    }
+  }
+  return out;
+};
+
+const computeReadiness = (manifestState, cli, credentials, wrappers) => {
+  if (manifestState !== OK) return NEEDS_SKILL;
+  if (cli.state !== PRESENT) return NEEDS_CLI;
+  if (credentials.state !== PRESENT) return NEEDS_CREDENTIALS;
+  if (wrappers.every((w) => w.state === PRESENT)) return READY;
+  return DEGRADED;
+};
+
+// ── core ─────────────────────────────────────────────────────────────────────
+
+// Detect one backend → the data-model object (manifestState + decoupled readiness signals).
+// manifestState precedence: not-installed → (validate) unsupported-schema → invalid-manifest →
+// stub (available:false) → foreign (wrong kind/name) → ok.
+export const detectBackend = (entry, deps = {}) => {
+  const validate = deps.validate ?? validateManifest;
+  const getenv = deps.getenv ?? process.env;
+  const home = deps.home ?? os.homedir();
+  const probeCliFn = deps.probeCli ?? ((bin) => findOnPath(bin, deps));
+  const probeWrapperFn =
+    deps.probeWrapper ??
+    ((cmd) => {
+      const r = findOnPath(cmd, deps);
+      return { name: cmd, state: r.state };
+    });
+  const probeCredentialsFn = deps.probeCredentials ?? ((e) => probeCredential(e, deps));
+  const readManifest = deps.readManifest ?? ((dir) => defaultReadManifest(dir, deps));
+
+  const resolvedDir = resolveDir({ env: entry.installed.env, default: entry.installed.default }, getenv, home);
+  const markerPresent = probeFile(join(resolvedDir, entry.installed.file), deps) === PRESENT;
+
+  let manifestState;
+  let manifestReason;
+  let isOk = false;
+  if (!markerPresent) {
+    manifestState = NOT_INSTALLED;
+    manifestReason = `bridge skill not installed — ${entry.installed.file} not found in ${resolvedDir}`;
+  } else {
+    const report = validate(resolvedDir);
+    if (report.result === UNSUPPORTED) {
+      manifestState = UNSUPPORTED_SCHEMA;
+      manifestReason = `manifest schema unsupported — ${report.errors?.[0] ?? 'unknown schema'}`;
+    } else if (report.result === INVALID) {
+      manifestState = INVALID_MANIFEST;
+      manifestReason = `manifest invalid — ${report.errors?.[0] ?? 'failed validation'}`;
+    } else if (report.available === false) {
+      manifestState = STUB;
+      manifestReason = 'manifest declares available:false (stub, not a usable backend)';
+    } else if (report.kind !== EXPECTED_KIND || report.name !== entry.name) {
+      manifestState = FOREIGN;
+      manifestReason = `manifest is ${report.kind ?? '?'}/${report.name ?? '?'}, expected ${EXPECTED_KIND}/${entry.name}`;
+    } else {
+      manifestState = OK;
+      manifestReason = 'bridge skill installed and manifest valid';
+      isOk = true;
+    }
+  }
+
+  const cliProbe = probeCliFn(entry.bin);
+  const credentials = probeCredentialsFn(entry);
+  const wrappers = isOk ? wrapperCmds(readManifest(resolvedDir)).map(probeWrapperFn) : [];
+  const readiness = computeReadiness(manifestState, cliProbe, credentials, wrappers);
+
+  const installed = manifestState !== NOT_INSTALLED;
+  const localPresent = installed && probeFile(join(resolvedDir, entry.setupPathLocal), deps) === PRESENT;
+  const setupHint = localPresent
+    ? { local: entry.setupPathLocal, url: entry.setupUrl }
+    : { url: entry.setupUrl };
+
+  return {
+    name: entry.name,
+    manifestState,
+    manifestReason,
+    skillDir: installed ? resolvedDir : null,
+    cli: { bin: entry.bin, state: cliProbe.state, path: cliProbe.path ?? null },
+    credentials: { state: credentials.state, path: credentials.path },
+    wrappers,
+    readiness,
+    setupHint,
+  };
+};
+
+export const detectBackends = (deps = {}) => KNOWN_BACKENDS.map((entry) => detectBackend(entry, deps));
+
+// ── report ───────────────────────────────────────────────────────────────────
+
+const MARK = { [PRESENT]: '✓', [MISSING]: '✗', [UNKNOWN]: '?' };
+const mark = (state) => MARK[state] ?? '?';
+
+const setupTarget = (s) => s.setupHint.local ?? s.setupHint.url;
+
+// Next-step hint per readiness. Deliberately never says "authenticated"/"authed" — only
+// "credentials present/missing" (detection is file-presence, not a live login check).
+const nextStep = (s) => {
+  switch (s.readiness) {
+    case READY:
+      return null;
+    case NEEDS_SKILL:
+      return `install the bridge skill — ${setupTarget(s)}`;
+    case NEEDS_CLI:
+      return `install or locate the "${s.cli.bin}" CLI on PATH`;
+    case NEEDS_CREDENTIALS:
+      return `set up credentials for "${s.cli.bin}" (marker file ${s.credentials.path} not present)`;
+    case DEGRADED:
+      return `bridge wrapper(s) not on PATH: ${s.wrappers.filter((w) => w.state !== PRESENT).map((w) => w.name).join(', ')}`;
+    default:
+      return null;
+  }
+};
+
+const fmtWrappers = (ws) =>
+  ws.length ? `wrappers ${ws.filter((w) => w.state === PRESENT).length}/${ws.length}` : 'wrappers —';
+
+export const formatReport = (statuses) => {
+  const lines = ['agent-workflow execution backends (detection only — no subscription CLI is run)', ''];
+  for (const s of statuses) {
+    lines.push(
+      `  ${s.name}  [${s.manifestState}]  ` +
+        `cli ${s.cli.bin} ${mark(s.cli.state)}  ` +
+        `credentials ${mark(s.credentials.state)}  ` +
+        `${fmtWrappers(s.wrappers)}  → ${s.readiness}`,
+    );
+    const hint = nextStep(s);
+    if (hint) lines.push(`      ↳ ${hint}`);
+  }
+  return lines.join('\n');
+};
+
+const main = (_argv, deps = {}) => {
+  console.log(formatReport(detectBackends(deps)));
+  process.exit(0); // informational, like validate.mjs non-strict — never blocks anything
+};
+
+const isDirectRun = process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href;
+if (isDirectRun) main(process.argv.slice(2));

package/tools/detect-backends.test.mjs

@@ -0,0 +1,342 @@
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { existsSync, mkdtempSync, writeFileSync, symlinkSync, chmodSync, readFileSync, readdirSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import {
+  expandTilde,
+  resolveDir,
+  findOnPath,
+  probeCredential,
+  detectBackend,
+  detectBackends,
+  formatReport,
+  KNOWN_BACKENDS,
+} from './detect-backends.mjs';
+
+const REPO = fileURLToPath(new URL('../../', import.meta.url)); // …/agent-workflow-kit/tools/ → repo root
+const KIT = join(REPO, 'agent-workflow-kit');
+const FIX = join(KIT, 'tools', 'manifest', 'fixtures');
+const HOME = '/home/u';
+
+// An ENOENT-typed error, matching the shape Node's fs throws (used to drive the wrapped probes).
+const enoent = () => Object.assign(new Error('ENOENT'), { code: 'ENOENT' });
+const eacces = () => Object.assign(new Error('EACCES'), { code: 'EACCES' });
+
+// ── pure helpers ─────────────────────────────────────────────────────────────
+
+describe('expandTilde', () => {
+  it('"~" → home', () => assert.equal(expandTilde('~', HOME), HOME));
+  it('"~/x" → home/x', () => assert.equal(expandTilde('~/x/y', HOME), join(HOME, 'x/y')));
+  it('absolute path untouched', () => assert.equal(expandTilde('/abs/path', HOME), '/abs/path'));
+  it('relative path untouched', () => assert.equal(expandTilde('rel/path', HOME), 'rel/path'));
+});
+
+describe('resolveDir', () => {
+  it('non-empty env wins, as-is', () => {
+    assert.equal(resolveDir({ env: 'D', default: '~/d' }, { D: '/from/env' }, HOME), '/from/env');
+  });
+  it('empty-string env → default', () => {
+    assert.equal(resolveDir({ env: 'D', default: '/d' }, { D: '' }, HOME), '/d');
+  });
+  it('null env name → default', () => {
+    assert.equal(resolveDir({ env: null, default: '/d' }, {}, HOME), '/d');
+  });
+  it('default is tilde-expanded', () => {
+    assert.equal(resolveDir({ env: 'D', default: '~/skills/x' }, {}, HOME), join(HOME, 'skills/x'));
+  });
+});
+
+describe('findOnPath', () => {
+  const linux = { platform: 'linux', getenv: { PATH: '/a:/b' }, realpath: (p) => p };
+
+  it('present via posix exec-bit', () => {
+    const r = findOnPath('codex', { ...linux, access: (p) => { if (p !== '/a/codex') throw enoent(); } });
+    assert.equal(r.state, 'present');
+    assert.equal(r.path, '/a/codex');
+  });
+
+  it('missing when absent everywhere', () => {
+    const r = findOnPath('codex', { ...linux, access: () => { throw enoent(); } });
+    assert.equal(r.state, 'missing');
+    assert.equal(r.path, null);
+  });
+
+  it('found in the 2nd PATH dir', () => {
+    const r = findOnPath('agy', { ...linux, access: (p) => { if (p !== '/b/agy') throw enoent(); } });
+    assert.equal(r.state, 'present');
+    assert.equal(r.path, '/b/agy');
+  });
+
+  it('Windows: matches via PATHEXT', () => {
+    const r = findOnPath('codex', {
+      platform: 'win32',
+      getenv: { PATH: 'C:\\bin', PATHEXT: '.COM;.EXE;.CMD' },
+      realpath: (p) => p,
+      access: (p) => { if (!p.endsWith('codex.EXE')) throw enoent(); },
+    });
+    assert.equal(r.state, 'present');
+    assert.ok(r.path.endsWith('codex.EXE'));
+  });
+
+  it('resolves a symlinked binary to its realpath (real fs)', () => {
+    const dir = mkdtempSync(join(tmpdir(), 'awf-path-'));
+    const target = join(dir, 'real-tool');
+    const link = join(dir, 'linked-tool');
+    writeFileSync(target, '#!/bin/sh\n');
+    chmodSync(target, 0o755);
+    symlinkSync(target, link);
+    const r = findOnPath('linked-tool', { platform: 'linux', getenv: { PATH: dir } });
+    assert.equal(r.state, 'present');
+    assert.equal(r.path, target); // realpath followed the symlink
+  });
+
+  it('accessSync throwing EACCES → unknown (cannot confirm)', () => {
+    const r = findOnPath('codex', { ...linux, access: () => { throw eacces(); } });
+    assert.equal(r.state, 'unknown');
+  });
+});
+
+describe('probeCredential', () => {
+  const entry = (over = {}) => ({ credential: { env: 'CRED', default: '~/.codex', file: 'auth.json', ...over } });
+
+  it('present when the marker file is a real file (env override honoured)', () => {
+    const r = probeCredential(entry(), { getenv: { CRED: '/cdir' }, home: HOME, exists: () => true, stat: () => ({ isFile: () => true }) });
+    assert.equal(r.state, 'present');
+    assert.equal(r.path, '/cdir/auth.json');
+  });
+
+  it('absent → missing', () => {
+    const r = probeCredential(entry(), { getenv: {}, home: HOME, exists: () => false });
+    assert.equal(r.state, 'missing');
+    assert.equal(r.path, join(HOME, '.codex/auth.json')); // env unset → tilde default
+  });
+
+  it('statSync throwing a non-ENOENT error → unknown', () => {
+    const r = probeCredential(entry(), { getenv: {}, home: HOME, exists: () => true, stat: () => { throw eacces(); } });
+    assert.equal(r.state, 'unknown');
+  });
+
+  it('credential.env:null uses the (tilde-expanded) default', () => {
+    const r = probeCredential(entry({ env: null, default: '~/.gemini/antigravity-cli', file: 'tok' }), {
+      getenv: {}, home: HOME, exists: () => true, stat: () => ({ isFile: () => true }),
+    });
+    assert.equal(r.state, 'present');
+    assert.equal(r.path, join(HOME, '.gemini/antigravity-cli/tok'));
+  });
+
+  it('never counts a directory as a present credential', () => {
+    const r = probeCredential(entry(), { getenv: { CRED: '/cdir' }, home: HOME, exists: () => true, stat: () => ({ isFile: () => false }) });
+    assert.equal(r.state, 'missing');
+  });
+});
+
+// ── detectBackend: manifestState precedence ──────────────────────────────────
+
+// Build an entry whose installed-marker is `capability.json` so a fixture without a SKILL.md still
+// registers as "installed", letting the validator branch decide the state.
+const entryAt = (dir, over = {}) => ({
+  name: 'codex-cli-bridge',
+  installed: { env: 'X_DIR', default: dir, file: 'capability.json' },
+  bin: 'codex',
+  credential: { env: null, default: '/no/such/dir', file: 'auth.json' },
+  setupUrl: 'https://example.test/setup',
+  setupPathLocal: 'setup/README.md',
+  ...over,
+});
+
+// All readiness inputs present, so manifestState is the only variable under test.
+const allPresentDeps = {
+  getenv: {},
+  probeCli: () => ({ bin: 'codex', state: 'present', path: '/usr/bin/codex' }),
+  probeCredentials: () => ({ state: 'present', path: '/c/auth.json' }),
+  probeWrapper: (cmd) => ({ name: cmd, state: 'present' }),
+};
+
+describe('detectBackend — manifestState precedence', () => {
+  it('not-installed when the marker file is absent', () => {
+    const empty = mkdtempSync(join(tmpdir(), 'awf-empty-'));
+    const d = detectBackend(entryAt(empty), allPresentDeps);
+    assert.equal(d.manifestState, 'not-installed');
+    assert.equal(d.skillDir, null);
+    assert.equal(d.readiness, 'needs-skill');
+  });
+
+  it('unsupported-schema (fixtures/unknown-schema)', () => {
+    const d = detectBackend(entryAt(join(FIX, 'unknown-schema')), allPresentDeps);
+    assert.equal(d.manifestState, 'unsupported-schema');
+  });
+
+  it('invalid-manifest (fixtures/malformed-json)', () => {
+    const d = detectBackend(entryAt(join(FIX, 'malformed-json')), allPresentDeps);
+    assert.equal(d.manifestState, 'invalid-manifest');
+  });
+
+  it('stub (fixtures/stub — available:false)', () => {
+    const d = detectBackend(entryAt(join(FIX, 'stub')), allPresentDeps);
+    assert.equal(d.manifestState, 'stub');
+  });
+
+  it('foreign (valid, but a memory-substrate, not this backend)', () => {
+    const d = detectBackend(entryAt(join(REPO, 'agent-workflow-memory')), allPresentDeps);
+    assert.equal(d.manifestState, 'foreign');
+    assert.match(d.manifestReason, /memory-substrate/);
+  });
+
+  it('ok (the real codex-cli-bridge dir, marker = SKILL.md)', () => {
+    const d = detectBackend(
+      entryAt(join(REPO, 'codex-cli-bridge'), { installed: { env: 'X_DIR', default: join(REPO, 'codex-cli-bridge'), file: 'SKILL.md' } }),
+      allPresentDeps,
+    );
+    assert.equal(d.manifestState, 'ok');
+    assert.deepEqual(d.wrappers.map((w) => w.name).sort(), ['codex-exec', 'codex-review']);
+    assert.equal(d.setupHint.local, 'setup/README.md'); // installed AND setup/README.md exists
+  });
+});
+
+// ── detectBackend: readiness matrix (over an `ok` manifest) ───────────────────
+
+const okEntry = entryAt(join(REPO, 'codex-cli-bridge'), {
+  installed: { env: 'X_DIR', default: join(REPO, 'codex-cli-bridge'), file: 'SKILL.md' },
+});
+
+describe('detectBackend — readiness over an ok manifest', () => {
+  it('ready when cli + credentials + every wrapper present', () => {
+    assert.equal(detectBackend(okEntry, allPresentDeps).readiness, 'ready');
+  });
+
+  it('needs-cli when the CLI is missing', () => {
+    const d = detectBackend(okEntry, { ...allPresentDeps, probeCli: () => ({ bin: 'codex', state: 'missing', path: null }) });
+    assert.equal(d.readiness, 'needs-cli');
+  });
+
+  it('needs-cli when the CLI is unknown (unknown never counts as present)', () => {
+    const d = detectBackend(okEntry, { ...allPresentDeps, probeCli: () => ({ bin: 'codex', state: 'unknown', path: null }) });
+    assert.equal(d.readiness, 'needs-cli');
+  });
+
+  it('needs-credentials when the credential marker is missing', () => {
+    const d = detectBackend(okEntry, { ...allPresentDeps, probeCredentials: () => ({ state: 'missing', path: '/c/auth.json' }) });
+    assert.equal(d.readiness, 'needs-credentials');
+  });
+
+  it('degraded when a wrapper is missing from PATH', () => {
+    const d = detectBackend(okEntry, {
+      ...allPresentDeps,
+      probeWrapper: (cmd) => ({ name: cmd, state: cmd === 'codex-review' ? 'missing' : 'present' }),
+    });
+    assert.equal(d.readiness, 'degraded');
+  });
+
+  it('needs-skill dominates even when cli + credentials are present', () => {
+    const empty = mkdtempSync(join(tmpdir(), 'awf-empty2-'));
+    const d = detectBackend(entryAt(empty), allPresentDeps);
+    assert.equal(d.readiness, 'needs-skill');
+  });
+});
+
+// ── registry drift guard ─────────────────────────────────────────────────────
+
+const readManifest = (dir) => JSON.parse(readFileSync(join(dir, 'capability.json'), 'utf8'));
+
+// Every top-level in-repo dir with a kind:execution-backend manifest, discovered fresh from disk.
+const inRepoBackends = () =>
+  readdirSync(REPO, { withFileTypes: true })
+    .filter((e) => e.isDirectory() && existsSync(join(REPO, e.name, 'capability.json')))
+    .filter((e) => readManifest(join(REPO, e.name)).kind === 'execution-backend')
+    .map((e) => e.name);
+
+describe('KNOWN_BACKENDS — drift guard against the in-repo manifests', () => {
+  it('set equality: registry names == in-repo execution-backend dirs', () => {
+    const onDisk = inRepoBackends().sort();
+    const registry = KNOWN_BACKENDS.map((b) => b.name).sort();
+    assert.deepEqual(registry, onDisk);
+  });
+
+  it('the methodology-engine is NOT counted as a backend', () => {
+    assert.ok(!KNOWN_BACKENDS.some((b) => b.name === 'agent-workflow-engine'));
+    assert.equal(readManifest(join(REPO, 'agent-workflow-engine')).kind, 'methodology-engine');
+  });
+
+  it('registry names are unique', () => {
+    const names = KNOWN_BACKENDS.map((b) => b.name);
+    assert.equal(new Set(names).size, names.length);
+  });
+
+  it('each entry.installed matches the real manifest detect.installed', () => {
+    for (const entry of KNOWN_BACKENDS) {
+      const real = readManifest(join(REPO, entry.name)).detect.installed;
+      assert.equal(entry.installed.env, real.env, `${entry.name} env`);
+      assert.equal(entry.installed.default, real.default, `${entry.name} default`);
+      assert.equal(entry.installed.file, real.file, `${entry.name} file`);
+    }
+  });
+
+  it('each entry.setupPathLocal exists in the repo', () => {
+    for (const entry of KNOWN_BACKENDS) {
+      assert.ok(existsSync(join(REPO, entry.name, entry.setupPathLocal)), `${entry.name}/${entry.setupPathLocal}`);
+    }
+  });
+});
+
+// ── formatReport ─────────────────────────────────────────────────────────────
+
+const readyStatus = {
+  name: 'codex-cli-bridge',
+  manifestState: 'ok',
+  manifestReason: 'ok',
+  skillDir: '/skills/codex-cli-bridge',
+  cli: { bin: 'codex', state: 'present', path: '/usr/bin/codex' },
+  credentials: { state: 'present', path: '/home/u/.codex/auth.json' },
+  wrappers: [{ name: 'codex-exec', state: 'present' }, { name: 'codex-review', state: 'present' }],
+  readiness: 'ready',
+  setupHint: { local: 'setup/README.md', url: 'https://example.test/codex' },
+};
+const needsSkillStatus = {
+  name: 'antigravity-cli-bridge',
+  manifestState: 'not-installed',
+  manifestReason: 'not installed',
+  skillDir: null,
+  cli: { bin: 'agy', state: 'present', path: '/home/u/.local/bin/agy' },
+  credentials: { state: 'present', path: '/home/u/.gemini/antigravity-cli/antigravity-oauth-token' },
+  wrappers: [],
+  readiness: 'needs-skill',
+  setupHint: { url: 'https://example.test/agy' },
+};
+
+describe('formatReport', () => {
+  const out = formatReport([readyStatus, needsSkillStatus]);
+
+  it('never says "authenticated" or "authed" (credentials = file presence, not a live login)', () => {
+    const low = out.toLowerCase();
+    assert.ok(!low.includes('authenticated'));
+    assert.ok(!low.includes('authed'));
+  });
+
+  it('uses the word "credentials"', () => assert.ok(out.toLowerCase().includes('credentials')));
+
+  it('shows the ready backend as ready', () => {
+    assert.match(out, /codex-cli-bridge.*ready/s);
+  });
+
+  it('a needs-skill backend (CLI + creds present) says install the bridge + points at the setup URL', () => {
+    assert.match(out, /needs-skill/);
+    assert.match(out, /install the bridge/);
+    assert.match(out, /https:\/\/example\.test\/agy/);
+  });
+});
+
+describe('detectBackends — live shape on this machine', () => {
+  it('returns one status per registry entry with all data-model keys', () => {
+    const statuses = detectBackends();
+    assert.equal(statuses.length, KNOWN_BACKENDS.length);
+    for (const s of statuses) {
+      for (const key of ['name', 'manifestState', 'manifestReason', 'cli', 'credentials', 'wrappers', 'readiness', 'setupHint']) {
+        assert.ok(key in s, `${s.name} missing ${key}`);
+      }
+      assert.ok(['present', 'missing', 'unknown'].includes(s.cli.state));
+      assert.ok(['present', 'missing', 'unknown'].includes(s.credentials.state));
+    }
+  });
+});