@slycode/slycode 0.1.14 → 0.1.16

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

@@ -1,33 +1,33 @@
 # Messaging Service
 
-Updated: 2026-02-14
+Updated: 2026-03-13
 
 ## 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.
+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, 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
+- `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, chat actions
+- `messaging/src/channels/telegram.ts` - TelegramChannel: bot polling, inline buttons, persistent keyboards, callback handlers, chat actions
 
 ### Voice Pipeline
-- `messaging/src/stt.ts` - Whisper STT via OpenAI API
+- `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/command-filter.ts` - Context-aware command filtering by terminal class, session state, card type
+- `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 Claude skills
+- `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
@@ -44,47 +44,86 @@ Channel {
   stop(): void;
   onText(handler): void;
   onVoice(handler): void;
+  onPhoto(handler): void;              // Photo messages (batched for albums)
   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>;
+  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
+  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 ClaudeMaster 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
-- `/projects` - Inline keyboard for project selection
-- `/select N` - Select project by number
-- `/status` - Current project, voice, response mode, and tone
+- `/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 → Claude)
+### 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. 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]`
+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)
@@ -103,22 +142,24 @@ Channel {
 
 ## 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
+- `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
+- `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**: OpenAI Whisper (`whisper-1`), accepts OGG from Telegram
+- **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
@@ -127,16 +168,34 @@ Channel {
 ## Provider Support
 
 - `StateManager.selectedProvider` - Persisted provider choice (default: 'claude')
-- Session names include provider segment: `{projectId}:{provider}:global`
+- **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
@@ -152,8 +211,9 @@ Projects loaded from `projects/registry.json` at startup.
 
 ## 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: `{projectId}:{provider}:global` (with legacy fallback)
+- 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
@@ -161,6 +221,15 @@ Projects loaded from `projects/registry.json` at startup.
 - 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
 
@@ -170,8 +239,13 @@ Projects loaded from `projects/registry.json` at startup.
 - Bridge routing → bridge-client.ts
 - State persistence → state.ts
 - Telegram-specific behavior → channels/telegram.ts
-- Command filtering → command-filter.ts, kanban-client.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), bridge-client.ts (ensureSession provider param)
+- 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()

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

@@ -1,6 +1,6 @@
 # Scripts & Deployment
 
-Updated: 2026-02-11
+Updated: 2026-03-14
 
 ## Overview
 
@@ -17,6 +17,7 @@ SlyCode has a two-tier deployment model: **dev** (individual services via tmux)
 | `sly-dev.sh` | Tmux session "sly" with three side-by-side panes running `npm run dev` |
 | `kanban.js` | Kanban CLI (standalone Node.js, no build needed) |
 | `scaffold.js` | Project scaffolding CLI (standalone Node.js) |
+| `migrate-store.sh` | Migrate store from provider-split to canonical flat layout |
 
 ## Port Architecture
 
@@ -30,7 +31,7 @@ Two separate port ranges — dev and prod never overlap:
 
 - **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`
+- **Prod ports**: configured in `slycode.config.js` (loaded by `start.ts`), or `.env` fallback, passed as `PORT` env var
 - `BRIDGE_URL` must match bridge port — `sly-start.sh` derives it automatically
 - Next.js reads `PORT` env var natively (no `--port` flag in prod `npm start`)
 
@@ -38,7 +39,7 @@ Two separate port ranges — dev and prod never overlap:
 
 ### Production (`sly-start.sh` / `sly-stop.sh`)
 
-- **Start**: runs `npm start` in background with `nohup` (assumes services are already built via `setup.sh`)
+- **Start**: `slycode start` spawns services with `cwd: workspace` (ensures services inherit correct working directory). Sets `SLYCODE_HOME` env var for prod path resolution.
 - **Stop**: finds PIDs by port (not PID files — those are unreliable with npm subshells), kills process tree with `pkill -P` + `kill`
 - Ports file at `~/.slycode/ports` records which ports were started for stop to read
 - Health check after start: verifies each port is listening
@@ -62,15 +63,16 @@ Two separate port ranges — dev and prod never overlap:
 ## 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
+2. Check build tools (`check_build_tools()` — gcc, make, g++ for node-pty compilation)
+3. Create directories (`~/bin`, `~/.slycode/logs`)
+4. `npm install` in web, bridge, messaging
+5. Build bridge, messaging, web (web last — heaviest, needs most memory)
+6. `chmod +x` on CLI scripts
+7. Symlink CLIs to `~/bin` (sly-kanban, sly-scaffold, sly-messaging)
+8. Update `registry.json` with correct SlyCode path
+9. Copy `.env.example` to `.env` if missing
+10. Prompt: install as system service?
+11. Linux: check linger, offer to enable
 
 **Flags**: `--yes` (non-interactive), `--service` (auto-install services), `--remove-service` (cleanup)
 
@@ -97,9 +99,9 @@ This means `sly-messaging` works regardless of whether you started with `sly-dev
 ## Key Design Decisions
 
 ### No hardcoded paths anywhere
-- Web: `web/src/lib/paths.ts` derives SlyCode root from `process.cwd()` (detects `/web` suffix)
+- Web: `web/src/lib/paths.ts` — centralized `getSlycodeRoot()` (via `SLYCODE_HOME` → cwd fallback) and `getPackageDir()` (detects `node_modules/slycode/dist/` for prod). All 10+ API routes import from paths.ts — no local `getRepoRoot()` helpers. `legacy root env var` env var removed.
 - Bridge: reads `BRIDGE_PORT` from env
-- Messaging: CLI auto-detects service port (dev 3005 / prod 7593) with caching; service reads port from env
+- Messaging: uses `SLYCODE_HOME` env var for workspace resolution (replaces `__dirname`-relative paths that broke in prod npm packages). CLI auto-detects service port (dev 3005 / prod 7593) with caching.
 - Skills: reference `sly-kanban` and `sly-messaging` by global command name, not paths
 - Documentation: uses `<slycode-root>` placeholder instead of absolute paths
 - `registry.json`: `setup.sh` updates the SlyCode path entry at install time
@@ -120,14 +122,57 @@ Code-server terminals don't set `XDG_RUNTIME_DIR`, breaking `systemctl --user`.
 - 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/`.
+Bridge requires absolute path for session `cwd` — no defaults, no relative paths. This ensures the AI CLI associates sessions with the correct project directory.
 
 ## Env Files
 
-- **`.env.example`**: template with all config vars, prod port defaults, placeholder secrets
+- **`.env.example`**: template with all config vars, prod port defaults, placeholder secrets, TZ timezone var, DEV_HOSTNAME (Tailscale hostname for Next.js dev origins)
 - **`.env`**: actual config, created from example by `setup.sh`, gitignored
 - `.env` lives at repo root — messaging loads it via `dotenv`, bridge reads env vars, web gets them via `sly-start.sh` exports
 
+## slycode.config.js
+
+Workspace-level configuration file loaded by `packages/slycode/src/config/loader.ts`:
+
+```js
+module.exports = {
+  ports: { web: 7591, bridge: 7592, messaging: 7593 },
+  services: { web: true, bridge: true, messaging: true },
+  host: '127.0.0.1',  // Only web binds to this; bridge+messaging always localhost
+};
+```
+
+- `slycode config [key] [value]` — View/modify config via CLI
+- Defaults: ports 7591/7592/7593, all services enabled, host `127.0.0.1`
+- Only web binds to `config.host`; bridge and messaging are always `127.0.0.1`
+
+## NPM Distribution (`packages/`)
+
+- `packages/slycode/` (`@slycode/slycode` v0.1.11) — Main npm package providing `slycode` CLI
+  - Subcommands: workspace, start, stop, service, doctor, skills, sync, update, config, uninstall
+  - `slycode skills list|check|add|reset` for skill management
+  - `slycode config [key] [value]` for slycode.config.js management
+  - `slycode uninstall` for removing services and CLI tools
+  - Platform-specific service management (Linux systemd, macOS launchd, Windows Task Scheduler)
+  - Templates in `templates/` use flat canonical store layout, includes `tutorial-project/` template
+  - `files` in package.json: `bin/`, `data/`, `lib/`, `dist/`, `templates/`. Dependencies include `multer` (bridge image upload).
+  - Default host: `127.0.0.1` (configurable via slycode.config.js)
+- `packages/create-slycode/` (`@slycode/create-slycode` v0.1.11) — Scaffold tool for initializing new SlyCode workspaces
+  - Exports `create-slycode` CLI command
+  - Setup wizard prompts for timezone (auto-detects system TZ, writes `TZ=` to .env for cron scheduling)
+  - Seeds `providers.json` and `sly-actions.json` from package templates during workspace creation. System service prompt skipped on Windows.
+  - Tutorial content seeded into workspace root via `seedTutorialWorkspaceContent()` (not a separate `slycode_tutorial/` subdirectory)
+  - Registry seeds workspace root as default project (id: `slycode`, path: workspace dir)
+  - Kanban seed uses correct stage-based format (`project_id`, `stages`, `last_updated`)
+- `build/build-package.ts` — Full build pipeline: builds services, syncs store→updates, copies templates, scaffold-templates/, store/, and store/actions/ to templates/store/actions/ for scaffold seeding. Preserves tutorial-project template during wipe/rebuild.
+- `build/sync-updates.ts` — Sync manifest skills from store/ to updates/ (enforces manifest as authority)
+- `build/store-manifest.js` — Curated list of skills included in package distribution
+
+### slycode CLI new subcommands
+- `slycode sync` — Refresh workspace updates/ from package templates
+- `slycode update` — Platform-aware restart (systemd/launchd/Windows Task Scheduler/background)
+- `slycode start` — Auto-refreshes updates + npm version check (3s timeout). Passes workspace as `cwd` to spawned services and sets `SLYCODE_HOME` env var (fixes prod path resolution where Next.js server.js does `process.chdir(__dirname)`).
+
 ## Related Files
 
 - `documentation/designs/global_cli_setup.md` — full design document

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

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

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

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