testerkit 0.4.0__py3-none-any.whl

testerkit/_docs/reference/operator-ui/tests.md

@@ -0,0 +1,173 @@
+# Tests
+
+**URLs:** `/tests` (list), `/tests/{path}` (detail)
+
+A test in TesterKit is a `def test_*` function that pytest discovers — either a
+top-level function or a method inside a `class Test*`. The Tests pages give you
+a file-level inventory of every `test_*.py` under `tests/`, cross-referenced
+against run history, without importing or executing any test code.
+
+## List — `/tests`
+
+Files are grouped by directory. Each directory renders a folder-icon header
+followed by one row per `test_*.py` file under it.
+
+### File rows
+
+Each row shows:
+
+| Field | What it shows |
+|---|---|
+| Filename | The `test_*.py` filename, in monospace |
+| Test count | Number of `def test_*` functions found in the file (top-level and inside `class Test*`) |
+| Class count | Number of `class Test*` definitions, shown inline when non-zero |
+| Vectors | A `~N vectors` badge, present when the file has parametrize, `testerkit_sweeps`, or similar list-valued markers. The count is a rough upper-bound estimate from the decorator arguments — not an exact cross-product |
+| Markers | Up to four marker chips (decorator names, without the `pytest.mark.` prefix), then `+N` when there are more |
+| Runs | Count of distinct `run_id` values in history where any step from this file executed; omitted when zero |
+| Failed | Count of those runs with at least one failed step; omitted when there are no runs or no failures |
+| Sidecar | A `sidecar` badge when a `.yaml` file with the same stem exists alongside the `.py`; a dash otherwise |
+
+Clicking any row navigates to `/tests/{path}` for that file.
+
+When a file cannot be parsed (syntax error or I/O problem), the row renders in
+red with a warning icon and a truncated error message. The file is still
+clickable — the detail page shows the full parse error.
+
+### Badge
+
+A `N files` badge in the page header shows the total number of `test_*.py`
+files found.
+
+### Observed in history (no matching source)
+
+Below the file list, when run history contains step paths that do not match
+any function in the current source, an **Observed in history (no matching
+source)** section appears. This surfaces tests that were renamed, deleted, or
+run from a code state that isn't checked out. The section shows the count of
+orphaned paths as a warning badge.
+
+The orphan table has these columns:
+
+| Column | What it shows |
+|---|---|
+| Step Path | The `step_path` value from the steps table — bare function name or `Class/method` |
+| Runs | Distinct run count |
+| Passed | Runs with outcome `passed` |
+| Failed | Runs with outcome `failed` |
+| Last Run | Most recent step start timestamp, browser-local time |
+
+Rows are sorted by Last Run descending so the most recently orphaned paths appear first.
+
+### Empty state
+
+When no `test_*.py` files are found and there are no orphan step paths, the
+file list is replaced with a card:
+
+> No test files found.
+>
+> Add test_*.py files under tests/.
+
+### Data-testid anchors
+
+| Element | `data-testid` |
+|---|---|
+| Directory-grouped file list container | `tests-table` |
+| Orphaned step paths table | `tests-orphans-table` |
+
+## Detail — `/tests/{path}`
+
+The `{path}` segment carries the full relative path from the project root,
+including the `tests/` prefix and the `.py` extension — for example,
+`/tests/tests/test_power_rail.py`. The path is resolved against the server's
+current working directory; only files inside the working tree are served.
+
+### Header
+
+The page header shows the file path, a `N tests` badge, a `sidecar` badge
+when a sidecar exists, and a **Launch Test** button (top right) that navigates
+to `/launch?test={path}`.
+
+A note below the header reads:
+
+> What actually runs depends on the active profile — sidecar < profile
+> (last-wins). See Profiles.
+
+"Profiles" is a link to `/profiles`. For the cascade order, see
+[Profiles](../configuration.md#profile-blocks-under-profiles).
+
+### Test functions table
+
+A table with one row per `def test_*` function found in the file. Columns:
+
+| Column | What it shows |
+|---|---|
+| Test | Bare function name (`test_foo`) |
+| Class | Parent `class Test*` name, or `—` for top-level functions |
+| Markers | Comma-separated decorator names (without `pytest.mark.` prefix), or `—` |
+| Vectors | Estimated parametrize / `testerkit_sweeps` vector count, or `—` when zero |
+| Sidecar | `✓` when this function (or its parent class) has an entry in the sidecar `tests:` block; `—` otherwise |
+| Runs | Distinct run count from history for this step path; `0` when never run |
+| Passed | Runs with outcome `passed` |
+| Failed | Runs with outcome `failed` |
+| Last Run | Most recent step start timestamp, browser-local time; `—` when never run |
+
+The step path used to look up run history is `Class/method` when the function
+is inside a class, or the bare function name for top-level functions. This
+matches the `step_path` value recorded in run history.
+
+The test functions table is omitted when the file has a parse error.
+
+Data-testid anchor: `test-functions-table`.
+
+### Tabs
+
+Below the test functions table, two tabs are available:
+
+| Tab | Content |
+|---|---|
+| Code | The `.py` file rendered as a read-only Python code block |
+| Sidecar YAML | The colocated `.yaml` file rendered as a read-only YAML code block; present only when a sidecar exists |
+
+When no sidecar exists, only the **Code** tab appears.
+
+### Parse error state
+
+When the file cannot be parsed, a red card appears at the top of the content
+area with the full error message. The Code tab still renders the raw file
+contents.
+
+### Not-found state
+
+When `{path}` does not resolve to an existing `.py` file inside the working
+tree, the page shows a card:
+
+> Test file '{path}' not found.
+
+with a "← Back to Tests" link.
+
+## Underlying data
+
+The file list is built by reading every `test_*.py` under `tests/` directly —
+without importing or running any test code — to extract its function names,
+class names, and decorators. Files that fail to parse are still listed,
+flagged with the parse error.
+
+Run history (Runs / Passed / Failed / Last Run) is tallied from run history
+for each test, by step path. For the full step record schema, see
+[Parquet schema](../data/parquet-schema.md).
+
+A test shows the `sidecar` badge when a `.yaml` file with the same stem sits
+alongside the `.py`. On the detail page, a function gets the `✓` when it (or
+its class) has an entry in the sidecar's `tests:` block.
+
+## See also
+
+- [How-to → Writing Tests](../../how-to/execution/writing-tests.md) — pytest
+  classes, sidecar YAML, the `verify` pattern
+- [pytest markers reference](../pytest/markers.md) — every `@testerkit.mark.*`
+  decorator that appears in the Markers column
+- [Profiles](profiles.md) — how profiles override sidecar config at session
+  start (the cascade note on the detail page)
+- [Launch Test](launch.md) — start a run targeting one of these test files
+- [Results](results/list.md) — per-run view; the step-level detail that feeds
+  the Runs / Passed / Failed counts on this page

testerkit/_docs/reference/operator-ui/uuts.md

@@ -0,0 +1,67 @@
+# UUTs
+
+**URLs:** `/uuts`
+
+Every distinct UUT serial that has appeared in run history gets one row
+here. A UUT isn't declared in YAML — it's identified at run time by the
+serial number the operator (or automation) supplies when starting a run.
+
+## List — `/uuts`
+
+A table with one row per distinct UUT serial observed in run history.
+Rows are ordered by most-recent run first.
+
+| Column | What it shows |
+|---|---|
+| Serial | The `uut_serial_number` value recorded on the run |
+| Part Number | The `uut_part_number` recorded on the most recent run for this serial |
+| Lot | The `uut_lot_number` recorded on the most recent run for this serial |
+| Runs | Total run count across all outcomes for this serial |
+| Passed | Run count with outcome `passed` |
+| Failed | Run count with outcome `failed` |
+| Last Run | Most recent run start timestamp, browser-local time |
+
+A badge in the page header shows the total count of observed UUTs.
+
+The table has no filter row. All rows are observed-only — there is no
+Configured / Observed distinction because UUTs have no backing YAML.
+
+There is no detail page at `/uuts/{serial}`. The list is the only view.
+
+### Empty state
+
+When no runs with a non-empty `uut_serial_number` are present, the table is
+replaced with a card:
+
+> No UUTs observed yet.
+>
+> Run a test against a station to populate this list. Every distinct UUT
+> serial that appears in run history shows up here.
+
+### Outcome columns
+
+**Passed** and **Failed** count only runs whose outcome is exactly
+`passed` or `failed`. Runs with other outcomes (for example `aborted`)
+contribute to the **Runs** total but are not reflected in either column.
+
+## Underlying data
+
+Each column maps to a field on the run:
+
+| Column | Run field |
+|---|---|
+| Serial | `uut_serial_number` |
+| Part Number | `uut_part_number` |
+| Lot | `uut_lot_number` |
+
+For the full set of run fields, see
+[Parquet schema](../data/parquet-schema.md).
+
+## See also
+
+- [Parquet schema](../data/parquet-schema.md) — the `uut_serial_number`,
+  `uut_part_number`, and `uut_lot_number` run columns
+- [Results](results/list.md) — per-run view; its Serial column shows
+  which runs belong to a UUT
+- [Launch Test](launch.md) — where the operator supplies the serial
+  number that populates this page

testerkit/_docs/reference/overview/index.md

@@ -0,0 +1,11 @@
+# Reference — Overview
+
+The foundational reference pages: pytest mechanics every TesterKit test uses, and the AI / MCP skills the platform ships.
+
+- [pytest-native](pytest-native.md) — TesterKit tests against pytest's own collection / fixtures / markers / `conftest.py` / CLI flags. The baseline every other reference page builds on. Generated from source.
+- [Skills](skills.md) — the 11 Agent Skills that ship with TesterKit for AI-assisted authoring, and how `testerkit setup <tool>` installs them into each AI tool.
+
+## See also
+
+- [Concepts → Overview](../../concepts/overview/index.md) — the platform-vs-framework framing
+- [pytest plugin reference](../pytest/) — the fixtures and markers the plugin adds on top of pytest-native

testerkit/_docs/reference/overview/pytest-native.md

@@ -0,0 +1,142 @@
+# pytest-native reference
+
+TesterKit is a hardware test **platform**; pytest is its primary test-runner integration. The bundled pytest plugin slots into a stock pytest install with zero configuration — every pytest concept (collection, fixtures, markers, plugins, `conftest.py`, command-line flags) works unchanged. This page is the map of what pytest gives you natively and what the plugin layers on top. For the plugin's own surface see [TesterKit fixtures](../pytest/fixtures.md) and [TesterKit markers](../pytest/markers.md). Other runner integrations (OpenHTF, LabVIEW / TestStand via the results API) live under [Integrations](../../integration/).
+
+## Collection
+
+The bundled pytest plugin uses pytest's default collection — no custom file collectors.
+
+| Convention | Default |
+|---|---|
+| Test files | `tests/test_*.py` or `tests/*_test.py` |
+| Test classes | classes named `Test*` (no `__init__`) |
+| Test functions / methods | functions named `test_*` |
+| Override | standard pytest `python_files` / `python_classes` / `python_functions` in `pyproject.toml` |
+
+What TesterKit adds at collection time:
+
+- A `pytest_collection_modifyitems` hook merges per-test sidecar YAML (`tests/test_<module>.yaml`) into each item's marker set. This expands `testerkit_sweeps` into one pytest case per row exactly as if you had written `@pytest.mark.parametrize` — pytest still owns the case multiplication.
+- Profiles (`--test-profile=<name>`) add `pytest.mark.skip` to items they exclude. The selection is visible in `pytest --collect-only -q`.
+
+The sidecar is recursive: top-level keys apply to every test in the file; `tests: { ClassName: { ... } }` scopes per class; `tests: { ClassName: { tests: { test_method: { ... } } } }` scopes per method. See [Sidecar configuration](../configuration.md#sidecar-yaml).
+
+## Fixtures
+
+pytest's fixture model is unchanged.
+
+- **All four scopes work.** `function`, `class`, `module`, `session` — choose the one that matches your resource cost.
+- **Resolution by name.** Take a fixture in the test signature; pytest resolves it from the nearest `conftest.py` upward, then from registered plugins (TesterKit included).
+- **Yield fixtures, finalizers, request injection** all work as pytest documents them.
+- **`autouse=True`** works. TesterKit uses an autouse-session fixture internally so every test records measurements without taking a recording fixture as an argument.
+
+You can write your own fixtures in `conftest.py` alongside TesterKit's. A common pattern is a project-local `uut` factory wrapping the TesterKit `uut` session fixture, or a per-class hardware-setup fixture that takes `instruments` as a dependency.
+
+The fixtures the TesterKit plugin contributes are documented in [TesterKit fixtures](../pytest/fixtures.md).
+
+## Markers
+
+pytest's marker mechanism is unchanged. All of these work on TesterKit tests as documented in the pytest manual:
+
+| Marker | Use |
+|---|---|
+| `@pytest.mark.parametrize` | Generate one pytest case per row. Stack to cross-product. |
+| `@pytest.mark.skip` / `@pytest.mark.skipif` | Skip the test (with optional condition). |
+| `@pytest.mark.xfail` | Mark as expected-to-fail; surfaces as `XFAIL` / `XPASS`. |
+| `@pytest.mark.usefixtures("a", "b")` | Require fixtures without taking them in the signature. |
+| `@pytest.mark.filterwarnings` | Per-test warning filters. |
+| Custom markers via `pytest.ini` / `pyproject.toml` | Register and filter with `-m`. |
+
+The seven `@pytest.mark.testerkit_*` markers TesterKit adds are registered the same way as native markers and stack with them (with one constraint — see the [no-stacking rule](../pytest/markers.md#no-stacking-rule) for TesterKit markers). See [TesterKit markers](../pytest/markers.md) for full details.
+
+`@pytest.mark.parametrize` and `@pytest.mark.testerkit_sweeps` interoperate: both feed the same `inputs` lane on the vector row (query with `FieldRef.input(name)`).
+
+## conftest.py
+
+Works as pytest documents it. Place a `conftest.py` in `tests/` (or a subdirectory) for fixtures and hooks that apply to that scope. Common uses with TesterKit:
+
+- Project-local fixtures that wrap or extend TesterKit's (a typed `uut` accessor, a per-class measurement helper).
+- `pytest_addoption` for project-specific CLI flags.
+- `pytest_collection_modifyitems` for project-specific item filtering. (TesterKit's hook is in the plugin and runs alongside, not instead of, yours.)
+- `pytest_runtest_setup` / `_teardown` for per-test setup beyond what fixtures express.
+
+The TesterKit plugin loads via the standard pytest entry-point mechanism — no `conftest.py` manipulation needed.
+
+## Command-line flags
+
+All pytest flags work. The ones that matter most for hardware test work:
+
+| Flag | Purpose |
+|---|---|
+| `-k "expr"` | Run tests whose nodeid matches the substring expression. |
+| `-m "marker"` | Run tests whose markers match the boolean expression. |
+| `-x` / `--maxfail=N` | Stop after the first failure / Nth failure. |
+| `--lf` / `--ff` | Run last-failed / failed-first (uses pytest's cache). |
+| `--collect-only -q` | Show what would run without running. |
+| `-v` / `-q` | Verbose / quiet. |
+| `--tb=short` / `--tb=line` / `--tb=no` | Traceback style. |
+| `-p no:plugin` | Disable a specific plugin. |
+| `--co` | Alias for `--collect-only`. |
+
+TesterKit adds the flags below.
+
+<!-- Generated from pytest_addoption; regenerate with
+     `uv run python scripts/generate_reference_docs.py pytest-native` after editing the hook. -->
+
+<!-- GENERATED:pytest-plugin-flags:start -->
+| Flag | Type | Default | Description |
+|---|---|---|---|
+| `--uut-serial` | `text` | `'UUT001'` | UUT serial number |
+| `--uut-serials` | `text` |  | Per-site UUT serials: 0=SN1,1=SN2 (by index) or left=SN1,right=SN2 (by name) |
+| `--site` | `text` |  | Physical fixture site for this single-process run (e.g. ``0``, ``1``, or a named site like ``left``). Use this when running a single UUT against a specific position in a multi-site fixture so the run records which site was exercised. Multi-site orchestration uses ``--uut-serials`` instead — supplying both is an error. |
+| `--uut-part-number` | `text` |  | UUT part number |
+| `--uut-revision` | `text` |  | UUT revision |
+| `--uut-lot-number` | `text` |  | UUT lot/batch number (mirrors TESTERKIT_UUT_LOT_NUMBER env var) |
+| `--station` | `text` |  | Station ID or YAML path. Bare id looks up ``stations/<id>.yaml``; a value with ``/`` or ``.yaml``/``.yml`` is used as an explicit path. When unset, the resolver tries hostname auto-match against stations/*.yaml ``hostname:`` fields, then falls back to ``ProjectConfig.default_station``. |
+| `--operator` | `text` |  | Operator name |
+| `--data-dir` | `text` | *resolved at runtime* | Directory for Parquet results (default: platform data dir) |
+| `--part` | `text` |  | Part ID or YAML path. Bare id looks up ``parts/<id>.yaml``; a value with ``/`` or ``.yaml``/``.yml`` is used as an explicit path. |
+| `--guardband` | `text` | `'0'` | Default guardband percentage |
+| `--mock-instruments` | `flag` | `False` | Use mock instruments instead of real hardware. Resolution: this flag > TESTERKIT_MOCK_INSTRUMENTS env var > testerkit.yaml `mock_instruments:` > false. |
+| `--no-mock-instruments` | `flag` (inverse) | `True` | Use real hardware (overrides TESTERKIT_MOCK_INSTRUMENTS env and testerkit.yaml `mock_instruments: true`). |
+| `--fixture` | `text` |  | Fixture ID or YAML path. Bare id looks up ``fixtures/<id>.yaml``; a value with ``/`` or ``.yaml``/``.yml`` is used as an explicit path. When unset, the resolver tries the active profile's ``fixture:`` field, then ``ProjectConfig.default_fixture``, then the single-file fallback in ``fixtures/``. |
+| `--test-phase` | `text` |  | Test phase (development, validation, characterization, production). Defaults to development; a non-development phase is demoted to development on a dirty git tree or under --mock-instruments. |
+| `--strict-traceability` | `flag` | `False` | Fail tests whose measurements lack required traceability fields (run_id, step_name, and spec_ref/uut_pin when a spec is active). |
+| `--test-profile` | `text` | *resolved at runtime* | Named profile from testerkit.yaml `profiles:` (overrides vectors, limits, markers, and filter for the session). |
+| `--no-test-profile` | `flag` | `False` | Skip profile resolution. Use when profiles are declared but you want to run with bare project defaults (ad-hoc runs). |
+
+Plus dynamic flags generated from `testerkit.yaml`: every `profiles[*].facets:` key becomes `--<facet-key>` and every `required_inputs:` key becomes `--<required-input-key>`. See [how-to/profiles.md](../../how-to/execution/profiles.md) for the resolution chain (CLI flag → env var → profile binding → `default_*`).
+<!-- GENERATED:pytest-plugin-flags:end -->
+
+## Plugins that interact with TesterKit
+
+| Plugin | Notes |
+|---|---|
+| **pytest-rerunfailures** | Powers `@pytest.mark.testerkit_retry`. Install it if you use the marker; the translation happens in the plugin. |
+| **pytest-xdist** | Parallel execution. Generally **not** appropriate for hardware tests on a single bench (instruments aren't reentrant). Fine for mock-only suites and CI lint passes. |
+| **pytest-cov** | Code coverage. Works unchanged on test files; collects coverage on the test code, not on instrument drivers behind hardware. |
+| **pytest-html** / **pytest-json-report** | Independent of TesterKit's own event log + parquet output. Run them alongside if you want pytest-flavored reports too. |
+
+## Discovery vs activation
+
+Two things to keep separate:
+
+- **Discovery** is pytest's: what `tests/test_*.py` files match, what items they expose. TesterKit has no opinion here.
+- **Activation** is TesterKit's: which station, part, fixture, profile is loaded for the session. Driven by the CLI flags above (or by `default_station:` / `default_profile:` in `testerkit.yaml`).
+
+A test that runs on a bringup tier with no station YAML and a test that runs on a factory tier with full traceability are **collected identically**. The activation context decides what fixtures resolve to and what limits `verify` finds.
+
+## See also
+
+- [TesterKit fixtures](../pytest/fixtures.md) — all the fixtures the plugin contributes
+- [TesterKit markers](../pytest/markers.md) — the seven `testerkit_*` markers and their sidecar equivalents
+- [Sidecar configuration](../configuration.md#sidecar-yaml) — sidecar YAML merge semantics
+- [CLI reference](../cli.md) — full flag list, including the non-pytest commands (`testerkit serve`, `testerkit runs`, etc.)
+- [pytest documentation](https://docs.pytest.org/en/stable/) — canonical reference for everything in the "pytest-native" half of this page
+
+
+**Related quadrants:**
+
+- [Concepts → Overview](../../concepts/overview/index.md) — concepts entry point for this category
+- [How-to → Overview](../../how-to/overview/index.md) — how-to entry point for this category
+- [Integration](../../integration/index.md) — integration entry point for this category
+- [Tutorial](../../tutorial/index.md) — tutorial entry point for this category

testerkit/_docs/reference/overview/skills.md

@@ -0,0 +1,177 @@
+# Skills reference
+
+TesterKit ships 12 **Agent Skills** — one directory per skill under
+[`src/testerkit/skills/`](https://github.com/pragmatest-dev/testerkit/tree/main/src/testerkit/skills),
+each a `SKILL.md` written to the
+[Agent Skills open standard](https://github.blog/changelog/2025-12-18-github-copilot-now-supports-agent-skills/):
+YAML frontmatter (`name`, `description`) an agent matches against the user's
+request, then a body the agent reads once matched. This page is the
+inventory — what each skill covers, how the depth behind it is sourced, and
+how `testerkit setup <tool>` gets the files in front of your agent.
+
+For motivation (why AI integration at all), see
+[concepts/why-ai-integration](../../concepts/overview/ai-integration.md). For
+registering the MCP server and instructions file per tool, see
+[how-to/mcp-integration](../../how-to/overview/mcp-integration.md).
+
+## The 12 skills
+
+| Skill | Use when |
+|---|---|
+| `testerkit-tests` | Testing, measuring, or logging any hardware value — the front door. Starts at zero config, grows only as the request demands. |
+| `testerkit-mocks` | Running tests without real hardware — dev-machine smoke tests, CI, a bench that's tied up, or pinning one instrument call's return value. |
+| `testerkit-stations` | Setting up the bench — instruments, roles, a bring-your-own driver, discovery, fixture pin routing. |
+| `testerkit-parts` | Specifying the DUT — documented characteristics, pin map, or a datasheet limit as reusable part YAML. |
+| `testerkit-profiles` | Different limits, sweeps, mocks, or wiring per test phase or part variant, selected with a CLI flag at run time. |
+| `testerkit-sites` | Testing multiple UUTs at once on one fixture — multi-site / multi-socket parallel production testing. |
+| `testerkit-capture` | Capturing non-tabular evidence during a test — a waveform, a live sensor feed, a photo, a vendor capture file, a log. |
+| `testerkit-data` | Reading, querying, or exporting existing test data — runs, steps, measurements, channels, files, events — via the models, CLI, Query API, or MCP. |
+| `testerkit-analysis` | Computing a statistic across runs — yield, Pareto, Ppk, a trend, a retest rate, time-loss. |
+| `testerkit-debug` | Triaging why a run failed, errored, looks wrong, or is missing. |
+| `testerkit-interactive` | Pausing a test for operator input, building a custom live operator screen, or driving a station interactively outside pytest. |
+| `testerkit-datasheets` | Importing an instrument or part datasheet PDF into catalog or part config. |
+
+Each row above is a condensed reading of that skill's own `description`
+frontmatter — the exact text an agent matches against. `testerkit-tests` is
+the deliberate front door: it starts at a bare `def test_x(verify): ...`
+with no station, no YAML, and only routes to a sibling skill (mocks,
+stations, parts, profiles, sites, capture, data, analysis, debug,
+interactive) once the request needs that layer.
+
+(`testerkit-capture` writes non-tabular evidence, `testerkit-data` reads any store
+back, `testerkit-analysis` computes statistics over the tabular data — three
+distinct jobs on the data axis, no overlap.)
+
+## Single-source design
+
+A `SKILL.md` is not a standalone essay. It carries the **action
+playbook** — the decision the agent has to make and the judgment calls
+around it (which verb, which config rung, what to warn about) — in a body
+short enough to read in full every time the skill matches. Anything that's
+already documented at length lives in the shipped docs, and the skill
+tells the agent to read it there instead of re-stating it:
+
+```
+## Deeper
+Read the docs:
+testerkit docs show concepts/overview/tiers
+testerkit docs show how-to/execution/writing-tests
+```
+
+This keeps exactly one copy of any factual claim — the shipped `docs/`
+tree — instead of a frozen paraphrase inside the skill that drifts the
+next time the underlying behavior changes. `testerkit docs show <path>`
+streams that same tree; see [The `testerkit docs` CLI](#the-testerkit-docs-cli)
+below.
+
+Two skills carry a `references/` subdirectory for content that has no
+shipped-doc home:
+
+- **`testerkit-datasheets`** — `references/catalog-pipeline.md`,
+  `test-pipeline.md`, `scaffold.md`, `process-queue.md` are the full
+  phase-by-phase orchestration contracts for its four import pipelines
+  (too long and too procedural for a `docs/` page). It also carries
+  `agents/` — five sub-agent prompts (`section-splitter`,
+  `scaffold-writer`, `section-extractor`, `section-writer`,
+  `section-reviewer`) the catalog pipeline spawns in sequence; each is
+  single-responsibility and not invoked directly by a user.
+- **`testerkit-interactive`** — `references/live-ui-patterns.md` is the
+  decision table + anti-pattern catalog for building a custom NiceGUI
+  page against live channel data (subscribe-vs-raw-thread, when to
+  stop mutating from a callback).
+
+Every other skill's `SKILL.md` is self-contained plus links out to `testerkit
+docs show` — no `references/` directory.
+
+## Install / cross-tool
+
+`testerkit setup <tool>` copies the packaged skill directories into the
+tool's **native** Agent-Skills path — the same `SKILL.md` file, read
+directly, no per-tool adapter or reformatting:
+
+| Tool | Setup command | Skills copied to | Instructions file | MCP registration |
+|---|---|---|---|---|
+| Claude Code | `testerkit setup claude-code` | `.claude/skills/` | `CLAUDE.md` | `claude mcp add testerkit -- <bin> mcp serve` |
+| OpenAI Codex | `testerkit setup codex` | `.agents/skills/` | `AGENTS.md` | printed for `~/.codex/config.toml` (Codex's home config; TesterKit doesn't write another tool's home config) |
+| Cursor | `testerkit setup cursor` | `.cursor/skills/` | `AGENTS.md` | `.cursor/mcp.json` |
+| GitHub Copilot | `testerkit setup copilot` | `.github/skills/` | `.github/copilot-instructions.md` + `AGENTS.md` | `.vscode/mcp.json` |
+
+All four read `SKILL.md` natively — Claude Code and Codex from the start;
+Cursor since 2.4 (shipped 2026-01-22); GitHub Copilot since its Agent
+Skills support shipped 2025-12-18 (stable in VS Code early January 2026),
+across VS Code/JetBrains agent mode, Copilot CLI, and the coding agent.
+There is no Cursor `.mdc` rules file and no Copilot `.prompt.md` wrapper
+generated — the single `SKILL.md` is the whole artifact.
+
+The instructions file (`CLAUDE.md` / `AGENTS.md` /
+`.github/copilot-instructions.md`) is marker-managed: `testerkit setup`
+writes the TesterKit section between `<!-- testerkit:start -->` /
+`<!-- testerkit:end -->` markers, creating the file if it doesn't exist or
+replacing only that section if it does, leaving the rest of the file
+alone.
+
+`testerkit setup claude-desktop` and `testerkit setup cline` are MCP-only —
+neither projects a native skills directory. `claude-desktop` bundles the
+skill files inside the `.mcpb` extension as reference material rather
+than a loose, natively-read directory; `cline` writes only
+`cline_mcp_settings.json`.
+
+Every `testerkit setup <tool>` command accepts `--print-only` to preview all
+of its side effects — skills copied, instructions file created/updated,
+MCP config — without writing anything.
+
+## The `testerkit docs` CLI
+
+```cli
+$ testerkit docs list reference
+reference/catalog/schema
+reference/cli
+reference/overview/pytest-native
+reference/overview/skills
+...
+
+$ testerkit docs show concepts/data/three-verbs
+# Three verbs: configure, observe, verify
+...
+```
+
+`testerkit docs list [section]` enumerates shipped doc pages (optionally
+scoped to `concepts`, `how-to`, `reference`, `tutorial`, or `integration`);
+`testerkit docs show <path>` prints one page to stdout, resolved with or
+without a trailing `.md`. Both read from the same `docs/` tree that ships
+in the installed package (a bundled copy in a wheel install, the repo's
+`docs/` directory in an editable/source checkout) — the environment-stable
+way for an agent (or a human) to read TesterKit documentation without baking
+an absolute path into project config. This is the single source every
+skill's "Deeper" section points at, and it replaces the removed `testerkit
+refs` command — there is no separate curated reference corpus to keep in
+sync.
+
+## MCP vs skills
+
+Two different jobs, not overlapping ones:
+
+- **MCP** is live execution and introspection — `testerkit_project`,
+  `testerkit_run`, `testerkit_match`, `testerkit_discover`, `testerkit_runs`,
+  `testerkit_metrics`, and the rest of the tool surface the `testerkit mcp
+  serve` server exposes. Calling one of these does something or reads
+  something right now. Full per-tool detail: [API reference →
+  MCP tools](../runtime/api.md#tools).
+- **Skills** are judgment and procedure — which verb to reach for, which
+  config rung a request actually needs, what to check before declaring a
+  pipeline done. A skill matching doesn't execute anything by itself; it
+  tells the agent which MCP tools or CLI commands to call and in what
+  order, and where to read further before it does.
+
+A skill's playbook routes into MCP tools and CLI commands as the steps
+require — `testerkit-tests` step 6 runs plain `pytest`; `testerkit-datasheets`
+saves through `testerkit_project(action="save", ...)`; `testerkit-debug` reads
+back through `testerkit_runs` / `testerkit_steps`. Neither layer substitutes for
+the other.
+
+## See also
+
+- [Concepts: why AI integration](../../concepts/overview/ai-integration.md) — motivation
+- [How-to: MCP integration](../../how-to/overview/mcp-integration.md) — registering the server and instructions file with each AI tool
+- [Reference: MCP tools](../runtime/api.md#tools) — per-tool parameter detail
+- [Reference: CLI](../cli.md) — `testerkit docs`, `testerkit setup`, and every other command