# The catalog

Your OpenAPI document, with x-rungent on the operations agents may use, is the catalog. What an operation is, what its effect implies, how names become ids, how two calls chain, and how to check it all before you ship.

A cloud console already has an OpenAPI 3.1 document. Three of its endpoints become a catalog
with one `x-rungent` object each:

```json
"/api/vms": {
  "get": {
    "x-rungent": { "name": "list_vms", "description": "List the user's cloud servers (VMs)." }
  },
  "post": {
    "x-rungent": { "name": "create_vm", "description": "Create a cloud server (VM).", "form": "vm_form" }
  }
},
"/api/vms/{vm_id}/stop": {
  "post": {
    "x-rungent": {
      "name": "stop_vm",
      "description": "Stop a running cloud server (VM).",
      "effect": "update",
      "resolve": { "vm_id": { "op": "list_vms" } },
      "confirmation": { "title": "Stop server {vm_id}?" }
    }
  }
}
```

Operations without `x-rungent` stay invisible to rungent. The assistant, MCP, the CLI, `skill.md` and
search all read the same annotations, so you describe each operation once. Every key is in
[x-rungent](x-rungent.md).

## What an operation is

An operation is one HTTP method on one path that carries `x-rungent`. It is a tool for the agent,
a tool for MCP clients and a command of the CLI. Its `name` is the only required key: lowercase
letters, digits and `_`, at most 64 characters, unique in the catalog.

| Where | Spelling |
|---|---|
| The agent's tool, the MCP tool, the assertion's `op` | `stop_vm` |
| The CLI command | `stop-vm`, or the words in `cli.command` (`vm stop`) |

`description` is what the model reads to choose a tool: name the resource and the words users
say for it ("cloud server (VM)"). `title` labels approval cards, activity rows and CLI help.
Both default to the OpenAPI `summary`.

## Effects, approval and surfaces

`effect` says what a call does, and it sets the defaults for everything else. rungent takes it
from the HTTP method unless you say otherwise:

| `effect` | Meaning | Default for | `approval` | `surfaces` |
|---|---|---|---|---|
| `read` | Changes nothing | `GET`, `HEAD` | `never` | `agent`, `mcp`, `cli` |
| `create` | Creates something | `POST` | `always` | `agent`, `cli` |
| `update` | Changes something that exists | `PUT`, `PATCH` | `always` | `agent`, `cli` |
| `delete` | Removes something | `DELETE` | `always` | `agent`, `cli` |
| `external` | Reaches outside: sends mail, charges a card | none | `always` | `agent`, `cli` |

Set `effect` when the method does not say it: stopping a server is a `POST` that changes an
existing server, so `stop_vm` is an `update`. A `GET` must stay a `read`.

- **`approval`** is `never` or `always`, decided by the runtime from the catalog, never by a
  prompt. A read that should still be confirmed, such as exporting every customer, sets
  `"approval": "always"`. See [Forms and approvals](forms-and-approvals.md).
- **`surfaces`** lists where the operation appears. MCP starts read-only; list `mcp` on a write
  to offer it to MCP clients that can ask the user to confirm. See [Surfaces](surfaces.md).

## Operations with a special role

Some operations answer rungent itself instead of being tools. They carry `role`, have no surfaces,
and are never offered to the model:

| `role` | Shape | Page |
|---|---|---|
| `identity` | `GET`, no parameters; exactly one per catalog | [Acting as the user](acting-as-the-user.md#who-the-user-is) |
| `search` | `GET` with a required `q` query parameter | [Search and knowledge](search.md#add-a-search-source) |
| `form` | `POST` that answers a form; rungent treats it as a read | [Forms and approvals](forms-and-approvals.md#declare-the-form) |

## Each user sees their own catalog

rungent fetches your OpenAPI document with the signed-in user's own credential and keeps what it
read for 5 minutes per credential. Your server may leave out operations a user may not call,
and no surface offers them to that user. `GET /rungent/v0/catalog` lists what the caller sees.
Hiding an operation is a courtesy: your API still authorizes every call it receives.

## The input schema

rungent turns each operation into one flat input schema, which the model, MCP clients and the CLI
all see:

- Path and query parameters become top-level properties; path parameters are required.
- A JSON body that is an object with `properties` is flattened into top-level properties; any
  other body becomes one `body` property.
- `$ref`s into `#/components/schemas` stay as `$defs` references, so recursive schemas stay
  valid.

For `POST /api/vms/{vm_id}/stop` with the body `{"forced": boolean}`, the input is
`{vm_id, forced}`, with `vm_id` required. rungent splits the arguments back into path, query and
body when it calls your API.

Before any call, rungent coerces the arguments (a numeric string to a number, a JSON string to an
object) and validates them. Arguments that do not fit never reach your API: the model gets
`invalid_arguments` with each problem at its path (`vm_id: required`) and corrects its call.
An operation with a form opens its form instead.

## Turn names into ids

The user writes "stop gpu-train-01"; your route takes `vm-42`. `resolve` maps an argument to the
read operation that lists its candidates, `{op, key?}`, where `key` is the item field holding
the id (`id` by default). For each listed argument that holds a string, rungent:

1. calls `op` as the user, asking for 100 items when it takes a `page_size` query parameter;
2. takes the items from the answer: the array itself, or the first nested array of objects that
   carry `key` (`{"items": [...]}`);
3. keeps the value when an item's `key` equals it, because it is already an id;
4. otherwise compares it with each item's `name`, `display_name`, `displayName` or `title`,
   ignoring case, and replaces it with the one match's `key`.

No match, or several, fails the call with `unresolved_reference` and names up to ten
candidates, so the model can pick one or ask the user. Names resolve before the approval card,
so the approval binds to `vm-42` and a rename while the card waits cannot change what runs. A
confirmation [lookup](forms-and-approvals.md#write-the-card) puts the name back on the card.

Resolve suits collections one list call returns whole: servers, projects, members. For larger
ones, the model finds the id with [search](search.md) or a filtered list.

## Run two calls as one

Some actions take two calls: prepare a draft that checks quota and prices it, then commit it.
`next` on the first operation names the second, and rungent runs it right after success, before
the model writes anything:

```json
"x-rungent": {
  "name": "prepare_vm_draft",
  "approval": "never",
  "next": {
    "op": "commit_vm_draft",
    "arguments": { "draft_id": "id", "revision": "revision" },
    "when": { "status": "prepared" }
  }
}
```

The draft answers `{"id": "d-7", "revision": 3, "status": "prepared", …}`, so rungent calls
`commit_vm_draft` with `{"draft_id": "d-7", "revision": 3}`. A draft that answers
`"status": "needs_quota"` fails `when`: the chain stops and the model explains the result.
`argumentsFrom` takes a result object as the next call's whole input instead
([x-rungent](x-rungent.md#chains)).

The next call goes through validation, resolve and its own approval like any other, so a chain
never skips a card. Each operation runs at most once per chain, so a cycle ends.

## What happens after a call

- `open` names a page of your product to show after success, filled from the arguments and the
  result (`/console/instance/{vm_id}`). The dock passes it to your router.
- `redact` lists result fields the model and MCP clients never see (`ip`). Fields with
  secret-like names (`password`, `token`, `api_key`, `cookie` and similar) are always removed.
- `timeoutSeconds` bounds the call: 120 seconds by default, at most 3600.
- Within one run, a write repeated with identical arguments is answered from the first result.
  Set `repeatable: true` when repeating is the point ("add one more GPU").
- An operation that needs longer than a request answers `202 {"rungentTask": "<id>"}`, and the run
  waits until your API [completes the task](http-api.md#deferred-tasks).

## Check the catalog

rungent validates the catalog when it reads it and refuses one with errors. Check a document
before you deploy it:

```bash
npx rungent check --openapi http://localhost:3000/api/openapi.json --routes routes.txt
```

It prints every issue and exits 1 when there is any; the rules are in
[x-rungent](x-rungent.md#validation-rules). `--routes` takes the requests your UI makes, one
`METHOD /path` per line, and fails each one no operation serves, unless the line ends with
`# browser-only: <reason>`. That keeps the agent able to do what your UI does.

## Where to go next

[Acting as the user](acting-as-the-user.md) shows how rungent calls these operations with the
user's own rights.
