D9: Curated baked-agent set

[Teagan42]

Part of #2

D9 — Curated baked-agent set

Labels: wayfinder:grilling status:closed
Blocked by: D5 (closed)
Blocks: D6, D8

Resolution

Baked agent set for v1:

Agent	Install	Verified package name?
Claude Code	npm install -g @anthropic-ai/claude-code	Yes
OpenAI Codex CLI	npm install -g @openai/codex	Verify at implementation — confirm current npm name
Aider	pip3 install --prefix=/usr/local aider-chat	Yes
Gemini CLI	npm install -g @google/gemini-cli	Verify at implementation — confirm current npm name
OpenCode	npm install -g opencode-ai (or @sst/opencode — verify)	Verify at implementation — pick the correct/current package

Two agents flagged for package-name verification at implementation time; if any turns out to be a moving target or unpublished, D6's build step should fail loudly (not silently skip) so it graduates back to a decision rather than silently shipping a broken image.

Version-pin strategy: Float on @latest at build time. Image digest is the reproducibility anchor; agents move too fast to hand-pin. Every push-to-main and every tagged build refreshes them. The GHCR workflow (D7) already publishes on both triggers, so users who want the newest agents pull :edge or the latest tag; users who need reproducibility pin to a specific image digest.

Discoverability — three channels, all in scope:

1. README / docs section under docs/docker.md (owned by D8) — flat list with a link to each agent's homepage.
2. OCI image labels on the final image — set at build time in the Dockerfile:
   • chartr.agents=claude-code,codex,aider,gemini,opencode (comma-separated, kebab-case slugs).
   • chartr.agents.versions — optional; populated by a build step that runs <agent> --version for each and joins them. Nice-to-have; if it complicates the build, drop it.
3. chartr agents list-baked subcommand — reads the label off its own container's OCI metadata (or, simpler and more portable: reads an /etc/chartr/baked-agents file written by the Dockerfile at the same time as the OCI label). Small Go addition to cmd/chartr (or a subcommand under a new agents verb). Non-container invocations print an empty list. Scope note: this is the one non-packaging Go change D9 introduces; keep it small.

Deprecation policy: announce in release notes, keep for one minor version, then remove. If a baked agent becomes unmaintained or its upstream @latest starts failing the build:

• Build failure is the trigger — implementers must not || true the install steps.
• Release notes for the current minor call the deprecation out.
• The next minor removes the install line and the OCI label entry.

Downstream impact:

• D6 (Dockerfile) — install stage now has five concrete install commands + one label-writing step + optional /etc/chartr/baked-agents write. Cache-mount the npm+pip layers since they dominate build time and change only when @latest moves.
• D7 (GHCR workflow) — no matrix expansion; --pull on the base image plus install-at-@latest means every scheduled/tag/main build gets refreshed agents. Note in the workflow that scheduled rebuilds (weekly cron) would let long-lived tags refresh their agents without a code push — worth mentioning but not required for v1.
• D8 (compose + docs) — README/docs section listing all five agents; troubleshooting entry: "an agent I need isn't baked in" → /opt/agents bind-mount pattern from D5.
• New Go work — small: chartr agents list-baked subcommand + a helper to read /etc/chartr/baked-agents. This is the only non-packaging code change surfaced by this ticket.

Question

D5 committed to baking a curated set of agents into the image and prepending /opt/agents for operator extensions. Decide which agents make the initial cut:

• Claude Code (@anthropic-ai/claude-code via npm) — presumably in; confirm and pin version-management strategy (float on @latest at build time? pin to a known-good?).
• Codex (@openai/codex or its actual npm name) — in or out for v1?
• Aider (aider-chat via pip) — in or out?
• Continue CLI — in or out?
• Anything else — Cursor CLI, Sourcegraph Cody, etc.?

Also decide:

• Version-pin strategy: rebuild-on-agent-release (fast-moving upstream) vs. tag-pinned (chartr image versions bundle known-good agent versions)?
• How the set is discoverable to users: docker run chartr:latest chartr agents list-baked? Documented in README? Both?
• Removal policy: if a baked agent becomes unmaintained or actively broken, what's the deprecation surface?

Deliverable: the exact list of baked agents + their install commands (npm install line, pip install line), plus the version strategy. D6 consumes this verbatim in its Dockerfile install stage.