@codedology/code-forge 0.2.1 → 0.2.2

package/CHANGELOG.md

@@ -6,6 +6,23 @@ waits on a second real consumer (plan §10.4, Q17).
 
 ## [Unreleased]
 
+## [0.2.2] — 2026-10-01
+
+### Added
+
+- 1Password item ID or item link accepted for the Jev key (init question, --jev-ref, keys set --op, keys test --ref):
+  code-forge finds the vault and key field and saves a full op:// reference of IDs; 1Password failures (CLI missing,
+  locked, timeout, not found, bad output, no key field) get one clear message, a retry/skip menu in init, and never
+  write a partial config
+- code-forge tools: lists the recommended tools (claude, codex, gemini, grok, op, solo) as installed with their version
+  or missing with the install command; code-forge tools install [<id>...] [--yes] [--dry-run] installs the missing ones
+  after one yes. init step 1 and doctor use the same tool table; doctor adds an INFO line naming the missing tools.
+
+### Changed
+
+- Releases: CI no longer publishes to npm. Publish with `npm publish` from your machine, then push the tag; the tag push
+  only creates the GitHub release (`.github/workflows/release.yml`).
+
 ## [0.2.1] — 2026-10-01
 
 ### Changed

package/README.md

@@ -39,8 +39,12 @@ for later. Non-interactively:
 code-forge init --no-interaction --no-jev
 ```
 
-`--no-jev` skips the System-1 key for a first try; drop it and pass `--jev-ref op://vault/item/field`
-or `--jev-env MY_JEV_KEY` once you have one. A second run of `init` changes nothing it already wrote.
+`--no-jev` skips the System-1 key for a first try; drop it and pass `--jev-ref <1Password item ID>`
+(or the item link, or `op://vault/item/field`; code-forge finds the vault and the key field) or
+`--jev-env MY_JEV_KEY` once you have one. A second run of `init` changes nothing it already wrote.
+
+To upgrade: `npm install -g @codedology/code-forge@latest`, then `code-forge upgrade` (re-copies
+skill installs made with `--copy`). See [docs/getting-started.md](docs/getting-started.md#keeping-it-up-to-date).
 
 ## Quickstart
 
@@ -79,8 +83,9 @@ usage line.
 
 | Verb | Usage |
 |---|---|
-| `init` | `code-forge init [--no-interaction] [--tools recommended\|current] [--yes-tool <tool>]… [--harness a,b] [-g\|-p] [--copy] [--provider P] [--level Ln=model[:effort][@provider]]… [--refresh-models] [--multimodel on\|off] [--second-provider P] [--jev-ref op://… \| --jev-env NAME \| --no-jev] [--engine auto\|solo\|harness] [--solo-project N] [--gate name=cmd]… [--proof isolation=export\|lock \| high=a,b \| link_dirs=a,b \| copy_untracked=a,b]… [--skip-doctor]` |
+| `init` | `code-forge init [--no-interaction] [--tools recommended\|current] [--yes-tool <tool>]… [--harness a,b] [-g\|-p] [--copy] [--provider P] [--level Ln=model[:effort][@provider]]… [--refresh-models] [--multimodel on\|off] [--second-provider P] [--jev-ref <item-id\|link\|op://…> \| --jev-env NAME \| --no-jev] [--engine auto\|solo\|harness] [--solo-project N] [--gate name=cmd]… [--proof isolation=export\|lock \| high=a,b \| link_dirs=a,b \| copy_untracked=a,b]… [--skip-doctor]` |
 | `doctor` | `code-forge doctor [--quick] [--json] [--cwd <dir>]` |
+| `tools` | `code-forge tools [--json]` · `code-forge tools install [<id>…] [--yes] [--dry-run]` — see and install the recommended tools (claude, codex, gemini, grok, op, solo) |
 | `validate` | `code-forge validate [--file <path>]` |
 | `resolve` | `code-forge resolve <L0\|L1\|L2\|L3>` |
 | `run` | `code-forge run start [--cwd <dir>] [--run <id>] [--engine <e>] [--worker-pid <pid>]` · `run start --reattach --run <id>` · `run status --run <id>` · `run end --run <id>` |

package/docs/reference/blocks.json

@@ -1,10 +1,10 @@
 {
-  "$comment": "hand-maintained; checked against plan §10.4 + NIGHT-LOG by test/docs-blocks.test.mjs. Ids = every `| **Bxx** |` row in plans/code-forge-plan-v1.3.md §10.4 Waves 2-6 (19 ids), plus the blocks the root orchestrator added during the night run of 2026-09-25 that are not in that table (plans/NIGHT-LOG.md): B1.2, B4.1, B11.1, B12c (B3.1 was already in the v1.3 §10.4 table); plus B22 (the review-only verb), which the root added on 2026-09-26 after the night run. Wave 0-1 blocks (B0-B8) are the pre-v1.3 baseline landed before this plan revision; they have no entry under blocks and are listed in baseline_ids so every depends_on id resolves; see plans/code-forge-plan-v1.3.md §10.2-§10.3 for their record. B10c is listed with deleted:true — the maintainer answered Q16 'cut' on 2026-09-25, so B10c (consumer-facing mutation-testing tools) never lands.",
+  "$comment": "hand-maintained; checked against plan §10.4 + NIGHT-LOG by test/docs-blocks.test.mjs. Ids = every `| **Bxx** |` row in plans/code-forge-plan-v1.3.md §10.4 Waves 2-6 (19 ids), plus the blocks the root orchestrator added during the night run of 2026-09-25 that are not in that table (plans/NIGHT-LOG.md): B1.2, B4.1, B11.1, B12c (B3.1 was already in the v1.3 §10.4 table); plus B22 (the review-only verb) and B23 (release tools), which the root added on 2026-09-26 after the night run, and B24 (init project settings) and B25 (1Password item IDs), added on 2026-10-01. Wave 0-1 blocks (B0-B8) are the pre-v1.3 baseline landed before this plan revision; they have no entry under blocks and are listed in baseline_ids so every depends_on id resolves; see plans/code-forge-plan-v1.3.md §10.2-§10.3 for their record. B10c is listed with deleted:true — the maintainer answered Q16 'cut' on 2026-09-25, so B10c (consumer-facing mutation-testing tools) never lands.",
   "checked_against": [
     "plans/code-forge-plan-v1.3.md §10.4",
     "plans/NIGHT-LOG.md"
   ],
-  "block_count": 24,
+  "block_count": 28,
   "baseline_ids": ["B0", "B1", "B2", "B3", "B4", "B5", "B6", "B7", "B8"],
   "baseline_note": "Wave 0-1 blocks, landed before v1.3; depends_on may name them, but they have no entry under blocks.",
   "blocks": {
@@ -288,12 +288,64 @@
       "title": "Review-only verb: code-forge review (base/file discovery, run start -> block open -> review-file -> block stop -> run end) and its docs",
       "wave": 6,
       "level": "L2",
-      "status": "in_review",
+      "status": "landed",
+      "commit": "1e9ea32",
       "owned": [
         "src/cli/review.mjs", "test/cli/review.test.mjs", "docs/review-only.md"
       ],
       "depends_on": ["B11", "B12a", "B12c"],
       "note": "root-added 2026-09-26 (after the night run); not in the v1.3 §10.4 table"
+    },
+    "B23": {
+      "title": "Release and changelog tools: npm run release (bump, CHANGELOG, checks, commit, tag), npm run changelog, GitHub Releases linked to the npm publish; both publish paths",
+      "wave": 6,
+      "level": "L2",
+      "status": "landed",
+      "commit": "805dca8",
+      "owned": [
+        "scripts/release.mjs", "scripts/changelog.mjs", ".github/workflows/release.yml",
+        "test/release.test.mjs", "docs/releasing.md"
+      ],
+      "depends_on": ["B16"],
+      "note": "root-added 2026-09-26; not in the v1.3 §10.4 table. Both publish paths (by hand or CI) added in d61623f; on 2026-10-01 CI publishing was removed (publish.yml became release.yml: GitHub release only, npm publish by hand)"
+    },
+    "B24": {
+      "title": "init project settings: detect gates and proof settings, print a summary that marks every blank, one choice (Use these / Customize now / Leave for later)",
+      "wave": 6,
+      "level": "L2",
+      "status": "landed",
+      "commit": "fa915c7",
+      "owned": [
+        "src/install/wizard/answers.mjs", "src/install/wizard/run.mjs", "src/install/wizard/steps.mjs",
+        "src/install/wizard/summary.mjs", "test/init/settings.test.mjs", "docs/getting-started.md"
+      ],
+      "depends_on": ["B13a"],
+      "note": "root-added 2026-10-01; not in the v1.3 §10.4 table. Released in 0.2.1"
+    },
+    "B25": {
+      "title": "1Password item ID or item link for the Jev key: resolve vault and key field with op item get, save an op:// reference of IDs; classified 1Password failures with a retry/skip menu",
+      "wave": 6,
+      "level": "L2",
+      "status": "landed",
+      "owned": [
+        "src/keys/onepassword.mjs", "src/cli/keys.mjs", "src/doctor/local.mjs",
+        "test/keys/onepassword.test.mjs", "test/init/onepassword.test.mjs"
+      ],
+      "depends_on": ["B24"],
+      "note": "root-added 2026-10-01; not in the v1.3 §10.4 table"
+    },
+    "B26": {
+      "title": "code-forge tools: see and install the recommended tools from one shared table (status, versions, install plan with one yes); init step 1 and doctor use the same table",
+      "wave": 6,
+      "level": "L2",
+      "status": "landed",
+      "owned": [
+        "src/install/tools.mjs", "src/cli/tools.mjs", "src/install/wizard/run.mjs", "src/install/wizard/flags.mjs",
+        "src/doctor/local.mjs", "src/doctor/index.mjs",
+        "test/cli/tools.test.mjs", "test/init/tools.test.mjs"
+      ],
+      "depends_on": ["B13a"],
+      "note": "root-added 2026-10-01; not in the v1.3 §10.4 table"
     }
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codedology/code-forge",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "description": "Plan/harden/code/review orchestration CLI and Agent Skill for cross-model, parallel, evidence-gated feature delivery.",
   "repository": {
     "type": "git",

package/skill/scripts/forge

@@ -10,7 +10,7 @@
 #      copied install with no package next to it); `test/skill/shim.test.mjs` asserts the pin
 #      equals package.json's version.
 # The shim holds no logic of its own: every verb, flag and message is the CLI's.
-PINNED_VERSION="0.2.1"
+PINNED_VERSION="0.2.2"
 set -eu
 
 self="$0"

package/src/cli/keys.mjs

@@ -5,18 +5,21 @@
  * message would be masked once the chain registered it.
  *
  *   keys list
- *   keys set <name> [--op <op://ref>]    hidden prompt, or read once from 1Password and cache 8 h
+ *   keys set <name> [--op <ref>]         hidden prompt, or read once from 1Password and cache 8 h
  *   keys test <name> [--ref <ref>]       resolve through the chain (no prompt)
  *   keys remove <name>
  *
+ * An `--op`/`--ref` value may be a 1Password item ID or item link instead of `op://vault/item/field`:
+ * it is resolved to `op://<vaultId>/<itemId>/<fieldId>` first (`op item get`, B25).
+ *
  * Every name is validated before any store call, on every subcommand.
  */
 
 import { writeSafe } from '../util/redact.mjs';
-import { isOpRef } from '../keys/onepassword.mjs';
+import { describeOpItem, isOpRef, OP_MESSAGES, opItemIdFromInput, toOpRef } from '../keys/onepassword.mjs';
 import { assertKeyName, createDefaultKeyStore, parseRef, readOpAndCache, resolveKey } from '../keys/store.mjs';
 
-const USAGE = 'usage: code-forge keys list | set <name> [--op <ref>] | test <name> [--ref <ref>] | remove <name>\n';
+const USAGE = 'usage: code-forge keys list | set <name> [--op <item-id|link|op://ref>] | test <name> [--ref <ref>] | remove <name>\n';
 
 /** The one flag each subcommand accepts (list and remove take none). */
 const FLAGS = /** @type {Record<string, string|null>} */ ({ list: null, set: '--op', test: '--ref', remove: null });
@@ -76,11 +79,12 @@ async function askHidden(name) {
  * @param {{write: (s: string) => unknown}} [deps.stderr]
  * @param {(name: string) => Promise<string|null>} [deps.ask]
  * @param {typeof import('../keys/onepassword.mjs').opRead} [deps.opRead]
+ * @param {typeof import('../util/exec.mjs').exec} [deps.opExec] - runs `op item get` for an item ID or link.
  * @param {NodeJS.ProcessEnv} [deps.env]
  * @param {number} [deps.now]
  * @returns {Promise<number>}
  */
-export async function runKeys(args, { store, stdout = process.stdout, stderr = process.stderr, ask = askHidden, opRead, env = process.env, now = Date.now() }) {
+export async function runKeys(args, { store, stdout = process.stdout, stderr = process.stderr, ask = askHidden, opRead, opExec, env = process.env, now = Date.now() }) {
   const out = (/** @type {string} */ s) => writeSafe(stdout, s);
   const err = (/** @type {string} */ s) => writeSafe(stderr, s);
 
@@ -89,11 +93,41 @@ export async function runKeys(args, { store, stdout = process.stdout, stderr = p
     err(USAGE);
     return 2;
   }
-  const { sub, name, flagArg } = parsed;
+  const { sub, name } = parsed;
+  let { flagArg } = parsed;
   try {
     if (name !== undefined) {
       assertKeyName(name);
     }
+  } catch (e) {
+    err(`keys: ${e.message}\n`);
+    return 2;
+  }
+  const fullRef = flagArg !== undefined && isOpRef(flagArg);
+  const itemId = flagArg !== undefined && !fullRef ? opItemIdFromInput(flagArg) : null;
+  if (sub === 'set' && flagArg !== undefined && !fullRef && itemId === null) {
+    err(`${name}: --op must be a 1Password item ID, item link or op://vault/item/field reference\n`);
+    return 2;
+  }
+  // A 1Password item ID or link becomes a full op:// reference before any store call (B25).
+  if (flagArg !== undefined && itemId !== null) {
+    /** @type {Awaited<ReturnType<typeof toOpRef>>} */
+    let res;
+    try {
+      res = await toOpRef(flagArg, opExec ? { exec: opExec } : {});
+    } catch {
+      // never the thrown message: it could carry op output
+      res = { ref: null, kind: 'op_failed', error: `${OP_MESSAGES.op_failed} (unexpected error); run \`op item get ${itemId}\` yourself to see why` };
+    }
+    if (res.ref === null) {
+      err(`${name}: ${res.error ?? OP_MESSAGES.op_failed}\n`);
+      return 1;
+    }
+    const found = describeOpItem(res);
+    out(`${name}: ${found ? `${found} -> ` : ''}${res.ref}\n`);
+    flagArg = res.ref;
+  }
+  try {
     if (sub === 'test' && flagArg !== undefined) {
       parseRef(name, flagArg);
     }
@@ -101,10 +135,6 @@ export async function runKeys(args, { store, stdout = process.stdout, stderr = p
     err(`keys: ${e.message}\n`);
     return 2;
   }
-  if (sub === 'set' && flagArg !== undefined && !isOpRef(flagArg)) {
-    err(`${name}: --op must be an op://vault/item/field reference\n`);
-    return 2;
-  }
 
   if (store.warning) {
     err(`WARN ${store.warning}\n`);

package/src/cli/tools.mjs

@@ -0,0 +1,221 @@
+/**
+ * `code-forge tools` (block B26): see and install the recommended tools of the shared table
+ * (`src/install/tools.mjs`).
+ *
+ *   tools [--json]                               one line per tool; exit 0 always
+ *   tools install [<id>...] [--yes] [--dry-run]  install the missing (or the named) tools
+ *
+ * `install` shows the plan (each command as argv, joined for display only), asks ONE yes (default
+ * no) unless `--yes`; without a terminal and without `--yes` it prints the plan, installs nothing
+ * and exits 2. Each install runs through B0 `exec` (argv, never a shell); a failure does not stop
+ * the others; presence is re-checked afterwards. The final table lists the tools acted on (and,
+ * with named ids, "already installed"); a failure says why: `failed (exit n | signal S | timed out
+ * | did not start)`. Exit 0 when every requested install succeeded, 1 when any failed or the yes
+ * was refused ("cancelled — nothing installed", exit 1, as in init), 2 on a usage error. Manual tools are never "failed"
+ * and no browser is ever opened.
+ */
+
+import { exec as realExec } from '../util/exec.mjs';
+import { writeSafe } from '../util/redact.mjs';
+import { detectTool, failureReason, installPlan, TOOL_IDS, TOOLS, toolById, toolVersion } from '../install/tools.mjs';
+import { parseFlags } from '../state/cli-args.mjs';
+
+const USAGE = 'usage: code-forge tools [--json] | tools install [<id>...] [--yes] [--dry-run]\n  (install asks one yes, default no; answering no prints "cancelled — nothing installed" and exits 1)\n';
+
+/** An install may take a while (npm, brew); a hung one is killed after this. */
+const INSTALL_TIMEOUT_MS = 600_000;
+
+/** @typedef {{write: (s: string) => unknown}} Out */
+
+/**
+ * @typedef {object} ToolsDeps
+ * @property {NodeJS.ProcessEnv} [env]
+ * @property {Out} [stdout]
+ * @property {Out} [stderr]
+ * @property {boolean} [isTTY] - whether stdin is a terminal (default `process.stdin.isTTY`).
+ * @property {{confirm: (o: {message: string, initialValue?: boolean}) => Promise<any>, isCancel: (v: unknown) => boolean}} [ui] - default `@clack/prompts`.
+ * @property {typeof realExec} [exec] - runs `--version` and the installs (tests: a fake).
+ * @property {NodeJS.Platform} [platform]
+ * @property {(p: string) => boolean} [exists] - the Solo app bundle check (tests: a fake).
+ */
+
+/**
+ * @typedef {object} ToolStatus
+ * @property {string} id
+ * @property {'installed'|'missing'} status
+ * @property {string|null} version
+ * @property {string[]|null} install - the argv that would install it (missing only).
+ * @property {string|null} hint - the manual hint (missing only, when there is no argv).
+ * @property {string|null} note
+ */
+
+/** @param {ToolsDeps} deps */
+function toolEnv(deps) {
+  const env = deps.env ?? process.env;
+  return { pathEnv: env.PATH ?? '', platform: deps.platform ?? process.platform, home: env.HOME ?? '', ...(deps.exists ? { exists: deps.exists } : {}) };
+}
+
+/**
+ * @param {ToolsDeps} deps
+ * @returns {Promise<ToolStatus[]>}
+ */
+export async function toolStatuses(deps = {}) {
+  const opts = toolEnv(deps);
+  const exec = deps.exec ?? realExec;
+  const env = deps.env ?? process.env;
+  /** @type {ToolStatus[]} */
+  const out = [];
+  for (const tool of TOOLS) {
+    if (await detectTool(tool, opts)) {
+      out.push({ id: tool.id, status: 'installed', version: await toolVersion(tool, { exec, env }), install: null, hint: null, note: tool.note });
+    } else {
+      const plan = await installPlan(tool, opts);
+      out.push({ id: tool.id, status: 'missing', version: null, install: plan.kind === 'run' ? plan.argv : null, hint: plan.kind === 'manual' ? plan.hint : null, note: null });
+    }
+  }
+  return out;
+}
+
+/** @param {ToolStatus} s @returns {string} one line, no newline */
+export function renderStatus(s) {
+  if (s.status === 'installed') return `${s.id.padEnd(7)} installed  ${s.version ?? 'version unknown'}${s.note ? ` — ${s.note}` : ''}`;
+  return `${s.id.padEnd(7)} missing    ${s.install ? `install: ${s.install.join(' ')}` : `manual: ${s.hint}`}`;
+}
+
+/**
+ * @param {string[]} args
+ * @param {ToolsDeps} [deps]
+ * @returns {Promise<number>}
+ */
+export async function runTools(args, deps = {}) {
+  const stdout = deps.stdout ?? process.stdout;
+  const stderr = deps.stderr ?? process.stderr;
+  const out = (/** @type {string} */ s) => writeSafe(stdout, s);
+  const err = (/** @type {string} */ s) => writeSafe(stderr, s);
+
+  if (args[0] === 'install') return runInstall(args.slice(1), deps, out, err);
+
+  let parsed;
+  try {
+    parsed = parseFlags(args, { booleans: ['json'] });
+  } catch (e) {
+    err(`tools: ${e.message}\n${USAGE}`);
+    return 2;
+  }
+  if (parsed.positionals.length > 0) {
+    err(`tools: unknown subcommand ${JSON.stringify(parsed.positionals[0])}\n${USAGE}`);
+    return 2;
+  }
+  const statuses = await toolStatuses(deps);
+  if (parsed.flags.json) {
+    out(`${JSON.stringify({ tools: statuses })}\n`);
+  } else {
+    for (const s of statuses) out(`${renderStatus(s)}\n`);
+  }
+  return 0;
+}
+
+/**
+ * @param {string[]} args @param {ToolsDeps} deps
+ * @param {(s: string) => void} out @param {(s: string) => void} err
+ * @returns {Promise<number>}
+ */
+async function runInstall(args, deps, out, err) {
+  let parsed;
+  try {
+    parsed = parseFlags(args, { booleans: ['yes', 'dry-run'] });
+  } catch (e) {
+    err(`tools: ${e.message}\n${USAGE}`);
+    return 2;
+  }
+  const ids = [...new Set(parsed.positionals)];
+  const unknown = ids.filter((id) => !TOOL_IDS.includes(id));
+  if (unknown.length > 0) {
+    err(`tools: unknown tool id(s): ${unknown.join(', ')} — valid ids: ${TOOL_IDS.join(', ')}\n${USAGE}`);
+    return 2;
+  }
+  const opts = toolEnv(deps);
+  const env = deps.env ?? process.env;
+  const exec = deps.exec ?? realExec;
+  const named = ids.length > 0;
+  const wanted = named ? TOOLS.filter((t) => ids.includes(t.id)) : TOOLS;
+
+  /** @type {Array<{id: string, result: string}>} */
+  const table = [];
+  /** @type {Array<{id: string, argv: string[]}>} */
+  const runs = [];
+  /** @type {Array<{id: string, hint: string}>} */
+  const manual = [];
+  for (const tool of wanted) {
+    if (await detectTool(tool, opts)) {
+      if (named) table.push({ id: tool.id, result: 'already installed' });
+      continue;
+    }
+    const plan = await installPlan(tool, opts);
+    if (plan.kind === 'run') runs.push({ id: tool.id, argv: plan.argv });
+    else manual.push({ id: tool.id, hint: plan.hint });
+  }
+
+  if (runs.length === 0 && manual.length === 0) {
+    out(named ? '' : 'all recommended tools are installed\n');
+    printTable(out, table);
+    return 0;
+  }
+
+  out('plan:\n');
+  for (const r of runs) out(`  ${r.id}: ${r.argv.join(' ')}\n`);
+  for (const m of manual) out(`  ${m.id}: manual — ${m.hint}\n`);
+
+  if (parsed.flags['dry-run']) {
+    out('dry run: nothing installed\n');
+    return 0;
+  }
+  if (runs.length > 0 && !parsed.flags.yes) {
+    if (!(deps.isTTY ?? process.stdin.isTTY === true)) {
+      err('tools: no terminal to confirm; nothing installed — pass --yes to install the plan above\n');
+      return 2;
+    }
+    const ui = deps.ui ?? /** @type {any} */ (await import('@clack/prompts'));
+    const go = await ui.confirm({ message: `Run ${runs.length} install command(s)?`, initialValue: false });
+    if (ui.isCancel(go) || go !== true) {
+      out('cancelled — nothing installed\n');
+      return 1;
+    }
+  }
+
+  let failed = 0;
+  for (const r of runs) {
+    out(`\n$ ${r.argv.join(' ')}\n`);
+    let res;
+    try {
+      res = await exec(r.argv, { timeoutMs: INSTALL_TIMEOUT_MS, env });
+    } catch (e) {
+      // a spawn that throws reads "did not start"; its message is never printed
+      res = { result: 'failed', code: null, signal: null, stdout: '', stderr: '', timedOut: false };
+    }
+    if (res.stdout) out(res.stdout.endsWith('\n') ? res.stdout : `${res.stdout}\n`);
+    if (res.stderr) err(res.stderr.endsWith('\n') ? res.stderr : `${res.stderr}\n`);
+    if (res.result === 'ok') {
+      const tool = /** @type {NonNullable<ReturnType<typeof toolById>>} */ (toolById(r.id));
+      const present = await detectTool(tool, opts);
+      table.push({ id: r.id, result: present ? 'installed' : 'installed (not on PATH yet — open a new shell)' });
+    } else {
+      failed += 1;
+      table.push({ id: r.id, result: `failed (${failureReason(res)})` });
+    }
+  }
+  for (const m of manual) table.push({ id: m.id, result: `skipped: manual — ${m.hint}` });
+  out('\n');
+  printTable(out, table);
+  return failed > 0 ? 1 : 0;
+}
+
+/** @param {(s: string) => void} out @param {Array<{id: string, result: string}>} table */
+function printTable(out, table) {
+  for (const t of table) out(`${t.id.padEnd(7)} ${t.result}\n`);
+}
+
+/** @param {string[]} args @returns {Promise<number>} */
+export default async function tools(args) {
+  return runTools(args);
+}

package/src/doctor/index.mjs

@@ -13,7 +13,7 @@ import path from 'node:path';
 import { cliNameForProvider } from '../engines/provider-cli.mjs';
 import { newRunId } from '../state/paths.mjs';
 import { runRoot } from '../util/tmp.mjs';
-import { checkCommands, checkConfig, checkJev, checkKeys, checkLedger, checkLinks, checkTmp } from './local.mjs';
+import { checkCommands, checkConfig, checkJev, checkKeys, checkLedger, checkLinks, checkTmp, checkTools } from './local.mjs';
 import { configuredProviders, pingRoles, probeCli, probeCodexRules, probeIsolation, probePathDeny } from './probes.mjs';
 import { row } from './rows.mjs';
 import { probeWorkerAndSigner, SIGNER_ROW } from './worker-probe.mjs';
@@ -28,6 +28,8 @@ import { probeWorkerAndSigner, SIGNER_ROW } from './worker-probe.mjs';
  * @property {any} [opRead]
  * @property {typeof import('../decide/jev-client.mjs').askJev} [askJev]
  * @property {string} [canary] - the path-deny canary (tests).
+ * @property {NodeJS.Platform} [platform] - the recommended-tools row (default `process.platform`).
+ * @property {(p: string) => boolean} [toolExists] - the recommended-tools row's Solo app check (tests).
  */
 
 /** @param {Record<string, any> | null} cfg @returns {string} a new, private run root for the probes. */
@@ -57,6 +59,13 @@ export async function runDoctor(opts = {}, deps = {}) {
     rows.push(...(await checkCommands(cfg, env.PATH ?? '')));
     rows.push(...(await checkJev(cfg, keys.key, { askJev: deps.askJev })));
   }
+  const toolOpts = {
+    pathEnv: env.PATH ?? '',
+    platform: deps.platform ?? process.platform,
+    home: env.HOME || os.homedir(),
+    ...(deps.toolExists ? { exists: deps.toolExists } : {}),
+  };
+  rows.push(...(await checkTools(toolOpts)));
   rows.push(...(await checkLedger()));
   rows.push(...checkTmp(cfg));
   if (!cfg) {

package/src/doctor/local.mjs

@@ -13,6 +13,8 @@ import { askJev as realAskJev } from '../decide/jev-client.mjs';
 import { buildQuestionPayload } from '../decide/questions.mjs';
 import { commandOnPath } from '../install/detect.mjs';
 import { installsPath, readInstalls, targetResolves } from '../install/link.mjs';
+import { missingTools } from '../install/tools.mjs';
+import { OP_MESSAGES } from '../keys/onepassword.mjs';
 import { createDefaultKeyStore, resolveKey } from '../keys/store.mjs';
 import { ledgerDir } from '../ledger/paths.mjs';
 import { listEntries } from '../util/reaper.mjs';
@@ -71,7 +73,16 @@ export async function checkKeys(cfg, deps) {
     const store = deps.store ?? (await createDefaultKeyStore(deps.env));
     const ref = cfg?.system1?.key ?? cfg?.keys?.jev;
     const res = await resolveKey('jev', { store, env: deps.env, ref: typeof ref === 'string' ? ref : undefined, ...(deps.opRead ? { opRead: deps.opRead } : {}) });
-    if (res.value === null) return { rows: [row('keys', 'WARN', 'keys', 'jev key not resolved; System 1 falls back to rules')], key: null };
+    if (res.value === null) {
+      // only fixed texts are shown: a 1Password failure by its classified message (B25), any other
+      // reason as a fixed "key store error" — never a reference, a path or tool output
+      const known = Object.values(OP_MESSAGES);
+      const reasons = Array.isArray(res.errors)
+        ? [...new Set(res.errors.map((e) => known.find((m) => typeof e === 'string' && (e === m || e.startsWith(m))) ?? 'key store error'))]
+        : [];
+      const why = reasons.length > 0 ? ` (${reasons.join('; ')})` : '';
+      return { rows: [row('keys', 'WARN', 'keys', `jev key not resolved${why}; System 1 falls back to rules`)], key: null };
+    }
     const exp = res.exp === null ? 'no expiry' : `expires ${new Date(res.exp).toISOString()}`;
     return { rows: [row('keys', 'OK', 'keys', `jev key from ${res.source}, ${exp}`)], key: res.value };
   } catch (err) {
@@ -101,6 +112,23 @@ export async function checkCommands(cfg, pathEnv) {
   return rows;
 }
 
+/**
+ * The recommended tools of the shared table (B26): one INFO row naming the missing ones, none
+ * when all are there. A missing optional tool never WARNs or FAILs.
+ * @param {import('../install/tools.mjs').ToolEnv} opts
+ * @returns {Promise<Row[]>}
+ */
+export async function checkTools(opts) {
+  let missing;
+  try {
+    missing = await missingTools(opts);
+  } catch {
+    return [row('tools', 'INFO', 'tools', 'could not check recommended tools')];
+  }
+  if (missing.length === 0) return [];
+  return [row('tools', 'INFO', 'tools', `missing recommended tools: ${missing.join(', ')} — run code-forge tools install`)];
+}
+
 /**
  * One live Jev call (a `risk` question on a two-line state). Without a key it is skipped (WARN);
  * a bad key or a malformed answer FAILs; a transient failure WARNs.