Onboarding

Run the first-use conductor, install Engineer Kit, and verify your coding runtime.

Onboarding is complete when your chosen coding assistant recognizes an Engineer Kit Skill in a project you control.

Before you start

You need:

ak on your PATH — see Installation.
A supported coding runtime installed and signed in with its own provider.
An AgentKit account with access to Engineer Kit.
A test project where you can add runtime configuration.

AgentKit authentication grants access to licensed Kits. It does not sign Claude Code, Codex, Cursor, DeepSeek Harness, Grok, Pi, or Oh My Pi in to their providers, and runtime login does not grant AgentKit Kit access.

Run onboarding

Change to the project where you want the Kit, then run the conductor:

cd /path/to/project
ak onboard

ak onboard runs one state-aware pipeline:

Stage	Behavior
1. Setup	When `adapters.enabled` or `kit.default` is missing, runs the TTY wizard or writes scripted defaults.
2. Channel	Fills both `updates.channel` and `kit.channel`.
3. Scope	Resolves project or global scope before asking for login.
4. Login	Skips a renewable CLI session; otherwise offers email OTP or a user API key on a TTY.
5. Kit	Skips an existing install receipt; otherwise confirms kit and runtime on a TTY, then installs.

Completed steps are reported as skipped, so you can rerun the command after a partial or interrupted first use. --yes accepts confirmation prompts but never becomes --force.

Choose the Kit, runtime, and release channel explicitly when you want a repeatable result:

ak onboard --kit engineer --target codex --channel <channel>

Replace <channel> with the channel selected in the docs header. Channel selection prioritizes an explicit stable or beta, a published -beta CLI, a persisted kit.channel, then version inference (beta for a Beta CLI; stable for development and Stable builds). An unsupported value such as nightly exits 2 without changing config.

Kit selection falls back from --kit to kit.default, then engineer; a configured default of none also resolves to engineer. Target selection falls back from --target to the first enabled adapter. On a TTY, onboard confirms both values before install unless --kit or --target already locked that axis. Non-interactive mode keeps those defaults and exits 2 if no target can be resolved.

Every directory except your user home is valid project scope, including a new, empty directory without .git or .agentkit/ownership.json. Running from your home directory is not project scope. Onboard warns, tells you to change into a project, and exits 2. Pass --project-dir or --global instead of expecting a TTY offer to install globally:

ak onboard --global --kit engineer --target codex --channel <channel>

Location	Behavior
Any directory except the user home	Uses that directory as project scope and installs the Kit there.
User home on a TTY	Warns that home is not a project, prints the next command, and exits `2`. It never writes project Kit files into the home directory.
User home without a TTY	Exits `2` before login and tells you to change directories or use `--global`.
`--global`	Skips the project check and installs the user-wide Kit, including when run from home.
`--project-dir <path>`	Uses that path instead of the current directory; the user home still requires `--global`.

Stage	New user	Returning user
Setup	Runs setup	Skips when basic config exists
Login	Offers email OTP or user API key	Skips when the session can renew
Kit	Installs the selected route	Skips an existing receipt; if only the receipt is missing, installs only the Kit

Email OTP is the default TTY login method. --email <address> bypasses the method picker and goes directly to OTP. An interactive install authentication failure triggers login and one installation retry.

Use onboarding in automation

Non-interactive onboard cannot collect a new credential. Create the CLI session first, then pass every choice the job depends on:

ak login --api-key ak_live_... --no-interactive
ak onboard \
  --no-interactive \
  --yes \
  --project-dir /path/to/project \
  --kit engineer \
  --target codex \
  --channel <channel>

Without a usable session, non-interactive onboard exits 2 instead of opening a login prompt. When basic setup is missing, scripted setup uses --kit or engineer, --target or claude-code, and disables telemetry. Keep real API keys, OTPs, license keys, session files, and provider credentials out of source control, screenshots, diagnostics, and shared shell history.

When to use the individual commands

You normally do not need to run setup, login, and Kit installation separately during first use. Use their standalone forms when you need to change or recover one layer without replaying the whole conductor:

Command	Use it when
`ak setup`	Change adapters, the default Kit, telemetry, or advanced provider/model preferences after onboarding
`ak login`	Switch AgentKit accounts, rotate a user API key, recover authentication, or create a session before automation
`ak kit init`	Install a specific Kit route after configuration and authentication are already known-good
`ak init`	Ask AgentKit to adopt and track an existing project as a whole, including its ownership manifest and custom docs/plan paths

These commands remain part of the CLI contract, but they are supporting paths, not extra onboarding steps.

Verify the result

Confirm the AgentKit account, Kit grant, and local installation health:

ak whoami
ak licenses
ak doctor --exit-on-fail

ak whoami exits 0 even when it reports an unauthenticated state. Scripts must inspect the result rather than treating exit code zero as proof of login. Continue only when ak licenses lists Engineer Kit and doctor reports no blocking failure.

Restart the assistant or open a new session so it reloads the installed content, then invoke one Skill:

/ak:cook Add a health-check endpoint

$ak:cook Add a health-check endpoint

For Cursor, Grok Build, and Pi, use that runtime's current Skill discovery and invocation surface. For DeepSeek Harness, use its current discovery surface or the one-shot local dispatch route ak run engineer/scout --target dsh; do not put secrets in that dispatch prompt because it is passed as a process argument. Onboarding is complete when the assistant recognizes the Skill, reads the request, and begins its workflow in the current project.

Recovery and common failures

No AgentKit session: rerun ak onboard on a TTY, or use an explicit ak login method.
Engineer Kit is absent from ak licenses: sign in with the account that owns the Kit. Reinstalling cannot create a missing grant.
Runtime missing or signed out: install or sign in to that runtime with its provider account, then rerun onboard.
Skill not recognized: confirm the install summary names the intended target, restart the assistant, and run ak doctor --exit-on-fail before reinstalling.
channel_drift warning: align both channels with ak onboard --channel stable or ak onboard --channel beta.
Occupied runtime files: on a TTY, onboard can ask to overwrite AgentKit collision paths and retry once with --force. Unrelated custom files stay. --yes and non-interactive mode never auto-force; cancel exits 3.

For detailed Kit scope, target compatibility, refresh, uninstall, and recovery behavior, continue with Installing Kits. Otherwise, go to the focused Quickstart.