supercov 0.0.43 → 0.0.45

package/docs/assertion-maps.md

@@ -0,0 +1,252 @@
+# Assertion maps
+
+Each normal test run creates `assertions.json` in its run directory. Any coding
+agent can edit that file to describe what specific assertions observe and which
+statements contribute to those observations. Rust handles syntax, references,
+input freshness, reuse and reporting. Supercov does not run an embedded model or
+reconstruct the agent's semantic reasoning with a static analyzer.
+
+## Run, investigate, save
+
+```sh
+supercov -- npm test
+supercov runs latest assertions --json
+# Pin the returned run ID; edit data.map using matching current project files.
+supercov runs <run> assertions report --view changes --json
+supercov runs <run> assertions validate --json
+# After investigating, copy expectedBasis tokens into the corresponding entries.
+supercov runs <run> assertions check --require-mappings --require-observed --json
+supercov runs <run>
+```
+
+There is no `init` or `review` command. `validate` is read-only: it returns the
+expected acknowledgements, and the agent saves them in the one editable file.
+A token says that the author acknowledges these particular inputs and this
+particular claim. It is not proof, a signature, or a model confidence score.
+
+## File format, version 2
+
+```json
+{
+  "schemaVersion": 2,
+  "assertions": [{
+    "id": "a_example",
+    "at": {
+      "file": "tests/value.test.ts", "line": 5, "column": 3,
+      "text": "assert.equal(value(), 1)"
+    },
+    "observes": ["The returned number equals one."],
+    "flows": [{
+      "id": "return-value",
+      "basis": null,
+      "appliesTo": [{ "file": "tests/value.test.ts", "name": "value" }],
+      "explanation": "The function's returned number reaches the equality assertion through value().",
+      "nodes": [{
+        "id": "return",
+        "at": { "file": "src/value.ts", "line": 2, "column": 3, "text": "return 1;" }
+      }],
+      "edges": [{ "from": "return", "to": "$assertion", "kind": "data" }],
+      "countsAsAsserted": ["return"],
+      "watch": []
+    }]
+  }]
+}
+```
+
+This is an illustrative draft; its anchors and test selector must match a real
+run before it can receive credit. `basis: null` explicitly means unacknowledged.
+`supercov assertions schema` exports the schema generated from the same Rust
+types as the parser. The published editor schema is `schemas/assertions.schema.json`.
+`supercov assertions validate --file <path> --json` checks JSON shape without a run.
+
+| Field | Meaning |
+| --- | --- |
+| `id`, `at` | Persistent assertion identity and exact assertion expression. |
+| `observes` | What the predicate distinguishes; an existence check does not check every field. |
+| `flows` | Recorded explanations. An empty array means none are recorded; there is no known total. |
+| `questions` | Optional assertion-level investigation questions. They do not establish completeness. |
+| Flow `id` | Stable within its assertion; `assertion-id/flow-id` identifies the claim. |
+| Flow `basis` | Null, or the opaque `scov2:<64 lowercase hex digits>` token supplied by validation. |
+| `appliesTo` | Explicit project-relative test file and exact displayed test name. Empty means no execution credit. |
+| `nodes`, `edges` | Exact source anchors and authored relationships ending at the reserved `$assertion` sink. |
+| `countsAsAsserted` | The node IDs judged asserted. Context nodes earn no automatic credit. |
+| `watch` | Additional whole-file dependencies as path strings. |
+| Flow `questions` | Optional unresolved questions; any entry blocks this flow's credit. |
+
+Anchors use project-relative `/` paths, one-based lines and one-based UTF-8 byte
+columns. Preserve exact text, including multiline expressions. IDs use letters,
+digits, `_`, `-`, or `.`. Edges have `from`, `to`, `kind`, and optional explanatory
+`basis` text; that edge text is distinct from the flow's acknowledgement token.
+Every counted node needs a path through the authored edges to `$assertion`.
+The checker traverses this JSON graph only; it does not infer source dependencies.
+A counted node must match one measured statement exactly to earn credit. A block
+or guard does not implicitly credit its nested body.
+
+A zero-credit explanation is useful for a fixture-only check or an absence check:
+explain the observation and use `countsAsAsserted: []`. An absent event cannot
+credit an unexecuted body. An executed guard can receive credit only when the
+author judges that the predicate observes its behavior.
+
+## Percentage and report states
+
+The regular `supercov runs <run>` report reads the map on demand. Its primary
+percentage is the union of eligible, explicitly counted measured statements,
+divided by **all measured statements** in the run. Unexecuted and unanchored
+measured statements remain in the denominator. Duplicate claims count once.
+Line credit requires all measured statements on that line to be credited.
+
+Eligibility requires valid references, current input acknowledgement, no open
+flow questions, a passing run, an exact passing assertion occurrence, and
+statement execution attributed to the same selected passing test. File + name
+selectors must resolve unambiguously. A missing or unobserved selector contributes
+nothing; an observed sibling selector can still contribute. Coexecution supports
+the agent's claim but does not establish causality or temporal ordering.
+
+| `summary.status` | Public percentage |
+| --- | --- |
+| `available` | Numeric, including a meaningful 0 when a current observed explanation credits nothing. |
+| `notAssessed` | Null: no flow explanations have been recorded. |
+| `pending` | Null: change impact remains outstanding, or no eligible current explanation exists. |
+| `unavailable` | Null or an unavailable report: failed run, invalid identities, mismatching source or unreadable map. |
+| `notApplicable` | Null: no measured statements exist. |
+
+For example:
+
+```text
+Assertions 62.50% (50/80) — agent-assessed statements, whole run
+  18 assertions with flows; 7 without; 29 current flows; 3 stale; 2 draft
+Assertions not assessed — No recorded flow explanations
+Assertions pending — Source changes need impact assessment
+```
+
+A partial map can produce a useful numeric score. Counts show assertions with
+and without flows, current/draft/stale/invalid flows, unobserved assertions,
+questions and pending changes. There is no `mapped` or `complete` status. The
+number of missing semantic flows is unknown. `current` means the claim has no
+freshness/reference/question blockers; selector evidence is reported separately.
+Diagnostic statement counts remain inspectable while change impact is pending;
+the public percentage stays null.
+
+JSON regular reports expose this under `data.assertionCoverage.summary`; detailed
+assertion reports use `data.summary`. `assertionCoverage.available` indicates
+whether the report could be read, while `summary.status` describes whether its
+percentage is available. Structural filters do not change the assertion score:
+it describes the whole run, as its label says. MC/DC remains a separate metric.
+`revision` binds each response to the map, managed state and run evidence.
+
+## Resource commands
+
+| Command | Shows |
+| --- | --- |
+| `runs <run> assertions` | Recognized and authored assertions, including sites missing from the map. |
+| `runs <run> assertions --needs-attention` | Assertions without flows, with open questions, or with flows needing investigation/evidence. |
+| `runs <run> assertion <id>` | One exact assertion and its graph, freshness, selectors and evidence. |
+| `runs <run> source <path>` | Matching current source, printed as code with line numbers. |
+| `runs <run> assertions files` | Input paths, byte sizes and SHA-256 hashes; works even with a stale checkout. |
+| `runs <run> assertions report --view <view>` | `summary`, `assertions`, `statements`, `tests`, `changes`, `creditedLines`, or `unassertedLines`. |
+| `runs <run> assertions validate --json` | Shape/reference errors, changes and flow `expectedBasis` tokens. Read-only. |
+| `runs <run> assertions check` | Read-only policy gates. |
+
+`--file <path>` filters assertion/statement/line items, never the summary.
+List views support `--offset <n> --limit <1..1000>` and `--json`. Follow
+`pagination.nextOffset`; restart a multi-page read if `revision` changes.
+Source defaults to 20 lines and prints `34 │ code here`. Source JSON uses
+`{line, text}` items for integrations. It is usable with malformed map JSON but
+requires current files matching the run. There is no separate inventory command.
+
+Large validation responses can be paged with `validate --view flows|changes|errors`
+and `--offset`/`--limit`. Entries appear under `items`; overall `valid` and
+`errorCount` still cover the whole map. Default validation returns all entries.
+
+`validate` returns exit 2 for syntax/reference errors, not merely null/stale
+acknowledgements. `check` returns exit 2 for invalid references, failed runs,
+unacknowledged/stale/invalid flows, open questions, pending impact assessments,
+or an unverifiable checkout. An incremental map with untouched empty sites is
+allowed by basic `check`. Optional gates:
+
+- `--require-mappings`: every recognized assertion observed passing has at least
+  one eligible current explanation. A zero-credit explanation qualifies. This
+  is not a claim that every flow is known.
+- `--require-observed`: every listed assertion and every explicit selector has
+  matching passing evidence. Empty selectors fail this gate.
+- `--min <0..100>`: the public statement percentage must be numeric and meet the target.
+
+## Reuse after source or test changes
+
+Run the same test command again. Before publication, Supercov selects the newest
+usable map for that exact command and language. A malformed newer candidate is
+reported under `inheritance.skipped`; fallback claims require fresh acknowledgement.
+Publication writes evidence, map and managed state together atomically. Previous
+runs stay untouched. Finish editing the newest map before starting its successor.
+
+The run stores a hash manifest and assertion identities, not complete source
+files. Current project files supply the source for investigation. Managed
+`assertions.state.json` (version 3) binds evidence and input identities and stores
+invalidation generations, outstanding change records and inheritance metadata.
+It contains no second semantic graph. Only `assertions.json` is agent-editable.
+No query changes either file.
+
+A flow depends on the assertion file, each selected test file, every node file,
+and extra `watch` files. Any byte change in those files, including comments or
+blank lines, invalidates that flow. Other sibling flows can remain current.
+Changes to the assertion/observation affect all its flows. Context/dependency/
+instrumenter changes invalidate inherited claims conservatively. Flow tokens
+bind the claim (excluding their own token), context, sorted dependency hashes,
+and effective invalidation generation; they exclude run IDs and runtime events.
+
+Exact identities retain IDs. Unique snippets or unique identical-file renames
+can relocate as suggestions. A sole unmatched old/new assertion in the same file
+can retain its ID as a changed candidate. Ambiguous/removed assertions remain
+under `retiredAssertions` with explanations. Unresolved changes stay stale across
+reruns and reverts until acknowledged. Every new run supplies fresh evidence.
+
+Every added, edited or removed file in the captured analysis scope enters the
+change queue, even if a flow already watches it. Known dependencies are a starting
+point, not proof that other flows are unaffected. Read `--view changes` and edit:
+
+```json
+{
+  "changeAssessments": [{
+    "id": "c_copy_from_changes_view",
+    "basis": null,
+    "affectedFlows": ["a_example/return-value"],
+    "explanation": "The edit affects the returned value; the independent sibling computation is unchanged."
+  }]
+}
+```
+
+This is an excerpt. Include all `knownFlows` that still exist, plus any additional
+claims affected by the change. Repair missing watches when appropriate. An empty
+list needs an explanation of why existing claims are unaffected; it does not
+mean the changed code is tested. Save responses, validate, copy examined change
+tokens, save, then validate again for final flow tokens. Impact assignment can
+invalidate another flow, so this order matters. Tokens have no circular dependency.
+Deleting a response does not clear its managed change record.
+
+On the next run, resolved changes are folded into per-flow generation baselines
+and retired. Unchanged equivalent runs preserve current tokens. Pending records
+survive and their responses must match the current input manifest. The scope is
+finite: uncaptured external state is not automatically monitored.
+
+Version-1 maps remain importable during carry; graphs and IDs are preserved,
+span watches become file watches, and all flow tokens start null. Former test
+names are retained in investigation questions until file-qualified selectors are
+provided. Missing sink edges are not invented. Legacy evidence may contain full
+source, used only to recover hashes. No migration writes into the old run.
+
+## Limits and validation
+
+The JS/TS verification matrix covers Node ESM/CommonJS/native TypeScript, Vitest
+TypeScript, Jest CommonJS and Playwright's Node-side TypeScript assertions,
+including aliases, shared parameterized sites and async rejection matchers.
+Unsupported/custom sites can be documented, but JS/TS credit requires the exact
+recognized expression and operation in runtime evidence. This does not infer
+browser assertion identity or data flows through external services.
+
+The map is an agent assessment. A credited statement can be changed without
+failing a test when the change preserves the observed property. Neither 100%
+assertion coverage nor 100% MC/DC proves mutation resistance or safety for every
+change. Use the observation and graph to select tests and identify missing
+checks; sample mutation audits can independently evaluate the authored claims.
+See [the agent workflow](assertion-agent.md), [assertion evidence](assertion-evidence.md),
+and [verification](verification.md).

package/docs/assertions.md

@@ -0,0 +1,82 @@
+# Understanding assertion coverage
+
+After a normal test run, a coding agent can map what each JavaScript or
+TypeScript assertion checks into the run's `assertions.json`. Supercov reads
+that map alongside the recorded execution evidence and displays an assertion
+percentage in the regular coverage report.
+
+```sh supercov
+npx supercov -- npm test
+npx supercov runs latest assertions --json
+```
+
+The run creates the map automatically, reusing the newest available map for the
+same test command and language. Pin the returned run ID and edit `data.map`.
+Ask your agent to follow
+`supercov docs assertion-agent`, read the current project source, and complete the map.
+Then validate and save the acknowledgement tokens for examined flows:
+
+```sh supercov-example
+npx supercov runs <run> assertions validate --json
+# Copy examined expectedBasis tokens into assertions.json; save again.
+npx supercov runs <run> assertions check --require-mappings --require-observed --json
+npx supercov runs <run>
+```
+
+The **Assertions** row appears beside Lines, Branches and MC/DC. It is the
+percentage of measured statements credited by current agent-authored flows,
+with exact passing assertion identity and execution in the same test. It uses
+the whole run with matching current source even when structural coverage is filtered. Incomplete
+maps remain useful; unmapped or dirty flows earn no credit.
+
+## Check what the test asserts
+
+Suppose `src/shipping.js` contains:
+
+```js
+export function shippingCost() {
+  return 4;
+}
+```
+
+These checks all call the function, but they test different things. Here,
+`assert` comes from `node:assert/strict`:
+
+| Assertion | What it checks |
+| --- | --- |
+| `assert.equal(shippingCost(), 4)` | The cost is exactly `4`. Returning `5` would fail. |
+| `assert.ok(shippingCost())` | The cost is truthy. Returning `5` would still pass. |
+| `shippingCost(); assert.equal(7, 7)` | Nothing about the returned cost. The assertion compares two constants. |
+
+Line coverage can be the same in all three cases. The useful test is the one
+that checks the behavior you need to preserve.
+
+The same applies to other results: checking the number of log calls does not
+check their messages, and checking one substring does not check the whole response.
+
+## Inspect and improve the map
+
+```sh supercov-example
+npx supercov runs <run> assertions --limit 5
+npx supercov runs <run> assertion <assertion-id>
+npx supercov runs <run> source src/shipping.js
+npx supercov runs <run> assertions --view statements --file src/shipping.js --limit 20
+```
+
+Each assertion keeps its exact test source anchor, the behavior it observes,
+and flows to explicit production statements. Follow those links when deciding
+whether a test needs another scenario or a stronger assertion. The model owns
+the semantic assessment; Supercov validates syntax, source references, evidence
+and freshness without reconstructing the reasoning.
+
+After changing code or tests, run the same suite command again. Its new map
+automatically carries forward unchanged entries;
+changed or ambiguous references stay dirty until reviewed. Source files are
+read from the project; each run retains file hashes and the map, without storing
+complete source copies. A stale checkout makes assertion coverage unavailable
+until tests are rerun. See the
+[map reference](assertion-maps.md) for the format, commands and limitations.
+
+MC/DC measures independent condition effects. Assertion coverage measures the
+statements linked to checks by the reviewed map. Maximizing either number does
+not prove every edit will fail a test: the exact property in `observes` matters.

package/docs/cli.md

@@ -4,7 +4,7 @@ Supercov has one command for measuring a suite and a small set of commands for
 reading the result. Text output is designed for people and coding agents. Add
 `--json` only when an integration needs a stable machine-readable response.
 
-```sh
+```sh supercov
 npx supercov --help
 ```
 
@@ -17,7 +17,9 @@ npx supercov --help
 | Read the newest run | `npx supercov runs latest` |
 | Find useful gaps | `npx supercov runs latest gaps` |
 | Inspect one file | `npx supercov runs latest file <path>` |
-| Inspect assertion evidence (JS/TS) | `npx supercov runs latest assertions` |
+| List assertions and their status | `npx supercov runs latest assertions` |
+| Inspect one assertion and its flows | `npx supercov runs latest assertion <id>` |
+| Read matching current source code | `npx supercov runs latest source <path>` |
 | Compare two runs | `npx supercov diff <older> <newer>` |
 | Combine shards | `npx supercov merge <id> <id> [...]` |
 | Remove local data | `npx supercov clean` |
@@ -25,13 +27,13 @@ npx supercov --help
 
 ## Measure a test command
 
-```sh
+```sh supercov
 npx supercov -- <test command>
 ```
 
 Everything after `--` is passed to the test command:
 
-```sh
+```sh supercov
 npx supercov -- npm test
 npx supercov -- npx playwright test --project=chromium
 npx supercov -- cargo test
@@ -43,7 +45,7 @@ preserves the wrapped command's exit status, so it can remain a CI gate.
 
 ## List and select runs
 
-```sh
+```sh supercov
 npx supercov runs
 npx supercov runs --limit 5
 npx supercov runs latest
@@ -56,7 +58,7 @@ sessions.
 
 ## Query a run
 
-```sh
+```sh supercov
 npx supercov runs <run-id> [query] [options]
 ```
 
@@ -72,12 +74,14 @@ npx supercov runs <run-id> [query] [options]
 | `kinds` | Group coverage by test level, such as unit or E2E |
 | `runners` | Group coverage by test runner |
 | `scope` | Review included, excluded, and ambiguous source files |
-| `assertions` | Analyze source-to-assertion evidence, gaps, and limits (JS/TS) |
+| `assertions` | List assertions, including sites without flows, with freshness and execution status |
+| `assertion <id>` | Inspect one assertion and its authored flows |
+| `source <path>` | Read matching current project source with line numbers |
 | `minimize` | Find a small test subset that preserves a coverage target |
 
 Common examples:
 
-```sh
+```sh supercov
 npx supercov runs latest gaps --limit 10
 npx supercov runs latest file app/routes/checkout.ts
 npx supercov runs latest decision app/routes/checkout.ts:42
@@ -87,18 +91,29 @@ npx supercov runs latest test "checkout retry"
 
 Run any query with `--help` to see only the options valid for that query:
 
-```sh
+```sh supercov
 npx supercov runs latest --help
 npx supercov runs latest file --help
 npx supercov runs latest assertions --help
 ```
 
-The npm-only `assertions` query runs after tests against matching source. It
-reports unverified candidates, not a proven assertion score or permission to
-change behavior. Its filters differ from the structural queries below; see
-[assertion evidence](assertion-evidence.md) for requirements, pagination, and
-optional assertion hints. The guide is also available through
-`npx supercov docs assertion-evidence`.
+Assertion queries read the run-owned map. `source <path>` reads the matching current
+file directly. It prints source code with line numbers, preserving indentation;
+add `--json` only when you want structured `{line, text}` items. `--offset` is
+zero-based and `--limit` controls the number of source lines. Source and assertion analysis require the current
+checkout to match the run. Changed source makes assertion coverage unavailable;
+rerun tests to inherit mappings. The old `assertions inventory` and nested
+`assertions source --file` commands are replaced by these resource queries.
+Use read-only `assertions validate --json` to obtain expected acknowledgement tokens.
+After investigating, copy those tokens into `assertions.json`, save, and run
+`assertions check`. The `review` command is removed. `--require-mappings` requires
+a current explanation per recognized passing site, without implying completeness.
+Use `assertions --needs-attention` and `assertions report --view changes` to resume work.
+The regular run summary automatically includes the assertion percentage when
+that map exists, in text and `data.assertionCoverage` JSON. Read
+[Understanding assertion coverage](assertions.md) for the workflow or run
+`npx supercov docs assertion-agent` for instructions to give a coding agent.
+The [map reference](assertion-maps.md) covers syntax and verification gates.
 
 ## Narrow a view
 
@@ -115,14 +130,14 @@ Collection output includes a copyable command for the next page.
 
 For a large file, group and rank its decisions:
 
-```sh
+```sh supercov
 npx supercov runs latest file app/routes/checkout.ts \
   --group decision --sort missing
 ```
 
 ## Compare runs
 
-```sh
+```sh supercov
 npx supercov diff <older-run> <newer-run>
 ```
 
@@ -132,13 +147,13 @@ Neither input run is changed.
 
 The same filters can focus a comparison:
 
-```sh
+```sh supercov
 npx supercov diff <older-run> <newer-run> --kind e2e
 ```
 
 ## Find a smaller test set
 
-```sh
+```sh supercov
 npx supercov runs latest minimize
 npx supercov runs latest minimize --metric branches --target 90
 ```
@@ -150,7 +165,7 @@ selected metric.
 
 ## Combine shards
 
-```sh
+```sh supercov
 npx supercov merge <shard-a> <shard-b> <shard-c>
 ```
 
@@ -160,7 +175,7 @@ incompatible merge rather than publishing a misleading aggregate.
 
 ## Clean local data
 
-```sh
+```sh supercov
 npx supercov clean --dry-run
 npx supercov clean --keep 20
 npx supercov clean
@@ -172,7 +187,7 @@ storage.
 
 ## Read bundled documentation
 
-```sh
+```sh supercov
 npx supercov docs
 npx supercov docs getting-started
 npx supercov docs troubleshooting
@@ -190,7 +205,7 @@ terminal or offline environment after the package has been downloaded.
 
 Examples:
 
-```sh
+```sh supercov
 SUPERCOV_SOURCE_ROOTS=src,app npx supercov -- npm test
 SUPERCOV_TEST_KIND=e2e npx supercov -- npx playwright test
 ```

package/docs/coverage-model.md

@@ -17,7 +17,7 @@ runner boundary.
 Supercov keeps those states separate. It does not turn “unknown” into
 “uncovered,” and it does not round either one away to produce a reassuring 100%.
 
-```sh
+```sh supercov
 npx supercov runs latest
 npx supercov runs latest gaps
 npx supercov runs latest scope
@@ -39,7 +39,7 @@ The exact obligations depend on the language and source construct. You do not
 need to reason about all of them at once. Start with a file, then open a decision
 or line only when the missing behavior needs explanation:
 
-```sh
+```sh supercov
 npx supercov runs latest file app/checkout/session.ts
 npx supercov runs latest decision app/checkout/session.ts:64
 npx supercov runs latest line app/checkout/session.ts:64
@@ -71,6 +71,9 @@ does not mean the product has no bugs, the assertions are meaningful, or every
 possible input was tested. Review test quality and user-visible behavior, not
 only the percentage.
 
+To review what your JavaScript and TypeScript tests actually check, see
+[Understanding assertions](assertions.md).
+
 If source cannot be measured safely, Supercov reports a measurement limit
 instead of claiming completeness.
 
@@ -92,7 +95,7 @@ each runner.
 
 The same stored run can answer different questions:
 
-```sh
+```sh supercov
 npx supercov runs latest --filter all
 npx supercov runs latest --filter passed
 npx supercov runs latest --filter failed
@@ -103,7 +106,7 @@ attempts. `failed` isolates failed attempts, including failed retries.
 
 You can also focus on a test level or runner:
 
-```sh
+```sh supercov
 npx supercov runs latest gaps --kind e2e
 npx supercov runs latest gaps --runner playwright
 ```
@@ -115,13 +118,13 @@ percentage that was computed from a different set of tests.
 
 If the summary reports ambiguous source scope, inspect it:
 
-```sh
+```sh supercov
 npx supercov runs latest scope
 ```
 
 When first-party source lives in unusual directories, declare it explicitly:
 
-```sh
+```sh supercov
 SUPERCOV_SOURCE_ROOTS=src,app npx supercov -- npm test
 ```
 
@@ -138,3 +141,12 @@ the bundler consumes them at build time; nothing about them runs.
 
 Choose roots that describe code the repository owns. Do not include dependencies
 or generated output merely to make a warning disappear.
+
+## Assertion percentage
+
+When a run has an `assertions.json` map, its regular summary also shows
+agent-assessed assertion coverage: credited measured statements divided by all
+measured statements. This row always describes the whole archived run,
+independently of `--filter`, `--kind` and `--runner`. It is separate from the
+structural metrics above. See [assertion maps](assertion-maps.md) for credit,
+freshness and incomplete-map rules.

package/docs/evidence.md

@@ -6,7 +6,7 @@ without rerunning the tests.
 
 ## Find the run you want
 
-```sh
+```sh supercov
 npx supercov runs
 npx supercov runs --limit 10
 npx supercov runs latest
@@ -23,7 +23,7 @@ A run id is immutable. `latest` is only a convenient selector.
 
 ## Ask the same run different questions
 
-```sh
+```sh supercov
 npx supercov runs latest gaps --limit 10
 npx supercov runs latest file app/checkout/session.ts
 npx supercov runs latest line app/checkout/session.ts:64
@@ -45,7 +45,7 @@ new work from it.
 
 ## Focus on passed or failed attempts
 
-```sh
+```sh supercov
 npx supercov runs latest --filter all
 npx supercov runs latest --filter passed
 npx supercov runs latest --filter failed
@@ -60,7 +60,7 @@ reports that can drift apart.
 
 ## Compare before and after
 
-```sh
+```sh supercov
 npx supercov diff <older-run> <newer-run>
 ```
 
@@ -76,7 +76,7 @@ need to reproduce the result.
 
 ## Combine distributed shards
 
-```sh
+```sh supercov
 npx supercov merge <shard-a> <shard-b> <shard-c>
 ```
 
@@ -100,7 +100,7 @@ Completed runs live under `.supercov/runs/<run-id>/`. The isolated workspace and
 instrumented build cache may use more space than the compressed run itself.
 Nothing is pruned in the background.
 
-```sh
+```sh supercov
 npx supercov clean --dry-run
 npx supercov clean --keep 20
 npx supercov clean