strom-research 1.0.0

package/dist/commands/start.js

@@ -0,0 +1,383 @@
+// How a person starts: the guided menu, a conversation with the agent set up
+// the way they chose, the Strom app, the shortcut on the desktop, and teaching
+// the agents about strom in any folder.
+import fs from "node:fs";
+import path from "node:path";
+import { configDir, userHome } from "../core/paths.js";
+import { prependPath, spawnAgent } from "../runners/runner.js";
+import { register } from "../cli/registry.js";
+import { lines } from "../cli/format.js";
+import { ui } from "../cli/ui.js";
+import { StromError, UsageError } from "../core/errors.js";
+import { PROFILES } from "../agents/profiles.js";
+import { conversationArgs } from "../agents/launch.js";
+import { globalTargets, installGlobal, isInstalled, uninstallGlobal } from "../agents/global.js";
+import { syncAgentFiles } from "../agents/files.js";
+import { AGENTS, findAgent, isAgent } from "../core/which.js";
+import { DESKTOP_APPS, agentsHere, whereToTalk } from "../core/apps.js";
+import { assertIntact } from "../core/integrity.js";
+import { browserConnectors } from "../core/connector.js";
+import { appOpensResearch, importAppUrl, installedStromApp, liveAppUrl, noticeStromApp, STROM_APP_URL, stromAppUrl } from "../core/stromapp.js";
+import { liveRunning, serveLive, startLive, stopLive } from "../core/live.js";
+import { openForUser } from "../core/open.js";
+import { createShortcut, openInNewTerminal } from "../core/shortcut.js";
+import { chromiumBrowser, openFileWith, openInBrowser, revealFile } from "../core/chromium.js";
+import { uninstallPlan } from "../core/uninstall.js";
+import { Tree } from "../core/tree.js";
+import { commitNow, shimDir } from "./session.js";
+import { abandonedSessions, closeSession, openSessions } from "../core/session.js";
+import { enterWorker, liveWorkers } from "../core/workers.js";
+import { phrase } from "../core/phrases.js";
+import { writeGedcoms, writeTreeGed } from "./output.js";
+import { shortcutName } from "../cli/wizard.js";
+/** Has the user trusted this folder in Claude Code already? (Its own record, read only.) */
+function claudeTrusts(root, env) {
+    const file = env.CLAUDE_CONFIG_DIR ? path.join(env.CLAUDE_CONFIG_DIR, ".claude.json") : path.join(userHome(env), ".claude.json");
+    try {
+        const projects = JSON.parse(fs.readFileSync(file, "utf8")).projects ?? {};
+        const real = fs.realpathSync(root);
+        return Boolean(projects[root]?.hasTrustDialogAccepted || projects[real]?.hasTrustDialogAccepted);
+    }
+    catch {
+        return false;
+    }
+}
+/** An argument as a shell would need it (for --print). */
+function shellQuote(a) {
+    return /^[\w./:=@,+-]+$/.test(a) ? a : `'${a.replace(/'/g, "'\\''")}'`;
+}
+/** Wait for a child that has the terminal. */
+function waitFor(child) {
+    return new Promise((resolve) => {
+        child.on("error", () => resolve(127));
+        child.on("close", (code) => resolve(code ?? 1));
+    });
+}
+register({
+    path: ["chat"],
+    summary: "Talk with the AI agent about the research — in its desktop app or in this terminal, set up the way you chose",
+    group: "start",
+    tree: true,
+    description: "The default way to research: the agent works in the tree folder with the tree's permissions and your level\n" +
+        "(agent.permissions: ask, auto, full), your model, and asks you what matters. Where you talk (agent.where): the\n" +
+        "agent's desktop app when it is installed (Claude, ChatGPT/Codex, OpenCode — the tree folder and the first message\n" +
+        "filled in; you confirm the folder and send it), else its CLI in this terminal (Claude Code, Codex, Antigravity,\n" +
+        "OpenCode). The first message is yours to give (--say); without it the agent reports where things\n" +
+        "stand and suggests what next.",
+    options: [
+        { name: "say", type: "string", value: "<text>", description: "your first message to the agent" },
+        { name: "print", type: "boolean", description: "print the command line instead of starting the agent" },
+    ],
+    examples: ["strom chat", 'strom chat --say "Find the baptism of Karel"', "strom chat --agent codex", "strom chat --print"],
+    run: async (ctx, { opts }) => {
+        // An agent strom started (a conversation, a run) is where the research happens already. Any other
+        // agent — the one that set strom up from the web page, one opened in some folder — hands the
+        // research over: its own conversation, opened where it lives (the tree folder, its permissions).
+        const agentHere = isAgent(ctx.env);
+        if (agentHere && (ctx.env.STROM_WORKER || ctx.env.STROM_SESSION) && !opts.print)
+            throw new UsageError("strom chat opens a conversation for the user — you are in one already", { hint: "go on with strom here" });
+        const tree = ctx.tree();
+        assertIntact(tree);
+        const lang = tree.lang;
+        const agent = ctx.settings.agent(tree.config).value;
+        const profile = PROFILES[agent];
+        if (!profile)
+            throw new UsageError(`strom chat does not know agent "${agent}"`, { hint: `${Object.keys(PROFILES).join(", ")} — strom agents use claude` });
+        const where = whereToTalk(agent, ctx.settings.agentWhere(), ctx.env);
+        const program = findAgent(profile.command, ctx.env);
+        if (!program && where === "terminal" && !opts.print)
+            throw new StromError(ui(lang, "ui.chat.agent.missing", { agent: profile.name }), { hint: `strom setup — or install it: ${profile.url}` });
+        const files = syncAgentFiles(tree);
+        if (files.length)
+            tree.withTreeLock(() => tree.commit(`Agent instructions: ${files.join(", ")}`, files));
+        const shared = ctx.settings.shared()?.value;
+        const researches = tree.list("research");
+        const kickoff = typeof opts.say === "string" && opts.say.trim() ? opts.say.trim() : ui(lang, researches.length ? "ui.chat.continue" : "ui.chat.first");
+        const level = ctx.settings.agentPermissions();
+        // In the agent's desktop app: a link opens a conversation in the tree folder with the first
+        // message filled in. The app reads the tree's instructions and permissions itself; the level of
+        // a Claude app is the person's pick in the app (it cannot be set from outside), so strom says which.
+        if (where === "app") {
+            const app = DESKTOP_APPS[agent];
+            const link = app.link(tree.root, kickoff);
+            if (opts.print)
+                return { text: link, data: { app: app.name, link, cwd: tree.root } };
+            const opened = openForUser(link, ctx.env);
+            const say = [opened ? ui(lang, "ui.chat.app.open", { app: app.name }) : ui(lang, "ui.chat.app.closed", { app: app.name, dir: ctx.display(tree.root), message: kickoff })];
+            if (agent === "claude" && level !== "ask")
+                say.push(ui(lang, level === "full" ? "ui.chat.app.full" : "ui.chat.app.auto"));
+            // Claude's app takes the model from the tree's settings; the others' the person picks there.
+            if (agent !== "claude")
+                say.push(ui(lang, "ui.chat.app.model", { app: app.name }));
+            if (agentHere && opened)
+                say.push(ui(lang, "ui.chat.handover.end"));
+            return { text: say.join("\n"), data: { agent, app: app.name, link, opened, ...(agentHere ? { handover: "app" } : {}) } };
+        }
+        // In a terminal: a new window, not a conversation inside this one.
+        if (agentHere && !opts.print) {
+            const say = typeof opts.say === "string" && opts.say.trim() ? ["--say", opts.say.trim()] : [];
+            const opened = openInNewTerminal(["chat", "--agent", agent, ...say], tree.root, ctx.env);
+            return { text: ui(lang, opened ? "ui.chat.handover" : "ui.chat.handover.failed", { agent: profile.name }), data: { agent, handover: opened ? "window" : "none", cwd: tree.root } };
+        }
+        const base = {
+            kickoff,
+            level,
+            model: ctx.settings.models(agent, tree.config).lead,
+            settingsFile: path.join(tree.root, ".claude", "settings.json"),
+            // Found again in Claude Code's list of sessions (/resume) and the terminal's title: the family,
+            // its research when there is one, the day.
+            name: ["Strom", tree.config.name, researches.length === 1 ? researches[0].name : undefined, new Date().toLocaleDateString(lang, { day: "numeric", month: "numeric" })].filter(Boolean).join(" · "),
+            shared,
+            ...(agent === "claude" ? { chrome: browserConnectors(ctx.env, shared).length > 0 } : {}),
+        };
+        const args = conversationArgs(agent, base);
+        if (opts.print)
+            return { text: [program ?? profile.command, ...args].map(shellQuote).join(" "), data: { command: program ?? profile.command, args, cwd: tree.root } };
+        // Other agents may work in this tree too: this one gets a name of its own, is present while it
+        // works, and has its own session. Sessions of conversations that ended without closing are closed.
+        for (const s of abandonedSessions(Tree.open(tree.root, ctx.env))) {
+            const t = Tree.open(tree.root, ctx.env);
+            closeSession(t, s, { summary: phrase(t.lang, "session.chat"), next: "", interrupted: true, endedBy: "chat" });
+            commitNow(t, `${s.id} interrupted: its conversation had ended`);
+        }
+        const worker = `${agent}-${process.pid}-${Date.now().toString(36)}`;
+        const leave = enterWorker(tree.root, worker, `${profile.name} conversation`);
+        ctx.io.stdout(ui(lang, "ui.chat.open", { agent: profile.name, exit: profile.exit }) + "\n");
+        // Claude Code asks once whether the folder is to be trusted — its own safety step, kept; the user knows what to answer.
+        if (agent === "claude" && !claudeTrusts(tree.root, ctx.env))
+            ctx.io.stdout(ui(lang, "ui.chat.trust") + "\n");
+        const env = { ...prependPath(ctx.env, shimDir(tree)), STROM_WORKER: worker };
+        let code;
+        try {
+            const started = Date.now();
+            code = await waitFor(spawnAgent(profile.command, args, { cwd: tree.root, env, stdio: "inherit" }));
+            // A Claude Code without the auto mode (an older one, or a plan without it) stops at once: go on in its own mode.
+            if (code !== 0 && agent === "claude" && level === "auto" && Date.now() - started < 5000)
+                code = await waitFor(spawnAgent(profile.command, conversationArgs(agent, { ...base, level: "ask" }), { cwd: tree.root, env, stdio: "inherit" }));
+        }
+        finally {
+            leave();
+        }
+        // A session the agent left open goes back: its task returns to the queue.
+        for (const s of openSessions(Tree.open(tree.root, ctx.env)).filter((x) => x.worker === worker)) {
+            const t = Tree.open(tree.root, ctx.env);
+            closeSession(t, s, { summary: phrase(t.lang, "session.chat"), next: "", interrupted: true, endedBy: "chat" });
+        }
+        // What the conversation recorded goes into the results at once.
+        const after = Tree.open(tree.root, ctx.env);
+        writeGedcoms(ctx, after);
+        commitNow(after, "Results after a conversation with the agent");
+        return { text: "", data: { agent, exitCode: code } };
+    },
+});
+register({
+    path: ["app"],
+    summary: "Open the Strom app (the family tree app) — the installed one, else in the browser",
+    group: "output",
+    description: "In a tree, with an app that can take it (from its version 3.0.0), the app opens this research itself — the first time as\n" +
+        "a new tree, after that the same tree updated — and follows it while somebody is at work on it (the live bridge).\n" +
+        `Otherwise the results are ready for it in output/tree-strom.ged (in the app: Import). Web: ${STROM_APP_URL}`,
+    options: [{ name: "live", type: "boolean", description: "the app follows this research while it goes on (the live bridge)" }],
+    examples: ["strom app", "strom app --live", "strom app install"],
+    run(ctx, { opts }) {
+        const lang = ctx.uiLang();
+        const root = appOpensResearch(ctx.env) ? ctx.locateTree() : undefined;
+        if (root) {
+            const tree = Tree.open(root, ctx.env);
+            const name = tree.config.name;
+            // Followed while somebody is at work on it: an agent strom started, or the agent asking for it now.
+            const follow = Boolean(opts.live) || liveWorkers(root).length > 0 || isAgent(ctx.env);
+            // The file as the research is now: the installed app takes it, or the user drags it in.
+            const file = writeTreeGed(tree, { for: "strom", stromVersion: ctx.settings.stromVersion(tree.config) }).file;
+            // B, D: the app reaches strom on this computer — in a Chromium browser, never whatever is the default (Safari cannot).
+            const browser = chromiumBrowser(ctx.env);
+            if (browser) {
+                // The bridge serves the tree's GEDCOM to the app; it ends by itself when nobody asks it anything.
+                const info = startLive(root, ctx.env);
+                if (!info)
+                    throw new StromError("the bridge did not start", { hint: "strom live serve shows why" });
+                const url = follow ? liveAppUrl(info.url, ctx.env) : importAppUrl(`${info.url}/tree.ged`, ctx.env);
+                const opened = openInBrowser(browser, url, ctx.env);
+                const text = opened ? ui(lang, follow ? "ui.app.following" : "ui.app.research", { name, where: browser.name }) : ui(lang, "ui.app.url", { url });
+                return { text, data: { opened, via: "browser", browser: browser.name, url, bridge: info.url, follow } };
+            }
+            // A: no such browser to hand it over, but the Strom app installed from one takes the file itself (its
+            // file handler) — not when strom is pointed at another copy of the app (STROM_APP_URL: a beta, a development one).
+            const installed = installedStromApp(ctx.env);
+            if (!follow && !ctx.env.STROM_APP_URL && installed && /Chrome|Edge|Brave|Chromium|Vivaldi/.test(installed.kind) && openFileWith(installed.path, file, ctx.env))
+                return { text: ui(lang, "ui.app.research", { name, where: installed.kind }), data: { opened: true, via: "file", file, app: installed.path, follow } };
+            // C: no such browser — the app opens, the file is shown, the user drags it into the app's window.
+            openForUser(installed?.path ?? stromAppUrl(ctx.env), ctx.env);
+            const shown = revealFile(file, ctx.env);
+            return {
+                text: lines(follow ? ui(lang, "ui.app.nolive") : undefined, ui(lang, "ui.app.drag", { file: ctx.display(file), shown: shown ? ui(lang, "ui.app.drag.shown") : "" })),
+                data: { opened: shown, via: "drag", file, follow },
+            };
+        }
+        if (opts.live) {
+            const info = startLive(ctx.tree().root, ctx.env);
+            if (!info)
+                throw new StromError("the bridge did not start", { hint: "strom live serve shows why" });
+            const url = liveAppUrl(info.url, ctx.env);
+            const opened = openForUser(url, ctx.env);
+            return { text: opened ? ui(lang, "ui.app.opened", { where: ui(lang, "ui.app.browser") }) : ui(lang, "ui.app.url", { url }), data: { opened, url, bridge: info.url } };
+        }
+        const app = noticeStromApp(ctx.settings, ctx.env, { look: true }) ?? installedStromApp(ctx.env);
+        const opened = openForUser(app?.path ?? stromAppUrl(ctx.env), ctx.env);
+        const text = opened ? ui(lang, "ui.app.opened", { where: app ? app.kind : ui(lang, "ui.app.browser") }) : ui(lang, "ui.app.url", { url: stromAppUrl(ctx.env) });
+        return { text, data: { opened, url: stromAppUrl(ctx.env), ...(app ? { installed: app } : {}) } };
+    },
+}, {
+    path: ["live"],
+    summary: "The live bridge: the Strom app follows this research while it goes on (read only, this computer only)",
+    group: "output",
+    tree: true,
+    description: "A small web server on this computer only (127.0.0.1, a secret address), that only reads: the Strom app, opened with\n" +
+        "strom app --live, takes the tree from it and hears what changes — who is at work on what, what was recorded, what\n" +
+        "waits for the user. It ends by itself when nobody asks it anything for two hours, or with strom live stop.",
+    examples: ["strom live", "strom live start", "strom live stop"],
+    run(ctx) {
+        const tree = ctx.tree();
+        const info = liveRunning(tree.root);
+        return info
+            ? { text: lines(`the bridge runs: ${info.url}`, `  the Strom app following it: ${liveAppUrl(info.url, ctx.env)}`, "  stop: strom live stop"), data: { running: true, ...info, app: liveAppUrl(info.url, ctx.env) } }
+            : { text: "the bridge does not run — strom live start (or strom app --live)", data: { running: false } };
+    },
+}, {
+    path: ["live", "start"],
+    summary: "Start the live bridge in the background (or say where it runs)",
+    group: "output",
+    tree: true,
+    run(ctx) {
+        const tree = ctx.tree();
+        const info = startLive(tree.root, ctx.env);
+        if (!info)
+            throw new StromError("the bridge did not start", { hint: "strom live serve shows why" });
+        return { text: lines(`the bridge runs: ${info.url}`, `  the Strom app following it: ${liveAppUrl(info.url, ctx.env)}`), data: { ...info, app: liveAppUrl(info.url, ctx.env) } };
+    },
+}, {
+    path: ["live", "stop"],
+    summary: "Stop the live bridge",
+    group: "output",
+    tree: true,
+    run(ctx) {
+        const stopped = stopLive(ctx.tree().root);
+        return { text: stopped ? "the bridge stopped" : "no bridge ran", data: { stopped } };
+    },
+}, {
+    path: ["live", "serve"],
+    summary: "Run the live bridge here, in the foreground (strom live start runs it in the background)",
+    group: "output",
+    tree: true,
+    async run(ctx) {
+        const tree = ctx.tree();
+        await serveLive(tree.root, ctx.env);
+        return { text: "the bridge ended", data: {} };
+    },
+}, {
+    path: ["app", "install"],
+    summary: "Help install the Strom app: it opens in the browser and strom says where to click",
+    group: "output",
+    run(ctx) {
+        const lang = ctx.uiLang();
+        const app = installedStromApp(ctx.env);
+        if (app) {
+            noticeStromApp(ctx.settings, ctx.env, { look: true });
+            const opened = openForUser(app.path, ctx.env);
+            return { text: ui(lang, "ui.app.installed", { kind: app.kind }), data: { installed: app, opened } };
+        }
+        const opened = openForUser(stromAppUrl(ctx.env), ctx.env);
+        return { text: opened ? ui(lang, "ui.app.install") : ui(lang, "ui.app.url", { url: stromAppUrl(ctx.env) }), data: { installed: false, opened, url: stromAppUrl(ctx.env) } };
+    },
+});
+register({
+    path: ["agents", "install"],
+    summary: "Teach the installed AI agents about strom in any folder (a Claude Code skill, a note in the others' instructions) and let them run it without asking",
+    group: "setup",
+    description: "Done by the setup already. A user who opens their agent anywhere and asks about their family gets an agent that knows\nstrom is there. The user's own text in those files is kept; strom agents uninstall takes it away again.",
+    options: [{ name: "all", type: "boolean", description: "also for agents not installed yet" }],
+    run(ctx, { opts }) {
+        const installed = agentsHere(ctx.env).map((a) => a.id);
+        // One file may serve two agents: written once.
+        const seen = new Set();
+        const rows = globalTargets(ctx.env)
+            .filter((t) => (opts.all || installed.includes(t.agent)) && !seen.has(`${t.kind}:${t.file}`) && seen.add(`${t.kind}:${t.file}`))
+            .map((t) => ({ agent: t.agent, file: t.file, written: installGlobal(t) }));
+        const text = rows.length
+            ? lines(...rows.map((r) => `${PROFILES[r.agent].name}: ${ctx.display(r.file)}${r.written ? "" : " (already there)"}`))
+            : "no AI agent installed — strom setup offers one";
+        return { text, data: { agents: rows } };
+    },
+}, {
+    path: ["agents", "uninstall"],
+    summary: "Take strom's note out of the AI agents' own instructions again",
+    group: "setup",
+    run(ctx) {
+        const rows = globalTargets(ctx.env)
+            .filter((t) => isInstalled(t))
+            .map((t) => ({ agent: t.agent, file: t.file, removed: uninstallGlobal(t) }))
+            .filter((r) => r.removed);
+        return { text: rows.length ? lines(...rows.map((r) => `${PROFILES[r.agent].name}: removed from ${ctx.display(r.file)}`)) : "nothing to remove", data: { agents: rows } };
+    },
+}, {
+    path: ["uninstall"],
+    summary: "Take strom off this computer: what the agents were taught, the shortcut, its own git, its PATH lines and the program — the research and the settings stay",
+    group: "setup",
+    description: "The user's decision: a person at their terminal is asked there (--yes: no question); asked by an agent, strom asks\n" +
+        "in a window of the system. Installed through npm, the program itself goes with npm uninstall -g strom-research.",
+    examples: ["strom uninstall"],
+    async run(ctx) {
+        const lang = ctx.uiLang();
+        const plan = uninstallPlan(ctx.env, ["en", "cs", "de"].map(shortcutName));
+        const label = (r) => ui(lang, `ui.uninstall.${r.kind}`, { agent: r.agent ?? "" });
+        const home = ctx.settings.home()?.value;
+        const keeps = ui(lang, "ui.uninstall.keeps", { home: home ? ctx.display(home) : "—", config: ctx.display(configDir(ctx.env)) });
+        if (!plan.remove.length)
+            return { text: lines(ui(lang, "ui.uninstall.nothing"), plan.npm ? ui(lang, "ui.uninstall.npm") : undefined, keeps), data: { removed: [], npm: plan.npm } };
+        const list = plan.remove.map((r) => `  ${label(r)}: ${ctx.display(r.path)}`);
+        if (isAgent(ctx.env) || !ctx.yes) {
+            if (!isAgent(ctx.env) && ctx.interactive) {
+                ctx.io.stdout(`${lines(ui(lang, "ui.uninstall.list"), ...list, "", keeps)}
+`);
+                if (!(await ctx.confirm(ui(lang, "ui.uninstall.sure"), false)))
+                    return { text: ui(lang, "ui.uninstall.kept"), data: { removed: [] } };
+            }
+            else
+                ctx.requireHuman("uninstall strom from this computer", "strom uninstall", "uninstall", ui(lang, "ui.uninstall.window"));
+        }
+        const removed = plan.remove.filter((r) => {
+            try {
+                return r.remove();
+            }
+            catch {
+                return false;
+            }
+        });
+        const failed = plan.remove.filter((r) => !removed.includes(r));
+        return {
+            text: lines(...removed.map((r) => `✓ ${label(r)}: ${ctx.display(r.path)}`), ...failed.map((r) => `✗ ${label(r)}: ${ctx.display(r.path)}`), "", plan.npm ? ui(lang, "ui.uninstall.npm") : undefined, keeps, failed.length ? undefined : ui(lang, "ui.uninstall.done")),
+            data: { removed: removed.map((r) => ({ kind: r.kind, path: r.path })), failed: failed.map((r) => ({ kind: r.kind, path: r.path })), npm: plan.npm },
+        };
+    },
+}, {
+    path: ["shortcut"],
+    summary: 'Put a "Strom research" shortcut on the desktop — a double-click opens strom\'s menu',
+    group: "setup",
+    run(ctx) {
+        const lang = ctx.uiLang();
+        const files = createShortcut(shortcutName(lang), ctx.env);
+        return { text: lines(...files.map((f) => ui(lang, "ui.shortcut.done", { file: ctx.display(f) }))), data: { files } };
+    },
+}, {
+    path: ["menu"],
+    summary: "The guided menu for a person — what `strom` opens in a terminal",
+    group: "start",
+    run: async (ctx) => {
+        if (isAgent(ctx.env))
+            throw new UsageError("the menu is for a person at a terminal", { hint: "strom (orientation) — or strom --json" });
+        const { runMenu } = await import("../cli/menu.js");
+        const { main } = await import("../cli/main.js");
+        await runMenu(ctx, (argv, quiet) => main(argv, quiet ? { ...ctx.io, stdout: () => undefined } : ctx.io, ctx.env, ctx.cwd));
+        return { text: "" };
+    },
+});

package/dist/commands/story.js

@@ -0,0 +1,75 @@
+// story set · show — the story of a person or a couple, written from the facts
+// for the family. It goes into the GEDCOM as _STORY (Strom sets it in the
+// family book after the facts).
+import fs from "node:fs";
+import { register } from "../cli/registry.js";
+import { lines } from "../cli/format.js";
+import { setStory, findEventOwner } from "../core/actions.js";
+import { UsageError } from "../core/errors.js";
+import { csvOpt, normId, textOpt } from "../core/records.js";
+import { resolvePerson } from "../core/people.js";
+function owner(tree, ref) {
+    return /^F\d+$/i.test(ref.trim()) ? normId(ref, "family") : resolvePerson(tree, ref).id;
+}
+register({
+    path: ["story", "set"],
+    summary: "Write the story of a person or a couple from the facts (a draft until the user approves it)",
+    group: "people",
+    tree: true,
+    writes: true,
+    description: "Every statement rests on a recorded fact: list them with --fact. Paragraphs are separated by a blank line;\n" +
+        "**bold** is kept. Writing it again replaces it (the history keeps the old one).",
+    args: [{ name: "who", description: "person (ID or name) or family (F…)", required: true }],
+    options: [
+        { name: "text", type: "string", value: "<text|@file>", description: "the story, in the research language" },
+        { name: "title", type: "string", value: "<text>", description: "a heading" },
+        { name: "fact", type: "string", multiple: true, value: "<E…>", description: "a fact it leans on (repeatable)" },
+        { name: "note", type: "string", value: "<text>", description: "your caveat: what is inferred, what is unknown" },
+        { name: "final", type: "boolean", description: "the user approved it" },
+    ],
+    examples: ['strom story set P0001 --text @notes/story-P0001.md --title "The miller of Týnec" --fact E0001 --fact E0002 --note "The house is inferred from the census."'],
+    run(ctx, { args, opts }) {
+        const tree = ctx.tree();
+        const text = textOpt(opts.text, (p) => fs.readFileSync(ctx.resolvePath(p), "utf8"));
+        if (!text?.trim())
+            throw new UsageError("--text is required", { hint: "--text @notes/story.md (a file) or the text itself" });
+        const rec = setStory(tree, owner(tree, args[0]), {
+            text,
+            title: opts.title,
+            facts: csvOpt(opts.fact).map((f) => normId(f)),
+            note: opts.note,
+            final: Boolean(opts.final),
+        });
+        const missing = rec.story.facts.length === 0 ? "note: no --fact given — say which facts the story rests on" : undefined;
+        return { text: lines(...tree.written.map((o) => o.summary), tree.dryRun ? "(dry run — nothing written)" : undefined, missing), data: { story: rec.story } };
+    },
+}, {
+    path: ["story", "show"],
+    summary: "The story of a person or a couple, with the facts it rests on",
+    group: "people",
+    tree: true,
+    args: [{ name: "who", description: "person (ID or name) or family (F…)", required: true }],
+    run(ctx, { args }) {
+        const tree = ctx.tree();
+        const id = owner(tree, args[0]);
+        const rec = tree.get(id);
+        if (!rec)
+            throw new UsageError(`no family ${id}`);
+        const st = rec.story;
+        if (!st)
+            return { text: `${id} has no story yet → strom story set ${id} --text @file --fact E…`, data: { story: null } };
+        const facts = st.facts.map((f) => {
+            try {
+                const { owner: o, event: e } = findEventOwner(tree, f);
+                return `  ${e.id} ${o.id} ${e.kind}${e.date ? ` ${e.date}` : ""}${e.place ? ` ${e.place}` : ""} [${e.status}]`;
+            }
+            catch {
+                return `  ${f} (no longer exists)`;
+            }
+        });
+        return {
+            text: lines(`${id} story · ${st.status} · ${st.at.slice(0, 10)}${st.title ? ` · ${st.title}` : ""}`, "", st.text, "", st.facts.length ? "rests on" : "rests on no recorded fact", ...facts, st.note ? `\nnote: ${st.note}` : undefined),
+            data: { story: st },
+        };
+    },
+});