@cat-factory/app 0.167.0 → 0.168.0

package/app/components/settings/ConnectionWarnings.vue

@@ -0,0 +1,38 @@
+<script setup lang="ts">
+// The non-fatal GAPS a connection test reports about the config it just probed: it connects,
+// but something it never declared costs a recovery or cleanup path that only shows itself
+// during an incident (a runner-pool manifest with no `release` template leaks a runner on
+// every cancelled run).
+//
+// Rendered beside the pass/fail verdict rather than as part of it, because the two are
+// independent — a green test with a gap is the common case, and folding the gap into the
+// failure line would make a working connection look broken.
+//
+// The backend sends machine-readable codes (it does not localize prose); the copy lives in the
+// catalog behind `CONNECTION_WARNING_KEYS`. A code this SPA build predates falls back to the
+// backend's own English `message` — untranslated, but never a blank row.
+import type { ConnectionWarning } from '@cat-factory/contracts'
+import { CONNECTION_WARNING_KEYS } from '~/utils/connectionWarnings'
+
+defineProps<{ warnings?: ConnectionWarning[] }>()
+
+const { t, te } = useI18n()
+
+const copy = (warning: ConnectionWarning): string => {
+  const key = CONNECTION_WARNING_KEYS[warning.code]
+  return key && te(key) ? t(key) : warning.message
+}
+</script>
+
+<template>
+  <div
+    v-if="warnings?.length"
+    class="rounded-md border border-amber-500/40 bg-amber-950/40 px-3 py-2 text-xs text-amber-200"
+    data-testid="connection-warnings"
+  >
+    <p class="font-semibold">{{ t('settings.providerConnection.test.warningsTitle') }}</p>
+    <ul class="mt-1 list-disc space-y-1 pl-4">
+      <li v-for="warning in warnings" :key="warning.code">{{ copy(warning) }}</li>
+    </ul>
+  </div>
+</template>

package/app/components/settings/KubernetesEnvironmentForm.vue

@@ -10,6 +10,8 @@
 // driven (see docs/initiatives/descriptor-driven-infra-forms.md).
 import { computed, reactive, ref, watch } from 'vue'
 import { KUBERNETES_ENV_TOKEN_SECRET_KEY } from '@cat-factory/contracts'
+import type { ConnectionTestResult } from '@cat-factory/contracts'
+import ConnectionWarnings from '~/components/settings/ConnectionWarnings.vue'
 import SecretInput from '~/components/common/SecretInput.vue'
 import type { ProviderConnection } from '~/types/providerConnections'
 
@@ -18,7 +20,7 @@ const props = defineProps<{
   supportsTest: boolean
   testing: boolean
   busy: boolean
-  testResult: { ok: boolean; message?: string } | null
+  testResult: ConnectionTestResult | null
 }>()
 
 const emit = defineEmits<{
@@ -409,6 +411,8 @@ function optional(label: string): string {
       </span>
     </div>
 
+    <ConnectionWarnings :warnings="testResult?.warnings" />
+
     <div class="flex items-center justify-end gap-3">
       <p v-if="connectBlockedReason" class="flex-1 text-left text-xs text-rose-400">
         {{ connectBlockedReason }}

package/app/components/settings/ProviderConnectionTab.vue

@@ -12,7 +12,9 @@
 //   - a MANIFEST-driven provider (no template) → the full JSON manifest editor
 //     (ProviderManifestEditor), which replaces the old "use the API" disclaimer.
 import { computed, ref, toRaw, watch } from 'vue'
+import type { ConnectionTestResult } from '@cat-factory/contracts'
 import type { ProviderConfigField, ProviderConnectionKind } from '~/types/providerConnections'
+import ConnectionWarnings from '~/components/settings/ConnectionWarnings.vue'
 import ProvisioningLogsDrawer from '~/components/provisioning/ProvisioningLogsDrawer.vue'
 import ProviderManifestEditor from '~/components/settings/ProviderManifestEditor.vue'
 import KubernetesEnvironmentForm from '~/components/settings/KubernetesEnvironmentForm.vue'
@@ -56,7 +58,7 @@ const showLogs = ref(false)
 
 // --- Shared state -------------------------------------------------------------------
 const values = ref<Record<string, string>>({})
-const testResult = ref<{ ok: boolean; message?: string } | null>(null)
+const testResult = ref<ConnectionTestResult | null>(null)
 const testing = ref(false)
 const busy = ref(false)
 
@@ -515,6 +517,8 @@ function fieldHelp(key: string): string | undefined {
         </span>
       </div>
 
+      <ConnectionWarnings :warnings="testResult?.warnings" />
+
       <div class="flex justify-end">
         <UButton
           color="primary"

package/app/components/settings/ProviderManifestEditor.vue

@@ -17,7 +17,9 @@
 import { computed, ref, watch } from 'vue'
 import * as v from 'valibot'
 import { environmentManifestSchema, runnerPoolManifestSchema } from '@cat-factory/contracts'
+import type { ConnectionTestResult } from '@cat-factory/contracts'
 import type { ProviderConnectionKind } from '~/types/providerConnections'
+import ConnectionWarnings from '~/components/settings/ConnectionWarnings.vue'
 import SecretInput from '~/components/common/SecretInput.vue'
 
 const props = defineProps<{
@@ -34,7 +36,7 @@ const props = defineProps<{
   /** Bubbled-up busy state from the tab's store calls (so the editor shows loading). */
   testing: boolean
   busy: boolean
-  testResult: { ok: boolean; message?: string } | null
+  testResult: ConnectionTestResult | null
 }>()
 
 const emit = defineEmits<{
@@ -286,6 +288,8 @@ function onSave() {
       </span>
     </div>
 
+    <ConnectionWarnings :warnings="testResult?.warnings" />
+
     <div class="flex justify-end">
       <UButton
         color="primary"

package/app/components/tasks/BugHuntModal.vue

@@ -10,6 +10,7 @@
 // unavailable or failed still shows its candidates (flagged as unassessed, since the scan is
 // useful on its own), and a scan that hit its cap says so — a silently shortened list reads
 // exactly like an exhaustive one.
+import type { TaskSourceReadReason } from '@cat-factory/contracts'
 import type {
   BugHuntAnalysisStatus,
   BugHuntCandidate,
@@ -69,8 +70,9 @@ const boardItems = computed(() =>
  * backend's reason code, not on "any error": an unreachable tracker or an expired token would
  * otherwise present as a free-text field that simply moves the same failure to the next click.
  */
+const BOARDS_UNSUPPORTED: TaskSourceReadReason = 'boards_unsupported'
 const boardIsFreeText = computed(
-  () => !hunt.boardsLoading && hunt.boardsErrorReason === 'boards_unsupported',
+  () => !hunt.boardsLoading && hunt.boardsErrorReason === BOARDS_UNSUPPORTED,
 )
 
 /** A board read that failed for a reason the user has to fix — shown, never silently swallowed. */

package/app/components/tasks/ContextIssuePicker.vue

@@ -7,12 +7,19 @@
 // them once the block exists (see useContextLinking). A search hit / pasted ref
 // carries `needsImport: true` so it's fetched + persisted before linking.
 //
+// Search results are always confined to ONE repository (`scopeBlockId`'s service).
+// An issue in another repo is reachable only by pasting its URL, which the explicit
+// "attach by reference" row below imports directly — it never comes back as a hit,
+// so what the search offers is exactly what the service owns.
+//
 // The tracker being searched is ALWAYS on screen (even when the workspace offers
 // exactly one), and its menu doubles as the "add a tracker" affordance: attaching a
 // context issue is where a missing integration is discovered, and the connect modal
 // opens over the caller's form rather than navigating away from it.
 import type { DropdownMenuItem } from '@nuxt/ui'
+import type { TaskSourceReadReason } from '@cat-factory/contracts'
 import type { SourceTask, TaskSearchResult, TaskSourceKind } from '~/types/domain'
+import { apiErrorReason } from '~/composables/api/errors'
 import EmptyState from '~/components/common/EmptyState.vue'
 import { buildSourceChoices, reconcileSource } from '~/components/tasks/ContextIssuePicker.logic'
 
@@ -21,10 +28,13 @@ const props = defineProps<{
   chosenKeys?: string[]
   /**
    * The block the picker is attaching context to (a service frame or a task/module
-   * under one). Scopes a GitHub search to that service's linked repo, so hits stay
-   * in-repo and a pasted URL / bare issue number resolves to the exact issue.
+   * under one). REQUIRED: it is what scopes a GitHub search to that service's linked
+   * repo, so hits stay in-repo and a bare issue number resolves to the exact issue.
+   * A search with no scope reaches every repository the deployment's credential can
+   * see (under a PAT, all of public GitHub), so there is no unscoped mode — a caller
+   * that has no block yet must not render the picker.
    */
-  scopeBlockId?: string
+  scopeBlockId: string
   /**
    * Controlled source: when provided the parent owns the selected tracker (via
    * `v-model:source`); omitted, the picker manages it internally (the add-task case).
@@ -147,7 +157,14 @@ async function runSearch() {
     results.value = await tasks.search(source.value, q, props.scopeBlockId)
   } catch (e) {
     results.value = []
-    searchError.value = e instanceof Error ? e.message : String(e)
+    // "This service has no repo" is the one failure with an action attached, so it gets its
+    // own localized copy off the backend's machine-readable reason rather than the raw
+    // message (CLAUDE.md "Backend strings"). Anything else keeps the generic wording.
+    const notLinked: TaskSourceReadReason = 'repo_not_linked'
+    searchError.value =
+      apiErrorReason(e) === notLinked
+        ? t('tasks.picker.searchNeedsRepo')
+        : t('tasks.picker.searchFailed', { error: e instanceof Error ? e.message : String(e) })
   } finally {
     searching.value = false
   }
@@ -295,7 +312,7 @@ onMounted(() => {
     />
 
     <p v-if="searchError" class="px-1 text-[11px] text-amber-400">
-      {{ t('tasks.picker.searchFailed', { error: searchError }) }}
+      {{ searchError }}
     </p>
 
     <div class="max-h-56 space-y-0.5 overflow-y-auto">

package/app/components/tasks/TaskImportModal.vue

@@ -163,7 +163,7 @@ async function doSpawnEpic() {
              or paste a URL/key — choosing one opens the prefilled add-task form. The
              search is scoped to the chosen container's repo (so a GitHub search stays
              in that service's repo and a pasted URL / bare number resolves there). -->
-        <UFormField :label="t('tasks.import.searchIssues')">
+        <UFormField v-if="containerId" :label="t('tasks.import.searchIssues')">
           <ContextIssuePicker
             v-model:source="source"
             :scope-block-id="containerId"

package/app/composables/api/errors.ts

@@ -54,6 +54,22 @@ export function apiErrorEnvelope(error: unknown): ApiErrorEnvelope | undefined {
   return envelopeOf(e?.body) ?? envelopeOf(e?.data)
 }
 
+/**
+ * The backend's machine-readable `error.details.reason` code, when it sent one.
+ *
+ * This is the client half of the "backend strings" contract (see CLAUDE.md): a localizable
+ * server condition emits a stable code and the SPA maps it to a message key, with the raw
+ * prose `message` as the untranslated last resort. Callers compare the result against a union
+ * imported from `@cat-factory/contracts`, so a renamed code fails the typecheck instead of
+ * silently falling through to the generic wording.
+ */
+export function apiErrorReason(error: unknown): string | null {
+  const details = apiErrorEnvelope(error)?.details
+  if (!details || typeof details !== 'object') return null
+  const reason = (details as Record<string, unknown>).reason
+  return typeof reason === 'string' ? reason : null
+}
+
 /** The HTTP status of a thrown API error, when present (contract client or `$fetch`). */
 export function apiErrorStatus(error: unknown): number | undefined {
   const e = error as { statusCode?: unknown; status?: unknown }

package/app/composables/api/tasks.ts

@@ -71,16 +71,19 @@ export function tasksApi({ send, ws }: ApiContext) {
     importTask: (workspaceId: string, source: TaskSourceKind, body: { ref: string }) =>
       send(importTaskContract, { pathPrefix: ws(workspaceId), pathParams: { source }, body }),
 
+    // `blockId` is required: it is what scopes a GitHub search to the block's service
+    // repo, and the backend refuses an unscoped one (it would reach every repository the
+    // deployment's credential can see).
     searchTaskSource: (
       workspaceId: string,
       source: TaskSourceKind,
       query: string,
-      blockId?: string,
+      blockId: string,
     ) =>
       send(searchTasksContract, {
         pathPrefix: ws(workspaceId),
         pathParams: { source },
-        body: { query, ...(blockId ? { blockId } : {}) },
+        body: { query, blockId },
       }),
 
     linkTask: (

package/app/composables/useNavContributions.ts

@@ -47,6 +47,9 @@ export function useNavContributions() {
     operatorDashboard: () => ui.openOperatorDashboard(),
     reports: () => ui.openReports(),
     shortcuts: () => ui.openShortcutsHelp(),
+    // 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(),
   }
 
   /** Run a contribution's action (consumer `run` closure wins over the id map). */

package/app/docs/consumer-extensions.md

@@ -61,12 +61,17 @@ 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?, formPanel? }`             | `AddTaskModal` picker/fields + `TaskCard` badge (via `taskTypeMeta`) |
-| Sidebar / command-palette / toolbar | `nav`             | `{ id, labelKey, icon, surfaces, gate?, run, sidebar?, command?, toolbar? }`                     | the three shells via `useNavContributions`                           |
+| Sidebar / command-palette / toolbar | `nav`             | `{ id, labelKey, icon, surfaces, gate?, advanced?, 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)`                   |
 | 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
+[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.
+
 ### Run-detail windows (`resultViews` + `agentKinds`)
 
 Backend data selects a frontend component, joined by a namespaced id:

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

@@ -32,6 +32,9 @@ const NO_GATES: NavGates = {
   infrastructureAvailable: false,
   accountsEnabled: false,
   isAccountAdmin: false,
+  // The permission axis is what these cases vary; keep the interface tier at `advanced`
+  // so a dropped item is unambiguously an RBAC/availability drop, not a tier drop.
+  advancedMode: true,
 }
 
 const ALL_GATES: NavGates = {
@@ -43,6 +46,7 @@ const ALL_GATES: NavGates = {
   infrastructureAvailable: true,
   accountsEnabled: true,
   isAccountAdmin: true,
+  advancedMode: true,
 }
 
 const slots = (): AppSlots => ({
@@ -84,6 +88,58 @@ describe('navSlotFilter', () => {
     const kept = ids(navSlotFilter(slots(), {}))
     expect(kept.sort()).toEqual(NAV_CONTRIBUTIONS.map((i) => i.id).sort())
   })
+
+  it('drops every advanced destination in basic interface mode', () => {
+    const gates: NavGates = { ...ALL_GATES, advancedMode: false }
+    const kept = ids(navSlotFilter(slots(), { gates }))
+    const basicOnly = NAV_CONTRIBUTIONS.filter((i) => !i.advanced).map((i) => i.id)
+    expect(kept.sort()).toEqual(basicOnly.sort())
+    // The everyday surface survives...
+    expect(kept).toContain('add-from-repo')
+    expect(kept).toContain('integrations-hub')
+    expect(kept).toContain('workspace-settings')
+    expect(kept).toContain('model-config')
+    // ...and the authoring / operator surfaces don't.
+    expect(kept).not.toContain('build-pipeline')
+    expect(kept).not.toContain('fragments')
+    expect(kept).not.toContain('sandbox')
+    expect(kept).not.toContain('operator-dashboard')
+  })
+
+  it('keeps the tier switch itself reachable in basic mode', () => {
+    // Basic is the shipped default, so this palette entry is how a user who never finds the
+    // (icon-only, in the basic rail) sidebar switcher gets to the advanced half at all. Marking
+    // it `advanced` would hide the way back from exactly the tier that needs it.
+    const uiModeItem = NAV_CONTRIBUTIONS.find((i) => i.id === 'ui-mode')
+    expect(uiModeItem?.advanced).toBeUndefined()
+    expect(uiModeItem?.gate).toBeUndefined()
+
+    const gates: NavGates = { ...NO_GATES, advancedMode: false }
+    expect(ids(navSlotFilter(slots(), { gates }))).toContain('ui-mode')
+  })
+
+  it('keeps the tier and the permission axes independent — both must pass', () => {
+    // `build-pipeline` is advanced AND needs board.write: neither axis alone reveals it.
+    const advancedOnly: NavGates = { ...NO_GATES, advancedMode: true }
+    expect(ids(navSlotFilter(slots(), { gates: advancedOnly }))).not.toContain('build-pipeline')
+
+    const permissionOnly: NavGates = { ...NO_GATES, canWriteBoard: true, advancedMode: false }
+    expect(ids(navSlotFilter(slots(), { gates: permissionOnly }))).not.toContain('build-pipeline')
+
+    const both: NavGates = { ...NO_GATES, canWriteBoard: true, advancedMode: true }
+    expect(ids(navSlotFilter(slots(), { gates: both }))).toContain('build-pipeline')
+  })
+
+  it('leaves at least one sidebar destination in every basic-mode section it keeps', () => {
+    // A section whose every item is advanced is dropped wholesale upstream (groupSidebar drops
+    // empties), which is intended — but a basic-mode sidebar with NO destinations at all would
+    // be a broken shell, so pin that the everyday surface is non-empty.
+    const gates: NavGates = { ...ALL_GATES, advancedMode: false }
+    const kept = (navSlotFilter(slots(), { gates }) as AppSlots).nav
+    const groups = groupSidebar(kept)
+    expect(groups.length).toBeGreaterThan(0)
+    for (const group of groups) expect(group.items.length).toBeGreaterThan(0)
+  })
 })
 
 describe('NAV_CONTRIBUTIONS catalog integrity', () => {
@@ -172,7 +228,8 @@ describe('nav grouping helpers', () => {
 
   it('groupCommands preserves the pre-slice-1 workspace-group order', () => {
     const workspace = groupCommands(NAV_CONTRIBUTIONS).find((g) => g.group === 'workspace')
-    // Same order the old CommandBar pushed them in (parity, not a reorder).
+    // Same order the old CommandBar pushed them in (parity, not a reorder), with genuinely
+    // new entries appended after it rather than interleaved.
     expect(workspace?.items.map((ci) => ci.item.id)).toEqual([
       'fragments',
       'merge-thresholds',
@@ -182,6 +239,7 @@ describe('nav grouping helpers', () => {
       'local-models',
       'sandbox',
       'keyboard-shortcuts',
+      'ui-mode',
     ])
   })
 

package/app/modular/nav-contributions.ts

@@ -60,6 +60,12 @@ export interface NavGates {
   accountsEnabled: boolean
   /** The caller is an admin of the active account. */
   isAccountAdmin: boolean
+  /**
+   * The interface tier is `advanced` (see `stores/uiMode.ts`). Read by
+   * {@link navSlotFilter} for every {@link NavContribution.advanced} item, and
+   * available to a `gate` predicate that needs to combine it with something else.
+   */
+  advancedMode: boolean
 }
 
 /** Command-palette placement + copy for a contribution that appears in the palette. */
@@ -98,6 +104,7 @@ export const NAV_ACTIONS = [
   'operatorDashboard',
   'reports',
   'shortcuts',
+  'toggleUiMode',
 ] as const
 
 export type NavActionId = (typeof NAV_ACTIONS)[number]
@@ -111,6 +118,13 @@ export interface NavContribution {
   surfaces: readonly NavSurface[]
   /** Reactive predicate over {@link NavGates}; absent = always visible. */
   gate?: (g: NavGates) => boolean
+  /**
+   * A power-user destination: shown only in ADVANCED interface mode (basic mode is the
+   * everyday surface — see `stores/uiMode.ts`). Declarative rather than folded into
+   * {@link gate}, so an item keeps its RBAC/availability predicate unchanged and the two
+   * axes stay independently assertable. Absent = visible in both tiers.
+   */
+  advanced?: boolean
   /**
    * First-party action id, resolved to a `run()` against the host `ui` store by
    * `useNavContributions`. A consumer module that has its own stores instead
@@ -138,6 +152,14 @@ const S = (...s: NavSurface[]) => s as readonly NavSurface[]
  *    previously showed it unconditionally; the account modal only makes sense
  *    with accounts enabled).
  *  - one icon per destination across shells.
+ *
+ * `advanced: true` marks the power-user half, hidden in basic interface mode. The line
+ * drawn here is "would a team shipping their first task open this?": connecting a repo or
+ * an integration, picking models, and the workspace/account settings stay; AUTHORING the
+ * machinery those defaults come from (the pipeline builder, the fragment library, merge
+ * thresholds, service fragment defaults), the experimentation surfaces (sandbox, Kaizen),
+ * the infrastructure/environment plumbing, per-user local models, and the operator-tier
+ * dashboards do not.
  */
 export const NAV_CONTRIBUTIONS: readonly NavContribution[] = [
   {
@@ -145,6 +167,7 @@ export const NAV_CONTRIBUTIONS: readonly NavContribution[] = [
     labelKey: 'nav.buildPipeline',
     icon: 'i-lucide-workflow',
     surfaces: S('sidebar', 'command'),
+    advanced: true,
     gate: (g) => g.canWriteBoard,
     action: 'buildPipeline',
     testId: 'nav-build-pipeline',
@@ -203,6 +226,7 @@ export const NAV_CONTRIBUTIONS: readonly NavContribution[] = [
     labelKey: 'nav.sandbox',
     icon: 'i-lucide-flask-conical',
     surfaces: S('sidebar', 'command'),
+    advanced: true,
     gate: (g) => g.canManageIntegrations,
     action: 'sandbox',
     testId: 'nav-sandbox',
@@ -219,6 +243,7 @@ export const NAV_CONTRIBUTIONS: readonly NavContribution[] = [
     labelKey: 'nav.kaizen',
     icon: 'i-lucide-sparkles',
     surfaces: S('sidebar'),
+    advanced: true,
     action: 'kaizen',
     testId: 'nav-kaizen',
     sidebar: { group: 'integrations', order: 30 },
@@ -228,6 +253,7 @@ export const NAV_CONTRIBUTIONS: readonly NavContribution[] = [
     labelKey: 'nav.infrastructure',
     icon: 'i-lucide-server-cog',
     surfaces: S('sidebar'),
+    advanced: true,
     gate: (g) => g.infrastructureAvailable,
     action: 'infrastructure',
     testId: 'nav-infrastructure',
@@ -238,6 +264,7 @@ export const NAV_CONTRIBUTIONS: readonly NavContribution[] = [
     labelKey: 'nav.environmentSetup',
     icon: 'i-lucide-flask-conical',
     surfaces: S('sidebar'),
+    advanced: true,
     gate: (g) => g.infrastructureAvailable,
     action: 'environmentSetup',
     testId: 'nav-environment-setup',
@@ -248,6 +275,7 @@ export const NAV_CONTRIBUTIONS: readonly NavContribution[] = [
     labelKey: 'nav.contextFragments',
     icon: 'i-lucide-book-marked',
     surfaces: S('sidebar', 'command'),
+    advanced: true,
     gate: (g) => g.libraryAvailable && g.canManageSettings,
     action: 'fragmentLibrary',
     testId: 'nav-fragments',
@@ -264,6 +292,7 @@ export const NAV_CONTRIBUTIONS: readonly NavContribution[] = [
     labelKey: 'layout.commandBar.cmd.mergeThresholds',
     icon: 'i-lucide-git-merge',
     surfaces: S('command'),
+    advanced: true,
     gate: (g) => g.canManageSettings,
     action: 'mergeThresholds',
     command: {
@@ -309,6 +338,7 @@ export const NAV_CONTRIBUTIONS: readonly NavContribution[] = [
     labelKey: 'layout.commandBar.cmd.serviceFragmentDefaults',
     icon: 'i-lucide-book-open-check',
     surfaces: S('command'),
+    advanced: true,
     gate: (g) => g.canManageSettings,
     action: 'serviceFragmentDefaults',
     command: {
@@ -322,6 +352,7 @@ export const NAV_CONTRIBUTIONS: readonly NavContribution[] = [
     labelKey: 'layout.commandBar.cmd.localModels',
     icon: 'i-lucide-server',
     surfaces: S('command'),
+    advanced: true,
     action: 'localModels',
     command: {
       group: 'workspace',
@@ -350,6 +381,7 @@ export const NAV_CONTRIBUTIONS: readonly NavContribution[] = [
     labelKey: 'nav.operatorDashboard',
     icon: 'i-lucide-gauge',
     surfaces: S('sidebar'),
+    advanced: true,
     gate: (g) => g.accountsEnabled && g.isAccountAdmin,
     action: 'operatorDashboard',
     testId: 'nav-operator-dashboard',
@@ -360,6 +392,7 @@ export const NAV_CONTRIBUTIONS: readonly NavContribution[] = [
     labelKey: 'nav.reports',
     icon: 'i-lucide-chart-column',
     surfaces: S('sidebar'),
+    advanced: true,
     gate: (g) => g.accountsEnabled && g.isAccountAdmin,
     action: 'reports',
     testId: 'nav-reports',
@@ -377,6 +410,23 @@ export const NAV_CONTRIBUTIONS: readonly NavContribution[] = [
       keywordsKey: 'layout.commandBar.keywords.shortcuts',
     },
   },
+  {
+    // Deliberately NOT `advanced`: this is the way BACK. Basic mode is the shipped default, so
+    // for most users the sidebar switcher is their first sight of the tier — and in the basic
+    // rail it renders icon-only, which is a thin thread to hang the entire advanced half of the
+    // product on. The palette is reachable in both tiers, searchable by name, and is already
+    // "the primary way to reach every action", so the tier belongs in it.
+    id: 'ui-mode',
+    labelKey: 'layout.commandBar.cmd.toggleUiMode',
+    icon: 'i-lucide-toggle-right',
+    surfaces: S('command'),
+    action: 'toggleUiMode',
+    command: {
+      group: 'workspace',
+      order: 90,
+      keywordsKey: 'layout.commandBar.keywords.toggleUiMode',
+    },
+  },
 ]
 
 /**
@@ -390,10 +440,14 @@ export const navigationModule = defineModule({
 })
 
 /**
- * Reactive RBAC/availability filter over the merged `nav` slot. Reads
+ * Reactive RBAC/availability/interface-tier filter over the merged `nav` slot. Reads
  * `deps.gates.*` (the reactive gate service) per item, so evaluated inside
- * `useReactiveSlots` it re-runs when a permission or connection flips. Passed to
- * `installModularApp` as the global `slotFilter`.
+ * `useReactiveSlots` it re-runs when a permission, connection, or the interface
+ * mode flips. Passed to `installModularApp` as the global `slotFilter`.
+ *
+ * The two axes are independent and BOTH must pass: an `advanced` item is dropped in
+ * basic mode, and every item still answers to its own `gate`. Order doesn't matter
+ * (it's a conjunction) but the tier is checked first, since it's the cheaper read.
  *
  * Typed against `AppSlots` (not the generic `SlotFilter`) so it matches the
  * filter shape the runtime infers for this registry. `deps` is widened to an
@@ -406,7 +460,11 @@ export function navSlotFilter(slots: AppSlots, deps: { gates?: NavGates }): AppS
     ...slots,
     // No gates service wired (tests / bare install) ⇒ show everything, matching
     // the dev-open "absent access allows all" backend parity.
-    nav: gates ? nav.filter((i) => (i.gate ? i.gate(gates) : true)) : nav,
+    nav: gates
+      ? nav.filter(
+          (i) => (i.advanced ? gates.advancedMode : true) && (i.gate ? i.gate(gates) : true),
+        )
+      : nav,
   }
 }
 

package/app/modular/nav-gates.ts

@@ -13,7 +13,9 @@ import type { NavGates } from '~/modular/nav-contributions'
  * permission or connection flip re-gates every shell with no `recalculateSlots()`.
  *
  * This mirrors the exact gating the pre-slice-1 `SideBar` computeds encoded (see
- * `useWorkspaceAccess` for the dev-open "absent access ⇒ allow all" parity).
+ * `useWorkspaceAccess` for the dev-open "absent access ⇒ allow all" parity), plus
+ * the interface tier (`advancedMode`), which rides the same service so a mode flip
+ * re-gates all three shells through the same reactive path as a permission flip.
  */
 export function createNavGates(): NavGates {
   const access = useWorkspaceAccess()
@@ -22,6 +24,7 @@ export function createNavGates(): NavGates {
   const accounts = useAccountsStore()
   const auth = useAuthStore()
   const providerConnections = useProviderConnectionsStore()
+  const uiMode = useUiModeStore()
 
   const infrastructureAvailable = computed(
     () =>
@@ -59,5 +62,8 @@ export function createNavGates(): NavGates {
     get isAccountAdmin() {
       return isAccountAdmin.value
     },
+    get advancedMode() {
+      return uiMode.isAdvanced
+    },
   }
 }

package/app/modular/registry.spec.ts

@@ -12,6 +12,7 @@ const NO_GATES: NavGates = {
   infrastructureAvailable: false,
   accountsEnabled: false,
   isAccountAdmin: false,
+  advancedMode: false,
 }
 
 describe('app modular registry', () => {

package/app/stores/bugHunt.ts

@@ -1,18 +1,10 @@
 import { defineStore } from 'pinia'
 import { computed, ref } from 'vue'
 import type { BugHuntResult, RunBugHuntInput, TaskSourceKind, TrackerBoard } from '~/types/domain'
-import { apiErrorEnvelope } from '~/composables/api/errors'
+import { apiErrorReason } from '~/composables/api/errors'
 import { useWorkspaceStore } from '~/stores/workspace'
 import { usePersonalSubscriptionsStore } from '~/stores/personalSubscriptions'
 
-/** The backend's `error.details.reason` code, when it sent one (see `useApi`'s error envelope). */
-function errorReasonOf(error: unknown): string | null {
-  const details = apiErrorEnvelope(error)?.details
-  if (!details || typeof details !== 'object') return null
-  const reason = (details as Record<string, unknown>).reason
-  return typeof reason === 'string' ? reason : null
-}
-
 /**
  * Bug-hunt state: the boards of the tracker being browsed, the last hunt's ranked candidates,
  * and the actions behind the three steps (list boards → run the hunt → adopt one candidate).
@@ -68,7 +60,7 @@ export const useBugHuntStore = defineStore('bugHunt', () => {
       if (boardsSource.value !== source) return
       boards.value = []
       boardsError.value = e instanceof Error ? e.message : String(e)
-      boardsErrorReason.value = errorReasonOf(e)
+      boardsErrorReason.value = apiErrorReason(e)
     } finally {
       boardsLoading.value = false
     }