# Discovery

The discovery API exposes the same catalog shipped in `docs/DISCOVERY.json`
and used by `omnius discover` / `omnius show`.

| Method | Path | Purpose |
| --- | --- | --- |
| `GET` | `/v1/discovery/bootstrap` | Compact agent strategy, profiles, intents, safety rules, and expanded start-here entries |
| `GET` | `/v1/discovery` | Search or list catalog entries |
| `GET` | `/v1/discovery/{id}` | Expand one stable entry |

## Search

```bash
curl -s http://127.0.0.1:11435/v1/discovery/bootstrap
curl -s "http://127.0.0.1:11435/v1/discovery?q=web%20search&kind=workflow&audience=integrator&limit=5"
```

Query fields:

- `q`: free-text intent; omit to list entries.
- `kind`: one supported catalog kind.
- `audience`: require an exact audience tag.
- `layer`: require an exact architecture layer.
- `include_internal`: `true`/`1` to include internal notes hidden by default.
- `limit`: page size.
- `offset`: zero-based page offset.

The response includes pagination metadata and an ETag. Use
`If-None-Match` when polling a long-running daemon.

## Expand

```bash
curl -s http://127.0.0.1:11435/v1/discovery/tool.web-search
```

An entry contains its stable ID, kind, title, summary, aliases/keywords,
audiences/layer, use and avoid conditions, inputs/outputs, invocation
interfaces, workflow steps, verification, failure recovery, source-of-truth,
typed references, and related entries as applicable. Discovery is static,
read-scoped, cacheable, and does not probe hardware, install dependencies,
load models, or execute the selected capability.

Important entrypoints:

- `overview`
- `workflow.choose-entrypoint`
- `workflow.async-agent-run`
- `workflow.debug-runtime`
- `layer.orchestration`
- `store.project`
- `capability.bring-your-own-inference`
- `provider.anthropic`
- `provider.gemini`
- `tool.web-search`
- `api.tools`
- `operation.version-compatibility`

Static discovery describes declared behavior. For observed state, use the live
service endpoints named by an entry, such as `/version`, `/health/ready`,
`/v1/tools`, `/v1/asr/status`, or `/v1/voice/state`.