cratis init does not configure Pi, and the embedded llm-context is a pinned snapshot

[woksin]

What works today

cratis init is a genuinely good design for this problem, and most of it needs no change:

• cratis llm-context emits a ~57 KB machine-readable descriptor of every command group, option, argument and output-format hint (181 named entries), plus connectionInfo, tips and per-command output guidance.
• cratis init writes a small always-loaded primer (CHRONICLE.md, ~3.7 KB) and a large on-demand skill carrying the full catalog (~60 KB). That split is the right call — the primer is cheap enough to always sit in context, and the expensive catalog is only pulled in when an agent is actually writing cratis commands.
• Detection is genuinely automatic: project files (.claude/, CLAUDE.md, .github/copilot-instructions.md, .cursor*, .windsurfrules) and runtime environment (CLAUDECODE, CLAUDE_CODE_ENTRYPOINT, VSCODE_PID, TERM_PROGRAM, CURSOR_TRACE_DIR, WINDSURF_SESSION_ID). So running cratis init from inside an agent's terminal configures that agent even on a first-time project.

The gap

AiTool covers claude, copilot, cursor, windsurf only. Pi (@earendil-works/pi-coding-agent) is not among them, and it is what a lot of this work is actually driven with.

Pi discovers skills from .pi/skills/<name>/SKILL.md and .agents/skills/<name>/SKILL.md, with YAML frontmatter carrying name and description — exactly the shape ChronicleSkillGenerator already emits. No format change is needed.

Verified end to end rather than assumed:

cratis init --tool claude --yes
mkdir -p .pi/skills/chronicle-cli
cp .claude/commands/chronicle-cli.md .pi/skills/chronicle-cli/SKILL.md

then asking Pi to list its skills returns chronicle-cli first. The generated file is byte-identical and needs no transformation — it is purely a matter of which path it is written to.

Suggested change

1. Add AiTool.Pi, writing .pi/skills/chronicle-cli/SKILL.md (and the diagnose command as .pi/prompts/chronicle-diagnose.md, matching Pi's prompt convention).
2. Detect it: project-side .pi/ directory, and environment-side the PI_* variables Pi sets in spawned terminals.
3. Include pi in --tool's accepted values and its description.

Since Pi also reads AGENTS.md walking up from cwd, the @CHRONICLE.md reference could equally be appended there rather than to CLAUDE.md — worth deciding deliberately rather than by default, since AGENTS.md is shared with other tools.

Second, smaller point: the catalog is a pinned snapshot

The embedded descriptor carries "version": "2.8.2.0" — it is a snapshot taken at init time, not resolved live. After a CLI upgrade the skill still describes the old surface, and nothing detects the drift. cratis init --refresh exists and fixes it, but nothing prompts anyone to run it.

Cheap options, roughly in order of effort: have cratis update run the refresh automatically; or have any command warn when the descriptor's recorded version differs from the running CLI's; or have the skill state the version it was generated from prominently enough that an agent notices the mismatch itself.

[woksin]

Fixed in #80.

Pi is configured now — the skill goes to .pi/skills/chronicle-cli/SKILL.md, the diagnose prompt to .pi/prompts/, and the @CHRONICLE.md reference to AGENTS.md. Detection covers both a project's .pi/ directory and the PI_* variables Pi exports, so running cratis init from inside a Pi session configures it on a project that has nothing yet. --tool pi targets it explicitly, and --refresh updates the Pi skill alongside the others.

Verified against the built binary rather than assumed: after cratis init --tool pi, asking Pi to list its skills returns chronicle-cli first. The generated file needed no transformation — the frontmatter the generator already emits is what Pi requires.

The snapshot half is addressed too. cratis init now reads the version out of an existing CHRONICLE.md and reports a mismatch instead of a bare "already exists":

CHRONICLE.md was generated by CLI v2.0.0.0 but this is v1.0.0.0 - run 'cratis init --refresh' to update the command catalog

A file carrying no version is deliberately not flagged — it predates version stamping or was hand-written, and a warning nobody can act on is how people learn to ignore warnings.

One thing I did not do, from the suggestions in the issue: hooking the refresh into cratis update. Reporting the drift where someone is already running init felt like the smaller, more predictable change, and it leaves update free of side effects on project files. Worth revisiting if the warning turns out not to be noticed.