Module onboard 

firstpass onboard — fully agentic onboarding (SPEC §0.2: the primary user is an agent, and the human deserves the same one-command experience). Detect the environment, plan the exact steps, execute them under --apply, and verify end-to-end — so “install firstpass and route my agent through it” is one command, not a doc to follow.

Structure: detect and plan are pure (injected lookups, no I/O) so the decision logic is unit-tested offline; execute performs the side effects (spawn proxy, append one marked line to the shell rc, probe /healthz) and is deliberately thin. Without --apply the command is a dry run that prints the plan — agentic, but never surprising.

Structs

ConfigPlan

A config the caller wants written: where it goes and the answers behind it. None means the step is skipped — either a firstpass.toml is already there or the user opted out.

Environment

What onboarding discovered about this machine. Everything is injected-lookup driven so tests construct arbitrary environments without touching the real one.

LadderChoice

The three answers that decide a starting ladder. Everything else in the generated file follows from these, which is why onboarding asks exactly three questions and not a wizard’s worth.

Enums

Provider

Which provider the ladder opens on. Only anthropic and openai are built into the provider registry; the other two must carry a [[provider]] block or the config will not resolve.

Shape

What the model is being asked to produce. This is what actually picks the gate — the whole product rests on gating the real output, so it is the one question worth asking carefully.

Step

One onboarding step: what it is, and whether it’s already satisfied.

Constants

RC_MARKER

Marker comment appended with the env line so re-running onboard is idempotent and offboarding is greppable.

Functions

detect

Detect the environment via injected lookups: env(key) for env vars, on_path(bin) for PATH probes, healthz() for a live proxy probe. Pure decision logic; all I/O behind the closures.

execute

Execute the side-effectful steps. Returns a human report. Failures are reported per step — onboarding never half-dies silently.

offboard

firstpass offboard — the exact mirror of onboard: strip the marked line from every candidate rc file, stop the proxy onboard started (pidfile), and print the one command for this shell. Fully idempotent; reports what it found either way.

offboard_rc

Remove every marked onboard line from rc. Returns whether anything was removed. Only lines carrying RC_MARKER are touched — nothing else in the user’s rc is ever rewritten.

plan

Build the ordered plan for this environment. rc_already_wired is whether the rc file already carries the marker line (checked by the caller, injected here to stay pure). config is the routing file to generate, if any — it is written before the proxy starts so the child can be handed it, since a config the proxy never loads is worse than no config at all.

presets_js

Render every answer combination as a JavaScript asset for the documentation site.

rc_wired

Whether the rc file already carries the onboard marker (idempotence check for plan).

render

Render the plan for the dry run (default) or as the running commentary under --apply.

render_config

Render a complete, runnable firstpass.toml for these answers — including the [[provider]] and [[gate]] blocks the choice requires. Emitting a fragment would be worse than emitting nothing: only anthropic/openai are built-in providers and only non-empty/json-valid are built-in gates, so anything else must be declared here or the file will not resolve.

shell_wiring

The shell-dialect line that routes agents through the proxy, plus the rc file it belongs in. home is injected so tests never touch a real home directory.