@cat-factory/app 1.0.0

package/app/composables/useBlockQueries.ts

@@ -0,0 +1,136 @@
+import { computed, type Ref } from 'vue'
+import type { Block, BlockStatus } from '~/types/domain'
+
+/**
+ * Pure, read-only queries over a board's blocks. Extracted from the board store
+ * so the (sizeable) derivation logic — hierarchy traversal, status/progress
+ * rollups and container sizing — lives in one focused, independently testable
+ * place. The store wires these against its reactive `blocks` cache and re-exposes
+ * them unchanged, so callers and tests are unaffected.
+ */
+export function useBlockQueries(blocks: Ref<Block[]>) {
+  const byId = computed(() => {
+    const map = new Map<string, Block>()
+    for (const b of blocks.value) map.set(b.id, b)
+    return map
+  })
+
+  function getBlock(id: string) {
+    return byId.value.get(id)
+  }
+
+  /** Top-level architecture blocks (the only ones drawn as Vue Flow nodes). */
+  const frames = computed(() => blocks.value.filter((b) => (b.level ?? 'frame') === 'frame'))
+
+  /** Direct children of a block, in insertion order. */
+  function childrenOf(parentId: string) {
+    return blocks.value.filter((b) => b.parentId === parentId)
+  }
+
+  /** Tasks directly inside a container (a service or a module). */
+  function tasksOf(containerId: string) {
+    return blocks.value.filter((b) => b.parentId === containerId && b.level === 'task')
+  }
+
+  /** Modules (sub-frames) inside a service. */
+  function modulesOf(serviceId: string) {
+    return blocks.value.filter((b) => b.parentId === serviceId && b.level === 'module')
+  }
+
+  /** Tasks anywhere under a container — directly, or nested inside its modules. */
+  function allTasksUnder(containerId: string): Block[] {
+    const direct = tasksOf(containerId)
+    const nested = modulesOf(containerId).flatMap((m) => tasksOf(m.id))
+    return [...direct, ...nested]
+  }
+
+  /** The top-level service a block ultimately belongs to. */
+  function serviceOf(block: Block): Block | undefined {
+    let cur: Block | undefined = block
+    while (cur && cur.level !== 'frame') {
+      cur = cur.parentId ? getBlock(cur.parentId) : undefined
+    }
+    return cur
+  }
+
+  /** All tasks across every service (used for the dependency picker). */
+  const allTasks = computed(() => blocks.value.filter((b) => b.level === 'task'))
+
+  /** A task's dependencies that are not yet merged (i.e. block it from running). */
+  function unmetDeps(taskId: string) {
+    const t = getBlock(taskId)
+    if (!t) return [] as Block[]
+    return t.dependsOn
+      .map((id) => getBlock(id))
+      .filter((b): b is Block => !!b && b.status !== 'done')
+  }
+
+  /** A task may run only once all of its dependencies have merged. */
+  function isRunnable(taskId: string) {
+    return unmetDeps(taskId).length === 0
+  }
+
+  /** Container status/progress are derived from the tasks under it (containers have no PR). */
+  function frameProgress(frameId: string) {
+    const tasks = allTasksUnder(frameId)
+    if (tasks.length === 0) return getBlock(frameId)?.progress ?? 0
+    const sum = tasks.reduce((n, t) => n + (t.status === 'done' ? 1 : t.progress), 0)
+    return sum / tasks.length
+  }
+
+  /**
+   * A frame is a long-lived service: it never reaches a terminal "done" —
+   * tasks keep appearing. So its status reflects current *activity*, mapped
+   * onto the shared status palette but capped below `done`:
+   *   planned       → no tasks yet (empty)
+   *   ready         → has tasks but nothing active (idle / caught up / "live")
+   *   in_progress   → at least one task running or with an open PR
+   *   blocked       → at least one task needs a decision
+   */
+  function frameStatus(frameId: string): BlockStatus {
+    const tasks = allTasksUnder(frameId)
+    if (tasks.length === 0) return 'planned'
+    if (tasks.some((t) => t.status === 'blocked')) return 'blocked'
+    if (tasks.some((t) => t.status === 'in_progress' || t.status === 'pr_ready'))
+      return 'in_progress'
+    return 'ready'
+  }
+
+  /** Pixel size of a container's inner 2D canvas, derived from its children. */
+  function containerSize(id: string): { w: number; h: number } {
+    const b = getBlock(id)
+    const isModule = b?.level === 'module'
+    const TASK_W = 180
+    const TASK_H = 160
+    const headerH = isModule ? 30 : 0
+    let w = isModule ? 200 : 360
+    let inner = isModule ? 60 : 220
+    for (const t of tasksOf(id)) {
+      w = Math.max(w, t.position.x + TASK_W + 12)
+      inner = Math.max(inner, t.position.y + TASK_H + 12)
+    }
+    for (const m of modulesOf(id)) {
+      const s = containerSize(m.id)
+      w = Math.max(w, m.position.x + s.w + 12)
+      inner = Math.max(inner, m.position.y + s.h + 12)
+    }
+    return { w, h: inner + headerH }
+  }
+
+  return {
+    byId,
+    getBlock,
+    frames,
+    allTasks,
+    childrenOf,
+    tasksOf,
+    modulesOf,
+    allTasksUnder,
+    serviceOf,
+    unmetDeps,
+    isRunnable,
+    frameProgress,
+    frameStatus,
+    containerSize,
+  }
+}

package/app/composables/useBoardFlow.ts

@@ -0,0 +1,11 @@
+import { useVueFlow } from '@vue-flow/core'
+
+/** Stable id for the main board's Vue Flow instance. Passing this id to
+ * useVueFlow() from anywhere (e.g. the toolbar) accesses the same instance. */
+export const BOARD_FLOW_ID = 'board'
+
+/** Camera controls for the main board, usable outside the canvas component. */
+export function useBoardFlow() {
+  const { fitView, zoomIn, zoomOut, viewport } = useVueFlow(BOARD_FLOW_ID)
+  return { fitView, zoomIn, zoomOut, viewport }
+}

package/app/composables/useDepLabels.ts

@@ -0,0 +1,26 @@
+import type { Block } from '~/types/domain'
+
+/**
+ * Labels a dependency block, qualifying it with its owning frame when it lives
+ * in a different container than the task depending on it (a "cross-frame" edge).
+ * Shared by the inspector and the task card so the two read identically.
+ */
+export function useDepLabels() {
+  const board = useBoardStore()
+
+  /** Title of a block's parent container, if any. */
+  function frameTitle(b: Block): string | undefined {
+    return b.parentId ? board.getBlock(b.parentId)?.title : undefined
+  }
+
+  /**
+   * `Parent / Title` when `dep` lives in a different container than
+   * `contextParentId`, otherwise just the dependency's own title.
+   */
+  function depLabel(dep: Block, contextParentId?: string | null): string {
+    const f = frameTitle(dep)
+    return f && dep.parentId !== contextParentId ? `${f} / ${dep.title}` : dep.title
+  }
+
+  return { frameTitle, depLabel }
+}

package/app/composables/useSemanticZoom.ts

@@ -0,0 +1,16 @@
+import type { LodLevel } from '~/types/domain'
+
+/** Map a raw zoom factor to a level-of-detail bucket. Shared by the main board
+ * and the drill-down focus view so both honour the same thresholds. */
+export function zoomToLod(zoom: number): LodLevel {
+  if (zoom < 0.6) return 'far'
+  if (zoom < 1.2) return 'mid'
+  return 'close'
+}
+
+/** Reactive LOD bound to the global UI zoom (set by the board canvas). */
+export function useSemanticZoom() {
+  const ui = useUiStore()
+  const lod = computed<LodLevel>(() => zoomToLod(ui.zoom))
+  return { lod, zoom: computed(() => ui.zoom) }
+}

package/app/composables/useWorkspaceStream.ts

@@ -0,0 +1,125 @@
+import { ref, onScopeDispose } from 'vue'
+import type { WorkspaceEvent } from '~/types/domain'
+
+/**
+ * Subscribes to the backend's per-workspace WebSocket event stream and keeps the
+ * board in sync in real time — the replacement for the old polling clock. Mount
+ * once (e.g. on the board page) after the workspace is ready.
+ *
+ * `execution` events patch the run + its block directly; `bootstrap` events patch
+ * a repo-bootstrap run + its service frame (live "bootstrapping…" progress); the
+ * coarse `board` event (module materialised, run cancelled) triggers a debounced
+ * full refresh. On every (re)connect we refresh once to reconcile anything missed
+ * while disconnected, so the server stays the source of truth and a dropped socket
+ * self-heals.
+ */
+export function useWorkspaceStream() {
+  const workspace = useWorkspaceStore()
+  const execution = useExecutionStore()
+  const board = useBoardStore()
+  const agentRuns = useAgentRunsStore()
+  const api = useApi()
+  const apiBase = useRuntimeConfig().public.apiBase
+
+  const connected = ref(false)
+
+  let socket: WebSocket | null = null
+  let stopped = false
+  let attempt = 0
+  let reconnectTimer: ReturnType<typeof setTimeout> | null = null
+  let boardDebounce: ReturnType<typeof setTimeout> | null = null
+
+  // http→ws, https→wss (apiBase is an absolute origin, see nuxt.config.ts).
+  const wsBase = String(apiBase).replace(/^http/, 'ws')
+
+  function debouncedBoardRefresh() {
+    if (boardDebounce) clearTimeout(boardDebounce)
+    boardDebounce = setTimeout(() => void workspace.refresh(), 300)
+  }
+
+  function onMessage(raw: string) {
+    let event: WorkspaceEvent
+    try {
+      event = JSON.parse(raw) as WorkspaceEvent
+    } catch {
+      return
+    }
+    if (event.type === 'execution') {
+      // Full instance drives the step-level UI; agentRuns derives its coarse
+      // failure/retry summary from the same store, so no extra call is needed.
+      execution.upsert(event.instance)
+      if (event.block) board.upsert(event.block)
+    } else if (event.type === 'board') {
+      debouncedBoardRefresh()
+    } else if (event.type === 'bootstrap') {
+      // Patch the run's live status/subtasks and its provisional/linked frame so
+      // the "bootstrapping…" card updates in place (then flips to a ready service
+      // or a failed badge) without a full refresh.
+      agentRuns.upsertBootstrap(event.job)
+      if (event.block) board.upsert(event.block)
+    }
+  }
+
+  async function connect() {
+    if (stopped || !workspace.workspaceId) return
+    const workspaceId = workspace.workspaceId
+
+    // A browser can't set Authorization on a WS handshake, so mint a short-lived,
+    // workspace-scoped ticket over the authenticated REST channel and pass it as
+    // `?ticket=`. Empty when auth is disabled (dev) — the handshake is open then.
+    let ticket: string
+    try {
+      ticket = (await api.mintEventsTicket(workspaceId)).ticket
+    } catch {
+      // Couldn't mint (offline, token lapsed) — back off and retry.
+      scheduleReconnect()
+      return
+    }
+    // A workspace switch (or stop()) may have happened while awaiting the mint.
+    if (stopped || workspace.workspaceId !== workspaceId) return
+
+    const query = ticket ? `?ticket=${encodeURIComponent(ticket)}` : ''
+    socket = new WebSocket(`${wsBase}/workspaces/${workspaceId}/events${query}`)
+
+    socket.onopen = () => {
+      attempt = 0
+      connected.value = true
+      // Resync on (re)connect: any event missed while disconnected is reconciled.
+      // The snapshot carries `bootstrapJobs` + executions, so one refresh rehydrates
+      // agentRuns too — a missed terminal event (e.g. a container eviction that
+      // failed the run) can't leave a frame stuck on a stale "bootstrapping…" badge.
+      void workspace.refresh()
+    }
+    socket.onmessage = (e) => onMessage(typeof e.data === 'string' ? e.data : '')
+    socket.onclose = () => {
+      connected.value = false
+      scheduleReconnect()
+    }
+    socket.onerror = () => socket?.close()
+  }
+
+  function scheduleReconnect() {
+    if (stopped) return
+    socket = null
+    const delay = Math.min(30_000, 500 * 2 ** attempt) // 0.5s → 30s cap
+    attempt += 1
+    reconnectTimer = setTimeout(connect, delay)
+  }
+
+  function start() {
+    stopped = false
+    connect()
+  }
+
+  function stop() {
+    stopped = true
+    if (reconnectTimer) clearTimeout(reconnectTimer)
+    if (boardDebounce) clearTimeout(boardDebounce)
+    socket?.close()
+    socket = null
+    connected.value = false
+  }
+
+  onScopeDispose(stop)
+  return { start, stop, connected }
+}

package/app/docs/architecture.md

@@ -0,0 +1,31 @@
+# Frontend architecture — state & data flow
+
+How the SPA stays in sync with the backend. The app is a **thin client**: it holds
+no business logic, calls the Worker for every mutation, and hydrates its stores
+from server snapshots plus pushed events. For the high-level tour see
+[`../README.md`](../README.md).
+
+## The three paths
+
+```
+REST (useApi)  ─────────────▶  Worker  ─────────────▶  D1
+   ▲                                                    │
+   │ mutations                                          │ persisted transition
+stores (Pinia)  ◀── patch ──  useWorkspaceStream  ◀── WebSocket push (events hub)
+```
+
+- **Read path** — the `workspace` store loads the full snapshot and fans it into
+  `board`, `pipelines`, `execution`, `spend`, etc.
+- **Write path** — components call `useApi` → Worker; the response (or a pushed
+  event) patches the relevant store. No optimistic business logic.
+- **Live path** — `useWorkspaceStream` opens one WebSocket to
+  `GET /workspaces/:ws/events?token=…`, patches `execution` / `agentRuns` /
+  `board` as events arrive, and refreshes on reconnect to reconcile anything
+  missed.
+
+## Stores
+
+One Pinia store per feature domain: `workspace`, `accounts`, `auth`, `board`,
+`ui`, `pipelines`, `agents`, `execution`, `agentRuns`, `models`, `github`,
+`bootstrap`, `documents`, `tasks`, `requirements`, `scenarios`, `fragments`
+(built-in catalog), `fragmentLibrary` (tenant tiers + sources), and `spend`.

package/app/pages/index.vue

@@ -0,0 +1,80 @@
+<script setup lang="ts">
+import BoardCanvas from '~/components/board/BoardCanvas.vue'
+import SideBar from '~/components/layout/SideBar.vue'
+import BoardToolbar from '~/components/layout/BoardToolbar.vue'
+import SpendWarningBanner from '~/components/layout/SpendWarningBanner.vue'
+import PipelineBuilder from '~/components/pipeline/PipelineBuilder.vue'
+import InspectorPanel from '~/components/panels/InspectorPanel.vue'
+import DecisionModal from '~/components/panels/DecisionModal.vue'
+import BlockFocusView from '~/components/focus/BlockFocusView.vue'
+import DocumentSourceConnectModal from '~/components/documents/DocumentSourceConnectModal.vue'
+import DocumentImportModal from '~/components/documents/DocumentImportModal.vue'
+import SpawnPreviewModal from '~/components/documents/SpawnPreviewModal.vue'
+import TaskSourceConnectModal from '~/components/tasks/TaskSourceConnectModal.vue'
+import TaskImportModal from '~/components/tasks/TaskImportModal.vue'
+import BootstrapModal from '~/components/bootstrap/BootstrapModal.vue'
+import GitHubPanel from '~/components/github/GitHubPanel.vue'
+import FragmentLibraryPanel from '~/components/fragments/FragmentLibraryPanel.vue'
+import RequirementReviewModal from '~/components/requirements/RequirementReviewModal.vue'
+
+const workspace = useWorkspaceStore()
+
+// Load the board from the backend before rendering it.
+onMounted(() => workspace.init())
+
+// Subscribe to the backend's real-time event stream and (re)connect whenever the
+// active workspace changes. Runs advance durably server-side; progress arrives as
+// pushed events rather than by polling.
+const stream = useWorkspaceStream()
+watch(
+  () => workspace.workspaceId,
+  (id) => {
+    stream.stop()
+    if (id) stream.start()
+  },
+  { immediate: true },
+)
+</script>
+
+<template>
+  <div class="flex h-screen w-screen overflow-hidden bg-slate-950 text-slate-100">
+    <template v-if="workspace.ready">
+      <SideBar />
+      <main class="relative min-w-0 flex-1">
+        <BoardCanvas />
+        <BoardToolbar />
+        <SpendWarningBanner />
+        <InspectorPanel />
+        <BlockFocusView />
+      </main>
+
+      <PipelineBuilder />
+      <DecisionModal />
+      <DocumentSourceConnectModal />
+      <DocumentImportModal />
+      <SpawnPreviewModal />
+      <TaskSourceConnectModal />
+      <TaskImportModal />
+      <BootstrapModal />
+      <GitHubPanel />
+      <FragmentLibraryPanel />
+      <RequirementReviewModal />
+    </template>
+
+    <!-- Backend unreachable / bootstrap failed -->
+    <div v-else-if="workspace.error" class="m-auto max-w-md p-8 text-center">
+      <UIcon name="i-lucide-plug-zap" class="mx-auto mb-3 h-10 w-10 text-amber-400" />
+      <h1 class="mb-1 text-lg font-semibold">Can’t reach the backend</h1>
+      <p class="mb-4 text-sm text-slate-400">{{ workspace.error }}</p>
+      <UButton color="primary" icon="i-lucide-rotate-ccw" @click="workspace.init()">
+        Retry
+      </UButton>
+    </div>
+
+    <!-- Initial load -->
+    <div v-else class="m-auto flex flex-col items-center gap-3 text-slate-400">
+      <UIcon name="i-lucide-loader" class="h-8 w-8 animate-spin" />
+      <span class="text-sm">Loading board…</span>
+    </div>
+  </div>
+</template>

package/app/stores/accounts.ts

@@ -0,0 +1,64 @@
+import { defineStore } from 'pinia'
+import { computed, ref } from 'vue'
+import type { Account } from '~/types/domain'
+
+/**
+ * Account tenancy on the client: the accounts the signed-in user can switch
+ * between (their personal account plus any orgs they belong to) and which one is
+ * active. The active account scopes the board switcher and stamps new boards, so
+ * a team can keep org boards separate from personal ones.
+ *
+ * Empty when auth is disabled (the backend returns no accounts in dev), in which
+ * case the UI simply hides the account switcher and boards stay unscoped.
+ */
+export const useAccountsStore = defineStore(
+  'accounts',
+  () => {
+    const api = useApi()
+
+    const accounts = ref<Account[]>([])
+    /** Active account id (persisted so a reload keeps the same context). */
+    const activeAccountId = ref<string | null>(null)
+    const ready = ref(false)
+
+    const activeAccount = computed(
+      () => accounts.value.find((a) => a.id === activeAccountId.value) ?? null,
+    )
+    /** Whether accounts exist (auth on); gates the switcher UI. */
+    const enabled = computed(() => accounts.value.length > 0)
+
+    /** Load the user's accounts and resolve the active one (persisted or first). */
+    async function load() {
+      accounts.value = await api.listAccounts()
+      if (!activeAccountId.value || !accounts.value.some((a) => a.id === activeAccountId.value)) {
+        activeAccountId.value = accounts.value[0]?.id ?? null
+      }
+      ready.value = true
+    }
+
+    /** Create a shared org account and make it active. */
+    async function createOrg(name: string) {
+      const account = await api.createAccount({ name })
+      accounts.value.push(account)
+      activeAccountId.value = account.id
+      return account
+    }
+
+    /** Switch the active account (the caller re-scopes the board list). */
+    function switchTo(id: string) {
+      activeAccountId.value = id
+    }
+
+    return {
+      accounts,
+      activeAccountId,
+      activeAccount,
+      enabled,
+      ready,
+      load,
+      createOrg,
+      switchTo,
+    }
+  },
+  { persist: { pick: ['activeAccountId'] } },
+)

package/app/stores/agentRuns.ts

@@ -0,0 +1,117 @@
+import { defineStore } from 'pinia'
+import { computed, ref } from 'vue'
+import type { AgentFailure, AgentRunKind, BootstrapJob, StepSubtasks } from '~/types/domain'
+import { useWorkspaceStore } from '~/stores/workspace'
+import { useExecutionStore } from '~/stores/execution'
+
+/**
+ * A coarse, per-block view of the current "agent run" against a block, regardless
+ * of which flow produced it — enough for the board to render a failure banner +
+ * retry and a "working…" progress badge uniformly. The rich step-level UI still
+ * reads the full {@link ExecutionInstance} from the execution store.
+ */
+export interface AgentRunSummary {
+  blockId: string
+  kind: AgentRunKind
+  /** The run's own status: execution running|blocked|done|paused|failed,
+   * bootstrap pending|running|succeeded|failed. */
+  status: string
+  /** Id of the run, for the unified retry endpoint. */
+  runId: string
+  /** Structured failure when `status` is `failed`; null otherwise. */
+  failure: AgentFailure | null
+  /** Latest subtask counts for a live progress bar (null until reported). */
+  subtasks: StepSubtasks | null
+}
+
+/**
+ * Unified failure/retry surface over BOTH agent flows. Bootstrap runs are held
+ * here (they have no other home on the client); executions are read from the
+ * execution store so they're never duplicated. `byBlock` merges the two so a
+ * board card / inspector can look itself up and show the same failure banner +
+ * retry whether the block was made by a bootstrap or is running a task pipeline.
+ *
+ * This replaces the old bootstrap-only `bootstrap.byBlock`/`retry`, whose retry
+ * could silently vanish when the separate jobs projection failed to resolve.
+ */
+export const useAgentRunsStore = defineStore('agentRuns', () => {
+  const api = useApi()
+  const execution = useExecutionStore()
+
+  /** Bootstrap runs for this workspace, newest-first. */
+  const bootstrapJobs = ref<BootstrapJob[]>([])
+
+  /** Replace the cached bootstrap runs with a server snapshot. */
+  function hydrate(jobs: BootstrapJob[]) {
+    bootstrapJobs.value = [...jobs].sort((a, b) => b.createdAt - a.createdAt)
+  }
+
+  /**
+   * Patch a bootstrap run from a real-time `bootstrap` event (or after launching
+   * one): replace it in place by id, else prepend it. Keeps the service card
+   * reactive to live progress without a refetch.
+   */
+  function upsertBootstrap(job: BootstrapJob) {
+    const i = bootstrapJobs.value.findIndex((j) => j.id === job.id)
+    if (i >= 0) bootstrapJobs.value[i] = job
+    else bootstrapJobs.value.unshift(job)
+  }
+
+  /**
+   * The current run summary per block, merged from execution instances (task
+   * runs) and bootstrap runs (service frames). Executions take a block first;
+   * a frame block has no execution, so the newest bootstrap run wins there.
+   */
+  const byBlock = computed<Record<string, AgentRunSummary>>(() => {
+    const map: Record<string, AgentRunSummary> = {}
+    for (const e of execution.instances) {
+      map[e.blockId] = {
+        blockId: e.blockId,
+        kind: 'execution',
+        status: e.status,
+        runId: e.id,
+        failure: e.failure ?? null,
+        subtasks: e.steps[e.currentStep]?.subtasks ?? null,
+      }
+    }
+    // `bootstrapJobs` is newest-first; keep the first (newest) seen per block.
+    for (const job of bootstrapJobs.value) {
+      if (!job.blockId || map[job.blockId]) continue
+      map[job.blockId] = {
+        blockId: job.blockId,
+        kind: 'bootstrap',
+        status: job.status,
+        runId: job.id,
+        failure: job.failure,
+        subtasks: job.subtasks,
+      }
+    }
+    return map
+  })
+
+  /**
+   * Retry a failed run (bootstrap or execution) via the unified endpoint, then
+   * refresh the snapshot so both stores rehydrate — the card flips from failed
+   * back to "working…" as a fresh run is dispatched server-side.
+   */
+  async function retry(runId: string) {
+    const ws = useWorkspaceStore()
+    await api.retryAgentRun(ws.requireId(), runId)
+    await ws.refresh()
+  }
+
+  /**
+   * Explicitly stop a running run (bootstrap or execution) via the unified endpoint:
+   * the backend kills the per-run container + tears down the durable driver, then
+   * marks the run cancelled. Refresh so both stores rehydrate and the card flips out
+   * of its "running" state. Returns the resolved kind so the caller can word a toast.
+   */
+  async function stop(runId: string): Promise<AgentRunKind> {
+    const ws = useWorkspaceStore()
+    const { kind } = await api.stopAgentRun(ws.requireId(), runId)
+    await ws.refresh()
+    return kind
+  }
+
+  return { bootstrapJobs, hydrate, upsertBootstrap, byBlock, retry, stop }
+})

package/app/stores/agents.ts

@@ -0,0 +1,40 @@
+import { defineStore } from 'pinia'
+import { ref } from 'vue'
+import { AGENT_ARCHETYPES, AGENT_BY_KIND, uid } from '~/utils/catalog'
+import type { AgentArchetype, AgentKind } from '~/types/domain'
+
+/**
+ * The agent palette. Seeded from the static catalog, but custom agents can be
+ * added at runtime (they show up in the pipeline builder). Newly created agents
+ * are also registered into AGENT_BY_KIND so the many components that look an
+ * agent up by kind keep rendering it correctly.
+ */
+export const useAgentsStore = defineStore('agents', () => {
+  const archetypes = ref<AgentArchetype[]>([...AGENT_ARCHETYPES])
+
+  function get(kind: AgentKind) {
+    return AGENT_BY_KIND[kind]
+  }
+
+  function addAgent(input: {
+    label: string
+    description?: string
+    icon?: string
+    color?: string
+  }): AgentArchetype {
+    const archetype: AgentArchetype = {
+      // custom kinds are free-form ids; cast keeps the existing AgentKind typing happy
+      kind: uid('agent') as AgentKind,
+      label: input.label.trim() || 'Custom Agent',
+      description: input.description?.trim() || 'Custom agent.',
+      icon: input.icon || 'i-lucide-sparkles',
+      color: input.color || '#22d3ee',
+    }
+    // register for kind-based lookups across the app, then surface in the palette
+    AGENT_BY_KIND[archetype.kind] = archetype
+    archetypes.value.push(archetype)
+    return archetype
+  }
+
+  return { archetypes, get, addAgent }
+})