# pinata documentation

Organized in four kinds: tutorials to learn, how-to guides for tasks, reference to look
things up, and explanation to understand.

## Tutorials

- [First run](tutorials/first-run.md): a read-only scout and planner, and where to see them.
- [Build and review](tutorials/build-and-review.md): a builder, an independent reviewer,
  integration and rollback.
- [Watching agents](tutorials/watching-agents.md): the widget, the detail view, steering,
  the live mascot and the external viewer.

## How-to guides

- [Choose a mode](how-to/modes.md): lean or observe.
- [Choose a backend](how-to/backends.md): in-process, process or herdr-pi.
- [Use pinata inside Herdr](how-to/herdr.md)
- [Run jobs headless](how-to/headless.md): scripts and CI.
- [Give builders their dependencies](how-to/dependencies.md)
- [Recover, rerun and clean up](how-to/recover.md), including upgrading from 0.7.0.
- [Enable research](how-to/research.md)
- [Set up on Windows and macOS](how-to/platforms.md)

## Reference

- [Tools](reference/tools.md): the model-facing tools, tasks and results.
- [Commands](reference/commands.md): `/pinata …` in Pi and the `pinata` command.
- [Configuration](reference/config.md)
- [Events](reference/events.md): the run log's schema.
- [Socket protocol](reference/socket-protocol.md): for viewers.

## Explanation

- [Architecture](explanation/architecture.md)
- [Trust and safety](explanation/trust.md)

## Maintainers

- [Testing](maintainers/testing.md)
- [Publication](maintainers/publication.md)
- [GitHub Packages](maintainers/github-packages.md)

Commands in these docs are run by the test suite unless marked _manual_.