@cat-factory/app 0.207.0 → 0.208.1

package/app/components/tutorial/TutorialPrompt.vue

@@ -1,13 +1,15 @@
 <script setup lang="ts">
 // 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.
+// listing the first-run 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.
+// It is the OFFER, not the library: the full list — the platform walkthroughs that are kept out
+// of this question (`offeredAtLaunch: false`), plus the ones 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, and why it reads `offered` rather than
+// every startable tour.
 //
 // 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.
@@ -15,7 +17,7 @@ import { TUTORIAL_ACTION_KEYS } from '~/utils/tutorial'
 
 const { t } = useI18n()
 const tutorial = useTutorialStore()
-const { tours } = useTutorialTours()
+const { offered } = useTutorialTours()
 // Start / Resume / Repeat is decided in one place for both surfaces — see `useTutorialLaunch`.
 const { actionFor, launch } = useTutorialLaunch()
 
@@ -41,7 +43,7 @@ const undecided = computed(() => tutorial.decision === null)
         <p class="text-sm text-slate-300">{{ t('tutorial.prompt.intro') }}</p>
         <ul class="space-y-2">
           <li
-            v-for="tour in tours"
+            v-for="tour in offered"
             :key="tour.id"
             class="flex items-center gap-3 rounded-lg border border-slate-800 bg-slate-900/60 p-3"
           >
@@ -75,9 +77,15 @@ const undecided = computed(() => tutorial.decision === null)
             </UButton>
           </li>
         </ul>
-        <!-- Every tour gated away (e.g. a viewer on a write-only catalog): say so rather
-             than showing an unexplained empty list. -->
-        <p v-if="tours.length === 0" class="text-sm text-slate-400">
+        <!-- Every first-run tour gated away: say so rather than showing an unexplained empty
+             list. The copy points at the catalogue rather than declaring the deployment empty,
+             because with the split this state no longer implies there is nothing to take: what
+             is missing is the FIRST-RUN arc, and the catalogue-only walkthroughs gate on a
+             permission that this user may well hold. (Unreachable with the built-in catalog
+             alone, where `board-basics` requires nothing at all — but a consumer's own slot
+             filter can produce it, and "no tours exist" would be the wrong thing to say then.)
+             The footer's browse button is the way on, so it stays. -->
+        <p v-if="offered.length === 0" class="text-sm text-slate-400">
           {{ t('tutorial.prompt.empty') }}
         </p>
       </div>

package/app/composables/useTutorialTours.ts

@@ -1,7 +1,7 @@
 import { computed } from 'vue'
 import { useReactiveSlots } from '@modular-vue/runtime'
 import { createSharedComposables } from '@modular-vue/vue'
-import { resolveTourCatalogue } from '~/utils/tutorial'
+import { isLaunchOffer, resolveTourCatalogue } from '~/utils/tutorial'
 import type { TutorialCatalogueEntry, TutorialTour } from '~/utils/tutorial'
 import type { AppDeps } from '~/modular/registry'
 import type { AppSlots } from '~/modular/nav-contributions'
@@ -21,10 +21,13 @@ 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:
+ * Three views over one resolution, and the differences between them are 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`.
+ *  - `tours` — what can be started right now. The overlay resolves a running tour from these,
+ *    exactly as when this gating lived in `navSlotFilter`.
+ *  - `offered` — the subset the launch prompt asks about: startable AND part of the first-run
+ *    arc (see `TutorialTour.offeredAtLaunch`). The prompt is one answerable question, so it
+ *    stays the delivery loop even as the catalog grows to cover the platform surfaces.
  *  - `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
@@ -42,5 +45,6 @@ export function useTutorialTours() {
   const tours = computed<TutorialTour[]>(() =>
     catalogue.value.filter((entry) => entry.availability === 'ready').map((entry) => entry.tour),
   )
-  return { tours, catalogue }
+  const offered = computed<TutorialTour[]>(() => tours.value.filter(isLaunchOffer))
+  return { tours, offered, catalogue }
 }

package/app/docs/architecture.md

@@ -1,4 +1,4 @@
-# Frontend architecture — state & data flow
+# Frontend architecture: state & data flow
 
 How the SPA stays in sync with the backend. The app is a **thin client**: it holds
 no business logic, calls the Worker for every mutation, and hydrates its stores
@@ -14,11 +14,11 @@ REST (useApi)  ─────────────▶  Worker  ────
 stores (Pinia)  ◀── patch ──  useWorkspaceStream  ◀── WebSocket push (events hub)
 ```
 
-- **Read path** — the `workspace` store loads the full snapshot and fans it into
+- **Read path**: the `workspace` store loads the full snapshot and fans it into
   `board`, `pipelines`, `execution`, `spend`, etc.
-- **Write path** — components call `useApi` → Worker; the response (or a pushed
+- **Write path**: components call `useApi` → Worker; the response (or a pushed
   event) patches the relevant store. No optimistic business logic.
-- **Live path** — `useWorkspaceStream` opens one WebSocket to
+- **Live path**: `useWorkspaceStream` opens one WebSocket to
   `GET /workspaces/:ws/events?token=…`, patches `execution` / `agentRuns` /
   `board` as events arrive, and refreshes on reconnect to reconcile anything
   missed.

package/app/docs/consumer-extensions.md

@@ -1,14 +1,14 @@
 # Extending the SPA from a consumer deployment
 
 A deployment that consumes this layer (`extends: ['@cat-factory/app']`) can contribute
-its own **components** — result windows, navigation entries, inspector panels, agent-kind
-palette data — **without forking the layer**. This is the frontend counterpart of the
+its own **components** (result windows, navigation entries, inspector panels, agent-kind
+palette data) **without forking the layer**. This is the frontend counterpart of the
 backend's public registries (`registerAgentKind`, `registerGate`; see
 [`backend/docs/custom-agents.md`](../../../backend/docs/custom-agents.md)). The governing
 principle is the same: **zero host edits for a consumer extension**.
 
-A worked, end-to-end example ships in the template deployment —
-[`deploy/frontend/app/`](../../../deploy/frontend) (the `acme:security` module) — the
+A worked, end-to-end example ships in the template deployment:
+[`deploy/frontend/app/`](../../../deploy/frontend) (the `acme:security` module): the
 frontend analogue of the backend
 [`@cat-factory/example-custom-agent`](../../../backend/internal/example-custom-agent)
 package. Read this guide alongside it.
@@ -31,13 +31,13 @@ import AcmeSecurityReport from '../components/acme/AcmeSecurityReport.vue'
 export default defineNuxtPlugin(() => {
   registerAppModule(
     defineModule({
-      id: 'acme:security', // namespaced — see "Rules" below
+      id: 'acme:security', // namespaced - see "Rules" below
       version: '1.0.0',
       slots: {
         resultViews: [{ id: 'acme:security-report', component: AcmeSecurityReport }],
-        agentKinds: [/* palette entries — see "Agent kinds" */],
-        nav: [/* sidebar / command-palette destinations — see "Navigation" */],
-        inspectorPanels: [/* per-block detail panels — see "Inspector panels" */],
+        agentKinds: [/* palette entries - see "Agent kinds" */],
+        nav: [/* sidebar / command-palette destinations - see "Navigation" */],
+        inspectorPanels: [/* per-block detail panels - see "Inspector panels" */],
       },
     }),
   )
@@ -49,9 +49,9 @@ export default defineNuxtPlugin(() => {
 - **`enforce: 'post'` is load-bearing.** The layer's own install plugin is `enforce:
 'post'`, and Nuxt runs layer plugins before the consuming app's plugins within one
   enforce bucket. So your registration plugin must run in the **default** (or `pre`) bucket
-  — i.e. **do not** put `enforce: 'post'` on it, or it registers too late and is silently
+  , i.e. **do not** put `enforce: 'post'` on it, or it registers too late and is silently
   missed.
-- **`defineModule` / the slot-entry types come from `@modular-vue/core`** — add it to your
+- **`defineModule` / the slot-entry types come from `@modular-vue/core`**: add it to your
   deployment's `dependencies`.
 
 ## The landed seams
@@ -70,7 +70,7 @@ export default defineNuxtPlugin(() => {
 | Locale strings                      | (i18n)                    | `i18n/locales/*.json` in the deployment                                                          | `@nuxtjs/i18n` layer deep-merge                                           |
 
 A `nav` entry may also declare `advanced: true`, which hides it in **basic** interface mode
-(the shipped default) exactly as it does for the first-party destinations — see
+(the shipped default) exactly as it does for the first-party destinations: see
 [the layer README](../../README.md#interface-modes-basic--advanced). Use it for a power-user
 destination; the flag is independent of `gate`, so both must pass for the item to render.
 
@@ -80,7 +80,7 @@ Backend data selects a frontend component, joined by a namespaced id:
 
 1. A backend agent kind (registered on `AgentKindRegistry`, e.g.
    `@cat-factory/example-custom-agent`'s `security-auditor`) arrives in the workspace
-   snapshot with `presentation.resultView: '<ns>:<name>'` — **or** you code-ship the kind's
+   snapshot with `presentation.resultView: '<ns>:<name>'`: **or** you code-ship the kind's
    palette entry via the `agentKinds` slot (as the example does, to give an existing kind a
    bespoke window).
 2. You contribute the component to `resultViews` under the SAME id.
@@ -107,7 +107,7 @@ nullish subject (the boot-time validation resolve passes `null`).
 
 ### External tools + workspace metadata (`externalTools`, `workspaceMetadataFields`)
 
-Put your OWN web applications — a map editor, an asset pipeline, an admin console — in the
+Put your OWN web applications (a map editor, an asset pipeline, an admin console) in the
 sidebar's **External tools** section, and open each one _already scoped to what the user is
 looking at_. That second half is the point of the seam; a static link needs no registration.
 
@@ -132,25 +132,25 @@ workspaceMetadataFields: [{ key: 'gameId', label: 'Game id', placeholder: 'zork'
 ```
 
 - **`url` is a string or a RESOLVER** `(ctx) => string | null`. The context carries `userId`,
-  `userEmail`, `workspaceId`, `workspaceName` and `metadata` — the custom workspace fields you
+  `userEmail`, `workspaceId`, `workspaceName` and `metadata`: the custom workspace fields you
   declared. It is read at CLICK time, so a value a teammate fills in while the sidebar is open
   takes effect without a reload.
 - **Clicking opens a separate page** (`target=_blank`, `noopener`). The resolved URL must be
   `http(s)`: anything else is refused rather than handed to the browser, because the string
   reaches `window.open` and a `javascript:` URL would run in the SPA's own origin.
 - **Declare `requiredMetadata` for the fields your resolver needs.** An unconfigured workspace
-  then gets "fill in `gameId` on the Metadata tab" instead of a generic failure — and the tool
+  then gets "fill in `gameId` on the Metadata tab" instead of a generic failure, and the tool
   stays LISTED, because the person looking at the sidebar is usually the one who can fix it. A
   resolver that returns `null` reports separately ("this tool gave no address"), since that one
   is yours to fix, not the operator's.
 - **Treat every `ctx.metadata` value as untrusted input.** A workspace admin types these in, so a
-  value is operator-supplied text that happens to be length-bounded — not a constant you chose.
+  value is operator-supplied text that happens to be length-bounded, not a constant you chose.
   Set it as a query parameter or an `encodeURIComponent`'d path segment, as above. Never build the
   ORIGIN from one: `` `https://${ctx.metadata.region}.acme.dev` `` with `region` set to
   `evil.com/x?a=` resolves to a URL on someone else's host, and the `http(s)` allow-list cannot
   tell that apart from the link you meant.
 - **A resolver that THROWS costs only its own item.** It is caught and reported as a fourth
-  reason (`resolver-failed`) with the cause logged to the console — the sidebar, the palette and
+  reason (`resolver-failed`) with the cause logged to the console: the sidebar, the palette and
   the toolbar all render from one catalog, so an uncaught throw would otherwise blank all three.
   Do not rely on it: `requiredMetadata` is how you say a field must be there.
 - **`gate` and `advanced`** work exactly as on a `nav` entry; both must pass.
@@ -158,27 +158,27 @@ workspaceMetadataFields: [{ key: 'gameId', label: 'Game id', placeholder: 'zork'
 **The metadata half** is a deployment-declared FIELD list (here) whose VALUES are per workspace,
 typed in under _Workspace settings → Metadata_ and persisted on the workspace settings row. The
 tab appears only where a deployment declares fields. Keys must be identifier-shaped
-(`^[A-Za-z][A-Za-z0-9_.-]{0,63}$` — the backend refuses anything else); a malformed or duplicate
+(`^[A-Za-z][A-Za-z0-9_.-]{0,63}$`: the backend refuses anything else); a malformed or duplicate
 key is dropped with a dev-console warning rather than rendered. `type: 'select'` renders a picker
 over your `options`; everything is stored as a string.
 
 Two rules the editor keeps, and any other writer of the bag should too: a CLEARED field drops its
 key (so "unset" never reads as "set to nothing" in a resolver), and a save carries through any
-stored key the current build does not declare — the update replaces the whole bag, so a value
+stored key the current build does not declare; the update replaces the whole bag, so a value
 written under a field you have since retired must not be deleted by an unrelated save.
 
 Values are readable anywhere in the SPA via `useWorkspaceSettingsStore().settings.metadata`.
 
 ### Custom task types (`taskTypes`)
 
-Model a proprietary work item — an "incident", "pentest", "compliance-audit" — as a first-class
+Model a proprietary work item (an "incident", "pentest", "compliance-audit") as a first-class
 task type, the create-task twin of an agent kind. Contribute `{ taskType: '<ns>:<name>',
 presentation: { label, icon, color, description }, fields?, defaultPipelineId?, formPanel? }` to
 the `taskTypes` slot (see `acme:incident` in the example module). The SPA merges it into the
 create-task picker and the card-badge catalog:
 
 - **`presentation`** drives the create-task picker entry and the `TaskCard` type badge (resolved
-  through the pure `taskTypeMeta` read-model — the `agentKindMeta` twin). An UNREGISTERED
+  through the pure `taskTypeMeta` read-model: the `agentKindMeta` twin). An UNREGISTERED
   namespaced type (a stale row after your extension is removed) degrades to the `feature`
   presentation, so a leftover string never breaks a card.
 - **`fields`** are descriptor-driven create-form inputs (`text` / `textarea` / `number` /
@@ -198,20 +198,20 @@ task created with it round-trips with zero host edits.
 > (namespaced id, well-formed `formPanel`, a `defaultPipelineId` that resolves to a real pipeline).
 > A CODE-shipped `taskTypes` entry is trusted and **not** validated (like a code-shipped agent kind):
 > a malformed `taskType`/`formPanel` id or a `defaultPipelineId` naming no real pipeline fails
-> silently — the type just won't pre-select a pipeline and an unpaired `formPanel` degrades to the
+> silently; the type just won't pre-select a pipeline and an unpaired `formPanel` degrades to the
 > descriptor `fields`. Prefer backend registration when you want the fail-fast guardrail.
 
 ### Top-level overlays (`appOverlays`)
 
-A nav item's `run` closure — or any consumer code — often needs to open a full-screen panel of
+A nav item's `run` closure, or any consumer code, often needs to open a full-screen panel of
 its own: a dashboard, a wizard, a settings surface. The layer's first-party modals are
 hand-mounted in `pages/index.vue`, which a consumer can't edit, so the `appOverlays` slot + the
 single `<AppOverlayHost>` are the seam:
 
 1. Contribute `{ id: '<ns>:<name>', component }` to the `appOverlays` slot (see
    `acme:security-dashboard-overlay` in the example module).
-2. Open it from anywhere with the auto-imported `useAppOverlays().open('<ns>:<name>', subject?)`
-   — typically a nav item's `run` closure. The optional `subject` is any value your overlay
+2. Open it from anywhere with the auto-imported `useAppOverlays().open('<ns>:<name>', subject?)`:
+   typically a nav item's `run` closure. The optional `subject` is any value your overlay
    renders against (e.g. a block id); it reaches the component as a `subject` prop.
 3. `<AppOverlayHost>` resolves the slot with `resolveComponentRegistry` (the same pick-one
    primitive `resultViews` uses) and mounts the matching component, wiring its `close` emit to
@@ -219,16 +219,16 @@ single `<AppOverlayHost>` are the seam:
 
 It is a **pick-one** host: opening a second overlay replaces the first, and `close()` clears it.
 Compose the shared `ResultWindowShell` (via `#components`) for chrome so your overlay inherits
-focus-trap / scroll-lock / shared-stack Escape — emit `close` from its `@close`. A dangling open
-(`open('<ns>:x')` with no registered component — e.g. a stale closure after the extension was
+focus-trap / scroll-lock / shared-stack Escape: emit `close` from its `@close`. A dangling open
+(`open('<ns>:x')` with no registered component, e.g. a stale closure after the extension was
 removed) degrades to nothing (a dev-console warning names the id), never a crash. Duplicate ids
 across modules throw at boot, like every other slot.
 
 > **Scope.** This seam is for CONSUMER overlays. The layer's own ~34 first-party modals stay
-> hand-mounted in `index.vue` and are migrated only opportunistically — don't reach for
+> hand-mounted in `index.vue` and are migrated only opportunistically: don't reach for
 > `appOverlays` to replace a first-party fast-path modal.
 
-## Reuse the shared building blocks — don't reinvent them
+## Reuse the shared building blocks: don't reinvent them
 
 The layer ships window/inspector primitives you compose instead of hand-rolling chrome or
 re-deriving the "which run is this / how did the model do" facts. **Composables** (and the
@@ -236,25 +236,25 @@ 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. 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").                                                                                                                                                                                                                                                                                                          |
+| 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`
 > → `PanelsResultWindowShell`), and only rewrites bare `<ResultWindowShell>` tags inside the
 > layer's own SFCs. A bare tag in a **consumer** SFC resolves to nothing and silently renders
-> as an unknown element — its `<slot>` children still appear, so a shallow test can pass while
+> as an unknown element: its `<slot>` children still appear, so a shallow test can pass while
 > the shared chrome (and its `data-testid`) never mounts. Import the ones you use from
-> `#components` (Nuxt's stable virtual registry — **not** a deep path into the layer's
+> `#components` (Nuxt's stable virtual registry: **not** a deep path into the layer's
 > `app/components/*`), aliasing them back to the short names for readable templates:
 >
 > ```ts
@@ -274,13 +274,13 @@ below). Compose these:
 
 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
+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
+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
@@ -293,19 +293,19 @@ reads the auditor's structured assessment straight off `step.custom`.
 Ship your strings under your own namespace in the deployment's `i18n/locales/*.json` (e.g.
 `acme.*`). `@nuxtjs/i18n` is layer-aware and **deep-merges** them into the layer catalog, so
 `t('acme.securityReport.title')` resolves in your components with no config change. The
-layer's typed-key and locale-parity guards govern only the layer's own keys — your namespace
+layer's typed-key and locale-parity guards govern only the layer's own keys: your namespace
 is yours.
 
 ## Rules that hold across every seam
 
 - **Namespacing.** Every consumer-authored id is `<ns>:<name>`. Built-ins are never
-  shadowable — the merge logic drops a consumer entry whose id collides with a built-in
+  shadowable: the merge logic drops a consumer entry whose id collides with a built-in
   (see the agents store).
 - **Fail fast at boot, degrade at runtime.** Duplicate ids across first-party + consumer
   modules throw when the layer resolves the merged slots at startup; missing pairings and
   unknown wire ids degrade with a dev-console warning, never a crash.
 - **Never crash on stale data.** An id that arrives on the wire (a `resultView`, an agent
-  kind) after its extension was removed must degrade to a defined rendering — extensions get
+  kind) after its extension was removed must degrade to a defined rendering: extensions get
   uninstalled while persisted rows outlive them.
 - **The remote manifest is DATA only.** Components never travel the wire; per-workspace
   variability comes from which capabilities the snapshot lists, not from which modules are

package/app/modular/nav-contributions.ts

@@ -609,16 +609,32 @@ export const navigationModule = defineModule({
   slots: { nav: [...NAV_CONTRIBUTIONS] },
 })
 
+/**
+ * Does a shell render this contribution under `gates`?
+ *
+ * The two axes a destination is gated on, in ONE place. They are independent and BOTH must
+ * pass: an `advanced` item is dropped in basic mode, and every item still answers to its own
+ * `gate`. Order doesn't matter (it's a conjunction) but the tier is checked first, since it's
+ * the cheaper read.
+ *
+ * Named rather than inlined in {@link navSlotFilter} because a second reader has to agree with
+ * it exactly: a tutorial tour whose step CLICKS a nav entry declares the requirement that
+ * renders it, and `tutorial-tours.spec.ts` pairs the two through this function. Spelling the
+ * conjunction out there instead would be a copy that keeps passing while this one changes —
+ * and the drift it would miss (an entry gaining a gate clause, or being marked `advanced` and
+ * so leaving the DEFAULT interface tier) is precisely a tour offered to a user who then finds
+ * no such control.
+ */
+export function navItemVisible(item: NavContribution, gates: NavGates): boolean {
+  return (item.advanced ? gates.advancedMode : true) && (item.gate ? item.gate(gates) : true)
+}
+
 /**
  * Reactive RBAC/availability/interface-tier filter over the merged `nav` slot. Reads
  * `deps.gates.*` (the reactive gate service) per item, so evaluated inside
  * `useReactiveSlots` it re-runs when a permission, connection, or the interface
  * mode flips. Passed to `installModularApp` as the global `slotFilter`.
  *
- * The two axes are independent and BOTH must pass: an `advanced` item is dropped in
- * basic mode, and every item still answers to its own `gate`. Order doesn't matter
- * (it's a conjunction) but the tier is checked first, since it's the cheaper read.
- *
  * Typed against `AppSlots` (not the generic `SlotFilter`) so it matches the
  * filter shape the runtime infers for this registry. `deps` is widened to an
  * optional `gates` to avoid importing `AppDeps` (which would be circular).
@@ -631,11 +647,7 @@ export function navSlotFilter(slots: AppSlots, deps: { gates?: NavGates }): AppS
     ...slots,
     // No gates service wired (tests / bare install) ⇒ show everything, matching
     // the dev-open "absent access allows all" backend parity.
-    nav: gates
-      ? nav.filter(
-          (i) => (i.advanced ? gates.advancedMode : true) && (i.gate ? i.gate(gates) : true),
-        )
-      : nav,
+    nav: gates ? nav.filter((i) => navItemVisible(i, gates)) : nav,
     // `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