@cat-factory/app 0.152.0 → 0.153.0

package/app/components/panels/AppOverlayHost.logic.spec.ts

@@ -0,0 +1,38 @@
+import { describe, it, expect } from 'vitest'
+import { selectOverlay } from './AppOverlayHost.logic'
+import type { OverlayContribution } from '~/modular/slots'
+
+/**
+ * The pure selection behind `<AppOverlayHost>` (extension slice D — the frontend-extension-mechanism
+ * initiative). Pins the resilience the seam advertises: a matching id mounts its component, a
+ * dangling open (no registered component) degrades to nothing (`missing: true`, the host's dev-warn
+ * signal), no open renders nothing, and duplicate ids fail fast (the boot guard's contract).
+ */
+// A plain object stands in for the SFC — `selectOverlay` only ever keys by id.
+const overlay = (id: string): OverlayContribution => ({ id, component: { name: id } as never })
+
+describe('selectOverlay (AppOverlayHost slice D)', () => {
+  it('returns nothing when no overlay is open (null / undefined id)', () => {
+    const overlays = [overlay('acme:security-dashboard-overlay')]
+    expect(selectOverlay(overlays, null)).toEqual({ component: null, missing: false })
+    expect(selectOverlay(overlays, undefined)).toEqual({ component: null, missing: false })
+  })
+
+  it('picks the component whose id matches the active overlay', () => {
+    const entry = overlay('acme:security-dashboard-overlay')
+    const { component, missing } = selectOverlay([entry], 'acme:security-dashboard-overlay')
+    expect(component).toBe(entry.component)
+    expect(missing).toBe(false)
+  })
+
+  it('degrades a dangling open to nothing and flags it missing (no crash)', () => {
+    const { component, missing } = selectOverlay([overlay('acme:one')], 'acme:gone')
+    expect(component).toBeNull()
+    expect(missing).toBe(true)
+  })
+
+  it('fails fast on duplicate overlay ids (the boot guard contract)', () => {
+    const dupes = [overlay('acme:dup'), overlay('acme:dup')]
+    expect(() => selectOverlay(dupes, 'acme:dup')).toThrow()
+  })
+})

package/app/components/panels/AppOverlayHost.logic.ts

@@ -0,0 +1,24 @@
+import type { Component } from 'vue'
+import { resolveComponentRegistry } from '@modular-vue/core'
+import type { OverlayContribution } from '~/modular/slots'
+
+/**
+ * Pure selection for `<AppOverlayHost>` (extension slice D). Indexes the merged `appOverlays`
+ * slot into an id → component registry (`resolveComponentRegistry` — the same pick-one primitive
+ * `StepResultViewHost` uses; duplicate ids throw, as validated once at boot) and picks the entry
+ * matching the active overlay id.
+ *
+ * Kept side-effect-free — the host's dev-warn for a dangling open lives in a `watchEffect`, not
+ * here — so both the host's `computed` and the unit spec can call it. `missing` is the explicit
+ * dangling-open signal (an id with no registered component, e.g. a stale nav closure after an
+ * extension was removed): the host degrades that to nothing rather than crashing.
+ */
+export function selectOverlay(
+  overlays: OverlayContribution[],
+  activeId: string | null | undefined,
+): { component: Component | null; missing: boolean } {
+  if (!activeId) return { component: null, missing: false }
+  const registry = resolveComponentRegistry(overlays)
+  const component = (registry.get(activeId) as Component | undefined) ?? null
+  return { component, missing: !component }
+}

package/app/components/panels/AppOverlayHost.vue

@@ -0,0 +1,57 @@
+<script setup lang="ts">
+// Universal CONSUMER-overlay host (extension slice D — the frontend-extension-mechanism
+// initiative, docs/initiatives/frontend-extension-mechanism.md). The one top-level surface a
+// consumer deployment could not extend before: `pages/index.vue` hand-mounts every first-party
+// modal as a `v-if`, so a consumer nav item's `run` closure had nothing to open. This host is
+// the seam — a deployment registers `{ id: '<ns>:<name>', component }` in the `appOverlays` slot
+// and opens it with `ui.openOverlay(id, subject?)` (usually via `useAppOverlays().open(...)`).
+//
+// The mechanism is the same slice-2 pick-one primitive `StepResultViewHost` uses: index the
+// merged `appOverlays` slot into an id → component registry via `resolveComponentRegistry`, and
+// mount the entry whose id matches the active `ui.activeOverlay` pointer. Only ONE consumer
+// overlay is open at a time. The mounted overlay receives the optional `subject` as a prop and
+// emits `close` (the consumer overlay composes `ResultWindowShell` / `useModalBehavior` for its
+// own chrome, so Escape/backdrop/focus-trap are inherited — see the consumer-extensions guide).
+//
+// First-party modals stay hand-mounted in `index.vue`; this seam is deliberately scoped to
+// consumer extensions (strangler discipline — the ~34 existing lazy modals are not migrated).
+import { computed, watchEffect, type Component } from 'vue'
+import { useReactiveSlots } from '@modular-vue/runtime'
+import type { AppSlots } from '~/modular/slots'
+import { selectOverlay } from './AppOverlayHost.logic'
+
+const ui = useUiStore()
+const slots = useReactiveSlots<AppSlots>()
+
+// Pick the component for the active overlay id via the pure `selectOverlay` helper (indexes the
+// merged `appOverlays` slot with `resolveComponentRegistry`; duplicate ids throw, validated once
+// at boot in `modular.client.ts`). Recomputed if a consumer module's contributions change (they
+// don't after boot, but the read is cheap).
+const selection = computed(() => selectOverlay(slots.value.appOverlays ?? [], ui.activeOverlay?.id))
+const active = computed<Component | null>(() => selection.value.component)
+
+// Dev guard: a dangling open (`openOverlay('acme:x')` with no registered component — e.g. a stale
+// nav closure after an extension was removed) degrades to nothing rather than crashing. Kept in a
+// `watchEffect` — not the `computed` above — so the selection stays side-effect-free, mirroring
+// `StepResultViewHost`.
+if (import.meta.dev) {
+  watchEffect(() => {
+    if (selection.value.missing) {
+      const id = ui.activeOverlay?.id
+      console.warn(
+        `[AppOverlayHost] ui.openOverlay('${id}') has no registered component. ` +
+          `Contribute { id: '${id}', component } to the appOverlays slot in a registerAppModule module.`,
+      )
+    }
+  })
+}
+</script>
+
+<template>
+  <component
+    :is="active"
+    v-if="active"
+    :subject="ui.activeOverlay?.subject"
+    @close="ui.closeOverlay()"
+  />
+</template>

package/app/composables/useAppOverlays.ts

@@ -0,0 +1,26 @@
+import { computed } from 'vue'
+
+/**
+ * The public seam a consumer deployment uses to open its own top-level overlays (extension
+ * slice D — the frontend-extension-mechanism initiative). A deployment contributes an overlay
+ * component to the `appOverlays` slot (`{ id: '<ns>:<name>', component }`) and opens it from a
+ * nav item's `run` closure (or any consumer code) with `useAppOverlays().open('<ns>:<name>')`.
+ * The single `<AppOverlayHost>` in `pages/index.vue` resolves the slot and mounts the matching
+ * component, handing it the optional `subject`.
+ *
+ * This is a thin, auto-imported wrapper over the `ui` store's overlay pointer so a consumer
+ * never has to reach into the layer's Pinia stores directly — the same decoupling the rest of
+ * the consumer surface follows (auto-imported composables + `#components`, no deep layer
+ * imports). Opening a second overlay replaces the first (a pick-one host).
+ */
+export function useAppOverlays() {
+  const ui = useUiStore()
+  return {
+    /** The active consumer overlay (`{ id, subject? }`) or null when none is open. */
+    active: computed(() => ui.activeOverlay),
+    /** Open the `appOverlays`-slot overlay with this id, optionally passing it a subject. */
+    open: (id: string, subject?: unknown) => ui.openOverlay(id, subject),
+    /** Close the active consumer overlay. */
+    close: () => ui.closeOverlay(),
+  }
+}

package/app/docs/consumer-extensions.md

@@ -69,6 +69,7 @@ export default defineNuxtPlugin(() => {
 | Custom task types                   | `taskTypes`       | `{ taskType: '<ns>:<name>', presentation, fields?, defaultPipelineId?, formPanel? }`             | `AddTaskModal` picker/fields + `TaskCard` badge (via `taskTypeMeta`) |
 | Sidebar / command-palette / toolbar | `nav`             | `{ id, labelKey, icon, surfaces, gate?, run, sidebar?, command?, toolbar? }`                     | the three shells via `useNavContributions`                           |
 | Inspector body panels               | `inspectorPanels` | `{ id, component, when(block), order }` (`PanelEntry<Block>`)                                    | `<PanelsOutlet>` in `InspectorPanel`                                 |
+| Top-level overlays                  | `appOverlays`     | `{ id: '<ns>:<name>', component }`                                                               | `<AppOverlayHost>` via `useAppOverlays().open(id)`                   |
 | Multi-step wizards                  | (journeys)        | `registerJourney` + step modules                                                                 | `<JourneyHost>` / `<JourneyOutlet>`                                  |
 | Locale strings                      | (i18n)            | `i18n/locales/*.json` in the deployment                                                          | `@nuxtjs/i18n` layer deep-merge                                      |
 
@@ -135,6 +136,33 @@ task created with it round-trips with zero host edits.
 > silently — the type just won't pre-select a pipeline and an unpaired `formPanel` degrades to the
 > descriptor `fields`. Prefer backend registration when you want the fail-fast guardrail.
 
+### Top-level overlays (`appOverlays`)
+
+A nav item's `run` closure — or any consumer code — often needs to open a full-screen panel of
+its own: a dashboard, a wizard, a settings surface. The layer's first-party modals are
+hand-mounted in `pages/index.vue`, which a consumer can't edit, so the `appOverlays` slot + the
+single `<AppOverlayHost>` are the seam:
+
+1. Contribute `{ id: '<ns>:<name>', component }` to the `appOverlays` slot (see
+   `acme:security-dashboard-overlay` in the example module).
+2. Open it from anywhere with the auto-imported `useAppOverlays().open('<ns>:<name>', subject?)`
+   — typically a nav item's `run` closure. The optional `subject` is any value your overlay
+   renders against (e.g. a block id); it reaches the component as a `subject` prop.
+3. `<AppOverlayHost>` resolves the slot with `resolveComponentRegistry` (the same pick-one
+   primitive `resultViews` uses) and mounts the matching component, wiring its `close` emit to
+   `useAppOverlays().close()`.
+
+It is a **pick-one** host: opening a second overlay replaces the first, and `close()` clears it.
+Compose the shared `ResultWindowShell` (via `#components`) for chrome so your overlay inherits
+focus-trap / scroll-lock / shared-stack Escape — emit `close` from its `@close`. A dangling open
+(`open('<ns>:x')` with no registered component — e.g. a stale closure after the extension was
+removed) degrades to nothing (a dev-console warning names the id), never a crash. Duplicate ids
+across modules throw at boot, like every other slot.
+
+> **Scope.** This seam is for CONSUMER overlays. The layer's own ~34 first-party modals stay
+> hand-mounted in `index.vue` and are migrated only opportunistically — don't reach for
+> `appOverlays` to replace a first-party fast-path modal.
+
 ## Reuse the shared building blocks — don't reinvent them
 
 The layer ships window/inspector primitives you compose instead of hand-rolling chrome or
@@ -152,6 +180,7 @@ below). Compose these:
 | `InspectorSection`     | `#components` → `PanelsInspectorSection`  | The collapsible inspector-section shell (chevron header, count, hint) so a consumer panel reads like a built-in one.                                                                                                                                                                                          |
 | `useResultView(id)`    | auto-imported                             | The window seam contract: `{ open, blockId, instanceId, stepIndex, close }` (+ an `onOpen` loader for windows that fetch, and an `onClose` flush). Escape is owned by the shell, not here.                                                                                                                    |
 | `usePanelSubject<T>()` | `@modular-vue/core`                       | Read the block injected into an inspector panel by `<PanelsOutlet>`.                                                                                                                                                                                                                                          |
+| `useAppOverlays()`     | auto-imported                             | Open / close your own top-level overlays: `{ open(id, subject?), close(), active }`. The store-free seam a nav `run` closure uses to open an `appOverlays`-slot component (see "Top-level overlays").                                                                                                         |
 
 > **Reference layer components through `#components`, not bare tags.** Nuxt auto-registers a
 > layer's components under a **path-derived** name (`components/panels/ResultWindowShell.vue`

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

@@ -52,6 +52,7 @@ const slots = (): AppSlots => ({
   inspectorPanels: [],
   taskTypes: [],
   taskTypeFormPanels: [],
+  appOverlays: [],
 })
 const ids = (s: unknown) => (s as AppSlots).nav.map((i) => i.id)
 

package/app/modular/registry.spec.ts

@@ -111,4 +111,27 @@ describe('app modular registry', () => {
     expect(ids).toContain('build-pipeline')
     expect(ids).toContain('consumer:reports')
   })
+
+  it('merges a consumer-contributed overlay into the appOverlays slot (slice-D extensibility)', () => {
+    // A deployment contributes its OWN top-level overlay to the `appOverlays` slot; the layer's
+    // single `<AppOverlayHost>` mounts it on `ui.openOverlay(id)` — no host edit (the slice-D
+    // extensibility promise). A fake component (plain object) stands in for the SFC.
+    const fakeOverlay = { name: 'AcmeSecurityDashboard' }
+    registerAppModule(
+      defineModule({
+        id: 'consumer:overlay',
+        version: '1.0.0',
+        slots: {
+          appOverlays: [{ id: 'acme:security-dashboard-overlay', component: fakeOverlay }],
+        },
+      }),
+    )
+
+    const slots = createAppRegistry({ gates: NO_GATES }).resolveManifest().slots as {
+      appOverlays: { id: string }[]
+    }
+    // The slot exists by default (empty) even with no first-party overlays, and the consumer
+    // entry lands in it.
+    expect(slots.appOverlays.map((o) => o.id)).toContain('acme:security-dashboard-overlay')
+  })
 })

package/app/modular/registry.ts

@@ -108,6 +108,7 @@ export function createAppRegistry(
       inspectorPanels: [],
       taskTypes: [],
       taskTypeFormPanels: [],
+      appOverlays: [],
     },
   }).use(journeysPlugin())
   for (const mod of [...FIRST_PARTY_MODULES, ...extraModules, ...consumerModules]) {

package/app/modular/slots.ts

@@ -31,6 +31,14 @@ import type { NavContribution } from './nav-contributions'
  *    per custom task type, addressed by the type's `formPanel` id and paired via
  *    `resolveComponentRegistry` (same shape as `resultViews`); shown INSTEAD of the
  *    descriptor-driven `fields`. An unpaired id degrades to the descriptor fields.
+ *  - `appOverlays` (extension slice D) — top-level modals/overlays a consumer module
+ *    contributes ({@link OverlayContribution}, an id → component `ComponentEntry`),
+ *    opened by `ui.openOverlay(id, subject?)` / `useAppOverlays().open(...)` and
+ *    mounted by the single `<AppOverlayHost>` in `pages/index.vue` (which selects the
+ *    active entry through `resolveComponentRegistry`, the same pick-one primitive
+ *    `resultViews` uses). This is the one host surface a consumer flatly could not
+ *    extend before — a nav item's `run` closure now has something to open. First-party
+ *    modals stay hand-mounted in `index.vue`; the seam is for consumer overlays.
  *
  * The index signature is mutable (`unknown[]`) to satisfy the runtime's
  * `SlotMap` constraint while `unknown[]` still meets `useReactiveSlots`'
@@ -43,6 +51,7 @@ export interface AppSlots {
   inspectorPanels: PanelEntry<Block>[]
   taskTypes: CustomTaskType[]
   taskTypeFormPanels: ResultViewContribution[]
+  appOverlays: OverlayContribution[]
   [key: string]: unknown[]
 }
 
@@ -57,3 +66,15 @@ export interface AppSlots {
  * custom task type's `formPanel` id).
  */
 export type ResultViewContribution = ComponentEntry<Component>
+
+/**
+ * One consumer-contributed top-level overlay (a modal/panel with no first-party
+ * home), addressed by its namespaced `<ns>:<name>` id. A plain `ComponentEntry`,
+ * so `<AppOverlayHost>` indexes the merged `appOverlays` slot with the same
+ * `resolveComponentRegistry` pick-one primitive as `resultViews` and mounts the
+ * entry whose id matches the active `ui.openOverlay(...)` request. The overlay
+ * component receives the (optional) subject as a `subject` prop and emits `close`;
+ * it composes the layer's `ResultWindowShell` / `useModalBehavior` for its own
+ * chrome (see the consumer-extensions guide).
+ */
+export type OverlayContribution = ComponentEntry<Component>

package/app/pages/index.vue

@@ -16,6 +16,7 @@ import InspectorPanel from '~/components/panels/InspectorPanel.vue'
 import DecisionModal from '~/components/panels/DecisionModal.vue'
 import AgentStepDetail from '~/components/panels/AgentStepDetail.vue'
 import StepResultViewHost from '~/components/panels/StepResultViewHost.vue'
+import AppOverlayHost from '~/components/panels/AppOverlayHost.vue'
 import AddTaskModal from '~/components/board/AddTaskModal.vue'
 import ReviewFrictionDialog from '~/components/board/ReviewFrictionDialog.vue'
 import CreateInitiativeModal from '~/components/board/CreateInitiativeModal.vue'
@@ -377,6 +378,9 @@ watch(
       <DecisionModal />
       <AgentStepDetail />
       <StepResultViewHost />
+      <!-- Consumer-contributed top-level overlays (extension slice D). Renders nothing until a
+           consumer opens one via `ui.openOverlay` / `useAppOverlays().open(...)`. -->
+      <AppOverlayHost />
       <AddTaskModal />
       <ReviewFrictionDialog v-if="ui.reviewFrictionContext" />
       <CreateInitiativeModal />

package/app/plugins/modular.client.ts

@@ -15,7 +15,7 @@ import {
   environmentSetupModule,
   environmentSetupPersistence,
 } from '~/modular/journeys/environmentSetup'
-import type { AppSlots, ResultViewContribution } from '~/modular/slots'
+import type { AppSlots, OverlayContribution, ResultViewContribution } from '~/modular/slots'
 import type { Block, CustomAgentKind, CustomTaskType } from '~/types/domain'
 
 /**
@@ -102,6 +102,11 @@ export default defineNuxtPlugin({
     // duplicate `formPanel` id across the first-party + consumer modules throws at BOOT
     // rather than the first time the create-task form opens a custom type's section.
     resolveComponentRegistry((slots.taskTypeFormPanels ?? []) as ResultViewContribution[])
+    // Same fail-fast for the consumer-overlay registry (extension slice D): a duplicate
+    // `appOverlays` id across the first-party + consumer modules throws at BOOT rather than
+    // the first time `<AppOverlayHost>` mounts one. The slot is static after this resolve, so
+    // the host's own reactive re-resolve is a cheap read this has already validated.
+    resolveComponentRegistry((slots.appOverlays ?? []) as OverlayContribution[])
     // Consumer agent kinds + task types contributed as CODE to the static `agentKinds` /
     // `taskTypes` slots (module slots resolve once, so the static base is the full set).
     useAgentsStore().registerConsumerKinds((slots.agentKinds ?? []) as CustomAgentKind[])

package/app/stores/environmentWizard/context.ts

@@ -0,0 +1,68 @@
+import type { ComputedRef, Ref } from 'vue'
+import type {
+  MergedRecipeDraft,
+  PreflightResult,
+  ProvisioningRecommendation,
+  StackRecipe,
+} from '@cat-factory/contracts'
+import type { useBoardStore } from '~/stores/board'
+import type { useExecutionStore } from '~/stores/execution'
+import type { useGitHubStore } from '~/stores/github'
+import type { useInfraConfigStore } from '~/stores/infraConfig'
+import type { usePipelinesStore } from '~/stores/pipelines'
+import type { usePreflightsStore } from '~/stores/preflights'
+
+/**
+ * Shared reactive state + resolved store handles the environment-wizard action factories
+ * ({@link import('./flow').createFlowActions}, {@link import('./recipe').createRecipeActions},
+ * {@link import('./save').createSaveActions}) close over. Assembled once in the store setup and
+ * threaded into each factory so the split actions stay behaviourally identical to the former
+ * single-closure store — a size-only extraction following the `board` store idiom.
+ */
+export interface WizardContext {
+  board: ReturnType<typeof useBoardStore>
+  github: ReturnType<typeof useGitHubStore>
+  infra: ReturnType<typeof useInfraConfigStore>
+  execution: ReturnType<typeof useExecutionStore>
+  preflights: ReturnType<typeof usePreflightsStore>
+  // ---- state ----
+  frameId: Ref<string | null>
+  detecting: Ref<boolean>
+  detectError: Ref<boolean>
+  recommendation: Ref<ProvisioningRecommendation | null>
+  analysisRequested: Ref<boolean>
+  analysisError: Ref<boolean>
+  recipe: Ref<StackRecipe>
+  composeService: Ref<string>
+  preflightRunning: Ref<boolean>
+  preflightResults: Ref<PreflightResult[] | null>
+  preflightError: Ref<string | null>
+  handlerLabel: Ref<string>
+  exposedPort: Ref<number>
+  saving: Ref<boolean>
+  saveError: Ref<string | null>
+  saved: Ref<boolean>
+  trialing: Ref<boolean>
+  trialError: Ref<string | null>
+  trialStarted: Ref<boolean>
+  // ---- derived the actions read ----
+  repoContext: ComputedRef<{ githubId: number; directory?: string | null } | undefined>
+  analysisPipeline: ComputedRef<ReturnType<ReturnType<typeof usePipelinesStore>['getPipeline']>>
+  merged: ComputedRef<MergedRecipeDraft | null>
+}
+
+/** Drop empty arrays / undefined so the persisted recipe stays minimal and schema-valid
+ *  (`composeFiles` etc. are `minLength(1)`, so an empty array would 422). */
+export function pruneRecipe(recipe: StackRecipe): StackRecipe {
+  const out: Record<string, unknown> = {}
+  for (const [key, value] of Object.entries(recipe)) {
+    if (value === undefined || value === null) continue
+    if (Array.isArray(value) && value.length === 0) continue
+    out[key] = value
+  }
+  return out as StackRecipe
+}
+
+export function cloneRecipe(recipe: StackRecipe): StackRecipe {
+  return JSON.parse(JSON.stringify(recipe)) as StackRecipe
+}

package/app/stores/environmentWizard/flow.ts

@@ -0,0 +1,143 @@
+import type { WizardContext } from './context'
+import { cloneRecipe } from './context'
+
+/**
+ * The wizard's per-frame lifecycle + recommendation actions: reset/target a frame, (re)seed the
+ * working recipe from the merged recommendation, run checkout-free detection, fire the analyst
+ * pipeline, and fold a ready analyst draft in. Closes over the shared {@link WizardContext};
+ * behaviour is identical to the former in-closure functions (a size-only extraction). The internal
+ * `resetFlowState` / `seedFromMerged` helpers are not exposed (they were never part of the public
+ * store shape).
+ */
+export function createFlowActions(ctx: WizardContext) {
+  const {
+    github,
+    infra,
+    execution,
+    frameId,
+    detecting,
+    detectError,
+    recommendation,
+    analysisRequested,
+    analysisError,
+    recipe,
+    composeService,
+    preflightRunning,
+    preflightResults,
+    preflightError,
+    handlerLabel,
+    exposedPort,
+    saving,
+    saveError,
+    saved,
+    trialing,
+    trialError,
+    trialStarted,
+    repoContext,
+    analysisPipeline,
+    merged,
+  } = ctx
+
+  /**
+   * Clear all per-frame flow state (detection, working recipe, preflight, save, trial). Shared by
+   * `beginForFrame` so re-targeting the wizard at a different frame can't leave a prior frame's
+   * `saved`/`composeService`/`exposedPort`/results behind (which would make an unsaved frame render
+   * the green "saved" confirmation + offer a trial provision).
+   */
+  function resetFlowState() {
+    detecting.value = false
+    detectError.value = false
+    recommendation.value = null
+    analysisRequested.value = false
+    analysisError.value = false
+    recipe.value = {}
+    composeService.value = ''
+    preflightRunning.value = false
+    preflightResults.value = null
+    preflightError.value = null
+    handlerLabel.value = 'Docker Compose'
+    exposedPort.value = 80
+    saving.value = false
+    saveError.value = null
+    saved.value = false
+    trialing.value = false
+    trialError.value = null
+    trialStarted.value = false
+  }
+
+  /** Re-seed the working recipe from the current merge (detector-only, or +analyst after apply). */
+  function seedFromMerged() {
+    if (merged.value) recipe.value = cloneRecipe(merged.value.recipe)
+    // Default the exposed service to the detector's recommended compose service, when known.
+    const recommended = recommendation.value?.composeServiceCandidates?.find((c) => c.recommended)
+    if (recommended && !composeService.value) composeService.value = recommended.service
+  }
+
+  /** Run checkout-free detection for the frame's repo (non-binding; seeds the working recipe). */
+  async function detect() {
+    const target = repoContext.value
+    if (!target) {
+      detectError.value = true
+      return
+    }
+    const repo = github.repoFor(target.githubId)
+    if (!repo) {
+      detectError.value = true
+      return
+    }
+    detecting.value = true
+    detectError.value = false
+    try {
+      const rec = await infra.detectProvisioning({
+        owner: repo.owner,
+        repo: repo.name,
+        ...(target.directory ? { directory: target.directory } : {}),
+        prefer: 'docker-compose',
+      })
+      recommendation.value = rec
+      // Seed the exposed port + build flag from the detected provisioning where present.
+      seedFromMerged()
+    } catch {
+      detectError.value = true
+    } finally {
+      detecting.value = false
+    }
+  }
+
+  /**
+   * Seed the data layer for a frame the journey's review step is entering. The journey owns
+   * navigation, so this is idempotent by frame: it (re)seeds + detects only when the target frame
+   * actually changes, so back-navigating to the review step (or a resume) does NOT clobber the
+   * operator's in-progress recipe edits. Selecting a different frame resets the flow for it.
+   */
+  function beginForFrame(id: string | null) {
+    if (frameId.value === id) return
+    frameId.value = id
+    resetFlowState()
+    if (id) void detect()
+  }
+
+  /** Fire the analyst-only pipeline against the frame (mirrors how bootstrap runs pl_blueprint). */
+  async function startAnalysis() {
+    const id = frameId.value
+    const pipeline = analysisPipeline.value
+    if (!id || !pipeline) {
+      analysisError.value = true
+      return
+    }
+    analysisError.value = false
+    try {
+      await execution.start(id, pipeline)
+      analysisRequested.value = true
+    } catch {
+      analysisError.value = true
+    }
+  }
+
+  /** Fold the (now-ready) analyst draft into the working recipe (re-seed from the merge). */
+  function applyAnalystDraft() {
+    seedFromMerged()
+  }
+
+  return { beginForFrame, detect, startAnalysis, applyAnalystDraft }
+}

package/app/stores/environmentWizard/recipe.ts

@@ -0,0 +1,63 @@
+import * as v from 'valibot'
+import { type ProvisioningSeedDumpCandidate, stackRecipeSchema } from '@cat-factory/contracts'
+import type { WizardContext } from './context'
+
+/**
+ * The working-recipe editing actions (compose-file / profile toggles, seed-step insertion, raw-JSON
+ * replace). Closes over the shared {@link WizardContext}; behaviour is identical to the former
+ * in-closure functions (a size-only extraction).
+ */
+export function createRecipeActions(ctx: WizardContext) {
+  const { recipe, composeService } = ctx
+
+  /** Toggle an OS-override / extra compose file into the working recipe's ordered `composeFiles`. */
+  function toggleComposeFile(path: string) {
+    const files = recipe.value.composeFiles ? [...recipe.value.composeFiles] : []
+    const idx = files.indexOf(path)
+    if (idx >= 0) files.splice(idx, 1)
+    else files.push(path)
+    recipe.value = { ...recipe.value, composeFiles: files }
+  }
+
+  /** Toggle a `COMPOSE_PROFILES` label into the working recipe. */
+  function toggleProfile(profile: string) {
+    const profiles = recipe.value.composeProfiles ? [...recipe.value.composeProfiles] : []
+    const idx = profiles.indexOf(profile)
+    if (idx >= 0) profiles.splice(idx, 1)
+    else profiles.push(profile)
+    recipe.value = { ...recipe.value, composeProfiles: profiles }
+  }
+
+  /**
+   * Convert a confirmed seed-dump candidate into a `compose-exec` step that pipes the dump via
+   * stdin. The service + command are a best-effort default (the exposed/db service + a `cat`
+   * placeholder) the operator refines in the recipe editor — detection can't know the DB client.
+   */
+  function addSeedStep(candidate: ProvisioningSeedDumpCandidate) {
+    const setupSteps = recipe.value.setupSteps ? [...recipe.value.setupSteps] : []
+    setupSteps.push({
+      kind: 'compose-exec',
+      name: `Import seed ${candidate.name}`,
+      service: composeService.value || 'db',
+      command: ['sh', '-c', 'cat'],
+      stdinFile: candidate.path,
+    })
+    recipe.value = { ...recipe.value, setupSteps }
+  }
+
+  /** Replace the working recipe from a raw-JSON edit; returns an error message or null on success. */
+  function setRecipeFromJson(text: string): string | null {
+    let parsedJson: unknown
+    try {
+      parsedJson = JSON.parse(text)
+    } catch (err) {
+      return err instanceof Error ? err.message : 'Invalid JSON'
+    }
+    const result = v.safeParse(stackRecipeSchema, parsedJson)
+    if (!result.success) return result.issues.map((i) => i.message).join('; ')
+    recipe.value = result.output
+    return null
+  }
+
+  return { toggleComposeFile, toggleProfile, addSeedStep, setRecipeFromJson }
+}