@cat-factory/app 0.197.0 → 0.198.0

package/app/modular/nav-gates.ts

@@ -1,4 +1,5 @@
 import { computed } from 'vue'
+import { hasActionablePark } from '~/modular/nav-gates.logic'
 import type { NavGates } from '~/modular/nav-contributions'
 
 /**
@@ -26,9 +27,36 @@ export function createNavGates(): NavGates {
   const providerConnections = useProviderConnectionsStore()
   const uiMode = useUiModeStore()
   const board = useBoardStore()
+  const execution = useExecutionStore()
+  const reviews = useReviewStage()
 
   // A top-level frame IS a service (see `app/types/domain.ts`); modules are sub-frames.
   const hasService = computed(() => board.blocks.some((b) => b.level === 'frame' && !b.parentId))
+  const hasTask = computed(() => board.blocks.some((b) => b.level === 'task'))
+
+  // Every run gate below is scoped to runs on TASK blocks, because every surface they gate is
+  // reached through a task card and its inspector (the card's Resolve action, the inspector's
+  // step list and result views). A frame-level run — a blueprint pass, an initiative plan —
+  // renders none of those, so counting it would offer a tour onto controls that do not exist.
+  const taskBlockIds = computed(
+    () => new Set(board.blocks.filter((b) => b.level === 'task').map((b) => b.id)),
+  )
+  const isTaskBlock = (blockId: string) => taskBlockIds.value.has(blockId)
+
+  const hasRun = computed(() => execution.instances.some((e) => isTaskBlock(e.blockId)))
+  // A run that finished successfully. `done` only: see `NavGates.boardHasFinishedRun` for
+  // why a `failed` run is not a subject for the review/merge tour.
+  const hasFinishedRun = computed(() =>
+    execution.instances.some((e) => e.status === 'done' && isTaskBlock(e.blockId)),
+  )
+  // Not the store's raw pending counts: those answer "is anything parked", while the tour
+  // these gate anchors on the card affordance a park RENDERS. See `hasActionablePark`.
+  const hasOpenDecision = computed(() =>
+    hasActionablePark(execution.openDecisions, isTaskBlock, reviews.isBackground),
+  )
+  const hasPendingApproval = computed(() =>
+    hasActionablePark(execution.openApprovals, isTaskBlock, reviews.isBackground),
+  )
 
   const infrastructureAvailable = computed(
     () =>
@@ -72,5 +100,24 @@ export function createNavGates(): NavGates {
     get boardHasService() {
       return hasService.value
     },
+    get boardHasTask() {
+      return hasTask.value
+    },
+    get boardHasRun() {
+      return hasRun.value
+    },
+    // The two park kinds read the execution store's existing open-decision / open-approval
+    // projections rather than re-scanning `instances` here, so a tour can never disagree with
+    // the queue that sent the user looking for it — then narrowed to the parks a task card
+    // actually offers an action for (`hasActionablePark`).
+    get boardHasOpenDecision() {
+      return hasOpenDecision.value
+    },
+    get boardHasPendingApproval() {
+      return hasPendingApproval.value
+    },
+    get boardHasFinishedRun() {
+      return hasFinishedRun.value
+    },
   }
 }

package/app/modular/registry.spec.ts

@@ -14,6 +14,11 @@ const NO_GATES: NavGates = {
   isAccountAdmin: false,
   advancedMode: false,
   boardHasService: false,
+  boardHasTask: false,
+  boardHasRun: false,
+  boardHasOpenDecision: false,
+  boardHasPendingApproval: false,
+  boardHasFinishedRun: false,
 }
 
 describe('app modular registry', () => {

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

@@ -16,6 +16,26 @@ const ALL_GATES: NavGates = {
   isAccountAdmin: true,
   advancedMode: true,
   boardHasService: true,
+  boardHasTask: true,
+  boardHasRun: true,
+  boardHasOpenDecision: true,
+  boardHasPendingApproval: true,
+  boardHasFinishedRun: true,
+}
+
+/**
+ * A workspace on its very first launch: fully permitted, source control wired, and nothing
+ * on the board yet. This is the state the launch prompt auto-opens in, so it is the gate set
+ * most of the availability cases below vary from.
+ */
+const FRESH_BOARD: NavGates = {
+  ...ALL_GATES,
+  boardHasService: false,
+  boardHasTask: false,
+  boardHasRun: false,
+  boardHasOpenDecision: false,
+  boardHasPendingApproval: false,
+  boardHasFinishedRun: false,
 }
 
 const slots = (): AppSlots =>
@@ -58,6 +78,19 @@ describe('the built-in tutorial tour catalog', () => {
     }
   })
 
+  it('supplies a param for every placeholder its copy names, and no unused ones', () => {
+    // A body naming `{repo}` with no `bodyParams` renders the literal braces to the user,
+    // and a param with no placeholder is dead weight the next copy edit trips over. Both
+    // are invisible until someone runs that exact step, so they are pinned here.
+    for (const tour of TUTORIAL_TOURS) {
+      for (const s of tour.steps) {
+        const body = lookupKey(s.bodyKey)
+        const named = new Set([...String(body).matchAll(/\{(\w+)\}/g)].map((m) => m[1]))
+        expect(new Set(Object.keys(s.bodyParams ?? {})), `${tour.id}/${s.id}`).toEqual(named)
+      }
+    }
+  })
+
   it('names plain data-testid values as targets, never selectors', () => {
     for (const tour of TUTORIAL_TOURS) {
       for (const s of tour.steps) {
@@ -96,8 +129,37 @@ describe('navSlotFilter over tutorialTours', () => {
     // 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 })
-    const ids = filtered.tutorialTours.map((t) => t.id)
-    expect(ids).toEqual(['board-basics'])
+    expect(filtered.tutorialTours.map((t) => t.id)).not.toContain('first-task')
+  })
+
+  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'])
+  })
+
+  it('drops the repo tour when no source-control connection can list repositories', () => {
+    const noSource: NavGates = { ...FRESH_BOARD, githubAvailable: false }
+    expect(navSlotFilter(slots(), { gates: noSource }).tutorialTours.map((t) => t.id)).toEqual([
+      'board-basics',
+    ])
+  })
+
+  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')
+
+    const finished: NavGates = { ...withTask, boardHasRun: true, boardHasFinishedRun: true }
+    expect(navSlotFilter(slots(), { gates: finished }).tutorialTours.map((t) => t.id)).toContain(
+      'review-merge',
+    )
   })
 
   it('passes tours through untouched when no gates service is wired', () => {
@@ -105,3 +167,56 @@ describe('navSlotFilter over tutorialTours', () => {
     expect(filtered.tutorialTours.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)
+      ?.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')
+  })
+
+  it('shows the decision branch only, for a run parked on a decision', () => {
+    const decision: NavGates = { ...FRESH_BOARD, boardHasOpenDecision: true }
+    expect(stepIds(decision, 'answer-park')).toEqual(['intro', 'resolve', 'decide', 'finish'])
+  })
+
+  it('shows the approval branch only, for a run parked on an approval', () => {
+    const approval: NavGates = { ...FRESH_BOARD, boardHasPendingApproval: true }
+    expect(stepIds(approval, 'answer-park')).toEqual(['intro', 'resolve', 'approve', 'finish'])
+  })
+
+  it('follows the card`s own precedence when a board has both', () => {
+    // `TaskCard.attention` prefers a decision, so the Resolve click lands on the decision
+    // modal: an approval step here would point at a control this click never opens, and
+    // the tour would report itself abridged on a board that showed exactly the right thing.
+    const both: NavGates = {
+      ...FRESH_BOARD,
+      boardHasOpenDecision: true,
+      boardHasPendingApproval: true,
+    }
+    expect(stepIds(both, 'answer-park')).toEqual(['intro', 'resolve', 'decide', 'finish'])
+  })
+
+  it('drops the run-anatomy step until a run exists to point at', () => {
+    const noRun: NavGates = { ...FRESH_BOARD, boardHasService: true, boardHasTask: true }
+    expect(stepIds(noRun, 'run-task')).not.toContain('steps')
+    expect(stepIds({ ...noRun, boardHasRun: true }, 'run-task')).toContain('steps')
+  })
+
+  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')
+    expect(answerPark?.steps.map((s) => s.id)).toEqual([
+      'intro',
+      'resolve',
+      'decide',
+      'approve',
+      'finish',
+    ])
+  })
+})

package/app/modular/tutorial-tours.ts

@@ -21,8 +21,28 @@ import type { TutorialTour } from '~/utils/tutorial'
  *    next step anchors to. Steps whose anchor only exists after that response give it a
  *    longer `waitForTargetMs`.
  *  - Copy lives under `tutorial.tours.<tourCamelId>.steps.<stepId>` in the i18n catalogs;
- *    tours never carry display strings.
+ *    tours never carry display strings. The exception is a fixed proper noun such as
+ *    {@link SAMPLE_REPO}, which rides `bodyParams` so it is written once here rather than
+ *    translated ten times.
+ *  - 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.
+ *
+ * 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.
  */
+
+/**
+ * The practice project the tours point at: a deliberately small Hono service, kept
+ * unfinished on purpose so there is always a real task to hand an agent.
+ *
+ * Named in code rather than in `en.json` because it is a repository slug: it must not be
+ * translated, and nine other catalogs would each hold their own copy of it to drift.
+ */
+export const SAMPLE_REPO = 'kibertoad/cat-factory-sample-repository'
+
 export const TUTORIAL_TOURS: readonly TutorialTour[] = [
   {
     id: 'board-basics',
@@ -64,6 +84,19 @@ export const TUTORIAL_TOURS: readonly TutorialTour[] = [
         titleKey: 'tutorial.tours.boardBasics.steps.toolbar.title',
         bodyKey: 'tutorial.tours.boardBasics.steps.toolbar.body',
       },
+      {
+        // Basic mode is the shipped default, and it HIDES a whole half of the product
+        // (sandbox, Kaizen, bootstrap, the operator surfaces). A user who never finds the
+        // switcher never learns that half exists, so the orientation tour is the one place
+        // that has to name it — the switcher is deliberately visible in both tiers for the
+        // same reason (see `nav-contributions.ts`).
+        id: 'interfaceTier',
+        target: 'ui-mode-switcher',
+        altTargets: ['ui-mode-toggle'],
+        placement: 'right',
+        titleKey: 'tutorial.tours.boardBasics.steps.interfaceTier.title',
+        bodyKey: 'tutorial.tours.boardBasics.steps.interfaceTier.body',
+      },
       {
         id: 'finish',
         titleKey: 'tutorial.tours.boardBasics.steps.finish.title',
@@ -71,6 +104,62 @@ export const TUTORIAL_TOURS: readonly TutorialTour[] = [
       },
     ],
   },
+  {
+    id: 'add-service',
+    order: 15,
+    icon: 'i-lucide-folder-git-2',
+    titleKey: 'tutorial.tours.addService.title',
+    descriptionKey: 'tutorial.tours.addService.description',
+    // The tour that unblocks every later one: `first-task` needs a service frame to add a
+    // task to, and until one exists a new workspace is offered `board-basics` and nothing
+    // else — an orientation tour of an empty canvas ending on "you're all set". Linking a
+    // 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,
+    steps: [
+      {
+        id: 'intro',
+        titleKey: 'tutorial.tours.addService.steps.intro.title',
+        bodyKey: 'tutorial.tours.addService.steps.intro.body',
+      },
+      {
+        id: 'open',
+        target: 'nav-add-from-repo',
+        advanceOn: 'target-click',
+        placement: 'right',
+        titleKey: 'tutorial.tours.addService.steps.open.title',
+        bodyKey: 'tutorial.tours.addService.steps.open.body',
+      },
+      {
+        id: 'search',
+        target: 'add-service-repo-search',
+        // Inside the modal the previous click opens.
+        waitForTargetMs: 8000,
+        placement: 'bottom',
+        titleKey: 'tutorial.tours.addService.steps.search.title',
+        bodyKey: 'tutorial.tours.addService.steps.search.body',
+        // The sample repo is a suggestion, not an instruction: the picker lists what this
+        // workspace's installation can see, and someone practising on their own repo is
+        // doing the right thing too. The copy says as much — a step that told them to pick
+        // a repo they may not have would strand them at exactly this anchor.
+        bodyParams: { repo: SAMPLE_REPO },
+      },
+      {
+        id: 'add',
+        target: 'add-service-submit',
+        advanceOn: 'target-click',
+        placement: 'top',
+        titleKey: 'tutorial.tours.addService.steps.add.title',
+        bodyKey: 'tutorial.tours.addService.steps.add.body',
+      },
+      {
+        id: 'finish',
+        titleKey: 'tutorial.tours.addService.steps.finish.title',
+        bodyKey: 'tutorial.tours.addService.steps.finish.body',
+      },
+    ],
+  },
   {
     id: 'first-task',
     order: 20,
@@ -137,6 +226,191 @@ export const TUTORIAL_TOURS: readonly TutorialTour[] = [
       },
     ],
   },
+  {
+    id: 'run-task',
+    order: 30,
+    icon: 'i-lucide-play',
+    titleKey: 'tutorial.tours.runTask.title',
+    descriptionKey: 'tutorial.tours.runTask.description',
+    // Everything that MAKES this a delivery platform lives one click inside a task: the
+    // 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,
+    steps: [
+      {
+        id: 'intro',
+        titleKey: 'tutorial.tours.runTask.steps.intro.title',
+        bodyKey: 'tutorial.tours.runTask.steps.intro.body',
+      },
+      {
+        id: 'openTask',
+        target: 'task-card',
+        advanceOn: 'target-click',
+        placement: 'right',
+        titleKey: 'tutorial.tours.runTask.steps.openTask.title',
+        bodyKey: 'tutorial.tours.runTask.steps.openTask.body',
+      },
+      {
+        id: 'inspector',
+        target: 'inspector-panel',
+        waitForTargetMs: 8000,
+        placement: 'left',
+        titleKey: 'tutorial.tours.runTask.steps.inspector.title',
+        bodyKey: 'tutorial.tours.runTask.steps.inspector.body',
+      },
+      {
+        id: 'pipeline',
+        target: 'pipeline-picker-trigger',
+        placement: 'left',
+        titleKey: 'tutorial.tours.runTask.steps.pipeline.title',
+        bodyKey: 'tutorial.tours.runTask.steps.pipeline.body',
+      },
+      {
+        // Deliberately NOT `target-click`, unlike every other "here is the button" step in
+        // the catalog: starting a run spends the workspace's model budget for real. The
+        // tour points the control out and hands the decision back, so nobody discovers they
+        // agreed to a paid run by following a tutorial.
+        id: 'start',
+        target: 'run-start',
+        placement: 'left',
+        titleKey: 'tutorial.tours.runTask.steps.start.title',
+        bodyKey: 'tutorial.tours.runTask.steps.start.body',
+      },
+      {
+        // The anatomy of a run in flight. Dropped on a board that has never run anything —
+        // there is no step list to point at, and that is a state, not an omission.
+        id: 'steps',
+        target: 'run-step',
+        when: (gates) => gates.boardHasRun,
+        waitForTargetMs: 6000,
+        placement: 'left',
+        titleKey: 'tutorial.tours.runTask.steps.steps.title',
+        bodyKey: 'tutorial.tours.runTask.steps.steps.body',
+      },
+      {
+        id: 'finish',
+        titleKey: 'tutorial.tours.runTask.steps.finish.title',
+        bodyKey: 'tutorial.tours.runTask.steps.finish.body',
+      },
+    ],
+  },
+  {
+    id: 'answer-park',
+    order: 40,
+    icon: 'i-lucide-circle-help',
+    titleKey: 'tutorial.tours.answerPark.title',
+    descriptionKey: 'tutorial.tours.answerPark.description',
+    // The one gap with a standing cost attached: a parked run waits for a human
+    // INDEFINITELY by design (there is deliberately no park timeout), so a user who does not
+    // 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,
+    steps: [
+      {
+        id: 'intro',
+        titleKey: 'tutorial.tours.answerPark.steps.intro.title',
+        bodyKey: 'tutorial.tours.answerPark.steps.intro.body',
+      },
+      {
+        // The card's own attention action, which resolves to whichever surface this park
+        // needs — one anchor for both branches, rather than a decision route and an approval
+        // route the tour would have to choose between before the user has clicked anything.
+        id: 'resolve',
+        target: 'task-resolve',
+        advanceOn: 'target-click',
+        placement: 'right',
+        titleKey: 'tutorial.tours.answerPark.steps.resolve.title',
+        bodyKey: 'tutorial.tours.answerPark.steps.resolve.body',
+      },
+      {
+        id: 'decide',
+        target: 'decision-option',
+        when: (gates) => gates.boardHasOpenDecision,
+        waitForTargetMs: 8000,
+        placement: 'top',
+        titleKey: 'tutorial.tours.answerPark.steps.decide.title',
+        bodyKey: 'tutorial.tours.answerPark.steps.decide.body',
+      },
+      {
+        // Mirrors the card's own precedence (`TaskCard.attention` prefers a decision when a
+        // block has both), so this branch is included exactly when the click above will
+        // really land on an approval — not merely when an approval exists somewhere.
+        id: 'approve',
+        target: 'step-approve',
+        when: (gates) => gates.boardHasPendingApproval && !gates.boardHasOpenDecision,
+        waitForTargetMs: 8000,
+        placement: 'top',
+        titleKey: 'tutorial.tours.answerPark.steps.approve.title',
+        bodyKey: 'tutorial.tours.answerPark.steps.approve.body',
+      },
+      {
+        id: 'finish',
+        titleKey: 'tutorial.tours.answerPark.steps.finish.title',
+        bodyKey: 'tutorial.tours.answerPark.steps.finish.body',
+      },
+    ],
+  },
+  {
+    id: 'review-merge',
+    order: 50,
+    icon: 'i-lucide-git-merge',
+    titleKey: 'tutorial.tours.reviewMerge.title',
+    descriptionKey: 'tutorial.tours.reviewMerge.description',
+    // 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,
+    steps: [
+      {
+        id: 'intro',
+        titleKey: 'tutorial.tours.reviewMerge.steps.intro.title',
+        bodyKey: 'tutorial.tours.reviewMerge.steps.intro.body',
+      },
+      {
+        id: 'openTask',
+        target: 'task-card',
+        advanceOn: 'target-click',
+        placement: 'right',
+        titleKey: 'tutorial.tours.reviewMerge.steps.openTask.title',
+        bodyKey: 'tutorial.tours.reviewMerge.steps.openTask.body',
+      },
+      {
+        id: 'openStep',
+        target: 'run-step',
+        advanceOn: 'target-click',
+        waitForTargetMs: 8000,
+        placement: 'left',
+        titleKey: 'tutorial.tours.reviewMerge.steps.openStep.title',
+        bodyKey: 'tutorial.tours.reviewMerge.steps.openStep.body',
+      },
+      {
+        id: 'result',
+        target: 'step-detail',
+        waitForTargetMs: 8000,
+        placement: 'left',
+        titleKey: 'tutorial.tours.reviewMerge.steps.result.title',
+        bodyKey: 'tutorial.tours.reviewMerge.steps.result.body',
+      },
+      {
+        // Left to the anchor-skip rather than given a `when`: a finished run whose pipeline
+        // opened no PR genuinely has no merge control, which is what a skip MEANS. Gating it
+        // would need a "this block has an open PR" gate that nothing else wants.
+        id: 'merge',
+        target: 'inspector-merge-pr',
+        waitForTargetMs: 6000,
+        placement: 'left',
+        titleKey: 'tutorial.tours.reviewMerge.steps.merge.title',
+        bodyKey: 'tutorial.tours.reviewMerge.steps.merge.body',
+      },
+      {
+        id: 'finish',
+        titleKey: 'tutorial.tours.reviewMerge.steps.finish.title',
+        bodyKey: 'tutorial.tours.reviewMerge.steps.finish.body',
+      },
+    ],
+  },
 ]
 
 /** The module that contributes the catalog; registered by `createAppRegistry`. */

package/app/utils/tutorial.spec.ts

@@ -1,6 +1,7 @@
 import { describe, expect, it } from 'vitest'
-import { computeCoachMarkLayout, sortTours } from '~/utils/tutorial'
-import type { TutorialTour } from '~/utils/tutorial'
+import { computeCoachMarkLayout, resolveTours, sortTours } from '~/utils/tutorial'
+import type { TutorialStep, TutorialTour } from '~/utils/tutorial'
+import type { NavGates } from '~/modular/nav-contributions'
 
 const tour = (id: string, order: number): TutorialTour => ({
   id,
@@ -19,6 +20,52 @@ describe('sortTours', () => {
   })
 })
 
+/**
+ * Only the fields the predicates below read; the gate object is otherwise irrelevant to
+ * `resolveTours`, which never looks at it itself.
+ */
+const gates = (advanced: boolean) => ({ advancedMode: advanced }) as NavGates
+
+const step = (id: string, when?: TutorialStep['when']): TutorialStep => ({
+  id,
+  titleKey: `t.${id}`,
+  bodyKey: `b.${id}`,
+  when,
+})
+
+const withSteps = (id: string, steps: TutorialStep[], when?: TutorialTour['when']): TutorialTour =>
+  ({ ...tour(id, 10), steps, when }) as TutorialTour
+
+describe('resolveTours', () => {
+  it('drops a tour its own `when` rejects', () => {
+    const tours = [
+      withSteps('a', [step('one')], (g) => g.advancedMode),
+      withSteps('b', [step('one')]),
+    ]
+    expect(resolveTours(tours, gates(false)).map((t) => t.id)).toEqual(['b'])
+  })
+
+  it('drops the steps their own `when` rejects, keeping the tour', () => {
+    const t = withSteps('a', [step('always'), step('advancedOnly', (g) => g.advancedMode)])
+    const [resolved] = resolveTours([t], gates(false))
+    expect(resolved?.steps.map((s) => s.id)).toEqual(['always'])
+  })
+
+  it('drops a tour left with no steps at all', () => {
+    // Otherwise the launch prompt offers a tour that ends the instant it starts: the overlay
+    // has no step to render, so Start looks like a dead button.
+    const t = withSteps('a', [step('advancedOnly', (g) => g.advancedMode)])
+    expect(resolveTours([t], gates(false))).toEqual([])
+  })
+
+  it('returns the original tour object when nothing was dropped', () => {
+    // Identity matters: the prompt lists tours by reference, so minting a new object on
+    // every gate read would re-render the list on flips that changed nothing about it.
+    const t = withSteps('a', [step('one')])
+    expect(resolveTours([t], gates(true))[0]).toBe(t)
+  })
+})
+
 const viewport = { width: 1000, height: 800 }
 const tooltip = { width: 300, height: 150 }
 

package/app/utils/tutorial.ts

@@ -52,6 +52,19 @@ export interface TutorialStep {
   altTargets?: readonly string[]
   titleKey: string
   bodyKey: string
+  /**
+   * Interpolation values for {@link bodyKey}'s `{named}` placeholders.
+   *
+   * The reason this exists rather than the value living in the catalogs: a step that names
+   * something FIXED and untranslatable — the sample repository a tour tells you to search
+   * for — would otherwise be spelled out in `en.json` and copied into nine other locales,
+   * where it reads as prose to translate and drifts the moment the value changes. Declared
+   * here it is written once, in code, beside the tour that needs it.
+   *
+   * Prose still belongs in the catalog: this is for proper nouns and code-shaped literals,
+   * the same split `frontend/app/README.md` states for inline placeholders in components.
+   */
+  bodyParams?: Record<string, string | number>
   placement?: TutorialPlacement
   /** Defaults to `'next'`. */
   advanceOn?: TutorialAdvance
@@ -64,6 +77,22 @@ export interface TutorialStep {
    * longer wait.
    */
   waitForTargetMs?: number
+  /**
+   * Applicability gate over the same reactive {@link NavGates} the tour's own `when` reads.
+   * A step this rejects is DROPPED from the tour before it runs; absent = always included.
+   *
+   * Deliberately distinct from the anchor skip above, because the two are different facts
+   * and only one of them is a defect in the tour. A skip means "this step's control should
+   * be here and isn't", which is what the final card reports as an abridged walkthrough. A
+   * `when` says "this branch of the flow is not what this board is doing" — a run parked on
+   * a decision has no approval gate to point at, and vice versa. Rendering the second as
+   * the first would tell a user who saw exactly the right walkthrough that they missed
+   * half of it, every single time.
+   *
+   * Use it only for a step whose ABSENCE is expected on a legitimate board; an anchor that
+   * merely might be slow keeps the wait budget instead.
+   */
+  when?: (gates: NavGates) => boolean
 }
 
 export interface TutorialTour {
@@ -94,6 +123,31 @@ export function sortTours(tours: readonly TutorialTour[]): TutorialTour[] {
   return [...tours].sort((a, b) => a.order - b.order || a.id.localeCompare(b.id))
 }
 
+/**
+ * Resolve every tour against the gates: drop the tours whose own `when` rejects them, drop
+ * the steps whose `when` rejects them, and then drop a tour left with no steps at all.
+ *
+ * That last rule is what makes per-step gating safe to reach for. A tour whose every step
+ * is branch-specific (the parked-run tour: some boards have a decision waiting, some an
+ * approval) would otherwise survive its own `when` and open on an empty cursor — which the
+ * overlay ends immediately, so the user presses Start and nothing happens.
+ *
+ * Pure and total, so `navSlotFilter` (which runs inside a reactive computed, once per gate
+ * flip) stays a straight fold and the rules above are unit-testable without a Vue runtime.
+ */
+export function resolveTours(tours: readonly TutorialTour[], gates: NavGates): TutorialTour[] {
+  const out: TutorialTour[] = []
+  for (const tour of tours) {
+    if (tour.when && !tour.when(gates)) continue
+    const steps = tour.steps.filter((s) => (s.when ? s.when(gates) : true))
+    if (steps.length === 0) continue
+    // Reuse the original object when nothing was dropped: the prompt keys its list on the
+    // tour, and a fresh object per gate read would re-render it on every unrelated flip.
+    out.push(steps.length === tour.steps.length ? tour : { ...tour, steps })
+  }
+  return out
+}
+
 /** A DOMRect-shaped box, structurally typed so the geometry below is unit-testable. */
 export interface TutorialRect {
   top: number