@crvouga/atlas 0.11.0 → 0.13.0

package/dist/server/src/openapi.js

@@ -14,7 +14,7 @@
  */
 import { z } from 'zod/v4';
 import { ProjectsSchema } from '../../schema/src/project.js';
-import { EffectiveDeltaSchema, EffectiveEvidenceSchema, EvidencePageSchema, HealthSchema, LayerRowsSchema, CheckDetailSchema, OutlineSchema, ProblemSchema, ReadySchema, ServerInfoSchema, StoreListingSchema, StoreWriteResultSchema, ChecksResultSchema, HelloEventSchema, ReportEventSchema, PingEventSchema, TestCatalogSchema, TestHistorySchema, RunListSchema, RunDetailSchema } from '../../schema/src/api.js';
+import { EffectiveDeltaSchema, EffectiveEvidenceSchema, EvidencePageSchema, HealthSchema, LayerRowsSchema, CheckDetailSchema, OutlineSchema, ProblemSchema, ReadySchema, ServerInfoSchema, StoreListingSchema, StoreWriteResultSchema, ChecksResultSchema, HelloEventSchema, ReportEventSchema, PingEventSchema, TestCatalogSchema, CatalogHealthSchema, TestHistorySchema, RunListSchema, RunDetailSchema } from '../../schema/src/api.js';
 import { LiveRunSchema, LiveRunStartSchema, LiveRunUpdateSchema, ServerEditableSettingsSchema, ServerSettingsSnapshotSchema, AtlasChangeSchema, PublishChecksSchema, ReportSourcesSchema, ReportStatusSchema, RunsIndexSchema, SpecIndexSchema } from '../../schema/src/index.js';
 /** The version of the API described, `major.minor.patch`: the minor grows when an operation or field is added, the major never within `/api`. */
 export const API_VERSION = '1.4.0';
@@ -35,7 +35,7 @@ const COMPONENTS = {
     PublishChecks: [PublishChecksSchema.partial({ recordedAtMs: true }), 'input'], ChecksResult: [ChecksResultSchema, 'output'],
     StoreListing: [StoreListingSchema, 'output'], StoreWriteResult: [StoreWriteResultSchema, 'output'],
     Outline: [OutlineSchema, 'output'], EvidencePage: [EvidencePageSchema, 'output'], LayerRows: [LayerRowsSchema, 'output'], CheckDetail: [CheckDetailSchema, 'output'],
-    TestCatalog: [TestCatalogSchema, 'output'], TestHistory: [TestHistorySchema, 'output'], RunList: [RunListSchema, 'output'], RunDetail: [RunDetailSchema, 'output'],
+    TestCatalog: [TestCatalogSchema, 'output'], CatalogHealth: [CatalogHealthSchema, 'output'], TestHistory: [TestHistorySchema, 'output'], RunList: [RunListSchema, 'output'], RunDetail: [RunDetailSchema, 'output'],
     SpecIndex: [SpecIndexSchema, 'output'], ReportSources: [ReportSourcesSchema, 'output'], RunsIndex: [RunsIndexSchema, 'output'],
     RunEvent: [LiveRunSchema, 'output'], HelloEvent: [HelloEventSchema, 'output'], ReportEvent: [ReportEventSchema, 'output'], AtlasChangeEvent: [AtlasChangeSchema, 'output'], PingEvent: [PingEventSchema, 'output']
 };
@@ -279,6 +279,22 @@ const BASE_OPERATIONS = [
         ],
         responses: { '200': { ...json('The catalog.', 'TestCatalog'), headers: { ETag: { description: 'Changes with the report, its history and the query.', schema: str } } }, '304': { description: 'Unchanged since the `If-None-Match` ETag.' }, '401': UNAUTHORIZED, '503': NOT_READY }
     },
+    {
+        route: 'GET /api/reports/tests/health', path: '/api/reports/tests/health', operationId: 'getCatalogHealth', tag: 'Report', role: 'read',
+        summary: 'Why specs, domains and counts disagree',
+        description: [
+            'Diagnoses the report\'s metadata, so a domain filter or a coverage percentage can be trusted or fixed at its source. It reads; it never changes a status, a slot or a winner.',
+            '',
+            '`counts` keeps the denominators apart: spec files, defined specs, specs with an executed test (and those without: the defined coverage gaps), tests, outlines, examples and per-environment observations. `reconciliation` walks from the Specs count to the Tests count. `findings` name ambiguous and unmatched spec paths, identical or same-titled specs, a domain shared by nearly every spec, tests with no spec, checks that fall back to their title as identity and root mappings that matched nothing.',
+            '',
+            'Two paths are one logical spec only when a `root` mapping relates them (`from>to`: paths under `from` are the same specs as paths under `to`; an empty `from` matches every path). Without one, similar paths are reported as ambiguous and never merged. A check\'s label `outline` names the outline its example belongs to. Send `format=markdown` for Markdown.'
+        ].join('\n'),
+        parameters: [
+            { name: 'root', in: 'query', description: 'A root mapping `from>to`, URL-encoded. Repeatable or comma-separated.', schema: str, example: '>specs/' },
+            { name: 'format', in: 'query', description: '`markdown` for a Markdown report instead of JSON.', schema: { type: 'string', enum: ['json', 'markdown'] } }
+        ],
+        responses: { '200': { ...json('The diagnostics.', 'CatalogHealth'), headers: { ETag: { description: 'Changes with the report, its history and the mappings.', schema: str } } }, '304': { description: 'Unchanged since the `If-None-Match` ETag.' }, '401': UNAUTHORIZED, '503': NOT_READY }
+    },
     {
         route: 'GET /api/reports/tests/history', path: '/api/reports/tests/history', operationId: 'getTestHistory', tag: 'Report', role: 'read',
         summary: 'One test and every result recorded for it',

package/docs/reference/http-api.md

@@ -504,6 +504,40 @@ Scoped to one project. The same project may be selected on the unprefixed API us
 
 Responses: `200` The catalog.; `304` Unchanged since the `If-None-Match` ETag.; `401` No token, or an unknown one. Send `Authorization: Bearer <token>`.; `503` The server is still reading its backends. Retry after the number of seconds in `Retry-After`.
 
+### Why specs, domains and counts disagree
+
+`GET /api/reports/tests/health` · role: read
+
+Diagnoses the report's metadata, so a domain filter or a coverage percentage can be trusted or fixed at its source. It reads; it never changes a status, a slot or a winner.
+
+`counts` keeps the denominators apart: spec files, defined specs, specs with an executed test (and those without: the defined coverage gaps), tests, outlines, examples and per-environment observations. `reconciliation` walks from the Specs count to the Tests count. `findings` name ambiguous and unmatched spec paths, identical or same-titled specs, a domain shared by nearly every spec, tests with no spec, checks that fall back to their title as identity and root mappings that matched nothing.
+
+Two paths are one logical spec only when a `root` mapping relates them (`from>to`: paths under `from` are the same specs as paths under `to`; an empty `from` matches every path). Without one, similar paths are reported as ambiguous and never merged. A check's label `outline` names the outline its example belongs to. Send `format=markdown` for Markdown.
+
+- `root` (query): A root mapping `from>to`, URL-encoded. Repeatable or comma-separated.
+- `format` (query): `markdown` for a Markdown report instead of JSON.
+- `project` (query): Project slug. Alternatively send X-Atlas-Project or use the project-prefixed route. Omit for the default project. Conflicting selectors are refused.
+
+Responses: `200` The diagnostics.; `304` Unchanged since the `If-None-Match` ETag.; `401` No token, or an unknown one. Send `Authorization: Bearer <token>`.; `503` The server is still reading its backends. Retry after the number of seconds in `Retry-After`.
+
+### Why specs, domains and counts disagree
+
+`GET /api/projects/{project}/reports/tests/health` · role: read
+
+Diagnoses the report's metadata, so a domain filter or a coverage percentage can be trusted or fixed at its source. It reads; it never changes a status, a slot or a winner.
+
+`counts` keeps the denominators apart: spec files, defined specs, specs with an executed test (and those without: the defined coverage gaps), tests, outlines, examples and per-environment observations. `reconciliation` walks from the Specs count to the Tests count. `findings` name ambiguous and unmatched spec paths, identical or same-titled specs, a domain shared by nearly every spec, tests with no spec, checks that fall back to their title as identity and root mappings that matched nothing.
+
+Two paths are one logical spec only when a `root` mapping relates them (`from>to`: paths under `from` are the same specs as paths under `to`; an empty `from` matches every path). Without one, similar paths are reported as ambiguous and never merged. A check's label `outline` names the outline its example belongs to. Send `format=markdown` for Markdown.
+
+Scoped to one project. The same project may be selected on the unprefixed API using ?project= or X-Atlas-Project. Unknown projects return 404 on reads and are created by an authenticated upload.
+
+- `project` (path, required): Project slug. Alternatively send X-Atlas-Project or use the project-prefixed route. Omit for the default project. Conflicting selectors are refused.
+- `root` (query): A root mapping `from>to`, URL-encoded. Repeatable or comma-separated.
+- `format` (query): `markdown` for a Markdown report instead of JSON.
+
+Responses: `200` The diagnostics.; `304` Unchanged since the `If-None-Match` ETag.; `401` No token, or an unknown one. Send `Authorization: Bearer <token>`.; `503` The server is still reading its backends. Retry after the number of seconds in `Retry-After`.
+
 ### One test and every result recorded for it
 
 `GET /api/reports/tests/history` · role: read

package/docs/reference/reports.md

@@ -330,6 +330,227 @@ export async function readBundleIndex(
 
 Reads and parses the bundle index at `key`; an index that is not there is an empty bundle (`{}`). Invalid JSON throws.
 
+### Catalog health: spec identity, domains and denominators
+
+Source: `packages/reports/src/catalog-health.ts`. Import: `@crvouga/atlas/reports/catalog-health`
+
+Explains why the Specs and the Tests of a report may disagree, and what a producer or an operator can change about it.
+`catalogHealth` reads a `CatalogModel` (the tests of a report and the specs it is laid over) and writes a
+`CatalogHealth` document:
+
+- **Spec identity.** The same promise can reach Atlas under two paths (`checkout/cart.feature` published,
+  `specs/checkout/cart.feature` recorded). Atlas joins two paths only when a declared root mapping (`RootMapping`)
+  relates them, and then shows one logical spec with its original paths. Without a mapping it never merges by a
+  similar title or file name: it reports the pair as ambiguous and names the candidates.
+- **Domains.** A domain is whatever the spec's metadata says. When almost every spec shares one value, often the root
+  folder, the document says so; it never replaces explicit metadata.
+- **Denominators.** Defined specs, specs with an executed test, tests (check identities), examples and per-environment
+  observations are different numbers. `reconciliation` walks from the number the Specs view shows to the number the
+  Tests view groups by, step by step, and `counts.scenarios` tells one outline, its examples and their observations apart.
+- **Fallback identity.** A check whose id is its title has no stable id; renaming it starts a new check. Counted, not
+  guessed at.
+
+It only reads: it never changes a status, a slot or a winner, so it cannot disagree with the report it describes.
+Optional label `outline` on a check names the scenario outline its example belongs to.
+
+See docs/server.md#reading-the-report-as-an-agent
+
+#### `CATALOG_HEALTH_VERSION`
+
+```ts
+export const CATALOG_HEALTH_VERSION = …
+```
+
+The version of the `CatalogHealth` document. Only optional fields are added within it.
+
+#### `HEALTH_ITEM_LIMIT`
+
+```ts
+export const HEALTH_ITEM_LIMIT = …
+```
+
+The most paths listed in one finding; its `count` is always the whole.
+
+#### `RootMapping`
+
+```ts
+export type RootMapping = { readonly from: string; readonly to: string };
+```
+
+Declares that paths under `from` are the same specs as paths under `to`, e.g. `{ from: '', to: 'specs/' }`. Empty `from` matches every path.
+
+#### `HealthItem`
+
+```ts
+export type HealthItem = {
+  readonly path: string;
+  /** Other paths it could be the same promise as, when any; Atlas has not merged them. */
+  readonly candidates?: readonly { readonly path: string; readonly reason: string }[];
+};
+```
+
+One thing worth a look.
+
+#### `HealthCode`
+
+```ts
+export type HealthCode =
+  | 'ambiguous-spec-path'
+  | 'unmatched-spec-path'
+  | 'duplicate-spec-content'
+  | 'duplicate-spec-title'
+  | 'generic-domain'
+  | 'tests-without-spec'
+  | 'no-spec-definitions'
+  | 'fallback-identity'
+  | 'unused-root-mapping'
+  | 'spec-without-execution'
+  | 'historical-only';
+```
+
+Codes of `HealthFinding.code`. The set grows; a reader treats an unknown code as informational.
+
+#### `HealthFinding`
+
+```ts
+export type HealthFinding = {
+  readonly code: HealthCode;
+  /** `warning` is something that makes a count or a filter misleading; `info` explains a number. */
+  readonly severity: 'warning' | 'info';
+  readonly message: string;
+  /** How many paths, specs or tests it affects. */
+  readonly count: number;
+  /** Up to `HEALTH_ITEM_LIMIT` of them. */
+  readonly items: readonly HealthItem[];
+};
+```
+
+A finding: what is inconsistent, how many it affects, and what to change.
+
+#### `SpecAlias`
+
+```ts
+export type SpecAlias = {
+  /** The logical spec's path after mapping. */
+  readonly path: string;
+  /** Every original path it was seen under, sorted. */
+  readonly sources: readonly string[];
+};
+```
+
+A spec that reached Atlas under more than one path and was joined by a declared root mapping.
+
+#### `ReconciliationStep`
+
+```ts
+export type ReconciliationStep = {
+  readonly code: 'merged-by-mapping' | 'defined-without-results' | 'results-without-definition';
+  readonly label: string;
+  /** The change to the running total: negative removes specs, positive adds them. */
+  readonly delta: number;
+};
+```
+
+One step from the Specs count to the Tests count.
+
+#### `CatalogHealth`
+
+```ts
+export type CatalogHealth = {
+  readonly schemaVersion: typeof CATALOG_HEALTH_VERSION;
+  readonly version: string;
+  readonly generatedAtMs: number;
+  /** True when there is no warning. Informational findings do not count. */
+  readonly ok: boolean;
+  readonly counts: {
+    readonly specs: {
+      /** Spec files the report is laid over (before mapping). */
+      readonly files: number;
+      /** Logical specs among them: files joined by a root mapping count once. */
+      readonly defined: number;
+      /** Logical specs, defined or not, with at least one test. */
+      readonly withTests: number;
+      /** Defined logical specs with a test that has a passed or failed result. They are the denominator of execution coverage. */
+      readonly executed: number;
+      /** Defined logical specs with no test that has a passed or failed result: the defined coverage gaps. */
+      readonly withoutExecution: number;
+    };
+    readonly tests: {
+      readonly total: number;
+      readonly withSpec: number;
+      readonly withoutSpec: number;
+      /** Tests whose current status is `passed`. A definition with no test never adds to it. */
+      readonly passed: number;
+      /** Tests the history holds but the report has no current result for. */
+      readonly historicalOnly: number;
+    };
+    readonly scenarios: {
+      /** Outlines: tests sharing the label `outline` count once; a test without it is its own outline. */
+      readonly outlines: number;
+      /** Concrete examples: tests (a check identity), however many environments ran them. */
+      readonly examples: number;
+      /** Current results per producer, environment and parameter set. */
+      readonly observations: number;
+      /** Observations that passed or failed. */
+      readonly executedObservations: number;
+      readonly passedObservations: number;
+    };
+  };
+  …
+```
+
+The `GET /api/reports/tests/health` document.
+
+#### `parseRootMapping`
+
+```ts
+export function parseRootMapping(text: string): RootMapping | null
+```
+
+Parses `from>to` (as `?root=` gives it) into a mapping. Returns null when there is no `>`. Whitespace around each side is trimmed.
+
+#### `parseRootMappings`
+
+```ts
+export function parseRootMappings(params: URLSearchParams): RootMapping[]
+```
+
+Reads the repeatable `root` search parameter: each value `from>to`, several may be comma-separated. Values without `>` are ignored.
+
+#### `canonicalSpecPath`
+
+```ts
+export function canonicalSpecPath(path: string, roots: readonly RootMapping[]): { readonly path: string; readonly mapping: RootMapping | null }
+```
+
+The logical path of a spec path: the path Atlas already normalises (`specPath`), after the first mapping whose `from`
+is a prefix of it (the longest `from` wins). A path already under `to` is left alone. Returns the path and the mapping
+that changed it, if any.
+
+#### `catalogHealth`
+
+```ts
+export function catalogHealth(model: CatalogModel, roots: readonly RootMapping[] = []): CatalogHealth
+```
+
+Diagnoses a report's spec identity, domains and counts. `roots` are the declared path-root mappings. Pure: the same
+model and mappings give the same document, and nothing in it changes what the report says passed.
+
+**Example**
+
+```ts
+const health = catalogHealth(model, [{ from: '', to: 'specs/' }]);
+if (!health.ok) console.log(healthMarkdown(health));
+```
+
+#### `healthMarkdown`
+
+```ts
+export function healthMarkdown(health: CatalogHealth): string
+```
+
+The health document as Markdown, for an agent or a terminal.
+
 ### Catalog search, filter, group and sort
 
 Source: `packages/reports/src/catalog.ts`. Import: `@crvouga/atlas/reports/catalog`
@@ -7564,6 +7785,7 @@ const catalog = testCatalog(catalogModel(layers, { history }));
 
 - `get rev(): number { return this.#rev; }` — Changes each time a layer is added.
 - `get specs(): RecordedSpecs { return this.#specs; }` — The specs the added layers recorded.
+- `tests(): readonly { readonly key: string; readonly id: string; readonly specPath: string | null }[]` — Every test the history holds a result for (keyed as `TestSummary.key`), including tests the report no longer has a current result for.
 - `get layers(): number { return this.#seen.size; }` — How many layers were added.
 - `add(layer: LayerHeader, rows: readonly LayerRow[], specs: readonly SpecEntry[] = [], backend = layer.backend): void` — Takes in one layer: its header, its rows, the specs it recorded and the backend it was read from. A layer id already added is ignored.
 - `of(key: string): readonly TestResultEntry[]` — The recorded results of one test (by `TestSummary.key`), newest first. Empty when none.
@@ -7616,6 +7838,8 @@ export type CatalogModel = {
   readonly facets: CatalogFacets;
   readonly haystacks: ReadonlyMap<string, string>;
   readonly history: TestHistory | null;
+  /** The specs the report is laid over, sorted by path: the given ones, else those the layers recorded. What `catalogHealth` calls defined. Absent on a model built from a server's catalog document. */
+  readonly specs?: readonly SpecEntry[];
 };
 ```
 

package/docs/reference/schema.md

@@ -234,6 +234,16 @@ export const TestCatalogSchema = …
 `GET /api/reports/tests`: every test of the report with a summary, insights and facets. The summary and facets cover
 every test; `tests` is the page of those the query matched.
 
+#### `CatalogHealthSchema`
+
+```ts
+export const CatalogHealthSchema = …
+```
+
+`GET /api/reports/tests/health`: why the report's Specs, domains and counts may disagree. Counts keep the denominators
+apart (spec files, defined specs, specs with an executed test, tests, outlines, examples, observations), `reconciliation`
+walks from one to another, and `findings` name what to fix. It reads the report; it never changes what passed.
+
 #### `TestHistorySchema`
 
 ```ts

package/docs/server.md

@@ -255,6 +255,7 @@ with `format=markdown` (or `Accept: text/markdown`), and takes the project prefi
 | Every test, a summary (by status, environment, producer, domain), insights (failing, flaky, slowest) and facets | `GET /api/reports/tests` |
 | Only some: `q` (all words), `status` (or `flaky`), `environment`, `producer`, `domain`, `spec`, `tag`, `run`; `sort`, `offset`, `limit` | `GET /api/reports/tests?status=failed&environment=ios` |
 | One test: every recorded result (status, duration, environment, branch, commit, CI run), newest first | `GET /api/reports/tests/history?key=<key>` |
+| Why Specs, domains and counts disagree: ambiguous spec paths, shared domains, gaps, a reconciliation of the totals | `GET /api/reports/tests/health` |
 | The runs that recorded the report (by CI run URL, else branch and commit) | `GET /api/reports/runs` |
 | Every test one run recorded | `GET /api/reports/runs/detail?key=<run key>` |
 
@@ -267,6 +268,13 @@ curl "$ATLAS_SERVER_URL/api/projects/$ATLAS_PROJECT/reports/tests?format=markdow
   `stats` describes its recorded history: pass rate, flips, whether it is flaky and why (it passed and failed on the
   same commit, passed only after a retry, or its producer said so), durations (avg, p50, p95, min, max, last), runs
   and branches.
+- The **health** document explains the numbers instead of adding one. It keeps spec files, defined specs, specs with an
+  executed test, tests, outlines, examples and per-environment observations apart, and walks from the Specs total to
+  the Tests total. Two spec paths are one logical spec only when a mapping says so
+  (`?root=<from>><to>`, for example `?root=%3Especs/` to put `checkout/cart.feature` under `specs/`); similar paths
+  are reported as ambiguous and never merged, and a similar title is never an identity. Give a check the label
+  `outline` to say which scenario outline an example belongs to. A domain shared by nearly every spec is flagged, but
+  explicit domain metadata always stays authoritative. The document only reads: it changes no status.
 - The server keeps the newest 100 results of every test (progress reported as `running` is not history) and every run's last result per test, in memory, as layers
   arrive; it is rebuilt from the layers on restart. History never changes a result.
 - Without a published spec set, tests are grouped under the specs their layers recorded (`specs[]`: path, domain,
@@ -318,6 +326,8 @@ curl "$ATLAS_SERVER_URL/api/projects/$ATLAS_PROJECT/reports/tests?format=markdow
 | `DELETE /api/projects/{project}/store/{key}` | publish | Remove a scratch object. |
 | `GET /api/reports/tests` | read | Every test, with insights, facets and history statistics. |
 | `GET /api/projects/{project}/reports/tests` | read | Every test, with insights, facets and history statistics. |
+| `GET /api/reports/tests/health` | read | Why specs, domains and counts disagree. |
+| `GET /api/projects/{project}/reports/tests/health` | read | Why specs, domains and counts disagree. |
 | `GET /api/reports/tests/history` | read | One test and every result recorded for it. |
 | `GET /api/projects/{project}/reports/tests/history` | read | One test and every result recorded for it. |
 | `GET /api/reports/runs` | read | The runs that recorded the report. |

package/docs/ui.md

@@ -119,7 +119,7 @@ The narrowly scoped exceptions are:
 | --- | --- | --- |
 | Shared shell | Project switching, spec navigation, run selection, connection status, diagnostics, mobile index | AppShell, Burger, NavLink, Menu, Popover, NativeSelect, Drawer |
 | Project home | Tests/runs tabs, metrics, search, status/environment/domain filters, grouping, sorting, show more | Container, Tabs, SimpleGrid, Paper, TextInput, Button, Accordion |
-| Test detail | Current outcomes, statistics, duration graph, history, artifacts, recording | Drawer, Table, Badge, Alert, Stage |
+| Test detail | Current outcomes, statistics, duration graph, history, artifacts, recording; the `layer` address parameter pins it to one run's result, labelled "This run" against "Latest combined evidence" | Drawer, Table, Badge, Alert, Stage |
 | Specs | All six existing kinds, overview/index, Gherkin rules/scenarios/examples, Quint declarations/traces, DMN tables, source text | SpecHeader, Accordion, Table, CodeHighlightTabs, ResultRow |
 | Statecharts | Graph, screen/event/journey details, developer metadata, chart test results | Mantine cards/navigation and product compositions; graph exception above |
 | Evidence | Steps, retries, annotations, facts, unknown extensions, safe downloads and previews | List, Badge, Accordion, Code, Image, native media |

package/llms-full.txt

@@ -1435,6 +1435,7 @@ with `format=markdown` (or `Accept: text/markdown`), and takes the project prefi
 | Every test, a summary (by status, environment, producer, domain), insights (failing, flaky, slowest) and facets | `GET /api/reports/tests` |
 | Only some: `q` (all words), `status` (or `flaky`), `environment`, `producer`, `domain`, `spec`, `tag`, `run`; `sort`, `offset`, `limit` | `GET /api/reports/tests?status=failed&environment=ios` |
 | One test: every recorded result (status, duration, environment, branch, commit, CI run), newest first | `GET /api/reports/tests/history?key=<key>` |
+| Why Specs, domains and counts disagree: ambiguous spec paths, shared domains, gaps, a reconciliation of the totals | `GET /api/reports/tests/health` |
 | The runs that recorded the report (by CI run URL, else branch and commit) | `GET /api/reports/runs` |
 | Every test one run recorded | `GET /api/reports/runs/detail?key=<run key>` |
 
@@ -1447,6 +1448,13 @@ curl "$ATLAS_SERVER_URL/api/projects/$ATLAS_PROJECT/reports/tests?format=markdow
   `stats` describes its recorded history: pass rate, flips, whether it is flaky and why (it passed and failed on the
   same commit, passed only after a retry, or its producer said so), durations (avg, p50, p95, min, max, last), runs
   and branches.
+- The **health** document explains the numbers instead of adding one. It keeps spec files, defined specs, specs with an
+  executed test, tests, outlines, examples and per-environment observations apart, and walks from the Specs total to
+  the Tests total. Two spec paths are one logical spec only when a mapping says so
+  (`?root=<from>><to>`, for example `?root=%3Especs/` to put `checkout/cart.feature` under `specs/`); similar paths
+  are reported as ambiguous and never merged, and a similar title is never an identity. Give a check the label
+  `outline` to say which scenario outline an example belongs to. A domain shared by nearly every spec is flagged, but
+  explicit domain metadata always stays authoritative. The document only reads: it changes no status.
 - The server keeps the newest 100 results of every test (progress reported as `running` is not history) and every run's last result per test, in memory, as layers
   arrive; it is rebuilt from the layers on restart. History never changes a result.
 - Without a published spec set, tests are grouped under the specs their layers recorded (`specs[]`: path, domain,
@@ -1498,6 +1506,8 @@ curl "$ATLAS_SERVER_URL/api/projects/$ATLAS_PROJECT/reports/tests?format=markdow
 | `DELETE /api/projects/{project}/store/{key}` | publish | Remove a scratch object. |
 | `GET /api/reports/tests` | read | Every test, with insights, facets and history statistics. |
 | `GET /api/projects/{project}/reports/tests` | read | Every test, with insights, facets and history statistics. |
+| `GET /api/reports/tests/health` | read | Why specs, domains and counts disagree. |
+| `GET /api/projects/{project}/reports/tests/health` | read | Why specs, domains and counts disagree. |
 | `GET /api/reports/tests/history` | read | One test and every result recorded for it. |
 | `GET /api/projects/{project}/reports/tests/history` | read | One test and every result recorded for it. |
 | `GET /api/reports/runs` | read | The runs that recorded the report. |
@@ -3779,7 +3789,7 @@ The narrowly scoped exceptions are:
 | --- | --- | --- |
 | Shared shell | Project switching, spec navigation, run selection, connection status, diagnostics, mobile index | AppShell, Burger, NavLink, Menu, Popover, NativeSelect, Drawer |
 | Project home | Tests/runs tabs, metrics, search, status/environment/domain filters, grouping, sorting, show more | Container, Tabs, SimpleGrid, Paper, TextInput, Button, Accordion |
-| Test detail | Current outcomes, statistics, duration graph, history, artifacts, recording | Drawer, Table, Badge, Alert, Stage |
+| Test detail | Current outcomes, statistics, duration graph, history, artifacts, recording; the `layer` address parameter pins it to one run's result, labelled "This run" against "Latest combined evidence" | Drawer, Table, Badge, Alert, Stage |
 | Specs | All six existing kinds, overview/index, Gherkin rules/scenarios/examples, Quint declarations/traces, DMN tables, source text | SpecHeader, Accordion, Table, CodeHighlightTabs, ResultRow |
 | Statecharts | Graph, screen/event/journey details, developer metadata, chart test results | Mantine cards/navigation and product compositions; graph exception above |
 | Evidence | Steps, retries, annotations, facts, unknown extensions, safe downloads and previews | List, Badge, Accordion, Code, Image, native media |
@@ -4805,6 +4815,40 @@ Scoped to one project. The same project may be selected on the unprefixed API us
 
 Responses: `200` The catalog.; `304` Unchanged since the `If-None-Match` ETag.; `401` No token, or an unknown one. Send `Authorization: Bearer <token>`.; `503` The server is still reading its backends. Retry after the number of seconds in `Retry-After`.
 
+### Why specs, domains and counts disagree
+
+`GET /api/reports/tests/health` · role: read
+
+Diagnoses the report's metadata, so a domain filter or a coverage percentage can be trusted or fixed at its source. It reads; it never changes a status, a slot or a winner.
+
+`counts` keeps the denominators apart: spec files, defined specs, specs with an executed test (and those without: the defined coverage gaps), tests, outlines, examples and per-environment observations. `reconciliation` walks from the Specs count to the Tests count. `findings` name ambiguous and unmatched spec paths, identical or same-titled specs, a domain shared by nearly every spec, tests with no spec, checks that fall back to their title as identity and root mappings that matched nothing.
+
+Two paths are one logical spec only when a `root` mapping relates them (`from>to`: paths under `from` are the same specs as paths under `to`; an empty `from` matches every path). Without one, similar paths are reported as ambiguous and never merged. A check's label `outline` names the outline its example belongs to. Send `format=markdown` for Markdown.
+
+- `root` (query): A root mapping `from>to`, URL-encoded. Repeatable or comma-separated.
+- `format` (query): `markdown` for a Markdown report instead of JSON.
+- `project` (query): Project slug. Alternatively send X-Atlas-Project or use the project-prefixed route. Omit for the default project. Conflicting selectors are refused.
+
+Responses: `200` The diagnostics.; `304` Unchanged since the `If-None-Match` ETag.; `401` No token, or an unknown one. Send `Authorization: Bearer <token>`.; `503` The server is still reading its backends. Retry after the number of seconds in `Retry-After`.
+
+### Why specs, domains and counts disagree
+
+`GET /api/projects/{project}/reports/tests/health` · role: read
+
+Diagnoses the report's metadata, so a domain filter or a coverage percentage can be trusted or fixed at its source. It reads; it never changes a status, a slot or a winner.
+
+`counts` keeps the denominators apart: spec files, defined specs, specs with an executed test (and those without: the defined coverage gaps), tests, outlines, examples and per-environment observations. `reconciliation` walks from the Specs count to the Tests count. `findings` name ambiguous and unmatched spec paths, identical or same-titled specs, a domain shared by nearly every spec, tests with no spec, checks that fall back to their title as identity and root mappings that matched nothing.
+
+Two paths are one logical spec only when a `root` mapping relates them (`from>to`: paths under `from` are the same specs as paths under `to`; an empty `from` matches every path). Without one, similar paths are reported as ambiguous and never merged. A check's label `outline` names the outline its example belongs to. Send `format=markdown` for Markdown.
+
+Scoped to one project. The same project may be selected on the unprefixed API using ?project= or X-Atlas-Project. Unknown projects return 404 on reads and are created by an authenticated upload.
+
+- `project` (path, required): Project slug. Alternatively send X-Atlas-Project or use the project-prefixed route. Omit for the default project. Conflicting selectors are refused.
+- `root` (query): A root mapping `from>to`, URL-encoded. Repeatable or comma-separated.
+- `format` (query): `markdown` for a Markdown report instead of JSON.
+
+Responses: `200` The diagnostics.; `304` Unchanged since the `If-None-Match` ETag.; `401` No token, or an unknown one. Send `Authorization: Bearer <token>`.; `503` The server is still reading its backends. Retry after the number of seconds in `Retry-After`.
+
 ### One test and every result recorded for it
 
 `GET /api/reports/tests/history` · role: read

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crvouga/atlas",
-  "version": "0.11.0",
+  "version": "0.13.0",
   "description": "Atlas: specs of any kind, reported as layered evidence. Publish checks from any runner (JUnit, CTRF, a script), combine them across nodes, branches, environments and backends, gate CI on the result, and run statecharts against the real app.",
   "license": "MIT",
   "type": "module",