@cat-factory/app 0.174.0 → 0.178.0

package/app/components/panels/inspector/ContainerSummary.vue

@@ -22,72 +22,64 @@ function addTask() {
 </script>
 
 <template>
+  <!-- Modules and tasks are two peer collapsible lists, not one "Contents" group: the
+       grouping added a level of nesting without adding information, and a service's task
+       list is long enough to want collapsing independently of its modules. -->
   <InspectorSection
-    :title="t('inspector.container.title')"
-    :hint="t('inspector.container.hint')"
-    :count="tasks.length"
+    v-if="modules.length"
+    :title="t('inspector.container.modulesTitle')"
+    :hint="t('inspector.container.modulesHint')"
+    :count="modules.length"
     default-open
   >
-    <!-- modules (services only) -->
-    <div v-if="modules.length">
-      <div class="mb-1 text-[11px] font-semibold uppercase tracking-wide text-slate-400">
-        {{ t('inspector.container.modules', { count: modules.length }) }}
-      </div>
-      <ul class="space-y-1">
-        <li
-          v-for="m in modules"
-          :key="m.id"
-          class="flex cursor-pointer items-center gap-2 rounded-md px-2 py-1 hover:bg-slate-800/60"
-          @click="ui.select(m.id)"
-        >
-          <UIcon name="i-lucide-package" class="h-3.5 w-3.5 text-violet-400" />
-          <span class="truncate text-xs text-slate-200">{{ m.title }}</span>
-          <span class="ms-auto text-[10px] text-slate-500">{{
-            t(
-              'inspector.container.taskCount',
-              { count: board.tasksOf(m.id).length },
-              board.tasksOf(m.id).length,
-            )
-          }}</span>
-        </li>
-      </ul>
-    </div>
+    <ul class="space-y-1">
+      <li
+        v-for="m in modules"
+        :key="m.id"
+        class="flex cursor-pointer items-center gap-2 rounded-md px-2 py-1 hover:bg-slate-800/60"
+        @click="ui.select(m.id)"
+      >
+        <UIcon name="i-lucide-package" class="h-3.5 w-3.5 text-violet-400" />
+        <span class="truncate text-xs text-slate-200">{{ m.title }}</span>
+        <span class="ms-auto text-[10px] text-slate-500">{{
+          t(
+            'inspector.container.taskCount',
+            { count: board.tasksOf(m.id).length },
+            board.tasksOf(m.id).length,
+          )
+        }}</span>
+      </li>
+    </ul>
+  </InspectorSection>
 
-    <div>
-      <div class="mb-1 flex items-center justify-between">
-        <span class="text-[11px] font-semibold uppercase tracking-wide text-slate-400">
-          {{
-            isFrame
-              ? t('inspector.container.allTasks', { count: tasks.length })
-              : t('inspector.container.tasks', { count: tasks.length })
-          }}
-        </span>
-        <div class="flex items-center gap-1.5">
-          <ReviewDebtBadge />
-          <UButton size="xs" variant="soft" color="primary" icon="i-lucide-plus" @click="addTask">
-            {{ t('inspector.container.addTask') }}
-          </UButton>
-        </div>
-      </div>
-      <ul v-if="tasks.length" class="space-y-1">
-        <li
-          v-for="task in tasks"
-          :key="task.id"
-          class="flex cursor-pointer items-center gap-2 rounded-md px-2 py-1 hover:bg-slate-800/60"
-          @click="ui.select(task.id)"
-        >
-          <span
-            class="h-2 w-2 shrink-0 rounded-full"
-            :style="{ backgroundColor: STATUS_META[task.status].color }"
-          />
-          <span class="truncate text-xs text-slate-200">{{ task.title }}</span>
-          <span class="ms-auto text-[10px] text-slate-500">{{
-            STATUS_META[task.status].label
-          }}</span>
-        </li>
-      </ul>
-      <div v-else class="text-[11px] text-slate-500">{{ t('inspector.container.noTasks') }}</div>
-    </div>
+  <InspectorSection
+    :title="isFrame ? t('inspector.container.allTasksTitle') : t('inspector.container.tasksTitle')"
+    :hint="t('inspector.container.tasksHint')"
+    :count="tasks.length"
+    default-open
+  >
+    <template #actions>
+      <ReviewDebtBadge />
+      <UButton size="xs" variant="soft" color="primary" icon="i-lucide-plus" @click="addTask">
+        {{ t('inspector.container.addTask') }}
+      </UButton>
+    </template>
+    <ul v-if="tasks.length" class="space-y-1">
+      <li
+        v-for="task in tasks"
+        :key="task.id"
+        class="flex cursor-pointer items-center gap-2 rounded-md px-2 py-1 hover:bg-slate-800/60"
+        @click="ui.select(task.id)"
+      >
+        <span
+          class="h-2 w-2 shrink-0 rounded-full"
+          :style="{ backgroundColor: STATUS_META[task.status].color }"
+        />
+        <span class="truncate text-xs text-slate-200">{{ task.title }}</span>
+        <span class="ms-auto text-[10px] text-slate-500">{{ STATUS_META[task.status].label }}</span>
+      </li>
+    </ul>
+    <div v-else class="text-[11px] text-slate-500">{{ t('inspector.container.noTasks') }}</div>
     <p v-if="isFrame" class="text-[11px] text-slate-500">
       {{ t('inspector.container.servicesHint') }}
     </p>

package/app/components/panels/inspector/ServiceReleaseHealthConfig.vue

@@ -2,6 +2,7 @@
 import { computed, reactive, ref, watch } from 'vue'
 import type { Block } from '~/types/domain'
 import InspectorSection from '~/components/panels/inspector/InspectorSection.vue'
+import { showOverrideField } from '~/utils/uiMode'
 
 // Per-service (frame) post-release-health mapping: which observability monitors/SLOs the
 // `post-release-health` gate watches after this service's PRs ship. Keyed by THIS block's
@@ -11,6 +12,7 @@ const props = defineProps<{ block: Block }>()
 
 const store = useReleaseHealthStore()
 const ui = useUiStore()
+const uiMode = useUiModeStore()
 const toast = useToast()
 const { t } = useI18n()
 const { confirmAction, toastDone } = useConfirmAction()
@@ -21,6 +23,14 @@ const draft = reactive({ monitorIds: '', sloIds: '', envTag: '' })
 const connected = computed(() => store.connection.connected)
 const saved = computed(() => store.configForBlock(props.block.id))
 
+// Post-release health is an ADVANCED-tier concern: with no mapping the gate is a pass-through,
+// so basic mode hides the whole section rather than showing a service-level knob whose absence
+// changes nothing. `showOverrideField` (not a bare `isAdvanced`) because the mapping is per
+// SERVICE and durable — once a teammate on the advanced tier maps monitors onto this frame,
+// hiding the panel would leave a basic-mode user with releases being watched (and an on-call
+// agent that can spawn) by a configuration they can neither see nor clear.
+const show = computed(() => showOverrideField(uiMode.isAdvanced, saved.value))
+
 function parseIds(csv: string): string[] {
   return csv
     .split(',')
@@ -91,6 +101,7 @@ async function clear() {
 
 <template>
   <InspectorSection
+    v-if="show"
     :title="t('inspector.releaseHealth.title')"
     :hint="t('inspector.releaseHealth.sectionHint')"
   >

package/app/components/panels/inspector/ServiceValidationConfig.vue

@@ -7,7 +7,9 @@ import {
   VALIDATION_MAX_ATTEMPTS_CEILING,
   VALIDATION_MAX_CHECKS,
   type ValidationCheck,
+  type ValidationEcosystem,
 } from '~/types/validationChecks'
+import { mergeDetectedChecks } from '~/utils/validationDetection'
 
 // Per-service (frame) PRE-PR VALIDATION CHECKS: the shell commands the executor-harness runs
 // against the checkout after the coder settles and BEFORE the PR opens. A failing command's
@@ -18,10 +20,11 @@ const props = defineProps<{ block: Block }>()
 
 const store = useValidationChecksStore()
 const toast = useToast()
-const { t } = useI18n()
+const { t, te } = useI18n()
 const { confirmAction, toastDone } = useConfirmAction()
 
 const busy = ref(false)
+const detecting = ref(false)
 const rows = ref<ValidationCheck[]>([])
 const maxAttempts = ref(VALIDATION_DEFAULT_MAX_ATTEMPTS)
 
@@ -64,6 +67,88 @@ function notifyError(title: string, e: unknown) {
   })
 }
 
+// Ecosystem label KEYS, exhaustive over the contracts `ValidationEcosystem` union: a new
+// backend detector fails THIS typecheck until it is mapped (the key is assembled at runtime,
+// so the typed-message-keys check cannot see the `t()` lookup — the map's exhaustiveness is
+// the drift guard, same pattern as `ENV_TEST_STAGE_KEYS`).
+const ECOSYSTEM_KEYS: Record<ValidationEcosystem, string> = {
+  node: 'inspector.validationChecks.ecosystem.node',
+  python: 'inspector.validationChecks.ecosystem.python',
+  go: 'inspector.validationChecks.ecosystem.go',
+  rust: 'inspector.validationChecks.ecosystem.rust',
+  maven: 'inspector.validationChecks.ecosystem.maven',
+  gradle: 'inspector.validationChecks.ecosystem.gradle',
+  dotnet: 'inspector.validationChecks.ecosystem.dotnet',
+  ruby: 'inspector.validationChecks.ecosystem.ruby',
+  php: 'inspector.validationChecks.ecosystem.php',
+  elixir: 'inspector.validationChecks.ecosystem.elixir',
+  make: 'inspector.validationChecks.ecosystem.make',
+  just: 'inspector.validationChecks.ecosystem.just',
+  task: 'inspector.validationChecks.ecosystem.task',
+}
+
+function ecosystemLabel(id: ValidationEcosystem): string {
+  const key = ECOSYSTEM_KEYS[id]
+  // `te`-guarded so a locale missing the key shows the raw id, never a raw message key.
+  return te(key) ? t(key) : id
+}
+
+/**
+ * Fill the rows from what the service's repo declares. The suggestion is NOT saved — it
+ * lands in the same unsaved rows the operator edits by hand, so Detect is always reversible
+ * by walking away from the panel.
+ */
+async function detect() {
+  detecting.value = true
+  try {
+    const result = await store.detect(props.block.id)
+    if (result.status !== 'ok') {
+      // The backend distinguishes "no repo linked" from "the repo could not be read"; say
+      // which, because they send the operator to different places.
+      toast.add({
+        title: t(`inspector.validationChecks.detect.${result.status}`),
+        icon: 'i-lucide-triangle-alert',
+        color: 'warning',
+      })
+      return
+    }
+    const merged = mergeDetectedChecks(rows.value, result.checks, VALIDATION_MAX_CHECKS)
+    rows.value = merged.rows
+    if (merged.added === 0) {
+      toast.add({
+        title: t('inspector.validationChecks.detect.nothingNew'),
+        description:
+          result.checks.length > 0
+            ? t('inspector.validationChecks.detect.alreadyPresent')
+            : t('inspector.validationChecks.detect.unrecognised'),
+        icon: 'i-lucide-info',
+        color: 'neutral',
+      })
+      return
+    }
+    const names = result.ecosystems.map(ecosystemLabel).join(', ')
+    toast.add({
+      title: t('inspector.validationChecks.detect.added', { count: merged.added }, merged.added),
+      // Name what was recognised AND what was left out: a cap that silently swallowed a
+      // suggestion reads as "that is everything your repo has".
+      description: [
+        names ? t('inspector.validationChecks.detect.found', { ecosystems: names }) : '',
+        merged.dropped > 0 || result.truncated
+          ? t('inspector.validationChecks.detect.capped', { max: VALIDATION_MAX_CHECKS })
+          : '',
+      ]
+        .filter(Boolean)
+        .join(' '),
+      icon: 'i-lucide-wand-sparkles',
+      color: 'success',
+    })
+  } catch (e) {
+    notifyError(t('inspector.validationChecks.detect.failed'), e)
+  } finally {
+    detecting.value = false
+  }
+}
+
 async function save() {
   busy.value = true
   try {
@@ -179,6 +264,19 @@ async function clear() {
           />
         </UFormField>
         <div class="flex gap-2">
+          <UButton
+            color="neutral"
+            variant="soft"
+            size="xs"
+            icon="i-lucide-wand-sparkles"
+            :loading="detecting"
+            :disabled="!canAdd"
+            :title="t('inspector.validationChecks.detect.hint')"
+            data-testid="validation-detect"
+            @click="detect"
+          >
+            {{ t('inspector.validationChecks.detect.action') }}
+          </UButton>
           <UButton
             color="neutral"
             variant="soft"

package/app/components/settings/ComposeEnvironmentSetupSection.vue

@@ -0,0 +1,102 @@
+<script setup lang="ts">
+// The guided per-service Docker Compose environment setup, as a section of the Infrastructure
+// window's "Test environments" tab.
+//
+// It used to be its own top-level sidebar destination called "Environment setup", which was
+// wrong twice over: the name said nothing about WHAT it sets up (people read it as the place
+// to configure environments in general, which is the rest of this tab), and a wizard that
+// fills in one field of one service's config sat at the same level as the workspace-wide
+// infrastructure it depends on. It lives here now, next to the two settings it writes: the
+// service's provision type and the workspace's Docker Compose handler.
+//
+// The section deliberately carries a full explanation rather than a one-line hint. The wizard
+// is a five-minute flow that touches a repo and can trial-provision a stack, so "when you need
+// this / when you don't" has to be answerable BEFORE opening it — most services on most boards
+// never need it at all.
+const { t } = useI18n()
+const ui = useUiStore()
+
+/** Bullet lists rendered below; static literal keys so the typed-key check sees them. */
+const steps = computed(() => [
+  t('settings.composeEnvSetup.how.scan'),
+  t('settings.composeEnvSetup.how.analyse'),
+  t('settings.composeEnvSetup.how.preflight'),
+  t('settings.composeEnvSetup.how.save'),
+])
+const needed = computed(() => [
+  t('settings.composeEnvSetup.needed.running'),
+  t('settings.composeEnvSetup.needed.compose'),
+  t('settings.composeEnvSetup.needed.setup'),
+])
+const notNeeded = computed(() => [
+  t('settings.composeEnvSetup.notNeeded.inContainer'),
+  t('settings.composeEnvSetup.notNeeded.otherBackend'),
+  t('settings.composeEnvSetup.notNeeded.noRepo'),
+])
+
+// The wizard is its own modal, so hand over rather than stacking: close this window first.
+function start() {
+  ui.closeProviderConnection()
+  ui.openEnvironmentSetup()
+}
+</script>
+
+<template>
+  <section class="space-y-3" data-testid="compose-env-setup-section">
+    <div>
+      <h3 class="text-sm font-semibold text-slate-200">
+        {{ t('settings.composeEnvSetup.title') }}
+      </h3>
+      <p class="mt-1 text-xs leading-relaxed text-slate-400">
+        {{ t('settings.composeEnvSetup.lead') }}
+      </p>
+    </div>
+
+    <div class="rounded border border-slate-800 bg-slate-900/40 p-3">
+      <p class="text-[11px] font-medium uppercase tracking-wide text-slate-400">
+        {{ t('settings.composeEnvSetup.how.title') }}
+      </p>
+      <ol class="mt-2 list-decimal space-y-1 ps-4 text-[11px] leading-relaxed text-slate-400">
+        <li v-for="(step, i) in steps" :key="`how-${i}`">{{ step }}</li>
+      </ol>
+      <p class="mt-2 text-[11px] leading-relaxed text-slate-500">
+        {{ t('settings.composeEnvSetup.how.outcome') }}
+      </p>
+    </div>
+
+    <div class="grid gap-2 sm:grid-cols-2">
+      <div class="rounded border border-emerald-900/50 bg-emerald-950/20 p-3">
+        <p class="flex items-center gap-1.5 text-[11px] font-medium text-emerald-200/90">
+          <UIcon name="i-lucide-check" class="h-3.5 w-3.5 shrink-0" />
+          {{ t('settings.composeEnvSetup.needed.title') }}
+        </p>
+        <ul class="mt-1.5 list-disc space-y-1 ps-4 text-[11px] leading-relaxed text-slate-400">
+          <li v-for="(item, i) in needed" :key="`need-${i}`">{{ item }}</li>
+        </ul>
+      </div>
+      <div class="rounded border border-slate-800 bg-slate-900/40 p-3">
+        <p class="flex items-center gap-1.5 text-[11px] font-medium text-slate-300">
+          <UIcon name="i-lucide-minus" class="h-3.5 w-3.5 shrink-0" />
+          {{ t('settings.composeEnvSetup.notNeeded.title') }}
+        </p>
+        <ul class="mt-1.5 list-disc space-y-1 ps-4 text-[11px] leading-relaxed text-slate-400">
+          <li v-for="(item, i) in notNeeded" :key="`skip-${i}`">{{ item }}</li>
+        </ul>
+      </div>
+    </div>
+
+    <div class="flex items-center gap-2">
+      <UButton
+        size="xs"
+        color="primary"
+        variant="soft"
+        icon="i-lucide-wand-sparkles"
+        data-testid="compose-env-setup-start"
+        @click="start()"
+      >
+        {{ t('settings.composeEnvSetup.start') }}
+      </UButton>
+      <span class="text-[11px] text-slate-500">{{ t('settings.composeEnvSetup.rerunHint') }}</span>
+    </div>
+  </section>
+</template>

package/app/components/settings/InfrastructureWindow.vue

@@ -6,7 +6,10 @@
 //     mode — the warm-container-pool + checkout-reuse settings (the local agent-container
 //     runtime, folded in from the former LocalModeSettingsPanel).
 //   - "Test environments" — where the Tester's ephemeral environments run. Shows the test-env
-//     backend selector and the environment-provider connection.
+//     backend selector, the environment-provider connection, and the guided per-service Docker
+//     Compose setup (formerly a standalone "Environment setup" sidebar entry — it writes a
+//     service's Compose recipe plus the workspace's Compose handler, so it belongs beside the
+//     settings it edits rather than at the same level as them).
 // Local-specific affordances render inline, gated on `auth.localMode?.enabled`. A tab whose
 // backend integration is disabled (503) simply doesn't render.
 import { computed, ref, watch } from 'vue'
@@ -16,6 +19,7 @@ import InfraHandlersConfigurator from '~/components/settings/InfraHandlersConfig
 import DefaultProvisionTypeSection from '~/components/settings/DefaultProvisionTypeSection.vue'
 import LocalContainerPoolSettings from '~/components/settings/LocalContainerPoolSettings.vue'
 import SharedStacksPanel from '~/components/settings/SharedStacksPanel.vue'
+import ComposeEnvironmentSetupSection from '~/components/settings/ComposeEnvironmentSetupSection.vue'
 
 // The shared-stacks tab uses its own slot key beyond the provider-connection kinds.
 type InfraTabValue = ProviderConnectionKind | 'shared-stacks'
@@ -142,6 +146,12 @@ watch([tabs, () => store.loaded], () => {
               <div class="border-t border-slate-800 pt-4">
                 <InfraHandlersConfigurator />
               </div>
+              <!-- The guided per-SERVICE Compose flow (formerly the standalone "Environment
+                   setup" sidebar entry). Last, because it fills in one service's recipe on
+                   top of the workspace-wide choices above. -->
+              <div class="border-t border-slate-800 pt-4">
+                <ComposeEnvironmentSetupSection />
+              </div>
             </div>
           </template>
           <template #shared-stacks>

package/app/composables/api/validationChecks.ts

@@ -1,5 +1,6 @@
 import {
   deleteServiceValidationConfigContract,
+  detectServiceValidationChecksContract,
   getServiceValidationConfigContract,
   listServiceValidationConfigsContract,
   setServiceValidationConfigContract,
@@ -30,6 +31,13 @@ export function validationChecksApi({ send, ws }: ApiContext) {
         body,
       }),
 
+    /** Suggest checks from the service repo's manifests — a read; the operator still saves. */
+    detectServiceValidationChecks: (workspaceId: string, blockId: string) =>
+      send(detectServiceValidationChecksContract, {
+        pathPrefix: ws(workspaceId),
+        pathParams: { blockId },
+      }),
+
     deleteServiceValidationConfig: (workspaceId: string, blockId: string) =>
       send(deleteServiceValidationConfigContract, {
         pathPrefix: ws(workspaceId),

package/app/composables/useIntegrationBack.ts

@@ -10,8 +10,9 @@ import type { Ref, WritableComputedRef } from 'vue'
  * resort to an obscure comma-operator expression. A named handler reads clearly instead.
  *
  * Returns to whichever hub the panel was reached from: the user-scoped "My setup" hub when
- * `cameFromPersonal` is set, else the workspace Integrations hub. A shared panel (e.g. the
- * vendor-credentials modal, reachable from both) thus lands the user back where they were.
+ * `cameFromPersonal` is set, the Model providers hub when `cameFromModelProviders` is set,
+ * else the workspace Integrations hub. A shared panel (e.g. the vendor-credentials modal,
+ * reachable from all three) thus lands the user back where they were.
  *
  * Pass the panel's `open` model (the writable ref/computed bound to its `UModal`).
  */
@@ -19,8 +20,10 @@ export function useIntegrationBack(open: Ref<boolean> | WritableComputedRef<bool
   const ui = useUiStore()
   return () => {
     const toPersonal = ui.cameFromPersonal
+    const toModelProviders = ui.cameFromModelProviders
     open.value = false
     if (toPersonal) ui.openPersonalSetup()
+    else if (toModelProviders) ui.openModelProviders()
     else ui.openIntegrations()
   }
 }

package/app/composables/useNavContributions.ts

@@ -33,10 +33,10 @@ export function useNavContributions() {
     addFromRepo: () => ui.openAddService(),
     bootstrapRepo: () => ui.openBootstrap(),
     integrationsHub: () => ui.openIntegrations(),
+    modelProviders: () => ui.openModelProviders(),
     sandbox: () => ui.openSandbox(),
     kaizen: () => ui.openKaizen(),
     infrastructure: () => ui.openInfrastructure(),
-    environmentSetup: () => ui.openEnvironmentSetup(),
     fragmentLibrary: () => ui.openFragmentLibrary(),
     mergeThresholds: () => ui.openWorkspaceSettings('merge'),
     workspaceSettings: () => ui.openWorkspaceSettings(),

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

@@ -99,36 +99,74 @@ describe('navSlotFilter', () => {
     expect(kept).toContain('integrations-hub')
     expect(kept).toContain('workspace-settings')
     expect(kept).toContain('model-config')
-    // ...and so does every destination that is the SOLE route to its capability, however deep
-    // it feels: authoring a flow, the standards library, the PREnv/runner plumbing, and the
-    // aggregate run-health / spend views.
+    // Model providers are NOT an integration: the split is what makes the engines findable.
+    expect(kept).toContain('model-providers')
+    // ...and so does everything the everyday delivery loop runs on, however deep it feels:
+    // authoring a flow, the standards library, and the PREnv/runner plumbing.
     expect(kept).toContain('build-pipeline')
     expect(kept).toContain('fragments')
+    // Also the only route to the guided per-service Compose environment setup, which folded
+    // into this window rather than staying a sibling nav entry.
     expect(kept).toContain('infrastructure')
-    expect(kept).toContain('environment-setup')
-    expect(kept).toContain('operator-dashboard')
-    expect(kept).toContain('reports')
-    // What drops is beside the delivery path (experimentation) or a shortcut into a surface
-    // basic mode already reaches another way.
+    // What drops is either a shortcut basic mode reaches another way, or a capability
+    // deliberately kept out of the tier (experimentation, one-off repo setup, the
+    // deployment-wide operator rollups).
     expect(kept).not.toContain('sandbox')
     expect(kept).not.toContain('kaizen')
     expect(kept).not.toContain('merge-thresholds')
+    expect(kept).not.toContain('bootstrap-repo')
+    expect(kept).not.toContain('operator-dashboard')
+    expect(kept).not.toContain('reports')
   })
 
-  it('never makes an advanced item the only route to its capability', () => {
-    // The tier's governing rule (see the catalog comment): every advanced destination either
-    // sits beside the delivery path, or is a shortcut into a surface a basic destination also
-    // opens. Spelled out here as a table so promoting an item to `advanced` forces an explicit
-    // claim about how basic mode still reaches it, rather than a silent capability loss.
-    const ALTERNATIVE_ROUTE: Record<string, string> = {
-      sandbox: 'none needed - experimentation surface, not on the delivery path',
-      kaizen: 'none needed - self-grading history, not on the delivery path',
-      'merge-thresholds': 'workspace-settings -> Merge tab',
-      'service-fragment-defaults': 'workspace-settings -> Service best practices tab',
-      'local-models': 'integrations-hub -> Local runners',
+  it('states, per advanced item, whether basic mode still reaches its capability', () => {
+    // Marking an item `advanced` does one of two things, and which one has to be said out
+    // loud. `reached-another-way` promises a basic destination opens the same surface, so
+    // nothing is lost. `out-of-tier` concedes the opposite: the capability is ABSENT from
+    // basic mode and the tier switch is the only way to it. Both are legitimate; a silent
+    // one is not. The table is the claim, and it must match the catalog exactly, so adding
+    // `advanced: true` fails here until the reason is written down.
+    const REASON: Record<string, { kind: 'reached-another-way' | 'out-of-tier'; why: string }> = {
+      'merge-thresholds': {
+        kind: 'reached-another-way',
+        why: 'workspace-settings -> Merge tab',
+      },
+      'service-fragment-defaults': {
+        kind: 'reached-another-way',
+        why: 'workspace-settings -> Service best practices tab',
+      },
+      'local-models': {
+        kind: 'reached-another-way',
+        why: 'model-providers -> My local runners',
+      },
+      sandbox: {
+        kind: 'out-of-tier',
+        why: 'experimentation surface, beside the delivery path',
+      },
+      kaizen: {
+        kind: 'out-of-tier',
+        why: 'self-grading history, beside the delivery path',
+      },
+      'bootstrap-repo': {
+        kind: 'out-of-tier',
+        why: 'one-off new-repo setup, not part of running work on an existing board',
+      },
+      'operator-dashboard': {
+        kind: 'out-of-tier',
+        why: 'deployment-wide health rollup - an operator job, not a delivery one',
+      },
+      reports: {
+        kind: 'out-of-tier',
+        why: 'deployment-wide spend/activity rollup - an operator job, not a delivery one',
+      },
     }
     const advanced = NAV_CONTRIBUTIONS.filter((i) => i.advanced).map((i) => i.id)
-    expect(advanced.sort()).toEqual(Object.keys(ALTERNATIVE_ROUTE).sort())
+    expect(advanced.sort()).toEqual(Object.keys(REASON).sort())
+    // An `out-of-tier` item is a real capability loss, so the switcher back must survive basic
+    // mode — pinned by the next case. Assert here only that every claim carries a reason.
+    for (const [id, reason] of Object.entries(REASON)) {
+      expect(reason.why.length, `${id} has no stated reason`).toBeGreaterThan(0)
+    }
   })
 
   it('keeps the tier switch itself reachable in basic mode', () => {
@@ -215,6 +253,7 @@ describe('NAV_CONTRIBUTIONS catalog integrity', () => {
     for (const group of [
       'create',
       'repositories',
+      'models',
       'integrations',
       'infrastructure',
       'workspaceContext',
@@ -240,15 +279,19 @@ describe('nav grouping helpers', () => {
     expect(groups.map((g) => g.group)).toEqual([
       'create',
       'repositories',
+      'models',
       'integrations',
       'infrastructure',
       'workspaceContext',
       'configuration',
     ])
+    // The engines are their own section, ahead of the optional integrations; `model-config`
+    // sits beside the providers it picks models from rather than under `configuration`.
+    const models = groups.find((g) => g.group === 'models')
+    expect(models?.items.map((i) => i.id)).toEqual(['model-providers', 'model-config'])
     const configuration = groups.find((g) => g.group === 'configuration')
     expect(configuration?.items.map((i) => i.id)).toEqual([
       'workspace-settings',
-      'model-config',
       'account-settings',
       'operator-dashboard',
       'reports',