@slycode/slycode 0.1.14 → 0.1.15

package/templates/updates/skills/context-priming/references/references/areas/scripts-deployment.md

@@ -1,183 +0,0 @@
-# Scripts & Deployment
-
-Updated: 2026-03-13
-
-## 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) |
-| `migrate-store.sh` | Migrate store from provider-split to canonical flat layout |
-
-## 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 `slycode.config.js` (loaded by `start.ts`), or `.env` fallback, passed as `PORT` env var
-- `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**: `slycode start` spawns services with `cwd: workspace` (ensures services inherit correct working directory). Sets `SLYCODE_HOME` env var for prod path resolution.
-- **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. Check build tools (`check_build_tools()` — gcc, make, g++ for node-pty compilation)
-3. Create directories (`~/bin`, `~/.slycode/logs`)
-4. `npm install` in web, bridge, messaging
-5. Build bridge, messaging, web (web last — heaviest, needs most memory)
-6. `chmod +x` on CLI scripts
-7. Symlink CLIs to `~/bin` (sly-kanban, sly-scaffold, sly-messaging)
-8. Update `registry.json` with correct SlyCode path
-9. Copy `.env.example` to `.env` if missing
-10. Prompt: install as system service?
-11. 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` | `sly-kanban` | 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` — centralized `getSlycodeRoot()` (via `SLYCODE_HOME` → cwd fallback) and `getPackageDir()` (detects `node_modules/slycode/dist/` for prod). All 10+ API routes import from paths.ts — no local `getRepoRoot()` helpers. `legacy root env var` env var removed.
-- Bridge: reads `BRIDGE_PORT` from env
-- Messaging: uses `SLYCODE_HOME` env var for workspace resolution (replaces `__dirname`-relative paths that broke in prod npm packages). CLI auto-detects service port (dev 3005 / prod 7593) with caching.
-- 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 the AI CLI associates sessions with the correct project directory.
-
-## Env Files
-
-- **`.env.example`**: template with all config vars, prod port defaults, placeholder secrets, TZ timezone var, DEV_HOSTNAME (Tailscale hostname for Next.js dev origins)
-- **`.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
-
-## slycode.config.js
-
-Workspace-level configuration file loaded by `packages/slycode/src/config/loader.ts`:
-
-```js
-module.exports = {
-  ports: { web: 7591, bridge: 7592, messaging: 7593 },
-  services: { web: true, bridge: true, messaging: true },
-  host: '127.0.0.1',  // Only web binds to this; bridge+messaging always localhost
-};
-```
-
-- `slycode config [key] [value]` — View/modify config via CLI
-- Defaults: ports 7591/7592/7593, all services enabled, host `127.0.0.1`
-- Only web binds to `config.host`; bridge and messaging are always `127.0.0.1`
-
-## NPM Distribution (`packages/`)
-
-- `packages/slycode/` (v0.1.0) — Main npm package providing `slycode` CLI
-  - Subcommands: workspace, start, stop, service, doctor, skills, sync, update, config, uninstall
-  - `slycode skills list|check|add|reset` for skill management
-  - `slycode config [key] [value]` for slycode.config.js management
-  - `slycode uninstall` for removing services and CLI tools
-  - Platform-specific service management (Linux systemd, macOS launchd, Windows Task Scheduler)
-  - Templates in `templates/` use flat canonical store layout, includes `tutorial-project/` template
-  - `files` in package.json: `bin/`, `data/`, `lib/`, `dist/`, `templates/`. Dependencies include `multer` (bridge image upload).
-  - Default host: `127.0.0.1` (configurable via slycode.config.js)
-- `packages/create-slycode/` (v0.1.0) — Scaffold tool for initializing new SlyCode workspaces
-  - Exports `create-slycode` CLI command
-  - Setup wizard prompts for timezone (auto-detects system TZ, writes `TZ=` to .env for cron scheduling)
-  - Seeds `providers.json` and `sly-actions.json` from package templates during workspace creation
-  - Tutorial content seeded into workspace root via `seedTutorialWorkspaceContent()` (not a separate `slycode_tutorial/` subdirectory)
-  - Registry seeds workspace root as default project (id: `slycode`, path: workspace dir)
-  - Kanban seed uses correct stage-based format (`project_id`, `stages`, `last_updated`)
-- `build/build-package.ts` — Full build pipeline: builds services, syncs store→updates, copies templates, scaffold-templates/, store/, and store/actions/ to templates/store/actions/ for scaffold seeding. Preserves tutorial-project template during wipe/rebuild.
-- `build/sync-updates.ts` — Sync manifest skills from store/ to updates/ (enforces manifest as authority)
-- `build/store-manifest.js` — Curated list of skills included in package distribution
-
-### slycode CLI new subcommands
-- `slycode sync` — Refresh workspace updates/ from package templates
-- `slycode update` — Platform-aware restart (systemd/launchd/Windows Task Scheduler/background)
-- `slycode start` — Auto-refreshes updates + npm version check (3s timeout). Passes workspace as `cwd` to spawned services and sets `SLYCODE_HOME` env var (fixes prod path resolution where Next.js server.js does `process.chdir(__dirname)`).
-
-## 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/templates/updates/skills/context-priming/references/references/areas/skills.md

@@ -1,196 +0,0 @@
-# Skills & Infrastructure
-
-Updated: 2026-03-13
-
-## Overview
-
-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 (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 (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 (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
-- `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
-- `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 (v0.1.0): `slycode` CLI with workspace, start, stop, service, doctor, skills, sync, update, config, uninstall subcommands
-- `packages/create-slycode/` - Scaffold tool: `create-slycode` for initializing new workspaces. Setup wizard prompts for timezone (auto-detects via `Intl.DateTimeFormat`, writes `TZ=` to .env for cron scheduling). 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`).
-- Templates removed from `packages/slycode/templates/` (skills, actions, tutorial-project all deleted — content now delivered via build pipeline and updates/ only)
-- `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/` - 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-049)
-- `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
-```
-
-All user-invocable operations are now skills (no separate commands directory).
-
-## 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)
-
-- **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**: 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/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
-- 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
-
-- `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 skill, creates a new skill in .claude/skills/
-- Creating new agent → .claude/agents/
-- 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/, 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/references/areas/terminal-bridge.md

@@ -1,263 +0,0 @@
-# Terminal Bridge
-
-Updated: 2026-03-12
-
-## 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, 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, instruction file check/create
-- `bridge/src/pty-handler.ts` - PTY process wrapper, output buffering
-- `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` - Provider-agnostic session ID detection (Claude/Codex/Gemini) with unified dispatchers
-- `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
-### Web Components
-- `web/src/components/Terminal.tsx` - xterm.js terminal, SSE via ConnectionManager, resize broadcast with echo-loop suppression
-- `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.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, 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)
-- `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, group, status (running|stopped|detached|creating), pid, connectedClients,
-  hasHistory, resumed, lastActive, lastOutputAt?,
-  claudeSessionId?, provider?, skipPermissions?
-}
-
-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,
-  activityStartedAt?, lastOutputSnippet?
-}
-
-ActivityTransition {
-  timestamp: string;
-  became: 'active' | 'inactive';
-  lastOutputAt: string;
-  activityStartedAt: string;
-  outputAgeMs: number;
-  triggerSnippet: string;
-  triggerRawHex: string;
-  triggerDataLength: 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;
-  fresh?: boolean;
-  idleTimeout?: number;
-  prompt?: string;
-  createInstructionFile?: boolean; // Opt-in: copy sibling instruction file if missing
-}
-
-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? },
-  instructionFile?: string,    // e.g. "CLAUDE.md" for Claude, "AGENTS.md" for Codex
-  altInstructionFile?: string  // e.g. "CODEX.md" for Codex (provider-specific alt)
-}
-
-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
-
-- **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
-
-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
-- `action-assistant` - Terminal in SlyActionConfigModal
-
-## 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 [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)
-- 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`
-- **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"`
-
-### 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
-- 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 }`
-- 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 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 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.
-
-## API Endpoints
-
-- `GET /sessions` - List all sessions
-- `GET /sessions/:name` - Get session info
-- `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
-
-- 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
-- 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