npm - @huydao/karrot - Versions diffs - 0.1.6 → 0.1.8 - Mend

@huydao/karrot 0.1.6 → 0.1.8

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (18) hide show

package/README.md +496 -243
package/dist/executors/adapters/ag-ui-post.d.ts +10 -0
package/dist/executors/adapters/ag-ui-post.js +174 -21
package/dist/executors/adapters/ag-ui.js +5 -3
package/dist/executors/execute.js +1 -0
package/dist/executors/executor.js +2 -1
package/dist/executors/run-result.d.ts +3 -0
package/dist/reports/report.js +20 -0
package/dist/scenarios/scenario.d.ts +1 -0
package/dist/utils/config.d.ts +9 -0
package/package.json +5 -2
package/site/assets/app.js +201 -0
package/site/assets/karrot-mark.svg +10 -0
package/site/assets/styles.css +698 -0
package/site/check.js +43 -0
package/site/docs/index.html +505 -0
package/site/index.html +162 -0
package/site/serve.js +50 -0

package/site/docs/index.html ADDED Viewed

@@ -0,0 +1,505 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1">
+    <title>Karrot Docs - Guide</title>
+    <meta name="description" content="Guide for setting up Karrot config, scenarios, assertions, evals, reports, Playwright integration, and existing session recall.">
+    <link rel="icon" href="../assets/karrot-mark.svg" type="image/svg+xml">
+    <link rel="stylesheet" href="../assets/styles.css">
+  </head>
+  <body>
+    <header class="site-header">
+      <div class="site-header__inner">
+        <a class="brand" href="../index.html" aria-label="Karrot home">
+          <img src="../assets/karrot-mark.svg" alt="">
+          <span>Karrot <small>Docs</small></span>
+        </a>
+        <nav class="top-nav" aria-label="Primary navigation">
+          <a href="../index.html">Home</a>
+          <a class="is-active" href="index.html">Docs</a>
+          <a href="https://www.npmjs.com/package/@huydao/karrot">npm</a>
+        </nav>
+        <button class="mobile-nav-toggle" type="button" data-nav-toggle aria-expanded="false" aria-controls="docs-sidebar">
+          Menu
+        </button>
+      </div>
+    </header>
+    <div class="sidebar-backdrop" data-sidebar-backdrop></div>
+    <div class="docs-shell">
+      <aside class="docs-sidebar" id="docs-sidebar" data-sidebar aria-label="Docs navigation">
+        <div class="docs-sidebar__title">Karrot guide</div>
+        <div class="sidebar-group">
+          <strong>Start</strong>
+          <a data-section-link href="#introduction">Introduction</a>
+          <a data-section-link href="#quick-start">Installation</a>
+          <a data-section-link href="#yaml-config">YAML config</a>
+          <a data-section-link href="#run-script">Run script</a>
+        </div>
+        <div class="sidebar-group">
+          <strong>Authoring</strong>
+          <a data-section-link href="#scenario-basics">Scenario basics</a>
+          <a data-section-link href="#turn-model">Turn model</a>
+          <a data-section-link href="#assertions">Assertions</a>
+          <a data-section-link href="#eval">Eval</a>
+        </div>
+        <div class="sidebar-group">
+          <strong>Operations</strong>
+          <a data-section-link href="#reports">Reports and artifacts</a>
+          <a data-section-link href="#playwright">Playwright integration</a>
+          <a data-section-link href="#existing-session">Existing session recall</a>
+        </div>
+      </aside>
+      <main class="docs-content">
+        <div class="docs-hero">
+          <div class="eyebrow">Documentation</div>
+          <h1>Guide to using Karrot</h1>
+          <p>
+            Use this page as the onboarding path for engineers and agents. It explains the files Karrot expects,
+            the scenario model, and how to embed Karrot in a Playwright workflow.
+          </p>
+        </div>
+        <section id="introduction">
+          <h2>Introduction</h2>
+          <p>
+            Karrot is a reusable AI-level test runner. It sends user turns to an assistant, collects output,
+            runs assertions, scores eval dimensions, and writes stable artifacts and reports.
+          </p>
+          <div class="callout">
+            <strong>Boundary</strong>
+            <p>Karrot owns the AI test layer. Your project owns auth, runtime discovery, transport secrets, and product-specific context.</p>
+          </div>
+          <ul>
+            <li>Use Karrot for product AI chat testing, multi-turn regression, and prompt quality checks.</li>
+            <li>Keep product-specific login and runtime discovery outside Karrot.</li>
+            <li>Pass runtime values through YAML variables and `execute()` options.</li>
+          </ul>
+        </section>
+        <section id="quick-start">
+          <h2>Installation</h2>
+          <p>Add Karrot to the project that will run your assistant tests.</p>
+          <pre><code class="language-bash">npm install @huydao/karrot
+npm install -D tsx typescript</code></pre>
+          <div class="callout">
+            <strong>OpenAI requirement</strong>
+            <p>Set `OPENAI_API_KEY` when you use `aiAssert`, `eval`, or generated user messages with `aiGen`.</p>
+          </div>
+          <pre><code class="language-bash">export OPENAI_API_KEY=&lt;your-openai-api-key&gt;</code></pre>
+          <p>The normal setup has three files: `karrot.config.yml`, a runner script, and one scenario module.</p>
+        </section>
+        <section id="yaml-config">
+          <h2>YAML config</h2>
+          <p>
+            The YAML config describes transport, artifacts, evaluation prompt paths, scenario context, and report metadata.
+            Karrot resolves `${VARIABLE}` placeholders from `execute({ variables })`, then from `process.env`.
+          </p>
+          <h3 id="ag-ui-wss">AG-UI WSS transport</h3>
+          <pre><code class="language-yml">version: 1
+transport:
+  type: ag-ui-wss
+  env:
+    AGENT_URL: ${AGENT_URL}
+    AGENT_ID: ${AGENT_ID}
+    WS_URL: ${WS_URL}
+    WS_TOPIC: ${WS_TOPIC}
+    AUTH_TOKEN: ${AUTH_TOKEN}
+    WS_STOMP_HEADERS: Authorization:${AUTH_TOKEN}
+    WS_HEADERS: Origin:${APP_BASE_URL},User-Agent:Mozilla/5.0
+  processTimeoutMs: 120000
+artifacts:
+  directory: ./artifacts/karrot
+execution:
+  stopOnFailure: false
+  concurrency: 1
+context:
+  appBaseUrl: ${APP_BASE_URL}
+  projectId: ${PROJECT_ID}
+evaluation:
+  promptDirectory: ./prompts/eval
+report:
+  enabled: true
+  environment: ${TEST_ENV}
+  projectName: ${PROJECT_NAME}
+  runtime:
+    agentUrl: ${AGENT_URL}
+    agentId: ${AGENT_ID}
+    wsUrl: ${WS_URL}
+    wsTopic: ${WS_TOPIC}
+    accountId: ${ACCOUNT_ID}
+    projectId: ${PROJECT_ID}
+    appBaseUrl: ${APP_BASE_URL}</code></pre>
+          <div class="callout">
+            <strong>Secrets</strong>
+            <p>Keep tokens, account IDs, and auth headers in environment variables or CI secrets. Do not commit them in YAML.</p>
+          </div>
+          <h3 id="ag-ui-post">AG-UI POST transport</h3>
+          <pre><code class="language-yml">version: 1
+transport:
+  type: ag-ui-post
+  injectMessage: true
+  run:
+    url: ${AGENT_RUN_URL}
+    headers:
+      Authorization: Bearer ${AUTH_TOKEN}
+      Content-Type: application/json
+    payload:
+      body:
+        threadId: ${THREAD_ID}
+        messages: []
+  processTimeoutMs: 120000</code></pre>
+        </section>
+        <section id="run-script">
+          <h2>Run script</h2>
+          <p>The run script collects runtime values, points Karrot at a scenario file, and returns a failed exit code when scenarios fail.</p>
+          <pre><code class="language-ts">import { execute, getScenarioRunStatus } from '@huydao/karrot';
+function required(name: string): string {
+  const value = process.env[name]?.trim();
+  if (!value) {
+    throw new Error(`Missing required environment variable: ${name}`);
+  }
+  return value;
+}
+const execution = await execute('./karrot.config.yml', {
+  variables: {
+    TEST_ENV: process.env.TEST_ENV ?? 'local',
+    PROJECT_NAME: process.env.PROJECT_NAME ?? 'Demo Agent',
+    APP_BASE_URL: required('APP_BASE_URL'),
+    AGENT_URL: required('AGENT_URL'),
+    AGENT_ID: required('AGENT_ID'),
+    WS_URL: required('WS_URL'),
+    WS_TOPIC: required('WS_TOPIC'),
+    AUTH_TOKEN: required('AUTH_TOKEN'),
+    ACCOUNT_ID: process.env.ACCOUNT_ID ?? '',
+    PROJECT_ID: process.env.PROJECT_ID ?? '',
+  },
+  scenario: {
+    file: './src/scenarios/basic.ts',
+    ids: process.env.SCENARIO_IDS?.split(',').map((id) => id.trim()).filter(Boolean),
+  },
+});
+if (getScenarioRunStatus(execution.results) === 'FAIL') {
+  process.exitCode = 1;
+}</code></pre>
+          <pre><code class="language-bash">TEST_ENV=qa npx tsx ./src/run-karrot.ts</code></pre>
+        </section>
+        <section id="scenario-basics">
+          <h2>Scenario basics</h2>
+          <p>A scenario module exports `scenarioSet`. Export `buildScenarioContext(baseContext)` when the scenario needs typed or derived context.</p>
+          <pre><code class="language-ts">import {
+  aiGen,
+  AiScenarioSet,
+  type AiScenario,
+  type BaseAiScenarioContext,
+} from '@huydao/karrot';
+type DemoContext = BaseAiScenarioContext & {
+  appBaseUrl: string;
+};
+export function buildScenarioContext(baseContext: BaseAiScenarioContext): DemoContext {
+  return {
+    ...baseContext,
+    appBaseUrl: String(baseContext.appBaseUrl ?? ''),
+  };
+}
+const scenarios: AiScenario&lt;DemoContext&gt;[] = [
+  {
+    id: 'BASIC-CHAT-01',
+    name: 'Agent answers and suggests next steps',
+    turns: [
+      {
+        label: 'Ask what the agent can do',
+        message: () =&gt; 'What can you help me do in this product?',
+        assertions: [
+          {
+            assert: { hasText: 'help' },
+            description: 'The response should explain useful capabilities',
+          },
+        ],
+        eval: ['correctness', 'helpfulness', 'clarity'],
+      },
+      {
+        label: 'Ask for follow-up prompts',
+        message: aiGen.fromGuidance(
+          'Ask for three short follow-up prompts based on the previous answer.',
+        ),
+      },
+    ],
+  },
+];
+export const scenarioSet = new AiScenarioSet(scenarios);</code></pre>
+          <ul>
+            <li>`id` is stable and used by filters, CI, and reports.</li>
+            <li>`name` is the readable report name.</li>
+            <li>`turns` are ordered user messages sent to the same conversation thread.</li>
+          </ul>
+        </section>
+        <section id="turn-model">
+          <h2>Turn model</h2>
+          <p>Each turn describes one user message plus optional checks and quality scoring.</p>
+          <ul>
+            <li>`label`: readable turn label shown in reports.</li>
+            <li>`message`: user input as a function or `aiGen` helper.</li>
+            <li>`idleTimeoutMs`: optional timeout for assistant inactivity.</li>
+            <li>`processTimeoutMs`: optional hard timeout for long-running operations.</li>
+            <li>`assertions`: hard pass/fail checks.</li>
+            <li>`eval`: response quality dimensions.</li>
+            <li>`onComplete`: optional callback after output is returned.</li>
+          </ul>
+          <pre><code class="language-ts">{
+  label: 'Ask for next prompts',
+  message: aiGen.fromGuidance(
+    'Ask for three concise follow-up prompts based on the previous answer.',
+  ),
+  idleTimeoutMs: 120_000,
+  processTimeoutMs: 120_000,
+  assertions: [
+    { assert: { hasText: 'prompt' } },
+  ],
+  eval: ['relevance', 'conciseness'],
+}</code></pre>
+        </section>
+        <section id="assertions">
+          <h2>Assertions</h2>
+          <p>Assertions decide whether a turn passes or fails. Use them for required behavior.</p>
+          <h3 id="direct-assertions">Direct assertions</h3>
+          <pre><code class="language-ts">assertions: [
+  { assert: { hasText: 'created successfully' } },
+  { assert: { toolcall: ['create_test_case'] } },
+  { assert: { toolcall: [] } },
+  {
+    assert: {
+      toolcallWithContent: {
+        name: 'create_test_case',
+        hasText: ['login', 'password'],
+        hasProperties: {
+          priority: 'High',
+        },
+      },
+    },
+  },
+]</code></pre>
+          <h3 id="semantic-assertions">Semantic AI assertions</h3>
+          <pre><code class="language-ts">assertions: [
+  {
+    aiAssert: {
+      hasContent: 'The answer explains the next action and why it is needed.',
+    },
+  },
+  {
+    aiAssert: {
+      notHasContent: 'The answer invents product capabilities not present in the prompt.',
+    },
+  },
+]</code></pre>
+          <div class="callout">
+            <strong>When to use each</strong>
+            <p>Use `assert` for deterministic text or tool checks. Use `aiAssert` when the requirement is semantic and exact matching would be brittle.</p>
+          </div>
+        </section>
+        <section id="eval">
+          <h2>Eval</h2>
+          <p>Eval is separate from assertions. Assertions are hard requirements; evals score response quality.</p>
+          <pre><code class="language-ts">eval: [
+  'correctness',
+  'coverage',
+  'helpfulness',
+  {
+    dimension: 'productFit',
+    guidance: 'Score whether the answer is specifically useful for users of this product.',
+  },
+]</code></pre>
+          <p>Common dimensions include correctness, coverage, helpfulness, clarity, completeness, conciseness, relevance, actionability, structure, consistency, and safety.</p>
+          <pre><code class="language-yml">evaluation:
+  promptDirectory: ./prompts/eval</code></pre>
+        </section>
+        <section id="reports">
+          <h2>Reports and artifacts</h2>
+          <p>Each run creates an artifact directory under `artifacts/&lt;timestamp&gt;` or the configured `artifacts.directory`.</p>
+          <ul>
+            <li>Raw transport logs such as `.jsonl` or `.sse`.</li>
+            <li>Generated-message traces.</li>
+            <li>AI assertion traces.</li>
+            <li>JSON run report.</li>
+            <li>HTML run report.</li>
+          </ul>
+          <pre><code class="language-ts">console.log([
+  `Status: ${status}`,
+  `Artifacts: ${execution.outputDirectory}`,
+  `JSON report: ${execution.reportPaths?.jsonPath ?? '-'}`,
+  `HTML report: ${execution.reportPaths?.htmlPath ?? '-'}`,
+].join('\n'));</code></pre>
+        </section>
+        <section id="playwright">
+          <h2>Playwright integration</h2>
+          <p>Use `execute()` when the scenario file owns the full conversation. Karrot starts a thread on the first turn and reuses it for later turns in the scenario.</p>
+          <pre><code class="language-ts">import path from 'node:path';
+import { expect, test } from '@playwright/test';
+import { execute, getScenarioRunStatus } from '@huydao/karrot';
+test('agent completes the basic flow', async () =&gt; {
+  const execution = await execute(path.resolve(__dirname, '../karrot.config.yml'), {
+    variables: {
+      TEST_ENV: process.env.TEST_ENV ?? 'qa',
+      PROJECT_NAME: 'Demo Agent',
+      APP_BASE_URL: process.env.APP_BASE_URL,
+      AGENT_URL: process.env.AGENT_URL,
+      AGENT_ID: process.env.AGENT_ID,
+      WS_URL: process.env.WS_URL,
+      WS_TOPIC: process.env.WS_TOPIC,
+      AUTH_TOKEN: process.env.AUTH_TOKEN,
+      ACCOUNT_ID: process.env.ACCOUNT_ID,
+      PROJECT_ID: process.env.PROJECT_ID,
+    },
+    scenario: {
+      file: path.resolve(__dirname, '../src/scenarios/basic.ts'),
+      ids: ['BASIC-CHAT-01'],
+    },
+  });
+  expect(getScenarioRunStatus(execution.results)).toBe('PASS');
+});</code></pre>
+        </section>
+        <section id="existing-session">
+          <h2>Existing session recall</h2>
+          <p>Use `runScenario()` when Playwright needs to create or recall an existing agent session itself. Pass the known thread ID as `initialThreadId`.</p>
+          <div class="callout">
+            <strong>Concurrency rule</strong>
+            <p>Keep `concurrency: 1` when using `initialThreadId`. A single existing session should not be shared by parallel scenarios.</p>
+          </div>
+          <pre><code class="language-ts">import { expect, test } from '@playwright/test';
+import {
+  AiScenarioSet,
+  createRunArtifactDirectory,
+  runScenario,
+  type AiScenario,
+  type BaseAiScenarioContext,
+} from '@huydao/karrot';
+import { runAgUiMessage } from '@huydao/karrot/adapters/ag-ui';
+type SessionContext = BaseAiScenarioContext & {
+  projectId: string;
+};
+const scenarios: AiScenario&lt;SessionContext&gt;[] = [
+  {
+    id: 'RESUME-SESSION-01',
+    name: 'Continue an existing assistant session',
+    turns: [
+      {
+        label: 'Recall current context',
+        message: ({ projectId }) =&gt;
+          `Continue in project ${projectId}. Summarize what we have already discussed.`,
+        assertions: [
+          {
+            aiAssert: {
+              hasContent: 'The answer uses the existing conversation context.',
+            },
+          },
+        ],
+        eval: ['relevance', 'helpfulness'],
+      },
+    ],
+  },
+];
+test('continues an existing agent session', async () =&gt; {
+  const initialThreadId = process.env.KARROT_THREAD_ID;
+  if (!initialThreadId) {
+    throw new Error('KARROT_THREAD_ID is required to resume an existing session.');
+  }
+  const outputDirectory = await createRunArtifactDirectory('./artifacts/karrot-playwright');
+  const env = {
+    ...process.env,
+    WS_STOMP_HEADERS: `Authorization:${process.env.AUTH_TOKEN ?? ''}`,
+    WS_HEADERS: `Origin:${process.env.APP_BASE_URL ?? ''},User-Agent:Mozilla/5.0`,
+  };
+  const scenarioSet = new AiScenarioSet(scenarios);
+  const [result] = await runScenario(scenarioSet.select(['RESUME-SESSION-01']), {
+    context: {
+      projectId: process.env.PROJECT_ID ?? '',
+    },
+    env,
+    outputDirectory,
+    initialThreadId,
+    concurrency: 1,
+    messageRunner: async ({ message, outputDirectory, threadId, processTimeoutMs }) =&gt;
+      await runAgUiMessage({
+        message,
+        env,
+        outputDirectory,
+        threadId,
+        processTimeoutMs,
+      }),
+  });
+  expect(result.status).toBe('PASS');
+  expect(result.threadId).toBe(initialThreadId);
+});</code></pre>
+          <h3 id="init-then-recall">Init then recall</h3>
+          <p>To start a new session and continue it later in the same script, run once without `initialThreadId`, then pass the returned `threadId` into the next call.</p>
+          <pre><code class="language-ts">const [createdSession] = await runScenario(initScenarioSet.select(['INIT-SESSION-01']), {
+  context,
+  env,
+  outputDirectory,
+  concurrency: 1,
+  messageRunner,
+});
+const threadId = createdSession.threadId;
+if (!threadId) {
+  throw new Error('Initial scenario did not return a threadId.');
+}
+const [continuedSession] = await runScenario(recallScenarioSet.select(['RECALL-SESSION-01']), {
+  context,
+  env,
+  outputDirectory,
+  initialThreadId: threadId,
+  concurrency: 1,
+  messageRunner,
+});</code></pre>
+        </section>
+      </main>
+      <aside class="docs-toc" aria-label="On this page">
+        <div class="toc-title">On this page</div>
+        <nav data-toc></nav>
+      </aside>
+    </div>
+    <script src="../assets/app.js"></script>
+  </body>
+</html>

package/site/index.html ADDED Viewed

@@ -0,0 +1,162 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1">
+    <title>Karrot - AI scenario testing for multi-turn agents</title>
+    <meta name="description" content="Karrot is a reusable AI scenario runner for testing multi-turn agents with assertions, evals, and reports.">
+    <link rel="icon" href="assets/karrot-mark.svg" type="image/svg+xml">
+    <link rel="stylesheet" href="assets/styles.css">
+  </head>
+  <body>
+    <header class="site-header">
+      <div class="site-header__inner">
+        <a class="brand" href="index.html" aria-label="Karrot home">
+          <img src="assets/karrot-mark.svg" alt="">
+          <span>Karrot <small>AI test runner</small></span>
+        </a>
+        <nav class="top-nav" aria-label="Primary navigation">
+          <a href="docs/index.html">Docs</a>
+          <a href="docs/index.html#quick-start">Quick start</a>
+          <a href="https://www.npmjs.com/package/@huydao/karrot">npm</a>
+        </nav>
+      </div>
+    </header>
+    <main>
+      <section class="hero">
+        <div class="hero-grid">
+          <div>
+            <div class="eyebrow">Reusable assistant testing</div>
+            <h1>AI scenario testing for multi-turn agents</h1>
+            <p class="lead">
+              Karrot runs agent conversations as repeatable scenarios, checks required behavior with assertions,
+              scores response quality with evals, and writes reports that humans and CI can read.
+            </p>
+            <div class="hero-actions">
+              <a class="button button--primary" href="docs/index.html#quick-start">Get started</a>
+              <a class="button" href="docs/index.html">Read docs</a>
+            </div>
+          </div>
+          <div class="hero-panel" aria-label="Karrot command preview">
+            <div class="panel-bar" aria-hidden="true">
+              <span class="dot"></span>
+              <span class="dot"></span>
+              <span class="dot"></span>
+            </div>
+            <pre class="terminal"><code><span class="muted">$</span> npm install @huydao/karrot
+<span class="muted">$</span> TEST_ENV=qa npx tsx ./src/run-karrot.ts
+Status: PASS
+Artifacts: artifacts/karrot/2026-05-18T09-12-44
+JSON report: scenario-run-report.json
+HTML report: scenario-run-report.html</code></pre>
+          </div>
+        </div>
+      </section>
+      <section class="section">
+        <div class="section-header">
+          <div>
+            <div class="eyebrow">What it handles</div>
+            <h2>Purpose-built for agent regression</h2>
+          </div>
+          <p>Karrot owns the AI test layer. Your product code owns login, runtime discovery, and product-specific context.</p>
+        </div>
+        <div class="feature-grid">
+          <article class="feature-card">
+            <span>1</span>
+            <h3>Multi-turn scenarios</h3>
+            <p>Model user turns as ordered conversations and keep the same agent thread across each scenario.</p>
+          </article>
+          <article class="feature-card">
+            <span>2</span>
+            <h3>AG-UI transports</h3>
+            <p>Run agents over AG-UI WebSocket/STOMP or HTTP POST patterns without baking product auth into Karrot.</p>
+          </article>
+          <article class="feature-card">
+            <span>3</span>
+            <h3>Assertions</h3>
+            <p>Use deterministic checks for text/tool calls and semantic AI assertions for behavior that is hard to match literally.</p>
+          </article>
+          <article class="feature-card">
+            <span>4</span>
+            <h3>Eval dimensions</h3>
+            <p>Score response quality with built-in or project-specific dimensions such as correctness, coverage, and helpfulness.</p>
+          </article>
+          <article class="feature-card">
+            <span>5</span>
+            <h3>Reports</h3>
+            <p>Produce JSON and HTML reports with turn output, assertion results, eval scores, artifacts, and thread IDs.</p>
+          </article>
+          <article class="feature-card">
+            <span>6</span>
+            <h3>Playwright friendly</h3>
+            <p>Call Karrot from Playwright tests, attach artifacts, and resume an existing agent session with `initialThreadId`.</p>
+          </article>
+        </div>
+      </section>
+      <section class="section" id="quick-start">
+        <div class="section-header">
+          <div>
+            <div class="eyebrow">Quick start</div>
+            <h2>Three files to a runnable scenario</h2>
+          </div>
+          <p>Start with a YAML config, a small runner script, and a scenario module that exports `scenarioSet`.</p>
+        </div>
+        <div class="quick-grid">
+          <article class="quick-card">
+            <h3>Install</h3>
+            <p>Add Karrot to the project that already knows how to authenticate and discover your agent runtime.</p>
+            <pre><code class="language-bash">npm install @huydao/karrot
+npm install -D tsx typescript
+export OPENAI_API_KEY=&lt;your-openai-api-key&gt;</code></pre>
+          </article>
+          <article class="quick-card">
+            <h3>Run</h3>
+            <p>Keep runtime values in environment variables or CI secrets, then execute the scenario file.</p>
+            <pre><code class="language-bash">TEST_ENV=qa npx tsx ./src/run-karrot.ts</code></pre>
+          </article>
+        </div>
+      </section>
+      <section class="section">
+        <div class="section-header">
+          <div>
+            <div class="eyebrow">Minimal example</div>
+            <h2>Config plus scenario plus runner</h2>
+          </div>
+          <p>The docs page expands each part, including Playwright integration and existing-session recall.</p>
+        </div>
+        <pre><code class="language-ts">import { execute, getScenarioRunStatus } from '@huydao/karrot';
+const execution = await execute('./karrot.config.yml', {
+  variables: {
+    AGENT_URL: process.env.AGENT_URL,
+    AGENT_ID: process.env.AGENT_ID,
+    WS_URL: process.env.WS_URL,
+    WS_TOPIC: process.env.WS_TOPIC,
+    AUTH_TOKEN: process.env.AUTH_TOKEN,
+  },
+  scenario: {
+    file: './src/scenarios/basic.ts',
+    ids: ['BASIC-CHAT-01'],
+  },
+});
+if (getScenarioRunStatus(execution.results) === 'FAIL') {
+  process.exitCode = 1;
+}</code></pre>
+      </section>
+    </main>
+    <footer class="footer">
+      <div class="footer__inner">
+        <span>Karrot 0.1.6 - reusable AI scenario execution, assertion, evaluation, and reporting.</span>
+        <span><a href="docs/index.html">Docs</a> · <a href="https://www.npmjs.com/package/@huydao/karrot">npm package</a></span>
+      </div>
+    </footer>
+    <script src="assets/app.js"></script>
+  </body>
+</html>