# Install from the registry

Each item is a JSON file at `https://agentsandhumans.ai/api/registry/<name>.json`. `shadcn add` writes the files into the app; there is no runtime package.

| Item | What it adds |
|---|---|
| `interaction-contract` | `lib/interaction-contract.ts`: the event model and the shared records. Each component depends on it. |
| `plan-preview`, `approval-gate`, `progress-trace` | One component each: `<name>-core.tsx` (logic, no styles), `<name>.tsx` (the styled skin), `tokens.css`. |
| `agent-workflow` | The three above plus `review-receipt-core.tsx`, `agent-workflow.tsx`, `lib/agent-workflow-host.ts`, the example page and its server route. |

Other components on the same registry: `emergency-stop`, `interruption`, `recovery`, `eval-comparison`, `eval-set-authoring`. The list at `https://agentsandhumans.ai/patterns/get-started/install` is the current one.

## Commands

```bash
npx shadcn@latest add https://agentsandhumans.ai/api/registry/agent-workflow.json --yes
```

To use the short name, add the namespace to `components.json` once:

```json
{ "registries": { "@agentsandhumans": "https://agentsandhumans.ai/api/registry/{name}.json" } }
```

```bash
npx shadcn@latest add @agentsandhumans/agent-workflow
```

## When it goes wrong

- **It asks to overwrite `tokens.css`.** Each component ships the same file. Answer yes, or pass `--overwrite`.
- **It asks to run `init`.** Stop. Write `components.json` by hand (see `inspect.md`) and run `add` again.
- **The example lands in the wrong place** (a `src/` app, or Pages Router). Move `page.tsx` and `route.ts` to where the app keeps pages and API routes. In Pages Router the route becomes `pages/api/agent-workflow.ts` with a `(req, res)` handler; keep its logic.
- **Imports of `@/lib/...` fail.** The app has no `@/*` alias or puts `lib` elsewhere. Fix the import paths in the installed files, not the app's `tsconfig.json`, unless the person agrees.
- **Tailwind or CSS layer warnings.** `tokens.css` is plain CSS with its own variables. It needs no Tailwind.