@cat-factory/app 0.196.0 → 0.197.0

package/app/components/tutorial/TutorialOverlay.logic.ts

@@ -0,0 +1,92 @@
+import { DEFAULT_TARGET_WAIT_MS } from '~/utils/tutorial'
+import type { TutorialStep } from '~/utils/tutorial'
+
+/**
+ * The tour runtime's decision logic, extracted from `TutorialOverlay.vue` so it is
+ * unit-testable (the vitest setup has no SFC transform — same split as
+ * `AppOverlayHost.logic.ts`). The component keeps the DOM work (querying, measuring,
+ * listeners); everything that DECIDES something lives here.
+ */
+
+/**
+ * Which way the step cursor is travelling. It matters only for a step whose anchor
+ * never appears: a skip must continue in the direction the user was already going,
+ * or pressing Back onto a step whose control this deployment doesn't render would
+ * bounce them straight forward again — an unusable Back button.
+ */
+export type TutorialDirection = 'forward' | 'back'
+
+/** What the overlay does with a step whose anchor never appeared. */
+export type SkipOutcome = { kind: 'move'; index: number } | { kind: 'complete' }
+
+/**
+ * What a `data-testid` may look like. Every one of the ~470 test ids in this layer is
+ * lowercase kebab-case, and the e2e suite's convention keeps it that way, so this rejects
+ * nothing real — which is what makes it usable as a GUARD rather than as escaping.
+ *
+ * A tour is DATA and a consumer deployment authors its own, so an id reaches
+ * `querySelector` from outside this package. Escaping it is the obvious move and the wrong
+ * one: `[data-testid="a\"b"]` is valid CSS that real selector engines disagree about (it
+ * throws in happy-dom), so an id with a quote could still take down the tracking interval —
+ * several times a second, for as long as the tour runs. Validating the shape instead means
+ * no selector is ever built from a string that could break one, and an id that fails simply
+ * finds no anchor, which the runtime already handles as a skipped step.
+ */
+export const TARGET_ID_PATTERN = /^[a-z0-9-]+$/
+
+/** Is this a well-formed anchor id, i.e. safe to put in a selector? */
+export function isSafeTargetId(id: string): boolean {
+  return TARGET_ID_PATTERN.test(id)
+}
+
+/** The `data-testid`s a step declares, in priority order (target first, then fallbacks). */
+export function stepTargetIds(step: TutorialStep): string[] {
+  return [step.target, ...(step.altTargets ?? [])].filter((id): id is string => id !== undefined)
+}
+
+/** The selectors to try for a step: its declared ids, minus any that are malformed. */
+export function stepTargetSelectors(step: TutorialStep): string[] {
+  return stepTargetIds(step)
+    .filter(isSafeTargetId)
+    .map((id) => `[data-testid="${id}"]`)
+}
+
+/** How long this step may spend looking for its anchor before it is skipped. */
+export function waitBudgetMs(step: TutorialStep): number {
+  return step.waitForTargetMs ?? DEFAULT_TARGET_WAIT_MS
+}
+
+/**
+ * Where the cursor goes when the current step's anchor never appeared.
+ *
+ * Travelling BACK off the first step has nowhere further back to go, so it reverses to
+ * forward rather than pinning the tour on an anchor that is never coming.
+ */
+export function resolveSkip(
+  index: number,
+  direction: TutorialDirection,
+  total: number,
+): SkipOutcome {
+  if (direction === 'back' && index > 0) return { kind: 'move', index: index - 1 }
+  return index + 1 < total ? { kind: 'move', index: index + 1 } : { kind: 'complete' }
+}
+
+/** Does this real click count as the "now click this" step's advance? */
+export function isTargetClickAdvance(
+  step: TutorialStep | null,
+  targetEl: { contains: (node: Node) => boolean } | null,
+  eventTarget: EventTarget | null,
+): boolean {
+  if (!step || step.advanceOn !== 'target-click' || !targetEl) return false
+  return eventTarget instanceof Node && targetEl.contains(eventTarget)
+}
+
+/**
+ * A tour is ABRIDGED when it reached its end having skipped steps: the controls those
+ * steps point at aren't part of this board/role/deployment. The final card says so
+ * instead of congratulating the user on a walkthrough they never saw — absent and
+ * complete must not render the same.
+ */
+export function tourWasAbridged(skippedStepIds: ReadonlySet<string>): boolean {
+  return skippedStepIds.size > 0
+}

package/app/components/tutorial/TutorialOverlay.vue

@@ -0,0 +1,273 @@
+<script setup lang="ts">
+import {
+  computeCoachMarkLayout,
+  DEFAULT_TARGET_WAIT_MS,
+  TARGET_TRACK_INTERVAL_MS,
+} from '~/utils/tutorial'
+import type { CoachMarkLayout, TutorialRect, TutorialStep } from '~/utils/tutorial'
+import {
+  isTargetClickAdvance,
+  resolveSkip,
+  stepTargetSelectors,
+  tourWasAbridged,
+  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()
+
+const tour = computed(() => tours.value.find((x) => x.id === tutorial.activeTourId) ?? null)
+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 running tour vanished from the slot (a gate flipped, a consumer module withdrew it)
+// or the cursor ran past the end: end the tour instead of rendering a dead overlay.
+watch(
+  () => [tour.value, step.value] as const,
+  ([tr, st]) => {
+    if (tutorial.touring && (!tr || !st)) tutorial.stopTour()
+  },
+  { immediate: true },
+)
+
+const targetEl = ref<HTMLElement | null>(null)
+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)
+const abridged = computed(() => tourWasAbridged(skippedStepIds.value))
+
+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) {
+    targetEl.value = null
+    targetRect.value = null
+  } else {
+    const el = queryTarget(s)
+    targetEl.value = el
+    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)
+  targetEl.value = null
+  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, targetEl.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>
+        <p class="text-sm text-slate-300">{{ t(step.bodyKey) }}</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: skippedStepIds.size }, skippedStepIds.size) }}
+        </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(),