chore(kai): deprecate the legacy kai command group (0.77.0)

.claude-plugin/marketplace.json

@@ -10,7 +10,7 @@
   "plugins": [
     {
       "name": "kbagent",
-      "version": "0.76.2",
+      "version": "0.77.0",
       "source": "./plugins/kbagent",
       "description": "AI-friendly interface to Keboola Connection projects — explore configs, jobs, lineage, call MCP tools, manage dev branches, and debug SQL in workspaces",
       "category": "development"

CLAUDE.md

@@ -602,6 +602,15 @@ 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]
+# kai group DEPRECATED (0.77.0+): targets the LEGACY `kai-assistant` backend, which is frozen --
+#   Linear AI-3388 was canceled, and product confirmed only the successor backend gets further work.
+#   That successor, `kai-agent` (Linear AI-3391), is a different API surface and is NOT wired into
+#   kbagent; retargeting is a separate future task. Behavior is UNCHANGED -- every subcommand still
+#   works against a master Storage token + `agent-chat` feature; each now warns on stderr in human
+#   mode and adds an additive "deprecation" key to the --json success payload (error envelopes carry
+#   none). The group and the serve `/kai/*` routes will be removed in a later minor. NO replacement
+#   in the interim: use `docs query` for documentation questions and the native commands
+#   (`storage tables`, `config detail`, `search`, `lineage show`, ...) for project data.
 
 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]

README.md

@@ -159,7 +159,7 @@ kbagent workspace query --project prod --workspace-id WS_ID \
 | **Project members & invitations** | `project invite` (single or `--from-csv` bulk with parallel workers), `project member-list / member-remove / member-set-role`, `project invitation-list / invitation-cancel`. Role whitelist enforced at the CLI layer; Manage API "already invited" treated as `noop` not error (since 0.29.0). |
 | **Lineage** | Column-level dependency analysis across projects. SQL/Python parsing, AI-enhanced detection, interactive web browser, Mermaid/HTML/ER export. |
 | **Semantic layer** | Define and manage a metastore semantic model per project — datasets, metrics, relationships, constraints, glossary. Validate (incl. `--deep`), export, diff two models/files, import/promote across projects, AI-assisted `build` from tables. `kbagent semantic-layer ...` (alias `sl`). |
-| **Kai (AI Assistant)** | Ask Keboola's built-in AI questions about your project. One-shot or chat sessions with full MCP context. |
+| **Kai (AI Assistant)** — **DEPRECATED (0.77.0)** | Ask Keboola's built-in AI questions about your project. One-shot or chat sessions with full MCP context. **Deprecated since 0.77.0**: targets the legacy `kai-assistant` backend, which is frozen; its successor `kai-agent` is not wired into kbagent. Still fully functional, but slated for removal in a later minor with no replacement — use `kbagent docs query` for documentation questions and the native commands for project data. |
 | **Encryption** | Encrypt secrets (`#password`, `#api_token`) via Keboola Encryption API. Works with sync push and MCP. |
 | **Permissions** | Firewall for AI agents: read-only, deny-writes, deny-destructive (session-only flags or persisted policy). Project pin + `KBAGENT_PROJECT` env override. Code-level enforcement, stable `ErrorCode` enum, not prompt tricks. |
 | **Auto-update** | Self-updates kbagent + `keboola-mcp-server` on every startup (since 0.30.1). "What's new" after each update. Full changelog via `kbagent changelog`. |
@@ -241,7 +241,7 @@ kbagent workspace   create | list | detail | delete | password | load | query |
 kbagent tool        list | call
 kbagent sync        init | pull | status | diff | push | branch-link | branch-unlink | branch-status
 kbagent schedule    list | detail | find
-kbagent kai         ping | preflight | ask | chat | chat-detail | history
+kbagent kai         ping | preflight | ask | chat | chat-detail | history   # DEPRECATED (0.77.0)
 kbagent encrypt     values
 kbagent permissions list | show | set | reset | check
 kbagent agent       list | show | create | update | delete | run | runs | run-detail | run-events

docs/build-your-own-client.md

@@ -101,7 +101,7 @@ without first knowing the token. Everything else needs auth.
 /sharing         kbagent sharing (list, share, link, unshare, unlink, edges)
 /data-apps       kbagent data-app (CRUD, deploy, start/stop, secrets-*, validate-repo)
 /mcp             kbagent tool (list, call) -- multi-project MCP fan-out
-/kai             kbagent kai (ping, ask, chat, history, preflight, chat-detail)
+/kai             kbagent kai (ping, ask, chat, history, preflight, chat-detail) -- DEPRECATED 0.77.0
 /encrypt         kbagent encrypt values
 /search          kbagent search QUERY
 /org             kbagent org setup

docs/error-codes.md

@@ -109,6 +109,10 @@ of `ErrorCode` in `src/keboola_agent_cli/errors.py`.
 
 ### KAI (AI Service)
 
+Both codes remain valid and unchanged, but the `kbagent kai` command group that
+raises them is **deprecated since 0.77.0** (legacy `kai-assistant` backend
+frozen; removal planned, no replacement).
+
 | Code | Description |
 |---|---|
 | `KAI_ERROR` | AI Service request failed |

docs/web-server.md

@@ -90,7 +90,7 @@ else lives here, with their own agents that know their projects.
 | `/sharing` | share/unshare/link/unlink | `kbagent sharing *` |
 | `/data-apps` | CRUD, deploy, start/stop, **secrets** | `kbagent data-app *` |
 | `/mcp/tools` | list, schema, **call** (multi-project) | `kbagent tool *` |
-| `/kai/*` | ping, ask, chat, history | `kbagent kai *` |
+| `/kai/*` **(DEPRECATED 0.77.0)** | ping, ask, chat, history | `kbagent kai *` (deprecated -- legacy `kai-assistant` backend frozen; removal planned, no replacement) |
 | `/encrypt` | encrypt secret values | `kbagent encrypt values` |
 | `/search` | textual + config-based cross-project search | `kbagent search` |
 | `/org` `/members` | bulk org setup, invite, remove, role (manage token) | `kbagent org|project member-* *` |

plugins/kbagent/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "kbagent",
-  "version": "0.76.2",
+  "version": "0.77.0",
   "description": "AI-friendly interface to Keboola Connection projects — explore configs, jobs, lineage, call MCP tools, manage dev branches, and debug SQL in workspaces",
   "author": {
     "name": "Keboola",

plugins/kbagent/agents/keboola-expert.md

@@ -93,7 +93,7 @@ a critical failure.
 | Search items by name across projects | `kbagent search QUERY [--project P] [--type table\|bucket\|config\|flow\|data-app\|transformation] [--search-type textual\|config-based] [--limit N] [--regex]` (0.30.0+); `--regex` (0.67.0+) opts into case-insensitive whole-term regex on entity names — `report` does NOT match `monthly_report`, write `.*report.*`; textual mode marks `table` results matched via a column name with `matched_columns` in `--json` (0.67.0+; always present, `[]` when the name itself matched; always `[]` under `--regex` — regex never matches column names) | `tool call search_tables` / `tool call search_configurations` (one resource-type per call) | chaining multiple `tool call` for different types; `--regex` with `--search-type config-based` (exit 2); `--regex` below 0.67.0 |
 | Search config JSON bodies | `kbagent search QUERY --search-type config-based [--project P]` (0.30.0+) | `kbagent config search --query Q` (config-body only, no tables/buckets) | repeated `tool call get_config` to grep locally |
 | Browse configs (exploration) | `kbagent config list` / `kbagent config search --query Q` | `tool call list_configs` | full-project pull via MCP just to grep locally |
-| Answer a Keboola-documentation question ("how do I configure incremental loading?") | `kbagent docs query "QUESTION" [--project P]` (0.73.0+; AI-service RAG, returns answer + source URLs) | -- | `kai ask` (project-scoped assistant, not docs Q&A); `tool call docs_query` (deprecated 0.74.0) |
+| Answer a Keboola-documentation question ("how do I configure incremental loading?") | `kbagent docs query "QUESTION" [--project P]` (0.73.0+; AI-service RAG, returns answer + source URLs) | -- | `kai ask` (**the whole `kai` group is DEPRECATED 0.77.0** -- legacy `kai-assistant` backend frozen, AI-3388 canceled, successor `kai-agent` not wired into kbagent, removal planned, no replacement); `tool call docs_query` (deprecated 0.74.0) |
 | Fetch a specific config | `kbagent config detail --project P --component-id C --config-id K --json` | `tool call get_config` | re-using an earlier JSON dump |
 | Override the auto-derived output bucket on a config | `kbagent config set-default-bucket --bucket in.c-name` (0.26.0+) -- read-modify-write of `storage.output.default_bucket`, preserves siblings; `--clear` removes it | `kbagent config update --set 'storage.output.default_bucket=in.c-name'` (works pre-0.26.0 but not discoverable) | editing the raw JSON in the UI; full-config replace with `--configuration` (wipes other storage keys) |
 | Cross-project migration | `kbagent sync pull` + edit files locally + `kbagent sync push --dry-run` | -- | repeated `tool call` loops, one per resource |

plugins/kbagent/skills/kbagent/SKILL.md

@@ -188,12 +188,12 @@ When working inside a git repository or project directory, run `kbagent init` (o
 | Show what's in a cached lineage graph | `kbagent lineage info --load LOAD` |
 | Query upstream/downstream dependencies from a cached lineage graph | `kbagent lineage show --load LOAD` |
 | Start a local web server with interactive lineage browser | `kbagent lineage server --load LOAD` |
-| Check Kai server health and MCP connection status | `kbagent kai ping` |
-| Ask Kai a one-shot question and get the full response | `kbagent kai ask --message MESSAGE` |
-| Send a message to Kai in a chat session | `kbagent kai chat --message MESSAGE` |
-| Check whether the configured token can use Kai (master token + AI Agent Chat) | `kbagent kai preflight` |
-| Fetch the full message history of a single Kai chat | `kbagent kai chat-detail --chat-id CHAT-ID` |
-| List recent Kai chat sessions | `kbagent kai history` |
+| (DEPRECATED) Check Kai server health and MCP connection status | `kbagent kai ping` |
+| (DEPRECATED) Ask Kai a one-shot question and get the full response | `kbagent kai ask --message MESSAGE` |
+| (DEPRECATED) Send a message to Kai in a chat session | `kbagent kai chat --message MESSAGE` |
+| (DEPRECATED) Check whether the configured token can use Kai | `kbagent kai preflight` |
+| (DEPRECATED) Fetch the full message history of a single Kai chat | `kbagent kai chat-detail --chat-id CHAT-ID` |
+| (DEPRECATED) List recent Kai chat sessions | `kbagent kai history` |
 | Ask the Keboola documentation a natural language question | `kbagent docs query <QUESTION>` |
 | Create a SQL transformation from a SQL script | `kbagent transformation create --name NAME` |
 | Show a SQL transformation's block/code tree with positional IDs | `kbagent transformation show --config-id CONFIG-ID` |

plugins/kbagent/skills/kbagent/references/commands-reference.md

@@ -220,9 +220,13 @@ Ports the MCP `create_sql_transformation` / `update_sql_transformation` tools (#
 - `transformation edit --project NAME --config-id ID --change-description TEXT (--op JSON ... | --op-file ops.json) [--storage JSON|@file|-] [--component-id ID] [--branch ID] [--dry-run]` -- 9 ops (`add_block`, `remove_block`, `rename_block`, `add_code`, `remove_code`, `rename_code`, `set_code`, `add_script`, `str_replace`) applied sequentially against batch-start ids. `--storage` REPLACES `configuration.storage` wholesale (include ALL mappings you want to keep). Unknown ids error with the list of valid ids.
 
 ## Documentation Q&A (since v0.73.0)
-- `docs query "QUESTION" [--project NAME]` -- natural-language answer from the Keboola documentation via the AI Service (server-side RAG, no local corpus). Returns answer text + source URLs; `--json` emits `{query, text, source_urls}`. Unlike `kai ask` it does NOT see project data, works with any token (no master-token / feature-flag requirement), and is the right tool for "how do I ..." questions. Ports the `docs_query` MCP tool.
+- `docs query "QUESTION" [--project NAME]` -- natural-language answer from the Keboola documentation via the AI Service (server-side RAG, no local corpus). Returns answer text + source URLs; `--json` emits `{query, text, source_urls}`. Unlike `kai ask` (DEPRECATED since v0.77.0) it does NOT see project data, works with any token (no master-token / feature-flag requirement), and is the right tool for "how do I ..." questions. Ports the `docs_query` MCP tool. **Prefer this over `kai ask` for documentation questions.**
+
+## Kai (Keboola AI Assistant) -- DEPRECATED since v0.77.0
+**DEPRECATED -- do not recommend this group for new work.** `kbagent kai *` talks to the **legacy `kai-assistant` backend**, which is frozen: Linear AI-3388 was canceled, and product confirmed that only the successor backend will receive further work. That successor, **`kai-agent`** (Linear AI-3391), is a different API surface that is **not wired into kbagent**. The group will be **removed in a later minor** and there is **no replacement in the interim** -- use `docs query` for documentation questions and native commands (`storage tables`, `config detail`, `search`, `lineage show`, ...) for project data.
+
+Behavior is unchanged in 0.77.0: every subcommand still works exactly as before. Each now prints a deprecation warning on **stderr** in human mode and adds an additive `deprecation` key to the `--json` **success** payload (error envelopes carry no such key; no existing key, exit code, or API call changed).
 
-## Kai (Keboola AI Assistant)
 Requires the project to be added with its **master ('owner') Storage API token** -- the auto-generated owner token, not a custom one. Custom tokens cannot access Kai. Also requires the `agent-chat` feature flag on the project. Use `kai preflight` to verify both conditions without raising.
 - `kai ping [--project NAME]` -- check Kai server health and MCP connection status. Fails with KAI_NOT_ENABLED if the agent-chat feature is missing or the token is not a master token
 - `kai preflight [--project NAME]` -- inspect token readiness WITHOUT raising. Returns `{ok, is_master_token, has_agent_chat_feature, token_description, error}`. Use this in UIs and automation pre-flight checks instead of `ping`

plugins/kbagent/skills/kbagent/references/gotchas.md

@@ -11,6 +11,44 @@ Versioning convention:
   behavior; the inline `(updated vX.Y.Z)` records when the refinement landed.
 -->
 
+## The whole `kai` group is DEPRECATED -- legacy backend frozen, no replacement (since v0.77.0)
+
+- **All six `kbagent kai *` subcommands (`ping`, `preflight`, `ask`, `chat`,
+  `chat-detail`, `history`) are on a removal track.** They talk to the
+  **legacy `kai-assistant` backend** -- the service registered under that id
+  in `GET /v2/storage` -- which is frozen. Linear AI-3388 was **canceled**,
+  and product confirmed that only the successor backend will receive further
+  work.
+- **The successor is `kai-agent`** (`kai-agent.{stack_suffix}`, a Hono
+  server), tracked in Linear AI-3391. It is a **different API surface** and
+  is **NOT wired into kbagent** -- retargeting is a separate, future task.
+  Do not assume `kbagent kai` will migrate to it.
+- **There is NO replacement in the interim.** For "how do I ..."
+  documentation questions use `kbagent docs query` (AI Service RAG, works
+  with any token, does **not** see project data). For project data use the
+  native commands (`storage tables`, `storage table-detail`, `config list`,
+  `config detail`, `search`, `job detail`, `lineage show`) or the MCP
+  integration. Do not recommend `kai ask` as a project-data oracle.
+- **Behavior is UNCHANGED in 0.77.0 -- deprecated is not removed.** Every
+  subcommand still hits the same endpoints with the same exit codes. The only
+  additions are the deprecation surfaces, which follow the `tool`-group
+  pattern exactly: a yellow `Warning:` on **stderr** in human mode (stdout
+  stays byte-clean for piping) and an additive `deprecation` string key on
+  the `--json` **success** payload. **Error envelopes carry no `deprecation`
+  key** -- a failing command exits before the key is injected. No existing
+  key was renamed or removed, so a script that parses `--json` today keeps
+  working.
+- **The token requirements have not relaxed and never will**: a project must
+  still be registered with its **master ('owner') Storage API token** (the
+  auto-generated one, not a custom token) *and* carry the `agent-chat`
+  feature flag, or every call fails `KAI_NOT_ENABLED`. Use `kai preflight`
+  to check both without raising. Because the backend is frozen, this gate is
+  permanent.
+- **The `/kai/*` REST routes on `kbagent serve` are deprecated too**, for the
+  same reason. They still respond this release. See also the
+  "Web UI `Kai Chat` is gone" entry below -- its "what stays" list now means
+  "stays until removal".
+
 ## MCP passthrough is DEPRECATED; parity map + canary (since v0.74.0)
 
 - **`tool call` / `tool list` / `agent --type mcp_tool` are on a removal
@@ -59,7 +97,9 @@ Versioning convention:
   reports `schema_version`).
 - **`docs query` vs `kai ask`**: `docs query` is documentation-only RAG (any
   token, no feature flag, no project data); `kai ask` sees project data but
-  needs the master token + `agent-chat` feature.
+  needs the master token + `agent-chat` feature. **`kai ask` is DEPRECATED
+  since v0.77.0** -- use `docs query` for documentation and native commands
+  for project data.
 
 ## `token` group mints/rotates/revokes SCOPED Storage tokens; secret shown ONCE (since v0.66.0)
 
@@ -630,6 +670,10 @@ a kbagent co-pilot.
   per-project session-state API. Only the dashboard UI tile + left
   nav entry was swapped. `kbagent kai ping|preflight|ask|chat`
   CLI commands are unchanged.
+- **Caveat added in v0.77.0:** the whole `kai` CLI group *and* the
+  `/kai/*` REST routes are now **DEPRECATED** (see the next entry).
+  They still work, but "what stays" now means "stays until removal in a
+  later minor" -- do not build anything new on them.
 
 **Implication for AI agents:**