AI Generation & Assistant

The CMS embeds an AI layer for generating components and pages and for driving the app conversationally. It lives under apps/cms/src/server/ai/ (see the README there) with prompts in apps/cms/src/prompts/. The default model is Cloudflare Workers AI (@cf/google/gemma-4-26b-a4b-it); generation flows also accept image input (Figma frames, screenshots, uploads).

Surfaces

Two chat surfaces share the plumbing but expose different tools:

• page-chat — the in-editor co-pilot. Scoped to the page in context; can mutate zones.
• assistant — the global assistant; broader management tools, also exposed over MCP.

Tools are filtered per surface by toolsForSurface(surface) (apps/cms/src/server/ai/tools/index.ts). Because Workers can’t auto-discover modules, the tool registry is an explicit list (tree-shaking-friendly).

Generation endpoints

Defined in apps/cms/src/server/routes/ai.ts:

Endpoint	Purpose
POST /ai/generate-component	Generate a section/component (streams via SSE). Also drives generate-from-figma / generate-from-stitch.
POST /ai/page-chat	In-editor co-pilot turn.
POST /ai/assistant-chat	Global assistant turn.
POST /ai/regenerate-page	Regenerate a page’s content.
POST /ai/apply-client-actions	Apply a batch of client actions.

Design tokens for the active edition are injected into the system prompt so output matches brand styling. The output contract for section generation (TSX + schema) is defined in apps/cms/src/prompts/section-generator-system.ts.

Client actions

Instead of tool-calling for UI side-effects, assistant replies may include a fenced ```client-actions block. apps/cms/src/server/ai/actions/parse.ts extracts it into a typed ClientAction union (navigate, open-modal, toast, reload-list, confirm-destructive, switch-context). Both sides of the network boundary share the same union — the server emits it, the client dispatches it (apps/cms/src/client/ai/actions/). Keep the two definitions in sync.

MCP bridge

apps/cms/src/server/ai/mcp-client.ts calls the external MCP worker (the MCP service binding) over JSON-RPC. It forwards context as headers (X-Alokai-CMS-Org-Id, X-Alokai-CMS-Space-Id, X-Alokai-CMS-Edition-Id) plus the caller’s auth. This is how the assistant surface reaches the full CMS tool set. See the MCP Server page for the external transport.

Prompts

Every prompt the worker sends lives in apps/cms/src/prompts/ (one file per prompt, <feature>-<role>.ts). System prompts define the role + output contract; user prompts carry per-request inputs via a single args object. Prompts may import type only — never runtime values from server/ or client/.

Voice

Voice mode is an alternate input to these same surfaces: audio → Whisper (POST /api/voice/transcribe) → page-chat / assistant → client actions. It adds no tools of its own.