@cat-factory/app 0.253.2 → 0.254.1

package/README.md

@@ -265,6 +265,55 @@ picking what each of them runs on are halves of the same job.
   whatever the tier: the same rule `showOverrideField` states for a single field: a row the
   user can neither read nor clear is worse than a longer list.
 
+### The palette's second dial: the pipeline's purpose
+
+The builder's palette narrows on two axes, and both controls sit on one row above the catalog
+(`PipelinePurposeSelect` above `AgentTierSelect`), each with its own "n hidden" hint so neither
+narrowing reads as an empty catalog. The tier says how deep to look; the **purpose** says what
+the pipeline is for (`build` / `document` / `review` / `research` / `planning`), and the palette
+drops the categories that purpose has no use for. The purpose is not a view preference: it is
+saved on the pipeline and also decides which task pickers offer it, which is why the control
+writes through to the draft while the tier writes to its own store.
+
+Purpose is filtered by two predicates in `@cat-factory/contracts`, and the difference between
+them is the point:
+
+- `purposeSuggestsAgentCategory` is **relevance**: what the palette OFFERS. Opinionated (a
+  review pipeline designs nothing; a planning pipeline has no pull request to gate), because a
+  wrong guess costs one purpose switch.
+- `purposeAllowsAgentCategory` is **compatibility**: what the builder will SAVE. It states only
+  what is contradictory (a pipeline that writes no code carrying an implementation step) and
+  drives the draft's conflict warning.
+
+Relevance is a subset of compatibility, asserted over the whole grid in `pipeline.spec.ts`. Keep
+it that way: the palette may hide what the save gate tolerates, so tightening the relevance table
+never turns a stored pipeline into one its own editor refuses, but offering a kind the save gate
+then rejects would be a dead end with the refusal arriving after the work.
+
+**Each hint counts what relaxing THAT dial alone would reveal**, which is why the reduction is one
+function (`utils/agentPalette.ts`) rather than two chained filters at the call site. Chaining them
+and subtracting the lengths gives the second dial an honest count and hands the first one the whole
+rest of the catalog: at the default `basic` tier a `planning` pipeline claimed thirteen kinds hidden
+for its purpose when switching back to Build revealed three, the other ten being tier-hidden either
+way. So a kind BOTH dials hide is counted by neither, correctly, and a new dial measures itself
+against what the others already admit rather than against the raw catalog.
+
+**A purpose or category this build does not recognise narrows nothing.** Both are closed
+vocabularies and both are persisted, so a reader is total against the type and partial against the
+data: a `Pipeline.purpose` outlives the build that wrote it, and a `presentation.category` arrives
+in the snapshot from a kind a deployment registered. Narrow with the schema-derived
+`isPipelinePurpose` / `isAgentCategory` before indexing anything by one, never with an optional
+call, so adding a member still fails the build. The two predicates read the unknown value through
+one helper because they have to agree about it: one narrowing by a purpose the other no longer
+recognises is exactly the subset violation above. On the control itself an unrecognised purpose is
+NAMED and quoted back rather than left to render blank, which would read as a pipeline nobody
+classified while the saved row says otherwise.
+
+Offering such a kind is only half of keeping it: `groupAgentPalette` puts whatever no section
+CLAIMED into the trailing custom bucket, derived from the sections rather than from an absent
+`category`. A kind whose category has no section matches neither test, so filtering on the absent
+one alone deleted it from a palette its own save gate accepts.
+
 ## In-app tutorial tours
 
 On first launch (once the board is up and no other startup advisory is open) the app asks

package/app/components/palettes/AgentPalette.vue

@@ -1,53 +1,46 @@
 <script setup lang="ts">
 import { computed } from 'vue'
 import { useLocalStorage } from '@vueuse/core'
-import { purposeAllowsAgentCategory } from '@cat-factory/contracts'
 import type { AgentKind, PipelinePurpose } from '~/types/domain'
 import AgentTierSelect from '~/components/palettes/AgentTierSelect.vue'
-import { filterByAgentTier } from '~/utils/agentTier'
+import PipelinePurposeSelect from '~/components/palettes/PipelinePurposeSelect.vue'
+import { groupAgentPalette, narrowAgentPalette } from '~/utils/agentPalette'
 import { AGENT_CATEGORIES, OBSERVABILITY_GATE_ARCHETYPE } from '~/utils/catalog'
 
 const { t } = useI18n()
 const agents = useAgentsStore()
 const agentTier = useAgentTierStore()
 const releaseHealth = useReleaseHealthStore()
-defineEmits<{ (e: 'add', kind: AgentKind): void }>()
-// The purpose of the pipeline being built. When set to a non-`build` classifier, the
-// Implementation (`build`) and Testing (`test`) categories are hidden — such a pipeline writes
-// no product code and runs no tests (see `purposeAllowsAgentCategory`). `null`/`build` shows all.
+defineEmits<{
+  (e: 'add', kind: AgentKind): void
+  (e: 'update:purpose', purpose: PipelinePurpose): void
+}>()
+// The purpose of the pipeline being built, edited right here by the control above the catalog.
+// It narrows the palette to the categories that purpose has any use for (a review pipeline
+// designs nothing and builds nothing, see `purposeSuggestsAgentCategory`); `null` shows all.
 const props = defineProps<{ purpose?: PipelinePurpose | null }>()
 
 // The post-release-health gate is only meaningful — and only accepted by the backend —
 // with an observability integration connected, so it appears in the palette ONLY then.
-const offered = computed(() => {
-  const all = releaseHealth.connection.connected
+const connected = computed(() =>
+  releaseHealth.connection.connected
     ? [...agents.archetypes, OBSERVABILITY_GATE_ARCHETYPE]
-    : agents.archetypes
-  // Hide the categories the pipeline's purpose doesn't build from (an uncategorized custom kind
-  // has no category to gate, so it always shows).
-  return all.filter((a) => !a.category || purposeAllowsAgentCategory(props.purpose, a.category))
-})
+    : agents.archetypes,
+)
 
-// Then narrow to the selected tier. Applied AFTER the purpose gate so the "n hidden" hint
-// counts only what the TIER is holding back — a kind the pipeline's purpose rules out is not
-// something a wider tier would reveal, so counting it would send the user chasing a control
-// that cannot help them.
-const palette = computed(() => filterByAgentTier(offered.value, agentTier.tier))
-const hiddenByTier = computed(() => offered.value.length - palette.value.length)
+// Then narrow on the two dials above the catalog, each hint counting what relaxing THAT dial
+// alone would reveal. `narrowAgentPalette` owns that rule so it is unit-testable, and so neither
+// count can be quietly re-derived here as a subtraction that measures the wrong population.
+const narrowed = computed(() => narrowAgentPalette(connected.value, props.purpose, agentTier.tier))
+const palette = computed(() => narrowed.value.offered)
 
-// Group the palette into the ordered catalog categories, plus a trailing "Custom" bucket
-// for runtime-added agents that carry no category. Empty groups are dropped.
-const groups = computed(() => {
-  const ordered = AGENT_CATEGORIES.map((cat) => ({
-    id: cat.id as string,
-    label: cat.label,
-    agents: palette.value.filter((a) => a.category === cat.id),
-  }))
-  const custom = palette.value.filter((a) => !a.category)
-  if (custom.length)
-    ordered.push({ id: 'custom', label: t('palette.customAgents'), agents: custom })
-  return ordered.filter((g) => g.agents.length)
-})
+// Group the palette into the ordered catalog categories, plus a trailing "Custom" bucket for
+// whatever none of them claimed. `groupAgentPalette` owns the placement rule for the same reason
+// `narrowAgentPalette` owns the counting one: it decides what is VISIBLE, and the version living
+// here as an inline computed dropped a kind whose category had no section outright.
+const groups = computed(() =>
+  groupAgentPalette(palette.value, AGENT_CATEGORIES, t('palette.customAgents')),
+)
 
 // Persist which category sections are collapsed across builder opens.
 const collapsed = useLocalStorage<string[]>('cf.pipelineBuilder.collapsedAgentCategories', [])
@@ -64,7 +57,19 @@ function toggle(id: string) {
 <template>
   <div class="space-y-2">
     <p class="px-1 text-[11px] text-slate-500">{{ t('palette.hint') }}</p>
-    <AgentTierSelect :hidden-count="hiddenByTier" />
+    <!-- The two catalog dials, one above the other: what this pipeline is for, and how deep into
+         the agent catalog to look. Both narrow the sections below, and each states its own count.
+         Stacked rather than side by side because the palette column is a third of the slideover:
+         two half-width buttons truncate to "Purpose: Doc…", which is the one thing a filter
+         control may not do. -->
+    <div class="space-y-2">
+      <PipelinePurposeSelect
+        :purpose="props.purpose"
+        :hidden-count="narrowed.hiddenByPurpose"
+        @update:purpose="$emit('update:purpose', $event)"
+      />
+      <AgentTierSelect :hidden-count="narrowed.hiddenByTier" />
+    </div>
     <div class="space-y-2">
       <section v-for="g in groups" :key="g.id">
         <button

package/app/components/palettes/PipelinePurposeSelect.vue

@@ -0,0 +1,80 @@
+<script setup lang="ts">
+// The pipeline-PURPOSE control: what the pipeline being built exists to do (build, document,
+// review, research, plan). It sits beside `AgentTierSelect` at the top of the agent palette
+// because the two are the same kind of dial (each narrows the catalog below to what is worth
+// offering), and a filter the user cannot see is a catalog that looks incomplete for no reason.
+//
+// Unlike the tier, this is not a view preference: it is saved on the pipeline and also decides
+// which task pickers offer it (`pipelineAllowedForTaskType`). So the control writes through to
+// the draft rather than to a store of its own.
+import { computed } from 'vue'
+import { isPipelinePurpose, PIPELINE_PURPOSES, type PipelinePurpose } from '@cat-factory/contracts'
+
+const { t } = useI18n()
+
+const props = defineProps<{
+  /** The draft's purpose. `null` = unclassified, which narrows nothing. */
+  purpose?: PipelinePurpose | null
+  /** How many agent kinds the current purpose hides. Renders the "n hidden" hint when > 0. */
+  hiddenCount?: number
+}>()
+
+const emit = defineEmits<{ (e: 'update:purpose', purpose: PipelinePurpose): void }>()
+
+// One STATIC literal `t()` key per purpose (not a key assembled from the loop variable), so the
+// typed-message-keys check covers them, the same shape `AgentTierSelect` uses for its tiers.
+const PURPOSE_LABELS = computed<Record<PipelinePurpose, string>>(() => ({
+  build: t('pipeline.builder.purposeOption.build'),
+  document: t('pipeline.builder.purposeOption.document'),
+  review: t('pipeline.builder.purposeOption.review'),
+  research: t('pipeline.builder.purposeOption.research'),
+  planning: t('pipeline.builder.purposeOption.planning'),
+}))
+
+// The button text: the chosen purpose, or the placeholder while the draft carries none. An
+// unclassified draft reads as an unmade choice rather than as a purpose called "none", because
+// that is what it is: nothing is filtered until one is picked.
+//
+// A stored purpose this build has no label for is NAMED as unrecognised and quoted back, not
+// folded into the placeholder and not left to render as an empty string after the colon. It is
+// the one state the user cannot diagnose from the control: the palette is unfiltered (see
+// `purposeSuggestsAgentCategory`), so a blank label would read as a pipeline nobody classified
+// while the saved row says otherwise. The menu still lists every current member, so naming the
+// value is also the way out of it.
+const current = computed(() => {
+  const purpose = props.purpose
+  if (!purpose) return t('pipeline.builder.purposePlaceholder')
+  if (!isPipelinePurpose(purpose)) return t('pipeline.builder.purposeUnrecognized', { purpose })
+  return PURPOSE_LABELS.value[purpose]
+})
+
+const items = computed(() => [
+  PIPELINE_PURPOSES.map((purpose) => ({
+    label: PURPOSE_LABELS.value[purpose],
+    icon: purpose === props.purpose ? 'i-lucide-check' : 'i-lucide-target',
+    onSelect: () => emit('update:purpose', purpose),
+  })),
+])
+</script>
+
+<template>
+  <div class="space-y-1">
+    <UDropdownMenu :items="items" :ui="{ content: 'z-[60] max-w-72' }">
+      <UButton
+        size="xs"
+        color="neutral"
+        variant="soft"
+        icon="i-lucide-target"
+        trailing-icon="i-lucide-chevron-down"
+        class="w-full justify-between"
+        :title="t('pipeline.builder.purposeLabel')"
+        data-testid="pipeline-purpose-select"
+      >
+        <span class="truncate"> {{ t('pipeline.builder.purposeLabel') }}: {{ current }} </span>
+      </UButton>
+    </UDropdownMenu>
+    <p v-if="props.hiddenCount" class="px-1 text-[10px] text-slate-500">
+      {{ t('palette.purposeHidden', { count: props.hiddenCount }, props.hiddenCount) }}
+    </p>
+  </div>
+</template>

package/app/components/pipeline/PipelineBuilder.vue

@@ -1,7 +1,7 @@
 <script setup lang="ts">
 import { computed, ref, watch } from 'vue'
 import { purposeAllowsAgentCategory } from '@cat-factory/contracts'
-import type { AgentKind, Pipeline, PipelinePurpose } from '~/types/domain'
+import type { AgentKind, Pipeline } from '~/types/domain'
 import AgentPalette from '~/components/palettes/AgentPalette.vue'
 import AgentKindIcon from '~/components/pipeline/AgentKindIcon.vue'
 import AgentPromptEditor from '~/components/pipeline/AgentPromptEditor.vue'
@@ -30,18 +30,6 @@ const CONSENSUS_STRATEGIES = computed<{ value: ConsensusStrategy; label: string
   { value: 'ranked-voting', label: t('pipeline.builder.strategyOption.ranked-voting') },
 ])
 
-// The use-case classifier options for the pipeline (its `purpose`). Static literal `t()` keys, one
-// per `PIPELINE_PURPOSES` member, so the typed-message-keys check sees them (a runtime-built key
-// wouldn't be checkable). A non-`build` purpose hides the Implementation/Testing agent kinds in
-// the palette below (see `AgentPalette`), and drives which task pickers offer the saved pipeline.
-const PURPOSE_OPTIONS = computed<{ value: PipelinePurpose; label: string }[]>(() => [
-  { value: 'build', label: t('pipeline.builder.purposeOption.build') },
-  { value: 'document', label: t('pipeline.builder.purposeOption.document') },
-  { value: 'review', label: t('pipeline.builder.purposeOption.review') },
-  { value: 'research', label: t('pipeline.builder.purposeOption.research') },
-  { value: 'planning', label: t('pipeline.builder.purposeOption.planning') },
-])
-
 /** Add a blank participant to the draft step's consensus config. */
 function addParticipant(i: number) {
   const cfg = pipelines.draftConsensus[i]
@@ -208,12 +196,16 @@ const skillStepNeedsPick = computed(() =>
   ),
 )
 
-// Steps whose agent category the chosen purpose forbids (a non-`build` purpose writes no code and
-// runs no tests, so the Implementation/Testing categories are disallowed — see
-// `purposeAllowsAgentCategory`). The palette hides those kinds, so this is only reachable by
-// switching an existing draft to a non-`build` purpose AFTER such steps were added. The backend has
-// no kind→category map to gate on, so the builder is the enforcement point: save is blocked until
-// the offending steps are removed (or the purpose set back to Build).
+// Steps whose agent category the chosen purpose CONTRADICTS (a non-`build` purpose writes no code
+// and runs no tests, so the Implementation/Testing categories are disallowed, see
+// `purposeAllowsAgentCategory`). Only reachable by switching an existing draft to a non-`build`
+// purpose AFTER such steps were added, since the palette offers neither. The backend has no
+// kind→category map to gate on, so the builder is the enforcement point: save is blocked until the
+// offending steps are removed (or the purpose set back to Build).
+//
+// Deliberately the compatibility predicate, not the palette's narrower relevance one: a purpose
+// that merely stops SUGGESTING a category must not turn a pipeline somebody already built into
+// one they cannot save.
 const stepsDisallowedByPurpose = computed(() =>
   pipelines.draft.filter((kind) => {
     const category = agentKindMeta(kind).category
@@ -492,7 +484,7 @@ async function clone(p: Pipeline) {
             </UButton>
           </div>
           <div class="flex-1 pe-1 lg:min-h-0 lg:overflow-y-auto">
-            <AgentPalette :purpose="pipelines.draftPurpose" @add="add" />
+            <AgentPalette v-model:purpose="pipelines.draftPurpose" @add="add" />
           </div>
         </div>
 
@@ -524,24 +516,6 @@ async function clone(p: Pipeline) {
             data-testid="pipeline-builder-name"
           />
 
-          <!-- Purpose: the pipeline's use-case classifier. Drives which task pickers offer it (a
-               document task offers only `document` pipelines) and narrows the palette below (a
-               non-build purpose hides the Implementation/Testing kinds). -->
-          <div class="mb-2 flex items-center gap-2">
-            <label class="shrink-0 text-[11px] font-medium text-slate-400">
-              {{ t('pipeline.builder.purposeLabel') }}
-            </label>
-            <USelect
-              :model-value="pipelines.draftPurpose ?? undefined"
-              :items="PURPOSE_OPTIONS"
-              value-key="value"
-              size="sm"
-              class="min-w-40"
-              :placeholder="t('pipeline.builder.purposePlaceholder')"
-              @update:model-value="pipelines.draftPurpose = $event"
-            />
-          </div>
-
           <!-- Description: the prose summary shown next to the step list in the pipeline pickers. -->
           <UTextarea
             v-model="pipelines.draftDescription"

package/app/utils/agentPalette.spec.ts

@@ -0,0 +1,145 @@
+import { describe, expect, it } from 'vitest'
+import type { AgentArchetype } from '~/types/domain'
+import { groupAgentPalette, narrowAgentPalette } from '~/utils/agentPalette'
+
+const archetype = (
+  kind: string,
+  category?: AgentArchetype['category'],
+  tier?: AgentArchetype['tier'],
+): AgentArchetype => ({
+  kind: kind as AgentArchetype['kind'],
+  label: kind,
+  icon: 'i-lucide-bot',
+  color: '#fff',
+  description: kind,
+  ...(category ? { category } : {}),
+  ...(tier ? { tier } : {}),
+})
+
+// Spread across both dials on purpose: every combination of relevant/irrelevant to a `planning`
+// pipeline (which keeps `review` + `design` and drops `build` / `test` / `docs` / `gates`) and
+// visible/hidden at the `basic` tier, so the two counts cannot both be right by coincidence.
+const CATALOG: AgentArchetype[] = [
+  archetype('coder', 'build', 'basic'), // irrelevant, in tier
+  archetype('tester', 'test', 'advanced'), // irrelevant AND out of tier
+  archetype('architect', 'design', 'basic'), // relevant, in tier
+  archetype('researcher', 'design', 'advanced'), // relevant, out of tier
+  archetype('documenter', 'docs', 'basic'), // irrelevant, in tier
+  // A deployment-registered kind declaring neither: no category to judge (always relevant) and an
+  // absent tier, which defaults to `intermediate` and so is out of the basic tier.
+  archetype('acme-auditor'),
+]
+
+describe('narrowAgentPalette', () => {
+  it('narrows nothing for an unclassified pipeline at the widest tier', () => {
+    const { offered, hiddenByPurpose, hiddenByTier } = narrowAgentPalette(CATALOG, null, 'advanced')
+    expect(offered.map((a) => a.kind)).toEqual(CATALOG.map((a) => a.kind))
+    expect(hiddenByPurpose).toBe(0)
+    expect(hiddenByTier).toBe(0)
+  })
+
+  it('accumulates the tiers when the purpose narrows nothing', () => {
+    expect(narrowAgentPalette(CATALOG, null, 'basic').offered.map((a) => a.kind)).toEqual([
+      'coder',
+      'architect',
+      'documenter',
+    ])
+    expect(narrowAgentPalette(CATALOG, null, 'intermediate').offered.map((a) => a.kind)).toEqual([
+      'coder',
+      'architect',
+      'documenter',
+      // An undeclared tier defaults to intermediate, so it appears here.
+      'acme-auditor',
+    ])
+    expect(narrowAgentPalette(CATALOG, null, 'basic').hiddenByTier).toBe(3)
+  })
+
+  it('counts each dial against what the OTHER already admits', () => {
+    // The regression this shape exists for: measuring the purpose count over the whole catalog
+    // reported 3 here (coder, tester, documenter) while switching back to Build at this tier
+    // reveals only 2: `tester` is tier-hidden either way, so naming it under the purpose control
+    // sends the reader to a dial that cannot produce it.
+    const { offered, hiddenByPurpose, hiddenByTier } = narrowAgentPalette(
+      CATALOG,
+      'planning',
+      'basic',
+    )
+    expect(offered.map((a) => a.kind)).toEqual(['architect'])
+    expect(hiddenByPurpose).toBe(2)
+    expect(hiddenByTier).toBe(2)
+  })
+
+  it('states the full purpose narrowing once the tier stops hiding anything', () => {
+    const { offered, hiddenByPurpose, hiddenByTier } = narrowAgentPalette(
+      CATALOG,
+      'planning',
+      'advanced',
+    )
+    // The uncategorized kind has nothing for the purpose dial to judge, so it stays offered.
+    expect(offered.map((a) => a.kind)).toEqual(['architect', 'researcher', 'acme-auditor'])
+    expect(hiddenByPurpose).toBe(3)
+    expect(hiddenByTier).toBe(0)
+  })
+
+  it('leaves a kind both dials hide out of both counts', () => {
+    // Each count promises "relax THIS dial alone and you get n more", and relaxing either alone
+    // would not reveal `tester`. So the four buckets partition the catalog with it in none of the
+    // three the palette names, which is the property that keeps the two hints from double-counting.
+    const { offered, hiddenByPurpose, hiddenByTier } = narrowAgentPalette(
+      CATALOG,
+      'planning',
+      'basic',
+    )
+    const hiddenByBoth = CATALOG.length - offered.length - hiddenByPurpose - hiddenByTier
+    expect(hiddenByBoth).toBe(1)
+  })
+
+  it('keeps a purpose this build does not recognise from narrowing anything', () => {
+    // A stored `purpose` from a build that shipped a member this one has not (or has retired):
+    // unknown is not a licence to guess, so the palette offers what the tier admits and says so.
+    const purpose = 'acme-migration' as never
+    const { offered, hiddenByPurpose } = narrowAgentPalette(CATALOG, purpose, 'advanced')
+    expect(offered.map((a) => a.kind)).toEqual(CATALOG.map((a) => a.kind))
+    expect(hiddenByPurpose).toBe(0)
+  })
+})
+
+// The rendered sections, mirroring `utils/catalog.ts` shape (id + display label).
+const SECTIONS = [
+  { id: 'design', label: 'Design & research' },
+  { id: 'build', label: 'Implementation' },
+  { id: 'test', label: 'Testing' },
+  { id: 'docs', label: 'Documentation' },
+]
+
+describe('groupAgentPalette', () => {
+  it('fills the sections in their given order and drops the empty ones', () => {
+    const groups = groupAgentPalette(CATALOG, SECTIONS, 'Custom agents')
+    expect(groups.map((g) => [g.id, g.agents.map((a) => a.kind)])).toEqual([
+      ['design', ['architect', 'researcher']],
+      ['build', ['coder']],
+      ['test', ['tester']],
+      ['docs', ['documenter']],
+      // The uncategorized kind, in the trailing bucket. `review` and `gates` have no members
+      // here, so neither section is rendered at all.
+      ['custom', ['acme-auditor']],
+    ])
+  })
+
+  it('files a kind whose category has no section under custom rather than deleting it', () => {
+    // The regression: every section filter misses it AND so does a bare `!a.category`, so it
+    // vanished from a palette whose save gate accepts it. Reachable from both sides (a
+    // deployment-registered kind naming a category this build retired, and this list drifting
+    // behind the schema), which is why the leftover bucket is derived from the sections.
+    const registered = archetype('acme-auditor', 'observability' as never, 'basic')
+    const groups = groupAgentPalette([registered], SECTIONS, 'Custom agents')
+    expect(groups).toEqual([{ id: 'custom', label: 'Custom agents', agents: [registered] }])
+  })
+
+  it('renders no custom section when every kind was claimed', () => {
+    const claimed = CATALOG.filter((a) => a.category)
+    const groups = groupAgentPalette(claimed, SECTIONS, 'Custom agents')
+    expect(groups.map((g) => g.id)).not.toContain('custom')
+    expect(groups.flatMap((g) => g.agents)).toHaveLength(claimed.length)
+  })
+})

package/app/utils/agentPalette.ts

@@ -0,0 +1,89 @@
+import {
+  type AgentTier,
+  agentTierVisibleAt,
+  type PipelinePurpose,
+  purposeSuggestsAgentCategory,
+} from '@cat-factory/contracts'
+import type { AgentArchetype } from '~/types/domain'
+
+/**
+ * The pipeline builder's palette narrows the agent catalog on TWO dials, and the pair is the
+ * reason this reduction is one function rather than two chained filters at the call site.
+ *
+ * The dials are independent (the pipeline's PURPOSE says which categories the work has any use
+ * for, the agent TIER says how deep into the catalog to look), but their hints are not, because
+ * each hint is an invitation to reach for that dial. Chaining the filters and subtracting the
+ * lengths gives the second dial an honest count and the first one the whole rest of the catalog,
+ * so at the default `basic` tier a `planning` pipeline reported thirteen kinds hidden for its
+ * purpose when switching back to Build revealed three: the other ten were tier-hidden either way.
+ * That is exactly the "chasing a control that cannot help them" the ordering was meant to avoid,
+ * just pointed at the other dial.
+ *
+ * So each count is measured against what the OTHER dial already admits, which makes both of them
+ * the same promise: relax THIS dial alone and you get n more. A kind both dials hide is counted
+ * by neither, and correctly: relaxing either one alone would not reveal it.
+ */
+export interface NarrowedAgentPalette<T> {
+  /** The archetypes both dials admit: what the palette renders, in input order. */
+  offered: T[]
+  /** How many more the CURRENT tier would show if the purpose narrowed nothing. */
+  hiddenByPurpose: number
+  /** How many more the CURRENT purpose would show at the widest tier. */
+  hiddenByTier: number
+}
+
+/**
+ * Reduce `archetypes` to what the palette offers at `purpose` + `tier`, with each dial's hint
+ * count (see {@link NarrowedAgentPalette} for what the counts promise).
+ *
+ * An archetype carrying no `category` has nothing for the purpose dial to judge, so it is always
+ * relevant; an absent `tier` is `DEFAULT_AGENT_TIER`. Both are how a deployment-registered kind
+ * that declares neither behaves, and neither is a reason to drop it from the catalog.
+ */
+export function narrowAgentPalette<T extends Pick<AgentArchetype, 'tier' | 'category'>>(
+  archetypes: readonly T[],
+  purpose: PipelinePurpose | null | undefined,
+  tier: AgentTier,
+): NarrowedAgentPalette<T> {
+  const relevant = (a: T) => !a.category || purposeSuggestsAgentCategory(purpose, a.category)
+  const inTier = (a: T) => agentTierVisibleAt(a.tier, tier)
+  return {
+    offered: archetypes.filter((a) => relevant(a) && inTier(a)),
+    hiddenByPurpose: archetypes.filter((a) => inTier(a) && !relevant(a)).length,
+    hiddenByTier: archetypes.filter((a) => relevant(a) && !inTier(a)).length,
+  }
+}
+
+/** One rendered palette section: an ordered category, or the trailing custom bucket. */
+export interface AgentPaletteGroup<T> {
+  id: string
+  label: string
+  agents: T[]
+}
+
+/**
+ * Group what the palette offers into `sections` in their given order, with everything left over
+ * in a trailing bucket under `customLabel`. Empty sections are dropped.
+ *
+ * The leftover bucket is what no section CLAIMED, not what carries no `category`, and the two are
+ * different populations: an archetype whose category has no section here belongs to neither, so
+ * testing for the absent one alone silently DELETED it from the palette. A `presentation.category`
+ * comes from a kind a DEPLOYMENT registered and `sections` is the SPA's own mirror of the schema,
+ * so the gap opens from either side, and the save gate accepts such a kind either way. Showing it
+ * under "custom" says what is true: nothing here knows where to file it.
+ */
+export function groupAgentPalette<T extends Pick<AgentArchetype, 'category'>>(
+  offered: readonly T[],
+  sections: readonly { id: string; label: string }[],
+  customLabel: string,
+): AgentPaletteGroup<T>[] {
+  const claimed = new Set<string>(sections.map((s) => s.id))
+  const groups: AgentPaletteGroup<T>[] = sections.map((s) => ({
+    id: s.id,
+    label: s.label,
+    agents: offered.filter((a) => a.category === s.id),
+  }))
+  const custom = offered.filter((a) => !a.category || !claimed.has(a.category))
+  if (custom.length) groups.push({ id: 'custom', label: customLabel, agents: custom })
+  return groups.filter((g) => g.agents.length)
+}

package/app/utils/agentTier.spec.ts

@@ -1,6 +1,6 @@
 import { describe, expect, it } from 'vitest'
 import type { AgentArchetype } from '~/types/domain'
-import { filterByAgentTier, filterByAgentTierKeeping, isAgentTier } from '~/utils/agentTier'
+import { filterByAgentTierKeeping, isAgentTier } from '~/utils/agentTier'
 
 const archetype = (kind: string, tier?: AgentArchetype['tier']): AgentArchetype => ({
   kind: kind as AgentArchetype['kind'],
@@ -19,22 +19,6 @@ const CATALOG: AgentArchetype[] = [
   archetype('acme-auditor'),
 ]
 
-describe('filterByAgentTier', () => {
-  it('shows only the basic kinds at the default level', () => {
-    expect(filterByAgentTier(CATALOG, 'basic').map((a) => a.kind)).toEqual(['coder'])
-  })
-
-  it('accumulates the levels, with advanced showing the whole catalog', () => {
-    expect(filterByAgentTier(CATALOG, 'intermediate').map((a) => a.kind)).toEqual([
-      'coder',
-      'researcher',
-      // An undeclared tier defaults to intermediate, so it appears here.
-      'acme-auditor',
-    ])
-    expect(filterByAgentTier(CATALOG, 'advanced')).toHaveLength(CATALOG.length)
-  })
-})
-
 describe('filterByAgentTierKeeping', () => {
   it('keeps a pinned kind the tier would otherwise hide, in catalog order', () => {
     const kept = filterByAgentTierKeeping(CATALOG, 'basic', (a) => a.kind === 'mocker')

package/app/utils/agentTier.ts

@@ -25,14 +25,6 @@ export function isAgentTier(value: unknown): value is AgentTier {
   return typeof value === 'string' && (AGENT_TIERS as readonly string[]).includes(value)
 }
 
-/** Keep only the archetypes visible at `level` (cumulative — see `agentTierVisibleAt`). */
-export function filterByAgentTier<T extends Pick<AgentArchetype, 'tier'>>(
-  archetypes: readonly T[],
-  level: AgentTier,
-): T[] {
-  return archetypes.filter((a) => agentTierVisibleAt(a.tier, level))
-}
-
 /**
  * Keep the archetypes visible at `level`, PLUS any the caller marks as pinned — the model
  * preset editor's kinds that already carry an override. An entity can hold a setting written

package/app/utils/pipeline.spec.ts

@@ -1,8 +1,13 @@
 import { describe, expect, it } from 'vitest'
 import {
+  agentCategorySchema,
+  isAgentCategory,
+  isPipelinePurpose,
+  PIPELINE_PURPOSES,
   pipelineAllowedForBlockLevel,
   pipelineAllowedForTaskType,
   purposeAllowsAgentCategory,
+  purposeSuggestsAgentCategory,
 } from '@cat-factory/contracts'
 import type { Block, Pipeline } from '~/types/domain'
 import {
@@ -12,6 +17,17 @@ import {
   pipelineGateCount,
 } from '~/utils/pipeline'
 
+// The palette categories, read off the schema the predicates themselves are typed against, so a
+// new category joins these sweeps instead of quietly going unasserted behind a hand-listed tuple.
+const AGENT_CATEGORIES = agentCategorySchema.options
+
+// A `purpose` typed as a member and only DECLARED to be one: `Pipeline.purpose` is persisted and
+// no boundary re-checks it against the union this build compiled, so a browser on a cached bundle
+// sees a member shipped after it and a retired member goes on living in saved rows. Same story for
+// a `presentation.category`, which arrives in the snapshot from a deployment-registered kind.
+const UNKNOWN_PURPOSE = 'acme-migration' as never
+const UNKNOWN_CATEGORY = 'observability' as never
+
 // A minimal pipeline: only the fields the launch/task-type filters read matter here.
 function pipeline(over: Partial<Pipeline> = {}): Pipeline {
   return { id: 'pl_x', name: 'X', agentKinds: ['coder'], ...over } as Pipeline
@@ -134,20 +150,21 @@ describe('pipelineAllowedForBlockLevel (initiative binding)', () => {
   })
 })
 
-describe('purposeAllowsAgentCategory (builder palette gate)', () => {
+describe('purposeAllowsAgentCategory (builder save gate)', () => {
   it('a build (or unclassified) pipeline may use every category', () => {
     for (const purpose of ['build', null, undefined] as const) {
-      for (const cat of ['review', 'design', 'build', 'test', 'docs', 'gates'] as const) {
+      for (const cat of AGENT_CATEGORIES) {
         expect(purposeAllowsAgentCategory(purpose, cat)).toBe(true)
       }
     }
   })
 
-  it('a non-build pipeline hides the Implementation (build) and Testing (test) categories', () => {
+  it('a non-build pipeline refuses the Implementation (build) and Testing (test) categories', () => {
     for (const purpose of ['document', 'review', 'research', 'planning'] as const) {
       expect(purposeAllowsAgentCategory(purpose, 'build')).toBe(false)
       expect(purposeAllowsAgentCategory(purpose, 'test')).toBe(false)
-      // Non-code categories stay visible.
+      // Everything else stays SAVEABLE even where the palette stops offering it (below), so a
+      // stored pipeline never becomes unsaveable because the relevance table gained an opinion.
       expect(purposeAllowsAgentCategory(purpose, 'docs')).toBe(true)
       expect(purposeAllowsAgentCategory(purpose, 'review')).toBe(true)
       expect(purposeAllowsAgentCategory(purpose, 'gates')).toBe(true)
@@ -155,6 +172,70 @@ describe('purposeAllowsAgentCategory (builder palette gate)', () => {
   })
 })
 
+describe('purposeSuggestsAgentCategory (builder palette filter)', () => {
+  it('offers the whole catalog to a build pipeline and to an unclassified one', () => {
+    for (const purpose of ['build', null, undefined] as const) {
+      for (const cat of AGENT_CATEGORIES) {
+        expect(purposeSuggestsAgentCategory(purpose, cat)).toBe(true)
+      }
+    }
+  })
+
+  it('narrows each purpose to the categories it has a use for', () => {
+    // A PR review designs nothing and builds nothing; the plan an initiative pipeline produces
+    // is its own in-repo tracker, with no pull request to gate and no repo docs to write.
+    expect(purposeSuggestsAgentCategory('review', 'design')).toBe(false)
+    expect(purposeSuggestsAgentCategory('review', 'review')).toBe(true)
+    expect(purposeSuggestsAgentCategory('planning', 'gates')).toBe(false)
+    expect(purposeSuggestsAgentCategory('planning', 'docs')).toBe(false)
+    expect(purposeSuggestsAgentCategory('planning', 'design')).toBe(true)
+    // Authoring a document and running a spike are researched and reviewed like any change.
+    for (const purpose of ['document', 'research'] as const) {
+      expect(purposeSuggestsAgentCategory(purpose, 'design')).toBe(true)
+      expect(purposeSuggestsAgentCategory(purpose, 'docs')).toBe(true)
+    }
+  })
+
+  it('never offers what the save gate would refuse', () => {
+    // The invariant that keeps the two tables honest, over the whole grid rather than the cells
+    // that happen to differ today: relevance may hide more than compatibility, never less, or
+    // the palette would offer a kind whose step then blocks the save. The unknown purpose rides
+    // the same sweep because it is the case where the two could most easily read the same value
+    // in opposite directions, one narrowing by it and the other not.
+    for (const purpose of [...PIPELINE_PURPOSES, UNKNOWN_PURPOSE]) {
+      for (const cat of AGENT_CATEGORIES) {
+        if (purposeSuggestsAgentCategory(purpose, cat)) {
+          expect(purposeAllowsAgentCategory(purpose, cat)).toBe(true)
+        }
+      }
+    }
+  })
+})
+
+describe('a purpose or category this build does not recognise', () => {
+  it('is recognised as unknown rather than trusted', () => {
+    for (const purpose of PIPELINE_PURPOSES) expect(isPipelinePurpose(purpose)).toBe(true)
+    for (const cat of AGENT_CATEGORIES) expect(isAgentCategory(cat)).toBe(true)
+    expect(isPipelinePurpose('acme-migration')).toBe(false)
+    expect(isPipelinePurpose('')).toBe(false)
+    expect(isAgentCategory('observability')).toBe(false)
+  })
+
+  it('narrows nothing, in the palette or the save gate', () => {
+    // Both predicates index a table by these values, so before the guards an unknown purpose threw
+    // inside the palette's computed and white-screened the builder, while an unknown category read
+    // as `undefined` and silently dropped a registered kind the save gate would have accepted.
+    // Unknown means this build has nothing to narrow by, which is exactly what absent already means.
+    for (const cat of AGENT_CATEGORIES) {
+      expect(purposeSuggestsAgentCategory(UNKNOWN_PURPOSE, cat)).toBe(true)
+      expect(purposeAllowsAgentCategory(UNKNOWN_PURPOSE, cat)).toBe(true)
+    }
+    for (const purpose of PIPELINE_PURPOSES) {
+      expect(purposeSuggestsAgentCategory(purpose, UNKNOWN_CATEGORY)).toBe(true)
+    }
+  })
+})
+
 describe('pipelineAllowedForManualStart composes the task-type gate', () => {
   const noFrame = undefined
   const blocks: Block[] = []

package/i18n/locales/de.json

@@ -4214,6 +4214,7 @@
       "rounds": "Runden",
       "purposeLabel": "Zweck",
       "purposePlaceholder": "Zweck auswählen",
+      "purposeUnrecognized": "Nicht erkannt ({purpose})",
       "purposeOption": {
         "build": "Entwicklung",
         "document": "Dokumentation",
@@ -6734,7 +6735,8 @@
   },
   "palette": {
     "hint": "Klicke auf einen Agenten, um ihn an die Pipeline anzuhängen.",
-    "customAgents": "Benutzerdefinierte Agenten"
+    "customAgents": "Benutzerdefinierte Agenten",
+    "purposeHidden": "{count} Agent ist für diesen Zweck ausgeblendet. | {count} Agenten sind für diesen Zweck ausgeblendet."
   },
   "forkDecision": {
     "title": "Implementierungsansatz wählen",

package/i18n/locales/en.json

@@ -4796,6 +4796,10 @@
       "rounds": "Rounds",
       "purposeLabel": "Purpose",
       "purposePlaceholder": "Select a purpose",
+      "purposeUnrecognized": "Unrecognized ({purpose})",
+      "@purposeUnrecognized": {
+        "description": "Shown on the pipeline-purpose control when the pipeline carries a purpose this build has no label for (a member added by a newer build, or one since retired). The raw stored value is quoted back so it can be recognised and re-picked."
+      },
       "purposeOption": {
         "build": "Build",
         "document": "Documentation",
@@ -5129,7 +5133,11 @@
   },
   "palette": {
     "hint": "Click an agent to append it to the pipeline.",
-    "customAgents": "Custom agents"
+    "customAgents": "Custom agents",
+    "purposeHidden": "{count} agent hidden for this purpose. | {count} agents hidden for this purpose.",
+    "@purposeHidden": {
+      "description": "Shown under the pipeline-purpose control in the agent palette: how many agents are not offered because they are irrelevant to the pipeline's purpose (e.g. a coder in a documentation pipeline)."
+    }
   },
   "gates": {
     "subtitle": {

package/i18n/locales/es.json

@@ -4653,6 +4653,7 @@
       "rounds": "Rondas",
       "purposeLabel": "Propósito",
       "purposePlaceholder": "Seleccionar un propósito",
+      "purposeUnrecognized": "No reconocido ({purpose})",
       "purposeOption": {
         "build": "Desarrollo",
         "document": "Documentación",
@@ -4903,7 +4904,8 @@
   },
   "palette": {
     "hint": "Haz clic en un agente para añadirlo al pipeline.",
-    "customAgents": "Agentes personalizados"
+    "customAgents": "Agentes personalizados",
+    "purposeHidden": "{count} agente oculto para este propósito. | {count} agentes ocultos para este propósito."
   },
   "gates": {
     "subtitle": {

package/i18n/locales/fr.json

@@ -4653,6 +4653,7 @@
       "rounds": "Tours",
       "purposeLabel": "Objectif",
       "purposePlaceholder": "Sélectionner un objectif",
+      "purposeUnrecognized": "Non reconnu ({purpose})",
       "purposeOption": {
         "build": "Développement",
         "document": "Documentation",
@@ -4903,7 +4904,8 @@
   },
   "palette": {
     "hint": "Cliquez sur un agent pour l'ajouter au pipeline.",
-    "customAgents": "Agents personnalisés"
+    "customAgents": "Agents personnalisés",
+    "purposeHidden": "{count} agent masqué pour cet objectif. | {count} agents masqués pour cet objectif."
   },
   "gates": {
     "subtitle": {

package/i18n/locales/he.json

@@ -4653,6 +4653,7 @@
       "rounds": "סבבים",
       "purposeLabel": "מטרה",
       "purposePlaceholder": "בחר מטרה",
+      "purposeUnrecognized": "לא מזוהה ({purpose})",
       "purposeOption": {
         "build": "פיתוח",
         "document": "תיעוד",
@@ -4903,7 +4904,8 @@
   },
   "palette": {
     "hint": "לחץ על סוכן כדי להוסיף אותו לצינור.",
-    "customAgents": "סוכנים מותאמים אישית"
+    "customAgents": "סוכנים מותאמים אישית",
+    "purposeHidden": "סוכן אחד מוסתר עבור מטרה זו. | שני סוכנים מוסתרים עבור מטרה זו. | {count} סוכנים מוסתרים עבור מטרה זו."
   },
   "gates": {
     "subtitle": {

package/i18n/locales/it.json

@@ -4214,6 +4214,7 @@
       "rounds": "Giri",
       "purposeLabel": "Scopo",
       "purposePlaceholder": "Seleziona uno scopo",
+      "purposeUnrecognized": "Non riconosciuto ({purpose})",
       "purposeOption": {
         "build": "Sviluppo",
         "document": "Documentazione",
@@ -6734,7 +6735,8 @@
   },
   "palette": {
     "hint": "Clicca su un agente per aggiungerlo alla pipeline.",
-    "customAgents": "Agenti personalizzati"
+    "customAgents": "Agenti personalizzati",
+    "purposeHidden": "{count} agente nascosto per questo scopo. | {count} agenti nascosti per questo scopo."
   },
   "forkDecision": {
     "title": "Scegli un approccio di implementazione",

package/i18n/locales/ja.json

@@ -4653,6 +4653,7 @@
       "rounds": "ラウンド",
       "purposeLabel": "目的",
       "purposePlaceholder": "目的を選択",
+      "purposeUnrecognized": "認識できません ({purpose})",
       "purposeOption": {
         "build": "開発",
         "document": "ドキュメント",
@@ -4903,7 +4904,8 @@
   },
   "palette": {
     "hint": "エージェントをクリックするとパイプラインに追加されます。",
-    "customAgents": "カスタムエージェント"
+    "customAgents": "カスタムエージェント",
+    "purposeHidden": "この目的では {count} 件のエージェントが非表示です。"
   },
   "gates": {
     "subtitle": {

package/i18n/locales/pl.json

@@ -4653,6 +4653,7 @@
       "rounds": "Rundy",
       "purposeLabel": "Cel",
       "purposePlaceholder": "Wybierz cel",
+      "purposeUnrecognized": "Nierozpoznany ({purpose})",
       "purposeOption": {
         "build": "Programowanie",
         "document": "Dokumentacja",
@@ -4903,7 +4904,8 @@
   },
   "palette": {
     "hint": "Kliknij agenta, aby dodać go do pipeline'u.",
-    "customAgents": "Agenci niestandardowi"
+    "customAgents": "Agenci niestandardowi",
+    "purposeHidden": "{count} agent ukryty dla tego celu. | {count} agenci ukryci dla tego celu. | {count} agentów ukrytych dla tego celu."
   },
   "gates": {
     "subtitle": {

package/i18n/locales/tr.json

@@ -4653,6 +4653,7 @@
       "rounds": "Tur",
       "purposeLabel": "Amaç",
       "purposePlaceholder": "Bir amaç seçin",
+      "purposeUnrecognized": "Tanınmayan ({purpose})",
       "purposeOption": {
         "build": "Geliştirme",
         "document": "Dokümantasyon",
@@ -4903,7 +4904,8 @@
   },
   "palette": {
     "hint": "Bir agent'ı pipeline'a eklemek için tıklayın.",
-    "customAgents": "Özel agent'lar"
+    "customAgents": "Özel agent'lar",
+    "purposeHidden": "Bu amaç için {count} ajan gizli."
   },
   "gates": {
     "subtitle": {

package/i18n/locales/uk.json

@@ -4653,6 +4653,7 @@
       "rounds": "Раунди",
       "purposeLabel": "Призначення",
       "purposePlaceholder": "Виберіть призначення",
+      "purposeUnrecognized": "Нерозпізнано ({purpose})",
       "purposeOption": {
         "build": "Розробка",
         "document": "Документація",
@@ -4903,7 +4904,8 @@
   },
   "palette": {
     "hint": "Натисніть агента, щоб додати його до пайплайну.",
-    "customAgents": "Власні агенти"
+    "customAgents": "Власні агенти",
+    "purposeHidden": "{count} агента приховано для цього призначення. | {count} агентів приховано для цього призначення. | {count} агентів приховано для цього призначення."
   },
   "gates": {
     "subtitle": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cat-factory/app",
-  "version": "0.253.2",
+  "version": "0.254.1",
   "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",
@@ -40,7 +40,7 @@
     "valibot": "^1.4.2",
     "vue": "3.5.40",
     "wretch": "^3.0.9",
-    "@cat-factory/contracts": "0.276.0"
+    "@cat-factory/contracts": "0.278.0"
   },
   "devDependencies": {
     "@toad-contracts/testing": "0.3.2",