Persist gateway secrets and worktree state in user data

README.md

@@ -20,3 +20,22 @@ Current state:
   image. It performs no live Napseer API download during the build.
 
 The backend remains the protocol and compatibility source of truth through `/v1/gateway-protocol`.
+
+Private gateway state is stored outside the checkout using the same
+`WorkspacePaths` contract as the CLI. The image sets
+`NAPSEER_USER_DATA_DIR=/var/lib/napseer`; persist that directory in a dedicated
+volume and mount source code separately at `/workspace`. Vaults, worker grants,
+logs, indexes, and process state belong to a worktree; repository signing keys
+are shared across related Git worktrees.
+
+To migrate an existing gateway, stop its old process and retain the old volume.
+Mount that volume at `/workspace/.napseer` and the new persistent volume at
+`/var/lib/napseer`, then run the new image with
+`python3 /opt/napseer/napseer_mcp_server.py auth migrate` as its command.
+Start the service after migration succeeds. Conflicting state is preserved for
+explicit reconciliation. Do not run old and new gateway versions against the
+same credentials during migration.
+
+`resources/scripts/napseer_credentials.py` vendors the CLI's private-state
+contract so the gateway image requires no runtime download. Keep its path and
+migration behavior aligned with the CLI when changing storage layout.