core/docs/ROADMAP.md

Roadmap — Chat Switchboard

See also:

• ARCHITECTURE.md — Core services design, store layer, scope model
• EXTENSIONS.md — Extension system spec (Browser/Starlark/Sidecar tiers, manifests, browser tool bridge, surfaces/modes, model roles)
• EXTENSION-SURFACES.md — Extension surface authoring guide (manifest format, platform API, CSS properties, install workflow)
• CHANGELOG.md — Detailed release notes for all completed versions

Versioning (pre-1.0): 0.<major>.<minor> — hotfixes use quad: 0.x.y.z No compatibility guarantees before 1.0.

---

Dependency Graph

Two parallel implementation tracks converge at v0.50.0 (MVP). The extension track builds the package ecosystem and workflow capabilities. The operations track builds production readiness for multi-team deployment. Neither blocks the other until the MVP gate.

v0.9.x–v0.28.7  Foundation through Platform Polish          ✅
                 (see CHANGELOG.md for full history)
                        │
                  v0.28.8  ICD Green Board                   ✅
                        │
        ┌───────────────┼───────────────┐
        │               │               │
   Extension Track  UI Rewrite     Operations Track
        │            Track              │
   v0.29.0  ✅       │            v0.32.0  ✅
   v0.29.1  ✅       │            v0.33.0  ✅
   v0.29.2  ✅       │            v0.34.0  ✅
   v0.29.3  ✅       │                 │
   v0.30.0  ✅       │                 │
   v0.30.1  ✅       │                 │
   v0.30.2  ✅       │                 │
   v0.31.0  ✅       │                 │
   v0.31.1  ✅       │                 │
   v0.31.2  ✅       │                 │
        │            │            v0.35.0 Workflow Product
        │            │                 │
        │            │            v0.36.0 Full OpenAPI  ✅
        │            │                 │
        │       v0.37.1 Perm Audit ✅  │
        │       v0.37.2 Primitives ✅  │
        │       v0.37.3 SDK  ✅        │
        │       v0.37.4 Shell  ✅      │
        │       v0.37.5–16 Surfaces ✅  │
        │       v0.37.17–18 Surfaces ✅ │
        │       v0.37.19    Tag         │
        │            │                 │
        │       v0.38.x Workflow        │
        │         Product Maturity      │
        │            │                 │
   v0.39.0           │                 │
   v0.39.1           │                 │
   v0.39.2           │                 │
   v0.39.3           │                 │
        │            │                 │
  ══════╪════════════╪═════════════════╪══════
        │         MVP v0.50.0          │
        │  (all three tracks complete  │
        │   + mobile + deploy docs)    │
  ══════╪════════════╪═════════════════╪══════
        │
   v0.50.0+ Rich Media + Beyond
     (image gen, code sandbox,
      STT/TTS, desktop app)

Completed Versions (see CHANGELOG.md for details)

Version	Summary
v0.28.0–v0.28.8	Platform polish, ICD green board, security, infrastructure
v0.29.0–v0.29.3	Extension track: Starlark sandbox, API extensions, DB extensions, workflow forms
v0.30.0–v0.30.2	Package lifecycle, SDK adoption, workflow packages
v0.31.0–v0.31.2	Editor package, SDK composability, team workflow self-service
v0.32.0	Multi-replica HA (PG SKIP LOCKED, cross-pod WS, shared tickets/rate limits)
v0.33.0	Observability (slog, Prometheus, Grafana, OpenAPI, admin dashboard)
v0.34.0	Data portability (export/import, GDPR, backup/restore)
v0.35.0	Workflow product (forms, data pipeline, conditional routing, structured review)
v0.36.0	Full OpenAPI spec (20 ICD domains, auth docs, WebSocket schemas)

---

UI Rewrite Track

Scorched earth rebuild of the frontend on Preact+htm. Three-layer architecture (Primitives → SDK → Shell) replacing the imperative DOM manipulation codebase. See UI redesign.md for full design doc.

Depends on: v0.36.0 (OpenAPI spec), v0.31.2 (SDK composability).

v0.37.1 — Permission Audit & Enforcement ✅

Backend prerequisite for frontend RBAC. See CHANGESET.md.

• RequirePermission middleware on 8 unprotected routes
• GET /profile/permissions — self-service resolved permission set
• 12 permission enforcement integration tests (deny → grant → allow)
• Mirror route fixes in integration test harness

v0.37.2 — Layer 0: UI Primitives + Shell Layout ✅

Preact+htm component library and application frame.

• Vendor: preact.module.js, hooks.module.js, htm.module.js (~5KB total)
• 14 primitive components: Button, Spinner, Avatar, FormField, Tooltip, Banner, Toast, Dialog, Confirm, Prompt, Menu, Drawer, Tabs, Dropdown
• AppShell layout: fixed top/bottom banners (single config), dismissible message bar, footer, surface viewport
• sw-primitives.css + sw-shell.css — sw- prefixed, no conflicts with existing styles
• dev.html — interactive primitives gallery + shell controls
• ES module loading with window.preact/hooks/html globals

v0.37.3 — Layer 1: SDK ✅

Namespaced REST client, auth module, RBAC gate, event bus, pipe/filter pipeline, theme control.

Depends on: v0.37.2.

• sw.api.{domain}.* — 18 namespaced domain clients (auth, channels, personas, knowledge, notes, projects, workspaces, memory, models, providers, notifications, extensions, profile, teams, workflows, tasks, surfaces, admin)
• sw.auth.* — login, logout, refresh, session lifecycle, permissions/teams/policies cache
• sw.can(perm) — synchronous RBAC gate from cached permission set
• sw.on/off/emit — event bus with wildcard patterns, WebSocket connection with ticket-first auth
• sw.pipe.* — carry forward pre-send/stream/render pipeline
• sw.theme.* — theme control with FOUC prevention

v0.37.4 — Layer 2: Shell ✅

Application frame with user menu, surface viewport, banners, toast/dialog stacks. Temp auth bypass for visual validation.

Depends on: v0.37.3.

• Root <App> component tree (AppShell + SurfaceViewport + ToastContainer + DialogStack)
• UserMenu — avatar + flyout (Settings, Admin, Team Admin, Debug, Sign Out) with RBAC gating
• SurfaceViewport — mount point for active surface
• ToastContainer + DialogStack — global overlay management
• sw.userMenu(container, opts) — imperative mount helper for non-Preact surfaces

v0.37.5 — Login + Settings Surfaces ✅

First surface rebuilds. Login page and Settings surface converted from Go templates + imperative DOM JS to Preact component trees.

Depends on: v0.37.4.

• Login surface — 5 components (Hero, LoginForm, RegisterForm, SSOPanel, LoginSurface root)
• Settings surface — framework with nav + section routing
• 7 Preact sections: General, Appearance, Profile, Models, Teams, Providers (stub), Personas (stub)
• Bridge pattern for deferred sections (Tasks, Git Keys, Workflows, Data & Privacy)
• sw.toast() SDK wiring, nav gating (BYOK + Personas)
• sw-login.css extracted from inline styles

Known issues (tracked in CHANGELOG, resolve before v0.37.# tag):

• BYOK sections not tested with policy enabled
• Bridge sections Resolved in v0.37.7 (all settings sections native Preact)
• ui-settings.js + settings-handlers.js Confirmed deleted, stale sw.js references cleaned in v0.37.12

v0.37.6–v0.37.18 — Remaining Surface Rebuilds

Each surface rebuilt as Preact component tree. Old JS deleted per surface.

Version	Surface	Notes
v0.37.6	Admin	Largest section count, no real-time
v0.37.7	Team Admin	Inherits from Admin patterns
v0.37.8	ChatPane ✅	Composable kit (9 files), standalone stripped from old chat-pane.js
v0.37.9	NotesPane ✅	Obsidian-grade kit (10 files), old notes code scorched (~1,630 lines)
v0.37.10	Chat surface ✅	Scorched earth: 21 files deleted (−12,841 net), Preact surface + ChatPane kit upgrades
v0.37.11	Notes surface ✅	Preact surface (7 JS + 1 CSS), sidebar folders/tags, UserMenu, template rewrite, Menu primitive fix
v0.37.12	Scorched Earth II ✅	23 files deleted (~2,600 lines): 9 JS, 6 CSS, 8 admin templates; sw.js + base.html cleaned
v0.37.13	Scorched Earth III ✅	5 JS deleted (−2,269 lines): ui-primitives, code-editor, file-tree, user-menu, app-state; SDK slimmed, Theme→Preact
v0.37.14	SE IV + Pane audit ✅	4 JS deleted (~−1,672 lines); double-unwrap cleanup (93 sites); API envelope normalization (18 Go handlers); thinking tags persistence; deleteMessage endpoint; extension surface user menu fix; 7 bug fixes
v0.37.15	Workflow surfaces ✅	Workflow ownership/lifecycle, stage CRUD, team-admin tabs, assignments queue
v0.37.16	Projects surface ✅	Card grid + detail, inline ChatPane, context menu, sidebar pickers, deep-link
v0.37.17	Workspaces ✅	Workspace-first project file storage, tree browser UI, archive upload/download
v0.37.18	Debug / model surface ✅	Debug modal Preact rebuild (CR P2-5), default workspace, tool_output auto-save, save-to-workspace bridge, model/provider polish
v0.37.19	Tag	Light mode CSS audit, dead code hunt, all features verified; sw.can() RBAC gates across surfaces (CR P2-1), __USER__/__PAGE_DATA__ removal (CR P2-4), _getScale → sw.shell.getScale() (CR P3-3)

v0.37.14 — Scorched Earth IV + Pane Audit ✅ (10 sessions, v0.37.14.0–.22):

Scorched Earth IV (4 JS deleted, ~−1,672 lines), unified sidebar with nested folders + DnD, notification bell, @mentions, typing indicators, member panel, double-unwrap cleanup (93 sites), API envelope normalization (18 Go handlers), thinking tags persistence, deleteMessage endpoint, 6 bug fixes. Cumulative scorched earth: 53 files, ~−19,382 lines.

v0.37.15 — Workflow Ownership & Lifecycle:

Team-admin workflow management as first-class path. See DESIGN-0.37.15 for full design. Instance cancel/unclaim/reassign, stage CRUD FE wiring, team-admin workflow queue + stage editor + instance monitor surfaces.

v0.37.16 — Projects Surface ✅:

Card-grid list + two-column detail (inline ChatPane, context menu, sidebar pickers, star toggle, deep-linking). UserMenu in header. Backend was already complete (16+2 endpoints, 18 SDK methods). File upload UI wired but backend storage deferred to v0.37.17.

v0.37.17 — Workspaces (File Storage):

Workspace-first file management for projects. Architecture: files table + objStore = ephemeral message attachments; Workspace FS = persistent file collections (tree, dirs, archive, quota, indexing). Bridge ("Save to workspace") deferred to v0.37.18.

Schema and model FK already exist (workspaces table, Project.WorkspaceID). Workspace backend fully implemented (FS layer, handlers, store, SDK). This version bridges projects to workspaces and builds the file browser UI. Git integration (clone, pull, branch tracking) is optional/post-MVP.

• Auto-create workspace for project on first file upload
• Route project file uploads through workspace FS
• File browser UI in project sidebar (tree, folders, download, delete)
• Archive upload: zip/tar extraction into workspace
• Archive download: zip bundle of project files
• Storage quota enforcement (max_bytes on workspace)

v0.37.18 — Debug + Model Surface ✅:

Debug modal Preact rebuild (673-line imperative → component tree, 8 files). User default workspace (auto-create "My Files" on first access). tool_output auto-save (file refs linked to assistant messages). Save-to-workspace bridge (save code blocks to workspace). Model selector health dots. Provider test buttons (BYOK + admin). repl.js absorbed into Preact. sw-debug.css extracted.

v0.37.19 — Tag ("UI Complete"):

sw.can() RBAC gates, __USER__/__PAGE_DATA__ removal, _getScale SDK, light mode CSS audit, dead code hunt. Every capability has a UI.

---

v0.38.x — Workflow Product Maturity

See ROADMAP-0.38 for full version plan.

Visual workflow builder series. Bridges .37 plumbing to MVP gate ("team admins build workflows visually").

Version	Summary	MVP Role
v0.38.0	Form Builder	Blocker — visual field editor replaces JSON textarea
v0.38.1	Stage Reorder + Bulk Ops	DnD reorder, multi-select operations
v0.38.2	SLA Alerting	Scheduled scanner, breach notifications
v0.38.3	Visitor Experience	Branding, progress indicator, email notifications
v0.38.4	Workflow Templates + Clone	5 built-in templates, deep copy
v0.38.5	Analytics Dashboard	Throughput, cycle time, SLA compliance

---

v0.39.x — Extension Track Continuation

Resumes the extension track (v0.29–v0.31 ✅) with three new platform primitives: multi-file Starlark packages, extension connections, and library packages. See design docs for full specifications.

Version	Summary	Design Doc
v0.39.0	Multi-file Starlark	DESIGN-MULTI-FILE-STARLARK.md — load() support, disk-based scripts, package-scoped loader. Prerequisite for libraries. 5 backend changesets.
v0.39.1	Extension Connections	DESIGN-EXT-CONNECTIONS-LIBRARIES.md Part 1 — ext_connections table, scoped CRUD (personal → team → global resolution), connections Starlark module, 3 management UIs.
v0.39.2	Library Packages	Part 2 — library package type, ext_dependencies table, lib.load() with per-library permission context, dependency resolution, uninstall protection.
v0.39.3	Full Composition	Part 3 — Libraries declare connection types for consumers, reference gitea-client library, migrate git-board to library-backed surface.

---

MVP v0.50.0

Gate: deploy for 5–10 teams, ~50 users, 100+ anonymous visitors on a 3-node cluster. An IT team can operate the platform without reading Go source code. Team admins build workflows visually.

Requires all of:

• Extension track through v0.31.2 (full package ecosystem, visual workflow builder, SDK-based surfaces, team workflow self-service)
• Operations track through v0.34.0 (multi-replica HA, observability, data portability) ✅
• Workflow product v0.35.0 (form rendering, data pipeline, conditional routing, structured review, monitoring dashboard)
• Full OpenAPI spec v0.36.0 (complete API documentation for all domains)

Additionally requires:

• Deployment guide: step-by-step for IT team (PG cluster, S3/MinIO, CephFS/NFS, Helm install, TLS, OIDC)
• Admin guide: team setup, provider config, workflow creation, package management, backup/restore
• Mobile-responsive layouts (proper mobile navigation, touch-optimized chat, not just CSS responsive)
• Project creation dialog (v0.37.16, sw.prompt-based)
• Admin-level project management (cross-instance visibility)

---

v0.50.0+ — Rich Media + Beyond

Post-MVP. Each item is a standalone .pkg or platform primitive. No ordering constraints between items.

Media + Generation

• Image generation tool (browser or sidecar, provider-agnostic)
• STT input (browser extension, Web Speech API)
• TTS output (browser extension, provider API)
• Code execution sandbox (server-side, container isolation)

Desktop + Mobile

• Desktop app (Tauri — native wrapper around existing web UI)
• Full PWA with offline capability

Platform

• Multi-tenant SaaS mode (tenant isolation, billing, onboarding)
• Surface IDE (built-in surface for building surfaces)
• Sidecar HTTP tool protocol (container-isolated tool execution)
• Latency-aware provider routing (response time percentiles)
• Cost-aware routing with budget ceiling per request
• Fallback chain visualizer (drag-to-reorder provider priority)

Knowledge + Memory

• Hybrid KB search (vector + tsvector + re-rank)
• Semantic chunking (embedding-based boundary detection)
• HNSW index (replaces IVFFlat for large datasets)
• Web scraping KB source (ingest URLs via url_fetch)
• Scheduled re-indexing (periodic rebuild when sources update)
• Memory export/import (portable format across instances)
• Cross-persona memory sharing (opt-in)
• Memory analytics dashboard

Projects

• /p/:id shared project view (public/team-scoped read-only link)
• Project templates (predefined configurations)
• Sub-projects / nested hierarchy
• Git integration (clone, pull, branch tracking — optional workspace feature)

UX

• "Group" scope badge on model selector / KB list
• Article drag-to-reorder outline sections
• Article AI tools (suggest_outline, expand_section, check_citations)
• Rate limiting per user/team/tier (token budgets)