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

[claude]

Requested by David Esner · Slack thread

Before / After

Today, a new user follows five separate steps across two different places, in the right order, from the docs at keboola.com/cli: generate a Storage API token in the UI → open Claude Code → run the curl … install.sh | sh one-liner in a terminal → kbagent project add --project X --url Y --token … → kbagent doctor → back in Claude Code, /plugin marketplace add keboola/cli and /plugin install kbagent@keboola-agent-cli. Nothing in the repo chains those; kbagent doctor detects the missing plugin but deliberately does not fix it.

After this PR, the documented flow is: install the plugin, then run one command.

/plugin marketplace add keboola/cli
/plugin install kbagent@keboola-agent-cli
/kbagent:setup

/kbagent:setup does the rest — and there is no token to generate or paste on the default path.

What it does

Adds one new plugin slash command, /kbagent:setup, that runs first-time setup end to end — install the CLI if missing, connect a project, verify — with every step conditional on a check, so it is idempotent and safe to re-run on a half-finished setup.

How

plugins/kbagent/commands/setup.md is markdown instructions for the agent, in the same shape as the existing keboola.md / review.md (same frontmatter keys, ## Behavior numbered steps, ## Examples, a closing rationale section). It orchestrates existing, already-tested verbs — no new CLI surface, no new code path:

1. kbagent --json version → if the CLI is absent, run this repo's own install.sh, handling the installer's documented PATH caveat (kbagent is on PATH for the installer's own process only; source $HOME/.local/bin/env or a new shell). If kbagent.install_channel is present, that is a standalone/packaged build — the command respects it and points at upgrade_command / upgrade_hint instead of installing a second kbagent over the top.
2. kbagent --json project list → if a project is already connected, name the aliases and skip to verification. Never re-registers or overwrites an existing project or alias.
3. Otherwise kbagent --json auth login --register-projects — browser PKCE with the automatic device-code fallback, so nothing to paste. It reads session_unsupported_features off the result (canonical list: SESSION_UNSUPPORTED_FEATURES in services/_auth_registration.py) and relays it rather than hand-listing it, and falls back to kbagent --json project add --project '<ALIAS>' --url <STACK_URL> when the user needs one of those surfaces or there is no browser (headless, container, CI). The fallback never passes --token on a command line: either KBC_TOKEN is already in the environment, or the command is handed to the user to run in their own terminal, because project add's hidden token prompt needs a real TTY that a tool-run shell does not have.
4. kbagent --json doctor, interpreted for the user — including the claude_plugin check (pass / version drift → /plugin update kbagent; warn → print the two /plugin lines; skip → Claude Code not detected).
5. A short "you're set up, here's what to try" close.

The body encodes the rules explicitly: never print or persist a token, --json for anything parsed, don't re-run a step that already passes, and when a step genuinely needs a human (browser login), say so plainly instead of guessing.

Flag placement was verified against the live CLI — --json is a root-callback option, so it goes before the subcommand (kbagent --json project list, not project list --json). All four invocations in the file were run locally.

Doc sync (CLAUDE.md convention #17 / CONTRIBUTING.md "Plugin synchronization map")

None of these have a CI freshness check, so they are the silent-failure surfaces for this change:

• plugins/kbagent/.claude-plugin/CLAUDE.md — surfaces list (two slash commands → three) and the "For Claude Code users" block now leads with /kbagent:setup.
• plugins/kbagent/skills/kbagent/SKILL.md — the prose "First-time setup" section points at /kbagent:setup as the one-command path, keeps the manual sequence below it for a plain shell or another agent, and swaps its stale uv tool install git+… line for the install.sh one-liner plus the PATH caveat. The CI-checked auto-generated decision table was not touched (make skill-check regenerates it clean).
• README.md — the Claude Code plugin block is now the two /plugin lines plus /kbagent:setup.
• docs/TUTORIAL.md — §5 install flow and the "What the plugin ships" component table.
• install.sh — the printed "Next steps" now leads with /kbagent:setup for Claude Code users and keeps every existing explicit command under "Or do it by hand", so nothing regresses for people not in Claude Code.
• src/keboola_agent_cli/commands/context.py (AGENT_CONTEXT) — the "Claude Code Plugin" section, since this is the primary reference agents load at session start.
• CLAUDE.md — the plugin structure tree and surfaces sentence were already stale (still claimed one slash command and one subagent); corrected while adding setup.md.
• CONTRIBUTING.md — the sync-map row for plugins/kbagent/commands/keboola.md was stale for the same reason. Widened to commands/*.md and given the explicit follow-through list for adding a new slash-command file, which the map has never had (/kbagent:review was added without it).

No changelog entry: pyproject.toml's version is unchanged, and CONTRIBUTING defines a release as a version bump. No new tests: per CONTRIBUTING, the mandatory test checklist is scoped to new CLI commands (service / CLI / E2E layers), and no CI gate or test reads plugins/kbagent/commands/*.md at all — tests/test_skill_frontmatter.py targets skills/kbagent/SKILL.md exclusively. Nothing enumerates plugin command files, so there was no such test to extend. Flagging that gap rather than papering over it.

Checks run

Check	Result
make lint (ruff check src/ tests/ scripts/)	pass
make format-check (ruff format . --check)	pass — 433 files already formatted
make skill-check	pass (post-commit; the generator regenerates SKILL.md byte-identical)
make version-check	pass
make command-sync-check	pass — 261 commands registered + documented
make check-error-codes	pass
make check-sentinel-guards	pass
make loc-check	pass (pre-existing soft-ceiling warnings only, none in files this PR touches)
make typecheck (ty)	0 errors
make test	5688 passed, 13 skipped, 2 failed -- tests/test_config_store.py::TestPermissionDenied::{test_save_to_readonly_directory,test_load_unreadable_config_file}. Both are environmental and pre-existing: the sandbox runs as uid 0, so chmod 0o000 does not deny root and the expected ConfigError never raises. Verified identical on main at d8f7a7b with this branch's changes absent. This diff touches no config-store code.
bash -n install.sh	pass
Live CLI: kbagent --json version / project list / doctor	all verified working with the documented flag placement
make test-e2e	not run — needs E2E_API_TOKEN + E2E_URL against a real project; no CLI behavior changed
make changelog-check	not run -- requires the gh binary, which is absent from this environment. It is local/release-time only and is deliberately not part of CI's per-PR check job.

Not in this PR

• A kbagent setup Python CLI subcommand for agents that are not Claude Code. That is a larger change with real CI follow-through (permissions.py OPERATION_REGISTRY, commands/context.py, commands-reference.md, CLAUDE.md ## All CLI Commands, generate_skill.py SKIP_COMMANDS, plus service/CLI/E2E tests, all gated by scripts/check_command_sync.py) and deserves its own review. A slash command also has a chicken-and-egg limit worth naming: it only helps someone who already installed the plugin, so it cannot cover the /plugin step for the person who most needs it — it can only detect and explain it.
• doctor was not changed to auto-fix anything. doctor --fix was deliberately removed in 0.85.0; reopening that is out of scope here.
• The public page at keboola.com/cli lives outside this repo and still needs updating to the new two-step flow. This PR only fixes the in-repo docs.

Open question for reviewers

The repo's own auth guidance forks, and this command had to pick a side.

• plugins/kbagent/.claude-plugin/CLAUDE.md:93-100 says a static Storage token is not automatically the answer for an unattended context, and prefers kbagent auth login-password (0.84.0+) when account credentials exist.
• plugins/kbagent/agents/keboola-expert.md:74 says the opposite: refuse session auth and point at project add --token.

/kbagent:setup currently prefers browser auth login --register-projects with a project add (hidden-prompt / KBC_TOKEN) fallback — chosen because the product goal is explicitly "no token to paste", and because login-password needs email + password + TOTP that a first-time user is unlikely to have staged. But that is a third position, not a reconciliation. Two things reviewers should decide:

1. Should the fallback prefer auth login-password over project add when KBC_LOGIN_EMAIL / KBC_LOGIN_PASSWORD / KBC_LOGIN_TOTP_SECRET are present in the environment?
2. Whichever way that goes, keboola-expert.md:74 and .claude-plugin/CLAUDE.md:93-100 should be brought into agreement — they currently give an agent contradictory instructions, independent of this PR. I did not touch either, since picking a winner is a product call and keboola-expert.md is the highest silent-drift-risk file in the repo.

---

Generated by Claude Code

[claude]

Merge-order note vs #627 (which moves the plugin's marketplace listing to keboola/ai-kit / keboola-claude-kit).

This PR overlaps #627 in README.md, docs/TUTORIAL.md, src/keboola_agent_cli/commands/context.py and CLAUDE.md. Whichever merges second should, in each conflicted /plugin fence, keep #627's two /plugin lines plus this PR's /kbagent:setup line — the three belong together. In CLAUDE.md, keep #627's rewritten marketplace section with this PR's corrected surfaces list (three slash commands, two subagents). Three more files are touched by both at adjacent hunks and may need a trivial resolution: CONTRIBUTING.md, plugins/kbagent/.claude-plugin/CLAUDE.md, plugins/kbagent/skills/kbagent/SKILL.md.

As of this push, install.sh no longer hardcodes marketplace names — the next-steps hint defers to kbagent doctor, which prints the current /plugin commands and is itself updated by #627, so it stays correct under either merge order.

---

Generated by Claude Code