@nzila/sdk 0.1.0 → 0.1.1

package/README.md

@@ -67,4 +67,15 @@ const nzila = traceNzilaFeature("Checkout");
 await nzila.runApi("charge", () => charge());
 ```
 
-See JSDoc on each export in `src/` and the monorepo guide [examples/COMPLEX-USAGE.md](../../examples/COMPLEX-USAGE.md).
+## Examples (included in this package)
+
+After install, open **`node_modules/@nzila/sdk/examples/`**:
+
+- **[INDEX.md](./examples/INDEX.md)** — map of all samples
+- **[COMPLEX-USAGE.md](./examples/COMPLEX-USAGE.md)** — every feature (Vitest, runtime, `mapFeature`, webhooks)
+- **[RUNTIME-TRACE.md](./examples/RUNTIME-TRACE.md)** — React + backend live tracing
+- **[TRACING-FAILURES.md](./examples/TRACING-FAILURES.md)** — tests → dashboard
+- Config: `vitest.config.example.ts`, `jest.config.example.cjs`, `mocharc.nzila.example.cjs`
+- Code: `backend/`, `frontend/`, `complex/`, `react/checkout-feature.example.tsx`
+
+All example imports use `@nzila/sdk` (same as your app).

package/examples/COMPLEX-USAGE.md

@@ -0,0 +1,113 @@
+# Complex usage — all Nzila SDK features
+
+This guide ties together **test webhooks**, **runtime signals**, **mapFeature**, and **manual error reporting** in one flow. Use it after the quick starts in [README.md](README.md), [TRACING-FAILURES.md](TRACING-FAILURES.md), and [RUNTIME-TRACE.md](RUNTIME-TRACE.md).
+
+## Feature matrix
+
+| Capability | API | When to use |
+|------------|-----|-------------|
+| CI test run | `NzilaVitestReporter` / `NzilaJestReporter` / Mocha | Every `vitest run` / Jest / Mocha finish |
+| Manual run POST | `sendNzilaRun(payload, { webhookUrl, apiKey })` | Custom runners, replay payloads |
+| Feature naming | `mapFeature(describePath, testName)` | Suite title ≠ dashboard feature |
+| Backend handler | `traceNzilaFeature("Checkout")` | First line of route/service |
+| React screen | `useNzilaFeature("Checkout")` | Top of component matching tests |
+| HTTP wrapper | `nzila.runApi("label", () => fetch…)` | Auto `api` success/failure |
+| Handled errors | `nzila.captureError(err, { … })` | `catch`, validation, business rules |
+| No handle in scope | `reportFeatureError("Checkout", err)` | Deep helper, fire-and-forget |
+| API failure label | `nzila.captureApiError(err, "payment.charge")` | After failed call outside `runApi` |
+| UI issues | `nzila.reportUi("custom_banner", { … })` | Non-throwing UX problems |
+| Render errors | `NzilaFeatureBoundary` + `useNzilaFeature` | Child tree throws |
+| Static demo payload | `shared/send-webhook.mjs` | No Vitest installed |
+
+Use the **same feature strings** everywhere (e.g. `"Checkout"`, `"Inventory"`) so test failures and runtime signals land on one dashboard row.
+
+## 1. Complex Vitest run (multi-feature, pass + fail)
+
+**Files:** `complex/full-platform.demo.test.ts`, `vitest.complex.config.ts`, `shared/feature-map.ts`
+
+- Three describe roots: `Checkout UI`, `Inventory`, `Authentication`
+- `mapFeature` maps UI vs API names via `resolveFrontendFeature` / `resolveBackendFeature`
+- Several tests **fail on purpose** so Nzila shows failure analysis
+
+```bash
+# .env.local: NZILA_API_KEY, NZILA_WEBHOOK_URL
+# Optional: NZILA_COMPLEX_APP_NAME=checkout-api (must exist in dashboard)
+npm run example:test:complex
+```
+
+Open **Runs** → latest run → failures grouped by feature.
+
+## 2. Complex backend runtime (runApi + capture + reportFeatureError)
+
+**File:** `complex/api-services.demo.ts`
+
+Demonstrates:
+
+1. `initNzilaRuntime({ signalsUrl, apiKey })`
+2. `traceNzilaFeature("Checkout")` with `runApi` for inventory + payment
+3. `captureError` for handled business failure (409)
+4. `captureApiError` for pipeline failure
+5. Second feature `Inventory` with `reportFeatureError` in a job
+
+```bash
+npm run example:runtime:complex
+```
+
+Wait ~1s for batched flush, then check **Feature health** / runtime signals for `Checkout` and `Inventory`.
+
+## 3. Tracing-only Vitest (focused failure fingerprints)
+
+```bash
+npm run example:test:tracing:all
+npm run example:webhook:tracing
+npm run example:webhook:tracing:frontend
+```
+
+## 4. React runtime (monorepo)
+
+See [RUNTIME-TRACE.md](RUNTIME-TRACE.md). Pattern:
+
+```tsx
+initNzilaRuntime({ signalsUrl, apiKey });
+
+function CheckoutPage() {
+  const nzila = useNzilaFeature("Checkout");
+  async function pay() {
+    try {
+      await nzila.runApi("checkout.submit", () =>
+        fetch("/api/checkout", { method: "POST" }),
+      );
+    } catch (e) {
+      nzila.captureError(e, { step: "submit" });
+    }
+  }
+  return (
+    <NzilaFeatureBoundary feature="Checkout" nzila={nzila}>
+      {/* children */}
+    </NzilaFeatureBoundary>
+  );
+}
+```
+
+## 5. Jest and Mocha
+
+- Jest: copy `jest.config.example.cjs` → wire `NzilaJestReporter` with same env vars as Vitest.
+- Mocha: `mocharc.nzila.example.cjs` — register reporter, call `sendNzilaRun` on `end` if you roll your own.
+
+## 6. End-to-end local checklist
+
+1. `npm run dev` + `npm run worker`
+2. Create app(s): `checkout-api`, `checkout-web` (or your `NZILA_COMPLEX_APP_NAME`)
+3. API key in `.env.local`
+4. `npm run example:test:complex` → webhook run
+5. `npm run example:runtime:complex` → runtime signals
+6. Dashboard: **Runs**, **Failures**, **Feature health** — same feature names
+
+## Environment reference
+
+| Variable | Used by |
+|----------|---------|
+| `NZILA_API_KEY` | Webhook + runtime |
+| `NZILA_WEBHOOK_URL` | Vitest/Jest reporters, `sendNzilaRun` |
+| `NZILA_SIGNALS_URL` | `initNzilaRuntime` (default `http://localhost:3000/api/signals/runtime`) |
+| `NZILA_COMPLEX_APP_NAME` | Complex Vitest config only |

package/examples/INDEX.md

@@ -0,0 +1,27 @@
+# @nzila/sdk examples
+
+These files ship inside the npm package under `node_modules/@nzila/sdk/examples/`.
+
+| Topic | Files |
+|-------|--------|
+| Overview | [README from monorepo](./README.md) |
+| All features walkthrough | [COMPLEX-USAGE.md](./COMPLEX-USAGE.md) |
+| Live app tracing | [RUNTIME-TRACE.md](./RUNTIME-TRACE.md) |
+| Test → dashboard mapping | [TRACING-FAILURES.md](./TRACING-FAILURES.md) |
+| Vitest | [vitest.config.example.ts](./vitest.config.example.ts), [complex/](./complex/) |
+| Jest | [jest.config.example.cjs](./jest.config.example.cjs) |
+| Mocha | [mocharc.nzila.example.cjs](./mocharc.nzila.example.cjs) |
+| Backend runtime | [backend/runtime-trace.example.ts](./backend/runtime-trace.example.ts), [complex/api-services.demo.ts](./complex/api-services.demo.ts) |
+| React | [react/checkout-feature.example.tsx](./react/checkout-feature.example.tsx) |
+| Manual webhook | [send-run-manual.mjs](./send-run-manual.mjs), [shared/send-webhook.mjs](./shared/send-webhook.mjs) |
+| Sample payloads | [backend/sample-payload.json](./backend/sample-payload.json), [frontend/sample-payload.json](./frontend/sample-payload.json) |
+
+## Environment
+
+```env
+NZILA_API_KEY=nzl_...
+NZILA_WEBHOOK_URL=https://your-host/api/webhooks/tests
+NZILA_SIGNALS_URL=https://your-host/api/signals/runtime
+```
+
+Imports in these files use `@nzila/sdk` — the same as in your application after `npm install @nzila/sdk`.

package/examples/README.md

@@ -0,0 +1,94 @@
+> **npm:** Start with [INDEX.md](./INDEX.md). Imports use `@nzila/sdk`.
+
+# Nzila integration examples
+
+End-to-end samples for **backend (API)** and **frontend (UI)** test flows.
+
+## Prerequisites
+
+1. `npm run dev` and `npm run worker` (with `QUEUE_DRIVER` and DB migrated).
+2. Register, create an API key at `/en/keys`.
+3. In **`.env.local`**:
+
+```env
+NZILA_API_KEY=nzl_...
+NZILA_WEBHOOK_URL=http://localhost:3000/api/webhooks/tests
+HF_API_TOKEN=hf_...          # optional, for AI summaries
+```
+
+The same examples are published inside **`@nzila/sdk`** at `node_modules/@nzila/sdk/examples/` (see `INDEX.md` there).
+
+## Layout
+
+| Path | Purpose |
+|------|---------|
+| `backend/` | API-style unit tests (pricing, inventory, auth) |
+| `frontend/` | UI logic tests (checkout form, product card) |
+| `shared/send-webhook.mjs` | POST static JSON payloads (CI / manual) |
+| `vitest.config.ts` | Vitest + Nzila reporter (fires webhook on finish) |
+| `jest.config.example.cjs` | Jest + NzilaJestReporter |
+| `mocharc.nzila.example.cjs` | Mocha reporter setup notes |
+| `@nzila/sdk` | Installed npm package (you are reading its `examples/` folder) |
+
+Each suite includes **passing and failing** tests so the dashboard shows real failure analysis.
+
+## Trace failures (tests → dashboard)
+
+See **[TRACING-FAILURES.md](TRACING-FAILURES.md)** for how `describe()` paths, fingerprints, and `errors[]` map to **Runs**, **Failures**, and **Feature health**.
+
+## Complex usage (all features)
+
+See **[COMPLEX-USAGE.md](COMPLEX-USAGE.md)** for a single walkthrough: multi-feature Vitest, `mapFeature`, runtime `runApi` / `captureError`, Jest/Mocha, and env vars.
+
+```bash
+npm run example:test:complex      # Vitest: Checkout UI + Inventory + Auth (pass/fail)
+npm run example:runtime:complex   # Backend: traceNzilaFeature + reportFeatureError
+```
+
+## Runtime trace (live app → Feature health)
+
+See **[RUNTIME-TRACE.md](RUNTIME-TRACE.md)** for `useNzilaFeature` (React), `traceNzilaFeature` (backend), and **`captureError` / `reportFeatureError`** when you handle errors yourself.
+
+Example backend handler: `backend/runtime-trace.example.ts`. Heavier demo: `complex/api-services.demo.ts`.
+
+Quick demo (Vitest only):
+
+```bash
+npm run example:test:tracing      # Vitest → webhook
+npm run example:webhook:tracing   # static JSON payload
+```
+
+## Run Vitest (sends one webhook per run)
+
+```bash
+# All examples (mixed app name: nzila-demo)
+npm run example:test
+
+# Backend only → app name checkout-api
+npm run example:test:backend
+
+# Frontend only → app name checkout-web
+npm run example:test:frontend
+```
+
+## Send sample payloads (no Vitest)
+
+```bash
+npm run example:webhook:backend
+npm run example:webhook:frontend
+npm run example:webhook          # both
+```
+
+## Full local demo
+
+```bash
+npm run example:all              # vitest + both webhooks (needs dev + worker up)
+```
+
+## Server-side client
+
+Use `frontend-webhook-client.ts` from a Route Handler or CI job — not from browser bundles.
+
+## Payload contract
+
+See `backend/sample-payload.json`, `frontend/sample-payload.json`, and `src/lib/webhook-schema.ts`.

package/examples/RUNTIME-TRACE.md

@@ -0,0 +1,222 @@
+# Runtime feature tracing (`traceNzilaFeature` / `useNzilaFeature`)
+
+Pair **Vitest** failures (webhook) with **live** signals on the same **feature** name (e.g. `Checkout`). Call one function at the top of the UI component or backend handler that owns that feature; use **`captureError`** when you already handle errors.
+
+## SDK package exports
+
+| Import path | Use for |
+|-------------|---------|
+| `@nzila/sdk` | `initNzilaRuntime`, `traceNzilaFeature`, `reportFeatureError`, Vitest/Jest reporters |
+| `@nzila/sdk/react` | `useNzilaFeature`, `NzilaFeatureBoundary`, `reportFeatureError` |
+| `@nzila/sdk/runtime` | Low-level runtime client only |
+| `@nzila/sdk/vitest` | `NzilaVitestReporter` |
+
+---
+
+## Setup (once per app)
+
+```ts
+import { initNzilaRuntime } from "@nzila/sdk/runtime";
+// or: import { initNzilaRuntime } from "@nzila/sdk";
+
+initNzilaRuntime({
+  signalsUrl: process.env.NZILA_SIGNALS_URL!, // https://your-app.vercel.app/api/signals/runtime
+  apiKey: process.env.NZILA_API_KEY!,
+  locale: "en",
+  renderLoopThreshold: 40, // optional — React render-loop detection
+});
+```
+
+| Variable | Where |
+|----------|--------|
+| `NZILA_SIGNALS_URL` | Node / Route Handlers |
+| `NEXT_PUBLIC_NZILA_SIGNALS_URL` | Browser (Next.js) |
+| `NZILA_API_KEY` / `NEXT_PUBLIC_NZILA_API_KEY` | Same project key as test webhooks |
+
+Requires DB migration `0003_feature_intelligence.sql` (`npm run db:migrate`).
+
+---
+
+## API reference
+
+| Function | Signature | When to use |
+|----------|-----------|-------------|
+| `initNzilaRuntime` | `(config)` once | Before any trace calls |
+| `useNzilaFeature` | `(feature, options?)` | **Top of React component** |
+| `traceNzilaFeature` | `(feature)` | **Top of backend handler** |
+| `handle.captureError` | `(error, detail?)` | Your `try/catch`, toasts, form errors |
+| `handle.captureApiError` | `(error, label, detail?)` | Caught fetch/HTTP without `runApi` |
+| `handle.runApi` | `(label, fn)` | Wrap async API calls |
+| `handle.reportError` | same as `captureError` | Alias |
+| `reportFeatureError` | `(feature, error, detail?)` | Shared util; pass feature + error |
+| `captureFeatureError` | alias of `reportFeatureError` | |
+| `extractErrorFields` | `(error)` | `message`, `name`, `stack` normalization |
+
+Returned **handle** (from hook or `traceNzilaFeature`): `{ feature, runApi, captureError, captureApiError, reportError, reportUi }`.
+
+---
+
+## React — `useNzilaFeature` at the top of the component
+
+```tsx
+"use client";
+
+import { useNzilaFeature } from "@nzila/sdk/react";
+import { initNzilaRuntime } from "@nzila/sdk/react";
+
+// e.g. app/layout.tsx or instrumentation.ts (once)
+initNzilaRuntime({
+  signalsUrl: process.env.NEXT_PUBLIC_NZILA_SIGNALS_URL!,
+  apiKey: process.env.NEXT_PUBLIC_NZILA_API_KEY!,
+});
+
+export function CheckoutPage() {
+  const nzila = useNzilaFeature("Checkout"); // same feature as Vitest mapFeature
+
+  async function pay() {
+    await nzila.runApi("POST /api/checkout", () =>
+      fetch("/api/checkout", { method: "POST", body: "{}" }),
+    );
+  }
+
+  return <button onClick={() => void pay()}>Pay</button>;
+}
+```
+
+### Manual error handling (your `try/catch`)
+
+Use the handle from the hook (feature is already bound):
+
+```tsx
+export function CheckoutPage() {
+  const nzila = useNzilaFeature("Checkout");
+
+  async function pay() {
+    try {
+      await nzila.runApi("POST /api/checkout", () =>
+        fetch("/api/checkout", { method: "POST" }),
+      );
+    } catch (err) {
+      nzila.captureError(err, { step: "pay", handled: true });
+      // your toast / form error state
+    }
+  }
+}
+```
+
+Or pass **feature + error** from anywhere (e.g. shared error util):
+
+```ts
+import { reportFeatureError } from "@nzila/sdk/react";
+
+reportFeatureError("Checkout", error, { step: "validation" });
+```
+
+`captureError` uses `extractErrorFields` — works with `Error`, strings, and unknown values.
+
+### What is reported automatically
+
+| Issue | Signal `type` | `payload` notes |
+|-------|---------------|-----------------|
+| Too many re-renders in ~1s | `ui` | `kind: "render_loop"`, `renderCount` |
+| `window.onerror` | `error` | while component mounted |
+| Unhandled promise rejection | `error` | while mounted |
+| `runApi` failure | `api` | `success: false`, message |
+| `runApi` success | `api` | `success: true`, `label` |
+
+Optional error boundary:
+
+```tsx
+import { NzilaFeatureBoundary } from "@nzila/sdk/react";
+
+<NzilaFeatureBoundary feature="Checkout" nzila={nzila}>
+  <CheckoutForm />
+</NzilaFeatureBoundary>
+```
+
+---
+
+## Backend — `traceNzilaFeature` at the top of the handler
+
+```ts
+import { initNzilaRuntime, traceNzilaFeature } from "@nzila/sdk";
+
+initNzilaRuntime({
+  signalsUrl: process.env.NZILA_SIGNALS_URL!,
+  apiKey: process.env.NZILA_API_KEY!,
+});
+
+export async function postCheckout(req: Request) {
+  const nzila = traceNzilaFeature("Checkout");
+
+  try {
+    const upstream = await nzila.runApi("payment-gateway", () =>
+      fetch("https://api.example.com/charge", { method: "POST" }),
+    );
+    if (!upstream.ok) throw new Error(`charge failed: ${upstream.status}`);
+    return Response.json({ ok: true });
+  } catch (err) {
+    nzila.captureError(err, { route: "POST /checkout", handled: true });
+    return Response.json({ error: "payment_failed" }, { status: 502 });
+  }
+}
+```
+
+Caught an API error without `runApi`?
+
+```ts
+nzila.captureApiError(err, "payment-gateway", { status: 502 });
+```
+
+From a nested helper without the handle:
+
+```ts
+import { reportFeatureError } from "@nzila/sdk";
+
+reportFeatureError("Checkout", err, { layer: "inventory-service" });
+```
+
+Call **`traceNzilaFeature("Checkout")` as the first line** of the route/service that matches your tested feature.
+
+Repo example: [backend/runtime-trace.example.ts](./backend/runtime-trace.example.ts).
+
+---
+
+## Dashboard
+
+Open **Feature health** for the project — compare **tests** (from webhooks) with **runtime** (`api` / `ui` / `error` signals).
+
+Use the **same feature string** everywhere:
+
+| Source | Example |
+|--------|---------|
+| Vitest `describe` / `mapFeature` | `"Checkout"` |
+| `useNzilaFeature("…")` | `"Checkout"` |
+| `traceNzilaFeature("…")` | `"Checkout"` |
+| `reportFeatureError("…", err)` | `"Checkout"` |
+| Manual HTTP (advanced) | `POST /api/signals/runtime` |
+
+Test-side tracing: [TRACING-FAILURES.md](./TRACING-FAILURES.md).  
+Deploy (Vercel + Render): [../docs/DEPLOY-VERCEL-RENDER.md](../docs/DEPLOY-VERCEL-RENDER.md).
+
+---
+
+## Manual HTTP (optional)
+
+Same payload the SDK sends:
+
+```json
+{
+  "locale": "en",
+  "signals": [
+    {
+      "feature": "Checkout",
+      "type": "error",
+      "success": false,
+      "payload": { "message": "card declined", "handled": true }
+    }
+  ]
+}
+```
+
+Types: `navigation`, `api`, `ui`, `error`, `custom`.

package/examples/TRACING-FAILURES.md

@@ -0,0 +1,186 @@
+# Tracing test failures in Nzila
+
+How failures move from **backend** and **frontend** test runs into the dashboard, how to **attach tests to a feature**, and how to trace an error even when the test was already in your suite.
+
+## Mental model
+
+```text
+describe() tree  →  describePath + fingerprint
+mapFeature / feature field  →  dashboard "Feature" column
+test name        →  human label
+errors[]         →  processed into Failure analysis (not raw stacks in UI)
+worker           →  summaries + feature health
+```
+
+1. Vitest finishes one run → reporter sends **one** webhook (`runId` is idempotent).
+2. Each test becomes a row with `describePath`, `feature`, `testName`, `status`, `errors`.
+3. The worker enriches failures and updates **Stability**, **Failures**, and **Feature health**.
+
+## Developer setup (one-time)
+
+### 1. Run Nzila locally
+
+From the repo root (see [README](../README.md)):
+
+```bash
+npm install
+cp .env.example .env.local   # fill DATABASE_URL, AUTH_SECRET, etc.
+npm run db:migrate
+npm run dev                  # http://localhost:3000
+npm run worker               # second terminal — processes webhooks
+```
+
+### 2. Create two projects (API + web)
+
+In the dashboard, create **two** projects so backend and frontend keys do not mix:
+
+| Project display name | **App name** (must match Vitest `appName`) | Example tests |
+|----------------------|------------------------------------------|---------------|
+| Checkout API         | `checkout-api`                           | `examples/backend/` |
+| Checkout Web         | `checkout-web`                           | `examples/frontend/` |
+
+For each project: **Settings → API keys** → create a key. You can use one key for both demos if both projects belong to your org and you switch `NZILA_API_KEY` when running each suite — separate keys are clearer.
+
+### 3. Configure `.env.local`
+
+```bash
+NZILA_WEBHOOK_URL=http://localhost:3000/api/webhooks/tests
+NZILA_API_KEY=nzl_your_key_for_checkout_api
+```
+
+For frontend tracing, use the **checkout-web** key (or change the key before `example:test:tracing:frontend`).
+
+### 4. Run tracing demos
+
+```bash
+npm run example:test:tracing:backend    # failures → checkout-api
+npm run example:test:tracing:frontend   # failures → checkout-web
+npm run example:test:tracing:all        # both
+```
+
+Tracing-only Vitest configs (reporter + `mapFeature`):
+
+- `examples/vitest.tracing.backend.config.ts`
+- `examples/vitest.tracing.frontend.config.ts`
+
+## Attach tests to a feature
+
+Nzila groups failures and health by **feature** string. You have three ways to set it:
+
+### A. Top-level `describe` name (default)
+
+The Vitest reporter uses the **first** `describe()` segment as `feature` unless you override with `mapFeature`.
+
+```ts
+describe("Checkout", () => {
+  it("should reject expired cards", () => { /* ... */ });
+});
+```
+
+→ `feature: "Checkout"`, fingerprint includes full `describePath`.
+
+### B. `mapFeature` in the reporter (recommended for UI vs product names)
+
+When suite titles are long (e.g. `"Checkout UI"`) but the product feature is `"Checkout"`, map them in config:
+
+```ts
+// examples/shared/feature-map.ts
+export function resolveFrontendFeature(describePath: string[], _testName: string) {
+  if (describePath[0] === "Checkout UI") return "Checkout";
+  return describePath[0] ?? "general";
+}
+```
+
+Wire it in `NzilaVitestReporter({ mapFeature: resolveFrontendFeature, ... })`.
+
+### C. Explicit `feature` in webhook JSON
+
+For manual/CI payloads, set `feature` on each test (see `examples/backend/sample-tracing-payload.json` and `examples/frontend/sample-tracing-payload.json`):
+
+```json
+{
+  "describePath": ["Checkout UI", "email field"],
+  "feature": "Checkout",
+  "testName": "should reject malformed email addresses",
+  "status": "failed",
+  "errors": [{ "message": "...", "stack": "..." }]
+}
+```
+
+Server fallback: `feature ?? describePath[0] ?? "general"` (`ensureTestCase`).
+
+**Runtime signals** should use the **same** feature string so **Feature health** lines up tests and production.
+
+**Recommended (live app):** use the SDK so production matches tests:
+
+| Layer | Call at top of unit | Manual `catch` |
+|-------|---------------------|----------------|
+| React | `const nzila = useNzilaFeature("Checkout")` | `nzila.captureError(err, { … })` |
+| Backend | `const nzila = traceNzilaFeature("Checkout")` | `nzila.captureError(err, { … })` |
+| Either | — | `reportFeatureError("Checkout", err, { … })` |
+
+Auto-reported: render loops (`ui`), `runApi` failures (`api`), unhandled window errors. Full API: **[RUNTIME-TRACE.md](./RUNTIME-TRACE.md)**.
+
+## Example suites
+
+| Layer | File | App name | Script |
+|-------|------|----------|--------|
+| Backend | `examples/backend/error-tracing.test.ts` | `checkout-api` | `npm run example:test:tracing:backend` |
+| Frontend | `examples/frontend/error-tracing.test.ts` | `checkout-web` | `npm run example:test:tracing:frontend` |
+
+Failures are intentional so you can practice tracing without breaking production code paths.
+
+## Trace a failure after tests ran (even with tests in CI)
+
+Tests passing or failing does not block tracing: each **run** is stored with per-test `errors`. When a test **fails** (or starts failing in a new run):
+
+1. **Test runs** (`/en/runs`) — open the latest run for `checkout-api` or `checkout-web`.
+2. **Failure analysis** (`/en/failures`) — read processed summaries (from `errors[].message`, not raw stacks).
+3. **Feature insights** / **Feature health** — filter by the same `feature` you attached in the suite or payload.
+4. **Code** — match **fingerprint**: `describePath[0] › … › testName` (same `describe` + `it` names as in repo).
+
+Optional: send runtime signals for the same feature and compare on **Feature health**.
+
+## Manual webhook (no Vitest)
+
+```bash
+npm run example:webhook:tracing           # backend sample
+npm run example:webhook:tracing:frontend  # frontend sample
+```
+
+Requires `NZILA_API_KEY` and `NZILA_WEBHOOK_URL` in `.env.local` (script loads env via `send-webhook.mjs`).
+
+## Webhook error fields
+
+Per test in `tests[]`:
+
+```json
+{
+  "describePath": ["Checkout", "Payment"],
+  "feature": "Checkout",
+  "testName": "should reject expired cards",
+  "status": "failed",
+  "duration": 42,
+  "errors": [
+    { "message": "expected false to be true", "stack": "AssertionError: ..." }
+  ]
+}
+```
+
+- **message** — drives operator-facing copy after processing.
+- **stack** — optional; used server-side, not shown as-is on **Failures**.
+
+## Related files
+
+| File | Role |
+|------|------|
+| `examples/shared/feature-map.ts` | Backend/frontend feature mapping |
+| `@nzila/sdk/vitest-reporter.ts` | Vitest → webhook + `mapFeature` |
+| `src/lib/webhook-schema.ts` | Payload validation |
+| `src/server/test-cases.ts` | `feature` resolution |
+| `src/server/process-run.ts` | Worker enrichment |
+| `examples/TRACING-FAILURES.md` | This guide (tests) |
+| `examples/RUNTIME-TRACE.md` | Live `useNzilaFeature`, `captureError` |
+| `examples/backend/runtime-trace.example.ts` | Backend handler sample |
+| `@nzila/sdk/runtime/` | Runtime client |
+| `@nzila/sdk/react/` | React hook + boundary |