@cat-factory/app 0.206.0 → 0.208.0

package/app/modular/tutorial-tours.ts

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

package/app/utils/binaryOutput.spec.ts

@@ -311,6 +311,66 @@ describe('the generative half of the read model', () => {
   })
 })
 
+// The one judgement this surface can make that admission cannot: admission checked what the
+// selected integrations CAN emit, this checks what the run actually came back with.
+describe('the delivered-format check', () => {
+  const required = (mediaTypes: string[], stored: { location: string; contentType?: string }[]) =>
+    binaryOutputView(
+      step({
+        stepOptions: { binaryOutput: { storageServiceId: 'files', mediaTypes } },
+        binaryOutputs: report({
+          stored: stored.map((entry) => ({ service: 'files', ...entry })),
+        }),
+      }),
+    )
+
+  it('names a required format no declared artifact reports', () => {
+    const view = required(
+      ['model/gltf-binary', 'model/fbx'],
+      [{ location: 'a.glb', contentType: 'model/gltf-binary' }],
+    )
+    expect(view?.undeliveredMediaTypes).toEqual(['model/fbx'])
+    expect(binaryOutputHasWarnings(view!)).toBe(true)
+  })
+
+  it('reduces the agent’s own spelling before comparing, and only then', () => {
+    // The requirement came through `mediaTypeSchema`; the artifact's content type is the model's
+    // prose. Comparing them raw reports a format as undelivered while the file sits where it was
+    // asked for.
+    expect(
+      required(['model/gltf-binary'], [{ location: 'a.glb', contentType: 'Model/GLTF-Binary' }])
+        ?.undeliveredMediaTypes,
+    ).toEqual([])
+  })
+
+  it('does not accept a near neighbour of the required format', () => {
+    // The entire point of requiring a format rather than a content type: both of these are 3D.
+    expect(
+      required(['model/gltf-binary'], [{ location: 'a.fbx', contentType: 'model/fbx' }])
+        ?.undeliveredMediaTypes,
+    ).toEqual(['model/gltf-binary'])
+  })
+
+  it('counts an artifact that reports no content type as covering nothing', () => {
+    expect(required(['model/gltf-binary'], [{ location: 'a.glb' }])?.undeliveredMediaTypes).toEqual(
+      ['model/gltf-binary'],
+    )
+  })
+
+  it('stays silent when there are no artifacts, because the state line already said so', () => {
+    // "It did not deliver a GLB" on top of "it declared nothing" is one fact stated twice as if
+    // it were two, and the second one adds nothing a reader can act on.
+    const view = binaryOutputView(
+      step({
+        stepOptions: { binaryOutput: { storageServiceId: 'files', mediaTypes: ['model/obj'] } },
+        binaryOutputs: report({ undeclared: true }),
+      }),
+    )
+    expect(view?.mediaTypes).toEqual(['model/obj'])
+    expect(view?.undeliveredMediaTypes).toEqual([])
+  })
+})
+
 describe('binaryOutputPickIssues, generative half', () => {
   const catalog = [{ id: 'files', capabilities: ['asset-storage'] }]
   const generators = [
@@ -368,6 +428,51 @@ describe('binaryOutputPickIssues, generative half', () => {
     expect(pick.issues).toEqual([])
   })
 
+  // The FORMAT half, mirroring kernel's `binaryFormatCoverage` — and its three outcomes, which
+  // are what a second copy of the rule most easily loses.
+  const meshy = {
+    id: 'meshy',
+    modalities: ['3d-model' as const],
+    mediaTypes: ['model/gltf-binary'],
+  }
+
+  it('mirrors the refusal for a format no DECLARING integration emits', () => {
+    const pick = binaryOutputPickIssues(
+      { storageServiceId: 'files', generatorIds: ['meshy'], mediaTypes: ['model/fbx'] },
+      catalog,
+      true,
+      [meshy],
+    )
+    expect(pick.issues).toContain('media_type_uncovered')
+    expect(pick.uncoveredMediaTypes).toEqual(['model/fbx'])
+    expect(pick.unverifiableMediaTypes).toEqual([])
+  })
+
+  it('keeps an UNCHECKABLE format apart from a refused one, because the step still starts', () => {
+    // `retro` declares no formats — "only my modality is known". Flagging this as a refusal would
+    // send someone editing a selection the backend admits; saying nothing would present an
+    // unchecked requirement as a checked one.
+    const pick = binaryOutputPickIssues(
+      { storageServiceId: 'files', generatorIds: ['retro'], mediaTypes: ['image/webp'] },
+      catalog,
+      true,
+      generators,
+    )
+    expect(pick.issues).toContain('media_type_unverifiable')
+    expect(pick.issues).not.toContain('media_type_uncovered')
+    expect(pick.unverifiableMediaTypes).toEqual(['image/webp'])
+  })
+
+  it('accepts a format the selection covers, however many other formats it emits', () => {
+    const pick = binaryOutputPickIssues(
+      { storageServiceId: 'files', generatorIds: ['meshy'], mediaTypes: ['model/gltf-binary'] },
+      catalog,
+      true,
+      [meshy],
+    )
+    expect(pick.issues).toEqual([])
+  })
+
   it('reports an UNREADABLE set as an outage and makes no claim about the selection', () => {
     // The picker's half of the mothership-mode disposition. A failed read arrives as the same
     // empty list an unregistering deployment produces, so judging the selection against it would

package/app/utils/binaryOutput.ts

@@ -1,4 +1,4 @@
-import { ASSET_STORAGE_CAPABILITY } from '@cat-factory/contracts'
+import { ASSET_STORAGE_CAPABILITY, normalizeMediaType } from '@cat-factory/contracts'
 import type { BinaryModality, RegisteredBinaryGenerator } from '@cat-factory/contracts'
 import type {
   BinaryOutputArtifact,
@@ -118,6 +118,28 @@ export interface BinaryOutputView {
    * Empty ⇒ the step imposes no requirement, so nothing is uncovered by construction.
    */
   modalities: readonly BinaryModality[]
+  /**
+   * The concrete FORMATS the step declares it must deliver
+   * (`stepOptions.binaryOutput.mediaTypes`), for the deliverables where the container is the
+   * requirement rather than a preference — a mesh the engine can import.
+   */
+  mediaTypes: readonly string[]
+  /**
+   * Required formats no DECLARED artifact reports a matching `contentType` for.
+   *
+   * The one judgement this surface can make that admission cannot: admission checked what the
+   * selected integrations CAN emit, and this checks what the run actually came back with. It is
+   * derived in code from the two records the step already carries — never read off the agent's
+   * prose — and it is the question a human opens this panel to answer once a mesh is supposed to
+   * load in a build.
+   *
+   * Computed only when there ARE artifacts to compare against: with none, the state line above
+   * already says nothing was recorded, and "it did not deliver a GLB" on top of "it declared
+   * nothing" is the same fact stated twice as if it were two. An artifact that reports no
+   * `contentType` covers nothing — the platform does not guess a format from a filename — so a
+   * report with formats required and none reported says so rather than passing.
+   */
+  undeliveredMediaTypes: readonly string[]
   /**
    * Integration ids the AGENT named that the deployment does not register. The generative twin of
    * {@link unknownDeclaredServices}, and it needs no exclusion to stay disjoint from anything —
@@ -168,6 +190,7 @@ export function binaryOutputView(step: PipelineStep | null | undefined): BinaryO
   const contextServices = config?.contextServiceIds ?? []
   const generators = config?.generatorIds ?? []
   const modalities = config?.modalities ?? []
+  const mediaTypes = config?.mediaTypes ?? []
   if (!report) {
     return {
       // A step still queued has not had the chance to record anything, which is a different
@@ -180,6 +203,8 @@ export function binaryOutputView(step: PipelineStep | null | undefined): BinaryO
       unknownDeclaredServices: [],
       generators,
       modalities,
+      mediaTypes,
+      undeliveredMediaTypes: [],
       unknownDeclaredGenerators: [],
       generatorsUnverified: false,
       invalidEntries: 0,
@@ -208,6 +233,8 @@ export function binaryOutputView(step: PipelineStep | null | undefined): BinaryO
     unknownDeclaredServices: report.unknownServices.filter((id) => id !== target),
     generators,
     modalities,
+    mediaTypes,
+    undeliveredMediaTypes: undeliveredMediaTypes(mediaTypes, rows),
     unknownDeclaredGenerators: report.unknownGenerators,
     generatorsUnverified: report.generatorsUnverified === true,
     invalidEntries: report.invalidEntries,
@@ -216,6 +243,30 @@ export function binaryOutputView(step: PipelineStep | null | undefined): BinaryO
   }
 }
 
+/**
+ * The required formats {@link BinaryOutputRow.contentType} does not account for.
+ *
+ * Compared through `normalizeMediaType` on the DECLARED side only: the step's requirement already
+ * came through `mediaTypeSchema` at the write boundary, while the artifact's content type is the
+ * agent's own prose and matches nothing until it is reduced the same way. Exact match after that,
+ * never a modality fallback — an artifact reported as `model/fbx` does not satisfy a requirement
+ * for `model/gltf-binary` just because both are 3D, and that is the entire point of requiring a
+ * format rather than a content type.
+ */
+function undeliveredMediaTypes(
+  required: readonly string[],
+  rows: readonly BinaryOutputRow[],
+): string[] {
+  if (required.length === 0 || rows.length === 0) return []
+  const delivered = new Set(
+    rows.flatMap((row) => {
+      const normalized = row.contentType ? normalizeMediaType(row.contentType) : null
+      return normalized ? [normalized] : []
+    }),
+  )
+  return required.filter((mediaType) => !delivered.has(mediaType))
+}
+
 /**
  * Which failure the report records, in the order the parser can produce them. `parseFailed`
  * and `undeclared` are checked BEFORE the (always empty in those cases) `stored` list, so a
@@ -298,6 +349,7 @@ export function binaryOutputHasWarnings(view: BinaryOutputView): boolean {
     view.unknownDeclaredServices.length > 0 ||
     view.unknownDeclaredGenerators.length > 0 ||
     view.generatorsUnverified ||
+    view.undeliveredMediaTypes.length > 0 ||
     view.invalidEntries > 0 ||
     view.omitted > 0 ||
     view.misdirected > 0
@@ -345,6 +397,21 @@ export type BinaryOutputPickIssue =
   | 'unknown_generator'
   /** A content type the step declares it delivers is produced by NO selected integration. */
   | 'modality_uncovered'
+  /**
+   * A concrete FORMAT the step declares it delivers is emitted by no selected integration that
+   * declared its formats (kernel's `media_type_uncovered` spelling verbatim). A refusal, like the
+   * two above it.
+   */
+  | 'media_type_uncovered'
+  /**
+   * A declared format nothing selected claims, where a selected integration declares no formats
+   * at all — so it MIGHT be met and nothing may say otherwise. ADVISORY: unlike every other
+   * member here it is not a refusal and must not be styled as one, or a step that is going to
+   * start perfectly well reads as broken. It is here rather than nowhere because the alternative
+   * is silence about a requirement the platform could not check, which is how "nobody looked"
+   * comes to look exactly like "this is fine".
+   */
+  | 'media_type_unverifiable'
 
 /** What the builder found wrong with one step's selection, and which ids to name. */
 export interface BinaryOutputPickState {
@@ -355,6 +422,10 @@ export interface BinaryOutputPickState {
   unknownGeneratorIds: readonly string[]
   /** The declared content types nothing selected can produce, for the message that names them. */
   uncoveredModalities: readonly BinaryModality[]
+  /** The declared formats no DECLARING integration emits — the refusal's own list. */
+  uncoveredMediaTypes: readonly string[]
+  /** The declared formats that could not be judged, kept apart from the refusal above. */
+  unverifiableMediaTypes: readonly string[]
 }
 
 /**
@@ -374,24 +445,72 @@ export interface BinaryOutputPickState {
  */
 function generatorPickIssues(
   config: BinaryOutputConfig | undefined,
-  generators: readonly Pick<RegisteredBinaryGenerator, 'id' | 'modalities'>[],
+  generators: readonly Pick<RegisteredBinaryGenerator, 'id' | 'modalities' | 'mediaTypes'>[],
   unavailable: boolean,
-): { issues: BinaryOutputPickIssue[]; unknownGeneratorIds: string[]; uncovered: BinaryModality[] } {
-  if (unavailable) {
-    return { issues: ['generators_unavailable'], unknownGeneratorIds: [], uncovered: [] }
+): {
+  issues: BinaryOutputPickIssue[]
+  unknownGeneratorIds: string[]
+  uncovered: BinaryModality[]
+  uncoveredMediaTypes: string[]
+  unverifiableMediaTypes: string[]
+} {
+  const none = {
+    unknownGeneratorIds: [],
+    uncovered: [],
+    uncoveredMediaTypes: [],
+    unverifiableMediaTypes: [],
   }
+  if (unavailable) return { issues: ['generators_unavailable'], ...none }
   const byId = new Map(generators.map((g) => [g.id, g]))
   const selectedIds = config?.generatorIds ?? []
   const unknownGeneratorIds = selectedIds.filter((id) => !byId.has(id))
   // Coverage is judged against what RESOLVED, exactly as admission judges it: an unknown id
   // contributes no content types, so a step whose only audio generator is unregistered is told
   // BOTH things — the id is gone, and the requirement it was covering is now uncovered.
-  const covered = new Set(selectedIds.flatMap((id) => byId.get(id)?.modalities ?? []))
+  const selected = selectedIds.flatMap((id) => byId.get(id) ?? [])
+  const covered = new Set(selected.flatMap((g) => g.modalities))
   const uncovered = (config?.modalities ?? []).filter((m) => !covered.has(m))
+  const format = formatCoverage(config?.mediaTypes ?? [], selected)
   const issues: BinaryOutputPickIssue[] = []
   if (unknownGeneratorIds.length) issues.push('unknown_generator')
   if (uncovered.length) issues.push('modality_uncovered')
-  return { issues, unknownGeneratorIds, uncovered }
+  if (format.uncovered.length) issues.push('media_type_uncovered')
+  if (format.unverifiable.length) issues.push('media_type_unverifiable')
+  return {
+    issues,
+    unknownGeneratorIds,
+    uncovered,
+    uncoveredMediaTypes: format.uncovered,
+    unverifiableMediaTypes: format.unverifiable,
+  }
+}
+
+/**
+ * The SPA's copy of kernel's `binaryFormatCoverage`, restated for the reason the two `*_service`
+ * members above are: the builder cannot see kernel, and the wire vocabulary that does cross
+ * (`@cat-factory/contracts`) carries the schema, not the rule.
+ *
+ * The THIRD outcome is what must not be lost in the copying. A generator that declares no formats
+ * has said "only my modality is known" — a documented state, not an empty answer — so a
+ * requirement it cannot be judged against is unverifiable and the step still starts. Collapsing
+ * that into `uncovered` would flag steps the backend admits (and send someone editing a selection
+ * that is fine); collapsing it into silence would present an unchecked requirement as a checked
+ * one.
+ */
+function formatCoverage(
+  required: readonly string[],
+  selected: readonly Pick<RegisteredBinaryGenerator, 'mediaTypes'>[],
+): { uncovered: string[]; unverifiable: string[] } {
+  const emitted = new Set(selected.flatMap((g) => g.mediaTypes ?? []))
+  const undeclared = selected.some((g) => (g.mediaTypes ?? []).length === 0)
+  const uncovered: string[] = []
+  const unverifiable: string[] = []
+  for (const mediaType of required) {
+    if (emitted.has(mediaType)) continue
+    if (undeclared) unverifiable.push(mediaType)
+    else uncovered.push(mediaType)
+  }
+  return { uncovered, unverifiable }
 }
 
 /**
@@ -425,7 +544,7 @@ export function binaryOutputPickIssues(
   // that registers no integrations cannot satisfy a step that selects one. So a call site that
   // omits this FLAGS a selection rather than passing it — the loud direction — and the default
   // stays a legitimate value rather than a hole.
-  generators: readonly Pick<RegisteredBinaryGenerator, 'id' | 'modalities'>[] = [],
+  generators: readonly Pick<RegisteredBinaryGenerator, 'id' | 'modalities' | 'mediaTypes'>[] = [],
   // Whether the deployment's integrations could not be READ. Defaulted to `false` — the honest
   // default, since every deployment but a mothership-mode node reads them in-process and cannot
   // fail — so an omitting call site judges the list it was given rather than claiming an outage.
@@ -451,6 +570,8 @@ export function binaryOutputPickIssues(
       unknownContextIds: [],
       unknownGeneratorIds: generative.unknownGeneratorIds,
       uncoveredModalities: generative.uncovered,
+      uncoveredMediaTypes: generative.uncoveredMediaTypes,
+      unverifiableMediaTypes: generative.unverifiableMediaTypes,
     }
   }
 
@@ -472,5 +593,7 @@ export function binaryOutputPickIssues(
     unknownContextIds,
     unknownGeneratorIds: generative.unknownGeneratorIds,
     uncoveredModalities: generative.uncovered,
+    uncoveredMediaTypes: generative.uncoveredMediaTypes,
+    unverifiableMediaTypes: generative.unverifiableMediaTypes,
   }
 }

package/app/utils/tutorial.spec.ts

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