# 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.