yadflow 4.9.0 → 4.10.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (93) hide show
  1. package/CHANGELOG.md +87 -0
  2. package/README.md +4 -3
  3. package/bin/commands.mjs +6 -0
  4. package/bin/yad.mjs +101 -6
  5. package/cli/agent-guard.mjs +793 -65
  6. package/cli/agent-rules.mjs +33 -5
  7. package/cli/argv-flags.mjs +1 -1
  8. package/cli/ci-check.mjs +45 -1
  9. package/cli/codeowners-command.mjs +72 -6
  10. package/cli/commit.mjs +17 -3
  11. package/cli/docs.mjs +2 -0
  12. package/cli/doctor.mjs +71 -12
  13. package/cli/epic-state.mjs +94 -4
  14. package/cli/epic.mjs +11 -7
  15. package/cli/fold.mjs +31 -6
  16. package/cli/guide.mjs +3 -1
  17. package/cli/hook.mjs +50 -7
  18. package/cli/issue-links.mjs +61 -0
  19. package/cli/issues-act.mjs +327 -0
  20. package/cli/issues-write.mjs +428 -0
  21. package/cli/issues.mjs +474 -0
  22. package/cli/lifecycle.mjs +7 -0
  23. package/cli/manifest.mjs +9 -3
  24. package/cli/openpr.mjs +24 -4
  25. package/cli/plan.mjs +2 -0
  26. package/cli/platform.mjs +157 -2
  27. package/cli/protection.mjs +21 -3
  28. package/cli/reconcile.mjs +1 -1
  29. package/cli/run-checks.mjs +10 -2
  30. package/cli/scan.mjs +314 -0
  31. package/cli/setup.mjs +12 -3
  32. package/cli/standup.mjs +33 -7
  33. package/cli/story-frames.mjs +17 -6
  34. package/cli/test-agents-file.mjs +378 -11
  35. package/cli/test-build.mjs +25 -0
  36. package/cli/test-ci-check.mjs +469 -10
  37. package/cli/test-guide.mjs +7 -0
  38. package/cli/test-node.mjs +15 -0
  39. package/cli/test-run-checks.mjs +17 -0
  40. package/cli/test-setup-agent.mjs +14 -0
  41. package/cli/test-story-frames.mjs +74 -4
  42. package/cli/toolbox-connect.mjs +244 -0
  43. package/cli/toolbox.mjs +129 -9
  44. package/package.json +7 -3
  45. package/skills/sdlc/config.yaml +1 -1
  46. package/skills/sdlc/module-help.csv +3 -1
  47. package/skills/yad-analysis/SKILL.md +4 -0
  48. package/skills/yad-backfill/SKILL.md +4 -0
  49. package/skills/yad-change/SKILL.md +4 -0
  50. package/skills/yad-checks/SKILL.md +13 -7
  51. package/skills/yad-checks/references/check-gates.md +62 -30
  52. package/skills/yad-checks/templates/checks/member-check.mjs +3 -2
  53. package/skills/yad-checks/templates/checks/risk-map-check.sh +2 -2
  54. package/skills/yad-checks/templates/checks/verified-commits.sh +3 -3
  55. package/skills/yad-checks/templates/github/yad-checks.yml +357 -69
  56. package/skills/yad-checks/templates/github/yad-pr-text.yml +118 -0
  57. package/skills/yad-checks/templates/github/yad-product-checks.yml +130 -54
  58. package/skills/yad-checks/templates/github/yad-product-pr-text.yml +131 -0
  59. package/skills/yad-checks/templates/github/yad-update-guard.yml +2 -1
  60. package/skills/yad-checks/templates/github/yad-verified-commits.yml +49 -3
  61. package/skills/yad-checks/templates/gitlab/yad-checks.gitlab-ci.yml +79 -20
  62. package/skills/yad-checks/templates/gitlab/yad-product-checks.gitlab-ci.yml +59 -9
  63. package/skills/yad-checks/templates/gitlab/yad-update-guard.gitlab-ci.yml +1 -0
  64. package/skills/yad-checks/templates/gitlab/yad-verified-commits.gitlab-ci.yml +49 -1
  65. package/skills/yad-checks/templates/hooks/agent-guard.mjs +44 -10
  66. package/skills/yad-checks/templates/hooks/ledger-guard-cursor.mjs +12 -6
  67. package/skills/yad-commit/SKILL.md +3 -1
  68. package/skills/yad-connect-design/SKILL.md +42 -10
  69. package/skills/yad-connect-design/references/design-context.md +35 -5
  70. package/skills/yad-connect-design/references/design-registry.md +3 -3
  71. package/skills/yad-connect-learning/SKILL.md +12 -2
  72. package/skills/yad-connect-repos/SKILL.md +4 -0
  73. package/skills/yad-connect-testing/SKILL.md +22 -5
  74. package/skills/yad-connect-testing/references/testing-context.md +1 -1
  75. package/skills/yad-epic/SKILL.md +4 -0
  76. package/skills/yad-epic/references/state-schema.md +15 -0
  77. package/skills/yad-guide/SKILL.md +8 -4
  78. package/skills/yad-implement/SKILL.md +56 -4
  79. package/skills/yad-implement/references/implement-conventions.md +2 -1
  80. package/skills/yad-issues/SKILL.md +53 -0
  81. package/skills/yad-learn/SKILL.md +4 -0
  82. package/skills/yad-open-pr/SKILL.md +6 -0
  83. package/skills/yad-pr-template/SKILL.md +2 -1
  84. package/skills/yad-pr-template/templates/checks/pr-title.sh +34 -2
  85. package/skills/yad-product-bridge/references/bridge.md +28 -0
  86. package/skills/yad-product-bridge/templates/github/yad-gate-sync.yml +25 -11
  87. package/skills/yad-product-bridge/templates/gitlab/yad-gate-sync.gitlab-ci.yml +38 -14
  88. package/skills/yad-run/SKILL.md +5 -0
  89. package/skills/yad-scan/SKILL.md +51 -0
  90. package/skills/yad-spec/SKILL.md +13 -2
  91. package/skills/yad-test-cases/SKILL.md +18 -2
  92. package/skills/yad-ui/SKILL.md +43 -8
  93. package/skills/yad-checks/templates/gitlab/.gitlab-ci.yml +0 -49
package/cli/setup.mjs CHANGED
@@ -19,6 +19,7 @@ import { recordActor } from './skip.mjs';
19
19
  import { loadSkillBindings, stepSkills } from './epic-state.mjs';
20
20
  import { offerToolbox, REPOMIX_VERSION } from './toolbox.mjs';
21
21
  import { readAllowList } from './agent-rules.mjs';
22
+ import { PREAPPROVED } from './agent-guard.mjs';
22
23
 
23
24
  // Parse a comma/space separated list into a clean, deduped array of trimmed tokens.
24
25
  export function parseList(s) {
@@ -645,9 +646,9 @@ export async function runSetup(root, opts = {}) {
645
646
  const learningPath = path.join(root, PROJECT_FILES.learningConfig);
646
647
  if (configureTools) {
647
648
  // Connect a design tool (Figma-first, pluggable; the UI step materializes the design here)
648
- S('Connect a design tool (Figma / pencil / none)');
649
+ S(`Connect a design tool (${[...DESIGN_TOOLS, 'none'].join(' / ')})`);
649
650
  guide([
650
- 'Where yad-ui materializes real screens. figma (confirm the MCP later) or none for markdown-only.',
651
+ 'Where yad-ui materializes real screens: figma, pencil or openpencil (confirm its MCP or CLI later), or none for markdown-only.',
651
652
  'Skipping is safe — the UI step degrades to ui-design.md.',
652
653
  ]);
653
654
  if (exists(designPath) && !(opts.reconfigure ?? await askYesNo('design.json exists — reconfigure?', false))) {
@@ -659,7 +660,7 @@ export async function runSetup(root, opts = {}) {
659
660
  tool = DESIGN_PRIMARY;
660
661
  }
661
662
  // A tool named by flag takes its URL by flag too (blank when not given): no prompt.
662
- const project_url = tool === 'none' ? null : (has_(opts.design) ? opts.designUrl : await ask(' project/file URL (blank to set later)', '')) || null;
663
+ const project_url = tool === 'none' ? null : (has_(opts.design) ? opts.designUrl : await ask(tool === 'openpencil' ? ' project URL (blank: each epic keeps its design file in its own design/ folder)' : ' project/file URL (blank to set later)', '')) || null;
663
664
  registerDesign(root, { tool, project_url, today: opts.today ?? null });
664
665
  ok(tool === 'none'
665
666
  ? `wrote ${PROJECT_FILES.designConfig} (markdown-only)`
@@ -806,6 +807,10 @@ export async function runSetup(root, opts = {}) {
806
807
  log(` ${c.bold(who)} ${c.dim('(read-only yad commands Claude Code runs without asking, in .claude/settings.json)')}`);
807
808
  if (allowListShown) { log(` ${c.dim('the same list as above')}`); return; }
808
809
  for (const e of readAllowList()) log(` ${c.dim(e)}`);
810
+ // E167 (#353): what the agent guard also lets run without asking, read word by word (cli/agent-guard.mjs).
811
+ log(` ${c.dim('and, judged by the agent guard each time (YAD_NO_PREAPPROVE=1 turns this off):')}`);
812
+ for (const [k, text] of Object.entries(PREAPPROVED)) if (k !== 'never') log(` ${c.dim(`- ${text}`)}`);
813
+ log(` ${c.dim(`never: ${PREAPPROVED.never}`)}`);
809
814
  allowListShown = true;
810
815
  };
811
816
  for (const repo of registry.repos) {
@@ -934,6 +939,10 @@ export async function runSetup(root, opts = {}) {
934
939
  if (learning && learning.tool && learning.tool !== 'none') {
935
940
  hand(`confirm the learning tool: run \`yad-connect-learning\` to detect the ${learning.tool} CLI (or it degrades to harness-native)`);
936
941
  }
942
+ // E165: each tool in use that is not ready here, offered under the connect-tool rule — one yes per tool.
943
+ for (const f of toolbox?.findings ?? []) {
944
+ if (f.connect) hand(`offer to connect ${f.name}: \`${f.connect}\` (the connect-tool rule: ask once, run only its agent steps)`);
945
+ }
937
946
  log('');
938
947
  log(c.dim('Re-run anytime: `yad check` (report) / `yad check --fix` (reconcile).'));
939
948
  // The --json answer (E1). A --json setup never prompts: every answer comes from a flag, or the run was
package/cli/standup.mjs CHANGED
@@ -3,7 +3,7 @@
3
3
  //
4
4
  // READ-ONLY, DERIVED LIVE, FACTS ONLY. Nothing here is stored; every line is rebuilt from git, the Product
5
5
  // ledgers, the capture branches and the platform each time. No score, no ranking and no judging flag
6
- // (`yad usage`'s rule), and never an email, a commit message, a PR title or a comment body. The one write
6
+ // (`yad usage`'s rule), and never an email, a commit message, a PR title or a comment body. Issue and work item titles are the one exception (E171). The one write
7
7
  // is E131's access cache in git's own folder (`memberStatuses`), never a Product file.
8
8
  //
9
9
  // WHO. The team list is E131's member files. Each member is one block, joined through every identity the
@@ -41,6 +41,7 @@ import { readClaims, fetchCaptures } from './claims.mjs';
41
41
  import { gitIn, wipName, WIP_PREFIX } from './capture.mjs';
42
42
  import { gitAuthors, personKey } from './people.mjs';
43
43
  import { isBot } from './riskmap.mjs';
44
+ import { accountId, buildIssues, mdEscape, mdUrl } from './issues.mjs';
44
45
  import { readMembers, memberStatuses, memberMatches, productIdentity, ttlDays, accountLabel, accessCheck } from './members.mjs';
45
46
  import { ledgerEvents, esc, mdText, writeReport } from './usage.mjs';
46
47
  import { readRegistry, judgeRepo, runnable } from './workspace.mjs';
@@ -168,7 +169,7 @@ function wipSaves(root, env, startMs) {
168
169
 
169
170
  // The repos to read: the Product and every registered repo. `dir` is set only when git may run there
170
171
  // (judged first, E81); `gitUrl` is what the platform is asked about.
171
- export function repoSources(root, identity, productConfig, notRead, env) {
172
+ export function repoSources(root, identity, productConfig, notRead, env, { localPaths = true } = {}) {
172
173
  const productUrl = typeof productConfig?.git_url === 'string' && productConfig.git_url ? productConfig.git_url
173
174
  : (gitIn(root, env)(['remote', 'get-url', 'origin']).out.trim() || '');
174
175
  const out = [{ label: 'Product', dir: root, gitUrl: productUrl, platform: identity.platform }];
@@ -178,7 +179,7 @@ export function repoSources(root, identity, productConfig, notRead, env) {
178
179
  if (!r || typeof r.name !== 'string' || !r.name) continue;
179
180
  const label = forTerminal(r.name);
180
181
  let dir = null;
181
- if (typeof r.path === 'string' && r.path) {
182
+ if (!localPaths) { /* a platform-only read (`yad issues`) needs no checkout */ } else if (typeof r.path === 'string' && r.path) {
182
183
  const j = judgeRepo(root, r);
183
184
  if (runnable(j)) dir = path.resolve(root, r.path);
184
185
  else notRead.push(`${label}: ${j.state === 'missing' ? 'not cloned on this machine' : j.linked ? "reached through a link inside a repo's tree" : safe(j.reason)} — its commits are not read`);
@@ -209,7 +210,7 @@ function whoseWip(members, w) {
209
210
  // and the same login on GitLab can be two people, so the platform and host must match too; an account two
210
211
  // files claim (`matchLogins` leaves it out) matches nobody.
211
212
  const keyOf = (a) => `${a.platform}\0${String(a.host).toLowerCase()}\0${String(a.login).toLowerCase()}`; // members.mjs's accountKey
212
- function whoseAccount(members, { platform, host, login }, disputed = new Set()) {
213
+ export function whoseAccount(members, { platform, host, login }, disputed = new Set()) {
213
214
  const want = keyOf({ platform, host: host || '', login: login || '' });
214
215
  // An account two files claim is matched by nobody — unless it is a member's own primary (E131's rule).
215
216
  const hit = members.filter((m) => m.accounts.some((a) => keyOf(a) === want && (keyOf(a) === keyOf(m.primary) || !disputed.has(want))));
@@ -504,9 +505,21 @@ export function buildStandup(root, { now = Date.now(), tz = 'UTC', since = null,
504
505
  const shape = (m) => ({
505
506
  login: m.primary.login, logins: m.accounts.map((a) => a.login), account: accountLabel(m.primary), accounts: m.accounts.map(accountLabel), status: m.status, lastActive: isDay(m.lastActive) ? m.lastActive : null, ...blocks.get(m),
506
507
  });
507
- const team = members.filter((m) => m.status !== 'left').map(shape);
508
+ // E171. Each member's items: open ones, and those closed in this window. Titles are shown on purpose: a list of
509
+ // numbers is no use in a standup. A repo not read is "not read", through `gapLines`, never "no items".
510
+ const active = members.filter((m) => m.status !== 'left');
511
+ const backlog = active.length ? buildIssues(root, { now, closedSinceMs: win.startMs, env, authCache, ...(runner ? { runner } : {}) }) : { items: [], repos: [], notes: [], registryUnread: false };
512
+ const platformGone = new Set(prMissing.map((p) => p.label));
513
+ // Each repo's failure is said once, with its PR read's line if that failed too. The flag does not depend on that.
514
+ const issuesNotRead = backlog.repos.filter((r) => !r.read && !platformGone.has(r.label)).map((r) => `${r.label}: items not read — ${r.why}`);
515
+ notes.push(...backlog.notes.filter((n) => !notes.includes(n)));
516
+ const issuesUnknown = backlog.registryUnread || backlog.repos.some((r) => !r.read || r.partial) || backlog.items.some((i) => i.assignees.some((a) => a.ambiguous));
517
+ const itemsFor = (m) => backlog.items.filter((i) => i.assignees.some((a) => a.memberKey === accountId(m.primary))).map((i) => ({ ref: i.ref, url: i.url, title: i.title, priority: i.priority, status: i.status, epic: i.epic?.id ?? null, flags: i.flags }));
518
+ const team = active.map((m) => ({ ...shape(m), issues: itemsFor(m) }));
508
519
  const left = members.filter((m) => m.status === 'left').map(shape);
509
520
  return {
521
+ issuesNotRead,
522
+ issuesUnknown,
510
523
  window: { start: new Date(win.startMs).toISOString(), end: new Date(now).toISOString(), tz, basis: win.basis, ledgerFrom: win.startUtcDay },
511
524
  fetched,
512
525
  ttlDays: ttl,
@@ -534,7 +547,7 @@ export function onlyMember(model, login) {
534
547
  // ---- rendering -----------------------------------------------------------------------------------
535
548
 
536
549
  const SECTIONS = [['done', 'Done'], ['working', 'Working on'], ['waiting', 'Waiting']];
537
- const FOOTER = 'Derived, read-only — rebuilt from git, the Product ledgers, the capture branches and the platform each time it runs. Facts only: no score, no ranking, and no emails, commit messages, PR titles or comment bodies.';
550
+ const FOOTER = 'Derived, read-only — rebuilt from git, the Product ledgers, the capture branches and the platform each time it runs. Facts only: no score, no ranking, and no emails, commit messages, PR titles or comment bodies. Issue and work item titles are shown: check before sharing outside the team.';
538
551
 
539
552
  const LOCAL_ONLY = 'no remote named origin — only your own capture branches are read';
540
553
 
@@ -544,6 +557,7 @@ export function gapLines(model) {
544
557
  ...(model.fetched === 'failed' ? ['could not fetch the capture branches — claims and drafts are as last fetched'] : []),
545
558
  ...model.platform.filter((p) => !p.read).map((p) => `${p.repo}: platform not read — ${p.why}`),
546
559
  ...model.notRead,
560
+ ...(model.issuesNotRead ?? []),
547
561
  ...model.notes,
548
562
  ...(model.fetched === 'local' ? [LOCAL_ONLY] : []),
549
563
  ...model.memberErrors,
@@ -577,6 +591,9 @@ const emptyLine = (model) => {
577
591
  return gaps.length ? `nothing recorded here — but ${gaps.join(', and ')}, so something may be missing (see the end)` : 'nothing';
578
592
  };
579
593
 
594
+ const itemMeta = (i) => [i.priority ?? 'no priority', i.status, i.epic ?? 'no epic', ...(i.flags ?? [])].join(' · ');
595
+ const noItems = (model) => (model.issuesUnknown ? 'none found — but some items could not be read or matched to a member (see the end)' : 'none');
596
+
580
597
  function blockText(model, b, title) {
581
598
  log(`\n ${c.bold(title)}`);
582
599
  for (const [k, label] of SECTIONS) {
@@ -584,6 +601,10 @@ function blockText(model, b, title) {
584
601
  if (!b[k].length) log(` ${c.dim(emptyLine(model))}`);
585
602
  for (const it of b[k]) log(` • ${it.text}`);
586
603
  }
604
+ if (!b.issues) return;
605
+ log(` ${c.dim('Assigned items')}`);
606
+ if (!b.issues.length) log(` ${c.dim(noItems(model))}`);
607
+ for (const i of b.issues) log(` • ${forTerminal(i.ref)} ${i.title} ${c.dim(`[${itemMeta(i)}]`)}${i.url ? ` ${i.url}` : ''}`);
587
608
  }
588
609
 
589
610
  const memberTitle = (m) => `${forTerminal(m.login)} ${c.dim(`— ${m.status}${m.lastActive ? `, last active ${m.lastActive}` : ''}${m.accounts.length > 1 ? ` · ${m.accounts.join(', ')}` : ''}`)}`;
@@ -623,6 +644,11 @@ export function renderMarkdown(model) {
623
644
  for (const it of b[k]) L.push(`- ${mdText(it.text)}`);
624
645
  L.push('');
625
646
  }
647
+ if (!b.issues) return;
648
+ L.push('**Assigned items**', '');
649
+ if (!b.issues.length) L.push(`- _${noItems(model)}_`);
650
+ for (const i of b.issues) L.push(`- ${i.url ? `[${mdEscape(i.ref)}](${mdUrl(i.url)})` : mdEscape(i.ref)} ${mdEscape(i.title)} (${mdEscape(itemMeta(i))})`);
651
+ L.push('');
626
652
  };
627
653
  const none = noTeamLine(model);
628
654
  if (none) L.push(`_${mdText(none)}_`, '');
@@ -641,7 +667,7 @@ export function renderMarkdown(model) {
641
667
 
642
668
  export function renderHtml(model) {
643
669
  const list = (items, empty) => (items.length ? `<ul>${items.map((it) => `<li>${esc(it.text)}</li>`).join('')}</ul>` : `<p class="none">${esc(empty)}</p>`);
644
- const block = (b, title, sub = '') => `<section class="member"><h2>${esc(title)}${sub ? ` <span>${esc(sub)}</span>` : ''}</h2>${SECTIONS.map(([k, label]) => `<h3>${label}</h3>${list(b[k], emptyLine(model))}`).join('')}</section>`;
670
+ const block = (b, title, sub = '') => `<section class="member"><h2>${esc(title)}${sub ? ` <span>${esc(sub)}</span>` : ''}</h2>${SECTIONS.map(([k, label]) => `<h3>${label}</h3>${list(b[k], emptyLine(model))}`).join('')}${b.issues ? `<h3>Assigned items</h3>${b.issues.length ? `<ul>${b.issues.map((it) => `<li>${it.url ? `<a href="${esc(it.url)}">${esc(it.ref)}</a>` : esc(it.ref)} ${esc(it.title)} <span class="none">(${esc(itemMeta(it))})</span></li>`).join('')}</ul>` : `<p class="none">${esc(noItems(model))}</p>`}` : ''}</section>`;
645
671
  const missing = gapLines(model);
646
672
  return `<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">
647
673
  <title>yadflow — standup</title><style>
@@ -152,7 +152,8 @@ export function readDesignConfig(root) {
152
152
  // when the answer is no; the yad-spec and yad-implement skills make the call and stop on a failure.
153
153
  // null when the story names no frame (no UI task, nothing to check). `reachable` is `check` (probe, and
154
154
  // stop when it fails) or `not-checkable` (nothing to probe: go on with the links). `appBound` is true (read
155
- // through the running app), false (a hosted server: sign in) or null (yad cannot tell: `stop` names both).
155
+ // through the running app), false (no app: a hosted server, so sign in — or, with `local` true, a CLI that
156
+ // works on the design file on disk, E164) or null (yad cannot tell: `stop` names both).
156
157
  export function designPreflight(design, links, frames) {
157
158
  if (!frames.length) return null;
158
159
  const d = design.state === 'ok' ? design.data : null;
@@ -184,14 +185,21 @@ export function designPreflight(design, links, frames) {
184
185
  // Every recorded ID is unresolved: the bad IDs are the problem (the warnings name them), not the app.
185
186
  const found = frames.find((f) => f.found);
186
187
  if (!found) return notCheckable('no recorded frame is in design-links.json — fix the frame IDs first');
187
- const appBound = reach.appBound === true || listed(reach.appBound) ? true : listed(reach.signInOnly) ? false : null;
188
+ const local = listed(reach.local);
189
+ const appBound = local ? false : reach.appBound === true || listed(reach.appBound) ? true : listed(reach.signInOnly) ? false : null;
188
190
  // design.json's project_url is a project, not a file, so it is never compared against.
189
191
  const file = links.fileUrl;
190
192
  const fill = (s) => s.replace(/<file>/g, file ? `\`${forTerminal(file)}\`` : 'the design file').replace(/<frame>/g, `\`${forTerminal(found.id)}\``);
191
193
  return {
192
- tool, provider, reachable: 'check', appBound, file, frame: found.id,
193
- probe: fill(reach.probe),
194
- stop: fill(appBound === true ? reach.open : appBound === false ? reach.signIn : reach.either),
194
+ tool, provider, reachable: 'check', appBound, local, file, frame: found.id,
195
+ probe: fill(local ? reach.localProbe : appBound === null && reach.eitherProbe ? reach.eitherProbe : reach.probe),
196
+ stop: fill(local ? reach.localStop : appBound === true ? reach.open : appBound === false ? reach.signIn : reach.either),
197
+ // E165: when the probe fails because the tool is not on this machine at all (not a closed app or a
198
+ // sign-in), the agent offers this first, under the connect-tool rule. A tool with a reach rule is shipped.
199
+ // Not for a provider that is one app's own server (`reach.ownServer`: Figma's figma-desktop): the tool's
200
+ // recipe connects its other server, so the person opens the app instead, as `stop` says. OpenPencil's
201
+ // MCP server is not one: its recipe adds it.
202
+ ...(listed(reach.ownServer) ? {} : { connect: `yad toolbox connect ${tool} --json` }),
195
203
  };
196
204
  }
197
205
 
@@ -290,7 +298,10 @@ export async function runStory(root, { action, story, json = false } = {}) {
290
298
  }
291
299
  for (const w of warnings) warn(w);
292
300
  const p = r.preflight;
293
- if (p?.reachable === 'check') hand(`before UI work: ${p.probe} — if that fails, stop: ${p.stop}`);
301
+ if (p?.reachable === 'check') {
302
+ hand(`before UI work: ${p.probe} — if that fails, stop: ${p.stop}`);
303
+ if (p.connect) hand(`if ${forTerminal(p.tool)} is not on this machine at all, your agent can offer to connect it first: \`${p.connect}\``);
304
+ }
294
305
  else if (p) info(`before UI work: the design tool is not checked (${p.why}) — build from the frame links`);
295
306
  return { ok: true, ...r };
296
307
  }