@cat-factory/app 0.201.1 → 0.204.0

package/app/utils/tutorial.ts

@@ -95,6 +95,30 @@ export interface TutorialStep {
   when?: (gates: NavGates) => boolean
 }
 
+/**
+ * One named precondition a tour needs before it can be taken — a board write permission, a
+ * source-control connection, a service on the board.
+ *
+ * A DECLARED object rather than the bare `when(gates)` predicate a tour used to carry, because
+ * the catalogue has to say why a tour it is showing cannot be started right now. A predicate
+ * answers only "no", and a surface that lists what it can offer while silently omitting the
+ * rest reads exactly like a deployment that ships four tours instead of six — the "absent and
+ * zero must never render the same" rule, applied to a catalog. Pairing the predicate with the
+ * i18n key that NAMES it means the reason is computed from the same fact that withheld the
+ * tour, rather than restated beside it and left to drift.
+ *
+ * A consumer deployment writes its own: this is a plain object with its own copy key, so it
+ * needs no registration and no entry in a first-party table.
+ */
+export interface TutorialRequirement {
+  /** Stable id, unique within a tour's list; the catalogue keys its reason list on it. */
+  id: string
+  /** i18n key naming the requirement as a noun phrase ("A service on the board"). */
+  labelKey: string
+  /** Whether this board/user currently satisfies it. */
+  met: (gates: NavGates) => boolean
+}
+
 export interface TutorialTour {
   /** Stable id; completion is persisted against it, so renaming one resets its state. */
   id: string
@@ -104,48 +128,198 @@ export interface TutorialTour {
   /** Sort key in the tour list; ties break on `id` so the order is deterministic. */
   order: number
   /**
-   * Availability gate over the same reactive {@link NavGates} the nav catalog uses, so a
-   * tour about a surface the caller can't reach (no board write, no GitHub) never shows.
-   * Absent = always offered.
+   * What this board/user must have before the tour can run, over the same reactive
+   * {@link NavGates} the nav catalog uses — so a tour about a surface the caller can't reach
+   * (no board write, no source control) is never started, and the catalogue can say which of
+   * these is the one still missing. Absent = always available.
    */
-  when?: (gates: NavGates) => boolean
+  requires?: readonly TutorialRequirement[]
   steps: readonly TutorialStep[]
 }
 
 /** How long the overlay polls for a step's anchor before auto-skipping the step. */
 export const DEFAULT_TARGET_WAIT_MS = 4000
 
-/** How often the overlay re-queries / re-measures its anchor (canvas pans, panels open). */
+/**
+ * How often the overlay re-queries the DOM while it is still HUNTING for a step's anchor.
+ * Fast on purpose — the anchor can appear at any moment (a modal mounting, a live event
+ * landing a card) and every tick spent waiting is time the user stares at a "looking for
+ * it" note — and bounded on purpose, by the step's own {@link DEFAULT_TARGET_WAIT_MS}-ish
+ * budget, after which the step is skipped and the hunt stops.
+ */
 export const TARGET_TRACK_INTERVAL_MS = 150
 
+/**
+ * How often the overlay re-queries once it HAS an anchor.
+ *
+ * Anchored tracking is event-driven (scroll, resize, element resize, canvas pan/zoom), so
+ * this interval is only the backstop for movement nothing reports — and it is the tick that
+ * runs for the whole length of a tour, where the hunting one above is bounded by a step's
+ * wait budget. It also re-RESOLVES the selector rather than re-measuring the cached element,
+ * which is what lets a step re-anchor when the control it names is replaced underneath it.
+ */
+export const TARGET_IDLE_INTERVAL_MS = 400
+
+/**
+ * How much of an anchor has to be on screen before the overlay leaves the viewport alone.
+ *
+ * Measured against `min(anchorArea, viewportArea)`, not against the anchor's own area, because
+ * the catalog points at controls of wildly different sizes: `add-task-submit` is a button that
+ * must be almost wholly visible to be pointed at, while `board-canvas` and `sidebar` are bigger
+ * than the viewport and can NEVER clear a fraction of their own area. Taking the smaller of the
+ * two means "mostly visible" for a small control and "filling a good part of the screen" for a
+ * large one, which is the same judgement in both cases.
+ */
+export const MIN_VISIBLE_RATIO = 0.5
+
 /** Deterministic tour-list order: `order`, then `id`. */
 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.
+ * Why a tour is or isn't offered right now.
  *
- * 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
+ * Three values rather than a boolean, because the two unavailable ones need different copy
+ * and different action from the reader: `blocked` names things they can go and do (link a
+ * repository, start a run), while `not-applicable` is a tour whose every step is about a
+ * branch this board isn't on — nothing to fix, and telling someone to fix it would send them
+ * looking for a control that was never missing.
+ *
+ * `blocked` OUTRANKS `not-applicable` when a tour is both, and that order is load-bearing: a
+ * step's `when` reads the same gates the requirements do, so under UNMET requirements the step
+ * filter is answering a hypothetical — what would apply on a board that, by construction, this
+ * one is not. Reporting that as `not-applicable` would tell the reader there is nothing to be
+ * done about a tour they can in fact unlock. The cost is the reverse case: a tour can be named
+ * as unlockable and still turn out `not-applicable` once the requirement is met. See
+ * {@link resolveTourCatalogue} for why a tour should not be authored that way.
+ */
+export type TutorialAvailability = 'ready' | 'blocked' | 'not-applicable'
+
+/** One tour as this board sees it: the resolved script plus why it can (or can't) run. */
+export interface TutorialCatalogueEntry {
+  /** The tour with its inapplicable steps already dropped — what a start would run. */
+  tour: TutorialTour
+  availability: TutorialAvailability
+  /** The requirements this board/user does not meet. Empty unless `blocked`. */
+  unmet: readonly TutorialRequirement[]
+}
+
+/**
+ * Resolve the whole catalog against the gates: which tours can run now, and for the rest,
+ * exactly what is standing in the way.
+ *
+ * Per-step `when`s are applied here too, and a tour left with NO applicable steps is
+ * `not-applicable` rather than ready. That 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 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.
+ * `gates` is nullable for the same reason `navSlotFilter` passes everything through when no
+ * gates service is wired (a bare install / dev-open parity): with nothing to gate against,
+ * nothing is withheld — including the per-step branches, which must not be silently thinned.
+ *
+ * AUTHORING RULE, and the reason `blocked` outranks `not-applicable` is safe in practice: give
+ * every tour at least one step with NO `when`. An intro and a finish card qualify, which is why
+ * every built-in has two (pinned by `tutorial-tours.spec.ts`). Then `steps` can never be empty,
+ * `not-applicable` is reachable only for a tour authored as branch-specific END TO END, and a
+ * tour named in the catalogue as unlockable can never turn out unstartable after the reader has
+ * gone and done the thing it asked for.
+ *
+ * Pure, total and sorted, so both consumers (the launch prompt's offer list and the
+ * catalogue) read one resolution rather than each re-deriving availability, 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 })
+export function resolveTourCatalogue(
+  tours: readonly TutorialTour[],
+  gates: NavGates | null,
+): TutorialCatalogueEntry[] {
+  return sortTours(tours).map((tour) => {
+    const unmet = gates ? (tour.requires ?? []).filter((r) => !r.met(gates)) : []
+    const steps = gates ? tour.steps.filter((s) => (s.when ? s.when(gates) : true)) : tour.steps
+    // Reuse the original object when nothing was dropped: both surfaces key their lists on
+    // the tour, and a fresh object per gate read would re-render on every unrelated flip.
+    const resolved = steps.length === tour.steps.length ? tour : { ...tour, steps }
+    const availability: TutorialAvailability =
+      unmet.length > 0 ? 'blocked' : steps.length === 0 ? 'not-applicable' : 'ready'
+    return { tour: resolved, availability, unmet }
+  })
+}
+
+/** The tours that can be started right now, resolved — the launch prompt's offer list. */
+export function resolveTours(
+  tours: readonly TutorialTour[],
+  gates: NavGates | null,
+): TutorialTour[] {
+  return resolveTourCatalogue(tours, gates)
+    .filter((entry) => entry.availability === 'ready')
+    .map((entry) => entry.tour)
+}
+
+/**
+ * Where a tour stands for this user: the state the catalogue badges and the action label
+ * derive from. Camel-cased because the values ARE the i18n leaf keys
+ * (`tutorial.status.<state>`, `tutorial.action.<action>`), which keeps those lookups total.
+ */
+export type TutorialTourState = 'notStarted' | 'inProgress' | 'paused' | 'completed'
+
+/** What the tour's button does, given that state. */
+export type TutorialLaunchAction = 'start' | 'resume' | 'restart' | 'continue'
+
+/**
+ * Which state a tour is in, in precedence order: the one RUNNING wins over everything, then a
+ * broken-off position, then completion.
+ *
+ * Paused beating completed is the deliberate half: a tour taken again and broken off is
+ * offered where it stopped, rather than being described by the badge it earned last time.
+ */
+export function tourState(input: {
+  active: boolean
+  resumable: boolean
+  completed: boolean
+}): TutorialTourState {
+  if (input.active) return 'inProgress'
+  if (input.resumable) return 'paused'
+  return input.completed ? 'completed' : 'notStarted'
+}
+
+/**
+ * The action offered for a state. Total, so a new state cannot reach a surface without an
+ * action — `continue` exists because the catalogue is reachable DURING a tour (nothing about
+ * the overlay blocks the sidebar), and offering "Start" for the walkthrough already on screen
+ * would restart it from step one on a click most people would read as "back to it".
+ */
+export function launchActionFor(state: TutorialTourState): TutorialLaunchAction {
+  const actions: Record<TutorialTourState, TutorialLaunchAction> = {
+    notStarted: 'start',
+    inProgress: 'continue',
+    paused: 'resume',
+    completed: 'restart',
   }
-  return out
+  return actions[state]
+}
+
+/**
+ * The copy for each state / action, as exhaustive `Record`s rather than a key assembled at
+ * the call site (`t(\`tutorial.action.${action}\`)`).
+ *
+ * The typed-message-key check only covers keys written as literals, so an assembled one is
+ * exactly the drift it cannot see — the i18n guard's tier-2 rule. Declared this way, adding a
+ * state without its copy fails the typecheck, and `tutorial.spec.ts` pins every value against
+ * the catalog so a RENAMED key fails a test instead of rendering a raw path to the user.
+ */
+export const TUTORIAL_STATUS_KEYS: Record<TutorialTourState, string> = {
+  notStarted: 'tutorial.status.notStarted',
+  inProgress: 'tutorial.status.inProgress',
+  paused: 'tutorial.status.paused',
+  completed: 'tutorial.status.completed',
+}
+
+export const TUTORIAL_ACTION_KEYS: Record<TutorialLaunchAction, string> = {
+  start: 'tutorial.action.start',
+  resume: 'tutorial.action.resume',
+  restart: 'tutorial.action.restart',
+  continue: 'tutorial.action.continue',
 }
 
 /** A DOMRect-shaped box, structurally typed so the geometry below is unit-testable. */
@@ -156,6 +330,43 @@ export interface TutorialRect {
   height: number
 }
 
+/**
+ * How much of `rect` lies inside the viewport, in square pixels. Zero when they don't overlap
+ * at all, which is the case that matters: an anchor scrolled or panned off screen.
+ */
+export function visibleArea(
+  rect: TutorialRect,
+  viewport: { width: number; height: number },
+): number {
+  const overlapWidth = Math.min(rect.left + rect.width, viewport.width) - Math.max(rect.left, 0)
+  const overlapHeight = Math.min(rect.top + rect.height, viewport.height) - Math.max(rect.top, 0)
+  return Math.max(0, overlapWidth) * Math.max(0, overlapHeight)
+}
+
+/**
+ * Does the overlay have to bring this anchor into view before the step can read correctly?
+ *
+ * The runtime accepts any element with layout boxes, and an element scrolled out of a panel or
+ * panned off the board canvas still HAS them — so without this check the highlight ring is
+ * drawn at off-screen coordinates while `computeCoachMarkLayout` clamps the tooltip to a
+ * viewport edge, leaving the user reading "click this" beside nothing at all. It bites the
+ * most-travelled steps hardest: the two `task-card` steps anchor whichever card is first in
+ * the DOM, which on a populated board is the one least likely to be the one on screen.
+ *
+ * Pure, so the threshold is pinned by unit tests rather than eyeballed against a real board.
+ * A zero-area anchor never needs revealing: there is no position to bring anywhere, and
+ * treating it as off-screen would make every degenerate rect trigger a canvas pan.
+ */
+export function needsReveal(
+  rect: TutorialRect,
+  viewport: { width: number; height: number },
+): boolean {
+  const area = rect.width * rect.height
+  if (area <= 0) return false
+  const required = MIN_VISIBLE_RATIO * Math.min(area, viewport.width * viewport.height)
+  return visibleArea(rect, viewport) < required
+}
+
 export interface CoachMarkLayout {
   top: number
   left: number

package/i18n/locales/de.json

@@ -2162,7 +2162,6 @@
         "shortcuts": "Tastenkürzel",
         "bugHunt": "Fehlerjagd",
         "toggleUiMode": "Oberflächenmodus wechseln",
-        "tutorial": "Tour starten",
         "foundationalServices": "Basisdienste"
       },
       "keywords": {
@@ -3733,7 +3732,17 @@
       "consensusGroupsActive": "Dieser Schritt führt die ausgewählte Gruppe aus. Hebe die Auswahl aller Gruppen auf, um die Teilnehmer hier zu konfigurieren.",
       "consensusGroupAlways": "immer",
       "variantLabel": "Prompt-Variante",
-      "variantShipped": "Ausgelieferter Prompt"
+      "variantShipped": "Ausgelieferter Prompt",
+      "binaryOutputStorage": "Speichern über",
+      "binaryOutputContext": "Kontext der Erzeugung",
+      "binaryOutputPlaceholder": "Speicherdienst wählen",
+      "binaryOutputContextPlaceholder": "Optional: Dienste, die den Umfang bestimmen",
+      "binaryOutputNeedsPick": "Für einen Schritt, der binäre Ausgaben erzeugt, ist kein Speicherdienst gewählt. Wähle einen vor dem Speichern.",
+      "binaryOutputNoStorage": "Kein Dienst im Katalog dieses Boards deklariert die Fähigkeit {capability}. Registriere einen, oder ergänze die Fähigkeit beim gemeinten Dienst unter den grundlegenden Diensten.",
+      "binaryOutputMissing": "Dieser Speicherdienst ist nicht mehr im Katalog; wähle einen anderen.",
+      "binaryOutputNotStorage": "Dieser Dienst deklariert die Fähigkeit {capability} nicht mehr, deshalb werden Läufe abgelehnt; wähle einen anderen.",
+      "binaryOutputContextMissing": "Diese Kontextdienste sind nicht mehr im Katalog: {ids}",
+      "binaryOutputUnavailable": "Der Katalog der grundlegenden Dienste ist nicht erreichbar, deshalb lässt sich hier noch nichts wählen."
     },
     "progress": {
       "status": {
@@ -4384,6 +4393,47 @@
       "unlinkSourceFailed": "Repo-Verknüpfung konnte nicht gelöst werden"
     }
   },
+  "binaryOutput": {
+    "heading": "Binäre Ausgaben",
+    "target": "Speicherdienst",
+    "targetNone": "Für diesen Schritt nicht erfasst",
+    "contextServices": "Kontext der Erzeugung",
+    "misdirectedBadge": "Anderer Dienst",
+    "unknownBadge": "Nicht im Katalog",
+    "storedCount": "{outcome}, 1 Artefakt | {outcome}, {count} Artefakte",
+    "state": {
+      "notStarted": {
+        "summary": "Noch nicht gestartet",
+        "detail": "Dieser Schritt hat noch nicht begonnen. Wenn er läuft, speichert er seine binären Ausgaben über den unten genannten Dienst."
+      },
+      "configured": {
+        "summary": "Noch nichts erfasst",
+        "detail": "Dieser Schritt ist auf das Speichern binärer Ausgaben eingerichtet, hat aber noch keine gemeldet. Er läuft noch, oder er endete vor seiner Meldung."
+      },
+      "undeclared": {
+        "summary": "Nichts angegeben",
+        "detail": "Dieser Schritt endete, ohne anzugeben, was er gespeichert hat. Möglicherweise hat er etwas gespeichert, möglicherweise nicht; erfasst wurde in beiden Fällen nichts."
+      },
+      "parseFailed": {
+        "summary": "Angabe unlesbar",
+        "detail": "Dieser Schritt endete mit einer Angabe, welche die Plattform nicht lesen konnte, deshalb wurde nichts erfasst. Was er gespeichert hat, fehlt in der Liste unten."
+      },
+      "declaredNone": {
+        "summary": "Nichts gespeichert",
+        "detail": "Der Agent hat gemeldet, dass er keine binären Artefakte gespeichert hat. Das ist ein gültiges Ergebnis, kein Fehler."
+      },
+      "stored": {
+        "summary": "Gespeichert"
+      }
+    },
+    "warning": {
+      "unknownServices": "Nennt einen Dienst, den der Katalog nicht enthält: {ids}. Der Eintrag bleibt wie angegeben erhalten; prüfe die Kennung gegen den Katalog des Boards. | Nennt Dienste, die der Katalog nicht enthält: {ids}. Die Einträge bleiben wie angegeben erhalten; prüfe die Kennungen gegen den Katalog des Boards.",
+      "targetUnknown": "Der Katalog enthält den eigenen Speicherdienst dieses Schritts nicht mehr ({id}), deshalb konnte nichts unten dagegen geprüft werden. Registriere ihn erneut, oder verweise den Schritt auf einen anderen Dienst.",
+      "misdirected": "1 Artefakt ging an einen anderen Dienst als {target}. | {count} Artefakte gingen an einen anderen Dienst als {target}.",
+      "invalidEntries": "1 angegebener Eintrag wurde verworfen: er nannte weder Dienst noch Ablageort. | {count} angegebene Einträge wurden verworfen: sie nannten weder Dienst noch Ablageort.",
+      "omitted": "1 weiteres Artefakt wurde jenseits der Berichtsgrenze angegeben und ist nicht aufgeführt. | {count} weitere Artefakte wurden jenseits der Berichtsgrenze angegeben und sind nicht aufgeführt."
+    }
+  },
   "brainstorm": {
     "title": {
       "architecture": "Architektur-Brainstorm",
@@ -4823,7 +4873,9 @@
     "accountSettings": "Kontoeinstellungen",
     "operatorDashboard": "Plattform-Observability",
     "reports": "Berichte",
-    "foundationalServices": "Basisdienste"
+    "foundationalServices": "Basisdienste",
+    "tutorials": "Tutorials",
+    "help": "Hilfe"
   },
   "errors": {
     "generic": {
@@ -6125,12 +6177,41 @@
     "prompt": {
       "title": "Eine kurze Tour machen?",
       "intro": "Geführte Touren zeigen dir die App direkt auf diesem Bildschirm: Sie heben die echten Bedienelemente hervor und sagen dir, was du anklicken sollst.",
-      "start": "Starten",
-      "restart": "Wiederholen",
-      "completed": "Abgeschlossen",
       "decline": "Nein danke",
       "later": "Vielleicht später",
-      "empty": "Für deine Rolle auf diesem Board sind noch keine Touren verfügbar."
+      "empty": "Für deine Rolle auf diesem Board sind noch keine Touren verfügbar.",
+      "browse": "Alle Tutorials anzeigen"
+    },
+    "catalogue": {
+      "title": "Tutorials",
+      "intro": "Geführte Rundgänge, die dir unterwegs die echten Bedienelemente hervorheben. Du kannst jeden davon jederzeit starten und beliebig oft wiederholen.",
+      "progress": "{completed} von {total} abgeschlossen",
+      "steps": "1 Schritt | {count} Schritte",
+      "blocked": "Verfügbar, sobald du Folgendes hast:",
+      "notApplicable": "Auf diesem Board gibt es derzeit nichts, was dieser Rundgang zeigen könnte.",
+      "empty": "Diese Installation enthält keine Tutorials.",
+      "reset": "Fortschritt zurücksetzen",
+      "resetHint": "Vergisst, welche Tutorials du abgeschlossen hast, und fragt dich beim nächsten Besuch erneut nach der Tour."
+    },
+    "action": {
+      "start": "Starten",
+      "resume": "Fortsetzen",
+      "restart": "Wiederholen",
+      "continue": "Zurück zur Tour"
+    },
+    "status": {
+      "notStarted": "Nicht begonnen",
+      "inProgress": "Läuft",
+      "paused": "Pausiert",
+      "completed": "Abgeschlossen"
+    },
+    "requirements": {
+      "boardWrite": "Berechtigung, dieses Board zu bearbeiten",
+      "sourceControl": "Eine verbundene Quellcodeverwaltung",
+      "service": "Ein Service auf dem Board",
+      "task": "Eine Aufgabe auf dem Board",
+      "waitingAnswer": "Ein Lauf, der auf deine Antwort wartet",
+      "finishedRun": "Ein erfolgreich abgeschlossener Lauf"
     },
     "overlay": {
       "next": "Weiter",
@@ -6139,6 +6220,7 @@
       "done": "Fertig",
       "progress": "Schritt {current} von {total}",
       "ariaLabel": "Tutorial-Schritt",
+      "announcement": "Schritt {current} von {total}. {title}. {body}",
       "abridged": "1 Schritt wurde übersprungen: dieses Element gehört nicht zu diesem Board. | {count} Schritte wurden übersprungen: diese Elemente gehören nicht zu diesem Board.",
       "searching": "Suche das hervorgehobene Element...",
       "clickHint": "Klicke auf das hervorgehobene Element, um fortzufahren"

package/i18n/locales/en.json

@@ -151,7 +151,9 @@
     "accountSettings": "Account settings",
     "operatorDashboard": "Platform observability",
     "reports": "Reports",
-    "foundationalServices": "Foundational services"
+    "foundationalServices": "Foundational services",
+    "tutorials": "Tutorials",
+    "help": "Help"
   },
   "board": {
     "toast": {
@@ -2164,7 +2166,6 @@
         "shortcuts": "Keyboard shortcuts",
         "bugHunt": "Bug hunt",
         "toggleUiMode": "Switch interface mode",
-        "tutorial": "Take a tour",
         "foundationalServices": "Foundational services"
       },
       "keywords": {
@@ -4208,7 +4209,17 @@
       "consensusGroupsActive": "This step runs the selected group. Deselect every group to configure participants here instead.",
       "consensusGroupAlways": "always",
       "variantLabel": "Prompt variant",
-      "variantShipped": "Shipped prompt"
+      "variantShipped": "Shipped prompt",
+      "binaryOutputStorage": "Store through",
+      "binaryOutputContext": "Generation context",
+      "binaryOutputPlaceholder": "Pick a storage service",
+      "binaryOutputContextPlaceholder": "Optional: services that scope the generation",
+      "binaryOutputNeedsPick": "A step that generates binary outputs has no storage service selected. Pick one before saving.",
+      "binaryOutputNoStorage": "No service in this board's catalog declares the {capability} capability. Register one, or add the capability to the service you meant, under foundational services.",
+      "binaryOutputMissing": "This storage service is no longer in the catalog; pick another.",
+      "binaryOutputNotStorage": "This service no longer declares the {capability} capability, so runs will be refused; pick another.",
+      "binaryOutputContextMissing": "These context services are no longer in the catalog: {ids}",
+      "binaryOutputUnavailable": "The foundational services catalog is unreachable, so nothing can be picked here yet."
     },
     "progress": {
       "status": {
@@ -5592,6 +5603,47 @@
       "unlinkSourceFailed": "Could not unlink the repo"
     }
   },
+  "binaryOutput": {
+    "heading": "Binary outputs",
+    "target": "Storage service",
+    "targetNone": "None recorded on this step",
+    "contextServices": "Generation context",
+    "misdirectedBadge": "Other service",
+    "unknownBadge": "Not in catalog",
+    "storedCount": "{outcome}, 1 artifact | {outcome}, {count} artifacts",
+    "state": {
+      "notStarted": {
+        "summary": "Not started yet",
+        "detail": "This step has not started yet. When it runs, it will store its binary outputs through the service below."
+      },
+      "configured": {
+        "summary": "Nothing recorded yet",
+        "detail": "This step is set up to store binary outputs, but it has not reported any yet. It is still running, or it ended before it reported."
+      },
+      "undeclared": {
+        "summary": "Nothing declared",
+        "detail": "This step finished without declaring what it stored. It may or may not have stored something; either way, nothing was recorded."
+      },
+      "parseFailed": {
+        "summary": "Declaration unreadable",
+        "detail": "This step ended with a declaration the platform could not read, so nothing was recorded. Anything it stored is missing from the list below."
+      },
+      "declaredNone": {
+        "summary": "Stored nothing",
+        "detail": "The agent reported that it stored no binary artifacts. That is a valid outcome, not a failure."
+      },
+      "stored": {
+        "summary": "Stored"
+      }
+    },
+    "warning": {
+      "unknownServices": "Named a service the catalog does not contain: {ids}. The entry is kept as claimed; check the id against the workspace catalog. | Named services the catalog does not contain: {ids}. Their entries are kept as claimed; check the ids against the workspace catalog.",
+      "targetUnknown": "The catalog no longer contains this step's own storage service ({id}), so nothing below could be checked against it. Register it again, or point the step at another service.",
+      "misdirected": "1 artifact went to a service other than {target}. | {count} artifacts went to a service other than {target}.",
+      "invalidEntries": "1 declared entry was dropped: it named no service and location. | {count} declared entries were dropped: they named no service and location.",
+      "omitted": "1 more artifact was declared beyond the report's limit and is not listed. | {count} more artifacts were declared beyond the report's limit and are not listed."
+    }
+  },
   "sandbox": {
     "title": "Sandbox: prompt and model testing",
     "description": "Try prompt versions and models against graded fixtures, scored by a judge model.",
@@ -6329,12 +6381,50 @@
     "prompt": {
       "title": "Take a quick tour?",
       "intro": "Guided tours walk you through the app right on this screen: they highlight the actual controls and tell you what to click.",
-      "start": "Start",
-      "restart": "Repeat",
-      "completed": "Completed",
       "decline": "No thanks",
       "later": "Maybe later",
-      "empty": "No tours are available for your role on this board yet."
+      "empty": "No tours are available for your role on this board yet.",
+      "browse": "See all tutorials"
+    },
+    "catalogue": {
+      "title": "Tutorials",
+      "intro": "Guided walkthroughs that highlight the real controls as you go. Start any of them whenever you like, and take one again as often as you want.",
+      "progress": "{completed} of {total} completed",
+      "steps": "1 step | {count} steps",
+      "@steps": {
+        "description": "The length of one walkthrough. Needs the plural forms of the target language (pl/uk take three: one | few | many); {count} is the number of steps."
+      },
+      "blocked": "Available once you have:",
+      "notApplicable": "Nothing on this board matches this walkthrough right now.",
+      "empty": "This deployment ships no tutorials.",
+      "reset": "Reset progress",
+      "resetHint": "Forget which tutorials you have finished and ask about the tour again on your next visit."
+    },
+    "action": {
+      "start": "Start",
+      "resume": "Resume",
+      "@resume": {
+        "description": "Verb, on a button: pick a guided tour back up from where it was broken off. Not the noun (CV/resume)."
+      },
+      "restart": "Repeat",
+      "continue": "Back to the tour",
+      "@continue": {
+        "description": "Button on the tour that is already running: return to it. It does not restart the walkthrough from the beginning."
+      }
+    },
+    "status": {
+      "notStarted": "Not started",
+      "inProgress": "In progress",
+      "paused": "Paused",
+      "completed": "Completed"
+    },
+    "requirements": {
+      "boardWrite": "Permission to edit this board",
+      "sourceControl": "A connected source-control provider",
+      "service": "A service on the board",
+      "task": "A task on the board",
+      "waitingAnswer": "A run waiting for your answer",
+      "finishedRun": "A run that finished successfully"
     },
     "overlay": {
       "next": "Next",
@@ -6343,6 +6433,10 @@
       "done": "Finish",
       "progress": "Step {current} of {total}",
       "ariaLabel": "Tutorial step",
+      "announcement": "Step {current} of {total}. {title}. {body}",
+      "@announcement": {
+        "description": "Screen-reader-only announcement read out on every step change; it is never shown on screen. {title} and {body} are the step's own heading and full sentence, so the separators around them have to be real sentence punctuation in the target language."
+      },
       "abridged": "1 step was skipped: that control is not part of this board. | {count} steps were skipped: those controls are not part of this board.",
       "@abridged": {
         "description": "Shown on a tour's final card when steps were skipped. Needs the plural forms of the target language (pl/uk take three: one | few | many); {count} is the number of skipped steps."