@slycode/slycode 0.1.1 → 0.1.2

package/templates/tutorial-project/.agents/skills/context-priming/references/area-index.md

@@ -0,0 +1,101 @@
+# Area Index
+
+Updated: 2026-02-14
+
+## Areas
+
+### web-frontend
+- path: areas/web-frontend.md
+- updated: 2026-02-14
+- load-when: dashboard, kanban, cards, modal, UI components, drag-drop, project page, checklist, command config, health monitor, reconnection, toolkit, assets, search, scaffolding, activity feed, keyboard shortcuts, health score, tab sync, theme, design system, colors, gradient, texture, grain, noise, logo, neon, glow, blend mode, terminal styling, dark mode, light mode, provider selector, provider dropdown
+- notes:
+  - CardModal tabs are dynamic: Details, Design?, Feature?, Test?, Checklist?, Terminal
+  - Terminal tab auto-connects when session is running
+  - HealthMonitor in ProjectHeader shows CPU/memory/terminals, expands on hover
+  - ConnectionManager handles SSE reconnection with Page Visibility API
+  - Cards with active work show pulsing green glow (active-glow-card CSS class)
+  - Commands use startupCommands (session start) and activeCommands (toolbar)
+  - ToolkitTab manages cross-project asset deployment (commands/skills/agents)
+  - HealthDot on ProjectCard shows 0-100 score (green/amber/red)
+  - paths.ts replaces all hardcoded paths with dynamic resolution
+  - CardModal has edit session protection (2000ms grace period, last-known-value tracking)
+  - Provider selector in ClaudeTerminalPanel pre-fills from stage defaults via /api/providers
+  - CardModal detects existing session's provider from session name (projectId:provider:card:cardId)
+  - NEVER use dark-end color scales for dark mode vibrant colors — use bright color at low opacity
+  - soft-light blend produces warm/red cast on dark backgrounds — use screen or overlay instead
+  - drop-shadow filters create rectangular glow on images with opaque backgrounds — incompatible with mix-blend-mode logo transparency
+  - Gradient direction: always left (vibrant) to right (soft), never center-out
+  - Texture is three layers: fine grain + perlin noise + depth highlight — each with separate light/dark tuning
+
+### terminal-bridge
+- path: areas/terminal-bridge.md
+- updated: 2026-02-14
+- load-when: terminal, Claude panel, xterm, bridge, pty, session, websocket, SSE, spawn, terminal class, security, stats, activity log, stop-all, provider, providers.json, multi-provider, gemini, codex, claude, resume, skip-permissions, YOLO
+- notes:
+  - Pass prompts as positional args to Claude CLI, NOT -p flag (-p is print mode)
+  - Bridge binds to localhost by default (not 0.0.0.0) for security
+  - Command whitelist in bridge-config.json (only 'claude' and 'bash' allowed)
+  - CWD validated before spawning PTY (must be absolute path)
+  - Activity tracking: lastOutputAt timestamp, 2s threshold for "active" status
+  - Grace period (5s) after disconnect prevents idle timeout race condition
+  - ActivityTransition logging with trigger details for debugging phantom blips
+  - Atomic state saves (temp file + rename) prevent data corruption
+  - POST /sessions/:name/stop sends Escape key (soft stop) vs DELETE (kill)
+  - Session names now include provider: {projectId}:{provider}:card:{cardId} (with legacy fallback)
+  - provider-utils.ts builds command args from providers.json config (flag vs subcommand resume)
+  - GUID detection only for Claude; Gemini/Codex use --resume --last
+
+### claude-actions
+- path: areas/claude-actions.md
+- updated: 2026-02-09
+- load-when: actions, prompts, templates, context injection, commands, visibility, command config
+- notes:
+  - Unified command system in data/commands.json (v2.0)
+  - No 'type' field on Command - filtering by class + sessionState
+  - getStartupCommands() for session start, getActiveCommands() for toolbar
+  - Session states: new, resume, active, any
+  - Groups: Card Actions, Session, Project, Utilities, Problems, Command Assistant
+  - Update Priming and Chore Plan are newer commands
+
+### messaging
+- path: areas/messaging.md
+- updated: 2026-02-14
+- load-when: telegram, messaging, voice, TTS, STT, speech, channel, bot, ElevenLabs, Whisper, voice swap, stop command, response mode, tone, command filter, provider, permission mismatch
+- notes:
+  - Channel abstraction in types.ts, Telegram is first implementation
+  - Voice pipeline: Whisper STT → ElevenLabs v3 TTS with [audio tags]
+  - sendTextRaw() bypasses Markdown (preserves [brackets] for voice tags)
+  - Chat actions for status indicators (record_voice, typing, upload_voice)
+  - Voice search queries both personal (/v2/voices) and community (/v1/shared-voices)
+  - State persisted in messaging-state.json (project + voice + responseMode + voiceTone)
+  - CLI tool used by messaging skill to send outbound messages
+  - "stop" text intercepted and sends Escape to active session (not forwarded as prompt)
+  - command-filter.ts provides context-aware command filtering with template resolution
+  - kanban-client.ts gives direct access to project card data for prompts
+  - Messaging always forces skipPermissions: true (remote can't approve prompts)
+  - Permission mismatch detection when session started from web UI without skip-permissions
+  - State persists selectedProvider alongside project/voice/mode/tone
+
+### skills
+- path: areas/skills.md
+- updated: 2026-02-09
+- load-when: skills, commands, agents, hooks, slash commands, SKILL.md, scaffolding
+- notes:
+  - Skills live in .claude/skills/, commands in .claude/commands/, agents in .claude/agents/
+  - 6 skills: context-priming, interactive-explainer, skill-creator, messaging, claude-code-docs-maintainer, kanban
+  - 1 agent: doc-updater
+  - 10 commands: checkpoint, feature, chore, implement, design, doc-discovery, doc-update, reference-fetch, create-command, problem_summary
+  - Scaffold templates in data/scaffold-templates/
+
+### scripts-deployment
+- path: areas/scripts-deployment.md
+- updated: 2026-02-10
+- load-when: setup, scripts, deployment, start, stop, restart, dev, ports, service, systemd, launchd, linger, PID, zombie, sly-start, sly-stop, sly-dev, sly-restart, setup.sh, .env, environment, production, build, tmux, bridge-sessions, XDG_RUNTIME_DIR
+- notes:
+  - Two port ranges: dev (3003/4/5) and prod (7591/2/3 = "sly" on keypad)
+  - Stop by port, NOT PID files (npm spawns children, PIDs go stale)
+  - bridge-sessions.json is critical — crash on read errors, never silently wipe
+  - XDG_RUNTIME_DIR must be set for systemctl --user in code-server
+  - Build every time on prod start — no stale build risk
+  - sly-dev.sh tmux hook calls sly-stop.sh on session close to prevent zombies
+  - Global CLIs: sly-kanban, sly-messaging, sly-scaffold (symlinked to ~/bin)

package/templates/tutorial-project/.agents/skills/context-priming/references/areas/claude-actions.md

@@ -0,0 +1,120 @@
+# Claude Actions (Commands)
+
+Updated: 2026-02-09
+
+## Overview
+
+Unified command system for Claude terminals. Commands are defined in `data/sly-actions.json` with visibility controlled by terminal classes and session state. Commands are split into **startup commands** (shown before/during session start) and **active commands** (shown in toolbar while running).
+
+## Key Files
+
+- `data/sly-actions.json` - Unified command definitions (prompts, visibility, groups)
+- `documentation/terminal-classes.json` - Terminal class definitions
+- `web/src/lib/sly-actions.ts` - getStartupActions(), getActiveActions(), renderTemplate(), buildPrompt()
+- `web/src/lib/types.ts` - Command, CommandsConfig, TerminalClass types
+- `web/src/app/api/commands/route.ts` - CRUD for sly-actions.json
+- `web/src/app/api/commands/stream/route.ts` - SSE for file change detection
+- `web/src/app/api/terminal-classes/route.ts` - Serves terminal-classes.json
+- `web/src/app/api/claude-actions/route.ts` - Serves commands in ClaudeActionsConfig format
+
+## Data Models
+
+```typescript
+// Unified command (no 'type' field - filtering by class + sessionState)
+Command {
+  label: string;
+  description: string;
+  group?: string;           // Card Actions, Session, Project, Utilities, Problems
+  cardTypes?: string[];     // Filter: feature/bug/chore
+  prompt: string;           // Template with {{placeholders}}
+  visibleIn: {
+    classes: string[];      // Terminal classes where this appears
+    projects: string[];     // Specific projects (if scope='specific')
+  };
+  scope: 'global' | 'specific';
+  sessionState: 'new' | 'resume' | 'active' | 'any';
+}
+
+// Internal format used by ClaudeTerminalPanel
+ClaudeCommand {
+  id: string;
+  label: string;
+  description: string;
+  group?: string;
+  cardTypes?: string[];
+  prompt: string;
+  visibleIn: { classes: string[]; projects: string[] };
+  scope: 'global' | 'specific';
+  sessionState: 'new' | 'resume' | 'active' | 'any';
+}
+
+// Config format served by /api/claude-actions
+ClaudeActionsConfig {
+  version: string;
+  contextTemplate: { card: string; global: string };
+  commands: ClaudeCommand[];
+}
+```
+
+## Key Functions
+
+- `getStartupActions(commands, terminalClass, hasHistory)` - Commands for session start (new/resume/any states)
+- `getActiveActions(commands, terminalClass)` - Commands for toolbar while running (active/any states)
+- `renderTemplate(template, context)` - Handles {{var}}, {{#if}}, {{#each}}
+- `buildPrompt(contextTemplate, actionPrompt, context)` - Combines context + task sections
+
+## Template Syntax
+
+- `{{var}}` - Simple substitution
+- `{{obj.prop}}` - Nested property access (e.g., `{{card.title}}`)
+- `{{#if var}}...{{/if}}` - Conditional block
+- `{{#each arr}}...{{this}}...{{/each}}` - Array iteration
+
+## Context Objects
+
+Card context: `{ project, projectPath, card, stage, problems[] }`
+Global context: `{ project, projectPath }`
+
+## Command Groups
+
+- **Card Actions** - Stage-specific workflows (Onboard, Design Doc, Implement, Debug, etc.)
+- **Session** - Continue, Summarize (for resume state)
+- **Project** - Explore, New Card (for project-level terminals)
+- **Utilities** - Compact, Clear, Checkpoint, Context, Show Card
+- **Problems** - Log Problem, Triage Problems, Fix Issues
+- **Action Assistant** - Configure, Update Priming (for action-assistant terminal class)
+
+### Additional Commands
+- **Chore Plan** - Create maintenance/bug fix plan from card
+
+## Session States
+
+- `new` - No history, shown for fresh start
+- `resume` - Has history, shown when resuming (Continue, Summarize)
+- `active` - Shown in toolbar when terminal is running
+- `any` - Always shown regardless of state
+
+## Command Flow
+
+1. **No session**: Show `startupCommands` (new + any states) as buttons
+2. **Has history**: Show Resume button + `startupCommands` (new + any) for fresh start options
+3. **Running**: Show `activeCommands` (active + any states) in footer toolbar
+
+## Patterns & Invariants
+
+- Commands filtered by: terminalClass + sessionState
+- Startup commands: sessionState in ['new', 'resume', 'any'] based on hasHistory
+- Active commands: sessionState in ['active', 'any']
+- MAX_VISIBLE_ACTIONS = 6, overflow goes to "..." menu
+- Context button (id: 'context') appends card.areas to command
+- Show Card button (id: 'show-card') appends cardId
+- Shift+click on active command inserts without submitting
+
+## When to Expand
+
+- Adding new commands → data/sly-actions.json
+- Changing filter logic → getStartupActions/getActiveActions in sly-actions.ts
+- Template issues → renderTemplate() in sly-actions.ts
+- UI for commands → ClaudeTerminalPanel.tsx
+- Terminal class definitions → documentation/terminal-classes.json
+- Command configuration UI → SlyActionConfigModal.tsx

package/templates/tutorial-project/.agents/skills/context-priming/references/areas/messaging.md

@@ -0,0 +1,177 @@
+# 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/templates/tutorial-project/.agents/skills/context-priming/references/areas/scripts-deployment.md

@@ -0,0 +1,138 @@
+# 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/templates/tutorial-project/.agents/skills/context-priming/references/areas/skills.md

@@ -0,0 +1,135 @@
+# Skills & Infrastructure
+
+Updated: 2026-02-09
+
+## Overview
+
+ClaudeMaster 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