Add the Snowplow Assistant chat drawer

[jborlase-snowplow]

Summary

Adds the Snowplow Assistant to the docs site: an Ask AI button beside the search box opens a resizable right-side drawer that answers questions from the documentation, with citations.

• Widget (src/components/Assistant/): Vercel AI SDK useChat + DefaultChatTransport; AI Elements components vendored from the Console into src/components/ai-elements/ and ported to Tailwind 3.4; answers rendered with streamdown (sanitized). Lazy-loaded on first open so docs pages do not download the chat bundle. Mounted in src/theme/Root.js so an open conversation survives navigating to a linked page; internal links open in the same tab. Drag the left edge to resize (380–1100 px, remembered in localStorage; arrow keys and double-click reset for accessibility). Single conversation kept in sessionStorage.
• Worker proxy (worker/assistant.js, wired in worker/index.js before tracking): POST /api/assistant/chat only, 128 KB body cap, 10 requests/minute per IP via the Workers rate-limiting binding, adds X-Docs-Assistant-Secret, forwards to ${DOCS_ASSISTANT_AGENT_URL}/api/agent/docs/chat, streams back. Fails closed (503) if unconfigured. JSON errors carry status so the widget shows a countdown on 429.
• Config: wrangler.jsonc gains vars.DOCS_ASSISTANT_AGENT_URL and the ASSISTANT_RATE_LIMITER binding; wrangler ^4.36 added as a devDependency. .dev.vars / .wrangler gitignored.
• Also: Tailwind 3.3 → 3.4.19 (+ tailwindcss-animate), zod bumped for ai@7, a dev-server proxy plugin (ASSISTANT_PROXY_TARGET), Snowplow assistant_interaction events matching the Console, the prompt form excluded from form tracking, Product Fruits / Qualified hidden while the drawer is open. ARCHITECTURE, WORKFLOWS and CONTRIBUTING updated.

Depends on snowplow-product/console-agent feat/docs-assistant being deployed first; until then the button shows but questions return "The assistant is unavailable right now".

Before merging

• Reviewer runs yarn build locally (no build runs in CI). It passes on this branch.
• Set the Worker secret DOCS_ASSISTANT_SHARED_SECRET in Cloudflare (same value as the agent's SSM parameter).
• Decide on preview builds for the Worker: preview versions run with production secrets, so either disable them or give non-production branches an environment without the secret.
• Click through the homepage, a tutorial and a release note after the Tailwind upgrade.

Test plan

• yarn build succeeds; streamdown/shiki are not in the main bundle
• Headless browser run: drawer opens with focus in the textbox, extra chunks load only on open, answer streams with a "Searched documentation: …" row and a citation, internal link navigates in the same tab with the conversation intact, Esc closes, conversation restored after reload, resize by drag / keyboard / double-click, no console errors or warnings
• Through wrangler dev: GET → 405, unknown path → 404, 200 KB body → 413, real question streams, 11th request in a minute → 429
• Production: curl -i https://docs.snowplow.io/api/assistant/chat → 405; no /api/ page views in the docs-cloudflare app

Follow-up

• Trim conversation history client-side so long chats never hit the agent's 20-message / 40k-character limit (today they get a generic error).

🤖 Generated with Claude Code

[github-actions]

Missing SEO metadata

The following markdown files are missing required metadata fields:

• ARCHITECTURE.md: missing frontmatter block
• WORKFLOWS.md: missing frontmatter block

Required fields

The file metadata is important for SEO and marketing. All markdown files, except for those with filenames starting with _, should include:

• title: Full, descriptive page title
• sidebar_label: Short title for navigation sidebar (can be the same as the main title)
• description: One to two sentences summarizing the page contents
• keywords: Array of marketing/SEO keywords

Please add the missing metadata.

[wiz-2cefcfbd9e]

Wiz Scan Summary

Scanner	Findings
Vulnerabilities	2  3  1
Sensitive Data	-
Secrets	-
IaC Misconfigurations	-
SAST Findings	-
Software Management Findings	-
Total	2  3  1

View scan details in Wiz

To detect these findings earlier in the dev lifecycle, try the Wiz Code extension for VS Code, JetBrains, or Visual Studio.

[claude]

Docs style review

Scope here is the prose in the three Markdown files this PR touches (ARCHITECTURE.md, CONTRIBUTING.md, WORKFLOWS.md) plus user-facing strings. These are contributor docs rather than published /docs pages, so the frontmatter and index.md rules don't apply — but the terminology and formatting rules still do. No technical comments below.

UI elements should be bold, not quoted

The "Ask AI" button in the navbar opens a chat drawer… (ARCHITECTURE.md:68)

The style guide's Bold, italic, and code section says "Use bold for UI elements: buttons, page titles, tabs, menus", and CLAUDE.md says bold is only for UI elements. Use **Ask AI** instead of "Ask AI". Same fix applies at CONTRIBUTING.md:320 (The "Ask AI" drawer calls…) and to the dashboard path in WORKFLOWS.md (Workers & Pages → documentation → Settings → Variables and Secrets) — bold the labels. The & there is Cloudflare's own label, so leave it as-is despite the "use and, never &" rule.

"Console" takes no article

It is the Snowplow Console's assistant (the console-agent service)… (ARCHITECTURE.md:68)
…using the same schema and event specifications as the Console. (ARCHITECTURE.md:76)

Style guide, Snowplow terminology: "Console: Capitalized, no article. Data structures in Console." Suggest "It is Console's assistant…" and "…the same schema and event specifications as Console."

Use yarn, not npx

npx wrangler dev / npx wrangler secret put DOCS_ASSISTANT_SHARED_SECRET

CLAUDE.md → Development workflow: "Use yarn, not npm." Since this PR adds wrangler as a devDependency, yarn wrangler dev and yarn wrangler secret put … are both correct and consistent with the rest of the repo's instructions. Appears in CONTRIBUTING.md:326, ARCHITECTURE.md:74, and WORKFLOWS.md. (The npm run dev for console-agent is a different repo's command — fine to leave.)

Code block missing a language

DOCS_ASSISTANT_AGENT_URL=http://localhost:3001

(CONTRIBUTING.md, step 1)

Style guide, Markdown formatting: "Use triple backticks and specify the language for code blocks." Use ```ini (or ```bash).

Missing commas after leading clauses

Without both the Worker answers 503. (ARCHITECTURE.md:74)
Without the Worker the drawer still opens, but… (CONTRIBUTING.md:328)

Both need a comma after the introductory phrase: "Without both, the Worker returns 503." and "Without the Worker, the drawer still opens…". ("Returns 503" also reads better than "answers 503".)

Inconsistent names for the feature

The same thing is called Snowplow Assistant (heading, drawer title), "the assistant" (## Run the assistant locally), "the AI assistant drawer" (the new tracking table row), and Ask AI (the button). Pick one product name — "Snowplow Assistant" — and use Ask AI only for the button. Suggest Run Snowplow Assistant locally for the CONTRIBUTING heading and "assistant_interaction events from the Snowplow Assistant drawer" in the table row.

Readability of the Frontend. paragraph

ARCHITECTURE.md:74 is a single ~90-word sentence chaining four separate facts (mount point, navbar registration, lazy loading, the SDK stack). Worth splitting into two or three sentences; the neighboring Request path. and Configuration. paragraphs read fine.

Smaller points

• DOCS_ASSISTANT_AGENT_URL is a plain var in wrangler.jsonc (ARCHITECTURE and WORKFLOWS) — "var" is jargon. Suggest "a plain variable (a vars entry in wrangler.jsonc)".
• running in a documentation-only mode — drop the article: "running in documentation-only mode".
• the agent only has the two documentation tools — "the two documentation tools" hasn't been introduced; naming them would help a future reader.
• UI microcopy (Thinking…, Searching documentation: …, Scroll to latest message) uses ellipses and "latest", which the style guide bars in docs prose. Conventional for loading states and mostly inherited from the vendored AI Elements components, so non-blocking — flagging once rather than per line.

Release note

CLAUDE.md says new user-facing functionality needs a release note in the same PR or a linked follow-up, while release-notes/_README.md excludes "internal repo changes, such as tooling and CI". Ask AI is user-facing but it's a docs-site feature rather than a product change, so this falls in the gap — the guidance is to ask rather than guess. Is a Product news note planned for this?

Links

Both new cross-file anchors resolve (ARCHITECTURE.md#snowplow-assistant, CONTRIBUTING.md#run-the-assistant-locally), and the TOC entry matches its heading. The only external URL on a touched line is https://docsearch.algolia.com (in the reworded Overview sentence) — returns 200.

[cloudflare-workers-and-pages]

Deploying with    Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

Status	Name	Latest Commit	Preview URL	Updated (UTC)
✅ Deployment successful! View logs	documentation	e332e4e	Commit Preview URL Branch Preview URL	Sep 14 2026, 04:45 PM