@cat-factory/app 0.132.0 → 0.134.0

package/app/components/panels/StepResultViewHost.vue

@@ -1,98 +1,60 @@
 <script setup lang="ts">
-// Universal dedicated-result-view host. An agent archetype can declare a `resultView`
-// id (see `~/utils/catalog`); when a step of that kind is opened, `ui.resultView` is set
-// and this host renders the matching registered window instead of the generic
-// `AgentStepDetail` prose panel. Adding a bespoke visualization for a new agent is just:
-//   1. declare `resultView: '<id>'` on its archetype, and
-//   2. register `'<id>': <Component>` below.
-// No caller changes — every board/inspector entry point already routes through
-// `ui` dispatch. Each registered window builds on `useResultView(viewId, { onOpen })`,
-// which owns the seam contract (open/blockId/close + Escape + load-on-open) so a new
-// window can't reintroduce the route-dependent empty-state bug by forgetting to fetch
-// on mount — declare an `onOpen` loader and it fires on every open.
-import { computed, type Component } from 'vue'
-import RequirementsReviewWindow from '~/components/requirements/RequirementsReviewWindow.vue'
-import ClarityReviewWindow from '~/components/clarity/ClarityReviewWindow.vue'
-import BrainstormWindow from '~/components/brainstorm/BrainstormWindow.vue'
-import TestReportWindow from '~/components/testing/TestReportWindow.vue'
-import HumanTestWindow from '~/components/humanTest/HumanTestWindow.vue'
-import VisualConfirmationWindow from '~/components/visualConfirm/VisualConfirmationWindow.vue'
-import GateResultView from '~/components/gates/GateResultView.vue'
-import ConsensusSessionWindow from '~/components/consensus/ConsensusSessionWindow.vue'
-import GenericStructuredResultView from '~/components/panels/GenericStructuredResultView.vue'
-import ServiceSpecWindow from '~/components/spec/ServiceSpecWindow.vue'
-import FollowUpWindow from '~/components/followUp/FollowUpWindow.vue'
-import ForkDecisionWindow from '~/components/forkDecision/ForkDecisionWindow.vue'
-import PrReviewWindow from '~/components/prReview/PrReviewWindow.vue'
-import MergerResultView from '~/components/panels/MergerResultView.vue'
-import InitiativeTrackerWindow from '~/components/initiative/InitiativeTrackerWindow.vue'
-import InitiativePlanningWindow from '~/components/initiative/InitiativePlanningWindow.vue'
-import DocInterviewWindow from '~/components/docs/DocInterviewWindow.vue'
-import RalphLoopResultView from '~/components/ralph/RalphLoopResultView.vue'
+// Universal dedicated-result-view host (slice 2 of the modular-vue adoption —
+// docs/initiatives/modular-vue-adoption.md). An agent archetype can declare a
+// `resultView` id (see `~/utils/catalog`); when a step of that kind is opened,
+// `ui.resultView` is set and this host mounts the matching registered window
+// instead of the generic `AgentStepDetail` prose panel.
+//
+// The registry is no longer a hardcoded `Record` here — every built-in window is
+// contributed to the modular `resultViews` slot (`~/modular/result-views`), and
+// a consumer deployment adds its OWN window to the SAME slot from a
+// `registerAppModule` module. This host reads the merged slot reactively via
+// `useReactiveSlots` and indexes it with `resolveComponentRegistry`; the kind's
+// (or custom kind's) `resultView` id selects the component. Adding a bespoke
+// visualization for a new agent is: declare `resultView: '<id>'` on its
+// archetype + contribute `{ id: '<id>', component }` to the `resultViews` slot.
+//
+// Each registered window builds on `useResultView(viewId, { onOpen })`, which
+// owns the seam contract (open/blockId/close + Escape + load-on-open) so a new
+// window can't reintroduce the route-dependent empty-state bug by forgetting to
+// fetch on mount.
+import { computed, watchEffect, type Component } from 'vue'
+import { useReactiveSlots } from '@modular-vue/runtime'
+import { pairById, resolveComponentRegistry } from '@modular-vue/core'
+import type { AppSlots } from '~/modular/slots'
 
 const ui = useUiStore()
+const agents = useAgentsStore()
+const slots = useReactiveSlots<AppSlots>()
 
-const STEP_RESULT_VIEWS: Record<string, Component> = {
-  'requirements-review': RequirementsReviewWindow,
-  'clarity-review': ClarityReviewWindow,
-  // Shared by both brainstorm stages (requirements + architecture); the window reads the stage.
-  brainstorm: BrainstormWindow,
-  tester: TestReportWindow,
-  // The human-testing gate: env URL + confirm / request-fix / pull-main / recreate / destroy.
-  'human-test': HumanTestWindow,
-  // The visual-confirmation gate: actual-vs-reference screenshot gallery + approve / request-fix.
-  'visual-confirm': VisualConfirmationWindow,
-  // Shared by both polling gates (`ci` + `conflicts`); the window branches on agentKind.
-  gate: GateResultView,
-  // Opened for any step that ran the consensus mechanism (routed in `ui.dispatchStepView`).
-  'consensus-session': ConsensusSessionWindow,
-  // Default dedicated view for a registered CUSTOM kind's structured (`custom`) output —
-  // a read-only JSON viewer, so a proprietary agent ships a result view with no bespoke code.
-  'generic-structured': GenericStructuredResultView,
-  // The service's prescriptive spec tree (+ Gherkin), opened from the inspector's "View
-  // Requirements" button. Not a pipeline-step view — opened directly via `ui.openServiceSpec`.
-  'service-spec': ServiceSpecWindow,
-  // The future-looking Follow-up companion: the Coder's surfaced loose ends / questions.
-  // Opened directly via `ui.openFollowUps` (the blinking chip + the `followup_pending` card).
-  'follow-ups': FollowUpWindow,
-  // The implementation-fork decision: the proposer's materially different approaches + the
-  // human's pick / custom approach. Opened directly via `ui.openForkDecision` (the pipeline
-  // chip, the inspector button, and the `fork_decision_pending` card).
-  'fork-decision': ForkDecisionWindow,
-  // The PR deep-review: the reviewer's sliced, prioritized findings + the human's multi-select.
-  // Opened as the `pr-reviewer` step's result view and via the `pr_review_ready` inbox card.
-  'pr-review': PrReviewWindow,
-  // The merger's verdict: the PR's complexity/risk/impact scores + the engine's auto-merge
-  // or awaiting-review decision (and why), instead of the agent's raw JSON.
-  merger: MergerResultView,
-  // The initiative tracker: phases, per-item status + PR links, decisions, deviations,
-  // caveats. Opened from the initiative card / inspector (`ui.openInitiativeTracker`) and
-  // as the planner step's result view.
-  'initiative-tracker': InitiativeTrackerWindow,
-  'initiative-planning': InitiativePlanningWindow,
-  // The interactive document-interview gate (WS5): the interviewer's clarifying questions +
-  // answer / continue / proceed, opened as the `doc-interviewer` step's result view.
-  'doc-interview': DocInterviewWindow,
-  // The Ralph loop: the persistent retry-until-done iteration history + the programmatic
-  // validation command + its latest exit code / output. Opened as the `ralph` step's view.
-  'ralph-loop': RalphLoopResultView,
-}
+// Index the merged `resultViews` slot into an id → component registry. Duplicate
+// ids throw by default (`resolveComponentRegistry`) — two modules claiming the
+// same view id is a wiring bug, not a silent last-wins. Recomputed if a consumer
+// module's contributions change (they don't after boot, but the read is cheap).
+const registry = computed(() => resolveComponentRegistry(slots.value.resultViews ?? []))
 
 const active = computed<Component | null>(() => {
   const view = ui.resultView?.view
   if (!view) return null
-  const component = STEP_RESULT_VIEWS[view] ?? null
-  // An archetype declared a `resultView` id with no registered component — this used to
-  // silently fall back to the prose panel. The backend now validates `resultView` against the
-  // canonical id set, so this should only fire mid-development of a new view; make it loud.
-  if (!component && import.meta.dev) {
-    console.warn(
-      `[StepResultViewHost] no component registered for resultView "${view}". ` +
-        `Add it to STEP_RESULT_VIEWS (and to RESULT_VIEW_IDS in @cat-factory/contracts).`,
-    )
-  }
-  return component
+  return registry.value.get(view) ?? null
 })
+
+// Dev guard: surface any CUSTOM kind whose declared `resultView` id resolves to
+// no registered component (a dangling reference — e.g. a backend kind naming a
+// consumer view this build doesn't ship). `pairById`'s `missing` bucket makes
+// the degradation explicit instead of a silent fall-through to the prose panel.
+if (import.meta.dev) {
+  watchEffect(() => {
+    const { missing } = pairById(agents.customArchetypes, registry.value, (a) => a.resultView)
+    if (missing.length) {
+      console.warn(
+        `[StepResultViewHost] custom agent kind(s) reference unregistered resultView id(s): ` +
+          missing.map((m) => `${m.item.kind}→${m.id}`).join(', ') +
+          `. Register a component for the id in a resultViews-slot module.`,
+      )
+    }
+  })
+}
 </script>
 
 <template>

package/app/composables/useNavContributions.ts

@@ -0,0 +1,75 @@
+import { computed } from 'vue'
+import { useReactiveSlots } from '@modular-vue/runtime'
+import { groupCommands, groupSidebar, sortToolbar } from '~/modular/nav-contributions'
+import type {
+  AppSlots,
+  CommandGroup,
+  NavActionId,
+  NavContribution,
+  SidebarGroup,
+} from '~/modular/nav-contributions'
+
+/**
+ * The single source the three nav shells render from (slice 1 of the modular-vue
+ * adoption). Reads the reactively-gated `nav` slot via `useReactiveSlots` — the
+ * `slotFilter` has already dropped items the caller lacks permission for, and
+ * the computed re-runs when a gate flips — then shapes the surviving items per
+ * surface (via the pure helpers in `nav-contributions.ts`) and resolves each
+ * item's action.
+ *
+ * First-party items carry an `action` id resolved here against the `ui` store; a
+ * consumer-contributed item may instead carry its own `run` closure, which wins.
+ */
+export function useNavContributions() {
+  const slots = useReactiveSlots<AppSlots>()
+  const ui = useUiStore()
+
+  // First-party action ids → host handlers. Typed as an exhaustive
+  // `Record<NavActionId, …>`, so a catalog `action` with no handler (or a handler
+  // with no catalog entry) is a compile error, not a silently dead button.
+  // Consumer items bypass this map entirely via their own `run` closure.
+  const actions: Record<NavActionId, () => void> = {
+    buildPipeline: () => ui.openBuilder(),
+    addFromRepo: () => ui.openAddService(),
+    bootstrapRepo: () => ui.openBootstrap(),
+    integrationsHub: () => ui.openIntegrations(),
+    sandbox: () => ui.openSandbox(),
+    kaizen: () => ui.openKaizen(),
+    infrastructure: () => ui.openInfrastructure(),
+    environmentSetup: () => ui.openEnvironmentSetup(),
+    fragmentLibrary: () => ui.openFragmentLibrary(),
+    mergeThresholds: () => ui.openWorkspaceSettings('merge'),
+    workspaceSettings: () => ui.openWorkspaceSettings(),
+    modelConfiguration: () => ui.openModelConfig(),
+    serviceFragmentDefaults: () => ui.openWorkspaceSettings('fragments'),
+    localModels: () => ui.openLocalModels(),
+    accountSettings: () => ui.openAccountSettings(),
+    operatorDashboard: () => ui.openOperatorDashboard(),
+    shortcuts: () => ui.openShortcutsHelp(),
+  }
+
+  /** Run a contribution's action (consumer `run` closure wins over the id map). */
+  function invoke(item: NavContribution): void {
+    if (item.run) {
+      item.run()
+      return
+    }
+    // First-party `action` is a `NavActionId`, so the exhaustive map always has a
+    // handler; the optional call only guards a consumer item that mis-uses
+    // `action` (its contract is `run`) — it no-ops rather than throwing.
+    if (item.action) actions[item.action]?.()
+  }
+
+  const all = computed<NavContribution[]>(() => slots.value.nav ?? [])
+
+  /** Grouped + ordered sidebar sections, empty sections dropped. */
+  const sidebarGroups = computed<SidebarGroup[]>(() => groupSidebar(all.value))
+
+  /** Grouped + ordered command-palette entries, empty groups dropped. */
+  const commandGroups = computed<CommandGroup[]>(() => groupCommands(all.value))
+
+  /** Toolbar contributions (the consumer extension point on `BoardToolbar`). */
+  const toolbarItems = computed<NavContribution[]>(() => sortToolbar(all.value))
+
+  return { sidebarGroups, commandGroups, toolbarItems, invoke }
+}

package/app/modular/agent-kinds.spec.ts

@@ -0,0 +1,80 @@
+import { describe, expect, it } from 'vitest'
+import {
+  buildAgentCapabilitiesManifest,
+  capabilitiesManifestVersion,
+  customKindToArchetype,
+  WORKSPACE_CAPABILITIES_MANIFEST_ID,
+} from './agent-kinds'
+import type { AgentKind, CustomAgentKind } from '~/types/domain'
+
+const kind = (
+  over: Partial<CustomAgentKind['presentation']> = {},
+  kindId = 'acme-audit',
+): CustomAgentKind => ({
+  kind: kindId as AgentKind,
+  container: true,
+  presentation: {
+    label: 'Audit',
+    icon: 'i-lucide-shield',
+    color: '#fff',
+    description: 'd',
+    ...over,
+  },
+})
+
+describe('buildAgentCapabilitiesManifest', () => {
+  it('models the snapshot kinds as one remote capability manifest carrying the agentKinds slot', () => {
+    const kinds = [kind(), kind()]
+    const manifest = buildAgentCapabilitiesManifest(kinds)
+    expect(manifest.id).toBe(WORKSPACE_CAPABILITIES_MANIFEST_ID)
+    expect(manifest.slots?.agentKinds).toEqual(kinds)
+  })
+
+  it('copies the input (no aliasing of the caller array)', () => {
+    const kinds = [kind()]
+    const manifest = buildAgentCapabilitiesManifest(kinds)
+    kinds.push(kind())
+    expect(manifest.slots?.agentKinds).toHaveLength(1)
+  })
+
+  it('derives an identical version for identical content (so an unchanged re-hydrate no-ops)', () => {
+    // A fresh, structurally-equal kinds array (a new snapshot re-delivering the same kinds)
+    // must produce the same version — that's what lets `hydrateCustomKinds` skip the swap.
+    expect(buildAgentCapabilitiesManifest([kind()]).version).toBe(
+      buildAgentCapabilitiesManifest([kind()]).version,
+    )
+  })
+
+  it('changes the version when a display/pairing field or the kind set differs', () => {
+    const base = capabilitiesManifestVersion([kind()])
+    expect(capabilitiesManifestVersion([kind({ label: 'Renamed' })])).not.toBe(base)
+    expect(capabilitiesManifestVersion([kind({ resultView: 'acme:audit' })])).not.toBe(base)
+    expect(capabilitiesManifestVersion([kind({}, 'acme-other')])).not.toBe(base)
+    expect(capabilitiesManifestVersion([kind(), kind({}, 'acme-two')])).not.toBe(base)
+    expect(capabilitiesManifestVersion([])).not.toBe(base)
+  })
+})
+
+describe('customKindToArchetype', () => {
+  it('projects presentation onto the display archetype', () => {
+    expect(customKindToArchetype(kind())).toEqual({
+      kind: 'acme-audit',
+      label: 'Audit',
+      icon: 'i-lucide-shield',
+      color: '#fff',
+      description: 'd',
+    })
+  })
+
+  it('carries category and resultView through when present', () => {
+    const a = customKindToArchetype(kind({ category: 'review', resultView: 'acme:audit' }))
+    expect(a.category).toBe('review')
+    expect(a.resultView).toBe('acme:audit')
+  })
+
+  it('omits category/resultView when absent (no undefined keys)', () => {
+    const a = customKindToArchetype(kind())
+    expect('category' in a).toBe(false)
+    expect('resultView' in a).toBe(false)
+  })
+})

package/app/modular/agent-kinds.ts

@@ -0,0 +1,83 @@
+import type { RemoteModuleManifest } from '@modular-vue/core'
+import type { AgentArchetype, CustomAgentKind } from '~/types/domain'
+import type { AppSlots } from './slots'
+
+/**
+ * Custom agent kinds as remote capability manifests (slice 2 of the modular-vue
+ * adoption — docs/initiatives/modular-vue-adoption.md).
+ *
+ * A deployment's BACKEND-registered agent kinds arrive in the workspace snapshot
+ * as `customAgentKinds` (wire data). Rather than mutating a module-global
+ * catalog, they're modeled as a single {@link RemoteModuleManifest} whose
+ * `agentKinds` slot carries the data. cat-factory holds ONE active manifest per
+ * workspace (swapped on snapshot), so the agents store reads its `.slots`
+ * directly — the sanctioned single-active-manifest shape (the merge-many
+ * `mergeRemoteManifests` helper is for holding several manifests at once, which
+ * we don't). CODE-shipped consumer kinds instead enter via the static
+ * `agentKinds` slot (a `registerAppModule` module); the store merges both.
+ */
+
+/** The stable id for the per-workspace capability manifest built from the snapshot. */
+export const WORKSPACE_CAPABILITIES_MANIFEST_ID = 'cat-factory:workspace-capabilities'
+
+/**
+ * A deterministic, key-order-independent content signature of the custom kinds, used as the
+ * manifest `version`. The workspace snapshot re-delivers the SAME deployment-registered kinds on
+ * every board-event refresh (a full `workspace.refresh()` runs `hydrateCustomKinds` each time), so
+ * a content-derived version lets the store skip re-projecting an UNCHANGED catalog — otherwise
+ * every refresh would replace the `customAgentKindMeta` read-model and needlessly invalidate the
+ * ~17 `agentKindMeta` / `isKnownAgentKind` consumers. It still changes (and swaps wholesale) when a
+ * different workspace's kinds actually differ. Serialized as fixed-order tuples of only the fields
+ * that affect display/pairing, so a re-serialization with reordered object keys can't spuriously
+ * differ.
+ */
+export function capabilitiesManifestVersion(kinds: readonly CustomAgentKind[]): string {
+  return JSON.stringify(
+    kinds.map((k) => [
+      k.kind,
+      k.container,
+      k.presentation.label,
+      k.presentation.icon,
+      k.presentation.color,
+      k.presentation.description,
+      k.presentation.category ?? null,
+      k.presentation.resultView ?? null,
+    ]),
+  )
+}
+
+/**
+ * Model the snapshot's `customAgentKinds` as a single remote capability manifest. The `version` is
+ * a {@link capabilitiesManifestVersion content signature} so identical snapshots produce an
+ * identical manifest — which `useAgentsStore().hydrateCustomKinds` uses to no-op an unchanged
+ * re-hydrate. Swapped wholesale (not diffed) when the content genuinely changes.
+ */
+export function buildAgentCapabilitiesManifest(
+  kinds: readonly CustomAgentKind[],
+): RemoteModuleManifest<AppSlots> {
+  return {
+    id: WORKSPACE_CAPABILITIES_MANIFEST_ID,
+    version: capabilitiesManifestVersion(kinds),
+    slots: { agentKinds: [...kinds] },
+  }
+}
+
+/**
+ * Project a wire `CustomAgentKind` onto the frontend's display `AgentArchetype`
+ * (icon/label/color/description + optional category/resultView). The inverse of
+ * the backend `agentPresentationSchema` — the SAME mapping the removed
+ * `registerCustomKinds` did inline, now pure and shared by the consumer-slot and
+ * backend-manifest paths.
+ */
+export function customKindToArchetype(kind: CustomAgentKind): AgentArchetype {
+  const { presentation: p } = kind
+  return {
+    kind: kind.kind,
+    label: p.label,
+    icon: p.icon,
+    color: p.color,
+    description: p.description,
+    ...(p.category ? { category: p.category } : {}),
+    ...(p.resultView ? { resultView: p.resultView } : {}),
+  }
+}

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

@@ -0,0 +1,182 @@
+import { describe, expect, it } from 'vitest'
+import enCatalog from '../../i18n/locales/en.json'
+import {
+  groupCommands,
+  groupSidebar,
+  NAV_ACTIONS,
+  NAV_CONTRIBUTIONS,
+  navSlotFilter,
+  sortToolbar,
+} from './nav-contributions'
+import type { AppSlots, NavGates } from './nav-contributions'
+
+/** The layer's base i18n catalog, used to prove every referenced key resolves. */
+const en = enCatalog as Record<string, unknown>
+
+/** Walk a dotted vue-i18n key path; true when it resolves to a leaf string. */
+function hasKey(path: string): boolean {
+  let node: unknown = en
+  for (const part of path.split('.')) {
+    if (typeof node !== 'object' || node === null || !(part in node)) return false
+    node = (node as Record<string, unknown>)[part]
+  }
+  return typeof node === 'string'
+}
+
+const NO_GATES: NavGates = {
+  canWriteBoard: false,
+  canManageIntegrations: false,
+  canManageSettings: false,
+  githubAvailable: false,
+  libraryAvailable: false,
+  infrastructureAvailable: false,
+  accountsEnabled: false,
+  isAccountAdmin: false,
+}
+
+const ALL_GATES: NavGates = {
+  canWriteBoard: true,
+  canManageIntegrations: true,
+  canManageSettings: true,
+  githubAvailable: true,
+  libraryAvailable: true,
+  infrastructureAvailable: true,
+  accountsEnabled: true,
+  isAccountAdmin: true,
+}
+
+const slots = (): AppSlots => ({ nav: [...NAV_CONTRIBUTIONS], resultViews: [], agentKinds: [] })
+const ids = (s: unknown) => (s as AppSlots).nav.map((i) => i.id)
+
+describe('navSlotFilter', () => {
+  it('drops every gated item when no permission/availability is granted', () => {
+    const kept = ids(navSlotFilter(slots(), { gates: NO_GATES }))
+    // Only the always-visible destinations survive (no `gate`).
+    const alwaysVisible = NAV_CONTRIBUTIONS.filter((i) => !i.gate).map((i) => i.id)
+    expect(kept.sort()).toEqual(alwaysVisible.sort())
+    expect(kept).toContain('kaizen')
+    expect(kept).not.toContain('build-pipeline')
+    expect(kept).not.toContain('operator-dashboard')
+  })
+
+  it('keeps every item when all gates pass', () => {
+    const kept = ids(navSlotFilter(slots(), { gates: ALL_GATES }))
+    expect(kept.sort()).toEqual(NAV_CONTRIBUTIONS.map((i) => i.id).sort())
+  })
+
+  it('reflects a single permission — board.write reveals only its items', () => {
+    const gates: NavGates = { ...NO_GATES, canWriteBoard: true, githubAvailable: true }
+    const kept = ids(navSlotFilter(slots(), { gates }))
+    expect(kept).toContain('build-pipeline')
+    expect(kept).toContain('add-from-repo') // needs github + board.write
+    expect(kept).not.toContain('bootstrap-repo') // needs integrations.manage
+  })
+
+  it('passes everything through when no gates service is wired (dev-open parity)', () => {
+    const kept = ids(navSlotFilter(slots(), {}))
+    expect(kept.sort()).toEqual(NAV_CONTRIBUTIONS.map((i) => i.id).sort())
+  })
+})
+
+describe('NAV_CONTRIBUTIONS catalog integrity', () => {
+  it('has unique ids and every item targets at least one surface', () => {
+    const seen = new Set<string>()
+    for (const item of NAV_CONTRIBUTIONS) {
+      expect(seen.has(item.id), `duplicate id ${item.id}`).toBe(false)
+      seen.add(item.id)
+      expect(item.surfaces.length, `${item.id} has no surface`).toBeGreaterThan(0)
+      // Every surface it targets must carry that surface's placement.
+      if (item.surfaces.includes('sidebar')) expect(item.sidebar, `${item.id} sidebar`).toBeTruthy()
+      if (item.surfaces.includes('command')) expect(item.command, `${item.id} command`).toBeTruthy()
+      // A first-party item is actionable (an id resolved host-side, or a run closure).
+      expect(item.action ?? item.run, `${item.id} has no action`).toBeTruthy()
+    }
+  })
+
+  it('every first-party action id is a known NAV_ACTION (no dead buttons)', () => {
+    // `useNavContributions` resolves an `action` against an exhaustive
+    // `Record<NavActionId, …>` handler map, so a catalog action outside
+    // NAV_ACTIONS would be a dead button. The type system already enforces this;
+    // this asserts it at runtime too (and that NAV_ACTIONS has no stale ids).
+    const declared = new Set<string>(NAV_ACTIONS)
+    const used = new Set<string>()
+    for (const item of NAV_CONTRIBUTIONS) {
+      if (!item.action) continue
+      used.add(item.action)
+      expect(declared.has(item.action), `${item.id} → unknown action ${item.action}`).toBe(true)
+    }
+    // No NAV_ACTION is orphaned (every declared handler id is actually used).
+    for (const action of NAV_ACTIONS) {
+      expect(used.has(action), `NAV_ACTION ${action} is unused`).toBe(true)
+    }
+  })
+
+  it('every referenced i18n key exists in the en catalog (no raw-key leak)', () => {
+    const missing: string[] = []
+    const check = (key: string | undefined) => {
+      if (key && !hasKey(key)) missing.push(key)
+    }
+    for (const group of ['create', 'repositories', 'integrations', 'workspace', 'account']) {
+      check(`layout.commandBar.groups.${group}`)
+    }
+    for (const group of [
+      'create',
+      'repositories',
+      'integrations',
+      'infrastructure',
+      'workspaceContext',
+      'configuration',
+    ]) {
+      check(`nav.${group}`)
+    }
+    for (const item of NAV_CONTRIBUTIONS) {
+      check(item.labelKey)
+      if (item.command) {
+        // Palette label falls back to the item's default labelKey.
+        check(item.command.labelKey ?? item.labelKey)
+        check(item.command.keywordsKey)
+      }
+    }
+    expect(missing).toEqual([])
+  })
+})
+
+describe('nav grouping helpers', () => {
+  it('groupSidebar orders sections + items and drops empty sections', () => {
+    const groups = groupSidebar(NAV_CONTRIBUTIONS)
+    expect(groups.map((g) => g.group)).toEqual([
+      'create',
+      'repositories',
+      'integrations',
+      'infrastructure',
+      'workspaceContext',
+      'configuration',
+    ])
+    const configuration = groups.find((g) => g.group === 'configuration')
+    expect(configuration?.items.map((i) => i.id)).toEqual([
+      'workspace-settings',
+      'model-config',
+      'account-settings',
+      'operator-dashboard',
+    ])
+  })
+
+  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).
+    expect(workspace?.items.map((ci) => ci.item.id)).toEqual([
+      'fragments',
+      'merge-thresholds',
+      'workspace-settings',
+      'model-config',
+      'service-fragment-defaults',
+      'local-models',
+      'sandbox',
+      'keyboard-shortcuts',
+    ])
+  })
+
+  it('sortToolbar yields nothing first-party (consumer-only extension point)', () => {
+    expect(sortToolbar(NAV_CONTRIBUTIONS)).toEqual([])
+  })
+})