/setup

description: First-run wizard — pick AI providers, walk through CLI install + auth, verify each, save settings
allowed-tools: Bash(node:*), Bash(npm:*), AskUserQuestion

You are walking the user through first-time setup of `@ai-plugins-cc/ai`. Be efficient and decisive — they want to be done, not lectured.

Step 0: read current state

Before running the bash probe, create a task so the user sees a friendly progress spinner instead of a blank "thinking" pause:

TaskCreate(subject="Probe AI providers", activeForm="Probing AI providers")
TaskUpdate(taskId=<id>, status="in_progress")

Then run:

node "${CLAUDE_PLUGIN_ROOT}/scripts/ai-companion.mjs" setup

Mark the task `completed` once the bash returns. Use the same TaskCreate pattern for any other long-running probe step (CLI installs, codex-update). Keep `activeForm` short and concrete — it shows in the spinner area as the user waits.

The non-JSON form prints a 5-7 line human-readable summary, one line per provider. Format: `- <id> [<tags>] (enabled|disabled): <detail>`. The `<detail>` field is one of:

• `ready` — provider is fully set up
• `CLI not on PATH` — provider's CLI binary needs `npm install -g ...`
• `no auth credential detected` — CLI is installed but no key/login is set
• `Sibling plugin "<id>" is not installed. Run /plugin install ...` — only fires if the umbrella's bundled fallback is also unavailable (rare)
• Anything else — drill in with `verify --provider=<id> --json` for structured detail

If every enabled provider's `<detail>` is `ready`, tell the user setup is already complete and offer `/ai:settings` if they want to change anything. Stop.

When you need structured fields (`available`, `loggedIn`, `pluginInstalled`, raw probe output) for a specific provider during the per-provider walkthrough, run `node "${CLAUDE_PLUGIN_ROOT}/scripts/ai-companion.mjs" verify --provider=<id> --json` — that returns the single-provider blob without dumping all three. Avoid `setup --json` unless you genuinely need the full multi-provider snapshot; its output is ~100 lines and clutters the chat.

Step 1: ask which providers they want

Use `AskUserQuestion` once with `multiSelect: true`. Options are the entries in `knownProviders`. Pre-select any provider whose probe shows `ready: true`. Suggested copy:

> Which AI providers do you want to enable? Pick any combination — you can change this later with `/ai:settings`.

Append `(Recommended)` to **every** option that has a viable default auth path on the local machine — that's all three of `gemini`, `grok`, and `codex`. They each install in seconds and have a clear default credential (Google API key / OAuth, xAI API key, ChatGPT login). Don't single one out as "the" recommendation — the umbrella works best with all three, and the user is the only one who knows which providers they pay for.

For each selected provider, follow the matching block below. Run them in the order the user picked.

Step 2: per-provider walk-through

For each selected provider:

> **Important:** the umbrella plugin (`ai@ai-plugins-cc`) ships bundled fallback runtimes for Gemini and Grok at `sibling-fallback/<provider>/`. **Do not** tell the user to `/plugin install gemini@ai-plugins-cc` or `/plugin install grok@ai-plugins-cc` as a prerequisite — `resolveSiblingCompanionPath` will use the bundled fallback automatically when the per-provider Claude plugin isn't installed. The per-provider plugins are only needed if the user wants the dedicated `/gemini:*` / `/grok:*` slash commands; the `/ai:*` flow works with just the umbrella.

Gemini

If `available: false`, the user already opted in by selecting Gemini — don't ask again, just install:

• Tell them once: *"Installing Gemini CLI (`npm install -g @google/gemini-cli`)…"*
• Run `npm install -g @google/gemini-cli` via Bash.
• If install fails (e.g. `EACCES` from a system-managed Node), surface the raw error verbatim and stop this provider's flow with a hint that they may need to fix npm prefix permissions or use a Node version manager.
• Re-run `verify --provider=gemini --json` after install.

If `loggedIn: false`, use `AskUserQuestion` (single choice) to pick the auth method:

• **"Sign in with my Google account (recommended)"** — uses the Gemini CLI's OAuth flow with your personal Google account; opens a browser.
• **"Set `GEMINI_API_KEY` from Google AI Studio"** — paste-an-API-key.
• **"Use Vertex AI via `gcloud auth application-default login`"** — for users on Google Cloud.
• **"Skip — I'll authenticate later"** — leaves the provider enabled but not ready.

Auth-path actions:

• **OAuth (Google account)**: run `gemini auth login` via Bash. The CLI will print a URL or open a browser; tell the user to complete the flow there. The Bash subprocess blocks until the login completes — that's expected. Re-run verify after it returns. (Note: `gemini auth login` is the developer-CLI auth subcommand, distinct from the web app's sign-in at gemini.google.com.)
• **API key**: ask for the key with `AskUserQuestion` (single text answer, treat the response as sensitive — do not echo). Tell the user to `export GEMINI_API_KEY=…` for the current session. Only modify their shell config if they explicitly request persistence — and when they do, write to `~/.zshenv` (zsh) or `~/.bash_profile` (bash), **not** `~/.zshrc`. The `/ai:*` commands spawn non-interactive subprocesses; `~/.zshrc` is sourced for interactive shells only, so a key persisted there won't be visible to dispatch.
• **Vertex**: instruct them to run `gcloud auth application-default login` in another terminal, come back, and acknowledge.
• Re-run `verify --provider=gemini --json` after each path completes.

Grok

Same shape — the user already opted in by selecting Grok, so install without re-asking.

If `available: false`:

• Tell them once: *"Installing Grok CLI (`npm install -g @vibe-kit/grok-cli`)…"*
• Run `npm install -g @vibe-kit/grok-cli` via Bash. This is a Node-compatible CL