mulmoterminal 7.2.0 → 8.0.0

package/README.md

@@ -183,18 +183,19 @@ than as bytes (files within the session's working directory only):
 **A line after the path is followed.** `src/a.ts:42`, `src/a.ts:42:7` (gcc, clang, `eslint -f unix`,
 stack traces) and `src/a.ts(12,5)` (tsc) are one link. In the pane, and in the Files view, the file
 opens as text with the caret on that line and column — an HTML page, an SVG or a table included, and a
-tab reading in Preview switches to Edit. A route that renders the file in a new tab (`.md`, `.json`,
+tab reading in Preview switches to Edit. An image, a PDF, a video or an audio file has no line to go
+to and simply opens as itself. A route that renders the file in a new tab (`.md`, `.json`,
 `.csv`, `.html` with no cell enlarged) ignores the line. When the pane beside an enlarged cell takes
 the click, the keyboard stays in the terminal; the full-screen Files view, with no terminal beside it,
 puts it in the editor. (ESLint's default output puts the path on a line of its own, with no line number to follow.)
 
 **While a grid cell is enlarged, the [Files pane](#files-view-browse--edit) takes the click first** — every
-row above except PDF, video and audio, since the pane is the same editor with a Preview for
-Markdown, HTML and SVG, and shows an image as a picture. The file opens *beside* the terminal
+row above, since the pane is the same editor with a Preview for Markdown, HTML and SVG, shows an
+image as a picture and a PDF in a frame, and plays a video or an audio file with the browser's own
+controls (seeking included, whatever the file's size). The file opens *beside* the terminal
 that printed it, and the pane opens itself if it was closed. It declines, leaving the routing
-above untouched, when nothing is enlarged, when the path is not under that cell's own directory
-(the pane cannot walk above its root), or for a PDF, a video or an audio file, which only a
-browser tab can play.
+above untouched, when nothing is enlarged, or when the path is not under that cell's own directory
+(the pane cannot walk above its root). A file too large to edit as text still offers **Open in OS**.
 
 Highlighting in the Files view covers the JS/TS family, JSON and Markdown (the modes
 `cmEditor.ts` bundles); other languages open as plain text.
@@ -823,7 +824,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. |
+| `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`**; Settings → **Sessions and background tasks** has the box (or 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
@@ -1058,6 +1059,20 @@ they came from. It also names the keys it **dropped** (a color that isn't `#rrgg
 of range) and the keys it doesn't read at all (`badgeColour`, a global-only setting) — which is
 what tells "I never set that" apart from "I set it and it didn't take".
 
+**Changing it there.** Under the values, **Change here** is a form for the name, the seven chrome
+colors, how the header shows a running session (`headerStatusTint`) and its colour per status
+(`headerStatusColors`), the terminal theme and palette (`colors`), font size, font family, grid priority, the model its
+sessions start on (`provider` / `model`), the closing summary (`appendSystemPrompt`) and extra
+directories (`addDirs`), its icon, terminal background, and attention sounds (`sound` / `sounds`), and its header buttons,
+chips and command-palette entries (`buttons` / `chips` / `commands`) with the same editors the global
+lists use, its Skill menu (`skills`, in order), Mulmo menu decks (`decks`) and per-worktree variables
+(`worktreeEnv`) — every key the file can hold. **This checkout only** moves a key into
+`.mulmoterminal.local.json` (and **Share** moves it back). A cell's path menu has **This directory's
+settings**, which opens Settings on that directory. Each change is written to
+the directory's file at once and applies without a restart; **Use global** takes the key out
+again. A key `.mulmoterminal.local.json` already holds is written there. Keys the form doesn't
+show are left as they are, and a file that isn't a JSON object is not touched — fix it in Files.
+
 ---
 
 ## Running
@@ -1342,11 +1357,13 @@ or changed (amber), and a notch where lines were removed, as VS Code's gutter sh
 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
+**HTML pages, images, PDFs, video and audio 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
+while a relative stylesheet or script does not. An `.svg` previews as the picture it draws, a PNG, JPEG, GIF or WebP opens as the image
+rather than as "not text", a PDF opens in a frame, and a video or audio file plays with the
+browser's controls, seeking by range rather than fetching the whole file. A text file too large to edit
+says so and still offers **Open in OS**. 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.
 
@@ -2080,6 +2097,7 @@ From a shell: `mulmoterminal room read <room>` · `room post <room> <text…> [-
 | -------- | ------- |
 | `GET\|POST /api/config` | User UI config (`cwdPresets`, `soundFile`, `soundKinds`, `sounds`, `prRepos`, `launchers`, `quickCommands`, `userMcpServers`, `providers`). |
 | `GET /api/sound?kind=` · `/api/dir-sound?cwd=&kind=` · `/api/sound-preset/:id` · `/api/dir-config?cwd=` | Custom / per-directory / preset attention sound + per-dir config. `kind` selects a config entry, never a path. |
+| `PUT /api/dir-config` | The Settings form's save: `{ cwd, set: { key: value }, unset: [key] }` for the keys the form edits (`common/dirConfigForm.ts`), each validated like the Files pane's editor. Other keys and their order are kept; a file that isn't a JSON object answers 422 and is not written. Answers with the new `dir-config-detail`. |
 | `GET /api/dir-config-detail?cwd=` | The same per-dir config, **plus** the settings a running terminal doesn't need (`provider`, `model`, `skills`, `addDirs`, header button/chip **labels**), **plus** which keys the file set and how each fared (applied / dropped in validation / not a setting at all). Read-only; backs the Settings modal's **Directory settings** preview. Unlike the other `?cwd=` routes this one does **not** fall back to the default workspace — it reports on the directory it was asked about, so a path that no longer exists comes back as `exists:false`. Sound paths and button commands stay server-side. |
 | `GET /api/launch-options` | The Anthropic-compatible backends this server can reach, each with its models and — when it can't — the reason. Reports the **name** of the env var a key is read from, never the key. |
 | `GET /api/update-status` | What is running and whether anything newer exists: `install` (`npm` / `git`), `version`, `commit` (a checkout's short HEAD sha), `latest` (npm, only when newer) and the one-line `notice`. Backs the header's **Update** badge and the Settings version line. Served from memory, recomputed at startup and every 3 hours — a long-running server started with `npx mulmoterminal@latest` is current when it starts, so only a later check can tell it a release shipped. `ready` is false until the first check lands. |

package/blueprints/adopt/checks/adopt.mjs

@@ -0,0 +1,106 @@
+// The adopt usecase's two checks. `survey`: .blueprint/adopt.json records the genre the person chose and how many
+// findings chaff reports on the places today, measured again here; nothing in the repository has changed yet.
+// `apply`: chaff.yaml names that genre and keeps what it had, .chaff-baseline.json shelves today's findings so chaff
+// now reports none, and the workflow — when asked for — reports only what is new, with no more rights than that.
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { fromBase } from "./base.mjs";
+import { placesIn, workflowProblems } from "./setup.mjs";
+const { actionable, fail, findingsIn, readJson, runChaff } = await import(fromBase("chaff.mjs"));
+const { lostLines } = await import(fromBase("config.mjs"));
+
+const RECORD = ".blueprint/adopt.json";
+const READABLE = ".blueprint/adopt.txt";
+const CHECKED = ".blueprint/.adopt-checked";
+const CONFIG = "chaff.yaml";
+const BASELINE = ".chaff-baseline.json";
+const WORKFLOW = ".github/workflows/chaff.yml";
+const WITH_CI = "GitHub の PR に指摘を出すワークフローを作る";
+
+const answers = readJson(".blueprint/answers.json", "the interview answers");
+const { places, refused } = placesIn(answers.places);
+if (refused.length > 0) fail(`these places are outside this folder: ${refused.join(", ")}`);
+if (places.length === 0) fail("the answer names no place to check");
+const absent = places.filter((place) => !existsSync(place));
+if (absent.length > 0) fail(`not in this folder: ${absent.join(", ")}`);
+const kinds = JSON.parse(readFileSync(join(process.env.BLUEPRINT_USECASE, "kinds.json"), "utf8")).kinds;
+const genre = kinds.find((kind) => kind.option === answers.kind)?.genre;
+if (!genre) fail(`the answer kind ${JSON.stringify(answers.kind)} is not one of the kinds in kinds.json`);
+
+const textOrNull = (file) => (existsSync(file) ? readFileSync(file, "utf8") : null);
+const findingsNow = (extra) => places.flatMap((place) => findingsIn(place, extra).filter(actionable));
+const byRule = (findings) =>
+  Object.entries(findings.reduce((counts, finding) => ({ ...counts, [finding.rule]: (counts[finding.rule] ?? 0) + 1 }), {})).sort(
+    ([a, x], [b, y]) => y - x || a.localeCompare(b),
+  );
+
+const survey = () => {
+  const record = readJson(RECORD, '{ "genre", "findings" }');
+  const measured = findingsNow(["--genre", genre]);
+  if (record?.genre !== genre) fail(`${RECORD}: "genre" must be ${genre}, the genre of the kind the person chose`);
+  if (record?.findings !== measured.length) fail(`${RECORD}: "findings" is ${record?.findings}, but chaff reports ${measured.length} as ${genre} now`);
+  writeFileSync(
+    READABLE,
+    [`genre: ${genre}`, `findings: ${measured.length}`, ...byRule(measured).map(([rule, count]) => `  ${rule}: ${count}`), ""].join("\n"),
+  );
+  writeFileSync(CHECKED, JSON.stringify({ config: textOrNull(CONFIG), workflow: existsSync(WORKFLOW), findings: measured.length }) + "\n");
+  console.log(`${measured.length} finding(s) today as ${genre}`);
+};
+
+const recorded = () => {
+  try {
+    return JSON.parse(readFileSync(CHECKED, "utf8"));
+  } catch {
+    return null;
+  }
+};
+
+const workflowSide = (checked) => {
+  if (answers.ci === WITH_CI) {
+    if (!existsSync(WORKFLOW)) return [`${WORKFLOW} is missing`];
+    const template = readFileSync(join(process.env.BLUEPRINT_USECASE, "templates", "chaff.yml"), "utf8");
+    return workflowProblems(readFileSync(WORKFLOW, "utf8"), template, places).map((problem) => `${WORKFLOW}: ${problem}`);
+  }
+  return !checked.workflow && existsSync(WORKFLOW) ? [`${WORKFLOW} was added, but the person chose no workflow`] : [];
+};
+
+const apply = () => {
+  const checked = existsSync(CHECKED) ? recorded() : null;
+  if (checked === null || typeof checked !== "object") fail("the survey step's record is missing: run that step again");
+  if (!existsSync(CONFIG)) fail(`${CONFIG} is missing`);
+  const run = runChaff(["rules", "--json"]);
+  if (run.code !== 0) fail(`chaff could not load ${CONFIG}:\n${run.stderr}`);
+  const detected = JSON.parse(run.stdout).detected?.genre;
+  const baseline = existsSync(BASELINE) ? readJson(BASELINE, '{ "entries" }') : null;
+  const left = findingsNow([]);
+  // The shelf is the survey's, taken under this chaff.yaml: shown with what it shelves, chaff reports what was measured.
+  const shelved = findingsNow(["--show-baseline"]);
+  const problems = [
+    ...(detected === genre ? [] : [`${CONFIG} gives genre ${detected}, not ${genre}`]),
+    ...lostLines(checked.config, readFileSync(CONFIG, "utf8"), ["genre"]).map((line) => `${CONFIG} lost a line it had: ${line.trim()}`),
+    ...(baseline === null ? [`${BASELINE} is missing: run chaff baseline on the places`] : []),
+    ...(baseline !== null && (baseline.entries?.length ?? 0) < checked.findings
+      ? [`${BASELINE} shelves ${baseline.entries?.length ?? 0} finding(s), fewer than the ${checked.findings} measured`]
+      : []),
+    ...(shelved.length === checked.findings
+      ? []
+      : [
+          `with its baseline shown, chaff reports ${shelved.length} finding(s) under ${CONFIG}, not the ${checked.findings} measured: the settings or the shelf are not the ones the person approved`,
+        ]),
+    ...(left.length === 0
+      ? []
+      : [
+          `chaff still reports ${left.length} finding(s) the baseline does not shelve: ${byRule(left)
+            .map(([rule, count]) => `${rule} ${count}`)
+            .join(", ")}`,
+        ]),
+    ...workflowSide(checked),
+  ];
+  if (problems.length > 0) fail(problems.join("\n"));
+  console.log(`chaff is set up: today's ${checked.findings} finding(s) shelved, only new ones will be reported`);
+};
+
+const mode = process.argv[2];
+if (mode === "survey") survey();
+else if (mode === "apply") apply();
+else fail(`usage: adopt.mjs survey | apply (got ${JSON.stringify(mode)})`);

package/blueprints/adopt/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/adopt/checks/report.mjs

@@ -0,0 +1,22 @@
+// The report tells the person what was set up and how chaff behaves from now on: it names chaff.yaml, the baseline,
+// and the workflow when one was made.
+import { existsSync, readFileSync } from "node:fs";
+import { fromBase } from "./base.mjs";
+const { fail, readJson } = await import(fromBase("chaff.mjs"));
+const { missingSections } = await import(fromBase("markdown.mjs"));
+
+const REPORT = ".blueprint/adopt-report.md";
+const WITH_CI = "GitHub の PR に指摘を出すワークフローを作る";
+
+if (!existsSync(REPORT)) fail(`${REPORT} is missing`);
+const text = readFileSync(REPORT, "utf8");
+const missing = missingSections(text, [
+  ["入れたもの", "What was set up"],
+  ["棚に上げた指摘", "Shelved findings"],
+  ["これから", "From now on"],
+]);
+if (missing.length > 0) fail(`${REPORT} lacks sections: ${missing.join(", ")}`);
+const ci = readJson(".blueprint/answers.json", "the interview answers").ci === WITH_CI;
+const named = ["chaff.yaml", ".chaff-baseline.json", ...(ci ? [".github/workflows/chaff.yml"] : [])].filter((file) => !text.includes(file));
+if (named.length > 0) fail(`${REPORT} does not name: ${named.join(", ")}`);
+console.log("the report names what was set up");

package/blueprints/adopt/checks/setup.d.mts

@@ -0,0 +1,4 @@
+// Types for setup.mjs, which the pack runs with plain node and the specs import.
+export declare const placesIn: (answer: unknown) => { places: string[]; refused: string[] };
+export declare const workflowFor: (template: string, places: readonly string[]) => string;
+export declare const workflowProblems: (workflow: string, template: string, places: readonly string[]) => string[];

package/blueprints/adopt/checks/setup.mjs

@@ -0,0 +1,47 @@
+// What adopting chaff in a folder of documents has to leave behind: the places chaff watches, and the workflow that
+// reports on them. The workflow is the pack's template filled in with the places, exactly: a workflow is judged
+// by being that one known file, not by reading arbitrary YAML for what might be unsafe in it.
+import { posix } from "node:path";
+
+// A place goes into the workflow's command line unquoted, so only characters with no meaning to a shell are allowed:
+// letters and digits of any script, and . _ - / — never a leading - (it would read as an option).
+const SAFE = /^[\p{L}\p{N}._/-]+$/u;
+
+/** The places the answer names, one a line, as paths inside this folder; a line that leaves it or is unsafe is `refused`. */
+export const placesIn = (answer) => {
+  const lines = String(answer ?? "")
+    .split("\n")
+    .map((line) => line.trim())
+    .filter((line) => line !== "");
+  const inside = (line) => {
+    const path = posix.normalize(line.replaceAll("\\", "/"));
+    if (posix.isAbsolute(path) || /^[A-Za-z]:/u.test(path) || path === ".." || path.startsWith("../")) return null;
+    const trimmed = path.replace(/\/$/u, "") || ".";
+    return SAFE.test(trimmed) && !trimmed.startsWith("-") ? trimmed : null;
+  };
+  return {
+    places: [...new Set(lines.map(inside).filter((path) => path !== null))],
+    refused: lines.filter((line) => inside(line) === null),
+  };
+};
+
+/** The workflow the pack writes for `places`: its template with the places in the chaff run. */
+export const workflowFor = (template, places) => String(template).replace("{{PATHS}}", places.join(" "));
+
+// Line endings and trailing spaces aside (a line's trailing \r goes with its spaces): an editor's habits are not a different workflow.
+const normalized = (text) =>
+  String(text)
+    .split("\n")
+    .map((line) => line.trimEnd())
+    .join("\n")
+    .trimEnd();
+
+/** What is wrong with `workflow`: anything but the template filled in with `places`. */
+export const workflowProblems = (workflow, template, places) => {
+  if (normalized(workflow) === normalized(workflowFor(template, places))) return [];
+  const expected = normalized(workflowFor(template, places)).split("\n");
+  const actual = normalized(workflow).split("\n");
+  const at = expected.findIndex((line, index) => actual[index] !== line);
+  const line = at < 0 ? expected.length + 1 : at + 1;
+  return [`it is not the pack's template filled in with the places (first difference at line ${line}): copy the template again`];
+};

package/blueprints/adopt/hearing.json

@@ -0,0 +1,42 @@
+{
+  "questions": [
+    {
+      "id": "places",
+      "label": "chaff に見させる文書（このフォルダの中のフォルダかファイルを 1 行に 1 つ）",
+      "why": "ここにある文書の今の指摘を棚に上げ、以後はここの新しい指摘だけが出る",
+      "kind": "text",
+      "lines": true,
+      "pick": "files"
+    },
+    {
+      "id": "kind",
+      "label": "どんな文書ですか",
+      "why": "文書の種類ごとの物差し（文の長さの上限、どの検査を動かすか）で chaff が測る",
+      "kind": "select",
+      "options": [
+        "手順書・ヘルプ・マニュアル",
+        "README・開発者向けの説明",
+        "仕様書・設計書",
+        "よくある質問",
+        "用語集",
+        "技術ブログ",
+        "会社のサイトの記事（オウンドメディア）",
+        "報告書・社内文書",
+        "提案書・企画書",
+        "議事録",
+        "プレスリリース・お知らせ",
+        "契約書・利用規約",
+        "規程・社内規則",
+        "論文"
+      ]
+    },
+    {
+      "id": "ci",
+      "label": "GitHub の PR に指摘を出しますか",
+      "why": "作ると、PR を出すたびに chaff が動き、新しい指摘がその行に出る",
+      "kind": "select",
+      "options": ["GitHub の PR に指摘を出すワークフローを作る", "作らない（手元で npx chaffjs を動かす）"],
+      "needsPath": { "GitHub の PR に指摘を出すワークフローを作る": ".git" }
+    }
+  ]
+}

package/blueprints/adopt/kinds.json

@@ -0,0 +1,18 @@
+{
+  "kinds": [
+    { "option": "手順書・ヘルプ・マニュアル", "genre": "docs/manual" },
+    { "option": "README・開発者向けの説明", "genre": "technical/readme" },
+    { "option": "仕様書・設計書", "genre": "technical/spec" },
+    { "option": "よくある質問", "genre": "docs/faq" },
+    { "option": "用語集", "genre": "docs/glossary" },
+    { "option": "技術ブログ", "genre": "blog/tech" },
+    { "option": "会社のサイトの記事（オウンドメディア）", "genre": "blog/owned-media" },
+    { "option": "報告書・社内文書", "genre": "business/report" },
+    { "option": "提案書・企画書", "genre": "business/proposal" },
+    { "option": "議事録", "genre": "business/meeting-notes" },
+    { "option": "プレスリリース・お知らせ", "genre": "business/press-release" },
+    { "option": "契約書・利用規約", "genre": "legal/contract" },
+    { "option": "規程・社内規則", "genre": "legal/statute" },
+    { "option": "論文", "genre": "academic/paper" }
+  ]
+}

package/blueprints/adopt/manifest.json

@@ -0,0 +1,9 @@
+{
+  "slug": "adopt",
+  "kind": "usecase",
+  "title": "文書のフォルダに chaff を入れる（今ある指摘は棚に上げて）",
+  "version": "0.1.0",
+  "description": "既にある文書のフォルダに chaff を入れる。文書の種類に合わせた chaff.yaml を置き、今ある指摘は chaff baseline で棚に上げて、新しい指摘だけが出るようにする。望めば、GitHub の PR の行に指摘が出るワークフローも作る。原本は変えない。",
+  "bases": ["docs"],
+  "report": ".blueprint/adopt-report.md"
+}

package/blueprints/adopt/presets/help-pages/export.md

@@ -0,0 +1,9 @@
+# データを書き出す
+
+## CSV で書き出す
+
+一覧の画面の右上にある「書き出し」を押して「CSV」を選ぶと、いま表示している条件で絞り込んだ行だけが、文字コードが UTF-8 のファイルとしてダウンロードされるので、表計算ソフトで開くときは文字コードを指定してください。
+
+## 書き出せないとき
+
+一度に書き出せるのは 10,000 行までです。それより多いときは、期間を分けて書き出してください。

package/blueprints/adopt/presets/help-pages/login.md

@@ -0,0 +1,9 @@
+# ログインできないとき
+
+## パスワードを忘れたとき
+
+ログイン画面の「パスワードを忘れた方」を押し、登録しているメールアドレスを入れると、パスワードを設定し直すためのリンクが届くので、そのリンクを開いて新しいパスワードを二回入れてから「保存」を押してください。
+
+## アカウントがロックされたとき
+
+パスワードを5回続けて間違えると、アカウントが30分ロックされます。30分たってから、もう一度ログインしてください。

package/blueprints/adopt/presets.json

@@ -0,0 +1,15 @@
+{
+  "presets": [
+    {
+      "id": "help-pages",
+      "title": "ヘルプのページに chaff を入れる",
+      "description": "見本のヘルプ（login.md と export.md）を「手順書・ヘルプ・マニュアル」として測り、今ある長すぎる文の指摘を棚に上げて、以後は新しい指摘だけが出るようにする。GitHub の PR に指摘を出すワークフローも作る。原本は変えない。",
+      "base": "docs",
+      "answers": {
+        "places": "login.md\nexport.md",
+        "kind": "手順書・ヘルプ・マニュアル",
+        "ci": "GitHub の PR に指摘を出すワークフローを作る"
+      }
+    }
+  ]
+}

package/blueprints/adopt/skills/apply/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: blueprint-adopt-apply
+description: "Set chaff up in the folder: chaff.yaml for the chosen genre, today's findings shelved in .chaff-baseline.json, and, when asked, a GitHub workflow that puts new findings on the pull request's lines."
+---
+
+# Set chaff up
+
+The person approved the setup in `.blueprint/adopt.json`. The documents stay exactly as they are: fixing what is
+shelved is 「文書を整える」's work, later.
+
+## 1. chaff.yaml
+
+Write the folder's `chaff.yaml` with the genre from `.blueprint/adopt.json` and the documents' `language`
+(`npx chaffjs init --genre <genre>` writes a commented one). If the folder already has one, set its `genre` to the
+chosen one and **keep every other line it has** — the check refuses any other line of the old file that is gone. Add the rule
+levels the person agreed to at the gate, nothing else.
+
+## 2. Shelve today's findings
+
+Run `sh <base pack>/checks/chaff.sh baseline <place> …` with every place. It writes `.chaff-baseline.json` in the
+folder: the findings there today are not reported again; new ones are. Tell the person to commit it with
+`chaff.yaml`.
+
+## 3. The workflow — only when `ci` is 「GitHub の PR に指摘を出すワークフローを作る」
+
+Copy `<usecase pack>/templates/chaff.yml` to `.github/workflows/chaff.yml`, replacing `{{PATHS}}` with the places
+separated by spaces, and change nothing else: the check compares the file with the template filled in that way, line
+for line. Its `permissions:` let the workflow read the documents (`contents: read`) and upload findings
+(`security-events: write`), nothing more. A place whose name has a space or a character a shell reads (`$`, `;`, `*`,
+quotes…) cannot go into the workflow: the interview refuses it, so ask the person to name a folder above it instead. When `ci` is 「作らない」, add nothing under `.github/`.
+
+## 4. The report
+
+Write `.blueprint/adopt-report.md` for the person, in their language and in plain words:
+
+- `## 入れたもの` / `## What was set up` — `chaff.yaml` (the genre, and why), `.chaff-baseline.json`, and the
+  workflow `.github/workflows/chaff.yml` when one was made. The check looks for each file's name.
+- `## 棚に上げた指摘` / `## Shelved findings` — how many were shelved, by rule, in plain words.
+- `## これから` / `## From now on` — only new findings are reported (run `npx chaffjs <places>` by hand, or see them
+  on the pull request's lines); how to lower the shelf later (「文書を整える」, then `chaff baseline` again); that
+  the workflow needs code scanning enabled on the repository (a public repository has it; a private one needs
+  GitHub Advanced Security).
+
+## Done when
+
+`node <usecase pack>/checks/adopt.mjs apply` and then `node <usecase pack>/checks/report.mjs` (with `BLUEPRINT_BASE`
+and `BLUEPRINT_USECASE` set) pass.

package/blueprints/adopt/skills/survey/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: blueprint-adopt-survey
+description: "Measure what chaff reports on the named documents today, as the kind the person chose, and propose the setup — changing nothing yet."
+---
+
+# Measure what is there today
+
+`.blueprint/answers.json` names the places chaff will watch (`places`, a folder or a file a line), what kind of
+documents they are (`kind`) and whether a GitHub workflow is wanted (`ci`). The person may not be an engineer: say
+what you do in plain words.
+
+Change nothing in the repository: this step only measures. The person approves the setup before anything is
+written.
+
+## Measure
+
+The kind maps to a genre in `<usecase pack>/kinds.json`. For each place, run
+`sh <base pack>/checks/chaff.sh <place> --genre <genre> --compact` and count the warnings and errors, by rule. Read a
+few of them: a rule that reports mostly what the documents do on purpose may be worth turning down in `chaff.yaml`
+rather than shelving — say which, and why, for the person to decide at the gate.
+
+## Write `.blueprint/adopt.json`
+
+```json
+{ "genre": "docs/manual", "findings": 2, "proposal": "chaff.yaml に genre と language を書き、今の 2 件を棚に上げる。" }
+```
+
+`findings` is the number of warnings and errors chaff reports on all the places together, as that genre, now; the
+check measures it again. If the folder already has a `chaff.yaml` or a `.chaff-baseline.json`, say so in
+`proposal`: the next step keeps what they hold.
+
+## Done when
+
+`node <usecase pack>/checks/adopt.mjs survey` (with `BLUEPRINT_BASE` and `BLUEPRINT_USECASE` set to the pack folders
+from your prompt) passes. It writes `.blueprint/adopt.txt`, what the person reads before anything changes.

package/blueprints/adopt/steps.json

@@ -0,0 +1,20 @@
+{
+  "steps": [
+    {
+      "id": "survey",
+      "title": "今の指摘を測る",
+      "description": "選んだ種類で、文書に今どれだけ指摘があるかを測り、入れる設定の案を書く。まだ何も変えない。",
+      "skill": "skills/survey",
+      "check": "node \"$BLUEPRINT_USECASE/checks/adopt.mjs\" survey"
+    },
+    {
+      "id": "apply",
+      "title": "chaff を入れる",
+      "description": "chaff.yaml を置き、今の指摘を .chaff-baseline.json に棚上げし、望めば PR に指摘を出すワークフローを足す。以後は新しい指摘だけが出ることを機械で確かめる。",
+      "skill": "skills/apply",
+      "check": "node \"$BLUEPRINT_USECASE/checks/adopt.mjs\" apply && node \"$BLUEPRINT_USECASE/checks/report.mjs\"",
+      "gates": ["review"],
+      "reads": [".blueprint/adopt.txt"]
+    }
+  ]
+}

package/blueprints/adopt/templates/chaff.yml

@@ -0,0 +1,29 @@
+# Checks the documents with chaff on every pull request, and puts each new finding on the line it is about.
+# The findings already in the documents are shelved in .chaff-baseline.json, so only new ones appear.
+name: chaff
+
+on:
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  chaff:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      security-events: write
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          persist-credentials: false
+      - uses: actions/setup-node@v7
+        with:
+          node-version: 24
+      - run: npx -y chaffjs@0.16 {{PATHS}} --sarif chaff.sarif
+        continue-on-error: true
+      - uses: github/codeql-action/upload-sarif@1c5b675653bb5c22dbe9b12b556ec555138e09fd # v4.38.1
+        with:
+          sarif_file: chaff.sarif
+          category: chaff

package/blueprints/compare/checks/articles.d.mts

@@ -0,0 +1,8 @@
+// Types for articles.mjs, which the pack runs with plain node and the specs import.
+export type Article = { readonly address: string; readonly label: string; readonly body: string };
+export type Row = { readonly old?: string | null; readonly new?: string | null; readonly change: string; readonly what?: string };
+
+export declare const CHANGES: readonly string[];
+export declare const articlesIn: (tree: unknown, text: string) => Article[];
+export declare const mentions: (text: string, name: string) => boolean;
+export declare const comparisonProblems: (rows: unknown, olds: readonly Article[], news: readonly Article[]) => string[];