@cat-factory/app 0.213.1 → 0.214.0

package/app/modular/tutorial-tours.spec.ts

@@ -29,6 +29,7 @@ const ALL_GATES: NavGates = {
   boardHasOpenDecision: true,
   boardHasPendingApproval: true,
   boardHasFinishedRun: true,
+  boardHasFailedRun: true,
 }
 
 /**
@@ -44,6 +45,7 @@ const FRESH_BOARD: NavGates = {
   boardHasOpenDecision: false,
   boardHasPendingApproval: false,
   boardHasFinishedRun: false,
+  boardHasFailedRun: false,
 }
 
 /** Resolve a dot-path against the en catalog; undefined when any hop is missing. */
@@ -295,10 +297,10 @@ describe('the built-in tutorial tour catalog', () => {
     // rather than spelled out a second time here.
     const pairs = navAnchoredSteps()
     // Guard the guard, twice over. A pairing that matched nothing would pass vacuously, and
-    // there is one per tour that opens a sidebar surface: `add-service` plus the four platform
-    // tours. And a gate field that is not a boolean would silently never vary across the
+    // there is one per tour that opens a sidebar surface: `add-service` plus every platform
+    // tour. And a gate field that is not a boolean would silently never vary across the
     // matrix, leaving whatever it gates unexercised.
-    expect(pairs.length).toBeGreaterThanOrEqual(5)
+    expect(pairs.length).toBeGreaterThanOrEqual(8)
     expect(Object.values(ALL_GATES).every((value) => typeof value === 'boolean')).toBe(true)
 
     const drifted = pairs.flatMap((pair) => {
@@ -344,6 +346,9 @@ describe('tour availability across the catalog', () => {
       'design-pipeline',
       'agent-standards',
       'connect-systems',
+      'prepare-infrastructure',
+      'panel-reviews',
+      'share-services',
     ])
   })
 
@@ -383,9 +388,20 @@ describe('tour availability across the catalog', () => {
       'first-task',
       'run-task',
       'answer-park',
+      // Work going WRONG is part of the arc, not an appendix to it: a first run fails often, and
+      // this is the tour the contextual offer raises when one does.
+      'diagnose-failure',
       'review-merge',
     ]
-    const CATALOGUE_ONLY = ['wire-models', 'design-pipeline', 'agent-standards', 'connect-systems']
+    const CATALOGUE_ONLY = [
+      'wire-models',
+      'design-pipeline',
+      'agent-standards',
+      'connect-systems',
+      'prepare-infrastructure',
+      'panel-reviews',
+      'share-services',
+    ]
     expect(TUTORIAL_TOURS.filter(isLaunchOffer).map((t) => t.id)).toEqual(LAUNCH_ARC)
     expect(TUTORIAL_TOURS.filter((t) => !isLaunchOffer(t)).map((t) => t.id)).toEqual(CATALOGUE_ONLY)
     // Un-offered is not un-runnable: it thins the offer, never the library.
@@ -435,6 +451,41 @@ describe('tour availability across the catalog', () => {
     expect(ready(finished)).toContain('review-merge')
   })
 
+  it('offers the failure tour on the state the success tour refuses', () => {
+    // The two are disjoint on purpose, and this is the pairing that used to have no second half:
+    // a board whose only run FAILED was offered a walkthrough of reading a successful result
+    // (blocked, so invisible in the prompt) and nothing whatsoever about the banner on screen.
+    const failed: NavGates = { ...FRESH_BOARD, boardHasRun: true, boardHasFailedRun: true }
+    expect(ready(failed)).toContain('diagnose-failure')
+    expect(ready(failed)).not.toContain('review-merge')
+    expect(entry(failed, 'review-merge')?.unmet.map((r) => r.id)).toEqual(['finished-run'])
+
+    const succeeded: NavGates = { ...FRESH_BOARD, boardHasRun: true, boardHasFinishedRun: true }
+    expect(ready(succeeded)).toContain('review-merge')
+    expect(entry(succeeded, 'diagnose-failure')?.unmet.map((r) => r.id)).toEqual(['failed-run'])
+  })
+
+  it('holds the interface tier as a requirement of the tours whose surface hides in basic', () => {
+    // Two different reasons, one requirement. `share-services` clicks a nav entry marked
+    // `advanced: true` (which `navRequirementDrift` also enforces); `panel-reviews` clicks a
+    // BASIC entry whose consensus section renders only in advanced mode or once a group exists,
+    // one level below anything the nav guard can see. Basic is the shipped default, so without
+    // this both would be offered to nearly every user and find nothing.
+    const basic: NavGates = { ...ALL_GATES, advancedMode: false }
+    expect(ready(basic)).not.toContain('share-services')
+    expect(ready(basic)).not.toContain('panel-reviews')
+    expect(entry(basic, 'share-services')?.unmet.map((r) => r.id)).toEqual(['advanced-tier'])
+    expect(entry(basic, 'panel-reviews')?.unmet.map((r) => r.id)).toEqual(['advanced-tier'])
+  })
+
+  it('names the missing execution backend for the infrastructure tour', () => {
+    const noInfra: NavGates = { ...ALL_GATES, infrastructureAvailable: false }
+    expect(ready(noInfra)).not.toContain('prepare-infrastructure')
+    expect(entry(noInfra, 'prepare-infrastructure')?.unmet.map((r) => r.id)).toEqual([
+      'infrastructure',
+    ])
+  })
+
   it('names every unmet requirement, not just the first', () => {
     // The reader has to do all of them; reporting one at a time turns unblocking a tour into
     // a guessing game with a fresh answer after each attempt.

package/app/modular/tutorial-tours.ts

@@ -34,16 +34,26 @@ import type { TutorialRequirement, TutorialTour } from '~/utils/tutorial'
  * The catalog is in two halves, and the split is what keeps the launch prompt answerable:
  *
  *  - The DELIVERY LOOP, end to end — get a repo onto the board, put a task on it, run it, answer
- *    it when it asks, read the result and merge it — each tour requiring the state the previous
- *    one produces, so the prompt only ever offers what this board can actually demonstrate and
- *    the catalogue turns the rest into a to-do list rather than an absence.
+ *    it when it asks, read a failure when it comes, read the result and merge it — each tour
+ *    requiring the state the previous one produces, so the prompt only ever offers what this
+ *    board can actually demonstrate and the catalogue turns the rest into a to-do list rather
+ *    than an absence. The loop deliberately covers work going WRONG as well as right
+ *    (`diagnose-failure`): a first run fails often, and that was the one state on the whole arc
+ *    with no walkthrough.
  *  - The PLATFORM behind it (`offeredAtLaunch: false`) — the engine the agents run on, the
- *    pipelines that sequence them, the standards they read, the systems they talk to. Each is
- *    gated on a PERMISSION rather than on board state, so every one is startable on a brand-new
- *    board; offered at launch they would bury the two tours a first-time user can act on. They
- *    are reference material someone goes and gets from the catalogue when the question comes up,
- *    which is why each covers ONE surface and ends there rather than touring the sidebar: these
- *    surfaces open as modals, so a step after one cannot reach another sidebar entry anyway.
+ *    pipelines that sequence them, the standards they read, the systems they talk to, where
+ *    their containers and environments come from, and the two libraries that change what a
+ *    review or a design is made of. Each is gated on a PERMISSION or a deployment CAPABILITY
+ *    rather than on board state, so every one is startable on a brand-new board; offered at
+ *    launch they would bury the two tours a first-time user can act on. They are reference
+ *    material someone goes and gets from the catalogue when the question comes up, which is why
+ *    each covers ONE surface and ends there rather than touring the sidebar: these surfaces open
+ *    as modals, so a step after one cannot reach another sidebar entry anyway.
+ *
+ * The two halves also differ in what they are FOR now that the finish card hands off
+ * (`nextTourAfter`): the loop is a course, taken in order, each tour unlocked by the last one's
+ * own outcome; the platform half is a shelf. That is why the handoff prefers a launch-offer tour
+ * whatever its `order` — a deployment's own reference tour must not cut into the arc.
  */
 
 /**
@@ -98,6 +108,28 @@ export const TUTORIAL_REQUIREMENTS = {
     labelKey: 'tutorial.requirements.finishedRun',
     met: (gates) => gates.boardHasFinishedRun,
   },
+  failedRun: {
+    id: 'failed-run',
+    labelKey: 'tutorial.requirements.failedRun',
+    met: (gates) => gates.boardHasFailedRun,
+  },
+  // Two deployment-capability requirements the newer surfaces need. `infrastructure` is the
+  // gate of the sidebar entry its tour clicks (`nav-infrastructure`), which already folds in
+  // `integrations.manage`; `advancedTier` is the INTERFACE MODE, and it is a requirement in its
+  // own right for the two reasons the README's drift-guard section names: an entry marked
+  // `advanced: true` is absent from BASIC mode, which is the shipped default, and a SECTION
+  // inside a basic-mode surface can hide itself the same way. Either leaves a tour hunting for
+  // an anchor that nearly every user's screen does not render.
+  infrastructure: {
+    id: 'infrastructure',
+    labelKey: 'tutorial.requirements.infrastructure',
+    met: (gates) => gates.infrastructureAvailable,
+  },
+  advancedTier: {
+    id: 'advanced-tier',
+    labelKey: 'tutorial.requirements.advancedTier',
+    met: (gates) => gates.advancedMode,
+  },
   // The platform half's requirements. Each mirrors, exactly, the `gate` of the sidebar entry the
   // tour clicks (`nav-model-providers` / `nav-integrations`, `nav-fragments`). A requirement
   // WEAKER than the gate of the control a step points at offers the tour to a user who has no
@@ -431,6 +463,59 @@ export const TUTORIAL_TOURS: readonly TutorialTour[] = [
       },
     ],
   },
+  {
+    id: 'diagnose-failure',
+    order: 45,
+    icon: 'i-lucide-triangle-alert',
+    titleKey: 'tutorial.tours.diagnoseFailure.title',
+    descriptionKey: 'tutorial.tours.diagnoseFailure.description',
+    // The state a first run reaches most often, and the one the catalog had nothing for. Every
+    // other delivery-loop tour describes work going right: `review-merge` requires a run that
+    // finished SUCCESSFULLY, so a user whose runs all failed was offered a walkthrough of the
+    // happy path they cannot reach and no account of the screen they are actually looking at.
+    // That is the point at which people conclude the product does not work.
+    requires: [TUTORIAL_REQUIREMENTS.failedRun],
+    steps: [
+      {
+        id: 'intro',
+        titleKey: 'tutorial.tours.diagnoseFailure.steps.intro.title',
+        bodyKey: 'tutorial.tours.diagnoseFailure.steps.intro.body',
+      },
+      {
+        // The banner, not the card: `TaskCard` swaps its progress bar for the shared failure
+        // banner on a failed run, and that banner is the whole subject of this tour.
+        id: 'banner',
+        target: 'agent-failure-banner',
+        placement: 'right',
+        titleKey: 'tutorial.tours.diagnoseFailure.steps.banner.title',
+        bodyKey: 'tutorial.tours.diagnoseFailure.steps.banner.body',
+      },
+      {
+        // NOT `target-click`, for `design-pipeline`'s reason rather than `run-task`'s: Retry is
+        // rendered but DISABLED without `runs.execute`, and a click-to-advance step whose
+        // control cannot be clicked drops its Next button and strands the tour. The copy
+        // therefore describes retrying rather than instructing it. (A retry also spends model
+        // budget, so handing the decision back is right on both counts.)
+        id: 'retry',
+        target: 'agent-failure-retry',
+        placement: 'right',
+        titleKey: 'tutorial.tours.diagnoseFailure.steps.retry.title',
+        bodyKey: 'tutorial.tours.diagnoseFailure.steps.retry.body',
+      },
+      {
+        id: 'finish',
+        titleKey: 'tutorial.tours.diagnoseFailure.steps.finish.title',
+        bodyKey: 'tutorial.tours.diagnoseFailure.steps.finish.body',
+      },
+    ],
+    // Deliberately NOT anchored on `agent-failure-history` or
+    // `agent-failure-configure-environment`, both of which the finish card mentions in prose
+    // instead. Each renders only in a narrower state than this tour's own requirement (a trail
+    // of PRIOR attempts; a failure whose kind is `environment`), so a step on either would need
+    // its own `when` and therefore its own gate, added for one step apiece — and left without
+    // one it would count as an unexpected skip and tell a user who saw exactly the right
+    // walkthrough that they missed part of it.
+  },
   {
     id: 'review-merge',
     order: 50,
@@ -681,6 +766,143 @@ export const TUTORIAL_TOURS: readonly TutorialTour[] = [
       },
     ],
   },
+  {
+    id: 'prepare-infrastructure',
+    order: 100,
+    icon: 'i-lucide-server-cog',
+    titleKey: 'tutorial.tours.prepareInfrastructure.title',
+    descriptionKey: 'tutorial.tours.prepareInfrastructure.description',
+    // Where agent containers run, what a test environment is brought up from, and which
+    // credentials the capabilities an agent uses are allowed to resolve. None of it announces
+    // itself, and the cost of not finding it is a run that fails on provisioning with a banner
+    // pointing at a window the user has never opened.
+    offeredAtLaunch: false,
+    requires: [TUTORIAL_REQUIREMENTS.infrastructure],
+    steps: [
+      {
+        id: 'intro',
+        titleKey: 'tutorial.tours.prepareInfrastructure.steps.intro.title',
+        bodyKey: 'tutorial.tours.prepareInfrastructure.steps.intro.body',
+      },
+      {
+        id: 'open',
+        target: 'nav-infrastructure',
+        advanceOn: 'target-click',
+        placement: 'right',
+        titleKey: 'tutorial.tours.prepareInfrastructure.steps.open.title',
+        bodyKey: 'tutorial.tours.prepareInfrastructure.steps.open.body',
+      },
+      {
+        // The tab STRIP, not any one tab's panel. Which tabs exist is itself resolved from three
+        // independent availability probes, so a step anchored on a panel inside one of them
+        // (`capability-credentials-panel`, `compose-env-setup-section`) points at a control that
+        // exists only while that tab is both offered AND selected — and the tour cannot select
+        // it, since the click that would is the user's. The strip is what the window always
+        // renders, and naming the tabs in the copy is what this tour is for.
+        id: 'tabs',
+        target: 'infrastructure-tabs',
+        waitForTargetMs: 8000,
+        placement: 'bottom',
+        titleKey: 'tutorial.tours.prepareInfrastructure.steps.tabs.title',
+        bodyKey: 'tutorial.tours.prepareInfrastructure.steps.tabs.body',
+      },
+      {
+        id: 'finish',
+        titleKey: 'tutorial.tours.prepareInfrastructure.steps.finish.title',
+        bodyKey: 'tutorial.tours.prepareInfrastructure.steps.finish.body',
+      },
+    ],
+  },
+  {
+    id: 'panel-reviews',
+    order: 110,
+    icon: 'i-lucide-users',
+    titleKey: 'tutorial.tours.panelReviews.title',
+    descriptionKey: 'tutorial.tours.panelReviews.description',
+    // A review step can run as a multi-model PANEL instead of one agent, chosen per estimate
+    // tier from a workspace group library. Nobody guesses that from a pipeline: the step looks
+    // like every other review step until a group exists for it to select.
+    offeredAtLaunch: false,
+    // `advancedTier` is NOT redundant beside `settingsManage`, and the nav drift guard cannot
+    // see why: `nav-model-config` is a basic-mode entry, but the consensus SECTION inside that
+    // panel renders on `uiMode.isAdvanced || groups.hasGroups`, so on the shipped default tier a
+    // workspace that has never made a group renders nothing for the anchored step to find. The
+    // guard only pairs a tour against the visibility of a NAV entry, so a section hiding itself
+    // one level in is exactly the case that has to be declared by hand.
+    requires: [TUTORIAL_REQUIREMENTS.settingsManage, TUTORIAL_REQUIREMENTS.advancedTier],
+    steps: [
+      {
+        id: 'intro',
+        titleKey: 'tutorial.tours.panelReviews.steps.intro.title',
+        bodyKey: 'tutorial.tours.panelReviews.steps.intro.body',
+      },
+      {
+        id: 'open',
+        target: 'nav-model-config',
+        advanceOn: 'target-click',
+        placement: 'right',
+        titleKey: 'tutorial.tours.panelReviews.steps.open.title',
+        bodyKey: 'tutorial.tours.panelReviews.steps.open.body',
+      },
+      {
+        id: 'groups',
+        target: 'consensus-group-new',
+        waitForTargetMs: 8000,
+        placement: 'top',
+        titleKey: 'tutorial.tours.panelReviews.steps.groups.title',
+        bodyKey: 'tutorial.tours.panelReviews.steps.groups.body',
+      },
+      {
+        id: 'finish',
+        titleKey: 'tutorial.tours.panelReviews.steps.finish.title',
+        bodyKey: 'tutorial.tours.panelReviews.steps.finish.body',
+      },
+    ],
+  },
+  {
+    id: 'share-services',
+    order: 120,
+    icon: 'i-lucide-library-big',
+    titleKey: 'tutorial.tours.shareServices.title',
+    descriptionKey: 'tutorial.tours.shareServices.description',
+    // The catalog of shared capabilities an org already runs, with the API contracts a design
+    // is expected to build ON rather than reinvent. Without it an architect agent designs every
+    // service as if the estate were empty.
+    offeredAtLaunch: false,
+    // `nav-foundational-services` is marked `advanced: true`, so the tier is part of what
+    // renders the entry this tour clicks. Declared rather than assumed: `navRequirementDrift`
+    // enumerates the whole gate matrix against that entry's own visibility rule and fails
+    // without it.
+    requires: [TUTORIAL_REQUIREMENTS.settingsManage, TUTORIAL_REQUIREMENTS.advancedTier],
+    steps: [
+      {
+        id: 'intro',
+        titleKey: 'tutorial.tours.shareServices.steps.intro.title',
+        bodyKey: 'tutorial.tours.shareServices.steps.intro.body',
+      },
+      {
+        id: 'open',
+        target: 'nav-foundational-services',
+        advanceOn: 'target-click',
+        placement: 'right',
+        titleKey: 'tutorial.tours.shareServices.steps.open.title',
+        bodyKey: 'tutorial.tours.shareServices.steps.open.body',
+      },
+      {
+        id: 'catalog',
+        target: 'foundational-manager',
+        waitForTargetMs: 8000,
+        placement: 'bottom',
+        titleKey: 'tutorial.tours.shareServices.steps.catalog.title',
+        bodyKey: 'tutorial.tours.shareServices.steps.catalog.body',
+      },
+      {
+        id: 'finish',
+        titleKey: 'tutorial.tours.shareServices.steps.finish.title',
+        bodyKey: 'tutorial.tours.shareServices.steps.finish.body',
+      },
+    ],
+  },
 ]
 
 /** The module that contributes the catalog; registered by `createAppRegistry`. */

package/app/pages/index.vue

@@ -143,7 +143,8 @@ const AiPresetMismatchDialog = defineAsyncComponent(
 )
 // The in-app tutorial: the launch prompt (auto-opened once for a user who never answered
 // it), the catalogue of every tour the deployment ships (opened from the sidebar's Help
-// section or the palette, at any time), and the coach-mark overlay that runs a tour. All
+// section or the palette, at any time), the coach-mark overlay that runs a tour, and the
+// contextual offer that raises the ONE walkthrough this board just made takeable. All
 // mount only while their store flag is set, so they cost the initial bundle nothing.
 const TutorialPrompt = defineAsyncComponent(
   () => import('~/components/tutorial/TutorialPrompt.vue'),
@@ -154,6 +155,7 @@ const TutorialCatalogue = defineAsyncComponent(
 const TutorialOverlay = defineAsyncComponent(
   () => import('~/components/tutorial/TutorialOverlay.vue'),
 )
+const TutorialNudge = defineAsyncComponent(() => import('~/components/tutorial/TutorialNudge.vue'))
 
 const workspace = useWorkspaceStore()
 const github = useGitHubStore()
@@ -332,6 +334,18 @@ if (!tutorialOfferSettled()) {
   )
   if (tutorialOfferSettled()) stopTutorialOffer()
 }
+// The CONTEXTUAL offer: a different mechanism from the launch one above, so it sits outside that
+// watcher's `settled` guard. It has no decision to settle and nothing to defer, because it fires
+// on a tour becoming TAKEABLE rather than on the app starting. It reads `workspace.ready` itself
+// rather than being gated here, because readiness is not a precondition for CALLING it but the
+// definition of its baseline: the gates it watches are board state, so a baseline taken before
+// the snapshot lands makes the board's own hydration look like a transition (see `resolveNudge`).
+// It honours an explicit decline itself, too (see `newlyAvailableTour`).
+useTutorialNudge()
+// The mirror to the signed-in user's server row (so progress follows the PERSON, not the browser)
+// plus the funnel counters. Unconditional and best-effort: with no accounts or no store wired it
+// simply has nothing to talk to, and the browser-persisted store carries on alone.
+useTutorialSync()
 
 // Probe the GitHub integration as soon as a board is active (re-probe per board —
 // connections are per workspace). The result drives the onboarding gate below
@@ -518,6 +532,11 @@ watch(
       <TutorialPrompt v-if="tutorial.promptOpen" />
       <TutorialCatalogue v-if="tutorial.catalogueOpen" />
       <TutorialOverlay v-if="tutorial.touring" />
+      <!-- Mounted off the PENDING id rather than off whether it may currently be SHOWN: the
+           component holds a suppressed offer (a tour is running, a tutorial window is open) and
+           renders it once the way is clear, which is the whole reason the offer survives the
+           moment it was raised in. -->
+      <TutorialNudge v-if="tutorial.pendingNudgeId" />
     </template>
 
     <!-- Backend unreachable / bootstrap failed -->

package/app/stores/tutorial.prompt.ts

@@ -0,0 +1,59 @@
+import { ref } from 'vue'
+
+/**
+ * The LAUNCH PROMPT's own state machine, extracted from `stores/tutorial.ts`.
+ *
+ * It is a small machine with four distinguishable exits and no other consumer, which is what makes
+ * it a seam worth having rather than four refs among twenty: closing without answering, an explicit
+ * decline, a DEFERRAL (something the user must actually answer opened on top), and the
+ * once-per-session auto-open are four different things, and only two of them write anything down.
+ * The subtlety they share is the ONE-OFFER-PER-SESSION guard, which is why they belong together:
+ * `promptAutoOpened` must be spent by an offer the user saw and NOT by one that was withdrawn.
+ *
+ * `hasDecision` is a bound getter over the persisted record rather than the record itself, so this
+ * module never learns what a decision IS — only whether one exists, which is the whole of what the
+ * offer needs.
+ */
+export function createTutorialPrompt(deps: { hasDecision: () => boolean }) {
+  const promptOpen = ref(false)
+  /** Once-per-session guard for the launch auto-open; later opens are user-driven. */
+  const promptAutoOpened = ref(false)
+
+  /**
+   * Auto-open the launch prompt, at most once per session and only while the user has never
+   * answered it. Callers gate on the rest of the launch context (board ready, no other startup
+   * advisory open) — see `pages/index.vue`.
+   */
+  function maybeOfferOnLaunch() {
+    if (deps.hasDecision() || promptAutoOpened.value) return
+    promptAutoOpened.value = true
+    promptOpen.value = true
+  }
+
+  /** User-driven open (command palette), regardless of any saved decision. */
+  function openPrompt() {
+    promptOpen.value = true
+  }
+
+  /**
+   * Withdraw an offer this store made, because something the user actually has to answer (a startup
+   * advisory, the GitHub onboarding gate) opened on top of it — and re-arm, so the offer returns
+   * once that surface is gone. Distinct from {@link closePrompt}: no decision is written EITHER way,
+   * but a deferral was not the user's doing, so it must not consume this session's one offer.
+   *
+   * Only ever withdraws the AUTO-opened prompt; a prompt the user opened themselves from the palette
+   * is theirs to close.
+   */
+  function deferPrompt() {
+    if (!promptAutoOpened.value) return
+    promptOpen.value = false
+    promptAutoOpened.value = false
+  }
+
+  /** Close without answering: no decision is written, so the next launch asks again. */
+  function closePrompt() {
+    promptOpen.value = false
+  }
+
+  return { promptOpen, promptAutoOpened, maybeOfferOnLaunch, openPrompt, deferPrompt, closePrompt }
+}

package/app/stores/tutorial.record.ts

@@ -0,0 +1,191 @@
+import { ref } from 'vue'
+
+/** The launch-prompt answer. `null` = never answered, so the app asks again next launch. */
+export type TutorialDecision = 'accepted' | 'declined'
+
+/** The server's copy of a user's record, as the snapshot delivers it. */
+export interface RemoteTutorialRecord {
+  decision: TutorialDecision | null
+  completedTourIds: readonly string[]
+  nudgedTourIds: readonly string[]
+}
+
+/**
+ * The PERSISTED tier of the tutorial's state: the standing record of what this PERSON has done.
+ *
+ * Extracted from `stores/tutorial.ts` along the boundary that store's own docblock already draws.
+ * Everything here outlives a visit and is mirrored to the signed-in user's server row; everything
+ * left behind (the prompt, the catalogue, the step cursor, the resume point, which offer is on
+ * screen) is session state that a reload is right to discard. Splitting on that line also put every
+ * piece of the sync story in one module: the union rule, what counts as "this browser knows more",
+ * and the flag the mirror acts on.
+ *
+ * A factory rather than a second Pinia store, because the two tiers are one store's worth of state
+ * to every consumer: the returned refs go straight into the setup store's state, so
+ * `persist: { pick: [...] }` and every existing `tutorial.completedTourIds` read are unchanged.
+ */
+export function createTutorialRecord() {
+  /** The saved launch-prompt answer. Written only by an explicit accept/decline/reset. */
+  const decision = ref<TutorialDecision | null>(null)
+  /** Ids of tours the user finished (reached the last step's Done). */
+  const completedTourIds = ref<string[]>([])
+  /**
+   * Ids the CONTEXTUAL offer has already been spent on (see `newlyAvailableTour`). Persisted beside
+   * the completions, because "we have mentioned this once" is a fact about the person, not about
+   * this visit: re-offering the parked-run walkthrough on every reload is a nag, and the gates it
+   * watches flip several times per run.
+   */
+  const nudgedTourIds = ref<string[]>([])
+  /**
+   * This browser holds progress the server row does not, so the mirror owes it a write.
+   *
+   * Session-lived and a FLAG rather than a direct call, because the merge below runs inside the
+   * snapshot fan-out, which is synchronous and store-only. `useTutorialSync` watches it.
+   */
+  const serverPushNeeded = ref(false)
+  /**
+   * Counts LOCAL changes to this record, and nothing else. Session-lived.
+   *
+   * The mirror watches this rather than the state itself, and the distinction is the whole reason
+   * it exists: adopting the server's ids in {@link mergeServerProgress} also changes the state, so
+   * a watcher over the state pushes the server's own row straight back at it on every fresh-browser
+   * board load. Counting only what the USER did means a write happens exactly when this browser has
+   * something to say.
+   */
+  const localRev = ref(0)
+  /**
+   * The local `decision` has changed and has not been mirrored yet, so it must survive a snapshot.
+   *
+   * Without this, a failed mirror write silently UNDOES the user's answer: they click "No thanks",
+   * the push fails, and the next snapshot re-adopts the older `accepted` from the server row,
+   * re-arming every contextual offer they just declined. The server row wins on `decision` because
+   * it is the shared record of the latest answer, but only where this browser is not itself holding
+   * a newer one that the server has not seen.
+   */
+  const decisionDirty = ref(false)
+
+  const isCompleted = (tourId: string) => completedTourIds.value.includes(tourId)
+  const wasNudged = (tourId: string) => nudgedTourIds.value.includes(tourId)
+
+  /** Record a finished walkthrough. Idempotent: the same tour taken twice is still one entry. */
+  function markCompleted(tourId: string) {
+    if (isCompleted(tourId)) return
+    completedTourIds.value = [...completedTourIds.value, tourId]
+    localRev.value += 1
+  }
+
+  /** Spend the contextual offer for a tour. Idempotent, so an offer can never be made twice. */
+  function markNudged(tourId: string) {
+    if (wasNudged(tourId)) return
+    nudgedTourIds.value = [...nudgedTourIds.value, tourId]
+    localRev.value += 1
+  }
+
+  /** Record an answer to the launch prompt, and ask the mirror to carry it. */
+  function answer(next: TutorialDecision) {
+    if (decision.value === next) return
+    decision.value = next
+    decisionDirty.value = true
+    localRev.value += 1
+  }
+
+  /** Starting a tour IS accepting the tutorial, however the user got there. */
+  function acceptOffer() {
+    answer('accepted')
+  }
+
+  /** The explicit "no thanks": saved, so the launch prompt never auto-opens again. */
+  function declineOffer() {
+    answer('declined')
+  }
+
+  /**
+   * Fold the signed-in user's SERVER copy into this browser's, and report whether the local copy
+   * held anything the server did not.
+   *
+   * A union rather than a replace, in the same direction and for the same reason the server merges:
+   * both lists are grow-only sets of things that HAPPENED, so neither side is ever right to un-say
+   * one. A replace here would lose a tour finished while the mirror write was failing; a replace on
+   * the server would lose a tour finished on another machine. `decision` is taken from the server
+   * when it HAS one and this browser is not holding an un-mirrored answer of its own
+   * ({@link decisionDirty}), because it is a preference someone re-answers rather than an
+   * accumulating fact — while a server row with no answer is not evidence that the local answer
+   * never happened.
+   *
+   * The return value closes the loop: `true` means this browser knows something the server does not,
+   * so the merged state is worth pushing back. Recomputing that comparison at the call site would be
+   * a second copy of the union rule. It is also what makes the server's un-guarded merge safe: the
+   * PUT's response goes through here too, so a merge that lost a concurrent writer's ids comes back
+   * missing something local, and the re-push is automatic rather than hoped for.
+   */
+  function mergeServerProgress(remote: RemoteTutorialRecord | null): boolean {
+    // No server copy at all (no accounts, no store wired, or the read degraded) is NOT a reason to
+    // push: there is nothing to reconcile against, and treating an absent row as an empty one would
+    // make every such board load write a mirror nothing reads.
+    if (!remote) return false
+    const union = (mine: string[], theirs: readonly string[]) => [...new Set([...theirs, ...mine])]
+    const completed = union(completedTourIds.value, remote.completedTourIds)
+    const nudged = union(nudgedTourIds.value, remote.nudgedTourIds)
+    const keepLocalDecision = decisionDirty.value || remote.decision === null
+    const localOnly =
+      completed.length > remote.completedTourIds.length ||
+      nudged.length > remote.nudgedTourIds.length ||
+      (keepLocalDecision && decision.value !== remote.decision)
+    completedTourIds.value = completed
+    nudgedTourIds.value = nudged
+    if (!keepLocalDecision) decision.value = remote.decision
+    if (localOnly) serverPushNeeded.value = true
+    return localOnly
+  }
+
+  /**
+   * The mirror has caught up: this browser's state is on the server, including its answer.
+   *
+   * Called BEFORE the response is reconciled, so that a response missing something local can flip
+   * {@link serverPushNeeded} back on and re-trigger the watcher. Clearing it after would look
+   * identical and would swallow exactly the retry that matters.
+   */
+  function markServerPushed() {
+    serverPushNeeded.value = false
+    decisionDirty.value = false
+  }
+
+  /**
+   * Forget the whole record, including the answered offer.
+   *
+   * The decision goes with it deliberately: "Reset" is asked for by someone handing the app to a
+   * colleague, demoing it, or re-walking the product after it changed, and every one of those wants
+   * the first-launch experience back, which a cleared completion list alone does not restore. The
+   * spent contextual offers go too, or a board that has already run something would never make
+   * those offers again to the colleague the app was just handed to.
+   *
+   * Deliberately does NOT bump {@link localRev}, and cancels any pending mirror write. The server
+   * side of a reset is a DELETE, and a PUT of the freshly-emptied state racing it would re-create
+   * the row the DELETE just removed — leaving "reset it" distinguishable from "never touched the
+   * tutorial", which is the one thing the reset has to get right.
+   */
+  function reset() {
+    completedTourIds.value = []
+    nudgedTourIds.value = []
+    decision.value = null
+    serverPushNeeded.value = false
+    decisionDirty.value = false
+  }
+
+  return {
+    decision,
+    completedTourIds,
+    nudgedTourIds,
+    serverPushNeeded,
+    localRev,
+    isCompleted,
+    wasNudged,
+    markCompleted,
+    markNudged,
+    acceptOffer,
+    declineOffer,
+    mergeServerProgress,
+    markServerPushed,
+    reset,
+  }
+}