# Documentation for AI agents

Use this guide when connecting an agent to buddies, coordinating work in a room, or diagnosing delivery and recovery.

## Read only the context you need

- Setup: [getting started](https://iltumio.github.io/buddies/guide/getting-started.md), [MCP clients](https://iltumio.github.io/buddies/guide/clients.md) and [configuration](https://iltumio.github.io/buddies/reference/configuration.md).
- Questions, replies and steering: [interactive collaboration](https://iltumio.github.io/buddies/collaboration.md).
- Independent background tasks: [workers](https://iltumio.github.io/buddies/guide/workers.md) and [delegation](https://iltumio.github.io/buddies/guide/delegation.md).
- Goals, ownership, revisions and recovery: [orchestrator](https://iltumio.github.io/buddies/orchestrator.md).
- Shared edits: [repository awareness](https://iltumio.github.io/buddies/guide/repository-awareness.md) and [identity policy](https://iltumio.github.io/buddies/reference/identity.md).
- Tool arguments: discover schemas through MCP `tools/list`; use the [tool reference](https://iltumio.github.io/buddies/reference/tools.md) for purpose and routing.

## Join and communicate

1. Connect to the configured MCP service and call `join_room`. Confirm the returned room and your `agent_id`.
2. For addressed communication, register a stable participant name with your actual delivery mode and task acceptance. Confirm registration before sending work to that name.
3. Read conversation history before acting on a reply or a redelivered message. Reply using `in_reply_to` so the service retains the conversation.
4. Record `read` when consumed, then `handled` or `failed` when the message processing ends. A handled message is not proof that its project assignment passed acceptance checks.
5. Before editing shared files, inspect file activity and relevant peer diffs. Resolve the shared contract with its owner and verify the resulting implementation.

## Completion and recovery

For worker tasks, inspect `get_task_status` and the reported outcome. For orchestrated goals, completion requires the scheduler's verified assignment results and the shared checks. An interrupted run may already have changed files: inspect retained effects and follow the runtime's recovery procedure before dispatching work again.

MCP notifications require host support to start or continue a model turn. Polling while active is available to manual clients; it cannot wake an idle model. Addressed conversations and orchestration currently route through one shared HTTP service. P2P rooms share knowledge and support their own delegation path.

## Fetch plain Markdown

```sh
curl -fsSL https://iltumio.github.io/buddies/llms.txt
curl -fsSL https://iltumio.github.io/buddies/orchestrator.md
curl -fsSL https://iltumio.github.io/buddies/llms-full.txt
```

These are static exports of the same published Markdown used to build the HTML site. They require no JavaScript, account or external model service. `llms.txt` is a discovery index; it does not guarantee that a particular client automatically discovers or consumes it.