@slycode/slycode 0.1.1 → 0.1.2

package/templates/tutorial-project/.claude/skills/checkpoint/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: checkpoint
+version: 1.3.1
+updated: 2026-02-22
+allowed-tools: Bash, Read
+argument-hint: [optional commit message]
+description: Create a git checkpoint of ALL recent changes
+---
+
+# Git Checkpoint Creation
+
+Create a checkpoint commit of ALL uncommitted changes in the repository.
+
+## Process
+
+1. **Check status**: Run `git status --short` to see all changes
+2. **Analyze changes**: For each modified/added file, briefly review what changed using `git diff <file> | head -50` or read new files
+3. **Stage everything**: Run `git add -A` to stage ALL changes (modified, new, and deleted files)
+4. **Write commit message**: Based on analysis, write a clear commit message that:
+   - Has a concise summary line (under 72 chars)
+   - Lists key changes as bullet points
+   - Groups related changes together
+5. **Commit**: Create the commit with the message
+
+## Important Rules
+
+- **Commit EVERYTHING**: Do not selectively pick files. All uncommitted changes should be included.
+- **Analyze first**: Read diffs or file contents to understand what changed before writing the commit message.
+- **Be descriptive**: The commit message should explain WHAT was done, not just list file names.
+- **No AI attribution**: Do not include "Co-Authored-By: Claude" or similar.
+
+## Example Commit Message Format
+
+```
+Summary of changes in imperative mood
+
+- Add feature X with support for Y
+- Fix bug in Z where condition was wrong
+- Update config to enable new option
+- Refactor module for better performance
+```
+
+If an optional message argument is provided, use it as the summary line.

package/templates/tutorial-project/.claude/skills/context-priming/SKILL.md

@@ -0,0 +1,152 @@
+---
+name: context-priming
+version: 1.1.1
+updated: 2026-02-22
+description: Dynamic context provider for codebase knowledge. This skill should be used when working on code, answering questions about architecture, or making changes that require understanding of project structure. Maintains area-specific reference files that are loaded on demand. Self-updating based on observed drift between references and actual code. Load this skill early in work sessions - it contains essential workflow and update protocols.
+---
+
+# Context Priming
+
+Provide dynamic, accurate context about this project's architecture and code. Load knowledge on demand, update when drift is observed, self-improve based on experience.
+
+## When to Invoke
+
+**Load context when:**
+- Starting work requiring codebase knowledge not in current conversation
+- Making changes to unfamiliar areas
+- Answering questions about project architecture or patterns
+- User asks about functionality and current context is insufficient
+
+**Do NOT load when:**
+- Information is clearly present from last 3-5 exchanges
+- Task is trivial and doesn't require architectural understanding
+- Already loaded relevant areas in this session (unless significant time/work has passed)
+
+## How to Use
+
+1. **Load area-index.md first** - understand available areas, their update dates, load-when triggers
+2. **Load relevant area(s)** - based on current task and index guidance
+3. **Follow area's "when to expand"** - each area indicates when to open specific files
+4. **Evaluate freshness** - compare area's `updated` date against today (from system prompt); consider git activity if concerned
+
+## Callouts
+
+Prefix operational updates with `Priming:` to signal skill activity. Keep brief - one line.
+
+**When to call out:**
+- Loading an area: `Priming: Loading backend - API work detected.`
+- Loading multiple: `Priming: This spans backend and database areas, loading both.`
+- Staleness concern: `Priming: backend looks stale (Nov 20), will verify as I go.`
+- Making a note: `Priming: Quick note added - auth order matters.`
+- Skipping load: `Priming: Already have frontend context from earlier.`
+
+**Don't call out:** Every file read, minor internal decisions, routine checks.
+
+## Update Behavior
+
+| Situation | Action |
+|-----------|--------|
+| Loaded info contradicts code in misleading way | Update reference in stride |
+| Minor drift, no practical impact | Let it slide |
+| Unsure if update needed | Note concern, ask at end of task |
+| Multiple areas need restructuring | Consult user before proceeding |
+| New feature added affecting an area | Update area reference |
+| User says "context priming needs to know this" | Capture in relevant area |
+| User says "you should have known this" | Analyze failure, propose fix (see below) |
+
+**Small updates**: Make concisely, in stride, no announcement needed.
+**Large restructuring/defrag**: Consult first. See `references/maintenance.md`.
+
+## "You Should Have Known" Response
+
+When user indicates priming failed:
+
+1. **Identify cause**: Which of these?
+   - Area not loaded when it should have been (bad load-when criteria)
+   - Area loaded but info missing (incomplete reference)
+   - Info existed but outdated (stale reference)
+   - Area doesn't exist (missing area)
+   - Judgment call to skip loading was wrong (bad heuristic)
+
+2. **Propose fix** based on cause:
+   - Content/index updates → do in stride
+   - SKILL.md or maintenance.md changes → explain problem, propose change, await approval
+
+3. **Surface immediately** - don't wait for task end. User will indicate if disruptive.
+
+## Permission Model
+
+| File | Permission |
+|------|------------|
+| references/areas/*.md | Update in stride |
+| references/area-index.md | Update in stride |
+| Add/remove/split areas | Suggest, light confirmation |
+| SKILL.md | Explain, propose, await approval |
+| references/maintenance.md | Explain, propose, await approval |
+
+## Git Usage
+
+Use `git diff` or `git log` sparingly:
+- Before major refactors to verify scope
+- When user questions accuracy of loaded info
+- To check activity since area's last update date when staleness suspected
+
+Not for routine small changes.
+
+## Context Compaction
+
+No direct visibility into remaining context space. When user flags compaction is imminent, or after long exploration sessions: consider if valuable learnings should be captured before context is summarized.
+
+## Self-Improvement
+
+Area notes (in area-index.md) capture learnings:
+- Up to 10 notes per area, quality over quantity
+- Format: actionable guidance ("when X, do Y" or "don't assume Z")
+- Remove notes that no longer apply
+- If skill behavior is flawed, suggest improvement to user
+
+If suggestion timing/frequency becomes disruptive, user will indicate - adjust accordingly.
+
+## Operational Principles
+
+- Concise updates: prefer short phrase tweaks over paragraph additions
+- Don't bloat references - information density is the goal
+- When on fence about loading, lean toward loading
+- Trust the index's load-when triggers; refine them when wrong
+- No hardcoded "status" - freshness is evaluated dynamically
+
+## Skill Location & Cross-Provider Note
+
+**Canonical path (relative to project root):**
+```
+.claude/skills/context-priming/
+├── SKILL.md                        # This file
+├── references/
+│   ├── area-index.md               # Index of all areas (load first)
+│   ├── maintenance.md              # Defrag, pruning, area separation doctrine
+│   └── areas/
+│       └── [name].md               # Deep reference per area
+```
+
+**Resolution order — try these paths in order, use the first that exists:**
+
+1. **Primary:** `<project-root>/.claude/skills/context-priming/` — the canonical, most up-to-date copy. Always check here first.
+2. **Fallback:** The directory containing this SKILL.md (i.e. your own skill folder). If there is no `.claude/` directory in the project, the references were likely copied alongside this file.
+
+This matters when the skill is deployed to another provider (Codex at `.agents/skills/`, Gemini at `.gemini/skills/`). Those folders may contain just this SKILL.md for discovery, with the area files living in `.claude/`. But if the project has no `.claude/` directory at all (e.g. a pure Codex or Gemini project), fall back to reading from your own skill directory.
+
+**Resolved paths (primary):**
+- **Area index:** `<project-root>/.claude/skills/context-priming/references/area-index.md`
+- **Area files:** `<project-root>/.claude/skills/context-priming/references/areas/<name>.md`
+- **Maintenance:** `<project-root>/.claude/skills/context-priming/references/maintenance.md`
+
+**Resolved paths (fallback — relative to this SKILL.md):**
+- **Area index:** `./references/area-index.md`
+- **Area files:** `./references/areas/<name>.md`
+- **Maintenance:** `./references/maintenance.md`
+
+## Files
+
+- `references/area-index.md` - compact index of all areas
+- `references/maintenance.md` - defrag, pruning, area separation doctrine
+- `references/areas/[name].md` - deep reference per area

package/templates/tutorial-project/.claude/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/.claude/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/.claude/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