@cat-factory/app 0.201.1 → 0.204.0

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>
 

package/app/stores/pipelines/draftBinaryOutput.spec.ts

@@ -0,0 +1,70 @@
+import { describe, expect, it } from 'vitest'
+import { usePipelinesStore } from '~/stores/pipelines'
+
+/**
+ * The pipeline-builder draft's binary-output selection (`stepOptions.binaryOutput`), the store
+ * half of the picker (docs/initiatives/binary-output-foundational-storage.md). Same contract as
+ * the skill and variant helpers beside it — merge into the options bag, normalize an emptied bag
+ * back to null — plus the one rule specific to this field: an empty `contextServiceIds` is
+ * DROPPED rather than persisted, because `[]` and absence are different claims to the agent.
+ */
+describe('pipelines store — per-step binary-output selection', () => {
+  it('sets, reads and clears the selection', () => {
+    const pipelines = usePipelinesStore()
+    pipelines.addToDraft('coder')
+    expect(pipelines.draftBinaryOutput(0)).toBeUndefined()
+
+    pipelines.setDraftBinaryOutput(0, { storageServiceId: 'file-storage' })
+    expect(pipelines.draftBinaryOutput(0)).toEqual({ storageServiceId: 'file-storage' })
+    expect(pipelines.draftStepOptions[0]).toEqual({
+      binaryOutput: { storageServiceId: 'file-storage' },
+    })
+
+    // Clearing drops the field and, with the bag now empty, normalizes the entry back to null —
+    // so a step that never used it persists exactly the shape it always did.
+    pipelines.setDraftBinaryOutput(0, undefined)
+    expect(pipelines.draftBinaryOutput(0)).toBeUndefined()
+    expect(pipelines.draftStepOptions[0]).toBeNull()
+  })
+
+  // `[]` reads as "context was considered and rejected", which the brief would then repeat to
+  // the agent; absence reads as "no scope service was selected". Only one of those is true.
+  it('drops an emptied context list rather than persisting an empty array', () => {
+    const pipelines = usePipelinesStore()
+    pipelines.addToDraft('coder')
+
+    pipelines.setDraftBinaryOutput(0, {
+      storageServiceId: 'file-storage',
+      contextServiceIds: ['asset-management'],
+    })
+    expect(pipelines.draftBinaryOutput(0)?.contextServiceIds).toEqual(['asset-management'])
+
+    pipelines.setDraftBinaryOutput(0, { storageServiceId: 'file-storage', contextServiceIds: [] })
+    expect(pipelines.draftBinaryOutput(0)).toEqual({ storageServiceId: 'file-storage' })
+  })
+
+  // A blank storage id is not a selection: the backend refuses the step either way, so the
+  // draft must not carry a half-filled shape that saves and then fails.
+  it('treats a blank storage id as no selection at all', () => {
+    const pipelines = usePipelinesStore()
+    pipelines.addToDraft('coder')
+    pipelines.setDraftBinaryOutput(0, { storageServiceId: '', contextServiceIds: ['inventory'] })
+    expect(pipelines.draftBinaryOutput(0)).toBeUndefined()
+    expect(pipelines.draftStepOptions[0]).toBeNull()
+  })
+
+  it('merges into the options bag rather than clobbering other per-step options', () => {
+    const pipelines = usePipelinesStore()
+    pipelines.addToDraft('coder')
+    pipelines.draftStepOptions[0] = { agentVariantId: 'acme:fast' }
+
+    pipelines.setDraftBinaryOutput(0, { storageServiceId: 'file-storage' })
+    expect(pipelines.draftStepOptions[0]).toEqual({
+      agentVariantId: 'acme:fast',
+      binaryOutput: { storageServiceId: 'file-storage' },
+    })
+
+    pipelines.setDraftBinaryOutput(0, undefined)
+    expect(pipelines.draftStepOptions[0]).toEqual({ agentVariantId: 'acme:fast' })
+  })
+})

package/app/stores/pipelines/draftStepConfig.ts

@@ -1,4 +1,4 @@
-import type { StepOptions } from '@cat-factory/contracts'
+import type { BinaryOutputConfig, StepOptions } from '@cat-factory/contracts'
 import type { ConsensusStepConfig } from '~/types/consensus'
 import { defaultConsensusConfig, type PipelinesContext } from './context'
 
@@ -6,7 +6,8 @@ import { defaultConsensusConfig, type PipelinesContext } from './context'
  * The pipeline-builder draft's PER-STEP CONFIG toggles: consensus (inline panel and the workspace
  * consensus-GROUP tier set), the human approval gate, the estimate gate on a companion step, the
  * follow-up and test-QC companions, the per-step enable flag, and the `StepOptions` bag
- * (requirements auto-recommendation, the picked skill, the picked agent-kind variant).
+ * (requirements auto-recommendation, the picked skill, the picked agent-kind variant, the
+ * per-step output-token ceiling, the binary-output storage/context selection).
  *
  * Split out of `./draftActions`, which owns the draft's STRUCTURE (insert / remove / reorder /
  * units). Every function here reads and writes one of the parallel per-step arrays at an index and
@@ -160,6 +161,39 @@ export function createPipelineStepConfigActions(ctx: PipelinesContext) {
     draftStepOptions.value[index] = Object.keys(next).length ? next : null
   }
 
+  /**
+   * The binary-output SELECTION on the draft step at `index` (its `stepOptions.binaryOutput`) —
+   * the foundational storage service a generator kind's artifacts are stored through, plus any
+   * services consulted for the generation's scope. Undefined on every step of every stock
+   * pipeline; required on a step whose kind carries the `binary-output` trait.
+   */
+  function draftBinaryOutput(index: number): BinaryOutputConfig | undefined {
+    return draftStepOptions.value[index]?.binaryOutput
+  }
+
+  /**
+   * Set (or clear) the binary-output selection on the draft step at `index`. Merges into the
+   * step's `StepOptions` bag rather than clobbering it; clearing drops the field and, if the
+   * bag empties, the whole entry — exactly like the other options here, so a step that never
+   * used it persists the shape it always did.
+   *
+   * An EMPTY `contextServiceIds` is dropped rather than stored, for the reason the consensus
+   * tier set drops its own empty array: the field's absence means "no scope service was
+   * selected", while `[]` reads as "context was considered and rejected" — a different claim,
+   * and one the brief renderer would repeat to the agent.
+   */
+  function setDraftBinaryOutput(index: number, config: BinaryOutputConfig | undefined) {
+    const next: StepOptions = { ...draftStepOptions.value[index] }
+    if (config?.storageServiceId) {
+      const { storageServiceId, contextServiceIds } = config
+      next.binaryOutput = {
+        storageServiceId,
+        ...(contextServiceIds?.length ? { contextServiceIds } : {}),
+      }
+    } else delete next.binaryOutput
+    draftStepOptions.value[index] = Object.keys(next).length ? next : null
+  }
+
   /**
    * The output-token ceiling pinned on the draft step at `index`, or undefined when the step
    * inherits (the workspace's per-kind setting, else the deployment default).
@@ -197,6 +231,8 @@ export function createPipelineStepConfigActions(ctx: PipelinesContext) {
     setDraftSkillId,
     draftAgentVariantId,
     setDraftAgentVariantId,
+    draftBinaryOutput,
+    setDraftBinaryOutput,
     draftMaxOutputTokens,
     setDraftMaxOutputTokens,
   }

package/app/stores/tutorial.spec.ts

@@ -64,6 +64,81 @@ describe('useTutorialStore launch prompt', () => {
   })
 })
 
+describe('useTutorialStore catalogue', () => {
+  it('opens over the launch prompt without answering it', () => {
+    // Browsing the full list is not "no thanks" — it is the opposite — so the offer must
+    // return next launch if the user browses and starts nothing. And the two are modals:
+    // leaving the prompt open would stack them.
+    const tutorial = useTutorialStore()
+    tutorial.maybeOfferOnLaunch()
+    tutorial.openCatalogue()
+    expect(tutorial.catalogueOpen).toBe(true)
+    expect(tutorial.promptOpen).toBe(false)
+    expect(tutorial.decision).toBeNull()
+  })
+
+  it('closes when a tour starts or resumes from it', () => {
+    const tutorial = useTutorialStore()
+    tutorial.openCatalogue()
+    tutorial.startTour('board-basics')
+    expect(tutorial.catalogueOpen).toBe(false)
+
+    tutorial.setStepIndex(2)
+    tutorial.stopTour()
+    tutorial.openCatalogue()
+    tutorial.resumeTour('board-basics')
+    expect(tutorial.catalogueOpen).toBe(false)
+  })
+
+  it('reports its own window as open, so the coach marks stand down', () => {
+    // The overlay renders at z-[70] to sit ABOVE the app's modals, since a step legitimately
+    // points into one. The catalogue is openable mid-tour (that is what the `continue` action
+    // is for), and there the same z-index would float a ring and a tooltip over the window the
+    // user just opened. The tour itself is untouched — only the marks go.
+    const tutorial = useTutorialStore()
+    tutorial.startTour('board-basics')
+    expect(tutorial.ownWindowOpen).toBe(false)
+
+    tutorial.openCatalogue()
+    expect(tutorial.ownWindowOpen).toBe(true)
+    expect(tutorial.activeTourId).toBe('board-basics')
+
+    tutorial.closeCatalogue()
+    expect(tutorial.ownWindowOpen).toBe(false)
+
+    tutorial.openPrompt()
+    expect(tutorial.ownWindowOpen).toBe(true)
+  })
+
+  it('resets every record of progress, including the answered offer', () => {
+    // What someone handing the app to a colleague is asking for: the first-launch experience
+    // back. Clearing only the completion list would leave the offer answered, so the prompt
+    // they are trying to demo would never appear.
+    const tutorial = useTutorialStore()
+    tutorial.startTour('board-basics')
+    tutorial.completeTour()
+    tutorial.startTour('run-task')
+    tutorial.setStepIndex(2)
+    tutorial.stopTour()
+
+    tutorial.resetProgress()
+    expect(tutorial.completedTourIds).toEqual([])
+    expect(tutorial.interruptedAt('run-task')).toBeNull()
+    expect(tutorial.decision).toBeNull()
+  })
+
+  it('leaves a running tour alone when progress is reset', () => {
+    // A click about history must not end the walkthrough the user is in the middle of —
+    // which would also leave it unrecorded, since nothing marks a stopped tour complete.
+    const tutorial = useTutorialStore()
+    tutorial.startTour('board-basics')
+    tutorial.setStepIndex(2)
+    tutorial.resetProgress()
+    expect(tutorial.activeTourId).toBe('board-basics')
+    expect(tutorial.stepIndex).toBe(2)
+  })
+})
+
 describe('useTutorialStore tours', () => {
   it('starting a tour records acceptance, closes the prompt, and resets the cursor', () => {
     const tutorial = useTutorialStore()
@@ -133,3 +208,95 @@ describe('useTutorialStore tours', () => {
     expect(tutorial.isCompleted('made-up')).toBe(false)
   })
 })
+
+describe('useTutorialStore resuming a broken-off tour', () => {
+  it('offers to resume a tour abandoned part-way', () => {
+    // Esc and Skip are both cheap to hit — one by accident, one to get the overlay out of the
+    // way for a moment — and before this the position they discarded was the whole walkthrough.
+    const tutorial = useTutorialStore()
+    tutorial.startTour('board-basics')
+    tutorial.setStepIndex(3)
+    tutorial.stopTour()
+    expect(tutorial.interruptedAt('board-basics')).toBe(3)
+
+    tutorial.resumeTour('board-basics')
+    expect(tutorial.activeTourId).toBe('board-basics')
+    expect(tutorial.stepIndex).toBe(3)
+    // Consumed: the tour is running again, so there is no longer a position to go back to.
+    expect(tutorial.interruptedAt('board-basics')).toBeNull()
+  })
+
+  it('offers nothing for a tour abandoned on its very first step', () => {
+    // Resuming and starting are the same thing there, so a Resume label would be noise.
+    const tutorial = useTutorialStore()
+    tutorial.startTour('board-basics')
+    tutorial.stopTour()
+    expect(tutorial.interruptedAt('board-basics')).toBeNull()
+  })
+
+  it('keeps the resume point scoped to the tour it belongs to', () => {
+    const tutorial = useTutorialStore()
+    tutorial.startTour('run-task')
+    tutorial.setStepIndex(2)
+    tutorial.stopTour()
+    expect(tutorial.interruptedAt('first-task')).toBeNull()
+    // Resuming a DIFFERENT tour degrades to a plain start rather than resuming the wrong one.
+    tutorial.resumeTour('first-task')
+    expect(tutorial.activeTourId).toBe('first-task')
+    expect(tutorial.stepIndex).toBe(0)
+  })
+
+  it('discards the resume point when the same tour is started from the top', () => {
+    const tutorial = useTutorialStore()
+    tutorial.startTour('board-basics')
+    tutorial.setStepIndex(3)
+    tutorial.stopTour()
+    tutorial.startTour('board-basics')
+    expect(tutorial.stepIndex).toBe(0)
+    expect(tutorial.interruptedAt('board-basics')).toBeNull()
+  })
+
+  it('keeps another tour’s resume point when a different tour is started from the top', () => {
+    // Starting a tour discards ITS own stale position, not somebody else's. Glancing at
+    // another tour and pressing Esc at step 0 must not cost the position you were coming
+    // back to — that one loses the single slot only when this tour is broken off past step 0.
+    const tutorial = useTutorialStore()
+    tutorial.startTour('board-basics')
+    tutorial.setStepIndex(3)
+    tutorial.stopTour()
+
+    tutorial.startTour('run-task')
+    tutorial.stopTour()
+    expect(tutorial.interruptedAt('board-basics')).toBe(3)
+
+    // ...and it does lose it the moment the other tour is broken off past its first step.
+    tutorial.startTour('run-task')
+    tutorial.setStepIndex(1)
+    tutorial.stopTour()
+    expect(tutorial.interruptedAt('board-basics')).toBeNull()
+    expect(tutorial.interruptedAt('run-task')).toBe(1)
+  })
+
+  it('leaves no resume point behind a completed tour', () => {
+    // It would sit beside that tour's own Completed badge, offering to resume what just finished.
+    const tutorial = useTutorialStore()
+    tutorial.startTour('board-basics')
+    tutorial.setStepIndex(3)
+    tutorial.stopTour()
+    tutorial.resumeTour('board-basics')
+    tutorial.setStepIndex(4)
+    tutorial.completeTour()
+    expect(tutorial.interruptedAt('board-basics')).toBeNull()
+    expect(tutorial.isCompleted('board-basics')).toBe(true)
+  })
+
+  it('leaves no resume point when the runtime bails out on an unusable position', () => {
+    // The overlay could not resolve the tour at all; handing that position back would put the
+    // user straight into the same dead overlay.
+    const tutorial = useTutorialStore()
+    tutorial.startTour('gone-away')
+    tutorial.setStepIndex(2)
+    tutorial.stopTour({ resumable: false })
+    expect(tutorial.interruptedAt('gone-away')).toBeNull()
+  })
+})