@cat-factory/app 0.196.1 → 0.198.0

package/app/composables/usePipelineErrorToast.ts

@@ -24,6 +24,7 @@
  * added — which is exactly why the detail stays reachable rather than being dropped).
  */
 
+import { createBespokeConflictToasts } from '~/composables/pipelineErrorToast/bespokeConflicts'
 import type { ApiErrorCode, ConflictReason } from '@cat-factory/contracts'
 import { apiErrorEnvelope, apiErrorStatus } from './api/errors'
 
@@ -244,7 +245,7 @@ export function parseConflict(
 }
 
 /** The non-null parsed shape of a backend conflict, as returned by {@link parseConflict}. */
-type ParsedConflict = NonNullable<ReturnType<typeof parseConflict>>
+export type ParsedConflict = NonNullable<ReturnType<typeof parseConflict>>
 
 /**
  * Generic translated description per STATUS CLASS, for a failure no `reason` code narrows.
@@ -330,171 +331,29 @@ export function describeGenericFailure(error: unknown): GenericFailure {
 export function usePipelineErrorToast() {
   const toast = useToast()
   const ui = useUiStore()
-  const { t, te } = useI18n()
+  // Resolved through the Nuxt app's global i18n instance rather than `useI18n()`, which
+  // requires an active component instance — the same pattern (and the same reason) as the
+  // board / recurring-pipelines stores.
+  //
+  // This composable is called from STORE SETUP (`stores/execution.ts`, `stores/agentRuns.ts`),
+  // and a Pinia setup store runs its body on the FIRST `useStore()` anywhere. That used to be
+  // a component, so `useI18n()` happened to be legal; the moment anything instantiated one of
+  // those stores earlier — `createNavGates()` does, from the `enforce: 'post'` modular plugin —
+  // vue-i18n threw `MUST_BE_CALL_SETUP_TOP`, the plugin threw, and Nuxt's error boundary
+  // replaced the entire app with its 500 page. Every single e2e spec failed on a blank board.
+  // A store must be instantiable outside a component, so the i18n handle it reaches for has
+  // to be too.
+  //
+  // Typed as `useI18n`'s own return (`$i18n` IS that global Composer in composition mode), so
+  // `t`/`te` keep their real signatures. No typed-message-key coverage is lost by the switch:
+  // tier 1 only sees literal keys written in a `<script setup>`, never in a `.ts` composable —
+  // the drift guard here is the exhaustive `CONFLICT_INFO` / `ApiErrorCode` records above.
+  const { t, te } = useNuxtApp().$i18n as ReturnType<typeof useI18n>
 
-  // The headline case: a pipeline step's model has no usable provider. Name the
-  // offending model(s), explain no provider is available, and offer the one-click jump
-  // to the AI setup — the same remedy the startup "No AI model configured" banner gives.
-  function presentProvidersUnconfigured(conflict: ParsedConflict): void {
-    const models = Array.isArray(conflict.details.models) ? conflict.details.models : []
-    const list = models.join(', ')
-    toast.add({
-      title: t('errors.conflict.providersUnconfigured.title'),
-      description: list
-        ? t('errors.conflict.providersUnconfigured.body', { models: list })
-        : (conflict.message ?? t('errors.conflict.fallbackMessage')),
-      color: 'error',
-      icon: 'i-lucide-cpu',
-      // Stay until dismissed: an actionable toast whose remedy button vanishes on the ~5s
-      // auto-dismiss takes the one-click fix with it before the user can reach it.
-      duration: 0,
-      actions: [
-        {
-          label: t('errors.conflict.providersUnconfigured.action'),
-          icon: 'i-lucide-settings',
-          onClick: () => ui.openAiProviderSetup(),
-        },
-      ],
-    })
-  }
-
-  // A pipeline step relies on binary-artifact storage (the UI Tester uploads screenshots)
-  // but the account has none configured. Explain it and offer the jump to the content-storage
-  // settings — the same shape as the providers-unconfigured case above. Prefer the localized
-  // body (it carries no runtime interpolation) so non-English users see translated copy; the
-  // raw backend prose is only the last-resort fallback when the locale lacks the key.
-  function presentBinaryStorageUnconfigured(conflict: ParsedConflict): void {
-    toast.add({
-      title: t('errors.conflict.binaryStorageUnconfigured.title'),
-      description: te('errors.conflict.binaryStorageUnconfigured.body')
-        ? t('errors.conflict.binaryStorageUnconfigured.body')
-        : (conflict.message ?? t('errors.conflict.fallbackMessage')),
-      color: 'error',
-      icon: 'i-lucide-image',
-      // Sticky, like the providers-unconfigured toast above: keep the "Configure storage"
-      // remedy reachable instead of letting it auto-dismiss.
-      duration: 0,
-      actions: [
-        {
-          label: t('errors.conflict.binaryStorageUnconfigured.action'),
-          icon: 'i-lucide-settings',
-          onClick: () => ui.openContentStorageSettings(),
-        },
-      ],
-    })
-  }
-
-  // A pipeline includes a Deployer, but the SERVICE's ephemeral-environment config (the in-repo
-  // "what/where") is incomplete for its declared type. Steer the user straight to THAT service's
-  // environment config — the compose wizard for docker-compose, the service inspector otherwise —
-  // falling back to the workspace infrastructure window if the frame id wasn't carried.
-  function presentDeployerServiceConfig(conflict: ParsedConflict): void {
-    const frameId =
-      typeof conflict.details.frameId === 'string' ? conflict.details.frameId : undefined
-    const provisionType =
-      typeof conflict.details.provisionType === 'string'
-        ? conflict.details.provisionType
-        : undefined
-    const missing = Array.isArray(conflict.details.missing)
-      ? conflict.details.missing.join(', ')
-      : ''
-    toast.add({
-      title: t('errors.conflict.deployerServiceConfig.title'),
-      description: missing
-        ? t('errors.conflict.deployerServiceConfig.body', { missing })
-        : (conflict.message ?? t('errors.conflict.fallbackMessage')),
-      color: 'error',
-      icon: 'i-lucide-server',
-      // Sticky, like the other actionable conflicts: keep the "Fix configuration" jump reachable.
-      duration: 0,
-      actions: [
-        {
-          label: t('errors.conflict.deployerServiceConfig.action'),
-          icon: 'i-lucide-settings',
-          onClick: () => {
-            if (frameId && provisionType === 'docker-compose') ui.openEnvironmentSetup(frameId)
-            else if (frameId) ui.select(frameId)
-            else ui.openProviderConnection('environment')
-          },
-        },
-      ],
-    })
-  }
-
-  // A pipeline includes a Deployer and the service config is sound, but no WORKSPACE handler
-  // resolves for the service's provision type (missing or ambiguous). Steer to the Infrastructure
-  // window's Test-environments tab. (Also raised by the Tester start gate — same fix applies.)
-  function presentProvisionTypeUnhandled(conflict: ParsedConflict): void {
-    const type =
-      typeof conflict.details.provisionType === 'string' ? conflict.details.provisionType : ''
-    toast.add({
-      title: t('errors.conflict.provisionTypeUnhandled.title'),
-      description: type
-        ? t('errors.conflict.provisionTypeUnhandled.body', { type })
-        : (conflict.message ?? t('errors.conflict.fallbackMessage')),
-      color: 'error',
-      icon: 'i-lucide-server-cog',
-      duration: 0,
-      actions: [
-        {
-          label: t('errors.conflict.provisionTypeUnhandled.action'),
-          icon: 'i-lucide-settings',
-          onClick: () => ui.openProviderConnection('environment'),
-        },
-      ],
-    })
-  }
-
-  // A pipeline includes a Deployer, the config is structurally complete, but the live connection
-  // probe of the resolved deployment integration failed (unreachable endpoint / apiserver, bad
-  // token). Surface the provider's failure detail and steer to the handler to fix + re-test it.
-  function presentDeployerConnectionFailed(conflict: ParsedConflict): void {
-    const detail = typeof conflict.details.detail === 'string' ? conflict.details.detail : undefined
-    toast.add({
-      title: t('errors.conflict.deployerConnectionFailed.title'),
-      description: detail
-        ? t('errors.conflict.deployerConnectionFailed.body', { detail })
-        : (conflict.message ?? t('errors.conflict.fallbackMessage')),
-      color: 'error',
-      icon: 'i-lucide-plug',
-      duration: 0,
-      actions: [
-        {
-          label: t('errors.conflict.deployerConnectionFailed.action'),
-          icon: 'i-lucide-settings',
-          onClick: () => ui.openProviderConnection('environment'),
-        },
-      ],
-    })
-  }
-
-  /**
-   * Dispatch the bespoke conflict reasons (a runtime-interpolated body + a "configure X" action,
-   * each with its own key namespace — the ones excluded from `CONFLICT_INFO`). Returns `true` when
-   * the reason was one of them (and the toast was raised), `false` to fall through to the generic
-   * map. The reason values are mutually exclusive, so dispatch order is irrelevant.
-   */
-  function presentBespokeConflict(conflict: ParsedConflict): boolean {
-    switch (conflict.reason) {
-      case 'providers_unconfigured':
-        presentProvidersUnconfigured(conflict)
-        return true
-      case 'binary_storage_unconfigured':
-        presentBinaryStorageUnconfigured(conflict)
-        return true
-      case 'deployer_service_provisioning_incomplete':
-        presentDeployerServiceConfig(conflict)
-        return true
-      case 'provision_type_unhandled':
-        presentProvisionTypeUnhandled(conflict)
-        return true
-      case 'deployer_connection_test_failed':
-        presentDeployerConnectionFailed(conflict)
-        return true
-      default:
-        return false
-    }
-  }
+  // The five bespoke conflict reasons (a runtime-interpolated body + a "configure X" jump each)
+  // live in a sibling factory over the same toast/ui/i18n handles, so this composable stays
+  // within the per-function line budget.
+  const presentBespokeConflict = createBespokeConflictToasts({ toast, ui, t, te })
 
   /**
    * Per-reason copy from the exhaustive map: a translated title + description, and a jump

package/app/composables/useTutorialTours.ts

@@ -0,0 +1,18 @@
+import { computed } from 'vue'
+import { useReactiveSlots } from '@modular-vue/runtime'
+import { sortTours } from '~/utils/tutorial'
+import type { TutorialTour } from '~/utils/tutorial'
+import type { AppSlots } from '~/modular/nav-contributions'
+
+/**
+ * The tours the current user may take: the merged `tutorialTours` slot (first-party +
+ * consumer-contributed), already gated per tour by `navSlotFilter` (each tour's `when`
+ * runs over the reactive gates service, so a permission flip shows/hides tours live),
+ * in deterministic catalog order. The single source both the launch prompt and the
+ * coach-mark overlay resolve tours from.
+ */
+export function useTutorialTours() {
+  const slots = useReactiveSlots<AppSlots>()
+  const tours = computed<TutorialTour[]>(() => sortTours(slots.value.tutorialTours ?? []))
+  return { tours }
+}

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

@@ -25,6 +25,12 @@ const NO_GATES: NavGates = {
   // The permission axis is what these cases vary; keep the interface tier at `advanced`
   // so a dropped item is unambiguously an RBAC/availability drop, not a tier drop.
   advancedMode: true,
+  boardHasService: false,
+  boardHasTask: false,
+  boardHasRun: false,
+  boardHasOpenDecision: false,
+  boardHasPendingApproval: false,
+  boardHasFinishedRun: false,
 }
 
 const ALL_GATES: NavGates = {
@@ -37,6 +43,12 @@ const ALL_GATES: NavGates = {
   accountsEnabled: true,
   isAccountAdmin: true,
   advancedMode: true,
+  boardHasService: true,
+  boardHasTask: true,
+  boardHasRun: true,
+  boardHasOpenDecision: true,
+  boardHasPendingApproval: true,
+  boardHasFinishedRun: true,
 }
 
 const slots = (): AppSlots => ({
@@ -47,6 +59,7 @@ const slots = (): AppSlots => ({
   taskTypes: [],
   taskTypeFormPanels: [],
   appOverlays: [],
+  tutorialTours: [],
 })
 const ids = (s: unknown) => (s as AppSlots).nav.map((i) => i.id)
 
@@ -312,6 +325,7 @@ describe('nav grouping helpers', () => {
       'sandbox',
       'keyboard-shortcuts',
       'ui-mode',
+      'tutorial',
     ])
   })
 

package/app/modular/nav-contributions.ts

@@ -1,4 +1,5 @@
 import { defineModule } from '@modular-vue/core'
+import { resolveTours } from '~/utils/tutorial'
 import type { AppSlots } from './slots'
 
 // Re-exported for the slice-1 importers that reach `AppSlots` through this
@@ -81,6 +82,49 @@ export interface NavGates {
    * available to a `gate` predicate that needs to combine it with something else.
    */
   advancedMode: boolean
+  /**
+   * The open board has at least one service frame. Availability, not permission: a
+   * surface that operates ON a service (today the task-creation tutorial tour) has
+   * nothing to point at until one exists, and offering it anyway means a walkthrough
+   * that hunts for absent controls. Reactive like the rest, so it flips the moment a
+   * service lands on the board.
+   */
+  boardHasService: boolean
+  /**
+   * The open board has at least one task block. The service frame that {@link boardHasService}
+   * reports is where a task GOES; this is whether one is actually there to run, which is what
+   * a tour about the run controls needs — they live in the inspector of a task, and a board of
+   * empty frames offers nothing to open.
+   */
+  boardHasTask: boolean
+  /**
+   * Some run on a TASK block is cached for this board, in any state. Availability for the
+   * steps that explain a run's ANATOMY (the step list, its live progress), which have nothing
+   * to anchor to until a run has been started at least once.
+   *
+   * Task-scoped, like the three below: every surface these gates open is reached through a
+   * task card and its inspector, and a frame-level run (a blueprint pass, an initiative plan)
+   * renders none of them.
+   */
+  boardHasRun: boolean
+  /**
+   * Some task card is offering a human an unanswered DECISION to resolve.
+   *
+   * "Offering" rather than "exists": these two report what the board actually RENDERS, which
+   * is what a tour anchoring on the card's action can point at — see `hasActionablePark` for
+   * the two ways a park can exist with no control to show for it.
+   */
+  boardHasOpenDecision: boolean
+  /** Some task card is offering a human an unanswered APPROVAL gate. See above. */
+  boardHasPendingApproval: boolean
+  /**
+   * Some run on a task block has finished successfully. Availability for the review/merge
+   * tour: its subject is the OUTPUT of a run, so there has to be one that produced output. A
+   * FAILED run deliberately does not count — the failure banner is its own surface, and a
+   * tour about reading a result and merging it would spend its steps pointing at controls a
+   * failed run never renders.
+   */
+  boardHasFinishedRun: boolean
 }
 
 /** Command-palette placement + copy for a contribution that appears in the palette. */
@@ -119,6 +163,7 @@ export const NAV_ACTIONS = [
   'operatorDashboard',
   'reports',
   'shortcuts',
+  'tutorial',
   'toggleUiMode',
 ] as const
 
@@ -445,6 +490,25 @@ export const NAV_CONTRIBUTIONS: readonly NavContribution[] = [
     testId: 'nav-reports',
     sidebar: { group: 'configuration', order: 45 },
   },
+  {
+    // Deliberately NOT `advanced`: the tours exist for exactly the users basic mode serves,
+    // and the palette entry is the way back to them after the launch prompt was declined
+    // or dismissed. Ungated: every tour gates itself via its own `when` predicate, and the
+    // prompt is worth reaching even when it can only list some tours.
+    id: 'tutorial',
+    labelKey: 'layout.commandBar.cmd.tutorial',
+    icon: 'i-lucide-graduation-cap',
+    surfaces: S('command'),
+    action: 'tutorial',
+    testId: 'nav-tutorial',
+    command: {
+      // After the pre-slice-1 tail (the workspace group pins that order): genuinely new
+      // entries append rather than interleave.
+      group: 'workspace',
+      order: 100,
+      keywordsKey: 'layout.commandBar.keywords.tutorial',
+    },
+  },
   {
     id: 'keyboard-shortcuts',
     labelKey: 'layout.commandBar.cmd.shortcuts',
@@ -503,6 +567,7 @@ export const navigationModule = defineModule({
 export function navSlotFilter(slots: AppSlots, deps: { gates?: NavGates }): AppSlots {
   const gates = deps.gates
   const nav = slots.nav ?? []
+  const tutorialTours = slots.tutorialTours ?? []
   return {
     ...slots,
     // No gates service wired (tests / bare install) ⇒ show everything, matching
@@ -512,6 +577,11 @@ export function navSlotFilter(slots: AppSlots, deps: { gates?: NavGates }): AppS
           (i) => (i.advanced ? gates.advancedMode : true) && (i.gate ? i.gate(gates) : true),
         )
       : nav,
+    // Tutorial tours gate over the same reactive service, so a tour about a surface the
+    // caller can't reach (e.g. creating tasks without board write) never shows, and a step
+    // about a branch this board isn't on is dropped rather than skipped (see `resolveTours`).
+    // Same gates-absent pass-through as `nav`.
+    tutorialTours: gates ? resolveTours(tutorialTours, gates) : tutorialTours,
   }
 }
 

package/app/modular/nav-gates.logic.spec.ts

@@ -0,0 +1,41 @@
+import { describe, expect, it } from 'vitest'
+import { hasActionablePark } from '~/modular/nav-gates.logic'
+import type { ParkedGateRef } from '~/modular/nav-gates.logic'
+
+const onlyTasks = (id: string) => id.startsWith('task_')
+const nothingIsBackground = () => false
+
+describe('hasActionablePark', () => {
+  it('reports a park a task card really shows an action for', () => {
+    const parks: ParkedGateRef[] = [{ blockId: 'task_login', agentKind: 'architect' }]
+    expect(hasActionablePark(parks, onlyTasks, nothingIsBackground)).toBe(true)
+  })
+
+  it('ignores a park on a block that renders no task card', () => {
+    // A frame/module run parks too, but the affordance the tour anchors on is TaskCard's.
+    const parks: ParkedGateRef[] = [{ blockId: 'frame_billing', agentKind: 'blueprints' }]
+    expect(hasActionablePark(parks, onlyTasks, nothingIsBackground)).toBe(false)
+  })
+
+  it('ignores a reviewer gate the card suppresses as background work', () => {
+    // Mirrors `TaskCard.pendingApproval`: while the review is folding answers / re-reviewing
+    // it needs no human, so no Resolve button exists to point a tour at.
+    const parks: ParkedGateRef[] = [{ blockId: 'task_login', agentKind: 'requirements-review' }]
+    const isBackground = (kind: string | undefined) => kind === 'requirements-review'
+    expect(hasActionablePark(parks, onlyTasks, isBackground)).toBe(false)
+  })
+
+  it('reports the actionable one when a board holds both kinds at once', () => {
+    const parks: ParkedGateRef[] = [
+      { blockId: 'frame_billing', agentKind: 'architect' },
+      { blockId: 'task_login', agentKind: 'requirements-review' },
+      { blockId: 'task_signup', agentKind: 'coder' },
+    ]
+    const isBackground = (kind: string | undefined) => kind === 'requirements-review'
+    expect(hasActionablePark(parks, onlyTasks, isBackground)).toBe(true)
+  })
+
+  it('is false for a board with nothing parked at all', () => {
+    expect(hasActionablePark([], onlyTasks, nothingIsBackground)).toBe(false)
+  })
+})

package/app/modular/nav-gates.logic.ts

@@ -0,0 +1,36 @@
+/**
+ * The decisions the `NavGates` service makes that are worth testing without a Pinia runtime.
+ * `nav-gates.ts` itself is pure store wiring (getters over computeds); everything that
+ * DECIDES something lives here, the same split as `TutorialOverlay.logic.ts`.
+ */
+
+/** One park (an open decision or a pending approval gate) as the execution store projects it. */
+export interface ParkedGateRef {
+  blockId: string
+  agentKind?: string
+}
+
+/**
+ * Is some park actually SHOWING a human an action to take?
+ *
+ * The gates this answers (`boardHasOpenDecision` / `boardHasPendingApproval`) exist to offer
+ * a tour that anchors on a task card's attention affordance (`task-resolve`), so they have to
+ * mean what makes that affordance RENDER — not merely "a park exists somewhere in the cached
+ * runs". Two facts the raw store counts miss, both of which would offer the tour onto a board
+ * with no control to point at (the tour then anchor-skips and reports itself abridged, which
+ * is exactly the noise per-step `when` gating exists to avoid):
+ *
+ *  - a park on a frame or module block has no task card, so nothing renders the action;
+ *  - a reviewer gate mid-cycle is deliberately SUPPRESSED by the card (`TaskCard.pendingApproval`
+ *    → `useReviewStage().isBackground`): while the driver is folding answers or re-reviewing,
+ *    the gate needs no human and the card shows a working indicator instead.
+ *
+ * Both predicates are injected rather than reached for, so the rule is checkable on plain data.
+ */
+export function hasActionablePark(
+  parks: readonly ParkedGateRef[],
+  isTaskBlock: (blockId: string) => boolean,
+  isBackground: (agentKind: string | undefined, blockId: string) => boolean,
+): boolean {
+  return parks.some((p) => isTaskBlock(p.blockId) && !isBackground(p.agentKind, p.blockId))
+}

package/app/modular/nav-gates.ts

@@ -1,4 +1,5 @@
 import { computed } from 'vue'
+import { hasActionablePark } from '~/modular/nav-gates.logic'
 import type { NavGates } from '~/modular/nav-contributions'
 
 /**
@@ -25,6 +26,37 @@ export function createNavGates(): NavGates {
   const auth = useAuthStore()
   const providerConnections = useProviderConnectionsStore()
   const uiMode = useUiModeStore()
+  const board = useBoardStore()
+  const execution = useExecutionStore()
+  const reviews = useReviewStage()
+
+  // A top-level frame IS a service (see `app/types/domain.ts`); modules are sub-frames.
+  const hasService = computed(() => board.blocks.some((b) => b.level === 'frame' && !b.parentId))
+  const hasTask = computed(() => board.blocks.some((b) => b.level === 'task'))
+
+  // Every run gate below is scoped to runs on TASK blocks, because every surface they gate is
+  // reached through a task card and its inspector (the card's Resolve action, the inspector's
+  // step list and result views). A frame-level run — a blueprint pass, an initiative plan —
+  // renders none of those, so counting it would offer a tour onto controls that do not exist.
+  const taskBlockIds = computed(
+    () => new Set(board.blocks.filter((b) => b.level === 'task').map((b) => b.id)),
+  )
+  const isTaskBlock = (blockId: string) => taskBlockIds.value.has(blockId)
+
+  const hasRun = computed(() => execution.instances.some((e) => isTaskBlock(e.blockId)))
+  // A run that finished successfully. `done` only: see `NavGates.boardHasFinishedRun` for
+  // why a `failed` run is not a subject for the review/merge tour.
+  const hasFinishedRun = computed(() =>
+    execution.instances.some((e) => e.status === 'done' && isTaskBlock(e.blockId)),
+  )
+  // Not the store's raw pending counts: those answer "is anything parked", while the tour
+  // these gate anchors on the card affordance a park RENDERS. See `hasActionablePark`.
+  const hasOpenDecision = computed(() =>
+    hasActionablePark(execution.openDecisions, isTaskBlock, reviews.isBackground),
+  )
+  const hasPendingApproval = computed(() =>
+    hasActionablePark(execution.openApprovals, isTaskBlock, reviews.isBackground),
+  )
 
   const infrastructureAvailable = computed(
     () =>
@@ -65,5 +97,27 @@ export function createNavGates(): NavGates {
     get advancedMode() {
       return uiMode.isAdvanced
     },
+    get boardHasService() {
+      return hasService.value
+    },
+    get boardHasTask() {
+      return hasTask.value
+    },
+    get boardHasRun() {
+      return hasRun.value
+    },
+    // The two park kinds read the execution store's existing open-decision / open-approval
+    // projections rather than re-scanning `instances` here, so a tour can never disagree with
+    // the queue that sent the user looking for it — then narrowed to the parks a task card
+    // actually offers an action for (`hasActionablePark`).
+    get boardHasOpenDecision() {
+      return hasOpenDecision.value
+    },
+    get boardHasPendingApproval() {
+      return hasPendingApproval.value
+    },
+    get boardHasFinishedRun() {
+      return hasFinishedRun.value
+    },
   }
 }

package/app/modular/registry.spec.ts

@@ -13,6 +13,12 @@ const NO_GATES: NavGates = {
   accountsEnabled: false,
   isAccountAdmin: false,
   advancedMode: false,
+  boardHasService: false,
+  boardHasTask: false,
+  boardHasRun: false,
+  boardHasOpenDecision: false,
+  boardHasPendingApproval: false,
+  boardHasFinishedRun: false,
 }
 
 describe('app modular registry', () => {

package/app/modular/registry.ts

@@ -2,6 +2,7 @@ import type { AnyModuleDescriptor } from '@modular-vue/core'
 import { createRegistry } from '@modular-vue/runtime'
 import { journeysPlugin } from '@modular-vue/journeys'
 import { navigationModule } from '~/modular/nav-contributions'
+import { tutorialToursModule } from '~/modular/tutorial-tours'
 import type { NavGates } from '~/modular/nav-contributions'
 import type { AppSlots } from '~/modular/slots'
 
@@ -37,7 +38,7 @@ export type AppDeps = {
  * First-party modules the layer always registers. Real feature modules land
  * here as each area is converted; slice 1 adds the navigation catalog.
  */
-const FIRST_PARTY_MODULES: readonly AnyModuleDescriptor[] = [navigationModule]
+const FIRST_PARTY_MODULES: readonly AnyModuleDescriptor[] = [navigationModule, tutorialToursModule]
 
 /**
  * Consumer-contributed modules, collected before the layer resolves its
@@ -109,6 +110,7 @@ export function createAppRegistry(
       taskTypes: [],
       taskTypeFormPanels: [],
       appOverlays: [],
+      tutorialTours: [],
     },
   }).use(journeysPlugin())
   for (const mod of [...FIRST_PARTY_MODULES, ...extraModules, ...consumerModules]) {

package/app/modular/slots.ts

@@ -1,6 +1,7 @@
 import type { Component } from 'vue'
 import type { ComponentEntry, PanelEntry } from '@modular-vue/core'
 import type { Block, CustomAgentKind, CustomTaskType } from '~/types/domain'
+import type { TutorialTour } from '~/utils/tutorial'
 import type { NavContribution } from './nav-contributions'
 
 /**
@@ -31,6 +32,11 @@ 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.
+ *  - `tutorialTours` — the in-app tutorial catalog ({@link TutorialTour}: data-only
+ *    guided tours anchored to `data-testid`s, no components). First-party tours come
+ *    from `modular/tutorial-tours.ts`; a consumer contributes its own to the same slot
+ *    and they appear in the launch prompt beside the built-ins, gated per tour by its
+ *    `when(gates)` predicate in the same reactive `slotFilter` that gates `nav`.
  *  - `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
@@ -52,6 +58,7 @@ export interface AppSlots {
   taskTypes: CustomTaskType[]
   taskTypeFormPanels: ResultViewContribution[]
   appOverlays: OverlayContribution[]
+  tutorialTours: TutorialTour[]
   [key: string]: unknown[]
 }