Plaintext Family History
An operating spec for a durable, file-first family-history archive with an AI research assistant layered on top.
See what it can do: open the example site → A fictional family's archive (the
example-archive/) compiled byfha site- the same self-contained, redacted site you'd publish or hand off on a USB stick.
This project stemmed from one idea: for a hundred years, genealogy lived in a filing cabinet, and anyone could open the drawer. No login, no subscription, no schema migration. A century later a curious descendant could still pull the folder or open the book and read it. Modern genealogy software and workflows have lost that virtue.
Plaintext is that filing cabinet, built to last. Plain files at the foundation, with search, structured claims, and an AI research layer stacked on top of the files, never instead of them.
Delete every layer above and the archive still works, the way the drawer still works.
Which one are you?
| You are… | Start here |
|---|---|
| A genealogist who wants to use this system | docs/GETTING_STARTED.md |
| A genealogist who wants to start by hand with plain files and no tools | quickstart-template/ (blank starter kit); see quickstart-example/ for a filled-in worked example |
| A genealogist who got a zip and doesn't use git/GitHub | docs/SETUP_FROM_ZIP.md |
| Someone the owner sent documents to | docs/CONTRIBUTING_SOURCES.md |
| A developer building or extending the tools | BUILD.md then TOOLING.md (core); the capture on-ramp is BUILD_INGESTION.md/TOOLING_INGESTION.md; the workbench skills are BUILD_INTERFACE.md/TOOLING_INTERFACE.md |
| Here to understand or rebuild the spec | SPEC.md |
NOTE: This is a specification and scaffold, not finished software.
It is the blueprint for a simple, future-proof system for family research. The goal of this repo is to establish simple standards that can be maintained with or without tooling. It also provides the spec to recreate the tooling from scratch if you wish, plus sample tools to get you started.
Repo, tools, and your archive
Three things live at arm's length from each other, by design:
- This repo (public): the spec (
SPEC.md,TOOLING.md,AGENTS.md), the docs, the genericfhatools, anarchive-template/with copy-paste record templates, and a fictionalexample-archive/fixture. - The tools (public, in
tools/): generic - they operate on any conforming archive and hold no family data. Publishing them is the manifestation of the spec. Tools are replaceable glue, regenerable from the spec. - Your archive (private, separate repo): your real family's records, created from
archive-template/, depending on this repo's spec and tools but never living inside it. Public examples stay fictional; your groceries don't go in the cookbook.
Public examples must remain fictional. Do not open issues or PRs containing real records about living people, private family documents, raw DNA files, or identifying photos. See PRIVACY.md.
How the two repos relate
In practice you end up with two separate repositories - one public, one private:
plaintext-family-history/ ← PUBLIC: the spec + the generic tools (this repo)
my-family-archive/ ← PRIVATE: your real family's records
They are not technically linked.
The only relationship is that your private archive uses the tools that live in this public repo.
The tools get to your archive by installing them into it:
./fha install PATH-TO-YOUR-ARCHIVE --repo . # macOS / Linux
.\fha install PATH-TO-YOUR-ARCHIVE --repo . # Windows PowerShell
fha install PATH-TO-YOUR-ARCHIVE --repo . # Windows Command Prompt
(Run it from inside this clone. The fha launcher sits right here beside this
README, but a fresh clone is not on your PATH - hence the ./.)
Already know your photos/documents live outside the archive (an external drive, an existing
library)? Editarchive-template/fha.yaml'sroots:in this clone before running
install, and the matching internal placeholder folder is never created in the first place.
Otherwise, install with the defaults and editfha.yamlinside your new archive afterward -
fha update-toolsremoves the now-unneeded placeholder the next time you run it.
That copies the whole operating layer - the program, its design package, the rulebooks, and the
owner-facing docs - into the archive and records what it wrote, so fha update-tools can refresh
it later. What "refresh" means is worth being precise about: your records,
fha.yaml, your place registry, and your stylesheet are never touched. Tool
files and rulebooks ARE replaced - if you edited one, your version is moved to
.plaintext-backup/ first and the new stock file takes its place, so the edit
survives but stops being in effect until you re-apply it. One folder can also disappear on
purpose: if fha.yaml points documents:, photos:, or inbox: outside the archive, its
now-purposeless empty placeholder is removed too (recreated if you ever point it back inside).
The machinery lands in a hidden .fha/ folder
so the archive root shows your genealogy rather than the program: your records, START_HERE.md
(the one page that explains the archive to anyone who opens the folder), fha.yaml, AGENTS.md,
CLAUDE.md, the launchers, and docs/ (which holds SPEC.md, TOOLING.md,
GETTING_STARTED.md, CHEATSHEET.md and the rest of the manual) stay in plain sight. The archive is then
self-contained: it works on any machine, offline, forever, even if this repo disappears.
This README is not part of that. It is repo-facing - badges, a milestone roadmap, contributing,
and links to example-archive/, quickstart-template/, archive-template/ and
obsidian-templater/, none of which an archive receives - so an installed archive has no
README.md at its root. Its entry point is START_HERE.md, written for a reader with no tools;
the owner's first-day guide is docs/GETTING_STARTED.md, backed by the one-page
docs/CHEATSHEET.md. Anything here an archive owner genuinely needs lives in those.
The fha program itself is never pip installed - the archive owns its own copy on purpose, so
it cannot be uninstalled out from under you. Its Python dependencies are ordinary external
packages, though: PyYAML is needed for everything, and Jinja2, Pillow, and pypdf for the site,
photo, and PDF features. docs/GETTING_STARTED.md walks through
installing them, and fha doctor names any that are missing. If you have no git clone,
docs/SETUP_FROM_ZIP.md covers the download-a-zip route.
Your private family data never enters this public repo. The public repo is the cookbook and the appliances; your private repo is your kitchen with your food in it.
Contents
- What this is
- What this is not
- How it works
- Repository layout
- Quick start
- The documents
- Design principles
- Status & roadmap
- A complementary project
- Contributing
- License
What this is
Plaintext is an archive-first system.
The durable archive - plain text and standard file formats on disk - is the source of truth.
Every other moving part (the search index, the AI assistant, any genealogy app or website) is an optional, replaceable helper built from the archive and rebuildable from scratch.
It is designed to be operated with an AI coding agent - a chat assistant that can read your files and run commands for you, the same way a human research assistant would, except it never gets tired of repetitive filing work.
You open the archive in Claude Code (or any agent that reads AGENTS.md), and the agent helps you process records, draft sourced claims, build family trees, and surface research leads - while a set of small deterministic tools (the fha command suite, specified in TOOLING.md) does the mechanical work: the boring, exact, repeatable parts (checking IDs, building search indexes, scanning for contradictions) that don't need judgment, just consistency.
The spec is written so that all of that tooling can be regenerated from the documents, in any language, if it is ever lost.
What this is not
- Not a finished app. Milestones 1-11 are implemented, including the intake pipeline (
fha process,fha capture,fha convert-mining), the static-site generator (fha site), the installer/update tooling (fha install,fha update-tools), working-copy mode (fha working-copy), and the milestone 11 usage-feedback wave (fha reconcile,fha reorganize,fha source extract,fha process refile, stub promotion). - Not a database. No server, no proprietary store. Files are the truth; the index is a disposable cache.
- Not a genealogy app that happens to store documents. It is the inverse: an archive that may feed a genealogy app via export.
- Not a hosted service. Your data lives on your disk, in formats you can read with a text editor.
How it works
Your existing photos and documents plus FIVE record types, all plain Markdown/YAML on disk:
| Type | What it is |
|---|---|
Person p- |
A human - identity, flags, prose, and the relationships that tie them to others. |
Source s- |
A piece of evidence: a record, document, photo, interview. |
Claim c- |
A single sourced assertion (a date, place, relationship) living inside its source record, moving through a suggested → accepted review lifecycle. |
Place l- |
A physical location, identified by coordinates, with a dated name/jurisdiction history. |
Working answer h- |
A guess written on an open question in notes/questions.md - with its basis and what would verify it - never a fact; a source that proves it mints a new claim. |
Around those, a rebuildable index (SQLite, regenerated from the files) powers search, family-tree generation, contradiction detection, and a research report - none of it authoritative, all of it disposable.
The operating loop is simple: capture → file → process → review → report, with human review the only gate to an accepted fact.
One source, one piece of evidence. A source's files are always copies or facets of one piece of evidence - fronts, backs, extra prints, pages, transcripts, even entries written across several sittings - never several separately published items bundled together just because they arrived at the same time (SPEC §7); two different letters, or two different newspaper clippings even about the same event, are two sources.
Kept for texture without becoming evidence. A clipping or note that names no one in your family - period news, local color, general history kept on purpose for a future biography - files as source_type: ephemera (SPEC §14) rather than an ordinary source type. It's still kept and full-text searched, but it won't appear on any person's page, packet, or timeline as long as its ## Claims block also stays person-free (the ordinary shape for a clipping like this - a claim naming someone reaches their page the same way a people: link would); find it through the generated site's homepage Sources list instead.
Linking, the human way. You connect records by name. In any profile or note, cite a source or cross-link a person by writing the name in double brackets - [[Grandpa Joe]], [[Hartley family bible]] - and a nickname works just as well. Don't worry about making an ID: name your file something sensible, link to it by name, and if you ever run the tools the linter quietly assigns the IDs and tidies everything. The copy-paste templates in archive-template/ (person, source, research file, inbox note) give you a filled-in starting point.
Opens in Obsidian. The archive is a Markdown-plus-frontmatter-plus-[[wikilink]] vault: point Obsidian (or another Markdown app) at the folder and it opens as-is, no import. An optional Templater pack and the generated site's interactive family tree make it native to plaintext-PKM workflows; see docs/USING_WITH_OBSIDIAN.md.
Or open it in a browser. fha serve starts a private local workbench (this machine only, no login) with a review queue, an inbox, and every record page one click away - every button is the same fha command you'd otherwise type, previewed before it writes. It's a second way in, not a second copy of anything: close the window and nothing is lost.
Stop re-reading the same newspaper page. The optional Seen It browser add-on remembers which Newspapers.com pages, Ancestry and FamilySearch records and Find a Grave memorials you have already opened, ruled out or attached to your tree, and marks them right on the sites. It works on its own, with everything kept in your browser; turn on its Advanced mode and it also marks what your archive already holds, reading the archive without ever changing it.
Back it up with one command. fha backup copies the archive into a dated zip in a folder beside it (my-family-archive-backups/) and verifies every file. Photos and documents are not included by default - they are often huge and often live on another drive - and the output says so every time; add --include-assets to pack them too, or back those folders up separately (fha doctor lists every path a full backup must cover, and reports when you last actually ran a backup). To restore: unzip the file. That's the whole procedure - a backup is just your files.
Repository layout
plaintext-family-history/
├── README.md ← you are here
├── SPEC.md ← the law: philosophy, data model, physical format, governance
├── TOOLING.md ← implementation design for the core fha tools
│ (+ TOOLING_INGESTION.md capture on-ramp, TOOLING_INTERFACE.md skills)
├── BUILD.md ← build sequence for the core tools
│ (+ BUILD_INGESTION.md, BUILD_INTERFACE.md - one per TOOLING doc)
├── AGENTS.md ← canonical operating instructions for the AI agent
├── CLAUDE.md ← Claude Code entry point (defers to AGENTS.md)
├── docs/ ← the owner's manual (ships to the archive's docs/, where SPEC.md
│ │ and TOOLING.md land too)
│ ├── GETTING_STARTED.md ← the archive owner's first-day guide
│ ├── CHEATSHEET.md ← the one printable page
│ ├── COMMANDS.md ← every fha command and its options
│ ├── TROUBLESHOOTING.md
│ ├── SETUP_FROM_ZIP.md
│ ├── GLOSSARY.md
│ ├── FAQ.md
│ └── DESIGN_RATIONALE.md
├── archive-template/ ← skeleton + copy-paste record templates (+ fha.yaml) to start your own (private) archive
├── example-archive/ ← a small, fully fictional worked example (+ its own fha.yaml)
├── quickstart-template/ ← blank by-hand starter kit — plain files, no tools required, open in any text editor
├── quickstart-example/ ← filled-in fictional worked example of quickstart-template/ (the Rivera/Lee family)
├── tools/ ← the generic fha command suite (see tools/README.md)
├── browser-companion/ ← the capture browser add-on (ships into every archive)
├── seen-it/ ← "Seen It", an optional research add-on: marks pages and records
│ you've already looked at; can also show what your archive holds
├── tests/ ← automated tests and fixtures for the tools
├── PRIVACY.md ← example-data policy
└── .github/ ← issue templates, contributing guide
Quick start
You need an AI coding agent that can read project instructions and run shell commands - Claude Code is the reference harness. The spec is harness-agnostic; anything that reads
AGENTS.mdworks. Codex, for example, readsAGENTS.mdnatively; see the FAQ.
- Clone this repo and read
SPEC.mdend to end. It is the contract; everything else serves it. - Open the folder in your agent. It will read
CLAUDE.md→AGENTS.mdand know the rules before you say anything. - Use or extend the tools. Milestones 1-11 are implemented; run them from
tools/or declare tool-building mode to continue with the build order inBUILD.md. - Start your own archive. Copy the structure, drop your first scan or note into
inbox/, and ask the agent to process it. - Coming from Ancestry (or any app)? You don't start over. Download your tree as a GEDCOM file and run
fha gedcom import family-tree.ged- every person arrives as a record and every assertion as a reviewable suggestion, with your original file kept untouched.
See docs/GETTING_STARTED.md for the full walkthrough.
The documents
| Document | Read it for |
|---|---|
| SPEC.md | The complete specification - what exists, how it lives on disk, and the rules that never bend. Start here. |
| TOOLING.md | How the core tools are built, in enough detail to rewrite from scratch. The fha command suite, the index schema, the linter rules. Two siblings cover the rest by concern: TOOLING_INGESTION.md (capture/inbox on-ramp) and TOOLING_INTERFACE.md (workbench + skills). Each has a matching build doc (BUILD.md, BUILD_INGESTION.md, BUILD_INTERFACE.md). |
| AGENTS.md | What an AI agent may and may not do inside the archive - the contract, the operating modes, the workflows. |
| docs/GETTING_STARTED.md | A practical first-session walkthrough. |
| docs/GLOSSARY.md | Every term and ID type defined. |
| docs/FAQ.md | Why files, why not a database, why AI, how durable is this really. |
| docs/DESIGN_RATIONALE.md | Why the archive is shaped this way: for each design topic, what we do, why, and what was rejected. Read it before changing a rule. |
Design principles
- The archive is the source of truth; tools are replaceable.
- Durable, plain formats.
.md,.txt,.csv,.jsonl,.yaml,.jpg,.tiff, embedded IPTC/XMP. - Every important fact traces to a source. Uncited prose is story or context, never fact.
- AI suggestions are not facts. They enter a review queue and stay there until a human accepts them.
- Nothing generated is load-bearing. Index, search, trees, the website - all rebuildable from the files.
- Folder location is for human browsing; metadata carries meaning.
- Stay light. Long-term durability beats short-term convenience.
Status & roadmap
Current: spec v2.2 - milestones 1-11 complete.
Everything through the intake pipeline, the static-site generator, the
installer/update tooling, and working-copy mode is
implemented and runs cleanly on the example archive: the linting/indexing
substrate, the view generators and universal locator, the photo catalog, the
candidate-finding tools (contradiction/corroboration detection, person and
place co-occurrence, and fha find --related's neighborhood queries), the
deterministic review write-backs (fha claim for claim status, fha confirm
for the detectors' confirm/dismiss), the
fha report session feed, fha packet, fha places, GEDCOM/WikiTree export
and the GEDCOM import on-ramp (fha gedcom import),
the milestone 7 intake tools (fha process, fha capture, fha convert-mining),
the milestone 8 static-site generator (fha site), the milestone 9
scaffolding tools (fha install/fha update-tools), the milestone 10 working-copy mode (fha working-copy),
and the milestone 11 usage-feedback wave - fha reconcile (heal moved-document
inventory paths), fha reorganize (bulk-tidy the documents root, never touching
a human-organized folder), fha source extract (dump a PDF's text layer into a
searchable companion), fha process refile (the sanctioned cross-root correction
move), and stub promotion (fha person promote / fha views brackets --fix-promote).
Plan 17 (2026-07) added a second front door onto the same tools: fha serve, the localhost
workbench, plus the write-back verbs it drives - fha claim new, fha person new/relate/
estimate/edit/note, fha source note, and fha find --json. The 2026-07 live review
round added per-entry note edits (fha person edit-note, fha source edit-note), the
human-directed place registry edits (fha places set/note, with an embedded map and
research notes on place pages), and workbench conveniences (native file picker,
reciprocal-by-default family ties). See BUILD.md for the detailed
milestone breakdown. The intended build sequence (detailed in TOOLING.md §15):
- Shared foundations (
_lib: parsing, dates, ID grammar, path resolution) -
fha id,fha index,fha lint,fha stubs- the substrate (milestone 1: lint clean on the example archive) -
fha claim- the claim-review write-back: move a claim's status and stampreviewed:(the human gate, as a deterministic command) (milestone 1) -
fha views timeline,fha views sources-index,fha views draft-queue- view generators (milestone 2);--format md|htmlstandalone printable pages undergenerated/views/(2026-07 usability wave) -
fha views brackets- folder maintenance: W103 bracket refresh, W110 Ahnentafel placement (milestone 2) -
fha views tree- relationship tree traversal, neutral JSON + DOT output (milestone 2; HTML arrives with the site-wide family tree) -
fha views clean,fha views refresh- generated-file lifecycle management, both formats (milestone 2) -
fha find- universal ID locator and full-text search across records, notes, transcripts (milestone 2) -
fha doctor- archive health report: index freshness, file integrity, privacy flags (milestone 2) -
fha photoindex- photo catalog: scan/grouping, find, triage/report, reconcile/tag-person, set-summary (milestone 3) -
fha xref,fha cooccur- corroboration/contradiction and co-occurrence candidate detection (milestone 4) -
fha confirm- the write-back floor under the read-only detectors and report prompts: confirm/dismiss a candidate, register a place cluster, log a discovery, accept a draft, enact a human-confirmed identity merge (confirm merge, the SPEC §9 write) (milestone 4) -
fha find --related- the neighborhood query: people, places, sources, and time slices (milestone 4) -
fha report- the session research feed: discoveries, review queue, vitals gaps, contradictions, search-log awareness, answerable questions, photo triage, hypotheses, possible connections (milestone 5) -
fha packet- person data-export packet: profile, fresh timeline, sources, files, photos, zipped (milestone 6.1) -
fha places- place registry lint, recurring unlinked place/GPS candidate detection, and offline GeoNames coordinate backfill (milestone 6.2-6.3) -
fha gedcom- GEDCOM 5.5.1 relationship export (living-redacted by default);fha wikitree- curated-profile export in the WikiTree dialect (milestone 6.4-6.5) -
fha gedcom import- the Ancestry on-ramp: file a GEDCOM download as one source, a person stub per individual, and every assertion as a suggested claim with a line anchor - plan first,--applyto write, full rollback, one-shot re-run guard (milestone 6.6) -
fha process- asset intake: single-file documents/photos,--more, folder triage, variation grouping, and bundle dissolution (milestone 7.1-7.4) -
fha capture- paste-fallback web capture, generic recipe, and Ancestry/FamilySearch/Newspapers.com/FindAGrave recipes (milestone 7.5-7.7) -
fha convert-mining- one-time legacy transcript-mining migration (milestone 7.8) -
fha site- static-site generator: source/person/place/discoveries/home pages, standalone (redacted, self-contained) vs linked preview, and vendored interactive descendant/ancestor trees (milestone 8.1-8.5) -
fha install/fha update-tools- archive scaffolding and updating: bootstrap a private archive's operating layer from a clone or unzipped download, then refresh it later, backing up your edits and never deleting or touching yourfha.yaml/places data. The machinery installs into a hidden.fha/folder so the archive root shows your genealogy rather than the program - your records, the rulebooks, and the owner-facingdocs/stay where you can see them (the project's own design reference and roadmap ride along inside.fha/docs/) (milestone 9.1-9.2) - working-copy mode - asset-less plain-text working copies synced to a second machine (toggle with
fha working-copy on/off, which sets a git-ignoredWORKING_COPYmarker so the mode never syncs back): tools treat absent photos/documents as present-elsewhere (never "missing", never pruned), so you can write narratives and research against existing records anywhere (milestone 10 - SPEC §12.4 / TOOLING §13d) -
fha backup- one-command dated zip snapshot written outside the archive (records-only by default;--include-assetspacks the mapped photo/document roots), verified after writing, withfha doctorreporting the real last-backup date; restore = unzip (2026-07 usability review, plan 04 - TOOLING §13e) -
fha serve- the localhost workbench: a private, editable browser front door onto the same tools, plusfha claim new(mint a claim by hand),fha person new/relate/estimate/edit/note,fha source note, andfha find --json(machine-readable search) (plan 17 - TOOLING_INTERFACE.md §1b) - usage-feedback wave:
fha reconcile(heal moved-document inventory paths, documents + photos in one command),fha reorganize(bulk-tidy the documents root intodocuments/{type}/, checked in batches againstfha reconcile, never touching a folder a human already organized by hand - issue #107),fha source extract(dump a PDF's embedded text layer into arole: extracted-textcompanion, searchable afterfha index),fha process refile(the sanctioned cross-root correction move, documents ⇄ photos), stub promotion (fha person promote/fha views brackets --fix-promote), grouped claim review (fha claimbatch), and biography styles (milestone 11 - TOOLING §9/§9a/§14, SPEC §12.1/§13) - Ahnentafel realignment wave: couple-folder names gain their missing
+ second spousehalf (add-only, never rewrites a hand-crafted name),fha views brackets --realign(renames, moves, and stub promotions in ONE previewed pass - the recovery command after re-anchoringroot_person, correcting asex:, or accepting a new parent claim), W120 (a folder number that was silently guessed because a lone linked parent has nosex:recorded is now flagged with its one-line fix), and W127 (the anchor itself: aroot_personwho has a child on record numbers every couple folder one generation high, which no folder check can catch because the folders match that same count - reported byfha lintandfha views bracketsalike, as a note rather than a defect); the capture browser extension now ships into every archive at.fha/browser-companion/, ready for chrome://extensions "Load unpacked" - no clone of this repo needed to use it (milestone 11.7 - TOOLING §7/§13c, SPEC §12.2) -
root_generation(fha.yaml): a researcher who anchors the archive at themselves no longer has to misname one of their own children asroot_personto get the documented#1 = the children, collectivelynumbering (or has no way at all if childless) -root_generation: self(default, unchanged) keepsroot_personat #1;root_generation: childrenanchorsroot_personat #2 instead, so their own generation numbers correctly without renaming who the archive is centred on. W127 (the anchor-too-high note) stands down the momentroot_generation: childrensays the shape is deliberate; an unrecognized value is rejected with a plain fix rather than silently read asself(W129) (issue #72 - SPEC §12.2/§12.4) - SPEC 2.0-2.2 alignment (plan 19): IDs written lowercase and matched without regard to case, links written
[[p-…|Name]], one research ladder (open questions and their working answers innotes/questions.md;needs-reviewretired - a looked-at, unsettled claim stayssuggestedwith areviewed:date),START_HERE.mdas the archive's front page for a reader with no tools, generated summary lines (Born, Died, Married, Parents, Children) under every profile's title, andrelationships:naming each person once per role with all its supporting claims
A complementary project
A related project worth studying: if your interest is the research half - autonomous AI research loops, archive guides for specific countries, prompt templates for pushing a family tree backward - see autoresearch-genealogy by Matt Prusak.
It and Plaintext arrived independently at the same files-first, Claude-Code-driven philosophy from different angles: that project is a research playbook, this one is the filing system the findings live in.
They complement each other well.
Contributing
This is an early-stage spec and feedback is genuinely useful - especially from genealogists and from anyone building the tools against it.
See .github/CONTRIBUTING.md.
Issues and discussion welcome.
License
MIT.
The spec, the documents, and any code built from them are free to use, adapt, and build on.