@cat-factory/app 0.273.2 → 0.275.0

package/app/pages/index.vue

@@ -155,6 +155,9 @@ const TutorialOverlay = defineAsyncComponent(
   () => import('~/components/tutorial/TutorialOverlay.vue'),
 )
 const TutorialNudge = defineAsyncComponent(() => import('~/components/tutorial/TutorialNudge.vue'))
+// The first-run role question (Engineer / Product manager / Designer). Same shape as the tutorial
+// launch prompt: mounted only while its store flag is set, so an answered question costs nothing.
+const RolePrompt = defineAsyncComponent(() => import('~/components/layout/RolePrompt.vue'))
 
 const workspace = useWorkspaceStore()
 const github = useGitHubStore()
@@ -312,11 +315,11 @@ const needsGitHubInstall = computed(() => github.available === true && !github.c
 const githubProbePending = computed(() => github.available === null)
 
 // Offer the tutorial on launch, once the board is up. Yields to every other startup
-// surface — the GitHub onboarding gate and the advisory/onboarding modals above — so a
-// first launch never stacks the tour prompt on top of a dialog that needs answering
-// first; when one of those is open, the flip of its flag re-fires this watcher and the
-// prompt appears then. The store guards the rest: only a user who never answered is
-// asked, at most once per session.
+// surface — the GitHub onboarding gate, the advisory/onboarding modals above, and the role
+// question below — so a first launch never stacks the tour prompt on top of a dialog that
+// needs answering first; when one of those is open, the flip of its flag re-fires this
+// watcher and the prompt appears then. The store guards the rest: only a user who never
+// answered is asked, at most once per session.
 //
 // Yielding runs in BOTH directions: an advisory that opens LATER (a health probe that
 // resolves a beat after the board) would otherwise land on top of an open tour prompt,
@@ -330,6 +333,7 @@ const githubProbePending = computed(() => github.available === null)
 // state pays nothing for the launch offer: no watcher, no mounted component (the v-ifs
 // below), no store reads.
 const tutorial = useTutorialStore()
+const uiRole = useUiRoleStore()
 const startupAdvisoryOpen = computed(
   () =>
     needsGitHubInstall.value ||
@@ -340,6 +344,30 @@ const startupAdvisoryOpen = computed(
     ui.aiProviderSetupOpen ||
     ui.aiPresetMismatchOpen,
 )
+
+// The ROLE question comes before the tour offer, and the ordering is the point: the role decides
+// which surfaces exist, so a tour picked ahead of it could be about half a product the next answer
+// removes. It runs the same launch machine as the tutorial offer (yield to anything the user must
+// actually answer, re-arm when that surface goes, at most one offer per session) and stops itself
+// once it can no longer do anything.
+const roleOfferSettled = () => uiRole.chosen || (uiRole.promptAutoOpened && !uiRole.promptOpen)
+if (!roleOfferSettled()) {
+  let stopRoleOffer: (() => void) | undefined
+  stopRoleOffer = watch(
+    () => [workspace.ready, startupAdvisoryOpen.value, uiRole.promptOpen],
+    () => {
+      if (startupAdvisoryOpen.value) uiRole.deferPrompt()
+      else if (workspace.ready) uiRole.maybeOfferOnLaunch()
+      if (roleOfferSettled()) stopRoleOffer?.()
+    },
+    { immediate: true },
+  )
+  if (roleOfferSettled()) stopRoleOffer()
+}
+// What the TOUR offer yields to: every startup advisory, plus the role question above it. The
+// role prompt is not in `startupAdvisoryOpen` itself, or the role offer would defer to its own
+// standing offer and withdraw it a tick after making it.
+const tutorialYieldsTo = computed(() => startupAdvisoryOpen.value || uiRole.promptOpen)
 // Settled = the offer can never need to act again: a decision exists, or the prompt was
 // auto-opened and is still standing (a deferral clears `promptAutoOpened`, which is
 // exactly what keeps the watcher alive to re-offer).
@@ -350,9 +378,9 @@ if (!tutorialOfferSettled()) {
   // inside `watch(...)`, before the handle is assigned — the trailing check covers it.
   let stopTutorialOffer: (() => void) | undefined
   stopTutorialOffer = watch(
-    () => [workspace.ready, startupAdvisoryOpen.value, tutorial.promptOpen],
+    () => [workspace.ready, tutorialYieldsTo.value, tutorial.promptOpen],
     () => {
-      if (startupAdvisoryOpen.value) tutorial.deferPrompt()
+      if (tutorialYieldsTo.value) tutorial.deferPrompt()
       else if (workspace.ready) tutorial.maybeOfferOnLaunch()
       if (tutorialOfferSettled()) stopTutorialOffer?.()
     },
@@ -506,6 +534,7 @@ watch(
         <VendorCredentialsModal v-if="ui.vendorCredentialsOpen" />
         <AiProviderOnboardingModal v-if="ui.aiProviderSetupOpen" />
         <AiPresetMismatchDialog v-if="ui.aiPresetMismatchOpen" />
+        <RolePrompt v-if="uiRole.promptOpen" />
         <TutorialPrompt v-if="tutorial.promptOpen" />
         <TutorialCatalogue v-if="tutorial.catalogueOpen" />
         <TutorialOverlay v-if="tutorial.touring" />

package/app/stores/launchPrompt.ts

@@ -0,0 +1,63 @@
+import { ref } from 'vue'
+
+/**
+ * The state machine behind a ONCE-PER-SESSION launch offer: the tutorial's "take a tour?"
+ * (`stores/tutorial.ts`) and the role question (`stores/uiRole.ts`) are the same shape, so
+ * they share this rather than each re-deriving it.
+ *
+ * It is a small machine with four distinguishable exits and no other job, which is what makes
+ * it a seam worth having rather than four refs among twenty: closing without answering, an
+ * explicit decline (the caller's own, since only it knows what a decision IS), a DEFERRAL
+ * (something the user must actually answer opened on top), and the once-per-session auto-open
+ * are four different things, and only some of them write anything down. The subtlety they share
+ * is the ONE-OFFER-PER-SESSION guard, which is why they belong together: `promptAutoOpened`
+ * must be spent by an offer the user saw and NOT by one that was withdrawn.
+ *
+ * `hasDecision` is a bound getter over the caller's persisted record rather than the record
+ * itself, so this module never learns what a decision IS — only whether one exists, which is
+ * the whole of what the offer needs.
+ */
+export function createLaunchPrompt(deps: { hasDecision: () => boolean }) {
+  const promptOpen = ref(false)
+  /** Once-per-session guard for the launch auto-open; later opens are user-driven. */
+  const promptAutoOpened = ref(false)
+
+  /**
+   * Auto-open the launch prompt, at most once per session and only while the user has never
+   * answered it. Callers gate on the rest of the launch context (board ready, no other startup
+   * advisory open) — see `pages/index.vue`.
+   */
+  function maybeOfferOnLaunch() {
+    if (deps.hasDecision() || promptAutoOpened.value) return
+    promptAutoOpened.value = true
+    promptOpen.value = true
+  }
+
+  /** User-driven open (command palette), regardless of any saved decision. */
+  function openPrompt() {
+    promptOpen.value = true
+  }
+
+  /**
+   * Withdraw an offer this store made, because something the user actually has to answer (a
+   * startup advisory, the GitHub onboarding gate) opened on top of it — and re-arm, so the offer
+   * returns once that surface is gone. Distinct from {@link closePrompt}: no decision is written
+   * EITHER way, but a deferral was not the user's doing, so it must not consume this session's
+   * one offer.
+   *
+   * Only ever withdraws the AUTO-opened prompt; a prompt the user opened themselves from the
+   * palette is theirs to close.
+   */
+  function deferPrompt() {
+    if (!promptAutoOpened.value) return
+    promptOpen.value = false
+    promptAutoOpened.value = false
+  }
+
+  /** Close without answering: no decision is written, so the next launch asks again. */
+  function closePrompt() {
+    promptOpen.value = false
+  }
+
+  return { promptOpen, promptAutoOpened, maybeOfferOnLaunch, openPrompt, deferPrompt, closePrompt }
+}

package/app/stores/tutorial.ts

@@ -1,6 +1,6 @@
 import { defineStore } from 'pinia'
 import { computed, ref } from 'vue'
-import { createTutorialPrompt } from '~/stores/tutorial.prompt'
+import { createLaunchPrompt } from '~/stores/launchPrompt'
 import { createTutorialRecord } from '~/stores/tutorial.record'
 
 // `TutorialDecision` is deliberately NOT re-exported from here even though it used to live here:
@@ -37,9 +37,9 @@ export const useTutorialStore = defineStore(
   'tutorial',
   () => {
     const record = createTutorialRecord()
-    // The launch offer's own four-exit state machine (`stores/tutorial.prompt.ts`), which needs to
-    // know only WHETHER an answer exists.
-    const prompt = createTutorialPrompt({ hasDecision: () => record.decision.value !== null })
+    // The launch offer's own four-exit state machine (`stores/launchPrompt.ts`, shared with the
+    // role question), which needs to know only WHETHER an answer exists.
+    const prompt = createLaunchPrompt({ hasDecision: () => record.decision.value !== null })
     const { promptOpen } = prompt
     /**
      * The tutorial catalogue (every tour this deployment ships, startable at any time) is

package/app/stores/uiMode.spec.ts

@@ -66,6 +66,17 @@ describe('useUiModeStore mode resolution', () => {
     expect(ui.mode).toBe('advanced')
   })
 
+  it('ignores an unrecognised RESTORED value on the same terms as the env one', () => {
+    // `storedMode`'s type says what `setMode` writes, not what the persistence plugin
+    // rehydrated: an older build's blob (or a hand-edited one) arrives typed as a `UiMode`.
+    // Left unparsed it resolves to neither tier, and `isAdvanced` then answers a question
+    // about a value that is not a tier at all.
+    const ui = useUiModeStore()
+    ui.storedMode = 'expert' as UiMode
+    expect(ui.mode).toBe('basic')
+    expect(ui.isAdvanced).toBe(false)
+  })
+
   it('toggleMode flips between the two tiers', () => {
     const ui = useUiModeStore()
     ui.toggleMode()

package/app/stores/uiMode.ts

@@ -1,11 +1,13 @@
 import { defineStore } from 'pinia'
 import { computed, ref } from 'vue'
+import { useUiRoleStore } from '~/stores/uiRole'
 import { DEFAULT_RAIL_COLLAPSED, parseUiMode, resolveUiMode, type UiMode } from '~/utils/uiMode'
 
 /**
  * The interface tier (`basic` / `advanced`) and the side-navbar collapse state.
  *
- * Mode resolution is `env → browser-stored → basic` (see `utils/uiMode.ts`). The env value
+ * Mode resolution is `role surface → env → browser-stored → basic` (see `utils/uiMode.ts`); the
+ * role is the ceiling, so an `intake` role renders basic whatever the other two say. The env value
  * is `runtimeConfig.public.uiMode`, i.e. `NUXT_PUBLIC_UI_MODE`: the SPA is `ssr: false`, so
  * — exactly like `apiBase` — it is baked in at build time and cannot change while the app
  * is loaded. It is therefore read ONCE here rather than tracked reactively. Only the user's
@@ -31,7 +33,17 @@ export const useUiModeStore = defineStore(
     /** The rail state each tier was last left in, persisted. Seeded from the per-tier defaults. */
     const railCollapsed = ref<Record<UiMode, boolean>>({ ...DEFAULT_RAIL_COLLAPSED })
 
-    const mode = computed<UiMode>(() => resolveUiMode(envMode, storedMode.value))
+    // The role's surface caps the tier (see `resolveUiMode`): an `intake` role renders basic
+    // whatever the env pin or the stored choice says, so every `isAdvanced` reader in the app
+    // agrees with the narrowed nav without restating the role.
+    const uiRole = useUiRoleStore()
+    // The restored value goes through `parseUiMode` for the same reason the env string does, and
+    // for the reason `railCollapsed` is read defensively just below: `storedMode`'s type says
+    // what `setMode` writes, not what the persistence plugin rehydrated. An unrecognised tier
+    // would otherwise pass straight through `resolveUiMode` and render as neither tier.
+    const mode = computed<UiMode>(() =>
+      resolveUiMode(envMode, parseUiMode(storedMode.value), uiRole.surface),
+    )
     const isAdvanced = computed(() => mode.value === 'advanced')
     /** Pinned by the deployment: the switcher is read-only, since a write would be ignored. */
     const envPinned = computed(() => envMode !== null)

package/app/stores/uiRole.spec.ts

@@ -0,0 +1,185 @@
+import { beforeEach, describe, expect, it } from 'vitest'
+import { createPinia, setActivePinia } from 'pinia'
+import { missingI18nKeys } from '../../test/i18nKeys'
+import { useUiRoleStore } from '~/stores/uiRole'
+import { useUiModeStore } from '~/stores/uiMode'
+import {
+  parseUiRole,
+  ROLE_PRESENTATION,
+  ROLE_SURFACES,
+  UI_ROLES,
+  type UiRole,
+} from '~/utils/uiRole'
+
+describe('useUiRoleStore role resolution', () => {
+  it('boots on the FULL surface with nothing stored, and says nobody has chosen', () => {
+    // The two halves of the first-run condition, and they must not be conflated: an unanswered
+    // question leaves the whole product in place (`fullSurface`) while still being unanswered
+    // (`chosen`), which is what lets the prompt ask again without ever having taken anything away.
+    const role = useUiRoleStore()
+    expect(role.chosen).toBe(false)
+    expect(role.role).toBe('engineer')
+    expect(role.fullSurface).toBe(true)
+  })
+
+  it('honours a stored choice and narrows only for the intake role', () => {
+    const role = useUiRoleStore()
+    role.setRole('product-manager')
+    expect(role.role).toBe('product-manager')
+    expect(role.chosen).toBe(true)
+    // Engineer and product-manager resolve to the SAME surface today; that is the product
+    // decision, not an accident of the mapping.
+    expect(role.fullSurface).toBe(true)
+
+    role.setRole('designer')
+    expect(role.surface).toBe('intake')
+    expect(role.fullSurface).toBe(false)
+    // Persisted, so a reload restores it (the persist plugin picks `storedRole`).
+    expect(role.storedRole).toBe('designer')
+  })
+
+  it('coerces an unknown persisted value on the way IN, not at the call sites', () => {
+    // What the persistence plugin restores is a JSON blob an older build wrote or somebody hand
+    // edited, so an unknown string arrives typed as a `UiRole` and nothing downstream is
+    // forgiving: `ROLE_SURFACES[role]` is `undefined` (the nav narrows to intake without a
+    // word) and `ROLE_PRESENTATION[role].labelKey` throws in the switcher. Writing the raw
+    // value onto `storedRole` is exactly what hydration does, which is why this drives the
+    // STORE rather than calling `parseUiRole` by hand: a guard nothing calls looks identical to
+    // a guard that works.
+    const role = useUiRoleStore()
+    role.storedRole = 'architect' as UiRole
+
+    expect(role.role).toBe('engineer')
+    expect(role.surface).toBe('full')
+    expect(role.fullSurface).toBe(true)
+    // An unrecognised value is not an ANSWER, so the first-run prompt asks again and the person
+    // can replace it. Reading `storedRole !== null` instead pins the browser to the default with
+    // the one question that would fix it already marked settled.
+    expect(role.chosen).toBe(false)
+    // The resolved role indexes both catalogs, which is the property the switcher relies on.
+    expect(ROLE_PRESENTATION[role.role].labelKey).toBeTruthy()
+    expect(ROLE_SURFACES[role.role]).toBe('full')
+  })
+
+  it('parses a raw value the way the store consumes it', () => {
+    expect(parseUiRole('lead-designer')).toBeNull()
+    expect(parseUiRole(undefined)).toBeNull()
+    expect(parseUiRole(' Designer ')).toBe('designer')
+  })
+})
+
+describe('useUiRoleStore first-run prompt', () => {
+  it('offers itself once per session while unanswered', () => {
+    const role = useUiRoleStore()
+    role.maybeOfferOnLaunch()
+    expect(role.promptOpen).toBe(true)
+
+    // Closing without answering writes nothing, so the NEXT launch asks again, but this
+    // session's one offer is spent.
+    role.closePrompt()
+    expect(role.storedRole).toBeNull()
+    role.maybeOfferOnLaunch()
+    expect(role.promptOpen).toBe(false)
+  })
+
+  it('never offers itself again once a role is recorded', () => {
+    const role = useUiRoleStore()
+    role.setRole('designer')
+    role.maybeOfferOnLaunch()
+    expect(role.promptOpen).toBe(false)
+  })
+
+  it('re-arms after a deferral, so a startup advisory does not consume the offer', () => {
+    // What `pages/index.vue` does when an advisory the user must answer opens on top: the offer
+    // is withdrawn and comes back, rather than counting as a question they were asked.
+    const role = useUiRoleStore()
+    role.maybeOfferOnLaunch()
+    role.deferPrompt()
+    expect(role.promptOpen).toBe(false)
+    role.maybeOfferOnLaunch()
+    expect(role.promptOpen).toBe(true)
+  })
+
+  it('leaves a user-opened prompt alone on a deferral', () => {
+    // Opened from the command palette: it is the user's, so nothing withdraws it.
+    const role = useUiRoleStore()
+    role.openPrompt()
+    role.deferPrompt()
+    expect(role.promptOpen).toBe(true)
+  })
+
+  it('settles the prompt by picking a role', () => {
+    const role = useUiRoleStore()
+    role.openPrompt()
+    role.setRole('engineer')
+    expect(role.promptOpen).toBe(false)
+    expect(role.chosen).toBe(true)
+  })
+})
+
+describe('the role as a ceiling on the interface tier', () => {
+  beforeEach(() => {
+    setActivePinia(createPinia())
+  })
+
+  it('caps a narrowed role at the basic tier, whatever the user stored', () => {
+    // Resolved rather than merely hidden: every `isAdvanced` reader inside a surface (the
+    // override fields, the authoring affordances) has to agree with the narrowed nav, and only
+    // the resolved mode reaches all of them.
+    const mode = useUiModeStore()
+    mode.setMode('advanced')
+    expect(mode.isAdvanced).toBe(true)
+
+    useUiRoleStore().setRole('designer')
+    expect(mode.mode).toBe('basic')
+    expect(mode.isAdvanced).toBe(false)
+
+    // Leaving the narrowed role restores the tier the person had picked: the cap withholds the
+    // tier, it does not overwrite the preference.
+    useUiRoleStore().setRole('engineer')
+    expect(mode.isAdvanced).toBe(true)
+  })
+})
+
+describe('UI_ROLES catalog integrity', () => {
+  it('maps every role to a surface and presents each one', () => {
+    // Derived from the vocabulary rather than re-listed, so a new role fails here (and in the
+    // exhaustive Records themselves) until it has picked a surface and gained its copy.
+    expect(Object.keys(ROLE_SURFACES).sort()).toEqual([...UI_ROLES].sort())
+    expect(Object.keys(ROLE_PRESENTATION).sort()).toEqual([...UI_ROLES].sort())
+    // Exactly one narrowed role today, and the full ones are the majority: a mapping that
+    // narrowed everything would pass every other assertion in this file.
+    const surfaces = UI_ROLES.map((role: UiRole) => ROLE_SURFACES[role])
+    expect(surfaces.filter((s) => s === 'full').length).toBeGreaterThan(0)
+    expect(surfaces.filter((s) => s === 'intake').length).toBeGreaterThan(0)
+  })
+
+  it('names an i18n key that exists for every role label and hint', () => {
+    // A table lookup is invisible to typed message keys and to `i18n:check` (neither sees
+    // `t(ROLE_PRESENTATION[role].labelKey)`), so deleting one of these keys would otherwise read
+    // as a clean removal and render its own key path in the picker.
+    const keys = UI_ROLES.flatMap((role: UiRole) => [
+      ROLE_PRESENTATION[role].labelKey,
+      ROLE_PRESENTATION[role].hintKey,
+    ])
+    expect(missingI18nKeys(keys)).toEqual([])
+    // And the copy the two surfaces around them use, which is written literally there but is
+    // just as easy to rename out from under this table.
+    expect(
+      missingI18nKeys([
+        'uiRole.switcher',
+        'uiRole.prompt.title',
+        'uiRole.prompt.intro',
+        'uiRole.prompt.change',
+        'uiRole.prompt.later',
+      ]),
+    ).toEqual([])
+  })
+
+  it('gives every role a distinct glyph', () => {
+    // The rail renders the glyph alone above a truncated name, so two roles sharing one would be
+    // indistinguishable exactly where the label has the least room.
+    const icons = UI_ROLES.map((role: UiRole) => ROLE_PRESENTATION[role].icon)
+    expect(new Set(icons).size).toBe(icons.length)
+  })
+})

package/app/stores/uiRole.ts

@@ -0,0 +1,86 @@
+import { defineStore } from 'pinia'
+import { computed, ref } from 'vue'
+import { createLaunchPrompt } from '~/stores/launchPrompt'
+import {
+  isFullSurfaceRole,
+  parseUiRole,
+  resolveUiRole,
+  roleSurface,
+  type UiRole,
+} from '~/utils/uiRole'
+
+/**
+ * The role the person is here to do (`engineer` / `product-manager` / `designer`) and the
+ * first-run question that asks for it. Resolution and the surface each role maps to are in
+ * `utils/uiRole.ts`.
+ *
+ * Only the person's own choice exists: there is deliberately NO deployment env pin, unlike the
+ * interface tier. The tier is a fleet-shaped decision an operator can reasonably make for a
+ * kiosk deployment; which JOB the person at the keyboard does is not something the build can
+ * know, and pinning it would leave a designer's laptop configured as an engineer's with no way
+ * to say otherwise.
+ *
+ * `chosen` is the whole of the first-run condition: no recognised answer is recorded, which is
+ * what the prompt asks about, and it is what a browser that has never been asked, one whose
+ * answer was cleared, and one carrying a value that is no longer a role all have in common. The
+ * resolved role stays the default throughout, so an unanswered question never takes a
+ * destination away.
+ */
+export const useUiRoleStore = defineStore(
+  'uiRole',
+  () => {
+    /** The person's explicit pick, persisted. `null` until they choose one. */
+    const storedRole = ref<UiRole | null>(null)
+
+    /**
+     * The persisted pick, COERCED, and the only thing anything below reads.
+     *
+     * `storedRole`'s type describes what {@link setRole} WRITES, not what boot restores into it:
+     * the persistence plugin rehydrates a JSON blob a previous build wrote or a person hand-
+     * edited, so an unknown string arrives typed as a `UiRole` and every reader believes it.
+     * There is nothing forgiving downstream to catch it: `ROLE_SURFACES[role]` is `undefined`,
+     * which narrows the nav to intake without a word, and `ROLE_PRESENTATION[role].labelKey`
+     * throws in the switcher, i.e. white-screens the board rather than degrading. So the raw
+     * value is parsed ONCE here, exactly as `agentTier` does with its own restored level.
+     *
+     * `chosen` reads it too, and that is the half that makes the degradation honest rather than
+     * merely safe: an unrecognised value is not an answer, so the first-run prompt asks again
+     * and the person can replace it. Reading `storedRole !== null` instead would leave a browser
+     * pinned to the default with the question it needs to be asked already marked settled.
+     */
+    const pickedRole = computed<UiRole | null>(() => parseUiRole(storedRole.value))
+
+    const role = computed<UiRole>(() => resolveUiRole(pickedRole.value))
+    const surface = computed(() => roleSurface(role.value))
+    /**
+     * The role sees the whole product. Read by the nav gate of the same name and by the few
+     * surfaces that narrow inline; stated positively so no reader has to invert it.
+     */
+    const fullSurface = computed(() => isFullSurfaceRole(role.value))
+    /** A RECOGNISED answer has been recorded, so the first-run prompt has nothing left to ask. */
+    const chosen = computed(() => pickedRole.value !== null)
+
+    // The same once-per-session launch machine the tutorial offer runs on: the question is
+    // answered by PICKING a role, so `hasDecision` is exactly `chosen`. Closing without picking
+    // writes nothing and the next launch asks again, which is safe here precisely because the
+    // default is the full surface.
+    const prompt = createLaunchPrompt({ hasDecision: () => chosen.value })
+
+    /** Record the person's pick and settle the question. */
+    function setRole(next: UiRole) {
+      storedRole.value = next
+      prompt.promptOpen.value = false
+    }
+
+    return {
+      role,
+      surface,
+      fullSurface,
+      chosen,
+      storedRole,
+      ...prompt,
+      setRole,
+    }
+  },
+  { persist: { pick: ['storedRole'] } },
+)

package/app/utils/catalog.spec.ts

@@ -158,16 +158,11 @@ describe('catalog', () => {
     for (const a of AGENT_ARCHETYPES) {
       expect(agentKindMeta(a.kind)).toBe(a)
     }
-    // Engine system kinds (present in seeded pipelines but not the palette) resolve
-    // to their system metadata rather than blowing up an undefined access.
-    for (const kind of [
-      'conflicts',
-      'conflict-resolver',
-      'ci',
-      'ci-fixer',
-      'merger',
-      'post-release-health',
-    ]) {
+    // Engine system kinds (present in seeded pipelines but not the palette) resolve to their
+    // system metadata rather than blowing up an undefined access. Read off the map itself rather
+    // than a hand-kept sample: a kind added there is exactly the one nobody thinks to add here,
+    // and it renders as a generic "Agent" until somebody notices.
+    for (const kind of Object.keys(SYSTEM_AGENT_META)) {
       expect(agentKindMeta(kind)).toBe(SYSTEM_AGENT_META[kind])
       expect(agentKindMeta(kind).icon).toEqual(expect.any(String))
     }

package/app/utils/catalog.ts

@@ -737,6 +737,18 @@ export const SYSTEM_AGENT_META: Record<string, AgentArchetype> = {
     color: '#38bdf8',
     description: 'Fixes failing CI and pushes back to the PR branch.',
   },
+  // The deployer's escalation, and the ci-fixer's shape one step earlier in the pipeline: never a
+  // palette block (nobody authors it into a pipeline), but it runs an LLM over the checkout, so it
+  // needs display metadata for timelines and a pinnable per-workspace model.
+  'deploy-fixer': {
+    kind: 'deploy-fixer',
+    tier: 'basic',
+    label: 'Deploy Fixer',
+    icon: 'i-lucide-server-cog',
+    color: '#0ea5e9',
+    description:
+      'Repairs the deployment files a failed provision was rejected for and pushes back to the PR branch, then the environment is stood up again.',
+  },
   fixer: {
     kind: 'fixer',
     tier: 'basic',
@@ -826,6 +838,7 @@ export const MODEL_CONFIGURABLE_SYSTEM_KINDS: AgentArchetype[] = [
     'initiative-planner',
     'conflict-resolver',
     'ci-fixer',
+    'deploy-fixer',
     'fixer',
     'merger',
     'kaizen',

package/app/utils/uiMode.spec.ts

@@ -29,6 +29,18 @@ describe('resolveUiMode', () => {
     expect(resolveUiMode(null, null)).toBe(DEFAULT_UI_MODE)
     expect(DEFAULT_UI_MODE).toBe('basic')
   })
+
+  it('caps an intake role at basic, above BOTH the env pin and the stored choice', () => {
+    // The role is a ceiling rather than another preference: an `intake` surface is offered the
+    // delivery loop and none of the platform configuration behind it, which is what the advanced
+    // tier is made of. So it wins over the env pin too, the one layer nothing else overrides.
+    expect(resolveUiMode('advanced', 'advanced', 'intake')).toBe('basic')
+    expect(resolveUiMode(null, 'advanced', 'intake')).toBe('basic')
+    // A full-surface role changes nothing, which is what the default argument encodes for every
+    // caller that has no role to hand (the pure-logic callers and the specs above).
+    expect(resolveUiMode('advanced', null, 'full')).toBe('advanced')
+    expect(resolveUiMode(null, 'advanced', 'full')).toBe('advanced')
+  })
 })
 
 describe('showOverrideField', () => {

package/app/utils/uiMode.ts

@@ -1,14 +1,17 @@
+import type { RoleSurface } from '~/utils/uiRole'
+
 /**
  * The interface tier the SPA renders at: `basic` shows the everyday surface, `advanced`
  * shows every destination and every run/pipeline option. Pure resolution logic, kept out
  * of the store so it is testable without Pinia or a Nuxt runtime.
  *
- * Precedence is fixed and NOT negotiable per surface: the deployment's env value always
- * wins over the browser-stored user choice, which wins over the `basic` default. That
- * ordering is what lets an operator pin a fleet of kiosk-ish deployments to one tier
- * without a per-browser reset, so `setMode` is a no-op while the env pin is present
+ * Precedence is fixed and NOT negotiable per surface: the ROLE's surface caps the tier, then
+ * the deployment's env value wins over the browser-stored user choice, which wins over the
+ * `basic` default. That ordering is what lets an operator pin a fleet of kiosk-ish deployments
+ * to one tier without a per-browser reset, so `setMode` is a no-op while the env pin is present
  * rather than writing a preference the resolver would then ignore.
  */
+
 export const UI_MODES = ['basic', 'advanced'] as const
 
 export type UiMode = (typeof UI_MODES)[number]
@@ -37,8 +40,23 @@ export function parseUiMode(raw: unknown): UiMode | null {
   return (UI_MODES as readonly string[]).includes(value) ? (value as UiMode) : null
 }
 
-/** Apply the precedence: env pin → browser-stored user choice → {@link DEFAULT_UI_MODE}. */
-export function resolveUiMode(env: UiMode | null, stored: UiMode | null): UiMode {
+/**
+ * Apply the precedence: the ROLE's surface as a ceiling, then env pin → browser-stored user
+ * choice → {@link DEFAULT_UI_MODE}.
+ *
+ * The role (`utils/uiRole.ts`) sits ABOVE the env pin rather than beside it, because it is a
+ * ceiling and not a preference: an `intake` role is offered the delivery surface and none of the
+ * platform configuration behind it, and the advanced tier's whole content is that configuration.
+ * Resolved here rather than by hiding the tier switcher alone, so every `isAdvanced` reader
+ * inside a surface (the override fields, the authoring affordances) agrees with the nav
+ * without each one restating the role.
+ */
+export function resolveUiMode(
+  env: UiMode | null,
+  stored: UiMode | null,
+  surface: RoleSurface = 'full',
+): UiMode {
+  if (surface === 'intake') return 'basic'
   return env ?? stored ?? DEFAULT_UI_MODE
 }