@cat-factory/app 0.202.0 → 0.204.0

package/app/components/pipeline/PipelineBuilder.vue

@@ -7,6 +7,7 @@ import AgentKindIcon from '~/components/pipeline/AgentKindIcon.vue'
 import AgentPromptEditor from '~/components/pipeline/AgentPromptEditor.vue'
 import EstimateThresholdFields from '~/components/pipeline/EstimateThresholdFields.vue'
 import OutputBudgetInput from '~/components/pipeline/OutputBudgetInput.vue'
+import BinaryOutputStepPicker from '~/components/pipeline/BinaryOutputStepPicker.vue'
 import { ESTIMATE_AXES, ESTIMATE_AXIS_FIELD, type EstimateAxis } from '~/utils/estimateGating'
 import { showOverrideField } from '~/utils/uiMode'
 import {
@@ -202,6 +203,36 @@ const stepsDisallowedByPurpose = computed(() =>
   }),
 )
 
+// The workspace's foundational-services catalog, for the binary-output storage/context picker.
+const foundational = useFoundationalServicesStore()
+
+/**
+ * Whether this step's kind is a BINARY-OUTPUT generator, and therefore needs the storage +
+ * context picker. Read off the kind's projected `binaryOutput` flag rather than a kind-id list,
+ * so a deployment's generator opts in by carrying the trait exactly as the engine's own checks
+ * key on it.
+ *
+ * Deliberately NOT behind `showOverrideField` / `isAdvanced` the way the variant picker is: a
+ * variant OVERRIDES what the kind ships, while this selection is REQUIRED. A basic-mode user
+ * who cannot see it has a step that cannot be saved and no way to find out why.
+ */
+function showBinaryOutputPicker(kind: AgentKind): boolean {
+  return agentKindMeta(kind).binaryOutput === true
+}
+
+// An enabled generator step with no storage selection — mirrors the backend save/start
+// rejection (`assertValidBinaryOutputSteps`), surfaced as an inline hint so the user fixes it
+// before the round trip. Same disposition as `skillStepNeedsPick`, for the same reason: both
+// are a step parametrized by a selection it cannot run without.
+const binaryOutputStepNeedsPick = computed(() =>
+  pipelines.draft.some(
+    (kind, i) =>
+      showBinaryOutputPicker(kind) &&
+      pipelines.draftEnabled[i] !== false &&
+      !pipelines.draftBinaryOutput(i)?.storageServiceId,
+  ),
+)
+
 // A step's picked skill id is no longer in the account catalog (the source dir was renamed or
 // unlinked). The step will fail cleanly at dispatch; flag it so the user re-picks.
 function skillMissing(index: number): boolean {
@@ -226,6 +257,11 @@ watch(open, (isOpen) => {
   // The workspace's per-kind output ceilings, which the per-step field shows as its inherited
   // placeholder and the prompt editor edits. Best-effort on the same terms as the prompt index.
   if (isOpen) agentSettings.load().catch(() => {})
+  // The resolved foundational-services catalog, which the binary-output picker offers from.
+  // Single-flighted per workspace, so this shares the panel's load rather than adding one. A
+  // failure is not swallowed into an empty picker: the store records `available: false`, and
+  // the picker says the catalog is unreachable rather than "no services exist".
+  if (isOpen) void foundational.ensureProbed()
 })
 
 function add(kind: AgentKind) {
@@ -531,6 +567,15 @@ async function clone(p: Pipeline) {
             {{ t('pipeline.builder.skillNeedsPick') }}
           </p>
 
+          <p
+            v-if="binaryOutputStepNeedsPick"
+            class="mb-2 flex items-center gap-1.5 rounded-md border border-amber-800/50 bg-amber-950/30 px-2 py-1 text-[11px] text-amber-300"
+            data-testid="binary-output-needs-pick"
+          >
+            <UIcon name="i-lucide-alert-triangle" class="h-3.5 w-3.5 shrink-0" />
+            {{ t('pipeline.builder.binaryOutputNeedsPick') }}
+          </p>
+
           <p
             v-if="stepsDisallowedByPurpose.length"
             class="mb-2 flex items-center gap-1.5 rounded-md border border-amber-800/50 bg-amber-950/30 px-2 py-1 text-[11px] text-amber-300"
@@ -792,6 +837,15 @@ async function clone(p: Pipeline) {
                 />
               </div>
 
+              <!-- Binary-output picker: a generator kind's step is parametrized by the
+                 foundational STORAGE service its artifacts go through (`stepOptions.binaryOutput`)
+                 plus any services consulted for the generation's scope. Required, not an
+                 override — so it shows in both interface tiers. -->
+              <BinaryOutputStepPicker
+                v-if="showBinaryOutputPicker(unit.kind)"
+                :index="unit.index"
+              />
+
               <!-- This step's own output-token ceiling. An OVERRIDE of the workspace's per-kind
                  setting (itself an override of the deployment routing default), so it is
                  advanced-only until a value is pinned; empty inherits. -->

package/app/components/settings/OpenRouterCatalogPanel.vue

@@ -32,10 +32,13 @@ const back = useIntegrationBack(open)
 const RECOMMENDED_SLUGS = [
   'anthropic/claude-fable-5',
   'anthropic/claude-opus-5',
-  'openai/gpt-5.5',
-  'google/gemini-3-pro',
-  'deepseek/deepseek-chat',
+  'openai/gpt-5.6-sol',
+  'openai/gpt-5.6-terra',
+  'google/gemini-3.1-pro-preview',
+  'google/gemini-3.6-flash',
+  'deepseek/deepseek-v4-flash',
   'moonshotai/kimi-k2.7-code',
+  'z-ai/glm-5.2',
 ]
 
 // Whether the workspace/user has an OpenRouter key connected at any reachable scope.

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

@@ -0,0 +1,103 @@
+import { describe, expect, it } from 'vitest'
+import { buildCatalogueRows, summarizeProgress } from './TutorialCatalogue.logic'
+import type { TutorialCatalogueEntry, TutorialTourState } from '~/utils/tutorial'
+
+const entry = (
+  id: string,
+  availability: TutorialCatalogueEntry['availability'],
+  stepCount = 3,
+): TutorialCatalogueEntry => ({
+  tour: {
+    id,
+    order: 10,
+    titleKey: `tutorial.tours.${id}.title`,
+    descriptionKey: `tutorial.tours.${id}.description`,
+    steps: Array.from({ length: stepCount }, (_, i) => ({
+      id: `s${i}`,
+      titleKey: 't',
+      bodyKey: 'b',
+    })),
+  },
+  availability,
+  unmet:
+    availability === 'blocked'
+      ? [{ id: 'service', labelKey: 'tutorial.requirements.service', met: () => false }]
+      : [],
+})
+
+const states = (map: Record<string, TutorialTourState>) => (id: string) => map[id] ?? 'notStarted'
+
+describe('buildCatalogueRows', () => {
+  it('carries every tour through, ready or not', () => {
+    const rows = buildCatalogueRows(
+      [entry('a', 'ready'), entry('b', 'blocked'), entry('c', 'not-applicable')],
+      states({}),
+    )
+    expect(rows.map((r) => r.tour.id)).toEqual(['a', 'b', 'c'])
+    expect(rows.map((r) => r.startable)).toEqual([true, false, false])
+  })
+
+  it('counts the steps of a runnable tour and withholds a count for the rest', () => {
+    // A blocked tour's resolved script is not what the user gets once they unblock it, and a
+    // number that quietly changes under them is worse than no number.
+    const rows = buildCatalogueRows([entry('a', 'ready', 4), entry('b', 'blocked', 4)], states({}))
+    expect(rows[0]?.stepCount).toBe(4)
+    expect(rows[1]?.stepCount).toBeNull()
+  })
+
+  it('labels each row from the user`s own progress', () => {
+    const rows = buildCatalogueRows(
+      [entry('a', 'ready'), entry('b', 'ready'), entry('c', 'ready')],
+      states({ a: 'completed', b: 'paused', c: 'inProgress' }),
+    )
+    expect(rows.map((r) => r.action)).toEqual(['restart', 'resume', 'continue'])
+  })
+
+  it('keeps a blocked tour`s unmet requirements for the reason list', () => {
+    const [row] = buildCatalogueRows([entry('a', 'blocked')], states({}))
+    expect(row?.unmet.map((r) => r.id)).toEqual(['service'])
+  })
+})
+
+describe('summarizeProgress', () => {
+  /** The launch offer is still unanswered, so only the rows can make anything resettable. */
+  const unanswered = { launchOfferAnswered: false }
+  const rows = (map: Record<string, TutorialTourState>, ids: string[]) =>
+    buildCatalogueRows(
+      ids.map((id) => entry(id, 'ready')),
+      states(map),
+    )
+
+  it('counts completions against the WHOLE catalog, not the runnable part', () => {
+    // Counting only what this board can offer today would move the denominator every time a
+    // repo was linked or a run finished — and "2 of 2" on a board with four walkthroughs
+    // still waiting reads as a finished tutorial, which is what this surface disproves.
+    const all = buildCatalogueRows(
+      [entry('a', 'ready'), entry('b', 'blocked'), entry('c', 'not-applicable')],
+      states({ a: 'completed' }),
+    )
+    expect(summarizeProgress(all, unanswered)).toMatchObject({ completed: 1, total: 3 })
+  })
+
+  it('offers a reset for a paused tour, not only for completed ones', () => {
+    expect(summarizeProgress(rows({}, ['a', 'b']), unanswered).resettable).toBe(false)
+    expect(summarizeProgress(rows({ a: 'paused' }, ['a', 'b']), unanswered).resettable).toBe(true)
+    expect(summarizeProgress(rows({ a: 'completed' }, ['a', 'b']), unanswered).resettable).toBe(
+      true,
+    )
+  })
+
+  it('offers a reset to a user who only ever answered the launch offer', () => {
+    // The case keying Reset off the rows alone got wrong, and the one that matters most: someone
+    // who clicked "No thanks" and took no tour has nothing completed and nothing paused, yet the
+    // saved answer is exactly what stops the prompt returning. Hiding the control left them no
+    // route back to the first-launch experience Reset promises.
+    expect(summarizeProgress(rows({}, ['a', 'b']), { launchOfferAnswered: true }).resettable).toBe(
+      true,
+    )
+  })
+
+  it('offers no reset on a genuinely untouched install', () => {
+    expect(summarizeProgress([], unanswered).resettable).toBe(false)
+  })
+})

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

@@ -0,0 +1,102 @@
+import { launchActionFor } from '~/utils/tutorial'
+import type {
+  TutorialAvailability,
+  TutorialCatalogueEntry,
+  TutorialLaunchAction,
+  TutorialRequirement,
+  TutorialTour,
+  TutorialTourState,
+} from '~/utils/tutorial'
+
+/**
+ * What the catalogue renders per tour, and the progress line above the list.
+ *
+ * Extracted from `TutorialCatalogue.vue` for the same reason the overlay's decisions are
+ * (`TutorialOverlay.logic.ts`): the vitest setup has no SFC transform, so anything that
+ * DECIDES has to live outside the component to be tested. Here that is the whole of what the
+ * surface claims — which tours can be started, which are held back and by what, and how much
+ * of the catalog this user has been through.
+ */
+
+/** One rendered row: an entry, plus everything derived from it and the user's progress. */
+export interface TutorialCatalogueRow {
+  tour: TutorialTour
+  availability: TutorialAvailability
+  /** What is standing in the way, when {@link availability} is `blocked`. */
+  unmet: readonly TutorialRequirement[]
+  state: TutorialTourState
+  action: TutorialLaunchAction
+  /**
+   * How many steps a start would walk this board through — the RESOLVED count, not the
+   * declared one, since branch steps that don't apply here are already gone.
+   *
+   * Null for a tour that cannot run: its resolved script is not what the user would get once
+   * the missing requirement is met, and a number that quietly changes when they unblock it is
+   * worse than no number.
+   */
+  stepCount: number | null
+  /** Whether the row's button does anything (a blocked tour's is inert, not hidden). */
+  startable: boolean
+}
+
+/** The list, in catalog order — the entries arrive sorted by `resolveTourCatalogue`. */
+export function buildCatalogueRows(
+  entries: readonly TutorialCatalogueEntry[],
+  stateOf: (tourId: string) => TutorialTourState,
+): TutorialCatalogueRow[] {
+  return entries.map((entry) => {
+    const ready = entry.availability === 'ready'
+    const state = stateOf(entry.tour.id)
+    return {
+      tour: entry.tour,
+      availability: entry.availability,
+      unmet: entry.unmet,
+      state,
+      action: launchActionFor(state),
+      stepCount: ready ? entry.tour.steps.length : null,
+      startable: ready,
+    }
+  })
+}
+
+/** The headline count. */
+export interface TutorialProgressSummary {
+  completed: number
+  /** Every tour this deployment ships, available or not — the honest denominator. */
+  total: number
+  /**
+   * Whether there is anything for Reset to clear — which is everything `resetProgress` writes,
+   * not only what this list shows. See {@link summarizeProgress}.
+   */
+  resettable: boolean
+}
+
+/**
+ * Progress across the WHOLE catalog, not just the runnable part.
+ *
+ * Counting only what this board can offer today would move the denominator under the user
+ * every time they linked a repo or finished a run — "2 of 2 completed" on a board with four
+ * more walkthroughs waiting behind requirements reads as a finished tutorial, which is the
+ * one thing this surface exists to disprove.
+ *
+ * `launchOfferAnswered` is the store's `decision`, and it is here rather than derived from the
+ * rows because `resetProgress` clears it too — Reset restores the FIRST-LAUNCH experience, and
+ * the saved answer to "would you like a tour?" is most of that. Keying the control on the rows
+ * alone hid it from the one user who most needs it: someone who clicked "No thanks" and took no
+ * tour has nothing completed and nothing paused, so the only route back to the offer was the
+ * control that was not being drawn.
+ */
+export function summarizeProgress(
+  rows: readonly TutorialCatalogueRow[],
+  input: { launchOfferAnswered: boolean },
+): TutorialProgressSummary {
+  const completed = rows.filter((row) => row.state === 'completed').length
+  return {
+    completed,
+    total: rows.length,
+    // A paused tour is progress too: clearing it is exactly what someone handing this to a
+    // colleague wants, and offering Reset only for completions would leave it behind.
+    resettable:
+      completed > 0 || rows.some((row) => row.state === 'paused') || input.launchOfferAnswered,
+  }
+}

package/app/components/tutorial/TutorialCatalogue.vue

@@ -0,0 +1,150 @@
+<script setup lang="ts">
+// The tutorial catalogue: every guided walkthrough this deployment ships, startable (or
+// re-startable) at any time from the sidebar's Help section and the command palette.
+//
+// It is deliberately NOT the launch prompt with a second entry point. The prompt asks a
+// question once, offers what this board can run, and goes away; this answers "what else is
+// there, and why can't I take that one yet?" — so it lists the tours that are HELD BACK too,
+// each with the requirement still missing. Omitting them (which is all a slot filter could do)
+// makes a deployment shipping six walkthroughs look like one shipping two.
+//
+// Everything that decides lives in `TutorialCatalogue.logic.ts` (rows, progress) and
+// `utils/tutorial.ts` (availability, state, action), so the SFC only renders.
+import { buildCatalogueRows, summarizeProgress } from './TutorialCatalogue.logic'
+import type { TutorialCatalogueRow } from './TutorialCatalogue.logic'
+import { TUTORIAL_ACTION_KEYS, TUTORIAL_STATUS_KEYS } from '~/utils/tutorial'
+
+const { t } = useI18n()
+const tutorial = useTutorialStore()
+const { catalogue } = useTutorialTours()
+const { stateOf, launch } = useTutorialLaunch()
+
+const open = computed({
+  get: () => tutorial.catalogueOpen,
+  set: (v: boolean) => (v ? tutorial.openCatalogue() : tutorial.closeCatalogue()),
+})
+
+const rows = computed(() => buildCatalogueRows(catalogue.value, stateOf))
+const progress = computed(() =>
+  summarizeProgress(rows.value, { launchOfferAnswered: tutorial.decision !== null }),
+)
+
+/** A badge only where there is something to say: "not started" is the unremarkable default. */
+const showsStatus = (row: TutorialCatalogueRow) => row.state !== 'notStarted'
+
+const statusColor = (row: TutorialCatalogueRow) =>
+  row.state === 'completed' ? 'success' : row.state === 'inProgress' ? 'primary' : 'neutral'
+</script>
+
+<template>
+  <UModal
+    v-model:open="open"
+    :title="t('tutorial.catalogue.title')"
+    :description="t('tutorial.catalogue.intro')"
+    :ui="{ content: 'max-w-2xl' }"
+  >
+    <template #body>
+      <div class="space-y-4" data-testid="tutorial-catalogue">
+        <p v-if="rows.length > 0" class="text-xs text-slate-400" data-testid="tutorial-progress">
+          {{
+            t('tutorial.catalogue.progress', {
+              completed: progress.completed,
+              total: progress.total,
+            })
+          }}
+        </p>
+        <ul class="space-y-2">
+          <li
+            v-for="row in rows"
+            :key="row.tour.id"
+            class="flex items-start gap-3 rounded-lg border border-slate-800 bg-slate-900/60 p-3"
+            :class="row.startable ? '' : 'opacity-75'"
+            :data-testid="`tutorial-catalogue-entry-${row.tour.id}`"
+          >
+            <UIcon
+              :name="row.tour.icon ?? 'i-lucide-compass'"
+              class="mt-0.5 h-5 w-5 shrink-0 text-primary-400"
+            />
+            <div class="min-w-0 flex-1 space-y-1">
+              <div class="flex flex-wrap items-center gap-2">
+                <span class="text-sm font-medium text-slate-100">{{ t(row.tour.titleKey) }}</span>
+                <UBadge
+                  v-if="showsStatus(row)"
+                  :color="statusColor(row)"
+                  variant="subtle"
+                  size="sm"
+                  :data-testid="`tutorial-catalogue-status-${row.tour.id}`"
+                >
+                  {{ t(TUTORIAL_STATUS_KEYS[row.state]) }}
+                </UBadge>
+              </div>
+              <p class="text-xs text-slate-400">{{ t(row.tour.descriptionKey) }}</p>
+              <p v-if="row.stepCount !== null" class="text-xs text-slate-500">
+                {{ t('tutorial.catalogue.steps', { count: row.stepCount }, row.stepCount) }}
+              </p>
+              <!-- A held-back tour says what would unlock it, rather than vanishing from the
+                   list: these are things the reader can go and do. -->
+              <div
+                v-else-if="row.availability === 'blocked'"
+                class="text-xs text-slate-500"
+                :data-testid="`tutorial-catalogue-requirements-${row.tour.id}`"
+              >
+                <span>{{ t('tutorial.catalogue.blocked') }}</span>
+                <ul class="mt-1 space-y-0.5">
+                  <li v-for="req in row.unmet" :key="req.id" class="flex items-center gap-1.5">
+                    <UIcon name="i-lucide-lock" class="h-3 w-3 shrink-0" />
+                    <span>{{ t(req.labelKey) }}</span>
+                  </li>
+                </ul>
+              </div>
+              <!-- Requirements met, but every step is about a branch this board isn't on:
+                   nothing to go and fix, so it must not read like the case above. -->
+              <p v-else class="text-xs text-slate-500">
+                {{ t('tutorial.catalogue.notApplicable') }}
+              </p>
+            </div>
+            <UButton
+              size="sm"
+              color="primary"
+              :variant="row.state === 'completed' ? 'soft' : 'solid'"
+              :disabled="!row.startable"
+              :data-testid="`tutorial-catalogue-start-${row.tour.id}`"
+              @click="launch(row.tour.id)"
+            >
+              {{ t(TUTORIAL_ACTION_KEYS[row.action]) }}
+            </UButton>
+          </li>
+        </ul>
+        <!-- No tours at all is a real state (a deployment may register none of its own and
+             strip the built-ins), and it is not the same as one whose tours are all blocked. -->
+        <p v-if="rows.length === 0" class="text-sm text-slate-400">
+          {{ t('tutorial.catalogue.empty') }}
+        </p>
+      </div>
+    </template>
+    <template #footer>
+      <div class="flex w-full items-center justify-between gap-2">
+        <UButton
+          v-if="progress.resettable"
+          color="neutral"
+          variant="ghost"
+          icon="i-lucide-rotate-ccw"
+          :title="t('tutorial.catalogue.resetHint')"
+          data-testid="tutorial-catalogue-reset"
+          @click="tutorial.resetProgress()"
+        >
+          {{ t('tutorial.catalogue.reset') }}
+        </UButton>
+        <span v-else />
+        <UButton
+          color="neutral"
+          variant="soft"
+          data-testid="tutorial-catalogue-close"
+          @click="tutorial.closeCatalogue()"
+        >
+          {{ t('common.close') }}
+        </UButton>
+      </div>
+    </template>
+  </UModal>
+</template>

package/app/components/tutorial/TutorialOverlay.vue

@@ -428,7 +428,9 @@ onUnmounted(() => {
 
 <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. -->
+       the app's modals (z-50s), since steps legitimately point INTO an open modal — with the
+       one exception of the tutorial's OWN windows (`ownWindowOpen`), which no step points into
+       and over which the same z-index would float a ring and a tooltip the user cannot use. -->
   <Teleport to="body">
     <!-- The step-change announcement. Visually hidden, and outside BOTH the dialog and the
          `v-if` below, so the live region is a stable node whose TEXT changes for the whole
@@ -438,7 +440,12 @@ onUnmounted(() => {
     <div class="sr-only" role="status" aria-live="polite" data-testid="tutorial-announcement">
       {{ announcement }}
     </div>
-    <div v-if="step" data-testid="tutorial-overlay">
+    <!-- SUPPRESSED, not unmounted, while a tutorial-owned window is open: this component holds
+         the running tour's resolved script (see `tour` above), and a remount would re-resolve it
+         against gates that may have flipped since the tour started — which is the very failure
+         that holding it fixed. The cursor, the tracking and the script all survive; only the
+         marks go, and they come back the moment the window closes. -->
+    <div v-if="step && !tutorial.ownWindowOpen" data-testid="tutorial-overlay">
       <!-- `motion-safe:` on the ring's transition: it slides between controls on every step,
            which is exactly the involuntary movement `prefers-reduced-motion` is about. -->
       <div

package/app/components/tutorial/TutorialPrompt.vue

@@ -1,39 +1,33 @@
 <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 tutorial launch prompt: asks once on first launch whether the user wants a guided tour,
+// listing the tours this board can actually run right now (first-party + consumer, resolved
+// against the same gates the nav uses), so it grows with the catalog rather than hard-coding
+// tours.
+//
+// It is the OFFER, not the library: the full list — including the walkthroughs this board
+// can't run yet and what would unlock them — is `TutorialCatalogue.vue`, one button away in
+// the footer and permanently reachable from the sidebar's Help section. That split is why
+// this stays a short, answerable question instead of growing into a browsing surface.
 //
 // 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.
+import { TUTORIAL_ACTION_KEYS } from '~/utils/tutorial'
+
 const { t } = useI18n()
 const tutorial = useTutorialStore()
 const { tours } = useTutorialTours()
+// Start / Resume / Repeat is decided in one place for both surfaces — see `useTutorialLaunch`.
+const { actionFor, launch } = useTutorialLaunch()
 
 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.
+// Only an unanswered prompt offers the persistent "No thanks": there is a decision to save.
+// Once one exists — this window can still be opened by the store — the only dismissal left is
+// a plain close, since declining something already answered would write nothing new.
 const undecided = computed(() => tutorial.decision === null)
-
-// A tour broken off mid-way (Esc, or Skip to get the overlay out of the way) offers to RESUME
-// where it stopped rather than only to start over. Session-scoped, so this is only ever offered
-// while the board is still in the state the tour left it in — see the store.
-const isResumable = (tourId: string) => tutorial.interruptedAt(tourId) !== null
-
-function launch(tourId: string) {
-  if (isResumable(tourId)) tutorial.resumeTour(tourId)
-  else tutorial.startTour(tourId)
-}
-
-/** Resume beats Completed: a tour taken again and broken off is offered where it stopped. */
-function launchLabel(tourId: string): string {
-  if (isResumable(tourId)) return t('tutorial.prompt.resume')
-  return tutorial.isCompleted(tourId) ? t('tutorial.prompt.restart') : t('tutorial.prompt.start')
-}
 </script>
 
 <template>
@@ -65,7 +59,7 @@ function launchLabel(tourId: string): string {
                   size="sm"
                   data-testid="tutorial-tour-completed"
                 >
-                  {{ t('tutorial.prompt.completed') }}
+                  {{ t('tutorial.status.completed') }}
                 </UBadge>
               </div>
               <p class="text-xs text-slate-400">{{ t(tour.descriptionKey) }}</p>
@@ -73,11 +67,11 @@ function launchLabel(tourId: string): string {
             <UButton
               size="sm"
               color="primary"
-              :variant="tutorial.isCompleted(tour.id) && !isResumable(tour.id) ? 'soft' : 'solid'"
+              :variant="actionFor(tour.id) === 'restart' ? 'soft' : 'solid'"
               :data-testid="`tutorial-start-${tour.id}`"
               @click="launch(tour.id)"
             >
-              {{ launchLabel(tour.id) }}
+              {{ t(TUTORIAL_ACTION_KEYS[actionFor(tour.id)]) }}
             </UButton>
           </li>
         </ul>
@@ -100,14 +94,27 @@ function launchLabel(tourId: string): string {
           {{ 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 class="flex items-center gap-2">
+          <!-- The way to the tours this board can't run yet, and to the ones already taken.
+               Browsing answers nothing, so it neither declines the offer nor accepts it. -->
+          <UButton
+            color="neutral"
+            variant="ghost"
+            icon="i-lucide-graduation-cap"
+            data-testid="tutorial-browse"
+            @click="tutorial.openCatalogue()"
+          >
+            {{ t('tutorial.prompt.browse') }}
+          </UButton>
+          <UButton
+            color="neutral"
+            variant="soft"
+            data-testid="tutorial-close"
+            @click="tutorial.closePrompt()"
+          >
+            {{ undecided ? t('tutorial.prompt.later') : t('common.close') }}
+          </UButton>
+        </div>
       </div>
     </template>
   </UModal>

package/app/composables/useNavContributions.ts

@@ -59,7 +59,10 @@ export function useNavContributions() {
     operatorDashboard: () => ui.openOperatorDashboard(),
     reports: () => ui.openReports(),
     shortcuts: () => ui.openShortcutsHelp(),
-    tutorial: () => useTutorialStore().openPrompt(),
+    // The CATALOGUE, not the launch prompt: reaching this from the sidebar or the palette is
+    // "show me the walkthroughs", and the prompt answers a narrower question (would you like
+    // one now?) that a returning user has already answered once.
+    tutorial: () => useTutorialStore().openCatalogue(),
     // 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/useTutorialLaunch.ts

@@ -0,0 +1,50 @@
+import { launchActionFor, tourState } from '~/utils/tutorial'
+import type { TutorialLaunchAction, TutorialTourState } from '~/utils/tutorial'
+
+/**
+ * Starting a tour, from whichever surface offers it.
+ *
+ * Both the launch prompt and the catalogue answer the same question per tour — start it,
+ * resume where it was broken off, take it again, or step back into the one already running —
+ * and getting that precedence subtly different between the two surfaces would show up as the
+ * same button doing different things on two screens. So the decision is made once here, over
+ * the pure {@link tourState} / {@link launchActionFor} pair, and each surface renders it.
+ */
+export function useTutorialLaunch() {
+  const tutorial = useTutorialStore()
+
+  /** Where this tour stands for this user right now. */
+  function stateOf(tourId: string): TutorialTourState {
+    return tourState({
+      active: tutorial.activeTourId === tourId,
+      resumable: tutorial.interruptedAt(tourId) !== null,
+      completed: tutorial.isCompleted(tourId),
+    })
+  }
+
+  /** What this tour's button will do — also what labels it. */
+  function actionFor(tourId: string): TutorialLaunchAction {
+    return launchActionFor(stateOf(tourId))
+  }
+
+  /**
+   * Act on that. `continue` only steps out of the way: the overlay for that tour is already
+   * on screen, so restarting it from step one — which is what a plain `startTour` would do —
+   * would throw away the position of the walkthrough the user was pointing at.
+   */
+  function launch(tourId: string): void {
+    switch (actionFor(tourId)) {
+      case 'continue':
+        tutorial.closeCatalogue()
+        tutorial.closePrompt()
+        return
+      case 'resume':
+        tutorial.resumeTour(tourId)
+        return
+      default:
+        tutorial.startTour(tourId)
+    }
+  }
+
+  return { stateOf, actionFor, launch }
+}