Replace the leads demo with examples that run

DESIGN.md

@@ -218,7 +218,10 @@ plane — which is what makes them different from `store.url`, holding the check
 and files a parked task resumes from.
 
 At boot the worker loads each listed config version and calls
-`worker.workflow(agent, version=N)` once per version. There is one operation —
+`worker.workflow(agent, version=N)` once per version. It reads only what the agent
+is — `v<N>.yaml` and its skills. `runtime.yaml` and `lifecycle.yaml` are policy,
+applied rather than served, and the caps come back from the control plane, so the
+same numbers hold whether the worker was given a checkout or a pulled artifact. There is one operation —
 the entry handler — re-entered after every park. `serves` is what makes a worker fleet-manageable: which process can run
 which agent is declarative, so you can shard agents across workers, or run a
 canary worker holding only `v2` while the fleet stays on `v1`.
@@ -434,6 +437,13 @@ tools:
   trace.
 - **`always`** — the call is intercepted and parks, every time.
 
+A gated tool also gains a required `justification` argument, which the model fills
+and Charter strips before calling the server. It becomes the gate's
+`justification`, which is the only field a notification carries. The harness
+supplies no reasoning of its own, so without it an approver sees the call and
+nothing else. `justify: false` on a tool turns it off, for a call whose arguments
+already say everything.
+
 Set every tool to `never`, omit `gate`, and omit `ask_human`, and
 you have a fully autonomous agent that never asks anyone anything. It is still
 governed: per-task budget, tool limits, the full audit trail, and lifecycle rules
@@ -678,6 +688,9 @@ exactly one of `pause: {window}`, `cooldown: {window, seconds}`, or
 `set_version: {target}`. A `set_version` target must exist on disk *and* appear in
 `serves[].versions` for every worker running the agent.
 
+`set_version` takes no window: it compares totals for the version now running,
+which reset when the version changes.
+
 ### Worker — `worker.yaml`
 
 Not versioned. Every secret is an `${ENV_VAR}` reference, never a literal.
@@ -735,8 +748,8 @@ break Charter's invariants outright:
 | `charter status <task-id>` | result, cost, tools called, approvals, why it stopped |
 | `charter audit <agent> --instance <id>` | every governance decision recorded |
 | `charter pending <agent> --instance <id>` | the open approval or input gate |
-| `charter approve <id> [--reason]` | resolve to workflow + approval id, decide |
-| `charter reject <id> [--reason]` | same |
+| `charter approve <id> [--actor] [--reason]` | resolve to workflow + approval id, decide |
+| `charter reject <id> [--actor] [--reason]` | same |
 | `charter answer <id> <text>` | respond to an `ask_human` gate |
 | `charter pause <agent> --instance <id> [--now]` | hold it; prints the suspension id |
 | `charter resume <agent> --instance <id> --suspension <id>` | release that hold |

README.md

@@ -57,7 +57,7 @@ export ANTHROPIC_API_KEY=<your model key>   # or another provider's, see worker.
 ```
 
 Remove it with `docker compose -f local.compose.yml down -v`. Cloning the repo
-works too, and gets you the examples and the demo alongside it.
+works too, and gets you the examples alongside it.
 
 For production you have two options. Run the BoundFlow backend yourself, following
 its [deployment docs](https://github.com/boundflow/boundflow/blob/main/docs/deployment.md).
@@ -197,7 +197,7 @@ Charter stops the task and shows a person the call it wants to make and the
 reasoning behind it:
 
 ```bash
-charter approve apr_01J8Z --reason "third dispute this month"
+charter approve apr_01J8Z --actor dana --reason "third dispute this month"
 ```
 
 Nothing waits in your terminal. The task ends at the gate and resumes when someone
@@ -288,10 +288,9 @@ through their workers and the control plane whether or not the CLI is installed.
 
 - [DESIGN.md](DESIGN.md): every field of every file, and the decisions behind them
 - [deploy/](deploy/): running workers as containers, and a control plane locally
-- [examples/](examples/): fuller configurations, for reading. They name real
-  Zendesk and Stripe servers, so they do not run as-is
-- [demo/leads/](demo/leads/): an agent that runs end to end against a local MCP
-  server, where you play the people it contacts
+- [examples/](examples/): two agents over a toy support system. One gates a refund
+  and pauses itself when too many are turned down, the other rolls itself back to
+  an earlier version. They run with nothing but a model key
 
 ## Development