@cat-factory/app 0.167.1 → 0.169.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)
+- [Interface modes (basic / advanced)](#interface-modes-basic--advanced)
 - [Key UI surfaces](#key-ui-surfaces)
 - [Develop & test](#develop--test)
 
@@ -52,6 +53,48 @@ over the WebSocket. How that sync works is written up in
 | `types/`          | TypeScript domain unions (`domain.ts`) and wire types mirroring the contracts.                                                                        |
 | `utils/`          | Small pure helpers.                                                                                                                                   |
 
+## Interface modes (basic / advanced)
+
+The SPA renders at one of two **interface tiers**. `basic` (the default) is the everyday
+surface: the power-user nav destinations are hidden and the run/pipeline options that only
+exist to override a workspace-level default are left at that default. `advanced` shows
+everything. The tier resolves in a fixed order, first match wins:
+
+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
+   would be a lie. An unrecognised value is ignored rather than failing the boot.
+2. **The user's own choice**, persisted client-side (the `uiMode` store) and changed from the
+   switcher at the bottom of the sidebar — or from the **command palette** entry, which is
+   deliberately _not_ an advanced item: basic is the default, so the route back to the
+   advanced half has to exist inside basic mode.
+3. **`basic`.**
+
+The sidebar can independently be **collapsed to an icon rail** (the toggle at its top, lg+
+only — below `lg` the navbar is already an off-canvas drawer). The rail preference is
+**per-tier**: basic _defaults_ to railed and advanced to expanded, and each tier remembers its
+own choice, so an expand in either survives a reload and a round trip through the other.
+
+Two seams carry the tier, and a new feature should use them rather than reading the store ad
+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.
+- **A less-used option inside a surface** reads `useUiModeStore().isAdvanced`. Hide, never
+  disable, and only ever hide an OVERRIDE: what remains must be exactly the default the hidden
+  field would have shown, so a basic-mode user never gets different behaviour from an advanced
+  one — only fewer choices. An input nothing else supplies (the pipeline, the apriori branches)
+  stays in both tiers however advanced it feels.
+- **An override control on an EXISTING entity gates on `showOverrideField(isAdvanced, …values)`**
+  (`app/utils/uiMode.ts`) rather than on `isAdvanced` alone. Hiding an override is only safe
+  while it is unset — always true for a creation form, never guaranteed for a block that a
+  teammate on the advanced tier (or the API) already wrote one onto. The helper reveals the
+  control, editable, as soon as any value it edits is set (`false` included — a tri-state
+  `false` is a choice, not absence), so basic mode can never conceal a setting a run will
+  actually use.
+
 ## Extending the layer (consumer modules)
 
 A deployment can contribute its own components — result windows, nav entries, inspector
@@ -69,8 +112,8 @@ example ships in [`deploy/frontend`](../../deploy/frontend) (the `acme:security`
   `ModuleFrame`, `TaskCard`), dependency edges, the per-block `AgentFailureCard` /
   `AgentStopButton`, and a deep-zoom `focus/BlockFocusView`.
 - **Sidebar & chrome** (`components/layout`) — board/account switchers, palettes
-  entry points, the `SpendWarningBanner`, and the toolbar (zoom, LOD, decision
-  queue).
+  entry points, the language + [interface-mode](#interface-modes-basic--advanced)
+  switchers, the `SpendWarningBanner`, and the toolbar (zoom, LOD, decision queue).
 - **Palettes** (`components/palettes`) — drag blocks, pipelines and agents onto
   the board.
 - **Inspector** (`components/panels` + `panels/inspector`) — per-block tabs:

package/app/components/auth/UserMenu.vue

@@ -2,6 +2,11 @@
 import type { DropdownMenuItem } from '@nuxt/ui'
 
 // Signed-in identity + per-user actions, shown in the sidebar when auth is enabled.
+//
+// `collapsed` renders the avatar-only rail variant (the sidebar's collapsed state); the
+// dropdown is unchanged, so "My setup" / sign-out stay reachable from the rail.
+withDefaults(defineProps<{ collapsed?: boolean }>(), { collapsed: false })
+
 const auth = useAuthStore()
 const ui = useUiStore()
 const { t } = useI18n()
@@ -30,7 +35,9 @@ const items = computed<DropdownMenuItem[][]>(() => [
   <UDropdownMenu v-if="auth.user" :items="items" :content="{ side: 'top', align: 'start' }">
     <button
       type="button"
+      :title="collapsed ? auth.user.name || auth.user.login : undefined"
       class="flex w-full items-center gap-2 rounded-lg border border-slate-800 bg-slate-900/60 p-2 text-start transition hover:bg-slate-800/60"
+      :class="collapsed ? 'justify-center' : ''"
     >
       <UAvatar
         :src="auth.user.avatarUrl ?? undefined"
@@ -38,13 +45,13 @@ const items = computed<DropdownMenuItem[][]>(() => [
         size="xs"
         icon="i-lucide-user"
       />
-      <div class="min-w-0 flex-1">
+      <div v-if="!collapsed" class="min-w-0 flex-1">
         <div class="truncate text-xs font-medium text-white">
           {{ auth.user.name || auth.user.login }}
         </div>
         <div class="truncate text-[10px] text-slate-500">@{{ auth.user.login }}</div>
       </div>
-      <UIcon name="i-lucide-chevron-up" class="h-4 w-4 shrink-0 text-slate-500" />
+      <UIcon v-if="!collapsed" name="i-lucide-chevron-up" class="h-4 w-4 shrink-0 text-slate-500" />
     </button>
   </UDropdownMenu>
 </template>

package/app/components/board/AddTaskModal.vue

@@ -32,6 +32,14 @@ import { parseConflict } from '~/composables/usePipelineErrorToast'
 import { pipelineAllowedForManualStart } from '~/utils/pipeline'
 
 const ui = useUiStore()
+// Interface tier. In BASIC mode this form asks for the task itself (type, title,
+// description, per-type fields, context, the pipeline) and hides the OVERRIDES: the run
+// knobs with a workspace-level default (merge policy, model preset), the per-task deviation
+// from the service's best-practice fragments, and the technical/business hint the engine
+// infers on its own. Hidden, never disabled — each one falls back to exactly the value it
+// would have shown, so a basic-mode task behaves identically, it just asks less. The
+// inspector's `TaskRunSettings` applies the same split after creation.
+const uiMode = useUiModeStore()
 const board = useBoardStore()
 const documents = useDocumentsStore()
 const tasks = useTasksStore()
@@ -864,7 +872,7 @@ function openReviewFrictionDialog(conflict: NonNullable<ReturnType<typeof parseC
             </UFormField>
           </template>
 
-          <UCheckbox v-model="technical" name="technical">
+          <UCheckbox v-if="uiMode.isAdvanced" v-model="technical" name="technical">
             <template #label>
               <span class="text-sm text-slate-200">{{ t('board.addTask.technical') }}</span>
             </template>
@@ -1113,7 +1121,9 @@ function openReviewFrictionDialog(conflict: NonNullable<ReturnType<typeof parseC
             </template>
           </div>
 
-          <div class="grid grid-cols-2 gap-3">
+          <!-- One column in basic mode, where the pipeline picker is the only survivor and a
+               two-column grid would leave it stranded beside an empty cell. -->
+          <div class="grid gap-3" :class="uiMode.isAdvanced ? 'grid-cols-2' : 'grid-cols-1'">
             <UFormField :label="t('board.addTask.pipeline')">
               <PipelinePicker
                 :model-value="pipelineId"
@@ -1124,8 +1134,12 @@ function openReviewFrictionDialog(conflict: NonNullable<ReturnType<typeof parseC
               />
             </UFormField>
 
-            <!-- A review task merges nothing, so its risk (merge) policy is meaningless — omit it. -->
-            <UFormField v-if="!isReview" :label="t('board.addTask.mergePolicy')">
+            <!-- A review task merges nothing, so its risk (merge) policy is meaningless — omit it.
+                 Basic mode leaves it (and the model preset below) on the workspace default. -->
+            <UFormField
+              v-if="!isReview && uiMode.isAdvanced"
+              :label="t('board.addTask.mergePolicy')"
+            >
               <RiskPolicyPicker
                 :model-value="riskPolicyId"
                 :options="riskPolicies.presets"
@@ -1136,7 +1150,7 @@ function openReviewFrictionDialog(conflict: NonNullable<ReturnType<typeof parseC
               />
             </UFormField>
 
-            <UFormField :label="t('board.addTask.modelPreset')">
+            <UFormField v-if="uiMode.isAdvanced" :label="t('board.addTask.modelPreset')">
               <UDropdownMenu :items="modelPresetMenu" class="w-full">
                 <UButton
                   color="neutral"
@@ -1184,8 +1198,11 @@ function openReviewFrictionDialog(conflict: NonNullable<ReturnType<typeof parseC
           </div>
 
           <!-- Best-practice fragments pinned on the task at creation, scoped to the frame's type.
-               Pre-seeded from the enclosing service's standards; the task owns them from here. -->
-          <div class="space-y-2">
+               Pre-seeded from the enclosing service's standards; the task owns them from here.
+               Hidden in basic mode: `fragmentIds` still carries the service-seeded selection, so
+               the task ships with its service's standards either way — advanced mode is what
+               lets you deviate from them per task. -->
+          <div v-if="uiMode.isAdvanced" class="space-y-2">
             <FragmentSelector
               v-model="fragmentIds"
               :pool="fragmentPool"
@@ -1349,10 +1366,12 @@ function openReviewFrictionDialog(conflict: NonNullable<ReturnType<typeof parseC
                 {{ t('board.addTask.attach') }}
               </UButton>
             </div>
+            <!-- The container is what scopes the issue search to a repo, so the picker is
+                 only rendered once we have one (the modal is open, so we always do). -->
             <ContextIssuePicker
-              v-if="showIssuePicker && issuesConnected"
+              v-if="showIssuePicker && issuesConnected && ui.addTaskContainerId"
               :chosen-keys="chosenIssueKeys"
-              :scope-block-id="ui.addTaskContainerId ?? undefined"
+              :scope-block-id="ui.addTaskContainerId"
               @pick="addPending"
             />
             <div v-if="pendingIssues.length" class="space-y-1">

package/app/components/layout/BoardSwitcher.vue

@@ -6,6 +6,13 @@ import type { CloudProvider } from '~/types/domain'
 // active board within it, and manages boards (new / rename / delete). The account
 // row is shown only when accounts exist (auth on); in dev it falls back to a plain
 // board switcher over the single unscoped context.
+//
+// `collapsed` renders the icon-only rail variant (the sidebar's collapsed state): the
+// account row folds away — it is a label with a menu duplicated inside the board menu's
+// reach — and the board button keeps only its glyph. Both dropdowns are unchanged, so
+// switching boards never requires expanding the sidebar first.
+withDefaults(defineProps<{ collapsed?: boolean }>(), { collapsed: false })
+
 const { t } = useI18n()
 
 const accounts = useAccountsStore()
@@ -245,9 +252,9 @@ async function submitPrompt() {
 
 <template>
   <div class="space-y-1.5">
-    <!-- account selector (only when accounts exist) -->
+    <!-- account selector (only when accounts exist, and not in the collapsed rail) -->
     <UDropdownMenu
-      v-if="accounts.enabled"
+      v-if="accounts.enabled && !collapsed"
       :items="accountItems"
       :content="{ align: 'start' }"
       class="w-full"
@@ -275,14 +282,24 @@ async function submitPrompt() {
     <UDropdownMenu :items="boardItems" :content="{ align: 'start' }" class="w-full">
       <button
         type="button"
+        :title="
+          collapsed
+            ? (workspace.activeWorkspace?.name ?? t('layout.boardSwitcher.boardFallback'))
+            : undefined
+        "
         class="flex w-full items-center gap-2 rounded-lg border border-slate-800 bg-slate-900/60 px-2.5 py-1.5 text-start transition hover:bg-slate-800/60"
+        :class="collapsed ? 'justify-center' : ''"
         :disabled="busy"
       >
         <UIcon name="i-lucide-layout-dashboard" class="h-4 w-4 shrink-0 text-indigo-400" />
-        <span class="truncate text-sm font-medium text-white">
+        <span v-if="!collapsed" class="truncate text-sm font-medium text-white">
           {{ workspace.activeWorkspace?.name ?? t('layout.boardSwitcher.boardFallback') }}
         </span>
-        <UIcon name="i-lucide-chevron-down" class="ms-auto h-4 w-4 shrink-0 text-slate-500" />
+        <UIcon
+          v-if="!collapsed"
+          name="i-lucide-chevron-down"
+          class="ms-auto h-4 w-4 shrink-0 text-slate-500"
+        />
       </button>
     </UDropdownMenu>
 

package/app/components/layout/CommandBar.vue

@@ -235,13 +235,14 @@ function indexOf(cmd: Command) {
 <template>
   <UModal v-model:open="open" :ui="{ content: 'max-w-xl' }">
     <template #content>
-      <div class="flex flex-col" @keydown="onKeydown">
+      <div class="flex flex-col" data-testid="command-bar" @keydown="onKeydown">
         <div class="flex items-center gap-2 border-b border-slate-800 px-3">
           <UIcon name="i-lucide-search" class="h-4 w-4 shrink-0 text-slate-500" />
           <UInput
             ref="inputRef"
             v-model="query"
             variant="none"
+            data-testid="command-bar-input"
             :placeholder="t('layout.commandBar.searchPlaceholder')"
             class="w-full"
             :ui="{ base: 'py-3 text-sm' }"
@@ -264,6 +265,7 @@ function indexOf(cmd: Command) {
               v-for="cmd in group.items"
               :key="cmd.id"
               type="button"
+              :data-testid="`command-${cmd.id}`"
               class="flex w-full items-center gap-2.5 rounded-md px-2 py-1.5 text-start text-sm transition"
               :class="
                 indexOf(cmd) === activeIndex

package/app/components/layout/LanguageSwitcher.vue

@@ -7,6 +7,11 @@ import { useLocaleStore } from '~/stores/locale'
 // the user menu. The list is data-driven from the i18n config (`useI18n().locales`), so
 // adding a locale in nuxt.config.ts surfaces it here automatically. Selecting one switches
 // the live locale AND persists the choice (the locale store) so it survives a reload.
+//
+// `collapsed` renders the icon-only rail variant (the sidebar's collapsed state); the
+// dropdown itself is unchanged, so the picker stays fully usable from the rail.
+withDefaults(defineProps<{ collapsed?: boolean }>(), { collapsed: false })
+
 const { t, locale, locales, setLocale } = useI18n()
 const localeStore = useLocaleStore()
 
@@ -39,16 +44,18 @@ const items = computed<DropdownMenuItem[][]>(() => [
       type="button"
       data-testid="language-switcher"
       :aria-label="t('language.switcher')"
+      :title="collapsed ? `${t('language.switcher')}: ${current}` : undefined"
       class="flex w-full items-center gap-2 rounded-lg border border-slate-800 bg-slate-900/60 p-2 text-start transition hover:bg-slate-800/60"
+      :class="collapsed ? 'justify-center' : ''"
     >
       <UIcon name="i-lucide-languages" class="h-4 w-4 shrink-0 text-slate-400" />
-      <div class="min-w-0 flex-1">
+      <div v-if="!collapsed" class="min-w-0 flex-1">
         <div class="truncate text-[10px] uppercase tracking-wide text-slate-500">
           {{ t('language.switcher') }}
         </div>
         <div class="truncate text-xs font-medium text-white">{{ current }}</div>
       </div>
-      <UIcon name="i-lucide-chevron-up" class="h-4 w-4 shrink-0 text-slate-500" />
+      <UIcon v-if="!collapsed" name="i-lucide-chevron-up" class="h-4 w-4 shrink-0 text-slate-500" />
     </button>
   </UDropdownMenu>
 </template>

package/app/components/layout/SideBar.vue

@@ -5,9 +5,15 @@
 // actions, repository management, integration management, the workspace-wide
 // 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 footer switcher / the 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 UserMenu from '~/components/auth/UserMenu.vue'
 import { useViewport } from '~/composables/useViewport'
 
@@ -34,6 +40,13 @@ const { sidebarGroups, invoke } = useNavContributions()
 // above it the aside is static and the drawer flag is inert.
 const { isCompact } = useViewport()
 
+// The collapsed RAIL: labels drop away and the aside narrows to its icons. Scoped to the
+// STATIC aside — an off-canvas drawer is already a deliberate, temporary reveal, so opening
+// 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 railed = computed(() => !isCompact.value && uiMode.navCollapsed)
+
 // The off-canvas drawer is a modal surface on compact viewports, so give it the
 // expected affordances:
 //   • Escape closes it (keyboard parity with the backdrop tap),
@@ -135,48 +148,87 @@ watch(
     :aria-label="isCompact ? t('nav.menu') : undefined"
     :inert="isCompact && !ui.mobileNavOpen"
     class="fixed inset-y-0 start-0 z-40 flex h-full w-64 shrink-0 flex-col gap-4 overflow-y-auto border-e border-slate-800 bg-slate-900/95 px-3 pt-3 pb-[calc(0.75rem+env(safe-area-inset-bottom))] backdrop-blur transition-transform duration-200 focus:outline-none lg:static lg:z-auto lg:translate-x-0 lg:bg-slate-900/80"
-    :class="
-      ui.mobileNavOpen ? 'translate-x-0' : '-translate-x-full rtl:translate-x-full lg:translate-x-0'
-    "
+    :class="[
+      ui.mobileNavOpen
+        ? 'translate-x-0'
+        : '-translate-x-full rtl:translate-x-full lg:translate-x-0',
+      // The rail is lg-only (see `railed`), so the narrow width is too — below lg the drawer
+      // keeps its full width whatever the collapse state says.
+      railed ? 'lg:w-14 lg:px-2' : '',
+    ]"
+    :data-collapsed="railed ? 'true' : 'false'"
   >
-    <BoardSwitcher />
+    <!-- Rail toggle. lg-only: below it the hamburger + backdrop already own showing and
+         hiding the whole navbar, and a second collapse control there would fight them. -->
+    <!-- The panel glyphs are drawn for a left-hand navbar; under RTL the aside is `start`-anchored
+         to the right, so mirror them like the other directional icons in the SPA. -->
+    <UButton
+      class="hidden shrink-0 lg:flex"
+      :class="railed ? 'justify-center' : 'justify-end'"
+      :ui="{ leadingIcon: 'rtl:-scale-x-100' }"
+      :icon="railed ? 'i-lucide-panel-left-open' : 'i-lucide-panel-left-close'"
+      color="neutral"
+      variant="ghost"
+      size="xs"
+      :aria-label="railed ? t('nav.expandSidebar') : t('nav.collapseSidebar')"
+      :title="railed ? t('nav.expandSidebar') : t('nav.collapseSidebar')"
+      :aria-expanded="!railed"
+      data-testid="sidebar-collapse-toggle"
+      @click="uiMode.toggleNav()"
+    />
+
+    <BoardSwitcher :collapsed="railed" />
 
     <div class="contents" @click="onNavAction">
       <!-- Command bar launcher (⌘K) — the primary way to create blocks / pipelines
          and reach every action below. -->
       <button
         type="button"
-        class="flex items-center gap-2 rounded-lg border border-slate-700 bg-slate-800/60 px-2.5 py-2 text-start text-sm text-slate-400 transition hover:border-slate-500 hover:bg-slate-800"
+        class="flex items-center gap-2 rounded-lg border border-slate-700 bg-slate-800/60 py-2 text-start text-sm text-slate-400 transition hover:border-slate-500 hover:bg-slate-800"
+        :class="railed ? 'justify-center px-0' : 'px-2.5'"
+        :aria-label="t('nav.commandBar')"
+        :title="railed ? t('nav.commandBar') : undefined"
+        data-testid="command-bar-launcher"
         @click="ui.openCommandBar()"
       >
         <UIcon name="i-lucide-search" class="h-4 w-4 shrink-0" />
-        <span class="flex-1 truncate">{{ t('nav.commandBar') }}</span>
-        <UKbd value="⌘K" />
+        <span v-if="!railed" class="flex-1 truncate">{{ t('nav.commandBar') }}</span>
+        <UKbd v-if="!railed" value="⌘K" />
       </button>
 
       <!-- Sections + items come from the shared nav manifest, already gated by the
-         reactive slotFilter (docs/initiatives/modular-vue-adoption.md, slice 1). An
-         empty section is dropped upstream, so there is no per-section `v-if` here. -->
+         reactive slotFilter (docs/initiatives/modular-vue-adoption.md, slice 1) — which
+         also drops the `advanced` items in basic interface mode. An empty section is
+         dropped upstream, so there is no per-section `v-if` here.
+         In the rail the section HEADERS go (they'd wrap to nothing at 3.5rem) but the
+         separators stay, so the grouping is still legible as icon clusters. -->
       <template v-for="section in sidebarGroups" :key="section.group">
         <USeparator />
         <section>
-          <h2 class="mb-2 px-1 text-[11px] font-semibold uppercase tracking-wide text-slate-400">
+          <h2
+            v-if="!railed"
+            class="mb-2 px-1 text-[11px] font-semibold uppercase tracking-wide text-slate-400"
+          >
             {{ t(section.labelKey) }}
           </h2>
           <div class="space-y-1.5">
             <UButton
               v-for="item in section.items"
               :key="item.id"
-              block
+              :block="!railed"
               color="primary"
               variant="soft"
               size="sm"
               :icon="item.icon"
-              class="justify-start"
+              :square="railed"
+              class="w-full"
+              :class="railed ? 'justify-center' : 'justify-start'"
+              :aria-label="railed ? t(item.labelKey) : undefined"
+              :title="railed ? t(item.labelKey) : undefined"
               :data-testid="item.testId"
               @click="invoke(item)"
             >
-              {{ t(item.labelKey) }}
+              <span v-if="!railed">{{ t(item.labelKey) }}</span>
             </UButton>
           </div>
         </section>
@@ -184,8 +236,9 @@ watch(
     </div>
 
     <div class="mt-auto space-y-2">
-      <LanguageSwitcher />
-      <UserMenu />
+      <UiModeSwitcher :collapsed="railed" />
+      <LanguageSwitcher :collapsed="railed" />
+      <UserMenu :collapsed="railed" />
     </div>
   </aside>
 </template>

package/app/components/layout/UiModeSwitcher.vue

@@ -0,0 +1,90 @@
+<script setup lang="ts">
+import type { DropdownMenuItem } from '@nuxt/ui'
+import { computed } from 'vue'
+import { UI_MODES, type UiMode } from '~/utils/uiMode'
+
+// Interface-tier picker, shown at the sidebar bottom next to the language switcher (the
+// same shape, deliberately: both are per-user shell preferences rather than board state).
+// Basic mode hides the power-user destinations and the less-used run options; advanced
+// shows everything. The user's pick is persisted client-side — unless the deployment pinned
+// the tier via NUXT_PUBLIC_UI_MODE, in which case the row is a read-only indicator, since
+// writing a preference the resolver ignores would be a lie (see `stores/uiMode.ts`).
+withDefaults(defineProps<{ collapsed?: boolean }>(), { collapsed: false })
+
+const uiMode = useUiModeStore()
+const { t } = useI18n()
+
+// Static literal `t()` keys, one per UI_MODES member, so the typed-message-keys check sees
+// them (a runtime-assembled key wouldn't be checkable).
+const MODE_LABELS: Record<UiMode, string> = {
+  basic: 'uiMode.basic',
+  advanced: 'uiMode.advanced',
+}
+const MODE_HINTS: Record<UiMode, string> = {
+  basic: 'uiMode.basicHint',
+  advanced: 'uiMode.advancedHint',
+}
+
+const currentLabel = computed(() => t(MODE_LABELS[uiMode.mode]))
+const icon = computed(() => (uiMode.isAdvanced ? 'i-lucide-toggle-right' : 'i-lucide-toggle-left'))
+/** Tooltip for the collapsed rail (and the pinned row): mode + why it can't be changed. */
+const title = computed(() =>
+  uiMode.envPinned
+    ? `${t('uiMode.switcher')}: ${currentLabel.value} (${t('uiMode.pinned')})`
+    : `${t('uiMode.switcher')}: ${currentLabel.value}`,
+)
+
+const items = computed<DropdownMenuItem[][]>(() => [
+  UI_MODES.map((mode) => ({
+    label: t(MODE_LABELS[mode]),
+    icon: mode === uiMode.mode ? 'i-lucide-check' : undefined,
+    onSelect: () => uiMode.setMode(mode),
+  })),
+])
+</script>
+
+<template>
+  <!-- Pinned by the deployment: no dropdown, just the current tier. -->
+  <div
+    v-if="uiMode.envPinned"
+    data-testid="ui-mode-pinned"
+    :title="title"
+    class="flex w-full items-center gap-2 rounded-lg border border-slate-800 bg-slate-900/40 p-2 text-start"
+    :class="collapsed ? 'justify-center' : ''"
+  >
+    <UIcon :name="icon" class="h-4 w-4 shrink-0 text-slate-500" />
+    <div v-if="!collapsed" class="min-w-0 flex-1">
+      <div class="truncate text-[10px] uppercase tracking-wide text-slate-500">
+        {{ t('uiMode.switcher') }}
+      </div>
+      <div class="truncate text-xs font-medium text-slate-300">{{ currentLabel }}</div>
+    </div>
+    <UIcon v-if="!collapsed" name="i-lucide-lock" class="h-3.5 w-3.5 shrink-0 text-slate-600" />
+  </div>
+
+  <UDropdownMenu v-else :items="items" :content="{ side: 'top', align: 'start' }">
+    <button
+      type="button"
+      data-testid="ui-mode-switcher"
+      :aria-label="t('uiMode.switcher')"
+      :title="title"
+      class="flex w-full items-center gap-2 rounded-lg border border-slate-800 bg-slate-900/60 p-2 text-start transition hover:bg-slate-800/60"
+      :class="collapsed ? 'justify-center' : ''"
+    >
+      <UIcon :name="icon" class="h-4 w-4 shrink-0 text-slate-400" />
+      <div v-if="!collapsed" class="min-w-0 flex-1">
+        <div class="truncate text-[10px] uppercase tracking-wide text-slate-500">
+          {{ t('uiMode.switcher') }}
+        </div>
+        <div class="truncate text-xs font-medium text-white">{{ currentLabel }}</div>
+      </div>
+      <UIcon v-if="!collapsed" name="i-lucide-chevron-up" class="h-4 w-4 shrink-0 text-slate-500" />
+    </button>
+  </UDropdownMenu>
+
+  <!-- The one-line "what this tier gives you", so the choice is self-explanatory. Dropped in
+       the collapsed rail, where the tooltip above carries the mode instead. -->
+  <p v-if="!collapsed" class="px-1 text-[10px] leading-snug text-slate-500">
+    {{ t(MODE_HINTS[uiMode.mode]) }}
+  </p>
+</template>

package/app/components/observability/StepMetricsBar.vue

@@ -4,10 +4,10 @@ import type { StepMetrics } from '~/types/execution'
 import {
   formatMs,
   formatTokens,
-  freshPromptTokens,
   headroomColor,
   headroomRatio,
   pct,
+  totalInputTokens,
   transportRatio,
 } from '~/utils/observability'
 
@@ -23,12 +23,16 @@ defineEmits<{ inspect: [] }>()
 const { t } = useI18n()
 
 const m = computed(() => props.metrics)
-// The headline "↑" is FRESH (uncached) input, not the raw prompt-token sum: a long agentic
-// run re-sends its whole transcript every turn, so the raw sum is ~all cache reads and reads
-// as a blow-up. The cached prefix is shown separately (the green chip) so the two are distinct.
-const freshPrompt = computed(() =>
-  freshPromptTokens(m.value.promptTokens, m.value.cachedPromptTokens ?? 0),
-)
+// The headline "↑" is TOTAL input — fresh + both cache classes — the like-for-like measure of
+// Claude Code's own context gauge, which counts the same buckets because a cached token still
+// occupies the context window (see `totalInputTokens`). The three classes then render as the
+// breakdown, because they are priced an order of magnitude apart in opposite directions: a read
+// is ~0.1x base input, a write 1.25-2x. Volume in the headline, cost in the breakdown — leading
+// with fresh made a 31M-token run read as a 685-token one.
+const totalInput = computed(() => totalInputTokens(m.value))
+const cacheRead = computed(() => m.value.cacheReadTokens ?? 0)
+const cacheWrite = computed(() => m.value.cacheWriteTokens ?? 0)
+const hasCache = computed(() => cacheRead.value > 0 || cacheWrite.value > 0)
 const headroom = computed(() => headroomRatio(m.value))
 const transport = computed(() => transportRatio(m.value))
 const headroomTone = computed(() => headroomColor(headroom.value, m.value.truncatedCalls > 0))
@@ -53,20 +57,9 @@ const headroomTone = computed(() => headroomColor(headroom.value, m.value.trunca
       <span class="text-slate-500">·</span>
       <span
         class="tabular-nums text-slate-400"
-        :title="t('observability.metricsBar.promptCompletionTokens')"
+        :title="t('observability.metricsBar.inputCompletionTokens')"
       >
-        {{ formatTokens(freshPrompt) }}↑ {{ formatTokens(m.completionTokens) }}↓
-      </span>
-      <span
-        v-if="(m.cachedPromptTokens ?? 0) > 0"
-        class="tabular-nums text-emerald-400/80"
-        :title="t('observability.metricsBar.cachedTokensHint')"
-      >
-        {{
-          t('observability.metricsBar.cachedTokens', {
-            tokens: formatTokens(m.cachedPromptTokens ?? 0),
-          })
-        }}
+        {{ formatTokens(totalInput) }}↑ {{ formatTokens(m.completionTokens) }}↓
       </span>
       <div class="ms-auto flex items-center gap-1">
         <UBadge v-if="m.errors > 0" color="error" variant="subtle" size="sm">
@@ -83,6 +76,29 @@ const headroomTone = computed(() => headroomColor(headroom.value, m.value.trunca
       </div>
     </div>
 
+    <!-- input breakdown: the headline's three classes, priced an order of magnitude apart -->
+    <div v-if="hasCache" class="mt-1.5 flex items-center gap-1.5 text-[11px] tabular-nums">
+      <span class="text-slate-400" :title="t('observability.metricsBar.freshHint')">
+        {{ t('observability.metricsBar.fresh', { tokens: formatTokens(m.promptTokens) }) }}
+      </span>
+      <span v-if="cacheRead > 0" class="text-slate-600">·</span>
+      <span
+        v-if="cacheRead > 0"
+        class="text-emerald-400/80"
+        :title="t('observability.metricsBar.cacheReadHint')"
+      >
+        {{ t('observability.metricsBar.cacheRead', { tokens: formatTokens(cacheRead) }) }}
+      </span>
+      <span v-if="cacheWrite > 0" class="text-slate-600">·</span>
+      <span
+        v-if="cacheWrite > 0"
+        class="text-amber-400/80"
+        :title="t('observability.metricsBar.cacheWriteHint')"
+      >
+        {{ t('observability.metricsBar.cacheWrite', { tokens: formatTokens(cacheWrite) }) }}
+      </span>
+    </div>
+
     <!-- output-limit headroom -->
     <div v-if="headroom !== null" class="mt-2">
       <div class="flex items-center justify-between text-[11px]">