From 352cab4a94a836e3085292de6348b54acea8a5ef Mon Sep 17 00:00:00 2001
From: vikingowl <christian@nachtigall.dev>
Date: Sun, 24 May 2026 22:29:56 +0200
Subject: [PATCH] docs(todo): extend config-migration plan with project
 registry

Adds item #5 to the config write/merge corruption entry:
~/.config/gnoma/projects.json tracking which directories gnoma has
been launched in. Enables doctor --all-projects, cross-project
session listing, and one-shot upgrade-config across all known
projects.

Documents the design constraints: must use the same omitempty /
atomic-write discipline as the encoder fix to avoid recreating the
class of bug it exists to help solve. Privacy footprint flagged
(local-only directory log; opt-out toggle). Stale-entry handling
gated through doctor, not auto-prune.
---
 TODO.md | 46 ++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 46 insertions(+)

diff --git a/TODO.md b/TODO.md
index af0aa5b..1f64a71 100644
--- a/TODO.md
+++ b/TODO.md
@@ -67,6 +67,52 @@ Active work, newest first.
        toggle, defaulting to `true`. Global configs require
        explicit `gnoma upgrade-config`.
 
+  5. **Project registry** (`~/.config/gnoma/projects.json`). Today
+     there is no record of which directories gnoma has been launched
+     in — items #2 and #3 can work with a filesystem scan
+     (`find ~ -type d -name .gnoma`), but a registry makes them
+     significantly faster and unlocks cross-project features.
+     Sketch:
+
+     ```json
+     {
+       "projects": [
+         {
+           "path": "/home/.../my-repo",
+           "first_seen": "2026-04-15T10:30:00Z",
+           "last_seen":  "2026-05-24T19:23:00Z",
+           "session_count": 47
+         }
+       ]
+     }
+     ```
+
+     Update on every successful startup (record project root,
+     bump `last_seen` + increment `session_count`). Enables:
+     - Fast `gnoma doctor --all-projects` without a filesystem walk.
+     - Cross-project session listing (`gnoma sessions --all`
+       picker; surface most-recent sessions across the registry).
+     - `gnoma upgrade-config` that can migrate every known project
+       in one invocation.
+     - Future local-only aggregate stats (`gnoma stats`) — still
+       no-phone-home, just a sum across the registry.
+
+     **Caveats and design constraints:**
+     - The registry file becomes another silent-corruption surface
+       — must use the same `omitempty` / atomic-write discipline
+       as the encoder fix in #1, or it'll exhibit the same class
+       of bug.
+     - Stale entries (deleted projects). `gnoma doctor` should
+       detect and offer to prune; do not auto-delete.
+     - Privacy: this is literally a log of directories the user
+       has worked in. Local-only, never sent off-machine (per the
+       no-phone-home positioning), but worth a one-line note in
+       the Security section of the README so users know it exists.
+     - Opt-out: `[config].project_registry = false` for users who
+       don't want this tracked. Default `true`.
+     - Atomic writes (temp file + rename) so a crash mid-write
+       doesn't corrupt the file.
+
   Surfaced from the v0.3.1 launch wave (2026-05-24).
 
 - **Bandit selector — design decisions deferred.** The current