Just Add Water
People keep asking for the code.
It is a reasonable request and the wrong one. The code is about four thousand lines of Python that knows an enormous amount about Yiddish handwriting, letter-shaped records, and one specific family. Almost none of that would help you. If your collection is ship manifests or court records or a decade of a parish register, the parts of this project that look most like software are the parts least worth copying.
What transfers is the posture. A handful of commitments made early, most of them before any code existed, which then decided nearly every technical question downstream. They would decide the same questions the same way for a collection of something else entirely.
This piece is that posture, and there is a file at the end of it you can hand to whatever agent you are working with. Two warnings about that file before you get there, both of which the rest of this explains: it is deliberately incomplete, and it has been used exactly once.
Three things, and the sentence that connects them
Every archive project has the same three functions in it, whether or not anyone has named them. Naming them is most of the benefit, because unnamed functions get collapsed into each other and the collapse is where the trouble starts.
- There is a record. It holds everything ever found, including the uncertain, the contradictory and the unused, with its confidence marked. It never invents. If a word cannot be read, the record says so rather than guessing.
- There is a presentation. It takes the record and curates it into something a person can follow — which means it shows a subset, on purpose, and leaves things out that are perfectly real.
- And there is a gate between them. It runs before anything is published, and it checks that references resolve, that links work, and that nothing claims more than the record supports.
The sentence that connects them is the most useful thing in this article:
The record keeps everything; the presentation shows only some of it; the gate guards the seam.
That is why there are separate tiers for provisional and public material. It is why hiding something on the website never deletes it from the archive. It is why an automated check is allowed to refuse a publish. All three follow from taking the sentence seriously.
There are two more roles and they are both human-shaped. Someone edits — decides what is featured, what is hidden, what is ready, how it sounds. And someone, or something, does the legwork. In our case the legwork is done by an AI agent and the editing is not, and the important discipline is keeping those two distinct even when they happen in the same conversation. The moment they blur, generated material starts arriving as though it had been established.
Say which operation you are performing
This one sounds like bureaucracy and is not. It came out of a specific embarrassment.
The project has a small vocabulary for the operations that get performed on the archive: ingest, discover, audit, correct, clarify, connect, park, decline, retire, vet, build. Most are self-evident. Three are worth explaining, because each fixes a real failure.
Vet is never allowed to stand alone. Saying a thing has been vetted conveys almost nothing, and it took an incident to notice: the sentence "we reviewed the places" was completely true and thoroughly misleading, because reviewing meant one thing to the person who wrote it and another to the person who read it. So the word is always qualified now, and there turned out to be four different jobs sharing it.
- Vetted same-thing. Two records refer to the same entity, and merging them is safe.
- Vetted real-thing. The entity exists outside our own data.
- Vetted true. The evidence actually supports the claim being made.
- Vetted ready. The material is fit to publish.
Park is a real outcome rather than a failure. Some questions cannot be settled with what you have, and the useful move is to record why you stopped. A parked question with its reasoning attached is worth more than a gap somebody has to rediscover.
Decline needs to be as durable as acceptance. A rejected claim that leaves no trace will be proposed again, and again, by whoever comes next — including a machine that has no memory of the last time. Writing down that something was considered and refused is not bookkeeping; it is the only thing that stops the same argument recurring forever.
Eight commitments, each one paid for
None of these were designed in advance. Every one exists because its absence caused a problem that took real effort to undo.
- Everything rendered records what produced it. A reader points at something on a page and you need to know which source file to edit. Without it, corrections get applied to the output and vanish at the next rebuild.
- Provisional and public are different tiers, enforced structurally. Not by convention or a naming rule someone remembers — by construction, so that generated material cannot reach a public surface without a human moving it there.
- Superseding never deletes. When a record is replaced, keep it and record what replaced it. You will want the old one, usually to understand why somebody made a decision that now looks wrong.
- A gate runs before publication and is allowed to refuse. The refusal is the feature. A gate that always passes is decoration, and you will not find out which kind you have until the day it matters.
- Edits resolve to source, never to output. The built site is a reference surface, not an edit surface. A hand-edit to generated output survives until the next build and then disappears without trace, which is worse than being unable to make it — so here, a hook physically blocks it.
- The name of a thing is not evidence about the thing. Filenames, folder names and titles are somebody's earlier guess, recorded at a moment you cannot see. In a cold test of this posture on about a hundred and fifty scans, the filenames disagreed with the documents they named roughly a quarter of the time — wrong dates, two names swapped with each other, four promising crops that were never made. None of it was visible without opening the images. The distinction that matters is whether a fact was read from the object or inferred from its surroundings, and nothing downstream can tell those apart unless somebody records which it was.
- Prefer the reversible action, and when you cannot, stop and ask. This is the principle the others quietly share. Superseding is reversible; deleting is not. A dry run is reversible; a write is not. When something is expensive to undo — rewriting history, discarding originals — that is the moment to put the choice to a person, even when you are confident. Confidence and reversibility are different things.
And the one that has cost the most: derive, never enumerate. Compute status and coverage from what is actually there, never from a hand-maintained list. Lists rot silently, and the rot is invisible precisely because a list looks authoritative. This project has lost data to that at least seven separate times, which is why the rule is stated so bluntly.
The file, and why it is deliberately incomplete
At the end of this there is a single Markdown file. You give it to whatever agent you are working with, along with your material, and it establishes the posture above before any design decisions get made.
It does not contain a data schema. It does not contain a pipeline, a stage list, a directory layout or a technology recommendation. Those omissions are the point.
The reasoning is that a recipe implies completeness — follow the steps, get the dish — and this cannot be that. It has never seen your material. If it prescribed a record shape, you would copy a structure built for handwritten letters into a collection of something else, and the mismatch would be invisible until it had already cost you something.
So what it carries instead is commitments with their reasons attached, because a rule that travels with its reason can be extended to a case it does not name. That is what makes it useful in the situation you will actually be in, which is one nobody anticipated.
This is also why it does not need to be complete, and why trying would make it worse. An agent that hits an uncovered case is expected to work out which commitment applies and reason from it. A file detailed enough to answer everything is a file that stops that reasoning and replaces it with pattern-matching against somebody else's archive. The gaps are where judgement is required, and marking them as gaps is more honest than filling them with guesses.
It opens by telling you to do two things before anything else: write down where the material came from and whether the folder is source or copy, and then open the material itself rather than reading its filenames. Both came out of watching agents skip them. It ends with five questions rather than five answers. What is the thing in your material that cannot be wrong? Who can check the machine's output, and what happens where nobody can? What could be regenerated, and what would be lost forever? What does uncertainty look like, and does it survive all the way to a reader? And what is the smallest thing you could publish that would still be honest?
The second question is the one that determines everything else. If a competent person can verify every result, you can afford a permissive pipeline and fix errors as they surface. If nobody can — a dead language, a hand nobody reads, a vocabulary that died with its speakers — then error has to be made structurally difficult, because there is no later in which to catch it.
What we do not know
Publishing this file breaks one of the project's own rules, and that is the part that ought to make you cautious.
This project has a rule about exactly this situation, and publishing the file breaks it. The rule says: do not extract a shared abstraction in anticipation of a second user; extract it at the second user, once you can see which parts were really general. It exists because generalising from one example produces something shaped like the example, wearing the costume of a principle.
We are breaking it deliberately, and the honest reason is that a shape is more useful shared than hoarded. But you should read the file knowing that it has been run on one archive, by two people, over about five weeks in the summer of 2026.
Our best guess at what transfers: the one sentence, the derive-never-enumerate rule, and the habit of qualifying the word vetted.
Our best guess at what is ours rather than yours: the specific tiers, the record shape, and everything downstream of the fact that our material is handwritten letters in a language nobody in the family reads. That last constraint drove more of our design than anything else, and most collections do not have it.
We genuinely do not know which of those two lists a given piece belongs on. That is not modesty. It is what one data point buys you.
We did test it, as far as we could. The file went to four agents that had never seen the project, each with an empty folder, a copy of the material and nothing else, and each run changed it. That is not the same as knowing it works on your material, so treat it as a starting posture rather than a validated one. The more useful result was one we were not testing for: two of those runs found errors in our own records, including a woman addressed by two different surnames in the years before her marriage, which nobody had thought to ask about. We were testing the document and the archive turned out to be what needed correcting.
Take it and tell us what broke
The useful thing you can do with this is not to follow it.
It is to adapt it to material it was not built for, notice where it fails, and say so. The second person to use a shape is the one who finds out which parts of it were real — everything before that is a hypothesis with good presentation.
If you do try it, the failures are more interesting than the successes. A commitment that turned out to be specific to letters, a question that made no sense for your material, an invariant that cost more than it saved. Those tell us something the first run structurally cannot.
The file is below. It is short, it is opinionated, and it is incomplete on purpose.