@cat-factory/app 0.213.1 → 0.214.0

package/app/components/tutorial/TutorialCatalogue.vue

@@ -18,6 +18,19 @@ const { t } = useI18n()
 const tutorial = useTutorialStore()
 const { catalogue } = useTutorialTours()
 const { stateOf, launch } = useTutorialLaunch()
+const { resetServerProgress } = useTutorialServer()
+
+/**
+ * Forget everything, on BOTH sides. The local clear alone would be undone by the next board load:
+ * the snapshot brings the server row back and the store MERGES it, which is exactly right for every
+ * other reconciliation and exactly wrong for the one action whose whole point is to erase the
+ * record. `useTutorialServer` rather than `useTutorialSync` because this must not install a second
+ * set of mirror watchers each time the catalogue mounts.
+ */
+function reset() {
+  tutorial.resetProgress()
+  resetServerProgress()
+}
 
 const open = computed({
   get: () => tutorial.catalogueOpen,
@@ -131,7 +144,7 @@ const statusColor = (row: TutorialCatalogueRow) =>
           icon="i-lucide-rotate-ccw"
           :title="t('tutorial.catalogue.resetHint')"
           data-testid="tutorial-catalogue-reset"
-          @click="tutorial.resetProgress()"
+          @click="reset()"
         >
           {{ t('tutorial.catalogue.reset') }}
         </UButton>

package/app/components/tutorial/TutorialNudge.vue

@@ -0,0 +1,107 @@
+<script setup lang="ts">
+import { computed } from 'vue'
+
+// The contextual offer's surface: one walkthrough, offered beside the work that just made it
+// relevant. Deliberately NOT a modal — the whole point is the moment, and a modal would
+// interrupt whatever the user was doing to reach it (answering a parked run, reading a failure).
+// A corner card they can ignore is the strongest thing that is still honest about being an aside.
+//
+// Which tour, and whether one is on offer at all, is decided upstream (`useTutorialNudge` over
+// the pure `newlyAvailableTour`). This component owns only whether now is a moment it may be on
+// screen, and that is the reason the offer is HELD rather than dropped: the gates that raise it
+// are live run state, so it routinely arrives while a tour or a tutorial window is already up.
+const { t } = useI18n()
+const tutorial = useTutorialStore()
+const { catalogue } = useTutorialTours()
+const { launch } = useTutorialLaunch()
+
+/**
+ * The offered tour, resolved from the catalogue rather than held as an object.
+ *
+ * Resolving by id means a tour whose availability has since changed cannot be offered from a
+ * stale copy: if the gates dropped it while the offer sat suppressed (a run un-parked itself),
+ * the entry is no longer `ready` and the card goes away rather than starting a walkthrough whose
+ * every step would now anchor-skip.
+ */
+const offered = computed(() => {
+  const id = tutorial.pendingNudgeId
+  if (id === null) return null
+  const entry = catalogue.value.find((e) => e.tour.id === id)
+  return entry?.availability === 'ready' ? entry.tour : null
+})
+
+/**
+ * A tour in progress or a tutorial window on screen suppresses the card.
+ *
+ * `ownWindowOpen` covers the prompt and the catalogue for the same reason the coach marks stand
+ * down for them: those are windows the user is answering, and an offer floating over the library
+ * they opened to browse offers is noise. A running tour suppresses it because the card would
+ * compete with the coach mark for the same attention, and because taking the offer mid-tour
+ * would end the walkthrough the user is in the middle of.
+ */
+const suppressed = computed(() => tutorial.touring || tutorial.ownWindowOpen)
+
+function take(tourId: string) {
+  tutorial.dismissNudge()
+  launch(tourId)
+}
+</script>
+
+<template>
+  <!-- `aria-live="polite"`: this appears without the user asking, so a screen-reader user is told
+       about it when they are between things rather than mid-sentence. The card is not a dialog —
+       nothing is trapped and nothing must be answered — so it takes no focus. -->
+  <Transition
+    enter-active-class="motion-safe:transition motion-safe:duration-200"
+    enter-from-class="opacity-0 translate-y-2"
+    leave-active-class="motion-safe:transition motion-safe:duration-150"
+    leave-to-class="opacity-0 translate-y-2"
+  >
+    <!-- `end-4`, not `right-4`: the layer ships a RTL locale, so a physical side would pin this to
+         the wrong corner in Hebrew. `bottom-20` rather than `bottom-4` because `UApp`'s toaster
+         defaults to `bottom-right` and this card is PERSISTENT where a toast is transient, so the
+         card yields the lane rather than sitting under it. A tall toast stack can still reach up
+         this far, which is acceptable in a way the standing overlap was not: it clears itself. -->
+    <div
+      v-if="offered && !suppressed"
+      class="fixed end-4 bottom-20 z-50 w-80 max-w-[calc(100vw-32px)] rounded-xl border border-slate-700 bg-slate-900/95 p-3 shadow-2xl backdrop-blur"
+      role="status"
+      aria-live="polite"
+      data-testid="tutorial-nudge"
+    >
+      <div class="flex items-start gap-2">
+        <UIcon
+          :name="offered.icon ?? 'i-lucide-graduation-cap'"
+          class="text-primary-300 mt-0.5 h-4 w-4 shrink-0"
+        />
+        <div class="min-w-0 flex-1">
+          <p class="text-[11px] tracking-wide text-slate-400 uppercase">
+            {{ t('tutorial.nudge.label') }}
+          </p>
+          <p class="mt-0.5 text-sm font-medium text-slate-100">{{ t(offered.titleKey) }}</p>
+          <p class="mt-0.5 text-xs text-slate-400">{{ t(offered.descriptionKey) }}</p>
+        </div>
+        <UButton
+          size="xs"
+          variant="ghost"
+          color="neutral"
+          icon="i-lucide-x"
+          :aria-label="t('tutorial.nudge.dismiss')"
+          data-testid="tutorial-nudge-dismiss"
+          @click="tutorial.dismissNudge()"
+        />
+      </div>
+      <div class="mt-2 flex justify-end">
+        <UButton
+          size="xs"
+          color="primary"
+          variant="soft"
+          data-testid="tutorial-nudge-start"
+          @click="take(offered.id)"
+        >
+          {{ t('tutorial.nudge.start') }}
+        </UButton>
+      </div>
+    </div>
+  </Transition>
+</template>

package/app/components/tutorial/TutorialOverlay.vue

@@ -4,6 +4,7 @@ import {
   computeCoachMarkLayout,
   DEFAULT_TARGET_WAIT_MS,
   needsReveal,
+  nextTourAfter,
   TARGET_IDLE_INTERVAL_MS,
   TARGET_TRACK_INTERVAL_MS,
 } from '~/utils/tutorial'
@@ -41,6 +42,7 @@ import type { TutorialAdvanceCause, TutorialDirection } from './TutorialOverlay.
 const { t } = useI18n()
 const tutorial = useTutorialStore()
 const { tours } = useTutorialTours()
+const { launch } = useTutorialLaunch()
 const { fitView, viewport } = useBoardFlow()
 // Reduced motion is honoured in BOTH directions here: the CSS below drops the ring's transition
 // and the searching spinner behind `motion-safe:`, and this drives the JS half — an instant
@@ -49,6 +51,25 @@ const { fitView, viewport } = useBoardFlow()
 const reducedMotion = usePreferredReducedMotion()
 const motionMs = computed(() => (reducedMotion.value === 'reduce' ? 0 : 250))
 
+// ---------------------------------------------------------------------------------------
+// PER-RUN state: everything below belongs to ONE pass through ONE script, so it is declared
+// here, ahead of the script itself, and reset by the same watcher that re-resolves it. It
+// used to be declared further down and rebuilt by the component UNMOUNTING between tours,
+// which the finish card's handoff broke: that completes one tour and starts the next within a
+// single tick, so `touring` never goes false for a render and nothing unmounts.
+// ---------------------------------------------------------------------------------------
+/** 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())
+/**
+ * The step index whose anchor has already been brought into view. A reveal is attempted at
+ * most ONCE per step: `fitView` and `scrollIntoView` are animations that take longer than a
+ * tracking tick, so re-deciding each tick would re-issue the move against a viewport still
+ * mid-flight and fight the user the moment they panned away deliberately.
+ */
+const revealedForStep = ref<number | null>(null)
+
 /**
  * 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
@@ -70,6 +91,15 @@ watch(
     // 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
+    // Per-RUN state belongs to the script, so it resets with it. This used to be safe by
+    // accident: the overlay is mounted only while `tutorial.touring`, so it unmounted between
+    // tours and every ref below was rebuilt. The finish card's handoff completes one tour and
+    // starts the next in ONE tick, so `touring` never goes false for a render and nothing
+    // unmounts — leaving the finished tour's skips to be counted against the new one, which
+    // would open a fresh walkthrough already claiming the user had missed part of it.
+    skippedStepIds.value = new Set()
+    revealedForStep.value = null
+    direction.value = 'forward'
   },
   { immediate: true },
 )
@@ -105,13 +135,6 @@ const targetRect = ref<TutorialRect | null>(null)
  * document query several times a second for the whole length of the tour.
  */
 const anchorEl = ref<HTMLElement | null>(null)
-/**
- * The step index whose anchor has already been brought into view. A reveal is attempted at
- * most ONCE per step: `fitView` and `scrollIntoView` are animations that take longer than a
- * tracking tick, so re-deciding each tick would re-issue the move against a viewport still
- * mid-flight and fight the user the moment they panned away deliberately.
- */
-const revealedForStep = ref<number | null>(null)
 const cardEl = ref<HTMLElement | null>(null)
 const layout = ref<CoachMarkLayout>({ top: -9999, left: -9999, placement: 'center' })
 
@@ -121,10 +144,6 @@ const layout = ref<CoachMarkLayout>({ top: -9999, left: -9999, placement: 'cente
  * 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)
@@ -134,6 +153,41 @@ const unexpectedSkips = computed(() =>
 )
 const abridged = computed(() => unexpectedSkips.value.length > 0)
 
+/**
+ * The walkthrough to hand off to on the finish card, or null when there is nothing left.
+ *
+ * Read LIVE from the gated slot, which is the deliberate exception to the held-script rule
+ * above: the delivery loop is a chain in which each tour produces the state the next one
+ * requires, so the completion the user is about to record is itself what makes the next tour
+ * takeable. A candidate resolved when the tour STARTED would be empty exactly when this
+ * matters. Nothing about the running script is read from it, so the hazard the hold exists to
+ * prevent (a step swapped underneath a stationary cursor) cannot arise here.
+ *
+ * `justFinishedId` is the tour's OWN id rather than `tutorial.activeTourId`, so that the
+ * suggestion is stable across the completion that clears the cursor.
+ */
+const nextTour = computed<TutorialTour | null>(() =>
+  tour.value
+    ? nextTourAfter(tours.value, {
+        justFinishedId: tour.value.id,
+        isCompleted: (id) => tutorial.isCompleted(id),
+      })
+    : null,
+)
+
+/**
+ * Finish this tour and go straight into the one offered beside Done.
+ *
+ * Two calls rather than `launch()` alone: the completion has to be recorded first, or the tour
+ * the user just finished keeps its "not started" badge in the catalogue. `launch` (not
+ * `startTour`) so a suggested tour the user had broken off earlier RESUMES, exactly as it would
+ * from the catalogue — the precedence lives in one place for every surface that offers a tour.
+ */
+function takeNextTour(tourId: string) {
+  tutorial.completeTour()
+  launch(tourId)
+}
+
 /**
  * The browser viewport. Named apart from Vue Flow's `viewport` (the board CAMERA) above —
  * and not `screen`, which would shadow the DOM global of that name for the whole component.
@@ -523,6 +577,33 @@ onUnmounted(() => {
             )
           }}
         </p>
+        <!-- The handoff. The catalog is a chain — each delivery-loop tour produces the state
+             the next one needs — and this is the last moment the product can say so: starting
+             any tour saves `decision: 'accepted'`, which stops the launch prompt returning, so
+             without this the walkthrough the user's own last action just unlocked is reachable
+             only by going and finding the catalogue. One tour, not a list; absent when there is
+             nothing ready, where the plain Done below is the honest ending. -->
+        <div
+          v-if="isLast && nextTour"
+          class="mt-3 rounded-lg border border-slate-700/70 bg-slate-800/40 p-2.5"
+          data-testid="tutorial-next-tour"
+        >
+          <p class="text-[11px] tracking-wide text-slate-400 uppercase">
+            {{ t('tutorial.overlay.nextUp') }}
+          </p>
+          <p class="mt-0.5 text-sm font-medium text-slate-100">{{ t(nextTour.titleKey) }}</p>
+          <p class="mt-0.5 text-xs text-slate-400">{{ t(nextTour.descriptionKey) }}</p>
+          <UButton
+            size="xs"
+            color="primary"
+            variant="soft"
+            class="mt-2"
+            data-testid="tutorial-next-tour-start"
+            @click="takeNextTour(nextTour.id)"
+          >
+            {{ t('tutorial.overlay.takeNext') }}
+          </UButton>
+        </div>
         <div class="mt-3 flex items-center justify-between gap-2">
           <UButton
             size="xs"

package/app/composables/api/execution.ts

@@ -15,7 +15,7 @@ import {
   resumeSpendContract,
   startExecutionContract,
 } from '@cat-factory/contracts'
-import type { RequestStepChangesInput } from '@cat-factory/contracts'
+import type { RequestStepChangesInput, RunMode } from '@cat-factory/contracts'
 import type { IterationCapChoice } from '~/types/execution'
 import type { ReviewEffort } from '~/types/merge'
 import type { ApiContext } from './context'
@@ -27,7 +27,10 @@ export function executionApi({ send, sendWith, ws, pwHeaders }: ApiContext) {
     startExecution: (
       workspaceId: string,
       blockId: string,
-      body: { pipelineId: string },
+      // `mode: 'dry_run'` REQUESTS a sandboxed run (the pipeline runs and opens its PR, but
+      // nothing merges). Omitted ⇒ live. The task's merge preset can force a sandbox regardless
+      // of what is asked here, so the response's `mode` is what the run actually got.
+      body: { pipelineId: string; mode?: RunMode },
       password?: string,
     ) =>
       sendWith(pwHeaders(password), startExecutionContract, {

package/app/composables/api/tutorial.ts

@@ -0,0 +1,25 @@
+import {
+  getTutorialProgressContract,
+  recordTutorialEventContract,
+  resetTutorialProgressContract,
+  updateTutorialProgressContract,
+} from '@cat-factory/contracts'
+import type { RecordTutorialEventInput, UpdateTutorialProgressInput } from '~/types/domain'
+import type { ApiContext } from './context'
+
+/**
+ * The in-app tutorial's server surface, scoped to the signed-in user: progress that follows the
+ * PERSON across browsers, plus the funnel events (which store nothing and answer only whether the
+ * tutorial is being found and finished).
+ */
+export function tutorialApi({ send }: ApiContext) {
+  return {
+    getTutorialProgress: () => send(getTutorialProgressContract, {}),
+    /** MERGES: the two id sets are grow-only, so this never removes what another device recorded. */
+    updateTutorialProgress: (body: UpdateTutorialProgressInput) =>
+      send(updateTutorialProgressContract, { body }),
+    resetTutorialProgress: () => send(resetTutorialProgressContract, {}),
+    recordTutorialEvent: (body: RecordTutorialEventInput) =>
+      send(recordTutorialEventContract, { body }),
+  }
+}

package/app/composables/useApi.ts

@@ -51,6 +51,7 @@ import { tasksApi } from './api/tasks'
 import { bugHuntApi } from './api/bugHunt'
 import { testSecretsApi } from './api/testSecrets'
 import { userSecretsApi } from './api/userSecrets'
+import { tutorialApi } from './api/tutorial'
 import { userSettingsApi } from './api/userSettings'
 import { workspacesApi } from './api/workspaces'
 
@@ -163,6 +164,7 @@ export function useApi() {
     ...slackApi(ctx),
     ...bootstrapApi(ctx),
     ...userSecretsApi(ctx),
+    ...tutorialApi(ctx),
     ...userSettingsApi(ctx),
   }
 }

package/app/composables/usePipelineErrorToast.ts

@@ -105,6 +105,10 @@ const CONFLICT_INFO: Record<Exclude<ConflictReason, BespokeConflictReason>, Conf
     titleKey: 'errors.conflict.title.no_pr_to_merge',
     descriptionKey: 'errors.conflict.description.no_pr_to_merge',
   },
+  dry_run_not_mergeable: {
+    titleKey: 'errors.conflict.title.dry_run_not_mergeable',
+    descriptionKey: 'errors.conflict.description.dry_run_not_mergeable',
+  },
   github_not_connected: {
     titleKey: 'errors.conflict.title.github_not_connected',
     descriptionKey: 'errors.conflict.description.github_not_connected',

package/app/composables/useTutorialNudge.ts

@@ -0,0 +1,77 @@
+import { ref, watch } from 'vue'
+import { boardStateFingerprint, resolveNudge } from '~/utils/tutorial'
+import { createSharedComposables } from '@modular-vue/vue'
+import type { AppDeps } from '~/modular/registry'
+
+const { useOptional } = createSharedComposables<AppDeps>()
+
+/**
+ * The contextual offer: watch the resolved tour catalogue and hold out the ONE walkthrough that
+ * just became takeable.
+ *
+ * This is the half of the tutorial the catalogue could not fix. The catalogue made every tour
+ * reachable, but nothing brings one UP: starting any tour saves `decision: 'accepted'`, which is
+ * what stops the launch prompt auto-opening again, so after a user's first tour the product never
+ * mentions the tutorial unless they go looking. The two walkthroughs that matter most are also
+ * the two that are only available inside a transient window — `answer-park` while something is
+ * actually waiting for a human, `review-merge` once a run has produced something to merge — so
+ * "go and look" and "be available" rarely coincide.
+ *
+ * The rule itself is pure and lives in `resolveNudge` (over `newlyAvailableTour`); this is the
+ * reactive half and nothing more. That split is deliberate: the one piece of state here that
+ * cannot be pure is the BASELINE, and a wrong baseline silently converts a moment-triggered offer
+ * into an every-board-load greeting, which is the failure this mechanism is supposed to be the
+ * cure for.
+ *
+ * Called once from `pages/index.vue`. Never suppresses anything itself — whether the offer may be
+ * on screen right now is the component's business (`TutorialNudge.vue`), because the offer is
+ * held rather than dropped while a tutorial window or a tour is up.
+ */
+export function useTutorialNudge() {
+  const tutorial = useTutorialStore()
+  const workspace = useWorkspaceStore()
+  const { catalogue } = useTutorialTours()
+  // The same registered `gates` service the catalogue resolves against, so the fingerprint below
+  // can never describe a different board than the availability it is paired with. `useOptional`
+  // for the bare-install case the nav filter also allows: no gates means no board state to move,
+  // so the offer simply never fires.
+  const gates = useOptional('gates')
+
+  /**
+   * What the last look saw: which tours were takeable, and the board-state stamp they went with.
+   * `null` = no baseline yet (never seeded, or the board went away and the next one must seed its
+   * own).
+   *
+   * `resolveNudge` decides when this is seeded, advanced and discarded; the only reason it lives
+   * out here is that a pure function cannot hold it.
+   */
+  const previous = ref<{ ready: ReadonlySet<string>; boardState: string } | null>(null)
+
+  watch(
+    // Two inputs beyond the catalogue, and each closes a different half of the "the app starting up
+    // is not a moment" problem. `workspace.ready` gates taking a baseline at all on the snapshot
+    // having landed, and is re-set per board so a SWITCH re-seeds. The board-state fingerprint is
+    // what an offer requires to have moved, so the permissions and capability probes that resolve
+    // after `ready` widen availability without being mistaken for something the user did.
+    () =>
+      [catalogue.value, workspace.ready, gates.value ? boardStateFingerprint(gates.value) : ''] as [
+        typeof catalogue.value,
+        boolean,
+        string,
+      ],
+    ([entries, boardReady, boardState]) => {
+      const { baseline, offer } = resolveNudge({
+        boardReady,
+        catalogue: entries,
+        boardState,
+        previous: previous.value,
+        declined: tutorial.decision === 'declined',
+        isCompleted: (id) => tutorial.isCompleted(id),
+        wasNudged: (id) => tutorial.wasNudged(id),
+      })
+      previous.value = baseline
+      if (offer) tutorial.offerNudge(offer.id)
+    },
+    { immediate: true },
+  )
+}

package/app/composables/useTutorialSync.ts

@@ -0,0 +1,141 @@
+import { watch } from 'vue'
+
+/**
+ * The tutorial's server calls, with no watchers attached — safe to call from anywhere, as many
+ * times as you like.
+ *
+ * Split from {@link useTutorialSync} for exactly that reason: the catalogue's "Reset progress"
+ * button needs the DELETE, and reaching it through the composable that installs the mirror watchers
+ * would install a second set of them every time the catalogue mounted.
+ *
+ * Everything here is BEST-EFFORT and nothing throws into a caller. That is the design rather than a
+ * shortcut: the browser-persisted store stays the source the SPA reads and stays fully functional on
+ * a deployment with no accounts, with no progress store wired, or offline. A failed mirror costs a
+ * re-offer on another machine; it must never cost the walkthrough the user is taking.
+ */
+export function useTutorialServer() {
+  const tutorial = useTutorialStore()
+  const api = useApi()
+
+  /**
+   * Push the WHOLE local state to the server, and reconcile against what comes back.
+   *
+   * Whole state, never a delta, which is what makes fire-and-forget correct here rather than merely
+   * convenient: a retry, a racing tab and a stale copy are all the same well-formed write.
+   *
+   * The response is the merged row, and feeding it back through the store is what closes the one
+   * hole a merge with no revision guard leaves: two concurrent merges CAN lose a writer's ids (a
+   * union is idempotent under retry, not commutative under concurrency), and the answer then comes
+   * back missing something local, which flips `serverPushNeeded` on again and re-pushes. So the
+   * repair is automatic and bounded to one extra round, rather than waiting on a local change that
+   * may never come. `markServerPushed` runs FIRST for that reason: it has to be able to go back on.
+   */
+  function push() {
+    void api
+      .updateTutorialProgress({
+        decision: tutorial.decision,
+        completedTourIds: [...tutorial.completedTourIds],
+        nudgedTourIds: [...tutorial.nudgedTourIds],
+      })
+      .then((merged) => {
+        tutorial.markServerPushed()
+        tutorial.mergeServerProgress(merged)
+      })
+      .catch(() => {
+        // silent-catch-ok: the local store is authoritative for this session and the next board
+        // load re-runs the whole reconciliation, so there is nothing to report and nothing a user
+        // could act on. Deliberately NOT re-armed here either: a refusal (the merged row would
+        // exceed its cap) would otherwise retry forever. (The SPA has no logger seam — see
+        // CLAUDE.md's silent-catch scope.)
+      })
+  }
+
+  /** Count one funnel event. */
+  function recordEvent(event: 'started' | 'completed' | 'abandoned', tourId: string) {
+    void api.recordTutorialEvent({ event, tourId }).catch(() => {
+      // silent-catch-ok: a dropped metric is a dropped metric. Failing a walkthrough over one, or
+      // retrying it, would both be worse than the missing data point.
+    })
+  }
+
+  /** Clear the server row too, so "Reset progress" is not undone by the next snapshot. */
+  function resetServerProgress() {
+    void api.resetTutorialProgress().catch(() => {
+      // silent-catch-ok: the local reset already happened. The failure mode is that the next
+      // snapshot restores the server copy, which is the state the user just left.
+    })
+  }
+
+  return { push, recordEvent, resetServerProgress }
+}
+
+/**
+ * Mirror the tutorial's persisted state to the signed-in user's server row, and count the funnel.
+ *
+ * Two things a browser-only store could not do, both of which the in-app-tutorial tracker left
+ * open:
+ *
+ *  - progress that follows the PERSON. Client-persisted only, a second machine re-asks the launch
+ *    question and re-makes every contextual offer, because "which walkthroughs have I finished" was
+ *    a fact about a browser profile.
+ *  - MEASUREMENT. Whether the catalogue is found and whether a tour is FINISHED was unmeasured, so
+ *    every further slice of this feature was chosen on a guess.
+ *
+ * Called once, from `pages/index.vue`.
+ */
+export function useTutorialSync() {
+  const tutorial = useTutorialStore()
+  const { push, recordEvent } = useTutorialServer()
+
+  // The adoption half runs in the snapshot fan-out (`stores/workspace/hydrate.ts` →
+  // `mergeServerProgress`), which is where every other per-user slice is hydrated and, crucially,
+  // early enough that the launch prompt decides whether to appear against the merged state rather
+  // than against this browser's copy alone. All that is left here is the write-back it asks for.
+  watch(
+    () => tutorial.serverPushNeeded,
+    (needed) => {
+      if (needed) push()
+    },
+    { immediate: true },
+  )
+
+  // Every later local change is mirrored. Watching the store's LOCAL revision counter rather than
+  // wrapping each action keeps this a single seam as the store grows (a new action that records a
+  // completion is covered by being a local change, where a hand-wired call per action is one more
+  // place to forget) — and rather than watching the STATE, because adopting the server's own ids in
+  // `mergeServerProgress` is a state change too, so that would post the server's row back at it on
+  // every fresh-browser board load. A reset bumps nothing on purpose: its server side is a DELETE.
+  watch(
+    () => tutorial.localRev,
+    () => push(),
+  )
+
+  /**
+   * Derive the funnel events from the cursor rather than emitting them from each action.
+   *
+   * One watcher instead of calls in `startTour` / `resumeTour` / `stopTour` / `completeTour` /
+   * `takeNextTour`, because those are five sites and a sixth is one refactor away — and a missing
+   * `started` does not fail anything, it just quietly biases the number the rest of this feature
+   * will be planned against.
+   *
+   * Vue batches, which is what makes the derivation work across the finish card's handoff: that
+   * completes one tour and starts the next in a single tick, so the cursor goes `A → null → B` and
+   * this sees `A → B` with the completion list one longer. It reports "A completed, B started",
+   * which is what happened. A plain Skip is `A → null` with the list unchanged: abandoned.
+   *
+   * A RESUME counts as a start. That is a deliberate reading, not an oversight: from the funnel's
+   * point of view an attempt is an attempt, and the alternative (silently not counting re-entries)
+   * would make completions exceed starts for anyone who breaks off and comes back.
+   */
+  watch(
+    () => [tutorial.activeTourId, tutorial.completedTourIds.length] as const,
+    ([activeId, completedCount], [previousId, previousCount]) => {
+      if (activeId === previousId) return
+      if (previousId !== null) {
+        const finished = completedCount > previousCount
+        recordEvent(finished ? 'completed' : 'abandoned', previousId)
+      }
+      if (activeId !== null) recordEvent('started', activeId)
+    },
+  )
+}

package/app/modular/external-tools.spec.ts

@@ -43,6 +43,7 @@ const GATES: NavGates = {
   boardHasOpenDecision: true,
   boardHasPendingApproval: true,
   boardHasFinishedRun: true,
+  boardHasFailedRun: true,
 }
 
 describe('resolveExternalToolUrl', () => {

package/app/modular/nav-contributions.spec.ts

@@ -33,6 +33,7 @@ const NO_GATES: NavGates = {
   boardHasOpenDecision: false,
   boardHasPendingApproval: false,
   boardHasFinishedRun: false,
+  boardHasFailedRun: false,
 }
 
 const ALL_GATES: NavGates = {
@@ -51,6 +52,7 @@ const ALL_GATES: NavGates = {
   boardHasOpenDecision: true,
   boardHasPendingApproval: true,
   boardHasFinishedRun: true,
+  boardHasFailedRun: true,
 }
 
 const slots = (): AppSlots => ({

package/app/modular/nav-contributions.ts

@@ -144,6 +144,17 @@ export interface NavGates {
    * failed run never renders.
    */
   boardHasFinishedRun: boolean
+  /**
+   * Some run on a task block has FAILED, so the card is rendering the failure banner.
+   *
+   * The other half of {@link boardHasFinishedRun}, and the reason it is a separate gate rather
+   * than a looser "a run settled": the two states render disjoint surfaces (a result view and
+   * a merge control; a failure banner and a retry), so one tour cannot cover both. It is also
+   * the state a new user is MOST likely to be in and the one the catalog had nothing for: with
+   * only the success gate, a board where every run failed reports the delivery loop as
+   * permanently half-finished and explains none of it.
+   */
+  boardHasFailedRun: boolean
 }
 
 /** Command-palette placement + copy for a contribution that appears in the palette. */

package/app/modular/nav-gates.ts

@@ -49,6 +49,13 @@ export function createNavGates(): NavGates {
   const hasFinishedRun = computed(() =>
     execution.instances.some((e) => e.status === 'done' && isTaskBlock(e.blockId)),
   )
+  // Mirrors what the CARD renders, exactly as the park gates do: `TaskCard` shows the shared
+  // failure banner on `agentRun.status === 'failed'`, which is the anchor the diagnose tour
+  // points at. Kept apart from `hasFinishedRun` because the two states render disjoint
+  // controls — see `NavGates.boardHasFailedRun`.
+  const hasFailedRun = computed(() =>
+    execution.instances.some((e) => e.status === 'failed' && isTaskBlock(e.blockId)),
+  )
   // Not the store's raw pending counts: those answer "is anything parked", while the tour
   // these gate anchors on the card affordance a park RENDERS. See `hasActionablePark`.
   const hasOpenDecision = computed(() =>
@@ -119,5 +126,8 @@ export function createNavGates(): NavGates {
     get boardHasFinishedRun() {
       return hasFinishedRun.value
     },
+    get boardHasFailedRun() {
+      return hasFailedRun.value
+    },
   }
 }

package/app/modular/registry.spec.ts

@@ -19,6 +19,7 @@ const NO_GATES: NavGates = {
   boardHasOpenDecision: false,
   boardHasPendingApproval: false,
   boardHasFinishedRun: false,
+  boardHasFailedRun: false,
 }
 
 describe('app modular registry', () => {