moving

docs/ux-refactor/deltas/backend-api-delta.md

@@ -0,0 +1,383 @@
+# Backend API Delta — Waggle OS UX Refactor (Master List)
+
+> **Purpose.** The single, consolidated, de-duplicated, **ordered** master list of every backend
+> endpoint the UX refactor must build or extend, plus every `.mind`/relational schema migration
+> required. This is the build contract for the LOCKED execution model: **in-place incremental
+> refactor** of `apps/web` + targeted **local Fastify sidecar** extensions. Every endpoint is built
+> over the existing substrate — no new database, minimal-to-zero SQLite migration (see §M).
+>
+> **Sources (all read & grounded):** PRD §16 (`docs/.../Waggle_OS_UX_Refactor_PRD.md:1060-1158`),
+> PRD §8/§21 phase+sprint structure (`:212-253`, `:1304-1374`), PRD §15 data model (`:918-1057`);
+> the 22 gap cards (`docs/ux-refactor/gap-cards/S00–S21`); the route/substrate inventories
+> (`docs/ux-refactor/_inventory/{backend-routes,substrate-types,frontend}.md`); the audited
+> backend-map (`docs/backend-map/sections/03a–03g`); and spot-verified live source under
+> `packages/server/src/local/routes/*.ts`, `packages/server/src/local/workspace-state.ts`,
+> `packages/hive-mind-core/src/{workspace-manager,mind/schema,mind/db}.ts`,
+> `packages/core/src/{install-audit,cron-store}.ts`.
+>
+> **Scope.** Everything is the **Local Sidecar** (`packages/server/src/local/index.ts` →
+> `buildLocalServer()`, loopback `:3333`, flat `/api/*`, Bearer session-token). The desktop frontend
+> talks ONLY to this server. The Clerk-gated **Cloud** server (`packages/server/src/routes/*.ts`) is
+> out of scope — where its routes collide with PRD paths (notably `/api/agents/*`) the sidecar work is
+> still **net-new locally** and flagged.
+
+---
+
+## How to read this
+
+Each row carries:
+
+- **Method + Path** — the PRD/refactor contract path (PRD-literal where §16 names it).
+- **Disposition** — `NET-NEW` (no route serves this; build it) · `EXTEND` (a real handler exists;
+  add alias/param/field/behavior) · `NET-NEW (thin dispatcher/alias)` (new path, delegates wholly to
+  existing handlers, no new logic).
+- **Build target** — the exact route file to create or the existing file/handler/builder to extend
+  (with line where load-bearing). **Verified absent:** `agents.ts`, `artifacts.ts`, `home.ts`,
+  `command.ts`, `mcps.ts`, `automations.ts`, `quick-capture.ts` do **not** exist under
+  `packages/server/src/local/routes/` (grep-confirmed) — all are net-new files.
+- **Substrate** — the store(s) it reads/writes.
+- **Shape** — a 3–5 line request/response sketch.
+- **Screens** — gap-card IDs that consume it.
+
+Counts are in §Counts at the bottom. **De-dup note:** §16 lists 65 endpoints but several are consumed
+by multiple screens (e.g. `/api/workspaces/:id/state` → S01+S02; `/api/skills/*` → S06+S19;
+`/api/agents/*` → S09+S18; the cron→automations aliases → S11+S20; connector/MCP → S07+S08+S14+S17;
+harvest → S15+S16). This master list states each endpoint **once**, attributing all consuming screens.
+Endpoints that **EXIST as-is** with zero backend work (e.g. `GET /api/workspaces`, `GET /api/connectors`,
+`GET /api/memory/graph`, the team CRUD core, the harvest engine) are **excluded** — they need only FE
+wiring. Only NET-NEW + EXTEND backend work is listed.
+
+---
+
+## Phase 0 — Architecture alignment (PRD §8 Phase 0 / §21 Sprint 1)
+
+No new endpoints. Backend-relevant work is **type alignment + shared additive fields** that later
+phases write through. Land these first because Phase 1–5 write paths depend on them.
+
+| Item | Disposition | Build target | Substrate | Notes / shape |
+|---|---|---|---|---|
+| `WorkspaceConfig` V2 additive fields | EXTEND (no route, no migration) | `packages/hive-mind-core/src/workspace-manager.ts:5-58` (interface) + `CreateWorkspaceOptions :60-95` | `workspace.json` (file, NOT SQLite) | Add optional `description, type(WorkspaceType), status('active'\|'paused'\|'archived'), agentIds[], connectorIds[], mcpIds[], updatedAt, lastActiveAt`. Default `status:'active'`; derive `type` from `templateId`/`group` for existing workspaces. **No DB migration** (JSON file). Consumed by S02/S17. |
+| Stamp `updatedAt` on write | EXTEND | `workspace-manager.ts:222` (`update()` currently stamps nothing but `riskClassifiedAt`) | `workspace.json` | One-line write-side touch. |
+| Stamp `lastActiveAt` | EXTEND | agent loop / chat route write-back | `workspace.json` | Currently `lastActive` is DERIVED at read from session mtimes (`workspace-context.ts:375-387`); persist it. |
+| Shared frontend type unions | EXTEND (FE only) | `apps/web/src/lib/types.ts` | — | Add `WorkspaceType, Scope, Confidence, MemoryKind, ArtifactKind, AgentType, AutonomyLevel, ExtensionType` (PRD §15.2). Reconcile FE `MemoryFrame`/`Workspace` lossy projections against API shapes (substrate-types §e). |
+
+---
+
+## Phase 1 — Core runtime: Home, Workspace Desktop, Command Center (PRD §8 Phase 1 / §21 Sprint 2–3)
+
+### 1a. Home Cockpit + Quick Capture (S01) — new `home.ts` + extend `memory.ts`
+
+| Method + Path | Disposition | Build target | Substrate | Shape | Screens |
+|---|---|---|---|---|---|
+| `GET /api/home/briefing` | **NET-NEW** | new `routes/home.ts`; fans `buildWorkspaceState()` (`workspace-state.ts:234`) / `buildWorkspaceNowBlock()` (`workspace-context.ts:191`) over `WorkspaceManager.list()` and ranks | `memory_frames`, session JSONL, `awareness`, `cron_schedules`, `identity` (for name) | `→ { greeting, userName, date, workspaces:[{id,name,rank,summary,pending,nextActions}], suggestedActions[] }`. Cross-workspace ranking aggregator (per-workspace builder is the seed; no cross-WS ranker exists today). | S01 |
+| `GET /api/home/overnight` | **NET-NEW** | new `routes/home.ts`; aggregates over since-last-login window | `events`/`ai_interactions`, `notifications`, `cron_execution_history`, `memory_frames` | `?since=<iso> → { memoriesAdded, artifactsCreated, automationsCompleted, failures:[{source,error}], window:{from,to} }`. No time-windowed delta exists today. | S01 |
+| `POST /api/quick-capture` | **EXTEND** (thin handler delegating to memory write) | `routes/memory.ts` `POST /api/memory/frames` (`:248`) as the write primitive; new thin handler or alias | `memory_frames` (personal `.mind`) + `awareness` (for `kind:task`) + `POST /api/ingest` (for `kind:file`) | `{ kind:'note'\|'task'\|'link'\|'file', content, workspaceId? } → { frameId }`. Defaults to personal mind, stamps `source:'quick-capture'`; `task` also writes an awareness row so it surfaces in `nextActions`. **No migration.** | S01 |
+
+### 1b. Workspace Desktop (S02) — extend `workspaces.ts`
+
+| Method + Path | Disposition | Build target | Substrate | Shape | Screens |
+|---|---|---|---|---|---|
+| `GET /api/workspaces/:id/state` | **EXTEND** (thin route) | new thin route in `workspaces.ts` returning the `buildWorkspaceState()` sub-object already computed inside `/context` (`workspaces.ts:311`) | `memory_frames` + session JSONL + `awareness` | `→ WorkspaceState { active, openQuestions, pending, blocked, completed, stale, recentDecisions, nextActions }` (`workspace-state.ts:38-55`). `pending`+`blocked` seed the Tasks tab. No migration. | S01, S02 |
+| `GET /api/workspaces/:id/activity` | **EXTEND** (thin alias) | new thin route over `GET /api/events?workspaceId=` (`events.ts`) | `ai_interactions` / `execution_traces` / `audit_events` | `?limit= → { events:[{ts,type,actor,summary}] }`. Per-workspace audit feed. No migration. | S02 |
+
+> **No backend work** for S02 Tasks (`tasks.ts` CRUD EXISTS), Members (`/api/team/members` EXISTS),
+> or status-bar feeds (`/api/fleet`, `/api/cron`, `/api/capabilities/status` all EXIST — compose
+> client-side; an aggregate `/status` route is optional and deferred). Artifacts tab is **S05's**
+> scope; S02 ships an interim file-registry view via existing `GET /api/workspaces/:id/files`.
+
+### 1c. Command Center (Ctrl+K) (S00, S03) — new `command.ts`
+
+| Method + Path | Disposition | Build target | Substrate | Shape | Screens |
+|---|---|---|---|---|---|
+| `GET /api/command/search?q=` | **NET-NEW** | new `routes/command.ts` federating route | reads `/api/memory/search` (`memory.ts:120`), `WorkspaceManager.list()`, `/api/skills`, `/api/workspaces/:id/sessions/search` (`sessions.ts`) — **no new store** | `?q=&scope= → { results:[CommandResult{id,kind:'search'\|'launch'\|'create'\|'run'\|'navigate'\|'extend', objectType, title, subtitle?, score, requiresApproval?, payload?}] }`. Federates over ~4 substrates. | S00, S03 |
+| `POST /api/command/execute` | **EXTEND** | existing `POST /api/commands/execute` (note **plural**, `commands.ts`) — extend for navigate/create/run/extend dispatch, OR add a singular `/command/execute` alias | command runtime + dispatch targets | `{ command, objectType?, payload?, workspaceId? } → { ok, result? }`. Current runs slash-commands with a subset CommandContext; PRD's palette execute is broader. | S00, S03 |
+| `GET /api/command/recent` | **NET-NEW** (or client-derive first) | new `routes/command.ts` reading `ai_interactions` (or derive from session/event history) | `ai_interactions` (read-only) | `→ { recent:[{command,ts,objectType}] }`. No schema change. Cheapest v1 = client-side from session history; promote to server when a consumer needs cross-device. | S03 |
+| `GET /api/command/suggestions` | **NET-NEW** | new `routes/command.ts` reusing `deriveNextActions` (`workspace-state.ts:182-218`) + folding in `/api/skills/suggestions` | read-only over `memory_frames`/`awareness`/`cron` | `→ { suggestions:[CommandResult] }`. No migration. | S03 |
+
+---
+
+## Phase 2 — Work layer: Memory Center, Artifact Center, Workspace Creation, Onboarding (PRD §8 Phase 2 / §21 Sprint 4–5)
+
+### 2a. Memory Center (S04, S16) — extend `memory.ts` + ONE optional migration
+
+| Method + Path | Disposition | Build target | Substrate | Shape | Screens |
+|---|---|---|---|---|---|
+| `GET /api/memory` | **EXTEND** (alias) | accept bare path on existing `GET /api/memory/frames` (`memory.ts:188`) | `memory_frames` | `?scope=&kind=&confidence=&status= → { frames:[...] }`. Alias only. | S04 |
+| `GET /api/memory/:id` | **NET-NEW** (thin) | new thin read in `memory.ts` over `FrameStore.getById(id)` (no `GET .../frames/:id` exists today) | `memory_frames` | `→ { frame }`. Drawer detail. No migration. | S04 |
+| `POST /api/memory` | **EXTEND** (alias) | alias on `POST /api/memory/frames` (`memory.ts:248`) | `memory_frames` | `{ kind,title,content,scope,tags? } → { id }`. | S04 |
+| `PATCH /api/memory/:id` | **EXTEND** | extend `PUT /api/memory/frames/:id` (`memory.ts:448`) to accept `PATCH` + bare `:id` | `memory_frames` (`FrameStore.update`) | `{ content?, importance?, status?, tags? } → { ok }`. | S04 |
+| `POST /api/memory/:id/archive` | **NET-NEW** (thin) | new thin route; model archive as `FrameStore.update(id, importance:'deprecated')` OR `status` in the new metadata column | `memory_frames` | `→ { ok }`. No hard delete. | S04 |
+| `DELETE /api/memory/:id` | **EXTEND** (alias) | alias bare `:id` over `DELETE /api/memory/frames/:id` (`memory.ts:551`) | `memory_frames` (`FrameStore.delete`) | `→ { ok }`. | S04 |
+| `POST /api/memory/merge` | **NET-NEW** | new route in `memory.ts`; real logic (read N frames, synthesize merged content, write one, archive/delete originals) — reuse `FrameStore` + `findDuplicate` dedup | `memory_frames` | `{ frameIds:[...], strategy?:'concat'\|'llm' } → { mergedId, archived:[...] }`. Net-new logic, low schema risk. | S04 |
+| Harvest preview/commit confidence + selection | **EXTEND** | `POST /api/harvest/preview` (`harvest.ts:221`) → return ALL items (or paged) + per-item `confidence` + normalized `kind`; `POST /api/harvest/commit` (`harvest.ts:243`) → accept `{ selectedIds?:[] }` filter before the `createIFrame` loop (`:382-409`) | in-memory parse (preview) / `memory_frames` (commit) | Honors the trust-gate AC ("nothing imports without approval"). Preview confidence needs a classifier (LLM or heuristic). Preview-only confidence needs **no** migration. | S16 |
+
+### 2b. Artifact Center (S05) — new `artifacts.ts` (largest net-new domain; aggregation only)
+
+> **Single largest entity gap:** no `Artifact` type, table, or `/api/artifacts*` route exists anywhere
+> (substrate-types §e). The backend is a **thin net-new aggregation/normalization layer** over three
+> existing stores — **NO new data store**. A lightweight `artifacts.json` index holds title/status/
+> tags/relations; the bytes stay in the existing file/document/storage stores.
+
+| Method + Path | Disposition | Build target | Substrate | Shape | Screens |
+|---|---|---|---|---|---|
+| `GET /api/artifacts` | **NET-NEW** | new `routes/artifacts.ts`; normalize 3 stores | `GET /api/workspaces/:id/files` (`workspaces.ts:594`), document versions (`documents.ts`), storage files (`workspaces.ts /storage/files`) + `artifacts.json` index | `?workspaceId=&kind=&status= → { artifacts:[Artifact{id,title,kind,workspaceId,status,mimeType,storagePath,tags,relatedMemoryIds,...}] }`. | S02, S05 |
+| `POST /api/artifacts` | **NET-NEW** | `artifacts.ts`; delegates byte-write to `POST /api/ingest` / `files/upload` / `documents` | file/document stores + `artifacts.json` | `{ title,kind,workspaceId,content?/file? } → { id }`. | S05 |
+| `GET /api/artifacts/:id` | **NET-NEW** | `artifacts.ts`; resolve composite id → normalized Artifact + relations + preview meta | 3 stores + `documents.ts` versions | `→ { artifact, relatedVersions[], relatedMemoryIds[] }`. | S05 |
+| `PATCH /api/artifacts/:id` | **NET-NEW** | `artifacts.ts`; update title/status/tags/relations in `artifacts.json` (move = re-point storagePath via `files/move`) | `artifacts.json` (+ `files/move`) | `{ title?, status?, tags?, relatedMemoryIds? } → { ok }`. | S05 |
+| `DELETE /api/artifacts/:id` | **NET-NEW** (route) | `artifacts.ts`; remove index entry + optionally backing file via `files/delete`/`storage/delete` | `artifacts.json` + file stores | `?deleteBacking=bool → { ok }`. | S05 |
+| `GET /api/artifacts/search-related?q=` | **NET-NEW** | `artifacts.ts`; lean on `memory_frames_fts` + wiki search internally | `memory_frames_fts`, sessions, tasks, fleet | `?q=&artifactId= → { related:[{type,id,title,score}] }`. | S05 |
+
+### 2c. Workspace Creation (S17) — extend `workspaces.ts` write path
+
+| Method + Path | Disposition | Build target | Substrate | Shape | Screens |
+|---|---|---|---|---|---|
+| `POST /api/workspaces` (extend body) | **EXTEND** | `workspaces.ts:116-135` + `WorkspaceManager.create` (`workspace-manager.ts:60-95`) | `workspace.json` | Accept `description, type, status, skills[], agentIds[], connectorIds[], mcpIds[]` (the Phase-0 additive fields). **No DB migration.** | S17 |
+| `GET /api/workspace-templates` (extend shape) | **EXTEND** (optional) | `workspace-templates.ts:33` | template store | Add `skills[]`/`mcps[]`/`type` to `WorkspaceTemplate` so a chosen template pre-populates all 4 suggestion panels. | S17 |
+
+### 2d. Onboarding: First Launch, Who-Are-You, Tool Discovery, Memory Import (S12–S15)
+
+| Method + Path | Disposition | Build target | Substrate | Shape | Screens |
+|---|---|---|---|---|---|
+| `PUT /api/profile` (extend merge) | **EXTEND** | `profile.ts:167-228` allow-list (`:172-196`) + `UserProfile` (`:41-94`) + `DEFAULT_PROFILE` (`:96-135`) | `profile.json` (NOT SQLite) | Add `workType, teamSize, goals[]` to the merged-fields allow-list + interface. Already mirrors identity → memory P/I frame (`:201-224`). **No migration.** | S13 |
+| `POST /api/harvest/sources/:id/sync` | **NET-NEW** (thin) | new thin route in `harvest.ts`; resolve registered source + re-run commit | `harvest_sources` + `memory_frames` | `→ { runId }`. Sync today = `POST /api/harvest/commit`. NOTE: current sources keyed by `:source` **name** (not `:id`) — keep name key or alias. No new substrate. | S15, S16 |
+
+> **S12 First Launch + S14 Tool Discovery need ZERO net-new backend** — all source catalogs already
+> have routes (`GET /api/connectors`, `GET /api/tools/detect`, `GET /api/offline/status`,
+> `GET /api/workspaces`); selections persist client-side in `OnboardingState` (localStorage),
+> optionally threaded via the extended `PUT /api/profile`. The full harvest engine
+> (`preview/commit/sources/progress/scan-claude-code/runs/extract-identity` + `POST /api/ingest`)
+> already EXISTS for S15 — only the `/sources/:id/sync` alias (above) and the S16 confidence/selection
+> extension (Phase 2a) are new.
+
+---
+
+## Phase 3 — Intelligence layer: Agents, Skills, Automations (PRD §8 Phase 3 / §21 Sprint 6)
+
+### 3a. Agent Center + Agent Builder (S09, S18) — new sidecar `agents.ts` + agent store
+
+> **Naming collision:** `/api/agents/*` CRUD exists ONLY on the Clerk-gated **Cloud** server
+> (`packages/server/src/routes/agents.ts`) — NOT the sidecar (confirmed absent). All of §16.7 is
+> **net-new locally**: a new `packages/server/src/local/routes/agents.ts` registered in `local/index.ts`.
+> **Persistence (recommended v1):** a `{dataDir}/agents.json` file store, mirroring the agent-groups
+> JSON precedent (`agent-groups.ts:29`) — **no SQLite migration**. (Alternative: an `agents` table in
+> `mind/schema.ts` with SCHEMA_VERSION bump — only if agents must be FTS/relation-queryable. See §M.)
+
+| Method + Path | Disposition | Build target | Substrate | Shape | Screens |
+|---|---|---|---|---|---|
+| `GET /api/agents` | **NET-NEW** | new `routes/agents.ts`; reads agent store; overlay live status from `/api/agents/active` + `/api/fleet` | `agents.json` (new) | `→ { agents:[Agent{id,name,type,goal,personaId,model,autonomyLevel,status,lastRunAt,successRate,...}] }`. May union saved agents + read-only personas for back-compat. | S09, S18 |
+| `POST /api/agents` | **NET-NEW** | `agents.ts`; persist Agent (§15.5 fields); PRO-tier gate like `personas.ts:32` | `agents.json` + `install_audit` (if elevated tools/MCPs claimed) | `{ name,type,goal,model,personaId?,autonomyLevel,memoryScopes,skillIds,connectorIds,mcpIds,permissions } → { id }`. | S18 |
+| `GET /api/agents/:id` | **NET-NEW** | `agents.ts` read over store | `agents.json` | `→ { agent }`. | S09, S18 |
+| `PATCH /api/agents/:id` | **NET-NEW** | `agents.ts`; mirror `agent-groups.ts:74-90` PATCH shape | `agents.json` | `{ ...partial } → { ok }`. | S18 |
+| `POST /api/agents/:id/run` | **EXTEND** | resolve agent → call real executor `POST /api/fleet/spawn` (`fleet.ts:66`, the only path that runs `runAgentLoop :185`). **Do NOT** use `agent-groups/:id/run` (stub `:105`). | fleet/orchestrator + `execution_traces` via `TraceRecorder` | `{ input?, workspaceId? } → { sessionId }`. Map agent persona/model/memoryScope/workspace onto spawn body. | S09, S18 |
+| `POST /api/agents/:id/pause` | **EXTEND** | map agent→active session → `POST /api/fleet/:workspaceId/pause` (`fleet.ts:260`) | fleet | `→ { ok }`. | S09, S18 |
+| `GET /api/agents/:id/traces` | **NET-NEW** (route over existing store) | new thin read over `execution_traces` (`mind/schema.ts:199`, written by `chat.ts`/`evolution.ts`, **no HTTP read today**), filtered by agent/session; fallback session timeline `sessions.ts` | `execution_traces` + `ai_interactions` | `?limit= → { traces:[{ts,step,tool,outcome,cost}] }`. | S09, S18 |
+
+### 3b. Skills Hub + Skill Builder (S06, S19) — extend `skills.ts`
+
+| Method + Path | Disposition | Build target | Substrate | Shape | Screens |
+|---|---|---|---|---|---|
+| `PATCH /api/skills/:id` | **EXTEND** | add `PATCH` alias + `:id`↔`:name` over `PUT /api/skills/:name` (`skills.ts:506`) | `~/.waggle/skills/*.md` | `{ content? } → { ok }`. No new substrate. | S06, S19 |
+| `POST /api/skills/:id/test` | **EXTEND** | add `:id` path variant routing to existing `POST /api/skills/test` (body-driven) | skill file + `parseSkillFrontmatter` | `{ testInput? } → { wouldInject, frontmatter }`. Sandbox/dry-run only; no execution. | S06, S19 |
+| `POST /api/skills/:id/install` | **NET-NEW** (thin dispatcher) | new dispatcher over `POST /api/skills/starter-pack/:id`, `capability-packs/:id`, `marketplace/install` (keep `requireTier('PRO')` for marketplace-sourced) | `marketplace.db` + `MarketplaceInstaller` + `SecurityGate` + `install_audit` | `{ source:'starter'\|'pack'\|'marketplace' } → { installed }`. Resolves source + delegates. | S06 |
+
+> Skill **create** is the existing structured `POST /api/skills/create` (`skills.ts:431` →
+> `generateSkillMarkdown` + `redactSkillContent` + audit + hash) — the Builder's real target,
+> **EXISTS**. Publish reuses `POST /api/marketplace/publish` (PRO). Optional later: extend
+> `SkillFrontmatter` for structured inputs/outputs/memoryAccess (Builder Steps 3–4) — open question, not
+> in §16.8. No `.mind` migration (skills are flat files; marketplace is `marketplace.db`).
+
+### 3c. Automation Center + Automation Builder (S11, S20) — alias cron as automations
+
+> **The capability is cron** (`cron.ts`, `/api/cron/*` — full CRUD + trigger + history). "Automations"
+> = a rename/alias surface. **Zero MISSING, all PARTIAL.** Register a real `/api/automations/*` alias
+> plugin (PRD vocabulary) OR point the new UI at `/api/cron`. Trigger/condition/actions ride in the
+> existing `job_config TEXT` blob → **no `.mind` migration** for v1.
+
+| Method + Path | Disposition | Build target | Substrate | Shape | Screens |
+|---|---|---|---|---|---|
+| `GET /api/automations` | **EXTEND** (alias) | alias of `GET /api/cron` (`cron.ts:94`); reshape `toResponse` to expose `trigger/condition/actions/status` from `job_type`+`job_config` | `cron_schedules` | `→ { automations:[...] }`. | S11, S20 |
+| `POST /api/automations` | **EXTEND** (alias) | alias of `POST /api/cron` (`cron.ts:67`); persist `trigger/condition/actions` into `job_config` (+ `cron_expr` for schedule triggers) | `cron_schedules` | `{ name,trigger,condition?,actions[],schedule? } → { id }`. | S11, S20 |
+| `PATCH /api/automations/:id` | **EXTEND** (alias) | alias of `PATCH /api/cron/:id` (`cron.ts:124`) | `cron_schedules` | `{ ...partial } → { ok }`. **Note real bug:** FE `updateCronJob` calls `PUT /api/cron/:id` but only `PATCH` is registered (adapter.ts:836 vs cron.ts) — fix the adapter. | S11, S20 |
+| `POST /api/automations/:id/run` | **EXTEND** (alias) | alias of `POST /api/cron/:id/trigger` (`cron.ts:174`; auto-enables + executes + notifies) | `cron_schedules` + executor (`index.ts:1379`) | `→ { runId }`. | S11, S20 |
+| `POST /api/automations/:id/pause` | **NET-NEW** (thin) / EXTEND | add thin `/pause` route OR adapter calls `PATCH /api/cron/:id { enabled:false }` | `cron_schedules.enabled` + scheduler | `→ { ok }`. Add `/pause` for PRD contract. | S11, S20 |
+| `GET /api/automations/:id/logs` | **EXTEND** (alias) | alias of `GET /api/cron/:id/history` (in `notifications.ts:202` → `cronStore.getExecutionHistory`) | `cron_execution_history` | `?limit= → { logs:[...] }`. | S11, S20 |
+| `POST /api/automations/test` | **NET-NEW** | new dry-run route (PRD §12.10 "test before activate"); current `POST /api/cron/:id/trigger` really executes | cron executor (no-persist mode) | `{ trigger,actions[] } → { previewResult }`. No log/notify side-effects. | S20 |
+
+---
+
+## Phase 4 — Extend layer: Connectors, MCPs, Marketplace, Install Audit (PRD §8 Phase 4 / §21 Sprint 7)
+
+### 4a. Connector Hub (S07, S14) — extend `connectors.ts`
+
+| Method + Path | Disposition | Build target | Substrate | Shape | Screens |
+|---|---|---|---|---|---|
+| `POST /api/connectors/:id/sync` | **NET-NEW** | new route in `connectors.ts` (`WaggleConnector` has `connect`/`healthCheck`/`execute` but **no `sync()`**) | vault sub-key `connector:<id>:lastSync` (or small store) + activity event + `install_audit` | `→ { lastSyncAt, ok }`. **Phased:** MVP = `healthCheck()` + stamp `lastSyncAt` + emit event; full data re-pull is a larger connector-SDK addition. No `.mind` migration. | S07 |
+| `POST /api/connectors/:id/revoke` | **EXTEND** (alias) | alias to `POST /api/connectors/:id/disconnect` (`connectors.ts:107`) + write `install_audit` `action:'rejected'`/revoke | vault + `install_audit` | `→ { ok }`. Same intent, PRD verb. | S07 |
+| `POST /api/connectors/:id/connect` (extend) | **EXTEND** | `connectors.ts:55` — add `auditStore.record(...)` on success | vault + `install_audit` | (audit-trail enrichment, no shape change). | S07, S14 |
+| `GET /api/connectors` (extend payload) | **EXTEND** (optional) | `connectors.ts:6` — carry `category` (already on type, `types.ts:299`) + `lastSyncAt` so UI drops hardcoded CATEGORIES/sync-shim | connector registry | (payload enrichment). | S07, S14 |
+| `GET /api/connectors/health` (aggregate) | **NET-NEW** (optional, mockup) | `connectors.ts` — fan `healthCheck()` across connectors | connector registry | `→ { connectors:[{id,status,lastSyncAt}], systemHealth }`. Optional v1; compose client-side otherwise. | S07 |
+| `GET /api/connectors/activity` | **NET-NEW** (or use shared `/api/extend/audit?type=connector`) | reads `install_audit` rows filtered to `type:'connector'` | `install_audit` | `→ { activity:[...] }`. **Prefer the shared `/api/extend/audit`** (4c) which serves S07+S08+S21 with one route. No migration. | S07 |
+
+### 4b. MCP Hub (S08, S17) — new `mcps.ts` + persisted MCP-config store + runtime population
+
+> **The deepest backend gap in the Extend layer.** Today `mcpRuntime` is **empty and never populated**
+> (`local/index.ts:911`); there is no `GET /api/mcps`, no persisted MCP-config store, no boot-time
+> population. All routes live in a new `packages/server/src/local/routes/mcps.ts`. **Substrate decision:**
+> persist installed MCP configs as a JSON file / `.mcp.json` (no migration) — confirm dataDir path +
+> multi-workspace scoping (open question). The MCP catalog is static in `@waggle/shared mcp-catalog.ts`.
+
+| Method + Path | Disposition | Build target | Substrate | Shape | Screens |
+|---|---|---|---|---|---|
+| `GET /api/mcps` | **NET-NEW** | `routes/mcps.ts`; join static catalog (`@waggle/shared mcp-catalog.ts`) + installed-state (`capabilities/status.mcpServers[]`, `.mcp.json`, `marketplace mcp-registry.ts`) | catalog + `.mcp.json` + `install_audit` | `→ { mcps:[{id,name,status,installed,tools[],scope}] }`. Reads existing substrate; no migration. | S08, S17 |
+| `POST /api/mcps/install` | **EXTEND** | route through existing marketplace installer `POST /api/marketplace/install` (already handles `installType:'mcp'` → writes `.mcp.json`, `installer.ts:580`) | `marketplace.db` + `.mcp.json` + `install_audit` | `{ mcpId } → { installed }`. Resolve MCP id → marketplace package → install. Audit already recorded. | S08 |
+| `POST /api/mcps/:id/test` | **NET-NEW** | `mcps.ts`; resolve server, `start()` if needed, assert `isHealthy()` (`mcp-runtime.ts:94,399`) and/or `tools/list` round-trip | `McpRuntime` | `→ { ok, tools[], error? }`. Open question: live spawn-and-handshake vs static manifest validation. | S08 |
+| `POST /api/mcps/:id/revoke` | **NET-NEW** | `mcps.ts`; `mcpRuntime.removeServer(name)` (`mcp-runtime.ts:327`) + delete persisted config + `install_audit` `action:'revoked'` | `McpRuntime` + `.mcp.json` + `install_audit` | `→ { ok }`. | S08 |
+| `POST /api/mcps` (add custom) | **NET-NEW** | `mcps.ts`; persist config + add to runtime (blueprint API line 530) | `.mcp.json` + `McpRuntime` | `{ name, command, args[], env{}, workspaceId? } → { id }`. | S08 |
+| `POST /api/mcps/:id/start` · `POST /api/mcps/:id/stop` | **NET-NEW** | `mcps.ts`; map to `McpRuntime` start/stop (PRD §12.8 start/stop) | `McpRuntime` | `→ { status }`. | S08 |
+| `PATCH /api/mcps/:id/permissions` | **NET-NEW** | `mcps.ts` (blueprint API line 530) | `.mcp.json` config | `{ scope?, permissions? } → { ok }`. | S08 |
+| `GET /api/mcps/:id/logs` | **NET-NEW** (phased) | `mcps.ts`; needs a ring-buffer of stderr/stateChange in `McpServerInstance` (no log capture today) | new in-memory ring buffer | `→ { logs:[...] }`. Defer to later phase if log-capture infra not built. | S08 |
+
+> **Boot-time runtime population** (populate `mcpRuntime` from the persisted config at startup,
+> `local/index.ts:911`) is the foundational non-route work item that unblocks all of the above.
+
+### 4c. Marketplace / Extend + Install Audit (S21, shared S06/S07/S08)
+
+| Method + Path | Disposition | Build target | Substrate | Shape | Screens |
+|---|---|---|---|---|---|
+| `GET /api/marketplace` | **EXTEND** (alias) | bare path = alias of `GET /api/marketplace/search` with default params (`marketplace.ts:56`) | `marketplace.db` | `→ { results:[...] }`. | S21 |
+| `GET /api/extend/audit` (shared governance read) | **EXTEND** (param) | the install-audit read route `GET /api/audit/installs` **already EXISTS** (`skills.ts:685`); add `?capability=` / `?type=` filter exposing `getByCapability()` (`install-audit.ts:125`) | `install_audit` | `?type=skill\|connector\|mcp\|marketplace&limit= → { entries:[AuditEntry] }`. Serves S06+S07+S08+S21 with one route. No migration. **Note:** substrate-types §d#1 listed this as missing; it is present — the work is the filter param, not a new route. | S06, S07, S08, S21 |
+
+> **No `POST /api/share`** here — that is Phase 5 (Team). Per-workspace install scoping (§12.13) is
+> net-new product surface; PRD §22 risk register says "start with catalog + install audit, postpone
+> billing/public marketplace" — **defer to Phase 4 polish**.
+
+---
+
+## Phase 5 — Team intelligence: Team Workspace, RBAC, Sharing, Audit (PRD §8 Phase 5 / §21 Sprint 8)
+
+> Team CRUD core EXISTS in `team.ts` (`teams.db`): `GET/POST/PUT/DELETE /api/teams`, `/:id`,
+> `/members`, `/members/:userId`, `/activity`. No `.mind` migration for the team core (`teams.db`
+> standalone; `team_capability_policies`/`overrides`/`requests` exist in migration `0001`).
+
+| Method + Path | Disposition | Build target | Substrate | Shape | Screens |
+|---|---|---|---|---|---|
+| `POST /api/teams/:id/invite` | **EXTEND** (alias) | thin `/invite` alias forwarding to `POST /api/teams/:id/members` (`team.ts:581`, owner/admin gated) | `team_members` (`teams.db`) | `{ email?, userId?, role? } → { ok }`. No new substrate. | S10 |
+| `GET /api/teams/:id/audit` | **EXTEND** (alias) | alias `/audit` → existing `GET /api/teams/:id/activity` (`team.ts:690`, reads `audit_events` via `getAuditDb`) | `audit_events` | `→ { events:[...] }`. Or add audit-export shape. No new store. | S10 |
+| `PATCH /api/teams/:id/members/:memberId` (fix gate) | **EXTEND** (bug fix) | `team.ts:642` (`:userId`==`:memberId`); **fix PUT(owner-only `:615`) vs PATCH(owner/admin `:642`) role-gate inconsistency** | `team_members` | (behavior fix, no shape change). | S10 |
+| `POST /api/share` | **NET-NEW** | new route (no `/api/share` anywhere — grep-confirmed); shares memory/artifact with role-appropriate perms | `workspace.json teamId` linkage + (if frame-level) `memory_frames` metadata | `{ objectType:'memory'\|'artifact'\|'workspace', objectId, teamId, role } → { ok }`. **Open:** frame-level scope needs the `memory_frames` metadata migration (§M); v1 may scope implicitly via workspace `teamId`. Gate behind TEAMS tier like `/api/team/*`. | S05, S10 |
+| `POST /api/artifacts/:id/share` | **NET-NEW** (blueprint) | maps to `POST /api/share` + artifact scope; gate TEAMS | `artifacts.json` + team scope | `{ teamId, role } → { ok }`. Blueprint action not in §16.6; defer to Phase 5. | S05 |
+| `GET /api/teams/:id/governance` (optional) | **NET-NEW** (optional) | surface `team_capability_policies`/`overrides`/`requests` (migration `0001`); Enterprise proxy `GET /api/team/governance/permissions` (`team.ts:418`) is the remote analog | `team_capability_policies` etc. | `→ { policies[], overrides[], requests[] }`. RBAC UI. | S10 |
+
+---
+
+## §M — Schema migrations required
+
+> **Headline: the entire refactor needs AT MOST ONE conditional SQLite migration**, and it is
+> deferrable. Every other "schema addition" is to a **JSON file** (`workspace.json`, `profile.json`,
+> `agents.json`, `artifacts.json`, `.mcp.json`) — **not** a database — so it is a pure additive
+> TypeScript-interface change with **no migration**. The migration runner already does idempotent
+> additive `ADD COLUMN` on `memory_frames` (precedent: it added `source`, `mind/db.ts:116-124`;
+> pattern = `pragma_table_info` guard + `ALTER TABLE … ADD COLUMN`).
+
+### M1 — `memory_frames.metadata` (CONDITIONAL — Phase 2/Phase 5) — the only `.mind` SQLite migration
+
+- **What:** add one nullable column `metadata TEXT NOT NULL DEFAULT '{}'` to `memory_frames`
+  (`mind/schema.ts:47`). Store `{kind, title, scope, sourceId, sourceUrl, confidence, tags, evidence,
+  relatedMemoryIds, relatedArtifactIds, status}` as JSON (PRD §15.4 fields; PRD endorses metadata-first,
+  `:1013`).
+- **Why conditional:** `memory_frames` is the **only** mind table without a JSON blob column (unlike
+  `awareness.metadata`, `knowledge_entities.properties`, etc.). Needed ONLY when persisted
+  confidence/provenance/scope/status becomes a real **query/filter axis** (S04 Memory Center filters;
+  S16 persisted-confidence review; S10/S05 frame-level `/api/share` scope). **NOT needed** if S16
+  review is preview-only (pre-commit) and S04 filtering is in-app over the existing columns.
+- **Risk:** low — single additive nullable column; avoids touching the FTS/vec virtual tables and IPB
+  scoring. **Promotion path:** if `confidence` becomes a primary indexed filter, a later migration adds
+  `confidence REAL` as a real column (same ADD-COLUMN pattern).
+- **Screens:** S04, S16, S10, S05. **Build target:** `packages/hive-mind-core/src/mind/db.ts` migration
+  block + `mind/schema.ts`.
+
+### M2 — `install_audit` risk-level CHECK fix (RECOMMENDED — pre-Phase 4, latent bug)
+
+- **What:** the TS `AuditRiskLevel` includes `'critical'` (`install-audit.ts:16`) but **both** DDL CHECK
+  constraints allow only `('low','medium','high')` (`install-audit.ts:65` AND `schema.ts:130` — duplicated
+  DDL that must stay in sync). A `record({riskLevel:'critical'})` throws a CHECK violation.
+- **Why:** Phase 4 connector/MCP/skill installs all route through `auditStore.record(...)`. The
+  marketplace route currently side-steps by mapping CRITICAL→`riskLevel:'high'`+`approvalClass:'blocked'`
+  (`marketplace.ts:224-319`) — but any new Extend caller passing `'critical'` crashes.
+- **Fix (pick one):** (a) widen both CHECK constraints to include `'critical'` (additive CHECK migration
+  — needs table rebuild for SQLite CHECK change, or relax to no-CHECK), OR (b) lock the CRITICAL→`'high'`
+  mapping as the permanent contract and drop `'critical'` from the TS union. (b) is zero-migration.
+- **Risk:** low. **Screens:** S06, S07, S08, S21 (all Extend installs). **Build target:**
+  `install-audit.ts:65` + `mind/schema.ts:130` (kept in sync) OR the TS union.
+
+### M3 — `agents` table (OPTIONAL — Phase 3, NOT recommended for v1)
+
+- **What:** an `agents` table in `mind/schema.ts` with a `SCHEMA_VERSION` bump.
+- **Recommendation: do NOT do this for v1.** Persist agents to `{dataDir}/agents.json` (file store,
+  mirrors the `agent-groups.json` precedent `agent-groups.ts:29`) — **no migration, reversible.** Only
+  add the table if agents must be FTS/relation-queryable. PRD §14.4 non-goal favors minimal backend.
+- **Screens:** S09, S18.
+
+### Non-migrations (additive JSON-file / interface changes only — listed for completeness, NOT migrations)
+
+- `WorkspaceConfig` V2 fields → `workspace.json` (Phase 0; substrate-types §a).
+- `UserProfile` `workType/teamSize/goals` → `profile.json` (S13).
+- `Agent` entity → `agents.json` (Phase 3, M3 alt).
+- `Artifact` index → `artifacts.json` (Phase 2b).
+- MCP installed configs → `.mcp.json` (Phase 4b).
+- Automation `trigger/condition/actions` → existing `job_config TEXT` blob (Phase 3c; no schema change).
+- `cron_schedules`/`cron_execution_history`/`notifications` tables already exist with lazy creation
+  (`cron-store.ts:135-157`) — no migration for Automations.
+
+---
+
+## Counts
+
+> Counted as **distinct backend endpoints** (each method+path = 1). Endpoints that **EXIST as-is** and
+> need only frontend wiring are **excluded**. Phase-0 non-route work (V2 fields, FE type unions, write-
+> side stamps) is counted separately under "interface/field extensions", not as endpoints.
+
+- **Total endpoints requiring backend work: 53** (NET-NEW + EXTEND, de-duplicated).
+- **NET-NEW endpoints: 35**
+  - Home ×2 (`/home/briefing`, `/home/overnight`)
+  - Command ×3 (`/command/search`, `/command/recent`, `/command/suggestions`)
+  - Memory ×3 (`/memory/:id`, `/memory/:id/archive`, `/memory/merge`)
+  - Artifacts ×6 (GET, POST, `/:id`, PATCH `/:id`, DELETE `/:id`, `/search-related`)
+  - Agents ×5 (GET, POST, `/:id`, PATCH `/:id`, `/:id/traces`)
+  - Skills ×1 (`/skills/:id/install`)
+  - Automations ×1 (`/automations/test`)
+  - Connectors ×3 (`/:id/sync`, `/connectors/health`, `/connectors/activity`)
+  - MCPs ×8 (`GET /mcps`, `/:id/test`, `/:id/revoke`, `POST /mcps` custom, `/:id/start`, `/:id/stop`, `PATCH /:id/permissions`, `/:id/logs`)
+  - Team ×3 (`POST /api/share`, `POST /artifacts/:id/share`, `GET /teams/:id/governance`)
+  - *(Several MCP/connector/team items are blueprint-implied beyond the §16 literal list; `/api/automations/:id/pause` is counted under EXTEND as a thin alias over the cron `enabled` flag.)*
+- **EXTEND endpoints: 18** (distinct backend touch-points; an EXTEND may be an alias, an added param, or added behavior)
+  - `/quick-capture` (delegates to memory write)
+  - `/workspaces/:id/state`, `/workspaces/:id/activity` (thin routes over existing builders/events)
+  - `/command/execute` (broaden dispatch)
+  - `/memory` GET, `/memory` POST, `/memory/:id` PATCH, `/memory/:id` DELETE (aliases over `/memory/frames*`)
+  - `/harvest/preview` + `/harvest/commit` (confidence + `selectedIds` selection)
+  - `/harvest/sources/:id/sync` (thin re-commit alias)
+  - `/workspaces` POST (richer body)
+  - `/agents/:id/run`, `/agents/:id/pause` (delegate to fleet)
+  - `/skills/:id` PATCH, `/skills/:id/test` (`:id` variants)
+  - 6× `/automations/*` aliases over `/cron/*` (GET, POST, PATCH, run, pause, logs)
+  - `/connectors/:id/revoke`, `/connectors/:id/connect` (+audit), `/connectors` GET (payload)
+  - `/mcps/install` (via marketplace installer)
+  - `/marketplace` (bare-path alias)
+  - `/extend/audit` filter param (over existing `/audit/installs`)
+  - `/teams/:id/invite`, `/teams/:id/audit`, `/teams/:id/members/:memberId` (alias + role-gate fix)
+- **Phase-0 interface/field extensions (NOT endpoints): 5** — `WorkspaceConfig` V2 fields + `updatedAt`/
+  `lastActiveAt` write-stamps (`workspace-manager.ts`), FE type unions (`types.ts`), `UserProfile`
+  `workType/teamSize/goals` (`profile.ts`), `WorkspaceTemplate` shape, `Connector` interface fields.
+- **PRD §16 cross-reference (from `_inventory/backend-routes.md`):** of 65 §16-literal endpoints —
+  **16 EXIST** as-is (FE wiring only), **30 PARTIAL** (→ EXTEND), **19 MISSING** (→ NET-NEW). This
+  master list adds ~16 blueprint-implied endpoints (MCP start/stop/logs/permissions/custom, connector
+  health/activity, automations/test, team governance, artifact-share, extend/audit) beyond the §16
+  literal set.
+- **Schema migrations:** **1 conditional** SQLite (M1 `memory_frames.metadata`) + **1 recommended**
+  CHECK fix (M2 `install_audit` risk-level) + **1 optional/deferred** (M3 `agents` table — recommend
+  NOT doing in v1). Net likely-to-ship: **1** (`memory_frames.metadata`); **0 strictly required** if
+  S16 confidence stays preview-only and `/api/share` scopes implicitly via workspace `teamId`.
+- **New sidecar route files: 5** (`home.ts`, `command.ts`, `artifacts.ts`, `agents.ts`, `mcps.ts`)
+  + 1 alias plugin (`automations.ts` → cron). **New JSON file stores: 2** (`agents.json`,
+  `artifacts.json`); plus reuse of `.mcp.json`, `workspace.json`, `profile.json`.