mulmoterminal 6.7.0 → 7.0.0

package/README.md

@@ -303,7 +303,8 @@ with `tmux` installed the agent sessions survive and come back under **Settings
 survived a restart**; without it they end with the server.
 
 **First-run setup (optional).** `npx mulmoterminal@latest init` checks your environment (Node ≥ 22.12
-and every CLI in the table above), seeds the launcher's **directory
+and every CLI in the table above), says how to update when Node is behind the latest LTS of its line
+or Claude Code is behind its `stable` release, seeds the launcher's **directory
 presets** from the projects in your Claude Code history, and writes `~/.mulmoterminal/config.json`.
 It's **idempotent** — re-run it any time to refresh the presets; it overwrites the managed parts
 and keeps your other settings. When `claude` is installed it can hand off to the
@@ -766,7 +767,7 @@ The Settings modal (the gear button) persists per-user UI choices to `~/.mulmote
 
 ![The Settings modal — a sidebar of grouped sections beside the one being edited](https://raw.githubusercontent.com/receptron/mulmoterminal/main/docs/guide/images/settings-tabs.png)
 
-*Open it from the gear button in the toolbar. The **sidebar** groups the sections — Appearance, Projects, Header & launch, Input, Models & servers, Notifications, Integrations, Sessions, Help — and one is on screen at a time; on a phone the sidebar becomes a picker above the section. Settings is available in **English and Japanese**: it follows your browser's language unless you pick one under **Language** (per browser, like the theme). Only this modal is translated so far. Under the title, a **Version** row shows what is running: the version from the shipped `package.json`, plus a `commit <sha>` chip on a git checkout — there the version is only whatever was last released, so the commit is what identifies the build. When something newer exists, the row is followed by the header badge's update notice, command included. Pick a **theme**, set the **terminal font size**, **font** and **scroll speed** (and whether sending **returns to the latest output**), set a custom **attention sound**, list the repos the cross-repo **PRs & Issues** view should aggregate, add **launch commands** for grid cells, register your own **MCP servers**, and turn on the switches for what this app writes on your behalf — **issue work comments**, the **PR clone footer**, the **closing summary**, the **decision digest**, the **dev worklog** — no need to hand-edit the config file. Four settings stay with their skill because a form would be the wrong tool for them (`keymap`, `themes`, `providers`, `buttons`/`chips`); Settings shows what each is doing now and launches that skill. Note that **theme, font size, scroll speed and the return-to-latest switch are stored per browser** (they're display preferences, so a phone and a desktop keep their own); the rest live in `~/.mulmoterminal/config.json` and are shared by every client.*
+*Open it from the gear button in the toolbar. The **sidebar** groups the sections — Appearance, Projects, Header & launch, Input, Models & servers, Notifications, Integrations, Sessions, Help — and one is on screen at a time; on a phone the sidebar becomes a picker above the section. The interface is available in **English, 日本語, 简体中文, 繁體中文 and 한국어**: it follows your browser's language unless you pick one under **Language** (per browser, like the theme). Translated so far: this modal, the grid's status words, and every button's hover tip and screen-reader label; the rest of the app's words are still English. Under the title, a **Version** row shows what is running: the version from the shipped `package.json`, plus a `commit <sha>` chip on a git checkout — there the version is only whatever was last released, so the commit is what identifies the build. When something newer exists, the row is followed by the header badge's update notice, command included. Pick a **theme**, set the **terminal font size**, **font** and **scroll speed** (and whether sending **returns to the latest output**), set a custom **attention sound**, list the repos the cross-repo **PRs & Issues** view should aggregate, add **launch commands** for grid cells, register your own **MCP servers**, and turn on the switches for what this app writes on your behalf — **issue work comments**, the **PR clone footer**, the **closing summary**, the **decision digest**, the **dev worklog** — no need to hand-edit the config file. Four settings stay with their skill because a form would be the wrong tool for them (`keymap`, `themes`, `providers`, `buttons`/`chips`); Settings shows what each is doing now and launches that skill. Note that **theme, font size, scroll speed and the return-to-latest switch are stored per browser** (they're display preferences, so a phone and a desktop keep their own); the rest live in `~/.mulmoterminal/config.json` and are shared by every client.*
 
 | Field        | Meaning |
 | ------------ | ------- |
@@ -1287,6 +1288,41 @@ server says when it arrives — including any directory you expanded while waiti
 pane has not read before says so (`Loading…`) rather than claiming to be empty, and a read that
 fails shows the error rather than a tree it can no longer vouch for.
 
+**Several files open as tabs, when you ask for them.** A plain click in the tree replaces the file
+in front, as it always has — so someone who never wants a tab never sees one. **Cmd+click** (Ctrl+click
+off macOS) or the row menu's **Open in a new tab** adds a tab, and a strip of tabs appears under the
+header once there are two. Opening a file that already has a tab goes to that tab, from the tree, the
+finder, the search or a clicked terminal path alike. Switching tabs saves the one you leave, exactly as
+opening another file does, so only the front tab can hold unsaved edits; each tab keeps its own place
+(Preview or editor, caret, scroll) and the whole strip is remembered with the rest of the pane. Close a
+tab with its **×**, a middle click, or **Delete** while it has focus; ←/→, Home and End move between them.
+The tree follows the tab in front, as VS Code's explorer does: its folders open and its row comes into
+view (a reload still puts the tree back where you left it).
+
+**The tree shows what git sees.** In a git repository a changed file is tinted and lettered as in VS
+Code's explorer — `M` modified, `A` added, `U` untracked, `R` renamed — and a folder holding changes
+carries a dot, so a collapsed tree still says where the agent has been. It is read when the tree
+loads or reloads, after a save or an outside change to the open file, and every thirty seconds.
+
+**The editor marks what changed since the last commit.** A bar beside each line that is new (green)
+or changed (amber), and a notch where lines were removed, as VS Code's gutter shows them — kept up
+to date as you type. **Changes** in the header also shows the removed lines in place, as a unified
+diff. Nothing is marked for a file outside git or one not yet committed.
+
+**HTML pages and images show in the pane too.** An `.html` file has a **Preview** like a Markdown
+file: the page itself, sandboxed as presentHtml pages are — its scripts run on an opaque origin with
+no fetch/XHR; images and the curated CDN list still load, and so does an image it links beside it,
+while a relative stylesheet or script does not. An `.svg` previews as the picture it draws, and a PNG, JPEG, GIF or WebP opens as the image
+rather than as "not text". A path to any of these clicked in terminal output opens in the pane when
+it is up, so a chart an agent just wrote stays in the grid. They are served only under the workspace
+or a terminal's directory, like every other file the app hands to the browser.
+
+**A link in the Preview opens in the pane.** A link to another file (`./b.md`, `../README.md`) is
+resolved against the document it is in and opens in a new tab — in Preview when it is Markdown — or
+goes to the tab that file already has. A link that climbs above the pane's folder is not opened and
+the pane says so; an external link opens in a new browser tab, and a `#heading` link scrolls the
+document.
+
 The toggle is not the only way in: while a cell is enlarged, **clicking a file path the agent
 printed** opens it here too, rather than in a new tab or full-screen — see
 [Clicking a file path](#clicking-a-file-path).

package/bin/check-versions.d.ts

@@ -0,0 +1,7 @@
+export declare const NODE_RELEASES_URL: string;
+export declare const CLAUDE_DIST_TAGS_URL: string;
+export declare function fetchNodeReleases(): Promise<unknown>;
+export declare function fetchClaudeStable(): Promise<string | null>;
+export declare function resolveCommandPath(cmd: string, env?: Record<string, string | undefined>, platform?: string): string | null;
+export declare function readClaudeVersion(binaryPath: string, timeout_ms?: number): Promise<string | null>;
+export declare function checkVersions(options: { claudeBin: string | null }): Promise<{ node: string[]; claude: string[] }>;

package/bin/check-versions.js

@@ -0,0 +1,80 @@
+// The network and process half of `init`'s version check (#2477); the decisions are in
+// bin/version-drift.js. Every probe resolves null on failure — `init` must finish offline.
+import { execFile } from "node:child_process";
+import { realpathSync } from "node:fs";
+import path from "node:path";
+import { extensionsFor, namesAPath, realProbe, searchDirectories } from "./has-command.js";
+import { nodeUpgradeGuide } from "./node-install.js";
+import { claudeDrift, claudeDriftLines, claudeUpdateCommands, nodeDrift, nodeDriftLines, parseClaudeVersion } from "./version-drift.js";
+
+export const NODE_RELEASES_URL = "https://nodejs.org/dist/index.json";
+const REGISTRY = (process.env.npm_config_registry || "https://registry.npmjs.org").replace(/\/$/, "");
+export const CLAUDE_DIST_TAGS_URL = `${REGISTRY}/-/package/@anthropic-ai/claude-code/dist-tags`;
+
+const FETCH_TIMEOUT_MS = 4000;
+// `claude --version` starts the whole CLI, which is slower than a fetch on a cold disk.
+const CLAUDE_VERSION_TIMEOUT_MS = 8000;
+
+async function fetchJson(url) {
+  try {
+    const response = await fetch(url, { signal: AbortSignal.timeout(FETCH_TIMEOUT_MS), headers: { accept: "application/json" } });
+    return response.ok ? await response.json() : null;
+  } catch {
+    return null;
+  }
+}
+
+export const fetchNodeReleases = () => fetchJson(NODE_RELEASES_URL);
+
+export async function fetchClaudeStable() {
+  const distTags = await fetchJson(CLAUDE_DIST_TAGS_URL);
+  return typeof distTags?.stable === "string" ? distTags.stable : null;
+}
+
+/**
+ * Where `cmd` lives, symlinks followed, or null — searched with the start-up gate's own PATH rules
+ * (bin/has-command.js). Only picks the update command, never gates.
+ */
+export function resolveCommandPath(cmd, env = process.env, platform = process.platform) {
+  const join = platform === "win32" ? path.win32.join : path.posix.join;
+  const candidates = namesAPath(cmd) ? [cmd] : searchDirectories(platform, env).flatMap((dir) => extensionsFor(platform).map((ext) => join(dir, cmd + ext)));
+  const found = candidates.find((candidate) => realProbe.isFile(candidate) && (platform === "win32" || realProbe.isExecutable(candidate)));
+  if (found === undefined) return null;
+  try {
+    return realpathSync(found);
+  } catch {
+    return found;
+  }
+}
+
+// Own timer rather than execFile's `timeout`: that one only signals the child and then waits for it
+// to exit, so a `claude` that ignores SIGTERM (or a grandchild holding stdout) would hold `init`.
+export function readClaudeVersion(binaryPath, timeout_ms = CLAUDE_VERSION_TIMEOUT_MS) {
+  return new Promise((resolve) => {
+    const child = execFile(binaryPath, ["--version"], (error, stdout) => {
+      clearTimeout(timer);
+      resolve(error ? null : parseClaudeVersion(stdout));
+    });
+    const timer = setTimeout(() => {
+      child.kill("SIGKILL");
+      resolve(null);
+    }, timeout_ms);
+  });
+}
+
+async function claudeLines(claudeBin) {
+  const binaryPath = resolveCommandPath(claudeBin);
+  const [localVersion, stable] = await Promise.all([binaryPath ? readClaudeVersion(binaryPath) : null, fetchClaudeStable()]);
+  return claudeDriftLines(claudeDrift(localVersion, stable), localVersion, claudeUpdateCommands(binaryPath));
+}
+
+async function nodeLines() {
+  const releases = await fetchNodeReleases();
+  return nodeDriftLines(nodeDrift(process.versions.node, releases), nodeUpgradeGuide(process.execPath, process.platform, process.env));
+}
+
+/** The hint lines `init` prints under its Node and Claude Code checks. */
+export async function checkVersions({ claudeBin }) {
+  const [node, claude] = await Promise.all([nodeLines(), claudeBin ? claudeLines(claudeBin) : []]);
+  return { node, claude };
+}

package/bin/has-command.d.ts

@@ -3,6 +3,10 @@ export interface CommandProbe {
   isExecutable: (candidate: string) => boolean;
 }
 
+export declare const realProbe: CommandProbe;
+export declare const namesAPath: (cmd: string) => boolean;
+export declare const extensionsFor: (platform: string) => string[];
+export declare const searchDirectories: (platform: string, env: Record<string, string | undefined>) => string[];
 export declare function hasCommand(
   cmd: string,
   options?: { platform?: NodeJS.Platform; env?: Record<string, string | undefined>; probe?: CommandProbe },

package/bin/has-command.js

@@ -37,9 +37,9 @@ import path from "node:path";
 const WINDOWS_LAUNCHABLE_EXTENSIONS = ["", ".exe", ".com", ".cmd", ".bat"];
 
 /** A name CreateProcess/execvp resolves itself rather than by searching PATH. */
-const namesAPath = (cmd) => cmd.includes("/") || cmd.includes("\\");
+export const namesAPath = (cmd) => cmd.includes("/") || cmd.includes("\\");
 
-const realProbe = {
+export const realProbe = {
   isFile: (candidate) => {
     try {
       return statSync(candidate).isFile();
@@ -60,7 +60,7 @@ const realProbe = {
 };
 
 // "" first so an explicit `foo.exe` is found as itself rather than as `foo.exe.EXE`.
-const extensionsFor = (platform) => (platform === "win32" ? WINDOWS_LAUNCHABLE_EXTENSIONS : [""]);
+export const extensionsFor = (platform) => (platform === "win32" ? WINDOWS_LAUNCHABLE_EXTENSIONS : [""]);
 
 // A Windows PATH entry may be QUOTED — `"C:\Program Files\tools"` — which the shells strip and a
 // plain join would not, leaving a path that matches nothing. Same rule as the server's
@@ -69,7 +69,7 @@ const extensionsFor = (platform) => (platform === "win32" ? WINDOWS_LAUNCHABLE_E
 // The current directory is on neither platform's list. cmd.exe searches it and POSIX shells do
 // not, but what launches an agent is node-pty on both — and the directory THIS process sits in is
 // the launch directory, never the one the PTY will run in.
-const searchDirectories = (platform, env) => {
+export const searchDirectories = (platform, env) => {
   const raw = env.PATH || env.Path || "";
   if (platform === "win32") {
     return raw

package/bin/mulmoterminal.js

@@ -223,12 +223,18 @@ function passStartupGate(args) {
 async function runInit(initArgs) {
   log("Setting up MulmoTerminal…\n");
 
+  const hasClaude = agentInstalled("claude");
+  // Imported here so a normal launch never loads the version check or reaches its network.
+  const { checkVersions } = await import("./check-versions.js");
+  const versionHints = await checkVersions({ claudeBin: hasClaude ? agentBin("claude") : null });
+
   const nodeOk = nodeMeetsMinimum(process.versions.node);
   console.log(nodeOk ? `  ✓ Node ${process.versions.node}` : `  ✗ Node ${process.versions.node} — MulmoTerminal needs ≥ ${MIN_NODE_LABEL}`);
+  versionHints.node.forEach((line) => console.log(line));
 
-  const hasClaude = agentInstalled("claude");
   if (hasClaude) {
     console.log("  ✓ Claude Code CLI");
+    versionHints.claude.forEach((line) => console.log(line));
   } else {
     console.log("  ✗ Claude Code CLI — not found");
     console.log("      → npm install -g @anthropic-ai/claude-code   (then run `claude` and log in)");

package/bin/version-drift.d.ts

@@ -0,0 +1,11 @@
+export type Drift = { kind: "current" } | { kind: "unknown" } | { kind: "behind"; latest: string; sameMajor?: boolean };
+export declare const CURRENT: Drift;
+export declare const UNKNOWN: Drift;
+export declare const CLAUDE_UPDATE_NATIVE: string;
+export declare const CLAUDE_UPDATE_NPM: string;
+export declare function nodeDrift(localVersion: string, releases: unknown): Drift;
+export declare function claudeDrift(localVersion: string | null, stableVersion: string | null): Drift;
+export declare function parseClaudeVersion(stdout: string | null | undefined): string | null;
+export declare function claudeUpdateCommands(realPath: string | null): string[];
+export declare function nodeDriftLines(drift: Drift, upgrade: import("./node-install.js").NodeUpgradeGuide): string[];
+export declare function claudeDriftLines(drift: Drift, localVersion: string | null, updateCommands: string[]): string[];

package/bin/version-drift.js

@@ -0,0 +1,88 @@
+// Whether this machine's Node and Claude Code are behind the published releases, and what `init`
+// says about it (#2477). Pure: the releases, the local versions and the binary path are handed in
+// by bin/check-versions.js, so every decision here is testable without the network.
+import { NODE_DOWNLOAD_URL } from "./node-install.js";
+import { isNewerVersion } from "./update-check.js";
+
+export const CURRENT = { kind: "current" };
+export const UNKNOWN = { kind: "unknown" };
+
+const stripV = (version) => String(version).replace(/^v/, "");
+const majorOf = (version) => Number.parseInt(stripV(version).split(".")[0], 10);
+const newestOf = (versions) => versions.reduce((newest, version) => (isNewerVersion(version, newest) ? version : newest));
+// Remote strings are printed as-is, so only a plain x.y.z is accepted — anything else would compare
+// as zeros (and read as current) or put the registry's text on the user's terminal.
+const isPlainVersion = (version) => typeof version === "string" && /^v?\d+\.\d+\.\d+$/.test(version);
+const isRelease = (entry) => typeof entry === "object" && entry !== null && isPlainVersion(entry.version);
+
+/**
+ * Node against the LTS releases in nodejs.org's index.json.
+ *
+ * The target is the newest LTS of the same major: moving someone off a working 22.x because 24.x
+ * exists is not this check's call. A major with no LTS release is compared with the newest LTS,
+ * unless it is newer than that one — a Current release is not behind anything.
+ */
+export function nodeDrift(localVersion, releases) {
+  if (!Array.isArray(releases) || Number.isNaN(majorOf(localVersion))) return UNKNOWN;
+  const ltsVersions = releases.filter((entry) => isRelease(entry) && entry.lts).map((entry) => stripV(entry.version));
+  if (ltsVersions.length === 0) return UNKNOWN;
+  const sameMajor = ltsVersions.filter((version) => majorOf(version) === majorOf(localVersion));
+  const newestLts = newestOf(ltsVersions);
+  if (sameMajor.length === 0 && majorOf(localVersion) > majorOf(newestLts)) return CURRENT;
+  const target = sameMajor.length > 0 ? newestOf(sameMajor) : newestLts;
+  return isNewerVersion(target, stripV(localVersion)) ? { kind: "behind", latest: target, sameMajor: sameMajor.length > 0 } : CURRENT;
+}
+
+/** Claude Code against the npm `stable` dist-tag. Ahead of `stable` (on `latest`) is current. */
+export function claudeDrift(localVersion, stableVersion) {
+  if (typeof localVersion !== "string" || !isPlainVersion(stableVersion)) return UNKNOWN;
+  return isNewerVersion(stableVersion, localVersion) ? { kind: "behind", latest: stableVersion } : CURRENT;
+}
+
+/** `claude --version` prints `2.1.284 (Claude Code)`; anything without a leading version is null. */
+export function parseClaudeVersion(stdout) {
+  return /^\s*(\d+\.\d+\.\d+)/.exec(String(stdout ?? ""))?.[1] ?? null;
+}
+
+export const CLAUDE_UPDATE_NATIVE = "claude update";
+export const CLAUDE_UPDATE_NPM = "npm install -g @anthropic-ai/claude-code@latest";
+
+/**
+ * How to update the Claude Code at `realPath`. Only the two layouts checked on a real machine get a
+ * single command; anything else gets both, as the server's own "too old" message does.
+ */
+export function claudeUpdateCommands(realPath) {
+  const path = String(realPath ?? "").replaceAll("\\", "/");
+  if (path.includes("/node_modules/@anthropic-ai/claude-code/")) return [CLAUDE_UPDATE_NPM];
+  if (path.includes("/.local/share/claude/")) return [CLAUDE_UPDATE_NATIVE];
+  return [CLAUDE_UPDATE_NATIVE, `${CLAUDE_UPDATE_NPM}   (if you installed it with npm)`];
+}
+
+const HINT = "      → ";
+const COMMAND = "          ";
+
+function updateLines(headline, commands, fallback, via = null) {
+  if (commands.length === 0) return [`${HINT}${headline} Update: ${fallback}`];
+  const withTool = via ? " with " + via : "";
+  return [`${HINT}${headline} To update${withTool}:`, ...commands.map((command) => `${COMMAND}${command}`)];
+}
+
+/**
+ * The lines printed under `✓ Node …`; empty when there is nothing to say. The commands are the
+ * install tool's own upgrade (`nodeUpgradeGuide`), which may land on a newer major than the one
+ * named — so the tool is named too.
+ */
+export function nodeDriftLines(drift, upgrade) {
+  if (drift.kind === "unknown") return [`${HINT}○ could not check for a newer Node (offline?)`];
+  if (drift.kind !== "behind") return [];
+  const headline = drift.sameMajor ? `Node ${drift.latest} is out (latest ${majorOf(drift.latest)}.x LTS).` : `Node ${drift.latest} is the latest LTS.`;
+  return updateLines(headline, upgrade.commands, NODE_DOWNLOAD_URL, upgrade.via);
+}
+
+/** The lines printed under `✓ Claude Code CLI`; empty when there is nothing to say. */
+export function claudeDriftLines(drift, localVersion, updateCommands) {
+  if (localVersion === null) return [`${HINT}○ could not read the Claude Code version`];
+  if (drift.kind === "unknown") return [`${HINT}○ could not check for a newer Claude Code (offline?)`];
+  if (drift.kind !== "behind") return [];
+  return updateLines(`Claude Code ${localVersion} is older than the stable release ${drift.latest}.`, updateCommands, CLAUDE_UPDATE_NATIVE);
+}

package/blueprints/ask/checks/replies.mjs

@@ -1,7 +1,7 @@
 // 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
+//           and names every place it quotes (the address, or the heading of the section there); 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
@@ -9,6 +9,7 @@ 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 { headingsOf, namesPlace } = await import(fromBase("places.mjs"));
 
 const REPLIES = ".blueprint/replies.json";
 const REPLIES_PAGE = ".blueprint/replies.md";
@@ -29,6 +30,15 @@ if (answers?.keep === KEEP && documents.includes(FAQ)) fail(`${FAQ} is one of th
 const indented = (line) => "  " + line;
 const nonEmpty = (value) => typeof value === "string" && value.trim() !== "";
 
+// Read once per document, and only for one of the documents: a source that is not is refused by the quotation check.
+const headingCache = new Map();
+const headingAt = (source, address) => {
+  const resolved = documentSource(documents)(source);
+  if (!resolved.path) return undefined;
+  if (!headingCache.has(resolved.path)) headingCache.set(resolved.path, headingsOf(resolved.path));
+  return headingCache.get(resolved.path).get(address.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";
@@ -39,7 +49,10 @@ const replyProblem = (reply) => {
   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()));
+  const unnamed = citations.filter(
+    (citation) =>
+      !reply.answer.includes(citation.address.trim()) && !namesPlace(reply.answer, citation.address, headingAt(String(citation.source), citation.address)),
+  );
   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;

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

@@ -48,11 +48,15 @@ the answers before anything is kept.
 - `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.
+  copied character for character — the check runs `chaff cite` on every one. **Name every cited place in
+  the `answer` text** so the person can open the document there: an article or item as the document numbers it
+  (第4条第2項, Section 3.1), and a section of a Markdown document by its heading, word for word, in 「」 (「作業用フォルダを信頼しておく」;
+  in an English answer, "Getting started") — the check looks for it in those marks.
+  chaff's index for a section (`h1.3`) goes in `address` only — it means nothing to the person.
 - `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.
+Also write `.blueprint/replies.md` for the person: each question as a heading, the answer, and the quotations,
+each with its place named as in the answer (never `h1.3`).
 
 ## Done when
 

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

@@ -17,7 +17,8 @@ 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
+written (the document, and the place named as in the answer: 第4条第2項, or a section's heading in 「」 —
+never chaff's `h1.3`). For a question the documents do not answer, say so — that is worth keeping
 too.
 
 ## Done when

package/blueprints/ask/steps.json

@@ -13,7 +13,8 @@
       "description": "残すと決めたなら、確かめた答えを FAQ.md に書き足す。",
       "skill": "skills/keep",
       "check": "node \"$BLUEPRINT_USECASE/checks/replies.mjs\" keep",
-      "gates": ["review"]
+      "gates": ["review"],
+      "reads": [".blueprint/replies.md"]
     }
   ]
 }

package/blueprints/docs/checks/chaff.sh

@@ -4,4 +4,4 @@
 if [ -n "${CHAFF_BIN:-}" ]; then
   exec sh -c "$CHAFF_BIN \"\$@\"" chaff "$@"
 fi
-exec npx -y chaffjs@0.10 "$@"
+exec npx -y chaffjs@0.13 "$@"

package/blueprints/docs/checks/places.d.mts

@@ -0,0 +1,7 @@
+// Types for places.mjs, which the packs run with plain node and the specs import.
+export function headingsIn(tree: unknown): Map<string, string>;
+export function headingsOf(file: string): Map<string, string>;
+export function namesPlace(text: string, address: string, heading: string | undefined): boolean;
+export function placeNamesIn(tree: unknown): Map<string, string>;
+export function placeNamesOf(file: string): Map<string, string>;
+export function placeNamer(sourcePath: (source: string) => { path?: string; problem?: string }): (source: string, address: string) => string;

package/blueprints/docs/checks/places.mjs

@@ -0,0 +1,102 @@
+// Where a quotation sits, named for the person who reads it: a section of a Markdown document by its heading,
+// since chaff's address for it (h1.3) tells nobody anything. Other addresses (第4条第2項, 3.1) already read as the
+// document writes them.
+import { runChaff } from "./chaff.mjs";
+
+const sectionsIn = (node) => [
+  ...(node?.kind === "section" && typeof node.address === "string" && typeof node.attrs?.heading === "string" ? [[node.address, node.attrs.heading]] : []),
+  ...(Array.isArray(node?.children) ? node.children.flatMap(sectionsIn) : []),
+];
+
+const PARTS = new Set(["section", "article"]);
+
+const text = (value) => (typeof value === "string" && value !== "" ? value : null);
+
+// A Japanese article (第4条, 第二十一条の二): what is under it is named as Japanese law cites it.
+const JA_ARTICLE = /^第[^条\s]+条/u;
+const halfWidth = (digits) => digits.replace(/[０-９]/gu, (digit) => String.fromCharCode(digit.charCodeAt(0) - 0xfee0));
+
+// Under a Japanese article, one level down is a paragraph (第2項, numbered from the address when chaff gives it no
+// label) and anything deeper an item (第三号, by its label). chaff calls both "item", so the depth tells them apart.
+function japaneseName(label, own, above, article) {
+  const levels = own.slice(article.address.length + 1).split(".");
+  if (levels.length === 1) return `${above}第${halfWidth(label ?? levels[0])}項`;
+  return `${above}第${label ?? levels.at(-1)}号`;
+}
+
+// A part (an article, a section) is named by its label, or by its quoted heading when it has none (a Markdown
+// section); anything below it (an item, a paragraph) adds its own label to the name of what holds it.
+function nameOf(node, own, above, article) {
+  const label = text(node?.attrs?.label);
+  if (PARTS.has(node?.kind)) {
+    const heading = text(node?.attrs?.heading);
+    return label ?? (heading === null ? own : `「${heading}」`);
+  }
+  if (above === null) return label ?? own;
+  return article?.japanese && own.startsWith(`${article.address}.`) ? japaneseName(label, own, above, article) : `${above} ${label ?? own}`;
+}
+
+const partOf = (node, own, name, article) => (PARTS.has(node?.kind) && own !== null ? { address: own, japanese: JA_ARTICLE.test(name ?? "") } : article);
+
+const namesIn = (node, above, article) => {
+  const own = text(node?.address);
+  const name = own === null ? above : nameOf(node, own, above, article);
+  const here = own === null ? [] : [[own, name]];
+  const within = partOf(node, own, name, article);
+  return [...here, ...(Array.isArray(node?.children) ? node.children.flatMap((child) => namesIn(child, name, within)) : [])];
+};
+
+/** Every address in a chaff tree, with the name a person reads for it: 第4条第2項, Section 3.2 (a) (i), 「用意するもの」. */
+export const placeNamesIn = (tree) => new Map(namesIn(tree, null, null));
+
+/** The place names of `file`, by address; none when chaff cannot read its tree. */
+export const placeNamesOf = (file) => {
+  const run = runChaff(["tree", file, "--format", "json"]);
+  if (run.code !== 0) return new Map();
+  try {
+    return placeNamesIn(JSON.parse(run.stdout));
+  } catch {
+    return new Map();
+  }
+};
+
+/**
+ * Where a citation sits, for a view a person reads: its place name from the document's tree, read once per document
+ * and only for one of `documents` (through `sourcePath`, which resolves or refuses a source); the address itself
+ * when there is no name.
+ */
+export const placeNamer = (sourcePath) => {
+  const cache = new Map();
+  return (source, address) => {
+    const resolved = sourcePath(source);
+    if (!resolved.path) return address;
+    if (!cache.has(resolved.path)) cache.set(resolved.path, placeNamesOf(resolved.path));
+    return cache.get(resolved.path).get(String(address).trim()) ?? address;
+  };
+};
+
+/** Every section address in a chaff tree (`tree --format json`), with its heading. */
+export const headingsIn = (tree) => new Map(sectionsIn(tree));
+
+/** The section headings of `file`, by address; none when chaff cannot read its tree. */
+export const headingsOf = (file) => {
+  const run = runChaff(["tree", file, "--format", "json"]);
+  if (run.code !== 0) return new Map();
+  try {
+    return headingsIn(JSON.parse(run.stdout));
+  } catch {
+    return new Map();
+  }
+};
+
+// A heading counts only in quotation marks: a short one (期限) is also an ordinary word, and bare it would be found by accident.
+const QUOTES = [
+  ["「", "」"],
+  ['"', '"'],
+  ["“", "”"],
+];
+
+/** Whether `text` names a place: by its address as written, or by the quoted heading of the section at that address. */
+export const namesPlace = (text, address, heading) =>
+  text.includes(address.trim()) ||
+  (typeof heading === "string" && heading !== "" && QUOTES.some(([open, close]) => text.includes(`${open}${heading}${close}`)));

package/blueprints/docs/skills/workspace/SKILL.md

@@ -12,7 +12,7 @@ repository, `.git/info/exclude`) until the person has approved the models.
 1. `.blueprint/` already exists (the build created it). Everything this build records goes there.
 2. Run chaff once through the base pack's wrapper, so its first download happens now and not in the
    middle of a later step: `sh <base pack>/checks/chaff.sh rules --json > /dev/null`. The wrapper runs the
-   pinned chaff (`npx -y chaffjs@0.10`) unless `CHAFF_BIN` names another. If it fails, show the person the
+   pinned chaff (`npx -y chaffjs@0.13`) unless `CHAFF_BIN` names another. If it fails, show the person the
    error and stop — do not work around it.
 3. If the folder is a git repository, add `.blueprint/` to `.git/info/exclude`. That keeps the build's
    working files out of commits without touching `.gitignore`, which belongs to the person.

package/blueprints/firebase/checks/security-report.sh

@@ -0,0 +1,11 @@
+#!/bin/sh
+# The security review's report exists, walks every OWASP Top 10:2025 category, and leaves no HIGH or
+# MEDIUM finding open or merely accepted. A finding is one line: `- <HIGH|MEDIUM|LOW> <fixed|open|accepted>: …`.
+set -eu
+report=.blueprint/security-review.md
+[ -s "$report" ] || { echo "missing $report" >&2; exit 1; }
+for category in A01 A02 A03 A04 A05 A06 A07 A08 A09 A10; do
+  grep -q "^#.*$category" "$report" || { echo "$report has no section for $category (OWASP Top 10:2025)" >&2; exit 1; }
+done
+open=$(grep -nE '^- (HIGH|MEDIUM) (open|accepted)' "$report" || true)
+[ -z "$open" ] || { printf 'HIGH / MEDIUM findings must be fixed, but are open or accepted in %s:\n%s\n' "$report" "$open" >&2; exit 1; }

package/blueprints/firebase/checks/security.sh

@@ -0,0 +1,41 @@
+#!/bin/sh
+# The security review is proven by what ships, not by the review's word: the rules refuse what the
+# review's emulator tests say they refuse, the rules end in deny-all, Hosting sends the headers a browser
+# needs, no service account key is in the project, the dependencies have no known high-severity hole,
+# the review's own report is in place, and dev runs what the review left — so production, which ships
+# what dev ran, gets the fixes, and a header that breaks the page shows up here, on dev.
+set -eu
+here="$(dirname "$0")"
+sh "$here/security-report.sh"
+grep -qE 'allow +read, *write: *if +false' firestore.rules || { echo "firestore.rules does not end in a deny-all (allow read, write: if false)" >&2; exit 1; }
+node -e 'const fs=require("node:fs");
+  const hosting=[JSON.parse(fs.readFileSync("firebase.json","utf8")).hosting].flat().filter(Boolean);
+  if (hosting.length===0) { console.error("firebase.json has no hosting section"); process.exit(1); }
+  for (const site of hosting) {
+    const all=(site.headers??[]).filter((h)=>h.source==="**").flatMap((h)=>h.headers??[]);
+    const value=(key)=>all.find((h)=>h.key.toLowerCase()===key)?.value??"";
+    const missing=[];
+    if (!/nosniff/i.test(value("x-content-type-options"))) missing.push("X-Content-Type-Options: nosniff");
+    if (!value("content-security-policy")) missing.push("Content-Security-Policy");
+    if (!/frame-ancestors/i.test(value("content-security-policy")) && !/deny|sameorigin/i.test(value("x-frame-options"))) missing.push("frame-ancestors or X-Frame-Options");
+    if (missing.length) { console.error("firebase.json hosting headers for ** lack: "+missing.join(", ")); process.exit(1); }
+  }'
+keys=$(grep -rlE '"private_key"|-----BEGIN [A-Z ]*PRIVATE KEY-----' . --exclude-dir=node_modules --exclude-dir=.firebase --exclude-dir=dist 2>/dev/null || true)
+[ -z "$keys" ] || { printf 'a private key is in the project; move it out and revoke it:\n%s\n' "$keys" >&2; exit 1; }
+audit() {
+  # Read from the summary, not the exit code: an audit that could not reach the registry must not pass.
+  (cd "$1" && yarn audit --groups dependencies --json 2>/dev/null) | node -e 'let s="";process.stdin.on("data",(c)=>s+=c).on("end",()=>{
+    const summary = s.split("\n").filter(Boolean).map((line) => JSON.parse(line)).find((entry) => entry.type === "auditSummary");
+    if (!summary) { console.error(process.argv[1] + ": yarn audit did not report a summary (is the registry reachable?)"); process.exit(1); }
+    const { high = 0, critical = 0 } = summary.data.vulnerabilities;
+    if (high + critical > 0) { console.error(`${process.argv[1]}: yarn audit finds ${high} high and ${critical} critical vulnerabilities in dependencies`); process.exit(1); }
+  })' "$1"
+}
+audit .
+if [ -f functions/package.json ]; then
+  [ -f functions/yarn.lock ] || { echo "functions/ has no yarn.lock; install its dependencies with yarn so they can be audited" >&2; exit 1; }
+  audit functions
+fi
+sh "$here/emulator-test.sh" security
+[ .blueprint/build-id -nt .blueprint/security-review.md ] || { echo "dev was not deployed after the review; deploy it to dev again so production ships what dev runs" >&2; exit 1; }
+sh "$here/deploy-check.sh" dev

package/blueprints/firebase/checks/spec.sh

@@ -6,3 +6,7 @@ if grep -n '{{' .blueprint/spec.md >&2; then
   echo "unfilled placeholders are left in .blueprint/spec.md" >&2
   exit 1
 fi
+# A usecase may hold its spec to more than the template: when it ships its own spec check, that runs too.
+if [ -n "${BLUEPRINT_USECASE:-}" ] && [ -f "$BLUEPRINT_USECASE/checks/spec.sh" ]; then
+  sh "$BLUEPRINT_USECASE/checks/spec.sh"
+fi

package/blueprints/firebase/checks/start-here.sh

@@ -0,0 +1,8 @@
+#!/bin/sh
+# The first page the finished build shows says where the published app is and what to try to see it works.
+set -eu
+start=.blueprint/start-here.md
+[ -s "$start" ] || { echo "missing $start" >&2; exit 1; }
+prod=$(sh "$(dirname "$0")/project-id.sh" prod)
+grep -q "https://$prod.web.app" "$start" || { echo "$start does not name the production URL (https://$prod.web.app)" >&2; exit 1; }
+grep -q '^- \[ \] ' "$start" || { echo "$start has no checklist of what to try (- [ ] …)" >&2; exit 1; }

package/blueprints/firebase/manifest.json

@@ -35,5 +35,6 @@
   "credentials": [
     "firebase login",
     "gcloud auth login"
-  ]
+  ],
+  "report": ".blueprint/start-here.md"
 }