fix(mac): bundle web chat UI deps

docs/session.md

@@ -1,66 +1,45 @@
 # Session Management
 
-CLAWDIS keeps lightweight session state so your agent can remember context between messages. Sessions are stored in a small JSON file and expire automatically after idle time or when you reset them.
+Clawdis treats **one session as primary**. By default the canonical key is `main`; set `inbound.reply.session.mainKey` to change it. Older/local sessions can stay on disk, but only the primary key is used for desktop/web chat and direct agent calls.
 
-## Where sessions live
+## Where state lives
+- Store file: `~/.clawdis/sessions/sessions.json` (legacy: `~/.warelay/sessions.json`).
+- Transcripts: `~/.clawdis/sessions/<SessionId>.jsonl` (one file per session id).
+- The store is a map `sessionKey -> { sessionId, updatedAt, ... }`. Deleting entries is safe; they are recreated on demand.
 
-- Default path: `~/.clawdis/sessions.json` (legacy: `~/.warelay/sessions.json`).
-- Override with `inbound.reply.session.store` in your config if you want a custom location.
-- The file is a plain map of `sessionKey -> { sessionId, updatedAt, ... }`; it is safe to delete if you want a full reset.
+## Mapping transports → session keys
+- Direct chats (WhatsApp, Telegram, desktop Web Chat) all collapse to the **primary key** so they share context.
+- Multiple phone numbers can map to that same key; they act as transports into the same conversation.
+- Group chats still isolate state with `group:<jid>` keys; do not reuse the primary key for groups.
 
-## How session keys are chosen
-
-- Direct chats: by default collapse to the canonical key `main` so all 1:1 channels (WhatsApp, WebChat, Telegram) share a single session.
-- Group chats: `group:<whatsapp-jid>` so group history stays isolated from DMs.
-- Global mode: set `inbound.reply.session.scope = "global"` to force a single shared session for all chats.
-- Unknown senders fall back to `unknown`.
-
-To change the canonical key (or disable collapsing), set `inbound.reply.session.mainKey` to another string or leave it empty.
-
-## When sessions reset
-
-- Idle timeout: `inbound.reply.session.idleMinutes` (default 60). If no messages arrive within this window, a new `sessionId` is created on the next message.
-- Reset triggers: `inbound.reply.session.resetTriggers` (default `['/new']`). Sending exactly `/new` or `/new <text>` starts a fresh session and passes the remaining text to the agent.
-- Manual nuke: delete the store file or remove specific keys with `jq`/your editor; a new file is created on the next message.
-
-## Configuration recap
+## Lifecyle
+- Idle expiry: `inbound.reply.session.idleMinutes` (default 60). After the timeout a new `sessionId` is minted on the next message.
+- Reset triggers: exact `/new` (plus any extras in `resetTriggers`) start a fresh session id and pass the remainder of the message through.
+- Manual reset: delete specific keys from the store or remove the JSONL transcript; the next message recreates them.
 
+## Configuration (primary-only example)
 ```json5
 // ~/.clawdis/clawdis.json
 {
   inbound: {
     reply: {
       session: {
-        scope: "per-sender",      // or "global"
-        resetTriggers: ["/new"],   // additional triggers allowed
-        idleMinutes: 120,           // extend or shrink timeout (min 1)
-        store: "~/state/clawdis-sessions.json", // optional custom path
-        mainKey: "main"             // canonical direct-chat bucket
+        scope: "per-sender",      // keep group keys separate
+        idleMinutes: 120,
+        resetTriggers: ["/new"],
+        store: "~/.clawdis/sessions/sessions.json",
+        mainKey: "main"           // marks the primary session
       }
     }
   }
 }
-
-## Surfaces (channel labels)
-
-Each inbound message can carry a `Surface` hint in the templating context (e.g., `whatsapp`, `webchat`, `telegram`, `voice`). Routing stays deterministic: replies are sent back to the origin surface, but the shared `main` session keeps context unified across direct channels. Groups retain their `group:<jid>` buckets.
-
-## WebChat history
-
-WebChat always attaches to the `main` session and hydrates the full Tau JSONL transcript from `~/.clawdis/sessions/<SessionId>.jsonl`, so desktop view reflects all turns, even those that arrived via WhatsApp/Telegram.
 ```
 
-Other session-related behaviors:
-- `thinkingLevel` and `verboseLevel` persist per session so inline directives stick until the session resets.
-- Heartbeats reuse the existing session for a recipient when available (good for keeping context warm).
-
-## Inspecting sessions
-
-- `clawdis status` shows the session store path, total count, and the five most recent keys with ages.
-- `clawdis sessions` lists every session (filter with `--active <minutes>` or use `--json` for scripts). It also reports token usage per session; set `inbound.reply.agent.contextTokens` to see the budget percentage (defaults to ~200k tokens for Opus 4.5 via pi-ai defaults).
-- For a deeper look, open the JSON store directly; the keys match the rules above.
+## Inspecting
+- `pnpm clawdis status` — shows store path and recent sessions.
+- `pnpm clawdis sessions --json` — dumps every entry (filter with `--active <minutes>`).
+- JSONL transcripts can be opened directly to review full turns.
 
 ## Tips
-
-- Keep groups isolated: mention-based triggers plus the `group:<jid>` session key prevent group traffic from contaminating your DM history.
-- If you automate cleanup, prefer deleting specific keys instead of the whole file to keep other conversations intact.
+- Keep the primary key dedicated to 1:1 traffic; let groups keep their own keys.
+- When automating cleanup, delete individual keys instead of the whole store to preserve context elsewhere.