docs: update ClickHouse chat agent example for generative UI

[matt-aitken]

Updates the ClickHouse chat agent example page to match the upgraded example (triggerdotdev/examples#124), which is now a fullstack generative-UI chat app rather than an agent-only project.

What changed

• Overview / tech stack / features rewritten: Next.js chat app (useChat + useTriggerChatTransport, no API route), a renderVisualization tool taking json-render specs rendered with @json-render/shadcn + shadcn charts (Recharts) + mapcn point maps, and a shared catalog that generates both the system-prompt component reference and tool-call validation.
• The agent section now shows the versioned AI Prompt pattern (prompts.define() + chat.prompt.set() + chat.toStreamTextOptions({ registry })), with a warning that experimental_telemetry comes from the stored prompt — the docs previously showed a static system: string, which silently ships no LLM observability.
• New sections for the shared catalog, the renderVisualization tool, the Next.js chat UI and registry.
• Relevant code links updated to the new src/ layout.
• Learn more cards now include Frontend and AI Prompts.

Note: merge after triggerdotdev/examples#124 lands, so the GitHub file links resolve.

🤖 Generated with Claude Code

[changeset-bot]

⚠️ No Changeset found

Latest commit: 9c0e806

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: 9cbbfd94-d101-476f-b53b-769fd658cf28

📥 Commits

Reviewing files that changed from the base of the PR and between 6e943f2 and 9c0e806.

📒 Files selected for processing (1)

• docs/guides/example-projects/clickhouse-chat-agent.mdx

📜 Recent review details

⏰ Context from checks skipped due to timeout. (2)

• GitHub Check: code-quality / code-quality
• GitHub Check: Analyze (javascript-typescript)

🧰 Additional context used

📓 Path-based instructions (1)

docs/**/*.mdx

📄 CodeRabbit inference engine (docs/CLAUDE.md)

docs/**/*.mdx: MDX documentation pages must include frontmatter with title (required), description (required), and sidebarTitle (optional) in YAML format
Use Mintlify components for structured content: , , , , , , /, /
Always import from @trigger.dev/sdk in code examples (never from @trigger.dev/sdk/v3)
Code examples must be complete and runnable where possible
Use language tags in code fences: typescript, bash, json

Documentation in docs/ uses MDX conventions defined by the documentation guidance.

Files:

• docs/guides/example-projects/clickhouse-chat-agent.mdx

🧠 Learnings (2)

📚 Learning: 2026-03-10T12:44:14.176Z

Learnt from: nicktrn
Repo: triggerdotdev/trigger.dev PR: 3200
File: docs/config/config-file.mdx:353-368
Timestamp: 2026-03-10T12:44:14.176Z
Learning: In the trigger.dev repo, docs PRs are often companions to implementation PRs. When reviewing docs PRs (MDX files under docs/), check the PR description for any companion/related PR references and verify that the documented features exist in those companion PRs before flagging missing implementations. This ensures docs stay in sync with code changes across related PRs.

Applied to files:

• docs/guides/example-projects/clickhouse-chat-agent.mdx

📚 Learning: 2026-04-30T20:30:29.458Z

Learnt from: ericallam
Repo: triggerdotdev/trigger.dev PR: 3226
File: docs/ai-chat/quick-start.mdx:13-13
Timestamp: 2026-04-30T20:30:29.458Z
Learning: In this repo’s documentation MDX files (`docs/**/*.mdx`), use `ts` and `tsx` (not `typescript`) as the code-fence language tags for TypeScript/TSX snippets. Do not flag `ts`/`tsx` code-fence language tags as incorrect in any docs MDX file, since this is the site-wide Mintlify-compatible convention.

Applied to files:

• docs/guides/example-projects/clickhouse-chat-agent.mdx

🔇 Additional comments (6)

docs/guides/example-projects/clickhouse-chat-agent.mdx (6)

4-28: LGTM!

---

45-83: LGTM!

---

84-91: 🎯 Functional Correctness | ⚡ Quick win

Confirm tools is still wired into the model call.

run() destructures tools (line 84) but the visible streamText config only spreads chat.toStreamTextOptions({ registry }) (line 91) — tools isn't referenced in the shown lines. Trigger.dev's own reference pattern forwards it explicitly: "...chat.toStreamTextOptions({ tools }), model: anthropic("claude-sonnet-4-5"), messages, abortSignal: signal, stopWhen: stepCountIs(15)," with the comment that this "Wires the system prompt, tool approval (HITL), compaction, mid-turn steering, and telemetry."

Since the snippet is truncated right after line 91 (---- unchanged lines 92-100 not shown ----), tools may well be forwarded as a separate key just below — but worth double-checking the full file so listTables/describeTable/runQuery/renderVisualization are actually passed to the model (either via chat.toStreamTextOptions({ registry, tools }) or a direct tools, property).

---

101-168: LGTM! The shared catalog / catalogPromptSection() / validateSpec() pattern and the renderVisualization tool's validate-then-respond flow are consistent and well-documented.

---

170-211: LGTM! useChat + useTriggerChatTransport and the registry-to-React-component mapping are consistent with the catalog defined earlier and use verified official import subpaths (@trigger.dev/sdk/chat/react).

---

213-289: LGTM! The query tool's double guard (regex allowlist + ClickHouse readonly=2/row cap/timeout) is clearly framed as defense-in-depth, and the "Running it" env vars, commands, links, and Learn More cards are all internally consistent with the rest of the guide.

---

Walkthrough

The guide now describes a ClickHouse chat agent that generates interactive charts, tables, stat cards, and maps through a validated renderVisualization tool and json-render. It updates prompt resolution, streaming, catalog synchronization, frontend rendering, read-only SQL validation, environment configuration, commands, links, and learning resources.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Description check	⚠️ Warning	The description explains the change well, but it omits the required template sections like Closes, Checklist, Testing, Changelog, and Screenshots.	Add the missing template sections and fill in Closes #issue, checklist items, testing steps, a changelog entry, and screenshots if applicable.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly summarizes the main documentation update for the ClickHouse chat agent's generative UI workflow.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/clickhouse-example-generative-ui

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[devin-ai-integration]

✅ Devin Review: No Issues Found

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