@slycode/slycode 0.1.14 → 0.1.16

package/templates/updates/skills/context-priming/references/areas/claude-actions.md

@@ -1,120 +0,0 @@
-# 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/updates/skills/context-priming/references/references/area-index.md

@@ -1,152 +0,0 @@
-# Area Index
-
-Updated: 2026-03-13
-
-## Areas
-
-### web-frontend
-- path: areas/web-frontend.md
-- updated: 2026-03-13
-- load-when: dashboard, kanban, cards, modal, UI components, drag-drop, project page, checklist, action config, health monitor, reconnection, cli assets, 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 button, store, updates, update delivery, diff, assistant, asset creation, terminal prompt, pushToTerminal, Code Den, StoreView, UpdatesView, SkillDiffViewer, AssetAssistant, mcp config, automation, automations, scheduler, cron, cron-utils, timezone, TZ, agent notes, notes, summary note, wide viewport, 4K, copyright, favicon, context menu, right-click, confirm dialog, CliAssetsTab, project reorder, displayOrder, version check, VersionUpdateToast, AddProjectModal, scaffold wizard, provider overlay, placement, classAssignments, voice, voice input, voice recording, transcribe, Whisper, STT, VoiceControlBar, VoiceSettings, VoiceContext, VoiceClaimant, FloatingVoiceWidget, ThemeToggle, settings, image paste, screenshot, clipboard, DashboardData, chevron, hazard stripe, loadParentEnv, shadow, shadow depth, elevation, shadow-surface, shadow-card, shadow-overlay, lane texture, lane-texture, inset shadow, card number, glow-color, type emoji, glassmorphic, compact card, JetBrains Mono, priority glow, responsive, mobile, touch, fullscreen, snap-scroll, scrollbar-hide, import preview, ImportDialog, SKILL.md-only, skillMainOnly, activity ring, DEV_HOSTNAME, allowedDevOrigins, version display, getRepoRoot, getParentEnv, MASTER_PROJECT_ID, workspace ID, basename, fetchWithTimeout, checkSessionAlive, liveness check, soft failure, hard failure, activity detection, fresh session, resume session, action-scanner, ActionUpdatesModal, action updates, action cache, invalidateActionsCache, instruction file, instruction file warning, resize broadcast, resize sync, grace window, nextRun, getNextRun, HMR, globalThis, per-card provider
-- notes:
-  - CardModal tabs: Details, Notes?, Design?, Feature?, Test?, Checklist?, Terminal. Edit session protection (2000ms grace). suppressAutoTerminal from context menu. Fullscreen on mobile (rounded-none, h-full), windowed on desktop (lg:rounded-xl, lg:max-w-4xl). Horizontal tab scroll with scrollbar-hide on mobile.
-  - Automation uses card description as prompt. Run Now button with feedback. Orange theme. onActiveAutomationsChange drives header pulse. Timezone badge in AutomationsScreen header + AutomationConfig one-shot picker. Automation safeguards: cannot archive automation cards (CLI + web), cannot enable automation on archived cards.
-  - Surgical save: changedCardIds in POST merges against disk. last_modified_by tracks source (web/cli/agent).
-  - Right-click context menu on cards: move stage, set priority, copy title/ID/desc, archive, delete. Portal z-51/52, lane-colored accent bars.
-  - Z-index layers: BackdropModal z-50, ContextMenu z-51, Submenu z-52, ConfirmDialog z-60
-  - Provider button group pre-fills from stage defaults. Session name: {projectId}:{provider}:card:{cardId}
-  - Store canonical flat layout (store/skills/, store/actions/, store/agents/). UpdatesView: accept/dismiss/preview workflow. CliAssetsTab (was ToolkitTab). ImportDialog for skill imports: SKILL.md-only default, full folder option. Preview API lists files before import.
-  - Action updates: ActionUpdatesModal for accept/dismiss/preview with diff viewer. ProjectHeader polls for actionEntries count, shows badge on Actions button. SlyActionConfigModal shows "Updates" tab when available. Cache invalidated via /api/sly-actions/invalidate on modal close.
-  - action-scanner.ts: scans store/actions/*.md, parses YAML frontmatter, assembles SlyActionsConfig with 30s cache, writes back from config (reverse-engineers classes from classAssignments), content-hash based update scanning, additive class merge on accept.
-  - Dashboard project drag-and-drop reordering with displayOrder field. AddProjectModal wizard: details → providers → review → creating → summary.
-  - VersionUpdateToast: npm version polling (6-hour interval, daily dismiss, bottom-left toast).
-  - Scheduler auto-starts via instrumentation.ts (30s), 60s grace window prevents stale ticks on re-enable. HMR-safe via globalThis state/timer. pushToTerminal() dispatches to GlobalClaudePanel.
-  - Single `actions` prop on ClaudeTerminalPanel, split by placement locally (startup/toolbar/both). CardModal and GlobalClaudePanel each call one getActionsForClass().
-  - SlyActionConfigModal: two-tab layout — Commands tab (edit definitions + placement dropdown) and Classes tab (assign + reorder commands per terminal class). Voice-enabled assistant terminal, Escape passes through to terminal when expanded.
-  - Voice: global VoiceContext (useVoice() hook). Claim system: CardModal/GlobalClaudePanel claim → release. FloatingVoiceWidget when unclaimed. VoiceControlBar, MediaRecorder → /api/transcribe → insert at claimant target. ThemeToggle for light/dark in Dashboard.
-  - Image paste: Terminal.tsx intercepts Ctrl+V at keydown (before xterm), clipboard.read() for images → bridge /sessions/:name/image → inject `[Screenshot: ...]` into PTY. Screenshot toast overlay on ClaudeTerminalPanel.
-  - Path resolution centralized: getSlycodeRoot() (workspace) + getPackageDir() (dev: repo root, prod: node_modules/slycode/dist/). All API routes use these — no local getRepoRoot(). CLI assets import/sync use registry.ts getRepoRoot() instead of hardcoded project lookup.
-  - next.config.ts: getParentEnv() reads DEV_HOSTNAME from parent .env for allowedDevOrigins (no hardcoded hostnames). Dashboard footer shows slycode version from /api/version-check with clickable slycode.ai link.
-  - Scrubbed hardcoded project names: asset-scanner.ts uses MASTER_PROJECT_ID (path.basename), kanban-paths.ts derives workspace ID with underscore→hyphen normalization. paths.ts removed legacy root env var fallback (SLYCODE_HOME → cwd only).
-  - NEVER use dark-end color scales for vibrant dark mode — use bright color at low opacity instead
-  - Shadow depth system: 3 CSS custom property tiers (--shadow-surface, --shadow-card, --shadow-overlay) with light/dark variants. All neon-pulse keyframes layer glow on top of shadow vars. CardModal uses shadow-(--shadow-overlay). KanbanColumn wrappers use lightweight shadow.
-  - Texture: three layers (grain + perlin + depth) + lane-texture (18px grid on column card areas) + `.light-clean` suppression (hides grain/depth on headers in light mode). soft-light → warm cast on dark — use screen. drop-shadow → rectangular glow with blend-mode logos.
-  - Global terminal rebranded from neon-orange to neon-blue (steely blue #2490b5 in light mode). All glow effects have separate light-mode keyframes for visibility. ClaudeTerminalPanel buttons are neon-blue.
-  - KanbanColumn: light mode flat solid bg (no gradients), thicker borders (3px), neutral text colors (void-500/void-600). Inset shadows on headers (color-matched per lane). Header text has drop-shadow for legibility.
-  - KanbanCardItem: glassmorphism (bg-white/40 + backdrop-blur, dark: bg-[#20232a]/55), priority-colored left border + hover inset glow (--glow-color CSS var), card numbers (#0001 format, JetBrains Mono), type emojis replace color dots, compact mode for done column. Session status: green ping (running), orange (paused), grey (none).
-  - Voice-aware click-outside: GlobalClaudePanel and SlyActionConfigModal won't close while voice is recording/transcribing.
-  - Scheduler timezone-aware (TZ env var). loadParentEnv() reads .env from workspace root (Next.js only loads web/.env). Always recalculates nextRun for accurate countdowns. Automation run header: === AUTOMATION RUN === with time, card, trigger (scheduled with cron description / manual), last run + relative time.
-  - cronToHumanReadable() in cron-utils.ts (shared by AutomationConfig, AutomationsScreen). getNextRunISO() removed — all nextRun calculation now server-side via scheduler.ts getNextRun(). Kanban GET API dynamically computes nextRun for all enabled recurring cards. Timezone abbreviation appended to time descriptions.
-  - AutomationsScreen redesigned: max-w-5xl centered, 2-col grid (not 3), cards have chevron texture + hazard stripe + orange left border. Large countdown timers (text-2xl), "idle" label. Collapsible tag groups via `<details>`. New CSS: `.automation-chevron`, `.hazard-stripe` + muted variants.
-  - AgentNote extended: summary?, summarizedCount?, dateRange? for note summarization. Amber "Summary" badge in CardModal notes tab.
-  - Responsive mobile: CardModal fullscreen on mobile, GlobalClaudePanel fullscreen when expanded (h-svh w-screen on mobile), HealthMonitor click-to-toggle (was hover), Terminal touch-scroll + debounced resize (150ms), ProjectHeader mobile search overlay + hidden Actions, KanbanColumn snap-scroll (85vw on mobile). `.scrollbar-hide` CSS utility. All header buttons min-h/w-[44px] touch targets.
-  - Activity ring: uses isActive (not status=running) for session detection. Global terminal sessions included in counts.
-  - Scheduler split fresh/resume: fresh uses checkSessionAlive(20s), resume uses waitForActivity()+retry. fetchWithTimeout(10s) on all bridge calls. Soft failure notifications only on hard errors.
-  - Instruction file warning: ClaudeTerminalPanel checks /check-instruction-file on provider/cwd change. Amber warning + opt-out checkbox if missing. createInstructionFile state passed to session creation.
-  - Resize broadcast: Terminal.tsx guards resize POST (visible tabs only), suppressResizePost prevents echo loop from SSE resize events, skips resize on reconnect.
-
-### terminal-bridge
-- path: areas/terminal-bridge.md
-- updated: 2026-03-12
-- load-when: terminal, terminal 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, session detection, session ID, screenshot, image, image upload, image delivery, group status, action endpoint, relink, race condition, creating, mutex, idempotent, session cleanup, stopped session, heartbeat, instruction file, instructionFile, altInstructionFile, check-instruction-file, ensureInstructionFile, resize broadcast, suppressResizePost
-- notes:
-  - Pass prompts as positional args to Claude CLI, NOT -p flag (-p is print mode)
-  - Bridge: localhost binding, command whitelist (bridge-config.json), CWD validation (absolute path)
-  - Activity tracking: lastOutputAt, 2s threshold. Grace period (5s) prevents idle timeout race. activityStartedAt for debouncing.
-  - Atomic state saves (temp + rename). bridge-sessions.json crash on corrupt, graceful on ENOENT.
-  - Session names: {projectId}:{provider}:card:{cardId} with legacy fallback. POST stop = Escape, DELETE = kill.
-  - provider-utils.ts builds command args from providers.json (flag vs subcommand resume)
-  - Session detection ALL providers: Claude (.jsonl), Codex (rollout UUID), Gemini (chat JSON) — 60s timeout
-  - Prompt works alongside resume: Claude positional, Codex positional after subcommand
-  - claude-utils.ts: provider-agnostic dispatchers (getProviderSessionDir, detectNewProviderSessionId, getMostRecentProviderSessionId)
-  - Image delivery: POST /sessions/:name/image (multer, 10MB), screenshot-utils.ts saves to screenshots/ in session CWD, 10-file retention, auto-.gitignore
-  - ActivityTransition: became (active/inactive), outputAgeMs, triggerSnippet/RawHex/DataLength (flat, not nested)
-  - New endpoints: GET /groups/:group/status, POST /sessions/:name/action (compact/clear/interrupt), POST /sessions/:name/relink
-  - SessionInfo includes group, resumed, lastActive fields
-  - Race condition fix: createSession() uses 'creating' placeholder as mutex. Concurrent requests for same session get 202 (idempotent). guidDetectionCancelled flag prevents stale detection overwrites.
-  - Stopped sessions removed from in-memory map (frees slot), data preserved in persistedState for resume.
-  - SSE heartbeat: 15s comment heartbeats keep connections alive through proxies (Tailscale, Next.js)
-  - Instruction file fallback: checkInstructionFile() priority scan (primary → alt → sibling copy source). ensureInstructionFile() copies on demand. Opt-in via createInstructionFile in CreateSessionRequest. GET /check-instruction-file endpoint for pre-flight checks.
-  - Resize broadcast: PTY resize events sent via SSE to all connected tabs. Terminal.tsx guards resize POST (visible tabs only, suppressResizePost echo-loop prevention, skip on reconnect).
-
-### terminal-actions
-- path: areas/terminal-actions.md
-- updated: 2026-03-10
-- load-when: actions, prompts, templates, context injection, commands, visibility, action config, terminal commands, startup commands, active commands, test review, placement, classAssignments, deep design, deep-design, action scanner, action updates, action .md, store/actions, action frontmatter, action cache, action delivery
-- notes:
-  - Provider-agnostic: same commands across Claude, Codex, Gemini. Individual .md files in store/actions/ (v4.0)
-  - Each action is a .md file with YAML frontmatter (name, version, label, group, placement, classes map) + prompt body
-  - classAssignments assembled at runtime from per-action classes maps, sorted by priority (ascending)
-  - Context templates hardcoded in sly-actions.ts (no longer in JSON config)
-  - action-scanner.ts: parse, cache (30s), assemble config, write back, update scanning (content-hash), accept with additive class merge
-  - messaging/sly-action-filter.ts has duplicated YAML parser + 30s cache (reads store/actions/ directly)
-  - Action update delivery: updates/actions/ → content-hash diff → accept with class merge → store/actions/
-  - ActionUpdatesModal.tsx for accept/dismiss/preview. ProjectHeader polls for update count badge.
-  - SlyActionConfigModal shows "Updates" tab when action updates available
-  - Groups: Card Actions (14), Session, Project, Utilities, Action Assistant (no Problems group)
-  - Deep Design: 4-phase workflow (design doc → parallel analysis agents → synthesis → Q&A). 6 optional agent perspectives.
-  - Test Review: interactive testing-lane with checklist assessment, area priming, max 3 questions/round
-  - Organise Backlog: `kanban board` snapshot + `kanban reorder` for reprioritisation
-
-### messaging
-- path: areas/messaging.md
-- updated: 2026-03-13
-- load-when: telegram, messaging, voice, TTS, STT, speech, channel, bot, ElevenLabs, Whisper, whisper.cpp, local STT, STT_BACKEND, voice swap, stop command, response mode, tone, action filter, provider, provider resolution, bridge provider, explicit session, default provider, PROVIDER_LABELS, permission mismatch, /search, /provider, /sly, /switch, /global, /project, card search, photo, image, album, navigation, target, inline keyboard, callback, instruction file, ifc_, pre-flight, PendingInstructionFileConfirm
-- notes:
-  - Channel interface: onText/onVoice/onPhoto/onCommand + sendText/sendTextRaw/sendVoice/sendInlineKeyboard/setPersistentKeyboard/onCallback
-  - Navigation model: three-level targets (global/project/card) via /switch command with inline keyboards
-  - Bot commands: /start, /switch, /global, /project, /search, /sly, /status, /provider, /voice, /mode, /tone
-  - Callback prefixes: sw_ (switch), qc_ (quick card), cfg_ (config), perm_ (permissions), mode_, tone_
-  - State: messaging-state.json (targetType, projectId, cardId, cardStage, provider, voice, responseMode, voiceTone)
-  - Voice: Dual-backend STT (OpenAI Whisper or local whisper.cpp via STT_BACKEND env var) → ElevenLabs v3 TTS with [audio tags]. "stop" intercepted → Escape to session.
-  - skipPermissions always true. Permission mismatch detection for web-started sessions.
-  - sly-action-filter.ts: v3 classAssignments-based filtering. kanban-client.ts: card data, searchCards
-  - Photo albums batched via media_group_id (2s window). BridgeClient.sendImage() → bridge screenshot
-  - Persistent keyboard: [['/switch', '/search'], ['/provider', '/status'], ['/voice', '/tone'], ['/mode', '/sly']]
-  - Session names: global:{provider}:global, {projectId}:{provider}:global, {projectId}:{provider}:card:{cardId}
-  - Provider auto-resolution: resolveProviderFromBridge() / resolveProjectProviderFromBridge() pick provider from most recent bridge session. hasExplicitSession() determines default vs explicit. Navigation commands (sw_, /global, /project) auto-resolve provider. cfg_ callback updates providers.json global default when no explicit session.
-  - Instruction file pre-flight: checkInstructionFilePreFlight() checks before new session creation (text/voice/photo). Shows ifc_ inline buttons if needed. PendingInstructionFileConfirm stored in StateManager (ephemeral). BridgeClient.checkInstructionFile() + createInstructionFile param on ensureSession/sendMessage.
-
-### skills
-- path: areas/skills.md
-- updated: 2026-03-13
-- load-when: skills, commands, agents, hooks, slash commands, SKILL.md, scaffolding, store, cross-provider, convert-asset, notes, notes summarize, automation, kanban CLI, last_modified_by, updates, update delivery, npm, packages, slycode CLI, migrate, board, reorder, build pipeline, sync-updates, store-manifest, provider overlay, base-instructions, slycode config, slycode uninstall, tutorial project, card number, nextCardNumber, licensing, BUSL, open-core, skillMainOnly, STT_BACKEND, WHISPER_CLI_PATH, WHISPER_MODEL_PATH
-- notes:
-  - ALL commands converted to skills. 17 skills + 1 agent (doc-updater) + 1 dummy skill (inert test). .claude/commands/ removed. Licensed under BUSL-1.1 (open-core).
-  - Store: 17 canonical skills (store/skills/) + actions (store/actions/*.md). Flat layout, no provider subdirectories.
-  - Update delivery: updates/ → accept → store/ (with backup) → deploy to projects. Actions use content-hash comparison + additive class merge.
-  - NPM: packages/slycode/ (CLI, 11 subcommands incl config + uninstall) + packages/create-slycode/ (scaffold). .agents/skills/ for Codex format.
-  - kanban.js: board, reorder, notes (add/list/search/edit/delete/clear/oldest/summarize), automation subcommands. stamps last_modified_by/source on writes. Notes: 100 hard cap, 30 soft suggestion threshold, summarize replaces oldest N with summary note. Archive safeguard: automation cards cannot be archived. Sequential card numbers: ensureCardNumbers() auto-backfills on first write, nextCardNumber tracked on kanban root. Kanban skill v1.4.0: multiline description example in docs. `automation enable` recalculates nextRun via croner.
-  - Scaffold: multi-provider, tutorial content seeded into workspace root (not separate slycode_tutorial/ subdirectory). Kanban seed uses stage-based format. Clean output: suppresses zero-count lines, reports new vs existing doc dirs.
-  - Build pipeline: build-package.ts → sync-updates.ts (skills + actions) → copy scaffold-templates/ + store/ + updates/actions/ to dist/. Templates (skills, actions, tutorial-project) removed from packages/slycode/templates/ — build pipeline is sole delivery mechanism.
-  - Hooks: useSlyActionsConfig.ts (not useCommandsConfig.ts)
-
-### feature-guide
-- path: areas/feature-guide.md
-- updated: 2026-03-13
-
-- load-when: feature guide, feature reference, full scope, system overview, product overview, comprehensive reference, all features, complete reference, deep dive features, product messaging, value proposition, USP, positioning, user story, what is slycode, why slycode, target audience, marketing, website copy, README copy, onboarding copy, pricing, teams tier, per-card provider selection
-- notes:
-  - Auto-maintained by automation card-1772101929502
-  - Comprehensive reference of every SlyCode feature, function, and behavior
-  - Use when needing full product scope for design docs, comparisons, or thorough analysis
-  - PROTECTED: documentation/features/042_slycode_product_messaging.md is the canonical product messaging framework. It defines SlyCode's positioning, value proposition, messaging pillars, target audience, pricing framing, and proof points. Load this document whenever product identity, messaging, marketing copy, or user-facing language is relevant. Do NOT remove or overwrite this reference during context priming updates.
-
-### scripts-deployment
-- path: areas/scripts-deployment.md
-- updated: 2026-03-05
-- 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, build tools, gcc, npm, packages, slycode, create-slycode, migrate, build-package, sync-updates, store-manifest, SLYCODE_HOME, path resolution, getSlycodeRoot, getPackageDir, slycode.config.js, config, uninstall, DEV_HOSTNAME, legacy root env var
-- 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
-  - slycode.config.js: workspace-level config for ports, services, host. Loaded by config/loader.ts.
-  - Default host: 127.0.0.1. Only web binds to config.host; bridge+messaging always localhost.
-  - slycode CLI: 11 subcommands (workspace, start, stop, service, doctor, skills, sync, update, config, uninstall)
-  - 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)
-  - Build: build-package.ts preserves tutorial-project/ template during wipe/rebuild
-  - NPM packages: packages/slycode/ (v0.1.0 CLI) and packages/create-slycode/ (v0.1.0 scaffold)
-  - Tutorial v3: content seeded into workspace root (not slycode_tutorial/ subdir). Registry default project = workspace root.
-  - Path resolution simplified: legacy root env var env var removed. Resolution is now SLYCODE_HOME → cwd fallback only.

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

@@ -1,251 +0,0 @@
-# Messaging Service
-
-Updated: 2026-03-13
-
-## Overview
-
-Multi-channel messaging service for remote AI interaction via Telegram (and future channels). Supports text, voice, and photo messages, target-based navigation (global/project/card), voice swapping, response mode/tone preferences, multi-provider support (Claude/Gemini/Codex), stop command for session interruption, cross-project card search with inline keyboards, permission mismatch detection, instruction file pre-flight checks, 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, callback handlers, stop interception
-- `messaging/src/types.ts` - Channel interface, InlineButton, configs, bridge types, ResponseMode, TargetType, NavigationTarget, InstructionFileCheck, PendingInstructionFileConfirm, BridgeSessionInfo
-- `messaging/src/state.ts` - StateManager: target navigation (global/project/card), voice state, response mode, voice tone, provider selection, persistence. Resolves paths via SLYCODE_HOME env var (messaging-state.json, registry.json).
-- `messaging/src/bridge-client.ts` - BridgeClient: session management, provider-aware creation, permission mismatch detection, instruction file check, activity watching, soft stop, debug logging, background activity monitor, image upload
-
-### Channels
-- `messaging/src/channels/telegram.ts` - TelegramChannel: bot polling, inline buttons, persistent keyboards, callback handlers, chat actions
-
-### Voice Pipeline
-- `messaging/src/stt.ts` - Dual-backend STT: OpenAI Whisper API or local whisper.cpp CLI. SttConfig interface, validateSttConfig() validation. Local backend: ffmpeg OGA→WAV conversion + whisper-cli execution (2min timeout).
-- `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/sly-action-filter.ts` - SlyActionFilter: context-aware action filtering by terminal class, placement, card type (v3 classAssignments-based). Resolves sly-actions.json via SLYCODE_HOME env var.
-- `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 agent 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;
-  onPhoto(handler): void;              // Photo messages (batched for albums)
-  onCommand(command, handler): void;
-  sendText(text): Promise<void>;        // With Markdown
-  sendTextRaw(text): Promise<void>;     // Without Markdown (preserves [brackets])
-  sendVoice(audio: Buffer): Promise<void>;
-  sendInlineKeyboard(text, buttons: InlineButton[][]): Promise<void>;  // Inline buttons with breadcrumb
-  setPersistentKeyboard(buttons: string[][]): Promise<void>;           // Bottom keyboard
-  sendTyping(): Promise<void>;
-  sendChatAction(action): Promise<void>;
-  sendVoiceList?(voices): Promise<void>;     // Optional
-  onVoiceSelect?(handler): void;             // Optional
-  onCallback(prefix, handler): void;         // Inline button callback routing
-  isReady(): boolean;
-}
-
-InlineButton { label: string; callbackData: string; }
-```
-
-## Navigation Model
-
-Three-level target system replacing old project-selection model:
-
-- **Global** - No project context, uses workspace root as CWD
-- **Project** - Project-level terminal (`{projectId}:{provider}:global`)
-- **Card** - Card-specific terminal (`{projectId}:{provider}:card:{cardId}`)
-
-`StateManager.getTarget()` returns `NavigationTarget { type, projectId?, cardId?, stage? }`
-
-## Bot Commands
-
-- `/start` - Help text with available commands
-- `/switch` - Primary navigation: drill-down inline keyboards (global → projects → cards)
-- `/global` - Quick switch to global terminal
-- `/project` - Quick switch from card to project terminal (stays in same project)
-- `/search` - Quick-access: active sessions + recent cards as inline buttons. With args: text search across cards
-- `/sly` - Context-aware sly actions as inline buttons (filtered by terminal class + placement)
-- `/status` - Current target, project, voice, response mode, and tone
-- `/provider` - Provider selection inline keyboard (Claude/Gemini/Codex)
-- `/voice` - Search/swap TTS voices, reset to default
-- `/voice <name>` - Search voices, auto-select on exact match, inline buttons for multiple
-- `/mode` - Response mode selection (text/voice/both)
-- `/tone` - Voice tone customization
-
-## Callback Handlers
-
-- `sw_` - Switch navigation (project/card selection from inline keyboards)
-- `qc_` - Quick card actions (from /search results)
-- `cfg_` - Configuration callbacks
-- `ifc_` - Instruction file confirmation (yes/no for creating missing instruction file)
-- `perm_` - Permission mismatch actions (restart session with correct perms)
-- `mode_` - Response mode selection callbacks
-- `tone_` - Voice tone selection callbacks
-
-## Message Flow
-
-### Inbound (user → agent session)
-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. **Instruction file pre-flight**: if new session would be created, checks bridge for missing instruction file. If needed, shows inline buttons (yes/no). Pending state stored in `StateManager._pendingInstructionFileConfirm` (ephemeral, not persisted). `ifc_yes` callback creates file + delivers original message; `ifc_no` delivers without creating.
-6. BridgeClient.ensureSession() creates/finds session (with selected provider, always skipPermissions, optional createInstructionFile)
-7. If permission mismatch (existing session without skipPermissions), warns user and offers restart
-8. BridgeClient.sendMessage() writes text + CR to PTY
-9. BridgeClient.watchActivity() polls /stats, sends typing while active
-
-### Outbound (agent → user)
-1. Agent 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()
-
-### Photo Messages (user → agent session)
-1. User sends photo(s) on Telegram (single or album)
-2. TelegramChannel downloads largest resolution, batches album photos (2s window via media_group_id)
-3. BridgeClient.sendImage() uploads each photo to bridge `POST /sessions/:name/image`
-4. Bridge saves to `screenshots/` in session CWD, returns filename
-5. Screenshot references (`[Screenshot: screenshots/<filename>]`) + optional caption built into message
-6. Message sent to PTY, activity watched as normal
-
-### 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
-
-- `SlyActionFilter.loadActions()` - Hot-reloads sly-actions.json on each call
-- `SlyActionFilter.filterActions(terminalClass, placement?, cardType?)` - Context-aware filtering via classAssignments lookup
-- `SlyActionFilter.resolveTemplate(prompt, context)` - Template variable resolution
-- `SlyActionFilter.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 sorted by `order` field (used by reorder command), automation cards excluded
-- `KanbanClient.searchCards(projectIds, query, maxResults)` - Text search across cards (title +2, description +1, archived -1)
-- `KanbanClient.getAllCards(projectIds)` - All non-archived, non-automation cards
-- Resolves kanban.json paths per project
-
-## Voice System
-
-- **STT**: Dual-backend via `SttConfig.backend` ('openai' | 'local'). OpenAI Whisper (`whisper-1`) or local whisper.cpp CLI. Backend selected via `STT_BACKEND` env var. Local backend requires `WHISPER_CLI_PATH` and `WHISPER_MODEL_PATH`. `validateSttConfig()` checks env setup before transcription attempts.
-- **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')
-- **Auto-resolution**: Provider auto-resolved on navigation. `resolveProviderFromBridge()` checks bridge for existing card sessions (picks most recently active). `resolveProjectProviderFromBridge()` does the same for project-level sessions. Resolution chain: bridge session → stage default (from providers.json) → global default.
-- `getProviderDefault(stage?)` reads providers.json defaults (stage-specific → global fallback)
-- `updateGlobalProviderDefault(provider)` writes to providers.json when changing provider on a target with no explicit bridge session
-- `hasExplicitSession()` checks whether the current provider was derived from a bridge session vs default. Status/lifecycle messages show "(default)" suffix when no explicit session exists.
-- Shared `PROVIDER_LABELS` constant and `ALL_PROVIDERS` list (no more inline duplicated maps)
-- Session names include provider segment: `{projectId}:{provider}:global` or `{projectId}:{provider}:card:{cardId}`
-- Global target uses `global:{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
-- `BridgeClient.startActivityMonitor()` runs persistent background polling (4s) sending typing indicators when session is active
-- `BridgeClient.checkInstructionFile(provider, cwd)` checks bridge for missing instruction file, returns InstructionFileCheck
-- `BridgeClient.ensureSession()` accepts optional `createInstructionFile` param, passed to bridge session creation
-- `BridgeClient.sendMessage()` accepts optional `createInstructionFile` param, forwarded to ensureSession
-- `BridgeClient.sendImage(name, filePath, cwd?)` uploads image to bridge screenshot endpoint, returns filename
-- `BridgeClient.getActiveCardSessions(projectIds)` returns Set of card IDs with active bridge sessions (for /search quick-access)
-- `BridgeClient.getCardSessionRecency(projectIds)` returns Map of card IDs to lastActive timestamps (for /search recent sorting)
-- Debug logging via `debugLog()` writes to `messaging-debug.log` for session create/send troubleshooting
-- Resume+prompt flow: detects resumed sessions and types prompt via sendInput after delay
-
-## State Persistence
-
-`messaging-state.json` stores:
-- `targetType` - Navigation level: global/project/card
-- `selectedProjectId` - Active project
-- `selectedCardId` - Active card (only with project)
-- `selectedCardStage` - Active card's stage
-- `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
-
-- Path resolution: `SLYCODE_HOME` env var (set by `slycode start`) → `process.cwd()` fallback. All file paths (state, registry, sly-actions) resolve via `getWorkspaceRoot()` helper — no `__dirname`-relative paths (breaks in npm package installs).
-- Chat actions for status: `record_voice` (transcribing), `typing` (processing), `upload_voice` (TTS)
-- Session names include provider and target type: `{projectId}:{provider}:card:{cardId}` or `global:{provider}:global`
-- 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
-- /search quick-access shows active sessions (up to 5) + recent cards sorted by laterDate(session.lastActive, card.updated_at)
-- /search text mode uses kanban-client.searchCards() with scoring (title +2, desc +1, archived -1)
-- /search supports global (multi-project) and single-project scopes with cross-project card switching
-- Persistent keyboard is unified single layout for all contexts: [['/switch', '/search'], ['/provider', '/status'], ['/voice', '/tone'], ['/mode', '/sly']]
-- /provider shows provider inline keyboard (excludes current provider, dynamic from ALL_PROVIDERS). cfg_ callback also updates global default in providers.json when no explicit bridge session exists.
-- Photo albums batched via media_group_id (2s flush window), single photos delivered immediately
-- Photos: download largest resolution, save to temp dir, upload to bridge, inject `[Screenshot: screenshots/<filename>]` into message
-- Instruction file pre-flight: before creating new sessions (text, voice, photo handlers), `checkInstructionFilePreFlight()` checks if provider instruction file is missing. If needed, shows inline buttons and stores pending state (PendingInstructionFileConfirm). `ifc_` callback delivers original message with `createInstructionFile` flag.
-- Callback prefixes route inline button presses: sw_ (switch), qc_ (quick card), cfg_ (config), ifc_ (instruction file confirm), perm_ (permissions), mode_ (mode), tone_ (tone)
-
-## 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 → sly-action-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), index.ts (resolveProviderFromBridge, getProviderDefault, updateGlobalProviderDefault), bridge-client.ts (ensureSession provider param)
-- Permission mismatch → bridge-client.ts ensureSession/sendMessage permissionMismatch detection
-- Photo messages → channels/telegram.ts (photo listener, album batching), index.ts (onPhoto handler), bridge-client.ts (sendImage)
-- Card search → index.ts /search handler, kanban-client.ts searchCards/getAllCards, bridge-client.ts getActiveCardSessions/getCardSessionRecency
-- Navigation → index.ts /switch handler, state.ts target methods, callback handlers (sw_)
-- Instruction file flow → index.ts checkInstructionFilePreFlight(), ifc_ callback, bridge-client.ts checkInstructionFile(), state.ts pending confirm
-- Inline buttons → channels/telegram.ts, types.ts InlineButton, channel.onCallback()