yadflow 4.1.0 → 4.3.0

package/CHANGELOG.md

@@ -1,3 +1,37 @@
+# [4.3.0](https://github.com/abdelrahmannasr/yadflow/compare/v4.2.0...v4.3.0) (2026-10-01)
+
+
+### Bug Fixes
+
+* **toolbox:** E85 review 1 — hint order, the folder check looks in, team-wide remove advice ([c7f6592](https://github.com/abdelrahmannasr/yadflow/commit/c7f65922cdad49e9816c4cbe81190283392c1df6))
+* **toolbox:** E85 review 2 — look for tools at the top of the repo, read --dir's Product ([82fb5ed](https://github.com/abdelrahmannasr/yadflow/commit/82fb5ed6a1afcf364a9844d3faf2676bd4a84274))
+* **toolbox:** E85 review 3 — a worktree is its own checkout; look at the deepest top ([4926799](https://github.com/abdelrahmannasr/yadflow/commit/4926799f6db758c7abb59029bd8e71923550c227))
+* **toolbox:** E85 review 4 — find the checkout top under both spellings of a linked folder ([9728384](https://github.com/abdelrahmannasr/yadflow/commit/9728384c140178d55608d2ab2b67037a2f80140d))
+
+
+### Features
+
+* **toolbox:** offer the missing tools in setup, check, update and join (E85) ([53e06c6](https://github.com/abdelrahmannasr/yadflow/commit/53e06c6da8bf585ced68435b052d01ba4ca5e6fa))
+
+# [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 (`yad setup`, `check`, `update` and `join` print the same list, and never install anything)
 - 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

@@ -12,7 +12,7 @@
 
 export { runSetup } from '../cli/setup.mjs';
 export { runNew, runInit, runJoin } from '../cli/workspace.mjs';
-export { findProduct, hasProduct, workspaceProduct, registryEntryFor, WORKSPACE_FILE } from '../cli/find-product.mjs';
+export { findProduct, hasProduct, workspaceProduct, registryEntryFor, toolsFolder, WORKSPACE_FILE } from '../cli/find-product.mjs';
 export { reconcile } from '../cli/reconcile.mjs';
 export { gateOpen, gateSync, gateComments, gateStatus, gateCi, gateReview, gateTrailer, gateWalkthrough, gateRepair } from '../cli/gate.mjs';
 export { gateApprove, gateComment, gateAdvance } from '../cli/gate-local.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

@@ -24,7 +24,8 @@ ${c.bold('Start a workspace')} ${c.dim('(the folder holding product/ and the cod
                        Never commits, pushes, or changes a shared file
 
 ${c.bold('Setup & maintenance')}
-  yad setup            Guided first-run setup (profile interview, install, connect & wire repos)
+  yad setup            Guided first-run setup (profile interview, install, connect & wire repos,
+                       then the tools this project uses that are missing — offered, never installed)
                        profile flags: --solo | --team <n>, --greenfield | --brownfield,
                        --monorepo | --separate, --tools (configure design/testing/learning now)
   yad check            Report what is missing / drifted / modified / stale / legacy (read-only)
@@ -116,6 +117,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 +339,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 +386,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 +436,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:
@@ -525,8 +540,12 @@ async function main() {
   // registers (through `.yad-workspace.json`) — and says where, on stderr. A code-repo command keeps acting
   // on the repo it runs in, and is handed the Product to read (its registry: name, platform, branch).
   const dirGiven = process.argv.slice(2).some((a) => a === '--dir' || a.startsWith('--dir='));
+  // E85: where `check` and `update` look for tools, and whose choices they read — worked out from the
+  // folder the person ran yad in (or named), before a Product command moves `o.dir` to the Product.
+  let toolboxAt = null;
   if (PRODUCT_CMDS.has(cmd) || REPO_CMDS.has(cmd)) {
     const found = commands.findProduct(dirGiven ? o.dir : shellCwd());
+    toolboxAt = { from: commands.toolsFolder(found, dirGiven ? o.dir : shellCwd()), product: found?.root ?? null };
     const shown = (p) => path.relative(process.cwd(), p) || '.';
     if (found?.problem) warn(`${found.problem} — using ${o.dir}`);
     else if (found?.elsewhere) {
@@ -557,12 +576,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);
@@ -611,11 +630,11 @@ async function main() {
     }
     case 'check':
       if (noProduct()) break;
-      result = await commands.reconcile(o.dir, { fix: o.fix, scope: o.scope, force: o.force, push: o.push, allowBranch: o.allowBranch, overwriteLocal: o.overwriteLocal, today });
+      result = await commands.reconcile(o.dir, { fix: o.fix, scope: o.scope, force: o.force, push: o.push, allowBranch: o.allowBranch, overwriteLocal: o.overwriteLocal, today, toolbox: toolboxAt });
       break;
     case 'update':
       if (noProduct()) break;
-      result = await commands.reconcile(o.dir, { fix: true, scope: 'changed', force: o.force, push: o.push, allowBranch: o.allowBranch, overwriteLocal: o.overwriteLocal, today });
+      result = await commands.reconcile(o.dir, { fix: true, scope: 'changed', force: o.force, push: o.push, allowBranch: o.allowBranch, overwriteLocal: o.overwriteLocal, today, toolbox: toolboxAt });
       break;
     case 'doctor':
       result = await commands.runDoctor(o.dir, { json: o.json });
@@ -623,6 +642,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(commands.toolsFolder(found, 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 +1063,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/find-product.mjs

@@ -181,6 +181,30 @@ export function gitTopOf(dir) {
   }
 }
 
+// Where `yad toolbox` and the toolbox section of `check` / `update` look for tools (E85), given
+// `findProduct(from)`'s answer. Finding reads `<folder>/.claude/…` and never walks up, so a subfolder
+// must be lifted to the top of what the person is working in. That is the DEEPEST of these that holds
+// `from`: the git checkout it is in (a worktree inside `api/` is its own checkout, on its own branch — never
+// swapped for api's, as in E80 review 3), the registered repo holding it (`apps/web` in a monorepo is not
+// a checkout of its own), and the Product found from it. A checkout ABOVE the Product (a Product that is
+// not a git repo, inside one that is not ours) is never deeper than the Product, so it never wins. Reads
+// only whether `.git` exists; runs nothing.
+export function toolsFolder(found, from) {
+  const at = real(from);
+  if (!at) return from;
+  // Both spellings: the shell's (through a link) and the one on disk, so `check` (given the shell's
+  // folder) and `yad toolbox check` (given the process's) look in the same place (E85 review 4).
+  const candidates = [gitTopOf(from), gitTopOf(at)];
+  if (found?.root && found.repo && typeof found.repo.path === 'string') candidates.push(path.resolve(found.root, found.repo.path));
+  if (found?.root && (found.via === 'here' || found.via === 'above')) candidates.push(found.root);
+  let best = null;
+  for (const c of candidates) {
+    const cAt = c && real(c);
+    if (cAt && within(at, cAt) && (!best || cAt.length > best.length)) best = cAt;
+  }
+  return best ?? from;
+}
+
 // The registry entry for the code repo a code-repo command runs in (E80), with the folder to work in.
 // It is the CHECKOUT that must be the registered repo — not merely a folder inside it: a worktree or a
 // repo nested in `backend/` is another checkout, on another branch, and must never be swapped for

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/reconcile.mjs

@@ -19,6 +19,7 @@ import {
 import { gitHead, packRepo } from './setup.mjs';
 import { groupByRoot, commitUpdates, repoLabel } from './update-commit.mjs';
 import { hasSiblingRepo, workspaceFileState, writeWorkspaceFile, WORKSPACE_FILE } from './find-product.mjs';
+import { offerToolbox } from './toolbox.mjs';
 
 const MARK = { missing: c.red('missing'), new: c.cyan('new'), outdated: c.yellow('outdated'), modified: c.cyan('modified'), stale: c.yellow('stale'), legacy: c.yellow('legacy'), removed: c.yellow('removed'), ok: c.green('ok') };
 
@@ -30,7 +31,7 @@ const repoShown = (repo) => `product (the code repo at ${forTerminal(repo.path)}
 const shown = (a) => a.shownScope ?? a.scope;
 const itemsOf = (actions) => actions.map((a) => ({ scope: a.scope, item: a.item, status: a.status, product: !a.fromRepo }));
 
-export async function reconcile(root, { fix = false, scope = 'all', force = false, push = false, allowBranch = false, overwriteLocal = false } = {}) {
+export async function reconcile(root, { fix = false, scope = 'all', force = false, push = false, allowBranch = false, overwriteLocal = false, toolbox: toolboxAt = null } = {}) {
   log(c.bold(`\nSDLC reconcile  ${c.dim('v' + VERSION)}`));
   log(c.dim(`target: ${root}\n`));
 
@@ -239,7 +240,9 @@ export async function reconcile(root, { fix = false, scope = 'all', force = fals
     if (workspaceFile === 'missing') info(`no ${WORKSPACE_FILE} beside the Product — \`yad check --fix\` writes it, so yad finds the Product from its code repos`);
     if (push) warn('--push has no effect without --fix (there is nothing applied to commit).');
     if (fixable.length || gaps.length) hand('run `yad check --fix` to reconcile (or `yad setup` for missing one-time setup).');
-    return { fix: false, counts, gaps, items: itemsOf(actions), applied: 0, modified: modified.length, commits: [], workspaceFile };
+    // After the --fix hint, never above it: --fix installs no tool, and must not read as if it did.
+    const toolbox = toolboxSection(root, toolboxAt);
+    return { fix: false, counts, gaps, items: itemsOf(actions), applied: 0, modified: modified.length, commits: [], workspaceFile, toolbox };
   }
 
   // --- apply --- (collect the applied actions so --push can stage each repo's exact allowlist) ---
@@ -314,5 +317,18 @@ export async function reconcile(root, { fix = false, scope = 'all', force = fals
       },
     });
   }
-  return { fix: true, counts, gaps, items: itemsOf(actions), applied, modified: modified.length, commits, workspaceFile };
+  const toolbox = toolboxSection(root, toolboxAt);
+  return { fix: true, counts, gaps, items: itemsOf(actions), applied, modified: modified.length, commits, workspaceFile, toolbox };
+}
+
+// E85: `yad check` and `yad update` end with the toolbox check — the tools this Product uses that are not
+// here. Report only: it never adds to what `--fix` applies, never changes the exit code, and installs
+// nothing. Both verbs, because both run here and a release can add a core tool. `at` comes from the
+// command line: `from`, the top of the repo the person ran yad in, where tools are looked for (as
+// `yad toolbox check` does — a code repo's own skills count); `product`, the Product whose choices are
+// read, which is not `root` under `--dir <a code repo>`.
+function toolboxSection(root, at) {
+  log('');
+  log(c.bold('Toolbox'));
+  return offerToolbox(at?.from || root, at?.product || root);
 }

package/cli/setup.mjs

@@ -16,6 +16,7 @@ import {
 import { modeFields, modeOf } from './mode.mjs';
 import { recordActor } from './skip.mjs';
 import { loadSkillBindings, stepSkills } from './epic-state.mjs';
+import { offerToolbox } from './toolbox.mjs';
 
 // Parse a comma/space separated list into a clean, deduped array of trimmed tokens.
 export function parseList(s) {
@@ -322,8 +323,9 @@ export async function runSetup(root, opts = {}) {
 
   // 0. Profile interview — branch the wizard to the user's situation (solo/team, code, repo layout).
   const { solo, team_size, codebase, repo_layout, configureTools } = await resolveProfile(root, opts);
-  // Steps: interview, preflight, install, Product, tools (1 if deferred else 3), repos, wire, coderabbit, done.
-  const total = 8 + (configureTools ? 3 : 1);
+  // Steps: interview, preflight, install, Product, tools (1 if deferred else 3), repos, wire, coderabbit,
+  // toolbox, done.
+  const total = 9 + (configureTools ? 3 : 1);
   let _n = 0;
   const S = (title) => step(++_n, total, title);
 
@@ -672,6 +674,13 @@ export async function runSetup(root, opts = {}) {
     }
   }
 
+  // E85: the external tools this project uses that are not here, and how to get each. AFTER the tools
+  // step, so a connector chosen there counts as in use. It offers and never installs: nothing is run and
+  // no file is written, and a missing tool never fails setup (each has a fallback).
+  S('Toolbox (external tools this project uses)');
+  guide(['Each tool is optional and has a fallback. yad installs nothing: it prints how to get each one, and you choose.']);
+  const toolbox = offerToolbox(root, root);
+
   // Summary + version stamp
   S('Done');
   writeJSON(path.join(root, PROJECT_FILES.version), { version: VERSION, ideTargets, updatedAt: opts.today ?? null });
@@ -713,7 +722,7 @@ export async function runSetup(root, opts = {}) {
   // step has written, so a scripted setup passes every flag (or SDLC_NONINTERACTIVE for the defaults).
   return {
     profile: { solo, team_size, codebase, repo_layout }, ideTargets,
-    repos: registry.repos.map((r) => r.name ?? null), next: epicSkill,
+    repos: registry.repos.map((r) => r.name ?? null), next: epicSkill, toolbox,
   };
 }