@slycode/slycode 0.1.14 → 0.1.15

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

@@ -1,35 +1,37 @@
 # Skills & Infrastructure
 
-Updated: 2026-02-09
+Updated: 2026-03-14
 
 ## 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.
+SlyCode is the central hub for reusable AI coding assets (skills, agents, configs). All commands have been converted to skills — everything is now a skill with SKILL.md. 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
+### Skills (17 total — all commands converted to 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
+- `.claude/skills/kanban/` - Kanban board management (v1.4.0), notes + automation subcommands, multiline description support
+- `.claude/skills/checkpoint/` - Git checkpoint creation
+- `.claude/skills/feature/` - Create feature specifications
+- `.claude/skills/chore/` - Create chore/maintenance plans
+- `.claude/skills/implement/` - Execute plans
+- `.claude/skills/design/` - Start iterative design document
+- `.claude/skills/doc-discovery/` - Documentation discovery
+- `.claude/skills/doc-update/` - Documentation updates
+- `.claude/skills/reference-fetch/` - Fetch external docs
+- `.claude/skills/create-command/` - Meta-command for new commands
+- `.claude/skills/problem_summary/` - Summarize debugging issues
+- `.claude/skills/convert-asset/` - Convert store asset between provider formats
 
 ### 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
+### Commands (REMOVED)
+- `.claude/commands/` directory no longer exists — all converted to `.claude/skills/*/SKILL.md`
 
 ### Scripts
 - `scripts/setup.sh` - Guided setup: environment, services, global CLI, linger
@@ -37,24 +39,69 @@ SlyCode is the central hub for reusable Claude Code assets. Skills provide speci
 - `scripts/sly-stop.sh` - Stop all services
 - `scripts/sly-restart.sh` - Restart all services
 - `scripts/sly-dev.sh` - Development mode launcher
-- `sly-kanban` - Kanban CLI tool (installed globally as `sly-kanban`)
-- `scripts/scaffold.js` - Project scaffolding CLI (installed globally as `sly-scaffold`)
+- `sly-kanban` - Kanban CLI tool (installed globally as `sly-kanban`), board/reorder/notes/automation subcommands, last_modified_by tracking. Sequential card numbers (auto-backfilled on first run, `nextCardNumber` on kanban root). Notes: summarize subcommand (oldest/summarize), 100 hard cap, 30 soft suggestion threshold. Archive safeguard: automation cards cannot be archived (bulk `archive done` skips them with count, individual archive rejects with error). `automation enable` no longer recalculates nextRun locally (moved server-side to web scheduler/kanban API).
+- `scripts/scaffold.js` - Project scaffolding CLI (installed globally as `sly-scaffold`), multi-provider support (Claude/Codex/Gemini), provider overlay templates, purpose-grouped scaffold plan, overwrite protection, clean output (suppresses zero-count copied/created lines, reports new vs existing doc dirs)
+- `scripts/migrate-store.sh` - Migrates store from provider-split to canonical flat layout
+- `scripts/migrate-sly-actions.js` - One-time v2→v3 sly-actions.json migration (sessionState→placement, visibleIn.classes→classAssignments) [historical]
+- `scripts/convert-actions-to-md.js` - One-time v3→v4 migration: converts sly-actions.json to individual .md files in store/actions/
+
+### Store (Canonical Layout)
+- `store/skills/` - 17 canonical skill definitions (single source of truth, includes dummy)
+- `store/actions/` - Individual action .md files (v4.0 format: YAML frontmatter + prompt body)
+- `store/agents/` - Agent definitions (doc-updater.md)
+- `store/mcp/` - MCP module configs (context7.json)
+- `store/.backups/` - Backup copies created when accepting updates
+- `store/.ignored-updates.json` - Tracks dismissed update versions
+- `.agents/skills/` - Codex-format copies deployed to SlyCode (7 skills: chore, context-priming, design, feature, implement, kanban, messaging)
+
+### Update Delivery
+- `updates/skills/` - Staged skill updates awaiting acceptance
+- `updates/actions/` - Staged action updates (content-hash based comparison)
+- `updates/agents/` - Staged agent updates
+- `updates/claude/` - Provider-specific update overrides
+- Workflow: updates/ → accept → store/ (with backup) → deploy to projects
+- Actions use additive class merge on accept: keeps user's class customizations, adds new upstream classes
+
+### NPM Distribution
+- `packages/slycode/` - Main npm package (`@slycode/slycode` v0.1.11): `slycode` CLI with workspace, start, stop, service, doctor, skills, sync, update, config, uninstall subcommands
+- `packages/create-slycode/` - Scaffold tool (`@slycode/create-slycode` v0.1.11): `create-slycode` for initializing new workspaces. Setup wizard prompts for timezone (auto-detects via `Intl.DateTimeFormat`, writes `TZ=` to .env for cron scheduling). System service prompt skipped on Windows. Tutorial content seeded into workspace root (not a separate `slycode_tutorial/` subdirectory). Kanban seed uses correct stage-based format (`project_id`, `stages`, `last_updated`). Registry seeds workspace root as default project (id: `slycode`).
+- Both packages under `@slycode` npm scope. Template paths resolve via `node_modules/@slycode/slycode/templates/`.
+- `slycode config [key] [value]` - View/modify slycode.config.js via CLI
+- `slycode uninstall` - Remove services and CLI tools (preserves workspace)
+- `slycode sync` - Refresh workspace updates/ from package templates
+- `slycode update` - Platform-aware restart (systemd/launchd/Windows Task Scheduler/background)
+- `slycode start` auto-refreshes updates on startup + npm version check (3s timeout)
+
+### Build Pipeline
+- `build/build-package.ts` - Full build script: builds services, syncs updates, copies templates to packages/slycode/. Copies `data/scaffold-templates/`, `store/`, `updates/actions/` to dist/ for runtime access. Also copies store/actions/ to packages/slycode/templates/store/actions/ for scaffold seeding. Removed sly-actions.json template (actions now individual .md files).
+- `build/sync-updates.ts` - Sync manifest skills + actions from store/ to updates/ (enforces manifest as authority). Returns `{ skills: SyncResult, actions: SyncResult }`.
+- `build/store-manifest.js` - Curated list of skills and actions included in npm package and updates
 
 ### Scaffold Templates
-- `data/scaffold-templates/` - Templates for project scaffolding
-  - `claude-md.md`, `kanban.json`, `mcp.json`, `gitignore`, `archive-readme.md`, `seed-cards.json`
+- `data/scaffold-templates/` - Blessed defaults for new workspaces. Sourced by build pipeline instead of `data/*.json` (working copies may have local changes).
+  - `base-instructions.md` (provider-neutral, replaces claude-md.md), `kanban.json`, `mcp.json`, `gitignore`, `archive-readme.md`, `seed-cards.json`, `events.json`
+  - `providers.json` — seeded into new workspaces by create-slycode (sly-actions.json removed — actions now in store/actions/*.md)
+  - `overlays/` - Provider-specific instruction overlays (`claude.md`, `codex.md`, `gemini.md`)
+  - To update templates: manually copy `data/*.json` → `data/scaffold-templates/*.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
+- `AGENTS.md` - Project instructions for Codex provider (mirrors CLAUDE.md content)
+
+### Licensing
+- `LICENSE` - Business Source License 1.1 (BUSL-1.1)
+- `LICENSING.md` - Human-readable licensing guide (open-core model)
+- All package.json files set `"license": "BUSL-1.1"` (web, bridge, messaging, slycode, create-slycode)
+- Design doc: `documentation/designs/open_core_licensing.md`
 
 ### 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/features/` - Feature specs (001-049)
 - `documentation/chores/` - Chore plans (active + completed/)
 - `documentation/designs/` - Design documents
 - `documentation/reference/` - Reference documentation
@@ -67,17 +114,7 @@ SlyCode is the central hub for reusable Claude Code assets. Skills provide speci
 └── 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
-```
+All user-invocable operations are now skills (no separate commands directory).
 
 ## Global CLI Commands
 
@@ -95,27 +132,46 @@ After `scripts/setup.sh`, these are available globally:
 
 ## Environment Variables (.env.example)
 
+- **TZ**: IANA timezone for cron schedule evaluation (e.g., Australia/Melbourne). Defaults to UTC if unset.
 - **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)
+- **STT**: STT_BACKEND (openai|local), OPENAI_API_KEY (Whisper API), WHISPER_CLI_PATH + WHISPER_MODEL_PATH (local whisper.cpp)
 - **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/useSlyActionsConfig.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
+- Always update version and date when modifying skills
+- Skills invoked via `/skill-name` shorthand (commands no longer exist as separate entity)
 - 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)
+- Store uses canonical flat layout: `store/skills/`, `store/actions/`, `store/agents/`, `store/mcp/` (no provider subdirectories)
+- Skill import defaults to SKILL.md-only (via `skillMainOnly` flag on store POST) to avoid overwriting references/. Full folder import available via ImportDialog.
+- Assets deployed from store to projects (including SlyCode itself)
+- Codex-format skills live in `.agents/skills/`, Claude in `.claude/skills/`
+- Update delivery: `updates/` → accept → `store/` (with backup) → deploy to projects
+- `store/.ignored-updates.json` tracks dismissed update versions per asset
+- Scaffold uses overwrite protection: copyDirRecursive defaults to skip-existing, all template files check existence. Tutorial content seeded into workspace root via `seedTutorialWorkspaceContent()` (not separate subdirectory).
+- CLAUDE.release.md + templates/CLAUDE.md: AI-operated CLI policy — treat CLI tools as AI-operated, don't instruct users to run CLI commands, execute and report results plainly
+- Scaffold uses multi-provider overlays: base-instructions.md + overlays/{provider}.md for provider-specific setup
+- Scaffold groups items by purpose: AI Config, Project Management, Documentation, Skills, Configuration
+- Build pipeline: sync-updates.ts enforces store-manifest.js as authority for both skills and actions, removes non-manifest items from updates/. build-package.ts copies scaffold-templates/, store/, and updates/actions/ to dist/ for prod runtime access. Templates (skills, actions, tutorial-project) removed from packages/slycode/templates/ — build pipeline is the sole delivery mechanism.
+- Scaffold seeds `providers.json` from `data/scaffold-templates/` into new workspaces (create-slycode). Actions delivered via updates/actions/ instead of scaffold template.
+- kanban.js stamps `last_modified_by: 'cli'` on all write operations and `source: 'cli'` on events. Uses dynamic `PROJECT_NAME` (from workspace basename) for event project field and session names — no hardcoded 'claude-master'.
+- kanban.js has `board` (--all/--stages/--inflight/--compact), `reorder` (positional card IDs or --top/--bottom/--position), `notes` (add/list/search/edit/delete/clear/oldest/summarize), and `automation` (configure/enable/disable/run/status/list) subcommands
+- Card numbers: `backfillCardNumbers()` sorts all cards by created_at and assigns sequential numbers. `ensureCardNumbers()` auto-runs on first create. Verbose format shows `(#0001)`. Search includes automation cards when query is provided (only bare search excludes them).
+- Notes summarization: `notes oldest [N]` shows oldest N notes, `notes summarize "text" --count N --agent "Name"` replaces oldest N with a summary note (marked `summary: true`, tracks `summarizedCount` and `dateRange`). Hard cap 100 notes, soft suggestion at 30.
+- `kanban reorder` sets order 10,20,30... on listed cards; unlisted cards keep relative order but sort after prioritized ones
+- Automation uses card description as prompt (no separate --prompt option). `automation run` sends card description to bridge session.
 
 ## Environment
 
@@ -125,11 +181,16 @@ After `scripts/setup.sh`, these are available globally:
 ## When to Expand
 
 - Creating new skill → skill-creator skill, .claude/skills/
-- Creating new command → create-command, .claude/commands/
+- Creating new command → create-command skill, creates a new skill in .claude/skills/
 - Creating new agent → .claude/agents/
-- Modifying Claude behavior → CLAUDE.md
+- Cross-provider assets → store/, .agents/skills/, convert-asset skill
+- Skill updates → updates/ directory, web UpdatesView, store/.ignored-updates.json
+- NPM distribution → packages/slycode/, packages/create-slycode/
+- Store migration → scripts/migrate-store.sh
+- Modifying agent 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/
+- Project scaffolding → scripts/scaffold.js, data/scaffold-templates/, data/scaffold-templates/overlays/
+- Build pipeline → build/build-package.ts, build/sync-updates.ts, build/store-manifest.js
 - Activity events → documentation/events.json, web/src/lib/event-log.ts

package/{templates/updates/skills/context-priming/references → dist/store/skills/context-priming}/references/areas/terminal-actions.md

@@ -105,7 +105,7 @@ Global context: `{ project, projectPath }`
 - **Chore** - Create maintenance/bug fix plan from card
 - **Analyse Implementation** - Detailed analysis with findings table and problem logging
 - **Test Review** - Interactive test review for testing lane (checklist assessment, implicit testing, max 3 questions per Q&A round, area context priming)
-- **Convert Asset** - Cross-provider asset conversion (global scope, placement: startup)
+- **Convert Asset** - Cross-provider asset conversion (scoped to claude-master project only, placement: startup)
 - **Organise Backlog** - Uses `kanban board` for snapshot and `kanban reorder` for reprioritisation
 
 ## Placement

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

@@ -1,56 +1,63 @@
 # Terminal Bridge
 
-Updated: 2026-02-14
+Updated: 2026-03-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.
+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, graceful idle timeout handling, and image delivery to PTY sessions. 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/session-manager.ts` - Session lifecycle, PTY spawning, provider resolution, activity tracking, atomic state saving, deferred prompt delivery (Windows)
+- `bridge/src/provider-utils.ts` - Provider config loading, command building, session detection helpers, instruction file check/create
+- `bridge/src/pty-handler.ts` - PTY process wrapper, output buffering, Windows .cmd extension resolution
+- `bridge/src/api.ts` - REST endpoints for session CRUD, /stats, stop-all, activity-log, image upload, instruction file check
+- `bridge/src/screenshot-utils.ts` - Screenshot saving, retention (10-file cap), .gitignore management
 - `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
+- `bridge/src/claude-utils.ts` - Provider-agnostic session ID detection (Claude/Codex/Gemini) with unified dispatchers
+- `bridge/src/types.ts` - Session (incl. pendingPrompt, pendingPromptTimer), 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/Terminal.tsx` - xterm.js terminal, SSE via ConnectionManager, resize broadcast with echo-loop suppression, paste interception via `attachCustomKeyEventHandler`
+- `web/src/components/ClaudeTerminalPanel.tsx` - Terminal panel with startupActions/activeActions
 - `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.getSessionCwd()` - Returns CWD for a session (running or persisted), used by image upload endpoint
+- `SessionManager.createSession()` - Resolves provider, builds command via `buildProviderCommand()`, validates CWD, spawns PTY. Uses `creating` placeholder as mutex to prevent concurrent creation (returns 202 for duplicate requests).
 - `SessionManager.resolveSessionName()` - Checks both new (with provider) and legacy session name formats
-- `SessionManager.stopSession()` - Graceful SIGINT, waits for exit
+- `SessionManager.stopSession()` - Graceful SIGINT, waits for exit, removes session from in-memory map (frees slot; data preserved in persistedState for resume)
 - `SessionManager.stopAllSessions()` - Bulk stop all running/detached sessions, returns count
 - `SessionManager.getStats()` - Returns BridgeStats with activity info
+- `SessionManager.getGroupStatus(group)` - Returns status of all sessions in a group
+- `SessionManager.relinkSession(name)` - Re-detect session ID from most recent provider session file
 - `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
+- `checkInstructionFile(providerId, cwd)` - Checks if provider's instruction file exists. Priority scan: primary file → alt file → sibling copy source → no action needed
+- `ensureInstructionFile(providerId, cwd)` - Creates missing instruction file by copying from sibling (never throws, logs warnings)
+- `supportsSessionDetection()` - Check if provider supports session detection (all three now do)
+- `getProviderSessionDir()` - Provider-agnostic session directory resolver
+- `listProviderSessionFiles()` - Provider-agnostic session file listing
+- `detectNewProviderSessionId()` - Provider-agnostic new session detection dispatcher
+- `getMostRecentProviderSessionId()` - Find most recent session file (used by relink)
 - `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?
+  name, group, status (running|stopped|detached|creating), pid, connectedClients,
+  hasHistory, resumed, lastActive, lastOutputAt?,
+  claudeSessionId?, provider?, skipPermissions?
 }
 
 BridgeStats {
@@ -61,20 +68,19 @@ BridgeStats {
 }
 
 SessionActivity {
-  name, status, lastOutputAt, isActive
+  name, status, lastOutputAt, isActive,
+  activityStartedAt?, lastOutputSnippet?
 }
 
 ActivityTransition {
   timestamp: string;
-  from: string;                 // Previous state
-  to: string;                   // New state
+  became: 'active' | 'inactive';
   lastOutputAt: string;
-  outputAge: number;
-  trigger?: {                   // Debug info for phantom blips
-    snippet: string;
-    hex: string;
-    dataLength: number;
-  }
+  activityStartedAt: string;
+  outputAgeMs: number;
+  triggerSnippet: string;
+  triggerRawHex: string;
+  triggerDataLength: number;
 }
 
 BridgeConfig {
@@ -91,9 +97,11 @@ CreateSessionRequest {
   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;
+  cwd?: string;
   fresh?: boolean;
+  idleTimeout?: number;
+  prompt?: string;
+  createInstructionFile?: boolean; // Opt-in: copy sibling instruction file if missing
 }
 
 PersistedSession {
@@ -107,7 +115,9 @@ 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? }
+  prompt: { type ('positional'|'flag'), interactive?, nonInteractive? },
+  instructionFile?: string,    // e.g. "CLAUDE.md" for Claude, "AGENTS.md" for Codex
+  altInstructionFile?: string  // e.g. "CODEX.md" for Codex (provider-specific alt)
 }
 
 ProvidersData {
@@ -123,7 +133,7 @@ ProvidersData {
 ## 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)
+- **Command whitelist**: Only commands in `bridge-config.json` allowedCommands can be spawned (claude, codex, gemini, bash — all four in both config and hardcoded defaults)
 - **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
@@ -146,9 +156,12 @@ ProvidersData {
 
 ## Race Condition Handling
 
+- **Creation mutex**: `creating` status placeholder prevents concurrent createSession() for same name. API returns 202 for idempotent duplicate requests. Placeholder cleaned up on failure.
+- **GUID detection cancellation**: `guidDetectionCancelled` flag on Session prevents detection from overwriting state after session stops/exits.
 - **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
+- **SSE heartbeat**: 15-second comment heartbeats (`: heartbeat\n\n`) keep connections alive through proxies (Tailscale, Next.js). Started per-client on SSE connect, cleared on disconnect.
 
 ## Terminal Classes
 
@@ -162,15 +175,15 @@ Controls which commands appear in each context:
 
 ### 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`
+- **Codex CLI** (`codex`) — Positional prompts, `codex resume --last [PROMPT]` (subcommand-style), `--yolo`, session detection via rollout files
+- **Gemini CLI** (`gemini`) — Flag-based prompts (`-i`/`-p`), `--resume` (no GUID), `--yolo`, session detection via chat JSON files
 
 ### 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)
+- Prompt works alongside resume: Claude accepts positional after `--resume`, Codex accepts positional after `resume --last`
 
 ### Session Name Format
 - **New format**: `{projectId}:{provider}:card:{cardId}` or `{projectId}:{provider}:global`
@@ -178,11 +191,14 @@ Controls which commands appear in each context:
 - `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
+### Session Detection (All Providers)
+- `supportsSessionDetection()` checks `provider.resume.detectSession` — all three providers have `detectSession: true`
+- Provider-agnostic dispatchers route to provider-specific logic:
+  - **Claude**: Watches `~/.claude/projects/<cwd>/` for new `.jsonl` files, extracts GUID from filename
+  - **Codex**: Watches `~/.codex/sessions/YYYY/MM/DD/` for new rollout files, extracts UUID from filename
+  - **Gemini**: Watches `~/.gemini/tmp/<SHA256(cwd)>/chats/` for new session JSON files
 - `getClaimedGuids()` excludes GUIDs already used by other sessions
-- Gemini/Codex use `--resume --last` (no GUID tracking)
+- Detection timeout: 60 seconds (Gemini CLI takes ~30s to create session files)
 
 ### Stage-Based Defaults
 - `providers.json` `defaults.stages` maps each kanban stage → `{ provider, skipPermissions }`
@@ -196,24 +212,37 @@ Controls which commands appear in each context:
 - 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
+- Bridge port from BRIDGE_PORT env var (default 7592 prod, 3004 dev), localhost binding, proxied through Next.js
+- Stopped sessions removed from in-memory `sessions` map (frees slot); session data preserved in `persistedState` for future resume. `getSessionInfo()` falls back to persistedState when session not in map.
 - Idle timeout: 4 hours default, checked every 60 seconds
-- Atomic state saves prevent data corruption
+- Atomic state saves with unique temp file names (`.tmp.${pid}.${Date.now()}`) prevent race conditions
 - Provider config cached 30s in provider-utils.ts
+- Bracketed paste mode (`\x1b[200~...\x1b[201~`) for multi-line prompt input, 150ms delay before Enter
+- lastActive timestamp preserved on resume (not overwritten with current time)
+- Image delivery: saves to `screenshots/` in session CWD, timestamped filenames, 10-file retention, auto-.gitignore
+- Screenshot reference injected as `[Screenshot: screenshots/<filename>]` text into PTY (not auto-submitted)
+- Instruction file fallback: `checkInstructionFile()` scans for sibling instruction files (CLAUDE.md, AGENTS.md, CODEX.md, GEMINI.md) in priority order. `ensureInstructionFile()` copies when requested. Creation is opt-in only (`createInstructionFile: true` in CreateSessionRequest).
+- Resize broadcast: PTY resize events broadcast via SSE to all connected tabs. Terminal.tsx guards resize POSTs (only visible tabs), uses `suppressResizePost` flag to prevent ResizeObserver echo loop when adapting to another tab's resize. Skips resize on reconnect.
+- **Windows ConPTY support**: On Windows, CLI tools are installed as `.cmd` batch wrappers — `pty-handler.ts` auto-appends `.cmd` extension. cmd.exe mangles multi-line CLI args (newlines become command separators), so prompts are deferred: stripped from spawn args and delivered via bracketed paste after provider output settles (1.5s quiet, 30s max timeout). ConPTY silently truncates PTY writes >~4KB, so large prompts are chunked (1024-byte chunks with 500ms delay, surrogate-pair-safe boundaries). Session tracks `pendingPrompt` and `pendingPromptTimer` for debounced delivery.
 
 ## API Endpoints
 
 - `GET /sessions` - List all sessions
 - `GET /sessions/:name` - Get session info
-- `POST /sessions` - Create session (validates command + CWD)
+- `POST /sessions` - Create session (validates command + CWD, returns 202 if already creating)
 - `DELETE /sessions/:name` - Stop or delete session
 - `POST /sessions/:name/input` - Send input to PTY
 - `POST /sessions/:name/resize` - Resize terminal
+- `POST /sessions/:name/image` - Upload image to session's screenshots/ dir (multipart, 10MB limit), returns filename
+- `POST /sessions/:name/action` - Structured actions: compact, clear, interrupt
+- `POST /sessions/:name/relink` - Re-detect session ID from most recent provider session file
 - `POST /sessions/:name/stop` - Send Escape key to active session (soft stop)
 - `GET /sessions/:name/stream` - SSE output stream
+- `GET /groups/:group/status` - Group-level session status aggregation
 - `POST /sessions/stop-all` - Bulk stop all running sessions
 - `GET /stats` - BridgeStats with activity info
 - `GET /activity-log/:name` - Activity transition history for debugging
+- `GET /check-instruction-file?provider=X&cwd=Y` - Check if instruction file exists, returns { needed, targetFile?, copySource? }
 
 ## When to Expand
 
@@ -228,5 +257,8 @@ Controls which commands appear in each context:
 - Connection problems → api/bridge proxy, connection-manager.ts
 - Idle timeout issues → session-manager.ts checkIdleSessions()
 - Bulk operations → stopAllSessions(), /sessions/stop-all
+- Image delivery → screenshot-utils.ts (saving/retention), api.ts (image endpoint), ClaudeTerminalPanel.tsx (paste handling)
 - State corruption → session-manager.ts loadState/saveState
 - Session name resolution → session-manager.ts resolveSessionName(), toLegacySessionName()
+- Instruction file issues → provider-utils.ts checkInstructionFile/ensureInstructionFile, api.ts check-instruction-file endpoint
+- Terminal resize sync → Terminal.tsx sendResize(), SSE resize event handling