From 2dc365629df996dc6796c8010d8ea7665a5a3d6d Mon Sep 17 00:00:00 2001
From: Brian Love <brian@liveloveapp.com>
Date: Mon, 8 Jun 2026 16:02:11 -0700
Subject: [PATCH 01/15] =?UTF-8?q?docs(spec):=20AG-UI=20docs=20polish=20?=
 =?UTF-8?q?=E2=80=94=20demo=20link=20+=20API=20reference=20+=20custom-even?=
 =?UTF-8?q?ts=20guide?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 .../2026-06-07-ag-ui-docs-demo-link-design.md | 165 ++++++++++++++++++
 1 file changed, 165 insertions(+)
 create mode 100644 docs/superpowers/specs/2026-06-07-ag-ui-docs-demo-link-design.md

diff --git a/docs/superpowers/specs/2026-06-07-ag-ui-docs-demo-link-design.md b/docs/superpowers/specs/2026-06-07-ag-ui-docs-demo-link-design.md
new file mode 100644
index 000000000..9eb926378
--- /dev/null
+++ b/docs/superpowers/specs/2026-06-07-ag-ui-docs-demo-link-design.md
@@ -0,0 +1,165 @@
+# AG-UI Docs Polish — Demo Link + API Reference + Custom-Events Guide
+
+**Date:** 2026-06-07
+**Status:** Design / spec
+**Scope:** Website docs surface for the `@threadplane/ag-ui` adapter. No library code changes, no `/ag-ui` marketing-landing-page changes.
+
+---
+
+## Goal
+
+Close the three concrete AG-UI website/docs gaps surfaced by the reassessment against latest `main`:
+
+1. **Demo link** — the live demo we shipped at `ag-ui.threadplane.ai` is not linked anywhere on the site. Surface it as a **context-scoped** link in the AG-UI docs navigation (not the global navbar).
+2. **API Reference nav (B)** — AG-UI has a generated `api-docs.json` but, unlike langgraph/render/chat, no hand-authored API Reference section in the docs nav. Author parity API pages and wire the section.
+3. **Custom-events guide (C)** — the `AgUiAgent.customEvents` signal (shipped in #606 for live a2ui streaming) is mentioned only in passing. Add a dedicated guide.
+
+## Non-Goals (YAGNI)
+
+- No changes to the global top navbar `links` array (`Demo` / `Examples` stay as-is, pointing at the LangGraph demo + cockpit).
+- No `/ag-ui` product/landing page changes (no hero "See it live" button, no embedded iframe on the landing page).
+- No global "demos" dropdown menu. The `demoUrl` config field makes that trivial later, but it is out of scope now.
+- No library (`libs/ag-ui`) source changes. API reference content is authored prose mirroring the existing langgraph API mdx pages.
+
+---
+
+## Architecture & key decisions
+
+### Where the demo link lives
+
+The global top navbar (`apps/website/src/components/shared/Nav.tsx`, `links` array) is **global and single-valued** — it already carries one `Demo` → `https://demo.threadplane.ai` (LangGraph) and one `Examples` → `https://cockpit.threadplane.ai`. A second, library-specific "AG-UI Demo" entry there would clutter it and make "Demo" ambiguous.
+
+Instead the demo link is attached to the **per-library docs config** and rendered only in the **contextual docs navigation**, which already knows which library you are viewing:
+
+- **Desktop:** `apps/website/src/components/docs/DocsSidebar.tsx` — a "Live demo ↗" link rendered directly under the `LibraryDropdown`, shown only when the active library config defines a `demoUrl`.
+- **Mobile:** `apps/website/src/components/shared/Nav.tsx` — the docs-tab rendering path (NOT the global site `links`) renders the same link when the selected library config defines a `demoUrl`.
+
+The global navbar is therefore **untouched**. The link appears only while reading AG-UI docs.
+
+This is driven by adding optional fields to the `DocsLibrary` interface in `apps/website/src/lib/docs-config.ts`:
+
+```ts
+export interface DocsLibrary {
+  id: LibraryId;
+  title: string;
+  description: string;
+  /** Optional external live-demo URL, surfaced contextually in docs nav. */
+  demoUrl?: string;
+  /** Optional label override for the demo link. Defaults to 'Live demo'. */
+  demoLabel?: string;
+  sections: DocsSection[];
+}
+```
+
+For the AG-UI library entry: `demoUrl: 'https://ag-ui.threadplane.ai'`. No other library sets `demoUrl` in this change, so nothing else renders a demo link.
+
+A complementary in-content callout is added to `apps/website/content/docs/ag-ui/getting-started/introduction.mdx` so on-page readers also see the demo link (using whatever callout/link primitives the existing AG-UI mdx already uses — to be matched at implementation time).
+
+### API Reference (B)
+
+Mirror the langgraph pattern exactly. langgraph has `apps/website/content/docs/langgraph/api/{inject-agent,provide-agent,fetch-stream-transport,mock-stream-transport}.mdx` plus a generated `api-docs.json`, wired via an `API Reference` section (`id: 'api'`) in `docs-config.ts`.
+
+The `@threadplane/ag-ui` public surface (from `libs/ag-ui/src/public-api.ts`):
+
+- Functions: `toAgent(source, options?) → AgUiAgent`, `provideAgent(configOrFactory) → Provider[]`, `injectAgent() → Agent`, `provideFakeAgent(config?) → Provider[]`, `bridgeCitationsState(thread, messages) → Message[]`
+- Class: `FakeAgent`
+- Types: `AgUiAgent` (extends `Agent` with `customEvents: Signal<CustomStreamEvent[]>`), `AgentConfig`, `ToAgentOptions`, `CustomStreamEvent`
+
+**Decision: 4 core API pages (parity with langgraph):**
+
+| Page (`api/<slug>.mdx`) | Primary symbol | Folds in |
+| --- | --- | --- |
+| `provide-agent` | `provideAgent()` | `AgentConfig` |
+| `inject-agent` | `injectAgent()` | `AgUiAgent` returned contract, incl. `customEvents` (cross-link to custom-events guide) |
+| `to-agent` | `toAgent()` | `ToAgentOptions`, `CustomStreamEvent` (lower-level adapter entrypoint) |
+| `fake-agent` | `provideFakeAgent()` + `FakeAgent` | testing surface |
+
+`bridgeCitationsState` is niche — it is cross-linked from the existing `guides/citations.mdx` rather than given its own API page.
+
+Wire these into a new `API Reference` section (`id: 'api'`, after `Reference`) in the AG-UI entry of `docs-config.ts`:
+
+```ts
+{
+  title: 'API Reference',
+  id: 'api',
+  color: 'blue',
+  pages: [
+    { title: 'provideAgent()', slug: 'provide-agent', section: 'api' },
+    { title: 'injectAgent()', slug: 'inject-agent', section: 'api' },
+    { title: 'toAgent()', slug: 'to-agent', section: 'api' },
+    { title: 'FakeAgent', slug: 'fake-agent', section: 'api' },
+  ],
+},
+```
+
+The generated `api-docs.json` is already current (regenerated in #606, confirmed during reconnaissance). Implementation re-runs `npm run generate-api-docs` and commits only if the output changes.
+
+### Custom-events guide (C)
+
+New `apps/website/content/docs/ag-ui/guides/custom-events.mdx`, added to the AG-UI `Guides` section in `docs-config.ts` (after `citations`, before `interrupts` — both are CUSTOM-event features so they sit together).
+
+Content outline:
+- What `customEvents` is: AG-UI `CUSTOM` events (other than `on_interrupt`) accumulate into the `AgUiAgent.customEvents` signal — `Signal<CustomStreamEvent[]>` where `CustomStreamEvent = { name: string; data: unknown }`. Reset on `RUN_STARTED`.
+- The backend side: a LangGraph `get_stream_writer()` → `stream_mode='custom'` emit becomes an AG-UI `CUSTOM` event becomes an entry in `customEvents()`.
+- Worked example: consuming `agent.customEvents()` for live/progressive a2ui surface updates during a run.
+- Cross-links: `concepts/architecture.mdx` (where customEvents is mentioned), `reference/event-mapping.mdx` (the CUSTOM row), and `api/inject-agent.mdx` (the signal on the returned agent).
+- Match the established AG-UI doc voice (per the recent voice pass): no fabricated anecdotes, trimmed technical register.
+
+---
+
+## Components / files touched
+
+**Config (shared by all three):**
+- `apps/website/src/lib/docs-config.ts` — add `demoUrl`/`demoLabel` to `DocsLibrary`; set `demoUrl` on ag-ui; add `API Reference` section; add `custom-events` to Guides.
+
+**Demo link:**
+- `apps/website/src/components/docs/DocsSidebar.tsx` — render contextual "Live demo ↗" link when `libConfig?.demoUrl`.
+- `apps/website/src/components/shared/Nav.tsx` — render the same in the mobile docs-tab path when `currentLib?.demoUrl`.
+- `apps/website/content/docs/ag-ui/getting-started/introduction.mdx` — in-content demo callout.
+
+**API Reference:**
+- `apps/website/content/docs/ag-ui/api/provide-agent.mdx` (new)
+- `apps/website/content/docs/ag-ui/api/inject-agent.mdx` (new)
+- `apps/website/content/docs/ag-ui/api/to-agent.mdx` (new)
+- `apps/website/content/docs/ag-ui/api/fake-agent.mdx` (new)
+- `apps/website/content/docs/ag-ui/guides/citations.mdx` — add `bridgeCitationsState` cross-link.
+
+**Custom-events guide:**
+- `apps/website/content/docs/ag-ui/guides/custom-events.mdx` (new)
+
+---
+
+## Data flow (demo link)
+
+`docs-config.ts` (`DocsLibrary.demoUrl`) → consumed by `DocsSidebar.tsx` (desktop) and `Nav.tsx` mobile docs path → renders an external anchor (`target="_blank" rel="noopener noreferrer"`) with analytics tracking matching the existing `trackExternalLinkClick` pattern (e.g. `cta_id: 'docs_sidebar_demo'` / `'mobile_nav_demo'`, `cta_text` from `demoLabel`).
+
+## Error handling / edge cases
+
+- Libraries without `demoUrl` render no demo link (the common case). Guard with a simple truthiness check.
+- The demo link is external and unauthenticated; no app state depends on it.
+- API mdx pages are static content; the only failure mode is a broken internal cross-link — caught by the website build + any link-check in CI.
+
+## Testing / verification
+
+This is a static Next.js docs + mdx change. Verification per workstream:
+
+- **Build:** `nx build website` (or the repo's website build target) succeeds with the new mdx pages and nav entries.
+- **Lint/typecheck:** the `docs-config.ts` interface change and the two component edits typecheck (`nx lint website` / `tsc`).
+- **Nav rendering:** the new API Reference section and `custom-events` guide appear in the AG-UI sidebar; the "Live demo" link appears only on AG-UI docs (desktop sidebar + mobile docs tab) and resolves to `https://ag-ui.threadplane.ai`.
+- **Cross-links:** new pages' internal links resolve (no 404s in build).
+- **No regressions:** other libraries' nav is unchanged; global navbar is unchanged.
+- **API docs regen:** `npm run generate-api-docs` produces no unexpected diff (or commit the refreshed `api-docs.json` if it does).
+
+A Playwright/visual smoke is optional; if the website has an existing docs e2e harness, add a minimal assertion that the AG-UI sidebar shows the demo link and the API Reference section. Otherwise rely on build + manual verification.
+
+---
+
+## Decomposition (for the plan)
+
+Three largely independent workstreams; `docs-config.ts` is the one shared file (sequence its edits to avoid churn):
+
+- **A — Demo link:** config field + DocsSidebar + Nav mobile + introduction callout.
+- **B — API reference:** 4 API mdx pages + config `API Reference` section + citations cross-link + api-docs regen check.
+- **C — Custom-events guide:** 1 guide mdx + config Guides entry.
+
+Suggested order: A, then B, then C (each appends to `docs-config.ts`, minimizing conflicts). Single PR, or one PR per workstream if review prefers smaller diffs.

From 90e7f1fc8ea93e9c3525a34924d9e3aca9b5c261 Mon Sep 17 00:00:00 2001
From: Brian Love <brian@liveloveapp.com>
Date: Mon, 8 Jun 2026 16:37:42 -0700
Subject: [PATCH 02/15] docs(spec): expand to paired demo CTAs + homepage demo
 rebuild

Augments the AG-UI docs polish spec with: site-wide paired LangGraph/AG-UI
demo CTAs (shared DEMOS source + DemoCtaPair), a tabbed video-first homepage
demo section (DemoShowcase), context-scoped AG-UI docs demo link + content
callouts, the API reference nav section, and the custom-events guide.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 .../2026-06-07-ag-ui-docs-demo-link-design.md | 204 +++++++++++-------
 1 file changed, 124 insertions(+), 80 deletions(-)

diff --git a/docs/superpowers/specs/2026-06-07-ag-ui-docs-demo-link-design.md b/docs/superpowers/specs/2026-06-07-ag-ui-docs-demo-link-design.md
index 9eb926378..10f855cf3 100644
--- a/docs/superpowers/specs/2026-06-07-ag-ui-docs-demo-link-design.md
+++ b/docs/superpowers/specs/2026-06-07-ag-ui-docs-demo-link-design.md
@@ -1,42 +1,94 @@
-# AG-UI Docs Polish — Demo Link + API Reference + Custom-Events Guide
+# AG-UI Demo Discoverability + Docs Polish
 
 **Date:** 2026-06-07
 **Status:** Design / spec
-**Scope:** Website docs surface for the `@threadplane/ag-ui` adapter. No library code changes, no `/ag-ui` marketing-landing-page changes.
+**Scope:** Website (`apps/website`) — surface the AG-UI live demo, present LangGraph + AG-UI demos as a paired choice everywhere a demo is referenced, rebuild the homepage demo section, and close the remaining AG-UI docs gaps. No `@threadplane/*` library source changes.
 
 ---
 
 ## Goal
 
-Close the three concrete AG-UI website/docs gaps surfaced by the reassessment against latest `main`:
+Make the AG-UI live demo (`ag-ui.threadplane.ai`, shipped earlier) discoverable, and present it as a first-class peer to the LangGraph demo across the marketing site, while closing two AG-UI docs gaps surfaced during the reassessment.
 
-1. **Demo link** — the live demo we shipped at `ag-ui.threadplane.ai` is not linked anywhere on the site. Surface it as a **context-scoped** link in the AG-UI docs navigation (not the global navbar).
-2. **API Reference nav (B)** — AG-UI has a generated `api-docs.json` but, unlike langgraph/render/chat, no hand-authored API Reference section in the docs nav. Author parity API pages and wire the section.
-3. **Custom-events guide (C)** — the `AgUiAgent.customEvents` signal (shipped in #606 for live a2ui streaming) is mentioned only in passing. Add a dedicated guide.
+Five workstreams:
+
+- **A — Paired demo CTAs site-wide.** Everywhere "the demo" is referenced, show **two parallel CTAs** (LangGraph + AG-UI), driven by one shared source of truth.
+- **B — Homepage demo section rebuild.** Replace the single embedded LangGraph iframe with a **tabbed, video-first** section that shows both demos large and launches the live interactive embed on click.
+- **C — AG-UI docs demo link.** A context-scoped demo link in the AG-UI docs nav + AG-UI-specific content callouts.
+- **D — API reference nav.** Author parity AG-UI API mdx pages and wire the `API Reference` nav section.
+- **E — Custom-events guide.** A dedicated guide for the `AgUiAgent.customEvents` signal (#606).
 
 ## Non-Goals (YAGNI)
 
-- No changes to the global top navbar `links` array (`Demo` / `Examples` stay as-is, pointing at the LangGraph demo + cockpit).
-- No `/ag-ui` product/landing page changes (no hero "See it live" button, no embedded iframe on the landing page).
-- No global "demos" dropdown menu. The `demoUrl` config field makes that trivial later, but it is out of scope now.
-- No library (`libs/ag-ui`) source changes. API reference content is authored prose mirroring the existing langgraph API mdx pages.
+- No `/ag-ui` product/landing-page redesign (no hero "See it live" button, no landing iframe). The landing page is out of scope.
+- No `libs/ag-ui` (or any library) source changes. API reference content is authored prose.
+- No new backend/runtime; the demos already exist (`demo.threadplane.ai`, `ag-ui.threadplane.ai`).
+- The chat product page's "See it live →" (→ cockpit) and the homepage Hero screenshot (→ cockpit example) are **examples** links, not demo links — left unchanged.
+
+---
+
+## Decisions locked during brainstorming
+
+- **FinalCTA:** two demo buttons (LangGraph + AG-UI) **and** keep the existing cockpit "See each feature in action →" ghost secondary.
+- **Navbar:** the single global "Demo" link becomes a **"Demo ▾" dropdown** (desktop) listing LangGraph + AG-UI; mobile renders the two as separate entries.
+- **Homepage:** **Layout A — tabbed single large frame** (LangGraph | AG-UI tabs, LangGraph-first), **video-first**: each tab opens with a looping muted recording and a "Launch live demo ▶" overlay that swaps in the real interactive iframe on click. Approved composition copy: eyebrow "See it running", headline "One chat UI. Two runtimes. Same code.", parity subhead, paired CTAs + cockpit ghost, caption.
 
 ---
 
-## Architecture & key decisions
+## Architecture
+
+### Single source of truth for demos
 
-### Where the demo link lives
+New `apps/website/src/lib/demos.ts`:
 
-The global top navbar (`apps/website/src/components/shared/Nav.tsx`, `links` array) is **global and single-valued** — it already carries one `Demo` → `https://demo.threadplane.ai` (LangGraph) and one `Examples` → `https://cockpit.threadplane.ai`. A second, library-specific "AG-UI Demo" entry there would clutter it and make "Demo" ambiguous.
+```ts
+export interface DemoTarget {
+  /** Stable key for analytics cta_id suffixes. */
+  key: 'langgraph' | 'ag-ui';
+  /** Button/link label (without trailing arrow — callers add it). */
+  label: string;
+  href: string;
+}
+
+export const DEMOS: DemoTarget[] = [
+  { key: 'langgraph', label: 'LangGraph demo', href: 'https://demo.threadplane.ai' },
+  { key: 'ag-ui', label: 'AG-UI demo', href: 'https://ag-ui.threadplane.ai' },
+];
+```
+
+Every demo surface reads from `DEMOS`, so adding/retargeting a demo is a one-line change.
 
-Instead the demo link is attached to the **per-library docs config** and rendered only in the **contextual docs navigation**, which already knows which library you are viewing:
+### Workstream A — Paired demo CTAs site-wide
 
-- **Desktop:** `apps/website/src/components/docs/DocsSidebar.tsx` — a "Live demo ↗" link rendered directly under the `LibraryDropdown`, shown only when the active library config defines a `demoUrl`.
-- **Mobile:** `apps/website/src/components/shared/Nav.tsx` — the docs-tab rendering path (NOT the global site `links`) renders the same link when the selected library config defines a `demoUrl`.
+| Surface | File | Change |
+| --- | --- | --- |
+| Reusable button pair | `apps/website/src/components/landing/DemoCtaPair.tsx` (new) | Renders the two `DEMOS` entries as parallel `Button`s (props: `size`, primary/secondary `variant` per entry, per-click analytics `cta_id` = `${surface}_demo_${key.replace(/-/g,'_')}`, i.e. `ag-ui` → `ag_ui`). |
+| FinalCTA (9 pages) | `apps/website/src/components/landing/FinalCTA.tsx` | Replace the single `primary` "Try the demo →" with `<DemoCtaPair>`; **keep** the cockpit `secondary` ghost. Preserve existing per-page `primary`/`secondary` override props for callers that pass them (default path uses the pair). |
+| Navbar (desktop) | `apps/website/src/components/shared/Nav.tsx` | Replace the `Demo` entry in `links` with a **"Demo ▾" dropdown** (reuse the click-outside dropdown pattern from `DocsSidebar`'s `LibraryDropdown`) listing the `DEMOS` entries. |
+| Navbar (mobile) | `apps/website/src/components/shared/Nav.tsx` | In the mobile site-links list, render the `DEMOS` entries as two rows ("LangGraph demo", "AG-UI demo") in place of the single "Demo" row. |
+| Footer | `apps/website/src/components/shared/Footer.tsx` | Replace the single "Demo" link with two links from `DEMOS`. |
 
-The global navbar is therefore **untouched**. The link appears only while reading AG-UI docs.
+Analytics: each rendered link/button keeps `trackExternalLinkClick`/`trackCtaClick` with distinct `cta_id`s (`nav_demo_langgraph`, `nav_demo_ag_ui`, `footer_demo_langgraph`, `final_cta_demo_langgraph`, etc.) so click attribution survives the split.
 
-This is driven by adding optional fields to the `DocsLibrary` interface in `apps/website/src/lib/docs-config.ts`:
+### Workstream B — Homepage demo section rebuild
+
+New `apps/website/src/components/landing/DemoShowcase.tsx` (client component) replaces the `LiveDemoFrame` usage at `apps/website/src/app/page.tsx:115`. Structure (approved):
+
+- Eyebrow "See it running" · headline "One chat UI. Two runtimes. Same code." · parity subhead.
+- **Tabs**: `LangGraph | AG-UI` (LangGraph default). Tab state is local (`useState`).
+- **Frame** (`BrowserFrame`): per active tab, render the **video-first** state — a looping, muted, `playsInline`, `autoPlay` `<video>` (poster = a static screenshot fallback) with a "Launch live demo ▶" overlay button. Clicking the overlay (or the matching CTA) swaps that tab to the live `<iframe src={demo.href}>` (lazy; only mounts on launch). Switching tabs returns to the video state unless that tab was already launched (track launched-tab set).
+- **Paired CTAs** beneath: `<DemoCtaPair>` + cockpit "See each feature in action →" ghost.
+- Caption: "Video loops instantly · click Launch to open the live, interactive demo · MIT · no signup".
+
+**Video assets** (`apps/website/public/demo/`): `langgraph-demo.mp4` + `.webm`, `ag-ui-demo.mp4` + `.webm`, plus `langgraph-demo-poster.webp` / `ag-ui-demo-poster.webp`. Each video is a ~15–25s screen capture of a real run (prompt → streaming answer → a2ui surface render), encoded small (target < 2–3 MB, H.264 + VP9). Production is a discrete task.
+
+**Shippability guard:** the section must render correctly **before** the videos exist — if a video asset is missing, the tab shows the poster image (or a screenshot) with the launch overlay, so the section degrades to a static-poster + launch-to-live state. Video is layered in without blocking the rest.
+
+`LiveDemoFrame.tsx` is removed once `DemoShowcase` replaces its only usage (confirm no other importers first; reconnaissance shows only `page.tsx`).
+
+### Workstream C — AG-UI docs demo link (context-scoped)
+
+Add optional fields to `DocsLibrary` in `apps/website/src/lib/docs-config.ts`:
 
 ```ts
 export interface DocsLibrary {
@@ -51,38 +103,36 @@ export interface DocsLibrary {
 }
 ```
 
-For the AG-UI library entry: `demoUrl: 'https://ag-ui.threadplane.ai'`. No other library sets `demoUrl` in this change, so nothing else renders a demo link.
-
-A complementary in-content callout is added to `apps/website/content/docs/ag-ui/getting-started/introduction.mdx` so on-page readers also see the demo link (using whatever callout/link primitives the existing AG-UI mdx already uses — to be matched at implementation time).
+Set `demoUrl: 'https://ag-ui.threadplane.ai'` on the AG-UI entry only. Render a "Live demo ↗" link:
+- **Desktop:** `apps/website/src/components/docs/DocsSidebar.tsx` — under the `LibraryDropdown`, shown only when `libConfig?.demoUrl`.
+- **Mobile:** `apps/website/src/components/shared/Nav.tsx` docs-tab path — same, when `currentLib?.demoUrl`.
 
-### API Reference (B)
+**AG-UI-specific content callouts** (the "augment AG-UI content" ask): add a demo callout/link to:
+- `apps/website/content/docs/ag-ui/getting-started/introduction.mdx`
+- `apps/website/content/docs/ag-ui/getting-started/quickstart.mdx`
 
-Mirror the langgraph pattern exactly. langgraph has `apps/website/content/docs/langgraph/api/{inject-agent,provide-agent,fetch-stream-transport,mock-stream-transport}.mdx` plus a generated `api-docs.json`, wired via an `API Reference` section (`id: 'api'`) in `docs-config.ts`.
+using the callout/link primitives already used in the AG-UI mdx (matched at implementation time). Both point at `https://ag-ui.threadplane.ai`.
 
-The `@threadplane/ag-ui` public surface (from `libs/ag-ui/src/public-api.ts`):
+### Workstream D — API reference nav
 
-- Functions: `toAgent(source, options?) → AgUiAgent`, `provideAgent(configOrFactory) → Provider[]`, `injectAgent() → Agent`, `provideFakeAgent(config?) → Provider[]`, `bridgeCitationsState(thread, messages) → Message[]`
-- Class: `FakeAgent`
-- Types: `AgUiAgent` (extends `Agent` with `customEvents: Signal<CustomStreamEvent[]>`), `AgentConfig`, `ToAgentOptions`, `CustomStreamEvent`
+Mirror the langgraph pattern (hand-authored mdx + generated `api-docs.json`, wired via an `id: 'api'` section). The `@threadplane/ag-ui` public surface: `toAgent`, `provideAgent`, `injectAgent`, `provideFakeAgent`, `bridgeCitationsState`, `FakeAgent`; types `AgUiAgent`, `AgentConfig`, `ToAgentOptions`, `CustomStreamEvent`.
 
-**Decision: 4 core API pages (parity with langgraph):**
+**4 core API pages** under `apps/website/content/docs/ag-ui/api/`:
 
-| Page (`api/<slug>.mdx`) | Primary symbol | Folds in |
+| Page (`<slug>.mdx`) | Primary symbol | Folds in |
 | --- | --- | --- |
 | `provide-agent` | `provideAgent()` | `AgentConfig` |
-| `inject-agent` | `injectAgent()` | `AgUiAgent` returned contract, incl. `customEvents` (cross-link to custom-events guide) |
-| `to-agent` | `toAgent()` | `ToAgentOptions`, `CustomStreamEvent` (lower-level adapter entrypoint) |
+| `inject-agent` | `injectAgent()` | `AgUiAgent` returned contract incl. `customEvents` (cross-link to custom-events guide) |
+| `to-agent` | `toAgent()` | `ToAgentOptions`, `CustomStreamEvent` |
 | `fake-agent` | `provideFakeAgent()` + `FakeAgent` | testing surface |
 
-`bridgeCitationsState` is niche — it is cross-linked from the existing `guides/citations.mdx` rather than given its own API page.
+`bridgeCitationsState` is cross-linked from `guides/citations.mdx` rather than given its own page.
 
-Wire these into a new `API Reference` section (`id: 'api'`, after `Reference`) in the AG-UI entry of `docs-config.ts`:
+Wire a new section into the AG-UI entry of `docs-config.ts` (after `Reference`):
 
 ```ts
 {
-  title: 'API Reference',
-  id: 'api',
-  color: 'blue',
+  title: 'API Reference', id: 'api', color: 'blue',
   pages: [
     { title: 'provideAgent()', slug: 'provide-agent', section: 'api' },
     { title: 'injectAgent()', slug: 'inject-agent', section: 'api' },
@@ -92,74 +142,68 @@ Wire these into a new `API Reference` section (`id: 'api'`, after `Reference`) i
 },
 ```
 
-The generated `api-docs.json` is already current (regenerated in #606, confirmed during reconnaissance). Implementation re-runs `npm run generate-api-docs` and commits only if the output changes.
+Re-run `npm run generate-api-docs`; commit refreshed `api-docs.json` only if it changes.
 
-### Custom-events guide (C)
+### Workstream E — Custom-events guide
 
-New `apps/website/content/docs/ag-ui/guides/custom-events.mdx`, added to the AG-UI `Guides` section in `docs-config.ts` (after `citations`, before `interrupts` — both are CUSTOM-event features so they sit together).
+New `apps/website/content/docs/ag-ui/guides/custom-events.mdx`, added to the AG-UI `Guides` section in `docs-config.ts` (after `citations`). Outline:
 
-Content outline:
-- What `customEvents` is: AG-UI `CUSTOM` events (other than `on_interrupt`) accumulate into the `AgUiAgent.customEvents` signal — `Signal<CustomStreamEvent[]>` where `CustomStreamEvent = { name: string; data: unknown }`. Reset on `RUN_STARTED`.
-- The backend side: a LangGraph `get_stream_writer()` → `stream_mode='custom'` emit becomes an AG-UI `CUSTOM` event becomes an entry in `customEvents()`.
+- `customEvents`: AG-UI `CUSTOM` events (other than `on_interrupt`) accumulate into `AgUiAgent.customEvents` — `Signal<CustomStreamEvent[]>`, `CustomStreamEvent = { name: string; data: unknown }`, reset on `RUN_STARTED`.
+- Backend side: LangGraph `get_stream_writer()` → `stream_mode='custom'` → AG-UI `CUSTOM` → an entry in `customEvents()`.
 - Worked example: consuming `agent.customEvents()` for live/progressive a2ui surface updates during a run.
-- Cross-links: `concepts/architecture.mdx` (where customEvents is mentioned), `reference/event-mapping.mdx` (the CUSTOM row), and `api/inject-agent.mdx` (the signal on the returned agent).
-- Match the established AG-UI doc voice (per the recent voice pass): no fabricated anecdotes, trimmed technical register.
+- Cross-links: `concepts/architecture.mdx`, `reference/event-mapping.mdx` (CUSTOM row), `api/inject-agent.mdx`.
+- AG-UI doc voice (recent voice pass): no fabricated anecdotes, trimmed technical register.
 
 ---
 
-## Components / files touched
-
-**Config (shared by all three):**
-- `apps/website/src/lib/docs-config.ts` — add `demoUrl`/`demoLabel` to `DocsLibrary`; set `demoUrl` on ag-ui; add `API Reference` section; add `custom-events` to Guides.
+## Files touched (summary)
 
-**Demo link:**
-- `apps/website/src/components/docs/DocsSidebar.tsx` — render contextual "Live demo ↗" link when `libConfig?.demoUrl`.
-- `apps/website/src/components/shared/Nav.tsx` — render the same in the mobile docs-tab path when `currentLib?.demoUrl`.
-- `apps/website/content/docs/ag-ui/getting-started/introduction.mdx` — in-content demo callout.
+**New:** `lib/demos.ts`, `components/landing/DemoCtaPair.tsx`, `components/landing/DemoShowcase.tsx`, `public/demo/{langgraph,ag-ui}-demo.{mp4,webm}` + posters, `content/docs/ag-ui/api/{provide-agent,inject-agent,to-agent,fake-agent}.mdx`, `content/docs/ag-ui/guides/custom-events.mdx`.
 
-**API Reference:**
-- `apps/website/content/docs/ag-ui/api/provide-agent.mdx` (new)
-- `apps/website/content/docs/ag-ui/api/inject-agent.mdx` (new)
-- `apps/website/content/docs/ag-ui/api/to-agent.mdx` (new)
-- `apps/website/content/docs/ag-ui/api/fake-agent.mdx` (new)
-- `apps/website/content/docs/ag-ui/guides/citations.mdx` — add `bridgeCitationsState` cross-link.
+**Modified:** `lib/docs-config.ts` (DocsLibrary fields + ag-ui demoUrl + API section + custom-events guide entry), `components/landing/FinalCTA.tsx`, `components/shared/Nav.tsx` (desktop demo dropdown + mobile entries + docs demo link), `components/shared/Footer.tsx`, `app/page.tsx` (swap LiveDemoFrame → DemoShowcase), `components/docs/DocsSidebar.tsx`, `content/docs/ag-ui/getting-started/{introduction,quickstart}.mdx`, `content/docs/ag-ui/guides/citations.mdx`.
 
-**Custom-events guide:**
-- `apps/website/content/docs/ag-ui/guides/custom-events.mdx` (new)
+**Removed:** `components/landing/LiveDemoFrame.tsx` (after confirming sole importer).
 
 ---
 
-## Data flow (demo link)
-
-`docs-config.ts` (`DocsLibrary.demoUrl`) → consumed by `DocsSidebar.tsx` (desktop) and `Nav.tsx` mobile docs path → renders an external anchor (`target="_blank" rel="noopener noreferrer"`) with analytics tracking matching the existing `trackExternalLinkClick` pattern (e.g. `cta_id: 'docs_sidebar_demo'` / `'mobile_nav_demo'`, `cta_text` from `demoLabel`).
-
 ## Error handling / edge cases
 
-- Libraries without `demoUrl` render no demo link (the common case). Guard with a simple truthiness check.
-- The demo link is external and unauthenticated; no app state depends on it.
-- API mdx pages are static content; the only failure mode is a broken internal cross-link — caught by the website build + any link-check in CI.
+- **Missing video asset:** `DemoShowcase` falls back to poster/screenshot + launch overlay; never a broken `<video>`. Section ships before videos are produced.
+- **Demo iframe cold-load:** the video-first default hides the cold-load entirely; the live iframe mounts only on explicit launch.
+- **Libraries without `demoUrl`:** render no docs demo link (guard on truthiness). Only AG-UI sets it.
+- **FinalCTA per-page overrides:** pages currently passing a custom `primary`/`secondary` keep that behavior; only the default closer renders the pair.
+- **Analytics:** distinct `cta_id`s per demo so the LangGraph/AG-UI split is measurable.
 
 ## Testing / verification
 
-This is a static Next.js docs + mdx change. Verification per workstream:
+Static Next.js site + mdx. Per workstream:
 
-- **Build:** `nx build website` (or the repo's website build target) succeeds with the new mdx pages and nav entries.
-- **Lint/typecheck:** the `docs-config.ts` interface change and the two component edits typecheck (`nx lint website` / `tsc`).
-- **Nav rendering:** the new API Reference section and `custom-events` guide appear in the AG-UI sidebar; the "Live demo" link appears only on AG-UI docs (desktop sidebar + mobile docs tab) and resolves to `https://ag-ui.threadplane.ai`.
-- **Cross-links:** new pages' internal links resolve (no 404s in build).
-- **No regressions:** other libraries' nav is unchanged; global navbar is unchanged.
-- **API docs regen:** `npm run generate-api-docs` produces no unexpected diff (or commit the refreshed `api-docs.json` if it does).
+- **Build:** website build succeeds with new components, mdx pages, and nav entries; no broken internal links.
+- **Lint/typecheck:** `demos.ts`, the two new components, the `DocsLibrary` interface change, and all edited components typecheck and lint clean.
+- **Demo CTAs:** FinalCTA shows two demo buttons + cockpit ghost on a sampled page; navbar shows the Demo dropdown (desktop) and two entries (mobile); footer shows two demo links; each links to the correct host.
+- **Homepage:** `DemoShowcase` renders tabs; default tab shows the video-first state with launch overlay (poster fallback when video absent); launching mounts the live iframe; CTAs resolve.
+- **AG-UI docs:** sidebar (desktop) + mobile docs tab show the "Live demo ↗" link only on AG-UI; introduction/quickstart callouts resolve to `ag-ui.threadplane.ai`.
+- **API reference:** the `API Reference` section appears in the AG-UI sidebar with 4 pages; pages render; `generate-api-docs` yields no unexpected diff.
+- **Custom-events guide:** appears in AG-UI Guides; renders; cross-links resolve.
+- **No regressions:** other libraries' nav unchanged; the chat "See it live"/Hero-screenshot examples links unchanged.
 
-A Playwright/visual smoke is optional; if the website has an existing docs e2e harness, add a minimal assertion that the AG-UI sidebar shows the demo link and the API Reference section. Otherwise rely on build + manual verification.
+If the website has an existing docs/landing e2e harness, add minimal assertions (demo dropdown present; AG-UI sidebar demo link + API section present). Otherwise rely on build + manual verification. Video production is verified by visual review of the recorded clips.
 
 ---
 
 ## Decomposition (for the plan)
 
-Three largely independent workstreams; `docs-config.ts` is the one shared file (sequence its edits to avoid churn):
+Order chosen to minimize churn on the two shared files (`docs-config.ts`, `Nav.tsx`):
 
-- **A — Demo link:** config field + DocsSidebar + Nav mobile + introduction callout.
-- **B — API reference:** 4 API mdx pages + config `API Reference` section + citations cross-link + api-docs regen check.
-- **C — Custom-events guide:** 1 guide mdx + config Guides entry.
+1. **A1 — `demos.ts` + `DemoCtaPair`** (foundation; no behavior change yet).
+2. **A2 — FinalCTA** uses the pair (keep cockpit ghost).
+3. **A3 — Footer** two demo links.
+4. **A4 — Navbar** desktop Demo dropdown + mobile two entries.
+5. **B1 — `DemoShowcase`** component (tabbed, video-first, poster fallback) + swap on homepage; remove `LiveDemoFrame`.
+6. **B2 — Demo video assets** (record/encode/host) — discrete production task; section already ships with posters.
+7. **C1 — `DocsLibrary.demoUrl`** + DocsSidebar + Nav mobile docs link + ag-ui `demoUrl`.
+8. **C2 — AG-UI content callouts** (introduction, quickstart).
+9. **D — API reference**: 4 mdx pages + `docs-config` API section + citations cross-link + api-docs regen.
+10. **E — Custom-events guide**: mdx + `docs-config` guides entry.
 
-Suggested order: A, then B, then C (each appends to `docs-config.ts`, minimizing conflicts). Single PR, or one PR per workstream if review prefers smaller diffs.
+Single PR is feasible but large; recommend splitting into **(i) demo CTAs + homepage (A+B)** and **(ii) AG-UI docs C+D+E** as two PRs for reviewability. Video assets (B2) can be a third, follow-on PR if not ready when (i) merges.

From 4b6317e3a49c5fb62c9e57ef9efffac598d1fc06 Mon Sep 17 00:00:00 2001
From: Brian Love <brian@liveloveapp.com>
Date: Mon, 8 Jun 2026 16:48:07 -0700
Subject: [PATCH 03/15] =?UTF-8?q?docs(plan):=20AG-UI=20demo=20discoverabil?=
 =?UTF-8?q?ity=20+=20docs=20polish=20=E2=80=94=20task-by-task=20plan?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 .../2026-06-07-ag-ui-demo-discoverability.md  | 776 ++++++++++++++++++
 1 file changed, 776 insertions(+)
 create mode 100644 docs/superpowers/plans/2026-06-07-ag-ui-demo-discoverability.md

diff --git a/docs/superpowers/plans/2026-06-07-ag-ui-demo-discoverability.md b/docs/superpowers/plans/2026-06-07-ag-ui-demo-discoverability.md
new file mode 100644
index 000000000..abc24ba22
--- /dev/null
+++ b/docs/superpowers/plans/2026-06-07-ag-ui-demo-discoverability.md
@@ -0,0 +1,776 @@
+# AG-UI Demo Discoverability + Docs Polish — Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Make the AG-UI live demo (`ag-ui.threadplane.ai`) a first-class peer to the LangGraph demo across the marketing site, rebuild the homepage demo into a tabbed video-first showcase, and close the AG-UI docs API-reference + custom-events gaps.
+
+**Architecture:** A single `DEMOS` source of truth feeds a reusable `DemoCtaPair` (two parallel buttons) used by FinalCTA + a new tabbed, video-first `DemoShowcase` homepage section; the global navbar's single "Demo" link becomes a dropdown; the docs config gains an optional per-library `demoUrl` rendered contextually in the AG-UI docs nav; and AG-UI gains 4 API-reference mdx pages + a custom-events guide.
+
+**Tech Stack:** Next.js (App Router) + React (client components, inline styles + `@threadplane/design-tokens`), MDX docs (no frontmatter; `# H1` + `<Callout>`), Nx (`nx build website`, `nx lint website`, `nx e2e website-e2e`), Playwright e2e.
+
+**Reference spec:** `docs/superpowers/specs/2026-06-07-ag-ui-docs-demo-link-design.md`
+
+**Verification note:** The website has no component unit-test runner; verification per task is `nx lint website` + `nx build website` (both must pass), plus targeted Playwright/visual checks where called out. This is a presentational/docs effort — there is no red-green unit TDD. Commit after each task.
+
+**Constraint:** New content authored in this effort must NOT introduce any CopilotKit mention/reference. (The pre-existing ecosystem mention in `introduction.mdx` is untouched.)
+
+**Working dir:** worktree `.claude/worktrees/ag-ui-docs-demo-link` (branch `worktree-ag-ui-docs-demo-link`), off latest `main`.
+
+---
+
+## File structure
+
+**New files:**
+- `apps/website/src/lib/demos.ts` — `DemoTarget` type + `DEMOS` constant (source of truth).
+- `apps/website/src/components/landing/DemoCtaPair.tsx` — two parallel demo buttons.
+- `apps/website/src/components/landing/DemoShowcase.tsx` — tabbed, video-first homepage demo section.
+- `apps/website/content/docs/ag-ui/api/{provide-agent,inject-agent,to-agent,fake-agent}.mdx` — API reference pages.
+- `apps/website/content/docs/ag-ui/guides/custom-events.mdx` — custom-events guide.
+- `apps/website/public/demo/` — video + poster assets (Task 11, follow-on).
+
+**Modified files:**
+- `apps/website/src/components/landing/FinalCTA.tsx`, `apps/website/src/components/shared/Footer.tsx`, `apps/website/src/components/shared/Nav.tsx`, `apps/website/src/app/page.tsx`, `apps/website/src/lib/docs-config.ts`, `apps/website/src/components/docs/DocsSidebar.tsx`, `apps/website/content/docs/ag-ui/getting-started/{introduction,quickstart}.mdx`, `apps/website/content/docs/ag-ui/guides/citations.mdx`.
+
+**Removed:** `apps/website/src/components/landing/LiveDemoFrame.tsx` (Task 6, after confirming `page.tsx` is the sole importer).
+
+**PR boundaries (recommended):** PR-1 = Tasks 1–6 (demo CTAs + homepage). PR-2 = Tasks 7–10 (AG-UI docs). PR-3 = Task 11 (video assets, follow-on; homepage already ships with posters).
+
+---
+
+## Task 1: `DEMOS` source of truth
+
+**Files:**
+- Create: `apps/website/src/lib/demos.ts`
+
+- [ ] **Step 1: Create the constant**
+
+```ts
+// apps/website/src/lib/demos.ts
+export interface DemoTarget {
+  /** Stable key; analytics cta_id suffix uses this (hyphens → underscores). */
+  key: 'langgraph' | 'ag-ui';
+  /** Label without trailing arrow — callers add their own. */
+  label: string;
+  href: string;
+}
+
+export const DEMOS: readonly DemoTarget[] = [
+  { key: 'langgraph', label: 'LangGraph demo', href: 'https://demo.threadplane.ai' },
+  { key: 'ag-ui', label: 'AG-UI demo', href: 'https://ag-ui.threadplane.ai' },
+];
+
+/** `ag-ui` → `ag_ui` for analytics ids. */
+export const demoCtaSuffix = (key: DemoTarget['key']): string => key.replace(/-/g, '_');
+```
+
+- [ ] **Step 2: Verify it compiles**
+
+Run: `npx nx lint website`
+Expected: PASS (no new lint errors).
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add apps/website/src/lib/demos.ts
+git commit -m "feat(website): add DEMOS source of truth for demo CTAs"
+```
+
+---
+
+## Task 2: `DemoCtaPair` component
+
+**Files:**
+- Create: `apps/website/src/components/landing/DemoCtaPair.tsx`
+
+Uses the existing `Button` (`variant: 'primary'|'secondary'|'ghost'`, `size: 'md'|'lg'`, `href`, anchor props) and the analytics client (`trackExternalLinkClick`).
+
+- [ ] **Step 1: Create the component**
+
+```tsx
+// apps/website/src/components/landing/DemoCtaPair.tsx
+'use client';
+import { Button } from '../ui/Button';
+import { DEMOS, demoCtaSuffix } from '../../lib/demos';
+import { trackExternalLinkClick } from '../../lib/analytics/client';
+
+interface Props {
+  /** Analytics surface prefix, e.g. 'final_cta', 'home_demo'. */
+  surface: string;
+  size?: 'md' | 'lg';
+}
+
+/** Renders the LangGraph + AG-UI demos as two parallel CTA buttons. */
+export function DemoCtaPair({ surface, size = 'lg' }: Props) {
+  return (
+    <>
+      {DEMOS.map((demo, i) => (
+        <Button
+          key={demo.key}
+          variant={i === 0 ? 'primary' : 'secondary'}
+          size={size}
+          href={demo.href}
+          target="_blank"
+          rel="noopener noreferrer"
+          onClick={() =>
+            trackExternalLinkClick(demo.href, {
+              surface,
+              cta_id: `${surface}_demo_${demoCtaSuffix(demo.key)}`,
+              cta_text: demo.label,
+            })
+          }
+        >
+          {demo.label} →
+        </Button>
+      ))}
+    </>
+  );
+}
+```
+
+> Note: confirm `trackExternalLinkClick`'s signature/import path against an existing caller (e.g. `Nav.tsx` imports it from `../../lib/analytics/client`). If its options type rejects a free-form `surface` string, pass the `surface` value the existing callers use and keep `cta_id`/`cta_text` identical to the pattern there.
+
+- [ ] **Step 2: Verify**
+
+Run: `npx nx lint website`
+Expected: PASS.
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add apps/website/src/components/landing/DemoCtaPair.tsx
+git commit -m "feat(website): DemoCtaPair — parallel LangGraph + AG-UI demo buttons"
+```
+
+---
+
+## Task 3: FinalCTA uses the demo pair
+
+**Files:**
+- Modify: `apps/website/src/components/landing/FinalCTA.tsx`
+
+Goal: default closer renders the two demo buttons via `DemoCtaPair` AND keeps the cockpit ghost secondary. Pages that pass explicit `primary` keep current behavior.
+
+- [ ] **Step 1: Import the pair**
+
+Add at top of `FinalCTA.tsx`:
+
+```tsx
+import { DemoCtaPair } from './DemoCtaPair';
+```
+
+- [ ] **Step 2: Replace the primary button render with the pair (default path)**
+
+Change the props default so `primary` defaults to `null` (meaning "use the demo pair"), keeping the override path. Replace the button row (currently the `primary` `<Button>` + `secondary` `<Button>`) with:
+
+```tsx
+// props: change `primary = DEFAULT_PRIMARY` → `primary = null`
+// and update the JSDoc for `primary` to: "Override CTA. When omitted, renders the LangGraph + AG-UI demo pair."
+```
+
+Button row becomes:
+
+```tsx
+<div style={{ display: 'flex', justifyContent: 'center', gap: 12, flexWrap: 'wrap', marginBottom: 16 }}>
+  {primary ? (
+    <Button
+      variant="primary"
+      size="lg"
+      href={primary.href}
+      {...((primary as { external?: boolean }).external ? { target: '_blank', rel: 'noopener noreferrer' } : {})}
+    >
+      {primary.label}
+    </Button>
+  ) : (
+    <DemoCtaPair surface="final_cta" size="lg" />
+  )}
+  {secondary ? (
+    <Button
+      variant="ghost"
+      size="lg"
+      href={secondary.href}
+      {...(secondary.external ? { target: '_blank', rel: 'noopener noreferrer' } : {})}
+    >
+      {secondary.label}
+    </Button>
+  ) : null}
+</div>
+```
+
+Delete the now-unused `DEFAULT_PRIMARY` const (keep `DEFAULT_SECONDARY`). Update the `primary` prop type/default to `{ label: string; href: string; external?: boolean } | null` defaulting to `null`.
+
+- [ ] **Step 3: Verify lint + build**
+
+Run: `npx nx lint website && npx nx build website`
+Expected: PASS. (Build compiles all 9 pages using FinalCTA.)
+
+- [ ] **Step 4: Check no page broke its FinalCTA contract**
+
+Run: `grep -rn "FinalCTA" apps/website/src/app | grep -v "import"`
+Expected: pages either use `<FinalCTA />` (now gets the pair) or pass explicit `primary`/`secondary`. Confirm none relied on the removed `DEFAULT_PRIMARY` by name.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add apps/website/src/components/landing/FinalCTA.tsx
+git commit -m "feat(website): FinalCTA renders paired demo CTAs by default"
+```
+
+---
+
+## Task 4: Footer — two demo links
+
+**Files:**
+- Modify: `apps/website/src/components/shared/Footer.tsx` (the single `https://demo.threadplane.ai` anchor around line 180)
+
+- [ ] **Step 1: Replace the single Demo link with two**
+
+Import at top: `import { DEMOS, demoCtaSuffix } from '../../lib/demos';`
+
+Replace the single `<a href="https://demo.threadplane.ai" … >Demo</a>` block with a map over `DEMOS`, preserving the existing anchor styling, hover handlers, and `trackExternalLinkClick`:
+
+```tsx
+{DEMOS.map((demo) => (
+  <a key={demo.key} href={demo.href} className="transition-colors" style={{ color: tokens.colors.textSecondary }}
+    onClick={() => trackExternalLinkClick(demo.href, {
+      surface: 'footer',
+      cta_id: `footer_demo_${demoCtaSuffix(demo.key)}`,
+      cta_text: demo.label,
+    })}
+    onMouseEnter={(e) => (e.currentTarget.style.color = tokens.colors.accent)}
+    onMouseLeave={(e) => (e.currentTarget.style.color = tokens.colors.textSecondary)}>
+    {demo.label}
+  </a>
+))}
+```
+
+- [ ] **Step 2: Verify**
+
+Run: `npx nx lint website`
+Expected: PASS.
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add apps/website/src/components/shared/Footer.tsx
+git commit -m "feat(website): footer lists LangGraph + AG-UI demos"
+```
+
+---
+
+## Task 5: Navbar — Demo dropdown (desktop) + two entries (mobile)
+
+**Files:**
+- Modify: `apps/website/src/components/shared/Nav.tsx`
+
+The `links` array currently has `{ label: 'Demo', href: 'https://demo.threadplane.ai', external: true }`. Replace it with a dropdown on desktop and two list entries on mobile.
+
+- [ ] **Step 1: Remove the single Demo entry from `links`**
+
+Delete the `{ label: 'Demo', … }` object from the `links` array (line ~15). Add import: `import { DEMOS, demoCtaSuffix } from '../../lib/demos';`
+
+- [ ] **Step 2: Add a `DemoDropdown` (desktop) sub-component**
+
+Add inside `Nav.tsx` (above `export function Nav`), reusing the click-outside pattern from `DocsSidebar.tsx`'s `LibraryDropdown`:
+
+```tsx
+function DemoDropdown() {
+  const [open, setOpen] = useState(false);
+  const ref = useRef<HTMLDivElement>(null);
+  useEffect(() => {
+    const handler = (e: MouseEvent) => {
+      if (ref.current && !ref.current.contains(e.target as Node)) setOpen(false);
+    };
+    document.addEventListener('mousedown', handler);
+    return () => document.removeEventListener('mousedown', handler);
+  }, []);
+  return (
+    <div ref={ref} style={{ position: 'relative' }}>
+      <button
+        onClick={() => setOpen((o) => !o)}
+        className="text-sm font-mono transition-colors"
+        style={{ color: tokens.colors.textSecondary, background: 'none', border: 'none', cursor: 'pointer', display: 'inline-flex', alignItems: 'center', gap: 4 }}
+        onMouseEnter={(e) => (e.currentTarget.style.color = tokens.colors.accent)}
+        onMouseLeave={(e) => (e.currentTarget.style.color = tokens.colors.textSecondary)}
+        aria-haspopup="true" aria-expanded={open}
+      >
+        Demo <span style={{ fontSize: 10, transition: 'transform .2s', transform: open ? 'rotate(180deg)' : 'rotate(0)' }}>&#9662;</span>
+      </button>
+      {open && (
+        <div style={{ position: 'absolute', top: '100%', left: 0, marginTop: 8, minWidth: 180, background: tokens.surfaces.surface, border: `1px solid ${tokens.surfaces.border}`, borderRadius: 8, boxShadow: tokens.shadows.md, overflow: 'hidden', zIndex: 60 }}>
+          {DEMOS.map((demo) => (
+            <a key={demo.key} href={demo.href} target="_blank" rel="noopener noreferrer"
+              onClick={() => { setOpen(false); trackExternalLinkClick(demo.href, { surface: 'nav', cta_id: `nav_demo_${demoCtaSuffix(demo.key)}`, cta_text: demo.label }); }}
+              className="text-sm font-mono"
+              style={{ display: 'block', padding: '10px 14px', color: tokens.colors.textSecondary, textDecoration: 'none' }}
+              onMouseEnter={(e) => (e.currentTarget.style.color = tokens.colors.accent)}
+              onMouseLeave={(e) => (e.currentTarget.style.color = tokens.colors.textSecondary)}>
+              {demo.label}
+            </a>
+          ))}
+        </div>
+      )}
+    </div>
+  );
+}
+```
+
+- [ ] **Step 3: Render `DemoDropdown` in the desktop links row**
+
+In the desktop links `<div className="hidden lg:flex …">`, after the `links.map(...)` output and before the GitHub icon, insert `<DemoDropdown />`. (`useState`, `useRef`, `useEffect` are already imported in `Nav.tsx`.)
+
+- [ ] **Step 4: Add the two demo rows to the mobile site-links list**
+
+In the mobile "Site content" block (where `links.map(...)` renders rows), after that map insert:
+
+```tsx
+{DEMOS.map((demo) => (
+  <a key={demo.key} href={demo.href} target="_blank" rel="noopener noreferrer"
+    onClick={() => { trackExternalLinkClick(demo.href, { surface: 'mobile_nav', cta_id: `mobile_nav_demo_${demoCtaSuffix(demo.key)}`, cta_text: demo.label }); setOpen(false); }}
+    style={{ display: 'block', padding: '14px 14px', borderRadius: 8, fontSize: 16, lineHeight: '24px', minHeight: 48, color: tokens.colors.textSecondary, textDecoration: 'none', fontFamily: 'Inter, sans-serif' }}>
+    {demo.label}
+  </a>
+))}
+```
+
+- [ ] **Step 5: Verify lint + build**
+
+Run: `npx nx lint website && npx nx build website`
+Expected: PASS.
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add apps/website/src/components/shared/Nav.tsx
+git commit -m "feat(website): navbar Demo dropdown (LangGraph + AG-UI)"
+```
+
+---
+
+## Task 6: Homepage `DemoShowcase` (tabbed, video-first)
+
+**Files:**
+- Create: `apps/website/src/components/landing/DemoShowcase.tsx`
+- Modify: `apps/website/src/app/page.tsx` (swap `<LiveDemoFrame />` at line ~115)
+- Remove: `apps/website/src/components/landing/LiveDemoFrame.tsx`
+
+Approved composition: eyebrow "See it running", headline "One chat UI. Two runtimes. Same code.", parity subhead, tabs (LangGraph default), large video-first frame with "Launch live demo ▶" overlay → swaps to live iframe, paired CTAs + cockpit ghost, caption. Degrades to poster image when a video asset is absent.
+
+- [ ] **Step 1: Create the component**
+
+```tsx
+// apps/website/src/components/landing/DemoShowcase.tsx
+'use client';
+import { useState } from 'react';
+import { tokens } from '@threadplane/design-tokens';
+import { BrowserFrame } from '../ui/BrowserFrame';
+import { Button } from '../ui/Button';
+import { DemoCtaPair } from './DemoCtaPair';
+import { DEMOS } from '../../lib/demos';
+
+type TabKey = (typeof DEMOS)[number]['key'];
+
+interface DemoMedia {
+  key: TabKey;
+  tabLabel: string;
+  /** Faux URL shown in the frame chrome. */
+  url: string;
+  /** Looping video sources (mp4 + webm). */
+  videoMp4: string;
+  videoWebm: string;
+  poster: string;
+  href: string;
+}
+
+const MEDIA: DemoMedia[] = [
+  { key: 'langgraph', tabLabel: 'LangGraph', url: 'demo.threadplane.ai', videoMp4: '/demo/langgraph-demo.mp4', videoWebm: '/demo/langgraph-demo.webm', poster: '/demo/langgraph-demo-poster.webp', href: DEMOS[0].href },
+  { key: 'ag-ui', tabLabel: 'AG-UI', url: 'ag-ui.threadplane.ai', videoMp4: '/demo/ag-ui-demo.mp4', videoWebm: '/demo/ag-ui-demo.webm', poster: '/demo/ag-ui-demo-poster.webp', href: DEMOS[1].href },
+];
+
+export function DemoShowcase() {
+  const [active, setActive] = useState<TabKey>('langgraph');
+  const [launched, setLaunched] = useState<Set<TabKey>>(new Set());
+  const media = MEDIA.find((m) => m.key === active)!;
+  const isLaunched = launched.has(active);
+  const launch = () => setLaunched((prev) => new Set(prev).add(active));
+
+  return (
+    <div style={{ maxWidth: 760, margin: '0 auto', textAlign: 'center' }}>
+      <p style={{ fontFamily: tokens.typography.fontMono, fontSize: 12, fontWeight: 700, letterSpacing: '0.08em', textTransform: 'uppercase', color: tokens.colors.accent, margin: 0 }}>See it running</p>
+      <h2 style={{ fontFamily: tokens.typography.h2.family, fontSize: tokens.typography.h2.size, lineHeight: tokens.typography.h2.line, fontWeight: 700, color: tokens.colors.textPrimary, margin: '10px 0 8px', letterSpacing: '-0.015em' }}>
+        One chat UI. Two runtimes. Same code.
+      </h2>
+      <p style={{ fontFamily: tokens.typography.bodyLg.family, fontSize: tokens.typography.bodyLg.size, lineHeight: tokens.typography.bodyLg.line, color: tokens.colors.textSecondary, maxWidth: 560, margin: '0 auto 20px' }}>
+        The identical Threadplane chat surface, running live against a LangGraph backend and an AG-UI backend. Switch tabs to compare — the front end never changes.
+      </p>
+
+      {/* Tabs */}
+      <div role="tablist" aria-label="Demo backend" style={{ display: 'flex', gap: 6, justifyContent: 'center', marginBottom: 12 }}>
+        {MEDIA.map((m) => {
+          const on = m.key === active;
+          return (
+            <button key={m.key} role="tab" aria-selected={on} onClick={() => setActive(m.key)}
+              style={{ fontFamily: 'Inter, sans-serif', fontSize: 13, fontWeight: 600, padding: '9px 16px', borderRadius: 8, border: 'none', cursor: 'pointer',
+                background: on ? tokens.colors.accent : tokens.colors.accentSurface, color: on ? tokens.colors.textInverted : tokens.colors.textMuted }}>
+              {m.tabLabel}
+            </button>
+          );
+        })}
+      </div>
+
+      {/* Frame */}
+      <BrowserFrame url={media.url} elevation="lg">
+        <div style={{ position: 'relative', width: '100%', aspectRatio: '16 / 10', background: '#15161f' }}>
+          {isLaunched ? (
+            <iframe src={media.href} title={`${media.tabLabel} live demo`} loading="lazy"
+              style={{ width: '100%', height: '100%', border: 'none', display: 'block' }} />
+          ) : (
+            <>
+              <video key={media.key} autoPlay muted loop playsInline poster={media.poster}
+                style={{ width: '100%', height: '100%', objectFit: 'cover', display: 'block' }}>
+                <source src={media.videoWebm} type="video/webm" />
+                <source src={media.videoMp4} type="video/mp4" />
+              </video>
+              <button onClick={launch} aria-label={`Launch ${media.tabLabel} live demo`}
+                style={{ position: 'absolute', inset: 0, display: 'flex', flexDirection: 'column', alignItems: 'center', justifyContent: 'center', gap: 10,
+                  background: 'linear-gradient(180deg, rgba(16,18,32,.15), rgba(16,18,32,.45))', border: 'none', cursor: 'pointer' }}>
+                <span style={{ width: 56, height: 56, borderRadius: '50%', background: 'rgba(255,255,255,.95)', display: 'flex', alignItems: 'center', justifyContent: 'center', color: '#15161f', fontSize: 22 }}>▶</span>
+                <span style={{ fontFamily: 'Inter, sans-serif', fontWeight: 600, fontSize: 13, color: '#fff', background: 'rgba(0,0,0,.5)', padding: '8px 14px', borderRadius: 8 }}>Launch live demo</span>
+              </button>
+            </>
+          )}
+        </div>
+      </BrowserFrame>
+
+      {/* CTAs */}
+      <div style={{ display: 'flex', gap: 10, justifyContent: 'center', flexWrap: 'wrap', marginTop: 18 }}>
+        <DemoCtaPair surface="home_demo" size="lg" />
+        <Button variant="ghost" size="lg" href="https://cockpit.threadplane.ai" target="_blank" rel="noopener noreferrer">
+          See each feature in action →
+        </Button>
+      </div>
+      <p style={{ fontFamily: tokens.typography.caption.family, fontSize: tokens.typography.caption.size, color: tokens.colors.textMuted, margin: '14px 0 0' }}>
+        Video loops instantly · click Launch to open the live, interactive demo · MIT · no signup
+      </p>
+    </div>
+  );
+}
+```
+
+> The `<video>` falls back to its `poster` when no source loads, so the section renders before Task 11's assets exist. Confirm `tokens.typography.caption` / `tokens.colors.textInverted` / `tokens.colors.accentSurface` exist (they are used elsewhere in `FinalCTA.tsx` / `Nav.tsx`); if a token name differs, match the one those files use.
+
+- [ ] **Step 2: Swap on the homepage**
+
+In `apps/website/src/app/page.tsx`:
+
+1. Replace the import `import { LiveDemoFrame } from '../components/landing/LiveDemoFrame';` with `import { DemoShowcase } from '../components/landing/DemoShowcase';`. Confirm `Section`, `Container`, and `BrowserFrame` are imported (add any missing — they are used elsewhere on the page / in components).
+
+2. The demo currently lives as `visual={<LiveDemoFrame />}` on the "production patterns" `FeatureBlock` (eyebrow `Ship`, headline "Patterns built for production, not demos."). That block's copy must survive. Repoint **its** visual to the existing static canonical screenshot (already shipped, used in `Hero.tsx`) so the block stays intact without the live iframe:
+
+```tsx
+visual={
+  <BrowserFrame url="demo.threadplane.ai" elevation="lg">
+    <img
+      src="/screenshots/canonical-demo-generative-ui.webp"
+      alt="Threadplane chat rendering a live generative-UI dashboard"
+      style={{ display: 'block', width: '100%', height: 'auto' }}
+      loading="lazy"
+      decoding="async"
+    />
+  </BrowserFrame>
+}
+```
+
+3. Add the interactive showcase as its **own full-width Section**, placed immediately after the hero block (before the first `FeatureBlock`):
+
+```tsx
+<Section surface="canvas">
+  <Container>
+    <DemoShowcase />
+  </Container>
+</Section>
+```
+
+`DemoShowcase` owns its own `<h2>` heading, so no `ariaLabelledBy` wiring is needed on this `Section`.
+
+- [ ] **Step 3: Remove `LiveDemoFrame`**
+
+Confirm sole importer, then delete:
+
+```bash
+grep -rn "LiveDemoFrame" apps/website/src
+# expect: only the (now-removed) page.tsx import and the component file
+git rm apps/website/src/components/landing/LiveDemoFrame.tsx
+```
+
+- [ ] **Step 4: Verify lint + build**
+
+Run: `npx nx lint website && npx nx build website`
+Expected: PASS. The homepage compiles; `DemoShowcase` renders with posters (videos 404 until Task 11 — acceptable, `<video>` shows poster).
+
+- [ ] **Step 5: Visual check (dev server)**
+
+Run: `npx nx serve website` (or the repo's dev command), open the homepage, confirm: tabs switch; the launch overlay appears; clicking Launch mounts the live iframe; CTAs link correctly. Stop the server.
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add apps/website/src/components/landing/DemoShowcase.tsx apps/website/src/app/page.tsx
+git rm apps/website/src/components/landing/LiveDemoFrame.tsx
+git commit -m "feat(website): tabbed video-first DemoShowcase on homepage"
+```
+
+---
+
+## Task 7: `DocsLibrary.demoUrl` + contextual docs demo link
+
+**Files:**
+- Modify: `apps/website/src/lib/docs-config.ts` (interface + ag-ui entry)
+- Modify: `apps/website/src/components/docs/DocsSidebar.tsx` (desktop)
+- Modify: `apps/website/src/components/shared/Nav.tsx` (mobile docs path)
+
+- [ ] **Step 1: Extend the interface + set ag-ui `demoUrl`**
+
+In `docs-config.ts`, add to `interface DocsLibrary` (after `description`):
+
+```ts
+  /** Optional external live-demo URL, surfaced contextually in docs nav. */
+  demoUrl?: string;
+  /** Optional label override for the demo link. Defaults to 'Live demo'. */
+  demoLabel?: string;
+```
+
+On the `id: 'ag-ui'` library object, add: `demoUrl: 'https://ag-ui.threadplane.ai',` (e.g. right after its `description`).
+
+- [ ] **Step 2: Render the link in the desktop sidebar**
+
+In `DocsSidebar.tsx`, just below `<LibraryDropdown activeLibrary={activeLibrary} />`, add:
+
+```tsx
+{libConfig?.demoUrl && (
+  <div className="px-4 mb-4">
+    <a href={libConfig.demoUrl} target="_blank" rel="noopener noreferrer"
+      className="w-full text-left px-3 py-2 rounded-lg text-sm flex items-center justify-between"
+      style={{ background: tokens.colors.accentSurface, color: tokens.colors.accent, border: `1px solid ${tokens.surfaces.border}`, textDecoration: 'none', fontWeight: 600 }}>
+      <span>{libConfig.demoLabel ?? 'Live demo'}</span>
+      <span aria-hidden="true">↗</span>
+    </a>
+  </div>
+)}
+```
+
+(`libConfig` is already in scope in `DocsSidebar`; `tokens` is imported.)
+
+- [ ] **Step 3: Render the link in the mobile docs nav**
+
+In `Nav.tsx`, inside the mobile docs block (`mobileTab === 'docs' && isDocsPage && currentLib`), above the `currentLib.sections.map(...)`, add:
+
+```tsx
+{currentLib.demoUrl && (
+  <a href={currentLib.demoUrl} target="_blank" rel="noopener noreferrer"
+    onClick={() => { trackExternalLinkClick(currentLib.demoUrl!, { surface: 'mobile_nav', cta_id: `mobile_nav_docs_demo_${currentLib.id}`, cta_text: currentLib.demoLabel ?? 'Live demo' }); setOpen(false); }}
+    style={{ display: 'flex', alignItems: 'center', justifyContent: 'space-between', padding: '12px 14px', borderRadius: 8, minHeight: 44, color: tokens.colors.accent, background: tokens.colors.accentSurface, textDecoration: 'none', fontFamily: 'Inter, sans-serif', fontWeight: 600 }}>
+    <span>{currentLib.demoLabel ?? 'Live demo'}</span><span aria-hidden="true">↗</span>
+  </a>
+)}
+```
+
+- [ ] **Step 4: Verify lint + build**
+
+Run: `npx nx lint website && npx nx build website`
+Expected: PASS.
+
+- [ ] **Step 5: Visual check**
+
+Dev server: AG-UI docs show "Live demo ↗" in the sidebar (desktop) and mobile docs tab; other libraries show none.
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add apps/website/src/lib/docs-config.ts apps/website/src/components/docs/DocsSidebar.tsx apps/website/src/components/shared/Nav.tsx
+git commit -m "feat(website): contextual AG-UI live-demo link in docs nav"
+```
+
+---
+
+## Task 8: AG-UI content demo callouts
+
+**Files:**
+- Modify: `apps/website/content/docs/ag-ui/getting-started/introduction.mdx`
+- Modify: `apps/website/content/docs/ag-ui/getting-started/quickstart.mdx`
+
+Use the existing `<Callout type="tip" title="…">` mdx component (no import needed — provided by MdxRenderer). Do NOT add any CopilotKit reference.
+
+- [ ] **Step 1: Add a demo callout to introduction.mdx**
+
+After the existing intro `<Callout type="info" title="What is AG-UI?">…</Callout>` block (ends ~line 9), add:
+
+```mdx
+<Callout type="tip" title="See it live">
+The [AG-UI demo](https://ag-ui.threadplane.ai) runs this exact chat surface against an AG-UI backend — streaming, tool calls, and generative UI included. Compare it side by side with the [LangGraph demo](https://demo.threadplane.ai).
+</Callout>
+```
+
+- [ ] **Step 2: Add a demo callout to quickstart.mdx**
+
+After the `<Callout type="info" title="Prerequisites">…</Callout>` block (~line 7), add:
+
+```mdx
+<Callout type="tip" title="Try it first">
+Want to see the finished result before you build? Open the live [AG-UI demo](https://ag-ui.threadplane.ai).
+</Callout>
+```
+
+- [ ] **Step 3: Verify build (mdx compiles, links resolve)**
+
+Run: `npx nx build website`
+Expected: PASS (no MDX parse errors, no broken-link failures).
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add apps/website/content/docs/ag-ui/getting-started/introduction.mdx apps/website/content/docs/ag-ui/getting-started/quickstart.mdx
+git commit -m "docs(ag-ui): add live-demo callouts to introduction + quickstart"
+```
+
+---
+
+## Task 9: AG-UI API reference pages + nav
+
+**Files:**
+- Create: `apps/website/content/docs/ag-ui/api/provide-agent.mdx`
+- Create: `apps/website/content/docs/ag-ui/api/inject-agent.mdx`
+- Create: `apps/website/content/docs/ag-ui/api/to-agent.mdx`
+- Create: `apps/website/content/docs/ag-ui/api/fake-agent.mdx`
+- Modify: `apps/website/src/lib/docs-config.ts` (add `API Reference` section to ag-ui)
+- Modify: `apps/website/content/docs/ag-ui/guides/citations.mdx` (cross-link `bridgeCitationsState`)
+
+Author prose mirroring `apps/website/content/docs/langgraph/api/*.mdx` voice (concise, `# symbolName()` H1, intro paragraph, a usage code block, sub-sections). Source the exact signatures from `libs/ag-ui/src/public-api.ts`. No CopilotKit references.
+
+Required content per page (each begins with the H1 shown, then prose + a `ts` code block):
+
+- [ ] **Step 1: `provide-agent.mdx`** — `# provideAgent()`. Cover: registers the singleton AG-UI agent config consumed by every `injectAgent()`; the `AgentConfig` fields (`url`, `agentId?`, `threadId?`, `headers?`, `telemetry?` — verify exact names against `public-api.ts`); accepts a config object or a factory `() => AgentConfig`; returns `Provider[]` for `ApplicationConfig.providers`. Include a `bootstrapApplication` usage snippet. Cross-link `injectAgent()`.
+
+- [ ] **Step 2: `inject-agent.mdx`** — `# injectAgent()`. Cover: no-args; call in an injection context; returns the runtime-neutral `Agent` (note AG-UI returns an `AgUiAgent` which extends `Agent` with `customEvents: Signal<CustomStreamEvent[]>`); list the signal surface (`status`, `messages`, `toolCalls`, `state`, `interrupt`, `customEvents`, …) and actions (`submit`, `stop`, `regenerate`). Cross-link the [custom-events guide](/docs/ag-ui/guides/custom-events) and `provideAgent()`.
+
+- [ ] **Step 3: `to-agent.mdx`** — `# toAgent()`. Cover: the lower-level adapter — `toAgent(source: AbstractAgent, options?: ToAgentOptions): AgUiAgent` — wraps a raw AG-UI `AbstractAgent` into the neutral contract; `ToAgentOptions` (`telemetry?`); document `CustomStreamEvent` (`{ name: string; data: unknown }`) here as the element type of `AgUiAgent.customEvents`. Note `provideAgent` is the DI-friendly wrapper most apps use; reach for `toAgent` when you construct the `AbstractAgent` yourself.
+
+- [ ] **Step 4: `fake-agent.mdx`** — `# FakeAgent`. Cover: the in-process test double; `provideFakeAgent(config?: FakeAgentConfig)` provider + the `FakeAgent` class for direct use; the canned stream/config options (verify `FakeAgentConfig` fields incl. `reasoningTokens` against source). Cross-link the [Fake Agent guide](/docs/ag-ui/guides/fake-agent) and [Testing guide](/docs/ag-ui/guides/testing).
+
+- [ ] **Step 5: Wire the nav section** — in `docs-config.ts`, in the `id: 'ag-ui'` library `sections`, after the `Reference` section add:
+
+```ts
+{
+  title: 'API Reference',
+  id: 'api',
+  color: 'blue',
+  pages: [
+    { title: 'provideAgent()', slug: 'provide-agent', section: 'api' },
+    { title: 'injectAgent()', slug: 'inject-agent', section: 'api' },
+    { title: 'toAgent()', slug: 'to-agent', section: 'api' },
+    { title: 'FakeAgent', slug: 'fake-agent', section: 'api' },
+  ],
+},
+```
+
+- [ ] **Step 6: Cross-link `bridgeCitationsState`** — in `guides/citations.mdx`, add a short note where citations state is discussed:
+
+```mdx
+The `bridgeCitationsState(thread, messages)` helper merges thread-level citation state onto the message list; import it from `@threadplane/ag-ui` when you assemble messages yourself.
+```
+
+- [ ] **Step 7: Verify build + nav**
+
+Run: `npx nx build website`
+Expected: PASS; the 4 pages compile and resolve at `/docs/ag-ui/api/<slug>`; sidebar shows the new `API Reference` section.
+
+- [ ] **Step 8: Refresh generated API JSON (commit only if changed)**
+
+Run: `npm run generate-api-docs`
+Then: `git status --porcelain apps/website/content/docs/ag-ui/api/api-docs.json`
+If changed, include it in the commit; otherwise leave it.
+
+- [ ] **Step 9: Commit**
+
+```bash
+git add apps/website/content/docs/ag-ui/api apps/website/src/lib/docs-config.ts apps/website/content/docs/ag-ui/guides/citations.mdx
+git commit -m "docs(ag-ui): API reference pages + nav section"
+```
+
+---
+
+## Task 10: AG-UI custom-events guide
+
+**Files:**
+- Create: `apps/website/content/docs/ag-ui/guides/custom-events.mdx`
+- Modify: `apps/website/src/lib/docs-config.ts` (add to ag-ui Guides section)
+
+Author in AG-UI doc voice (no fabricated anecdotes, trimmed register, no CopilotKit reference).
+
+- [ ] **Step 1: Write the guide**
+
+`# Custom Events` H1. Required sections/content:
+- Intro: AG-UI `CUSTOM` events (other than `on_interrupt`) accumulate into `AgUiAgent.customEvents` — a `Signal<CustomStreamEvent[]>` where `CustomStreamEvent = { name: string; data: unknown }`. The list resets on `RUN_STARTED`.
+- "Where they come from": a LangGraph node calling `get_stream_writer()` and emitting with `stream_mode='custom'` becomes an AG-UI `CUSTOM` event becomes an entry in `customEvents()`. Include a small Python emit snippet and the matching wire shape.
+- "Reading them in Angular": a worked snippet using `injectAgent()` and an `effect`/`computed` over `agent.customEvents()` to drive live/progressive a2ui surface updates during a run.
+- "Relation to interrupts": `on_interrupt` is handled specially (surfaced via `agent.interrupt`), so it does NOT appear in `customEvents`. Cross-link the [Interrupts guide](/docs/ag-ui/guides/interrupts).
+- Cross-links: [Architecture](/docs/ag-ui/concepts/architecture), [Event Mapping](/docs/ag-ui/reference/event-mapping) (the CUSTOM row), [injectAgent()](/docs/ag-ui/api/inject-agent).
+
+- [ ] **Step 2: Add to nav**
+
+In `docs-config.ts`, in the ag-ui `Guides` section `pages`, add after the `citations` entry:
+
+```ts
+{ title: 'Custom Events', slug: 'custom-events', section: 'guides' },
+```
+
+- [ ] **Step 3: Verify build**
+
+Run: `npx nx build website`
+Expected: PASS; guide resolves at `/docs/ag-ui/guides/custom-events`, cross-links valid, sidebar shows it.
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add apps/website/content/docs/ag-ui/guides/custom-events.mdx apps/website/src/lib/docs-config.ts
+git commit -m "docs(ag-ui): custom-events guide (live a2ui streaming)"
+```
+
+---
+
+## Task 11: Demo video assets (follow-on)
+
+**Files:**
+- Create: `apps/website/public/demo/langgraph-demo.mp4`, `.webm`, `langgraph-demo-poster.webp`
+- Create: `apps/website/public/demo/ag-ui-demo.mp4`, `.webm`, `ag-ui-demo-poster.webp`
+
+This task produces the recorded clips `DemoShowcase` references. The homepage already ships (Task 6) with posters; this upgrades it. Can land as a separate PR.
+
+- [ ] **Step 1: Record each demo** — capture a ~15–25s screen recording of a real run on each live demo (a representative prompt → streaming answer → an a2ui/generative-UI surface rendering). Use `demo.threadplane.ai` (LangGraph) and `ag-ui.threadplane.ai` (AG-UI). Trim to a clean loop.
+
+- [ ] **Step 2: Encode small + extract poster** — produce H.264 mp4 + VP9 webm (target < 2–3 MB each, muted, ~1280×800), and a first-frame `.webp` poster. Example:
+
+```bash
+ffmpeg -i raw-langgraph.mov -vf "scale=1280:-2" -an -c:v libx264 -crf 30 -movflags +faststart apps/website/public/demo/langgraph-demo.mp4
+ffmpeg -i raw-langgraph.mov -vf "scale=1280:-2" -an -c:v libvpx-vp9 -crf 36 -b:v 0 apps/website/public/demo/langgraph-demo.webm
+ffmpeg -i raw-langgraph.mov -vframes 1 -vf "scale=1280:-2" apps/website/public/demo/langgraph-demo-poster.webp
+# repeat for ag-ui-demo.*
+```
+
+- [ ] **Step 3: Verify** — filenames match the paths in `DemoShowcase.MEDIA`; `nx build website`; dev server confirms each tab plays its loop and the launch overlay still swaps to the live iframe.
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add apps/website/public/demo
+git commit -m "feat(website): recorded demo videos for the homepage showcase"
+```
+
+---
+
+## Final verification (after all tasks)
+
+- [ ] `npx nx lint website` — PASS
+- [ ] `npx nx build website` — PASS
+- [ ] Manual: navbar Demo dropdown (desktop) + two mobile entries; footer two demo links; FinalCTA shows the pair + cockpit ghost on a sampled page; homepage `DemoShowcase` tabs/launch work; AG-UI docs sidebar shows the live-demo link + the new API Reference section + custom-events guide; other libraries unchanged.
+- [ ] If a website e2e harness exists: add/confirm a Playwright assertion for (a) the navbar Demo dropdown and (b) the AG-UI sidebar demo link + API section. Otherwise note manual verification in the PR.
+- [ ] Finish via superpowers:finishing-a-development-branch (PR split per the boundaries above).

From 2ad7b059fd4bd6ec4cb14738e7435ad48895746a Mon Sep 17 00:00:00 2001
From: Brian Love <brian@liveloveapp.com>
Date: Mon, 8 Jun 2026 16:55:11 -0700
Subject: [PATCH 04/15] feat(website): add DEMOS source of truth for demo CTAs

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 apps/website/src/lib/demos.ts | 16 ++++++++++++++++
 1 file changed, 16 insertions(+)
 create mode 100644 apps/website/src/lib/demos.ts

diff --git a/apps/website/src/lib/demos.ts b/apps/website/src/lib/demos.ts
new file mode 100644
index 000000000..d4cc54ec9
--- /dev/null
+++ b/apps/website/src/lib/demos.ts
@@ -0,0 +1,16 @@
+// apps/website/src/lib/demos.ts
+export interface DemoTarget {
+  /** Stable key; analytics cta_id suffix uses this (hyphens → underscores). */
+  key: 'langgraph' | 'ag-ui';
+  /** Label without trailing arrow — callers add their own. */
+  label: string;
+  href: string;
+}
+
+export const DEMOS: readonly DemoTarget[] = [
+  { key: 'langgraph', label: 'LangGraph demo', href: 'https://demo.threadplane.ai' },
+  { key: 'ag-ui', label: 'AG-UI demo', href: 'https://ag-ui.threadplane.ai' },
+];
+
+/** `ag-ui` → `ag_ui` for analytics ids. */
+export const demoCtaSuffix = (key: DemoTarget['key']): string => key.replace(/-/g, '_');

From 6f5e72b22e8d3ea4f03351b3c8d5bfc927a691e6 Mon Sep 17 00:00:00 2001
From: Brian Love <brian@liveloveapp.com>
Date: Mon, 8 Jun 2026 17:09:21 -0700
Subject: [PATCH 05/15] =?UTF-8?q?feat(website):=20DemoCtaPair=20=E2=80=94?=
 =?UTF-8?q?=20parallel=20LangGraph=20+=20AG-UI=20demo=20buttons?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 .../src/components/landing/DemoCtaPair.tsx    | 38 +++++++++++++++++++
 apps/website/src/lib/analytics/events.ts      |  9 ++++-
 2 files changed, 45 insertions(+), 2 deletions(-)
 create mode 100644 apps/website/src/components/landing/DemoCtaPair.tsx

diff --git a/apps/website/src/components/landing/DemoCtaPair.tsx b/apps/website/src/components/landing/DemoCtaPair.tsx
new file mode 100644
index 000000000..986e91b35
--- /dev/null
+++ b/apps/website/src/components/landing/DemoCtaPair.tsx
@@ -0,0 +1,38 @@
+'use client';
+import { Button } from '../ui/Button';
+import { DEMOS, demoCtaSuffix } from '../../lib/demos';
+import { trackExternalLinkClick } from '../../lib/analytics/client';
+import type { AnalyticsSurface, CtaId } from '../../lib/analytics/events';
+
+interface Props {
+  /** Analytics surface prefix, e.g. 'final_cta', 'home_demo'. */
+  surface: string;
+  size?: 'md' | 'lg';
+}
+
+/** Renders the LangGraph + AG-UI demos as two parallel CTA buttons. */
+export function DemoCtaPair({ surface, size = 'lg' }: Props) {
+  return (
+    <>
+      {DEMOS.map((demo, i) => (
+        <Button
+          key={demo.key}
+          variant={i === 0 ? 'primary' : 'secondary'}
+          size={size}
+          href={demo.href}
+          target="_blank"
+          rel="noopener noreferrer"
+          onClick={() =>
+            trackExternalLinkClick(demo.href, {
+              surface: surface as AnalyticsSurface,
+              cta_id: `${surface}_demo_${demoCtaSuffix(demo.key)}` as CtaId,
+              cta_text: demo.label,
+            })
+          }
+        >
+          {demo.label} →
+        </Button>
+      ))}
+    </>
+  );
+}
diff --git a/apps/website/src/lib/analytics/events.ts b/apps/website/src/lib/analytics/events.ts
index ee66985a4..5d06529f0 100644
--- a/apps/website/src/lib/analytics/events.ts
+++ b/apps/website/src/lib/analytics/events.ts
@@ -31,6 +31,7 @@ export type AnalyticsSurface =
   | 'mobile_nav'
   | 'footer'
   | 'home'
+  | 'home_demo'
   | 'home_whitepaper'
   | 'pricing'
   | 'docs'
@@ -38,7 +39,8 @@ export type AnalyticsSurface =
   | 'library_landing'
   | 'solution'
   | 'toast'
-  | 'contact';
+  | 'contact'
+  | 'final_cta';
 
 /**
  * Stable identifiers for marketing CTAs. New CTAs must be added to this
@@ -80,7 +82,10 @@ export type CtaId =
   // Nav + footer derive ids from labels at runtime
   | `nav_${string}`
   | `mobile_nav_${string}`
-  | `footer_${string}`;
+  | `footer_${string}`
+  // Landing section CTAs derive ids from surface + demo key at runtime
+  | `final_cta_${string}`
+  | `home_demo_${string}`;
 
 export type AnalyticsLibrary = 'langgraph' | 'render' | 'chat' | 'unknown';
 

From 0b009719518a8495dee71c6e4db90232e7adbae4 Mon Sep 17 00:00:00 2001
From: Brian Love <brian@liveloveapp.com>
Date: Mon, 8 Jun 2026 17:25:18 -0700
Subject: [PATCH 06/15] feat(website): FinalCTA renders paired demo CTAs by
 default

---
 .../src/components/landing/FinalCTA.tsx       | 38 +++++++++----------
 1 file changed, 17 insertions(+), 21 deletions(-)

diff --git a/apps/website/src/components/landing/FinalCTA.tsx b/apps/website/src/components/landing/FinalCTA.tsx
index f84c4c106..ab06d7cc5 100644
--- a/apps/website/src/components/landing/FinalCTA.tsx
+++ b/apps/website/src/components/landing/FinalCTA.tsx
@@ -2,27 +2,27 @@ import { tokens } from '@threadplane/design-tokens';
 import { Container } from '../ui/Container';
 import { Section } from '../ui/Section';
 import { Button } from '../ui/Button';
+import { DemoCtaPair } from './DemoCtaPair';
 
 interface FinalCTAProps {
   /** Headline. Defaults to the homepage closer. */
   headline?: string;
   /** Sub-headline. Defaults to the homepage closer. */
   subtext?: string;
-  /** Primary CTA. Defaults to "Try the demo →" → demo.threadplane.ai. */
-  primary?: { label: string; href: string; external?: boolean };
+  /** Override CTA. When omitted, renders the LangGraph + AG-UI demo pair. */
+  primary?: { label: string; href: string; external?: boolean } | null;
   /** Optional secondary CTA. Defaults to "See each feature in action →" → cockpit. */
   secondary?: { label: string; href: string; external?: boolean } | null;
   /** Optional trailing caption. Defaults to MIT line. Pass null to hide. */
   caption?: string | null;
 }
 
-const DEFAULT_PRIMARY = { label: 'Try the demo →', href: 'https://demo.threadplane.ai', external: true };
 const DEFAULT_SECONDARY = { label: 'See each feature in action →', href: 'https://cockpit.threadplane.ai', external: true };
 
 export function FinalCTA({
   headline = 'Stop stalling on agentic Angular.',
   subtext = 'Install the framework, read the docs, and have a streaming chat in your app this afternoon.',
-  primary = DEFAULT_PRIMARY,
+  primary = null,
   secondary = DEFAULT_SECONDARY,
   caption = 'MIT · No signup required · App telemetry off by default',
 }: FinalCTAProps = {}) {
@@ -58,23 +58,19 @@ export function FinalCTA({
           >
             {subtext}
           </p>
-          <div
-            style={{
-              display: 'flex',
-              justifyContent: 'center',
-              gap: 12,
-              flexWrap: 'wrap',
-              marginBottom: 16,
-            }}
-          >
-            <Button
-              variant="primary"
-              size="lg"
-              href={primary.href}
-              {...((primary as { external?: boolean }).external ? { target: '_blank', rel: 'noopener noreferrer' } : {})}
-            >
-              {primary.label}
-            </Button>
+          <div style={{ display: 'flex', justifyContent: 'center', gap: 12, flexWrap: 'wrap', marginBottom: 16 }}>
+            {primary ? (
+              <Button
+                variant="primary"
+                size="lg"
+                href={primary.href}
+                {...((primary as { external?: boolean }).external ? { target: '_blank', rel: 'noopener noreferrer' } : {})}
+              >
+                {primary.label}
+              </Button>
+            ) : (
+              <DemoCtaPair surface="final_cta" size="lg" />
+            )}
             {secondary ? (
               <Button
                 variant="ghost"

From e2bfb902477d2a2c7a6238807e5a431ba5d227ea Mon Sep 17 00:00:00 2001
From: Brian Love <brian@liveloveapp.com>
Date: Mon, 8 Jun 2026 17:29:29 -0700
Subject: [PATCH 07/15] feat(website): footer lists LangGraph + AG-UI demos

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 apps/website/src/components/shared/Footer.tsx | 23 +++++++++++--------
 1 file changed, 13 insertions(+), 10 deletions(-)

diff --git a/apps/website/src/components/shared/Footer.tsx b/apps/website/src/components/shared/Footer.tsx
index 120320494..f6d564357 100644
--- a/apps/website/src/components/shared/Footer.tsx
+++ b/apps/website/src/components/shared/Footer.tsx
@@ -5,6 +5,7 @@ import { tokens } from '@threadplane/design-tokens';
 import { analyticsEvents } from '../../lib/analytics/events';
 import { track, trackCtaClick, trackExternalLinkClick } from '../../lib/analytics/client';
 import { SHORT_POSITIONING_DESCRIPTION } from '../../lib/positioning';
+import { DEMOS, demoCtaSuffix } from '../../lib/demos';
 import { LogoMark } from '../ui/LogoMark';
 import { Button } from '../ui/Button';
 import { Eyebrow } from '../ui/Eyebrow';
@@ -177,16 +178,18 @@ export function Footer() {
               onMouseLeave={(e) => (e.currentTarget.style.color = tokens.colors.textSecondary)}>
               API Reference
             </Link>
-            <a href="https://demo.threadplane.ai" className="transition-colors" style={{ color: tokens.colors.textSecondary }}
-              onClick={() => trackExternalLinkClick('https://demo.threadplane.ai', {
-                surface: 'footer',
-                cta_id: 'footer_demo',
-                cta_text: 'Demo',
-              })}
-              onMouseEnter={(e) => (e.currentTarget.style.color = tokens.colors.accent)}
-              onMouseLeave={(e) => (e.currentTarget.style.color = tokens.colors.textSecondary)}>
-              Demo
-            </a>
+            {DEMOS.map((demo) => (
+              <a key={demo.key} href={demo.href} className="transition-colors" style={{ color: tokens.colors.textSecondary }}
+                onClick={() => trackExternalLinkClick(demo.href, {
+                  surface: 'footer',
+                  cta_id: `footer_demo_${demoCtaSuffix(demo.key)}`,
+                  cta_text: demo.label,
+                })}
+                onMouseEnter={(e) => (e.currentTarget.style.color = tokens.colors.accent)}
+                onMouseLeave={(e) => (e.currentTarget.style.color = tokens.colors.textSecondary)}>
+                {demo.label}
+              </a>
+            ))}
             <a href="https://cockpit.threadplane.ai" className="transition-colors" style={{ color: tokens.colors.textSecondary }}
               onClick={() => trackExternalLinkClick('https://cockpit.threadplane.ai', {
                 surface: 'footer',

From da02289e650d837dc110fb8af8b128ff7954a186 Mon Sep 17 00:00:00 2001
From: Brian Love <brian@liveloveapp.com>
Date: Mon, 8 Jun 2026 17:33:41 -0700
Subject: [PATCH 08/15] feat(website): navbar Demo dropdown (LangGraph + AG-UI)

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 apps/website/src/components/shared/Nav.tsx | 52 +++++++++++++++++++++-
 1 file changed, 50 insertions(+), 2 deletions(-)

diff --git a/apps/website/src/components/shared/Nav.tsx b/apps/website/src/components/shared/Nav.tsx
index c4c5b75a1..d80b4c68d 100644
--- a/apps/website/src/components/shared/Nav.tsx
+++ b/apps/website/src/components/shared/Nav.tsx
@@ -1,5 +1,5 @@
 'use client';
-import { useState, useEffect } from 'react';
+import { useState, useEffect, useRef } from 'react';
 import Link from 'next/link';
 import { usePathname } from 'next/navigation';
 import { tokens } from '@threadplane/design-tokens';
@@ -7,12 +7,12 @@ import { docsConfig } from '../../lib/docs-config';
 import { trackCtaClick, trackExternalLinkClick } from '../../lib/analytics/client';
 import { LogoMark } from '../ui/LogoMark';
 import { Button } from '../ui/Button';
+import { DEMOS, demoCtaSuffix } from '../../lib/demos';
 
 const links = [
   { label: 'Pilot to Prod', href: '/pilot-to-prod', external: false },
   { label: 'Docs', href: '/docs', external: false },
   { label: 'Pricing', href: '/pricing', external: false },
-  { label: 'Demo', href: 'https://demo.threadplane.ai', external: true },
   { label: 'Examples', href: 'https://cockpit.threadplane.ai', external: true },
 ];
 
@@ -40,6 +40,46 @@ function CloseIcon() {
   );
 }
 
+function DemoDropdown() {
+  const [open, setOpen] = useState(false);
+  const ref = useRef<HTMLDivElement>(null);
+  useEffect(() => {
+    const handler = (e: MouseEvent) => {
+      if (ref.current && !ref.current.contains(e.target as Node)) setOpen(false);
+    };
+    document.addEventListener('mousedown', handler);
+    return () => document.removeEventListener('mousedown', handler);
+  }, []);
+  return (
+    <div ref={ref} style={{ position: 'relative' }}>
+      <button
+        onClick={() => setOpen((o) => !o)}
+        className="text-sm font-mono transition-colors"
+        style={{ color: tokens.colors.textSecondary, background: 'none', border: 'none', cursor: 'pointer', display: 'inline-flex', alignItems: 'center', gap: 4 }}
+        onMouseEnter={(e) => (e.currentTarget.style.color = tokens.colors.accent)}
+        onMouseLeave={(e) => (e.currentTarget.style.color = tokens.colors.textSecondary)}
+        aria-haspopup="true" aria-expanded={open}
+      >
+        Demo <span style={{ fontSize: 10, transition: 'transform .2s', transform: open ? 'rotate(180deg)' : 'rotate(0)' }}>&#9662;</span>
+      </button>
+      {open && (
+        <div style={{ position: 'absolute', top: '100%', left: 0, marginTop: 8, minWidth: 180, background: tokens.surfaces.surface, border: `1px solid ${tokens.surfaces.border}`, borderRadius: 8, boxShadow: tokens.shadows.md, overflow: 'hidden', zIndex: 60 }}>
+          {DEMOS.map((demo) => (
+            <a key={demo.key} href={demo.href} target="_blank" rel="noopener noreferrer"
+              onClick={() => { setOpen(false); trackExternalLinkClick(demo.href, { surface: 'nav', cta_id: `nav_demo_${demoCtaSuffix(demo.key)}`, cta_text: demo.label }); }}
+              className="text-sm font-mono"
+              style={{ display: 'block', padding: '10px 14px', color: tokens.colors.textSecondary, textDecoration: 'none' }}
+              onMouseEnter={(e) => (e.currentTarget.style.color = tokens.colors.accent)}
+              onMouseLeave={(e) => (e.currentTarget.style.color = tokens.colors.textSecondary)}>
+              {demo.label}
+            </a>
+          ))}
+        </div>
+      )}
+    </div>
+  );
+}
+
 export function Nav() {
   const [open, setOpen] = useState(false);
   const pathname = usePathname();
@@ -141,6 +181,7 @@ export function Nav() {
               {l.label}
             </Link>
           ))}
+          <DemoDropdown />
           <a href="https://github.com/cacheplane/angular-agent-framework"
             target="_blank"
             rel="noopener noreferrer"
@@ -308,6 +349,13 @@ export function Nav() {
                     </LinkEl>
                   );
                 })}
+                {DEMOS.map((demo) => (
+                  <a key={demo.key} href={demo.href} target="_blank" rel="noopener noreferrer"
+                    onClick={() => { trackExternalLinkClick(demo.href, { surface: 'mobile_nav', cta_id: `mobile_nav_demo_${demoCtaSuffix(demo.key)}`, cta_text: demo.label }); setOpen(false); }}
+                    style={{ display: 'block', padding: '14px 14px', borderRadius: 8, fontSize: 16, lineHeight: '24px', minHeight: 48, color: tokens.colors.textSecondary, textDecoration: 'none', fontFamily: 'Inter, sans-serif' }}>
+                    {demo.label}
+                  </a>
+                ))}
                 <a href="https://github.com/cacheplane/angular-agent-framework"
                   target="_blank" rel="noopener noreferrer"
                   onClick={() => {

From ec73eb9cfcc57f312c6218f2449fb16c7d620740 Mon Sep 17 00:00:00 2001
From: Brian Love <brian@liveloveapp.com>
Date: Mon, 8 Jun 2026 17:46:42 -0700
Subject: [PATCH 09/15] feat(website): tabbed video-first DemoShowcase on
 homepage

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 apps/website/src/app/page.tsx                 | 23 ++++-
 .../src/components/landing/DemoShowcase.tsx   | 90 +++++++++++++++++++
 .../src/components/landing/LiveDemoFrame.tsx  | 63 -------------
 3 files changed, 111 insertions(+), 65 deletions(-)
 create mode 100644 apps/website/src/components/landing/DemoShowcase.tsx
 delete mode 100644 apps/website/src/components/landing/LiveDemoFrame.tsx

diff --git a/apps/website/src/app/page.tsx b/apps/website/src/app/page.tsx
index 015d3e808..daa0f5cf2 100644
--- a/apps/website/src/app/page.tsx
+++ b/apps/website/src/app/page.tsx
@@ -3,13 +3,15 @@ import { EcosystemStrip } from '../components/landing/EcosystemStrip';
 import { Differentiator } from '../components/landing/Differentiator';
 import { FeatureBlock } from '../components/landing/FeatureBlock';
 import { BrowserFrame } from '../components/ui/BrowserFrame';
-import { LiveDemoFrame } from '../components/landing/LiveDemoFrame';
+import { DemoShowcase } from '../components/landing/DemoShowcase';
 import { PilotBlock } from '../components/landing/PilotBlock';
 import { WhitePaperBlock } from '../components/landing/WhitePaperBlock';
 import { Promises } from '../components/landing/Promises';
 import { HomeFAQ } from '../components/landing/HomeFAQ';
 import { FinalCTA } from '../components/landing/FinalCTA';
 import { RecentArticles } from '../components/landing/RecentArticles';
+import { Section } from '../components/ui/Section';
+import { Container } from '../components/ui/Container';
 import { tokens } from '@threadplane/design-tokens';
 import { createPageMetadata, LONG_SUBHEAD, PRIMARY_TAGLINE } from '../lib/site-metadata';
 
@@ -27,6 +29,13 @@ export default async function HomePage() {
       <EcosystemStrip />
       <Differentiator />
 
+      {/* Interactive demo showcase */}
+      <Section surface="canvas">
+        <Container>
+          <DemoShowcase />
+        </Container>
+      </Section>
+
       {/* Stream */}
       <FeatureBlock
         id="stream"
@@ -112,7 +121,17 @@ export default async function HomePage() {
           { title: 'thread persistence', description: 'Restore conversations across sessions.' },
         ]}
         cta={{ label: 'Production patterns', href: '/docs/langgraph/guides/deployment' }}
-        visual={<LiveDemoFrame />}
+        visual={
+          <BrowserFrame url="demo.threadplane.ai" elevation="lg">
+            <img
+              src="/screenshots/canonical-demo-generative-ui.webp"
+              alt="Threadplane chat rendering a live generative-UI dashboard"
+              style={{ display: 'block', width: '100%', height: 'auto' }}
+              loading="lazy"
+              decoding="async"
+            />
+          </BrowserFrame>
+        }
       />
 
       <PilotBlock />
diff --git a/apps/website/src/components/landing/DemoShowcase.tsx b/apps/website/src/components/landing/DemoShowcase.tsx
new file mode 100644
index 000000000..ceb97880b
--- /dev/null
+++ b/apps/website/src/components/landing/DemoShowcase.tsx
@@ -0,0 +1,90 @@
+'use client';
+import { useState } from 'react';
+import { tokens } from '@threadplane/design-tokens';
+import { BrowserFrame } from '../ui/BrowserFrame';
+import { Button } from '../ui/Button';
+import { DemoCtaPair } from './DemoCtaPair';
+import { DEMOS } from '../../lib/demos';
+
+type TabKey = (typeof DEMOS)[number]['key'];
+
+interface DemoMedia {
+  key: TabKey;
+  tabLabel: string;
+  url: string;
+  videoMp4: string;
+  videoWebm: string;
+  poster: string;
+  href: string;
+}
+
+const MEDIA: DemoMedia[] = [
+  { key: 'langgraph', tabLabel: 'LangGraph', url: 'demo.threadplane.ai', videoMp4: '/demo/langgraph-demo.mp4', videoWebm: '/demo/langgraph-demo.webm', poster: '/demo/langgraph-demo-poster.webp', href: DEMOS[0].href },
+  { key: 'ag-ui', tabLabel: 'AG-UI', url: 'ag-ui.threadplane.ai', videoMp4: '/demo/ag-ui-demo.mp4', videoWebm: '/demo/ag-ui-demo.webm', poster: '/demo/ag-ui-demo-poster.webp', href: DEMOS[1].href },
+];
+
+export function DemoShowcase() {
+  const [active, setActive] = useState<TabKey>('langgraph');
+  const [launched, setLaunched] = useState<Set<TabKey>>(new Set());
+  const media = MEDIA.find((m) => m.key === active)!;
+  const isLaunched = launched.has(active);
+  const launch = () => setLaunched((prev) => new Set(prev).add(active));
+
+  return (
+    <div style={{ maxWidth: 760, margin: '0 auto', textAlign: 'center' }}>
+      <p style={{ fontFamily: tokens.typography.fontMono, fontSize: 12, fontWeight: 700, letterSpacing: '0.08em', textTransform: 'uppercase', color: tokens.colors.accent, margin: 0 }}>See it running</p>
+      <h2 style={{ fontFamily: tokens.typography.h2.family, fontSize: tokens.typography.h2.size, lineHeight: tokens.typography.h2.line, fontWeight: 700, color: tokens.colors.textPrimary, margin: '10px 0 8px', letterSpacing: '-0.015em' }}>
+        One chat UI. Two runtimes. Same code.
+      </h2>
+      <p style={{ fontFamily: tokens.typography.bodyLg.family, fontSize: tokens.typography.bodyLg.size, lineHeight: tokens.typography.bodyLg.line, color: tokens.colors.textSecondary, maxWidth: 560, margin: '0 auto 20px' }}>
+        The identical Threadplane chat surface, running live against a LangGraph backend and an AG-UI backend. Switch tabs to compare — the front end never changes.
+      </p>
+
+      <div role="tablist" aria-label="Demo backend" style={{ display: 'flex', gap: 6, justifyContent: 'center', marginBottom: 12 }}>
+        {MEDIA.map((m) => {
+          const on = m.key === active;
+          return (
+            <button key={m.key} role="tab" aria-selected={on} onClick={() => setActive(m.key)}
+              style={{ fontFamily: 'Inter, sans-serif', fontSize: 13, fontWeight: 600, padding: '9px 16px', borderRadius: 8, border: 'none', cursor: 'pointer',
+                background: on ? tokens.colors.accent : tokens.colors.accentSurface, color: on ? tokens.colors.textInverted : tokens.colors.textMuted }}>
+              {m.tabLabel}
+            </button>
+          );
+        })}
+      </div>
+
+      <BrowserFrame url={media.url} elevation="lg">
+        <div style={{ position: 'relative', width: '100%', aspectRatio: '16 / 10', background: '#15161f' }}>
+          {isLaunched ? (
+            <iframe src={media.href} title={`${media.tabLabel} live demo`} loading="lazy"
+              style={{ width: '100%', height: '100%', border: 'none', display: 'block' }} />
+          ) : (
+            <>
+              <video key={media.key} autoPlay muted loop playsInline poster={media.poster}
+                style={{ width: '100%', height: '100%', objectFit: 'cover', display: 'block' }}>
+                <source src={media.videoWebm} type="video/webm" />
+                <source src={media.videoMp4} type="video/mp4" />
+              </video>
+              <button onClick={launch} aria-label={`Launch ${media.tabLabel} live demo`}
+                style={{ position: 'absolute', inset: 0, display: 'flex', flexDirection: 'column', alignItems: 'center', justifyContent: 'center', gap: 10,
+                  background: 'linear-gradient(180deg, rgba(16,18,32,.15), rgba(16,18,32,.45))', border: 'none', cursor: 'pointer' }}>
+                <span style={{ width: 56, height: 56, borderRadius: '50%', background: 'rgba(255,255,255,.95)', display: 'flex', alignItems: 'center', justifyContent: 'center', color: '#15161f', fontSize: 22 }}>&#9654;</span>
+                <span style={{ fontFamily: 'Inter, sans-serif', fontWeight: 600, fontSize: 13, color: '#fff', background: 'rgba(0,0,0,.5)', padding: '8px 14px', borderRadius: 8 }}>Launch live demo</span>
+              </button>
+            </>
+          )}
+        </div>
+      </BrowserFrame>
+
+      <div style={{ display: 'flex', gap: 10, justifyContent: 'center', flexWrap: 'wrap', marginTop: 18 }}>
+        <DemoCtaPair surface="home_demo" size="lg" />
+        <Button variant="ghost" size="lg" href="https://cockpit.threadplane.ai" target="_blank" rel="noopener noreferrer">
+          See each feature in action →
+        </Button>
+      </div>
+      <p style={{ fontFamily: tokens.typography.caption.family, fontSize: tokens.typography.caption.size, color: tokens.colors.textMuted, margin: '14px 0 0' }}>
+        Video loops instantly · click Launch to open the live, interactive demo · MIT · no signup
+      </p>
+    </div>
+  );
+}
diff --git a/apps/website/src/components/landing/LiveDemoFrame.tsx b/apps/website/src/components/landing/LiveDemoFrame.tsx
deleted file mode 100644
index 4ff9930d2..000000000
--- a/apps/website/src/components/landing/LiveDemoFrame.tsx
+++ /dev/null
@@ -1,63 +0,0 @@
-'use client';
-import { useEffect, useRef, useState } from 'react';
-import { tokens } from '@threadplane/design-tokens';
-import { BrowserFrame } from '../ui/BrowserFrame';
-
-export function LiveDemoFrame() {
-  const ref = useRef<HTMLDivElement>(null);
-  const [shouldLoad, setShouldLoad] = useState(false);
-
-  useEffect(() => {
-    if (!ref.current || shouldLoad) return;
-    const el = ref.current;
-    const observer = new IntersectionObserver(
-      (entries) => {
-        for (const e of entries) {
-          if (e.isIntersecting) {
-            setShouldLoad(true);
-            observer.disconnect();
-            return;
-          }
-        }
-      },
-      { rootMargin: '200px' },
-    );
-    observer.observe(el);
-    return () => observer.disconnect();
-  }, [shouldLoad]);
-
-  return (
-    <div ref={ref}>
-      <BrowserFrame url="demo.threadplane.ai" elevation="lg">
-        {shouldLoad ? (
-          <iframe
-            src="https://demo.threadplane.ai"
-            title="Canonical demo — @threadplane/chat running against the shared LangGraph backend"
-            loading="lazy"
-            style={{
-              width: '100%',
-              height: 480,
-              border: 'none',
-              display: 'block',
-            }}
-          />
-        ) : (
-          <div
-            style={{
-              height: 480,
-              display: 'flex',
-              alignItems: 'center',
-              justifyContent: 'center',
-              background: tokens.surfaces.surfaceTinted,
-              color: tokens.colors.textMuted,
-              fontFamily: tokens.typography.fontMono,
-              fontSize: 13,
-            }}
-          >
-            Loading demo…
-          </div>
-        )}
-      </BrowserFrame>
-    </div>
-  );
-}

From aea5587d9c32a14fdd269465f965cd93977794fb Mon Sep 17 00:00:00 2001
From: Brian Love <brian@liveloveapp.com>
Date: Mon, 8 Jun 2026 17:52:18 -0700
Subject: [PATCH 10/15] feat(website): contextual AG-UI live-demo link in docs
 nav

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 apps/website/src/components/docs/DocsSidebar.tsx | 11 +++++++++++
 apps/website/src/components/shared/Nav.tsx       |  7 +++++++
 apps/website/src/lib/docs-config.ts              |  5 +++++
 3 files changed, 23 insertions(+)

diff --git a/apps/website/src/components/docs/DocsSidebar.tsx b/apps/website/src/components/docs/DocsSidebar.tsx
index 9adf50440..9f593f721 100644
--- a/apps/website/src/components/docs/DocsSidebar.tsx
+++ b/apps/website/src/components/docs/DocsSidebar.tsx
@@ -217,6 +217,17 @@ export function DocsSidebar({ activeLibrary, activeSection, activeSlug }: Props)
 
       <LibraryDropdown activeLibrary={activeLibrary} />
 
+      {libConfig?.demoUrl && (
+        <div className="px-4 mb-4">
+          <a href={libConfig.demoUrl} target="_blank" rel="noopener noreferrer"
+            className="w-full text-left px-3 py-2 rounded-lg text-sm flex items-center justify-between"
+            style={{ background: tokens.colors.accentSurface, color: tokens.colors.accent, border: `1px solid ${tokens.surfaces.border}`, textDecoration: 'none', fontWeight: 600 }}>
+            <span>{libConfig.demoLabel ?? 'Live demo'}</span>
+            <span aria-hidden="true">↗</span>
+          </a>
+        </div>
+      )}
+
       {libConfig?.sections.map((section) => (
         <SectionGroup
           key={section.id}
diff --git a/apps/website/src/components/shared/Nav.tsx b/apps/website/src/components/shared/Nav.tsx
index d80b4c68d..4592cd662 100644
--- a/apps/website/src/components/shared/Nav.tsx
+++ b/apps/website/src/components/shared/Nav.tsx
@@ -269,6 +269,13 @@ export function Nav() {
             {/* Docs content */}
             {(mobileTab === 'docs' && isDocsPage && currentLib) && (
               <div style={{ display: 'flex', flexDirection: 'column', gap: 4 }}>
+                {currentLib.demoUrl && (
+                  <a href={currentLib.demoUrl} target="_blank" rel="noopener noreferrer"
+                    onClick={() => { trackExternalLinkClick(currentLib.demoUrl!, { surface: 'mobile_nav', cta_id: `mobile_nav_docs_demo_${currentLib.id}`, cta_text: currentLib.demoLabel ?? 'Live demo' }); setOpen(false); }}
+                    style={{ display: 'flex', alignItems: 'center', justifyContent: 'space-between', padding: '12px 14px', borderRadius: 8, minHeight: 44, color: tokens.colors.accent, background: tokens.colors.accentSurface, textDecoration: 'none', fontFamily: 'Inter, sans-serif', fontWeight: 600 }}>
+                    <span>{currentLib.demoLabel ?? 'Live demo'}</span><span aria-hidden="true">↗</span>
+                  </a>
+                )}
                 {currentLib.sections.map((section) => {
                   return (
                     <div key={section.id}>
diff --git a/apps/website/src/lib/docs-config.ts b/apps/website/src/lib/docs-config.ts
index ac71d827f..c4f84cc4e 100644
--- a/apps/website/src/lib/docs-config.ts
+++ b/apps/website/src/lib/docs-config.ts
@@ -24,6 +24,10 @@ export interface DocsLibrary {
   id: LibraryId;
   title: string;
   description: string;
+  /** Optional external live-demo URL, surfaced contextually in docs nav. */
+  demoUrl?: string;
+  /** Optional label override for the demo link. Defaults to 'Live demo'. */
+  demoLabel?: string;
   sections: DocsSection[];
 }
 
@@ -224,6 +228,7 @@ export const docsConfig: DocsLibrary[] = [
     id: 'ag-ui',
     title: 'AG-UI',
     description: 'Adapter for any AG-UI-compatible backend (CrewAI, Mastra, Microsoft AF, AG2, Pydantic AI, AWS Strands, CopilotKit runtime)',
+    demoUrl: 'https://ag-ui.threadplane.ai',
     sections: [
       {
         title: 'Getting Started',

From f267857235a2a26b9897651d1df7a720e6b7b7e1 Mon Sep 17 00:00:00 2001
From: Brian Love <brian@liveloveapp.com>
Date: Mon, 8 Jun 2026 17:56:49 -0700
Subject: [PATCH 11/15] docs(ag-ui): add live-demo callouts to introduction +
 quickstart

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 .../content/docs/ag-ui/getting-started/introduction.mdx       | 4 ++++
 .../website/content/docs/ag-ui/getting-started/quickstart.mdx | 4 ++++
 2 files changed, 8 insertions(+)

diff --git a/apps/website/content/docs/ag-ui/getting-started/introduction.mdx b/apps/website/content/docs/ag-ui/getting-started/introduction.mdx
index f376b29e7..a567ccfb6 100644
--- a/apps/website/content/docs/ag-ui/getting-started/introduction.mdx
+++ b/apps/website/content/docs/ag-ui/getting-started/introduction.mdx
@@ -8,6 +8,10 @@
 AG-UI is the open agent-to-UI protocol from the CopilotKit ecosystem. It standardizes how agent runtimes stream events (messages, tool calls, state updates) to a frontend. Used by **CrewAI**, **Mastra**, **Microsoft Agent Framework**, **AG2**, **Pydantic AI**, **AWS Strands**, and the **CopilotKit runtime**. One adapter unlocks all of them.
 </Callout>
 
+<Callout type="tip" title="See it live">
+The [AG-UI demo](https://ag-ui.threadplane.ai) runs this exact chat surface against an AG-UI backend — streaming, tool calls, and generative UI included. Compare it side by side with the [LangGraph demo](https://demo.threadplane.ai).
+</Callout>
+
 ## How it fits
 
 ```text
diff --git a/apps/website/content/docs/ag-ui/getting-started/quickstart.mdx b/apps/website/content/docs/ag-ui/getting-started/quickstart.mdx
index be1059135..72dd3c823 100644
--- a/apps/website/content/docs/ag-ui/getting-started/quickstart.mdx
+++ b/apps/website/content/docs/ag-ui/getting-started/quickstart.mdx
@@ -6,6 +6,10 @@ Let's bind `<chat>` from `@threadplane/chat` to an AG-UI backend in 5 minutes.
 Angular 20+ project with Node.js 22+. If you need setup help, see the [Installation](/docs/ag-ui/getting-started/installation) guide.
 </Callout>
 
+<Callout type="tip" title="Try it first">
+Want to see the finished result before you build? Open the live [AG-UI demo](https://ag-ui.threadplane.ai).
+</Callout>
+
 <Steps>
 <Step title="Install the packages">
 

From f0a6f2e18fcd656cc6d8c9312834240da852fc93 Mon Sep 17 00:00:00 2001
From: Brian Love <brian@liveloveapp.com>
Date: Mon, 8 Jun 2026 18:11:41 -0700
Subject: [PATCH 12/15] docs(ag-ui): API reference pages + nav section

Add four AG-UI API reference MDX pages (provideAgent, injectAgent,
toAgent, FakeAgent), wire them into the docs nav under a new
'API Reference' section, and add a bridgeCitationsState cross-link
in the Citations guide.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 .../content/docs/ag-ui/api/fake-agent.mdx     | 121 ++++++++++++++++++
 .../content/docs/ag-ui/api/inject-agent.mdx   | 112 ++++++++++++++++
 .../content/docs/ag-ui/api/provide-agent.mdx  |  83 ++++++++++++
 .../content/docs/ag-ui/api/to-agent.mdx       |  80 ++++++++++++
 .../content/docs/ag-ui/guides/citations.mdx   |   2 +-
 apps/website/src/lib/docs-config.ts           |  11 ++
 6 files changed, 408 insertions(+), 1 deletion(-)
 create mode 100644 apps/website/content/docs/ag-ui/api/fake-agent.mdx
 create mode 100644 apps/website/content/docs/ag-ui/api/inject-agent.mdx
 create mode 100644 apps/website/content/docs/ag-ui/api/provide-agent.mdx
 create mode 100644 apps/website/content/docs/ag-ui/api/to-agent.mdx

diff --git a/apps/website/content/docs/ag-ui/api/fake-agent.mdx b/apps/website/content/docs/ag-ui/api/fake-agent.mdx
new file mode 100644
index 000000000..edb856d6b
--- /dev/null
+++ b/apps/website/content/docs/ag-ui/api/fake-agent.mdx
@@ -0,0 +1,121 @@
+# FakeAgent
+
+`FakeAgent` is an in-process AG-UI test double that emits a canned streaming response without a real backend. Use it for offline development, CI, and component tests.
+
+## provideFakeAgent()
+
+`provideFakeAgent()` is the DI-friendly entry point. It is a drop-in replacement for `provideAgent({ url })` when no backend is available.
+
+```ts
+import { bootstrapApplication } from '@angular/platform-browser';
+import { provideFakeAgent } from '@threadplane/ag-ui';
+import { AppComponent } from './app/app.component';
+
+bootstrapApplication(AppComponent, {
+  providers: [
+    provideFakeAgent(),
+  ],
+});
+```
+
+Pass a `FakeAgentConfig` to customize the canned response:
+
+```ts
+provideFakeAgent({
+  tokens: ['Hello', ' world', '!'],
+  delayMs: 40,
+})
+```
+
+### FakeAgentConfig
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `tokens` | `string[]` | Assistant reply streamed token-by-token. Defaults to a fixed placeholder message. |
+| `reasoningTokens` | `string[]` | Optional reasoning chunks emitted before the text reply. |
+| `delayMs` | `number` | Milliseconds between successive token emissions. Defaults to `60`. |
+
+## FakeAgent class
+
+Construct a `FakeAgent` directly when you need lower-level control, for example to pass it to `toAgent()` in a test harness.
+
+```ts
+import { FakeAgent } from '@threadplane/ag-ui';
+import { toAgent } from '@threadplane/ag-ui';
+
+const agent = toAgent(new FakeAgent({
+  tokens: ['Thinking', '...', ' done.'],
+  reasoningTokens: ['Step 1', ': evaluate'],
+  delayMs: 30,
+}));
+```
+
+`FakeAgent` extends `AbstractAgent` from `@ag-ui/client`. Its `run()` method returns an `Observable<BaseEvent>` that emits the full event sequence — `RUN_STARTED`, optional reasoning events, `TEXT_MESSAGE_START` / `TEXT_MESSAGE_CONTENT` tokens, `TEXT_MESSAGE_END`, `RUN_FINISHED` — then completes.
+
+## TestBed example
+
+```ts
+import { TestBed } from '@angular/core/testing';
+import { provideFakeAgent, injectAgent } from '@threadplane/ag-ui';
+import { Component } from '@angular/core';
+
+@Component({ template: '' })
+class ChatComponent {
+  readonly chat = injectAgent();
+}
+
+describe('ChatComponent', () => {
+  beforeEach(() => {
+    TestBed.configureTestingModule({
+      imports: [ChatComponent],
+      providers: [
+        provideFakeAgent({ tokens: ['Hello', ' from', ' fake'] }),
+      ],
+    });
+  });
+
+  it('streams a canned reply', async () => {
+    const fixture = TestBed.createComponent(ChatComponent);
+    fixture.detectChanges();
+
+    await fixture.componentInstance.chat.submit({ message: 'Hi' });
+    fixture.detectChanges();
+
+    expect(fixture.componentInstance.chat.messages().at(-1)?.content)
+      .toBe('Hello from fake');
+  });
+});
+```
+
+<Callout type="info" title="Not for production">
+  `FakeAgent` and `provideFakeAgent()` are intended for development and tests
+  only. Do not use them in production builds.
+</Callout>
+
+## What's Next
+
+<CardGroup cols={3}>
+  <Card
+    title="Fake Agent guide"
+    icon="flask"
+    href="/docs/ag-ui/guides/fake-agent"
+  >
+    Practical patterns for offline demos and rapid prototyping with FakeAgent.
+  </Card>
+  <Card
+    title="Testing guide"
+    icon="check"
+    href="/docs/ag-ui/guides/testing"
+  >
+    Full testing patterns for components that use `injectAgent()`.
+  </Card>
+  <Card
+    title="provideAgent() API"
+    icon="settings"
+    href="/docs/ag-ui/api/provide-agent"
+  >
+    The production provider `provideFakeAgent()` replaces in tests.
+  </Card>
+</CardGroup>
+
+{/* Auto-rendered from api-docs.json — see page component */}
diff --git a/apps/website/content/docs/ag-ui/api/inject-agent.mdx b/apps/website/content/docs/ag-ui/api/inject-agent.mdx
new file mode 100644
index 000000000..9d9be6a8f
--- /dev/null
+++ b/apps/website/content/docs/ag-ui/api/inject-agent.mdx
@@ -0,0 +1,112 @@
+# injectAgent()
+
+`injectAgent()` retrieves the AG-UI agent from Angular's dependency injection container. Call it in an Angular injection context — typically as a component field initializer. The returned object exposes Angular Signals for reactive UI state and async methods for user actions.
+
+Configuration is supplied globally via `provideAgent({...})` — `injectAgent()` itself takes no arguments.
+
+```ts
+import { injectAgent } from '@threadplane/ag-ui';
+
+readonly chat = injectAgent();
+
+await this.chat.submit({ message: 'Hello' });
+```
+
+Pair it with `provideAgent()` at bootstrap to configure the agent endpoint:
+
+```ts
+import { bootstrapApplication } from '@angular/platform-browser';
+import { provideAgent } from '@threadplane/ag-ui';
+import { AppComponent } from './app/app.component';
+
+bootstrapApplication(AppComponent, {
+  providers: [
+    provideAgent({ url: 'http://localhost:8000/my-agent' }),
+  ],
+});
+```
+
+## Runtime-neutral surface
+
+These fields are stable across runtime adapters and are what chat components consume.
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `messages()` | `Message[]` | Chat messages with `role`, `content`, optional `toolCallIds`, citations, and reasoning. |
+| `status()` | `'idle' \| 'running' \| 'error'` | UI lifecycle status. |
+| `isLoading()` | `boolean` | Convenience signal for active streaming. |
+| `error()` | `unknown` | Latest runtime error, when present. |
+| `toolCalls()` | `ToolCall[]` | Tool calls projected into the chat contract. |
+| `state()` | `Record<string, unknown>` | Latest agent state projected as a plain object. |
+| `interrupt()` | `AgentInterrupt \| undefined` | Current interrupt, when the backend pauses for human input. |
+| `submit(input, opts?)` | `Promise<void>` | Submit a user message or resume payload. |
+| `stop()` | `Promise<void>` | Abort the active run. |
+| `regenerate(index)` | `Promise<void>` | Remove the assistant message at `index` and rerun from the preceding user message. |
+
+## AG-UI-specific surface
+
+The AG-UI adapter extends the neutral `Agent` contract with one additional signal:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `customEvents()` | `CustomStreamEvent[]` | Custom events emitted by the backend during a run. Accumulates per run; resets on each new `submit()`. |
+
+The chat a2ui bridge reads `customEvents` to light up live generative-UI streaming when your backend emits `a2ui-partial` events. See the [Custom Events guide](/docs/ag-ui/guides/custom-events) for backend wiring details.
+
+## Submit and resume
+
+Use the runtime-neutral submit shape for normal chat input:
+
+```ts
+await chat.submit({ message: 'Summarize this document' });
+```
+
+Resume an interrupt by passing a `resume` payload:
+
+```ts
+await chat.submit({ resume: { approved: true } });
+```
+
+## Regenerate semantics
+
+`regenerate(assistantMessageIndex)` has replace semantics: it keeps the user message before the selected assistant message, removes the selected assistant message and all later messages, syncs the rollback to the AG-UI source, then reruns with no new user message appended.
+
+```ts
+await chat.regenerate(3);
+```
+
+The method throws when the selected index is not an assistant message, when no preceding user message exists, or while another response is already loading.
+
+<Callout type="warning" title="Injection context required">
+  `injectAgent()` must be called during construction, inside an injection context
+  (e.g. a component constructor, field initializer, or a function passed to
+  `runInInjectionContext`). Calling it outside an injection context will throw.
+</Callout>
+
+## What's Next
+
+<CardGroup cols={3}>
+  <Card
+    title="provideAgent() API"
+    icon="settings"
+    href="/docs/ag-ui/api/provide-agent"
+  >
+    Configure the endpoint URL, headers, and telemetry for the agent provider.
+  </Card>
+  <Card
+    title="Custom Events guide"
+    icon="wave-sine"
+    href="/docs/ag-ui/guides/custom-events"
+  >
+    Wire `customEvents` to live generative-UI streaming from any AG-UI backend.
+  </Card>
+  <Card
+    title="Testing guide"
+    icon="flask"
+    href="/docs/ag-ui/guides/testing"
+  >
+    Test components that call `injectAgent()` with the in-process FakeAgent.
+  </Card>
+</CardGroup>
+
+{/* Auto-rendered from api-docs.json — see page component */}
diff --git a/apps/website/content/docs/ag-ui/api/provide-agent.mdx b/apps/website/content/docs/ag-ui/api/provide-agent.mdx
new file mode 100644
index 000000000..5dee8a9c8
--- /dev/null
+++ b/apps/website/content/docs/ag-ui/api/provide-agent.mdx
@@ -0,0 +1,83 @@
+# provideAgent()
+
+`provideAgent()` registers the singleton AG-UI agent configuration for every `injectAgent()` call in an Angular application. Call it once in `bootstrapApplication` or an `ApplicationConfig` to wire up the endpoint URL, optional identifiers, custom headers, and telemetry.
+
+`injectAgent()` itself takes no arguments — all configuration flows through `provideAgent()`.
+
+```ts
+import { bootstrapApplication } from '@angular/platform-browser';
+import { provideAgent } from '@threadplane/ag-ui';
+import { AppComponent } from './app/app.component';
+
+bootstrapApplication(AppComponent, {
+  providers: [
+    provideAgent({
+      url: 'http://localhost:8000/my-agent',
+    }),
+  ],
+});
+```
+
+## Configuration options
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `url` | `string` | HTTP endpoint for the AG-UI backend agent. Required. |
+| `agentId` | `string` | Optional agent identifier forwarded to the backend. |
+| `threadId` | `string` | Optional thread identifier for session continuity. |
+| `headers` | `Record<string, string>` | Optional custom HTTP headers included on every request. |
+| `telemetry` | `AgentRuntimeTelemetrySink \| false` | Optional app-owned telemetry sink. No telemetry is emitted unless this is provided. |
+
+## Static vs factory config
+
+Pass a plain `AgentConfig` object when the URL is known up front. Pass a `() => AgentConfig` factory when the config depends on runtime DI state — the factory runs inside an Angular injection context, so it may call `inject()` to read services or environment tokens.
+
+```ts
+// Factory form — reads an environment token at runtime
+provideAgent(() => {
+  const env = inject(APP_ENV);
+  return {
+    url: env.agentUrl,
+    headers: { Authorization: `Bearer ${env.apiKey}` },
+  };
+});
+```
+
+## Singleton model
+
+A single `provideAgent({...})` call configures the entire application. Every `injectAgent()` call resolves to the same configured agent.
+
+```ts
+provideAgent({ url: 'https://api.example.com/agent' });
+
+// Elsewhere, inside an injection context:
+const chat = injectAgent();
+```
+
+## What's Next
+
+<CardGroup cols={3}>
+  <Card
+    title="injectAgent() API"
+    icon="code"
+    href="/docs/ag-ui/api/inject-agent"
+  >
+    The primitive you call inside components after registering a provider.
+  </Card>
+  <Card
+    title="Quick Start"
+    icon="rocket"
+    href="/docs/ag-ui/getting-started/quickstart"
+  >
+    End-to-end setup connecting a real AG-UI backend in minutes.
+  </Card>
+  <Card
+    title="Fake Agent guide"
+    icon="flask"
+    href="/docs/ag-ui/guides/fake-agent"
+  >
+    Swap the live backend for an in-process test double during development.
+  </Card>
+</CardGroup>
+
+{/* Auto-rendered from api-docs.json — see page component */}
diff --git a/apps/website/content/docs/ag-ui/api/to-agent.mdx b/apps/website/content/docs/ag-ui/api/to-agent.mdx
new file mode 100644
index 000000000..651c4f8fd
--- /dev/null
+++ b/apps/website/content/docs/ag-ui/api/to-agent.mdx
@@ -0,0 +1,80 @@
+# toAgent()
+
+`toAgent()` is the lower-level adapter function that wraps a raw AG-UI `AbstractAgent` into the runtime-neutral `Agent` contract used by `@threadplane/chat` components.
+
+```ts
+toAgent(source: AbstractAgent, options?: ToAgentOptions): AgUiAgent
+```
+
+Most applications should use [`provideAgent()`](/docs/ag-ui/api/provide-agent) instead — it constructs the `HttpAgent` source and calls `toAgent()` internally. Reach for `toAgent()` directly when you instantiate or customize the `AbstractAgent` yourself, for example to integrate a non-HTTP AG-UI transport.
+
+```ts
+import { HttpAgent } from '@ag-ui/client';
+import { toAgent } from '@threadplane/ag-ui';
+
+const source = new HttpAgent({ url: 'http://localhost:8000/my-agent' });
+const agent = toAgent(source, { telemetry: myTelemetrySink });
+```
+
+## ToAgentOptions
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `telemetry` | `AgentRuntimeTelemetrySink \| false` | Optional app-owned telemetry sink. No telemetry is emitted unless this is provided. |
+
+## AgUiAgent
+
+`toAgent()` returns an `AgUiAgent`, which extends the neutral `Agent` contract with one additional signal:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `customEvents()` | `Signal<CustomStreamEvent[]>` | Custom events accumulated during a run. Resets at the start of each new run. |
+
+The standard `Agent` signals (`messages`, `status`, `isLoading`, `error`, `toolCalls`, `state`, `interrupt`) and actions (`submit`, `stop`, `regenerate`) are all present.
+
+## CustomStreamEvent
+
+`CustomStreamEvent` is the element type of `AgUiAgent.customEvents`:
+
+```ts
+interface CustomStreamEvent {
+  /** Event name set by the backend (e.g. 'a2ui-partial', 'state_update'). */
+  name: string;
+  /** Arbitrary payload from the backend (JSON-string values are parsed). */
+  data: unknown;
+}
+```
+
+Custom events are surfaced from AG-UI `CUSTOM` protocol events whose `name` is not `on_interrupt`. The `on_interrupt` event is routed to the `interrupt` signal instead.
+
+## Lifecycle note
+
+The returned `AgUiAgent` does not manage its own lifetime. When using DI via `provideAgent()`, the provider's destroy hook handles cleanup. When calling `toAgent()` directly, treat the returned agent's lifecycle as tied to the `AbstractAgent` instance you constructed.
+
+## What's Next
+
+<CardGroup cols={3}>
+  <Card
+    title="provideAgent() API"
+    icon="settings"
+    href="/docs/ag-ui/api/provide-agent"
+  >
+    The DI-friendly wrapper around `toAgent()` for most Angular apps.
+  </Card>
+  <Card
+    title="Architecture"
+    icon="diagram"
+    href="/docs/ag-ui/concepts/architecture"
+  >
+    How the AG-UI adapter fits into the broader `@threadplane/chat` design.
+  </Card>
+  <Card
+    title="Event Mapping"
+    icon="list"
+    href="/docs/ag-ui/reference/event-mapping"
+  >
+    Which AG-UI protocol events map to which signals and actions.
+  </Card>
+</CardGroup>
+
+{/* Auto-rendered from api-docs.json — see page component */}
diff --git a/apps/website/content/docs/ag-ui/guides/citations.mdx b/apps/website/content/docs/ag-ui/guides/citations.mdx
index cf20972a6..108788e5e 100644
--- a/apps/website/content/docs/ag-ui/guides/citations.mdx
+++ b/apps/website/content/docs/ag-ui/guides/citations.mdx
@@ -117,7 +117,7 @@ const nextMessages = bridgeCitationsState(
 );
 ```
 
-Most apps should not need this directly. The built-in AG-UI reducer already calls it for state snapshots and deltas.
+Most apps should not need this directly. The built-in AG-UI reducer already calls it for state snapshots and deltas. The `bridgeCitationsState(thread, messages)` helper merges thread-level citation state onto the message list; import it from `@threadplane/ag-ui` when you assemble messages yourself outside the standard adapter pipeline.
 
 ## Gotchas
 
diff --git a/apps/website/src/lib/docs-config.ts b/apps/website/src/lib/docs-config.ts
index c4f84cc4e..e350b4ee3 100644
--- a/apps/website/src/lib/docs-config.ts
+++ b/apps/website/src/lib/docs-config.ts
@@ -268,6 +268,17 @@ export const docsConfig: DocsLibrary[] = [
           { title: 'Event Mapping', slug: 'event-mapping', section: 'reference' },
         ],
       },
+      {
+        title: 'API Reference',
+        id: 'api',
+        color: 'blue',
+        pages: [
+          { title: 'provideAgent()', slug: 'provide-agent', section: 'api' },
+          { title: 'injectAgent()', slug: 'inject-agent', section: 'api' },
+          { title: 'toAgent()', slug: 'to-agent', section: 'api' },
+          { title: 'FakeAgent', slug: 'fake-agent', section: 'api' },
+        ],
+      },
     ],
   },
   {

From bff8c19a3689c79898f37fc99d29c3b2c981ccf4 Mon Sep 17 00:00:00 2001
From: Brian Love <brian@liveloveapp.com>
Date: Mon, 8 Jun 2026 18:20:31 -0700
Subject: [PATCH 13/15] docs(ag-ui): add missing cross-links to API reference
 pages

---
 apps/website/content/docs/ag-ui/api/fake-agent.mdx    | 2 ++
 apps/website/content/docs/ag-ui/api/inject-agent.mdx  | 2 +-
 apps/website/content/docs/ag-ui/api/provide-agent.mdx | 2 +-
 3 files changed, 4 insertions(+), 2 deletions(-)

diff --git a/apps/website/content/docs/ag-ui/api/fake-agent.mdx b/apps/website/content/docs/ag-ui/api/fake-agent.mdx
index edb856d6b..1fe1776f7 100644
--- a/apps/website/content/docs/ag-ui/api/fake-agent.mdx
+++ b/apps/website/content/docs/ag-ui/api/fake-agent.mdx
@@ -92,6 +92,8 @@ describe('ChatComponent', () => {
   only. Do not use them in production builds.
 </Callout>
 
+See also: [Fake Agent guide](/docs/ag-ui/guides/fake-agent) for practical offline-development patterns, and [Testing guide](/docs/ag-ui/guides/testing) for full component-testing recipes.
+
 ## What's Next
 
 <CardGroup cols={3}>
diff --git a/apps/website/content/docs/ag-ui/api/inject-agent.mdx b/apps/website/content/docs/ag-ui/api/inject-agent.mdx
index 9d9be6a8f..460da11b8 100644
--- a/apps/website/content/docs/ag-ui/api/inject-agent.mdx
+++ b/apps/website/content/docs/ag-ui/api/inject-agent.mdx
@@ -2,7 +2,7 @@
 
 `injectAgent()` retrieves the AG-UI agent from Angular's dependency injection container. Call it in an Angular injection context — typically as a component field initializer. The returned object exposes Angular Signals for reactive UI state and async methods for user actions.
 
-Configuration is supplied globally via `provideAgent({...})` — `injectAgent()` itself takes no arguments.
+Configuration is supplied globally via [provideAgent()](/docs/ag-ui/api/provide-agent) — `injectAgent()` itself takes no arguments.
 
 ```ts
 import { injectAgent } from '@threadplane/ag-ui';
diff --git a/apps/website/content/docs/ag-ui/api/provide-agent.mdx b/apps/website/content/docs/ag-ui/api/provide-agent.mdx
index 5dee8a9c8..9f1c30c18 100644
--- a/apps/website/content/docs/ag-ui/api/provide-agent.mdx
+++ b/apps/website/content/docs/ag-ui/api/provide-agent.mdx
@@ -1,6 +1,6 @@
 # provideAgent()
 
-`provideAgent()` registers the singleton AG-UI agent configuration for every `injectAgent()` call in an Angular application. Call it once in `bootstrapApplication` or an `ApplicationConfig` to wire up the endpoint URL, optional identifiers, custom headers, and telemetry.
+`provideAgent()` registers the singleton AG-UI agent configuration for every [injectAgent()](/docs/ag-ui/api/inject-agent) call in an Angular application. Call it once in `bootstrapApplication` or an `ApplicationConfig` to wire up the endpoint URL, optional identifiers, custom headers, and telemetry.
 
 `injectAgent()` itself takes no arguments — all configuration flows through `provideAgent()`.
 

From 62bd359671b1aa1bcda0d0f2115e91b500158fe7 Mon Sep 17 00:00:00 2001
From: Brian Love <brian@liveloveapp.com>
Date: Mon, 8 Jun 2026 18:25:29 -0700
Subject: [PATCH 14/15] docs(ag-ui): custom-events guide (live a2ui streaming)

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 .../docs/ag-ui/guides/custom-events.mdx       | 136 ++++++++++++++++++
 apps/website/src/lib/docs-config.ts           |   1 +
 2 files changed, 137 insertions(+)
 create mode 100644 apps/website/content/docs/ag-ui/guides/custom-events.mdx

diff --git a/apps/website/content/docs/ag-ui/guides/custom-events.mdx b/apps/website/content/docs/ag-ui/guides/custom-events.mdx
new file mode 100644
index 000000000..2cbd50bf5
--- /dev/null
+++ b/apps/website/content/docs/ag-ui/guides/custom-events.mdx
@@ -0,0 +1,136 @@
+# Custom Events
+
+AG-UI `CUSTOM` events let a backend node push arbitrary data to the Angular client while a run is in progress. The adapter accumulates these events into the `customEvents` signal on the `AgUiAgent` returned by `injectAgent()`.
+
+```ts
+interface CustomStreamEvent {
+  name: string;
+  data: unknown;
+}
+```
+
+`customEvents` is a `Signal<CustomStreamEvent[]>`. The list is reset to `[]` when `RUN_STARTED` arrives, so it only ever contains events from the current run.
+
+<Callout type="info" title="on_interrupt is not in customEvents">
+The special `CUSTOM` event with `name: "on_interrupt"` is handled separately — it populates `agent.interrupt` and does **not** appear in `customEvents`. See the [Interrupts guide](/docs/ag-ui/guides/interrupts).
+</Callout>
+
+## Where Custom Events Come From
+
+A LangGraph node emits a custom event by writing to the stream writer with `stream_mode='custom'`:
+
+```python
+from langchain_core.runnables import RunnableConfig
+from langgraph.config import get_stream_writer
+
+def analysis_node(state: State, config: RunnableConfig) -> State:
+    writer = get_stream_writer()
+
+    # Emit a partial result as the node runs
+    writer({"name": "analysis_progress", "data": {"step": "scoring", "pct": 42}})
+
+    # ... do more work ...
+
+    writer({"name": "analysis_progress", "data": {"step": "scoring", "pct": 100}})
+    return state
+```
+
+The `ag-ui-langgraph` package surfaces this as an AG-UI `CUSTOM` event on the wire:
+
+```json
+{
+  "type": "CUSTOM",
+  "name": "analysis_progress",
+  "value": { "step": "scoring", "pct": 42 }
+}
+```
+
+The adapter JSON-parses `value` when it arrives as a string, so consumers always receive the structured object. The event is appended to `customEvents` as `{ name: "analysis_progress", data: { step: "scoring", pct: 42 } }`.
+
+## Reading Custom Events in Angular
+
+### Reactive effect
+
+Use an `effect` to react every time new events arrive:
+
+```typescript
+import { Component, ChangeDetectionStrategy, effect, signal } from '@angular/core';
+import { ChatComponent } from '@threadplane/chat';
+import { injectAgent } from '@threadplane/ag-ui';
+
+@Component({
+  standalone: true,
+  imports: [ChatComponent],
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  template: `
+    <chat [agent]="agent" />
+    @if (progress() !== null) {
+      <progress-bar [value]="progress()" />
+    }
+  `,
+})
+export class AnalysisComponent {
+  protected readonly agent = injectAgent();
+  protected readonly progress = signal<number | null>(null);
+
+  constructor() {
+    effect(() => {
+      const events = this.agent.customEvents();
+      const last = [...events]
+        .reverse()
+        .find((e) => e.name === 'analysis_progress');
+      this.progress.set(
+        last ? (last.data as { pct: number }).pct : null,
+      );
+    });
+  }
+}
+```
+
+### Computed signal
+
+When you only need to derive a value, `computed` is more concise:
+
+```typescript
+import { Component, ChangeDetectionStrategy, computed } from '@angular/core';
+import { ChatComponent } from '@threadplane/chat';
+import { injectAgent } from '@threadplane/ag-ui';
+import type { CustomStreamEvent } from '@threadplane/ag-ui';
+
+@Component({
+  standalone: true,
+  imports: [ChatComponent],
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  template: `
+    <chat [agent]="agent" />
+    <event-log [events]="progressEvents()" />
+  `,
+})
+export class AnalysisComponent {
+  protected readonly agent = injectAgent();
+
+  protected readonly progressEvents = computed(() =>
+    this.agent.customEvents().filter(
+      (e): e is CustomStreamEvent => e.name === 'analysis_progress',
+    ),
+  );
+}
+```
+
+Both patterns are zoneless-safe: Angular's signal graph tracks the `customEvents()` read and re-evaluates the derived value automatically.
+
+<Callout type="info" title="Live a2ui rendering">
+`customEvents` is the mechanism the chat composition uses for progressive a2ui surface updates — partial argument events accumulate here during a tool call and drive live rendering before the call completes. If you are building a custom a2ui integration over AG-UI, read `agent.customEvents()` the same way.
+</Callout>
+
+## Relation to Interrupts
+
+`CUSTOM` events named `on_interrupt` follow a separate path: the adapter routes them to `agent.interrupt` (a `Signal<AgentInterrupt | undefined>`) and they never enter `customEvents`. This keeps the two signals purpose-distinct — `interrupt` drives human-in-the-loop approval flows, while `customEvents` carries all other backend-pushed data.
+
+See the [Interrupts guide](/docs/ag-ui/guides/interrupts) for the full interrupt lifecycle including `<chat-approval-card>` and `submit({ resume })`.
+
+## See Also
+
+- [Architecture](/docs/ag-ui/concepts/architecture) — how the adapter reduces protocol events into Angular signals
+- [Event Mapping](/docs/ag-ui/reference/event-mapping) — full table of AG-UI event types and the agent fields they populate
+- [injectAgent()](/docs/ag-ui/api/inject-agent) — the injection function that returns `AgUiAgent`
diff --git a/apps/website/src/lib/docs-config.ts b/apps/website/src/lib/docs-config.ts
index e350b4ee3..783ff4f47 100644
--- a/apps/website/src/lib/docs-config.ts
+++ b/apps/website/src/lib/docs-config.ts
@@ -255,6 +255,7 @@ export const docsConfig: DocsLibrary[] = [
         pages: [
           { title: 'Fake Agent', slug: 'fake-agent', section: 'guides' },
           { title: 'Citations', slug: 'citations', section: 'guides' },
+          { title: 'Custom Events', slug: 'custom-events', section: 'guides' },
           { title: 'Interrupts', slug: 'interrupts', section: 'guides' },
           { title: 'Testing', slug: 'testing', section: 'guides' },
           { title: 'Troubleshooting', slug: 'troubleshooting', section: 'guides' },

From d656680fadd350a3618180b5b53c9b04e27c2377 Mon Sep 17 00:00:00 2001
From: Brian Love <brian@liveloveapp.com>
Date: Mon, 8 Jun 2026 19:18:51 -0700
Subject: [PATCH 15/15] fix(website): correct customEvents docs cast +
 DemoShowcase key lookup + ag-ui analytics library

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 apps/website/content/docs/ag-ui/api/inject-agent.mdx   |  9 +++++++++
 .../content/docs/ag-ui/guides/custom-events.mdx        | 10 ++++++----
 apps/website/src/components/landing/DemoShowcase.tsx   |  4 ++--
 apps/website/src/components/shared/Nav.tsx             |  2 +-
 apps/website/src/lib/analytics/events.ts               |  2 +-
 5 files changed, 19 insertions(+), 8 deletions(-)

diff --git a/apps/website/content/docs/ag-ui/api/inject-agent.mdx b/apps/website/content/docs/ag-ui/api/inject-agent.mdx
index 460da11b8..cd437ff88 100644
--- a/apps/website/content/docs/ag-ui/api/inject-agent.mdx
+++ b/apps/website/content/docs/ag-ui/api/inject-agent.mdx
@@ -51,6 +51,15 @@ The AG-UI adapter extends the neutral `Agent` contract with one additional signa
 |-------|------|-------------|
 | `customEvents()` | `CustomStreamEvent[]` | Custom events emitted by the backend during a run. Accumulates per run; resets on each new `submit()`. |
 
+`injectAgent()` is typed as the neutral `Agent` interface; to access `customEvents` you must cast to `AgUiAgent`:
+
+```ts
+import { injectAgent, type AgUiAgent } from '@threadplane/ag-ui';
+
+const chat = injectAgent() as AgUiAgent;
+chat.customEvents(); // Signal<CustomStreamEvent[]>
+```
+
 The chat a2ui bridge reads `customEvents` to light up live generative-UI streaming when your backend emits `a2ui-partial` events. See the [Custom Events guide](/docs/ag-ui/guides/custom-events) for backend wiring details.
 
 ## Submit and resume
diff --git a/apps/website/content/docs/ag-ui/guides/custom-events.mdx b/apps/website/content/docs/ag-ui/guides/custom-events.mdx
index 2cbd50bf5..1fe6be66b 100644
--- a/apps/website/content/docs/ag-ui/guides/custom-events.mdx
+++ b/apps/website/content/docs/ag-ui/guides/custom-events.mdx
@@ -49,6 +49,8 @@ The adapter JSON-parses `value` when it arrives as a string, so consumers always
 
 ## Reading Custom Events in Angular
 
+`injectAgent()` returns the neutral `Agent` type; cast it to `AgUiAgent` (exported from `@threadplane/ag-ui`) to reach the `customEvents` signal.
+
 ### Reactive effect
 
 Use an `effect` to react every time new events arrive:
@@ -56,7 +58,7 @@ Use an `effect` to react every time new events arrive:
 ```typescript
 import { Component, ChangeDetectionStrategy, effect, signal } from '@angular/core';
 import { ChatComponent } from '@threadplane/chat';
-import { injectAgent } from '@threadplane/ag-ui';
+import { injectAgent, type AgUiAgent } from '@threadplane/ag-ui';
 
 @Component({
   standalone: true,
@@ -70,7 +72,7 @@ import { injectAgent } from '@threadplane/ag-ui';
   `,
 })
 export class AnalysisComponent {
-  protected readonly agent = injectAgent();
+  protected readonly agent = injectAgent() as AgUiAgent;
   protected readonly progress = signal<number | null>(null);
 
   constructor() {
@@ -94,7 +96,7 @@ When you only need to derive a value, `computed` is more concise:
 ```typescript
 import { Component, ChangeDetectionStrategy, computed } from '@angular/core';
 import { ChatComponent } from '@threadplane/chat';
-import { injectAgent } from '@threadplane/ag-ui';
+import { injectAgent, type AgUiAgent } from '@threadplane/ag-ui';
 import type { CustomStreamEvent } from '@threadplane/ag-ui';
 
 @Component({
@@ -107,7 +109,7 @@ import type { CustomStreamEvent } from '@threadplane/ag-ui';
   `,
 })
 export class AnalysisComponent {
-  protected readonly agent = injectAgent();
+  protected readonly agent = injectAgent() as AgUiAgent;
 
   protected readonly progressEvents = computed(() =>
     this.agent.customEvents().filter(
diff --git a/apps/website/src/components/landing/DemoShowcase.tsx b/apps/website/src/components/landing/DemoShowcase.tsx
index ceb97880b..9a698275e 100644
--- a/apps/website/src/components/landing/DemoShowcase.tsx
+++ b/apps/website/src/components/landing/DemoShowcase.tsx
@@ -19,8 +19,8 @@ interface DemoMedia {
 }
 
 const MEDIA: DemoMedia[] = [
-  { key: 'langgraph', tabLabel: 'LangGraph', url: 'demo.threadplane.ai', videoMp4: '/demo/langgraph-demo.mp4', videoWebm: '/demo/langgraph-demo.webm', poster: '/demo/langgraph-demo-poster.webp', href: DEMOS[0].href },
-  { key: 'ag-ui', tabLabel: 'AG-UI', url: 'ag-ui.threadplane.ai', videoMp4: '/demo/ag-ui-demo.mp4', videoWebm: '/demo/ag-ui-demo.webm', poster: '/demo/ag-ui-demo-poster.webp', href: DEMOS[1].href },
+  { key: 'langgraph', tabLabel: 'LangGraph', url: 'demo.threadplane.ai', videoMp4: '/demo/langgraph-demo.mp4', videoWebm: '/demo/langgraph-demo.webm', poster: '/demo/langgraph-demo-poster.webp', href: DEMOS.find((d) => d.key === 'langgraph')!.href },
+  { key: 'ag-ui', tabLabel: 'AG-UI', url: 'ag-ui.threadplane.ai', videoMp4: '/demo/ag-ui-demo.mp4', videoWebm: '/demo/ag-ui-demo.webm', poster: '/demo/ag-ui-demo-poster.webp', href: DEMOS.find((d) => d.key === 'ag-ui')!.href },
 ];
 
 export function DemoShowcase() {
diff --git a/apps/website/src/components/shared/Nav.tsx b/apps/website/src/components/shared/Nav.tsx
index 4592cd662..e39689733 100644
--- a/apps/website/src/components/shared/Nav.tsx
+++ b/apps/website/src/components/shared/Nav.tsx
@@ -309,7 +309,7 @@ export function Nav() {
                                     destination_url: `/docs/${currentLib.id}/${page.section}/${page.slug}`,
                                     cta_id: 'mobile_nav_docs_page',
                                     cta_text: page.title,
-                                    library: currentLib.id === 'langgraph' || currentLib.id === 'render' || currentLib.id === 'chat' ? currentLib.id : 'unknown',
+                                    library: currentLib.id === 'langgraph' || currentLib.id === 'render' || currentLib.id === 'chat' || currentLib.id === 'ag-ui' ? currentLib.id : 'unknown',
                                   });
                                   setOpen(false);
                                 }}
diff --git a/apps/website/src/lib/analytics/events.ts b/apps/website/src/lib/analytics/events.ts
index 5d06529f0..d678b2b25 100644
--- a/apps/website/src/lib/analytics/events.ts
+++ b/apps/website/src/lib/analytics/events.ts
@@ -87,7 +87,7 @@ export type CtaId =
   | `final_cta_${string}`
   | `home_demo_${string}`;
 
-export type AnalyticsLibrary = 'langgraph' | 'render' | 'chat' | 'unknown';
+export type AnalyticsLibrary = 'langgraph' | 'render' | 'chat' | 'ag-ui' | 'unknown';
 
 export type WhitepaperId = 'overview' | 'angular' | 'render' | 'chat';