@cat-factory/app 0.202.0 → 0.205.0

package/app/components/tutorial/TutorialCatalogue.vue

@@ -0,0 +1,150 @@
+<script setup lang="ts">
+// The tutorial catalogue: every guided walkthrough this deployment ships, startable (or
+// re-startable) at any time from the sidebar's Help section and the command palette.
+//
+// It is deliberately NOT the launch prompt with a second entry point. The prompt asks a
+// question once, offers what this board can run, and goes away; this answers "what else is
+// there, and why can't I take that one yet?" — so it lists the tours that are HELD BACK too,
+// each with the requirement still missing. Omitting them (which is all a slot filter could do)
+// makes a deployment shipping six walkthroughs look like one shipping two.
+//
+// Everything that decides lives in `TutorialCatalogue.logic.ts` (rows, progress) and
+// `utils/tutorial.ts` (availability, state, action), so the SFC only renders.
+import { buildCatalogueRows, summarizeProgress } from './TutorialCatalogue.logic'
+import type { TutorialCatalogueRow } from './TutorialCatalogue.logic'
+import { TUTORIAL_ACTION_KEYS, TUTORIAL_STATUS_KEYS } from '~/utils/tutorial'
+
+const { t } = useI18n()
+const tutorial = useTutorialStore()
+const { catalogue } = useTutorialTours()
+const { stateOf, launch } = useTutorialLaunch()
+
+const open = computed({
+  get: () => tutorial.catalogueOpen,
+  set: (v: boolean) => (v ? tutorial.openCatalogue() : tutorial.closeCatalogue()),
+})
+
+const rows = computed(() => buildCatalogueRows(catalogue.value, stateOf))
+const progress = computed(() =>
+  summarizeProgress(rows.value, { launchOfferAnswered: tutorial.decision !== null }),
+)
+
+/** A badge only where there is something to say: "not started" is the unremarkable default. */
+const showsStatus = (row: TutorialCatalogueRow) => row.state !== 'notStarted'
+
+const statusColor = (row: TutorialCatalogueRow) =>
+  row.state === 'completed' ? 'success' : row.state === 'inProgress' ? 'primary' : 'neutral'
+</script>
+
+<template>
+  <UModal
+    v-model:open="open"
+    :title="t('tutorial.catalogue.title')"
+    :description="t('tutorial.catalogue.intro')"
+    :ui="{ content: 'max-w-2xl' }"
+  >
+    <template #body>
+      <div class="space-y-4" data-testid="tutorial-catalogue">
+        <p v-if="rows.length > 0" class="text-xs text-slate-400" data-testid="tutorial-progress">
+          {{
+            t('tutorial.catalogue.progress', {
+              completed: progress.completed,
+              total: progress.total,
+            })
+          }}
+        </p>
+        <ul class="space-y-2">
+          <li
+            v-for="row in rows"
+            :key="row.tour.id"
+            class="flex items-start gap-3 rounded-lg border border-slate-800 bg-slate-900/60 p-3"
+            :class="row.startable ? '' : 'opacity-75'"
+            :data-testid="`tutorial-catalogue-entry-${row.tour.id}`"
+          >
+            <UIcon
+              :name="row.tour.icon ?? 'i-lucide-compass'"
+              class="mt-0.5 h-5 w-5 shrink-0 text-primary-400"
+            />
+            <div class="min-w-0 flex-1 space-y-1">
+              <div class="flex flex-wrap items-center gap-2">
+                <span class="text-sm font-medium text-slate-100">{{ t(row.tour.titleKey) }}</span>
+                <UBadge
+                  v-if="showsStatus(row)"
+                  :color="statusColor(row)"
+                  variant="subtle"
+                  size="sm"
+                  :data-testid="`tutorial-catalogue-status-${row.tour.id}`"
+                >
+                  {{ t(TUTORIAL_STATUS_KEYS[row.state]) }}
+                </UBadge>
+              </div>
+              <p class="text-xs text-slate-400">{{ t(row.tour.descriptionKey) }}</p>
+              <p v-if="row.stepCount !== null" class="text-xs text-slate-500">
+                {{ t('tutorial.catalogue.steps', { count: row.stepCount }, row.stepCount) }}
+              </p>
+              <!-- A held-back tour says what would unlock it, rather than vanishing from the
+                   list: these are things the reader can go and do. -->
+              <div
+                v-else-if="row.availability === 'blocked'"
+                class="text-xs text-slate-500"
+                :data-testid="`tutorial-catalogue-requirements-${row.tour.id}`"
+              >
+                <span>{{ t('tutorial.catalogue.blocked') }}</span>
+                <ul class="mt-1 space-y-0.5">
+                  <li v-for="req in row.unmet" :key="req.id" class="flex items-center gap-1.5">
+                    <UIcon name="i-lucide-lock" class="h-3 w-3 shrink-0" />
+                    <span>{{ t(req.labelKey) }}</span>
+                  </li>
+                </ul>
+              </div>
+              <!-- Requirements met, but every step is about a branch this board isn't on:
+                   nothing to go and fix, so it must not read like the case above. -->
+              <p v-else class="text-xs text-slate-500">
+                {{ t('tutorial.catalogue.notApplicable') }}
+              </p>
+            </div>
+            <UButton
+              size="sm"
+              color="primary"
+              :variant="row.state === 'completed' ? 'soft' : 'solid'"
+              :disabled="!row.startable"
+              :data-testid="`tutorial-catalogue-start-${row.tour.id}`"
+              @click="launch(row.tour.id)"
+            >
+              {{ t(TUTORIAL_ACTION_KEYS[row.action]) }}
+            </UButton>
+          </li>
+        </ul>
+        <!-- No tours at all is a real state (a deployment may register none of its own and
+             strip the built-ins), and it is not the same as one whose tours are all blocked. -->
+        <p v-if="rows.length === 0" class="text-sm text-slate-400">
+          {{ t('tutorial.catalogue.empty') }}
+        </p>
+      </div>
+    </template>
+    <template #footer>
+      <div class="flex w-full items-center justify-between gap-2">
+        <UButton
+          v-if="progress.resettable"
+          color="neutral"
+          variant="ghost"
+          icon="i-lucide-rotate-ccw"
+          :title="t('tutorial.catalogue.resetHint')"
+          data-testid="tutorial-catalogue-reset"
+          @click="tutorial.resetProgress()"
+        >
+          {{ t('tutorial.catalogue.reset') }}
+        </UButton>
+        <span v-else />
+        <UButton
+          color="neutral"
+          variant="soft"
+          data-testid="tutorial-catalogue-close"
+          @click="tutorial.closeCatalogue()"
+        >
+          {{ t('common.close') }}
+        </UButton>
+      </div>
+    </template>
+  </UModal>
+</template>

package/app/components/tutorial/TutorialOverlay.vue

@@ -428,7 +428,9 @@ onUnmounted(() => {
 
 <template>
   <!-- Teleported so board/panel stacking contexts can't clip the marks; z-[70] sits above
-       the app's modals (z-50s), since steps legitimately point INTO an open modal. -->
+       the app's modals (z-50s), since steps legitimately point INTO an open modal — with the
+       one exception of the tutorial's OWN windows (`ownWindowOpen`), which no step points into
+       and over which the same z-index would float a ring and a tooltip the user cannot use. -->
   <Teleport to="body">
     <!-- The step-change announcement. Visually hidden, and outside BOTH the dialog and the
          `v-if` below, so the live region is a stable node whose TEXT changes for the whole
@@ -438,7 +440,12 @@ onUnmounted(() => {
     <div class="sr-only" role="status" aria-live="polite" data-testid="tutorial-announcement">
       {{ announcement }}
     </div>
-    <div v-if="step" data-testid="tutorial-overlay">
+    <!-- SUPPRESSED, not unmounted, while a tutorial-owned window is open: this component holds
+         the running tour's resolved script (see `tour` above), and a remount would re-resolve it
+         against gates that may have flipped since the tour started — which is the very failure
+         that holding it fixed. The cursor, the tracking and the script all survive; only the
+         marks go, and they come back the moment the window closes. -->
+    <div v-if="step && !tutorial.ownWindowOpen" data-testid="tutorial-overlay">
       <!-- `motion-safe:` on the ring's transition: it slides between controls on every step,
            which is exactly the involuntary movement `prefers-reduced-motion` is about. -->
       <div

package/app/components/tutorial/TutorialPrompt.vue

@@ -1,39 +1,33 @@
 <script setup lang="ts">
-// The tutorial launch prompt: asks once on first launch whether the user wants a guided
-// tour, and doubles as the tour picker for later visits (command palette: "Take a tour").
-// Lists whatever the merged `tutorialTours` slot offers this user (first-party + consumer
-// tours, RBAC-gated per tour), so it grows with the catalog rather than hard-coding tours.
+// The tutorial launch prompt: asks once on first launch whether the user wants a guided tour,
+// listing the tours this board can actually run right now (first-party + consumer, resolved
+// against the same gates the nav uses), so it grows with the catalog rather than hard-coding
+// tours.
+//
+// It is the OFFER, not the library: the full list — including the walkthroughs this board
+// can't run yet and what would unlock them — is `TutorialCatalogue.vue`, one button away in
+// the footer and permanently reachable from the sidebar's Help section. That split is why
+// this stays a short, answerable question instead of growing into a browsing surface.
 //
 // The decision semantics live in the store: starting a tour or "No thanks" is SAVED (the
 // prompt never auto-opens again), while closing without answering defers to next launch.
+import { TUTORIAL_ACTION_KEYS } from '~/utils/tutorial'
+
 const { t } = useI18n()
 const tutorial = useTutorialStore()
 const { tours } = useTutorialTours()
+// Start / Resume / Repeat is decided in one place for both surfaces — see `useTutorialLaunch`.
+const { actionFor, launch } = useTutorialLaunch()
 
 const open = computed({
   get: () => tutorial.promptOpen,
   set: (v: boolean) => (v ? tutorial.openPrompt() : tutorial.closePrompt()),
 })
 
-// Only an unanswered prompt offers the persistent "No thanks"; once a decision exists this
-// is just a picker, and the only dismissal left is a plain close.
+// Only an unanswered prompt offers the persistent "No thanks": there is a decision to save.
+// Once one exists — this window can still be opened by the store — the only dismissal left is
+// a plain close, since declining something already answered would write nothing new.
 const undecided = computed(() => tutorial.decision === null)
-
-// A tour broken off mid-way (Esc, or Skip to get the overlay out of the way) offers to RESUME
-// where it stopped rather than only to start over. Session-scoped, so this is only ever offered
-// while the board is still in the state the tour left it in — see the store.
-const isResumable = (tourId: string) => tutorial.interruptedAt(tourId) !== null
-
-function launch(tourId: string) {
-  if (isResumable(tourId)) tutorial.resumeTour(tourId)
-  else tutorial.startTour(tourId)
-}
-
-/** Resume beats Completed: a tour taken again and broken off is offered where it stopped. */
-function launchLabel(tourId: string): string {
-  if (isResumable(tourId)) return t('tutorial.prompt.resume')
-  return tutorial.isCompleted(tourId) ? t('tutorial.prompt.restart') : t('tutorial.prompt.start')
-}
 </script>
 
 <template>
@@ -65,7 +59,7 @@ function launchLabel(tourId: string): string {
                   size="sm"
                   data-testid="tutorial-tour-completed"
                 >
-                  {{ t('tutorial.prompt.completed') }}
+                  {{ t('tutorial.status.completed') }}
                 </UBadge>
               </div>
               <p class="text-xs text-slate-400">{{ t(tour.descriptionKey) }}</p>
@@ -73,11 +67,11 @@ function launchLabel(tourId: string): string {
             <UButton
               size="sm"
               color="primary"
-              :variant="tutorial.isCompleted(tour.id) && !isResumable(tour.id) ? 'soft' : 'solid'"
+              :variant="actionFor(tour.id) === 'restart' ? 'soft' : 'solid'"
               :data-testid="`tutorial-start-${tour.id}`"
               @click="launch(tour.id)"
             >
-              {{ launchLabel(tour.id) }}
+              {{ t(TUTORIAL_ACTION_KEYS[actionFor(tour.id)]) }}
             </UButton>
           </li>
         </ul>
@@ -100,14 +94,27 @@ function launchLabel(tourId: string): string {
           {{ t('tutorial.prompt.decline') }}
         </UButton>
         <span v-else />
-        <UButton
-          color="neutral"
-          variant="soft"
-          data-testid="tutorial-close"
-          @click="tutorial.closePrompt()"
-        >
-          {{ undecided ? t('tutorial.prompt.later') : t('common.close') }}
-        </UButton>
+        <div class="flex items-center gap-2">
+          <!-- The way to the tours this board can't run yet, and to the ones already taken.
+               Browsing answers nothing, so it neither declines the offer nor accepts it. -->
+          <UButton
+            color="neutral"
+            variant="ghost"
+            icon="i-lucide-graduation-cap"
+            data-testid="tutorial-browse"
+            @click="tutorial.openCatalogue()"
+          >
+            {{ t('tutorial.prompt.browse') }}
+          </UButton>
+          <UButton
+            color="neutral"
+            variant="soft"
+            data-testid="tutorial-close"
+            @click="tutorial.closePrompt()"
+          >
+            {{ undecided ? t('tutorial.prompt.later') : t('common.close') }}
+          </UButton>
+        </div>
       </div>
     </template>
   </UModal>

package/app/composables/useNavContributions.ts

@@ -59,7 +59,10 @@ export function useNavContributions() {
     operatorDashboard: () => ui.openOperatorDashboard(),
     reports: () => ui.openReports(),
     shortcuts: () => ui.openShortcutsHelp(),
-    tutorial: () => useTutorialStore().openPrompt(),
+    // The CATALOGUE, not the launch prompt: reaching this from the sidebar or the palette is
+    // "show me the walkthroughs", and the prompt answers a narrower question (would you like
+    // one now?) that a returning user has already answered once.
+    tutorial: () => useTutorialStore().openCatalogue(),
     // No-op under an env pin (`setMode` refuses), so the palette entry matches the sidebar
     // switcher's read-only state rather than pretending to flip a tier the resolver fixes.
     toggleUiMode: () => useUiModeStore().toggleMode(),

package/app/composables/usePipelineErrorToast.ts

@@ -228,6 +228,10 @@ const CONFLICT_INFO: Record<Exclude<ConflictReason, BespokeConflictReason>, Conf
     titleKey: 'errors.conflict.title.binary_output_service_invalid',
     descriptionKey: 'errors.conflict.description.binary_output_service_invalid',
   },
+  binary_output_generator_invalid: {
+    titleKey: 'errors.conflict.title.binary_output_generator_invalid',
+    descriptionKey: 'errors.conflict.description.binary_output_generator_invalid',
+  },
   foundational_service_not_inherited: {
     titleKey: 'errors.conflict.title.foundational_service_not_inherited',
     descriptionKey: 'errors.conflict.description.foundational_service_not_inherited',

package/app/composables/useTutorialLaunch.ts

@@ -0,0 +1,50 @@
+import { launchActionFor, tourState } from '~/utils/tutorial'
+import type { TutorialLaunchAction, TutorialTourState } from '~/utils/tutorial'
+
+/**
+ * Starting a tour, from whichever surface offers it.
+ *
+ * Both the launch prompt and the catalogue answer the same question per tour — start it,
+ * resume where it was broken off, take it again, or step back into the one already running —
+ * and getting that precedence subtly different between the two surfaces would show up as the
+ * same button doing different things on two screens. So the decision is made once here, over
+ * the pure {@link tourState} / {@link launchActionFor} pair, and each surface renders it.
+ */
+export function useTutorialLaunch() {
+  const tutorial = useTutorialStore()
+
+  /** Where this tour stands for this user right now. */
+  function stateOf(tourId: string): TutorialTourState {
+    return tourState({
+      active: tutorial.activeTourId === tourId,
+      resumable: tutorial.interruptedAt(tourId) !== null,
+      completed: tutorial.isCompleted(tourId),
+    })
+  }
+
+  /** What this tour's button will do — also what labels it. */
+  function actionFor(tourId: string): TutorialLaunchAction {
+    return launchActionFor(stateOf(tourId))
+  }
+
+  /**
+   * Act on that. `continue` only steps out of the way: the overlay for that tour is already
+   * on screen, so restarting it from step one — which is what a plain `startTour` would do —
+   * would throw away the position of the walkthrough the user was pointing at.
+   */
+  function launch(tourId: string): void {
+    switch (actionFor(tourId)) {
+      case 'continue':
+        tutorial.closeCatalogue()
+        tutorial.closePrompt()
+        return
+      case 'resume':
+        tutorial.resumeTour(tourId)
+        return
+      default:
+        tutorial.startTour(tourId)
+    }
+  }
+
+  return { stateOf, actionFor, launch }
+}

package/app/composables/useTutorialTours.ts

@@ -1,18 +1,46 @@
 import { computed } from 'vue'
 import { useReactiveSlots } from '@modular-vue/runtime'
-import { sortTours } from '~/utils/tutorial'
-import type { TutorialTour } from '~/utils/tutorial'
+import { createSharedComposables } from '@modular-vue/vue'
+import { resolveTourCatalogue } from '~/utils/tutorial'
+import type { TutorialCatalogueEntry, TutorialTour } from '~/utils/tutorial'
+import type { AppDeps } from '~/modular/registry'
 import type { AppSlots } from '~/modular/nav-contributions'
 
 /**
- * The tours the current user may take: the merged `tutorialTours` slot (first-party +
- * consumer-contributed), already gated per tour by `navSlotFilter` (each tour's `when`
- * runs over the reactive gates service, so a permission flip shows/hides tours live),
- * in deterministic catalog order. The single source both the launch prompt and the
- * coach-mark overlay resolve tours from.
+ * The registered `gates` service — the SAME reactive object `navSlotFilter` reads, resolved
+ * from the modular app's shared dependencies rather than rebuilt here, so the tutorial
+ * surfaces and the nav can never disagree about what this board offers. Reading its getters
+ * inside a `computed` tracks the underlying stores, so availability re-resolves the instant a
+ * permission flips or a task lands on the board.
+ *
+ * `useOptional` (not `useService`) covers the bare-install case the nav filter also allows: a
+ * host that registered no gates withholds nothing rather than throwing.
+ */
+const { useOptional } = createSharedComposables<AppDeps>()
+
+/**
+ * The tutorial catalog as this board sees it, resolved ONCE for every surface that reads it.
+ *
+ * Two views over one resolution, and the difference between them is the point:
+ *
+ *  - `tours` — what can be started right now. The launch prompt offers these, and the overlay
+ *    resolves a running tour from them, exactly as when this gating lived in `navSlotFilter`.
+ *  - `catalogue` — EVERY tour this deployment ships, each carrying why it is or isn't
+ *    available. The catalogue surface needs the unavailable ones: a list that quietly omits
+ *    four of six tours is indistinguishable from a deployment that ships two, and the user it
+ *    fails is the one who came looking for the walkthrough they were told about.
+ *
+ * Gating cannot live in the slot filter for that reason — a `SlotFilter` maps slots to slots,
+ * so it can only drop, never annotate. `resolveTourCatalogue` is pure and does both.
  */
 export function useTutorialTours() {
   const slots = useReactiveSlots<AppSlots>()
-  const tours = computed<TutorialTour[]>(() => sortTours(slots.value.tutorialTours ?? []))
-  return { tours }
+  const gates = useOptional('gates')
+  const catalogue = computed<TutorialCatalogueEntry[]>(() =>
+    resolveTourCatalogue(slots.value.tutorialTours ?? [], gates.value),
+  )
+  const tours = computed<TutorialTour[]>(() =>
+    catalogue.value.filter((entry) => entry.availability === 'ready').map((entry) => entry.tour),
+  )
+  return { tours, catalogue }
 }

package/app/docs/consumer-extensions.md

@@ -236,17 +236,17 @@ re-deriving the "which run is this / how did the model do" facts. **Composables*
 **components** must be named through the `#components` virtual module (see the boxed note
 below). Compose these:
 
-| Building block                | Reference it as                           | What it gives you                                                                                                                                                                                                                                                                                                                                                                                                |
-| ----------------------------- | ----------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `ResultWindowShell`           | `#components` → `PanelsResultWindowShell` | The shared modal chrome for a result window — backdrop, header (icon/title/subtitle), a `#header-extras` slot, close button, and the modal _behaviour_ (focus-trap + return, body-scroll lock, shared-stack Escape via `useModalBehavior`). Pass `stepRef` to surface the shared "restart from here" control.                                                                                                    |
-| `StepRunMeta`                 | `#components` → `PanelsStepRunMeta`       | **The shared run-details metadata block** every agent window reuses: step position, live duration, model, run id, and the LLM model-activity rollup. Drop it into your window's sidebar — never reinvent run metadata.                                                                                                                                                                                           |
-| `MarkdownProse`               | `#components` → `CommonMarkdownProse`     | Render an agent's prose output as markdown.                                                                                                                                                                                                                                                                                                                                                                      |
-| `CopyButton`                  | `#components` → `CommonCopyButton`        | The shared copy-to-clipboard affordance.                                                                                                                                                                                                                                                                                                                                                                         |
-| `InspectorSection`            | `#components` → `PanelsInspectorSection`  | The collapsible inspector-section shell (chevron header, count, hint) so a consumer panel reads like a built-in one.                                                                                                                                                                                                                                                                                             |
-| `useResultView(id)`           | auto-imported                             | The window seam contract: `{ open, blockId, instanceId, stepIndex, close }` (+ an `onOpen` loader for windows that fetch, and an `onClose` flush). Escape is owned by the shell, not here.                                                                                                                                                                                                                       |
-| `useResultViewRunMeta(id, …)` | auto-imported                             | The `StepRunMeta` prop bundle (`{ step, instanceId, position, totalSteps, runFailed, failureAt }`), resolved for BOTH ways a window opens. A window reachable off-path — from a board card or the inspector — carries no `stepIndex`, so wiring `StepRunMeta` straight off `useResultView` leaves it blank on exactly that route; this resolves the block's live run and the step your view id declares instead. |
-| `usePanelSubject<T>()`        | `@modular-vue/core`                       | Read the block injected into an inspector panel by `<PanelsOutlet>`.                                                                                                                                                                                                                                                                                                                                             |
-| `useAppOverlays()`            | auto-imported                             | Open / close your own top-level overlays: `{ open(id, subject?), close(), active }`. The store-free seam a nav `run` closure uses to open an `appOverlays`-slot component (see "Top-level overlays").                                                                                                                                                                                                            |
+| Building block                | Reference it as                           | What it gives you                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
+| ----------------------------- | ----------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `ResultWindowShell`           | `#components` → `PanelsResultWindowShell` | The shared modal chrome for a result window — backdrop, header (icon/title/subtitle), a `#header-extras` slot, close button, and the modal _behaviour_ (focus-trap + return, body-scroll lock, shared-stack Escape via `useModalBehavior`). Pass `stepRef` to surface the shared "restart from here" control. It also renders the universal per-step trailing sections (agent effort, pre-PR validation, binary outputs) off the ACTIVE step, so your window inherits them and must not re-render them itself. |
+| `StepRunMeta`                 | `#components` → `PanelsStepRunMeta`       | **The shared run-details metadata block** every agent window reuses: step position, live duration, model, run id, and the LLM model-activity rollup. Drop it into your window's sidebar — never reinvent run metadata.                                                                                                                                                                                                                                                                                         |
+| `MarkdownProse`               | `#components` → `CommonMarkdownProse`     | Render an agent's prose output as markdown.                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| `CopyButton`                  | `#components` → `CommonCopyButton`        | The shared copy-to-clipboard affordance.                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
+| `InspectorSection`            | `#components` → `PanelsInspectorSection`  | The collapsible inspector-section shell (chevron header, count, hint) so a consumer panel reads like a built-in one.                                                                                                                                                                                                                                                                                                                                                                                           |
+| `useResultView(id)`           | auto-imported                             | The window seam contract: `{ open, blockId, instanceId, stepIndex, close }` (+ an `onOpen` loader for windows that fetch, and an `onClose` flush). Escape is owned by the shell, not here.                                                                                                                                                                                                                                                                                                                     |
+| `useResultViewRunMeta(id, …)` | auto-imported                             | The `StepRunMeta` prop bundle (`{ step, instanceId, position, totalSteps, runFailed, failureAt }`), resolved for BOTH ways a window opens. A window reachable off-path — from a board card or the inspector — carries no `stepIndex`, so wiring `StepRunMeta` straight off `useResultView` leaves it blank on exactly that route; this resolves the block's live run and the step your view id declares instead.                                                                                               |
+| `usePanelSubject<T>()`        | `@modular-vue/core`                       | Read the block injected into an inspector panel by `<PanelsOutlet>`.                                                                                                                                                                                                                                                                                                                                                                                                                                           |
+| `useAppOverlays()`            | auto-imported                             | Open / close your own top-level overlays: `{ open(id, subject?), close(), active }`. The store-free seam a nav `run` closure uses to open an `appOverlays`-slot component (see "Top-level overlays").                                                                                                                                                                                                                                                                                                          |
 
 > **Reference layer components through `#components`, not bare tags.** Nuxt auto-registers a
 > layer's components under a **path-derived** name (`components/panels/ResultWindowShell.vue`
@@ -270,6 +270,19 @@ below). Compose these:
 > Hardening these building blocks into an explicitly exported, location-independent public
 > surface is slice G of the initiative.
 
+### Don't render step state the shell already owns
+
+Some state the engine records on a step is deliberately NOT a result view's job, because the
+record's scope is wider than any one kind: the agent's effort self-assessment, the pre-PR
+validation report, and — for a `binary-output` generator — the artifacts it declared it stored
+(`step.binaryOutputs`). `ResultWindowShell` resolves the active step itself and renders each as a
+collapsible trailing section, and the generic step-detail panel renders the same components for a
+step whose kind declares no window at all.
+
+So a generator kind should declare a result view for its OWN output (or none), and leave the
+artifact list alone — you get it either way, on every entry point, with no id to register. A
+window that renders it again just shows it twice.
+
 The example `AcmeSecurityReport.vue` window is a full demonstration: it imports
 `ResultWindowShell` + `StepRunMeta` + `MarkdownProse` from `#components`, composes them with
 the auto-imported `useResultView`, adds only its own bespoke body (the security findings), and

package/app/modular/agent-kinds.ts

@@ -32,5 +32,11 @@ export function customKindToArchetype(kind: CustomAgentKind): AgentArchetype {
     // projection would fork the rule the moment the default changes.
     ...(p.tier ? { tier: p.tier } : {}),
     ...(p.resultView ? { resultView: p.resultView } : {}),
+    // Not part of `presentation` on the wire — it is a fact about how the kind RUNS, projected
+    // beside `container` — so it is lifted from the entry itself. Carried onto the archetype
+    // because the pipeline builder resolves a step's meta through `agentKindMeta`, not through
+    // the snapshot, and a required step option cannot be gated on something the read model
+    // does not carry.
+    ...(kind.binaryOutput ? { binaryOutput: true } : {}),
   }
 }

package/app/modular/nav-contributions.spec.ts

@@ -310,6 +310,7 @@ describe('nav grouping helpers', () => {
       'infrastructure',
       'workspaceContext',
       'configuration',
+      'help',
     ])
     // The model layer is its own section, ahead of the optional integrations: the engines,
     // the per-agent model choice (beside the providers it picks from, rather than under
@@ -332,6 +333,12 @@ describe('nav grouping helpers', () => {
       'operator-dashboard',
       'reports',
     ])
+    // The tail section: what teaches the product, rather than what configures it. It is on
+    // the sidebar at all because the launch prompt is answered once and the palette was then
+    // the only route back to the walkthroughs — asking the user least likely to have found
+    // the palette to find it.
+    const help = groups.find((g) => g.group === 'help')
+    expect(help?.items.map((i) => i.id)).toEqual(['tutorial'])
   })
 
   it('groupCommands preserves the pre-slice-1 workspace-group order', () => {

package/app/modular/nav-contributions.ts

@@ -1,5 +1,4 @@
 import { defineModule } from '@modular-vue/core'
-import { resolveTours } from '~/utils/tutorial'
 import { filterExternalTools } from './external-tools'
 import type { AppSlots } from './slots'
 
@@ -47,6 +46,11 @@ export type NavSurface = 'sidebar' | 'command' | 'toolbar'
  * dropped entirely where none are registered. It is separate from `integrations` for the same
  * reason `models` is — an integration is a system cat-factory READS FROM or WRITES TO on your
  * behalf, while these are places a person GOES.
+ *
+ * `help` is the tail section: surfaces that teach the product rather than configure it. It is
+ * separate from `configuration` because nothing in it changes what a run does — and it is a
+ * SIDEBAR section rather than a palette-only entry because the people it serves are the ones
+ * least likely to know the palette exists.
  */
 export type NavSidebarGroup =
   | 'create'
@@ -57,6 +61,7 @@ export type NavSidebarGroup =
   | 'workspaceContext'
   | 'externalTools'
   | 'configuration'
+  | 'help'
 
 /** Command-palette group (its i18n label is `layout.commandBar.groups.<group>`). */
 export type NavCommandGroup =
@@ -539,21 +544,27 @@ export const NAV_CONTRIBUTIONS: readonly NavContribution[] = [
     sidebar: { group: 'configuration', order: 45 },
   },
   {
-    // Deliberately NOT `advanced`: the tours exist for exactly the users basic mode serves,
-    // and the palette entry is the way back to them after the launch prompt was declined
-    // or dismissed. Ungated: every tour gates itself via its own `when` predicate, and the
-    // prompt is worth reaching even when it can only list some tours.
+    // Deliberately NOT `advanced`: the tutorials exist for exactly the users basic mode
+    // serves. It is on the SIDEBAR as well as in the palette because the launch prompt is
+    // shown once and answered once — after that, a palette entry was the only route back to
+    // the walkthroughs, which asks the user least likely to have found the palette to find
+    // it. Ungated: every tour answers for itself (an unavailable one is listed with what
+    // would unlock it), so the catalogue is worth reaching even when little of it can run.
     id: 'tutorial',
-    labelKey: 'layout.commandBar.cmd.tutorial',
+    labelKey: 'nav.tutorials',
     icon: 'i-lucide-graduation-cap',
-    surfaces: S('command'),
+    surfaces: S('sidebar', 'command'),
     action: 'tutorial',
     testId: 'nav-tutorial',
+    sidebar: { group: 'help', order: 10 },
     command: {
       // After the pre-slice-1 tail (the workspace group pins that order): genuinely new
       // entries append rather than interleave.
       group: 'workspace',
       order: 100,
+      // No `labelKey` override: the palette shows "Tutorials" too, so an override would be a
+      // second key holding the same word in ten locales — two places to keep in step and one
+      // of them free to drift. `layout.commandBar.cmd.tutorial` was deleted with it.
       keywordsKey: 'layout.commandBar.keywords.tutorial',
     },
   },
@@ -615,7 +626,6 @@ export const navigationModule = defineModule({
 export function navSlotFilter(slots: AppSlots, deps: { gates?: NavGates }): AppSlots {
   const gates = deps.gates
   const nav = slots.nav ?? []
-  const tutorialTours = slots.tutorialTours ?? []
   const externalTools = slots.externalTools ?? []
   return {
     ...slots,
@@ -626,11 +636,12 @@ export function navSlotFilter(slots: AppSlots, deps: { gates?: NavGates }): AppS
           (i) => (i.advanced ? gates.advancedMode : true) && (i.gate ? i.gate(gates) : true),
         )
       : nav,
-    // Tutorial tours gate over the same reactive service, so a tour about a surface the
-    // caller can't reach (e.g. creating tasks without board write) never shows, and a step
-    // about a branch this board isn't on is dropped rather than skipped (see `resolveTours`).
-    // Same gates-absent pass-through as `nav`.
-    tutorialTours: gates ? resolveTours(tutorialTours, gates) : tutorialTours,
+    // `tutorialTours` is deliberately NOT filtered here, unlike every other gated slot. A
+    // `SlotFilter` can only DROP, and the tutorial catalogue's whole job is to explain what
+    // was dropped — which tour this board can't run yet, and what would unlock it. That is a
+    // richer value than a thinned list, so tour resolution lives in `resolveTourCatalogue`
+    // (pure, gates-nullable) and runs once in `useTutorialTours`, whose `tours` is the same
+    // gated set the launch prompt and the overlay always saw.
     // External tools gate on the same two axes as `nav` — they become nav items downstream
     // (`useNavContributions` projects them), so gating them anywhere else would let a tool the
     // caller can't use reach the palette while its sidebar twin was correctly hidden.
@@ -650,6 +661,7 @@ export const SIDEBAR_GROUP_ORDER: readonly NavSidebarGroup[] = [
   // configuration tail: they are destinations someone reaches mid-work, not settings.
   'externalTools',
   'configuration',
+  'help',
 ]
 
 /** Command-palette groups, in render order; each label is `layout.commandBar.groups.<group>`. */

package/app/modular/slots.ts

@@ -37,8 +37,11 @@ import type { WorkspaceMetadataFieldDefinition } from './workspace-metadata'
  *  - `tutorialTours` — the in-app tutorial catalog ({@link TutorialTour}: data-only
  *    guided tours anchored to `data-testid`s, no components). First-party tours come
  *    from `modular/tutorial-tours.ts`; a consumer contributes its own to the same slot
- *    and they appear in the launch prompt beside the built-ins, gated per tour by its
- *    `when(gates)` predicate in the same reactive `slotFilter` that gates `nav`.
+ *    and they appear in the launch prompt and the tutorial catalogue beside the built-ins.
+ *    The one gated slot `navSlotFilter` does NOT filter: a tour's `requires` is resolved by
+ *    `resolveTourCatalogue` in `useTutorialTours` instead, because the catalogue must list
+ *    the tours this board can't run yet WITH what would unlock them — an annotation a
+ *    slots-to-slots filter cannot carry.
  *  - `externalTools` — the deployment's OWN web applications, listed in their own
  *    "External tools" sidebar section ({@link ExternalToolContribution}). Each entry resolves
  *    its URL from the invocation context (user, workspace, the custom metadata below), so the