@cat-factory/app 0.207.0 → 0.208.1

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

@@ -7,9 +7,11 @@ import {
   TUTORIAL_TOURS,
   tutorialToursModule,
 } from '~/modular/tutorial-tours'
-import { resolveTourCatalogue, resolveTours } from '~/utils/tutorial'
+import { isLaunchOffer, resolveTourCatalogue, resolveTours } from '~/utils/tutorial'
 import { isSafeTargetId } from '~/components/tutorial/TutorialOverlay.logic'
-import type { NavGates } from '~/modular/nav-contributions'
+import { NAV_CONTRIBUTIONS, navItemVisible } from '~/modular/nav-contributions'
+import type { NavContribution, NavGates } from '~/modular/nav-contributions'
+import type { TutorialStep, TutorialTour } from '~/utils/tutorial'
 
 const ALL_GATES: NavGates = {
   canWriteBoard: true,
@@ -100,6 +102,90 @@ function declaredAnchors(): { label: string; id: string }[] {
   return out
 }
 
+/**
+ * Every step whose anchor IS a nav entry, paired with the contribution it points at.
+ *
+ * Those steps are the ones a tour's `requires` has to agree with, because the anchor only
+ * exists while the sidebar/palette renders that entry. An anchor that is NOT a nav entry (a
+ * control inside the modal the click opens) has no contribution to pair with and is left to
+ * the anchor guard above; `altTargets` are included, since a fallback anchor is reached on
+ * exactly the same terms as the primary one.
+ */
+function navAnchoredSteps(): {
+  tour: TutorialTour
+  step: TutorialStep
+  item: NavContribution
+  label: string
+}[] {
+  const byTestId = new Map(
+    NAV_CONTRIBUTIONS.flatMap((item) => (item.testId ? [[item.testId, item] as const] : [])),
+  )
+  return TUTORIAL_TOURS.flatMap((tour) =>
+    tour.steps.flatMap((step) =>
+      [step.target, ...(step.altTargets ?? [])].flatMap((target) => {
+        const item = target === undefined ? undefined : byTestId.get(target)
+        return item ? [{ tour, step, item, label: `${tour.id}/${step.id} -> ${item.id}` }] : []
+      }),
+    ),
+  )
+}
+
+/**
+ * Every combination of the {@link NavGates} booleans, yielded lazily so the 2^N gate sets are
+ * never all live at once.
+ *
+ * Enumerating rather than reasoning is deliberate. The pairing below is an IMPLICATION over
+ * gate sets — anything that satisfies a tour must also render its entry — between two
+ * predicates written independently in two files, and nothing about their shape is guaranteed
+ * (either may be a conjunction, a disjunction, or read a field the other doesn't). At fifteen
+ * fields the whole matrix costs milliseconds, which is a fair price for a guard that needs no
+ * assumption about how either side is spelled.
+ */
+function* everyGateSet(): Generator<NavGates> {
+  const keys = Object.keys(ALL_GATES) as (keyof NavGates)[]
+  for (let mask = 0; mask < 2 ** keys.length; mask++) {
+    const gates = {} as Record<keyof NavGates, boolean>
+    for (const [bit, key] of keys.entries()) gates[key] = (mask & (1 << bit)) !== 0
+    yield gates as NavGates
+  }
+}
+
+/** The gate fields a witness has turned OFF — the interesting half of a failure message. */
+function absentGates(gates: NavGates): readonly string[] {
+  return Object.entries(gates)
+    .filter(([, value]) => value === false)
+    .map(([key]) => key)
+}
+
+/**
+ * A gate set that OFFERS this tour while the entry its step clicks is NOT rendered, or
+ * `undefined` when no such set exists (what the guard wants). A step the gate set DROPS
+ * (`when`) needs no anchor, so it cannot be a counterexample.
+ *
+ * Of the many counterexamples one break produces, the one reported is the SMALLEST: the gate
+ * set closest to fully-permitted, so its absent fields are exactly the ones that matter. The
+ * first witness the matrix happens to reach names most of `NavGates` and reads as noise, which
+ * is the difference between a failure that says "declare `advancedMode`" and one that says
+ * "something about fourteen gates".
+ */
+function navRequirementDrift(
+  pair: ReturnType<typeof navAnchoredSteps>[number],
+): NavGates | undefined {
+  let smallest: NavGates | undefined
+  let fewestAbsent = Number.POSITIVE_INFINITY
+  for (const gates of everyGateSet()) {
+    if (!(pair.tour.requires ?? []).every((requirement) => requirement.met(gates))) continue
+    if (pair.step.when && !pair.step.when(gates)) continue
+    if (navItemVisible(pair.item, gates)) continue
+    const absent = absentGates(gates).length
+    if (absent < fewestAbsent) {
+      fewestAbsent = absent
+      smallest = gates
+    }
+  }
+  return smallest
+}
+
 /** Every static test id this layer actually renders. */
 function renderedTestIds(): Set<string> {
   const ids = new Set<string>()
@@ -190,14 +276,52 @@ describe('the built-in tutorial tour catalog', () => {
     expect(missing).toEqual([])
   })
 
+  it('requires, of every step that clicks a nav entry, whatever renders that entry', () => {
+    // The other drift guard, and the one the availability cases below CANNOT stand in for.
+    // Those assert this pairing by restating the permission in a hand-built gate set, which
+    // says nothing about the nav catalog: both edits that really break the pairing happen in
+    // `nav-contributions.ts` and touch no tour.
+    //
+    //  - an entry's `gate` gains a clause the tour doesn't require;
+    //  - an entry is marked `advanced: true`, which removes it from BASIC mode — and basic is
+    //    the SHIPPED DEFAULT, so the tour would then be offered to nearly every user and find
+    //    nothing.
+    //
+    // Both land on the same production failure: the tour is offered, hunts for an anchor that
+    // this user's sidebar never renders, skips the step (no `when`, so the miss COUNTS) and
+    // leaves them on a permanent "you missed N steps" notice about a walkthrough that could
+    // not have gone any other way. So the requirement is derived from the entry's OWN
+    // visibility rule (`navItemVisible`, the function `navSlotFilter` itself filters with)
+    // 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
+    // matrix, leaving whatever it gates unexercised.
+    expect(pairs.length).toBeGreaterThanOrEqual(5)
+    expect(Object.values(ALL_GATES).every((value) => typeof value === 'boolean')).toBe(true)
+
+    const drifted = pairs.flatMap((pair) => {
+      const witness = navRequirementDrift(pair)
+      if (witness === undefined) return []
+      return [`${pair.label} is offered without ${absentGates(witness).join(' / ')}`]
+    })
+    expect(drifted).toEqual([])
+  })
+
   it('is contributed to the tutorialTours slot by the module', () => {
     expect(tutorialToursModule.slots?.tutorialTours).toEqual([...TUTORIAL_TOURS])
   })
 })
 
 describe('tour availability across the catalog', () => {
-  /** The ids a board can START right now — what the launch prompt offers. */
+  /** The ids a board can START right now — every startable tour, whatever offers it. */
   const ready = (gates: NavGates) => resolveTours(TUTORIAL_TOURS, gates).map((t) => t.id)
+  /** The narrower set the LAUNCH PROMPT asks about (`useTutorialTours().offered`). */
+  const offered = (gates: NavGates) =>
+    resolveTours(TUTORIAL_TOURS, gates)
+      .filter(isLaunchOffer)
+      .map((t) => t.id)
   /** The catalogue's own view: every tour, with what is holding each one back. */
   const entry = (gates: NavGates, tourId: string) =>
     resolveTourCatalogue(TUTORIAL_TOURS, gates).find((e) => e.tour.id === tourId)
@@ -207,14 +331,19 @@ describe('tour availability across the catalog', () => {
   })
 
   it('lists the whole catalog whatever the gates say, holding back rather than hiding', () => {
-    // The catalogue surface's contract. A fresh board can run two of the six walkthroughs;
-    // dropping the other four (all a slot filter could do) would misrepresent the product as
-    // shipping two, to exactly the user who came looking for the rest.
+    // The catalogue surface's contract. A fresh board can run the two delivery-loop tours that
+    // need no board state plus the whole platform half; dropping the rest (all a slot filter
+    // could do) would misrepresent the product as shipping fewer walkthroughs than it does, to
+    // exactly the user who came looking for them.
     const catalogue = resolveTourCatalogue(TUTORIAL_TOURS, FRESH_BOARD)
     expect(catalogue.map((e) => e.tour.id)).toEqual(TUTORIAL_TOURS.map((t) => t.id))
     expect(catalogue.filter((e) => e.availability === 'ready').map((e) => e.tour.id)).toEqual([
       'board-basics',
       'add-service',
+      'wire-models',
+      'design-pipeline',
+      'agent-standards',
+      'connect-systems',
     ])
   })
 
@@ -234,18 +363,68 @@ describe('tour availability across the catalog', () => {
   })
 
   it('offers a brand-new board the orientation tour AND the way out of being empty', () => {
-    // The state the launch prompt actually auto-opens in. Orientation alone would leave a
-    // new workspace with a tour of an empty canvas and no route to a first service, which
-    // is what `add-service` exists to fix — so it must survive exactly this gate set.
-    expect(ready(FRESH_BOARD)).toEqual(['board-basics', 'add-service'])
+    // The state the launch prompt actually auto-opens in, asserted on what it ASKS ABOUT.
+    // Orientation alone would leave a new workspace with a tour of an empty canvas and no route
+    // to a first service, which is what `add-service` exists to fix — so it must survive exactly
+    // this gate set. And nothing else may join it here: this is a modal with one question, and
+    // the platform tours are all startable on a fresh board (they need only a permission), so
+    // without the offer/library split they would bury both of these four-to-two.
+    expect(offered(FRESH_BOARD)).toEqual(['board-basics', 'add-service'])
+  })
+
+  it('keeps the platform tours in the catalogue rather than in the launch offer', () => {
+    // The split, stated as a table so promoting a tour into the first-launch question has to be
+    // written down here. The delivery loop is the arc a first-time user is answering about; the
+    // platform half is reference material they go and get from the catalogue, where it is listed,
+    // counted and startable exactly like the rest.
+    const LAUNCH_ARC = [
+      'board-basics',
+      'add-service',
+      'first-task',
+      'run-task',
+      'answer-park',
+      'review-merge',
+    ]
+    const CATALOGUE_ONLY = ['wire-models', 'design-pipeline', 'agent-standards', 'connect-systems']
+    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.
+    expect(ready(ALL_GATES)).toEqual(expect.arrayContaining(CATALOGUE_ONLY))
   })
 
   it('names the missing connection when no source control can list repositories', () => {
     const noSource: NavGates = { ...FRESH_BOARD, githubAvailable: false }
-    expect(ready(noSource)).toEqual(['board-basics'])
+    expect(offered(noSource)).toEqual(['board-basics'])
     expect(entry(noSource, 'add-service')?.unmet.map((r) => r.id)).toEqual(['source-control'])
   })
 
+  it('holds each platform tour back on the permission its own sidebar entry needs', () => {
+    // Every one of these tours clicks a sidebar entry as its second step, so its requirement has
+    // to be the SAME fact that renders the entry. A weaker one offers the tour to a user with no
+    // such control: it would hunt for the anchor, skip the rest and report itself abridged.
+    const member: NavGates = {
+      ...ALL_GATES,
+      canManageIntegrations: false,
+      canManageSettings: false,
+    }
+    expect(ready(member)).not.toContain('wire-models')
+    expect(ready(member)).not.toContain('connect-systems')
+    expect(ready(member)).not.toContain('agent-standards')
+    expect(entry(member, 'wire-models')?.unmet.map((r) => r.id)).toEqual(['integrations-manage'])
+    expect(entry(member, 'connect-systems')?.unmet.map((r) => r.id)).toEqual([
+      'integrations-manage',
+    ])
+    expect(entry(member, 'agent-standards')?.unmet.map((r) => r.id)).toEqual(['settings-manage'])
+    // A viewer keeps the builder tour out too: it opens a board-write surface.
+    expect(ready({ ...ALL_GATES, canWriteBoard: false })).not.toContain('design-pipeline')
+  })
+
+  it('names the disabled library when the deployment ships no fragment surface', () => {
+    const noLibrary: NavGates = { ...ALL_GATES, libraryAvailable: false }
+    expect(ready(noLibrary)).not.toContain('agent-standards')
+    expect(entry(noLibrary, 'agent-standards')?.unmet.map((r) => r.id)).toEqual(['library'])
+  })
+
   it('offers the run tour once a task exists, and the review tour once a run finished', () => {
     const withTask: NavGates = { ...FRESH_BOARD, boardHasService: true, boardHasTask: true }
     expect(ready(withTask)).toContain('run-task')

package/app/modular/tutorial-tours.ts

@@ -31,11 +31,19 @@ import type { TutorialRequirement, TutorialTour } from '~/utils/tutorial'
  *    anonymous predicate: the catalogue lists every tour this deployment ships and has to say
  *    what a user must do before one it is holding back becomes available.
  *
- * Together the tours below walk 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 — with each
- * later tour requiring the state the previous one produces, so the launch 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 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.
+ *  - 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.
  */
 
 /**
@@ -90,6 +98,28 @@ export const TUTORIAL_REQUIREMENTS = {
     labelKey: 'tutorial.requirements.finishedRun',
     met: (gates) => gates.boardHasFinishedRun,
   },
+  // 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
+  // such control: it then hunts for the anchor, skips every step behind it, and reports itself
+  // abridged — which is the state this mechanism exists to prevent. They are permissions and
+  // deployment wiring rather than board state, which is why those tours are startable on a board
+  // with nothing on it, and therefore why they are kept out of the launch offer.
+  integrationsManage: {
+    id: 'integrations-manage',
+    labelKey: 'tutorial.requirements.integrationsManage',
+    met: (gates) => gates.canManageIntegrations,
+  },
+  settingsManage: {
+    id: 'settings-manage',
+    labelKey: 'tutorial.requirements.settingsManage',
+    met: (gates) => gates.canManageSettings,
+  },
+  library: {
+    id: 'library',
+    labelKey: 'tutorial.requirements.library',
+    met: (gates) => gates.libraryAvailable,
+  },
 } as const satisfies Record<string, TutorialRequirement>
 
 export const TUTORIAL_TOURS: readonly TutorialTour[] = [
@@ -460,6 +490,197 @@ export const TUTORIAL_TOURS: readonly TutorialTour[] = [
       },
     ],
   },
+  // ---------------------------------------------------------------------------------------
+  // The platform half. Ordered after the whole delivery loop so the catalogue reads in the
+  // order someone meets these things: learn the loop, then the machinery under it.
+  // ---------------------------------------------------------------------------------------
+  {
+    id: 'wire-models',
+    order: 60,
+    icon: 'i-lucide-plug-zap',
+    titleKey: 'tutorial.tours.wireModels.title',
+    descriptionKey: 'tutorial.tours.wireModels.description',
+    // The one connection a deployment cannot live without: every pipeline step is a model call,
+    // so with no provider the whole product is inert. It is nonetheless catalogue-only, because a
+    // deployment with nothing wired already gets its own first-launch nudge (the provider
+    // onboarding advisory, which the launch prompt stands down for) — this is for the person who
+    // meets the question later, or who wants to know where the answer lives.
+    offeredAtLaunch: false,
+    requires: [TUTORIAL_REQUIREMENTS.integrationsManage],
+    steps: [
+      {
+        id: 'intro',
+        titleKey: 'tutorial.tours.wireModels.steps.intro.title',
+        bodyKey: 'tutorial.tours.wireModels.steps.intro.body',
+      },
+      {
+        id: 'open',
+        target: 'nav-model-providers',
+        advanceOn: 'target-click',
+        placement: 'right',
+        titleKey: 'tutorial.tours.wireModels.steps.open.title',
+        bodyKey: 'tutorial.tours.wireModels.steps.open.body',
+      },
+      {
+        id: 'hub',
+        target: 'model-providers-hub',
+        // Inside the modal the previous click opens.
+        waitForTargetMs: 8000,
+        placement: 'bottom',
+        titleKey: 'tutorial.tours.wireModels.steps.hub.title',
+        bodyKey: 'tutorial.tours.wireModels.steps.hub.body',
+      },
+      {
+        // Deliberately prose rather than a step pointing at Model configuration: that entry is a
+        // sibling in the same sidebar section, and by now the hub modal is open over it, so a
+        // step anchored there would spend its wait budget on a control the user cannot reach.
+        id: 'finish',
+        titleKey: 'tutorial.tours.wireModels.steps.finish.title',
+        bodyKey: 'tutorial.tours.wireModels.steps.finish.body',
+      },
+    ],
+  },
+  {
+    id: 'design-pipeline',
+    order: 70,
+    icon: 'i-lucide-workflow',
+    titleKey: 'tutorial.tours.designPipeline.title',
+    descriptionKey: 'tutorial.tours.designPipeline.description',
+    // `run-task` teaches picking a pipeline; nothing teaches that the sequence is yours to
+    // change. A user who never finds the builder treats the built-in catalog as the product's
+    // fixed shape and works around it in task descriptions instead.
+    offeredAtLaunch: false,
+    requires: [TUTORIAL_REQUIREMENTS.boardWrite],
+    steps: [
+      {
+        id: 'intro',
+        titleKey: 'tutorial.tours.designPipeline.steps.intro.title',
+        bodyKey: 'tutorial.tours.designPipeline.steps.intro.body',
+      },
+      {
+        id: 'open',
+        target: 'nav-build-pipeline',
+        advanceOn: 'target-click',
+        placement: 'right',
+        titleKey: 'tutorial.tours.designPipeline.steps.open.title',
+        bodyKey: 'tutorial.tours.designPipeline.steps.open.body',
+      },
+      {
+        id: 'palette',
+        target: 'pipeline-builder-palette',
+        // Inside the slideover the previous click opens.
+        waitForTargetMs: 8000,
+        placement: 'right',
+        titleKey: 'tutorial.tours.designPipeline.steps.palette.title',
+        bodyKey: 'tutorial.tours.designPipeline.steps.palette.body',
+      },
+      {
+        id: 'chain',
+        target: 'pipeline-builder-draft',
+        placement: 'right',
+        titleKey: 'tutorial.tours.designPipeline.steps.chain.title',
+        bodyKey: 'tutorial.tours.designPipeline.steps.chain.body',
+      },
+      {
+        // NOT `target-click`, and not for `run-task`'s budget reason: Save is DISABLED until the
+        // draft holds a step, and a click-to-advance step on a control that cannot be clicked
+        // strands the tour — the tooltip drops its Next button, so there is no way forward.
+        //
+        // Which is also why the copy DESCRIBES saving rather than instructing it, and says what
+        // lights the button up. The previous step invites a click on the palette but doesn't
+        // require one, so this step is routinely read with Save greyed out; an imperative title
+        // over a dead control reads as a tour pointing at something broken.
+        id: 'save',
+        target: 'pipeline-builder-save',
+        placement: 'top',
+        titleKey: 'tutorial.tours.designPipeline.steps.save.title',
+        bodyKey: 'tutorial.tours.designPipeline.steps.save.body',
+      },
+      {
+        id: 'finish',
+        titleKey: 'tutorial.tours.designPipeline.steps.finish.title',
+        bodyKey: 'tutorial.tours.designPipeline.steps.finish.body',
+      },
+    ],
+  },
+  {
+    id: 'agent-standards',
+    order: 80,
+    icon: 'i-lucide-book-marked',
+    titleKey: 'tutorial.tours.agentStandards.title',
+    descriptionKey: 'tutorial.tours.agentStandards.description',
+    // How you steer output without restating your conventions in every task description, which
+    // is what people do instead when they never find this.
+    offeredAtLaunch: false,
+    requires: [TUTORIAL_REQUIREMENTS.library, TUTORIAL_REQUIREMENTS.settingsManage],
+    steps: [
+      {
+        id: 'intro',
+        titleKey: 'tutorial.tours.agentStandards.steps.intro.title',
+        bodyKey: 'tutorial.tours.agentStandards.steps.intro.body',
+      },
+      {
+        id: 'open',
+        target: 'nav-fragments',
+        advanceOn: 'target-click',
+        placement: 'right',
+        titleKey: 'tutorial.tours.agentStandards.steps.open.title',
+        bodyKey: 'tutorial.tours.agentStandards.steps.open.body',
+      },
+      {
+        id: 'library',
+        target: 'fragment-library',
+        waitForTargetMs: 8000,
+        placement: 'bottom',
+        titleKey: 'tutorial.tours.agentStandards.steps.library.title',
+        bodyKey: 'tutorial.tours.agentStandards.steps.library.body',
+      },
+      {
+        id: 'finish',
+        titleKey: 'tutorial.tours.agentStandards.steps.finish.title',
+        bodyKey: 'tutorial.tours.agentStandards.steps.finish.body',
+      },
+    ],
+  },
+  {
+    id: 'connect-systems',
+    order: 90,
+    icon: 'i-lucide-blocks',
+    titleKey: 'tutorial.tours.connectSystems.title',
+    descriptionKey: 'tutorial.tours.connectSystems.description',
+    // Each integration changes what a run can SEE or SAY, and none of them announces itself:
+    // a board with no tracker linked simply never mentions that issues could arrive on their own.
+    offeredAtLaunch: false,
+    requires: [TUTORIAL_REQUIREMENTS.integrationsManage],
+    steps: [
+      {
+        id: 'intro',
+        titleKey: 'tutorial.tours.connectSystems.steps.intro.title',
+        bodyKey: 'tutorial.tours.connectSystems.steps.intro.body',
+      },
+      {
+        id: 'open',
+        target: 'nav-integrations',
+        advanceOn: 'target-click',
+        placement: 'right',
+        titleKey: 'tutorial.tours.connectSystems.steps.open.title',
+        bodyKey: 'tutorial.tours.connectSystems.steps.open.body',
+      },
+      {
+        id: 'hub',
+        target: 'integrations-hub',
+        waitForTargetMs: 8000,
+        placement: 'bottom',
+        titleKey: 'tutorial.tours.connectSystems.steps.hub.title',
+        bodyKey: 'tutorial.tours.connectSystems.steps.hub.body',
+      },
+      {
+        id: 'finish',
+        titleKey: 'tutorial.tours.connectSystems.steps.finish.title',
+        bodyKey: 'tutorial.tours.connectSystems.steps.finish.body',
+      },
+    ],
+  },
 ]
 
 /** The module that contributes the catalog; registered by `createAppRegistry`. */

package/app/utils/tutorial.spec.ts

@@ -2,6 +2,7 @@ import { describe, expect, it } from 'vitest'
 import en from '../../i18n/locales/en.json'
 import {
   computeCoachMarkLayout,
+  isLaunchOffer,
   launchActionFor,
   needsReveal,
   resolveTourCatalogue,
@@ -92,6 +93,24 @@ describe('resolveTours', () => {
   })
 })
 
+describe('isLaunchOffer', () => {
+  it('offers a tour that declares nothing, and only withholds an explicit opt-out', () => {
+    // The DEFAULT is the whole point: a consumer deployment contributes a tour with no extra
+    // field and it appears in the launch prompt beside the built-ins, exactly as documented.
+    // Only `false` withholds it, so a tour cannot fall out of the offer by omission.
+    expect(isLaunchOffer(tour('a', 10))).toBe(true)
+    expect(isLaunchOffer({ ...tour('a', 10), offeredAtLaunch: true })).toBe(true)
+    expect(isLaunchOffer({ ...tour('a', 10), offeredAtLaunch: false })).toBe(false)
+  })
+
+  it('is orthogonal to availability, so an un-offered tour still resolves as ready', () => {
+    // It thins an OFFER, never the library: the catalogue lists, counts and starts these.
+    const t = { ...withSteps('a', [step('one')]), offeredAtLaunch: false }
+    expect(resolveTours([t], gates(true)).map((x) => x.id)).toEqual(['a'])
+    expect(resolveTourCatalogue([t], gates(true))[0]?.availability).toBe('ready')
+  })
+})
+
 describe('resolveTourCatalogue', () => {
   it('keeps an unavailable tour, saying which requirements are unmet', () => {
     // The whole reason the catalogue resolves rather than filters: a tour dropped from the

package/app/utils/tutorial.ts

@@ -127,6 +127,24 @@ export interface TutorialTour {
   icon?: string
   /** Sort key in the tour list; ties break on `id` so the order is deterministic. */
   order: number
+  /**
+   * Whether the LAUNCH PROMPT offers this tour. Absent = offered, so a consumer deployment's
+   * own tour appears beside the built-ins with nothing to declare.
+   *
+   * The prompt is one question a new user is trying to answer in a glance; the catalogue is the
+   * library. That split only holds while the prompt stays short, and the catalog does not: the
+   * built-ins now cover the platform (the engine, the pipeline builder, the standards library,
+   * the integrations) alongside the delivery loop, and every platform tour is startable on a
+   * brand-new board, because all it needs is a permission. Offered unfiltered they would put
+   * six walkthroughs in front of someone whose board has neither a repository nor a task,
+   * burying the two they can act on under four they have no reason to care about yet.
+   *
+   * This thins an OFFER, never the library — the distinction {@link resolveTourCatalogue} exists
+   * to keep. An un-offered tour is listed, startable, counted in the progress line and reachable
+   * from the prompt's own "See all tutorials" footer button, so nothing here can make a
+   * walkthrough disappear; only `requires` can hold one back, and that is always reported.
+   */
+  offeredAtLaunch?: boolean
   /**
    * What this board/user must have before the tour can run, over the same reactive
    * {@link NavGates} the nav catalog uses — so a tour about a surface the caller can't reach
@@ -246,7 +264,7 @@ export function resolveTourCatalogue(
   })
 }
 
-/** The tours that can be started right now, resolved — the launch prompt's offer list. */
+/** The tours that can be started right now, resolved — what the overlay may run. */
 export function resolveTours(
   tours: readonly TutorialTour[],
   gates: NavGates | null,
@@ -256,6 +274,18 @@ export function resolveTours(
     .map((entry) => entry.tour)
 }
 
+/**
+ * Does the launch prompt offer this tour? See {@link TutorialTour.offeredAtLaunch} for why the
+ * prompt shows a subset while the catalogue shows everything.
+ *
+ * One function rather than an inline `!== false` at each site, because the DEFAULT is the whole
+ * subtlety: a tour that declares nothing is offered, so a reader spelling the check out
+ * themselves has to get the polarity of an absent field right.
+ */
+export function isLaunchOffer(tour: TutorialTour): boolean {
+  return tour.offeredAtLaunch !== false
+}
+
 /**
  * Where a tour stands for this user: the state the catalogue badges and the action label
  * derive from. Camel-cased because the values ARE the i18n leaf keys