mulmoterminal 6.4.0 → 6.6.0

package/README.md

@@ -63,7 +63,9 @@ npx mulmoterminal@latest        # starts on http://localhost:34567 and opens you
 Requires **Node ≥ 22.12**, and by default the [`claude`](https://claude.com/claude-code) CLI —
 on your `PATH` or named by `CLAUDE_BIN`, already logged in. Declare a different default agent
 (`--agent codex`, or `"defaultAgent"` in `~/.mulmoterminal/config.json`) and start-up checks that
-one instead. `npx mulmoterminal@latest init` reports what it can't find.
+one instead. `npx mulmoterminal@latest init` reports what it can't find. On an older Node it stops
+before starting the server, with a banner and the upgrade commands for however that Node was
+installed.
 
 ### Why not tmux + iTerm panes?
 
@@ -277,7 +279,7 @@ Needs **Node ≥ 22.12**, plus these CLIs — on your `PATH`, or named by the ma
 | Optional | any other agent CLI | a cell can run **Codex**, **Antigravity** (`agy`), **Grok**, **Muse**, **GitHub Copilot CLI** or **Cursor CLI** instead of Claude — install only the ones you use, and a missing one simply fails to start that cell. What each can do is [the capability matrix](docs/agent-capability-matrix.md); how to install and pick one is the [agents guide](https://receptron.github.io/mulmoterminal/guide/en/agents.html) | e.g. `npm i -g @openai/codex` |
 | Optional | `ffmpeg` | video rendering from the [mulmo-script panel](#wiki-collections--the-gui-panel) (its plugin ships enabled) | `brew install ffmpeg` · `sudo apt install ffmpeg` · `sudo dnf install ffmpeg` |
 | Optional | `ollama` | [`claude-ollama`](https://receptron.github.io/mulmoterminal/guide/en/claude-ollama.html) — Claude Code against a fully local model | [ollama.com/download](https://ollama.com/download) |
-| Linux only | a file dialog | the **Choose a folder / Insert a file path** buttons, which open an OS dialog on the machine the server runs on. macOS and Windows have one built in; **WSL** uses the Windows one over interop and needs nothing installed. A Linux desktop needs one of these — without any, the buttons say so and you type the path instead (#1447) | `sudo apt install zenity` · `sudo dnf install zenity` · `kdialog`, `qarma` and `yad` also work |
+| Linux only | a file dialog | the launcher's **Choose a folder** button and the path menu's **Insert a file path**, which open an OS dialog on the machine the server runs on. macOS and Windows have one built in; **WSL** uses the Windows one over interop and needs nothing installed. A Linux desktop needs one of these — without any, they say so and you type the path instead (#1447) | `sudo apt install zenity` · `sudo dnf install zenity` · `kdialog`, `qarma` and `yad` also work |
 
 The server starts without any of the non-required rows; you just lose that row's feature,
 and the header/panel for it says so. `git` and `gh` are marked required because losing them
@@ -810,9 +812,9 @@ easier to debug than one that silently vanished. See the
 #### Header buttons
 
 Each terminal header shows configurable **action buttons**. Omitting `buttons` (globally or per-dir)
-keeps the built-in **starter set**: a file-path picker (📎), an OS file-manager reveal (📂), an in-app
-file explorer (📁), a new terminal here (🖥), this branch's PR (🔗, git repos, only when a PR exists),
-and open-on-GitHub (🌐, git repos). Setting `buttons` (at either level) **replaces the whole default
+keeps the built-in **starter set**: this branch's PR (git repos, only when a PR exists). Inserting a
+file path, revealing the folder, the in-app file explorer, a new terminal here and the GitHub links
+are items in the **path menu** (click the directory path on the terminal header). Setting `buttons` (at either level) **replaces the whole default
 set** with your list (it is not merged on top), so listing your own — even a **shorter** one — is how
 you drop, reorder, or swap them.
 A button has an `id`, `label`, and a `run` of `"shell"` (run a command), `"input"` (send text to the
@@ -822,6 +824,8 @@ change takes effect; it costs a resume and asks nothing first). An `open` button
 (in-app explorer) / `view` (a built-in overlay) / `terminal` (a dir → a new cell running `$SHELL`,
 opened next to the current one) / `pr: true` (open the current branch's PR — the button is hidden when
 there's no open PR) / `pickFile: true` (OS file dialog → insert the path).
+An entry with `items` instead of `run` is a **folder**: one icon that opens a menu of the buttons
+inside it (one level only — a folder cannot hold a folder).
 `${dir}`, `${branch}`, `${repo}`, … substitute live context, and `when` (e.g. `"isGitRepo"`) gates
 visibility. The `/mulmoterminal-header` skill writes a valid config interactively; per-dir buttons
 merge over the global ones by `id`, while `chips` replace the global list wholesale.
@@ -988,7 +992,7 @@ Settings → Directory settings names both files and lists which keys the local
 | Field        | Meaning |
 | ------------ | ------- |
 | `name`       | Label shown as a badge in the terminal/cell header. |
-| `icon`       | An **image** marking this directory — shown in the cell header, the cockpit roster, the filmstrip thumbnails, the launcher's directory chips, and the phone's terminal list and terminal screen. Either a path **relative to this directory** (an absolute path, or a `../` that escapes it, is rejected), an `http(s)://` URL, or a `data:image/…` URI. PNG / JPEG / **GIF (animated plays)** / WebP / AVIF / SVG / ICO / BMP. Not to be confused with a header **button's** `icon`, which is a Material Symbols name, or with the small glyph a chat started from a **collection** wears beside its status dot — that one is the collection's own `icon`, and it says which collection the cell was opened for while this one says which directory it runs in. **Omit it and the repository's own favicon is used** (`public/favicon.svg`, `apple-touch-icon.png`, a web manifest — see `autoDirIcon`); `false` means no icon here and stops that search. |
+| `icon`       | An **image** marking this directory — shown in the cell header, the cockpit roster, the filmstrip thumbnails, the launcher's directory chips, and the phone's terminal list and terminal screen. Either a path **relative to this directory** (an absolute path, or a `../` that escapes it, is rejected), an `http(s)://` URL, or a `data:image/…` URI. PNG / JPEG / **GIF (animated plays)** / WebP / AVIF / SVG / ICO / BMP. Not to be confused with a header **button's** `icon`, which is a Material Symbols name (or `github:<name>` for one of GitHub's icons), or with the small glyph a chat started from a **collection** wears beside its status dot — that one is the collection's own `icon`, and it says which collection the cell was opened for while this one says which directory it runs in. **Omit it and the repository's own favicon is used** (`public/favicon.svg`, `apple-touch-icon.png`, a web manifest — see `autoDirIcon`); `false` means no icon here and stops that search. |
 | `backgroundImage` | A **picture shown faintly behind this directory's terminals**, blended with the text so it stays readable on either theme. A string is the image (15% opaque, fills the terminal); `{ "image", "opacity", "fit" }` sets how faint (above 0, at most 1) and whether it crops to fill (`cover`) or shows whole (`contain`). The image follows `icon`'s rules. |
 | `badgeColor` | Badge background color (`#rrggbb`); text auto-contrasts. |
 | `headerColor` | Header **background** color (`#rrggbb`) — the grid cell's header row and the terminal's own header row (grid row 2). While a terminal is working/blocked the status tint still shows; the custom color applies when idle. |
@@ -1422,8 +1426,8 @@ A worktree cell's header carries a **diff badge** (`+<commits> ●<dirty>`); cli
 Closing a worktree cell asks whether to **keep** the worktree or **discard & remove** it
 (a dirty worktree is never removed unless you confirm).
 
-**PRs & Issues (cross-repo).** The toolbar's **Pull requests** button opens a full-screen
-view that aggregates open PRs **and** issues across the repos listed in Settings →
+**PRs & Issues (cross-repo).** The toolbar's **Pull requests** button (shown once at least one
+repository is listed) opens a full-screen view that aggregates open PRs **and** issues across the repos listed in Settings →
 **Pull request repos** (`prRepos`, `owner/repo` entries, or `gitlab.com/group/project` — plus any host declared in `gitlabHosts`) via your server-side `gh` / `glab` login.
 PRs show a CI-rollup / review-decision / draft badge; each repo lists its latest open
 issues. Rows are real links, per-repo errors don't sink the view, and the two lists load
@@ -1504,8 +1508,8 @@ The **Settings** modal (the gear button) shows an **estimated $ cost** — Sessi
 0.1×, cache writes at 1.25× input). It's an estimate: real billing differs, **flat-plan
 (Max) usage isn't reflected**, and turns on unpriced models are flagged and excluded.
 
-A separate, full **double-entry accounting** book (the `account_balance` toolbar button →
-`/accounting`) is provided by the bundled `@mulmoclaude/accounting-plugin` and stores its
+A separate, full **double-entry accounting** book (the `account_balance` button first on the
+Collections screen's top row → `/accounting`) is provided by the bundled `@mulmoclaude/accounting-plugin` and stores its
 books under `<workspace>/data/accounting`. It's a bookkeeping app — unrelated to the LLM
 cost estimate above — and is also exposed to Claude as the `manageAccounting` GUI tool.
 
@@ -1694,7 +1698,8 @@ narrow and tall for one record you are discussing — and each position keeps it
   receives those as input. A cell that **stops for a permission prompt comes back to full strength
   on its own**, so setting one aside can never hide a session that is waiting on you; a merely *finished* turn
   does not, since that is the expected outcome of setting a running agent aside.
-- **Timeline** (🕘) — a read-only per-session activity timeline (tools run, newest first),
+- **History menu** (on the cell header) — the Prompts and Conversation panes below, and the
+  **Timeline**: a read-only per-session activity timeline (tools run, newest first),
   from `GET /api/transcript/timeline`.
 - **Bring another cell's turn here** (💬) — pick another terminal in the grid and its
   **last completed turn** is pasted into *this* cell's input box, so you can have Claude
@@ -1703,7 +1708,7 @@ narrow and tall for one record you are discussing — and each position keeps it
   ANSI debris and nothing lost to scrollback. It is **pasted, never sent** — you read
   what arrived and press Enter, in the cell you were already in. A turn still running
   isn't available yet (Codex writes its rollout only once the turn ends).
-- **Tools pane** — the available GUI tools plus a live tool-call history for the active
+- **Tools pane** (the cell header's **Tools** menu, beside the Canvas, Collections and **Restart the agent**) — the available GUI tools plus a live tool-call history for the active
   session.
 - **Prompts pane** — the prompts *you* sent the enlarged cell's session, newest first, from
   `GET /api/transcript/prompts`. The mirror of the Timeline above: that one is what the agent

package/bin/cli-args.d.ts

@@ -1,3 +1,4 @@
+import type { NodeUpgradeGuide } from "./node-install.js";
 export type PortChoice = { port: number; explicit: boolean } | { error: string };
 export type CwdChoice = { path: string; mustExist: boolean } | { error: string };
 export declare function parsePortArg(args: string[], env: Record<string, string | undefined>, defaultPort: number): PortChoice;
@@ -16,6 +17,7 @@ export declare function saysYes(answer: unknown): boolean;
 export declare const SECOND_INSTANCE_NOTE: string;
 export declare const MIN_NODE_LABEL: string;
 export declare function nodeMeetsMinimum(version: string): boolean;
+export declare function unsupportedNodeMessage(version: string, execPath: string, upgrade: NodeUpgradeGuide): string;
 export declare function serverNodeArgs(serverEntry: string, launchDir: string, port: number, declaredAgent?: string | null): string[];
 export declare function serverSpawnEnv(env: Record<string, string | undefined>, cwd: string): Record<string, string | undefined>;
 export interface RunningInstance {

package/bin/cli-args.js

@@ -11,6 +11,7 @@
 // environment or the filesystem.
 import { isIP } from "node:net";
 import { join } from "node:path";
+import { NODE_DOWNLOAD_URL } from "./node-install.js";
 
 // The v4 loopback every local client of this server dials by literal — `guiMcpUrlTemplate` in
 // server/infra/gui-mcp-registration.ts builds `http://127.0.0.1:<port>/api/mcp/...`. Duplicated
@@ -390,24 +391,61 @@ const MIN_NODE_MAJOR = 22;
 const MIN_NODE_MINOR = 12;
 
 /**
- * The lowest Node the `init` check reports as good, for the "needs ≥ x.y" line.
+ * The lowest Node MulmoTerminal runs on, for the "needs ≥ x.y" line.
  */
 export const MIN_NODE_LABEL = `${MIN_NODE_MAJOR}.${MIN_NODE_MINOR}`;
 
 /**
- * Whether the running Node is new enough for the `init` pre-flight tick.
+ * Whether the running Node is new enough — the `init` tick, and the gate on a normal launch.
  *
  * `process.versions.node` is "major.minor.patch", with a "-prerelease" tag on the patch for
  * nightlies ("22.12.0-nightly…"). Only major.minor gate, and Number.parseInt stops at the
  * first non-digit, so that tag never reaches the comparison. A string that is not a version
  * parses to NaN, and every comparison against NaN is false, so an unreadable version reads as
- * "below minimum" — the safe direction for a display-only check.
+ * "below minimum". Node's own `process.versions.node` is always readable, so that only ever
+ * decides a malformed string passed in a test.
  */
 export function nodeMeetsMinimum(version) {
   const [major, minor] = version.split(".").map((part) => Number.parseInt(part, 10));
   return major > MIN_NODE_MAJOR || (major === MIN_NODE_MAJOR && minor >= MIN_NODE_MINOR);
 }
 
+const NODE_TOO_OLD_ART = [
+  "  ##      ##    ######    ########    ##########",
+  "  ####    ##  ##      ##  ##      ##  ##",
+  "  ##  ##  ##  ##      ##  ##      ##  ########",
+  "  ##    ####  ##      ##  ##      ##  ##",
+  "  ##      ##    ######    ########    ##########",
+  "",
+  "  ##########    ######      ######            ######    ##          ########",
+  "      ##      ##      ##  ##      ##        ##      ##  ##          ##      ##",
+  "      ##      ##      ##  ##      ##        ##      ##  ##          ##      ##",
+  "      ##      ##      ##  ##      ##        ##      ##  ##          ##      ##",
+  "      ##        ######      ######            ######    ##########  ########",
+];
+
+/**
+ * What a normal launch prints before stopping on a Node below the minimum.
+ *
+ * Without it the first thing to fail is the server spawn itself — Node 20 rejects
+ * `--env-file-if-exists` with "bad option", which reads as a `.env` problem rather than an old
+ * Node (#2351). The banner is large so it is not mistaken for one more line of startup output.
+ * `upgrade` is `nodeUpgradeGuide`'s answer for this Node.
+ */
+export function unsupportedNodeMessage(version, execPath, upgrade) {
+  const lines = ["", ...NODE_TOO_OLD_ART, "", `  Node ${version} is not supported. MulmoTerminal needs Node ≥ ${MIN_NODE_LABEL}.`, `  Running: ${execPath}`];
+  if (upgrade.via) lines.push(`  Installed with: ${upgrade.via}`);
+  lines.push("");
+  if (upgrade.commands.length > 0) {
+    lines.push("  To upgrade, run:", "", ...upgrade.commands.map((command) => `    ${command}`), "");
+    lines.push(`  Node LTS downloads: ${NODE_DOWNLOAD_URL}`);
+  } else {
+    lines.push(`  To upgrade, install the LTS from ${NODE_DOWNLOAD_URL}`);
+  }
+  lines.push("  Then open a new terminal and run the same command again.", "");
+  return lines.join("\n");
+}
+
 /**
  * The node arguments the launcher spawns the server with.
  *

package/bin/mulmoterminal.js

@@ -31,6 +31,7 @@ import {
   stopCommandFor,
   SECOND_INSTANCE_NOTE,
   nodeMeetsMinimum,
+  unsupportedNodeMessage,
   MIN_NODE_LABEL,
   serverNodeArgs,
   serverSpawnEnv,
@@ -41,6 +42,7 @@ import { liveInstances, servingInstances } from "./instances.js";
 import { agentBin, AGENT_BIN_SPEC } from "./agent-bins.js";
 import { configuredDefaultAgent, gateFor, isKnownAgent, missingAgentMessage, parseAgentArg, resolveDeclaredAgent } from "./default-agent.js";
 import { setProcessTitle } from "./process-title.js";
+import { nodeUpgradeGuide } from "./node-install.js";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const PKG_DIR = join(__dirname, "..");
@@ -740,6 +742,14 @@ async function main() {
     return;
   }
 
+  // Before anything that spawns: on an old Node the server dies on its own node flags, and what
+  // it prints says nothing about the version.
+  if (!nodeMeetsMinimum(process.versions.node)) {
+    const upgrade = nodeUpgradeGuide(process.execPath, process.platform, process.env);
+    console.error(unsupportedNodeMessage(process.versions.node, process.execPath, upgrade));
+    process.exit(1);
+  }
+
   checkForUpdate();
 
   const declaredAgent = passStartupGate(args);

package/bin/node-install.d.ts

@@ -0,0 +1,6 @@
+export interface NodeUpgradeGuide {
+  via: string | null;
+  commands: string[];
+}
+export declare const NODE_DOWNLOAD_URL: string;
+export declare function nodeUpgradeGuide(execPath: string, platform: string, env: Record<string, string | undefined>): NodeUpgradeGuide;

package/bin/node-install.js

@@ -0,0 +1,81 @@
+// How to upgrade THIS Node, worked out from where it is installed (#2351).
+//
+// "Install the LTS from nodejs.org" is wrong advice for most people who hit the version gate: a
+// Node that came from a version manager is shadowed by it, so a fresh installer leaves `node` on
+// PATH exactly as old as before. The binary's own path says which tool put it there.
+//
+// Every command below was checked against that tool's own help or README. A tool whose upgrade
+// command could not be confirmed gets no command — its readers still get the download link.
+
+export const NODE_DOWNLOAD_URL = "https://nodejs.org/en/download";
+
+// fnm's `default` takes a version, and it has no documented name for "the latest LTS".
+// Any major at or above the minimum works; this one was the Active LTS when written.
+const SUGGESTED_NODE_MAJOR = 24;
+
+const toMatchable = (execPath) => execPath.replaceAll("\\", "/").toLowerCase();
+
+const withoutTrailingSlashes = (path) => (path.endsWith("/") ? withoutTrailingSlashes(path.slice(0, -1)) : path);
+
+// Boundary-aware, so `C:\Program Files\nodejs-old` is not inside `C:\Program Files\nodejs`.
+function isInsideDir(path, dir) {
+  if (typeof dir !== "string") return false;
+  const prefix = withoutTrailingSlashes(toMatchable(dir));
+  return prefix !== "" && path.startsWith(`${prefix}/`);
+}
+
+// The app id is read off a path and printed as a command to paste, so anything beyond a plain
+// manifest name gets no command rather than a second one smuggled in by `&` or a space.
+const isPlainScoopAppId = (id) => /^[a-z0-9][a-z0-9._-]*$/.test(id);
+
+const guide = (via, commands) => ({ via, commands });
+
+function versionManagerGuide(path) {
+  if (path.includes("/.nodebrew/")) return guide("nodebrew", ["nodebrew install stable", "nodebrew use stable"]);
+  if (path.includes("/.nvm/versions/node/")) return guide("nvm", ["nvm install --lts", "nvm alias default 'lts/*'"]);
+  if (path.includes("volta/tools/image/node/")) return guide("Volta", ["volta install node"]);
+  if (path.includes("/fnm/") || path.includes("/fnm_multishells/")) {
+    return guide("fnm", [`fnm install ${SUGGESTED_NODE_MAJOR}`, `fnm default ${SUGGESTED_NODE_MAJOR}`]);
+  }
+  if (path.includes("/mise/installs/node/")) return guide("mise", ["mise use -g node@lts"]);
+  if (path.includes("/.asdf/installs/nodejs/")) return guide("asdf", ["asdf install nodejs latest", "asdf set -u nodejs $(asdf latest nodejs)"]);
+  return null;
+}
+
+function packageManagerGuide(path) {
+  const scoopApp = /\/scoop\/apps\/([^/]+)\//.exec(path)?.[1];
+  if (scoopApp) return guide("Scoop", isPlainScoopAppId(scoopApp) ? [`scoop update ${scoopApp}`] : []);
+  // Homebrew resolves `node` to its keg, so the formula is in the path: `node`, or a pinned `node@20`.
+  const formula = /\/cellar\/(node|node@\d+)\//.exec(path)?.[1];
+  if (formula === "node") return guide("Homebrew", ["brew upgrade node"]);
+  if (formula) return guide(`Homebrew (${formula})`, [`brew unlink ${formula}`, "brew install node"]);
+  return null;
+}
+
+// nvm-windows points one fixed symlink (NVM_SYMLINK, by default C:\Program Files\nodejs — the
+// installer's own directory) at the active version, so only its environment tells the two apart.
+function nvmWindowsGuide(path, env) {
+  if (!isInsideDir(path, env.NVM_SYMLINK) && !isInsideDir(path, env.NVM_HOME)) return null;
+  return guide("nvm-windows", ["nvm install lts", "nvm use lts"]);
+}
+
+// The .msi installs to `Program Files\nodejs` (or its x86 twin) on whichever drive Windows is on.
+const isWindowsInstallerPath = (path) => /\/program files( \(x86\))?\/nodejs\/node\.exe$/.test(path);
+
+function installerGuide(path, platform) {
+  if (platform === "win32" && isWindowsInstallerPath(path)) return guide("the Windows installer", []);
+  if (platform === "darwin" && path === "/usr/local/bin/node") return guide("the macOS installer from nodejs.org", []);
+  if (platform === "linux" && path === "/usr/bin/node") return guide("your system's package manager", []);
+  return guide(null, []);
+}
+
+/**
+ * How the running Node was installed, and the commands that upgrade it there.
+ *
+ * `via` is null when the path matches nothing known; `commands` is empty when the only honest
+ * advice is the download page.
+ */
+export function nodeUpgradeGuide(execPath, platform, env) {
+  const path = toMatchable(execPath);
+  return (platform === "win32" ? nvmWindowsGuide(path, env) : null) ?? versionManagerGuide(path) ?? packageManagerGuide(path) ?? installerGuide(path, platform);
+}

package/blueprints/ask/checks/base.mjs

@@ -0,0 +1,12 @@
+// The docs base holds the helpers every usecase on it shares (running chaff, reading Markdown sections).
+// A usecase loads them from BLUEPRINT_BASE, which the executor sets for every check.
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+
+if (!process.env.BLUEPRINT_BASE) {
+  console.error("BLUEPRINT_BASE is not set: run this check through the blueprint executor");
+  process.exit(1);
+}
+
+/** The URL of a module in the docs base's checks/, for `await import(...)`. */
+export const fromBase = (file) => pathToFileURL(join(process.env.BLUEPRINT_BASE, "checks", file)).href;

package/blueprints/ask/checks/replies.mjs

@@ -0,0 +1,99 @@
+// Reads .blueprint/replies.json — an answer to each question the person asked — and answers one question
+// per mode. Exit 0 is yes.
+//   answer  every question has exactly one reply; a reply found in the documents quotes them (chaff cite)
+//           and names every address it quotes; a reply not found says what was searched. Records the
+//           documents' and FAQ.md's fingerprints.
+//   keep    the documents are unchanged; FAQ.md holds every question after what it held before when the
+//           person asked to keep the answers, and is untouched otherwise
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { fromBase } from "./base.mjs";
+const { fail, quotationProblems, readJson } = await import(fromBase("chaff.mjs"));
+const { digest, documentSource, documentsNamed, fingerprint } = await import(fromBase("documents.mjs"));
+
+const REPLIES = ".blueprint/replies.json";
+const REPLIES_PAGE = ".blueprint/replies.md";
+const RECORDED = ".blueprint/.replies-before.json";
+const FAQ = "FAQ.md";
+const KEEP = "このフォルダの FAQ.md に書き足す";
+
+const answers = readJson(".blueprint/answers.json", "the interview answers");
+const documents = documentsNamed(answers?.documents);
+const questions = String(answers?.questions ?? "")
+  .split("\n")
+  .map((line) => line.trim())
+  .filter((line) => line !== "");
+if (questions.length === 0) fail("the interview asks no question");
+if (new Set(questions).size !== questions.length) fail("the interview asks the same question twice");
+if (answers?.keep === KEEP && documents.includes(FAQ)) fail(`${FAQ} is one of the documents, so the answers cannot be added to it`);
+
+const indented = (line) => "  " + line;
+const nonEmpty = (value) => typeof value === "string" && value.trim() !== "";
+
+const replyProblem = (reply) => {
+  if (typeof reply !== "object" || reply === null) return "a reply is not an object";
+  if (!nonEmpty(reply.question)) return "a reply names no question";
+  const which = JSON.stringify(reply.question);
+  if (typeof reply.found !== "boolean") return `${which}: "found" must be true or false`;
+  if (!nonEmpty(reply.answer)) return `${which}: no answer`;
+  const citations = reply.citations ?? [];
+  if (!Array.isArray(citations)) return `${which}: citations must be an array`;
+  if (reply.found && citations.length === 0) return `${which}: an answer found in the documents quotes them`;
+  if (!citations.every((citation) => nonEmpty(citation?.address))) return `${which}: every quotation needs an "address"`;
+  const unnamed = citations.filter((citation) => !reply.answer.includes(citation.address.trim()));
+  if (unnamed.length > 0) return `${which}: the answer does not name ${unnamed.map((citation) => citation.address).join(", ")}, which it quotes`;
+  if (!reply.found && (!Array.isArray(reply.searched) || !reply.searched.some(nonEmpty))) return `${which}: say what was searched ("searched")`;
+  return null;
+};
+
+const readReplies = () => {
+  const record = readJson(REPLIES, '{ "replies": [{ "question", "found", "answer", "citations", "searched" }] }');
+  const replies = Array.isArray(record?.replies) ? record.replies : fail(`${REPLIES} needs a "replies" array`);
+  const problem = replies.map(replyProblem).find((found) => found !== null);
+  if (problem) fail(`${REPLIES}: ${problem}`);
+  const asked = replies.map((reply) => reply.question.trim());
+  const unanswered = questions.filter((question) => !asked.includes(question));
+  if (unanswered.length > 0) fail(`no reply to:\n${unanswered.map(indented).join("\n")}`);
+  const extra = asked.filter((question) => !questions.includes(question));
+  if (extra.length > 0) fail(`replies to questions nobody asked:\n${extra.map(indented).join("\n")}`);
+  if (new Set(asked).size !== asked.length) fail(`${REPLIES}: a question is answered twice`);
+  return replies;
+};
+
+const faqState = () => (existsSync(FAQ) ? { bytes: readFileSync(FAQ).length, hash: fingerprint(FAQ) } : null);
+
+const mode = process.argv[2];
+
+if (mode === "answer") {
+  const replies = readReplies();
+  const quoted = replies.flatMap((reply) => quotationProblems(JSON.stringify(reply.question), reply.citations ?? [], documentSource(documents)));
+  if (quoted.length > 0) fail(quoted.join("\n"));
+  if (!existsSync(REPLIES_PAGE)) fail(`${REPLIES_PAGE} is missing: the replies for the person to read`);
+  const page = readFileSync(REPLIES_PAGE, "utf8");
+  const absent = questions.filter((question) => !page.includes(question));
+  if (absent.length > 0) fail(`${REPLIES_PAGE} does not show: ${absent.join(" / ")}`);
+  writeFileSync(RECORDED, JSON.stringify({ documents: Object.fromEntries(documents.map((file) => [file, fingerprint(file)])), faq: faqState() }));
+  console.log(`${replies.length} repl(ies): ${replies.filter((reply) => reply.found).length} found in the documents`);
+} else if (mode === "keep") {
+  const recorded = readJson(RECORDED, "what the answer step recorded");
+  const readThen = recorded?.documents;
+  if (typeof readThen !== "object" || readThen === null || Array.isArray(readThen))
+    fail(`${RECORDED} is not what the answer step records: run the answer check again`);
+  if (JSON.stringify(Object.keys(readThen).sort()) !== JSON.stringify([...documents].sort()))
+    fail(`the documents named now are not the ones that were read (${Object.keys(readThen).join(", ")}): run the answer check again`);
+  const changed = documents.filter((file) => readThen[file] !== fingerprint(file));
+  if (changed.length > 0) fail(`changed since they were read — the documents must stay as they are: ${changed.join(", ")}`);
+  const before = recorded.faq ?? null;
+  if (answers?.keep === KEEP) {
+    if (!existsSync(FAQ)) fail(`${FAQ} is missing`);
+    const now = readFileSync(FAQ);
+    if (before !== null && digest(now.subarray(0, before.bytes)) !== before.hash) fail(`${FAQ}: what it held before must stay as it was; add after it`);
+    const text = now.toString("utf8");
+    const absent = questions.filter((question) => !text.includes(question));
+    if (absent.length > 0) fail(`${FAQ} does not hold: ${absent.join(" / ")}`);
+  } else if (JSON.stringify(faqState()) !== JSON.stringify(before)) {
+    fail(`${FAQ} changed, but the person chose not to keep the answers`);
+  }
+  console.log("the documents are untouched");
+} else {
+  fail(`usage: replies.mjs answer | keep (got ${JSON.stringify(mode)})`);
+}

package/blueprints/ask/hearing.json

@@ -0,0 +1,23 @@
+{
+  "questions": [
+    {
+      "id": "documents",
+      "label": "質問する相手の文書（このフォルダの中のファイルを 1 行に 1 つ）",
+      "why": "答えはこの文書だけから出し、どこに書いてあるかを示す",
+      "kind": "text"
+    },
+    {
+      "id": "questions",
+      "label": "質問（1 行に 1 つ）",
+      "why": "質問ごとに一つ答える",
+      "kind": "text"
+    },
+    {
+      "id": "keep",
+      "label": "答えを残しますか",
+      "why": "読んで確かめた答えを、このフォルダの FAQ.md に書き足すかどうか",
+      "kind": "select",
+      "options": ["このフォルダの FAQ.md に書き足す", "残さない（.blueprint の中だけ）"]
+    }
+  ]
+}

package/blueprints/ask/manifest.json

@@ -0,0 +1,9 @@
+{
+  "slug": "ask",
+  "kind": "usecase",
+  "title": "文書に尋ねる（どこに書いてあるかを添えて）",
+  "version": "0.1.0",
+  "description": "込み入ったマニュアル・規程・契約書に質問すると、文書のどこに書いてあるかを原文の引用で示して答える。書いていないことは「書いていない」と答える。引用は chaff cite で原文にあることを確かめる。答えは、人が読んでから FAQ.md に残せる。",
+  "bases": ["docs"],
+  "report": ".blueprint/replies.md"
+}

package/blueprints/ask/presets/keihi/keihi.md

@@ -0,0 +1,19 @@
+# 経費精算の手引き
+
+## 対象になるもの
+
+仕事のために使った交通費、宿泊費、会議の飲食代が対象です。私用の買い物や、会社のカードで払ったものは対象になりません。
+
+## 申請のしかた
+
+1. 領収書を写真に撮り、経費精算システムに登録します。
+2. 使った日から30日以内に申請します。30日を過ぎたものは、上長の承認があるときだけ受け付けます。
+3. 上長が承認すると、経理部が確かめます。
+
+## 支払い
+
+経理部の確認が済んだ申請は、毎月25日にまとめて給与口座へ振り込みます。25日が土日祝日のときは、その前の営業日に振り込みます。
+
+## 領収書が無いとき
+
+交通系ICカードの利用履歴を印刷したものは、領収書の代わりになります。それ以外で領収書が無いときは、「支払証明書」に理由を書いて上長の承認を受けてください。

package/blueprints/ask/presets.json

@@ -0,0 +1,15 @@
+{
+  "presets": [
+    {
+      "id": "keihi",
+      "title": "経費精算の手引きに尋ねる",
+      "description": "見本の手引き（keihi.md）に 3 つの質問をすると、どこに書いてあるかを原文の引用で示して答える。書いていないこと（海外出張の日当）には「書いていない」と答える。",
+      "base": "docs",
+      "answers": {
+        "documents": "keihi.md",
+        "questions": "申請の期限はいつまで？\n領収書をなくしたときはどうする？\n海外出張の日当はいくら？",
+        "keep": "このフォルダの FAQ.md に書き足す"
+      }
+    }
+  ]
+}

package/blueprints/ask/skills/answer/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: blueprint-ask-answer
+description: "Answer each question from the named documents only, quoting where the answer is written, or saying plainly that the documents do not say — changing nothing yet."
+---
+
+# Answer from the documents
+
+`.blueprint/answers.json` names the documents (`documents`, one path per line), the questions
+(`questions`, one per line) and whether to keep the answers (`keep`). The person may not know the
+documents well: answer in their language and in plain words.
+
+Change nothing in the repository: this step only reads. Write only under `.blueprint/`; the person reads
+the answers before anything is kept.
+
+## How to answer
+
+- **Only from the documents.** Not from general knowledge, not from what such documents usually say. If the
+  documents do not answer a question, the answer is that they do not — and what they do say nearby, if it
+  helps.
+- **Find where it is written.** `chaff tree <document>` (through the base pack's wrapper,
+  `sh <base pack>/checks/chaff.sh tree <document>`) shows the document's addresses — articles, sections,
+  items — so an answer can say "第4条第2項" or "Section 3.1". Read the whole relevant part, including
+  exceptions and definitions elsewhere that change its meaning.
+- **When provisions disagree**, say so and quote both rather than choosing one.
+
+## Write `.blueprint/replies.json`
+
+```json
+{
+  "replies": [
+    {
+      "question": "委託料はいつまでに払う？",
+      "found": true,
+      "answer": "検収後30日以内です（第4条第2項）。",
+      "citations": [{ "source": "contract.txt", "address": "第4条第2項", "quote": "成果物の検収後30日以内に" }]
+    },
+    {
+      "question": "消費税は含まれる？",
+      "found": false,
+      "answer": "文書には書かれていません。第4条第1項は「金50万円」とだけ定めています。",
+      "citations": [{ "source": "contract.txt", "address": "第4条第1項", "quote": "委託料として金50万円を支払う" }],
+      "searched": ["消費税", "税", "税込", "税別"]
+    }
+  ]
+}
+```
+
+- `question`: the question exactly as it is in `questions`. One reply per question, none extra.
+- `found`: `true` when the documents answer it. Then at least one citation.
+- `citations`: `source` is the document's path as `documents` names it; `address` is where; `quote` is
+  copied character for character — the check runs `chaff cite` on every one. **Write every cited address in
+  the `answer` text** so the person can open the document there.
+- `searched`: when `found` is `false`, the words and places you looked for.
+
+Also write `.blueprint/replies.md` for the person: each question as a heading, the answer, and the quotations.
+
+## Done when
+
+`node <usecase pack>/checks/replies.mjs answer` (with `BLUEPRINT_BASE` and `BLUEPRINT_USECASE` set to the
+pack folders from your prompt) passes. It also records a fingerprint of the documents and of `FAQ.md`.

package/blueprints/ask/skills/keep/SKILL.md

@@ -0,0 +1,25 @@
+---
+name: blueprint-ask-keep
+description: "Add the approved answers to FAQ.md when the person chose to keep them, after what it already holds; change nothing otherwise."
+---
+
+# Keep the answers
+
+The person has read the answers and approved them. Read `.blueprint/answers.json` and
+`.blueprint/replies.json`.
+
+**Never change a document.** The check compares each one with the fingerprint recorded when the answers were
+written.
+
+If `keep` is `残さない（.blueprint の中だけ）`, there is nothing to write: leave `FAQ.md` exactly as it is,
+run the check and stop.
+
+Otherwise add to `FAQ.md` in this folder (create it if there is none). **Add after what it already holds;
+never edit or reorder what is there** — the check compares the beginning of the file with what it held
+before. For each question: the question as a `##` heading, word for word; the answer; and where it is
+written (document and address). For a question the documents do not answer, say so — that is worth keeping
+too.
+
+## Done when
+
+`node <usecase pack>/checks/replies.mjs keep` passes.

package/blueprints/ask/steps.json

@@ -0,0 +1,19 @@
+{
+  "steps": [
+    {
+      "id": "answer",
+      "title": "文書から答える",
+      "description": "質問ごとに、文書のどこに書いてあるかを引用で示して答える。書いていなければ、そう答えて何を探したかを残す。",
+      "skill": "skills/answer",
+      "check": "node \"$BLUEPRINT_USECASE/checks/replies.mjs\" answer"
+    },
+    {
+      "id": "keep",
+      "title": "答えを残す",
+      "description": "残すと決めたなら、確かめた答えを FAQ.md に書き足す。",
+      "skill": "skills/keep",
+      "check": "node \"$BLUEPRINT_USECASE/checks/replies.mjs\" keep",
+      "gates": ["review"]
+    }
+  ]
+}