@cat-factory/app 0.273.2 → 0.275.0

package/README.md

@@ -15,6 +15,7 @@ The SPA source lives under `app/` (the Nuxt srcDir).
 - [What it is](#what-it-is)
 - [Tech stack](#tech-stack)
 - [Layout](#layout)
+- [Roles (engineer / product manager / designer)](#roles-engineer--product-manager--designer)
 - [Interface modes (basic / advanced)](#interface-modes-basic--advanced)
 - [Agent tiers (basic / intermediate / advanced)](#agent-tiers-basic--intermediate--advanced)
 - [In-app tutorial tours](#in-app-tutorial-tours)
@@ -239,6 +240,70 @@ surface rather than a toast, and are tracked as G4 in
 
 A status → chip map feeding a `<UBadge :color="…">` types its values as `BadgeColor` (`utils/badge.ts`), which is derived from `UBadge`'s own prop type rather than restated as a literal union. Typed `string`, the binding does not compile and the reflex is `as any` at each call site: seven of them had accumulated. That cast also accepts a colour Nuxt UI does not define, which renders as an unstyled badge with nothing failing.
 
+## Roles (engineer / product manager / designer)
+
+The outermost of the three narrowing axes, and the only one the app **asks about**: on a first-ever
+launch it puts up one question, "what do you work on?", offering `engineer`, `product-manager` and
+`designer` with a line each on what picking it gives you. Vocabulary, resolution and the
+presentation table are in `app/utils/uiRole.ts`; the choice and its once-per-session prompt live in
+the `uiRole` store.
+
+Two roles, three names. `engineer` and `product-manager` both map to the **`full`** surface, and
+that is the product decision rather than an oversight: the two do the same job in this app (plan
+work on a board, run it, review and merge it), and what makes the question answerable is the copy a
+person recognises themselves in. `designer` maps to **`intake`**: the services already on the board,
+the work in flight on them, and the routes that bring new work IN (a new task, a task from a tracker
+ticket, a task from a design). None of the platform configuration behind that. They are separate
+`UiRole` members precisely so one of them can gain a surface the other does not without a migration.
+
+- **The default is the FULL surface, and an unanswered question changes nothing.** Closing the prompt
+  writes no choice, so the next launch asks again and the person keeps the whole product in the
+  meantime. There is deliberately no "don't ask me again": an unanswered question costs nothing,
+  where a wrongly-recorded one costs somebody destinations they need. It is also why the prompt
+  yields to every startup advisory (and why the tour offer, in turn, yields to it: the role decides
+  which surfaces exist, so a tour picked ahead of it could be about half a product).
+- **It is not authorization.** Workspace RBAC (ADR 0025) decides what a request may do and is
+  enforced server-side; this decides what the SPA OFFERS, and every role's surface is still gated by
+  the caller's permissions on top. Nothing here can widen what a person may do, and everything it
+  hides is something they may well be allowed to open, which is why the **way back is reachable from
+  inside the narrowed role**: the switcher at the top of the sidebar (rendered in every role) plus a
+  command-palette entry, both `intake`.
+- **There is NO deployment env pin**, unlike the interface tier. Which tier a fleet of kiosk-ish
+  deployments shows is a decision an operator can reasonably make; which JOB the person at the
+  keyboard does is not something a build can know.
+- **A narrowed role CAPS the interface tier at basic** (`resolveUiMode` takes the surface and answers
+  `basic` for `intake`, ahead of the env pin). Resolved rather than merely hidden, so every
+  `isAdvanced` reader inside a surface agrees with the narrowed nav without restating the role, and
+  the tier switcher is dropped for that role: a control that flipped a tier the resolver fixes would
+  be the same lie it refuses to be under an env pin.
+
+The seams, and what a new feature should use rather than reading the store ad hoc:
+
+- **A nav destination** declares `intake: true` in `app/modular/nav-contributions.ts` to survive a
+  narrowed role. It is **opt-in**, so a destination added later defaults to the full-surface roles:
+  getting that wrong costs one flag, where the other default is a persona that stopped being simple
+  without anyone deciding to un-simplify it. Today's set is three (`tutorial`,
+  `keyboard-shortcuts`, `ui-role`), and `nav-contributions.spec.ts` pins it against a table naming
+  each one's reason, so adding a fourth forces the claim to be written down. The `fullSurface` gate
+  rides the same reactive `NavGates` service as `advancedMode`, so a role switch re-gates all three
+  shells with no reload; all three axes (role, tier, `gate`) must pass.
+- **A deployment's own external tool** declares the same flag, and defaults the same way. The three
+  axes live on one `NavGatedContribution` that both `NavContribution` and `ExternalToolContribution`
+  extend, and `navSlotFilter` runs the one `navItemVisible` over both slots, because a tool is
+  projected onto a nav contribution downstream. A tool filtered by any other expression is a
+  registered application that outlives the narrowing every destination beside it obeys, which is how
+  the role axis first shipped; `nav-contributions.spec.ts` pins the two slots' verdicts in lockstep
+  across the axes rather than trusting the two spellings to stay equal.
+- **A surface that narrows inline** reads `useUiRoleStore().fullSurface` (the frame header's bug-hunt
+  button, the palette's per-connection integration commands). Same rule as the tier: what remains
+  must be exactly what the full surface would have shown, only less of it.
+- **A tutorial tour whose step clicks a non-`intake` nav entry declares
+  `TUTORIAL_REQUIREMENTS.fullSurface`.** Which tours those are is not a judgement call:
+  `tutorial-tours.spec.ts` derives the pairing from `navItemVisible`, so a tour that gains such a
+  step fails until the requirement is declared. A single STEP that the role removes (the orientation
+  tour's interface-tier step) declares `when` instead, so it is dropped rather than reported as an
+  abridged tour.
+
 ## Interface modes (basic / advanced)
 
 The SPA renders at one of two **interface tiers**. `basic` (the default) is the everyday
@@ -247,6 +312,8 @@ options that only exist to override a workspace-level default are left at that d
 the nav is trimmed to what that loop needs. `advanced` shows everything. The tier resolves in
 a fixed order, first match wins:
 
+0. **The [role](#roles-engineer--product-manager--designer)'s surface**, as a ceiling: an `intake`
+   role renders `basic` whatever the two below say.
 1. **`NUXT_PUBLIC_UI_MODE`** (`basic` | `advanced`): the deployment pin. Like
    `NUXT_PUBLIC_API_BASE` it is baked in at **build** time (`ssr: false`), and while it is
    set the in-app switcher is a read-only indicator, since a preference the resolver ignores
@@ -274,8 +341,8 @@ hoc where it can be avoided:
 
 - **A nav destination** declares `advanced: true` in `app/modular/nav-contributions.ts`. The
   shared `navSlotFilter` drops it in basic mode across all three shells (sidebar, command
-  palette, toolbar), independently of its RBAC `gate`: both must pass. A consumer module's
-  own contributions take the same flag. The bar is **whether the everyday delivery loop needs
+  palette, toolbar), independently of its RBAC `gate` and of the role's `intake` flag: all
+  three must pass. A consumer module's own contributions take the same flag. The bar is **whether the everyday delivery loop needs
   it**, and marking an item does one of two distinguishable things:
   - **Reached another way**; a shortcut whose surface a basic destination also opens, so
     nothing is lost (the Merge / Service-best-practices palette entries into Workspace

package/app/components/board/nodes/BlockNode.vue

@@ -26,6 +26,7 @@ const services = useServicesStore()
 const reviews = useReviewStage()
 const access = useWorkspaceAccess()
 const uiMode = useUiModeStore()
+const uiRole = useUiRoleStore()
 const { t } = useI18n()
 const { lod } = useSemanticZoom()
 // Coarse-pointer (touch) bumps the frame-header actions from `xs` to `sm` so
@@ -460,8 +461,13 @@ const ITEM_ICON: Record<string, string> = {
                   :title="t('board.frame.createInitiativeTitle')"
                   @click.stop="createInitiative"
                 />
+                <!-- Hunting a tracker board for a bug worth adopting is TRIAGE, not intake: it
+                     rates open bugs against each other and picks one to take on, which is the
+                     engineer/PM judgement call. So it is dropped for a narrowed role, whose three
+                     routes in (a new task, a task from a named ticket, a task from a design) all
+                     start from work somebody has already decided to do. -->
                 <UButton
-                  v-if="tasks.anyOffered"
+                  v-if="tasks.anyOffered && uiRole.fullSurface"
                   class="nodrag"
                   data-testid="frame-hunt-bugs"
                   :size="isTouch ? 'sm' : 'xs'"

package/app/components/layout/CommandBar.vue

@@ -24,6 +24,7 @@ const documents = useDocumentsStore()
 const tasks = useTasksStore()
 const library = useFragmentLibraryStore()
 const access = useWorkspaceAccess()
+const uiRole = useUiRoleStore()
 
 // The static destination catalog + its RBAC/availability gating now comes from
 // the shared nav manifest (backend/docs/adr/0049-modular-vue-adoption.md, slice 1),
@@ -44,8 +45,14 @@ const activeIndex = ref(0)
 // carry: their label (connect vs manage) and set (one per document/task source)
 // depend on live connection state. Gated by `integrations.manage`, they render
 // under the palette's Integrations group.
+//
+// Also gated on the ROLE's surface, which the manifest entries get for free from `navSlotFilter`
+// (see `NavGates.fullSurface`): these are the platform-configuration half: connecting a source,
+// managing a connection, importing across the whole board. A narrowed role that happens to
+// hold `integrations.manage` would otherwise reach through the palette exactly the surfaces its
+// sidebar dropped. What it keeps is on the board: a frame's own from-ticket / from-design buttons.
 const dynamicIntegrationCommands = computed<Command[]>(() => {
-  if (!access.canManageIntegrations.value) return []
+  if (!access.canManageIntegrations.value || !uiRole.fullSurface) return []
   const groupIntegrations = t('layout.commandBar.groups.integrations')
   const list: Command[] = []
   if (github.available) {

package/app/components/layout/NotificationsInbox.vue

@@ -32,6 +32,9 @@ const META: Record<Notification['type'], { icon: string; color: Accent }> = {
   merge_tag_request: { icon: 'i-lucide-tag', color: 'primary' },
   ci_failed: { icon: 'i-lucide-triangle-alert', color: 'error' },
   test_failed: { icon: 'i-lucide-flask-conical', color: 'error' },
+  // The deploy-fixer gave up on an environment that would not come up. Same disposition as
+  // `ci_failed`: the run failed, and "act" retries it once the files are fixed.
+  deploy_blocked: { icon: 'i-lucide-server-off', color: 'error' },
   // Clicking the title opens the review window for the task (see `reveal`); "act" just marks
   // it read (the server performs no side-effect for this type).
   requirement_review: { icon: 'i-lucide-clipboard-list', color: 'primary' },
@@ -97,6 +100,7 @@ const ACTION_KEYS: Record<Notification['type'], string> = {
   merge_tag_request: 'layout.notifications.action.merge_tag_request',
   ci_failed: 'layout.notifications.action.ci_failed',
   test_failed: 'layout.notifications.action.test_failed',
+  deploy_blocked: 'layout.notifications.action.deploy_blocked',
   requirement_review: 'layout.notifications.action.requirement_review',
   clarity_review: 'layout.notifications.action.clarity_review',
   release_regression: 'layout.notifications.action.release_regression',

package/app/components/layout/RolePrompt.vue

@@ -0,0 +1,75 @@
+<script setup lang="ts">
+// The first-run role question: asks once what the person is here to do, so the SPA can open on
+// the surfaces that job needs. Offered at launch (at most once per session, and only until it is
+// answered: see `stores/uiRole.ts`) and re-openable at any time from the command palette.
+//
+// It states what each role GIVES you rather than only naming it, because the narrowed role
+// genuinely removes destinations: a person picking blind would either avoid the choice or make it
+// and not know what happened to their sidebar. Same reason the footer names the way back.
+//
+// Closing without picking writes nothing: the role stays the default (the FULL surface), and the
+// next launch asks again. There is deliberately no "don't ask me again": an unanswered question
+// costs nothing here, where a wrongly-recorded answer costs a person destinations they need.
+import { ROLE_PRESENTATION, UI_ROLES, type UiRole } from '~/utils/uiRole'
+
+const { t } = useI18n()
+const uiRole = useUiRoleStore()
+
+const open = computed({
+  get: () => uiRole.promptOpen,
+  set: (v: boolean) => (v ? uiRole.openPrompt() : uiRole.closePrompt()),
+})
+
+function pick(role: UiRole) {
+  uiRole.setRole(role)
+}
+</script>
+
+<template>
+  <UModal v-model:open="open" :title="t('uiRole.prompt.title')" :ui="{ content: 'max-w-lg' }">
+    <template #body>
+      <div class="space-y-4" data-testid="role-prompt">
+        <p class="text-sm text-slate-300">{{ t('uiRole.prompt.intro') }}</p>
+        <div class="space-y-2">
+          <button
+            v-for="role in UI_ROLES"
+            :key="role"
+            type="button"
+            :data-testid="`role-option-${role}`"
+            :aria-pressed="role === uiRole.role && uiRole.chosen"
+            class="flex w-full items-center gap-3 rounded-lg border p-3 text-start transition"
+            :class="
+              role === uiRole.role && uiRole.chosen
+                ? 'border-indigo-500/60 bg-indigo-500/10'
+                : 'border-slate-800 bg-slate-900/60 hover:border-slate-600 hover:bg-slate-800/60'
+            "
+            @click="pick(role)"
+          >
+            <UIcon :name="ROLE_PRESENTATION[role].icon" class="h-5 w-5 shrink-0 text-primary-400" />
+            <div class="min-w-0 flex-1">
+              <div class="text-sm font-medium text-slate-100">
+                {{ t(ROLE_PRESENTATION[role].labelKey) }}
+              </div>
+              <p class="text-xs text-slate-400">{{ t(ROLE_PRESENTATION[role].hintKey) }}</p>
+            </div>
+          </button>
+        </div>
+        <!-- The choice is not a commitment, and saying so is what makes the narrowed role
+             pickable: it is one dropdown at the top of the sidebar to leave again. -->
+        <p class="text-[11px] leading-snug text-slate-500">{{ t('uiRole.prompt.change') }}</p>
+      </div>
+    </template>
+    <template #footer>
+      <div class="flex w-full justify-end">
+        <UButton
+          color="neutral"
+          variant="soft"
+          data-testid="role-prompt-close"
+          @click="uiRole.closePrompt()"
+        >
+          {{ uiRole.chosen ? t('common.close') : t('uiRole.prompt.later') }}
+        </UButton>
+      </div>
+    </template>
+  </UModal>
+</template>

package/app/components/layout/SideBar.vue

@@ -6,15 +6,16 @@
 // context-fragment library, and workspace configuration (merge thresholds +
 // default models).
 //
-// Two orthogonal ways this panel shrinks. WHICH destinations exist is the interface
-// TIER (basic hides the `advanced` contributions, filtered upstream in `navSlotFilter`);
-// how much room they take is the COLLAPSE state (the icon-only rail). Basic mode starts
-// railed, but either can be changed independently from the tier switcher at the top /
-// the rail toggle.
+// Three orthogonal ways this panel shrinks. WHICH destinations exist is the person's ROLE (a
+// narrowed one keeps only the `intake` contributions) and then the interface TIER (basic hides the
+// `advanced` ones), both filtered upstream in `navSlotFilter`; how much room they take is the
+// COLLAPSE state (the icon-only rail). Basic mode starts railed, but each can be changed
+// independently from the role / tier switchers at the top and the rail toggle.
 import { useEventListener, useScrollLock } from '@vueuse/core'
 import BoardSwitcher from '~/components/layout/BoardSwitcher.vue'
 import LanguageSwitcher from '~/components/layout/LanguageSwitcher.vue'
 import UiModeSwitcher from '~/components/layout/UiModeSwitcher.vue'
+import UiRoleSwitcher from '~/components/layout/UiRoleSwitcher.vue'
 import UserMenu from '~/components/auth/UserMenu.vue'
 import { useViewport } from '~/composables/useViewport'
 import type { NavContribution } from '~/modular/nav-contributions'
@@ -67,6 +68,7 @@ const { isCompact } = useViewport()
 // it only to find a rail would be two taps for one destination. The tier decides the default
 // (basic starts collapsed), the user's toggle wins from there — see `stores/uiMode.ts`.
 const uiMode = useUiModeStore()
+const uiRole = useUiRoleStore()
 const railed = computed(() => !isCompact.value && uiMode.navCollapsed)
 
 // The off-canvas drawer is a modal surface on compact viewports, so give it the
@@ -201,15 +203,22 @@ watch(
 
     <BoardSwitcher :collapsed="railed" />
 
-    <!-- The interface tier sits ABOVE the destinations it gates, not in the footer: basic is the
-         shipped default, so this row is most users' only sight of the tier, and below the fold in
-         a scrolled navbar it is a thin thread to hang the advanced half of the product on. The
-         wrapper is what keeps the control and its hint together — the aside's own `gap-4` would
-         otherwise push them apart. Kept OUT of the `onNavAction` group deliberately: switching
-         tiers opens nothing, and closing the compact drawer would hide the destinations the
-         switch just revealed. -->
+    <!-- The two "how much of the app do I see" controls sit ABOVE the destinations they gate, not
+         in the footer: basic is the shipped default, so this row is most users' only sight of the
+         tier, and below the fold in a scrolled navbar it is a thin thread to hang the advanced
+         half of the product on. The wrapper is what keeps each control with its hint, since the aside's
+         own `gap-4` would otherwise push them apart. Kept OUT of the `onNavAction` group
+         deliberately: switching tier or role opens nothing, and closing the compact drawer would
+         hide the destinations the switch just revealed.
+
+         The ROLE comes first because it is the outer of the two: it caps the tier (see
+         `resolveUiMode`), which is also why the tier switcher is dropped on a narrowed role:
+         with the tier fixed at basic, a control that flipped it would be advertising a choice the
+         resolver ignores, exactly as it refuses to be under an env pin. The role switcher itself
+         is rendered in EVERY role: it is the way back. -->
     <div class="space-y-1">
-      <UiModeSwitcher :collapsed="railed" />
+      <UiRoleSwitcher :collapsed="railed" />
+      <UiModeSwitcher v-if="uiRole.fullSurface" :collapsed="railed" />
     </div>
 
     <div class="contents" @click="onNavAction">

package/app/components/layout/UiRoleSwitcher.vue

@@ -0,0 +1,73 @@
+<script setup lang="ts">
+import { computed } from 'vue'
+import { ROLE_PRESENTATION, UI_ROLES } from '~/utils/uiRole'
+
+// Role picker, at the TOP of the sidebar beside the interface-tier switcher: one place answers
+// "how much of the app do I see", and the role is the outer of the two (it can cap the tier, see
+// `resolveUiMode`), so it sits above it.
+//
+// A DROPDOWN rather than the tier switcher's segmented control, and the difference is not
+// cosmetic: three role names do not fit legibly across a 15rem sidebar, and the choice has already
+// been made explicitly once (the first-run prompt states what each role gives you), so this
+// control's job is to NAME the current role and offer the way out, not to advertise that a choice
+// exists. It is rendered in EVERY role, including the narrowed one, because it is the way back.
+//
+// In the collapsed rail it keeps the menu and drops to the glyph plus the role's name, so the rail
+// still says which role is on (the same reason the tier button keeps its label there).
+withDefaults(defineProps<{ collapsed?: boolean }>(), { collapsed: false })
+
+const uiRole = useUiRoleStore()
+const { t } = useI18n()
+
+// Name / glyph / one-line description all come from the shared presentation table, so this
+// control and the first-run prompt can never describe the same role differently.
+const current = computed(() => ROLE_PRESENTATION[uiRole.role])
+const currentLabel = computed(() => t(current.value.labelKey))
+
+const items = computed(() =>
+  UI_ROLES.map((role) => ({
+    label: t(ROLE_PRESENTATION[role].labelKey),
+    icon: ROLE_PRESENTATION[role].icon,
+    // The tick, so an open menu says which role is current as well as which are available.
+    trailingIcon: role === uiRole.role ? 'i-lucide-check' : undefined,
+    onSelect: () => uiRole.setRole(role),
+  })),
+)
+</script>
+
+<template>
+  <UDropdownMenu :items="items" :ui="{ content: 'min-w-48' }">
+    <!-- Rail: glyph over the role name, matching the tier button beside it. -->
+    <button
+      v-if="collapsed"
+      type="button"
+      data-testid="ui-role-toggle"
+      :aria-label="`${t('uiRole.switcher')}: ${currentLabel}`"
+      :title="`${t('uiRole.switcher')}: ${currentLabel}`"
+      class="flex w-full flex-col items-center gap-0.5 rounded-lg border border-slate-700 bg-slate-900/60 px-1 py-1.5 transition hover:border-indigo-500/60 hover:bg-slate-800/60"
+    >
+      <UIcon :name="current.icon" class="h-4 w-4 shrink-0 text-indigo-400" />
+      <span class="w-full truncate text-center text-[9px] font-medium uppercase text-slate-300">
+        {{ currentLabel }}
+      </span>
+    </button>
+
+    <button
+      v-else
+      type="button"
+      data-testid="ui-role-switcher"
+      :aria-label="t('uiRole.switcher')"
+      :title="t(current.hintKey)"
+      class="flex w-full items-center gap-2 rounded-lg border border-slate-700 bg-slate-900/60 p-2 text-start transition hover:border-indigo-500/60 hover:bg-slate-800/60"
+    >
+      <UIcon :name="current.icon" class="h-4 w-4 shrink-0 text-indigo-400" />
+      <div class="min-w-0 flex-1">
+        <div class="truncate text-[10px] uppercase tracking-wide text-slate-500">
+          {{ t('uiRole.switcher') }}
+        </div>
+        <div class="truncate text-xs font-medium text-slate-200">{{ currentLabel }}</div>
+      </div>
+      <UIcon name="i-lucide-chevron-down" class="h-3.5 w-3.5 shrink-0 text-slate-500" />
+    </button>
+  </UDropdownMenu>
+</template>

package/app/components/slack/SlackPanel.vue

@@ -36,6 +36,7 @@ const ROUTABLE = computed<{ type: NotificationType; label: string }[]>(() => [
   { type: 'merge_tag_request', label: t('slack.routable.merge_tag_request') },
   { type: 'ci_failed', label: t('slack.routable.ci_failed') },
   { type: 'test_failed', label: t('slack.routable.test_failed') },
+  { type: 'deploy_blocked', label: t('slack.routable.deploy_blocked') },
   { type: 'requirement_review', label: t('slack.routable.requirement_review') },
   { type: 'clarity_review', label: t('slack.routable.clarity_review') },
   { type: 'release_regression', label: t('slack.routable.release_regression') },
@@ -60,6 +61,7 @@ const routes = reactive<Record<NotificationType, SlackRoute>>({
   merge_tag_request: { enabled: false, channel: '' },
   ci_failed: { enabled: false, channel: '' },
   test_failed: { enabled: false, channel: '' },
+  deploy_blocked: { enabled: false, channel: '' },
   requirement_review: { enabled: false, channel: '' },
   clarity_review: { enabled: false, channel: '' },
   release_regression: { enabled: false, channel: '' },

package/app/composables/useNavContributions.ts

@@ -66,6 +66,9 @@ export function useNavContributions() {
     // No-op under an env pin (`setMode` refuses), so the palette entry matches the sidebar
     // switcher's read-only state rather than pretending to flip a tier the resolver fixes.
     toggleUiMode: () => useUiModeStore().toggleMode(),
+    // The QUESTION, not a toggle: with three roles there is no unambiguous "next one", and the
+    // prompt is the one surface that states what each role gives you before you pick it.
+    chooseRole: () => useUiRoleStore().openPrompt(),
   }
 
   /** Run a contribution's action (consumer `run` closure wins over the id map). */

package/app/docs/consumer-extensions.md

@@ -61,18 +61,29 @@ export default defineNuxtPlugin(() => {
 | Run-detail windows                  | `resultViews`             | `{ id: '<ns>:<name>', component }`                                                                        | `StepResultViewHost` via `dispatchStepView`                               |
 | Agent kinds (palette data)          | `agentKinds`              | `{ kind, container, presentation: { label, icon, color, description, category?, resultView? } }`          | agents store merge → `agentKindMeta`                                      |
 | Custom task types                   | `taskTypes`               | `{ taskType: '<ns>:<name>', presentation, fields?, defaultPipelineId?, defaultFragmentIds?, formPanel? }` | `AddTaskModal` picker/fields + `TaskCard` badge (via `taskTypeMeta`)      |
-| Sidebar / command-palette / toolbar | `nav`                     | `{ id, labelKey, icon, surfaces, gate?, advanced?, run, sidebar?, command?, toolbar? }`                   | the three shells via `useNavContributions`                                |
+| Sidebar / command-palette / toolbar | `nav`                     | `{ id, labelKey, icon, surfaces, gate?, advanced?, intake?, run, sidebar?, command?, toolbar? }`          | the three shells via `useNavContributions`                                |
 | Inspector body panels               | `inspectorPanels`         | `{ id, component, when(block), order }` (`PanelEntry<Block>`)                                             | `<PanelsOutlet>` in `InspectorPanel`                                      |
 | Top-level overlays                  | `appOverlays`             | `{ id: '<ns>:<name>', component }`                                                                        | `<AppOverlayHost>` via `useAppOverlays().open(id)`                        |
-| External tools                      | `externalTools`           | `{ id, title, icon, url, description?, requiredMetadata?, gate?, advanced?, order? }`                     | the "External tools" sidebar section + palette, via `useNavContributions` |
+| External tools                      | `externalTools`           | `{ id, title, icon, url, description?, requiredMetadata?, gate?, advanced?, intake?, order? }`            | the "External tools" sidebar section + palette, via `useNavContributions` |
 | Custom workspace metadata fields    | `workspaceMetadataFields` | `{ key, label, description?, placeholder?, type?, options?, order? }`                                     | the Metadata tab of Workspace settings                                    |
 | Multi-step wizards                  | (journeys)                | `registerJourney` + step modules                                                                          | `<JourneyHost>` / `<JourneyOutlet>`                                       |
 | 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
+Beyond `gate`, a destination answers to two narrowing axes, both applied to your entries exactly
+as they are to the first-party ones. All three are independent, and all three must pass.
+
+`advanced: true` hides an entry in **basic** interface mode, the shipped default: 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.
+destination.
+
+`intake: true` keeps an entry for a role narrowed to the intake surface, today `designer`: see
+[Roles](../../README.md#roles-engineer--product-manager--designer). This one is opt-IN, so an
+entry that says nothing is offered to the full-surface roles only. Declare it where your
+destination is somewhere work comes IN from rather than somewhere the platform is configured; a
+design-handoff console qualifies, an admin panel does not.
+
+Both flags live on `NavGatedContribution`, which an external tool extends too, so a tool answers
+the same axes as a `nav` entry and there is one predicate (`navItemVisible`) deciding both.
 
 ### Run-detail windows (`resultViews` + `agentKinds`)
 
@@ -153,7 +164,10 @@ workspaceMetadataFields: [{ key: 'gameId', label: 'Game id', placeholder: 'zork'
   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.
+- **`gate`, `advanced` and `intake`** work exactly as on a `nav` entry, and for the same reason:
+  a tool is projected onto a nav contribution and filtered by the same predicate. All must pass,
+  and `intake` defaults the same way, so a registered application is dropped for a narrowed role
+  until you say it belongs there.
 
 **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

package/app/modular/external-tools.spec.ts

@@ -2,13 +2,11 @@ import { describe, expect, it, vi } from 'vitest'
 import { missingI18nKeys } from '../../test/i18nKeys'
 import {
   EXTERNAL_TOOL_UNAVAILABLE_KEYS,
-  filterExternalTools,
   projectExternalTools,
   resolveExternalToolUrl,
   type ExternalToolContext,
   type ExternalToolContribution,
 } from './external-tools'
-import type { NavGates } from './nav-contributions'
 
 const CONTEXT: ExternalToolContext = {
   userId: 'usr_1',
@@ -27,26 +25,6 @@ const MAP_EDITOR: ExternalToolContribution = {
     `https://maps.acme.dev/edit?game=${ctx.metadata.gameId}&ws=${ctx.workspaceId}&user=${ctx.userId ?? ''}`,
 }
 
-const GATES: NavGates = {
-  canWriteBoard: true,
-  canManageIntegrations: true,
-  canManageSettings: true,
-  githubAvailable: true,
-  libraryAvailable: true,
-  designSourceConnected: true,
-  infrastructureAvailable: true,
-  accountsEnabled: true,
-  isAccountAdmin: true,
-  advancedMode: true,
-  boardHasService: true,
-  boardHasTask: true,
-  boardHasRun: true,
-  boardHasOpenDecision: true,
-  boardHasPendingApproval: true,
-  boardHasFinishedRun: true,
-  boardHasFailedRun: true,
-}
-
 describe('resolveExternalToolUrl', () => {
   it('folds the invocation context into the resolved URL', () => {
     // The whole point of a resolver over a static link: the tool opens on the right game,
@@ -250,29 +228,6 @@ describe('projectExternalTools', () => {
   })
 })
 
-describe('filterExternalTools', () => {
-  const tools: ExternalToolContribution[] = [
-    { id: 'a', title: 'A', icon: 'i', url: 'https://a.dev' },
-    { id: 'b', title: 'B', icon: 'i', url: 'https://b.dev', gate: (g) => g.canManageIntegrations },
-    { id: 'c', title: 'C', icon: 'i', url: 'https://c.dev', advanced: true },
-  ]
-
-  it('applies the RBAC gate and the interface tier independently', () => {
-    expect(filterExternalTools(tools, GATES).map((t) => t.id)).toEqual(['a', 'b', 'c'])
-    expect(
-      filterExternalTools(tools, { ...GATES, canManageIntegrations: false }).map((t) => t.id),
-    ).toEqual(['a', 'c'])
-    expect(filterExternalTools(tools, { ...GATES, advancedMode: false }).map((t) => t.id)).toEqual([
-      'a',
-      'b',
-    ])
-  })
-
-  it('passes everything through with no gates service wired (dev-open parity)', () => {
-    expect(filterExternalTools(tools, undefined).map((t) => t.id)).toEqual(['a', 'b', 'c'])
-  })
-})
-
 describe('EXTERNAL_TOOL_UNAVAILABLE_KEYS', () => {
   it('names copy that exists for every reason', () => {
     // The exhaustive `Record` proves each reason HAS an entry; only this proves the entry still

package/app/modular/external-tools.ts

@@ -1,5 +1,5 @@
 import { metadataValue } from './workspace-metadata'
-import type { NavContribution, NavGates } from './nav-contributions'
+import type { NavContribution, NavGatedContribution } from './nav-contributions'
 
 /**
  * EXTERNAL TOOLS — a deployment's own web applications, registered programmatically and
@@ -56,8 +56,17 @@ export interface ExternalToolContext {
  */
 export type ExternalToolUrlResolver = (context: ExternalToolContext) => string | null
 
-/** One registered external tool. */
-export interface ExternalToolContribution {
+/**
+ * One registered external tool.
+ *
+ * The visibility axes are INHERITED from {@link NavGatedContribution} rather than redeclared:
+ * a tool is projected onto a nav contribution and filtered by the same `navItemVisible`, so
+ * every axis a first-party destination answers to (the interface tier, the role's surface, the
+ * RBAC/availability predicate) is one this answers to as well. `intake` defaults the same way
+ * it does there, which for a registered application means the full-surface roles only until
+ * the deployment says otherwise.
+ */
+export interface ExternalToolContribution extends NavGatedContribution {
   /** Namespaced id (`<ns>:<name>`), like every other consumer contribution. */
   id: string
   /** Display name. Literal copy, not an i18n key: a tool's name is deployment DATA (the same
@@ -83,10 +92,6 @@ export interface ExternalToolContribution {
   requiredMetadata?: readonly string[]
   /** Sidebar/palette order within the External tools section. Defaults to 0. */
   order?: number
-  /** Reactive RBAC/availability predicate, exactly as on a {@link NavContribution}. */
-  gate?: (gates: NavGates) => boolean
-  /** Show only in advanced interface mode. */
-  advanced?: boolean
   /** Stable selector for e2e. Defaults to `nav-external-tool-<id>`. */
   testId?: string
 }
@@ -247,19 +252,3 @@ export function projectExternalTools(
       return { tool, resolution, contribution }
     })
 }
-
-/**
- * Drop the tools the caller may not see, on the same two independent axes as `navSlotFilter`
- * applies to `nav`: the interface tier, then the item's own RBAC/availability predicate. With
- * no gates service wired (tests, a bare install) everything passes, matching the dev-open
- * "absent access allows all" parity the nav filter keeps.
- */
-export function filterExternalTools(
-  tools: readonly ExternalToolContribution[],
-  gates: NavGates | undefined,
-): ExternalToolContribution[] {
-  if (!gates) return [...tools]
-  return tools.filter(
-    (t) => (t.advanced ? gates.advancedMode : true) && (t.gate ? t.gate(gates) : true),
-  )
-}