strom-research 1.0.0 → 1.1.0

package/dist/cli/wizard.js

@@ -13,7 +13,8 @@ import { agentsHere, DESKTOP_APPS } from "../core/apps.js";
 import { PROFILES } from "../agents/profiles.js";
 import { writeStored, PERMISSION_LEVELS } from "../core/config.js";
 import { globalTargets, installGlobal } from "../agents/global.js";
-import { noticeStromApp, researchUrl } from "../core/stromapp.js";
+import { noticeStromApp, researchUrl, stromAppState, stromAppUrl } from "../core/stromapp.js";
+import { openForUser } from "../core/open.js";
 import { createShortcut } from "../core/shortcut.js";
 import { desktopDir } from "../core/paths.js";
 import { ensureShared } from "../commands/setup.js";
@@ -24,7 +25,7 @@ export function shortcutName(lang) {
 function shortcutExists(ctx, lang) {
     const dir = desktopDir(ctx.env);
     const name = shortcutName(lang);
-    return [`${name}.command`, `${name}.cmd`, "strom-research.desktop"].some((f) => fs.existsSync(path.join(dir, f)));
+    return [`${name}.command`, `${name}.lnk`, `${name}.cmd`, "strom-research.desktop"].some((f) => fs.existsSync(path.join(dir, f)));
 }
 export async function setupWizard(ctx) {
     const s = ctx.settings;
@@ -42,6 +43,8 @@ export async function setupWizard(ctx) {
             break;
         }
     }
+    // Run again: each choice can be left as it is (0), the current one suggested.
+    const keep = first ? {} : { back: ui(lang, "ui.keep") };
     // 2. Where the research lives.
     const home = ctx.resolvePath(await ctx.ask(ui(lang, "ui.setup.home"), ctx.display(s.home()?.value ?? s.suggestedHome())));
     cfg.lang = lang;
@@ -71,7 +74,7 @@ export async function setupWizard(ctx) {
         agent = installed[0];
     else if (installed.length > 1) {
         const current = Math.max(0, installed.indexOf(cfg.agent ?? "claude"));
-        const i = await ctx.choose(ui(lang, "ui.setup.agent.pick"), installed.map((id) => ({ label: PROFILES[id].name })), current);
+        const i = await ctx.choose(ui(lang, "ui.setup.agent.pick"), installed.map((id) => ({ label: PROFILES[id].name })), current, keep);
         agent = installed[i ?? current];
     }
     if (agent) {
@@ -82,7 +85,7 @@ export async function setupWizard(ctx) {
         if (has.app && has.cli) {
             const app = DESKTOP_APPS[agent].name;
             const current = cfg.agentWhere === "terminal" ? 1 : 0;
-            const i = await ctx.choose(ui(lang, "ui.setup.where"), [{ label: ui(lang, "ui.setup.where.app", { app }) }, { label: ui(lang, "ui.setup.where.terminal", { agent: PROFILES[agent].name }) }], current);
+            const i = await ctx.choose(ui(lang, "ui.setup.where"), [{ label: ui(lang, "ui.setup.where.app", { app }) }, { label: ui(lang, "ui.setup.where.terminal", { agent: PROFILES[agent].name }) }], current, keep);
             cfg.agentWhere = (i ?? current) === 1 ? "terminal" : "app";
         }
     }
@@ -93,18 +96,18 @@ export async function setupWizard(ctx) {
         const models = ["opus", "sonnet", undefined];
         const current = cfg.models?.claude?.lead;
         const suggested = current === undefined ? (first ? 0 : 2) : Math.max(0, models.indexOf(current));
-        const i = await ctx.choose(ui(lang, "ui.setup.model"), [{ label: ui(lang, "ui.setup.model.opus") }, { label: ui(lang, "ui.setup.model.sonnet") }, { label: ui(lang, "ui.setup.model.own") }], suggested);
+        const i = await ctx.choose(ui(lang, "ui.setup.model"), [{ label: ui(lang, "ui.setup.model.opus") }, { label: ui(lang, "ui.setup.model.sonnet") }, { label: ui(lang, "ui.setup.model.own") }], suggested, keep);
         writeStored(cfg, "model.lead", "claude", models[i ?? suggested]);
     }
     else if (agent)
         out(ui(lang, "ui.setup.model.strong", { agent: PROFILES[agent].name }));
     // 5b. Stories of the ancestors for the family book: on unless the person says no.
-    const si = await ctx.choose(ui(lang, "ui.setup.stories"), [{ label: ui(lang, "ui.setup.stories.yes") }, { label: ui(lang, "ui.setup.stories.no") }], cfg.stories === "no" ? 1 : 0);
+    const si = await ctx.choose(ui(lang, "ui.setup.stories"), [{ label: ui(lang, "ui.setup.stories.yes") }, { label: ui(lang, "ui.setup.stories.no") }], cfg.stories === "no" ? 1 : 0, keep);
     cfg.stories = (si ?? (cfg.stories === "no" ? 1 : 0)) === 1 ? "no" : "yes";
     // 6. What the agent may do without asking.
     const now = s.agentPermissions();
     const labels = { ask: ui(lang, "ui.setup.level.ask"), auto: ui(lang, "ui.setup.level.auto"), full: ui(lang, "ui.setup.level.full") };
-    const li = await ctx.choose(ui(lang, "ui.setup.level"), PERMISSION_LEVELS.map((l) => ({ label: labels[l] })), PERMISSION_LEVELS.indexOf(now));
+    const li = await ctx.choose(ui(lang, "ui.setup.level"), PERMISSION_LEVELS.map((l) => ({ label: labels[l] })), PERMISSION_LEVELS.indexOf(now), keep);
     let level = PERMISSION_LEVELS[li ?? PERMISSION_LEVELS.indexOf(now)];
     if (level === "full" && now !== "full") {
         out(ui(lang, "ui.setup.level.warn"));
@@ -127,16 +130,40 @@ export async function setupWizard(ctx) {
     }
     else
         createShortcut(shortcutName(lang), ctx.env);
-    // Quietly: the installed agents learn about strom; the Strom app is noticed.
+    // Quietly: the installed agents learn about strom.
     const taught = new Set();
     for (const t of globalTargets(ctx.env).filter((t) => installed.includes(t.agent)))
         if (installGlobal(t))
             taught.add(t.agent);
     for (const a of taught)
         out(ui(lang, "ui.setup.skill", { agent: PROFILES[a].name }));
-    if (noticeStromApp(s, ctx.env, { look: true }))
+    // 8. The Strom app: noticed when it is here; else asked once whether they want it (pre-filled after).
+    if (noticeStromApp(s, ctx.env, { look: true }) || stromAppState(s) === "seen")
         out(ui(lang, "ui.setup.app"));
+    else
+        await askStromApp(ctx, lang, first ? undefined : ui(lang, "ui.keep"));
     out();
     out(`${ui(lang, "ui.setup.done")}  (${langName(lang, lang)} · ${ctx.display(home)})`);
     return { home, lang, ...(agent ? { agent } : {}), permissions: level };
 }
+/**
+ * Does the person want the Strom app (not found on this computer)? Yes and
+ * install it now: it opens in the browser and strom says where to click; yes
+ * but later; no: strom never mentions it again (strom.app no). Undefined when
+ * not answered or 0 (back) — nothing changes.
+ */
+export async function askStromApp(ctx, lang, back = ui(lang, "ui.browse.back")) {
+    const said = ctx.settings.config.stromApp;
+    const answers = ["install", "later", "no"];
+    const i = await ctx.choose(ui(lang, "ui.setup.stromapp"), [{ label: ui(lang, "ui.setup.stromapp.install") }, { label: ui(lang, "ui.setup.stromapp.later") }, { label: ui(lang, "ui.setup.stromapp.no") }], said === "no" ? 2 : said === "yes" ? 1 : 0, back ? { back } : {});
+    if (i === undefined)
+        return undefined;
+    const answer = answers[i];
+    ctx.settings.config.stromApp = answer === "no" ? "no" : "yes";
+    ctx.settings.save();
+    if (answer === "install") {
+        const url = stromAppUrl(ctx.settings);
+        ctx.io.stdout(ui(lang, openForUser(url, ctx.env) ? "ui.app.install" : "ui.app.url", { url }) + "\n");
+    }
+    return answer;
+}

package/dist/commands/browse.js

@@ -0,0 +1,243 @@
+// stats · pedigree · person card · recent · plan — the tree as a person looks through
+// it (the guided menu's "Look through the family tree"), in the research
+// language. Read only; --json gives the same for a program.
+import { register } from "../cli/registry.js";
+import { lines, table, truncate } from "../cli/format.js";
+import { ui } from "../cli/ui.js";
+import { eventName, generationName, humanCost, humanDate, humanDay, humanPlace, statusName } from "../cli/human.js";
+import { UsageError } from "../core/errors.js";
+import { mainPerson } from "../core/kin.js";
+import { resolvePerson } from "../core/people.js";
+import { knownGenerations, ownerName, pedigree, personCard, recent, treeStats } from "../core/overview.js";
+import { displayName } from "../core/people.js";
+import { lacksImages } from "../core/queue.js";
+import { rankedQueue, waitingForUser } from "./tasks.js";
+/** Most rows a section of `recent` lists; the rest is counted. */
+const RECENT_ROWS = 15;
+function whoText(w) {
+    return w.years ? `${w.name} (${w.years})` : w.name;
+}
+/** The person asked for, else the main person of the tree. */
+function personOrMain(tree, ref) {
+    if (ref)
+        return resolvePerson(tree, ref).id;
+    const main = mainPerson(tree);
+    if (!main)
+        throw new UsageError("this tree has no research yet, so no main person", { hint: 'name one: strom pedigree "<name>"' });
+    return main;
+}
+function positive(value, name, fallback, max) {
+    if (value === undefined)
+        return fallback;
+    const n = Number(value);
+    if (!Number.isInteger(n) || n < 1 || n > max)
+        throw new UsageError(`--${name} must be a whole number from 1 to ${max}`);
+    return n;
+}
+/** A fact as a person reads it: "25. 6. 1905, Týnec nad Labem č. 12 · doloženo — Křest Jana Nováka 1905". */
+function factText(f, lang) {
+    const core = [f.value, humanDate(f.date, lang), humanPlace(f.place, f.house, lang), f.cause].filter(Boolean).join(", ");
+    return `${core ? `${core} · ` : ""}${statusName(f.status, lang)}${f.source ? ` — ${truncate(f.source, 70)}` : ""}`;
+}
+function factRows(facts, lang, indent) {
+    return table(facts.map((f) => [`${indent}${eventName(f.kind, lang, f.label)}`, factText(f, lang)]));
+}
+function drawPedigree(root, lang) {
+    const label = (n) => `${whoText(n.person)}${n.person.proven ? " ✓" : ""}${n.seen ? ` ${ui(lang, "ui.ped.seen")}` : ""}`;
+    const out = [label(root)];
+    const walk = (n, prefix) => {
+        if (!n.father || !n.mother)
+            return;
+        if (!n.father.person && !n.mother.person) {
+            out.push(`${prefix}└─ ? ${ui(lang, "ui.ped.noparents")}`);
+            return;
+        }
+        const parents = [[n.father, "ui.ped.nofather"], [n.mother, "ui.ped.nomother"]];
+        parents.forEach(([p, missing], i) => {
+            const last = i === parents.length - 1;
+            out.push(`${prefix}${last ? "└─ " : "├─ "}${p.person ? label(p) : `? ${ui(lang, missing)}`}`);
+            if (p.person)
+                walk(p, prefix + (last ? "   " : "│  "));
+        });
+    };
+    walk(root, "");
+    return out;
+}
+/** What the agent wrote into a task, for the user: the records it names by ID by their names ("S0001" → its title). */
+export function humanTask(tree, text, lang) {
+    const name = (id) => {
+        const r = tree.get(id);
+        if (!r)
+            return id;
+        if (r.type === "session")
+            return ui(lang, "ui.plan.session", { day: humanDay(r.started, lang) });
+        if (r.type === "person")
+            return displayName(r);
+        if (r.type === "family")
+            return r.partners.map((x) => tree.get(x)).filter((x) => !!x).map(displayName).join(" & ") || id;
+        return r.title;
+    };
+    // A list of IDs as a list of names, each once (two sessions of one day read as one).
+    return text.replace(/\b[PFSBN]\d{4,}\b(?:, [PFSBN]\d{4,}\b)*/g, (ids) => [...new Set(ids.split(", ").map(name))].join(", "));
+}
+function more(n, lang) {
+    return n > 0 ? `  ${ui(lang, "ui.recent.more", { n })}` : undefined;
+}
+register({
+    path: ["stats"],
+    summary: "The research at a glance: people, facts and how sure they are, the ancestors known in each generation, tasks, sessions and their cost",
+    group: "analysis",
+    tree: true,
+    args: [{ name: "person", description: "whose ancestors to count (default: the main person of the tree)" }],
+    examples: ["strom stats", 'strom stats "Jan Novák"'],
+    run(ctx, { args }) {
+        const tree = ctx.tree();
+        const lang = ctx.uiLang();
+        const from = args[0] ? resolvePerson(tree, args[0]).id : mainPerson(tree);
+        const s = treeStats(tree, from);
+        const out = [
+            ui(lang, "ui.stats.title", { name: tree.config.name }),
+            ui(lang, "ui.stats.counts", { persons: s.persons, families: s.families, sources: s.sources, images: s.images, places: s.places }),
+            ui(lang, "ui.stats.facts", s.facts),
+        ];
+        if (s.from) {
+            out.push("", ui(lang, "ui.stats.from", { name: whoText(s.from) }));
+            if (!s.generations.length)
+                out.push(`  ${ui(lang, "ui.stats.noancestors")}`);
+            else
+                out.push(table(s.generations.map((g) => [`  ${generationName(g.generation, lang)}`, ui(lang, "ui.stats.gen", { known: g.known, expected: g.expected, proven: g.proven })])));
+            if (s.oldest)
+                out.push(ui(lang, "ui.stats.oldest", { name: whoText(s.oldest) }));
+        }
+        out.push("", ui(lang, "ui.stats.tasks", s.tasks));
+        if (s.sessions.count)
+            out.push(ui(lang, "ui.stats.sessions", { n: s.sessions.count, last: humanDay(s.sessions.last, lang) }) +
+                (s.sessions.costUsd ? ui(lang, "ui.stats.cost", { cost: humanCost(s.sessions.costUsd, lang) }) : ""));
+        if (s.stories.written)
+            out.push(ui(lang, "ui.stats.stories", { n: s.stories.written, final: s.stories.final }));
+        return { text: lines(...out), data: s };
+    },
+}, {
+    path: ["pedigree"],
+    summary: "The ancestors of a person as a tree, father and mother at each step — who is known, whose birth a record proves, where it ends",
+    group: "analysis",
+    tree: true,
+    args: [{ name: "person", description: "ID (P0001) or name (default: the main person of the tree)" }],
+    options: [{ name: "generations", type: "string", value: "<n>", description: "how many generations, the person included (default 5, at most 12)" }],
+    examples: ["strom pedigree", 'strom pedigree "Jan Novák" --generations 7'],
+    run(ctx, { args, opts }) {
+        const tree = ctx.tree();
+        const lang = ctx.uiLang();
+        const id = personOrMain(tree, args[0]);
+        const generations = positive(opts.generations, "generations", 5, 12);
+        const root = pedigree(tree, id, generations);
+        const known = knownGenerations(tree, id);
+        return {
+            text: lines(...drawPedigree(root, lang), "", ui(lang, "ui.ped.legend"), known > generations ? ui(lang, "ui.ped.more", { n: known, id }) : undefined),
+            data: { generations, known, pedigree: root },
+        };
+    },
+}, {
+    path: ["person", "card"],
+    summary: "One person for the family to read: their life, parents, marriages and children, each fact with how sure it is and its record — and their story",
+    group: "people",
+    tree: true,
+    args: [{ name: "person", description: "ID (P0001) or name", required: true }],
+    examples: ['strom person card "Jan Novák"', "strom person card P0001"],
+    run(ctx, { args }) {
+        const tree = ctx.tree();
+        const lang = ctx.uiLang();
+        const c = personCard(tree, resolvePerson(tree, args[0]));
+        const out = [whoText(c.person)];
+        if (c.otherNames.length)
+            out.push(`  ${ui(lang, "ui.card.also", { names: c.otherNames.join(", ") })}`);
+        out.push(c.facts.length ? factRows(c.facts, lang, "  ") : `  ${ui(lang, "ui.card.nofacts")}`, "");
+        out.push(c.parents.length ? ui(lang, "ui.card.parents", { names: c.parents.map(whoText).join(", ") }) : ui(lang, "ui.card.noparents"));
+        for (const f of c.families) {
+            const key = f.partner?.sex === "F" ? "ui.card.wife" : f.partner?.sex === "M" ? "ui.card.husband" : c.sex === "M" ? "ui.card.wife" : c.sex === "F" ? "ui.card.husband" : "ui.card.partner";
+            out.push(ui(lang, key, { name: f.partner ? whoText(f.partner) : ui(lang, "ui.card.unknown") }));
+            if (f.facts.length)
+                out.push(factRows(f.facts, lang, "  "));
+            if (f.children.length)
+                out.push(`  ${ui(lang, "ui.card.children", { names: f.children.map(whoText).join(", ") })}`);
+        }
+        if (c.story) {
+            const text = c.story.text.replace(/\*\*/g, "").trim();
+            out.push("", ui(lang, "ui.card.story", { status: ui(lang, c.story.status === "final" ? "ui.card.story.final" : "ui.card.story.draft") }));
+            // markdown headings as plain lines
+            out.push(text.split("\n").map((l) => (l.trim() ? `  ${l.trim().replace(/^#+\s*/, "")}` : "")).join("\n"));
+        }
+        return { text: lines(...out), data: c };
+    },
+}, {
+    path: ["plan"],
+    summary: "What the agent will do next, for the user: the first tasks of the queue in its order, what waits for scans, the stories after them",
+    group: "tasks",
+    tree: true,
+    options: [{ name: "count", type: "string", value: "<n>", description: "how many tasks (default 10)" }],
+    examples: ["strom plan", "strom plan --count 20"],
+    run(ctx, { opts }) {
+        const tree = ctx.tree();
+        const lang = ctx.uiLang();
+        const count = positive(opts.count, "count", 10, 200);
+        // The order of a conversation (the story's turn is only for working alone).
+        const queue = rankedQueue(tree, { strategy: ctx.settings.strategy(tree.config) }).map((r) => r.task);
+        const work = queue.filter((t) => t.level !== "narrate");
+        const stories = queue.filter((t) => t.level === "narrate");
+        const waiting = waitingForUser(tree).length;
+        const shown = work.slice(0, count);
+        let n = 0;
+        const rows = shown.map((t) => [
+            `  ${t.state === "doing" ? ui(lang, "ui.plan.now") : `${++n}.`}`,
+            `${truncate(humanTask(tree, t.what, lang), 110)}${lacksImages(tree, t) ? ui(lang, "ui.plan.images") : ""}`,
+        ]);
+        const storyNames = [...new Set(stories.map((t) => tree.get(t.subject[0] ?? "")).filter((p) => !!p).map(displayName))];
+        const out = [ui(lang, "ui.plan.title", { name: tree.config.name })];
+        if (!queue.length)
+            out.push(`  ${ui(lang, "ui.plan.none")}`);
+        else {
+            if (rows.length)
+                out.push(table(rows));
+            if (work.length > count)
+                out.push(`  ${ui(lang, "ui.plan.more", { n: work.length - count })}`);
+            if (stories.length)
+                out.push(ui(lang, "ui.plan.stories", { n: stories.length, names: storyNames.join(", ") }));
+        }
+        if (waiting)
+            out.push(ui(lang, "ui.plan.waiting", { n: waiting }));
+        if (queue.length)
+            out.push("", ui(lang, "ui.plan.steer"));
+        const item = (t) => ({ id: t.id, what: humanTask(tree, t.what, lang), level: t.level, state: t.state, needsImages: lacksImages(tree, t) });
+        return { text: lines(...out), data: { tasks: work.map(item), stories: stories.map(item), waiting } };
+    },
+}, {
+    path: ["recent"],
+    summary: "What came in lately: new people, facts added or refined, records, stories, and what the agent did in its sessions",
+    group: "analysis",
+    tree: true,
+    options: [{ name: "days", type: "string", value: "<n>", description: "how many days back (default 7)" }],
+    examples: ["strom recent", "strom recent --days 30"],
+    run(ctx, { opts }) {
+        const tree = ctx.tree();
+        const lang = ctx.uiLang();
+        const days = positive(opts.days, "days", 7, 3660);
+        const r = recent(tree, new Date(Date.now() - days * 86_400_000).toISOString());
+        const since = humanDay(r.since, lang);
+        const refined = r.facts.filter((f) => f.refined).length;
+        if (!r.persons.length && !r.facts.length && !r.sources.length && !r.stories.length && !r.sessions.length && !r.tasksDone)
+            return { text: ui(lang, "ui.recent.nothing", { since }), data: { days, ...r } };
+        const out = [
+            ui(lang, "ui.recent.title", { since }),
+            ui(lang, "ui.recent.counts", { persons: r.persons.length, facts: r.facts.length - refined, refined, sources: r.sources.length, stories: r.stories.length, done: r.tasksDone }),
+        ];
+        if (r.persons.length)
+            out.push("", ui(lang, "ui.recent.persons"), ...r.persons.slice(0, RECENT_ROWS).map((p) => `  ${whoText(p)}`), more(r.persons.length - RECENT_ROWS, lang));
+        if (r.facts.length)
+            out.push("", ui(lang, "ui.recent.facts"), ...r.facts.slice(0, RECENT_ROWS).map((f) => `  ${ownerName(tree, f.owner)} – ${eventName(f.fact.kind, lang, f.fact.label)}: ${factText(f.fact, lang)}${f.refined ? ` (${ui(lang, "ui.recent.refined")})` : ""}`), more(r.facts.length - RECENT_ROWS, lang));
+        if (r.stories.length)
+            out.push("", ui(lang, "ui.recent.stories"), ...r.stories.map((p) => `  ${whoText(p)}`));
+        if (r.sessions.length)
+            out.push("", ui(lang, "ui.recent.sessions"), ...r.sessions.slice(0, RECENT_ROWS).map((s) => `  ${humanDay(s.at, lang)} – ${[s.task, s.summary ? truncate(s.summary, 220) : undefined].filter(Boolean).join(": ")}`), more(r.sessions.length - RECENT_ROWS, lang));
+        return { text: lines(...out), data: { days, ...r } };
+    },
+});

package/dist/commands/clips.js

@@ -0,0 +1,190 @@
+// strom clips — mark where the entries already read are on their scans, for
+// sources that have none (read before clips existed, or brought in from an
+// older research): readers find each entry on its image, strom cuts it out, a
+// second look checks the cut-out; what passes becomes the source's clip. Run
+// again, it takes up only what is still missing.
+import fs from "node:fs";
+import path from "node:path";
+import { register } from "../cli/registry.js";
+import { lines, truncate } from "../cli/format.js";
+import { UsageError } from "../core/errors.js";
+import { normId, requireRecord, update } from "../core/records.js";
+import { makeView, VIEW_MAX } from "../core/views.js";
+import { clipText, MAX_CLIPS, regionText } from "../core/media.js";
+import { withMargin } from "../core/excerpt.js";
+import { batches } from "../core/reader.js";
+import { checkPrompt, locatePrompt, parseChecked, parseLocated, widen } from "../core/clipfinder.js";
+import { displayName } from "../core/people.js";
+import { readers } from "./readers.js";
+import { verifyFast } from "../core/integrity.js";
+import { pool } from "./read.js";
+/** Entries per reader: each is one image (sometimes two) the reader looks at. */
+const PER_READER = 10;
+/** How many times a cut-out found cut off is cut out wider and checked again. */
+const WIDER = 2;
+/** Who a source names: the people whose facts cite it. */
+export function namesIn(tree, id) {
+    const out = new Set();
+    for (const p of tree.list("person"))
+        if (p.events.some((e) => e.citations.some((c) => c.source === id)) || p.names.some((n) => n.citations?.some((c) => c.source === id)))
+            out.add(displayName(p));
+    for (const f of tree.list("family"))
+        if (f.events.some((e) => e.citations.some((c) => c.source === id)) || f.citations?.some((c) => c.source === id))
+            for (const id2 of f.partners) {
+                const p = tree.get(id2);
+                if (p)
+                    out.add(displayName(p));
+            }
+    return [...out].slice(0, 8);
+}
+register({
+    path: ["clips"],
+    summary: "Mark where entries already read are on their scans (sources without clips): readers find them, a second look checks",
+    group: "sources",
+    tree: true,
+    writes: true,
+    lock: "sections",
+    description: "For sources on images that have no clip yet — read before clips existed, or brought in from an older research.\n" +
+        "A reader finds each entry on its image (its words and the people it names are given), strom cuts it out, and a\n" +
+        "second reader checks the cut-out shows that entry whole: only then it becomes the source's clip (for the Strom app's\n" +
+        "excerpts: output/tree-strom.ged, strom app). Paid model work, about two looks per entry: --dry-run says how many first.\n" +
+        "Run again, it takes up only what is still missing. It waits for its readers: run it in the foreground.",
+    args: [{ name: "sources", description: "only these sources (S…); default every source on images without a clip", variadic: true }],
+    options: [
+        { name: "recordset", type: "string", value: "<B…>", description: "only the sources of this book" },
+        { name: "limit", type: "string", value: "<n>", description: "at most this many sources this time" },
+        { name: "again", type: "boolean", description: "also the sources that have clips (found again, replaced when the check passes)" },
+        { name: "batch", type: "string", value: "<n>", description: `entries per reader (default ${PER_READER})` },
+        { name: "parallel", type: "string", value: "<n>", description: "readers at the same time (default 3)" },
+        { name: "model", type: "string", value: "<model>", description: "model of the readers (default: model.vision — it reads the handwriting to find the entry)" },
+        { name: "minutes", type: "string", value: "<n>", description: "time limit of one reader (default 15)" },
+    ],
+    examples: ["strom clips --dry-run", "strom clips --recordset B0001 --limit 20", "strom clips S0001 S0002"],
+    run: async (ctx, { args, opts }) => {
+        const tree = ctx.tree();
+        const shared = ctx.settings.shared()?.value;
+        if (!shared)
+            throw new UsageError("no shared folder with the images is set", { hint: "strom setup" });
+        const all = new Map(tree.list("media").map((m) => [m.id, m]));
+        const only = new Set(args.map((a) => requireRecord(tree, normId(a), "source").id));
+        const book = typeof opts.recordset === "string" ? normId(opts.recordset) : undefined;
+        const imageOf = (id) => {
+            const m = all.get(id);
+            return m && /^image\/(jpeg|png)$/.test(m.mime) && fs.existsSync(path.join(shared, m.file)) ? m : undefined;
+        };
+        let todo = tree
+            .list("source")
+            .filter((s) => !s.retracted && s.media?.length && (only.size ? only.has(s.id) : true))
+            .filter((s) => (book ? s.recordset === book || s.media.some((m) => all.get(m)?.recordset === book) : true))
+            .filter((s) => opts.again || !s.clips?.length);
+        const away = todo.filter((s) => !s.media.some((m) => imageOf(m)));
+        todo = todo.filter((s) => s.media.some((m) => imageOf(m)));
+        const limit = opts.limit === undefined ? undefined : Number(opts.limit);
+        if (limit !== undefined && !(Number.isInteger(limit) && limit > 0))
+            throw new UsageError("--limit must be a positive number");
+        if (limit)
+            todo = todo.slice(0, limit);
+        const size = opts.batch === undefined ? PER_READER : Number(opts.batch);
+        if (!Number.isInteger(size) || size < 1)
+            throw new UsageError("--batch must be a positive number");
+        const groups = batches(todo, size);
+        if (!todo.length)
+            return { text: lines("nothing to do: every source on images has its clip", away.length ? `${away.length} source(s) on images not on this computer (or not JPEG/PNG)` : undefined), data: { sources: 0 } };
+        if (tree.dryRun)
+            return {
+                text: lines(`${todo.length} source(s) to find on their images — ${groups.length} reader(s) to find them, as many to check`, away.length ? `${away.length} more on images not on this computer (or not JPEG/PNG)` : undefined, "(dry run — no reader started)"),
+                data: { sources: todo.length, readers: groups.length, away: away.map((s) => s.id) },
+            };
+        const r0 = readers(ctx, tree, shared, "clips", "find", opts);
+        const { model, parallel, reportsDir, failed, progress } = r0;
+        const reader = r0.read;
+        // 1. Find: each image whole, with a grid, and what the entry says.
+        const byId = new Map(todo.map((s) => [s.id, s]));
+        const found = await pool(groups, parallel, async (group, k) => {
+            const jobs = group.map((s) => ({
+                source: s.id,
+                title: s.title,
+                facts: [
+                    s.locator || s.date ? `where: ${[s.locator, s.date ? `recorded ${s.date}` : ""].filter(Boolean).join("; ")}` : "",
+                    namesIn(tree, s.id).length ? `people in it: ${namesIn(tree, s.id).join(", ")}` : "",
+                ].filter(Boolean),
+                words: s.transcript ? truncate(s.transcript.replace(/\s+/g, " "), 400) : undefined,
+                images: s.media.flatMap((id) => {
+                    const m = imageOf(id);
+                    return m ? [{ media: m.id, view: makeView(tree, path.join(shared, m.file), m.id, { grid: true, max: VIEW_MAX }).file }] : [];
+                }),
+            }));
+            progress(`▶ finding ${k + 1}/${groups.length}: ${group.map((s) => s.id).join(" ")}`);
+            const r = await reader(`find-${k + 1}`, jobs.flatMap((j) => j.images.map((i) => i.view)), `Where the entries are · batch ${k + 1} of ${groups.length}`, (report) => locatePrompt(jobs, report));
+            const located = parseLocated(r.text).filter((l) => byId.get(l.source)?.media?.includes(l.media));
+            progress(`■ finding ${k + 1}: ${r.outcome} · ${located.filter((l) => l.result === "found").length} found`);
+            return located;
+        });
+        const locs = found.flat();
+        const hits = locs.filter((l) => l.result === "found" && !!l.region);
+        // 2. Check: the cut-out as the Strom app will show it. Cut off: wider on those sides, and checked again.
+        const check = async (list, round) => {
+            const checks = list.map((l) => {
+                const m = all.get(l.media);
+                const s = byId.get(l.source);
+                return {
+                    source: l.source,
+                    media: l.media,
+                    title: s.title,
+                    words: s.transcript ? truncate(s.transcript.replace(/\s+/g, " "), 400) : undefined,
+                    view: makeView(tree, path.join(shared, m.file), m.id, { crop: regionText(withMargin(l.region)) }).file,
+                };
+            });
+            const checkGroups = batches(checks, size);
+            const name = (k) => (round ? `check${round + 1}-${k + 1}` : `check-${k + 1}`);
+            return (await pool(checkGroups, parallel, async (group, k) => {
+                progress(`▶ checking${round ? ` again (${round + 1})` : ""} ${k + 1}/${checkGroups.length}: ${group.length} cut-outs`);
+                const r = await reader(name(k), group.map((g) => g.view), `Checking the cut-outs${round ? `, cut out wider` : ""} · batch ${k + 1} of ${checkGroups.length}`, (report) => checkPrompt(group, report));
+                const v = parseChecked(r.text);
+                progress(`■ checking ${k + 1}: ${r.outcome} · ${v.filter((x) => x.verdict === "ok").length} ok`);
+                return v;
+            })).flat();
+        };
+        const verdicts = [];
+        let open = hits;
+        for (let round = 0; open.length && round <= WIDER; round++) {
+            const got = await check(open, round);
+            const key = (x) => `${x.source} ${x.media}`;
+            const cut = new Map(got.filter((v) => v.verdict === "cut").map((v) => [key(v), v]));
+            const last = round === WIDER;
+            verdicts.push(...got.filter((v) => v.verdict !== "cut" || last));
+            open = last ? [] : open.filter((l) => cut.has(key(l))).map((l) => ({ ...l, region: widen(l.region, cut.get(key(l)).missing) }));
+            hits.splice(0, hits.length, ...hits.filter((h) => !open.some((o) => key(o) === key(h))), ...open);
+        }
+        const passed = new Set(verdicts.filter((v) => v.verdict === "ok").map((v) => `${v.source} ${v.media}`));
+        // 3. What passed becomes the source's clips.
+        const clipsOf = new Map();
+        for (const l of hits)
+            if (passed.has(`${l.source} ${l.media}`))
+                clipsOf.set(l.source, [...(clipsOf.get(l.source) ?? []), { media: l.media, region: l.region }].slice(0, MAX_CLIPS));
+        for (const [id, clips] of clipsOf)
+            update(tree, id, "source", (s) => ({ ...s, clips }), { op: "source.edit", summary: `${id} clips ${clips.map(clipText).join(" ")} (found by a reader, checked)` });
+        // The reports are working notes of the research: committed with it.
+        if (verifyFast(tree).findings.every((f) => f.level !== "error"))
+            tree.withTreeLock(() => tree.commit(`Clips: ${clipsOf.size} of ${todo.length} entries marked on their scans`, [tree.relative(reportsDir)]));
+        const rejected = verdicts.filter((v) => v.verdict !== "ok");
+        // a search over many entries, not one entry: no clip, and said so
+        const many = [...new Set(locs.filter((l) => l.result === "many").map((l) => l.source))];
+        const missed = todo.filter((s) => !clipsOf.has(s.id));
+        const text = lines(`${clipsOf.size} of ${todo.length} source(s) got their clip${model ? ` · ${model}` : ""}${r0.cost() ? ` · $${r0.cost().toFixed(2)}` : ""}`, many.length ? `not one entry but a search over many (no clip — a page of it would show nothing): ${many.join(", ")}` : undefined, rejected.length ? `the check turned down: ${rejected.map((v) => `${v.source} (${v.verdict}${v.why ? `: ${truncate(v.why, 40)}` : ""})`).join(", ")}` : undefined, missed.length ? `without a clip: ${missed.map((s) => s.id).slice(0, 20).join(", ")}${missed.length > 20 ? ` … (${missed.length})` : ""} — strom source edit S… --clip M…@x,y,w,h, or strom clips again` : undefined, away.length ? `on images not on this computer (or not JPEG/PNG): ${away.length}` : undefined, failed.length ? `readers that failed: ${failed.join(", ")}` : undefined, "the entries cut out for the Strom app: strom app (output/tree-strom.ged)");
+        return {
+            text,
+            data: {
+                sources: todo.length,
+                clipped: [...clipsOf.keys()],
+                rejected,
+                many,
+                missed: missed.map((s) => s.id),
+                away: away.map((s) => s.id),
+                failed,
+                costUsd: r0.cost() || undefined,
+            },
+            exitCode: failed.length ? 1 : 0,
+        };
+    },
+});