docs(migration): #144 — Mozilla profiles.ini, and why NOT to restore a snapshot

A real migration (2026-07-16) lost ~/.thunderbird/profiles.ini, so
Thunderbird made an empty profile and opened it while 30 GB of mail —
19 GB ImapMail, 64 account prefs — sat in the directory it had stopped
looking at. The fix was eight lines.

MIGRATION.md already warned about this class for Chromium extensions.
The Mozilla case gets its own bullet because it is the inverse failure
and the inverse danger: Chromium silently deletes extension data and
looks minor; Thunderbird loses nothing and looks catastrophic — so the
reflex it provokes, restoring a snapshot over a good profile, is the one
thing that can actually cost you mail. The bullet therefore leads with
`ls`/`du` ("a multi-GB dir = your data is fine"), then gives the working
profiles.ini shape and the Path=/Default= semantics.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

agent/BACKLOG.md

@@ -198,50 +198,6 @@ scaled splash — the LUKS prompt especially, since a passphrase box half off
 the panel is the failure that matters. Pass = docked boot + shutdown centred
 on both heads; undocked unchanged.
 
-### 144. MIGRATION.md must warn about Mozilla `profiles.ini` — it reads as total data loss
-
-Bernardo 2026-07-16: "it seems that I have lost all my thunderbird accounts and
-emails!" — nothing was lost. `~/.thunderbird/bernardo` was intact the whole
-time: **30 GB**, 64 account/identity prefs, 19 GB `ImapMail` + 9.7 GB `Mail`,
-last used 2026-06-26. Only `profiles.ini` was gone, so on first launch after the
-migration Thunderbird did what it always does with no profile list — created an
-empty one (`wc966grk.default`, 16 MB) and pointed itself at it. Fixed by
-rewriting `profiles.ini` to `Path=bernardo` + `Default=1` (old file kept as
-`profiles.ini.bak-*`); Thunderbird reopened the real profile and went straight
-into its Duo login. **Total fix: one 8-line file.**
-
-This is the **same class** MIGRATION.md's "Browser profiles" bullet already
-covers — a file Home Manager used to manage disappears, and the app reads its
-own absence as "first run" — but that bullet only names Chromium extensions.
-The Mozilla case deserves its own warning precisely because it is *louder and
-less dangerous*: Chromium silently deletes extension data (real loss, looks
-minor); Thunderbird touches nothing and merely looks away from 30 GB (no loss,
-looks catastrophic). A user who believes the second one will go restore a
-snapshot over a perfectly good profile — the recovery is the risk here.
-
-Firefox on this box shows the same fingerprint, unreported because he browses in
-Chromium: `~/.mozilla/firefox/profiles.ini` (Jul 12) points at
-`u9p8fdhh.default` (101 MB, created at migration), while
-`profiles.ini.hm-bak` — Home Manager's own backup, dated **Jun 2025** — points
-at `lfr4aapb.default` (129 MB, last used 2025-09-07), and a third profile
-`default` (290 MB) was last used 2026-03-02. So the pattern is Mozilla-family,
-not Thunderbird-specific. **Do not repoint Firefox without asking Bernardo** —
-u9p8fdhh has been in use since Jul 14 and merging profiles is his call.
-
-**What to write** (docs only, no code): in MIGRATION.md's Phase-0/browser
-section — before first launch of any Mozilla app, check that
-`~/.thunderbird/profiles.ini` and `~/.mozilla/firefox/profiles.ini` exist and
-name your real profile directory; if an app opens empty, **do not restore a
-snapshot** — `ls ~/.thunderbird` first, and if a fat profile dir is sitting
-there, it is a one-file fix. Include the working `profiles.ini` shape and the
-`Name=`/`Path=`/`Default=1` semantics.
-
-**Root cause is unproven and probably not worth chasing:** zero HM generations
-survive on disk to show whether HM ever managed that file (the Firefox
-`.hm-bak` proves it did there, in 2025), and the snapshot check needs sudo. The
-warning is worth writing either way — it costs nothing and it is the difference
-between a one-line fix and a restore that overwrites good data.
-
 ### 143. Rofi keeps the selected *row number* when the search changes, so the highlight lands on an unrelated entry
 
 Bernardo 2026-07-16, and his repro is exact: open the app menu, type `ca`, move

docs/MIGRATION.md

@@ -289,6 +289,47 @@ default yet.
   `pre-nomarchy-home` snapshot, then reinstall each extension — from
   the Web Store (ids are stable, so the data reattaches) or by
   re-declaring the ids if you want them declarative again.
+- **Thunderbird / Firefox — “all my email is gone” (it isn’t):** Mozilla
+  apps find your data through **one small text file**,
+  `~/.thunderbird/profiles.ini` (and `~/.mozilla/firefox/profiles.ini`),
+  which names the profile directory to open. Lose that file and the app
+  does not error — it does what it does on a brand-new machine: creates
+  an empty profile and cheerfully opens *that*. Every account, folder and
+  message is still on disk, in the profile dir it stopped looking at.
+  This bit us on a real migration (2026‑07‑16): a 30 GB profile with 19 GB
+  of `ImapMail` went “missing”; the fix was eight lines of `profiles.ini`.
+  **Before first launch,** check the file exists and names your real
+  profile:
+  ```console
+  $ ls ~/.thunderbird/            # bernardo/  ← the fat one is your profile
+  $ cat ~/.thunderbird/profiles.ini
+  ```
+  **If an app opens empty, do not restore a snapshot** — look first:
+  ```console
+  $ du -sh ~/.thunderbird/*/      # a multi-GB dir = your data is fine
+  ```
+  If a fat profile is sitting there, this is a pointer problem, not data
+  loss. Close the app, then write (`Path=` is the directory name, relative
+  to the `.thunderbird` dir):
+  ```ini
+  [Profile0]
+  Name=default
+  IsRelative=1
+  Path=<your-profile-dir>
+  Default=1
+
+  [General]
+  StartWithLastProfile=1
+  Version=2
+  ```
+  Keep the empty profile listed as `[Profile1]` (no `Default=`) if you
+  want it out of the way rather than deleted. The **restore is the risk
+  here**, not the bug: rolling a snapshot over a good 30 GB profile to
+  “recover” data that was never lost can cost you the mail that arrived
+  since. Same shape as the Chromium bullet above — a file HM used to
+  manage disappears and the app reads its own absence as “first run” —
+  but inverted: Chromium *deletes* quietly, Thunderbird *loses nothing*
+  and looks catastrophic.
 - **VPN:** NetworkManager connections survive under
   `/etc/NetworkManager` and your home. System › VPN lists NM
   `vpn`/`wireguard` profiles; import any that lived outside NM.

docs/ROADMAP.md

@@ -449,6 +449,17 @@ Design/decision records and a running log of shipped work (items marked
   (#131). Those windows therefore carry float/center rules and deliberately no
   `size` rule. Measured after: calendar 1536×936 = exactly 60%×65%, doctor
   1408×1008 = 55%×70%, both centred in the Waybar work area.
+- ✓ **MIGRATION.md: Mozilla `profiles.ini` (#144, 2026-07-16):** a real
+  migration ate Bernardo's `~/.thunderbird/profiles.ini`, so Thunderbird did
+  what it does on any new machine — made an empty profile and opened it —
+  while 30 GB of mail (19 GB `ImapMail`, 64 account prefs) sat untouched in the
+  directory it had stopped looking at. Recovered in eight lines. Documented as
+  its own bullet next to the Chromium one because it is the **inverse failure**
+  and the inverse danger: Chromium silently deletes extension data and looks
+  minor; Thunderbird loses nothing and looks catastrophic — so the reflex it
+  provokes (restore a snapshot over a perfectly good profile) is itself the way
+  to actually lose mail. The doc therefore leads with `ls`/`du`, not with a
+  restore.
 - ✓ **Ask hands off to a web chat (#140, 2026-07-16):** Bernardo: "opening
   claude-code is too disruptive." SUPER+CTRL+A used to spend a terminal, an npm
   fetch and a REPL on "what's the syntax for…" — the prompt was the right