[Quintasan]

Pi Pocket keeps everything in one folder, ~/.pi-pocket: the database, people and their tokens, uploads, worktrees, extension drop-ins, the tunnel's log, and the browser's profile. Nothing there follows the XDG base directory spec, and it mixes secrets with caches.

This splits them by kind, the way the spec asks:

Kind	Default	Holds
config	~/.config/pi-pocket	config.json (people, roles, tokens, settings), launcher.json
data	~/.local/share/pi-pocket	pocket.sqlite and its lock, push.json, uploads/, worktrees/, repos/, gallery/, themes/, extensions/
state	~/.local/state/pi-pocket	the Cloudflare tunnel's log
cache	~/.cache/pi-pocket	the downloaded cloudflared, the built-in browser's profile

XDG_*_HOME moves them. PI_POCKET_CONFIG_DIR, PI_POCKET_DATA_DIR, PI_POCKET_STATE_DIR, and PI_POCKET_CACHE_DIR name each one itself, so the --data option and PI_POCKET_DIR are gone (they named one folder, which is no longer the shape). The launcher passes the four resolved folders to the server, so the two always agree.

Migration. src/server/dirs.ts moves an older ~/.pi-pocket into the four, once, entry by entry:

• it runs only where the destination has nothing, so a migration cut off midway finishes on the next start;
• a file it does not recognise is left where it is, with a line naming it;
• a database already in the data folder is kept and named, instead of being passed over in silence while the app runs on it;
• a Pi Pocket still running on the old folder (a live harness.lock) stops the migration with a message, rather than moving a database out from under it;
• a cross-filesystem move copies to a .partial name and renames it into place, so a copy cut short is never mistaken for a finished one;
• the legacy folder is removed only when it is empty.

Compatibility. host.dataDir keeps meaning the data folder, and nothing in types/pocket.d.ts changes, so no module or reference page gets a new Since line. The lock stays in the data folder: it guards that database and its message says which folder is taken, so a second instance with its own data folder still runs. The NixOS module pins all four folders to dataDir, so an existing service deployment keeps its files exactly where they are rather than starting on empty folders.

Tested. npm run format, npm run check, npm run lint, and npm test: 356 tests, 315 pass, 8 fail — the same 8 test/pi-sessions.test.ts tests that fail on main here before any change (this machine's Pi session files), plus model-refresh intermittently. New tests in test/dirs.test.ts cover the XDG precedence (including relative, empty, and PI_POCKET_*_DIR overrides), the folder modes, a full legacy migration (database with -wal/-shm, extensions, worktrees, repos, tunnel log, cloudflared, browser profile), idempotency, no overwriting, the database-already-there case, and the still-running case. test/qol.test.ts now checks a guest cannot read config.json, launcher.json, pocket.sqlite, push.json, the tunnel log, the browser's cookies, or what a migration left in the old folder. Also ran a throwaway-HOME end-to-end check: a fake legacy folder migrates into the four, an unknown file stays behind with a line, and a second run does nothing.

One known effect: documents written before the upgrade name files by their old absolute path — an older message's attachments, an isolated session's worktree, a PiP clone in a session's folder. Those paths move with everything else, and the migration log says so, but the old messages and sessions then point at the old folder. Keeping ~/.pi-pocket (or symlinking uploads/, worktrees/, and repos/ back to the data folder) keeps them working; rewriting the stored paths would be a separate change. Say if you would like that in this PR instead.

Also updated the docs the paths appear in (README.md, AGENTS.md, SECURITY.md, docs/**, site/**) and the NixOS module and its tests.