@cat-factory/app 0.196.1 → 0.197.0

package/README.md

@@ -17,6 +17,7 @@ The SPA source lives under `app/` (the Nuxt srcDir).
 - [Layout](#layout)
 - [Interface modes (basic / advanced)](#interface-modes-basic--advanced)
 - [Agent tiers (basic / intermediate / advanced)](#agent-tiers-basic--intermediate--advanced)
+- [In-app tutorial tours](#in-app-tutorial-tours)
 - [Key UI surfaces](#key-ui-surfaces)
 - [Develop & test](#develop--test)
 
@@ -159,6 +160,44 @@ picking what each of them runs on are halves of the same job.
   whatever the tier — the same rule `showOverrideField` states for a single field: a row the
   user can neither read nor clear is worse than a longer list.
 
+## In-app tutorial tours
+
+On first launch (once the board is up and no other startup advisory is open) the app asks
+whether the user wants a guided tour. The answer is SAVED per browser (`stores/tutorial.ts`,
+persisted like the interface tier): "no thanks" stops the prompt for good, closing without
+answering defers it to the next launch, and the command palette's "Take a tour" entry is the
+way back either way.
+
+A tour is **data, not components**: an ordered list of steps, each pointing at an on-screen
+control by its `data-testid` (the e2e anchor vocabulary — cover a control that has none by
+adding the test id first) and carrying i18n keys for its copy. One shared runtime
+(`components/tutorial/TutorialOverlay.vue`) renders every tour: it highlights the current
+step's control, places the tooltip (`utils/tutorial.ts` owns the pure geometry + types),
+advances on Next or — for `advanceOn: 'target-click'` steps — on the user really clicking
+the control, so the app's real response (the actual modal, the actual task) is what the next
+step anchors to. `target-click` is for BUTTONS, where the click is the completed action; a
+text field keeps Next, or the tooltip would leave the instruction the moment the user clicked
+in to type. A step whose anchor never appears within its wait is SKIPPED, because controls
+come and go with RBAC, tier, and deployment wiring: a tour is a set of opportunities, not a
+fixed script. Reaching the end having skipped steps is reported on the final card rather than
+congratulating the user on a walkthrough they did not see — and a tour that could only ever
+be abridged should not be offered at all, which is what each tour's `when(gates)` is for (the
+task-creation tour requires board write AND a service frame to add a task to).
+
+Two runtime constraints worth knowing before changing the overlay: it must keep
+`pointer-events-auto` and swallow `pointerdown`, because Nuxt UI modals are reka-ui
+dismissable layers that set `body { pointer-events: none }` and dismiss on an outside
+pointerdown — without both, the tooltip's own buttons go inert and pressing one closes the
+user's half-filled form. And everything that DECIDES (skip direction, wait budget,
+target-click matching) lives in `components/tutorial/TutorialOverlay.logic.ts` so it is
+unit-tested; the SFC keeps only the DOM work.
+
+The catalog is the `tutorialTours` slot: first-party tours live in
+`modular/tutorial-tours.ts`, and a consumer deployment contributes its own through
+`registerAppModule` — they appear in the launch prompt beside the built-ins, gated per tour
+by its `when(gates)` predicate (the same reactive gates service the nav uses, filtered in
+`navSlotFilter`). Completion is persisted per tour id, so renaming an id resets its state.
+
 ## Extending the layer (consumer modules)
 
 A deployment can contribute its own components — result windows, nav entries, inspector

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

@@ -0,0 +1,126 @@
+import { describe, expect, it } from 'vitest'
+import {
+  isSafeTargetId,
+  isTargetClickAdvance,
+  resolveSkip,
+  stepTargetIds,
+  stepTargetSelectors,
+  tourWasAbridged,
+  waitBudgetMs,
+} from '~/components/tutorial/TutorialOverlay.logic'
+import { DEFAULT_TARGET_WAIT_MS } from '~/utils/tutorial'
+import type { TutorialStep } from '~/utils/tutorial'
+
+const step = (over: Partial<TutorialStep> = {}): TutorialStep => ({
+  id: 'a-step',
+  titleKey: 'tutorial.tours.x.steps.a.title',
+  bodyKey: 'tutorial.tours.x.steps.a.body',
+  ...over,
+})
+
+describe('stepTargetIds', () => {
+  it('lists the target then its fallbacks, in order', () => {
+    expect(
+      stepTargetIds(step({ target: 'frame-add-task', altTargets: ['frame-add-task-empty'] })),
+    ).toEqual(['frame-add-task', 'frame-add-task-empty'])
+  })
+
+  it('is empty for an untargeted (centered) step', () => {
+    expect(stepTargetIds(step())).toEqual([])
+  })
+})
+
+describe('isSafeTargetId', () => {
+  it('accepts the kebab-case ids the repo actually uses', () => {
+    for (const id of ['task-card', 'add-task-submit', 'board-fit-view', 'nav-tutorial', 'h2'])
+      expect(isSafeTargetId(id), id).toBe(true)
+  })
+
+  it('rejects anything that could end up inside a selector as syntax', () => {
+    for (const id of ['od"d', "od'd", 'back\\slash', 'a b', 'a]b', 'Upper', ''])
+      expect(isSafeTargetId(id), id).toBe(false)
+  })
+})
+
+describe('stepTargetSelectors', () => {
+  it('builds the data-testid selectors, target first then fallbacks', () => {
+    const s = step({ target: 'frame-add-task', altTargets: ['frame-add-task-empty'] })
+    expect(stepTargetSelectors(s)).toEqual([
+      '[data-testid="frame-add-task"]',
+      '[data-testid="frame-add-task-empty"]',
+    ])
+  })
+
+  it('drops a malformed id rather than building a selector that could throw', () => {
+    // A tour is DATA a consumer deployment authors, so an id arrives from outside this
+    // package. A bad one must degrade to "anchor not found" (a skipped step) — NOT to a
+    // SyntaxError raised out of the 150ms tracking interval, several times a second.
+    const s = step({ target: 'od"d', altTargets: ['task-card'] })
+    expect(stepTargetSelectors(s)).toEqual(['[data-testid="task-card"]'])
+    for (const selector of stepTargetSelectors(s))
+      expect(() => document.querySelector(selector)).not.toThrow()
+  })
+
+  it('is empty for an untargeted step', () => {
+    expect(stepTargetSelectors(step())).toEqual([])
+  })
+})
+
+describe('waitBudgetMs', () => {
+  it('defaults, and honours a step that waits on a just-opened modal', () => {
+    expect(waitBudgetMs(step())).toBe(DEFAULT_TARGET_WAIT_MS)
+    expect(waitBudgetMs(step({ waitForTargetMs: 8000 }))).toBe(8000)
+  })
+})
+
+describe('resolveSkip', () => {
+  it('continues forward past a missing anchor', () => {
+    expect(resolveSkip(1, 'forward', 4)).toEqual({ kind: 'move', index: 2 })
+  })
+
+  it('completes the tour when the last step is the one that went missing', () => {
+    expect(resolveSkip(3, 'forward', 4)).toEqual({ kind: 'complete' })
+  })
+
+  it('keeps travelling BACK when the user is stepping backwards', () => {
+    // Otherwise Back onto a step this deployment does not render bounces the user
+    // straight forward again, making the button unusable exactly where it is needed.
+    expect(resolveSkip(2, 'back', 4)).toEqual({ kind: 'move', index: 1 })
+  })
+
+  it('reverses to forward rather than pinning on the first step', () => {
+    expect(resolveSkip(0, 'back', 4)).toEqual({ kind: 'move', index: 1 })
+  })
+
+  it('completes a single-step tour whose only anchor never appeared', () => {
+    expect(resolveSkip(0, 'back', 1)).toEqual({ kind: 'complete' })
+    expect(resolveSkip(0, 'forward', 1)).toEqual({ kind: 'complete' })
+  })
+})
+
+describe('isTargetClickAdvance', () => {
+  const el = document.createElement('button')
+  const child = document.createElement('span')
+  el.appendChild(child)
+
+  it('advances on a real click on the highlighted control, or inside it', () => {
+    const s = step({ target: 'add-task-submit', advanceOn: 'target-click' })
+    expect(isTargetClickAdvance(s, el, el)).toBe(true)
+    expect(isTargetClickAdvance(s, el, child)).toBe(true)
+  })
+
+  it('ignores clicks elsewhere, on a Next-advanced step, or with no anchor', () => {
+    const s = step({ target: 'add-task-submit', advanceOn: 'target-click' })
+    expect(isTargetClickAdvance(s, el, document.createElement('div'))).toBe(false)
+    expect(isTargetClickAdvance(s, null, el)).toBe(false)
+    expect(isTargetClickAdvance(step({ target: 'x' }), el, el)).toBe(false)
+    expect(isTargetClickAdvance(null, el, el)).toBe(false)
+  })
+})
+
+describe('tourWasAbridged', () => {
+  it('is true once any step was skipped, so the finish card can say so', () => {
+    expect(tourWasAbridged(new Set())).toBe(false)
+    expect(tourWasAbridged(new Set(['addTask']))).toBe(true)
+  })
+})

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>