@cat-factory/app 0.196.0 → 0.197.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.
@@ -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',
@@ -460,9 +488,9 @@ export const NAV_CONTRIBUTIONS: readonly NavContribution[] = [
   {
     // Deliberately NOT `advanced`: this is the way BACK. Basic mode is the shipped default, so
     // for most users the sidebar switcher is their first sight of the tier — and in the basic
-    // rail it renders icon-only, which is a thin thread to hang the entire advanced half of the
-    // product on. The palette is reachable in both tiers, searchable by name, and is already
-    // "the primary way to reach every action", so the tier belongs in it.
+    // rail it collapses to a single toggle, which is a thin thread to hang the entire advanced
+    // half of the product on. The palette is reachable in both tiers, searchable by name, and
+    // is already "the primary way to reach every action", so the tier belongs in it.
     id: 'ui-mode',
     labelKey: 'layout.commandBar.cmd.toggleUiMode',
     icon: 'i-lucide-toggle-right',
@@ -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[]
 }
 

package/app/modular/tutorial-tours.spec.ts

@@ -0,0 +1,107 @@
+import { describe, expect, it } from 'vitest'
+import en from '../../i18n/locales/en.json'
+import { TUTORIAL_TOURS, tutorialToursModule } from '~/modular/tutorial-tours'
+import { NAV_CONTRIBUTIONS, navSlotFilter } from '~/modular/nav-contributions'
+import { isSafeTargetId } from '~/components/tutorial/TutorialOverlay.logic'
+import type { AppSlots, NavGates } from '~/modular/nav-contributions'
+
+const ALL_GATES: NavGates = {
+  canWriteBoard: true,
+  canManageIntegrations: true,
+  canManageSettings: true,
+  githubAvailable: true,
+  libraryAvailable: true,
+  infrastructureAvailable: true,
+  accountsEnabled: true,
+  isAccountAdmin: true,
+  advancedMode: true,
+  boardHasService: true,
+}
+
+const slots = (): AppSlots =>
+  ({
+    nav: [...NAV_CONTRIBUTIONS],
+    tutorialTours: [...TUTORIAL_TOURS],
+  }) as unknown as AppSlots
+
+/** Resolve a dot-path against the en catalog; undefined when any hop is missing. */
+function lookupKey(key: string): unknown {
+  return key
+    .split('.')
+    .reduce<unknown>((node, part) => (node as Record<string, unknown> | undefined)?.[part], en)
+}
+
+describe('the built-in tutorial tour catalog', () => {
+  it('has unique tour ids and unique step ids within each tour', () => {
+    const tourIds = TUTORIAL_TOURS.map((t) => t.id)
+    expect(new Set(tourIds).size).toBe(tourIds.length)
+    for (const tour of TUTORIAL_TOURS) {
+      const stepIds = tour.steps.map((s) => s.id)
+      expect(new Set(stepIds).size).toBe(stepIds.length)
+      expect(tour.steps.length).toBeGreaterThan(0)
+    }
+  })
+
+  it('resolves every i18n key it names against the en catalog', () => {
+    // Tour copy is looked up with runtime-assembled keys, which the typed-key check
+    // cannot cover (i18n drift-guard tier 2): pin the catalog here instead, so a renamed
+    // key or a new step without copy fails a test rather than rendering a raw key path.
+    for (const tour of TUTORIAL_TOURS) {
+      for (const key of [tour.titleKey, tour.descriptionKey]) {
+        expect(typeof lookupKey(key), key).toBe('string')
+      }
+      for (const s of tour.steps) {
+        for (const key of [s.titleKey, s.bodyKey]) {
+          expect(typeof lookupKey(key), key).toBe('string')
+        }
+      }
+    }
+  })
+
+  it('names plain data-testid values as targets, never selectors', () => {
+    for (const tour of TUTORIAL_TOURS) {
+      for (const s of tour.steps) {
+        for (const target of [s.target, ...(s.altTargets ?? [])]) {
+          if (target === undefined) continue
+          // Asserted through the runtime's OWN guard, not a copy of its regex: the overlay
+          // drops an id this rejects, so a built-in tour that tripped it would silently
+          // lose the step rather than fail here.
+          expect(isSafeTargetId(target), `${tour.id}/${s.id}: ${target}`).toBe(true)
+        }
+      }
+    }
+  })
+
+  it('is contributed to the tutorialTours slot by the module', () => {
+    expect(tutorialToursModule.slots?.tutorialTours).toEqual([...TUTORIAL_TOURS])
+  })
+})
+
+describe('navSlotFilter over tutorialTours', () => {
+  it('keeps every tour for a fully-gated user', () => {
+    const filtered = navSlotFilter(slots(), { gates: ALL_GATES })
+    expect(filtered.tutorialTours.map((t) => t.id)).toEqual(TUTORIAL_TOURS.map((t) => t.id))
+  })
+
+  it('drops the task-creating tour for a read-only viewer', () => {
+    const viewer: NavGates = { ...ALL_GATES, canWriteBoard: false }
+    const filtered = navSlotFilter(slots(), { gates: viewer })
+    const ids = filtered.tutorialTours.map((t) => t.id)
+    expect(ids).toContain('board-basics')
+    expect(ids).not.toContain('first-task')
+  })
+
+  it('drops the task-creating tour on a board with no service to add a task to', () => {
+    // Every targeted step of that tour would time out in turn and it would then claim to
+    // have taught the core loop; `board-basics` is what an empty board can deliver.
+    const emptyBoard: NavGates = { ...ALL_GATES, boardHasService: false }
+    const filtered = navSlotFilter(slots(), { gates: emptyBoard })
+    const ids = filtered.tutorialTours.map((t) => t.id)
+    expect(ids).toEqual(['board-basics'])
+  })
+
+  it('passes tours through untouched when no gates service is wired', () => {
+    const filtered = navSlotFilter(slots(), {})
+    expect(filtered.tutorialTours.map((t) => t.id)).toEqual(TUTORIAL_TOURS.map((t) => t.id))
+  })
+})

package/app/modular/tutorial-tours.ts

@@ -0,0 +1,147 @@
+import { defineModule } from '@modular-vue/core'
+import type { TutorialTour } from '~/utils/tutorial'
+
+/**
+ * The first-party tutorial-tour catalog, contributed to the `tutorialTours` slot the same
+ * way the nav catalog fills `nav`: declared ONCE as data, rendered by one shared runtime
+ * (`TutorialOverlay`), and open to consumer deployments — `registerAppModule` a module
+ * with its own `tutorialTours` entries and they appear in the launch prompt beside these.
+ *
+ * Authoring rules (what keeps a tour evolvable as the app changes):
+ *
+ *  - A step points at a control by its `data-testid` — the same stable anchor vocabulary
+ *    the e2e suite owns. Covering a control that has none means adding the test id first
+ *    (a behaviour-neutral change), never inventing a parallel attribute.
+ *  - A missing anchor SKIPS the step rather than stranding the tour: controls come and go
+ *    with RBAC, interface tier, and deployment wiring, so a tour must be a set of
+ *    opportunities, not a fixed script. Gate a whole tour on `when` only when its SUBJECT
+ *    requires it (e.g. board-write for a tour that creates a task).
+ *  - "Now click this" steps use `advanceOn: 'target-click'` so the user drives the real
+ *    control and the app's real response (the actual modal, the actual task) is what the
+ *    next step anchors to. Steps whose anchor only exists after that response give it a
+ *    longer `waitForTargetMs`.
+ *  - Copy lives under `tutorial.tours.<tourCamelId>.steps.<stepId>` in the i18n catalogs;
+ *    tours never carry display strings.
+ */
+export const TUTORIAL_TOURS: readonly TutorialTour[] = [
+  {
+    id: 'board-basics',
+    order: 10,
+    icon: 'i-lucide-map',
+    titleKey: 'tutorial.tours.boardBasics.title',
+    descriptionKey: 'tutorial.tours.boardBasics.description',
+    steps: [
+      {
+        id: 'welcome',
+        titleKey: 'tutorial.tours.boardBasics.steps.welcome.title',
+        bodyKey: 'tutorial.tours.boardBasics.steps.welcome.body',
+      },
+      {
+        id: 'canvas',
+        target: 'board-canvas',
+        placement: 'right',
+        titleKey: 'tutorial.tours.boardBasics.steps.canvas.title',
+        bodyKey: 'tutorial.tours.boardBasics.steps.canvas.body',
+      },
+      {
+        id: 'sidebar',
+        target: 'sidebar',
+        placement: 'right',
+        titleKey: 'tutorial.tours.boardBasics.steps.sidebar.title',
+        bodyKey: 'tutorial.tours.boardBasics.steps.sidebar.body',
+      },
+      {
+        id: 'commandBar',
+        target: 'command-bar-launcher',
+        placement: 'right',
+        titleKey: 'tutorial.tours.boardBasics.steps.commandBar.title',
+        bodyKey: 'tutorial.tours.boardBasics.steps.commandBar.body',
+      },
+      {
+        id: 'toolbar',
+        target: 'board-fit-view',
+        placement: 'bottom',
+        titleKey: 'tutorial.tours.boardBasics.steps.toolbar.title',
+        bodyKey: 'tutorial.tours.boardBasics.steps.toolbar.body',
+      },
+      {
+        id: 'finish',
+        titleKey: 'tutorial.tours.boardBasics.steps.finish.title',
+        bodyKey: 'tutorial.tours.boardBasics.steps.finish.body',
+      },
+    ],
+  },
+  {
+    id: 'first-task',
+    order: 20,
+    icon: 'i-lucide-list-plus',
+    titleKey: 'tutorial.tours.firstTask.title',
+    descriptionKey: 'tutorial.tours.firstTask.description',
+    // Creating a task is a board WRITE; a viewer has no add-task button to point at.
+    // It also needs somewhere to PUT the task: on a board with no service frame every
+    // targeted step below would time out in turn, so the tour would spend half a minute
+    // hunting for controls and then claim to have taught the core loop. Offering it only
+    // once a service exists is the honest version — and the launch prompt still lists
+    // `board-basics`, which is the tour an empty board can actually deliver.
+    when: (gates) => gates.canWriteBoard && gates.boardHasService,
+    steps: [
+      {
+        id: 'intro',
+        titleKey: 'tutorial.tours.firstTask.steps.intro.title',
+        bodyKey: 'tutorial.tours.firstTask.steps.intro.body',
+      },
+      {
+        id: 'addTask',
+        target: 'frame-add-task',
+        // An empty frame renders its add-task affordance as a full-width button instead.
+        altTargets: ['frame-add-task-empty'],
+        advanceOn: 'target-click',
+        placement: 'bottom',
+        titleKey: 'tutorial.tours.firstTask.steps.addTask.title',
+        bodyKey: 'tutorial.tours.firstTask.steps.addTask.body',
+      },
+      {
+        id: 'describe',
+        target: 'add-task-title',
+        // Deliberately NOT `target-click`: clicking a text field is how you START typing,
+        // so click-to-advance would move the tooltip off the instruction the moment the
+        // user acted on it. The user reads, types, and presses Next when they are ready;
+        // `target-click` is for buttons, where the click IS the completed action.
+        placement: 'right',
+        // The anchor lives inside the modal the previous click opens; allow it to mount.
+        waitForTargetMs: 8000,
+        titleKey: 'tutorial.tours.firstTask.steps.describe.title',
+        bodyKey: 'tutorial.tours.firstTask.steps.describe.body',
+      },
+      {
+        id: 'create',
+        target: 'add-task-submit',
+        advanceOn: 'target-click',
+        placement: 'top',
+        titleKey: 'tutorial.tours.firstTask.steps.create.title',
+        bodyKey: 'tutorial.tours.firstTask.steps.create.body',
+      },
+      {
+        id: 'card',
+        target: 'task-card',
+        placement: 'bottom',
+        // The card arrives over the live event stream after the create round-trips.
+        waitForTargetMs: 10000,
+        titleKey: 'tutorial.tours.firstTask.steps.card.title',
+        bodyKey: 'tutorial.tours.firstTask.steps.card.body',
+      },
+      {
+        id: 'finish',
+        titleKey: 'tutorial.tours.firstTask.steps.finish.title',
+        bodyKey: 'tutorial.tours.firstTask.steps.finish.body',
+      },
+    ],
+  },
+]
+
+/** The module that contributes the catalog; registered by `createAppRegistry`. */
+export const tutorialToursModule = defineModule({
+  id: 'cat-factory:tutorial-tours',
+  version: '1.0.0',
+  slots: { tutorialTours: [...TUTORIAL_TOURS] },
+})