diff --git a/README.md b/README.md
index e7c55ce..72fcef2 100644
--- a/README.md
+++ b/README.md
@@ -6,10 +6,14 @@ Experimental monorepo for [Pi coding agent](https://github.com/mariozechner/pi-c
 
 ### `pi-turn-limit`
 
-Limits the number of turns (agent round-trips) in a Pi session. When the limit is exceeded, the agent aborts with an error notification.
+Limits the number of turns (agent round-trips) in a Pi session. When the limit is reached, the user is prompted to continue or abort.
 
 - **Default limit:** 25 turns
-- **Override:** set `PI_MAX_TURNS` environment variable
+- **Override:** set `PI_MAX_TURNS` environment variable to a positive integer
+- **Unlimited:** set `PI_MAX_TURNS=unlimited` or run the `turn-limit unlimited` command to disable the boundary check entirely (the counter still increments for observability)
+- **Re-enable:** switch from unlimited back to a number via `turn-limit <N>`; the counter resets to 0
+
+See [packages/pi-turn-limit/README.md](packages/pi-turn-limit/README.md) for details and the [Allium spec](packages/pi-turn-limit/turn-limit.allium).
 
 ## Installation
 
diff --git a/packages/pi-turn-limit/README.md b/packages/pi-turn-limit/README.md
new file mode 100644
index 0000000..8bd82dc
--- /dev/null
+++ b/packages/pi-turn-limit/README.md
@@ -0,0 +1,81 @@
+# pi-turn-limit
+
+Pi coding agent extension to limit the number of turns taken by a model in a session.
+
+## Why
+
+Pi agents can run indefinitely, consuming tokens and time, and taking focus. This extension gives you a circuit breaker: when the agent reaches a configurable turn limit, you decide whether to continue or abort.
+
+This is useful for:
+
+- **Interaction** — Shorter _Time To Next Interaction (TTNI)_ keeps you in the loop. Focus, clarity, single-tasking mode. 
+- **Cost control** — prevent runaway sessions from burning through API credits
+- **Quality control** — if an agent needs more turns than expected, something may be wrong with the prompt or task
+
+## How it works
+
+The extension tracks turns (agent round-trips) per session. Each new user prompt resets the counter.
+
+| Event                 | Behavior                                          |
+|-----------------------|---------------------------------------------------|
+| `agent_start`         | Counter resets to 0                               |
+| `turn_start`          | Counter increments; widget updates                |
+| Counter reaches limit | User prompted: continue (counter resets) or abort |
+| No UI available       | Silent abort at limit                             |
+
+When the limit is reached and the user confirms continuation, the counter resets to 0, allowing another round of turns. This repeats — there's no maximum number of continuations.
+
+## Configuration
+
+### Environment variable
+
+Set `PI_MAX_TURNS` before starting pi:
+
+```bash
+# 50 turns
+PI_MAX_TURNS=50 pi
+
+# Unlimited — no boundary check fires
+PI_MAX_TURNS=unlimited pi
+
+# Default (25 turns)
+pi
+```
+
+### Runtime command
+
+Adjust the limit during a session with the `turn-limit` command:
+
+```
+/turn-limit 50        # Set to 50 turns
+/turn-limit unlimited # Disable the limit
+/turn-limit 25        # Re-enable with 25 turns (counter resets from 0)
+```
+
+### Unlimited mode
+
+Setting the limit to `unlimited` disables the boundary check entirely. The turn counter still increments and the widget still displays `∞`, so you retain observability without enforcement.
+
+Switching from unlimited back to a number triggers the **LimitReEnabled** rule: the counter resets to 0 so the new limit applies from a clean starting point.
+
+## Widget
+
+When a UI is available, the extension displays a widget showing `Turns: N/M` (or `Turns: N/∞` in unlimited mode).
+
+## Spec
+
+This extension was developed using [Allium](https://juxt.github.io/allium/), a formal language for specifying software behavior. The Allium spec captures the turn counting, limit enforcement, unlimited mode, and re-enable rules:
+
+📄 [turn-limit.allium](./turn-limit.allium)
+
+## Contributing
+
+This is an experimental extension. To contribute:
+
+1. Fork the repository
+2. Make your changes
+3. Contact Willem through [qwan.co.uk](https://qwan.co.uk) to discuss your contribution
+
+## License
+
+MIT