Mirrors ~/.pi/agent/ as the authoritative copy. models.json becomes
models.json.template with ${ZENMUX_API_KEY} substituted; the real value stays
in secrets/zenmux.env, which is untracked and enforced by the pre-commit guard.
Excluded with rationale: auth.json, trust.json, models-store.json, sessions/,
herdr-agent-state.ts (installer-managed, overwritten on reinstall) and the
third-party skills under ~/.agents/skills.
Recorded during migration: the configured fallback model zenmux/x-ai/grok-4.6 is
absent from models.json, so pi falls back to an undeclared custom model id with
no context window, cost table or thinkingLevelMap. Fixing that is a behaviour
change and is deferred rather than folded into this zero-change migration.
Two defects found by testing the guard against itself:
1. When invoked through the .git/hooks/pre-commit symlink, deriving the repo
root from dirname(BASH_SOURCE)/.. resolved to .git/ instead of the work
tree, so the hook scanned nothing and never blocked. Use
'git rev-parse --show-toplevel' instead.
2. The blanket secrets/ rule rejected secrets/.gitkeep. Replaced with an
explicit allowlist: .gitkeep, README.md, *.example, *.template.
Verified: a staged file containing a Telegram bot token now aborts the commit
and leaves HEAD unchanged.
Establishes this repository as the authoritative source for Pi agent
configuration across scenarios, starting with the documentation layer.
Key verified findings (probe harness included, zero model tokens):
- The skills section of the system prompt is emitted only when an active tool
named 'read' exists (system-prompt.js:59,113). Therefore --no-tools silently
makes every SKILL.md unreachable and --skill a no-op.
- registerTool accepts a plain JSON Schema object, so tool definitions can be
served from a backend instead of duplicated in TypeScript.
- An extension can shadow a built-in tool by name, which is how a dedicated
agent gets a path-restricted 'read' while still satisfying the rule above.
- .pi/SYSTEM.md replaces pi's coding-assistant prompt, but the replacement
branch contributes neither the tool list nor the guidelines.
- Without --no-skills/--no-extensions, user-global resources leak into every
scenario; probed leak was find-skills, modsearch, summarize.
Measured effect of the full baseline: system prompt 2619 -> 960 characters,
coding-assistant framing and pi-docs paths removed, skill finally reachable.
Secrets are guarded by scripts/verify-no-secrets.sh, installed as a pre-commit
hook. Backups deliberately live outside the repository.
Kai