@cat-factory/app 0.133.0 → 0.134.0

package/app/components/panels/StepResultViewHost.vue

@@ -1,98 +1,60 @@
 <script setup lang="ts">
-// Universal dedicated-result-view host. An agent archetype can declare a `resultView`
-// id (see `~/utils/catalog`); when a step of that kind is opened, `ui.resultView` is set
-// and this host renders the matching registered window instead of the generic
-// `AgentStepDetail` prose panel. Adding a bespoke visualization for a new agent is just:
-//   1. declare `resultView: '<id>'` on its archetype, and
-//   2. register `'<id>': <Component>` below.
-// No caller changes — every board/inspector entry point already routes through
-// `ui` dispatch. Each registered window builds on `useResultView(viewId, { onOpen })`,
-// which owns the seam contract (open/blockId/close + Escape + load-on-open) so a new
-// window can't reintroduce the route-dependent empty-state bug by forgetting to fetch
-// on mount — declare an `onOpen` loader and it fires on every open.
-import { computed, type Component } from 'vue'
-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'
+// Universal dedicated-result-view host (slice 2 of the modular-vue adoption —
+// docs/initiatives/modular-vue-adoption.md). An agent archetype can declare a
+// `resultView` id (see `~/utils/catalog`); when a step of that kind is opened,
+// `ui.resultView` is set and this host mounts the matching registered window
+// instead of the generic `AgentStepDetail` prose panel.
+//
+// The registry is no longer a hardcoded `Record` here — every built-in window is
+// contributed to the modular `resultViews` slot (`~/modular/result-views`), and
+// a consumer deployment adds its OWN window to the SAME slot from a
+// `registerAppModule` module. This host reads the merged slot reactively via
+// `useReactiveSlots` and indexes it with `resolveComponentRegistry`; the kind's
+// (or custom kind's) `resultView` id selects the component. Adding a bespoke
+// visualization for a new agent is: declare `resultView: '<id>'` on its
+// archetype + contribute `{ id: '<id>', component }` to the `resultViews` slot.
+//
+// Each registered window builds on `useResultView(viewId, { onOpen })`, which
+// owns the seam contract (open/blockId/close + Escape + load-on-open) so a new
+// window can't reintroduce the route-dependent empty-state bug by forgetting to
+// fetch on mount.
+import { computed, watchEffect, type Component } from 'vue'
+import { useReactiveSlots } from '@modular-vue/runtime'
+import { pairById, resolveComponentRegistry } from '@modular-vue/core'
+import type { AppSlots } from '~/modular/slots'
 
 const ui = useUiStore()
+const agents = useAgentsStore()
+const slots = useReactiveSlots<AppSlots>()
 
-const STEP_RESULT_VIEWS: Record<string, 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 both polling gates (`ci` + `conflicts`); the window branches on agentKind.
-  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 from the inspector's "View
-  // Requirements" button. Not a pipeline-step view — opened directly via `ui.openServiceSpec`.
-  'service-spec': ServiceSpecWindow,
-  // The future-looking Follow-up companion: the Coder's surfaced loose ends / questions.
-  // Opened directly via `ui.openFollowUps` (the blinking chip + the `followup_pending` card).
-  'follow-ups': FollowUpWindow,
-  // The implementation-fork decision: the proposer's materially different approaches + the
-  // human's pick / custom approach. Opened directly via `ui.openForkDecision` (the pipeline
-  // chip, the inspector button, and the `fork_decision_pending` card).
-  'fork-decision': ForkDecisionWindow,
-  // The PR deep-review: the reviewer's sliced, prioritized findings + the human's multi-select.
-  // Opened as the `pr-reviewer` step's result view and via the `pr_review_ready` inbox card.
-  'pr-review': PrReviewWindow,
-  // The merger's verdict: the PR's complexity/risk/impact scores + the engine's auto-merge
-  // or awaiting-review decision (and why), instead of the agent's raw JSON.
-  merger: MergerResultView,
-  // The initiative tracker: phases, per-item status + PR links, decisions, deviations,
-  // caveats. Opened from the initiative card / inspector (`ui.openInitiativeTracker`) and
-  // as the planner step's result view.
-  'initiative-tracker': InitiativeTrackerWindow,
-  'initiative-planning': InitiativePlanningWindow,
-  // The interactive document-interview gate (WS5): the interviewer's clarifying questions +
-  // answer / continue / proceed, opened as the `doc-interviewer` step's result view.
-  'doc-interview': DocInterviewWindow,
-  // The Ralph loop: the persistent retry-until-done iteration history + the programmatic
-  // validation command + its latest exit code / output. Opened as the `ralph` step's view.
-  'ralph-loop': RalphLoopResultView,
-}
+// Index the merged `resultViews` slot into an id → component registry. Duplicate
+// ids throw by default (`resolveComponentRegistry`) — two modules claiming the
+// same view id is a wiring bug, not a silent last-wins. Recomputed if a consumer
+// module's contributions change (they don't after boot, but the read is cheap).
+const registry = computed(() => resolveComponentRegistry(slots.value.resultViews ?? []))
 
 const active = computed<Component | null>(() => {
   const view = ui.resultView?.view
   if (!view) return null
-  const component = STEP_RESULT_VIEWS[view] ?? null
-  // An archetype declared a `resultView` id with no registered component — this used to
-  // silently fall back to the prose panel. The backend now validates `resultView` against the
-  // canonical id set, so this should only fire mid-development of a new view; make it loud.
-  if (!component && import.meta.dev) {
-    console.warn(
-      `[StepResultViewHost] no component registered for resultView "${view}". ` +
-        `Add it to STEP_RESULT_VIEWS (and to RESULT_VIEW_IDS in @cat-factory/contracts).`,
-    )
-  }
-  return component
+  return registry.value.get(view) ?? null
 })
+
+// Dev guard: surface any CUSTOM kind whose declared `resultView` id resolves to
+// no registered component (a dangling reference — e.g. a backend kind naming a
+// consumer view this build doesn't ship). `pairById`'s `missing` bucket makes
+// the degradation explicit instead of a silent fall-through to the prose panel.
+if (import.meta.dev) {
+  watchEffect(() => {
+    const { missing } = pairById(agents.customArchetypes, registry.value, (a) => a.resultView)
+    if (missing.length) {
+      console.warn(
+        `[StepResultViewHost] custom agent kind(s) reference unregistered resultView id(s): ` +
+          missing.map((m) => `${m.item.kind}→${m.id}`).join(', ') +
+          `. Register a component for the id in a resultViews-slot module.`,
+      )
+    }
+  })
+}
 </script>
 
 <template>

package/app/modular/agent-kinds.spec.ts

@@ -0,0 +1,80 @@
+import { describe, expect, it } from 'vitest'
+import {
+  buildAgentCapabilitiesManifest,
+  capabilitiesManifestVersion,
+  customKindToArchetype,
+  WORKSPACE_CAPABILITIES_MANIFEST_ID,
+} from './agent-kinds'
+import type { AgentKind, CustomAgentKind } from '~/types/domain'
+
+const kind = (
+  over: Partial<CustomAgentKind['presentation']> = {},
+  kindId = 'acme-audit',
+): CustomAgentKind => ({
+  kind: kindId as AgentKind,
+  container: true,
+  presentation: {
+    label: 'Audit',
+    icon: 'i-lucide-shield',
+    color: '#fff',
+    description: 'd',
+    ...over,
+  },
+})
+
+describe('buildAgentCapabilitiesManifest', () => {
+  it('models the snapshot kinds as one remote capability manifest carrying the agentKinds slot', () => {
+    const kinds = [kind(), kind()]
+    const manifest = buildAgentCapabilitiesManifest(kinds)
+    expect(manifest.id).toBe(WORKSPACE_CAPABILITIES_MANIFEST_ID)
+    expect(manifest.slots?.agentKinds).toEqual(kinds)
+  })
+
+  it('copies the input (no aliasing of the caller array)', () => {
+    const kinds = [kind()]
+    const manifest = buildAgentCapabilitiesManifest(kinds)
+    kinds.push(kind())
+    expect(manifest.slots?.agentKinds).toHaveLength(1)
+  })
+
+  it('derives an identical version for identical content (so an unchanged re-hydrate no-ops)', () => {
+    // A fresh, structurally-equal kinds array (a new snapshot re-delivering the same kinds)
+    // must produce the same version — that's what lets `hydrateCustomKinds` skip the swap.
+    expect(buildAgentCapabilitiesManifest([kind()]).version).toBe(
+      buildAgentCapabilitiesManifest([kind()]).version,
+    )
+  })
+
+  it('changes the version when a display/pairing field or the kind set differs', () => {
+    const base = capabilitiesManifestVersion([kind()])
+    expect(capabilitiesManifestVersion([kind({ label: 'Renamed' })])).not.toBe(base)
+    expect(capabilitiesManifestVersion([kind({ resultView: 'acme:audit' })])).not.toBe(base)
+    expect(capabilitiesManifestVersion([kind({}, 'acme-other')])).not.toBe(base)
+    expect(capabilitiesManifestVersion([kind(), kind({}, 'acme-two')])).not.toBe(base)
+    expect(capabilitiesManifestVersion([])).not.toBe(base)
+  })
+})
+
+describe('customKindToArchetype', () => {
+  it('projects presentation onto the display archetype', () => {
+    expect(customKindToArchetype(kind())).toEqual({
+      kind: 'acme-audit',
+      label: 'Audit',
+      icon: 'i-lucide-shield',
+      color: '#fff',
+      description: 'd',
+    })
+  })
+
+  it('carries category and resultView through when present', () => {
+    const a = customKindToArchetype(kind({ category: 'review', resultView: 'acme:audit' }))
+    expect(a.category).toBe('review')
+    expect(a.resultView).toBe('acme:audit')
+  })
+
+  it('omits category/resultView when absent (no undefined keys)', () => {
+    const a = customKindToArchetype(kind())
+    expect('category' in a).toBe(false)
+    expect('resultView' in a).toBe(false)
+  })
+})

package/app/modular/agent-kinds.ts

@@ -0,0 +1,83 @@
+import type { RemoteModuleManifest } from '@modular-vue/core'
+import type { AgentArchetype, CustomAgentKind } from '~/types/domain'
+import type { AppSlots } from './slots'
+
+/**
+ * Custom agent kinds as remote capability manifests (slice 2 of the modular-vue
+ * adoption — docs/initiatives/modular-vue-adoption.md).
+ *
+ * A deployment's BACKEND-registered agent kinds arrive in the workspace snapshot
+ * as `customAgentKinds` (wire data). Rather than mutating a module-global
+ * catalog, they're modeled as a single {@link RemoteModuleManifest} whose
+ * `agentKinds` slot carries the data. cat-factory holds ONE active manifest per
+ * workspace (swapped on snapshot), so the agents store reads its `.slots`
+ * directly — the sanctioned single-active-manifest shape (the merge-many
+ * `mergeRemoteManifests` helper is for holding several manifests at once, which
+ * we don't). CODE-shipped consumer kinds instead enter via the static
+ * `agentKinds` slot (a `registerAppModule` module); the store merges both.
+ */
+
+/** The stable id for the per-workspace capability manifest built from the snapshot. */
+export const WORKSPACE_CAPABILITIES_MANIFEST_ID = 'cat-factory:workspace-capabilities'
+
+/**
+ * A deterministic, key-order-independent content signature of the custom kinds, used as the
+ * manifest `version`. The workspace snapshot re-delivers the SAME deployment-registered kinds on
+ * every board-event refresh (a full `workspace.refresh()` runs `hydrateCustomKinds` each time), so
+ * a content-derived version lets the store skip re-projecting an UNCHANGED catalog — otherwise
+ * every refresh would replace the `customAgentKindMeta` read-model and needlessly invalidate the
+ * ~17 `agentKindMeta` / `isKnownAgentKind` consumers. It still changes (and swaps wholesale) when a
+ * different workspace's kinds actually differ. Serialized as fixed-order tuples of only the fields
+ * that affect display/pairing, so a re-serialization with reordered object keys can't spuriously
+ * differ.
+ */
+export function capabilitiesManifestVersion(kinds: readonly CustomAgentKind[]): string {
+  return JSON.stringify(
+    kinds.map((k) => [
+      k.kind,
+      k.container,
+      k.presentation.label,
+      k.presentation.icon,
+      k.presentation.color,
+      k.presentation.description,
+      k.presentation.category ?? null,
+      k.presentation.resultView ?? null,
+    ]),
+  )
+}
+
+/**
+ * Model the snapshot's `customAgentKinds` as a single remote capability manifest. The `version` is
+ * a {@link capabilitiesManifestVersion content signature} so identical snapshots produce an
+ * identical manifest — which `useAgentsStore().hydrateCustomKinds` uses to no-op an unchanged
+ * re-hydrate. Swapped wholesale (not diffed) when the content genuinely changes.
+ */
+export function buildAgentCapabilitiesManifest(
+  kinds: readonly CustomAgentKind[],
+): RemoteModuleManifest<AppSlots> {
+  return {
+    id: WORKSPACE_CAPABILITIES_MANIFEST_ID,
+    version: capabilitiesManifestVersion(kinds),
+    slots: { agentKinds: [...kinds] },
+  }
+}
+
+/**
+ * Project a wire `CustomAgentKind` onto the frontend's display `AgentArchetype`
+ * (icon/label/color/description + optional category/resultView). The inverse of
+ * the backend `agentPresentationSchema` — the SAME mapping the removed
+ * `registerCustomKinds` did inline, now pure and shared by the consumer-slot and
+ * backend-manifest paths.
+ */
+export function customKindToArchetype(kind: CustomAgentKind): AgentArchetype {
+  const { presentation: p } = kind
+  return {
+    kind: kind.kind,
+    label: p.label,
+    icon: p.icon,
+    color: p.color,
+    description: p.description,
+    ...(p.category ? { category: p.category } : {}),
+    ...(p.resultView ? { resultView: p.resultView } : {}),
+  }
+}

package/app/modular/nav-contributions.spec.ts

@@ -45,7 +45,7 @@ const ALL_GATES: NavGates = {
   isAccountAdmin: true,
 }
 
-const slots = (): AppSlots => ({ nav: [...NAV_CONTRIBUTIONS] })
+const slots = (): AppSlots => ({ nav: [...NAV_CONTRIBUTIONS], resultViews: [], agentKinds: [] })
 const ids = (s: unknown) => (s as AppSlots).nav.map((i) => i.id)
 
 describe('navSlotFilter', () => {

package/app/modular/nav-contributions.ts

@@ -1,4 +1,11 @@
 import { defineModule } from '@modular-vue/core'
+import type { AppSlots } from './slots'
+
+// Re-exported for the slice-1 importers that reach `AppSlots` through this
+// module (`useNavContributions`, `registry`, the nav specs); its canonical home
+// is now `./slots`, where all slot keys are aggregated (slice 2 added
+// `resultViews` / `agentKinds`).
+export type { AppSlots } from './slots'
 
 /**
  * The single nav/command catalog for the layer (slice 1 of the modular-vue
@@ -121,17 +128,6 @@ export interface NavContribution {
   toolbar?: { order: number }
 }
 
-/**
- * The layer's slot map. Consumer modules contribute to the same `nav` key. The
- * index signature is mutable (`unknown[]`) to satisfy the runtime's `SlotMap`
- * constraint; `unknown[]` still satisfies `useReactiveSlots`' `readonly unknown[]`
- * bound, so both the install and the read side accept it.
- */
-export interface AppSlots {
-  nav: NavContribution[]
-  [key: string]: unknown[]
-}
-
 const S = (...s: NavSurface[]) => s as readonly NavSurface[]
 
 /**

package/app/modular/registry.spec.ts

@@ -41,6 +41,44 @@ describe('app modular registry', () => {
     expect(() => createAppRegistry({ gates: NO_GATES }).resolveManifest()).toThrow(/duplicate/i)
   })
 
+  it('merges consumer-contributed result-view + agent-kind slots (slice-2 extensibility)', () => {
+    // A deployment ships its OWN dedicated window AND its custom agent kind through the
+    // same slots the first-party modules use — no layer fork. A fake component (plain
+    // object) stands in for the SFC so this stays a pure registry test.
+    const fakeComponent = { name: 'AcmeReportWindow' }
+    registerAppModule(
+      defineModule({
+        id: 'consumer:acme',
+        version: '1.0.0',
+        slots: {
+          resultViews: [{ id: 'acme:report', component: fakeComponent }],
+          agentKinds: [
+            {
+              kind: 'acme-audit',
+              container: true,
+              presentation: {
+                label: 'Acme Audit',
+                icon: 'i-lucide-shield',
+                color: '#fff',
+                description: 'd',
+                resultView: 'acme:report',
+              },
+            },
+          ],
+        },
+      }),
+    )
+
+    const slots = createAppRegistry({ gates: NO_GATES }).resolveManifest().slots as {
+      resultViews: { id: string }[]
+      agentKinds: { kind: string; presentation: { resultView?: string } }[]
+    }
+    expect(slots.resultViews.map((v) => v.id)).toContain('acme:report')
+    const audit = slots.agentKinds.find((k) => k.kind === 'acme-audit')
+    // The custom kind's resultView id pairs against the consumer's own registered component.
+    expect(audit?.presentation.resultView).toBe('acme:report')
+  })
+
   it('merges a consumer-contributed nav item into the resolved nav slot', () => {
     // A deployment extending the layer contributes its own nav destination to the
     // SAME `nav` slot the first-party module fills — it then renders in every shell

package/app/modular/registry.ts

@@ -2,7 +2,8 @@ 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 { AppSlots, NavGates } 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
@@ -70,23 +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. The `nav` slot default is seeded empty so the
- * key always exists even before any module (or with only consumer modules)
- * contributes.
+ * `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(deps: AppDeps): ModuleRegistry<AppDeps, AppSlots> {
+export function createAppRegistry(
+  deps: AppDeps,
+  extraModules: readonly AnyModuleDescriptor[] = [],
+): ModuleRegistry<AppDeps, AppSlots> {
   const registry = createRegistry<AppDeps, AppSlots>({
     services: { gates: deps.gates },
-    slots: { nav: [] },
+    slots: { nav: [], resultViews: [], agentKinds: [] },
   })
-  for (const mod of [...FIRST_PARTY_MODULES, ...consumerModules]) {
+  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,7 +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
@@ -26,15 +30,34 @@ import { createNavGates } from '~/modular/nav-gates'
  * 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({ gates: createNavGates() })
+    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
 }

package/app/utils/catalog.ts

@@ -1,3 +1,4 @@
+import { shallowRef } from 'vue'
 import type {
   AgentArchetype,
   AgentCategory,
@@ -304,10 +305,44 @@ export function isProducerCompanion(kind: string): boolean {
   return COMPANION_KINDS.has(kind)
 }
 
-export const AGENT_BY_KIND: Record<AgentKind, AgentArchetype> = Object.fromEntries(
-  [...AGENT_ARCHETYPES, ...COMPANION_ARCHETYPES].map((a) => [a.kind, a]),
+/**
+ * The BUILT-IN palette + companion catalog, keyed by kind. Frozen and never
+ * mutated: custom (deployment/consumer) kinds no longer reach into this const —
+ * they flow through the modular `agentKinds` slot / the workspace-capability
+ * remote manifest and land in {@link customAgentKindMeta} instead (slice 2 of
+ * the modular-vue adoption). Freezing turns any stray write into a loud runtime
+ * error rather than silently conflating built-ins with custom kinds.
+ */
+export const AGENT_BY_KIND: Record<AgentKind, AgentArchetype> = Object.freeze(
+  Object.fromEntries([...AGENT_ARCHETYPES, ...COMPANION_ARCHETYPES].map((a) => [a.kind, a])),
 ) as Record<AgentKind, AgentArchetype>
 
+/**
+ * Reactive read-model of the deployment's CUSTOM agent kinds (consumer-slot +
+ * backend remote-manifest), kept in sync by the agents store from the resolved
+ * modular `agentKinds` slot. The slot/manifest is the source of truth; this
+ * `shallowRef` is its synchronous projection so the pure kind-meta lookups below
+ * ({@link agentKindMeta} / {@link isKnownAgentKind}) resolve a custom kind — and
+ * re-render when the catalog changes — WITHOUT importing the store (which would
+ * be circular) or mutating {@link AGENT_BY_KIND}. Empty until the store first
+ * populates it, so an unknown custom kind degrades to the generic fallback,
+ * exactly as before registration.
+ */
+const customAgentKindMeta = shallowRef<Record<string, AgentArchetype>>({})
+
+/**
+ * Replace the custom-kind projection (called only by the agents store, whenever
+ * its merged custom catalog changes). Whole-map replace, not per-key mutation.
+ */
+export function setCustomAgentKindMeta(map: Record<string, AgentArchetype>): void {
+  customAgentKindMeta.value = map
+}
+
+/** Test-only: clear the custom-kind projection so a spec starts from built-ins only. */
+export function __resetCustomAgentKindMetaForTest(): void {
+  customAgentKindMeta.value = {}
+}
+
 /**
  * Agent kinds eligible for the optional consensus mechanism (the pipeline builder shows an
  * "Enable Consensus" toggle for these). Mirrors the backend default-eligible set assigned by
@@ -596,30 +631,36 @@ const FALLBACK_AGENT_META: Omit<AgentArchetype, 'kind'> = {
 }
 
 /**
- * Resolve display metadata for ANY agent kind — a palette archetype (incl. custom
- * agents registered into {@link AGENT_BY_KIND}), an engine system kind, or an
- * unknown one — ALWAYS returning a usable icon/label/color. This is the single
- * lookup every pipeline / run renderer should use so a kind missing from the
- * archetype map (e.g. `ci`/`merger`/`blueprints` in a seeded pipeline) can never
- * blow up a component with an undefined access.
+ * Resolve display metadata for ANY agent kind — a built-in palette archetype
+ * ({@link AGENT_BY_KIND}), an engine system kind ({@link SYSTEM_AGENT_META}), a
+ * deployment CUSTOM kind (projected from the modular `agentKinds` slot into
+ * {@link customAgentKindMeta} by the agents store), or an unknown one — ALWAYS
+ * returning a usable icon/label/color. This is the single lookup every pipeline
+ * / run renderer should use so a kind missing from the archetype map (e.g.
+ * `ci`/`merger`/`blueprints` in a seeded pipeline) can never blow up a component
+ * with an undefined access. Reading `customAgentKindMeta` reactively means a
+ * component computed re-runs when the custom catalog changes.
  */
 export function agentKindMeta(kind: string): AgentArchetype {
   return (
     AGENT_BY_KIND[kind as AgentKind] ??
-    SYSTEM_AGENT_META[kind] ?? { kind: kind as AgentKind, ...FALLBACK_AGENT_META }
+    SYSTEM_AGENT_META[kind] ??
+    customAgentKindMeta.value[kind] ?? { kind: kind as AgentKind, ...FALLBACK_AGENT_META }
   )
 }
 
 /**
- * Whether an agent kind is actually known to this build — a palette archetype or companion
- * ({@link AGENT_BY_KIND}, which deployment custom kinds are merged into via
- * `useAgentsStore().registerCustomKinds`), or an engine system/gate kind
- * ({@link SYSTEM_AGENT_META}). Unlike {@link agentKindMeta} (which always returns a usable
- * fallback so renderers never crash), this returns `false` for an unknown kind — used to flag
- * a pipeline that references a nonexistent agent. Call AFTER custom kinds are registered.
+ * Whether an agent kind is actually known to this build — a built-in palette
+ * archetype or companion ({@link AGENT_BY_KIND}), an engine system/gate kind
+ * ({@link SYSTEM_AGENT_META}), or a deployment CUSTOM kind projected from the
+ * modular `agentKinds` slot ({@link customAgentKindMeta}). Unlike
+ * {@link agentKindMeta} (which always returns a usable fallback so renderers
+ * never crash), this returns `false` for an unknown kind — used to flag a
+ * pipeline that references a nonexistent agent. Call AFTER the workspace
+ * snapshot has hydrated the custom kinds.
  */
 export function isKnownAgentKind(kind: string): boolean {
-  return kind in AGENT_BY_KIND || kind in SYSTEM_AGENT_META
+  return kind in AGENT_BY_KIND || kind in SYSTEM_AGENT_META || kind in customAgentKindMeta.value
 }
 
 type BlockTypeMeta = { label: string; icon: string; accent: string }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cat-factory/app",
-  "version": "0.133.0",
+  "version": "0.134.0",
   "description": "Reusable Nuxt layer for the Agent Architecture Board SPA (components, stores, composables, pages). Consume it from a thin deployment app via `extends: ['@cat-factory/app']` and point it at your backend with NUXT_PUBLIC_API_BASE. See deploy/frontend for an example.",
   "repository": {
     "type": "git",
@@ -18,8 +18,8 @@
     "access": "public"
   },
   "dependencies": {
-    "@modular-frontend/core": "^0.1.0",
-    "@modular-vue/core": "^1.0.1",
+    "@modular-frontend/core": "^0.2.0",
+    "@modular-vue/core": "^1.1.0",
     "@modular-vue/nuxt": "^0.1.1",
     "@modular-vue/runtime": "^1.1.0",
     "@modular-vue/vue": "^1.1.0",
@@ -39,7 +39,7 @@
     "valibot": "^1.4.2",
     "vue": "3.5.40",
     "wretch": "^3.0.9",
-    "@cat-factory/contracts": "0.147.1"
+    "@cat-factory/contracts": "0.148.0"
   },
   "devDependencies": {
     "@toad-contracts/testing": "0.3.2",