strom-research 1.18.0-beta.11 → 1.18.0-beta.13

package/CHANGELOG.cs.md

@@ -7,7 +7,7 @@ Změny každé verze ve zkratce. Úplné poznámky a instalační řádky jsou n
 
 ## 1.18.0
 
-*Připravuje se: bety do 1.18.0-beta.11. Oddíl bude úplný s vydáním.*
+*Připravuje se: bety do 1.18.0-beta.13. Oddíl bude úplný s vydáním.*
 
 - **Fotky z telefonu nastojato.** Fotka otočená podle údaje EXIF se čte tak, jak se má dívat, nastojato; místa na ní
   vyznačená (výřezy, poloviny dvoustrany, uložená část) jsou místa obrázku, jak se ukazuje. Fotka sama zůstává, jak
@@ -16,14 +16,17 @@ Změny každé verze ve zkratce. Úplné poznámky a instalační řádky jsou n
   na macOS, Windows i Linuxu — a originál zůstává, jak přišel. Fotka HEIC jde do aplikace Strom jako výřez JPEG.
   Kde obrázek na počítači nic nepřevede, řekne to jedna věta i s tím, co by pomohlo; `strom tidy` převedené obrázky
   po 30 dnech nebo nad 500 MB uklidí.
-- **Jeden dokument přečtený naráz.** `strom document read` přečte fotku, sken nebo PDF jednoho dokumentu — zápis
-  z matriky, dopis, listinu, náhrobek, rub fotky: přepis slovo od slova, překlad, význam starých slov a zkratek
-  a osoby, které jmenuje, i s tím, kdo ze stromu to může být. Nic se nedomýšlí: jméno, které v dokumentu není,
-  vypadne — i příjmení, nikdy se nebere od otce ani z jiné rodiny —, co nejde přečíst, je označené; druhý čtenář
-  může číst naslepo. Do stromu se z toho nic nezapíše samo. Dokument už přečtený to o sobě řekne, takže se omylem
-  nečte podruhé. Dokument čtený znovu se ukazuje pod názvem svého souboru, nikdy pod kódem.
-  Dokument poslaný z aplikace Strom najde agenta stejně jako terminál — i nainstalovaného do vlastní složky, přes npm
-  nebo Homebrew — místo hlášení, že agent není nastavený.
+- **Jeden dokument přečtený naráz.** `strom document read` přečte fotku, sken nebo PDF jednoho dokumentu — zápis z
+  matriky, dopis, listinu, náhrobek, rub fotky: přepis slovo od slova, překlad, význam starých slov a zkratek a osoby,
+  které jmenuje, i s tím, kdo ze stromu to může být. Nic se nedomýšlí: jméno, které v dokumentu není, vypadne — i
+  příjmení, nikdy se nebere od otce ani z jiné rodiny —, co nejde přečíst, je označené; druhý čtenář může číst naslepo.
+  Dokument na úředním formuláři, jako rodný list, si své osoby ponechá — dítě i oba rodiče s jejich podílem —, a dokument
+  přečtený dřív je po aktualizaci ukáže, aniž by se četl znovu. U každé osoby a události je i místo na stránce, kde
+  stojí, takže aplikace Strom ukáže výřez každé z nich.
+  Do stromu se z toho nic nezapíše samo. Dokument už přečtený to o sobě řekne, takže se omylem nečte podruhé. Dokument
+  čtený znovu se ukazuje pod názvem svého souboru, nikdy pod kódem. Dokument poslaný z aplikace Strom najde agenta
+  stejně jako terminál — i nainstalovaného do vlastní složky, přes npm nebo Homebrew — místo hlášení, že agent není
+  nastavený. Čte ho každý agent, se kterým výzkum pracuje, s modelem a úsilím nastaveným pro výzkum.
 - **Fotky z telefonu.** `strom phone on`, které zapíná jen člověk, pustí k počítači telefon v domácí síti (Wi-Fi
   nebo kabel — nikdy mobilní síť ani VPN). Telefon se jednou spáruje přes QR kód; jeho stránka pak fotí nebo vybírá
   z galerie a posílá fotky celé do stromu výzkumu, s poznámkou a osobou, kterou ukazují — stejně jako „Přidat

package/CHANGELOG.de.md

@@ -7,7 +7,7 @@ Die Änderungen jeder Version in Kürze. Die vollständigen Hinweise und die Ins
 
 ## 1.18.0
 
-*In Vorbereitung: die Betas bis 1.18.0-beta.11. Der Abschnitt ist mit dem Release vollständig.*
+*In Vorbereitung: die Betas bis 1.18.0-beta.13. Der Abschnitt ist mit dem Release vollständig.*
 
 - **Handyfotos aufrecht.** Ein Foto, das nach seiner EXIF-Ausrichtung gedreht ist, wird gelesen, wie es gesehen
   werden soll, aufrecht; die darauf markierten Stellen (Ausschnitte, die Hälften einer Doppelseite, ein gespeicherter
@@ -16,16 +16,20 @@ Die Änderungen jeder Version in Kürze. Die vollständigen Hinweise und die Ins
   umgewandelt — unter macOS, Windows und Linux —, das Original bleibt, wie es kam. Ein HEIC-Foto geht als
   JPEG-Ausschnitt in die Strom-App. Wo nichts auf dem Computer ein Bild umwandelt, sagt es ein Satz, auch was helfen
   würde; `strom tidy` räumt umgewandelte Bilder nach 30 Tagen oder über 500 MB weg.
-- **Ein Dokument auf einmal gelesen.** `strom document read` liest ein Foto, einen Scan oder eine PDF eines
-  Dokuments — einen Matrikeleintrag, einen Brief, eine Urkunde, einen Grabstein, die Rückseite eines Fotos: die
-  Abschrift Wort für Wort, ihre Übersetzung, was alte Wörter und Abkürzungen bedeuten, und die genannten Personen,
-  samt wem im Stammbaum sie entsprechen können. Nichts wird ergänzt: ein Name, der nicht im Dokument steht, fällt
-  weg — auch ein Nachname, nie vom Vater oder aus einer anderen Familie genommen —, Unleserliches wird markiert; ein
-  zweiter Leser kann blind lesen. In den Stammbaum gelangt nichts von selbst. Ein schon gelesenes Dokument sagt es,
-  so wird es nicht versehentlich ein zweites Mal gelesen. Ein erneut gelesenes Dokument wird unter dem Namen seiner
-  Datei gezeigt, nie unter einem Code. Ein aus der Strom-App gesendetes Dokument findet den Agenten wie das Terminal —
-  auch einen in einem eigenen Ordner, über npm oder Homebrew installierten —, statt zu melden, es sei kein Agent
-  eingerichtet.
+- **Ein Dokument auf einmal gelesen.** `strom document read` liest ein Foto, einen Scan oder eine PDF eines Dokuments —
+  einen Matrikeleintrag, einen Brief, eine Urkunde, einen Grabstein, die Rückseite eines Fotos: die Abschrift Wort für
+  Wort, ihre Übersetzung, was alte Wörter und Abkürzungen bedeuten, und die genannten Personen, samt wem im Stammbaum
+  sie entsprechen können. Nichts wird ergänzt: ein Name, der nicht im Dokument steht, fällt weg — auch ein Nachname, nie
+  vom Vater oder aus einer anderen Familie genommen —, Unleserliches wird markiert; ein zweiter Leser kann blind lesen.
+  Ein Dokument auf einem amtlichen Formular, etwa eine Geburtsurkunde, behält seine Personen — das Kind und beide
+  Eltern mit ihrem Anteil —, und ein früher gelesenes Dokument zeigt sie nach dem Update, ohne erneut gelesen zu werden.
+  Jede Person und jedes Ereignis kommt mit der Stelle auf der Seite, an der es steht, so zeigt die Strom-App von jedem
+  einen eigenen Ausschnitt.
+  In den Stammbaum gelangt nichts von selbst. Ein schon gelesenes Dokument sagt es, so wird es nicht versehentlich ein
+  zweites Mal gelesen. Ein erneut gelesenes Dokument wird unter dem Namen seiner Datei gezeigt, nie unter einem Code.
+  Ein aus der Strom-App gesendetes Dokument findet den Agenten wie das Terminal — auch einen in einem eigenen Ordner,
+  über npm oder Homebrew installierten —, statt zu melden, es sei kein Agent eingerichtet. Jeder Agent, mit dem die
+  Forschung arbeitet, liest es, mit dem Modell und dem Aufwand, die für die Forschung eingestellt sind.
 - **Fotos vom Handy.** `strom phone on`, das nur ein Mensch einschaltet, lässt ein Handy im Heimnetz (WLAN oder
   Kabel — nie ein Mobilfunknetz oder ein VPN) zu diesem Computer. Das Handy wird einmal per QR-Code gekoppelt; seine
   Seite fotografiert dann oder wählt aus der Galerie und schickt die Fotos ganz in einen Stammbaum der Forschung, mit

package/CHANGELOG.md

@@ -7,7 +7,7 @@ The changes of each version in short. The full notes and the install lines are o
 
 ## 1.18.0
 
-*In preparation: the betas up to 1.18.0-beta.11. The section is complete with the release.*
+*In preparation: the betas up to 1.18.0-beta.13. The section is complete with the release.*
 
 - **Phone photos upright.** A photo turned by its EXIF orientation is read as it is meant to be seen, upright; the
   places marked on it (excerpts, the halves of a spread, a cut-out part) are of the picture as it is shown. The
@@ -18,12 +18,16 @@ The changes of each version in short. The full notes and the install lines are o
   help; `strom tidy` clears the converted pictures away after 30 days or above 500 MB.
 - **One document read at once.** `strom document read` reads a photo, a scan or a PDF of one document — a register
   entry, a letter, a deed, a gravestone, the back of a photo: the transcript word for word, its translation, what its
-  old words and abbreviations mean, and the people it names, with who of the tree they may be. Nothing is filled in:
-  a name the document does not have is left out — a surname too, never taken from a father or another family —,
-  what cannot be read is marked; a second reader can read it blind. Nothing of it enters the tree by itself. A
-  document read already says so, so it is not read a second time by mistake. A document read again is shown under
-  the name of its file, never a code. A document sent from the Strom app finds the agent as the terminal does — one
-  installed in a folder of its own, by npm or Homebrew too — instead of saying no agent is set up.
+  old words and abbreviations mean, and the people it names, with who of the tree they may be. Nothing is filled in: a
+  name the document does not have is left out — a surname too, never taken from a father or another family —, what
+  cannot be read is marked; a second reader can read it blind. A
+  document on a printed form, as a birth certificate, keeps its people — the child and both parents with their part in
+  it —, and a document read before shows them after the update with nothing read again. Each person and event it names
+  comes with the place on the page where it stands, so the Strom app shows each its own excerpt. Nothing of it enters the tree by itself. A document read
+  already says so, so it is not read a second time by mistake. A document read again is shown under the name of its
+  file, never a code. A document sent from the Strom app finds the agent as the terminal does — one installed in a
+  folder of its own, by npm or Homebrew too — instead of saying no agent is set up. Every agent the research works with
+  reads it, with the model and effort set for the research.
 - **Photos from a phone.** `strom phone on`, turned on by the person alone, lets a phone on the home network (Wi-Fi
   or a cable — never a mobile network or a VPN) reach this computer. The phone is paired once by its QR code; its
   page then takes photos or picks them from the gallery and sends them whole into a tree of the research, with a

package/dist/commands/read.js

@@ -440,7 +440,8 @@ register({
             const own = path.join(work, `${stem}-${k + 1}`);
             fs.mkdirSync(own, { recursive: true });
             const settingsFile = path.join(own, "reader-settings.json");
-            fs.writeFileSync(settingsFile, JSON.stringify(readerSettings(group.flatMap((g) => [g.view, ...(g.parts ?? []).map((p) => p.view)]), report, permissionPath), null, 2));
+            const seen = group.flatMap((g) => [g.view, ...(g.parts ?? []).map((p) => p.view)]);
+            fs.writeFileSync(settingsFile, JSON.stringify(readerSettings(seen, report, permissionPath), null, 2));
             const context = typeof opts.context === "string" && opts.context.trim() ? `Context: ${opts.context.trim().replace(/\s*\n\s*/g, " ")}\n` : "";
             // a blind reading says so in its head: its "unclear" over a place the researcher looked at before is a check
             const head = `# Reading ${label} · batch ${k + 1}${fetching ? "" : ` of ${groups.length}`}\nQuestion: ${question.replace(/\s*\n\s*/g, " ")}\n${context}${opts.blind ? "Blind: yes\n" : ""}\n${NEXT_BLOCK}\n`;
@@ -459,6 +460,7 @@ register({
                 env: { ...withoutAgentMarks(env), STROM_NONINTERACTIVE: "1", STROM_READER: "1" },
                 settingsFile,
                 reader: true,
+                readerFiles: { views: seen, report },
                 // without the user's own add-ons (skills, plugins, MCP servers) unless they said otherwise
                 ...(ctx.settings.agentAddons(tree.config) ? {} : { clean: true }),
                 timeoutMs: minutes * 60_000,

package/dist/commands/readers.js

@@ -135,6 +135,7 @@ export function readers(ctx, tree, shared, kind, first, opts, reportsAt, own = {
             env: { ...withoutAgentMarks(env), STROM_NONINTERACTIVE: "1", STROM_READER: "1" },
             settingsFile,
             reader: true,
+            readerFiles: { views, report },
             // without the user's own add-ons (skills, plugins, MCP servers) unless they said otherwise
             ...(ctx.settings.agentAddons(tree.config) ? {} : { clean: true }),
             timeoutMs: limit.minutes * 60_000,

package/dist/core/document.js

@@ -110,12 +110,15 @@ term: <a word or abbreviation as written> = <what it means, in ${into}> (term |
   — one line each, for the old words, formulas, abbreviations, occupations, and on a gravestone its symbols
 `}person: <ref> | <role> | ${blind ? "" : `<the role in ${into}> | `}written=<the name exactly as it stands in the transcript> | given=<the given
   name in today's form> | surname=<the surname in today's form> | sex=M|F|U | age=<as written> | occupation=<…> |
-  residence=<…> — one line each person named; ref p1, p2, … in this entry; role: ${ROLES.join(", ")};
+  residence=<…> | region=x,y,w,h — one line each person named; ref p1, p2, … in this entry; role: ${ROLES.join(", ")};
   given and surname only turn the written name into today's form ("Joannes" → "Jan"): never a name the transcript
   does not have — no surname the entry does not write by the person (a child's is not taken from its father's);
-  a name you could not read stays out; leave out what the entry does not say
+  on a form (a certificate) whose fields hold a name apart, written= the words of its fields as written there;
+  a name you could not read stays out; leave out what the entry does not say; region: where the person's name
+  stands — its line, or its field on a form — as the entry's region, of the page's whole view (tight, not the entry)
 event: <BIRT | BAPM | MARR | DEAT | BURI | RESI | EVEN> | date=<as on the record, in numbers: 3.4.1846, or a year> |
-  place=<the place as written> | persons=<ref>:<principal|father|mother|godparent|witness|groom|bride|deceased|other>,…
+  place=<the place as written> | persons=<ref>:<principal|father|mother|godparent|witness|groom|bride|deceased|other>,… |
+  region=x,y,w,h — where its date (and place) stand, as a person's region
 relation: parent <ref of the parent> <ref of the child>  — or —  spouse <ref> <ref>
 ${blind
         ? ""
@@ -259,12 +262,18 @@ export function parseDocReport(text) {
             const ref = /^p\d+$/iu.test(parts[0].trim()) ? parts.shift().trim().toLowerCase() : `p${entry.persons.length + 1}`;
             const role = parts[0] && !parts[0].includes("=") ? parts.shift().trim().toLowerCase() : "other";
             const roleText = parts[0] && !parts[0].includes("=") ? parts.shift().trim() : undefined;
-            entry.persons.push({ ref, role, ...(roleText ? { roleText } : {}), fields: pairs(parts) });
+            const fields = pairs(parts);
+            const region = parseRegion(fields.region);
+            delete fields.region;
+            entry.persons.push({ ref, role, ...(roleText ? { roleText } : {}), ...(region ? { region } : {}), fields });
         }
         for (const e of fields.get("event") ?? []) {
             const parts = e.split(/\s*\|\s*/u);
             const type = parts[0] && !parts[0].includes("=") ? parts.shift().trim() : "EVEN";
-            entry.events.push({ type, fields: pairs(parts) });
+            const fields = pairs(parts);
+            const region = parseRegion(fields.region);
+            delete fields.region;
+            entry.events.push({ type, ...(region ? { region } : {}), fields });
         }
         for (const r of fields.get("relation") ?? []) {
             const w = r.split(/[\s,]+/u).filter(Boolean);
@@ -280,6 +289,9 @@ export function parseDocReport(text) {
 /** A kind a reader wrote in its own words: the nearest of the list. */
 function kindOf(said) {
     const f = foldText(said);
+    // a certificate first: a birth certificate is no register of births ("rodný list", "Geburtsurkunde", "odpis aktu")
+    if (/certif|urkunde|zaswiadcz|odpis|extrait|auszug|vypis|(?:rodn|oddac|umrtn)\p{L}*\s+list/u.test(f))
+        return "certificate";
     if (/bapt|krest|tauf|chrzest|christen/u.test(f))
         return "register.baptism";
     if (/birth|narozen|geburt|urodzen/u.test(f))
@@ -327,6 +339,29 @@ function find(whole, part) {
     }
     return -1;
 }
+/**
+ * Where the words of `part` stand in `whole` apart — a form's fields, the surname in one and the given names in
+ * another —: each at a place of its own, after the word before where it can be; undefined when one is not there
+ * (a word not read, "[...]", is never found apart).
+ */
+function findApart(whole, part) {
+    if (!part.length || part.some((w) => w.illegible))
+        return undefined;
+    const used = new Set();
+    const out = [];
+    let from = 0;
+    for (const w of part) {
+        let i = whole.findIndex((x, k) => k >= from && !used.has(k) && x.key === w.key);
+        if (i < 0)
+            i = whole.findIndex((x, k) => !used.has(k) && x.key === w.key);
+        if (i < 0)
+            return undefined;
+        used.add(i);
+        out.push(whole[i]);
+        from = i + 1;
+    }
+    return out;
+}
 /** A name's word in letters alone (folded): Latin and old spellings as today's (ph f, th t, w v, y i, j i, ae e). */
 function spelled(key) {
     return key
@@ -458,7 +493,8 @@ export function gedcomDate(text) {
 }
 /**
  * A reader's entry as strom gives it on: each person's written name must stand in the transcript (folded — no
- * accents, no case — as words in a row), else the person is left out; its surname must be a form of one of those
+ * accents, no case — as words in a row; on a form, `form`, each word in a field of its own), else the person is left
+ * out; its surname must be a form of one of those
  * words in the form of the person's sex, else it is left out (a surname of another person, of the parish's head, of
  * nowhere, a woman's form for a man written in a man's); its given name in
  * today's form must be of the letters of the others, else the name is as written and the reader's form a lead
@@ -466,7 +502,7 @@ export function gedcomDate(text) {
  * transcript marks "[?]" is uncertain, one it marks "[...]" all through is left out (the reader cannot have read it);
  * a date of "[...]" has no GEDCOM; references to people left out go too. What was left out is said (checks).
  */
-export function checkEntry(raw, id, blind = false) {
+export function checkEntry(raw, id, blind = false, form = false) {
     const checks = [];
     const text = words(raw.transcript);
     const persons = [];
@@ -478,11 +514,13 @@ export function checkEntry(raw, id, blind = false) {
         }
         const w = words(written);
         const at = find(text, w);
-        if (at < 0) {
+        // a form (a certificate) holds a name in its fields apart — the surname in one, the given names in another —:
+        // its words each written there are the name; elsewhere a name stands in a row as written
+        const span = at >= 0 ? text.slice(at, at + w.length) : form ? findApart(text, w) : undefined;
+        if (!span) {
             checks.push({ entry: id, ref: p.ref, what: written, why: "not-in-transcript" });
             continue;
         }
-        const span = text.slice(at, at + w.length);
         const role = (ROLES.includes(p.role) ? p.role : "other");
         const person = { ref: p.ref, role, written: span.map((x) => x.text).join(" ") };
         if (p.roleText && !blind)
@@ -544,6 +582,9 @@ export function checkEntry(raw, id, blind = false) {
         }
         if (uncertain.size)
             person.uncertain = [...uncertain];
+        const region = partOf(p.region, raw.region);
+        if (region)
+            person.region = region;
         persons.push(person);
     }
     const refs = new Set(persons.map((p) => p.ref));
@@ -573,6 +614,9 @@ export function checkEntry(raw, id, blind = false) {
         }
         if (uncertain.size)
             ev.uncertain = [...uncertain];
+        const region = partOf(e.region, raw.region);
+        if (region)
+            ev.region = region;
         events.push(ev);
     }
     const relations = [];
@@ -593,6 +637,24 @@ export function checkEntry(raw, id, blind = false) {
         entry.glossary = raw.terms;
     return { entry, checks };
 }
+/** A name's or a date's line is no more than a quarter of the page. */
+const PART_AREA = 0.25;
+/** How far a part may lie out of its entry's region (a reader's regions are rough). */
+const PART_SLACK = 0.05;
+/**
+ * A person's or an event's region as a reader gave it, where it can be one: a part of the page no bigger than a
+ * quarter of it, that lies (roughly) in its entry's region; else none — the app shows the entry's region then.
+ */
+function partOf(r, entry) {
+    if (!r || r[2] * r[3] > PART_AREA)
+        return undefined;
+    if (!entry)
+        return r;
+    const [x, y, w, h] = [entry[0] - PART_SLACK, entry[1] - PART_SLACK, entry[2] + 2 * PART_SLACK, entry[3] + 2 * PART_SLACK];
+    const across = Math.min(r[0] + r[2], x + w) - Math.max(r[0], x);
+    const down = Math.min(r[1] + r[3], y + h) - Math.max(r[1], y);
+    return across > 0 && down > 0 ? r : undefined;
+}
 // ── two readers ───────────────────────────────────────────────────────────────────────────────────────────────────
 /** The hunks where two transcripts differ, word by word (their keys; the marks [?] are no difference). */
 export function wordDiff(a, b) {
@@ -630,6 +692,46 @@ export function wordDiff(a, b) {
     return out;
 }
 const same = (a, b) => foldText(a ?? "") === foldText(b ?? "");
+/**
+ * The people of one reader paired with the other's by the name written, the best match first: the whole name alike,
+ * else the most of its words shared, a word of the surname weighing more. A person two match equally well (a father
+ * and his son of one given name, two of the same name) is paired with none — missing on one side rather than another
+ * one's. Index in `mine` → index in `theirs`.
+ */
+function pairByName(mine, theirs) {
+    const keys = (p) => words(p.written).filter((x) => !x.illegible).map((x) => x.key);
+    const surname = (p) => words(p.surname ?? "").map((x) => x.key);
+    const WHOLE = 1000;
+    const score = (p, q) => {
+        const a = keys(p);
+        const b = keys(q);
+        if (a.length && a.join(" ") === b.join(" "))
+            return WHOLE;
+        const other = new Set(b);
+        const sur = new Set([...surname(p), ...surname(q)]);
+        let n = 0;
+        for (const k of new Set(a))
+            if (other.has(k))
+                n += sur.has(k) ? 2 : 1;
+        return n;
+    };
+    let open = mine.flatMap((p, i) => theirs.map((q, j) => ({ i, j, s: score(p, q) }))).filter((x) => x.s > 0);
+    const out = new Map();
+    while (open.length) {
+        const best = Math.max(...open.map((x) => x.s));
+        const top = open.filter((x) => x.s === best);
+        const done = { i: new Set(), j: new Set() };
+        for (const x of top) {
+            // equally good for either side: a tie, neither paired
+            if (!top.some((y) => y !== x && (y.i === x.i || y.j === x.j)))
+                out.set(x.i, x.j);
+            done.i.add(x.i);
+            done.j.add(x.j);
+        }
+        open = open.filter((x) => !done.i.has(x.i) && !done.j.has(x.j));
+    }
+    return out;
+}
 /**
  * The first reader's entries against the blind reader's: paired by page and order; the transcripts word by word, the
  * people by role and order (given name, surname), the events by type and order (date, place). Where they differ is a
@@ -650,6 +752,7 @@ export function compareReadings(first, blind) {
         used.set(e.page, k + 1);
         const b = other.get(e.page)?.[k];
         const variants = [];
+        const regions = new Map();
         if (!b)
             variants.push({ field: "entry", at: e.id, other: "" });
         else {
@@ -663,20 +766,41 @@ export function compareReadings(first, blind) {
             };
             const theirs = groups(b.persons);
             const seen = new Map();
+            const fields = (p, q) => {
+                for (const f of ["given", "surname"])
+                    if (!same(p[f], q[f]))
+                        variants.push({ field: `${p.ref}.${f}`, at: p[f] ?? "", other: q[f] ?? "" });
+                // where the name stands: the first reader's, else the blind one's of the same person
+                if (!p.region && q.region)
+                    regions.set(p, q.region);
+            };
+            const alone = [];
             for (const p of e.persons) {
                 const i = seen.get(p.role) ?? 0;
                 seen.set(p.role, i + 1);
                 const q = theirs.get(p.role)?.[i];
-                if (!q) {
+                if (q)
+                    fields(p, q);
+                else
+                    alone.push(p);
+            }
+            // a person the blind reader gave another role (other / writer): the same one by the name written, the role a
+            // variant as its other fields
+            const left = [...theirs].flatMap(([role, qs]) => qs.slice(seen.get(role) ?? 0));
+            const pairs = pairByName(alone, left);
+            for (const [i, p] of alone.entries()) {
+                const j = pairs.get(i);
+                if (j === undefined) {
                     variants.push({ field: `${p.ref}`, at: [p.given, p.surname].filter(Boolean).join(" ") || p.written, other: "" });
                     continue;
                 }
-                for (const f of ["given", "surname"])
-                    if (!same(p[f], q[f]))
-                        variants.push({ field: `${p.ref}.${f}`, at: p[f] ?? "", other: q[f] ?? "" });
+                const q = left[j];
+                variants.push({ field: `${p.ref}.role`, at: p.role, other: q.role });
+                fields(p, q);
             }
-            for (const [role, qs] of theirs)
-                for (const q of qs.slice(seen.get(role) ?? 0))
+            const taken = new Set(pairs.values());
+            for (const [j, q] of left.entries())
+                if (!taken.has(j))
                     variants.push({ field: "person", at: "", other: [q.given, q.surname].filter(Boolean).join(" ") || q.written });
             const evs = new Map();
             for (const ev of e.events) {
@@ -687,6 +811,8 @@ export function compareReadings(first, blind) {
                     variants.push({ field: ev.type, at: ev.date?.text ?? ev.type, other: "" });
                     continue;
                 }
+                if (!ev.region && q.region)
+                    regions.set(ev, q.region);
                 if ((ev.date?.gedcom ?? ev.date?.text) !== (q.date?.gedcom ?? q.date?.text) && !same(ev.date?.text, q.date?.text))
                     variants.push({ field: `${ev.type}.date`, at: ev.date?.text ?? "", other: q.date?.text ?? "" });
                 if (!same(ev.place?.text, q.place?.text))
@@ -696,7 +822,8 @@ export function compareReadings(first, blind) {
         const agree = variants.length ? "differ" : "same";
         if (variants.length)
             all = false;
-        return { ...e, agree, ...(variants.length ? { variants } : {}) };
+        const placed = (x) => (regions.has(x) ? { ...x, region: regions.get(x) } : x);
+        return { ...e, persons: e.persons.map(placed), events: e.events.map(placed), agree, ...(variants.length ? { variants } : {}) };
     });
     // entries only the blind reader has
     for (const [page, list] of other)
@@ -881,6 +1008,37 @@ export function alive(pid) {
     }
 }
 const LEGIBLE_ORDER = { yes: 0, partly: 1, no: 2 };
+/** A variant of a person's role (`p2.role`): no words of the transcript. */
+const ROLE_VARIANT = /^[\p{L}\p{N}_-]+\.role$/u;
+/**
+ * The result as the Strom app is given it (GET /read/<id>): a variant of a person's role is no words of the
+ * transcript, and the app (3.14) marks each variant where its words stand in the transcript and counts it as a
+ * difference — a role code ("other") stood inside "Mother". So the role the blind reader gave goes to the person
+ * (`blindRole`) and out of `variants`; the result kept and `strom document show` keep it as a variant.
+ */
+export function resultForApp(r) {
+    return {
+        ...r,
+        entries: r.entries.map((e) => {
+            const roles = new Map();
+            for (const v of e.variants ?? [])
+                if (ROLE_VARIANT.test(v.field))
+                    roles.set(v.field.slice(0, -".role".length), v.other);
+            if (!roles.size)
+                return e;
+            const variants = (e.variants ?? []).filter((v) => !ROLE_VARIANT.test(v.field));
+            const { variants: _, ...rest } = e;
+            return {
+                ...rest,
+                ...(variants.length ? { variants } : {}),
+                persons: e.persons.map((p) => {
+                    const other = roles.get(p.ref);
+                    return other && ROLES.includes(other) ? { ...p, blindRole: other } : p;
+                }),
+            };
+        }),
+    };
+}
 /**
  * The result of a reading as it stands (while its readers write too: what they wrote so far): the first reader's
  * entries checked and matched with the tree, the blind reader's held against them.
@@ -921,13 +1079,19 @@ export function buildResult(tree, s) {
             }
             for (const e of rep?.entries ?? []) {
                 const id = `e${out.length + 1}`;
-                const c = checkEntry(e, id, blind);
+                const c = checkEntry(e, id, blind, rep?.doc.kind === "certificate");
                 if (!blind)
                     checks.push(...c.checks);
                 // a region of a part asked (--region): of the whole page
                 const page = s.pages.find((p) => p.n === e.page);
-                if (c.entry.region && page?.region)
-                    c.entry.region = within(page.region, c.entry.region);
+                if (page?.region) {
+                    const part = page.region;
+                    if (c.entry.region)
+                        c.entry.region = within(part, c.entry.region);
+                    for (const x of [...c.entry.persons, ...c.entry.events])
+                        if (x.region)
+                            x.region = within(part, x.region);
+                }
                 out.push(c.entry);
             }
         });

package/dist/core/live-read.js

@@ -15,7 +15,7 @@ import path from "node:path";
 import { spawn } from "node:child_process";
 import { newerTree, Tree } from "./tree.js";
 import { actsAsArchive } from "./state.js";
-import { APP_READ_FROM, alive, backBefore, buildResult, DOC_PAGES, FINAL_STATES, loadState, parseRegion, READ_ID, readsDir, reportPath, resultPath, saveState, shownName, statePath } from "./document.js";
+import { APP_READ_FROM, alive, backBefore, buildResult, DOC_PAGES, FINAL_STATES, loadState, parseRegion, READ_ID, readsDir, reportPath, resultForApp, resultPath, saveState, shownName, statePath } from "./document.js";
 import { knownOriginal } from "./originals.js";
 import { readableTypes } from "./readable.js";
 import { makeView } from "./views.js";
@@ -33,8 +33,6 @@ export const APP_READ_DEFAULT = { hour: 20, day: 60 };
 export const READ_QUEUE_MAX = 3;
 /** The largest file read (a page is read at 2000 px at most: a larger file adds nothing). */
 export const READ_MAX_BYTES = 50 * 1024 * 1024;
-/** The agents whose reader of documents was tried (the others wait for a live test: why agent.untested). */
-export const READ_TESTED = ["claude", "script"];
 /** The longest side of a page's picture for the app. */
 const PAGE_PX = 2000;
 const DAY_MS = 24 * 3600_000;
@@ -283,8 +281,6 @@ function notReady(tree, settings, env, seen, now) {
     const known = AGENTS.find((a) => a.id === agent);
     if (agent !== "script" && (!known || !findAgent(known.command, env)))
         return { why: "agent.none" };
-    if (!READ_TESTED.includes(agent))
-        return { why: "agent.untested" };
     // the last reading that ended: its agent out of its limit, or not signed in — until another reads
     const last = (seen ?? new ReadingsSeen(tree.root, env)).all().find((r) => r.state && FINAL_STATES.includes(r.state.state))?.state;
     if (last?.state === "failed") {
@@ -397,7 +393,8 @@ export class AppReadings {
             const n = this.none(id);
             return this.json(res, n.code, n.body);
         }
-        this.json(res, 200, { ...got.result, pages: got.result.pages.map((p) => ({ ...p, image: `read/${id}/page/${p.n}.jpg` })) });
+        const r = resultForApp(got.result);
+        this.json(res, 200, { ...r, pages: r.pages.map((p) => ({ ...p, image: `read/${id}/page/${p.n}.jpg` })) });
     }
     /** GET /read/<id>/page/<n>.jpg: the page upright as a JPEG of 2000 px at most (a HEIC's, a PDF's page too). */
     page(res, id, rest) {

package/dist/core/readsync.js

@@ -13,10 +13,17 @@ import { shownToFile } from "../image/image.js";
 import { inputPath, mimeOf, storeShared } from "./media.js";
 import { create, update } from "./records.js";
 import { foldText } from "./text.js";
-/** The reading's result as the research keeps it: its finished result (in git), else its state here when done. */
+/**
+ * The reading's result as the research keeps it: read here, from its readers' reports as the app is shown it (GET
+ * /read/<id>: a newer strom's checks on reports read before), else its finished result (in git — read on another
+ * computer).
+ */
 export function readingResult(tree, id) {
     if (!READ_ID.test(id))
         return undefined;
+    const s = loadState(tree.root, id);
+    if (s?.state === "done")
+        return buildResult(tree, s);
     try {
         const file = resultPath(tree.root, id);
         if (fs.existsSync(file))
@@ -25,8 +32,7 @@ export function readingResult(tree, id) {
     catch {
         // an unreadable result is none
     }
-    const s = loadState(tree.root, id);
-    return s?.state === "done" ? buildResult(tree, s) : undefined;
+    return undefined;
 }
 /**
  * The readings of an input (Input.read) as an agent is told of them: each one's ID and state here (its state on this

package/dist/core/tree.js

@@ -27,7 +27,7 @@ import { lastBackup } from "./backup.js";
 export const TREE_FILE = "strom.json";
 // between releases the candidate being made (a bridge run from the sources says what it is: the Strom app goes by it);
 // at a release the release's own (package.json)
-export const VERSION = "1.18.0-beta.11";
+export const VERSION = "1.18.0-beta.13";
 const GITIGNORE = `# Strom Research — local state and large files are not versioned
 .strom/
 /media/

package/dist/runners/antigravity.js

@@ -21,6 +21,7 @@ import path from "node:path";
 import { addResponses, heardResponse, runJsonLines, webUse } from "./jsonl.js";
 import { usageNumber, tellUsage, tellWeb } from "./runner.js";
 import { effortArgs } from "../agents/effort.js";
+import { DOC_NEXT } from "../core/document.js";
 /** Command-line arguments of a headless run (exported for tests); `first` is its first message. */
 export function antigravityArgs(opts, first) {
     return [
@@ -36,6 +37,30 @@ export function antigravityArgs(opts, first) {
         ...(opts.extraArgs ?? []),
     ];
 }
+/**
+ * A reader in agy: its views in its workspace (--add-dir: read without asking); never a skipped permission, whatever the
+ * level. agy refuses every file it would write in a headless run, its own folder's too (only rules in the person's
+ * settings would allow one, and strom writes none there): its report is its answer, which strom adds to the report
+ * (found live 2026-10-20 — the views refused outside its folder, then the report).
+ */
+export function antigravityReaderArgs(opts, files, first) {
+    const dirs = [...new Set(files.views.map((v) => path.dirname(path.resolve(v))))];
+    return antigravityArgs({ ...opts, permissions: "auto" }, first).flatMap((a, i, all) => (i === all.indexOf("stream-json") ? [a, ...dirs.flatMap((d) => ["--add-dir", d])] : [a]));
+}
+/** What a reader in agy is told beside its task: the report as its answer (exported for tests). */
+export function antigravityReaderNote(report) {
+    return (`\n\nHERE: this agent cannot write files. Do not edit ${report}: give every block you would add to it, in order, ` +
+        "as your final answer — the blocks alone, nothing before or after them — and strom adds them to the report.");
+}
+/** A reader's answer added to its report at its last line (DOC_NEXT), when it added nothing itself (exported for tests). */
+export function addReaderAnswer(report, answer, next) {
+    const text = fs.existsSync(report) ? fs.readFileSync(report, "utf8") : "";
+    const at = text.lastIndexOf(next);
+    if (at < 0 || !answer.trim() || text.slice(0, at).includes("## Document"))
+        return false;
+    fs.writeFileSync(report, `${text.slice(0, at)}${answer.trim()}\n${text.slice(at)}`);
+    return true;
+}
 /** The first message of a run whose brief is in a file (exported for tests). */
 export function antigravityFirstMessage(briefFile) {
     return (`Your brief for this strom session is the file ${briefFile}. Read that whole file first, every line of it ` +
@@ -94,6 +119,16 @@ export const antigravityRunner = {
             resume: (id, message, timeoutMs) => ({ args: antigravityGoOnArgs({ ...opts, timeoutMs }, id, message), input: "" }),
         };
         const web = { seen: new Set(), on: (w) => tellWeb(opts, w) };
+        const reader = opts.readerFiles;
+        if (reader) {
+            // a reader: its report is its answer, and it is never told to go on through strom
+            const args = antigravityReaderArgs(opts, reader, first + antigravityReaderNote(reader.report));
+            return runJsonLines("agy", args, opts.env, { ...opts, prompt: "" }, undefined, (msg, heard) => readEvent(msg, heard, said, opts.onProgress, opts.onUsage, web), { totalsAtEnd: true }).then((r) => {
+                if (r.outcome === "ok")
+                    addReaderAnswer(reader.report, r.text, DOC_NEXT);
+                return r;
+            });
+        }
         return runJsonLines("agy", antigravityArgs(opts, first), opts.env, { ...opts, prompt: "" }, undefined, (msg, heard) => readEvent(msg, heard, said, opts.onProgress, opts.onUsage, web), { totalsAtEnd: true, goOn });
     },
 };

package/dist/runners/codex.js

@@ -18,6 +18,14 @@ import { isolated } from "../core/paths.js";
 export function codexWritable(root, shared) {
     return ["-c", `sandbox_workspace_write.writable_roots=${JSON.stringify([path.join(root, ".git"), ...(shared ? [shared] : [])])}`];
 }
+/**
+ * A reader's sandbox: the folder of its report the one place it writes besides the folder it works in (found live: the
+ * report in the tree's notes/readings was refused, "writing outside of the project"), and no network — it reads the
+ * views it is given, it fetches nothing. Whatever the person's level: a reader opens its views and writes its report.
+ */
+export function codexReaderWritable(files) {
+    return ["-c", `sandbox_workspace_write.writable_roots=${JSON.stringify([path.dirname(path.resolve(files.report))])}`];
+}
 /**
  * The folder Codex works in, trusted for this process alone in an isolated installation: a session Codex starts in a
  * folder its config does not trust it records as trusted in ~/.codex/config.toml (`[projects."<folder>"]`, found
@@ -47,9 +55,11 @@ export function codexTrust(env, cwd) {
 export const CODEX_CLEAN = ["-c", "features.plugins=false", "-c", "features.apps=false", "-c", "features.hooks=false", "-c", "features.memories=false"];
 /** Command-line arguments of a headless run (exported for tests). */
 export function codexArgs(opts) {
-    const sandbox = opts.permissions === "full"
-        ? ["--dangerously-bypass-approvals-and-sandbox"]
-        : ["--sandbox", "workspace-write", "-c", "sandbox_workspace_write.network_access=true", ...codexWritable(opts.cwd, opts.shared)];
+    const sandbox = opts.readerFiles
+        ? ["--sandbox", "workspace-write", ...codexReaderWritable(opts.readerFiles)]
+        : opts.permissions === "full"
+            ? ["--dangerously-bypass-approvals-and-sandbox"]
+            : ["--sandbox", "workspace-write", "-c", "sandbox_workspace_write.network_access=true", ...codexWritable(opts.cwd, opts.shared)];
     return ["exec", "--json", "--skip-git-repo-check", ...sandbox, ...codexTrust(opts.env ?? {}, opts.cwd), ...(opts.clean ? CODEX_CLEAN : []), ...(opts.model ? ["--model", opts.model] : []), ...effortArgs("codex", opts.effort), ...(opts.extraArgs ?? []), "-"];
 }
 /**
@@ -57,9 +67,11 @@ export function codexArgs(opts) {
  * --sandbox or --add-dir: the same sandbox is set through its configuration.
  */
 export function codexResumeArgs(id, opts) {
-    const sandbox = opts.permissions === "full"
-        ? ["--dangerously-bypass-approvals-and-sandbox"]
-        : ["-c", 'sandbox_mode="workspace-write"', "-c", "sandbox_workspace_write.network_access=true", ...codexWritable(opts.cwd, opts.shared)];
+    const sandbox = opts.readerFiles
+        ? ["-c", 'sandbox_mode="workspace-write"', ...codexReaderWritable(opts.readerFiles)]
+        : opts.permissions === "full"
+            ? ["--dangerously-bypass-approvals-and-sandbox"]
+            : ["-c", 'sandbox_mode="workspace-write"', "-c", "sandbox_workspace_write.network_access=true", ...codexWritable(opts.cwd, opts.shared)];
     return ["exec", "resume", "--json", "--skip-git-repo-check", ...sandbox, ...codexTrust(opts.env ?? {}, opts.cwd), ...(opts.clean ? CODEX_CLEAN : []), ...(opts.model ? ["--model", opts.model] : []), ...effortArgs("codex", opts.effort), id, "-"];
 }
 /**

package/dist/runners/grok.js

@@ -35,6 +35,14 @@ export function grokTrust(env, reader) {
         return { args: [], env: {} };
     return isolated(env) ? { args: [], env: { GROK_FOLDER_TRUST: "0" } } : { args: ["--trust"], env: {} };
 }
+/**
+ * A reader's report, the one file it may write: dontAsk refuses an edit outside the folder it works in, and a reader
+ * works beside its views, its report in the tree (found live 2026-10-20: the report refused, the reading lost).
+ */
+export function grokReaderAllow(files) {
+    const report = path.resolve(files.report).replace(/\\/g, "/");
+    return ["--allow", `Edit(${report})`, "--allow", `Write(${report})`];
+}
 /** Command-line arguments of a headless run (exported for tests). */
 export function grokArgs(opts, prompt, session) {
     return [
@@ -42,7 +50,7 @@ export function grokArgs(opts, prompt, session) {
         ...prompt,
         "--output-format",
         "streaming-json",
-        ...(opts.permissions === "full" ? ["--always-approve"] : ["--permission-mode", "dontAsk"]),
+        ...(opts.readerFiles ? ["--permission-mode", "dontAsk", ...grokReaderAllow(opts.readerFiles)] : opts.permissions === "full" ? ["--always-approve"] : ["--permission-mode", "dontAsk"]),
         ...session,
         ...(opts.model ? ["--model", opts.model] : []),
         ...effortArgs("grok", opts.effort),

package/dist/runners/opencode.js

@@ -7,11 +7,48 @@
 // (everything the rules do not deny). Events are JSON lines: text, tool_use,
 // step_start, step_finish (tokens and cost of a step), error; each names its
 // session (sessionID), which `--session` resumes.
+import path from "node:path";
 import { runJsonLines, webUse } from "./jsonl.js";
 import { OPENCODE_RUN_AGENT } from "../agents/files.js";
 import { usageNumber, tellUsage, tellWeb } from "./runner.js";
 /** OpenCode's own web tools (OpenCode 2: webfetch with its url, websearch with its query), counted once each call is done. */
 export const OPENCODE_WEB = { page: ["webfetch"], search: ["websearch"] };
+/** OpenCode's agent of a reader, given for its run alone (OPENCODE_CONFIG_CONTENT): no tree's config is where it works. */
+export const OPENCODE_READER_AGENT = "strom-reader";
+/** A reader's message: its task comes on stdin, joined with it. */
+const READER_KICKOFF = "Your task is above: open the pages it names and write your report as it says.";
+/**
+ * A reader's agent (exported for tests): it opens its views and edits its report — every other file, the shell, the
+ * web, subagents and questions refused (refused, never asked: OpenCode 2 ends a headless run at a question). Paths with
+ * forward slashes, as OpenCode matches them.
+ */
+export function opencodeReaderConfig(files) {
+    const abs = (p) => path.resolve(p).replace(/\\/g, "/");
+    const only = (paths) => ({ "*": "deny", ...Object.fromEntries(paths.map((p) => [p, "allow"])) });
+    const report = abs(files.report);
+    const views = files.views.map(abs);
+    return {
+        agent: {
+            [OPENCODE_READER_AGENT]: {
+                mode: "primary",
+                description: "a reader of strom: opens the views it is given, writes its report — nothing else",
+                permission: {
+                    read: only([...views, report]),
+                    edit: only([report]),
+                    external_directory: only([...new Set([...views, report].map((f) => `${path.posix.dirname(f)}/*`))]),
+                    ...Object.fromEntries(["bash", "webfetch", "websearch", "task", "question", "skill", "todowrite", "glob", "grep", "list"].map((t) => [t, "deny"])),
+                },
+            },
+        },
+    };
+}
+/**
+ * Command-line arguments of a reader (exported for tests): a server of its own (--standalone — never the person's
+ * background service, which another installation's settings may have started: found live, its port taken), its agent.
+ */
+export function opencodeReaderArgs(opts) {
+    return ["run", "--standalone", "--format", "json", "--agent", OPENCODE_READER_AGENT, ...(opts.model ? ["--model", opts.model] : []), ...(opts.extraArgs ?? []), READER_KICKOFF];
+}
 /** Command-line arguments of a headless run (exported for tests). */
 export function opencodeArgs(opts) {
     const level = opts.permissions === "full" ? ["--auto"] : ["--agent", OPENCODE_RUN_AGENT];
@@ -21,14 +58,17 @@ export const opencodeRunner = {
     id: "opencode",
     command: "opencode",
     run(opts) {
-        const args = opencodeArgs({ ...opts, kickoff: "Your brief is above. Work only through `strom` in this folder, as it says." });
+        // a reader: its own agent and rules, given for this run (no tree's opencode.json where it works)
+        const reader = opts.readerFiles;
+        const env = reader ? { ...opts.env, OPENCODE_CONFIG_CONTENT: JSON.stringify(opencodeReaderConfig(reader)) } : opts.env;
+        const args = reader ? opencodeReaderArgs(opts) : opencodeArgs({ ...opts, kickoff: "Your brief is above. Work only through `strom` in this folder, as it says." });
         const tokens = { input: 0, output: 0, cacheRead: 0 };
         let main;
         // the web tools' calls passed on (a call is said again as its state changes)
         const webSeen = new Set();
         // Resumed: its session by id, the message as the prompt.
-        const resume = (id, message) => ({ args: [...opencodeArgs({ ...opts, kickoff: message }).slice(0, -1), "--session", id, message], input: "" });
-        return runJsonLines("opencode", args, opts.env, opts, resume, (msg, heard) => {
+        const resume = (id, message) => ({ args: [...(reader ? opencodeReaderArgs(opts) : opencodeArgs({ ...opts, kickoff: message })).slice(0, -1), "--session", id, message], input: "" });
+        return runJsonLines("opencode", args, env, opts, resume, (msg, heard) => {
             const part = (msg.part ?? {});
             // the run's own session is the first one named; another one is a subagent's (its scan reader) — the run's own
             // is the one resumed at the time limit, never the subagent's that spoke last

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "strom-research",
-  "version": "1.18.0-beta.11",
+  "version": "1.18.0-beta.13",
   "description": "Genealogical research toolkit for AI coding agents",
   "type": "module",
   "bin": {