From fc7a2525e5a1ae960c182b8d3299607fa1071a82 Mon Sep 17 00:00:00 2001
From: Ali Al Dallal <ali@alicoding.com>
Date: Mon, 17 Aug 2026 20:02:05 -0400
Subject: [PATCH] feat: faceted search -- typed inline qualifier for palette,
 Quick Panel, Atlas jump (goal 0086)

Adds a shared `<label>: <text>` grammar (shared/facetQuery.ts) so the
command palette, Quick Panel, and Atlas jump dialog all scope a search
to one type the same way -- a suggestion-chip row (shared/FacetChipRow.tsx)
completes the token on click, with typing the token itself as the
primary path. filterJumpCards gains a scope parameter for kind/area
scoping in the Atlas jump.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01FW5GkkAG8du7tNdYLk2zSd
---
 frontend/e2e/atlas-jump.spec.ts             | 48 +++++++++++
 frontend/e2e/command-palette.spec.ts        | 59 +++++++++++++
 frontend/src/app/CommandPalette.tsx         | 57 ++++++++++++-
 frontend/src/app/QuickPanel.tsx             | 12 ++-
 frontend/src/app/quickPanelFacets.ts        | 81 ++++++++++++++++++
 frontend/src/atlas/AtlasJumpDialog.tsx      | 37 +++++++-
 frontend/src/atlas/atlasJumpFilter.test.ts  | 53 +++++++++++-
 frontend/src/atlas/atlasJumpFilter.ts       | 33 ++++++--
 frontend/src/locales/en/app.json            | 18 ++++
 frontend/src/locales/en/atlas.json          |  4 +-
 frontend/src/shared/FacetChipRow.module.css | 42 ++++++++++
 frontend/src/shared/FacetChipRow.tsx        | 46 ++++++++++
 frontend/src/shared/facetQuery.test.ts      | 93 +++++++++++++++++++++
 frontend/src/shared/facetQuery.ts           | 63 ++++++++++++++
 14 files changed, 632 insertions(+), 14 deletions(-)
 create mode 100644 frontend/src/app/quickPanelFacets.ts
 create mode 100644 frontend/src/shared/FacetChipRow.module.css
 create mode 100644 frontend/src/shared/FacetChipRow.tsx
 create mode 100644 frontend/src/shared/facetQuery.test.ts
 create mode 100644 frontend/src/shared/facetQuery.ts

diff --git a/frontend/e2e/atlas-jump.spec.ts b/frontend/e2e/atlas-jump.spec.ts
index a33f3764..1ae99309 100644
--- a/frontend/e2e/atlas-jump.spec.ts
+++ b/frontend/e2e/atlas-jump.spec.ts
@@ -151,3 +151,51 @@ test('no matches shows the empty-result row instead of an empty list', async ({
 
   await page.keyboard.press('Escape')
 })
+
+// Faceted search (goal 0086, shared/facetQuery.ts): vocabulary is every
+// Kind's own Label + "area". "My space"/"Example area"/"Getting
+// started"/"Scratchpad" are all Topic-kind (builtin.go's own seed
+// comment: containment is a role, not a Kind); "Ada Lovelace" is
+// Contact and "Project charter" is Document -- scoping to "Topic:"
+// with empty text must list exactly the four, excluding both others.
+test('"Topic: " lists every Topic-kind card, excluding other kinds', async ({ page }) => {
+  await page.goto('/')
+  await page.getByRole('link', { name: 'Atlas' }).click()
+  await expect(page.getByTestId('atlas-board')).toBeVisible()
+  await page.keyboard.press('Meta+k')
+  await expect(jumpDialog(page)).toBeVisible()
+
+  await page.getByTestId('atlas-jump-input').fill('Topic: ')
+
+  const results = jumpDialog(page).getByTestId('atlas-jump-result')
+  await expect(results).toHaveCount(4)
+  // Title-ascending, same order filterJumpCards' stableSortResults produces.
+  await expect(results).toContainText(['Example area', 'Getting started', 'My space', 'Scratchpad'])
+  await expect(jumpDialog(page)).not.toContainText('Ada Lovelace')
+  await expect(jumpDialog(page)).not.toContainText('Project charter')
+
+  await page.keyboard.press('Escape')
+})
+
+test('typing a Kind-label prefix offers a kind-glyph-colored suggestion chip; clicking it scopes the search', async ({ page }) => {
+  await page.goto('/')
+  await page.getByRole('link', { name: 'Atlas' }).click()
+  await expect(page.getByTestId('atlas-board')).toBeVisible()
+  await page.keyboard.press('Meta+k')
+  await expect(jumpDialog(page)).toBeVisible()
+
+  const input = page.getByTestId('atlas-jump-input')
+  await input.fill('to')
+
+  const chip = jumpDialog(page).getByRole('button', { name: 'Topic' })
+  await expect(chip).toBeVisible()
+  await expect(chip.getByTestId('facet-chip-dot')).toBeVisible()
+
+  await chip.click()
+  await expect(input).toHaveValue('Topic: ')
+  await expect(jumpDialog(page).getByTestId('atlas-jump-result')).toHaveCount(4)
+  // The chip row is a completion aid only -- gone once a scope is active.
+  await expect(jumpDialog(page).getByRole('button', { name: 'Topic' })).toHaveCount(0)
+
+  await page.keyboard.press('Escape')
+})
diff --git a/frontend/e2e/command-palette.spec.ts b/frontend/e2e/command-palette.spec.ts
index 94a318a9..ec948efd 100644
--- a/frontend/e2e/command-palette.spec.ts
+++ b/frontend/e2e/command-palette.spec.ts
@@ -270,3 +270,62 @@ test('Delete selection and Group into a new area are excluded from the palette (
 
   await page.keyboard.press('Escape')
 })
+
+// Faceted search (goal 0086, shared/facetQuery.ts): the `<label>: <text>`
+// grammar. "echo" is deliberately absent from any seeded command's own
+// label/id, so a leaked non-workflow match would be a real regression,
+// not a coincidental substring hit.
+test('typing "workflow: <text>" scopes results to workflows only', async ({ page }) => {
+  const label = 'ZzE2eFacetEchoWorkflow'
+  await page.goto('/')
+  await createSimpleWorkflow(page, label)
+
+  await page.keyboard.press('Meta+k')
+  await expect(paletteDialog(page)).toBeVisible()
+  await paletteDialog(page).getByRole('combobox').fill(`workflow: ${label}`)
+
+  await expect(paletteDialog(page).getByRole('option', { name: new RegExp(`Run: ${label}`) })).toBeVisible()
+  await expect(paletteDialog(page).getByRole('option', { name: 'Open Settings' })).toHaveCount(0)
+
+  await page.keyboard.press('Escape')
+
+  // Cleanup.
+  await page.getByRole('link', { name: 'Workflows' }).click()
+  await clickRowAction(page, workflowRow(page, label), 'Delete')
+  await expect(workflowRow(page, label)).toHaveCount(0)
+})
+
+test('typing "work" offers a Workflow suggestion chip; clicking it scopes the search, and backspacing the token unscopes it', async ({ page }) => {
+  const label = 'ZzE2eFacetChipTarget'
+  await page.goto('/')
+  await createSimpleWorkflow(page, label)
+
+  await page.keyboard.press('Meta+k')
+  await expect(paletteDialog(page)).toBeVisible()
+  const input = paletteDialog(page).getByRole('combobox')
+  await input.fill('work')
+
+  const chip = paletteDialog(page).getByTestId('facet-chip-row').getByRole('button', { name: 'Workflow', exact: true })
+  await expect(chip).toBeVisible()
+  await chip.click()
+
+  await expect(input).toHaveValue('Workflow: ')
+  await expect(paletteDialog(page).getByRole('option', { name: new RegExp(`Run: ${label}`) })).toBeVisible()
+  // The chip row is a completion aid only -- once a scope is active,
+  // there's nothing left to suggest.
+  await expect(paletteDialog(page).getByTestId('facet-chip-row')).toHaveCount(0)
+
+  // Ordinary backspace over the token is the removal path (no special
+  // key handling) -- clearing it back to empty returns the palette to
+  // its bare rest state.
+  for (let i = 0; i < 'Workflow: '.length; i++) await input.press('Backspace')
+  await expect(input).toHaveValue('')
+  await expect(paletteDialog(page).getByRole('option', { name: 'Open Settings' })).toBeVisible()
+
+  await page.keyboard.press('Escape')
+
+  // Cleanup.
+  await page.getByRole('link', { name: 'Workflows' }).click()
+  await clickRowAction(page, workflowRow(page, label), 'Delete')
+  await expect(workflowRow(page, label)).toHaveCount(0)
+})
diff --git a/frontend/src/app/CommandPalette.tsx b/frontend/src/app/CommandPalette.tsx
index 5216d8c7..471bd977 100644
--- a/frontend/src/app/CommandPalette.tsx
+++ b/frontend/src/app/CommandPalette.tsx
@@ -18,6 +18,9 @@ import type { PaletteSearchable } from './paletteFilter'
 import { sortWorkflowsByPinnedAndFrecency } from './workflowFrecency'
 import { HotkeyHint } from '../shared/HotkeyHint'
 import { WorkflowRowTrailingVisual } from './WorkflowRowTrailingVisual'
+import { matchFacetSuggestions, parseFacetQuery } from '../shared/facetQuery'
+import type { FacetVocabEntry } from '../shared/facetQuery'
+import { FacetChipRow } from '../shared/FacetChipRow'
 import styles from './CommandPalette.module.css'
 
 // The ⌘K command palette (docs/goals/0015-summon-quick-invoke.md): the
@@ -73,6 +76,31 @@ function groupMetadataFor(t: (key: string) => string) {
   ]
 }
 
+// Faceted search (goal 0086): vocabulary drawn straight from the
+// palette's own groups/types -- "command" covers both the 'commands'
+// and 'surface' groupIds (a surface-scoped command is still a
+// command, just ranked first), "setting" narrows further still, to
+// the per-section deep-link commands shared/settingsCommands.ts
+// registers (id `settings.open.<section>`) -- a strict subset of
+// "command". Quick Panel's own configure-entity-type facets don't
+// apply here: this surface has no Configure jump rows at all.
+function facetVocabularyFor(t: (key: string) => string): FacetVocabEntry[] {
+  return [
+    { key: 'command', label: t('commandPalette.facets.command') },
+    { key: 'workflow', label: t('commandPalette.facets.workflow') },
+    { key: 'tab', label: t('commandPalette.facets.tab') },
+    { key: 'setting', label: t('commandPalette.facets.setting') },
+  ]
+}
+
+function matchesPaletteFacet(scopeKey: string, entry: PaletteEntry): boolean {
+  if (scopeKey === 'command') return entry.groupId === 'commands' || entry.groupId === 'surface'
+  if (scopeKey === 'workflow') return entry.groupId === 'workflows'
+  if (scopeKey === 'tab') return entry.groupId === 'tabs'
+  if (scopeKey === 'setting') return entry.id === 'cmd:settings.open' || entry.id.startsWith('cmd:settings.open.')
+  return true
+}
+
 // Rest-state bound (design-wave-1 fix #2, Spotlight/Raycast/VS Code
 // convention: an empty query shows a short, useful default rather than
 // every command/workflow/tab at once). Nav commands are every
@@ -318,7 +346,29 @@ export function CommandPalette() {
     // eslint-disable-next-line react-hooks/exhaustive-deps -- commandEntry/workflowEntries/tabEntries close over workflows/nodeTypes/requests/workTabs/mostUsedRank/hotkeyCombos/pinnedWorkflowIds/togglePinnedWorkflow/t, already listed
   }, [restState, workflows, nodeTypes, requests, workTabs, mostUsedRank, hotkeyCombos, pinnedWorkflowIds, viewKind, t])
 
-  const filtered = restState ? allEntries : filterPaletteEntries(allEntries, query)
+  // Faceted search (goal 0086): the scope narrows allEntries FIRST,
+  // then filterPaletteEntries ranks the remainder against the
+  // post-token text -- an empty text (just "workflow: ") already lists
+  // every entry in that scope, since filterPaletteEntries returns its
+  // input unranked for a blank query.
+  const facetVocab = useMemo(() => facetVocabularyFor(t), [t])
+  const parsed = useMemo(() => parseFacetQuery(query, facetVocab), [query, facetVocab])
+  const chipSuggestions = useMemo(
+    () => (parsed.scopeKey || !query.trim() ? [] : matchFacetSuggestions(query, facetVocab)),
+    [parsed.scopeKey, query, facetVocab],
+  )
+  const scopedEntries = useMemo(
+    () => (parsed.scopeKey ? allEntries.filter((e) => matchesPaletteFacet(parsed.scopeKey!, e)) : allEntries),
+    [allEntries, parsed.scopeKey],
+  )
+  const filtered = restState ? allEntries : filterPaletteEntries(scopedEntries, parsed.text)
+
+  const selectChip = (key: string) => {
+    const entry = facetVocab.find((v) => v.key === key)
+    if (!entry) return
+    setQuery(`${entry.label}: `)
+    inputRef.current?.focus()
+  }
 
   const items = filtered.map((entry) => ({
     key: entry.id,
@@ -345,6 +395,11 @@ export function CommandPalette() {
       height="auto"
       initialFocusRef={inputRef}
     >
+      <FacetChipRow
+        items={chipSuggestions.map((entry) => ({ key: entry.key, label: entry.label }))}
+        onSelect={selectChip}
+        ariaLabel={t('commandPalette.facets.suggestionsAriaLabel')}
+      />
       <FilteredActionList
         className={styles.list}
         items={items}
diff --git a/frontend/src/app/QuickPanel.tsx b/frontend/src/app/QuickPanel.tsx
index a5506cf0..8bf30209 100644
--- a/frontend/src/app/QuickPanel.tsx
+++ b/frontend/src/app/QuickPanel.tsx
@@ -13,13 +13,14 @@ import {
 } from '../shared/configureEntityStore'
 import { useAtlasStore, refreshAtlasCards, refreshAtlasKinds, refreshAtlasNotes } from '../atlas/atlasStore'
 import { findRootNode } from '../composition/triggerRowInfo'
-import { filterPaletteEntries } from './paletteFilter'
 import { sortWorkflowsByPinnedAndFrecency } from './workflowFrecency'
 import { WorkflowRowTrailingVisual } from './WorkflowRowTrailingVisual'
 import { buildConfigureAndActionEntries } from './quickPanelActionEntries'
 import type { PanelEntry } from './quickPanelActionEntries'
 import { cascadeNotePosition, resolveNoteParentID } from './quickPanelCapture'
 import { QuickPanelClipboardApply } from './QuickPanelClipboardApply'
+import { FacetChipRow } from '../shared/FacetChipRow'
+import { useQuickPanelFacetSearch } from './quickPanelFacets'
 import styles from './QuickPanel.module.css'
 
 // docs/adr/0033-quick-panel-second-window.md: the search+run surface
@@ -410,7 +411,9 @@ export function QuickPanel() {
     decisions, execEnvs, aiProviders, declaredStepTypes, atlasCards, atlasKinds, reviewPendingCount,
   ])
 
-  const filtered = filterPaletteEntries(allEntries, query)
+  // Faceted search (goal 0086) -- quickPanelFacets.ts's own hook, same
+  // scope-then-rank shape app/CommandPalette.tsx runs inline.
+  const { filtered, chipSuggestions, selectChip } = useQuickPanelFacetSearch({ t, allEntries, query, setQuery, inputRef })
 
   // The save-note row (docs/goals/0090) never goes through
   // filterPaletteEntries -- it isn't a match against the typed text,
@@ -468,6 +471,11 @@ export function QuickPanel() {
 
   return (
     <div className={styles.panel} data-testid="quick-panel">
+      <FacetChipRow
+        items={chipSuggestions.map((entry) => ({ key: entry.key, label: entry.label }))}
+        onSelect={selectChip}
+        ariaLabel={t('quickPanel.facets.suggestionsAriaLabel')}
+      />
       <FilteredActionList
         items={items}
         groupMetadata={GROUP_METADATA}
diff --git a/frontend/src/app/quickPanelFacets.ts b/frontend/src/app/quickPanelFacets.ts
new file mode 100644
index 00000000..29faa91c
--- /dev/null
+++ b/frontend/src/app/quickPanelFacets.ts
@@ -0,0 +1,81 @@
+import { useMemo, type RefObject } from 'react'
+import { filterPaletteEntries } from './paletteFilter'
+import { matchFacetSuggestions, parseFacetQuery } from '../shared/facetQuery'
+import type { FacetVocabEntry } from '../shared/facetQuery'
+import type { PanelEntry } from './quickPanelActionEntries'
+
+// Split out of QuickPanel.tsx (architecture.md's 500-line convention),
+// same seam quickPanelActionEntries.tsx was split along: the panel's
+// own faceted-search vocabulary (goal 0086) is a pure derivation from
+// the entry shapes quickPanelActionEntries.tsx already builds, with no
+// hook state of its own.
+//
+// Vocabulary is "workflow" plus one keyword per Configure entity type
+// this panel actually renders as jump rows (quickPanelActionEntries.tsx's
+// own `configure:<tab>:<id>` id shape drives the match below). 'atlas'
+// and 'actions' stay unscoped on purpose -- Atlas cards already have
+// their own dedicated jump surface (atlas/AtlasJumpDialog.tsx), and
+// 'actions' is a handful of fixed rows with nothing worth narrowing.
+export function facetVocabularyFor(t: (key: string) => string): FacetVocabEntry[] {
+  return [
+    { key: 'workflow', label: t('quickPanel.facets.workflow') },
+    { key: 'integration', label: t('quickPanel.facets.integration') },
+    { key: 'list', label: t('quickPanel.facets.list') },
+    { key: 'mcpServer', label: t('quickPanel.facets.mcpServer') },
+    { key: 'decision', label: t('quickPanel.facets.decision') },
+    { key: 'execEnv', label: t('quickPanel.facets.execEnv') },
+    { key: 'aiProvider', label: t('quickPanel.facets.aiProvider') },
+    { key: 'stepType', label: t('quickPanel.facets.stepType') },
+  ]
+}
+
+const CONFIGURE_TAB_BY_FACET: Record<string, string> = {
+  integration: 'integration',
+  list: 'lists',
+  mcpServer: 'mcpservers',
+  decision: 'decisions',
+  execEnv: 'execenvs',
+  aiProvider: 'aiproviders',
+  stepType: 'steptypes',
+}
+
+function matchesPanelFacet(scopeKey: string, entry: PanelEntry): boolean {
+  if (scopeKey === 'workflow') return entry.groupId === 'workflows'
+  const tab = CONFIGURE_TAB_BY_FACET[scopeKey]
+  return tab ? entry.id.startsWith(`configure:${tab}:`) : true
+}
+
+// The scope-then-rank pipeline QuickPanel.tsx's own filtered-entries
+// step delegates to (same shape app/CommandPalette.tsx runs inline) --
+// pulled into a hook so QuickPanel.tsx's render body stays a single
+// call instead of five separate useMemos (architecture.md's 500-line
+// convention).
+export function useQuickPanelFacetSearch(params: {
+  t: (key: string) => string
+  allEntries: PanelEntry[]
+  query: string
+  setQuery: (query: string) => void
+  inputRef: RefObject<HTMLInputElement | null>
+}): { filtered: PanelEntry[]; chipSuggestions: FacetVocabEntry[]; selectChip: (key: string) => void } {
+  const { t, allEntries, query, setQuery, inputRef } = params
+  const facetVocab = useMemo(() => facetVocabularyFor(t), [t])
+  const parsed = useMemo(() => parseFacetQuery(query, facetVocab), [query, facetVocab])
+  const chipSuggestions = useMemo(
+    () => (parsed.scopeKey || !query.trim() ? [] : matchFacetSuggestions(query, facetVocab)),
+    [parsed.scopeKey, query, facetVocab],
+  )
+  const scopedEntries = useMemo(
+    () => (parsed.scopeKey ? allEntries.filter((e) => matchesPanelFacet(parsed.scopeKey!, e)) : allEntries),
+    [allEntries, parsed.scopeKey],
+  )
+  const filtered = filterPaletteEntries(scopedEntries, parsed.text)
+
+  const selectChip = (key: string) => {
+    const entry = facetVocab.find((v) => v.key === key)
+    if (!entry) return
+    setQuery(`${entry.label}: `)
+    inputRef.current?.focus()
+  }
+
+  return { filtered, chipSuggestions, selectChip }
+}
diff --git a/frontend/src/atlas/AtlasJumpDialog.tsx b/frontend/src/atlas/AtlasJumpDialog.tsx
index 93042e34..0a9677e2 100644
--- a/frontend/src/atlas/AtlasJumpDialog.tsx
+++ b/frontend/src/atlas/AtlasJumpDialog.tsx
@@ -3,7 +3,10 @@ import { useTranslation } from 'react-i18next'
 import { ActionList, Dialog, TextInput } from '@primer/react'
 import type { Card, Kind } from '../../bindings/github.com/alicoding/mill/internal/domain/atlas/models'
 import { kindColorTokens } from './atlasKindColor'
-import { filterJumpCards } from './atlasJumpFilter'
+import { AREA_FACET_KEY, filterJumpCards } from './atlasJumpFilter'
+import { matchFacetSuggestions, parseFacetQuery } from '../shared/facetQuery'
+import type { FacetVocabEntry } from '../shared/facetQuery'
+import { FacetChipRow } from '../shared/FacetChipRow'
 import monoStyles from '../shared/monoText.module.css'
 import styles from './AtlasJumpDialog.module.css'
 
@@ -39,7 +42,28 @@ export function AtlasJumpDialog({ open, onClose, cards, kinds, onJump }: {
     setActiveIndex(0)
   }, [open])
 
-  const results = useMemo(() => filterJumpCards(cards, kinds, query), [cards, kinds, query])
+  // Faceted search (goal 0086): vocabulary is every Kind's own Label
+  // plus the "area" role (group cards, orthogonal to Kind -- ADR-0038
+  // Decision 3). parseFacetQuery/matchFacetSuggestions are the same
+  // shared grammar the command palette and Quick Panel use.
+  const vocabulary = useMemo<FacetVocabEntry[]>(
+    () => [...kinds.map((k) => ({ key: k.ID, label: k.Label })), { key: AREA_FACET_KEY, label: t('jump.areaFacetLabel') }],
+    [kinds, t],
+  )
+  const parsed = useMemo(() => parseFacetQuery(query, vocabulary), [query, vocabulary])
+  const results = useMemo(() => filterJumpCards(cards, kinds, parsed.text, parsed.scopeKey), [cards, kinds, parsed])
+  const chipSuggestions = useMemo(
+    () => (parsed.scopeKey || !query.trim() ? [] : matchFacetSuggestions(query, vocabulary)),
+    [parsed.scopeKey, query, vocabulary],
+  )
+
+  const selectChip = (key: string) => {
+    const entry = vocabulary.find((v) => v.key === key)
+    if (!entry) return
+    setQuery(`${entry.label}: `)
+    setActiveIndex(0)
+    inputRef.current?.focus()
+  }
 
   const go = (card: Card) => {
     onClose()
@@ -86,6 +110,15 @@ export function AtlasJumpDialog({ open, onClose, cards, kinds, onJump }: {
         onKeyDown={onInputKeyDown}
         data-testid="atlas-jump-input"
       />
+      <FacetChipRow
+        items={chipSuggestions.map((entry) => ({
+          key: entry.key,
+          label: entry.label,
+          dotColorToken: entry.key === AREA_FACET_KEY ? undefined : kindColorTokens(entry.key).emphasis,
+        }))}
+        onSelect={selectChip}
+        ariaLabel={t('jump.suggestionsAriaLabel')}
+      />
       <ActionList selectionVariant="single" data-testid="atlas-jump-results">
         {results.map((r, i) => {
           const tokens = kindColorTokens(r.card.KindID)
diff --git a/frontend/src/atlas/atlasJumpFilter.test.ts b/frontend/src/atlas/atlasJumpFilter.test.ts
index af6ff999..348c44f6 100644
--- a/frontend/src/atlas/atlasJumpFilter.test.ts
+++ b/frontend/src/atlas/atlasJumpFilter.test.ts
@@ -1,9 +1,9 @@
 import { describe, expect, it } from 'vitest'
 import type { Card, Kind } from '../../bindings/github.com/alicoding/mill/internal/domain/atlas/models'
-import { ancestorPathLabel, filterJumpCards } from './atlasJumpFilter'
+import { AREA_FACET_KEY, ancestorPathLabel, filterJumpCards } from './atlasJumpFilter'
 
-function card(id: string, title: string, parentID: string, note = ''): Card {
-  return { ID: id, KindID: 'k1', Title: title, Note: note, ParentID: parentID } as Card
+function card(id: string, title: string, parentID: string, note = '', kindID = 'k1'): Card {
+  return { ID: id, KindID: kindID, Title: title, Note: note, ParentID: parentID } as Card
 }
 
 function kind(id: string): Kind {
@@ -53,6 +53,53 @@ describe('filterJumpCards', () => {
     const results = filterJumpCards(cards, [kind('k1')], 'alpha')
     expect(results[0].kind?.ID).toBe('k1')
   })
+
+  it('scopes to a single Kind, excluding cards of other kinds even when the text matches', () => {
+    const cards = [
+      card('a', 'Topic Alpha', '', '', 'topic'),
+      card('b', 'Document Alpha', '', '', 'document'),
+    ]
+    const results = filterJumpCards(cards, [], 'alpha', 'topic')
+    expect(results.map((r) => r.card.ID)).toEqual(['a'])
+  })
+
+  it('scoped + empty text lists every card of that Kind, title-ascending, capped at 8', () => {
+    const cards = [
+      ...Array.from({ length: 10 }, (_, i) => card(`t${i}`, `Topic ${i}`, '', '', 'topic')),
+      card('doc', 'Document one', '', '', 'document'),
+    ]
+    const results = filterJumpCards(cards, [], '', 'topic')
+    expect(results).toHaveLength(8)
+    expect(results.every((r) => r.card.KindID === 'topic')).toBe(true)
+    expect(results.map((r) => r.card.Title)).toEqual([...results.map((r) => r.card.Title)].sort())
+  })
+
+  it('scopes to areas (group cards) via AREA_FACET_KEY, excluding leaf cards', () => {
+    // "Root" itself has a child (Example area), so it's a group card
+    // too -- isGroupCard is purely structural (does a card have
+    // children), independent of any parent/child depth.
+    const root = card('root', 'Root', '')
+    const area = card('area', 'Example area', 'root')
+    const leaf = card('leaf', 'A leaf', 'area')
+    const cards = [root, area, leaf]
+    const results = filterJumpCards(cards, [], '', AREA_FACET_KEY)
+    expect(results.map((r) => r.card.ID)).toEqual(['area', 'root'])
+  })
+
+  it('scoped area + text still substring-matches within the area candidates', () => {
+    const root = card('root', 'Root', '')
+    const area1 = card('area1', 'Example area', 'root')
+    const area2 = card('area2', 'Another zone', 'root')
+    const leaf = card('leaf', 'Example leaf', 'area1')
+    const cards = [root, area1, area2, leaf]
+    const results = filterJumpCards(cards, [], 'example', AREA_FACET_KEY)
+    expect(results.map((r) => r.card.ID)).toEqual(['area1'])
+  })
+
+  it('an unscoped empty query still returns no results (unchanged from before faceting)', () => {
+    const cards = [card('a', 'Alpha', '')]
+    expect(filterJumpCards(cards, [], '')).toEqual([])
+  })
 })
 
 describe('ancestorPathLabel', () => {
diff --git a/frontend/src/atlas/atlasJumpFilter.ts b/frontend/src/atlas/atlasJumpFilter.ts
index b2451536..422e01bb 100644
--- a/frontend/src/atlas/atlasJumpFilter.ts
+++ b/frontend/src/atlas/atlasJumpFilter.ts
@@ -1,5 +1,6 @@
 import type { Card, Kind } from '../../bindings/github.com/alicoding/mill/internal/domain/atlas/models'
 import { buildBreadcrumbPath, singleRootCard } from './atlasGrouping'
+import { isGroupCard } from './atlasBoardLayout'
 
 // The ⌘K jump dialog's pure filter/rank (goal 0072 slice B) -- kept
 // dependency-free like atlasGrouping.ts's own helpers so it's
@@ -8,6 +9,12 @@ import { buildBreadcrumbPath, singleRootCard } from './atlasGrouping'
 
 const MAX_RESULTS = 8
 
+// The jump dialog's "area" facet scope (goal 0086) -- a role, not a
+// Kind, so it needs a sentinel distinct from any real Kind ID (Kind
+// IDs are user-declared, ADR-0038 Decision 2, so this stays a
+// two-underscore form no real slug is likely to collide with).
+export const AREA_FACET_KEY = '__area__'
+
 export interface AtlasJumpResult {
   card: Card
   kind: Kind | undefined
@@ -38,15 +45,31 @@ function stableSortResults(results: AtlasJumpResult[]): AtlasJumpResult[] {
 
 // filterJumpCards: case-insensitive substring match, title first (rank
 // 0) then note (rank 1), title-ascending within a rank, capped at the
-// dialog's own max visible rows. An empty query returns no results --
-// the dialog has nothing useful to show until the user types.
-export function filterJumpCards(cards: Card[], kinds: Kind[], query: string): AtlasJumpResult[] {
+// dialog's own max visible rows. An empty, unscoped query returns no
+// results -- the dialog has nothing useful to show until the user
+// types or picks a facet. `scopeKey` narrows the candidate set FIRST
+// (goal 0086's faceted search: a Kind's ID, or AREA_FACET_KEY for
+// group-card "areas") -- once scoped, an empty query still lists every
+// candidate of that scope (title-ascending), since the facet itself is
+// already a specific enough ask.
+export function filterJumpCards(cards: Card[], kinds: Kind[], query: string, scopeKey?: string): AtlasJumpResult[] {
   const q = query.trim().toLowerCase()
-  if (!q) return []
+  if (!q && !scopeKey) return []
+
   const kindByID = new Map(kinds.map((k) => [k.ID, k]))
+  const candidates = scopeKey === AREA_FACET_KEY
+    ? cards.filter((c) => isGroupCard(cards, c))
+    : scopeKey
+      ? cards.filter((c) => c.KindID === scopeKey)
+      : cards
+
+  if (!q) {
+    const wrapped = candidates.map((card) => ({ card, kind: kindByID.get(card.KindID), path: ancestorPathLabel(cards, card) }))
+    return stableSortResults(wrapped).slice(0, MAX_RESULTS)
+  }
 
   const byRank: AtlasJumpResult[][] = [[], []]
-  for (const card of cards) {
+  for (const card of candidates) {
     const rank = card.Title.toLowerCase().includes(q) ? 0 : (card.Note ?? '').toLowerCase().includes(q) ? 1 : null
     if (rank === null) continue
     byRank[rank].push({ card, kind: kindByID.get(card.KindID), path: ancestorPathLabel(cards, card) })
diff --git a/frontend/src/locales/en/app.json b/frontend/src/locales/en/app.json
index 46990d60..93c6c8a4 100644
--- a/frontend/src/locales/en/app.json
+++ b/frontend/src/locales/en/app.json
@@ -22,6 +22,17 @@
       "atlas": "Atlas",
       "actions": "Mill"
     },
+    "facets": {
+      "workflow": "Workflow",
+      "integration": "Integration",
+      "list": "List",
+      "mcpServer": "MCP server",
+      "decision": "Decision",
+      "execEnv": "Execution environment",
+      "aiProvider": "AI provider",
+      "stepType": "Step type",
+      "suggestionsAriaLabel": "Search type suggestions"
+    },
     "entries": {
       "enterToRun": "Enter to run",
       "jumpToIntegration": "Jump to Integration",
@@ -111,6 +122,13 @@
       "tabs": "Open tabs",
       "surface": "On this page"
     },
+    "facets": {
+      "command": "Command",
+      "workflow": "Workflow",
+      "tab": "Tab",
+      "setting": "Setting",
+      "suggestionsAriaLabel": "Search type suggestions"
+    },
     "testRun": "Test run",
     "runLabel": "Run: {{label}}",
     "openInEditor": "Open in editor",
diff --git a/frontend/src/locales/en/atlas.json b/frontend/src/locales/en/atlas.json
index 45a6990c..330d8cbd 100644
--- a/frontend/src/locales/en/atlas.json
+++ b/frontend/src/locales/en/atlas.json
@@ -45,7 +45,9 @@
   "jump": {
     "placeholder": "Jump to a card",
     "noMatches": "No cards match",
-    "footerHint": "↵ go · ⌘↵ open"
+    "footerHint": "↵ go · ⌘↵ open",
+    "areaFacetLabel": "Area",
+    "suggestionsAriaLabel": "Search type suggestions"
   },
   "lens": {
     "openButton": "Lens",
diff --git a/frontend/src/shared/FacetChipRow.module.css b/frontend/src/shared/FacetChipRow.module.css
new file mode 100644
index 00000000..c302c334
--- /dev/null
+++ b/frontend/src/shared/FacetChipRow.module.css
@@ -0,0 +1,42 @@
+/* Faceted-search suggestion chips (goal 0086) -- a token-chip look
+   consistent with shared/KeyComboChip.module.css's own idiom (Primer
+   tokens, bordered pill), but interactive: hover/focus states since
+   these are real completion buttons, not static hints. */
+.row {
+  display: flex;
+  flex-wrap: wrap;
+  gap: var(--base-size-4, 4px);
+  padding: var(--base-size-8, 8px) var(--base-size-8, 8px) 0;
+}
+
+.chip {
+  display: inline-flex;
+  align-items: center;
+  gap: var(--base-size-4, 4px);
+  height: 24px;
+  padding: 0 var(--base-size-8, 8px);
+  border: 1px solid var(--borderColor-default);
+  border-radius: var(--borderRadius-full, 999px);
+  background: var(--bgColor-muted);
+  color: var(--fgColor-default);
+  font-size: var(--text-body-size-small);
+  font-family: inherit;
+  cursor: pointer;
+}
+
+.chip:hover {
+  background: var(--bgColor-neutral-muted);
+  border-color: var(--borderColor-emphasis);
+}
+
+.chip:focus-visible {
+  outline: 2px solid var(--fgColor-accent);
+  outline-offset: 1px;
+}
+
+.dot {
+  width: 8px;
+  height: 8px;
+  border-radius: 50%;
+  flex-shrink: 0;
+}
diff --git a/frontend/src/shared/FacetChipRow.tsx b/frontend/src/shared/FacetChipRow.tsx
new file mode 100644
index 00000000..a7cdd1b7
--- /dev/null
+++ b/frontend/src/shared/FacetChipRow.tsx
@@ -0,0 +1,46 @@
+import styles from './FacetChipRow.module.css'
+
+// The faceted-search suggestion row (goal 0086): completion buttons
+// only -- clicking one completes "<label>: " into the search input,
+// nothing else. No Tab handling and no other chip state exist; typing
+// the token is the primary path (shared/facetQuery.ts's grammar), this
+// row is strictly the click-to-complete shortcut. Native <button>
+// elements so keyboard Tab-focus and Enter/Space activation come for
+// free, with the visible label doubling as the accessible name.
+
+export interface FacetChipItem {
+  key: string
+  label: string
+  // A CSS custom property name (e.g. '--bgColor-accent-emphasis') for
+  // a leading color dot -- the same kind-glyph idiom
+  // atlas/AtlasJumpDialog.tsx's own result rows and atlas/KindPicker.tsx
+  // already use. Omitted renders a plain, uncolored chip (the palette/
+  // Quick Panel look).
+  dotColorToken?: string
+}
+
+export function FacetChipRow({ items, onSelect, ariaLabel }: {
+  items: FacetChipItem[]
+  onSelect: (key: string) => void
+  ariaLabel: string
+}) {
+  if (items.length === 0) return null
+  return (
+    <div className={styles.row} role="group" aria-label={ariaLabel} data-testid="facet-chip-row">
+      {items.map((item) => (
+        <button
+          key={item.key}
+          type="button"
+          className={styles.chip}
+          onClick={() => onSelect(item.key)}
+          data-testid="facet-chip"
+        >
+          {item.dotColorToken && (
+            <span className={styles.dot} style={{ background: `var(${item.dotColorToken})` }} aria-hidden="true" data-testid="facet-chip-dot" />
+          )}
+          {item.label}
+        </button>
+      ))}
+    </div>
+  )
+}
diff --git a/frontend/src/shared/facetQuery.test.ts b/frontend/src/shared/facetQuery.test.ts
new file mode 100644
index 00000000..f63aef36
--- /dev/null
+++ b/frontend/src/shared/facetQuery.test.ts
@@ -0,0 +1,93 @@
+import { describe, expect, it } from 'vitest'
+import { matchFacetSuggestions, parseFacetQuery } from './facetQuery'
+import type { FacetVocabEntry } from './facetQuery'
+
+const VOCAB: FacetVocabEntry[] = [
+  { key: 'workflow', label: 'Workflow' },
+  { key: 'mcpServer', label: 'MCP server' },
+  { key: 'setting', label: 'Setting', aliases: ['settings'] },
+]
+
+describe('parseFacetQuery', () => {
+  it('returns no scope and the whole query when there is no colon', () => {
+    expect(parseFacetQuery('echo', VOCAB)).toEqual({ text: 'echo' })
+  })
+
+  it('scopes on an exact, case-insensitive label match', () => {
+    expect(parseFacetQuery('workflow: echo', VOCAB)).toEqual({ scopeKey: 'workflow', text: 'echo' })
+    expect(parseFacetQuery('WORKFLOW: echo', VOCAB)).toEqual({ scopeKey: 'workflow', text: 'echo' })
+    expect(parseFacetQuery('WorkFlow: echo', VOCAB)).toEqual({ scopeKey: 'workflow', text: 'echo' })
+  })
+
+  it('matches a multi-word label only when typed in full', () => {
+    expect(parseFacetQuery('mcp server: prod', VOCAB)).toEqual({ scopeKey: 'mcpServer', text: 'prod' })
+    // "mcp" alone is not the whole label -- falls through to unscoped.
+    expect(parseFacetQuery('mcp: prod', VOCAB)).toEqual({ text: 'mcp: prod' })
+  })
+
+  it('matches an alias the same as the primary label', () => {
+    expect(parseFacetQuery('settings: theme', VOCAB)).toEqual({ scopeKey: 'setting', text: 'theme' })
+  })
+
+  it('trims leading whitespace off the text but preserves internal spacing', () => {
+    expect(parseFacetQuery('workflow:    echo   test', VOCAB)).toEqual({ scopeKey: 'workflow', text: 'echo   test' })
+  })
+
+  it('treats empty text after the token as valid (list-all)', () => {
+    expect(parseFacetQuery('workflow: ', VOCAB)).toEqual({ scopeKey: 'workflow', text: '' })
+    expect(parseFacetQuery('workflow:', VOCAB)).toEqual({ scopeKey: 'workflow', text: '' })
+  })
+
+  it('leaves a query with a non-matching prefix before the colon fully unscoped', () => {
+    expect(parseFacetQuery('look at ada: page 5', VOCAB)).toEqual({ text: 'look at ada: page 5' })
+  })
+
+  it('only ever considers the FIRST colon -- a later one stays inside text once scoped', () => {
+    expect(parseFacetQuery('workflow: sync at 10:30', VOCAB)).toEqual({ scopeKey: 'workflow', text: 'sync at 10:30' })
+  })
+
+  it('returns unscoped for an empty or whitespace-only query', () => {
+    expect(parseFacetQuery('', VOCAB)).toEqual({ text: '' })
+    expect(parseFacetQuery('   ', VOCAB)).toEqual({ text: '   ' })
+  })
+
+  it('does not scope on a bare colon with no label text before it', () => {
+    expect(parseFacetQuery(': echo', VOCAB)).toEqual({ text: ': echo' })
+  })
+
+  it('returns unscoped when the vocabulary is empty', () => {
+    expect(parseFacetQuery('workflow: echo', [])).toEqual({ text: 'workflow: echo' })
+  })
+})
+
+describe('matchFacetSuggestions', () => {
+  it('returns vocabulary entries whose label prefix-matches the first typed word', () => {
+    expect(matchFacetSuggestions('work', VOCAB).map((v) => v.key)).toEqual(['workflow'])
+  })
+
+  it('matches case-insensitively', () => {
+    expect(matchFacetSuggestions('WORK', VOCAB).map((v) => v.key)).toEqual(['workflow'])
+  })
+
+  it('matches a multi-word label off its first word alone', () => {
+    expect(matchFacetSuggestions('mcp', VOCAB).map((v) => v.key)).toEqual(['mcpServer'])
+  })
+
+  it('keeps matching once the query has moved past the first word', () => {
+    expect(matchFacetSuggestions('work in progress', VOCAB).map((v) => v.key)).toEqual(['workflow'])
+  })
+
+  it('returns nothing for an empty query', () => {
+    expect(matchFacetSuggestions('', VOCAB)).toEqual([])
+  })
+
+  it('returns nothing when no label prefix-matches', () => {
+    expect(matchFacetSuggestions('zzz', VOCAB)).toEqual([])
+  })
+
+  it('caps results at max (default 5)', () => {
+    const bigVocab: FacetVocabEntry[] = Array.from({ length: 8 }, (_, i) => ({ key: `k${i}`, label: `Kind${i}` }))
+    expect(matchFacetSuggestions('kind', bigVocab)).toHaveLength(5)
+    expect(matchFacetSuggestions('kind', bigVocab, 3)).toHaveLength(3)
+  })
+})
diff --git a/frontend/src/shared/facetQuery.ts b/frontend/src/shared/facetQuery.ts
new file mode 100644
index 00000000..871b9e8c
--- /dev/null
+++ b/frontend/src/shared/facetQuery.ts
@@ -0,0 +1,63 @@
+// Faceted search grammar (goal 0086): a typed inline qualifier
+// `<label>: <text>` at a search query's start, shared by the command
+// palette, the Quick Panel, and the Atlas jump dialog so all three
+// scope the exact same way. Precedent survey (goal 0086's DoR) found
+// no surveyed launcher uses a click/Tab-to-accept facet in its primary
+// search -- the convergence is this typed qualifier, where typing IS
+// the acceptance and the token stays visible in the input as its own
+// scope indicator.
+
+export interface FacetVocabEntry {
+  // Opaque to this module -- the caller's own scope identifier (a
+  // group id, an entity-type key, an Atlas Kind ID, ...), returned
+  // unchanged in a match so the caller can filter its own entries by
+  // it.
+  key: string
+  // Displayed and matched exactly as given (matching is
+  // case-insensitive, but the label's own stored casing is what a
+  // suggestion chip renders).
+  label: string
+  aliases?: string[]
+}
+
+export interface FacetQuery {
+  scopeKey?: string
+  text: string
+}
+
+// parseFacetQuery: a whole vocabulary label (or alias) immediately
+// before the query's FIRST colon, matched case-insensitively,
+// activates that entry's scope and consumes the token -- everything
+// after the colon (leading whitespace trimmed) becomes `text`. A
+// colon anywhere else in the query (inside `text`, because the label
+// portion didn't match anything) is left alone: only the substring
+// before the first colon is ever checked against the vocabulary, so a
+// non-matching prefix falls through to "no scope, text = the whole
+// query" rather than misparsing. Multi-word labels ("mcp server")
+// match only when typed in full, never a partial word.
+export function parseFacetQuery(query: string, vocabulary: FacetVocabEntry[]): FacetQuery {
+  const colonIndex = query.indexOf(':')
+  if (colonIndex === -1) return { text: query }
+
+  const token = query.slice(0, colonIndex).trim().toLowerCase()
+  if (!token) return { text: query }
+
+  const match = vocabulary.find(
+    (entry) => entry.label.toLowerCase() === token || (entry.aliases ?? []).some((alias) => alias.toLowerCase() === token),
+  )
+  if (!match) return { text: query }
+
+  return { scopeKey: match.key, text: query.slice(colonIndex + 1).trimStart() }
+}
+
+// matchFacetSuggestions: the suggestion-chip row's own source list --
+// every vocabulary entry whose label starts with the query's first
+// word, capped at `max`. Only meaningful before a scope is active (the
+// caller checks that); once a query already has a matching label+colon
+// at its start, parseFacetQuery already resolved it and there's
+// nothing left to suggest.
+export function matchFacetSuggestions(query: string, vocabulary: FacetVocabEntry[], max = 5): FacetVocabEntry[] {
+  const firstWord = query.trimStart().split(/\s+/)[0]?.toLowerCase()
+  if (!firstWord) return []
+  return vocabulary.filter((entry) => entry.label.toLowerCase().startsWith(firstWord)).slice(0, max)
+}