diff --git a/.agents/skills/build-agent/SKILL.md b/.agents/skills/build-agent/SKILL.md
new file mode 100644
index 0000000..6dcac18
--- /dev/null
+++ b/.agents/skills/build-agent/SKILL.md
@@ -0,0 +1,115 @@
+---
+name: build-agent
+description: Build and ship a new installable agent in this repo, following the web-agent pattern from development to CLI to production. USE WHEN adding a new agent, adding tools to an agent, exposing an agent through the agentcn CLI/registry, writing agent docs, or wiring the docs demo. Trigger words - new agent, add agent, add a tool, register agent, agent registry, agentcn add, agent docs demo.
+---
+
+# Build an Agent (dev → CLI → prod)
+
+This skill is the canonical, repeatable recipe for adding a new agent to this
+repo. It mirrors the reference implementation, the **web-agent**
+(`ai/agents/web/`), which is distributed to users through the `agentcn` CLI.
+
+Follow the checklist top-to-bottom. Each phase links to a deeper reference file
+under `references/`. Always copy the existing web-agent conventions instead of
+inventing new ones — consistency is what makes the registry + CLI work.
+
+## Mental model
+
+An agent in this repo has **five layers**. Adding an agent means touching each:
+
+1. **Source** — the agent + tools live in `ai/agents/<name>/`. This is the code
+   users actually run. (→ `references/agent-anatomy.md`)
+2. **Registry** — `registry/registry-agents.ts` declares which files, deps, and
+   env vars make up the agent. A build script turns this into static JSON at
+   `apps/web/public/r/<name>.json`. (→ `references/registry-cli-prod.md`)
+3. **CLI** — `agentcn add <name>` fetches that JSON and installs the agent into a
+   user's project. The CLI is generic; you don't edit it per-agent. (→
+   `references/registry-cli-prod.md`)
+4. **Docs** — `apps/web/content/docs/agents/<name>.mdx` documents install +
+   wiring. (→ `references/docs-and-demo.md`)
+5. **Demo** — `apps/web/lib/agent-demos/<name>.ts` powers the zero-cost
+   simulated preview shown in the docs. (→ `references/docs-and-demo.md`)
+
+## Conventions (do not deviate)
+
+- **Package manager:** `pnpm` (see `packageManager` in root `package.json`).
+- **Task runner:** Nx. Prefer `pnpm exec nx run ...` or the root `package.json`
+  scripts over calling tools directly.
+- **Model:** `anthropic("claude-sonnet-4-5-20250929")` via `@ai-sdk/anthropic`.
+- **AI SDK:** Vercel `ai` (`streamText`, `tool`, `stepCountIs`).
+- **Tool schemas:** `zod`, defined in a dedicated `schema.ts`, imported by tools.
+- **Agent name:** kebab-case, matches the folder, the registry `name`, the docs
+  slug, and the demo `agentId` — all identical. E.g. `web-agent`.
+- **Env vars:** never hardcode secrets. Read from `process.env` and throw a clear
+  error if missing (see `tools/core.ts`).
+
+## Checklist
+
+### Phase 1 — Scaffold the source (`ai/agents/<name>/`)
+
+Copy the web-agent layout. Full templates in `references/agent-anatomy.md`.
+
+- [ ] `ai/agents/<name>/index.ts` — re-export the agent: `export { <name>Agent } from "./agent"`.
+- [ ] `ai/agents/<name>/agent.ts` — `streamText` call with model, system prompt, tools, `stopWhen`.
+- [ ] `ai/agents/<name>/prompt.ts` — the `SYSTEM_PROMPT` string.
+- [ ] `ai/agents/<name>/tools/schema.ts` — one zod schema per tool.
+- [ ] `ai/agents/<name>/tools/core.ts` — shared clients/helpers + env-var guards.
+- [ ] `ai/agents/<name>/tools/<tool>.ts` — one file per tool using `tool({...})`.
+- [ ] `ai/agents/<name>/tools/toolset.ts` — map tool names → tool defs.
+- [ ] `ai/agents/<name>/tools/index.ts` — `export { <name>Toolset } from "./toolset"`.
+- [ ] `ai/agents/<name>/tools/types.ts` — shared TS types (optional).
+- [ ] `ai/agents/<name>/tools/services/*.ts` — external API clients (optional).
+
+### Phase 2 — Tests (`ai/agents/<name>/test/`)
+
+- [ ] `test/test-helpers.ts` — `describeIf<Provider>` guards keyed on env vars.
+- [ ] `test/<tool>.test.ts` — one suite per tool; live-API suites use the guards.
+- [ ] Run `pnpm test:web-agent`-equivalent: `pnpm jest ai/agents/<name>`.
+
+### Phase 3 — Register for distribution
+
+- [ ] Add an entry to the `agents` array in `registry/registry-agents.ts`
+      (name, description, title, categories, `dependencies`, `envVars`, and every
+      file from Phase 1 with its `type`).
+- [ ] Build the registry: `pnpm agentcn:registry:build`.
+- [ ] Confirm `apps/web/public/r/<name>.json` and updated `index.json` exist.
+
+### Phase 4 — Docs + demo
+
+- [ ] `apps/web/content/docs/agents/<name>.mdx` — frontmatter (`title`,
+      `description`, `component: true`), `<AgentDemoPreview agentId="<name>" />`,
+      install tabs, wiring, tools reference.
+- [ ] Add the slug to `pages` in `apps/web/content/docs/agents/meta.json`.
+- [ ] `apps/web/lib/agent-demos/<name>.ts` — an `AgentDemoConfig` with scenarios.
+- [ ] Register it in `apps/web/lib/agent-demos/index.ts` (`agentDemos` map).
+
+### Phase 5 — Verify (dev) and ship (prod)
+
+- [ ] `pnpm exec nx run @kit/web:typecheck`
+- [ ] `pnpm exec nx run @kit/web:build`
+- [ ] `pnpm deploy:build` (registry build + web build — what prod runs).
+- [ ] Optional live check: `pnpm agentcn:registry:verify-live`.
+- [ ] Ship: registry JSON deploys with the web app; the CLI is published via
+      `nx release` on an `agentcn@*` tag. See `references/registry-cli-prod.md`.
+
+## Quick command reference
+
+```bash
+pnpm jest ai/agents/<name>          # run agent tests
+pnpm agentcn:registry:build         # regenerate public/r/*.json (REQUIRED after registry edits)
+pnpm exec nx run @kit/web:typecheck # typecheck the web app + agent source
+pnpm exec nx run @kit/web:build     # build docs/marketing site
+pnpm deploy:build                   # registry build + web build (prod parity)
+npx agentcn@latest add <name>       # what a user runs to install your agent
+```
+
+## Common mistakes
+
+- **Forgetting `pnpm agentcn:registry:build`** after editing source or the
+  registry — the CLI serves stale JSON and installs the old files.
+- **Name drift** — folder, registry `name`, docs slug, and demo `agentId` must be
+  identical.
+- **Adding a file to `ai/agents/<name>/` but not to `files` in the registry** —
+  the CLI won't install it, so the agent breaks in the user's project.
+- **New dependency not listed in the registry `dependencies`** — user install
+  fails at runtime. Keep `dependencies`/`envVars` in sync with the source.
diff --git a/.agents/skills/build-agent/references/agent-anatomy.md b/.agents/skills/build-agent/references/agent-anatomy.md
new file mode 100644
index 0000000..1c1eb64
--- /dev/null
+++ b/.agents/skills/build-agent/references/agent-anatomy.md
@@ -0,0 +1,202 @@
+# Agent anatomy — source layout & templates
+
+Reference implementation: `ai/agents/web/`. Copy this structure verbatim for a
+new agent, replacing `web`/`<name>` and the tool set.
+
+## Directory layout
+
+```
+ai/agents/<name>/
+├── index.ts              # public entry: re-exports the agent
+├── agent.ts              # the agent (streamText call)
+├── prompt.ts            # SYSTEM_PROMPT string
+├── tools/
+│   ├── index.ts          # re-exports the toolset
+│   ├── toolset.ts        # { tool_name: toolDef } passed to the agent
+│   ├── schema.ts         # zod input schemas (one per tool)
+│   ├── core.ts           # shared clients + env-var guards + helpers
+│   ├── types.ts          # shared TS types (optional)
+│   ├── <tool>.ts         # one file per tool (tool({...}))
+│   └── services/
+│       └── <service>.ts  # external API client wrappers (optional)
+└── test/
+    ├── test-helpers.ts   # describeIf<Provider> guards
+    └── <tool>.test.ts    # one suite per tool
+```
+
+## Layer 1 — `index.ts`
+
+Thin public surface. Consumers import from `ai/agents/<name>`.
+
+```ts
+export { webAgent } from "./agent";
+```
+
+## Layer 2 — `agent.ts`
+
+The agent is a plain function that returns a `streamText` result. It wires the
+model, system prompt, tools, and a stop condition. Keep it this small — all the
+behavior lives in the prompt and tools.
+
+```ts
+import { anthropic } from "@ai-sdk/anthropic";
+import { streamText, type ModelMessage, stepCountIs } from "ai";
+import { SYSTEM_PROMPT } from "./prompt";
+import { webToolset } from "./tools";
+
+export function webAgent(messages: ModelMessage[]) {
+  return streamText({
+    model: anthropic("claude-sonnet-4-5-20250929"),
+    system: SYSTEM_PROMPT,
+    messages,
+    tools: webToolset,
+    stopWhen: [stepCountIs(20)],
+  });
+}
+```
+
+Notes:
+- **`messages: ModelMessage[]`** in, streaming result out. The caller (an API
+  route, script, or the demo app) owns the transport.
+- **`stopWhen: [stepCountIs(20)]`** caps the tool-use loop. Tune per agent.
+- Keep the model choice consistent across agents unless there's a reason.
+
+## Layer 3 — `prompt.ts`
+
+Export a single `SYSTEM_PROMPT` constant. Describe the agent's role, when to use
+each tool, and output/citation rules. Keep tool names in the prompt exactly
+matching the `toolset.ts` keys.
+
+```ts
+export const SYSTEM_PROMPT = `You are a web research agent.
+...
+Use web_search for quick lookups. Use deep_research for multi-source reports.
+Always cite sources as markdown links.`;
+```
+
+## Layer 4 — Tools
+
+### `tools/schema.ts` — validation
+
+One zod schema per tool. Use `.describe()` on every field — the model reads
+these descriptions.
+
+```ts
+import { z } from "zod";
+
+export const webSearchSchema = z.object({
+  query: z.string().describe("The search query."),
+  num_results: z
+    .number()
+    .int()
+    .min(1)
+    .max(25)
+    .optional()
+    .default(5)
+    .describe("Maximum number of search results."),
+});
+```
+
+### `tools/core.ts` — shared clients & env guards
+
+Centralize provider clients and secret access. Every secret read throws a clear
+error when missing (never silently fall back).
+
+```ts
+import Exa from "exa-js";
+
+export function getExaClient() {
+  const exaApiKey = process.env["EXA_API_KEY"];
+  if (!exaApiKey) {
+    throw new Error("EXA_API_KEY is not set.");
+  }
+  return new Exa(exaApiKey);
+}
+```
+
+Put filesystem/artifact helpers here too if the agent persists output (the
+web-agent writes to `data/<name>.local/` via `saveArtifact`).
+
+### `tools/<tool>.ts` — a tool
+
+Each tool is `tool({ description, inputSchema, execute })`. `execute` receives
+the validated, typed args. Return a serializable object; a `success` flag plus a
+`content` payload is the house style.
+
+```ts
+import { tool } from "ai";
+import { getExaClient } from "./core";
+import { webSearchSchema } from "./schema";
+
+export const webSearchTool = tool({
+  description: "Search the web for up-to-date information.",
+  inputSchema: webSearchSchema,
+  execute: async ({ query, num_results }) => {
+    const exa = getExaClient();
+    const { results } = await exa.searchAndContents(query, {
+      numResults: num_results,
+      highlights: true,
+    });
+    return {
+      success: true,
+      content: results.map((r) => ({
+        title: r.title,
+        url: r.url,
+        content: r.highlights.join("\n"),
+      })),
+    };
+  },
+});
+```
+
+### `tools/toolset.ts` — the map
+
+Keys are the tool names the model calls (and what you name in the prompt).
+
+```ts
+import { ToolSet } from "ai";
+import { webSearchTool } from "./web-search";
+import { answerQuestionTool } from "./answer-question";
+
+export const webToolset = {
+  web_search: webSearchTool,
+  answer_question: answerQuestionTool,
+} as ToolSet;
+```
+
+### `tools/index.ts`
+
+```ts
+export { webToolset } from "./toolset";
+```
+
+## Layer 5 — Tests
+
+Live-API tests are gated so CI/local runs without keys don't fail.
+
+`test/test-helpers.ts`:
+
+```ts
+import { describe } from "@jest/globals";
+declare const process: { env: Record<string, string | undefined> };
+
+export const describeIfExa =
+  process.env.EXA_API_KEY ? describe : describe.skip;
+```
+
+`test/web-search.test.ts`:
+
+```ts
+import { describeIfExa } from "./test-helpers";
+
+describeIfExa("web_search (live)", () => {
+  it("returns results", async () => {
+    // ... call the tool's execute and assert on shape
+  });
+});
+```
+
+Run: `pnpm jest ai/agents/<name>`.
+
+> Tests that hit a real provider will fail without network + keys — that's
+> expected. Gate them behind `describeIf<Provider>` so they skip cleanly.
diff --git a/.agents/skills/build-agent/references/docs-and-demo.md b/.agents/skills/build-agent/references/docs-and-demo.md
new file mode 100644
index 0000000..ef1ed6c
--- /dev/null
+++ b/.agents/skills/build-agent/references/docs-and-demo.md
@@ -0,0 +1,210 @@
+# Docs page & simulated demo
+
+Every agent gets a docs page and a zero-cost simulated demo. The demo replays a
+scripted conversation (no live API calls, no keys, no spend) so visitors can see
+the agent "work" in the docs.
+
+## Part A — Docs page (MDX)
+
+### 1. Create the page
+
+`apps/web/content/docs/agents/<name>.mdx`. Frontmatter must set
+`component: true` (enables the MDX components used below).
+
+```mdx
+---
+title: Web Agent
+description: Web research agent with search, deep research, browser, and websets.
+component: true
+---
+
+<AgentDemoPreview agentId="web-agent" />
+
+## Installation
+
+<CodeTabs>
+
+<TabsList>
+  <TabsTrigger value="cli">CLI</TabsTrigger>
+  <TabsTrigger value="manual">Manual</TabsTrigger>
+</TabsList>
+
+<TabsContent value="cli">
+
+```bash
+npx agentcn@latest add web-agent
+```
+
+</TabsContent>
+
+<TabsContent value="manual">
+
+<Steps>
+
+<Step>Install the following dependencies:</Step>
+
+```bash
+npm install ai @ai-sdk/anthropic zod exa-js playwright-core
+```
+
+<Step>Set environment variables in your `.env` file. Get each key from its provider:</Step>
+
+- [ANTHROPIC_API_KEY](https://console.anthropic.com/settings/keys) — Anthropic Console
+- [EXA_API_KEY](https://dashboard.exa.ai/api-keys) — Exa Dashboard
+- [ANCHOR_API_KEY](https://app.anchorbrowser.io/) — Anchor Browser
+
+```bash
+ANTHROPIC_API_KEY=
+EXA_API_KEY=
+ANCHOR_API_KEY=
+```
+
+<Step>Copy the agent files into your project.</Step>
+
+</Steps>
+
+</TabsContent>
+
+</CodeTabs>
+
+## Usage
+
+... show importing and calling the agent ...
+
+## Tools
+
+... document each tool: name, purpose, key inputs ...
+```
+
+- `<AgentDemoPreview agentId="<name>" />` renders the simulated player. The
+  `agentId` **must** match the demo's `agentId` (Part B) and the registry name.
+- The dependency list and env vars must match `registry/registry-agents.ts`.
+
+### 2. Register the page in nav
+
+Add the slug to `pages` in `apps/web/content/docs/agents/meta.json`:
+
+```json
+{
+  "title": "Agents",
+  "pages": ["web-agent", "<name>"]
+}
+```
+
+(The top-level `apps/web/content/docs/meta.json` already includes the `agents`
+section — no change needed there.)
+
+## Part B — Simulated demo data
+
+The demo is pure data. You script the prompt, the tool calls, and the final
+answer; the player animates it.
+
+### 1. Create the demo config
+
+`apps/web/lib/agent-demos/<name>.ts` exporting an `AgentDemoConfig`.
+
+Types (`apps/web/lib/agent-demos/types.ts`):
+
+```ts
+type AgentDemoConfig = {
+  agentId: string          // === registry name / docs slug
+  label: string
+  description: string
+  defaultScenarioId: string
+  scenarios: AgentDemoScenario[]
+}
+
+type AgentDemoScenario = {
+  id: string
+  label: string            // chip label in the UI
+  prompt: string           // the simulated user message
+  assistantParts: DemoMessagePart[]
+}
+```
+
+`DemoMessagePart` is a discriminated union — mix and match to script the run:
+
+- `{ type: "tool", tool: DemoToolName, input: Record<string,string> }` — renders a
+  tool step (pending → running → done). `tool` must be one of the known
+  `DemoToolName`s; add new names to the union in `types.ts` if your agent has new
+  tools.
+- `{ type: "text", text: string }` — the assistant's answer. Supports inline
+  markdown (bold, links, bullet lines).
+- `{ type: "browser_view", ... }` — a simulated browser panel (url, pageTitle,
+  navigationSteps, pageContent).
+- `{ type: "webset_view", ... }` — a simulated result table (title, columns,
+  rows, entityCount).
+
+Example:
+
+```ts
+import type { AgentDemoConfig } from "./types"
+
+export const webAgentDemo: AgentDemoConfig = {
+  agentId: "web-agent",
+  label: "Web Agent",
+  description: "Uses web search, deep research, browser automation, and websets.",
+  defaultScenarioId: "search",
+  scenarios: [
+    {
+      id: "search",
+      label: "Search & cite",
+      prompt: "Find top AI coding agents launched this month with citations.",
+      assistantParts: [
+        { type: "tool", tool: "web_search", input: { query: "AI coding agents 2026" } },
+        { type: "tool", tool: "answer_question", input: { question: "Top agents this month?" } },
+        {
+          type: "text",
+          text: `Here are notable agents:\n\n• **Cursor Agent** — IDE-native. [cursor.com](https://cursor.com)`,
+        },
+      ],
+    },
+    // add scenarios per capability (deep research, browser, webset, ...)
+  ],
+}
+```
+
+Guidelines:
+- Give each scenario a distinct `label` — these become the capability chips.
+- Set `defaultScenarioId` to the most representative scenario.
+- Keep tool `input` realistic; it's shown to users as the tool call.
+- Order `assistantParts` in execution order: tool calls first, rich views next,
+  final `text` last.
+
+### 2. Register the demo
+
+Add it to the `agentDemos` map in `apps/web/lib/agent-demos/index.ts`:
+
+```ts
+import { webAgentDemo } from "./web-agent"
+
+const agentDemos: Record<string, AgentDemoConfig> = {
+  [webAgentDemo.agentId]: webAgentDemo,
+}
+```
+
+That's it — `<AgentDemoPreview agentId="<name>" />` looks the agent up here.
+
+## Rendering internals (for reference only)
+
+You normally don't edit these; they're generic and already handle any config:
+
+- `apps/web/components/agent-demo-preview.tsx` — the MDX entry component.
+- `apps/web/components/agent-demo/agent-demo-player.tsx` — orchestrates replay,
+  scenario chips, thinking state, and reveals parts in sequence.
+- `agent-demo-message.tsx`, `agent-demo-tool-steps.tsx`, `agent-demo-thinking.tsx`,
+  `agent-demo-browser-panel.tsx`, `agent-demo-webset-table.tsx`,
+  `agent-demo-formatted-text.tsx`, `agent-demo-input.tsx` — the individual pieces.
+- `apps/web/lib/agent-demos/tool-labels.ts` — human labels + view extractors.
+
+Only touch these if you're adding a **new part type** (e.g. a new rich view). In
+that case: add the type to `types.ts`, render it in `agent-demo-message.tsx`, and
+handle its timing in `agent-demo-player.tsx`.
+
+## Definition of done
+
+- [ ] `apps/web/content/docs/agents/<name>.mdx` created with `<AgentDemoPreview>`.
+- [ ] Slug added to `apps/web/content/docs/agents/meta.json`.
+- [ ] `apps/web/lib/agent-demos/<name>.ts` created with ≥1 scenario.
+- [ ] Registered in `apps/web/lib/agent-demos/index.ts`.
+- [ ] `pnpm exec nx run @kit/web:build` passes and the demo replays in the docs.
diff --git a/.agents/skills/build-agent/references/registry-cli-prod.md b/.agents/skills/build-agent/references/registry-cli-prod.md
new file mode 100644
index 0000000..262295c
--- /dev/null
+++ b/.agents/skills/build-agent/references/registry-cli-prod.md
@@ -0,0 +1,143 @@
+# Registry, CLI & production
+
+How agent source in `ai/agents/<name>/` becomes something a user installs with
+`npx agentcn@latest add <name>`, and how it reaches production.
+
+## Pipeline overview
+
+```
+ai/agents/<name>/*          registry/registry-agents.ts
+      (source)          →        (declaration)
+                                       │
+                                       │  pnpm agentcn:registry:build
+                                       ▼
+                        apps/web/public/r/<name>.json  +  index.json
+                                       │
+                                       │  served as static files by the web app
+                                       ▼
+                          agentcn add <name>  (CLI fetches JSON, writes files)
+                                       ▼
+                            user's project (installed agent)
+```
+
+Two independently shipped artifacts:
+1. **Registry JSON** — deploys with the web app (`apps/web/public/r/`).
+2. **`agentcn` CLI** — published to npm via `nx release`.
+
+## Step 1 — Declare the agent in the registry
+
+Edit `registry/registry-agents.ts` and add an entry to the `agents` array. The
+shape is `RegistryAgentItem`:
+
+```ts
+{
+  name: "web-agent",                 // === folder / docs slug / demo agentId
+  type: "registry:agent",
+  description: "Web research agent with search, deep research, browser, websets.",
+  title: "Web Agent",
+  categories: ["web", "research", "browser"],
+  dependencies: ["ai", "@ai-sdk/anthropic", "zod", "exa-js", "playwright-core"],
+  envVars: {
+    ANTHROPIC_API_KEY: "",
+    EXA_API_KEY: "",
+    ANCHOR_API_KEY: "",
+  },
+  files: [
+    { path: "ai/agents/web/index.ts", type: "registry:agent" },
+    { path: "ai/agents/web/agent.ts", type: "registry:agent" },
+    { path: "ai/agents/web/prompt.ts", type: "registry:agent" },
+    { path: "ai/agents/web/tools/index.ts", type: "registry:lib" },
+    { path: "ai/agents/web/tools/toolset.ts", type: "registry:lib" },
+    { path: "ai/agents/web/tools/schema.ts", type: "registry:lib" },
+    { path: "ai/agents/web/tools/core.ts", type: "registry:lib" },
+    { path: "ai/agents/web/tools/web-search.ts", type: "registry:lib" },
+    // ...every file the agent needs to run
+  ],
+  meta: { providers: ["anthropic", "exa", "anchor"] },
+}
+```
+
+Rules:
+- **Every file** the agent imports at runtime must be listed in `files`. If it's
+  not listed, the CLI won't install it.
+- `type` is `registry:agent` for the core agent files and `registry:lib` for
+  tools/helpers. (An optional `target` overrides the install path; default is the
+  same `path`.)
+- Keep `dependencies` and `envVars` in sync with what the source actually uses.
+  These drive the CLI's dependency install and `.env` scaffolding.
+
+## Step 2 — Build the registry JSON
+
+```bash
+pnpm agentcn:registry:build
+```
+
+This runs `scripts/build-agent-registry.mts`, which:
+- reads each entry from `registry/registry-agents.ts`,
+- inlines the **content** of every listed file,
+- writes `apps/web/public/r/<name>.json` per agent,
+- writes an aggregate `apps/web/public/r/index.json` (drives `agentcn list`).
+
+> ALWAYS re-run this after editing agent source or the registry. The CLI serves
+> whatever JSON is committed/deployed, not the live source.
+
+Verify the output exists and includes your new files:
+`apps/web/public/r/<name>.json`.
+
+## Step 3 — How the CLI consumes it (no per-agent edits)
+
+The `agentcn` CLI lives in `packages/agentcn/cli/`. It's generic — you do not
+change it when adding an agent. For reference:
+
+- `src/commands/add.ts` — `agentcn add <name>`: fetches `r/<name>.json`, builds an
+  install plan, installs deps, writes files, scaffolds env vars.
+- `src/commands/list.ts` / `info.ts` — read `index.json` / a single item.
+- `src/lib/registry.ts` — resolves the registry URL and fetches JSON.
+- `src/lib/{deps,package-json,project,config,install-plan}.ts` — install logic.
+- Tests: `src/tests/*.test.ts` (run with the CLI's `nx test` target).
+
+You'd only touch the CLI to change *install behavior* for all agents (e.g. a new
+`type`, a new config option) — not to add a single agent.
+
+## Step 4 — Verify (dev)
+
+```bash
+pnpm jest ai/agents/<name>          # agent unit/live tests
+pnpm exec nx run @kit/web:typecheck # typecheck source + web app
+pnpm exec nx run @kit/web:build     # build the site (includes docs)
+pnpm deploy:build                   # registry build + web build (prod parity)
+```
+
+Optional end-to-end registry check against a running/deployed site:
+
+```bash
+pnpm agentcn:registry:verify-live      # scripts/verify-agentcn-registry-live.sh
+pnpm agentcn:runner-matrix-smoke       # CLI install smoke across package managers
+```
+
+## Step 5 — Production
+
+- **Registry JSON** ships automatically: `pnpm deploy:build` runs
+  `agentcn:registry:build` then `web:build`, and the JSON under
+  `apps/web/public/r/` is deployed as static assets with the web app. Once the
+  site deploys, `agentcn add <name>` can install your agent.
+- **CLI publishing** (only when the CLI package itself changed): the repo uses
+  Nx release.
+
+  ```bash
+  pnpm release            # version + changelog + publish
+  pnpm release:version    # bump versions only
+  pnpm release:changelog  # generate changelog only
+  pnpm release:publish    # publish only
+  ```
+
+  Publishing is triggered on an `agentcn@*` git tag (see the publish workflow in
+  `.github/workflows/`). Adding a new agent usually does **not** require a CLI
+  release — only a site deploy with the rebuilt registry.
+
+## Definition of done
+
+- [ ] Entry added to `registry/registry-agents.ts` with all files, deps, env vars.
+- [ ] `pnpm agentcn:registry:build` run; `public/r/<name>.json` + `index.json` updated.
+- [ ] `pnpm deploy:build` passes.
+- [ ] (If applicable) CLI released via `nx release`.
diff --git a/.env.example b/.env.example
index f8e47eb..a504fa6 100644
--- a/.env.example
+++ b/.env.example
@@ -1,4 +1,3 @@
 # Required for agent
 ANTHROPIC_API_KEY=
-AGENTCN_REGISTRY_URL=https://agentcn.dev/r
-NEXT_PUBLIC_AGENT_DEMO_URL=
\ No newline at end of file
+AGENTCN_REGISTRY_URL=https://agentcn.dev/r
\ No newline at end of file
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 81b4c45..e57189e 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -45,7 +45,6 @@ jobs:
     timeout-minutes: 15
     env:
       NEXT_PUBLIC_APP_URL: https://agentcn.dev
-      NEXT_PUBLIC_AGENT_DEMO_URL: https://kit-demo-agentcn-ui.vercel.app
     steps:
       - name: Checkout repository
         uses: actions/checkout@v4
diff --git a/README.md b/README.md
index d0ed136..c42372f 100644
--- a/README.md
+++ b/README.md
@@ -78,16 +78,18 @@ pnpm web
 
 Open [http://localhost:3000](http://localhost:3000) for the marketing site and docs.
 
-### Run the agent demo embed
+### Run the agent demo app (optional)
 
-The docs live preview expects a demo app on port **3001**:
+For live agent testing with your API keys, run the demo app on port **3001**:
 
 ```bash
 cd examples/agent-ui-template
 pnpm install
-pnpm dev:embed    # port 3001 — matches NEXT_PUBLIC_AGENT_DEMO_URL
+pnpm dev:embed    # port 3001
 ```
 
+Docs agent pages use simulated examples and do not require this app.
+
 ### Build for production
 
 ```bash
@@ -112,7 +114,6 @@ For the docs site (`apps/web/.env`):
 
 ```env
 NEXT_PUBLIC_APP_URL=http://localhost:3000
-NEXT_PUBLIC_AGENT_DEMO_URL=http://localhost:3001
 ```
 
 ### Getting API keys
diff --git a/apps/web/.env.example b/apps/web/.env.example
index 408d605..0090f17 100644
--- a/apps/web/.env.example
+++ b/apps/web/.env.example
@@ -1,2 +1 @@
 NEXT_PUBLIC_APP_URL=https://agentcn.dev
-NEXT_PUBLIC_AGENT_DEMO_URL=http://localhost:3001
diff --git a/apps/web/app/(view)/view/[name]/page.tsx b/apps/web/app/(view)/view/[name]/page.tsx
index 6e3434b..0c48e5c 100644
--- a/apps/web/app/(view)/view/[name]/page.tsx
+++ b/apps/web/app/(view)/view/[name]/page.tsx
@@ -44,7 +44,7 @@ export async function generateMetadata({
       url: absoluteUrl(`/view/${item.name}`),
       images: [
         {
-          url: siteConfig.ogImage,
+          url: absoluteUrl(siteConfig.ogImage),
           width: 1200,
           height: 630,
           alt: siteConfig.name,
@@ -55,7 +55,7 @@ export async function generateMetadata({
       card: "summary_large_image",
       title,
       description,
-      images: [siteConfig.ogImage],
+      images: [absoluteUrl(siteConfig.ogImage)],
       creator: "@shadcn",
     },
   }
diff --git a/apps/web/app/layout.tsx b/apps/web/app/layout.tsx
index 0fed024..4104ee8 100644
--- a/apps/web/app/layout.tsx
+++ b/apps/web/app/layout.tsx
@@ -4,6 +4,7 @@ import Script from "next/script"
 
 import { META_THEME_COLORS, siteConfig } from "@/lib/config"
 import { fontVariables } from "@/lib/fonts"
+import { defaultOgImage } from "@/lib/metadata"
 import { cn, getSiteUrl } from "@/lib/utils"
 import { LayoutProvider } from "@/hooks/use-layout"
 import { Toaster } from "@/components/ui/sonner"
@@ -62,20 +63,13 @@ export const metadata: Metadata = {
     title: siteConfig.name,
     description: siteConfig.description,
     siteName: siteConfig.name,
-    images: [
-      {
-        url: `${siteUrl}/opengraph-image.png`,
-        width: 1200,
-        height: 630,
-        alt: siteConfig.name,
-      },
-    ],
+    images: [defaultOgImage],
   },
   twitter: {
     card: "summary_large_image",
     title: siteConfig.name,
     description: siteConfig.description,
-    images: [`${siteUrl}/opengraph-image.png`],
+    images: [defaultOgImage.url],
     creator: `@${siteConfig.social.twitterHandle}`,
   },
   manifest: `${siteConfig.url}/site.webmanifest`,
diff --git a/apps/web/app/opengraph-image.tsx b/apps/web/app/opengraph-image.tsx
new file mode 100644
index 0000000..469ca59
--- /dev/null
+++ b/apps/web/app/opengraph-image.tsx
@@ -0,0 +1,98 @@
+import { ImageResponse } from "next/og"
+
+import { siteConfig } from "@/lib/config"
+
+export const alt = siteConfig.name
+export const size = {
+  width: 1200,
+  height: 630,
+}
+export const contentType = "image/png"
+
+export default function OpenGraphImage() {
+  return new ImageResponse(
+    (
+      <div
+        style={{
+          width: "100%",
+          height: "100%",
+          display: "flex",
+          flexDirection: "column",
+          justifyContent: "space-between",
+          padding: "64px",
+          background: "linear-gradient(145deg, #09090b 0%, #18181b 45%, #09090b 100%)",
+          color: "#fafafa",
+          fontFamily: "system-ui, sans-serif",
+        }}
+      >
+        <div style={{ display: "flex", alignItems: "center", gap: "16px" }}>
+          <svg
+            width="56"
+            height="56"
+            viewBox="0 0 32 32"
+            fill="none"
+            xmlns="http://www.w3.org/2000/svg"
+          >
+            <path
+              d="M7.5 21.5C7.5 12.8 13.2 7.5 19.8 10.6C24.2 12.8 25.8 18.8 23.4 23.6C21.8 26.6 18.4 28.2 14.6 27.8"
+              stroke="#fafafa"
+              strokeWidth="3"
+              strokeLinecap="round"
+              strokeLinejoin="round"
+            />
+            <path
+              d="M21.2 9.8L25.4 22.2"
+              stroke="#fafafa"
+              strokeWidth="3"
+              strokeLinecap="round"
+            />
+            <circle cx="23.4" cy="6.8" r="2.1" fill="#fafafa" />
+          </svg>
+          <span style={{ fontSize: 40, fontWeight: 700, letterSpacing: "-0.02em" }}>
+            AgentCN
+          </span>
+        </div>
+
+        <div style={{ display: "flex", flexDirection: "column", gap: "20px" }}>
+          <div
+            style={{
+              fontSize: 56,
+              fontWeight: 700,
+              lineHeight: 1.1,
+              letterSpacing: "-0.03em",
+              maxWidth: "900px",
+            }}
+          >
+            Installable AI agents for your workflow
+          </div>
+          <div
+            style={{
+              fontSize: 28,
+              lineHeight: 1.4,
+              color: "#a1a1aa",
+              maxWidth: "820px",
+            }}
+          >
+            {siteConfig.description}
+          </div>
+        </div>
+
+        <div
+          style={{
+            display: "flex",
+            alignItems: "center",
+            justifyContent: "space-between",
+            fontSize: 22,
+            color: "#a1a1aa",
+          }}
+        >
+          <span>agentcn.dev</span>
+          <span>CLI · Registry · Docs</span>
+        </div>
+      </div>
+    ),
+    {
+      ...size,
+    }
+  )
+}
diff --git a/apps/web/app/twitter-image.tsx b/apps/web/app/twitter-image.tsx
new file mode 100644
index 0000000..ee29dc8
--- /dev/null
+++ b/apps/web/app/twitter-image.tsx
@@ -0,0 +1 @@
+export { default, alt, contentType, size } from "./opengraph-image"
diff --git a/apps/web/components/agent-demo-preview.tsx b/apps/web/components/agent-demo-preview.tsx
index e3f31e5..ba8463c 100644
--- a/apps/web/components/agent-demo-preview.tsx
+++ b/apps/web/components/agent-demo-preview.tsx
@@ -3,33 +3,28 @@
 import Link from "next/link"
 
 import { CodeBlockCommand } from "@/components/code-block-command"
+import { AgentDemoPlayer } from "@/components/agent-demo/agent-demo-player"
 import { ComponentPreviewTabs } from "@/components/component-preview-tabs"
 
-const demoBaseUrl =
-  process.env.NEXT_PUBLIC_AGENT_DEMO_URL ?? "http://localhost:3001"
-
 export function AgentDemoPreview({
   agentId = "web-agent",
-  align = "center",
+  align = "start",
   replayable = true,
 }: {
   agentId?: string
   align?: "center" | "start" | "end"
   replayable?: boolean
 }) {
-  const embedUrl = `${demoBaseUrl.replace(/\/$/, "")}/embed/${agentId}`
-
   return (
     <ComponentPreviewTabs
       align={align}
       replayable={replayable}
+      codeLabel="Setup"
+      previewHeight={560}
       component={
-        <iframe
-          src={embedUrl}
-          className="size-full rounded-md border-0 bg-background"
-          title="Web Agent live preview"
-          allow="clipboard-write"
-        />
+        <div className="bg-background size-full overflow-hidden rounded-md">
+          <AgentDemoPlayer agentId={agentId} />
+        </div>
       }
       source={
         <div className="space-y-4 p-4">
@@ -48,11 +43,11 @@ export function AgentDemoPreview({
             __bun__="bunx agentcn@latest add web-agent"
           />
           <p className="text-muted-foreground text-sm">
-            Run the demo app locally (requires API keys in{" "}
+            Run the demo app locally for a live agent with your API keys in{" "}
             <code className="bg-muted relative rounded px-[0.3rem] py-[0.1rem] font-mono text-sm">
               .env.local
             </code>
-            ):
+            :
           </p>
           <figure className="overflow-hidden rounded-lg">
             <pre className="bg-code border-border/70 max-w-full min-w-0 overflow-x-auto rounded-[0.375rem] border px-4 py-3.5">
diff --git a/apps/web/components/agent-demo/agent-demo-browser-panel.tsx b/apps/web/components/agent-demo/agent-demo-browser-panel.tsx
new file mode 100644
index 0000000..30fc3d9
--- /dev/null
+++ b/apps/web/components/agent-demo/agent-demo-browser-panel.tsx
@@ -0,0 +1,121 @@
+"use client"
+
+import * as React from "react"
+import { Globe, Loader2, Lock } from "lucide-react"
+
+import type { DemoBrowserViewPart } from "@/lib/agent-demos/types"
+import { cn } from "@/lib/utils"
+import { Badge } from "@/components/ui/badge"
+
+export function AgentDemoBrowserPanel({
+  view,
+  isReplaying = false,
+}: {
+  view: DemoBrowserViewPart
+  isReplaying?: boolean
+}) {
+  const [stepIndex, setStepIndex] = React.useState(
+    isReplaying ? -1 : view.navigationSteps.length - 1
+  )
+  const [showContent, setShowContent] = React.useState(!isReplaying)
+
+  React.useEffect(() => {
+    if (!isReplaying) {
+      setStepIndex(view.navigationSteps.length - 1)
+      setShowContent(true)
+      return
+    }
+
+    setStepIndex(-1)
+    setShowContent(false)
+
+    const timers: number[] = []
+    view.navigationSteps.forEach((_step, index) => {
+      timers.push(
+        window.setTimeout(() => {
+          setStepIndex(index)
+        }, (index + 1) * 700)
+      )
+    })
+
+    timers.push(
+      window.setTimeout(() => {
+        setShowContent(true)
+      }, view.navigationSteps.length * 700 + 400)
+    )
+
+    return () => {
+      timers.forEach((id) => window.clearTimeout(id))
+    }
+  }, [isReplaying, view.navigationSteps])
+
+  const isNavigating = isReplaying && !showContent
+  const currentStep =
+    stepIndex >= 0 ? view.navigationSteps[stepIndex] : "Starting browser session…"
+
+  return (
+    <div className="space-y-2">
+      <div className="border-border overflow-hidden rounded-lg border shadow-sm">
+        <div className="border-border bg-muted/50 flex items-center gap-2 border-b px-3 py-2">
+          <span className="size-2 rounded-full bg-red-500/80" />
+          <span className="size-2 rounded-full bg-yellow-500/80" />
+          <span className="size-2 rounded-full bg-green-500/80" />
+          <div className="bg-background text-muted-foreground ml-1 flex min-w-0 flex-1 items-center gap-1.5 rounded-md border px-2 py-1 text-xs">
+            <Lock className="size-3 shrink-0" />
+            <span className="truncate">{view.url}</span>
+          </div>
+        </div>
+
+        <div className="bg-muted/20 flex items-center justify-between gap-2 border-b px-3 py-1.5">
+          <div className="text-muted-foreground flex min-w-0 items-center gap-1.5 text-xs">
+            {isNavigating ? (
+              <Loader2 className="text-primary size-3 shrink-0 animate-spin" />
+            ) : (
+              <Globe className="size-3 shrink-0" />
+            )}
+            <span className="truncate">{currentStep}</span>
+          </div>
+          <Badge variant="outline" className="shrink-0 text-[10px] font-normal">
+            {view.provider}
+          </Badge>
+        </div>
+
+        <div
+          className={cn(
+            "bg-background space-y-3 p-4 transition-opacity duration-500",
+            showContent ? "opacity-100" : "opacity-40"
+          )}
+        >
+          <div>
+            <h4 className="text-foreground text-sm font-semibold">
+              {view.pageTitle}
+            </h4>
+            <p className="text-muted-foreground text-xs">{view.url}</p>
+          </div>
+
+          <div className="grid gap-2 sm:grid-cols-2">
+            {view.pageContent.map((item) => (
+              <div
+                key={item.heading}
+                className="border-border bg-card rounded-md border p-2.5"
+              >
+                <p className="text-foreground text-xs font-medium">
+                  {item.heading}
+                </p>
+                <p className="text-muted-foreground mt-0.5 text-xs">
+                  {item.detail}
+                </p>
+              </div>
+            ))}
+          </div>
+        </div>
+      </div>
+
+      <p className="text-muted-foreground text-[11px] leading-relaxed">
+        Simulated preview. Real agent uses{" "}
+        <span className="text-foreground font-medium">{view.provider}</span> to
+        open live browser sessions and return results + artifacts.
+      </p>
+    </div>
+  )
+}
diff --git a/apps/web/components/agent-demo/agent-demo-formatted-text.tsx b/apps/web/components/agent-demo/agent-demo-formatted-text.tsx
new file mode 100644
index 0000000..08c2ed3
--- /dev/null
+++ b/apps/web/components/agent-demo/agent-demo-formatted-text.tsx
@@ -0,0 +1,126 @@
+"use client"
+
+import Link from "next/link"
+import type { ReactNode } from "react"
+
+type InlineNode =
+  | { type: "text"; value: string }
+  | { type: "bold"; value: string }
+  | { type: "link"; label: string; href: string }
+
+function parseInline(text: string): InlineNode[] {
+  const nodes: InlineNode[] = []
+  const pattern = /(\*\*[^*]+\*\*|\[[^\]]+\]\([^)]+\))/g
+  let lastIndex = 0
+  let match: RegExpExecArray | null
+
+  while ((match = pattern.exec(text)) !== null) {
+    if (match.index > lastIndex) {
+      nodes.push({ type: "text", value: text.slice(lastIndex, match.index) })
+    }
+
+    const token = match[0]
+    if (token.startsWith("**")) {
+      nodes.push({ type: "bold", value: token.slice(2, -2) })
+    } else {
+      const linkMatch = token.match(/^\[([^\]]+)\]\(([^)]+)\)$/)
+      if (linkMatch) {
+        nodes.push({
+          type: "link",
+          label: linkMatch[1],
+          href: linkMatch[2],
+        })
+      } else {
+        nodes.push({ type: "text", value: token })
+      }
+    }
+
+    lastIndex = match.index + token.length
+  }
+
+  if (lastIndex < text.length) {
+    nodes.push({ type: "text", value: text.slice(lastIndex) })
+  }
+
+  return nodes.length > 0 ? nodes : [{ type: "text", value: text }]
+}
+
+function InlineContent({ text }: { text: string }) {
+  return (
+    <>
+      {parseInline(text).map((node, index) => {
+        if (node.type === "bold") {
+          return (
+            <strong key={index} className="text-foreground font-medium">
+              {node.value}
+            </strong>
+          )
+        }
+
+        if (node.type === "link") {
+          return (
+            <Link
+              key={index}
+              href={node.href}
+              target="_blank"
+              rel="noopener noreferrer"
+              className="text-primary underline-offset-2 hover:underline"
+            >
+              {node.label}
+            </Link>
+          )
+        }
+
+        return <span key={index}>{node.value}</span>
+      })}
+    </>
+  )
+}
+
+export function AgentDemoFormattedText({ text }: { text: string }) {
+  const lines = text.split("\n")
+  const blocks: ReactNode[] = []
+  let listItems: string[] = []
+
+  const flushList = () => {
+    if (listItems.length === 0) return
+    blocks.push(
+      <ul key={`list-${blocks.length}`} className="space-y-2 pl-1">
+        {listItems.map((item, index) => (
+          <li key={index} className="flex gap-2 leading-relaxed">
+            <span className="text-muted-foreground mt-0.5 shrink-0">•</span>
+            <span>
+              <InlineContent text={item} />
+            </span>
+          </li>
+        ))}
+      </ul>
+    )
+    listItems = []
+  }
+
+  for (const line of lines) {
+    const trimmed = line.trim()
+
+    if (!trimmed) {
+      flushList()
+      continue
+    }
+
+    if (trimmed.startsWith("•")) {
+      listItems.push(trimmed.replace(/^•\s*/, ""))
+      continue
+    }
+
+    flushList()
+    blocks.push(
+      <p key={`p-${blocks.length}`} className="leading-relaxed">
+        <InlineContent text={trimmed} />
+      </p>
+    )
+  }
+
+  flushList()
+
+  return <div className="space-y-3 text-sm">{blocks}</div>
+}
diff --git a/apps/web/components/agent-demo/agent-demo-input.tsx b/apps/web/components/agent-demo/agent-demo-input.tsx
new file mode 100644
index 0000000..84cddfc
--- /dev/null
+++ b/apps/web/components/agent-demo/agent-demo-input.tsx
@@ -0,0 +1,74 @@
+"use client"
+
+import { ArrowUp, Loader2 } from "lucide-react"
+
+import { cn } from "@/lib/utils"
+import { Button } from "@/components/ui/button"
+import { Textarea } from "@/components/ui/textarea"
+
+export function AgentDemoInput({
+  value,
+  onChange,
+  onSubmit,
+  disabled,
+  hint,
+  isLoading,
+}: {
+  value: string
+  onChange: (value: string) => void
+  onSubmit: () => void
+  disabled?: boolean
+  hint?: string
+  isLoading?: boolean
+}) {
+  const handleSubmit = (e: React.FormEvent) => {
+    e.preventDefault()
+    onSubmit()
+  }
+
+  return (
+    <div className="shrink-0 space-y-1.5">
+      {hint ? (
+        <p className="text-muted-foreground rounded-md bg-amber-500/10 px-2 py-1.5 text-[11px] text-amber-800 dark:text-amber-200">
+          {hint}
+        </p>
+      ) : null}
+      <form onSubmit={handleSubmit}>
+        <div
+          className={cn(
+            "border-border bg-card flex items-end gap-1.5 rounded-lg border px-2 py-1.5 shadow-sm transition-opacity",
+            isLoading && "opacity-80"
+          )}
+        >
+          <Textarea
+            value={value}
+            onChange={(e) => onChange(e.target.value)}
+            placeholder="Send the example prompt…"
+            rows={2}
+            className="max-h-14 min-h-9 flex-1 resize-none border-0 bg-transparent p-1 text-sm leading-snug shadow-none focus-visible:ring-0"
+            disabled={disabled}
+            onKeyDown={(e) => {
+              if (e.key === "Enter" && !e.shiftKey) {
+                e.preventDefault()
+                onSubmit()
+              }
+            }}
+          />
+          <Button
+            type="submit"
+            size="icon"
+            className="size-7 shrink-0 rounded-full"
+            disabled={disabled || value.trim().length === 0}
+            aria-label="Send message"
+          >
+            {isLoading ? (
+              <Loader2 className="size-3.5 animate-spin" />
+            ) : (
+              <ArrowUp className="size-3.5" />
+            )}
+          </Button>
+        </div>
+      </form>
+    </div>
+  )
+}
diff --git a/apps/web/components/agent-demo/agent-demo-message.tsx b/apps/web/components/agent-demo/agent-demo-message.tsx
new file mode 100644
index 0000000..b1b35e7
--- /dev/null
+++ b/apps/web/components/agent-demo/agent-demo-message.tsx
@@ -0,0 +1,121 @@
+"use client"
+
+import { Bot, User } from "lucide-react"
+
+import type { DemoMessagePart } from "@/lib/agent-demos/types"
+import {
+  getDemoBrowserViews,
+  getDemoText,
+  getDemoToolParts,
+  getDemoWebsetViews,
+} from "@/lib/agent-demos/tool-labels"
+import { cn } from "@/lib/utils"
+import { AgentDemoBrowserPanel } from "@/components/agent-demo/agent-demo-browser-panel"
+import { AgentDemoFormattedText } from "@/components/agent-demo/agent-demo-formatted-text"
+import {
+  AgentDemoToolSteps,
+  type DemoToolStatus,
+} from "@/components/agent-demo/agent-demo-tool-steps"
+import { AgentDemoWebsetTable } from "@/components/agent-demo/agent-demo-webset-table"
+
+export function AgentDemoMessage({
+  role,
+  parts,
+  toolStatuses,
+  animateIn = false,
+  isReplaying = false,
+}: {
+  role: "user" | "assistant"
+  parts: DemoMessagePart[] | string
+  toolStatuses?: DemoToolStatus[]
+  animateIn?: boolean
+  isReplaying?: boolean
+}) {
+  const isUser = role === "user"
+  const text = typeof parts === "string" ? parts : getDemoText(parts)
+  const toolParts = typeof parts === "string" ? [] : getDemoToolParts(parts)
+  const browserViews = typeof parts === "string" ? [] : getDemoBrowserViews(parts)
+  const websetViews = typeof parts === "string" ? [] : getDemoWebsetViews(parts)
+  const showText = Boolean(text)
+  const hasRichViews = browserViews.length > 0 || websetViews.length > 0
+
+  return (
+    <div
+      className={cn(
+        "flex w-full",
+        isUser ? "justify-end" : "justify-start",
+        animateIn && "animate-in fade-in-0 slide-in-from-bottom-2 duration-300"
+      )}
+    >
+      <div
+        className={cn(
+          "flex flex-col gap-1.5",
+          isUser ? "max-w-[90%] items-end" : "w-full max-w-full items-start"
+        )}
+      >
+        <div className="flex items-center gap-2 px-1">
+          <div
+            className={cn(
+              "flex size-5 items-center justify-center rounded-full border shadow-sm",
+              isUser
+                ? "bg-primary text-primary-foreground"
+                : "bg-foreground text-background"
+            )}
+          >
+            {isUser ? <User className="size-3" /> : <Bot className="size-3" />}
+          </div>
+          <span className="text-muted-foreground text-xs font-medium">
+            {isUser ? "You" : "AI Agent"}
+          </span>
+        </div>
+
+        <div
+          className={cn(
+            "relative rounded-2xl px-4 py-3 text-sm shadow-sm",
+            isUser
+              ? "bg-primary text-primary-foreground max-w-full rounded-tr-sm"
+              : "bg-card text-foreground border-border w-full rounded-tl-sm border"
+          )}
+        >
+          {isUser ? (
+            <p className="leading-relaxed">{text}</p>
+          ) : (
+            <div className="space-y-3">
+              {toolParts.length > 0 ? (
+                <AgentDemoToolSteps tools={toolParts} statuses={toolStatuses} />
+              ) : null}
+
+              {browserViews.map((view) => (
+                <AgentDemoBrowserPanel
+                  key={view.url}
+                  view={view}
+                  isReplaying={isReplaying}
+                />
+              ))}
+
+              {websetViews.map((view) => (
+                <AgentDemoWebsetTable
+                  key={view.title}
+                  view={view}
+                  isReplaying={isReplaying}
+                />
+              ))}
+
+              {showText ? (
+                <div
+                  className={cn(
+                    (toolParts.length > 0 || hasRichViews) &&
+                      "border-border border-t pt-3",
+                    animateIn && "animate-in fade-in-0 duration-500"
+                  )}
+                >
+                  <AgentDemoFormattedText text={text} />
+                </div>
+              ) : null}
+            </div>
+          )}
+        </div>
+      </div>
+    </div>
+  )
+}
diff --git a/apps/web/components/agent-demo/agent-demo-player.tsx b/apps/web/components/agent-demo/agent-demo-player.tsx
new file mode 100644
index 0000000..626f55c
--- /dev/null
+++ b/apps/web/components/agent-demo/agent-demo-player.tsx
@@ -0,0 +1,292 @@
+"use client"
+
+import * as React from "react"
+
+import {
+  getAgentDemo,
+  getDefaultScenario,
+  getScenarioById,
+} from "@/lib/agent-demos"
+import type { DemoMessagePart } from "@/lib/agent-demos/types"
+import { getDemoToolParts } from "@/lib/agent-demos/tool-labels"
+import { AgentDemoInput } from "@/components/agent-demo/agent-demo-input"
+import { AgentDemoMessage } from "@/components/agent-demo/agent-demo-message"
+import { AgentDemoScenarioChips } from "@/components/agent-demo/agent-demo-scenario-chips"
+import { AgentDemoThinking } from "@/components/agent-demo/agent-demo-thinking"
+import type { DemoToolStatus } from "@/components/agent-demo/agent-demo-tool-steps"
+
+const STEP_DELAY_MS = 600
+const THINKING_DELAY_MS = 500
+const RICH_VIEW_DELAY_MS = 2200
+const TEXT_DELAY_MS = 400
+
+type PlayerPhase = "idle" | "playing" | "complete"
+
+type PlaybackView = {
+  showUser: boolean
+  showThinking: boolean
+  revealedParts: DemoMessagePart[]
+  toolStatuses: DemoToolStatus[]
+}
+
+function normalizePrompt(value: string) {
+  return value.trim().replace(/\s+/g, " ")
+}
+
+function buildIdleView(scenario: {
+  assistantParts: DemoMessagePart[]
+}): PlaybackView {
+  const tools = getDemoToolParts(scenario.assistantParts)
+  return {
+    showUser: true,
+    showThinking: false,
+    revealedParts: scenario.assistantParts,
+    toolStatuses: tools.map(() => "done" as const),
+  }
+}
+
+function buildEmptyView(): PlaybackView {
+  return {
+    showUser: false,
+    showThinking: false,
+    revealedParts: [],
+    toolStatuses: [],
+  }
+}
+
+function toolStatusesForParts(parts: DemoMessagePart[]): DemoToolStatus[] {
+  return getDemoToolParts(parts).map(() => "done" as const)
+}
+
+export function AgentDemoPlayer({ agentId }: { agentId: string }) {
+  const demo = getAgentDemo(agentId)
+  const defaultScenario = demo ? getDefaultScenario(demo) : undefined
+
+  const [activeScenarioId, setActiveScenarioId] = React.useState(
+    defaultScenario?.id ?? ""
+  )
+  const scenario = demo
+    ? getScenarioById(demo, activeScenarioId) ?? getDefaultScenario(demo)
+    : undefined
+
+  const [phase, setPhase] = React.useState<PlayerPhase>("idle")
+  const [input, setInput] = React.useState(scenario?.prompt ?? "")
+  const [playingScenario, setPlayingScenario] = React.useState<
+    NonNullable<typeof scenario> | null
+  >(null)
+  const [playback, setPlayback] = React.useState<PlaybackView>(buildEmptyView())
+  const [hint, setHint] = React.useState<string>()
+  const timeoutsRef = React.useRef<number[]>([])
+  const scrollRef = React.useRef<HTMLDivElement>(null)
+
+  const displayScenario = playingScenario ?? scenario
+
+  const clearTimeouts = () => {
+    timeoutsRef.current.forEach((id) => window.clearTimeout(id))
+    timeoutsRef.current = []
+  }
+
+  const schedule = (fn: () => void, delay: number) => {
+    const id = window.setTimeout(fn, delay)
+    timeoutsRef.current.push(id)
+  }
+
+  const selectScenario = React.useCallback(
+    (scenarioId: string) => {
+      if (!demo || phase === "playing") return
+
+      const next = getScenarioById(demo, scenarioId)
+      if (!next) return
+
+      clearTimeouts()
+      setActiveScenarioId(scenarioId)
+      setInput(next.prompt)
+      setPlayback(buildIdleView(next))
+      setPhase("idle")
+      setHint(undefined)
+    },
+    [demo, phase]
+  )
+
+  React.useEffect(() => {
+    if (!scenario) return
+    setPlayback(buildIdleView(scenario))
+    setPhase("idle")
+    setInput(scenario.prompt)
+    setHint(undefined)
+  }, [scenario])
+
+  React.useEffect(() => {
+    return () => {
+      timeoutsRef.current.forEach((id) => window.clearTimeout(id))
+    }
+  }, [])
+
+  React.useEffect(() => {
+    scrollRef.current?.scrollTo({
+      top: scrollRef.current.scrollHeight,
+      behavior: phase === "playing" ? "smooth" : "auto",
+    })
+  }, [playback, phase])
+
+  const replayScenario = React.useCallback(
+    (targetScenario: NonNullable<typeof scenario>) => {
+      const parts = targetScenario.assistantParts
+
+      clearTimeouts()
+      setHint(undefined)
+      setPlayingScenario(targetScenario)
+      setPhase("playing")
+      setPlayback(buildEmptyView())
+
+      let delay = STEP_DELAY_MS
+
+      schedule(() => {
+        setPlayback((prev) => ({ ...prev, showUser: true }))
+      }, delay)
+
+      delay += THINKING_DELAY_MS
+      schedule(() => {
+        setPlayback((prev) => ({ ...prev, showThinking: true }))
+      }, delay)
+
+      parts.forEach((part, index) => {
+        const slice = parts.slice(0, index + 1)
+        const toolsInSlice = getDemoToolParts(slice)
+
+        if (part.type === "tool") {
+          delay += STEP_DELAY_MS
+          schedule(() => {
+            setPlayback((prev) => ({
+              ...prev,
+              showThinking: false,
+              revealedParts: slice,
+              toolStatuses: toolsInSlice.map((_, toolIndex) =>
+                toolIndex < toolsInSlice.length - 1 ? "done" : "running"
+              ),
+            }))
+          }, delay)
+
+          delay += STEP_DELAY_MS
+          schedule(() => {
+            setPlayback((prev) => ({
+              ...prev,
+              revealedParts: slice,
+              toolStatuses: toolStatusesForParts(slice),
+            }))
+          }, delay)
+          return
+        }
+
+        delay += STEP_DELAY_MS
+        schedule(() => {
+          setPlayback((prev) => ({
+            ...prev,
+            showThinking: false,
+            revealedParts: slice,
+            toolStatuses: toolStatusesForParts(slice),
+          }))
+        }, delay)
+
+        if (part.type === "browser_view" || part.type === "webset_view") {
+          delay += RICH_VIEW_DELAY_MS
+        }
+      })
+
+      delay += TEXT_DELAY_MS
+      schedule(() => {
+        setPlayback({
+          showUser: true,
+          showThinking: false,
+          revealedParts: parts,
+          toolStatuses: toolStatusesForParts(parts),
+        })
+        setPhase("complete")
+        setPlayingScenario(null)
+      }, delay)
+    },
+    []
+  )
+
+  const handleSubmit = () => {
+    if (!scenario || !demo || phase === "playing") return
+
+    const normalizedInput = normalizePrompt(input)
+    const matchingScenario = demo.scenarios.find(
+      (item) => normalizePrompt(item.prompt) === normalizedInput
+    )
+
+    if (!matchingScenario) {
+      setHint(
+        "This demo only replays example prompts. Pick a scenario chip above or install locally for custom prompts."
+      )
+      return
+    }
+
+    if (matchingScenario.id !== activeScenarioId) {
+      setActiveScenarioId(matchingScenario.id)
+    }
+
+    replayScenario(matchingScenario)
+  }
+
+  if (!demo || !scenario) {
+    return (
+      <div className="text-muted-foreground flex h-full items-center justify-center p-6 text-sm">
+        Demo not found for agent &quot;{agentId}&quot;.
+      </div>
+    )
+  }
+
+  return (
+    <div className="flex h-full flex-col">
+      <div className="border-border shrink-0 border-b px-3 py-2 pr-11">
+        <p className="text-muted-foreground mb-1.5 text-xs">Try a capability</p>
+        <AgentDemoScenarioChips
+          scenarios={demo.scenarios}
+          activeScenarioId={activeScenarioId}
+          onSelect={selectScenario}
+          disabled={phase === "playing"}
+        />
+      </div>
+
+      <div
+        ref={scrollRef}
+        className="min-h-0 flex-1 overflow-y-auto scroll-smooth px-3 py-4"
+      >
+        <div className="space-y-4">
+          {playback.showUser && displayScenario ? (
+            <AgentDemoMessage
+              role="user"
+              parts={displayScenario.prompt}
+              animateIn={phase === "playing"}
+            />
+          ) : null}
+
+          {playback.showThinking ? <AgentDemoThinking /> : null}
+
+          {playback.revealedParts.length > 0 ? (
+            <AgentDemoMessage
+              role="assistant"
+              parts={playback.revealedParts}
+              toolStatuses={playback.toolStatuses}
+              animateIn={phase !== "idle"}
+              isReplaying={phase === "playing"}
+            />
+          ) : null}
+        </div>
+      </div>
+
+      <div className="border-border shrink-0 border-t px-3 py-2">
+        <AgentDemoInput
+          value={input}
+          onChange={setInput}
+          onSubmit={handleSubmit}
+          disabled={phase === "playing"}
+          hint={hint}
+          isLoading={phase === "playing"}
+        />
+      </div>
+    </div>
+  )
+}
diff --git a/apps/web/components/agent-demo/agent-demo-scenario-chips.tsx b/apps/web/components/agent-demo/agent-demo-scenario-chips.tsx
new file mode 100644
index 0000000..19c3cd3
--- /dev/null
+++ b/apps/web/components/agent-demo/agent-demo-scenario-chips.tsx
@@ -0,0 +1,48 @@
+"use client"
+
+import type { AgentDemoScenario } from "@/lib/agent-demos/types"
+import { cn } from "@/lib/utils"
+import { Badge } from "@/components/ui/badge"
+
+export function AgentDemoScenarioChips({
+  scenarios,
+  activeScenarioId,
+  onSelect,
+  disabled,
+}: {
+  scenarios: AgentDemoScenario[]
+  activeScenarioId: string
+  onSelect: (scenarioId: string) => void
+  disabled?: boolean
+}) {
+  return (
+    <div className="flex flex-wrap gap-1.5">
+      {scenarios.map((scenario) => {
+        const isActive = scenario.id === activeScenarioId
+
+        return (
+          <Badge
+            key={scenario.id}
+            variant={isActive ? "default" : "outline"}
+            className={cn(
+              "cursor-pointer px-2.5 py-0.5 text-xs font-normal transition-colors",
+              disabled && "pointer-events-none opacity-50",
+              !isActive && "hover:bg-muted"
+            )}
+            onClick={() => onSelect(scenario.id)}
+            role="button"
+            tabIndex={disabled ? -1 : 0}
+            onKeyDown={(e) => {
+              if (e.key === "Enter" || e.key === " ") {
+                e.preventDefault()
+                onSelect(scenario.id)
+              }
+            }}
+          >
+            {scenario.label}
+          </Badge>
+        )
+      })}
+    </div>
+  )
+}
diff --git a/apps/web/components/agent-demo/agent-demo-thinking.tsx b/apps/web/components/agent-demo/agent-demo-thinking.tsx
new file mode 100644
index 0000000..10df129
--- /dev/null
+++ b/apps/web/components/agent-demo/agent-demo-thinking.tsx
@@ -0,0 +1,33 @@
+"use client"
+
+import { Bot } from "lucide-react"
+
+import { cn } from "@/lib/utils"
+
+export function AgentDemoThinking({ className }: { className?: string }) {
+  return (
+    <div className={cn("flex w-full justify-start", className)}>
+      <div className="flex max-w-[85%] flex-col gap-1.5">
+        <div className="flex items-center gap-2 px-1">
+          <div className="bg-foreground text-background flex size-5 items-center justify-center rounded-full border shadow-sm">
+            <Bot className="size-3" />
+          </div>
+          <span className="text-muted-foreground text-xs font-medium">
+            AI Agent
+          </span>
+        </div>
+
+        <div className="bg-card border-border rounded-2xl rounded-tl-sm border px-4 py-3 shadow-sm">
+          <div className="flex items-center gap-1.5">
+            <span className="bg-muted-foreground/70 size-1.5 animate-bounce rounded-full [animation-delay:0ms]" />
+            <span className="bg-muted-foreground/70 size-1.5 animate-bounce rounded-full [animation-delay:150ms]" />
+            <span className="bg-muted-foreground/70 size-1.5 animate-bounce rounded-full [animation-delay:300ms]" />
+            <span className="text-muted-foreground ml-2 text-xs">
+              Running tools…
+            </span>
+          </div>
+        </div>
+      </div>
+    </div>
+  )
+}
diff --git a/apps/web/components/agent-demo/agent-demo-tool-steps.tsx b/apps/web/components/agent-demo/agent-demo-tool-steps.tsx
new file mode 100644
index 0000000..f38fcb0
--- /dev/null
+++ b/apps/web/components/agent-demo/agent-demo-tool-steps.tsx
@@ -0,0 +1,66 @@
+"use client"
+
+import { Check, Loader2 } from "lucide-react"
+
+import type { DemoToolPart } from "@/lib/agent-demos/types"
+import { getDemoToolLabel } from "@/lib/agent-demos/tool-labels"
+import { cn } from "@/lib/utils"
+
+export type DemoToolStatus = "pending" | "running" | "done"
+
+export function AgentDemoToolSteps({
+  tools,
+  statuses,
+}: {
+  tools: DemoToolPart[]
+  statuses?: DemoToolStatus[]
+}) {
+  if (tools.length === 0) return null
+
+  return (
+    <div className="space-y-2">
+      {tools.map((tool, index) => {
+        const status = statuses?.[index] ?? "done"
+        const isRunning = status === "running"
+        const isPending = status === "pending"
+
+        return (
+          <div
+            key={`${tool.tool}-${index}`}
+            className={cn(
+              "bg-muted/40 flex items-center gap-2 rounded-md border px-2.5 py-2 text-xs transition-all duration-300",
+              isRunning && "border-primary/30 bg-primary/5",
+              isPending && "opacity-40",
+              status === "done" && "border-border/60"
+            )}
+          >
+            <span
+              className={cn(
+                "flex size-4 shrink-0 items-center justify-center rounded-full",
+                isRunning && "text-primary",
+                status === "done" && "text-emerald-600 dark:text-emerald-400",
+                isPending && "text-muted-foreground"
+              )}
+            >
+              {isRunning ? (
+                <Loader2 className="size-3.5 animate-spin" />
+              ) : status === "done" ? (
+                <Check className="size-3.5" />
+              ) : (
+                <span className="bg-muted-foreground/40 size-1.5 rounded-full" />
+              )}
+            </span>
+            <span
+              className={cn(
+                "text-foreground/90 min-w-0 flex-1 truncate",
+                isRunning && "text-foreground"
+              )}
+            >
+              {getDemoToolLabel(tool)}
+            </span>
+          </div>
+        )
+      })}
+    </div>
+  )
+}
diff --git a/apps/web/components/agent-demo/agent-demo-webset-table.tsx b/apps/web/components/agent-demo/agent-demo-webset-table.tsx
new file mode 100644
index 0000000..313476c
--- /dev/null
+++ b/apps/web/components/agent-demo/agent-demo-webset-table.tsx
@@ -0,0 +1,146 @@
+"use client"
+
+import * as React from "react"
+import { Loader2, Table2 } from "lucide-react"
+
+import type { DemoWebsetViewPart } from "@/lib/agent-demos/types"
+import { cn } from "@/lib/utils"
+import { Badge } from "@/components/ui/badge"
+import { Skeleton } from "@/components/ui/skeleton"
+
+export function AgentDemoWebsetTable({
+  view,
+  isReplaying = false,
+}: {
+  view: DemoWebsetViewPart
+  isReplaying?: boolean
+}) {
+  const [visibleRows, setVisibleRows] = React.useState(
+    isReplaying ? 0 : view.rows.length
+  )
+  const [isBuilding, setIsBuilding] = React.useState(isReplaying)
+
+  React.useEffect(() => {
+    if (!isReplaying) {
+      setVisibleRows(view.rows.length)
+      setIsBuilding(false)
+      return
+    }
+
+    setVisibleRows(0)
+    setIsBuilding(true)
+
+    const timers: number[] = []
+    view.rows.forEach((_row, index) => {
+      timers.push(
+        window.setTimeout(() => {
+          setVisibleRows(index + 1)
+        }, (index + 1) * 450)
+      )
+    })
+
+    timers.push(
+      window.setTimeout(() => {
+        setIsBuilding(false)
+      }, view.rows.length * 450 + 300)
+    )
+
+    return () => {
+      timers.forEach((id) => window.clearTimeout(id))
+    }
+  }, [isReplaying, view.rows])
+
+  return (
+    <div className="space-y-2">
+      <div className="border-border overflow-hidden rounded-lg border shadow-sm">
+        <div className="border-border bg-muted/40 flex items-center justify-between gap-2 border-b px-3 py-2">
+          <div className="flex min-w-0 items-center gap-2">
+            <Table2 className="text-muted-foreground size-3.5 shrink-0" />
+            <span className="text-foreground truncate text-xs font-medium">
+              {view.title}
+            </span>
+          </div>
+          <div className="flex shrink-0 items-center gap-1.5">
+            {isBuilding ? (
+              <span className="text-muted-foreground flex items-center gap-1 text-[10px]">
+                <Loader2 className="size-3 animate-spin" />
+                Building…
+              </span>
+            ) : (
+              <Badge variant="secondary" className="text-[10px] font-normal">
+                {view.entityCount} entities
+              </Badge>
+            )}
+            <Badge variant="outline" className="text-[10px] font-normal">
+              {view.provider}
+            </Badge>
+          </div>
+        </div>
+
+        <div className="overflow-x-auto">
+          <table className="w-full min-w-[480px] text-left text-xs">
+            <thead>
+              <tr className="border-border bg-muted/30 border-b">
+                {view.columns.map((column) => (
+                  <th
+                    key={column}
+                    className="text-muted-foreground px-3 py-2 font-medium"
+                  >
+                    {column}
+                  </th>
+                ))}
+              </tr>
+            </thead>
+            <tbody>
+              {Array.from({ length: view.rows.length }).map((_, rowIndex) => {
+                const row = view.rows[rowIndex]
+                const isVisible = rowIndex < visibleRows
+
+                if (!isVisible) {
+                  return (
+                    <tr key={`sk-${rowIndex}`} className="border-border border-b">
+                      {view.columns.map((column) => (
+                        <td key={column} className="px-3 py-2.5">
+                          <Skeleton className="h-3 w-full max-w-24" />
+                        </td>
+                      ))}
+                    </tr>
+                  )
+                }
+
+                return (
+                  <tr
+                    key={row.join("-")}
+                    className={cn(
+                      "border-border border-b last:border-0",
+                      isReplaying && "animate-in fade-in-0 duration-300"
+                    )}
+                  >
+                    {row.map((cell, cellIndex) => (
+                      <td
+                        key={`${rowIndex}-${cellIndex}`}
+                        className={cn(
+                          "px-3 py-2.5",
+                          cellIndex === 0 && "text-foreground font-medium"
+                        )}
+                      >
+                        {cell}
+                      </td>
+                    ))}
+                  </tr>
+                )
+              })}
+            </tbody>
+          </table>
+        </div>
+      </div>
+
+      <p className="text-muted-foreground text-[11px] leading-relaxed">
+        Simulated preview. Real agent uses{" "}
+        <span className="text-foreground font-medium">{view.provider}</span>{" "}
+        (async job) and saves results to artifact files — table UI is demo-only
+        for now.
+      </p>
+    </div>
+  )
+}
diff --git a/apps/web/components/component-preview-tabs.tsx b/apps/web/components/component-preview-tabs.tsx
index a9c9e57..065aca2 100644
--- a/apps/web/components/component-preview-tabs.tsx
+++ b/apps/web/components/component-preview-tabs.tsx
@@ -12,6 +12,8 @@ export function ComponentPreviewTabs({
   align = "center",
   hideCode = false,
   replayable = false,
+  codeLabel = "Code",
+  previewHeight = 400,
   component,
   source,
   ...props
@@ -19,6 +21,8 @@ export function ComponentPreviewTabs({
   align?: "center" | "start" | "end"
   hideCode?: boolean
   replayable?: boolean
+  codeLabel?: string
+  previewHeight?: number
   component: React.ReactNode
   source: React.ReactNode
 }) {
@@ -29,6 +33,8 @@ export function ComponentPreviewTabs({
     setKey((prev) => prev + 1)
   }
 
+  const isPreview = tab === "preview"
+
   return (
     <div
       className={cn("group relative mt-4 mb-12 flex flex-col gap-2", className)}
@@ -52,7 +58,7 @@ export function ComponentPreviewTabs({
                 value="code"
                 className="text-muted-foreground data-[state=active]:text-foreground px-0 text-base data-[state=active]:shadow-none dark:data-[state=active]:border-transparent dark:data-[state=active]:bg-transparent"
               >
-                Code
+                {codeLabel}
               </TabsTrigger>
             </TabsList>
           )}
@@ -60,14 +66,18 @@ export function ComponentPreviewTabs({
       </Tabs>
       <div
         data-tab={tab}
-        className="data-[tab=code]:border-code relative rounded-lg border md:-mx-4"
+        className="data-[tab=code]:border-code relative overflow-hidden rounded-lg border md:-mx-4"
+        style={{ height: previewHeight }}
       >
         <div
           data-slot="preview"
-          data-active={tab === "preview"}
-          className="invisible data-[active=true]:visible"
+          data-active={isPreview}
+          className={cn(
+            "absolute inset-0 flex flex-col",
+            !isPreview && "pointer-events-none opacity-0"
+          )}
         >
-          {replayable && (
+          {replayable && isPreview && (
             <Button
               variant="outline"
               size="icon"
@@ -80,7 +90,7 @@ export function ComponentPreviewTabs({
           <div
             data-align={align}
             className={cn(
-              "preview flex h-[400px] w-full justify-center data-[align=center]:items-center data-[align=end]:items-end data-[align=start]:items-start"
+              "preview flex size-full justify-center data-[align=center]:items-center data-[align=end]:items-end data-[align=start]:items-start"
             )}
             key={key}
           >
@@ -89,8 +99,11 @@ export function ComponentPreviewTabs({
         </div>
         <div
           data-slot="code"
-          data-active={tab === "code"}
-          className="component-preview-code absolute inset-0 hidden overflow-hidden rounded-[inherit] data-[active=true]:block **:[figure]:!m-0 **:[pre]:h-[400px]"
+          data-active={!isPreview}
+          className={cn(
+            "component-preview-code absolute inset-0 overflow-auto rounded-[inherit] **:[figure]:!m-0 **:[pre]:min-h-full",
+            isPreview && "pointer-events-none opacity-0"
+          )}
         >
           {source}
         </div>
diff --git a/apps/web/components/marketing/benefits.tsx b/apps/web/components/marketing/benefits.tsx
index 2d29c2d..a798572 100644
--- a/apps/web/components/marketing/benefits.tsx
+++ b/apps/web/components/marketing/benefits.tsx
@@ -65,7 +65,7 @@ const navOptions = [
   },
   {
     name: "Agents",
-    text: "Agents ship as installable modules with their own docs and live previews. Pick one from the registry, add it to your app, and request new ones in GitHub discussions.",
+    text: "Agents ship as installable modules with their own docs and interactive examples. Pick one from the registry, add it to your app, and request new ones in GitHub discussions.",
   },
   {
     name: "Benefits",
diff --git a/apps/web/content/docs/(root)/changelog.mdx b/apps/web/content/docs/(root)/changelog.mdx
index 05cd4b5..2885c13 100644
--- a/apps/web/content/docs/(root)/changelog.mdx
+++ b/apps/web/content/docs/(root)/changelog.mdx
@@ -4,6 +4,14 @@ description: Release notes for AgentCN docs and product direction.
 toc: false
 ---
 
+## 2026-07-12
+
+### Docs demo preview
+
+- Replaced live iframe embed with zero-cost simulated agent demos in docs.
+- Example conversations show on load with replayable tool-call steps.
+- Setup tab links to CLI install and optional local live demo app.
+
 ## 2026-05-19
 
 ### AgentCN site & docs
diff --git a/apps/web/content/docs/(root)/index.mdx b/apps/web/content/docs/(root)/index.mdx
index 5cb6ac0..5283166 100644
--- a/apps/web/content/docs/(root)/index.mdx
+++ b/apps/web/content/docs/(root)/index.mdx
@@ -11,13 +11,13 @@ Install agents with the CLI, copy source into your project, wire environment var
 
 - **CLI** — `npx agentcn@latest add web-agent` (and more agents over time).
 - **Registry** — hosted agent payloads at [agentcn.dev/r](https://agentcn.dev/r).
-- **Docs** — setup, configuration, and live previews for each agent.
+- **Docs** — setup, configuration, and interactive examples for each agent.
 - **Demo app** — [`examples/agent-ui-template`](https://github.com/anayatkhan1/kit/tree/main/examples/agent-ui-template) for testing agents locally.
 
 ## How to use these docs
 
 1. Start here for project context.
-2. Open **Agents → Web Agent** for install steps, env vars, and a live chat preview.
+2. Open **Agents → Web Agent** for install steps, env vars, and an interactive example demo.
 3. Check **AgentCN Scope** for what is in and out of MVP.
 4. Use the changelog to track doc and product updates.
 
diff --git a/apps/web/content/docs/(root)/scope.mdx b/apps/web/content/docs/(root)/scope.mdx
index 740e71e..2cfd0a5 100644
--- a/apps/web/content/docs/(root)/scope.mdx
+++ b/apps/web/content/docs/(root)/scope.mdx
@@ -11,7 +11,7 @@ This page defines the practical boundary of the first AgentCN release.
 
 - Installable AI agents via the `agentcn` CLI (starting with web-agent).
 - Docs for setup, configuration, and extension.
-- A demo app and embed route for live previews in docs.
+- A demo app for local live testing (optional; docs use simulated examples).
 
 ## Out of scope for MVP
 
@@ -32,7 +32,7 @@ Keeping scope tight helps you:
 ### Phase 1
 
 - Core agent install flow and registry.
-- Web agent docs with live preview.
+- Web agent docs with interactive example demo.
 - CLI publish and hosted registry on agentcn.dev.
 
 ### Phase 2
diff --git a/apps/web/lib/agent-demos/index.ts b/apps/web/lib/agent-demos/index.ts
new file mode 100644
index 0000000..c41f7c3
--- /dev/null
+++ b/apps/web/lib/agent-demos/index.ts
@@ -0,0 +1,30 @@
+/**
+ * Agent docs demo registry.
+ *
+ * To add a new agent demo:
+ * 1. Add the agent to registry/registry-agents.ts
+ * 2. Create apps/web/lib/agent-demos/{agent-id}.ts with a default scenario
+ * 3. Register it in agentDemos below
+ * 4. Add docs MDX: <AgentDemoPreview agentId="{agent-id}" />
+ */
+
+import type { AgentDemoConfig } from "./types"
+import { webAgentDemo } from "./web-agent"
+
+const agentDemos: Record<string, AgentDemoConfig> = {
+  [webAgentDemo.agentId]: webAgentDemo,
+}
+
+export function getAgentDemo(agentId: string): AgentDemoConfig | undefined {
+  return agentDemos[agentId]
+}
+
+export function getDefaultScenario(demo: AgentDemoConfig) {
+  return getScenarioById(demo, demo.defaultScenarioId) ?? demo.scenarios[0]
+}
+
+export function getScenarioById(demo: AgentDemoConfig, scenarioId: string) {
+  return demo.scenarios.find((s) => s.id === scenarioId)
+}
+
+export type { AgentDemoConfig, AgentDemoScenario, DemoMessagePart } from "./types"
diff --git a/apps/web/lib/agent-demos/tool-labels.ts b/apps/web/lib/agent-demos/tool-labels.ts
new file mode 100644
index 0000000..4966420
--- /dev/null
+++ b/apps/web/lib/agent-demos/tool-labels.ts
@@ -0,0 +1,53 @@
+import type { DemoMessagePart, DemoToolPart } from "@/lib/agent-demos/types"
+
+function queryInput(input: Record<string, string>) {
+  return input.query ?? "unknown"
+}
+
+function questionInput(input: Record<string, string>) {
+  return input.question ?? "unknown"
+}
+
+function taskInput(input: Record<string, string>) {
+  return input.task_name ?? input.task ?? "unknown"
+}
+
+const toolLabelFormatters: Record<
+  DemoToolPart["tool"],
+  (part: DemoToolPart) => string
+> = {
+  web_search: (part) => `Web search: ${queryInput(part.input)}`,
+  answer_question: (part) => `Answer question: ${questionInput(part.input)}`,
+  deep_research: (part) => `Deep research: ${taskInput(part.input)}`,
+  use_browser: (part) => `Use browser: ${taskInput(part.input)}`,
+  create_webset: (part) => `Create webset: ${taskInput(part.input)}`,
+}
+
+export function getDemoToolLabel(part: DemoToolPart): string {
+  return toolLabelFormatters[part.tool](part)
+}
+
+export function getDemoText(parts: DemoMessagePart[]): string {
+  return parts
+    .filter((part): part is { type: "text"; text: string } => part.type === "text")
+    .map((part) => part.text)
+    .join("")
+}
+
+export function getDemoToolParts(parts: DemoMessagePart[]): DemoToolPart[] {
+  return parts.filter((part): part is DemoToolPart => part.type === "tool")
+}
+
+export function getDemoBrowserViews(parts: DemoMessagePart[]) {
+  return parts.filter(
+    (part): part is Extract<DemoMessagePart, { type: "browser_view" }> =>
+      part.type === "browser_view"
+  )
+}
+
+export function getDemoWebsetViews(parts: DemoMessagePart[]) {
+  return parts.filter(
+    (part): part is Extract<DemoMessagePart, { type: "webset_view" }> =>
+      part.type === "webset_view"
+  )
+}
diff --git a/apps/web/lib/agent-demos/types.ts b/apps/web/lib/agent-demos/types.ts
new file mode 100644
index 0000000..0b4aaa0
--- /dev/null
+++ b/apps/web/lib/agent-demos/types.ts
@@ -0,0 +1,59 @@
+export type DemoToolName =
+  | "web_search"
+  | "answer_question"
+  | "deep_research"
+  | "use_browser"
+  | "create_webset"
+
+export type DemoToolPart = {
+  type: "tool"
+  tool: DemoToolName
+  input: Record<string, string>
+}
+
+export type DemoTextPart = {
+  type: "text"
+  text: string
+}
+
+export type DemoBrowserViewPart = {
+  type: "browser_view"
+  url: string
+  pageTitle: string
+  provider: "Anchor Browser"
+  navigationSteps: string[]
+  pageContent: Array<{
+    heading: string
+    detail: string
+  }>
+}
+
+export type DemoWebsetViewPart = {
+  type: "webset_view"
+  title: string
+  provider: "Exa Websets"
+  entityCount: number
+  columns: string[]
+  rows: string[][]
+}
+
+export type DemoMessagePart =
+  | DemoToolPart
+  | DemoTextPart
+  | DemoBrowserViewPart
+  | DemoWebsetViewPart
+
+export type AgentDemoScenario = {
+  id: string
+  label: string
+  prompt: string
+  assistantParts: DemoMessagePart[]
+}
+
+export type AgentDemoConfig = {
+  agentId: string
+  label: string
+  description: string
+  defaultScenarioId: string
+  scenarios: AgentDemoScenario[]
+}
diff --git a/apps/web/lib/agent-demos/web-agent.ts b/apps/web/lib/agent-demos/web-agent.ts
new file mode 100644
index 0000000..98f4910
--- /dev/null
+++ b/apps/web/lib/agent-demos/web-agent.ts
@@ -0,0 +1,144 @@
+import type { AgentDemoConfig } from "./types"
+
+export const webAgentDemo: AgentDemoConfig = {
+  agentId: "web-agent",
+  label: "Web Agent",
+  description:
+    "Uses web search, deep research, browser automation, and websets.",
+  defaultScenarioId: "search",
+  scenarios: [
+    {
+      id: "search",
+      label: "Search & cite",
+      prompt:
+        "Find top AI coding agents launched this month with concise citations.",
+      assistantParts: [
+        {
+          type: "tool",
+          tool: "web_search",
+          input: {
+            query: "AI coding agents launched July 2026",
+          },
+        },
+        {
+          type: "tool",
+          tool: "answer_question",
+          input: {
+            question:
+              "What are the top AI coding agents launched this month?",
+          },
+        },
+        {
+          type: "text",
+          text: `Here are notable AI coding agents launched recently:
+
+• **Cursor Agent** — IDE-native agent with multi-file edits and terminal access. [cursor.com](https://cursor.com)
+
+• **Devin 2.0** — Autonomous software engineer for end-to-end task completion. [cognition.ai](https://cognition.ai)
+
+• **Windsurf Cascade** — Flow-based coding agent with deep repo context. [windsurf.com](https://windsurf.com)
+
+These agents emphasize autonomous coding workflows, tool use, and tighter IDE integration.`,
+        },
+      ],
+    },
+    {
+      id: "research",
+      label: "Deep research",
+      prompt:
+        "Research how EU AI Act enforcement changed for foundation model providers in 2026.",
+      assistantParts: [
+        {
+          type: "tool",
+          tool: "deep_research",
+          input: {
+            task: "EU AI Act foundation model enforcement changes 2026",
+          },
+        },
+        {
+          type: "text",
+          text: `Summary of 2026 enforcement shifts for foundation model providers:
+
+• **Documentation duties** — Providers must maintain technical docs and training-data summaries for high-risk downstream use.
+
+• **Systemic risk tier** — Models above compute thresholds face additional incident reporting and red-team audit expectations.
+
+• **Market surveillance** — National authorities gained powers to request model evaluations before public deployment in sensitive sectors.
+
+• **Open-weight carve-outs** — Fine-tuned releases still inherit obligations when deployed in high-risk contexts.
+
+Sources: EU AI Office guidance, Digital Markets compliance briefs, and provider policy updates from Q1–Q2 2026.`,
+        },
+      ],
+    },
+    {
+      id: "browser",
+      label: "Browser",
+      prompt:
+        "Open anthropic.com/pricing and summarize the current Claude plan tiers.",
+      assistantParts: [
+        {
+          type: "tool",
+          tool: "use_browser",
+          input: {
+            task: "Navigate anthropic.com/pricing and extract plan tiers",
+          },
+        },
+        {
+          type: "browser_view",
+          url: "https://www.anthropic.com/pricing",
+          pageTitle: "Claude pricing",
+          provider: "Anchor Browser",
+          navigationSteps: [
+            "Opening browser session…",
+            "Navigating to anthropic.com/pricing…",
+            "Waiting for page load…",
+            "Extracting plan tiers…",
+          ],
+          pageContent: [
+            { heading: "Free", detail: "Limited Claude access with usage caps" },
+            { heading: "Pro", detail: "Higher limits and priority access" },
+            { heading: "Team", detail: "Shared workspace and admin controls" },
+            { heading: "Enterprise", detail: "SSO, custom terms, dedicated support" },
+          ],
+        },
+        {
+          type: "text",
+          text: `Summary: Claude offers **Free**, **Pro**, **Team**, and **Enterprise** tiers. API usage is billed separately per million tokens on the same page.`,
+        },
+      ],
+    },
+    {
+      id: "webset",
+      label: "Webset",
+      prompt:
+        "Create a webset of YC W26 AI infrastructure startups with founders and funding.",
+      assistantParts: [
+        {
+          type: "tool",
+          tool: "create_webset",
+          input: {
+            task: "YC W26 AI infrastructure startups with founders and funding",
+          },
+        },
+        {
+          type: "webset_view",
+          title: "YC W26 · AI infrastructure startups",
+          provider: "Exa Websets",
+          entityCount: 12,
+          columns: ["Company", "Founders", "Round", "Category"],
+          rows: [
+            ["LatticeFlow AI", "Ana Ruiz", "$4.2M Seed", "Observability"],
+            ["Pipestack", "Sam Cho, Priya N.", "$2.1M Pre-seed", "Inference"],
+            ["VaultML", "Marco Bellini", "$3.8M Seed", "On-prem runtime"],
+            ["ContextForge", "Lee & Kim", "$5.0M Seed", "Agent memory"],
+          ],
+        },
+        {
+          type: "text",
+          text: `Webset job completed with **12 entities** and enrichments for founders, funding, and product category. Export as CSV or JSON from the artifact file in a real run.`,
+        },
+      ],
+    },
+  ],
+}
diff --git a/apps/web/lib/config.ts b/apps/web/lib/config.ts
index b550ab5..21ad9d5 100644
--- a/apps/web/lib/config.ts
+++ b/apps/web/lib/config.ts
@@ -1,7 +1,7 @@
 export const siteConfig = {
   name: "AgentCN",
   url: "https://agentcn.dev",
-  ogImage: "https://agentcn.dev/og.jpg",
+  ogImage: "/opengraph-image",
   description:
     "Open source kit for installable AI agents. CLI, registry, docs, and editable agent source in your repo.",
   links: {
diff --git a/apps/web/lib/metadata.ts b/apps/web/lib/metadata.ts
index 7c5f8ee..09c95ed 100644
--- a/apps/web/lib/metadata.ts
+++ b/apps/web/lib/metadata.ts
@@ -1,5 +1,15 @@
 import { Metadata } from "next"
 
+import { siteConfig } from "@/lib/config"
+import { absoluteUrl } from "@/lib/utils"
+
+export const defaultOgImage = {
+  url: absoluteUrl(siteConfig.ogImage),
+  width: 1200,
+  height: 630,
+  alt: siteConfig.name,
+}
+
 export const createStaticOGMetadata = (
   title: string,
   description: string
@@ -7,24 +17,14 @@ export const createStaticOGMetadata = (
   title,
   description,
   openGraph: {
-    images: [
-      {
-        url: "/opengraph-image.png",
-        width: 1200,
-        height: 628,
-        alt: title,
-      },
-    ],
+    title,
+    description,
+    images: [defaultOgImage],
   },
   twitter: {
     card: "summary_large_image",
-    images: [
-      {
-        url: "/twitter-image.png",
-        width: 1200,
-        height: 628,
-        alt: title,
-      },
-    ],
+    title,
+    description,
+    images: [defaultOgImage.url],
   },
 })
diff --git a/examples/agent-ui-template/README.md b/examples/agent-ui-template/README.md
index 52ce9d0..91cc67c 100644
--- a/examples/agent-ui-template/README.md
+++ b/examples/agent-ui-template/README.md
@@ -1,11 +1,13 @@
 # Agent UI Template (Next.js + Vercel AI SDK)
 
-Minimal demo app for the **web-agent** live preview on [agentcn.dev/docs](https://agentcn.dev/docs).
+Minimal demo app for running the **web-agent** locally with real API keys.
+
+Docs at [agentcn.dev/docs](https://agentcn.dev/docs) use simulated examples and do not require this app.
 
 ## Included
 
 - `web-agent` chat UI on `/`
-- Compact embed route at `/embed/web-agent` for docs iframe previews
+- Compact embed route at `/embed/web-agent` for local testing
 
 ## Prerequisites
 
@@ -33,20 +35,13 @@ ANCHOR_API_KEY=...
 ## Commands
 
 - `pnpm dev` — full template app on port 3000
-- `pnpm dev:embed` — embed server on port 3001 (use this for docs local preview)
+- `pnpm dev:embed` — embed server on port 3001
 - `pnpm lint` — Biome checks
 - `pnpm build` — production build
 
-## Docs embed
-
-Point the docs app at this server:
-
-```bash
-# in apps/web/.env
-NEXT_PUBLIC_AGENT_DEMO_URL=http://localhost:3001
-```
+## Local embed route
 
-Then run:
+Run the embed server:
 
 ```bash
 pnpm dev:embed
@@ -57,7 +52,7 @@ Open `http://localhost:3001/embed/web-agent`.
 ## Key files
 
 - `app/api/chat/route.ts` — streaming chat route for web-agent
-- `app/embed/web-agent/` — iframe-friendly embed UI
+- `app/embed/web-agent/` — compact embed UI
 - `lib/agent-registry.ts` — server runtime config
 - `lib/agent-profiles.ts` — UI metadata
 - `tsconfig.json` — `@kit-ai/*` maps to `kit/ai/*` in the monorepo
@@ -67,6 +62,6 @@ Open `http://localhost:3001/embed/web-agent`.
 1. Add source under `kit/ai/agents/<name>/`
 2. Register runtime config in `lib/agent-registry.ts`
 3. Register UI metadata in `lib/agent-profiles.ts`
-4. Add `app/embed/<name>/` if you want a docs preview route
+4. Add `app/embed/<name>/` if you want a local embed route
 
 See [AgentCN scope docs](https://agentcn.dev/docs/scope) for the full registry + publish workflow.