diff --git a/CLAUDE.md b/CLAUDE.md
index 8c279f16..cbad63ad 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -109,7 +109,7 @@ Codeman is a Claude Code session manager with web interface and autonomous Ralph
| **Infra** | `src/hooks-config.ts`, `src/push-store.ts`, `src/tunnel-manager.ts`, `src/image-watcher.ts`, `src/file-stream-manager.ts` | |
| **Plan** | `src/plan-orchestrator.ts`, `src/prompts/*.ts`, `src/templates/claude-md.ts` | |
| **Web** | `src/web/server.ts`, `src/web/sse-events.ts`, `src/web/routes/*.ts` (13 route modules incl. `ws-routes.ts` + barrel), `src/web/ports/*.ts`, `src/web/middleware/auth.ts`, `src/web/schemas.ts` | |
-| **Frontend** | `src/web/public/app.js` ★ (~12.5K lines) + 10 JS modules (incl. `sw.js`, `input-cjk.js`) | |
+| **Frontend** | `src/web/public/app.js` ★ (~12.5K lines) + 11 JS modules (incl. `sw.js`, `input-cjk.js`) | |
| **Types** | `src/types/index.ts` → 13 domain files | See `@fileoverview` in index.ts |
★ = Large file (>50KB). All files have `@fileoverview` JSDoc — read that before diving in.
diff --git a/docs/performance-plan.md b/docs/performance-plan.md
new file mode 100644
index 00000000..fd2806d9
--- /dev/null
+++ b/docs/performance-plan.md
@@ -0,0 +1,74 @@
+# Codeman Performance Optimization Plan
+
+## Current State
+
+The backend is **already production-grade** — SSE broadcasting, state persistence, terminal batching, buffer management, and memory patterns are all well-optimized. The biggest gains are on the **frontend delivery** side.
+
+## Implemented Optimizations
+
+### 1. V8 Compile Cache (10-20% faster cold start)
+
+**Files:** `scripts/codeman-web.service`, `package.json`
+
+Node.js re-parses and compiles all JS on every cold start. `NODE_COMPILE_CACHE` caches V8 compiled bytecode to disk, reusing it on subsequent starts.
+
+- Added `Environment=NODE_COMPILE_CACHE=/home/arkon/.codeman/compile-cache` to systemd service
+- Added to `npm start` script for non-systemd usage
+- Zero code changes, immediate win on every restart
+
+### 2. WebGL Addon Lazy-Loading (244KB saved on mobile, non-blocking on desktop)
+
+**Files:** `src/web/public/index.html`, `src/web/public/app.js`
+
+`xterm-addon-webgl.min.js` (244KB) was loaded eagerly for all users via `
-
+