diff --git a/VERSION b/VERSION
index 5564d9a..81566e4 100644
--- a/VERSION
+++ b/VERSION
@@ -1 +1 @@
-0.26.5
+0.27.0
\ No newline at end of file
diff --git a/docker-entrypoint-fe.sh b/docker-entrypoint-fe.sh
index d6fcb97..8173e04 100644
--- a/docker-entrypoint-fe.sh
+++ b/docker-entrypoint-fe.sh
@@ -78,6 +78,10 @@ $(page_proxy_block "${BASE_PATH}/editor")
$(page_proxy_block "${BASE_PATH}/notes")
$(page_proxy_block "${BASE_PATH}/settings")
$(page_proxy_block "${BASE_PATH}/w")
+ # v0.27.0: Extension surface page routes
+$(page_proxy_block "${BASE_PATH}/s")
+ # v0.27.0: Extension surface static assets (served by backend from /data/surfaces/)
+$(page_proxy_block "${BASE_PATH}/surfaces")
ROUTES
)
diff --git a/docs/DESIGN-0.27.0.md b/docs/DESIGN-0.27.0.md
new file mode 100644
index 0000000..46f27cf
--- /dev/null
+++ b/docs/DESIGN-0.27.0.md
@@ -0,0 +1,842 @@
+# DESIGN — v0.27.0+: Debt Clearance, Extension Surfaces, Tasks
+
+**Status:** Draft
+**Scope:** Deferred debt clearance (v0.27.0), Tasks / Autonomous Agents (v0.27.x), TBD pull-forward (v0.28.0)
+**Depends on:** Workflow Engine (v0.26.0), Dynamic Surfaces (v0.25.0), Permissions (v0.24.2)
+**Current version:** 0.26.5
+
+---
+
+## Versioning Plan
+
+```
+v0.27.0 Debt Clearance: Extension Surface Routes + Workflow Polish
+ │
+v0.27.1 Tasks Foundation: Service Channels + Scheduler
+ │
+v0.27.2 Task Execution: Budgets + Admin Controls
+ │
+v0.27.3 Task Chaining: Webhooks + Workflow-to-Workflow
+ │
+v0.27.4 Personal Tasks: BYOK Scheduling + User Task UI
+ │
+v0.28.0 Platform Polish (TBD pull-forward)
+```
+
+---
+
+## Code Audit — Items Already Shipped
+
+The ROADMAP lists these as deferred but the code proves they're done:
+
+| Item | Evidence | Listed as deferred in |
+|------|----------|----------------------|
+| Persona tool grant enforcement in completion handler | `completion.go:928–949` — second-pass allowlist via `GetToolGrants()` | v0.25.0, v0.26.0 |
+| Version snapshot includes persona tool grants | `workflows.go:263–273` — `stageSnapshot.ToolGrants` populated at publish | v0.25.0 |
+| Session cleanup job | Shipped in v0.26.0 (background goroutine, `SESSION_EXPIRY_DAYS`) | v0.24.3 |
+
+**Action:** Cross off all three in the ROADMAP's deferred sections and in
+the v0.25.0 / v0.26.0 milestone checklists.
+
+---
+
+## v0.27.0 — Debt Clearance
+
+All deferred items from v0.25.0 and v0.26.0 plus outstanding tech debt
+that blocks future work. No new features — just finishing what's owed.
+
+### Phase 1: Extension Surface Routes (`/s/:slug`)
+
+The longest-deferred item (originally v0.21.3). Infrastructure exists:
+`surface_registry` table, `InstallSurface` handler (zip upload + asset
+extraction), `ListEnabledSurfaces` API. What's missing is the runtime
+route mounting, template rendering, and frontend nav integration.
+
+**Problem: Hardcoded surface conditionals in `base.html`**
+
+Lines 61–66 and 118–122 of `base.html` use `{{if eq .Surface "chat"}}`
+chains. Extension surfaces fall through to "Unknown surface". Same
+pattern for CSS includes (line 25–26) and script includes (118–122).
+
+**Solution: Generic extension surface template + dynamic blocks**
+
+```
+base.html changes:
+ {{if eq .Surface "chat"}}...
+ {{else if eq .Surface "admin"}}...
+ ...
+ {{else if .Manifest}}{{template "surface-extension" .}}
+ {{else}}Unknown surface: {{.Surface}}
+ {{end}}
+```
+
+New template `templates/surfaces/extension.html`:
+```html
+{{define "surface-extension"}}
+
+ {{/* Extension JS mounts into this container */}}
+
+
My Dashboard
';
+})();
+```
+
+**Admin UI additions:**
+
+The admin surfaces section (already exists) gains:
+- Upload button (already wired to `InstallSurface`)
+- Enable/disable toggles (already wired)
+- Uninstall button (already wired to `DeleteSurface`)
+- Route display showing the `/s/:slug` URL
+
+**Deliverables:**
+- [ ] `surface-extension` template (HTML + CSS + scripts blocks)
+- [ ] `base.html` conditional chain extended with `{{if .Manifest}}` fallthrough
+- [ ] `loadExtensionSurfaces()` in page engine
+- [ ] nginx location block for `/surfaces/` static assets
+- [ ] Frontend nav renders extension surfaces from `ListEnabledSurfaces`
+- [ ] Admin surfaces section shows upload/enable/disable/uninstall
+- [ ] Sample `.surface` archive (hello-world dashboard) for testing
+- [ ] CSP nonce propagation for extension scripts
+
+
+### Phase 2: Workflow Engine Polish
+
+Eight items deferred from v0.26.0. All backend infrastructure exists;
+these are wiring, UI, and enforcement.
+
+**Channel header stage indicator + advance/reject controls**
+- Workflow channels show: stage name, step N of M, assignment info
+- Advance / Reject buttons (permission-gated by `workflow.manage`)
+- Renders in the chat header area (same slot as `ai_mode` context banner)
+
+**Stage persona auto-switch in chat UI**
+- On stage transition, chat UI updates the active persona display
+- Model selector reflects the stage persona's bound model
+- System prompt injection already works (v0.26.4); this is FE-only
+
+**Assignment notifications via WebSocket**
+- New workflow assignment → `workflow.assigned` WS event to team members
+- Claim confirmation → `workflow.claimed` WS event to claimer
+- Uses existing notification infrastructure (v0.20.0)
+
+**Round-robin auto-assignment**
+- Per-stage `transition_rules.auto_assign: "round_robin"` in `workflow_stages`
+- On stage entry: query team members, pick least-recently-assigned
+- `workflow_assignments.assigned_to` populated automatically
+- Falls back to unassigned pool if round-robin fails
+
+**`on_complete` workflow chaining**
+- Column exists on `workflows` table (nullable JSONB, v0.26.1)
+- Schema: `{"action": "start_workflow", "target_slug": "...", "data_map": {...}}`
+- On workflow completion: if `on_complete` is non-null, start target workflow
+ with mapped `stage_data` from completed instance
+- Reuses existing `StartInstance()` path
+
+**Workflow retention enforcement**
+- Column exists on `workflows` table (`retention` JSONB, v0.26.1)
+- Background sweep (extend staleness goroutine): completed instances
+ older than `retention.delete_after_days` → hard delete
+- `retention.mode = "archive"` → set `workflow_status = 'archived'`,
+ `ai_mode = 'off'` (already implemented for channel archive)
+
+**Drag-and-drop stage reorder in builder**
+- Backend `PATCH /api/v1/workflows/:id/stages/reorder` already exists
+- Frontend: HTML5 drag events on stage list items in workflow builder
+- Same DnD pattern as channel/folder reorder (v0.23.1)
+
+**Team-scoped workflow management UI**
+- Team admin settings surface gains "Workflows" section
+- Lists workflows owned by the team, quick-edit name/description
+- Links to full builder for stage editing
+- Mirrors the admin-level builder but scoped to `team_id`
+
+**Deliverables:**
+- [ ] Channel header workflow stage indicator component
+- [ ] Advance/reject buttons with permission gate
+- [ ] Stage persona auto-switch in chat UI
+- [ ] `workflow.assigned` / `workflow.claimed` WS events
+- [ ] Round-robin auto-assignment in stage transition handler
+- [ ] `on_complete` chaining trigger in workflow completion path
+- [ ] Retention enforcement in staleness sweep goroutine
+- [ ] Drag-and-drop stage reorder in workflow builder UI
+- [ ] Team settings → Workflows section
+
+
+### Phase 3: Workspace + Editor Debt
+
+Items deferred from v0.21.x that are low-hanging fruit.
+
+- [ ] `.gitignore` respect in workspace indexing (`workspace/indexer.go` — skip paths matching patterns from `.gitignore` in workspace root)
+- [ ] Workspace settings UI: git config section in channel/project settings (remote URL, branch, auto-commit toggle)
+- [ ] Pane state persistence per-user/per-project (save pane layout to `user_settings` JSONB, restore on surface load)
+- [ ] Editor drag-drop file reorder (workspace file tree — reorder via DnD, persist order in workspace metadata)
+
+**Explicitly deferred (not v0.27.0):**
+- User settings git credentials management UI — needs vault-encrypted git credential store (v0.28.0 candidate)
+- Integration tests: clone/commit/push/pull — needs git binary in CI container
+- Article-specific AI tools — needs article surface rebuild
+- Mobile hamburger nav — needs responsive audit pass
+
+**Deliverables:**
+- [ ] `.gitignore` filter in `workspace/indexer.go`
+- [ ] Git config section in workspace/project settings UI
+- [ ] Pane layout persistence in `user_settings`
+- [ ] Editor file tree DnD reorder
+
+
+### ROADMAP Cleanup
+
+Update the ROADMAP itself:
+- [ ] Cross off tool grant enforcement (3 locations)
+- [ ] Move "Deferred to v0.27.0" items under their proper v0.27.0 section
+- [ ] Remove duplicate entries (extension surface routes listed 4× across the file)
+- [ ] Add v0.27.0 section with phase structure
+- [ ] Update dependency graph
+
+---
+
+## v0.27.1 — Tasks Foundation: Service Channels + Scheduler
+
+The core primitive: a channel with no human participant, driven by
+a scheduler.
+
+### Service Channels
+
+`type: 'service'` — a new channel type. Service channels:
+- Have zero human participants (only persona participants)
+- Cannot be joined by users (read-only view for authorized users)
+- Are created by the scheduler or the `task_create` tool
+- Inherit the workflow engine's stage model (optional — simple tasks
+ skip stages entirely)
+- Appear in a "Tasks" sidebar section (collapsed by default)
+
+```sql
+-- No new migration needed — channel type CHECK already allows extension.
+-- Add 'service' to the channel type CHECK constraint:
+ALTER TABLE channels DROP CONSTRAINT IF EXISTS channels_type_check;
+ALTER TABLE channels ADD CONSTRAINT channels_type_check
+ CHECK (type IN ('direct','dm','group','channel','workflow','service'));
+```
+
+### Task Definitions
+
+A task is a lightweight scheduled job that creates a service channel
+and runs a completion (or instantiates a workflow).
+
+**`tasks` table:**
+```sql
+CREATE TABLE tasks (
+ id TEXT PRIMARY KEY DEFAULT gen_random_uuid()::text,
+ owner_id TEXT NOT NULL REFERENCES users(id) ON DELETE CASCADE,
+ team_id TEXT REFERENCES teams(id) ON DELETE SET NULL,
+ name TEXT NOT NULL,
+ description TEXT,
+ scope TEXT NOT NULL DEFAULT 'personal'
+ CHECK (scope IN ('personal', 'team', 'global')),
+
+ -- What to run
+ task_type TEXT NOT NULL DEFAULT 'prompt'
+ CHECK (task_type IN ('prompt', 'workflow')),
+ persona_id TEXT REFERENCES personas(id) ON DELETE SET NULL,
+ model_id TEXT, -- explicit model override (nullable)
+ system_prompt TEXT, -- additional system prompt (prepended)
+ user_prompt TEXT, -- the message to send
+ workflow_id TEXT REFERENCES workflows(id) ON DELETE SET NULL,
+ tool_grants JSONB, -- explicit tool allowlist (nullable = inherit all)
+
+ -- Schedule
+ schedule TEXT NOT NULL, -- cron expression (5-field)
+ timezone TEXT NOT NULL DEFAULT 'UTC',
+ is_active BOOLEAN NOT NULL DEFAULT true,
+
+ -- Execution policy
+ max_tokens INTEGER NOT NULL DEFAULT 4096,
+ max_tool_calls INTEGER NOT NULL DEFAULT 10,
+ max_wall_clock INTEGER NOT NULL DEFAULT 300, -- seconds
+ output_mode TEXT NOT NULL DEFAULT 'channel'
+ CHECK (output_mode IN ('channel', 'note', 'webhook')),
+ output_channel_id TEXT REFERENCES channels(id) ON DELETE SET NULL,
+ webhook_url TEXT,
+
+ -- Provider routing
+ provider_config_id TEXT REFERENCES provider_configs(id) ON DELETE SET NULL,
+
+ -- Notifications
+ notify_on_complete BOOLEAN NOT NULL DEFAULT false,
+ notify_on_failure BOOLEAN NOT NULL DEFAULT true,
+
+ -- Bookkeeping
+ last_run_at TIMESTAMPTZ,
+ next_run_at TIMESTAMPTZ,
+ run_count INTEGER NOT NULL DEFAULT 0,
+ created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+ updated_at TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+
+CREATE INDEX idx_tasks_next_run ON tasks (next_run_at) WHERE is_active = true;
+CREATE INDEX idx_tasks_owner ON tasks (owner_id);
+```
+
+**Two task types:**
+
+1. **Prompt task** (`task_type = 'prompt'`): Create a service channel,
+ send `user_prompt` with `system_prompt` prepended, collect response.
+ Simple, single-turn. Good for: news digest, stock screener, daily
+ standup prep, report generation.
+
+2. **Workflow task** (`task_type = 'workflow'`): Instantiate a workflow
+ in a service channel. Multi-stage, tool-using, potentially long-running.
+ Good for: data pipeline, automated review, research agent.
+
+### Scheduler
+
+Background goroutine (same pattern as compaction scanner, staleness sweep):
+
+```go
+type TaskScheduler struct {
+ stores store.Stores
+ interval time.Duration // poll interval: 30s
+ stop chan struct{}
+}
+
+func (s *TaskScheduler) Run() {
+ ticker := time.NewTicker(s.interval)
+ for {
+ select {
+ case <-ticker.C:
+ s.poll()
+ case <-s.stop:
+ return
+ }
+ }
+}
+
+func (s *TaskScheduler) poll() {
+ // SELECT * FROM tasks WHERE is_active AND next_run_at <= now()
+ // ORDER BY next_run_at LIMIT 10
+ due, _ := s.stores.Tasks.ListDue(ctx)
+ for _, task := range due {
+ go s.execute(task)
+ }
+}
+```
+
+Cron parsing: use `github.com/robfig/cron/v3` for 5-field expressions.
+Compute `next_run_at` after each execution.
+
+### Provider Resolution for Tasks
+
+Task execution needs a provider. Resolution order:
+
+1. Explicit `provider_config_id` on task (user chose a specific provider)
+2. Personal BYOK provider (if `scope = 'personal'` and user has BYOK keys)
+3. Team provider (if `scope = 'team'`)
+4. Global provider (fallback)
+5. Routing policy (if task's model matches a routing policy)
+
+This is the same resolution chain as completions, reusing the existing
+`resolveProvider()` path in `completion.go`.
+
+### Migration
+
+- 026_tasks.sql: `tasks` table, service channel type extension
+
+**Deliverables:**
+- [ ] `tasks` table + store interface + PG/SQLite implementations
+- [ ] `type: 'service'` channel type
+- [ ] `TaskScheduler` background goroutine
+- [ ] Cron expression parsing + `next_run_at` computation
+- [ ] Task execution path (create service channel, run completion)
+- [ ] Provider resolution for task context
+- [ ] Tasks sidebar section (read-only view of service channels)
+
+
+---
+
+## v0.27.2 — Task Execution: Budgets + Admin Controls
+
+### Execution Budgets
+
+Three limits enforced in the task execution path:
+
+1. **`max_tokens`** — total output tokens. Tracked via existing
+ `usage_log` infrastructure. Execution halts mid-stream if exceeded.
+2. **`max_tool_calls`** — total tool invocations per run. Counter
+ incremented in `streamWithToolLoop`. Execution halts on breach.
+3. **`max_wall_clock`** — seconds. `context.WithTimeout` on the
+ execution goroutine. Hard kill on timeout.
+
+Budget breach → task marked as `budget_exceeded` in run history,
+notification to owner.
+
+### Task Run History
+
+**`task_runs` table:**
+```sql
+CREATE TABLE task_runs (
+ id TEXT PRIMARY KEY DEFAULT gen_random_uuid()::text,
+ task_id TEXT NOT NULL REFERENCES tasks(id) ON DELETE CASCADE,
+ channel_id TEXT REFERENCES channels(id) ON DELETE SET NULL,
+ status TEXT NOT NULL DEFAULT 'running'
+ CHECK (status IN ('running','completed','failed',
+ 'budget_exceeded','cancelled')),
+ started_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+ completed_at TIMESTAMPTZ,
+ tokens_used INTEGER DEFAULT 0,
+ tool_calls INTEGER DEFAULT 0,
+ wall_clock INTEGER DEFAULT 0, -- seconds
+ error TEXT
+);
+```
+
+### Admin Controls
+
+**Global config keys:**
+- `tasks.enabled` — master kill switch (default: true)
+- `tasks.allow_personal` — whether non-admin users can create personal
+ tasks (default: false). Same pattern as `personas.allow_personal`.
+- `tasks.max_concurrent` — max simultaneous task executions (default: 5)
+- `tasks.default_budget.max_tokens` — default ceiling (overridable per task)
+- `tasks.default_budget.max_tool_calls` — default ceiling
+- `tasks.default_budget.max_wall_clock` — default ceiling (seconds)
+
+**Admin panel — Tasks section:**
+- List all tasks (filterable by owner, team, scope, status)
+- View task run history with budget usage
+- Pause/resume individual tasks
+- Kill running executions
+- Edit default budgets
+- Toggle `tasks.allow_personal`
+
+**Permission integration:**
+- New permission: `tasks.create` — required to create tasks
+- New permission: `tasks.admin` — required to manage others' tasks
+- `Everyone` group gets `tasks.create` if `tasks.allow_personal` is true
+
+**Deliverables:**
+- [ ] Execution budget enforcement (tokens, tool calls, wall clock)
+- [ ] `task_runs` table + store
+- [ ] Budget breach notification to task owner
+- [ ] Global config keys for task admin controls
+- [ ] Admin panel Tasks section (CRUD, history, kill switch)
+- [ ] `tasks.create` and `tasks.admin` permissions
+- [ ] `tasks.allow_personal` toggle (mirrors `personas.allow_personal`)
+
+
+---
+
+## v0.27.3 — Task Chaining: Webhooks + Workflow-to-Workflow
+
+### Completion Webhooks
+
+When a task (or workflow) completes, optionally POST to an external URL:
+
+```go
+type WebhookPayload struct {
+ TaskID string `json:"task_id"`
+ TaskName string `json:"task_name"`
+ Status string `json:"status"`
+ ChannelID string `json:"channel_id"`
+ CompletedAt time.Time `json:"completed_at"`
+ Output string `json:"output"` // last assistant message
+ StageData any `json:"stage_data"` // workflow stage data (if applicable)
+}
+```
+
+- Webhook URL on task or workflow (`webhook_url` column)
+- Retry: 3 attempts with exponential backoff (1s, 5s, 25s)
+- Timeout: 10s per attempt
+- HMAC signature header (`X-Switchboard-Signature`) using a per-task secret
+
+### `task_create` Tool
+
+AI-invocable tool that spawns sub-tasks:
+
+```json
+{
+ "name": "task_create",
+ "description": "Create a new scheduled or one-shot task",
+ "parameters": {
+ "name": "string",
+ "prompt": "string",
+ "schedule": "string (cron or 'once')",
+ "persona": "string (handle, optional)",
+ "max_tokens": "integer (optional)"
+ }
+}
+```
+
+- `RequireWorkflow` or `RequireTeam` predicate (not available in
+ personal chats — prevents runaway task creation)
+- One-shot tasks: `schedule = 'once'`, `next_run_at = now()`
+- Created tasks inherit the parent's scope (team/global)
+- Depth limit: tasks cannot create tasks (no recursive spawning)
+
+### Workflow-to-Workflow Chaining
+
+Wires the `on_complete` column (v0.26.1) into the task system:
+
+- On workflow completion with `on_complete` set: create a one-shot task
+ that instantiates the target workflow with mapped data
+- Data mapping: `data_map` keys in `on_complete` JSONB map source
+ `stage_data` fields to target workflow's initial `stage_data`
+
+**Deliverables:**
+- [ ] Webhook delivery with retry + HMAC signature
+- [ ] `task_create` tool with depth limit
+- [ ] `on_complete` chaining via task system
+- [ ] Webhook secret generation per task/workflow
+
+
+---
+
+## v0.27.4 — Personal Tasks: BYOK Scheduling + User Task UI
+
+The user-facing task experience. Users create personal tasks that run
+against their BYOK providers.
+
+### Use Cases
+
+- **Morning news digest:** Daily at 6am, prompt "Summarize top tech news",
+ output to a personal service channel. Persona: "News Analyst" with
+ `web_search` tool grant.
+- **Stock screener:** Weekdays at market open, prompt "Check my watchlist
+ for unusual pre-market activity", BYOK OpenAI key for cost control.
+- **Weekly project summary:** Friday at 5pm, prompt "Summarize this
+ week's activity across my projects", uses `conversation_search` +
+ `workspace_search` tools.
+- **Daily standup prep:** Weekday mornings, reviews yesterday's notes
+ and generates standup talking points.
+
+### Settings Surface — Tasks Section
+
+New section in user settings (same pattern as BYOK, Personas):
+
+- Task list: name, schedule (human-readable), last run status, next run
+- Create task: name, persona picker, model picker, prompt editor,
+ schedule builder (preset crons + custom), budget overrides
+- Task detail: run history, output channel link, edit, pause/delete
+- BYOK indicator: shows which provider the task will use
+
+### Schedule Builder
+
+Preset schedules + custom cron for power users:
+
+| Preset | Cron |
+|--------|------|
+| Every morning (6am) | `0 6 * * *` |
+| Weekday mornings (8am) | `0 8 * * 1-5` |
+| Every hour | `0 * * * *` |
+| Weekly (Monday 9am) | `0 9 * * 1` |
+| Monthly (1st at midnight) | `0 0 1 * *` |
+| Custom... | user-entered 5-field cron |
+
+Timezone selector defaults to browser timezone.
+
+### BYOK Task Routing
+
+Personal tasks prefer the user's BYOK provider:
+
+1. If task has explicit `provider_config_id` → use it
+2. If user has a BYOK provider config for the task's model → use BYOK
+3. Fall through to team/global provider (if allowed by admin)
+
+Admin can restrict personal tasks to BYOK-only via
+`tasks.personal_require_byok` config key (default: false). When true,
+personal tasks without a BYOK provider fail with a clear error instead
+of falling through to org providers.
+
+### Output Modes
+
+Three output destinations:
+
+1. **Channel** (default): Output goes to a persistent service channel.
+ User views it like a read-only chat. Channel accumulates run outputs
+ over time (scrollable history).
+2. **Note**: Output saved as a channel-scoped note (good for structured
+ data, reports). Note title includes timestamp.
+3. **Webhook**: Output POSTed to external URL (for integration with
+ other tools — Slack, email, etc.).
+
+### Task Sidebar Section
+
+New sidebar section (below Channels, above Chats):
+
+```
+▾ Tasks (collapsible)
+ ◷ Morning News Digest ✓ 6:02am
+ ◷ Stock Screener ✓ 9:30am
+ ◷ Weekly Summary ⏳ Fri 5pm
+ + New task
+```
+
+Click opens the task's output channel. Status indicators: ✓ (last run
+succeeded), ✗ (failed), ⏳ (next run time), ▶ (running now).
+
+**Deliverables:**
+- [ ] Settings → Tasks section (CRUD, schedule builder, budget config)
+- [ ] BYOK provider routing for personal tasks
+- [ ] `tasks.personal_require_byok` config key
+- [ ] Output modes: channel, note, webhook
+- [ ] Tasks sidebar section with status indicators
+- [ ] "Run Now" button for manual trigger
+- [ ] Task output channel read-only view
+
+
+---
+
+## v0.28.0 — Platform Polish (TBD Pull-Forward)
+
+Candidates pulled from the TBD section, prioritized by value and
+dependency readiness.
+
+### Tier 1 — High value, dependencies met
+
+**Virtual scroll for long conversations**
+Conversations with 500+ messages bog down the DOM. Virtual scroll renders
+only visible messages + buffer zone. Prerequisite for heavy task output
+channels.
+
+**KB auto-injection (context-aware)**
+Top-K chunk prepend to system prompt, context budget aware, per-channel
+toggle. Useful for tasks that need domain knowledge without explicit
+`kb_search` tool calls. Latency budgeting required (embedding lookup
+adds ~200ms).
+
+**Helm chart**
+Raw k8s manifests with `${VAR}` substitution → proper Helm chart.
+`values.yaml` for replicas, image tags, ingress, storage, secrets,
+feature flags. Subchart for dev/test Postgres. Target: `helm install
+switchboard ./chart`. Now makes sense because the feature set is
+stabilizing post-tasks.
+
+**Per-provider model preferences**
+`user_model_settings` unique key is `(user_id, model_id)` — same model
+from different providers shares one visibility toggle. Needs
+`provider_config_id` dimension in DB constraint, store, API, and
+frontend `hiddenModels` keying. Natural fit now that BYOK tasks need
+per-provider model selection.
+
+### Tier 2 — Medium value, some design work needed
+
+**Memory compaction**
+Summarize old memories to save context tokens. Confidence decay: reduce
+confidence over time, prune low-confidence entries. Natural extension of
+the memory system (v0.18.0).
+
+**`capability_match` routing policy**
+"Cheapest model with tool_calling" — a new routing policy type. Useful
+for tasks that need tool use but don't need the strongest model.
+
+**New provider types via config file**
+OpenAI-compatible endpoints registrable via YAML config (no Go code).
+Enables users to point at local LLMs (Ollama, vLLM, llama.cpp) without
+a provider code change.
+
+### Tier 3 — Future (v0.29+)
+
+- Desktop app (Tauri) — large scope, independent track
+- Full PWA with offline — needs service worker rewrite
+- Plugin/extension marketplace — needs extension surface routes first (v0.27.0)
+- Starlark/sidecar extension tiers — needs extension surface routes first
+- Git credentials vault store — needs vault extension design
+- Cross-persona memory sharing — needs memory system redesign
+
+
+---
+
+## Design Decision: Task Permission Model
+
+Tasks introduce a new resource type that intersects with multiple
+existing permission boundaries:
+
+| Scope | Who can create | Provider used | Visibility |
+|-------|---------------|---------------|------------|
+| Personal | User (if `tasks.allow_personal`) | User's BYOK or team fallback | Owner only |
+| Team | User with `tasks.create` + team membership | Team provider | Team members |
+| Global | Admin | Global provider | All users (read) |
+
+Personal tasks are the BYOK sweet spot. The admin toggle
+(`tasks.allow_personal`) mirrors the existing `personas.allow_personal`
+pattern — a single boolean in global config, surfaced in the admin
+settings panel.
+
+**Why not just a permission?** The `tasks.create` permission already
+gates the ability. `tasks.allow_personal` is a _policy_ control —
+admins might allow task creation for team tasks but prohibit personal
+tasks to prevent uncontrolled BYOK spending. Two orthogonal knobs.
+
+
+---
+
+## Design Decision: Task vs. Workflow Relationship
+
+Tasks and workflows are related but distinct:
+
+| | Task | Workflow |
+|---|------|---------|
+| Trigger | Cron schedule or `task_create` tool | Human click or task trigger |
+| Participants | Zero humans (service channel) | Humans + AI |
+| Complexity | Single prompt or workflow instantiation | Multi-stage, assignment queue |
+| Output | Channel, note, or webhook | Channel (interactive) |
+| Lifecycle | Recurring (cron) or one-shot | Single instance |
+
+A **prompt task** is simpler than a workflow — it's a scheduled
+completion. A **workflow task** is a task that instantiates a workflow.
+This keeps the task system lean (scheduling + budgets + output routing)
+and the workflow engine rich (stages + assignment + personas).
+
+The `task_type` column makes this explicit. Prompt tasks don't need
+workflows at all — they're a direct scheduler → completion path.
+Workflow tasks reuse the full workflow engine.
+
+
+---
+
+## Resolved Decisions
+
+1. **Task output retention.** Use channel-level retention from v0.26.0.
+ No per-task retention policy needed — the channel's `retention` JSONB
+ handles archive/delete semantics. Notes created by task output survive
+ channel removal (notes are channel-scoped but not cascade-deleted).
+ Storage quotas per user are a future concern (v0.29+ candidate) — not
+ blocking for initial task support.
+
+2. **Concurrent task execution.** Skip with a warning log. If
+ `task_runs` has a row with `status = 'running'` for the task, the
+ scheduler skips that tick. Log: `[scheduler] Skipping task %s — previous
+ run still active`. No queue — if a task consistently overruns its
+ schedule, the user needs to adjust the cron interval or budget.
+
+3. **Task templates.** Ship 3–5 optional starter templates in v0.27.4.
+ Presented as suggestions during task creation ("Start from a
+ template..." option alongside blank task). Not auto-created — user
+ must explicitly choose one. Templates are just pre-filled form values,
+ not persistent DB records.
+
+4. **Task notifications.** Opt-in per task. Two booleans on the `tasks`
+ table: `notify_on_complete` (default false), `notify_on_failure`
+ (default true). Uses existing notification infrastructure (v0.20.0
+ bell + WebSocket push).
diff --git a/docs/EXTENSION-SURFACES.md b/docs/EXTENSION-SURFACES.md
new file mode 100644
index 0000000..e7b1a48
--- /dev/null
+++ b/docs/EXTENSION-SURFACES.md
@@ -0,0 +1,453 @@
+# Extension Surfaces — Authoring Guide
+
+**Version:** v0.27.0+
+**Audience:** Developers building custom surfaces for Chat Switchboard
+**Prerequisite:** Admin access to install surfaces
+
+---
+
+## What Is an Extension Surface?
+
+An extension surface is a custom full-page UI that runs inside the
+Chat Switchboard shell. It gets its own URL (`/s/your-surface`), a
+link in the sidebar, and full access to the platform's authenticated
+API, theme system, and UI components.
+
+Examples of what you can build:
+
+- A monitoring dashboard that polls external APIs
+- A custom form builder for workflow intake
+- A kanban board backed by channel data
+- A cost tracking view using usage data
+- A project timeline visualization
+
+Extension surfaces are installed as `.surface` archives via the admin
+panel. No code changes to the platform are required.
+
+---
+
+## Quick Start
+
+### 1. Create the Archive
+
+A `.surface` file is a zip archive with this structure:
+
+```
+my-dashboard/
+├── manifest.json ← required: surface metadata
+├── js/
+│ └── main.js ← required: entry point script
+└── css/
+ └── main.css ← optional: styles
+```
+
+The top-level directory name must match the `id` in `manifest.json`.
+
+### 2. Write the Manifest
+
+```json
+{
+ "id": "my-dashboard",
+ "title": "My Dashboard",
+ "route": "/s/my-dashboard",
+ "auth": "authenticated",
+ "layout": "single",
+ "version": "1.0.0",
+ "description": "A custom dashboard surface."
+}
+```
+
+| Field | Required | Description |
+|---------------|----------|-------------|
+| `id` | yes | Unique identifier. Lowercase, alphanumeric + hyphens. Must match the archive's top-level directory name. |
+| `title` | yes | Human-readable name shown in the sidebar nav. |
+| `route` | no | URL path. Defaults to `/s/{id}` if omitted. Must start with `/s/`. |
+| `auth` | no | Auth requirement. Only `"authenticated"` is supported currently. Default: `"authenticated"`. |
+| `layout` | no | Layout preset. Only `"single"` is supported currently. Default: `"single"`. |
+| `version` | no | Semver string for your own tracking. Not enforced. |
+| `description` | no | Shown in the admin surfaces panel. |
+
+### 3. Write the Entry Point
+
+`js/main.js` runs after all platform scripts have loaded. Your code
+mounts into the `#extension-mount` container:
+
+```js
+(function() {
+ 'use strict';
+
+ var mount = document.getElementById('extension-mount');
+ if (!mount) return;
+
+ var manifest = window.__MANIFEST__ || {};
+ var user = window.__USER__ || {};
+
+ mount.innerHTML = 'Hello, ' + esc(user.display_name || user.username) + '!
';
+
+ function esc(s) {
+ var el = document.createElement('span');
+ el.textContent = s;
+ return el.innerHTML;
+ }
+})();
+```
+
+### 4. Package and Install
+
+```sh
+zip -r my-dashboard.surface my-dashboard/
+```
+
+Then in the admin panel: **Admin → Surfaces → Upload** and select the
+`.surface` file. The surface is immediately available — no restart
+required. A link appears in the sidebar.
+
+---
+
+## Platform Globals
+
+Your `main.js` runs in the full platform context. These globals are
+available when your script executes:
+
+### Window Injections
+
+| Global | Type | Description |
+|--------|------|-------------|
+| `window.__MANIFEST__` | Object | Your surface's manifest with route, layout, etc. Keys are **lowercase** (JSON serialization from Go). Access as `manifest.id`, `manifest.route`, `manifest.title`. |
+| `window.__USER__` | Object | Authenticated user: `{ username, display_name, role, id, email }`. |
+| `window.__BASE__` | String | URL base path (e.g. `"/dev"` or `""`). Prepend to all internal links. |
+| `window.__VERSION__` | String | Platform version string. |
+| `window.__SURFACE__` | String | Your surface ID. |
+
+### API Module
+
+`API` provides authenticated fetch wrappers. Auth headers and token
+refresh are handled automatically.
+
+```js
+// GET request — returns parsed JSON
+var data = await API._get('/api/v1/channels');
+
+// POST request — body is JSON-serialized automatically
+var result = await API._post('/api/v1/channels', {
+ name: 'my-channel',
+ type: 'channel'
+});
+
+// PUT request
+await API._put('/api/v1/channels/' + id, { name: 'renamed' });
+```
+
+All methods return a Promise that resolves to parsed JSON. On 401,
+tokens are refreshed automatically and the request is retried.
+
+**Important:** The methods are `_get`, `_post`, `_put` — prefixed with
+underscore. There is no `API.get()`.
+
+### UI Module
+
+`UI` provides platform UI primitives:
+
+```js
+// Toast notification — types: 'success', 'error', 'info', 'warning'
+UI.toast('Operation completed', 'success');
+UI.toast('Something went wrong', 'error');
+
+// Navigate to settings
+UI.openSettings('general');
+```
+
+### Theme Module
+
+`Theme` manages dark/light mode:
+
+```js
+// Current resolved theme: 'dark' or 'light'
+var mode = Theme.resolved();
+
+// Check via DOM attribute
+var isDark = document.documentElement.getAttribute('data-theme') === 'dark';
+```
+
+Your CSS should use CSS custom properties (see below) rather than
+querying Theme directly. Properties update automatically on theme change.
+
+### Events Module
+
+`Events` is the platform event bus (WebSocket-backed):
+
+```js
+// Subscribe to events
+Events.on('chat.message.created', function(data) {
+ console.log('New message:', data);
+});
+
+// Emit local-only events
+Events.emit('my-surface.updated', { key: 'value' });
+```
+
+### ChatPane Component
+
+If your surface needs an embedded chat, you can mount a ChatPane:
+
+```js
+var container = document.createElement('div');
+container.style.height = '400px';
+mount.appendChild(container);
+
+ChatPane.create(container, { role: 'assist' });
+```
+
+---
+
+## CSS Custom Properties
+
+Your CSS should use the platform's CSS custom properties for consistent
+theming. These update automatically when the user switches themes.
+
+### Colors
+
+| Property | Dark Default | Light Default | Usage |
+|----------|-------------|---------------|-------|
+| `--bg` | `#0e0e10` | `#f7f7fa` | Page background |
+| `--bg-surface` | `#18181b` | `#ffffff` | Card/panel background |
+| `--bg-raised` | `#222227` | `#eff0f3` | Elevated element background |
+| `--bg-hover` | `#2a2a30` | `#e5e6eb` | Hover state background |
+| `--border` | `#2e2e35` | `#d5d6dc` | Default borders |
+| `--border-light` | `#3a3a42` | `#c2c3cb` | Subtle borders |
+| `--text` | `#e8e8ed` | `#1a1a2e` | Primary text |
+| `--text-2` | `#9898a8` | — | Secondary text |
+| `--text-3` | `#6b6b7b` | — | Tertiary/muted text |
+| `--accent` | `#6c9fff` | — | Accent color (links, highlights) |
+| `--accent-hover` | `#84b0ff` | — | Accent hover state |
+| `--accent-dim` | `rgba(108,159,255,0.12)` | — | Accent tinted background |
+| `--danger` | `#ef4444` | — | Error/destructive actions |
+| `--success` | `#22c55e` | — | Success indicators |
+| `--warning` | `#eab308` | — | Warning indicators |
+
+### Layout
+
+| Property | Default | Usage |
+|----------|---------|-------|
+| `--radius` | `8px` | Default border radius |
+| `--radius-lg` | `12px` | Large border radius |
+| `--font` | `'DM Sans', ...` | Primary font stack |
+| `--mono` | `'JetBrains Mono', ...` | Monospace font stack |
+| `--transition` | `180ms ease` | Default transition timing |
+
+### Example
+
+```css
+.my-card {
+ background: var(--bg-surface);
+ border: 1px solid var(--border);
+ border-radius: var(--radius-lg);
+ padding: 16px;
+ color: var(--text);
+}
+
+.my-card-subtitle {
+ color: var(--text-2);
+ font-size: 13px;
+}
+
+.my-card:hover {
+ background: var(--bg-hover);
+}
+```
+
+**Do not use** `--bg-secondary`, `--text-secondary`, or
+`--text-tertiary` — these do not exist. Use `--bg-surface`, `--text-2`,
+and `--text-3` respectively.
+
+---
+
+## DOM Structure
+
+When your surface loads, the page DOM looks like this:
+
+```
+
+
+
+
+ ← platform nav
+
+ ← YOUR CONTENT GOES HERE
+
+
+
+
' +
- '
' +
- '
← Back' +
- '
Hello World' +
- '
' +
- '
' +
- '
' +
- '
👋
' +
- '
Hello from a Surface
' +
- '
Waiting for app init…
' +
- '
' +
- '
' +
- '