@cat-factory/app 0.202.0 → 0.204.0

package/app/composables/useTutorialTours.ts

@@ -1,18 +1,46 @@
 import { computed } from 'vue'
 import { useReactiveSlots } from '@modular-vue/runtime'
-import { sortTours } from '~/utils/tutorial'
-import type { TutorialTour } from '~/utils/tutorial'
+import { createSharedComposables } from '@modular-vue/vue'
+import { resolveTourCatalogue } from '~/utils/tutorial'
+import type { TutorialCatalogueEntry, TutorialTour } from '~/utils/tutorial'
+import type { AppDeps } from '~/modular/registry'
 import type { AppSlots } from '~/modular/nav-contributions'
 
 /**
- * The tours the current user may take: the merged `tutorialTours` slot (first-party +
- * consumer-contributed), already gated per tour by `navSlotFilter` (each tour's `when`
- * runs over the reactive gates service, so a permission flip shows/hides tours live),
- * in deterministic catalog order. The single source both the launch prompt and the
- * coach-mark overlay resolve tours from.
+ * The registered `gates` service — the SAME reactive object `navSlotFilter` reads, resolved
+ * from the modular app's shared dependencies rather than rebuilt here, so the tutorial
+ * surfaces and the nav can never disagree about what this board offers. Reading its getters
+ * inside a `computed` tracks the underlying stores, so availability re-resolves the instant a
+ * permission flips or a task lands on the board.
+ *
+ * `useOptional` (not `useService`) covers the bare-install case the nav filter also allows: a
+ * host that registered no gates withholds nothing rather than throwing.
+ */
+const { useOptional } = createSharedComposables<AppDeps>()
+
+/**
+ * The tutorial catalog as this board sees it, resolved ONCE for every surface that reads it.
+ *
+ * Two views over one resolution, and the difference between them is the point:
+ *
+ *  - `tours` — what can be started right now. The launch prompt offers these, and the overlay
+ *    resolves a running tour from them, exactly as when this gating lived in `navSlotFilter`.
+ *  - `catalogue` — EVERY tour this deployment ships, each carrying why it is or isn't
+ *    available. The catalogue surface needs the unavailable ones: a list that quietly omits
+ *    four of six tours is indistinguishable from a deployment that ships two, and the user it
+ *    fails is the one who came looking for the walkthrough they were told about.
+ *
+ * Gating cannot live in the slot filter for that reason — a `SlotFilter` maps slots to slots,
+ * so it can only drop, never annotate. `resolveTourCatalogue` is pure and does both.
  */
 export function useTutorialTours() {
   const slots = useReactiveSlots<AppSlots>()
-  const tours = computed<TutorialTour[]>(() => sortTours(slots.value.tutorialTours ?? []))
-  return { tours }
+  const gates = useOptional('gates')
+  const catalogue = computed<TutorialCatalogueEntry[]>(() =>
+    resolveTourCatalogue(slots.value.tutorialTours ?? [], gates.value),
+  )
+  const tours = computed<TutorialTour[]>(() =>
+    catalogue.value.filter((entry) => entry.availability === 'ready').map((entry) => entry.tour),
+  )
+  return { tours, catalogue }
 }

package/app/docs/consumer-extensions.md

@@ -236,17 +236,17 @@ re-deriving the "which run is this / how did the model do" facts. **Composables*
 **components** must be named through the `#components` virtual module (see the boxed note
 below). Compose these:
 
-| Building block                | Reference it as                           | What it gives you                                                                                                                                                                                                                                                                                                                                                                                                |
-| ----------------------------- | ----------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `ResultWindowShell`           | `#components` → `PanelsResultWindowShell` | The shared modal chrome for a result window — backdrop, header (icon/title/subtitle), a `#header-extras` slot, close button, and the modal _behaviour_ (focus-trap + return, body-scroll lock, shared-stack Escape via `useModalBehavior`). Pass `stepRef` to surface the shared "restart from here" control.                                                                                                    |
-| `StepRunMeta`                 | `#components` → `PanelsStepRunMeta`       | **The shared run-details metadata block** every agent window reuses: step position, live duration, model, run id, and the LLM model-activity rollup. Drop it into your window's sidebar — never reinvent run metadata.                                                                                                                                                                                           |
-| `MarkdownProse`               | `#components` → `CommonMarkdownProse`     | Render an agent's prose output as markdown.                                                                                                                                                                                                                                                                                                                                                                      |
-| `CopyButton`                  | `#components` → `CommonCopyButton`        | The shared copy-to-clipboard affordance.                                                                                                                                                                                                                                                                                                                                                                         |
-| `InspectorSection`            | `#components` → `PanelsInspectorSection`  | The collapsible inspector-section shell (chevron header, count, hint) so a consumer panel reads like a built-in one.                                                                                                                                                                                                                                                                                             |
-| `useResultView(id)`           | auto-imported                             | The window seam contract: `{ open, blockId, instanceId, stepIndex, close }` (+ an `onOpen` loader for windows that fetch, and an `onClose` flush). Escape is owned by the shell, not here.                                                                                                                                                                                                                       |
-| `useResultViewRunMeta(id, …)` | auto-imported                             | The `StepRunMeta` prop bundle (`{ step, instanceId, position, totalSteps, runFailed, failureAt }`), resolved for BOTH ways a window opens. A window reachable off-path — from a board card or the inspector — carries no `stepIndex`, so wiring `StepRunMeta` straight off `useResultView` leaves it blank on exactly that route; this resolves the block's live run and the step your view id declares instead. |
-| `usePanelSubject<T>()`        | `@modular-vue/core`                       | Read the block injected into an inspector panel by `<PanelsOutlet>`.                                                                                                                                                                                                                                                                                                                                             |
-| `useAppOverlays()`            | auto-imported                             | Open / close your own top-level overlays: `{ open(id, subject?), close(), active }`. The store-free seam a nav `run` closure uses to open an `appOverlays`-slot component (see "Top-level overlays").                                                                                                                                                                                                            |
+| Building block                | Reference it as                           | What it gives you                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
+| ----------------------------- | ----------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `ResultWindowShell`           | `#components` → `PanelsResultWindowShell` | The shared modal chrome for a result window — backdrop, header (icon/title/subtitle), a `#header-extras` slot, close button, and the modal _behaviour_ (focus-trap + return, body-scroll lock, shared-stack Escape via `useModalBehavior`). Pass `stepRef` to surface the shared "restart from here" control. It also renders the universal per-step trailing sections (agent effort, pre-PR validation, binary outputs) off the ACTIVE step, so your window inherits them and must not re-render them itself. |
+| `StepRunMeta`                 | `#components` → `PanelsStepRunMeta`       | **The shared run-details metadata block** every agent window reuses: step position, live duration, model, run id, and the LLM model-activity rollup. Drop it into your window's sidebar — never reinvent run metadata.                                                                                                                                                                                                                                                                                         |
+| `MarkdownProse`               | `#components` → `CommonMarkdownProse`     | Render an agent's prose output as markdown.                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| `CopyButton`                  | `#components` → `CommonCopyButton`        | The shared copy-to-clipboard affordance.                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
+| `InspectorSection`            | `#components` → `PanelsInspectorSection`  | The collapsible inspector-section shell (chevron header, count, hint) so a consumer panel reads like a built-in one.                                                                                                                                                                                                                                                                                                                                                                                           |
+| `useResultView(id)`           | auto-imported                             | The window seam contract: `{ open, blockId, instanceId, stepIndex, close }` (+ an `onOpen` loader for windows that fetch, and an `onClose` flush). Escape is owned by the shell, not here.                                                                                                                                                                                                                                                                                                                     |
+| `useResultViewRunMeta(id, …)` | auto-imported                             | The `StepRunMeta` prop bundle (`{ step, instanceId, position, totalSteps, runFailed, failureAt }`), resolved for BOTH ways a window opens. A window reachable off-path — from a board card or the inspector — carries no `stepIndex`, so wiring `StepRunMeta` straight off `useResultView` leaves it blank on exactly that route; this resolves the block's live run and the step your view id declares instead.                                                                                               |
+| `usePanelSubject<T>()`        | `@modular-vue/core`                       | Read the block injected into an inspector panel by `<PanelsOutlet>`.                                                                                                                                                                                                                                                                                                                                                                                                                                           |
+| `useAppOverlays()`            | auto-imported                             | Open / close your own top-level overlays: `{ open(id, subject?), close(), active }`. The store-free seam a nav `run` closure uses to open an `appOverlays`-slot component (see "Top-level overlays").                                                                                                                                                                                                                                                                                                          |
 
 > **Reference layer components through `#components`, not bare tags.** Nuxt auto-registers a
 > layer's components under a **path-derived** name (`components/panels/ResultWindowShell.vue`
@@ -270,6 +270,19 @@ below). Compose these:
 > Hardening these building blocks into an explicitly exported, location-independent public
 > surface is slice G of the initiative.
 
+### Don't render step state the shell already owns
+
+Some state the engine records on a step is deliberately NOT a result view's job, because the
+record's scope is wider than any one kind: the agent's effort self-assessment, the pre-PR
+validation report, and — for a `binary-output` generator — the artifacts it declared it stored
+(`step.binaryOutputs`). `ResultWindowShell` resolves the active step itself and renders each as a
+collapsible trailing section, and the generic step-detail panel renders the same components for a
+step whose kind declares no window at all.
+
+So a generator kind should declare a result view for its OWN output (or none), and leave the
+artifact list alone — you get it either way, on every entry point, with no id to register. A
+window that renders it again just shows it twice.
+
 The example `AcmeSecurityReport.vue` window is a full demonstration: it imports
 `ResultWindowShell` + `StepRunMeta` + `MarkdownProse` from `#components`, composes them with
 the auto-imported `useResultView`, adds only its own bespoke body (the security findings), and

package/app/modular/agent-kinds.ts

@@ -32,5 +32,11 @@ export function customKindToArchetype(kind: CustomAgentKind): AgentArchetype {
     // projection would fork the rule the moment the default changes.
     ...(p.tier ? { tier: p.tier } : {}),
     ...(p.resultView ? { resultView: p.resultView } : {}),
+    // Not part of `presentation` on the wire — it is a fact about how the kind RUNS, projected
+    // beside `container` — so it is lifted from the entry itself. Carried onto the archetype
+    // because the pipeline builder resolves a step's meta through `agentKindMeta`, not through
+    // the snapshot, and a required step option cannot be gated on something the read model
+    // does not carry.
+    ...(kind.binaryOutput ? { binaryOutput: true } : {}),
   }
 }

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

@@ -310,6 +310,7 @@ describe('nav grouping helpers', () => {
       'infrastructure',
       'workspaceContext',
       'configuration',
+      'help',
     ])
     // The model layer is its own section, ahead of the optional integrations: the engines,
     // the per-agent model choice (beside the providers it picks from, rather than under
@@ -332,6 +333,12 @@ describe('nav grouping helpers', () => {
       'operator-dashboard',
       'reports',
     ])
+    // The tail section: what teaches the product, rather than what configures it. It is on
+    // the sidebar at all because the launch prompt is answered once and the palette was then
+    // the only route back to the walkthroughs — asking the user least likely to have found
+    // the palette to find it.
+    const help = groups.find((g) => g.group === 'help')
+    expect(help?.items.map((i) => i.id)).toEqual(['tutorial'])
   })
 
   it('groupCommands preserves the pre-slice-1 workspace-group order', () => {

package/app/modular/nav-contributions.ts

@@ -1,5 +1,4 @@
 import { defineModule } from '@modular-vue/core'
-import { resolveTours } from '~/utils/tutorial'
 import { filterExternalTools } from './external-tools'
 import type { AppSlots } from './slots'
 
@@ -47,6 +46,11 @@ export type NavSurface = 'sidebar' | 'command' | 'toolbar'
  * dropped entirely where none are registered. It is separate from `integrations` for the same
  * reason `models` is — an integration is a system cat-factory READS FROM or WRITES TO on your
  * behalf, while these are places a person GOES.
+ *
+ * `help` is the tail section: surfaces that teach the product rather than configure it. It is
+ * separate from `configuration` because nothing in it changes what a run does — and it is a
+ * SIDEBAR section rather than a palette-only entry because the people it serves are the ones
+ * least likely to know the palette exists.
  */
 export type NavSidebarGroup =
   | 'create'
@@ -57,6 +61,7 @@ export type NavSidebarGroup =
   | 'workspaceContext'
   | 'externalTools'
   | 'configuration'
+  | 'help'
 
 /** Command-palette group (its i18n label is `layout.commandBar.groups.<group>`). */
 export type NavCommandGroup =
@@ -539,21 +544,27 @@ export const NAV_CONTRIBUTIONS: readonly NavContribution[] = [
     sidebar: { group: 'configuration', order: 45 },
   },
   {
-    // Deliberately NOT `advanced`: the tours exist for exactly the users basic mode serves,
-    // and the palette entry is the way back to them after the launch prompt was declined
-    // or dismissed. Ungated: every tour gates itself via its own `when` predicate, and the
-    // prompt is worth reaching even when it can only list some tours.
+    // Deliberately NOT `advanced`: the tutorials exist for exactly the users basic mode
+    // serves. It is on the SIDEBAR as well as in the palette because the launch prompt is
+    // shown once and answered once — after that, a palette entry was the only route back to
+    // the walkthroughs, which asks the user least likely to have found the palette to find
+    // it. Ungated: every tour answers for itself (an unavailable one is listed with what
+    // would unlock it), so the catalogue is worth reaching even when little of it can run.
     id: 'tutorial',
-    labelKey: 'layout.commandBar.cmd.tutorial',
+    labelKey: 'nav.tutorials',
     icon: 'i-lucide-graduation-cap',
-    surfaces: S('command'),
+    surfaces: S('sidebar', 'command'),
     action: 'tutorial',
     testId: 'nav-tutorial',
+    sidebar: { group: 'help', order: 10 },
     command: {
       // After the pre-slice-1 tail (the workspace group pins that order): genuinely new
       // entries append rather than interleave.
       group: 'workspace',
       order: 100,
+      // No `labelKey` override: the palette shows "Tutorials" too, so an override would be a
+      // second key holding the same word in ten locales — two places to keep in step and one
+      // of them free to drift. `layout.commandBar.cmd.tutorial` was deleted with it.
       keywordsKey: 'layout.commandBar.keywords.tutorial',
     },
   },
@@ -615,7 +626,6 @@ export const navigationModule = defineModule({
 export function navSlotFilter(slots: AppSlots, deps: { gates?: NavGates }): AppSlots {
   const gates = deps.gates
   const nav = slots.nav ?? []
-  const tutorialTours = slots.tutorialTours ?? []
   const externalTools = slots.externalTools ?? []
   return {
     ...slots,
@@ -626,11 +636,12 @@ export function navSlotFilter(slots: AppSlots, deps: { gates?: NavGates }): AppS
           (i) => (i.advanced ? gates.advancedMode : true) && (i.gate ? i.gate(gates) : true),
         )
       : nav,
-    // Tutorial tours gate over the same reactive service, so a tour about a surface the
-    // caller can't reach (e.g. creating tasks without board write) never shows, and a step
-    // about a branch this board isn't on is dropped rather than skipped (see `resolveTours`).
-    // Same gates-absent pass-through as `nav`.
-    tutorialTours: gates ? resolveTours(tutorialTours, gates) : tutorialTours,
+    // `tutorialTours` is deliberately NOT filtered here, unlike every other gated slot. A
+    // `SlotFilter` can only DROP, and the tutorial catalogue's whole job is to explain what
+    // was dropped — which tour this board can't run yet, and what would unlock it. That is a
+    // richer value than a thinned list, so tour resolution lives in `resolveTourCatalogue`
+    // (pure, gates-nullable) and runs once in `useTutorialTours`, whose `tours` is the same
+    // gated set the launch prompt and the overlay always saw.
     // External tools gate on the same two axes as `nav` — they become nav items downstream
     // (`useNavContributions` projects them), so gating them anywhere else would let a tool the
     // caller can't use reach the palette while its sidebar twin was correctly hidden.
@@ -650,6 +661,7 @@ export const SIDEBAR_GROUP_ORDER: readonly NavSidebarGroup[] = [
   // configuration tail: they are destinations someone reaches mid-work, not settings.
   'externalTools',
   'configuration',
+  'help',
 ]
 
 /** Command-palette groups, in render order; each label is `layout.commandBar.groups.<group>`. */

package/app/modular/slots.ts

@@ -37,8 +37,11 @@ import type { WorkspaceMetadataFieldDefinition } from './workspace-metadata'
  *  - `tutorialTours` — the in-app tutorial catalog ({@link TutorialTour}: data-only
  *    guided tours anchored to `data-testid`s, no components). First-party tours come
  *    from `modular/tutorial-tours.ts`; a consumer contributes its own to the same slot
- *    and they appear in the launch prompt beside the built-ins, gated per tour by its
- *    `when(gates)` predicate in the same reactive `slotFilter` that gates `nav`.
+ *    and they appear in the launch prompt and the tutorial catalogue beside the built-ins.
+ *    The one gated slot `navSlotFilter` does NOT filter: a tour's `requires` is resolved by
+ *    `resolveTourCatalogue` in `useTutorialTours` instead, because the catalogue must list
+ *    the tours this board can't run yet WITH what would unlock them — an annotation a
+ *    slots-to-slots filter cannot carry.
  *  - `externalTools` — the deployment's OWN web applications, listed in their own
  *    "External tools" sidebar section ({@link ExternalToolContribution}). Each entry resolves
  *    its URL from the invocation context (user, workspace, the custom metadata below), so the

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

@@ -2,10 +2,14 @@ import { readdirSync, readFileSync } from 'node:fs'
 import { join } from 'node:path'
 import { describe, expect, it } from 'vitest'
 import en from '../../i18n/locales/en.json'
-import { TUTORIAL_TOURS, tutorialToursModule } from '~/modular/tutorial-tours'
-import { NAV_CONTRIBUTIONS, navSlotFilter } from '~/modular/nav-contributions'
+import {
+  TUTORIAL_REQUIREMENTS,
+  TUTORIAL_TOURS,
+  tutorialToursModule,
+} from '~/modular/tutorial-tours'
+import { resolveTourCatalogue, resolveTours } from '~/utils/tutorial'
 import { isSafeTargetId } from '~/components/tutorial/TutorialOverlay.logic'
-import type { AppSlots, NavGates } from '~/modular/nav-contributions'
+import type { NavGates } from '~/modular/nav-contributions'
 
 const ALL_GATES: NavGates = {
   canWriteBoard: true,
@@ -40,12 +44,6 @@ const FRESH_BOARD: NavGates = {
   boardHasFinishedRun: false,
 }
 
-const slots = (): AppSlots =>
-  ({
-    nav: [...NAV_CONTRIBUTIONS],
-    tutorialTours: [...TUTORIAL_TOURS],
-  }) as unknown as AppSlots
-
 /** Resolve a dot-path against the en catalog; undefined when any hop is missing. */
 function lookupKey(key: string): unknown {
   return key
@@ -197,73 +195,124 @@ describe('the built-in tutorial tour catalog', () => {
   })
 })
 
-describe('navSlotFilter over tutorialTours', () => {
-  it('keeps every tour for a fully-gated user', () => {
-    const filtered = navSlotFilter(slots(), { gates: ALL_GATES })
-    expect(filtered.tutorialTours.map((t) => t.id)).toEqual(TUTORIAL_TOURS.map((t) => t.id))
+describe('tour availability across the catalog', () => {
+  /** The ids a board can START right now — what the launch prompt offers. */
+  const ready = (gates: NavGates) => resolveTours(TUTORIAL_TOURS, gates).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)
+
+  it('offers every tour to a fully-gated user on a fully-populated board', () => {
+    expect(ready(ALL_GATES)).toEqual(TUTORIAL_TOURS.map((t) => t.id))
   })
 
-  it('drops the task-creating tour for a read-only viewer', () => {
+  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.
+    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',
+    ])
+  })
+
+  it('holds the task-creating tour back from a read-only viewer, and says why', () => {
     const viewer: NavGates = { ...ALL_GATES, canWriteBoard: false }
-    const filtered = navSlotFilter(slots(), { gates: viewer })
-    const ids = filtered.tutorialTours.map((t) => t.id)
-    expect(ids).toContain('board-basics')
-    expect(ids).not.toContain('first-task')
+    expect(ready(viewer)).toContain('board-basics')
+    expect(ready(viewer)).not.toContain('first-task')
+    expect(entry(viewer, 'first-task')?.unmet.map((r) => r.id)).toEqual(['board-write'])
   })
 
-  it('drops the task-creating tour on a board with no service to add a task to', () => {
+  it('holds the task-creating tour back on a board with no service to add a task to', () => {
     // Every targeted step of that tour would time out in turn and it would then claim to
     // have taught the core loop; `board-basics` is what an empty board can deliver.
     const emptyBoard: NavGates = { ...ALL_GATES, boardHasService: false }
-    const filtered = navSlotFilter(slots(), { gates: emptyBoard })
-    expect(filtered.tutorialTours.map((t) => t.id)).not.toContain('first-task')
+    expect(ready(emptyBoard)).not.toContain('first-task')
+    expect(entry(emptyBoard, 'first-task')?.unmet.map((r) => r.id)).toEqual(['service'])
   })
 
   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.
-    const filtered = navSlotFilter(slots(), { gates: FRESH_BOARD })
-    expect(filtered.tutorialTours.map((t) => t.id)).toEqual(['board-basics', 'add-service'])
+    expect(ready(FRESH_BOARD)).toEqual(['board-basics', 'add-service'])
   })
 
-  it('drops the repo tour when no source-control connection can list repositories', () => {
+  it('names the missing connection when no source control can list repositories', () => {
     const noSource: NavGates = { ...FRESH_BOARD, githubAvailable: false }
-    expect(navSlotFilter(slots(), { gates: noSource }).tutorialTours.map((t) => t.id)).toEqual([
-      'board-basics',
-    ])
+    expect(ready(noSource)).toEqual(['board-basics'])
+    expect(entry(noSource, 'add-service')?.unmet.map((r) => r.id)).toEqual(['source-control'])
   })
 
   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(navSlotFilter(slots(), { gates: withTask }).tutorialTours.map((t) => t.id)).toContain(
-      'run-task',
-    )
-    expect(
-      navSlotFilter(slots(), { gates: withTask }).tutorialTours.map((t) => t.id),
-    ).not.toContain('review-merge')
+    expect(ready(withTask)).toContain('run-task')
+    expect(ready(withTask)).not.toContain('review-merge')
+    expect(entry(withTask, 'review-merge')?.unmet.map((r) => r.id)).toEqual(['finished-run'])
 
     const finished: NavGates = { ...withTask, boardHasRun: true, boardHasFinishedRun: true }
-    expect(navSlotFilter(slots(), { gates: finished }).tutorialTours.map((t) => t.id)).toContain(
-      'review-merge',
-    )
+    expect(ready(finished)).toContain('review-merge')
+  })
+
+  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.
+    const bare: NavGates = { ...FRESH_BOARD, canWriteBoard: false, githubAvailable: false }
+    expect(entry(bare, 'add-service')?.unmet.map((r) => r.id)).toEqual([
+      'board-write',
+      'source-control',
+    ])
+  })
+
+  it('resolves every requirement copy key against the en catalog', () => {
+    // Same tier-2 i18n guard as the tour copy above: a requirement's label is looked up from
+    // data, so a renamed key would reach the user as a raw path in the "available once" list.
+    for (const requirement of Object.values(TUTORIAL_REQUIREMENTS)) {
+      expect(typeof lookupKey(requirement.labelKey), requirement.labelKey).toBe('string')
+    }
+  })
+
+  it('gives every tour a step that always applies, so none can be listed then not run', () => {
+    // The authoring rule `resolveTourCatalogue` documents. `blocked` outranks `not-applicable`,
+    // which is right — but it means a tour COULD be named in the catalogue as unlockable and
+    // then, once the reader has gone and done the thing it asked for, resolve to no applicable
+    // steps and still refuse to start. An unconditional step (every built-in has an intro and a
+    // finish card) makes `steps` non-empty under any gates, so that outcome is unreachable.
+    for (const tour of TUTORIAL_TOURS) {
+      const unconditional = tour.steps.filter((s) => !s.when).map((s) => s.id)
+      expect(unconditional, tour.id).not.toEqual([])
+    }
+  })
+
+  it('declares its requirements from the shared set', () => {
+    // A tour with an inline requirement object is not wrong, but a duplicate of a shared one
+    // is: two copies of "a service on the board" drift into two different sentences about the
+    // same gate. Pinning the built-ins to the table keeps that a deliberate act.
+    const shared = new Set(Object.values(TUTORIAL_REQUIREMENTS).map((r) => r.id))
+    for (const tour of TUTORIAL_TOURS) {
+      for (const requirement of tour.requires ?? []) {
+        expect(shared, `${tour.id}: ${requirement.id}`).toContain(requirement.id)
+      }
+    }
   })
 
   it('passes tours through untouched when no gates service is wired', () => {
-    const filtered = navSlotFilter(slots(), {})
-    expect(filtered.tutorialTours.map((t) => t.id)).toEqual(TUTORIAL_TOURS.map((t) => t.id))
+    expect(resolveTours(TUTORIAL_TOURS, null).map((t) => t.id)).toEqual(
+      TUTORIAL_TOURS.map((t) => t.id),
+    )
   })
 })
 
 describe('the parked-run tour branches', () => {
   const stepIds = (gates: NavGates, tourId: string) =>
-    navSlotFilter(slots(), { gates })
-      .tutorialTours.find((t) => t.id === tourId)
+    resolveTours(TUTORIAL_TOURS, gates)
+      .find((t) => t.id === tourId)
       ?.steps.map((s) => s.id)
 
   it('is not offered while nothing is waiting for a human', () => {
-    const ids = navSlotFilter(slots(), { gates: FRESH_BOARD }).tutorialTours.map((t) => t.id)
-    expect(ids).not.toContain('answer-park')
+    expect(resolveTours(TUTORIAL_TOURS, FRESH_BOARD).map((t) => t.id)).not.toContain('answer-park')
   })
 
   it('shows the decision branch only, for a run parked on a decision', () => {
@@ -297,7 +346,7 @@ describe('the parked-run tour branches', () => {
   it('keeps every branch when no gates service is wired', () => {
     // Same dev-open parity as `nav`: with nothing to gate against, nothing is withheld —
     // including the per-step branches, which a bare install must not silently thin out.
-    const answerPark = navSlotFilter(slots(), {}).tutorialTours.find((t) => t.id === 'answer-park')
+    const answerPark = resolveTours(TUTORIAL_TOURS, null).find((t) => t.id === 'answer-park')
     expect(answerPark?.steps.map((s) => s.id)).toEqual([
       'intro',
       'resolve',

package/app/modular/tutorial-tours.ts

@@ -1,5 +1,5 @@
 import { defineModule } from '@modular-vue/core'
-import type { TutorialTour } from '~/utils/tutorial'
+import type { TutorialRequirement, TutorialTour } from '~/utils/tutorial'
 
 /**
  * The first-party tutorial-tour catalog, contributed to the `tutorialTours` slot the same
@@ -27,11 +27,15 @@ import type { TutorialTour } from '~/utils/tutorial'
  *  - A step whose branch of the flow this board simply isn't on declares `when`, so it is
  *    DROPPED rather than skipped: a skip is reported as an abridged tour, and a parked run
  *    that has a decision and no approval gate is not an abridged anything.
+ *  - A tour's own preconditions are DECLARED ({@link TUTORIAL_REQUIREMENTS}), never an
+ *    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 gated on the state the previous one produces, so the launch prompt only ever
- * offers what this board can actually demonstrate.
+ * 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.
  */
 
 /**
@@ -43,6 +47,51 @@ import type { TutorialTour } from '~/utils/tutorial'
  */
 export const SAMPLE_REPO = 'kibertoad/cat-factory-sample-repository'
 
+/**
+ * The preconditions the built-in tours declare, each pairing the gate that decides it with
+ * the copy that NAMES it — so a tour the board can't run yet is listed with the one thing
+ * still missing instead of being silently absent from the catalogue.
+ *
+ * Shared constants rather than a literal per tour because several tours need the same fact
+ * (`service` gates two of them), and a second copy of a requirement is a second reason string
+ * to keep in step with the gate it describes.
+ */
+export const TUTORIAL_REQUIREMENTS = {
+  boardWrite: {
+    id: 'board-write',
+    labelKey: 'tutorial.requirements.boardWrite',
+    met: (gates) => gates.canWriteBoard,
+  },
+  sourceControl: {
+    id: 'source-control',
+    labelKey: 'tutorial.requirements.sourceControl',
+    met: (gates) => gates.githubAvailable,
+  },
+  service: {
+    id: 'service',
+    labelKey: 'tutorial.requirements.service',
+    met: (gates) => gates.boardHasService,
+  },
+  task: {
+    id: 'task',
+    labelKey: 'tutorial.requirements.task',
+    met: (gates) => gates.boardHasTask,
+  },
+  // One requirement over both kinds of park, mirroring the tour's single `task-resolve`
+  // anchor: the card offers ONE attention action whichever way a run is waiting, so splitting
+  // this would list two things to go and do where either one alone unlocks the tour.
+  waitingAnswer: {
+    id: 'waiting-answer',
+    labelKey: 'tutorial.requirements.waitingAnswer',
+    met: (gates) => gates.boardHasOpenDecision || gates.boardHasPendingApproval,
+  },
+  finishedRun: {
+    id: 'finished-run',
+    labelKey: 'tutorial.requirements.finishedRun',
+    met: (gates) => gates.boardHasFinishedRun,
+  },
+} as const satisfies Record<string, TutorialRequirement>
+
 export const TUTORIAL_TOURS: readonly TutorialTour[] = [
   {
     id: 'board-basics',
@@ -116,7 +165,7 @@ export const TUTORIAL_TOURS: readonly TutorialTour[] = [
     // repo is a board write against a connected source, and in basic interface mode
     // add-from-repo is the ONLY route (bootstrap is advanced), which is what makes this
     // worth a tour rather than a hint.
-    when: (gates) => gates.canWriteBoard && gates.githubAvailable,
+    requires: [TUTORIAL_REQUIREMENTS.boardWrite, TUTORIAL_REQUIREMENTS.sourceControl],
     steps: [
       {
         id: 'intro',
@@ -172,7 +221,7 @@ export const TUTORIAL_TOURS: readonly TutorialTour[] = [
     // hunting for controls and then claim to have taught the core loop. Offering it only
     // once a service exists is the honest version — and the launch prompt still lists
     // `board-basics`, which is the tour an empty board can actually deliver.
-    when: (gates) => gates.canWriteBoard && gates.boardHasService,
+    requires: [TUTORIAL_REQUIREMENTS.boardWrite, TUTORIAL_REQUIREMENTS.service],
     steps: [
       {
         id: 'intro',
@@ -236,7 +285,7 @@ export const TUTORIAL_TOURS: readonly TutorialTour[] = [
     // pipeline it will run, the start control, the live step list. `first-task` stops at the
     // card, so without this tour a user who finished the shipped walkthrough has never seen
     // the inspector. Needs a task to open, not merely a service to hold one.
-    when: (gates) => gates.canWriteBoard && gates.boardHasTask,
+    requires: [TUTORIAL_REQUIREMENTS.boardWrite, TUTORIAL_REQUIREMENTS.task],
     steps: [
       {
         id: 'intro',
@@ -306,7 +355,7 @@ export const TUTORIAL_TOURS: readonly TutorialTour[] = [
     // realise a run is asking them something has a run that never finishes and a workspace
     // in-flight slot held open. Offered only while something is actually waiting, because
     // the whole tour anchors on controls that exist only then.
-    when: (gates) => gates.boardHasOpenDecision || gates.boardHasPendingApproval,
+    requires: [TUTORIAL_REQUIREMENTS.waitingAnswer],
     steps: [
       {
         id: 'intro',
@@ -361,7 +410,7 @@ export const TUTORIAL_TOURS: readonly TutorialTour[] = [
     // The last mile: a task is only DONE when its PR actually merged, so a user who never
     // finds the result and the merge control has a board full of finished-looking work that
     // shipped nothing. Its subject is a run's output, so it needs a run that produced one.
-    when: (gates) => gates.boardHasFinishedRun,
+    requires: [TUTORIAL_REQUIREMENTS.finishedRun],
     steps: [
       {
         id: 'intro',

package/app/pages/index.vue

@@ -142,11 +142,15 @@ const AiPresetMismatchDialog = defineAsyncComponent(
   () => import('~/components/providers/AiPresetMismatchDialog.vue'),
 )
 // The in-app tutorial: the launch prompt (auto-opened once for a user who never answered
-// it) and the coach-mark overlay that runs a tour. Both mount only while their store flag
-// is set, so they cost the initial bundle nothing.
+// 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
+// mount only while their store flag is set, so they cost the initial bundle nothing.
 const TutorialPrompt = defineAsyncComponent(
   () => import('~/components/tutorial/TutorialPrompt.vue'),
 )
+const TutorialCatalogue = defineAsyncComponent(
+  () => import('~/components/tutorial/TutorialCatalogue.vue'),
+)
 const TutorialOverlay = defineAsyncComponent(
   () => import('~/components/tutorial/TutorialOverlay.vue'),
 )
@@ -512,6 +516,7 @@ watch(
       <AiProviderOnboardingModal v-if="ui.aiProviderSetupOpen" />
       <AiPresetMismatchDialog v-if="ui.aiPresetMismatchOpen" />
       <TutorialPrompt v-if="tutorial.promptOpen" />
+      <TutorialCatalogue v-if="tutorial.catalogueOpen" />
       <TutorialOverlay v-if="tutorial.touring" />
     </template>