@bakapiano/ccsm 0.14.0 → 0.15.1

package/CLAUDE.md

@@ -1,475 +1,474 @@
-# ccsm — Claude Code Session Manager
-
-A small Node/Express + Preact web tool that runs every Claude/Codex/
-Copilot CLI session inside a single web app. PTYs live in-process
-(node-pty), sessions persist across restarts, and `--resume <uuid>`
-reattaches to the exact upstream conversation.
-
-## Why this exists
-
-When you're running 8–10 concurrent `claude` sessions across ad-hoc
-clones (`D:\proj`, `D:\proj2`, `…`, plus GUID worktree dirs), it's easy
-to lose track of which terminal is which session. ccsm gives an
-at-a-glance sidebar, organises sessions into folders, and `--resume`s
-each one in the same xterm.js panel.
-
-## Architecture: hosted frontend + local backend
-
-The frontend is **not** bundled in the npm package — it's hosted on
-GitHub Pages and matched to your installed backend version through a
-version router.
-
-```
-┌── browser ────────────────────────────┐
-│  https://bakapiano.github.io/ccsm/    ← version router (tiny)
-│                       ↓
-│  https://bakapiano.github.io/ccsm/X.Y.Z/  ← per-version frontend
-└────────────┬──────────────────────────┘
-             │  fetch /api/*   (CORS, allow-list)
-             │  ws://localhost:7777/ws/*
-             ▼
-┌── local backend ──────────────────────┐
-│  npm i -g @bakapiano/ccsm             │
-│  ccsm                                  │
-│   ├── /api/sessions  /api/sessions/new │
-│   ├── /api/sessions/:id/resume         │
-│   ├── /api/sessions/adopt              │
-│   ├── /ws/terminal/:id (PTY)           │
-│   ├── /api/version  /api/upgrade       │
-│   ├── /api/heartbeat /api/health       │
-│   └── /api/shutdown                    │
-└───────────────────────────────────────┘
-```
-
-**Version routing.** GH Pages root (`/ccsm/`) hosts a tiny static
-router (`pages-root/index.html`) that probes `localhost:7777/api/health`
-and redirects to `./<backend.version>/`. Each release publishes a fresh
-`/ccsm/<X.Y.Z>/` subdir; old ones stay forever via the workflow's
-`keep_files: true`. Result: a 1:1 frontend↔backend version pin, no
-semver-compat logic, and old backends keep working indefinitely.
-
-Each per-version frontend has its version baked into a `<meta
-name="ccsm-frontend-version">` at deploy time (injected by the GH Pages
-workflow). On boot it re-fetches `/api/health` and bounces back through
-the router via `location.replace('../')` if the backend has since been
-upgraded.
-
-When the backend is offline the router itself shows a "Start ccsm" UI
-with a `ccsm://start` link (same protocol-handler trick we already
-register at install time). No need to redirect to a stale version.
-
-**Dev mode.** When running from a checkout (`__dirname` not under
-`node_modules`), the backend ALSO serves `public/` so contributors can
-iterate at `localhost:7777/` without pushing. In dev there's no
-`<meta>` tag → the version guard no-ops.
-
-## Run
-
-```powershell
-# install once
-npm install -g @bakapiano/ccsm
-
-# then anywhere
-ccsm
-```
-
-`ccsm` opens the version router in a chromeless Edge `--app=` window.
-Terminal returns immediately (the server is spawned detached). Close
-the window → server saves a final snapshot of state and exits within
-~12s.
-
-If you don't want the auto-opened window (e.g. you live in the PWA),
-just visit `https://bakapiano.github.io/ccsm/` — when backend is
-down you see the inline OfflineBanner with a **Start ccsm** button.
-
-Default port `7777`, default workDir `~/ccsm-workspaces`. Config +
-state live at `~/.ccsm/` (override with `CCSM_HOME=<path>`). All
-settings editable through the Configure page
-(`~/.ccsm/config.json` on disk). Notable knobs:
-
-- `port` (default `7777`) — preferred listen port. If taken, ccsm tries `+1..+9` then asks the OS for any free port.
-- `browserMode` (default `app`) — `app` finds Edge or Chrome and spawns it with `--app=<url> --user-data-dir=<DATA_DIR>/browser-profile`. `tab` opens the default browser. `none` skips opening.
-- `clis` — array of CLI definitions. Built-ins for `claude`, `codex`, `copilot`; users can add `other` CLIs with custom `command`, `args`, `resumeArgs`, `resumeIdArgs`, `shell` (direct/pwsh/cmd).
-- `defaultCliId` — which CLI the Launch page pre-selects.
-
-## ccsm:// protocol · "wake on click"
-
-The hosted frontend can't spawn processes (sandboxed). For "click to
-wake backend" we register a per-user URL protocol handler on Windows:
-
-```
-HKCU\Software\Classes\ccsm\shell\open\command
-  → wscript.exe "<LOCALAPPDATA>\ccsm\launcher.vbs" "%1"
-```
-
-`launcher.vbs` uses `Shell.Run(..., 0, False)` — windowstyle 0 means the
-spawned `ccsm.cmd` runs **completely hidden**. No console flash. The
-`.cmd` goes through `bin/ccsm.js`, which detects `ccsm://start` in argv,
-spawns `server.js` detached with `CCSM_NO_BROWSER=1`, and exits.
-
-The router's "Start ccsm" button (and OfflineBanner inside each
-per-version frontend) is just `<a href="ccsm://start">`. First click
-triggers a one-time Windows confirmation dialog ("Open ccsm.cmd?");
-ticking "Always allow" makes it silent thereafter.
-
-postinstall (`scripts/install.js`) registers the protocol
-unconditionally on Windows — including npx-cache installs. The path
-stored in the registry points at whatever `ccsm.cmd` location npm gave
-us (`<prefix>/ccsm.cmd` from `npm config get prefix`).
-
-## In-app upgrade
-
-About page surfaces the installed version, polls
-`registry.npmjs.org/@bakapiano%2Fccsm/latest` (cached 30 min) for the
-latest published version, and offers an **Upgrade** button when newer.
-`POST /api/upgrade` spawns `npm i -g @bakapiano/ccsm@latest` detached,
-then on success spawns a fresh `ccsm` (also detached) and
-gracefulShutdowns. The OfflineBanner appears briefly; the router then
-picks up the new version on its next probe.
-
-The `target` field is regex-validated (`/^[a-z0-9.+\-^~]+$/i`) before
-the spawn — npm install doesn't shell out, but defends against argv
-weirdness regardless. Concurrent calls return `409`.
-
-## Lifecycle
-
-Single `gracefulShutdown(reason)` function in `server.js` is the only
-exit path. It kills any PTY children, then `process.exit(0)`. Every
-trigger funnels here:
-
-| trigger | path |
-|---|---|
-| auto-spawned browser window closes | `child.on('exit')` — see smart-kill below |
-| `POST /api/shutdown` | from npm uninstall, from launcher's auto-upgrade |
-| `POST /api/upgrade` after install completes | self-restart |
-| SIGINT / SIGTERM | OS signals |
-| heartbeat watchdog timeout | 90s with no heartbeat, only when launched via `bin/ccsm.js` |
-
-**Smart browser-exit**: when the spawned browser child dies, we don't
-kill immediately. Two filters:
-
-1. **Fast-exit (<5s)** — Edge `--app=` often hands the URL off to an existing Edge profile process group and the spawned child dies milliseconds after creation. We ignore any exit inside the first 5s.
-2. **Deferred multi-client check (12s)** — after a real close, wait 12s and check if any heartbeat arrived AFTER the close timestamp. If yes, a hosted-frontend tab (or another window) is keeping us busy, stay alive. If no, gracefulShutdown.
-
-Frontend heartbeat cadence is 10s (in `main.js`), so one full cycle
-fits inside the 12s decision window.
-
-Environment overrides:
-- `CCSM_KEEP_ALIVE=1` → disable both browser-exit hook and heartbeat watchdog. For automation hosts.
-- `CCSM_LAUNCHER=1` → set by `bin/ccsm.js` when it spawns the server; enables the heartbeat watchdog.
-- `CCSM_NO_BROWSER=1` → set by the launcher when handling a `ccsm://` click or by `/api/upgrade` self-respawn; suppresses the server's auto-open browser.
-- `CCSM_NO_DEV=1` → suppress dev-mode features (static serving, hot-reload SSE) even when running from a checkout.
-
-## Sessions: persisted, adopted, resumed
-
-There's **one source of truth**: `~/.ccsm/sessions.json`, managed by
-`lib/persistedSessions.js`. Every session ccsm starts goes in there
-with `{ id, cliId, cwd, workspace, title, folderId, repos,
-cliSessionId, status, … }`. We don't enumerate `~/.claude/` or walk
-process trees anymore.
-
-**`cliSessionId` capture.** For `claude` / `codex` / `copilot`, on
-spawn we kick off `lib/cliSessionWatcher.js`. It polls the CLI's
-transcript directory (`~/.claude/projects/<slug>/`,
-`~/.codex/sessions/`, `~/.copilot/session-state/`) for a new file whose
-recorded cwd matches our spawn cwd, then stores its UUID into the
-record. Later, **resume** rewrites the args using the CLI's
-`resumeIdArgs` template (`['--resume', '<id>']`) so the upstream
-conversation reattaches precisely. Fallback when no UUID is captured:
-`cli.resumeArgs` (`--continue` / `resume --last`).
-
-Watcher lifecycle: 5-minute timeout. If no transcript ever appears,
-the ccsm record is removed (we assume the user closed the CLI before
-it persisted anything). The cleanup fn returned by `captureSessionId`
-is tracked in a module-scope `Map` keyed by ccsm session id, and torn
-down on PTY exit and on session delete — otherwise a still-running
-watcher could match a future session's transcript and stamp the wrong
-UUID onto a dead record.
-
-If the record already has a `cliSessionId` (typical for resume and
-**always** for `adopt`-imported sessions), we skip the watcher
-entirely — there's nothing left to capture, and the timeout would
-wipe the record after 5 min.
-
-**Adopt.** "Import existing session" on the Launch page lists
-sessions found on disk (`/api/cli-sessions/:type`) and lets the user
-add one to ccsm with `/api/sessions/adopt`. The created record is
-born `status: 'exited'` with `cliSessionId` pre-set. Clicking it in
-the sidebar runs the normal resume flow — which uses the captured id.
-
-**Auto-resume.** SessionsPage doesn't show a "Resume" button. On
-mount, if the active session's status isn't `running`, it calls
-`resumeSession()`. `resumeSession()` in `api.js` keeps a per-id
-in-flight Map so the same call from Sidebar.onClick and the
-SessionsPage effect collapse into a single backend hit.
-
-## Layout
-
-```
-ccsm/
-├── server.js                     # Express + WebSocket; API-only in prod
-├── bin/ccsm.js                   # launcher · detach, wake-on-protocol,
-│                                 # auto-upgrade-restart, first-run hint
-├── scripts/
-│   ├── install.js                # postinstall · ccsm:// + launcher.vbs
-│   └── uninstall.js              # preuninstall · cleanup + /api/shutdown
-├── lib/
-│   ├── persistedSessions.js      # ~/.ccsm/sessions.json — source of truth
-│   ├── folders.js                # ~/.ccsm/folders.json — sidebar tree
-│   ├── localCliSessions.js       # scan ~/.claude · ~/.codex · ~/.copilot
-│   ├── cliSessionWatcher.js      # capture upstream session UUID after spawn
-│   ├── workspace.js              # ws-N allocation under workDir, repo clones
-│   ├── webTerminal.js            # in-process PTY pool · node-pty + WebSocket
-│   ├── jsonStore.js              # shared keyed-JSON store factory
-│   └── config.js                 # loadConfig / saveConfig + DATA_DIR
-├── pages-root/                   # pushed to GH Pages /
-│   ├── index.html                # version router · probe localhost, redirect
-│   ├── manifest.webmanifest      # PWA · stable id, start_url: ./
-│   └── favicon.svg
-└── public/                       # pushed to GH Pages /<version>/
-    ├── index.html                # workflow injects <meta ccsm-frontend-version>
-    ├── manifest.webmanifest      # per-version (links back to root scope)
-    ├── favicon.svg
-    ├── js/
-    │   ├── backend.js            # httpBase() / wsBase() — same-origin local, cross-origin hosted
-    │   ├── main.js               # boot · version guard · clock · heartbeat
-    │   ├── state.js              # signals
-    │   ├── api.js                # fetch wrapper + loaders + dedup-aware resumeSession
-    │   ├── streaming.js          # NDJSON clone-progress stream
-    │   ├── dialog.js · toast.js  # ccsmConfirm / ccsmPrompt / setToast
-    │   ├── html.js · icons.js · util.js
-    │   ├── components/
-    │   │   ├── App.js · Sidebar.js · PageTitleBar.js
-    │   │   ├── ServerStatus.js · Toast.js · OfflineBanner.js · DialogHost.js
-    │   │   ├── Card.js · Modal.js · Popover.js · Picker.js · EntityFormModal.js
-    │   │   ├── DirectoryPicker.js · AdoptModal.js
-    │   │   ├── ProgressList.js · TerminalView.js · useDragSort.js
-    │   └── pages/
-    │       ├── SessionsPage.js · LaunchPage.js
-    │       ├── ConfigurePage.js · AboutPage.js
-    └── css/                      # 12 focused stylesheets
-        ├── tokens.css · base.css · layout.css
-        ├── sidebar.css · cards.css · forms.css
-        ├── widgets.css · feedback.css · modal.css
-        ├── terminals.css · wco.css · responsive.css
-
-~/.ccsm/                          # or $CCSM_HOME
-├── config.json                   # source of truth
-├── sessions.json                 # persisted sessions (id, cliSessionId, …)
-├── folders.json                  # folder tree
-├── server.log                    # detached-server stdout/stderr
-├── .first-run-shown              # marker so launcher only prints PWA hint once
-└── browser-profile/              # Edge/Chrome --user-data-dir when browserMode=app
-
-%LOCALAPPDATA%/ccsm/
-└── launcher.vbs                  # silent ccsm:// dispatcher (written by postinstall)
-
-HKCU\Software\Classes\ccsm        # URL protocol registration
-```
-
-On first run, if a legacy `<repo>/data/` directory exists and `~/.ccsm/`
-is empty, `lib/config.js` copies the old data over (one-time,
-idempotent).
-
-## Locked-in design decisions
-
-**Single in-app terminal, no `wt`.** PTYs run in-process via node-pty
-and stream to xterm.js over `/ws/terminal/:id`. We dropped the
-`wt`-per-session, focus-by-HWND, snapshot-of-live-claudes layer
-entirely — too platform-specific and the web terminal handles
-everything the old path did.
-
-**Workspace = folder holding multiple repo clones.** Each `ws-N` under
-`workDir` contains a subdirectory per cloned repo. CLIs launch at the
-workspace root so all selected repos are sibling folders.
-
-**Workspace naming.** Auto-allocated names are `ws-1`, `ws-2`, …
-(lowest free integer). Hand-named folders under `workDir` are still
-picked up.
-
-**Frontend trusts the backend's capability advertisement.**
-`/api/capabilities` returns `{ webTerminal: true|false, ... }`. The
-frontend uses ONLY features the backend says it has. Breaking changes
-ship a new `/ccsm/<X.Y.Z>/` frontend; the router pins users to the
-matching version.
-
-**One source of truth for cross-origin.** `public/js/backend.js`
-exports `httpBase()` and `wsBase()`. Localhost → same-origin (empty
-base). Anything else → `http://localhost:7777`. CORS on the backend
-allows `https://bakapiano.github.io` only — never `*`.
-
-## API surface
-
-| Method | Path | Purpose |
-|---|---|---|
-| GET / PUT | `/api/config` | read / replace config |
-| GET | `/api/sessions` | list persisted sessions |
-| PUT | `/api/sessions/:id` | rename / move to folder |
-| DELETE | `/api/sessions/:id` | kill PTY + drop record + stop any watcher |
-| POST | `/api/sessions/new` | body `{cliId, cwd?, repos?, folderId?, title?}` — NDJSON stream (workspace · clone-progress · launched) |
-| POST | `/api/sessions/:id/resume` | re-spawn at `cwd` with `cli.resumeIdArgs <id>` (fallback `resumeArgs`) |
-| GET | `/api/cli-sessions/:type` | scan disk for unimported `claude`/`codex`/`copilot` sessions |
-| POST | `/api/sessions/adopt` | body `{cliId, cliSessionId, cwd, title?, folderId?}` — create a `status:exited` record with `cliSessionId` pre-set |
-| GET | `/api/folders` · POST `/api/folders` · PUT/DELETE `/api/folders/:id` · POST `/api/folders/reorder` | folder CRUD |
-| GET | `/api/workspaces` | workspaces under workDir with repo clone status + in-use flag |
-| GET | `/api/browse` | directory browser for the Launch page workdir picker |
-| GET | `/api/version` | `{ current, latest, updateAvailable, fetchedAt, cached, error? }` (npm registry cached 30 min, `?refresh=1` to bust) |
-| POST | `/api/upgrade` | body `{target?}` — `npm i -g @bakapiano/ccsm@<target>` then self-restart |
-| GET | `/api/capabilities` | `{ webTerminal: bool, ... }` for frontend feature gating |
-| GET | `/api/health` | `{ ok, pid, version, name }` — used by router probe + heartbeat |
-| POST | `/api/heartbeat` | called every 10s by the frontend; feeds lifecycle decisions |
-| POST | `/api/spawn-browser` | open another browser window into the running server (used by `bin/ccsm.js` for auto-upgrade-restart) |
-| POST | `/api/shutdown` | gracefulShutdown — used by uninstall + auto-upgrade |
-| WS | `/ws/terminal/:id` | xterm.js bridge to a PTY in the webTerminal pool |
-| GET (dev) | `/api/dev/ping` · `/api/dev/reload` | hot-reload SSE (only when running from a checkout) |
-
-`/api/sessions/new` streams **NDJSON** (one JSON object per line). Event
-types: `workspace`, `clone-start`, `clone-progress` (phase/percent/
-current/total/detail), `clone-line` (raw git stderr line when not a
-progress line), `clone-end`, `launched`, `done`. The frontend reads it
-with `fetch().body.getReader()` + `TextDecoder` and updates per-repo
-progress bars live.
-
-**WebSocket Origin check**: same allow-list as CORS. The upgrade handler
-rejects any Origin not in `ALLOWED_ORIGINS` (plus localhost/127.0.0.1).
-Browsers always send Origin on WS upgrades.
-
-## Non-obvious gotchas
-
-**`firstJsonField` close-event race.** `lib/cliSessionWatcher.js` reads
-the first few lines of the upstream CLI's transcript to extract its
-`cwd` field. `readline.close()` synchronously emits `'close'` on
-Windows, which would re-enter `done(null)` and clobber a freshly
-resolved value. Guarded by a `settled` flag.
-
-**Watcher rejected entries are NOT memoised by mtime.** Earlier
-implementations cached "this file was old at first poll, skip forever".
-Wrong — `claude` *appends* to an existing transcript on `--resume`, so
-the file's mtime later crosses `spawnAt` and the watcher must
-re-evaluate. Only `cwd`-mismatch rejections are memoised (those are
-stable per file).
-
-**Adopt is atomic.** `persistedSessions.create()` accepts `status` +
-`cliSessionId` so the adopt endpoint writes the record in a single
-file write rather than `create({running})` + `update({exited,
-cliSessionId})`. The two-write form had a window where a concurrent
-GET /api/sessions could see `running` with no live PTY, fooling the
-sidebar's "skip resume if running" guard.
-
-**Auto-resume dedup is module-level in api.js.** Sidebar.onClick and
-SessionsPage's effect can both fire for the same exited session in the
-same tick. `resumeSession()` keeps a per-id in-flight `Map` so the
-second caller awaits the first one's promise instead of issuing a
-second `/resume`.
-
-**Heartbeat watchdog only when launched.** Set via `CCSM_LAUNCHER=1` by
-`bin/ccsm.js`. If you start `server.js` directly (e.g. dev), the
-90-second timeout doesn't apply — convenient when stepping through
-code, but you have to ctrl-c yourself when done.
-
-**ccsm:// silent dispatch.** Direct registration of `ccsm.cmd` as the
-protocol handler causes a brief console window flash (cmd hosts the
-.cmd file). The wscript.exe + .vbs wrapper avoids it entirely — wscript
-is a Windows-subsystem host (no console) and `Shell.Run(..., 0, False)`
-launches the target hidden. The `.vbs` is generated at install time
-with the correct ccsm.cmd path baked in.
-
-**Edge --app handoff race.** When the user has an existing Edge profile
-process running, `--app=URL --user-data-dir=DIR` against the same DIR
-may cause the new msedge.exe to immediately exit after handing the URL
-off to the existing process. Our child handle dies milliseconds after
-spawn. The lifecycle hook ignores any browser-child exit inside the
-first 5s for exactly this reason.
-
-## Frontend design language
-
-The UI deliberately copies **claude.ai's** calm light aesthetic — warm
-cream surfaces, generous spacing, soft borders, **no orange highlights**.
-The brand orange `#b3614a` survives only in the brand mark / wordmark
-dot. Every other "highlight" use (selection, focus rings, dirty
-indicators, progress bars, page-actions banner) is ink/gray.
-
-**Palette** (CSS vars in `public/css/tokens.css`):
-- `--bg`            `#faf9f5`  warm cream page background
-- `--bg-elev`       `#ffffff`  card surfaces
-- `--sidebar-bg`    `#faf9f5`  (same as `--bg`, single continuous surface)
-- `--border`        `#e8e3d5`
-- `--ink`           `#1a1815`  body text (warm near-black, also used for terminal background)
-- `--ink-mid` / `--ink-muted` / `--ink-faint`
-- `--accent`        `#b3614a`  desaturated terracotta — brand only
-- Status: green `#4a8a4a` idle · blue `#4a73a5` busy (pulsing) · red `#b73f3f` danger
-
-**Type**:
-- Body / headings: **Geist** (Google Fonts, 300–700).
-- Mono: **JetBrains Mono** for paths, PIDs, sessionIds, branch tags.
-- Always `font-variant-numeric: tabular-nums` on numeric cells.
-
-**Buttons**:
-- `.action` (default) — white bg, ink-mid border, ink text.
-- `.action.primary` — black ink bg, white text. The "do this" CTA.
-- `.action.subtle` — transparent bg, light border.
-- `.action.danger` — filled red bg + white text.
-
-**Layout**:
-- Sidebar (collapsible, ~232px ↔ ~60px, state in `localStorage["ccsm.sidebar-collapsed"]`)
-  - brand mark + `CCSM.` wordmark
-  - tabs: Sessions / Launch / Configure / About
-  - folder tree of persisted sessions (drag-sortable)
-- Page-title bar: title on the left, server-status pill + Refresh button on the right
-- Top-right control group uses fixed `min-height: 28px` and `border-radius: 999px` so server-status + Refresh align as a coherent control row
-
-**No emoji in the UI** unless the user typed it. Use inline SVG icons
-everywhere (line stroke, 1.5–2px) so they take `currentColor`.
-
-**PWA + WCO**:
-- `display_override: ["window-controls-overlay", "standalone"]` in the manifest. When installed and launched as PWA, the title bar's middle is reclaimed; only OS controls float top-right.
-- `public/css/wco.css` provides drag regions (`-webkit-app-region: drag`) on `.sidebar-brand`, `.page-head`, etc., unconditional. Interactive elements opt out via the no-drag block.
-- The root PWA manifest at `pages-root/manifest.webmanifest` has stable `id: /ccsm/` so installs survive across version-router redirects to new `/ccsm/<X.Y.Z>/` subdirs.
-
-## Versioning
-
-The hosted frontend lives at `https://bakapiano.github.io/ccsm/`. The
-deploy workflow publishes two things to gh-pages on every push to main:
-
-1. `pages-root/` → `/` (the router, plus root PWA manifest)
-2. `public/` → `/<pkg.version>/` (the per-version frontend; workflow injects `<meta name="ccsm-frontend-version">` at build time)
-
-Old version dirs stay forever (`keep_files: true`), so a user on an
-older backend keeps loading the matching frontend until they upgrade.
-
-`bin/ccsm.js` does auto-upgrade-restart: when the user runs `ccsm` and
-the installed package version differs from a running backend, it POSTs
-`/api/shutdown` to the old, waits for the port to free, then spawns a
-fresh server. So `npm i -g @bakapiano/ccsm@latest && ccsm` is one
-seamless step. From the frontend, the About page's Upgrade button
-achieves the same thing without leaving the browser.
-
-## Cross-platform
-
-Today: Windows-first.
-
-Cross-platform-clean already:
-- Frontend (pure web)
-- Router page (pure HTML/JS)
-- `bin/ccsm.js` (pure node)
-- `lib/webTerminal.js` (node-pty handles platform)
-- `lib/persistedSessions.js`, `lib/folders.js`, `lib/config.js`, `lib/jsonStore.js`, `lib/cliSessionWatcher.js`, `lib/localCliSessions.js`, `lib/workspace.js` (fs only)
-- `server.js` Express + ws
-
-Windows-specific (need ports for Mac/Linux):
-- `scripts/install.js` — uses `reg.exe` and `wscript.exe`. Mac: write `Info.plist` with `CFBundleURLTypes`. Linux: write `~/.local/share/applications/ccsm.desktop` with `MimeType=x-scheme-handler/ccsm`.
-- The `--app=` browser detection and PATH-merge in `server.js` are Windows-shaped (Edge first, registry HKCU\Environment for PATH).
-
-Pattern for adding a platform: `switch (process.platform)` at each
-entry point in those files. Each platform branch is roughly 50-100
-lines.
-
-## Extending
-
-When adding features, the natural extension points:
-- **New REST routes**: `server.js` (keep under `/api/*`, use the `asyncH` wrapper, decide if it needs CORS by being in the allow-list).
-- **Frontend page**: `public/js/pages/<Name>Page.js`, route in `App.js`, sidebar nav item in `Sidebar.js`, heading in `state.js`'s `TAB_HEADINGS`.
-- **Persistent user data**: drop a JSON file under `~/.ccsm/` and use `lib/jsonStore.js`'s factory.
-- **Different CLIs**: add a built-in to `DEFAULT_CLIS` in `lib/config.js`, an icon to `public/js/icons.js`, and (if the CLI persists transcripts on disk) a `profile` to `lib/cliSessionWatcher.js` and a list helper to `lib/localCliSessions.js`.
-- **A capability**: advertise via `/api/capabilities`. Frontend gates UI on `caps.<feature>`.
-- **Bumping the frontend**: just `npm version <patch|minor|major>` + push. The GH Pages workflow publishes to `/<new-version>/` and the router redirects users to it.
+# ccsm — Claude Code Session Manager
+
+A small Node/Express + Preact web tool that runs every Claude/Codex/
+Copilot CLI session inside a single web app. PTYs live in-process
+(node-pty), sessions persist across restarts, and `--resume <uuid>`
+reattaches to the exact upstream conversation.
+
+## Why this exists
+
+When you're running 8–10 concurrent `claude` sessions across ad-hoc
+clones (`D:\proj`, `D:\proj2`, `…`, plus GUID worktree dirs), it's easy
+to lose track of which terminal is which session. ccsm gives an
+at-a-glance sidebar, organises sessions into folders, and `--resume`s
+each one in the same xterm.js panel.
+
+## Architecture: hosted frontend + local backend
+
+The frontend is **not** bundled in the npm package — it's hosted on
+GitHub Pages and matched to your installed backend version through a
+version router.
+
+```
+┌── browser ────────────────────────────┐
+│  https://bakapiano.github.io/ccsm/    ← version router (tiny)
+│                       ↓
+│  https://bakapiano.github.io/ccsm/X.Y.Z/  ← per-version frontend
+└────────────┬──────────────────────────┘
+             │  fetch /api/*   (CORS, allow-list)
+             │  ws://localhost:7777/ws/*
+             ▼
+┌── local backend ──────────────────────┐
+│  npm i -g @bakapiano/ccsm             │
+│  ccsm                                  │
+│   ├── /api/sessions  /api/sessions/new │
+│   ├── /api/sessions/:id/resume         │
+│   ├── /api/sessions/adopt              │
+│   ├── /ws/terminal/:id (PTY)           │
+│   ├── /api/version  /api/upgrade       │
+│   ├── /api/heartbeat /api/health       │
+│   └── /api/shutdown                    │
+└───────────────────────────────────────┘
+```
+
+**Version routing.** GH Pages root (`/ccsm/`) hosts a tiny static
+router (`pages-root/index.html`) that probes `localhost:7777/api/health`
+and redirects to `./<backend.version>/`. Each release publishes a fresh
+`/ccsm/<X.Y.Z>/` subdir; old ones stay forever via the workflow's
+`keep_files: true`. Result: a 1:1 frontend↔backend version pin, no
+semver-compat logic, and old backends keep working indefinitely.
+
+Each per-version frontend has its version baked into a `<meta
+name="ccsm-frontend-version">` at deploy time (injected by the GH Pages
+workflow). On boot it re-fetches `/api/health` and bounces back through
+the router via `location.replace('../')` if the backend has since been
+upgraded.
+
+When the backend is offline the router itself shows a "Start ccsm" UI
+with a `ccsm://start` link (same protocol-handler trick we already
+register at install time). No need to redirect to a stale version.
+
+**Dev mode.** When running from a checkout (`__dirname` not under
+`node_modules`), the backend ALSO serves `public/` so contributors can
+iterate at `localhost:7777/` without pushing. In dev there's no
+`<meta>` tag → the version guard no-ops.
+
+## Run
+
+```powershell
+# install once
+npm install -g @bakapiano/ccsm
+
+# then anywhere
+ccsm
+```
+
+`ccsm` opens the version router in a chromeless Edge `--app=` window.
+Terminal returns immediately (the server is spawned detached). Close
+the window → server saves a final snapshot of state and exits within
+~12s.
+
+If you don't want the auto-opened window (e.g. you live in the PWA),
+just visit `https://bakapiano.github.io/ccsm/` — when backend is
+down you see the inline OfflineBanner with a **Start ccsm** button.
+
+Default port `7777`, default workDir `~/ccsm-workspaces`. Config +
+state live at `~/.ccsm/` (override with `CCSM_HOME=<path>`). All
+settings editable through the Configure page
+(`~/.ccsm/config.json` on disk). Notable knobs:
+
+- `port` (default `7777`) — preferred listen port. If taken, ccsm tries `+1..+9` then asks the OS for any free port.
+- `browserMode` (default `app`) — `app` finds Edge or Chrome and spawns it with `--app=<url> --user-data-dir=<DATA_DIR>/browser-profile`. `tab` opens the default browser. `none` skips opening.
+- `clis` — array of CLI definitions. Built-ins for `claude`, `codex`, `copilot`; users can add `other` CLIs with custom `command`, `args`, `resumeArgs`, `resumeIdArgs`, `shell` (direct/pwsh/cmd).
+- `defaultCliId` — which CLI the Launch page pre-selects.
+
+## ccsm:// protocol · "wake on click"
+
+The hosted frontend can't spawn processes (sandboxed). For "click to
+wake backend" we register a per-user URL protocol handler on Windows:
+
+```
+HKCU\Software\Classes\ccsm\shell\open\command
+  → wscript.exe "<LOCALAPPDATA>\ccsm\launcher.vbs" "%1"
+```
+
+`launcher.vbs` uses `Shell.Run(..., 0, False)` — windowstyle 0 means the
+spawned `ccsm.cmd` runs **completely hidden**. No console flash. The
+`.cmd` goes through `bin/ccsm.js`, which detects `ccsm://start` in argv,
+spawns `server.js` detached with `CCSM_NO_BROWSER=1`, and exits.
+
+The router's "Start ccsm" button (and OfflineBanner inside each
+per-version frontend) is just `<a href="ccsm://start">`. First click
+triggers a one-time Windows confirmation dialog ("Open ccsm.cmd?");
+ticking "Always allow" makes it silent thereafter.
+
+postinstall (`scripts/install.js`) registers the protocol
+unconditionally on Windows — including npx-cache installs. The path
+stored in the registry points at whatever `ccsm.cmd` location npm gave
+us (`<prefix>/ccsm.cmd` from `npm config get prefix`).
+
+## In-app upgrade
+
+About page surfaces the installed version, polls
+`registry.npmjs.org/@bakapiano%2Fccsm/latest` (cached 30 min) for the
+latest published version, and offers an **Upgrade** button when newer.
+`POST /api/upgrade` spawns `npm i -g @bakapiano/ccsm@latest` detached,
+then on success spawns a fresh `ccsm` (also detached) and
+gracefulShutdowns. The OfflineBanner appears briefly; the router then
+picks up the new version on its next probe.
+
+The `target` field is regex-validated (`/^[a-z0-9.+\-^~]+$/i`) before
+the spawn — npm install doesn't shell out, but defends against argv
+weirdness regardless. Concurrent calls return `409`.
+
+## Lifecycle
+
+Single `gracefulShutdown(reason)` function in `server.js` is the only
+exit path. It kills any PTY children, then `process.exit(0)`. Every
+trigger funnels here:
+
+| trigger | path |
+|---|---|
+| auto-spawned browser window closes | `child.on('exit')` — see smart-kill below |
+| `POST /api/shutdown` | from npm uninstall, from launcher's auto-upgrade |
+| `POST /api/upgrade` after install completes | self-restart |
+| SIGINT / SIGTERM | OS signals |
+| heartbeat watchdog timeout | 90s with no heartbeat, only when launched via `bin/ccsm.js` |
+
+**Smart browser-exit**: when the spawned browser child dies, we don't
+kill immediately. Two filters:
+
+1. **Fast-exit (<5s)** — Edge `--app=` often hands the URL off to an existing Edge profile process group and the spawned child dies milliseconds after creation. We ignore any exit inside the first 5s.
+2. **Deferred multi-client check (12s)** — after a real close, wait 12s and check if any heartbeat arrived AFTER the close timestamp. If yes, a hosted-frontend tab (or another window) is keeping us busy, stay alive. If no, gracefulShutdown.
+
+Frontend heartbeat cadence is 10s (in `main.js`), so one full cycle
+fits inside the 12s decision window.
+
+Environment overrides:
+- `CCSM_KEEP_ALIVE=1` → disable both browser-exit hook and heartbeat watchdog. For automation hosts.
+- `CCSM_LAUNCHER=1` → set by `bin/ccsm.js` when it spawns the server; enables the heartbeat watchdog.
+- `CCSM_NO_BROWSER=1` → set by the launcher when handling a `ccsm://` click or by `/api/upgrade` self-respawn; suppresses the server's auto-open browser.
+- `CCSM_NO_DEV=1` → suppress dev-mode features (static serving, hot-reload SSE) even when running from a checkout.
+
+## Sessions: persisted, adopted, resumed
+
+There's **one source of truth**: `~/.ccsm/sessions.json`, managed by
+`lib/persistedSessions.js`. Every session ccsm starts goes in there
+with `{ id, cliId, cwd, workspace, title, folderId, repos,
+cliSessionId, status, … }`. We don't enumerate `~/.claude/` or walk
+process trees anymore.
+
+**`cliSessionId` pre-assignment.** Every built-in CLI (claude, codex,
+copilot) gets a UUID generated by `crypto.randomUUID()` at spawn time
+and stamped into the persistedSessions record up front. How the UUID
+makes it into the CLI's own state depends on what the CLI exposes:
+
+- **claude / copilot** — pass it via `--session-id <uuid>` (their
+  `newSessionIdArgs` template). The CLI creates its transcript file
+  under that exact UUID.
+- **codex** — no equivalent flag exists. Instead, `lib/codexSeed.js`
+  writes a fake rollout file at
+  `~/.codex/sessions/YYYY/MM/DD/rollout-<ts>-<uuid>.jsonl` containing
+  one `session_meta` line carrying the chosen id + spawn cwd, then we
+  spawn `codex resume <uuid>` so the first launch *is* a resume
+  against our seed. Codex appends real events to the same file from
+  there.
+
+Either way, no polling, no race, no 5-minute timeout. **Resume** uses
+the CLI's `resumeIdArgs` template (`['--resume', '<id>']` for
+claude/copilot, `['resume', '<id>']` for codex) to reattach precisely.
+There is no fallback path — every ccsm-launched session has a captured
+upstream id, so resume by id always applies. User-added "other" CLIs
+must configure `newSessionIdArgs` + `resumeIdArgs` (or accept that
+resume won't work).
+
+For `adopt`-imported sessions the record is born with `cliSessionId`
+already set (from disk scan), so resume uses `resumeIdArgs` directly.
+
+**Adopt.** "Import existing session" on the Launch page lists
+sessions found on disk (`/api/cli-sessions/:type`) and lets the user
+add one to ccsm with `/api/sessions/adopt`. The created record is
+born `status: 'exited'` with `cliSessionId` pre-set. Clicking it in
+the sidebar runs the normal resume flow — which uses the captured id.
+
+**Auto-resume.** SessionsPage doesn't show a "Resume" button. On
+mount, if the active session's status isn't `running`, it calls
+`resumeSession()`. `resumeSession()` in `api.js` keeps a per-id
+in-flight Map so the same call from Sidebar.onClick and the
+SessionsPage effect collapse into a single backend hit.
+
+## Layout
+
+```
+ccsm/
+├── server.js                     # Express + WebSocket; API-only in prod
+├── bin/ccsm.js                   # launcher · detach, wake-on-protocol,
+│                                 # auto-upgrade-restart, first-run hint
+├── scripts/
+│   ├── install.js                # postinstall · ccsm:// + launcher.vbs
+│   └── uninstall.js              # preuninstall · cleanup + /api/shutdown
+├── lib/
+│   ├── persistedSessions.js      # ~/.ccsm/sessions.json — source of truth
+│   ├── folders.js                # ~/.ccsm/folders.json — sidebar tree
+│   ├── localCliSessions.js       # scan ~/.claude · ~/.codex · ~/.copilot
+│   ├── codexSeed.js              # seed ~/.codex/sessions/.../rollout-*.jsonl
+│   │                             #   so `codex resume <uuid>` works on launch 1
+│   ├── workspace.js              # ws-N allocation under workDir, repo clones
+│   ├── webTerminal.js            # in-process PTY pool · node-pty + WebSocket
+│   ├── jsonStore.js              # shared keyed-JSON store factory
+│   └── config.js                 # loadConfig / saveConfig + DATA_DIR
+├── pages-root/                   # pushed to GH Pages /
+│   ├── index.html                # version router · probe localhost, redirect
+│   ├── manifest.webmanifest      # PWA · stable id, start_url: ./
+│   └── favicon.svg
+└── public/                       # pushed to GH Pages /<version>/
+    ├── index.html                # workflow injects <meta ccsm-frontend-version>
+    ├── manifest.webmanifest      # per-version (links back to root scope)
+    ├── favicon.svg
+    ├── js/
+    │   ├── backend.js            # httpBase() / wsBase() — same-origin local, cross-origin hosted
+    │   ├── main.js               # boot · version guard · clock · heartbeat
+    │   ├── state.js              # signals
+    │   ├── api.js                # fetch wrapper + loaders + dedup-aware resumeSession
+    │   ├── streaming.js          # NDJSON clone-progress stream
+    │   ├── dialog.js · toast.js  # ccsmConfirm / ccsmPrompt / setToast
+    │   ├── html.js · icons.js · util.js
+    │   ├── components/
+    │   │   ├── App.js · Sidebar.js · PageTitleBar.js
+    │   │   ├── ServerStatus.js · Toast.js · OfflineBanner.js · DialogHost.js
+    │   │   ├── Card.js · Modal.js · Popover.js · Picker.js · EntityFormModal.js
+    │   │   ├── DirectoryPicker.js · AdoptModal.js
+    │   │   ├── ProgressList.js · TerminalView.js · useDragSort.js
+    │   └── pages/
+    │       ├── SessionsPage.js · LaunchPage.js
+    │       ├── ConfigurePage.js · AboutPage.js
+    └── css/                      # 12 focused stylesheets
+        ├── tokens.css · base.css · layout.css
+        ├── sidebar.css · cards.css · forms.css
+        ├── widgets.css · feedback.css · modal.css
+        ├── terminals.css · wco.css · responsive.css
+
+~/.ccsm/                          # or $CCSM_HOME
+├── config.json                   # source of truth
+├── sessions.json                 # persisted sessions (id, cliSessionId, …)
+├── folders.json                  # folder tree
+├── server.log                    # detached-server stdout/stderr
+├── .first-run-shown              # marker so launcher only prints PWA hint once
+└── browser-profile/              # Edge/Chrome --user-data-dir when browserMode=app
+
+%LOCALAPPDATA%/ccsm/
+└── launcher.vbs                  # silent ccsm:// dispatcher (written by postinstall)
+
+HKCU\Software\Classes\ccsm        # URL protocol registration
+```
+
+On first run, if a legacy `<repo>/data/` directory exists and `~/.ccsm/`
+is empty, `lib/config.js` copies the old data over (one-time,
+idempotent).
+
+## Locked-in design decisions
+
+**Single in-app terminal, no `wt`.** PTYs run in-process via node-pty
+and stream to xterm.js over `/ws/terminal/:id`. We dropped the
+`wt`-per-session, focus-by-HWND, snapshot-of-live-claudes layer
+entirely — too platform-specific and the web terminal handles
+everything the old path did.
+
+**Workspace = folder holding multiple repo clones.** Each `ws-N` under
+`workDir` contains a subdirectory per cloned repo. CLIs launch at the
+workspace root so all selected repos are sibling folders.
+
+**Workspace naming.** Auto-allocated names are `ws-1`, `ws-2`, …
+(lowest free integer). Hand-named folders under `workDir` are still
+picked up.
+
+**Frontend trusts the backend's capability advertisement.**
+`/api/capabilities` returns `{ webTerminal: true|false, ... }`. The
+frontend uses ONLY features the backend says it has. Breaking changes
+ship a new `/ccsm/<X.Y.Z>/` frontend; the router pins users to the
+matching version.
+
+**One source of truth for cross-origin.** `public/js/backend.js`
+exports `httpBase()` and `wsBase()`. Localhost → same-origin (empty
+base). Anything else → `http://localhost:7777`. CORS on the backend
+allows `https://bakapiano.github.io` only — never `*`.
+
+## API surface
+
+| Method | Path | Purpose |
+|---|---|---|
+| GET / PUT | `/api/config` | read / replace config |
+| GET | `/api/sessions` | list persisted sessions |
+| PUT | `/api/sessions/:id` | rename / move to folder |
+| DELETE | `/api/sessions/:id` | kill PTY + drop record |
+| POST | `/api/sessions/new` | body `{cliId, cwd?, repos?, folderId?, title?}` — NDJSON stream (workspace · clone-progress · launched) |
+| POST | `/api/sessions/:id/resume` | re-spawn at `cwd` with `cli.resumeIdArgs <id>` (fallback `resumeArgs`) |
+| GET | `/api/cli-sessions/:type` | scan disk for unimported `claude`/`codex`/`copilot` sessions |
+| POST | `/api/sessions/adopt` | body `{cliId, cliSessionId, cwd, title?, folderId?}` — create a `status:exited` record with `cliSessionId` pre-set |
+| GET | `/api/folders` · POST `/api/folders` · PUT/DELETE `/api/folders/:id` · POST `/api/folders/reorder` | folder CRUD |
+| GET | `/api/workspaces` | workspaces under workDir with repo clone status + in-use flag |
+| GET | `/api/browse` | directory browser for the Launch page workdir picker |
+| GET | `/api/version` | `{ current, latest, updateAvailable, fetchedAt, cached, error? }` (npm registry cached 30 min, `?refresh=1` to bust) |
+| POST | `/api/upgrade` | body `{target?}` — `npm i -g @bakapiano/ccsm@<target>` then self-restart |
+| GET | `/api/capabilities` | `{ webTerminal: bool, ... }` for frontend feature gating |
+| GET | `/api/health` | `{ ok, pid, version, name }` — used by router probe + heartbeat |
+| POST | `/api/heartbeat` | called every 10s by the frontend; feeds lifecycle decisions |
+| POST | `/api/spawn-browser` | open another browser window into the running server (used by `bin/ccsm.js` for auto-upgrade-restart) |
+| POST | `/api/shutdown` | gracefulShutdown — used by uninstall + auto-upgrade |
+| WS | `/ws/terminal/:id` | xterm.js bridge to a PTY in the webTerminal pool |
+| GET (dev) | `/api/dev/ping` · `/api/dev/reload` | hot-reload SSE (only when running from a checkout) |
+
+`/api/sessions/new` streams **NDJSON** (one JSON object per line). Event
+types: `workspace`, `clone-start`, `clone-progress` (phase/percent/
+current/total/detail), `clone-line` (raw git stderr line when not a
+progress line), `clone-end`, `launched`, `done`. The frontend reads it
+with `fetch().body.getReader()` + `TextDecoder` and updates per-repo
+progress bars live.
+
+**WebSocket Origin check**: same allow-list as CORS. The upgrade handler
+rejects any Origin not in `ALLOWED_ORIGINS` (plus localhost/127.0.0.1).
+Browsers always send Origin on WS upgrades.
+
+## Non-obvious gotchas
+
+**Pre-assigned UUID needs either a flag OR a writable transcript dir.**
+`newSessionIdArgs` works two ways: native flag (claude, copilot via
+`--session-id`) or seeded transcript file (codex via `resume <id>` +
+`lib/codexSeed.js`). User-added "other" CLIs without either get no
+pre-assignment and fall back to `resumeArgs` (`--continue` / equivalent)
+on relaunch — they just won't have a captured upstream id.
+
+**Adopt is atomic.** `persistedSessions.create()` accepts `status` +
+`cliSessionId` so the adopt endpoint writes the record in a single
+file write rather than `create({running})` + `update({exited,
+cliSessionId})`. The two-write form had a window where a concurrent
+GET /api/sessions could see `running` with no live PTY, fooling the
+sidebar's "skip resume if running" guard.
+
+**Auto-resume dedup is module-level in api.js.** Sidebar.onClick and
+SessionsPage's effect can both fire for the same exited session in the
+same tick. `resumeSession()` keeps a per-id in-flight `Map` so the
+second caller awaits the first one's promise instead of issuing a
+second `/resume`.
+
+**Heartbeat watchdog only when launched.** Set via `CCSM_LAUNCHER=1` by
+`bin/ccsm.js`. If you start `server.js` directly (e.g. dev), the
+90-second timeout doesn't apply — convenient when stepping through
+code, but you have to ctrl-c yourself when done.
+
+**ccsm:// silent dispatch.** Direct registration of `ccsm.cmd` as the
+protocol handler causes a brief console window flash (cmd hosts the
+.cmd file). The wscript.exe + .vbs wrapper avoids it entirely — wscript
+is a Windows-subsystem host (no console) and `Shell.Run(..., 0, False)`
+launches the target hidden. The `.vbs` is generated at install time
+with the correct ccsm.cmd path baked in.
+
+**Edge --app handoff race.** When the user has an existing Edge profile
+process running, `--app=URL --user-data-dir=DIR` against the same DIR
+may cause the new msedge.exe to immediately exit after handing the URL
+off to the existing process. Our child handle dies milliseconds after
+spawn. The lifecycle hook ignores any browser-child exit inside the
+first 5s for exactly this reason.
+
+## Frontend design language
+
+The UI deliberately copies **claude.ai's** calm light aesthetic — warm
+cream surfaces, generous spacing, soft borders, **no orange highlights**.
+The brand orange `#b3614a` survives only in the brand mark / wordmark
+dot. Every other "highlight" use (selection, focus rings, dirty
+indicators, progress bars, page-actions banner) is ink/gray.
+
+**Palette** (CSS vars in `public/css/tokens.css`):
+- `--bg`            `#faf9f5`  warm cream page background
+- `--bg-elev`       `#ffffff`  card surfaces
+- `--sidebar-bg`    `#faf9f5`  (same as `--bg`, single continuous surface)
+- `--border`        `#e8e3d5`
+- `--ink`           `#1a1815`  body text (warm near-black, also used for terminal background)
+- `--ink-mid` / `--ink-muted` / `--ink-faint`
+- `--accent`        `#b3614a`  desaturated terracotta — brand only
+- Status: green `#4a8a4a` idle · blue `#4a73a5` busy (pulsing) · red `#b73f3f` danger
+
+**Type**:
+- Body / headings: **Geist** (Google Fonts, 300–700).
+- Mono: **JetBrains Mono** for paths, PIDs, sessionIds, branch tags.
+- Always `font-variant-numeric: tabular-nums` on numeric cells.
+
+**Buttons**:
+- `.action` (default) — white bg, ink-mid border, ink text.
+- `.action.primary` — black ink bg, white text. The "do this" CTA.
+- `.action.subtle` — transparent bg, light border.
+- `.action.danger` — filled red bg + white text.
+
+**Layout**:
+- Sidebar (collapsible, ~232px ↔ ~60px, state in `localStorage["ccsm.sidebar-collapsed"]`)
+  - brand mark + `CCSM.` wordmark
+  - tabs: Sessions / Launch / Configure / About
+  - folder tree of persisted sessions (drag-sortable)
+- Page-title bar: title on the left, server-status pill + Refresh button on the right
+- Top-right control group uses fixed `min-height: 28px` and `border-radius: 999px` so server-status + Refresh align as a coherent control row
+
+**No emoji in the UI** unless the user typed it. Use inline SVG icons
+everywhere (line stroke, 1.5–2px) so they take `currentColor`.
+
+**PWA + WCO**:
+- `display_override: ["window-controls-overlay", "standalone"]` in the manifest. When installed and launched as PWA, the title bar's middle is reclaimed; only OS controls float top-right.
+- `public/css/wco.css` provides drag regions (`-webkit-app-region: drag`) on `.sidebar-brand`, `.page-head`, etc., unconditional. Interactive elements opt out via the no-drag block.
+- The root PWA manifest at `pages-root/manifest.webmanifest` has stable `id: /ccsm/` so installs survive across version-router redirects to new `/ccsm/<X.Y.Z>/` subdirs.
+
+## Versioning
+
+The hosted frontend lives at `https://bakapiano.github.io/ccsm/`. The
+deploy workflow publishes two things to gh-pages on every push to main:
+
+1. `pages-root/` → `/` (the router, plus root PWA manifest)
+2. `public/` → `/<pkg.version>/` (the per-version frontend; workflow injects `<meta name="ccsm-frontend-version">` at build time)
+
+Old version dirs stay forever (`keep_files: true`), so a user on an
+older backend keeps loading the matching frontend until they upgrade.
+
+`bin/ccsm.js` does auto-upgrade-restart: when the user runs `ccsm` and
+the installed package version differs from a running backend, it POSTs
+`/api/shutdown` to the old, waits for the port to free, then spawns a
+fresh server. So `npm i -g @bakapiano/ccsm@latest && ccsm` is one
+seamless step. From the frontend, the About page's Upgrade button
+achieves the same thing without leaving the browser.
+
+## Cross-platform
+
+Today: Windows-first.
+
+Cross-platform-clean already:
+- Frontend (pure web)
+- Router page (pure HTML/JS)
+- `bin/ccsm.js` (pure node)
+- `lib/webTerminal.js` (node-pty handles platform)
+- `lib/persistedSessions.js`, `lib/folders.js`, `lib/config.js`, `lib/jsonStore.js`, `lib/localCliSessions.js`, `lib/workspace.js` (fs only)
+- `server.js` Express + ws
+
+Windows-specific (need ports for Mac/Linux):
+- `scripts/install.js` — uses `reg.exe` and `wscript.exe`. Mac: write `Info.plist` with `CFBundleURLTypes`. Linux: write `~/.local/share/applications/ccsm.desktop` with `MimeType=x-scheme-handler/ccsm`.
+- The `--app=` browser detection and PATH-merge in `server.js` are Windows-shaped (Edge first, registry HKCU\Environment for PATH).
+
+Pattern for adding a platform: `switch (process.platform)` at each
+entry point in those files. Each platform branch is roughly 50-100
+lines.
+
+## Extending
+
+When adding features, the natural extension points:
+- **New REST routes**: `server.js` (keep under `/api/*`, use the `asyncH` wrapper, decide if it needs CORS by being in the allow-list).
+- **Frontend page**: `public/js/pages/<Name>Page.js`, route in `App.js`, sidebar nav item in `Sidebar.js`, heading in `state.js`'s `TAB_HEADINGS`.
+- **Persistent user data**: drop a JSON file under `~/.ccsm/` and use `lib/jsonStore.js`'s factory.
+- **Different CLIs**: add a built-in to `DEFAULT_CLIS` in `lib/config.js` (set `newSessionIdArgs` if the CLI accepts a pre-assigned UUID, `resumeIdArgs` for precise resume), an icon to `public/js/icons.js`, and (if the CLI persists transcripts on disk and you want adopt support) a list helper to `lib/localCliSessions.js`.
+- **A capability**: advertise via `/api/capabilities`. Frontend gates UI on `caps.<feature>`.
+- **Bumping the frontend**: just `npm version <patch|minor|major>` + push. The GH Pages workflow publishes to `/<new-version>/` and the router redirects users to it.