/setup-gaia

name: setup-gaia
description: Single post-init onboarding command; detects situation, runs only owed phases; safe to re-run. --reconfigure rotates token and re-selects tools.
argument-hint: [--reconfigure]

Run this once after `/gaia-init`, and re-run it any time. `/setup-gaia` is the single onboarding command for a GAIA project. It detects the situation and runs only the phases this clone actually owes:

• **Per-machine work** every clone needs (tool installs, plugins, spec-kit runtime, statusline bit, `.env`).
• **GitHub repository provisioning** (create / adopt / manual, private by default).
• **CI wiring** when a repo exists and the runner is a repo admin.
• **Your per-developer audit-mode choice** (CI vs local at merge time).

It is safe for **any developer** to run at any time. A plain (no-flag) re-run on a fully provisioned project prints the already-configured line and mutates nothing: it never re-provisions the repo, rotates the token, or changes branch protection. Pass `--reconfigure` to rotate the bot token and re-select which tools run on cron.

The slash command name intentionally does NOT start with `gaia-` so it does not pollute the `/gaia` autocomplete namespace (those are reserved for the four user-invoked GAIA workflows).

Pre-flight: Worktree check

This command does per-machine and per-clone provisioning, writes `.gaia/local/setup-state.json`, and provisions the GitHub repository. If invoked from a linked worktree, reject hard: `gaia_refuse_if_worktree` (`.gaia/scripts/main-only-lib.sh`) asks the shared resolver which tree this is and refuses out loud, naming the main checkout, when the answer is a worktree.

Detection (run this first, before anything else):

. .gaia/scripts/main-only-lib.sh
gaia_refuse_if_worktree "/setup-gaia" || exit 1

If the detection does not fire, fall through to `## Argument parse` below.

Argument parse

Parse `$ARGUMENTS` for the `--reconfigure` flag. Cache the boolean as `RECONFIGURE`.

Phase 0: Prerequisites (every invocation, never skipped)

These run on every invocation and record no setup-state step. They sit outside the per-machine skip gate.

0a. Self-heal worktree symlinks

If this clone is being set up from a linked worktree (e.g. one created via `git worktree add` outside the Claude Code harness), the shared-state links that `.gaia/scripts/link-worktree.sh` creates may not exist yet: one symlink at `.gaia/local` pointing at the main checkout's, plus a link for each gitignored root `.env` file the main checkout holds. Run the self-heal:

.gaia/cli/gaia setup link-worktree

In a main checkout this is a no-op (exits 0 with `not a linked worktree`). In a linked worktree that lacks them it creates them; where a real file or directory already sits at one of those paths, it is backed up to `<path>.bak.<timestamp>` first, so nothing is clobbered.

If the command exits non-zero (e.g. Windows symlink permission failure), HALT and surface the error verbatim. The user must fix the underlying issue (typically: enable Windows Developer Mode) and re-run `/setup-gaia`.

0b. Ensure pnpm + node_modules

Tell the user: "Checking pnpm + node_modules…"

If `corepack` is available, run `corepack enable pnpm`. Otherwise `npm install -g pnpm`. If `node_modules/` does not exist at the project root, run `pnpm install`. `pnpm install` is fast on a clean clone and fast-no-op when up to date.

0c. GitHub CLI prerequisites (advisory)

Advisory only: warnings surface but do not halt setup, because a contributor may legitimately set up GAIA without `gh` wired up yet.

if ! command -v gh &>/dev/null; then
  echo "Warning: GitHub CLI ('gh') is not installed. The PR merge gate, /gaia-plan, and forensics workflows depend on it. Install: https://cli.github.com/" >&2
elif ! gh auth status &>/dev/null; then
  echo "Warning: GitHub CLI is not authenticated. Run: gh auth login" >&2
elif [ -f .github/workflows/forensics-triage.yml ] && gh repo view &>/dev/null; then
  .gaia/cli/gaia labels sync
fi

Surface every warning and the sync report verbatim, then continue. `gaia labels sync` reconciles this repo's labels against the registry for whichever audience and feature set it resolves to. `gaia-forensics` is a maintainer-audience entry, so an adopter's sync never creates it; an adopter files forensics reports upstream, never locally, regardless of what this step finds.

Phase 1: Detect situation

Classify the clone by reading state, gating on **file existence, not key presence**. Every input is optional; a missing file is a signal, not an error.

.gaia/cli/gaia setup status --json
.gaia/cli/gaia setup-ci status --json

• `.gaia/local/setup-state.json` (per-machine, gitignored). From `setup status --json`, cache `completed_at` and `completed_steps`.
• `.gaia/automation.json` (committed when present). From `setup-ci status --json`, cache `configured`, `setup_complete`, `setup_opted_out`, `nudge_dismissed`, `tools_enabled`.
• `.gaia/audit-ci.yml` (committed when present): gates Phase 5.

Then read the **repo / branch / push / required-check** state, not merely whether an `origin` remote exists:

.gaia/cli/gaia setup-ci detect-remote --json

Cache `found`, `host`, `owner`, `repo`. When `found` and `host == "github.com"`, probe the live repo state (each degrades to "absent" on a non-zero exit):

gh api "repos/<owner>/<repo>" --jq '.default_branch' 2>/dev/null                                              # repo exists + its default branch
gh api "repos/<owner>/<repo>/branches/<default-branch>" --jq '.name' 2>/dev/null                              # default branch has been pushed
gh api "repos/<owner>/<repo>/branches/<default-branch>/protection/required_status_checks" --jq '.contexts[]' 2>/dev/null  # GAIA-Audit registered?

Classify into one of: **fresh clone**, **first adopter**, **partial re-run**, **provisioned**, or **admin-teammate-on-unwired-clone**.

• A clone with a gith