{"schemaVersion":1,"buildSha":"23d142e6d4ce6954c54a9130bd59de1dfb2a2828","builtAt":"2026-10-22T19:43:31.078Z","pages":[{"path":"/agentic-app-builders.md","title":"For Agentic App Builders","description":"Make your existing SaaS or webapp something an AI agent can drive — without rewriting the frontend. Vision page + waitlist for the agentic-app track, productized by guuey.","body":"---\ntitle: For Agentic App Builders\ndescription: Make your existing SaaS or webapp something an AI agent can drive — without rewriting the frontend. Vision page + waitlist for the agentic-app track, productized by guuey.\n---\n\n:::caution[Vision page]\nThis describes a direction, not a shipped product. If you're building agents **today**, take the [hosted quickstart](/quickstart/hosted-agent/) or the [self-hosted one](/quickstart/self-hosted/) — those paths are live. The waitlist at the bottom is for early access to this track when its first adapter lands.\n:::\n\n## What an agentic app is\n\nAn agentic app is a product you have already shipped, driven by an agent instead of only by hands. The user asks for the outcome — \"refund last month's invoice for this customer\" — and the agent works the real flows of your app to get there, in typed calls rather than simulated clicks.\n\nThe part that matters commercially is what it does **not** require: a frontend rewrite. Your React app, your Rails views, your existing routes and permissions all stay. Agent access arrives as a second, parallel surface onto the same flows, not as a replacement for the one your users already know.\n\nToday agents reach existing SaaS through three unreliable layers: **reading screenshots** (vision models reasoning about pixels — brittle, slow, no typed I/O), **browser automation** (Playwright scripts that snap the moment a button moves, with no way for the agent to learn the contract changed), and **official APIs** (when they exist, and only for the slice they cover — most production apps keep a large share of their behavior in the UI). What's missing between an agent and an app it did not generate is a **typed contract**.\n\n## The adapter approach\n\nYou add a GGUI adapter beside your existing app rather than inside it. The adapter reads your app's routes and describes them in the protocol's own terms: each navigable route becomes a **render** with a typed contract, form fields become **`actionSpec`** entries (typed inbound actions that drive turns), visible state becomes **`contextSpec`** (read-only state the agent observes), and browser-only libraries you depend on — Stripe Checkout, Mapbox, a calendar picker — are wrapped as **gadgets** so a model knows how to compose with them.\n\nFrom the agent's side, nothing is special about your app. It drives it through `ggui_handshake`, `ggui_render`, and `ggui_consume` exactly as it drives a freshly generated GGUI UI: same MCP wire, same contract guarantees, same failure modes. From your users' side, nothing changed at all — they keep clicking the buttons that were always there.\n\n## What you'd write\n\nThe provisional shape is a `ggui.app.json` next to your existing app config:\n\n```json\n{\n \"name\": \"my-saas\",\n \"routes\": [\n {\n \"path\": \"/invoices/new\",\n \"intent\": \"create an invoice\",\n \"agentCapabilities\": {\n \"tools\": {\n \"createInvoice\": {\n \"toolInfo\": { \"inputSchema\": { \"$ref\": \"./schemas/invoice.json\" } }\n }\n }\n },\n \"actionSpec\": {\n \"submit\": {\n \"label\": \"Create invoice\",\n \"schema\": { \"$ref\": \"./schemas/invoice.json\" },\n \"nextStep\": \"createInvoice\"\n }\n },\n \"contextSpec\": {\n \"currentDraft\": { \"schema\": { \"$ref\": \"./schemas/invoice-draft.json\" } }\n }\n }\n ]\n}\n```\n\nYour app code stays as-is. An agent runtime can now discover `/invoices/new` from the adapter's catalog, `ggui_handshake` against its contract, and `ggui_render` with a typed payload — no clicking around. (Exact wire shape for app-catalog lookup is part of the SDK's in-design surface.)\n\n## Where this is built: GGUI vs guuey\n\nThe hosted product this track becomes is **guuey**'s — a separate agent-hosting platform, at [guuey.com](https://guuey.com), built on the GGUI protocol. GGUI (this site) documents the protocol; guuey productizes hosting. guuey is not a paid tier of GGUI, and it is not run from this site.\n\nThe split is clean and worth internalizing before you plan against it:\n\n- **GGUI** (this site) is the open protocol and its hosted deployment. It defines the contract, the `ggui_*` tool surface, and the render lifecycle, and it documents both the [hosted](/quickstart/hosted-agent/) and [self-hosted](/quickstart/self-hosted/) ways to run it. The spec and the SDKs are open source.\n- **guuey** productizes hosting on top of that protocol: running your agent, the operational surface around it, and — for this track — the hosted service that keeps an adapter pointed at your live app.\n\nThe protocol side of the adapter (contracts, gadgets, the wire shape above) belongs to GGUI and will be documented here. The hosted service that runs it for you belongs to guuey and will be documented there. If a future page tells you an agentic-app feature is \"part of GGUI\", check which of those two it actually is.\n\n## Three scenarios this unlocks\n\n1. **Your support agent drives the app for the customer.** \"Refund last month's invoice for customer X\" → agent navigates to `/invoices/`, finds the row, calls `refund` with the typed payload. No human-in-the-loop browsing.\n\n2. **Your sales engineer runs an agent-narrated demo.** During a prospect call, the agent narrates while driving the form in real-time. The prospect sees the same UI any user sees, but the agent's typed actions land like a polished guided tour.\n\n3. **Power users hand work off to their AI.** \"I have 40 of these to fill in — can my AI do it?\" The AI has a typed surface to drive, not pixels to scrape.\n\n## What's shipping when\n\n| Component | Owner | Status |\n| --------------------------------------------------------- | ----- | --------- |\n| GGUI protocol (this site) | GGUI | Live |\n| Building a ggui-native agent | GGUI | Live |\n| Agentic App SDK (the adapter you'd add to your app) | GGUI | In design |\n| Hosted service that runs an adapter against your live app | guuey | In design |\n| Reference adapters for Next.js / Rails / Django | GGUI | Planned |\n| Reference adapters for legacy stacks (Java EE, Drupal, …) | GGUI | Planned |\n\nNo dates. Real engineering work, not a marketing roadmap.\n\n## Waitlist\n\nThe adapter SDK half of this track is still in design here. The guuey platform is in open public beta at [guuey.com](https://guuey.com) — anyone can deploy a hosted agent today. If the hosted product is what you want, start there.\n\nIf it's the adapter itself you need — you'd rather run it yourself against the open protocol — drop your email below. We'll write when the first adapter ships and we have an early-access slot to fill.\n\n\n \n
\n \n \n
\n

\n Opens your mail client with a pre-filled message. We'll wire up a real\n intake form before the first adapter lands — until then this stays a\n direct mailto so nothing intermediates the signal.\n

\n\n\n\n\n## Related\n\n- [How GGUI works](/how-it-works/) — the protocol's five moments. The gguify pattern reuses the same handshake → render → interact → consume → reopen loop, just driven by your app's routes instead of LLM-generated UI.\n- [Glossary](/glossary/) — `actionSpec`, `contextSpec`, `gadget`, `tool`, `blueprint`.\n- [The dev loop](/build/dev-loop/) — how a GGUI agent moves between a local runtime and hosted ggui. The adapter track inherits the same split.\n- [For LLM agents](/agents/) — machine-readable resources, including this page at [`/agentic-app-builders.md`](/agentic-app-builders.md)."},{"path":"/agents.md","title":"For LLM agents","description":"Machine-readable resources for LLMs and coding-assistant devtools reading GGUI docs programmatically — aggregated dumps, per-page .md companions, stable anchors, wire schemas.","body":"---\ntitle: For LLM agents\ndescription: Machine-readable resources for LLMs and coding-assistant devtools reading GGUI docs programmatically — aggregated dumps, per-page .md companions, stable anchors, wire schemas.\n---\n\nThis page is for **non-human readers** — LLM agents, coding-assistant devtools (Claude Code, Cursor, Cline, Continue, Codeium), evaluators, and scrapers. Humans, the rest of the site is for you.\n\n## What's available\n\n| Resource | URL | When to fetch |\n| --------------------- | ---------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| Dump pointer | [`/llms.txt`](/llms.txt) | First contact. A short [llms.txt](https://llmstxt.org/) file naming the two dumps below plus 11 per-section subsets, one per top-level sidebar group. It is not a per-page list — the finest granularity it indexes is the section. |\n| Whole-site dump | [`/llms-full.txt`](/llms-full.txt) | One-shot context loading. Every page in one file, sorted to lead with Get Started, Concepts, then the hosted track — around 800 KB, roughly 200K tokens. Check `Content-Length` before you load it. |\n| Compact dump | [`/llms-small.txt`](/llms-small.txt) | The same page set with navigational chrome stripped. Only about 15 percent smaller than the full dump — if full does not fit, this probably will not either. |\n| Per-section subset | `/_llms-txt/.txt` | One sidebar group at a time — `get-started`, `concepts`, `hosted`, `build`, `connect`, `self-host`, `protocol`, `api`, `cli`, `architecture`, `reference` (slugs listed in `/llms.txt`). A few pages are cross-listed in two sets where the sidebar itself repeats them (e.g. `cli/login` in both `hosted` and `cli`). |\n| Per-page raw markdown | `/.md` | Reading one specific page. No HTML, no chrome. |\n| Whole-site corpus | [`/docs-corpus.json`](/docs-corpus.json) | Every page as one JSON document — `{ schemaVersion, buildSha, builtAt, pages: [{ path, title, description, body }] }`, where each `body` is exactly the bytes that page's `.md` companion serves. Built for the docs MCP service behind `mcp.ggui.ai/docs`; fetch it once and refresh on the `Cache-Control` TTL. |\n| Stable anchors | `/#` | Deep-linking to a section. Every H2/H3 has a Starlight-derived id. |\n\nBoth dumps carry the site's `404 — page not found` stub as an early section. It is navigation copy, not documentation — skip it.\n\n## Per-page `.md` companions\n\nEvery page is also served as raw markdown at the same slug with a `.md` extension. Examples:\n\n- [`/how-it-works.md`](/how-it-works.md) — the narrative walk-through\n- [`/api/mcp-protocol.md`](/api/mcp-protocol.md) — the wire reference\n- [`/protocol/envelopes.md`](/protocol/envelopes.md) — live-channel envelope shapes\n- [`/glossary.md`](/glossary.md) — terminology lookup\n- [`/cli/serve.md`](/cli/serve.md) — `ggui serve` command reference\n\nThe `.md` response is the source markdown with a small `---\\ntitle: ...\\n---` envelope on top. For the markdown-authored pages — every page except the four named below — there is no other transformation.\n\nFour pages are authored in MDX and their companions carry that through: [`/index.md`](/index.md), [`/design/tokens.md`](/design/tokens.md), [`/protocol/showcase-trimly.md`](/protocol/showcase-trimly.md) and [`/build/dev-loop.md`](/build/dev-loop.md) keep their JSX component tags (``, ``, ``), and `showcase-trimly` also carries the inline JS block that computes its wire counts. The ESM import preamble is stripped, so the response opens on prose, but the components are not rendered. Prose and code blocks are intact on all four; layout wrappers are not. Fetch the HTML page when you need the rendered form — on `/design/tokens.md` and `/protocol/showcase-trimly.md` in particular, much of the substance lives inside the components.\n\nFetch from any origin:\n\n```bash\ncurl https://docs.ggui.ai/protocol/envelopes.md\n```\n\n```ts\nconst res = await fetch(\"https://docs.ggui.ai/protocol/envelopes.md\");\nconst body = await res.text();\n```\n\nCORS is open (`Access-Control-Allow-Origin: *`); `Cache-Control` permits 5-minute CDN caching.\n\n## Search docs via MCP\n\nAny LLM agent can connect to `mcp.ggui.ai/docs` and search / read these docs programmatically — no auth required. See [Docs MCP route](/api/mcp-docs/) for the tool catalog and connection details.\n\n## When to use which\n\n```\nYou want → Fetch\n─────────────────────────────────────────── ──────────────────────────────────\nSee which dumps and sets exist /llms.txt\nOrient quickly, plan a session /index.md, then /.md\nDrop everything into context (one-shot) /llms-full.txt (~800 KB)\nLoad just one sidebar section /_llms-txt/.txt\nRead one specific page /.md\nDeep-link to a section in conversation //#\n```\n\n`/llms.txt`, `/llms-full.txt`, `/llms-small.txt`, the 11 `/_llms-txt/.txt` section subsets, and the per-page `.md` companions are the whole machine-readable surface.\n\n## Stable anchors\n\nEvery H2 and H3 has a stable `id` derived by Starlight from its text. Anchors don't change between releases unless the heading text changes. Examples:\n\n- [`/glossary/#gguisession-a-render`](/glossary/#gguisession-a-render) — definition of the GguiSession (the \"render\")\n- [`/protocol/envelopes/#actionenvelope`](/protocol/envelopes/#actionenvelope) — inbound live-channel envelope\n- [`/api/mcp-protocol/#ggui_render`](/api/mcp-protocol/#ggui_render) — the `ggui_render` MCP method\n\nThe same anchors work on the `.md` companions: [`/protocol/envelopes.md#actionenvelope`](/protocol/envelopes.md#actionenvelope) — markdown clients with anchor-scroll support honor them.\n\n## Wire schemas (roadmap)\n\nThe wire envelopes (`ActionEnvelope`, `StreamEnvelope`) and the MCP method shapes (`ggui_handshake`, `ggui_render`, `ggui_consume`, …) live in TypeScript in `@ggui-ai/protocol`. Protocol version: see `PROTOCOL_VERSION` in `@ggui-ai/protocol` (currently `draft-2026-09-10`). Standalone JSON-Schema endpoints at `/api/schemas/.json` are planned but not yet shipped.\n\nUntil then, the canonical wire shapes live at:\n\n- [`/protocol/envelopes/`](/protocol/envelopes/) — envelope shapes, fields, validation rules\n- [`/api/mcp-protocol/`](/api/mcp-protocol/) — MCP methods, request/response shapes\n- [`/api/websocket-protocol/`](/api/websocket-protocol/) — live-channel framing\n\nFor machine-parseable types, install the npm package:\n\n```bash\nnpm install @ggui-ai/protocol\n```\n\n## Site conventions\n\nThings to know if you're writing code against these docs:\n\n- **`ggui`** = the open protocol. Self-host with `ggui serve`, or use the hosted endpoint at `mcp.ggui.ai`. Open source at `github.com/ggui-ai/ggui`. Documented on this site.\n- **`guuey`** = a separate SaaS platform at `guuey.com`. Different surface, different docs. Don't conflate the two.\n- **`gadget`** = renderer-side capability — a wrapped 3rd-party library (`Leaflet`, `Stripe`, …). Formerly called `clientLibraries`.\n- **`tool`** = agent-side action (an MCP tool the agent invokes).\n- **`blueprint`** = cached UI recipe (matched at `ggui_handshake` by intent + contract similarity).\n\nThese three nouns are not interchangeable; mixing them in generated code will confuse readers.\n\n## Page-level metadata\n\nEvery page has frontmatter with at least `title` and `description`. Most also carry `audience` (one of `agent-builder`, `host`, `operator`, `llm-agent`, `agentic-app-builder`, `all`) and optionally `prereqs`. The `.md` companion re-emits `title` and `description` at the top of the response; other frontmatter fields (`audience`, `prereqs`) are only in the repo source.\n\n## Telemetry\n\nThe site sends pageview events to PostHog and tags requests from known LLM-agent user-agents (`claude-bot`, `gptbot`, `perplexitybot`, `cursor`, `cline`, `continue`, `codeium`, …) with `is_bot: true`. No PII, no fingerprinting. Set a useful user-agent and you'll show up in the bot-traffic dashboard — that helps us prioritize docs machine readers actually use.\n\n## Reporting issues\n\nFound a page that's hard for LLM consumption, or want a `.md` companion that's missing something? Open an issue at [`github.com/ggui-ai/ggui/issues`](https://github.com/ggui-ai/ggui/issues) tagged `docs/llm-readability`."},{"path":"/api/control-mcp.md","title":"Control MCP plane","description":"MCP tools on the /control plane — design-time protocol tools (anonymous) plus operator actions (apps, orgs, connector keys, coupons, blueprints, provider keys, credits) for operator agents.","body":"---\ntitle: Control MCP plane\ndescription: MCP tools on the /control plane — design-time protocol tools (anonymous) plus operator actions (apps, orgs, connector keys, coupons, blueprints, provider keys, credits) for operator agents.\n---\n\nThe `/control` plane is one of GGUI's two MCP surfaces. It carries everything called _around_ a session rather than during one:\n\n- **Design-time `protocol` tools** — format references, example blueprints, validators. Answered **anonymously**, because an agent authoring a blueprint has no account yet. See [MCP protocol](/api/mcp-protocol/) for those tools.\n- **Operator-class `ops` tools** — the same actions the [console UI](/hosted/console/) exposes to a human (create an app, rename it, mint a connector key, redeem a coupon, …), exposed as MCP tools so an LLM acting as an operator agent can perform them on the user's behalf. **Auth required**, and **confirm-gated** when state-changing.\n\nThis page is the wire reference for the 16 ops-audience handlers across four domains that ship in the open `@ggui-ai/mcp-server-handlers` package, plus the 24 hosted-only ops tools that live directly in the cloud pod's own tool registry and answer only on `mcp.ggui.ai` (see [Hosted-only ops](#hosted-only-ops) below). The agent-loop surface (handshake / render / consume / …) lives on the [`/mcp`](/api/mcp-protocol/) data plane and is documented separately — the two surfaces are strictly disjoint.\n\n:::note[Audience tags]\nEvery handler in this package carries an `audience: ['ops']` tag, which determines mounting. See [Audience Routes](/architecture/audience-routes/) for the full model — four tags, two surfaces: the `/mcp` data plane (`agent` + `runtime`) and the `/control` plane (`protocol` + `ops`). The tag is the source of truth; the surface is the projection.\n:::\n\n## What's on /control\n\nThe ops half is the destination for an **operator agent** — an LLM acting as the console's hands. Typical caller: a Claude conversation that the user opens from `console.ggui.ai` and gives natural-language instructions like \"create a new app called Inbox Triage and lock a connector key to it.\" The agent calls `ggui_ops_create_app` followed by `ggui_ops_issue_connector_key`, never touching the AppSync GraphQL layer directly.\n\nEvery tool here mirrors a UI action the console exposes. The open apps handlers in `@ggui-ai/mcp-server-handlers` are pure over typed seams (`AppsSource`, `UserDefaultAppSource`) — the cloud pod binds AppSync-backed adapters; OSS deployments leave the seams unwired and the surface stays narrow. Orgs, connector keys and coupons are hosted-only tools (see [Hosted-only ops](#hosted-only-ops)).\n\n## Endpoint\n\n```\nPOST http://127.0.0.1:6781/control\n```\n\nThe route is **always mounted** — the control plane is part of what a GGUI server is, not an opt-in. A default self-hosted boot serves the 6 design-time `protocol` tools there. The `ggui_ops_*` families register when the operator seams are wired into `createGguiServer({opsApps})` (the ops-blueprint family additionally hangs off the `opsBlueprint` dep bundle). Hosted GGUI serves the same route at `https://mcp.ggui.ai/control`, with every domain bound — the full hosted surface is 46 tools: 6 protocol + 40 ops (the 16 handler-package tools below, including provider-keys and credits, plus the 24 hosted-only tools in [Hosted-only ops](#hosted-only-ops)). See \"OSS vs hosted\" below for what a self-hosted deployment gets instead.\n\n## Authentication\n\n`/control` is **anonymous-capable**: a request with no bearer is admitted with a synthesized anonymous identity so the design-time `protocol` tools answer. Every `ggui_ops_*` handler then re-imposes auth for itself — an anonymous caller gets an auth error naming the tool, not a silent no-op and not a transport-level 401.\n\nAuthenticated callers present a bearer exactly as on [`/mcp`](/api/mcp-protocol/#authentication), via the same upstream `AuthAdapter`:\n\n```\nAuthorization: Bearer dev\nContent-Type: application/json\n```\n\nSelf-hosted: with `ggui serve --dev-allow-all`, any bearer (or none) authenticates as the `builder` identity; default serve requires a pairing-minted bearer. Hosted GGUI runs the OAuth 2.0 Dynamic Client Registration ceremony (see [OAuth on mcp.ggui.ai](/self-hosted/oauth/)). The bearer presented on `/control` is the same bearer presented on `/mcp` — there is no separate \"ops token\".\n\nExternally-federated end-user identities (`source: 'oidc'`) are rejected at the route with `403`, before MCP dispatch. The control plane is for the account holder and their operator agents, not for an app's end users.\n\n## Confirmation gate on state-changing tools\n\nAn `ops` tool that changes state answers the first call with a **preview** and mutates nothing. Only a second call carrying `confirm: true` commits:\n\n```jsonc\n// 1st call → preview, nothing happens\n{\"name\": \"ggui_ops_delete_app\", \"arguments\": {\"appId\": \"aB3kP9xY\"}}\n// → {\"confirmationRequired\": true, \"confirmationPrompt\": \"…\"}\n\n// 2nd call → commits\n{\"name\": \"ggui_ops_delete_app\", \"arguments\": {\"appId\": \"aB3kP9xY\", \"confirm\": true}}\n```\n\nThe gate exists so an agent cannot silently mint credentials, spend credits, or delete resources on the user's behalf: it forces the agent to show the human what will happen and get explicit approval. Reads and lists are single-call.\n\nClassification is **default-deny** — an `ops` tool not on the read-only list is treated as state-changing. Deployments that register their own read-only ops tools declare them via `createGguiServer({control: {singleCallOps: [...]}})`.\n\nThe single-call ops tools (`SINGLE_CALL_OPS`, 15 entries) are: `ggui_ops_list_apps`, `ggui_ops_list_orgs`, `ggui_ops_list_connector_keys`, `ggui_ops_list_blueprints`, `ggui_ops_list_my_apps`, `ggui_ops_list_my_blueprints`, `ggui_ops_list_provider_keys`, `ggui_ops_list_credit_transactions`, `ggui_ops_list_recent_renders`, `ggui_ops_get_credit_balance`, `ggui_ops_get_org_balance`, `ggui_ops_get_my_blueprint_source`, `ggui_ops_get_render_source`, `ggui_ops_setup_byok`, and `ggui_ops_save_library_blueprint`.\n\nFourteen of those are genuine reads. `ggui_ops_save_library_blueprint` is the one deliberate exception — a MUTATION added to the single-call set by owner ruling (GGUI#525, 2026-08-16). It earns the exemption on three properties: it's idempotent (same name ⇒ one row, a repeat is a no-op), it writes only to the caller's own library (no cross-tenant or account-wide effect), and its primary caller is the console helper agent auto-saving after a render, where the confirm round-trip was an agent self-confirm with no human in the loop — it bought no safety and cost an extra call on every helper render. A future single-call entry that lacks any of those three properties does not inherit this ruling on its own.\n\n## Identity model\n\nEvery handler resolves the calling identity through a single helper:\n\n```typescript\nfunction resolveOwnerSub(toolName: string, ctx: HandlerContext): string {\n const sub = ctx.userId ?? ctx.appId;\n if (!sub) throw new Error(`${toolName}: missing caller identity`);\n return sub;\n}\n```\n\n- **Hosted (multi-tenant):** `ctx.userId` is the caller's Cognito sub, populated by the upstream auth adapter.\n- **OSS (single-tenant):** `ctx.userId` is undefined; `ctx.appId` (resolved by the auth adapter via `defaultAppIdFromIdentity` — typically `workspaceId ?? userId` for kind=user identities) serves as the identity.\n- **Neither set:** the handler throws — that means an unauthenticated caller slipped past auth, surfaced as a 5xx rather than masked as an empty list.\n\n### Tenancy posture\n\nEvery read and write is scoped by the resolved identity at the seam layer (`AppsSource.list(ownerSub)` returns only the caller's rows; `AppsSource.get` returns `null` for foreign rows). Cross-tenant probes never reveal whether a given id exists on another user's account — the handlers translate \"row exists but you don't own it\" to the same shape as \"no such row\":\n\n| Operation | Cross-tenant probe |\n| --------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- |\n| `ggui_ops_list_apps` | Returns only caller's rows; foreign rows invisible. |\n| `ggui_ops_update_app` / `ggui_ops_set_app_theme` / `ggui_ops_set_default_app` | Throws `app_not_found` — same as a genuinely missing id. |\n| `ggui_ops_delete_app` | Returns `{deleted: true}` without touching the foreign row. Uniform with \"row didn't exist.\" |\n| `ggui_ops_rename_org` / `ggui_ops_remove_org_member` / `ggui_ops_get_org_balance` | Throws `org_not_found` for orgs the caller isn't a member of — same as a missing id. |\n| `ggui_ops_invite_to_org` / `ggui_ops_revoke_invite` | Throws `org_invite_access_denied` for orgs the caller doesn't administer. |\n| `ggui_ops_revoke_connector_key` | Throws `connector_key_access_denied` for keys owned by other users. |\n| `ggui_ops_redeem_coupon` | Throws `coupon_access_denied` for `targetOrgId` orgs the caller isn't a member of. |\n| `ggui_ops_set_provider_key` / `ggui_ops_remove_provider_key` with `appId` | Throws `app_not_found` for apps the caller doesn't own — same as a missing id. |\n\n### One-time secret reveal\n\n:::caution[Plaintext keys appear exactly once]\n`ggui_ops_issue_connector_key` returns the plaintext `ggui_user_*` secret on its result — this is the **only call** that ever surfaces it. The adapter persists `sha256(plaintext)` hex plus the first ~8 plaintext characters (`apiKeyPrefix`); the plaintext is not stored anywhere. Subsequent `ggui_ops_list_connector_keys` responses carry the prefix and the metadata but never the full secret.\n\nThe MCP caller (Claude Desktop conversation, console) is responsible for surfacing the plaintext to the user immediately. There is no recovery if it's lost — the user must revoke and reissue.\n:::\n\n---\n\n## Tools by domain\n\nFour domains, 16 handlers total. Each domain is optional: apps hangs off `CreateGguiServerOptions.opsApps`; ops-blueprint hangs off the `opsBlueprint` dep bundle on `defaultHandlers`; provider-keys and credits are bound by the hosted cloud pod. Leaving a domain unwired removes its tools from `tools/list` at registration time.\n\n## Apps (`ops-apps`, 6 handlers)\n\nOperator actions on `GguiApp` rows — the rows the universal MCP route resolves per-request to scope sessions. Each row carries `appId` (server-minted base62), `displayName`, optional `systemPrompt` override, optional `rateLimitPerMinute`, `createdAt`, `updatedAt`. Bound on the cloud pod via DDB adapters over the `GguiApp` table.\n\n### `ggui_ops_list_apps`\n\nEnumerate every `GguiApp` row owned by the calling user. Returns metadata only — same data the console's Apps section renders. Use to discover ids before calling the mutating tools.\n\n**Inputs:** none.\n\n**Returns:** `{ apps: AppRecord[] }`\n\n```typescript\ninterface AppRecord {\n readonly appId: string;\n readonly displayName: string;\n readonly systemPrompt?: string;\n readonly createdAt: string;\n readonly updatedAt: string;\n}\n```\n\n**Tenancy:** scope is `ownerSub` from the bearer token. Cross-user listings are impossible by construction.\n\n### `ggui_ops_create_app`\n\nProvision a fresh `GguiApp` owned by the calling user. Wraps the cloud's `provisionGguiApp` mutation — opaque base62 `appId` is minted server-side; argument-supplied `appId` is NEVER honored (tenant-takeover vector).\n\n| Field | Type | Required | Description |\n| ------------- | ---------------------- | -------- | -------------------------------------------------------------------------------------------------------------- |\n| `displayName` | `string` (1–120 chars) | No | Human-friendly label. Defaults to `'My GGUI app'` when absent — matches the auto-create path in `useGguiUser`. |\n\n**Returns:** the full `AppRecord` shape as above.\n\n**Follow-up:** call `ggui_ops_set_default_app({appId})` to promote the new app to the user's default.\n\n### `ggui_ops_update_app`\n\nPartially update an app the caller owns — `displayName`, `systemPrompt`, and `rateLimitPerMinute` in one call. At least one field is required; an empty update is rejected before any store work.\n\n| Field | Type | Required | Description |\n| -------------------- | ------------------------ | -------- | ----------------------------------------------------------------------------------------------------------------------------------------- |\n| `appId` | `string` | Yes | Target `GguiApp.appId`. Discover via `ggui_ops_list_apps`. |\n| `displayName` | `string` (1–120 chars) | No | New display name. |\n| `systemPrompt` | `string` (≤10,000 chars) | No | Replacement text. Pass `\"\"` to clear the override — renders then fall back to the universal default. |\n| `rateLimitPerMinute` | `integer` (≥ 0) | No | Per-API-key renders/minute. Pass `0` to clear the limit (unlimited). The stored column keeps ONE \"unlimited\" representation, server-side. |\n\n**Returns:** the updated `AppRecord` (with `systemPrompt` / `rateLimitPerMinute` omitted when cleared).\n\n**Errors:**\n\n| Code | When |\n| --------------- | ---------------------------------------------------------------------------------------- |\n| `app_not_found` | The id doesn't exist OR exists under another tenant (uniform shape — no existence leak). |\n\n### `ggui_ops_delete_app`\n\nHard-delete an app owned by the calling user. Idempotent — a second delete of the same id resolves cleanly.\n\n| Field | Type | Required | Description |\n| ------- | -------- | -------- | ----------------------- |\n| `appId` | `string` | Yes | Target `GguiApp.appId`. |\n\n**Returns:** `{ deleted: true }`\n\n**Tenancy:** cross-tenant probes return the success shape without touching the foreign row. Uniform with \"row didn't exist.\"\n\n**Errors:**\n\n| Code | When |\n| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |\n| `default_app_delete_blocked` | The target is the caller's default app. The universal route resolves `defaultAppId` on every request, so it must point at a live app — call `ggui_ops_set_default_app` first, then delete. |\n\n:::note[Cleanup is asynchronous]\n`{deleted: true}` means the `GguiApp` row is gone and the dependent-row sweep is queued. Both delete paths — this tool and the console's **Apps → row menu → Delete** — converge on one cascade worker that revokes the app's keys and removes its blueprints, provider keys, installs, tool-identity catalog, durable registry rows, and render-identity records; through this tool the sweep is eventually consistent (typically seconds). Every delete emits a structured `app_delete_rows_orphaned` log event naming the row classes pending cleanup, with `cascadeQueued` saying whether the sweep was durably queued ([#463](https://github.com/loqu-co/ggui/issues/463)).\n:::\n\n### `ggui_ops_set_default_app`\n\nSet the calling user's `GguiUser.defaultAppId` — the universal MCP route resolves this on every request to scope the session. The handler first verifies the caller owns the target `appId` before writing `User.defaultAppId`.\n\n| Field | Type | Required | Description |\n| ------- | -------- | -------- | ----------------------------------------- |\n| `appId` | `string` | Yes | Target app — must be owned by the caller. |\n\n**Returns:** `{ defaultAppId: string }`\n\n**Errors:**\n\n| Code | When |\n| --------------- | ----------------------------------------------------------- |\n| `app_not_found` | Target `appId` doesn't exist OR is owned by another tenant. |\n\n### `ggui_ops_set_app_theme`\n\nReplace the theme on an app the caller owns. The payload is validated with the protocol's canonical `appThemeSchema` — the same validator every `GguiApp.theme` write surface runs — so no surface can persist a theme another surface would reject.\n\n| Field | Type | Required | Description |\n| ------- | ---------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |\n| `appId` | `string` | Yes | Target `GguiApp.appId`. |\n| `theme` | `AppTheme` | Yes | `{mode: 'light'\\|'dark', cssVariables, name?}`. Keys must match `--ggui-*`; values ≤256 chars with breakout characters rejected; ≤200 variables total. |\n\n**Returns:** `{ appId, theme, updatedAt }` — the persisted theme echoed back.\n\n**Errors:**\n\n| Code | When |\n| --------------- | ----------------------------------------------------------- |\n| `app_not_found` | Target `appId` doesn't exist OR is owned by another tenant. |\n\n---\n\n## Blueprints (`ops-blueprint`, 5 handlers)\n\nOperator blueprint authorship — generate, register, list, update, delete cached blueprints for the calling app. Unlike the apps domain, this family registers on the OSS server via the `opsBlueprint` dep bundle on `defaultHandlers` (registry + blueprint store + search; `generate` additionally requires the `resolveLlm` + `blueprints` deps the render generation path reads).\n\n### `ggui_ops_generate_blueprint`\n\nAuthor a blueprint via the bound generator (LLM generation + validation).\n\n| Field | Type | Required | Description |\n| ---------------------- | --------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |\n| `appId` | `string` | No | Target app. Defaults to the caller's bound app; a caller not bound to an app must pass it. |\n| `contract` | `object` | Yes | The `DataContract` to generate against. |\n| `generator` | `string` | No | Generator slug. Unknown slug fails with `generator_not_found`. |\n| `persona` | `string` | No | Variance axis — normalized lowercase + trimmed. |\n| `aesthetic` | `string` | No | Variance axis. |\n| `context` | `object` | No | Variance axis: a small structured signal. |\n| `seedPrompt` | `string` | No | Variance axis. |\n| `intent` | `string` | No | What to generate, in plain words: the prompt the generator composes from, at most 2,000 characters. Not part of the cache identity, so calls that differ only in `intent` share a variant key. When omitted, the generator falls back to `seedPrompt`. |\n| `setAsOperatorDefault` | `boolean` | No | Mark the result as the operator default for its contract (orders listings; does not decide what serves). |\n\n**Returns:** `{ blueprintId, codeHash?, source }` — `source` is the stamped provenance `{ kind: 'llm', generator, model }` from the engine's own metadata stamp.\n\n**Errors:** `generator_not_found`; `missing_credentials` (BYOK fix: `ggui_ops_set_provider_key`); generation failure.\n\n### `ggui_ops_register_blueprint`\n\nRegister pre-built component code verbatim — no LLM, no validator. Operator entry point for fixture seeding and export/reimport round-trips.\n\n| Field | Type | Required | Description |\n| --------------- | -------- | -------- | ----------------------------------------------------- |\n| `contract` | `object` | Yes | The `DataContract` the code implements. |\n| `componentCode` | `string` | Yes | The component code to register verbatim (min 1 char). |\n\nPlus the same optional `generator` / `persona` / `aesthetic` / `context` / `seedPrompt` / `setAsOperatorDefault` fields as `ggui_ops_generate_blueprint`, and four optional non-identity facts the semantic reuse pre-filter reads off the cache row (none is part of the cache identity; an omitted fact reads _not evaluated_, never a miss):\n\n| Field | Type | Required | Description |\n| ----------------- | ---------------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `intent` | `string` | No | What the interface is for, in the request's own words — the sentence the semantic reuse judge compares. Falls back to `seedPrompt`, then `persona`. |\n| `judgedCanvases` | `string[]` | No | A non-empty list of the canvas classes the interface was judged on (e.g. `xs-chat-card`, `md`). A request on a canvas outside the list is not offered it for semantic reuse. |\n| `aestheticPreset` | `{ id: string, version?: string }` | No | The aesthetic preset (and resolved version, when known) it was generated under. A request under another preset, or a pinned version that differs, is not offered it. |\n| `directionDigest` | `string` (sha256 hex) | No | Digest of the direction text it was generated under, normalised (trimmed, whitespace collapsed, lowercased). A request whose direction digests differently is not offered it. |\n| `directionScope` | `'app' \\| 'request'` | No | Which direction `directionDigest` hashes: `app` — the direction the app's profile carries; `request` — a direction given with the request itself. Only beside `directionDigest` (refused without it). |\n| `clonedFrom` | `string` | No | When these bytes are a copy of a row this app already holds, that row's `blueprintId`. The new row records it as provenance; nothing that serves reads it. Refused (`cloned_from_refused`, nothing persisted) when empty, the new row's own id, not held, or another app's row, with the same answer for a missing row as for another app's. |\n\n**Returns:** `{ blueprintId, codeHash, source }` — `source` is always `{ kind: 'user' }`; hand-supplied bytes carry no engine claim, so none is recorded.\n\n### `ggui_ops_list_blueprints`\n\n| Field | Type | Required | Description |\n| ---------------- | ---------- | -------- | ----------------------------------------------------- |\n| `contractHash` | `string` | No | Filter by canonical contract hash. |\n| `generator` | `string` | No | Filter by generator slug. |\n| `persona` | `string` | No | Dispatches semantic search. |\n| `intentKeywords` | `string[]` | No | Dispatches semantic search. Filters are AND-composed. |\n\n**Returns:** `{ blueprints: Blueprint[] }`\n\nA row minted by a generation carries `build`: the minting engine's version, design mode and template digests. Registered, installed and older rows carry none, and a reader treats that as an unknown build.\n\n### `ggui_ops_update_blueprint`\n\n| Field | Type | Required | Description |\n| ------------------- | -------------- | -------- | ---------------------------------------------------------------------------- |\n| `blueprintId` | `string` | Yes | Target blueprint. |\n| `isOperatorDefault` | `literal true` | No | Mark as the operator default (orders listings; does not decide what serves). |\n| `variance` | `object` | No | Partial-merge of variance axes; `{persona: \"\"}` clears the field. |\n\n**Returns:** `{ blueprintId, updatedAt }`\n\n### `ggui_ops_delete_blueprint`\n\n| Field | Type | Required | Description |\n| ------------- | -------- | -------- | ----------------- |\n| `blueprintId` | `string` | Yes | Target blueprint. |\n\n**Returns:** `{ deleted: true }` — idempotent.\n\n---\n\n## Provider keys (`provider-keys`, 3 handlers) — BYOK\n\nOperator actions on the caller's BYOK LLM provider keys. Provider enum: `'anthropic' | 'openai' | 'google' | 'openrouter'`. The handler factories ship in `@ggui-ai/mcp-server-handlers`; they are bound today by the hosted cloud pod, which validates keys against the provider and encrypts at rest.\n\n### `ggui_ops_set_provider_key`\n\n| Field | Type | Required | Description |\n| -------------- | -------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |\n| `provider` | `enum` | Yes | One of `anthropic` / `openai` / `google` / `openrouter`. |\n| `plaintextKey` | `string` | Yes | The provider API key (min 1 char). Re-set replaces (rotation). |\n| `label` | `string` | No | Human label. |\n| `appId` | `string` | No | Scope the key to ONE app the caller owns instead of the whole account. App key beats account key for that app's renders. Requires app-scoped key storage; deployments without it reject with `app_scoped_keys_unavailable`. Foreign/missing apps answer `app_not_found`. |\n\n**Returns:** `{ provider, label?, lastFour, createdAt?, lastUsedAt? }` — never echoes the key.\n\n### `ggui_ops_list_provider_keys`\n\n**Inputs:** none.\n\n**Returns:** `{ keys: [{ provider, label?, lastFour, createdAt?, lastUsedAt? }] }`\n\n### `ggui_ops_remove_provider_key`\n\n| Field | Type | Required | Description |\n| ---------- | -------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `provider` | `enum` | Yes | Provider to remove. |\n| `appId` | `string` | No | Remove the key scoped to one app the caller owns instead of the account-level key. Same availability + tenancy rules as on `ggui_ops_set_provider_key`. |\n\n**Returns:** `{ deleted, provider }`\n\n---\n\n## Credits (`credits`, 2 handlers)\n\nRead-only views over the caller's prepaid credit wallet. Bound by the hosted cloud pod; self-hosted deployments have no credit plane.\n\n### `ggui_ops_get_credit_balance`\n\n**Inputs:** none.\n\n**Returns:** `{ balanceCents, lifetimeGrantedCents, lifetimeSpentCents, updatedAt }`\n\n### `ggui_ops_list_credit_transactions`\n\n| Field | Type | Required | Description |\n| -------- | -------- | -------- | ------------------ |\n| `limit` | `number` | No | 1–100, default 20. |\n| `cursor` | `string` | No | Pagination cursor. |\n\n**Returns:** `{ transactions: [{ transactionId, kind, deltaCents, balanceAfterCents, reason, createdAt, relatedSessionId? }], nextCursor? }` — `kind` is an open vocabulary: the known kinds are `free_credit`, `render_charge`, `topup` and `refund`, and a deployment may add others. Accept a kind you do not know, keep it as named, and never read it as a render charge.\n\n---\n\n## Hosted-only ops\n\nTwenty-four more `ops`-audience tools live directly in `cloud/ggui-protocol-pod/src/tools/` — the cloud pod's own tool registry, not the open `@ggui-ai/mcp-server-handlers` package. They answer only on `https://mcp.ggui.ai/control`; a self-hosted `ggui serve` never registers them, because there is no seam to wire them through — they read and write cloud-pod-native tables directly. Thirteen back the chat-native experience (a Claude Desktop or claude.ai conversation acting as the user's own agent) rather than a specific console UI action, so they're absent from the [Console parity](#console-parity) table below. The other eleven — orgs, connector keys and coupons — mirror console actions and are listed there; they shipped in the open handler package before v0.25.0.\n\n### App meta-tools\n\nUniversal connector key only (a per-app key is scoped to one app and structurally can't enumerate or switch siblings).\n\n#### `ggui_ops_list_my_apps`\n\nEnumerate the caller's apps, most-recently-touched first.\n\n**Inputs:** `limit` (`integer`, 1–500, optional, default 100).\n\n**Returns:** `{ apps: [{ appId, displayName, isDefault, createdAt, updatedAt }] }` — `isDefault` marks the app the universal `mcp.ggui.ai` endpoint currently resolves to.\n\n#### `ggui_ops_open_app`\n\nSwitch the caller's default app. Writes `User.defaultAppId`; takes effect on the **next** connection — the calling Claude session keeps its already-bound `appId` for the life of the connection.\n\n| Field | Type | Required | Description |\n| ------- | -------- | -------- | ----------------------------------------------------------------------------------------------- |\n| `appId` | `string` | Yes | 8-char base62 target app id. Must be owned by the caller. Discover via `ggui_ops_list_my_apps`. |\n\n**Returns:** `{ appId, message }` — `message` reiterates the reconnect-to-switch caveat.\n\n### Personal blueprint library\n\nThe caller's own saved-blueprint library (Claude composes something useful in a conversation, saves it, renders it again later) — a different `GguiUserBlueprint` world from the `ops-blueprint` family's app-scoped variant curation above, scoped per-app via `ctx.appId` rather than per-owner.\n\n#### `ggui_ops_list_my_blueprints`\n\n| Field | Type | Required | Description |\n| ------- | --------- | -------- | ------------------- |\n| `limit` | `integer` | No | 1–500, default 100. |\n\n**Returns:** `{ blueprints: [{ name, description?, tags?, usageCount, createdAt, updatedAt, lastUsedAt?, systemSourceId?, systemVersion? }] }` — definition bodies are omitted to keep the list lean; fetch one with `ggui_ops_get_my_blueprint_source`.\n\n#### `ggui_ops_get_my_blueprint_source`\n\n| Field | Type | Required | Description |\n| ------ | -------- | -------- | ----------------------------------------------------------- |\n| `name` | `string` | Yes | Blueprint slug. Discover via `ggui_ops_list_my_blueprints`. |\n\n**Returns:** `{ name, definition: { source, contract?, fixtureProps? }, description?, tags?, updatedAt }`.\n\n**Errors:** `blueprint_not_found` (missing or foreign name — uniform, no existence leak); `blueprint_definition_invalid` (a stored row lost its source text).\n\n#### `ggui_ops_save_library_blueprint`\n\nUpsert a blueprint into the caller's library, keyed on `(appId, name)` — same name replaces the existing row. Re-runs the canonical D16 validator (compile → self-check → runtime probe) server-side as defense-in-depth. Single-call by owner ruling; see the [confirmation-gate section](#confirmation-gate-on-state-changing-tools) above for why.\n\n| Field | Type | Required | Description |\n| ------------- | ---------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------- |\n| `name` | `string` | Yes | Slug 2–64 chars, kebab-case `[a-z0-9-]`, no underscores, no single-char names. |\n| `blueprint` | `object` | Yes | `{source, contract?, fixtureProps?}` — pass the object as-is, e.g. straight from `ggui_ops_get_render_source`'s `blueprint` field. |\n| `description` | `string` | No | Surfaces in the console's miniapp library. |\n| `tags` | `string[]` | No | Organization tags. |\n\n**Returns:** `{ name, createdAt, updatedAt }`.\n\n**Errors:** the D16 validator's tiered failure envelope (same shape as `ggui_protocol_validate_blueprint`) when validation fails.\n\n#### `ggui_ops_update_my_blueprint`\n\nRename a library blueprint and/or replace its `description` / `tags` in one call — at least one of `newName`, `description`, `tags` is required. Rename applies first and refuses to overwrite an existing sibling name.\n\n| Field | Type | Required | Description |\n| ------------- | ---------- | -------- | ---------------------------------------------------------------------------------------- |\n| `name` | `string` | Yes | Current slug. Discover via `ggui_ops_list_my_blueprints`. |\n| `newName` | `string` | No | New slug, same rule as `name`. Same-name is a no-op. |\n| `description` | `string` | No | Replacement (≤4000 chars); empty string clears it. |\n| `tags` | `string[]` | No | Replacement list, trimmed/lowercased/deduped, ≤32 tags of ≤64 chars; empty array clears. |\n\n**Returns:** `{ name, updatedAt }` — `name` is the post-rename value.\n\n**Errors:** `blueprint_not_found`; `blueprint_name_taken` (rename collision, names the taken slug).\n\n#### `ggui_ops_delete_my_blueprint`\n\nIdempotent delete by name.\n\n| Field | Type | Required | Description |\n| ------ | -------- | -------- | ----------------------------------------------------------- |\n| `name` | `string` | Yes | Blueprint slug. Discover via `ggui_ops_list_my_blueprints`. |\n\n**Returns:** `{ name, deleted }` — `deleted: false` means no such blueprint existed; still a success.\n\n### Render introspection\n\nUniversal connector key only — same posture as the app meta-tools, since both read across every app the caller owns.\n\n#### `ggui_ops_list_recent_renders`\n\n| Field | Type | Required | Description |\n| ------------- | --------- | -------- | ---------------------------------------------------------------------------------------------- |\n| `limit` | `integer` | No | 1–100, default 20. |\n| `appId` | `string` | No | Narrow to one app. Omit to list across every app the caller owns. |\n| `erroredOnly` | `boolean` | No | Return only renders whose generation failed. Covers at most the 500 most-recent rows per call. |\n\n**Returns:** `{ renders: [{ sessionId, appId, createdAt, status, errorCode? }] }` — `status` is `active` or `expired`; an empty list is a valid \"nothing yet\" answer, not an error.\n\n#### `ggui_ops_get_render_source`\n\nCaller-gated source read for a render session — the link between a render and `ggui_ops_save_library_blueprint`. Only component-variant renders have source; MCP-Apps and system-card renders (and a render that hasn't finished its first commit) answer a typed no-source error instead of an empty string.\n\n| Field | Type | Required | Description |\n| ----------- | -------- | -------- | -------------------------------------------------------------- |\n| `sessionId` | `string` | Yes | From `ggui_ops_list_recent_renders` or a `ggui_render` result. |\n\n**Returns:** `{ sessionId, blueprint: { source, contract?, fixtureProps? } }` — feed `blueprint` straight into `ggui_ops_save_library_blueprint`'s `blueprint` argument with no reshaping.\n\n**Errors:** `render_not_found` (missing or foreign session — uniform, no existence leak).\n\n### BYOK setup card\n\n#### `ggui_ops_setup_byok`\n\nEntry point for the BYOK provider-key MCP App card — the chat-native counterpart to `ggui_ops_list_provider_keys` above, shaped for inline card rendering rather than flat consumption. Declares `_meta.ui.resourceUri` so MCP-Apps-aware hosts pre-fetch the bundle and render the card on first call.\n\n**Inputs:** none.\n\n**Returns:** `{ kind: 'provider-key', configured: [{ provider, prefix }] }` — `prefix` is a display string like `sk-ant…abcd` (canonical provider prefix + the stored last-four), never the plaintext key.\n\n### Registry scope administration\n\nPlatform-operator only — gated by `requireScopeOpsOperator` against the `REGISTRY_OPS_OPERATOR_SUBS` allowlist (checked against `ctx.userId`), on top of the normal auth + confirm gates. Scope **owners** publish through the ordinary publish flow and never call these; they exist for the registry operator to reassign or verify scope ownership (e.g. reclaiming a squatted `@scope` for its proven brand owner) and to record which signer identities may publish under a scope. All three mutate global registry state, are deliberately excluded from the single-call set, and emit a structured audit line (`scope_transfer` / `scope_verification_set` / `scope_san_allowlist_set` / `scope_ops_denied`) on every call.\n\n#### `ggui_ops_scope_transfer`\n\nReassign an existing scope's ownership row, or seed one for a reserved scope that was never first-publish-claimable. The written row always lands `verification: 'unverified'` — a transfer moves ownership, it does not assert proof.\n\n| Field | Type | Required | Description |\n| ----------------- | -------- | -------- | --------------------------------------------------------- |\n| `scope` | `string` | Yes | Target scope, leading `@` included. |\n| `newOwnerSubject` | `string` | Yes | Auth subject that will own publishes under the scope. |\n| `reason` | `string` | Yes | Why ownership moves — recorded verbatim in the audit log. |\n\n**Returns:** `{ scope, ownerSubject, claimedAt, verification, previousOwnerSubject? }`.\n\n#### `ggui_ops_scope_set_verification`\n\nRecord or withdraw the verified-domain proof on an existing ownership row. `verified` requires `verifiedDomain`; `unverified` forbids it (withdrawing clears both proof fields).\n\n| Field | Type | Required | Description |\n| ---------------- | ---------------------------- | ----------- | ------------------------------------------------------------------------------- |\n| `scope` | `string` | Yes | Must already have an ownership row — seed with `ggui_ops_scope_transfer` first. |\n| `verification` | `'unverified' \\| 'verified'` | Yes | New label. |\n| `verifiedDomain` | `string` | Conditional | Required with `verified`; forbidden with `unverified`. |\n\n**Returns:** `{ scope, ownerSubject, claimedAt, verification, verifiedDomain?, verifiedAt? }`.\n\n#### `ggui_ops_scope_set_san_allowlist`\n\nSet or clear the exact sigstore certificate identities (emails or CI workflow URIs) permitted to publish under a scope — pass exactly one of `sanAllowlist` (non-empty, to set) or `clear: true` (to remove); an empty array is refused rather than guessed at. Scopes without a list fall back to the deployment's default identity rule (verified-email match, where wired).\n\n| Field | Type | Required | Description |\n| -------------- | ---------- | -------- | --------------------------------------------------------------------------------------------------- |\n| `scope` | `string` | Yes | Must already have an ownership row — seed with `ggui_ops_scope_transfer` first. |\n| `sanAllowlist` | `string[]` | No | Replacement allowlist, exact literal strings only (no regex/glob). Mutually exclusive with `clear`. |\n| `clear` | `boolean` | No | Remove the allowlist. Mutually exclusive with `sanAllowlist`. |\n\n**Returns:** `{ scope, ownerSubject, claimedAt, verification, verifiedDomain?, verifiedAt?, sanAllowlist? }` — `sanAllowlist` absent after a clear.\n\n### Orgs (7 tools)\n\nOperator actions on `GguiOrg` + `GguiOrgMember` + `GguiOrgInvite` (+ the org credit-balance) rows. Orgs are the unit of multi-user collaboration; each row carries `orgId` (ULID), `name`, `ownerUserId`, plus per-membership role on the join rows. Bound on the cloud pod via DDB adapters over the same tables the console's org mutations write.\n\n#### `ggui_ops_list_orgs`\n\nEnumerate every org the calling user belongs to — owner + admin + member memberships in a single list, each row carrying the caller's role.\n\n**Inputs:** none.\n\n**Returns:** `{ orgs: OrgMembershipRecord[] }`\n\n```typescript\ninterface OrgMembershipRecord {\n readonly orgId: string;\n readonly name: string;\n readonly ownerUserId: string;\n readonly role: \"owner\" | \"admin\" | \"member\";\n readonly joinedAt: string;\n}\n```\n\nMirrors the AppSync `fetchMyOrgs` custom resolver. Use to discover `orgId` before calling the invite tools.\n\n#### `ggui_ops_create_org`\n\nProvision a fresh `GguiOrg` owned by the calling user. Wraps the cloud's `provisionGguiOrg` mutation — ULID `orgId` minted server-side; an owner membership row and a zero-balance credit row are inserted atomically via TransactWrite.\n\n| Field | Type | Required | Description |\n| ------ | ---------------------- | -------- | ------------------------------------------------------------------------------------ |\n| `name` | `string` (1–120 chars) | Yes | Human-friendly display name. Required (no default — orgs are intentional creations). |\n\n**Returns:**\n\n```typescript\ninterface CreateOrgOutput {\n readonly orgId: string;\n readonly name: string;\n readonly ownerUserId: string;\n readonly createdAt: string;\n readonly updatedAt: string;\n}\n```\n\n#### `ggui_ops_rename_org`\n\nRename an org the caller owns or administers. Authorization is owner-OR-admin — an admin curates the org's presentation just like the owner; member-role callers are rejected.\n\n| Field | Type | Required | Description |\n| ------- | ---------------------- | -------- | --------------------------------------------------------------------------------- |\n| `orgId` | `string` | Yes | Target org — caller must own or administer it. Discover via `ggui_ops_list_orgs`. |\n| `name` | `string` (1–120 chars) | Yes | New display name. Trimmed; cap matches org provisioning. |\n\n**Returns:** `{ orgId, name, updatedAt }`\n\n**Errors:**\n\n| Code | When |\n| ------------------- | -------------------------------------------------------------------------------- |\n| `org_not_found` | The id doesn't exist OR the caller isn't a member (uniform — no existence leak). |\n| `org_access_denied` | The caller is a member but not owner/admin. |\n\n#### `ggui_ops_remove_org_member`\n\nRemove a member from an org, or leave an org by removing yourself. Permission matrix (caller's role × target's role):\n\n| | target=owner | target=admin | target=member |\n| --------------- | ------------ | ------------ | ------------- |\n| `caller=owner` | no | yes | yes |\n| `caller=admin` | no | only-self | yes |\n| `caller=member` | no | no | only-self |\n\nThe org **owner can never be removed** — ownership transfer is a separate flow. Matrix violations surface the specific rule that was hit; only non-member callers get the uniform not-found.\n\n| Field | Type | Required | Description |\n| -------------- | -------- | -------- | --------------------------------------------------------- |\n| `orgId` | `string` | Yes | Target org — the caller must be a member. |\n| `memberUserId` | `string` | Yes | Member to remove. Pass your own user id to leave the org. |\n\n**Returns:** `{ orgId, memberUserId, alreadyAbsent }` — `alreadyAbsent: true` means no membership row existed (idempotent; a parallel removal is not an error).\n\n**Errors:**\n\n| Code | When |\n| --------------------------- | -------------------------------------------------------------------------------- |\n| `org_not_found` | The id doesn't exist OR the caller isn't a member (uniform — no existence leak). |\n| `org_member_removal_denied` | The role matrix denies the removal — the message names the specific rule. |\n\n#### `ggui_ops_get_org_balance`\n\nRead the shared prepaid credit balance of an org the caller belongs to. **Any membership role** — every member can see how much shared credit there is to spend. Single-call (no confirmation gate).\n\n| Field | Type | Required | Description |\n| ------- | -------- | -------- | ----------------------------------------- |\n| `orgId` | `string` | Yes | Target org — the caller must be a member. |\n\n**Returns:** `{ orgId, balanceCents, lifetimeGrantedCents, lifetimeSpentCents, updatedAt }` — an org with no spend history reads as zeros (the balance value is the contract, not the row's existence).\n\n**Errors:**\n\n| Code | When |\n| --------------- | -------------------------------------------------------------------------------- |\n| `org_not_found` | The id doesn't exist OR the caller isn't a member (uniform — no existence leak). |\n\n#### `ggui_ops_invite_to_org`\n\nIssue an `admin`- or `member`-role invite to a `GguiOrg` the caller can administer. The invite link in the recipient's email points at the console: `console.ggui.ai/invites/`.\n\n| Field | Type | Required | Description |\n| ------- | --------------------- | -------- | --------------------------------------------------------------------------------------------------------------------- |\n| `orgId` | `string` | Yes | Target org — caller must own or administer it. Discover via `ggui_ops_list_orgs`. |\n| `email` | `string` (RFC 5322) | Yes | Recipient email — the invite link is sent here. |\n| `role` | `'admin' \\| 'member'` | Yes | Role the recipient holds once they accept. Owner can't be granted via invite — ownership transfer is a separate flow. |\n\n**Returns:**\n\n```typescript\ninterface InviteToOrgOutput {\n readonly inviteId: string;\n readonly orgId: string;\n readonly email: string;\n readonly role: \"admin\" | \"member\";\n readonly inviterUserId: string;\n readonly status: \"pending\" | \"accepted\" | \"revoked\" | \"expired\";\n readonly expiresAt: string;\n readonly createdAt: string;\n readonly reused: boolean;\n}\n```\n\n**Anti-double-issue:** an existing pending invite for the same `(orgId, email)` is reused — no new row, no second email. `reused: true` flags the dedup.\n\n**Errors:**\n\n| Code | When |\n| -------------------------- | -------------------------------------------- |\n| `org_invite_access_denied` | Caller is not owner/admin of the target org. |\n\n#### `ggui_ops_revoke_invite`\n\nInvalidate a pending org invite — the bearer-secret link in the recipient's email stops working immediately.\n\n| Field | Type | Required | Description |\n| ---------- | -------- | -------- | ---------------------------------------------------------------- |\n| `inviteId` | `string` | Yes | Target invite — must belong to an org the caller can administer. |\n\n**Returns:**\n\n```typescript\ninterface RevokeInviteOutput {\n readonly inviteId: string;\n readonly status: \"pending\" | \"accepted\" | \"revoked\" | \"expired\";\n readonly alreadyRevoked: boolean;\n}\n```\n\n**Concurrency:** the adapter flips `status` from `pending` → `revoked` via a CAS `ConditionExpression`. A racing accept surfaces a clear conflict instead of silently overwriting. Already-revoked invites return `alreadyRevoked: true`; already-accepted invites reject.\n\n**Errors:**\n\n| Code | When |\n| -------------------------- | ------------------------------------------------------ |\n| `org_invite_access_denied` | Caller is not owner/admin of the invite's org. |\n| `org_invite_not_found` | The id doesn't exist OR isn't reachable by the caller. |\n\n### Connector keys (3 tools)\n\nOperator actions on `GguiUserApiKey` rows — the user-facing `ggui_user_*` API key strings that Claude Desktop (and other Connectors) present to call the MCP routes on the user's behalf. Bound on the cloud pod via the `issueGguiUserApiKey` AppSync mutation + the `apiKeysByUserId` GSI + raw DDB `UpdateItem` for revoke.\n\n#### `ggui_ops_list_connector_keys`\n\nRead the calling user's `ggui_user_*` connector keys. **Metadata only — NEVER plaintext.**\n\n**Inputs:** none.\n\n**Returns:** `{ keys: ConnectorKeySummary[] }`\n\n```typescript\ninterface ConnectorKeySummary {\n readonly id: string; // stable id for revoke\n readonly apiKeyPrefix: string; // first ~8 chars of the secret (human re-identification)\n readonly name?: string; // user-supplied label\n readonly appId?: string; // optional FK — when set the key locks to that app\n readonly status: \"active\" | \"revoked\";\n readonly createdAt: string;\n readonly lastUsedAt?: string; // from the last successful auth lookup\n readonly expiresAt?: string; // past timestamp ⇒ adapter rejects auth\n}\n```\n\nThe hash itself is never returned on any tool.\n\n#### `ggui_ops_issue_connector_key`\n\nMint a fresh `ggui_user_*` connector key.\n\n| Field | Type | Required | Description |\n| ----------- | ---------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `name` | `string` (1–120 chars) | No | Optional label, e.g. `'MacBook Claude Desktop'`. Surfaces on `ggui_ops_list_connector_keys`. |\n| `appId` | `string` | No | Lock the key to one app. When set, sessions opened with this key scope to the named app and meta-tools (`ggui_ops_open_app`, `ggui_ops_list_apps`) are NOT exposed. Absent ⇒ universal key (scopes to `User.defaultAppId` per request). |\n| `expiresAt` | `string` (ISO 8601) | No | Optional expiry. Past timestamps reject auth from the start. |\n\n**Returns:**\n\n```typescript\ninterface IssueConnectorKeyOutput {\n // metadata — same shape as a list row\n readonly id: string;\n readonly apiKeyPrefix: string;\n readonly name?: string;\n readonly appId?: string;\n readonly status: \"active\" | \"revoked\";\n readonly createdAt: string;\n readonly lastUsedAt?: string;\n readonly expiresAt?: string;\n // ONE-TIME REVEAL — never returned again\n readonly plaintextKey: string;\n}\n```\n\n:::caution[One-time reveal]\n`plaintextKey` is the `ggui_user_` secret. It appears on this response and never again — the adapter persists `sha256(plaintextKey)` hex plus `apiKeyPrefix`, and the plaintext is not stored. The caller MUST surface it to the user immediately.\n:::\n\n#### `ggui_ops_revoke_connector_key`\n\nSoft-revoke a `GguiUserApiKey` row. The adapter sets `status='revoked'`; the auth path rejects revoked keys regardless of hash match. Rows are kept for audit (age-based sweep handles cleanup).\n\n| Field | Type | Required | Description |\n| ------- | -------- | -------- | ------------------------------------------------------------------------------------------ |\n| `keyId` | `string` | Yes | Stable id of the row (NOT the secret string). Discover via `ggui_ops_list_connector_keys`. |\n\n**Returns:**\n\n```typescript\ninterface RevokeConnectorKeyOutput {\n readonly id: string;\n readonly status: \"active\" | \"revoked\";\n readonly alreadyRevoked: boolean;\n}\n```\n\n**Errors:**\n\n| Code | When |\n| ----------------------------- | ------------------------------------ |\n| `connector_key_access_denied` | The key belongs to another user. |\n| `connector_key_not_found` | No such key reachable by the caller. |\n\nIdempotent — re-revoking returns `alreadyRevoked: true`.\n\n### Coupons (1 tool)\n\nOperator action on `GguiCoupon` rows — bearer-secret promo codes that credit user or org wallets. Bound on the cloud pod via the `redeemCoupon` AppSync mutation.\n\n#### `ggui_ops_redeem_coupon`\n\nRedeem a `cpn_*` coupon code, crediting the caller's wallet (default) or a target org's wallet. The adapter runs an atomic three-leg `TransactWrite`:\n\n1. Flip `GguiCoupon.status` from `issued` → `activated`.\n2. Credit the wallet (user or org).\n3. Insert a ledger row.\n\nFailure of any leg rolls all back — no half-credit, no double-spend.\n\n| Field | Type | Required | Description |\n| ------------- | -------- | -------- | --------------------------------------------------------------------------------------------------------------------- |\n| `couponCode` | `string` | Yes | The bearer-secret code in format `cpn_<8 chars>`. One-time redemption. |\n| `targetOrgId` | `string` | No | When set, credits the named org's wallet instead of the caller's personal wallet. Caller MUST be a member of the org. |\n\n**Returns:**\n\n```typescript\ninterface RedeemCouponOutput {\n readonly couponCode: string;\n readonly creditCents: number;\n readonly redeemedByPrincipalType: \"user\" | \"org\";\n readonly redeemedByPrincipalId: string;\n readonly activatedAt: string;\n}\n```\n\n**Errors:**\n\n| Code | When |\n| ------------------------- | ---------------------------------------------------------------------- |\n| `coupon_not_found` | The code doesn't exist. |\n| `coupon_already_redeemed` | The code was previously activated (one-time semantics). |\n| `coupon_expired` | The code is past its expiry. |\n| `coupon_access_denied` | `targetOrgId` was provided but the caller is not a member of that org. |\n\n---\n\n## OSS vs hosted\n\nThe apps domain is wired through an optional field on `CreateGguiServerOptions` (ops-blueprint hangs off the `opsBlueprint` dep bundle on `defaultHandlers`; provider-keys + credits are cloud-pod-bound):\n\n```typescript\ninterface CreateGguiServerOptions {\n readonly opsApps?: {\n readonly apps: AppsSource;\n readonly userDefaultApp: UserDefaultAppSource;\n };\n}\n```\n\n- **Hosted (`mcp.ggui.ai`):** the cloud pod binds the apps domain — AppSync-backed adapters wrap the corresponding mutations. Provider-keys and credits (above) are also bound, and the pod additionally registers its own 24 hosted-only tools, orgs, connector keys and coupons among them (see [Hosted-only ops](#hosted-only-ops)) — the full ops surface is already live on `/control`.\n- **OSS (`ggui serve`):** every field is `undefined` by default. The route still mounts but `tools/list` rejects with `Method not found` — no tools capability is advertised when zero handlers are registered. Operator tools only make sense alongside a data model to operate on; the ops-blueprint family is the one most self-hosters wire (via the `opsBlueprint` dep bundle).\n- **Wiring apps:** a self-hosted deployment with its own `AppsSource` and `UserDefaultAppSource` binds `opsApps` and gets the six `ggui_ops_*_app` tools.\n- **Before v0.25.0:** orgs, connector keys and coupons were open handler families wired through `opsOrgs`, `opsConnectorKeys` and `opsCoupon`. Organisations, wallets and user API keys are features of the hosted service, so those families now ship only there; a deployment that bound them can stay on v0.24.0, or copy the handlers into its own code and register them through the `handlers` option.\n\nThe seam interfaces (`AppsSource`, `UserDefaultAppSource`) are exported from `@ggui-ai/mcp-server-handlers` — implementing them against your own backend is the integration path for downstream forks.\n\n## Console parity\n\nThe [console UI](/hosted/console/) mirrors these tools 1:1 — every tool corresponds to one UI action:\n\n| Tool | Console surface |\n| ------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `ggui_ops_list_apps` | Apps section — main list. |\n| `ggui_ops_create_app` | Apps section — \"New app\" button. |\n| `ggui_ops_update_app` | Apps section — inline rename + System Prompt editor + rate-limit setting. |\n| `ggui_ops_set_app_theme` | Apps section → Theme editor. |\n| `ggui_ops_delete_app` | Apps section — row menu → Delete. Both paths converge on the app-delete cascade worker (see the tool’s section above); the console removes the app row synchronously, the tool’s dependent-row sweep is eventually consistent (seconds). |\n| `ggui_ops_set_default_app` | Apps section — \"Set as default\" toggle. |\n| `ggui_ops_list_orgs` | Orgs section — main list. |\n| `ggui_ops_create_org` | Orgs section — \"New org\" button. |\n| `ggui_ops_rename_org` | Orgs section — org header → Rename. |\n| `ggui_ops_remove_org_member` | Orgs section → Members → row menu → Remove / \"Leave org\". |\n| `ggui_ops_get_org_balance` | Orgs section → Wallet balance readout. |\n| `ggui_ops_invite_to_org` | Orgs section → Members → Invite. |\n| `ggui_ops_revoke_invite` | Orgs section → Members → pending invite row → Revoke. |\n| `ggui_ops_list_connector_keys` | Account → Connector Keys list. |\n| `ggui_ops_issue_connector_key` | Account → Connector Keys → \"Issue new key\". |\n| `ggui_ops_revoke_connector_key` | Account → Connector Keys → row menu → Revoke. |\n| `ggui_ops_redeem_coupon` | Billing → Redeem coupon. |\n| `ggui_ops_set_provider_key` / `ggui_ops_remove_provider_key` with `appId` | App settings → Provider Keys (per-app override). |\n\nThe MCP surface and the UI surface are siblings over the same seam — they write the same rows — the console's \"New app\" and `ggui_ops_create_app` both go through `AppsSource.create`, for example. There's no privileged path on either side.\n\n---\n\n## Example: curl\n\nThis walkthrough targets a self-hosted server with the ops seams wired (started with `--dev-allow-all` for the `Bearer dev` shortcut). On hosted GGUI, the same calls go to `https://mcp.ggui.ai/control` with an OAuth bearer.\n\nNote the `confirm` argument on the state-changing steps — without it, each returns a preview instead of acting.\n\n```bash\n# 1. Initialize\ncurl -X POST http://127.0.0.1:6781/control \\\n -H \"Authorization: Bearer dev\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"initialize\",\"params\":{\"protocolVersion\":\"2025-11-25\",\"clientInfo\":{\"name\":\"curl\",\"version\":\"1.0\"},\"capabilities\":{}}}'\n\n# 2. Enumerate the caller's apps\ncurl -X POST http://127.0.0.1:6781/control \\\n -H \"Authorization: Bearer dev\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"jsonrpc\":\"2.0\",\"id\":2,\"method\":\"tools/call\",\"params\":{\"name\":\"ggui_ops_list_apps\",\"arguments\":{}}}'\n\n# 3. Create a fresh app\ncurl -X POST http://127.0.0.1:6781/control \\\n -H \"Authorization: Bearer dev\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"jsonrpc\":\"2.0\",\"id\":3,\"method\":\"tools/call\",\"params\":{\"name\":\"ggui_ops_create_app\",\"arguments\":{\"displayName\":\"Inbox Triage\",\"confirm\":true}}}'\n\n# 4. Promote the new app to default (use the appId from step 3's response)\ncurl -X POST http://127.0.0.1:6781/control \\\n -H \"Authorization: Bearer dev\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"jsonrpc\":\"2.0\",\"id\":4,\"method\":\"tools/call\",\"params\":{\"name\":\"ggui_ops_set_default_app\",\"arguments\":{\"appId\":\"\",\"confirm\":true}}}'\n```\n\nOn hosted GGUI, a fifth call — `ggui_ops_issue_connector_key` with `{\"name\":\"MacBook Claude Desktop\",\"appId\":\"\",\"confirm\":true}` — mints a connector key locked to the new app; its response carries `plaintextKey`, to surface to the user immediately (see [Connector keys](#connector-keys-3-tools)).\n\nThe same calls can be made through the [`@modelcontextprotocol/sdk`](https://github.com/modelcontextprotocol/typescript-sdk) client by pointing the transport at `/control` instead of `/mcp` — the tool registration shapes are standard.\n\n---\n\n## See Also\n\n- [Console](/hosted/console/) — the human-facing surface for the same actions.\n- [Audience Routes](/architecture/audience-routes/) — the `agent` / `runtime` / `protocol` / `ops` tag model and how it projects onto the two surfaces.\n- [MCP Protocol Reference](/api/mcp-protocol/) — the sibling agent-loop surface on `/mcp`."},{"path":"/api/mcp-apps.md","title":"MCP Apps support","description":"How GGUI implements the io.modelcontextprotocol/ui capability so hosts like Claude Desktop, claude.ai, Goose, and VS Code Copilot render generative UIs inline.","body":"---\ntitle: MCP Apps support\ndescription: How GGUI implements the io.modelcontextprotocol/ui capability so hosts like Claude Desktop, claude.ai, Goose, and VS Code Copilot render generative UIs inline.\n---\n\n[MCP Apps](https://modelcontextprotocol.io/extensions/apps/overview) is the protocol extension that lets MCP servers ship interactive UI alongside structured data, and lets MCP hosts render those UIs inline in the chat surface. The OSS [`@ggui-ai/mcp-server`](/quickstart/self-hosted/) implements the wire format on both sides — as does the hosted GGUI server (`mcp.ggui.ai`) — so generative UIs render directly in chat instead of forcing a \"click this link\" detour to a browser tab.\n\nThis page documents the protocol pieces GGUI implements. For end-user setup, see [Connect Claude Desktop](/clients/claude-desktop/). For the underlying transport, see [WebSocket protocol](/api/websocket-protocol/).\n\n## What MCP Apps adds\n\nWithout MCP Apps, an MCP tool that produces UI has to choose between:\n\n1. Returning structured data and hoping the host formats it (no interactivity), or\n2. Returning a URL the user clicks out to (interactive, but chat and UI live in separate windows).\n\nMCP Apps adds a third option: declare a UI resource alongside the tool result, the host sandboxes it in an iframe inside the chat, and a WebSocket channel carries data both ways — host to UI for live updates, UI to server for actions.\n\n## What GGUI ships\n\nWhen the server boots with `mcpApps` enabled, three things happen:\n\n1. **`io.modelcontextprotocol/ui` is advertised** in the server's `initialize` capabilities (under `experimental`). MCP-Apps-aware hosts read this and switch on inline rendering.\n2. **`ui://ggui/render` is served** as a resource via `resources/read` — a minimal HTML shell that loads [`@ggui-ai/iframe-runtime`](https://www.npmjs.com/package/@ggui-ai/iframe-runtime) and opens the WebSocket channel.\n3. **Every `ggui_render` tool result carries `_meta.ui.resourceUri`** — the `ui://` locator naming the view. Whether the result ALSO carries the `_meta[\"ai.ggui/render\"]` bootstrap slice depends on the deployment posture; see [Tool result shape](#tool-result-shape) below. Hosted GGUI withholds it, self-hosted `ggui serve` inlines it.\n\n### The bootstrap slice\n\nWherever it is delivered — on the tool result, or inlined by a per-render shell — the `_meta[\"ai.ggui/render\"]` slice is the same shape: `sessionId`, `appId`, `runtimeUrl`, `wsUrl`, a short-TTL `wsToken`, and `expiresAt` (ISO 8601 string) as top-level fields, alongside capability + render-state fields, plus theme fields (`themeId`, `themeMode`, `theme` — the app's theme, its `--ggui-*` projection for both modes, which the iframe merges into the scoped token block the components read), a `pollingUrl` fallback for WS-blocked environments, `lastSequence` to seed replay cursors, and `epoch`. The iframe consumes the slice and opens the WebSocket with the `wsToken`, which it presents again on a reconnect.\n\n`epoch` is the history epoch this mount belongs to, and it is load-bearing rather than decorative. `ggui_render` mints epoch 0; each `ggui_update` result carries its new epoch; a pinned `#N` read carries N; absent reads as 0. The iframe records it at boot as its OWN epoch, and when a later [`props_update`](/api/websocket-protocol/#props_update) frame arrives carrying a HIGHER epoch, this mount has been superseded and freezes instead of applying the new props. A custom runtime that ignores `epoch` will happily repaint a stale history card with state that belongs to a newer one — the exact bug the freeze latch exists to prevent.\n\n## Capability declaration\n\nOn `initialize`, GGUI returns:\n\n```json\n{\n \"capabilities\": {\n \"tools\": { \"listChanged\": true },\n \"resources\": { \"subscribe\": false, \"listChanged\": false },\n \"experimental\": {\n \"io.modelcontextprotocol/ui\": {}\n }\n }\n}\n```\n\nHosts that recognize `io.modelcontextprotocol/ui` flip into inline-render mode. Hosts that don't simply ignore the capability and skip inline rendering — the render is still delivered as a resource, addressed by `_meta.ui.resourceUri` (see [Render locator grammar](#render-locator-grammar)), but without MCP-Apps support there is nothing to mount it. There is no agent-returned URL to open instead.\n\n## Tool result shape\n\nEvery UI-producing tool (today: `ggui_render`) stamps a locator on the result so the host knows where to load the UI from. There are **two postures**, and a host builder must handle the one their server runs.\n\n### Read-plane-only — what `https://mcp.ggui.ai` returns\n\nHosted GGUI runs read-plane-only. The result publishes the durable identity and nothing else: no `ai.ggui/render` slice, no `wsToken`. No bootstrap token is minted for a slice nobody receives.\n\n```json\n{\n \"content\": [{ \"type\": \"text\", \"text\": \"Created render render_abc123\" }],\n \"structuredContent\": {\n \"sessionId\": \"render_abc123\",\n \"resourceUri\": \"ui://ggui/render/render_abc123/bp_9f2c\"\n // … plus action / contractHash / blueprintId / variantKey / cache\n },\n \"_meta\": {\n \"ui\": { \"resourceUri\": \"ui://ggui/render/render_abc123/bp_9f2c\" },\n \"ui/resourceUri\": \"ui://ggui/render/render_abc123/bp_9f2c\"\n }\n}\n```\n\nThe host MUST resolve the view by an authenticated `resources/read` on that locator. What comes back is a **per-render self-contained shell** — an HTML document that inlines the bootstrap slice synchronously on `globalThis.__GGUI_META__`, so the runtime reads it directly and never waits for a host relay. `ui/resourceUri` is the flat legacy alias of the same value, carried for hosts that read that slot.\n\nReading the locator is the shortest path, not the only one. A host that mounts the **declaration-level** static shell instead, the `_meta.ui.resourceUri` announced on `tools/list`, still paints, provided it forwards this result via `ui/notifications/tool-result` and answers `resources/read` from the view. The shell finds only the locator on the result, asks the host to read it, and mounts from the envelope that comes back: the [read-plane door](/protocol/bootstrap-handshake/#the-read-plane-door). That costs one extra host-proxied round trip. A host that cannot proxy the read ends on a failure card after a bounded wait: it reports `MISSING_META_GGUI_BOOTSTRAP`, and its message names the `READ_DOOR_FAILED:` cause (see [the read-plane door](/protocol/bootstrap-handshake/#the-read-plane-door)).\n\n### Inlined bootstrap — the self-hosted `ggui serve` default\n\nWithout the withhold posture, the result carries the bootstrap slice inline and a host may mount directly, with no further round-trip:\n\n```json\n{\n \"content\": [{ \"type\": \"text\", \"text\": \"Created render render_abc123\" }],\n \"_meta\": {\n \"ui\": {\n \"resourceUri\": \"ui://ggui/render/render_abc123\"\n },\n \"ai.ggui/render\": {\n \"sessionId\": \"render_abc123\",\n \"appId\": \"app_abc\",\n \"runtimeUrl\": \"https://your-server.example.com/_ggui/iframe-runtime.js\",\n \"wsUrl\": \"wss://your-server.example.com/ws\",\n \"wsToken\": \"btkn_…\",\n \"expiresAt\": \"2099-01-01T00:00:00.000Z\",\n \"epoch\": 0\n }\n }\n}\n```\n\nAny deployment can adopt the read-plane-only posture by setting `withholdResultMeta` on the server factory. The identity pointer stays in both postures — the identity IS the pointer, and spec-canonical hosts mount from it.\n\nThe tool **declaration** (returned by `tools/list`) is what carries `_meta.ui.visibility: [\"model\"]` — the MCP Apps signal that this tool ships a renderable UI surface. Per-call **results** stamp the locator, as above.\n\n### Render locator grammar\n\n```\nui://ggui/render/[/][#]\n```\n\n| Segment | Presence | Meaning |\n| -------------- | ----------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `sessionId` | Always. | The render to resolve. |\n| `blueprintKey` | On every render since the resume contract landed. | Lets a read fall back to a registry-only mount (the original card with default props) when the render row is gone, instead of returning a typed failure. The segment is named for its domain; the record field it comes from is `contractKey`. |\n| `#` | On `ggui_update` results; absent means the live head. | Pins the immutable epoch-N record. Pinned reads serve identical content forever (conformance-pinned); the bare URI tracks the session's current state. |\n\nBoth the single-segment and two-segment shapes resolve. The single-segment form is kept registered so pre-resume-contract cards still in chat history rehydrate — parse for the optional second segment rather than assuming one is absent.\n\n## The shell at `ui://ggui/render`\n\nReading the resource returns a small HTML document — paper-themed, full-bleed, no chrome — whose only job is:\n\n1. Obtain the `ai.ggui/render` slice — from the host via `postMessage`, or, for a per-render self-contained shell, from the `globalThis.__GGUI_META__` global it inlines synchronously before the bundle loads.\n2. Dynamically load `runtimeUrl` (the iframe-runtime bundle).\n3. Hand the slice to the runtime, which opens the WebSocket and starts rendering.\n\nThe shell is intentionally minimal. The actual rendering work — component resolution, contract validation, action dispatch, gadget loading — lives in [`@ggui-ai/iframe-runtime`](https://www.npmjs.com/package/@ggui-ai/iframe-runtime), which the shell loads on demand. This keeps the shell payload tiny and lets the runtime version-bump independently of host caches.\n\n### Three shell registrations\n\nReading traffic against a real server, you will see more than one shell URI. There are three registrations, and they all serve the same current shell:\n\n| URI | Who asks for it |\n| ----------------------------- | --------------------------------------------------------------------------------------- |\n| `ui://ggui/render` | Grandfathered sessions and hosts that read the bare URI directly. |\n| `ui://ggui/render/rt-` | The content-addressed twin. **Tool declarations advertise THIS URI**, not the bare one. |\n| `ui://ggui/render/rt-` | Stale-hash grandfather template — serves the current shell under any prior hash. |\n\nThe hash covers the full served representation: the shell bytes AND the `_meta.ui.csp` declaration the response carries. Hosts cache the prefetched shell keyed on the resource URI, so the URI must change exactly when the content or the CSP policy does — and never otherwise. The meta has to be in the hash input because hosts cache the declaration alongside the bytes: a policy-only change would otherwise ship under an old URI and never reach cached frames.\n\nThe grandfather template exists because hosts snapshot tool declarations. After a shell-changing deploy they keep asking for the previous deploy's `rt-` URI; without the template that read falls through to the per-session template (a bare `rt-abc…` segment parses as a `sessionId`), resolves no render, and the host shows a mount failure.\n\n### The `_meta.ui.csp` declaration\n\nShell responses carry a `_meta.ui.csp` block with `connectDomains`. Hosts derive the frame's `connect-src` from it — claude.ai applies a restrictive default (`connect-src 'none'`) unless the resource declares otherwise, which blocks the cross-origin runtime `\n```\n\nThe `event.source` check is non-optional — without it, any window can spoof renderer envelopes. Production hosts SHOULD also validate `msg` against [the lifecycle envelope schema](https://github.com/ggui-ai/ggui/blob/main/packages/protocol/src/integrations/mcp-apps.ts) before mirroring state into trusted UI.\n\n---\n\n## Host obligations summary\n\nA host that implements the JSON-RPC methods above plus the four postMessage event handlers honors the protocol's bootstrap contract. The MUST / SHOULD breakdown:\n\n1. **MUST** honor `_meta[\"ai.ggui/render\"].runtimeUrl` from the resource — the iframe-runtime bundle URL.\n2. **MUST** classify `ggui:bootstrap-failed` onto `BootstrapFailureReason` (or render the raw string for unknown values).\n3. **MUST** surface `ggui:bootstrap-failed` as a user-visible error.\n4. **SHOULD** surface `ggui:observe` events to host telemetry.\n5. **MUST NOT** intercept `tools/call` JSON-RPC traffic — forward to the MCP server's tool registry verbatim.\n6. **MUST** narrow `event.source` to the iframe's `contentWindow` before reading any postMessage data.\n\nPart of this is graded by the [conformance kit](/protocol/conformance/)'s host-helper catalog (`host-helper-conformance`): a well-formed `ui/initialize`, truthful capability advertisement (a host that advertises `serverResources` must answer `resources/read`), honest and bounded refusals, and an unmodified `tools/call` relay. The DOM-level obligations above (`runtimeUrl`, bootstrap-failure surfacing, `ggui:observe`, the `event.source` check) are not graded by the kit.\n\n---\n\n## See also\n\n- [Protocol overview](/protocol/overview/) — three-channel topology; bootstrap is the path into the live channel.\n- [Envelopes](/protocol/envelopes/) — live-channel wire shapes (post-bootstrap traffic).\n- [Conformance](/protocol/conformance/) — the bar a host implementation must pass.\n- [`@ggui-ai/iframe-runtime` on GitHub](https://github.com/ggui-ai/ggui/tree/main/packages/iframe-runtime) — `ProtocolError` union, full `ObservabilityEvent` catalog, boot-sequence source.\n- [`useMcpAppsChat`](/host-helpers/react/) (from `@ggui-ai/mcp-apps-react/chat-helpers`) + `` (from `@mcp-ui/client`) — the web React surface that boxes everything above (React Native's host is ``).\n- [`packages/console/src/routes/GguiSessions.tsx`](https://github.com/ggui-ai/ggui/blob/main/packages/console/src/routes/GguiSessions.tsx) — production reference implementation."},{"path":"/protocol/conformance.md","title":"Conformance","description":"What it means to be ggui-conformant — the 4-criterion contract bar, 6-criterion protocol bar, and the conformance kit as arbiter.","body":"---\ntitle: Conformance\ndescription: What it means to be ggui-conformant — the 4-criterion contract bar, 6-criterion protocol bar, and the conformance kit as arbiter.\n---\n\n> An implementation is ggui-conformant iff it passes the [conformance kit](https://github.com/ggui-ai/ggui/tree/main/packages/protocol-conformance) — a fixture-based test suite a candidate runs against. Opinion, intent, and prose-level reading of this site are NOT the arbiter; the kit is.\n\nThis page describes what the GGUI protocol promises in exchange for the name \"protocol\", what each contract inside it must satisfy, and how the kit makes those promises observable.\n\n## What conformance means\n\nConformance for GGUI means three concrete things:\n\n1. **A third-party implementation can replace the first-party one** — agents, hosts, and ops tools that work against the OSS `ggui serve` work against the third-party server too, without source-level changes.\n2. **Every named failure mode produces an observable signal** — operators see violations without running a debugger.\n3. **Every breaking change to the protocol is reproducible** — \"is this PR breaking?\" resolves to a kit run, not a debate.\n\nIf a layer that calls itself a \"protocol\" can't honor these three promises, the layer is something else (a shape, an SDK feature, an author convention) and should be named accordingly.\n\n## The Contract Bar — 4 criteria\n\nA **runtime contract** in GGUI MUST satisfy all four. Three of four is not a contract. Documenting a fourth in prose without mechanism is not a contract.\n\n### 1. Named parties\n\nThe contract states WHO is on each side. Not \"producer\" and \"consumer\" in the abstract — the concrete roles. The `ggui_runtime_submit_action` handler and the consume-buffer pipe. The iframe-runtime and the render-channel server. The contract author and the platform validator. If you can't name the parties in one sentence, there is no contract — only a data type adrift.\n\n- ✅ \"The `ggui_runtime_submit_action` handler appends every valid `kind: 'dispatch'` envelope to the render-keyed pending-events pipe; the agent drains it via `ggui_consume`.\"\n- ❌ \"Clients should respect the ordering semantics.\"\n\n### 2. Explicit obligations per party\n\nEach party has a list of MUSTs and MUST-NOTs. SHOULDs are discipline, not contract — a SHOULD belongs in a style guide. The obligations must be specific enough that a reviewer can literally check a diff against them.\n\n- ✅ \"Agent-authored `streamSpec` MUST NOT declare a channel whose name starts with `_ggui:`.\"\n- ❌ \"Handlers should behave predictably.\"\n\nAn obligation without a verifiable test is a hope, not a contract.\n\n### 3. Defined failure mode per obligation\n\nWhen the obligation breaks, there is a **named, typed, observable failure**. Generic `throw new Error()` is not a failure mode. `console.warn()` is not a failure mode. \"Log the outcome to telemetry and carry on\" is not a failure mode.\n\nAcceptable mechanisms:\n\n- A canonical error-code union (`CONTRACT_VIOLATION`, `SESSION_NOT_FOUND`, `SCHEMA_MISMATCH_ERROR`, the runtime-tool rejection codes `INVALID_ACTION_KIND` / `PIPE_NOT_FOUND` / `CONTEXT_TOO_LARGE`).\n- A typed rejection frame the caller receives on the call that caused it (e.g. a `CONTRACT_VIOLATION` error frame on the live channel, or a `{ok:false, code}` `structuredContent` rejection on a runtime tool).\n- Boot-time refusal with a message naming the offender (e.g. mount tool-name collision).\n- Compile-time impossibility (the type has no field → consumers can't read it).\n\nUnacceptable: silent noop, silent degradation, swallowed exception, \"it'll surface in the next call if it's a real problem.\"\n\n### 4. Observable violation\n\nAn operator can **see the violation without running a debugger**. Surfaces:\n\n- An error envelope/frame the caller observes synchronously (the gold standard — a `CONTRACT_VIOLATION` error frame on the live channel when an inbound action violates the contract).\n- A validation response the caller receives synchronously.\n- An operator UI that reads the above.\n- A structured log emitted at a known event name, documented as the contract's telemetry point.\n\nA contract whose violations only show up in production stack traces fails this bar — an operator who inherits the system in six months can't tell what's working and what's silently degraded.\n\n---\n\n## The Protocol Bar — 6 criteria\n\nA **protocol** is the emergent layer above a set of contracts. Every layer called \"a protocol\" MUST satisfy all six. Five of six is a protocol-in-progress; the gap MUST be flagged explicitly and the layer treated as experimental until closed.\n\n### 1. Wire-format specification\n\nA canonical prose spec describing every envelope shape, every field, every value constraint, and — critically — every intentional omission and why. Not just TypeScript types. Types say the shape; the spec says the **semantics**.\n\nFor GGUI, this lives in the site-level wire references — [Envelopes](/protocol/envelopes/), [MCP Protocol](/api/mcp-protocol/), [WebSocket Protocol](/api/websocket-protocol/) — which document every envelope shape, field, and intentional omission.\n\n### 2. Message sequencing and state\n\nGiven envelope X at time T in state S, which transitions are legal? What happens on reconnect? On resume? On concurrent emission? Crash recovery? Out-of-order delivery?\n\nA protocol without sequencing is a data type with pretensions. GGUI's sequencing lives in the [three-channel topology](/protocol/overview/) + the `GguiSessionStreamBuffer` interface + the `fromSeq` replay contract. Any new channel or envelope class MUST answer the sequencing question explicitly.\n\n### 3. Version negotiation\n\nProducer and consumer MUST be able to agree on what version they speak, or explicitly refuse. Stamping a version on every envelope is infrastructure; actually rejecting a mismatched peer is the protocol feature. Pre-launch \"advisory stamp only\" is acceptable IF the launch-cutover plan names the policy flip (producer-stamp + consumer-reject).\n\nAnti-pattern: calling version-stamping \"versioning\" and shipping. See [Version policy](/protocol/version-policy/) for the post-launch handshake semantics.\n\n### 4. Conformance testability at the seam\n\nA third-party implementer can verify their implementation without running the GGUI server. This means:\n\n- A public fixture table of envelopes and expected behaviors.\n- An executable conformance kit (a test package a third party `pnpm add`s and runs).\n- Coverage of every canonical failure mode — a third-party implementation that passes the kit can be used interchangeably with the first-party one.\n\nWithout this, \"third party adopts the protocol\" means \"third party reads the spec and hopes.\"\n\n### 5. Named failure modes — closed, or extensibly-closed\n\nEvery way the protocol can fail has a name, a code, and a shape. Acceptable forms:\n\n- **Closed union** — exhaustive by design. Bumping requires a major version bump. Use when the set of values is fixed by an external spec or by a pre-launch design decision the protocol owners control end-to-end.\n- **Extensibly-closed** — e.g. the `channel_error` code union `'CHANNEL_UNKNOWN' | 'SESSION_NOT_FOUND' | 'SUBSCRIBE_UNAUTHORIZED' | 'POLL_FAILED' | (string & {})`, or the open `code: string` on the WS `error` frame whose canonical literals include `CONTRACT_VIOLATION` and `UPGRADE_REQUIRED`. Consumers MUST handle unknown values gracefully. Adding new values does NOT bump the protocol version. Use when producer-side failure modes are expected to grow (new tool classes, new transports, new preconditions) without consumers needing a new version to render them.\n\nUnacceptable: ad-hoc `message: string` as the only failure surface.\n\n### 6. Vendor-neutral separation from implementation\n\nThe protocol package imports nothing from a specific runtime, transport, cloud vendor, or framework. `@ggui-ai/protocol` MUST remain consumable by a third-party implementation that has never seen `@ggui-ai/mcp-server`.\n\nViolation of this criterion is the loudest signal that what you have is an SDK feature pretending to be a protocol.\n\n---\n\n## The conformance kit\n\nThe kit lives at [`packages/protocol-conformance`](https://github.com/ggui-ai/ggui/tree/main/packages/protocol-conformance) in the open repo — a fixture-based test suite a candidate implementation runs against to demonstrate conformance.\n\n```bash\npnpm add -D @ggui-ai/protocol-conformance\n```\n\nBeyond the WS runner, the package ships a sub-entrypoint per catalog that is not a WS fixture. The [package README](https://github.com/ggui-ai/ggui/tree/main/packages/protocol-conformance#conformance-status) says what each is graded against. Among them:\n\n| Entrypoint | Kind | Covers |\n| ---------------------------------- | -------------------------------------- | -------------------------------------------------------------------------------------------------- |\n| `schema-conformance` | Pure function | Gadget schema obligations. |\n| `registration-conformance` | Pure function | Gadget registration obligations. |\n| `resolution-conformance` | Pure function | Gadget resolution obligations. |\n| `binding-conformance` | Pure function | MCP tool-binding resolution and search-filter semantics. |\n| `resource-read-conformance` | Driver (live MCP server) | A `resources/read` catalog — the kit's first MCP-binding driver. |\n| `domain-error-conformance` | Driver (`tools/call`) | Domain errors as tool results whose text leads with the registered slug (§7.9 Plane 2). |\n| `dispatch-idempotency-conformance` | Driver (`tools/call`) + a session seam | A retried `ggui_runtime_submit_action` dispatch is one gesture (§11.1); SHOULD level this release. |\n\nImport them as `@ggui-ai/protocol-conformance/`. The raw fixture catalog is also exported at `@ggui-ai/protocol-conformance/fixtures`.\n\nProgrammatic and CLI entry points:\n\n```ts\nimport { runConformance } from \"@ggui-ai/protocol-conformance\";\n\nconst result = await runConformance({\n serverUrl: \"http://localhost:3000\",\n auth: { kind: \"bearer\", token: process.env.TOKEN! },\n});\n\nif (result.failed.length > 0) process.exit(1);\n```\n\n```bash\nnpx ggui-protocol-conformance --url http://localhost:3000 --auth bearer:$TOKEN\n```\n\nA fixture grades a MUST unless it declares `\"level\": \"should\"`. An unmet SHOULD is a **warning**: it lands in `result.warned` with the same evidence a failure carries and never fails a run, so the exit code above ignores it. The first SHOULD case is `fresh-subscribe-replays-reserved-preview` (SPEC §12.2.1): a fresh subscribe replays a known-reserved channel's retained envelopes after the ack.\n\n`serverUrl` / `--url` take the implementation's **base** `http://` / `https://` URL — the runner appends `/ws` and derives the `ws://` / `wss://` scheme itself.\n\n**Transport.** The behavioral fixture catalog is **WebSocket-only** — the canonical GGUI transport (see the [WebSocket Protocol reference](/api/websocket-protocol/)). `resource-read-conformance` adds a second binding: an MCP `resources/read` catalog driven against a live MCP server. The kit's `TransportConfig` is an extensibly-closed union, so further bindings (stdio MCP, HTTP long-poll) can be added without breaking the public API.\n\n**Path-A vs Path-B fixtures.** The fixture catalog spans both wire-observable claims and surface-observable claims. The runner handles **Path-A** — behaviors a runner can assert from WS frames alone (no MCP-Apps-host adapter, no Playwright). **Path-B** fixtures (e.g., `bootstrap-failure`, `props-update`) require a browser-host harness driving Playwright + `page.route()` fault injection + DOM assertion; they are recorded as SKIP on the WS runner, not FAIL. The partition is intentional: Path-A FAILs are vendor-neutrality bugs the server owns; Path-B SKIPs are claims a different driver is responsible for.\n\nThe kit covers:\n\n- **Envelope round-trip** — every fixture in the table can be emitted, observed, validated, and round-tripped.\n- **Reserved-channel authority** — the implementation rejects agent-authored `streamSpec` entries in the `_ggui:` namespace and validates the platform-owned shapes (`_ggui:preview`, `_ggui:lifecycle`).\n- **Schema enforcement** — `actionSpec[action].schema` ⊆ the hinted tool's `inputSchema`, with a `SCHEMA_MISMATCH_ERROR` push-time rejection on violation.\n- **Sequencing** — `seq` is gap-free per-session, `fromSeq` replay returns the right tail, `replayTruncated` is honored when the requested cursor is unrecoverable.\n- **Version handshake** — schema-version stamping on every envelope; `UPGRADE_REQUIRED` emission on mismatch (post-launch — pre-launch is advisory).\n- **Action persistence** — an action frame round-trips to an ack carrying `payload.sequence`, proving the event landed on the GguiSession's consume buffer (append-then-ack).\n- **Contract enforcement at receipt** — an action for an undeclared name is rejected with a `CONTRACT_VIOLATION` error frame and nothing reaches the consume buffer.\n\nA change is **breaking** iff at least one fixture that passed against version N now fails against version N+1 when the only change is the protocol version. See [Version policy → §2](/protocol/version-policy/#2-breaking-change-definition--the-kit-is-the-arbiter) for the policy this anchors.\n\n---\n\n## Pre-launch vs launch posture\n\nPre-launch (`draft-` versions), some protocol criteria are intentionally at ⚠️ — flagged gaps with owners and closing slices. The point is not zero gaps forever; it is **zero silent gaps**.\n\n| Criterion | Pre-launch posture | Launch (v1.0) |\n| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |\n| Version negotiation | Envelope `schemaVersion`: advisory stamp; consumers MUST NOT reject on mismatch. Subscribe handshake (`supportedVersions` / `serverVersion`): server default `versionPolicy: 'reject'` — emits `UPGRADE_REQUIRED` and closes; `'advisory'` is a legacy opt-out for migration windows. | Same mechanisms; envelope stamps stay advisory, the subscribe handshake stays the rejection point. Mismatched majors surface as `UPGRADE_REQUIRED`. |\n| Conformance kit | Optional today; available for first-party servers + early third-party implementers. | Required before third-party implementers are invited to build on the protocol. |\n| Schema-compat checker | Render-time + console blueprint-try (`SCHEMA_MISMATCH_ERROR` rejection on the `ggui_render` tool result); operator policy `'reject' \\| 'warn' \\| 'off'` (default `'reject'`). | Same; default unchanged. |\n\nAt launch, all load-bearing boundaries MUST be at 4/4 contract + 6/6 protocol for any layer described as a public interop surface. Load-bearing = any boundary a third-party implementer is expected to adopt. Internal-only boundaries may sit at lower scores if the gap is explicitly scoped to internal use.\n\n---\n\n## Anti-patterns\n\nThings that feel contract-shaped but fail the bar:\n\n| Looks like | Is actually | Why |\n| ------------------------------------- | ---------------------------- | ---------------------------------------------------------- |\n| \"TypeScript type is the contract\" | Shape-only | Types say what, not who/when/what-on-violation |\n| \"Docstring says MUST\" | Author discipline | Prose without mechanism decays |\n| \"A validator function exists\" | Half-contract | Validator without observable failure path wastes the check |\n| \"Error gets logged\" | Not observable | Logs aren't observability unless somebody reads them |\n| \"Pre-launch advisory\" | Infrastructure, not contract | Valid interim stance; MUST flag the gap + name the flip |\n| \"We cover the common cases\" | Denylist discipline | Rock-paper-scissors with future adversaries |\n| \"Three similar implementations agree\" | Folklore | Interop-by-intuition is not interop |\n\nIf a new \"contract\" maps to a row here, either strengthen it to meet the bar or pick a different word.\n\n---\n\n## Vocabulary\n\nUsed precisely throughout this site:\n\n- **Shape** — a TypeScript type with no enforcement story.\n- **Convention** — author discipline; no mechanism.\n- **Contract** — passes the 4-criterion bar.\n- **Protocol** — passes the 6-criterion bar; a set of contracts with sequencing + versioning + conformance-kit.\n\nIf a doc says \"this contract is enforced by convention\" — that's a category error and either the contract framing or the convention framing is wrong.\n\n---\n\n## See also\n\n- [Protocol overview](/protocol/overview/) — three-channel topology and reference implementation.\n- [Version policy](/protocol/version-policy/) — semver semantics, breaking-change definition, deprecation timeline.\n- [Envelopes](/protocol/envelopes/) — wire shapes the conformance kit asserts on.\n- [Conformance kit on GitHub](https://github.com/ggui-ai/ggui/tree/main/packages/protocol-conformance) — the test package itself."},{"path":"/protocol/envelopes.md","title":"Live-channel envelopes","description":"Wire shapes for ActionEnvelope (inbound), StreamEnvelope (outbound), and the reserved _ggui namespace.","body":"---\ntitle: Live-channel envelopes\ndescription: Wire shapes for ActionEnvelope (inbound), StreamEnvelope (outbound), and the reserved _ggui namespace.\n---\n\nThe live WebSocket carries three body shapes:\n\n| Shape | Direction | Carries |\n| -------------------- | --------------- | -------------------------------------------------------------- |\n| `ActionEnvelope` | client → server | A canonical user action (form submit, click, …) |\n| `StreamEnvelope` | server → client | An outbound delivery on a named stream channel |\n| `PropsUpdatePayload` | server → client | The full replacement props state for an already-mounted render |\n\nThe first two are the envelopes an agent-declared contract validates against. `PropsUpdatePayload` carries no contract-declared channel — it is the state fan-out — but it rides the same socket, so it is documented here too. For the complete frame catalog (`subscribe`, `ack`, `render`, `render_event`, `channel_*`, …) see the [WebSocket Protocol reference](/api/websocket-protocol/#frame-catalog).\n\nCanonical wire reference. Shapes below mirror the TypeScript in [`@ggui-ai/protocol`](https://github.com/ggui-ai/ggui/tree/main/packages/protocol/src) verbatim: `types/events.ts` (ActionEnvelope), `types/live-channel.ts` (StreamEnvelope, PropsUpdatePayload).\n\n:::tip[Protocol version]\nWire shapes documented here are stable at `draft-2026-09-10`. See [Version policy](/protocol/version-policy/) for breaking-change semantics.\n:::\n\n---\n\n## ActionEnvelope\n\nInbound live-channel envelope — the body of a `type: 'action'` WebSocket message. Flat, narrow, limited to fields the server actually enforces or diagnostic fields real consumers populate today.\n\n```ts\ninterface ActionEnvelope {\n sessionId: string; // required — render identity\n type: EventType; // required — see EventType below\n payload?: TPayload; // shape depends on `type`\n clientSeq?: number; // client-monotonic dedup hint\n schemaVersion?: string; // producer's PROTOCOL_SCHEMA_VERSION (advisory pre-launch)\n}\n```\n\n| Field | Type | Required | Semantics |\n| --------------- | ----------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `sessionId` | `string` | Yes | Server enforces subscriber-render binding — envelopes whose `sessionId` doesn't match the render the WebSocket subscriber is bound to are rejected with `SESSION_MISMATCH`. |\n| `type` | `EventType` | Yes | Always `data:submit` — the only member of the `EventType` union (see below). The active render's `actionSpec` gates which action names are accepted. (The pre-actionSpec `EventSubscription` / `DEFAULT_SUBSCRIPTION` gating shapes were deleted from `@ggui-ai/protocol` — there is no subscription gating on the wire.) |\n| `payload` | `TPayload?` | No | For `type: 'data:submit'` this carries an `ActionEventValue` shape (`{action, data, tool?}`) whose `data` field is validated against the render's `actionSpec[action].schema`. |\n| `clientSeq` | `number?` | No | Client-monotonic sequence number for at-least-once dedup. Declared shape; no server enforcement today (no inbound dedup infrastructure yet). Clients SHOULD populate when their transport can replay (e.g., reconnect-with-backfill). |\n| `schemaVersion` | `string?` | No | Protocol schema version stamped by the producer. Pre-launch: advisory — consumers MUST NOT reject on mismatch. Post-launch: receiving major mismatches surface as `UPGRADE_REQUIRED`. |\n\n### Fields intentionally NOT on the envelope\n\nThese fields appear on neighboring shapes but are excluded from `ActionEnvelope` by design:\n\n| Field | Why omitted |\n| --------------------------------- | ------------------------------------------------------------------------------------------------------- |\n| `appId` | Server resolves it from the render; client-claimed values are ignored for enforcement. |\n| `userId` / `user` | Diagnostic render metadata captured at subscribe time, not per-delivery. |\n| `deviceInfo` / `interfaceContext` | Same as above — render-level, not action-level. |\n| `componentId` / `contractHash` | Diagnostic; no enforcement consumer today. |\n| `timestamp` | Server uses its own clock for ordering + log emission; client-supplied timestamps aren't authoritative. |\n| `correlationId` | The doctrine names this for agent-push ↔ user-action pairing; `sessionId` covers the narrow case today. |\n\n### `EventType`\n\n`EventType` is a single-member union — `'data:submit'` is the only action type the protocol recognizes:\n\n| Type | Notes |\n| ------------- | ----------------------------------------------------------------------- |\n| `data:submit` | Carries `ActionEventValue` (`{action, data, tool?}`); schema-validated. |\n\nThe old `data:change` / `lifecycle:focus` / `lifecycle:blur` / `interaction:click` / `interaction:hover` / `interaction:scroll` / `error:validation` / `error:connection` members were removed in `draft-2026-06-12` — they had no producers.\n\n### `ActionEventValue`\n\nPayload shape for `data:submit`:\n\n```ts\ninterface ActionEventValue {\n action: string; // action ID from the contract (e.g. \"submit\", \"archive\")\n data: TData; // action payload (e.g. form data)\n tool?: string; // MCP tool name mirrored from actionSpec[action].nextStep (when declared)\n}\n```\n\n**Derivation.** `tool` is derived server-side from `actionSpec[action].nextStep` at event-build time — clients do not populate it. When the action has no declared `nextStep`, `tool` is absent — the agent decides the next tool freely from broader context. The hint is advisory either way; the agent owns the call decision.\n\n---\n\n## StreamEnvelope\n\nOutbound live-channel envelope — the body of a `type: 'data'` WebSocket message. Carries a single delivery on a named stream channel.\n\n```ts\ninterface StreamEnvelope {\n sessionId: string; // required\n channel: string; // required — keys into streamSpec\n mode: StreamChannelMode; // required — 'append' | 'replace'\n payload: JsonValue; // required — channel-specific shape\n complete?: boolean; // terminal marker for completable channels\n seq?: number; // server-assigned monotonic outbound sequence\n schemaVersion?: string; // producer's PROTOCOL_SCHEMA_VERSION\n}\n```\n\n| Field | Type | Required | Semantics |\n| --------------- | ------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |\n| `sessionId` | `string` | Yes | Render this delivery belongs to. |\n| `channel` | `string` | Yes | Channel name. Keys into the agent's declared `streamSpec`. Names starting with `_ggui:` are server-owned (see [Reserved channels](#reserved-channels)). |\n| `mode` | `StreamChannelMode` | Yes | State-folding mode. `'append'` (default for narrative streams — message log, telemetry) accumulates deliveries; `'replace'` (default for snapshot streams — task progress, session state) replaces the current value. Senders declare; receivers honor. Typically equals the channel's declared `mode` on the spec, but the envelope is the authoritative per-delivery signal. |\n| `payload` | `JsonValue` | Yes | Validated against `streamSpec[channel].schema`. Shape is channel-specific; consumers typecheck via contract inference when they use `defineContract` + `useStream`. |\n| `complete` | `boolean?` | No | Terminal completion marker — truthy on the last delivery for a completable channel (one declared with `complete: true` on the spec). Consumers use this to transition subscribers into a \"channel closed\" state. Absent on non-terminal deliveries. |\n| `seq` | `number?` | No | Render-scoped monotonic outbound sequence. Server-assigned; clients MUST NOT populate it on producer-side inputs. Gap-free within a single render, starting at 1. Used by the client to track `lastSeenSeq`, the highest `seq` it has applied, for reconnect (pass it back as `SubscribePayload.fromSeq`), and to dedupe deliveries against it (at-least-once semantics), never against the ack's `streamSeq` (SPEC §12.2.1). OPTIONAL because stamping is best-effort: both OSS `@ggui-ai/mcp-server` and hosted cloud stamp `seq` on every successfully buffered delivery, but a delivery whose buffer record failed ships unstamped rather than blocking the emit. A future slice promotes this to required once buffering is guaranteed non-lossy. |\n| `schemaVersion` | `string?` | No | Same advisory-pre-launch / `UPGRADE_REQUIRED`-post-launch semantics as on `ActionEnvelope`. |\n\n### Fields intentionally NOT on the envelope\n\n| Field | Why omitted |\n| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `replay` | Per-channel policy declared on `streamSpec[channel].replay`. A per-delivery field would imply replay can vary message-to-message, which it can't. |\n| `timestamp` | Replay correctness needs `seq` only; timestamp is a future optional addition driven by a concrete client-UX need. |\n\n---\n\n## PropsUpdatePayload\n\nServer → client. The body of a `type: 'props_update'` message — the `ggui_update` / `ggui_amend` fan-out. Replaces props on an already-rendered component without re-generation.\n\n```ts\ninterface PropsUpdatePayload {\n sessionId: string;\n props: JsonObject;\n epoch?: number;\n}\n```\n\n| Field | Type | Required | Description |\n| ----------- | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `sessionId` | `string` | Yes | The render being updated. |\n| `props` | `JsonObject` | Yes | **Full replacement state**, not a patch — post-merge for `kind: \"merge\"` updates. Persistence is the source of truth; this frame is the latency optimization. |\n| `epoch` | `number?` | No | The commit-time history epoch. `ggui_update` stamps its just-advanced epoch; `ggui_amend` stamps the unchanged head. |\n\n`epoch` is the **freeze-latch signal**. A mount whose own epoch is lower than the frame's has been superseded and MUST freeze rather than apply — that is what keeps an old history card from silently repainting with state belonging to a newer one.\n\nAbsent `epoch` reads as `0`: pre-epoch producers and amends against an epoch-0 head omit it. Consumers MUST tolerate the absence rather than reject the frame.\n\n---\n\n## Reserved channels\n\nChannel names starting with `_ggui:` are **reserved** for the server. Agent-authored `streamSpec` MUST NOT declare any name in this namespace; structural validation rejects every reserved-prefix entry with the message `Stream channel '' is in the reserved '_ggui:' namespace — server-owned channels cannot be declared in agent streamSpec`.\n\nTwo channel names are recognized today:\n\n| Channel | Owner | Payload shape | Purpose |\n| ----------------- | ------------- | -------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `_ggui:preview` | Server (A2UI) | A2UI `ServerMessage` — see `@ggui-ai/preview-a2ui` | Provisional A2UI assembly stream emitted by the server during fresh-gen `ggui_render` flows. The renderer subscribes implicitly and dispatches the payload through its preview surface. |\n| `_ggui:lifecycle` | Server | `GguiLifecyclePayload` | Generation-progress lifecycle kinds (`handshake_started`, `handshake_completed`, `render_started`, `consume_polling`) the renderer surfaces as a progress affordance. |\n\nA typo inside the reserved namespace (e.g. `_ggui:preveiw`) is NOT recognized — delivery falls through to the normal \"unknown channel\" rejection rather than silently passing as a reserved channel.\n\nThe `_ggui:contract-error` channel was a reserved channel in earlier drafts but was removed entirely in `draft-2026-06-11` — the channel, its payload shape, and its validator are gone. Contract violations now surface as a typed `CONTRACT_VIOLATION` error frame on the live channel on the call that caused them; nothing lands on the consume buffer.\n\n---\n\n## Schema versioning\n\nThe `schemaVersion` field is present on both envelopes. It carries the producer's `PROTOCOL_SCHEMA_VERSION` constant.\n\n**Pre-launch (`draft-` versions):** advisory. Consumers MUST NOT reject on mismatch; missing `schemaVersion` fields are normal.\n\n**Post-launch:** receiving an envelope whose major version diverges from the consumer's known major surfaces as a live-channel error with `code: UPGRADE_REQUIRED`. The handshake resolution flow is documented in the [WebSocket Protocol](/api/websocket-protocol/) reference.\n\nSee [Version policy](/protocol/version-policy/) for the full mapping of what counts as a major / minor / patch bump.\n\n---\n\n## See also\n\n- [WebSocket Protocol](/api/websocket-protocol/) — live-channel message types (`subscribe`, `action`, `ack`, `render`, `data`, `error`) that carry these envelope payloads.\n- [MCP Protocol](/api/mcp-protocol/) — MCP JSON-RPC methods (`ggui_handshake`, `ggui_render`, `ggui_consume`, etc.).\n- [Protocol overview](/protocol/overview/) — the three-channel topology.\n- [Version policy](/protocol/version-policy/) — semver semantics, breaking-change definition, deprecation timeline.\n- [`@ggui-ai/protocol` source](https://github.com/ggui-ai/ggui/tree/main/packages/protocol/src) — canonical TypeScript definitions."},{"path":"/protocol/overview.md","title":"Protocol overview","description":"GGUI is an open protocol for AI agents to render interactive UIs over three wire channels. MCP-native, framework-agnostic, server-enforced.","body":"---\ntitle: Protocol overview\ndescription: GGUI is an open protocol for AI agents to render interactive UIs over three wire channels. MCP-native, framework-agnostic, server-enforced.\n---\n\n`ggui` is an **open protocol** that lets AI agents render interactive UIs to humans. An agent describes what it needs in natural language; GGUI generates React components, delivers them over a typed live channel, and routes user actions back through a server-side enforcement point.\n\nThis site documents the protocol itself, version `draft-2026-09-10` (see `PROTOCOL_SCHEMA_VERSION` in [`@ggui-ai/protocol`](https://github.com/ggui-ai/ggui/tree/main/packages/protocol/src/version.ts)). Everything below is implementable from the spec — the open-source [`ggui serve`](/cli/serve/) is the reference conformant implementation, and hosted GGUI at `https://mcp.ggui.ai` runs the same protocol. The `@ggui-ai/*` packages are the reference implementations.\n\n:::note[GGUI vs guuey]\n**GGUI** (this site) is the open protocol — published at [github.com/ggui-ai/ggui](https://github.com/ggui-ai/ggui); a hosted endpoint at `mcp.ggui.ai` runs it too. **guuey** is a separate commercial agent-hosting platform at [guuey.com](https://guuey.com) that speaks the GGUI protocol. Don't conflate them.\n:::\n\n## Three parties, three channels\n\n```\n ┌───────────────────────┐\n │ user client │\n │ (React / RN / web) │\n └─────┬────────────┬────┘\n │ │\n chat live (WebSocket)\n (HTTP SSE) ↑↓\n │ │\n ┌────────▼────┐ ┌───▼────────────┐\n │ wrapped- │ │ │\n │ agent │ │ core-mcp │\n │ (developer │───▶ (session │\n │ code) │ MCP authority) │\n └─────────────┘ └────────────────┘\n MCP\n (over HTTP)\n```\n\n| Channel | Direction | Transport | Purpose | Status |\n| ------- | ---------------------- | ------------- | ------------------------------------------------- | --------- |\n| Chat | user ↔ wrapped-agent | HTTP SSE | Conversational surface (chat-completion style) | Optional |\n| MCP | agent ↔ core-mcp | MCP over HTTP | Tool control + session mutation | Mandatory |\n| Live | core-mcp ↔ user client | WebSocket | Live UI session delivery + canonical user actions | Mandatory |\n\nThe MCP and live channels are the **protocol kernel** — every conformant implementation MUST provide them. The chat channel is product-mandatory (the OSS `ggui serve` ships a chat surface) but protocol-optional: an embed that uses GGUI purely for typed live UIs, with no conversational chat, is still conformant.\n\n:::note[Channel names, not numbers]\nThis page describes the conversational stack — the three transports between a user, a wrapped agent, and the GGUI server: **chat / MCP / live**. The [Architecture overview](/architecture/overview/) describes the wire pipeline instead — **bootstrap / MCP / live**. The two views share MCP and the live channel; they differ only on the third: the protocol view names the chat surface the agent and user talk over, while the architecture view names the bootstrap fetch that delivers the compiled component to the renderer. Naming channels by their transport keeps the two views consistent.\n:::\n\nThe WebSocket endpoint is `ws://127.0.0.1:6781/ws` (default) when running `ggui serve` locally; self-hosters expose it as `wss:///ws`. (The hosted endpoint is `wss://mcp.ggui.ai/ws`.)\n\n## Why the live channel is mandatory\n\nThe typed live-channel contract needs a server-side enforcement point. That point is the live channel itself.\n\nA `streamSpec` declares named streams, payload schemas (validated as `StreamEnvelope`s), replay policy, ordering, and completion semantics. Subscriptions declare which events the client UI consumes. None of that means anything unless a non-agent authority validates it on the wire. If the agent shipped bytes directly to the user, the \"contract\" would be documentation, not contract — see [Conformance](/protocol/conformance/) for the 4-criterion contract bar this enforces.\n\nSo **no live channel, no enforcement point, no contract.** The live channel and the typed live-channel contract are a pair — reconsider one, you reconsider the other.\n\n## Wire surfaces\n\nEach channel maps to a documented wire surface on this site:\n\n| Surface | Channel | What it covers |\n| --------------------------------------------------- | ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| [MCP Protocol](/api/mcp-protocol/) | MCP | JSON-RPC methods (canonical lifecycle order): `ggui_handshake`, `ggui_render`, `ggui_consume`, `ggui_update`, `ggui_amend`, `ggui_emit`, `ggui_get_session`, `ggui_get_render_source`, `ggui_list_sessions`, plus gadget/theme/blueprint discovery (`ggui_list_gadgets`, `ggui_list_themes`, `ggui_list_featured_blueprints`, `ggui_search_blueprints`, `ggui_render_blueprint`) |\n| [WebSocket Protocol](/api/websocket-protocol/) | Live | Subscribe / `ActionEnvelope` / ack / render / `StreamEnvelope`; replay; reconnection |\n| [MCP Apps support](/api/mcp-apps/) | MCP + Live | Resource shape (`{contents:[{uri,mimeType,text}]}`); host-side iframe-runtime boot |\n| [OAuth (`ggui serve --oauth`)](/self-hosted/oauth/) | MCP | OAuth 2.1 + PKCE + Dynamic Client Registration for hosts with no pre-shared bearer |\n\n## Reference implementation\n\nThe open implementation lives at [`github.com/ggui-ai/ggui`](https://github.com/ggui-ai/ggui):\n\n- `packages/mcp-server` — the MCP + live-channel server.\n- `packages/mcp-apps-react` / `packages/mcp-apps-react-native` — the web and React Native MCP-Apps host helpers. They wrap the host side of the handshake; rendering semantics live in the mounted view, not in these packages.\n- `packages/ggui-cli` — ships [`ggui serve`](/cli/serve/), which runs the whole protocol locally on one command.\n\nThe self-hosted open-source path runs the whole protocol on one command via `ggui serve`. Hosted GGUI at `https://mcp.ggui.ai` runs the same protocol on managed infrastructure, with no self-host required.\n\n## Core vocabulary\n\nThree nouns recur on every page. Get them right and the rest of the spec falls into place — see the [glossary](/glossary/) for the full list.\n\n- **Gadget** — a renderer-side capability (Mapbox, Leaflet, a charting library). Declared per-app in `ggui.json#app.gadgets` (the `@ggui-ai/gadgets` stdlib is always the floor); loaded at iframe boot. The agent never touches gadget code.\n- **Tool** — an agent-side action exposed over MCP (`ggui_render`, `ggui_update`, `ggui_amend`, etc.). Tools mutate session state.\n- **Blueprint** — a cached recipe (component code + contract) keyed by intent. Matched on the reuse path; generated on miss.\n\nGadgets and tools are the protocol's two **symmetric capability surfaces** — gadgets give the renderer something to render with; tools give the agent something to act with. Both are operator-bounded and declared per-app (`clientCapabilities.gadgets`, `agentCapabilities.tools`). See [glossary → Capabilities](/glossary/#capabilities).\n\n## What the protocol is not\n\n- **Not a renderer.** The protocol carries component code and props; how the host evaluates that code is its concern. The reference implementation uses dynamic ESM import plus the `@ggui-ai/iframe-runtime` bundle (the self-contained ESM bundle that boots inside the MCP-Apps iframe), but a conformant host can swap in a sandboxed iframe, a server-rendered HTML pipeline, or anything else.\n- **Not a UI library.** Components are generated per render by the agent; GGUI ships no fixed component set. Primitives (Button, Input) are catalog-declared, not protocol-declared.\n- **Not framework-coupled.** The wire is JSON over HTTP and WebSocket. React has the most-developed host helpers today, but `@ggui-ai/protocol` types and `@modelcontextprotocol/sdk` (Anthropic's official MCP TypeScript SDK) are framework-neutral.\n\n## Versioning + conformance\n\nThe protocol follows semver. The arbiter for \"what counts as a breaking change\" is the **conformance kit** at [`packages/protocol-conformance`](https://github.com/ggui-ai/ggui/tree/main/packages/protocol-conformance) — a fixture-based test suite that any candidate implementation runs against.\n\nA change is **major** iff at least one conformance fixture that passed against version N now fails against version N+1, with the protocol version as the only delta. See the [Version policy](/protocol/version-policy/) for the full semver mapping, deprecation timeline, and version support matrix.\n\n## See also\n\n- [MCP Protocol reference](/api/mcp-protocol/) — MCP wire grammar.\n- [WebSocket Protocol reference](/api/websocket-protocol/) — live-channel wire grammar.\n- [Envelopes](/protocol/envelopes/) — the live-channel wire shapes: `ActionEnvelope` (inbound) and `StreamEnvelope` (outbound), plus the reserved `_ggui:` channel namespace.\n- [Bootstrap handshake](/protocol/bootstrap-handshake/) — host-side postMessage + JSON-RPC contract for mounting a session in an iframe.\n- [Conformance](/protocol/conformance/) — the kit, the bar, and how to claim conformance.\n- [`ggui serve`](/cli/serve/) — run the protocol locally."},{"path":"/protocol/showcase-trimly.md","title":"Showcase: a real turn","description":"One real conversation with a live ggui-rendering agent, narrated beat by beat — every \"On the wire\" panel is a frame recorded off the wire, not prose about what would happen.","body":"---\ntitle: Showcase: a real turn\ndescription: One real conversation with a live ggui-rendering agent, narrated beat by beat — every \"On the wire\" panel is a frame recorded off the wire, not prose about what would happen.\n---\n\n{/* Every claim this page makes about how a turn WENT — the counts AND the\n which-call-shape flags — is read off the same frames the panels show,\n never asserted in prose and never defaulted. The manifest declares the\n same four facts; they are reconciled here rather than trusted, so a\n manifest that drifts from the recording reds the build instead of putting\n a false sentence above a panel that contradicts it. */}\nexport const renderStats = (turn, n) => {\n const kinds = frameKinds(turn.frames);\n const results = turn.frames.filter((_, i) => kinds[i] === \"message:tool.done:ggui_render\");\n const refusals = results.filter((f) => f.data.isError === true);\n const succeeded = results.filter((f) => f.data.isError !== true);\n const counted = {\n renderAttempts: results.length,\n refusedRenders: refusals.length,\n hasRender: succeeded.length > 0,\n // Mirrors hasRender, and mirrors the capture rig's turnFlags(): a REFUSED\n // update is not an update. Counting any tool.done would make a recording\n // with a rejected ggui_update disagree with its own manifest.\n hasUpdate: turn.frames.some(\n (f, i) => kinds[i] === \"message:tool.done:ggui_update\" && f.data.isError !== true\n ),\n };\n // Under the read-plane-only posture (guuey#209 C3, armed on prod\n // 2026-08-16) the tool result carries NO _meta: identity only, on\n // structuredContent + the text block; the mount material lives behind\n // resourceUri via resources/read. A recording that DOES carry the\n // slice (a host or deployment that emits it) is narrated as such.\n const bootstrap = succeeded[0]?.data._meta?.[\"ai.ggui/render\"];\n const carriesSlice = bootstrap !== undefined;\n const structured = succeeded[0]?.data.structuredContent;\n const okText = String(succeeded[0]?.data.content?.[0]?.text ?? \"\");\n // A successful render's first content block is the result JSON, but a host\n // that framed it differently must not red the build with a bare SyntaxError.\n let okResult = null;\n try {\n okResult = JSON.parse(okText);\n } catch {\n okResult = null;\n }\n // Honesty gate (read-plane-only posture): a successful render result MUST carry\n // its identity on structuredContent — under _meta withhold that is the ONLY\n // machine-readable place resourceUri lives, and beat 3's prose says so. A\n // recording where it is missing would narrate a contract the panel refutes.\n if (succeeded.length > 0 && !(structured !== null && typeof structured === \"object\" && typeof structured.resourceUri === \"string\")) {\n throw new Error(\n `showcase-trimly: turn ${n}'s successful render carries no structuredContent.resourceUri — the read-plane-only ` +\n `posture requires the identity there (beat 3 narrates it); check the recording's host framing`\n );\n }\n const carriesOverride = turn.frames.some(\n (f, i) =>\n kinds[i] === \"message:tool.args.assembled:ggui_render\" && f.data.input?.override !== undefined\n );\n const declared = manifest.turns.find((t) => t.n === n);\n if (!declared) {\n throw new Error(`showcase-trimly: the manifest carries no entry for turn ${n}`);\n }\n if (declared.renderAttempts === undefined || declared.refusedRenders === undefined) {\n throw new Error(\n `showcase-trimly: manifest turn ${n} carries no renderAttempts/refusedRenders — it predates ` +\n `the render-count fields; re-run the capture with --remanifest so the counts match the frames`\n );\n }\n if (\n declared.renderAttempts !== counted.renderAttempts ||\n declared.refusedRenders !== counted.refusedRenders\n ) {\n throw new Error(\n `showcase-trimly: manifest turn ${n} declares ${declared.renderAttempts} render attempt(s) / ` +\n `${declared.refusedRenders} refused, the recorded frames show ${counted.renderAttempts} / ${counted.refusedRenders} ` +\n `— the manifest and the capture disagree, so one of them is describing a turn that did not happen`\n );\n }\n if (declared.hasRender !== counted.hasRender || declared.hasUpdate !== counted.hasUpdate) {\n throw new Error(\n `showcase-trimly: manifest turn ${n} declares hasRender=${declared.hasRender} / hasUpdate=${declared.hasUpdate}, ` +\n `the recorded frames show hasRender=${counted.hasRender} / hasUpdate=${counted.hasUpdate} ` +\n `— the page would narrate a call shape the recording does not contain`\n );\n }\n const firstViolation = String(refusals[0]?.data.content?.[0]?.text ?? \"\")\n .split(\"\\n\")\n .find((line) => line.startsWith(\"- \"));\n if (refusals.length > 0 && !firstViolation) {\n throw new Error(\n `showcase-trimly: turn ${n}'s refused render carries no violation text to quote — ` +\n `the page would print an empty quotation where the evidence should be`\n );\n }\n return {\n attempts: counted.renderAttempts,\n refused: counted.refusedRenders,\n succeeded: counted.renderAttempts - counted.refusedRenders,\n hasRender: counted.hasRender,\n hasUpdate: counted.hasUpdate,\n carriesSlice,\n carriesCode: typeof bootstrap?.codeB64 === \"string\",\n carriesOverride,\n cacheKind: okResult?.cache?.kind ?? null,\n cacheHit: okResult?.cache?.hit ?? null,\n firstViolation: firstViolation ? firstViolation.slice(2) : null,\n };\n};\nexport const r1 = renderStats(turn1, 1);\nexport const r2 = renderStats(turn2, 2);\n\n{/* What the handshake negotiated, read off the two frames beat 2's panel\n renders: what the agent's draft asked for, what the server proposed back,\n and which gaps between them it raised. Beat 2 tells that story from these\n values, so the next recording re-narrates itself. */}\nexport const handshakeFacts = (turn) => {\n const kinds = frameKinds(turn.frames);\n const draft = turn.frames.find(\n (_, i) => kinds[i] === \"message:tool.args.assembled:ggui_handshake\"\n )?.data.input?.blueprintDraft?.contract;\n const resultText = String(\n turn.frames.find((_, i) => kinds[i] === \"message:tool.done:ggui_handshake\")?.data.content?.[0]\n ?.text ?? \"\"\n );\n let result = null;\n try {\n result = JSON.parse(resultText);\n } catch {\n result = null;\n }\n const summary = result?.suggestion?.proposedContractSummary ?? null;\n const gaps = (result?.suggestion?.validationFindings ?? []).filter(\n (f) => f.code === \"COVERAGE_GAP\"\n );\n const advice = /Default to [^,]+/.exec(gaps[0]?.message ?? \"\");\n return {\n draftActions: Object.keys(draft?.actionSpec ?? {}),\n action: result?.action ?? null,\n origin: result?.suggestion?.origin ?? null,\n summary,\n gapPaths: gaps.map((f) => f.path),\n gapSeverity: gaps[0]?.severity ?? null,\n advice: advice ? advice[0] : null,\n // The proposal is what the agent accepted whenever it posted no override.\n proposalDeclaresActions: summary === null ? null : !/actions=∅/.test(summary),\n };\n};\nexport const h1 = handshakeFacts(turn1);\nexport const grid1IsReadOnly = !r1.carriesOverride && h1.proposalDeclaresActions === false;\n\n{/* Equal placeholders mean equal ids only when the capture redacted both\n turns through ONE map, which the manifest states as redaction:\"single-map\".\n Absent that stamp — or two session frames that disagree — the shared thread\n is something the rig did, not something these frames evidence. */}\nexport const redaction = manifest.redaction ?? null;\n\n{/* Whether ONE placeholder map spans both turns is provable from the fixtures\n themselves: under one map, turn 2's newly-seen ids continue turn 1's\n numbering; under per-turn maps every kind restarts at _1, so no kind in\n turn 2 could exceed turn 1's maximum. Derived, so the page neither claims\n nor disclaims evidence it has. A manifest stamped redaction:\"single-map\"\n is an additional sufficient proof, not a required one. */}\nexport const placeholderMax = (turn) => {\n const max = new Map();\n JSON.stringify(turn.frames).replace(/\"([a-z_]+)_(\\d+)\"/g, (whole, kind, n) => {\n const v = Number(n);\n if (!max.has(kind) || max.get(kind) < v) max.set(kind, v);\n return whole;\n });\n return max;\n};\nexport const maxTurn1 = placeholderMax(turn1);\nexport const continuing = [...placeholderMax(turn2).entries()].filter(\n ([kind, n]) => n > (maxTurn1.get(kind) ?? 0)\n);\nexport const sharedMap = maxTurn1.size > 0 && continuing.length > 0;\nexport const independentMaps = maxTurn1.size > 0 && continuing.length === 0;\nexport const continuityExamples = continuing\n .map(([kind]) => `${kind}_${(maxTurn1.get(kind) ?? 0) + 1}`)\n .sort()\n .slice(0, 3)\n .join(\", \");\nexport const doneThreadIdOf = (turn) => {\n const kinds = frameKinds(turn.frames);\n const frame = turn.frames.find((_, i) => kinds[i] === \"done\");\n return frame?.data.threadId ?? null;\n};\nexport const threadIdOf = (turn) => {\n const kinds = frameKinds(turn.frames);\n const session = turn.frames.find((_, i) => kinds[i] === \"session\");\n return session?.data.threadId ?? null;\n};\nexport const sameThread = threadIdOf(turn1) !== null && threadIdOf(turn1) === threadIdOf(turn2);\n\n{/* The session-space thread is on screen four times: both `session` frames and\n both `done` frames, which the closing panels already select. */}\nexport const threadOnScreenFourTimes =\n sameThread &&\n [turn1, turn2].every((t) => doneThreadIdOf(t) !== null && doneThreadIdOf(t) === threadIdOf(t));\n\n{/* Two id spaces share the key name `threadId`: the session frame's is the\n platform's durable conversation thread, the AgJSON stream frames carry\n their own per-turn one. Only explain that while the recording actually\n shows both — a wire that later unifies them must not leave a stale note. */}\nexport const streamThreadIdOf = (turn) => {\n const kinds = frameKinds(turn.frames);\n const frame = turn.frames.find((_, i) => kinds[i] === \"message:turn.start\");\n return frame?.data.threadId ?? null;\n};\nexport const twoThreadSpaces = [turn1, turn2].some(\n (t) => streamThreadIdOf(t) !== null && streamThreadIdOf(t) !== threadIdOf(t)\n);\n\n:::note[What you are looking at]\nRecorded **{new Date(manifest.capturedAt).toISOString().slice(0, 10)}** against protocol **{manifest.protocolSchemaVersion}**, from guuey's release-tier demo agent _Trimly_ — a fictional booking SaaS running at {manifest.endpointHost} (app {manifest.agentAppId}). guuey is a separate hosting platform that speaks the GGUI protocol; this page is about the **protocol**, and the frames are the evidence. Ids are stable placeholders; credentials were removed at capture, never recorded.\n:::\n\nTwo turns, one thread, two rendered surfaces. Read the story; open any **On the wire** panel to see exactly what crossed the wire at that beat. Nothing on this page is typed by hand: each panel is read out of the committed recording at build time, and a panel that names a frame the recording does not contain fails the build rather than quietly showing you prose.\n\n## 1 · The ask\n\nA visitor — anonymous, no account — types _\"{turn1.prompt}\"_. The rig behind this recording invoked the agent the way that visitor would: over the host's guest wire, with no sign-in and no bearer token. One POST goes out, and the first frame back is the `session`, which is where that shows up on the wire: `authMode: \"anonymous\"`, a caller id standing in for the guest hash the real exchange carried (placeholdered here like every other id), and the `threadId` that names the durable thread every later turn replays against.\n\n\n\n## 2 · Handshake — the contract, negotiated\n\nBefore any UI exists, the agent calls **`ggui_handshake`** with an _intent_ and a _draft contract_. The draft is the interesting half: the agent describes, in schema, the surface it wants. The server answers with a **proposed** contract, an `action` (here {h1.action}), and an `origin` — `cache` (a similar UI was built before and is reused), `agent` (the draft was already clean), or `synth` (the server repaired it). Open the panel to read the server's rationale: which blueprint it matched, at what confidence, and every coverage gap between the draft and the cached surface.\n\nThe contract is where the protocol's placement rule lives: `actionSpec` = discrete events that drive the agent's next turn, `contextSpec` = observable state the agent reads when it next works, and there is no third category — see [the placement test](/glossary/#contract) and [Envelopes](/protocol/envelopes/).\n\n{h1.draftActions.length > 0 && h1.gapPaths.length > 0 ? (\n\n

\n Watch what the two frames in the panel do with that. This ask wanted an action: the draft declares{\" \"}\n actionSpec.{h1.draftActions[0]} alongside its props. The contract the server proposed —\n reused from a cached blueprint — carries no such thing: {h1.summary}. {h1.gapPaths.length === 1 ? \"The difference comes\" : \"The differences come\"}\n {\" \"}back as {h1.gapPaths.length === 1 ? \"one \" : `${h1.gapPaths.length} `}\n COVERAGE_GAP finding{h1.gapPaths.length === 1 ? \"\" : \"s\"} at {h1.gapSeverity}\n {h1.gapPaths.length > 1 ? <> — {h1.gapPaths.map((p, i) => <>{p}{i < h1.gapPaths.length - 1 ? \", \" : \"\"})} — : \" \"}\n never a veto{h1.advice ? <>, with the server's own counsel attached: \"{h1.advice}\" : null}. The agent\n accepted, so the grid this recording mounted is a read-only card. Re-aiming the contract instead is a\n call the protocol gives it — beat 6 is where that lever appears.\n

\n) : null}\n\n\n\nOne detail the raw frames show and this page smooths over: hosts may namespace MCP tool names. In these recordings the wire name is `mcp__ggui__ggui_handshake`; the protocol name is `ggui_handshake`, and readers of the stream should match on the bare name.\n\n## 3 · Render — and the contract check that refuses a bad one\n\n**`ggui_render`** commits the contract and returns the view's **identity** — not its material. On this host's stream that arrives as a `tool.done` frame carrying the render's JSON both as text and as the result's `structuredContent`: `resourceUri`, the view's durable `ui://` identity; `action`, reporting whether the surface was created or reused; `contractHash`; and a `cache` record. What is deliberately **not** on the wire is the mount material — the bootstrap that boots the runtime and opens the live channel, the compiled component, the theme. A host resolves those by reading `resourceUri` (MCP `resources/read`), the read-plane-only posture: the tool result names the view, the read plane serves it — see [Bootstrap handshake](/protocol/bootstrap-handshake/).\n\nNote what the agent never writes: component code. Its call is `handshakeId` plus `props` — and, when it wants to re-aim the contract it was offered, an `override` — but read the assembled-arguments frame in the panel and you will not find markup, styling, or a component anywhere in it. Authoring the UI is not the agent's job.\n\n{!r1.carriesSlice ? (\n

\n So where is the code? Not in the panel — and that is the point. Under the read-plane-only posture\n the tool result carries no ai.ggui/render slice at all: the host takes the{\" \"}\n resourceUri above to MCP resources/read and receives the shell — the bootstrap\n (which runtime to load, which live channel to open), the compiled component, the theme — from the read\n plane, cached and content-addressed. The agent's stream stays small and identity-shaped; the multi-kilobyte\n material never rides the conversation. It was generated server-side, from the contract; the agent neither\n wrote it nor saw it.\n

\n) : r1.carriesCode ? (\n

\n The code lives in the material coming back. This recording's ai.ggui/render slice hands the\n host a compiled component as codeB64 alongside propsJson and theme —\n that is what makes the view mountable without a second fetch, and it is why the frame in the panel is\n several kilobytes of base64. It was generated server-side, from the contract; the agent neither wrote\n it nor saw it.\n

\n) : (\n

\n In this recording the ai.ggui/render slice carries no codeB64 — open the panel\n to see what it does hand the host, and how the host is expected to resolve the view from it.\n

\n)}\n\nA negotiated contract is enforced, not advised. When the props an agent commits violate the contract it just agreed to, the render is **refused** with a typed error naming the exact offending path, and the agent repairs the call and renders again — no human in the loop. That is the check working, not the agent failing.\n\n{r1.refused > 0 ? (\n\n

\n In this turn the check fired. The panel below carries every render call and result in wire order:\n the {r1.refused === 1 ? \"first result is a refusal\" : `first ${r1.refused} results are refusals`}\n {r1.succeeded > 0\n ? \", and the last is the success\"\n : \", and every call was refused — the surface never mounted\"}. The violation is worth reading in\n full — it names a path and the vocabulary the contract declared:{\" \"}\n {r1.firstViolation}. Other violations take the same shape: a field the contract never\n declared, a string where an object was specified, each reported by path.\n

\n) : (\n

\n In this turn the check had nothing to refuse: the agent's props conformed on the first call. The panel\n below is that single exchange — the call it assembled, and the result it got back.\n

\n)}\n\n\n\n## 4 · The view boots\n\nThe host mounts the material; the runtime inside the frame answers the MCP-Apps `ui/initialize` handshake, posts `ggui:renderer-ready`, and opens the live WebSocket named in the bootstrap. This beat happens **inside the host page**, not on the agent's SSE stream — which is why there is no wire panel here: the recorded stream shows the agent's side only. The exact boot flow and host obligations are specified in [Bootstrap handshake → the boot flow](/protocol/bootstrap-handshake/#the-boot-flow).\n\n## 5 · The gesture (and how a real one arrives)\n\nA surface that declares an action routes a tap this way: the visitor taps, the runtime emits an `ActionEnvelope` on the live channel, and the agent drains it with **`ggui_consume`** and reasons about it on its next turn — see [Envelopes → ActionEnvelope](/protocol/envelopes/#actionenvelope).\n\n{grid1IsReadOnly ? (\n\n

\n This grid declares none. Beat 2's coverage gap is why: the agent asked for an action, the cached\n contract it accepted has no actionSpec at all, so there is nothing here to tap. Whether the live\n demo negotiates you the same read-only card or one with an action is its own handshake's call — this\n page speaks only for the recording. The recording was also made by a script that sent no gesture, so\n no ggui_consume frame exists and nothing on this page claims one does. What the frames do\n show is the end of the turn: the agent hands control back with a next step, offering to take the\n conversation further.\n

\n) : (\n

\n This recording was made by a script that sent no gesture, so there is no ggui_consume frame\n to show and nothing here claims one happened. What the frames do show is the end of the turn: the agent\n hands control back with a next step, offering to take the conversation further.\n

\n)}\n\n\n\n## 6 · Turn 2 — a second ask on the same thread\n\n_\"{turn2.prompt}\"_ The invoke carries the `threadId` learned in beat 1, so the agent has the whole conversation. The panel below opens turn 2 with its own `session` frame — {sameThread && sharedMap ? (<>naming the same {threadIdOf(turn2)} you read in beat 1, and the numbering is what makes that evidence rather than coincidence: one placeholder map spans the whole recording, so turn 2's ids continue turn 1's instead of restarting at _1 ({continuityExamples}). Equal placeholders therefore mean equal ids{threadOnScreenFourTimes ? <>, and this thread is on screen four times across the panels on this page — both session frames and both done frames, all agreeing : null}) : sameThread && redaction === \"single-map\" ? (<>naming the same {threadIdOf(turn2)} you read in beat 1, which this capture stamps as redacted through one placeholder map (redaction: \"single-map\"), so equal placeholders mean equal ids) : independentMaps ? (<>the rig replayed the threadId it learned in turn 1; this recording's turns were redacted through independent maps, each restarting at _1, so equal placeholders are not evidence of it here) : (<>the rig replayed the threadId it learned in turn 1)}. The handshake that follows it negotiates a contract for the new ask.\n\n\n\n{twoThreadSpaces ? (\n\n

\n One caution if you open the raw fixtures: two different id spaces share the key name{\" \"}\n threadId. The session frame's is the platform's durable conversation thread —\n the one a replayed turn rejoins, and the one every claim on this page is about. The message-stream\n frames (turn.start, message.start) carry the AgJSON stream's own per-turn\n thread id under the same key: {streamThreadIdOf(turn1)} in turn 1 and{\" \"}\n {streamThreadIdOf(turn2)} in turn 2, neither of them{\" \"}\n {threadIdOf(turn1)}. Different spaces, same spelling; compare session frames to session\n frames.\n

\n) : null}\n\n{r2.hasUpdate ? (\n\n <>\n

This recording mutates the mounted surface. The agent called ggui_update: the props were swapped and fanned out to the live view, plus a new history card and an advanced epoch. No fresh ggui_render, so the view is never replaced. See the callout below for how that differs from ggui_amend.

\n \n \n) : r2.hasRender ? (\n <>\n

This recording shows a second render. The agent negotiated again — a second ggui_handshake on the same thread — and rendered a fresh comparison surface. That is a legitimate choice for a different surface: a two-option slot comparison is not the week grid. The contract check from beat 3 applies here too.

\n {r2.refused > 0 ? (\n

The panel is again in wire order: the {r2.refused === 1 ? \"first result is a refusal\" : `first ${r2.refused} results are refusals`}{r2.succeeded > 0 ? \", the last is the success\" : \", and every call was refused — this surface never mounted\"}.

\n ) : (\n

This time nothing was refused — the agent's props conformed on the first call, so the panel holds one call and one successful result. Beat 3 is where you can see the check turn a call back.

\n )}\n \n {r2.carriesOverride ? (\n

\n This render call carries a third field{!r1.carriesOverride ? \" the turn-1 call did not\" : \"\"}:{\" \"}\n override. That is\n step 3 of the handshake — the agent takes the proposed contract as a starting point and re-aims\n it, posting the contract it actually wants (open override.contract in the panel).\n An override re-resolves the render's effective identity{r2.cacheHit === false ? (\n <>, so the server had nothing stored under it: this render reports cache: {\"{\"}hit: false, kind: \"{r2.cacheKind}\"{\"}\"} and the component was generated fresh\n ) : r2.cacheHit === true ? (\n <>, and this one still landed on something stored: cache: {\"{\"}hit: true, kind: \"{r2.cacheKind}\"{\"}\"}\n ) : null}\n {!r1.carriesOverride && r1.cacheHit === true\n ? ` — where turn 1, which posted no override and accepted the proposal as-is, reused a stored blueprint (${r1.cacheKind})`\n : \"\"}\n . Reuse is the reward for accepting a proposal; re-aiming it can cost a generation, and the agent\n gets to decide which it wants.\n

\n ) : null}\n \n \n) : (\n

In this recording turn 2 was answered in prose — the agent judged no new surface was needed. The frames below are the turn as recorded. Mutating an already-mounted view is a different call, ggui_amend (or ggui_update, which also mints a history card and advances the epoch); both fan out as a props_update on the live channel, and this recording does not exercise either.

\n)}\n\n\n\n## 7 · What a conforming implementation had to do\n\nAt each beat above, an implementation either did the specified thing or the turn would not have completed: answered the handshake with a conforming contract (beat 2), validated the committed props against that contract before mounting anything (beat 3), returned a durable identity the host resolves to mount material through the read plane (beat 3), booted and negotiated inside the frame (beat 4), and — for a surface that declares an action — would route a gesture back as an `ActionEnvelope` (beat 5).\n\n{r1.refused + r2.refused > 0 ? (\n\n

\n Validation is the one of those you can watch happen rather than take on faith:{\" \"}\n {r1.refused + r2.refused === 1 ? \"one call in this recording was\" : `${r1.refused + r2.refused} calls in this recording were`}{\" \"}\n refused for violating the contract\n {(() => {\n const repaired = [\n r1.refused > 0 && r1.succeeded > 0 ? \"beat 3's panel\" : null,\n r2.refused > 0 && r2.succeeded > 0 ? \"beat 6's panel\" : null,\n ].filter(Boolean);\n if (repaired.length === 0) return \", and no repaired call followed — the refused surface never mounted\";\n if (repaired.length === 1) return `, and the repair that followed is in ${repaired[0]}, one frame later`;\n return `, and the repairs that followed are in ${repaired.join(\" and \")}, each one frame later`;\n })()}.\n

\n) : (\n

\n No call was refused anywhere in this recording — every render conformed on its first attempt, so\n validation is the one obligation above that you have to take on faith here. Beat 3 describes the shape\n a refusal takes when it happens.\n

\n)}\n\nThe arbiter of \"conforming\" is not this page — it is the [conformance kit](/protocol/conformance/); the fixtures behind these panels are the kind of input it runs.\n\n## 8 · Run it yourself, check yours\n\n- **See it live:** [guuey.com/demos/scheduler](https://guuey.com/demos/scheduler) — run the same ask and watch a negotiation of your own.\n- **Check your implementation:** take the recording itself — [turn 1](/showcase/trimly/turn-1.frames.json), [turn 2](/showcase/trimly/turn-2.frames.json), and its [manifest](/showcase/trimly/manifest.json) — and feed the frames to your host or server as fixtures. They are the same files these panels are built from, ids placeholdered, nothing else altered.\n- **Build your own agent on the protocol:** [Build an agent on hosted GGUI](/quickstart/hosted-agent/) or [self-host](/quickstart/self-hosted/).\n\n"},{"path":"/protocol/version-policy.md","title":"Version policy","description":"Major / minor / patch semantics for the GGUI protocol, deprecation timeline, support matrix, and CI enforcement.","body":"---\ntitle: Version policy\ndescription: Major / minor / patch semantics for the GGUI protocol, deprecation timeline, support matrix, and CI enforcement.\n---\n\n> **Semver promise:** a change to `@ggui-ai/protocol` is breaking if-and-only-if a consumer built against the prior version now fails the conformance kit.\n\nThis page defines \"major\", \"minor\", and \"patch\" on the GGUI protocol, how deprecation windows work, which server ↔ client pairs are supported, and how a breaking change is migrated.\n\nThe canonical version constant is `PROTOCOL_SCHEMA_VERSION` (an alias of `PROTOCOL_VERSION` in [`@ggui-ai/protocol`](https://github.com/ggui-ai/ggui/blob/main/packages/protocol/src/version.ts)). Current value: `draft-2026-09-10`. Wire-level negotiation runs through the schema-version handshake; mismatches surface as the `UPGRADE_REQUIRED` error. The current server default is `versionPolicy: 'reject'` — on mismatch the server emits `UPGRADE_REQUIRED` and closes the connection; `'advisory'` is a legacy opt-out that keeps it open.\n\n---\n\n## 1. Semver semantics applied to the protocol\n\nThe protocol follows semver. What counts as each bump kind is defined by the **conformance kit** ([`packages/protocol-conformance`](https://github.com/ggui-ai/ggui/tree/main/packages/protocol-conformance)), not by surface-syntax changes in the `@ggui-ai/protocol` package.\n\n### Major (N → N+1)\n\nA bump is **major** iff at least one conformance-kit fixture that passed against version N now fails against version N+1 when the only change is the protocol version.\n\nExamples of changes that are major:\n\n- Renaming a **reserved channel** (e.g., `_ggui:preview` → `_ggui:assembly`).\n- Removing a canonical live-channel error code that the kit asserts (e.g., deleting `CONTRACT_VIOLATION`).\n- **Narrowing** an extensibly-closed union (e.g., collapsing `SubmitActionKind` variants so previously-recognized kinds now fail validation).\n- Changing the shape of an **envelope** (`ActionEnvelope`, `StreamEnvelope`) in a way that invalidates fixtures emitted by prior-version producers — required-field additions, required-field renames, required-field type changes.\n- Tightening a `MUST` / `MUST NOT` clause in the spec such that prior-conformant implementations become non-conformant.\n- Changing handshake semantics in a way that rejects a subscribe that would previously have succeeded (e.g., the `versionPolicy` default flip `advisory` → `reject` — already shipped on 2026-04-24 as a pre-launch config-default change with its own release note; post-v1.0, a flip of this shape is major).\n- Removing or replacing a **transport binding** previously declared conformant.\n\n### Minor (N.x → N.(x+1))\n\nA bump is **minor** iff every conformance-kit fixture that passed against N.x still passes against N.(x+1), and the delta is additive.\n\nExamples of changes that are minor:\n\n- Adding a new **`channel_error` code** literal (consumers that don't recognize it degrade per the extensibly-closed union rule).\n- Adding a new **observability event kind** to the renderer's `ggui:observe` postMessage union (extensibly-closed — see the [Bootstrap handshake](/protocol/bootstrap-handshake/) page).\n- Adding an **optional field** on an envelope. Pre-existing consumers see `undefined` and MUST behave as before.\n- Adding a new **reserved channel** whose absence is not a failure mode for prior-version consumers.\n- Adding a new **canonical live-channel error code** (the `code` field is typed open).\n- Adding a new **transport binding** (e.g., stdio MCP, HTTP long-poll) while keeping WebSocket canonical.\n\n### Patch (N.x.y → N.x.(y+1))\n\nA bump is **patch** iff the only changes are documentation clarifications, fixture additions that do not change assertions on prior-version consumers, or internal implementation adjustments to first-party packages that do not affect the wire or the kit.\n\nExamples:\n\n- Spec prose clarifications that close a reader-ambiguity without changing obligations.\n- New conformance-kit fixtures that assert behavior already required by the prior version's spec text.\n- Bug fixes in first-party servers / clients that bring them back into conformance (the bar was always there — the code now honors it).\n\n### The `draft-` prefix\n\nPre-v1 versions use a `draft-` prefix (e.g., `draft-2026-06-12`). While `draft-`, the semver rules above describe **intent**, not **obligation** — the protocol reserves the right to ship breaking changes without a migration doc until the first stable release tags `v1.0`.\n\n**Rule flip at v1.0:** once `PROTOCOL_SCHEMA_VERSION` drops the `draft-` prefix, every major bump MUST have a migration doc (CI-enforced) and every deprecation MUST honor the window described in §3.\n\n---\n\n## 2. Breaking change definition — the kit is the arbiter\n\n> **A change is breaking if-and-only-if a consumer built against the prior version now fails the conformance kit.**\n\nAnchor every future \"is this breaking?\" debate to a kit run. Opinion, intent, and prose-level spec reading are NOT the arbiter — the kit is.\n\nOperational consequences:\n\n1. If you're unsure whether a PR is breaking, **run the kit** against the prior-version tag and against the PR branch. If fixtures that passed before now fail, the PR is major.\n2. If the kit passes but you \"feel\" the change is risky, **add a fixture** that captures the worry. Either the fixture passes (the change is not breaking) or it fails (the change is breaking and you just found out) — both outcomes are productive.\n3. If you think a change is major but the kit disagrees, the kit has a gap. Patch the kit in the same PR; the patched kit decides.\n\nThis anchor means every change's breaking-ness is **observable and reproducible**, not a matter of taste.\n\n---\n\n## 3. Deprecation timeline\n\nDeprecation is the only graceful path from a minor-version ship to a major-version removal.\n\n### The window\n\n- **v(N)** — the version in which a surface is first tagged `@deprecated` (in TSDoc) AND documented in the release notes as deprecated. The surface MUST continue to work identically to the prior version; `@deprecated` is a signal to consumers, not a behavior change.\n- **v(N+1)** — deprecated surface still works. Callers SHOULD migrate in this window. Release notes repeat the deprecation warning.\n- **v(N+2)** — removal is allowed here at the earliest. Removal is a major bump, so this version is v(N+2) = major. The two-minor window guarantees consumers saw at least one full minor cycle with the `@deprecated` warning before removal.\n\n### Minimum\n\n**At least two minor versions MUST elapse between `@deprecated` and removal.** If N is the first deprecated version and N+2 is the major that removes it, the intermediate v(N+1) minor MUST ship. Shorter windows (v(N) deprecated → v(N+1) removed) are NOT allowed for non-security changes.\n\n### Security-fix escape hatch\n\nA **critical security fix** MAY skip the window — shipping a breaking change without a prior `@deprecated` minor — if and only if:\n\n1. The release note explicitly names the CVE or security class.\n2. The release note explains why the window was skipped.\n3. A migration doc per §5 ships alongside the release.\n\nNon-security urgency (e.g., \"this mistake is embarrassing\") is NOT grounds for skipping the window.\n\n### What \"deprecated\" means on the wire\n\nThe protocol does not have a wire-level \"deprecated field\" marker. Deprecation lives in TSDoc on the `@ggui-ai/protocol` types and in the release notes. Consumers parsing the wire cannot detect a field is `@deprecated` from the frame alone — they learn it from the package changelog.\n\n### Policy-default flips count as breaking\n\nChanging a **default** that the wire handshake depends on is breaking under §2 because consumers that relied on the prior default observably fail against the new default. The canonical example already happened pre-launch: the `versionPolicy` default flip `advisory` → `reject` shipped on 2026-04-24 as a config-default change with its own release note. Post-v1.0, a flip of that shape MUST use the same window: ship the new value as an opt-in in v(N), document the flip in the release notes, then flip the default in v(N+2).\n\n---\n\n## 4. Version support matrix\n\nWhich server versions support which client versions. Populated at launch (v1.0); the row below is illustrative — the protocol is pre-v1 (`draft-2026-09-10`) today:\n\n| Server `PROTOCOL_SCHEMA_VERSION` | Min client | Max client | Status | EOL date |\n| -------------------------------- | ---------- | ---------- | ------------------------ | -------- |\n| _`1.0.x`_ | _`1.0.0`_ | _`1.0.x`_ | _current (illustrative)_ | — |\n\n### Column meanings\n\n- **Server version** — the `PROTOCOL_SCHEMA_VERSION` the server emits in the subscribe-ack payload's `serverVersion`.\n- **Min client / Max client** — the lowest / highest entries in the client's `CLIENT_SUPPORTED_VERSIONS` set guaranteed to subscribe successfully.\n- **Status** — one of:\n - `current` — actively maintained; all fixes land here.\n - `security-only` — no new features; only security patches.\n - `EOL` — no longer maintained. Servers on EOL versions MAY refuse to start.\n- **EOL date** — the date `current` transitions to `security-only`, or `security-only` transitions to EOL.\n\n### Matrix update cadence\n\n- New **minor** ship → append a row; prior row may update Max client.\n- New **major** ship → append a new row; prior-major row transitions to `security-only` for at least 6 months before EOL.\n- Security-only → EOL → at least 6 additional months.\n\n### Out-of-matrix clients\n\nIf a client targets a version outside the matrix, the server emits `UPGRADE_REQUIRED`. Whether the connection stays open depends on the server's `versionPolicy` at the time.\n\n---\n\n## 5. Migration-guide requirement\n\nEvery major bump MUST ship a migration doc at `docs/protocol/migrations/v-to-v.md`. (Current pre-v1 drafts use date-named migration docs — e.g. `2026-06-05-gguisession-reintroduction.md`; the `v-to-v.md` pattern applies from v1.0.) The CI check (§7) enforces the file's existence; content follows a standard template with required sections:\n\n- **What changed** — 1–2 paragraph summary.\n- **Why** — motivation (conformance-kit failure mode that drove the change).\n- **Breaking-change summary** — bullet list of renamed / removed / tightened surfaces.\n- **Migration steps per consumer kind** — fixture authors, ConformanceHost implementers, agent builders, SDK consumers.\n- **Timeline** — dates for v(N) deprecation ship, v(N+1) soft cut, v(N+2) removal.\n- **Rollback procedure** — how to pin to prior version if a consumer can't migrate fast enough.\n\n---\n\n## 6. Release cadence expectations\n\nThese are targets, not promises:\n\n- **Minor (N.x → N.(x+1)):** roughly monthly. Additive adjustments driven by conformance-kit fixture gaps, new observability events, or new canonical error codes tend to accumulate on this cadence. Empty minor cycles are skipped rather than force-shipped.\n- **Major (N → N+1):** annual or slower. Rare and pre-announced. A major ship is a disruption event for every downstream — the protocol leans hard on minor + deprecation windows to defer majors.\n- **Patch (N.x.y → N.x.(y+1)):** ad hoc. Doc corrections, fixture additions that tighten existing assertions, and first-party impl bug fixes ship when ready.\n\nAnnouncements ship in the version history maintained in [`@ggui-ai/protocol`'s `version.ts`](https://github.com/ggui-ai/ggui/blob/main/packages/protocol/src/version.ts) and in the public protocol release notes.\n\n---\n\n## 7. CI enforcement\n\nTwo workflows guard this policy:\n\n- **Spec drift** — ensures spec envelope code blocks match the `@ggui-ai/protocol` types. Catches structural drift that would otherwise ship as silent breakage.\n- **Version migration** — reads `PROTOCOL_SCHEMA_VERSION` on the PR head and on the base ref; if the **major** component changed, asserts the migration doc exists in the PR diff.\n\nThe second check is the policy's teeth: you cannot ship a major bump without the migration doc the policy requires.\n\n---\n\n## Appendix: Worked examples\n\n### A.1 Adding a new live-channel error code\n\n**Scenario:** a new failure mode — `TOOL_DENIED` — needs to land alongside the existing canonical literals on the WS `error` / `channel_error` frame.\n\n- **Bump kind:** minor. Prior-version consumers that don't know `TOOL_DENIED` see an extensibly-closed (`code: string`) value and MUST degrade gracefully. No kit fixture asserting the prior closed set should fail.\n- **Required work:** add the constant to `@ggui-ai/protocol`, document it as a canonical live-channel error-code literal, add a conformance-kit fixture asserting the new code round-trips.\n- **Migration doc:** none needed (not a major bump).\n\n### A.2 Removing a canonical error-code literal\n\n**Scenario:** `SCHEMA_MISMATCH_ERROR` is merged into `CONTRACT_VIOLATION` with a structured `causedBy`.\n\n- **Bump kind:** major. A consumer that pattern-matches on `SCHEMA_MISMATCH_ERROR` now never sees it, fails its fixture.\n- **Required work:** first ship `@deprecated SCHEMA_MISMATCH_ERROR` in v(N), continue emitting both `SCHEMA_MISMATCH_ERROR` and the new shape during v(N+1), then remove `SCHEMA_MISMATCH_ERROR` emission in v(N+2).\n- **Migration doc:** `vN-to-v(N+1).md` (enforced by CI on the major-bump PR). Covers the `causedBy` shape, fixture changes, and consumer-side pattern-match migration.\n\n### A.3 Renaming a reserved channel\n\n**Scenario:** `_ggui:preview` → `_ggui:assembly` for parity with transport-layer conventions.\n\n- **Bump kind:** major. Every consumer that subscribes to the old name now fails. Every fixture that references the old name needs updating.\n- **Required work:** can NOT ship via deprecation (reserved-channel names are matched verbatim). Must bundle with other breaking changes into the next major. Migration doc is non-trivial — every producer AND consumer changes.\n- **Operational note:** changes of this shape are exactly why the protocol prefers extensibly-closed unions + additive fields + separate channels over in-place renames.\n\n### A.4 Clarifying a spec MUST\n\n**Scenario:** the spec's `refresh` semantics paragraph has two readings; the kit's fixture matched only one.\n\n- **Bump kind:** patch IF the kit's existing assertion already covered the intended reading (prose clarifies code); minor IF the clarification surfaces a new required behavior that prior-version impls weren't necessarily honoring (new assertion); major IF the clarification tightens behavior such that previously-conformant impls now fail.\n- **Test:** run the kit against the prior-version tag. If it passes, the clarification is patch/minor. If it fails, it was major all along — the original spec text was ambiguous and shipping the clarification is a breaking change.\n\n---\n\n## See also\n\n- [Protocol overview](/protocol/overview/) — three-channel topology and reference implementation.\n- [Conformance kit](https://github.com/ggui-ai/ggui/tree/main/packages/protocol-conformance) — the test suite this policy treats as the arbiter.\n- [Conformance](/protocol/conformance/) — the 4-criteria contract bar + 6-criteria protocol bar this policy gates."},{"path":"/quickstart/claude-desktop.md","title":"Use GGUI in Claude Desktop","description":"Connect Claude Desktop to hosted GGUI and get generated UI in your chats in about three minutes — no code, no infrastructure.","body":"---\ntitle: Use GGUI in Claude Desktop\ndescription: Connect Claude Desktop to hosted GGUI and get generated UI in your chats in about three minutes — no code, no infrastructure.\n---\n\nClaude answers in text. With GGUI connected, it can answer with a real interface — a form, a table, a picker — right inside the chat. Setup takes about three minutes and never leaves your browser and Claude Desktop. You don't write any code and you don't open a terminal.\n\n## Step 1: Create your GGUI account\n\nGo to [console.ggui.ai](https://console.ggui.ai) and sign in with Google, GitHub, or email. That is your whole signup.\n\nNew accounts start with a **one-time welcome credit** while it is available — no card — and render on it at the published per-render rates; the amount and the rates are on [ggui.ai/pricing](https://ggui.ai/pricing). When it is spent, top up on the console's credits page or bring your own provider key — see [Credits, billing & BYOK](/hosted/billing/).\n\n## Step 2: Add GGUI to Claude Desktop\n\nIn Claude Desktop, open **Settings → Connectors → Add custom connector**, and paste this address:\n\n```\nhttps://mcp.ggui.ai\n```\n\nLeave the authentication fields blank, then save. Claude handles the sign-in for you on first use.\n\n## Step 3: Approve the connection\n\nThe first time Claude uses GGUI — or as soon as you click **Connect** on the new connector card — a browser window opens on the GGUI console.\n\n1. Sign in with the same account you created in Step 1.\n2. Click **Approve**.\n\nThe console creates the access key for you and hands it to Claude Desktop automatically. There is nothing to copy and nothing to paste. The browser window closes on its own, and the connector card shows as connected.\n\nYou can see that key later on [the connector keys page](/hosted/connector-keys/). Revoking one is a command-line step for now, and that page walks through it.\n\n## Step 4: Ask for something you'd rather click than type\n\nOpen a new chat and ask for something that wants an interface. For example:\n\n> Plan my week — give me a form to rank these five tasks: inbox triage, dentist, Q3 draft, gym, call Mum.\n\nClaude decides an interface is the better answer, asks GGUI to build one, and the form appears inline in the chat. It is generated for that request, not picked from a template library, so the first one takes a while: tens of seconds, not instant. Leave it running; asking for the same kind of thing again later is much faster, because GGUI reuses what it built.\n\n**Text instead of a card?** If Claude answered in plain words, ask again and name the interface (\"show it as a form\"). If it called GGUI and still no card appears, check that the connector card shows as connected and that Claude Desktop is up to date: a card needs a host that can mount it. [Troubleshooting](/clients/claude-desktop/#troubleshooting) covers the rest.\n\n## Step 5: Use it, and let Claude read your answer\n\nDrag the rows, tick the boxes, hit submit. Your input travels straight back to Claude as structured data, exactly as if you had typed it out — so Claude can act on it in the very next message.\n\nAsk for a variation and you get a new interface. Ask for the same kind of thing again later and it comes back faster, because GGUI reuses what it built the first time.\n\n:::note[Running your own server instead?]\nEverything above uses hosted GGUI at `mcp.ggui.ai`. If you would rather run the server yourself, on your own machine and your own model key, start with the [Self-hosted quickstart](/quickstart/self-hosted/).\n:::\n\n## Where to next\n\n- **[Todos playground](/hosted/playgrounds/todos/)** — a live surface to try; one more connector to add, same three-minute ceremony.\n- **[Build an agent on hosted GGUI](/quickstart/hosted-agent/)** — put generated UI in front of your own users, in your own agent.\n- **[The GGUI console](/hosted/console/)** — manage your keys, credits, and apps.\n- **[Claude Desktop reference](/clients/claude-desktop/)** — other hosts, disconnecting, and what to do if nothing renders.\n- **[Trust & security](/hosted/trust/)** — what GGUI stores, what reaches a model, and how to delete your account."},{"path":"/quickstart/hosted-agent.md","title":"Build an agent on hosted GGUI","description":"Ship your first agent UI against hosted GGUI (mcp.ggui.ai) in under 5 minutes — no infrastructure required.","body":"---\ntitle: Build an agent on hosted GGUI\ndescription: Ship your first agent UI against hosted GGUI (mcp.ggui.ai) in under 5 minutes — no infrastructure required.\n---\n\nNew accounts start with a **one-time welcome credit** while it is available — no card — and render on it at the published per-render rates (the amount and the rates are on [ggui.ai/pricing](https://ggui.ai/pricing)). When it is spent, top up on the console's credits page, or bring your own provider key — see [Credits, billing & BYOK](/hosted/billing/).\n\n:::tip[Zero-wrapper architecture]\nGGUI has **no client SDK wrapper**. Your agent talks to `mcp.ggui.ai` directly over MCP — either via the Claude Agent SDK's native `mcpServers` config (Pattern A below) or via `@modelcontextprotocol/sdk` for any other LLM. See [the Claude agent example](/examples/claude-agent/) for the canonical reference implementation.\n:::\n\nIn 5 minutes, your agent will negotiate a UI contract and put a generated form on the wire as an MCP-Apps resource — no React code, no front-end build, no infrastructure.\n\nOne thing to know before you start, because it shapes what you see at the end: a render is a resource, not a URL, and something has to **mount** it before a human can fill it in. That something is an MCP-Apps host. Run this agent programmatically with no host attached and it will block at `ggui_consume`, waiting on a render nobody can see — correct behavior, but not a finished demo. The fastest way to watch the whole loop close is to run the same prompt inside Claude Desktop connected to GGUI ([three-minute setup](/quickstart/claude-desktop/), zero code); this page is the programmatic path that gets your own agent onto the same wire.\n\n```\nYour Agent → mcp.ggui.ai → MCP-Apps render (ui://ggui/render/) → User submits → Agent gets typed data\n```\n\n## Prerequisites\n\n- **Node.js** 20+\n- **A free GGUI console account.** Sign in at [the GGUI console](https://console.ggui.ai) with Google, GitHub, or email. (The GGUI console is the end-user dashboard for hosted GGUI — see the [glossary](/glossary/) if the `ggui` / `guuey` split confuses you.)\n\n## Step 1: Pick an app and mint an SDK API key\n\n1. Sign in at [the GGUI console](https://console.ggui.ai). You land on `/apps` — new accounts come pre-provisioned with one default app; create another with **New App** if you want to scope this quickstart to its own surface (e.g. `feedback-demo`).\n2. Open the app and go to **Keys** (`/apps/[appId]/keys`). Name the key (e.g. `feedback-demo-sdk`) and click **Generate per-app key**.\n3. The key reveals exactly once — **copy it (`ggui_user_…`) immediately.** Lose it and you generate a new one; there's no recovery. You also need the app's ID: it is an opaque 8-character string with no prefix, and the app's overview page shows the full endpoint, `mcp.ggui.ai/apps/`, ready to copy.\n\n:::caution\nNever commit `ggui_user_*` keys. Use `.env` files and a secret manager in production.\n:::\n\n:::tip[Prefer the CLI?]\n`ggui keys create --name feedback-demo-sdk` does the same thing from your terminal once you've run [`ggui login`](/cli/login/). The minted key still lands as one row in the console's keys table.\n:::\n\n## Step 2: Install the dependencies\n\n```bash\nnpm install @anthropic-ai/claude-agent-sdk @ggui-ai/protocol\n# or: pnpm add @anthropic-ai/claude-agent-sdk @ggui-ai/protocol\n# or: yarn add @anthropic-ai/claude-agent-sdk @ggui-ai/protocol\n```\n\n- **`@anthropic-ai/claude-agent-sdk`** runs Claude as a tool-using agent and speaks MCP natively — no wrapper needed.\n- **`@ggui-ai/protocol`** exports `GGUI_AGENT_SYSTEM_PROMPT`, the canonical system prompt that teaches Claude the handshake → render → consume loop.\n\n:::tip[Other LLMs]\nNot using Claude? Use the raw [`@modelcontextprotocol/sdk`](https://github.com/modelcontextprotocol/typescript-sdk) instead — see [`/examples/generic-mcp/`](/examples/generic-mcp/) for the low-level pattern, and [`/examples/openai-agent/`](/examples/openai-agent/) / [`/examples/gemini-agent/`](/examples/gemini-agent/) for vendor-specific wiring.\n:::\n\n## Step 3: Write your agent\n\nCreate `agent.ts`. The Claude Agent SDK connects to `mcp.ggui.ai` directly via its `mcpServers` config — your code just streams Claude's messages and lets the model drive the GGUI tools.\n\n```typescript\nimport { query } from \"@anthropic-ai/claude-agent-sdk\";\nimport { GGUI_AGENT_SYSTEM_PROMPT } from \"@ggui-ai/protocol\";\n\n// 1. Point Claude's MCP client at your app's hosted endpoint. Bearer-auth\n// with the `ggui_user_*` key you minted in Step 1. Note: the per-app\n// cloud endpoint is the bare `/apps/` path — NO `/mcp` suffix\n// (that suffix is local-`ggui serve`-only).\nconst mcpServers = {\n ggui: {\n type: \"http\" as const,\n url: \"https://mcp.ggui.ai/apps/\",\n headers: { Authorization: `Bearer ${process.env.GGUI_MCP_BEARER!}` },\n },\n};\n\n// 2. Allow Claude to call every ggui tool. The `mcp____`\n// naming is the SDK's convention — `` = `ggui` (the key above).\nconst allowedTools = [\n \"mcp__ggui__ggui_handshake\",\n \"mcp__ggui__ggui_render\",\n \"mcp__ggui__ggui_update\",\n \"mcp__ggui__ggui_amend\",\n \"mcp__ggui__ggui_emit\",\n \"mcp__ggui__ggui_consume\",\n \"mcp__ggui__ggui_get_session\",\n];\n\nasync function main() {\n const prompt =\n \"Collect product feedback from the user. Show a feedback form with a \" +\n \"1-5 star rating and a comments text area, wait for them to submit, \" +\n \"then summarize what they said.\";\n\n // 3. Stream the conversation. Claude reads GGUI_AGENT_SYSTEM_PROMPT,\n // decides when to call ggui_handshake / ggui_render,\n // polls ggui_consume until the user submits, and reports back —\n // all without any wrapper SDK on your side.\n for await (const msg of query({\n prompt,\n options: {\n mcpServers,\n allowedTools,\n systemPrompt: GGUI_AGENT_SYSTEM_PROMPT,\n },\n })) {\n if (msg.type === \"assistant\") {\n for (const block of msg.message.content) {\n if (block.type === \"text\") console.log(block.text);\n }\n } else if (msg.type === \"result\") {\n console.log(\"Done:\", msg.subtype);\n }\n }\n}\n\nmain().catch(console.error);\n```\n\n## Step 4: Run it\n\n```bash\nexport ANTHROPIC_API_KEY=\"sk-ant-...\" # for the Claude Agent SDK\nexport GGUI_MCP_BEARER=\"ggui_user_...\" # for mcp.ggui.ai\nnpx tsx agent.ts\n```\n\nYou'll see Claude narrate the handshake, call `ggui_render` (which returns `{ sessionId, resourceUri }` — the render surfaces as an MCP-Apps resource at `ui://ggui/render/`, not a clickable link), and then **block on `ggui_consume`**, polling for the user's submission.\n\nThat block is the expected end of the programmatic path: the render exists, and nothing is mounting it. Two ways to close the loop, easiest first:\n\n- **Run the prompt in an MCP-Apps host** — no code at all. Claude Desktop or claude.ai connected to GGUI mounts the resource inline, you submit, and the agent's `ggui_consume` returns. Setup is three minutes: [Use GGUI in Claude Desktop](/quickstart/claude-desktop/).\n- **Embed it in your own app** — Step 5 below mounts the render with the React host helpers. More wiring, and the right answer once you are putting this in front of your own users.\n\n:::note[How this differs from a wrapper SDK]\nThere is no `GguiClient` import, no `await ggui.handshake(…)`, no `waitForCompletion` helper. The Claude Agent SDK calls the GGUI MCP tools directly; `GGUI_AGENT_SYSTEM_PROMPT` is what teaches the model the protocol's handshake → render → consume sequence. Same wire protocol, zero wrapper code.\n:::\n\n## Step 5 (optional): Embed in React\n\nWant the UI inside your own app? Install the React host helpers and the MCP-Apps host:\n\n```bash\nnpm install @ggui-ai/mcp-apps-react @mcp-ui/client\n```\n\nA GGUI render is an **MCP-Apps resource**. You drive the conversation with the `useMcpAppsChat` hook and mount each render's sandboxed iframe with `` (imported directly from `@mcp-ui/client` — GGUI doesn't re-export it):\n\n```tsx\nimport { AppRenderer } from \"@mcp-ui/client\";\nimport { useMcpAppsChat } from \"@ggui-ai/mcp-apps-react/chat-helpers\";\n\nfunction Chat({ agentUrl }: { agentUrl: string }) {\n const { entries, sessions, send, handleAppMessage } = useMcpAppsChat({\n chatEndpoint: `${agentUrl}/agent`,\n });\n\n // - render `entries` as chat bubbles; call `send(prompt)` to talk to the agent\n // - mount each `sessions` entry with — it needs a sandbox-proxy\n // origin + onReadResource / onCallTool relay + onMessage={handleAppMessage}\n}\n```\n\n`useMcpAppsChat` talks to your **agent backend** (the process running the Step-3 `query()` loop, exposed over HTTP — `@ggui-ai/agent-server` gives you a brand-neutral `POST /agent` endpoint for exactly this). ``'s sandbox + resource-read + tool-call relay wiring is non-trivial; the complete runnable reference is the [`ggui-basic-web`](https://github.com/ggui-ai/ggui/tree/main/samples/apps/ggui-basic-web) sample. **Start there.**\n\n:::note[The render hosts its own live channel]\nYou don't open a WebSocket in your app to receive render updates. The sandboxed iframe owns its own live channel; your host code just mounts ``. Real-time updates (see [Real-Time Dashboard](/cookbook/real-time-dashboard/)) flow inside the iframe.\n:::\n\n## What just happened\n\nUnder the hood, Claude drove these MCP tool calls against `mcp.ggui.ai`:\n\n1. **`ggui_handshake`** negotiated a **contract** from a natural-language intent + draft, returning a `handshakeId` + a server suggestion (cache / agent / synth).\n2. **`ggui_render`** with `{ handshakeId, props }` materialized the contract: GGUI matched a cached **blueprint** (or synthesized a fresh React component), minted a `sessionId`, and returned `{ sessionId, resourceUri }` — the render is an MCP-Apps resource at `ui://ggui/render/`, surfaced on the tool result's `_meta.ui.resourceUri`. (There is no clickable URL on the wire.)\n3. A host mounted that resource — your app via `` (Step 5), or an MCP-Apps host like claude.ai inline — and the user submitted the form.\n4. **`ggui_consume`** delivered the user's submit gesture as a `ConsumeEventEntry` (`{ intent, actionData, uiContext, ... }`).\n\nThere is no terminal `close` ceremony — a render simply stays reopenable (see [Rehydration](/concepts/rehydration/)). There is no per-render time limit.\n\nEverything above the wire is `GGUI_AGENT_SYSTEM_PROMPT` + the Claude Agent SDK's tool loop — no ggui-specific client code on your side.\n\n```\nAgent mcp.ggui.ai MCP-Apps host\n │ │ (your app / claude.ai)\n │── handshake ───────────→ │ │\n │← { handshakeId, ─ │ │\n │ suggestion } │ │\n │── render(handshakeId, ─ │ │\n │ props) ────────────→ │ │\n │ │── match/synth blueprint │\n │← { sessionId, ─ │ │\n │ resourceUri } │ │\n │ │── ui://ggui/render/ ──→│ (host mounts iframe)\n │ │ │\n │── consume(sessionId) ───→ │ │\n │ │←── submit gesture ────────│\n │← { events } ──────────── │ │\n │ │ │\n │ (no explicit close — render stays reopenable) │\n```\n\n## Next steps\n\n- **[Claude agent example](/examples/claude-agent/)** — canonical reference implementation for the snippet above\n- **[MCP protocol reference](/api/mcp-protocol/)** — every `ggui_*` tool, request/response, and error code\n- **[React host helpers](/host-helpers/react/)** — embed GGUI renders directly in your own React app with `useMcpAppsChat` + ``\n- **[Other LLMs](/examples/generic-mcp/)** — raw `@modelcontextprotocol/sdk` recipe; also [OpenAI](/examples/openai-agent/), [Gemini](/examples/gemini-agent/)\n- **[Feedback-form cookbook](/cookbook/feedback-form/)** — the recipe above, with variations\n- **[Troubleshooting](/troubleshooting/)** — common issues and fixes\n- **[Glossary](/glossary/)** — gadget vs tool vs blueprint, GGUI vs guuey, and the rest\n- **[Agentic App Builders](/agentic-app-builders/)** — if your goal is to make an existing app agent-drivable rather than building a fresh agent."},{"path":"/quickstart/self-hosted.md","title":"Self-hosted quickstart","description":"Start from the GGUI samples and run an agentic app locally — no account, no cloud, no GGUI API key.","body":"---\ntitle: Self-hosted quickstart\ndescription: Start from the GGUI samples and run an agentic app locally — no account, no cloud, no GGUI API key.\n---\n\nRun the entire protocol yourself — no account, no cloud. This is the same protocol the hosted quickstarts use — nothing about your agent changes between them — see [Portability](/hosted/portability/).\n\nAssemble a complete GGUI agentic app from the canonical samples and run it locally — your agent, the GGUI MCP server, a sample MCP server, and a web client.\n\n```\nagent ── MCP ──→ ggui serve ──→ MCP-Apps resource ui://ggui/render/\n```\n\nTwo ways in — same protocol either way, in the same order as the [repo README](https://github.com/ggui-ai/ggui#quick-start--pick-your-path):\n\n1. **Composed path, on guuey's dev tooling:** published SDKs end-to-end. [guuey](https://guuey.com) is a separate agent-hosting platform; this path uses its dev tools to run the agent, and GGUI renders the UI.\n2. **Bring your own framework:** compose the framework-native samples (Claude Agent SDK / OpenAI Agents SDK / Google ADK) into one workspace, with GGUI alone and no guuey dependency.\n\n## Path 1: composed path, on guuey's dev tooling\n\nOne flow from a `guuey.json` to a rendered, interactive todo UI — every piece a published SDK. [guuey](https://guuey.com)'s dev tooling runs the agent (`@guuey/cli` + `@guuey/worker`), the GGUI runtime is the dev router's injected MCP default, and the web client talks to the router with `@guuey/agent-client`.\n\nPrerequisites: **Node.js 22+**, **pnpm**, and an **`ANTHROPIC_API_KEY`** (one key drives both the agent and GGUI's UI generation).\n\n```bash\ngit clone https://github.com/ggui-ai/ggui && cd ggui\npnpm install # workspace deps — `guuey dev` spawns the colocated\n # todo MCP from samples/mcp-servers/todo\nexport ANTHROPIC_API_KEY=sk-ant-… # in every terminal below\n\n# terminal 1 — the ggui runtime MCP (guuey's dev router injects ggui → this port)\nnpx -y @ggui-ai/cli serve --mcp-only --dev-allow-all # http://127.0.0.1:6781/mcp\n\n# terminal 2 — the agent half: guuey.json + a Claude agent worker\ncd samples/agents/with-guuey\nnpm install\nnpm run dev # guuey dev --serve → http://localhost:6790\n\n# terminal 3 — the web half: chat + rendered ggui cards\ncd samples/apps/with-guuey-web\nnpm install\nnpm run dev # http://127.0.0.1:6890\n```\n\n`--dev-allow-all` is what makes terminal 1 usable here: `/mcp` is bearer-gated by default, and both callers in this path arrive anonymous — the dev router's own GGUI connection (it carries no dev token; only colocated servers get one) and the web half's browser relay. Without the flag, the first `ggui_render` returns `401`. It is a loopback convenience — never put it on a public URL.\n\nOpen **`http://127.0.0.1:6890`** and ask for your todos: the agent calls the todo MCP, renders an interactive todo UI through GGUI, and your clicks flow back to the agent. Prefer a scaffolded start? `npx @guuey/create-agentic-app` scaffolds a guuey agentic app of the same shape (agent + MCP + GGUI + web) in one command.\n\n**Before / after.** This is the composed path's headline. The framework-native web client (`samples/apps/ggui-basic-web`) hand-rolls its agent loop in a 702-line `Chat.tsx` — SSE parsing, the per-turn status machine, the transcript fold, resource narrowing, and generative-UI recognition. The composed web half replaces all of that with `useAgentInvoke` from `@guuey/agent-client/react` plus `@guuey/mcp-apps-host`'s view-mount dispatcher (`toolResultViewMount` — inline mcp-ui resources first, GGUI renders second, bare `ui://` locators last); what remains in `samples/apps/with-guuey-web` is rendering — an `App.tsx` that is mostly JSX.\n\nTwo per-path notes, stated where you hit them (full detail in the sample READMEs — [`samples/agents/with-guuey`](https://github.com/ggui-ai/ggui/tree/main/samples/agents/with-guuey) · [`samples/apps/with-guuey-web`](https://github.com/ggui-ai/ggui/tree/main/samples/apps/with-guuey-web)):\n\n- **Dev-server trust:** `guuey dev` runs your agent unjailed with your environment — standard dev-server trust; run it in a container if that posture doesn't fit.\n- **Fresh sessions only:** `guuey dev --serve` keeps sessions in memory and serves no history endpoint — every page load starts a fresh thread. Durable state belongs in your MCP servers (the todo list survives reloads); reload-repaint of chat history is a hosted-platform feature.\n\nThis path drives the GGUI protocol through guuey's published SDKs. The protocol itself has no guuey dependency — path 2 below (and the self-host and hosted paths in the repo README) runs without it, and the framework-native samples stay first-class.\n\n## Path 2: bring your own framework — framework-native samples\n\nCompose the framework-native samples into one workspace — no guuey dependency. Composing is a real step, not a figure of speech; once the tree exists, a single `pnpm dev` runs all four services.\n\n### Prerequisites\n\n- **Node.js** 22+ — the repo declares `engines.node >= 22`.\n- **pnpm** 11+ — required, not a preference. The workspace carries pnpm-only settings (`nodeLinker: hoisted`, `autoInstallPeers`, `allowBuilds`) that npm and bun do not read.\n- An MCP-capable agent runtime (Claude Desktop, Claude Code, Cursor, or anything that reads `.mcp.json`).\n- No account, no GGUI API key. Everything is local (generation runs on your own LLM key — Step 2).\n\n### Step 1: Clone the samples\n\n```bash\ngit clone https://github.com/ggui-ai/ggui && cd ggui\npnpm install\n```\n\nThe clone gives you the pieces, not a preassembled app. Four canonical samples compose into one small monorepo: `samples/agents//` → `servers/agent/` (your agent — `claude-agent-sdk` / `openai-agents-sdk` / `google-adk`), `samples/gguis/default/` → `servers/ggui/` (the GGUI MCP server config), `samples/mcp-servers/todo/` → `servers/mcps/todo/` (a sample MCP server), and `samples/apps/ggui-basic-web/` → `apps/web/` (a web client).\n\n### Step 1.5: Compose them into one app\n\nComposing is a manual step today — the repo root has no `dev` script and no `servers/` directory until you make one. Two references ship in the repo, and they are the exact ones the project's own end-to-end suite uses:\n\n- **`e2e/samples-render/app-shell/`** — the root wrapper: the `package.json` that carries `dev` plus the granular `dev:ggui` / `dev:agent` / `dev:mcps` / `dev:web` / `dev:stop` scripts, the `pnpm-workspace.yaml` describing the composed layout, and the `pnpm dev` orchestrator itself.\n- **`e2e/samples-render/scripts/compose-app.mjs`** — the copy plan, including the `workspace:*` → published-version rewrite each sample's dependencies need once they live outside this repo's workspace.\n\nCopy the wrapper to an empty directory, copy the four samples to the target paths above, and you have the tree the rest of this path describes. See the [samples quickstart in the repo README](https://github.com/ggui-ai/ggui#quick-start--pick-your-path) for the same layout in the repo's own words.\n\n### Step 2: Boot the composed app\n\nSet an LLM key in `.env.local` at the composed app's root (any one — the boot probe walks `anthropic` → `openai` → `google` → `openrouter`):\n\n```bash\n# .env.local\nANTHROPIC_API_KEY=sk-ant-...\n```\n\n```bash\npnpm dev\n```\n\nFrom the composed root, `pnpm dev` boots the whole app together — the GGUI MCP server (`ggui serve` from [`@ggui-ai/cli`](https://www.npmjs.com/package/@ggui-ai/cli), embedding `@ggui-ai/mcp-server`), your agent, the sample MCP server, and the web client. The GGUI server (`servers/ggui`) defaults to `http://127.0.0.1:6781`:\n\n- **MCP endpoint:** `http://127.0.0.1:6781/mcp`\n- **WebSocket (live channel):** `ws://127.0.0.1:6781/ws`\n- **Operator console:** `http://127.0.0.1:6781/`\n\nGranular scripts (`dev:ggui`, `dev:agent`, `dev:mcps`, `dev:web`, `dev:stop`) run the pieces individually — they are declared in the wrapper's `package.json`.\n\n:::tip[Local dev auth]\nThe composed `servers/ggui` start script passes `--dev-allow-all`, so any non-empty bearer (the `\"Bearer dev\"` in Step 3 below) resolves as `builder`. Bare `ggui serve` does **not** — its default is pair-minted bearers, and a `Bearer dev` config gets a `401` against it. `--dev-allow-all` is fine on `127.0.0.1` and **must never reach the open internet**; switch to [pairing](/self-hosted/pairing/) when you tunnel out.\n:::\n\n:::tip[WebSocket URL differs by deployment]\n\n- **Self-hosted / OSS (this guide):** `ws://127.0.0.1:6781/ws` — or `wss:///ws` once you put TLS in front.\n- **Hosted ggui:** `wss://mcp.ggui.ai/ws` — handled for you. See [Build an agent on hosted GGUI](/quickstart/hosted-agent/).\n :::\n\n### Step 3: Point an agent runtime at the local MCP\n\nCreate `.mcp.json` at your project root with:\n\n```json\n{\n \"mcpServers\": {\n \"ggui\": {\n \"url\": \"http://127.0.0.1:6781/mcp\",\n \"headers\": { \"Authorization\": \"Bearer dev\" }\n }\n }\n}\n```\n\nClaude Desktop, Claude Code, Cursor, and any runtime that reads `.mcp.json` will discover the agent-facing tool catalogue — `ggui_handshake` / `ggui_render` / `ggui_update` / `ggui_amend` / `ggui_emit` / `ggui_consume`, plus discovery tools (`ggui_get_session`, `ggui_list_sessions`, `ggui_list_gadgets`, `ggui_list_themes`, blueprint search/render).\n\nThe flow is **`handshake` → `render`**, with `ggui_amend` to repaint props on the mounted card in place and `ggui_update` to mint a new history card when a change is worth its own transcript entry. Write a system prompt that tells the LLM when to render UIs — the [Examples](/examples/claude-agent/) section has working recipes per framework.\n\n## What works today\n\n- ✅ **Local server + wsToken-gated WebSocket subscribe → ack** work end-to-end — the iframe receives `wsUrl`/`wsToken` on the `ai.ggui/render` slice. Render plumbing is production-shaped, not a mock.\n- ✅ **`handshake` → `render`** delivers an MCP-Apps resource (`ui://ggui/render/`) that an MCP-Apps host mounts.\n- ✅ **Component generation is wired via BYOK.** Export `ANTHROPIC_API_KEY` (or `OPENAI_API_KEY` / `GOOGLE_API_KEY` / `OPENROUTER_API_KEY`) before `ggui serve` and `ggui_render` runs the real `@ggui-ai/ui-gen` pipeline (blueprint match → synth). Without any key, `ggui_render` returns a \"Connect Claude\" card pointing at the local `/settings` page rather than failing.\n- ✅ **Per-app theming.** Your `servers/ggui/ggui.json` sets `theme: {preset: 'indigo', mode: 'dark'}`; agents can list presets via `ggui_list_themes` and override per render with `ggui_render({themeId})`.\n- 🔒 **Default auth is pair-minted.** `/mcp` rejects bearers that weren't issued by the pairing flow. Pass `--dev-allow-all` to accept any non-empty bearer as `builder` (safe only on `127.0.0.1`), or swap in a real `AuthAdapter` via `createGguiServer({ auth })` before exposing the server beyond localhost.\n\n## What this is not\n\n- **Not a hosted service.** No GGUI cloud account, no billing, no managed dashboards. For those, see [Build an agent on hosted GGUI](/quickstart/hosted-agent/).\n- **Not a managed billing surface.** Generation runs on YOUR provider key (BYOK) — every `ggui_render` bills the provider directly. The hosted GGUI cloud bundles credit-metered billing and managed keys; this OSS path runs on your own provider key today.\n\n## Vocabulary\n\n- **Tool** — an agent-side action exposed over MCP (`ggui_render`, `ggui_handshake`, …).\n- **Gadget** — a renderer-side capability surfaced inside the viewer (formerly `clientLibraries`).\n- **Blueprint** — a cached component recipe matched before generation runs.\n\nFull definitions: [Glossary](/glossary/).\n\n## Just the bare MCP server\n\nThe composed app orchestrates everything through `pnpm dev`. If you only want the OSS MCP server — no agent or web supervision — run [`ggui serve`](/cli/serve/) against a `ggui.json` directly (the same `ggui serve` the composed samples' `servers/ggui` runs):\n\n```bash\n# = ggui serve --mcp-only --dev-allow-all --port 6781\npnpm --filter ./servers/ggui start\n```\n\nWorking from a monorepo clone rather than the published packages? Build the workspace copies first:\n\n```bash\npnpm --filter @ggui-ai/cli build\nnode packages/ggui-cli/dist/cli.js serve --mcp-only\n```\n\n## What's next\n\n- **[MCP Protocol Reference](/api/mcp-protocol/)** — wire format and tool catalogue (same on OSS and hosted).\n- **[WebSocket Protocol](/api/websocket-protocol/)** — live-channel envelopes (`ActionEnvelope`, `StreamEnvelope`).\n- **[Examples](/examples/claude-agent/)** — MCP-config-only integrations with system-prompt recipes (Claude, OpenAI, Gemini, generic MCP).\n- **[Build an agent on hosted GGUI](/quickstart/hosted-agent/)** — managed generation and dashboards on GGUI cloud.\n- **[GitHub repo](https://github.com/ggui-ai/ggui)** — source, issue tracker, full monorepo walkthrough."},{"path":"/sdk/gadgets.md","title":"Gadgets SDK","description":"Wrap any 3rd-party browser library (Leaflet, Mapbox, Stripe, …) into an LLM-callable React hook with `createGguiGadget` from `@ggui-ai/gadgets`.","body":"---\ntitle: Gadgets SDK\ndescription: Wrap any 3rd-party browser library (Leaflet, Mapbox, Stripe, …) into an LLM-callable React hook with `createGguiGadget` from `@ggui-ai/gadgets`.\n---\n\n`@ggui-ai/gadgets` is the standard library of browser-capability hooks **and** the wrapper SDK that lets you bind any 3rd-party library into the same uniform contract the LLM already knows.\n\n- **STDLIB hooks** — `useGeolocation`, `useCamera`, `useClipboardWrite`, `useClipboardPaste`, `useNotifications`, `useFilePicker`, `useMicrophone`.\n- **Wrapper SDK** — `createGguiGadget` for Leaflet, Mapbox, Stripe, Chart.js, Three.js, or anything else with a browser API.\n\nSee [Gadgets — deterministic islands](/concepts/gadgets/) for why the wrapper-only design exists, [Glossary](/glossary/) for the gadget / tool / blueprint vocabulary, and [Marketplace Registry](/hosted/marketplace/) for distribution.\n\n\n\n:::tip[Wrapper-only — by design]\n3rd-party libraries enter the system ONLY through `createGguiGadget`. The LLM never sees raw library APIs. Three architectural non-negotiables make this work:\n\n1. **Wrapper-only entry** — every 3rd-party library wraps to a stable React hook contract. The LLM learns ONE pattern.\n2. **Operator-controlled registry gating** — only exports the operator has registered on `App.gadgets` may appear in `contract.clientCapabilities.gadgets`. Render validates and rejects with `gadget_not_registered` on any miss.\n3. **Teaching text is part of the spec** — `description` (what), `usage` (when), `example` (concrete shape) are required on every wrapper. Optional `gotchas` (anti-patterns / known misuse). Without them, wrappers are technically valid but practically unusable: the LLM either skips them or misuses them.\n:::\n\n\n## Installation\n\n```bash\nnpm install @ggui-ai/gadgets\n```\n\n## Authoring a wrapper\n\n```ts\nimport { createGguiGadget } from \"@ggui-ai/gadgets\";\n\nexport const useLeafletMap = createGguiGadget<\n // TOutput — what the hook resolves with on `status: 'completed'`.\n { containerRef: (el: HTMLDivElement | null) => void },\n // TOptions — what the calling component passes in.\n { center: [number, number]; zoom: number }\n>({\n // Canonical hook name — the export name a contract references\n // under clientCapabilities.gadgets[][]. The\n // `use`-prefixed camelCase name marks this export as a hook.\n hook: \"useLeafletMap\",\n\n // REQUIRED teaching text. Synth + decision LLM both see this with\n // a 300-char per-entry budget; description is preserved, usage\n // truncates first when over budget.\n description:\n \"Render an interactive Leaflet map with tile layer and pan/zoom controls. Returns a container ref to attach to a
.\",\n usage:\n \"Mount when the intent names a rendered map (location browsing, route preview, points-of-interest grid). Pass `center: [lat, lng]` + `zoom: 2..20`.\",\n\n // REQUIRED example. JsonValue — concrete shape the LLM uses to\n // pattern-match on cold gen.\n example: {\n call: \"const map = useLeafletMap({ center: [37.7749, -122.4194], zoom: 12 });\",\n returns: {\n status: \"completed\",\n value: { containerRef: \"\" },\n },\n },\n\n // Optional anti-patterns / library quirks. Surfaces in the\n // boilerplate generator's prompt; the LLM uses them to avoid known\n // misuse patterns.\n gotchas:\n \"Leaflet requires the container
to have a non-zero height before the map mounts — apply `style={{ height: 400 }}` (or similar) directly. Default-marker icons require leaflet.css to be in the document; the styleUrl on this descriptor covers that.\",\n\n // REQUIRED. `version` is part of the blueprint cache key, so a\n // wrapper bump automatically invalidates stale cached generations.\n version: \"0.0.1\",\n\n // `package` AND `version` are both REQUIRED — bare npm name, exact\n // semver pin (no URLs, no ranges). `bundleUrl` is optional; when\n // set it wins for boilerplate import emission.\n //\n // Resolution order (operator wins over author wins over spec\n // default): explicit `bundleUrl` → operator `bundleHost` override\n // → author `bundleHost` → spec default `registry.ggui.ai`. With\n // `bundleHost` + `package` + `version` the server assembles\n // `https:///bundles////bundle.js`\n // — prefer this over hardcoded `bundleUrl`.\n package: \"@my-org/ggui-leaflet\",\n bundleHost: \"registry.ggui.ai\",\n\n // Optional companion CSS bundle. The wrapper SHOULD self-inject\n // any required CSS in its hook; the styleUrl is purely an origin\n // declaration so the renderer's CSP allows the load. Same\n // `bundleHost`-based resolution applies — explicit `styleUrl`\n // overrides the host-derived `style.css` path.\n\n // API-call origins (XHR / fetch / WebSocket / ``). The\n // renderer's Content-Security-Policy unions these into BOTH\n // connect-src AND img-src so map tiles loaded via work.\n connect: [\"https://tile.openstreetmap.org\"],\n\n // Public env keys this wrapper consumes (see \"Public env channel\"\n // below). Both wire + registry zod schemas enforce the same\n // `GGUI_PUBLIC_APP_[A-Z0-9_]+` prefix as App.publicEnv. Leaflet\n // doesn't need a token; Mapbox does.\n // requires: [\"GGUI_PUBLIC_APP_MAPBOX_TOKEN\"],\n\n // The React hook. Wrappers bundle their underlying library at\n // build time (esbuild / tsup) and `import` it inside the hook.\n // The function MUST return the standard `{value, status, start, …}`\n // shape that satisfies `GadgetHook`.\n hookImpl: (props) => {\n // … wrap Leaflet's lifecycle into ggui's stable hook contract …\n return {\n value: { containerRef: () => undefined },\n status: \"completed\",\n start: async () => undefined,\n };\n },\n});\n```\n\nThe factory **synchronously zod-validates** the spec at module load. Missing `description` / `usage` / `example`, or a missing `package` / `version`, throws `WrapperConformanceError` with the field path. Authors see the error at import time — not at runtime.\n\n`useLeafletMap` is a callable hook; the immutable wrapper descriptor is attached as `useLeafletMap.descriptor`. Operators register the descriptor on `App.gadgets`.\n\nFor distribution, wrappers ship as a `ggui.gadget.json` manifest (see [Marketplace Registry](/hosted/marketplace/)). The registry's publish endpoint computes the bundle's `sha384` and stamps it on the registered entry's `bundleSri`; `ggui gadget install` writes the descriptor (including `bundleSri` + resolved `bundleUrl`) into `ggui.json#app.gadgets[]`. Hand-authored entries omit `bundleSri` — the iframe runtime falls back to integrity-less dynamic `import()`.\n\nNon-stdlib registered descriptors also carry `typesUrl` (HTTPS URL to the wrapper's `.d.ts`) and `typesSri` (SHA-384 SRI over those types), so the generator can type-check against the wrapper's real surface. `typesUrl` is REQUIRED at registration time for any non-stdlib package; `typesSri` is stamped by the registry on publish (optional for hand-authored entries).\n\n## Multi-export and component packages\n\n`createGguiGadget` is the single-hook convenience — it authors exactly one hook export. For a package that ships more than one export, or a **component** export (like the `LeafletMap` component referenced later on this page), author it with `defineGadgetPackage` instead — the general builder for hook and/or component gadget packages, also from `@ggui-ai/gadgets`:\n\n```ts\nimport { defineGadgetPackage } from \"@ggui-ai/gadgets\";\nimport type { ComponentType } from \"react\";\n\n// Export each impl directly — the builder never wraps or re-types it.\nexport const LeafletMap: ComponentType<{ center: [number, number]; zoom: number }> = (props) => {\n // … render the map …\n};\nexport const useLeafletMap = (options: { center: [number, number]; zoom: number }) => {\n // … the hook version, same lifecycle as the wrapper example above …\n};\n\nexport const leafletDescriptor = defineGadgetPackage({\n package: \"@my-org/ggui-leaflet\",\n version: \"0.0.1\",\n bundleHost: \"registry.ggui.ai\",\n connect: [\"https://tile.openstreetmap.org\"],\n exports: [\n {\n // PascalCase `component` key ⇒ a component export.\n component: \"LeafletMap\",\n impl: LeafletMap,\n description: \"Render an interactive Leaflet map with tile layer and pan/zoom controls.\",\n usage: \"Mount when the intent names a rendered map (location browsing, route preview).\",\n example: { call: \"\", returns: null },\n },\n {\n // `use`-prefixed `hook` key ⇒ a hook export, same shape createGguiGadget produces.\n hook: \"useLeafletMap\",\n impl: useLeafletMap,\n description:\n \"Render an interactive Leaflet map. Returns a container ref to attach to a
.\",\n usage: \"Mount when the intent names a rendered map (location browsing, route preview).\",\n example: {\n call: \"const map = useLeafletMap({ center: [37.7749, -122.4194], zoom: 12 });\",\n returns: { status: \"completed\", value: { containerRef: \"\" } },\n },\n },\n ],\n});\n```\n\nBoth exports share one package identity and one set of transport metadata (`bundleHost`, `connect`), declared once. `defineGadgetPackage` synchronously zod-validates each export's teaching text and name grammar the same way `createGguiGadget` does, throwing `WrapperConformanceError` at module load on a malformed spec.\n\n## Operator registration\n\nAdd the descriptor (or its JSON shape) to `ggui.json#app.gadgets`:\n\nA `GadgetDescriptor` is a PACKAGE — `package` + `version` + transport\nmetadata declared once, plus an `exports[]` array carrying each\nexport's teaching text:\n\n```json\n{\n \"app\": {\n \"slug\": \"leaflet-demo\",\n \"name\": \"Leaflet gadget demo\",\n \"gadgets\": [\n {\n \"package\": \"@my-org/ggui-leaflet\",\n \"version\": \"0.0.1\",\n \"bundleHost\": \"registry.ggui.ai\",\n \"connect\": [\"https://tile.openstreetmap.org\"],\n \"exports\": [\n {\n \"hook\": \"useLeafletMap\",\n \"description\": \"Render an interactive Leaflet map…\",\n \"usage\": \"Mount when the intent names a rendered map…\",\n \"example\": {\n \"call\": \"const map = useLeafletMap({ center: [37.7749, -122.4194], zoom: 12 });\",\n \"returns\": {\n \"status\": \"completed\",\n \"value\": { \"containerRef\": \"\" }\n }\n },\n \"gotchas\": \"Leaflet requires the container
…\"\n }\n ]\n }\n ]\n }\n}\n```\n\nA package that ships more than one export (two hooks, or a hook plus a\nReact `component`) adds further entries to the same `exports` array —\nthe transport metadata is declared once and shared.\n\nThe CLI threads `app.gadgets` into the in-process `AppMetadataStore` so the same singleton powers `ggui_list_gadgets`, handshake-time prompt injection, render-time validation + enrichment, and CSP derivation.\n\n### From the console\n\nEditing `ggui.json` by hand isn't the only install path for a hosted app. The [GGUI console](https://console.ggui.ai)'s per-app **Gadgets** tab (`/apps/[appId]/gadgets`) shows exactly what agents receive from `ggui_list_gadgets` — the same three-tier catalog, resolved with the same precedence the server uses at render time: stdlib floor < web-installed < `ggui.json`-declared.\n\n- **stdlib** rows are the seven always-on hooks — action-free.\n- **installed** rows were added through the console's own search + install flow (not `ggui.json`). Each row carries a version menu — picking a version re-installs at that pin — and a two-step-confirm Remove that uninstalls it.\n- **declared** rows came from `ggui.json#app.gadgets`. The console never edits `ggui.json` for you; a declared package always wins over an installed one on an exact `package` collision, so a declared row is display-only here.\n\nUse the console tab for hosted apps where you'd rather browse + click-install a registry package than hand-edit JSON; use `ggui.json#app.gadgets` (above) when you're checking gadget config into source control or self-hosting.\n\n## Contract gadget refs vs `GadgetDescriptor`\n\nTwo distinct shapes — do not confuse them. One is the wire map a host\nagent authors on a contract; the other is the registry-side package\ndescriptor an operator registers. Both are organized around a gadget\n**package** that ships one or more **exports**, where each export is\neither a hook (a `use`-prefixed camelCase name) or a component (a\nPascalCase name):\n\n- **Contract gadget refs** — `clientCapabilities.gadgets` on a `DataContract` is a **package-keyed two-level map** carrying IDENTITY ONLY. The outer key is the npm package name; the inner key is the export name; the inner value is a `GadgetExportUse` — `{ description?, usage? }`, usually just `{}` (optional intent-specific override prose). There is NO `hook` / `component` field on the wire — the export-name GRAMMAR is the discriminator: `useGeolocation` is a hook, `LeafletMap` is a component. There is NO `version`, NO `permission`, NO transport metadata, and NO `binding` key. The wire carries `(package, exportName)` and nothing else.\n- **`GadgetDescriptor`** — the full registry-side PACKAGE descriptor (what operators register on `App.gadgets`). Package-level identity (`package` + `version`) plus transport metadata (bundle URLs, `connect`, `typesUrl` / `typesSri`) declared once, plus an `exports: GadgetExport[]` array (≥1). Each `GadgetExport` is a field-presence-discriminated union — a hook export `{ hook, … }` or a component export `{ component, … }` — carrying that export's teaching text + per-export `permission`. `version`, transport metadata, `permission`, and `requires` ALL resolve server-side from this descriptor at render time; the contract author never restates them. `createGguiGadget` authors a single-export package; multi-export packages add further `exports` entries.\n\n## Agent reference shape\n\nOnce a package is registered on `App.gadgets`, contracts reference its\nexports through the package-keyed `clientCapabilities.gadgets` map —\nouter key = package name, inner key = export name:\n\n```ts\nconst contract = {\n // … propsSpec / actionSpec / contextSpec …\n clientCapabilities: {\n gadgets: {\n \"@my-org/ggui-leaflet\": {\n // PascalCase key ⇒ a component export. Empty value is the\n // common case; an optional `{ description?, usage? }` override\n // sharpens the teaching text for this specific intent.\n LeafletMap: {},\n },\n \"@ggui-ai/gadgets\": {\n // `use`-prefixed camelCase key ⇒ a hook export.\n useGeolocation: {},\n },\n },\n },\n};\n```\n\nThe wire is identity-only: render resolves each `(package, exportName)`\npair against the registered `GadgetDescriptor` and enriches the\npersisted `ComponentGguiSession` with the canonical `version`, transport metadata,\nteaching text, and `permission`. To walk the map in code, call\n`listContractGadgets(contract)` — it flattens the package-keyed map\ninto a `readonly GadgetUse[]`, each entry `{ package, name, description?, usage? }`.\n\nReferences to unregistered exports reject at render validation with `gadget_not_registered` and a did-you-mean hint when a close stdlib match exists (Levenshtein < 3 cutoff). Render also rejects with `gadget_package_mismatch` when a referenced export name belongs to a different registered package than the one keyed.\n\n## What the renderer derives\n\nWhen ANY gadget in `clientCapabilities.gadgets` declares `bundleUrl` / `styleUrl` / `connect[]`, the render's spec-canonical `_meta.ui.csp` block carries the derived `{ connectDomains, resourceDomains }` (per the MCP Apps spec). The MCP-Apps host applies them to the sandboxed iframe as a Content-Security-Policy — conceptually:\n\n```\nscript-src 'self' 'unsafe-inline' ;\nstyle-src 'self' 'unsafe-inline' ;\nconnect-src 'self' ;\nimg-src 'self' data: \n```\n\n- `'unsafe-inline'` on `script-src` is needed because the render shell embeds the bootstrap as an inline `