refactor: SSE event handlers, LLM context optimization, @fileoverview docs (#29)

* refactor: extract SSE event handlers into named class methods

Replace ~80 inline addListener closures in connectSSE() with a
declarative _SSE_HANDLER_MAP array that drives registration in a
single loop. Each handler is now a named _on* method on CodemanApp,
making them individually addressable for LLM navigation.

Add SSE_EVENTS constant object in constants.js to eliminate magic
event-type strings scattered across the frontend.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* docs: fix inaccuracies in CLAUDE.md

- Fix types barrel path: src/types.ts → src/types/index.ts
- Update app.js line count: ~12K → ~11.5K
- Correct route handler counts (113 → 111, per-group fixes)
- Add code style, ESM gotcha, env vars, route test, lifecycle log docs
- Add Node 22 CI note, test teardown timeout, port range

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* docs: add mobile screenshots and QR auth security writeup to README

Add 3 mobile screenshots (landing, idle, active) and expand the
mobile section with QR auth security design details and a
touch-optimized interface subsection.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* feat: bundle xterm-zerolag-input as vendor IIFE and add pre-commit hook

Build and postinstall now bundle the local xterm-zerolag-input package
as an IIFE at vendor/xterm-zerolag-input.js with global LocalEchoOverlay
shim. Add git pre-commit hook that runs prettier --check on staged .ts
files to catch format issues before CI.

Also bump constants.js and app.js cache-bust versions to 0.3.0 and add
tunnel upload URL display row in settings.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* feat: add cloudflared install support and interactive launch menu

- Add optional cloudflared dependency detection and installation
  across 6 distro families (macOS, Debian, Fedora, Arch, Alpine, SUSE)
- Add tunnel systemd service setup helper
- Replace post-install instructions with interactive launch menu
  (run now / systemd service / skip)
- Uninstall now cleans up both codeman-web and codeman-tunnel services

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* chore: gitignore readme-preview.mjs

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* refactor: WIP — SSE event constants, @fileoverview docs, CLAUDE.md compression

- Migrate broadcast() string literals → SseEvent.* typed constants
- Add @fileoverview with cross-domain references to all 13 type domain files
- Add @fileoverview to frontend JS modules (constants, mobile, voice, etc.)
- Add section dividers to route files for LLM scanability
- Compress CLAUDE.md: flat file list → domain table, fix counts

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* refactor: optimize codebase for LLM context window efficiency

CLAUDE.md: 456 → 309 lines (32% reduction)
- Merge Commands into compact table, remove redundant bash block
- Convert Security section to dense table format
- Merge Performance + Resource Limits, Debugging + Troubleshooting
- Compress Tunnel, Memory Leak, Scripts, Screenshots sections
- Remove Key Patterns that duplicate @fileoverview in source files

Backend @fileoverview enhancements (10 priority files):
- session.ts: key methods, events, cross-domain refs
- respawn-controller.ts: state machine, idle detection layers
- ralph-tracker.ts: exports, circuit breaker, events
- ralph-loop.ts: lifecycle, persistence, events
- subagent-watcher.ts: watched patterns, teammate detection
- server.ts: coordination list, port interfaces
- state-store.ts: dual-file persistence, migration
- session-manager.ts: lifecycle methods, mutex guard
- hooks-config.ts: hook events list, categories
- sse-events.ts: category breakdown (~90 events, 17 categories)

Frontend app.js: add 6 section dividers, update @fileoverview line refs

Fix: escape glob `*/` in JSDoc that broke ESLint parser

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* fix: address PR #29 review bugs

- server.ts: replace hardcoded 'session:needsRefresh' with SseEvent constant
- install.sh: fix Alpine cloudflared install for non-root (download to tmpfile first)
- install.sh: replace Arch pacman (AUR-only) with direct binary download
- index.html: bump all 8 remaining cache-bust versions from v0.2.9 to v0.3.0
- mobile-handlers.js: fix @dependency annotation (keyboard-accessory.js, not constants.js)
- types/push.ts: fix layer number (4, not 5)
- subagent-watcher.ts: fix watched pattern path to include {session} segment
- constants.js: fix SSE_EVENTS count in @fileoverview (~73, not ~65)

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

src/web/routes/system-routes.ts

@@ -25,6 +25,7 @@ import { subagentWatcher } from '../../subagent-watcher.js';
 import { imageWatcher } from '../../image-watcher.js';
 import { getLifecycleLog } from '../../session-lifecycle-log.js';
 import { findSessionOrFail, formatUptime, SETTINGS_PATH } from '../route-helpers.js';
+import { SseEvent } from '../sse-events.js';
 import type { SessionPort, EventPort, ConfigPort, InfraPort, AuthPort } from '../ports/index.js';
 import { AUTH_COOKIE_NAME } from '../middleware/auth.js';
 import { QR_AUTH_FAILURE_MAX } from '../../config/tunnel-config.js';
@@ -91,6 +92,10 @@ export function registerSystemRoutes(
   const windowStatesPath = join(homedir(), '.codeman', 'subagent-window-states.json');
   const parentMapPath = join(homedir(), '.codeman', 'subagent-parents.json');
 
+  // ═══════════════════════════════════════════════════════════════
+  // System Status & Health
+  // ═══════════════════════════════════════════════════════════════
+
   // ========== Status ==========
 
   app.get('/api/status', async () => ctx.getLightState());
@@ -120,6 +125,10 @@ export function registerSystemRoutes(
     }
   });
 
+  // ═══════════════════════════════════════════════════════════════
+  // Authentication (QR auth, session revocation)
+  // ═══════════════════════════════════════════════════════════════
+
   // ========== QR Auth Route ==========
 
   app.get('/q/:code', async (req, reply) => {
@@ -177,7 +186,7 @@ export function registerSystemRoutes(
     });
 
     // Broadcast auth notification — desktop sees who authenticated
-    ctx.broadcast('tunnel:qrAuthUsed', {
+    ctx.broadcast(SseEvent.TunnelQrAuthUsed, {
       ip: clientIp,
       ua: clientUA,
       timestamp: Date.now(),
@@ -206,6 +215,10 @@ export function registerSystemRoutes(
     return { success: true };
   });
 
+  // ═══════════════════════════════════════════════════════════════
+  // CLI Integrations (OpenCode)
+  // ═══════════════════════════════════════════════════════════════
+
   // ========== OpenCode ==========
 
   app.get('/api/opencode/status', async () => {
@@ -216,6 +229,10 @@ export function registerSystemRoutes(
     };
   });
 
+  // ═══════════════════════════════════════════════════════════════
+  // State & Lifecycle (cleanup, lifecycle log, stats)
+  // ═══════════════════════════════════════════════════════════════
+
   // ========== State & Lifecycle ==========
 
   app.post('/api/cleanup-state', async () => {
@@ -279,6 +296,10 @@ export function registerSystemRoutes(
     };
   });
 
+  // ═══════════════════════════════════════════════════════════════
+  // Configuration & Settings (config, settings, model config, CPU priority)
+  // ═══════════════════════════════════════════════════════════════
+
   // ========== Config ==========
 
   app.get('/api/config', async () => {
@@ -424,7 +445,7 @@ export function registerSystemRoutes(
           console.log('Tunnel started via settings change');
         } else if (tunnelEnabled && ctx.tunnelManager.isRunning() && ctx.tunnelManager.getUrl()) {
           // Tunnel already running — re-emit so the client gets the URL
-          ctx.broadcast('tunnel:started', { url: ctx.tunnelManager.getUrl() });
+          ctx.broadcast(SseEvent.TunnelStarted, { url: ctx.tunnelManager.getUrl() });
           console.log('Tunnel already running, re-broadcast URL to client');
         } else if (!tunnelEnabled && ctx.tunnelManager.isRunning()) {
           ctx.tunnelManager.stop();
@@ -506,7 +527,7 @@ export function registerSystemRoutes(
 
     session.setNice(body);
     ctx.persistSessionState(session);
-    ctx.broadcast('session:updated', { session: ctx.getSessionStateWithRespawn(session) });
+    ctx.broadcast(SseEvent.SessionUpdated, { session: ctx.getSessionStateWithRespawn(session) });
 
     return {
       success: true,
@@ -515,6 +536,10 @@ export function registerSystemRoutes(
     };
   });
 
+  // ═══════════════════════════════════════════════════════════════
+  // Subagent Management (window states, parents, monitoring, transcripts)
+  // ═══════════════════════════════════════════════════════════════
+
   // ========== Subagent Window State Persistence ==========
 
   app.get('/api/subagent-window-states', async () => {
@@ -643,6 +668,10 @@ export function registerSystemRoutes(
     return { success: true, data: { cleared } };
   });
 
+  // ═══════════════════════════════════════════════════════════════
+  // Screenshots (upload, list, serve)
+  // ═══════════════════════════════════════════════════════════════
+
   // ========== Screenshots ==========
 
   app.post('/api/screenshots', async (req, reply) => {