Move private runtime state outside checkouts and isolate worktrees

README.md

@@ -28,9 +28,15 @@ Current state:
 - `nap auth login` stores the shared account session in the user data folder
   (`~/.local/share/napseer/credentials/default.json` on Linux; platform user data directories
   on macOS/Windows). `NAPSEER_USER_DATA_DIR` overrides that location.
-  `nap auth login --project` selects a local override. Legacy repository
-  credentials remain an explicit override until `nap auth migrate` moves them.
-  Gateway identities remain separate in `.napseer/gateway-auth.json`.
+  `nap auth login --project` selects a repository override shared by its Git
+  worktrees. Separate repositories retain separate overrides.
+- Private state lives entirely in user data. `credentials/` holds login grants;
+  `repositories/<id>/` holds the shared signing key; `workspaces/<id>/` holds
+  each worktree's selection, gateway identity, vault, index, locks, and logs.
+  Git common-directory identity groups related worktrees; each worktree's Git
+  directory identifies its runtime state, including after `git worktree move`.
+  Nested project locators keep their own namespace. Ordinary directories use
+  their canonical absolute path. Separate clones do not share project overrides.
 - `.napseer/project.json` is the commit-safe project locator. It contains only
   the schema, API origin, project UUID, and slug; it never contains tokens,
   account or worker identity, encryption state, keys, passphrases, or claim
@@ -42,6 +48,18 @@ Current state:
 Backend discovery publishes the release manifest and exact public source
 revision used for each bundle.
 
+For an existing checkout, stop older MCP clients and local gateway/UI processes,
+update the runtime, and run `nap auth migrate` once from that checkout. This moves
+private files out of `.napseer`, preserving the public locator and ignore file.
+Migration checks running gateway PIDs, copies and verifies every file before
+removing originals, and refuses conflicting destinations. An interrupted copy
+can be retried; it never selects a different login to hide a conflict. Restart
+clients afterward. Migrate existing worktrees individually; conflicting older
+credentials or signing keys must be reconciled explicitly, never overwritten.
+
+`NAPSEER_USER_DATA_DIR` and explicit credential files must point outside the
+checkout. There is no credential or private-state symlink inside the repository.
+
 Configure Codex and other long-lived stdio clients to launch:
 
 ```sh