keboola-cli 0.100.4__tar.gz → 1.0.0__tar.gz

keboola_cli-1.0.0/CLAUDE.md

@@ -0,0 +1,1710 @@
+# CLAUDE.md / AGENTS.md - Development Context for AI Coding Agents
+
+> **Contributors**: Read [CONTRIBUTING.md](CONTRIBUTING.md) before submitting a PR.
+> It covers coding style, security principles, Keboola API best practices,
+> and the full checklist for adding new CLI commands.
+
+## Build and Run
+
+```bash
+# Install in development mode (editable)
+uv pip install -e ".[dev]"
+
+# Or install dependencies only
+uv sync
+
+# Run the CLI
+kbagent --help
+uv run kbagent --help
+
+# Run a specific command
+kbagent --json project list
+```
+
+A `Makefile` provides shortcuts for common tasks. Run `make help` to see all targets, or use:
+
+```bash
+make install        # install in dev mode
+make test           # run all tests
+make lint           # run ruff linter
+make format         # format code
+make check          # lint + format-check + changelog-check + test (CI-like)
+make hooks          # install pre-commit hook
+make clean          # remove caches and build artifacts
+```
+
+## Testing
+
+```bash
+# Run all tests
+uv run pytest tests/ -v
+
+# Run a specific test file
+uv run pytest tests/test_cli.py -v
+
+# Run a specific test class or method
+uv run pytest tests/test_cli.py::TestProjectAdd -v
+uv run pytest tests/test_cli.py::TestProjectAdd::test_project_add_success_json -v
+```
+
+## Project Structure
+
+```
+src/keboola_agent_cli/
+  __init__.py           # PUBLIC SDK ENTRYPOINT + __version__. Re-exports the importable
+                        #   facade (Client, Files, FileEntry) and the typed result models
+                        #   (JobResult, QueryResult, UploadTableResult, SyncPushResult,
+                        #   ConfigDetailResult, CloneResult, JobIdempotencyStore). Everything
+                        #   in __all__ is committed public API (semver). __version__ is read
+                        #   at runtime via importlib.metadata; never hardcoded. See docs/sdk.md.
+  lib.py                # In-process SDK facade: Client (query/run_job/config_detail/
+                        #   upload_table + .files + .raw) over KeboolaClient. Stateless,
+                        #   config-dir-free, token passed at construction (issue #415). See docs/sdk.md.
+  result_models.py      # Typed pydantic return contracts for the SDK facade (extra="allow",
+                        #   populate_by_name); the semver-stable shapes consumers type against (issue #428).
+  py.typed              # PEP 561 marker -- ships in the wheel so downstream mypy/ty treat the SDK as typed.
+  __main__.py           # python -m support
+  cli.py                # Typer root app, global options, subcommand wiring
+  constants.py          # Shared constants + dynamic APP_NAME resolution (retry params, timeouts, defaults)
+  json_utils.py         # Deep-merge, set_nested_value, compute_diff utilities
+  models.py             # Pydantic models shared across layers
+  effective_branch.py   # resolve_branch(): the ONLY code that applies the `branch use` active branch;
+                        #   records project + branch for the `Target:` line / `targets` key (#766)
+  project_ref.py        # resolve_project_ref(): a project ID given where an alias is expected -> the
+                        #   alias (CLI-22); applied by commands/_project_ref.py and serve's dependency
+  output.py             # OutputFormatter: JSON vs Rich dual-mode output
+  root_command.py       # RootGroup: one --json document per exit, root flags after the subcommand,
+                        #   -h, the repeated-option check (#791 O1/O7/A6/H5)
+  errors.py             # KeboolaApiError, ConfigError, ErrorCode enum, mask_token()
+  config_store.py       # JSON persistence for config.json (0600 permissions)
+  permissions.py        # PermissionEngine (--deny-writes / --deny-destructive session firewall)
+  changelog.py          # Version changelog data + helpers (update on every release)
+  auto_update.py        # Auto-update on startup + "What's new" display
+
+  # LAYER 3 -- HTTP clients (all inherit BaseHttpClient in http_base.py:
+  #            shared 429/5xx retry + exponential backoff)
+  http_base.py          # BaseHttpClient - shared retry/backoff + common HTTP infra
+  client/               # Storage API + Queue API package (X-StorageApi-Token);
+                        #   split by endpoint family (storage_tables/storage_files/configs/
+                        #   queue/tokens/branches/stream/query/workspaces/editor/misc + _core/_transfer),
+                        #   composed into one KeboolaClient via mixins (#520)
+  manage_client.py      # Manage API                   (X-KBC-ManageApiToken)
+  ai_client.py          # AI Service API               (component schemas, Kai)
+  data_science_client.py # Data Science API            (data apps)
+  metastore_client.py   # Metastore API                (semantic layer)
+  dev_portal_client.py  # Developer Portal API
+  stream_client.py      # Stream / Data Streams API    (OTLP/HTTP sources)
+
+  commands/             # LAYER 1 -- thin Typer commands, one file per group (31 modules):
+                        #   project config job storage flow branch workspace data_app
+                        #   sync semantic_layer agent stream feature dev_portal kai
+                        #   sharing lineage schedule search org component encrypt
+                        #   permissions serve http_client repl init doctor version
+                        #   changelog context
+                        # _helpers.py = formatter/service-factory/error-mapping; _*.py = private helpers
+  services/             # LAYER 2 -- business logic, one <group>_service.py per command group
+                        #   (DI: receives ConfigStore + client_factory; base.py = parallel infra;
+                        #    member_service, variables_service, repo_validate_service,
+                        #    deep_lineage_service are extra non-1:1 services)
+  server/               # FastAPI app behind `kbagent serve` (REST API + Web UI mount + SSE)
+  sync/                 # GitOps sync engine (manifest v3, pull/push/diff, branch-linking)
+  _ui_dist/             # bundled React SPA served by `kbagent serve --ui`
+
+tests/                  # ~137 files; mirror the layers (one test_<module>.py per command/service)
+  conftest.py           # Shared fixtures (tmp_config_dir, config_store, formatters)
+  helpers.py            # Shared test utilities
+  test_cli.py           # End-to-end CLI tests via typer.testing.CliRunner
+  test_e2e*.py          # E2E tests against a real API (make test-e2e; needs E2E_API_TOKEN + E2E_URL)
+  test_integration.py   # Integration tests (edge cases, linting)
+```
+
+## Architecture: 3-Layer Design
+
+```
+CLI Commands (commands/)  -->  Services (services/)  -->  API Client (client/, manage_client.py)
+  Typer, output                 Business logic             HTTP, endpoints
+```
+
+- API changes: modify only the relevant LAYER 3 client (`client/` package, `manage_client.py`, ...)
+- Business logic changes: modify only `services/`
+- UI changes: modify only `commands/`
+
+### HTTP Clients
+
+Seven clients, all inheriting `BaseHttpClient` (`http_base.py`) which provides shared retry/backoff logic (429/5xx, exponential backoff, 3 retries) and common HTTP infrastructure:
+
+- **KeboolaClient** (`client/` package): Storage API + Queue API, auth via `X-StorageApi-Token`
+- **ManageClient** (`manage_client.py`): Manage API, auth via `X-KBC-ManageApiToken`
+- **AiServiceClient** (`ai_client.py`): AI Service API (component schemas, Kai), URL derived as `ai.{stack_suffix}`
+- **DataScienceClient** (`data_science_client.py`): Data Science API (data apps)
+- **MetastoreClient** (`metastore_client.py`): Metastore API (semantic layer)
+- **DeveloperPortalClient** (`dev_portal_client.py`): Developer Portal API (component publishing)
+- **StreamClient** (`stream_client.py`): Stream / Data Streams API (OTLP/HTTP sources)
+
+### No MCP passthrough (removed in 0.85.0)
+
+kbagent used to proxy `keboola-mcp-server` tools through a `tool` command group. That
+passthrough -- the group, `McpService`, the `/mcp/*` routes, the `--type mcp_tool` agent
+flavour and the MCP server install/auto-update -- was removed in 0.85.0 (epic #390 phase 3).
+Every tool the catalog exposed has a native command; the historical tool-to-command map is
+`docs/mcp-migration.md`. Do not reintroduce an MCP client here: add a native command instead.
+`keboola-mcp-server` itself is unaffected and still works with Claude Desktop / Cursor -- it
+is simply a separate distribution kbagent no longer manages.
+
+## Versioning
+
+**Single source of truth: `pyproject.toml`** (`version = "X.Y.Z"`).
+
+- `src/keboola_agent_cli/__init__.py` reads the version at runtime via `importlib.metadata.version(APP_NAME)`. `APP_NAME` is resolved **dynamically** in `constants.py` (`_resolve_app_name()`: prefers the current distribution `keboola-cli`, falls back to the legacy `keboola-agent-cli` so the #424 migration-bridge wheel keeps working) -- it is **not** a fixed literal. **Never hardcode a version string in `__init__.py`.**
+- `plugins/kbagent/.claude-plugin/plugin.json` must match. Run `make version-sync` (or `python scripts/sync_version.py`) to update it.
+- The pre-commit hook and CI automatically check version consistency.
+
+### Version bumps happen ONLY in a dedicated release PR
+
+**Feature/fix PRs MUST NOT bump the version and MUST NOT add a `changelog.py`
+entry.** PRs are routinely developed in parallel (separate AI sessions, one per
+issue); when each of them bumps `pyproject.toml`, every merge is a version
+conflict and the merge order silently renumbers releases. The historical
+`KNOWN_UNRELEASED` list in `scripts/generate_changelog.py` -- 18 versions whose
+content shipped with no release notes -- is exactly what that pattern produces.
+
+The flow is instead:
+
+1. **Feature PR**: merges to `main` with NO change to `pyproject.toml`
+   `version` and NO `changelog.py` entry. When the PR documents version-gated
+   behavior (gotchas.md, commands-reference.md, this file), it tags it with
+   the literal placeholder **`vNEXT`** -- `(since vNEXT)` / `vNEXT+`.
+   `make version-gate-check` ignores the placeholder (it only matches numeric
+   versions) but rejects a guessed numeric version with no changelog entry,
+   so a numeric future tag cannot even pass CI. Writing `vNEXT` in a feature
+   PR is correct and stays green -- the placeholder only becomes fatal in a
+   version-raising PR (below).
+2. **Release PR** (its only job): bump `pyproject.toml`, review everything
+   merged since the last release (`git log v<last>..origin/main`), write ONE
+   changelog entry covering all of it (one bullet per logical change, with
+   `(#PR)` references), replace every `vNEXT` placeholder with the real
+   version (`make vnext-check` verifies it -- CI runs the same check
+   automatically on any PR that raises the version, so a missed placeholder
+   is a red build, not a silent ship), add the curated What's-new entry to
+   `web/frontend/src/whatsnew.ts` when the release ships UI-visible features
+   (skipping it errors nowhere -- the popup falls back to the previous reel
+   and the release's UI work ships dark), run `make version-sync`. Merge,
+   then tag the merge commit -- **the tag push is the ONLY manual action**:
+   the pipeline renders the release notes from the changelog entry
+   (`scripts/gen_release_notes.py`; never write them by hand), publishes
+   PyPI + native binaries, and creates + fills the GitHub Release. Verify
+   afterwards: pipeline green, `gh release view` shows a non-empty body and
+   both wheels. Full checklist: `CONTRIBUTING.md` >
+   "Releasing a new version".
+
+**Inside the release PR**: edit `pyproject.toml`, add the changelog entry to `src/keboola_agent_cli/changelog.py`, then run `make version-sync`. Do not edit `__init__.py` or `plugin.json` manually. `make changelog-check` (release-time, needs `gh`) enforces changelog completeness in both directions.
+
+The one exception is a **beta/pre-release** (below): there the bump deliberately
+rides the feature branch, because the pre-release tag and GitHub Release are cut
+from that branch -- the branch temporarily *is* the release PR.
+
+### Beta / pre-release versions
+
+Beta and release-candidate versions follow **PEP 440**: `0.44.0b1`, `0.44.0rc1`, ... -- **not** the SemVer `-beta.1` form (hatchling + uv require PEP 440 syntax in `pyproject.toml`). Three independent gates keep stable users safe from accidentally landing on a beta:
+
+1. **PEP 440 pre-release suffix.** pip / uv default to **skipping** pre-releases unless told otherwise (`--pre` for pip, `--prerelease=allow` for uv).
+2. **GitHub Release `prerelease: true` flag.** The auto-update startup hook reads `/releases/latest`, which never names a release marked `prerelease`; when it reads the release list, it skips every release marked `prerelease` (and every PEP 440 pre-release version) unless `--beta` is given. Marking the release `--prerelease` makes it invisible to the auto-update path.
+3. **Tag-pinned install URL.** When `--beta` opts into a pre-release, the install command appends `@v<version>` to the git+ source URL so uv pulls the **exact commit** the tag points to. Without this, uv would resolve the default branch (`main`) and -- if the beta lives on a feature branch -- silently install the stale main HEAD even though the version fetcher advertised the beta tag.
+
+**Author workflow (release a beta from a feature branch):**
+
+```bash
+# 1. Bump pyproject.toml to PEP 440 pre-release form on the feature branch
+#    version = "0.44.0b1"
+make version-sync                          # propagates to plugin.json / marketplace.json
+
+# 2. Add a changelog entry under that key in src/keboola_agent_cli/changelog.py
+# 3. Commit + push to PR (NOT to main -- main stays on the stable channel)
+git push origin feat/my-feature
+
+# 4. Tag the PR head SHA + push tag
+git tag v0.44.0b1 && git push origin v0.44.0b1
+
+# 5. KEY STEP: create the GitHub Release WITH --prerelease pointing at the tag
+gh release create v0.44.0b1 --prerelease \
+    --title "v0.44.0 — Beta 1" \
+    --notes-file release-notes-0.44.0b1.md
+```
+
+When the beta cooks long enough, merge the PR (stable squash) and ship `0.44.0` from main with a normal release **without** `--prerelease` -- auto-update picks it up on next startup.
+
+**User opt-in (consume betas):**
+
+- One-shot: `kbagent update --beta` -- resolver opts into pre-releases for this invocation only.
+- Per-shell: `export KBAGENT_INCLUDE_PRERELEASE=1` -- every `kbagent update` / `kbagent version` in that shell treats betas as installable.
+- **No persistent setting.** Each beta install is an active choice; never a forgotten "I once typed --beta six months ago" foot-gun.
+
+The startup auto-update hook is **never** affected by `--beta` / env opt-in -- it uses the stable channel only. Beta installs only come from explicit `kbagent update --beta`.
+
+Full author checklist: see `CONTRIBUTING.md` > "Releasing a beta (pre-release) version".
+
+## Coding Conventions
+
+> **0. (BINDING) Follow [CONTRIBUTING.md](CONTRIBUTING.md) in full.** Every code change -- human or AI agent -- must satisfy the rules in `CONTRIBUTING.md`. Specifically, the "Code Quality Patterns" section is non-negotiable: dataclasses (not bare tuples) for multi-value returns; categorical arguments before variable ones; `ErrorCode` enum (never raw strings); file-size budgets (measured in CODE LINES -- docstrings and comments are free; `make loc-check`); context managers over lambdas; named functions over assigned anonymous functions; `ty` clean for new code. The `.claude/settings.json` post-edit hooks run `ruff check --fix`, `ruff format`, and `ty check` after every edit -- when an AI agent edits a file in this repo, those checks fire automatically and any failure must be addressed before continuing. If a rule conflicts with an existing pattern in legacy code, **fix it in the PR you are touching** or open a follow-up issue; do not propagate the pattern.
+
+1. **Typer commands** are thin - they parse arguments, call a service, and format output. No business logic in commands.
+
+2. **Services** receive `ConfigStore` and a `client_factory` callable via dependency injection. This enables easy testing with mocks.
+
+3. **All data models** use Pydantic 2.x (`BaseModel`). Models are defined in `models.py` and shared across layers.
+
+4. **Dual output**: every command supports `--json` for structured output and Rich formatting for human-readable output. Use `OutputFormatter.output(data, human_formatter)`.
+
+5. **Error handling**: commands catch `KeboolaApiError` and `ConfigError`, map them to the appropriate exit code, and output structured errors in JSON mode. Report a `KeboolaApiError` with `emit_api_error(formatter, exc)` (`commands/_helpers.py`), which keeps its `retryable` and `details`. `tests/test_error_forwarding.py` fails on a handler that drops them.
+
+6. **Exit codes**: 0=success, 1=general error, 2=usage error, 3=auth error, 4=network error, 5=config error, 6=permission denied, 7=job timed out and cancelled (`JOB_TIMEOUT_TERMINATED`), 130=interrupted. [`docs/error-codes.md`](docs/error-codes.md) is the one list of error codes with their exit code and error type. `ERROR_CODE_TABLE` in `errors.py` holds the same pairs and `map_error_to_exit_code` reads it. `make check-error-codes` keeps the two equal.
+
+7. **Token masking**: tokens are never printed in full. Use `mask_token()` from `errors.py`.
+
+8. **Config file**: stored at `~/.config/keboola-agent-cli/config.json` with `0600` permissions. Managed by `ConfigStore`.
+
+9. **Tests**: use `typer.testing.CliRunner` for CLI tests, `unittest.mock` for mocking services and clients, `pytest` fixtures from `conftest.py`.
+
+10. **Dependencies**: typer, rich, httpx, pydantic, platformdirs, jsonschema, pyyaml. Dev: pytest, pytest-httpx, pytest-asyncio, ruff.
+
+11. **Error accumulation**: multi-project operations collect per-project errors without stopping. One project failing doesn't block others (see `lineage_service.py`, `org_service.py`).
+
+12. **Manage token security**: never persisted, never passed as CLI argument, never logged. Default-deny since 0.29.0: only via interactive hidden prompt; the `KBC_MANAGE_API_TOKEN` env var is **ignored** unless the top-level `--allow-env-manage-token` flag is passed. Default-deny closes the AI-exfiltration risk where any subprocess (including the AI agent itself) inherits the manage token via env. CI/CD callers must opt in explicitly.
+
+13. **Idempotency**: `org setup` skips already-registered projects by matching `project_id`. Safe to re-run.
+
+14. **Protected main branch**: direct pushes to `main` are blocked. Always create a feature branch, commit there, push, create a PR via `gh pr create`, merge via `gh pr merge`, then switch back to main and pull.
+
+15. **Pre-commit checks are mandatory.** Before every `git commit`, run `ruff check` and `ruff format --check` on changed files. A pre-commit hook (`scripts/pre-commit`, install via `make hooks`) does this automatically. **Never commit without passing lint + format.** If using sub-agents that write code, always run `make check` (or at minimum `ruff check src/ tests/ && ruff format . --check`) before committing their output.
+
+16. **E2E test coverage**: Every new CLI command MUST have a corresponding E2E test in `tests/test_e2e.py`. Run `make test-e2e` to verify. E2E tests require `E2E_API_TOKEN` and `E2E_URL` env vars and exercise the full CLI against a real Keboola project.
+
+17. **Plugin & agent sync are mandatory, NOT CI-enforced.** When adding/removing/renaming any command -- and at every version bump -- follow `CONTRIBUTING.md` sections "Documentation changes (mandatory!)", "Plugin synchronization map", and "Releasing a new version". CI catches drift only in `SKILL.md` (decision table), `plugin.json` (version), and `changelog.py` (release entries). The following files are **silent-drift risks** that ship broken if you forget them:
+    - `src/keboola_agent_cli/commands/context.py` (`GROUP_NOTES` and the tips. The command lists of `AGENT_CONTEXT` are generated by `make cli-manifest` and CI-checked)
+    - `CLAUDE.md` `## All CLI Commands` section (this file)
+    - `plugins/kbagent/agents/keboola-expert.md` -- **highest risk** (Rule 6 VERSION GATE, tool selection matrix, inline gotchas)
+    - `plugins/kbagent/skills/kbagent/SKILL.md` -- description triggers and workflow links (the auto-generated table is CI-checked, the rest is not)
+    - `plugins/kbagent/skills/kbagent/references/commands-reference.md`
+    - `plugins/kbagent/skills/kbagent/references/gotchas.md` (every new gotcha **MUST** be tagged with a version -- `(since v0.90.1)` in a feature PR, replaced with the real `(since vX.Y.Z)` by the release PR; the *replacement* is now CI-enforced on any version-raising PR, the *tagging* still is not)
+    - `plugins/kbagent/skills/kbagent/references/<topic>-workflow.md` (e.g. `semantic-layer-workflow.md`, `workspace-workflow.md`, `sync-workflow.md`)
+
+    Forgetting any of these does not fail tests or lint -- it ships an AI agent that quietly recommends commands that do not exist on the user's installed kbagent version, or refuses commands that do. Treat the change as **not done** until every applicable file has been updated.
+
+18. **Session-sentinel guards are CI-enforced.** `make check-sentinel-guards`
+    (in `make check`) rejects three kinds of drift: a `config.json` credential
+    write that is not sentinel-aware, a `BaseHttpClient` subclass that neither
+    declares `SESSION_AUTH_FEATURE` nor is recorded as bearer-capable, and a
+    `require_static_token` guard missing from `SESSION_UNSUPPORTED_FEATURES`
+    (`services/_auth_registration.py`) -- the tuple `auth login` /
+    `auth register-projects` disclose and every doc surface defers to. Run
+    `python scripts/check_sentinel_guards.py --list` to see the inventory.
+
+19. **Only `effective_branch.resolve_branch()` applies the active branch.**
+    Commands and services get the branch ID from it and never read
+    `ProjectConfig.active_branch_id` themselves: the function records the
+    project and branch, and `OutputFormatter` reports them (a `Target:` line
+    on stderr, `targets` in the `--json` envelope, also for `--dry-run`).
+    `tests/test_effective_branch.py` fails on a new direct read. A read that
+    only shows or manages the active branch must be on its list, with a reason.
+
+20. **Services receive project aliases, never project IDs.** `--project`
+    (and `project use`, `KBAGENT_PROJECT`, serve's `{project}` / `?project=`)
+    also takes a project ID; the root command group
+    (`commands/_project_ref.py`) translates it to the alias before the command
+    runs. A new command gets this without extra code. A new command whose
+    `--project` is not a registry lookup (an offline filter like `lineage
+    show`, the only entry now) must be added to `NO_LOOKUP_COMMANDS` there, and an option with another name that takes an existing alias (like
+    `config clone --target-project`) to `ALIAS_OPTIONS`.
+    `tests/test_project_ref.py` fails on a new option whose flag contains
+    `project`, `alias` or `stack` until it is in `ALIAS_OPTIONS` or in the
+    test's `NOT_AN_ALIAS` list; an option with any other name (like
+    `sync clone --target`) needs that decision by hand.
+    A command that takes one project declares
+    `project: str = typer.Option(None, "--project", "-p", ...)`, never a
+    required `--project`: `LeafCommand.invoke` fills an omitted value from the
+    T1 chain before the body runs (`use_active_project`, spec T17, blocking
+    rule `target.project-not-required`), for writes and deletes too. A command
+    that decides in its body what an omitted `--project` means (`flow schema`,
+    `project invite`) goes into `OWN_PROJECT_DEFAULT_COMMANDS`; a command with
+    an all-projects option resolves its projects in its body. The plugin tells
+    agents to pass `--project` on every command anyway.
+
+21. **The CLI interface spec is binding.** Every change to the command-line interface or the `kbagent serve` REST API follows [`docs/cli-interface-spec.md`](docs/cli-interface-spec.md); `make cli-spec-check` enforces the rules that a machine can check.
+
+## Claude Code Plugin
+
+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.
+
+**`.claude-plugin/marketplace.json` in this repo is a DEPRECATED SHIM.** Do not delete it and do not remove its `kbagent` entry: existing installs from `keboola-agent-cli` resolve updates through it, and `scripts/sync_version.py` + `make version-check` still keep its `version` in lock-step with `pyproject.toml`. Its entry `description` carries the migration notice users see in `/plugin` listings. Plan: keep for ~3 releases, then drop the entry and leave a `renames` tombstone. `renames` cannot redirect across marketplaces, so the migration is necessarily a manual two-line user action -- which is why the notice lives in the description. Its relative `source` follows the default branch, so it must be pinned to the last 0.x tag before 1.x documents reach `main` (`CONTRIBUTING.md` > "Releasing a new major version"); for a 1.x version `scripts/sync_version.py` refuses an unpinned shim and never changes the version of a pinned one.
+
+**Update rules** -- see `CONTRIBUTING.md` > "Documentation changes (mandatory!)", "Plugin synchronization map", and "Releasing a new version" for the binding checklists. Coding convention #17 above is the short version. Do **not** maintain a parallel update list here -- it always drifts.
+
+**Structure:**
+```
+.claude-plugin/marketplace.json                        # DEPRECATED shim marketplace (kept so old installs keep updating)
+plugins/kbagent/
+  .claude-plugin/
+    plugin.json                                        # Plugin manifest (auto-synced from pyproject.toml)
+    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
+    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.
+
+## All CLI Commands
+
+> **Hand-maintained, no CI freshness check.** When you add/remove/rename a
+> command, you must edit this section AND the other silent-drift surfaces
+> listed in convention #17 above. See `CONTRIBUTING.md` >
+> "Plugin synchronization map" for the full list.
+
+```
+# Global options: --json, --verbose, --no-color, --config-dir, --conversation-id, --deny-writes, --deny-destructive, --allow-env-manage-token
+# Short flags (#791, spec A2): one short flag per long option, on every option of that long name:
+#   -p --project, -n --name, -t --type, -L --limit, -o --output, -e --email, -d --directory, -y --yes,
+#   ... (SHORT_FLAGS in scripts/check_cli_spec.py; blocking rules args.short-flag-one-meaning and
+#   args.short-flag-on-every-option). A long name outside the registry has no short flag. Removed in 1.0.0:
+#   -c, -r, and -d/-f/-l/-m/-n/-v where they meant another option. Version gate lives in gotchas.md.
+# Environment variables (CLI-50, spec EV1): every variable kbagent reads is in ENV_VARS in
+#   src/keboola_agent_cli/env_vars.py (name, purpose, secret, added in, option); a new read needs an
+#   entry there (blocking rule env.registry-complete). An option that a variable sets declares it with
+#   envvar= (--config-dir: KBAGENT_CONFIG_DIR, --conversation-id: KBAGENT_CONVERSATION_ID, ...), so
+#   --help names it; precedence stays flag > variable > saved choice > default.
+# Root command class (CLI-44, #791; root_command.py): --json/-j, --deny-writes and --deny-destructive are
+#   also accepted after the subcommand (hidden copies on every group and command, argv not rewritten);
+#   -h = --help. Under --json every exit writes one JSON document: a malformed command line or a bare
+#   group is USAGE_ERROR (exit 2, help on stderr), a bad option value (Click's BadParameter, also from a
+#   command body) INVALID_ARGUMENT (exit 2), a crash INTERNAL_ERROR (exit 1). A bare group exits 2 with
+#   its help on stderr in human mode too. Success envelope adds schema_version ("1.0") and exit_code;
+#   error envelope adds schema_version only. A site that exits non-zero after formatter.output() passes
+#   exit_code= (blocking rule output.ok-then-exit-declares-exit-code). A single-value option given twice
+#   is USAGE_ERROR on write/destructive/admin commands, a REPEATED_OPTION warnings[] entry on reads.
+#   Version gate in gotchas.md.
+# Confirmations (CLI-46, spec S4): the safety prompts go through `_confirm_or_abort` in commands/_helpers.py
+#   (also the preview-then-confirm of `org setup` and `project refresh`). --yes and --json skip it. On a
+#   terminal it asks on stderr. In human mode without a terminal (stdin or stderr not a TTY) it refuses with
+#   CONFIRMATION_REQUIRED, exit 2, naming --yes -- a piped "y" no longer confirms. Not through the helper:
+#   the non-safety questions of `init` and of the `auth login` / `auth register-projects` project picker;
+#   the `workspace load` size guard (asks on a terminal only, refuses without one); and the service guards
+#   of `semantic-layer add metric` / `edit metric` (VALIDATION_ERROR without a terminal, and they still ask
+#   on a terminal under --json). `branch delete` and `workspace delete` now ask too, and take --yes and a read-only --dry-run
+#   (REST: `dry_run` query parameter, no prompt). Deprecated flags (spec C3) are hidden options from
+#   `deprecated_option()` with a `DEPRECATIONS` entry. They add a DEPRECATED warning (`replacement`,
+#   `remove_after`). None exists now. 1.0.0 removed every old form (#791): `stream delete --force` (use
+#   --yes), `semantic-layer import --yes`/-y (no effect), `project add/create --project`/-p (use --alias),
+#   `project refresh --all` (use --all-projects), `--id` on merge-request, agent and
+#   semantic-layer reference-data get/delete commands, `branch merge`, `semantic-layer scope
+#   request-delete` (use request-cancel), the positional SOURCE_ID of `stream detail/delete`
+#   (use --source-id), the positional TASK_ID / RUN_ID of `agent` commands (use --task-id /
+#   --run-id), `storage describe-batch --from-file` and
+#   `project invite --from-csv` (use --file), `storage create-table --not-null` (use
+#   --not-null-column), the plural list options (spec A4) and the old file-input options (spec
+#   I1/I2/I6; both in "Input forms" below). Each keeps a `DEPRECATIONS` entry with removed_in="1.0.0".
+#   `removed_form()` (an option) and `removed_argument()` (a positional, key "<path> METAVAR")
+#   look it up, and LeafCommand/CommandGroup in root_command.py put its message into the
+#   USAGE_ERROR (exit 2), so the error names the replacement. Version gate lives in gotchas.md.
+# --conversation-id ID (#716): sets the X-Conversation-ID observability header for the
+#   invocation; equivalent to KBAGENT_CONVERSATION_ID and takes precedence over it. Exists because an
+#   agent harness does not persist shell state between tool calls, so the documented one-time `export`
+#   was unsatisfiable -- and re-prepending `export ...` to every command stops it matching a
+#   `Bash(kbagent ...)` permission allow-rule, so every call fell through to the safety classifier.
+#   For a whole session, set the env var in the harness's own env block instead (Claude Code:
+#   settings.json -> env). Neither set = header omitted, as before. Version gate for this entry
+#   lives in gotchas.md -- a `(since vNEXT)` tag cannot be written on these `# ` comment lines,
+#   because check_version_gates.py parses them as ATX markdown headings (where a `vNEXT` is fatal).
+# --project (CLI-22) takes a registered alias OR a project ID. An alias wins; an ID registered under
+#   several aliases is CONFIG_ERROR (exit 5) listing them, unless all are on one stack and exactly one is a
+#   session alias. Same for KBAGENT_PROJECT, `project use`, `config clone --target-project`,
+#   `sync clone --target`, the `semantic-layer promote/diff` project options, `auth * --stack`, and
+#   serve's {project} / ?project= / ?stack= (path and query only, not request bodies). Not for
+#   `project add --alias` / `project create --alias` (new alias) or `lineage show` (offline filter). Version gate in
+#   gotchas.md.
+# Headless / token-only (0.50.0+): export KBAGENT_PROJECT_FROM_ENV=1 + KBC_TOKEN + KBC_STORAGE_API_URL to synthesize an in-memory `__env__` project (no `project add`, no config.json on disk; token never persisted). Use `--project __env__`. Same env setup also powers `kbagent serve`.
+
+kbagent auth login [--stack URL|alias] [--device-code] [--register-projects] [--no-open]
+# auth login (CLI-50): notices, the device panel, hints and the picker question go to stderr in
+#   every mode; the result stays on stdout. The browser opens as before, also under --json and
+#   without a terminal (the auth login exception to spec HO5); --no-open uses the device flow and
+#   opens nothing. Version gate lives in gotchas.md.
+kbagent auth login-password --email EMAIL (--password PASSWORD | --password-stdin) [--totp-secret SECRET] [--stack URL|alias] [--register-projects]
+kbagent auth status [--stack URL|alias]
+kbagent auth logout [--stack URL|alias] [--remove-projects] [--yes]
+kbagent auth register-projects [--stack URL|alias] [--all] [--project-id ID ...] [--alias ID=ALIAS ...] [--yes]
+# auth stack (CLI-32): without --stack every auth command (and serve's /auth/* without ?stack=) takes the
+#   stack of KBAGENT_PROJECT > active project > sole registered project > CONFIG_ERROR naming --stack,
+#   KBAGENT_PROJECT and `project use`. Before, only the active project. With --stack given,
+#   KBAGENT_PROJECT is not read. A KBAGENT_PROJECT that names no registered project is CONFIG_ERROR in
+#   status/logout and is skipped with a `warnings` entry in login/login-password/register-projects.
+#   Version gate lives in gotchas.md.
+# auth login-password (0.84.0+): the deliberate unattended exception to auth login's "needs a human at
+#   a browser" rule -- email + password (+ TOTP if the account has MFA) grant, no browser, safe to run
+#   from a CI secret-backed workflow step. Prefer --password-stdin (or KBC_LOGIN_PASSWORD) over
+#   --password -- a value on the command line lands in shell history and process listings;
+#   --password/--password-stdin are mutually exclusive (ConfigError if both given).
+#   --email/--password/--totp-secret also read from
+#   KBC_LOGIN_EMAIL/KBC_LOGIN_PASSWORD/KBC_LOGIN_TOTP_SECRET env vars (mirroring KBC_TOKEN's convention),
+#   so a workflow can set them once in a step's env: block. --totp-secret is the base32 TOTP SEED (not
+#   a 6-digit code) -- kbagent computes the current code itself (auth/totp.py, stdlib-only RFC 6238),
+#   so no human ever types a live code. Only the TOTP factor is resolvable this way; a WebAuthn/passkey-
+#   only account gets AUTH_MFA_INVALID and must use `auth login` (needs a browser) instead. Stores the
+#   session in auth.json exactly like `auth login` does -- same auth-mode, same "session" column in
+#   `project list`, same downstream command support. Storing an account's password (and TOTP seed) as
+#   CI secrets is a bigger blast radius than a single scoped project token: use a dedicated,
+#   least-privileged service account, never a real human's own credentials. New error code:
+#   AUTH_MFA_INVALID.
+# auth (since 0.80.0): browser-based login -- PKCE authorization-code by default (falls back to the
+#   RFC 8628 device flow ONLY on a pre-exchange failure: no loopback browser, callback timeout, or an
+#   SSH/container/WSL heuristic; --device-code forces it). APPROVAL REQUIRES A HUMAN AT A BROWSER,
+#   but driving the command does not: in an ATTENDED session an agent MAY run
+#   `auth login --device-code` in a BACKGROUND shell, relay the verification URL + user code it prints
+#   before polling starts, and confirm with `auth status` (exit 0 = signed in, exit 3 = not yet). Never
+#   in a foreground tool shell (~120s timeout kills the flow mid-flight), never from an unattended task
+#   (nobody can approve), never blind-retry without checking `auth status` first (orphans a session);
+#   use `auth login-password` or a static Storage token for CI/headless instead. Issues a
+#   USER-scoped "programmatic session" (kbc_at_* access token + kbc_rt_* refresh token) stored in
+#   auth.json (0600), a sibling of config.json -- config.json's schema and CURRENT_CONFIG_VERSION are
+#   unchanged. --register-projects writes each accessible project into config.json with the sentinel
+#   token `kbc-session://{project_id}`. A session now works with nearly every command -- the Storage
+#   and Manage client paths plus (added by CLI-13) the Scheduler (flow schedule / schedule-remove),
+#   Data Streams (stream), Data Science (data-app), the semantic-layer group, the AI Service, and
+#   Storage bucket sharing (sharing share / unshare). `serve` reaches them too, because it delegates to
+#   the same already-guarded services (see server/dependencies.py). Only three features still fail fast
+#   on a sentinel-token project (AUTH_NOT_SUPPORTED_ON_STACK) naming the static-token fallback: the
+#   authoritative list is SESSION_UNSUPPORTED_FEATURES in services/_auth_registration.py, shipped to
+#   callers as `session_unsupported_features` in --json -- do not re-derive it by hand. `dev-portal` is NOT on it
+#   (it authenticates with its own identity, never a project token). Over `serve`, a session that
+#   expires at runtime answers HTTP 401 with
+#   error_code SESSION_EXPIRED -- a browser login only completes on the host. Serving session projects
+#   means whoever holds KBAGENT_SERVE_TOKEN acts as the signed-in USER; see docs/web-server.md.
+#   New error codes: AUTH_NOT_SUPPORTED_ON_STACK, AUTH_FLOW_TIMEOUT, AUTH_FLOW_DENIED, AUTH_FLOW_EXPIRED,
+#   AUTH_BROWSER_UNAVAILABLE, AUTH_STATE_MISMATCH, SESSION_EXPIRED, SESSION_NOT_FOUND.
+# `auth register-projects` (0.80.0+): fixes the usability gap where nothing was registered unless
+#   --register-projects was passed at login, and where the alias offered was a slug of the project
+#   NAME (never the numeric id; the id itself resolves as `--project` once registered, CLI-22). Lists every project the session
+#   can access with a collision-free suggested alias, then lets the caller pick which to register.
+#   --all selects every candidate; --project-id ID (repeatable) selects specific ones (unknown id ->
+#   ConfigError); omitting both runs an interactive arrow-key + spacebar checkbox picker (every
+#   not-yet-registered project preselected, [a] toggles all, [enter] accepts) followed by a single
+#   "Edit aliases?" confirm (default No) that opens the old per-project alias prompt only if opted
+#   into -- each row already shows its suggested alias. On a piped stdin or a terminal without real
+#   interactive capabilities, it falls back to the original numbers/ranges/'all'/'none' typed prompt.
+#   In a non-TTY or --json context with neither --all nor --project-id, it fails fast telling the
+#   caller to pass --all or --project-id. --alias ID=ALIAS (repeatable) overrides the
+#   suggested alias in every mode. --yes skips only the picker's final confirmation. Never overwrites
+#   an existing alias: same project+stack already registered -> status "exists" (no-op); alias taken by
+#   something else -> status "skipped" with a rename hint. `auth login` (no --register-projects) also
+#   offers this same picker interactively right after a successful login when stdout is a TTY and
+#   --json was not used; otherwise it just prints the `auth register-projects` hint. Same picker fix
+#   applies retroactively to `auth login --register-projects` (now suffixes on an alias collision
+#   instead of silently skipping the second project). See docs/programmatic-auth-login-plan.md
+#   section 4.5 for the full design.
+# `auth` over `kbagent serve` (since v0.90.1): `register-projects` / `status` / the project-candidate
+#   listing get a `server/routers/auth.py` counterpart -- `POST /auth/register-projects`,
+#   `GET /auth/status`, `GET /auth/projects` (the interactive picker's data source; no CLI leaf
+#   command of its own). `login` / `login-password` / `logout` deliberately have NO endpoint -- a
+#   browser login only completes on the host, a password grant must never sit behind the serve
+#   bearer token, and revoking the session is a host-operator action, not a remote one. `/auth/*`
+#   is also the FIRST router to enforce the `permissions` policy: every route declares
+#   `Depends(require_permission(...))`, so a denial answers HTTP 403 `PERMISSION_DENIED` over REST
+#   exactly as on the CLI. Every other route is checked too since #655 (see `permissions` below).
+#   The policy comes from the config dir `serve` RESOLVES (its own `--config-dir`, then -- since
+#   0.91.0, #679 -- an explicit root `kbagent --config-dir`, then KBAGENT_CONFIG_DIR, then the
+#   local/global chain) plus the session flags of the invocation. On 0.90.1 the root-level
+#   `--config-dir` was IGNORED here, so a policy stored beside the projects the caller named was
+#   silently not the one enforced; on that version pass --config-dir to `serve` itself.
+#   Reachable ways to enforce: a persisted narrow policy
+#   (`kbagent permissions set --mode allow --deny auth.register-projects`, needs a real
+#   terminal for the confirmation code), or `--mode deny` with `serve` (and the reads you want) in
+#   the allow list. `kbagent --deny-writes serve` does NOT work: `serve` is admin-class and
+#   `--deny-writes` appends `cli:write`, which spans write+destructive+admin, so the CLI callback
+#   blocks the `serve` command itself (exit 6) and no server ever starts. `--deny-destructive`
+#   starts the server and blocks every destructive route (none of them under `/auth/*`).
+#   See docs/web-server.md.
+
+kbagent project create --url URL [--alias ALIAS] [--name NAME] [--backend snowflake|bigquery] [--sync-backend-init]
+# project create (since 0.95.0, DMD-1940): the ONLY kbagent command that works from nothing --
+#   no account, no token, no `auth login`. POSTs the unauthenticated provisioning endpoint
+#   (`/manage/programmatic-projects`, gated by the `agent-provisioning` stack feature
+#   / `STACK_FEATURES__AGENT_PROVISIONING`, off on most stacks -- the COMMAND is always
+#   registered, so `--help` proves nothing about the stack; without the feature the stack 404s
+#   and this exits 5 (1 before 1.0.0) with AUTH_NOT_SUPPORTED_ON_STACK, naming the flag and the browser path),
+#   stores the returned project-pinned session in auth.json, and registers the project in
+#   config.json under the `kbc-session://` sentinel -- becoming the default project when nothing
+#   else was registered. THE PROJECT IT CREATES IS OWNED BY NOBODY: the result's `confirm_url` is a
+#   single-use, days-limited link a human must open and sign in at to take ownership; relay it
+#   verbatim. `auth status` re-prints it as `agent_confirm_url` while it is pending, so losing the
+#   terminal is recoverable -- losing the claim window is not. Confirming REVOKES this session, so
+#   the documented next step is `kbagent auth login --stack URL`; the alias survives it (the
+#   sentinel keys on project id + stack, never on the session). Refuses with exit 5 when a session
+#   for that stack already exists -- auth.json holds one session per stack, and whoever has one has
+#   an account and should create the project in the UI. `--backend` omitted keeps the stack
+#   maintainer's own default; `--sync-backend-init` waits for backend init instead of the async
+#   default (which warns that the first Storage command may fail until it lands). The provisioning
+#   POST is never auto-retried on 5xx/429 -- it is not idempotent, and each success creates an
+#   organization, a billable project and a credit grant. A timeout is classified rather than
+#   lumped together: a connect timeout never reached the stack (retryable), a READ timeout was
+#   delivered and may have succeeded (retryable:false, message says not to repeat -- check
+#   `auth status`, whose stored session + claim link is the evidence). `--sync-backend-init`
+#   raises that call's read timeout to 300s, which can outlast an agent's foreground shell.
+kbagent project add --alias NAME --url URL [--token-stdin | --token-file PATH [--keep-token-file] | --token-env NAME | --token TOKEN]
+kbagent project list
+kbagent project remove [--project NAME] [--dry-run] [--yes]
+kbagent project edit [--project NAME] [--url URL] [--token-stdin | --token-file PATH [--keep-token-file] | --token-env NAME | --token TOKEN] [--new-alias NEW]
+kbagent project status [--project NAME | --all-projects]
+kbagent project refresh [--project ALIAS] [--dry-run] [--force] [--yes] [--token-description DESC] [--token-expires-in N]
+kbagent project refresh --all-projects [--dry-run] [--force] [--yes] [--token-description DESC] [--token-expires-in N]
+kbagent project description-get [--project NAME]
+kbagent project description-set [--project NAME] (--description STR | --description-file PATH)
+kbagent project use ALIAS
+kbagent project current
+# Active project (CLI-32): `project remove` (and DELETE /projects/{alias}, bulk-delete, `auth logout
+#   --remove-projects`) CLEARS the active project instead of moving it to the next alias; `init --project`
+#   that leaves it out clears it too. Results carry `active_project_cleared` / `active_project_set`
+#   (project use/add, org setup, auth registration, project create). `project current` adds
+#   `resolved_alias` + `resolved_source` (env|active_project|sole|none). In 1.0.0 the `source` value
+#   `pin` of `project use` / `project current` is `active_project`. Version gate lives in gotchas.md.
+kbagent project info [--project NAME]
+kbagent project invite [--project ALIAS] --email EMAIL --role admin|guest|readOnly|share [--reason TEXT] [--dry-run]
+kbagent project invite --file FILE [--default-role ROLE] [--workers N] [--dry-run]
+kbagent project member-list [--project ALIAS] [--include-pending]
+kbagent project invitation-list [--project ALIAS]
+kbagent project invitation-cancel [--project ALIAS] --email EMAIL [--invitation-id ID] [--dry-run] [--yes]
+kbagent project member-remove [--project ALIAS] --email EMAIL [--yes]
+kbagent project member-set-role [--project ALIAS] --email EMAIL --role admin|guest|readOnly|share [--dry-run]
+
+kbagent config list [--project NAME | --all-projects] [--component-type TYPE] [--component-id ID] [--branch ID] [--include-rows]
+kbagent config detail [--project NAME] [--project NAME ...] --component-id ID [--config-id ID] [--branch ID] [--with-state]
+kbagent config search --query PATTERN [--project NAME | --all-projects] [--component-type TYPE] [--ignore-case] [--regex] [--branch ID]
+kbagent config update [--project NAME] --component-id ID --config-id ID [--name N] [--description D] [--configuration JSON | --configuration-file PATH] [--set PATH=VALUE ...] [--merge] [--change-description TEXT] [--dry-run] [--branch ID] [--allow-plaintext-on-encrypt-failure]
+kbagent config set-default-bucket [--project NAME] --component-id ID --config-id ID (--bucket BUCKET_ID | --clear) [--dry-run] [--branch ID]
+kbagent config rename [--project NAME] --component-id ID --config-id ID --name "New Name" [--branch ID] [--directory DIR]
+kbagent config delete [--project NAME] --component-id ID --config-id ID [--branch ID] [--dry-run]
+kbagent config restore [--project NAME] --component-id ID --config-id ID [--branch ID]
+kbagent config trash-list [--project NAME] [--component-id ID] [--branch ID]
+# config delete (0.89.0+ safety): SOFT delete into the Storage trash, with a locate-first guard.
+#   The raw API purges PERMANENTLY when DELETE hits a config already in the trash -- the classic
+#   agent retry after a timeout. kbagent now looks the config up first: live -> trash it;
+#   already trashed -> status "already_in_trash", exit 0, NO second DELETE ever sent; absent
+#   from both -> NOT_FOUND. Undo with `config restore`; browse candidates with `config
+#   trash-list`. Before 0.89.0 the second delete destroyed the config permanently. CLAUDE.md
+#   did not list `config delete` at all until 0.89.0 (silent drift) -- the command itself has
+#   existed for a long time.
+kbagent config variables-set [--project NAME] --component-id ID --config-id ID --var KEY=VALUE [--var ...] [--replace] [--variables-id ID] [--values-id ID] [--branch ID] [--dry-run]
+kbagent config variables-get [--project NAME] --component-id ID --config-id ID [--branch ID]
+kbagent config variables-clear [--project NAME] --component-id ID --config-id ID [--branch ID] [--yes]
+kbagent config metadata-list [--project NAME] --component-id ID --config-id ID [--branch ID]
+kbagent config get-metadata [--project NAME] --component-id ID --config-id ID --key KEY [--branch ID]
+kbagent config set-metadata [--project NAME] --component-id ID --config-id ID --key KEY --value VALUE [--branch ID]
+kbagent config delete-metadata [--project NAME] --component-id ID --config-id ID --metadata-id ID [--branch ID] [--yes]
+kbagent config set-folder [--project NAME] --component-id ID --config-id ID --name FOLDER [--branch ID]
+# set-folder (DMD-2348): writes the configuration's `folder` field (PUT, no new version); empty
+#   --name clears it. kbagent no longer reads or writes the KBC.configuration.folderName metadata key:
+#   `config list` and `sync pull` read `folder` from the listing they already fetch (no extra
+#   search/component-configurations call), `sync push` / `sync clone` send it on the create POST.
+#   The sync manifest still stores the folder under that key name. The set-folder JSON has
+#   `folder` and `configuration` (the PUT response subset {id, name, folder}). The metadata-era
+#   keys `key`, `value` and `result` are removed in 1.0.0.
+#   Needs keboola/connection DMD-2347 on the stack: without it set-folder fails FEATURE_NOT_ENABLED
+#   (exit 5) and push/clone add a `folder_not_supported` warnings[] entry. No metadata fallback.
+#   Version gate in gotchas.md.
+kbagent config row-create [--project NAME] --component-id ID --config-id ID --name ROW_NAME [--description D] [--configuration JSON | --configuration-file PATH] [--is-disabled] [--branch ID] [--allow-plaintext-on-encrypt-failure]
+kbagent config row-update [--project NAME] --component-id ID --config-id ID --row-id ID [--name N] [--description D] [--configuration JSON | --configuration-file PATH] [--change-description TEXT] [--is-disabled | --is-enabled] [--branch ID] [--allow-plaintext-on-encrypt-failure]
+kbagent config row-delete [--project NAME] --component-id ID --config-id ID --row-id ID [--branch ID] [--yes]
+kbagent config oauth-url [--project NAME] --component-id ID --config-id ID [--redirect-url URL] [--no-open]
+# oauth-url: opens the link in the default browser (interactive human mode only; never with
+#   --json, over SSH, in a container or in WSL without wslview); --no-open only prints it.
+#   Version gate in gotchas.md.
+kbagent config state-get [--project NAME] --component-id ID --config-id ID [--row-id ID] [--branch ID]
+kbagent config state-set [--project NAME] --component-id ID --config-id ID [--row-id ID] (--state JSON | --state-file PATH) [--branch ID] [--dry-run] [--yes]
+# state-get/state-set (0.84.2+, #593): read/write a config's runtime state via the dedicated
+#   PUT .../state endpoint -- closes the gap where `config update --set 'state...'` looked
+#   successful but silently wrote to configuration.state.* instead (runtime state untouched).
+#   Since 0.84.2, `config update --set` / `config row-update --set` REJECT (exit 2) any path
+#   whose first segment is a top-level API field (state, rows, name, description, id, version,
+#   currentVersion, changeDescription, created, creatorToken, isDeleted, isDisabled) -- use
+#   state-set / --name / --description / row-update --is-disabled instead, or --configuration
+#   for a genuine configuration.<prefix> key.
+kbagent config clone [--project P] --component-id ID --config-id ID --name NAME [--target-project P2] [--description D] [--set PATH=VALUE ...] [--secret PATH=VALUE ...] [--branch ID] [--target-branch ID] [--dry-run] [--allow-plaintext-on-encrypt-failure]
+# clone (0.84.2+, #587): duplicates a configuration WHOLE. Hand-rebuilding a body from `config
+#   detail` drops siblings of `parameters` (`runtime`, `storage`, `authorization`) silently -- a
+#   lost `runtime.parallelism` makes Keboola fall back to parallelism 1 (a 65-row writer then ran
+#   sequentially, 140 min instead of ~60-90, with nothing reported).
+#   SAME project (default): server-side copy (`POST .../configs/{id}/versions/{v}/create`) --
+#   rows AND `KBC::` values come along (verified live). `--set` edits are applied as a follow-up
+#   update on the copy, so an override can never be why a key went missing.
+#   CROSS project (`--target-project`): reassembled client-side, rows recreated one by one.
+#   Encrypted values CANNOT travel (ciphertext is project-scoped), so the clone is REFUSED,
+#   listing every path, until each is re-supplied via `--secret PATH=VALUE`; those are encrypted
+#   in the TARGET project on write. `--dry-run` reports the paths instead of refusing -- that is
+#   how you discover what to gather. Storage bucket/table IDs are copied VERBATIM, never remapped
+#   (`sync clone` is the command that remaps).
+
+# Target selection (CLI-45, spec T1/T2/T6/T12/E4): the 20 fan-out reads (search, billing credits, component
+#   list, config list/search, data-app list, job list, storage buckets/tables, sharing list/edges, flow list,
+#   schedule list/find, notification list, branch list, workspace list, project status, sync pull/diff) use the active
+#   project when --project is omitted (KBAGENT_PROJECT > `project use` > sole project > CONFIG_ERROR, exit 5,
+#   commands/_all_projects.fanout_projects). --all-projects reads all registered projects (with --project:
+#   USAGE_ERROR, exit 2). A read in which a project failed exits 1 after the full payload (finish_fanout,
+#   PAYG_NOT_AVAILABLE counts as read; headline `Success: N project(s) read.`). No registered project = exit 5.
+#   Every `targets` record has `project_source`
+#   (explicit|env|active_project|sole|all). effective_branch.record_project records it, called by the --project
+#   option callback, resolve_pinned_alias, resolve_projects and fanout_projects. A project without a branch record
+#   gets one record with branch_source "none". A destructive or admin command under --json whose project or branch
+#   is the active choice adds a TARGET_FROM_ACTIVE_CHOICE warnings[] entry (OutputFormatter, category set by
+#   root_command.LeafCommand). REST list routes follow the same chain since CLI-49. --json envelopes have an optional top-level
+#   `warnings` list ({code, message, ...}), not the same as `data.warnings`. Version gate in gotchas.md.
+kbagent search QUERY [--project NAME | --all-projects] [--type table|bucket|config|flow|data-app|transformation] [--search-type textual|config-based] [--regex] [--scope PATH ...] [--limit N]
+# --regex (0.67.0+): opt-in regex mode (mode=regex). Case-insensitive whole-term match on ENTITY NAMES
+#   only ('report' != 'monthly_report'; use '.*report.*'). Textual only -- error with --search-type
+#   config-based. Regex does NOT match column names, so matched_columns is always empty under --regex.
+#   In textual mode, table results matched via a column name carry matched_columns (JSON) / a
+#   "Matched columns" table column.
+# BOTH modes match case-insensitively (config-based was case-sensitive until #569, which made
+#   "is this referenced anywhere" miss a table spelled DCFAmount in one config and DCFAMOUNT in
+#   another). `kbagent config search --query` stays case-sensitive by default (it has --ignore-case).
+
+kbagent job list [--project NAME | --all-projects] [--component-id ID] [--config-id ID] [--status STATUS] [--limit N] [--offset N] [--sort-by startTime|endTime|createdTime|durationSeconds|id] [--sort-order asc|desc]
+# job list (0.90.1+, #675): a multi-project fan-out (--all-projects) is merged GLOBALLY by
+#   --sort-by/--sort-order (default startTime desc), missing values last in both directions,
+#   deterministic (project_alias, id) tiebreak. Before 0.90.1 rows came back grouped alias-then-id,
+#   which destroyed the chronological order the fan-out exists to produce. Same change applies to
+#   `kbagent serve`'s GET /jobs. Anything relying on per-project blocks must group them itself.
+kbagent job detail [--project NAME] --job-id ID [--log-tail-lines N]
+kbagent job run [--project NAME] --component-id ID --config-id ID [--row-id ID ...] [--wait] [--timeout N] [--branch ID] [--mode run|debug] [--variable-values-id ID] [--no-variables] [--poll-strategy exponential|fixed] [--log-tail-lines N] [--idempotency-key KEY] [--force-rerun]
+kbagent job terminate [--project NAME] (--job-id ID [--job-id ID ...] | --status any|created|waiting|processing [--component-id ID] [--config-id ID] [--branch ID] [--limit N]) [--dry-run] [--yes]
+# job terminate --status --branch 0 (CLI-21): matches only jobs whose branchId is the default branch
+#   ID (read from GET /v2/storage/dev-branches). Before, it matched no job. Version gate in gotchas.md.
+# job run --idempotency-key: a pending entry is recorded BEFORE the create. A definite failure (4xx,
+#   refused connection, connect timeout) removes it; an unknown outcome (read timeout, 5xx, exhausted
+#   retries) keeps it, because the job may exist. A replay that finds the pending entry exits with INVALID_ARGUMENT (1 before 1.0.0, 2 from 1.0.0, HTTP 400 over serve) and
+#   creates nothing; check `job list`, then `--force-rerun`. Version gate lives in gotchas.md.
+
+kbagent storage buckets [--project NAME | --all-projects] [--branch ID]
+kbagent storage bucket-detail [--project NAME] --bucket-id ID [--branch ID]
+kbagent storage tables [--project NAME ... | --all-projects] [--bucket-id ID] [--branch ID] [--include-usage]
+kbagent storage table-detail [--project NAME] --table-id ID [--branch ID]
+# table-detail (0.88.0+, #621): also returns the raw Storage API `definition`. On BigQuery
+#   that object (timePartitioning / rangePartitioning / clustering / requirePartitionFilter /
+#   partitions[]) is the ONLY readable record of the registered layout, so it is how a
+#   `create-table --source-table-id ...` + `swap-tables` repartition is VERIFIED -- the table
+#   ID is unchanged either way, and `create-table` only echoes the layout you REQUESTED (its
+#   --if-not-exists skip path nulls the layout keys outright). Human mode adds Time
+#   partitioning / Range partitioning / Clustering / Partition filter required / Partitions
+#   (a COUNT) and prints nothing new when there is no layout. The human
+#   Columns table also carries a Description column (0.89.0+, #642; NOT on 0.88.0), populated from
+#   `column_details[].description` and shown only when some column has one -- the one
+#   surface #624 left blank, so `describe-column` then `table-detail` now verifies
+#   itself (long text wraps, never truncates). --json passes `definition`
+#   through verbatim, including the unbounded `partitions[]` (one entry per physical
+#   partition from INFORMATION_SCHEMA.PARTITIONS). `definition` is present on EVERY response
+#   -- untyped tables get one too -- so null means the stack omitted the key, NOT "untyped".
+#   `storage tables` (the LIST endpoint) is unaffected: the API has no `definition` include.
+#   table-detail also returns `backend_path` (the owning bucket's Storage backendPath, verbatim)
+#   and `sql_path` (quoted, directly queryable path; null when Storage reports no location) --
+#   see the semantic-layer dataset fqn note (#761); version gate in gotchas.md.
+kbagent storage create-bucket [--project NAME] --stage STAGE --name NAME [--description D] [--backend B] [--branch ID]
+kbagent storage create-table [--project NAME] --bucket-id ID --name NAME [--column COL:TYPE[(length)] ...] [--primary-key COL] [--not-null-column COL ...] [--default NAME=VALUE ...] [--source-table-id ID] [--source-branch-id N] [--time-partitioning-type DAY|HOUR|MONTH|YEAR] [--time-partitioning-field COL] [--time-partitioning-expiration-ms MS] [--range-partitioning-field COL --range-partitioning-start S --range-partitioning-end E --range-partitioning-interval I] [--clustering-field COL ...] [--branch ID] [--if-not-exists] [--timeout SECONDS]
+# --column XOR --source-table-id (0.66.0+, BigQuery only): --source-table-id copies an existing table's data into the requested partition/clustering layout (schema derived from source) -> swap into place with swap-tables. Partition/clustering flags work in both modes (BigQuery only); time vs range partitioning are mutually exclusive. A non-BigQuery project fails fast (pre-flight backend check).
+kbagent storage upload-table [--project NAME] --table-id ID --file PATH [--incremental] [--delimiter D] [--enclosure E] [--no-auto-create] [--wait/--no-wait] [--timeout SECONDS] [--branch ID] [--progress]
+# upload-table / file-upload cloud upload (#834): on AWS stacks a file above 64 MiB goes up as an S3
+#   MULTIPART upload -- 64 MiB parts (auto-scaled so the file fits in 10,000 parts), 4 in parallel,
+#   per-part retry on 429/5xx/transport errors, peak memory ~4 x part size. Before, the whole file was
+#   read into RAM and sent as one PutObject (hard 5 GiB ceiling). Also covers the SDK
+#   Client.upload_table. Azure/GCP stacks unchanged (they already stream; chunked upload there is a
+#   follow-up in #834). Limits: S3 federation credentials last 12 h (200 GB needs ~5 MB/s sustained);
+#   the source file must not change during the upload (size/mtime checked); no resume across runs; an
+#   aborted multipart upload may leave orphaned parts (the token cannot abort). A .csv.gz is uploaded
+#   byte-for-byte and imported by Storage; auto-create reads its header through gzip. Human mode shows
+#   a progress bar on stderr. `serve`'s upload route streams the body to a temp file (needs temp disk
+#   of the file size) instead of holding it in memory.
+# upload-table / load-file async import (#834): --wait (default) waits --timeout SECONDS (default 600)
+#   for the Storage import job; --no-wait still waits for the cloud upload, then enqueues the import and
+#   returns file_id / job_id / job_status (imported_rows null while pending; keys are additive). A wait
+#   timeout is STORAGE_JOB_TIMEOUT, exit 4, retryable=false: the import KEEPS RUNNING server-side, the
+#   error names job_id + file_id and `storage job-detail --job-id ID --wait`. Never re-run the upload
+#   while that job is waiting/processing -- an incremental re-run duplicates rows. An enqueue failure
+#   after the upload carries file_id -> `storage load-file --file-id` instead of re-uploading.
+#   Workflow: plugins/kbagent/skills/kbagent/references/large-upload-workflow.md. Version gate for this
+#   entry lives in gotchas.md.
+kbagent storage download-table [--project NAME] --table-id ID [--output FILE] [--column COL ...] [--limit N] [--where-column COL --where-value VAL ... [--where-operator eq|neq]] [--changed-since WHEN] [--changed-until WHEN] [--branch ID] [--progress]
+# --progress on upload-table / file-upload / download-table / file-download / unload-table (with
+#   --download): ALWAYS report transfer progress on stderr -- also with --json and with no terminal.
+#   A terminal gets a Rich bar (percent, transferred/total, speed, elapsed, ETA); otherwise one plain line
+#   every 10 s plus a final line, e.g. `upload big.csv: 42.0% 4.20/10.00 GiB, 67.30 MiB/s, elapsed
+#   0:01:03, ETA 0:01:27` (last line: `avg` speed + `done`/`failed`). stdout (the JSON envelope) is
+#   untouched. Speed/ETA use a trailing 30 s window; downloads count network (compressed) bytes and start
+#   the clock when the download starts, not during the export job; a sliced download with no sizes in
+#   its manifest shows bytes + speed only. Without the flag nothing changes: a transient bar only in
+#   human mode on a terminal. Terminal-only: no serve / SDK surface. Version gate in gotchas.md.
+kbagent storage add-column [--project NAME] --table-id ID --column COL:TYPE[(length)] [--not-null] [--default VALUE] [--branch ID]
+kbagent storage delete-table [--project NAME] --table-id ID [--table-id ...] [--force] [--dry-run] [--yes] [--branch ID]
+kbagent storage truncate-table [--project NAME] --table-id ID [--table-id ...] [--dry-run] [--yes] [--branch ID]
+kbagent storage delete-column [--project NAME] --table-id ID --column COL [--column ...] [--force] [--dry-run] [--yes] [--branch ID]
+kbagent storage delete-bucket [--project NAME] --bucket-id ID [--bucket-id ...] [--force] [--dry-run] [--yes] [--branch ID]
+# delete-bucket / file-delete (CLI-30): both read --yes. Without it they ask on a terminal (stdin and
+#   stderr are a terminal, --json off). --json, --dry-run and a session without a terminal never ask.
+#   A declined prompt exits 0 and deletes nothing. delete-bucket --force cascade-deletes tables only:
+#   a shared bucket (`sharing` set in the bucket detail) is never deleted, also not with --force or
+#   over REST (DELETE /storage/buckets/{project}?force=true). It gets a failed[] entry that names
+#   `kbagent sharing unshare --project ALIAS --bucket-id ID`, the other buckets are still processed,
+#   and the run exits 1. Version gate lives in gotchas.md.
+kbagent storage swap-tables [--project NAME] --table-id ID --target-table-id ID --branch ID [--dry-run] [--yes] [--timeout SECONDS]
+    # --timeout SECONDS on create-table and swap-tables (since 0.99.0, #713): both halves
+    #   of the repartition path move real data yet used to inherit the 60s metadata-job
+    #   budget, so a large BigQuery table reported STORAGE_JOB_TIMEOUT for a job that was
+    #   still running and would succeed. Default is now 300s on both. A local timeout
+    #   NEVER cancels the job -- it keeps running server-side. The error is
+    #   STORAGE_JOB_TIMEOUT, exit 4, retryable=false, details.job_id, and the message
+    #   names `storage job-detail --job-id ID --wait` (create-table also names
+    #   `storage table-detail`). Never re-run: a repeated swap swaps the tables back,
+    #   a repeated --source-table-id create starts a second copy.
+kbagent storage clone-table [--project NAME] --table-id ID --branch ID [--dry-run]
+# --branch 0 / --source-branch-id 0 (CLI-21): swap-tables --branch 0 swaps on the default branch ID it
+#   reads first (was: exit 5 "requires a branch"); clone-table --branch 0 is INVALID_ARGUMENT, exit 2, no
+#   API call (HTTP 400 over serve; the target must be a dev branch); create-table --source-branch-id 0
+#   omits source.branchId in a production request and sends the default branch ID in a dev-branch
+#   request (was: source.branchId 0). Version gate in gotchas.md.
+kbagent storage snapshot-create [--project NAME] --table-id ID [--description D] [--branch ID]
+kbagent storage snapshots [--project NAME] --table-id ID [--limit N] [--branch ID]
+kbagent storage snapshot-detail [--project NAME] --snapshot-id ID
+kbagent storage snapshot-delete [--project NAME] --snapshot-id ID [--snapshot-id ...] [--dry-run] [--yes]
+kbagent storage table-from-snapshot [--project NAME] --snapshot-id ID --bucket-id ID --name NAME [--branch ID] [--dry-run]
+# Snapshots (0.75.0+, #512): point-in-time table backup (data+columns+PK) and restore as a NEW table.
+#   table-from-snapshot goes through the classic tables-async endpoint (NOT tables-definition), --name is
+#   REQUIRED (API rejects empty), no overwrite -- restore under a new name, then swap/delete yourself.
+kbagent storage describe-bucket [--project NAME] --bucket-id ID (--description STR | --description-file PATH) [--branch ID]
+kbagent storage describe-table [--project NAME] --table-id ID (--description STR | --description-file PATH) [--branch ID]
+kbagent storage describe-column [--project NAME] --table-id ID --column NAME=DESC [--column ...] [--branch ID]
+kbagent storage describe-batch [--project NAME] --file YAML [--branch ID]
+kbagent storage describe-migrate [--project ALIAS] [--table-id ID ...] [--bucket-id ID] [--prune-orphans] [--dry-run] [--yes] [--branch ID]
+# Column descriptions (0.88.0+, #624): describe-column/describe-batch write through the native
+#   `PUT .../tables/{id}/definition` endpoint (async job) with `isDescriptionSystemManaged: false`
+#   (stops the next Output Mapping run from overwriting the text). The backend mirrors the value into
+#   `columnMetadata` `KBC.description`, so the UI, the MCP server and the Snowflake COMMENT /
+#   BigQuery description all see it. Before 0.88.0 kbagent wrote a flat `KBC.column.{name}.description`
+#   key on the TABLE's metadata -- read by nothing but kbagent, so documented columns looked blank
+#   everywhere else. Unknown column names now FAIL FAST before any write (behavior change; the flat
+#   write accepted typos silently). `table-detail` reads with precedence native definition ->
+#   columnMetadata KBC.description -> legacy flat key, always returns `legacy_column_descriptions`
+#   and warns in human mode when legacy keys remain; it never writes. `describe-migrate` converts
+#   legacy keys in bulk (scope: --table-id / --bucket-id / whole project; scan-then-confirm,
+#   --dry-run reports only; per-table errors accumulate). describe-column/describe-batch also migrate
+#   leftovers on the table they touch. Rules: a column whose visible description already differs is
+#   skipped as `conflict` (newer value wins), an entry for a dropped column is skipped as `orphan`
+#   unless --prune-orphans. Migrated flat entries are DELETED so a later clear cannot be resurrected
+#   by the read fallback.
+# describe-batch --file shape check (0.89.0+, #645, issue #640): the WHOLE file is validated
+#   before the first write. A tables:/buckets:/columns: section given as a list instead of a mapping
+#   of ID to description, a column entry that is not a mapping, a null description, a non-mapping
+#   document, or two keys colliding after str() coercion (1 vs "1") -> structured INVALID_ARGUMENT,
+#   exit 2, naming the key and its actual type; nothing is half-applied. Behavior change: before
+#   0.89.0 the same input raised an AttributeError traceback PARTWAY THROUGH the batch. Empty
+#   sections (absent, null, [], '', {}) stay silent no-ops; per-item API failures during
+#   application are still accumulated into errors[] (exit 1) -- shape is a usage error, an API
+#   refusal is not.
+kbagent storage files [--project NAME] [--tag TAG ...] [--limit N] [--offset N] [--query Q] [--branch ID]
+kbagent storage file-upload [--project NAME] --file PATH [--name NAME] [--tag TAG ...] [--permanent] [--branch ID] [--progress]
+kbagent storage file-download [--project NAME] [--file-id ID | --tag TAG ...] [--output FILE] [--progress]
+kbagent storage file-detail [--project NAME] --file-id ID
+kbagent storage file-delete [--project NAME] --file-id ID [--file-id ...] [--dry-run] [--yes]
+kbagent storage file-tag [--project NAME] --file-id ID [--add TAG ...] [--remove TAG ...]
+kbagent storage load-file [--project NAME] --file-id ID --table-id ID [--incremental] [--delimiter D] [--enclosure E] [--wait/--no-wait] [--timeout SECONDS] [--branch ID]
+kbagent storage job-detail [--project NAME] --job-id ID [--wait] [--timeout SECONDS]
+# storage job-detail (#834): read-class; shows a Storage API job (status, operation_name, table_id,
+#   file_id, times, imported_rows, warnings, results, error). Exit 0 success/waiting/processing, exit 1
+#   STORAGE_JOB_FAILED when the job ended in error (details still returned), exit 4 on --wait timeout.
+#   Job ids are project-scoped, independent of the active branch (no --branch). Serve:
+#   GET /storage/jobs/{project}/{job_id}?wait=&timeout=. Version gate for this entry lives in gotchas.md.
+kbagent storage unload-table [--project NAME] --table-id ID [--column COL ...] [--limit N] [--tag TAG ...] [--download] [--output FILE|DIR] [--file-type csv|parquet] [--branch ID] [--progress]
+
+# stream: Data Streams (OpenTelemetry/OTLP). Storage token from config (no manage token).
+# Control plane = stream.<region> (derived from connection.<region>); the OTLP ingest URL
+# (stream-in.<region>/otlp/<projectId>/<sourceName>/<secret>) is returned in source.otlp.url
+# with the secret in the path -- MASKED by default, --reveal to print it. create-source --type otlp
+# auto-provisions the logs/metrics/traces sinks (bucket in.c-otlp-<source>) so data lands; --no-sinks opts out.
+kbagent stream list [--project NAME] [--branch ID]
+kbagent stream create-source [--project NAME] --name NAME [--type otlp|http] [--branch ID] [--if-not-exists] [--no-sinks] [--reveal]
+kbagent stream detail [--source-id ID | --name NAME] [--project NAME] [--branch ID] [--reveal]
+kbagent stream delete --source-id ID [--project NAME] [--branch ID] [--dry-run] [--yes]
+
+kbagent lineage build --directory PATH --output PATH [--ai] [--refresh]
+kbagent lineage show --file PATH [--upstream NODE] [--downstream NODE] [--column COL] [--columns] [--project ALIAS] [--depth N] [--format text|mermaid|html|er]
+kbagent lineage info --file PATH
+kbagent lineage server --file PATH [--port N] [--host HOST]
+
+kbagent sharing list [--project NAME | --all-projects]
+kbagent sharing share [--project ALIAS] --bucket-id ID --type TYPE [--target-project ALIAS|ID ...] [--target-user EMAIL ...]
+# Input forms (CLI-48, #791, spec A4): a list option is repeated once per value and has a singular
+#   name. split_multi() in commands/_helpers.py reads it and refuses a comma in a value of an ID or
+#   fixed-value option (INVALID_ARGUMENT, exit 2, naming the option; 0.x took one comma string and a
+#   repeat kept the last value). Free-form options (--set, --var, --op, --secret, JSON, SQL) are not
+#   checked. 1.0.0 renamed the plural options (old name = removed form naming the new one): org setup
+#   --project-id, sharing share --target-project (alias or ID, resolved like the semantic-layer
+#   --target-project) / --target-user, semantic-layer add constraint --metric, edit constraint
+#   --new-metric, build --table-id, import/promote --type, workspace load --table-id, and --column of
+#   storage download-table/unload-table and token list.
+#   Input from files (spec I1/I2/I6), one rule like `git commit -m TEXT` / `-F FILE`: the main input
+#   file of a command is --file PATH; a JSON/YAML or text value is --<field> inline plus a sibling
+#   --<field>-file PATH; `-` as the PATH reads stdin. The two are mutually exclusive (usage error
+#   naming both). `@` never reads a file. Structured values go through structured_input() /
+#   parse_json_arg() / parse_json_file_arg() in commands/_helpers.py; an inline value `@path` or `-`
+#   is refused with a message that names --<field>-file. Text values go through text_input() /
+#   read_input_file(). 1.0.0 renamed (old name = removed form naming the new one): lineage
+#   show/info/server --load (-l) -> --file; storage describe-bucket/describe-table and project
+#   description-set --text/--file/--stdin -> --description/--description-file; branch metadata-set
+#   --text/--file/--stdin -> --value/--value-file; workspace query --file -> --sql-file; agent
+#   create/test --from-file -> --definition/--definition-file; flow new/update/validate --file ->
+#   --definition/--definition-file; encrypt values --input -> --values/--values-file; data-app
+#   secrets-set --secrets-file -> --secret-file. New --<field>-file siblings: config row-create/row-update
+#   --configuration-file, config state-set --state-file, component sync-action --config-data-file,
+#   http post/patch --body-file, merge-request resolve --resolved-file, transformation edit
+#   --storage-file, agent run --runtime-input-file, semantic-layer reference-data set --members
+#   (inline, next to --members-file), dev-portal create/patch --data (now inline JSON) + --data-file.
+#   Secrets keep --token-file/--token-stdin/--token-env, --git-pat-file/--git-pat-env, --password-stdin.
+#   The free-text options --description / --value of those commands and `transformation create --sql`
+#   refuse `@<existing file>` with INVALID_ARGUMENT, exit 2, naming --description-file / --value-file /
+#   --sql-file (RefuseAtFile in commands/_helpers.py, spec I3). A bad input value exits 2 naming the
+#   option, never a traceback. Version gate lives in gotchas.md.
+kbagent sharing unshare [--project ALIAS] --bucket-id ID
+kbagent sharing link [--project ALIAS] --source-project-id ID --bucket-id ID [--name NAME] [--stage in|out]
+kbagent sharing unlink [--project ALIAS] --bucket-id ID [--dry-run] [--yes]
+# sharing unlink is destructive-class (spec S1): it deletes the linked bucket from the project.
+#   It asks for confirmation (--yes skips it); --dry-run reads the bucket, checks that it is a
+#   linked bucket and deletes nothing. REST: POST /sharing/{project}/unlink/{bucket_id}?dry_run=,
+#   no prompt. Version gate lives in gotchas.md.
+kbagent sharing edges [--project NAME | --all-projects]
+
+kbagent org setup --org-id ID --url URL [--dry-run] [--yes] [--token-description PREFIX] [--refresh]
+kbagent org setup --project-id ID [--project-id ID ...] --url URL [--dry-run] [--yes] [--token-description PREFIX] [--refresh]
+
+kbagent billing credits [--project ALIAS ... | --all-projects]
+# billing credits (0.84.2+, issue #594 secondary ask): read-only PAYG credit balance, fanned out
+#   across the --project projects or, with --all-projects, all registered projects in parallel. A project
+#   without the `pay-as-you-go` owner.features flag never touches the billing host (NXDOMAIN on some
+#   non-PAYG stacks) -- it gets a per-project error_code PAYG_NOT_AVAILABLE instead; per-project
+#   failures degrade individually, the run never aborts. Rows report the API's native unit (credits)
+#   AND derived minutes (1 credit = 60 min, matching the Keboola UI). Purchase history / Stripe
+#   invoice IDs are NOT available here -- that data lives on connection.{stack}
+#   /pay-as-you-go/billing/*, which does not accept a Storage token (issue #594 primary ask, open).
+
+# feature: requires a super-admin Manage API token (inline hidden prompt; never persisted; --allow-env-manage-token for CI). --project resolves the stack URL (+ project_id for project ops) from config.
+kbagent feature list [--project ALIAS]
+kbagent feature project-show [--project ALIAS]
+kbagent feature project-add [--project ALIAS] --feature NAME [--dry-run] [--yes]
+kbagent feature project-remove [--project ALIAS] --feature NAME [--dry-run] [--yes]
+kbagent feature user-show [--project ALIAS] --email EMAIL
+kbagent feature user-add [--project ALIAS] --email EMAIL --feature NAME [--dry-run] [--yes]
+kbagent feature user-remove [--project ALIAS] --email EMAIL --feature NAME [--dry-run] [--yes]
+
+# token: scoped Storage tokens (Keboola single-bucket-write pattern; secret shown once).
+# create REQUIRES a MASTER (admin) token -- pre-flight MISSING_MASTER_TOKEN guard (exit 3)
+#   since #599: a non-master token with canManageTokens is CreateTokenVoter's "impossible state"
+#   and the API answers a generic 500. That defect is CREATE-ONLY: list/delete/refresh need only
+#   canManageTokens and are deliberately NOT guarded (RefreshTokenVoter also lets any token
+#   rotate itself), so rotating a leaked device token from an org-setup token keeps working.
+kbagent token list [--project NAME] [--with-last-used] [--column NAME ...]
+kbagent token create [--project NAME] --description DESC [--bucket-write BUCKET ...] [--bucket-read BUCKET ...] [--component-access ID ...] [--can-read-all-file-uploads] [--expires-in N]
+kbagent token delete [--project NAME] --token-id ID [--yes]
+kbagent token refresh [--project NAME] --token-id ID [--yes]
+# `token list` (issue #599): GET /v2/storage/tokens -- the only way to see what already exists and to
+#   get the id `delete`/`refresh` need, without the web UI. Secrets are STRIPPED from every row: a
+#   project with the `force-decrypted-token` feature has the API embed live values in the listing, and
+#   echoing those would break the group's "revealed once, at mint" contract for every token at once.
+# `--with-last-used` (0.88.0+, issue #622): answers which tokens are still IN USE -- the Storage API
+#   carries no `lastUsed` (only the Manage API's PAT response does), so it is DERIVED per token from
+#   GET /v2/storage/tokens/{id}/events, fanned out over max_parallel_workers. Opt-in: ONE EXTRA CALL
+#   PER TOKEN. Adds lastUsed / lastUsedEvent / lastUsedStatus + a top-level `errors`; the default
+#   shape is unchanged. Sorts dormant-first (reading order = cleanup order).
+#   The feed is narrowed SERVER-SIDE to `q=token.id:{id}` -- events the token PERFORMED. The raw feed
+#   also carries events performed ON the token, so a fresh token's newest raw event is its own
+#   storage.tokenCreated: `events[0]` reports never-used as "used today", exactly backwards. Filtering
+#   client-side instead breaks differently -- right after a rotation the one event a limit=1 fetch
+#   returns is that rotation, so the filter is left with nothing and calls an active token unused.
+#   lastUsedStatus separates `never` (minted INSIDE the ~6-month retention window, no activity =>
+#   proven) from `unknown` (older than retention => the API cannot say) from `error` (per-token lookup
+#   failed; row degrades, audit completes). Do not collapse never/unknown -- they lead to opposite
+#   decisions. DEV-BRANCH ACTIVITY IS INVISIBLE (the endpoint always resolves to the default branch:
+#   `idBranch == <production> OR NOT EXISTS idBranch`), so a branch-only token reads as dormant.
+# `--column` (0.88.0+ as --columns, renamed in 1.0.0; repeatable): selects/orders the human table;
+#   `Refreshed` is now a default column (--json always returned it). --json is deliberately NOT
+#   affected by --column.
+#   `last_used` / `last_used_event` REQUIRE --with-last-used (exit 2 otherwise): nothing was
+#   derived, so any rendered value would assert something never checked.
+# SDK (importable Client(url,token)) now exposes create_scoped_token / list_tokens / delete_token /
+# refresh_token / create_stream_source / get_stream_source / list_stream_sources /
+# delete_stream_source: dicts on .raw, typed ScopedTokenResult / TokenListEntryResult /
+# StreamSourceResult on the facade. See docs/sdk.md.
+
+# permissions: session write/destructive firewall. The top-level --deny-writes / --deny-destructive
+# flags are the one-shot form; `permissions set` persists a policy (mode allow|deny + allow/deny patterns
+# like cli:read, cli:write, cli:destructive). `tool:*` patterns are INERT since 0.85.0 (the MCP
+# passthrough is gone): they load but match nothing, so a mode=deny policy whose only allowance was
+# tool:read now denies everything. The agent guards rails against mistakes; not a sandbox.
+# `permissions set` (since 0.91.0, issue #688) validates every --allow/--deny pattern BEFORE the
+#   interactive confirmation: each must be a cli:* category, an exact operation name (incl. a
+#   flag-escalated string like "auth.logout --remove-projects"), or a glob matching >=1 known
+#   operation -- an unknown pattern (typo, fabricated category) is rejected with VALIDATION_ERROR,
+#   exit 2, listing every offending pattern (--json: error.details.invalid_patterns), and nothing
+#   is persisted. `permissions show` / `kbagent doctor` also generalized: they now flag ANY
+#   persisted pattern matching zero known operations, not only the retired tool:* namespace.
+#   PermissionEngine itself stays lenient at evaluation time -- only `permissions set` is strict.
+# (since 0.99.0, #655) The policy also firewalls the WHOLE `kbagent serve` REST surface: every
+#   route is classified in server/route_permissions.py and checked by one app-level dependency
+#   against the SERVED config dir's policy -> HTTP 403 error_code PERMISSION_DENIED, the same
+#   code the CLI exits on. On 0.98.0 and older only /auth/* (0.90.1+) and /merge-requests/*
+#   (0.94.0+) were checked and every other route executed unchecked. Routes that declare their
+#   own `require_permission(...)` (those two routers) are skipped by the table. An unclassified
+#   route is REFUSED, not exempted (a test keeps the table
+#   and the live app in sync both ways); bootstrap paths (/health/ping, /health/auth-info,
+#   /ui-config, /docs, /redoc, /openapi.json, SPA shell) are never checked. A path param
+#   that collapses CLI leaves is checked like the CLI: POST/PUT/DELETE
+#   /semantic-layer/items/{kind}[/{name}] check the parent key (`semantic-layer.add`) AND
+#   the leaf `semantic-layer.add.<kind>` (route_permissions.LEAF_PATH_PARAMS).
+#   A `--scope organization` semantic-layer write is destructive-class over REST too:
+#   the handlers of scope PUT, models, items/{kind} (per-kind leaf key), import, promote
+#   and build check `<key> --scope organization` (FLAG_ESCALATIONS) for a typed OR an
+#   inherited organization scope, like the CLI.
+#   `config variables-set --replace` is destructive-class (FLAG_ESCALATIONS); the CLI and
+#   PUT /configs/.../variables with `replace: true` both check it. `token refresh` and
+#   `workspace password` are destructive-class (the old secret stops working).
+#   `http get/post/patch/delete` (group callback, key `http.<verb>`) and `search` (top-level
+#   guarded set in cli.py) check the caller's own policy and --deny-* flags before any
+#   request. Version gate lives in gotchas.md (no `(since vNEXT)` on `# ` lines).
+#   `GET /permissions/show` (serve, since 0.99.0) reports the EFFECTIVE policy (persisted block
+#   merged with the daemon's --deny-* flags); read-only by design -- no REST route can widen
+#   the policy that constrains it, so `permissions set|reset` stay terminal actions on the host.
+kbagent permissions list [--category read|write|destructive|admin]
+kbagent permissions show
+kbagent permissions set --mode allow|deny [--allow PATTERN ...] [--deny PATTERN ...]
+kbagent permissions reset
+kbagent permissions check OPERATION
+
+# The `tool` group is GONE (removed in 0.85.0, epic #390 phase 3) -- so are `agent --type
+#   mcp_tool` and the `/mcp/*` serve routes. Every catalog tool has a native command; the
+#   historical tool-to-command map is docs/mcp-migration.md. Persisted `mcp_tool` agent tasks
+#   are kept as inert tombstones (never run, flagged by `agent list`, FAIL in `doctor`) --
+#   recreate them as `--type cli_command`.
+
+kbagent branch list [--project NAME | --all-projects]
+kbagent branch create [--project ALIAS] --name "..." [--description "..."]
+kbagent branch use [--project ALIAS] --branch ID
+# branch use: every command that then picks a branch names it -- `Target:` on stderr, `targets` in
+#   --json (branch_source explicit|active_branch|git_mapping|manifest|merge_request|production|none, plus
+#   project_source since CLI-45). Version gate in gotchas.md (#766).
+kbagent branch reset [--project ALIAS]
+kbagent branch delete [--project ALIAS] --branch ID [--dry-run] [--yes]
+kbagent branch metadata-list [--project NAME] [--branch ID|default]
+kbagent branch metadata-get [--project NAME] --key KEY [--branch ID|default]
+kbagent branch metadata-set [--project NAME] --key KEY (--value STR | --value-file PATH) [--branch ID|default]
+kbagent branch metadata-delete [--project NAME] --metadata-id ID [--branch ID|default]
+# branch merge was removed in 1.0.0 (deprecated since 0.94.0; it only built a UI URL and reset the
+#   active branch), with its REST route GET /branches/{project}/merge-url. Merge with the merge-request
+#   group below, or in the Keboola UI. The usage error names `kbagent merge-request`.
+
+# merge-request (since 0.94.0, DMD-1900): the non-SOX Branches 2.0 lifecycle. Hidden alias `mr`. Every
+#   command except list/create takes `[--merge-request-id N] [--branch B]` (1.0.0 removed `--id`): omitted, the target is
+#   the merge request OF the active branch (`branch use`) -- a branch has at most one MR, ever. Both flags at
+#   once -> exit 2. `--project` is single-project (never fans out). Status is the DERIVED state the web UI
+#   shows (in_development|in_review|approved|in_merge|merged|closed|rejected), never the raw one.
+kbagent merge-request list [--project A] [--state STATE]   # derived (in_development|in_review|approved|in_merge|merged|closed|rejected) or raw (development|published|canceled) states; `--help` lists them
+kbagent merge-request detail [--project A] [--merge-request-id N | --branch B] [--activity-log]
+kbagent merge-request create --title T [--project A] [--branch B] [--description D] [--reviewer-id ID ...] [--external-id X]
+kbagent merge-request update [--project A] [--merge-request-id N | --branch B] [--title T] [--description D] [--reviewer-id ID ...] [--external-id X]
+kbagent merge-request request-review [--project A] [--merge-request-id N | --branch B]
+kbagent merge-request approve [--project A] [--merge-request-id N | --branch B]
+kbagent merge-request request-changes [--project A] [--merge-request-id N | --branch B] [--reason TEXT]
+kbagent merge-request auto-merge --strategy immediately|scheduled|none [--at TS] [--project A] [--merge-request-id N | --branch B] [--yes]
+kbagent merge-request merge [--project A] [--merge-request-id N | --branch B] [--yes]
+kbagent merge-request conflicts [--project A] [--merge-request-id N | --branch B]
+kbagent merge-request diff --component-id C --config-id I [--project A] [--merge-request-id N | --branch B] [--format short|full] [--output PATH]
+kbagent merge-request resolve --component-id C --config-id I (--take ours|theirs|delete | --resolved JSON | --resolved-file PATH) [--project A] [--merge-request-id N | --branch B] [--change-description TEXT]
+# WHAT IS DESTRUCTIVE -- a property of the COMMAND, never of a flag or of the MR's state, so a policy is
+#   evaluated from the command name alone, before any network call. Destructive = anything that moves a
+#   merge request toward or into production: `merge` (deletes the source branch, rewrites production),
+#   `request-review` (on the non-SOX default of 0 approvals it lands the MR directly in `approved`),
+#   `approve` (the last approval is what a merge waits for), `resolve` (removes the blocker a merge waits
+#   on) and `auto-merge` (arms a backend scheduler that runs every `approved` MR whose strategy is
+#   immediately/scheduled through the same MergeProcessor, on its own, retrying every tick -- a DELAYED
+#   PRODUCTION MERGE with `merge` never called; `--strategy none` disarms and rides the same command, same
+#   class). Write = shapes the MR without moving it: `create`, `update` (title/description/reviewers/
+#   external id -- auto-merge is NOT a field here), `request-changes` (moves it AWAY from approved).
+#   So `--deny-destructive` yields an agent that can observe and shape merge requests but never move one.
+#   Under --json every destructive command REQUIRES an explicit target (--merge-request-id or --branch),
+#   checked before anything is resolved: every destructive kbagent command either prompts or is told its
+#   target, and --json has no prompt. In human mode the active-branch fallback stays; `merge` and arming
+#   `auto-merge` prompt (--yes skips), the other destructive commands do not. After request-review/
+#   approve/resolve on an MR that IS armed, human mode warns that the backend will now merge (read off the
+#   write's own result, no extra GET).
+#   On a non-SOX project with the default 0 required approvals: `merge` works straight from `development`;
+#   `request-review` lands directly in `approved` (in_review is unreachable); `approve` answers 422 in every
+#   state. There is NO `close`: `request-changes` by the creator is the UI's cancel and leaves the MR in
+#   `development` (the `closed`/`rejected` derivations depend on reviewer status a 0-approval project never
+#   populates -- same blind spot as the web UI, DMD-1988). Requesting review with no reviewers selected
+#   emails EVERY project member.
+#   Conflicts: `conflicts` lists what changed on both sides (isDeleted = the DEV side's flag); `diff`
+#   classifies per path (both / only you / only production) and, when a side deleted the config wholesale,
+#   recommends the --take; `diff --output FILE` writes `resolution_candidate` (your branch's content, all
+#   five keys: name/description/isDisabled/configuration/rows -- rebase REPLACES, a missing key wipes data,
+#   the service refuses a partial body) to edit and hand back via `resolve --resolved-file FILE`. No `--all`.
+#   Errors: a project without the feature answers FEATURE_NOT_ENABLED (exit 5) from every command whose
+#   target was resolved implicitly, reads included -- two wordings, missing feature vs SOX project. A
+#   scoped Storage token 403s (ACCESS_DENIED) on everything but `list`. `MR_MERGE_CONFLICT` /
+#   `MR_NOT_READY_TO_MERGE` (exit 1; the latter retryable) come from the merge 409. After
+#   MR_NOT_READY_TO_MERGE, `merge` reads the MR: state `published` (an earlier call merged it) answers
+#   status "already_merged", exit 0. The four state-change PUTs are never repeated by the HTTP layer.
+#   Version gate lives in gotchas.md. A truncated conflict
+#   list in the error carries `details.api_error_params_truncated: true` -- run `conflicts` for the full set.
+#   `merge` blocks for up to 10 minutes (no --wait/--timeout). Every result may carry `warnings[]`
+#   (post-merge cleanup failures, a dropped --change-description on a delete resolution). A merge whose
+#   source branch id could not be read carries `cleanup_skipped: true` + `branch_from_id_raw` (the local
+#   active-branch reset / sync unlink did NOT run -- key on the flag, not on warning text). On a project
+#   where the feature was later switched OFF, `list` rows' `allowed_actions` still recommend writes that
+#   will fail FEATURE_NOT_ENABLED (state-derived, feature-blind); `detail` carries `feature_enabled` and
+#   its hint-next respects it.
+
+kbagent workspace create [--project ALIAS] [--name NAME] [--backend TYPE] [--ui] [--read-only/--no-read-only]
+# workspace create (#755): a failed create -- headless or --ui -- moves the keboola.sandboxes
+#   config it created to the trash and says so (--json error.details: sandbox_config_id,
+#   sandbox_config_rolled_back, branch_id, job_id for --ui) -- except when the outcome is
+#   unknown, where the config is kept (sandbox_config_kept_reason: outcome_unknown): a 5xx, a
+#   read/write TIMEOUT or RETRY_EXHAUSTED on the create POST, or any error after the --ui job was
+#   queued other than QUEUE_JOB_FAILED / WORKSPACE_NOT_FOUND; the --ui job is queued on the branch
+#   the config lives in (was: default branch -> Queue 400 on a pinned dev branch). --ui itself
+#   still ends in WORKSPACE_NOT_FOUND on current SaaS stacks: the keboola.sandboxes `create` task
+#   dropped Snowflake/BigQuery provisioning in 2026-03 (the UI uses SQL Editor sessions), so the
+#   green job attaches no Storage workspace. Not a race -- do not retry; use headless. Version
+#   gate for this entry lives in gotchas.md (these `# ` lines parse as ATX headings).
+kbagent workspace list [--project NAME ... | --all-projects] [--orphaned] [--branch ID] [--qs-compatible]
+kbagent workspace detail [--project ALIAS] --workspace-id ID [--branch ID]
+kbagent workspace delete [--project ALIAS] --workspace-id ID [--dry-run] [--yes]
+kbagent workspace password [--project ALIAS] --workspace-id ID
+kbagent workspace load [--project ALIAS] --workspace-id ID --table-id TABLE_ID [--table-id ...] [--preserve] [--load-type clone|copy|view] [--force] [--timeout SECONDS]
+# workspace load (since 0.91.0, #687): DEFAULT is now per-table AUTO-DECIDE, mirroring the
+#   server's LoadTypeDecider -- zero-copy CLONE when eligible (same backend as the workspace,
+#   backend snowflake/bigquery, full load -- kbagent never sends filters here, no
+#   external-schema bucket, alias only when column-auto-sync is ON and unfiltered, and on
+#   BigQuery not an Analytics-Hub-linked bucket), otherwise plain COPY with a per-table
+#   `clone_ineligible_reason` in the JSON. Before this, kbagent always sent a bare COPY (the
+#   API's own default when loadType is omitted) -- a 282 GB table load burned warehouse credits
+#   for hours where CLONE is metadata-only and finishes in seconds.
+#   --load-type clone|copy|view FORCES the type for every table; an ineligible explicit choice
+#   fails loudly with the server's HTTP 400 message -- it never silently degrades to COPY.
+#   `view` is a zero-storage read-only view (BigQuery: any same-backend bucket; Snowflake: only
+#   external-schema buckets + the project feature `input-mapping-read-only-storage`).
+#   Size guard: a table resolved/forced to COPY whose dataSizeBytes exceeds 1 GiB requires
+#   interactive confirmation (TTY human mode) or --force (JSON/non-interactive) -- a huge copy
+#   never starts silently. --timeout SECONDS (default 300 here; other storage-job commands keep
+#   60): on timeout the error now says the job CONTINUES RUNNING server-side and keeps consuming
+#   resources, names the job id, and how to poll it (GET /v2/storage/jobs/{id});
+#   STORAGE_JOB_TIMEOUT now maps to exit code 4 (network/retryable) instead of 1. JSON result
+#   gains per-table `load_type` / `data_size_bytes` / `clone_ineligible_reason` plus a top-level
+#   `load_type_requested` (`auto` when the flag was omitted); existing keys are unchanged.
+#   Cheap alternative for analytics-only access: with the read-only input-mapping feature, a
+#   workspace can query production data directly via the `KBC_<STACK>_<PROJECT>` shared
+#   database (zero load, zero storage) -- `workspace query` works on it, no load needed.
+kbagent workspace query [--project ALIAS] --workspace-id ID --sql "SELECT ..." [--transactional] [--full] [--limit N]
+kbagent workspace query [--project ALIAS] --workspace-id ID --sql-file query.sql
+# query: default reads results inline via Query Service `GET .../results` (fast, JSON columns+rows),
+#   capped at --limit rows (default 500); pass --full for the complete CSV export (slower, uncapped).
+#   Each statement carries structured columns+rows + a synthesized csv_data (back-compat) since 0.59.0.
+kbagent workspace gc [--project NAME ... | --all-projects] [--dry-run] [--yes]
+# gc (CLI-28, T17): --project, --all-projects, or neither for the active project (both = USAGE_ERROR,
+#   exit 2). Over REST the same: without `project` and `all_projects=true`, the active project. A project whose sandbox
+#   configs cannot be listed goes to errors[] and nothing is deleted there. A NOT_FOUND listing counts as
+#   "no sandbox configs" only when the branch component listing confirms it. Version gate lives in gotchas.md.
+kbagent workspace from-transformation [--project ALIAS] --component-id ID --config-id ID [--row-id ID]
+
+kbagent data-app list [--project NAME ... | --all-projects] [--branch ID]
+kbagent data-app detail [--project NAME] --app-id ID [--branch ID]
+kbagent data-app create [--project ALIAS] --name NAME --slug SLUG (--git-repo URL | --use-managed-git-repo) [--description STR | --description-file PATH] [--git-branch main] [--git-public/--no-git-public] [--git-username USER] [--git-pat-env VAR | --git-pat-file PATH | --git-pat-encrypted KBC::Project...] [--auth password|public] [--size tiny|small|medium|large] [--auto-suspend SECONDS] [--type python-js|streamlit] [--workspace/--no-workspace] [--branch ID] [--no-deploy] [--wait] [--timeout SECONDS] [--keep-on-failure] [--dry-run] [--copy] [--reveal]
+# --workspace / --no-workspace (0.87.0+): DEFAULT ON. Writes runtime.workspace.enabled=true --
+#   the ONLY switch that makes the platform provision the ephemeral workspace and inject WORKSPACE_ID,
+#   QUERY_SERVICE_URL and KBC_WORKSPACE_MANIFEST_PATH. Every app that reads Storage needs it. Before
+#   0.87.0 kbagent never wrote it and offered no way to: such an app deploys, reports state=running and
+#   passes its health probe while being unable to read a row, and the PLATFORM reports nothing -- verify
+#   via `config detail` -> `configuration.runtime`, not by grepping `data-app logs` (a `Missing env vars:
+#   WORKSPACE_ID` line is the app's own output, so its absence rules nothing out; an app that does not
+#   check crash-loops behind the probe instead). It defaults ON because the opposite mistake -- an
+#   unused workspace on an app that never reads Storage -- is the cheap one; pass --no-workspace there.
+#   Omitting the flag writes NO `enabled: false` key: the body is byte-identical to pre-0.87.0.
+#   Not gated on any project feature -- the config option is the sole control. Retrofit an existing app:
+#   `config update --merge --set 'runtime.workspace.enabled=true'` then `data-app deploy` (pins latest).
+# Exactly one git source is required: --git-repo URL (external) OR --use-managed-git-repo (0.65.0+).
+# --use-managed-git-repo provisions an EMPTY Keboola-hosted repo (POST useManagedGitRepo:true), writes
+#   NO parameters.dataApp.git block, and forces --no-deploy (nothing to run yet). Mutually exclusive with
+#   --git-repo and all --git-*/PAT auth flags. Full flow to a RUNNING managed-repo app (0.65.0+):
+#   (1) create --use-managed-git-repo -> (2) `git-credentials-create --type http_token --permissions
+#   readWrite` + `git push` code to the managed repo URL (from `git-repo`) -> (3) `data-app deploy`.
+#   The platform injects the clone credentials at deploy time, so no credential wiring is needed.
+#   deploy pins the LATEST configVersion. For a PURE managed repo (no git block yet), it first
+#   backfills parameters.dataApp.git from the managed repo's URL, then pins the resulting version
+#   (CLI-15) -- omitting configVersion alone does NOT provision the app's workspace;
+#   grant provisioning is gated on that block's presence, not on configVersion. The deploy result
+#   reports it (`git_backfilled`, `git_branch`, `warnings[]`). The branch written is `--git-branch`;
+#   without it, `main` for an app with no runs, and a VALIDATION_ERROR before any write for an app
+#   with runs (branch unknown: pass `--git-branch` with the branch the code is on). It has no effect
+#   on a deploy that does not backfill. Push the managed repo's code to that branch.
+#   Version gate lives in gotchas.md (no `(since vNEXT)` on `# ` lines). Use `data-app runs`
+#   to debug a failed deploy (setup-phase failures produce no container logs).
+# data-app calls go to the Data Science /v2 App Deployments API: deploy = POST /v2/apps/{id}/deployments
+#   (pinned configVersion, --wait until it serves production), start = /resume, stop = /suspend
+#   (wakes on the next request). Output has no desired_state / last_start_timestamp.
+kbagent data-app deploy [--project NAME] --app-id ID [--config-version N] [--wait] [--timeout SECONDS] [--branch ID] [--git-branch BRANCH] [--copy] [--reveal]
+kbagent data-app start [--project NAME] --app-id ID [--wait] [--timeout SECONDS]
+kbagent data-app stop [--project NAME] --app-id ID [--wait] [--timeout SECONDS]
+kbagent data-app delete [--project NAME] --app-id ID [--yes]
+kbagent data-app password [--project NAME] --app-id ID [--copy] [--reveal] [--open]
+# data-app password: never prints the password unless --reveal, so it does not go into an AI
+#   agent's context. Project token only (static or session) -- the Manage token and its prompt are
+#   gone. In a terminal (human mode) it waits for `c` to copy (Enter/Esc/q finishes, 120 s timeout);
+#   without a terminal or with --json only --copy copies. Nothing copied -> exit 0,
+#   password_delivered_to null, ui_url = the Keboola UI page that shows it. --reveal + --copy =
+#   INVALID_ARGUMENT. Refuses a non-password app (VALIDATION_ERROR) and a null password (NOT_FOUND).
+#   serve: GET /data-apps/{p}/{app}/password takes no X-Manage-Token; ?reveal=true adds `password`.
+#   create --wait / deploy --wait deliver the password the same way once the app runs (shared
+#   CopyOption / RevealOption + deliver_password in commands/_data_app_password.py); there
+#   --copy / --reveal need --wait and a deploy (else INVALID_ARGUMENT, exit 2, no API call;
+#   --dry-run applies the same rules and adds a `password_delivery` plan). Without a flag and
+#   without the terminal prompt nothing is read (output as before). With a flag, JSON adds only
+#   ui_url / password_delivered_to / password (--reveal); any failed read after the deploy is a
+#   warnings[] entry, exit 0. The serve create / deploy routes are unchanged. BREAKING: scripts
+#   reading `.data.password` from `data-app password` must add --reveal.
+#   Version gate + agent rules: gotchas.md / AGENT_CONTEXT.
+kbagent data-app logs [--project NAME] --app-id ID [--lines N] [--since ISO8601]
+kbagent data-app runs [--project NAME] --app-id ID [--limit N]
+kbagent data-app secrets-set [--project ALIAS] --app-id ID --secret '#KEY=VALUE' [--secret ...] [--secret-file PATH] [--branch ID] [--allow-plaintext-on-encrypt-failure] [--dry-run] [--no-hint-next]
+kbagent data-app secrets-list [--project ALIAS] --app-id ID [--branch ID] [--show-fingerprint]
+kbagent data-app secrets-get [--project ALIAS] --app-id ID --key 'KEY' [--branch ID]   # '#' optional; plain values return their value, encrypted return metadata only
+kbagent data-app secrets-remove [--project ALIAS] --app-id ID --key 'KEY' [--key ...] [--branch ID] [--yes] [--dry-run]   # '#' optional
+kbagent data-app validate-repo --git-repo URL [--git-branch BRANCH] [--git-public/--no-git-public] [--git-pat-env VAR | --git-pat-file PATH] [--type python-js] [--strict]
+kbagent data-app git-repo [--project NAME] --app-id ID
+kbagent data-app git-credentials [--project NAME] --app-id ID
+kbagent data-app git-credentials-create [--project NAME] --app-id ID --type ssh_key|http_token --permissions readOnly|readWrite [--public-key KEY | --public-key-file PATH] [--name LABEL] [--yes]
+# git-repo introspects the deployed-from git repo (sandboxes-service /v2/apps/{id}/git-repo); it returns 409 "no Git repository configured" until the app has been DEPLOYED at least once (git config syncs Storage->DS record at deploy). git-credentials* manage credentials for a MANAGED repo only; apps from `data-app create --git-repo` are external => git-credentials-create returns 409. http_token mints a ONE-TIME secret (shown once); credentials endpoints need an admin storage token.
+
+kbagent component list [--project NAME | --all-projects] [--type TYPE] [--query QUERY]
+kbagent component detail --component-id ID [--project NAME]
+# component detail (since 0.90.0): the AI Service indexes the PUBLIC catalog only, so a private/
+#   deprecated component the project can run (keboola.mcp-server-tool, keboola.data-apps) 404'd
+#   there while `component list` showed it -- over `serve` as an HTTP 502. A NOT_FOUND now falls
+#   back to the project's Storage component catalog; `documentation_source` ("ai_service" vs
+#   "storage_catalog") tells the two apart and is present on BOTH paths. The fallback has NO
+#   configuration examples (examples_count/row_examples_count always 0, schema_summary counts 0
+#   unless the catalog entry ships a configurationSchema) -- check documentation_source before
+#   reading 0 as "this component has none". NOT_FOUND still raised when both sources miss; a
+#   non-404 AI Service failure is never masked. Over `serve`, ErrorCode.NOT_FOUND now maps to
+#   HTTP 404 (was 502) on EVERY route -- branch on error.code, not on the status alone.
+kbagent component sync-action ACTION_NAME --component-id ID [--project ALIAS] (--config-id ID [--row-id ID] | --config-data JSON | --config-data-file PATH) [--branch ID] [--timeout N]
+# sync-action (0.73.0+): POST sync-actions.{stack}/actions; ACTION_NAME freeform (component-defined,
+#   e.g. testConnection/getTables); --row-id shallow-merges row over root at TOP level only (row
+#   parameters/storage keys replace root wholesale, MCP parity -- NOT deep merge); --config-data
+#   sends explicit configData verbatim (skips fetch); branchId omitted from body for production.
+# sync-action (0.89.0+, #620): the ROOT configuration's `authorization` and `runtime` blocks are
+#   forwarded into configData too (root only -- a --row-id never overrides them; only when
+#   non-empty, so a component without them sends the pre-0.89.0 body). authorization.oauth_api.id
+#   is the broker reference the sync-actions service resolves + decrypts, so before 0.89.0 every
+#   sync action on an OAuth/Service-Account component (e.g. keboola.ex-linkedin-ads) failed with
+#   an opaque empty-body 400. MCP run_sync_action parity.
+kbagent config examples --component-id ID [--project NAME] [--row]
+kbagent config new --component-id ID [--name NAME] [--project NAME] [--output-dir DIR] [--push --no-files --description D --configuration JSON | --configuration-file PATH --no-validate --branch ID --dry-run --allow-plaintext-on-encrypt-failure]
+# config new --push --output-dir (0.89.0+, #644): the written scaffold now records the created
+#   config's ID (_keboola.config_id, quoted so numeric IDs stay strings) and is placed in the
+#   subtree of the branch the config was ACTUALLY created in (--branch or active branch;
+#   unregistered branches are added to the manifest like `sync pull --branch` would). Before,
+#   the scaffold had no ID and always landed in the default branch tree, so the next
+#   `sync push` created a DUPLICATE (34-config incident). With --configuration, the local file
+#   mirrors the pushed encrypted body -- placeholders would overwrite the remote on next push.
+#   The scaffold also records _keboola.base_config_hash (#792 E), the created config as the API
+#   returned it, so `sync diff` compares it 3-way and push never overwrites an edit made in the UI.
+#   Version gate in gotchas.md.
+
+# sync: GitOps -- configs as local files. init/pull/push/diff are filesystem-local (no serve REST surface).
+kbagent sync init [--project ALIAS] [--directory DIR] [--git-branching] [--adopt-existing] [--with-workspaces]
+# `sync init --with-workspaces` (CLI-25) sets the manifest key `syncWorkspaces`: pull/diff/push/clone then also sync shared SQL workspaces (keboola.sandboxes with no parameters.id and runtime.shared true; Python/R and legacy SQL sandboxes stay skipped), config only (services/_sync_workspace.py). A `push --force` delete removes the workspace's SQL editor sessions (Editor service, client/editor.py) before the config, `push --dry-run --force` lists them, and a plain push holds the delete back under skipped_deletions; clone warns about workspace input tables missing in the target. With --adopt-existing it turns the key on in an existing manifest. Version gate for this entry lives in gotchas.md.
+kbagent sync pull [--project ALIAS] [--all-projects] [--force] [--theirs] [--dry-run] [--with-samples] [--no-storage] [--no-jobs] [--job-limit N] [--branch ID]
+# `sync pull` auto-inits: if the target directory has no `.keboola/manifest.json`, pull runs `init` first, so a separate `sync init` is NOT needed for a first checkout. `sync pull --project X -d ./dir` on an empty dir writes the manifest and fetches the configs in one step.
+# `sync pull --force` is conflict-aware (since 0.53.0): locally-modified config whose remote is UNCHANGED is preserved (delta stays pushable, never silently re-stamped); a true merge conflict (local AND remote both changed since last pull) aborts (exit 1, SYNC_CONFLICT, --json lists details.conflicts); local-untouched + remote-changed takes remote.
+# `sync pull --theirs` (0.72.0+) is the supported reconcile path for a drifted tree: remote wins everywhere -- overwrites locally-modified configs/rows, restores deleted/missing files, resolves conflicts by taking remote (no abort). Since 0.72.0 plain pull also re-materializes a tracked config whose local dir was deleted (manifest<->disk invariant), so delete-dir-then-pull refetches; config-level isDisabled round-trips as sparse `is_disabled: true` in _config.yml (pull/diff/push).
+kbagent sync status [--directory DIR]
+kbagent sync diff [--project ALIAS] [--all-projects] [--directory DIR] [--branch ID]
+kbagent sync push [--project ALIAS] [--all-projects] [--dry-run] [--force] [--allow-plaintext-on-encrypt-failure] [--branch ID] [--no-name-drift-warnings]
+# sync push --force (#792): push deletes remote configs and rows ONLY with --force; a plain push lists them
+#   under skipped_deletions (+ skipped_deletions_reason), also in --dry-run, whose summary.deleted counts only
+#   what push would delete. A config/row deleted on the remote since the last pull diffs as remote_deleted and
+#   is never re-created (it lands in skipped). Version gate in gotchas.md.
+# sync diff/push strict local files: a _config.yml (config or row) that is not valid YAML, is
+#   empty / not a mapping, or has a top-level key outside version/name/description/is_disabled/
+#   parameters/input/output/processors/_configuration_extra/_keboola is an errors[] entry
+#   (change_type invalid_local_file, SYNC_LOCAL_FILE_INVALID, path). Its config and rows are held
+#   (never created, updated or deleted, also with --force) and diff/push exit 1; before, a broken
+#   tracked file read as deleted and push --force deleted the remote config (#827 item 9). Pull
+#   keeps such a file. A missing description: equals ''; _description.md plus a different inline
+#   description adds a DESCRIPTION_SHADOWED warning. `config new` writes top-level input/output,
+#   not storage:. Version gate in gotchas.md.
+# sync diff/push/pull and adopted files (#792 E): an untracked _config.yml whose _keboola.config_id
+#   exists on the target has no baseline unless it records _keboola.base_config_hash; without one a
+#   difference is a conflict (push skips it), two files with one id are both conflicts, and pull keeps
+#   such a file with local changes (skipped) -- only --theirs overwrites it. Version gate in gotchas.md.
+# sync push encryption (#792 F): every #-secret is encrypted before the first write, so an
+#   ENCRYPTION_FAILED stops push before anything reaches the remote (the message ends with "Nothing
+#   was pushed.") and a retry creates nothing twice. Version gate in gotchas.md.
+# sync push workspace delete (CLI-25): in a `syncWorkspaces` tree, a `push --force` that deletes a shared SQL workspace also deletes its SQL editor sessions (every user's, push branch) and their backend workspaces, which `config restore` does not bring back; `push --dry-run --force` lists them (warnings[] workspace_sessions), a plain push lists the workspace under skipped_deletions and touches no session. `--force` is destructive-class (FLAG_ESCALATIONS `sync.push --force`), so `--deny-destructive` / a cli:destructive deny blocks it while a plain push stays write-class. Version gate for this entry lives in gotchas.md.
+# Partial failures change the exit code (#745): commands that collect per-item failures
+#   and keep going exit 1 (was 0) when at least one item failed:
+#   `sync push`, `sync push/pull/diff --all-projects`, `sync clone` (also `bucket_errors`),
+#   `org setup`, `project refresh`, `project invite --file`, `workspace gc`,
+#   `semantic-layer import/promote/build/edit metric`, `storage describe-batch --json`,
+#   `flow schedule-remove` (new `errors[]` key, always present, empty when nothing
+#   failed; a partial failure fills it and exits 1; when every schedule delete
+#   fails it still raises `SCHEDULE_DELETE_FAILED`). Each of these, and the bulk
+#   `storage` deletes, `storage file-tag`, `job terminate`, `auth register-projects`,
+#   `token list --with-last-used`, `config detail` with several --project (now exit 1 on a failed
+#   project) and the fan-out reads, ends its human output with one headline on stdout (CLI-50,
+#   spec HO2), one form for all: `Success: 2 table(s) deleted.` /
+#   `Failed: 1 of 3 projects. 2 project(s) read.` Every failed item is one `Error: <item>: <message>`
+#   line on stdout before it (OutputFormatter.item_error / output.format_item_error), never a stderr
+#   warning; contract cases in tests/test_cli_contract.py refuse any other form.
+#   `sync push --all-projects` counts a project
+#   whose push returned `errors[]` in `summary.failed`. The --json payload is emitted
+#   BEFORE the exit; the items that succeeded stay written. A `--dry-run` of these
+#   exits 1 when it reports a failed item, like the real run. `sync diff --all-projects`
+#   exits 1 when a project failed. The other fan-out reads (`billing credits`, `job list`,
+#   `schedule list`, ...) exit 1 too (CLI-45). The helper is `finish_items()` in
+#   commands/_helpers.py: it emits the envelope or the per-item lines plus the headline,
+#   then exits 1 when an item failed. The contract case output.multi-item-headline
+#   allows `item_failure_exit_code()` only there. Version gate for this
+#   entry lives in gotchas.md -- the placeholder cannot be written on these `# ` comment
+#   lines (check_version_gates.py parses them as ATX markdown headings).
+# sync push (since 0.91.0, #686): the manifest baseline `pull_config_hash` is stamped from the API
+#   response (or a read-back), never from disk -- push-deployed multi-statement SQL transformations
+#   (and anything disabled in the UI whose local YAML lacks `is_disabled`) no longer show permanent
+#   phantom `~ REMOTE MODIFIED` drift in `sync diff`. Unreadable-after-write leaves the baseline
+#   UNTOUCHED + a `warnings[]` entry (never a disk-derived fallback). One canonical script[] shape now
+#   (one element = one statement) and `transform.sql` gains `/* ===== STATEMENT ===== */` markers when
+#   semicolons cannot recover the boundaries -- which also closes a SILENT pre-0.91.0 rewrite that
+#   collapsed such scripts to one statement (MULTI_STATEMENT_COUNT=1) while diff said "in sync".
+#   Migration: entries carry `metadata.config_hash_version`; unversioned ones match leniently (pre-0.91.0
+#   hash of the SAME remote counts as in sync, nothing else), and ONE `sync pull` per project migrates.
+#   A pre-markers tree whose only difference from the remote is the lost boundaries is REFUSED per-change
+#   with SYNC_LEGACY_BOUNDARY telling you to pull first; genuine edits push normally.
+# sync diff/push (0.89.0+, #649): local side read from exactly ONE tree (target branch subtree, else main/); entries tracked on another branch's tree are excluded from the changeset and reported under orphaned[] + summary.orphaned (reasons + reconcile hints); fix with sync pull. Adopt-by-id is branch-aware.
+# Ignored components (since 0.91.0, #689): keboola.mcp-server-tool joins keboola.sandboxes on ALWAYS_IGNORED_COMPONENTS (the MCP server's auto-created empty mcp-workspace-<hex> configs); the manifest field ignoredComponents (.keboola/manifest.json) is now LIVE and unions with the hardcoded set, honored by pull/diff/push. pull drops manifest entries + local dirs for a newly-ignored component, reported with action "ignored" (distinct from "removed" = deleted on remote); diff filters the local side too, so a stale dir for an ignored component can never classify as DELETED -- closes the delete-dir-then-push trap that used to destroy production keboola.mcp-server-tool configs.
+# sync pull/diff/push refuse a directory of another project (CLI-31): the manifest project.id and apiHost must
+#   match the --project project (also --all-projects), else CONFIG_ERROR (exit 5) naming both project IDs, before
+#   any API call. A project without a stored project_id costs one token verification call. Copy configs between
+#   projects with `sync clone`. Version gate lives in gotchas.md (no `(since vNEXT)` on `# ` lines).
+kbagent sync clone --source DIR --target ALIAS --target-dir DIR [--bucket-map FILE] [--variable-values FILE] [--instance-rename FILE] [--no-create-buckets] [--dry-run] [--branch ID]
+# `sync clone` (0.63.0+) copies a reference synced tree into a fresh target project + parameterizes it: applies bucket_map / variable_values / instance_rename overrides (JSON/YAML files), then pushes so every config CREATEs fresh -- keboola.flow and keboola.orchestrator task configIds (and configRowIds), schedule targets, and transformation variable and shared-code links are remapped reference->ULID by push Phase C/D (`link_remaps` counts each kind; a link it cannot set is an `errors[]` entry, and a failed PUT is sent again by the next push). Schedules are never activated and data apps never deployed: `warnings[]` (also on --dry-run, human mode prints them) lists those, copied `KBC::` values the target cannot decrypt, and tasks that run a config not in the tree. Only the run that creates the configs reports them; a re-run returns `warnings: []`. Idempotent: re-run with an existing --target-dir reports no_changes. Fails fast if the target already contains the reference's configs (clone needs a fresh target). Override files must be flat {id: scalar} mappings (0.89.0+): a nested mapping/list/null value is rejected with CONFIG_ERROR naming the key + actual type, instead of being silently stringified into a bogus ID. `--branch` is optional on a fresh clone. It defaults to the target's production branch, resolved from the API like `sync init`. An active branch set with `branch use` on the target wins over production. Pass `--branch` only to target a dev branch of the target. Clone recreates the reference tree's storage buckets in the target from the `storage/buckets.json` pull export BY DEFAULT -- `--no-create-buckets` skips it. Idempotent: an existing bucket is skipped, a per-bucket failure is collected in `bucket_errors`, a linked (shared) bucket is linked to the same source as in the reference (listed in `linked_buckets`; the source's sharing settings decide, a refused link lands in `bucket_errors`). Only the buckets are created, never their tables or data (the export carries no table data). Version gate in gotchas.md.
+kbagent sync branch-link [--project ALIAS] (--branch-id ID | --branch-name NAME) [--directory DIR]
+kbagent sync branch-unlink [--directory DIR]
+kbagent sync branch-status [--directory DIR]
+
+kbagent dev-portal identity add --alias A --username U [--password P | --password-stdin]
+                                [--role-hint vendor|admin] [--vendor V] [--portal-url URL]
+kbagent dev-portal identity list
+kbagent dev-portal identity remove --alias A
+kbagent dev-portal identity edit --alias A [--username U] [--password P|--password-stdin]
+                                 [--role-hint H] [--vendor V] [--new-alias N]
+kbagent dev-portal identity use ALIAS
+kbagent dev-portal identity current
+kbagent dev-portal identity verify [--identity A]
+
+kbagent dev-portal list --vendor V [--identity A]
+kbagent dev-portal get --app VENDOR.APP_ID [--identity A]
+
+kbagent dev-portal create --vendor V (--data JSON | --data-file PATH) [--identity A] [--dry-run]
+kbagent dev-portal patch --app VENDOR.APP_ID (--data JSON | --data-file PATH | --property KEY (--value V | --value-file F))
+                         [--identity A] [--dry-run]
+kbagent dev-portal upload-icon --app VENDOR.APP_ID --file PATH [--identity A] [--dry-run]
+kbagent dev-portal publish --app VENDOR.APP_ID [--identity A] [--dry-run]
+kbagent dev-portal deprecate --app VENDOR.APP_ID [--identity A] [--dry-run]
+# All writes require an interactive random-code TTY confirm; no --yes / no env bypass.
+# Since v0.51.1: --role-hint is validated (vendor/admin) and load-bearing -- admin identities route
+# `patch` to PATCH /admin/apps/{app} (permissive schema). Vendor + admin-only field => fail-fast preflight.
+# --password-stdin works on TTY (hidden prompt) AND on a pipe (reads to EOF).
+
+kbagent encrypt values [--project ALIAS] --component-id ID (--values JSON | --values-file PATH) [--output-file PATH]
+
+kbagent semantic-layer model list [--project P]
+kbagent semantic-layer model create [--project P] --name N [--description D] [--sql-dialect Snowflake] [--scope project|organization|targeted] [--target-project ALIAS|ID ...]
+kbagent semantic-layer model delete [--project P] --model M [--yes]
+kbagent semantic-layer show [--project P] [--model M] [--type dataset|metric|relationship|constraint|glossary]
+kbagent semantic-layer search-context [--project P] [--pattern G ...] [--type model|dataset|metric|relationship|constraint|glossary|all] [--limit N]
+kbagent semantic-layer schema [--project P] (--type model|dataset|metric|relationship|constraint|glossary [--type ...] | --all)
+kbagent semantic-layer get-context [--project P] --context-id ID
+kbagent semantic-layer validate [--project P] [--model M] [--deep]
+kbagent semantic-layer export [--project P] [--model M] [--output PATH]
+kbagent semantic-layer diff (--project-a A | --file-a PATH) (--project-b B | --file-b PATH) [--model-a M] [--model-b M]
+kbagent semantic-layer add metric [--project P] [--model M] --name N --sql SQL --dataset TABLE_ID [--description D] [--yes]
+kbagent semantic-layer add dataset [--project P] [--model M] --name N --table-id TABLE_ID [--description D] [--grain G] [--primary-key COL ...] [--deep-fields] [--fqn FQN]
+# dataset fqn (#761): `add dataset` and `build` read the fqn from the table's Storage location --
+#   the owning bucket's backendPath, surfaced as `sql_path` / `backend_path` on `storage table-detail`.
+#   They used to hardcode a "KEBOOLA" database that exists in no project, so every consumer pasting
+#   the fqn into SQL failed. A LINKED bucket's path names the SOURCE project's database + schema;
+#   swapping in the consuming project's database does not resolve either. `add dataset` now needs
+#   the table to exist (one table-detail call) unless `--fqn` supplies the value verbatim; a table
+#   whose location Storage does not report fails with VALIDATION_ERROR. `build --types-workspace`
+#   queries INFORMATION_SCHEMA in that same database/schema. `validate --deep` warns FQN_MISMATCH
+#   on stored fqns that differ (pre-fix models); repair via export -> fix fqn + metric sql -> import
+#   --overwrite. Version gate lives in gotchas.md (no `(since vNEXT)` on `# ` lines).
+kbagent semantic-layer add relationship [--project P] [--model M] --name N --from TABLE_ID --to TABLE_ID --on EXPR [--type left|inner]
+kbagent semantic-layer add constraint [--project P] [--model M] --name N --constraint-type inequality|equality|range|composition|exclusion|temporal|conditional --rule "EXPR" --metric M [--metric ...] [--severity error|warning|info]
+kbagent semantic-layer add glossary [--project P] [--model M] --term TERM --definition D
+kbagent semantic-layer edit metric [--project P] [--model M] --name N [--new-name N2] [--new-sql SQL] [--new-dataset TABLE_ID] [--new-description D] [--yes]
+kbagent semantic-layer edit dataset [--project P] [--model M] --name N [--new-name N2] [--new-description D] [--new-grain G]
+kbagent semantic-layer edit constraint [--project P] [--model M] --name N [--new-name N2] [--new-rule "EXPR"] [--new-constraint-type T] [--new-severity error|warning|info] [--new-metric M ...]
+kbagent semantic-layer edit relationship [--project P] [--model M] --name N [--new-name N2] [--new-from TABLE_ID] [--new-to TABLE_ID] [--new-on EXPR] [--new-type left|inner]
+kbagent semantic-layer edit glossary [--project P] [--model M] --term TERM [--new-term TERM2] [--new-definition D] [--yes]
+kbagent semantic-layer remove metric [--project P] [--model M] --name N [--yes]
+kbagent semantic-layer remove dataset [--project P] [--model M] --name N [--yes]
+kbagent semantic-layer remove constraint [--project P] [--model M] --name N [--yes]
+kbagent semantic-layer remove relationship [--project P] [--model M] --name N [--yes]
+kbagent semantic-layer remove glossary [--project P] [--model M] --term TERM [--yes]
+kbagent semantic-layer import [--project P] --file PATH [--model M] [--type T ...] [--dry-run] [--overwrite] [--scope project|organization|targeted] [--target-project ALIAS|ID ...]
+kbagent semantic-layer promote --from-project A --to-project B [--from-model M] [--to-model M] [--type T ...] [--dry-run] [--yes] [--scope project|organization|targeted] [--target-project ALIAS|ID ...]
+kbagent semantic-layer build [--project P] [--model M] --table-id TABLE_ID [--table-id ...] [--name N] [--dry-run] [--keep-on-failure] [--output PATH]
+kbagent semantic-layer token --encrypt [--project P] --component-id C
+# scope (PSGO-140, new): visibility scope for a semantic-layer item -- "project"
+#   (owner only), "organization" (every project in the org), or "targeted" (owner +
+#   explicit --target-project grants). --scope/--target-project are also accepted by `model
+#   create` and every `add <kind>` above. --scope omitted: `model create` makes a "project"
+#   item, `add <kind>` INHERITS its model's scope (an org-level model gets org-level children;
+#   a targeted model, its target projects); an inherited organization scope is permission-gated
+#   like a typed one, and a non-org-admin gets a 403 on it (pass --scope project). `import`,
+#   `promote` and `build --model` create their NEW items at the target model's scope the same way
+#   (same gate: FLAG_ESCALATIONS `semantic-layer.import|promote|build --scope organization`);
+#   `import` / `promote --scope` (+ --target-project) override it, e.g. `--scope project` for a
+#   non-org-admin under an org-level model; items they overwrite keep their own scope. Item names are unique per object type across ALL
+#   models of a project (ALREADY_EXISTS says "in this project"), so a model cannot be copied into
+#   a second model of the same project under the same item names. An item stored at schema version
+#   1.0.0 (created before 0.97.0) cannot be elevated: the error names the stored version and the
+#   fix (export, delete, create again, import). --target-project takes a registered alias OR a
+#   numeric project ID (repeated once per project; an alias must be on the owner's stack);
+#   without --scope targeted it exits 2. With --scope targeted and no --target-project: a real
+#   terminal launches an interactive picker over the other projects on the stack; --json fails
+#   fast (exit 2). A bad alias/ID/--scope/--type is a usage error (exit 2), never a traceback.
+#   Creating directly at --scope organization requires the organization-admin ROLE (403
+#   otherwise) -- an ordinary token instead uses `scope request-create` + an org-admin's
+#   `scope set --scope organization`. Elevation is ONE-WAY (no downgrade endpoint), which is why
+#   every `--scope organization` (here and on `model create` / `add <kind>`) is destructive-class
+#   (FLAG_ESCALATIONS). `edit`, `import --overwrite` and `promote` update in place (PUT): an item
+#   keeps its id, scope, grants and pending elevation request. `scope add|remove` merge into the
+#   grants client-side (not atomic; refused from a project that does not own the item, because
+#   the server hides the grants from a non-owner -- use `scope set --target-project` there).
+#   Verbs follow the CLI spec (#791): get / add / remove / set / request-create / request-cancel /
+#   request-list; `scope set` takes exactly ONE of --scope organization, --target-project (replace
+#   the whole list) or --clear. 1.0.0 renamed `request-delete` to `request-cancel` (spec S1: it
+#   cancels a pending request, no Keboola object is deleted; permission key
+#   semantic-layer.scope.request-cancel); the old name is a removed command (DEPRECATIONS).
+kbagent semantic-layer scope get [--project P] --type model|dataset|metric|relationship|constraint|glossary --context-id ID
+kbagent semantic-layer scope add [--project P] --type T --context-id ID --target-project ALIAS|ID [--target-project ...]
+kbagent semantic-layer scope remove [--project P] --type T --context-id ID --target-project ALIAS|ID [--target-project ...]
+kbagent semantic-layer scope set [--project P] --type T --context-id ID (--scope organization | --target-project ALIAS|ID [...] | --clear) [--dry-run] [--yes]
+kbagent semantic-layer scope request-create [--project P] --type T --context-id ID
+kbagent semantic-layer scope request-cancel [--project P] --type T --context-id ID
+kbagent semantic-layer scope request-list [--project P] --type T [--limit N] [--offset N]
+# scope over `kbagent serve`: GET/PUT /semantic-layer/scope/{context_id}, POST/DELETE
+#   .../target-projects, PUT/DELETE .../elevation-request, GET /semantic-layer/scope/elevation-requests;
+#   POST /semantic-layer/models and /items/{kind} take `scope` + `target_projects`.
+kbagent semantic-layer reference-data list [--project P] [--model M]
+kbagent semantic-layer reference-data get [--project P] (--reference-data-id ID | --dimension D)
+kbagent semantic-layer reference-data set [--project P] [--model M] --dimension D (--members JSON | --members-file PATH) [--dataset-id T] [--description X]
+kbagent semantic-layer reference-data delete [--project P] --reference-data-id ID [--yes]
+# Alias: `kbagent sl ...` (hidden) is equivalent to `kbagent semantic-layer ...`.
+# semantic-layer READS work with any valid, non-disabled, non-expired Storage token
+#   (0.97.0, PSGO-282): the Metastore no longer requires a master token for GET/List. WRITES
+#   (add/edit/remove/import/promote/build/scope add|remove|set) still need a project-admin token
+#   (master token or any admin-role user token) -- a non-admin token 403s on the write. Before
+#   PSGO-282 the Metastore's auth gate rejected EVERY valid non-master token, including reads,
+#   with an opaque 401 "Failed to create project scope" (#711, MasterTokenRequiredError swallowed
+#   server-side); kbagent still reclassifies exactly that 401 to MISSING_MASTER_TOKEN (exit 3) as
+#   a safety net for a deployment that predates the fix. Other unexplained 401s anywhere map to
+#   AUTH_REJECTED instead of the false "Invalid or expired token" (INVALID_TOKEN stays for 401s
+#   that DO blame the credential). Version gate for this entry lives in gotchas.md -- `(since
+#   0.97.0)` cannot be written on these `# ` comment lines (check_version_gates.py parses them as
+#   ATX headings).
+
+kbagent http get PATH [--timeout SECONDS]
+kbagent http post PATH [--body JSON | --body-file PATH] [--timeout SECONDS]
+kbagent http patch PATH [--body JSON | --body-file PATH] [--timeout SECONDS]
+kbagent http delete PATH [--timeout SECONDS]
+# `http` talks to the running `kbagent serve`. Requires KBAGENT_SERVE_URL +
+# KBAGENT_SERVE_TOKEN env vars (auto-injected into AI-agent / cli_command
+# subprocesses by the scheduler). Use this from inside a scheduled agent
+# task instead of forking another `kbagent` CLI process tree.
+
+kbagent agent list
+kbagent agent show --task-id ID
+kbagent agent create --name NAME [--description D] [--cron CRON] [--manual] [--enabled/--disabled] (--type ai_agent --cli CLI --prompt P [--extra-arg ARG ...] [--timeout SECONDS] | --type cli_command --argv ARG [--argv ARG ...] [--timeout SECONDS] | --definition JSON | --definition-file PATH) [--trigger-task-id ID --trigger-on success|error|always]
+kbagent agent update --task-id ID [--name N] [--description D] [--cron C] [--enabled/--disabled] [--manual/--auto] [--clear-trigger] [--trigger-task-id ID --trigger-on success|error|always]
+kbagent agent delete --task-id ID [--yes]
+kbagent agent run --task-id ID [--stream] [--runtime-prompt TEXT] [--runtime-input JSON | --runtime-input-file PATH]
+kbagent agent runs --task-id ID [--limit N]
+kbagent agent run-detail --task-id ID --run-id ID
+kbagent agent run-events --task-id ID --run-id ID
+kbagent agent test (--type ai_agent --cli CLI --prompt P | --type cli_command --argv ARG ... | --definition JSON | --definition-file PATH) [--name N] [--stream] [--timeout SECONDS]
+kbagent agent cron-preview --cron "0 6 * * 1" [--count N]
+kbagent agent prompt-improve --goal "..." [--draft "..."] [--cli claude|codex|gemini] [--project ALIAS] [--extra-arg X ...] [--stream/--no-stream]
+# `agent` reads/writes <config_dir>/agents.json directly (offline-first, no
+# serve required for CRUD + ad-hoc run). The cron loop that fires scheduled
+# tasks still requires `kbagent serve` running. Two action flavours
+# (ai_agent / cli_command) mirror the /agents REST surface
+# byte-for-byte. A task is --task-id, a run --run-id (run-detail /
+# run-events), like --job-id in the rest of the CLI (spec A3). 1.0.0
+# removed --id and the positional TASK_ID / RUN_ID: the usage error names
+# the option (`removed_argument()` entries in DEPRECATIONS).
+
+kbagent kai ping [--project NAME]
+kbagent kai preflight [--project NAME]
+kbagent kai ask --message "question" [--project NAME]
+kbagent kai chat --message "msg" [--chat-id ID] [--project NAME]
+kbagent kai chat-detail --chat-id ID [--project NAME]
+kbagent kai history [--project NAME] [--limit N]
+# Default-project resolution (since 0.93.0, #684): the `kai` group, `docs query`, `component detail`,
+#   `component list --query`, `config examples`, and `config new` (scaffold mode) resolve an omitted
+#   --project through the shared cascade (--project > KBAGENT_PROJECT env > `project use` pin > sole
+#   project). Before 0.93.0 these paths used the FIRST REGISTERED project and ignored the pin.
+#   Several projects with no pin now exit 5 (CONFIG_ERROR) instead of silently picking the first.
+#   Same fix over `kbagent serve`: /kai/*, POST /documentation/query, GET /components?query=...
+
+kbagent transformation create [--project NAME] --name NAME (--sql 'SELECT ...' | --sql-file PATH) [--created-table NAME ...] [--component-id ID] [--description D] [--branch ID] [--dry-run]
+kbagent transformation show [--project NAME] --config-id ID [--component-id ID] [--branch ID]
+kbagent transformation edit [--project NAME] --config-id ID --change-description TEXT (--op JSON ... | --op-file ops.json) [--storage JSON | --storage-file PATH] [--component-id ID] [--branch ID] [--dry-run]
+# transformation (0.73.0+): native SQL-transformation editing (port of MCP create/update_sql_transformation, #396).
+#   create: component derived from the project default_backend (snowflake|bigquery; other backends need
+#   --component-id); SQL split one-statement-per-script[] element; single block "Blocks"/code "Code";
+#   each --created-table T maps to out.c-<cleaned-name>.<T>. show: synthetic positional ids b{i}/b{i}.c{j};
+#   when --component-id omitted, all known SQL transformation components are tried. edit: 9 ops
+#   (add/remove/rename block+code, set_code, add_script, str_replace) applied sequentially against
+#   batch-start ids -- ALWAYS `transformation show` first, ids renumber after structural ops;
+#   --storage REPLACES configuration.storage wholesale; --dry-run previews without PUT.
+
+kbagent docs query "QUESTION" [--project NAME]
+# (0.73.0+) Documentation Q&A via the AI Service (server-side RAG). Unlike kai ask it does NOT
+#   see project data; works with any token. --json emits {query, text, source_urls}.
+
+kbagent flow list [--project NAME | --all-projects] [--branch ID] [--with-schedules]
+kbagent flow detail [--project NAME] --flow-id ID [--branch ID]
+kbagent flow schema [--full [--project NAME]]
+kbagent flow examples [--component-id keboola.flow|keboola.orchestrator]
+kbagent flow validate (--definition YAML | --definition-file PATH) [--project NAME]
+kbagent flow new [--project NAME] --name NAME [--description D] [--definition YAML | --definition-file PATH] [--branch ID]
+kbagent flow update [--project NAME] --flow-id ID [--name N] [--description D] [--definition YAML | --definition-file PATH] [--branch ID]
+kbagent flow delete [--project NAME] --flow-id ID [--branch ID] [--yes]
+# flow delete: the same locate-first soft delete as `config delete` -- a flow already in the trash
+#   answers status "already_in_trash", exit 0, and no second DELETE (it would purge). Version gate
+#   lives in gotchas.md.
+kbagent flow schedule [--project NAME] --flow-id ID --cron "0 6 * * *" [--timezone TZ] [--disabled] [--branch ID]
+kbagent flow schedule-remove [--project NAME] --flow-id ID [--branch ID] [--yes]
+kbagent flow triggers [--project NAME] --flow-id ID [--branch ID]
+# flow triggers (#714): the honest answer to "what starts this flow automatically". A flow has at
+#   least three trigger mechanisms and kbagent used to see ONE: `schedule list` / `search` only ever
+#   read `keboola.scheduler` configs, so a flow driven by a TABLE TRIGGER came back "nothing found"
+#   and got reported as having no trigger -- twice in one investigation, for a flow that was already
+#   live. Table triggers are a SEPARATE Storage API resource (`GET /v2/storage/triggers`), not a
+#   component config, which is why nothing in kbagent saw them. This command returns cron_schedules
+#   AND table_triggers in one call.
+#   CROSS-PROJECT triggers (a trigger-queue app config in ANOTHER project) are NOT covered: the
+#   result carries `cross_project_triggers_checked: false`, deliberately NOT an empty list -- an
+#   empty list reads as "checked, found none", which is the exact false negative this exists to
+#   prevent. Read that flag before concluding a flow has no trigger.
+#   PRODUCTION ONLY: the Storage triggers route is declared `isAvailableInBranch: false`, so it has
+#   no branch-scoped variant. `--branch` narrows the CRON half only; `table_triggers_branch_scoped`
+#   is always false.
+#   `lastRun: null` means the trigger exists but has NEVER FIRED -- not that it is disabled.
+#   `schedule list` / `schedule find` now say "No cron schedules found. Table triggers and
+#   cross-project triggers were NOT checked -- see `kbagent flow triggers`" instead of the old
+#   "No schedules found".
+#   `job detail` on a keboola.flow / keboola.orchestrator job carries `trigger_hint` (same over
+#   `serve`): a run with no matching cron schedule is NOT necessarily manual -- check
+#   `flow triggers` first. Human mode adds "Created by token" (job provenance).
+# Flows are conditional flows (keboola.flow). keboola.orchestrator is NOT supported (dropped 0.57.0).
+# IDs are strings; phases use next[].goto + conditions; tasks are typed (job/notification/variable).
+# flow new/update validate against the live CF schema fetched from the stack (AI Service
+#   configurationSchema for keboola.flow; NOT bundled) -> INVALID_FLOW_DEFINITION on failure.
+#   Schema-fetch failure (network/empty) does NOT block the write: structural check skipped,
+#   semantic checks still run, a "structural schema validation skipped" warning is surfaced.
+# flow validate: with --project fetches the live schema (full validation; fetch failure ->
+#   semantic-only + note); without --project runs semantic-only + a note. flow schema --full:
+#   with --project fetches the live schema (source=live); without --project serves the bundled
+#   authoritative snapshot (source=bundled, 0.73.0+). Plain flow schema is the offline YAML template.
+# flow examples (0.73.0+): bundled example flow configs (vendored from keboola-mcp-server), offline.
+#   Default keboola.flow; keboola.orchestrator serves legacy examples informational-only (kbagent
+#   cannot create/edit orchestrator flows). --json emits the bare list of configs.
+# flow schedule (0.66.1+) also activates the config on the Scheduler Service so the cron fires;
+#   activation failure keeps the config written, sets activated=false + warning, exit stays 0.
+#   flow schedule-remove deregisters from the service before deleting each config.
+# Execute a flow with: kbagent job run --project NAME --component-id keboola.flow --config-id ID
+
+kbagent schedule list [--project NAME ... | --all-projects] [--enabled-only] [--branch ID]
+kbagent schedule detail [--project NAME] --schedule-id ID [--branch ID]
+kbagent schedule find [--cron-window START-END] [--not-run-since DAYS] [--project NAME ... | --all-projects] [--branch ID]
+
+kbagent notification list [--project NAME ... | --all-projects] [--event NAME] [--component-id ID] [--config-id ID]
+kbagent notification detail [--project NAME] --subscription-id ID
+kbagent notification create [--project ALIAS] --event NAME --channel email|webhook --address ADDR [--component-id ID] [--config-id ID] [--branch ID] [--expires-at TS]
+kbagent notification delete [--project ALIAS] --subscription-id ID [--yes]
+kbagent notification replace-recipient [--project ALIAS] --subscription-id ID --address NEW_ADDR [--channel email|webhook] [--yes]
+# notification WRITE path (since 0.91.0, #690): the group is no longer read-only.
+#   --address carries the email address (--channel email) OR the webhook URL (--channel webhook) --
+#   channel-discriminated on the wire, same as the read path's single `address` column. An invalid
+#   --channel is a structured INVALID_ARGUMENT, exit 2. `create` WITHOUT --branch writes NO branch.id
+#   filter, unlike the UI which always writes one; an absent filter does not constrain matching, so
+#   such a subscription fires for jobs on EVERY branch.
+#   `replace-recipient` is delete+recreate -- the API has NO update primitive. It creates the NEW
+#   subscription FIRST, then deletes the old one, so a NEW subscription_id is ALWAYS minted (scripts
+#   must not cache the old one; the result carries old_subscription_id + new_subscription_id). A
+#   failed delete leaves a recoverable DUPLICATE, surfaced as `old_deleted: false` + a warning --
+#   never a lost subscription.
+#   Permission classes: notification.create = write, notification.replace-recipient = write,
+#   notification.delete = destructive. So --deny-writes blocks all three; --deny-destructive blocks
+#   only `delete`. `delete` / `replace-recipient` prompt for confirmation unless --yes (or --json).
+# notification READ path (0.86.0+, #600): read-only audit of Notification Service subscriptions -- the
+#   recipients behind the Flow Builder's Notifications tab (bell icon). They live in a SEPARATE
+#   platform service (notification.{stack}, plain Storage token, no elevated scope), NOT in the
+#   flow's configuration JSON, so `flow detail` / `config detail` never showed them. The in-flow
+#   `type: "notification"` TASK is a different mechanism and stays visible there.
+#   Event names are kebab-case (job-failed, job-succeeded, job-succeeded-with-warning,
+#   job-processing-long + phase-job-* variants); --event is NOT validated (the API declares
+#   EventName as an open string). The service ACCEPTS ?event= and then IGNORES it (200 + the
+#   full list, verified live), so kbagent sends it AND narrows client-side -- a direct API
+#   caller must do the same or get a superset. Filter fields are dotted paths into the event
+#   payload (job.component.id, job.configuration.id, branch.id, phase.id) -- --component-id /
+#   --config-id likewise match CLIENT-SIDE. A subscription with
+#   NO filters is project-wide and fires for EVERY job; those are dropped by --component-id/
+#   --config-id and counted in `project_wide_excluded` (plus a warning) so "who gets paged for
+#   this flow" is never silently under-reported. Webhook recipients carry `url`, email carries
+#   `address` -- both render in the single `address` column. The Branch column is populated on
+#   EVERY row, production included: the UI always writes a branch.id filter, and for production
+#   that value is the DEFAULT branch's numeric id -- compare against `branch list` to tell a
+#   production alert from a dev-branch one; presence alone means nothing.
+
+kbagent context [GROUP]
+# context (CLI-52, spec AG1): the command part of AGENT_CONTEXT is generated -- `make cli-manifest`
+#   writes commands/_context_commands.py from docs/cli-manifest.json (one section per top-level group
+#   or command: usage lines and the first help paragraph). Blocking rule help.context-from-manifest
+#   compares it with the manifest. Hand-written notes per group go to GROUP_NOTES in
+#   commands/context.py. GROUP prints one section (an alias such as mr works). An unknown GROUP is
+#   INVALID_ARGUMENT, exit 2, listing the valid ones. --json adds data.group. Version gate in gotchas.md.
+kbagent init [--from-global] [--project ALIAS ...]
+# `--project ALIAS` (repeatable) copies only the named project(s) from the global config and implies --from-global.
+kbagent doctor
+# `doctor` includes an `mcp_tool_tasks` check: it FAILs on scheduled agent tasks still
+# using the removed `--type mcp_tool` (they are inert tombstones that never run again).
+# `agent list` marks those rows and adds a per-task `deprecation` key in --json. Recreate
+# each as `--type cli_command` using the map in docs/mcp-migration.md.
+# `doctor` has no `--fix` since 0.85.0 -- it only ever installed keboola-mcp-server.
+kbagent version [--beta]
+kbagent update [--beta] [--major]
+# Major gate (CLI-40, #791 section 4.3): the updater (startup hook, `update`, `version`) reads
+#   /releases/latest (the list /releases?per_page=100 only for --beta or when latest names a higher
+#   major) plus /releases/tags/v<N+1>.0.0 at most once per 24 h, and stays on the running major. It installs the next major only at M
+#   (published_at of the GitHub release v<N+1>.0.0 + 28 days, "now" = the GitHub Date header) or
+#   with `update --major`; `--beta` alone never crosses. A crossing always goes through the deferred
+#   helper (update_runner.py; /bin/sh + pgrep on POSIX, PowerShell on Windows): the command finishes
+#   on the old major, no re-exec, a running `serve` holds it (helper gives up after 900 s). While
+#   v<N+1>.0.0 exists the DEPRECATED_VERSION notice shows: stderr once per 24 h and every run in the
+#   last 72 h before M; always in version/update/doctor/context; under --json a top-level warnings[]
+#   entry on every run (update_notice.py keeps it at module level, output.py adds it to both
+#   envelopes). Cache keys next_major_version/_release_id/_published_at, checked_at,
+#   notice_shown_at; a cached latest_version of a higher major is ignored; `version --beta` no
+#   longer writes the cache. Version gate lives in gotchas.md.
+# 1.x updater and the crossing (CLI-51, #791 section 4.4): when /releases/latest names a LOWER
+#   major (a 1.x client before M), the updater reads the first page of the release list and takes
+#   the highest stable release of its own major (pre-releases only with --beta). The cache file is
+#   per major: version_cache.json (0.x), version_cache_v<N>.json (N >= 1). An automatic update
+#   to a higher major (KBAGENT_UPDATED_FROM, or the claimed marker of a finished deferred update
+#   with major_flag not true) writes crossing_pending.json in the state dir. Until the first
+#   write/destructive command (permissions.py class, not admin) every read gets a warnings[] entry
+#   UPDATED_ACROSS_MAJOR. That command claims the file with os.replace and exits 6 with
+#   UPDATED_ACROSS_MAJOR, from check_cli_permission() (update_crossing.py). Fail open on any I/O
+#   error. Not for serve REST routes. The banner lists the BREAKING: notes of every crossed version. Under --json
+#   the first command adds UPDATED_ACROSS_BREAKING. Version gate lives in gotchas.md.
+# `--beta` (or env `KBAGENT_INCLUDE_PRERELEASE=1`) opts into pre-release versions
+# (PEP 440 betas/rc, e.g. 0.43.0b1). Default (no flag) is stable-only -- auto-update
+# startup hook never silently lands on a beta.
+# Since 0.60.0 install + self-update prefer a prebuilt wheel Release asset (fast, no
+# source build; falls back to git+ when absent). Env `KBAGENT_UPDATE_TIMEOUT` (integer
+# seconds, default 300) raises the self-update subprocess timeout for the slow git+
+# fallback on WSL. Bootstrap install: `curl -LsSf .../main/install.sh | sh`.
+# Since 0.79.0 a STANDALONE (PyInstaller) binary (choco/winget/brew/apt/dnf/zip) refuses
+# the kbagent self-update stage and reports that channel's own command instead -- a uv/pip
+# reinstall would install a SECOND, unrelated kbagent that shadows it on PATH. `version
+# --json` gains additive `install_channel` + `upgrade_hint`; `upgrade_command` is empty for
+# a hand-unpacked archive. Since 0.88.0 `upgrade_command` is ALSO empty whenever `up_to_date`
+# is not `false` (i.e. `true` or `null`) -- it used to be built unconditionally, so a caller on
+# a pre-release got `up_to_date: true` beside a pinned `--force --reinstall` command for the
+# older STABLE wheel (a silent downgrade), and an unreachable feed got an unpinned `git+`
+# default-branch install. Gate on `up_to_date is False`, never on the string being present. Since 0.85.0 `update` handles kbagent ONLY -- keboola-mcp-server
+# is no longer installed or refreshed by kbagent (see docs/mcp-migration.md for the manual
+# `uv tool install --upgrade --prerelease=allow keboola-mcp-server` command). Self-update
+# completes discovery first, then does the terminal exact-version reinstall and immediately
+# re-executes; failures print a copy-paste recovery command.
+kbagent changelog [--limit N] [--full]
+# Default shows first sentences: every BREAKING note of a version, plus its first other notes until at least two show; --full expands every note.
+kbagent serve [--host HOST] [--port PORT] [--ui] [--ui-dist PATH] [--reload] [--log-level LVL] [--cors-origin ORIGIN] [--config-dir DIR] [--no-banner]
+# serve REST parity (CLI-49, spec V2/V3/V4/V8/V9): the 26 routes whose command applies the active branch
+#   (storage writes + table-download, job run/terminate, transformation, config variables, component
+#   sync action) call resolve_branch in the service, so an omitted branch_id is the active branch.
+#   branch_id 0 is production. server/response_meta.py: one ASGI middleware opens a per-request target
+#   record (effective_branch ContextVar) and adds the Kbagent-Targets / Kbagent-Warnings JSON headers. The
+#   error body adds targets, warnings and error_type/project/retryable, and its HTTP status comes from
+#   ERROR_CODE_TABLE (http_status_for). project use / branch use / branch reset add active_project_set /
+#   active_branch_set / active_branch_cleared and an ACTIVE_CHOICE_SHARED warning. PATCH for semantic-layer
+#   items, merge-request update, data-app secrets and the variables merge (extra fields -> 422). 1.0.0
+#   removed the old PUT: it answers HTTP 405, and the message (a DEPRECATIONS entry with removed_in,
+#   removed_route_message / removed_form_error in response_meta.py) names PATCH. PUT .../variables with
+#   replace: true stays the full replace. `refresh_all` in POST /org/refresh answers 422 naming all_projects. List routes that read several projects take all_projects=true; without it and
+#   without project they use services/base.resolve_fanout_aliases (the T1 chain, shared with the CLI
+#   fanout_projects). A destructive or admin route (route class or flag escalation, response_meta.note_operation)
+#   on the active branch adds TARGET_FROM_ACTIVE_CHOICE (hint branch_id=<id>). Version gate in gotchas.md.
+# serve dry_run (CLI-33): a POST/PUT/PATCH/DELETE route answers HTTP 422 (HTTP_ERROR) when the
+#   request sends `dry_run` in the query string or as a top-level JSON body key, and the route does
+#   not declare it there. Before, the route ignored it and ran the real write.
+#   A false value (false/0/no/off/f/n in any case, or JSON false/0) is ignored and the real write runs.
+#   Any other value (true, null, an unknown string) is refused.
+#   One app-level dependency does this: reject_undeclared_dry_run in server/dependencies.py.
+#   Not checked: GET routes, nested keys, multipart upload bodies, and a body above 1 MiB (or without
+#   Content-Length) on a route that has no body parameter. Version gate lives in gotchas.md.
+# `--config-dir` on serve (since 0.91.0, #679): `serve` is the only subcommand with a --config-dir of
+#   its own, and most specific wins -- `serve --config-dir X` beats a root `kbagent --config-dir Y`,
+#   which in turn beats KBAGENT_CONFIG_DIR / the .kbagent walk-up / global. Passing both is NOT an
+#   error. Up to 0.90.1 the ROOT flag was ignored by serve entirely, silently: `kbagent --config-dir A
+#   serve` exposed a different project set than the caller named, and (since 0.90.1's /auth/*
+#   enforcement) applied a different directory's `permissions` policy. On <=0.90.1 always pass
+#   --config-dir to `serve` itself. Only an explicit root flag propagates -- an env-var/walk-up/global
+#   resolution is left to the server, which reaches the identical directory on its own.
+# `--no-banner` (since 0.90.0): suppress the web UI's "What's new" popup. The UI shows a curated
+#   per-version highlights modal once per version (localStorage `kbagent.whatsnew.seen`); this flag
+#   turns the UNSOLICITED popup off fleet-wide. Surfaced to the SPA via `GET /ui-config`
+#   ({"banner": bool}) -- NOT injected into index.html: that injection point was removed in favour of
+#   the session cookie, and an injected copy would miss the StaticFiles fallback that serves the shell
+#   for deep links, silently re-enabling the popup the operator suppressed. The command palette's
+#   "What's new" action still opens it on request -- the flag governs what appears uninvited.
+```