mulmoterminal 7.1.0 → 7.2.0

package/README.md

@@ -308,7 +308,8 @@ mulmoterminal
 
 **Stopping it.** `Ctrl+C` in the terminal that started it — or, if you can no longer find that
 terminal, **Settings → Quit MulmoTerminal** in the browser, or **`npx mulmoterminal@latest stop`**
-from any terminal (installed globally, just `mulmoterminal stop`). All three run the same shutdown:
+from any terminal (installed globally, just `mulmoterminal stop`; it stops every server running on
+this machine, and `--port <port>` stops only that one). All three run the same shutdown:
 with `tmux` installed the agent sessions survive and come back under **Settings → Sessions that
 survived a restart**; without it they end with the server.
 
@@ -634,6 +635,17 @@ up for Codex, loaded by description.
 
 ---
 
+## Running the server on another machine
+
+The server can live on a Linux box, a VPS or a container while your browser stays on your laptop:
+start it there over SSH (`npx mulmoterminal`), and reach it through an SSH tunnel
+(`ssh -N -L 34567:127.0.0.1:34567 you@server`, then open `http://localhost:34567`). Started over
+SSH, the launcher opens no browser on the server and prints that command. It still listens on
+loopback only — nothing is opened to the network. Logging the agents in on the server, Docker, and
+the few actions that act on the server's machine: [Run the server on another machine](https://receptron.github.io/mulmoterminal/guide/en/remote.html).
+
+---
+
 ## Session persistence (tmux)
 
 If **`tmux` is installed**, MulmoTerminal runs each Claude session and launcher inside
@@ -777,7 +789,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. 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.*
+*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. Three settings stay with their skill because a form would be the wrong tool for them (`keymap`, `themes`, `buttons`/`chips`); Settings shows what each is doing now and launches that skill. Backends (`providers`), custom agents and accounts are added and removed in **Models and backends**. 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 |
 | ------------ | ------- |
@@ -799,7 +811,7 @@ The Settings modal (the gear button) persists per-user UI choices to `~/.mulmote
 | `pushKinds` | Which moments push: `"finished"` (a turn ended, ✅) and/or `"waiting"` (the agent stopped to ask — a permission prompt or a question, ❓, **once per prompt**). Omit to keep both; `[]` for none. A kind added in a later version stays off until you tick it. |
 | `worklogEnabled` | `true` to run the built-in **dev worklog** batch (see below). Off by default (each run spawns an LLM session, so it costs tokens). Editable in Settings → **Sessions and background tasks**. |
 | `worklogIntervalHours` | Worklog cadence in hours (default `6`, clamped to `1`–`168`). A stepper in the same Settings section covers the range. |
-| `feedRefreshEnabled` | `false` stops the hourly **collection/feed refresh** (one scheduled task per root — the workspace and every saved project directory). **On by default**; only an explicit `false` turns it off, so an existing config keeps the behaviour it has. Takes effect at the next server start — the scheduler registers once at boot. Feeds still refresh on demand. Checkbox in Settings → **Sessions**. |
+| `feedRefreshEnabled` | `false` stops the hourly **collection/feed refresh** (one scheduled task per root — the workspace and every saved project directory). **On by default**; only an explicit `false` turns it off, so an existing config keeps the behaviour it has. Saved from Settings (or any `POST /api/config`), it applies at once — the running scheduler rebuilds its built-in tasks; a hand-edit applies after **Settings → Reload config file** (or a restart). Feeds still refresh on demand. Checkbox in Settings → **Sessions**. |
 | `calendarSyncEnabled` | `false` stops the hourly **Google Calendar sync** (pulls changed events into collections that declare a calendar). Same default and the same restart rule as `feedRefreshEnabled`; calendar collections still sync on demand. Checkbox in the same Settings section. With both off and `worklogEnabled` off, no **built-in** task is registered. Your own tasks in `config/scheduler/tasks.json` are unaffected — these switches do not touch them, and an enabled one still registers and still runs the tick loop. Only when there is no enabled user task either does the scheduler stop writing its state file and run logs. |
 | `terminalSubmit` | Which bytes Claude reads as **submit** vs **newline**: `"cr"` (default — Enter submits, Shift+Enter makes a newline) or `"esc-cr"` (for a Claude Code rebound the other way). Applies to the keyboard **and** the phone remote-view submit, for **Claude sessions only** (shell/codex keep plain Enter). See the [Configuration guide](https://receptron.github.io/mulmoterminal/guide/en/config.html#terminal-submit). Settings → **Terminal keys** offers both, worded as behaviour. |
 | `copyOnSelect` | `true` puts a **mouse selection on the clipboard the moment it settles**, with no key pressed (the PuTTY / iTerm2 behaviour). **Off by default** — it changes the clipboard when you may only have meant to highlight something. There is a checkbox in Settings → **Terminal keys**, applied at once; a hand edit of the file needs a **server restart, then a tab reload** (the server reads this file once at startup, and the browser reads the value from it on load). Composes with the `copy` keymap action rather than replacing it. Over plain `http://` the browser gives a page no clipboard access, so a fallback asks xterm to copy instead; see the [Configuration guide](https://receptron.github.io/mulmoterminal/guide/en/config.html#copy-on-select). |
@@ -811,6 +823,7 @@ The Settings modal (the gear button) persists per-user UI choices to `~/.mulmote
 | `autoDirIcon` | Whether a project that sets no `icon` shows the favicon its repository already ships (`public/favicon.svg`, `apple-touch-icon.png`, a web manifest — first hit wins, ordered by how the image survives at 14px). **On by default**; Settings → **Directory appearance** has the switch. A single project opts out with `"icon": false` in its own `.mulmoterminal.json`, which this does not override. A key that was written and got it wrong shows nothing rather than falling back — a broken setting has to look broken. `true` / `false` only. |
 | `cockpitLines` | `{ summary, prompt, response }` — how many lines each **cockpit-roster** row shows before it clamps (default `2` / `2` / `3`, each clamped to `1`–`20`). Raising them trades how many sessions fit on screen for reading a long one in place. Three steppers in Settings → **Waiting rows**. |
 | `showLoadAverage` | Whether the grid header draws this machine's **load average** beside the 5h / 7d usage windows, as a percentage of its cores (`load 334%` = a 20-core machine with 66.8 runnable processes). **On by default**; amber at 100%, red at 200%, hover for the raw 1 / 5 / 15-minute figures. Settings → **Grid header read-outs** has the switch. A host that keeps no load average (Windows) shows nothing rather than `0%`, whatever this says. `true` / `false` only. |
+| `remoteServer` | **Experimental.** The server runs on another machine than your browser (an SSH tunnel — [guide](https://receptron.github.io/mulmoterminal/guide/en/remote.html)): the actions that would act on the server's screen (the file dialog, the file manager, the OS app) are hidden or say why, and a dropped file is always uploaded. **Off unless `true`**; set it in the server's config. |
 | `fontFamily` | The **terminal font** every session renders in — a CSS font-family stack, e.g. `"'Cica', 'MS Gothic', monospace"`. Set it in Settings → **Terminal font**, applied at once; editing the file instead needs a **restart** (this config is read once at startup). Unset uses the built-in stack (JetBrains Mono / Fira Code / Menlo / Consolas, then CJK faces for Japanese, Korean and Chinese). Unlike the per-browser font **size**, this is one value for the whole host — it names fonts, and which fonts exist is a property of the machine. A directory can override it. See the [Configuration guide](https://receptron.github.io/mulmoterminal/guide/en/config.html#font-family). |
 
 Every MulmoTerminal on the machine shares this one file, so an older build could save over a key a
@@ -829,9 +842,14 @@ are items in the **path menu** (click the directory path on the terminal header)
 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
-agent), `"open"`, or `"action"` (act on the cell itself — `action: "restart"` ends the agent and
-starts it again in the same cell on the same conversation, which is how an MCP / config / plugin
-change takes effect; it costs a resume and asks nothing first). An `open` button targets one of `url` / `reveal` (OS file manager) / `files`
+agent), `"open"`, or `"action"` (act on the cell itself, named like the `keymap` actions so one operation is
+a button, a key and a command-palette entry — `action: "terminal-restart"` ends the agent and starts
+it again in the same cell on the same conversation, which is how an MCP / config / plugin change
+takes effect; it costs a resume and asks nothing first. `"terminal-new-here"` opens the launch panel
+on the cell's directory, and `"pane-files"` / `"pane-prompts"` / … / `"terminal-timeline"` /
+`"terminal-talk"` / `"terminal-park"` / `"terminal-copy-code"` / `"terminal-insert-path"` / `"terminal-reveal"` /
+`"terminal-voice"` / `"terminal-diff"` / `"terminal-note"` do what the cell's menus and buttons do, and `"screen-*"` / `"settings-open"` /
+`"sound-toggle"` / `"view-toggle"` / `"order-*"` / `"page-next"` / `"page-prev"` do what the toolbar and the page tabs do; the old name `"restart"` still works). An `open` button targets one of `url` / `reveal` (OS file manager) / `files`
 (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).
@@ -891,7 +909,7 @@ channel is connected (its Google sign-in supplies the notification auth). With R
 disconnected, or with no device registered, the toggle is a no-op.
 
 **Dev worklog (cross-clone).** Set `worklogEnabled: true` in
-`~/.mulmoterminal/config.json` (and **restart** — the scheduler reads its tasks at boot)
+`~/.mulmoterminal/config.json` (or switch it on in Settings, which applies at once; after a hand-edit use Settings → **Reload config file**)
 to register a built-in scheduled task. Every `worklogIntervalHours` (default 6) it spawns
 a Claude session that reviews the work you did across **all your saved working dirs**
 (`cwdPresets`) since it last ran, and writes it up as a short manager-style report.

package/bin/cli-args.d.ts

@@ -25,4 +25,5 @@ export interface RunningInstance {
   port: number | null;
 }
 export declare function stopCommandFor(pkgDir: string): string;
+export declare function stopCommandForThis(stopCommand: string, port: number, instances: readonly { port: number | null }[]): string;
 export declare function runningInstancesPrompt(instances: readonly RunningInstance[], stopCommand?: string): string;

package/bin/cli-args.js

@@ -366,6 +366,11 @@ export function saysYes(answer) {
 // they are: npx unpacks into `<cache>/_npx/<hash>/node_modules/mulmoterminal`.
 const NPX_INSTALL = /[/\\]_npx[/\\]/;
 
+/** The stop command the ready banner shows for the server on `port`: the plain one while it is the
+ *  only server, and one narrowed to its port once another is running, which the plain one would stop
+ *  too (#2683). `instances` is the registry, this server included. */
+export const stopCommandForThis = (stopCommand, port, instances) => (instances.some((i) => i.port !== port) ? `${stopCommand} --port ${port}` : stopCommand);
+
 export const stopCommandFor = (pkgDir) => (NPX_INSTALL.test(String(pkgDir)) ? "npx mulmoterminal@latest stop" : "mulmoterminal stop");
 
 export function runningInstancesPrompt(instances, stopCommand = "mulmoterminal stop") {

package/bin/mulmoterminal.js

@@ -14,6 +14,7 @@ import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { computeUpdateNotice, isUpdateCheckDisabled } from "./update-check.js";
 import { detectNpxCacheDir, npxCacheHintLines } from "./npx-cache-hint.js";
+import { configuredRemoteServer, sshTunnelHintLines } from "./ssh-hint.js";
 import { planAfterServerExit } from "./server-supervision.js";
 import { waitUntilReady } from "./wait-ready.js";
 import {
@@ -29,6 +30,7 @@ import {
   secondInstancePrompt,
   runningInstancesPrompt,
   stopCommandFor,
+  stopCommandForThis,
   SECOND_INSTANCE_NOTE,
   nodeMeetsMinimum,
   unsupportedNodeMessage,
@@ -109,6 +111,17 @@ function readConfiguredDefaultAgent() {
   }
 }
 
+// The experimental `remoteServer` (#2669): the browser is on another machine, so the launcher opens
+// none here even when started without SSH (a service, a remote desktop). A missing or unreadable
+// file is simply "not set".
+function readRemoteServer() {
+  try {
+    return configuredRemoteServer(JSON.parse(readFileSync(CONFIG_FILE, "utf8")));
+  } catch {
+    return false;
+  }
+}
+
 // The command for `agent`, honouring its `<AGENT>_BIN` override.
 //
 // The override is the point rather than a detail: the gate used to look for the literal word
@@ -478,11 +491,16 @@ async function choosePort(requested, explicit) {
 //
 // `url` is where the BROWSER goes and `note` is what launchTarget wants said about that choice —
 // two different facts since #1889, and the note is null whenever the URL already covers it.
-function announceReady(url, note, noOpen) {
-  printReadyBanner(url, STOP_COMMAND);
+function announceReady(url, note, noOpen, sshHint, port) {
+  printReadyBanner(url, stopCommandForThis(STOP_COMMAND, port, liveInstances()));
   // Either the address a widened bind serves other machines on, or why the browser was NOT sent
   // to `localhost`. Null whenever the URL above already said everything.
   if (note) log(note);
+  // Over SSH the browser is on the other machine (see ssh-hint.js): say how to reach it, open nothing.
+  if (sshHint) {
+    sshHint.forEach((line) => log(line));
+    return;
+  }
   if (noOpen) return;
   try {
     // The command is a hardcoded literal; url is built by browserUrl from a numeric port, so it
@@ -549,7 +567,9 @@ function runServer({ port, probedAddress, localhostIsUnambiguous, noOpen, launch
       readyStarted = true;
       const localhostIsOurs = localhostIsUnambiguous && serverSaysLocalhostIsOurs !== false;
       const { url, note } = launchTarget(reachHost, port, localhostIsOurs);
-      cancelReady = waitUntilReady(port, () => announceReady(url, note, noOpen), { host: reachHost });
+      cancelReady = waitUntilReady(port, () => announceReady(url, note, noOpen, sshTunnelHintLines(process.env, port, readRemoteServer()), port), {
+        host: reachHost,
+      });
     };
     // The same message answers a second question now: whether this lifetime ever bound at all,
     // which is what a restart is allowed to depend on. Recorded BEFORE the address is looked at —

package/bin/ssh-hint.d.ts

@@ -0,0 +1,3 @@
+export declare function inSshSession(env: Record<string, string | undefined>): boolean;
+export declare const configuredRemoteServer: (config: unknown) => boolean;
+export declare function sshTunnelHintLines(env: Record<string, string | undefined>, port: number, remoteServer?: boolean): string[] | null;

package/bin/ssh-hint.js

@@ -0,0 +1,32 @@
+// A launcher started over SSH is on a machine whose screen nobody is looking at: the browser that
+// should open this is on the other end of the connection. So it does not try to open one here — on
+// a remote Mac that would put a window on a display no one sees — and it says how to reach the
+// server from there instead: an SSH port forward, the route the FAQ recommends. Nothing here reads
+// the process; the caller passes its environment.
+
+/** Whether this process runs inside an SSH login. sshd sets both variables; either is enough. */
+export function inSshSession(env) {
+  return Boolean(env.SSH_CONNECTION || env.SSH_CLIENT);
+}
+
+/** The experimental `remoteServer` out of a parsed `~/.mulmoterminal/config.json`: true only for a
+ *  literal `true`, like the server's own reading of it (common/remoteServer.ts). */
+export const configuredRemoteServer = (config) => config !== null && typeof config === "object" && config.remoteServer === true;
+
+/**
+ * The lines that tell someone on another machine how to open this server, or null when the browser
+ * is expected here: not an SSH login, and `remoteServer` not set. The host is left for them to fill
+ * in: SSH_CONNECTION names the address THIS side answered on, which behind NAT or a container is not
+ * one their machine can reach.
+ */
+export function sshTunnelHintLines(env, port, remoteServer = false) {
+  const ssh = inSshSession(env);
+  if (!ssh && !remoteServer) return null;
+  const user = env.USER || env.LOGNAME || "<user>";
+  const why = ssh ? "Started over SSH" : "remoteServer is set in config.json";
+  return [
+    `${why}, so no browser is opened here. On your own machine, run:`,
+    `  ssh -N -L ${port}:127.0.0.1:${port} ${user}@<this-host>`,
+    `then open http://localhost:${port} there.`,
+  ];
+}

package/bin/stop.d.ts

@@ -16,10 +16,12 @@ export interface StopResult {
   stubborn: StubbornInstance[];
   unconfirmed: InstanceEntry[];
 }
-export type StopArgs = { help: true } | { error: string } | { force: boolean };
+export type StopArgs = { help: true } | { error: string } | { force: boolean; port: number | null };
 
 export declare const STOP_USAGE: string;
 export declare function parseStopArgs(args: readonly string[]): StopArgs;
+export declare function selectByPort(instances: readonly InstanceEntry[], port: number | null): InstanceEntry[];
+export declare function noServerOnPortReport(port: number, instances: readonly InstanceEntry[]): string[];
 export interface ConfirmDeps {
   owners?: (port: number) => Promise<number[] | null>;
 }

package/bin/stop.js

@@ -14,7 +14,7 @@
 // Windows user find or kill anything.
 import { dirname } from "node:path";
 import { fileURLToPath } from "node:url";
-import { stopCommandFor } from "./cli-args.js";
+import { parsePortArg, stopCommandFor } from "./cli-args.js";
 import { isProcessAlive, liveInstances } from "./instances.js";
 import { portOwners } from "./port-owner.js";
 
@@ -140,10 +140,11 @@ export function stopReport({ stopped, stubborn, unconfirmed }, platform = proces
 export const stopExitCode = ({ stubborn, unconfirmed }) => (stubborn.length + unconfirmed.length ? 1 : 0);
 
 export const STOP_USAGE = [
-  "Usage: mulmoterminal stop [--force]",
+  "Usage: mulmoterminal stop [--port <port>] [--force]",
   "",
   "Stops every running MulmoTerminal server on this machine, from any terminal.",
   "",
+  "  --port    Stop only the server on that port (the one at http://localhost:<port>).",
   "  --force   Also stop a registered server that is no longer answering. Off by default:",
   "            a server that crashed leaves its entry behind, and that pid may since have",
   "            been given to an unrelated program.",
@@ -153,9 +154,26 @@ export const STOP_USAGE = [
  *  argument handling is testable — and so `stop --help` can never be read as "stop everything". */
 export function parseStopArgs(args) {
   if (args.includes("--help") || args.includes("-h")) return { help: true };
-  const unknown = args.filter((a) => a !== "--force");
+  const portAt = args.indexOf("--port");
+  const portArgs = portAt === -1 ? [] : [portAt, portAt + 1];
+  const unknown = args.filter((a, i) => a !== "--force" && !portArgs.includes(i));
   if (unknown.length) return { error: `Unknown argument for stop: ${unknown.join(" ")}` };
-  return { force: args.includes("--force") };
+  const force = args.includes("--force");
+  if (portAt === -1) return { force, port: null };
+  // The launcher's own reading of --port, so the two accept the same values. The environment's
+  // PORT is not consulted: a `stop` narrowed by a variable nobody typed here would surprise.
+  const parsed = parsePortArg(args, {}, null);
+  return "error" in parsed ? { error: parsed.error } : { force, port: parsed.port };
+}
+
+/** The servers a `stop` is about: all of them, or only the one on `port` (#2683). */
+export const selectByPort = (instances, port) => (port === null ? instances : instances.filter((i) => i.port === port));
+
+/** What `stop --port` says when nothing is registered there — and what IS running, since a wrong
+ *  port is the likeliest reason. */
+export function noServerOnPortReport(port, instances) {
+  const running = instances.map(describeInstance);
+  return [`No MulmoTerminal server is running on port ${port}.`, running.length ? `Running: ${running.join(", ")}` : "MulmoTerminal is not running."];
 }
 
 export async function runStop(args = []) {
@@ -169,7 +187,16 @@ export async function runStop(args = []) {
     console.error(STOP_USAGE);
     process.exit(2);
   }
-  const result = await stopInstances(liveInstances(), { force: parsed.force });
-  stopReport(result).forEach((line) => console.log(line));
+  const all = liveInstances();
+  const targets = selectByPort(all, parsed.port);
+  // Nothing on that port is the state asked for, like "nothing was running": not a failure.
+  if (parsed.port !== null && !targets.length) {
+    noServerOnPortReport(parsed.port, all).forEach((line) => console.log(line));
+    process.exit(0);
+  }
+  const result = await stopInstances(targets, { force: parsed.force });
+  // A retry must name the same server, or `--force` would stop every one.
+  const stopCommand = parsed.port === null ? selfStopCommand() : `${selfStopCommand()} --port ${parsed.port}`;
+  stopReport(result, process.platform, stopCommand).forEach((line) => console.log(line));
   process.exit(stopExitCode(result));
 }

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

@@ -18,7 +18,7 @@ Otherwise add to `FAQ.md` in this folder (create it if there is none). **Add aft
 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 (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
+in an English FAQ, 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/cloudflare/checks/page-renders.sh

@@ -15,12 +15,23 @@ RENDER_LIMIT_SECONDS=60
 work=$(mktemp -d)
 "$chrome" --headless=new --disable-gpu --no-first-run --user-data-dir="$work/profile" --virtual-time-budget=15000 --dump-dom "$url" >"$work/dom.html" 2>/dev/null &
 pid=$!
-trap 'kill "$pid" 2>/dev/null || true; rm -rf "$work"' EXIT
+# Chrome can still be writing its profile when it is stopped, and under set -e a failed rm in this trap would turn a page
+# that rendered into a failed check; the scratch folder is left behind instead.
+trap 'kill "$pid" 2>/dev/null || true; rm -rf "$work" 2>/dev/null || true' EXIT
 waited=0
 until grep -q "</html>" "$work/dom.html" 2>/dev/null || [ "$waited" -ge "$RENDER_LIMIT_SECONDS" ] || ! kill -0 "$pid" 2>/dev/null; do
   sleep 1
   waited=$((waited + 1))
 done
+# A Chrome that crashed before printing the page says nothing about the app: like no Chrome, it cannot judge.
+if ! grep -q "</html>" "$work/dom.html" 2>/dev/null && ! kill -0 "$pid" 2>/dev/null; then
+  status=0
+  wait "$pid" || status=$?
+  if [ "$status" -ne 0 ]; then
+    echo "Chrome ($chrome) exited with status $status before printing the page; could not confirm that $url renders" >&2
+    exit 0
+  fi
+fi
 node -e 'let s="";process.stdin.on("data",(c)=>s+=c).on("end",()=>{
   const body = (s.match(/<body[^>]*>([\s\S]*)<\/body>/i) || [, ""])[1];
   const text = body.replace(/<(script|style|noscript)[\s\S]*?<\/\1>/gi, "").replace(/<[^>]+>/g, " ").replace(/\s+/g, " ").trim();

package/blueprints/cloudflare/skills/spec/SKILL.md

@@ -17,7 +17,7 @@ The answers are in `.blueprint/answers.json`; the prompt names both pack directo
 4. Something the answers do not settle is not guessed: write "未定" and add a line to
    `.blueprint/open-questions.md` saying what is needed and why it matters.
 5. Append both packs' `security/` checklists under a heading "必ず詰める点", unchanged.
-6. Write in the language the user answered in. Nothing is built in this step; the next step stops for the user
+6. Write in the language the build's prompt says the user reads (without one, the language the user answered in). Nothing is built in this step; the next step stops for the user
    to read this spec.
 
 Done when the check passes: `.blueprint/spec.md` exists and no `{{` placeholder is left in it.

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.14 "$@"
+exec npx -y chaffjs@0.15 "$@"

package/blueprints/docs/checks/drafts.mjs

@@ -11,13 +11,16 @@ const DIR = ".blueprint/chaff-feedback";
 const INDEX = join(DIR, "index.json");
 const DRAFTS_SECTION = [["chaff への報告の下書き", "Drafts for chaff"]];
 
-const argsFor = (entry) =>
+const argsFor = (entry, extra) =>
   entry.kind === "wrong"
-    ? ["feedback", entry.file, "--rule", entry.rule, "--line", String(entry.line), "--experimental"]
-    : ["feedback", entry.file, "--missed", "--line", String(entry.line), "--experimental"];
+    ? ["feedback", entry.file, "--rule", entry.rule, "--line", String(entry.line), "--experimental", ...extra]
+    : ["feedback", entry.file, "--missed", "--line", String(entry.line), "--experimental", ...extra];
 
-/** Drafts one report per case and writes the index. Stops, leaving nothing behind, when a draft fails. */
-export const draftReports = (cases) => {
+/**
+ * Drafts one report per case and writes the index. Stops, leaving nothing behind, when a draft fails. `extra` adds
+ * arguments (such as `--genre`), so a draft reproduces the finding under the same measure the check used.
+ */
+export const draftReports = (cases, extra = []) => {
   if (existsSync(DRAFT)) fail(`${DRAFT} already exists in this folder: it may be the person's own draft, so move it away first`);
   const supported = runChaff(["--help"]).stdout.includes("chaff feedback");
   mkdirSync(DIR, { recursive: true });
@@ -30,7 +33,7 @@ export const draftReports = (cases) => {
   };
   const drafted = supported
     ? cases.map((entry) => {
-        const run = runChaff(argsFor(entry));
+        const run = runChaff(argsFor(entry, extra));
         if (run.code !== 0 || !existsSync(DRAFT)) undo(`chaff feedback did not draft ${entry.id}:\n${run.stderr || run.stdout}`);
         const draft = join(DIR, `${entry.id}.md`);
         renameSync(DRAFT, draft);

package/blueprints/docs/checks/places.mjs

@@ -24,13 +24,17 @@ function japaneseName(label, own, above, article) {
   return `${above}第${label ?? levels.at(-1)}号`;
 }
 
+// A heading is quoted the way its own language quotes: 「」 when it holds kana or kanji, "…" otherwise.
+const JAPANESE = /[\p{Script=Hiragana}\p{Script=Katakana}\p{Script=Han}]/u;
+const quoted = (heading) => (JAPANESE.test(heading) ? `「${heading}」` : `"${heading}"`);
+
 // 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}」`);
+    return label ?? (heading === null ? own : quoted(heading));
   }
   if (above === null) return label ?? own;
   return article?.japanese && own.startsWith(`${article.address}.`) ? japaneseName(label, own, above, article) : `${above} ${label ?? own}`;
@@ -46,7 +50,7 @@ const namesIn = (node, above, 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), 「用意するもの」. */
+/** Every address in a chaff tree, with the name a person reads for it: 第4条第2項, Section 3.2 (a) (i), 「用意するもの」, "Getting started". */
 export const placeNamesIn = (tree) => new Map(namesIn(tree, null, null));
 
 /** The tree of `file` (`chaff tree --format json`); null when chaff cannot read it. */

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.14`) unless `CHAFF_BIN` names another. If it fails, show the person the
+   pinned chaff (`npx -y chaffjs@0.15`) 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/page-renders.sh

@@ -15,12 +15,23 @@ RENDER_LIMIT_SECONDS=60
 work=$(mktemp -d)
 "$chrome" --headless=new --disable-gpu --no-first-run --user-data-dir="$work/profile" --virtual-time-budget=15000 --dump-dom "$url" >"$work/dom.html" 2>/dev/null &
 pid=$!
-trap 'kill "$pid" 2>/dev/null || true; rm -rf "$work"' EXIT
+# Chrome can still be writing its profile when it is stopped, and under set -e a failed rm in this trap would turn a page
+# that rendered into a failed check; the scratch folder is left behind instead.
+trap 'kill "$pid" 2>/dev/null || true; rm -rf "$work" 2>/dev/null || true' EXIT
 waited=0
 until grep -q "</html>" "$work/dom.html" 2>/dev/null || [ "$waited" -ge "$RENDER_LIMIT_SECONDS" ] || ! kill -0 "$pid" 2>/dev/null; do
   sleep 1
   waited=$((waited + 1))
 done
+# A Chrome that crashed before printing the page says nothing about the app: like no Chrome, it cannot judge.
+if ! grep -q "</html>" "$work/dom.html" 2>/dev/null && ! kill -0 "$pid" 2>/dev/null; then
+  status=0
+  wait "$pid" || status=$?
+  if [ "$status" -ne 0 ]; then
+    echo "Chrome ($chrome) exited with status $status before printing the page; could not confirm that $url renders" >&2
+    exit 0
+  fi
+fi
 node -e 'let s="";process.stdin.on("data",(c)=>s+=c).on("end",()=>{
   const body = (s.match(/<body[^>]*>([\s\S]*)<\/body>/i) || [, ""])[1];
   const text = body.replace(/<(script|style|noscript)[\s\S]*?<\/\1>/gi, "").replace(/<[^>]+>/g, " ").replace(/\s+/g, " ").trim();

package/blueprints/firebase/skills/spec/SKILL.md

@@ -15,7 +15,7 @@ directories.
    implication (the collections from `appPurpose`, for example), write your proposal and mark it `（提案）`.
 3. Append both packs' `security/` checklists under a heading "必ず詰める点", unchanged — they are what the later
    steps are held to.
-4. Write in the language the user answered in.
+4. Write in the language the build's prompt says the user reads (without one, the language the user answered in).
 5. Nothing else is built in this step. The next step stops for the user to read this spec before anything is
    created in their cloud account.
 

package/blueprints/from-collection/checks/actions.sh

@@ -8,19 +8,21 @@ file=.blueprint/actions.json
 # The record itself first: a build that got here without the spec check is held to it all the same.
 node --no-warnings "$(dirname "$0")/decisions.mjs"
 [ -s "$file" ] || { echo "no $file: the source has no actions or ingests to handle"; exit 0; }
-# A key for a model call lives in .env (.dev.vars on a Worker); the folder becomes a repository whenever its person adds
-# git, and neither must go with it.
-for secrets in .env .dev.vars; do
-  pattern="/?$(printf '%s' "$secrets" | sed 's/\./\\./g')(\*)?"
+# A key for a model call lives in .env (.dev.vars on a Worker, supabase/functions/.env for Supabase's functions); the
+# folder becomes a repository whenever its person adds git, and none of them must go with it. A line naming the file
+# alone (.env) ignores it at any depth, as git reads it.
+for secrets in .env .dev.vars supabase/functions/.env; do
+  escape() { printf '%s' "$1" | sed 's/\./\\./g'; }
+  pattern="/?$(escape "$secrets")(\*)?|$(escape "$(basename "$secrets")")(\*)?"
   if [ -f "$secrets" ] && ! grep -qxE "$pattern" .gitignore 2>/dev/null; then
     echo "$secrets exists and .gitignore does not ignore it; add a line $secrets to .gitignore before anything secret goes in" >&2
     exit 1
   fi
 done
 case "$base" in
-  local|cloudflare) tests="test/actions.test.ts" ;;
+  local|cloudflare|supabase) tests="test/actions.test.ts" ;;
   firebase) tests="test/blueprint/actions.spec.ts" ;;
-  *) echo "usage: actions.sh local|firebase|cloudflare" >&2; exit 2 ;;
+  *) echo "usage: actions.sh local|firebase|cloudflare|supabase" >&2; exit 2 ;;
 esac
 # The titles of the tests the file really declares — parsed, so a name in a comment or a string is not a test. Only read
 # when something is to be built.
@@ -47,6 +49,6 @@ process.stdout.write(String(entries.filter((entry) => entry.decision === "featur
 ' "$file" "$tests" "$titles")
 [ "$features" -gt 0 ] || exit 0
 case "$base" in
-  local|cloudflare) sh "$BLUEPRINT_BASE/checks/tests-pass.sh" actions ;;
+  local|cloudflare|supabase) sh "$BLUEPRINT_BASE/checks/tests-pass.sh" actions ;;
   firebase) sh "$BLUEPRINT_BASE/checks/emulator-test.sh" actions ;;
 esac

package/blueprints/from-collection/checks/compare.mjs

@@ -23,12 +23,20 @@ export const isFileField = (spec) => spec.type === "image" || spec.type === "fil
 export const hasValue = (value) => value !== undefined && value !== null && value !== "";
 export const labelOf = (schema, record) => `${schema.primaryKey}=${JSON.stringify(record[schema.primaryKey])}`;
 
+const DATE_TYPES = new Set(["date", "datetime"]);
+
 /**
  * Whether a stored value is the source's. `booleanAs` says how the store holds a boolean — 0/1 in SQLite, itself in
- * Firestore; a number is compared as a number, anything else as its text.
+ * Firestore; a number is compared as a number, anything else as its text. `datesAsInstants` is for a store that keeps
+ * dates as dates and writes them back in its own format (Postgres: 2026-01-02 as 2026-01-02T00:00:00Z): a date is then
+ * compared as the moment it names.
  */
-export function sameValue(type, sourceValue, stored, booleanAs) {
+export function sameValue(type, sourceValue, stored, booleanAs, datesAsInstants = false) {
   if (type === "number") return Number(sourceValue) === Number(stored);
+  if (datesAsInstants && DATE_TYPES.has(type)) {
+    const [source, back] = [Date.parse(String(sourceValue)), Date.parse(String(stored))];
+    if (!Number.isNaN(source) && !Number.isNaN(back)) return source === back;
+  }
   const want = type === "boolean" ? booleanAs(sourceValue === true) : sourceValue;
   return String(want) === String(stored);
 }
@@ -47,18 +55,20 @@ export const pointedAtFiles = () => [
   ),
 ];
 
-// A SQL store (SQLite, D1): the table is the collection's slug with `-` as `_`, a column is the field's key, and a
-// boolean is held as 0/1 (spec/conversion.md).
+// A SQL store: the table is the collection's slug with `-` as `_`, and a column is the field's key (spec/conversion.md).
+// How a value is held differs by store: SQLite and D1 keep a boolean as 0/1 and a date as its text; Postgres keeps both
+// as themselves.
 export const tableOf = (slug) => slug.replaceAll("-", "_");
-const asColumn = (flag) => (flag ? 1 : 0);
+export const SQLITE_STORE = { booleanAs: (flag) => (flag ? 1 : 0), datesAsInstants: false };
+export const POSTGRES_STORE = { booleanAs: (flag) => flag, datesAsInstants: true };
 
 // `at` is where the value sits: the collection, the record and its label, and how a missing file is told.
 function columnProblems(at, key, spec, row) {
-  const { slug, record, label, fileMissing } = at;
+  const { slug, record, label, fileMissing, store } = at;
   const value = record[key];
   if (!hasValue(value)) return [];
   if (!(key in row)) return [`${slug}: table ${tableOf(slug)} has no column ${key}`];
-  const problems = sameValue(spec.type, value, row[key], asColumn)
+  const problems = sameValue(spec.type, value, row[key], store.booleanAs, store.datesAsInstants)
     ? []
     : [`${slug} ${label}: ${key} is ${JSON.stringify(row[key])}, the source had ${JSON.stringify(value)}`];
   const missing = isFileField(spec) && existsSync(`${SOURCE}/files/${value}`) && fileMissing(value);
@@ -69,9 +79,9 @@ function columnProblems(at, key, spec, row) {
  * The rows of a collection's table held against its records: as many rows as records, and every stored field of every
  * record reads back equal. `rows` is every row of the table, or null when there is no such table. `fileMissing(path)`
  * says where a file the source holds is missing from ("not in data/files/"), or false when it is there; a store whose
- * files are checked elsewhere leaves it out.
+ * files are checked elsewhere leaves it out. `store` is how the store holds its values (SQLITE_STORE, POSTGRES_STORE).
  */
-export function tableProblems(slug, rows, fileMissing = () => false) {
+export function tableProblems(slug, rows, fileMissing = () => false, store = SQLITE_STORE) {
   const table = tableOf(slug);
   if (rows === null) return [`${slug}: there is no table ${table}`];
   const schema = schemaOf(slug);
@@ -83,7 +93,7 @@ export function tableProblems(slug, rows, fileMissing = () => false) {
   const perRecord = records.flatMap((record) => {
     const row = byKey.get(String(record[primary]));
     if (!row) return [`${slug}: no row for ${primary} = ${JSON.stringify(record[primary])}`];
-    return plainFields(schema).flatMap(([key, spec]) => columnProblems({ slug, record, label: labelOf(schema, record), fileMissing }, key, spec, row));
+    return plainFields(schema).flatMap(([key, spec]) => columnProblems({ slug, record, label: labelOf(schema, record), fileMissing, store }, key, spec, row));
   });
   return [...counted, ...perRecord];
 }

package/blueprints/from-collection/checks/import-supabase.sh

@@ -0,0 +1,35 @@
+#!/bin/sh
+# The records the build copied are in Postgres, and the files they point at in Storage — read back through the Supabase
+# CLI, not through the app. `local`: the local database is reset to the migrations and the seed, `yarn import-source
+# --local` runs twice, then the stack is read. `linked`: production is read through the person's supabase login (the
+# step itself did the import, after its approval). A build that copied only the shape has nothing to move.
+set -eu
+target="$1"
+here="$(dirname "$0")"
+source=.blueprint/source/source.json
+[ -s "$source" ] || { echo "missing $source; the build was started without a collection" >&2; exit 1; }
+if [ "$(node -e 'process.stdout.write(String(JSON.parse(require("fs").readFileSync(process.argv[1], "utf8")).records === true))' "$source")" != true ]; then
+  echo "only the shape was copied; there are no records to move"
+  exit 0
+fi
+grep -q '"import-source"' package.json || { echo "package.json has no import-source script" >&2; exit 1; }
+case "$target" in
+  local)
+    . "$BLUEPRINT_BASE/checks/local-stack.sh"
+    seeded=$(mktemp)
+    trap 'rm -f "$seeded"' EXIT INT TERM
+    node --no-warnings "$here/supabase-verify.mjs" --local --save-seeded "$seeded"
+    yarn -s import-source --local >/dev/null || { echo "yarn import-source --local failed" >&2; yarn -s import-source --local >&2 || true; exit 1; }
+    # Twice: moving the records again must leave the same rows, not a second copy of each.
+    yarn -s import-source --local >/dev/null || { echo "yarn import-source failed the second time over the same database" >&2; exit 1; }
+    node --no-warnings "$here/supabase-verify.mjs" --local --seeded "$seeded"
+    yarn test >/dev/null || { echo "yarn test fails" >&2; yarn test >&2 || true; exit 1; }
+    ;;
+  linked)
+    node --no-warnings "$here/supabase-verify.mjs" --linked
+    ;;
+  *)
+    echo "usage: import-supabase.sh local|linked" >&2
+    exit 2
+    ;;
+esac