Updates

docs/DESKTOP.md

@@ -132,26 +132,49 @@ Override home with `PEARDATA_HOME` if you need isolation (CI, multi-profile).
 
 | Module | Responsibility |
 |--------|----------------|
+| `client/paths.js` | Unified `~/.config/peardata` home |
+| `client/jsonCache.js` | Atomic JSON writes + LS mirror |
+| `client/settings.js` | UI prefs → `cache/settings.json` |
+| `client/peerCache.js` | Multi-host roster + last-active |
+| `client/bookmarks.js` | Compat shim over peerCache |
 | `client/identity.js` | Load/create keypair on disk |
 | `client/connection.js` | Single HyperDHT + protomux-rpc session |
 | `client/manager.js` | Multi-peer map, active selection, reconnect |
 | `client/errors.js` | Unwrap / normalize RPC errors for UI |
 | `app.js` | Wire DOM to manager + protocol methods |
 
+## Persistence (PearDock-style)
+
+| Store | Path |
+|-------|------|
+| Settings | `~/.config/peardata/cache/settings.json` (+ `localStorage` `peardata.settings.v1` FOUC) |
+| Peers / last-active | `~/.config/peardata/cache/peers.json` |
+| Identity | `~/.config/peardata/identity.json` |
+
+Override root with `PEARDATA_HOME`. Writes are atomic (`tmp` → rename, mode `0600`). Legacy `bookmarks.json` / `ui-settings.json` migrate on first load.
+
+### Multi-agent
+
+- Many peers can be dialed at once; **one active** owns Overview / Charts RPC.
+- Boot restores saved peers in parallel (`skipActivate`), then prefers last-active.
+- Reconnect never steals the active host unless that host was active.
+- Agents view + fleet strip: set active / connect / forget.
+- Settings → Connections: auto-restore toggle, reconnect budget, forget-all.
+
 ### Manager reconnect
 
-- Default max tries: `PEARDATA_MAX_RECONNECT` or **20**
-- `connect(input, { adminSeed, autoReconnect })`
+- Default max tries: settings `reconnectMaxAttempts` or `PEARDATA_MAX_RECONNECT` / **20**
+- `connect(input, { adminSeed, autoReconnect, skipActivate })`
 - Input may be **64-hex public key** or **`pd1.` invite**
 
-## LocalStorage keys (demo UI)
+## LocalStorage mirrors
 
 | Key | Purpose |
 |-----|---------|
-| `peardata:last-connect` | Last public key / invite string |
-| `peardata:display-name` | Last display name |
-
-These are demo convenience only — production apps often prefer a file under app storage.
+| `peardata.settings.v1` | Flat settings FOUC + offline mirror |
+| `peardata-ui-boot` | Theme-only early paint |
+| `peardata_active_peer_id` | Last active peer mirror |
+| `peardata.cache.peers` | Peers envelope mirror |
 
 ## Development tips