@slycode/slycode 0.1.18 → 0.2.0

package/dist/store/.backups/context-priming/references/areas/messaging.md

@@ -1,177 +0,0 @@
-# Messaging Service
-
-Updated: 2026-02-14
-
-## Overview
-
-Multi-channel messaging service for remote AI interaction via Telegram (and future channels). Supports text and voice messages, project selection, voice swapping, response mode/tone preferences, multi-provider support (Claude/Gemini/Codex), stop command for session interruption, permission mismatch detection, context-aware command filtering, and two-way communication with AI sessions through the terminal bridge. Runs as a standalone Node/Express service with a CLI for outbound messages.
-
-## Key Files
-
-### Service Core
-- `messaging/src/index.ts` - Main entry, channel wiring, HTTP server, bot commands, stop interception
-- `messaging/src/types.ts` - Channel interface, configs, bridge types, ResponseMode
-- `messaging/src/state.ts` - StateManager: project selection, voice state, response mode, voice tone, provider selection, persistence
-- `messaging/src/bridge-client.ts` - BridgeClient: session management, provider-aware creation, permission mismatch detection, activity watching, soft stop
-
-### Channels
-- `messaging/src/channels/telegram.ts` - TelegramChannel: bot polling, inline buttons, chat actions
-
-### Voice Pipeline
-- `messaging/src/stt.ts` - Whisper STT via OpenAI API
-- `messaging/src/tts.ts` - ElevenLabs v3 TTS with audio tag support, optional voice override
-- `messaging/src/voices.ts` - Voice search across personal + community library (v2 + v1 APIs)
-
-### Command System
-- `messaging/src/command-filter.ts` - Context-aware command filtering by terminal class, session state, card type
-- `messaging/src/kanban-client.ts` - Direct access to project kanban boards for card metadata
-
-### CLI & Skill
-- `messaging/src/cli.ts` - CLI tool for sending text/voice from Claude skills
-- `.claude/skills/messaging/SKILL.md` - Skill definition (v2.2.0) with mode/tone system and audio tags
-
-### Config
-- `messaging/package.json` - Dependencies: node-telegram-bot-api, openai, express, dotenv
-- `messaging/tsconfig.json` - TypeScript config (ESM, ES2022)
-- `.env` - Runtime config (tokens, API keys, ports)
-
-## Channel Interface
-
-```typescript
-Channel {
-  name: string;
-  start(): Promise<void>;
-  stop(): void;
-  onText(handler): void;
-  onVoice(handler): void;
-  onCommand(command, handler): void;
-  onProjectSelect(handler): void;
-  sendText(text): Promise<void>;        // With Markdown
-  sendTextRaw(text): Promise<void>;     // Without Markdown (preserves [brackets])
-  sendVoice(audio: Buffer): Promise<void>;
-  sendProjectList(projects): Promise<void>;
-  sendTyping(): Promise<void>;
-  sendChatAction(action): Promise<void>;
-  sendVoiceList?(voices): Promise<void>;     // Optional
-  onVoiceSelect?(handler): void;              // Optional
-  isReady(): boolean;
-}
-```
-
-## Bot Commands
-
-- `/start` - Help text with available commands
-- `/projects` - Inline keyboard for project selection
-- `/select N` - Select project by number
-- `/status` - Current project, voice, response mode, and tone
-- `/voice` - Search/swap TTS voices, reset to default
-- `/voice <name>` - Search voices, auto-select on exact match, inline buttons for multiple
-
-## Message Flow
-
-### Inbound (user → Claude)
-1. User sends text/voice on Telegram
-2. **Stop interception**: "stop" text (case-insensitive) sends Escape to active session instead of forwarding
-3. TelegramChannel routes to handler in index.ts
-4. Voice: `record_voice` chat action → Whisper transcription → typing indicator
-5. BridgeClient.ensureSession() creates/finds session (with selected provider, always skipPermissions)
-6. If permission mismatch (existing session without skipPermissions), warns user and offers restart
-7. BridgeClient.sendMessage() writes text + CR to PTY
-8. BridgeClient.watchActivity() polls /stats, sends typing while active
-
-### Outbound (Claude → user)
-1. Claude skill calls CLI: `tsx cli.ts send "message" [--tts]`
-2. CLI POSTs to HTTP server `/send` or `/voice`
-3. `/send` → channel.sendText()
-4. `/voice` → `upload_voice` chat action → TTS generation → channel.sendVoice() + sendTextRaw()
-
-### Stop Command
-1. User sends "stop" (exact, case-insensitive)
-2. BridgeClient.stopSession() calls `POST /sessions/:name/stop` (sends Escape key)
-3. Returns feedback: "Interrupted active session" or "Already stopped"
-4. Message NOT forwarded as a prompt
-
-## Response Mode System
-
-- **Mode**: `text` | `voice` | `both` - determines response format
-  - `text` - Text replies only (default)
-  - `voice` - Voice messages with text companion
-  - `both` - Both voice and text responses
-- **Tone**: Free-text description of voice style and length
-- Mode shown in message footer: `(Reply using /messaging | Mode: text)`
-- Persisted in messaging-state.json
-
-## Command Filtering
-
-- `CommandFilter.loadCommands()` - Hot-reloads commands.json on each call
-- `CommandFilter.filterCommands(terminalClass, sessionState, cardType?)` - Context-aware filtering
-- `CommandFilter.resolveTemplate(prompt, context)` - Template variable resolution
-- `CommandFilter.getTerminalClass(target)` - Maps navigation target to terminal class
-- Supports card context from KanbanClient for prompt templates
-
-## Kanban Client
-
-- `KanbanClient.getBoard(projectId)` - Load project's kanban board
-- `KanbanClient.getCard(projectId, cardId)` - Find card with its stage
-- `KanbanClient.getCardsByStage(projectId, stage)` - Cards in a stage
-- Resolves kanban.json paths per project
-
-## Voice System
-
-- **STT**: OpenAI Whisper (`whisper-1`), accepts OGG from Telegram
-- **TTS**: ElevenLabs v3 (`eleven_v3`), supports `[tag]` audio tags
-- **Voice selection**: Persisted in messaging-state.json, overrides .env default
-- **Voice search**: Queries both `/v2/voices` (personal) and `/v1/shared-voices` (community), deduplicates
-- **Conversion**: ffmpeg MP3→OGG/Opus for Telegram compatibility
-
-## Provider Support
-
-- `StateManager.selectedProvider` - Persisted provider choice (default: 'claude')
-- Session names include provider segment: `{projectId}:{provider}:global`
-- `getLegacySessionName()` provides backward-compat format for existing session lookups
-- Messaging always forces `skipPermissions: true` (remote interaction can't approve prompts)
-- `BridgeClient.ensureSession()` returns `{ session, permissionMismatch? }` — detects sessions started from web UI without skip-permissions
-- `BridgeClient.restartSession()` stops old session and creates fresh one with correct provider + skip-permissions
-
-## State Persistence
-
-`messaging-state.json` stores:
-- `selectedProjectId` - Active project
-- `selectedProvider` - Active AI provider (claude/gemini/codex)
-- `voiceId` / `voiceName` - Selected TTS voice (null = use .env default)
-- `responseMode` - text/voice/both preference
-- `voiceTone` - Free-text tone description
-
-Projects loaded from `projects/registry.json` at startup.
-
-## HTTP Endpoints
-
-- `POST /send` - Send text message to active channel
-- `POST /voice` - Generate TTS and send voice + text to channel
-- `GET /health` - Service health check (channel name, ready state)
-
-## Patterns & Invariants
-
-- Chat actions for status: `record_voice` (transcribing), `typing` (processing), `upload_voice` (TTS)
-- Session names include provider: `{projectId}:{provider}:global` (with legacy fallback)
-- Messages include channel header: `[Telegram] text (Reply using /messaging | Mode: text)`
-- Voice messages: `[Telegram/Voice] transcription (Reply using /messaging | Mode: text)`
-- sendTextRaw used for voice text companions (preserves [audio tags]) and voice IDs
-- Authorization: single authorized user ID per Telegram bot
-- Telegram message limit: 4096 chars, auto-split at newline boundaries
-- "stop" text intercepted before forwarding to session (soft stop via Escape key)
-- Card titles truncated to 35 chars in breadcrumb rendering
-
-## When to Expand
-
-- Adding new channel → implement Channel interface, add to createChannel() in index.ts
-- Voice issues → tts.ts (generation), voices.ts (search), stt.ts (transcription)
-- Bot command issues → index.ts setupChannel()
-- Bridge routing → bridge-client.ts
-- State persistence → state.ts
-- Telegram-specific behavior → channels/telegram.ts
-- Command filtering → command-filter.ts, kanban-client.ts
-- Stop command → bridge-client.ts stopSession(), index.ts stop interception
-- Response modes → state.ts, SKILL.md mode/tone guidelines
-- Provider selection → state.ts (selectedProvider), bridge-client.ts (ensureSession provider param)
-- Permission mismatch → bridge-client.ts ensureSession/sendMessage permissionMismatch detection

package/dist/store/.backups/context-priming/references/areas/scripts-deployment.md

@@ -1,138 +0,0 @@
-# Scripts & Deployment
-
-Updated: 2026-02-11
-
-## Overview
-
-SlyCode has a two-tier deployment model: **dev** (individual services via tmux) and **prod** (background processes with builds). All scripts live in `scripts/`. A guided installer (`setup.sh`) handles first-time and repeat setup. No hardcoded paths — everything is derived at runtime.
-
-## Scripts
-
-| Script | Purpose |
-|--------|---------|
-| `setup.sh` | Interactive guided installer — deps, builds, CLI symlinks, optional services, linger |
-| `sly-start.sh` | Build all services then start in production (background processes or systemd/launchd) |
-| `sly-stop.sh` | Stop production services by finding processes on their ports |
-| `sly-restart.sh` | Stop then start (delegates to sly-stop + sly-start) |
-| `sly-dev.sh` | Tmux session "sly" with three side-by-side panes running `npm run dev` |
-| `kanban.js` | Kanban CLI (standalone Node.js, no build needed) |
-| `scaffold.js` | Project scaffolding CLI (standalone Node.js) |
-
-## Port Architecture
-
-Two separate port ranges — dev and prod never overlap:
-
-| Service | Dev port | Prod port | Env var |
-|---------|----------|-----------|---------|
-| Web | 3003 | 7591 | `WEB_PORT` |
-| Bridge | 3004 | 7592 | `BRIDGE_PORT` |
-| Messaging | 3005 | 7593 | `MESSAGING_SERVICE_PORT` |
-
-- **7591/2/3**: "sly" = 759 on a phone keypad
-- **Dev ports**: hardcoded in each service's `package.json` dev scripts
-- **Prod ports**: configured in `.env`, read by `sly-start.sh`, passed as `PORT` env var to `npm start`
-- `BRIDGE_URL` must match bridge port — `sly-start.sh` derives it automatically
-- Next.js reads `PORT` env var natively (no `--port` flag in prod `npm start`)
-
-## Process Management
-
-### Production (`sly-start.sh` / `sly-stop.sh`)
-
-- **Start**: runs `npm start` in background with `nohup` (assumes services are already built via `setup.sh`)
-- **Stop**: finds PIDs by port (not PID files — those are unreliable with npm subshells), kills process tree with `pkill -P` + `kill`
-- Ports file at `~/.slycode/ports` records which ports were started for stop to read
-- Health check after start: verifies each port is listening
-- Log files: `~/.slycode/logs/{web,bridge,messaging}.log` with 10MB rotation
-
-### Dev (`sly-dev.sh`)
-
-- Creates tmux session "sly" with three horizontal panes
-- Each pane runs `npm run dev` in its service directory
-- `session-closed` hook calls `sly-stop.sh` to prevent zombie processes
-- If session already exists, just attaches
-- Switch panes: `Ctrl-b` + arrows. Zoom: `Ctrl-b z`
-
-### Platform Services (optional, via `setup.sh`)
-
-- **Linux**: systemd user services (`~/.config/systemd/user/slycode-{web,bridge,messaging}.service`)
-- **macOS**: launchd user agents (`~/Library/LaunchAgents/com.slycode.{web,bridge,messaging}.plist`)
-- `sly-start.sh` / `sly-stop.sh` detect installed services and use them instead of background processes
-- `setup.sh --service` installs, `setup.sh --remove-service` removes
-
-## Setup Flow (`setup.sh`)
-
-1. Welcome banner (platform, SlyCode root, Node version)
-2. Create directories (`~/bin`, `~/.slycode/logs`)
-3. `npm install` in web, bridge, messaging
-4. Build bridge, messaging, web (web last — heaviest, needs most memory)
-5. `chmod +x` on CLI scripts
-6. Symlink CLIs to `~/bin` (sly-kanban, sly-scaffold, sly-messaging)
-7. Update `registry.json` with correct SlyCode path
-8. Copy `.env.example` to `.env` if missing
-9. Prompt: install as system service?
-10. Linux: check linger, offer to enable
-
-**Flags**: `--yes` (non-interactive), `--service` (auto-install services), `--remove-service` (cleanup)
-
-## Global CLIs
-
-Symlinked to `~/bin` by `setup.sh`:
-
-| Command | Target | Type |
-|---------|--------|------|
-| `sly-kanban` | `scripts/kanban.js` | Standalone Node.js |
-| `sly-scaffold` | `scripts/scaffold.js` | Standalone Node.js |
-| `sly-messaging` | `messaging/dist/cli.js` | Built from TypeScript |
-
-### CLI Port Detection (`sly-messaging`)
-
-The CLI auto-detects which mode (dev/prod) the messaging service is running in:
-
-1. Read cached port from `~/.slycode/messaging-port` (if exists), try it first
-2. Probe dev port (3005) then prod port (7593) via `/health`
-3. Cache the successful port for next time
-
-This means `sly-messaging` works regardless of whether you started with `sly-dev.sh` or `sly-start.sh`. After the first successful call, subsequent calls skip probing entirely.
-
-## Key Design Decisions
-
-### No hardcoded paths anywhere
-- Web: `web/src/lib/paths.ts` derives SlyCode root from `process.cwd()` (detects `/web` suffix)
-- Bridge: reads `BRIDGE_PORT` from env
-- Messaging: CLI auto-detects service port (dev 3005 / prod 7593) with caching; service reads port from env
-- Skills: reference `sly-kanban` and `sly-messaging` by global command name, not paths
-- Documentation: uses `<slycode-root>` placeholder instead of absolute paths
-- `registry.json`: `setup.sh` updates the SlyCode path entry at install time
-
-### Stop by port, not PID files
-PID files are unreliable because `npm start` spawns child processes — the recorded PID is the npm wrapper which dies, leaving orphaned node/next-server children. Port-based discovery always finds the actual listening process.
-
-### Build in setup, not start
-`sly-start.sh` does NOT build — it assumes services are already built. Builds happen in `setup.sh` (which users rerun when code changes). This keeps start fast and avoids memory-heavy builds blocking service startup.
-
-### XDG_RUNTIME_DIR fix
-Code-server terminals don't set `XDG_RUNTIME_DIR`, breaking `systemctl --user`. All scripts set it to `/run/user/$(id -u)` if missing and the directory exists. Safe, standard, no side effects.
-
-### bridge-sessions.json protection
-- Path resolved via `__dirname` (never relative — avoids reading wrong file from wrong cwd)
-- Only starts fresh on ENOENT (file doesn't exist = first run)
-- Any other read error crashes loudly instead of silently wiping session data
-- Saves are atomic (write `.tmp` then `rename`)
-
-### Bridge CWD validation
-Bridge requires absolute path for session `cwd` — no defaults, no relative paths. This ensures Claude associates sessions with the correct project directory in `~/.claude/projects/`.
-
-## Env Files
-
-- **`.env.example`**: template with all config vars, prod port defaults, placeholder secrets
-- **`.env`**: actual config, created from example by `setup.sh`, gitignored
-- `.env` lives at repo root — messaging loads it via `dotenv`, bridge reads env vars, web gets them via `sly-start.sh` exports
-
-## Related Files
-
-- `documentation/designs/global_cli_setup.md` — full design document
-- `documentation/features/020_global_cli_setup.md` — 9-phase implementation plan
-- `web/src/lib/paths.ts` — runtime path resolution for web app
-- `bridge/src/session-manager.ts` — session persistence, CWD validation
-- `bridge/bridge-sessions.json` — persisted session state (NEVER wipe)
-- `.env.example` / `.env` — environment configuration

package/dist/store/.backups/context-priming/references/areas/skills.md

@@ -1,135 +0,0 @@
-# Skills & Infrastructure
-
-Updated: 2026-02-09
-
-## Overview
-
-SlyCode is the central hub for reusable Claude Code assets. Skills provide specialized capabilities, commands are user-invocable shortcuts, agents handle autonomous workflows, and hooks execute on events. Includes global CLI setup, service management scripts, and project scaffolding. This repo tests new skills before deploying to other projects.
-
-## Key Files
-
-### Skills
-- `.claude/skills/context-priming/` - Dynamic codebase context loader
-- `.claude/skills/interactive-explainer/` - Creates visual HTML explainers
-- `.claude/skills/skill-creator/` - Guide for creating new skills
-- `.claude/skills/messaging/` - Send text/voice responses to messaging channels (v2.2.0)
-- `.claude/skills/claude-code-docs-maintainer/` - Maintains Claude Code documentation
-- `.claude/skills/kanban/` - Kanban board management skill
-
-### Agents
-- `.claude/agents/doc-updater.md` - Autonomous documentation maintenance agent
-
-### Commands
-- `.claude/commands/checkpoint.md` - Git checkpoint creation
-- `.claude/commands/feature.md` - Create feature specifications
-- `.claude/commands/chore.md` - Create chore/maintenance plans
-- `.claude/commands/implement.md` - Execute plans
-- `.claude/commands/design.md` - Start iterative design document
-- `.claude/commands/doc-discovery.md` - Documentation discovery
-- `.claude/commands/doc-update.md` - Documentation updates
-- `.claude/commands/reference-fetch.md` - Fetch external docs
-- `.claude/commands/create-command.md` - Meta-command for new commands
-- `.claude/commands/problem_summary.md` - Summarize debugging issues
-
-### Scripts
-- `scripts/setup.sh` - Guided setup: environment, services, global CLI, linger
-- `scripts/sly-start.sh` - Start all services (web, bridge, messaging)
-- `scripts/sly-stop.sh` - Stop all services
-- `scripts/sly-restart.sh` - Restart all services
-- `scripts/sly-dev.sh` - Development mode launcher
-- `scripts/kanban.js` - Kanban CLI tool (installed globally as `sly-kanban`)
-- `scripts/scaffold.js` - Project scaffolding CLI (installed globally as `sly-scaffold`)
-
-### Scaffold Templates
-- `data/scaffold-templates/` - Templates for project scaffolding
-  - `claude-md.md`, `kanban.json`, `mcp.json`, `gitignore`, `archive-readme.md`, `seed-cards.json`
-
-### Config
-- `.claude/settings.local.json` - Local Claude settings
-- `.mcp.json` - MCP server configuration (Context7, etc.)
-- `.env` / `.env.example` - Environment config with service ports
-- `CLAUDE.md` - Project instructions for Claude
-
-### Documentation
-- `documentation/kanban.json` - Kanban card data
-- `documentation/events.json` - Activity event log (card moves, asset operations, sessions)
-- `documentation/terminal-classes.json` - Terminal class definitions
-- `documentation/features/` - Feature specs (001-020)
-- `documentation/chores/` - Chore plans (active + completed/)
-- `documentation/designs/` - Design documents
-- `documentation/reference/` - Reference documentation
-
-## Skill Structure
-
-```
-.claude/skills/{skill-name}/
-├── SKILL.md           # Main skill definition, invocation rules
-└── references/        # Supporting docs, templates, examples
-```
-
-## Command Structure
-
-```markdown
----
-version: X.Y.Z
-updated: YYYY-MM-DD
-allowed-tools: [Tool1, Tool2]
----
-# Command Name
-Instructions for Claude when command is invoked
-```
-
-## Global CLI Commands
-
-After `scripts/setup.sh`, these are available globally:
-- `sly-kanban` - Kanban board management
-- `sly-messaging` - Send messages via messaging channels
-- `sly-scaffold` - Project scaffolding
-
-## Service Management
-
-- `scripts/sly-start.sh` - Start all services (web on 7591, bridge on 7592, messaging on 7593)
-- `scripts/sly-stop.sh` - Stop all services
-- `scripts/setup.sh --service` - Install as persistent system services
-- `scripts/setup.sh --remove-service` - Remove persistent services
-
-## Environment Variables (.env.example)
-
-- **Ports**: WEB_PORT=7591, BRIDGE_PORT=7592, MESSAGING_SERVICE_PORT=7593
-- **Bridge**: BRIDGE_URL for bridge connection
-- **Telegram**: TELEGRAM_BOT_TOKEN, TELEGRAM_AUTHORIZED_USER_ID
-- **STT**: OPENAI_API_KEY (Whisper)
-- **TTS**: ELEVENLABS_API_KEY, ELEVENLABS_VOICE_ID, ELEVENLABS_VOICE_SPEED
-
-## Hooks
-
-- `web/src/hooks/useKeyboardShortcuts.ts` - Number keys 1-9 for project navigation, Escape
-- `web/src/hooks/useCommandsConfig.ts` - Polling-based commands config (30s)
-- `web/src/hooks/useConnectionStatus.ts` - SSE connection state
-- `web/src/hooks/usePolling.ts` - Generic polling hook
-
-## Patterns & Invariants
-
-- Skills use semantic versioning (MAJOR.MINOR.PATCH)
-- Always update version and date when modifying skills/commands
-- Commands invoked via `/command-name` shorthand
-- CLAUDE.md applies to entire project, overrides defaults
-- MCP servers configured in .mcp.json (Context7 for docs)
-- Event log in documentation/events.json tracks card moves, asset ops, sessions (500 cap)
-
-## Environment
-
-- `CLAUDE_ENV` - 'home' or 'work' for environment detection
-- Projects tracked in `projects/registry.json`
-
-## When to Expand
-
-- Creating new skill → skill-creator skill, .claude/skills/
-- Creating new command → create-command, .claude/commands/
-- Creating new agent → .claude/agents/
-- Modifying Claude behavior → CLAUDE.md
-- Adding MCP servers → .mcp.json
-- Service management → scripts/sly-*.sh
-- Setup/installation → scripts/setup.sh
-- Project scaffolding → scripts/scaffold.js, data/scaffold-templates/
-- Activity events → documentation/events.json, web/src/lib/event-log.ts

package/dist/store/.backups/context-priming/references/areas/terminal-bridge.md

@@ -1,232 +0,0 @@
-# Terminal Bridge
-
-Updated: 2026-02-14
-
-## Overview
-
-PTY bridge server manages AI coding sessions across multiple providers (Claude, Gemini, Codex). Express server spawns/manages PTY processes, streams output via SSE. Provider-agnostic command building via data-driven config (`providers.json`). Includes security hardening (command whitelist, CWD validation, localhost binding), activity tracking with transition logging for debugging, atomic state persistence, bulk session management, and graceful idle timeout handling. React components connect through Next.js API proxy.
-
-## Key Files
-
-### Bridge Server (Node/Express)
-- `bridge/src/index.ts` - Express server entry, routes setup, localhost binding
-- `bridge/src/session-manager.ts` - Session lifecycle, PTY spawning, provider resolution, activity tracking, atomic state saving
-- `bridge/src/provider-utils.ts` - Provider config loading, command building, session detection helpers
-- `bridge/src/pty-handler.ts` - PTY process wrapper, output buffering
-- `bridge/src/api.ts` - REST endpoints for session CRUD, /stats, stop-all, activity-log
-- `bridge/src/websocket.ts` - WebSocket upgrade handling (legacy, SSE preferred)
-- `bridge/src/claude-utils.ts` - Claude session ID detection from ~/.claude/projects/
-- `bridge/src/types.ts` - Session, BridgeConfig, BridgeStats, ActivityTransition, provider interfaces
-
-### Configuration
-- `bridge/bridge-config.json` - Runtime config: allowedCommands (claude, codex, gemini, bash), CORS origins
-- `data/providers.json` - Provider registry: CLI commands, permission flags, resume types, prompt handling, stage defaults
-- `documentation/terminal-classes.json` - Terminal class definitions for command visibility
-- `data/commands.json` - Unified command configuration with visibility per class
-
-### Web Components
-- `web/src/components/Terminal.tsx` - xterm.js terminal, SSE via ConnectionManager
-- `web/src/components/ClaudeTerminalPanel.tsx` - Terminal panel with startupCommands/activeCommands
-- `web/src/components/GlobalClaudePanel.tsx` - Floating panel for project-wide session
-- `web/src/app/api/bridge/[...path]/route.ts` - Next.js proxy to bridge server
-
-## Key Functions
-
-- `SessionManager.createSession()` - Resolves provider, builds command via `buildProviderCommand()`, validates CWD, spawns PTY
-- `SessionManager.resolveSessionName()` - Checks both new (with provider) and legacy session name formats
-- `SessionManager.stopSession()` - Graceful SIGINT, waits for exit
-- `SessionManager.stopAllSessions()` - Bulk stop all running/detached sessions, returns count
-- `SessionManager.getStats()` - Returns BridgeStats with activity info
-- `SessionManager.checkIdleSessions()` - Idle timeout with grace period after disconnect
-- `buildProviderCommand()` - Assembles { command, args } from provider config, handles flag vs subcommand resume
-- `getProvider()` - Loads provider config by ID from providers.json (30s cache)
-- `supportsSessionDetection()` - Check if provider supports GUID-based session detection
-- `Terminal.connectSSE()` - Via ConnectionManager for auto-reconnection
-
-## Data Models
-
-```typescript
-SessionInfo {
-  name, status (running|stopped|detached), pid, connectedClients,
-  hasHistory, claudeSessionId, lastOutputAt,
-  provider?, skipPermissions?,
-  lastOutputSnippet?, lastOutputRawHex?, lastOutputDataLength?
-}
-
-BridgeStats {
-  bridgeTerminals: number;      // Total PTY sessions
-  connectedClients: number;     // Total SSE/WS connections
-  activelyWorking: number;      // Sessions with output in last 2s
-  sessions: SessionActivity[];  // Per-session activity
-}
-
-SessionActivity {
-  name, status, lastOutputAt, isActive
-}
-
-ActivityTransition {
-  timestamp: string;
-  from: string;                 // Previous state
-  to: string;                   // New state
-  lastOutputAt: string;
-  outputAge: number;
-  trigger?: {                   // Debug info for phantom blips
-    snippet: string;
-    hex: string;
-    dataLength: number;
-  }
-}
-
-BridgeConfig {
-  host, port, sessionFile, defaultIdleTimeout, maxSessions
-}
-
-BridgeRuntimeConfig {
-  allowedCommands: string[];    // e.g., ['claude', 'codex', 'gemini', 'bash']
-  cors: { origins: string[] }
-}
-
-CreateSessionRequest {
-  name: string;
-  provider?: string;            // Provider id from providers.json
-  skipPermissions?: boolean;    // Whether to add permission-skip flag
-  command?: string;             // Legacy: direct command (backward compat)
-  cwd: string;
-  prompt?: string;
-  fresh?: boolean;
-}
-
-PersistedSession {
-  claudeSessionId?, cwd, createdAt, lastActive,
-  provider?: string;            // Defaults to 'claude' for old sessions
-  skipPermissions?: boolean;    // Defaults to true for old sessions
-}
-
-// Provider config types (provider-utils.ts)
-ProviderConfig {
-  id, displayName, command, install,
-  permissions: { flag, label, default },
-  resume: { supported, type ('flag'|'subcommand'), flag?, subcommand?, lastFlag?, detectSession, sessionDir? },
-  prompt: { type ('positional'|'flag'), interactive?, nonInteractive? }
-}
-
-ProvidersData {
-  providers: Record<string, ProviderConfig>;
-  defaults: {
-    stages: Record<string, { provider, skipPermissions }>;
-    global: { provider, skipPermissions };
-    projects: Record<string, { provider, skipPermissions }>;
-  }
-}
-```
-
-## Security Hardening
-
-- **Localhost binding**: HOST defaults to `localhost` (not `0.0.0.0`)
-- **Command whitelist**: Only commands in `bridge-config.json` allowedCommands can be spawned (claude, codex, gemini, bash)
-- **Provider validation**: Provider ID must exist in providers.json; resolved command must be in allowedCommands
-- **CWD validation**: Requires absolute path, verifies exists and is accessible before spawning PTY
-- **CORS origins**: Configured in bridge-config.json, not wide-open
-
-## Activity Tracking
-
-- `lastOutputAt` timestamp updated on every PTY output
-- `isActive` = output within last 2 seconds (with 1s debounce)
-- `activelyWorking` count in BridgeStats for health monitor
-- Cards with active sessions show pulsing green glow in UI
-- **Activity transitions**: Logged with trigger details (snippet, hex, data length) for debugging phantom blips
-- `GET /activity-log/:name` endpoint exposes transition history per session
-
-## State Persistence
-
-- Session state saved to bridge-sessions.json via atomic writes (temp file + rename)
-- State file uses `__dirname` resolution for reliable file location
-- Missing file (ENOENT) handled gracefully; corrupt JSON throws fatal error
-- Prevents silent data loss from corrupted state
-
-## Race Condition Handling
-
-- **Disconnect grace period**: 5 seconds before session eligible for idle timeout
-- **Status transitions**: Protected against reconnect during disconnect
-- **SSE cleanup**: Proper client tracking on connection/disconnection
-
-## Terminal Classes
-
-Controls which commands appear in each context:
-- `global-terminal` - Dashboard terminal (future)
-- `project-terminal` - Project-level panel at bottom
-- `backlog`, `design`, `implementation`, `testing`, `done` - Card terminals by stage
-- `command-assistant` - Terminal in CommandConfigModal
-
-## Multi-Provider System
-
-### Supported Providers
-- **Claude Code** (`claude`) — Positional prompts, `--resume <GUID>` with auto-detection, `--dangerously-skip-permissions`
-- **Codex CLI** (`codex`) — Positional prompts, `codex resume --last` (subcommand-style), `--yolo`
-- **Gemini CLI** (`gemini`) — Flag-based prompts (`-i`/`-p`), `--resume` (no GUID), `--yolo`
-
-### Command Building (`buildProviderCommand`)
-- Returns `{ command, args }` tuple (command can change for Codex resume: `codex resume`)
-- Permission flag added if `skipPermissions: true`
-- Resume: flag-type appends `--resume [GUID]`; subcommand-type prepends `resume [GUID|--last]`
-- Prompt: positional appends as final arg; flag-type uses `-i <prompt>` (interactive)
-- No prompt on resume (user types into running session instead)
-
-### Session Name Format
-- **New format**: `{projectId}:{provider}:card:{cardId}` or `{projectId}:{provider}:global`
-- **Legacy format**: `{projectId}:card:{cardId}` or `{projectId}:global`
-- `resolveSessionName()` checks new format first, falls back to legacy via `toLegacySessionName()`
-- Old sessions without provider field default to `provider: "claude"`
-
-### GUID Detection (Claude only)
-- `supportsSessionDetection()` checks `provider.resume.detectSession`
-- Watches `~/.claude/projects/` for new `.jsonl` files after spawn
-- `getClaimedGuids()` excludes GUIDs already used by other sessions
-- Gemini/Codex use `--resume --last` (no GUID tracking)
-
-### Stage-Based Defaults
-- `providers.json` `defaults.stages` maps each kanban stage → `{ provider, skipPermissions }`
-- UI pre-fills provider dropdown from stage default
-- `defaults.global` for project-level terminals
-- `defaults.projects` reserved for per-project overrides (future)
-
-## Patterns & Invariants
-
-- Session names include provider segment: `{projectId}:{provider}:card:{cardId}` (new) or legacy `{projectId}:card:{cardId}`
-- Claude prompts passed as positional arg, NOT `-p` flag (that's print mode)
-- Resume behavior is provider-specific: flag vs subcommand, GUID vs latest
-- SSE streams through `/api/bridge/sessions/{name}/stream` proxy
-- Bridge runs on port 3456 (localhost), proxied through Next.js
-- Idle timeout: 4 hours default, checked every 60 seconds
-- Atomic state saves prevent data corruption
-- Provider config cached 30s in provider-utils.ts
-
-## API Endpoints
-
-- `GET /sessions` - List all sessions
-- `GET /sessions/:name` - Get session info
-- `POST /sessions` - Create session (validates command + CWD)
-- `DELETE /sessions/:name` - Stop or delete session
-- `POST /sessions/:name/input` - Send input to PTY
-- `POST /sessions/:name/resize` - Resize terminal
-- `POST /sessions/:name/stop` - Send Escape key to active session (soft stop)
-- `GET /sessions/:name/stream` - SSE output stream
-- `POST /sessions/stop-all` - Bulk stop all running sessions
-- `GET /stats` - BridgeStats with activity info
-- `GET /activity-log/:name` - Activity transition history for debugging
-
-## When to Expand
-
-- Session not starting → session-manager.ts createSession(), check command whitelist + provider validation
-- Adding new provider → data/providers.json, bridge-config.json allowedCommands
-- Provider command issues → provider-utils.ts buildProviderCommand()
-- Resume not working → provider-utils.ts (flag vs subcommand), claude-utils.ts (GUID detection)
-- Security concerns → bridge-config.json, session-manager.ts validation
-- Activity tracking issues → session-manager.ts handlePtyOutput(), getStats(), ActivityTransition
-- Phantom activity blips → activity-log endpoint, transition trigger data
-- Terminal display issues → Terminal.tsx, xterm setup
-- Connection problems → api/bridge proxy, connection-manager.ts
-- Idle timeout issues → session-manager.ts checkIdleSessions()
-- Bulk operations → stopAllSessions(), /sessions/stop-all
-- State corruption → session-manager.ts loadState/saveState
-- Session name resolution → session-manager.ts resolveSessionName(), toLegacySessionName()