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.
Scenarios
- memo-inbox: mirrored by copying; the live directory was not moved or modified
and the service was not restarted. All four tracked files match byte for byte
(pi-diff.sh reports SAME). Marked deploy = "mirror" so deploy-scenario.sh
refuses --apply: applying a mirror would invert the direction of truth and
could change a service in daily use.
- curator: target configuration, not yet deployed. .pi/SYSTEM.md replaces pi's
coding-assistant prompt; durable role text is in .pi/APPEND_SYSTEM.md;
profile.toml is the single source of truth for the launch contract.
- pi-grok: registered only. It is genuinely a coding agent, so the isolation
baseline does not apply in full.
Corrections to the documentation, found by testing rather than by reading
- AGENTS.override.md does NOT block parent-directory context files; it only
shadows its own directory. Verified: with an override file in the workspace, a
marker in /tmp/AGENTS.md still reached the system prompt. The only effective
switch is --no-context-files, so durable role text must live in
.pi/APPEND_SYSTEM.md, which is a system-prompt file and unaffected by -nc.
Verified end state: no coding-assistant framing, no pi-docs block, own
identity and role text present, no parent pollution, only own skills/tools.
- PI_CODING_AGENT_DIR isolates settings/models/auth/trust/extensions/skills/
prompts/themes under the agent directory -- stronger than the --no-* flags
because it also repoints credentials -- but does NOT cover ~/.agents/skills.
Measured: find-skills, modsearch and summarize still leak. So it complements
--no-skills rather than replacing it.
- --append-system-prompt accepts a file path, which pi-grok relies on.
- cwd is what anchors .pi discovery: a probe that forgot cwd silently lost
.pi/SYSTEM.md and kept the coding-assistant persona.
Tooling (all dry-run by default; none of them restarts a service)
- pi-diff.sh: compares tracked config against the live install in both
directions, with a key-redacted comparison for models.json
- deploy-scenario.sh: installs a workspace and renders profile.toml into
.pi/launch.json, then checks that every referenced path exists
- deploy-runtime.sh: renders models.json from its template, refusing placeholder
or missing keys. Verified byte-identical to the live file
- pi-backup.sh / pi-restore.sh: archives outside the repo, sha256 manifest
verified before any restore, live paths preserved rather than overwritten
Fixed while testing: pi-backup.sh compared the destination against the repo root
literally, so a relative --dest ./backups wrote credential archives into the work
tree. Now canonicalised with realpath; ./backups, an absolute in-repo path and
./docs/../backups are all refused.
Kai