@vitronai/themis 1.2.1 → 1.2.2

package/README.md

@@ -7,15 +7,17 @@
   </a>
 </p>
 
-**A Node.js and TypeScript unit test framework designed for AI coding agents.**
+**A unit test framework built for AI coding agents.**
 
-Themis is a drop-in alternative to Jest and Vitest, built for the way code gets written today: humans and agents working the same edit-test-fix loop. Strict phase semantics keep generated tests legible, machine-readable failure output lets agents self-repair, and an incremental migration path means you don't rewrite your suite on day one.
+Drop-in alternative to Jest and Vitest. Agents write tests, get structured failure output, and self-repair — all in the same edit-test-fix loop.
 
-- **Faster than Jest and Vitest** — `68.59%` faster than Vitest and `130.26%` faster than Jest on the same React showcase benchmark ([proof](#performance-proof))
-- **Agent-native output** — `--agent` JSON with failure clusters and structured repair hints, ready to feed back into Claude Code, Cursor, Codex, or any agent loop
-- **One-command migration** — `npx themis migrate jest` or `npx themis migrate vitest` with codemods and a structured findings report
-- **Modern by default** — native `.js`, `.jsx`, `.ts`, `.tsx`, ESM, JSX, and React Testing Library, no config gymnastics
-- **Discoverable to agents** — ships an `AGENTS.md` template, a `themis.ai.json` manifest, and a [Tessl tile](tessl/tile.json) so AI assistants can find and adopt it without you copy-pasting docs
+- **Faster** — 68.59% faster than Vitest, 130.26% faster than Jest on the same benchmark ([proof](#performance))
+- **Agent-native** — `--agent` JSON with failure clusters and structured repair hints
+- **One-command migration** — `npx themis migrate jest` or `vitest` with codemods
+- **Modern by default** — `.ts`, `.tsx`, `.js`, `.jsx`, ESM, React Testing Library, no config gymnastics
+- **Discoverable** — ships `AGENTS.md`, `themis.ai.json`, and a [Tessl tile](tessl/tile.json) so agents find and adopt it automatically
+
+---
 
 ## Quickstart
 
@@ -26,350 +28,51 @@ npx themis generate src     # or `app` for Next App Router repos
 npx themis test
 ```
 
-`init --agents` writes `themis.config.json`, updates `.gitignore`, and scaffolds a downstream `AGENTS.md` so the agents on your team know how to use it. See the [agent adoption guide](docs/agents-adoption.md) for the full setup, including migration from Jest or Vitest.
-
-**Using Claude Code?** Run `npx themis init --claude-code` to install a `CLAUDE.md`, a Claude Code skill at `.claude/skills/themis/`, and slash commands (`/themis-test`, `/themis-generate`, `/themis-migrate`, `/themis-fix`) wired to the agent-readable test loop. See [Claude Code one-command setup](docs/agents-adoption.md#claude-code-one-command-setup).
-
-- machine-readable agent manifest: [`themis.ai.json`](themis.ai.json)
-- copyable downstream rules file: [`templates/AGENTS.themis.md`](templates/AGENTS.themis.md)
-
-<p align="center">
-  <img src="src/assets/themisVerdictEngine.png" alt="Themis verdict engine art" width="960">
-</p>
-
-## Contents
-
-- [Quickstart](#quickstart)
-- [Adopt In Another Repo](#adopt-in-another-repo)
-- [Code Scan](#code-scan)
-- [Positioning](#positioning)
-- [Performance Proof](#performance-proof)
-- [Modern JS/TS Support](#modern-jsts-support)
-- [Commands](#commands)
-- [Agent Guide](#agent-guide)
-- [VS Code](#vs-code)
-- [Mocks And UI Primitives](#mocks-and-ui-primitives)
-- [Intent Syntax](#intent-syntax)
-- [Config](#config)
-- [TypeScript](#typescript)
-- [Benchmark](#benchmark)
-- [Publish Readiness](#publish-readiness)
-- [Agent Adoption Guide](docs/agents-adoption.md)
-- [Why Themis](docs/why-themis.md)
-- [API Reference](docs/api.md)
-- [Showcase Comparisons](docs/showcases.md)
-- [Release Policy](docs/release-policy.md)
-- [Publish Guide](docs/publish.md)
-
-## Positioning
-
-- Best-in-class unit testing for AI agents in Node.js and TypeScript
-- Deterministic execution with fast rerun loops
-- Agent-native JSON and HTML reporting
-- Structured contract workflows instead of opaque snapshot files
-- Incremental migration path from Jest/Vitest without rewriting everything on day one
-- AI verdict engine for human triage and machine automation
-
-## Performance Proof
-
-On the current same-host React showcase benchmark sample, Themis measured `68.59%` faster than Vitest and `130.26%` faster than Jest on median wall-clock time for the same two-spec suite.
-
-The exact comparison artifact is emitted by CI as `.themis/benchmarks/showcase-comparison/perf-summary.json` and `.themis/benchmarks/showcase-comparison/perf-summary.md`. Treat those percentages as the current documented sample, not a universal constant for every environment.
-
-### First-Try Test Pass Rate
-
-The first-try benchmark measures how often Claude generates tests that pass on the first run — the metric that matters most for agent-driven development. For each of 5 fixture source files (pure functions, async services, React components, hooks), Claude generates tests using Themis, Vitest, and Jest, and each generated suite is run once without edits.
-
-```bash
-ANTHROPIC_API_KEY=sk-... npm run benchmark:first-try
-```
-
-Results are written to `.themis/benchmarks/first-try/first-try-results.json` and `.themis/benchmarks/first-try/first-try-results.md`. The generated test code is saved under `.themis/benchmarks/first-try/generated-tests/` for manual review.
-
-Themis's advantage here comes from its `CLAUDE.md` template and Claude Code skill, which give Claude structured guidance about phase semantics, import conventions, and common pitfalls — context that Jest and Vitest users do not ship out of the box.
-
-## Modern JS/TS Support
-
-Themis is built for modern Node.js and TypeScript projects:
+`init --agents` writes config, updates `.gitignore`, and scaffolds a downstream `AGENTS.md`.
 
-- `.js`, `.jsx`, `.ts`, and `.tsx` support
-- ESM `.js` loading in `type: "module"` projects
-- `tsconfig` path alias resolution
-- `node` and `jsdom` environments
-- `setupFiles` for harness bootstrapping
-- `testIgnore` patterns for deterministic discovery boundaries
-- first-party mocks, spies, and deterministic UI primitives
-- compatibility imports for `@jest/globals`, `vitest`, and `@testing-library/react`
-- `--watch`, `--rerun-failed`, `--isolation in-process`, and `--cache` for tight local and agent rerun loops
+**Using Claude Code?** Run `npx themis init --claude-code` to install `CLAUDE.md`, a Claude Code skill, and slash commands (`/themis-test`, `/themis-generate`, `/themis-migrate`, `/themis-fix`).
 
-## Visuals
+---
 
-- Real Themis brand mark: [`src/assets/themisLogo.png`](src/assets/themisLogo.png)
-- Verdict engine art: [`src/assets/themisVerdictEngine.png`](src/assets/themisVerdictEngine.png)
-- HTML verdict report art: [`src/assets/themisReport.png`](src/assets/themisReport.png)
-- Background art used by the report: [`src/assets/themisBg.png`](src/assets/themisBg.png)
+## Performance
 
-## Adopt In Another Repo
+On the same React showcase benchmark, Themis measured **68.59% faster than Vitest** and **130.26% faster than Jest** on median wall-clock time. The comparison artifact is emitted by CI as `.themis/benchmarks/showcase-comparison/perf-summary.json`.
 
-Use the AI Quickstart above as the canonical install/generate/test flow. Replace `<source-root>` with the repo's actual source tree such as `src` or `app`. Generated files land under `__themis__/tests` by default. TypeScript-generated tests are emitted as strict-typecheckable artifacts and self-reference Themis globals so downstream TS projects do not need a special `types` override just to compile generated output.
-TypeScript-generated suites use `import` syntax so downstream ESLint and ESM-style rules do not flag Themis output as legacy `require(...)` code.
-
-If another repo wants its agents to reliably choose Themis, put the framework choice directly in that repo's agent instructions instead of assuming agents will infer it from package metadata alone.
-
-For a copy-paste downstream setup guide, see [`docs/agents-adoption.md`](docs/agents-adoption.md).
-
-For a ready-to-copy downstream agent rules file, see [`templates/AGENTS.themis.md`](templates/AGENTS.themis.md).
-
-Generate the next-gen HTML report:
-
-```bash
-npx themis test --reporter html
-```
-
-Use the AI-agent payload:
+The first-try benchmark measures how often an AI agent generates tests that pass on the first run — the metric that matters most for agent-driven development:
 
 ```bash
-npx themis test --agent
+ANTHROPIC_API_KEY=sk-... npm run benchmark:first-try
 ```
 
-Stay in a local rerun loop while editing:
+---
 
-```bash
-npx themis test --watch --isolation in-process --cache --reporter next
-```
+## How it works
 
-Incrementally migrate existing Jest/Vitest suites:
+### Plain English → structured tests
 
-```bash
-npx themis migrate jest
-npx themis migrate vitest
-npx themis migrate jest --rewrite-imports
-npx themis migrate vitest --rewrite-imports
-npx themis migrate jest --rewrite-imports --convert
-npx themis migrate vitest --rewrite-imports --convert
-npx themis test
-```
+```js
+intent('user can sign in', ({ context, run, verify, cleanup }) => {
+  context('a valid user', (ctx) => {
+    ctx.user = { email: 'a@b.com', password: 'pw' };
+  });
 
-## Code Scan
+  run('the user submits credentials', (ctx) => {
+    ctx.result = { ok: true };
+  });
 
-Themis can scan your JS/TS source tree and generate deterministic unit-layer tests for exported modules, React components, React hooks, Next app components, Next route handlers, generic route handlers, and Node services:
+  verify('authentication succeeds', (ctx) => {
+    expect(ctx.result.ok).toBe(true);
+  });
 
-```bash
-npx themis generate src
-npx themis test
+  cleanup('remove test state', (ctx) => {
+    delete ctx.user;
+  });
+});
 ```
 
-Generated files land under `__themis__/tests` by default. Each generated test:
-
-- checks the scanned export names when Themis can resolve them exactly
-- asserts the normalized runtime export contract directly in generated source
-- adds scenario adapters for React components/hooks, Next app/router files, route handlers, and service functions when Themis can infer or read useful inputs
-- captures React interaction and hook state-transition contracts when event handlers or stateful methods are available
-- asserts DOM-state and behavioral flow contracts directly for generated React and Next component adapters
-- emits async behavioral flow contracts for generated React and Next component adapters when flow plans are inferred or hinted, including richer inferred input/submit/loading/success paths for common async forms
-- supports provider-driven DOM flow contracts for empty, disabled, retry, error, and recovery states with attribute- and role-aware assertions
-- fails with a regeneration hint when the source drifts after the scan
-
-Themis also supports per-file generation hints with sidecars like `src/components/Button.themis.json` so humans and agents can provide props, component flows, args, route requests, and route context. When those sidecars do not exist yet, `--write-hints` can scaffold them automatically from the current source analysis.
-
-This is the core alternative to snapshot-driven testing: generated and hand-written tests assert normalized contracts in readable source, so diffs stay reviewable and updates stay intentional.
-
-For repo-wide generation defaults, add `themis.generate.js` or `themis.generate.cjs` at the project root. Providers in that file can match source paths, supply shared props/args/flow plans, register runtime mocks for generated UI scenarios, and wrap generated component renders so generated DOM contracts run inside the same provider shells humans use in app tests. Providers can also declare preset wrapper metadata for router, Next navigation, auth/session shells, React Query, Zustand, and Redux-style app state patterns, including route history/state, query status, auth permissions, and store selector/action metadata.
-
-For CI and agent loops, Themis can also enforce generation quality instead of only writing files. Strict runs emit a structured backlog, fail on unresolved scan debt, and hand back exact remediation commands.
-
-Use these flags to control the generation loop:
-
-- `--json`: machine-readable payload for agents, including prompt-ready next steps
-- `--plan`: alias for `--review --json` with persisted handoff artifacts
-- `--review`: dry-run create/update/remove decisions without writing files
-- `--update`: refresh existing generated files only
-- `--clean`: remove generated files for the selected scope
-- `--changed`: target changed files in a git worktree
-- `--write-hints`: scaffold missing `.themis.json` sidecars so the next generate pass has explicit component props, hook args, service args, and route requests
-- `--scenario`: limit generation to one adapter family such as `react-hook`, `next-app-component`, or `next-route-handler`
-- `--min-confidence`: keep only entries at or above a confidence threshold
-- `--strict`: fail the generate run on skips, conflicts, or entries below `high` confidence
-- `--fail-on-skips`, `--fail-on-conflicts`: turn unresolved scan debt into a non-zero exit code
-- `--require-confidence`: fail if selected generated tests fall below a confidence threshold
-- `--files`, `--match-source`, `--match-export`, `--include`, `--exclude`: narrow the scan scope
-- `--force`: replace a conflicting non-Themis file
-- `--output <dir>`: change the generated test directory
-
-Every generation run also writes:
-
-- `.themis/generate/generate-map.json`: source-to-generated-test mapping plus scenario/confidence metadata
-- `.themis/generate/generate-last.json`: the full machine-readable generate payload
-- `.themis/generate/generate-handoff.json`: a compact agent handoff artifact with prompt-ready next actions
-- `.themis/generate/generate-backlog.json`: unresolved skips, conflicts, and confidence debt with suggested fixes
-
-Local test loops can also opt into a zero IPC execution path:
-
-- `npx themis test --isolation in-process`: executes suites in-process instead of worker mode
-- `npx themis test --watch --isolation in-process --cache`: keeps a fast local rerun loop with file-level result caching
-- `npx themis test --isolation worker`: keeps process isolation for CI or global-heavy suites
-
-When generated tests fail, Themis also writes:
-
-- `.themis/runs/fix-handoff.json`: a deduped failure-to-fix artifact that maps generated failures back to source files, categories, repair strategies, candidate files, and remediation commands
+Phase names: `context`, `run`, `verify`, `cleanup`. Legacy aliases (`arrange/act/assert`, `given/when/then`) also supported.
 
-Repair generated suites with:
-
-```bash
-npx themis test --fix
-```
-
-`--fix` reads `.themis/runs/fix-handoff.json`, regenerates the affected source targets with `--update`, scaffolds hints when the repair strategy needs them, and reruns the suite.
-
-Migration scaffolds also write:
-
-- `.themis/migration/migration-report.json`: a machine-readable inventory of detected Jest/Vitest compatibility imports and recommended next actions
-- `themis.compat.js`: an optional local compatibility bridge used by `themis migrate --rewrite-imports`
-
-## Why Themis
-
-See [`docs/why-themis.md`](docs/why-themis.md) for positioning, differentiators, and community messaging.
-
-Short version:
-
-- Themis aims to deliver the benefits people reach for in snapshots, without snapshot rot.
-- Prefer explicit, normalized contracts over broad output dumps.
-- Keep changes reviewable through source assertions, machine-readable artifacts, and diff-oriented rerun workflows.
-- See [`docs/showcases.md`](docs/showcases.md) for direct Jest/Vitest comparison examples.
-
-## Reference Docs
-
-- API reference: [`docs/api.md`](docs/api.md)
-- Agent adoption guide: [`docs/agents-adoption.md`](docs/agents-adoption.md)
-- Migration guide: [`docs/migration.md`](docs/migration.md)
-- Release policy: [`docs/release-policy.md`](docs/release-policy.md)
-- Publish guide: [`docs/publish.md`](docs/publish.md)
-- VS Code extension notes: [`docs/vscode-extension.md`](docs/vscode-extension.md)
-- Agent result schema: [`docs/schemas/agent-result.v1.json`](docs/schemas/agent-result.v1.json)
-- Generate result schema: [`docs/schemas/generate-result.v1.json`](docs/schemas/generate-result.v1.json)
-- Generate map schema: [`docs/schemas/generate-map.v1.json`](docs/schemas/generate-map.v1.json)
-- Generate handoff schema: [`docs/schemas/generate-handoff.v1.json`](docs/schemas/generate-handoff.v1.json)
-- Generate backlog schema: [`docs/schemas/generate-backlog.v1.json`](docs/schemas/generate-backlog.v1.json)
-- Fix handoff schema: [`docs/schemas/fix-handoff.v1.json`](docs/schemas/fix-handoff.v1.json)
-- Failures artifact schema: [`docs/schemas/failures.v1.json`](docs/schemas/failures.v1.json)
-- Contract diff schema: [`docs/schemas/contract-diff.v1.json`](docs/schemas/contract-diff.v1.json)
-- Changelog: [`CHANGELOG.md`](CHANGELOG.md)
-
-## Commands
-
-- `npx themis init`: creates `themis.config.json`, adds `.themis/` to `.gitignore`, and adds `__themis__/reports/` plus `__themis__/shims/` to `.gitignore`.
-- `npx themis init --agents`: does the same and also writes a downstream `AGENTS.md` from the Themis template if the repo does not already have one.
-- `npx themis generate src`: scans source files and generates contract tests under `__themis__/tests`, using `.generated.test.ts` for TS/TSX sources and `.generated.test.js` for JS/JSX sources.
-- `npx themis generate src --json`: emits a machine-readable generation payload for agents and automation.
-- `npx themis generate src --plan`: emits a planning payload and handoff artifact without writing generated tests.
-- `npx themis generate src --review --json`: previews create/update/remove decisions without writing files.
-- `npx themis generate src --review --strict --json`: fails fast on unresolved generation debt while still emitting a machine-readable plan.
-- `npx themis generate src --write-hints`: scaffolds missing hint sidecars and uses them in the same generate pass.
-- `npx themis generate src --update`: refreshes existing generated tests only.
-- `npx themis generate src --clean`: removes generated tests for the selected scope.
-- `npx themis generate src --changed`: regenerates against changed files in the current git worktree.
-- `npx themis generate src --scenario react-hook --min-confidence high`: targets one adapter family at a confidence threshold.
-- `npx themis generate app --scenario next-route-handler`: focuses generation on Next app router request handlers.
-- `npx themis migrate jest`: scaffolds a Themis config/setup bridge for existing Jest suites and gitignores `.themis/` plus `__themis__/reports/` and `__themis__/shims/`.
-- `npx themis migrate jest --rewrite-imports`: rewrites matched Jest/Vitest/Testing Library imports to a local `themis.compat.js` bridge file.
-- `npx themis migrate jest --convert`: applies codemods for common Jest/Vitest matcher/import patterns so suites move closer to native Themis style.
-- `npx themis migrate vitest`: scaffolds the same bridge for Vitest suites and gitignores `.themis/` plus `__themis__/reports/` and `__themis__/shims/`.
-- `npx themis generate src --require-confidence high`: enforces a quality bar for all selected generated tests.
-- `npx themis generate src --files src/routes/ping.ts`: targets one or more explicit source files.
-- `npx themis generate src --match-source "routes/" --match-export "GET|POST"`: narrows generation by source path and exported symbol.
-- `npx themis generate src --output tests/contracts`: writes generated tests to a custom directory.
-- `npx themis generate src --force`: replaces conflicting files in the target output directory.
-- `npx themis test`: discovers and runs tests.
-- `npx themis test --next`: next-gen console output mode.
-- `npx themis test --json`: emits JSON result payload.
-- `npx themis test --agent`: emits AI-agent-oriented JSON schema.
-- `npx themis test --reporter html`: generates a next-gen HTML report file.
-- `npx themis test --reporter html --html-output reports/themis.html`: writes HTML report to a custom path.
-- `npx themis test --watch`: reruns the suite when watched project files change.
-- `npx themis test --watch --isolation in-process --cache`: runs a zero IPC cached local loop for fast edit/rerun cycles.
-- `npx themis test --workers 8`: overrides worker count (positive integer).
-- `npx themis test --isolation in-process`: runs test files in-process instead of worker processes.
-- `npx themis test --cache`: enables file-level result caching for in-process local loops.
-- `npx themis test --environment jsdom`: runs tests in a browser-like DOM environment.
-- `npx themis test --stability 3`: runs the suite three times and classifies each test as `stable_pass`, `stable_fail`, or `unstable`.
-- `npx themis test --match "intent DSL"`: runs only tests whose full name matches regex.
-- `npx themis test --rerun-failed`: reruns failing tests from `.themis/runs/failed-tests.json`.
-- `npx themis test --fix`: applies generated-test autofixes from `.themis/runs/fix-handoff.json` and reruns the suite.
-- `npx themis test --update-contracts --match "suite > case"`: accepts reviewed `captureContract(...)` changes for a narrow slice of the suite.
-- `npx themis test --no-memes`: disables meme phase aliases (`cook`, `yeet`, `vibecheck`, `wipe`).
-- `npx themis test --lexicon classic|themis`: rebrands human-readable status labels in `next/spec` reporters.
-- `npm run lint`: runs ESLint across the CLI, runtime, scripts, tests, and the VS Code extension scaffold.
-- `npm run validate`: runs lint, test, typecheck, and benchmark gate in one command.
-- `npm run typecheck`: validates TypeScript types for Themis globals and DSL contracts.
-- `npm run benchmark:gate`: fails when benchmark performance exceeds the configured threshold.
-- `npm run pack:check`: previews the npm publish payload.
-- `npm run proof:migration`: migrates checked-in Jest/Vitest fixture suites and proves they run cleanly under Themis.
-
-## CI & Release Proof
-
-- Lint job runs `npm run lint` on Node 20.
-- Compatibility job runs `npm test` on Node 18 and 20.
-- Release surface job runs `npm run typecheck`, `npm run pack:check`, the HTML + agent reports, verifies `.themis/diffs/contract-diff.json`, produces `.themis/benchmarks/benchmark-last.json`/`.themis/benchmarks/migration-proof.json`, and uploads all of the artifacts for later inspection.
-- Perf gate job runs `npm run benchmark:gate` with `BENCH_MAX_AVG_MS=2500` to guard against regressions before publishing.
-- Migration proof job runs `npm run proof:migration` against checked-in Jest/Vitest fixtures for basic suites, table tests, RTL/jsdom flows, timers, module mocking, and a context/provider-heavy RTL example, then uploads the resulting migration reports plus Themis run artifacts as evidence.
-- Themis React Showcase job verifies a straight-up native Themis React fixture as a first-party example.
-- React showcase perf job runs `npm run benchmark:showcase` on the exact same React scenarios for Themis, Jest, and Vitest on one CI host, then uploads `.themis/benchmarks/showcase-comparison/perf-summary.{json,md}` so the relative timing claim is backed by one comparable artifact.
-- Release `1.0.17` packages this expanded proof lane so every CI run now proves the provider-heavy example alongside the earlier fixtures.
-
-## Agent Guide
-
-[`AGENTS.md`](AGENTS.md) is the AI-agent contributor contract for this repository. It tells agents working on Themis itself how to write tests, preserve determinism, and update artifact contracts safely.
-
-It is not a package-discovery mechanism for every external repo. If another project wants its agents to use Themis, that project should say so in its own `AGENTS.md`, rules, or agent prompt.
-
-For downstream install, generation, and migration guidance, see [`docs/agents-adoption.md`](docs/agents-adoption.md).
-
-For a copyable downstream rules file, see [`templates/AGENTS.themis.md`](templates/AGENTS.themis.md).
-
-You do not need an MCP server just to make agents use Themis. Package metadata, docs, CLI commands, and explicit downstream repo instructions are the primary adoption path. An MCP integration could be useful later for richer editor or automation workflows, but it is optional.
-
-Themis writes artifacts under `.themis/`:
-
-- `.themis/runs/last-run.json`: full machine-readable run payload.
-- `.themis/runs/failed-tests.json`: compact failure list for retry loops.
-- `.themis/diffs/run-diff.json`: diff against the previous run, including new and resolved failures.
-- `.themis/runs/run-history.json`: rolling recent-run history for agent comparison loops.
-- `.themis/runs/fix-handoff.json`: source-oriented repair handoff for generated test failures.
-- `.themis/migration/migration-report.json`: compatibility inventory and next actions for migrated Jest/Vitest suites.
-- `.themis/diffs/contract-diff.json`: contract capture drift, updates, and update commands for `captureContract(...)` workflows.
-- `.themis/generate/generate-last.json`: latest machine-readable generate payload.
-- `.themis/generate/generate-map.json`: source-to-generated-test mapping.
-- `.themis/generate/generate-handoff.json`: prompt-ready generate handoff payload.
-- `.themis/generate/generate-backlog.json`: unresolved generate debt and suggested remediation.
-- `themis.compat.js`: optional local compat bridge for rewritten migration imports.
-- `.themis/benchmarks/benchmark-last.json`: latest benchmark comparison payload, including migration proof output.
-- `.themis/benchmarks/migration-proof.json`: synthetic migration-conversion proof artifact emitted by `npm run benchmark`.
-- `__themis__/reports/report.html`: interactive HTML verdict report.
-- `__themis__/shims/`: reserved namespace for framework-owned compatibility shims when a fallback file is truly needed. Themis should prefer built-in support first and should not drop ad hoc shim files into `tests/`.
-
-`--agent` output includes deterministic failure fingerprints, grouped `analysis.failureClusters`, stability classifications, previous-run comparison data, and a direct generated-test repair hint via `npx themis test --fix`. Fix handoff entries also carry repair strategies, candidate files, and autofix commands for tighter failure-to-fix loops.
-
-Machine-facing reporters intentionally emit compact JSON. Agents and tooling should parse the payloads rather than depend on whitespace formatting.
-
-The HTML reporter is designed for agent-adjacent review workflows too: it combines verdict status, slow-test surfacing, artifact navigation, and interactive file filtering in one report.
-
-## VS Code
-
-The repo now includes a thin VS Code extension scaffold at [`packages/themis-vscode`](packages/themis-vscode).
-
-The extension is intentionally artifact-driven:
-
-- reads `.themis/runs/last-run.json`, `.themis/runs/failed-tests.json`, `.themis/diffs/run-diff.json`, `.themis/generate/generate-last.json`, `.themis/generate/generate-map.json`, `.themis/generate/generate-backlog.json`, and `__themis__/reports/report.html`
-- shows the latest verdict and failures in a sidebar
-- adds generated-review navigation for source/test/hint mappings plus unresolved generation backlog
-- reruns Themis from VS Code commands
-- opens the HTML report inside a webview
-
-It does not replace the CLI. The CLI and `.themis/**` artifacts remain the source of truth.
-
-## Mocks And UI Primitives
-
-Themis now ships first-party test utilities for agent-generated tests:
+### Mocks and UI primitives
 
 ```js
 mock('../src/api', () => ({
@@ -378,121 +81,47 @@ mock('../src/api', () => ({
 
 const { fetchUser } = require('../src/api');
 
-test('captures a stable UI contract', () => {
+test('mock captures calls', () => {
   const user = fetchUser();
   expect(fetchUser).toHaveBeenCalledTimes(1);
   expect(user).toMatchObject({ id: 'u_1', name: 'Ada' });
 });
 ```
 
-Contract capture for reviewable baselines:
-
-```js
-test('captures a stable response contract', () => {
-  const payload = {
-    status: 'ok',
-    flags: ['fast', 'deterministic']
-  };
-
-  captureContract('status payload', payload);
-  expect(payload.status).toBe('ok');
-});
-```
-
-Themis intentionally avoids first-party snapshot-file workflows. Prefer direct assertions, generated contract tests, and explicit flow expectations over large opaque snapshots. The goal is comparable baseline coverage with better reviewability: normalized contracts, focused assertions, machine-readable artifacts, and intentional updates instead of broad snapshot re-acceptance.
-
-Available globals:
-
-- `fn(...)`
-- `spyOn(object, methodName)`
-- `mock(moduleId, factoryOrExports)`
-- `unmock(moduleId)`
-- `clearAllMocks()`
-- `resetAllMocks()`
-- `restoreAllMocks()`
+For `jsdom` tests, Themis ships `render`, `screen`, `fireEvent`, `waitFor`, `useFakeTimers`, `mockFetch`, and more. Full list in the [API reference](docs/api.md).
 
-For UI-oriented `jsdom` tests, Themis also ships a lightweight DOM layer:
+### Code generation
 
-- `render(ui)`
-- `screen.getByText(...)`
-- `screen.getByRole(...)`
-- `screen.getByLabelText(...)`
-- `fireEvent.click/change/input/submit/keyDown(...)`
-- `waitFor(asyncAssertion)`
-- `cleanup()`
-- `useFakeTimers()`, `advanceTimersByTime(ms)`, `runAllTimers()`, `useRealTimers()`
-- `flushMicrotasks()`
-- `mockFetch(...)`, `resetFetchMocks()`, `restoreFetch()`
+Themis scans your source tree and generates contract tests for exported modules, React components, hooks, Next.js routes, and services:
 
-Example:
-
-```tsx
-test('submits the form', async () => {
-  render(<button onClick={() => document.body.setAttribute('data-state', 'sent')}>Send</button>);
-
-  fireEvent.click(screen.getByRole('button', { name: 'Send' }));
-
-  await waitFor(() => {
-    expect(document.body).toHaveAttribute('data-state', 'sent');
-  });
-});
+```bash
+npx themis generate src
+npx themis test
 ```
 
-Network and async example:
+When generated tests fail:
 
-```ts
-test('loads api state deterministically', async () => {
-  useFakeTimers();
-  const fetchMock = mockFetch({ json: { ok: true } });
-
-  let done = false;
-  setTimeout(async () => {
-    const response = await fetch('/api/status');
-    const payload = await response.json();
-    done = payload.ok;
-  }, 50);
-
-  advanceTimersByTime(50);
-  await flushMicrotasks();
-
-  expect(done).toBe(true);
-  expect(fetchMock).toHaveBeenCalled();
-  useRealTimers();
-  restoreFetch();
-});
+```bash
+npx themis test --fix
 ```
 
-## Intent Syntax
-
-Themis supports a strict code-native intent DSL:
-
-```js
-intent('user can sign in', ({ context, run, verify, cleanup }) => {
-  context('a valid user', (ctx) => {
-    ctx.user = { email: 'a@b.com', password: 'pw' };
-  });
-
-  run('the user submits credentials', (ctx) => {
-    ctx.result = { ok: true };
-  });
+`--fix` regenerates affected targets and reruns the suite. See the [API reference](docs/api.md) for all generation flags (`--review`, `--plan`, `--write-hints`, `--strict`, `--changed`, etc.).
 
-  verify('authentication succeeds', (ctx) => {
-    expect(ctx.result.ok).toBe(true);
-  });
+### Migration
 
-  cleanup('remove test state', (ctx) => {
-    delete ctx.user;
-  });
-});
+```bash
+npx themis migrate jest
+npx themis migrate vitest
+npx themis test
 ```
 
-Preferred phase names are `context`, `run`, `verify`, `cleanup`.
-Legacy aliases are still supported (`arrange/act/assert`, `given/when/then`, `setup/infer/teardown`).
-Easter egg aliases are also available: `cook`, `yeet`, `vibecheck`, `wipe`.
+One command scaffolds a compatibility bridge. Add `--rewrite-imports` to rewrite import paths, `--convert` for codemods. See the [migration guide](docs/migration.md).
+
+---
 
 ## Config
 
-`themis.config.json`
+`themis.config.json`:
 
 ```json
 {
@@ -503,28 +132,15 @@ Easter egg aliases are also available: `cook`, `yeet`, `vibecheck`, `wipe`.
   "reporter": "next",
   "environment": "node",
   "setupFiles": ["tests/setup.ts"],
-  "tsconfigPath": "tsconfig.json",
-  "htmlReportPath": "__themis__/reports/report.html",
-  "testIgnore": ["^tests/fixtures(?:/|$)"]
+  "tsconfigPath": "tsconfig.json"
 }
 ```
 
-Modern JS/TS projects can opt into `environment: "jsdom"` for DOM-driven tests and `setupFiles` for hooks, polyfills, or harness bootstrapping.
-Themis discovers both `testDir` and `generatedTestsDir` by default. Use `testIgnore` only for fixture folders, scratch suites, or other paths you intentionally want to skip.
-Themis also stubs common frontend style and asset imports under Node or jsdom runs, including `.css`, `.scss`, `.png`, `.jpg`, `.svg`, and common font/media files, so repos should not need ad hoc `tests/*.cjs` setup files just to make those imports load.
-
-## TypeScript
-
-The package ships first-party typings for:
-
-- programmatic APIs (`collectAndRun`, `runTests`, config helpers)
-- global test APIs (`describe`, `test`, `intent`, hooks, `expect`)
-- typed intent context (`intent<MyCtx>(...)`)
-- project-aware module loading for `ts`, `tsx`, ESM `js`, `jsx`, `tsconfig` path aliases, and setup files
+Use `environment: "jsdom"` for DOM-driven tests. Themis auto-stubs common style/asset imports (`.css`, `.scss`, `.png`, `.svg`, etc.).
 
-Themis is designed to feel native in modern TypeScript projects without requiring a separate Babel or ts-node setup just to run tests.
+---
 
-Use the global types in your project with:
+## TypeScript
 
 ```json
 {
@@ -534,37 +150,35 @@ Use the global types in your project with:
 }
 ```
 
-## Benchmark
+Ships first-party typings for all test APIs, typed intent context, and project-aware module loading for `.ts`, `.tsx`, ESM `.js`, `.jsx`, and `tsconfig` path aliases.
 
-```bash
-npm run benchmark
-npm run benchmark:showcase
-npm run benchmark:gate
-```
+---
 
-Optional env vars:
+## Pair with Alethia
 
-- `BENCH_FILES` (default `40`)
-- `BENCH_TESTS_PER_FILE` (default `25`)
-- `BENCH_REPEATS` (default `3`)
-- `BENCH_WORKERS` (default `4`)
-- `BENCH_INCLUDE_EXTERNAL=1` to include Jest/Vitest/Bun comparisons
-- `BENCH_MAX_AVG_MS` to override the gate threshold
-- `BENCH_GATE_CONFIG` to point `benchmark:gate` at a custom config file
-- `SHOWCASE_BENCH_WARMUPS` (default `1`) for the same-spec React showcase comparison
-- `SHOWCASE_BENCH_REPEATS` (default `5`) for the same-spec React showcase comparison
+Themis owns the unit/contract layer. [Alethia](https://github.com/vitron-ai/alethia) owns the E2E/policy layer. Together they form the tightest test loop an autonomous coding agent can sit inside:
 
-The benchmark always runs Themis and will include Jest/Vitest/Bun only when they are available locally.
-The default gate profile and threshold live in `benchmark-gate.json`.
-The showcase benchmark writes `.themis/benchmarks/showcase-comparison/perf-summary.json` and `.themis/benchmarks/showcase-comparison/perf-summary.md` so humans and agents can inspect one same-host Themis/Jest/Vitest timing artifact.
+1. Agent generates code
+2. **Themis** verifies the contract in milliseconds
+3. **Alethia** verifies the running app in a real browser, under safety policy, with a signed audit trail
 
-## Publish Readiness
+Use Themis on its own — it's MIT and stands alone.
 
-Before publishing a release:
+---
 
-```bash
-npm run validate
-npm run pack:check
-```
+## Reference docs
+
+- [API reference](docs/api.md) — all CLI flags, globals, matchers, mocks, UI primitives
+- [Agent adoption guide](docs/agents-adoption.md) — downstream repo setup
+- [Migration guide](docs/migration.md) — Jest/Vitest migration details
+- [Why Themis](docs/why-themis.md) — positioning and differentiators
+- [Showcase comparisons](docs/showcases.md) — direct Jest/Vitest examples
+- [Tutorial: Testing with Claude Code](docs/tutorial-claude-code.md)
+- [VS Code extension](docs/vscode-extension.md)
+- [Release policy](docs/release-policy.md)
+- [Publish guide](docs/publish.md)
+- [Changelog](CHANGELOG.md)
 
-The npm package should ship a clean CLI, first-party typings, schemas, docs, report assets, and a passing lint/test/typecheck baseline.
+<p align="center">
+  <img src="src/assets/themisVerdictEngine.png" alt="Themis verdict engine art" width="960">
+</p>

package/docs/tutorial-claude-code.md

@@ -0,0 +1,230 @@
+# Testing With Claude Code and Themis
+
+A step-by-step walkthrough showing how Themis turns Claude Code into a test-writing machine that gets it right on the first try.
+
+## The Problem
+
+When you ask Claude Code to write unit tests, it reaches for Jest or Vitest by default. The tests it generates are often correct, but just as often they have subtle issues: wrong import paths, misused mocking APIs, snapshot tests where assertions would be better, setup files where the framework handles things natively. You end up in an edit-test-fix loop that burns time and context window.
+
+Themis fixes this by shipping structured guidance directly to Claude Code — a skill, slash commands, and a `CLAUDE.md` that tells Claude exactly how to write, run, and fix tests. No copy-pasting docs. No explaining the framework. Claude just knows.
+
+## What You'll See
+
+By the end of this tutorial you'll have:
+
+1. A Node.js project with Themis installed and Claude Code fully wired up
+2. Generated tests that pass on the first run
+3. A structured failure-fix loop where Claude reads machine-parseable repair hints instead of raw stack traces
+4. Slash commands (`/themis-test`, `/themis-generate`, `/themis-fix`) that work out of the box
+
+## Step 1: Set Up a Project
+
+Start with any Node.js or TypeScript project. For this tutorial we'll use a small utility library.
+
+```bash
+mkdir demo-project && cd demo-project
+npm init -y
+```
+
+Create a source file at `src/cart.js`:
+
+```js
+class Cart {
+  constructor() {
+    this.items = [];
+  }
+
+  add(item) {
+    if (!item || !item.name || typeof item.price !== 'number') {
+      throw new TypeError('Item must have a name and a numeric price');
+    }
+    const existing = this.items.find((i) => i.name === item.name);
+    if (existing) {
+      existing.quantity += item.quantity || 1;
+    } else {
+      this.items.push({ ...item, quantity: item.quantity || 1 });
+    }
+  }
+
+  remove(name) {
+    const index = this.items.findIndex((i) => i.name === name);
+    if (index === -1) throw new Error(`Item "${name}" not in cart`);
+    this.items.splice(index, 1);
+  }
+
+  total() {
+    return this.items.reduce((sum, item) => sum + item.price * item.quantity, 0);
+  }
+
+  checkout(paymentMethod) {
+    if (this.items.length === 0) throw new Error('Cannot checkout an empty cart');
+    const receipt = {
+      items: this.items.map((i) => ({ ...i })),
+      total: this.total(),
+      paymentMethod,
+      timestamp: new Date().toISOString()
+    };
+    this.items = [];
+    return receipt;
+  }
+}
+
+module.exports = { Cart };
+```
+
+## Step 2: Install Themis With Claude Code Integration
+
+```bash
+npm install -D @vitronai/themis@latest
+npx themis init --claude-code
+```
+
+That one command installs:
+
+- `CLAUDE.md` — adoption rules at the repo root that Claude Code reads automatically
+- `.claude/skills/themis/SKILL.md` — a skill that auto-loads when Claude sees a test-related request
+- `.claude/commands/themis-test.md` — `/themis-test` slash command
+- `.claude/commands/themis-generate.md` — `/themis-generate` slash command
+- `.claude/commands/themis-migrate.md` — `/themis-migrate` slash command
+- `.claude/commands/themis-fix.md` — `/themis-fix` slash command
+
+You can verify:
+
+```bash
+cat CLAUDE.md          # Themis adoption rules
+ls .claude/skills/     # themis/SKILL.md
+ls .claude/commands/   # four slash command files
+```
+
+## Step 3: Generate Tests
+
+Open Claude Code in the project and type:
+
+```
+/themis-generate src
+```
+
+Claude uses the installed skill context to run `npx themis generate src`. Generated tests land under `__themis__/tests/` as `.generated.test.js` files. These are deterministic, contract-style tests — not LLM-generated guesses.
+
+## Step 4: Run the Test Loop
+
+```
+/themis-test
+```
+
+This runs `npx themis test --reporter agent` and Claude reads the structured JSON output. If everything passes, you're done. If there are failures, Claude sees:
+
+```json
+{
+  "failures": [
+    {
+      "cluster": "cart-checkout-validation",
+      "repairHints": ["checkout() throws when cart is empty — test passes an empty cart but expects success"],
+      "sourceFile": "src/cart.js",
+      "lineNumber": 32,
+      "expected": "Error: Cannot checkout an empty cart",
+      "actual": "{ items: [], total: 0 }"
+    }
+  ]
+}
+```
+
+Instead of re-reading a raw stack trace, Claude acts on the `repairHints` directly. This is the key difference: structured signals instead of unstructured error output.
+
+## Step 5: Ask Claude to Write More Tests
+
+Now ask Claude to add coverage for edge cases:
+
+```
+Write additional tests for the Cart class covering:
+- adding duplicate items increments quantity
+- removing a non-existent item throws
+- checkout clears the cart
+- total with no items returns 0
+```
+
+Because the Themis skill is loaded, Claude will:
+
+1. Use `intent(...)` for behavior tests and `test(...)` for pure unit checks
+2. Follow the four-phase shape: context, run, verify, cleanup
+3. Use `expect(...)` assertions (not snapshots)
+4. Place tests alongside the generated ones, not in a random `tests/` directory
+
+Run `/themis-test` again to verify.
+
+## Step 6: Fix Failures (When They Happen)
+
+If any test fails, use:
+
+```
+/themis-fix
+```
+
+Claude will:
+
+1. Run `npx themis test --reporter agent` to get the current failures
+2. Group failures by `cluster` — fixes within a cluster share a root cause
+3. Read `repairHints` before looking at the stack trace
+4. Apply the smallest fix that addresses the root cause
+5. Re-run with `--rerun-failed` to confirm the fix without running the full suite
+
+This cluster-based fixing is faster than fixing tests one at a time, and the `--rerun-failed` flag means you don't pay the cost of a full suite run after each fix.
+
+## Step 7: Optional — Wire Up the Automated Hook
+
+For the tightest possible loop, add a PostToolUse hook that runs Themis automatically after every edit Claude makes:
+
+Add this to `.claude/settings.json`:
+
+```json
+{
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "Edit|Write|MultiEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node node_modules/@vitronai/themis/scripts/claude-hook.js"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+Now every time Claude edits a `.js`/`.ts`/`.jsx`/`.tsx` file, Themis runs automatically. If tests fail, the structured failure JSON is fed back into the conversation — Claude sees it immediately and can fix it in the next turn without you running anything.
+
+The hook is smart about scope:
+
+- Skips non-source edits (docs, config, etc.)
+- Uses `--rerun-failed` when there's a prior failure artifact
+- Exits silently when tests pass (no context noise)
+- Set `THEMIS_HOOK_DISABLED=1` to pause it temporarily
+
+## Why This Works
+
+The magic is not in Themis being a better test runner (though it is faster). The magic is in the **structured agent context**:
+
+1. **The skill** tells Claude exactly when and how to use Themis — it auto-loads without you mentioning the framework
+2. **The CLAUDE.md** provides rules about what to avoid (no setup shims, no snapshots as defaults, no ad-hoc test directories)
+3. **The `--reporter agent` output** gives Claude machine-parseable failure data with repair hints, instead of raw stack traces it has to re-parse
+4. **The slash commands** encode the correct workflow so Claude doesn't have to figure out which flags to pass
+
+In Tessl evaluations across 10 scenarios, agents scored **37% without** the Themis skill context and **97% with it**. The context is the product.
+
+## What's Next
+
+- **Migrate from Jest or Vitest**: Run `/themis-migrate` — Claude walks through the four-step incremental migration
+- **Cursor users**: Run `npx themis init --cursor` to install `.cursorrules`
+- **Both at once**: `npx themis init --agents --claude-code --cursor`
+- **Auto-detection**: A bare `npx themis init` detects which agents are present and installs the right assets automatically
+
+## Links
+
+- npm: [`@vitronai/themis`](https://www.npmjs.com/package/@vitronai/themis)
+- GitHub: [vitron-ai/themis](https://github.com/vitron-ai/themis)
+- Tessl tile: [vitron-ai/themis](https://tessl.io/registry/vitron-ai/themis)
+- Eval results: [37% baseline → 97% with skill](https://tessl.io/eval-runs/019d72a0-8211-74ea-84ef-a8e336ead3d2)
+- Adoption guide: [`docs/agents-adoption.md`](agents-adoption.md)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vitronai/themis",
-  "version": "1.2.1",
+  "version": "1.2.2",
   "description": "A Node.js and TypeScript unit test framework designed for AI coding agents. Drop-in alternative to Jest and Vitest with machine-readable failure output, structured repair hints, and one-command migration.",
   "license": "MIT",
   "author": "Vitron AI",