Configuration

.undomap.json

Optional, at the root you map (or pass --config file). It tells undomap what it can't detect.

{
  "permanent": ["build/atlas/", ".cache/models/", "vendor/patched/"],
  "regenerable": ["generated/", "*.parquet", "data/cache/**"],
  "backedUp": ["media/", "Rushes/"]
}

• permanent: paths that can't be rebuilt even though they look like they can: a hand-tuned folder under build/ or dist/, model weights in .cache/models/, a vendored patch, a prebuilt binary with no source. They're graded Zone VE with the reason "looks regenerable (…) but .undomap.json marks it permanent", and the JSON finding carries "forcedBy": "<pattern>". A permanent folder inside a regenerable one is carved out as its own place, so .cache/ stays Zone AE and .cache/models/ shows up in Zone VE with its own bytes.
• regenerable: paths your scripts rebuild. They're graded Zone AE.
• backedUp: paths you back up some other way (restic, borg, rsync to a NAS, a versioned bucket). They're graded Zone AE with the reason "backed up per .undomap.json".

Precedence

When rules disagree, the first one that applies wins:

1. What git knows. Clean tracked files are Zone X and uncommitted edits or unpushed commits are Zone AE, whatever the config says. permanent can't make git forget a commit.
2. Real coverage. backedUp, a snapshot that covers the path, and cloud version history undomap could verify move it to Zone AE, even if it's also permanent: a copy really exists somewhere else. The reason says both ("marked permanent, but backed up per .undomap.json").
3. permanent beats every "regenerable" guess: built-in folder names (dist, .cache, vendor…), content markers (pyvenv.cfg, CACHEDIR.TAG, ELF/Mach-O/PE headers) and your own regenerable list. If a path is on both of your lists, permanent wins.
4. Regenerable (built-in or yours): Zone AE.
5. Everything else git doesn't hold: Zone VE.

Pattern rules: dir/ matches that directory at any depth, or anchored if it contains another slash (a/dir/). *.ext matches a basename. a/**/b matches across directories. Unknown keys are an error, so a typo can't silently grade your data as safe.

Flags

Exit codes

Next sheet: Reference