@cat-factory/app 0.169.0 → 0.170.0

package/README.md

@@ -56,9 +56,10 @@ over the WebSocket. How that sync works is written up in
 ## 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:
+surface: the run/pipeline options that only exist to override a workspace-level default are
+left at that default, and the nav is trimmed to the destinations that are the **only route**
+to their capability. `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
@@ -81,7 +82,15 @@ 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.
+  own contributions take the same flag. The bar for setting it is **route count, not how
+  advanced the surface feels**: hiding the only way to reach a capability removes the
+  capability from the tier, while hiding a shortcut into a surface a basic destination also
+  opens removes nothing. So the flag belongs on a surface that sits beside the delivery path
+  (Sandbox, Kaizen), on a palette shortcut into a Workspace-settings tab, or on a knob the
+  Integrations hub already offers — and never on a sole route (the pipeline builder, the
+  fragment library, the infrastructure/PREnv windows, the operator + reports views).
+  `nav-contributions.spec.ts` pins the advanced set against a table of each item's
+  alternative route, so promoting one forces that claim to be written down.
 - **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

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

@@ -99,11 +99,36 @@ describe('navSlotFilter', () => {
     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')
+    // ...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.
+    expect(kept).toContain('build-pipeline')
+    expect(kept).toContain('fragments')
+    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.
     expect(kept).not.toContain('sandbox')
-    expect(kept).not.toContain('operator-dashboard')
+    expect(kept).not.toContain('kaizen')
+    expect(kept).not.toContain('merge-thresholds')
+  })
+
+  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',
+    }
+    const advanced = NAV_CONTRIBUTIONS.filter((i) => i.advanced).map((i) => i.id)
+    expect(advanced.sort()).toEqual(Object.keys(ALTERNATIVE_ROUTE).sort())
   })
 
   it('keeps the tier switch itself reachable in basic mode', () => {
@@ -119,15 +144,19 @@ describe('navSlotFilter', () => {
   })
 
   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.
+    // `sandbox` is advanced AND needs integrations.manage: neither axis alone reveals it.
     const advancedOnly: NavGates = { ...NO_GATES, advancedMode: true }
-    expect(ids(navSlotFilter(slots(), { gates: advancedOnly }))).not.toContain('build-pipeline')
+    expect(ids(navSlotFilter(slots(), { gates: advancedOnly }))).not.toContain('sandbox')
 
-    const permissionOnly: NavGates = { ...NO_GATES, canWriteBoard: true, advancedMode: false }
-    expect(ids(navSlotFilter(slots(), { gates: permissionOnly }))).not.toContain('build-pipeline')
+    const permissionOnly: NavGates = {
+      ...NO_GATES,
+      canManageIntegrations: true,
+      advancedMode: false,
+    }
+    expect(ids(navSlotFilter(slots(), { gates: permissionOnly }))).not.toContain('sandbox')
 
-    const both: NavGates = { ...NO_GATES, canWriteBoard: true, advancedMode: true }
-    expect(ids(navSlotFilter(slots(), { gates: both }))).toContain('build-pipeline')
+    const both: NavGates = { ...NO_GATES, canManageIntegrations: true, advancedMode: true }
+    expect(ids(navSlotFilter(slots(), { gates: both }))).toContain('sandbox')
   })
 
   it('leaves at least one sidebar destination in every basic-mode section it keeps', () => {

package/app/modular/nav-contributions.ts

@@ -153,13 +153,24 @@ const S = (...s: NavSurface[]) => s as readonly NavSurface[]
  *    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.
+ * `advanced: true` marks the power-user half, hidden in basic interface mode. The line is
+ * drawn by ROUTE COUNT, not by how advanced a surface feels: hiding the only way to reach a
+ * capability removes the capability from the tier, while hiding a shortcut to a surface basic
+ * mode already reaches removes nothing. So an item is advanced only when both of these hold —
+ * it is not the sole route to its capability, and nothing on the delivery path needs it:
+ *
+ *  - `sandbox` / `kaizen` — experimentation and self-grading surfaces, beside the delivery
+ *    path rather than on it.
+ *  - `merge-thresholds` / `service-fragment-defaults` — palette shortcuts into Workspace
+ *    settings tabs (Merge, Service best practices), which basic mode reaches via
+ *    `workspace-settings`.
+ *  - `local-models` — a per-user endpoint knob the Integrations hub already offers.
+ *
+ * Everything else stays in basic BECAUSE it is a sole route: authoring a flow
+ * (`build-pipeline`), the standards/skills library (`fragments`, whose only other route is a
+ * button two levels into Workspace settings), the PREnv + runner plumbing (`infrastructure`,
+ * `environment-setup`), and the operator/cost views that are the only aggregate read of run
+ * health and spend (`operator-dashboard`, `reports`).
  */
 export const NAV_CONTRIBUTIONS: readonly NavContribution[] = [
   {
@@ -167,7 +178,6 @@ 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',
@@ -253,7 +263,6 @@ 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',
@@ -264,7 +273,6 @@ 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',
@@ -275,7 +283,6 @@ 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',
@@ -381,7 +388,6 @@ 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',
@@ -392,7 +398,6 @@ 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',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cat-factory/app",
-  "version": "0.169.0",
+  "version": "0.170.0",
   "description": "Reusable Nuxt layer for the Agent Architecture Board SPA (components, stores, composables, pages). Consume it from a thin deployment app via `extends: ['@cat-factory/app']` and point it at your backend with NUXT_PUBLIC_API_BASE. See deploy/frontend for an example.",
   "repository": {
     "type": "git",