@cat-factory/app 0.196.1 → 0.197.0

package/app/composables/pipelineErrorToast/bespokeConflicts.ts

@@ -0,0 +1,181 @@
+import type { ParsedConflict } from '~/composables/usePipelineErrorToast'
+
+/**
+ * The bespoke conflict toasts: the five 409 reasons whose copy interpolates runtime detail and
+ * whose remedy is a one-click jump into the panel that fixes them. Split out of
+ * {@link usePipelineErrorToast} purely for size — it closes over the SAME toast / ui / i18n
+ * handles, so behaviour is identical to the former in-composable functions.
+ */
+export function createBespokeConflictToasts(deps: {
+  toast: ReturnType<typeof useToast>
+  ui: ReturnType<typeof useUiStore>
+  t: ReturnType<typeof useI18n>['t']
+  te: ReturnType<typeof useI18n>['te']
+}): (conflict: ParsedConflict) => boolean {
+  const { toast, ui, t, te } = deps
+  // 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
+    }
+  }
+
+  return presentBespokeConflict
+}

package/app/composables/useNavContributions.ts

@@ -47,6 +47,7 @@ export function useNavContributions() {
     operatorDashboard: () => ui.openOperatorDashboard(),
     reports: () => ui.openReports(),
     shortcuts: () => ui.openShortcutsHelp(),
+    tutorial: () => useTutorialStore().openPrompt(),
     // No-op under an env pin (`setMode` refuses), so the palette entry matches the sidebar
     // switcher's read-only state rather than pretending to flip a tier the resolver fixes.
     toggleUiMode: () => useUiModeStore().toggleMode(),

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.
@@ -332,169 +333,10 @@ export function usePipelineErrorToast() {
   const ui = useUiStore()
   const { t, te } = 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,7 @@ 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,
 }
 
 const ALL_GATES: NavGates = {
@@ -37,6 +38,7 @@ const ALL_GATES: NavGates = {
   accountsEnabled: true,
   isAccountAdmin: true,
   advancedMode: true,
+  boardHasService: true,
 }
 
 const slots = (): AppSlots => ({
@@ -47,6 +49,7 @@ const slots = (): AppSlots => ({
   taskTypes: [],
   taskTypeFormPanels: [],
   appOverlays: [],
+  tutorialTours: [],
 })
 const ids = (s: unknown) => (s as AppSlots).nav.map((i) => i.id)
 
@@ -312,6 +315,7 @@ describe('nav grouping helpers', () => {
       'sandbox',
       'keyboard-shortcuts',
       'ui-mode',
+      'tutorial',
     ])
   })
 

package/app/modular/nav-contributions.ts

@@ -81,6 +81,14 @@ 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
 }
 
 /** Command-palette placement + copy for a contribution that appears in the palette. */
@@ -119,6 +127,7 @@ export const NAV_ACTIONS = [
   'operatorDashboard',
   'reports',
   'shortcuts',
+  'tutorial',
   'toggleUiMode',
 ] as const
 
@@ -445,6 +454,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 +531,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 +541,12 @@ 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. Same
+    // gates-absent pass-through as `nav`.
+    tutorialTours: gates
+      ? tutorialTours.filter((t) => (t.when ? t.when(gates) : true))
+      : tutorialTours,
   }
 }
 

package/app/modular/nav-gates.ts

@@ -25,6 +25,10 @@ export function createNavGates(): NavGates {
   const auth = useAuthStore()
   const providerConnections = useProviderConnectionsStore()
   const uiMode = useUiModeStore()
+  const board = useBoardStore()
+
+  // 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 infrastructureAvailable = computed(
     () =>
@@ -65,5 +69,8 @@ export function createNavGates(): NavGates {
     get advancedMode() {
       return uiMode.isAdvanced
     },
+    get boardHasService() {
+      return hasService.value
+    },
   }
 }

package/app/modular/registry.spec.ts

@@ -13,6 +13,7 @@ const NO_GATES: NavGates = {
   accountsEnabled: false,
   isAccountAdmin: false,
   advancedMode: false,
+  boardHasService: 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[]
 }