@cat-factory/app 0.133.0 → 0.135.0

package/app/modular/journeys/persistence.spec.ts

@@ -0,0 +1,68 @@
+import { describe, expect, it } from 'vitest'
+import type { SerializedJourney } from '@modular-vue/journeys'
+import { catFactoryJourneyPersistence, useJourneyPersistenceStore } from './persistence'
+
+// The Pinia-backed journey persistence adapter (slice 3). This is what makes a
+// modal-hosted wizard RESUME on reopen: `keyFor` scopes the stored blob, `save`
+// records it, `load` returns it (so `runtime.start()` rehydrates instead of
+// minting fresh), and `remove` drops it on completion. A fresh Pinia is installed
+// per test by `test/setup.ts`.
+
+interface FrameInput {
+  frameId: string | null
+}
+
+type FrameState = { frameId: string | null }
+
+function blob(step: string): SerializedJourney<FrameState> {
+  // Minimal plain-JSON blob — the adapter only stores/round-trips it (JSON clone),
+  // it never interprets the shape, so a representative object suffices.
+  return {
+    journeyId: 'environment-setup',
+    version: '1.0.0',
+    state: { frameId: 'blk_1' },
+    step,
+  } as unknown as SerializedJourney<FrameState>
+}
+
+describe('catFactoryJourneyPersistence', () => {
+  const persistence = catFactoryJourneyPersistence<FrameInput, { frameId: string | null }>(
+    ({ journeyId, input }) => `${journeyId}:${input.frameId ?? 'new'}`,
+  )
+
+  it('derives a deterministic, frame-scoped key', () => {
+    expect(
+      persistence.keyFor({ journeyId: 'environment-setup', input: { frameId: 'blk_1' } }),
+    ).toBe('environment-setup:blk_1')
+    expect(persistence.keyFor({ journeyId: 'environment-setup', input: { frameId: null } })).toBe(
+      'environment-setup:new',
+    )
+  })
+
+  it('round-trips save → load and detaches the loaded blob from the store', () => {
+    const key = 'environment-setup:blk_1'
+    persistence.save(key, blob('review'))
+
+    // Persisted under that key in the Pinia store.
+    expect(useJourneyPersistenceStore().journeys[key]).toMatchObject({ step: 'review' })
+
+    const loaded = persistence.load(key)
+    expect(loaded).toMatchObject({ step: 'review', state: { frameId: 'blk_1' } })
+    // Cloned, not the live store reference (mutating the load can't corrupt state).
+    expect(loaded).not.toBe(useJourneyPersistenceStore().journeys[key])
+  })
+
+  it('returns null for an unknown key (a fresh start)', () => {
+    expect(persistence.load('environment-setup:never-saved')).toBeNull()
+  })
+
+  it('removes a blob on completion so the next start is fresh', () => {
+    const key = 'environment-setup:blk_9'
+    persistence.save(key, blob('save'))
+    expect(persistence.load(key)).not.toBeNull()
+
+    persistence.remove(key)
+    expect(persistence.load(key)).toBeNull()
+    expect(useJourneyPersistenceStore().journeys[key]).toBeUndefined()
+  })
+})

package/app/modular/journeys/persistence.ts

@@ -0,0 +1,58 @@
+import { defineStore } from 'pinia'
+import { ref } from 'vue'
+import type { SerializedJourney } from '@modular-vue/journeys'
+import { createPiniaJourneyPersistence } from '@modular-vue/journeys'
+
+/**
+ * Pinia-backed journey persistence (slice 3 of the modular-vue adoption —
+ * docs/initiatives/modular-vue-adoption.md).
+ *
+ * A journey's `persistence` adapter is what makes `runtime.start()` mean
+ * RESUME: it probes `keyFor(input)` for an in-flight serialized instance and
+ * returns it instead of minting a fresh one, so a modal-hosted wizard that is
+ * closed and reopened for the same target picks up exactly where it left off
+ * (see `JourneyHost`'s start-means-resume contract).
+ *
+ * We route that through Pinia (via the upstream `createPiniaJourneyPersistence`,
+ * the Vue-ecosystem analogue of `createWebStoragePersistence`) rather than a
+ * bespoke store: in-flight journeys then participate in the app's existing Pinia
+ * devtools/timeline, and one `store.$reset()` drops every persisted journey
+ * through a path the app already owns. The binding takes NO `pinia` dependency —
+ * the caller (this file) brings the store.
+ *
+ * Scope is deliberately in-memory / session-only: it survives a modal
+ * close→reopen within a session (the demonstrable resume win) but is not wired
+ * through `pinia-plugin-persistedstate`, so a full page reload starts fresh.
+ * Reload recovery is a later opt-in — a wizard's serialized blob can reference
+ * transient run ids that a cross-reload resume would need to re-validate.
+ */
+
+/**
+ * The single store that owns every wizard journey's serialized blob, keyed by
+ * the per-journey `keyFor`. `SerializedJourney` is plain JSON by construction,
+ * so the record is trivially (de)serializable.
+ */
+export const useJourneyPersistenceStore = defineStore('journeyPersistence', () => {
+  const journeys = ref<Record<string, SerializedJourney>>({})
+  return { journeys }
+})
+
+/**
+ * Build a Pinia-backed `JourneyPersistence` for a journey, keyed by `keyFor`.
+ * Pass the result as a journey registration's `persistence` option. The `store`
+ * is a lazy getter so the adapter can be constructed at module-eval time (before
+ * any Pinia scope exists) and only resolves the store when the runtime actually
+ * loads/saves — inside the client plugin, where Pinia is active.
+ *
+ * `keyFor` MUST be deterministic for identical input (it's the resume probe
+ * key); scope it to the wizard's target (e.g. the service frame id) so reopening
+ * the same target resumes and a different target is a fresh flow.
+ */
+export function catFactoryJourneyPersistence<TInput, TState>(
+  keyFor: (ctx: { journeyId: string; input: TInput }) => string,
+) {
+  return createPiniaJourneyPersistence<TInput, TState>({
+    keyFor,
+    store: () => useJourneyPersistenceStore(),
+  })
+}

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

@@ -1,8 +1,9 @@
 import type { AnyModuleDescriptor } from '@modular-vue/core'
 import { createRegistry } from '@modular-vue/runtime'
-import type { ModuleRegistry } from '@modular-vue/runtime'
+import { journeysPlugin } from '@modular-vue/journeys'
 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,39 @@ 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[] = [],
+) {
+  // `.use(journeysPlugin())` attaches the journeys extension (slice 3): the returned
+  // registry gains `registerJourney(...)` and the resolved manifest exposes the
+  // `JourneyRuntime` at `extensions.journeys`, which the client plugin provides to the
+  // Vue app. The plugin itself carries no `.vue` imports, so it's safe in this
+  // unit-tested import graph; the journeys + their step modules (which DO import SFCs)
+  // are registered from the client plugin via `extraModules` + `registerJourney`.
   const registry = createRegistry<AppDeps, AppSlots>({
     services: { gates: deps.gates },
-    slots: { nav: [] },
-  })
-  for (const mod of [...FIRST_PARTY_MODULES, ...consumerModules]) {
+    slots: { nav: [], resultViews: [], agentKinds: [] },
+  }).use(journeysPlugin())
+  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,20 @@
 import { installModularApp } from '@modular-vue/nuxt/runtime'
+import type { ApplicationManifest } from '@modular-vue/runtime'
+import type { NavigationItem } from '@modular-frontend/core'
+import { resolveComponentRegistry } from '@modular-vue/core'
+import { provideJourneyRuntime } from '@modular-vue/journeys'
+import type { JourneyRuntime } from '@modular-vue/journeys'
 import { createAppRegistry } from '~/modular/registry'
 import { navSlotFilter } from '~/modular/nav-contributions'
 import { createNavGates } from '~/modular/nav-gates'
+import { resultViewsModule } from '~/modular/result-views'
+import {
+  environmentSetupJourney,
+  environmentSetupModule,
+  environmentSetupPersistence,
+} from '~/modular/journeys/environmentSetup'
+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 +39,58 @@ 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 manifest = installModularApp({ vueApp: nuxtApp.vueApp, $router: useRouter() }, registry, {
-      slotFilter: navSlotFilter,
+    // Register the step-module carriers (they import `.vue`, so they enter via
+    // `extraModules`, keeping the unit-tested `registry.ts` graph SFC-free) and the
+    // journeys themselves (slice 3). `registerJourney` must run BEFORE the manifest
+    // resolves (inside `installModularApp`).
+    const registry = createAppRegistry({ gates: createNavGates() }, [
+      resultViewsModule,
+      environmentSetupModule,
+    ])
+    registry.registerJourney(environmentSetupJourney, {
+      persistence: environmentSetupPersistence,
     })
+    // The annotation is still required to break `defineNuxtPlugin`'s self-referential
+    // return inference (the plugin provides `modular: manifest`, so an un-annotated
+    // `manifest` resolves to `any` — TS7022). But since `@modular-vue/nuxt@0.3.0` now
+    // FLOWS the registry's plugin-extension type through `installModularApp`, the
+    // annotation can name the real `{ journeys: JourneyRuntime }` extension and TS
+    // VERIFIES the `journeysPlugin` actually resolved it (pre-0.3.0 erased `TExtensions`
+    // to `unknown`, so the extension had to be recovered with an unchecked
+    // `as JourneyRuntime` cast). `manifest.journeys` / `manifest.slots` are now typed,
+    // so the downstream casts are gone too.
+    const manifest: ApplicationManifest<AppSlots, NavigationItem, { journeys: JourneyRuntime }> =
+      installModularApp({ vueApp: nuxtApp.vueApp, $router: useRouter() }, registry, {
+        slotFilter: navSlotFilter,
+      })
+    // Provide the resolved `JourneyRuntime` to the Vue app so `<JourneyProvider>` /
+    // `<JourneyHost>` / `<JourneyOutlet>` resolve it from context (the wizard hosts
+    // don't hand-thread a runtime).
+    provideJourneyRuntime(nuxtApp.vueApp, manifest.journeys)
+    const slots = manifest.slots
+    // 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')
+  })
+})