# Working with agent-ui

`agent-ui` is a source-first library of agentic UI primitives in plain HTML, CSS, and JavaScript. The primary user is an AI coding agent that needs to produce a credible, inspectable interface quickly.

## Start here

Read [`docs/catalog.json`](docs/catalog.json) before choosing a component. It is the generated machine-readable catalog and lists the component contract, states, dependencies, fixtures, raw source paths, and docs page for every MVP component.

Then read the smallest relevant recipe:

- complete first screen: [`docs/starters/chat-tools.html`](docs/starters/chat-tools.html)
- canonical host composition: [`showcase/chat-run.html`](showcase/chat-run.html)
- streaming conversation: [`docs/patterns/chat-streaming.html`](docs/patterns/chat-streaming.html)
- tool approval: [`docs/patterns/tool-approval.html`](docs/patterns/tool-approval.html)
- question and resume: [`docs/patterns/question-resume.html`](docs/patterns/question-resume.html)

Use each recipe's `stylesheets[]` from the catalog (or its Install tab). Copy `host-chrome.css` when the recipe lists it. Exclude `setup.docs_only_assets` (docs shell and showcase workbench). Optional: `recipes/chat-tools.css` or `node scripts/copy-recipe.js chat-tools <dir>`.

Human docs: [`docs/guides/ai-setup.html`](docs/guides/ai-setup.html). Agent index: [`llms.txt`](llms.txt). Positioning: [`docs/guides/html-agent-ui.html`](docs/guides/html-agent-ui.html).

## Copyable setup prompt

> Build this agentic interface with `agent-ui` source files. First read `docs/catalog.json` and choose the smallest matching recipe or component. Copy `tokens.css`, the recipe `stylesheets[]` (including `host-chrome.css` when listed), and only the required component markup. Use semantic HTML, native forms, the shared `data-au-*` vocabulary, and the documented `data-au-state` values. Keep the host responsible for execution, authorization, persistence, validation, and state transitions. Treat model output, tool arguments, and tool output as untrusted text and escape it before insertion. Keep the no-JS path usable. Do not add React, Tailwind, a bundler, external assets, fonts, analytics, or runtime network requests. Exclude `setup.docs_only_assets`. After implementation, run `node scripts/check-all.js` and, when a browser is available, `node scripts/check-browser.js`.

## Selection rules

1. Use the starter when the goal is a complete chat-with-tools screen.
2. Use `chat-thread` for the conversation container, `chat-message` for turns, and `chat-input` for the native composer.
3. Use `thinking-indicator` for brief waiting, `thinking-steps` for visible work (optional `__detail` for streaming text), and `tool-call` for an invocation and its exact output.
4. Use `approval-gate` when a consequential action needs a human decision. Bind the decision to an immutable action ID and exact serialized arguments. Prefer an optional `__rationale` (“why this is safe”) over decorative urgency.
5. Use `ask-user-question` when the agent needs a bounded answer before resuming work.
6. Compose primitives instead of inventing a larger component or adding undocumented state names.
7. Orbit-style rich objects (synthesis, verdict, status pills, attachments, diffs, domain refund cards) are compositions or deferred v1 rows — not new MVP inventory.

## HITL language

Prefer:

- Paused for review
- Review required before continuing
- Customer stall: “One moment — I’m still working on your issue.”

Avoid (MVP):

- Escalated to human
- Transferred to human
- Over-explaining HITL mechanics to the customer

## Non-negotiable contracts

- Source copy is canonical; hosted docs and CDN links are convenience layers.
- Components render host-provided state; they never execute tools or imply approval.
- Use `data-au-component`, `data-au-action`, `data-au-target`, `data-au-value`, and `data-au-state` as documented.
- Keep untrusted output escaped. Core components do not parse Markdown, ANSI, or arbitrary HTML.
- Preserve keyboard access, visible focus, dark mode, reduced motion, and the 390px mobile path.
- Keep styles local to explicit component parts. Consume semantic `--au-*` tokens rather than reaching into primitive palette values.

## Verification

From the repository root:

```bash
node scripts/check-all.js
node scripts/check-public.js
node scripts/check-jobs-matrix.js
node scripts/check-quality.js
node scripts/check-browser.js
```

A change is not complete if the generated catalog or generated agentic docs are stale. Run `node scripts/build-catalog.js` and `node scripts/build-agentic-docs.js` after changing their metadata sources, then rerun the checks.