# Agent Component Selection

This guide is the human-readable companion to `registry/agent-manifest.json`.
Agents should read the manifest first, then source files only when implementation
details are needed.

## Entry Points

- `sparkdesign/agent-manifest.json` — package export for agent-facing component semantics.
- `registry/agent-manifest.json` — source of truth in this repository.
- Showcase route `#/agent-component-selection` — visible companion page for the same decision model.
- `npm run check:agent-manifest` — validates required semantic fields and recipe references.
- `npm run report:agent-coverage` — reports manifest coverage against `registry/meta.json`.
- `npm run check:agent-coverage` — fails if manifest coverage drops below 100%.

## Decision Order

1. Choose by `intent`, not by component name similarity.
2. Check `antiPatterns` before composing a component into a generated screen.
3. Prefer `recipes` for common agent workflows before inventing a new layout.
4. Use `cliAdd` when the target app should own copied component source.
5. Use `packageImport` only when the app already consumes `sparkdesign` as a package.

## Common Name Boundaries

- `sidebar` is the full app-shell primitive set: provider state, trigger, responsive collapse, mobile sheet, and inset content. Package imports expose its menu list as `SidebarNavMenu` / `SidebarNavMenuItem`.
- `sidebar-menu` is the lightweight data-driven list component exported as `SidebarMenu`; use it when a full app shell would be overkill.
- `form` is for React Hook Form validation wiring; `field` is for layout-only form rows.

## Current High-Confidence Coverage

The manifest covers the components most likely to be selected by design/coding
agents. Use `npm run report:agent-coverage` for the current full coverage
snapshot.

- `button`
- `alert`
- `alert-dialog`
- `accordion`
- `aspect-ratio`
- `avatar`
- `badge`
- `breadcrumb`
- `button-group`
- `calendar`
- `card`
- `carousel`
- `chart`
- `checkbox`
- `collapse`
- `collapsible`
- `collapsible-card`
- `combobox`
- `command`
- `context-menu`
- `data-table`
- `date-picker`
- `dialog`
- `direction`
- `dropdown-menu`
- `drawer`
- `ellipsis-text`
- `empty`
- `field`
- `form`
- `hover-card`
- `icon-button`
- `input`
- `input-group`
- `input-otp`
- `item`
- `kbd`
- `label`
- `menubar`
- `native-select`
- `navigation-menu`
- `option-list`
- `pagination`
- `popover`
- `progress`
- `radio-group`
- `resizable`
- `scroll-area`
- `scrollbar`
- `select`
- `separator`
- `sidebar`
- `sidebar-menu`
- `shimmering-text`
- `slider`
- `skeleton`
- `spinner`
- `switch`
- `table`
- `tag`
- `tabs`
- `textarea`
- `toast`
- `tooltip`
- `toggle`
- `toggle-group`
- `typography`
- `ask-user-part` / `AgentQuestionCard`
- `browser-action-part`
- `chat-input`
- `code-block-part`
- `compression-divider` / `ContextCompressionDivider`
- `conversation-anchor-nav`
- `file-attachment`
- `file-card`
- `file-review-part`
- `folder-button`
- `generation-status-bar`
- `generated-images-grid`
- `hint-banner`
- `image-attachment`
- `image-generating` / `ImageGenerationPlaceholder`
- `markdown`
- `mermaid-part`
- `permission-card`
- `plan-part`
- `queue-indicator`
- `reasoning-step`
- `related-prompts` / `PromptSuggestions`
- `response` / `AssistantResponse`
- `send-button`
- `streaming-markdown-block`
- `task-part`
- `terminal-code-block-part`
- `thinking-indicator`
- `tool-invocation-card` / `ToolCallCard`
- `user-message`
- `user-question-answer`
- `user-question-part`

## Recipe Usage

Recipes are intended to prevent agents from flattening rich AI interfaces into
generic cards and Markdown.

- `structured-form` — deterministic forms/settings with labels, controls, validation, and actions.
- `assistant-composer` — prompt entry, attachments, send, and permissions.
- `assistant-response-stream` — generated answer, tools, Markdown, and errors.
- `focused-task-modal` — compact blocking task or confirmation flow.
- `settings-drawer` — contextual settings/details while preserving page context.
- `tool-approval-flow` — explicit approval before risky agent tool actions.
- `file-review-flow` — agent file changes, review decisions, and approval.
- `empty-state-with-prompts` — empty states that guide users into AI workflows.

## Maintenance Rule

When adding a component to the manifest:

1. Confirm the component exists in `registry/meta.json`.
2. Fill `intent`, `slots`, `states`, `a11y`, `composition`, `antiPatterns`, and `agentHints`.
3. Ensure `packageImport` uses names exported by `src/components/index.ts`.
4. Ensure `cliAdd` installs the same component id as the manifest key.
5. Add or update recipes if the component changes how agents should compose screens.
6. Run `npm run check:agent-manifest`.
7. Run `npm run check:agent-coverage` so new registry components cannot ship without agent semantics.
8. Run `npm run report:agent-coverage` when planning broader semantic coverage or reviewing drift.