@cat-factory/app 0.134.0 → 0.135.0

package/app/modular/journeys/environmentSetup.frame.ts

@@ -0,0 +1,31 @@
+import { type MaybeRefOrGetter, toValue, watch } from 'vue'
+import { useEnvironmentWizardStore } from '~/stores/environmentWizard'
+
+/**
+ * Bridge a journey step's target frame (`ModuleEntryProps.input.frameId`) into
+ * the `environmentWizard` data store (slice 3 of the modular-vue adoption).
+ *
+ * The journey owns per-frame NAVIGATION (its state carries the resolved
+ * `frameId`), but the heavy per-step DATA lives in the singleton
+ * `environmentWizard` store, which holds exactly ONE frame at a time. Every step
+ * that READS that store therefore has to (re)assert the frame it was entered for
+ * — otherwise the store can be pointing at a DIFFERENT frame than the one the
+ * journey is on, and the step renders (or `save()` persists) the wrong frame's
+ * recipe. That desync is reachable within a single session: configure frame A up
+ * to the preflight step, open the wizard for frame B (its review step repoints
+ * the store to B), then reopen A and RESUME at preflight — a step that never
+ * re-bridged would show B's data under A's journey.
+ *
+ * `beginForFrame` is idempotent per frame (a no-op when the store already targets
+ * `frameId`), so calling this from every data step is free on the happy path and
+ * only re-seeds when the store actually drifted. `immediate` so the store is
+ * targeted before the step's first render reads it.
+ */
+export function useEnvironmentWizardTarget(frameId: MaybeRefOrGetter<string | null>): void {
+  const store = useEnvironmentWizardStore()
+  watch(
+    () => toValue(frameId),
+    (id) => store.beginForFrame(id),
+    { immediate: true },
+  )
+}

package/app/modular/journeys/environmentSetup.logic.spec.ts

@@ -0,0 +1,34 @@
+import { describe, expect, it } from 'vitest'
+import {
+  ENV_STEP_ORDER,
+  envInitialState,
+  envNextAfter,
+  envStartStep,
+} from './environmentSetup.logic'
+
+// Pure navigation graph for the environment-setup journey (slice 3). `envNextAfter`
+// is the source of truth the journey's `advance` transitions derive their target
+// entries from (see `environmentSetup.ts`), so pinning the order, start branch, and
+// forward edges here means a wiring regression can't silently reorder or drop a step.
+describe('environment-setup journey logic', () => {
+  it('orders the steps pick → review → preflight → save', () => {
+    expect(ENV_STEP_ORDER).toEqual(['pick', 'review', 'preflight', 'save'])
+  })
+
+  it('seeds state from the launch input', () => {
+    expect(envInitialState({ frameId: 'blk_1' })).toEqual({ frameId: 'blk_1' })
+    expect(envInitialState({ frameId: null })).toEqual({ frameId: null })
+  })
+
+  it('skips the picker when a frame was preselected, else starts at pick', () => {
+    expect(envStartStep({ frameId: 'blk_1' }, { frameId: 'blk_1' })).toBe('review')
+    expect(envStartStep({ frameId: null }, { frameId: null })).toBe('pick')
+  })
+
+  it('advances linearly and terminates after save', () => {
+    expect(envNextAfter('pick')).toBe('review')
+    expect(envNextAfter('review')).toBe('preflight')
+    expect(envNextAfter('preflight')).toBe('save')
+    expect(envNextAfter('save')).toBe('done')
+  })
+})

package/app/modular/journeys/environmentSetup.logic.ts

@@ -0,0 +1,86 @@
+/**
+ * Pure navigation logic for the environment-setup journey (slice 3 of the
+ * modular-vue adoption — docs/initiatives/modular-vue-adoption.md).
+ *
+ * The journey owns only the WIZARD NAVIGATION — the ordered steps
+ * (pick → review → preflight → save), the forward transitions, and the
+ * back/rewind + resume that used to live as a hand-rolled `STEP_ORDER` + `step`
+ * ref + `goToStep` in `stores/environmentWizard.ts`. The heavy per-step DATA and
+ * async actions (detect / deep-analysis / recipe editing / preflight / save /
+ * trial) stay in that Pinia store, which the step components still drive; the
+ * journey just decides WHICH step shows and threads the target frame id.
+ *
+ * This file is deliberately free of Vue/`.vue`/`defineModule` imports so the
+ * transition graph is unit-tested directly (`environmentSetup.spec.ts`); the
+ * component wiring lives in `environmentSetup.ts`, which feeds these helpers into
+ * `defineJourney`'s `transitions` map.
+ */
+
+/** The journey's ordered step entries (also the module's `entryPoints` keys). */
+export const ENV_STEP_ORDER = ['pick', 'review', 'preflight', 'save'] as const
+export type EnvStep = (typeof ENV_STEP_ORDER)[number]
+
+/** The single module id every step entry lives under. */
+export const ENV_MODULE_ID = 'cat-factory:environment-setup' as const
+
+/** The picker's exit — carries the chosen frame into journey state. */
+export const ENV_SELECT_EXIT = 'select'
+/** Every other step's forward exit — void, just advances. */
+export const ENV_ADVANCE_EXIT = 'advance'
+
+/** Payload of the picker's `select` exit. */
+export interface EnvSelectOutput {
+  frameId: string
+}
+
+/** The journey's serializable state — just the resolved target frame. Everything
+ *  else is derived live in the `environmentWizard` store, so this stays tiny and
+ *  cheap to persist/resume. */
+export interface EnvSetupState {
+  frameId: string | null
+}
+
+/** The journey's start input — the frame the launcher preselected, or `null` to
+ *  begin at the pick step. `keyFor` scopes resume to this frame. */
+export interface EnvSetupInput {
+  frameId: string | null
+}
+
+/** Seed the journey state from the launch input. */
+export function envInitialState(input: EnvSetupInput): EnvSetupState {
+  return { frameId: input.frameId }
+}
+
+/** First step: skip the picker when the launcher already chose a frame. */
+export function envStartStep(_state: EnvSetupState, input: EnvSetupInput): EnvStep {
+  return input.frameId ? 'review' : 'pick'
+}
+
+/**
+ * The step reached by advancing from `from` via its forward exit, or `'done'`
+ * when the flow completes. The pick step advances via `select` (a distinct
+ * exit); the rest via `advance`. Pure and total over `EnvStep`.
+ *
+ * This is the SINGLE SOURCE OF TRUTH for the linear forward chain: the journey
+ * definition (`environmentSetup.ts`) derives its `advance` transitions' target
+ * entries from it, so pinning this function in `environmentSetup.logic.spec.ts`
+ * genuinely guards the wired graph against a silent reorder/drop. The overloads
+ * narrow the return to a concrete entry (or `'done'`) so a transition handler can
+ * feed the result straight into a `StepSpec` without a widened `EnvStep | 'done'`.
+ */
+export function envNextAfter(from: 'pick'): 'review'
+export function envNextAfter(from: 'review'): 'preflight'
+export function envNextAfter(from: 'preflight'): 'save'
+export function envNextAfter(from: 'save'): 'done'
+export function envNextAfter(from: EnvStep): EnvStep | 'done' {
+  switch (from) {
+    case 'pick':
+      return 'review'
+    case 'review':
+      return 'preflight'
+    case 'preflight':
+      return 'save'
+    case 'save':
+      return 'done'
+  }
+}

package/app/modular/journeys/environmentSetup.ts

@@ -0,0 +1,143 @@
+import { defineModule } from '@modular-vue/core'
+import { defineExit } from '@modular-frontend/core'
+import { defineJourney, defineJourneyHandle } from '@modular-vue/journeys'
+import EnvPickStep from '~/components/environments/steps/EnvPickStep.vue'
+import EnvReviewStep from '~/components/environments/steps/EnvReviewStep.vue'
+import EnvPreflightStep from '~/components/environments/steps/EnvPreflightStep.vue'
+import EnvSaveStep from '~/components/environments/steps/EnvSaveStep.vue'
+import { catFactoryJourneyPersistence } from '~/modular/journeys/persistence'
+import {
+  ENV_ADVANCE_EXIT,
+  ENV_MODULE_ID,
+  ENV_SELECT_EXIT,
+  type EnvSelectOutput,
+  type EnvSetupInput,
+  type EnvSetupState,
+  envInitialState,
+  envNextAfter,
+  envStartStep,
+} from '~/modular/journeys/environmentSetup.logic'
+
+/**
+ * The environment-setup journey — the slice-3 pilot of the modular-vue adoption
+ * (docs/initiatives/modular-vue-adoption.md). It replaces the wizard's hand-rolled
+ * `STEP_ORDER` + `step` ref + `goToStep` navigation (in `stores/environmentWizard.ts`)
+ * with a typed, back/rewind-capable, resumable journey; the per-step data + async
+ * actions stay in that Pinia store, driven by the step components below.
+ *
+ * Authoring notes (co-evolution): `defineModule` comes from the `@modular-vue/core`
+ * binding, but the exit helper `defineExit` is only exported from the neutral
+ * `@modular-frontend/core` engine (a direct dep) — the Vue binding doesn't re-export
+ * the entry/exit authoring helpers yet. That's a small binding-surface gap to close
+ * upstream (mirrors slice 2's remote-manifest re-export), not a blocker.
+ *
+ * Each step's `input` (the target frame) is threaded explicitly on the `next` step
+ * specs rather than via an entry `buildInput` factory: the frame is fixed once at the
+ * pick step and never changes mid-flow, so the snapshot input a transition places is
+ * always current — even on `preserve-state` back-navigation — which keeps the module
+ * type simple (no `buildInput`-optionality quirk) and the flow fully explicit.
+ *
+ * This file imports the step `.vue` components, so — like `result-views.ts` — it's
+ * registered from the client plugin, keeping the unit-tested `registry.ts` /
+ * `*.logic.ts` import graph free of SFCs.
+ */
+
+/**
+ * The step module: one module, four `journey`-mounted entries (the wizard steps),
+ * and two exits — `select` (the picker's chosen frame) and `advance` (every other
+ * step's void forward). Each non-initial entry opts into `preserve-state` back so
+ * the host's Back control rewinds a step without discarding the operator's edits.
+ */
+export const environmentSetupModule = defineModule({
+  id: ENV_MODULE_ID,
+  version: '1.0.0',
+  entryPoints: {
+    pick: { mountKinds: ['journey'] as const, component: EnvPickStep },
+    review: {
+      mountKinds: ['journey'] as const,
+      allowBack: 'preserve-state' as const,
+      component: EnvReviewStep,
+    },
+    preflight: {
+      mountKinds: ['journey'] as const,
+      allowBack: 'preserve-state' as const,
+      component: EnvPreflightStep,
+    },
+    save: {
+      mountKinds: ['journey'] as const,
+      allowBack: 'preserve-state' as const,
+      component: EnvSaveStep,
+    },
+  },
+  exitPoints: {
+    [ENV_SELECT_EXIT]: defineExit<EnvSelectOutput>(),
+    [ENV_ADVANCE_EXIT]: defineExit(),
+  },
+})
+
+type EnvModules = { [ENV_MODULE_ID]: typeof environmentSetupModule }
+
+/**
+ * The journey definition. `start` skips the picker when a frame was preselected;
+ * transitions are the linear pick → review → preflight → save chain, terminating
+ * with `complete` off the save step's `advance`. Back-navigation is handled by the
+ * entries' `allowBack`, not explicit transitions.
+ */
+export const environmentSetupJourney = defineJourney<EnvModules, EnvSetupState>()({
+  id: 'environment-setup',
+  version: '1.0.0',
+  initialState: (input: EnvSetupInput) => envInitialState(input),
+  start: (state, input: EnvSetupInput) =>
+    envStartStep(state, input) === 'review'
+      ? ({ module: ENV_MODULE_ID, entry: 'review', input: { frameId: state.frameId } } as const)
+      : ({ module: ENV_MODULE_ID, entry: 'pick', input: { frameId: state.frameId } } as const),
+  transitions: {
+    [ENV_MODULE_ID]: {
+      pick: {
+        [ENV_SELECT_EXIT]: (ctx) => ({
+          next: {
+            module: ENV_MODULE_ID,
+            entry: 'review',
+            input: { frameId: ctx.output.frameId },
+          } as const,
+          state: { frameId: ctx.output.frameId },
+        }),
+      },
+      review: {
+        [ENV_ADVANCE_EXIT]: (ctx) => ({
+          next: {
+            module: ENV_MODULE_ID,
+            entry: envNextAfter('review'),
+            input: { frameId: ctx.state.frameId },
+          } as const,
+        }),
+      },
+      preflight: {
+        [ENV_ADVANCE_EXIT]: (ctx) => ({
+          next: {
+            module: ENV_MODULE_ID,
+            entry: envNextAfter('preflight'),
+            input: { frameId: ctx.state.frameId },
+          } as const,
+        }),
+      },
+      // `save` advances to `envNextAfter('save') === 'done'`, i.e. journey completion.
+      save: {
+        [ENV_ADVANCE_EXIT]: () => ({ complete: undefined }),
+      },
+    },
+  },
+})
+
+/** Typed launch handle — callers `runtime.start(handle, { frameId })`. */
+export const environmentSetupHandle = defineJourneyHandle(environmentSetupJourney)
+
+/**
+ * Pinia-backed persistence keyed by the target frame, so reopening the wizard for
+ * the same frame RESUMES at the step it was left on (and a different frame is a
+ * fresh flow). A null frame (launched at the picker) is a single transient key.
+ */
+export const environmentSetupPersistence = catFactoryJourneyPersistence<
+  EnvSetupInput,
+  EnvSetupState
+>(({ journeyId, input }) => `${journeyId}:${input.frameId ?? 'new'}`)

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/registry.ts

@@ -1,6 +1,6 @@
 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 { NavGates } from '~/modular/nav-contributions'
 import type { AppSlots } from '~/modular/slots'
@@ -92,11 +92,17 @@ export function __resetConsumerModulesForTest(): void {
 export function createAppRegistry(
   deps: AppDeps,
   extraModules: readonly AnyModuleDescriptor[] = [],
-): ModuleRegistry<AppDeps, AppSlots> {
+) {
+  // `.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: [], resultViews: [], agentKinds: [] },
-  })
+  }).use(journeysPlugin())
   for (const mod of [...FIRST_PARTY_MODULES, ...extraModules, ...consumerModules]) {
     registry.register(mod)
   }

package/app/plugins/modular.client.ts

@@ -1,9 +1,18 @@
 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'
 
@@ -43,11 +52,35 @@ export default defineNuxtPlugin({
   name: 'cat-factory:modular',
   enforce: 'post',
   setup(nuxtApp) {
-    const registry = createAppRegistry({ gates: createNavGates() }, [resultViewsModule])
-    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,
     })
-    const slots = manifest.slots as AppSlots
+    // 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

package/app/stores/environmentWizard.ts

@@ -23,7 +23,7 @@ import { usePreflightsStore } from '~/stores/preflights'
 import { useServicesStore } from '~/stores/services'
 import { useWorkspaceStore } from '~/stores/workspace'
 
-// The environment setup wizard's cross-step state + actions (shared-stacks slice 7). It walks the
+// The environment setup wizard's cross-step DATA + actions (shared-stacks slice 7). It backs the
 // guided flow — pick a service frame → review the recommended `docker-compose` recipe (detector
 // facts + the opt-in analyst draft, merged with provenance) → run the machine preflights → save
 // (persist the recipe on the frame AND register the workspace's docker-compose handler so the
@@ -31,17 +31,19 @@ import { useWorkspaceStore } from '~/stores/workspace'
 //
 // The detector + analyst only RECOMMEND; the human confirms/edits the working `recipe` here and the
 // compose provider keys purely on the saved recipe (the build-flag rule). Mirrors the other infra
-// stores' idiom; the flow state is a singleton so the wizard modal + its step children share it.
+// stores' idiom; the flow state is a singleton so the wizard's step children share it.
+//
+// Since slice 3 of the modular-vue adoption (docs/initiatives/modular-vue-adoption.md) the wizard's
+// step NAVIGATION lives in a modular-vue journey (`app/modular/journeys/environmentSetup.ts`), NOT
+// here — this store no longer holds a `step` / `STEP_ORDER` / `goToStep`. It is purely the per-frame
+// data+action layer the journey's step components drive; `beginForFrame` seeds it when a step first
+// targets a frame.
 
 /** The seeded analyst-only pipeline the "run deep analysis" trigger starts against the frame. */
 const ANALYSIS_PIPELINE_ID = 'pl_environment_analysis'
 /** The analyst agent kind whose `result.custom` carries the drafted recipe. */
 const ANALYST_AGENT_KIND = 'environment-analyst'
 
-/** The wizard's ordered steps. `trial` is an optional post-save action, not a gate. */
-export type EnvWizardStep = 'pick' | 'review' | 'preflight' | 'save'
-export const ENV_WIZARD_STEPS: EnvWizardStep[] = ['pick', 'review', 'preflight', 'save']
-
 /** The analyst run's lifecycle as the wizard surfaces it. */
 export type AnalysisStatus = 'idle' | 'running' | 'ready' | 'failed'
 
@@ -70,9 +72,11 @@ export const useEnvironmentWizardStore = defineStore('environmentWizard', () =>
   const pipelines = usePipelinesStore()
   const preflights = usePreflightsStore()
 
-  // ---- Flow position ------------------------------------------------------
+  // ---- Target frame -------------------------------------------------------
+  // The frame the flow currently targets. Set by `beginForFrame` when a journey
+  // step first mounts against a frame; the journey (not this store) owns which
+  // step is showing.
   const frameId = ref<string | null>(null)
-  const step = ref<EnvWizardStep>('pick')
 
   // ---- Detection ----------------------------------------------------------
   const detecting = ref(false)
@@ -212,19 +216,18 @@ export const useEnvironmentWizardStore = defineStore('environmentWizard', () =>
     trialStarted.value = false
   }
 
-  /** Reset the flow for a (possibly preselected) frame. */
-  function open(preselectFrameId: string | null) {
-    frameId.value = preselectFrameId
-    step.value = preselectFrameId ? 'review' : 'pick'
-    resetFlowState()
-    if (preselectFrameId) void detect()
-  }
-
-  function selectFrame(id: string) {
+  /**
+   * 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()
-    step.value = 'review'
-    void detect()
+    if (id) void detect()
   }
 
   /** Re-seed the working recipe from the current merge (detector-only, or +analyst after apply). */
@@ -435,14 +438,9 @@ export const useEnvironmentWizardStore = defineStore('environmentWizard', () =>
     }
   }
 
-  function goToStep(next: EnvWizardStep) {
-    step.value = next
-  }
-
   return {
     // state
     frameId,
-    step,
     detecting,
     detectError,
     recommendation,
@@ -472,8 +470,7 @@ export const useEnvironmentWizardStore = defineStore('environmentWizard', () =>
     analysisStatus,
     merged,
     // actions
-    open,
-    selectFrame,
+    beginForFrame,
     detect,
     startAnalysis,
     applyAnalystDraft,
@@ -484,6 +481,5 @@ export const useEnvironmentWizardStore = defineStore('environmentWizard', () =>
     runPreflight,
     save,
     trialProvision,
-    goToStep,
   }
 })