# pi-flows documentation

pi-flows adds a `flow` tool to [pi](https://github.com/earendil-works/pi). The tool delegates bounded work to isolated child processes. Start at the [project README](../README.md) for the pitch, the install steps, and the [quick start](../README.md#quick-start). This index groups the other pages by purpose.

## How-to guides — get something done

- [Custom agents](./how-to/custom-agents.md) — write your own flow agents as markdown files, with shadowing and project trust explained.
- [Troubleshooting](./how-to/troubleshooting.md) — setup fixes, plus the catalog of every structured error code with its 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.
- [Architecture classification](./reference/architecture.md) — the ledger that maps each module to a subdomain, and the import direction between subdomains.

## Explanation — understand the design

- [Patterns](./explanation/patterns.md) — when a flow helps, which agent-design pattern each mode encodes, and what the harness guarantees.
- [Decomposition](./explanation/decomposition.md) — structural admission, optional Decomposition review, dependency waves, and the boundary with post-dispatch replanning.
- [Domain model](./explanation/domain-model.md) — why the codebase is split into Core, Supporting, and Generic subdomains, and why the import direction and review policy are what they are.
- [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, `research/` holds internal research notes, and `images/` holds demo GIFs generated by `scripts/demo/*.tape`. `domain-review.json` records the domain-model judgment rows that `npm run score:domain` carries.