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

# Agent configuration files

> Every per-agent YAML file, what it controls, and whether the feature ships on or off.

Every agent lives in its own folder and is self-contained. Files resolve
most-specific-first across `<project>/.ziro/agents/<id>/`, then
`~/.ziro/agents/<id>/`, then the bundled package, so an installed Ziro is
configured under your home directory without editing the package. A missing file
falls back to built-in defaults.

| File                     | Controls                                                             | Default               |
| ------------------------ | -------------------------------------------------------------------- | --------------------- |
| `meta.yaml`              | Name, description, `enabled` flag, pinned `model`, pinned `provider` | Required              |
| `agent_config.yaml`      | The persona and soul prompt                                          | On                    |
| `tool_policy.yaml`       | `core_tools`, deferred tiers, `max_active`                           | On                    |
| `permissions.yaml`       | Per-tool allow / deny / ask gating                                   | On                    |
| `guardrails_policy.yaml` | Input and output guard toggles and backends                          | Per agent             |
| `compaction_policy.yaml` | Trigger percentage, strategy, tool-output caps                       | On                    |
| `mcp_servers.yaml`       | External MCP servers and transports                                  | Empty                 |
| `hooks.yaml`             | Lifecycle hook specs by event and matcher                            | Empty                 |
| `memory_policy.yaml`     | Fact extraction, reflection, project memory                          | On                    |
| `shell_policy.yaml`      | `run_shell` mode, interpreter, denylist, timeouts                    | **Off**               |
| `fs_policy.yaml`         | Read tools, `allow_write`, confinement, scratch, `deny_paths`        | On                    |
| `webfetch_policy.yaml`   | `web_fetch`, SSRF guard, content caps                                | Per agent             |
| `websearch_policy.yaml`  | `web_search` provider and caps                                       | Per agent             |
| `subagent_policy.yaml`   | Allowed children, depth, spawn caps, model defaults                  | On                    |
| `handoff_policy.yaml`    | `request_handoff`, operator prompt, timeout                          | On                    |
| `clarify_policy.yaml`    | `ask_user_question`, question and option limits                      | On                    |
| `queue_policy.yaml`      | Background worker queue                                              | **Worker off**        |
| `voice_policy.yaml`      | STT and TTS backends                                                 | **Off**               |
| `attachment_policy.yaml` | Image size and type limits, notices                                  | On                    |
| `agents_md_policy.yaml`  | `AGENTS.md` ingestion and token cap                                  | On                    |
| `plugin_config.yaml`     | Which plugins may surface for this agent                             | **Absent means none** |

This page will expand each row with its schema, the meaningful keys, and a worked
example. Two rules are worth knowing now: a **missing** `plugin_config.yaml` means
the agent surfaces zero plugins (absence is opt-out, unlike every other file), and
a **malformed** one fails closed rather than falling back to permissive.

<Note>
  This page is in progress. See the [configuration guide](/guides/configuration) for
  how the layers resolve and how flavours overlay them.
</Note>

<Columns cols={2}>
  <Card title="Configuration" icon="settings" href="/guides/configuration">
    Layer resolution, flavour overlays, and project trust.
  </Card>

  <Card title="Permissions" icon="shield" href="/guides/permissions">
    `permissions.yaml` in depth.
  </Card>
</Columns>