@cat-factory/app 0.196.1 → 0.198.0

package/app/components/tutorial/TutorialOverlay.vue

@@ -0,0 +1,307 @@
+<script setup lang="ts">
+import {
+  computeCoachMarkLayout,
+  DEFAULT_TARGET_WAIT_MS,
+  TARGET_TRACK_INTERVAL_MS,
+} from '~/utils/tutorial'
+import type { CoachMarkLayout, TutorialRect, TutorialStep, TutorialTour } from '~/utils/tutorial'
+import {
+  isTargetClickAdvance,
+  resolveSkip,
+  stepTargetSelectors,
+  unexpectedlySkippedSteps,
+  waitBudgetMs,
+} from './TutorialOverlay.logic'
+import type { TutorialDirection } from './TutorialOverlay.logic'
+
+// The one shared tour runtime: resolves the running tour from the `tutorialTours` slot,
+// anchors a highlight ring + tooltip to the current step's `data-testid`, and advances
+// on Next or on a real click on the highlighted control. Mounted (from `pages/index.vue`)
+// only while `tutorial.touring`, so all the DOM tracking below exists only mid-tour.
+//
+// Anchor tracking is a poll, not a one-shot query: board controls move (canvas pan/zoom,
+// panels opening) and appear asynchronously (a step can point INTO the modal the previous
+// step's click opens), so every tick re-queries and re-measures. A target that never
+// appears within the step's wait SKIPS the step — controls are RBAC/tier/deployment
+// dependent, and a tour is a set of opportunities, not a fixed script. Everything that
+// DECIDES rather than measures lives in `TutorialOverlay.logic.ts`, which is unit-tested.
+const { t } = useI18n()
+const tutorial = useTutorialStore()
+const { tours } = useTutorialTours()
+
+/**
+ * The running tour's script, resolved ONCE from the slot when the tour starts and then HELD
+ * for its duration. Gates decide what is OFFERED; they do not get to rewrite a walkthrough
+ * that is already under way.
+ *
+ * Re-reading the gated slot on every flip was fine while the gates were slow-moving facts
+ * (a permission, a connection). Gates over live RUN state flip as a DIRECT RESULT of
+ * following the tour: `answer-park` is offered while something is waiting for a human, so
+ * the moment the user answered — the very thing the tour teaches — its `when` went false,
+ * the slot dropped the tour, and the watch below tore the overlay down one step short of its
+ * own finish card, with no completion recorded. Holding the script also freezes the branch
+ * `resolveTours` picked, so a step can't be swapped underneath a stationary cursor when a
+ * board that had both a decision and an approval loses one of them mid-tour.
+ */
+const tour = shallowRef<TutorialTour | null>(null)
+watch(
+  () => tutorial.activeTourId,
+  (id) => {
+    // Read untracked (a watch callback registers no dependencies), which is what pins the
+    // script: only starting a DIFFERENT tour re-resolves it.
+    tour.value = id ? (tours.value.find((x) => x.id === id) ?? null) : null
+  },
+  { immediate: true },
+)
+
+const step = computed<TutorialStep | null>(() => tour.value?.steps[tutorial.stepIndex] ?? null)
+const total = computed(() => tour.value?.steps.length ?? 0)
+const isLast = computed(() => tour.value !== null && tutorial.stepIndex >= total.value - 1)
+
+// The tour could not be resolved when it started (a stale persisted id, or a tour this board
+// is not offered at all) or the cursor ran past the end: end it instead of rendering a dead
+// overlay. Since the script is held, this can no longer fire because a gate flipped mid-tour.
+watch(
+  () => [tour.value, step.value] as const,
+  ([tr, st]) => {
+    if (tutorial.touring && (!tr || !st)) tutorial.stopTour()
+  },
+  { immediate: true },
+)
+
+const targetRect = ref<TutorialRect | null>(null)
+const cardEl = ref<HTMLElement | null>(null)
+const layout = ref<CoachMarkLayout>({ top: -9999, left: -9999, placement: 'center' })
+
+/**
+ * Wall-clock deadline for the current step's anchor search. A deadline rather than a
+ * per-tick counter: `measure()` also runs on resize and on every step change, so counting
+ * invocations let a resize drag burn a "4000 ms" budget in a fraction of that time.
+ */
+const searchDeadline = ref(0)
+/** Which way `skipMissingStep` travels — see `resolveSkip`. */
+const direction = ref<TutorialDirection>('forward')
+/** Steps this run gave up on, so the final card can be honest about an abridged tour. */
+const skippedStepIds = ref<Set<string>>(new Set())
+
+/** A targeted step whose anchor hasn't been found yet (renders the waiting note). */
+const searching = computed(() => step.value?.target !== undefined && targetRect.value === null)
+/** The skips the final card must own up to — a branch-gated step's absence is not one. */
+const unexpectedSkips = computed(() =>
+  unexpectedlySkippedSteps(skippedStepIds.value, tour.value?.steps ?? []),
+)
+const abridged = computed(() => unexpectedSkips.value.length > 0)
+
+const viewport = () => ({ width: window.innerWidth, height: window.innerHeight })
+/** The tooltip's own size, or a sensible guess before it has rendered once. */
+const cardSize = () => ({
+  width: cardEl.value?.offsetWidth ?? 320,
+  height: cardEl.value?.offsetHeight ?? 180,
+})
+
+function queryTarget(s: TutorialStep): HTMLElement | null {
+  for (const selector of stepTargetSelectors(s)) {
+    const el = document.querySelector<HTMLElement>(selector)
+    // `getClientRects().length` distinguishes a mounted-but-hidden control (display:none
+    // drawer item) from a visible one; pointing at an invisible control helps nobody.
+    if (el && el.getClientRects().length > 0) return el
+  }
+  return null
+}
+
+/** Give up on a step whose anchor never appeared, continuing the user's own direction. */
+function skipMissingStep(s: TutorialStep) {
+  skippedStepIds.value = new Set(skippedStepIds.value).add(s.id)
+  const outcome = resolveSkip(tutorial.stepIndex, direction.value, total.value)
+  if (outcome.kind === 'complete') tutorial.completeTour()
+  else tutorial.setStepIndex(outcome.index)
+}
+
+function measure() {
+  const s = step.value
+  if (!s) return
+  if (!s.target) {
+    targetRect.value = null
+  } else {
+    const el = queryTarget(s)
+    if (!el) {
+      targetRect.value = null
+      // Centered while searching: the card must not sit at the PREVIOUS step's anchor —
+      // nor at its off-screen initial position — pointing at nothing.
+      layout.value = computeCoachMarkLayout(null, cardSize(), viewport())
+      if (performance.now() >= searchDeadline.value) skipMissingStep(s)
+      return
+    }
+    const r = el.getBoundingClientRect()
+    targetRect.value = { top: r.top, left: r.left, width: r.width, height: r.height }
+  }
+  layout.value = computeCoachMarkLayout(
+    s.target ? targetRect.value : null,
+    cardSize(),
+    viewport(),
+    s.placement,
+  )
+}
+
+// Re-arm per step: fresh wait budget, drop the stale anchor immediately (the ring must not
+// linger on the previous control while the next anchor is located), and re-measure once
+// the card has re-rendered its new copy (its size feeds the layout).
+watch(step, async (s) => {
+  searchDeadline.value = performance.now() + (s ? waitBudgetMs(s) : DEFAULT_TARGET_WAIT_MS)
+  targetRect.value = null
+  await nextTick()
+  measure()
+})
+
+function advance() {
+  direction.value = 'forward'
+  if (isLast.value) tutorial.completeTour()
+  else tutorial.setStepIndex(tutorial.stepIndex + 1)
+}
+
+function back() {
+  direction.value = 'back'
+  tutorial.setStepIndex(tutorial.stepIndex - 1)
+}
+
+// "Now click this" steps: watch real clicks (capture phase, so a stopPropagation inside a
+// control can't hide them) and follow along AFTER the app has reacted — the deferral lets
+// the real handler open its modal/submit its form before the tour moves its anchor.
+function onDocumentClick(event: MouseEvent) {
+  if (isTargetClickAdvance(step.value, event.target)) {
+    window.setTimeout(advance, 0)
+  }
+}
+
+/** Esc ends the tour, matching every other dismissible surface in the app. */
+function onKeydown(event: KeyboardEvent) {
+  if (event.key === 'Escape') tutorial.stopTour()
+}
+
+let trackTimer: ReturnType<typeof setInterval> | undefined
+onMounted(() => {
+  const s = step.value
+  searchDeadline.value = performance.now() + (s ? waitBudgetMs(s) : DEFAULT_TARGET_WAIT_MS)
+  document.addEventListener('click', onDocumentClick, true)
+  document.addEventListener('keydown', onKeydown)
+  window.addEventListener('resize', measure)
+  trackTimer = setInterval(measure, TARGET_TRACK_INTERVAL_MS)
+  measure()
+})
+onUnmounted(() => {
+  document.removeEventListener('click', onDocumentClick, true)
+  document.removeEventListener('keydown', onKeydown)
+  window.removeEventListener('resize', measure)
+  if (trackTimer !== undefined) clearInterval(trackTimer)
+})
+</script>
+
+<template>
+  <!-- Teleported so board/panel stacking contexts can't clip the marks; z-[70] sits above
+       the app's modals (z-50s), since steps legitimately point INTO an open modal. -->
+  <Teleport to="body">
+    <div v-if="step" data-testid="tutorial-overlay">
+      <div
+        v-if="targetRect"
+        class="ring-primary-400 outline-primary-400/25 pointer-events-none fixed z-[70] rounded-lg outline-4 ring-2 transition-all duration-150"
+        :style="{
+          top: `${targetRect.top - 4}px`,
+          left: `${targetRect.left - 4}px`,
+          width: `${targetRect.width + 8}px`,
+          height: `${targetRect.height + 8}px`,
+        }"
+        data-testid="tutorial-highlight"
+      />
+      <!-- `pointer-events-auto` AND the swallowed `pointerdown` are both required for the
+           steps that point INSIDE an open modal: Nuxt UI's modal is a reka-ui dismissable
+           layer, which sets `body { pointer-events: none }` (leaving this card inert) and
+           dismisses on a document-level pointerdown outside its own content (so a press on
+           this card would close the user's half-filled form instead of pressing a button). -->
+      <div
+        ref="cardEl"
+        role="dialog"
+        aria-live="polite"
+        :aria-label="t('tutorial.overlay.ariaLabel')"
+        class="pointer-events-auto fixed z-[70] w-80 max-w-[calc(100vw-16px)] rounded-xl border border-slate-700 bg-slate-900 p-4 shadow-2xl"
+        :style="{ top: `${layout.top}px`, left: `${layout.left}px` }"
+        data-testid="tutorial-tooltip"
+        @pointerdown.stop
+      >
+        <div class="mb-1 flex items-start justify-between gap-3">
+          <h3 class="text-sm font-semibold text-slate-100">{{ t(step.titleKey) }}</h3>
+          <span class="shrink-0 text-xs text-slate-500">
+            {{ t('tutorial.overlay.progress', { current: tutorial.stepIndex + 1, total }) }}
+          </span>
+        </div>
+        <!-- `bodyParams` carries the fixed proper nouns a step names (a repository slug),
+             which live in the catalog's `{named}` placeholders rather than in nine
+             translations of the same literal. Absent for most steps. -->
+        <p class="text-sm text-slate-300">{{ t(step.bodyKey, step.bodyParams ?? {}) }}</p>
+        <p
+          v-if="searching"
+          class="mt-2 flex items-center gap-1.5 text-xs text-slate-400"
+          data-testid="tutorial-searching"
+        >
+          <UIcon name="i-lucide-loader" class="h-3.5 w-3.5 animate-spin" />
+          {{ t('tutorial.overlay.searching') }}
+        </p>
+        <p
+          v-else-if="step.advanceOn === 'target-click'"
+          class="text-primary-300 mt-2 text-xs"
+          data-testid="tutorial-click-hint"
+        >
+          {{ t('tutorial.overlay.clickHint') }}
+        </p>
+        <!-- Reaching the end having skipped steps is NOT the same as having been shown the
+             whole tour: say so rather than congratulating the user either way. -->
+        <p
+          v-if="isLast && abridged"
+          class="mt-2 text-xs text-amber-300/90"
+          data-testid="tutorial-abridged"
+        >
+          {{
+            t(
+              'tutorial.overlay.abridged',
+              { count: unexpectedSkips.length },
+              unexpectedSkips.length,
+            )
+          }}
+        </p>
+        <div class="mt-3 flex items-center justify-between gap-2">
+          <UButton
+            size="xs"
+            variant="ghost"
+            color="neutral"
+            data-testid="tutorial-skip"
+            @click="tutorial.stopTour()"
+          >
+            {{ t('tutorial.overlay.skip') }}
+          </UButton>
+          <div class="flex items-center gap-2">
+            <UButton
+              v-if="tutorial.stepIndex > 0"
+              size="xs"
+              variant="soft"
+              color="neutral"
+              data-testid="tutorial-back"
+              @click="back()"
+            >
+              {{ t('tutorial.overlay.back') }}
+            </UButton>
+            <!-- A click-to-advance step hides Next so the real control is the only way
+                 forward (its Done form stays on a last step, which must be finishable). -->
+            <UButton
+              v-if="step.advanceOn !== 'target-click' || isLast"
+              size="xs"
+              color="primary"
+              data-testid="tutorial-next"
+              @click="advance()"
+            >
+              {{ isLast ? t('tutorial.overlay.done') : t('tutorial.overlay.next') }}
+            </UButton>
+          </div>
+        </div>
+      </div>
+    </div>
+  </Teleport>
+</template>

package/app/components/tutorial/TutorialPrompt.vue

@@ -0,0 +1,102 @@
+<script setup lang="ts">
+// The tutorial launch prompt: asks once on first launch whether the user wants a guided
+// tour, and doubles as the tour picker for later visits (command palette: "Take a tour").
+// Lists whatever the merged `tutorialTours` slot offers this user (first-party + consumer
+// tours, RBAC-gated per tour), so it grows with the catalog rather than hard-coding tours.
+//
+// The decision semantics live in the store: starting a tour or "No thanks" is SAVED (the
+// prompt never auto-opens again), while closing without answering defers to next launch.
+const { t } = useI18n()
+const tutorial = useTutorialStore()
+const { tours } = useTutorialTours()
+
+const open = computed({
+  get: () => tutorial.promptOpen,
+  set: (v: boolean) => (v ? tutorial.openPrompt() : tutorial.closePrompt()),
+})
+
+// Only an unanswered prompt offers the persistent "No thanks"; once a decision exists this
+// is just a picker, and the only dismissal left is a plain close.
+const undecided = computed(() => tutorial.decision === null)
+</script>
+
+<template>
+  <UModal v-model:open="open" :title="t('tutorial.prompt.title')" :ui="{ content: 'max-w-lg' }">
+    <template #body>
+      <!-- NOTE for spec authors: this marks the modal's BODY, so it is the "prompt is
+           showing" signal, not a container for everything in the prompt. The footer's
+           decline/close buttons are in a SIBLING slot — address them from the page by
+           their own test ids rather than scoping a locator under this one. -->
+      <div class="space-y-4" data-testid="tutorial-prompt">
+        <p class="text-sm text-slate-300">{{ t('tutorial.prompt.intro') }}</p>
+        <ul class="space-y-2">
+          <li
+            v-for="tour in tours"
+            :key="tour.id"
+            class="flex items-center gap-3 rounded-lg border border-slate-800 bg-slate-900/60 p-3"
+          >
+            <UIcon
+              :name="tour.icon ?? 'i-lucide-compass'"
+              class="h-5 w-5 shrink-0 text-primary-400"
+            />
+            <div class="min-w-0 flex-1">
+              <div class="flex items-center gap-2">
+                <span class="text-sm font-medium text-slate-100">{{ t(tour.titleKey) }}</span>
+                <UBadge
+                  v-if="tutorial.isCompleted(tour.id)"
+                  color="success"
+                  variant="subtle"
+                  size="sm"
+                  data-testid="tutorial-tour-completed"
+                >
+                  {{ t('tutorial.prompt.completed') }}
+                </UBadge>
+              </div>
+              <p class="text-xs text-slate-400">{{ t(tour.descriptionKey) }}</p>
+            </div>
+            <UButton
+              size="sm"
+              color="primary"
+              :variant="tutorial.isCompleted(tour.id) ? 'soft' : 'solid'"
+              :data-testid="`tutorial-start-${tour.id}`"
+              @click="tutorial.startTour(tour.id)"
+            >
+              {{
+                tutorial.isCompleted(tour.id)
+                  ? t('tutorial.prompt.restart')
+                  : t('tutorial.prompt.start')
+              }}
+            </UButton>
+          </li>
+        </ul>
+        <!-- Every tour gated away (e.g. a viewer on a write-only catalog): say so rather
+             than showing an unexplained empty list. -->
+        <p v-if="tours.length === 0" class="text-sm text-slate-400">
+          {{ t('tutorial.prompt.empty') }}
+        </p>
+      </div>
+    </template>
+    <template #footer>
+      <div class="flex w-full items-center justify-between gap-2">
+        <UButton
+          v-if="undecided"
+          color="neutral"
+          variant="ghost"
+          data-testid="tutorial-decline"
+          @click="tutorial.decline()"
+        >
+          {{ t('tutorial.prompt.decline') }}
+        </UButton>
+        <span v-else />
+        <UButton
+          color="neutral"
+          variant="soft"
+          data-testid="tutorial-close"
+          @click="tutorial.closePrompt()"
+        >
+          {{ undecided ? t('tutorial.prompt.later') : t('common.close') }}
+        </UButton>
+      </div>
+    </template>
+  </UModal>
+</template>

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.spec.ts

@@ -49,7 +49,10 @@ beforeEach(() => {
   }
   vi.stubGlobal('useToast', () => ({ add, update }))
   vi.stubGlobal('useUiStore', () => ui)
-  vi.stubGlobal('useI18n', () => ({ t, te: (key: string) => hasKey(key) }))
+  // Stubbed on the Nuxt app's GLOBAL i18n instance, which is what this composable resolves
+  // (never `useI18n()`): it is called from store setup, where no component instance exists.
+  // See `frontend/app/README.md` — "A store must be instantiable outside a component setup".
+  vi.stubGlobal('useNuxtApp', () => ({ $i18n: { t, te: (key: string) => hasKey(key) } }))
 })
 
 function conflict(reason?: string, details: Record<string, unknown> = {}, message?: string) {