yadflow 4.1.0 → 4.2.0

package/CHANGELOG.md

@@ -1,3 +1,22 @@
+# [4.2.0](https://github.com/abdelrahmannasr/yadflow/compare/v4.1.0...v4.2.0) (2026-10-01)
+
+
+### Bug Fixes
+
+* **toolbox:** a turned-off plugin is disabled, and ranges read only full versions (E84 review 1) ([56a9864](https://github.com/abdelrahmannasr/yadflow/commit/56a9864bf91b764b736c6da12b2d30cc1d1fd861))
+* **toolbox:** add and remove report a shipped-tool edit through one function (E86 review 4) ([161ece4](https://github.com/abdelrahmannasr/yadflow/commit/161ece48cffd879fe0106747ae10698f7b5e67cf))
+* **toolbox:** clearer remove and dead-copy wording (E86 review 5 notes) ([33ba0b7](https://github.com/abdelrahmannasr/yadflow/commit/33ba0b7bae11462d9b81a739df302fe20bbd2a7c))
+* **toolbox:** npx before a turned-off plugin, Claude Code switches only, Windows PATH rules (E84 review 2) ([f052979](https://github.com/abdelrahmannasr/yadflow/commit/f052979a3018790c1d7c94fe5b761ce32bf15e55))
+* **toolbox:** offer an undo only when the tool's use changed (E86 review 3) ([32e5105](https://github.com/abdelrahmannasr/yadflow/commit/32e5105bb83f856b9b37b8bc0e96e7bf15e396e1))
+* **toolbox:** one remove clears everything under an id; add agrees with the list (E86 review 2) ([da75777](https://github.com/abdelrahmannasr/yadflow/commit/da75777496e4c705e52423c77c553f35e5c99002))
+* **toolbox:** truthful edit messages, remove clears dead lines, --dir is the Product (E86 review 1) ([2159543](https://github.com/abdelrahmannasr/yadflow/commit/21595432d611e190c93d97fc707f27c432ba936f))
+
+
+### Features
+
+* **toolbox:** yad toolbox add, remove and check (E86) ([715cd4c](https://github.com/abdelrahmannasr/yadflow/commit/715cd4c6cc63ffdcfdc33c97a9d2df8078965b64))
+* **toolbox:** yad toolbox list and the shipped toolbox of external tools (E84) ([3f5374b](https://github.com/abdelrahmannasr/yadflow/commit/3f5374b830c83782b884f48a7e760943bc2349d4))
+
 # [4.1.0](https://github.com/abdelrahmannasr/yadflow/compare/v4.0.1...v4.1.0) (2026-10-01)
 
 

package/README.md

@@ -155,7 +155,8 @@ unless CI runs it), or `yad gate advance` with no platform, is the human decisio
 - `yad skip` and `yad defer` pass over optional steps, such as the UI design.
 
 **Already using Yadflow?** Follow [staying up to date](docs/CLI.md#staying-up-to-date). Coming from
-3.x, read [upgrading to 4.0](docs/migrations/upgrading-to-4.md) first.
+3.x, read [upgrading to 4.0](docs/migrations/upgrading-to-4.md) first, then follow the
+[step-by-step upgrade guide](docs/migrations/upgrade-guide-3x-to-4x.md).
 
 ## How the project record evolves
 
@@ -256,6 +257,7 @@ The record is worth trusting because people approve what goes into it.
 - linked changes and `yad thread`
 - `yad history`, `yad next` and `yad usage`
 - `yad detect`, which lists the skills, agents, MCP servers and plugins installed for each AI agent
+- `yad toolbox list`, which shows the external tools yadflow can use, which ones you have, and what happens without each; `yad toolbox add` / `remove` record the tools your team uses, and `yad toolbox check` lists the ones not ready on your machine
 - draft saving, claims and owners
 - the CI checks
 - the Review Companion
@@ -280,7 +282,8 @@ The record is worth trusting because people approve what goes into it.
   - [all 38 skills](docs/SKILLS.md)
   - [the by-hand walkthrough](docs/WALKTHROUGH.md)
 - **Upgrade:** [staying up to date](docs/CLI.md#staying-up-to-date) ·
-  [upgrading to 4.0](docs/migrations/upgrading-to-4.md)
+  [upgrading to 4.0](docs/migrations/upgrading-to-4.md) ·
+  [step-by-step upgrade guide](docs/migrations/upgrade-guide-3x-to-4x.md)
 - **Project:**
   - [CONTRIBUTING.md](CONTRIBUTING.md)
   - [SECURITY.md](SECURITY.md)

package/bin/commands.mjs

@@ -36,6 +36,7 @@ export { runRiskMap } from '../cli/riskmap-command.mjs';
 export { runCodeowners } from '../cli/codeowners-command.mjs';
 export { runDocs } from '../cli/docs.mjs';
 export { runDetect } from '../cli/detect.mjs';
+export { runToolboxAdd, runToolboxCheck, runToolboxList, runToolboxRemove } from '../cli/toolbox.mjs';
 export { runDoctor } from '../cli/doctor.mjs';
 export { runMigrate, warnIfProjectAhead } from '../cli/migrate.mjs';
 export { runNext } from '../cli/next.mjs';

package/bin/yad.mjs

@@ -116,6 +116,18 @@ ${c.bold('Where am I / what next')}
                                        Bind a step to a skill of your own. Several skills run in
                                        the order given, one after another — each costs tokens
   yad skill unbind <step>              Drop the binding; the step goes back to the engine's default
+  yad toolbox list [--json] [--dir <folder>]
+                                       The external tools yadflow can use — core (offered at setup),
+                                       recommended pools, the design/testing/learning connectors and
+                                       this project's own — whether each is found here, whether this
+                                       project uses it, and what yadflow does without it. Installs nothing
+  yad toolbox check [--json]           The tools this project uses that are not ready here, each with
+                                       its install command and fallback. Never fails: none is required
+  yad toolbox add <id>                 Use a tool in this Product (.sdlc/toolbox.json); prints how to
+                                       install it, installs nothing. Your own tool: add <id> --custom
+                                       --role "<text>" --fallback "<text>" --detect <kind>:<name>[,…]
+                                       [--install "<type>: <command>"] [--source <https URL>]
+  yad toolbox remove <id>              Stop using a tool in this Product, or drop one of your own
   yad detect [--json] [--dir <folder>] Which skills, agents, MCP servers and plugins are installed
                                        for the agents that work here — in this folder and in your
                                        home folder, and which agents read each place. Read-only;
@@ -326,7 +338,7 @@ ${c.bold('Environment')}
   YAD_NO_REPORT=1            Never offer to file a bug report after a failure
   YAD_PLATFORM_LOGIN=0       Name a record's author by git user.name; never ask gh/glab who is logged in`;
 
-const VALUE_FLAGS = new Set(['--dir', '--type', '--message', '--task', '--ai', '--risk', '--repo', '--platform', '--base', '--title', '--scope', '--branch', '--pr', '--epic', '--team', '--body', '--out', '--since', '--until', '--member', '--format', '--reason', '--profile', '--parent', '--inherits', '--to', '--retro-ship', '--merge-commit', '--path', '--ide-targets', '--theme', '--thread', '--by', '--count', '--engagement', '--keep']);
+const VALUE_FLAGS = new Set(['--dir', '--type', '--message', '--task', '--ai', '--risk', '--repo', '--platform', '--base', '--title', '--scope', '--branch', '--pr', '--epic', '--team', '--body', '--out', '--since', '--until', '--member', '--format', '--reason', '--profile', '--parent', '--inherits', '--to', '--retro-ship', '--merge-commit', '--path', '--ide-targets', '--theme', '--thread', '--by', '--count', '--engagement', '--keep', '--role', '--fallback', '--detect', '--install', '--source']);
 
 function parseArgs(argv) {
   const o = { _: [], dir: process.cwd(), fix: false, force: false, scope: 'all' };
@@ -373,6 +385,7 @@ function parseArgs(argv) {
     // The roadmap and the release check spell the default `--preview`. Accepting it means a script can
     // say what it means rather than relying on the absence of a flag.
     else if (a === '--preview') o.apply = false;
+    else if (a === '--custom') o.custom = true;
     else if (a === '--json') o.json = true;
     else if (a === '-h' || a === '--help') o.help = true;
     else if (a === '-v' || a === '--version') o.version = true;
@@ -422,6 +435,7 @@ const ACTIONS = {
   docs: { known: ['list', 'build', 'deploy', 'sync'], default: 'list' },
   reconcile: { known: ['check', 'refresh', 'wire'] },
   hook: { known: ['ledger-guard'] },
+  toolbox: { known: ['list', 'check', 'add', 'remove'], default: 'list' },
 };
 // E80 — how each command finds its folder. A PRODUCT command works on the Product; a REPO command works
 // on the code repo it runs in and reads the Product beside it. The rest take their folder as given:
@@ -557,12 +571,12 @@ async function main() {
   // A project written by a newer yadflow is warned about before any command reads it (docs/migrations/
   // shape-8.md). Not on `hook` — its stderr is the channel a block reason reaches a model on — and not
   // where the command reports the same thing itself (doctor, migrate) or runs before a project exists.
-  if (!['hook', 'doctor', 'migrate', 'setup', 'report', 'detect', 'new', 'init', 'join'].includes(cmd)) commands.warnIfProjectAhead(o.dir || process.cwd());
+  if (!['hook', 'doctor', 'migrate', 'setup', 'report', 'detect', 'toolbox', 'new', 'init', 'join'].includes(cmd)) commands.warnIfProjectAhead(o.dir || process.cwd());
   // E122: the Product's settings (or an epic's PR ledger) under two names that say different things.
   // Every command refuses rather than pick one — whichever it picked, somebody's edit would be silently
   // ignored. Not `doctor` (it reports the drift), `migrate` (it ends it) or `report` (it files a bug
   // about a broken flow, and reads nothing it could get wrong). `hook` returned above: it guards.
-  if (!['doctor', 'migrate', 'report', 'detect'].includes(cmd)) {
+  if (!['doctor', 'migrate', 'report', 'detect', 'toolbox'].includes(cmd)) {
     // Both the folder the command runs on and, for a code-repo command, the Product it reads.
     for (const root of new Set([o.dir || process.cwd(), o.product].filter(Boolean))) {
       const drift = commands.productDriftError(root);
@@ -623,6 +637,49 @@ async function main() {
     case 'migrate':
       result = await commands.runMigrate(o.dir, { apply: o.apply, json: o.json, keep: o.keep ?? null });
       break;
+    case 'toolbox': {
+      // E84 + E86. Finding a tool reads the folder yad runs in (a code repo's own skills count); the
+      // team's choices are the Product's `.sdlc/toolbox.json`, found the way every Product command finds
+      // it. So `toolbox` is not in PRODUCT_CMDS: that would move the finding to the Product's folder.
+      const [, action = 'list', id, extra] = o._;
+      const usage = 'usage: yad toolbox list | check | add <id> [--custom …] | remove <id>   [--json] [--dir <folder>]';
+      if (!['list', 'check', 'add', 'remove'].includes(action)) { refuse(`unknown toolbox action: ${action} (list, check, add, remove)`, usage); break; }
+      const found = commands.findProduct(dirGiven ? o.dir : shellCwd());
+      const rel = (p) => path.relative(process.cwd(), p) || '.';
+      if (action === 'list' || action === 'check') {
+        if (id) { refuse(`yad toolbox ${action} takes no more words (got: ${id})`, usage); break; }
+        // A reader may be pointed at a code repo with --dir: it finds tools there and reads the Product
+        // that repo belongs to. Why no Product was found is said, as every Product command says it —
+        // otherwise the team's choices would be missing from the answer without a word.
+        if (found?.problem) warn(`${found.problem} — showing the defaults`);
+        else if (found?.elsewhere) warn(`this folder is not in a repo the Product registers — the Product is ${rel(found.elsewhere)}: cd there, or pass --dir ${rel(found.elsewhere)}`);
+        const productRoot = found?.root ?? null;
+        const run = action === 'list' ? commands.runToolboxList : commands.runToolboxCheck;
+        result = run(o.dir || process.cwd(), { json: o.json, productRoot });
+        break;
+      }
+      if (extra) { refuse(`yad toolbox ${action} takes one tool id (got also: ${extra})`, usage); break; }
+      // A writer: the Product's file, never a code repo's, and the same refusals every writer has. With
+      // --dir it is the Product itself, as for every other Product command (`yad skill bind --dir`) —
+      // never a folder a walk up from it happens to reach.
+      const productRoot = dirGiven ? (found?.via === 'here' ? found.root : null) : (found?.root ?? null);
+      if (!productRoot) {
+        const near = found?.root ?? found?.elsewhere;
+        const where = dirGiven ? `with --dir, name the Product folder itself (the one holding .sdlc/product.json)${near ? `: --dir ${rel(near)}` : ''}`
+          : found?.elsewhere ? `the Product is ${rel(found.elsewhere)}: cd there, or pass --dir ${rel(found.elsewhere)}`
+            : `${found?.problem ? `${found.problem}. ` : ''}run it from the Product, from inside a repo it registers, or pass --dir <the Product>; \`yad new\` / \`yad init\` start one`;
+        refuse(`no Product here (${o.dir}) — yad toolbox ${action} writes the Product's .sdlc/toolbox.json`, where);
+        break;
+      }
+      if (found.via !== 'here') process.stderr.write(c.dim(`Product: ${rel(productRoot)}\n`));
+      commands.warnIfProjectAhead(productRoot);
+      const drift = commands.productDriftError(productRoot);
+      if (drift) throw drift;
+      result = action === 'add'
+        ? commands.runToolboxAdd(productRoot, { id, custom: o.custom, role: o.role, fallback: o.fallback, detect: o.detect, install: o.install, source: o.source, json: o.json })
+        : commands.runToolboxRemove(productRoot, { id, custom: o.custom, role: o.role, fallback: o.fallback, detect: o.detect, install: o.install, source: o.source, json: o.json });
+      break;
+    }
     case 'detect': {
       // E50. Reads the folder and the home folder; writes nothing.
       const [, extra] = o._;
@@ -1001,8 +1058,9 @@ main()
       // block reason travels on — an update banner there would land in front of a model.
       // Resolved the way main() resolves it, NOT from argv[2]: that is the first raw argument, so
       // `yad --dir <path> hook ledger-guard` puts `--dir` there and the banner slips through.
-      // Nor `detect` (E50): it promises no network and no file written, and the check does both.
-      if (!['hook', 'detect'].includes(parseArgs(process.argv.slice(2))._[0])) {
+      // Nor `detect` (E50) or `toolbox` (E84): they promise no network and no file written, and the
+      // check does both.
+      if (!['hook', 'detect', 'toolbox'].includes(parseArgs(process.argv.slice(2))._[0])) {
         const { maybeNotifyUpdate } = await import('./commands.mjs');
         await maybeNotifyUpdate();
       }

package/cli/detect.mjs

@@ -163,7 +163,7 @@ const isPlainObject = (v) => !!v && typeof v === 'object' && !Array.isArray(v);
 // `--json` escapes only U+0000–001F and hands the rest to a program unchanged.
 // eslint-disable-next-line no-control-regex -- matching control characters is the point
 const UNSAFE = /[\u0000-\u001f\u007f-\u009f\u061c\u200b-\u200f\u2028\u2029\u202a-\u202e\u2060-\u2064\u2066-\u2069\ufeff]/g;
-const clean = (v) => String(v).replace(UNSAFE, '?');
+export const clean = (v) => String(v).replace(UNSAFE, '?');
 
 // ---- the three file formats -------------------------------------------------------------------------
 

package/cli/doctor.mjs

@@ -25,6 +25,7 @@ import { soloTeamHint, TEAM_CMD } from './people.mjs';
 import { indexFreshness, INDEX_FILE } from './product-index.mjs';
 import { productGit, resolveDefaultBranch } from './productcommit.mjs';
 import { readOwners } from './owners.mjs';
+import { loadChoices, readToolboxFile } from './toolbox.mjs';
 
 // A registered path doctor may run git in (E81): a checkout the judgement accepts — never a refused
 // entry (git run in a folder the Product shaped as a repo reads its `config`, which can run a command),
@@ -446,6 +447,7 @@ export function projectChecks(checks, root, { headCount = null } = {}) {
   // inside the `project` block. The renderer prints a header every time the section CHANGES, so a
   // `project` check added after the `shape` section prints the word "project" a second time.
   skillBindingChecks(checks, root);
+  toolboxFileChecks(checks, root);
 
   // repos.json: parse + every entry is a live git repo; staleness vs syncedHead
   let registry = { repos: [] };
@@ -2107,6 +2109,28 @@ export function skillBindingChecks(checks, root) {
   }
 }
 
+// `.sdlc/toolbox.json`: which toolbox tools this Product uses or skips, and its own tools (E86). Absent is
+// the normal case. THE FILE ONLY: whether a tool is installed is `yad toolbox check`'s answer, and a
+// missing tool is never a doctor line (decided with E86 — no tool is required). A broken file fails, as
+// skills.json does; a line that does nothing warns, because `yad toolbox list` quietly shows the default.
+export function toolboxFileChecks(checks, root) {
+  const rel = PROJECT_FILES.toolboxConfig;
+  if (!exists(path.join(root, rel))) return;
+  const { error } = readToolboxFile(root);
+  if (error) {
+    check(checks, 'toolbox', 'project', 'fail', `${rel} ${error}`, 'fix the JSON or restore it from git — `yad toolbox list` shows the defaults until then');
+    return;
+  }
+  const { problems, unreachable, shipped, custom } = loadChoices(root);
+  if (problems.length) {
+    // An entry with no id (or an empty one) is out of `remove`'s reach; only hand-editing fixes it.
+    check(checks, 'toolbox', 'project', 'warn', `${rel}: ${problems.length} line(s) do nothing — ${problems.map((p) => p.replace(`${rel}: `, '')).join('; ')} [YAD-CFG-007]`,
+      `fix them by hand, or \`yad toolbox remove <id>\` — it clears whatever the file holds under that id — and add the tool again${unreachable ? ' (an entry with no id, or an empty one: fix it by hand)' : ''}`);
+    return;
+  }
+  check(checks, 'toolbox', 'project', 'ok', `toolbox: ${shipped.size} shipped tool choice(s), ${custom.length} tool(s) of this project's own`);
+}
+
 // A step this release does not recognise. Every step the engine can run has a row in the step
 // catalogue (E4), and that row is what gives it both a phase and a skill. So an id no phase claims is
 // an id with no row at all: one `yad next` cannot guide, `yad gate` has no artifact rule for, and no

package/cli/errors.mjs

@@ -30,6 +30,7 @@ export const CODES = {
   'YAD-CFG-004': 'learning.json names an unknown learning tool (expected one of config.yaml learning.tools, or none)',
   'YAD-CFG-005': 'the Product settings (product.json, or hub.json on a Product that has only that name) set a platform but are missing git_url (required to scope auth + open PRs)',
   'YAD-CFG-006': 'skills.json binds a step to something that is not a skill name (expected a string, or a non-empty list of strings)',
+  'YAD-CFG-007': 'toolbox.json has a line that does nothing — a tool this yadflow does not ship, a choice other than use or skip, or a custom tool that is incomplete, malformed, listed twice or uses a shipped tool\'s id',
   'YAD-CLI-001': 'a --json run needed an answer that only a prompt could give',
 };
 

package/cli/manifest.mjs

@@ -275,6 +275,9 @@ export const PROJECT_FILES = {
   // the normal case and means "every step uses the skill the catalogue names" — like design.json,
   // which is absent on a markdown-only project.
   skillsConfig: '.sdlc/skills.json',
+  // Which toolbox tools this project uses or skips, and its own tools (E86). Absent is the normal case:
+  // the core tools and the connected design, testing and learning tools are the ones in use.
+  toolboxConfig: '.sdlc/toolbox.json',
   // The kill switch and the Shape steps a team has set to `advance: auto` (E34). Absent is the normal
   // case: the switch is off and every Shape step is `human`. A project file, not the module config the
   // switch lived in before (`_bmad/sdlc/config.yaml` then, `.sdlc/config.yaml` since E3) — that one is

package/cli/toolbox.mjs

@@ -0,0 +1,814 @@
+// The toolbox — every external tool yadflow can use, what each one is for, how it installs, and what
+// yadflow does without it (E84).
+//
+//   yad toolbox list [--json] [--dir <folder>]
+//   yad toolbox check [--json] [--dir <folder>]
+//   yad toolbox add <id> | add <id> --custom --role … --fallback … --detect … [--install …] [--source …]
+//   yad toolbox remove <id>
+//
+// THE RULE IT EXISTS FOR: no external tool is ever mandatory, and every one declares a fallback. yadflow
+// degrades; it never breaks. This file is the one place that says, per tool, what "degrades" means.
+//
+// NOT `manifest.mjs`. That is the INSTALL manifest — the files yadflow copies into a project. This list
+// is about tools yadflow does NOT ship and never installs on its own.
+//
+// SHIPPED, NOT A PROJECT FILE (decided with E84). The list moves with each release, like the step
+// catalogue. What a team CHOOSES from it is a project file, `.sdlc/toolbox.json` in the Product (E86):
+// which shipped tools it uses or skips, and its own tools. See "the team's choices" below.
+//
+// THREE TIERS:
+//   core         offered at setup (E85) — repomix, spec-kit, impeccable
+//   recommended  listed, never pushed — pools of skills and agents a team may choose (Part 7)
+//   connector    the tools a Product connects for design, testing and learning (`yad-connect-*`); the
+//                same adapters `skills/sdlc/config.yaml` names, with the same fallbacks
+//
+// FINDING A TOOL RUNS NOTHING. It reads `yad detect`'s answer (E50) — skills, plugins, MCP servers — and
+// looks for a program on PATH by reading folders, never by starting `which`. A tool that `npx` fetches
+// on demand (repomix) is "available" whenever `npx` is there.
+//
+// AN OLD OR NEW VERSION WARNS, IT DOES NOT DISQUALIFY (decided with the row). A tool outside its known
+// range still counts as installed: a slightly older tool usually works, and quietly switching to the
+// weaker fallback would be worse. A range is only set where a version is actually visible (a plugin's or
+// a skill's own record) and a known-good bound exists; `versions: null` means "no bound known".
+//
+// EVERY INSTALL COMMAND WAS CHECKED AGAINST THE TOOL'S OWN REPOSITORY OR DOCS, on the `checked` date —
+// never guessed from a package name (npm `ecc` is an unrelated crypto library, not ECC). A connector set
+// up inside a desktop app has no command: its `install` is empty and `manual` links the vendor's steps.
+import fs from 'node:fs';
+import path from 'node:path';
+import { c, emitJSON, exists, hand, info, log, ok, readJSON, readJSONStrict, refuse, warn, writeJSON } from './lib.mjs';
+import { clean, detectInstalled } from './detect.mjs';
+import { PROJECT_FILES, SCHEMA_VERSION } from './manifest.mjs';
+
+export const INSTALL_TYPES = Object.freeze(['plugin', 'npm', 'python', 'script']);
+export const TIERS = Object.freeze(['core', 'recommended', 'connector']);
+const TIER_TITLES = { core: 'Core — offered at setup', recommended: 'Recommended — listed, never pushed', connector: 'Connectors — design, testing and learning tools a Product connects' };
+
+const CHECKED = '2026-10-01';
+
+// The list itself, checked against each tool's own repository and docs on CHECKED. `install` keeps only
+// the routes the roadmap's four types describe (plugin, npm, python, script); a tool's other routes
+// (Docker, Homebrew, a VS Code extension) are in its own README, which `source` links. `versions` is null
+// everywhere for now: no bound has been tested yet — E88 vets each default and is where a known-good
+// range is earned. `records` is the exact line a skill writes when the tool is absent, so E87 can point
+// the skill at this entry without renaming anything.
+export const TOOLBOX = Object.freeze([
+  // ---- core: offered at setup --------------------------------------------------------------------
+  {
+    id: 'repomix', name: 'Repomix', tier: 'core', role: 'packs each code repo into one file the Shape steps read',
+    licence: 'MIT', source: 'https://github.com/yamadashy/repomix', checked: CHECKED,
+    install: [
+      { type: 'npm', command: 'npx repomix@latest' },
+      { type: 'npm', command: 'npm install -g repomix' },
+      { type: 'plugin', command: '/plugin marketplace add yamadashy/repomix, then /plugin install repomix-mcp@repomix' },
+    ],
+    manual: null,
+    // yad runs it through `npx repomix@latest` (setup, `yad repo refresh`), so `npx` alone makes it usable.
+    detect: { npx: true, bins: ['repomix'], plugins: ['repomix-mcp', 'repomix-commands', 'repomix-explorer'], mcp: ['repomix'], skills: ['repomix-explorer'] },
+    versions: null,
+    fallback: 'no code pack: repos are not packed, and the Shape steps read the code map alone',
+    records: null, note: null,
+    usedBy: ['yad setup', 'yad repo refresh', 'yad-connect-repos'],
+  },
+  {
+    id: 'spec-kit', name: 'Spec Kit', tier: 'core', role: 'runs the spec ceremony (specify → plan → tasks) in a code repo',
+    licence: 'MIT', source: 'https://github.com/github/spec-kit', checked: CHECKED,
+    install: [
+      { type: 'python', command: 'uv tool install specify-cli, then specify init <project> --integration claude' },
+      { type: 'python', command: 'pipx install specify-cli' },
+    ],
+    manual: null,
+    // Claude Code gets `speckit-<command>` skills since Spec Kit 0.4.5; older installs have flat
+    // `speckit.<command>.md` commands, which `yad detect` does not read — the `specify` program still shows.
+    detect: { skillPrefixes: ['speckit-', 'speckit.'], bins: ['specify'] },
+    versions: null,
+    fallback: "yad-spec writes the same spec files by hand, in Spec Kit's layout",
+    records: 'speckit: not-installed', note: 'A program named specify on PATH also counts; another tool by that name would too.',
+    usedBy: ['yad-spec'],
+  },
+  {
+    id: 'impeccable', name: 'Impeccable', tier: 'core', role: 'drives the UI design step (document, extract, craft)',
+    licence: 'Apache-2.0', source: 'https://github.com/pbakaus/impeccable', checked: CHECKED,
+    install: [
+      { type: 'npm', command: 'npx impeccable install' },
+      { type: 'plugin', command: '/plugin marketplace add pbakaus/impeccable, then /plugin install impeccable@impeccable' },
+    ],
+    manual: null,
+    detect: { skills: ['impeccable'], plugins: ['impeccable'] },
+    versions: null,
+    fallback: 'Markdown-only UI design: yad-ui writes ui-design.md and DESIGN.md directly',
+    records: 'impeccable: not-installed', note: null,
+    usedBy: ['yad-ui'],
+  },
+
+  // ---- recommended: listed, never pushed ---------------------------------------------------------
+  {
+    id: 'bmad-method', name: 'BMAD-METHOD', tier: 'recommended', role: 'a pool of planning and building skills',
+    // The LICENSE file is MIT text with attribution added (GitHub reads it as NOASSERTION); "BMad" is a trademark.
+    licence: 'MIT', source: 'https://github.com/bmad-code-org/BMAD-METHOD', checked: CHECKED,
+    install: [
+      { type: 'npm', command: 'npx bmad-method install' },
+      { type: 'plugin', command: '/plugin marketplace add bmad-code-org/bmad-plugins, then install bmad-method from /plugin' },
+    ],
+    manual: null,
+    // The README names a `bmad-core-tools` plugin; the marketplace lists `bmad-toolbox`. Both are kept.
+    detect: { skills: ['bmad'], skillPrefixes: ['bmad-', 'bmod-'], plugins: ['bmad-method', 'bmad-toolbox', 'bmad-core-tools'] },
+    versions: null,
+    fallback: "nothing changes: yadflow's own skills run every step",
+    records: null, note: 'Left the engine in E3; returns only as an optional pool you bind with `yad skill bind`.',
+    usedBy: ['yad skill bind'],
+  },
+  {
+    id: 'ecc', name: 'ECC (Everything Claude Code)', tier: 'recommended', role: 'a large pool of skills, agents and hooks',
+    licence: 'MIT', source: 'https://github.com/affaan-m/ECC', checked: CHECKED,
+    install: [
+      { type: 'npm', command: 'npx ecc-universal install --guided' },
+      { type: 'plugin', command: '/plugin marketplace add https://github.com/affaan-m/ECC, then /plugin install ecc@ecc' },
+      { type: 'script', command: 'git clone https://github.com/affaan-m/ECC.git && cd ECC && ./install.sh --profile minimal --target claude' },
+    ],
+    manual: null,
+    // Its skills have no common prefix, so they cannot identify it; the plugin and the program can.
+    detect: { plugins: ['ecc'], bins: ['ecc'] },
+    versions: null,
+    fallback: "nothing changes: yadflow's own skills run every step",
+    records: null, note: 'The npm package is ecc-universal. npm `ecc` is an unrelated crypto library.',
+    usedBy: ['yad skill bind'],
+  },
+  {
+    id: 'mattpocock-skills', name: 'mattpocock/skills', tier: 'recommended', role: 'a small pool of engineering skills',
+    licence: 'MIT', source: 'https://github.com/mattpocock/skills', checked: CHECKED,
+    install: [{ type: 'plugin', command: 'claude plugins install mattpocock-skills' }],
+    manual: null,
+    // Generic names (`tdd`, `code-review`) collide with other packs; this one is its own.
+    detect: { plugins: ['mattpocock-skills'], skills: ['setup-matt-pocock-skills'] },
+    versions: null,
+    fallback: "nothing changes: yadflow's own skills run every step",
+    records: null, note: 'About 8 contributors: fine as an option, risky as a default.',
+    usedBy: ['yad skill bind'],
+  },
+
+  // ---- connectors: what a Product connects (skills/sdlc/config.yaml names the same adapters) -------
+  {
+    id: 'figma', name: 'Figma', tier: 'connector', role: 'design tool: yad-ui generates and links screens in it',
+    licence: 'proprietary', source: 'https://developers.figma.com/docs/figma-mcp-server/', checked: CHECKED,
+    install: [{ type: 'plugin', command: 'claude plugin install figma@claude-plugins-official' }],
+    manual: 'https://developers.figma.com/docs/figma-mcp-server/',
+    detect: { plugins: ['figma'], mcp: ['figma', 'figma-desktop', 'html-to-design'] },
+    versions: null,
+    fallback: 'markdown-only: yad-ui writes ui-design.md and DESIGN.md only',
+    records: null, note: 'Sign-in is your own (OAuth); yadflow stores no token. The desktop server is named figma-desktop.',
+    usedBy: ['yad-connect-design', 'yad-ui'],
+  },
+  {
+    id: 'pencil', name: 'Pencil (pen.dev)', tier: 'connector', role: 'design tool: yad-ui writes .pen web and mobile screens',
+    licence: 'proprietary', source: 'https://docs.pencil.dev/getting-started/installation', checked: CHECKED,
+    install: [],
+    manual: 'https://docs.pencil.dev/getting-started/installation',
+    detect: { mcp: ['pencil'] },
+    versions: null,
+    fallback: 'markdown-only: yad-ui writes ui-design.md and DESIGN.md only',
+    records: null, note: 'Set up inside the desktop app: open a .pen file, then Settings → MCP → enable your agent.',
+    usedBy: ['yad-connect-design', 'yad-ui'],
+  },
+  {
+    id: 'playwright', name: 'Playwright MCP', tier: 'connector', role: 'testing tool: generates and runs browser and API tests',
+    licence: 'Apache-2.0', source: 'https://github.com/microsoft/playwright-mcp', checked: CHECKED,
+    install: [{ type: 'npm', command: 'claude mcp add playwright npx @playwright/mcp@latest' }],
+    manual: null,
+    detect: { mcp: ['playwright'], plugins: ['playwright'] },
+    versions: null,
+    fallback: 'artifacts-only: yad-test-cases writes test-cases.md only',
+    records: null,
+    note: 'Found by its server name only (yad never reads a server\'s settings), and an unofficial package is often registered under the same name.',
+    usedBy: ['yad-connect-testing', 'yad-test-cases'],
+  },
+  {
+    id: 'cypress', name: 'Cypress', tier: 'connector', role: 'testing tool: Cypress specs',
+    licence: 'proprietary', source: 'https://docs.cypress.io/cloud/integrations/cloud-mcp', checked: CHECKED,
+    install: [],
+    manual: 'https://docs.cypress.io/cloud/integrations/cloud-mcp',
+    detect: { mcp: ['cypress', 'cypress-cloud'] },
+    versions: null,
+    fallback: 'artifacts-only: yad-test-cases writes test-cases.md only',
+    records: null,
+    note: 'No official MCP server runs local tests. The official Cypress Cloud MCP only reads Cloud results; community servers exist but none is vetted.',
+    usedBy: ['yad-connect-testing', 'yad-test-cases'],
+  },
+  {
+    id: 'pytest', name: 'pytest', tier: 'connector', role: 'testing tool: service-layer tests',
+    licence: 'MIT', source: 'https://github.com/pytest-dev/pytest', checked: CHECKED,
+    install: [],
+    manual: 'https://docs.pytest.org/',
+    detect: { mcp: ['pytest'] },
+    versions: null,
+    fallback: 'artifacts-only: yad-test-cases writes test-cases.md only',
+    records: null,
+    note: 'pytest has no official MCP server; the small community ones are not vetted. Connect one you trust under the name pytest.',
+    usedBy: ['yad-connect-testing', 'yad-test-cases'],
+  },
+  {
+    id: 'maestro', name: 'Maestro', tier: 'connector', role: 'testing tool: mobile UI flows',
+    licence: 'Apache-2.0', source: 'https://github.com/mobile-dev-inc/Maestro', checked: CHECKED,
+    install: [{ type: 'script', command: 'curl -fsSL "https://get.maestro.mobile.dev" | bash, then claude mcp add maestro -- maestro mcp' }],
+    manual: 'https://docs.maestro.dev/get-started/maestro-mcp',
+    detect: { bins: ['maestro'], mcp: ['maestro'] },
+    versions: null,
+    fallback: 'artifacts-only: yad-test-cases writes test-cases.md only',
+    records: null, note: 'Needs Java 17 or later. The MCP server is built into the maestro program.',
+    usedBy: ['yad-connect-testing', 'yad-test-cases'],
+  },
+  {
+    id: 'deeptutor', name: 'DeepTutor', tier: 'connector', role: 'learning tool: tutors a team member on what is being built',
+    licence: 'Apache-2.0', source: 'https://github.com/HKUDS/DeepTutor', checked: CHECKED,
+    install: [{ type: 'python', command: 'pip install -U deeptutor, then deeptutor init' }],
+    manual: null,
+    detect: { bins: ['deeptutor'] },
+    versions: null,
+    fallback: 'harness-native tutoring: yad-learn has your agent read the project files directly',
+    records: null, note: 'A program, not an MCP server. Needs Python 3.11 or later.',
+    usedBy: ['yad-connect-learning', 'yad-learn'],
+  },
+]);
+
+// ---- checking an entry ------------------------------------------------------------------------------
+
+const DATE = /^\d{4}-\d{2}-\d{2}$/;
+const isStringList = (v) => Array.isArray(v) && v.every((x) => typeof x === 'string' && x.length > 0);
+
+// Every way an entry can be malformed, as sentences. [] means it is well formed. Run by the tests over the
+// shipped list, so a bad entry fails CI rather than a user's `yad toolbox list`.
+export function toolProblems(t) {
+  const out = [];
+  const need = (ok, what) => { if (!ok) out.push(what); };
+  need(typeof t?.id === 'string' && /^[a-z0-9][a-z0-9-]*$/.test(t.id), 'id is lower-case words joined by -');
+  need(typeof t?.name === 'string' && t.name.length > 0, 'name is set');
+  need(TIERS.includes(t?.tier), `tier is one of ${TIERS.join(', ')}`);
+  need(typeof t?.role === 'string' && t.role.length > 0, 'role is set');
+  need(typeof t?.licence === 'string' && t.licence.length > 0, 'licence is set (an SPDX id, or "proprietary")');
+  need(typeof t?.source === 'string' && /^https:\/\//.test(t.source), 'source is an https URL');
+  need(typeof t?.checked === 'string' && DATE.test(t.checked), 'checked is a YYYY-MM-DD date');
+  need(Array.isArray(t?.install), 'install is a list');
+  for (const r of Array.isArray(t?.install) ? t.install : []) {
+    need(INSTALL_TYPES.includes(r?.type), `an install route's type is one of ${INSTALL_TYPES.join(', ')}`);
+    need(typeof r?.command === 'string' && r.command.length > 0, 'an install route has its command');
+  }
+  need((Array.isArray(t?.install) && t.install.length > 0) || (typeof t?.manual === 'string' && /^https:\/\//.test(t.manual)),
+    'a tool with no install command links its manual steps (manual: https URL)');
+  const d = t?.detect;
+  need(d && typeof d === 'object', 'detect is set');
+  if (d && typeof d === 'object') {
+    for (const k of ['skills', 'skillPrefixes', 'plugins', 'mcp', 'bins']) need(d[k] === undefined || isStringList(d[k]), `detect.${k} is a list of names`);
+    need(d.npx === undefined || typeof d.npx === 'boolean', 'detect.npx is true or false');
+    need(['skills', 'skillPrefixes', 'plugins', 'mcp', 'bins'].some((k) => d[k]?.length) || d.npx === true, 'detect names at least one thing to look for');
+  }
+  need(t?.versions === null || (typeof t?.versions === 'string' && parseRange(t.versions) !== null), 'versions is null or a range this reader understands');
+  need(typeof t?.fallback === 'string' && t.fallback.length > 0, 'fallback says what yadflow does without it');
+  need(t?.records === null || (typeof t?.records === 'string' && t.records.length > 0), 'records is null or the line a skill writes');
+  need(t?.note === null || (typeof t?.note === 'string' && t.note.length > 0), 'note is null or a sentence');
+  need(t?.manual === null || (typeof t?.manual === 'string' && /^https:\/\//.test(t.manual)), 'manual is null or an https URL');
+  need(isStringList(t?.usedBy), 'usedBy lists the skills or commands that use it');
+  return out;
+}
+
+// ---- versions ---------------------------------------------------------------------------------------
+
+// `1.2.3`, `v1.2`, `3` → [1,2,3] / [1,2,0] / [3,0,0]; a pre-release (`1.2.3-beta`) is below its release.
+// Anything else (a git sha, a date) is not a version this can compare: null.
+export function parseVersion(v) {
+  const m = String(v ?? '').trim().match(/^v?(\d+)(?:\.(\d+))?(?:\.(\d+))?(-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/);
+  if (!m) return null;
+  // `full`: all three numbers were written. A range needs that (see parseRange); a found version does not.
+  return { parts: [Number(m[1]), Number(m[2] ?? 0), Number(m[3] ?? 0)], pre: m[4] ? m[4].slice(1) : null, full: m[2] !== undefined && m[3] !== undefined };
+}
+
+// The semantic-versioning order: numbers first; then a pre-release is below its release, and two
+// pre-releases compare label by label — a number below a word, numbers as numbers, a shorter list first.
+function compare(a, b) {
+  for (let i = 0; i < 3; i++) if (a.parts[i] !== b.parts[i]) return a.parts[i] < b.parts[i] ? -1 : 1;
+  if (!a.pre || !b.pre) return a.pre === b.pre ? 0 : a.pre ? -1 : 1;
+  const x = a.pre.split('.');
+  const y = b.pre.split('.');
+  for (let i = 0; i < Math.max(x.length, y.length); i++) {
+    if (x[i] === undefined) return -1;
+    if (y[i] === undefined) return 1;
+    const nx = /^\d+$/.test(x[i]);
+    const ny = /^\d+$/.test(y[i]);
+    if (nx && ny && Number(x[i]) !== Number(y[i])) return Number(x[i]) < Number(y[i]) ? -1 : 1;
+    if (nx !== ny) return nx ? -1 : 1;
+    if (!nx && x[i] !== y[i]) return x[i] < y[i] ? -1 : 1;
+  }
+  return 0;
+}
+
+// A range is space-separated comparators, all of which must hold: `>=3.0.0 <4.0.0`, `^3.2.0`, `~1.4.0`,
+// `=2.0.0`. A small reader on purpose — the list sets a handful of simple bounds, and a dependency for
+// that is not worth its weight. Returns the comparator list, or null when it cannot read the range.
+//
+// EVERY VERSION IN A RANGE HAS ALL THREE NUMBERS. A partial one (`~1`, `^0`, `>1.2`) means something
+// different for each operator, and reading it as `.0` got four of them wrong; refusing it makes
+// `toolProblems` reject such a range instead of letting it give a silent wrong answer.
+//
+// ONE RULE FOR PRE-RELEASES: an upper bound `<X.Y.Z` also keeps out X.Y.Z's own pre-releases
+// (`4.0.0-beta` is outside `<4.0.0`), whether it was written or comes from `^` / `~`.
+export function parseRange(range) {
+  const out = [];
+  // `<X.Y.Z-0` — below every pre-release of X.Y.Z, because `0` is the lowest label there is.
+  const below = (parts) => ['<', { parts, pre: '0', full: true }];
+  for (const tok of String(range).trim().split(/\s+/)) {
+    const m = tok.match(/^(>=|<=|>|<|=|\^|~)?(.+)$/);
+    const v = m && parseVersion(m[2]);
+    if (!v || !v.full) return null;
+    const [x, y, z] = v.parts;
+    const op = m[1] || '=';
+    if (op === '^') out.push(['>=', v], below(x > 0 ? [x + 1, 0, 0] : y > 0 ? [0, y + 1, 0] : [0, 0, z + 1]));
+    else if (op === '~') out.push(['>=', v], below([x, y + 1, 0]));
+    else if (op === '<' && !v.pre) out.push(below(v.parts));
+    else out.push([op, v]);
+  }
+  return out.length ? out : null;
+}
+
+// true or false when both sides can be read; null when either cannot (a sha, a missing version).
+export function versionInRange(version, range) {
+  const v = parseVersion(version);
+  const r = range === null ? null : parseRange(range);
+  if (!v || !r) return null;
+  return r.every(([op, b]) => {
+    const k = compare(v, b);
+    return op === '>=' ? k >= 0 : op === '>' ? k > 0 : op === '<=' ? k <= 0 : op === '<' ? k < 0 : k === 0;
+  });
+}
+
+// ---- finding a tool ---------------------------------------------------------------------------------
+
+// Is a program on PATH — by reading the PATH folders, never by starting one. On Windows a program is
+// `name` plus one of PATHEXT's endings (`.EXE`, `.CMD`, …); elsewhere it must be an executable file.
+export function onPath(bin, { env = process.env, platform = process.platform } = {}) {
+  // Only absolute folders: an empty or relative entry means "the current folder", which is not where a
+  // tool is installed, and would make the answer depend on where `yad` happened to run.
+  // On Windows that means a drive and a root (C:\x) or a share (\\server\share): \x is on whatever drive
+  // is current, and D:x in that drive's current folder. Windows accepts an entry in quotes; so does this —
+  // but not a `;` inside the quotes, which the plain split cuts in two (rare; that folder is then missed).
+  const isAbs = platform === 'win32' ? (d) => /^[A-Za-z]:[\\/]/.test(d) || /^[\\/]{2}[^\\/]/.test(d) : path.posix.isAbsolute;
+  const unquote = (d) => (platform === 'win32' ? d.replace(/^"(.*)"$/, '$1') : d);
+  const dirs = String(env.PATH || env.Path || '').split(platform === 'win32' ? ';' : ':').map(unquote).filter((d) => d && isAbs(d));
+  const exts = platform === 'win32' ? ['', ...String(env.PATHEXT || '.COM;.EXE;.BAT;.CMD').split(';').filter(Boolean)] : [''];
+  for (const dir of dirs) {
+    for (const ext of exts) {
+      const full = path.join(dir, bin + ext);
+      try {
+        if (!fs.statSync(full).isFile()) continue;
+        if (platform !== 'win32') fs.accessSync(full, fs.constants.X_OK);
+        return true;
+      } catch { /* not here */ }
+    }
+  }
+  return false;
+}
+
+const lower = (s) => String(s).toLowerCase();
+// A plugin id is `name@marketplace`; the toolbox names the plugin by `name` alone, or by the full id.
+const pluginMatches = (id, names) => names.some((n) => lower(n) === lower(id) || lower(n) === lower(String(id).split('@')[0]));
+
+// What the toolbox knows about one tool here: `installed` (something it installs was found), `available`
+// (fetched on demand — `npx` is there), `disabled` (found only through a plugin that is turned off), or
+// `missing`. `found` lists where, as `yad detect` shows places;
+// `version` is the first one a found item records; `inRange` is true, false, or null (nothing to compare).
+export function toolStatus(tool, items, { has = onPath } = {}) {
+  const d = tool.detect;
+  // A Claude Code plugin your settings turn off is not loaded, and neither is anything it brings (its
+  // skills, agents and MCP servers carry its id in `plugin`). `enabled: null` means no setting says, which
+  // is on. So a tool found ONLY through a plugin that is off is `disabled`, not installed.
+  // Claude Code's plugins only: a Codex plugin of the same name has its own switch, which is not read.
+  const claude = (it) => Array.isArray(it.agents) && it.agents.includes('Claude Code');
+  const off = new Set(items.filter((it) => it.kind === 'plugin' && it.enabled === false && claude(it)).map((it) => it.name));
+  const isOff = (it) => claude(it) && off.has(it.kind === 'plugin' ? it.name : it.plugin);
+  const matches = items.filter((it) => {
+    if (it.kind === 'skill') return (d.skills ?? []).some((n) => lower(n) === lower(it.name)) || (d.skillPrefixes ?? []).some((p) => lower(it.name).startsWith(lower(p)));
+    if (it.kind === 'plugin') return pluginMatches(it.name, d.plugins ?? []);
+    if (it.kind === 'mcp') return (d.mcp ?? []).some((n) => lower(n) === lower(it.name));
+    return false;
+  });
+  const hits = matches.filter((it) => !isOff(it));
+  const bins = (d.bins ?? []).filter((b) => has(b));
+  const found = [...new Set([...hits.map((h) => h.where), ...bins.map((b) => `${b} on PATH`)])];
+  const version = hits.map((h) => h.version).find((v) => typeof v === 'string' && v) ?? null;
+  const inRange = tool.versions === null ? null : versionInRange(version, tool.versions);
+  if (found.length) return { state: 'installed', found, version, inRange };
+  // `npx` before `disabled`: yadflow runs such a tool through npx, so a plugin that is off does not stop it.
+  if (d.npx && has('npx')) return { state: 'available', found: ['npx on PATH'], version: null, inRange: null };
+  if (matches.length) return { state: 'disabled', found: [...new Set(matches.map((h) => h.where))], version: null, inRange: null };
+  return { state: 'missing', found: [], version: null, inRange: null };
+}
+
+// ---- the team's choices (E86) -----------------------------------------------------------------------
+//
+// `.sdlc/toolbox.json` in the Product, committed, so the whole team shares one answer:
+//
+//   { "schemaVersion": 10,
+//     "shipped": { "<id>": "use" | "skip" },     only where this project differs from the default
+//     "custom":  [ { "id", "role", "fallback", "detect", "install"?, "source"?, "name"? } ] }
+//
+// IN USE BY DEFAULT: the core tools (setup offers them), and a connector the Product has connected — the
+// `tool` its design.json, testing.json or learning.json names. Everything else is listed, not in use.
+// `add` and `remove` write only a difference from that default, so the file never repeats one, and a
+// later release that changes a default is not overruled by a line nobody chose.
+//
+// RECORDS ONLY (decided with the row). Nothing here installs a tool or starts a program: `add` prints the
+// install command, and the person runs it. `yad toolbox check` then says whether it is found.
+
+export const TOOL_ID = /^[a-z0-9][a-z0-9-]*$/;
+const CHOICES = ['use', 'skip'];
+// `--detect skill:x,prefix:y-,plugin:p,mcp:m,bin:b` — the same five things a shipped entry looks for.
+const DETECT_KINDS = Object.freeze({ skill: 'skills', prefix: 'skillPrefixes', plugin: 'plugins', mcp: 'mcp', bin: 'bins' });
+const CONNECTOR_FILES = ['designConfig', 'testingConfig', 'learningConfig'];
+const FILE = PROJECT_FILES.toolboxConfig;
+const ADD_USAGE = 'usage: yad toolbox add <id>   or   yad toolbox add <id> --custom --role "<what it does>" --fallback "<what happens without it>" --detect <kind>:<name>[,…] [--install "<type>: <command>"] [--source <https URL>]';
+
+const isObject = (v) => v !== null && typeof v === 'object' && !Array.isArray(v);
+const shippedTool = (id) => TOOLBOX.find((t) => t.id === id) ?? null;
+
+// The file as it is on disk, for a read-modify-write: `{ doc }` or `{ error }`. STRICT, like
+// `yad skill bind`: a file that does not parse is refused, never rebuilt from nothing — that would delete
+// every choice in it, silently.
+export function readToolboxFile(root) {
+  const file = path.join(root, FILE);
+  if (!exists(file)) return { doc: {} };
+  let raw;
+  try { raw = readJSONStrict(file, null); } catch { return { error: 'does not parse [YAD-STATE-001]' }; }
+  if (!isObject(raw)) return { error: 'has the wrong shape [YAD-STATE-002]' };
+  if (raw.shipped !== undefined && !isObject(raw.shipped)) return { error: '`shipped` must be a JSON object [YAD-STATE-002]' };
+  if (raw.custom !== undefined && !Array.isArray(raw.custom)) return { error: '`custom` must be a JSON list [YAD-STATE-002]' };
+  return { doc: raw };
+}
+
+// Every way a team's own entry can be malformed, as sentences; [] means it is usable. Lighter than
+// `toolProblems`: a licence, a checked date and `usedBy` are the shipped list's promises, not a team's.
+export function customProblems(t) {
+  if (!isObject(t)) return ['an entry is a JSON object'];
+  const out = [];
+  const need = (ok, what) => { if (!ok) out.push(what); };
+  need(typeof t.id === 'string' && TOOL_ID.test(t.id), 'id is lower-case words joined by -');
+  need(!(typeof t.id === 'string' && shippedTool(t.id)), 'id is not the id of a shipped tool');
+  need(t.name === undefined || (typeof t.name === 'string' && t.name.length > 0), 'name, when set, is text');
+  need(typeof t.role === 'string' && t.role.trim().length > 0, 'role says what it does');
+  need(typeof t.fallback === 'string' && t.fallback.trim().length > 0, 'fallback says what happens without it');
+  const d = t.detect;
+  const kinds = Object.values(DETECT_KINDS);
+  need(isObject(d) && Object.keys(d).every((k) => kinds.includes(k) && isStringList(d[k])) && kinds.some((k) => d[k]?.length),
+    `detect names at least one thing to look for (${kinds.join(', ')}), each a list of names`);
+  // A program is a plain name looked up on PATH. A path (`../x`) would make every teammate's `check`
+  // look at a file the shared file chose, so it is refused.
+  need(!isObject(d) || !Array.isArray(d.bins) || d.bins.every((b) => typeof b !== 'string' || (!/[\\/]/.test(b) && b !== '.' && b !== '..')),
+    'detect.bins names programs, not paths (no / or \\)');
+  need(t.install === undefined || (Array.isArray(t.install) && t.install.every((r) => INSTALL_TYPES.includes(r?.type) && typeof r?.command === 'string' && r.command.length > 0)),
+    `install, when set, is a list of { type: ${INSTALL_TYPES.join(' | ')}, command }`);
+  need(t.source === undefined || t.source === null || (typeof t.source === 'string' && /^https:\/\//.test(t.source)), 'source, when set, is an https URL');
+  return out;
+}
+
+// A team's entry in the shipped entries' shape, so one printer and one finder serve both.
+const customRow = (t) => ({
+  id: t.id, name: t.name || t.id, tier: 'project', role: t.role,
+  licence: null, source: t.source ?? null, checked: null,
+  install: t.install ?? [], manual: null,
+  detect: Object.fromEntries(Object.values(DETECT_KINDS).filter((k) => t.detect[k]?.length).map((k) => [k, t.detect[k]])),
+  versions: null, fallback: t.fallback, records: null, note: null, usedBy: [],
+});
+
+// The connector each of design.json, testing.json and learning.json names, when it is one the toolbox
+// knows: id → the file. `none` and an adapter the toolbox does not list name nothing here.
+export function connectedTools(root) {
+  const out = new Map();
+  for (const key of CONNECTOR_FILES) {
+    const doc = readJSON(path.join(root, PROJECT_FILES[key]), null);
+    const id = isObject(doc) && typeof doc.tool === 'string' ? doc.tool : null;
+    if (id && shippedTool(id)?.tier === 'connector' && !out.has(id)) out.set(id, PROJECT_FILES[key]);
+  }
+  return out;
+}
+
+// What the Product says, read leniently: a broken file or line is a `problem` and the defaults stand,
+// because a list must still answer. With no Product, there is nothing to read: the defaults.
+export function loadChoices(productRoot) {
+  const problems = [];
+  let doc = {};
+  if (productRoot) {
+    const r = readToolboxFile(productRoot);
+    if (r.error) problems.push(`${FILE} ${r.error} — showing the defaults`);
+    else doc = r.doc;
+  }
+  const shipped = new Map();
+  // A line no `yad toolbox remove <id>` can reach — no id, or an empty one — is fixed by hand only.
+  let unreachable = false;
+  for (const [id, v] of Object.entries(doc.shipped ?? {})) {
+    if (!id) unreachable = true;
+    // A tool from a newer release, or a typo: the line stays in the file and does nothing here.
+    if (!shippedTool(id)) problems.push(`${FILE}: \`${clean(id)}\` is not a tool this yadflow ships — ignored`);
+    else if (!CHOICES.includes(v)) problems.push(`${FILE}: \`${id}\` should be "use" or "skip" — ignored`);
+    else shipped.set(id, v);
+  }
+  const custom = [];
+  for (const [i, t] of (doc.custom ?? []).entries()) {
+    const hasId = isObject(t) && typeof t.id === 'string' && t.id.length > 0;
+    const label = hasId ? `\`${clean(t.id)}\`` : `number ${i + 1}`;
+    const p = customProblems(t);
+    if (p.length && !hasId) unreachable = true;
+    if (p.length) problems.push(`${FILE}: custom tool ${label} is ignored — ${p.join('; ')}`);
+    else if (custom.some((c2) => c2.id === t.id)) problems.push(`${FILE}: custom tool ${label} is listed twice — the first one is used`);
+    else custom.push(customRow(t));
+  }
+  return { problems, unreachable, shipped, custom, connected: productRoot ? connectedTools(productRoot) : new Map() };
+}
+
+// Is a tool in use here, and why. `because`: core | connected | added | removed | custom | null.
+const defaultUsed = (tool, connected) => tool.tier === 'core' || connected.has(tool.id);
+export function toolUse(tool, { shipped, connected }) {
+  if (tool.tier === 'project') return { used: true, because: 'custom' };
+  const choice = shipped.get(tool.id);
+  if (choice === 'use') return { used: true, because: 'added' };
+  if (choice === 'skip') return { used: false, because: 'removed' };
+  if (tool.tier === 'core') return { used: true, because: 'core' };
+  if (connected.has(tool.id)) return { used: true, because: 'connected', connectedIn: connected.get(tool.id) };
+  return { used: false, because: null };
+}
+
+// Every row — shipped, then the team's own — with what is found here and whether it is in use. Finding
+// reads `detectRoot` (the folder yad runs in: a code repo's own skills count); the choices come from the
+// Product, which may be another folder.
+export function toolboxRows(detectRoot, productRoot, { tools = TOOLBOX, items = null, has = onPath } = {}) {
+  const found = items ?? detectInstalled(detectRoot).items;
+  const choices = loadChoices(productRoot);
+  const rows = [...tools, ...choices.custom].map((t) => ({ ...t, status: toolStatus(t, found, { has }), ...toolUse(t, choices) }));
+  return { rows, problems: choices.problems };
+}
+
+// ---- the command ------------------------------------------------------------------------------------
+
+const TITLES = { ...TIER_TITLES, project: 'Added by this project' };
+const BECAUSE = { core: 'used here', connected: 'used here — connected', added: 'used here — added', custom: 'used here', removed: 'not used here — removed' };
+
+// The lines `yad toolbox list` prints, from rows that already carry their status. Separate so a test can
+// read them. Everything from a file is cleaned like every name `yad detect` prints: a found version, and
+// every word of a team's own entry (the Product's file is shared, so anyone can write in it).
+export function toolboxLines(rows) {
+  const lines = [c.bold('The toolbox — external tools yadflow can use. None is required; each has a fallback.')];
+  for (const tier of [...TIERS, 'project']) {
+    const mine = rows.filter((r) => r.tier === tier);
+    if (!mine.length) continue;
+    lines.push('', c.bold(TITLES[tier]));
+    for (const r of mine) {
+      const s = r.status;
+      const version = s.version ? clean(s.version) : null;
+      const mark = s.state === 'missing' || s.state === 'disabled' ? c.dim('–') : c.green('✓');
+      const state = s.state === 'installed' ? `installed${version ? ` ${version}` : ''}`
+        : s.state === 'available' ? 'available (npx fetches it when needed)'
+          : s.state === 'disabled' ? 'installed, but its plugin is turned off in your Claude Code settings' : 'not found';
+      const tag = r.because ? c.cyan(` [${BECAUSE[r.because]}]`) : '';
+      lines.push(`  ${mark} ${c.bold(clean(r.name))} ${c.dim(`— ${clean(r.role)}`)}: ${state}${tag}`);
+      if (s.inRange === false) lines.push(`      ${c.yellow('!')} version ${version} is outside the known-good range ${r.versions} — still used; if it misbehaves, install a version in range`);
+      if (s.state === 'missing' || s.state === 'disabled') lines.push(`      ${c.dim(`without it: ${clean(r.fallback)}`)}`);
+      if (r.note) lines.push(`      ${c.dim(r.note)}`);
+    }
+  }
+  return lines;
+}
+
+export function runToolboxList(root, { json = false, productRoot = null, tools = TOOLBOX, items = null, has = onPath } = {}) {
+  const { rows, problems } = toolboxRows(root, productRoot, { tools, items, has });
+  if (json) return emitJSON({ ok: true, ...(productRoot ? where(productRoot) : { product: null, file: null }), tools: rows, problems });
+  for (const line of toolboxLines(rows)) log(line);
+  for (const p of problems) warn(p);
+  info(productRoot
+    ? '[used here] = in use in this Product; change it with `yad toolbox add <id>` / `yad toolbox remove <id>`'
+    : 'no Product here, so this shows the defaults: the core tools are the ones in use');
+  info('`yad toolbox list --json` adds each tool\'s licence, source, install commands and where it was found');
+  return undefined;
+}
+
+// How to get a tool, as lines: each install command, else the vendor's steps, else its source.
+const howToGet = (r) => (r.install.length ? r.install.map((i) => `${i.type}: ${clean(i.command)}`)
+  : r.manual ? [`set it up by hand: ${r.manual}`] : r.source ? [`see ${clean(r.source)}`] : []);
+
+// The tools this project uses that are not ready here: `missing`, `disabled` (its plugin is off), or
+// `out-of-range` (found, but outside its known-good versions — still used). The function E85 calls.
+export function toolboxCheck(root, productRoot, opts = {}) {
+  const { rows, problems } = toolboxRows(root, productRoot, opts);
+  const used = rows.filter((r) => r.used);
+  const findings = used.flatMap((r) => {
+    const s = r.status;
+    const problem = s.state === 'missing' ? 'missing' : s.state === 'disabled' ? 'disabled' : s.inRange === false ? 'out-of-range' : null;
+    if (!problem) return [];
+    return [{ id: r.id, name: r.name, tier: r.tier, problem, version: s.version, versions: r.versions, install: r.install, manual: r.manual, source: r.source, fallback: r.fallback }];
+  });
+  return { used, findings, problems };
+}
+
+// NEVER FAILS (decided with the row): no tool is required, so a missing one is news, not an error. Exit 0.
+export function runToolboxCheck(root, { json = false, productRoot = null, ...opts } = {}) {
+  const { used, findings, problems } = toolboxCheck(root, productRoot, opts);
+  if (json) return emitJSON({ ok: true, ...(productRoot ? where(productRoot) : { product: null, file: null }), used: used.map((r) => r.id), findings, problems });
+  for (const p of problems) warn(p);
+  if (!findings.length) {
+    ok(`all ${used.length} tool(s) this project uses are here: ${used.map((r) => clean(r.name)).join(', ')}`);
+    return undefined;
+  }
+  log(c.bold(`${findings.length} of the ${used.length} tool(s) this project uses ${findings.length === 1 ? 'is' : 'are'} not ready here. None is required.`));
+  for (const f of findings) {
+    const r = used.find((u) => u.id === f.id);
+    const what = f.problem === 'missing' ? 'not found'
+      : f.problem === 'disabled' ? 'installed, but its plugin is turned off in your Claude Code settings'
+        : `version ${clean(f.version)} is outside the known-good range ${f.versions} — still used`;
+    log(`  ${f.problem === 'out-of-range' ? c.yellow('!') : c.dim('–')} ${c.bold(clean(f.name))}: ${what}`);
+    if (f.problem === 'disabled') log(`      ${c.dim('turn it on with /plugin in Claude Code')}`);
+    else for (const line of howToGet(r)) log(`      ${c.dim(line)}`);
+    if (f.problem !== 'out-of-range') log(`      ${c.dim(`without it: ${clean(f.fallback)}`)}`);
+  }
+  info(productRoot ? 'stop using a tool here with `yad toolbox remove <id>`' : 'no Product here, so this checks the core tools only');
+  return undefined;
+}
+
+// `--detect skill:x,plugin:p` → { skills: ['x'], plugins: ['p'] }, or { error }.
+export function parseDetect(text) {
+  const out = {};
+  for (const part of String(text ?? '').split(',').map((p) => p.trim()).filter(Boolean)) {
+    const m = part.match(/^([a-z]+):(.+)$/);
+    const key = m && Object.hasOwn(DETECT_KINDS, m[1]) ? DETECT_KINDS[m[1]] : null;
+    if (!key) return { error: `\`${clean(part)}\` is not <kind>:<name> — the kinds are ${Object.keys(DETECT_KINDS).join(', ')}` };
+    (out[key] ??= []).push(m[2].trim());
+  }
+  return Object.keys(out).length ? { detect: out } : { error: '--detect names nothing to look for' };
+}
+
+// `--install "npm: npx thing"` → { type, command }, or { error }.
+export function parseInstall(text) {
+  const m = String(text ?? '').match(/^\s*([a-z]+)\s*:\s*(.+?)\s*$/);
+  if (!m || !INSTALL_TYPES.includes(m[1])) return { error: `--install is "<type>: <command>", the type one of ${INSTALL_TYPES.join(', ')}` };
+  return { route: { type: m[1], command: m[2] } };
+}
+
+const CUSTOM_FLAGS = ['role', 'fallback', 'detect', 'install', 'source'];
+const brokenFile = (error, json) => refuse(`${FILE} ${error}`, 'fix the file (or restore it from git) first — writing over it would delete every choice it holds', { json });
+
+// The document plus one edit, ready to write. `schemaVersion` is set outright, as `yad skill bind` does:
+// this command is the file's engine writer, so its write IS the file's migration. Keys this release does
+// not know are kept; an empty `shipped` or `custom` is left out.
+function save(productRoot, doc, shipped, custom) {
+  const next = { ...doc, schemaVersion: SCHEMA_VERSION, shipped, custom };
+  if (!Object.keys(shipped).length) delete next.shipped;
+  if (!custom.length) delete next.custom;
+  writeJSON(path.join(productRoot, FILE), next);
+}
+
+// The one edit both verbs make to a shipped tool: write `want` only where it differs from the default.
+function setShipped(doc, tool, want, connected) {
+  const shipped = { ...(isObject(doc.shipped) ? doc.shipped : {}) };
+  if (defaultUsed(tool, connected) === (want === 'use')) delete shipped[tool.id];
+  else shipped[tool.id] = want;
+  return shipped;
+}
+const sameJSON = (a, b) => JSON.stringify(a ?? {}) === JSON.stringify(b ?? {});
+
+// Where the file is, for an answer: the Product as a path from here, since run from a code repo nothing
+// else on stdout names it. Both sides as the disk has them: `process.cwd()` is already resolved, and a
+// Product reached through a link (macOS's /var is /private/var) would otherwise climb to the top and back.
+const onDisk = (p) => { try { return fs.realpathSync(p); } catch { return path.resolve(p); } };
+const where = (productRoot) => ({ product: path.relative(onDisk(process.cwd()), onDisk(productRoot)) || '.', file: FILE });
+
+// The edit to a shipped tool, said truthfully. Whether the FILE changed and whether the tool's USE changed
+// are two questions: removing a line that did nothing (`"figma": "bogus"`, or one that repeats the
+// default) changes the file and not the use.
+function sayEdit(tool, was, now, changed) {
+  const state = now.used ? 'used here' : 'not used here';
+  if (!changed) info(`${tool.name} is already ${state} — nothing to change`);
+  else if (was.used === now.used) info(`${tool.name} is already ${state} — removed a line in ${FILE} that did nothing`);
+  // The fallback is printed as `list` prints it, after "without it:" — on its own, ECC's ("nothing
+  // changes: …") read as if the remove had done nothing.
+  else ok(now.used ? `${tool.name} is used here now` : `${tool.name} is not used here now. Without it: ${clean(tool.fallback)}`);
+}
+// The whole report of an edit to a SHIPPED tool, for both verbs — one function, so `add` and `remove`
+// cannot say it differently again. Two facts, each said once: the shipped part (`sayEdit`), and the
+// dead custom copies under the tool's id that the same write removed.
+function sayShippedEdit(tool, was, now, shippedChanged, copies) {
+  if (shippedChanged || !copies) sayEdit(tool, was, now, shippedChanged);
+  if (copies) {
+    // When only copies went, the tool's use did not change: `customProblems` rejects every custom entry
+    // under a shipped tool's id, so no copy ever counted toward using it. If that rule ever changes,
+    // this branch must call `sayEdit` too.
+    const what = `${copies} custom entr${copies > 1 ? 'ies' : 'y'} under the id ${tool.id}, which ${copies > 1 ? 'were' : 'was'} ignored (the id is a shipped tool's)`;
+    info(shippedChanged ? `also removed ${what}` : `removed ${what} — ${tool.name} is still ${now.used ? 'used' : 'not used'} here`);
+  }
+}
+const usedFrom = (shipped, connected) => ({ shipped: new Map(Object.entries(shipped).filter(([, v]) => CHOICES.includes(v))), connected });
+const sameId = (id) => (t) => isObject(t) && t.id === id;
+
+export function runToolboxAdd(productRoot, { id, custom = false, json = false, ...flags } = {}) {
+  if (!id) return refuse('yad toolbox add needs a tool id', ADD_USAGE, { json });
+  if (!TOOL_ID.test(id)) return refuse(`\`${clean(id)}\` is not a tool id`, 'an id is lower-case letters, digits and dashes — `yad toolbox list --json` shows each one', { json });
+  const given = CUSTOM_FLAGS.filter((k) => flags[k] !== undefined);
+  if (!custom && given.length) return refuse(`--${given[0]} describes a tool of your own, and goes with --custom`, ADD_USAGE, { json });
+  const { doc, error } = readToolboxFile(productRoot);
+  if (error) return brokenFile(error, json);
+  const list = Array.isArray(doc.custom) ? doc.custom : [];
+  const tool = shippedTool(id);
+  const mine = list.find(sameId(id));
+  // In use exactly when `list` says so: `loadChoices` keeps the first USABLE copy, so a broken copy
+  // before a good one does not make the tool unused, and a broken copy alone does not make it used.
+  const usable = loadChoices(productRoot).custom.some((r) => r.id === id);
+  const ignored = () => refuse(`${id} is in ${FILE} but ignored: ${customProblems(mine).join('; ')}`, `fix it by hand, or \`yad toolbox remove ${id}\` and add it again with --custom`, { json });
+
+  if (custom) {
+    if (tool) return refuse(`${id} is a shipped tool`, `\`yad toolbox add ${id}\` marks it as used here`, { json });
+    if (usable) return refuse(`${id} is already one of this project's tools`, `to change it, \`yad toolbox remove ${id}\` and add it again`, { json });
+    if (mine) return ignored();
+    const d = parseDetect(flags.detect);
+    if (flags.detect === undefined || d.error) return refuse(d.error && flags.detect !== undefined ? d.error : 'a tool of your own needs --detect, so yadflow can tell whether it is here', ADD_USAGE, { json });
+    const entry = { id, role: flags.role, fallback: flags.fallback, detect: d.detect };
+    if (flags.install !== undefined) {
+      const r = parseInstall(flags.install);
+      if (r.error) return refuse(r.error, ADD_USAGE, { json });
+      entry.install = [r.route];
+    }
+    if (flags.source !== undefined) entry.source = flags.source;
+    const problems = customProblems(entry);
+    if (problems.length) return refuse(`cannot add ${id}: ${problems.join('; ')}`, ADD_USAGE, { json });
+    save(productRoot, doc, isObject(doc.shipped) ? doc.shipped : {}, [...list, entry]);
+    ok(`${id} added — a tool of this project's own, in use here`);
+    hand(`written to ${FILE} — commit it so the team shares it (undo with \`yad toolbox remove ${id}\`); \`yad toolbox check\` says whether it is found`);
+    return { id, used: true, because: 'custom', changed: true, ...where(productRoot) };
+  }
+
+  if (!tool) {
+    if (usable) {
+      info(`${id} is already one of this project's tools — nothing to change`);
+      return { id, used: true, because: 'custom', changed: false, ...where(productRoot) };
+    }
+    // An entry `list` and `check` ignore is not in use, whatever the file says.
+    if (mine) return ignored();
+    return refuse(`${id} is not in the toolbox`, '`yad toolbox list --json` shows each id; add a tool of your own with `yad toolbox add <id> --custom …`', { json });
+  }
+  const connected = connectedTools(productRoot);
+  const was = toolUse(tool, loadChoices(productRoot));
+  const shipped = setShipped(doc, tool, 'use', connected);
+  // A custom entry under a shipped id is ignored; it goes in the same write, as `remove` does it.
+  const left = list.filter((t) => !sameId(id)(t));
+  const copies = list.length - left.length;
+  const shippedChanged = !sameJSON(shipped, doc.shipped);
+  const changed = shippedChanged || copies > 0;
+  if (changed) save(productRoot, doc, shipped, left);
+  const now = toolUse(tool, usedFrom(shipped, connected));
+  sayShippedEdit(tool, was, now, shippedChanged, copies);
+  // Records only: the person installs it.
+  const how = howToGet(tool);
+  if (how.length) hand(`to install it: ${how.join('   or   ')}`);
+  // An undo is offered only when the tool's use changed: after clearing a line that did nothing, the
+  // "opposite" command would switch the tool off, not put anything back.
+  if (changed) hand(`written to ${FILE} — commit it so the team shares it${was.used !== now.used ? ` (undo with \`yad toolbox remove ${id}\`)` : ''}; \`yad toolbox check\` says whether it is found`);
+  return { id, ...now, changed, ...where(productRoot) };
+}
+
+// Removes EVERYTHING the file holds under `id`, in one write: the shipped tool's use, every custom entry
+// with that id (a dead one sharing a shipped tool's id included), and a shipped line for a tool this
+// release does not ship — so it also clears each line `yad doctor` names as doing nothing.
+export function runToolboxRemove(productRoot, { id, json = false, ...flags } = {}) {
+  if (!id) return refuse('yad toolbox remove needs a tool id', 'usage: yad toolbox remove <id>', { json });
+  const given = CUSTOM_FLAGS.filter((k) => flags[k] !== undefined);
+  if (flags.custom || given.length) return refuse(`yad toolbox remove takes only the tool id (got ${flags.custom ? '--custom' : `--${given[0]}`})`, 'usage: yad toolbox remove <id>', { json });
+  const { doc, error } = readToolboxFile(productRoot);
+  if (error) return brokenFile(error, json);
+  const list = Array.isArray(doc.custom) ? doc.custom : [];
+  const shipped0 = isObject(doc.shipped) ? doc.shipped : {};
+  const tool = shippedTool(id);
+  const left = list.filter((t) => !sameId(id)(t));
+  const copies = list.length - left.length;
+  const deadLine = !tool && Object.hasOwn(shipped0, id);
+  if (!tool && !copies && !deadLine) {
+    if (!TOOL_ID.test(id)) return refuse(`\`${clean(id)}\` is not a tool id`, 'an id is lower-case letters, digits and dashes — `yad toolbox list --json` shows each one', { json });
+    return refuse(`${id} is not in the toolbox`, '`yad toolbox list --json` shows each id', { json });
+  }
+  if (tool) {
+    const connected = connectedTools(productRoot);
+    const was = toolUse(tool, loadChoices(productRoot));
+    const shipped = setShipped(doc, tool, 'skip', connected);
+    const shippedChanged = !sameJSON(shipped, doc.shipped);
+    const changed = shippedChanged || copies > 0;
+    if (changed) save(productRoot, doc, shipped, left);
+    const now = toolUse(tool, usedFrom(shipped, connected));
+    sayShippedEdit(tool, was, now, shippedChanged, copies);
+    // Removing it from the toolbox does not disconnect it: the connect skill owns that file.
+    if (connected.has(id)) info(`${connected.get(id)} still connects it — \`${tool.usedBy[0]}\` changes the connection`);
+    if (changed) hand(`written to ${FILE} — commit it so the team shares it${was.used !== now.used ? ` (undo with \`yad toolbox add ${id}\`)` : ''}`);
+    return { id, ...now, changed, ...where(productRoot) };
+  }
+  const usableBefore = loadChoices(productRoot).custom.some((r) => r.id === id);
+  const shipped = { ...shipped0 };
+  if (deadLine) delete shipped[id];
+  save(productRoot, doc, shipped, left);
+  if (copies) {
+    const many = copies > 1 ? ` (listed ${copies} times; every copy is gone)` : '';
+    ok(usableBefore ? `${clean(id)} removed — it was one of this project's own tools${many}` : `removed the entry for ${clean(id)}, which was ignored${many}`);
+  }
+  if (deadLine) ok(`removed the line for \`${clean(id)}\` under shipped — a tool this yadflow does not ship`);
+  hand(`written to ${FILE} — commit it so the team shares it`);
+  return { id, used: false, because: null, changed: true, ...where(productRoot) };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "yadflow",
-  "version": "4.1.0",
+  "version": "4.2.0",
   "description": "Shared project memory and workflows for teams building with AI: a versioned record of plans, decisions, contracts and reviews across repos, human-approved review gates, and a zero-dependency `yad` CLI plus 38 skills for your AI assistant.",
   "type": "module",
   "author": "AbdelRahman Nasr",