@cat-factory/app 0.213.1 → 0.215.0

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', () => {

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 }
+}