geneseed 4.10.0 → 4.15.1

package/js/hosts/link.mjs

@@ -74,6 +74,7 @@
 import {
   chmodSync, existsSync, lstatSync, mkdirSync, readlinkSync, rmSync,
 } from 'node:fs';
+import { isatty } from 'node:tty';
 import { spawnSync } from 'node:child_process';
 import path from 'node:path';
 import os from 'node:os';
@@ -81,12 +82,84 @@ import os from 'node:os';
 import { ROOT } from '../build/source.mjs';
 import { readMaybe } from './installs.mjs';
 import { printOut, printErr, writeText } from '../lib/fs.mjs';
+import { confirm } from '../lib/prompt.mjs';
 import { toPlatformPath, which } from '../lib/paths.mjs';
 
 const IS_WIN = process.platform === 'win32';
 /** What `cmdUnlink` recognises a written Unix launcher by — see `isOurLauncher`. */
 const SHIM_MARKER = 'GENESEED_LINK_SHIM';
 
+/** The lines that open and close the PATH block `link` writes into a shell startup file. */
+const RC_BEGIN = '# >>> geneseed >>> (added by `geneseed link`; `geneseed unlink` removes it)';
+const RC_END = '# <<< geneseed <<<';
+
+/**
+ * The startup file to put the bin dir on PATH in, for this login shell — or null when it is
+ * not one we know how to edit (fish, csh, none), where `link` prints the line instead.
+ *
+ * zsh reads `$ZDOTDIR/.zshrc` (default `~`). bash reads `~/.bashrc` on Linux, but macOS
+ * Terminal opens LOGIN shells, which read `~/.bash_profile` and not `~/.bashrc`. Pure, for the
+ * test: nothing here may touch the real user's files.
+ */
+export function shellRcFile({
+  shell = process.env.SHELL || '', home = os.homedir(), zdotdir = process.env.ZDOTDIR,
+  platform = process.platform,
+} = {}) {
+  const name = path.basename(shell);
+  if (name === 'zsh') return path.join(zdotdir || home, '.zshrc');
+  if (name === 'bash') return path.join(home, platform === 'darwin' ? '.bash_profile' : '.bashrc');
+  return null;
+}
+
+/**
+ * `text` with the PATH block for `dir` appended, or unchanged when a block is already there.
+ *
+ * The dir goes inside double quotes with `\`, `"`, `$` and backtick escaped, so a home path
+ * holding any of them stays one literal word to the shell rather than becoming code.
+ */
+export function withPathBlock(text, dir) {
+  if (text.includes(RC_BEGIN)) return text;
+  const quoted = dir.replace(/[\\"$`]/g, (c) => `\\${c}`);
+  const sep = text === '' || text.endsWith('\n') ? '' : '\n';
+  return `${text}${sep}${RC_BEGIN}\nexport PATH="${quoted}:$PATH"\n${RC_END}\n`;
+}
+
+/** `text` without the PATH block `withPathBlock` wrote; unchanged when there is none. */
+export function withoutPathBlock(text) {
+  const start = text.indexOf(RC_BEGIN);
+  if (start < 0) return text;
+  const end = text.indexOf(RC_END, start);
+  if (end < 0) return text;
+  let stop = end + RC_END.length;
+  if (text[stop] === '\n') stop += 1;
+  return text.slice(0, start) + text.slice(stop);
+}
+
+/**
+ * Put `dir` on PATH for future shells, ASKING first — macOS zsh does not search
+ * `~/.local/bin`, so a linked `geneseed` was not found (reported 2026-10). Only in a terminal:
+ * the web console's button and every test run without one, and get the printed line instead,
+ * so no gate can edit the developer's own startup file. Returns whether it wrote.
+ */
+function offerShellPath(dir) {
+  const rc = shellRcFile();
+  if (!rc || !isatty(0)) return false;
+  const text = readMaybe(rc) ?? '';
+  if (text.includes(RC_BEGIN)) {
+    printOut(`geneseed: ${rc} already adds it — open a NEW terminal, then run 'geneseed'.\n`);
+    return true;
+  }
+  if (!confirm(`geneseed: add '${dir}' to your PATH in ${rc}?`, true)) return false;
+  try {
+    writeText(rc, withPathBlock(text, dir));
+  } catch (e) {
+    printErr(`geneseed: could not write ${rc} (${asOsError(e)})\n`);
+    return false;
+  }
+  printOut(`geneseed: added it to ${rc} — open a NEW terminal, then run 'geneseed'.\n`);
+  return true;
+}
+
 /** `_harness_lifecycle._win_bin_dir`. */
 function winBinDir() {
   // `os.environ.get(...) or str(Path.home())` — an EMPTY LOCALAPPDATA falls back too,
@@ -267,7 +340,7 @@ export function cmdLink(args) {
   printOut(`geneseed: linked ${dest} -> ${entry}\n`);
   if ((process.env.PATH || '').split(path.delimiter).includes(targetDir)) {
     printOut(`geneseed: '${targetDir}' is on PATH — run 'geneseed' from anywhere.\n`);
-  } else {
+  } else if (!offerShellPath(targetDir)) {
     printOut(`geneseed: NOTE '${targetDir}' is not on your PATH. Add it, e.g.:\n`);
     printOut(`  echo 'export PATH="${targetDir}:$PATH"' >> ~/.zshrc   # or ~/.bashrc\n`);
   }
@@ -311,6 +384,20 @@ export function cmdUnlink() {
       } catch { /* `except OSError: pass` */ }
     }
   }
+  // The PATH block `link` may have written, from each startup file it could have chosen.
+  const home = os.homedir();
+  const rcs = new Set([shellRcFile({ shell: 'zsh' }), path.join(home, '.bashrc'),
+    path.join(home, '.bash_profile')]);
+  for (const rc of rcs) {
+    const text = readMaybe(rc);
+    if (text === null || withoutPathBlock(text) === text) continue;
+    try {
+      writeText(rc, withoutPathBlock(text));
+      printOut(`geneseed: removed the PATH line from ${rc}\n`);
+    } catch (e) {
+      printErr(`geneseed: could not edit ${rc} (${asOsError(e)})\n`);
+    }
+  }
   if (!removed) printOut('geneseed: no linked launcher found on PATH\n');
   return 0;
 }

package/js/inspect/checks-build.mjs

@@ -10,7 +10,7 @@ import path from 'node:path';
 import { stripCapabilityLinks } from '../build/emit-common.mjs';
 import { STRUCTURE, renderAll } from '../build/render.mjs';
 import { CONFIG, CREDIT_RE, makeCfg } from '../build/source.mjs';
-import { hostCatalogsNatively, resolvePath } from '../hosts/hosts.mjs';
+import { CLAUDE_STYLE, hostCatalogsNatively, resolvePath } from '../hosts/hosts.mjs';
 import { EMIT_HOST_SCOPE, footprintOfDir, themeFiles } from '../hosts/installs.mjs';
 import { isVendoredPath } from '../hosts/native.mjs';
 import { PALETTE_ROLES, colorThemeFiles } from '../hosts/opencode.mjs';
@@ -217,7 +217,13 @@ export function renderedProblems(bundle) {
   else themeName = 'neutral';
   let emit;
   try { emit = readText(path.join(bundle, '.geneseed-emit')).trim(); } catch { emit = ''; }
-  const host = (EMIT_HOST_SCOPE.get(emit) ?? ['', ''])[0];
+  const [host, scope] = EMIT_HOST_SCOPE.get(emit) ?? ['', ''];
+  // A Claude-shaped PROJECT install is not a bundle: its tree is `AGENTS.md`/`CLAUDE.md` plus a
+  // `.bob/`/`.claude/`/`.openclaude/` data dir, so every rendered file reads "missing" and no
+  // rebuild can clear it. The console's onboarding once put a Bob project install exactly here
+  // (`./Harness` under the checkout, reported 2026-10: 178 such lines). Its own drift is
+  // `geneseed diff`'s and `status`'s to report, not this committed-bundle check's.
+  if (scope === 'project' && CLAUDE_STYLE.includes(host)) return [];
   let items;
   try {
     // THE FIRST CALLER IN THE PORT THAT CATCHES A REFUSAL, and that is why the stderr is

package/js/inspect/cost.mjs

@@ -35,7 +35,7 @@ import { isFile, readText } from '../lib/fs.mjs';
  * console draws it on the cost chart, so it lives here, once, where both read it. Raise it by
  * exactly the measured overrun and say why in that test's docblock, which keeps its history.
  */
-export const CARRIER_CEILING = { full: 62_219, lean: 39_111 };
+export const CARRIER_CEILING = { full: 63_266, lean: 39_628 };
 
 /**
  * A frontmatter value as the host shows it. The emit writes descriptions JSON-escaped

package/js/inspect/diff.mjs

@@ -321,8 +321,38 @@ export function diffCollect({
 /** The records that are drift: everything but a `linked` path, which is the user's own. */
 export const drifted = (files) => files.filter((f) => f.status !== 'linked');
 
+/** Where the self-improvement loops write, relative to an install's `notebook/`. */
+export const NOTES_DIRS = ['skill-notes', 'agent-notes'];
+
+/**
+ * The self-improvement notes an install has accumulated, as `{rel, body}` sorted by `rel`.
+ *
+ * WHY THESE ARE NOT DRIFT. The loops used to edit the rendered skill and agent files in place,
+ * which the doctor reported as stale and the next rebuild erased. They now write a sidecar
+ * under the notebook — seed-once and agent-owned, never in the manifest, so no rebuild touches
+ * it. That makes the notes the back-port QUEUE rather than an endangered edit: `diff` lists
+ * them and `--out` carries them so they can reach `src/`, but the upgrade export does not
+ * fire on them alone, because there is nothing for the rebuild to destroy. Empty files are
+ * skipped — an agent that cleared its notes has nothing to back-port.
+ */
+export function collectNotes(dir) {
+  const notes = [];
+  for (const sub of NOTES_DIRS) {
+    const d = path.join(dir, 'notebook', sub);
+    let names;
+    try { names = readdirSync(d); } catch { continue; }
+    for (const n of names.filter((x) => x.endsWith('.md')).sort()) {
+      const a = path.join(d, n);
+      if (!isFile(a)) continue;
+      const body = readText(a);
+      if (body.trim()) notes.push({ rel: `notebook/${sub}/${n}`, body });
+    }
+  }
+  return notes;
+}
+
 /** `_harness_diff._improvements_md` — pure; `when` is the caller's timestamp. */
-export function improvementsMd(target, theme, allFiles, when) {
+export function improvementsMd(target, theme, allFiles, when, notes = []) {
   // A linked path is never a back-port item: the file is the user's, not a local edit of ours.
   const files = drifted(allFiles);
   const edited = files.filter((f) => f.status === 'edited');
@@ -337,8 +367,8 @@ export function improvementsMd(target, theme, allFiles, when) {
     `- ${edited.length} edited · ${added.length} added in deployed · `
       + `${missing.length} missing from deployed`,
     '',
-    'The deployed harness drifted from a fresh render of `src/` — typically the',
-    'self-improvement loops editing agent/skill files in place. Hand this file to',
+    'The deployed harness drifted from a fresh render of `src/` — typically',
+    'agent/skill files edited in place, by hand or by an older harness. Hand this file to',
     'an agent in the Geneseed source repo and ask it to fold the changes below',
     'back into `src/`. Diffs read source -> deployed; the expected copy was',
     'rendered in the deployed theme, so only genuine local edits appear.',
@@ -352,6 +382,17 @@ export function improvementsMd(target, theme, allFiles, when) {
   for (const f of files) {
     lines.push(`## \`${f.rel}\`  (${label[f.status]})`, '', '```diff', ...f.diff, '```', '');
   }
+  // Only when there are notes, so a report without them stays byte-identical.
+  if (notes.length) {
+    lines.push('# Self-improvement notes', '',
+      'Corrections the agent recorded against a skill or agent instead of editing it.',
+      'Fold each one into the matching file under `src/`, then clear the note. Judge it by',
+      'its `seen:` evidence — a line without one is a claim, not a lesson — and weigh a',
+      '`[general]` line as a law, doctrine or memory rather than an edit to that one file.', '');
+    for (const n of notes) {
+      lines.push(`## \`${n.rel}\``, '', '```markdown', ...splitLines(n.body), '```', '');
+    }
+  }
   return `${lines.join('\n')}\n`;
 }
 
@@ -385,7 +426,9 @@ function stamp(d) {
  * the same instant, so a run that crosses a second boundary cannot name a file one second
  * away from what it says inside.
  */
-export function writeImprovements(target, theme, files, outPath = null) {
+export function writeImprovements(
+  target, theme, files, outPath = null, notes = collectNotes(target),
+) {
   const now = stamp(new Date());
   // `Path(out_path).expanduser()` — again NOT resolved, and again observable: the path is
   // printed, so `--out p.md` reports `p.md`.
@@ -393,7 +436,7 @@ export function writeImprovements(target, theme, files, outPath = null) {
     ? expanduser(outPath)
     : path.join(target, 'improvements', now.file);
   mkdirSync(path.dirname(p), { recursive: true });
-  writeText(p, improvementsMd(target, theme, files, now.when));
+  writeText(p, improvementsMd(target, theme, files, now.when, notes));
   return p;
 }
 
@@ -477,18 +520,21 @@ export function cmdDiff(args) {
     + `${missing.length} missing-from-deployed\n`);
   // Its own line, printed only when there is one, so the summary above is unchanged otherwise.
   if (linked.length) printOut(`[diff] ${linked.length} linked (yours, left alone)\n`);
+  const notes = collectNotes(target);
+  if (notes.length) printOut(`[diff] ${notes.length} self-improvement note(s) to back-port\n`);
   for (const f of edited) printOut(`  ~ ${f.rel}   (edited in deployed — review to back-port)\n`);
   for (const f of added) printOut(`  + ${f.rel}   (only in deployed — your addition)\n`);
   for (const f of missing) printOut(`  - ${f.rel}   (in source, not deployed — re-emit to add)\n`);
   for (const f of linked) printOut(`  = ${f.rel}   (a link — yours, left alone)\n`);
+  for (const n of notes) printOut(`  * ${n.rel}   (self-improvement note — review to back-port)\n`);
   if (args.out) {
-    if (drifted(files).length) {
+    if (drifted(files).length || notes.length) {
       // Bare `--out` is argparse's `nargs="?"` const: True, meaning "the default timestamped
       // path". `parse()` gives a flag `true` and an option a string, so the two arrive
       // distinguishable here without a third kind of entry in the VERBS table.
       const outPath = args.out === true ? null : args.out;
       printOut(`[diff] improvements file written: ${
-        writeImprovements(target, theme, files, outPath)}\n`);
+        writeImprovements(target, theme, files, outPath, notes)}\n`);
     } else {
       printOut('[diff] no differences — nothing written.\n');
     }

package/js/inspect/inventory.mjs

@@ -97,6 +97,7 @@ export const SKILL_CLASS = {
   'frontend-design': 'build', prototype: 'build', deck: 'build',
   'forge-mcp': 'build', bruno: 'build', worktree: 'build',
   'spring-boot': 'build', 'spring-data-jpa': 'build', 'spring-testing': 'build',
+  react: 'build', 'react-testing': 'build',
   'geneseed-code-review': 'review', 'fresh-eyes': 'review', 'security-audit': 'review',
   'roast-me': 'review', 'review-response': 'review', ponytail: 'review',
   commit: 'ship', ship: 'ship', release: 'ship', handoff: 'ship',

package/js/lib/prompt.mjs

@@ -12,6 +12,9 @@ import { readSync } from 'node:fs';
 import { printOut } from './fs.mjs';
 import { parseIntStrict } from './text.mjs';
 
+/** A cell to `Atomics.wait` on: the synchronous pause between `readLine`'s EAGAIN retries. */
+const PAUSE = new Int32Array(new SharedArrayBuffer(4));
+
 /**
  * `_harness_setup._ask` — `input(f"{prompt}{suffix}: ").strip()`, or the default at EOF.
  *
@@ -71,14 +74,28 @@ export function promptLine(prompt) {
  * the wizard's first non-ASCII answer is what exposed it, and the corpus caught it on the
  * first run. Scanning for the terminators a byte at a time is still correct: `\n` and `\r`
  * are ASCII, and no continuation byte of a UTF-8 sequence is below 0x80.
+ *
+ * EAGAIN IS "NOTHING TYPED YET", NOT EOF. Touching `process.stdin` — even `.isTTY`, which
+ * `cmdSetup` reads first — makes libuv put a terminal fd 0 in non-blocking mode, and from then
+ * on `readSync` throws EAGAIN until a key is pressed. Caught as EOF, every prompt took its
+ * default the instant it printed: setup's "Continue without one? (y/N)" answered itself N and
+ * the install stopped before anyone could type (reported 2026-10, reproduced under a pty). So
+ * it waits 20 ms and reads again; any other error is still the end of input. `read` is the
+ * test seam.
  */
-function readLine() {
+export function readLine(read = readSync) {
   const buf = Buffer.alloc(1);
   const bytes = [];
   let eof = false;
   for (;;) {
     let n = 0;
-    try { n = readSync(0, buf, 0, 1, null); } catch { eof = true; break; }
+    try {
+      n = read(0, buf, 0, 1, null);
+    } catch (e) {
+      if (e && e.code === 'EAGAIN') { Atomics.wait(PAUSE, 0, 0, 20); continue; }
+      eof = true;
+      break;
+    }
     if (n === 0) { eof = true; break; }
     if (buf[0] === 0x0a) break;
     if (buf[0] !== 0x0d) bytes.push(buf[0]);

package/js/maintain/setup.mjs

@@ -41,7 +41,8 @@
  * a cell could not have varied the answers at all.
  */
 import { spawnSync } from 'node:child_process';
-import { existsSync } from 'node:fs';
+import { existsSync, readdirSync } from 'node:fs';
+import os from 'node:os';
 import path from 'node:path';
 
 import { main as driverMain, resolveOut } from '../build/driver.mjs';
@@ -228,9 +229,11 @@ function askDoctrines(deployed = null) {
 }
 
 /**
- * The Kits question (spec A5): one pick, a kit or `none`, defaulting to what the install has on
- * (`deployed`, its `Active kits:` marker). Asked ONLY when this checkout ships a kit, so a kit-less
- * wizard reads exactly the stdin it always did (and has no kit to carry: `kitsOfDir` drops an unshipped one).
+ * The Kits questions (spec A5): one yes/no per shipped kit, each defaulting to whether the install
+ * has it on (`deployed`, its `Active kits:` marker), so holding Enter keeps the installed set. A
+ * single pick could not hold two kits at once, which is why the menu became per kit when the second
+ * kit shipped. Asked ONLY when this checkout ships a kit, so a kit-less wizard reads exactly the
+ * stdin it always did (and has no kit to carry: `kitsOfDir` drops an unshipped one).
  * Returns the kit list, or null for none (`setupBuildArgs` omits `--kits`).
  */
 export function askKits(deployed = null, kits = null) {
@@ -239,14 +242,9 @@ export function askKits(deployed = null, kits = null) {
     return null;
   }
   const on = (deployed ?? []).filter((k) => kits.has(k));
-  if (!kits.size) return null;
-  const opts = [...kits].map(([k, m]) => [k, m.description ?? '']);
-  // shortcut: one pick per run, so several deployed kits are offered as one "keep" option; ask
-  // per kit once a second kit ships.
-  if (on.length > 1) opts.push([on.join(','), 'keep the installed kits']);
-  opts.push(['none', 'no kit']);
-  const pick = askChoice('Kits', opts, on.length ? on.join(',') : 'none');
-  return pick === 'none' ? null : pick.split(',');
+  const picked = [...kits].filter(([k, m]) => askChoice(`Kit ${k} — ${m.description ?? k}`,
+    [['yes', `install the ${k} kit`], ['no', `leave ${k} out`]], on.includes(k) ? 'yes' : 'no') === 'yes');
+  return picked.length ? picked.map(([k]) => k) : null;
 }
 
 /**
@@ -521,8 +519,8 @@ export function setupLines() {
     doctrines = null, excludeRules = null, excludeSkills = null, gates = {}, kits = null,
   } = sel;
   if (emit === 'opencode-global') {
-    // The build below overwrites the deployed global harness, and the self-improvement loops
-    // may have edited it in place. Preserve that drift first.
+    // The build below overwrites the deployed global harness, which may carry hand edits (or
+    // in-place edits from a harness older than the notebook notes). Preserve that drift first.
     try {
       const [ipath] = exportImprovements();
       if (ipath) {
@@ -575,26 +573,83 @@ export function cmdSetup() {
 }
 
 /**
- * The AI coding tools Geneseed installs into, as `[label, present, url]` rows in HOSTS order.
+ * The AI coding tools Geneseed installs into, as `[label, present, url, where]` rows in HOSTS
+ * order. `where` is the path found OFF the PATH (see `userInstall`), else null.
  *
- * PRESENT MEANS THE COMMAND IS ON PATH, and nothing else. The config dir looked like a second
- * signal — a desktop-only install has one and no command — but GENESEED ITSELF CREATES IT: a
- * `bob-global` emit writes `~/.bob` on a machine that never had Bob, and the first run of this
- * check reported Bob present on exactly such a machine. A wrong "ok" sends the user to an
- * install mode for a tool they cannot open; a wrong "not found" costs one line they can ignore.
+ * PRESENT MEANS THE TOOL ITSELF WAS FOUND — its command on PATH, or its program in a per-user
+ * install location — and never its config dir. That dir looked like a signal — a desktop-only
+ * install has one and no command — but GENESEED ITSELF CREATES IT: a `bob-global` emit writes
+ * `~/.bob` on a machine that never had Bob, and the first run of this check reported Bob present
+ * on exactly such a machine. A wrong "ok" sends the user to an install mode for a tool they
+ * cannot open; a wrong "not found" costs a line, and `toolsReport` lets them name the path.
  *
  * NO SPAWN, deliberately. `which` walks PATH by hand, so asking costs nothing on the CLI's
  * child_process allow-list — a `claude --version` probe would have been a third entry there to
- * learn nothing `which` does not already say. `lookup` is the seam for the test, which cannot
- * rely on what this machine happens to have installed.
+ * learn nothing `which` does not already say. `lookup` and `userLookup` are the seams for the
+ * test, which cannot rely on what this machine happens to have installed.
  */
-export function hostTools({ lookup = which } = {}) {
+export function hostTools({ lookup = which, userLookup = userInstall } = {}) {
   return [
     ['OpenCode', 'opencode', 'https://opencode.ai/docs/'],
     ['Claude Code', 'claude', 'https://code.claude.com/docs/en/setup'],
     ['IBM Bob', 'bob', 'https://bob.ibm.com/'],
     ['OpenClaude', 'openclaude', 'https://openclaude.gitlawb.com/'],
-  ].map(([label, cmd, url]) => [label, Boolean(lookup(cmd)), url]);
+  ].map(([label, cmd, url]) => {
+    if (lookup(cmd)) return [label, true, url, null];
+    const where = userLookup(cmd);
+    return [label, Boolean(where), url, where || null];
+  });
+}
+
+/**
+ * Per-host off-PATH places: a bin dir a tool's own installer uses, and a name pattern for the
+ * desktop app folder. Only Bob ships as a desktop IDE; matching `claude` against app folders
+ * would find the Claude desktop chat app, which is not Claude Code.
+ */
+const USER_BIN_DIRS = {
+  opencode: ['.opencode/bin'],
+  claude: ['.claude/local'],
+  bob: [],
+  openclaude: [],
+};
+const APP_PATTERN = { bob: /\bbob\b/i };
+
+/**
+ * Where a tool installed FOR ONE USER lives when its installer did not put it on PATH — the
+ * report of 2026-10 was IBM Bob installed under the user's own profile, which `which` never sees.
+ *
+ * Three kinds of place, each one the tool's own program, never its config dir:
+ *   * a per-user bin dir: `~/.local/bin` and `~/bin` for every tool, plus the dir its own
+ *     installer uses (`USER_BIN_DIRS`) — an executable file, through `which` and its PATHEXT;
+ *   * on Windows, `%APPDATA%\npm` (a per-user `npm i -g`) and a desktop app folder under
+ *     `%LOCALAPPDATA%\Programs` whose name matches `APP_PATTERN`;
+ *   * on macOS, a matching `.app` in `/Applications` or `~/Applications`.
+ * The first hit wins. Everything a machine could differ on is a parameter, for the test.
+ */
+export function userInstall(cmd, {
+  home = os.homedir(), env = process.env, platform = process.platform,
+  find = which, list = listDir,
+} = {}) {
+  const bins = ['.local/bin', 'bin', ...(USER_BIN_DIRS[cmd] ?? [])].map((d) => path.join(home, d));
+  if (platform === 'win32' && env.APPDATA) bins.push(path.join(env.APPDATA, 'npm'));
+  const hit = find(cmd, bins.join(path.delimiter));
+  if (hit) return hit;
+  const pattern = APP_PATTERN[cmd];
+  if (!pattern) return null;
+  const appDirs = platform === 'win32'
+    ? (env.LOCALAPPDATA ? [path.join(env.LOCALAPPDATA, 'Programs')] : [])
+    : platform === 'darwin' ? ['/Applications', path.join(home, 'Applications')] : [];
+  for (const dir of appDirs) {
+    const name = list(dir).find((n) => pattern.test(n)
+      && (platform !== 'darwin' || n.endsWith('.app')));
+    if (name) return path.join(dir, name);
+  }
+  return null;
+}
+
+/** `readdirSync`, with a missing or unreadable dir as no entries. */
+function listDir(dir) {
+  try { return readdirSync(dir); } catch { return []; }
 }
 
 /**
@@ -602,16 +657,25 @@ export function hostTools({ lookup = which } = {}) {
  * answer knowing it — and when NONE is, ask whether to stop and install one first. It never
  * installs one: on a managed machine that is IT's call, and each tool has its own installer.
  * A missing tool among several present is a line, not a question; nobody needs all four.
+ * When none is found, the user can name where theirs is before being asked to stop — the
+ * search covers PATH and the usual per-user places, not every folder an installer may pick.
  * `false` is the user choosing to stop.
  */
 export function toolsReport(tools = hostTools()) {
   printOut('AI coding tools on this machine:\n');
-  for (const [label, present, url] of tools) {
-    printOut(present ? `  ok  ${label}\n` : `  --  ${label} not on PATH — install: ${url}\n`);
+  for (const [label, present, url, where] of tools) {
+    if (!present) printOut(`  --  ${label} not found — install: ${url}\n`);
+    else printOut(where ? `  ok  ${label} (${where}, not on PATH)\n` : `  ok  ${label}\n`);
   }
   if (tools.some(([, present]) => present)) { printOut('\n'); return true; }
-  printOut('\nNone of them is installed. Install the one you use (links above), then run setup '
-    + 'again — or go on and pick the plain bundle, which any AGENT.md tool can read.\n');
+  printOut('\nNone of them was found on PATH or in the usual per-user folders.\n');
+  // Quotes stripped: a path dragged into a Windows console arrives wrapped in them.
+  const given = ask('Installed somewhere else? Path to the tool (Enter to skip)')
+    .replace(/^"(.*)"$/, '$1');
+  if (given && existsSync(given)) { printOut(`  ok  ${given}\n\n`); return true; }
+  if (given) printOut(`  --  nothing at ${given}\n`);
+  printOut('Install the one you use (links above), then run setup again — or go on and pick the '
+    + 'plain bundle, which any AGENT.md tool can read.\n');
   if (confirm('Continue without one?', false)) { printOut('\n'); return true; }
   printOut('Stopped. Run setup again once a tool is installed.\n');
   return false;

package/js/maintain/update.mjs

@@ -796,8 +796,8 @@ export async function upgrade(ref = null, themeArg = null) {
  * `_harness_lifecycle.cmd_upgrade` — the harness verb, which is `export_improvements()` and
  * then `upgrade()`.
  *
- * THE EXPORT RUNS FIRST AND MUST NEVER BLOCK. The self-improvement loops edit the deployed
- * harness in place and the rebuild is about to overwrite those edits, so the drift has to be
+ * THE EXPORT RUNS FIRST AND MUST NEVER BLOCK. A deployed harness can carry in-place edits (by
+ * hand, or by a harness older than the notebook notes) and the rebuild is about to overwrite them, so the drift has to be
  * captured against the PRE-refresh source. Anything it throws is a warning on stderr and the
  * upgrade continues — a failed export is a lost note, a blocked upgrade is a broken install.
  */

package/js/web/actions.mjs

@@ -475,6 +475,14 @@ export function buildActionCmds(state, body) {
     const [, , ...rest] = installProfile(host, scope, state.root).argv;
     return actionCommands('build', { buildArgv: ['--theme', theme, ...rest] });
   }
+  // Only a GLOBAL emit has a home of its own. Any other carries no folder on this route, so the
+  // generator fell back to its default `./Harness` — and jobs run with the Geneseed checkout as
+  // cwd, so a Bob "project" install landed inside the clone (reported 2026-10), where the doctor's
+  // bundle check then read it as 178 missing files. The `deploy` action takes a chosen folder.
+  if (!emit.endsWith('-global')) {
+    return { error: `${emit} installs into a folder you choose — use Deploy with a folder, `
+      + 'not Build' };
+  }
   return actionCommands('build', {
     theme, emit, footprint: state.footprint, posture: state.posture, mode: state.mode,
     trust: state.trust,

package/js/web/api.mjs

@@ -8,21 +8,21 @@
  * bind paths to these functions are `routes.mjs`. This file imports none of its route siblings,
  * which is what keeps the old `api ↔ actions` and `api ↔ activity` cycles from coming back.
  */
-import { statSync } from 'node:fs';
+import { readdirSync, statSync } from 'node:fs';
 import path from 'node:path';
 
-import { CONFIG, ROOT, THEMES, discoverNames, loadKits, makeCfg } from '../build/source.mjs';
+import { CONFIG, CREDIT_RE, ROOT, SRC, THEMES, discoverNames, loadKits, makeCfg, upstreamOf } from '../build/source.mjs';
 import { readVersion, sourceFingerprint } from '../build/version.mjs';
 import { sourceReleaseVersion } from '../hosts/opencode.mjs';
 import { alwaysOnCost } from '../inspect/cost.mjs';
 import { installProfile } from '../build/generate.mjs';
 import { diffCollect, renderMemo } from '../inspect/diff.mjs';
 import { excludesSnapshot } from '../inspect/excludes.mjs';
-import { CLAUDE_STYLE, HOSTS, VERSION_MARKER, resolvePath } from '../hosts/hosts.mjs';
+import { VERSION_MARKER, resolvePath } from '../hosts/hosts.mjs';
 import {
   footprintOfDir, gatesOfDir, installState, installTargets, legacyProcessCarrierOfDir, modeOfDir,
   trustOfDir,
-  postureOfDir, readJsonMaybe, themeOfDir,
+  postureOfDir, readJsonMaybe, readMaybe, themeOfDir,
 } from '../hosts/installs.mjs';
 import { PRESETS } from '../loop/score.mjs';
 import { loadCatalog, catalogProblems } from '../loop/catalog.mjs';
@@ -34,7 +34,7 @@ import { comparePaths, normcase } from '../lib/paths.mjs';
 import {
   configItems, deployed, dget, memoryItems, notebookItems, wikiItems,
 } from './catalog.mjs';
-import { stampMinute } from './state.mjs';
+import { stampMinute, viewCfg } from './state.mjs';
 import { updateStatus } from './update-check.mjs';
 
 /**
@@ -108,16 +108,9 @@ export function apiDiff(state) {
 /** The union across every global install, verbatim. */
 export const apiExcludes = () => excludesSnapshot();
 
-/**
- * The data dir an install's inventory/memory/diff is read from. Host-driven, so a new
- * nested-marker host cannot silently read the bare root.
- */
-export function viewCfg(host, scope, root) {
-  if (scope === 'project' && CLAUDE_STYLE.includes(host)) {
-    return path.join(root, HOSTS.find((h) => h.host === host).projectMarker);
-  }
-  return root;
-}
+// `viewCfg` moved to `state.mjs`, which needs it to pick a default view and cannot import
+// this module back (this one imports `stampMinute` from it).
+export { viewCfg } from './state.mjs';
 
 const DAY_MS = 24 * 60 * 60 * 1000;
 
@@ -233,6 +226,31 @@ export function apiFleet(state) {
   return { installs, source_fp: sourceFp, doctor: state.doctor };
 }
 
+/** Source files of a kit member: `<dir>/<name>.md`, or every `.md` in a `<dir>/<name>/` folder. */
+function memberTexts(dir, name) {
+  const one = readMaybe(path.join(SRC, dir, `${name}.md`));
+  if (one !== null && one !== undefined) return [one];
+  const d = path.join(SRC, dir, name);
+  try { return readdirSync(d).filter((f) => f.endsWith('.md')).map((f) => readMaybe(path.join(d, f)) ?? ''); } catch { return []; }
+}
+
+/** Upstream credits cited by a kit's rules and member sources; an unknown key is skipped, never a 500. */
+function kitCredits(m, rules) {
+  const texts = [rules, ...(m.skills ?? []).flatMap((n) => memberTexts('skills', n)),
+    ...(m.agents ?? []).flatMap((n) => memberTexts('agents', n))];
+  const keys = new Set();
+  for (const t of texts) for (const x of t.matchAll(CREDIT_RE)) keys.add(x[1]);
+  const out = [];
+  for (const key of [...keys].sort()) {
+    let u;
+    try { u = upstreamOf(key); } catch { u = null; }
+    if (!u) continue;
+    out.push({ key, repo: u.repo, author: u.author, license: u.license, commit: u.commit,
+      compareUrl: `https://github.com/${u.repo}/compare/${u.commit}...HEAD` });
+  }
+  return out;
+}
+
 /**
  * EVERY INSTALL'S KITS — the Kits tab. Its own route, like `apiFleet`: it re-reads each carrier
  * and the kit manifests, which the sidebar's `/api/installs` refetch must not pay for.
@@ -247,8 +265,12 @@ export function apiKits() {
   try { known = loadKits(); } catch (e) {
     return { kits: [], installs: [], error: String(e?.message ?? e) };
   }
-  const kits = [...known].map(([name, m]) => ({
-    name, description: m.description ?? '', skills: m.skills ?? [], agents: m.agents ?? [] }));
+  const kits = [...known].map(([name, m]) => {
+    const rules = readMaybe(path.join(SRC, 'kits', name, 'rules.md')) ?? '';
+    return { name, description: m.description ?? '', skills: m.skills ?? [], agents: m.agents ?? [],
+      rules, rulesWordBudget: m.rulesWordBudget ?? null, banned: m.banned ?? [],
+      credits: kitCredits(m, rules) };
+  });
   const installs = [];
   for (const [host, scope, root] of installTargets()) {
     const st = installState(root, host, scope);