chore(release): prepare 0.89.0

[padak]

Release prep for 0.89.0. pyproject.toml, plugin.json and marketplace.json were already renumbered by #643; this PR completes the changelog and the documentation gates for everything else merged since v0.88.0.

Release contents

PR	Issue	What ships
#643	--	config delete never purges on a repeated delete (locate-first guard + per-call transport retry opt-out); new config restore and config trash-list; all three mirrored on kbagent serve
63475d4	#649	sync diff/sync push are branch-scoped: after a dev-branch pull re-targets the manifest, production diff no longer classifies the whole main/ tree as added (one push from duplicating the project); cross-tree configs land in a new orphaned report bucket
69831c7	#644	config new --push --output-dir scaffolds carry _keboola.config_id and land in the creation branch's subtree, so the next sync push adopts instead of duplicating (34-duplicate incident)
607fa7e	#650	flow scaffold _config.yml gains the _keboola block + push-compatible shape (version: 2, definition under _configuration_extra) — a pushed flow is no longer empty
5313801	#648	Process: version bumps + changelog move out of feature PRs into dedicated release PRs (vNEXT placeholder convention) — this PR is the first to follow it
#647	#599	token create / token refresh pre-flight the acting token and fail fast with MISSING_MASTER_TOKEN (exit 3) instead of the Storage API's generic 500 on a non-admin token
#646	--	sync clone override files (--bucket-map/--variable-values/--instance-rename) reject nested mappings/lists instead of silently stringifying them into bucket IDs; shared yaml_input.py now backs both sync clone and describe-batch
#645	#640	storage describe-batch --from-file rejects malformed shapes / null descriptions / coercion-colliding duplicate keys with a structured INVALID_ARGUMENT (exit 2) before any write. Behaviour change -- it used to raise an AttributeError traceback partway through, half-applied
#620	AI-3757 / SUPPORT-17393	component sync-action forwards the root config's authorization + runtime into configData, so OAuth / Service-Account components (keboola.ex-linkedin-ads) stop failing with an opaque empty-body 400
#642	--	storage table-detail human output shows column descriptions
#517	#513	Stable metavar contract in scripts/gen_command_reference.py (count flags, composites, enum choices; deterministic across Click/Typer versions)
#586	#585	Test gating the documented prompt budget against the enforced PROMPT_BYTE_BUDGET
#641	--	Docs-only reference-gap fixes from the 0.88.0 audit

Changelog

Adds the seven bullets above to the 0.89.0 block and decorates the existing #643 bullets with their PR reference so the block reads consistently. Every first sentence is self-contained and under the 160-char headline cap (kbagent changelog default view).

Silent-drift surfaces (convention #17)

• gotchas.md -- both (Release step: ... tag this sentence) placeholders resolved. git blame puts both on commits after the v0.88.0 tag (feat(storage): show column descriptions in table-detail human output #642 at the table-detail Description column, fix(storage): reject malformed describe-batch --from-file shapes with a structured error (#640) #645 at the describe-batch shape check), so both are tagged (since v0.89.0), not 0.88.0. New fix(AI-3757): forward authorization/runtime in component sync-action #620 gotcha added under "Native parity commands".
• fix(AI-3757): forward authorization/runtime in component sync-action #620 shipped with no doc surfaces at all -- CLAUDE.md, AGENT_CONTEXT (context.py) and commands-reference.md now carry the forwarding rule (root only, never row-overridden, only when non-empty) with its version gate.
• fix(storage): reject malformed describe-batch --from-file shapes with a structured error (#640) #645 never reached CLAUDE.md -- the shape check and the behaviour change are recorded there now; commands-reference.md gains the version tag.
• feat(storage): show column descriptions in table-detail human output #642 -- the human Description column is version-tagged in CLAUDE.md, commands-reference.md, AGENT_CONTEXT and storage-describe-workflow.md.
• fix(config): never purge on a repeated delete; add restore + trash-list (0.89.0) #643 was otherwise complete (CLAUDE.md, SKILL.md, commands-reference, gotchas, AGENT_CONTEXT). Added the two surfaces it did not touch: safe-write-workflow.md (delete is reversible; never blind-retry on <= 0.88.x) and a keboola-expert.md matrix row for delete / restore / trash-list.
• keboola-expert.md is 49 774 B, inside the 70 000 B budget.

Gates

• make check -- green (5934 passed, 12 skipped), including skill-check, version-check, command-sync-check, changelog-check, check-error-codes, check-sentinel-guards, loc-check.
• make version-gate-check -- All 438 version gates across 72 versions resolve to a release.
• make version-sync -- no changes (already at 0.89.0).

No tag and no GitHub release here -- that happens after e2e verification.

Live e2e verification (2026-08-22, project e2e-snowflake, CLI run from this branch)

• fix(storage): reject malformed describe-batch --from-file shapes with a structured error (#640) #645 describe-batch validation — 11/11 checks passed (~/kbagent/e2e/describe_batch_validation_e2e.py): valid batch applies; tables: as a list → exit 2 INVALID_ARGUMENT naming the key, nothing applied before the error; null description rejected; duplicate coerced keys (1: vs "1":) rejected; buckets: [] back-compat no-op confirmed; the exact issue storage describe-batch: malformed --from-file crashes with a traceback instead of a validation error #640 repro produces a structured error with no traceback.
• fix(config): never purge on a repeated delete; add restore + trash-list (0.89.0) #643 delete/restore cycle verified live: soft delete → status: deleted; repeated delete → status: already_in_trash, exit 0, with the explicit "a second DELETE would purge it permanently" message (no purge sent); config trash-list finds the config; config restore → status: restored (version bumped); config detail confirms it is alive; cleanup delete OK.
• fix(AI-3757): forward authorization/runtime in component sync-action #620 is not live-testable in the e2e projects (no OAuth-authorized component available there); it is covered by unit tests, byte-for-byte MCP-parity verification in review, and the original SUPPORT-17393 repro belongs to the reporter's stack.
• fix(docs): pin command-reference metavar format as a stable contract (#513) #517/test(agent-prompt): gate the documented prompt budget against the enforced one (#585) #586/feat(storage): show column descriptions in table-detail human output #642 are covered by CI (metavar grammar walks the live command tree; the budget test runs in every suite; table-detail rendering has unit tests).

Business Release Notes — draft for the 0.89.0 GitHub Release

The release pipeline generates the release body from changelog.py automatically. This section is the business-oriented summary to paste above the generated changelog (or use as the announcement text in Slack/e-mail).

Keboola CLI 0.89.0 — your configurations just became much harder to lose

A retry can no longer destroy a configuration. The Storage API overloads DELETE: the first call soft-deletes a configuration into the trash, but an identical second call — exactly what every agent, CI script, or impatient human does after a timeout — purged it permanently, rows, versions and metadata included. kbagent config delete now checks state first and never sends a DELETE at anything that is not live, and the HTTP layer no longer auto-retries this specific call. Deleting is now genuinely reversible: new config restore brings a trashed configuration back, and config trash-list shows what is in the trash. All three are also available over the kbagent serve REST API.

Bulk documentation is now all-or-nothing. storage describe-batch used to crash with a Python traceback partway through a malformed YAML file — leaving your project half-described. It now validates the whole file before the first write and reports exactly which key is wrong, its actual type, and a copy-pasteable example. A typo now costs you one clear error message instead of a cleanup session.

OAuth-connected components now work from the CLI. component sync-action (e.g. listing LinkedIn Ads accounts) failed with an opaque 400 for any component authorized via OAuth, because the CLI never forwarded the authorization reference. It does now — matching what the Keboola MCP server always did. (AI-3757 / SUPPORT-17393)

Column documentation is visible where you look for it. storage table-detail now shows column descriptions in its human-readable output — completing the 0.88.0 work that made kbagent write descriptions where the UI, MCP and warehouse COMMENTs read them.

For AI agents specifically: every one of these changes tightens the structured-error contract agents depend on — malformed input now fails fast with INVALID_ARGUMENT exit 2 before any write, destructive retries are idempotent, and all agent-facing docs (kbagent context, the kbagent skill references, gotchas) are version-tagged for 0.89.0.

sync push can no longer duplicate your whole project. After working in a dev branch, a production sync diff used to classify every production config as "new" — one confirmation away from creating each of them again. Diff and push are now scoped to a single branch tree and anything left over is reported as orphaned with a reconcile hint, never pushed. (#649) In the same spirit, config new --push scaffolds now remember the ID of the config they created, so the next push updates it instead of creating a duplicate (#644), and scaffolded flows are finally pushable at all (#650).

Token administration fails clean, not cryptic. token create and token refresh now check up front that the acting token is a master (admin) token and explain exactly what is missing, instead of letting the Storage API answer 500 Application error. (#647, closing the #599 investigation)

sync clone no longer accepts silently broken override files. A misplaced colon in a --bucket-map file used to produce a bucket literally named "{'new': 'in.c-new'}" in the target project; now the file is rejected up front with the offending key named. (#646)

Plus: a stable machine-readable format contract for the generated command reference (#517), a CI guard keeping documented limits in sync with enforced ones (#586), and reference-doc fixes from the 0.88.0 audit (#641).

Upgrade: kbagent update (or your package manager's own upgrade command — see kbagent version --json's upgrade_hint).

After merging (for @padak)

1. Merging this PR puts main at 0.89.0. Release = push the tag: git tag v0.89.0 <merge-commit-sha> && git push origin v0.89.0 — the pipeline builds the wheel, creates the GitHub Release (body from changelog), and pushes chocolatey. Paste the business notes above into the release body if you want them on the release page.
2. Landed after this PR was first opened and now included: fix(token): pre-flight master-token guard on token create/refresh #647 (closed token create: persistent upstream 500 on POST /v2/storage/tokens surfaces as a blind retry + generic error, no actionable guidance #599), fix(sync): reject non-scalar values in sync clone override files #646, sync: production diff/push after 'sync pull --branch' flags the whole orphaned main/ tree as added (mass-duplicate risk) #649, config new --output-dir --push writes a scaffold without the created config ID → duplicates on next sync push #644, config new: flow scaffold _config.yml lacks the _keboola block, sync push sees component 'unknown' #650 and the docs: version bumps move out of feature PRs into dedicated release PRs #648 release-process change — the branch is rebased to carry all their changelog entries, and every vNEXT placeholder from the feature PRs is resolved to v0.89.0 here (per the new docs: version bumps move out of feature PRs into dedicated release PRs #648 process). Not in this release: PR fix(AI-3750): stop duplicate _ui_dist wheel entry (hatchling >= 1.30) #623 (wheel _ui_dist fix) — awaiting @Matovidlo's confirmation; it targets the next release once he responds.

---

[devin-ai-integration]

✅ Devin Review: No Issues Found

Devin Review analyzed this PR and found no bugs or issues to report.

[padak]

Post-rebase verification: CI green on head a298a08 (check + 3.12 + 3.13 + Windows regression suite), and the live describe-batch e2e (~/kbagent/e2e/describe_batch_validation_e2e.py, project e2e-snowflake) re-ran against this exact head 11/11 passed — confirming #646's shared yaml_input.py extraction did not change describe-batch behavior. Ready to merge; after merging, release = push the v0.89.0 tag.

[padak]

Extended live e2e sweep (project e2e-snowflake, CLI run from this branch at 2c77a8f) — every release item that is live-testable in the e2e environment now has a live check:

• fix(storage): reject malformed describe-batch --from-file shapes with a structured error (#640) #645 describe-batch validation — 11/11 checks (run twice, incl. post-fix(sync): reject non-scalar values in sync clone override files #646 shared yaml_input.py).
• fix(config): never purge on a repeated delete; add restore + trash-list (0.89.0) #643 delete/trash/restore — full cycle: soft delete, repeated delete answers already_in_trash (no purge), trash-list finds it, restore brings it back, detail confirms alive.
• feat(storage): show column descriptions in table-detail human output #642 table-detail — describe-column then human-mode table-detail renders the Description column with the written text.
• config new: flow scaffold _config.yml lacks the _keboola block, sync push sees component 'unknown' #650 flow scaffold — config new --component-id keboola.flow --output-dir emits _keboola block, version: 2, definition under _configuration_extra, no top-level phases/tasks.
• fix(sync): reject non-scalar values in sync clone override files #646 sync clone overrides — malformed --bucket-map (nested mapping) fails fast with CONFIG_ERROR exit 5 naming the key; target dir never created.
• sync: production diff/push after 'sync pull --branch' flags the whole orphaned main/ tree as added (mass-duplicate risk) #649 branch-scoped diff — the exact incident repro (production pull, then sync pull --branch <dev>, then production sync diff) reports added: 0 (pre-0.89.0: added:14, one push from duplicating the project); all 14 configs adopted by id as unchanged, per the documented cross-tree adopt path.
• fix(token): pre-flight master-token guard on token create/refresh #647 token guard — positive path live (master token: create → list → delete OK). The negative path (non-master token → MISSING_MASTER_TOKEN instead of API 500) is covered by unit tests only: registering a scoped token for a live negative test would require handling the token secret outside the CLI, which our e2e policy forbids.
• fix(AI-3757): forward authorization/runtime in component sync-action #620 sync-action — not live-testable here (no OAuth-authorized component in the e2e project); covered by unit tests + byte-for-byte MCP-parity review.
• fix(docs): pin command-reference metavar format as a stable contract (#513) #517/test(agent-prompt): gate the documented prompt budget against the enforced one (#585) #586/docs: version bumps move out of feature PRs into dedicated release PRs #648/docs(plugin): close the reference gaps a 0.88.0 audit found #641 — CI/process surfaces, no live e2e applicable.