# for agents

Start in the shop worktree you own. Read the CLI's guidance and current state:

```sh
antil skill print
antil status --json
```

If there is no session, inspect `antil.yaml`, install the app's dependencies, prepare its resources, and start it with `antil session start --json`. Follow the [quickstart](/docs/quickstart/) for the shop's exact setup. Do not choose app ports yourself.

## read the result before acting

Check the top-level `status` and process exit code. Inspect `blockers`, `conflicts`, and `next_actions` before issuing another mutation. Run a returned action as an argument array, after checking its preconditions; do not concatenate it into a shell command.

For an app, require `data.services.web.state` to be `ready`, then open `data.services.web.url` in your harness's browser. Read its direct loopback URL if your client cannot resolve the named localhost address.

For resources, use the provided environment mapping. Do not copy database credentials into chat or logs. For test commands, inspect the command's exit status and exact log; a running app is not a passing test.

## survive retries and handoffs

For commands that accept `--idempotency-key` (session lifecycle, workspace creation, named commands, and resource changes), give each request one stable key. Check the command help for support. Reuse that key if delivery is uncertain. A different key means new work, including another test run. If a request is still running, follow it. If its outcome is unknown, inspect it before choosing an explicit retry.

Record a handoff to the next agent:

```sh
antil status --takeover checkout-agent --json
```

`status --takeover` and `session touch` do not accept an idempotency key. Repeating them refreshes liveness; it does not start another app or test.

A stale mark does not release a worker's data or ports. End the worker deliberately when it is finished.

## the three parts

Use **tunnels: apps & urls** for ready app addresses, **chambers: shared resources** for data, and, when available, **seals: proof & cache** for reusable test proof. Today chambers manage Postgres only and seals are coming. [The foundation](/docs/foundation/) is shared by all three.

## machine-readable docs

Read [llms.txt](/docs/llms.txt) for the page index or [llms-full.txt](/docs/llms-full.txt) for the whole manual. Every page also has **view markdown** and **copy page**. The [JSON reference](/docs/reference/json/) and [CLI reference](/docs/reference/cli/) describe the literal contract.