# Search / Command Palette UI

**Status:** Approved target-state behavior  
**First realization:** I3  
**Interaction substrate:** `dip/cmdk` after compatibility/reuse verification

## Page / Surface Job

Let users find any relevant AWP object or safe command quickly without navigating hierarchy manually, while preserving a separate mental model from Advisor conversation.

Primary jobs:

```text
find and open a Project / Plan / Task / Run / Decision / Incident
jump to a major product destination
invoke a safe common command
find something by partial title or remembered text
continue to a full Search page when the result set is large
```

## Target State

```text
Shell
  Search…  ⌘K

Cmd/Ctrl+K
  -> command/search dialog
      recent
      commands
      grouped entity results
      View all results

Full Search
  /search?q=...&type=...&project=...
  -> filters / groups / pagination / shareable URL
```

`cmdk` supplies command-menu/combobox interaction. AWP supplies styling, result data, ranking, grouping, commands and authorization.

## Primary Users / Jobs

- project/product manager: jump directly to work/Decision/attention without remembering where it lives;
- engineering/operator user: locate Factory/Agent/CI/Incident quickly by title/status/ID;
- keyboard-oriented user: operate common navigation/commands without mouse traversal;
- occasional user: discover the same search through a visible shell affordance.

## Entry / Exit Points

Entry:

```text
Cmd+K macOS
Ctrl+K Linux/Windows
visible Search affordance in global shell
optional search icon/button in narrow shell
```

Exit:

```text
open selected primitive/page
execute safe navigation/command
open full Search results
Ask Project Manager / Ask AWP explicit command item
Escape/Close back to original page
```

The originating page remains unchanged if the palette closes without selection.

## Palette Layout

Empty query:

```text
Search AWP…

Recent
  Press.Zone
  Plan: Launch governance

Commands
  New Plan
  Needs Your Attention
  Ask AWP
  Settings

Go to
  Projects
  Agents
  CI
```

Typed query:

```text
translation

Projects
  International Press Zone

Plans
  Translation fidelity

Tasks
  PG-11 Page translation fidelity

Runs / Agents
  FactoryRun 5j13mlx

Decisions
  Translation parent policy

View all results for “translation”
```

Group headings/counts are semantic text, not visual decoration.

## Result Row

A result should expose the minimum context needed to distinguish it:

```text
entity type
human title/name
Project when not obvious
status/attention when useful
short matching snippet or relationship context
keyboard hint only when meaningful
```

Avoid raw UUID/provider IDs as primary labels. Stable short IDs may appear secondarily for technical objects.

## Current-Project Boost

When opened from a Project route, current-Project matches can rank higher and can have a visible `Current Project` group/filter, but global authorized results remain reachable.

Do not silently scope all search to current Project unless UI states that scope explicitly.

## Search vs Advisor

Search results never silently transform into an AI answer.

If useful, show an explicit secondary command:

```text
Ask Project Manager about “translation delays”
Ask AWP about “CI bottlenecks”
```

This item is visually grouped under `Ask`, distinct from exact entity matches.

## Full Search Page

When a result set is too large or user needs filters, `View all results` opens stable Search.

### Full Search IA

```text
Search header
  query
  result count / freshness

Filters
  entity type
  Project
  status
  needs attention
  time range
  domain-specific optional filters

Results
  grouped/listed entity rows
  sort
  pagination/cursor
```

Full Search uses URL truth so refresh/share reproduces query/filter/sort.

Large result collections use pagination/load-more/cursor behavior rather than rendering hundreds of rows.

## Commands

Command items come from the canonical application/control-surface registry.

Examples:

```text
Open Needs Your Attention
New Plan
Open active FactoryRun
Ask Project Manager
Ask AWP
Open Settings
```

Navigation is direct. Mutating/protected commands can open their canonical page/dialog/confirmation and must not skip policy/Approval/revision checks.

## Complete States

### Empty query

Recent + useful commands/destinations; no filler illustration.

### Typing / debounce

Input remains responsive; remote query waits for short debounce. Previous result geometry can remain while loading if it does not misrepresent current query.

### Loading

Use `Command.Loading`/AWP equivalent row/skeleton shaped like results. Static commands may remain available.

### Populated

Grouped results + one selected row + keyboard interaction.

### No results

Human copy:

```text
No results for “translaton”.
[Search all] [Clear filters]
```

Optionally show `Ask AWP about...` separately if Advisor is active; do not make it the only recovery.

### Partial failure

Example:

```text
Projects and Plans loaded.
CI history is temporarily unavailable. [Retry]
```

Do not blank successful groups.

### Offline / disconnected

Static navigation commands and recent cached destinations may remain. Clearly mark entity search unavailable/stale. Protected mutations remain live-state gated.

### Permission-filtered

No indication that hidden entities exist. Search simply returns authorized result set.

## User Journeys

### J1 — Find a Plan quickly

```text
Cmd+K
 -> type partial Plan title
 -> Plan group appears
 -> arrow/Enter
 -> Plan route opens
```

### J2 — Find technical execution object

```text
Search
 -> paste/enter FactoryRun short ID or task keyword
 -> result shows Project/Task/status
 -> open FactoryRun
```

### J3 — Deep filter

```text
Cmd+K “translation”
 -> View all results
 -> /search?q=translation
 -> filter type=Task, status=blocked
 -> open Task
 -> browser back restores full Search filters
```

### J4 — Keyboard command

```text
Cmd+K
 -> “attention”
 -> Open Needs Your Attention
 -> attention route
```

### J5 — Distinguish Search from Advisor

```text
Cmd+K “why is PG-11 slow”
 -> exact entity matches remain grouped normally
 -> separate Ask Project Manager item available
 -> selecting Ask opens Advisor with query + current Project context
```

## Data / Source of Truth

Search result identity/title/snippet comes from authorized Search providers over AWP read models. Opening a result loads the canonical primitive. Search result cache/index is not lifecycle authority.

## Authorization / Mutation Safety

Entity provider queries apply Principal/Project access before returning result metadata/snippets. Command registry can hide unavailable commands for clarity, but execution always rechecks backend capability/policy.

Search selection is navigation. Mutating commands use canonical idempotency/revision/confirmation behavior.

## Responsive Behavior

Desktop/medium: centered or top-biased command dialog sized to show useful grouped rows without full-screen takeover.

Small: near-full-width sheet/dialog with input fixed at top and scrollable results. Keyboard/mobile focus must remain stable.

Full Search page uses stacked filters/drawer on small screens; result context stays readable without horizontal table overflow.

## Accessibility

- visible Search control with shortcut text;
- `Cmd+K` / `Ctrl+K` global shortcut except when browser/editor context must retain it by deliberate policy;
- semantic combobox/list behavior through cmdk;
- arrows/Enter/Escape predictable;
- focus trapped while palette open and returned to opener;
- selected state not color-only;
- dynamic result count/loading uses `aria-live="polite"` or equivalent;
- 44x44 minimum touch target for visible launcher/rows where touch applies.

## URL Truth

Palette query need not alter current URL while transient. Full Search query/filter/sort/page/cursor state is URL-restorable.

Selecting a result uses the canonical stable route for that primitive.

## Async / Duplicate Safety

Remote input is debounced/throttled and older requests are cancelled/ignored when a newer query supersedes them. Selecting one command closes/locks against duplicate activation while navigation/action starts.

Mutating commands inherit their canonical mutex/idempotency behavior.

## Invariants From Day 1

- one global palette/search mental model;
- cmdk is interaction substrate, not backend data store;
- current Project may boost but not silently hide global scope;
- Search and Advisor are distinct;
- unauthorized titles/snippets never leak;
- full Search state is shareable/restorable;
- static commands remain usable during partial entity-search failure where safe;
- no dead Search affordance before product activation.

## Increment Realization

| Increment | UI realization |
|---|---|
| I1 | not shown. |
| I2 | internal query seams only if Planning uses them. |
| I3 | shell Search affordance, Cmd/Ctrl+K palette, full Search, Project/Vision/Plan/Task/Decision/Approval + active lifecycle result providers. |
| I4 | Factory/Agent rich/history results + Advisor commands. |
| I5–I8 | CI/Release/Cluster/Incident result types activate with domains. |
| I9 | organization/tenant filters/scoping if productized. |

## Current Implementation State

Target UI specification only.

## Deferred Realization

Semantic/vector search, natural-language query rewriting, saved searches and cross-tenant enterprise search are later evidence-driven enhancements.

## Temporary Dogfood Behavior

I1 does not ship a partial fake global search. Direct navigation/breadcrumbs are sufficient until I3 while stable entity IDs/routes remain final-form.

## Related Contracts / Decisions

- `../architecture/search-and-command-palette.md`
- `../architecture/control-surfaces.md`
- `advisory-chat.md`
- `INDEX.md`
- current Platform search reuse preflight
- supplied UX-designer guidance explicitly calls for a Cmd/Ctrl+K command palette and URL-restorable view modifiers.

## Visual Mockup Authority

No Search high-fi is approved yet. Before I3: empty/recent, typed grouped results, no-results, partial failure, full Search filtered state and small-screen variants require explicit approval.

## Acceptance

A user can open Search without knowing product hierarchy, find an exact authorized AWP object or common command quickly, continue to advanced filtered Search when necessary, and never confuse retrieval with Advisor reasoning.