> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aui.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Capabilities & Policies

> What the agent can do, and the gates that govern every action and every reply.

Two declarations carry an agent's behavior. **Capabilities** state what it can do; **policies** state what must hold before it does. Both are business statements the runtime enforces — never prompts, never function schemas.

## Capabilities

A capability is one thing the agent can do, in one folder: `capabilities/<id>/capability.yaml`.

```yaml theme={"dark"}
id: cancel-order
intent: Cancel an order the caller placed.
use_when: >
  The caller wants to cancel, stop, or undo an order.
needs: [order.id, order.status]
reads: [orders]
changes: [orders]          # naming a source here makes this an ACTION
confirm:
  show: [order.id, order.total]
  warn: "This can't be undone once the order has shipped."
report:
  outcomes:
    - when: order.status is "shipped"
      say: >
        This order has already shipped, so it can't be cancelled —
        but I can start a return instead.
    - otherwise:
        say: "Done — {order.id} is cancelled and the refund is on its way."
```

The key difference from tool-calling: **the author never writes the orchestration.** The runtime routes to the capability on `use_when`, works out each fact in `needs` — from context, sources, derivations, or by asking the caller in that fact's own words — and only then proposes the action. `reads` names the sources consulted; `changes` names what the action writes, and a `changes` capability takes a `confirm` read-back — an irreversible write without one refuses to build.

## Policies: the gates

A policy is a gate: a condition that must hold before an action proceeds, and what to do when it doesn't. Agent-wide policies live in `policies/global.yaml`; capability-scoped ones sit next to the capability.

```yaml theme={"dark"}
policies:
  - id: refund-needs-a-delivered-order
    intent: Refunds are only issued for orders that actually arrived.
    applies_to: [refund-order]
    requires: order.status is "delivered"
    otherwise:
      refuse: >
        I can only refund an order once it's been delivered.
      offer: "I can check the delivery status for you."
```

* **`requires`** fails closed — if the condition is unknown, the action does not proceed. **`forbids`** fails open. Choosing between them is choosing what happens when the world is uncertain.
* **`applies_to`** names capabilities, or targets every write (`{effect: writes}`).
* **`otherwise`** says what happens at the gate: `refuse`, `must_say`, `offer`, `ask`.
* **`intent`** is the reason — it appears in the trace as the *because* of every enforcement.

Because a gate is a predicate over established facts, it cannot be talked around: gating on what a caller merely *claims* (a `conversation` fact) is itself a build error — ownership and identity gate on verified facts.

## Obligations: the reply-level guardrails

Alongside gates, the policies files carry **obligations** — constraints on the reply itself: things the agent must `never` say or must always include (`must`, `must_say`), optionally scoped by `when` or by standing state. This is where the old notion of "guardrails" lives — as checked rules, not advisory prose.

## Four surfaces, one question each

The engine separates refusal into four surfaces — most authoring confusion is putting a rule on the wrong one:

| Surface                     | Owns the question                  | Fires                                |
| --------------------------- | ---------------------------------- | ------------------------------------ |
| **Intake** (the door)       | Is this conversation mine at all?  | Before any capability runs           |
| **Policies** (the gates)    | May this *action* proceed?         | When a capability's work is proposed |
| **Obligations** (the reply) | May this *reply* ship?             | After the reply is composed          |
| **Decline** (the words)     | How do I say "not something I do"? | When routing finds nothing           |

Together with [confirmation](/overview/agent-program) (explicit consent before an irreversible write, with an expiry — a question left hanging is not consent), these give every rule one home and every enforcement a readable trace.