add-source (v1)

Adding an agent CLI is not a single-file change — it spans pixtuoid-core (decoder + registry + tests), the pixtuoid binary (runtime wiring + install target + badge hue), and the site manifest. Several steps have test teeth that only just preflight's FULL run catches, not the targeted source/install suites — so an agent that stops at "it compiles" ships a red PR.

When to use

• "Add support for <CLI>" / "integrate " / "add a source for X".
• A new transcript-bearing OR hook-only coding CLI should show up as sprites.

The authoritative checklist

The complete, current step list lives in crates/pixtuoid-core/CLAUDE.md ("multi-source decoding" / "Adding a new agent CLI") — read it first; it is the source of truth and stays current. The Copilot-format summary is .github/prompts/add-source.prompt.md. Before you start, decide transcript-bearing vs hook-only (invariant #3): a hook-only CLI (Reasonix/CodeWhale/opencode/Cursor) sets transcript: None, skips the runtime wiring + Source impl, and ships a hook.custom decoder + an install/ target instead.

The test-teeth steps agents miss

These are the ones with a failing test attached — do NOT stop before them:

• site/src/sources.json row — a manifest bridge test fails until it exists; then just gen-readme to sync the README. (CLAUDE.md step 5.)
• Per-source badge hue — a Theme::source (SourceColors) field in EVERY theme file + a dashboard_line match arm; two guard tests fail otherwise. (CLAUDE.md step 7.)
• pub fn <cli>_home() if the CLI has a custom config root — one fn honoring its *_HOME precedence, called from BOTH the watcher's default_paths() AND the installer's default_config_path() so they can't disagree. (CLAUDE.md step 6.)
• A captured fixture under tests/sources/fixtures/<name>/<scenario>/ exercising the SessionStart hook — the conformance test forces one, and its one-AgentId assertion guards against the reason-field ghost.

(The exact test names + full step list are in crates/pixtuoid-core/CLAUDE.md "Adding a new agent CLI" and add-source.prompt.md — this skill headlines the teeth, those own the specifics.)

Finish

• Wire it into runtime/driver.rs::build_source_set (transcript-bearing only — the one construction site, called by run_async). This step HAS teeth: build_source_set_wires_every_transcript_bearing_source_plus_the_hook_router (driver.rs) FAILS for a registered source left unwired, so just preflight catches the miss — don't make it wait that long.
• Capture the real wire shape and set verified_version ("unknown" until a byte-real capture anchors it). Drift-watch it (see the add-a-CLI list's drift-watch note in crates/pixtuoid-core/CLAUDE.md).
• just gen-contract only if you touched the --json/SourceStatus/OutcomeRow SHAPE (adding a row doesn't).
• just preflight before the PR, then run the two-lens-review skill.