# The Command Palette

The Command Palette is the human-facing surface to the same action registry that powers § 1 (the AI Assistant) and § 3 (the MCP server). Press `Ctrl+K` (Cmd+K on macOS), type what you want, hit Enter.

```yaml
actions:
  - action_id: palette.overlay.toggle
    input: { open: true }
    label: "▶ Open the Command Palette (Escape to close)"
```

## Opening + dismissing

| Gesture | Effect |
|---|---|
| **Ctrl/Cmd+K** | Open the palette |
| Click the **Search icon** in the topbar right cluster | Open the palette |
| **Escape** | Dismiss |
| Click outside the palette | Dismiss |

The palette overlays the workspace; focus shifts to the input field.

## Fuzzy search

Type any substring of an action's **title**, **description**, or **category**. Matches rank by relevance — exact-prefix on title beats mid-string in description.

Examples:

| Type | Surfaces |
|---|---|
| `dark` | Theme: Dark + any other action with "dark" in the title |
| `bpm` | Master: Set BPM + Transport: Set BPM |
| `play` | Transport: Play + DSP: Run + Sequencer: Play + Recorder: Start + DSP: Run |
| `recorder` | Every `recorder.*` action |
| `mcp` | The `palette.run` / `palette.list` / `palette.describe` meta-actions |

Empty search shows recent + pinned actions (if any) followed by alphabetical.

## What's in the palette

Only actions that declare a `run` handler (the UI-callable path). MCP-only actions (`mcpRun` without `run`) don't show up — they're intentionally not user-driveable from the palette (the human surface is the related UI; the AI surface is MCP).

In practice that's:

- All theme-set actions (`Theme: Dark` / `Light` / `Cyberpunk` / `System`).
- Transport (`Transport: Play` / `Stop`).
- Master + Mixer (`Master: Set Volume`, `Mixer: Set`, etc.).
- All DSP-Builder, Sequencer, Recorder dual-path actions.
- Module management (`Modules: Add` / `Close` / etc.).
- Hub actions (`Hub: Open`, `Auth: Login`, ...).

Roughly ~80 actions of the ~130 registered.

## Action previews

Some actions render a small preview swatch in the palette row — currently the theme picker shows a gradient swatch matching the theme it sets:

| Action | Preview |
|---|---|
| `Theme: Dark` | Dark gradient swatch |
| `Theme: Light` | Light gradient swatch |
| `Theme: Cyberpunk` | Magenta → purple → cyan gradient |
| `Theme: System` | Split light / dark gradient |

The preview surface is extensible — extensions can declare a custom preview renderer per action.

## Keyboard navigation

Inside the palette:

| Key | Effect |
|---|---|
| `↓` / `↑` | Move selection through filtered results |
| `Enter` | Run the selected action |
| `Escape` | Dismiss (no action) |
| `Tab` | Cycle through *recent* and *all* filters (planned) |

Mouse: hover highlights, click runs.

## Activity capture

Every palette invocation lands in the **Activity** rail panel just like an MCP call or a UI click. Surface is tagged `palette`. Replay-able, audit-able — the same trace surface the assistant + external MCP clients land in.

## Why a palette exists alongside menus + shortcuts + the AI

Three reasons:

1. **Discoverability** — keyboard shortcuts are fast once you know them, but you have to learn them first. The palette fuzzy-searches the entire surface; type what you want, get there.
2. **AI parity** — every palette entry is also a registry action. If you can do it in the palette, the AI can do it too. The palette doubles as documentation of what's possible.
3. **Friction-free access** — no menu hunting, no chrome to read, no spatial scanning. Two keystrokes + a search term + Enter.

For the AI side of this same registry, see § 1 and § 3.

## Where to go from here

- **§ 1 (The AI Assistant)** — the same registry, called by the model.
- **§ 3 (MCP)** — the same registry, called from outside the IDE.
- **FaustWave — Reference** § *Keyboard shortcuts* — the persistent-shortcut surface for the most-used actions.