niceeval 0.4.4 → 0.4.5

package/docs-site/images/hitl-handshake-zh.svg

@@ -0,0 +1,89 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1240 668" role="img" aria-labelledby="title desc">
+  <title id="title">HITL 一次完整握手</title>
+  <desc id="desc">eval 发送任务，应用停在审批上，本轮以 waiting 返回并带 input.requested；t.respond 作为又一次普通 send 把结构化裁决交回，同一轮继续执行到 completed。</desc>
+  <defs>
+    <marker id="headBlue" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="8" markerHeight="8" orient="auto-start-reverse">
+      <path d="M 0 0 L 10 5 L 0 10 z" fill="#8ab4f8" />
+    </marker>
+    <marker id="headPurple" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="8" markerHeight="8" orient="auto-start-reverse">
+      <path d="M 0 0 L 10 5 L 0 10 z" fill="#a78bfa" />
+    </marker>
+    <linearGradient id="card" x1="0" x2="1" y1="0" y2="1">
+      <stop offset="0" stop-color="#0d1117" />
+      <stop offset="1" stop-color="#111820" />
+    </linearGradient>
+    <style>
+      .label { fill: #e6edf3; font: 600 24px ui-monospace, SFMono-Regular, Menlo, Consolas, monospace; }
+      .code { fill: #e6edf3; font: 20px ui-monospace, SFMono-Regular, Menlo, Consolas, monospace; }
+      .codeSm { fill: #c9d1d9; font: 18px ui-monospace, SFMono-Regular, Menlo, Consolas, monospace; }
+      .cjk { fill: #c9d1d9; font: 20px -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; }
+      .muted { fill: #8b949e; font: 18px -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; }
+      .waiting { fill: #f0b429; }
+      .done { fill: #7ee787; }
+      .pill { fill: #1f2937; stroke: #374151; stroke-width: 1; }
+      .head { fill: #161b22; stroke: #30363d; stroke-width: 1.5; }
+      .arrow { stroke: #8ab4f8; stroke-width: 3; fill: none; marker-end: url(#headBlue); }
+      .returnArrow { stroke: #a78bfa; stroke-width: 3; fill: none; marker-end: url(#headPurple); }
+      .lane { stroke: #30363d; stroke-width: 1; stroke-dasharray: 5 8; }
+    </style>
+  </defs>
+
+  <rect x="1" y="1" width="1238" height="666" rx="24" fill="url(#card)" stroke="#30363d" stroke-width="2" />
+
+  <!-- 生命线与头部 -->
+  <line x1="200" y1="76" x2="200" y2="628" class="lane" />
+  <line x1="680" y1="76" x2="680" y2="628" class="lane" />
+  <line x1="1060" y1="76" x2="1060" y2="628" class="lane" />
+
+  <rect x="110" y="30" width="180" height="38" rx="10" class="head" />
+  <text x="200" y="57" class="label" text-anchor="middle">test(t)</text>
+  <rect x="565" y="30" width="230" height="38" rx="10" class="head" />
+  <text x="680" y="57" class="label" text-anchor="middle">Adapter 的 send</text>
+  <rect x="970" y="30" width="180" height="38" rx="10" class="head" />
+  <text x="1060" y="57" class="label" text-anchor="middle">你的应用</text>
+
+  <!-- ① 发起任务 -->
+  <text x="220" y="112" class="code">await t.send("把服务部署到 prod")</text>
+  <path d="M 206 124 H 668" class="arrow" />
+  <text x="220" y="146" class="muted">第 1 次 send</text>
+
+  <text x="700" y="152" class="cjk">调应用</text>
+  <path d="M 686 164 H 1048" class="arrow" />
+  <text x="944" y="196" class="muted" text-anchor="middle">停在部署确认上，等人批准</text>
+
+  <!-- ② waiting 返回 -->
+  <text x="220" y="222" class="code">Turn{ status: <tspan class="waiting">"waiting"</tspan>,</text>
+  <text x="220" y="246" class="codeSm">  events: [..., input.requested(</text>
+  <text x="220" y="268" class="codeSm">    id: "req_1", options: approve | deny)] }</text>
+  <path d="M 674 282 H 206" class="returnArrow" />
+
+  <!-- ③ eval 侧检查（不触发 send） -->
+  <rect x="40" y="308" width="170" height="32" rx="8" class="pill" />
+  <text x="54" y="331" class="codeSm">t.parked()</text>
+  <text x="230" y="331" class="muted">断言这一轮确实停下了</text>
+
+  <rect x="40" y="350" width="500" height="32" rx="8" class="pill" />
+  <text x="54" y="373" class="codeSm">t.requireInputRequest({ action: "deploy" })</text>
+  <text x="560" y="373" class="muted">取出待答请求；只读结果，不触发 send</text>
+
+  <!-- ④ 替人回答 -->
+  <text x="220" y="420" class="code">await t.respond("approve")</text>
+  <path d="M 206 432 H 668" class="arrow" />
+  <text x="220" y="456" class="codeSm">input.responses = [{ requestId: "req_1",</text>
+  <text x="220" y="478" class="codeSm">  optionId: "approve" }]</text>
+  <text x="500" y="420" class="muted">第 2 次 send：又一次普通 send</text>
+
+  <text x="696" y="470" class="cjk">按 requestId 交回裁决</text>
+  <path d="M 686 482 H 1048" class="arrow" />
+  <text x="944" y="510" class="muted" text-anchor="middle">同一轮接着跑，不重发请求</text>
+
+  <!-- ⑤ completed 返回 -->
+  <path d="M 1054 530 H 686" class="returnArrow" />
+  <text x="220" y="562" class="code">Turn{ status: <tspan class="done">"completed"</tspan>, events: [...] }</text>
+  <path d="M 674 574 H 206" class="returnArrow" />
+
+  <!-- ⑥ 断言照常 -->
+  <rect x="40" y="600" width="300" height="32" rx="8" class="pill" />
+  <text x="54" y="623" class="codeSm">t.calledTool("deploy")</text>
+  <text x="360" y="623" class="muted">事件流照常累计，断言词汇不变</text>
+</svg>

package/docs-site/images/logo.svg

@@ -0,0 +1,6 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 220 56" role="img" aria-label="niceeval">
+  <rect width="56" height="56" rx="12" fill="#11161e"/>
+  <path d="M15 14h28v7H25v7h15v7H25v13H15z" fill="#f8fafc"/>
+  <path d="M31 35h14v7H31z" fill="#848c8e"/>
+  <text x="72" y="37" fill="#11161e" font-family="Inter, Arial, sans-serif" font-size="28" font-weight="700">niceeval</text>
+</svg>

package/docs-site/index.mdx

@@ -0,0 +1,181 @@
+---
+title: "NiceEval"
+sidebarTitle: "Home"
+description: "NiceEval is a progressive, full-featured, developer-friendly, agent-native eval tool for AI agents."
+---
+
+<div align="center">
+
+# NiceEval
+
+**A progressive, full-featured, developer-friendly, agent-native eval tool for AI agents**
+
+</div>
+
+[NiceEval](https://niceeval.com/) is an agent-native eval tool inspired by [eve](https://eve.dev). It aims for strong developer experience first: a project can usually integrate it in about 10 minutes, eval files stay readable, and results are easy to inspect.
+
+It is also broad enough to evaluate coding-agent plugins, hooks, and Skills built for Claude Code / Codex, as well as your own AI agent application. Whether your app uses AI SDK, LangGraph, Pi, or a custom agent loop, you can connect it through an adapter.
+
+After each run, [NiceEval](https://niceeval.com/) generates readable reports and structured artifacts so you can inspect agent behavior, debug failures, and keep improving pass rate, cost, and latency.
+
+<CardGroup cols={3}>
+  <Card title="Claude Code / Codex plugin" icon="plug" href="/example/claude-code-codex-plugin">
+    Use sandbox workspaces to give a coding agent real tasks, then verify plugin behavior through tests, diffs, and tool-call records.
+  </Card>
+  <Card title="Claude Code / Codex Skill" icon="wand-magic-sparkles" href="/example/claude-code-codex-skill">
+    Inject the Skill through experiment setup, then compare pass rate, cost, and behavior against a no-Skill baseline.
+  </Card>
+  <Card title="AI agent application" icon="globe" href="/example/ai-agent-application">
+    Wrap your AI agent with `defineAgent` and bring replies, tool calls, and structured output into the same eval surface.
+  </Card>
+</CardGroup>
+
+## Architecture
+
+[NiceEval](https://niceeval.com/) supports two integration modes, depending on whether the subject under test needs an isolated workspace.
+
+### Mode 1: Sandbox
+
+Run coding agents such as Codex and Claude Code that need a sandbox:
+
+```text
+   evals/*.eval.ts
+        |
+        v
+   ┌────────────┐
+   │  niceeval  │
+   └────────────┘
+        |
+        | Agent adapter (official)
+        v
+   ┌───────────────────────────────┐
+   │        Docker Sandbox         │
+   │    ┌───────────────────────┐  │
+   │    │ Codex / Claude Code / │  │
+   │    │   apps that need an   │  │
+   │    │  isolated workspace   │  │
+   │    └───────────────────────┘  │
+   └───────────────────────────────┘
+```
+
+### Mode 2: Direct
+
+Connect directly to your own AI agent:
+
+```text
+   evals/*.eval.ts
+        |
+        v
+   ┌────────────┐
+   │  niceeval  │
+   └────────────┘
+        |
+        | Agent adapter (official / custom)
+        v
+   ┌────────────────────────────┐
+   │   Your own AI agent app    │
+   │ (AI SDK · LangGraph · Pi · │
+   │  custom agent loop, etc.)  │
+   └────────────────────────────┘
+```
+
+- **[NiceEval](https://niceeval.com/) core** handles eval discovery, scheduling, scoring, reporting, and artifacts.
+- **Agent adapters** are the open boundary: you decide how to call the subject under test and how to map its output into the standard event stream.
+- **Sandbox** handles file-system isolation: coding agents that need a real workspace use Docker or a cloud sandbox; direct web agents do not need Docker.
+
+## Core Concepts
+
+| Concept | In one sentence |
+|---|---|
+| [Eval](/concepts/evals) | A test case: written in `evals/*.eval.ts`, describing what to verify. |
+| [Experiment](/concepts/experiment) | A check-in-able run configuration: decides which adapter, model, and flags to use. |
+| [Adapter](/concepts/adapter) | The connection layer for the subject under test: implements `send` and translates responses into the standard event stream. |
+| [Sandbox](/guides/sandbox-backends) | Needed only for coding agents that require isolated workspaces; direct web agents do not need one. |
+| [Tier](/concepts/tier) | Three investment levels for adapter integration: Tier 1 only connects `send`, Tier 2 adds OTel for call waterfalls, and Tier 3 makes invasive changes for feature A/B tests. |
+
+See [Architecture Overview](/concepts/overview) for the full terminology map.
+
+## Examples
+
+To run one eval you need two files: the eval itself (what to test) and an experiment (which agent to run). The CLI does not accept a bare eval ID. In `niceeval exp <experiment> <eval-prefix>`, the experiment decides which subject gets connected. Here is a real direct web-agent scenario from `examples/zh/ai-sdk/`: verify that the agent calls a tool for a live weather question and answers from the tool result instead of inventing one.
+
+```ts
+// evals/weather-tool.eval.ts
+import { defineEval } from "niceeval";
+
+export default defineEval({
+  description: "Verify that the agent calls the weather tool and answers from the tool result",
+
+  async test(t) {
+    const turn = await t.send("What's the weather like in Beijing today?");
+    turn.succeeded();
+
+    await t.group("Calls get_weather with the right city", () => {
+      t.calledTool("get_weather", { input: { city: "Beijing" } });
+      t.messageIncludes(/°C|temperature|weather|sunny|cloudy|rain/i);
+    });
+
+    t.judge.autoevals
+      .closedQA("Does the assistant answer from the returned weather data instead of inventing a temperature?")
+      .atLeast(0.7);
+  },
+});
+```
+
+```ts
+// experiments/local.ts
+import { defineExperiment } from "niceeval";
+import { webAgent } from "./adapter"; // Your adapter for the web agent under test.
+
+export default defineExperiment({
+  agent: webAgent({ baseUrl: "http://127.0.0.1:5188" }),
+  model: "gpt-5.4",
+});
+```
+
+```sh
+npx niceeval exp local weather-tool
+npx niceeval view
+```
+
+If the subject under test is a coding agent that needs an isolated workspace, such as Codex or a Claude Code plugin / Skill, use `t.sandbox.uploadDirectory()` to lay down the workspace, `t.sandbox.fileChanged()` / `t.sandbox.file()` to inspect changes, and `t.sandbox.runCommand()` to run tests. See `examples/zh/coding-agent-skill/` in the repository.
+
+## Quickstart
+
+If you want a coding agent to integrate [NiceEval](https://niceeval.com/) into the project for you, hand it the matching scenario page:
+
+```text
+READ https://raw.githubusercontent.com/CorrectRoadH/niceeval/refs/heads/main/docs-site/zh/example/claude-code-codex-plugin.mdx and install niceeval for this repo.
+READ https://raw.githubusercontent.com/CorrectRoadH/niceeval/refs/heads/main/docs-site/zh/example/claude-code-codex-skill.mdx and install niceeval for this repo.
+READ https://raw.githubusercontent.com/CorrectRoadH/niceeval/refs/heads/main/docs-site/zh/example/ai-agent-application.mdx and install niceeval for this repo.
+```
+
+<CardGroup cols={3}>
+  <Card title="Eval your Claude Code / Codex plugin" icon="plug" href="/example/claude-code-codex-plugin">
+    Start from a real plugin task, upload a workspace, inject the plugin, and use pass rate to see whether it works reliably.
+  </Card>
+  <Card title="Eval your Claude Code / Codex Skill" icon="wand-magic-sparkles" href="/example/claude-code-codex-skill">
+    Verify that the Skill is loaded, uses tools as intended, and produces testable outcomes.
+  </Card>
+  <Card title="Eval your AI agent application" icon="globe" href="/example/ai-agent-application">
+    Wrap your app interface and write assertions over conversations, tool calls, structured outputs, and cost.
+  </Card>
+</CardGroup>
+
+## FAQ
+
+<AccordionGroup>
+  <Accordion title="Do I need to create an account?">
+    No. Running evals and inspecting reports with `niceeval view` happens locally. Docker or E2B-style sandbox backends are only needed when the subject under test is a coding agent that needs an isolated workspace.
+  </Accordion>
+  <Accordion title="Can I connect an agent that is not written in TypeScript or JavaScript?">
+    Yes. An adapter only sends to and receives from the interface your app already exposes, such as HTTP, gRPC, or WebSocket. [NiceEval](https://niceeval.com/) does not care which language your app is written in or where it is deployed. See [Adapter](/concepts/adapter).
+  </Accordion>
+  <Accordion title="Can this run in CI?">
+    Yes. See [CI Integration](/guides/ci-integration).
+  </Accordion>
+</AccordionGroup>
+
+<Tip>
+  For the shortest path, read [Quickstart](/quickstart). To understand the boundaries first, read [Architecture Overview](/concepts/overview).
+</Tip>

package/docs-site/introduction.mdx

@@ -0,0 +1,141 @@
+---
+title: "NiceEval: an eval tool for agents"
+sidebarTitle: "Introduction"
+description: "NiceEval helps teams measure, evaluate, and improve AI in production: compare models, iterate on agents, catch regressions, and improve with real data."
+---
+
+[NiceEval](https://niceeval.com/) is an agent eval tool that helps teams measure, evaluate, and improve AI in production. With NiceEval, teams can compare models, iterate on agents, catch regressions, and keep improving their AI applications using real user data. It aims for low-friction DX: most projects can integrate in about 10 minutes, write the first eval, and start checking agent behavior reliably.
+
+NiceEval is local-first at its core: your evals run in your own environment, so you don't need to create an account or connect to a platform before running your first eval. When your team needs to share eval results or track regressions, you can push a Report to platforms like BrainTrust, or export a custom report.
+
+It can evaluate coding-agent plugins, hooks, and Skills for Claude Code / Codex, and it can also evaluate your own AI agent application directly. Whether your agent is built on AI SDK, LangGraph, Pi, or a custom loop, you can connect it through an Adapter into the same eval surface.
+
+## 30 seconds of DX
+
+An eval is just a TypeScript file: send the agent a message, assert on what it did.
+
+```ts
+// evals/eval-tool-call.eval.ts
+import { defineEval } from "niceeval";
+
+export default defineEval({
+  description: "Verify the agent calls the weather tool and answers from its result",
+
+  async test(t) {
+    const turn = await t.send("What's the weather in Beijing today?");
+    t.succeeded();
+
+    await t.group("calls get_weather with the right city", () => {
+      t.calledTool("get_weather", { input: { city: "Beijing" } });
+      t.messageIncludes(/°C|sunny|cloudy|rain/);
+    });
+
+    const second = await t.send("What about Shanghai tomorrow?");
+    second.messageIncludes("Shanghai");
+
+    t.judge.autoevals
+      .closedQA("Does the reply use the tool's weather data instead of making up a temperature?")
+      .atLeast(0.7);
+  },
+});
+```
+
+```sh
+pnpm exec niceeval exp local eval-tool-call  # run only eval-tool-call under the local experiment
+pnpm exec niceeval view                      # view eval results
+```
+
+## Why NiceEval when DeepEval, LangFuse, and BrainTrust already exist
+
+NiceEval is an Agent-Native eval tool. The Dataset / golden pattern of building an Input and an Expected Output doesn't fit real agent evaluation — agents today need to be checked at a finer grain: multi-turn conversations, multi-agent collaboration, tool calls, skill loading. NiceEval is designed for exactly that: assertions land directly on tool calls, message content, structured output, and usage, instead of requiring you to hand-build a golden dataset first.
+
+Tools like Langfuse and Braintrust lean more toward tracing and observability. For the path of "write evals, run evals, inspect results", that is often heavier than necessary. NiceEval is designed around that path from the start, with a simpler developer experience. The two aren't mutually exclusive either: NiceEval coexists with LangFuse and BrainTrust — use them for tracing, or upload eval results to both.
+
+## What you can evaluate
+
+<CardGroup cols={2}>
+  <Card title="Coding agents" icon="code">
+    Put Claude Code, Codex, or bub into a sandbox, give them a task, then verify the result with real tests and file assertions.
+  </Card>
+  <Card title="Your own AI agent application" icon="globe">
+    Connect to your app directly and assert on replies, tool calls, and structured outputs.
+  </Card>
+</CardGroup>
+
+## Two integration modes
+
+<Tabs>
+  <Tab title="Sandbox mode">
+    Fits coding agents such as Codex and Claude Code that need a real file system and command execution.
+
+    ```text
+       evals/*.eval.ts
+            │
+            ▼
+       ┌────────────┐
+       │  niceeval  │
+       └────────────┘
+            │
+            │ Adapter (official)
+            ▼
+       ┌───────────────────────────────┐
+       │        Docker Sandbox         │
+       │    ┌───────────────────────┐  │
+       │    │ Codex / Claude Code / │  │
+       │    │  apps that need an    │  │
+       │    │  isolated workspace   │  │
+       │    └───────────────────────┘  │
+       └───────────────────────────────┘
+    ```
+  </Tab>
+  <Tab title="Direct mode">
+    Fits your own AI agent app and does not require Docker.
+
+    ```text
+       evals/*.eval.ts
+            │
+            ▼
+       ┌────────────┐
+       │  niceeval  │
+       └────────────┘
+            │
+            │ Adapter (official or custom)
+            ▼
+       ┌────────────────────────────┐
+       │   Your own AI agent app    │
+       │ (AI SDK · LangGraph · Pi · │
+       │  custom agent loop, etc.)  │
+       └────────────────────────────┘
+    ```
+  </Tab>
+</Tabs>
+
+## Core concepts at a glance
+
+| Concept | In one line |
+|---|---|
+| Eval | A test case: written in `evals/*.eval.ts`, describing what to check. |
+| Experiment | A checked-in run configuration: which Adapter, which model, which flags. |
+| Adapter | The layer that connects to the system under test: implement one `send`, get back a standard event stream. |
+| Sandbox | Only needed for coding agents that require an isolated workspace; a direct web agent doesn't need one. |
+| Tier | Three levels of Adapter integration effort: Tier 1 wires up `send` only, Tier 2 adds OTel for a call waterfall, Tier 3 makes invasive changes for feature A/B testing. |
+
+See the full glossary in the [architecture overview](/concepts/overview).
+
+## Start from your scenario
+
+<CardGroup cols={3}>
+  <Card title="Evaluate a Claude Code / Codex plugin" icon="puzzle-piece" href="/example/claude-code-codex-plugin">
+    Drop the plugin into a real workspace and compare pass rate, cost, latency, and behavior with and without it.
+  </Card>
+  <Card title="Evaluate a Claude Code / Codex Skill" icon="wand-magic-sparkles" href="/example/claude-code-codex-skill">
+    Compare coding-agent tasks with and without the Skill to measure whether it actually improves results.
+  </Card>
+  <Card title="Evaluate your own AI agent application" icon="robot" href="/example/ai-agent-application">
+    Connect directly to your app's API and assert on tool calls, image understanding, and multi-turn conversations.
+  </Card>
+</CardGroup>
+
+## What to read next
+
+[Quickstart](/quickstart) walks through installation, writing the first eval, and getting a report.

package/docs-site/quickstart.mdx

@@ -0,0 +1,136 @@
+---
+title: "Set up evals for your agent project"
+sidebarTitle: "Quickstart"
+description: "Install NiceEval, write three files, and run the first eval against your own application in about 10 minutes."
+---
+
+Connecting your own application takes three files: an **adapter** that calls your app, an **experiment** that chooses what to run, and an **eval** that declares what must be true. Below is the shortest complete path. Scenario-specific guides and the coding-agent handoff path come after it.
+
+## Let AI wire it up for you (recommended)
+
+<Steps>
+  <Step title="Install">
+    ```text
+    READ https://niceeval.com/INIT.md and install niceeval for this repo.
+    ```
+  </Step>
+  <Step title="Run evals">
+    ```bash
+    pnpm exec niceeval exp <experiment-name>
+    ```
+  </Step>
+  <Step title="View results">
+    ```bash
+    pnpm exec niceeval view
+    ```
+  </Step>
+</Steps>
+
+## Manual integration
+
+```bash
+pnpm add -D niceeval
+pnpm exec niceeval init
+```
+
+### Adapter
+
+The adapter is the layer between your agent and NiceEval. There are multiple integration tiers, from non-invasive to partially instrumented, which unlock more useful eval features. See [Tier](/concepts/tier).
+
+```ts
+// agents/my-bot.ts
+import { defineAgent } from "niceeval/adapter";
+
+export default defineAgent({
+  name: "my-bot",
+  async send(input, ctx) {
+    const r = await fetch("http://localhost:3000/chat", {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ message: input.text, model: ctx.model }),
+      signal: ctx.signal,
+    });
+    const body = await r.json();
+    return {
+      status: r.ok ? "completed" : "failed",
+      events: [{ type: "message", role: "assistant", text: body.reply }],
+    };
+  },
+});
+```
+
+### Experiment
+
+```ts
+// experiments/my-bot.ts
+import { defineExperiment } from "niceeval";
+import myBot from "../agents/my-bot.ts";
+
+export default defineExperiment({
+  description: "my-bot baseline",
+  model: "gpt-4o",
+  agent: myBot,
+  runs: 1,
+});
+```
+
+### Eval
+
+```ts
+// evals/refund-policy.eval.ts
+import { defineEval } from "niceeval";
+import { includes } from "niceeval/expect";
+
+export default defineEval({
+  description: "Refund policy question",
+  async test(t) {
+    await t.send("What is your refund policy?");
+    t.succeeded();
+    t.check(t.reply, includes("30 days"));
+  },
+});
+```
+
+```bash
+pnpm exec niceeval exp my-bot
+pnpm exec niceeval view
+```
+
+At this point the first eval is running.
+
+This minimal adapter is **single-turn**. The second turn will not remember the first until you teach the app how to continue conversation history. Multi-turn sessions, tool-call events that unlock `t.calledTool()`, HITL, and tracing are all optional increments you add later. Follow [Connect Your Agent](/guides/connect-your-agent) step by step. Existing evals do not need to be rewritten.
+
+## Start from a scenario
+
+If you already know what you want to evaluate, jump straight into the matching path:
+
+<CardGroup cols={3}>
+  <Card title="Eval your Claude Code / Codex plugin" icon="plug" href="/example/claude-code-codex-plugin">
+    For plugins, hooks, MCP servers, and project-level coding-agent extensions.
+  </Card>
+  <Card title="Eval your Claude Code / Codex Skill" icon="wand-magic-sparkles" href="/example/claude-code-codex-skill">
+    For verifying whether a Skill is triggered, follows the intended workflow, and genuinely improves task success.
+  </Card>
+  <Card title="Eval your AI agent application" icon="globe" href="/example/ai-agent-application">
+    For full examples built on AI SDK, LangGraph, Pi, or a custom agent app.
+  </Card>
+</CardGroup>
+
+## Put it in CI
+
+```yaml
+name: evals
+on: [pull_request]
+jobs:
+  evals:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+      - run: npm ci
+      - run: npm exec niceeval exp my-bot
+```
+
+<Tip>
+  Next, read [Authoring Evals](/guides/authoring) and [Scoring Guide](/guides/scoring-guide), then replace the example with your real behavior.
+</Tip>