# pi-flows documentation

pi-flows adds a `flow` tool to [pi](https://github.com/earendil-works/pi) that delegates bounded work to isolated child processes. Start at the [project README](../README.md) for the pitch and install; this index organizes the docs by the [Diátaxis](https://diataxis.fr/) framework.

## Tutorials — learn by doing

- [Quickstart](./tutorials/quickstart.md) — install, load the extension, and run your first delegated task, with no-model smoke checks along the way.

## How-to guides — get something done

- [Custom agents](./how-to/custom-agents.md) — write your own flow agents as markdown files, and understand shadowing and project trust.
- [Troubleshooting](./how-to/troubleshooting.md) — setup fixes plus the canonical catalog of every structured error code, each with cause and fix.
- [Release runbook](./how-to/release.md) — how maintainers cut, evidence, and roll back a release.
- [Examples cookbook](../examples/README.md) — copy-paste invocations for every mode, including error cases.

## Reference — look it up

- [Flow reference](./reference/flow-reference.md) — the complete `flow` tool contract: presets, modes, parameters, budgets, tracing, and structured errors.
- [Package reference](./reference/package.md) — what ships in the npm package, the pi manifest, and every install method.

## Explanation — understand the design

- [Patterns](./explanation/patterns.md) — when a flow helps, which agent-design pattern each mode encodes, and what the harness guarantees.
- [Privacy & telemetry](./explanation/privacy-telemetry.md) — what leaves your machine (nothing by default), what is redacted, and the controls.

## Not user docs

The other directories here serve the repo, not readers of the package: `agents/` holds contributor-agent instructions, `adr/` holds architecture decision records, `audits/` holds point-in-time audit records, and `images/` holds demo GIFs generated by `scripts/demo/*.tape`.