# Scenario: <name>

<One paragraph: what this agent does and for whom.>

Live service: `<name>.service`.
Live workspace: `/home/claw/pi-workspaces/<name>`.

## Checklist for a new scenario

1. Copy `scenarios/_template/` to `scenarios/<name>/` and fill every
   `<PLACEHOLDER>` in `profile.toml`.
2. Write `.pi/SYSTEM.md` — all six sections. The replacement branch supplies no
   tool list and no guidelines.
3. Write `.pi/APPEND_SYSTEM.md` for durable domain responsibilities.
4. Write the extension. Build it on `shared/extensions/pi-guard-base.ts`:
   `registerRestrictedRead` (mandatory — it is what keeps skills reachable) and
   `installGuard`. Give every tool a `promptSnippet`.
5. Drive it from `shared/lib/py/pi_rpc.py` rather than spawning `pi --print` per
   message.
6. Verify before deploying:
   ```bash
   scripts/deploy-scenario.sh <name>          # dry run
   shared/extensions/tests/run-guard-checks.sh
   ```
7. Deploy and restart yourself:
   ```bash
   scripts/deploy-scenario.sh <name> --apply
   systemctl --user restart <name>.service
   ```
8. Record the conformance row in `docs/isolation-baseline.md`.

## Gotchas that have already cost time

- `--no-tools` disables extension tools too, which removes `read`, which removes
  the skills section. Never use it. Use `--no-builtin-tools`.
- `cwd` anchors `.pi` discovery. Launch with `cwd` set to the workspace or
  `.pi/SYSTEM.md` is silently ignored.
- `--approve` is required for anything under `.pi/`.
- A tool without `promptSnippet` is callable but invisible in the prose tool list.
- Tools must truncate their own output (50 KB / 2000 lines).