@cat-factory/app 0.132.0 → 0.134.0

package/app/modular/registry.ts

@@ -1,7 +1,9 @@
-import { defineModule } from '@modular-vue/core'
 import type { AnyModuleDescriptor } from '@modular-vue/core'
 import { createRegistry } from '@modular-vue/runtime'
 import type { ModuleRegistry } from '@modular-vue/runtime'
+import { navigationModule } from '~/modular/nav-contributions'
+import type { NavGates } from '~/modular/nav-contributions'
+import type { AppSlots } from '~/modular/slots'
 
 /**
  * modular-vue registry for the `@cat-factory/app` layer (slice 0 of the
@@ -13,21 +15,29 @@ import type { ModuleRegistry } from '@modular-vue/runtime'
  * contributes its own, all through the same seam. The registry is resolved and
  * installed by `app/plugins/modular.client.ts`.
  *
- * Slice 0 wires the plumbing behind ZERO behaviour change: the one first-party
- * module carries no navigation / slots / component, so nothing new renders.
- * Later slices convert real areas (navigation, result views, wizards, inspector
- * panels) into modules registered here.
+ * Slice 1 registers the first real feature module: `cat-factory:navigation`
+ * contributes the whole nav/command catalog to the `nav` slot, gated reactively
+ * by a `gates` service + `navSlotFilter` and rendered by `SideBar`, `CommandBar`,
+ * and `BoardToolbar` via `useReactiveSlots`. Later slices add result views,
+ * wizards, and inspector panels as further modules registered here.
  */
 
 /**
- * First-party modules the layer always registers. Kept tiny on purpose for
- * slice 0 — a single descriptor with no contributions, present only to prove the
- * registration pipeline end to end and give the seam a stable anchor. Real
- * feature modules land here as later slices convert each area.
+ * The layer's shared-dependency shape (grows as later slices wire more deps).
+ * A `type` (not `interface`) so it satisfies the registry's
+ * `Record<string, any>` dependency constraint — an interface lacks the implicit
+ * index signature a type-literal has.
  */
-const FIRST_PARTY_MODULES: readonly AnyModuleDescriptor[] = [
-  defineModule({ id: 'cat-factory:core', version: '1.0.0' }),
-]
+export type AppDeps = {
+  /** Reactive RBAC/availability gates the nav `slotFilter` reads. */
+  gates: NavGates
+}
+
+/**
+ * First-party modules the layer always registers. Real feature modules land
+ * here as each area is converted; slice 1 adds the navigation catalog.
+ */
+const FIRST_PARTY_MODULES: readonly AnyModuleDescriptor[] = [navigationModule]
 
 /**
  * Consumer-contributed modules, collected before the layer resolves its
@@ -61,14 +71,33 @@ export function __resetConsumerModulesForTest(): void {
 }
 
 /**
- * Build a fresh registry with the first-party modules plus everything a consumer
- * contributed via {@link registerAppModule}. A new registry per call because
- * `resolve()` / `resolveManifest()` are single-commit; the install plugin calls
- * this exactly once at client startup (`ssr: false`, so a singleton app).
+ * Build a fresh registry with the first-party modules, any `extraModules` the
+ * caller supplies, plus everything a consumer contributed via
+ * {@link registerAppModule}. A new registry per call because `resolve()` /
+ * `resolveManifest()` are single-commit; the install plugin calls this exactly
+ * once at client startup (`ssr: false`, so a singleton app).
+ *
+ * `deps.gates` is the reactive gate service the nav `slotFilter` reads; it's
+ * built in the install plugin (Vue context) and registered as a `service` so
+ * `useReactiveSlots` tracks it. Each slot default is seeded empty so the key
+ * always exists even before any module (or with only consumer modules)
+ * contributes to it.
+ *
+ * `extraModules` is how the client plugin registers first-party modules that
+ * carry Vue components (the `resultViews` registry): keeping them out of
+ * `FIRST_PARTY_MODULES` keeps this module's static import graph — which the
+ * unit tests exercise — free of `.vue` files (the vitest config has no SFC
+ * transform).
  */
-export function createAppRegistry(): ModuleRegistry<Record<string, unknown>> {
-  const registry = createRegistry<Record<string, unknown>>({})
-  for (const mod of [...FIRST_PARTY_MODULES, ...consumerModules]) {
+export function createAppRegistry(
+  deps: AppDeps,
+  extraModules: readonly AnyModuleDescriptor[] = [],
+): ModuleRegistry<AppDeps, AppSlots> {
+  const registry = createRegistry<AppDeps, AppSlots>({
+    services: { gates: deps.gates },
+    slots: { nav: [], resultViews: [], agentKinds: [] },
+  })
+  for (const mod of [...FIRST_PARTY_MODULES, ...extraModules, ...consumerModules]) {
     registry.register(mod)
   }
   return registry

package/app/modular/result-views.ts

@@ -0,0 +1,104 @@
+import type { Component } from 'vue'
+import { defineModule } from '@modular-vue/core'
+import { RESULT_VIEW_IDS, type ResultViewId } from '@cat-factory/contracts'
+import RequirementsReviewWindow from '~/components/requirements/RequirementsReviewWindow.vue'
+import ClarityReviewWindow from '~/components/clarity/ClarityReviewWindow.vue'
+import BrainstormWindow from '~/components/brainstorm/BrainstormWindow.vue'
+import TestReportWindow from '~/components/testing/TestReportWindow.vue'
+import HumanTestWindow from '~/components/humanTest/HumanTestWindow.vue'
+import VisualConfirmationWindow from '~/components/visualConfirm/VisualConfirmationWindow.vue'
+import GateResultView from '~/components/gates/GateResultView.vue'
+import ConsensusSessionWindow from '~/components/consensus/ConsensusSessionWindow.vue'
+import GenericStructuredResultView from '~/components/panels/GenericStructuredResultView.vue'
+import ServiceSpecWindow from '~/components/spec/ServiceSpecWindow.vue'
+import FollowUpWindow from '~/components/followUp/FollowUpWindow.vue'
+import ForkDecisionWindow from '~/components/forkDecision/ForkDecisionWindow.vue'
+import PrReviewWindow from '~/components/prReview/PrReviewWindow.vue'
+import MergerResultView from '~/components/panels/MergerResultView.vue'
+import InitiativeTrackerWindow from '~/components/initiative/InitiativeTrackerWindow.vue'
+import InitiativePlanningWindow from '~/components/initiative/InitiativePlanningWindow.vue'
+import DocInterviewWindow from '~/components/docs/DocInterviewWindow.vue'
+import RalphLoopResultView from '~/components/ralph/RalphLoopResultView.vue'
+import type { ResultViewContribution } from './slots'
+
+/**
+ * The first-party result-view registry (slice 2 of the modular-vue adoption —
+ * docs/initiatives/modular-vue-adoption.md).
+ *
+ * Every built-in dedicated result window is contributed as a `ComponentEntry`
+ * to the `resultViews` slot instead of living in a hardcoded `Record` in
+ * `StepResultViewHost.vue`. The host reads the merged slot via
+ * `resolveComponentRegistry` (`@modular-vue/core`) and mounts `get(viewId)`; a
+ * step's/kind's `resultView` id (built-in or a custom kind's) selects the entry.
+ *
+ * A consumer deployment ships its OWN result window by contributing another
+ * `ComponentEntry` to the SAME slot from a `registerAppModule` module — it then
+ * mounts with zero host edits (the extensibility promise), paired against the
+ * kind's `presentation.resultView` id exactly like the built-ins. Consumer ids
+ * SHOULD be namespaced (`acme:report`) so they can't collide with a built-in;
+ * `resolveComponentRegistry` throws on a duplicate id by default.
+ *
+ * Because these carry Vue components, this module is registered from the client
+ * plugin (`plugins/modular.client.ts`), NOT from `createAppRegistry` — that
+ * keeps the pure/unit-tested registry import graph free of `.vue` files (the
+ * vitest config has no SFC transform).
+ *
+ * Built-in coverage is enforced at COMPILE time: {@link BUILT_IN_RESULT_VIEWS} is a
+ * `Record<ResultViewId, Component>`, so a built-in added to the contract's
+ * `RESULT_VIEW_IDS` picklist without a component here (or a stray id that isn't a
+ * built-in) is a `nuxt typecheck` failure — a CI gate — rather than a runtime warning
+ * that could ship. Consumer namespaced ids are validated separately by `pairById`.
+ */
+const BUILT_IN_RESULT_VIEWS: Record<ResultViewId, Component> = {
+  'requirements-review': RequirementsReviewWindow,
+  'clarity-review': ClarityReviewWindow,
+  // Shared by both brainstorm stages (requirements + architecture); the window reads the stage.
+  brainstorm: BrainstormWindow,
+  tester: TestReportWindow,
+  // The human-testing gate: env URL + confirm / request-fix / pull-main / recreate / destroy.
+  'human-test': HumanTestWindow,
+  // The visual-confirmation gate: actual-vs-reference screenshot gallery + approve / request-fix.
+  'visual-confirm': VisualConfirmationWindow,
+  // Shared by all polling gates (`ci` / `conflicts` / `human-review` / …); the window branches on kind.
+  gate: GateResultView,
+  // Opened for any step that ran the consensus mechanism (routed in `ui.dispatchStepView`).
+  'consensus-session': ConsensusSessionWindow,
+  // Default dedicated view for a registered CUSTOM kind's structured (`custom`) output —
+  // a read-only JSON viewer, so a proprietary agent ships a result view with no bespoke code.
+  'generic-structured': GenericStructuredResultView,
+  // The service's prescriptive spec tree (+ Gherkin); opened directly via `ui.openServiceSpec`.
+  'service-spec': ServiceSpecWindow,
+  // The Follow-up companion: the Coder's surfaced loose ends / questions.
+  'follow-ups': FollowUpWindow,
+  // The implementation-fork decision: the proposer's approaches + the human's pick / custom.
+  'fork-decision': ForkDecisionWindow,
+  // The PR deep-review: the reviewer's sliced, prioritized findings + the human's multi-select.
+  'pr-review': PrReviewWindow,
+  // The merger's verdict: PR complexity/risk/impact scores + the engine's decision (and why).
+  merger: MergerResultView,
+  // The initiative tracker: phases, per-item status + PR links, decisions, deviations, caveats.
+  'initiative-tracker': InitiativeTrackerWindow,
+  'initiative-planning': InitiativePlanningWindow,
+  // The interactive document-interview gate: clarifying questions + answer / continue / proceed.
+  'doc-interview': DocInterviewWindow,
+  // The Ralph loop: the retry-until-done iteration history + the validation command + its output.
+  'ralph-loop': RalphLoopResultView,
+}
+
+/**
+ * The built-in windows as slot entries, derived from `RESULT_VIEW_IDS` so the slot order matches
+ * the canonical id order. Exhaustiveness is guaranteed by {@link BUILT_IN_RESULT_VIEWS}'s type.
+ */
+export const RESULT_VIEW_CONTRIBUTIONS: readonly ResultViewContribution[] = RESULT_VIEW_IDS.map(
+  (id) => ({ id, component: BUILT_IN_RESULT_VIEWS[id] }),
+)
+
+/**
+ * The first-party result-views module: contributes every built-in window to the
+ * `resultViews` slot. Registered from the client plugin (see the note above).
+ */
+export const resultViewsModule = defineModule({
+  id: 'cat-factory:result-views',
+  version: '1.0.0',
+  slots: { resultViews: [...RESULT_VIEW_CONTRIBUTIONS] },
+})

package/app/modular/slots.ts

@@ -0,0 +1,40 @@
+import type { Component } from 'vue'
+import type { ComponentEntry } from '@modular-vue/core'
+import type { CustomAgentKind } from '~/types/domain'
+import type { NavContribution } from './nav-contributions'
+
+/**
+ * The layer's aggregated slot map — the single home for every slot key the
+ * first-party modules (and consumer deployments) contribute to. Grows one key
+ * per converted seam as the modular-vue adoption proceeds
+ * (docs/initiatives/modular-vue-adoption.md):
+ *
+ *  - `nav` (slice 1) — the nav/command catalog, rendered by the three shells.
+ *  - `resultViews` (slice 2) — the id → dedicated result-window registry
+ *    ({@link ResultViewContribution}), read by `StepResultViewHost` through
+ *    `resolveComponentRegistry`. First-party AND consumer components enter here.
+ *  - `agentKinds` (slice 2) — CODE-shipped custom agent kinds a consumer module
+ *    contributes (the palette/catalog data half). BACKEND-registered kinds
+ *    arrive separately as a {@link RemoteModuleManifest} read in the agents
+ *    store — see `stores/agents.ts`.
+ *
+ * The index signature is mutable (`unknown[]`) to satisfy the runtime's
+ * `SlotMap` constraint while `unknown[]` still meets `useReactiveSlots`'
+ * `readonly unknown[]` bound (the slice-1 type-friction note).
+ */
+export interface AppSlots {
+  nav: NavContribution[]
+  resultViews: ResultViewContribution[]
+  agentKinds: CustomAgentKind[]
+  [key: string]: unknown[]
+}
+
+/**
+ * One dedicated result-view window, addressed by its `resultView` id (the same
+ * ids as `@cat-factory/contracts` `RESULT_VIEW_IDS` for the built-ins). A plain
+ * `ComponentEntry` so the modular `resolveComponentRegistry` / `pairById`
+ * helpers index and pair it with the wire-delivered `presentation.resultView`
+ * id — the sanctioned "backend data selects a code-shipped, locally-registered
+ * component" pairing (see the modular-vue Remote Capability Manifests guide).
+ */
+export type ResultViewContribution = ComponentEntry<Component>

package/app/plugins/modular.client.ts

@@ -1,5 +1,11 @@
 import { installModularApp } from '@modular-vue/nuxt/runtime'
+import { resolveComponentRegistry } from '@modular-vue/core'
 import { createAppRegistry } from '~/modular/registry'
+import { navSlotFilter } from '~/modular/nav-contributions'
+import { createNavGates } from '~/modular/nav-gates'
+import { resultViewsModule } from '~/modular/result-views'
+import type { AppSlots, ResultViewContribution } from '~/modular/slots'
+import type { CustomAgentKind } from '~/types/domain'
 
 /**
  * Wire the modular-vue registry into the Nuxt app (slice 0 of the modular-vue
@@ -16,17 +22,42 @@ import { createAppRegistry } from '~/modular/registry'
  *
  * `ssr: false`, so this runs once on the client and a singleton registry is
  * fine. `installModularApp` is the router-owning path: it grafts each module's
- * routes onto Nuxt's router (none yet — slice 0 modules are non-routed) and
- * installs the modular contexts (shared deps, navigation, slots) app-wide. The
- * resolved manifest is exposed as `$modular` for later slices; nothing reads it
- * yet, which is what keeps this behaviour-neutral.
+ * routes onto Nuxt's router (none yet — the nav modules are non-routed) and
+ * installs the modular contexts (shared deps, navigation, slots) app-wide.
+ *
+ * Slice 1 wires the reactive nav gating here: `createNavGates()` builds the
+ * reactive `gates` service (Pinia + composables are available in a `post`
+ * plugin), which the registry registers as a `service` and `navSlotFilter` reads
+ * per item. The shells consume the gated `nav` slot through `useReactiveSlots`,
+ * so a permission/connection flip re-gates them with no `recalculateSlots()`.
+ *
+ * Slice 2 registers the first-party `resultViews` registry here (via
+ * `extraModules`, so its Vue-component imports stay out of the unit-tested
+ * `registry.ts` import graph), and feeds the resolved static `agentKinds` slot —
+ * the deployment's CODE-shipped consumer agent kinds — into the agents store.
+ * (Backend-registered kinds arrive later as the per-workspace capability
+ * manifest via `hydrateCustomKinds`.) The result-view components themselves are
+ * read reactively by `StepResultViewHost` through `useReactiveSlots`.
  */
 export default defineNuxtPlugin({
   name: 'cat-factory:modular',
   enforce: 'post',
   setup(nuxtApp) {
-    const registry = createAppRegistry()
-    const manifest = installModularApp({ vueApp: nuxtApp.vueApp, $router: useRouter() }, registry)
+    const registry = createAppRegistry({ gates: createNavGates() }, [resultViewsModule])
+    const manifest = installModularApp({ vueApp: nuxtApp.vueApp, $router: useRouter() }, registry, {
+      slotFilter: navSlotFilter,
+    })
+    const slots = manifest.slots as AppSlots
+    // Fail FAST on a result-view wiring bug (a duplicate id across the first-party +
+    // consumer `resultViews` modules) at BOOT rather than lazily the first time a result
+    // window opens: resolve the merged slot once here. `resolveComponentRegistry` throws on
+    // a duplicate id by default, so a misconfigured deployment surfaces at startup with a
+    // clear stack. The slot is static after this resolve, so `StepResultViewHost`'s own
+    // reactive re-resolve is a cheap memoized read that this has already validated.
+    resolveComponentRegistry((slots.resultViews ?? []) as ResultViewContribution[])
+    // Consumer agent kinds contributed as CODE to the static `agentKinds` slot
+    // (module slots resolve once, so the static base is the full set).
+    useAgentsStore().registerConsumerKinds((slots.agentKinds ?? []) as CustomAgentKind[])
     return { provide: { modular: manifest } }
   },
 })

package/app/stores/agents.spec.ts

@@ -0,0 +1,100 @@
+import { describe, expect, it } from 'vitest'
+import { useAgentsStore } from './agents'
+import {
+  __resetCustomAgentKindMetaForTest,
+  agentKindMeta,
+  AGENT_ARCHETYPES,
+  isKnownAgentKind,
+} from '~/utils/catalog'
+import type { AgentKind, CustomAgentKind } from '~/types/domain'
+
+const backendKind = (
+  kind: string,
+  over: Partial<CustomAgentKind['presentation']> = {},
+): CustomAgentKind => ({
+  kind: kind as AgentKind,
+  container: true,
+  presentation: {
+    label: `L:${kind}`,
+    icon: 'i-lucide-shield',
+    color: '#abc',
+    description: 'd',
+    ...over,
+  },
+})
+
+describe('agents store — custom-kind catalog (slice 2)', () => {
+  it('exposes only the built-in archetypes before any custom kind is hydrated', () => {
+    const agents = useAgentsStore()
+    expect(agents.archetypes).toHaveLength(AGENT_ARCHETYPES.length)
+    expect(agents.customArchetypes).toEqual([])
+  })
+
+  it('folds a backend remote-manifest custom kind into the palette + the pure-util projection', () => {
+    __resetCustomAgentKindMetaForTest()
+    const agents = useAgentsStore()
+    // Before hydrate the pure-util lookups don't know the kind.
+    expect(isKnownAgentKind('acme-audit')).toBe(false)
+    expect(agentKindMeta('acme-audit').label).toBe('Agent') // generic fallback
+
+    agents.hydrateCustomKinds([
+      backendKind('acme-audit', { category: 'review', resultView: 'acme:audit' }),
+    ])
+
+    // Palette + kind lookup both see it now (sync-flush projection — no tick needed).
+    expect(agents.archetypes.some((a) => a.kind === 'acme-audit')).toBe(true)
+    expect(isKnownAgentKind('acme-audit')).toBe(true)
+    const meta = agentKindMeta('acme-audit')
+    expect(meta.label).toBe('L:acme-audit')
+    expect(meta.resultView).toBe('acme:audit')
+    expect(meta.category).toBe('review')
+  })
+
+  it('never lets a custom kind shadow a built-in kind', () => {
+    const agents = useAgentsStore()
+    agents.hydrateCustomKinds([backendKind('coder', { label: 'Evil Coder' })])
+    // `coder` is a built-in; the custom entry is dropped, the built-in wins.
+    expect(agents.customArchetypes.some((a) => a.kind === 'coder')).toBe(false)
+    expect(agentKindMeta('coder').label).not.toBe('Evil Coder')
+  })
+
+  it('merges CODE-shipped consumer kinds with BACKEND manifest kinds, de-duplicated', () => {
+    const agents = useAgentsStore()
+    agents.registerConsumerKinds([backendKind('acme-consumer')])
+    agents.hydrateCustomKinds([backendKind('acme-backend'), backendKind('acme-consumer')])
+    const kinds = agents.customArchetypes.map((a) => a.kind)
+    expect(kinds).toContain('acme-consumer')
+    expect(kinds).toContain('acme-backend')
+    // consumer + backend both name `acme-consumer`; it appears once (consumer-slot first).
+    expect(kinds.filter((k) => k === 'acme-consumer')).toHaveLength(1)
+  })
+
+  it('no-ops a re-hydrate of identical content (stable projection, content-versioned manifest)', () => {
+    const agents = useAgentsStore()
+    agents.hydrateCustomKinds([backendKind('acme-x', { resultView: 'acme:x' })])
+    const first = agents.customArchetypes
+    // A new snapshot re-delivering structurally-equal kinds (fresh objects) must not
+    // recompute the merged catalog — the content-derived manifest version is unchanged, so
+    // `hydrateCustomKinds` skips the swap and the computed keeps its cached identity.
+    agents.hydrateCustomKinds([backendKind('acme-x', { resultView: 'acme:x' })])
+    expect(agents.customArchetypes).toBe(first)
+  })
+
+  it('swaps the backend catalog wholesale on re-hydrate (per-workspace manifest)', () => {
+    const agents = useAgentsStore()
+    agents.hydrateCustomKinds([backendKind('ws1-kind')])
+    expect(agents.customArchetypes.some((a) => a.kind === 'ws1-kind')).toBe(true)
+    agents.hydrateCustomKinds([backendKind('ws2-kind')])
+    expect(agents.customArchetypes.some((a) => a.kind === 'ws1-kind')).toBe(false)
+    expect(agents.customArchetypes.some((a) => a.kind === 'ws2-kind')).toBe(true)
+    expect(isKnownAgentKind('ws1-kind')).toBe(false)
+  })
+
+  it('addAgent registers an in-UI prototype without touching the built-in catalog', () => {
+    const agents = useAgentsStore()
+    const created = agents.addAgent({ label: 'My Agent' })
+    expect(agents.archetypes.some((a) => a.kind === created.kind)).toBe(true)
+    expect(created.category).toBeUndefined() // lands in the palette "custom" bucket
+    expect(agentKindMeta(created.kind).label).toBe('My Agent')
+  })
+})

package/app/stores/agents.ts

@@ -1,21 +1,96 @@
 import { defineStore } from 'pinia'
-import { ref } from 'vue'
-import { AGENT_ARCHETYPES, AGENT_BY_KIND, uid } from '~/utils/catalog'
+import { computed, ref, watch } from 'vue'
+import type { RemoteModuleManifest } from '@modular-vue/core'
+import { buildAgentCapabilitiesManifest, customKindToArchetype } from '~/modular/agent-kinds'
+import type { AppSlots } from '~/modular/slots'
+import {
+  AGENT_ARCHETYPES,
+  AGENT_BY_KIND,
+  setCustomAgentKindMeta,
+  SYSTEM_AGENT_META,
+  uid,
+} from '~/utils/catalog'
 import type { AgentArchetype, AgentKind, CustomAgentKind } 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.
+ * The agent palette catalog (slice 2 of the modular-vue adoption —
+ * docs/initiatives/modular-vue-adoption.md).
+ *
+ * Reactive union of three sources, none of which mutates the frozen built-in
+ * {@link AGENT_BY_KIND} const any more:
+ *  - the built-in archetypes (static);
+ *  - CONSUMER-shipped kinds contributed as CODE via the modular `agentKinds`
+ *    slot (`registerConsumerKinds`, fed once at boot from the resolved manifest);
+ *  - the deployment's BACKEND-registered kinds, modeled as a single
+ *    {@link RemoteModuleManifest} swapped per workspace snapshot
+ *    (`hydrateCustomKinds`) and read directly (single-active-manifest shape).
+ *
+ * The merged custom catalog is projected back into `catalog.ts`'s
+ * {@link setCustomAgentKindMeta} read-model so the pure `agentKindMeta` /
+ * `isKnownAgentKind` lookups (used across ~17 renderers) resolve a custom kind
+ * reactively without importing this store.
  */
 export const useAgentsStore = defineStore('agents', () => {
-  const archetypes = ref<AgentArchetype[]>([...AGENT_ARCHETYPES])
+  // CODE-shipped consumer kinds from the static `agentKinds` slot (fed once at
+  // boot by the modular install plugin — module slots are resolved once).
+  const consumerKinds = ref<CustomAgentKind[]>([])
+  // The active per-workspace capability manifest built from the snapshot's
+  // `customAgentKinds`, or null before the first hydrate.
+  const capabilitiesManifest = ref<RemoteModuleManifest<AppSlots> | null>(null)
+  // In-UI, client-only prototype agents created via the "add agent" modal.
+  const runtimeAgents = ref<AgentArchetype[]>([])
 
-  function get(kind: AgentKind) {
-    return AGENT_BY_KIND[kind]
+  /**
+   * The merged CUSTOM catalog (consumer-slot → backend-manifest → runtime), each
+   * mapped to display metadata, de-duplicated, and never shadowing a built-in or
+   * system kind. The old `registerCustomKinds` only guarded `AGENT_BY_KIND`; this
+   * intentionally ALSO drops any custom kind colliding with a `SYSTEM_AGENT_META`
+   * kind (`ci` / `merger` / `blueprints` / gates …), so a snapshot can't override an
+   * engine kind's palette entry either — matching `agentKindMeta`'s precedence
+   * (built-in → system → custom), where a colliding custom kind would never win anyway.
+   */
+  const customArchetypes = computed<AgentArchetype[]>(() => {
+    const seen = new Set<string>()
+    const out: AgentArchetype[] = []
+    const add = (a: AgentArchetype) => {
+      if (a.kind in AGENT_BY_KIND || a.kind in SYSTEM_AGENT_META || seen.has(a.kind)) return
+      seen.add(a.kind)
+      out.push(a)
+    }
+    for (const k of consumerKinds.value) add(customKindToArchetype(k))
+    for (const k of capabilitiesManifest.value?.slots?.agentKinds ?? [])
+      add(customKindToArchetype(k))
+    for (const a of runtimeAgents.value) add(a)
+    return out
+  })
+
+  /** The full palette: built-in archetypes + the merged custom ones. */
+  const archetypes = computed<AgentArchetype[]>(() => [
+    ...AGENT_ARCHETYPES,
+    ...customArchetypes.value,
+  ])
+
+  // Known-kind lookup (built-in ∪ system ∪ custom) for `get`.
+  const customByKind = computed<Record<string, AgentArchetype>>(() =>
+    Object.fromEntries(customArchetypes.value.map((a) => [a.kind, a])),
+  )
+
+  // Keep `catalog.ts`'s pure-util projection in sync with the merged custom
+  // catalog so `agentKindMeta` / `isKnownAgentKind` resolve custom kinds. Sync
+  // flush so an imperative read right after `hydrateCustomKinds` (e.g. the run
+  // dispatch resolving a custom kind's `resultView`) sees the fresh catalog with
+  // no tick gap. The watch lives in the store's effect scope (disposed with it).
+  watch(customByKind, (map) => setCustomAgentKindMeta(map), { immediate: true, flush: 'sync' })
+
+  /** Display metadata for a KNOWN kind (built-in / system / custom), else undefined. */
+  function get(kind: AgentKind): AgentArchetype | undefined {
+    return AGENT_BY_KIND[kind] ?? SYSTEM_AGENT_META[kind] ?? customByKind.value[kind]
   }
 
+  /**
+   * Add an in-UI prototype agent (the pipeline builder's "add agent" modal).
+   * Client-only, so it lives in store state — no backend, no global mutation.
+   */
   function addAgent(input: {
     label: string
     description?: string
@@ -30,36 +105,42 @@ export const useAgentsStore = defineStore('agents', () => {
       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)
+    runtimeAgents.value = [...runtimeAgents.value, archetype]
     return archetype
   }
 
   /**
-   * Merge the deployment's registered CUSTOM agent kinds (from the workspace snapshot)
-   * into the palette catalog: each becomes a first-class palette block + a kind-based
-   * lookup (so timelines / inspectors render it instead of the generic fallback), and its
-   * declared `resultView` opens through the same registry the built-ins use. Idempotent
-   * and built-in-safe — a kind already known (a built-in, or a prior load) is left
-   * untouched, so a snapshot can't shadow a built-in or duplicate on reload.
+   * Register the deployment's CODE-shipped consumer agent kinds — the resolved
+   * modular `agentKinds` slot, fed once by the install plugin. Idempotent
+   * replace (module slots resolve once, so this is called a single time).
    */
-  function registerCustomKinds(kinds: CustomAgentKind[]) {
-    for (const { kind, presentation } of kinds) {
-      if (AGENT_BY_KIND[kind]) continue
-      const archetype: AgentArchetype = {
-        kind,
-        label: presentation.label,
-        icon: presentation.icon,
-        color: presentation.color,
-        description: presentation.description,
-        ...(presentation.category ? { category: presentation.category } : {}),
-        ...(presentation.resultView ? { resultView: presentation.resultView } : {}),
-      }
-      AGENT_BY_KIND[kind] = archetype
-      archetypes.value.push(archetype)
-    }
+  function registerConsumerKinds(kinds: readonly CustomAgentKind[]) {
+    consumerKinds.value = [...kinds]
   }
 
-  return { archetypes, get, addAgent, registerCustomKinds }
+  /**
+   * Hydrate the deployment's BACKEND-registered custom kinds from a workspace
+   * snapshot, modeled as a single remote capability manifest (swapped wholesale
+   * per workspace). Replaces the old `registerCustomKinds` that mutated
+   * {@link AGENT_BY_KIND} directly.
+   *
+   * The snapshot re-delivers the same deployment kinds on every board refresh, so
+   * skip the swap — and the downstream projection invalidation of every
+   * `agentKindMeta` consumer — when the content-derived manifest version is
+   * unchanged. A genuinely different workspace's kinds change the version and swap.
+   */
+  function hydrateCustomKinds(kinds: CustomAgentKind[]) {
+    const next = buildAgentCapabilitiesManifest(kinds)
+    if (capabilitiesManifest.value?.version === next.version) return
+    capabilitiesManifest.value = next
+  }
+
+  return {
+    archetypes,
+    customArchetypes,
+    get,
+    addAgent,
+    registerConsumerKinds,
+    hydrateCustomKinds,
+  }
 })

package/app/stores/workspace.ts

@@ -168,9 +168,10 @@ export const useWorkspaceStore = defineStore(
       useInitiativesStore().hydratePresets(snapshot.initiativePresets)
       useTrackerStore().hydrate(snapshot.trackerSettings)
       useServicesStore().hydrate(snapshot.mounts ?? [], snapshot.serviceCatalog ?? [])
-      // Merge the deployment's registered custom agent kinds into the palette catalog so a
-      // proprietary kind renders as a first-class block + result view (idempotent on reload).
-      useAgentsStore().registerCustomKinds(snapshot.customAgentKinds ?? [])
+      // Hydrate the deployment's backend-registered custom agent kinds as the workspace's
+      // remote capability manifest, so a proprietary kind renders as a first-class palette
+      // block + result view. Swapped wholesale per workspace (no global-catalog mutation).
+      useAgentsStore().hydrateCustomKinds(snapshot.customAgentKinds ?? [])
       // The account's repo-sourced Claude Skills catalog (shared across its workspaces), so the
       // pipeline builder's per-step skill picker has its options. A straight replace.
       useSkillsStore().hydrate(snapshot.skills ?? [])

package/app/types/domain.ts

@@ -108,9 +108,10 @@ export interface AgentArchetype {
   category?: AgentCategory
   /**
    * Optional id of a DEDICATED result window this agent's step opens instead of the
-   * generic prose step-detail panel. Resolved through the result-view registry
-   * (`STEP_RESULT_VIEWS`) so any agent can declare a bespoke visualization without the
-   * renderer hardcoding a kind. Absent → the generic `AgentStepDetail` panel.
+   * generic prose step-detail panel. Resolved through the modular `resultViews` slot
+   * registry (`~/modular/result-views`, read by `StepResultViewHost`) so any agent —
+   * built-in or a consumer's — can declare a bespoke visualization without the renderer
+   * hardcoding a kind. Absent → the generic `AgentStepDetail` panel.
    */
   resultView?: string
 }