@cat-factory/app 0.273.2 → 0.275.0

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

@@ -10,7 +10,8 @@ import {
   SIDEBAR_GROUP_ORDER,
   sortToolbar,
 } from './nav-contributions'
-import type { AppSlots, NavGates } from './nav-contributions'
+import type { AppSlots, NavGatedContribution, NavGates } from './nav-contributions'
+import type { ExternalToolContribution } from './external-tools'
 
 /** Prove every referenced key resolves in the layer's base catalog (see `test/i18nKeys`). */
 const hasKey = hasI18nKey
@@ -25,9 +26,11 @@ const NO_GATES: NavGates = {
   infrastructureAvailable: false,
   accountsEnabled: false,
   isAccountAdmin: false,
-  // The permission axis is what these cases vary; keep the interface tier at `advanced`
-  // so a dropped item is unambiguously an RBAC/availability drop, not a tier drop.
+  // The permission axis is what these cases vary; keep the interface tier at `advanced` and the
+  // role at the full surface, so a dropped item is unambiguously an RBAC/availability drop rather
+  // than a tier or role drop.
   advancedMode: true,
+  fullSurface: true,
   boardHasService: false,
   boardHasTask: false,
   boardHasRun: false,
@@ -48,6 +51,7 @@ const ALL_GATES: NavGates = {
   accountsEnabled: true,
   isAccountAdmin: true,
   advancedMode: true,
+  fullSurface: true,
   boardHasService: true,
   boardHasTask: true,
   boardHasRun: true,
@@ -185,6 +189,76 @@ describe('navSlotFilter', () => {
     }
   })
 
+  it('drops every non-intake destination for a narrowed role', () => {
+    const gates: NavGates = { ...ALL_GATES, fullSurface: false }
+    const kept = ids(navSlotFilter(slots(), { gates }))
+    const intakeOnly = NAV_CONTRIBUTIONS.filter((i) => i.intake).map((i) => i.id)
+    expect(kept.sort()).toEqual(intakeOnly.sort())
+    // Fully permitted and on the advanced tier, so every drop here is the ROLE and nothing else:
+    // the platform configuration goes, and what teaches the product plus the way out stays.
+    expect(kept).toContain('tutorial')
+    expect(kept).toContain('ui-role')
+    expect(kept).not.toContain('build-pipeline')
+    expect(kept).not.toContain('add-from-repo')
+    expect(kept).not.toContain('integrations-hub')
+    expect(kept).not.toContain('workspace-settings')
+    expect(kept).not.toContain('model-providers')
+    expect(kept).not.toContain('account-settings')
+    // A narrowed sidebar is short by design, but never a shell with nothing in it: the sidebar
+    // is where the tutorials live, and `groupSidebar` drops an empty section upstream, so a
+    // surface whose every item was palette-only would render as a broken navbar.
+    const groups = groupSidebar((navSlotFilter(slots(), { gates }) as AppSlots).nav)
+    expect(groups.length).toBeGreaterThan(0)
+    for (const group of groups) expect(group.items.length).toBeGreaterThan(0)
+  })
+
+  it('states, per intake item, why the narrowed role keeps it', () => {
+    // The mirror of the advanced-item table above, and it earns its place for the opposite
+    // reason: `intake` is opt-IN, so the risk is not a silent capability loss but a silent
+    // WIDENING: one flag on a destination that configures the platform and the simplified
+    // surface has quietly stopped being simple. The table is the claim; adding `intake: true`
+    // fails here until the reason is written down.
+    const REASON: Record<string, string> = {
+      tutorial: 'the walkthroughs - the surface with the fewest destinations needs them most',
+      'keyboard-shortcuts': 'the cheatsheet covers the board and the palette, which every role has',
+      'ui-role': 'the way BACK out of the narrowed role',
+    }
+    const intake = NAV_CONTRIBUTIONS.filter((i) => i.intake).map((i) => i.id)
+    expect(intake.sort()).toEqual(Object.keys(REASON).sort())
+    for (const [id, why] of Object.entries(REASON)) {
+      expect(why.length, `${id} has no stated reason`).toBeGreaterThan(0)
+    }
+  })
+
+  it('keeps the role switch reachable from inside the narrowed role, and the tier switch out', () => {
+    // The role decides which surfaces exist at all, so its own entry must survive the narrowing
+    // it causes, or a designer who needs a pipeline has no route to say so.
+    const roleItem = NAV_CONTRIBUTIONS.find((i) => i.id === 'ui-role')
+    expect(roleItem?.intake).toBe(true)
+    expect(roleItem?.gate).toBeUndefined()
+    // The TIER toggle is deliberately the other way: a narrowed role's tier is capped at basic
+    // (`resolveUiMode`), so an entry that flipped it would write a preference nothing honours.
+    expect(NAV_CONTRIBUTIONS.find((i) => i.id === 'ui-mode')?.intake).toBeUndefined()
+
+    const gates: NavGates = { ...NO_GATES, fullSurface: false }
+    const kept = ids(navSlotFilter(slots(), { gates }))
+    expect(kept).toContain('ui-role')
+    expect(kept).not.toContain('ui-mode')
+  })
+
+  it('keeps the tier, role and permission axes independent, and all three must pass', () => {
+    // `tutorial` is `intake` and ungated, `sandbox` is advanced + permissioned + not intake:
+    // no single axis reveals the second, and narrowing the role cannot reveal anything.
+    const narrowedButPermitted: NavGates = { ...ALL_GATES, fullSurface: false }
+    expect(ids(navSlotFilter(slots(), { gates: narrowedButPermitted }))).not.toContain('sandbox')
+
+    const fullButBasic: NavGates = { ...ALL_GATES, advancedMode: false }
+    expect(ids(navSlotFilter(slots(), { gates: fullButBasic }))).not.toContain('sandbox')
+
+    const fullButUnpermitted: NavGates = { ...NO_GATES, canManageIntegrations: false }
+    expect(ids(navSlotFilter(slots(), { gates: fullButUnpermitted }))).not.toContain('sandbox')
+  })
+
   it('keeps the tier switch itself reachable in basic mode', () => {
     // Basic is the shipped default, so this palette entry is how a user who never finds the
     // (icon-only, in the basic rail) sidebar switcher gets to the advanced half at all. Marking
@@ -226,26 +300,107 @@ describe('navSlotFilter', () => {
 })
 
 describe('navSlotFilter external tools', () => {
-  const tools = [
-    { id: 'acme:a', title: 'A', icon: 'i-lucide-link', url: 'https://a.dev' },
-    {
-      id: 'acme:b',
-      title: 'B',
-      icon: 'i-lucide-link',
-      url: 'https://b.dev',
-      gate: (g: NavGates) => g.canManageIntegrations,
-    },
+  const tool = (id: string, axes: NavGatedContribution = {}): ExternalToolContribution => ({
+    id,
+    title: id,
+    icon: 'i-lucide-link',
+    url: `https://${id}.dev`,
+    ...axes,
+  })
+  const tools: ExternalToolContribution[] = [
+    tool('acme:open'),
+    tool('acme:permissioned', { gate: (g: NavGates) => g.canManageIntegrations }),
+    tool('acme:power-user', { advanced: true }),
+    tool('acme:intake', { intake: true }),
   ]
+  const withTools = (): AppSlots => ({ ...slots(), externalTools: [...tools] })
   const toolIds = (s: unknown) => (s as AppSlots).externalTools.map((t) => t.id)
 
   it('gates registered tools in the SAME filter as the nav catalog', () => {
     // 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.
-    const withTools = (): AppSlots => ({ ...slots(), externalTools: [...tools] })
-    expect(toolIds(navSlotFilter(withTools(), { gates: ALL_GATES }))).toEqual(['acme:a', 'acme:b'])
-    expect(toolIds(navSlotFilter(withTools(), { gates: NO_GATES }))).toEqual(['acme:a'])
-    expect(toolIds(navSlotFilter(withTools(), {}))).toEqual(['acme:a', 'acme:b'])
+    expect(toolIds(navSlotFilter(withTools(), { gates: ALL_GATES }))).toEqual(
+      tools.map((t) => t.id),
+    )
+    expect(toolIds(navSlotFilter(withTools(), { gates: NO_GATES }))).toEqual([
+      'acme:open',
+      'acme:power-user',
+      'acme:intake',
+    ])
+    // No gates service wired (tests, a bare install): everything passes, matching the dev-open
+    // "absent access allows all" parity the nav half keeps.
+    expect(toolIds(navSlotFilter(withTools(), {}))).toEqual(tools.map((t) => t.id))
+  })
+
+  it('drops a tool that has not opted into the intake surface', () => {
+    // The axis a separate external-tools filter used to miss entirely: a `designer` kept the
+    // deployment's whole External tools section while every first-party destination around it
+    // was hidden, which inverts the opt-in default rather than merely leaking one entry.
+    const narrowed: NavGates = { ...ALL_GATES, fullSurface: false }
+    expect(toolIds(navSlotFilter(withTools(), { gates: narrowed }))).toEqual(['acme:intake'])
+  })
+
+  it('keeps a tool and a nav entry declaring the same axes in lockstep', () => {
+    // The structural half, and the one a per-slot case cannot make: both slots run the same
+    // predicate today, so assert the PROPERTY that makes that worth keeping. A future axis
+    // wired into one slot and not the other fails here, whatever the axis turns out to be.
+    const AXES: NavGatedContribution[] = [
+      {},
+      { advanced: true },
+      { intake: true },
+      { gate: (g: NavGates) => g.canManageIntegrations },
+      { advanced: true, intake: true },
+      { advanced: true, gate: (g: NavGates) => g.canManageIntegrations },
+      { intake: true, gate: (g: NavGates) => g.canManageIntegrations },
+      { advanced: true, intake: true, gate: (g: NavGates) => g.canManageIntegrations },
+    ]
+
+    for (const [index, axes] of AXES.entries()) {
+      const id = `twin-${index}`
+      const paired = (gates: NavGates) => {
+        const filtered = navSlotFilter(
+          {
+            ...slots(),
+            nav: [
+              {
+                id,
+                labelKey: 'nav.kaizen',
+                icon: 'i-lucide-link',
+                surfaces: ['command'] as const,
+                ...axes,
+              },
+            ],
+            externalTools: [tool(id, axes)],
+          },
+          { gates },
+        ) as AppSlots
+        return {
+          nav: filtered.nav.some((i) => i.id === id),
+          tool: filtered.externalTools.some((t) => t.id === id),
+        }
+      }
+
+      // Every setting of the three gate fields these axes read; the rest of `NavGates` is
+      // invariant here, so varying it would only restate the same eight verdicts.
+      for (const advancedMode of [true, false]) {
+        for (const fullSurface of [true, false]) {
+          for (const canManageIntegrations of [true, false]) {
+            const gates: NavGates = {
+              ...ALL_GATES,
+              advancedMode,
+              fullSurface,
+              canManageIntegrations,
+            }
+            const verdict = paired(gates)
+            expect(
+              verdict.tool,
+              `${JSON.stringify(axes)} under ${JSON.stringify({ advancedMode, fullSurface, canManageIntegrations })}`,
+            ).toBe(verdict.nav)
+          }
+        }
+      }
+    }
   })
 })
 
@@ -348,7 +503,10 @@ describe('nav grouping helpers', () => {
   it('groupCommands preserves the pre-slice-1 workspace-group order', () => {
     const workspace = groupCommands(NAV_CONTRIBUTIONS).find((g) => g.group === 'workspace')
     // Same order the old CommandBar pushed them in (parity, not a reorder), with genuinely
-    // new entries appended after it rather than interleaved.
+    // new entries appended after it rather than interleaved. `ui-role` is the one deliberate
+    // exception, and it changes no existing entry's RELATIVE position: it sits beside `ui-mode`
+    // because the two answer one question ("how much of the app do I see"), and a user who finds
+    // one has found the other.
     expect(workspace?.items.map((ci) => ci.item.id)).toEqual([
       'fragments',
       'merge-thresholds',
@@ -359,6 +517,7 @@ describe('nav grouping helpers', () => {
       'sandbox',
       'keyboard-shortcuts',
       'ui-mode',
+      'ui-role',
       'tutorial',
       'foundational-services',
     ])

package/app/modular/nav-contributions.ts

@@ -1,5 +1,4 @@
 import { defineModule } from '@modular-vue/core'
-import { filterExternalTools } from './external-tools'
 import type { AppSlots } from './slots'
 
 // Re-exported for the slice-1 importers that reach `AppSlots` through this
@@ -111,6 +110,18 @@ export interface NavGates {
    * available to a `gate` predicate that needs to combine it with something else.
    */
   advancedMode: boolean
+  /**
+   * The person's ROLE sees the whole product (`stores/uiRole.ts`): true for `engineer` and
+   * `product-manager`, false for the `intake` surface a `designer` gets.
+   *
+   * Read by {@link navSlotFilter} for every item that does NOT declare
+   * {@link NavContribution.intake}, i.e. the narrowing is opt-IN for the small surface rather
+   * than opt-out for the large one. Stated positively (a role that sees everything, not a
+   * "restricted" flag) for the same reason `advancedMode` is: this is the third axis a
+   * contribution answers to, and one of the three reading inverted is a destination shown to
+   * exactly the person it was hidden from.
+   */
+  fullSurface: boolean
   /**
    * The open board has at least one service frame. Availability, not permission: a
    * surface that operates ON a service (today the task-creation tutorial tour) has
@@ -206,12 +217,50 @@ export const NAV_ACTIONS = [
   'shortcuts',
   'tutorial',
   'toggleUiMode',
+  'chooseRole',
 ] as const
 
 export type NavActionId = (typeof NAV_ACTIONS)[number]
 
+/**
+ * The axes a rendered destination answers to, and the whole of what {@link navItemVisible}
+ * reads. Extended by {@link NavContribution} and by an external tool
+ * (`modular/external-tools.ts`), which is projected onto a nav item downstream.
+ *
+ * Shared as an interface rather than restated per contribution kind, so the two cannot declare
+ * different axes. That is not hypothetical: the role axis first landed on `NavContribution`
+ * alone, and external tools went on rendering for a role every first-party destination was
+ * hidden from. A fourth axis added here is one a tool must answer too, and the typecheck plus
+ * the single predicate are what say so.
+ */
+export interface NavGatedContribution {
+  /** Reactive predicate over {@link NavGates}; absent = always visible. */
+  gate?: (g: NavGates) => boolean
+  /**
+   * A power-user destination: shown only in ADVANCED interface mode (basic mode is the
+   * everyday surface — see `stores/uiMode.ts`). Declarative rather than folded into
+   * {@link gate}, so an item keeps its RBAC/availability predicate unchanged and the two
+   * axes stay independently assertable. Absent = visible in both tiers.
+   */
+  advanced?: boolean
+  /**
+   * Offered on the INTAKE surface: the narrowed set a `designer` role gets (see
+   * `utils/uiRole.ts`). Absent = the full-surface roles only.
+   *
+   * Opt-in, and that direction is the point: a destination added later defaults to the roles
+   * that configure the platform, so a new entry can never quietly widen the simplified surface:
+   * the cost of getting it wrong is one flag, where the other default is a persona that stopped
+   * being simple without anyone deciding to un-simplify it. Independent of {@link advanced} and
+   * of {@link gate}: all three must pass.
+   *
+   * A deployment's own external tool declares it the same way, and defaults the same way: a
+   * registered application is platform surface until somebody says it is intake surface.
+   */
+  intake?: boolean
+}
+
 /** One destination, declared once and rendered per surface. */
-export interface NavContribution {
+export interface NavContribution extends NavGatedContribution {
   id: string
   /** Default (sidebar) label i18n key. */
   labelKey: string
@@ -225,15 +274,6 @@ export interface NavContribution {
   description?: string
   icon: string
   surfaces: readonly NavSurface[]
-  /** Reactive predicate over {@link NavGates}; absent = always visible. */
-  gate?: (g: NavGates) => boolean
-  /**
-   * A power-user destination: shown only in ADVANCED interface mode (basic mode is the
-   * everyday surface — see `stores/uiMode.ts`). Declarative rather than folded into
-   * {@link gate}, so an item keeps its RBAC/availability predicate unchanged and the two
-   * axes stay independently assertable. Absent = visible in both tiers.
-   */
-  advanced?: boolean
   /**
    * First-party action id, resolved to a `run()` against the host `ui` store by
    * `useNavContributions`. A consumer module that has its own stores instead
@@ -292,6 +332,13 @@ const S = (...s: NavSurface[]) => s as readonly NavSurface[]
  * (`fragments`), the ephemeral-env + runner plumbing (`infrastructure`, which is also the only route
  * to the guided per-service Compose environment setup), and the workspace/model configuration
  * a run actually reads (`workspace-settings`, `model-config`).
+ *
+ * `intake: true` marks the OTHER axis (see `utils/uiRole.ts`): the three entries a narrowed role
+ * keeps. It is opt-in, and the set is short on purpose, because the intake surface brings work IN and
+ * watches it, and every destination here that is not `tutorial`, `keyboard-shortcuts` or
+ * `ui-role` configures the platform the work runs on. What that role creates instead lives on the
+ * BOARD (a frame's add-task / from-ticket / from-design buttons), which is why dropping nearly
+ * the whole sidebar costs it nothing it is there to do.
  */
 export const NAV_CONTRIBUTIONS: readonly NavContribution[] = [
   {
@@ -575,6 +622,10 @@ export const NAV_CONTRIBUTIONS: readonly NavContribution[] = [
     labelKey: 'nav.tutorials',
     icon: 'i-lucide-graduation-cap',
     surfaces: S('sidebar', 'command'),
+    // On the intake surface too, and it is the surface that needs it most: a narrowed role has
+    // the fewest destinations to learn the product from, and the delivery-loop tours are exactly
+    // the ones it can take (the platform half gates on the full surface: see `tutorial-tours.ts`).
+    intake: true,
     action: 'tutorial',
     testId: 'nav-tutorial',
     sidebar: { group: 'help', order: 10 },
@@ -594,6 +645,9 @@ export const NAV_CONTRIBUTIONS: readonly NavContribution[] = [
     labelKey: 'layout.commandBar.cmd.shortcuts',
     icon: 'i-lucide-keyboard',
     surfaces: S('command'),
+    // Help, like the tutorials: the cheatsheet describes the board and the palette, which every
+    // role has, and nothing it lists is a destination the intake surface hides.
+    intake: true,
     action: 'shortcuts',
     command: {
       group: 'workspace',
@@ -611,6 +665,10 @@ export const NAV_CONTRIBUTIONS: readonly NavContribution[] = [
     labelKey: 'layout.commandBar.cmd.toggleUiMode',
     icon: 'i-lucide-toggle-right',
     surfaces: S('command'),
+    // Deliberately NOT `intake`: a narrowed role's tier is CAPPED at basic (see `resolveUiMode`),
+    // so this entry would flip a preference the resolver then ignores, the same lie the sidebar
+    // switcher refuses to be under an env pin. The way out of a narrowed role is the entry below,
+    // which changes the surface for real.
     action: 'toggleUiMode',
     command: {
       group: 'workspace',
@@ -618,6 +676,25 @@ export const NAV_CONTRIBUTIONS: readonly NavContribution[] = [
       keywordsKey: 'layout.commandBar.keywords.toggleUiMode',
     },
   },
+  {
+    // The way BACK from a narrowed role, and the reason the intake surface is safe to ship: the
+    // role decides which surfaces exist at all, so a person who picked `designer` and then needs
+    // a pipeline has to be able to say so from inside that surface. Palette-only because the
+    // sidebar already carries the switcher itself (`UiRoleSwitcher`, above the destinations it
+    // gates, in EVERY role) rather than a shortcut to this question, the same relationship
+    // `ui-mode` has with the tier switcher.
+    id: 'ui-role',
+    labelKey: 'layout.commandBar.cmd.chooseRole',
+    icon: 'i-lucide-user-round-cog',
+    surfaces: S('command'),
+    intake: true,
+    action: 'chooseRole',
+    command: {
+      group: 'workspace',
+      order: 95,
+      keywordsKey: 'layout.commandBar.keywords.chooseRole',
+    },
+  },
 ]
 
 /**
@@ -633,21 +710,25 @@ export const navigationModule = defineModule({
 /**
  * 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.
+ * The three axes a destination is gated on, in ONE place. They are independent and ALL must
+ * pass: an `advanced` item is dropped in basic mode, an item that is not `intake` is dropped for
+ * a narrowed role, and every item still answers to its own `gate`. Order doesn't matter (it's a
+ * conjunction) but the two flag reads come first, since they're the cheaper ones.
  *
- * Named rather than inlined in {@link navSlotFilter} because a second reader has to agree with
+ * Named rather than inlined in {@link navSlotFilter} because other readers have 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 —
+ * conjunction out anywhere else 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)
+export function navItemVisible(item: NavGatedContribution, gates: NavGates): boolean {
+  return (
+    (item.advanced ? gates.advancedMode : true) &&
+    (gates.fullSurface || item.intake === true) &&
+    (item.gate ? item.gate(gates) : true)
+  )
 }
 
 /**
@@ -675,10 +756,12 @@ export function navSlotFilter(slots: AppSlots, deps: { gates?: NavGates }): AppS
     // 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.
-    externalTools: filterExternalTools(externalTools, gates),
+    // A deployment's external tools run through the SAME predicate as `nav`, on the same line
+    // shape, because they become nav items downstream (`useNavContributions` projects them):
+    // gating them by any other expression lets a tool reach the palette while its first-party
+    // neighbours are correctly hidden. That is exactly what a separate `filterExternalTools`
+    // spelling its own conjunction did when the role axis landed.
+    externalTools: gates ? externalTools.filter((t) => navItemVisible(t, gates)) : externalTools,
   }
 }
 

package/app/modular/nav-gates.ts

@@ -15,8 +15,9 @@ import type { NavGates } from '~/modular/nav-contributions'
  *
  * This mirrors the exact gating the pre-slice-1 `SideBar` computeds encoded (see
  * `useWorkspaceAccess` for the dev-open "absent access ⇒ allow all" parity), plus
- * the interface tier (`advancedMode`), which rides the same service so a mode flip
- * re-gates all three shells through the same reactive path as a permission flip.
+ * the interface tier (`advancedMode`) and the person's role (`fullSurface`), which ride
+ * the same service so a mode or role flip re-gates all three shells through the same
+ * reactive path as a permission flip.
  */
 export function createNavGates(): NavGates {
   const access = useWorkspaceAccess()
@@ -27,6 +28,7 @@ export function createNavGates(): NavGates {
   const auth = useAuthStore()
   const providerConnections = useProviderConnectionsStore()
   const uiMode = useUiModeStore()
+  const uiRole = useUiRoleStore()
   const board = useBoardStore()
   const execution = useExecutionStore()
   const reviews = useReviewStage()
@@ -108,6 +110,13 @@ export function createNavGates(): NavGates {
     get advancedMode() {
       return uiMode.isAdvanced
     },
+    // The role axis rides the same reactive service as the tier, so picking a role re-gates all
+    // three shells through one path. It is not a permission: every item it keeps is still gated
+    // by its own `gate`, and every item it drops is one the caller may well be allowed to open,
+    // which is why the switcher out of a narrowed role is itself `intake`.
+    get fullSurface() {
+      return uiRole.fullSurface
+    },
     get boardHasService() {
       return hasService.value
     },

package/app/modular/registry.spec.ts

@@ -14,6 +14,7 @@ const NO_GATES: NavGates = {
   accountsEnabled: false,
   isAccountAdmin: false,
   advancedMode: false,
+  fullSurface: false,
   boardHasService: false,
   boardHasTask: false,
   boardHasRun: false,

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

@@ -24,6 +24,7 @@ const ALL_GATES: NavGates = {
   accountsEnabled: true,
   isAccountAdmin: true,
   advancedMode: true,
+  fullSurface: true,
   boardHasService: true,
   boardHasTask: true,
   boardHasRun: true,
@@ -140,9 +141,10 @@ function navAnchoredSteps(): {
  * 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.
+ * (either may be a conjunction, a disjunction, or read a field the other doesn't). The matrix
+ * doubles with every field {@link NavGates} gains, so the cost is worth re-measuring rather than
+ * quoting from here: at the field count this spec runs against today it is a fraction of a
+ * second, 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)[]

package/app/modular/tutorial-tours.ts

@@ -130,6 +130,17 @@ export const TUTORIAL_REQUIREMENTS = {
     labelKey: 'tutorial.requirements.advancedTier',
     met: (gates) => gates.advancedMode,
   },
+  // The other SPA-narrowing axis, and it is a requirement for exactly the same reason the tier is:
+  // a narrowed ROLE (`utils/uiRole.ts`) keeps only the `intake` nav entries, so every tour whose
+  // step CLICKS one of the others would be offered to a designer and then hunt for a sidebar entry
+  // their screen does not render. Which tours those are is not a judgement call: it is the pairing
+  // `tutorial-tours.spec.ts` derives from `navItemVisible`, so a tour that gains a nav-anchored
+  // step fails there until this is declared.
+  fullSurface: {
+    id: 'full-surface',
+    labelKey: 'tutorial.requirements.fullSurface',
+    met: (gates) => gates.fullSurface,
+  },
   // The platform half's requirements. Each mirrors, exactly, the `gate` of the sidebar entry the
   // tour clicks (`nav-model-providers` / `nav-integrations`, `nav-fragments`). A requirement
   // WEAKER than the gate of the control a step points at offers the tour to a user who has no
@@ -204,15 +215,33 @@ export const TUTORIAL_TOURS: readonly TutorialTour[] = [
         titleKey: 'tutorial.tours.boardBasics.steps.toolbar.title',
         bodyKey: 'tutorial.tours.boardBasics.steps.toolbar.body',
       },
+      {
+        // The role decides which surfaces exist at all, so the orientation tour names it before
+        // the tier it caps. No `when`: the switcher is rendered in EVERY role (it is the way back
+        // out of the narrowed one), which is exactly why the tour can always point at it.
+        id: 'role',
+        target: 'ui-role-switcher',
+        altTargets: ['ui-role-toggle'],
+        placement: 'right',
+        titleKey: 'tutorial.tours.boardBasics.steps.role.title',
+        bodyKey: 'tutorial.tours.boardBasics.steps.role.body',
+      },
       {
         // Basic mode is the shipped default, and it HIDES a whole half of the product
         // (sandbox, Kaizen, bootstrap, the operator surfaces). A user who never finds the
         // switcher never learns that half exists, so the orientation tour is the one place
         // that has to name it — the switcher is deliberately visible in both tiers for the
         // same reason (see `nav-contributions.ts`).
+        //
+        // `when` rather than a tour-level requirement, and rather than nothing: a narrowed role's
+        // tier is CAPPED at basic, so the sidebar drops this switcher, and a step that merely
+        // missed its anchor would be reported as an abridged tour, which is the wrong thing to say
+        // about a control that is absent because of a choice the user made. Gating the whole tour
+        // would be worse still: orientation is the one walkthrough every role should get.
         id: 'interfaceTier',
         target: 'ui-mode-switcher',
         altTargets: ['ui-mode-toggle'],
+        when: (gates) => gates.fullSurface,
         placement: 'right',
         titleKey: 'tutorial.tours.boardBasics.steps.interfaceTier.title',
         bodyKey: 'tutorial.tours.boardBasics.steps.interfaceTier.body',
@@ -236,7 +265,11 @@ export const TUTORIAL_TOURS: readonly TutorialTour[] = [
     // repo is a board write against a connected source, and in basic interface mode
     // add-from-repo is the ONLY route (bootstrap is advanced), which is what makes this
     // worth a tour rather than a hint.
-    requires: [TUTORIAL_REQUIREMENTS.boardWrite, TUTORIAL_REQUIREMENTS.sourceControl],
+    requires: [
+      TUTORIAL_REQUIREMENTS.boardWrite,
+      TUTORIAL_REQUIREMENTS.sourceControl,
+      TUTORIAL_REQUIREMENTS.fullSurface,
+    ],
     steps: [
       {
         id: 'intro',
@@ -668,7 +701,7 @@ export const TUTORIAL_TOURS: readonly TutorialTour[] = [
     // onboarding advisory, which the launch prompt stands down for) — this is for the person who
     // meets the question later, or who wants to know where the answer lives.
     offeredAtLaunch: false,
-    requires: [TUTORIAL_REQUIREMENTS.integrationsManage],
+    requires: [TUTORIAL_REQUIREMENTS.integrationsManage, TUTORIAL_REQUIREMENTS.fullSurface],
     steps: [
       {
         id: 'intro',
@@ -712,7 +745,7 @@ export const TUTORIAL_TOURS: readonly TutorialTour[] = [
     // change. A user who never finds the builder treats the built-in catalog as the product's
     // fixed shape and works around it in task descriptions instead.
     offeredAtLaunch: false,
-    requires: [TUTORIAL_REQUIREMENTS.boardWrite],
+    requires: [TUTORIAL_REQUIREMENTS.boardWrite, TUTORIAL_REQUIREMENTS.fullSurface],
     steps: [
       {
         id: 'intro',
@@ -774,7 +807,11 @@ export const TUTORIAL_TOURS: readonly TutorialTour[] = [
     // How you steer output without restating your conventions in every task description, which
     // is what people do instead when they never find this.
     offeredAtLaunch: false,
-    requires: [TUTORIAL_REQUIREMENTS.library, TUTORIAL_REQUIREMENTS.settingsManage],
+    requires: [
+      TUTORIAL_REQUIREMENTS.library,
+      TUTORIAL_REQUIREMENTS.settingsManage,
+      TUTORIAL_REQUIREMENTS.fullSurface,
+    ],
     steps: [
       {
         id: 'intro',
@@ -813,7 +850,7 @@ export const TUTORIAL_TOURS: readonly TutorialTour[] = [
     // Each integration changes what a run can SEE or SAY, and none of them announces itself:
     // a board with no tracker linked simply never mentions that issues could arrive on their own.
     offeredAtLaunch: false,
-    requires: [TUTORIAL_REQUIREMENTS.integrationsManage],
+    requires: [TUTORIAL_REQUIREMENTS.integrationsManage, TUTORIAL_REQUIREMENTS.fullSurface],
     steps: [
       {
         id: 'intro',
@@ -854,7 +891,7 @@ export const TUTORIAL_TOURS: readonly TutorialTour[] = [
     // itself, and the cost of not finding it is a run that fails on provisioning with a banner
     // pointing at a window the user has never opened.
     offeredAtLaunch: false,
-    requires: [TUTORIAL_REQUIREMENTS.infrastructure],
+    requires: [TUTORIAL_REQUIREMENTS.infrastructure, TUTORIAL_REQUIREMENTS.fullSurface],
     steps: [
       {
         id: 'intro',
@@ -906,7 +943,11 @@ export const TUTORIAL_TOURS: readonly TutorialTour[] = [
     // workspace that has never made a group renders nothing for the anchored step to find. The
     // guard only pairs a tour against the visibility of a NAV entry, so a section hiding itself
     // one level in is exactly the case that has to be declared by hand.
-    requires: [TUTORIAL_REQUIREMENTS.settingsManage, TUTORIAL_REQUIREMENTS.advancedTier],
+    requires: [
+      TUTORIAL_REQUIREMENTS.settingsManage,
+      TUTORIAL_REQUIREMENTS.advancedTier,
+      TUTORIAL_REQUIREMENTS.fullSurface,
+    ],
     steps: [
       {
         id: 'intro',
@@ -950,7 +991,11 @@ export const TUTORIAL_TOURS: readonly TutorialTour[] = [
     // renders the entry this tour clicks. Declared rather than assumed: `navRequirementDrift`
     // enumerates the whole gate matrix against that entry's own visibility rule and fails
     // without it.
-    requires: [TUTORIAL_REQUIREMENTS.settingsManage, TUTORIAL_REQUIREMENTS.advancedTier],
+    requires: [
+      TUTORIAL_REQUIREMENTS.settingsManage,
+      TUTORIAL_REQUIREMENTS.advancedTier,
+      TUTORIAL_REQUIREMENTS.fullSurface,
+    ],
     steps: [
       {
         id: 'intro',