diff --git a/.changeset/e2e-integration-roadmap.md b/.changeset/e2e-integration-roadmap.md
new file mode 100644
index 0000000..05703a4
--- /dev/null
+++ b/.changeset/e2e-integration-roadmap.md
@@ -0,0 +1,6 @@
+---
+"@guidekit/core": patch
+"@guidekit/react": patch
+---
+
+Expand E2E integration roadmap: contract/live test tiers, full tool coverage, publish live gate, proxy voice credential resolution, and widget test hooks.
diff --git a/.changeset/integration-hardening.md b/.changeset/integration-hardening.md
index ea7f28b..ffa3c2a 100644
--- a/.changeset/integration-hardening.md
+++ b/.changeset/integration-hardening.md
@@ -5,4 +5,4 @@
 "@guidekit/cli": patch
 ---
 
-Harden real-app integration: session token recovery after server restart, voice widget transcript streaming, continuous mic listening, doctor VAD checks, and voice E2E smoke tests.
+Harden real-app integration: session token recovery after server restart, voice widget transcript streaming, continuous mic listening, doctor VAD checks, voice E2E smoke tests, and full live-tier Playwright suite (agent tools, platform mode, proxy API, multi-turn).
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index da8e018..3ef991d 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -69,11 +69,11 @@ jobs:
       - name: Install Playwright browsers
         run: npx playwright install --with-deps chromium
 
-      - name: Run E2E tests
+      - name: Run E2E contract tests
         env:
           GUIDEKIT_SECRET: guidekit-example-e2e-secret-32-chars
           LLM_API_KEY: e2e-dummy-llm-key-for-contract-tests
-        run: pnpm test:e2e
+        run: pnpm test:e2e:contract
 
       - name: Upload test results
         if: failure()
diff --git a/.github/workflows/nightly.yml b/.github/workflows/nightly.yml
index b772d07..8346680 100644
--- a/.github/workflows/nightly.yml
+++ b/.github/workflows/nightly.yml
@@ -36,12 +36,13 @@ jobs:
         run: pnpm size:check
 
       - name: Install Playwright browsers
-        run: npx playwright install --with-deps
+        run: npx playwright install --with-deps chromium
 
-      - name: E2E tests
+      - name: E2E contract tests
         env:
           GUIDEKIT_SECRET: guidekit-example-e2e-secret-32-chars
-        run: npx playwright test
+          LLM_API_KEY: e2e-dummy-llm-key-for-contract-tests
+        run: pnpm test:e2e:contract
 
       - name: Dependency audit
         run: pnpm audit --prod
diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml
index 8afe180..6efc30d 100644
--- a/.github/workflows/publish.yml
+++ b/.github/workflows/publish.yml
@@ -14,8 +14,46 @@ concurrency:
   cancel-in-progress: true
 
 jobs:
+  live-e2e:
+    name: Live E2E (pre-publish)
+    if: ${{ !inputs.dry_run }}
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: pnpm/action-setup@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: pnpm
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Install Playwright browsers
+        run: npx playwright install --with-deps chromium
+
+      - name: Run live E2E suite
+        env:
+          LIVE_LLM: '1'
+          GUIDEKIT_SECRET: guidekit-example-e2e-secret-32-chars
+          LLM_API_KEY: ${{ secrets.LLM_API_KEY }}
+          SKIP_NPM_DRY_RUN: '1'
+        run: pnpm check:release
+
+      - name: Upload Playwright report
+        if: failure()
+        uses: actions/upload-artifact@v4
+        with:
+          name: publish-live-e2e-report
+          path: playwright-report/
+          retention-days: 14
+
   publish:
     name: Publish @guidekit/* to npm
+    needs: live-e2e
+    if: ${{ always() && (inputs.dry_run || needs.live-e2e.result == 'success') }}
     runs-on: ubuntu-latest
     environment: npm-publish
     permissions:
diff --git a/AGENTS.md b/AGENTS.md
index 884332a..c92bbfa 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -62,9 +62,52 @@ guidekit/
 
 ### Testing expectations
 
-- Unit tests: Vitest (`pnpm test:unit`)
-- E2E: Playwright (`pnpm test:e2e`) — agent flows in `e2e/`
-- New pipeline or cognitive behavior needs unit coverage; integration changes should touch example app or E2E when user-facing
+- Unit tests: Vitest (`pnpm test:unit`) — all packages
+- Contract E2E: Playwright (`pnpm test:e2e:contract`) — mocked LLM + Web Speech voice, runs on every PR
+- Live E2E: Playwright (`pnpm test:e2e:live`) — real Gemini via proxy; **publish gate only** (`LIVE_LLM=1` + `LLM_API_KEY`)
+- New pipeline or cognitive behavior needs unit coverage; user-facing integration changes should touch example app or contract E2E
+
+### E2E layout
+
+```
+e2e/
+├── contract/     # CI + pnpm check (no API key)
+├── live/         # Pre-publish only
+├── fixtures/     # LLM mocks, Web Speech mocks, helpers
+└── env.ts        # .env.local + LIVE_LLM detection
+```
+
+Voice E2E always mocks the browser Web Speech API — no Deepgram/ElevenLabs in Playwright.
+
+### E2E coverage matrix (user-facing flows)
+
+| Flow | Contract | Live |
+|------|:--------:|:----:|
+| Widget UI / a11y | yes | — |
+| Proxy health / token / LLM | yes | yes |
+| Text chat + streaming | mocked | yes |
+| Multi-turn memory | — | yes |
+| Agent tools (scroll, highlight, navigate, tour, clickElement) | yes | yes |
+| Platform Mode (RAG, plugin, cognitive page) | yes | yes |
+| Session recovery 401 | yes | yes |
+| Voice (Web Speech mock → LLM) | yes | yes |
+| Custom actions / form / readPage / dismiss | yes | partial |
+| STT/TTS proxy key minting | yes | — |
+| Hallucination guard bus event | yes | — |
+| Vanilla IIFE widget | yes | — |
+
+Commands: `pnpm test:e2e:contract` (CI), `pnpm test:e2e:live` (local), `pnpm test:e2e:live:full` (publish gate).
+
+Before release, run `pnpm check:release` (runs live suite twice for the flake budget). Publish workflow uploads Playwright artifacts on failure.
+
+### Release gate (production readiness)
+
+Run `pnpm check:release` before publishing. It includes:
+
+- `pnpm check` (build, typecheck, lint, unit, size, contract E2E)
+- Package artifact verification (`scripts/verify-published-packages.mjs`)
+- CLI subprocess smoke (`packages/cli/src/cli.smoke.test.ts`)
+- Live E2E twice (`pnpm test:e2e:live:full` ×2)
 
 ## Commands
 
@@ -74,6 +117,7 @@ pnpm skills:sync          # Link skills/guidekit for Codex/Cursor discovery
 pnpm dev                  # Start docs + example apps
 pnpm build                # Build all packages
 pnpm check                # Full CI parity (build, typecheck, lint, test)
+pnpm check:release        # Production publish gate (includes live E2E x2)
 pnpm publish:packages:dry-run  # Dry-run npm publish locally
 pnpm stats                # Package LOC + core facade size
 pnpm llms:generate        # Regenerate llms.txt agent index
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 6a8f2f0..7be863c 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -26,6 +26,16 @@ pnpm lint         # ESLint
 pnpm test         # Unit tests (Vitest)
 ```
 
+### Production readiness gate (before publishing)
+
+Use the full release gate locally (it runs the live E2E suite twice):
+
+```bash
+pnpm check:release
+```
+
+This requires a real `LLM_API_KEY` (or `apps/example-nextjs/.env.local`) and will skip npm publish dry-run unless `NODE_AUTH_TOKEN`/`NPM_TOKEN` is present.
+
 ## Development Workflow
 
 1. **Fork** the repository and create a feature branch from `main`.
diff --git a/apps/example-nextjs/app/about/page.tsx b/apps/example-nextjs/app/(main)/about/page.tsx
similarity index 100%
rename from apps/example-nextjs/app/about/page.tsx
rename to apps/example-nextjs/app/(main)/about/page.tsx
diff --git a/apps/example-nextjs/app/(main)/layout.tsx b/apps/example-nextjs/app/(main)/layout.tsx
new file mode 100644
index 0000000..ed4bed0
--- /dev/null
+++ b/apps/example-nextjs/app/(main)/layout.tsx
@@ -0,0 +1,6 @@
+import type { ReactNode } from 'react';
+import { Providers } from '../providers';
+
+export default function MainLayout({ children }: { children: ReactNode }) {
+  return <Providers>{children}</Providers>;
+}
diff --git a/apps/example-nextjs/app/page.tsx b/apps/example-nextjs/app/(main)/page.tsx
similarity index 100%
rename from apps/example-nextjs/app/page.tsx
rename to apps/example-nextjs/app/(main)/page.tsx
diff --git a/apps/example-nextjs/app/demo/layout.tsx b/apps/example-nextjs/app/demo/layout.tsx
new file mode 100644
index 0000000..2c054e7
--- /dev/null
+++ b/apps/example-nextjs/app/demo/layout.tsx
@@ -0,0 +1,48 @@
+'use client';
+
+import dynamic from 'next/dynamic';
+import type { ReactNode } from 'react';
+import {
+  platformDemoPlugin,
+  platformKnowledgeDocuments,
+} from '../../lib/guidekit-platform';
+import { GuideKitDemoActions } from '../guidekit-demo-actions';
+import { GuideKitTestBridge } from '../guidekit-test-bridge';
+
+const GuideKitProvider = dynamic(
+  () => import('@guidekit/react').then((mod) => mod.GuideKitProvider),
+  { ssr: false },
+);
+
+/** Demo layout with cognitive engine enabled for E2E contract tests. */
+export default function DemoLayout({ children }: { children: ReactNode }) {
+  return (
+    <GuideKitProvider
+      tokenEndpoint="/api/guidekit/token"
+      proxy={{
+        llm: '/api/guidekit/llm',
+        health: '/api/guidekit/health',
+        stt: '/api/guidekit/stt',
+        tts: '/api/guidekit/tts',
+      }}
+      llm={{ provider: 'gemini', model: 'gemini-2.5-flash-lite' }}
+      intelligence={true}
+      knowledge={{ documents: platformKnowledgeDocuments, engine: 'bm25', topK: 3 }}
+      plugins={[platformDemoPlugin]}
+      hallucinationGuard
+      cognitive
+      agent={{ name: 'GuideKit Cognitive Demo', greeting: 'Cognitive mode is enabled.' }}
+      options={{
+        debug: process.env.NODE_ENV === 'development',
+        mode: 'text',
+        clickableSelectors: {
+          allow: ['#name', '#email', '#message', 'input', 'textarea'],
+        },
+      }}
+    >
+      <GuideKitDemoActions />
+      <GuideKitTestBridge />
+      {children}
+    </GuideKitProvider>
+  );
+}
diff --git a/apps/example-nextjs/app/demo/page.tsx b/apps/example-nextjs/app/demo/page.tsx
new file mode 100644
index 0000000..db853f9
--- /dev/null
+++ b/apps/example-nextjs/app/demo/page.tsx
@@ -0,0 +1,28 @@
+export default function DemoPage() {
+  return (
+    <div style={{ maxWidth: '800px', margin: '0 auto', padding: '32px 16px' }}>
+      <h1>GuideKit Cognitive Demo</h1>
+      <p>
+        This page runs Platform Mode with <code>cognitive=&#123;true&#125;</code> for E2E contract
+        tests. Voice is text-only here for stability.
+      </p>
+
+      <section data-guidekit-target="overview" id="overview" style={{ marginTop: '32px' }}>
+        <h2>Overview</h2>
+        <p>Ask the assistant about page sections or request guided navigation.</p>
+      </section>
+
+      <section data-guidekit-target="contact" id="contact" style={{ marginTop: '32px' }}>
+        <h2>Contact Form</h2>
+        <form aria-label="Contact form" style={{ display: 'flex', flexDirection: 'column', gap: '12px', maxWidth: '400px' }}>
+          <label htmlFor="name">Name</label>
+          <input id="name" name="name" type="text" placeholder="Your name" />
+          <label htmlFor="email">Email</label>
+          <input id="email" name="email" type="email" placeholder="you@example.com" />
+          <label htmlFor="message">Message</label>
+          <textarea id="message" name="message" rows={3} />
+        </form>
+      </section>
+    </div>
+  );
+}
diff --git a/apps/example-nextjs/app/guidekit-test-bridge.tsx b/apps/example-nextjs/app/guidekit-test-bridge.tsx
new file mode 100644
index 0000000..42fab2f
--- /dev/null
+++ b/apps/example-nextjs/app/guidekit-test-bridge.tsx
@@ -0,0 +1,112 @@
+'use client';
+
+import { useEffect } from 'react';
+import { useGuideKitCore } from '@guidekit/react';
+import type { KnowledgeDocument } from '@guidekit/core';
+
+type BusEvent = { name: string; data: unknown; at: number };
+
+declare global {
+  interface Window {
+    __guidekitTest?: {
+      events: BusEvent[];
+      waitForEvent: (name: string, timeoutMs?: number) => Promise<BusEvent>;
+      waitForReady: (timeoutMs?: number) => Promise<void>;
+      addKnowledgeDocument: (doc: KnowledgeDocument) => void;
+      removeKnowledgeDocument: (documentId: string) => void;
+      clear: () => void;
+    };
+  }
+}
+
+/**
+ * Dev/E2E bridge: records EventBus emissions on window.__guidekitTest.
+ * Only active when NODE_ENV === 'development'.
+ */
+export function GuideKitTestBridge() {
+  const core = useGuideKitCore();
+
+  useEffect(() => {
+    if (process.env.NODE_ENV !== 'development' || !core) return;
+
+    const events: BusEvent[] = [];
+    const waiters = new Map<
+      string,
+      Array<{ resolve: (e: BusEvent) => void; reject: (err: Error) => void; timer: ReturnType<typeof setTimeout> }>
+    >();
+
+    const push = (name: string, data: unknown) => {
+      const entry: BusEvent = { name, data, at: Date.now() };
+      events.push(entry);
+      const pending = waiters.get(name);
+      if (pending?.length) {
+        const next = pending.shift()!;
+        clearTimeout(next.timer);
+        next.resolve(entry);
+        if (!pending.length) waiters.delete(name);
+      }
+    };
+
+    const unsubValidation = core.bus.on('validation:complete', (data) => {
+      push('validation:complete', data);
+    });
+    const unsubLlmEnd = core.bus.on('llm:response-end', (data) => {
+      push('llm:response-end', data);
+    });
+
+    window.__guidekitTest = {
+      events,
+      waitForEvent: (name, timeoutMs = 30_000) =>
+        new Promise<BusEvent>((resolve, reject) => {
+          const existing = events.find((e) => e.name === name);
+          if (existing) {
+            resolve(existing);
+            return;
+          }
+          const timer = setTimeout(() => {
+            const list = waiters.get(name) ?? [];
+            waiters.set(
+              name,
+              list.filter((w) => w.resolve !== resolve),
+            );
+            reject(new Error(`Timed out waiting for bus event: ${name}`));
+          }, timeoutMs);
+          const list = waiters.get(name) ?? [];
+          list.push({ resolve, reject, timer });
+          waiters.set(name, list);
+        }),
+      waitForReady: (timeoutMs = 30_000) =>
+        new Promise<void>((resolve, reject) => {
+          const start = Date.now();
+          const timer = setInterval(() => {
+            if (core.isReady) {
+              clearInterval(timer);
+              resolve();
+              return;
+            }
+            if (Date.now() - start > timeoutMs) {
+              clearInterval(timer);
+              reject(new Error('Timed out waiting for GuideKitCore to become ready.'));
+            }
+          }, 50);
+        }),
+      addKnowledgeDocument: (doc) => {
+        core.addKnowledgeDocument(doc);
+      },
+      removeKnowledgeDocument: (documentId) => {
+        core.removeKnowledgeDocument(documentId);
+      },
+      clear: () => {
+        events.length = 0;
+      },
+    };
+
+    return () => {
+      unsubValidation();
+      unsubLlmEnd();
+      delete window.__guidekitTest;
+    };
+  }, [core]);
+
+  return null;
+}
diff --git a/apps/example-nextjs/app/layout.tsx b/apps/example-nextjs/app/layout.tsx
index b376538..6d1307d 100644
--- a/apps/example-nextjs/app/layout.tsx
+++ b/apps/example-nextjs/app/layout.tsx
@@ -1,17 +1,15 @@
 import type { ReactNode } from 'react';
-import { Providers } from './providers';
 
 export default function RootLayout({ children }: { children: ReactNode }) {
   return (
     <html lang="en">
       <body>
-        <Providers>
-          <nav aria-label="Main navigation" style={{ padding: '16px', borderBottom: '1px solid #e2e8f0' }}>
-            <a href="/" style={{ marginRight: '16px' }}>Home</a>
-            <a href="/about" style={{ marginRight: '16px' }}>About</a>
-          </nav>
-          <main>{children}</main>
-        </Providers>
+        <nav aria-label="Main navigation" style={{ padding: '16px', borderBottom: '1px solid #e2e8f0' }}>
+          <a href="/" style={{ marginRight: '16px' }}>Home</a>
+          <a href="/about" style={{ marginRight: '16px' }}>About</a>
+          <a href="/demo">Demo</a>
+        </nav>
+        <main>{children}</main>
       </body>
     </html>
   );
diff --git a/apps/example-nextjs/app/providers.tsx b/apps/example-nextjs/app/providers.tsx
index d9a8145..a61c538 100644
--- a/apps/example-nextjs/app/providers.tsx
+++ b/apps/example-nextjs/app/providers.tsx
@@ -7,6 +7,7 @@ import {
   platformKnowledgeDocuments,
 } from '../lib/guidekit-platform';
 import { GuideKitDemoActions } from './guidekit-demo-actions';
+import { GuideKitTestBridge } from './guidekit-test-bridge';
 
 const GuideKitProvider = dynamic(
   () => import('@guidekit/react').then((mod) => mod.GuideKitProvider),
@@ -35,9 +36,13 @@ export function Providers({ children }: { children: ReactNode }) {
       options={{
         debug: process.env.NODE_ENV === 'development',
         mode: voiceEnabled ? 'voice' : 'text',
+        clickableSelectors: {
+          allow: ['#name', '#email', '#message', 'input', 'textarea'],
+        },
       }}
     >
       <GuideKitDemoActions />
+      <GuideKitTestBridge />
       {children}
     </GuideKitProvider>
   );
diff --git a/apps/example-nextjs/app/vanilla/guidekit-global/route.ts b/apps/example-nextjs/app/vanilla/guidekit-global/route.ts
new file mode 100644
index 0000000..ff1b90c
--- /dev/null
+++ b/apps/example-nextjs/app/vanilla/guidekit-global/route.ts
@@ -0,0 +1,15 @@
+import { readFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+
+export async function GET(): Promise<Response> {
+  const filePath = resolve(process.cwd(), '../../packages/vanilla/dist/index.global.js');
+  const js = await readFile(filePath, 'utf8');
+  return new Response(js, {
+    status: 200,
+    headers: {
+      'Content-Type': 'application/javascript; charset=utf-8',
+      'Cache-Control': 'no-store',
+    },
+  });
+}
+
diff --git a/apps/example-nextjs/app/vanilla/guidekit.global.js/route.ts b/apps/example-nextjs/app/vanilla/guidekit.global.js/route.ts
new file mode 100644
index 0000000..ff1b90c
--- /dev/null
+++ b/apps/example-nextjs/app/vanilla/guidekit.global.js/route.ts
@@ -0,0 +1,15 @@
+import { readFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+
+export async function GET(): Promise<Response> {
+  const filePath = resolve(process.cwd(), '../../packages/vanilla/dist/index.global.js');
+  const js = await readFile(filePath, 'utf8');
+  return new Response(js, {
+    status: 200,
+    headers: {
+      'Content-Type': 'application/javascript; charset=utf-8',
+      'Cache-Control': 'no-store',
+    },
+  });
+}
+
diff --git a/apps/example-nextjs/public/vanilla-demo.html b/apps/example-nextjs/public/vanilla-demo.html
new file mode 100644
index 0000000..4bc9e2a
--- /dev/null
+++ b/apps/example-nextjs/public/vanilla-demo.html
@@ -0,0 +1,50 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>GuideKit Vanilla Demo</title>
+    <style>
+      body {
+        font-family: system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
+        padding: 24px;
+      }
+      code {
+        background: #f1f5f9;
+        padding: 2px 6px;
+        border-radius: 6px;
+      }
+    </style>
+  </head>
+  <body>
+    <h1>GuideKit Vanilla Demo</h1>
+    <p>This page loads the <code>@guidekit/vanilla</code> IIFE bundle and mounts the widget.</p>
+
+    <script>
+      // Temporary shim: the IIFE bundle currently references `module` (Node-style).
+      // Defining it here keeps the browser bundle executable without polyfills.
+      window.module = window.module || { exports: {} };
+      // tsup sometimes aliases the Node `module` import as `module$1` in the IIFE wrapper.
+      window.module$1 = window.module$1 || window.module;
+    </script>
+    <script src="/vanilla/guidekit-global"></script>
+    <script>
+      if (window.GuideKit && typeof window.GuideKit.init === 'function') {
+        window.GuideKit.init({
+        tokenEndpoint: '/api/guidekit/token',
+        proxy: {
+          llm: '/api/guidekit/llm',
+          health: '/api/guidekit/health',
+          stt: '/api/guidekit/stt',
+          tts: '/api/guidekit/tts',
+        },
+        llm: { provider: 'gemini', model: 'gemini-2.5-flash-lite' },
+        intelligence: false,
+        agent: { name: 'GuideKit Assistant', greeting: 'Hello! How can I help you today?' },
+        options: { debug: true, mode: 'text' },
+        });
+      }
+    </script>
+  </body>
+</html>
+
diff --git a/e2e/accessibility.spec.ts b/e2e/contract/accessibility.spec.ts
similarity index 100%
rename from e2e/accessibility.spec.ts
rename to e2e/contract/accessibility.spec.ts
diff --git a/e2e/contract/agent-click.spec.ts b/e2e/contract/agent-click.spec.ts
new file mode 100644
index 0000000..6cd7620
--- /dev/null
+++ b/e2e/contract/agent-click.spec.ts
@@ -0,0 +1,45 @@
+import { test, expect } from '@playwright/test';
+import {
+  geminiClickElementSse,
+  geminiScrollToSectionSse,
+  geminiTextStopSse,
+  mockLlmToolSequenceRoute,
+  openWidgetInput,
+} from '../fixtures/mock-llm-proxy';
+
+test.describe('Agent clickElement', () => {
+  test.beforeEach(async ({ page }) => {
+    await mockLlmToolSequenceRoute(page, [
+      geminiScrollToSectionSse('contact'),
+      geminiClickElementSse('#name'),
+      geminiTextStopSse('Clicked.'),
+    ]);
+    await page.goto('/');
+    await page.waitForSelector('#guidekit-widget', { timeout: 15_000 });
+  });
+
+  test('clickElement focuses allowed input', async ({ page }) => {
+    await page.waitForSelector('#name');
+    await page.evaluate(() => {
+      (window as any).__gkClickedName = false;
+      const el = document.querySelector('#name');
+      if (el) {
+        el.addEventListener('click', () => {
+          (window as any).__gkClickedName = true;
+        });
+      }
+    });
+
+    const input = await openWidgetInput(page);
+    await input.fill('Click the name field in the contact form.');
+    await page.getByTestId('guidekit-send').click();
+
+    await expect(page.locator('#contact')).toBeVisible({ timeout: 20_000 });
+    const nameInput = page.locator('#name');
+    await expect(nameInput).toBeVisible();
+    await expect
+      .poll(() => page.evaluate(() => Boolean((window as any).__gkClickedName)), { timeout: 15_000 })
+      .toBe(true);
+  });
+});
+
diff --git a/e2e/agent-flows.spec.ts b/e2e/contract/agent-flows.spec.ts
similarity index 99%
rename from e2e/agent-flows.spec.ts
rename to e2e/contract/agent-flows.spec.ts
index 00d1c3f..aedbcbe 100644
--- a/e2e/agent-flows.spec.ts
+++ b/e2e/contract/agent-flows.spec.ts
@@ -4,7 +4,7 @@ import {
   mockLlmHighlightRoute,
   openWidgetInput,
   isElementInViewport,
-} from './fixtures/mock-llm-proxy';
+} from '../fixtures/mock-llm-proxy';
 
 /**
  * Agent flow E2E tests — guided navigation, forms, and proxy health.
diff --git a/e2e/contract/agent-form.spec.ts b/e2e/contract/agent-form.spec.ts
new file mode 100644
index 0000000..9dd70e5
--- /dev/null
+++ b/e2e/contract/agent-form.spec.ts
@@ -0,0 +1,20 @@
+import { test, expect } from '@playwright/test';
+import { mockLlmScrollRoute, openWidgetInput } from '../fixtures/mock-llm-proxy';
+
+test.describe('Agent form interaction', () => {
+  test.beforeEach(async ({ page }) => {
+    await mockLlmScrollRoute(page, 'contact');
+    await page.goto('/');
+    await page.waitForSelector('#guidekit-widget', { timeout: 15_000 });
+  });
+
+  test('scrollToSection exposes contact form fields', async ({ page }) => {
+    const input = await openWidgetInput(page);
+    await input.fill('Take me to the contact form');
+    await page.getByTestId('guidekit-send').click();
+
+    await expect(page.locator('#contact')).toBeVisible({ timeout: 20_000 });
+    await expect(page.locator('#name')).toBeVisible();
+    await expect(page.locator('#email')).toBeVisible();
+  });
+});
diff --git a/e2e/contract/agent-read-page.spec.ts b/e2e/contract/agent-read-page.spec.ts
new file mode 100644
index 0000000..18b6b70
--- /dev/null
+++ b/e2e/contract/agent-read-page.spec.ts
@@ -0,0 +1,27 @@
+import { test, expect } from '@playwright/test';
+import {
+  geminiReadPageContentSse,
+  geminiTextStopSse,
+  mockLlmToolSequenceRoute,
+  openWidgetInput,
+} from '../fixtures/mock-llm-proxy';
+
+test.describe('Agent read page', () => {
+  test.beforeEach(async ({ page }) => {
+    await mockLlmToolSequenceRoute(page, [
+      geminiReadPageContentSse('hero'),
+      geminiTextStopSse('The hero section welcomes users to the test application.'),
+    ]);
+    await page.goto('/');
+    await page.waitForSelector('#guidekit-widget', { timeout: 15_000 });
+  });
+
+  test('readPageContent tool leads to assistant summary', async ({ page }) => {
+    const input = await openWidgetInput(page);
+    await input.fill('What is in the hero section?');
+    await page.getByTestId('guidekit-send').click();
+
+    const assistant = page.locator('.gk-message[data-role="assistant"]').last();
+    await expect(assistant).toContainText(/hero|welcome/i, { timeout: 25_000 });
+  });
+});
diff --git a/e2e/contract/agent-tour.spec.ts b/e2e/contract/agent-tour.spec.ts
new file mode 100644
index 0000000..9dc8cd9
--- /dev/null
+++ b/e2e/contract/agent-tour.spec.ts
@@ -0,0 +1,23 @@
+import { test, expect } from '@playwright/test';
+import {
+  geminiStartTourSse,
+  mockLlmToolRoute,
+  openWidgetInput,
+} from '../fixtures/mock-llm-proxy';
+
+test.describe('Agent tour', () => {
+  test.beforeEach(async ({ page }) => {
+    await mockLlmToolRoute(page, geminiStartTourSse(['hero', 'pricing']));
+    await page.goto('/');
+    await page.waitForSelector('#guidekit-widget', { timeout: 15_000 });
+  });
+
+  test('startTour highlights the first tour section', async ({ page }) => {
+    const input = await openWidgetInput(page);
+    await input.fill('Start a tour of hero and pricing');
+    await page.getByTestId('guidekit-send').click();
+
+    await expect(page.locator('[data-guidekit-spotlight]')).toBeAttached({ timeout: 20_000 });
+    await expect(page.locator('#hero')).toBeVisible();
+  });
+});
diff --git a/e2e/contract/cognitive.spec.ts b/e2e/contract/cognitive.spec.ts
new file mode 100644
index 0000000..5356f8c
--- /dev/null
+++ b/e2e/contract/cognitive.spec.ts
@@ -0,0 +1,20 @@
+import { test, expect } from '@playwright/test';
+import { mockLlmTextRoute } from '../fixtures/voice-mocks';
+import { openWidgetInput } from '../fixtures/mock-llm-proxy';
+
+test.describe('Cognitive engine', () => {
+  test.beforeEach(async ({ page }) => {
+    await mockLlmTextRoute(page, 'Cognitive planning complete. The overview section describes the demo.');
+    await page.goto('/demo');
+    await page.waitForSelector('#guidekit-widget', { timeout: 20_000 });
+  });
+
+  test('cognitive demo page returns assistant reply', async ({ page }) => {
+    const input = await openWidgetInput(page);
+    await input.fill('Summarize the overview section.');
+    await page.getByTestId('guidekit-send').click();
+
+    const assistant = page.locator('.gk-message[data-role="assistant"]').last();
+    await expect(assistant).toContainText(/overview|cognitive|demo/i, { timeout: 25_000 });
+  });
+});
diff --git a/e2e/contract/contract-platform.spec.ts b/e2e/contract/contract-platform.spec.ts
new file mode 100644
index 0000000..2ae1924
--- /dev/null
+++ b/e2e/contract/contract-platform.spec.ts
@@ -0,0 +1,37 @@
+import { test, expect } from '@playwright/test';
+import { mockLlmTextRoute } from '../fixtures/voice-mocks';
+import { openWidgetInput } from '../fixtures/mock-llm-proxy';
+
+/**
+ * Platform Mode pipeline contracts — no live API key (runs in CI).
+ */
+test.describe('Contract Platform Mode', () => {
+  test.beforeEach(async ({ page }) => {
+    await mockLlmTextRoute(page, 'Platform pipeline check.');
+    await page.goto('/');
+    await page.waitForSelector('#guidekit-widget', { timeout: 15_000 });
+  });
+
+  test('platform-demo plugin appends footer to assistant response', async ({ page }) => {
+    const input = await openWidgetInput(page);
+    await input.fill('Run platform check');
+    await page.locator('.gk-send-btn').click();
+
+    const assistant = page.locator('.gk-message[data-role="assistant"]').last();
+    await expect(assistant).toContainText('Platform pipeline check', { timeout: 20_000 });
+    await expect(assistant).toContainText('[Platform Mode]', { timeout: 20_000 });
+  });
+
+  test('widget initializes with platform mode provider options', async ({ page }) => {
+    const health = await page.request.get('/api/guidekit/health');
+    expect(health.ok()).toBeTruthy();
+
+    const fab = page.locator('.gk-fab');
+    await fab.click();
+    const input = page.locator('.gk-input');
+    await expect(input).toBeVisible({ timeout: 10_000 });
+
+    const mic = page.locator('.gk-mic-btn');
+    await expect(mic).toBeVisible();
+  });
+});
diff --git a/e2e/contract/custom-actions.spec.ts b/e2e/contract/custom-actions.spec.ts
new file mode 100644
index 0000000..9d71282
--- /dev/null
+++ b/e2e/contract/custom-actions.spec.ts
@@ -0,0 +1,32 @@
+import { test, expect } from '@playwright/test';
+import {
+  geminiExecuteCustomActionSse,
+  mockLlmToolRoute,
+  openWidgetInput,
+} from '../fixtures/mock-llm-proxy';
+
+test.describe('Custom actions', () => {
+  test.beforeEach(async ({ page }) => {
+    await mockLlmToolRoute(
+      page,
+      geminiExecuteCustomActionSse('showAlert', { message: 'E2E custom action' }),
+    );
+    await page.goto('/');
+    await page.waitForSelector('#guidekit-widget', { timeout: 15_000 });
+  });
+
+  test('executeCustomAction showAlert opens a dialog', async ({ page }) => {
+    page.on('dialog', async (dialog) => {
+      expect(dialog.message()).toContain('E2E custom action');
+      await dialog.accept();
+    });
+
+    const input = await openWidgetInput(page);
+    await input.fill('Show alert');
+    await page.getByTestId('guidekit-send').click();
+
+    await expect(page.locator('.gk-message[data-role="assistant"]').last()).not.toHaveText('', {
+      timeout: 20_000,
+    });
+  });
+});
diff --git a/e2e/contract/hallucination-guard.spec.ts b/e2e/contract/hallucination-guard.spec.ts
new file mode 100644
index 0000000..1b3582e
--- /dev/null
+++ b/e2e/contract/hallucination-guard.spec.ts
@@ -0,0 +1,26 @@
+import { test, expect } from '@playwright/test';
+import { mockLlmTextRoute } from '../fixtures/voice-mocks';
+import { openWidgetInput } from '../fixtures/mock-llm-proxy';
+
+test.describe('Hallucination guard', () => {
+  test.beforeEach(async ({ page }) => {
+    await mockLlmTextRoute(page, 'The hero section welcomes you to GuideKit.');
+    await page.goto('/');
+    await page.waitForSelector('#guidekit-widget', { timeout: 15_000 });
+    await page.waitForFunction(() => window.__guidekitTest != null, undefined, { timeout: 20_000 });
+  });
+
+  test('validation:complete bus event fires after response', async ({ page }) => {
+    const waitForValidation = page.evaluate(() =>
+      window.__guidekitTest!.waitForEvent('validation:complete', 45_000),
+    );
+
+    const input = await openWidgetInput(page);
+    await input.fill('Describe the hero section.');
+    await page.getByTestId('guidekit-send').click();
+
+    const event = await waitForValidation;
+    expect(event.name).toBe('validation:complete');
+    expect(event.data).toBeTruthy();
+  });
+});
diff --git a/e2e/contract/highlight-dismiss.spec.ts b/e2e/contract/highlight-dismiss.spec.ts
new file mode 100644
index 0000000..7e42412
--- /dev/null
+++ b/e2e/contract/highlight-dismiss.spec.ts
@@ -0,0 +1,33 @@
+import { test, expect } from '@playwright/test';
+import {
+  geminiDismissHighlightSse,
+  geminiHighlightToolSse,
+  mockLlmToolSequenceRoute,
+  openWidgetInput,
+} from '../fixtures/mock-llm-proxy';
+
+test.describe('Highlight dismiss', () => {
+  test.beforeEach(async ({ page }) => {
+    await mockLlmToolSequenceRoute(page, [
+      geminiHighlightToolSse('hero'),
+      geminiDismissHighlightSse(),
+    ]);
+    await page.goto('/');
+    await page.waitForSelector('#guidekit-widget', { timeout: 15_000 });
+  });
+
+  test('dismissHighlight hides spotlight overlay', async ({ page }) => {
+    const input = await openWidgetInput(page);
+    await input.fill('Highlight hero then dismiss');
+    await page.getByTestId('guidekit-send').click();
+
+    const spotlight = page.locator('[data-guidekit-spotlight]');
+    await expect(spotlight).toBeAttached({ timeout: 25_000 });
+
+    await page.waitForFunction(() => {
+      const el = document.querySelector('[data-guidekit-spotlight]');
+      if (!el) return true;
+      return el instanceof HTMLElement && el.style.opacity === '0';
+    }, undefined, { timeout: 35_000 });
+  });
+});
diff --git a/e2e/contract/knowledge-retrieval.spec.ts b/e2e/contract/knowledge-retrieval.spec.ts
new file mode 100644
index 0000000..5c15a3d
--- /dev/null
+++ b/e2e/contract/knowledge-retrieval.spec.ts
@@ -0,0 +1,23 @@
+import { test, expect } from '@playwright/test';
+import { mockLlmTextRoute } from '../fixtures/voice-mocks';
+import { openWidgetInput } from '../fixtures/mock-llm-proxy';
+
+test.describe('Knowledge retrieval', () => {
+  test.beforeEach(async ({ page }) => {
+    await mockLlmTextRoute(
+      page,
+      'API keys are stored server-side only. The client uses a short-lived JWT and the LLM proxy.',
+    );
+    await page.goto('/');
+    await page.waitForSelector('#guidekit-widget', { timeout: 15_000 });
+  });
+
+  test('assistant answer reflects knowledge base security content', async ({ page }) => {
+    const input = await openWidgetInput(page);
+    await input.fill('According to the knowledge base, where are API keys stored in production?');
+    await page.getByTestId('guidekit-send').click();
+
+    const assistant = page.locator('.gk-message[data-role="assistant"]').last();
+    await expect(assistant).toContainText(/server-side|proxy|jwt/i, { timeout: 20_000 });
+  });
+});
diff --git a/e2e/contract/knowledge-runtime.spec.ts b/e2e/contract/knowledge-runtime.spec.ts
new file mode 100644
index 0000000..5032050
--- /dev/null
+++ b/e2e/contract/knowledge-runtime.spec.ts
@@ -0,0 +1,94 @@
+import { test, expect } from '@playwright/test';
+import { geminiTextStopSse, openWidgetInput } from '../fixtures/mock-llm-proxy';
+
+declare global {
+  interface Window {
+    __guidekitTest?: {
+      waitForReady: (timeoutMs?: number) => Promise<void>;
+      addKnowledgeDocument: (doc: { id: string; title: string; content: string }) => void;
+      removeKnowledgeDocument: (documentId: string) => void;
+    };
+  }
+}
+
+test.describe('Runtime knowledge API', () => {
+  test.beforeEach(async ({ page }) => {
+    await page.goto('/');
+    await page.waitForSelector('#guidekit-widget', { timeout: 15_000 });
+  });
+
+  test('addKnowledgeDocument influences LLM systemPrompt; removeKnowledgeDocument removes it', async ({
+    page,
+  }) => {
+    const docId = 'runtime-doc-1';
+    const docTitle = 'RuntimeKnowledgeDocTitle_123';
+    const uniquePhrase = 'RUNTIME_KNOWLEDGE_PHRASE_XYZZY_123';
+
+    await page.waitForFunction(() => Boolean(window.__guidekitTest), undefined, { timeout: 15_000 });
+    await page.evaluate(() => window.__guidekitTest!.waitForReady(30_000));
+    await page.evaluate(
+      ({ docId, docTitle, uniquePhrase }) => {
+        window.__guidekitTest!.addKnowledgeDocument({
+          id: docId,
+          title: docTitle,
+          content: `This doc contains a unique phrase: ${uniquePhrase}`,
+        });
+      },
+      { docId, docTitle, uniquePhrase },
+    );
+
+    let seenSystemPrompt = '';
+    await page.route('**/api/guidekit/llm', async (route) => {
+      if (route.request().method() !== 'POST') {
+        await route.continue();
+        return;
+      }
+      const body = route.request().postDataJSON() as { systemPrompt?: string };
+      seenSystemPrompt = body.systemPrompt ?? '';
+      await route.fulfill({
+        status: 200,
+        headers: {
+          'Content-Type': 'text/event-stream',
+          'Cache-Control': 'no-cache',
+        },
+        body: geminiTextStopSse('OK'),
+      });
+    });
+
+    const input = await openWidgetInput(page);
+    await input.fill(`What do you know about ${uniquePhrase}? Reply in one sentence.`);
+    await page.getByTestId('guidekit-send').click();
+
+    await expect.poll(() => seenSystemPrompt, { timeout: 15_000 }).toContain(docTitle);
+
+    await page.unroute('**/api/guidekit/llm');
+
+    await page.evaluate((docId) => window.__guidekitTest!.removeKnowledgeDocument(docId), docId);
+
+    let seenSystemPromptAfterRemove = '';
+    await page.route('**/api/guidekit/llm', async (route) => {
+      if (route.request().method() !== 'POST') {
+        await route.continue();
+        return;
+      }
+      const body = route.request().postDataJSON() as { systemPrompt?: string };
+      seenSystemPromptAfterRemove = body.systemPrompt ?? '';
+      await route.fulfill({
+        status: 200,
+        headers: {
+          'Content-Type': 'text/event-stream',
+          'Cache-Control': 'no-cache',
+        },
+        body: geminiTextStopSse('OK'),
+      });
+    });
+
+    await input.fill(`What do you know about ${uniquePhrase}? Reply in one sentence.`);
+    await page.getByTestId('guidekit-send').click();
+
+    await expect
+      .poll(() => seenSystemPromptAfterRemove, { timeout: 15_000 })
+      .not.toContain(docTitle);
+  });
+});
+
diff --git a/e2e/navigation.spec.ts b/e2e/contract/navigation.spec.ts
similarity index 100%
rename from e2e/navigation.spec.ts
rename to e2e/contract/navigation.spec.ts
diff --git a/e2e/contract/proxy-voice-keys.spec.ts b/e2e/contract/proxy-voice-keys.spec.ts
new file mode 100644
index 0000000..aaaaeff
--- /dev/null
+++ b/e2e/contract/proxy-voice-keys.spec.ts
@@ -0,0 +1,39 @@
+import { test, expect } from '@playwright/test';
+
+test.describe('Proxy voice key minting', () => {
+  test('POST /api/guidekit/stt returns ephemeral key when session has STT_API_KEY', async ({
+    request,
+  }) => {
+    const tokenRes = await request.post('/api/guidekit/token');
+    expect(tokenRes.ok()).toBeTruthy();
+    const { token } = (await tokenRes.json()) as { token: string };
+
+    const sttRes = await request.post('/api/guidekit/stt', {
+      headers: { Authorization: `Bearer ${token}` },
+    });
+    expect(sttRes.ok()).toBeTruthy();
+    const body = (await sttRes.json()) as { kind: string; apiKey: string };
+    expect(body.kind).toBe('stt');
+    expect(body.apiKey.length).toBeGreaterThan(5);
+  });
+
+  test('POST /api/guidekit/tts returns ephemeral key when session has TTS_API_KEY', async ({
+    request,
+  }) => {
+    const tokenRes = await request.post('/api/guidekit/token');
+    const { token } = (await tokenRes.json()) as { token: string };
+
+    const ttsRes = await request.post('/api/guidekit/tts', {
+      headers: { Authorization: `Bearer ${token}` },
+    });
+    expect(ttsRes.ok()).toBeTruthy();
+    const body = (await ttsRes.json()) as { kind: string; apiKey: string };
+    expect(body.kind).toBe('tts');
+    expect(body.apiKey.length).toBeGreaterThan(5);
+  });
+
+  test('STT and TTS routes reject GET', async ({ request }) => {
+    expect((await request.get('/api/guidekit/stt')).status()).toBe(405);
+    expect((await request.get('/api/guidekit/tts')).status()).toBe(405);
+  });
+});
diff --git a/e2e/contract/session-recovery.spec.ts b/e2e/contract/session-recovery.spec.ts
new file mode 100644
index 0000000..9857e71
--- /dev/null
+++ b/e2e/contract/session-recovery.spec.ts
@@ -0,0 +1,49 @@
+import { test, expect } from '@playwright/test';
+import { geminiTextSse } from '../fixtures/voice-mocks';
+
+/** Contract session recovery when live LLM is unavailable (CI). */
+test.describe('Contract session recovery', () => {
+  test('widget retries LLM after mocked stale session 401', async ({ page }) => {
+    let llmCalls = 0;
+    await page.route('**/api/guidekit/llm', async (route) => {
+      if (route.request().method() !== 'POST') {
+        await route.continue();
+        return;
+      }
+      llmCalls += 1;
+      if (llmCalls === 1) {
+        await route.fulfill({
+          status: 401,
+          contentType: 'application/json',
+          body: JSON.stringify({
+            error: 'Session expired or server restarted — request a new token',
+          }),
+        });
+        return;
+      }
+      await route.fulfill({
+        status: 200,
+        headers: {
+          'Content-Type': 'text/event-stream',
+          'Cache-Control': 'no-cache',
+        },
+        body: geminiTextSse('Session recovered successfully.'),
+      });
+    });
+
+    await page.goto('/');
+    await page.waitForSelector('#guidekit-widget', { timeout: 15_000 });
+    const fab = page.locator('.gk-fab');
+    await fab.click();
+    const input = page.locator('.gk-input');
+    await input.waitFor({ state: 'visible' });
+    await input.fill('Hello after recovery');
+    await page.locator('.gk-send-btn').click();
+
+    await expect(page.locator('.gk-message[data-role="assistant"]').last()).toContainText(
+      'Session recovered',
+      { timeout: 20_000 },
+    );
+    expect(llmCalls).toBe(2);
+  });
+});
diff --git a/e2e/contract/vanilla-widget.spec.ts b/e2e/contract/vanilla-widget.spec.ts
new file mode 100644
index 0000000..a3eaed1
--- /dev/null
+++ b/e2e/contract/vanilla-widget.spec.ts
@@ -0,0 +1,61 @@
+import { test, expect } from '@playwright/test';
+import { mockLlmScrollRoute } from '../fixtures/mock-llm-proxy';
+
+test.describe('@guidekit/vanilla IIFE', () => {
+  test.beforeEach(async ({ page }) => {
+    await page.addInitScript(() => {
+      (window as any).module = (window as any).module ?? { exports: {} };
+      (window as any).module$1 = (window as any).module$1 ?? (window as any).module;
+    });
+    await mockLlmScrollRoute(page, 'features');
+  });
+
+  test('vanilla bundle mounts widget and opens panel', async ({ page }) => {
+    const errors: string[] = [];
+    page.on('pageerror', (err) => errors.push(String(err)));
+    page.on('console', (msg) => {
+      if (msg.type() === 'error') errors.push(msg.text());
+    });
+
+    const resp = await page.goto('/vanilla-demo.html');
+    expect(resp?.ok(), `vanilla-demo.html failed: ${resp?.status()}`).toBe(true);
+
+    const bundleRes = await page.request.get('/vanilla/guidekit-global');
+    expect(bundleRes.ok(), `vanilla bundle failed: ${bundleRes.status()}`).toBe(true);
+
+    // Ensure the bundle is loaded even if the HTML page changes.
+    await page.addScriptTag({ url: '/vanilla/guidekit-global' });
+    await page.waitForTimeout(1000);
+    expect(errors, `console/page errors:\n${errors.join('\n')}`).toEqual([]);
+    const hasGlobal = await page.evaluate(() => Boolean((window as any).GuideKit));
+    expect(hasGlobal, 'GuideKit global not found after loading IIFE bundle').toBe(true);
+
+    // Ensure init ran (the page has its own init script, but this makes the test resilient).
+    await page.evaluate(() => {
+      if (!document.querySelector('#guidekit-widget')) {
+        (window as any).GuideKit.init({
+          tokenEndpoint: '/api/guidekit/token',
+          proxy: {
+            llm: '/api/guidekit/llm',
+            health: '/api/guidekit/health',
+            stt: '/api/guidekit/stt',
+            tts: '/api/guidekit/tts',
+          },
+          llm: { provider: 'gemini', model: 'gemini-2.5-flash-lite' },
+          intelligence: false,
+          agent: { name: 'GuideKit Assistant', greeting: 'Hello!' },
+          options: { debug: true, mode: 'text' },
+        });
+      }
+    });
+
+    // Vanilla widget uses the same host id + CSS classes.
+    await page.waitForSelector('#guidekit-widget', { timeout: 20_000 });
+    const fab = page.locator('.gk-fab');
+    await expect(fab).toBeVisible();
+
+    await fab.click();
+    await expect(page.locator('.gk-panel.gk-open')).toBeVisible({ timeout: 10_000 });
+  });
+});
+
diff --git a/e2e/voice.spec.ts b/e2e/contract/voice.spec.ts
similarity index 81%
rename from e2e/voice.spec.ts
rename to e2e/contract/voice.spec.ts
index 5ec7b37..17ebd65 100644
--- a/e2e/voice.spec.ts
+++ b/e2e/contract/voice.spec.ts
@@ -1,16 +1,14 @@
 import { test, expect } from '@playwright/test';
-import { openWidgetInput } from './fixtures/mock-llm-proxy';
-import {
-  installVoiceBrowserMocks,
-  mockLlmTextRoute,
-} from './fixtures/voice-mocks';
+import { openWidgetInput } from '../fixtures/mock-llm-proxy';
+import { mockLlmTextRoute } from '../fixtures/voice-mocks';
+import { setupVoiceE2e } from '../fixtures/voice-e2e';
 
+/** Voice E2E — Web Speech mocks only (see fixtures/voice-e2e.ts). */
 test.describe('Voice smoke', () => {
   test.describe.configure({ timeout: 90_000 });
 
   test.beforeEach(async ({ page, context }) => {
-    await context.grantPermissions(['microphone']);
-    await installVoiceBrowserMocks(page, 'scroll to pricing');
+    await setupVoiceE2e(page, context, 'scroll to pricing');
     await mockLlmTextRoute(page, 'Opening the pricing section for you.');
     await page.goto('/');
     await page.waitForSelector('#guidekit-widget', { timeout: 15_000 });
diff --git a/e2e/widget.spec.ts b/e2e/contract/widget.spec.ts
similarity index 100%
rename from e2e/widget.spec.ts
rename to e2e/contract/widget.spec.ts
diff --git a/e2e/env.ts b/e2e/env.ts
new file mode 100644
index 0000000..4fda286
--- /dev/null
+++ b/e2e/env.ts
@@ -0,0 +1,49 @@
+import { existsSync, readFileSync } from 'fs';
+import { resolve } from 'path';
+
+export const DUMMY_LLM_KEY = 'e2e-dummy-llm-key-for-contract-tests';
+export const DEFAULT_E2E_SECRET = 'guidekit-example-e2e-secret-32-chars';
+
+/** Load apps/example-nextjs/.env.local for local live runs (gitignored). */
+export function loadExampleEnvLocal(): Record<string, string> {
+  const envPath = resolve(__dirname, '../apps/example-nextjs/.env.local');
+  if (!existsSync(envPath)) return {};
+  const vars: Record<string, string> = {};
+  for (const line of readFileSync(envPath, 'utf8').split('\n')) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith('#')) continue;
+    const eq = trimmed.indexOf('=');
+    if (eq === -1) continue;
+    vars[trimmed.slice(0, eq)] = trimmed.slice(eq + 1);
+  }
+  return vars;
+}
+
+export function resolveGuidekitSecret(): string {
+  const exampleEnv = loadExampleEnvLocal();
+  return process.env.GUIDEKIT_SECRET ?? exampleEnv.GUIDEKIT_SECRET ?? DEFAULT_E2E_SECRET;
+}
+
+export function resolveLlmApiKey(): string {
+  const exampleEnv = loadExampleEnvLocal();
+  return process.env.LLM_API_KEY ?? exampleEnv.LLM_API_KEY ?? DUMMY_LLM_KEY;
+}
+
+export function hasRealLlmApiKey(): boolean {
+  const key = resolveLlmApiKey();
+  return key.length > 10 && key !== DUMMY_LLM_KEY && !key.startsWith('e2e-dummy');
+}
+
+export function isLiveLlmEnabled(): boolean {
+  return process.env.LIVE_LLM === '1' && hasRealLlmApiKey();
+}
+
+export function liveSkipReason(): string {
+  if (process.env.LIVE_LLM !== '1') {
+    return 'Set LIVE_LLM=1 to run live integration tests (pnpm test:e2e:live)';
+  }
+  if (!hasRealLlmApiKey()) {
+    return 'Set LLM_API_KEY in env or apps/example-nextjs/.env.local';
+  }
+  return 'Live LLM tests disabled';
+}
diff --git a/e2e/fixtures/live-helpers.ts b/e2e/fixtures/live-helpers.ts
new file mode 100644
index 0000000..9c686f0
--- /dev/null
+++ b/e2e/fixtures/live-helpers.ts
@@ -0,0 +1,85 @@
+import { expect, type APIRequestContext, type Page } from '@playwright/test';
+import { isElementInViewport } from './mock-llm-proxy';
+
+export async function gotoHomeWithWidget(page: Page): Promise<void> {
+  await page.goto('/');
+  await page.waitForSelector('#guidekit-widget', { timeout: 20_000 });
+}
+
+export async function sendChatMessage(page: Page, text: string): Promise<void> {
+  await page.waitForSelector('#guidekit-widget', { timeout: 20_000 });
+  const panel = page.locator('.gk-panel[data-open="true"]');
+  if (!(await panel.isVisible())) {
+    const fab = page.locator('.gk-fab');
+    await fab.waitFor({ state: 'visible', timeout: 10_000 });
+    await fab.click();
+  }
+
+  const input = page.locator('.gk-input');
+  await input.waitFor({ state: 'visible', timeout: 10_000 });
+  await expect(input).toBeEnabled({ timeout: 60_000 });
+  await input.fill(text);
+  await input.press('Enter');
+}
+
+export async function waitForAssistantReply(
+  page: Page,
+  options: { timeout?: number; minLength?: number } = {},
+): Promise<string> {
+  const timeout = options.timeout ?? 45_000;
+  const minLength = options.minLength ?? 5;
+  const assistant = page.locator('.gk-message[data-role="assistant"]').last();
+  await expect(assistant).not.toHaveText('', { timeout });
+  const text = (await assistant.textContent())?.trim() ?? '';
+  expect(text.length).toBeGreaterThanOrEqual(minLength);
+  expect(text.toLowerCase()).not.toContain('error:');
+  return text;
+}
+
+export async function waitForLlmResponse(page: Page, timeout = 60_000): Promise<void> {
+  await page.waitForResponse(
+    (res) =>
+      res.url().includes('/api/guidekit/llm') &&
+      res.request().method() === 'POST' &&
+      res.status() === 200,
+    { timeout },
+  );
+}
+
+export async function waitForSectionInViewport(
+  page: Page,
+  selector: string,
+  timeout = 20_000,
+): Promise<void> {
+  const viewport = page.viewportSize();
+  const viewportHeight = viewport?.height ?? 800;
+  await page.waitForFunction(
+    ([sel, vh]) => {
+      const el = document.querySelector(sel);
+      if (!el || !vh) return false;
+      const rect = el.getBoundingClientRect();
+      return rect.top >= 0 && rect.bottom <= vh;
+    },
+    [selector, viewportHeight] as const,
+    { timeout },
+  );
+  const box = await page.locator(selector).boundingBox();
+  expect(isElementInViewport(box, viewportHeight)).toBe(true);
+}
+
+export async function waitForSpotlight(page: Page, timeout = 25_000): Promise<void> {
+  const spotlight = page.locator('[data-guidekit-spotlight]');
+  await expect(spotlight).toBeAttached({ timeout });
+  await page.waitForFunction(() => {
+    const el = document.querySelector('[data-guidekit-spotlight]');
+    return el instanceof HTMLElement && el.style.opacity === '1';
+  }, undefined, { timeout });
+}
+
+export async function fetchSessionToken(request: APIRequestContext): Promise<string> {
+  const tokenRes = await request.post('/api/guidekit/token');
+  expect(tokenRes.ok()).toBeTruthy();
+  const { token } = (await tokenRes.json()) as { token: string };
+  expect(token.length).toBeGreaterThan(20);
+  return token;
+}
diff --git a/e2e/fixtures/mock-llm-proxy.ts b/e2e/fixtures/mock-llm-proxy.ts
index 34f8e84..18364ff 100644
--- a/e2e/fixtures/mock-llm-proxy.ts
+++ b/e2e/fixtures/mock-llm-proxy.ts
@@ -35,7 +35,50 @@ export function geminiScrollToSectionSse(sectionId: string): string {
   return geminiToolCallSse('scrollToSection', { sectionId });
 }
 
-/** Mock /api/guidekit/llm; first POST returns tool SSE, later POSTs return text-only STOP. */
+export function geminiTextStopSse(text = 'Done.'): string {
+  return `data: {"candidates":[{"content":{"parts":[{"text":${JSON.stringify(text)}}]},"finishReason":"STOP"}]}\n\ndata: [DONE]\n\n`;
+}
+
+export function geminiStartTourSse(sectionIds: string[]): string {
+  return geminiToolCallSse('startTour', { sectionIds, mode: 'manual' });
+}
+
+export function geminiClickElementSse(selector: string): string {
+  return geminiToolCallSse('clickElement', { selector });
+}
+
+export function geminiExecuteCustomActionSse(actionId: string, params: Record<string, unknown>): string {
+  return geminiToolCallSse('executeCustomAction', { actionId, params });
+}
+
+export function geminiDismissHighlightSse(): string {
+  return geminiToolCallSse('dismissHighlight', {});
+}
+
+export function geminiReadPageContentSse(sectionId: string): string {
+  return geminiToolCallSse('readPageContent', { sectionId });
+}
+
+/** Mock /api/guidekit/llm; each POST returns the next tool SSE, then text STOP. */
+export async function mockLlmToolSequenceRoute(page: Page, rounds: string[]): Promise<void> {
+  let calls = 0;
+  await page.route('**/api/guidekit/llm', async (route) => {
+    if (route.request().method() !== 'POST') {
+      await route.continue();
+      return;
+    }
+    calls += 1;
+    const body = calls <= rounds.length ? rounds[calls - 1]! : geminiTextStopSse();
+    await route.fulfill({
+      status: 200,
+      headers: {
+        'Content-Type': 'text/event-stream',
+        'Cache-Control': 'no-cache',
+      },
+      body,
+    });
+  });
+}
 export async function mockLlmToolRoute(
   page: Page,
   firstRoundBody: string,
diff --git a/e2e/fixtures/voice-e2e.ts b/e2e/fixtures/voice-e2e.ts
new file mode 100644
index 0000000..438cb03
--- /dev/null
+++ b/e2e/fixtures/voice-e2e.ts
@@ -0,0 +1,19 @@
+import type { BrowserContext, Page } from '@playwright/test';
+import { installVoiceBrowserMocks } from './voice-mocks';
+
+/**
+ * E2E voice policy: always use mocked Web Speech API (STT + mic).
+ *
+ * We do not run Playwright against Deepgram, ElevenLabs, or server STT/TTS
+ * proxies — those need paid keys, real audio, and are flaky in CI. Contract
+ * and live voice specs exercise the same browser path the example app uses by
+ * default (web-speech provider + @guidekit/vad).
+ */
+export async function setupVoiceE2e(
+  page: Page,
+  context: BrowserContext,
+  transcript = 'hello from voice',
+): Promise<void> {
+  await context.grantPermissions(['microphone']);
+  await installVoiceBrowserMocks(page, transcript);
+}
diff --git a/e2e/fixtures/voice-mocks.ts b/e2e/fixtures/voice-mocks.ts
index bc84353..0c196a7 100644
--- a/e2e/fixtures/voice-mocks.ts
+++ b/e2e/fixtures/voice-mocks.ts
@@ -33,6 +33,7 @@ export async function mockLlmTextRoute(page: Page, text: string): Promise<void>
 
 /**
  * Browser mocks for Web Speech STT and microphone access.
+ * Used by all voice E2E specs — do not swap for Deepgram/ElevenLabs here.
  * VAD still loads from @guidekit/vad; allow ~15s on first mic click in CI.
  */
 export async function installVoiceBrowserMocks(
diff --git a/e2e/live-llm.spec.ts b/e2e/live-llm.spec.ts
deleted file mode 100644
index 9d6de2a..0000000
--- a/e2e/live-llm.spec.ts
+++ /dev/null
@@ -1,36 +0,0 @@
-import { test, expect } from '@playwright/test';
-import { openWidgetInput } from './fixtures/mock-llm-proxy';
-
-/**
- * Live integration — real Gemini via server proxy (skipped in CI).
- * Run: LIVE_LLM=1 pnpm exec playwright test e2e/live-llm.spec.ts
- */
-test.describe('Live LLM integration', () => {
-  test.skip(!process.env.LIVE_LLM, 'Set LIVE_LLM=1 to run against a real API key');
-  test.setTimeout(90_000);
-
-  test.beforeEach(async ({ page }) => {
-    await page.goto('/');
-    await page.waitForSelector('#guidekit-widget', { timeout: 20_000 });
-  });
-
-  test('proxy token + health + real assistant reply', async ({ page, request }) => {
-    const health = await request.get('/api/guidekit/health');
-    expect(health.ok()).toBeTruthy();
-
-    const tokenRes = await request.post('/api/guidekit/token');
-    expect(tokenRes.ok()).toBeTruthy();
-    const { token } = (await tokenRes.json()) as { token: string };
-    expect(token.length).toBeGreaterThan(20);
-
-    const input = await openWidgetInput(page);
-    await input.fill('In one short sentence, what is on this page?');
-    await page.locator('.gk-send-btn').click();
-
-    const assistant = page.locator('.gk-message[data-role="assistant"]').last();
-    await expect(assistant).not.toHaveText('', { timeout: 45_000 });
-    const text = (await assistant.textContent())?.trim() ?? '';
-    expect(text.length).toBeGreaterThan(10);
-    expect(text.toLowerCase()).not.toContain('error:');
-  });
-});
diff --git a/e2e/live/agent-tools.spec.ts b/e2e/live/agent-tools.spec.ts
new file mode 100644
index 0000000..7ff5805
--- /dev/null
+++ b/e2e/live/agent-tools.spec.ts
@@ -0,0 +1,52 @@
+import { test, expect } from '@playwright/test';
+import { isLiveLlmEnabled, liveSkipReason } from '../env';
+import {
+  gotoHomeWithWidget,
+  sendChatMessage,
+  waitForAssistantReply,
+  waitForSectionInViewport,
+  waitForSpotlight,
+} from '../fixtures/live-helpers';
+
+/**
+ * Live agent tool execution — real LLM must invoke scrollToSection / highlight.
+ * Run: pnpm test:e2e:live
+ */
+test.describe('Live agent tools', () => {
+  test.skip(!isLiveLlmEnabled(), liveSkipReason());
+  test.describe.configure({ timeout: 120_000, retries: 2 });
+
+  test.beforeEach(async ({ page }) => {
+    await gotoHomeWithWidget(page);
+  });
+
+  test('scrollToSection scrolls pricing into view', async ({ page }) => {
+    await sendChatMessage(
+      page,
+      'Use the scrollToSection tool with sectionId "pricing". Do not reply with text — only call the tool.',
+    );
+    await waitForSectionInViewport(page, '#pricing');
+    await waitForAssistantReply(page, { timeout: 60_000, minLength: 1 }).catch(() => {
+      // Tool-only rounds may produce a short follow-up after scrolling.
+    });
+  });
+
+  test('highlight shows spotlight on hero section', async ({ page }) => {
+    await sendChatMessage(
+      page,
+      'Use the highlight tool with sectionId "hero" and tooltip "Hero section". Only use the tool.',
+    );
+    await waitForSpotlight(page);
+  });
+
+  test('navigate tool opens about page', async ({ page }) => {
+    await sendChatMessage(
+      page,
+      'Use the navigate tool to go to /about. Only call the tool, do not describe the page.',
+    );
+    await page.waitForURL('**/about', { timeout: 60_000 });
+    await page.waitForSelector('h1', { timeout: 15_000 });
+    const heading = await page.locator('h1').textContent();
+    expect(heading?.toLowerCase()).toContain('about');
+  });
+});
diff --git a/e2e/live/custom-actions.spec.ts b/e2e/live/custom-actions.spec.ts
new file mode 100644
index 0000000..29bd21e
--- /dev/null
+++ b/e2e/live/custom-actions.spec.ts
@@ -0,0 +1,28 @@
+import { test, expect } from '@playwright/test';
+import { isLiveLlmEnabled, liveSkipReason } from '../env';
+import { gotoHomeWithWidget, sendChatMessage, waitForAssistantReply } from '../fixtures/live-helpers';
+
+test.describe('Live custom actions', () => {
+  test.skip(!isLiveLlmEnabled(), liveSkipReason());
+  test.describe.configure({ timeout: 120_000, retries: 2 });
+
+  test.beforeEach(async ({ page }) => {
+    await gotoHomeWithWidget(page);
+  });
+
+  test('real LLM invokes showAlert custom action', async ({ page }) => {
+    let dialogSeen = false;
+    page.on('dialog', async (dialog) => {
+      dialogSeen = true;
+      await dialog.accept();
+    });
+
+    await sendChatMessage(
+      page,
+      'Use the executeCustomAction tool with actionId "showAlert" and params message "Live E2E alert". Only call the tool.',
+    );
+
+    await waitForAssistantReply(page, { timeout: 75_000, minLength: 1 });
+    expect(dialogSeen).toBeTruthy();
+  });
+});
diff --git a/e2e/live/form.spec.ts b/e2e/live/form.spec.ts
new file mode 100644
index 0000000..cf50529
--- /dev/null
+++ b/e2e/live/form.spec.ts
@@ -0,0 +1,28 @@
+import { test, expect } from '@playwright/test';
+import { isLiveLlmEnabled, liveSkipReason } from '../env';
+import {
+  gotoHomeWithWidget,
+  sendChatMessage,
+  waitForAssistantReply,
+  waitForSectionInViewport,
+} from '../fixtures/live-helpers';
+
+test.describe('Live form guidance', () => {
+  test.skip(!isLiveLlmEnabled(), liveSkipReason());
+  test.describe.configure({ timeout: 120_000, retries: 2 });
+
+  test.beforeEach(async ({ page }) => {
+    await gotoHomeWithWidget(page);
+  });
+
+  test('real LLM scrolls to contact and mentions the form', async ({ page }) => {
+    await sendChatMessage(
+      page,
+      'Use scrollToSection with sectionId "contact" to show the contact form. Then briefly mention the name field.',
+    );
+
+    await waitForSectionInViewport(page, '#contact', 60_000);
+    const reply = await waitForAssistantReply(page, { timeout: 75_000, minLength: 5 });
+    expect(reply.toLowerCase()).toMatch(/contact|name|form/);
+  });
+});
diff --git a/e2e/live/llm.spec.ts b/e2e/live/llm.spec.ts
new file mode 100644
index 0000000..916c61d
--- /dev/null
+++ b/e2e/live/llm.spec.ts
@@ -0,0 +1,69 @@
+import { test, expect } from '@playwright/test';
+import { isLiveLlmEnabled, liveSkipReason } from '../env';
+import {
+  fetchSessionToken,
+  gotoHomeWithWidget,
+  sendChatMessage,
+  waitForAssistantReply,
+  waitForLlmResponse,
+} from '../fixtures/live-helpers';
+
+/**
+ * Live integration — real Gemini via server proxy (skipped in CI / without API key).
+ * Run: pnpm test:e2e:live
+ */
+test.describe('Live LLM integration', () => {
+  test.skip(!isLiveLlmEnabled(), liveSkipReason());
+  test.describe.configure({ timeout: 90_000, retries: 1 });
+
+  test.beforeEach(async ({ page }) => {
+    await gotoHomeWithWidget(page);
+  });
+
+  test('proxy health + token + real assistant reply', async ({ page, request }) => {
+    const health = await request.get('/api/guidekit/health');
+    expect(health.ok()).toBeTruthy();
+    await fetchSessionToken(request);
+
+    await sendChatMessage(page, 'In one short sentence, what is on this page?');
+    const text = await waitForAssistantReply(page);
+    expect(text.length).toBeGreaterThan(10);
+  });
+
+  test('streaming shows processing indicator then assistant message', async ({ page }) => {
+    const llmResponse = waitForLlmResponse(page);
+    await sendChatMessage(page, 'Say hello in five words or fewer.');
+    await expect(page.locator('.gk-processing')).toBeVisible({ timeout: 15_000 });
+    await llmResponse;
+    await expect(page.locator('.gk-processing')).toBeHidden({ timeout: 45_000 });
+    await waitForAssistantReply(page, { minLength: 3 });
+  });
+
+  test('multi-turn conversation retains context', async ({ page }) => {
+    const firstTurn = 'Remember this codeword: ORBIT42. Reply with only OK.';
+    await sendChatMessage(page, firstTurn);
+    await waitForAssistantReply(page, { minLength: 1 });
+    await expect(page.locator('.gk-processing')).toBeHidden({ timeout: 60_000 });
+
+    const secondTurn = 'What codeword did I ask you to remember? Reply with only the codeword.';
+    const secondRequest = page.waitForRequest((req) => {
+      if (!req.url().includes('/api/guidekit/llm') || req.method() !== 'POST') return false;
+      try {
+        const body = req.postDataJSON() as { userMessage?: string; contents?: unknown[] };
+        return body.userMessage === secondTurn;
+      } catch {
+        return false;
+      }
+    });
+
+    await sendChatMessage(page, secondTurn);
+
+    const req = await secondRequest;
+    const body = req.postDataJSON() as { contents?: Array<{ role?: string; parts?: Array<{ text?: string }> }> };
+    const historyText = JSON.stringify(body.contents ?? []);
+    expect(historyText).toContain('ORBIT42');
+
+    // Still wait for a reply as a smoke check, but do not depend on model compliance.
+    await waitForAssistantReply(page, { minLength: 1 });
+  });
+});
diff --git a/e2e/live/platform.spec.ts b/e2e/live/platform.spec.ts
new file mode 100644
index 0000000..43fb202
--- /dev/null
+++ b/e2e/live/platform.spec.ts
@@ -0,0 +1,50 @@
+import { test, expect } from '@playwright/test';
+import { isLiveLlmEnabled, liveSkipReason } from '../env';
+import {
+  gotoHomeWithWidget,
+  sendChatMessage,
+  waitForAssistantReply,
+} from '../fixtures/live-helpers';
+
+/**
+ * Live Platform Mode — RAG knowledge + plugin hooks with a real LLM.
+ * Run: pnpm test:e2e:live
+ */
+test.describe('Live Platform Mode', () => {
+  test.skip(!isLiveLlmEnabled(), liveSkipReason());
+  test.describe.configure({ timeout: 90_000, retries: 1 });
+
+  test.beforeEach(async ({ page }) => {
+    await gotoHomeWithWidget(page);
+  });
+
+  test('knowledge retrieval answers security doc question', async ({ page }) => {
+    await sendChatMessage(
+      page,
+      'According to the knowledge base: where should API keys be stored in production? Answer in one sentence.',
+    );
+    const reply = await waitForAssistantReply(page);
+    const lower = reply.toLowerCase();
+    expect(
+      lower.includes('server') ||
+        lower.includes('proxy') ||
+        lower.includes('backend') ||
+        lower.includes('server-side'),
+    ).toBeTruthy();
+  });
+
+  test('platform-demo plugin appends validation footer', async ({ page }) => {
+    await sendChatMessage(page, 'Reply with exactly: Platform check.');
+    const reply = await waitForAssistantReply(page);
+    expect(reply).toContain('[Platform Mode]');
+  });
+
+  test('intelligence enriches page context in reply', async ({ page }) => {
+    await sendChatMessage(
+      page,
+      'Name one section on this page that has a contact form. Reply with only the section name.',
+    );
+    const reply = await waitForAssistantReply(page);
+    expect(reply.toLowerCase()).toMatch(/contact/);
+  });
+});
diff --git a/e2e/live/proxy.spec.ts b/e2e/live/proxy.spec.ts
new file mode 100644
index 0000000..971eb38
--- /dev/null
+++ b/e2e/live/proxy.spec.ts
@@ -0,0 +1,103 @@
+import { test, expect } from '@playwright/test';
+import { isLiveLlmEnabled, liveSkipReason } from '../env';
+import { fetchSessionToken } from '../fixtures/live-helpers';
+
+/**
+ * Live proxy API — direct HTTP against running example app.
+ * Run: pnpm test:e2e:live
+ */
+test.describe('Live proxy API', () => {
+  test.skip(!isLiveLlmEnabled(), liveSkipReason());
+  test.describe.configure({ timeout: 90_000, retries: 2 });
+
+  test('LLM proxy streams with valid session token', async ({ request }) => {
+    const token = await fetchSessionToken(request);
+    const res = await request.post('/api/guidekit/llm', {
+      headers: { Authorization: `Bearer ${token}` },
+      data: {
+        provider: 'gemini',
+        model: 'gemini-2.5-flash-lite',
+        systemPrompt: 'You are a helpful assistant.',
+        contents: [],
+        userMessage: 'Reply with exactly: PROXY_OK',
+        stream: true,
+      },
+    });
+    expect(res.ok()).toBeTruthy();
+    const body = await res.text();
+    expect(body.length).toBeGreaterThan(20);
+    expect(body.toLowerCase()).toContain('proxy_ok');
+  });
+
+  test('LLM proxy rejects missing bearer token', async ({ request }) => {
+    const res = await request.post('/api/guidekit/llm', {
+      data: {
+        provider: 'gemini',
+        systemPrompt: 'test',
+        contents: [],
+        userMessage: 'hi',
+      },
+    });
+    expect(res.status()).toBe(401);
+  });
+
+  test('stale session returns 401 with recovery hint', async ({ request }) => {
+    const res = await request.post('/api/guidekit/llm', {
+      headers: { Authorization: 'Bearer invalid.jwt.token' },
+      data: {
+        provider: 'gemini',
+        systemPrompt: 'test',
+        contents: [],
+        userMessage: 'hi',
+      },
+    });
+    expect(res.status()).toBe(401);
+    const body = await res.text();
+    expect(body.toLowerCase()).toMatch(/invalid|token|session/);
+  });
+});
+
+/**
+ * Client-side session recovery when server session keys are gone.
+ * Uses route mock for first 401, then allows real proxy on retry.
+ */
+test.describe('Live session recovery', () => {
+  test.skip(!isLiveLlmEnabled(), liveSkipReason());
+  test.describe.configure({ timeout: 90_000, retries: 2 });
+
+  test('widget recovers after stale session 401 on LLM proxy', async ({ page }) => {
+    let llmCalls = 0;
+    await page.route('**/api/guidekit/llm', async (route) => {
+      if (route.request().method() !== 'POST') {
+        await route.continue();
+        return;
+      }
+      llmCalls += 1;
+      if (llmCalls === 1) {
+        await route.fulfill({
+          status: 401,
+          contentType: 'application/json',
+          body: JSON.stringify({
+            error: 'Session expired or server restarted — request a new token',
+          }),
+        });
+        return;
+      }
+      await route.continue();
+    });
+
+    await page.goto('/');
+    await page.waitForSelector('#guidekit-widget', { timeout: 20_000 });
+
+    const fab = page.locator('.gk-fab');
+    await fab.click();
+    const input = page.locator('.gk-input');
+    await input.waitFor({ state: 'visible', timeout: 10_000 });
+    await input.fill('Reply with exactly: RECOVERED');
+    await page.locator('.gk-send-btn').click();
+
+    const assistant = page.locator('.gk-message[data-role="assistant"]').last();
+    await expect(assistant).toContainText(/RECOVERED/i, { timeout: 60_000 });
+    expect(llmCalls).toBeGreaterThanOrEqual(2);
+  });
+});
diff --git a/e2e/live/voice.spec.ts b/e2e/live/voice.spec.ts
new file mode 100644
index 0000000..364e269
--- /dev/null
+++ b/e2e/live/voice.spec.ts
@@ -0,0 +1,42 @@
+import { test, expect } from '@playwright/test';
+import { isLiveLlmEnabled, liveSkipReason } from '../env';
+import { gotoHomeWithWidget, waitForLlmResponse } from '../fixtures/live-helpers';
+import { openWidgetInput } from '../fixtures/mock-llm-proxy';
+import { setupVoiceE2e } from '../fixtures/voice-e2e';
+
+/**
+ * Live voice — mocked Web Speech STT + real LLM (no STT/TTS API keys).
+ * Run: pnpm test:e2e:live
+ */
+test.describe('Live voice integration', () => {
+  test.skip(!isLiveLlmEnabled(), liveSkipReason());
+  test.describe.configure({ timeout: 120_000, retries: 1 });
+
+  test.beforeEach(async ({ page, context }) => {
+    await setupVoiceE2e(page, context, 'scroll to the pricing section');
+    await gotoHomeWithWidget(page);
+  });
+
+  test('voice transcript reaches real LLM and assistant replies', async ({ page }) => {
+    await openWidgetInput(page);
+
+    const llmResponse = waitForLlmResponse(page, 75_000);
+    const mic = page.locator('.gk-mic-btn');
+    await mic.click();
+
+    await expect(page.locator('.gk-header-status')).toContainText(/Listening|Online/i, {
+      timeout: 45_000,
+    });
+
+    await llmResponse;
+
+    const userBubble = page.locator('.gk-message[data-role="user"]').last();
+    await expect(userBubble).toContainText(/pricing|scroll/i, { timeout: 20_000 });
+
+    const assistant = page.locator('.gk-message[data-role="assistant"]').last();
+    await expect(assistant).not.toHaveText('', { timeout: 45_000 });
+    const text = (await assistant.textContent())?.trim() ?? '';
+    expect(text.length).toBeGreaterThan(5);
+    expect(text.toLowerCase()).not.toContain('error:');
+  });
+});
diff --git a/package.json b/package.json
index 034cfd8..4092afb 100644
--- a/package.json
+++ b/package.json
@@ -29,8 +29,10 @@
     "test:watch": "vitest",
     "typecheck": "turbo typecheck",
     "clean": "turbo clean",
-    "test:e2e": "playwright test",
-    "test:e2e:live": "LIVE_LLM=1 playwright test e2e/live-llm.spec.ts",
+    "test:e2e": "playwright test --project=contract",
+    "test:e2e:contract": "playwright test --project=contract",
+    "test:e2e:live": "LIVE_LLM=1 playwright test --project=live",
+    "test:e2e:live:full": "LIVE_LLM=1 playwright test --project=live --retries=2",
     "size": "size-limit",
     "size:check": "size-limit --limit",
     "release": "pnpm changeset version && pnpm install && pnpm build && pnpm changeset publish",
@@ -39,6 +41,7 @@
     "changeset": "changeset",
     "skills:sync": "bash scripts/setup-codex-skills.sh",
     "check": "bash scripts/ci-check.sh",
+    "check:release": "bash scripts/release-check.sh",
     "stats": "node scripts/package-stats.mjs",
     "llms:generate": "node scripts/generate-llms-txt.mjs"
   },
diff --git a/packages/cli/src/cli.smoke.test.ts b/packages/cli/src/cli.smoke.test.ts
new file mode 100644
index 0000000..8bc24de
--- /dev/null
+++ b/packages/cli/src/cli.smoke.test.ts
@@ -0,0 +1,50 @@
+// @vitest-environment node
+
+import { describe, it, expect } from 'vitest';
+import { spawnSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { resolve } from 'node:path';
+
+function runCli(args: string[], cwd?: string) {
+  const cliPath = resolve(process.cwd(), 'packages/cli/dist/cli.js');
+  expect(existsSync(cliPath), `Missing built CLI at ${cliPath}. Run pnpm build first.`).toBe(true);
+
+  const res = spawnSync(process.execPath, [cliPath, ...args], {
+    cwd: cwd ?? process.cwd(),
+    env: {
+      ...process.env,
+      GUIDEKIT_SECRET: process.env.GUIDEKIT_SECRET ?? 'guidekit-example-e2e-secret-32-chars',
+      LLM_API_KEY: process.env.LLM_API_KEY ?? 'e2e-dummy-llm-key-for-contract-tests',
+    },
+    encoding: 'utf8',
+  });
+
+  return {
+    code: res.status ?? 0,
+    stdout: res.stdout ?? '',
+    stderr: res.stderr ?? '',
+  };
+}
+
+describe('@guidekit/cli — subprocess smoke', () => {
+  it('prints help', () => {
+    const { code, stdout } = runCli(['--help']);
+    expect(code).toBe(0);
+    expect(stdout).toContain('init');
+    expect(stdout).toContain('doctor');
+    expect(stdout).toContain('generate-secret');
+  });
+
+  it('generate-secret outputs a secret', () => {
+    const { code, stdout } = runCli(['generate-secret']);
+    expect(code).toBe(0);
+    expect(stdout.trim().length).toBeGreaterThan(20);
+  });
+
+  it('doctor runs in example app directory', () => {
+    const { code, stdout } = runCli(['doctor'], resolve(process.cwd(), 'apps/example-nextjs'));
+    expect(code).toBe(0);
+    expect(stdout.toLowerCase()).toContain('doctor');
+  });
+});
+
diff --git a/packages/core/src/core/runtime-init.ts b/packages/core/src/core/runtime-init.ts
index 0581853..96c5458 100644
--- a/packages/core/src/core/runtime-init.ts
+++ b/packages/core/src/core/runtime-init.ts
@@ -16,10 +16,9 @@ import { TokenManager } from '../auth/token-manager.js';
 import { ConfigurationError, ErrorCodes } from '../errors/index.js';
 import { createPlatformExtensions } from '../pipeline/extensions.js';
 import type { PlatformExtensionResult } from '../pipeline/extensions.js';
+import { resolveSttConfig, resolveTtsConfig } from './voice-config.js';
 import type {
   LLMConfig,
-  STTConfig,
-  TTSConfig,
   AgentState,
   PageModel,
   ToolDefinition,
@@ -214,7 +213,7 @@ export async function initializeGuideKitRuntime(host: RuntimeInitHost): Promise<
 
   await host.contextManager.initTokenBudget();
 
-  initVoicePipeline(host);
+  await initVoicePipeline(host);
 
   const session = host.contextManager.restoreSession();
   if (session && debug) {
@@ -286,10 +285,27 @@ export async function initializeGuideKitRuntime(host: RuntimeInitHost): Promise<
   }
 }
 
-function initVoicePipeline(host: RuntimeInitHost): void {
+async function initVoicePipeline(host: RuntimeInitHost): Promise<void> {
   const { options, debug } = host;
-  const sttConfig: STTConfig = options.stt ?? { provider: 'web-speech' };
-  const ttsConfig: TTSConfig = options.tts ?? { provider: 'web-speech' };
+  const getToken = () => host.tokenManager?.token ?? null;
+  const refreshSession = host.tokenManager
+    ? async () => {
+        await host.tokenManager!.refresh();
+      }
+    : undefined;
+
+  const sttConfig = await resolveSttConfig(
+    options,
+    host.tokenManager !== null,
+    getToken,
+    refreshSession,
+  );
+  const ttsConfig = await resolveTtsConfig(
+    options,
+    host.tokenManager !== null,
+    getToken,
+    refreshSession,
+  );
 
   let voiceSttConfig: VoicePipelineOptions['sttConfig'];
   let voiceTtsConfig: VoicePipelineOptions['ttsConfig'];
diff --git a/packages/core/src/core/voice-config.test.ts b/packages/core/src/core/voice-config.test.ts
new file mode 100644
index 0000000..5fe71fd
--- /dev/null
+++ b/packages/core/src/core/voice-config.test.ts
@@ -0,0 +1,75 @@
+import { describe, expect, it, vi, beforeEach, afterEach } from 'vitest';
+import { fetchVoiceCredential, resolveSttConfig, resolveTtsConfig } from './voice-config.js';
+import type { GuideKitCoreOptions } from './options.js';
+
+describe('voice-config', () => {
+  beforeEach(() => {
+    vi.stubGlobal('fetch', vi.fn());
+  });
+
+  afterEach(() => {
+    vi.unstubAllGlobals();
+  });
+
+  it('resolveSttConfig returns web-speech by default', async () => {
+    const config = await resolveSttConfig({}, false, () => null);
+    expect(config.provider).toBe('web-speech');
+  });
+
+  it('resolveSttConfig returns inline apiKey without fetch', async () => {
+    const options: GuideKitCoreOptions = {
+      stt: { provider: 'deepgram', apiKey: 'inline-key' },
+    };
+    const config = await resolveSttConfig(options, true, () => 'token');
+    expect(config).toEqual({ provider: 'deepgram', apiKey: 'inline-key' });
+    expect(fetch).not.toHaveBeenCalled();
+  });
+
+  it('resolveSttConfig fetches key from proxy.stt', async () => {
+    vi.mocked(fetch).mockResolvedValueOnce(
+      new Response(JSON.stringify({ apiKey: 'dg-from-proxy' }), { status: 200 }),
+    );
+
+    const options: GuideKitCoreOptions = {
+      tokenEndpoint: '/api/guidekit/token',
+      proxy: { llm: '/api/guidekit/llm', stt: '/api/guidekit/stt' },
+      stt: { provider: 'deepgram' },
+    };
+
+    const config = await resolveSttConfig(options, true, () => 'session-jwt');
+    expect(config).toEqual({ provider: 'deepgram', apiKey: 'dg-from-proxy' });
+    expect(fetch).toHaveBeenCalledWith('/api/guidekit/stt', {
+      method: 'POST',
+      headers: { Authorization: 'Bearer session-jwt' },
+    });
+  });
+
+  it('fetchVoiceCredential retries after session stale 403', async () => {
+    const refresh = vi.fn().mockResolvedValue(undefined);
+    vi.mocked(fetch)
+      .mockResolvedValueOnce(
+        new Response(JSON.stringify({ error: 'No STT API key for session' }), { status: 403 }),
+      )
+      .mockResolvedValueOnce(
+        new Response(JSON.stringify({ apiKey: 'refreshed-key' }), { status: 200 }),
+      );
+
+    const key = await fetchVoiceCredential('/api/guidekit/stt', () => 'jwt', refresh);
+    expect(key).toBe('refreshed-key');
+    expect(refresh).toHaveBeenCalledOnce();
+  });
+
+  it('resolveTtsConfig fetches key from proxy.tts', async () => {
+    vi.mocked(fetch).mockResolvedValueOnce(
+      new Response(JSON.stringify({ apiKey: 'el-from-proxy' }), { status: 200 }),
+    );
+
+    const options: GuideKitCoreOptions = {
+      proxy: { llm: '/api/guidekit/llm', tts: '/api/guidekit/tts' },
+      tts: { provider: 'elevenlabs' },
+    };
+
+    const config = await resolveTtsConfig(options, true, () => 'token');
+    expect(config).toEqual({ provider: 'elevenlabs', apiKey: 'el-from-proxy' });
+  });
+});
diff --git a/packages/core/src/core/voice-config.ts b/packages/core/src/core/voice-config.ts
new file mode 100644
index 0000000..eb9b8ce
--- /dev/null
+++ b/packages/core/src/core/voice-config.ts
@@ -0,0 +1,121 @@
+import { AuthenticationError, ConfigurationError, ErrorCodes, NetworkError } from '../errors/index.js';
+import type { STTConfig, TTSConfig } from '../types/index.js';
+import type { GuideKitCoreOptions } from './options.js';
+
+export type ResolvedSttConfig = STTConfig & (
+  | { provider: 'web-speech' }
+  | { provider: 'deepgram'; apiKey: string }
+  | { provider: 'elevenlabs'; apiKey: string }
+);
+
+export type ResolvedTtsConfig = TTSConfig & (
+  | { provider: 'web-speech' }
+  | { provider: 'elevenlabs'; apiKey: string }
+);
+
+/** Fetch ephemeral STT/TTS API key from server voice proxy. */
+export async function fetchVoiceCredential(
+  endpoint: string,
+  getToken: () => string | null,
+  refreshSession?: () => Promise<void>,
+  retried = false,
+): Promise<string> {
+  const token = getToken();
+  if (!token) {
+    throw new AuthenticationError({
+      code: ErrorCodes.AUTH_EXPIRED_TOKEN,
+      message: 'Session token required for voice proxy requests.',
+      suggestion: 'Ensure tokenEndpoint is configured and init() completed.',
+    });
+  }
+
+  const response = await fetch(endpoint, {
+    method: 'POST',
+    headers: { Authorization: `Bearer ${token}` },
+  });
+
+  if (!response.ok) {
+    const errorBody = await response.text().catch(() => '');
+    const sessionStale =
+      (response.status === 401 || response.status === 403) &&
+      (errorBody.includes('No STT API key') ||
+        errorBody.includes('No TTS API key') ||
+        errorBody.includes('Session expired'));
+
+    if (sessionStale && refreshSession && !retried) {
+      await refreshSession();
+      return fetchVoiceCredential(endpoint, getToken, refreshSession, true);
+    }
+
+    throw new NetworkError({
+      code: ErrorCodes.NETWORK_CONNECTION_LOST,
+      message: `Voice proxy request failed (${response.status}): ${errorBody}`,
+      suggestion: 'Check server STT_API_KEY / TTS_API_KEY and proxy routes.',
+    });
+  }
+
+  const data = (await response.json()) as { apiKey?: string };
+  if (!data.apiKey) {
+    throw new ConfigurationError({
+      code: ErrorCodes.CONFIG_MISSING_REQUIRED,
+      message: 'Voice proxy response missing apiKey.',
+      suggestion: 'Verify handleVoiceProxy returns { apiKey } for authenticated sessions.',
+    });
+  }
+
+  return data.apiKey;
+}
+
+export async function resolveSttConfig(
+  options: GuideKitCoreOptions,
+  hasTokenManager: boolean,
+  getToken: () => string | null,
+  refreshSession?: () => Promise<void>,
+): Promise<ResolvedSttConfig> {
+  const stt = options.stt ?? { provider: 'web-speech' as const };
+  if (stt.provider === 'web-speech') return stt;
+
+  if (stt.apiKey) {
+    return stt as ResolvedSttConfig;
+  }
+
+  const proxyEndpoint = options.proxy?.stt;
+  if (proxyEndpoint && hasTokenManager) {
+    const apiKey = await fetchVoiceCredential(proxyEndpoint, getToken, refreshSession);
+    return { ...stt, apiKey } as ResolvedSttConfig;
+  }
+
+  throw new ConfigurationError({
+    code: ErrorCodes.CONFIG_MISSING_REQUIRED,
+    message: `STT provider "${stt.provider}" requires apiKey or proxy.stt with tokenEndpoint.`,
+    suggestion:
+      'Use proxy={{ stt: "/api/guidekit/stt" }} with tokenEndpoint, or pass apiKey for local dev.',
+  });
+}
+
+export async function resolveTtsConfig(
+  options: GuideKitCoreOptions,
+  hasTokenManager: boolean,
+  getToken: () => string | null,
+  refreshSession?: () => Promise<void>,
+): Promise<ResolvedTtsConfig> {
+  const tts = options.tts ?? { provider: 'web-speech' as const };
+  if (tts.provider === 'web-speech') return tts;
+
+  if (tts.apiKey) {
+    return tts as ResolvedTtsConfig;
+  }
+
+  const proxyEndpoint = options.proxy?.tts;
+  if (proxyEndpoint && hasTokenManager) {
+    const apiKey = await fetchVoiceCredential(proxyEndpoint, getToken, refreshSession);
+    return { ...tts, apiKey } as ResolvedTtsConfig;
+  }
+
+  throw new ConfigurationError({
+    code: ErrorCodes.CONFIG_MISSING_REQUIRED,
+    message: 'TTS provider "elevenlabs" requires apiKey or proxy.tts with tokenEndpoint.',
+    suggestion:
+      'Use proxy={{ tts: "/api/guidekit/tts" }} with tokenEndpoint, or pass apiKey for local dev.',
+  });
+}
diff --git a/packages/core/src/llm/proxy-adapter.ts b/packages/core/src/llm/proxy-adapter.ts
index ceb5f12..78a1adf 100644
--- a/packages/core/src/llm/proxy-adapter.ts
+++ b/packages/core/src/llm/proxy-adapter.ts
@@ -40,7 +40,11 @@ export class ProxyLLMAdapter implements LLMProviderAdapter {
     this.provider = options.provider;
     this.model = options.model;
     const geminiModel =
-      options.model === 'gemini-2.5-pro' ? 'gemini-2.5-pro' : 'gemini-2.5-flash';
+      options.model === 'gemini-2.5-pro'
+        ? 'gemini-2.5-pro'
+        : options.model === 'gemini-2.5-flash-lite'
+          ? 'gemini-2.5-flash-lite'
+          : 'gemini-2.5-flash';
     this.inner =
       options.inner ??
       new GeminiAdapter({ apiKey: 'proxy', provider: 'gemini', model: geminiModel });
diff --git a/packages/core/src/types/index.ts b/packages/core/src/types/index.ts
index 509fa43..c2c27a1 100644
--- a/packages/core/src/types/index.ts
+++ b/packages/core/src/types/index.ts
@@ -385,13 +385,13 @@ export type AgentState =
 
 /** Speech-to-text provider configuration. */
 export type STTConfig =
-  | { provider: 'deepgram'; apiKey: string; model?: 'nova-2' | 'nova-3' }
-  | { provider: 'elevenlabs'; apiKey: string; language?: string }
+  | { provider: 'deepgram'; apiKey?: string; model?: 'nova-2' | 'nova-3' }
+  | { provider: 'elevenlabs'; apiKey?: string; language?: string }
   | { provider: 'web-speech'; language?: string; continuous?: boolean; interimResults?: boolean };
 
 /** Text-to-speech provider configuration. */
 export type TTSConfig =
-  | { provider: 'elevenlabs'; apiKey: string; voiceId?: string }
+  | { provider: 'elevenlabs'; apiKey?: string; voiceId?: string }
   | { provider: 'web-speech'; voice?: string; rate?: number; pitch?: number; language?: string };
 
 /** Transcript event emitted by any STT adapter. */
@@ -419,7 +419,7 @@ export type LLMConfig =
        * @deprecated Use `proxy.llm` + `tokenEndpoint` in production. Client API keys are dev-only.
        */
       apiKey?: string;
-      model?: 'gemini-2.5-flash' | 'gemini-2.5-pro';
+      model?: 'gemini-2.5-flash' | 'gemini-2.5-flash-lite' | 'gemini-2.5-pro';
     }
   | {
       provider: 'openai';
diff --git a/packages/react/src/widget/index.tsx b/packages/react/src/widget/index.tsx
index f57db8a..9aa3e10 100644
--- a/packages/react/src/widget/index.tsx
+++ b/packages/react/src/widget/index.tsx
@@ -312,9 +312,8 @@ export function GuideKitWidget({ theme, consentRequired, instanceId }: WidgetPro
       };
       setMessages((prev) => [...prev, assistantMsg]);
 
-      // Stream tokens into the message
+      // Stream tokens into the message; apply post-pipeline fullText (e.g. plugin hooks).
       const { stream, done } = core.sendTextStream(text);
-      done.catch(() => {});
       for await (const chunk of stream) {
         setMessages((prev) =>
           prev.map((m) =>
@@ -324,6 +323,14 @@ export function GuideKitWidget({ theme, consentRequired, instanceId }: WidgetPro
           ),
         );
       }
+      const result = await done;
+      if (result.fullText) {
+        setMessages((prev) =>
+          prev.map((m) =>
+            m.id === assistantMsgId ? { ...m, content: result.fullText } : m,
+          ),
+        );
+      }
     } catch (err) {
       const errorContent =
         err instanceof Error ? err.message : 'Something went wrong. Please try again.';
@@ -529,6 +536,7 @@ export function GuideKitWidget({ theme, consentRequired, instanceId }: WidgetPro
         className="gk-panel"
         ref={panelRef}
         data-open={isOpen ? 'true' : 'false'}
+        data-testid="guidekit-panel"
         role="dialog"
         aria-label={t('widgetTitle')}
         aria-hidden={!isOpen}
@@ -557,6 +565,7 @@ export function GuideKitWidget({ theme, consentRequired, instanceId }: WidgetPro
         <div
           className="gk-transcript"
           ref={transcriptRef}
+          data-testid="guidekit-transcript"
           role="log"
           aria-live="polite"
           aria-label="Conversation transcript"
@@ -603,6 +612,7 @@ export function GuideKitWidget({ theme, consentRequired, instanceId }: WidgetPro
           {hasVoice && (
             <button
               className="gk-mic-btn"
+              data-testid="guidekit-mic"
               onClick={handleMicToggle}
               disabled={!isReady || isSending}
               data-active={isVoiceActive || isListeningState ? 'true' : 'false'}
@@ -615,6 +625,7 @@ export function GuideKitWidget({ theme, consentRequired, instanceId }: WidgetPro
           <textarea
             className="gk-input"
             ref={inputRef}
+            data-testid="guidekit-input"
             value={inputValue}
             onChange={(e) => setInputValue(e.target.value)}
             onKeyDown={handleKeyDown}
@@ -626,6 +637,7 @@ export function GuideKitWidget({ theme, consentRequired, instanceId }: WidgetPro
           />
           <button
             className="gk-send-btn"
+            data-testid="guidekit-send"
             onClick={handleSend}
             disabled={!isReady || isSending || !inputValue.trim()}
             aria-label={t('sendMessage')}
@@ -672,6 +684,7 @@ export function GuideKitWidget({ theme, consentRequired, instanceId }: WidgetPro
       <button
         className="gk-fab"
         ref={fabRef}
+        data-testid="guidekit-fab"
         onClick={togglePanel}
         aria-label={isOpen ? t('closeAssistant') : t('openAssistant')}
         aria-expanded={isOpen || showConsentDialog}
diff --git a/packages/vanilla/src/index.ts b/packages/vanilla/src/index.ts
index f75278a..ee4d68a 100644
--- a/packages/vanilla/src/index.ts
+++ b/packages/vanilla/src/index.ts
@@ -435,9 +435,14 @@ class VanillaWidget {
 
 export interface GuideKitVanillaOptions {
   tokenEndpoint?: string;
+  proxy?: GuideKitCoreOptions['proxy'];
   stt?: GuideKitCoreOptions['stt'];
   tts?: GuideKitCoreOptions['tts'];
   llm?: GuideKitCoreOptions['llm'];
+  intelligence?: GuideKitCoreOptions['intelligence'];
+  knowledge?: GuideKitCoreOptions['knowledge'];
+  plugins?: GuideKitCoreOptions['plugins'];
+  hallucinationGuard?: GuideKitCoreOptions['hallucinationGuard'];
   agent?: GuideKitCoreOptions['agent'];
   contentMap?: GuideKitCoreOptions['contentMap'];
   options?: GuideKitCoreOptions['options'];
@@ -464,9 +469,14 @@ export async function init(options: GuideKitVanillaOptions): Promise<void> {
 
   _core = new GuideKitCore({
     tokenEndpoint: options.tokenEndpoint,
+    proxy: options.proxy,
     stt: options.stt,
     tts: options.tts,
     llm: options.llm,
+    intelligence: options.intelligence,
+    knowledge: options.knowledge,
+    plugins: options.plugins,
+    hallucinationGuard: options.hallucinationGuard,
     agent: options.agent,
     contentMap: options.contentMap,
     options: options.options,
diff --git a/playwright.config.ts b/playwright.config.ts
index 09c2159..ed74b1f 100644
--- a/playwright.config.ts
+++ b/playwright.config.ts
@@ -1,32 +1,20 @@
+/**
+ * Playwright E2E for the example-nextjs app.
+ *
+ * Voice tests intentionally mock the Web Speech API (see e2e/fixtures/voice-e2e.ts).
+ * Contract tier (e2e/contract): mocked LLM, runs on every PR.
+ * Live tier (e2e/live): real LLM when LIVE_LLM=1, publish gate only.
+ */
 import { defineConfig, devices } from '@playwright/test';
-import { existsSync, readFileSync } from 'fs';
-import { resolve } from 'path';
+import { resolveGuidekitSecret, resolveLlmApiKey } from './e2e/env';
 
-/** Load apps/example-nextjs/.env.local for local live-LLM runs (gitignored). */
-function loadExampleEnvLocal(): Record<string, string> {
-  const envPath = resolve(__dirname, 'apps/example-nextjs/.env.local');
-  if (!existsSync(envPath)) return {};
-  const vars: Record<string, string> = {};
-  for (const line of readFileSync(envPath, 'utf8').split('\n')) {
-    const trimmed = line.trim();
-    if (!trimmed || trimmed.startsWith('#')) continue;
-    const eq = trimmed.indexOf('=');
-    if (eq === -1) continue;
-    vars[trimmed.slice(0, eq)] = trimmed.slice(eq + 1);
-  }
-  return vars;
-}
+const E2E_GUIDEKIT_SECRET = resolveGuidekitSecret();
+const E2E_LLM_API_KEY = resolveLlmApiKey();
 
-const exampleEnv = loadExampleEnvLocal();
-
-const E2E_GUIDEKIT_SECRET =
-  process.env.GUIDEKIT_SECRET ??
-  exampleEnv.GUIDEKIT_SECRET ??
-  'guidekit-example-e2e-secret-32-chars';
-const E2E_LLM_API_KEY =
-  process.env.LLM_API_KEY ??
-  exampleEnv.LLM_API_KEY ??
-  'e2e-dummy-llm-key-for-contract-tests';
+const sharedUse = {
+  ...devices['Desktop Chrome'],
+  baseURL: 'http://localhost:3099',
+};
 
 export default defineConfig({
   testDir: './e2e',
@@ -35,7 +23,6 @@ export default defineConfig({
   retries: process.env.CI ? 2 : 0,
   workers: process.env.CI ? 1 : undefined,
   reporter: 'html',
-  timeout: 30_000,
   expect: {
     timeout: 10_000,
   },
@@ -46,11 +33,17 @@ export default defineConfig({
 
   projects: [
     {
-      name: 'example-nextjs',
-      use: {
-        ...devices['Desktop Chrome'],
-        baseURL: 'http://localhost:3099',
-      },
+      name: 'contract',
+      testDir: './e2e/contract',
+      timeout: 30_000,
+      use: sharedUse,
+    },
+    {
+      name: 'live',
+      testDir: './e2e/live',
+      timeout: 120_000,
+      retries: 2,
+      use: sharedUse,
     },
   ],
 
@@ -60,6 +53,8 @@ export default defineConfig({
       ...process.env,
       GUIDEKIT_SECRET: E2E_GUIDEKIT_SECRET,
       LLM_API_KEY: E2E_LLM_API_KEY,
+      STT_API_KEY: process.env.STT_API_KEY ?? 'e2e-dummy-stt-key-for-contract-tests',
+      TTS_API_KEY: process.env.TTS_API_KEY ?? 'e2e-dummy-tts-key-for-contract-tests',
     },
     url: 'http://localhost:3099',
     reuseExistingServer: !process.env.CI,
diff --git a/scripts/ci-check.sh b/scripts/ci-check.sh
index a4255e8..4846805 100755
--- a/scripts/ci-check.sh
+++ b/scripts/ci-check.sh
@@ -22,10 +22,10 @@ pnpm test:unit
 echo "==> pnpm size:check"
 pnpm size:check
 
-echo "==> pnpm test:e2e"
+echo "==> pnpm test:e2e:contract"
 GUIDEKIT_SECRET="${GUIDEKIT_SECRET:-guidekit-example-e2e-secret-32-chars}" \
 LLM_API_KEY="${LLM_API_KEY:-e2e-dummy-llm-key-for-contract-tests}" \
-pnpm test:e2e
+pnpm test:e2e:contract
 
 echo ""
 echo "All checks passed."
diff --git a/scripts/release-check.sh b/scripts/release-check.sh
new file mode 100755
index 0000000..b7877a2
--- /dev/null
+++ b/scripts/release-check.sh
@@ -0,0 +1,35 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+cd "$ROOT"
+
+echo "==> pnpm check"
+pnpm check
+
+echo "==> verify published packages"
+node scripts/verify-published-packages.mjs
+
+echo "==> CLI subprocess smoke"
+pnpm test:unit -- packages/cli/src/cli.smoke.test.ts
+
+echo "==> live E2E run 1"
+LIVE_LLM=1 pnpm test:e2e:live:full
+
+echo "==> live E2E run 2 (flake budget)"
+LIVE_LLM=1 pnpm test:e2e:live:full
+
+if [ "${SKIP_NPM_DRY_RUN:-}" = "1" ]; then
+  echo "==> npm dry-run skipped (SKIP_NPM_DRY_RUN=1)"
+else
+  if [ -n "${NODE_AUTH_TOKEN:-}" ] || [ -n "${NPM_TOKEN:-}" ]; then
+    echo "==> npm publish dry-run"
+    pnpm publish:packages:dry-run
+  else
+    echo "==> npm publish dry-run skipped (no token)"
+  fi
+fi
+
+echo ""
+echo "Release checks passed."
+
diff --git a/scripts/verify-published-packages.mjs b/scripts/verify-published-packages.mjs
new file mode 100644
index 0000000..fea230d
--- /dev/null
+++ b/scripts/verify-published-packages.mjs
@@ -0,0 +1,45 @@
+import { readFileSync, existsSync, readdirSync } from 'node:fs';
+import { resolve } from 'node:path';
+
+const ROOT = resolve(process.cwd());
+
+const PACKAGES = [
+  'core',
+  'react',
+  'server',
+  'intelligence',
+  'knowledge',
+  'plugins',
+  'vanilla',
+  'vad',
+  'cli',
+];
+
+function fail(msg) {
+  console.error(`verify-published-packages: ${msg}`);
+  process.exit(1);
+}
+
+for (const name of PACKAGES) {
+  const pkgDir = resolve(ROOT, 'packages', name);
+  const pkgJsonPath = resolve(pkgDir, 'package.json');
+  if (!existsSync(pkgJsonPath)) fail(`Missing package.json for packages/${name}`);
+
+  const pkgJson = JSON.parse(readFileSync(pkgJsonPath, 'utf8'));
+  const distDir = resolve(pkgDir, 'dist');
+  if (!existsSync(distDir)) fail(`Missing dist/ for packages/${name} (run pnpm build)`);
+
+  const files = pkgJson.files ?? [];
+  if (!Array.isArray(files) || !files.includes('dist')) {
+    fail(`packages/${name}/package.json should include \"dist\" in files[]`);
+  }
+
+  const srcDir = resolve(pkgDir, 'src');
+  if (!existsSync(srcDir)) fail(`Missing src/ for packages/${name}`);
+  const srcFiles = readdirSync(srcDir, { recursive: true }).map(String);
+  const hasTests = srcFiles.some((p) => p.endsWith('.test.ts') || p.endsWith('.test.tsx'));
+  if (!hasTests) fail(`packages/${name} has no *.test.ts(x) under src/`);
+}
+
+console.log('verify-published-packages: OK');
+