feat(plugin): add /kbagent:setup one-command first-run setup

CLAUDE.md

@@ -295,14 +295,15 @@ Full author checklist: see `CONTRIBUTING.md` > "Releasing a beta (pre-release) v
 
 ## Claude Code Plugin
 
-The plugin lives here in `plugins/kbagent/` and is **published through `keboola/ai-kit`**. It exposes four AI surfaces: a CLI (`kbagent`), a skill (`kbagent`), a slash command (`/keboola`), and a specialist subagent (`keboola-expert`). All are namespaced under `kbagent:`.
+The plugin lives here in `plugins/kbagent/` and is **published through `keboola/ai-kit`**. It exposes: a CLI (`kbagent`), three skills (`kbagent`, `kbagent-cicd-migration`, `kbagent-promotion-pipeline`), three slash commands (`/kbagent:setup`, `/keboola`, `/kbagent:review`), and two specialist subagents (`keboola-expert`, `kbagent-pr-reviewer`). All are namespaced under `kbagent:`. `/kbagent:setup` is the documented one-command first-run path (install CLI -> connect project -> `doctor`); it runs in the main context and spawns no subagent.
 
 **Source here, publication there.** The source stays in this repo because four CI gates validate it against the live command tree (`make skill-gen` / `make skill-check`, `scripts/sync_version.py`, `scripts/check_command_sync.py`, `make version-check`) -- none of which exist in ai-kit. What ai-kit owns is the *catalogue*: its `keboola-claude-kit` marketplace carries an external `git-subdir` entry pointing at `plugins/kbagent` in this repo, pinned to a release tag. Keboola has ONE Claude Code marketplace, and it is not this one.
 
 **Install path users are told to use:**
 ```
 /plugin marketplace add keboola/ai-kit
 /plugin install kbagent@keboola-claude-kit
+/kbagent:setup
 ```
 
 **The sync mechanism** is the `ai-kit-marketplace` job in `.github/workflows/release-kbagent.yml`: on every stable tag it rewrites the kbagent entry's `version` + `source.ref` in ai-kit and opens a PR there (a PR, not a push -- ai-kit's evals must see it). It needs `secrets.AI_KIT_TOKEN` in the `release` environment. No-op safe: an entry already at this version opens nothing.
@@ -320,14 +321,20 @@ plugins/kbagent/
     CLAUDE.md                                          # Operational guidance for Claude Code main agents
   agents/
     keboola-expert.md                                  # Specialist subagent system prompt (HIGHEST silent-drift risk)
+    kbagent-pr-reviewer.md                             # Read-only PR-review subagent system prompt
   commands/
+    setup.md                                           # /kbagent:setup slash command (one-command first-run setup)
     keboola.md                                         # /keboola slash command
-  skills/kbagent/
-    SKILL.md                                           # Trigger rules + auto-generated decision table
-    references/
-      commands-reference.md                            # Per-command notes (hand-maintained)
-      gotchas.md                                       # Response parsing + (since vX.Y.Z) behavior log
-      <topic>-workflow.md                              # One file per workflow (workspace, branch, sync, ...)
+    review.md                                          # /kbagent:review slash command
+  skills/
+    kbagent/
+      SKILL.md                                         # Trigger rules + auto-generated decision table
+      references/
+        commands-reference.md                          # Per-command notes (hand-maintained)
+        gotchas.md                                     # Response parsing + (since vX.Y.Z) behavior log
+        <topic>-workflow.md                            # One file per workflow (workspace, branch, sync, ...)
+    kbagent-cicd-migration/                            # CI/CD migration skill
+    kbagent-promotion-pipeline/                        # Promotion-pipeline skill
 ```
 
 `SKILL.md` instructs Claude to run `kbagent context` as its first step, which dynamically loads the full CLI documentation. That keeps command *signatures* in sync automatically -- but it does **not** save the agent's tool-selection matrix, the gotchas log, or the version-gate examples in `keboola-expert.md`. Those are static and must be updated by hand whenever the CLI changes.

CONTRIBUTING.md

@@ -385,7 +385,7 @@ before the PR is mergeable.
 - [ ] **`plugins/kbagent/skills/kbagent/references/gotchas.md`** -- if the command's behavior is non-obvious, add an entry tagged with a version. In a feature PR that version is not known yet (the PR does not bump the version), so tag with the literal placeholder `(since vNEXT)` -- the release PR replaces every `vNEXT` with the version actually being released. Never guess a numeric version: `make version-gate-check` (per-PR CI) rejects any `(since vX.Y.Z)` whose version has no `changelog.py` entry. The version tag is **non-optional**; gotchas without versions are how AI agents end up recommending behavior that does not exist on older kbagent installs.
 - [ ] **`plugins/kbagent/skills/kbagent/references/<topic>-workflow.md`** -- create a new file if the command introduces a new workflow or topic area (existing examples: `workspace-workflow.md`, `branch-workflow.md`, `sync-workflow.md`, `storage-files-workflow.md`, `storage-types-workflow.md`). Single-command additions go into an existing workflow file.
 - [ ] **`plugins/kbagent/.claude-plugin/CLAUDE.md`** -- only update when the high-level delegation strategy changes (e.g. new "when NOT to delegate" cases). Most command additions do not touch this.
-- [ ] **`plugins/kbagent/commands/keboola.md`** -- only update if the `/keboola` slash-command UX changes. Most command additions do not touch this.
+- [ ] **`plugins/kbagent/commands/*.md`** -- only update if a slash-command UX changes (`/keboola`, `/kbagent:setup`, `/kbagent:review`). Most command additions do not touch these. Adding a *new* slash-command file has its own follow-through list -- see the [Plugin synchronization map](#plugin-synchronization-map) row.
 
 ### Tests (mandatory!)
 
@@ -466,7 +466,7 @@ release checklist below.
 | **`keboola/ai-kit` -> `.claude-plugin/marketplace.json`** (ANOTHER REPO) | Every stable release -- this is where the plugin is actually published (`keboola-claude-kit`, an external `git-subdir` entry pinned to the release tag). Automated: the `ai-kit-marketplace` job in `.github/workflows/release-kbagent.yml` rewrites `version` + `source.ref` and opens a PR against keboola/ai-kit. **Merging that PR is what ships the release to plugin users** -- a green release here does not move them | NO -- nothing in this repo can see ai-kit's catalogue. Check the opened PR after every release; if `secrets.AI_KIT_TOKEN` is missing or expired the job fails and no PR appears |
 | `plugins/kbagent/.claude-plugin/CLAUDE.md` | Changing delegation strategy / when-to-delegate rules | NO |
 | `plugins/kbagent/agents/keboola-expert.md` | New write/destructive command **group** (one matrix row per group, not per command -- file has a hard 70 000 B prompt budget); new minimum-version requirement (Rule 6 VERSION GATE); behavior change (gotchas) | NO -- **highest silent-drift risk** |
-| `plugins/kbagent/commands/keboola.md` | `/keboola` slash-command UX change (rare) | NO |
+| `plugins/kbagent/commands/*.md` (`setup.md`, `keboola.md`, `review.md`) | Slash-command UX change (rare). **Adding a new slash-command file** also needs: the surfaces list + "For Claude Code users" block in `plugins/kbagent/.claude-plugin/CLAUDE.md`, `skills/kbagent/SKILL.md` prose if it changes the documented setup/usage path, and the user-facing flow in `README.md`, `docs/TUTORIAL.md`, `commands/context.py` `AGENT_CONTEXT` and `install.sh`'s "Next steps" | NO -- no CI gate or test reads `commands/*.md` at all |
 | `plugins/kbagent/skills/kbagent/SKILL.md` -- table | Auto-generated by `make skill-gen` | YES (`make skill-check`; pre-commit auto-stages) |
 | `plugins/kbagent/skills/kbagent/SKILL.md` -- description / rules / workflow links | New topic area in `description` triggers; new workflow file added to bottom table | NO |
 | `plugins/kbagent/skills/kbagent/references/commands-reference.md` | Adding/removing/renaming commands; flag changes | NO |

README.md

@@ -100,8 +100,11 @@ This CLI is built AI-first. Every command outputs structured JSON (`--json`), er
 ```
 /plugin marketplace add keboola/ai-kit
 /plugin install kbagent@keboola-claude-kit
+/kbagent:setup
 ```
 
+`/kbagent:setup` is the whole rest of the setup in one command: it installs the `kbagent` CLI if you don't have it, connects a Keboola project (browser login, so there is no token to paste; on a headless host it falls back to an account login from the environment, then to a static token), and verifies the result with `kbagent doctor`. Every step is conditional, so re-running it after a partial setup just fills the gaps.
+
 Then either let the `kbagent` skill auto-trigger from natural prompts, or delegate explicitly with `/keboola <task>` -- the slash command spawns a `kbagent:keboola-expert` subagent with fresh context, hard rules (fresh fetch, dry-run first, prefer CLI over raw REST, version gate), and a JSON verification payload. See [docs/TUTORIAL.md §6](docs/TUTORIAL.md#6-using-the-agent-and-slash-commands).
 
 **Any other agent** -- just tell it to run `kbagent context` and it gets the full command reference.

docs/TUTORIAL.md

@@ -309,11 +309,24 @@ In Claude Code, run:
 ```
 /plugin marketplace add keboola/ai-kit
 /plugin install kbagent@keboola-claude-kit
+/kbagent:setup
 ```
 
 Claude Code clones the marketplace and drops the plugin into
 `~/.claude/plugins/cache/keboola-claude-kit/kbagent/<version>/`.
 
+`/kbagent:setup` then does everything else in one command: installs the
+`kbagent` CLI if it is missing (handling the installer's PATH caveat),
+connects a project via `kbagent auth login --register-projects` (browser
+login -- nothing to paste; on a headless host it drops to `kbagent auth
+login-password` when `KBC_LOGIN_EMAIL`/`KBC_LOGIN_PASSWORD` are already in
+the environment, and only then to a `kbagent project add` static token --
+which is also the direct answer for a surface no browser session can serve,
+since a password login yields the same restricted session),
+and finishes with `kbagent doctor`, interpreting the result for you. Each
+step runs only if its check fails, so it is safe to re-run at any point
+-- including if you already followed §1-§4 by hand.
+
 ### Verify
 
 Outside Claude Code:
@@ -337,6 +350,7 @@ you to run `/plugin update kbagent` in Claude Code.
 | Component | What it does |
 |---|---|
 | `kbagent` skill | Loaded into the main agent when it recognises Keboola-related prompts. 10 rules + a decision table mapping goals to commands. |
+| `/kbagent:setup` slash command | One-command first-run setup: install the CLI, connect a project, verify with `doctor`. Idempotent. |
 | `/keboola <task>` slash command | Explicitly delegates a Keboola task to the specialist subagent (see §6). |
 | `kbagent:keboola-expert` subagent | Fresh-context specialist with non-negotiable rules, tool matrix, inline gotchas, and a JSON verification payload output contract. |
 | Plugin-level `CLAUDE.md` | Instructs the main agent *when* to delegate vs. handle inline. |

install.sh

@@ -258,6 +258,10 @@ printf '  %s%s%s %s%s%s  %s  %s\n' "$GREEN" "$CHECK" "$RESET" "$BOLD" "$ver_str"
 printf '  %sno sudo required%s\n' "$DIM" "$RESET" >&2
 info ""
 printf '  %sNext steps%s\n' "$BOLD" "$RESET" >&2
+printf '    %sIn Claude Code:%s %s/kbagent:setup%s   %s# connect + verify in one command%s\n' "$DIM" "$RESET" "$BOLD" "$RESET" "$DIM" "$RESET" >&2
+printf '    %s(needs the plugin:%s %skbagent doctor%s %sprints the exact /plugin commands)%s\n' "$DIM" "$RESET" "$BOLD" "$RESET" "$DIM" "$RESET" >&2
+info ""
+printf '  %sOr do it by hand%s\n' "$BOLD" "$RESET" >&2
 printf '    %skbagent project add%s --project myproject \\\n' "$BOLD" "$RESET" >&2
 printf '        --url https://connection.keboola.com --token YOUR_TOKEN   %s# connect a project%s\n' "$DIM" "$RESET" >&2
 printf '    %skbagent --help%s     %s# see everything you can do%s\n' "$BOLD" "$RESET" "$DIM" "$RESET" >&2

plugins/kbagent/.claude-plugin/CLAUDE.md

@@ -1,9 +1,15 @@
 # kbagent plugin — operational guidance
 
-This plugin exposes a CLI (`kbagent`), a skill (`kbagent`), two slash
-commands (`/keboola`, `/kbagent:review`), and two specialist subagents
-(`keboola-expert`, `kbagent-pr-reviewer`). All are namespaced under
-`kbagent:`. The two subagents serve disjoint domains:
+This plugin exposes a CLI (`kbagent`), three skills (`kbagent`,
+`kbagent-cicd-migration`, `kbagent-promotion-pipeline`), three slash
+commands (`/kbagent:setup`, `/keboola`, `/kbagent:review`), and two
+specialist subagents (`keboola-expert`, `kbagent-pr-reviewer`). All are
+namespaced under `kbagent:`.
+
+`/kbagent:setup` is the first-run entry point: it installs the CLI if
+missing, connects a project, and verifies with `kbagent doctor` -- every
+step conditional, so it is safe to re-run. It runs in the main context and
+spawns no subagent. The two subagents serve disjoint domains:
 
 | Subagent | Use for | Slash command | Trigger phrases |
 |---|---|---|---|
@@ -124,7 +130,12 @@ When the subagent returns:
 
 ## For Claude Code users
 
-- Install the kbagent CLI: `uv tool install git+https://github.com/keboola/cli`
+- **Start here: run `/kbagent:setup`.** One command -- it installs the
+  kbagent CLI if it is missing, connects a Keboola project (browser
+  login, falling back to `auth login-password` from the environment and
+  then a static token, per the order above), and verifies the result with
+  `kbagent doctor`. Idempotent, so re-running it after a partial setup
+  only fills the gaps.
 - Initialize a project workspace: `kbagent init --from-global`
   (writes `.kbagent/config.json` whose first field is a `_warning`
   steering any LLM that reads the file away from direct REST calls)