strom-research 1.13.2-beta.2 → 1.13.2-beta.3

package/dist/agents/profiles.js

@@ -12,8 +12,11 @@
 export const TIERS = ["lead", "vision", "text", "cheap"];
 const DELEGATION_RULES = `- Browsing a book, an index or a range of images ("is our surname on this page?")
   is delegated; so is anything self-contained that returns little.
-- About ten images per delegate, never more than twelve: an image stays in the
-  context of whoever opened it and is paid for again on every turn.
+- About ten scans (images B…:n) per delegate, never more than twelve; it opens
+  as many halves and crops of them as reading needs, but tell it to stop at
+  about 80 views and return what it has: every view stays in its context to
+  the end. It asks for the views of a scan (or of a few) in one call —
+  \`strom media view B0001:57-60 --half both\` — and opens them together.
 - Every delegate gets the full question (what counts as a find, which years,
   which names) and returns for each image: image and page, find or nothing,
   what was illegible, the hand, and certainty per name — written as it goes.
@@ -25,13 +28,20 @@ export const SELF_READING = `## Reading scans (Codex, Antigravity, OpenCode, Gro
 
 Read the images yourself, with your strongest model — never hand old
 handwriting to a faster or cheaper model, subagent or pass. Read them
-in batches of at most ten: open a batch, write down what it gave (strom
-search add … for what was not found, facts for what was), then open the
-next. Images stay in your context and are paid for on every turn, so never
-keep more than one batch open. A name or place the next search depends on:
+in batches of at most ten: open a batch (one call gives its views —
+\`strom media view B0001:57-66 --half both\` — open them together), write
+down what it gave (strom search add … for what was not found, facts for what
+was), then open the next. Every image and view stays in your context to the end: after about 80
+views, write down what you found and go on. A name or place the next search depends on:
 read it again on a crop at full resolution (\`strom media view … --crop\`)
 before you record it.
 `;
+/**
+ * The agents strom can start working alone without the user's personal add-ons (agent.addons): Claude Code
+ * (--strict-mcp-config, --tools, no auto-memory) and Codex (its plugins, apps, hooks and memories off). The others have
+ * no such switch — nothing is made up for them, and the setting is not offered.
+ */
+export const ADDON_SWITCHES = ["claude", "codex"];
 export const PROFILES = {
     claude: {
         id: "claude",

package/dist/brief/brief.js

@@ -4,10 +4,13 @@
 // session and its context was summarised within minutes (median ~11 min).
 // The brief has a hard token budget; sections come in priority order and
 // what does not fit is cut to a pointer: the command that shows the rest.
+import fs from "node:fs";
 import path from "node:path";
 import { inboxFolders, inputPath } from "../core/media.js";
-import { displayName, familiesAsChild, familiesAsPartner, formatName, label, lifespan, likelyDuplicates, parentsOf } from "../core/people.js";
+import { displayName, familiesAsChild, familiesAsPartner, formatName, label, lifespan, likelyDuplicates, parentsOf, sameFamilyName, surnameForms } from "../core/people.js";
+import { parseYears } from "../core/years.js";
 import { langName } from "../core/lang.js";
+import { dateYears } from "../core/gdate.js";
 import { methodFor } from "../core/assets.js";
 import { recentSessions } from "../core/session.js";
 import { briefClock } from "../core/clock.js";
@@ -16,14 +19,24 @@ import { taskRecordsets } from "../core/frontier.js";
 import { reviewItems } from "../core/review.js";
 import { readyConnectors } from "../core/connector.js";
 import { runs, shellArg } from "../cli/format.js";
+import { commandSheet } from "./sheet.js";
 import { foldText } from "../core/text.js";
 import { subjectPeople } from "../core/records.js";
 import { hypothesisPeople } from "../core/directions.js";
+import { imagesIndex } from "../core/mediaindex.js";
 export { DEFAULT_BUDGET } from "../core/config.js";
 import { DEFAULT_BUDGET } from "../core/config.js";
-/** Rough token estimate: good enough for a soft budget. */
+/**
+ * Estimated tokens, on the safe side. A word of plain ASCII (English, IDs, numbers) takes about 2.5 characters a
+ * token; a word with any other letter — a diacritic, another script — about one, the whole word (measured on the
+ * briefs and outputs of real sessions: a Czech research's brief is 1.7–1.8 characters a token, not 3.5).
+ */
 export function tokens(text) {
-    return Math.ceil(text.length / 3.5);
+    let other = 0;
+    for (const m of text.matchAll(/\S+/gu))
+        if (/[^\x00-\x7F]/u.test(m[0]))
+            other += m[0].length;
+    return Math.ceil((text.length - other) / 2.5 + other);
 }
 function eventLine(e) {
     const cites = citesOf(e.citations);
@@ -52,16 +65,122 @@ function personBlock(tree, p, depth) {
         out.push(`    story: ${p.story.status}${p.story.title ? ` "${p.story.title}"` : ""}, ${p.story.text.split(/\s+/).length} words (strom story show ${p.id})`);
     for (const n of p.notes.slice(-3))
         out.push(`    note: ${n.text}`);
+    if (p.notes.length > 3)
+        out.push(`    (${p.notes.length - 3} older note${p.notes.length > 4 ? "s" : ""}: strom person show ${p.id})`);
     return out;
 }
+const VITAL = new Set(["BIRT", "CHR", "BAPM", "DEAT", "BURI", "CREM"]);
+const NOTE_SHOWN = 300;
+/** Where a person lived and what they did, the years with each: what tells namesakes apart. */
+function identifying(p, vitalToo) {
+    const facts = p.events.filter((e) => !e.retracted && !VITAL.has(e.kind));
+    const grouped = (list) => {
+        const by = new Map();
+        for (const [what, date] of list) {
+            const years = by.get(what) ?? new Set();
+            for (const y of dateYears(date ?? ""))
+                years.add(y);
+            by.set(what, years);
+        }
+        // the years as a span: when, not every record of it
+        return [...by].map(([what, years]) => {
+            const y = [...years].sort((a, b) => a - b);
+            return `${what}${y.length ? ` ${y.length > 1 ? `${y[0]}–${y.at(-1)}` : y[0]}` : ""}`;
+        });
+    };
+    // where they lived: a house in a place, or the place of a residence
+    const lived = (e) => !!e.house || (e.kind === "RESI" && !!e.place);
+    const houses = grouped((vitalToo ? p.events.filter((e) => !e.retracted) : facts).filter(lived).map((e) => [[e.place, e.house].filter(Boolean).join(" "), e.date]));
+    const work = grouped(facts.filter((e) => e.kind === "OCCU" && e.value).map((e) => [e.value, e.date]));
+    const more = facts.filter((e) => !lived(e) && !(e.kind === "OCCU" && e.value)).length;
+    return { houses, work, more };
+}
+/** A parent of the task's person: the vital facts (sources by ID), where they lived and what they did, the parents, the last notes cut short. */
+function relativeBlock(tree, p, role) {
+    const out = [`  ${label(p)} ${p.sex} — ${role}`];
+    for (const e of p.events.filter((x) => !x.retracted && VITAL.has(x.kind)))
+        out.push(`    ${e.id} ${e.kind}${e.date ? ` ${e.date}` : ""}${e.place ? ` ${e.place}` : ""}${e.house ? `, house ${e.house}` : ""} [${e.status}]${e.citations?.length ? ` ← ${[...new Set(e.citations.map((c) => c.source))].join(", ")}` : ""}`);
+    const { houses, work, more } = identifying(p, false);
+    if (houses.length || work.length || more)
+        out.push(`    ${[houses.length ? `lived: ${houses.join("; ")}` : "", work.length ? `occupation: ${work.join("; ")}` : "", more ? `${more} more fact${more > 1 ? "s" : ""}` : ""].filter(Boolean).join(" · ")}`);
+    const parents = parentsOf(tree, p.id);
+    out.push(`    parents: ${parents.length ? parents.map(label).join(" & ") : "unknown"}`);
+    for (const n of p.notes.slice(-2))
+        out.push(`    note: ${[...n.text].length > NOTE_SHOWN ? `${[...n.text].slice(0, NOTE_SHOWN).join("")}…` : n.text}`);
+    if (p.notes.length > 2)
+        out.push(`    (${p.notes.length - 2} older note${p.notes.length > 3 ? "s" : ""}: strom person show ${p.id})`);
+    return out;
+}
+/** Anyone else concerned, in one line: who they are to the task's people, where they lived, what they did, their parents. */
+function relativeLine(tree, p, role, withParents) {
+    const { houses, work } = identifying(p, true);
+    const parents = withParents ? parentsOf(tree, p.id) : [];
+    return `  · ${label(p)} ${p.sex} — ${[role, houses.length ? `lived: ${houses.join("; ")}` : "", work.length ? `occupation: ${work.join("; ")}` : "", parents.length ? `parents: ${parents.map((x) => x.id).join(" & ")}` : ""].filter(Boolean).join(" · ")}`;
+}
+/** A small text file of an input, as strom input show gives it; unreadable: nothing. */
+function readSmall(file) {
+    try {
+        return fs.readFileSync(file, "utf8").trim();
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Words of a text, folded (any script; NFC or NFD alike). */
+function foldedWords(text) {
+    return foldText(text.normalize("NFC")).split(/[^\p{L}\p{M}\p{N}]+/u).filter(Boolean);
+}
+/** The part of a name its forms share ("Lhoty" → lhot, "Dvořák" → dvorak), long enough to mean it, else none. */
+function stem(name) {
+    const s = foldText(name.normalize("NFC")).replace(/[aeiouyаеёиоуыэюяієї]+$/u, "");
+    return [...s].length >= 4 ? s : undefined;
+}
+/**
+ * Which lessons of the whole project (no record set, archive or place of their own) go with a task: one naming a
+ * family or a place of this tree goes with a task of that family or place (its text, its people, their facts, its
+ * books); one naming none of them is general and goes with every task. A name told in a lesson's own words
+ * ("Dvořákovi", "u Lhoty") is known by its stem; one not recognised keeps the lesson in — never a lesson lost.
+ */
+function projectLessonFit(tree, task, persons, where) {
+    const known = new Set();
+    const add = (n) => {
+        if (!n)
+            return;
+        const first = n.trim().split(/[\s,]+/u)[0] ?? "";
+        for (const f of [first, ...surnameForms(first)]) {
+            const s = stem(f);
+            if (s)
+                known.add(s);
+        }
+    };
+    for (const p of tree.list("person"))
+        if (!p.retracted)
+            for (const n of p.names)
+                add(n.surname);
+    for (const pl of tree.list("place"))
+        for (const n of pl.names)
+            add(n.name);
+    for (const b of tree.list("recordset"))
+        for (const n of b.places ?? [])
+            add(n);
+    const books = where.map((w) => tree.get(w)).filter((b) => !!b && b.type === "recordset");
+    const context = new Set(foldedWords([
+        task ? [task.what, task.why, task.doneWhen, ...task.where, ...task.notes.map((n) => n.text)].join(" ") : "",
+        ...books.flatMap((b) => [b.title, ...(b.places ?? [])]),
+        ...persons.flatMap((p) => [...p.names.map((n) => `${n.given} ${n.surname}`), ...p.events.map((e) => e.place ?? "")]),
+        ...persons.flatMap((p) => parentsOf(tree, p.id).flatMap((x) => x.names.map((n) => n.surname))),
+    ].join(" ")));
+    return (l) => {
+        // the names it gives: words written with a capital that are a family or a place of this tree
+        const names = l.rule.normalize("NFC").split(/[^\p{L}\p{M}\p{N}]+/u).filter((w) => /^\p{Lu}/u.test(w)).map((w) => foldText(w));
+        const its = [...known].filter((k) => names.some((w) => w.startsWith(k)));
+        return its.length === 0 || its.some((k) => [...context].some((w) => w.startsWith(k)));
+    };
+}
 /** How many images of a record set are registered, and how to look at them. */
 function imagesLine(tree, b, shared) {
     // each image once: its parts and other copies are the same image
-    const nums = [...new Set(tree
-            .list("media")
-            .filter((m) => m.recordset === b.id && m.image !== undefined)
-            .map((m) => m.image))]
-        .sort((x, y) => x - y);
+    const nums = imagesIndex(tree).sets.get(b.id)?.images ?? [];
     if (nums.length === 0) {
         const repo = b.repository ? tree.get(b.repository) : undefined;
         const c = b.url && repo?.automation !== "forbidden" && repo?.automation !== "manual" ? readyConnectors(tree.env, shared, b.url)[0] : undefined;
@@ -74,7 +193,7 @@ function imagesLine(tree, b, shared) {
     // Which ones exist, when there are gaps (a few runs), or just the span.
     const list = runs(nums);
     const which = list.split(", ").length <= 12 ? list : `${nums[0]}–${nums.at(-1)} with gaps (strom media list --recordset ${b.id})`;
-    return `    images registered (${nums.length}): ${which} · strom media view ${b.id}:<image> [--half left|right] [--grid] [--crop x,y,w,h]`;
+    return `    images registered (${nums.length}): ${which} · strom media view ${b.id}:<image>[-<image>] [--half left|right|both] [--grid] [--crop x,y,w,h]`;
 }
 /** What the user put in the shared inbox, waiting to be registered — by folder (one download each). */
 function inboxLines(shared) {
@@ -145,6 +264,7 @@ export function buildBrief(tree, opts) {
                 `done:  ${task.doneWhen}`,
                 task.subject.length ? `about: ${task.subject.join(" ")}` : "",
                 ...task.notes.slice(-3).map((n) => `note:  ${n.text}`),
+                task.notes.length > 3 ? `(notes: the last 3 of ${task.notes.length} — all: strom task show ${task.id})` : "",
             ].filter(Boolean).join("\n"),
         });
         // 2. a review: what each item of the task is, as the tree has it
@@ -180,11 +300,17 @@ export function buildBrief(tree, opts) {
                     "## The material",
                     ...inputs.map((i) => {
                         const file = inputPath(tree, i);
+                        // all that strom input show says of it, so it needs no extra command (K6)
+                        const small = !i.text && i.kind === "text" && file && (i.size ?? 0) < 20_000 && /\.(txt|md|csv)$/i.test(file) ? readSmall(file) : undefined;
                         return [
-                            `${i.id} ${i.name} [${i.kind} · ${i.state}]${i.from ? ` from ${i.from}` : ""}`,
+                            `${i.id} ${i.name} [${i.kind} · ${i.state}]${i.from ? ` from ${i.from}` : ""}${i.mime ? ` · ${i.mime}${i.size !== undefined ? ` ${Math.round(i.size / 1024)} kB` : ""}` : ""}`,
                             file ? `file: ${file}${i.kind === "document" || i.kind === "photo" ? " — open it and read it yourself" : ""}` : "",
+                            i.batch ? `batch: ${i.batch}${i.path ? ` · ${i.path}` : ""}` : "",
+                            i.persons?.length ? `of: ${i.persons.join(", ")}` : "",
+                            i.sorted ? `sorted: ${i.sorted.as}${i.sorted.source ? ` → ${i.sorted.source}` : ""}${i.sorted.reason ? ` (${i.sorted.reason})` : ""}` : "",
                             i.imported ? `imported: ${i.imported.persons} persons, ${i.imported.families} families as leads, cited as ${i.source}` : "",
-                            i.text ? `text:\n${i.text}` : "",
+                            ...i.notes.map((n) => `note: ${n.text}`),
+                            i.text ? `text:\n${i.text}` : small ? `text:\n${small}` : "",
                         ].filter(Boolean).join("\n");
                     }),
                 ].join("\n"),
@@ -202,21 +328,67 @@ export function buildBrief(tree, opts) {
     const where = new Set([...(task?.where ?? []), ...located.sets.map((b) => b.id)]);
     // A task about a conflict or a hypothesis is about its people too.
     const subjects = new Set([...(task?.subject ?? []), ...subjectPeople(tree, task?.subject ?? [])]);
-    const surnames = new Set([...subjects].map((id) => tree.get(id)).filter((p) => !!p && p.type === "person").flatMap((p) => p.names.map((n) => foldText(n.surname)).filter(Boolean)));
-    const searches = tree
-        .list("search")
-        .filter((s) => s.recordsets.some((b) => where.has(b)) || (s.task && s.task === task?.id) || (s.scope.surnames ?? []).some((x) => surnames.has(foldText(x))));
+    const persons = [...subjects].map((id) => tree.get(id)).filter((p) => !!p && p.type === "person");
+    const theirs = persons.flatMap((p) => p.names.map((n) => n.surname).filter(Boolean));
+    const surnames = new Set(theirs.map((n) => foldText(n)));
     const repos = new Set([...where].map((w) => tree.get(w)?.repository).filter(Boolean));
-    const lessons = tree.list("lesson").filter((l) => (l.target && (where.has(l.target) || repos.has(l.target))) || l.scope === "project");
+    // a lesson on a place (L…) goes with the books of that place — or of the parish it belonged to
+    const bookPlaces = new Set([...where].flatMap((w) => tree.get(w)?.places ?? []).map((x) => foldText(x)));
+    // Where and when the task is: its books' places and years, its people's places and years (±30) — a search of their
+    // surname in other places and other times is only counted (K11).
+    const placeKey = (x) => foldText(x.split(",")[0].trim());
+    const taskPlaces = new Set([...bookPlaces].map(placeKey));
+    for (const p of persons)
+        for (const e of p.events)
+            if (!e.retracted && e.place)
+                taskPlaces.add(placeKey(e.place));
+    const taskYears = [
+        ...[...where].flatMap((w) => { const y = parseYears(tree.get(w)?.years); return y ? [y.from, y.to] : []; }),
+        ...persons.flatMap((p) => p.events.filter((e) => !e.retracted).flatMap((e) => dateYears(e.date ?? ""))),
+    ];
+    const span = taskYears.length ? { from: Math.min(...taskYears) - 30, to: Math.max(...taskYears) + 30 } : undefined;
+    const nearby = (s) => {
+        const books = s.recordsets.map((b) => tree.get(b)).filter((b) => !!b);
+        const spans = [s.scope.years, ...(s.scope.years ? [] : books.map((b) => b.years))].map((y) => parseYears(y)).filter((y) => !!y);
+        const places = [...(s.scope.places ?? []), ...books.flatMap((b) => b.places)].map(placeKey);
+        if (places.some((x) => taskPlaces.has(x)))
+            return true;
+        if (span && spans.length)
+            return spans.some((y) => y.from <= span.to && span.from <= y.to);
+        // nothing to tell it by: kept
+        return !places.length || (!span && !taskPlaces.size);
+    };
+    const named = (s) => (s.scope.surnames ?? []).some((x) => theirs.some((y) => sameFamilyName(x, y)));
+    const premise = tree.list("search").filter((s) => s.recordsets.some((b) => where.has(b)) || (s.task && s.task === task?.id) || named(s));
+    const searches = premise.filter((s) => s.recordsets.some((b) => where.has(b)) || (s.task && s.task === task?.id) || nearby(s));
+    const elsewhere = premise.filter((s) => !searches.includes(s));
+    const elsewhereNames = [...new Set(elsewhere.flatMap((s) => theirs.filter((y) => (s.scope.surnames ?? []).some((x) => sameFamilyName(x, y)))))];
+    const ofPlace = (id) => {
+        const pl = tree.get(id);
+        return pl?.type === "place" && [...pl.names.map((n) => n.name), ...pl.jurisdictions.map((j) => j.name)].some((n) => [...bookPlaces].some((b) => b === foldText(n) || b.startsWith(`${foldText(n)},`)));
+    };
+    const all = tree.list("lesson").filter((l) => !l.retracted);
+    // a lesson of the whole project goes with the task whose families or places it names — or names none of the tree's
+    const project = all.filter((l) => l.scope === "project" && !l.target);
+    const fits = project.length ? projectLessonFit(tree, task, persons, [...where]) : () => true;
+    const lessons = all.filter((l) => (l.target && (where.has(l.target) || repos.has(l.target) || ofPlace(l.target))) || (l.scope === "project" && (l.target || fits(l))));
+    const otherProject = project.filter((l) => !lessons.includes(l)).length;
+    const method = all.filter((l) => l.scope === "method").length;
     sections.push({
         name: "premise",
-        pointer: `strom searched ${[...where].find((w) => w.startsWith("B")) ?? [...surnames][0] ?? "<where>"}`,
+        // shown before the people, but given its room after them, the last sessions and the open questions: a long
+        // list of searches never pushes out whom the task is about (P3)
+        last: true,
+        pointer: `strom searched ${[...where].find((w) => w.startsWith("B")) ?? [...surnames][0] ?? "<where>"}${lessons.length ? " · lessons: strom lesson list" : ""}`,
         text: [
             "## Already known (check the premise before searching)",
             searches.length
                 ? searches.map((s) => `  ${s.id} [${s.result}] ${s.question}${s.scope.years ? ` · ${s.scope.years}` : ""}${s.scope.pages ? ` · pages ${s.scope.pages}` : ""} · ${s.recordsets.join(" ")}${s.by !== "main" ? ` (by ${s.by})` : ""}`).join("\n")
                 : "  nothing searched yet for this task's record sets and surnames",
+            ...(elsewhere.length ? [`  +${elsewhere.length} search${elsewhere.length > 1 ? "es" : ""} of ${elsewhereNames.join(", ")} in other places and years: ${elsewhereNames.map((n) => `strom searched ${shellArg(n)}`).join(" · ")}`] : []),
             ...(lessons.length ? ["lessons:", ...lessons.map((l) => `  ${l.id}${l.target ? ` (${l.target})` : ""}: ${l.rule}`)] : []),
+            ...(otherProject ? [`lessons about other families and places: ${otherProject} — strom lesson list --scope project`] : []),
+            ...(method ? [`method lessons of this research: ${method} — strom lesson list --scope method`] : []),
         ].join("\n"),
     });
     // 4. handover from the previous sessions
@@ -227,28 +399,48 @@ export function buildBrief(tree, opts) {
             pointer: "strom session list",
             text: ["## Last sessions", ...recent.map((s) => `  ${s.id} ${s.state}${s.task ? ` on ${s.task}` : ""}: ${s.summary ?? "(no summary)"}${s.next ? `\n    next: ${s.next}` : ""}`)].join("\n"),
         });
-    // 5. the people concerned
+    // 5. the people concerned: whom the task is about in full, their parents with what identifies them (facts, houses,
+    // occupations, parents), grandparents and brothers and sisters one line each — the rest is a command away
     const people = new Map();
     const personSubjects = [...subjects].filter((id) => tree.get(id)?.type === "person");
-    for (const id of personSubjects.length ? personSubjects : research ? [research.focus] : []) {
-        people.set(id, 1);
+    // no person named: the research's focus, to know whose tree it is
+    const about = personSubjects.length ? personSubjects : research ? [research.focus] : [];
+    for (const id of about)
+        people.set(id, { how: "full", role: "" });
+    for (const id of about) {
         for (const p of parentsOf(tree, id)) {
-            people.set(p.id, Math.max(people.get(p.id) ?? 0, 0));
+            if (!people.has(p.id))
+                people.set(p.id, { how: personSubjects.length ? "parent" : "line", role: `${p.sex === "F" ? "mother" : p.sex === "M" ? "father" : "parent"} of ${id}` });
             for (const gp of parentsOf(tree, p.id))
                 if (!people.has(gp.id))
-                    people.set(gp.id, 0);
+                    people.set(gp.id, { how: "line", role: `${gp.sex === "F" ? "mother" : gp.sex === "M" ? "father" : "parent"} of ${p.id}` });
         }
         for (const f of familiesAsChild(tree, id))
             for (const s of f.children)
                 if (!people.has(s.person) && s.person !== id)
-                    people.set(s.person, 0);
+                    people.set(s.person, { how: "line", role: `sibling of ${id}` });
     }
     if (people.size) {
-        const blocks = [...people.entries()].map(([id, depth]) => {
+        const blocks = [...people.entries()].flatMap(([id, { how, role }]) => {
             const p = tree.get(id);
-            return p ? personBlock(tree, p, depth).join("\n") : "";
+            if (!p)
+                return [];
+            if (how === "full")
+                return [personBlock(tree, p, 1).join("\n")];
+            if (how === "parent")
+                return [relativeBlock(tree, p, role).join("\n")];
+            return [relativeLine(tree, p, role, !role.startsWith("sibling"))];
+        });
+        const short = [...people.values()].some((x) => x.how !== "full");
+        sections.push({
+            name: "people",
+            pointer: `strom person show ${[...people.keys()][0]}`,
+            text: [
+                "## People concerned",
+                ...blocks,
+                ...(short ? ["  (others in short — all facts, sources and notes: strom person show P… · their life with its records: strom person card P…)"] : []),
+            ].join("\n"),
         });
-        sections.push({ name: "people", pointer: `strom person show ${[...people.keys()][0]}`, text: ["## People concerned", ...blocks].join("\n") });
     }
     // 6. open conflicts and hypotheses about them
     const ids = new Set(people.keys());
@@ -273,6 +465,8 @@ export function buildBrief(tree, opts) {
     if (sets.length)
         sections.push({
             name: "record sets",
+            // the books to work in, their images and calibration: kept before the long lists when the brief is full
+            first: true,
             pointer: `strom recordset show ${sets[0].id}`,
             text: [
                 located.guessed
@@ -307,7 +501,12 @@ export function buildBrief(tree, opts) {
             ].join("\n"),
         });
     // 8. method for this kind of task
-    sections.push({ name: "method", pointer: "strom guide", text: methodFor(task?.level) });
+    // (budgeted first, with the record sets and the commands: when the brief is long, the lists are cut before how to work)
+    sections.push({ name: "method", first: true, pointer: "strom guide", text: methodFor(task?.level) });
+    // 8b. the commands this kind of task uses, with every option and limit (K2): asking for them costs a turn each
+    const sheet = commandSheet(task?.level);
+    if (sheet)
+        sections.push({ name: "commands", first: true, pointer: "strom help <command>", text: sheet });
     // 9. how to finish
     sections.push({
         name: "closing",
@@ -315,37 +514,56 @@ export function buildBrief(tree, opts) {
         pointer: "",
         text: [
             "## Finishing",
-            task ? `- close the task: strom task done ${task.id} --result "…" (a complete negative search is a result) — or task park / task wait` : "",
             "- new questions → strom task add … (what, where, why, done-when)",
-            '- then: strom session close --summary "what was proven, what was searched in vain" --next "the next cheapest step"',
+            task
+                ? '- done: strom session close --done "what was proven, what was searched in vain" --next "the next cheapest step" (the task and the session in one call; a complete negative search is a result)'
+                : '- then: strom session close --summary "what was proven, what was searched in vain" --next "the next cheapest step"',
+            task ? `- put aside: strom task park|wait ${task.id} …, then strom session close --summary "…" --next "…"` : "",
             `- if the task is not finished: strom session close --continue --summary "…" --next "exactly where you stopped"`,
             "- a command you need: strom help <command> (short, with examples) — the full guide: strom guide",
         ].filter(Boolean).join("\n"),
     });
-    // Assemble within the budget: required sections always, others in order.
-    let used = sections.filter((s) => s.required).reduce((n, s) => n + tokens(s.text), 0);
-    const report = [];
-    const parts = [];
-    for (const s of sections) {
+    // Assemble within the budget: required sections always, then the first ones whole when they fit, then the others in
+    // order, the last ones after them; each written where it stands. Everything written counts: the blank line between
+    // sections, the pointer of a section cut.
+    const SEP = tokens("\n\n");
+    let used = sections.filter((s) => s.required).reduce((n, s) => n + tokens(s.text) + SEP, 0);
+    const shown = new Map();
+    for (const s of sections.filter((x) => x.first && !x.required))
+        if (used + tokens(s.text) + SEP <= budget) {
+            used += tokens(s.text) + SEP;
+            shown.set(s, { text: s.text, cut: false });
+        }
+    const fit = (s) => {
         const t = tokens(s.text);
-        if (s.required || used + t <= budget) {
-            if (!s.required)
-                used += t;
-            parts.push(s.text);
-            report.push({ name: s.name, tokens: t, cut: false });
-            continue;
+        if (!s.first && used + t + SEP <= budget) {
+            used += t + SEP;
+            shown.set(s, { text: s.text, cut: false });
+            return;
         }
-        // Keep as many whole lines as fit, then the pointer.
-        const lines = s.text.split("\n");
-        const kept = [];
-        for (const l of lines) {
-            if (used + tokens(l) + 20 > budget)
+        // Its heading always (the agent knows what it was not given), as many whole lines as fit, then the pointer.
+        const [head = "", ...rest] = s.text.split("\n");
+        const pointer = `  … cut to fit the brief — see: ${s.pointer}`;
+        const kept = [head];
+        used += tokens(head) + tokens(pointer) + SEP;
+        for (const l of rest) {
+            if (used + tokens(l) > budget)
                 break;
             kept.push(l);
             used += tokens(l);
         }
-        parts.push([...kept, `  … cut to fit the brief — see: ${s.pointer}`].join("\n"));
-        report.push({ name: s.name, tokens: tokens(kept.join("\n")), cut: true });
+        shown.set(s, { text: [...kept, pointer].join("\n"), cut: true });
+    };
+    // the others in order, a first one that did not fit whole cut after them, the last ones after all
+    const pending = sections.filter((s) => !s.required && !shown.has(s));
+    for (const s of [...pending.filter((x) => !x.first && !x.last), ...pending.filter((x) => x.first), ...pending.filter((x) => x.last && !x.first)])
+        fit(s);
+    const report = [];
+    const parts = [];
+    for (const s of sections) {
+        const r = s.required ? { text: s.text, cut: false } : shown.get(s);
+        parts.push(r.text);
+        report.push({ name: s.name, tokens: tokens(r.text), cut: r.cut });
     }
     const text = parts.join("\n\n") + "\n";
     return { text, sections: report, total: tokens(text), budget };

package/dist/brief/sheet.js

@@ -0,0 +1,65 @@
+// The commands a task of each level uses, with their exact options and limits — so the agent need not ask
+// `strom help` for them in every session (K2/P5). Everything shown comes from the command registry (arguments,
+// options, the values an option takes) and from the record schemas (how long a text may be): nothing is written
+// twice by hand. Only which commands go with which level is chosen here.
+import { commands } from "../cli/registry.js";
+import { SCHEMAS } from "../core/schema.js";
+import { NOTE_MAX } from "../core/model.js";
+const ALL = ["search add", "task add", "note add", "lesson add"];
+const SCANS = ["media view", "read", "fetch"];
+const LEVELS = {
+    link: [...ALL, ...SCANS, "hypothesis add", "hypothesis argue", "conflict add", "task wait"],
+    verify: [...ALL, ...SCANS, "conflict add", "hypothesis add", "hypothesis argue"],
+    enrich: [...ALL, ...SCANS, "hypothesis add", "task wait"],
+    locate: [...ALL, "recordset add", "fetch", "task wait"],
+    intake: [...ALL, "input sort", "input skip", "media view", "conflict add"],
+    request: [...ALL, "task wait", "source add"],
+    narrate: [...ALL, "story set"],
+};
+const camel = (name) => name.replace(/-(\p{L})/gu, (_, c) => c.toUpperCase());
+/** How long a text may be: a note's, or from the schema of the record an "add" writes ("search add <question>" → search.question). */
+function limit(def, name) {
+    if (name === "note" || (def.path[0] === "note" && name === "text"))
+        return NOTE_MAX;
+    if (def.path[1] !== "add")
+        return undefined;
+    const fields = SCHEMAS[def.path[0]];
+    const spec = fields?.[camel(name)];
+    return spec?.t === "string" ? spec.max : undefined;
+}
+/** The values an option takes when its description is just their list ("found, negative, partial"), else its placeholder. */
+function value(def, o) {
+    if (o.type === "boolean")
+        return "";
+    const words = o.description.replace(/\s*\(default\)/gu, "").trim().split(/,\s*/u);
+    const max = limit(def, o.name);
+    if (words.length > 1 && words.every((w) => /^[\p{L}\p{N}-]+$/u.test(w)))
+        return ` ${words.join("|")}`;
+    const v = o.value ?? "<value>";
+    return ` ${max ? v.replace(/>$/u, ` ≤${max}>`) : v}`;
+}
+function arg(def, a) {
+    const max = limit(def, a.name);
+    const name = `${a.name}${max ? ` ≤${max}` : ""}`;
+    return a.required ? `<${name}>${a.variadic ? "…" : ""}` : `[${name}]${a.variadic ? "…" : ""}`;
+}
+/** One command in one line: its arguments and every option, as the registry declares them. */
+export function synopsis(def) {
+    const opts = (def.options ?? []).filter((o) => !o.hidden);
+    // what an option needs besides, as its description says it ("required with --result found")
+    const needs = (o) => /required with (--[\p{L}\p{N}-]+(?: [\p{L}\p{N}-]+)?)/u.exec(o.description)?.[1];
+    return ["strom", ...def.path, ...(def.args ?? []).map((a) => arg(def, a)), ...opts.map((o) => `--${o.name}${value(def, o)}${o.multiple ? "…" : ""}${needs(o) ? ` (with ${needs(o)})` : ""}`)].join(" ");
+}
+/** The section of the brief: the commands of this level, or nothing (no level, or no registry — a unit test). */
+export function commandSheet(level) {
+    const names = level ? LEVELS[level] : undefined;
+    if (!names)
+        return "";
+    const defs = names.map((n) => commands().find((c) => c.path.join(" ") === n)).filter((d) => !!d);
+    if (!defs.length)
+        return "";
+    return [
+        "## Commands for this task (every option; ≤n: at most n characters; … repeatable — more: strom help <command>)",
+        ...defs.map((d) => `  ${synopsis(d)}`),
+    ].join("\n");
+}

package/dist/cli/context.js

@@ -29,6 +29,8 @@ export class Context {
     limit;
     page;
     dryRun = false;
+    /** The record IDs the command names (T…, N…, G…): which of an agent's sessions in several researches is its. */
+    refs = [];
     opened;
     /**
      * The backup before another channel or an older version could not be made (cli/backups.ts): no research is brought
@@ -417,7 +419,7 @@ export class Context {
         // Inside an open session every write is logged under the session's ID;
         // an agent writing outside a session is logged as "agent", never as the user.
         // What the bridge writes for the Strom app (STROM_FOR_APP) is the person's in the app: the user's.
-        const session = this.env.STROM_FOR_APP === "1" ? undefined : currentSession(this.opened, this.env);
+        const session = this.env.STROM_FOR_APP === "1" ? undefined : currentSession(this.opened, this.env, this.refs);
         if (session)
             this.opened.actor = session.id;
         else if (isAgent(this.env) && this.env.STROM_FOR_APP !== "1")