fix: register background tools, session replay, background persistence, and tests/docs for Task 5 spec-review

README.md

@@ -32,7 +32,31 @@ pi install https://gitea.rwiesner.com/pi/pi-subagents
 - selected model
 - optional working directory
 
-Child runs are normal Pi sessions. This package does not add built-in role behavior, markdown-discovered subagents, per-agent tool restrictions, or appended role prompts.
+Child runs are normal Pi sessions.
+
+## Presets
+
+Subagent presets are discovered from markdown files. Locations:
+
+- global: `~/.pi/agent/subagents/*.md`
+- nearest project: `.pi/subagents/*.md` (nearest ancestor directory)
+
+Project presets override global presets by name. No built-in presets or roles are bundled with this package.
+
+Preset frontmatter fields:
+
+- `name` (required)
+- `description` (required)
+- `model` (optional; provider/id)
+- `tools` (optional; comma-separated list or array)
+
+Preset body becomes the child session system prompt. The `tools` field maps directly to Pi CLI `--tools` and limits which built-in tools are available to the child run.
+
+## Tools provided
+
+- `subagent` — foreground single or parallel runs using named presets
+- `background_agent` — detached process-backed run that returns immediately with a handle
+- `background_agent_status` — query background run counts and status
 
 ## Requirements