@cat-factory/app 0.206.0 → 0.208.0

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

package/app/modular/tutorial-tours.spec.ts

@@ -7,9 +7,11 @@ import {
   TUTORIAL_TOURS,
   tutorialToursModule,
 } from '~/modular/tutorial-tours'
-import { resolveTourCatalogue, resolveTours } from '~/utils/tutorial'
+import { isLaunchOffer, resolveTourCatalogue, resolveTours } from '~/utils/tutorial'
 import { isSafeTargetId } from '~/components/tutorial/TutorialOverlay.logic'
-import type { NavGates } from '~/modular/nav-contributions'
+import { NAV_CONTRIBUTIONS, navItemVisible } from '~/modular/nav-contributions'
+import type { NavContribution, NavGates } from '~/modular/nav-contributions'
+import type { TutorialStep, TutorialTour } from '~/utils/tutorial'
 
 const ALL_GATES: NavGates = {
   canWriteBoard: true,
@@ -100,6 +102,90 @@ function declaredAnchors(): { label: string; id: string }[] {
   return out
 }
 
+/**
+ * Every step whose anchor IS a nav entry, paired with the contribution it points at.
+ *
+ * Those steps are the ones a tour's `requires` has to agree with, because the anchor only
+ * exists while the sidebar/palette renders that entry. An anchor that is NOT a nav entry (a
+ * control inside the modal the click opens) has no contribution to pair with and is left to
+ * the anchor guard above; `altTargets` are included, since a fallback anchor is reached on
+ * exactly the same terms as the primary one.
+ */
+function navAnchoredSteps(): {
+  tour: TutorialTour
+  step: TutorialStep
+  item: NavContribution
+  label: string
+}[] {
+  const byTestId = new Map(
+    NAV_CONTRIBUTIONS.flatMap((item) => (item.testId ? [[item.testId, item] as const] : [])),
+  )
+  return TUTORIAL_TOURS.flatMap((tour) =>
+    tour.steps.flatMap((step) =>
+      [step.target, ...(step.altTargets ?? [])].flatMap((target) => {
+        const item = target === undefined ? undefined : byTestId.get(target)
+        return item ? [{ tour, step, item, label: `${tour.id}/${step.id} -> ${item.id}` }] : []
+      }),
+    ),
+  )
+}
+
+/**
+ * Every combination of the {@link NavGates} booleans, yielded lazily so the 2^N gate sets are
+ * never all live at once.
+ *
+ * Enumerating rather than reasoning is deliberate. The pairing below is an IMPLICATION over
+ * gate sets — anything that satisfies a tour must also render its entry — between two
+ * predicates written independently in two files, and nothing about their shape is guaranteed
+ * (either may be a conjunction, a disjunction, or read a field the other doesn't). At fifteen
+ * fields the whole matrix costs milliseconds, which is a fair price for a guard that needs no
+ * assumption about how either side is spelled.
+ */
+function* everyGateSet(): Generator<NavGates> {
+  const keys = Object.keys(ALL_GATES) as (keyof NavGates)[]
+  for (let mask = 0; mask < 2 ** keys.length; mask++) {
+    const gates = {} as Record<keyof NavGates, boolean>
+    for (const [bit, key] of keys.entries()) gates[key] = (mask & (1 << bit)) !== 0
+    yield gates as NavGates
+  }
+}
+
+/** The gate fields a witness has turned OFF — the interesting half of a failure message. */
+function absentGates(gates: NavGates): readonly string[] {
+  return Object.entries(gates)
+    .filter(([, value]) => value === false)
+    .map(([key]) => key)
+}
+
+/**
+ * A gate set that OFFERS this tour while the entry its step clicks is NOT rendered, or
+ * `undefined` when no such set exists (what the guard wants). A step the gate set DROPS
+ * (`when`) needs no anchor, so it cannot be a counterexample.
+ *
+ * Of the many counterexamples one break produces, the one reported is the SMALLEST: the gate
+ * set closest to fully-permitted, so its absent fields are exactly the ones that matter. The
+ * first witness the matrix happens to reach names most of `NavGates` and reads as noise, which
+ * is the difference between a failure that says "declare `advancedMode`" and one that says
+ * "something about fourteen gates".
+ */
+function navRequirementDrift(
+  pair: ReturnType<typeof navAnchoredSteps>[number],
+): NavGates | undefined {
+  let smallest: NavGates | undefined
+  let fewestAbsent = Number.POSITIVE_INFINITY
+  for (const gates of everyGateSet()) {
+    if (!(pair.tour.requires ?? []).every((requirement) => requirement.met(gates))) continue
+    if (pair.step.when && !pair.step.when(gates)) continue
+    if (navItemVisible(pair.item, gates)) continue
+    const absent = absentGates(gates).length
+    if (absent < fewestAbsent) {
+      fewestAbsent = absent
+      smallest = gates
+    }
+  }
+  return smallest
+}
+
 /** Every static test id this layer actually renders. */
 function renderedTestIds(): Set<string> {
   const ids = new Set<string>()
@@ -190,14 +276,52 @@ describe('the built-in tutorial tour catalog', () => {
     expect(missing).toEqual([])
   })
 
+  it('requires, of every step that clicks a nav entry, whatever renders that entry', () => {
+    // The other drift guard, and the one the availability cases below CANNOT stand in for.
+    // Those assert this pairing by restating the permission in a hand-built gate set, which
+    // says nothing about the nav catalog: both edits that really break the pairing happen in
+    // `nav-contributions.ts` and touch no tour.
+    //
+    //  - an entry's `gate` gains a clause the tour doesn't require;
+    //  - an entry is marked `advanced: true`, which removes it from BASIC mode — and basic is
+    //    the SHIPPED DEFAULT, so the tour would then be offered to nearly every user and find
+    //    nothing.
+    //
+    // Both land on the same production failure: the tour is offered, hunts for an anchor that
+    // this user's sidebar never renders, skips the step (no `when`, so the miss COUNTS) and
+    // leaves them on a permanent "you missed N steps" notice about a walkthrough that could
+    // not have gone any other way. So the requirement is derived from the entry's OWN
+    // visibility rule (`navItemVisible`, the function `navSlotFilter` itself filters with)
+    // rather than spelled out a second time here.
+    const pairs = navAnchoredSteps()
+    // Guard the guard, twice over. A pairing that matched nothing would pass vacuously, and
+    // there is one per tour that opens a sidebar surface: `add-service` plus the four platform
+    // tours. And a gate field that is not a boolean would silently never vary across the
+    // matrix, leaving whatever it gates unexercised.
+    expect(pairs.length).toBeGreaterThanOrEqual(5)
+    expect(Object.values(ALL_GATES).every((value) => typeof value === 'boolean')).toBe(true)
+
+    const drifted = pairs.flatMap((pair) => {
+      const witness = navRequirementDrift(pair)
+      if (witness === undefined) return []
+      return [`${pair.label} is offered without ${absentGates(witness).join(' / ')}`]
+    })
+    expect(drifted).toEqual([])
+  })
+
   it('is contributed to the tutorialTours slot by the module', () => {
     expect(tutorialToursModule.slots?.tutorialTours).toEqual([...TUTORIAL_TOURS])
   })
 })
 
 describe('tour availability across the catalog', () => {
-  /** The ids a board can START right now — what the launch prompt offers. */
+  /** The ids a board can START right now — every startable tour, whatever offers it. */
   const ready = (gates: NavGates) => resolveTours(TUTORIAL_TOURS, gates).map((t) => t.id)
+  /** The narrower set the LAUNCH PROMPT asks about (`useTutorialTours().offered`). */
+  const offered = (gates: NavGates) =>
+    resolveTours(TUTORIAL_TOURS, gates)
+      .filter(isLaunchOffer)
+      .map((t) => t.id)
   /** The catalogue's own view: every tour, with what is holding each one back. */
   const entry = (gates: NavGates, tourId: string) =>
     resolveTourCatalogue(TUTORIAL_TOURS, gates).find((e) => e.tour.id === tourId)
@@ -207,14 +331,19 @@ describe('tour availability across the catalog', () => {
   })
 
   it('lists the whole catalog whatever the gates say, holding back rather than hiding', () => {
-    // The catalogue surface's contract. A fresh board can run two of the six walkthroughs;
-    // dropping the other four (all a slot filter could do) would misrepresent the product as
-    // shipping two, to exactly the user who came looking for the rest.
+    // The catalogue surface's contract. A fresh board can run the two delivery-loop tours that
+    // need no board state plus the whole platform half; dropping the rest (all a slot filter
+    // could do) would misrepresent the product as shipping fewer walkthroughs than it does, to
+    // exactly the user who came looking for them.
     const catalogue = resolveTourCatalogue(TUTORIAL_TOURS, FRESH_BOARD)
     expect(catalogue.map((e) => e.tour.id)).toEqual(TUTORIAL_TOURS.map((t) => t.id))
     expect(catalogue.filter((e) => e.availability === 'ready').map((e) => e.tour.id)).toEqual([
       'board-basics',
       'add-service',
+      'wire-models',
+      'design-pipeline',
+      'agent-standards',
+      'connect-systems',
     ])
   })
 
@@ -234,18 +363,68 @@ describe('tour availability across the catalog', () => {
   })
 
   it('offers a brand-new board the orientation tour AND the way out of being empty', () => {
-    // The state the launch prompt actually auto-opens in. Orientation alone would leave a
-    // new workspace with a tour of an empty canvas and no route to a first service, which
-    // is what `add-service` exists to fix — so it must survive exactly this gate set.
-    expect(ready(FRESH_BOARD)).toEqual(['board-basics', 'add-service'])
+    // The state the launch prompt actually auto-opens in, asserted on what it ASKS ABOUT.
+    // Orientation alone would leave a new workspace with a tour of an empty canvas and no route
+    // to a first service, which is what `add-service` exists to fix — so it must survive exactly
+    // this gate set. And nothing else may join it here: this is a modal with one question, and
+    // the platform tours are all startable on a fresh board (they need only a permission), so
+    // without the offer/library split they would bury both of these four-to-two.
+    expect(offered(FRESH_BOARD)).toEqual(['board-basics', 'add-service'])
+  })
+
+  it('keeps the platform tours in the catalogue rather than in the launch offer', () => {
+    // The split, stated as a table so promoting a tour into the first-launch question has to be
+    // written down here. The delivery loop is the arc a first-time user is answering about; the
+    // platform half is reference material they go and get from the catalogue, where it is listed,
+    // counted and startable exactly like the rest.
+    const LAUNCH_ARC = [
+      'board-basics',
+      'add-service',
+      'first-task',
+      'run-task',
+      'answer-park',
+      'review-merge',
+    ]
+    const CATALOGUE_ONLY = ['wire-models', 'design-pipeline', 'agent-standards', 'connect-systems']
+    expect(TUTORIAL_TOURS.filter(isLaunchOffer).map((t) => t.id)).toEqual(LAUNCH_ARC)
+    expect(TUTORIAL_TOURS.filter((t) => !isLaunchOffer(t)).map((t) => t.id)).toEqual(CATALOGUE_ONLY)
+    // Un-offered is not un-runnable: it thins the offer, never the library.
+    expect(ready(ALL_GATES)).toEqual(expect.arrayContaining(CATALOGUE_ONLY))
   })
 
   it('names the missing connection when no source control can list repositories', () => {
     const noSource: NavGates = { ...FRESH_BOARD, githubAvailable: false }
-    expect(ready(noSource)).toEqual(['board-basics'])
+    expect(offered(noSource)).toEqual(['board-basics'])
     expect(entry(noSource, 'add-service')?.unmet.map((r) => r.id)).toEqual(['source-control'])
   })
 
+  it('holds each platform tour back on the permission its own sidebar entry needs', () => {
+    // Every one of these tours clicks a sidebar entry as its second step, so its requirement has
+    // to be the SAME fact that renders the entry. A weaker one offers the tour to a user with no
+    // such control: it would hunt for the anchor, skip the rest and report itself abridged.
+    const member: NavGates = {
+      ...ALL_GATES,
+      canManageIntegrations: false,
+      canManageSettings: false,
+    }
+    expect(ready(member)).not.toContain('wire-models')
+    expect(ready(member)).not.toContain('connect-systems')
+    expect(ready(member)).not.toContain('agent-standards')
+    expect(entry(member, 'wire-models')?.unmet.map((r) => r.id)).toEqual(['integrations-manage'])
+    expect(entry(member, 'connect-systems')?.unmet.map((r) => r.id)).toEqual([
+      'integrations-manage',
+    ])
+    expect(entry(member, 'agent-standards')?.unmet.map((r) => r.id)).toEqual(['settings-manage'])
+    // A viewer keeps the builder tour out too: it opens a board-write surface.
+    expect(ready({ ...ALL_GATES, canWriteBoard: false })).not.toContain('design-pipeline')
+  })
+
+  it('names the disabled library when the deployment ships no fragment surface', () => {
+    const noLibrary: NavGates = { ...ALL_GATES, libraryAvailable: false }
+    expect(ready(noLibrary)).not.toContain('agent-standards')
+    expect(entry(noLibrary, 'agent-standards')?.unmet.map((r) => r.id)).toEqual(['library'])
+  })
+
   it('offers the run tour once a task exists, and the review tour once a run finished', () => {
     const withTask: NavGates = { ...FRESH_BOARD, boardHasService: true, boardHasTask: true }
     expect(ready(withTask)).toContain('run-task')