strom-research 1.0.0

package/assets/method/core.md

@@ -0,0 +1,43 @@
+# Method: the core
+
+You work to the Genealogical Proof Standard: search thoroughly, cite every
+fact, analyse and correlate the evidence, resolve conflicts, and write the
+conclusion so the next researcher can follow it.
+
+- **Certainty is explicit.** `proven` — you read the original record yourself
+  and it states the fact directly. `probable` — good evidence, but indirect or a
+  single reading of hard handwriting. `possible` — weak evidence. `lead` — a
+  family story, a family tree, an index or a guess: something to check, never a
+  fact. Family trees and memories are leads, always.
+- **A namesake is not your person.** Identify by year, place, house, occupation,
+  spouse and parents — the mother's maiden name decides most cases. Two entries
+  that give one name different parents (another mother) are **two people** —
+  even in the same house, with the same father's name. Never explain the
+  difference away as a clerk's error, never decide by majority. Your person is
+  who the entry about your person's own family names; the others are separate
+  persons, and "the same woman?" is a hypothesis (`strom hypothesis add`) with
+  what would decide it.
+- **Negative results are results.** Every search is recorded (`strom search add
+  … --result negative`), with exactly what was covered. The most expensive
+  mistake is to search the same book twice.
+- **Check the premise first.** Before opening anything: `strom searched <where>`.
+- **Extract everything the first time** you open a record: names, ages, house
+  numbers, occupations, godparents, witnesses, midwife, remarks in the margin.
+  Opening the same page again later costs more than writing it down now.
+- **Nothing is deleted.** A wrong fact is retracted with a reason; a changed
+  fact is edited with a reason. Contradictions become conflicts, competing
+  explanations become hypotheses — never silently pick one.
+- **Write as you go.** Record each finding as soon as you have it. Your context
+  can be cut or summarised at any moment; what is only in the conversation is
+  lost, what is in strom is not.
+- **Lessons belong where they apply.** A quirk of a register (its calibration,
+  two years per page, a hand that writes 7 like 1) goes to `strom lesson add
+  --on B…`, so whoever opens that book next sees it.
+- **Stay within the task.** New questions become new tasks (`strom task add`,
+  with where and done-when), not detours. A new task whose images are not here
+  gets them now: through the archive's connector (built first when it has
+  none), or — where the archive allows only that — it waits at once for what
+  the user should download (`strom task wait T… --images B…:<numbers> --on
+  "…"`); a later session would only find that out.
+- **Hand over cleanly.** Close with a summary of what was proven, what was
+  searched in vain, and the next cheapest step.

package/assets/method/enrich.md

@@ -0,0 +1,11 @@
+# Method: enriching a person
+
+The person is placed in the tree; now give them a life: occupations, every
+house they lived in, siblings, godparents, military service, land, events in
+the village. Each detail is a fact with a citation.
+
+- Work outward from records already found: the same book usually holds the
+  siblings and the next generation.
+- Keep the certainty honest: a house number from a baptism of a sibling is
+  evidence about the family at that date, not about the person's whole life.
+- Record what you learn about the place and the books as lessons.

package/assets/method/intake.md

@@ -0,0 +1,30 @@
+# Method: processing an input
+
+An input is material the user gave you: scans, photos, documents, notes, a
+family tree. Your job is to turn it into evidence without inventing anything.
+
+1. `strom input show I…` — read the file (images and PDFs directly, text is
+   shown). Identify who it is about and what kind of document it is.
+2. **What is it?** An original civil or church document (birth, marriage or
+   death certificate, extract from a register, military papers) is a **source**
+   and can prove facts: `strom source add … --input I… --form original
+   --information primary` (primary if written at the time of the event).
+   A photo, letter, family tree or someone's memory is authored or derivative:
+   everything taken from it stays a **lead**. What the user tells you is
+   `strom source add "<what it is>" --kind family-memory --form authored
+   --information secondary --input I…`; a family tree is `--kind family-tree`.
+   Many facts from one input: one `strom batch --file notes/<input>.txt`
+   (try it with `--dry-run` first).
+3. Record every person and every fact it states, with a citation to the source
+   (`--cite S… --locator "…"`). Use the words of the record in `--quote`.
+4. Put names and places as they are written; normalise only dates.
+5. For imported family trees: check for duplicates and impossible dates, but do
+   not "correct" them from memory — they are leads. A person of the tree who is
+   already researched here (the brief lists the likely ones) is merged INTO the
+   researched person, which keeps its evidence: `strom person merge <ours>
+   <imported> --reason "…"` — their parents first (`strom family merge`). What
+   the tree says differently stays a lead or becomes a conflict, never a fact.
+6. Create the next tasks: where would the records that prove these leads be?
+   (`locate` if the archive or book is unknown, `link` if it is known.)
+7. Close the task with what came out of it (`strom task done T… --result "…"`;
+   its input is marked processed with it).

package/assets/method/link.md

@@ -0,0 +1,28 @@
+# Method: proving a link (parents, marriage)
+
+1. **Premise:** `strom searched B… --years …` and `strom task show T…` — if the
+   range was already covered completely, do not repeat it; say so and close.
+2. **Index before book.** Use an index to find the page, then read the entry in
+   the register itself. An index entry alone is a lead — and so is its absence:
+   an index is a copy, written by another hand. A near spelling of the surname
+   in the right house or years (one letter off, a similar-looking letter of the
+   old script) is a candidate to check in the register by its parents, not a
+   different family: ask for that page (`strom task wait`) before you rule it
+   out.
+3. **Calibrate** the book before counting pages: measure image ↔ page at two
+   distant places (`strom recordset calibrate B… --point 95=189 --point 300=611`).
+   Never compute a page you have not measured in a book that is not linear.
+4. **Identify** the person by year, place, house number, parents and, above
+   all, the mother's maiden name. Two people of the same name in one village
+   are common.
+5. **Cheapest route:** a death or burial entry gives age and often parents; a
+   marriage entry names both sets of parents and the ages of the couple; the age
+   column is an independent check of a birth year.
+6. **Extract the whole entry** (see core). Godparents and witnesses are often
+   relatives and prove the next link.
+7. **Record** (see "recording an entry"): source (with transcript in the
+   original language), facts with citations, names, family links, the search
+   (found or negative), lessons about the book. `proven` only for what you read
+   yourself and the entry states directly.
+8. Done when the entry is found and recorded — or the agreed range was searched
+   completely without it (negative search recorded).

package/assets/method/locate.md

@@ -0,0 +1,28 @@
+# Method: locating records
+
+Before anything can be proven you need to know where the records are.
+
+1. Place and time decide the jurisdiction. Record it: `strom place add …` and
+   `strom place jurisdiction L… --kind parish|civil|manor|district --from --to`.
+   Borders, parishes and names changed; a village may belong to different
+   parishes in different centuries.
+2. Find the holding archive or portal and the concrete book or collection:
+   `strom repo add …` (record its terms of use and whether automated download
+   is allowed), `strom recordset add … --places --years --kinds --access --url`.
+   A connector the user allowed for the portal finds its books for you:
+   `strom fetch <connector> --find "<place>" --years 1780-1850`.
+3. Respect the terms of every archive. Never scrape a portal whose terms forbid
+   it; if records are only on site or on request, the task becomes a `request`.
+4. Indexes, catalogues and online trees tell you where to look — they are not
+   evidence of the fact itself. Use a catalogue as a person would: a search or
+   the page of one book — never walk its record numbers one after another
+   (archives block that). A catalogue you cannot read (an app, a login): ask
+   the user — the archive, the village, the years, the kind of book — with
+   `strom task wait T… --on "…"`.
+5. Record where you looked, also what gave nothing: `strom search add "<what>"
+   --method web|catalog --result found|negative --task T…` — the next session
+   must not search the same catalogues again.
+6. Done when a record set with access (URL or call number) exists and the next
+   `link` task points at it: `strom task edit T… --where B…` for a task that
+   was written before the book was known, `strom task add … --where B…` for a
+   new one.

package/assets/method/narrate.md

@@ -0,0 +1,13 @@
+# Method: writing the story
+
+A story is written from the facts, for the family.
+
+- Every statement rests on a recorded fact; say which ones.
+- What is inferred is marked as inference; what is unknown is said to be
+  unknown. Never fill gaps with plausible fiction.
+- Use the research language and plain words; explain old occupations and
+  terms the reader will not know.
+- Write it to a file in notes/, then `strom story set P… --text @notes/story-P….md
+  --fact E… --fact E… --note "what is inferred"`: every fact it leans on goes
+  in --fact. A couple's story goes on the family (F…).
+- It stays a draft; `--final` only when the user approved it.

package/assets/method/reading.md

@@ -0,0 +1,62 @@
+# Method: reading scans
+
+An image you open stays in your context and is paid for again on every turn.
+Look at as few pixels as the question needs, and write down what you saw at once.
+
+- **Look only through views**: `strom media view B0001:57` (record set and
+  image number) makes a file in `.strom/views/` — open that file. Whole images
+  come reduced: good for "is our surname on this page?", not for reading.
+- **Find, then crop.** `--grid` overlays tenths with labels; read off where the
+  entry is and ask for exactly that part: `--crop 0.05,0.40,0.45,0.18` (x, y,
+  width, height as fractions) or `--half left|right` for one page of a spread.
+  A crop comes at full resolution (small ones enlarged). `--contrast` for faded
+  ink, `--rotate 90` for sideways pages.
+- **Too small to read?** When a crop says it is enlarged, the scan has no more
+  detail there. A connector that can fetch a part of an image sharper says so
+  in that line: `strom fetch <connector> --recordset B0001 --images 57 --crop
+  …` (one request). Then view the same crop again: it comes from the sharper
+  part by itself.
+- **Browsing a book is a reader's job**: `strom read B0001 --images 40-69
+  --question "…"` — readers in batches of ten, each with the full question;
+  their reports stay in notes/readings/ for the next session, you get the finds.
+  It waits for its readers (often ten minutes or more): run it in the
+  foreground and let it finish — your session ends with your turn, and
+  whatever is left running in the background ends with it.
+  (Your own subagents can read too, in batches of at most twelve — but what they
+  report is lost with your session unless you write it down.) Only the entries
+  that will be cited need your own eyes, at full resolution.
+- Old handwriting is decoded, not copied: never a weaker model for handwriting,
+  never a guess. "Illegible" is a valid and valuable answer.
+- **Extract everything the first time**: names, ages, house numbers,
+  occupations, godparents, witnesses, midwife, remarks in the margin.
+- **Report image by image, as you go**: the image and page, what was found (or
+  nothing), what was illegible and where, the hand, how sure each name is.
+- **Cite the image**: `strom source add … --media B0001:57 --locator "pag. 112,
+  2nd entry"`; a searched range goes in `strom search add … --pages 40-69`.
+- Page ↔ image: `strom recordset calibrate B0001 --point 57=112` (measured on
+  the image, never guessed); then `strom media view B0001 --page 112` works.
+- **No images here yet:** a connector for that archive
+  (`strom connector list`) fetches them through strom:
+  `strom fetch <connector> <book> --images 40-69 --recordset B0001` — only the
+  images you need, never a whole book "just in case".
+- **The archive has no connector yet: build one — now, you.** The user does
+  not know connectors exist and will not ask for one. Tell them in a sentence
+  ("for this archive I am preparing a downloader; it will fetch only the images
+  we need, slowly"), run `strom connector new <name> --url <portal>` and
+  follow its DISCOVERY.md (the portal's terms and robots.txt first, official
+  exports preferred), test it with `strom connector test`, then fetch. It is
+  built once per archive and serves every later task.
+- You never download from an archive yourself (curl, a script, your browser
+  tools) — only through a connector, paced by strom. The user saves images by
+  hand only where the archive does not allow automation (the connector then
+  finds books and gives links only) or where a check stops it. Ask with
+  `strom task wait T… --images B0001:40-69 --on "…"`: strom makes the folder
+  of the inbox they go into, shows it to the user with the book's link, and
+  checks the numbers of what arrives. Write `--on` for the user, in their
+  language, so that they need nothing else: the book (title, call number),
+  its link, which images as the portal's viewer counts them (or the pages and
+  years, where you know only those), and that each is saved named by its
+  number (40.jpg). Where the portal gives only a small image, add: zoom in on
+  the entry and save that view too (40a.jpg); a full-resolution scan can be
+  ordered from the archive. Then take the next task; when the images are
+  registered the task comes back by itself.

package/assets/method/recording.md

@@ -0,0 +1,59 @@
+# Method: recording an entry
+
+Record a found entry in one batch: write the lines to a file in notes/, run
+`strom batch --file notes/<file> --dry-run`, fix what it reports, then run it
+without --dry-run. `#name` labels what a line creates, `@name` uses it later.
+
+    source add "Baptism of Jan Novák 1885" --kind baptism --recordset B0001 --media B0001:57 --locator "pag. 112, entry 2" --language la --information primary --transcript @notes/entry.txt #s
+    event add P0001 CHR --date "25 JUN 1885" --place "Týnec" --house 13 --cite @s --quote "baptizatus est" --with "godparent:Marie Dvořáková" --with "midwife:Anna Nová" --with "officiant:P. Josef Kříž" --status proven
+    cite E0001 @s --quote "natus 24. Junii" --status proven
+    name add P0002 "Marie /Svobodová/" --kind birth --cite @s --quote "Maria filia Josephi Svoboda"
+    person add "Josef /Svoboda/" --sex M --cite @s --information secondary #josef
+    family add --partner @josef --child P0002 --cite @s --information secondary
+    search add "Baptism of Jan Novák" --recordset B0001 --years 1884-1886 --pages 55-60 --method page-by-page --result found --found @s
+
+- A fact already in the tree gets the citation (`cite E…`), not a second fact —
+  and what the record adds to it: `event edit E… --age husband:27 --age wife:17
+  --house 21 --with "witness:…" --with "officiant:…"` (filling in needs no reason).
+- The names a record gives go on the person: `name add` (a maiden name completes
+  "Marie" to "Marie /Svobodová/"; a married name is `--kind married`).
+- A record that names someone's parents (a grandchild's baptism naming the
+  grandparents) cites the family itself (`family add … --cite`, `cite F…`) and
+  the new people's names (`person add … --cite`) — with `--information
+  secondary`: the priest wrote down what he was told.
+- What the entry says about each person it names becomes that person's fact,
+  dated by the entry: an occupation `event add P… OCCU --value "cottager"`, where
+  they live `event add P… RESI --place "Týnec" --house 7` — for the
+  grandparents too ("daughter of Jan Novák, cottager in Týnec No. 7"), cited
+  `--information secondary`. The next search identifies them by exactly these.
+- Everyone the entry names in a role goes in `--with`: godparent, witness,
+  midwife, officiant, informant, other.
+- A child the record does not name (stillborn, died unbaptised) has no given
+  name — never a description in its place: `person add "/Novák/" --sex M`, then
+  `event add P… DEAT --date … --age stillborn` (or a `--note`).
+- Only what you read for sure goes into a field (`--date`, `--house`, `--age`,
+  `--cause`, a name). An uncertain word or digit is marked `[?]` in the
+  transcript and said in the fact's note ("house 21 or 27"); what a reader
+  reported as illegible stays illegible until you read it yourself. An empty
+  column is empty — nothing is filled in from what would be usual. A name
+  read only in part keeps its sure letters, `[?]` for the rest (`"Anna
+  /Kr[?]ková/"`), so the person can still be found; a date whose day is
+  unsure keeps the month (`--date "MAY 1850"`, note "12 or 17"). A
+  conclusion that stands on one hard cell (a house number, an age, a maiden
+  name) gets a blind second reading before it is `proven`: `strom read M…
+  --blind --crop x,y,w,h --question "Transcribe this entry"`.
+- A place is the settlement only ("Týnec", not "Týnec No. 13"): the house
+  number goes in `--house 13`.
+- What a finding means for other tasks: `strom task edit T… --note "…"`.
+- Records about one person disagree (a name, a date, an age): record both
+  claims and your reasoning — `strom conflict add "<question>" --about P…
+  --claim "S…:<what it says>" --claim "S…:<what the other says>"`. Records
+  that give different parents are first two people (see core); they are one
+  person with a conflict only once something else proves it. What would decide
+  it, if not at hand, is a task about it: `strom task add … --about X…` (or H…).
+  `strom conflict resolve X… --resolution "…" --reasoning "…"` when the
+  evidence decides it. A decided
+  hypothesis that a new record overturns is decided again (the earlier
+  decision is kept): `strom hypothesis decide H… --decision "…" --reason "…"`.
+  People named wrongly by the weaker record keep that name as a variant
+  (`name add … --primary` for the right one); they are not deleted.

package/assets/method/request.md

@@ -0,0 +1,10 @@
+# Method: requests to archives
+
+When records are not online, ask the holding archive.
+
+- Write the request in the archive's language, short and precise: whose record,
+  which type, parish or office, years, what you already know (call number if
+  known). Offer to pay the research fee if the archive charges one.
+- Save the text in `notes/` and tell the user — the user sends it, not you.
+- Put the task on `strom task wait T… --on "reply from …"`. When the answer
+  comes, it becomes an input (`strom intake …`).

package/assets/method/verify.md

@@ -0,0 +1,17 @@
+# Method: independent verification
+
+A conclusion that stands on one hard-to-read cell (a house number, an age, a
+first name) needs a second, independent reading.
+
+- The second reader must be **blind**: do not tell them the expected value, the
+  name, the place or why it matters. Ask only what is written in that cell.
+- One cell, one second reader — not the whole page again.
+- Before asking, check whether two readings already exist (`strom find`).
+- Certainty above "probable" only when two independent readings agree. When
+  they disagree, record a conflict with both readings.
+- An independent reading of an entry you cited: `strom read M… --blind --crop
+  x,y,w,h --question "Transcribe this entry completely; mark what is uncertain
+  with [?]"` — a reader who knows nothing of your conclusion reads it at full
+  resolution. Where it differs from your reading (a digit, a name), look again
+  at that spot; what stays uncertain goes into the note, and a real
+  disagreement between two readings is a conflict, not a choice.

package/assets/plugins/README.md

@@ -0,0 +1,23 @@
+# strom plugins
+
+Plugins extend strom on this computer: one folder per kind of plugin, and in
+it one folder per plugin. The folder's name is the plugin's name.
+
+    plugins/
+      connectors/              downloaders for archive portals
+        README.md              their interface (version 1)
+        example-archive/       one connector: connector.json and its program
+
+**Install** a plugin by copying its folder in: `strom connector list` shows it
+and it can run at once, paced by strom and only to the hosts it names. To be
+asked before any plugin runs: `strom config set connectors.consent on`. A
+plugin whose code goes round strom always needs your yes, in your terminal
+(`strom allow connector <name>`).
+
+**Build** one with your agent: `strom connector new <name> --url <portal>`.
+
+**Remove** one by deleting its folder (or `strom connector remove <name>`).
+
+Plugins are programs on this computer, put here by you: the `.gitignore` here
+keeps them out of any repository. strom writes this file, the `.gitignore` and
+`connectors/README.md`, and keeps them up to date.

package/assets/plugins/connectors/DISCOVERY.md

@@ -0,0 +1,159 @@
+# Building the connector for __TITLE__
+
+You (the agent) build a connector for __URL__ together with the user. Work in
+this folder only. The contract (interface 1) is `../README.md`: read it first.
+strom runs the connector; you never run it yourself, you test it with
+`strom connector test`. Talk to the user in their language.
+
+## 1. What does the portal allow? (before any code)
+
+- **Terms of use** (Nutzungsbedingungen, podmínky užití, regulamin, conditions
+  d'utilisation, a reading-room rule …): find them, quote the sentences about
+  automated or bulk download, copying and reuse, and note the URL.
+- **robots.txt** of each host: what is disallowed, and any crawl-delay.
+- **Official ways to get the images**: a download of a whole volume (ZIP or
+  PDF), IIIF manifests, an API, a published list of books. Prefer them: they
+  are what the archive wants people to use.
+- Write what you found into `connector.json` → `policy`:
+  - `terms` (the URL), `termsSummary` (one to three sentences, quoted where it
+    matters), `robots`, `officialExport`.
+  - `automation`, one of:
+    - `"allowed"`: the terms allow it or say nothing against it, and nothing
+      is got round.
+    - `"manual"`: the terms forbid automated or bulk download. The connector
+      only finds books and gives their links (`"can": ["find", "list"]`), and
+      the user downloads by hand into the inbox.
+    - `"unknown"`: you could not find out. Say so; the user decides.
+  - `pace`: slower than strom's default when the terms or robots.txt ask for
+    it, e.g. `{"minIntervalMs": 5000}` for a crawl-delay of 5.
+- **Never get round a technical measure**: logins you do not have, captchas,
+  or tokens meant to stop scripts. Tiles are how many viewers show big images;
+  they are a measure against downloading only when the terms or the portal
+  say so — then stop and tell the user.
+- **A bot check** (strom's probe says so: Imperva, Cloudflare — a page that
+  only runs a script): the portal answers a real browser only. Then the whole
+  connector goes through the user's browser: `"routes": ["browser"]` and
+  `"browser": {"pages": true}` (the contract, section 5), then
+  `strom connector use __NAME__ --via browser`. Browser tools come with your
+  next session; probes then go through the browser too. The user passes the
+  check in their own browser — never you. In the browser, look at the portal
+  as a person does, a page at a time; what you would script (a list of
+  addresses, a search to repeat) goes through `strom connector probe`, which
+  strom paces — not through fetch() in the tab.
+- Tell the user what you found **before** you write code.
+
+Read the portal with your web tools (pages, not images). Never download images
+yourself. Once the hosts are in `connector.json`, read the portal through strom
+as well: see step 2.
+
+## 2. Map the portal
+
+- **Finding books** → `find`: how to find the books of a place (a catalogue
+  search, a parish tree, an API). A search form is fine: send it with `post()`.
+- **One book** → `list` and `fetch`:
+  - how a book is identified (usually an ID in its URL);
+  - how many images it has;
+  - what the address of one image looks like.
+- **The best address of an image**, in this order:
+  1. the portal's own link to the full image, or a whole-volume download;
+  2. a IIIF image: one request per image. Compare `info.json` (the original
+     size) with what `full/max` gives: some servers cap it.
+     Then the largest one request can give is the right choice. Do not ask
+     for hundreds of tiles.
+  3. tiles (DeepZoom, Zoomify, IIIF tiles), only when nothing else exists and
+     the terms allow it. Save the tiles and give them to strom with
+     `imageFromTiles()`: strom puts them together. For `fetch` take the level
+     nearest 2000 px on the longer side (what a viewer shows of a page); for
+     `part` the tiles of that region at full size. Say in `README.md` how many
+     requests one image and one part cost.
+  Whatever the address, check what it gives: strom answers each saved image
+  with its `width` and `height`. A thumbnail or a stand-in (a tiny picture in
+  place of an image the portal will not give) is not a scan — some portals
+  answer so for some images only: find where the full image is then (another
+  address, tiles, a whole-volume download).
+- **A part of an image, sharper** → `part`: when the whole image comes smaller
+  than the original, find whether one request can give a part of it at more
+  detail (IIIF: a region of the original, `x,y,w,h` or `pct:x,y,w,h`; a
+  viewer's zoomed-in link). Then add `"part"` to `can`: a reader asks for the
+  entry it cannot read, one request, instead of the whole image in tiles.
+- **An account**: when the portal gives more to users who log in (full-size
+  images, a subscription), the connector may use the user's own account.
+  Never ask the user for it and never type it in: declare `login` in
+  `connector.json` (see the contract), and the user saves it in their own
+  terminal (`strom login __NAME__`). Map the login form without logging in.
+- **The user's own browser** → `routes` and `locate`: when the portal gives
+  its images only to a browser (a login with a second factor, a session a
+  script cannot start), or the user wants them through theirs. Add
+  `"browser"` to `routes` (alone, when direct cannot work) and `"locate"` to
+  `can`, and answer `locate` with the addresses `fetch` would ask for,
+  downloading nothing. `browser.open`: the page where the user logs in, on the
+  images' site. You never log in in the browser: the user does.
+- **Pages built by JavaScript** (a catalogue or a viewer that is an
+  application) show your web tools almost nothing. Read them through strom:
+  `strom connector probe __NAME__ <url>` makes one request, paced and within
+  `hosts`, and saves the answer into `.test/probe/`. Fetch the page, find the
+  script it loads (`<script src=…>`), probe that too, and search it for the
+  addresses the application calls (`/api/`, `.json`, image or file addresses):
+  `strom connector grep __NAME__ <text>` shows each hit with the text round it
+  (`--regex` for a pattern). Pages and scripts are often too big to read whole.
+  Then probe those addresses to see what they answer. A POST works too:
+  `--method POST --body '…' --header "Content-Type: application/json"`.
+  Probes keep the cookies servers set, like one visit in a browser: probe the
+  page that starts a session, then the search or the viewer (`--fresh` starts
+  a new visit). Each probe is one request: keep them few, a dozen or two for
+  a whole portal.
+- **What the portal needs from a client**: a session (strom keeps its
+  cookies), a `Referer`, an `X-Requested-With` for its own scripts. Send
+  exactly what its pages send, nothing more.
+- Write the mapping into `README.md`, with URLs and placeholders. Whoever
+  keeps the connector working later starts there.
+
+## 3. Write the connector
+
+- Write `connector.ts` with the SDK (`sdk.ts`; do not change it):
+  - `get(url)` for pages and `post(url, {field: value})` for forms;
+  - `get(url, { save: "s0040.jpg", headers: { Referer: … } })` for images,
+    then `image(n, file, url)`;
+  - `book({...})` for what `find` and `list` found;
+  - for `part`: one `image(n, file, url)` for the part of image `n`;
+  - tiles only: `imageFromTiles(n, file, tiles, { width, height }, url)`;
+  - for `locate`: `located(n, src, url)` for each image — `src` the image's
+    own address, nothing fetched;
+  - with a login: `post(url, { name: login("user"), pass: login("password") })`,
+    only when `req.login` is true — strom puts the values in;
+  - `log()`, and `done()` at the end.
+- **Never** use `fetch()`, http or net modules, child_process or curl. strom
+  checks the code and warns the user that it cannot pace or stop such
+  requests.
+- Put in `hosts` of `connector.json` only the hosts the connector needs.
+- Name the files by image number (`s0040.jpg`), fetch only the images asked
+  for, in order.
+
+## 4. Test with a few requests
+
+    strom connector test __NAME__ --find "<place>" --years 1780-1850
+    strom connector test __NAME__ --list <book>
+    strom connector test __NAME__ --fetch <book> --images 1-2
+    strom connector test __NAME__ --fetch <book> --images 2 --crop 0.5,0,0.5,0.5   (with part)
+    strom connector test __NAME__ --locate <book> --images 1-2                     (with locate)
+
+- Run each `strom` command on its own, not in a pipe or after `;`: your
+  permissions allow `strom …` and nothing around it.
+- A test makes at most 10 requests (`--max 50` at most, for an image in
+  tiles). Its files go to `.test/` in this folder.
+- strom shows each image's size (width × height). It should be the right page
+  and full size, not a thumbnail. Check that the number of images of a book
+  matches the portal.
+- If strom answers with exit code 4 (consent required), stop and tell the
+  user: they give it in their own terminal after reading the warning
+  (`strom allow connector __NAME__`). You never do that.
+
+## 5. Hand over
+
+Show the user:
+- what the terms say (the policy);
+- what the connector can do;
+- the test results, with how many requests one image costs.
+
+They decide whether to use it. From then on, `strom fetch __NAME__ …`
+downloads through strom's limiter and registers what it fetched.