docs: repository README, contributor rules, scenario template and authoring guide

README leads with the finding that motivated the repository -- pi emits the
skills section only when a tool named 'read' is active, so Curator's
--no-tools --skill combination made its policy unreachable -- with the measured
before/after table and instructions to reproduce it at zero token cost.

AGENTS.md sets seven rules for anyone changing this repository. The third is the
one that matters most: verify pi's behaviour with a probe rather than inferring it
from the docs. Three claims in the first draft of these documents were wrong and
were only corrected by running one.

The _template scenario carries the isolation defaults and inline warnings at the
places where mistakes have already cost time: --no-tools disabling the skills
mechanism, cwd anchoring .pi discovery, the read override being mandatory rather
than optional, and allowed-tools frontmatter not being enforced in 0.84.3.

AGENTS.md

@@ -0,0 +1,74 @@
+# Working in pi-agent-config
+
+Rules for any agent or person changing this repository.
+
+## 1. Never commit a credential
+
+`models.json`, `auth.json`, `trust.json`, `*.env`, `*.pem`, private keys and any
+`*.rendered*` file are ignored, and `scripts/verify-no-secrets.sh` blocks them as
+a pre-commit hook. **Do not use `--no-verify`.** If the guard fires on a genuine
+false positive, fix the file (use a `${PLACEHOLDER}` and a `*.template` suffix) or
+add a narrow, commented exception to the guard — do not widen it broadly.
+
+Backups contain plaintext keys and must be written outside the work tree.
+`scripts/pi-backup.sh` refuses in-repo destinations.
+
+## 2. This repository is the source of truth, with one exception
+
+Configuration flows *out* of here via `scripts/deploy-*.sh`. Do not edit
+`~/.pi/agent` or `~/pi-workspaces/*` directly and then forget to bring the change
+back; `scripts/pi-diff.sh` exists to catch exactly that.
+
+The exception is a scenario whose `profile.toml` says `deploy = "mirror"`. A
+mirror records what a running service already does. It is diffable but not
+deployable, and `deploy-scenario.sh` refuses `--apply` for it. Promote a mirror
+to `managed` only as a deliberate, separately reviewed step.
+
+## 3. Verify pi's behaviour; do not infer it from the docs
+
+Several claims in this repository were wrong on the first pass and were only
+corrected by running a probe. Examples: `AGENTS.override.md` does not block
+parent-directory context files; `PI_CODING_AGENT_DIR` does not cover
+`~/.agents/skills`; `--no-tools` silently disables the entire skills mechanism.
+
+Before asserting a mechanism, prove it:
+
+```bash
+docs/evidence/probe-harness/collect-evidence.sh
+shared/extensions/tests/run-guard-checks.sh
+python3 shared/lib/py/tests/test_pi_rpc_smoke.py
+```
+
+All three cost zero model tokens: a single RPC `get_state` starts the agent,
+fires `session_start` and exits without contacting the provider. Record new
+findings in `docs/pi-runtime-notes.md` with a source quote or a probe result, and
+date them — they are version-specific.
+
+Re-run all three after every `pi update` and update the version banner.
+
+## 4. Do not restart services from a script
+
+Restarting interrupts a live conversation. Scripts print the command; a human or
+an explicitly instructed agent runs it.
+
+## 5. Keep enumerations in code, not in prose
+
+Intent values, verdict scales, field names and tool schemas must have one owner.
+The scenario backend defines them, exports JSON Schema, and the extension
+consumes that schema (`registerTool` accepts a plain JSON Schema object). Prose
+describes policy; code defines shape.
+
+A rule written in three places will drift. It already did once: the
+recommendation enum had four values in one file and five in another.
+
+## 6. Language
+
+Documentation and code comments: English. Anything the model reads as
+instructions — `SYSTEM.md`, `APPEND_SYSTEM.md`, `SKILL.md`, prompts — Chinese,
+matching the user-facing language.
+
+## 7. Explain *why* in commits
+
+These are configuration and security boundaries. A commit that says what changed
+but not which failure mode it prevents is not reviewable. Reference the measured
+evidence where one exists.