docs(kai): document chat controls and refresh Getting Started - #1106
Conversation
Every button in the Kai chat panel is now explained in one place. The panel header row (new chat, report a bug, settings, expand, close) and the message box row (upload files, plan mode, follow mode) each get a table with icons. Plan mode was advertised in the product and documented nowhere (PRDCT-654). It is now covered in the chat controls table. Also replaces the Opening Kai screenshot, adds a screenshot of the action approval dialog and names all three of its buttons, and folds the Follow Mode subsection into the table so no control is explained twice.
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
…mpts The new-chat shortcut is Shift + A, not Ctrl + Shift + A. The Enabling Kai bullets read as sentences instead of dash-separated fragments. Example prompts are rewritten from the perspective of a data engineer arriving at an unfamiliar project or maintaining an existing one: orientation, lineage, failure diagnosis, and cost and runtime optimization, rather than "what tables do we have".
Asking Kai to build a Generic Extractor for an API with no ready-made connector is one of its strongest use cases and was missing from the example prompts.
It writes a custom integration instead, so the example prompt no longer names an implementation and simply asks for the data and its destination.
The glossary pass matches `- **Term** — definition` and converts it to a two-column grid, but kept the dash it had already consumed for detection, so every definition rendered as "— definition" while the columns were already doing the separating. Affects the 41 built pages that use the pattern; the only visual change is the leading dash disappearing.
Kai has no web access, so an example prompt that hands it a URL does not work — the API documentation has to arrive as an attached file. Notes the constraint where it matters: the upload control, Best Practices, and the context-files section of Settings. Report a bug opens a prefilled support-ticket dialog rather than only collecting debug details.
…ions Five gaps from the agentic-Kai rollout, verified against keboola/ui rather than the changelog. Slash commands: the `/` menu, and what `/plan`, `/compact`, and `/feedback` each do. `/feedback` copies debug details to the clipboard by default and only opens the support form when asked, so it is cross-referenced to the Report a bug button rather than described twice. Compaction: the transcript keeping every message after a compact is deliberate, not a bug — it stays a full record while Kai moves to working from a summary of it. Also that Kai compacts on its own, and that text after the command steers the summary. Documents the kai-agent behaviour only; the legacy backend's new-chat compaction is left out. Attachments: CSV/TSV/.gz become Storage tables in in.c-uploads-from-Kai, everything else is uploaded to File Storage and restored on return, so attachments do survive across a session. 10 MB per file, and non-permanent files are deleted after 15 days. Plan mode and questions get their own sections next to Action Approval, since both are approval flows the controls table could only gesture at: the three plan outcomes and how the toggle resolves, and that Kai asks with clickable options carrying a free-text Other. Semantic layer is deliberately not here — it belongs with #1103.
Report a bug and /feedback both land on the same support form, but neither hands you a ready-to-send ticket: the debug block goes into the description, while Summary and Severity are required and left empty. "Already filled in" and "with those details filled in" both read as nothing-left-to-do. Also names the two menu items rather than calling it a dialog, and notes that the button only copies where support tickets aren't available.
keboola-pr-reviewer-bot
left a comment
keboola-pr-reviewer-bot
left a comment
There was a problem hiding this comment.
Verdict: needs_human (risk 4/5) · profile connection-docs
Escalating: this PR modifies build tooling and documents Kai behavior that open bugs say does not yet work.
Impact flags: scope creep — see Check Run summary.
Concerns:
src/integrations/beacon-transforms.mjs: Build/tooling code changed — policy requires human review for src/integrations/**.src/content/docs/kai/getting-started.md: Documents plan-mode gating and Decline as working; open bugs AI-3665/AI-3783 say otherwise.src/content/docs/kai/getting-started.md: Panel-header table has author-unverified claims (report-a-bug flow, close keeps conversation).
Suggested reviewers: @keboola/docs
…ntext files - Add a real capture of a clarifying question, and document the two controls it shows that the text did not mention: the step counter, and stepping back to change an earlier answer. - Simplify the compaction paragraph. Same point, split in two, no em dash. - Promote the "use a context file instead" line into a tip. Attachments upload with isPermanent: false (15 days); context files upload with isPermanent: true. Verified in keboola/ui — user-files.ts:59 and useContextFiles.ts:46. - Name the button in "On stacks without support tickets, Report a bug only copies" — "the button" was ambiguous after two buttons had just been described. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
There was a problem hiding this comment.
Approving. This is more thorough than what I opened as #1104, and everywhere it changed my text it was because my text was wrong — the Ctrl + Shift + A shortcut and the Report a bug description especially. Plan Mode deserved the full section it got.
I have pushed one commit on top, 6c52e65e, four small things:
1. Screenshot for "When Kai Asks You a Question." The section had no image. The capture shows two behaviours the bullets did not mention, so I added them: the step counter, and being able to go back and change an earlier answer.
2. Compaction paragraph simplified. Same point, split into two shorter paragraphs, em dash gone. I kept your framing — that the transcript and what Kai reads are two different things — because that is the part people get wrong.
3. The context-file line promoted to a tip. It was doing real work buried mid-paragraph. I checked both halves of the claim in keboola/ui before making it a callout, and they hold:
apps/kai-agent/src/hosts/keboola/content/user-files.ts:59— chat attachments upload withisPermanent: false, so the 15-day expiry is real.apps/kbc-ui/src/scripts/modules/settings/KaiAgentTab/useContextFiles.ts:46— context files upload withisPermanent: true.
So the contrast the tip draws is exactly what the code does.
4. Named the button in "On stacks without support tickets, Report a bug only copies." It said "the button", which was ambiguous right after two buttons had been described.
npm run build clean, 361 pages.
The chevron does open chat history. You had it right originally and removed it after my comment — I meant the expanded view also lists history. But leave it out; the header table is complete enough without it. Treating that open question as closed.
Close is confirmed. Clicking X keeps the conversation, so your table is correct as written. That is all three of your open questions answered.
#1097 will conflict. It rewrites the same Access block on getting-started.md to drop "Public Beta". Its deadline is the 15th and this PR is already approved, so merge this one first and rebase #1097 onto it — keeping your full-sentence bullets and dropping only the beta clause, since its version predates your rewording.
| - **Settings** — Kai can also be enabled via **Settings → Features** in your project | ||
| - **Organization Admins** can enable the feature directly from the chat screen when first clicking the Kai button. | ||
| - **Other users** need to ask their Organization Admin to enable the feature, or [contact Keboola Support](mailto:support@keboola.com) for assistance. | ||
| - Kai can also be enabled via **Settings → Features** in your project. |
There was a problem hiding this comment.
I think it allows you to disable it once you approve it on a project IIRC. Not enable
…holesale David's #1106 (chat controls + Getting Started refresh) superseded most of this PR: Shift+A is fixed and the approve shortcut documented in plan mode. The still-unique fixes land in the next commit on top of his version. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
On top of the merged #1106 rewrite, the four still-unique corrections: frontmatter description; 'supported stacks' -> multi-tenant claim with the VERIFY(Jordan) note on single-tenant; A also closes the chat; the ] shortcut for switching between side panel and expanded view; the Cmd/Ctrl+Enter shortcut on tool approval (was documented only for plan mode). Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This branch was successfully deployed
4 participants
Moved off the fork from #1104 (same commit, same content) so CI and the Vercel preview run with repo credentials. Original PR closed; review here.
Jira issue(s): n/a — Linear PRDCT-654
Every button in the Kai chat panel is now explained in one place, in tables with icons. Deeper configuration stays in Kai Settings.
Changes:
kai-welcome.pngis deletedAll screenshots are real product captures. Icons are all 72x72.
@jordanrburger — draft. Three things I could not verify, all in the panel header table:
Two open bugs describe behaviour this page now documents as working:
Documenting intended behaviour still seems right, but worth knowing the docs and those tickets disagree.
Rate Limits is deliberately untouched. It documents the beta caps, which are correct until 15 September. The replacement belongs with #1102 (Kai Pricing and Limits), which should merge after this one and update that section to point at
/kai/pricing/.