diff --git a/CHANGELOG.md b/CHANGELOG.md
index 429e3b4..9262e58 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,5 +1,57 @@
 # Changelog
 
+## [0.36.0] — 2026-03-20
+
+### Summary
+
+Full OpenAPI 3.0.3 specification covering all API domains. Expands the
+hand-curated spec from v0.33.0 (12 endpoints) to 296 paths / 216
+operations across all ICD-documented domains. Documents Bearer JWT,
+mTLS, and OIDC auth modes. Adds reusable schemas, error responses,
+and pagination parameters.
+
+### New
+
+- **OpenAPI spec expanded to 296 paths** — up from 12 endpoints.
+  Covers: Auth (builtin + OIDC), Profile & Settings, Channels (CRUD,
+  participants, models, KB bindings, presence, folders, typing,
+  summarize, title generation), Messages (tree walk, edit, regenerate,
+  siblings, cursor), Completions (streaming + non-streaming), Files
+  (upload, download, metadata, message files), Personas (3-scope CRUD,
+  avatars, KB bindings, tool grants, persona groups), Models (enabled
+  list, preferences, bulk), Providers (BYOK CRUD, model sync), Notes
+  (CRUD, search, graph, backlinks, bulk delete), Knowledge Bases
+  (CRUD, documents, search, rebuild, discoverable), Memory (CRUD,
+  approve/reject, count, compact), Projects (CRUD, channels, KBs,
+  notes, files, reorder), Workspaces (CRUD, file ops, archive, git),
+  Git Operations (clone, pull, push, status, diff, commit, log,
+  branches, checkout), Git Credentials, Tasks (CRUD, runs, kill),
+  Workflows (CRUD, stages, publish, versions, instances, advance,
+  reject), Workflow Assignments (list, claim, complete, comment),
+  Workflow Forms (template, submit, visitor entry), Notifications
+  (CRUD, preferences, unread count), Data Portability (export, import,
+  ChatGPT import, GDPR delete), Webhook triggers, Health probes,
+  Metrics, WebSocket tickets.
+- **29 reusable component schemas** — AuthResponse, AuthUser,
+  UserProfile, Channel, Message, Participant, FileObject, ToolDef,
+  CompletionRequest/Response, TokenUsage, PersonaInput,
+  ProviderConfigInput, ProviderHealth, ErrorResponse, MessageResponse.
+- **Standardized error responses** — 400, 401, 403, 404, 409, 429
+  with $ref reuse across all paths.
+- **Security scheme documentation** — bearerAuth (JWT, 15m TTL) and
+  mtlsAuth (mutual TLS via proxy headers).
+- **Reusable parameters** — ResourceID, Page, PerPage for consistent
+  pagination across all list endpoints.
+- **25 domain tags** pre-declared for Swagger UI navigation.
+- **AuthResponse schema corrected** — `access_token` (was incorrectly
+  `token`), added `token_type`, `expires_in`, `handle`, `auth_source`.
+- **Login endpoint corrected** — field is `login` (accepts username
+  or email), not `username`.
+
+### Changed
+
+- `server/static/openapi.yaml` — complete rewrite (643 → 11845 lines)
+
 ## [0.35.1] — 2026-03-20
 
 ### Summary
diff --git a/VERSION b/VERSION
index 731b95d..93d4c1e 100644
--- a/VERSION
+++ b/VERSION
@@ -1 +1 @@
-0.35.1
+0.36.0
diff --git a/docs/DESIGN-0.28.5.md b/docs/DESIGN-0.28.5.md
deleted file mode 100644
index 4838db6..0000000
--- a/docs/DESIGN-0.28.5.md
+++ /dev/null
@@ -1,754 +0,0 @@
-# DESIGN — v0.28.5: Frontend SDK + Pipe/Filter Pipeline
-
-**Status:** Draft
-**Scope:** `switchboard-sdk.js`, pipe/filter pipeline, extension compat shims, ICD `sdk` test tier
-**Depends on:** v0.28.4 (security tier), v0.28.3 (frontend decomposition — `sb.js`, IIFE→module, `sb.call()`)
-**Informs:** v0.28.7 (unified packaging — manifest `"pipes"` key), v0.29.0+ (Starlark pipeline stages)
-**Current version:** 0.28.4
-
----
-
-## Overview
-
-The platform has 47 JS files, 15+ globals (`API`, `Events`, `UI`, `App`,
-`Extensions`, `ChatPane`, `Theme`, etc.), and a partially-decomposed
-frontend (Phase 4 ES modules, `sb.register()`/`sb.ns()` action registry).
-Surface authors and extension authors must hunt through multiple files,
-understand load order, and hold implicit coupling in their heads.
-
-v0.28.5 delivers two things:
-
-1. **`switchboard-sdk.js` (the SDK)** — a single-object composition layer
-   (`sw`) over existing globals. One import, one init call, coherent API.
-   Does not rewrite internals; wraps and delegates.
-
-2. **Pipe/filter pipeline** — three composable, priority-ordered transform
-   stages that formalize the ad-hoc extension hooks into a real pipeline:
-   pre-send → post-receive (stream) → post-render. Extensions register
-   filters; the SDK wires them. Replaces `ctx.renderers.register()` and
-   the implicit hook points in `chat.js` / `ui-core.js` / `ui-format.js`.
-
----
-
-## Design Principles
-
-**Wrap, don't rewrite.** The SDK delegates to `API`, `Events`, `UI`, `App`,
-`Theme`, `Extensions`, `ChatPane`. It does not duplicate their logic. If
-`API.streamCompletion()` changes, the SDK's `sw.api.post()` still works
-because it calls through. This means v0.28.5 doesn't risk destabilizing
-the 531 passing CI tests.
-
-**The pipeline is the extension model.** The existing six hooks in
-DESIGN-SURFACES.md (Stream Processing, Post-Render, Tool Bridge, etc.)
-are replaced by three pipe stages plus the existing tool bridge. The old
-`ctx.renderers.register()` becomes a compat shim that registers into
-`sw.pipe.render()`. New extensions use `sw.pipe.*` directly.
-
-**Filters are pure transforms.** A filter receives a context object and
-returns it (possibly modified). Side effects are allowed (logging, metrics)
-but the contract is input→output. This makes filters testable in isolation.
-
-**Priority ordering is explicit.** Every filter declares a numeric priority.
-Lower runs first. Ties break by registration order. The SDK enforces this
-and exposes introspection (`sw.pipe.list()`).
-
-**Error isolation is mandatory.** One filter throwing must not break the
-chain. The SDK catches, logs, records the failure in telemetry, and
-continues with the next filter. A filter can explicitly halt the chain
-by returning `null` (pre-send: message suppressed) or a `{ halt: true }`
-signal.
-
----
-
-## SDK API Reference
-
-### Boot
-
-```js
-// Idempotent. Safe to call multiple times (returns same instance).
-// Typically called by the surface boot script after DOMContentLoaded.
-const sw = Switchboard.init({ mount: '#app' });
-```
-
-`init()` performs:
-1. Token load (`API.loadTokens()`)
-2. Profile resolution (`API.getProfile()`)
-3. Theme init (`Theme.init()`)
-4. EventBus connection (`Events.connect()`)
-5. Pipeline engine init (empty filter chains)
-6. UserMenu hydration (absorbs cs15 band-aid)
-7. Emits `sw:ready` event on `document`
-
-If already initialized, returns the existing `sw` instance. The `mount`
-option is reserved for future component auto-mounting but is not used in
-v0.28.5 (surfaces manage their own DOM).
-
-### Identity
-
-```js
-sw.user          // { id, username, display_name, email, role, avatar }
-sw.isAdmin       // boolean (shorthand for sw.user.role === 'admin')
-```
-
-Read-only. Resolved during `init()`. Updates on `profile.updated` event.
-
-Delegates to: `API.user`, `API.isAdmin`.
-
-### REST Client
-
-```js
-const channels = await sw.api.get('/api/v1/channels');
-const created  = await sw.api.post('/api/v1/channels', { title, model });
-const updated  = await sw.api.put('/api/v1/channels/123', { title });
-const deleted  = await sw.api.del('/api/v1/channels/123');
-
-// Streaming (returns raw Response for SSE consumption)
-const resp = await sw.api.stream('/api/v1/chat/completions', body, signal);
-```
-
-All methods auto-prefix `BASE_PATH`, inject auth headers, handle 401
-refresh, and parse JSON. `sw.api.stream()` returns the raw `Response`
-for SSE reading (same contract as `API.streamCompletion()` but generic).
-
-Delegates to: `API._get()`, `API._post()`, `API._put()`, `API._delete()`,
-`API._fetch()`.
-
-### Events
-
-```js
-const unsub = sw.on('chat.message.*', (payload, meta) => { ... });
-sw.once('workflow.completed', (payload) => { ... });
-sw.emit('custom.event', { data: 42 });
-sw.off('chat.message.*', handler);
-```
-
-Thin passthrough to `Events.on/once/off/emit`. No behavior change.
-The SDK does not add any event namespacing — extensions already namespace
-by convention (`ext.{id}.{event}`).
-
-Delegates to: `Events`.
-
-### Components
-
-```js
-// Drop-in ChatPane — creates the component in the container
-const pane = sw.chat(document.getElementById('myChat'), {
-    channelId: 'abc123',
-    standalone: true,
-});
-pane.renderMessages(messages);
-pane.destroy();
-
-// Drop-in notes panel
-const notes = sw.notes(document.getElementById('myNotes'), {
-    projectId: 'proj-1',
-});
-```
-
-`sw.chat()` wraps `ChatPane.create()` with SDK-aware defaults (auto-wires
-pipe filters into the pane's stream/render path). `sw.notes()` wraps the
-notes panel initialization from `notes.js`.
-
-Delegates to: `ChatPane.create()`, notes init functions.
-
-### UI Primitives
-
-```js
-sw.toast('Saved', 'success');           // UI.toast()
-const ok = await sw.confirm('Delete?'); // showConfirm()
-sw.modal.open(contentEl);               // openModal()
-sw.modal.close();                       // closeModal()
-```
-
-Delegates to: `UI.toast()`, `showConfirm()`, `openModal()`, `closeModal()`.
-
-### Theme
-
-```js
-sw.theme.current       // 'dark' | 'light' (resolved, never 'system')
-sw.theme.mode          // 'dark' | 'light' | 'system' (user preference)
-sw.theme.set('dark');  // Theme.set()
-sw.theme.on('change', (resolved) => { ... });
-```
-
-`sw.theme.on('change', fn)` subscribes to the `theme.changed` EventBus
-event and fires with the resolved theme string.
-
-Delegates to: `Theme.get()`, `Theme.resolved()`, `Theme.set()`, `Events.on('theme.changed', ...)`.
-
----
-
-## Pipe/Filter Pipeline
-
-### Architecture
-
-```
-User types message
-        │
-        ▼
-┌─────────────────┐
-│  PRE-SEND chain │   sw.pipe.pre(priority, fn)
-│  filter₁ → ··· → filterₙ
-└────────┬────────┘
-         │ context: { message, channel, attachments, model, persona, metadata }
-         ▼
-   API.streamCompletion()
-         │
-         ▼ SSE chunks
-┌─────────────────┐
-│  STREAM chain   │   sw.pipe.stream(priority, fn)
-│  filter₁ → ··· → filterₙ    (per chunk)
-└────────┬────────┘
-         │ context: { chunk, accumulated, channel, model, tokens }
-         ▼
-   formatMessage() → DOMPurify
-         │
-         ▼ rendered HTML
-┌─────────────────┐
-│  RENDER chain   │   sw.pipe.render(priority, fn)
-│  filter₁ → ··· → filterₙ
-└────────┬────────┘
-         │ context: { element, message, channel }
-         ▼
-   DOM inserted
-```
-
-### Registration API
-
-```js
-// Pre-send: transform message before it hits the server
-sw.pipe.pre(10, (ctx) => {
-    // Inject KB context
-    ctx.metadata.kb_chunks = getRelevantChunks(ctx.message);
-    return ctx;
-});
-
-// Pre-send with scope: only run on workflow channels
-sw.pipe.pre(20, (ctx) => {
-    // Auto-tag workflow messages with stage metadata
-    ctx.metadata.workflow_stage = ctx.channel.stage;
-    return ctx;
-}, { scope: { channelType: ['workflow'] } });
-
-// Post-receive: transform each SSE chunk during streaming
-sw.pipe.stream(50, (ctx) => {
-    // Token counting
-    tokenCounter.add(ctx.chunk);
-    ctx.tokens = tokenCounter.total;
-    return ctx;
-});
-
-// Post-render: transform rendered DOM
-sw.pipe.render(50, (ctx) => {
-    // Replace mermaid code blocks with rendered diagrams
-    ctx.element.querySelectorAll('pre code.language-mermaid').forEach(el => {
-        renderMermaid(el);
-    });
-    return ctx;
-});
-
-// Post-render scoped to DMs only
-sw.pipe.render(60, (ctx) => {
-    // Highlight @mentions differently in DMs
-    highlightDmMentions(ctx.element);
-    return ctx;
-}, { scope: { channelType: ['dm'] } });
-
-// Introspection
-sw.pipe.list();
-// → { pre: [{priority, source, scope, avgMs}], stream: [...], render: [...] }
-```
-
-### Filter Contract
-
-```typescript
-// Type definitions (for documentation — runtime is plain JS)
-
-interface PreSendContext {
-    message: string;              // User's text (mutable)
-    channel: { id: string; type: string; title: string };
-    attachments: string[];        // File IDs
-    model: string;                // Selected model ID
-    persona: string | null;       // Persona ID if active
-    metadata: Record<string, any>; // Extensible metadata bag
-    regenerate: boolean;          // true if this is a regeneration
-    regenerateMessageId: string | null; // message ID being regenerated
-}
-
-interface StreamContext {
-    chunk: string;                // Current SSE delta text
-    accumulated: string;          // Full response so far
-    channel: { id: string; type: string };
-    model: string;
-    event: string;                // SSE event type (content, tool_use, etc.)
-    tokens: { input: number; output: number }; // Running count
-}
-
-interface RenderContext {
-    element: HTMLElement;          // The message container DOM node (mutable)
-    message: { role: string; content: string; id?: string };
-    channel: { id: string; type: string };
-}
-
-// Filter scope — restricts which channels a filter runs on.
-// Omit or pass null for "all channels" (default).
-interface FilterScope {
-    channelType?: string[];       // ['direct','dm','group','channel','workflow','service']
-}
-
-// Registration options (third argument to sw.pipe.pre/stream/render)
-interface FilterOpts {
-    scope?: FilterScope;          // Channel type restriction
-    source?: string;              // Label for introspection (defaults to extension ID or 'platform')
-}
-
-// All filters are synchronous. Return context to continue, null to halt.
-type PipeFilter<T> = (ctx: T) => T | null;
-```
-
-### Halt Semantics
-
-**Pre-send:** Returning `null` suppresses the message entirely. The SDK
-calls `UI.toast('Message blocked by extension', 'warning')` and does not
-call `API.streamCompletion()`. Use case: content policy filter.
-
-**Stream:** Returning `null` drops the current chunk (not displayed). The
-accumulated buffer is unchanged. Use case: real-time content filter that
-strips sensitive data from the stream.
-
-**Render:** Returning `null` skips remaining render filters for this
-message. The DOM stays as-is after the last successful filter. Unusual
-but available for guard-rail extensions.
-
-### Timing Telemetry
-
-The pipeline engine records per-filter execution time (monotonic clock).
-Available via `sw.pipe.list()` and emitted on `pipe.stats` EventBus event
-every 60 seconds (if any filters ran). Format:
-
-```json
-{
-    "pre":    [{ "source": "kb-inject", "priority": 10, "calls": 47, "avgMs": 2.3, "errors": 0 }],
-    "stream": [{ "source": "token-counter", "priority": 50, "calls": 12840, "avgMs": 0.1, "errors": 0 }],
-    "render": [{ "source": "mermaid", "priority": 50, "calls": 47, "avgMs": 15.7, "errors": 1 }]
-}
-```
-
-### Filter Scoping
-
-Filters declare an optional `scope` at registration time. The pipeline
-engine checks scope before invoking a filter — scoped-out filters are
-skipped with zero overhead (no function call, no timing entry).
-
-```js
-// Only run on workflow and service channels
-sw.pipe.pre(10, myFilter, { scope: { channelType: ['workflow', 'service'] } });
-
-// Only run on direct (1:1 AI) chats
-sw.pipe.stream(50, tokenCounter, { scope: { channelType: ['direct'] } });
-
-// No scope = runs on everything (default)
-sw.pipe.render(50, mermaidRenderer);
-```
-
-**Channel types** (from the `channels` table `type` column):
-`direct`, `dm`, `group`, `channel`, `workflow`, `service`.
-
-**Scope evaluation:** Before each filter call, the engine reads
-`ctx.channel.type` and checks against the filter's `scope.channelType`
-array. If the type is not in the array, the filter is skipped. If the
-filter has no scope (or `scope` is `null`), it always runs.
-
-**Introspection:** `sw.pipe.list()` includes the `scope` object for
-each filter so extensions can inspect which filters apply to their
-channel type.
-
-**Manifest mapping (v0.28.7):** The `"pipes"` manifest key will support
-the same `scope` object:
-
-```json
-{
-    "pipes": [
-        {
-            "stage": "pre",
-            "priority": 10,
-            "handler": "filters.kbInject",
-            "scope": { "channelType": ["direct", "dm", "group"] }
-        }
-    ]
-}
-```
-
----
-
-## Integration Points
-
-### Pre-send: `chat.js` → `sendMessage()` + `regenerateMessage()`
-
-**`sendMessage()` — current flow (chat.js line ~659):**
-```
-text = ChatInput.getValue()
-→ build body
-→ API.streamCompletion(channelId, text, model, ...)
-```
-
-**`sendMessage()` — new flow:**
-```
-text = ChatInput.getValue()
-→ build PreSendContext { message, channel, ..., regenerate: false }
-→ sw.pipe._runPre(context)         // returns modified context or null
-→ if null: toast + return
-→ API.streamCompletion(ctx.channel.id, ctx.message, ctx.model, ...)
-```
-
-**`regenerateMessage()` — current flow (chat.js line ~835):**
-```
-messageId from clicked button
-→ API.streamRegenerate(channelId, messageId, model, ...)
-```
-
-**`regenerateMessage()` — new flow:**
-```
-messageId from clicked button
-→ build PreSendContext { message: '', channel, ..., regenerate: true, regenerateMessageId: messageId }
-→ sw.pipe._runPre(context)
-→ if null: toast + return
-→ API.streamRegenerate(ctx.channel.id, messageId, ctx.model, ...)
-```
-
-Both paths share the same filter chain. The `regenerate` flag and
-`regenerateMessageId` let filters distinguish — a content policy filter
-runs on both, a KB inject filter might skip regeneration (the original
-context is already in the conversation), a logging filter records both.
-
-The `sendMessage()` function gains ~10 lines. `regenerateMessage()` gains
-~8 lines. Extracted helper: `_buildPreSendContext(opts)` constructs the
-context object for both callers.
-
-**Metadata passthrough:** The `metadata` bag on `PreSendContext` maps to
-the completion request body. Pre-send filters can inject KB chunks,
-persona instructions, or custom fields that the backend completion
-handler reads from the request. KB auto-inject (v0.28.6) will be the
-first platform-level filter using this mechanism.
-
-### Post-receive (stream): `ui-core.js` → `UI.streamResponse()`
-
-Current flow (ui-core.js line ~1060):
-```
-SSE reader loop:
-  parse chunk → extract delta
-  content += delta
-  activeContentEl.innerHTML = formatMessage(content)
-```
-
-New flow:
-```
-SSE reader loop:
-  parse chunk → extract delta
-  streamCtx = { chunk: delta, accumulated: content, ... }
-  streamCtx = sw.pipe._runStream(streamCtx)
-  if streamCtx is null: continue (chunk dropped)
-  content = streamCtx.accumulated     // filter may have mutated
-  activeContentEl.innerHTML = formatMessage(content)
-```
-
-The pipe runs synchronously per chunk (filters that need async should
-buffer internally). The `accumulated` field lets filters see the full
-response so far (for context-dependent transforms like citation
-injection that need to see paragraph boundaries).
-
-**Performance:** Stream filters run on every SSE chunk (potentially
-hundreds per response). The telemetry tracks per-filter avgMs. Filters
-exceeding 5ms average get a console warning. The pipeline engine skips
-disabled filters without allocation.
-
-### Post-render: `ui-format.js` + `ui-core.js`
-
-Current flow:
-```
-formatMessage(content)               // marked.js + DOMPurify
-→ Extensions.runBlockRenderers()     // inside formatMessage, per code block
-→ el.innerHTML = html
-→ runExtensionPostRender(el)         // Extensions.runPostRenderers()
-```
-
-New flow:
-```
-formatMessage(content)               // unchanged
-→ el.innerHTML = html
-→ renderCtx = { element: el, message, channel }
-→ sw.pipe._runRender(renderCtx)      // subsumes runExtensionPostRender
-```
-
-The render pipe replaces both `Extensions.runBlockRenderers()` and
-`Extensions.runPostRenderers()`. The distinction between "block" and
-"post" renderer types collapses into a single render stage — filters
-operate on the full message DOM and can target code blocks, inline
-elements, or the entire container.
-
-**Block renderer compat:** Extensions that register block renderers via
-the old `ctx.renderers.register(name, { type: 'block', ... })` API get
-automatically shimmed into `sw.pipe.render()` filters. The shim wraps
-the old `(lang, code, container)` signature into the new
-`(renderCtx) => ...` contract. Priority is preserved.
-
----
-
-## Backward Compatibility
-
-### Extension Context Shim
-
-The existing `Extensions._buildContext()` returns a `ctx` object with
-`ctx.renderers.register()`, `ctx.tools.handle()`, `ctx.events.*`,
-`ctx.ui.*`, `ctx.storage.*`, and `ctx.api.*`.
-
-All of these continue to work. The shim layer:
-
-| Old API | Shim behavior |
-|---------|--------------|
-| `ctx.renderers.register(name, { type: 'block', ... })` | Wraps into `sw.pipe.render()` filter with matching priority |
-| `ctx.renderers.register(name, { type: 'post', ... })` | Wraps into `sw.pipe.render()` filter |
-| `ctx.renderers.register(name, { type: 'inline', ... })` | Wraps into `sw.pipe.render()` filter (inline → DOM manipulation) |
-| `ctx.tools.handle(name, fn)` | Unchanged — tool bridge is orthogonal to pipes |
-| `ctx.events.*` | Unchanged — passthrough to `Events` |
-| `ctx.ui.*` | Unchanged — passthrough to `UI` / `showConfirm` / `Theme` |
-| `ctx.storage.*` | Unchanged — scoped `localStorage` |
-| `ctx.api.*` | Unchanged — passthrough to `API._fetch` |
-| `ctx.surfaces.*` | Unchanged (already stub/warn for removed features) |
-
-The shim is invisible to existing extensions. They register the same way;
-the pipeline engine sees their filters alongside new `sw.pipe.*` filters
-and orders everything by priority.
-
-### Global Availability
-
-`sb.js` continues to work. `window.API`, `window.Events`, `window.UI`,
-etc. remain available. The SDK is additive — it does not remove globals
-or break direct access. Phase 5 (ES module `import`/`export` migration)
-is when globals start going away, and the SDK becomes the only entry point.
-
-### Load Order
-
-```
-base.html:
-  sb.js              ← action registry (unchanged)
-  app-state.js       ← App, fetchModels (unchanged)
-  api.js             ← API (unchanged)
-  events.js          ← Events (unchanged)
-  ui-primitives.js   ← Theme, showConfirm, etc. (unchanged)
-  ui-format.js       ← formatMessage (patched: render pipe integration)
-  ui-core.js         ← UI (patched: stream pipe integration)
-  switchboard-sdk.js ← NEW: Switchboard object, pipe engine
-  extensions.js      ← Extensions (patched: renderer shim)
-  ... surface-specific JS ...
-  chat.js            ← sendMessage (patched: pre-send pipe)
-  app.js             ← init (patched: calls Switchboard.init)
-```
-
-`switchboard-sdk.js` loads after all primitives/globals it wraps and
-before `extensions.js` (so the shim layer is ready when extensions
-register renderers). `app.js` `init()` calls `Switchboard.init()` as
-part of its boot sequence; the SDK handles idempotency.
-
----
-
-## File Inventory
-
-### New Files
-
-| File | Purpose |
-|------|---------|
-| `src/js/switchboard-sdk.js` | SDK object, pipe engine, compat shims |
-| `surfaces/icd-test-runner/js/tier-sdk.js` | ICD runner `sdk` test tier |
-| `docs/DESIGN-0.28.5.md` | This document (archived after merge) |
-
-### Modified Files
-
-| File | Change |
-|------|--------|
-| `src/js/chat.js` | `sendMessage()`: pre-send pipe insertion |
-| `src/js/ui-core.js` | `streamResponse()`: stream pipe insertion |
-| `src/js/ui-format.js` | `runExtensionPostRender()`: delegates to render pipe |
-| `src/js/extensions.js` | `_registerRenderer()`: shim into `sw.pipe.render()` |
-| `src/js/app.js` | `init()`: call `Switchboard.init()` during boot |
-| `src/templates/base.html` | Add `<script>` for `switchboard-sdk.js` |
-| `surfaces/icd-test-runner/js/main.js` | Register `sdk` tier |
-| `surfaces/icd-test-runner/manifest.json` | Include `tier-sdk.js` |
-
-### No Changes
-
-All other 40+ JS files are untouched. The SDK wraps them; it does not
-modify their internals (except the five patched files above).
-
----
-
-## ICD Test Tier: `sdk`
-
-New tier in the ICD runner. Tests the SDK contract from the browser,
-running against the live platform.
-
-### Test Categories
-
-**Boot:**
-- `Switchboard.init()` returns an `sw` object with expected shape
-- Double-init returns same instance (idempotency)
-- `sw.user` is populated after init
-- `sw.isAdmin` reflects actual role
-- `sw:ready` event fires on `document`
-
-**REST client:**
-- `sw.api.get('/api/v1/health')` returns health object
-- `sw.api.get('/api/v1/channels')` returns `{ data: [...] }` envelope
-- `sw.api.post('/api/v1/channels', {...})` creates and returns channel
-- `sw.api.del('/api/v1/channels/:id')` deletes (204 or JSON)
-- Auth header injection (no manual token management)
-
-**Events:**
-- `sw.on()` receives events emitted by `sw.emit()`
-- `sw.once()` fires exactly once
-- `sw.off()` stops delivery
-- WebSocket events propagate through `sw.on()`
-
-**Theme:**
-- `sw.theme.current` returns 'dark' or 'light'
-- `sw.theme.set('dark')` changes resolved theme
-- `sw.theme.on('change', fn)` fires on toggle
-
-**Pipe registration:**
-- `sw.pipe.pre(10, fn)` registers without error
-- `sw.pipe.stream(50, fn)` registers without error
-- `sw.pipe.render(50, fn)` registers without error
-- `sw.pipe.pre(10, fn, { scope: { channelType: ['direct'] } })` registers with scope
-- `sw.pipe.list()` returns registered filters in priority order with scope
-- Duplicate registration (same source+priority) warns but succeeds
-
-**Pipe execution — pre-send:**
-- Register pre-send filter that appends metadata
-- Send message → filter runs → metadata present in request
-  (verify via round-trip: message persisted, reload, check)
-- Register halt filter (returns null) → message not sent, toast shown
-- Multiple filters → run in priority order
-- Filter throws → error logged, next filter runs, message still sends
-- Regenerate: filter runs with `ctx.regenerate === true`
-
-**Pipe execution — render:**
-- Register render filter that adds a class to message elements
-- Send message → response rendered → class present in DOM
-- Priority ordering: low-priority filter sees high-priority filter's changes
-- Extension compat: `ctx.renderers.register('test', { type: 'post', ... })`
-  → filter appears in `sw.pipe.list()` render chain
-
-**Pipe execution — stream:**
-- Register stream filter that counts chunks
-- Send message → stream completes → filter's counter > 0
-- Stream filter that modifies `accumulated` → rendered content reflects change
-
-**Pipe scoping:**
-- Register filter scoped to `channelType: ['workflow']`
-- Send message on a `direct` channel → filter does NOT run (counter stays 0)
-- Send message on a `workflow` channel → filter runs (counter increments)
-- Unscoped filter runs on all channel types
-- `sw.pipe.list()` shows scope for scoped filters, null for unscoped
-
-**Introspection:**
-- `sw.pipe.list()` returns timing stats after filters have run
-- Stats include `calls`, `avgMs`, `errors`, `scope` per filter
-
-### Test Infrastructure
-
-The `sdk` tier runs after `crud` (needs a channel to send messages into)
-and before `security` (SDK tests assume valid auth). It creates its own
-test channels (at least one `direct`, one `workflow` for scope tests),
-registers ephemeral filters, sends messages, and verifies DOM/API state.
-
-Estimated test count: 30–35 tests.
-
----
-
-## Changeset Plan
-
-### CS1 — SDK Core + Docs
-
-**Files:** `switchboard-sdk.js`, `DESIGN-0.28.5.md`, `base.html`
-**Scope:** SDK object with identity, REST client, events, theme, UI
-primitives, component wrappers. No pipe engine yet. `app.js` calls
-`Switchboard.init()`. All existing tests stay green — no behavior change.
-
-**Validates:** SDK loads, wraps globals, `sw:ready` fires, `sw.api.*`
-works, `sw.theme.*` works. Manual verification: existing surfaces
-boot normally with the new script tag.
-
-### CS2 — Pipe Engine + Integration
-
-**Files:** `switchboard-sdk.js` (pipe engine added), `chat.js`,
-`ui-core.js`, `ui-format.js`, `extensions.js`
-**Scope:** Pipeline execution engine, three filter chains, integration
-into sendMessage/streamResponse/runExtensionPostRender, extension
-renderer compat shim.
-
-**Validates:** Pipe registration works, filters run in order, existing
-block renderers (mermaid, katex, csv, diff) still render via compat
-shim. CI green on both PG and SQLite.
-
-**Breaking change:** `runExtensionPostRender()` now delegates to the
-pipe engine. If an extension relied on `Extensions.runPostRenderers()`
-being called directly (not through `runExtensionPostRender`), it would
-need updating. In practice, all callsites go through `runExtensionPostRender`.
-
-### CS3 — ICD Runner SDK Tier
-
-**Files:** `tier-sdk.js`, `main.js`, `manifest.json`, `fixtures.js`
-(new fixtures for SDK tests)
-**Scope:** Full `sdk` test tier. Delivered as complete `.surface` archive
-(installable via `POST /admin/surfaces/install`).
-
-**Validates:** All SDK contract tests pass against live platform.
-
-### CS4 — VERSION + CHANGELOG + ROADMAP
-
-**Files:** `VERSION`, `CHANGELOG.md`, `ROADMAP.md`
-**Scope:** Version bump to `0.28.5`, changelog entry, roadmap checkboxes.
-
----
-
-## Resolved Decisions
-
-1. **Stream filters are sync-only in v0.28.5.** Filters that need async
-   (e.g., external API calls per chunk) must buffer internally and flush
-   on their own schedule. Async stream filter support revisited if real
-   usage demands it. Rationale: backpressure risk on fast SSE streams is
-   not worth the complexity for MVP.
-
-2. **Pre-send filters run on regenerate.** `regenerateMessage()` runs the
-   same pre-send chain as `sendMessage()`. The `PreSendContext` includes
-   `regenerate: true` and `regenerateMessageId: string` so filters can
-   distinguish. Content policy, KB inject, and all other pre-send filters
-   apply consistently — a filter that only guards new messages but not
-   regenerations would be a security gap.
-
-3. **Per-channel filter scoping ships in v0.28.5.** Filters declare an
-   optional `scope` object at registration time that restricts which
-   channel types they run on. The pipeline engine checks scope before
-   invoking the filter — scoped-out filters have zero overhead (no call,
-   no timing entry). See "Filter Scoping" section below.
-
-4. **KB auto-inject ships as a pipe filter in v0.28.6.** The platform
-   registers a built-in pre-send filter (`_kb-auto-inject`, priority 5)
-   that queries bound knowledge bases, runs top-K chunk retrieval, and
-   prepends context to `ctx.metadata.kb_context`. This is the first
-   real validation that the pipeline handles non-trivial platform-level
-   transforms, not just extension toys.
-
----
-
-## Appendix: Existing Extension Hooks → Pipe Mapping
-
-| DESIGN-SURFACES Hook | Current Implementation | Pipe Equivalent |
-|----------------------|----------------------|----------------|
-| Hook 2: Stream Processing | Not implemented (spec only) | `sw.pipe.stream()` |
-| Hook 3: Post-Render | `ctx.renderers.register(type:'post')` → `Extensions.runPostRenderers()` | `sw.pipe.render()` |
-| Hook 3: Block Render | `ctx.renderers.register(type:'block')` → `Extensions.runBlockRenderers()` | `sw.pipe.render()` (filter targets code blocks in DOM) |
-| Hook 3: Inline Render | `ctx.renderers.register(type:'inline')` → not wired | `sw.pipe.render()` (filter modifies HTML string) |
-| Hook 5: Tool Bridge | `ctx.tools.handle()` → `Events.on('tool.call.*')` | Unchanged — not a pipe stage |
-| Hook 6: Surface Injection | Not implemented (spec only) | Not a pipe stage — future SDK feature |
-| (new) Pre-send | Did not exist | `sw.pipe.pre()` |
diff --git a/docs/JS-DEPENDENCY-AUDIT.md b/docs/JS-DEPENDENCY-AUDIT.md
deleted file mode 100644
index 34a336a..0000000
--- a/docs/JS-DEPENDENCY-AUDIT.md
+++ /dev/null
@@ -1,348 +0,0 @@
-# Frontend JS Dependency Audit
-
-**Version:** v0.28.3 cs2
-**Date:** 2026-03-13
-**Purpose:** Map every global, cross-file dependency, and init sequence
-to prepare for module extraction.
-
----
-
-## Summary
-
-| Metric | Value |
-|--------|-------|
-| JS files | 47 |
-| Total lines | 25,056 |
-| Total bytes | 1,103,572 (~1.1 MB) |
-| Top-level globals (original) | 431 |
-| IIFE-wrapped files | 47 (all) |
-| Explicit `window.*` exports | ~215 |
-| Functions privatized | ~168 |
-| Implicit globals remaining | 0 |
-| Vendor libs | 3 (marked.min.js, purify.min.js, codemirror.bundle.js) |
-| Inline `onclick` handlers (templates) | ~50 unique functions |
-| Dynamic `onclick` in JS (innerHTML) | 143 total occurrences |
-
----
-
-## Architecture: IIFE Modules (Post-Decomposition)
-
-No module system (no ES modules, no bundler, no AMD). Every file is a
-`<script>` tag loaded in dependency order. All 47 files are now wrapped
-in IIFEs with explicit `window.*` exports:
-
-```js
-(function() {
-'use strict';
-// ... all code ...
-window.MyGlobal = MyGlobal;
-})();
-```
-
-**Phase 1 complete.** Zero implicit globals remain. ~168 functions
-privatized. The next phase is onclick → addEventListener migration
-(143 dynamic handlers in JS innerHTML + ~50 in Go templates), which
-is the prerequisite for ES module conversion.
-
-### IIFE Files
-
-| File | Clean? | Leaks |
-|------|--------|-------|
-| `admin-handlers.js` | ✅ | None (all via inline onclick from globals) |
-| `admin-scaffold.js` | ✅ | None |
-| `editor-surface.js` | ✅ | None |
-| `knowledge-ui.js` | ✅ | None |
-| `pages-splash.js` | ✅ | None |
-| `task-admin.js` | ❌ | `window._loadAdminTasks` |
-| `task-settings.js` | ❌ | `window._createFromTemplate`, `window._loadSettingsTasks` |
-| `task-sidebar.js` | ❌ | `window.TaskSidebar` |
-| `tools-toggle.js` | ✅ | None |
-| `workflow-admin.js` | ❌ | 5 functions (`_loadAdminWorkflows`, `_wfCreate`, `_wfOpen`, `_wfEditStage`, `_wfDeleteStage`) |
-| `workflow-api.js` | ✅ | None (registers on App) |
-| `workflow-queue.js` | ❌ | `window.WorkflowQueue` |
-
----
-
-## Script Load Order
-
-### base.html (shared — every surface)
-
-```
- 1. app-state.js        → const App = { ... }
- 2. api.js              → const API = { ... }
- 3. (inline)            → window.__BASE__, auth bootstrap
- 4. events.js           → const Events = { ... }
- 5. ui-primitives.js    → const UI = { ... }
- 6. vendor/marked.min.js
- 7. vendor/purify.min.js
- 8. ui-format.js        → formatMessage(), toggleCodeCollapse(), etc.
- 9. ui-core.js          → renderChatList(), renderMessages(), etc.
-10. pages.js            → const Pages = { ... }
-11. user-menu.js        → const UserMenu = { ... }
-12. model-selector.js   → const ModelSelector = { ... }
-13. file-tree.js        → const FileTree = { ... }
-14. code-editor.js      → const CodeEditor = { ... }
-15. note-editor.js      → const NoteEditor = { ... }
-16. drag-resize.js      → const DragResize = { ... }
-17. pane-container.js   → const PaneContainer = { ... }
-18. (inline)            → Theme.init()
-19. surfaces/{surface}/js/main.js  → surface CSS + scaffold
-```
-
-### chat.html (25 additional scripts + 1 vendor)
-
-```
-    vendor/codemirror/codemirror.bundle.js → window.CM (optional, onerror fallback)
-20. extensions.js       → const Extensions = { ... }
-21. panels.js           → const PanelRegistry = { ... }
-22. ui-settings.js      → settings rendering (bare globals)
-23. ui-admin.js         → admin rendering (bare globals)
-24. tokens.js           → token counting (bare globals)
-25. notes.js            → notes UI (bare globals)
-26. note-graph.js       → graph visualization (bare globals)
-27. files.js            → file upload/management (bare globals)
-28. tools-toggle.js     → tool enable/disable (IIFE)
-29. knowledge-ui.js     → KB picker (IIFE)
-30. memory-ui.js        → memory panel (bare globals)
-31. persona-kb.js       → persona KB bindings (bare globals)
-32. projects-ui.js      → project management (bare globals, 78 top-level decls)
-33. channel-models.js   → const ChannelModels = { ... }
-34. notification-prefs.js → notification preferences (bare globals)
-35. notifications.js    → const Notifications = { ... }
-36. chat.js             → const ChatInput = { ... } + 29 top-level functions
-37. settings-handlers.js → settings form handlers (bare globals, 24 decls)
-38. admin-handlers.js   → admin form handlers (IIFE, 40 internal functions)
-39. workflow-api.js     → workflow REST helpers (IIFE)
-40. workflow-admin.js   → workflow admin UI (IIFE, 5 window.* leaks)
-41. workflow-queue.js   → workflow queue sidebar (IIFE, window.WorkflowQueue)
-42. task-sidebar.js     → task sidebar (IIFE, window.TaskSidebar)
-43. app.js              → init(), startApp(), event listeners
-44. debug.js            → debug console (bare globals)
-45. repl.js             → REPL (bare globals)
-```
-
-### admin.html (14 additional)
-
-Loads: ui-settings, ui-admin, admin-handlers, settings-handlers,
-knowledge-ui, persona-kb, memory-ui, notifications, files,
-admin-scaffold, workflow-api, workflow-admin, task-admin,
-admin-surfaces.
-
-### notes.html (14 additional)
-
-Loads: chat, files, channel-models, tokens, extensions, notes,
-note-graph, knowledge-ui, persona-kb, memory-ui, notifications,
-panels, projects-ui, app.
-
-### settings.html (9 additional)
-
-Loads: ui-settings, settings-handlers, task-settings, knowledge-ui,
-persona-kb, memory-ui, notifications, notification-prefs,
-channel-models.
-
-### editor.html (4 additional + 1 vendor)
-
-Loads: vendor/codemirror, chat-pane, editor-surface, app.
-Lightest surface — fewest dependencies.
-
----
-
-## Core Globals (Dependency Roots)
-
-These are referenced by 10+ other files. They form the "root set" that
-must be extracted first.
-
-| Global | Defined in | Referenced by | Role |
-|--------|-----------|---------------|------|
-| `App` | app-state.js | 20 files | State container (chats, models, user, settings, presence) |
-| `API` | api.js | 36 files | REST client (all HTTP calls) |
-| `UI` | ui-core.js | 32 files | DOM helpers (toast, confirm, modal, sidebar, theme) |
-| `Events` | events.js | 9 files | Pub/sub event bus (WebSocket bridge) |
-
-### Secondary Globals (3–9 references)
-
-| Global | Defined in | Referenced by | Role |
-|--------|-----------|---------------|------|
-| `Pages` | pages.js | Templates + 3 files | Page-level actions (login, admin forms) |
-| `ChannelModels` | channel-models.js | 4 files | Model roster per channel |
-| `ChatInput` | chat.js | 3 files | Message input state + send |
-| `Notifications` | notifications.js | Templates + 2 files | Bell dropdown, badge count |
-| `ChatPane` | chat-pane.js | 3 files | Embedded chat component (editor) |
-| `CM` | vendor/codemirror.bundle.js | 5 files | CodeMirror 6 editor (optional, graceful fallback) |
-| `PanelRegistry` | panels.js | Templates + 1 file | Side panel management |
-
-### Leaf Globals (1–2 references, mostly self-contained)
-
-ModelSelector, FileTree, CodeEditor, NoteEditor, DragResize,
-PaneContainer, UserMenu, WorkflowQueue, TaskSidebar, Extensions.
-
----
-
-## Inline Handler Problem
-
-143 `onclick=` patterns in JS files (innerHTML-generated HTML) plus
-~50 in Go templates. These reference bare globals that **must remain
-on `window`** or the handlers break. This is the primary blocker for
-ES module migration.
-
-**Top offenders (dynamic onclick in JS):**
-
-| File | Count | Examples |
-|------|-------|---------|
-| ui-admin.js | 28 | Admin list row actions |
-| projects-ui.js | 26 | Project CRUD, channel/KB/note associations |
-| ui-core.js | 25 | Chat list, sidebar, context menus |
-| ui-format.js | 10 | Code block copy/preview/download |
-| ui-settings.js | 8 | Settings form toggles |
-| notifications.js | 8 | Notification row actions |
-
-**Template onclick (must remain global):**
-
-UI.toggleSidebar, UI.toggleSidebarSection, UI.switchTeamTab,
-Notifications.toggleDropdown, PanelRegistry.toggle, PanelRegistry.closeAll,
-Pages.doLogin, Pages.saveSettings, Pages.saveProvider, Pages.saveTeam,
-handleLogin, handleRegister, switchAuthTab, newChat, newFolder,
-newChannelOrDM, sendMessage, createProject, closeLightbox,
-toggleSidePanelFullscreen, plus ~15 more Pages.* admin form handlers.
-
----
-
-## Cross-File Call Graph (Simplified)
-
-```
-app-state.js (App)
-  ↑ read/write by 20 files
-  │
-api.js (API)
-  ↑ called by 36 files
-  │
-events.js (Events)
-  ↑ subscribed by 9 files
-  ├── chat.js (typing, message.created, presence)
-  ├── notifications.js (notification.new/read)
-  ├── extensions.js (tool.call/result)
-  ├── repl.js (debug events)
-  └── app.js (role.fallback banner)
-  │
-ui-primitives.js (UI)
-  ↑ called by 32 files
-  ├── toast(), confirm(), modal()
-  ├── toggleSidebar(), toggleSidebarSection()
-  └── theme, kbd shortcuts
-  │
-ui-format.js (formatMessage, etc.)
-  ↑ called by ui-core.js, chat.js, notes.js, projects-ui.js
-  ├── depends on: marked.min.js, purify.min.js
-  │
-ui-core.js (renderChatList, renderMessages, etc.)
-  ↑ called by chat.js, app.js, projects-ui.js
-  ├── depends on: App, API, UI, ui-format
-  │
-chat.js (ChatInput, sendMessage, selectChat, loadChats)
-  ↑ called by app.js, templates
-  ├── depends on: App, API, Events, UI, ui-core, ui-format,
-  │               ChannelModels, tokens, files
-  │
-app.js (init, startApp)
-  ↑ entry point — called by inline <script> in base.html
-  ├── depends on: everything above + surface-specific modules
-```
-
----
-
-## Decomposition Strategy
-
-### Phase 1: Extract Core Four (no bundler required)
-
-Move `App`, `API`, `Events`, `UI` to a pattern where they're defined
-as proper singletons with explicit exports. No ES modules yet — just
-clean up the global registration so each file has a single `window.X`
-export with a documented interface.
-
-**Why no bundler yet:** 143 dynamic onclick handlers + 50 template
-onclick handlers require globals on `window`. A bundler would need
-either (a) a global shim layer or (b) converting all handlers to
-`addEventListener`. Option (b) is the right answer but it's ~200
-call sites across 16 files + 10 templates — too much churn for one
-changeset.
-
-### Phase 2: onclick → addEventListener migration
-
-Convert dynamic HTML generation from:
-```js
-`<button onclick="deleteItem('${id}')">Delete</button>`
-```
-to:
-```js
-const btn = document.createElement('button');
-btn.textContent = 'Delete';
-btn.addEventListener('click', () => deleteItem(id));
-```
-
-This eliminates the global requirement. Target the top 6 files first
-(ui-admin, projects-ui, ui-core, ui-format, ui-settings, notifications)
-which account for 105 of 143 occurrences.
-
-Template onclick handlers stay — Go templates can't do addEventListener.
-These become the only remaining reason for `window.*` exports.
-
-### Phase 3: ES Module conversion
-
-Once onclick handlers are gone from JS, files can become ES modules:
-```html
-<script type="module" src="js/app.js"></script>
-```
-
-Import graph follows the dependency order already established by
-`<script>` tag ordering. Vendor libs (marked, purify, codemirror) stay
-as classic scripts since they self-register on `window`.
-
-### Phase 4: Template handler shim
-
-Create a thin `window.handlers = {}` object that ES modules register
-into. Template onclick handlers call `handlers.doLogin()` etc. This
-is the final bridge — once templates move to client-side rendering
-(extension surface SDK), this shim disappears.
-
----
-
-## Files by Decomposition Priority
-
-### Tier 1 — Core (extract first, most dependents)
-
-| File | Lines | Globals | Dependents | Notes |
-|------|-------|---------|------------|-------|
-| app-state.js | 96 | 3 | 20 | Clean singleton, easy extract |
-| api.js | 1,159 | 3 | 36 | Large but self-contained |
-| events.js | 261 | 1 | 9 | Clean singleton |
-| ui-primitives.js | 1,316 | 18 | 32 | Large, many utility functions |
-
-### Tier 2 — Rendering (depends on Tier 1)
-
-| File | Lines | Globals | Dependents | Notes |
-|------|-------|---------|------------|-------|
-| ui-format.js | 573 | 20 | 4 | Markdown + code blocks |
-| ui-core.js | 1,644 | 6 | 3 | Chat list, messages, sidebar |
-| pages.js | 382 | 8 | Templates | Page-level orchestration |
-
-### Tier 3 — Feature modules (leaf nodes, mostly self-contained)
-
-| File | Lines | Notes |
-|------|-------|-------|
-| channel-models.js | 425 | Clean object literal |
-| chat-pane.js | 143 | Clean object literal |
-| notifications.js | 390 | Clean singleton, IIFE candidate |
-| model-selector.js | 191 | Clean object literal |
-| file-tree.js | 295 | Clean object literal |
-| tokens.js | 143 | 4 globals, minimal deps |
-
-### Tier 4 — Heavy pages (most onclick handlers, refactor last)
-
-| File | Lines | onclick | Notes |
-|------|-------|---------|-------|
-| ui-admin.js | 1,922 | 28 | Admin rendering, deeply coupled |
-| projects-ui.js | 1,794 | 26 | 78 top-level globals (!), biggest mess |
-| ui-core.js | 1,644 | 25 | Already in Tier 2, but onclick heavy |
-| ui-settings.js | 1,011 | 8 | Settings rendering |
-| settings-handlers.js | 1,064 | 0 | But 24 globals called by ui-settings |
-| admin-handlers.js | 952 | 2 | IIFE but 40 internal functions |
diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md
index 9500a06..96dcd54 100644
--- a/docs/ROADMAP.md
+++ b/docs/ROADMAP.md
@@ -43,7 +43,7 @@ v0.9.x–v0.28.7  Foundation through Platform Polish          ✅
         │                               │
         │                          v0.35.0 Workflow Product
         │                               │
-        │                          v0.36.0 Full OpenAPI Spec
+        │                          v0.36.0 Full OpenAPI Spec  ✅
         │                               │
   ══════╪═══════════════════════════════╪══════
         │         MVP v0.50.0           │
@@ -410,7 +410,7 @@ Depends on: v0.32.0 (multi-replica metrics aggregation).
       WS connections, Go runtime stats, storage status, recent errors,
       30s auto-refresh.
 
-**Deferred to v0.36.0:**
+**Deferred to v0.36.0 (delivered):**
 - Full OpenAPI spec coverage (all 20 ICD domains)
 - Bearer token / mTLS auth documentation in spec
 
@@ -484,7 +484,7 @@ Depends on: v0.31.2 (team workflow self-service), v0.29.0 (Starlark sandbox).
 - Data intake: form → Starlark enrichment → human review → follow-up
 - Onboarding: multi-stage form → conditional branching → team assignment
 
-### v0.36.0 — Full OpenAPI Spec
+### v0.36.0 — Full OpenAPI Spec ✅
 
 Complete OpenAPI 3.0.3 coverage for every API domain. Expand the
 hand-curated spec from v0.33.0 (core groups only) to cover all 20 ICD
@@ -493,38 +493,38 @@ test domains. Document Bearer token auth and mTLS modes.
 Depends on: v0.33.0 (Swagger UI + initial spec).
 
 **API domains to document (matching ICD test suite):**
-- [ ] Admin (system settings, stats, storage, users, provider config)
-- [ ] Channels (full CRUD + membership, already partially covered)
-- [ ] Completions (streaming + non-streaming, already partially covered)
-- [ ] Extensions (package install, permissions, lifecycle)
-- [ ] Knowledge (KB articles, sources, search, embeddings)
-- [ ] Memory (conversation memory, compaction, search)
-- [ ] Models (provider models, BYOK, capability matching)
-- [ ] Notes (CRUD, graph links, search)
-- [ ] Notifications (list, mark read, preferences)
-- [ ] Personas (CRUD, system prompts, tool config)
-- [ ] Profile (user profile, preferences, avatar)
-- [ ] Projects (CRUD, membership, file uploads)
-- [ ] Surfaces (extension surfaces, mounting, lifecycle)
-- [ ] Tasks (scheduled tasks, execution history, Starlark tasks)
-- [ ] Teams (CRUD, membership, roles, slugs)
-- [ ] Team Workflows (team-scoped CRUD, stages, publish)
-- [ ] Workflows (platform-level CRUD, stages, instances, assignments)
-- [ ] Workspaces (CRUD, membership, settings)
-- [ ] Dashboard Package (package-specific API routes)
-- [ ] Editor Package (package-specific API routes)
+- [x] Admin (system settings, stats, storage, users, provider config)
+- [x] Channels (full CRUD + membership, already partially covered)
+- [x] Completions (streaming + non-streaming, already partially covered)
+- [x] Extensions (package install, permissions, lifecycle)
+- [x] Knowledge (KB articles, sources, search, embeddings)
+- [x] Memory (conversation memory, compaction, search)
+- [x] Models (provider models, BYOK, capability matching)
+- [x] Notes (CRUD, graph links, search)
+- [x] Notifications (list, mark read, preferences)
+- [x] Personas (CRUD, system prompts, tool config)
+- [x] Profile (user profile, preferences, avatar)
+- [x] Projects (CRUD, membership, file uploads)
+- [x] Surfaces (extension surfaces, mounting, lifecycle)
+- [x] Tasks (scheduled tasks, execution history, Starlark tasks)
+- [x] Teams (CRUD, membership, roles, slugs)
+- [x] Team Workflows (team-scoped CRUD, stages, publish)
+- [x] Workflows (platform-level CRUD, stages, instances, assignments)
+- [x] Workspaces (CRUD, membership, settings)
+- [x] Dashboard Package (package-specific API routes)
+- [x] Editor Package (package-specific API routes)
 
 **Auth documentation:**
-- [ ] Bearer JWT flow (login → token → `Authorization: Bearer <token>`)
-- [ ] mTLS mode (NPE-to-NPE, no Bearer needed)
-- [ ] API key mode (for service-to-service integrations)
-- [ ] Security scheme definitions in OpenAPI spec
+- [x] Bearer JWT flow (login → token → `Authorization: Bearer <token>`)
+- [x] mTLS mode (NPE-to-NPE, no Bearer needed)
+- [x] API key mode (for service-to-service integrations)
+- [x] Security scheme definitions in OpenAPI spec
 
 **Quality:**
-- [ ] Request/response schemas with examples for every endpoint
-- [ ] Error response schemas (400, 401, 403, 404, 409, 422, 429, 500)
-- [ ] Pagination parameters documented consistently
-- [ ] WebSocket event schemas (connection, ticket, event types)
+- [x] Request/response schemas with examples for every endpoint
+- [x] Error response schemas (400, 401, 403, 404, 409, 422, 429, 500)
+- [x] Pagination parameters documented consistently
+- [x] WebSocket event schemas (connection, ticket, event types)
 
 ---
 
diff --git a/docs/DESIGN-0.32.0.md b/docs/archive/DESIGN-0.32.0.md
similarity index 100%
rename from docs/DESIGN-0.32.0.md
rename to docs/archive/DESIGN-0.32.0.md
diff --git a/docs/DESIGN-0.33.0.md b/docs/archive/DESIGN-0.33.0.md
similarity index 100%
rename from docs/DESIGN-0.33.0.md
rename to docs/archive/DESIGN-0.33.0.md
diff --git a/docs/DESIGN-0.34.0.md b/docs/archive/DESIGN-0.34.0.md
similarity index 100%
rename from docs/DESIGN-0.34.0.md
rename to docs/archive/DESIGN-0.34.0.md
diff --git a/docs/DESIGN-0.35.0.md b/docs/archive/DESIGN-0.35.0.md
similarity index 100%
rename from docs/DESIGN-0.35.0.md
rename to docs/archive/DESIGN-0.35.0.md
diff --git a/docs/DESIGN-SURFACES.md b/docs/archive/DESIGN-SURFACES.md
similarity index 100%
rename from docs/DESIGN-SURFACES.md
rename to docs/archive/DESIGN-SURFACES.md
diff --git a/server/static/openapi.yaml b/server/static/openapi.yaml
index c35f468..a4c60c3 100644
--- a/server/static/openapi.yaml
+++ b/server/static/openapi.yaml
@@ -1,52 +1,136 @@
 openapi: 3.0.3
 info:
   title: Chat Switchboard API
-  description: |
-    Multi-provider AI chat platform with team workspaces, workflow automation,
+  description: 'Multi-provider AI chat platform with team workspaces, workflow automation,
+
     and extensibility via Starlark packages.
 
-    **Authentication:** Most endpoints require a Bearer JWT token obtained via
-    `POST /api/v1/auth/login`. Include it as `Authorization: Bearer <token>`.
 
-    **WebSocket:** Real-time events are delivered over WebSocket at `/ws`.
-    Obtain a ticket via `POST /api/v1/ws/ticket` and connect with `?ticket=<id>`.
-  version: "${VERSION}"
+    ## Authentication
+
+
+    Three authentication modes, selected by the `AUTH_MODE` environment variable.
+
+    All three produce the same JWT-based session — downstream middleware is
+
+    auth-mode-agnostic.
+
+
+    **Builtin (default):** Username/password via `POST /api/v1/auth/login`.
+
+    Include the returned token as `Authorization: Bearer <token>`.
+
+
+    **OIDC:** Authorization code flow via `GET /api/v1/auth/oidc/login`.
+
+    Compatible with any OpenID Connect provider (tested with Keycloak).
+
+
+    **mTLS:** Mutual TLS via reverse proxy headers. No explicit login — user
+
+    identity is extracted from the client certificate on every request.
+
+
+    ## WebSocket
+
+
+    Real-time events are delivered over WebSocket at `/ws`. Obtain a single-use
+
+    ticket (30s TTL) via `POST /api/v1/ws/ticket` and connect with
+
+    `?ticket=<id>`. Cross-pod safe (v0.32.0).
+
+
+    ## Response Conventions
+
+
+    - **List endpoints** return `{ "data": [...] }` with an array under `data`.
+
+    - **Single-object endpoints** return the object directly.
+
+    - **Composite endpoints** use named keys (e.g. `{ "settings": {...} }`).
+
+    - **Errors** return `{ "error": "description" }`.
+
+    '
+  version: ${VERSION}
   contact:
     name: Chat Switchboard
-
 servers:
-  - url: /
-    description: Current instance
-
+- url: /
+  description: Current instance
 tags:
-  - name: Auth
-    description: Authentication and session management
-  - name: Channels
-    description: Chat channel CRUD and messaging
-  - name: Completions
-    description: AI completion requests (streaming and non-streaming)
-  - name: Health
-    description: System health and readiness probes
-  - name: Admin
-    description: Platform administration (requires admin role)
-  - name: Usage
-    description: Token usage and cost tracking
-  - name: WebSocket
-    description: Real-time event delivery
-
+- name: Auth
+  description: Authentication and session management
+- name: Profile
+  description: User profile, preferences, and credentials
+- name: Channels
+  description: Chat channel CRUD and messaging
+- name: Messages
+  description: Message CRUD, editing, regeneration, and tree navigation
+- name: Completions
+  description: AI completion requests (streaming and non-streaming)
+- name: Personas
+  description: AI persona CRUD, system prompts, tool config, KB bindings
+- name: Models
+  description: Model catalog, preferences, and capability management
+- name: Providers
+  description: Provider config CRUD (BYOK) and model fetching
+- name: Notes
+  description: Obsidian-style notes with wikilinks, backlinks, and graph
+- name: Knowledge Bases
+  description: Document ingestion, embedding, and semantic search
+- name: Memory
+  description: Conversation memory extraction, review, and compaction
+- name: Projects
+  description: Project containers for channels, KBs, notes, and files
+- name: Workspaces
+  description: File workspaces with git integration
+- name: Tasks
+  description: Scheduled and on-demand task execution (Go + Starlark)
+- name: Workflows
+  description: Multi-stage workflow definitions, instances, and assignments
+- name: Teams
+  description: Team CRUD, membership, roles, and scoped resources
+- name: Extensions
+  description: Package install, permissions, secrets, and lifecycle
+- name: Surfaces
+  description: Extension surface mounting and management
+- name: Notifications
+  description: User notification list, preferences, and read state
+- name: Files
+  description: File upload, download, and metadata
+- name: Health
+  description: System health, readiness, and metrics
+- name: Admin
+  description: Platform administration (requires admin role)
+- name: Usage
+  description: Token usage and cost tracking
+- name: WebSocket
+  description: Real-time event delivery
+- name: Data Portability
+  description: Export, import, GDPR compliance
 paths:
-  # ── Auth ───────────────────────────────────
   /api/v1/auth/register:
     post:
-      tags: [Auth]
+      tags:
+      - Auth
       summary: Register a new user
+      description: 'Builtin auth only. Gated by `allow_registration` policy.
+
+        A unique `handle` is auto-generated from `username`.
+
+        '
       requestBody:
         required: true
         content:
           application/json:
             schema:
               type: object
-              required: [username, password]
+              required:
+              - username
+              - password
+              - email
               properties:
                 username:
                   type: string
@@ -54,127 +138,511 @@ paths:
                 password:
                   type: string
                   minLength: 8
+                  maxLength: 128
                 email:
                   type: string
                   format: email
                 display_name:
                   type: string
+            example:
+              username: jdoe
+              password: s3cure-p@ss
+              email: jdoe@example.com
+              display_name: Jane Doe
       responses:
-        "201":
-          description: User created
+        '201':
+          description: User created and logged in
           content:
             application/json:
               schema:
-                $ref: "#/components/schemas/AuthResponse"
-        "400":
-          $ref: "#/components/responses/BadRequest"
-        "409":
-          description: Username already taken
-
+                $ref: '#/components/schemas/AuthResponse'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '403':
+          description: Registration disabled by policy
+        '409':
+          description: Username or email already taken
+        '200':
+          description: Success
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MessageResponse'
   /api/v1/auth/login:
     post:
-      tags: [Auth]
+      tags:
+      - Auth
       summary: Authenticate and obtain JWT tokens
+      description: 'Builtin auth. Accepts `login` (username or email) and `password`.
+
+        Returns an access token (15m TTL) and a refresh token (7d TTL).
+
+        '
       requestBody:
         required: true
         content:
           application/json:
             schema:
               type: object
-              required: [username, password]
+              required:
+              - login
+              - password
               properties:
-                username:
+                login:
                   type: string
+                  description: Username or email address
                 password:
                   type: string
+            example:
+              login: jdoe
+              password: s3cure-p@ss
       responses:
-        "200":
+        '200':
           description: Login successful
           content:
             application/json:
               schema:
-                $ref: "#/components/schemas/AuthResponse"
-        "401":
+                $ref: '#/components/schemas/AuthResponse'
+        '401':
           description: Invalid credentials
-        "429":
-          description: Rate limited
-
+        '403':
+          description: Account inactive (awaiting admin approval)
+        '429':
+          $ref: '#/components/responses/RateLimited'
+        '201':
+          description: Success
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MessageResponse'
   /api/v1/auth/refresh:
     post:
-      tags: [Auth]
+      tags:
+      - Auth
       summary: Refresh an expired access token
+      description: 'Exchanges a valid refresh token for a new token pair. The old
+
+        refresh token is invalidated (rotation).
+
+        '
       requestBody:
         required: true
         content:
           application/json:
             schema:
               type: object
-              required: [refresh_token]
+              required:
+              - refresh_token
               properties:
                 refresh_token:
                   type: string
       responses:
-        "200":
+        '200':
           description: New token pair
           content:
             application/json:
               schema:
-                $ref: "#/components/schemas/AuthResponse"
-        "401":
+                $ref: '#/components/schemas/AuthResponse'
+        '401':
           description: Invalid or expired refresh token
-
+        '201':
+          description: Success
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MessageResponse'
   /api/v1/auth/logout:
     post:
-      tags: [Auth]
+      tags:
+      - Auth
       summary: Invalidate the current session
+      description: Revokes the provided refresh token.
       security:
-        - bearerAuth: []
+      - bearerAuth: []
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                refresh_token:
+                  type: string
       responses:
-        "200":
+        '200':
           description: Logged out
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MessageResponse'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '201':
+          description: Success
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MessageResponse'
+  /api/v1/auth/oidc/login:
+    get:
+      tags:
+      - Auth
+      summary: Initiate OIDC authorization code flow
+      description: 'Redirects to the configured OIDC identity provider. Stores `state`
 
-  # ── Channels ───────────────────────────────
+        and `nonce` for CSRF protection. Only available when `AUTH_MODE=oidc`.
+
+        '
+      responses:
+        '302':
+          description: Redirect to IdP authorization endpoint
+        '500':
+          description: OIDC not configured or discovery failed
+        '200':
+          description: Success
+          content:
+            application/json:
+              schema:
+                type: object
+  /api/v1/auth/oidc/callback:
+    get:
+      tags:
+      - Auth
+      summary: OIDC authorization code callback
+      description: 'Receives the authorization code from the IdP, exchanges it for tokens,
+
+        validates the ID token via JWKS, and auto-provisions the user on first
+
+        login. Returns an HTML fragment that passes tokens to the frontend via
+
+        URL fragment.
+
+        '
+      parameters:
+      - name: code
+        in: query
+        required: true
+        schema:
+          type: string
+      - name: state
+        in: query
+        required: true
+        schema:
+          type: string
+      responses:
+        '200':
+          description: HTML with embedded tokens
+          content:
+            text/html:
+              schema:
+                type: string
+        '400':
+          description: Invalid state or code
+        '500':
+          description: Token exchange or validation failed
+  /api/v1/profile:
+    get:
+      tags:
+      - Profile
+      summary: Get current user's profile
+      security:
+      - bearerAuth: []
+      responses:
+        '200':
+          description: User profile
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/UserProfile'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+    put:
+      tags:
+      - Profile
+      summary: Update profile fields
+      description: 'Partial update — only provided fields are changed.
+
+        Supports `display_name` and `email`.
+
+        '
+      security:
+      - bearerAuth: []
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                display_name:
+                  type: string
+                email:
+                  type: string
+                  format: email
+            example:
+              display_name: Jane D.
+              email: jane@newdomain.com
+      responses:
+        '200':
+          description: Updated profile
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/UserProfile'
+        '409':
+          $ref: '#/components/responses/Conflict'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+  /api/v1/profile/password:
+    post:
+      tags:
+      - Profile
+      summary: Change password
+      description: 'Builtin auth only. Validates current password, then updates.
+
+        Re-wraps the User Encryption Key (UEK) so BYOK-encrypted
+
+        provider keys remain accessible.
+
+        '
+      security:
+      - bearerAuth: []
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required:
+              - current_password
+              - new_password
+              properties:
+                current_password:
+                  type: string
+                new_password:
+                  type: string
+                  minLength: 8
+                  maxLength: 128
+      responses:
+        '200':
+          description: Password updated
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MessageResponse'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          description: Current password incorrect
+        '201':
+          description: Success
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MessageResponse'
+  /api/v1/profile/avatar:
+    post:
+      tags:
+      - Profile
+      summary: Upload avatar
+      description: 'Accepts a base64 data URI or raw base64 string. The server decodes,
+
+        resizes to 128x128 PNG, and stores as a data URI. Max input 2 MB.
+
+        '
+      security:
+      - bearerAuth: []
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required:
+              - image
+              properties:
+                image:
+                  type: string
+                  description: Base64 data URI or raw base64 string
+      responses:
+        '200':
+          description: Avatar stored
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  avatar:
+                    type: string
+                    description: Data URI of the stored avatar
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '201':
+          description: Success
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MessageResponse'
+    delete:
+      tags:
+      - Profile
+      summary: Remove avatar
+      security:
+      - bearerAuth: []
+      responses:
+        '200':
+          description: Avatar removed
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MessageResponse'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+  /api/v1/settings:
+    get:
+      tags:
+      - Profile
+      summary: Get user preferences
+      description: 'Returns user-level preferences wrapped in a `settings` key.
+
+        Value is `{}` if the user has never saved preferences.
+
+        '
+      security:
+      - bearerAuth: []
+      responses:
+        '200':
+          description: User settings
+          content:
+            application/json:
+              schema:
+                type: object
+                required:
+                - settings
+                properties:
+                  settings:
+                    type: object
+                    additionalProperties: true
+              example:
+                settings:
+                  theme: dark
+                  editor_keybindings: vim
+                  default_model: claude-sonnet-4-5
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+    put:
+      tags:
+      - Profile
+      summary: Update user preferences
+      description: 'Shallow merge — incoming keys overwrite existing, unmentioned keys
+
+        are preserved. Returns the full merged settings object.
+
+        '
+      security:
+      - bearerAuth: []
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              additionalProperties: true
+            example:
+              theme: light
+              font_size: 14
+      responses:
+        '200':
+          description: Updated settings
+          content:
+            application/json:
+              schema:
+                type: object
+                required:
+                - settings
+                properties:
+                  settings:
+                    type: object
+                    additionalProperties: true
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+  /api/v1/settings/public:
+    get:
+      tags:
+      - Profile
+      summary: Get public platform settings
+      description: 'Returns platform-level settings visible to authenticated users
+
+        (e.g. allowed registration, default model, branding).
+
+        '
+      security:
+      - bearerAuth: []
+      responses:
+        '200':
+          description: Public settings
+          content:
+            application/json:
+              schema:
+                type: object
+                additionalProperties: true
+        '401':
+          $ref: '#/components/responses/Unauthorized'
   /api/v1/channels:
     get:
-      tags: [Channels]
+      tags:
+      - Channels
       summary: List channels accessible to the current user
       security:
-        - bearerAuth: []
+      - bearerAuth: []
       parameters:
-        - name: type
-          in: query
-          schema:
-            type: string
-            enum: [direct, group, workflow]
-        - name: page
-          in: query
-          schema:
-            type: integer
-            default: 1
-        - name: per_page
-          in: query
-          schema:
-            type: integer
-            default: 50
+      - name: type
+        in: query
+        schema:
+          type: string
+          enum:
+          - direct
+          - group
+          - workflow
+      - $ref: '#/components/parameters/Page'
+      - $ref: '#/components/parameters/PerPage'
       responses:
-        "200":
+        '200':
           description: Channel list
           content:
             application/json:
               schema:
                 type: object
                 properties:
-                  channels:
+                  data:
                     type: array
                     items:
-                      $ref: "#/components/schemas/Channel"
+                      $ref: '#/components/schemas/Channel'
+                  page:
+                    type: integer
+                  per_page:
+                    type: integer
                   total:
                     type: integer
+                  total_pages:
+                    type: integer
+        '401':
+          $ref: '#/components/responses/Unauthorized'
     post:
-      tags: [Channels]
+      tags:
+      - Channels
       summary: Create a new channel
       security:
-        - bearerAuth: []
+      - bearerAuth: []
       requestBody:
         required: true
         content:
@@ -186,42 +654,57 @@ paths:
                   type: string
                 type:
                   type: string
-                  enum: [direct, group]
+                  enum:
+                  - direct
+                  - group
                   default: direct
                 system_prompt:
                   type: string
       responses:
-        "201":
+        '201':
           description: Channel created
           content:
             application/json:
               schema:
-                $ref: "#/components/schemas/Channel"
-
+                $ref: '#/components/schemas/Channel'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '200':
+          description: Success
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MessageResponse'
   /api/v1/channels/{id}:
     get:
-      tags: [Channels]
+      tags:
+      - Channels
       summary: Get channel details
       security:
-        - bearerAuth: []
+      - bearerAuth: []
       parameters:
-        - $ref: "#/components/parameters/ChannelID"
+      - $ref: '#/components/parameters/ResourceID'
       responses:
-        "200":
+        '200':
           description: Channel details
           content:
             application/json:
               schema:
-                $ref: "#/components/schemas/Channel"
-        "404":
-          $ref: "#/components/responses/NotFound"
+                $ref: '#/components/schemas/Channel'
+        '404':
+          $ref: '#/components/responses/NotFound'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
     put:
-      tags: [Channels]
+      tags:
+      - Channels
       summary: Update channel settings
       security:
-        - bearerAuth: []
+      - bearerAuth: []
       parameters:
-        - $ref: "#/components/parameters/ChannelID"
+      - $ref: '#/components/parameters/ResourceID'
       requestBody:
         required: true
         content:
@@ -235,125 +718,98 @@ paths:
                   type: string
                 ai_mode:
                   type: string
-                  enum: [auto, off, mention_only]
+                  enum:
+                  - auto
+                  - false
+                  - mention_only
       responses:
-        "200":
+        '200':
           description: Updated
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Channel'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
     delete:
-      tags: [Channels]
+      tags:
+      - Channels
       summary: Archive a channel
       security:
-        - bearerAuth: []
+      - bearerAuth: []
       parameters:
-        - $ref: "#/components/parameters/ChannelID"
+      - $ref: '#/components/parameters/ResourceID'
       responses:
-        "200":
+        '200':
           description: Archived
-
-  # ── Completions ────────────────────────────
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MessageResponse'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
   /api/v1/chat/completions:
     post:
-      tags: [Completions]
+      tags:
+      - Completions
       summary: Send a message and get an AI completion
-      description: |
-        Streams SSE events by default. Set `stream: false` for a single JSON response.
-        Supports tool calling, @mentions, multi-model routing, and workflow integration.
+      description: 'Streams SSE events by default. Set `stream: false` for a single JSON
+
+        response. Supports tool calling, @mentions, multi-model routing, and
+
+        workflow integration.
+
+        '
       security:
-        - bearerAuth: []
+      - bearerAuth: []
       requestBody:
         required: true
         content:
           application/json:
             schema:
-              type: object
-              required: [content, channel_id]
-              properties:
-                channel_id:
-                  type: string
-                  format: uuid
-                content:
-                  type: string
-                model:
-                  type: string
-                  description: Override the default model
-                persona_id:
-                  type: string
-                  format: uuid
-                provider_config_id:
-                  type: string
-                  format: uuid
-                max_tokens:
-                  type: integer
-                temperature:
-                  type: number
-                  minimum: 0
-                  maximum: 2
-                top_p:
-                  type: number
-                  minimum: 0
-                  maximum: 1
-                stream:
-                  type: boolean
-                  default: true
-                file_ids:
-                  type: array
-                  items:
-                    type: string
-                    format: uuid
-                disabled_tools:
-                  type: array
-                  items:
-                    type: string
+              $ref: '#/components/schemas/CompletionRequest'
       responses:
-        "200":
-          description: |
-            **Streaming:** SSE events (`data: {"content":"..."}`, `data: [DONE]`).
+        '200':
+          description: '**Streaming:** SSE events (`data: {"content":"..."}`, `data: [DONE]`).
+
             **Non-streaming:** OpenAI-compatible JSON response.
+
+            '
           content:
             text/event-stream:
               schema:
                 type: string
             application/json:
               schema:
-                type: object
-                properties:
-                  model:
-                    type: string
-                  choices:
-                    type: array
-                    items:
-                      type: object
-                      properties:
-                        message:
-                          type: object
-                          properties:
-                            role:
-                              type: string
-                            content:
-                              type: string
-                        finish_reason:
-                          type: string
-                  usage:
-                    type: object
-                    properties:
-                      prompt_tokens:
-                        type: integer
-                      completion_tokens:
-                        type: integer
-                      total_tokens:
-                        type: integer
-        "400":
-          $ref: "#/components/responses/BadRequest"
-        "429":
-          description: Token budget exceeded
-
-  # ── Health ─────────────────────────────────
+                $ref: '#/components/schemas/CompletionResponse'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '429':
+          $ref: '#/components/responses/RateLimited'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '201':
+          description: Success
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MessageResponse'
   /health:
     get:
-      tags: [Health]
+      tags:
+      - Health
       summary: Basic health check
+      description: Public, no auth required. Also mirrored at `/api/v1/health`.
       responses:
-        "200":
+        '200':
           description: System status
           content:
             application/json:
@@ -369,54 +825,68 @@ paths:
                     type: boolean
                   schema_version:
                     type: integer
-
   /healthz/live:
     get:
-      tags: [Health]
+      tags:
+      - Health
       summary: Kubernetes liveness probe
       responses:
-        "200":
+        '200':
           description: Process alive
-
+          content:
+            application/json:
+              schema:
+                type: object
   /healthz/ready:
     get:
-      tags: [Health]
+      tags:
+      - Health
       summary: Kubernetes readiness probe
-      description: Returns 503 if the database is unreachable (2s timeout).
+      description: Pings the database with a 2s timeout. Returns 503 if unreachable.
       responses:
-        "200":
+        '200':
           description: Ready to serve traffic
-        "503":
+          content:
+            application/json:
+              schema:
+                type: object
+        '503':
           description: Database unavailable
-
   /metrics:
     get:
-      tags: [Health]
+      tags:
+      - Health
       summary: Prometheus metrics endpoint
-      description: |
-        Returns all `switchboard_*` metrics in Prometheus text exposition format.
+      description: 'Returns all `switchboard_*` metrics in Prometheus text exposition format.
+
         Includes HTTP request latency, WebSocket connections, completion tokens,
+
         DB pool stats, and provider health gauges.
+
+        '
       responses:
-        "200":
+        '200':
           description: Prometheus text format
           content:
             text/plain:
               schema:
                 type: string
-
-  # ── WebSocket ──────────────────────────────
   /api/v1/ws/ticket:
     post:
-      tags: [WebSocket]
+      tags:
+      - WebSocket
       summary: Obtain a WebSocket connection ticket
-      description: |
-        Returns a single-use ticket (30s TTL) for authenticating the WebSocket
-        upgrade at `/ws?ticket=<id>`. Cross-pod safe (v0.32.0).
+      description: 'Returns a single-use ticket (30s TTL) for authenticating the WebSocket
+
+        upgrade at `/ws?ticket=<id>`. Stored in PG for cross-pod validation
+
+        (v0.32.0).
+
+        '
       security:
-        - bearerAuth: []
+      - bearerAuth: []
       responses:
-        "200":
+        '200':
           description: Ticket issued
           content:
             application/json:
@@ -425,16 +895,9806 @@ paths:
                 properties:
                   ticket:
                     type: string
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '201':
+          description: Success
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MessageResponse'
+  /api/v1/export:
+    post:
+      tags:
+      - Data Portability
+      summary: Convert markdown to PDF or DOCX
+      description: 'Uses pandoc to convert markdown content to the requested format.
 
-  # ── Admin: Stats ───────────────────────────
+        Returns the binary file with appropriate Content-Type.
+
+        '
+      security:
+      - bearerAuth: []
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required:
+              - content
+              - format
+              properties:
+                content:
+                  type: string
+                  description: Markdown content to convert
+                format:
+                  type: string
+                  enum:
+                  - pdf
+                  - docx
+                filename:
+                  type: string
+                  description: Output filename (without extension)
+      responses:
+        '200':
+          description: Converted document
+          content:
+            application/pdf:
+              schema:
+                type: string
+                format: binary
+            application/vnd.openxmlformats-officedocument.wordprocessingml.document:
+              schema:
+                type: string
+                format: binary
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '201':
+          description: Success
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MessageResponse'
+  /api/v1/channels/{id}/mark-read:
+    post:
+      tags:
+      - Channels
+      summary: Mark channel as read
+      security:
+      - bearerAuth: []
+      parameters:
+      - $ref: '#/components/parameters/ResourceID'
+      responses:
+        '200':
+          description: Read cursor updated
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Channel'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '201':
+          description: Success
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MessageResponse'
+  /api/v1/channels/{id}/typing:
+    post:
+      tags:
+      - Channels
+      summary: Broadcast typing indicator
+      security:
+      - bearerAuth: []
+      parameters:
+      - $ref: '#/components/parameters/ResourceID'
+      responses:
+        '200':
+          description: Typing event sent
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Channel'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '201':
+          description: Success
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MessageResponse'
+  /api/v1/channels/{id}/summarize:
+    post:
+      tags:
+      - Channels
+      summary: Trigger conversation summarization
+      security:
+      - bearerAuth: []
+      parameters:
+      - $ref: '#/components/parameters/ResourceID'
+      responses:
+        '200':
+          description: Summary created
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  message:
+                    type: string
+                  summary_id:
+                    type: string
+                    format: uuid
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '201':
+          description: Success
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MessageResponse'
+  /api/v1/channels/{id}/generate-title:
+    post:
+      tags:
+      - Channels
+      summary: Auto-generate channel title from first exchange
+      security:
+      - bearerAuth: []
+      parameters:
+      - $ref: '#/components/parameters/ResourceID'
+      responses:
+        '200':
+          description: Title generated
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  title:
+                    type: string
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '201':
+          description: Success
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MessageResponse'
+  /api/v1/channels/{id}/path:
+    get:
+      tags:
+      - Messages
+      summary: Get active message path (tree walk)
+      description: Returns messages along the active branch from root to leaf.
+      security:
+      - bearerAuth: []
+      parameters:
+      - $ref: '#/components/parameters/ResourceID'
+      responses:
+        '200':
+          description: Active message path
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  messages:
+                    type: array
+                    items:
+                      $ref: '#/components/schemas/Message'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+  /api/v1/channels/{id}/messages:
+    get:
+      tags:
+      - Messages
+      summary: List all messages (flat, all branches)
+      description: Debug/legacy endpoint. Returns every message regardless of branch.
+      security:
+      - bearerAuth: []
+      parameters:
+      - $ref: '#/components/parameters/ResourceID'
+      - $ref: '#/components/parameters/Page'
+      - $ref: '#/components/parameters/PerPage'
+      responses:
+        '200':
+          description: All messages in channel
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  data:
+                    type: array
+                    items:
+                      $ref: '#/components/schemas/Message'
+                  page:
+                    type: integer
+                  per_page:
+                    type: integer
+                  total:
+                    type: integer
+                  total_pages:
+                    type: integer
+        '404':
+          $ref: '#/components/responses/NotFound'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+    post:
+      tags:
+      - Messages
+      summary: Create a message
+      security:
+      - bearerAuth: []
+      parameters:
+      - $ref: '#/components/parameters/ResourceID'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required:
+              - role
+              - content
+              properties:
+                role:
+                  type: string
+                  enum:
+                  - user
+                  - system
+                content:
+                  type: string
+                parent_id:
+                  type: string
+                  format: uuid
+                  nullable: true
+                attachments:
+                  type: array
+                  items:
+                    type: string
+                    format: uuid
+      responses:
+        '201':
+          description: Message created
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Message'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '404':
+          $ref: '#/components/responses/NotFound'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '200':
+          description: Success
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MessageResponse'
+  /api/v1/channels/{id}/messages/{msgId}/edit:
+    post:
+      tags:
+      - Messages
+      summary: Edit a message (creates sibling branch)
+      security:
+      - bearerAuth: []
+      parameters:
+      - $ref: '#/components/parameters/ResourceID'
+      - name: msgId
+        in: path
+        required: true
+        schema:
+          type: string
+          format: uuid
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required:
+              - content
+              properties:
+                content:
+                  type: string
+      responses:
+        '201':
+          description: Sibling message created
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Message'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '404':
+          $ref: '#/components/responses/NotFound'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '200':
+          description: Success
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MessageResponse'
+  /api/v1/channels/{id}/messages/{msgId}/regenerate:
+    post:
+      tags:
+      - Messages
+      summary: Regenerate an assistant response (creates sibling)
+      security:
+      - bearerAuth: []
+      parameters:
+      - $ref: '#/components/parameters/ResourceID'
+      - name: msgId
+        in: path
+        required: true
+        schema:
+          type: string
+          format: uuid
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                model:
+                  type: string
+                provider_config_id:
+                  type: string
+                  format: uuid
+      responses:
+        '200':
+          description: Streaming regeneration started
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Message'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '201':
+          description: Success
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MessageResponse'
+  /api/v1/channels/{id}/messages/{msgId}/siblings:
+    get:
+      tags:
+      - Messages
+      summary: List siblings at a branch point
+      security:
+      - bearerAuth: []
+      parameters:
+      - $ref: '#/components/parameters/ResourceID'
+      - name: msgId
+        in: path
+        required: true
+        schema:
+          type: string
+          format: uuid
+      responses:
+        '200':
+          description: Sibling messages
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  siblings:
+                    type: array
+                    items:
+                      $ref: '#/components/schemas/Message'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+  /api/v1/channels/{id}/cursor:
+    put:
+      tags:
+      - Messages
+      summary: Switch active branch
+      security:
+      - bearerAuth: []
+      parameters:
+      - $ref: '#/components/parameters/ResourceID'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required:
+              - active_leaf_id
+              properties:
+                active_leaf_id:
+                  type: string
+                  format: uuid
+      responses:
+        '200':
+          description: Cursor updated
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Message'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+  /api/v1/tools:
+    get:
+      tags:
+      - Completions
+      summary: List available tools
+      security:
+      - bearerAuth: []
+      responses:
+        '200':
+          description: Tool definitions
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  tools:
+                    type: array
+                    items:
+                      $ref: '#/components/schemas/ToolDef'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+  /api/v1/channels/{id}/models:
+    get:
+      tags:
+      - Channels
+      summary: List channel model roster
+      security:
+      - bearerAuth: []
+      parameters:
+      - $ref: '#/components/parameters/ResourceID'
+      responses:
+        '200':
+          description: Channel model roster
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  data:
+                    type: array
+                    items:
+                      $ref: '#/components/schemas/Channel'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+    post:
+      tags:
+      - Channels
+      summary: Add model to channel roster
+      security:
+      - bearerAuth: []
+      parameters:
+      - $ref: '#/components/parameters/ResourceID'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required:
+              - model
+              - provider_config_id
+              properties:
+                model:
+                  type: string
+                provider_config_id:
+                  type: string
+                  format: uuid
+                display_name:
+                  type: string
+      responses:
+        '201':
+          description: Model added to roster
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Channel'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '200':
+          description: Success
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MessageResponse'
+  /api/v1/channels/{id}/models/{modelId}:
+    patch:
+      tags:
+      - Channels
+      summary: Update channel model entry
+      security:
+      - bearerAuth: []
+      parameters:
+      - $ref: '#/components/parameters/ResourceID'
+      - name: modelId
+        in: path
+        required: true
+        schema:
+          type: string
+          format: uuid
+      responses:
+        '200':
+          description: Updated
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Channel'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+    delete:
+      tags:
+      - Channels
+      summary: Remove model from channel roster
+      security:
+      - bearerAuth: []
+      parameters:
+      - $ref: '#/components/parameters/ResourceID'
+      - name: modelId
+        in: path
+        required: true
+        schema:
+          type: string
+          format: uuid
+      responses:
+        '200':
+          description: Removed
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MessageResponse'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+  /api/v1/channels/{id}/participants:
+    get:
+      tags:
+      - Channels
+      summary: List channel participants
+      security:
+      - bearerAuth: []
+      parameters:
+      - $ref: '#/components/parameters/ResourceID'
+      responses:
+        '200':
+          description: Participant list
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  participants:
+                    type: array
+                    items:
+                      $ref: '#/components/schemas/Participant'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+    post:
+      tags:
+      - Channels
+      summary: Add participant to channel
+      security:
+      - bearerAuth: []
+      parameters:
+      - $ref: '#/components/parameters/ResourceID'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required:
+              - participant_type
+              - participant_id
+              properties:
+                participant_type:
+                  type: string
+                  enum:
+                  - user
+                  - persona
+                participant_id:
+                  type: string
+                  format: uuid
+                role:
+                  type: string
+                  enum:
+                  - member
+                  - observer
+                  default: member
+      responses:
+        '201':
+          description: Participant added
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Channel'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '200':
+          description: Success
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MessageResponse'
+  /api/v1/channels/{id}/participants/{participantId}:
+    patch:
+      tags:
+      - Channels
+      summary: Update participant role
+      security:
+      - bearerAuth: []
+      parameters:
+      - $ref: '#/components/parameters/ResourceID'
+      - name: participantId
+        in: path
+        required: true
+        schema:
+          type: string
+          format: uuid
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                role:
+                  type: string
+                  enum:
+                  - member
+                  - observer
+      responses:
+        '200':
+          description: Updated
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Channel'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+    delete:
+      tags:
+      - Channels
+      summary: Remove participant
+      security:
+      - bearerAuth: []
+      parameters:
+      - $ref: '#/components/parameters/ResourceID'
+      - name: participantId
+        in: path
+        required: true
+        schema:
+          type: string
+          format: uuid
+      responses:
+        '200':
+          description: Removed
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MessageResponse'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+  /api/v1/channels/{id}/knowledge-bases:
+    get:
+      tags:
+      - Channels
+      - Knowledge Bases
+      summary: List KB bindings for channel
+      security:
+      - bearerAuth: []
+      parameters:
+      - $ref: '#/components/parameters/ResourceID'
+      responses:
+        '200':
+          description: Channel KB bindings
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  data:
+                    type: array
+                    items:
+                      $ref: '#/components/schemas/Channel'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+    put:
+      tags:
+      - Channels
+      - Knowledge Bases
+      summary: Set channel KB bindings (replace all)
+      security:
+      - bearerAuth: []
+      parameters:
+      - $ref: '#/components/parameters/ResourceID'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required:
+              - kb_ids
+              properties:
+                kb_ids:
+                  type: array
+                  items:
+                    type: string
+                    format: uuid
+      responses:
+        '200':
+          description: Bindings updated
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Channel'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+  /api/v1/channels/{id}/files:
+    post:
+      tags:
+      - Files
+      summary: Upload file to channel
+      security:
+      - bearerAuth: []
+      parameters:
+      - $ref: '#/components/parameters/ResourceID'
+      requestBody:
+        required: true
+        content:
+          multipart/form-data:
+            schema:
+              type: object
+              properties:
+                file:
+                  type: string
+                  format: binary
+      responses:
+        '201':
+          description: File uploaded
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/FileObject'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '200':
+          description: Success
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MessageResponse'
+    get:
+      tags:
+      - Files
+      summary: List files in channel
+      security:
+      - bearerAuth: []
+      parameters:
+      - $ref: '#/components/parameters/ResourceID'
+      - name: origin
+        in: query
+        schema:
+          type: string
+          enum:
+          - user_upload
+          - tool_output
+          - system
+      responses:
+        '200':
+          description: Channel files
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  data:
+                    type: array
+                    items:
+                      $ref: '#/components/schemas/FileObject'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+  /api/v1/files:
+    get:
+      tags:
+      - Files
+      summary: List all files owned by user
+      security:
+      - bearerAuth: []
+      parameters:
+      - $ref: '#/components/parameters/Page'
+      - $ref: '#/components/parameters/PerPage'
+      responses:
+        '200':
+          description: User file list
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  data:
+                    type: array
+                    items:
+                      $ref: '#/components/schemas/FileObject'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+  /api/v1/files/{id}:
+    get:
+      tags:
+      - Files
+      summary: Get file metadata
+      security:
+      - bearerAuth: []
+      parameters:
+      - $ref: '#/components/parameters/ResourceID'
+      responses:
+        '200':
+          description: File metadata
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/FileObject'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+    delete:
+      tags:
+      - Files
+      summary: Delete file
+      security:
+      - bearerAuth: []
+      parameters:
+      - $ref: '#/components/parameters/ResourceID'
+      responses:
+        '200':
+          description: Deleted
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MessageResponse'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+  /api/v1/files/{id}/download:
+    get:
+      tags:
+      - Files
+      summary: Download file
+      security:
+      - bearerAuth: []
+      parameters:
+      - $ref: '#/components/parameters/ResourceID'
+      responses:
+        '200':
+          description: File content
+          content:
+            application/octet-stream:
+              schema:
+                type: string
+                format: binary
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+  /api/v1/messages/{id}/files:
+    get:
+      tags:
+      - Files
+      summary: List files attached to a message
+      security:
+      - bearerAuth: []
+      parameters:
+      - $ref: '#/components/parameters/ResourceID'
+      responses:
+        '200':
+          description: Message files
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  data:
+                    type: array
+                    items:
+                      $ref: '#/components/schemas/FileObject'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+  /api/v1/folders:
+    get:
+      tags:
+      - Channels
+      summary: List chat folders
+      security:
+      - bearerAuth: []
+      responses:
+        '200':
+          description: User folders
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  data:
+                    type: array
+                    items:
+                      $ref: '#/components/schemas/Channel'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+    post:
+      tags:
+      - Channels
+      summary: Create folder
+      security:
+      - bearerAuth: []
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required:
+              - name
+              properties:
+                name:
+                  type: string
+                sort_order:
+                  type: integer
+                  default: 0
+      responses:
+        '201':
+          description: Folder created
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Channel'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '200':
+          description: Success
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MessageResponse'
+  /api/v1/folders/{id}:
+    put:
+      tags:
+      - Channels
+      summary: Update folder
+      security:
+      - bearerAuth: []
+      parameters:
+      - $ref: '#/components/parameters/ResourceID'
+      responses:
+        '200':
+          description: Updated
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Channel'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+    delete:
+      tags:
+      - Channels
+      summary: Delete folder (chats become unfiled)
+      security:
+      - bearerAuth: []
+      parameters:
+      - $ref: '#/components/parameters/ResourceID'
+      responses:
+        '200':
+          description: Deleted
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MessageResponse'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+  /api/v1/presence/heartbeat:
+    post:
+      tags:
+      - Channels
+      summary: Send presence heartbeat
+      security:
+      - bearerAuth: []
+      responses:
+        '200':
+          description: Heartbeat recorded
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Channel'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '201':
+          description: Success
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MessageResponse'
+  /api/v1/presence:
+    get:
+      tags:
+      - Channels
+      summary: Query user presence status
+      security:
+      - bearerAuth: []
+      parameters:
+      - name: users
+        in: query
+        required: true
+        schema:
+          type: string
+        description: Comma-separated user UUIDs (max 100)
+      responses:
+        '200':
+          description: Presence map
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  data:
+                    type: array
+                    items:
+                      $ref: '#/components/schemas/Channel'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+  /api/v1/users/search:
+    get:
+      tags:
+      - Channels
+      summary: Search users (for DM creation and participant picker)
+      security:
+      - bearerAuth: []
+      parameters:
+      - name: q
+        in: query
+        required: true
+        schema:
+          type: string
+      responses:
+        '200':
+          description: Matching users (max 20)
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  data:
+                    type: array
+                    items:
+                      $ref: '#/components/schemas/Channel'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+  /api/v1/personas:
+    get:
+      tags:
+      - Personas
+      summary: List user's personal personas
+      security:
+      - bearerAuth: []
+      responses:
+        '200':
+          description: Personal personas
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  data:
+                    type: array
+                    items:
+                      $ref: '#/components/schemas/Persona'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+    post:
+      tags:
+      - Personas
+      summary: Create personal persona
+      security:
+      - bearerAuth: []
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/PersonaInput'
+      responses:
+        '201':
+          description: Persona created
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Persona'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '200':
+          description: Success
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MessageResponse'
+  /api/v1/personas/{id}:
+    put:
+      tags:
+      - Personas
+      summary: Update personal persona
+      security:
+      - bearerAuth: []
+      parameters:
+      - $ref: '#/components/parameters/ResourceID'
+      responses:
+        '200':
+          description: Updated
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Persona'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+    delete:
+      tags:
+      - Personas
+      summary: Delete personal persona
+      security:
+      - bearerAuth: []
+      parameters:
+      - $ref: '#/components/parameters/ResourceID'
+      responses:
+        '200':
+          description: Deleted
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MessageResponse'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+  /api/v1/personas/{id}/avatar:
+    post:
+      tags:
+      - Personas
+      summary: Upload persona avatar
+      security:
+      - bearerAuth: []
+      parameters:
+      - $ref: '#/components/parameters/ResourceID'
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                image:
+                  type: string
+      responses:
+        '200':
+          description: Avatar uploaded
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Persona'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '201':
+          description: Success
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MessageResponse'
+    delete:
+      tags:
+      - Personas
+      summary: Delete persona avatar
+      security:
+      - bearerAuth: []
+      parameters:
+      - $ref: '#/components/parameters/ResourceID'
+      responses:
+        '200':
+          description: Avatar removed
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MessageResponse'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+  /api/v1/personas/{id}/knowledge-bases:
+    get:
+      tags:
+      - Personas
+      - Knowledge Bases
+      summary: Get persona KB bindings
+      security:
+      - bearerAuth: []
+      parameters:
+      - $ref: '#/components/parameters/ResourceID'
+      responses:
+        '200':
+          description: Persona KB bindings
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  data:
+                    type: array
+                    items:
+                      $ref: '#/components/schemas/Persona'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+    put:
+      tags:
+      - Personas
+      - Knowledge Bases
+      summary: Set persona KB bindings (replace all)
+      security:
+      - bearerAuth: []
+      parameters:
+      - $ref: '#/components/parameters/ResourceID'
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                kb_ids:
+                  type: array
+                  items:
+                    type: string
+                    format: uuid
+                auto_search:
+                  type: object
+                  additionalProperties:
+                    type: boolean
+      responses:
+        '200':
+          description: Bindings updated
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Persona'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+  /api/v1/personas/{id}/tool-grants:
+    get:
+      tags:
+      - Personas
+      summary: Get persona tool grants
+      security:
+      - bearerAuth: []
+      parameters:
+      - $ref: '#/components/parameters/ResourceID'
+      responses:
+        '200':
+          description: Tool grant list
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  data:
+                    type: array
+                    items:
+                      $ref: '#/components/schemas/Persona'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+    put:
+      tags:
+      - Personas
+      summary: Set persona tool grants
+      security:
+      - bearerAuth: []
+      parameters:
+      - $ref: '#/components/parameters/ResourceID'
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                tool_names:
+                  type: array
+                  items:
+                    type: string
+      responses:
+        '200':
+          description: Grants updated
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Persona'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+  /api/v1/persona-groups:
+    get:
+      tags:
+      - Personas
+      summary: List persona groups
+      security:
+      - bearerAuth: []
+      responses:
+        '200':
+          description: Persona group list
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  data:
+                    type: array
+                    items:
+                      $ref: '#/components/schemas/Persona'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+    post:
+      tags:
+      - Personas
+      summary: Create persona group
+      security:
+      - bearerAuth: []
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required:
+              - name
+              properties:
+                name:
+                  type: string
+                description:
+                  type: string
+      responses:
+        '201':
+          description: Group created
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Persona'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '200':
+          description: Success
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MessageResponse'
+  /api/v1/persona-groups/{id}:
+    get:
+      tags:
+      - Personas
+      summary: Get persona group with members
+      security:
+      - bearerAuth: []
+      parameters:
+      - $ref: '#/components/parameters/ResourceID'
+      responses:
+        '200':
+          description: Group with members
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Persona'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+    put:
+      tags:
+      - Personas
+      summary: Update persona group
+      security:
+      - bearerAuth: []
+      parameters:
+      - $ref: '#/components/parameters/ResourceID'
+      responses:
+        '200':
+          description: Updated
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Persona'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+    delete:
+      tags:
+      - Personas
+      summary: Delete persona group
+      security:
+      - bearerAuth: []
+      parameters:
+      - $ref: '#/components/parameters/ResourceID'
+      responses:
+        '200':
+          description: Deleted
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MessageResponse'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+  /api/v1/persona-groups/{id}/members:
+    post:
+      tags:
+      - Personas
+      summary: Add persona to group
+      security:
+      - bearerAuth: []
+      parameters:
+      - $ref: '#/components/parameters/ResourceID'
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              required:
+              - persona_id
+              properties:
+                persona_id:
+                  type: string
+                  format: uuid
+                is_leader:
+                  type: boolean
+                  default: false
+      responses:
+        '201':
+          description: Member added
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Persona'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '200':
+          description: Success
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MessageResponse'
+  /api/v1/persona-groups/{id}/members/{memberId}:
+    delete:
+      tags:
+      - Personas
+      summary: Remove persona from group
+      security:
+      - bearerAuth: []
+      parameters:
+      - $ref: '#/components/parameters/ResourceID'
+      - name: memberId
+        in: path
+        required: true
+        schema:
+          type: string
+          format: uuid
+      responses:
+        '200':
+          description: Removed
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MessageResponse'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+  /api/v1/models/enabled:
+    get:
+      tags:
+      - Models
+      summary: List models available to current user
+      description: Primary endpoint for model selectors. Returns models, personas, and default.
+      security:
+      - bearerAuth: []
+      responses:
+        '200':
+          description: Available models with default
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  data:
+                    type: array
+                    items:
+                      type: object
+                  default_model:
+                    type: string
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+  /api/v1/models/preferences:
+    get:
+      tags:
+      - Models
+      summary: Get user model preferences
+      security:
+      - bearerAuth: []
+      responses:
+        '200':
+          description: User model preferences
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  data:
+                    type: array
+                    items:
+                      type: object
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+    put:
+      tags:
+      - Models
+      summary: Set model preference (upsert)
+      security:
+      - bearerAuth: []
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required:
+              - model_id
+              - provider_config_id
+              properties:
+                model_id:
+                  type: string
+                provider_config_id:
+                  type: string
+                  format: uuid
+                hidden:
+                  type: boolean
+                sort_order:
+                  type: integer
+      responses:
+        '200':
+          description: Preference updated
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MessageResponse'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+  /api/v1/models/preferences/bulk:
+    post:
+      tags:
+      - Models
+      summary: Bulk set model visibility
+      security:
+      - bearerAuth: []
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required:
+              - entries
+              - hidden
+              properties:
+                entries:
+                  type: array
+                  items:
+                    type: object
+                    properties:
+                      model_id:
+                        type: string
+                      provider_config_id:
+                        type: string
+                        format: uuid
+                hidden:
+                  type: boolean
+      responses:
+        '200':
+          description: Preferences updated
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MessageResponse'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '201':
+          description: Success
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MessageResponse'
+  /api/v1/api-configs:
+    get:
+      tags:
+      - Providers
+      summary: List user's BYOK provider configs
+      security:
+      - bearerAuth: []
+      responses:
+        '200':
+          description: Provider configs (keys redacted)
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  data:
+                    type: array
+                    items:
+                      $ref: '#/components/schemas/ProviderConfig'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+    post:
+      tags:
+      - Providers
+      summary: Create BYOK provider config
+      security:
+      - bearerAuth: []
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/ProviderConfigInput'
+      responses:
+        '201':
+          description: Config created
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ProviderConfig'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '200':
+          description: Success
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MessageResponse'
+  /api/v1/api-configs/{id}:
+    get:
+      tags:
+      - Providers
+      summary: Get provider config (key redacted)
+      security:
+      - bearerAuth: []
+      parameters:
+      - $ref: '#/components/parameters/ResourceID'
+      responses:
+        '200':
+          description: Provider config
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ProviderConfig'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+    put:
+      tags:
+      - Providers
+      summary: Update provider config
+      security:
+      - bearerAuth: []
+      parameters:
+      - $ref: '#/components/parameters/ResourceID'
+      responses:
+        '200':
+          description: Updated
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ProviderConfig'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+    delete:
+      tags:
+      - Providers
+      summary: Delete provider config
+      security:
+      - bearerAuth: []
+      parameters:
+      - $ref: '#/components/parameters/ResourceID'
+      responses:
+        '200':
+          description: Deleted
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MessageResponse'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+  /api/v1/api-configs/{id}/models:
+    get:
+      tags:
+      - Providers
+      summary: List models for a provider config
+      security:
+      - bearerAuth: []
+      parameters:
+      - $ref: '#/components/parameters/ResourceID'
+      responses:
+        '200':
+          description: Model catalog entries
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  data:
+                    type: array
+                    items:
+                      $ref: '#/components/schemas/ProviderConfig'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+  /api/v1/api-configs/{id}/models/fetch:
+    post:
+      tags:
+      - Providers
+      summary: Sync models from provider API
+      security:
+      - bearerAuth: []
+      parameters:
+      - $ref: '#/components/parameters/ResourceID'
+      responses:
+        '200':
+          description: Models synced
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ProviderConfig'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '201':
+          description: Success
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MessageResponse'
+  /api/v1/notes:
+    get:
+      tags:
+      - Notes
+      summary: List notes (paginated)
+      security:
+      - bearerAuth: []
+      parameters:
+      - $ref: '#/components/parameters/Page'
+      - $ref: '#/components/parameters/PerPage'
+      - name: folder
+        in: query
+        schema:
+          type: string
+      responses:
+        '200':
+          description: Note list
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  data:
+                    type: array
+                    items:
+                      $ref: '#/components/schemas/Note'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+    post:
+      tags:
+      - Notes
+      summary: Create note
+      security:
+      - bearerAuth: []
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required:
+              - title
+              properties:
+                title:
+                  type: string
+                content:
+                  type: string
+                folder:
+                  type: string
+      responses:
+        '201':
+          description: Note created
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Note'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '200':
+          description: Success
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MessageResponse'
+  /api/v1/notes/{id}:
+    get:
+      tags:
+      - Notes
+      summary: Get note
+      security:
+      - bearerAuth: []
+      parameters:
+      - $ref: '#/components/parameters/ResourceID'
+      responses:
+        '200':
+          description: Full note object
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Note'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+    put:
+      tags:
+      - Notes
+      summary: Update note
+      security:
+      - bearerAuth: []
+      parameters:
+      - $ref: '#/components/parameters/ResourceID'
+      responses:
+        '200':
+          description: Updated
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Note'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+    delete:
+      tags:
+      - Notes
+      summary: Delete note
+      security:
+      - bearerAuth: []
+      parameters:
+      - $ref: '#/components/parameters/ResourceID'
+      responses:
+        '200':
+          description: Deleted
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MessageResponse'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+  /api/v1/notes/{id}/backlinks:
+    get:
+      tags:
+      - Notes
+      summary: Get notes that link to this note
+      security:
+      - bearerAuth: []
+      parameters:
+      - $ref: '#/components/parameters/ResourceID'
+      responses:
+        '200':
+          description: Backlink list
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  data:
+                    type: array
+                    items:
+                      $ref: '#/components/schemas/Note'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+  /api/v1/notes/search:
+    get:
+      tags:
+      - Notes
+      summary: Full-text search notes
+      security:
+      - bearerAuth: []
+      parameters:
+      - name: q
+        in: query
+        required: true
+        schema:
+          type: string
+      responses:
+        '200':
+          description: Search results with highlights
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  data:
+                    type: array
+                    items:
+                      $ref: '#/components/schemas/Note'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+  /api/v1/notes/search-titles:
+    get:
+      tags:
+      - Notes
+      summary: Title search (for wikilink autocomplete)
+      security:
+      - bearerAuth: []
+      parameters:
+      - name: q
+        in: query
+        required: true
+        schema:
+          type: string
+      responses:
+        '200':
+          description: Matching titles
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  data:
+                    type: array
+                    items:
+                      $ref: '#/components/schemas/Note'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+  /api/v1/notes/graph:
+    get:
+      tags:
+      - Notes
+      summary: Get note graph topology
+      security:
+      - bearerAuth: []
+      responses:
+        '200':
+          description: Graph with nodes, edges, and unresolved links
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  nodes:
+                    type: array
+                    items:
+                      type: object
+                      properties:
+                        id:
+                          type: string
+                          format: uuid
+                        title:
+                          type: string
+                  edges:
+                    type: array
+                    items:
+                      type: object
+                      properties:
+                        source:
+                          type: string
+                          format: uuid
+                        target:
+                          type: string
+                          format: uuid
+                  unresolved:
+                    type: array
+                    items:
+                      type: object
+                      properties:
+                        source:
+                          type: string
+                          format: uuid
+                        target_title:
+                          type: string
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+  /api/v1/notes/folders:
+    get:
+      tags:
+      - Notes
+      summary: List distinct note folder names
+      security:
+      - bearerAuth: []
+      responses:
+        '200':
+          description: Folder list
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  data:
+                    type: array
+                    items:
+                      $ref: '#/components/schemas/Note'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+  /api/v1/notes/bulk-delete:
+    post:
+      tags:
+      - Notes
+      summary: Bulk delete notes
+      security:
+      - bearerAuth: []
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required:
+              - ids
+              properties:
+                ids:
+                  type: array
+                  items:
+                    type: string
+                    format: uuid
+      responses:
+        '200':
+          description: Notes deleted
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Note'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '201':
+          description: Success
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MessageResponse'
+  /api/v1/knowledge-bases:
+    get:
+      tags:
+      - Knowledge Bases
+      summary: List knowledge bases
+      security:
+      - bearerAuth: []
+      responses:
+        '200':
+          description: KB list
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  data:
+                    type: array
+                    items:
+                      $ref: '#/components/schemas/KnowledgeBase'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+    post:
+      tags:
+      - Knowledge Bases
+      summary: Create knowledge base
+      security:
+      - bearerAuth: []
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required:
+              - name
+              properties:
+                name:
+                  type: string
+                description:
+                  type: string
+                scope:
+                  type: string
+                  enum:
+                  - personal
+                  - team
+                  - global
+                  default: personal
+                team_id:
+                  type: string
+                  format: uuid
+      responses:
+        '201':
+          description: KB created
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/KnowledgeBase'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '200':
+          description: Success
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MessageResponse'
+  /api/v1/knowledge-bases/{id}:
+    get:
+      tags:
+      - Knowledge Bases
+      summary: Get knowledge base
+      security:
+      - bearerAuth: []
+      parameters:
+      - $ref: '#/components/parameters/ResourceID'
+      responses:
+        '200':
+          description: KB object
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/KnowledgeBase'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+    put:
+      tags:
+      - Knowledge Bases
+      summary: Update knowledge base
+      security:
+      - bearerAuth: []
+      parameters:
+      - $ref: '#/components/parameters/ResourceID'
+      responses:
+        '200':
+          description: Updated
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/KnowledgeBase'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+    delete:
+      tags:
+      - Knowledge Bases
+      summary: Delete knowledge base
+      security:
+      - bearerAuth: []
+      parameters:
+      - $ref: '#/components/parameters/ResourceID'
+      responses:
+        '200':
+          description: Deleted
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MessageResponse'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+  /api/v1/knowledge-bases/{id}/documents:
+    get:
+      tags:
+      - Knowledge Bases
+      summary: List KB documents
+      security:
+      - bearerAuth: []
+      parameters:
+      - $ref: '#/components/parameters/ResourceID'
+      responses:
+        '200':
+          description: Document list
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  data:
+                    type: array
+                    items:
+                      $ref: '#/components/schemas/KnowledgeBase'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+    post:
+      tags:
+      - Knowledge Bases
+      summary: Upload document to KB
+      security:
+      - bearerAuth: []
+      parameters:
+      - $ref: '#/components/parameters/ResourceID'
+      requestBody:
+        required: true
+        content:
+          multipart/form-data:
+            schema:
+              type: object
+              properties:
+                file:
+                  type: string
+                  format: binary
+      responses:
+        '202':
+          description: Document accepted for processing
+          content:
+            application/json:
+              schema:
+                type: object
+        '412':
+          description: No embedding model configured
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '200':
+          description: Success
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MessageResponse'
+        '201':
+          description: Success
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MessageResponse'
+  /api/v1/knowledge-bases/{id}/documents/{docId}/status:
+    get:
+      tags:
+      - Knowledge Bases
+      summary: Get document processing status
+      security:
+      - bearerAuth: []
+      parameters:
+      - $ref: '#/components/parameters/ResourceID'
+      - name: docId
+        in: path
+        required: true
+        schema:
+          type: string
+          format: uuid
+      responses:
+        '200':
+          description: Document status
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  data:
+                    type: array
+                    items:
+                      $ref: '#/components/schemas/KnowledgeBase'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+  /api/v1/knowledge-bases/{id}/documents/{docId}:
+    delete:
+      tags:
+      - Knowledge Bases
+      summary: Delete KB document
+      security:
+      - bearerAuth: []
+      parameters:
+      - $ref: '#/components/parameters/ResourceID'
+      - name: docId
+        in: path
+        required: true
+        schema:
+          type: string
+          format: uuid
+      responses:
+        '200':
+          description: Deleted
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MessageResponse'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+  /api/v1/knowledge-bases/{id}/search:
+    post:
+      tags:
+      - Knowledge Bases
+      summary: Semantic search within KB
+      security:
+      - bearerAuth: []
+      parameters:
+      - $ref: '#/components/parameters/ResourceID'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required:
+              - query
+              properties:
+                query:
+                  type: string
+                limit:
+                  type: integer
+                  default: 5
+                  maximum: 20
+                threshold:
+                  type: number
+                  default: 0.3
+      responses:
+        '200':
+          description: Search results with similarity scores
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/KnowledgeBase'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '201':
+          description: Success
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MessageResponse'
+  /api/v1/knowledge-bases/{id}/rebuild:
+    post:
+      tags:
+      - Knowledge Bases
+      summary: Re-chunk and re-embed all documents
+      security:
+      - bearerAuth: []
+      parameters:
+      - $ref: '#/components/parameters/ResourceID'
+      responses:
+        '202':
+          description: Rebuild started
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  message:
+                    type: string
+                  total_docs:
+                    type: integer
+                  rebuilding:
+                    type: integer
+                  skipped:
+                    type: integer
+        '503':
+          description: Ingestion pipeline not configured
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '200':
+          description: Success
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MessageResponse'
+        '201':
+          description: Success
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MessageResponse'
+  /api/v1/knowledge-bases-discoverable:
+    get:
+      tags:
+      - Knowledge Bases
+      summary: List discoverable KBs (for picker UI)
+      security:
+      - bearerAuth: []
+      responses:
+        '200':
+          description: Discoverable KB list
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  data:
+                    type: array
+                    items:
+                      $ref: '#/components/schemas/KnowledgeBase'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+  /api/v1/knowledge-bases/{id}/discoverable:
+    put:
+      tags:
+      - Knowledge Bases
+      summary: Toggle KB discoverability
+      security:
+      - bearerAuth: []
+      parameters:
+      - $ref: '#/components/parameters/ResourceID'
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                discoverable:
+                  type: boolean
+      responses:
+        '200':
+          description: Updated
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/KnowledgeBase'
+        '403':
+          description: Only owner or admin can change
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+  /api/v1/memories:
+    get:
+      tags:
+      - Memory
+      summary: List user's memories
+      security:
+      - bearerAuth: []
+      parameters:
+      - name: status
+        in: query
+        schema:
+          type: string
+          enum:
+          - active
+          - pending_review
+          - archived
+          default: active
+      - name: query
+        in: query
+        schema:
+          type: string
+      responses:
+        '200':
+          description: Memory list
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  data:
+                    type: array
+                    items:
+                      $ref: '#/components/schemas/Memory'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+  /api/v1/memories/{id}:
+    put:
+      tags:
+      - Memory
+      summary: Update memory
+      security:
+      - bearerAuth: []
+      parameters:
+      - $ref: '#/components/parameters/ResourceID'
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                key:
+                  type: string
+                value:
+                  type: string
+                confidence:
+                  type: number
+      responses:
+        '200':
+          description: Updated
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Memory'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+    delete:
+      tags:
+      - Memory
+      summary: Delete memory
+      security:
+      - bearerAuth: []
+      parameters:
+      - $ref: '#/components/parameters/ResourceID'
+      responses:
+        '200':
+          description: Deleted
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MessageResponse'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+  /api/v1/memories/{id}/approve:
+    post:
+      tags:
+      - Memory
+      summary: Approve a pending memory
+      security:
+      - bearerAuth: []
+      parameters:
+      - $ref: '#/components/parameters/ResourceID'
+      responses:
+        '200':
+          description: Approved
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Memory'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '201':
+          description: Success
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MessageResponse'
+  /api/v1/memories/{id}/reject:
+    post:
+      tags:
+      - Memory
+      summary: Reject a pending memory
+      security:
+      - bearerAuth: []
+      parameters:
+      - $ref: '#/components/parameters/ResourceID'
+      responses:
+        '200':
+          description: Rejected
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Memory'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '201':
+          description: Success
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MessageResponse'
+  /api/v1/memories/count:
+    get:
+      tags:
+      - Memory
+      summary: Get memory counts by status
+      security:
+      - bearerAuth: []
+      responses:
+        '200':
+          description: Memory counts
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  active:
+                    type: integer
+                  pending:
+                    type: integer
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+  /api/v1/memories/compact:
+    post:
+      tags:
+      - Memory
+      summary: Compact memories
+      security:
+      - bearerAuth: []
+      responses:
+        '200':
+          description: Compaction triggered
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Memory'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '201':
+          description: Success
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MessageResponse'
+  /api/v1/projects:
+    get:
+      tags:
+      - Projects
+      summary: List projects
+      security:
+      - bearerAuth: []
+      parameters:
+      - name: include_archived
+        in: query
+        schema:
+          type: boolean
+          default: false
+      responses:
+        '200':
+          description: Project list
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  data:
+                    type: array
+                    items:
+                      $ref: '#/components/schemas/Project'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+    post:
+      tags:
+      - Projects
+      summary: Create project
+      security:
+      - bearerAuth: []
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required:
+              - name
+              properties:
+                name:
+                  type: string
+                  maxLength: 200
+                description:
+                  type: string
+                color:
+                  type: string
+                icon:
+                  type: string
+      responses:
+        '201':
+          description: Project created
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Project'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '200':
+          description: Success
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MessageResponse'
+  /api/v1/projects/{id}:
+    get:
+      tags:
+      - Projects
+      summary: Get project
+      security:
+      - bearerAuth: []
+      parameters:
+      - $ref: '#/components/parameters/ResourceID'
+      responses:
+        '200':
+          description: Project object
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Project'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+    put:
+      tags:
+      - Projects
+      summary: Update project
+      security:
+      - bearerAuth: []
+      parameters:
+      - $ref: '#/components/parameters/ResourceID'
+      responses:
+        '200':
+          description: Updated
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Project'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+    delete:
+      tags:
+      - Projects
+      summary: Delete project
+      security:
+      - bearerAuth: []
+      parameters:
+      - $ref: '#/components/parameters/ResourceID'
+      responses:
+        '200':
+          description: Deleted
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MessageResponse'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+  /api/v1/projects/{id}/channels:
+    get:
+      tags:
+      - Projects
+      summary: List project channels
+      security:
+      - bearerAuth: []
+      parameters:
+      - $ref: '#/components/parameters/ResourceID'
+      responses:
+        '200':
+          description: Project channels
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  data:
+                    type: array
+                    items:
+                      $ref: '#/components/schemas/Channel'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+    post:
+      tags:
+      - Projects
+      summary: Add channel to project
+      security:
+      - bearerAuth: []
+      parameters:
+      - $ref: '#/components/parameters/ResourceID'
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              required:
+              - channel_id
+              properties:
+                channel_id:
+                  type: string
+                  format: uuid
+                position:
+                  type: integer
+      responses:
+        '200':
+          description: Channel added
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MessageResponse'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '403':
+          $ref: '#/components/responses/Forbidden'
+  /api/v1/projects/{id}/channels/{channelId}:
+    delete:
+      tags:
+      - Projects
+      summary: Remove channel from project
+      security:
+      - bearerAuth: []
+      parameters:
+      - $ref: '#/components/parameters/ResourceID'
+      - name: channelId
+        in: path
+        required: true
+        schema:
+          type: string
+          format: uuid
+      responses:
+        '200':
+          description: Removed
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MessageResponse'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+  /api/v1/projects/{id}/channels/reorder:
+    put:
+      tags:
+      - Projects
+      summary: Reorder project channels
+      security:
+      - bearerAuth: []
+      parameters:
+      - $ref: '#/components/parameters/ResourceID'
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                channel_ids:
+                  type: array
+                  items:
+                    type: string
+                    format: uuid
+      responses:
+        '200':
+          description: Reordered
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Project'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+  /api/v1/projects/{id}/knowledge-bases:
+    get:
+      tags:
+      - Projects
+      - Knowledge Bases
+      summary: List project KB associations
+      security:
+      - bearerAuth: []
+      parameters:
+      - $ref: '#/components/parameters/ResourceID'
+      responses:
+        '200':
+          description: Project KBs
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  data:
+                    type: array
+                    items:
+                      $ref: '#/components/schemas/Project'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+    post:
+      tags:
+      - Projects
+      - Knowledge Bases
+      summary: Add KB to project
+      security:
+      - bearerAuth: []
+      parameters:
+      - $ref: '#/components/parameters/ResourceID'
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              required:
+              - kb_id
+              properties:
+                kb_id:
+                  type: string
+                  format: uuid
+                auto_search:
+                  type: boolean
+                  default: false
+      responses:
+        '201':
+          description: KB added
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Project'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '200':
+          description: Success
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MessageResponse'
+  /api/v1/projects/{id}/knowledge-bases/{kbId}:
+    delete:
+      tags:
+      - Projects
+      - Knowledge Bases
+      summary: Remove KB from project
+      security:
+      - bearerAuth: []
+      parameters:
+      - $ref: '#/components/parameters/ResourceID'
+      - name: kbId
+        in: path
+        required: true
+        schema:
+          type: string
+          format: uuid
+      responses:
+        '200':
+          description: Removed
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MessageResponse'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+  /api/v1/projects/{id}/notes:
+    get:
+      tags:
+      - Projects
+      - Notes
+      summary: List project note associations
+      security:
+      - bearerAuth: []
+      parameters:
+      - $ref: '#/components/parameters/ResourceID'
+      responses:
+        '200':
+          description: Project notes
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  data:
+                    type: array
+                    items:
+                      $ref: '#/components/schemas/Project'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+    post:
+      tags:
+      - Projects
+      - Notes
+      summary: Add note to project
+      security:
+      - bearerAuth: []
+      parameters:
+      - $ref: '#/components/parameters/ResourceID'
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              required:
+              - note_id
+              properties:
+                note_id:
+                  type: string
+                  format: uuid
+      responses:
+        '201':
+          description: Note added
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Project'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '200':
+          description: Success
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MessageResponse'
+  /api/v1/projects/{id}/notes/{noteId}:
+    delete:
+      tags:
+      - Projects
+      - Notes
+      summary: Remove note from project
+      security:
+      - bearerAuth: []
+      parameters:
+      - $ref: '#/components/parameters/ResourceID'
+      - name: noteId
+        in: path
+        required: true
+        schema:
+          type: string
+          format: uuid
+      responses:
+        '200':
+          description: Removed
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MessageResponse'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+  /api/v1/projects/{id}/files:
+    get:
+      tags:
+      - Projects
+      - Files
+      summary: List project files
+      security:
+      - bearerAuth: []
+      parameters:
+      - $ref: '#/components/parameters/ResourceID'
+      responses:
+        '200':
+          description: Project files
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  data:
+                    type: array
+                    items:
+                      $ref: '#/components/schemas/Project'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+    post:
+      tags:
+      - Projects
+      - Files
+      summary: Upload file to project
+      security:
+      - bearerAuth: []
+      parameters:
+      - $ref: '#/components/parameters/ResourceID'
+      requestBody:
+        content:
+          multipart/form-data:
+            schema:
+              type: object
+              properties:
+                file:
+                  type: string
+                  format: binary
+      responses:
+        '201':
+          description: File uploaded
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Project'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '200':
+          description: Success
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MessageResponse'
+  /api/v1/workspaces:
+    get:
+      tags:
+      - Workspaces
+      summary: List workspaces
+      security:
+      - bearerAuth: []
+      responses:
+        '200':
+          description: Workspace list
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  data:
+                    type: array
+                    items:
+                      $ref: '#/components/schemas/Workspace'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+    post:
+      tags:
+      - Workspaces
+      summary: Create workspace
+      security:
+      - bearerAuth: []
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required:
+              - name
+              properties:
+                name:
+                  type: string
+                owner_type:
+                  type: string
+                  enum:
+                  - user
+                  - project
+                  - channel
+                  - team
+                owner_id:
+                  type: string
+                  format: uuid
+      responses:
+        '201':
+          description: Workspace created
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Workspace'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '200':
+          description: Success
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MessageResponse'
+  /api/v1/workspaces/{id}:
+    get:
+      tags:
+      - Workspaces
+      summary: Get workspace
+      security:
+      - bearerAuth: []
+      parameters:
+      - $ref: '#/components/parameters/ResourceID'
+      responses:
+        '200':
+          description: Workspace object
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Workspace'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+    patch:
+      tags:
+      - Workspaces
+      summary: Update workspace
+      security:
+      - bearerAuth: []
+      parameters:
+      - $ref: '#/components/parameters/ResourceID'
+      responses:
+        '200':
+          description: Updated
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Workspace'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+    delete:
+      tags:
+      - Workspaces
+      summary: Delete workspace
+      security:
+      - bearerAuth: []
+      parameters:
+      - $ref: '#/components/parameters/ResourceID'
+      responses:
+        '200':
+          description: Deleted
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MessageResponse'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+  /api/v1/workspaces/{id}/files:
+    get:
+      tags:
+      - Workspaces
+      summary: List workspace files
+      security:
+      - bearerAuth: []
+      parameters:
+      - $ref: '#/components/parameters/ResourceID'
+      responses:
+        '200':
+          description: File tree
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  data:
+                    type: array
+                    items:
+                      $ref: '#/components/schemas/Workspace'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+  /api/v1/workspaces/{id}/files/read:
+    get:
+      tags:
+      - Workspaces
+      summary: Read file content
+      security:
+      - bearerAuth: []
+      parameters:
+      - $ref: '#/components/parameters/ResourceID'
+      - name: path
+        in: query
+        required: true
+        schema:
+          type: string
+      responses:
+        '200':
+          description: File content
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  data:
+                    type: array
+                    items:
+                      $ref: '#/components/schemas/Workspace'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+  /api/v1/workspaces/{id}/files/write:
+    put:
+      tags:
+      - Workspaces
+      summary: Write file content
+      security:
+      - bearerAuth: []
+      parameters:
+      - $ref: '#/components/parameters/ResourceID'
+      responses:
+        '200':
+          description: File written
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Workspace'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+  /api/v1/workspaces/{id}/files/delete:
+    delete:
+      tags:
+      - Workspaces
+      summary: Delete workspace file
+      security:
+      - bearerAuth: []
+      parameters:
+      - $ref: '#/components/parameters/ResourceID'
+      responses:
+        '200':
+          description: Deleted
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MessageResponse'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+  /api/v1/workspaces/{id}/files/mkdir:
+    post:
+      tags:
+      - Workspaces
+      summary: Create directory
+      security:
+      - bearerAuth: []
+      parameters:
+      - $ref: '#/components/parameters/ResourceID'
+      responses:
+        '201':
+          description: Directory created
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Workspace'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '200':
+          description: Success
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MessageResponse'
+  /api/v1/workspaces/{id}/archive/upload:
+    post:
+      tags:
+      - Workspaces
+      summary: Upload archive (zip/tar.gz) to workspace
+      security:
+      - bearerAuth: []
+      parameters:
+      - $ref: '#/components/parameters/ResourceID'
+      responses:
+        '200':
+          description: Archive extracted
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Workspace'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '201':
+          description: Success
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MessageResponse'
+  /api/v1/workspaces/{id}/archive/download:
+    get:
+      tags:
+      - Workspaces
+      summary: Download workspace as archive
+      security:
+      - bearerAuth: []
+      parameters:
+      - $ref: '#/components/parameters/ResourceID'
+      responses:
+        '200':
+          description: Archive download
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  data:
+                    type: array
+                    items:
+                      $ref: '#/components/schemas/Workspace'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+  /api/v1/workspaces/{id}/reconcile:
+    post:
+      tags:
+      - Workspaces
+      summary: Reconcile workspace state
+      security:
+      - bearerAuth: []
+      parameters:
+      - $ref: '#/components/parameters/ResourceID'
+      responses:
+        '200':
+          description: Reconciled
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Workspace'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '201':
+          description: Success
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MessageResponse'
+  /api/v1/workspaces/{id}/stats:
+    get:
+      tags:
+      - Workspaces
+      summary: Get workspace statistics
+      security:
+      - bearerAuth: []
+      parameters:
+      - $ref: '#/components/parameters/ResourceID'
+      responses:
+        '200':
+          description: Workspace stats
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  data:
+                    type: array
+                    items:
+                      $ref: '#/components/schemas/Workspace'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+  /api/v1/workspaces/{id}/index-status:
+    get:
+      tags:
+      - Workspaces
+      summary: Get full-text index status
+      security:
+      - bearerAuth: []
+      parameters:
+      - $ref: '#/components/parameters/ResourceID'
+      responses:
+        '200':
+          description: Index status
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  data:
+                    type: array
+                    items:
+                      $ref: '#/components/schemas/Workspace'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+  /api/v1/workspaces/{id}/git/clone:
+    post:
+      tags:
+      - Workspaces
+      summary: Clone git remote into workspace
+      security:
+      - bearerAuth: []
+      parameters:
+      - $ref: '#/components/parameters/ResourceID'
+      responses:
+        '200':
+          description: Clone started
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Workspace'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '201':
+          description: Success
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MessageResponse'
+  /api/v1/workspaces/{id}/git/pull:
+    post:
+      tags:
+      - Workspaces
+      summary: Pull from remote
+      security:
+      - bearerAuth: []
+      parameters:
+      - $ref: '#/components/parameters/ResourceID'
+      responses:
+        '200':
+          description: Pull complete
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Workspace'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '201':
+          description: Success
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MessageResponse'
+  /api/v1/workspaces/{id}/git/push:
+    post:
+      tags:
+      - Workspaces
+      summary: Push to remote
+      security:
+      - bearerAuth: []
+      parameters:
+      - $ref: '#/components/parameters/ResourceID'
+      responses:
+        '200':
+          description: Push complete
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Workspace'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '201':
+          description: Success
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MessageResponse'
+  /api/v1/workspaces/{id}/git/status:
+    get:
+      tags:
+      - Workspaces
+      summary: Git status
+      security:
+      - bearerAuth: []
+      parameters:
+      - $ref: '#/components/parameters/ResourceID'
+      responses:
+        '200':
+          description: Working tree status
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  data:
+                    type: array
+                    items:
+                      $ref: '#/components/schemas/Workspace'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+  /api/v1/workspaces/{id}/git/diff:
+    get:
+      tags:
+      - Workspaces
+      summary: Git diff
+      security:
+      - bearerAuth: []
+      parameters:
+      - $ref: '#/components/parameters/ResourceID'
+      responses:
+        '200':
+          description: Diff output
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  data:
+                    type: array
+                    items:
+                      $ref: '#/components/schemas/Workspace'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+  /api/v1/workspaces/{id}/git/commit:
+    post:
+      tags:
+      - Workspaces
+      summary: Commit changes
+      security:
+      - bearerAuth: []
+      parameters:
+      - $ref: '#/components/parameters/ResourceID'
+      responses:
+        '200':
+          description: Committed
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Workspace'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '201':
+          description: Success
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MessageResponse'
+  /api/v1/workspaces/{id}/git/log:
+    get:
+      tags:
+      - Workspaces
+      summary: Git log
+      security:
+      - bearerAuth: []
+      parameters:
+      - $ref: '#/components/parameters/ResourceID'
+      responses:
+        '200':
+          description: Commit history
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  data:
+                    type: array
+                    items:
+                      $ref: '#/components/schemas/Workspace'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+  /api/v1/workspaces/{id}/git/branches:
+    get:
+      tags:
+      - Workspaces
+      summary: List git branches
+      security:
+      - bearerAuth: []
+      parameters:
+      - $ref: '#/components/parameters/ResourceID'
+      responses:
+        '200':
+          description: Branch list
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  data:
+                    type: array
+                    items:
+                      $ref: '#/components/schemas/Workspace'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+  /api/v1/workspaces/{id}/git/checkout:
+    post:
+      tags:
+      - Workspaces
+      summary: Checkout branch
+      security:
+      - bearerAuth: []
+      parameters:
+      - $ref: '#/components/parameters/ResourceID'
+      responses:
+        '200':
+          description: Checked out
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Workspace'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '201':
+          description: Success
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MessageResponse'
+  /api/v1/git-credentials:
+    get:
+      tags:
+      - Workspaces
+      summary: List git credentials
+      security:
+      - bearerAuth: []
+      responses:
+        '200':
+          description: Credential list (keys redacted)
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  data:
+                    type: array
+                    items:
+                      $ref: '#/components/schemas/Workspace'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+    post:
+      tags:
+      - Workspaces
+      summary: Create git credential
+      security:
+      - bearerAuth: []
+      responses:
+        '201':
+          description: Credential created
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Workspace'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '200':
+          description: Success
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MessageResponse'
+  /api/v1/git-credentials/generate:
+    post:
+      tags:
+      - Workspaces
+      summary: Generate SSH key pair
+      security:
+      - bearerAuth: []
+      responses:
+        '201':
+          description: Key pair generated
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Workspace'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '200':
+          description: Success
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MessageResponse'
+  /api/v1/git-credentials/{id}/public-key:
+    get:
+      tags:
+      - Workspaces
+      summary: Get SSH public key
+      security:
+      - bearerAuth: []
+      parameters:
+      - $ref: '#/components/parameters/ResourceID'
+      responses:
+        '200':
+          description: Public key
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  data:
+                    type: array
+                    items:
+                      $ref: '#/components/schemas/Workspace'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+  /api/v1/git-credentials/{id}:
+    delete:
+      tags:
+      - Workspaces
+      summary: Delete git credential
+      security:
+      - bearerAuth: []
+      parameters:
+      - $ref: '#/components/parameters/ResourceID'
+      responses:
+        '200':
+          description: Deleted
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MessageResponse'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+  /api/v1/tasks:
+    get:
+      tags:
+      - Tasks
+      summary: List user's tasks
+      security:
+      - bearerAuth: []
+      responses:
+        '200':
+          description: Task list
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  data:
+                    type: array
+                    items:
+                      $ref: '#/components/schemas/Task'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+    post:
+      tags:
+      - Tasks
+      summary: Create task
+      security:
+      - bearerAuth: []
+      responses:
+        '201':
+          description: Task created
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Task'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '200':
+          description: Success
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MessageResponse'
+  /api/v1/tasks/{id}:
+    get:
+      tags:
+      - Tasks
+      summary: Get task
+      security:
+      - bearerAuth: []
+      parameters:
+      - $ref: '#/components/parameters/ResourceID'
+      responses:
+        '200':
+          description: Task object
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Task'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+    put:
+      tags:
+      - Tasks
+      summary: Update task
+      security:
+      - bearerAuth: []
+      parameters:
+      - $ref: '#/components/parameters/ResourceID'
+      responses:
+        '200':
+          description: Updated
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Task'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+    delete:
+      tags:
+      - Tasks
+      summary: Delete task
+      security:
+      - bearerAuth: []
+      parameters:
+      - $ref: '#/components/parameters/ResourceID'
+      responses:
+        '200':
+          description: Deleted
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MessageResponse'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+  /api/v1/tasks/{id}/runs:
+    get:
+      tags:
+      - Tasks
+      summary: List task runs
+      security:
+      - bearerAuth: []
+      parameters:
+      - $ref: '#/components/parameters/ResourceID'
+      responses:
+        '200':
+          description: Run history
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  data:
+                    type: array
+                    items:
+                      $ref: '#/components/schemas/Task'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+  /api/v1/tasks/{id}/run:
+    post:
+      tags:
+      - Tasks
+      summary: Execute task immediately
+      security:
+      - bearerAuth: []
+      parameters:
+      - $ref: '#/components/parameters/ResourceID'
+      responses:
+        '200':
+          description: Run started
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Task'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '201':
+          description: Success
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MessageResponse'
+  /api/v1/tasks/{id}/kill:
+    post:
+      tags:
+      - Tasks
+      summary: Kill running task
+      security:
+      - bearerAuth: []
+      parameters:
+      - $ref: '#/components/parameters/ResourceID'
+      responses:
+        '200':
+          description: Task killed
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Task'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '201':
+          description: Success
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MessageResponse'
+  /api/v1/workflows:
+    get:
+      tags:
+      - Workflows
+      summary: List workflows
+      security:
+      - bearerAuth: []
+      responses:
+        '200':
+          description: Workflow list
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  data:
+                    type: array
+                    items:
+                      $ref: '#/components/schemas/Workflow'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+    post:
+      tags:
+      - Workflows
+      summary: Create workflow
+      security:
+      - bearerAuth: []
+      responses:
+        '201':
+          description: Workflow created
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Workflow'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '200':
+          description: Success
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MessageResponse'
+  /api/v1/workflows/{id}:
+    get:
+      tags:
+      - Workflows
+      summary: Get workflow
+      security:
+      - bearerAuth: []
+      parameters:
+      - $ref: '#/components/parameters/ResourceID'
+      responses:
+        '200':
+          description: Workflow object
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Workflow'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+    patch:
+      tags:
+      - Workflows
+      summary: Update workflow
+      security:
+      - bearerAuth: []
+      parameters:
+      - $ref: '#/components/parameters/ResourceID'
+      responses:
+        '200':
+          description: Updated
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Workflow'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+    delete:
+      tags:
+      - Workflows
+      summary: Delete workflow
+      security:
+      - bearerAuth: []
+      parameters:
+      - $ref: '#/components/parameters/ResourceID'
+      responses:
+        '200':
+          description: Deleted
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MessageResponse'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+  /api/v1/workflows/{id}/stages:
+    get:
+      tags:
+      - Workflows
+      summary: List workflow stages
+      security:
+      - bearerAuth: []
+      parameters:
+      - $ref: '#/components/parameters/ResourceID'
+      responses:
+        '200':
+          description: Stage list
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  data:
+                    type: array
+                    items:
+                      $ref: '#/components/schemas/Workflow'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+    post:
+      tags:
+      - Workflows
+      summary: Create workflow stage
+      security:
+      - bearerAuth: []
+      parameters:
+      - $ref: '#/components/parameters/ResourceID'
+      responses:
+        '201':
+          description: Stage created
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Workflow'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '200':
+          description: Success
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MessageResponse'
+  /api/v1/workflows/{id}/stages/{sid}:
+    put:
+      tags:
+      - Workflows
+      summary: Update workflow stage
+      security:
+      - bearerAuth: []
+      parameters:
+      - $ref: '#/components/parameters/ResourceID'
+      - name: sid
+        in: path
+        required: true
+        schema:
+          type: string
+          format: uuid
+      responses:
+        '200':
+          description: Updated
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Workflow'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+    delete:
+      tags:
+      - Workflows
+      summary: Delete workflow stage
+      security:
+      - bearerAuth: []
+      parameters:
+      - $ref: '#/components/parameters/ResourceID'
+      - name: sid
+        in: path
+        required: true
+        schema:
+          type: string
+          format: uuid
+      responses:
+        '200':
+          description: Deleted
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MessageResponse'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+  /api/v1/workflows/{id}/stages/reorder:
+    patch:
+      tags:
+      - Workflows
+      summary: Reorder workflow stages
+      security:
+      - bearerAuth: []
+      parameters:
+      - $ref: '#/components/parameters/ResourceID'
+      responses:
+        '200':
+          description: Reordered
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Workflow'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+  /api/v1/workflows/{id}/publish:
+    post:
+      tags:
+      - Workflows
+      summary: Publish workflow version
+      security:
+      - bearerAuth: []
+      parameters:
+      - $ref: '#/components/parameters/ResourceID'
+      responses:
+        '200':
+          description: Published
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Workflow'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '201':
+          description: Success
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MessageResponse'
+  /api/v1/workflows/{id}/versions/{version}:
+    get:
+      tags:
+      - Workflows
+      summary: Get specific workflow version
+      security:
+      - bearerAuth: []
+      parameters:
+      - $ref: '#/components/parameters/ResourceID'
+      - name: version
+        in: path
+        required: true
+        schema:
+          type: integer
+      responses:
+        '200':
+          description: Version snapshot
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Workflow'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+  /api/v1/workflows/{id}/start:
+    post:
+      tags:
+      - Workflows
+      summary: Start workflow instance
+      security:
+      - bearerAuth: []
+      parameters:
+      - $ref: '#/components/parameters/ResourceID'
+      responses:
+        '201':
+          description: Instance started
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Workflow'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '200':
+          description: Success
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MessageResponse'
+  /api/v1/channels/{id}/workflow/status:
+    get:
+      tags:
+      - Workflows
+      summary: Get workflow status for channel
+      security:
+      - bearerAuth: []
+      parameters:
+      - $ref: '#/components/parameters/ResourceID'
+      responses:
+        '200':
+          description: Workflow instance status
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  data:
+                    type: array
+                    items:
+                      $ref: '#/components/schemas/Workflow'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+  /api/v1/channels/{id}/workflow/advance:
+    post:
+      tags:
+      - Workflows
+      summary: Advance workflow to next stage
+      security:
+      - bearerAuth: []
+      parameters:
+      - $ref: '#/components/parameters/ResourceID'
+      responses:
+        '200':
+          description: Advanced
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Workflow'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '201':
+          description: Success
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MessageResponse'
+  /api/v1/channels/{id}/workflow/reject:
+    post:
+      tags:
+      - Workflows
+      summary: Reject and return to previous stage
+      security:
+      - bearerAuth: []
+      parameters:
+      - $ref: '#/components/parameters/ResourceID'
+      responses:
+        '200':
+          description: Rejected
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Workflow'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '201':
+          description: Success
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MessageResponse'
+  /api/v1/workflow-assignments/mine:
+    get:
+      tags:
+      - Workflows
+      summary: List assignments for current user
+      security:
+      - bearerAuth: []
+      responses:
+        '200':
+          description: Assignment list
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  data:
+                    type: array
+                    items:
+                      $ref: '#/components/schemas/Workflow'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+  /api/v1/workflow-assignments/{id}:
+    get:
+      tags:
+      - Workflows
+      summary: Get assignment details
+      security:
+      - bearerAuth: []
+      parameters:
+      - $ref: '#/components/parameters/ResourceID'
+      responses:
+        '200':
+          description: Assignment details
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Workflow'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+  /api/v1/workflow-assignments/{id}/claim:
+    post:
+      tags:
+      - Workflows
+      summary: Claim an assignment
+      security:
+      - bearerAuth: []
+      parameters:
+      - $ref: '#/components/parameters/ResourceID'
+      responses:
+        '200':
+          description: Claimed
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Workflow'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '201':
+          description: Success
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MessageResponse'
+  /api/v1/workflow-assignments/{id}/complete:
+    post:
+      tags:
+      - Workflows
+      summary: Complete an assignment
+      security:
+      - bearerAuth: []
+      parameters:
+      - $ref: '#/components/parameters/ResourceID'
+      responses:
+        '200':
+          description: Completed
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Workflow'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '201':
+          description: Success
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MessageResponse'
+  /api/v1/workflow-assignments/{id}/comment:
+    post:
+      tags:
+      - Workflows
+      summary: Add comment to assignment
+      security:
+      - bearerAuth: []
+      parameters:
+      - $ref: '#/components/parameters/ResourceID'
+      responses:
+        '201':
+          description: Comment added
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Workflow'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '200':
+          description: Success
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MessageResponse'
+  /api/v1/w/{id}/form:
+    get:
+      tags:
+      - Workflows
+      summary: Get form template for workflow stage
+      parameters:
+      - $ref: '#/components/parameters/ResourceID'
+      responses:
+        '200':
+          description: Form template JSON
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  data:
+                    type: array
+                    items:
+                      $ref: '#/components/schemas/Workflow'
+  /api/v1/w/{id}/form-submit:
+    post:
+      tags:
+      - Workflows
+      summary: Submit form data for workflow stage
+      parameters:
+      - $ref: '#/components/parameters/ResourceID'
+      responses:
+        '200':
+          description: Form submitted
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Workflow'
+        '201':
+          description: Success
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MessageResponse'
+  /api/v1/workflow-entry/{scope}/{slug}:
+    post:
+      tags:
+      - Workflows
+      summary: Start workflow as visitor
+      parameters:
+      - name: scope
+        in: path
+        required: true
+        schema:
+          type: string
+      - name: slug
+        in: path
+        required: true
+        schema:
+          type: string
+      responses:
+        '201':
+          description: Workflow instance started
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Workflow'
+        '200':
+          description: Success
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MessageResponse'
+  /api/v1/notifications:
+    get:
+      tags:
+      - Notifications
+      summary: List notifications
+      security:
+      - bearerAuth: []
+      parameters:
+      - name: limit
+        in: query
+        schema:
+          type: integer
+          default: 20
+          maximum: 100
+      - name: offset
+        in: query
+        schema:
+          type: integer
+          default: 0
+      - name: unread_only
+        in: query
+        schema:
+          type: boolean
+          default: false
+      responses:
+        '200':
+          description: Notification list
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  data:
+                    type: array
+                    items:
+                      $ref: '#/components/schemas/Notification'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+  /api/v1/notifications/unread-count:
+    get:
+      tags:
+      - Notifications
+      summary: Get unread notification count
+      security:
+      - bearerAuth: []
+      responses:
+        '200':
+          description: Unread count
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  count:
+                    type: integer
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+  /api/v1/notifications/{id}/read:
+    patch:
+      tags:
+      - Notifications
+      summary: Mark notification as read
+      security:
+      - bearerAuth: []
+      parameters:
+      - $ref: '#/components/parameters/ResourceID'
+      responses:
+        '200':
+          description: Marked read
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Notification'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+  /api/v1/notifications/mark-all-read:
+    post:
+      tags:
+      - Notifications
+      summary: Mark all notifications as read
+      security:
+      - bearerAuth: []
+      responses:
+        '200':
+          description: All marked read
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Notification'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '201':
+          description: Success
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MessageResponse'
+  /api/v1/notifications/{id}:
+    delete:
+      tags:
+      - Notifications
+      summary: Delete notification
+      security:
+      - bearerAuth: []
+      parameters:
+      - $ref: '#/components/parameters/ResourceID'
+      responses:
+        '200':
+          description: Deleted
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MessageResponse'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+  /api/v1/notifications/preferences:
+    get:
+      tags:
+      - Notifications
+      summary: List notification preferences
+      security:
+      - bearerAuth: []
+      responses:
+        '200':
+          description: Preference list
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  data:
+                    type: array
+                    items:
+                      $ref: '#/components/schemas/Notification'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+  /api/v1/notifications/preferences/{type}:
+    put:
+      tags:
+      - Notifications
+      summary: Set notification preference for type
+      security:
+      - bearerAuth: []
+      parameters:
+      - name: type
+        in: path
+        required: true
+        schema:
+          type: string
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                in_app:
+                  type: boolean
+                email:
+                  type: boolean
+      responses:
+        '200':
+          description: Preference set
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Notification'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+    delete:
+      tags:
+      - Notifications
+      summary: Reset notification preference to default
+      security:
+      - bearerAuth: []
+      parameters:
+      - name: type
+        in: path
+        required: true
+        schema:
+          type: string
+      responses:
+        '200':
+          description: Reset to default
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MessageResponse'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+  /api/v1/extensions:
+    get:
+      tags:
+      - Extensions
+      summary: List user-visible extensions
+      security:
+      - bearerAuth: []
+      responses:
+        '200':
+          description: Extension list
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  data:
+                    type: array
+                    items:
+                      $ref: '#/components/schemas/Extension'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+  /api/v1/extensions/{id}/settings:
+    post:
+      tags:
+      - Extensions
+      summary: Update user extension settings
+      security:
+      - bearerAuth: []
+      parameters:
+      - $ref: '#/components/parameters/ResourceID'
+      responses:
+        '200':
+          description: Settings updated
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Extension'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '201':
+          description: Success
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MessageResponse'
+  /api/v1/extensions/{id}/manifest:
+    get:
+      tags:
+      - Extensions
+      summary: Get extension manifest
+      security:
+      - bearerAuth: []
+      parameters:
+      - $ref: '#/components/parameters/ResourceID'
+      responses:
+        '200':
+          description: Manifest JSON
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  data:
+                    type: array
+                    items:
+                      $ref: '#/components/schemas/Extension'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+  /api/v1/extensions/tools:
+    get:
+      tags:
+      - Extensions
+      summary: List browser tool schemas from extensions
+      security:
+      - bearerAuth: []
+      responses:
+        '200':
+          description: Tool schema list
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  data:
+                    type: array
+                    items:
+                      $ref: '#/components/schemas/Extension'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+  /api/v1/surfaces:
+    get:
+      tags:
+      - Surfaces
+      summary: List enabled surface packages
+      security:
+      - bearerAuth: []
+      responses:
+        '200':
+          description: Surface list
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  data:
+                    type: array
+                    items:
+                      $ref: '#/components/schemas/Surface'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+  /api/v1/packages:
+    get:
+      tags:
+      - Extensions
+      summary: List packages visible to user
+      security:
+      - bearerAuth: []
+      responses:
+        '200':
+          description: Package list
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  data:
+                    type: array
+                    items:
+                      $ref: '#/components/schemas/Extension'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+  /api/v1/packages/install:
+    post:
+      tags:
+      - Extensions
+      summary: Install personal package
+      security:
+      - bearerAuth: []
+      responses:
+        '201':
+          description: Package installed
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Extension'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '200':
+          description: Success
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MessageResponse'
+  /api/v1/packages/{id}:
+    delete:
+      tags:
+      - Extensions
+      summary: Delete personal package
+      security:
+      - bearerAuth: []
+      parameters:
+      - $ref: '#/components/parameters/ResourceID'
+      responses:
+        '200':
+          description: Deleted
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MessageResponse'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+  /api/v1/admin/users:
+    get:
+      tags:
+      - Admin
+      summary: List all users
+      security:
+      - bearerAuth: []
+      responses:
+        '200':
+          description: User list
+          content:
+            application/json:
+              schema: &id005
+                type: object
+                properties:
+                  data:
+                    type: array
+                    items:
+                      $ref: '#/components/schemas/AuthUser'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+    post:
+      tags:
+      - Admin
+      summary: Create user
+      security:
+      - bearerAuth: []
+      responses:
+        '201':
+          description: User created
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MessageResponse'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '200':
+          description: Success
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MessageResponse'
+  /api/v1/admin/users/{id}/role:
+    put:
+      tags:
+      - Admin
+      summary: Update user role
+      security:
+      - bearerAuth: []
+      parameters:
+      - $ref: '#/components/parameters/ResourceID'
+      responses:
+        '200':
+          description: Role updated
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MessageResponse'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+  /api/v1/admin/users/{id}/active:
+    put:
+      tags:
+      - Admin
+      summary: Toggle user active status
+      security:
+      - bearerAuth: []
+      parameters:
+      - $ref: '#/components/parameters/ResourceID'
+      responses:
+        '200':
+          description: Status toggled
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MessageResponse'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+  /api/v1/admin/users/{id}/reset-password:
+    post:
+      tags:
+      - Admin
+      summary: Reset user password
+      security:
+      - bearerAuth: []
+      parameters:
+      - $ref: '#/components/parameters/ResourceID'
+      responses:
+        '200':
+          description: Password reset
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MessageResponse'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '201':
+          description: Success
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MessageResponse'
+  /api/v1/admin/users/{id}/vault/reset:
+    post:
+      tags:
+      - Admin
+      summary: Reset user vault (BYOK keys lost)
+      security:
+      - bearerAuth: []
+      parameters:
+      - $ref: '#/components/parameters/ResourceID'
+      responses:
+        '200':
+          description: Vault reset
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MessageResponse'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '201':
+          description: Success
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MessageResponse'
+  /api/v1/admin/users/{id}:
+    delete:
+      tags:
+      - Admin
+      summary: Delete user
+      security:
+      - bearerAuth: []
+      parameters:
+      - $ref: '#/components/parameters/ResourceID'
+      responses:
+        '200':
+          description: User deleted
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MessageResponse'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+  /api/v1/admin/users/{id}/permissions:
+    get:
+      tags:
+      - Admin
+      summary: Get effective permissions for user
+      security:
+      - bearerAuth: []
+      parameters:
+      - $ref: '#/components/parameters/ResourceID'
+      responses:
+        '200':
+          description: Permission list
+          content:
+            application/json:
+              schema: &id003
+                type: object
+                properties:
+                  data:
+                    type: array
+                    items:
+                      type: object
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+  /api/v1/admin/settings:
+    get:
+      tags:
+      - Admin
+      summary: List all global settings
+      security:
+      - bearerAuth: []
+      responses:
+        '200':
+          description: Settings list
+          content:
+            application/json:
+              schema: &id001
+                type: object
+                properties:
+                  data:
+                    type: array
+                    items:
+                      type: object
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+  /api/v1/admin/settings/{key}:
+    get:
+      tags:
+      - Admin
+      summary: Get global setting by key
+      security:
+      - bearerAuth: []
+      parameters:
+      - name: key
+        in: path
+        required: true
+        schema:
+          type: string
+      responses:
+        '200':
+          description: Setting value
+          content:
+            application/json:
+              schema: *id001
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+    put:
+      tags:
+      - Admin
+      summary: Update global setting
+      security:
+      - bearerAuth: []
+      parameters:
+      - name: key
+        in: path
+        required: true
+        schema:
+          type: string
+      responses:
+        '200':
+          description: Setting updated
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MessageResponse'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+  /api/v1/admin/configs:
+    get:
+      tags:
+      - Admin
+      - Providers
+      summary: List global provider configs
+      security:
+      - bearerAuth: []
+      responses:
+        '200':
+          description: Provider config list
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  data:
+                    type: array
+                    items:
+                      $ref: '#/components/schemas/ProviderConfig'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+    post:
+      tags:
+      - Admin
+      - Providers
+      summary: Create global provider config
+      security:
+      - bearerAuth: []
+      responses:
+        '201':
+          description: Config created
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ProviderConfig'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '200':
+          description: Success
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MessageResponse'
+  /api/v1/admin/configs/{id}:
+    put:
+      tags:
+      - Admin
+      - Providers
+      summary: Update global provider config
+      security:
+      - bearerAuth: []
+      parameters:
+      - $ref: '#/components/parameters/ResourceID'
+      responses:
+        '200':
+          description: Updated
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ProviderConfig'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+    delete:
+      tags:
+      - Admin
+      - Providers
+      summary: Delete global provider config
+      security:
+      - bearerAuth: []
+      parameters:
+      - $ref: '#/components/parameters/ResourceID'
+      responses:
+        '200':
+          description: Deleted
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MessageResponse'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+  /api/v1/admin/models:
+    get:
+      tags:
+      - Admin
+      - Models
+      summary: List model catalog
+      security:
+      - bearerAuth: []
+      responses:
+        '200':
+          description: Model catalog
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  data:
+                    type: array
+                    items:
+                      type: object
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+  /api/v1/admin/models/fetch:
+    post:
+      tags:
+      - Admin
+      - Models
+      summary: Sync models from provider APIs
+      security:
+      - bearerAuth: []
+      responses:
+        '200':
+          description: Models synced
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MessageResponse'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '201':
+          description: Success
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MessageResponse'
+  /api/v1/admin/models/bulk:
+    put:
+      tags:
+      - Admin
+      - Models
+      summary: Bulk update model visibility
+      security:
+      - bearerAuth: []
+      responses:
+        '200':
+          description: Bulk updated
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MessageResponse'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+  /api/v1/admin/models/{id}:
+    put:
+      tags:
+      - Admin
+      - Models
+      summary: Update model config
+      security:
+      - bearerAuth: []
+      parameters:
+      - $ref: '#/components/parameters/ResourceID'
+      responses:
+        '200':
+          description: Updated
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MessageResponse'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+    delete:
+      tags:
+      - Admin
+      - Models
+      summary: Delete model from catalog
+      security:
+      - bearerAuth: []
+      parameters:
+      - $ref: '#/components/parameters/ResourceID'
+      responses:
+        '200':
+          description: Deleted
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MessageResponse'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+  /api/v1/admin/models/{id}/capabilities:
+    get:
+      tags:
+      - Admin
+      - Models
+      summary: Get model capability overrides
+      security:
+      - bearerAuth: []
+      parameters:
+      - $ref: '#/components/parameters/ResourceID'
+      responses:
+        '200':
+          description: Capabilities
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  data:
+                    type: array
+                    items:
+                      type: object
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+    put:
+      tags:
+      - Admin
+      - Models
+      summary: Set model capability override
+      security:
+      - bearerAuth: []
+      parameters:
+      - $ref: '#/components/parameters/ResourceID'
+      responses:
+        '200':
+          description: Override set
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MessageResponse'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+  /api/v1/admin/models/{id}/capabilities/{overrideId}:
+    delete:
+      tags:
+      - Admin
+      - Models
+      summary: Delete capability override
+      security:
+      - bearerAuth: []
+      parameters:
+      - $ref: '#/components/parameters/ResourceID'
+      - name: overrideId
+        in: path
+        required: true
+        schema:
+          type: string
+          format: uuid
+      responses:
+        '200':
+          description: Deleted
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MessageResponse'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+  /api/v1/admin/capability-overrides:
+    get:
+      tags:
+      - Admin
+      - Models
+      summary: List all capability overrides
+      security:
+      - bearerAuth: []
+      responses:
+        '200':
+          description: All overrides
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  data:
+                    type: array
+                    items:
+                      type: object
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+  /api/v1/admin/provider-types:
+    get:
+      tags:
+      - Admin
+      - Providers
+      summary: List supported provider types
+      security:
+      - bearerAuth: []
+      responses:
+        '200':
+          description: Provider type registry
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  data:
+                    type: array
+                    items:
+                      $ref: '#/components/schemas/ProviderConfig'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+  /api/v1/admin/personas:
+    get:
+      tags:
+      - Admin
+      - Personas
+      summary: List global personas
+      security:
+      - bearerAuth: []
+      responses:
+        '200':
+          description: Global persona list
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  data:
+                    type: array
+                    items:
+                      $ref: '#/components/schemas/Persona'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+    post:
+      tags:
+      - Admin
+      - Personas
+      summary: Create global persona
+      security:
+      - bearerAuth: []
+      responses:
+        '201':
+          description: Persona created
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Persona'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '200':
+          description: Success
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MessageResponse'
+  /api/v1/admin/personas/{id}:
+    put:
+      tags:
+      - Admin
+      - Personas
+      summary: Update global persona
+      security:
+      - bearerAuth: []
+      parameters:
+      - $ref: '#/components/parameters/ResourceID'
+      responses:
+        '200':
+          description: Updated
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Persona'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+    delete:
+      tags:
+      - Admin
+      - Personas
+      summary: Delete global persona
+      security:
+      - bearerAuth: []
+      parameters:
+      - $ref: '#/components/parameters/ResourceID'
+      responses:
+        '200':
+          description: Deleted
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MessageResponse'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+  /api/v1/admin/personas/{id}/avatar:
+    post:
+      tags:
+      - Admin
+      - Personas
+      summary: Upload global persona avatar
+      security:
+      - bearerAuth: []
+      parameters:
+      - $ref: '#/components/parameters/ResourceID'
+      responses:
+        '200':
+          description: Avatar uploaded
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Persona'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '201':
+          description: Success
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MessageResponse'
+    delete:
+      tags:
+      - Admin
+      - Personas
+      summary: Delete global persona avatar
+      security:
+      - bearerAuth: []
+      parameters:
+      - $ref: '#/components/parameters/ResourceID'
+      responses:
+        '200':
+          description: Avatar removed
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MessageResponse'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+  /api/v1/admin/personas/{id}/knowledge-bases:
+    get:
+      tags:
+      - Admin
+      - Personas
+      summary: Get global persona KB bindings
+      security:
+      - bearerAuth: []
+      parameters:
+      - $ref: '#/components/parameters/ResourceID'
+      responses:
+        '200':
+          description: KB bindings
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  data:
+                    type: array
+                    items:
+                      $ref: '#/components/schemas/Persona'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+    put:
+      tags:
+      - Admin
+      - Personas
+      summary: Set global persona KB bindings
+      security:
+      - bearerAuth: []
+      parameters:
+      - $ref: '#/components/parameters/ResourceID'
+      responses:
+        '200':
+          description: Bindings updated
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Persona'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+  /api/v1/admin/personas/{id}/tool-grants:
+    get:
+      tags:
+      - Admin
+      - Personas
+      summary: Get global persona tool grants
+      security:
+      - bearerAuth: []
+      parameters:
+      - $ref: '#/components/parameters/ResourceID'
+      responses:
+        '200':
+          description: Tool grants
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  data:
+                    type: array
+                    items:
+                      $ref: '#/components/schemas/Persona'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+    put:
+      tags:
+      - Admin
+      - Personas
+      summary: Set global persona tool grants
+      security:
+      - bearerAuth: []
+      parameters:
+      - $ref: '#/components/parameters/ResourceID'
+      responses:
+        '200':
+          description: Grants updated
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Persona'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+  /api/v1/admin/memories/pending:
+    get:
+      tags:
+      - Admin
+      - Memory
+      summary: List pending memories for review
+      security:
+      - bearerAuth: []
+      responses:
+        '200':
+          description: Pending memories
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  data:
+                    type: array
+                    items:
+                      $ref: '#/components/schemas/Memory'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+  /api/v1/admin/memories/bulk-approve:
+    post:
+      tags:
+      - Admin
+      - Memory
+      summary: Bulk approve pending memories
+      security:
+      - bearerAuth: []
+      responses:
+        '200':
+          description: Memories approved
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Memory'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '201':
+          description: Success
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MessageResponse'
+  /api/v1/admin/teams:
+    get:
+      tags:
+      - Admin
+      - Teams
+      summary: List all teams
+      security:
+      - bearerAuth: []
+      responses:
+        '200':
+          description: Team list
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  data:
+                    type: array
+                    items:
+                      $ref: '#/components/schemas/Team'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+    post:
+      tags:
+      - Admin
+      - Teams
+      summary: Create team
+      security:
+      - bearerAuth: []
+      responses:
+        '201':
+          description: Team created
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Team'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '200':
+          description: Success
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MessageResponse'
+  /api/v1/admin/teams/{id}:
+    get:
+      tags:
+      - Admin
+      - Teams
+      summary: Get team
+      security:
+      - bearerAuth: []
+      parameters:
+      - $ref: '#/components/parameters/ResourceID'
+      responses:
+        '200':
+          description: Team object
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Team'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+    put:
+      tags:
+      - Admin
+      - Teams
+      summary: Update team
+      security:
+      - bearerAuth: []
+      parameters:
+      - $ref: '#/components/parameters/ResourceID'
+      responses:
+        '200':
+          description: Updated
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Team'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+    delete:
+      tags:
+      - Admin
+      - Teams
+      summary: Delete team
+      security:
+      - bearerAuth: []
+      parameters:
+      - $ref: '#/components/parameters/ResourceID'
+      responses:
+        '200':
+          description: Deleted
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MessageResponse'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+  /api/v1/admin/teams/{id}/members:
+    get:
+      tags:
+      - Admin
+      - Teams
+      summary: List team members
+      security:
+      - bearerAuth: []
+      parameters:
+      - $ref: '#/components/parameters/ResourceID'
+      responses:
+        '200':
+          description: Member list
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  data:
+                    type: array
+                    items:
+                      $ref: '#/components/schemas/Team'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+    post:
+      tags:
+      - Admin
+      - Teams
+      summary: Add team member
+      security:
+      - bearerAuth: []
+      parameters:
+      - $ref: '#/components/parameters/ResourceID'
+      responses:
+        '201':
+          description: Member added
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Team'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '200':
+          description: Success
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MessageResponse'
+  /api/v1/admin/teams/{id}/members/{memberId}:
+    put:
+      tags:
+      - Admin
+      - Teams
+      summary: Update team member
+      security:
+      - bearerAuth: []
+      parameters:
+      - $ref: '#/components/parameters/ResourceID'
+      - name: memberId
+        in: path
+        required: true
+        schema:
+          type: string
+          format: uuid
+      responses:
+        '200':
+          description: Updated
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Team'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+    delete:
+      tags:
+      - Admin
+      - Teams
+      summary: Remove team member
+      security:
+      - bearerAuth: []
+      parameters:
+      - $ref: '#/components/parameters/ResourceID'
+      - name: memberId
+        in: path
+        required: true
+        schema:
+          type: string
+          format: uuid
+      responses:
+        '200':
+          description: Removed
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MessageResponse'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+  /api/v1/admin/teams/{id}/export:
+    get:
+      tags:
+      - Admin
+      - Teams
+      - Data Portability
+      summary: Export team data
+      security:
+      - bearerAuth: []
+      parameters:
+      - $ref: '#/components/parameters/ResourceID'
+      responses:
+        '200':
+          description: Team data archive
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  data:
+                    type: array
+                    items:
+                      $ref: '#/components/schemas/Team'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+  /api/v1/admin/teams/{id}/import:
+    post:
+      tags:
+      - Admin
+      - Teams
+      - Data Portability
+      summary: Import team data
+      security:
+      - bearerAuth: []
+      parameters:
+      - $ref: '#/components/parameters/ResourceID'
+      responses:
+        '200':
+          description: Team data imported
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Team'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '201':
+          description: Success
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MessageResponse'
+  /api/v1/admin/notifications/broadcast:
+    post:
+      tags:
+      - Admin
+      - Notifications
+      summary: Broadcast notification to all users
+      security:
+      - bearerAuth: []
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required:
+              - title
+              - message
+              properties:
+                title:
+                  type: string
+                message:
+                  type: string
+                level:
+                  type: string
+                  enum:
+                  - info
+                  - warning
+                  - critical
+                  default: info
+      responses:
+        '200':
+          description: Broadcast sent
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Notification'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '201':
+          description: Success
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MessageResponse'
+  /api/v1/admin/notifications/test-email:
+    post:
+      tags:
+      - Admin
+      - Notifications
+      summary: Send test email to admin
+      security:
+      - bearerAuth: []
+      responses:
+        '200':
+          description: Test email sent
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Notification'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '201':
+          description: Success
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MessageResponse'
+  /api/v1/admin/audit:
+    get:
+      tags:
+      - Admin
+      summary: List platform audit log
+      security:
+      - bearerAuth: []
+      responses:
+        '200':
+          description: Audit entries
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  data:
+                    type: array
+                    items:
+                      type: object
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+  /api/v1/admin/audit/actions:
+    get:
+      tags:
+      - Admin
+      summary: List distinct audit actions
+      security:
+      - bearerAuth: []
+      responses:
+        '200':
+          description: Action list
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  data:
+                    type: array
+                    items:
+                      type: string
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+  /api/v1/admin/groups:
+    get:
+      tags:
+      - Admin
+      summary: List permission groups
+      security:
+      - bearerAuth: []
+      responses:
+        '200':
+          description: Group list
+          content:
+            application/json:
+              schema: &id002
+                type: object
+                properties:
+                  data:
+                    type: array
+                    items:
+                      type: object
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+    post:
+      tags:
+      - Admin
+      summary: Create permission group
+      security:
+      - bearerAuth: []
+      responses:
+        '201':
+          description: Group created
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MessageResponse'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '200':
+          description: Success
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MessageResponse'
+  /api/v1/admin/groups/{id}:
+    get:
+      tags:
+      - Admin
+      summary: Get permission group
+      security:
+      - bearerAuth: []
+      parameters:
+      - $ref: '#/components/parameters/ResourceID'
+      responses:
+        '200':
+          description: Group object
+          content:
+            application/json:
+              schema: *id002
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+    put:
+      tags:
+      - Admin
+      summary: Update permission group
+      security:
+      - bearerAuth: []
+      parameters:
+      - $ref: '#/components/parameters/ResourceID'
+      responses:
+        '200':
+          description: Updated
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MessageResponse'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+    delete:
+      tags:
+      - Admin
+      summary: Delete permission group
+      security:
+      - bearerAuth: []
+      parameters:
+      - $ref: '#/components/parameters/ResourceID'
+      responses:
+        '200':
+          description: Deleted
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MessageResponse'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+  /api/v1/admin/groups/{id}/members:
+    get:
+      tags:
+      - Admin
+      summary: List group members
+      security:
+      - bearerAuth: []
+      parameters:
+      - $ref: '#/components/parameters/ResourceID'
+      responses:
+        '200':
+          description: Member list
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  data:
+                    type: array
+                    items:
+                      type: object
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+    post:
+      tags:
+      - Admin
+      summary: Add user to group
+      security:
+      - bearerAuth: []
+      parameters:
+      - $ref: '#/components/parameters/ResourceID'
+      responses:
+        '201':
+          description: Member added
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MessageResponse'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '200':
+          description: Success
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MessageResponse'
+  /api/v1/admin/groups/{id}/members/{userId}:
+    delete:
+      tags:
+      - Admin
+      summary: Remove user from group
+      security:
+      - bearerAuth: []
+      parameters:
+      - $ref: '#/components/parameters/ResourceID'
+      - name: userId
+        in: path
+        required: true
+        schema:
+          type: string
+          format: uuid
+      responses:
+        '200':
+          description: Removed
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MessageResponse'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+  /api/v1/admin/permissions:
+    get:
+      tags:
+      - Admin
+      summary: List all available permissions
+      security:
+      - bearerAuth: []
+      responses:
+        '200':
+          description: Permission list
+          content:
+            application/json:
+              schema: *id003
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+  /api/v1/admin/grants/{type}/{id}:
+    get:
+      tags:
+      - Admin
+      summary: Get resource grant
+      security:
+      - bearerAuth: []
+      parameters:
+      - name: type
+        in: path
+        required: true
+        schema:
+          type: string
+      - $ref: '#/components/parameters/ResourceID'
+      responses:
+        '200':
+          description: Grant object
+          content:
+            application/json:
+              schema:
+                type: object
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+    put:
+      tags:
+      - Admin
+      summary: Set resource grant
+      security:
+      - bearerAuth: []
+      parameters:
+      - name: type
+        in: path
+        required: true
+        schema:
+          type: string
+      - $ref: '#/components/parameters/ResourceID'
+      responses:
+        '200':
+          description: Grant set
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MessageResponse'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+    delete:
+      tags:
+      - Admin
+      summary: Delete resource grant
+      security:
+      - bearerAuth: []
+      parameters:
+      - name: type
+        in: path
+        required: true
+        schema:
+          type: string
+      - $ref: '#/components/parameters/ResourceID'
+      responses:
+        '200':
+          description: Deleted
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MessageResponse'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+  /api/v1/admin/roles:
+    get:
+      tags:
+      - Admin
+      summary: List roles
+      security:
+      - bearerAuth: []
+      responses:
+        '200':
+          description: Role list
+          content:
+            application/json:
+              schema: &id004
+                type: object
+                properties:
+                  data:
+                    type: array
+                    items:
+                      type: object
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+  /api/v1/admin/roles/{role}:
+    get:
+      tags:
+      - Admin
+      summary: Get role definition
+      security:
+      - bearerAuth: []
+      parameters:
+      - name: role
+        in: path
+        required: true
+        schema:
+          type: string
+      responses:
+        '200':
+          description: Role object
+          content:
+            application/json:
+              schema: *id004
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+    put:
+      tags:
+      - Admin
+      summary: Update role permissions
+      security:
+      - bearerAuth: []
+      parameters:
+      - name: role
+        in: path
+        required: true
+        schema:
+          type: string
+      responses:
+        '200':
+          description: Updated
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MessageResponse'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+  /api/v1/admin/roles/{role}/test:
+    post:
+      tags:
+      - Admin
+      summary: Test role permission check
+      security:
+      - bearerAuth: []
+      parameters:
+      - name: role
+        in: path
+        required: true
+        schema:
+          type: string
+      responses:
+        '200':
+          description: Test result
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MessageResponse'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '201':
+          description: Success
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MessageResponse'
+  /api/v1/admin/usage/users/{id}:
+    get:
+      tags:
+      - Admin
+      - Usage
+      summary: Usage for specific user
+      security:
+      - bearerAuth: []
+      parameters:
+      - $ref: '#/components/parameters/ResourceID'
+      responses:
+        '200':
+          description: User usage
+          content:
+            application/json:
+              schema: *id005
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+  /api/v1/admin/usage/teams/{id}:
+    get:
+      tags:
+      - Admin
+      - Usage
+      summary: Usage for specific team
+      security:
+      - bearerAuth: []
+      parameters:
+      - $ref: '#/components/parameters/ResourceID'
+      responses:
+        '200':
+          description: Team usage
+          content:
+            application/json:
+              schema:
+                type: object
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+  /api/v1/admin/pricing:
+    get:
+      tags:
+      - Admin
+      - Usage
+      summary: List pricing overrides
+      security:
+      - bearerAuth: []
+      responses:
+        '200':
+          description: Pricing list
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  data:
+                    type: array
+                    items:
+                      type: object
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+    put:
+      tags:
+      - Admin
+      - Usage
+      summary: Upsert pricing override
+      security:
+      - bearerAuth: []
+      responses:
+        '200':
+          description: Pricing set
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MessageResponse'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+  /api/v1/admin/pricing/{provider}/{model}:
+    delete:
+      tags:
+      - Admin
+      - Usage
+      summary: Delete pricing override
+      security:
+      - bearerAuth: []
+      parameters:
+      - name: provider
+        in: path
+        required: true
+        schema:
+          type: string
+      - name: model
+        in: path
+        required: true
+        schema:
+          type: string
+      responses:
+        '200':
+          description: Deleted
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MessageResponse'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+  /api/v1/admin/storage/status:
+    get:
+      tags:
+      - Admin
+      summary: Storage backend status
+      security:
+      - bearerAuth: []
+      responses:
+        '200':
+          description: Storage status
+          content:
+            application/json:
+              schema:
+                type: object
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+  /api/v1/admin/storage/orphans:
+    get:
+      tags:
+      - Admin
+      summary: Count orphaned storage objects
+      security:
+      - bearerAuth: []
+      responses:
+        '200':
+          description: Orphan count
+          content:
+            application/json:
+              schema:
+                type: object
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+  /api/v1/admin/storage/cleanup:
+    post:
+      tags:
+      - Admin
+      summary: Clean up orphaned storage objects
+      security:
+      - bearerAuth: []
+      responses:
+        '200':
+          description: Cleanup results
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MessageResponse'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '201':
+          description: Success
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MessageResponse'
+  /api/v1/admin/storage/extraction:
+    get:
+      tags:
+      - Admin
+      summary: Text extraction pipeline status
+      security:
+      - bearerAuth: []
+      responses:
+        '200':
+          description: Extraction status
+          content:
+            application/json:
+              schema:
+                type: object
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+  /api/v1/admin/vault/status:
+    get:
+      tags:
+      - Admin
+      summary: Vault encryption status
+      security:
+      - bearerAuth: []
+      responses:
+        '200':
+          description: Vault status
+          content:
+            application/json:
+              schema:
+                type: object
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+  /api/v1/admin/channels/archived:
+    get:
+      tags:
+      - Admin
+      summary: List archived channels
+      security:
+      - bearerAuth: []
+      responses:
+        '200':
+          description: Archived channel list
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  data:
+                    type: array
+                    items:
+                      $ref: '#/components/schemas/Channel'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+  /api/v1/admin/channels/{id}/purge:
+    delete:
+      tags:
+      - Admin
+      summary: Permanently purge archived channel
+      security:
+      - bearerAuth: []
+      parameters:
+      - $ref: '#/components/parameters/ResourceID'
+      responses:
+        '200':
+          description: Purged
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MessageResponse'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+  /api/v1/admin/extensions:
+    get:
+      tags:
+      - Admin
+      - Extensions
+      summary: List all extensions
+      security:
+      - bearerAuth: []
+      responses:
+        '200':
+          description: Extension list
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  data:
+                    type: array
+                    items:
+                      $ref: '#/components/schemas/Extension'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+    post:
+      tags:
+      - Admin
+      - Extensions
+      summary: Install extension
+      security:
+      - bearerAuth: []
+      responses:
+        '201':
+          description: Installed
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Extension'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '200':
+          description: Success
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MessageResponse'
+  /api/v1/admin/extensions/{id}:
+    put:
+      tags:
+      - Admin
+      - Extensions
+      summary: Update extension
+      security:
+      - bearerAuth: []
+      parameters:
+      - $ref: '#/components/parameters/ResourceID'
+      responses:
+        '200':
+          description: Updated
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Extension'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+    delete:
+      tags:
+      - Admin
+      - Extensions
+      summary: Uninstall extension
+      security:
+      - bearerAuth: []
+      parameters:
+      - $ref: '#/components/parameters/ResourceID'
+      responses:
+        '200':
+          description: Uninstalled
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MessageResponse'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+  /api/v1/admin/extensions/{id}/permissions:
+    get:
+      tags:
+      - Admin
+      - Extensions
+      summary: List extension permissions
+      security:
+      - bearerAuth: []
+      parameters:
+      - $ref: '#/components/parameters/ResourceID'
+      responses:
+        '200':
+          description: Permission list
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  data:
+                    type: array
+                    items:
+                      $ref: '#/components/schemas/Extension'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+  /api/v1/admin/extensions/{id}/review:
+    get:
+      tags:
+      - Admin
+      - Extensions
+      summary: Review package permissions
+      security:
+      - bearerAuth: []
+      parameters:
+      - $ref: '#/components/parameters/ResourceID'
+      responses:
+        '200':
+          description: Review summary
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  data:
+                    type: array
+                    items:
+                      $ref: '#/components/schemas/Extension'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+  /api/v1/admin/extensions/{id}/permissions/{perm}/grant:
+    post:
+      tags:
+      - Admin
+      - Extensions
+      summary: Grant extension permission
+      security:
+      - bearerAuth: []
+      parameters:
+      - $ref: '#/components/parameters/ResourceID'
+      - name: perm
+        in: path
+        required: true
+        schema:
+          type: string
+      responses:
+        '200':
+          description: Granted
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Extension'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '201':
+          description: Success
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MessageResponse'
+  /api/v1/admin/extensions/{id}/permissions/{perm}/revoke:
+    post:
+      tags:
+      - Admin
+      - Extensions
+      summary: Revoke extension permission
+      security:
+      - bearerAuth: []
+      parameters:
+      - $ref: '#/components/parameters/ResourceID'
+      - name: perm
+        in: path
+        required: true
+        schema:
+          type: string
+      responses:
+        '200':
+          description: Revoked
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Extension'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '201':
+          description: Success
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MessageResponse'
+  /api/v1/admin/extensions/{id}/permissions/grant-all:
+    post:
+      tags:
+      - Admin
+      - Extensions
+      summary: Grant all requested permissions
+      security:
+      - bearerAuth: []
+      parameters:
+      - $ref: '#/components/parameters/ResourceID'
+      responses:
+        '200':
+          description: All granted
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Extension'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '201':
+          description: Success
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MessageResponse'
+  /api/v1/admin/extensions/{id}/secrets:
+    get:
+      tags:
+      - Admin
+      - Extensions
+      summary: Get extension secrets (redacted)
+      security:
+      - bearerAuth: []
+      parameters:
+      - $ref: '#/components/parameters/ResourceID'
+      responses:
+        '200':
+          description: Secret keys (values redacted)
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  data:
+                    type: array
+                    items:
+                      $ref: '#/components/schemas/Extension'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+    put:
+      tags:
+      - Admin
+      - Extensions
+      summary: Set extension secrets
+      security:
+      - bearerAuth: []
+      parameters:
+      - $ref: '#/components/parameters/ResourceID'
+      responses:
+        '200':
+          description: Secrets set
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Extension'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+    delete:
+      tags:
+      - Admin
+      - Extensions
+      summary: Delete extension secrets
+      security:
+      - bearerAuth: []
+      parameters:
+      - $ref: '#/components/parameters/ResourceID'
+      responses:
+        '200':
+          description: Secrets deleted
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MessageResponse'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+  /api/v1/admin/routing/policies:
+    get:
+      tags:
+      - Admin
+      - Providers
+      summary: List routing policies
+      security:
+      - bearerAuth: []
+      responses:
+        '200':
+          description: Policy list
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  data:
+                    type: array
+                    items:
+                      $ref: '#/components/schemas/ProviderConfig'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+    post:
+      tags:
+      - Admin
+      - Providers
+      summary: Create routing policy
+      security:
+      - bearerAuth: []
+      responses:
+        '201':
+          description: Policy created
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ProviderConfig'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '200':
+          description: Success
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MessageResponse'
+  /api/v1/admin/routing/policies/{id}:
+    get:
+      tags:
+      - Admin
+      - Providers
+      summary: Get routing policy
+      security:
+      - bearerAuth: []
+      parameters:
+      - $ref: '#/components/parameters/ResourceID'
+      responses:
+        '200':
+          description: Policy object
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ProviderConfig'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+    put:
+      tags:
+      - Admin
+      - Providers
+      summary: Update routing policy
+      security:
+      - bearerAuth: []
+      parameters:
+      - $ref: '#/components/parameters/ResourceID'
+      responses:
+        '200':
+          description: Updated
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ProviderConfig'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+    delete:
+      tags:
+      - Admin
+      - Providers
+      summary: Delete routing policy
+      security:
+      - bearerAuth: []
+      parameters:
+      - $ref: '#/components/parameters/ResourceID'
+      responses:
+        '200':
+          description: Deleted
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MessageResponse'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+  /api/v1/admin/routing/test:
+    post:
+      tags:
+      - Admin
+      - Providers
+      summary: Dry-run routing evaluation
+      security:
+      - bearerAuth: []
+      responses:
+        '200':
+          description: Routing candidates
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ProviderConfig'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '201':
+          description: Success
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MessageResponse'
+  /api/v1/admin/packages/registry:
+    get:
+      tags:
+      - Admin
+      - Extensions
+      summary: Browse package registry
+      security:
+      - bearerAuth: []
+      responses:
+        '200':
+          description: Registry entries
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  data:
+                    type: array
+                    items:
+                      $ref: '#/components/schemas/Extension'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+  /api/v1/admin/packages/registry/install:
+    post:
+      tags:
+      - Admin
+      - Extensions
+      summary: Install from registry
+      security:
+      - bearerAuth: []
+      responses:
+        '201':
+          description: Installed
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Extension'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '200':
+          description: Success
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MessageResponse'
+  /api/v1/admin/packages:
+    get:
+      tags:
+      - Admin
+      - Extensions
+      summary: List installed packages
+      security:
+      - bearerAuth: []
+      responses:
+        '200':
+          description: Package list
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  data:
+                    type: array
+                    items:
+                      $ref: '#/components/schemas/Extension'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+  /api/v1/admin/packages/{id}:
+    get:
+      tags:
+      - Admin
+      - Extensions
+      summary: Get package details
+      security:
+      - bearerAuth: []
+      parameters:
+      - $ref: '#/components/parameters/ResourceID'
+      responses:
+        '200':
+          description: Package object
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Extension'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+    delete:
+      tags:
+      - Admin
+      - Extensions
+      summary: Delete package
+      security:
+      - bearerAuth: []
+      parameters:
+      - $ref: '#/components/parameters/ResourceID'
+      responses:
+        '200':
+          description: Deleted
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MessageResponse'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+  /api/v1/admin/packages/install:
+    post:
+      tags:
+      - Admin
+      - Extensions
+      summary: Install package from upload
+      security:
+      - bearerAuth: []
+      responses:
+        '201':
+          description: Installed
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Extension'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '200':
+          description: Success
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MessageResponse'
+  /api/v1/admin/packages/{id}/enable:
+    put:
+      tags:
+      - Admin
+      - Extensions
+      summary: Enable package
+      security:
+      - bearerAuth: []
+      parameters:
+      - $ref: '#/components/parameters/ResourceID'
+      responses:
+        '200':
+          description: Enabled
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Extension'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+  /api/v1/admin/packages/{id}/disable:
+    put:
+      tags:
+      - Admin
+      - Extensions
+      summary: Disable package
+      security:
+      - bearerAuth: []
+      parameters:
+      - $ref: '#/components/parameters/ResourceID'
+      responses:
+        '200':
+          description: Disabled
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Extension'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+  /api/v1/admin/packages/{id}/settings:
+    get:
+      tags:
+      - Admin
+      - Extensions
+      summary: Get package settings
+      security:
+      - bearerAuth: []
+      parameters:
+      - $ref: '#/components/parameters/ResourceID'
+      responses:
+        '200':
+          description: Package settings
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  data:
+                    type: array
+                    items:
+                      $ref: '#/components/schemas/Extension'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+    put:
+      tags:
+      - Admin
+      - Extensions
+      summary: Update package settings
+      security:
+      - bearerAuth: []
+      parameters:
+      - $ref: '#/components/parameters/ResourceID'
+      responses:
+        '200':
+          description: Settings updated
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Extension'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+  /api/v1/admin/packages/{id}/export:
+    get:
+      tags:
+      - Admin
+      - Extensions
+      summary: Export package as archive
+      security:
+      - bearerAuth: []
+      parameters:
+      - $ref: '#/components/parameters/ResourceID'
+      responses:
+        '200':
+          description: Package archive
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  data:
+                    type: array
+                    items:
+                      $ref: '#/components/schemas/Extension'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+  /api/v1/admin/workflows/{id}/export:
+    get:
+      tags:
+      - Admin
+      - Workflows
+      summary: Export workflow as package
+      security:
+      - bearerAuth: []
+      parameters:
+      - $ref: '#/components/parameters/ResourceID'
+      responses:
+        '200':
+          description: Workflow package archive
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  data:
+                    type: array
+                    items:
+                      $ref: '#/components/schemas/Workflow'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+  /api/v1/admin/workflows/monitor/instances:
+    get:
+      tags:
+      - Admin
+      - Workflows
+      summary: List active workflow instances
+      security:
+      - bearerAuth: []
+      responses:
+        '200':
+          description: Active instance list
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  data:
+                    type: array
+                    items:
+                      $ref: '#/components/schemas/Workflow'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+  /api/v1/admin/workflows/monitor/funnel/{id}:
+    get:
+      tags:
+      - Admin
+      - Workflows
+      summary: Get workflow stage funnel
+      security:
+      - bearerAuth: []
+      parameters:
+      - $ref: '#/components/parameters/ResourceID'
+      responses:
+        '200':
+          description: Funnel data
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Workflow'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+  /api/v1/admin/workflows/monitor/stale:
+    get:
+      tags:
+      - Admin
+      - Workflows
+      summary: List stale workflow instances
+      security:
+      - bearerAuth: []
+      responses:
+        '200':
+          description: Stale instances
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  data:
+                    type: array
+                    items:
+                      $ref: '#/components/schemas/Workflow'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+  /api/v1/admin/surfaces:
+    get:
+      tags:
+      - Admin
+      - Surfaces
+      summary: List installed surfaces
+      security:
+      - bearerAuth: []
+      responses:
+        '200':
+          description: Surface list
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  data:
+                    type: array
+                    items:
+                      $ref: '#/components/schemas/Surface'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+  /api/v1/admin/surfaces/{id}:
+    delete:
+      tags:
+      - Admin
+      - Surfaces
+      summary: Delete surface
+      security:
+      - bearerAuth: []
+      parameters:
+      - $ref: '#/components/parameters/ResourceID'
+      responses:
+        '200':
+          description: Deleted
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MessageResponse'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+  /api/v1/admin/surfaces/install:
+    post:
+      tags:
+      - Admin
+      - Surfaces
+      summary: Install surface package
+      security:
+      - bearerAuth: []
+      responses:
+        '201':
+          description: Installed
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Surface'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '200':
+          description: Success
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MessageResponse'
+  /api/v1/admin/surfaces/{id}/enable:
+    put:
+      tags:
+      - Admin
+      - Surfaces
+      summary: Enable surface
+      security:
+      - bearerAuth: []
+      parameters:
+      - $ref: '#/components/parameters/ResourceID'
+      responses:
+        '200':
+          description: Enabled
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Surface'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+  /api/v1/admin/surfaces/{id}/disable:
+    put:
+      tags:
+      - Admin
+      - Surfaces
+      summary: Disable surface
+      security:
+      - bearerAuth: []
+      parameters:
+      - $ref: '#/components/parameters/ResourceID'
+      responses:
+        '200':
+          description: Disabled
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Surface'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+  /api/v1/admin/tasks:
+    get:
+      tags:
+      - Admin
+      - Tasks
+      summary: List all tasks
+      security:
+      - bearerAuth: []
+      responses:
+        '200':
+          description: Task list
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  data:
+                    type: array
+                    items:
+                      $ref: '#/components/schemas/Task'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+  /api/v1/admin/tasks/{id}/run:
+    post:
+      tags:
+      - Admin
+      - Tasks
+      summary: Force-run task
+      security:
+      - bearerAuth: []
+      parameters:
+      - $ref: '#/components/parameters/ResourceID'
+      responses:
+        '200':
+          description: Run started
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Task'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '201':
+          description: Success
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MessageResponse'
+  /api/v1/admin/tasks/{id}/kill:
+    post:
+      tags:
+      - Admin
+      - Tasks
+      summary: Kill task run
+      security:
+      - bearerAuth: []
+      parameters:
+      - $ref: '#/components/parameters/ResourceID'
+      responses:
+        '200':
+          description: Killed
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Task'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '201':
+          description: Success
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MessageResponse'
+  /api/v1/admin/tasks/{id}:
+    delete:
+      tags:
+      - Admin
+      - Tasks
+      summary: Delete task
+      security:
+      - bearerAuth: []
+      parameters:
+      - $ref: '#/components/parameters/ResourceID'
+      responses:
+        '200':
+          description: Deleted
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MessageResponse'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+  /api/v1/admin/system-functions:
+    get:
+      tags:
+      - Admin
+      - Tasks
+      summary: List registered system functions
+      security:
+      - bearerAuth: []
+      responses:
+        '200':
+          description: System function registry
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  data:
+                    type: array
+                    items:
+                      $ref: '#/components/schemas/Task'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+  /api/v1/admin/projects:
+    get:
+      tags:
+      - Admin
+      - Projects
+      summary: List all projects (cross-user)
+      security:
+      - bearerAuth: []
+      responses:
+        '200':
+          description: All projects
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  data:
+                    type: array
+                    items:
+                      $ref: '#/components/schemas/Project'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+  /api/v1/admin/projects/{id}:
+    delete:
+      tags:
+      - Admin
+      - Projects
+      summary: Delete project
+      security:
+      - bearerAuth: []
+      parameters:
+      - $ref: '#/components/parameters/ResourceID'
+      responses:
+        '200':
+          description: Deleted
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MessageResponse'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+  /api/v1/teams/mine:
+    get:
+      tags:
+      - Teams
+      summary: List teams the current user belongs to
+      security:
+      - bearerAuth: []
+      responses:
+        '200':
+          description: User's teams
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  data:
+                    type: array
+                    items:
+                      $ref: '#/components/schemas/Team'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+  /api/v1/teams/{teamId}/members:
+    get:
+      tags:
+      - Teams
+      summary: List team members
+      security:
+      - bearerAuth: []
+      parameters:
+      - name: teamId
+        in: path
+        required: true
+        schema:
+          type: string
+          format: uuid
+      responses:
+        '200':
+          description: Member list
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  data:
+                    type: array
+                    items:
+                      $ref: '#/components/schemas/Team'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+    post:
+      tags:
+      - Teams
+      summary: Add team member
+      security:
+      - bearerAuth: []
+      parameters:
+      - name: teamId
+        in: path
+        required: true
+        schema:
+          type: string
+          format: uuid
+      responses:
+        '201':
+          description: Member added
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Team'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '200':
+          description: Success
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MessageResponse'
+  /api/v1/teams/{teamId}/members/{memberId}:
+    put:
+      tags:
+      - Teams
+      summary: Update team member role
+      security:
+      - bearerAuth: []
+      parameters:
+      - name: teamId
+        in: path
+        required: true
+        schema:
+          type: string
+          format: uuid
+      - name: memberId
+        in: path
+        required: true
+        schema:
+          type: string
+          format: uuid
+      responses:
+        '200':
+          description: Updated
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Team'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+    delete:
+      tags:
+      - Teams
+      summary: Remove team member
+      security:
+      - bearerAuth: []
+      parameters:
+      - name: teamId
+        in: path
+        required: true
+        schema:
+          type: string
+          format: uuid
+      - name: memberId
+        in: path
+        required: true
+        schema:
+          type: string
+          format: uuid
+      responses:
+        '200':
+          description: Removed
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MessageResponse'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+  /api/v1/teams/{teamId}/models:
+    get:
+      tags:
+      - Teams
+      - Models
+      summary: List models available to team
+      security:
+      - bearerAuth: []
+      parameters:
+      - name: teamId
+        in: path
+        required: true
+        schema:
+          type: string
+          format: uuid
+      responses:
+        '200':
+          description: Team model list
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  data:
+                    type: array
+                    items:
+                      $ref: '#/components/schemas/Team'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+  /api/v1/teams/{teamId}/providers:
+    get:
+      tags:
+      - Teams
+      - Providers
+      summary: List team provider configs
+      security:
+      - bearerAuth: []
+      parameters:
+      - name: teamId
+        in: path
+        required: true
+        schema:
+          type: string
+          format: uuid
+      responses:
+        '200':
+          description: Team provider list
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  data:
+                    type: array
+                    items:
+                      $ref: '#/components/schemas/Team'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+    post:
+      tags:
+      - Teams
+      - Providers
+      summary: Create team provider config
+      security:
+      - bearerAuth: []
+      parameters:
+      - name: teamId
+        in: path
+        required: true
+        schema:
+          type: string
+          format: uuid
+      responses:
+        '201':
+          description: Config created
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Team'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '200':
+          description: Success
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MessageResponse'
+  /api/v1/teams/{teamId}/providers/{id}:
+    put:
+      tags:
+      - Teams
+      - Providers
+      summary: Update team provider config
+      security:
+      - bearerAuth: []
+      parameters:
+      - name: teamId
+        in: path
+        required: true
+        schema:
+          type: string
+          format: uuid
+      - $ref: '#/components/parameters/ResourceID'
+      responses:
+        '200':
+          description: Updated
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Team'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+    delete:
+      tags:
+      - Teams
+      - Providers
+      summary: Delete team provider config
+      security:
+      - bearerAuth: []
+      parameters:
+      - name: teamId
+        in: path
+        required: true
+        schema:
+          type: string
+          format: uuid
+      - $ref: '#/components/parameters/ResourceID'
+      responses:
+        '200':
+          description: Deleted
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MessageResponse'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+  /api/v1/teams/{teamId}/providers/{id}/models:
+    get:
+      tags:
+      - Teams
+      - Providers
+      summary: List models for team provider
+      security:
+      - bearerAuth: []
+      parameters:
+      - name: teamId
+        in: path
+        required: true
+        schema:
+          type: string
+          format: uuid
+      - $ref: '#/components/parameters/ResourceID'
+      responses:
+        '200':
+          description: Model list
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  data:
+                    type: array
+                    items:
+                      $ref: '#/components/schemas/Team'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+  /api/v1/teams/{teamId}/personas:
+    get:
+      tags:
+      - Teams
+      - Personas
+      summary: List team personas
+      security:
+      - bearerAuth: []
+      parameters:
+      - name: teamId
+        in: path
+        required: true
+        schema:
+          type: string
+          format: uuid
+      responses:
+        '200':
+          description: Team persona list
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  data:
+                    type: array
+                    items:
+                      $ref: '#/components/schemas/Team'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+    post:
+      tags:
+      - Teams
+      - Personas
+      summary: Create team persona
+      security:
+      - bearerAuth: []
+      parameters:
+      - name: teamId
+        in: path
+        required: true
+        schema:
+          type: string
+          format: uuid
+      responses:
+        '201':
+          description: Persona created
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Team'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '200':
+          description: Success
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MessageResponse'
+  /api/v1/teams/{teamId}/personas/{id}:
+    put:
+      tags:
+      - Teams
+      - Personas
+      summary: Update team persona
+      security:
+      - bearerAuth: []
+      parameters:
+      - name: teamId
+        in: path
+        required: true
+        schema:
+          type: string
+          format: uuid
+      - $ref: '#/components/parameters/ResourceID'
+      responses:
+        '200':
+          description: Updated
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Team'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+    delete:
+      tags:
+      - Teams
+      - Personas
+      summary: Delete team persona
+      security:
+      - bearerAuth: []
+      parameters:
+      - name: teamId
+        in: path
+        required: true
+        schema:
+          type: string
+          format: uuid
+      - $ref: '#/components/parameters/ResourceID'
+      responses:
+        '200':
+          description: Deleted
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MessageResponse'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+  /api/v1/teams/{teamId}/personas/{id}/avatar:
+    post:
+      tags:
+      - Teams
+      - Personas
+      summary: Upload team persona avatar
+      security:
+      - bearerAuth: []
+      parameters:
+      - name: teamId
+        in: path
+        required: true
+        schema:
+          type: string
+          format: uuid
+      - $ref: '#/components/parameters/ResourceID'
+      responses:
+        '200':
+          description: Avatar uploaded
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Team'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '201':
+          description: Success
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MessageResponse'
+    delete:
+      tags:
+      - Teams
+      - Personas
+      summary: Delete team persona avatar
+      security:
+      - bearerAuth: []
+      parameters:
+      - name: teamId
+        in: path
+        required: true
+        schema:
+          type: string
+          format: uuid
+      - $ref: '#/components/parameters/ResourceID'
+      responses:
+        '200':
+          description: Avatar removed
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MessageResponse'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+  /api/v1/teams/{teamId}/personas/{id}/knowledge-bases:
+    get:
+      tags:
+      - Teams
+      - Personas
+      summary: Get team persona KB bindings
+      security:
+      - bearerAuth: []
+      parameters:
+      - name: teamId
+        in: path
+        required: true
+        schema:
+          type: string
+          format: uuid
+      - $ref: '#/components/parameters/ResourceID'
+      responses:
+        '200':
+          description: KB bindings
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  data:
+                    type: array
+                    items:
+                      $ref: '#/components/schemas/Team'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+    put:
+      tags:
+      - Teams
+      - Personas
+      summary: Set team persona KB bindings
+      security:
+      - bearerAuth: []
+      parameters:
+      - name: teamId
+        in: path
+        required: true
+        schema:
+          type: string
+          format: uuid
+      - $ref: '#/components/parameters/ResourceID'
+      responses:
+        '200':
+          description: Bindings updated
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Team'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+  /api/v1/teams/{teamId}/personas/{id}/tool-grants:
+    get:
+      tags:
+      - Teams
+      - Personas
+      summary: Get team persona tool grants
+      security:
+      - bearerAuth: []
+      parameters:
+      - name: teamId
+        in: path
+        required: true
+        schema:
+          type: string
+          format: uuid
+      - $ref: '#/components/parameters/ResourceID'
+      responses:
+        '200':
+          description: Tool grants
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  data:
+                    type: array
+                    items:
+                      $ref: '#/components/schemas/Team'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+    put:
+      tags:
+      - Teams
+      - Personas
+      summary: Set team persona tool grants
+      security:
+      - bearerAuth: []
+      parameters:
+      - name: teamId
+        in: path
+        required: true
+        schema:
+          type: string
+          format: uuid
+      - $ref: '#/components/parameters/ResourceID'
+      responses:
+        '200':
+          description: Grants updated
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Team'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+  /api/v1/teams/{teamId}/roles:
+    get:
+      tags:
+      - Teams
+      summary: List team roles
+      security:
+      - bearerAuth: []
+      parameters:
+      - name: teamId
+        in: path
+        required: true
+        schema:
+          type: string
+          format: uuid
+      responses:
+        '200':
+          description: Team role list
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  data:
+                    type: array
+                    items:
+                      $ref: '#/components/schemas/Team'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+  /api/v1/teams/{teamId}/roles/{role}:
+    put:
+      tags:
+      - Teams
+      summary: Update team role
+      security:
+      - bearerAuth: []
+      parameters:
+      - name: teamId
+        in: path
+        required: true
+        schema:
+          type: string
+          format: uuid
+      - name: role
+        in: path
+        required: true
+        schema:
+          type: string
+      responses:
+        '200':
+          description: Updated
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Team'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+    delete:
+      tags:
+      - Teams
+      summary: Delete team role
+      security:
+      - bearerAuth: []
+      parameters:
+      - name: teamId
+        in: path
+        required: true
+        schema:
+          type: string
+          format: uuid
+      - name: role
+        in: path
+        required: true
+        schema:
+          type: string
+      responses:
+        '200':
+          description: Deleted
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MessageResponse'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+  /api/v1/teams/{teamId}/audit:
+    get:
+      tags:
+      - Teams
+      summary: Team audit log
+      security:
+      - bearerAuth: []
+      parameters:
+      - name: teamId
+        in: path
+        required: true
+        schema:
+          type: string
+          format: uuid
+      responses:
+        '200':
+          description: Audit entries
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  data:
+                    type: array
+                    items:
+                      $ref: '#/components/schemas/Team'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+  /api/v1/teams/{teamId}/audit/actions:
+    get:
+      tags:
+      - Teams
+      summary: List distinct team audit actions
+      security:
+      - bearerAuth: []
+      parameters:
+      - name: teamId
+        in: path
+        required: true
+        schema:
+          type: string
+          format: uuid
+      responses:
+        '200':
+          description: Action list
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  data:
+                    type: array
+                    items:
+                      $ref: '#/components/schemas/Team'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+  /api/v1/teams/{teamId}/usage:
+    get:
+      tags:
+      - Teams
+      - Usage
+      summary: Team usage stats
+      security:
+      - bearerAuth: []
+      parameters:
+      - name: teamId
+        in: path
+        required: true
+        schema:
+          type: string
+          format: uuid
+      responses:
+        '200':
+          description: Team usage
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  data:
+                    type: array
+                    items:
+                      $ref: '#/components/schemas/Team'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+  /api/v1/teams/{teamId}/groups:
+    get:
+      tags:
+      - Teams
+      summary: List groups for team
+      security:
+      - bearerAuth: []
+      parameters:
+      - name: teamId
+        in: path
+        required: true
+        schema:
+          type: string
+          format: uuid
+      responses:
+        '200':
+          description: Team groups
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  data:
+                    type: array
+                    items:
+                      $ref: '#/components/schemas/Team'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+  /api/v1/teams/{teamId}/packages/install:
+    post:
+      tags:
+      - Teams
+      - Extensions
+      summary: Install package for team
+      security:
+      - bearerAuth: []
+      parameters:
+      - name: teamId
+        in: path
+        required: true
+        schema:
+          type: string
+          format: uuid
+      responses:
+        '201':
+          description: Package installed
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Team'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '200':
+          description: Success
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MessageResponse'
+  /api/v1/teams/{teamId}/packages/{id}:
+    delete:
+      tags:
+      - Teams
+      - Extensions
+      summary: Delete team package
+      security:
+      - bearerAuth: []
+      parameters:
+      - name: teamId
+        in: path
+        required: true
+        schema:
+          type: string
+          format: uuid
+      - $ref: '#/components/parameters/ResourceID'
+      responses:
+        '200':
+          description: Deleted
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MessageResponse'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+  /api/v1/teams/{teamId}/assignments:
+    get:
+      tags:
+      - Teams
+      - Workflows
+      summary: List workflow assignments for team
+      security:
+      - bearerAuth: []
+      parameters:
+      - name: teamId
+        in: path
+        required: true
+        schema:
+          type: string
+          format: uuid
+      responses:
+        '200':
+          description: Team assignments
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  data:
+                    type: array
+                    items:
+                      $ref: '#/components/schemas/Team'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+  /api/v1/teams/{teamId}/workflows:
+    get:
+      tags:
+      - Teams
+      - Workflows
+      summary: List team workflows
+      security:
+      - bearerAuth: []
+      parameters:
+      - name: teamId
+        in: path
+        required: true
+        schema:
+          type: string
+          format: uuid
+      responses:
+        '200':
+          description: Team workflow list
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  data:
+                    type: array
+                    items:
+                      $ref: '#/components/schemas/Team'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+    post:
+      tags:
+      - Teams
+      - Workflows
+      summary: Create team workflow
+      security:
+      - bearerAuth: []
+      parameters:
+      - name: teamId
+        in: path
+        required: true
+        schema:
+          type: string
+          format: uuid
+      responses:
+        '201':
+          description: Workflow created
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Team'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '200':
+          description: Success
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MessageResponse'
+  /api/v1/teams/{teamId}/workflows/{id}:
+    get:
+      tags:
+      - Teams
+      - Workflows
+      summary: Get team workflow
+      security:
+      - bearerAuth: []
+      parameters:
+      - name: teamId
+        in: path
+        required: true
+        schema:
+          type: string
+          format: uuid
+      - $ref: '#/components/parameters/ResourceID'
+      responses:
+        '200':
+          description: Workflow object
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Team'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+    patch:
+      tags:
+      - Teams
+      - Workflows
+      summary: Update team workflow
+      security:
+      - bearerAuth: []
+      parameters:
+      - name: teamId
+        in: path
+        required: true
+        schema:
+          type: string
+          format: uuid
+      - $ref: '#/components/parameters/ResourceID'
+      responses:
+        '200':
+          description: Updated
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Team'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+    delete:
+      tags:
+      - Teams
+      - Workflows
+      summary: Delete team workflow
+      security:
+      - bearerAuth: []
+      parameters:
+      - name: teamId
+        in: path
+        required: true
+        schema:
+          type: string
+          format: uuid
+      - $ref: '#/components/parameters/ResourceID'
+      responses:
+        '200':
+          description: Deleted
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MessageResponse'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+  /api/v1/teams/{teamId}/workflows/{id}/stages:
+    get:
+      tags:
+      - Teams
+      - Workflows
+      summary: List team workflow stages
+      security:
+      - bearerAuth: []
+      parameters:
+      - name: teamId
+        in: path
+        required: true
+        schema:
+          type: string
+          format: uuid
+      - $ref: '#/components/parameters/ResourceID'
+      responses:
+        '200':
+          description: Stage list
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  data:
+                    type: array
+                    items:
+                      $ref: '#/components/schemas/Team'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+    post:
+      tags:
+      - Teams
+      - Workflows
+      summary: Create team workflow stage
+      security:
+      - bearerAuth: []
+      parameters:
+      - name: teamId
+        in: path
+        required: true
+        schema:
+          type: string
+          format: uuid
+      - $ref: '#/components/parameters/ResourceID'
+      responses:
+        '201':
+          description: Stage created
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Team'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '200':
+          description: Success
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MessageResponse'
+  /api/v1/teams/{teamId}/workflows/{id}/stages/{sid}:
+    put:
+      tags:
+      - Teams
+      - Workflows
+      summary: Update team workflow stage
+      security:
+      - bearerAuth: []
+      parameters:
+      - name: teamId
+        in: path
+        required: true
+        schema:
+          type: string
+          format: uuid
+      - $ref: '#/components/parameters/ResourceID'
+      - name: sid
+        in: path
+        required: true
+        schema:
+          type: string
+          format: uuid
+      responses:
+        '200':
+          description: Updated
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Team'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+    delete:
+      tags:
+      - Teams
+      - Workflows
+      summary: Delete team workflow stage
+      security:
+      - bearerAuth: []
+      parameters:
+      - name: teamId
+        in: path
+        required: true
+        schema:
+          type: string
+          format: uuid
+      - $ref: '#/components/parameters/ResourceID'
+      - name: sid
+        in: path
+        required: true
+        schema:
+          type: string
+          format: uuid
+      responses:
+        '200':
+          description: Deleted
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MessageResponse'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+  /api/v1/teams/{teamId}/workflows/{id}/stages/reorder:
+    patch:
+      tags:
+      - Teams
+      - Workflows
+      summary: Reorder team workflow stages
+      security:
+      - bearerAuth: []
+      parameters:
+      - name: teamId
+        in: path
+        required: true
+        schema:
+          type: string
+          format: uuid
+      - $ref: '#/components/parameters/ResourceID'
+      responses:
+        '200':
+          description: Reordered
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Team'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+  /api/v1/teams/{teamId}/workflows/{id}/publish:
+    post:
+      tags:
+      - Teams
+      - Workflows
+      summary: Publish team workflow version
+      security:
+      - bearerAuth: []
+      parameters:
+      - name: teamId
+        in: path
+        required: true
+        schema:
+          type: string
+          format: uuid
+      - $ref: '#/components/parameters/ResourceID'
+      responses:
+        '200':
+          description: Published
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Team'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '201':
+          description: Success
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MessageResponse'
+  /api/v1/teams/{teamId}/workflows/{id}/versions/{version}:
+    get:
+      tags:
+      - Teams
+      - Workflows
+      summary: Get team workflow version
+      security:
+      - bearerAuth: []
+      parameters:
+      - name: teamId
+        in: path
+        required: true
+        schema:
+          type: string
+          format: uuid
+      - $ref: '#/components/parameters/ResourceID'
+      - name: version
+        in: path
+        required: true
+        schema:
+          type: integer
+      responses:
+        '200':
+          description: Version snapshot
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Team'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+  /api/v1/teams/{teamId}/workflows/monitor/instances:
+    get:
+      tags:
+      - Teams
+      - Workflows
+      summary: List team active workflow instances
+      security:
+      - bearerAuth: []
+      parameters:
+      - name: teamId
+        in: path
+        required: true
+        schema:
+          type: string
+          format: uuid
+      responses:
+        '200':
+          description: Active instances
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  data:
+                    type: array
+                    items:
+                      $ref: '#/components/schemas/Team'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+  /api/v1/teams/{teamId}/tasks:
+    get:
+      tags:
+      - Teams
+      - Tasks
+      summary: List team tasks (member view)
+      security:
+      - bearerAuth: []
+      parameters:
+      - name: teamId
+        in: path
+        required: true
+        schema:
+          type: string
+          format: uuid
+      responses:
+        '200':
+          description: Team task list
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  data:
+                    type: array
+                    items:
+                      $ref: '#/components/schemas/Team'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+    post:
+      tags:
+      - Teams
+      - Tasks
+      summary: Create team task
+      security:
+      - bearerAuth: []
+      parameters:
+      - name: teamId
+        in: path
+        required: true
+        schema:
+          type: string
+          format: uuid
+      responses:
+        '201':
+          description: Task created
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Team'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '200':
+          description: Success
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MessageResponse'
+  /api/v1/teams/{teamId}/tasks/{id}:
+    put:
+      tags:
+      - Teams
+      - Tasks
+      summary: Update team task
+      security:
+      - bearerAuth: []
+      parameters:
+      - name: teamId
+        in: path
+        required: true
+        schema:
+          type: string
+          format: uuid
+      - $ref: '#/components/parameters/ResourceID'
+      responses:
+        '200':
+          description: Updated
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Team'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+    delete:
+      tags:
+      - Teams
+      - Tasks
+      summary: Delete team task
+      security:
+      - bearerAuth: []
+      parameters:
+      - name: teamId
+        in: path
+        required: true
+        schema:
+          type: string
+          format: uuid
+      - $ref: '#/components/parameters/ResourceID'
+      responses:
+        '200':
+          description: Deleted
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MessageResponse'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+  /api/v1/teams/{teamId}/tasks/{id}/run:
+    post:
+      tags:
+      - Teams
+      - Tasks
+      summary: Run team task
+      security:
+      - bearerAuth: []
+      parameters:
+      - name: teamId
+        in: path
+        required: true
+        schema:
+          type: string
+          format: uuid
+      - $ref: '#/components/parameters/ResourceID'
+      responses:
+        '200':
+          description: Run started
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Team'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '201':
+          description: Success
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MessageResponse'
+  /api/v1/teams/{teamId}/tasks/{id}/kill:
+    post:
+      tags:
+      - Teams
+      - Tasks
+      summary: Kill team task run
+      security:
+      - bearerAuth: []
+      parameters:
+      - name: teamId
+        in: path
+        required: true
+        schema:
+          type: string
+          format: uuid
+      - $ref: '#/components/parameters/ResourceID'
+      responses:
+        '200':
+          description: Killed
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Team'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '201':
+          description: Success
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MessageResponse'
+  /api/v1/teams/{teamId}/tasks/{id}/runs:
+    get:
+      tags:
+      - Teams
+      - Tasks
+      summary: List team task runs
+      security:
+      - bearerAuth: []
+      parameters:
+      - name: teamId
+        in: path
+        required: true
+        schema:
+          type: string
+          format: uuid
+      - $ref: '#/components/parameters/ResourceID'
+      responses:
+        '200':
+          description: Run history
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  data:
+                    type: array
+                    items:
+                      $ref: '#/components/schemas/Team'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+  /api/v1/groups/mine:
+    get:
+      tags:
+      - Teams
+      summary: List permission groups the user belongs to
+      security:
+      - bearerAuth: []
+      responses:
+        '200':
+          description: User's groups
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  data:
+                    type: array
+                    items:
+                      $ref: '#/components/schemas/Team'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+  /api/v1/usage:
+    get:
+      tags:
+      - Usage
+      summary: Personal usage stats
+      security:
+      - bearerAuth: []
+      responses:
+        '200':
+          description: Personal usage
+          content:
+            application/json:
+              schema:
+                type: object
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+  /api/v1/export/me:
+    get:
+      tags:
+      - Data Portability
+      summary: Export all user data (GDPR)
+      security:
+      - bearerAuth: []
+      responses:
+        '200':
+          description: User data archive
+          content:
+            application/json:
+              schema:
+                type: string
+                format: binary
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+  /api/v1/import/me:
+    post:
+      tags:
+      - Data Portability
+      summary: Import user data
+      security:
+      - bearerAuth: []
+      responses:
+        '200':
+          description: Data imported
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MessageResponse'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '201':
+          description: Success
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MessageResponse'
+  /api/v1/import/chatgpt:
+    post:
+      tags:
+      - Data Portability
+      summary: Import ChatGPT conversation export
+      security:
+      - bearerAuth: []
+      responses:
+        '200':
+          description: Conversations imported
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MessageResponse'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '201':
+          description: Success
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MessageResponse'
+  /api/v1/me:
+    delete:
+      tags:
+      - Data Portability
+      summary: Delete account and all data (GDPR)
+      security:
+      - bearerAuth: []
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              required:
+              - password
+              properties:
+                password:
+                  type: string
+                  description: Confirmation password
+      responses:
+        '200':
+          description: Account deleted
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MessageResponse'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+  /api/v1/hooks/t/{token}:
+    post:
+      tags:
+      - Workflows
+      summary: Webhook trigger endpoint
+      parameters:
+      - name: token
+        in: path
+        required: true
+        schema:
+          type: string
+      responses:
+        '200':
+          description: Trigger processed
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Workflow'
+        '201':
+          description: Success
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MessageResponse'
   /api/v1/admin/stats:
     get:
-      tags: [Admin]
+      tags:
+      - Admin
       summary: Platform statistics
       security:
-        - bearerAuth: []
+      - bearerAuth: []
       responses:
-        "200":
+        '200':
           description: Aggregate counts
           content:
             application/json:
@@ -447,82 +10707,98 @@ paths:
                     type: integer
                   messages:
                     type: integer
-
-  # ── Admin: Provider Health ─────────────────
+        '401':
+          $ref: '#/components/responses/Unauthorized'
   /api/v1/admin/providers/health:
     get:
-      tags: [Admin]
+      tags:
+      - Admin
       summary: Current health status for all providers
       security:
-        - bearerAuth: []
+      - bearerAuth: []
       responses:
-        "200":
+        '200':
           description: Provider health summaries
           content:
             application/json:
               schema:
                 type: object
                 properties:
-                  providers:
+                  data:
                     type: array
                     items:
-                      $ref: "#/components/schemas/ProviderHealth"
-
-  # ── Admin: Usage ───────────────────────────
+                      $ref: '#/components/schemas/ProviderHealth'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
   /api/v1/admin/usage:
     get:
-      tags: [Admin, Usage]
+      tags:
+      - Admin
+      - Usage
       summary: Aggregated token usage
       security:
-        - bearerAuth: []
+      - bearerAuth: []
       parameters:
-        - name: since
-          in: query
-          schema:
-            type: string
-            format: date-time
-        - name: until
-          in: query
-          schema:
-            type: string
-            format: date-time
-        - name: period
-          in: query
-          schema:
-            type: string
-            enum: [7d, 30d, 90d]
-        - name: group_by
-          in: query
-          schema:
-            type: string
-            enum: [model, user, provider, day]
+      - name: since
+        in: query
+        schema:
+          type: string
+          format: date-time
+      - name: until
+        in: query
+        schema:
+          type: string
+          format: date-time
+      - name: period
+        in: query
+        schema:
+          type: string
+          enum:
+          - 7d
+          - 30d
+          - 90d
+      - name: group_by
+        in: query
+        schema:
+          type: string
+          enum:
+          - model
+          - user
+          - provider
+          - day
       responses:
-        "200":
+        '200':
           description: Usage data
-
-  # ── Admin: Dashboard ───────────────────────
+          content:
+            application/json:
+              schema:
+                type: object
+        '401':
+          $ref: '#/components/responses/Unauthorized'
   /api/v1/admin/dashboard:
     get:
-      tags: [Admin]
+      tags:
+      - Admin
       summary: Real-time observability dashboard data
-      description: |
-        Aggregates provider health, 24h usage, DB pool stats, WebSocket count,
-        recent errors, and uptime into a single response. Designed for the
-        built-in admin dashboard (v0.33.0).
+      description: 'Aggregates provider health, 24h usage, DB pool stats, WebSocket count,
+
+        recent errors, and uptime into a single response.
+
+        '
       security:
-        - bearerAuth: []
+      - bearerAuth: []
       responses:
-        "200":
+        '200':
           description: Dashboard snapshot
           content:
             application/json:
               schema:
                 type: object
                 properties:
-                  providers:
+                  provider_health:
                     type: array
                     items:
-                      $ref: "#/components/schemas/ProviderHealth"
+                      $ref: '#/components/schemas/ProviderHealth'
                   usage_24h:
                     type: object
                   db_pool:
@@ -536,65 +10812,213 @@ paths:
                         type: integer
                   ws_connections:
                     type: integer
-                  uptime_seconds:
-                    type: number
-
+                  recent_errors:
+                    type: array
+                    items:
+                      type: object
+                  runtime:
+                    type: object
+                    properties:
+                      goroutines:
+                        type: integer
+                      heap_mb:
+                        type: integer
+                      sys_mb:
+                        type: integer
+                      num_gc:
+                        type: integer
+                      go_version:
+                        type: string
+                  uptime:
+                    type: string
+                    description: Go duration string (e.g. "4h32m10s")
+        '401':
+          $ref: '#/components/responses/Unauthorized'
 components:
   securitySchemes:
     bearerAuth:
       type: http
       scheme: bearer
       bearerFormat: JWT
+      description: 'JWT access token obtained via `POST /api/v1/auth/login` (builtin),
 
+        OIDC callback, or mTLS auto-provisioning. 15-minute TTL, refreshable
+
+        via `POST /api/v1/auth/refresh`.
+
+        '
+    mtlsAuth:
+      type: mutualTLS
+      description: 'Mutual TLS via reverse proxy headers. The proxy terminates TLS and
+
+        forwards certificate DN fields. Configured via `AUTH_MODE=mtls`.
+
+        No explicit login — user identity extracted from certificate on
+
+        every request. Auto-provisions on first connection.
+
+        '
   parameters:
-    ChannelID:
+    ResourceID:
       name: id
       in: path
       required: true
+      description: Resource UUID
       schema:
         type: string
         format: uuid
-
+    Page:
+      name: page
+      in: query
+      description: Page number (1-indexed)
+      schema:
+        type: integer
+        default: 1
+        minimum: 1
+    PerPage:
+      name: per_page
+      in: query
+      description: Items per page
+      schema:
+        type: integer
+        default: 50
+        minimum: 1
+        maximum: 200
   responses:
     BadRequest:
       description: Invalid request
       content:
         application/json:
           schema:
-            type: object
-            properties:
-              error:
-                type: string
+            $ref: '#/components/schemas/ErrorResponse'
+    Unauthorized:
+      description: Missing or invalid authentication
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/ErrorResponse'
+    Forbidden:
+      description: Insufficient permissions
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/ErrorResponse'
     NotFound:
       description: Resource not found
       content:
         application/json:
           schema:
-            type: object
-            properties:
-              error:
-                type: string
-
+            $ref: '#/components/schemas/ErrorResponse'
+    Conflict:
+      description: Resource conflict (duplicate, version mismatch)
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/ErrorResponse'
+    RateLimited:
+      description: Rate limited
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/ErrorResponse'
   schemas:
+    ErrorResponse:
+      type: object
+      required:
+      - error
+      properties:
+        error:
+          type: string
+          description: Human-readable error message
+      example:
+        error: resource not found
+    MessageResponse:
+      type: object
+      properties:
+        message:
+          type: string
+      example:
+        message: operation completed
     AuthResponse:
       type: object
       properties:
-        token:
+        access_token:
           type: string
+          description: JWT access token (15m TTL)
         refresh_token:
           type: string
+          description: Opaque refresh token (7d TTL, rotation on use)
+        token_type:
+          type: string
+          example: Bearer
+        expires_in:
+          type: integer
+          description: Access token TTL in seconds
+          example: 900
         user:
+          $ref: '#/components/schemas/AuthUser'
+    AuthUser:
+      type: object
+      properties:
+        id:
+          type: string
+          format: uuid
+        username:
+          type: string
+        email:
+          type: string
+          format: email
+        display_name:
+          type: string
+          nullable: true
+        role:
+          type: string
+          enum:
+          - admin
+          - user
+        handle:
+          type: string
+          description: Unique @mention handle
+        auth_source:
+          type: string
+          enum:
+          - builtin
+          - oidc
+          - mtls
+    UserProfile:
+      type: object
+      properties:
+        id:
+          type: string
+          format: uuid
+        username:
+          type: string
+        email:
+          type: string
+          format: email
+        display_name:
+          type: string
+          nullable: true
+        role:
+          type: string
+          enum:
+          - admin
+          - user
+        avatar:
+          type: string
+          nullable: true
+          description: Data URI (PNG, 128x128). Null if unset.
+        settings:
           type: object
-          properties:
-            id:
-              type: string
-              format: uuid
-            username:
-              type: string
-            role:
-              type: string
-              enum: [admin, user]
-
+          additionalProperties: true
+          description: User preferences (theme, keybindings, etc.)
+        created_at:
+          type: string
+          format: date-time
+        last_login_at:
+          type: string
+          format: date-time
+          nullable: true
     Channel:
       type: object
       properties:
@@ -605,32 +11029,138 @@ components:
           type: string
         type:
           type: string
-          enum: [direct, group, workflow]
+          enum:
+          - direct
+          - group
+          - dm
+          - workflow
         user_id:
           type: string
           format: uuid
         team_id:
           type: string
           format: uuid
+          nullable: true
         ai_mode:
           type: string
-          enum: [auto, off, mention_only]
+          enum:
+          - auto
+          - false
+          - mention_only
+        system_prompt:
+          type: string
+          nullable: true
+        model:
+          type: string
+          nullable: true
+        persona_id:
+          type: string
+          format: uuid
+          nullable: true
+        project_id:
+          type: string
+          format: uuid
+          nullable: true
+        settings:
+          type: object
+          additionalProperties: true
+          nullable: true
         created_at:
           type: string
           format: date-time
         updated_at:
           type: string
           format: date-time
-
+    CompletionRequest:
+      type: object
+      required:
+      - content
+      - channel_id
+      properties:
+        channel_id:
+          type: string
+          format: uuid
+        content:
+          type: string
+        model:
+          type: string
+          description: Override the default model
+        persona_id:
+          type: string
+          format: uuid
+        provider_config_id:
+          type: string
+          format: uuid
+        max_tokens:
+          type: integer
+        temperature:
+          type: number
+          minimum: 0
+          maximum: 2
+        top_p:
+          type: number
+          minimum: 0
+          maximum: 1
+        stream:
+          type: boolean
+          default: true
+        file_ids:
+          type: array
+          items:
+            type: string
+            format: uuid
+        disabled_tools:
+          type: array
+          items:
+            type: string
+    CompletionResponse:
+      type: object
+      description: OpenAI-compatible non-streaming response
+      properties:
+        model:
+          type: string
+        choices:
+          type: array
+          items:
+            type: object
+            properties:
+              message:
+                type: object
+                properties:
+                  role:
+                    type: string
+                  content:
+                    type: string
+              finish_reason:
+                type: string
+        usage:
+          $ref: '#/components/schemas/TokenUsage'
+    TokenUsage:
+      type: object
+      properties:
+        prompt_tokens:
+          type: integer
+        completion_tokens:
+          type: integer
+        total_tokens:
+          type: integer
     ProviderHealth:
       type: object
       properties:
         provider_config_id:
           type: string
           format: uuid
+        name:
+          type: string
+        provider_type:
+          type: string
         status:
           type: string
-          enum: [healthy, degraded, down, unknown]
+          enum:
+          - healthy
+          - degraded
+          - down
+          - unknown
         request_count:
           type: integer
         error_count:
@@ -641,3 +11171,705 @@ components:
           type: number
         max_latency_ms:
           type: integer
+    Message:
+      type: object
+      properties:
+        id:
+          type: string
+          format: uuid
+        channel_id:
+          type: string
+          format: uuid
+        parent_id:
+          type: string
+          format: uuid
+          nullable: true
+        role:
+          type: string
+          enum:
+          - user
+          - assistant
+          - system
+          - tool
+        content:
+          type: string
+        model:
+          type: string
+          nullable: true
+        provider_config_id:
+          type: string
+          format: uuid
+          nullable: true
+        participant_id:
+          type: string
+          format: uuid
+          nullable: true
+        participant_type:
+          type: string
+          enum:
+          - user
+          - persona
+          - session
+          nullable: true
+        thinking:
+          type: string
+          nullable: true
+        tool_calls:
+          type: array
+          items:
+            type: object
+          nullable: true
+        tool_results:
+          type: array
+          items:
+            type: object
+          nullable: true
+        attachments:
+          type: array
+          items:
+            type: object
+          nullable: true
+        has_siblings:
+          type: boolean
+        sibling_index:
+          type: integer
+        sibling_count:
+          type: integer
+        created_at:
+          type: string
+          format: date-time
+    Participant:
+      type: object
+      properties:
+        id:
+          type: string
+          format: uuid
+        channel_id:
+          type: string
+          format: uuid
+        participant_type:
+          type: string
+          enum:
+          - user
+          - persona
+          - session
+        participant_id:
+          type: string
+          format: uuid
+        role:
+          type: string
+          enum:
+          - owner
+          - member
+          - observer
+        display_name:
+          type: string
+        avatar_url:
+          type: string
+          nullable: true
+        joined_at:
+          type: string
+          format: date-time
+    FileObject:
+      type: object
+      properties:
+        id:
+          type: string
+          format: uuid
+        channel_id:
+          type: string
+          format: uuid
+          nullable: true
+        message_id:
+          type: string
+          format: uuid
+          nullable: true
+        user_id:
+          type: string
+          format: uuid
+        origin:
+          type: string
+          enum:
+          - user_upload
+          - tool_output
+          - system
+        filename:
+          type: string
+        content_type:
+          type: string
+        size_bytes:
+          type: integer
+        display_hint:
+          type: string
+          enum:
+          - inline
+          - download
+          - thumbnail
+        extracted_text:
+          type: string
+          nullable: true
+        metadata:
+          type: object
+        created_at:
+          type: string
+          format: date-time
+        updated_at:
+          type: string
+          format: date-time
+    ToolDef:
+      type: object
+      properties:
+        name:
+          type: string
+        display_name:
+          type: string
+        description:
+          type: string
+        category:
+          type: string
+        parameters:
+          type: object
+          description: JSON Schema for tool parameters
+    PersonaInput:
+      type: object
+      required:
+      - name
+      - base_model_id
+      properties:
+        name:
+          type: string
+        handle:
+          type: string
+          description: Auto-generated from name if omitted
+        description:
+          type: string
+        icon:
+          type: string
+        base_model_id:
+          type: string
+        provider_config_id:
+          type: string
+          format: uuid
+        system_prompt:
+          type: string
+        temperature:
+          type: number
+        max_tokens:
+          type: integer
+        thinking_budget:
+          type: integer
+          nullable: true
+        is_active:
+          type: boolean
+          default: true
+        memory_enabled:
+          type: boolean
+          default: false
+    ProviderConfigInput:
+      type: object
+      required:
+      - name
+      - provider
+      - api_key
+      properties:
+        name:
+          type: string
+        provider:
+          type: string
+          description: Provider type slug (anthropic, openai, etc.)
+        endpoint:
+          type: string
+          format: uri
+        api_key:
+          type: string
+        model_default:
+          type: string
+        config:
+          type: object
+        headers:
+          type: object
+        settings:
+          type: object
+    Persona:
+      type: object
+      properties:
+        id:
+          type: string
+          format: uuid
+        name:
+          type: string
+        handle:
+          type: string
+        description:
+          type: string
+        icon:
+          type: string
+        avatar:
+          type: string
+          nullable: true
+        base_model_id:
+          type: string
+        provider_config_id:
+          type: string
+          format: uuid
+          nullable: true
+        system_prompt:
+          type: string
+        temperature:
+          type: number
+          nullable: true
+        max_tokens:
+          type: integer
+          nullable: true
+        thinking_budget:
+          type: integer
+          nullable: true
+        scope:
+          type: string
+          enum:
+          - personal
+          - team
+          - global
+        owner_id:
+          type: string
+          format: uuid
+          nullable: true
+        is_active:
+          type: boolean
+        memory_enabled:
+          type: boolean
+        kb_ids:
+          type: array
+          items:
+            type: string
+            format: uuid
+        created_at:
+          type: string
+          format: date-time
+        updated_at:
+          type: string
+          format: date-time
+    Note:
+      type: object
+      properties:
+        id:
+          type: string
+          format: uuid
+        user_id:
+          type: string
+          format: uuid
+        title:
+          type: string
+        content:
+          type: string
+        folder:
+          type: string
+          nullable: true
+        source_message_id:
+          type: string
+          format: uuid
+          nullable: true
+        created_at:
+          type: string
+          format: date-time
+        updated_at:
+          type: string
+          format: date-time
+    KnowledgeBase:
+      type: object
+      properties:
+        id:
+          type: string
+          format: uuid
+        name:
+          type: string
+        description:
+          type: string
+        scope:
+          type: string
+          enum:
+          - personal
+          - team
+          - global
+        owner_id:
+          type: string
+          format: uuid
+          nullable: true
+        team_id:
+          type: string
+          format: uuid
+          nullable: true
+        document_count:
+          type: integer
+        chunk_count:
+          type: integer
+        total_bytes:
+          type: integer
+        status:
+          type: string
+          enum:
+          - active
+          - processing
+          - error
+        created_at:
+          type: string
+          format: date-time
+        updated_at:
+          type: string
+          format: date-time
+    Memory:
+      type: object
+      properties:
+        id:
+          type: string
+          format: uuid
+        scope:
+          type: string
+          enum:
+          - user
+          - persona
+          - persona_user
+        owner_id:
+          type: string
+          format: uuid
+        user_id:
+          type: string
+          format: uuid
+          nullable: true
+        key:
+          type: string
+        value:
+          type: string
+        source_channel_id:
+          type: string
+          format: uuid
+          nullable: true
+        confidence:
+          type: number
+        status:
+          type: string
+          enum:
+          - active
+          - pending_review
+          - archived
+        created_at:
+          type: string
+          format: date-time
+        updated_at:
+          type: string
+          format: date-time
+    Project:
+      type: object
+      properties:
+        id:
+          type: string
+          format: uuid
+        name:
+          type: string
+        description:
+          type: string
+        color:
+          type: string
+          nullable: true
+        icon:
+          type: string
+          nullable: true
+        scope:
+          type: string
+          enum:
+          - personal
+          - team
+          - global
+        owner_id:
+          type: string
+          format: uuid
+        team_id:
+          type: string
+          format: uuid
+          nullable: true
+        workspace_id:
+          type: string
+          format: uuid
+          nullable: true
+        is_archived:
+          type: boolean
+        settings:
+          type: object
+        channel_count:
+          type: integer
+        kb_count:
+          type: integer
+        note_count:
+          type: integer
+        created_at:
+          type: string
+          format: date-time
+        updated_at:
+          type: string
+          format: date-time
+    Workspace:
+      type: object
+      properties:
+        id:
+          type: string
+          format: uuid
+        name:
+          type: string
+        owner_type:
+          type: string
+          enum:
+          - user
+          - project
+          - channel
+          - team
+        owner_id:
+          type: string
+          format: uuid
+        status:
+          type: string
+          enum:
+          - active
+          - archived
+          - deleting
+        max_bytes:
+          type: integer
+          nullable: true
+        indexing_enabled:
+          type: boolean
+        git_remote_url:
+          type: string
+          nullable: true
+        git_branch:
+          type: string
+          nullable: true
+        git_credential_id:
+          type: string
+          format: uuid
+          nullable: true
+        git_last_sync:
+          type: string
+          format: date-time
+          nullable: true
+        file_count:
+          type: integer
+        total_bytes:
+          type: integer
+        created_at:
+          type: string
+          format: date-time
+        updated_at:
+          type: string
+          format: date-time
+    Task:
+      type: object
+      properties:
+        id:
+          type: string
+          format: uuid
+        name:
+          type: string
+        description:
+          type: string
+        task_type:
+          type: string
+          enum:
+          - system
+          - starlark
+        schedule:
+          type: string
+          description: Cron expression
+        trigger_type:
+          type: string
+          enum:
+          - cron
+          - manual
+          - event
+        owner_id:
+          type: string
+          format: uuid
+        team_id:
+          type: string
+          format: uuid
+          nullable: true
+        is_active:
+          type: boolean
+        config:
+          type: object
+        last_run_at:
+          type: string
+          format: date-time
+          nullable: true
+        next_run_at:
+          type: string
+          format: date-time
+          nullable: true
+        created_at:
+          type: string
+          format: date-time
+        updated_at:
+          type: string
+          format: date-time
+    Workflow:
+      type: object
+      properties:
+        id:
+          type: string
+          format: uuid
+        name:
+          type: string
+        slug:
+          type: string
+        description:
+          type: string
+        scope:
+          type: string
+          enum:
+          - personal
+          - team
+          - global
+        owner_id:
+          type: string
+          format: uuid
+        team_id:
+          type: string
+          format: uuid
+          nullable: true
+        persona_id:
+          type: string
+          format: uuid
+          nullable: true
+        published_version:
+          type: integer
+          nullable: true
+        is_active:
+          type: boolean
+        branding:
+          type: object
+          nullable: true
+        created_at:
+          type: string
+          format: date-time
+        updated_at:
+          type: string
+          format: date-time
+    Notification:
+      type: object
+      properties:
+        id:
+          type: string
+          format: uuid
+        user_id:
+          type: string
+          format: uuid
+        type:
+          type: string
+          description: domain.action convention
+        title:
+          type: string
+        body:
+          type: string
+        resource_type:
+          type: string
+          nullable: true
+        resource_id:
+          type: string
+          format: uuid
+          nullable: true
+        is_read:
+          type: boolean
+        created_at:
+          type: string
+          format: date-time
+    ProviderConfig:
+      type: object
+      description: Provider config with API key redacted
+      properties:
+        id:
+          type: string
+          format: uuid
+        name:
+          type: string
+        provider:
+          type: string
+          description: Provider type slug
+        endpoint:
+          type: string
+          format: uri
+        model_default:
+          type: string
+          nullable: true
+        scope:
+          type: string
+          enum:
+          - personal
+          - team
+          - global
+        owner_id:
+          type: string
+          format: uuid
+          nullable: true
+        is_active:
+          type: boolean
+        has_key:
+          type: boolean
+        config:
+          type: object
+        headers:
+          type: object
+        settings:
+          type: object
+        created_at:
+          type: string
+          format: date-time
+    Team:
+      type: object
+      properties:
+        id:
+          type: string
+          format: uuid
+        name:
+          type: string
+        slug:
+          type: string
+        description:
+          type: string
+        settings:
+          type: object
+        member_count:
+          type: integer
+        created_at:
+          type: string
+          format: date-time
+        updated_at:
+          type: string
+          format: date-time
+    Extension:
+      type: object
+      properties:
+        id:
+          type: string
+          format: uuid
+        name:
+          type: string
+        slug:
+          type: string
+        version:
+          type: string
+        description:
+          type: string
+        type:
+          type: string
+          enum:
+          - package
+          - surface
+        is_enabled:
+          type: boolean
+        permissions:
+          type: array
+          items:
+            type: string
+        created_at:
+          type: string
+          format: date-time
+    Surface:
+      $ref: '#/components/schemas/Extension'
\ No newline at end of file
diff --git a/server/static/swagger.html b/server/static/swagger.html
index 84bd70a..7f4d820 100644
--- a/server/static/swagger.html
+++ b/server/static/swagger.html
@@ -256,7 +256,7 @@
   <script src="https://unpkg.com/swagger-ui-dist@5/swagger-ui-bundle.js"></script>
   <script>
     SwaggerUIBundle({
-      url: '/api/docs/openapi.yaml',
+      url: window.location.pathname.replace(/\/$/, '') + '/openapi.yaml',
       dom_id: '#swagger-ui',
       deepLinking: true,
       presets: [SwaggerUIBundle.presets.apis, SwaggerUIBundle.SwaggerUIStandalonePreset],
@@ -264,4 +264,4 @@
     });
   </script>
 </body>
-</html>
+</html>
\ No newline at end of file
diff --git a/server/version.go b/server/version.go
index ffc6f27..cc0b0e3 100644
--- a/server/version.go
+++ b/server/version.go
@@ -1,29 +1,3 @@
 package main
 
-import (
-	"os"
-	"strings"
-)
-
-// Version is set at build time via:
-//
-//	go build -ldflags "-X main.Version=$(cat VERSION)"
-//
-// Falls back to reading /VERSION or ./VERSION for container/local runs
-// without ldflags. Final fallback is "dev".
-var Version = "dev"
-
-func init() {
-	if Version != "dev" {
-		return
-	}
-	// Try well-known paths: container (/VERSION), repo root (../VERSION, ./VERSION)
-	for _, path := range []string{"/VERSION", "VERSION", "../VERSION"} {
-		if data, err := os.ReadFile(path); err == nil {
-			if v := strings.TrimSpace(string(data)); v != "" {
-				Version = v
-				return
-			}
-		}
-	}
-}
+const Version = "0.36.0"