keboola-cli 0.99.1__tar.gz → 0.100.2__tar.gz

{keboola_cli-0.99.1 → keboola_cli-0.100.2}/CLAUDE.md

@@ -206,7 +206,7 @@ from that branch -- the branch temporarily *is* the release PR.
 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 calls `/releases/latest`, which GitHub defines as "the most recent non-prerelease, non-draft release". Marking the release `--prerelease` makes it invisible to the auto-update path.
+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):**
@@ -237,7 +237,7 @@ When the beta cooks long enough, merge the PR (stable squash) and ship `0.44.0`
 - 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 always uses `/releases/latest` (stable channel). Beta installs only come from explicit `kbagent update --beta`.
+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".
 
@@ -253,9 +253,9 @@ Full author checklist: see `CONTRIBUTING.md` > "Releasing a beta (pre-release) v
 
 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.
+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. **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.
 
 7. **Token masking**: tokens are never printed in full. Use `mask_token()` from `errors.py`.
 
@@ -319,6 +319,8 @@ Full author checklist: see `CONTRIBUTING.md` > "Releasing a beta (pre-release) v
     test's `NOT_AN_ALIAS` list; an option with any other name (like
     `sync clone --target`) needs that decision by hand.
 
+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.
@@ -334,7 +336,7 @@ The plugin lives here in `plugins/kbagent/` and is **published through `keboola/
 
 **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.
+**`.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.
 
@@ -397,6 +399,12 @@ kbagent auth login-password --email EMAIL (--password PASSWORD | --password-stdi
 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
@@ -511,13 +519,19 @@ kbagent project add --project NAME --url URL [--token-stdin | --token-file PATH
 kbagent project list
 kbagent project remove --project NAME
 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]
+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 [--dry-run] [--force] [--yes] [--token-description DESC] [--token-expires-in N]
 kbagent project description-get --project NAME
 kbagent project description-set --project NAME [--text STR | --file PATH | --stdin]
 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). Existing keys and the `pin`
+#   source value are unchanged. 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 --from-csv FILE [--default-role ROLE] [--workers N] [--dry-run]
@@ -527,9 +541,9 @@ kbagent project invitation-cancel --project ALIAS --email EMAIL [--invitation-id
 kbagent project member-remove --project ALIAS --email EMAIL [--yes]
 kbagent project member-set-role --project ALIAS --email EMAIL --role admin|guest|readOnly|share
 
-kbagent config list [--project NAME] [--component-type TYPE] [--component-id ID] [--branch ID] [--include-rows]
+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] [--component-type TYPE] [--ignore-case] [--regex] [--branch ID]
+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|@file|-] [--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]
@@ -584,7 +598,11 @@ kbagent config clone --project P --component-id ID --config-id ID --name NAME [-
 #   how you discover what to gather. Storage bucket/table IDs are copied VERBATIM, never remapped
 #   (`sync clone` is the command that remaps).
 
-kbagent search QUERY [--project NAME] [--type table|bucket|config|flow|data-app|transformation] [--search-type textual|config-based] [--regex] [--scope PATH ...] [--limit N]
+# --all-projects (CLI-36): on the 18 fan-out reads that read all projects without --project; until 1.0.0 the
+#   same as an omitted --project, with --project USAGE_ERROR (exit 2). --json envelopes gain an optional
+#   top-level `warnings` list ({code, message, ...}), not the same as `data.warnings`. Details and 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.
@@ -594,7 +612,7 @@ kbagent search QUERY [--project NAME] [--type table|bucket|config|flow|data-app|
 #   "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] [--component-id ID] [--config-id ID] [--status STATUS] [--limit N] [--offset N] [--sort-by startTime|endTime|createdTime|durationSeconds|id] [--sort-order asc|desc]
+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): without --project the multi-project fan-out 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,
@@ -603,10 +621,16 @@ kbagent job list [--project NAME] [--component-id ID] [--config-id ID] [--status
 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]
-
-kbagent storage buckets [--project NAME] [--branch ID]
+# 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 1 (INVALID_ARGUMENT, 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 ...] [--bucket-id ID] [--branch ID] [--include-usage]
+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 /
@@ -666,6 +690,13 @@ kbagent storage delete-table --project NAME --table-id ID [--table-id ...] [--fo
 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
@@ -677,6 +708,11 @@ kbagent storage swap-tables --project NAME --table-id ID --target-table-id ID --
     #   `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
@@ -745,17 +781,17 @@ kbagent lineage show --load PATH [--upstream NODE] [--downstream NODE] [--column
 kbagent lineage info --load PATH
 kbagent lineage server --load PATH [--port N] [--host HOST]
 
-kbagent sharing list [--project NAME]
+kbagent sharing list [--project NAME | --all-projects]
 kbagent sharing share --project ALIAS --bucket-id ID --type TYPE [--target-project-ids IDs] [--target-users EMAILS]
 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
-kbagent sharing edges [--project NAME]
+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-ids 1,2,3 --url URL [--dry-run] [--yes] [--token-description PREFIX] [--refresh]
 
-kbagent billing credits [--project ALIAS ...]
+kbagent billing credits [--project ALIAS ... | --all-projects]
 # billing credits (0.84.2+, issue #594 secondary ask): read-only PAYG credit balance, fanned out
 #   across all registered projects in parallel by default (--project repeatable narrows). A project
 #   without the `pay-as-you-go` owner.features flag never touches the billing host (NXDOMAIN on some
@@ -841,6 +877,12 @@ kbagent token refresh --project NAME --token-id ID [--yes]
 #   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.
@@ -856,7 +898,7 @@ kbagent permissions check OPERATION
 #   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]
+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
@@ -920,7 +962,10 @@ kbagent merge-request resolve --component-id C --config-id I (--take ours|theirs
 #   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; a truncated 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
@@ -942,7 +987,7 @@ kbagent workspace create --project ALIAS [--name NAME] [--backend TYPE] [--ui] [
 #   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 ...] [--orphaned] [--branch ID] [--qs-compatible]
+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
 kbagent workspace password --project ALIAS --workspace-id ID
@@ -975,10 +1020,14 @@ kbagent workspace query --project ALIAS --workspace-id ID --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 ...] [--dry-run] [--yes]
+kbagent workspace gc (--project NAME ... | --all-projects) [--dry-run] [--yes]
+# gc (CLI-28): needs --project or --all-projects (neither or both = USAGE_ERROR, exit 2), also over
+#   REST (`project=` or `all_projects=true`, else HTTP 400 INVALID_ARGUMENT). 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 ...] [--branch 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|python|streamlit|r|...] [--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 --
@@ -1043,7 +1092,7 @@ 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 /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] [--type TYPE] [--query QUERY]
+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
@@ -1135,8 +1184,12 @@ kbagent sync push --project ALIAS [--all-projects] [--dry-run] [--force] [--allo
 #   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`. Pass it 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.
+# `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]
@@ -1275,14 +1328,14 @@ kbagent http delete PATH [--timeout SECONDS]
 
 kbagent agent list
 kbagent agent show TASK_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] | --from-file PATH|@path|-) [--trigger-task-id ID --trigger-on success|error|always]
+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] | --from-file JSON|@path|-) [--trigger-task-id ID --trigger-on success|error|always]
 kbagent agent update TASK_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 [--yes]
 kbagent agent run TASK_ID [--stream] [--runtime-prompt TEXT | --runtime-input JSON|@file|-]
 kbagent agent runs TASK_ID [--limit N]
 kbagent agent run-detail TASK_ID RUN_ID
 kbagent agent run-events TASK_ID RUN_ID
-kbagent agent test (--type ai_agent --cli CLI --prompt P | --type cli_command --argv ARG ... | --from-file PATH) [--name N] [--stream] [--timeout SECONDS]
+kbagent agent test (--type ai_agent --cli CLI --prompt P | --type cli_command --argv ARG ... | --from-file JSON|@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
@@ -1322,7 +1375,7 @@ 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] [--branch ID] [--with-schedules]
+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]
@@ -1330,6 +1383,9 @@ kbagent flow validate --file @flow.yaml|- [--project NAME]
 kbagent flow new --project NAME --name NAME [--description D] [--file @path.yaml|-|JSON] [--branch ID]
 kbagent flow update --project NAME --flow-id ID [--name N] [--description D] [--file @path.yaml|-|JSON] [--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]
@@ -1372,11 +1428,11 @@ kbagent flow triggers --project NAME --flow-id ID [--branch ID]
 #   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 ...] [--enabled-only] [--branch 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 ...] [--branch ID]
+kbagent schedule find [--cron-window START-END] [--not-run-since DAYS] [--project NAME ... | --all-projects] [--branch ID]
 
-kbagent notification list [--project NAME ...] [--event NAME] [--component-id ID] [--config-id 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]
@@ -1425,7 +1481,20 @@ kbagent doctor
 # 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]
+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.
 # `--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.
@@ -1449,6 +1518,14 @@ kbagent update [--beta]
 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 / -v 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 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

{keboola_cli-0.99.1 → keboola_cli-0.100.2}/CONTRIBUTING.md

@@ -51,7 +51,7 @@ def storage_create_bucket(ctx, project, stage, name):
     try:
         result = service.create_bucket(alias=project, stage=stage, name=name)
     except KeboolaApiError as exc:
-        formatter.error(message=exc.message, error_code=exc.error_code)
+        emit_api_error(formatter, exc)  # keeps code, message, retryable, details
         raise typer.Exit(code=map_error_to_exit_code(exc)) from None
     formatter.output(result) if formatter.json_mode else ...
 
@@ -91,7 +91,7 @@ Never print raw text that breaks JSON parsing. Always check `formatter.json_mode
 ### Error handling
 
 - Commands catch `KeboolaApiError` and `ConfigError`, map to exit codes
-- Exit codes: 0=success, 1=general, 2=usage, 3=auth, 4=network, 5=config, 6=permission denied
+- Exit codes: 0=success, 1=general, 2=usage, 3=auth, 4=network, 5=config, 6=permission denied, 7=job timed out and cancelled, 130=interrupted
 - Multi-project operations accumulate errors -- one project failing doesn't stop others
 - Use `raise typer.Exit(code=N) from None` to suppress traceback in CLI
 
@@ -355,6 +355,7 @@ When adding a new command (e.g., `kbagent storage create-foo`), you must update
 - [ ] **Permission registration** in `permissions.py` (`OPERATION_REGISTRY` dict)
 - [ ] **Branch choice** through `resolve_branch()` in `effective_branch.py` when the command takes `--branch` or uses the active branch -- never read `ProjectConfig.active_branch_id` directly. The function reports the branch (`Target:` line, `targets` in `--json`); `tests/test_effective_branch.py` fails on a new direct read.
 - [ ] **`--project` naming a NEW alias** -- every `--project` option also takes a project ID, translated to the alias before the command runs (`commands/_project_ref.py`, CLI-22). A command whose `--project` is not a registry lookup (a new alias like `project add`, an offline filter like `lineage show`) 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 (with a reason); an option with any other name needs this decision by hand.
+- [ ] **CLI interface spec** -- the command, its options, help, output, exit codes and its REST route follow [`docs/cli-interface-spec.md`](docs/cli-interface-spec.md). Run `make cli-spec-check`: a new violation of a blocking rule fails it, and each failure line links to the rule. The rules marked "review" in the spec are checked by the reviewer.
 - [ ] **Service wiring** in `cli.py` if adding a new service class
 - [ ] **HTTP API endpoint** in `src/keboola_agent_cli/server/routers/<group>.py` -- `kbagent serve` exposes the CLI as a REST API so external applications (Web UI, scheduled AI agents, Slack bots, Streamlit dashboards, CI pipelines) can call the platform without forking CLI subprocesses. The current convention is **1:1**: every command in a group has a matching endpoint in that group's router (e.g. `commands/flow.py` has 8 commands, `server/routers/flows.py` has 8 routes). If you add a new command, add the corresponding route. **Skip allowed** only for genuinely terminal-only commands (interactive prompts, Rich-rendered output that has no useful JSON shape, `doctor`/`init`/`update`-style infrastructure that manages kbagent itself rather than Keboola). Document any skip in the PR description with a one-line reason so reviewers don't flag it.
 
@@ -377,6 +378,7 @@ done** until every box below is ticked.
 
 - [ ] **`SKILL.md` decision table** -- run `make skill-gen` and commit the diff. **Do NOT edit the table by hand** -- the markers will be overwritten on the next `make skill-gen`. The pre-commit hook auto-regenerates and stages this file.
 - [ ] **`plugin.json` version** -- bumped via `make version-sync` from `pyproject.toml`. The pre-commit hook auto-stages this file; you should never edit it by hand.
+- [ ] **`docs/cli-manifest.json`** -- the command manifest (commands, options, help texts). Run `make cli-manifest` and commit the diff; `make cli-spec-check` fails while the file differs from the live tree.
 
 #### Plugin (`plugins/kbagent/`) -- HAND-MAINTAINED, NO CI CHECK
 
@@ -618,6 +620,10 @@ catch you** if you skip them; they are the manual safety net for the
 silent-drift risks summarized in the
 [Plugin synchronization map](#plugin-synchronization-map) above.
 
+> **Releasing a new major version (1.0.0)?** Walk this checklist as usual, and
+> also follow [Releasing a new major version](#releasing-a-new-major-version)
+> below: the GitHub "latest" flag, PyPI and the old-major fixes follow extra rules.
+
 > **Want to ship a beta first?** You can. PEP 440 pre-release versions
 > (`0.43.0b1`, `0.43.0rc1`) are fully supported by `kbagent update --beta`
 > since v0.42.0. The startup auto-update hook never silently lands on a
@@ -651,6 +657,8 @@ silent-drift risks summarized in the
    A leftover `(since vNEXT)` ships agents a gate no installed version can
    ever satisfy -- strictly worse than no gate, because they then refuse a
    command the user has. The release PR is the only place it can be fixed.
+   When a replaced placeholder is inside a command or option help string,
+   also run `make cli-manifest` and commit `docs/cli-manifest.json`.
 
    **This is now CI-enforced.** The `check` job runs the same check on any PR
    that RAISES `pyproject.toml`'s version, so a missed placeholder is a red
@@ -795,8 +803,10 @@ users safe from accidentally landing on a beta:
    **skipping** pre-releases unless the resolver is told otherwise (`--pre`
    for pip, `--prerelease=allow` for uv).
 2. **GitHub Release `prerelease: true` flag.** The auto-update startup
-   hook calls `GET /releases/latest`, which GitHub explicitly defines as
-   "the most recent non-prerelease, non-draft release". Marking the release
+   hook reads `GET /releases/latest`, which never names a release marked
+   `prerelease`; the release list is read only with `--beta` or when the
+   latest release is of a higher major, and then pre-releases are skipped
+   unless `--beta` is given. Marking the release
    `--prerelease` makes it invisible to the auto-update path.
 
 **Workflow:**
@@ -853,10 +863,124 @@ each invocation has to opt in. This is deliberate: betas should always be
 an active choice, never a forgotten "I once typed --beta six months ago"
 foot-gun.
 
+### Releasing a new major version
+
+These rules apply to 1.0.0 and to every later major. What users see and how to
+stay on 0.x is in [docs/migrate-to-1.0.md](docs/migrate-to-1.0.md); the
+maintainer rehearsal before T0 is
+[docs/release-1.0-rehearsal.md](docs/release-1.0-rehearsal.md).
+
+- **T0** is the `published_at` of the GitHub release `v<N>.0.0`.
+- **M** is T0 + 28 days (28 x 86,400 seconds, UTC).
+- Until M, `releases/latest` names the newest release of the previous major.
+  Clients older than the 0.x release with the major gate (0.100.0) follow
+  `releases/latest`, so they stay on 0.x until M. From M, the newest release
+  of the new major is latest.
+
+**What the automation does.** `scripts/release_latest.py` holds the rules; the
+workflows only call it. It reads `published_at` from the GitHub API, and "now"
+is the `Date` header of the GitHub response, the same clock the clients use.
+
+| Release | Before T0 | From T0 to M | From M |
+|---|---|---|---|
+| 0.x (stable) | `make_latest: true` | `make_latest: true` | `make_latest: false` |
+| 1.x (stable), `v1.0.0` included | n/a | `make_latest: false` | `make_latest: true` |
+| any pre-release | `make_latest: false` | `make_latest: false` | `make_latest: false` |
+
+- `release-kbagent.yml` sets `make_latest` explicitly on every release, never
+  the GitHub default (which marks every new stable release as latest). The
+  `github-release` job decides it right before it publishes, and the "Fill
+  release notes" step sends the same value again with `gh release edit
+  --latest=<value>`. A version lower than the current latest never gets
+  `true`, so a re-run of an older tag does not take the flag back.
+- `promote-major.yml` runs every hour (minute 17) from the default branch. At
+  M it marks the newest stable release of the new major as latest (`gh release
+  edit <tag> --latest`). Before T0 and before M it does nothing. It is
+  idempotent, and it also corrects a release that was decided before M but
+  published after M. Run it by hand with `gh workflow run promote-major.yml`.
+- For `v<N>.0.0` (output `MAJOR_START`), the `pypi` job publishes only after
+  `github-release` succeeded, so PyPI never names a new major before T0
+  exists. For every other tag, `pypi` waits for `github-release` too, but a
+  failed `github-release` does not stop it.
+- A tag of an old major after T0 (output `OLD_LINE`: `v<N+1>.0.0` is
+  published) skips the `homebrew` and `ai-kit-marketplace` jobs, because both
+  hold one version and would move back to the old major. Chocolatey, winget,
+  apt/rpm and PyPI keep every version, so they still publish it.
+  `test-install` installs the exact tagged version with apt and dnf.
+- `install.sh` and the PowerShell block of `README.md` take the version from
+  PyPI (`info.version`, the highest stable version), not from the
+  `releases/latest` redirect, so new installs get the new major from T0.
+
+**Steps for the maintainer.**
+
+1. **Before the first 1.0.0 change merges to `main`**, in this order:
+   1. Make sure `main` has the workflow changes above (`release-kbagent.yml`,
+      `promote-major.yml`, `scripts/release_latest.py`) and no install from
+      git without a release tag (`tests/test_pinned_installs.py` checks it).
+      A tag runs the workflow file of the tagged commit, so `release/0.N`
+      must start from a commit that has them. `install.sh` on `main` must
+      install any stable release of both majors, because it installs what
+      PyPI names: 0.x until T0, the new major from T0.
+      `tests/test_install_script.py` runs its install paths with a 0.x and a
+      1.x version; keep both.
+   2. Find the last 0.x release (stable tag only):
+      `git fetch --tags origin`, then
+      `git tag --list 'v0.*' --sort=-v:refname | grep -E '^v0\.[0-9]+\.[0-9]+$' | head -n 1`.
+      N is its minor version (`v0.105.2` gives `release/0.105`). If that tag
+      is older than the changes of step 1.1, release one more 0.x version
+      from `main` first (a normal release PR) and use its tag.
+   3. Create `release/0.N` from the commit of that tag:
+      `git push origin 'v0.N.x^{commit}:refs/heads/release/0.N'`.
+      CI runs on `release/0.N` only when its `ci.yml` and `frontend.yml` have
+      the `release/[0-9]+.[0-9]+` triggers. If that tag is older than the
+      triggers, the first PR into `release/0.N` adds them.
+   4. Pin the deprecated marketplace shim in a PR to `main`, and merge it
+      before the first 1.0.0 change. Its relative `source` follows the
+      default branch, so it would serve 1.x plugin documents to 0.x installs.
+      In `.claude-plugin/marketplace.json`, replace the `kbagent` entry's
+      `"source": "./plugins/kbagent"` with
+      `{"source": "git-subdir", "url": "https://github.com/keboola/cli.git", "path": "plugins/kbagent", "ref": "v0.N.x"}`
+      (the shape the ai-kit marketplace uses; `v0.N.x` is the tag of step
+      1.2) and set its `version` to `0.N.x`. `scripts/sync_version.py` keeps
+      the version of a pinned entry as it is, and for a version of major 1 or
+      higher it fails while the source is still relative. So the 1.0.0
+      release PR cannot pass `make version-sync`, `make version-check` or the
+      release `gate` with an unpinned shim. When a later 0.N.x release
+      changes the plugin documents, set `ref` and `version` on `main` to that
+      release in the same way.
+   5. Walk the rehearsal in [docs/release-1.0-rehearsal.md](docs/release-1.0-rehearsal.md).
+2. **T0 − 14 days or earlier:** the 0.x release with the major gate (0.100.0)
+   must be published by now, at least 14 days before T0.
+   Check that `promote-major` runs on `main` and prints `tag=` (nothing to do).
+3. **T0:** open the 1.0.0 release PR as usual (steps 1-15 above), merge it,
+   and push the tag `v1.0.0`. Do not create the GitHub release by hand, not
+   even as a draft: publishing a draft sets a new `published_at`. Never delete
+   or re-publish `v1.0.0`: a release with a new `published_at` restarts the
+   28 days. Edit it in place if something must change. Then check:
+   - `gh api repos/keboola/cli/releases/latest --jq .tag_name` still names 0.x.
+   - `gh release view v1.0.0` shows the release, and the releases page does
+     not mark it "Latest".
+   - PyPI has 1.0.0 only after the GitHub release exists.
+4. **From T0 to M:**
+   - 1.x releases come from `main` as usual and get `make_latest: false`.
+   - 0.N.x fixes come from `release/0.N`: a release PR against that branch,
+     then a tag on its merge commit. Add the same changelog entry to `main`
+     too, because `make changelog-check` audits every published release.
+     Homebrew and ai-kit skip these tags; they stay `make_latest: true`.
+5. **M:** `promote-major` marks the newest 1.x release as latest within one
+   hour. Check it with `gh api repos/keboola/cli/releases/latest --jq .tag_name`.
+6. **After M:** a 0.N.x tag still publishes, with `make_latest: false`. Stop
+   0.N.x releases unless a fix is critical.
+
+To delete the shim later instead of keeping it pinned, also remove
+`.claude-plugin/marketplace.json` from `make version-check` and from the
+"SKILL.md + version drift" step of the release `gate`: both give the path to
+`git diff`, which fails on a path that does not exist.
+
 ## Running CI Locally
 
 ```bash
-make check              # CI parity: lint + format + typecheck + skill + version + command-sync + endpoints + changelog + error-codes + sentinel-guards + test
+make check              # CI parity: lint + format + typecheck + skill + version + command-sync + cli-spec + endpoints + changelog + error-codes + sentinel-guards + test
 make lint               # Just the ruff linter
 make format             # Auto-format code
 make typecheck          # Static type check (Astral `ty`)
@@ -864,6 +988,11 @@ make audit              # Audit locked dependencies for known vulnerabilities (u
 make test               # Just the test suite (no coverage)
 make test-cov           # Test suite + informational coverage report (term-missing)
 make command-sync-check # Verify every CLI command is registered + documented
+make cli-spec-rules     # Check the CLI spec rules vs the baseline and docs/cli-manifest.json (in make check)
+make cli-spec-check     # cli-spec-rules plus the contract test files of the spec
+make cli-manifest       # Regenerate docs/cli-manifest.json after a command, option or help change
+make cli-spec-baseline  # Re-record scripts/cli_spec_baseline.json after a fix (it may only shrink)
+make cli-spec-report    # Per-command inventory: category, --project shape, safety flags, violated rules
 make endpoints-check    # Verify docs/web-server-endpoints.md matches the live FastAPI app
 make endpoints-gen      # Regenerate it after adding a serve route
 make check-sentinel-guards # Verify no kbc-session:// sentinel path is unguarded
@@ -936,6 +1065,38 @@ can do) also fires for a stale feature branch whose base has since been
 released; arming there would tell a contributor to delete a placeholder the
 process requires them to write.
 
+**CLI spec gate** (`scripts/check_cli_spec.py`, `make cli-spec-check`): walks
+the live command tree, the serve routes and the source of `commands/`, and
+checks them against the rules of the CLI interface spec (#791). Existing
+violations are listed in `scripts/cli_spec_baseline.json`, which has a
+`blocking` flag per rule. A new violation of a blocking rule fails, and so
+does a baseline entry that is no longer a violation: after a fix, run
+`make cli-spec-baseline` and commit the shorter file. A permanent, reviewed
+exception goes into `exceptions` with a reason. Renaming or moving a function
+or command that is in the baseline gives a `new` line for the new name and a
+`stale` line for the old one; run `make cli-spec-baseline` and commit the
+result.
+
+On a pull request CI also compares the baseline with the base branch, for
+every blocking rule. It fails when a rule has more `violations` entries than
+on the base branch (entries are counted per rule, so a renamed command, a
+hidden alias that keeps the old name, or a function moved to another file is
+no growth), when a rule of the base branch is missing or no longer blocking,
+and when a subject was added to `exceptions`. A new exception passes only when
+a reviewer has checked the exception and its reason and added the label
+`cli-spec-exception` to the pull request; re-run the CI job after adding the
+label. Known limits: the count lets one fixed entry be swapped for a new
+violation of the same rule elsewhere, and the ratchet is keyed by subject, so
+a second violation of the same rule inside a function or command that is
+already in the baseline passes.
+`make check` runs the rules (`make cli-spec-rules`); `make cli-spec-check`
+also runs the contract test files.
+The same step fails when `docs/cli-manifest.json` differs from the live tree
+(`make cli-manifest`). The contract cases of the spec are in
+`tests/test_cli_contract.py`, and the human output of one command per shared
+renderer is pinned by `tests/test_cli_human_snapshots.py`; record an intended
+renderer change with `KBAGENT_UPDATE_SNAPSHOTS=1` and commit the snapshot diff.
+
 **Command-sync silent-drift gate** (`scripts/check_command_sync.py`): treats the
 live Typer command tree as the single source of truth and fails if any command
 is missing from `permissions.py` `OPERATION_REGISTRY`, `CLAUDE.md`