@slycode/slycode 0.1.0 → 0.1.2

package/templates/tutorial-project/.claude/skills/context-priming/references/areas/terminal-bridge.md

@@ -0,0 +1,232 @@
+# Terminal Bridge
+
+Updated: 2026-02-14
+
+## Overview
+
+PTY bridge server manages AI coding sessions across multiple providers (Claude, Gemini, Codex). Express server spawns/manages PTY processes, streams output via SSE. Provider-agnostic command building via data-driven config (`providers.json`). Includes security hardening (command whitelist, CWD validation, localhost binding), activity tracking with transition logging for debugging, atomic state persistence, bulk session management, and graceful idle timeout handling. React components connect through Next.js API proxy.
+
+## Key Files
+
+### Bridge Server (Node/Express)
+- `bridge/src/index.ts` - Express server entry, routes setup, localhost binding
+- `bridge/src/session-manager.ts` - Session lifecycle, PTY spawning, provider resolution, activity tracking, atomic state saving
+- `bridge/src/provider-utils.ts` - Provider config loading, command building, session detection helpers
+- `bridge/src/pty-handler.ts` - PTY process wrapper, output buffering
+- `bridge/src/api.ts` - REST endpoints for session CRUD, /stats, stop-all, activity-log
+- `bridge/src/websocket.ts` - WebSocket upgrade handling (legacy, SSE preferred)
+- `bridge/src/claude-utils.ts` - Claude session ID detection from ~/.claude/projects/
+- `bridge/src/types.ts` - Session, BridgeConfig, BridgeStats, ActivityTransition, provider interfaces
+
+### Configuration
+- `bridge/bridge-config.json` - Runtime config: allowedCommands (claude, codex, gemini, bash), CORS origins
+- `data/providers.json` - Provider registry: CLI commands, permission flags, resume types, prompt handling, stage defaults
+- `documentation/terminal-classes.json` - Terminal class definitions for command visibility
+- `data/commands.json` - Unified command configuration with visibility per class
+
+### Web Components
+- `web/src/components/Terminal.tsx` - xterm.js terminal, SSE via ConnectionManager
+- `web/src/components/ClaudeTerminalPanel.tsx` - Terminal panel with startupCommands/activeCommands
+- `web/src/components/GlobalClaudePanel.tsx` - Floating panel for project-wide session
+- `web/src/app/api/bridge/[...path]/route.ts` - Next.js proxy to bridge server
+
+## Key Functions
+
+- `SessionManager.createSession()` - Resolves provider, builds command via `buildProviderCommand()`, validates CWD, spawns PTY
+- `SessionManager.resolveSessionName()` - Checks both new (with provider) and legacy session name formats
+- `SessionManager.stopSession()` - Graceful SIGINT, waits for exit
+- `SessionManager.stopAllSessions()` - Bulk stop all running/detached sessions, returns count
+- `SessionManager.getStats()` - Returns BridgeStats with activity info
+- `SessionManager.checkIdleSessions()` - Idle timeout with grace period after disconnect
+- `buildProviderCommand()` - Assembles { command, args } from provider config, handles flag vs subcommand resume
+- `getProvider()` - Loads provider config by ID from providers.json (30s cache)
+- `supportsSessionDetection()` - Check if provider supports GUID-based session detection
+- `Terminal.connectSSE()` - Via ConnectionManager for auto-reconnection
+
+## Data Models
+
+```typescript
+SessionInfo {
+  name, status (running|stopped|detached), pid, connectedClients,
+  hasHistory, claudeSessionId, lastOutputAt,
+  provider?, skipPermissions?,
+  lastOutputSnippet?, lastOutputRawHex?, lastOutputDataLength?
+}
+
+BridgeStats {
+  bridgeTerminals: number;      // Total PTY sessions
+  connectedClients: number;     // Total SSE/WS connections
+  activelyWorking: number;      // Sessions with output in last 2s
+  sessions: SessionActivity[];  // Per-session activity
+}
+
+SessionActivity {
+  name, status, lastOutputAt, isActive
+}
+
+ActivityTransition {
+  timestamp: string;
+  from: string;                 // Previous state
+  to: string;                   // New state
+  lastOutputAt: string;
+  outputAge: number;
+  trigger?: {                   // Debug info for phantom blips
+    snippet: string;
+    hex: string;
+    dataLength: number;
+  }
+}
+
+BridgeConfig {
+  host, port, sessionFile, defaultIdleTimeout, maxSessions
+}
+
+BridgeRuntimeConfig {
+  allowedCommands: string[];    // e.g., ['claude', 'codex', 'gemini', 'bash']
+  cors: { origins: string[] }
+}
+
+CreateSessionRequest {
+  name: string;
+  provider?: string;            // Provider id from providers.json
+  skipPermissions?: boolean;    // Whether to add permission-skip flag
+  command?: string;             // Legacy: direct command (backward compat)
+  cwd: string;
+  prompt?: string;
+  fresh?: boolean;
+}
+
+PersistedSession {
+  claudeSessionId?, cwd, createdAt, lastActive,
+  provider?: string;            // Defaults to 'claude' for old sessions
+  skipPermissions?: boolean;    // Defaults to true for old sessions
+}
+
+// Provider config types (provider-utils.ts)
+ProviderConfig {
+  id, displayName, command, install,
+  permissions: { flag, label, default },
+  resume: { supported, type ('flag'|'subcommand'), flag?, subcommand?, lastFlag?, detectSession, sessionDir? },
+  prompt: { type ('positional'|'flag'), interactive?, nonInteractive? }
+}
+
+ProvidersData {
+  providers: Record<string, ProviderConfig>;
+  defaults: {
+    stages: Record<string, { provider, skipPermissions }>;
+    global: { provider, skipPermissions };
+    projects: Record<string, { provider, skipPermissions }>;
+  }
+}
+```
+
+## Security Hardening
+
+- **Localhost binding**: HOST defaults to `localhost` (not `0.0.0.0`)
+- **Command whitelist**: Only commands in `bridge-config.json` allowedCommands can be spawned (claude, codex, gemini, bash)
+- **Provider validation**: Provider ID must exist in providers.json; resolved command must be in allowedCommands
+- **CWD validation**: Requires absolute path, verifies exists and is accessible before spawning PTY
+- **CORS origins**: Configured in bridge-config.json, not wide-open
+
+## Activity Tracking
+
+- `lastOutputAt` timestamp updated on every PTY output
+- `isActive` = output within last 2 seconds (with 1s debounce)
+- `activelyWorking` count in BridgeStats for health monitor
+- Cards with active sessions show pulsing green glow in UI
+- **Activity transitions**: Logged with trigger details (snippet, hex, data length) for debugging phantom blips
+- `GET /activity-log/:name` endpoint exposes transition history per session
+
+## State Persistence
+
+- Session state saved to bridge-sessions.json via atomic writes (temp file + rename)
+- State file uses `__dirname` resolution for reliable file location
+- Missing file (ENOENT) handled gracefully; corrupt JSON throws fatal error
+- Prevents silent data loss from corrupted state
+
+## Race Condition Handling
+
+- **Disconnect grace period**: 5 seconds before session eligible for idle timeout
+- **Status transitions**: Protected against reconnect during disconnect
+- **SSE cleanup**: Proper client tracking on connection/disconnection
+
+## Terminal Classes
+
+Controls which commands appear in each context:
+- `global-terminal` - Dashboard terminal (future)
+- `project-terminal` - Project-level panel at bottom
+- `backlog`, `design`, `implementation`, `testing`, `done` - Card terminals by stage
+- `action-assistant` - Terminal in SlyActionConfigModal
+
+## Multi-Provider System
+
+### Supported Providers
+- **Claude Code** (`claude`) — Positional prompts, `--resume <GUID>` with auto-detection, `--dangerously-skip-permissions`
+- **Codex CLI** (`codex`) — Positional prompts, `codex resume --last` (subcommand-style), `--yolo`
+- **Gemini CLI** (`gemini`) — Flag-based prompts (`-i`/`-p`), `--resume` (no GUID), `--yolo`
+
+### Command Building (`buildProviderCommand`)
+- Returns `{ command, args }` tuple (command can change for Codex resume: `codex resume`)
+- Permission flag added if `skipPermissions: true`
+- Resume: flag-type appends `--resume [GUID]`; subcommand-type prepends `resume [GUID|--last]`
+- Prompt: positional appends as final arg; flag-type uses `-i <prompt>` (interactive)
+- No prompt on resume (user types into running session instead)
+
+### Session Name Format
+- **New format**: `{projectId}:{provider}:card:{cardId}` or `{projectId}:{provider}:global`
+- **Legacy format**: `{projectId}:card:{cardId}` or `{projectId}:global`
+- `resolveSessionName()` checks new format first, falls back to legacy via `toLegacySessionName()`
+- Old sessions without provider field default to `provider: "claude"`
+
+### GUID Detection (Claude only)
+- `supportsSessionDetection()` checks `provider.resume.detectSession`
+- Watches `~/.claude/projects/` for new `.jsonl` files after spawn
+- `getClaimedGuids()` excludes GUIDs already used by other sessions
+- Gemini/Codex use `--resume --last` (no GUID tracking)
+
+### Stage-Based Defaults
+- `providers.json` `defaults.stages` maps each kanban stage → `{ provider, skipPermissions }`
+- UI pre-fills provider dropdown from stage default
+- `defaults.global` for project-level terminals
+- `defaults.projects` reserved for per-project overrides (future)
+
+## Patterns & Invariants
+
+- Session names include provider segment: `{projectId}:{provider}:card:{cardId}` (new) or legacy `{projectId}:card:{cardId}`
+- Claude prompts passed as positional arg, NOT `-p` flag (that's print mode)
+- Resume behavior is provider-specific: flag vs subcommand, GUID vs latest
+- SSE streams through `/api/bridge/sessions/{name}/stream` proxy
+- Bridge runs on port 3456 (localhost), proxied through Next.js
+- Idle timeout: 4 hours default, checked every 60 seconds
+- Atomic state saves prevent data corruption
+- Provider config cached 30s in provider-utils.ts
+
+## API Endpoints
+
+- `GET /sessions` - List all sessions
+- `GET /sessions/:name` - Get session info
+- `POST /sessions` - Create session (validates command + CWD)
+- `DELETE /sessions/:name` - Stop or delete session
+- `POST /sessions/:name/input` - Send input to PTY
+- `POST /sessions/:name/resize` - Resize terminal
+- `POST /sessions/:name/stop` - Send Escape key to active session (soft stop)
+- `GET /sessions/:name/stream` - SSE output stream
+- `POST /sessions/stop-all` - Bulk stop all running sessions
+- `GET /stats` - BridgeStats with activity info
+- `GET /activity-log/:name` - Activity transition history for debugging
+
+## When to Expand
+
+- Session not starting → session-manager.ts createSession(), check command whitelist + provider validation
+- Adding new provider → data/providers.json, bridge-config.json allowedCommands
+- Provider command issues → provider-utils.ts buildProviderCommand()
+- Resume not working → provider-utils.ts (flag vs subcommand), claude-utils.ts (GUID detection)
+- Security concerns → bridge-config.json, session-manager.ts validation
+- Activity tracking issues → session-manager.ts handlePtyOutput(), getStats(), ActivityTransition
+- Phantom activity blips → activity-log endpoint, transition trigger data
+- Terminal display issues → Terminal.tsx, xterm setup
+- Connection problems → api/bridge proxy, connection-manager.ts
+- Idle timeout issues → session-manager.ts checkIdleSessions()
+- Bulk operations → stopAllSessions(), /sessions/stop-all
+- State corruption → session-manager.ts loadState/saveState
+- Session name resolution → session-manager.ts resolveSessionName(), toLegacySessionName()

package/templates/tutorial-project/.claude/skills/context-priming/references/areas/web-frontend.md

@@ -0,0 +1,252 @@
+# Web Frontend
+
+Updated: 2026-02-14
+
+## Overview
+
+Next.js 16 command center for project management. Features project cards with health scoring, kanban boards with drag-drop, card modals, command configuration, system health monitoring, cross-project toolkit/asset management, global search, activity feed, project scaffolding, and graceful reconnection handling. Neon-minimalist theme (SlyCode Neon) with Tailwind CSS v4, featuring lane-colored gradients, SVG noise textures, and theme-aware terminal styling.
+
+## Key Files
+
+### Pages & Layout
+- `web/src/app/page.tsx` - Home dashboard, lists projects from registry
+- `web/src/app/project/[id]/page.tsx` - Project detail page with kanban
+- `web/src/components/ProjectPageClient.tsx` - Client wrapper for project pages, global terminal activity polling
+- `web/src/components/ProjectView.tsx` - Project view wrapper, manages archive toggle state
+
+### Core Components
+- `web/src/components/Dashboard.tsx` - Project card grid + Toolkit tab, global search, number-key shortcuts
+- `web/src/components/ProjectKanban.tsx` - Kanban board container, drag-drop logic
+- `web/src/components/KanbanColumn.tsx` - Stage columns (backlog, design, impl, testing, done)
+- `web/src/components/KanbanCardItem.tsx` - Individual card, status indicators, active glow effect
+- `web/src/components/CardModal.tsx` - Full card editor with dynamic tabs, edit session protection
+- `web/src/components/ProjectHeader.tsx` - Header with Commands, Archive toggle, HealthMonitor
+
+### Project Management
+- `web/src/components/ProjectCard.tsx` - Enhanced project card with health dot, platform badges, edit/delete
+- `web/src/components/AddProjectModal.tsx` - Multi-phase project creation wizard (details → analysis → scaffold → done)
+- `web/src/components/HealthDot.tsx` - Health score indicator with tooltip (green/amber/red)
+- `web/src/components/PlatformBadges.tsx` - Detected AI platform badges (Claude, Gemini, Codex)
+- `web/src/components/SearchBar.tsx` - Global/contextual search across all kanban cards
+
+### Terminal & Commands
+- `web/src/components/ClaudeTerminalPanel.tsx` - Reusable terminal with provider selector, startupCommands/activeCommands, card area filtering
+- `web/src/components/Terminal.tsx` - xterm.js terminal with ConnectionManager integration
+- `web/src/components/CommandConfigModal.tsx` - Command configuration UI with Command Assistant terminal
+- `web/src/components/GlobalClaudePanel.tsx` - Floating panel for project-wide session, supports session/CWD/class overrides
+
+### Toolkit & Assets
+- `web/src/components/ToolkitTab.tsx` - Asset management tab with matrix view and pending changes
+- `web/src/components/AssetMatrix.tsx` - Cross-project asset deployment matrix with click-to-deploy/remove
+- `web/src/components/AssetViewer.tsx` - Modal viewer for asset content with frontmatter display
+
+### Activity & Content
+- `web/src/components/ActivityFeed.tsx` - Collapsible event log with day grouping and stage indicators
+- `web/src/components/MarkdownContent.tsx` - Markdown renderer using react-markdown with GFM support
+
+### Health & Connection
+- `web/src/components/HealthMonitor.tsx` - System stats widget (CPU, memory, terminals)
+- `web/src/components/ConnectionStatusIndicator.tsx` - Reconnection toast indicator
+- `web/src/lib/connection-manager.ts` - Centralized SSE reconnection with Page Visibility API
+
+### Hooks
+- `web/src/hooks/useConnectionStatus.ts` - Hook for connection state subscription
+- `web/src/hooks/useKeyboardShortcuts.ts` - Keyboard navigation (1-9 project jump, Escape)
+- `web/src/hooks/useCommandsConfig.ts` - Polling-based commands config loader (30s intervals)
+- `web/src/hooks/usePolling.ts` - Generic polling hook
+
+### Utilities
+- `web/src/lib/types.ts` - All shared types (see Data Models)
+- `web/src/lib/claude-actions.ts` - getStartupCommands(), getActiveCommands(), renderTemplate()
+- `web/src/lib/registry.ts` - Project registry loader with kanban, health scoring, platform detection
+- `web/src/lib/paths.ts` - Dynamic path resolution for SlyCode root and project directories
+- `web/src/lib/kanban-paths.ts` - Project-aware kanban file path resolution with tiered backup
+- `web/src/lib/asset-scanner.ts` - Asset scanning, frontmatter parsing, version comparison, platform detection
+- `web/src/lib/event-log.ts` - Append-only activity log with filtering/querying (500 event cap)
+- `web/src/lib/health-score.ts` - Health score calculator with configurable weights
+- `web/src/lib/tab-sync.ts` - Cross-tab synchronization using BroadcastChannel API
+
+### API Routes
+- `web/src/app/api/kanban/route.ts` - Kanban CRUD
+- `web/src/app/api/bridge/[...path]/route.ts` - Bridge proxy
+- `web/src/app/api/commands/route.ts` - Commands CRUD
+- `web/src/app/api/commands/stream/route.ts` - SSE for command file changes
+- `web/src/app/api/system-stats/route.ts` - CPU/memory metrics
+- `web/src/app/api/areas/route.ts` - Available areas list
+- `web/src/app/api/terminal-classes/route.ts` - Terminal class definitions
+- `web/src/app/api/claude-actions/route.ts` - Commands in ClaudeActionsConfig format
+- `web/src/app/api/toolkit/route.ts` - Scan all project assets, build matrix
+- `web/src/app/api/toolkit/sync/route.ts` - Batch deploy/remove assets
+- `web/src/app/api/toolkit/import/route.ts` - Import asset from project to ClaudeMaster
+- `web/src/app/api/events/route.ts` - Query activity log with filters
+- `web/src/app/api/search/route.ts` - Cross-project card search
+- `web/src/app/api/projects/route.ts` - List/create projects
+- `web/src/app/api/projects/[id]/route.ts` - GET/PUT/DELETE individual project
+- `web/src/app/api/projects/analyze/route.ts` - Analyze directory before scaffolding
+- `web/src/app/api/providers/route.ts` - GET/PUT for providers.json (provider list + stage defaults)
+- `web/src/app/api/file/route.ts` - Read files from approved directories
+- `web/src/app/api/git-status/route.ts` - Git status for projects
+
+## Key Functions
+
+- `ProjectKanban.handleDragEnd()` - Reorders cards, handles cross-column moves
+- `ConnectionManager.createManagedEventSource()` - Auto-reconnecting SSE with backoff
+- `getStartupCommands(commands, terminalClass, hasHistory)` - Filter commands for session start
+- `getActiveCommands(commands, terminalClass)` - Filter commands for running session toolbar
+- `scanProjectAssets()` - Scan commands/skills/agents across projects, build matrix
+- `calculateHealthScore()` - Score 0-100 based on configurable weighted factors
+
+## CardModal Tabs
+
+- **Details** - Edit fields, dropdowns for stage/priority, editable areas/tags chips, delete button
+- **Design** - Shows if `design_ref` exists, renders markdown with copy path button
+- **Feature** - Shows if `feature_ref` exists, renders markdown
+- **Test** - Shows if `test_ref` exists, renders markdown
+- **Checklist** - Interactive checkboxes with progress bar (uses ref-based state for rapid clicks)
+- **Terminal** - AI session with provider selector, auto-connect, startupCommands/activeCommands
+
+CardModal uses edit session protection: last-known-value tracking, 2000ms grace period for field editing, prevents overwriting active edits from external updates.
+
+## Health Scoring
+
+- **Factors**: outdated assets, stale cards, unresolved problems, missing CLAUDE.md, non-compliant frontmatter
+- **Levels**: green (≥80), amber (≥50), red (<50)
+- **Display**: HealthDot component with tooltip showing score breakdown
+- Located on ProjectCard in Dashboard
+
+## Toolkit (Asset Management)
+
+- Scans commands/skills/agents across all projects
+- Frontmatter validation: name, version, updated, description required
+- Version comparison for detecting outdated assets
+- Matrix view: rows=assets, columns=projects, cells=status
+- Batch operations: deploy to / remove from projects
+- Import from project back to ClaudeMaster
+
+## Connection Management
+
+- `ConnectionManager` - Singleton managing all SSE connections
+- Page Visibility API detection for sleep/wake cycles
+- Exponential backoff with jitter (1s initial, 30s max)
+- `ConnectionStatusIndicator` - Toast showing "Reconnecting..." during recovery
+
+## Data Models
+
+- `KanbanCard` - id, title, description, type, priority, order, areas[], tags[], problems[], checklist[], archived?, design_ref?, feature_ref?, test_ref?, claude_session?
+- `Command` - label, description, group, cardTypes[], prompt, visibleIn, scope, sessionState
+- `BridgeStats` - bridgeTerminals, connectedClients, activelyWorking, sessions[]
+- `SystemStats` - cpu (0-100), memory {used, total}, swap {used, total}
+- `SessionActivity` - name, status, lastOutputAt, isActive
+- `AssetInfo` - name, type, version, updated, description, filePath, frontmatter
+- `AssetCell` - status (present|outdated|missing|extra), masterVersion?, projectVersion?
+- `ToolkitData` - rows (AssetRow[]), projects (string[])
+- `HealthScore` - score (0-100), level (green|amber|red), factors[]
+- `ActivityEvent` - type, timestamp, project, detail, cardId?
+- `SearchResult` - card, project, matchedFields[]
+- `ProjectWithBacklog` - extends Project with assets, gitUncommitted, healthScore, platforms, lastActivity, activeSessions
+- `ProvidersData` - providers (Record<id, ProviderConfig>), defaults (stages, global, projects)
+- `ProviderConfig` - id, displayName, command, permissions, resume, prompt
+
+## Design System — SlyCode Neon Theme
+
+### Philosophy
+Neon-minimalist aesthetic. Clean surfaces with subtle texture for life and depth. Never sterile/flat, never over-the-top. The theme should feel like a premium tool — atmospheric but professional. Light mode is clean with color; dark mode is moody with glow.
+
+### Color Palette
+- **Neon Blue** (`--neon-blue: #00bfff`) — Primary accent, design/implementation lanes, links, active states
+- **Neon Orange** (`--neon-orange: #ff8c00`) — Global/project terminal headers, warnings
+- **Red-Orange** (`#ff6a33`) — Testing lane (NOT standard orange, which looks brown in dark mode)
+- **Green** — Done lane, success states, running indicators
+- **Void** — Neutral grey scale for backgrounds, borders, muted text
+- **Red** (`#ff3b5c`) — Critical/bug indicators, stop buttons
+
+### Critical Color Lesson
+Dark-end scale colors (e.g. `neon-orange-950 = #2b1700`) are inherently brown. For vibrant dark mode colors, use the BRIGHT color at LOW OPACITY (e.g. `neon-orange-400/15`) instead of dark scale values.
+
+### Texture System (globals.css)
+Three-layer texture approach for gradient surfaces:
+
+1. **Fine grain** (`.grain`) — High-frequency SVG feTurbulence noise (`baseFrequency: 0.65`), overlay blend. Desaturate with `feColorMatrix type='saturate' values='0'` when color neutrality matters.
+2. **Perlin noise** (`.depth-glow`) — Low-frequency organic texture (`baseFrequency: 0.015` light, `0.012` dark), large 400px tiles. Light mode uses `screen` blend (lightens), dark mode uses `soft-light`. Masked with left-to-right gradient fade.
+3. **Terminal texture** (`.terminal-texture`) — CRT-like grain + vignette + lane-colored tint via `--terminal-tint` CSS variable. Box-shaped mask (edges visible, centre clear). Light: `soft-light` blend. Dark: `screen` blend (avoids warm/red cast from `soft-light` on dark backgrounds).
+
+### Blend Mode Rules
+- `soft-light` on dark backgrounds produces warm/red cast — avoid for dark mode textures
+- `overlay` is neutral but can be invisible on very dark surfaces
+- `screen` always adds light — use for dark mode when you need visible texture
+- `mix-blend-multiply` makes white backgrounds transparent (light mode logos)
+- `mix-blend-lighten` makes black backgrounds transparent (dark mode logos)
+- `filter: drop-shadow()` traces the ALPHA boundary — creates rectangular glow on images with opaque backgrounds. Incompatible with blend-mode logo transparency.
+
+### Logo Handling
+Logos have opaque backgrounds (white for light, black for dark). Two `<img>` tags per location:
+- Light: `mix-blend-multiply dark:hidden`
+- Dark: `mix-blend-lighten hidden dark:block`
+- All CSS drop-shadow/filter glow DISABLED (creates rectangular artifacts with blend modes). Logos have baked-in glow.
+- Files: `slycode_light.png` / `slycode.png` (hero), `slycode_logo_light.png` / `slycode_logo.png` (nav)
+
+### Lane-Colored Theming
+Stage colors flow through multiple layers:
+- **KanbanColumn headers** — `colorClasses` map with header gradient, text, count badge, border
+- **CardModal header/tabs** — `stageModalStyles` map with gradients, borders per stage. Uses transparency (85% → 50%) for subtle glass quality
+- **CardModal footer** — `stageTerminalColors` with colored top border
+- **Terminal tint** — `stageTerminalTint` map provides rgba color → passed as `tintColor` prop → sets `--terminal-tint` CSS variable on terminal overlay
+
+### Gradient Direction Convention
+Left-to-right, vibrant-to-soft. The left/start side is always the stronger color, fading lighter toward the right. Never center-out fades (looks artificial).
+
+### Button Aesthetic — Neon Glass
+Terminal/action buttons use semi-transparent backgrounds with colored borders and hover glow:
+```
+border border-{color}-400/40 bg-{color}-400/15 text-{color}-400
+hover:bg-{color}-400/25 hover:shadow-[0_0_12px_rgba(...,0.3)]
+```
+
+### Health Monitor
+Uses inline gradient fills + glow shadows (not flat CSS classes):
+- Normal: `linear-gradient(90deg, #00e676, #00bfff)` + blue glow
+- Warning: `linear-gradient(90deg, #ff8c00, #ffaa00)` + orange glow
+- Critical: `linear-gradient(90deg, #ff3b5c, #ff6b81)` + red glow
+
+### Terminal Background
+Theme-aware: `#222228` (light mode, slightly lighter) / `#1a1a1a` (dark mode). Detected at xterm mount via `document.documentElement.classList.contains('dark')`. Wrapper divs use `bg-[#222228] dark:bg-[#1a1a1a]`.
+
+### Dark Mode Borders
+Card modals get colored outer borders in dark mode (`dark:border dark:border-{color}/25-30`). Section dividers (header/tabs/terminal) use lane colors in both modes.
+
+## Patterns & Invariants
+
+- Cards auto-save on changes via `/api/kanban` PUT
+- Kanban data stored in `documentation/kanban.json` per project
+- Stage order: backlog → design → implementation → testing → done
+- Active glow: `active-glow-card` CSS class with pulse animation (2s activity threshold)
+- Commands use `startupCommands` (session start) and `activeCommands` (running toolbar)
+- SSE connections managed centrally via ConnectionManager for reconnection
+- Dynamic path resolution via paths.ts (no hardcoded paths)
+- Cross-tab sync via BroadcastChannel API
+- Number keys 1-9 jump to projects, Escape closes modals
+- Event log capped at 500 entries, append-only
+- Session names include provider segment: `{projectId}:{provider}:card:{cardId}`
+- Provider selector shown on no-session screen, pre-filled from stage defaults
+- CardModal detects existing session's provider from session name for pre-selection
+- ProjectKanban/ProjectPageClient use regex patterns to match both new and legacy session names
+
+## When to Expand
+
+- Editing card behavior → CardModal.tsx
+- Kanban drag/drop issues → ProjectKanban.tsx, KanbanColumn.tsx
+- Adding new card fields → types.ts, CardModal.tsx
+- Command configuration → CommandConfigModal.tsx, data/commands.json
+- Health monitoring → HealthMonitor.tsx, /api/system-stats
+- Connection issues → connection-manager.ts, ConnectionStatusIndicator.tsx
+- Terminal panel behavior → ClaudeTerminalPanel.tsx
+- Provider selection → ClaudeTerminalPanel.tsx, /api/providers, data/providers.json
+- Provider detection for existing sessions → CardModal.tsx (session name parsing)
+- Asset management → asset-scanner.ts, ToolkitTab.tsx, AssetMatrix.tsx
+- Health scoring → health-score.ts, HealthDot.tsx
+- Activity feed → event-log.ts, ActivityFeed.tsx
+- Project scaffolding → AddProjectModal.tsx, /api/projects
+- Search → SearchBar.tsx, /api/search
+- Path resolution → paths.ts, kanban-paths.ts
+- Keyboard shortcuts → useKeyboardShortcuts.ts
+- Theme/design system → globals.css (texture classes), CardModal.tsx (stageModalStyles), KanbanColumn.tsx (colorClasses), GlobalClaudePanel.tsx (terminal header), Terminal.tsx (tintColor, terminal-texture)

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

@@ -0,0 +1,128 @@
+# Maintenance Doctrine
+
+Rules for maintaining context-priming references. Changes to this file require user approval.
+
+## Area File Structure
+
+Area files should be as lean as the area requires. Include sections that add value; omit those that don't.
+
+**Always include:**
+```markdown
+# [Area Name]
+
+Updated: YYYY-MM-DD
+
+## Overview
+What this area does, boundaries. 2-3 sentences.
+
+## Key Files
+- `file.py` - purpose
+[Most important files/modules]
+
+## When to Expand
+- [task] → [files to open]
+```
+
+**Include when relevant:**
+
+| Section | When to include |
+|---------|-----------------|
+| Key Functions | Area has important entry points, APIs, or non-obvious control flow |
+| Data Models | Area defines data structures used internally or externally |
+| Shared Objects | Area defines or consumes objects used across multiple areas |
+| Patterns & Invariants | Area has critical rules that must hold |
+| Interfaces | Area connects to other areas with data flow |
+
+**Section formats (when used):**
+
+```markdown
+## Key Functions
+- `process_message()` in handlers.py - entry point for incoming messages
+
+## Data Models
+- `Message` (models.py) - id, content, sender_id, timestamp | core envelope
+
+## Shared Objects
+- `Message` - DEFINED HERE, used by: frontend, api, workers
+- `Config` - defined in core, IMPORTED HERE
+
+## Patterns & Invariants
+- Auth middleware runs before handlers
+
+## Interfaces
+- → frontend: sends Message via WebSocket
+- ← api: receives Request, returns Response
+```
+
+Keep area files under 200 lines. Simple areas may be 20-30 lines; complex areas will be longer.
+
+**Shared Objects note**: When present, prevents duplicate definitions. Mark canonical location.
+
+## Defragmentation
+
+**When to defrag an area:**
+- Information is scattered/duplicated within the file
+- Sections contain outdated content mixed with current
+- File has grown beyond 200 lines
+- Reading the file doesn't quickly answer "what do I need to know?"
+
+**Defrag process:**
+1. Read the entire area file
+2. Identify: duplicates, outdated info, poor organization
+3. Consolidate related information
+4. Remove obsolete content (don't comment it out - delete)
+5. Verify remaining content is accurate against current code
+6. Update the `Updated` date
+
+**Consult user before defragging if:**
+- Multiple areas need simultaneous restructuring
+- Unsure whether information is obsolete or still relevant
+- Defrag would take significant time
+
+## Area Separation
+
+**Heuristics for deciding areas:**
+- Group by logical module/subsystem, not by file type
+- An area should be loadable and useful independently
+- If two areas are always loaded together, consider merging
+- If an area covers unrelated concerns, consider splitting
+
+**When to split an area:**
+- File exceeds 200 lines despite being concise
+- Contains distinct subsystems that don't interact
+- Load-when triggers have diverged (some tasks need part A, others need part B)
+
+**When to merge areas:**
+- Two areas are nearly always loaded together
+- Combined size would still be under 150 lines
+- Separation creates artificial boundaries
+
+**Cross-references:**
+- Areas can note "see also: [other-area]" for related context
+- Don't auto-load chains - let the index's load-when guide loading
+- If area A heavily depends on area B, note this in A's Interfaces section
+
+## Note Pruning
+
+Notes in area-index.md capture learnings. Prune when:
+- Note contradicts newer information (keep newer)
+- Code changed and note no longer applies
+- Note is vague or not actionable
+- Area exceeds 10 notes
+
+**Pruning is lightweight** - remove stale notes during routine updates, don't treat as separate task.
+
+## New Project Initialization
+
+When skill is introduced to a new codebase:
+
+1. Clear `areas/` directory
+2. Reset area-index.md to template state
+3. Keep SKILL.md and maintenance.md intact
+4. Scan project structure:
+   - Look for obvious module boundaries (directories, packages)
+   - Check build configs (package.json, pyproject.toml, etc.)
+   - Read CLAUDE.md for existing documentation pointers
+5. Propose 3-6 initial areas to user
+6. After approval, create area files with initial discovery
+7. Mark all as freshly created - validate through actual use