@cat-factory/app 0.201.1 → 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

@@ -1,9 +1,15 @@
+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,
@@ -38,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
@@ -51,6 +51,72 @@ function lookupKey(key: string): unknown {
     .reduce<unknown>((node, part) => (node as Record<string, unknown> | undefined)?.[part], en)
 }
 
+/**
+ * The layer's srcDir. Anchored on the package directory rather than on `import.meta.url`,
+ * which under the happy-dom test environment is not a `file:` URL at all.
+ */
+const SRC_DIR = join(process.cwd(), 'app')
+
+/**
+ * The two ways this layer names a test id, both of which a tour may legitimately anchor on.
+ *
+ *  - written straight onto an element, in either quoting style, including the bound form
+ *    (`:data-testid="'foo'"`);
+ *  - declared as a `testId` field on a DATA contribution — the nav catalog's items carry one
+ *    and `SideBar.vue` renders it as `:data-testid="item.testId"`, which is how the whole
+ *    `nav-*` family (`nav-add-from-repo` among them) reaches the DOM.
+ *
+ * A template literal (`` `tutorial-start-${id}` ``) matches neither, which is correct: that is
+ * not an id, it is a family of them, and no built-in step anchors on one.
+ */
+const ID_PATTERNS = [
+  /data-testid\s*=\s*(?:"([^"]*)"|'([^']*)')/g,
+  /\btestId\s*:\s*(?:'([^']*)'|"([^"]*)")/g,
+]
+
+/**
+ * Every `.vue`/`.ts` file the layer SHIPS. Test sources are excluded in both spellings: an id
+ * that exists only in a spec or a fixture is not rendered by anything, so counting one would
+ * let the guard pass on a tour anchored to a control that no longer exists.
+ */
+function walk(dir: string): string[] {
+  return readdirSync(dir, { withFileTypes: true }).flatMap((entry) => {
+    const path = join(dir, entry.name)
+    if (entry.isDirectory()) return walk(path)
+    return /\.(vue|ts)$/.test(entry.name) && !/\.(spec|test)\.ts$/.test(entry.name) ? [path] : []
+  })
+}
+
+/** Every anchor the built-in catalog declares, labelled with the step that declares it. */
+function declaredAnchors(): { label: string; id: string }[] {
+  const out: { label: string; id: string }[] = []
+  for (const tour of TUTORIAL_TOURS) {
+    for (const s of tour.steps) {
+      for (const id of [s.target, ...(s.altTargets ?? [])]) {
+        if (id !== undefined) out.push({ label: `${tour.id}/${s.id}: ${id}`, id })
+      }
+    }
+  }
+  return out
+}
+
+/** Every static test id this layer actually renders. */
+function renderedTestIds(): Set<string> {
+  const ids = new Set<string>()
+  for (const file of walk(SRC_DIR)) {
+    // The catalog itself declares the ids under test; counting it would make this vacuous.
+    if (file.endsWith(join('modular', 'tutorial-tours.ts'))) continue
+    const source = readFileSync(file, 'utf8')
+    for (const pattern of ID_PATTERNS) {
+      for (const match of source.matchAll(pattern)) {
+        const raw = (match[1] ?? match[2] ?? '').trim().replace(/^['"]|['"]$/g, '')
+        if (isSafeTargetId(raw)) ids.add(raw)
+      }
+    }
+  }
+  return ids
+}
+
 describe('the built-in tutorial tour catalog', () => {
   it('has unique tour ids and unique step ids within each tour', () => {
     const tourIds = TUTORIAL_TOURS.map((t) => t.id)
@@ -92,91 +158,161 @@ describe('the built-in tutorial tour catalog', () => {
   })
 
   it('names plain data-testid values as targets, never selectors', () => {
-    for (const tour of TUTORIAL_TOURS) {
-      for (const s of tour.steps) {
-        for (const target of [s.target, ...(s.altTargets ?? [])]) {
-          if (target === undefined) continue
-          // Asserted through the runtime's OWN guard, not a copy of its regex: the overlay
-          // drops an id this rejects, so a built-in tour that tripped it would silently
-          // lose the step rather than fail here.
-          expect(isSafeTargetId(target), `${tour.id}/${s.id}: ${target}`).toBe(true)
-        }
-      }
+    for (const anchor of declaredAnchors()) {
+      // Asserted through the runtime's OWN guard, not a copy of its regex: the overlay
+      // drops an id this rejects, so a built-in tour that tripped it would silently
+      // lose the step rather than fail here.
+      expect(isSafeTargetId(anchor.id), anchor.label).toBe(true)
     }
   })
 
+  it('anchors every step on a data-testid this layer actually renders', () => {
+    // The drift guard. A tour's anchors are the ONE thing about it that nothing else in the
+    // build checks: a renamed `data-testid` passes typecheck, lint and the whole e2e suite,
+    // and five of the ids below (`nav-add-from-repo`, `add-service-repo-search`,
+    // `add-service-submit`, `pipeline-picker-trigger`, `inspector-merge-pr`) have no other
+    // consumer at all — the tour is the only thing that names them.
+    //
+    // The failure it prevents is worse than a dead step. None of those steps carries a `when`,
+    // so `unexpectedlySkippedSteps` counts the miss and EVERY user who takes that tour lands on
+    // a permanent "you missed N steps" notice: the tour would go on making a false claim about
+    // itself, in production, with nothing red anywhere.
+    //
+    // Scoped to the built-in catalog on purpose — a consumer deployment's tours anchor on
+    // controls that live in ITS layer, which this repo cannot see and must not fail over.
+    const rendered = renderedTestIds()
+    // Guard the guard: a scan that silently matched nothing would pass every assertion below.
+    expect(rendered.size).toBeGreaterThan(100)
+
+    const missing = declaredAnchors()
+      .filter((anchor) => !rendered.has(anchor.id))
+      .map((anchor) => anchor.label)
+    expect(missing).toEqual([])
+  })
+
   it('is contributed to the tutorialTours slot by the module', () => {
     expect(tutorialToursModule.slots?.tutorialTours).toEqual([...TUTORIAL_TOURS])
   })
 })
 
-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', () => {
@@ -210,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',