# Pi Herd documentation

[Repository README](../README.md)

This directory is the canonical human documentation for `pi-herd`.

The documentation follows one-source-of-truth ownership:

- **Getting started** teaches the shortest useful workflow.
- **Concepts** explain the mental model.
- **Guides** explain how to accomplish tasks.
- **Reference** specifies exact public behavior.
- **Development** covers repository validation and maintainer procedures.
- Root `SKILL.md` is optional model-facing reinforcement of the self-contained
  runtime operational contract plus deeper coordination guidance. Runtime
  remains authoritative and does not depend on the skill.

## Start here

[Getting started](getting-started.md) gets from prerequisites to the first
managed worker.

## Concepts

- [Workers and identity](concepts/workers.md)
- [Lifecycle](concepts/lifecycle.md)
- [Delegation](concepts/delegation.md)

## Guides

- [Agent definitions](guides/agent-definitions.md)
- [Customizing bundled agents](guides/customizing-agents.md)
- [Handoffs and files](guides/handoffs.md)
- [Recovery](guides/recovery.md)

## Reference

- [`subagent` API](reference/subagent.md)
- [`ask_owner` API](reference/ask-owner.md)
- [Agent-definition schema](reference/agent-definition-schema.md)
- [Worker states](reference/worker-states.md)
- [`/subagents` commands](reference/commands.md)
- [Configuration](reference/configuration.md)
- [Status widget](reference/status-widget.md)
- [Errors](reference/errors.md)

## Development

- [Validation](development/validation.md)
- [Smoke testing](development/smoke-testing.md)
- [Documentation maintenance](development/documentation.md)

## Canonical ownership

| Subject                               | Canonical page                                                  |
| ------------------------------------- | --------------------------------------------------------------- |
| Requirements and first use            | [Getting started](getting-started.md)                           |
| Worker identity                       | [Workers and identity](concepts/workers.md)                     |
| State transitions                     | [Lifecycle](concepts/lifecycle.md)                              |
| Delegation model                      | [Delegation](concepts/delegation.md)                            |
| Creating definitions                  | [Agent definitions](guides/agent-definitions.md)                |
| Overrides and prompt composition      | [Customizing bundled agents](guides/customizing-agents.md)      |
| `files`, body references, and results | [Handoffs and files](guides/handoffs.md)                        |
| Operator recovery                     | [Recovery](guides/recovery.md)                                  |
| `subagent` request contract           | [`subagent` API](reference/subagent.md)                         |
| `ask_owner` contract                  | [`ask_owner` API](reference/ask-owner.md)                       |
| Frontmatter fields                    | [Agent-definition schema](reference/agent-definition-schema.md) |
| Public worker states                  | [Worker states](reference/worker-states.md)                     |
| `/subagents` human commands           | [`/subagents` commands](reference/commands.md)                  |
| Settings                              | [Configuration](reference/configuration.md)                     |
| TUI worker widget                     | [Status widget](reference/status-widget.md)                     |
| Error categories                      | [Errors](reference/errors.md)                                   |
| Repository checks                     | [Validation](development/validation.md)                         |
| Live acceptance                       | [Smoke testing](development/smoke-testing.md)                   |

When another page needs one of these subjects, it links here instead of
restating the complete contract.