# A switcher's first week with Heartwood

For someone arriving from another genealogy program with an existing GEDCOM
file, this is the walkthrough for the first week: import,
read the loss report, understand what changed, and (if you want) export
back out.

## Day 1 — import your existing tree

Heartwood imports GEDCOM 5.5.1 and GEDCOM 7 files. If you're not sure
which your old program exports, either works — Heartwood detects the
version from the file's own header.

1. **Validate first, if you're cautious.** `gedcom.validate` (or `GET
   /v1/gedcom/validate?path=...`) parses your file and reports what it
   *would* do — with zero writes: no data lands in your tree, nothing is
   stored. This is the cheapest way to preview fidelity before committing.
2. **Import.** `gedcom.import` (or `POST /v1/imports/gedcom`) reads the
   file and builds your tree: individuals, families, events (births,
   deaths, marriages, census records, ...), notes, sources, and citations.
   The raw bytes of your original file are always retained verbatim in
   Heartwood's blob store — nothing about the source file itself is ever
   discarded, even if a structure inside it isn't given a domain home.
3. **Read the loss report.** Every import produces a `LossReport`
   (`gedcom.loss_report`, or the `heartwood://loss-report/latest` MCP
   resource) — the single most important thing to read after importing.
   It tells you, honestly:
   - `totals.lossless: true` means every structure in your file was
     mapped cleanly. This is common for simple trees.
   - If not lossless, `entries[]` itemizes exactly what happened to each
     structure that wasn't a clean 1:1 mapping — never a silent gap.
     Categories: `verbatim_retained` (kept, just not given a dedicated
     Heartwood concept — most vendor-specific tags land here),
     `downgraded` (mapped, but with a documented fidelity trade-off),
     `dangling_pointer` (your file referenced something that wasn't
     actually in it — Heartwood imports what it can and names the gap),
     `extension_tagged` and `suppressed_egress` (export-only — see Day 3
     below), and `dropped` (exceedingly rare — nothing at all could be
     preserved).

Most vendor "dialect" tags (custom source-linking IDs, program-specific
UID fields, etc.) show up as `verbatim_retained` — they're kept, just not
translated into anything Heartwood's own model understands yet.

## Days 2-3 — what changed vs. your old program

A few genuine differences to expect, by design (not bugs):

- **Family events are events, not text.** Where your old program may have
  stored "married to Jane" as a text note, Heartwood records marriage
  (and divorce, engagement, etc.) as a proper event shared between both
  spouses — one fact, viewable from either person, not a duplicated
  claim.
- **GEDCOM imports are directly usable; only AI-origin findings wait for
  review.** Bulk-importing your existing research does not route it through
  the pending lane. Fresh AI-assisted captures do, so they cannot support a
  conclusion or leave in an export until you review them.
- **Refuted/superseded claims and unreviewed AI output never round-trip
  invisibly.** If you (or an AI assistant) later mark something refuted
  or superseded in Heartwood, it never silently reappears looking like an
  ordinary fact if you export again (see Day 3).
- **Review at source-group scale, not across unrelated sources.** When an AI
  capture creates several pending claims from one source, you can review that
  source group together. Heartwood deliberately refuses a bulk decision that
  mixes sources: sharing a screen or a batch is not evidence that the records
  have the same reliability.

## Day 3 (or whenever) — exporting back out

If you want to move data to another program, use GEDCOM export. Do not
confuse that interchange file with a Heartwood backup: a scheduled backup
contains the database and blob manifest Heartwood needs to verify and restore
a new tree, while GEDCOM carries only what its chosen interchange version can
represent.

- The app writes GEDCOM 7. The local API can write GEDCOM 7 or 5.5.1.
  Export is human-only: it is not an MCP tool, and there is no agent export
  proposal tool.
- **Living people are withheld by default.** Anyone Heartwood believes is
  still alive is left out of the export entirely, unless you explicitly
  set `include_living: true` (itself human-only — no AI assistant can
  override this).
- Refuted/superseded claims, if present, export under documented `_HW_*`
  extension tags — never as an ordinary GEDCOM structure that another
  program (or a future you) might mistake for confirmed fact. See
  [the extension-tag registry](../gedcom/extension-registry.md).
- The export produces its own `LossReport` too — same honest accounting,
  this time in the export direction (`structures_visited`/
  `structures_emitted` instead of `records_seen`/`records_mapped`).

## Where to go next

- [GEDCOM extension-tag registry](../gedcom/extension-registry.md) — the
  `_HW_*` namespace.
- [Attribute/event split table](../gedcom/attribute-event-split.md) — the
  exact rule for which GEDCOM tags become events vs. plain facts.
- [FH7 interop checklist](../gedcom/fh7-interop-checklist.md) — if you're
  specifically comparing against Family Historian 7.