@crvouga/atlas 1.15.0 → 1.16.0

package/CHANGELOG.md

@@ -1,6 +1,12 @@
 # Changelog: @crvouga/atlas
 
-## 1.15.0 (2026-10-29)
+## 1.16.0 (2026-10-29)
+
+### Features
+
+- explain catalog counts and identity in a Catalog health tab with persistent root mappings (#71) ([0974e7a](https://github.com/crvouga/atlas/commit/0974e7a8d16b126c47e79a004974a629275122ad))
+
+## 1.15.0 (2026-10-28)
 
 ### Features
 

package/dist/reports/src/catalog-health.d.ts

@@ -3,10 +3,18 @@ import type { CatalogModel } from './test-catalog.js';
 export declare const CATALOG_HEALTH_VERSION = 1;
 /** The most paths listed in one finding; its `count` is always the whole. */
 export declare const HEALTH_ITEM_LIMIT = 25;
-/** Declares that paths under `from` are the same specs as paths under `to`, e.g. `{ from: '', to: 'specs/' }`. Empty `from` matches every path. */
+/** The label a producer puts on a check to give its behavior (the promise) an id that outlives renames and moves. */
+export declare const BEHAVIOR_ID_LABEL = "behavior-id";
+/** The label a producer puts on a check to give one example of a scenario outline an id of its own. */
+export declare const EXAMPLE_ID_LABEL = "example-id";
+/**
+ * Declares that paths under `from` are the same specs as paths under `to`, e.g. `{ from: '', to: 'specs/' }`. Empty `from`
+ * matches every path. `source` says where it was declared (the server's configuration or the request); it changes nothing.
+ */
 export type RootMapping = {
     readonly from: string;
     readonly to: string;
+    readonly source?: 'configuration' | 'request';
 };
 /** One thing worth a look. */
 export type HealthItem = {
@@ -18,7 +26,7 @@ export type HealthItem = {
     }[];
 };
 /** Codes of `HealthFinding.code`. The set grows; a reader treats an unknown code as informational. */
-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';
+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' | 'declared-id-split' | 'spec-without-execution' | 'historical-only';
 /** A finding: what is inconsistent, how many it affects, and what to change. */
 export type HealthFinding = {
     readonly code: HealthCode;
@@ -100,6 +108,10 @@ export type CatalogHealth = {
         readonly checks: number;
         /** Checks whose id equals their title: no stable id was given. */
         readonly fallbackIdentity: number;
+        /** Checks that declare a `behavior-id` label. Optional: absent from documents written before it existed. */
+        readonly declaredBehaviorIds?: number;
+        /** Checks that declare an `example-id` label. */
+        readonly declaredExampleIds?: number;
         readonly basis: string;
     };
     readonly domains: readonly {
@@ -110,6 +122,7 @@ export type CatalogHealth = {
         readonly from: string;
         readonly to: string;
         readonly matched: number;
+        readonly source?: 'configuration' | 'request';
     }[];
     readonly aliases: readonly SpecAlias[];
     readonly findings: readonly HealthFinding[];

package/dist/reports/src/catalog-health.js

@@ -7,6 +7,10 @@ export const HEALTH_ITEM_LIMIT = 25;
 const CANDIDATE_LIMIT = 5;
 /** Folder names that say where a spec lives, not what it is about. A domain with one of these names is likely a root folder. */
 const GENERIC_DOMAINS = new Set(['specs', 'spec', 'product', 'features', 'feature', 'tests', 'test', 'e2e', 'src', 'app', 'docs', 'overview', 'root', 'default']);
+/** The label a producer puts on a check to give its behavior (the promise) an id that outlives renames and moves. */
+export const BEHAVIOR_ID_LABEL = 'behavior-id';
+/** The label a producer puts on a check to give one example of a scenario outline an id of its own. */
+export const EXAMPLE_ID_LABEL = 'example-id';
 /** Parses `from>to` (as `?root=` gives it) into a mapping. Returns null when there is no `>`. Whitespace around each side is trimmed. */
 export function parseRootMapping(text) {
     const at = text.indexOf('>');
@@ -164,6 +168,21 @@ export function catalogHealth(model, roots = []) {
     const fallback = model.tests.filter(test => test.id === test.title);
     if (fallback.length)
         findings.push(finding('fallback-identity', 'info', 'These checks use their title as their id. A check is its spec path and id, so renaming one starts a new check and splits its history. Have the producer send a stable `id`.', fallback.map(test => ({ path: test.id })), fallback.length));
+    const split = [];
+    for (const label of [BEHAVIOR_ID_LABEL, EXAMPLE_ID_LABEL]) {
+        const byId = new Map();
+        for (const test of model.tests) {
+            const id = test.labels[label];
+            if (id)
+                byId.set(id, [...(byId.get(id) ?? []), test]);
+        }
+        for (const [id, tests] of [...byId].sort(([a], [b]) => byText(a, b))) {
+            if (tests.length > 1)
+                split.push({ path: `${label}=${id}`, candidates: tests.map(test => test.specPath ? `${test.specPath}  ${test.id}` : test.id).sort(byText).slice(0, CANDIDATE_LIMIT).map(path => ({ path, reason: `same ${label}` })) });
+        }
+    }
+    if (split.length)
+        findings.push(finding('declared-id-split', 'info', 'These declared ids sit on more than one check: the promise was renamed or moved, or two checks claim it. Atlas keeps the checks apart (a check is its spec path and id), so their histories are separate.', split));
     const unused = ordered.filter(mapping => !matched.get(mapping)?.size);
     if (unused.length)
         findings.push(finding('unused-root-mapping', 'warning', 'These root mappings matched no spec path. Check `from` against the paths in the report.', unused.map(mapping => ({ path: `${mapping.from}>${mapping.to}` }))));
@@ -213,10 +232,12 @@ export function catalogHealth(model, roots = []) {
         identity: {
             checks: model.tests.length,
             fallbackIdentity: fallback.length,
-            basis: 'A check is its spec path and its id. A check whose producer sent no id is known by its title, so a rename is a new check; a spec is known by its path, joined to another only by a declared root mapping.'
+            declaredBehaviorIds: model.tests.filter(test => test.labels[BEHAVIOR_ID_LABEL]).length,
+            declaredExampleIds: model.tests.filter(test => test.labels[EXAMPLE_ID_LABEL]).length,
+            basis: 'A check is its spec path and its id. A check whose producer sent no id is known by its title, so a rename is a new check; a spec is known by its path, joined to another only by a declared root mapping. The labels behavior-id and example-id are counted and checked for ids shared by several checks; they do not change which check a result belongs to.'
         },
         domains,
-        roots: ordered.map(mapping => ({ from: mapping.from, to: mapping.to, matched: matched.get(mapping)?.size ?? 0 })),
+        roots: ordered.map(mapping => ({ from: mapping.from, to: mapping.to, matched: matched.get(mapping)?.size ?? 0, ...(mapping.source ? { source: mapping.source } : {}) })),
         aliases,
         findings
     };

package/dist/schema/src/api.d.ts

@@ -2808,6 +2808,8 @@ export declare const CatalogHealthSchema: z.ZodObject<{
     identity: z.ZodObject<{
         checks: z.ZodNumber;
         fallbackIdentity: z.ZodNumber;
+        declaredBehaviorIds: z.ZodOptional<z.ZodNumber>;
+        declaredExampleIds: z.ZodOptional<z.ZodNumber>;
         basis: z.ZodString;
     }, z.core.$loose>;
     domains: z.ZodArray<z.ZodObject<{
@@ -2818,6 +2820,10 @@ export declare const CatalogHealthSchema: z.ZodObject<{
         from: z.ZodString;
         to: z.ZodString;
         matched: z.ZodNumber;
+        source: z.ZodOptional<z.ZodEnum<{
+            request: "request";
+            configuration: "configuration";
+        }>>;
     }, z.core.$loose>>;
     aliases: z.ZodArray<z.ZodObject<{
         path: z.ZodString;

package/dist/schema/src/api.js

@@ -533,9 +533,15 @@ export const CatalogHealthSchema = z.looseObject({
         testsWithoutSpec: nonneg,
         explanation: z.array(z.string())
     }),
-    identity: z.looseObject({ checks: nonneg, fallbackIdentity: nonneg.describe('Checks whose id equals their title'), basis: z.string() }),
+    identity: z.looseObject({
+        checks: nonneg,
+        fallbackIdentity: nonneg.describe('Checks whose id equals their title'),
+        declaredBehaviorIds: nonneg.optional().describe('Checks that declare a `behavior-id` label'),
+        declaredExampleIds: nonneg.optional().describe('Checks that declare an `example-id` label'),
+        basis: z.string()
+    }),
     domains: z.array(z.looseObject({ name: z.string(), specs: nonneg })).describe('Specs per domain, most first'),
-    roots: z.array(z.looseObject({ from: z.string(), to: z.string(), matched: nonneg.describe('Distinct paths the mapping changed') })),
+    roots: z.array(z.looseObject({ from: z.string(), to: z.string(), matched: nonneg.describe('Distinct paths the mapping changed'), source: z.enum(['configuration', 'request']).optional().describe('Where it was declared: the server\'s `catalog.roots` setting or this request\'s `root` parameter') })),
     aliases: z.array(z.looseObject({ path: z.string(), sources: z.array(z.string()) })).describe('Logical specs seen under more than one original path, joined by a root mapping'),
     findings: z.array(z.looseObject({
         code: z.string().describe('An open set: treat a code you do not know as informational'),

package/dist/schema/src/server-config.d.ts

@@ -66,6 +66,9 @@ export declare const ServerConfigSchema: z.ZodObject<{
         branches: z.ZodOptional<z.ZodArray<z.ZodString>>;
         ignoreModified: z.ZodOptional<z.ZodBoolean>;
     }, z.core.$strict>>;
+    catalog: z.ZodDefault<z.ZodObject<{
+        roots: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    }, z.core.$strict>>;
     refreshSeconds: z.ZodDefault<z.ZodNumber>;
     limits: z.ZodDefault<z.ZodObject<{
         maxObjectMiB: z.ZodDefault<z.ZodNumber>;

package/dist/schema/src/server-config.js

@@ -50,6 +50,11 @@ export const ServerConfigSchema = z.strictObject({
         ignoreModified: z.boolean().optional().describe('Leave out layers from modified checkouts and unknown origins')
     })
         .default({}),
+    catalog: z
+        .strictObject({
+        roots: z.array(z.string().refine((value) => value.includes('>'), { message: 'Write a root mapping as from>to, e.g. ">specs/" (paths under `from` are the same specs as paths under `to`)' })).default([]).describe('Root mappings `from>to` that relate spec paths a producer publishes to the paths the specs are recorded under (an empty `from` matches every path). The catalog health report applies them to every request, beside any `root` the request adds')
+    })
+        .default({ roots: [] }),
     refreshSeconds: z.number().min(1).default(10).describe('How often the backends are looked at for layers written by something other than this server'),
     limits: z
         .strictObject({

package/dist/server/src/app.d.ts

@@ -30,6 +30,8 @@ export type AtlasServerOptions = {
     /** The built viewer. Without it, only the API is served. */
     readonly site?: string;
     readonly outlineBranch?: string;
+    /** Root mappings `from>to` the catalog health report always applies (the `catalog.roots` setting), beside any `root` a request adds. */
+    readonly catalogRoots?: readonly string[];
     readonly include?: (layer: LayerHeader) => boolean;
     readonly refreshMs?: number;
     readonly limits?: {

package/dist/server/src/app.js

@@ -26,7 +26,7 @@ import { reportStatus } from '../../reports/src/report-status.js';
 import { ReportIndex } from '../../reports/src/report-index.js';
 import { listRunSummaries, readRunFile } from '../../reports/src/run-bundle.js';
 import { latestSpecSet, readSpecBody } from '../../reports/src/spec-set.js';
-import { catalogHealth, healthMarkdown, parseRootMappings } from '../../reports/src/catalog-health.js';
+import { catalogHealth, healthMarkdown, parseRootMapping, parseRootMappings } from '../../reports/src/catalog-health.js';
 import { parseArtifactFilter } from '../../reports/src/artifact-query.js';
 import { filterUiCatalog, pageUiCatalog, parseUiCatalogQuery, uiCatalog, uiCatalogMarkdown } from '../../reports/src/ui-catalog.js';
 import { parseReliabilityScope, reliability, reliabilityMarkdown } from '../../reports/src/reliability.js';
@@ -451,12 +451,16 @@ function createProjectApplication(options) {
         const document = () => testCatalog(found, query);
         return answer(c, found.version, document, () => catalogMarkdown(document()), `tests|${new URL(c.req.url).search}|${wantsMarkdown(c)}`);
     });
+    const configuredRoots = (options.catalogRoots ?? []).flatMap(text => parseRootMapping(text) ?? []).map(mapping => ({ ...mapping, source: 'configuration' }));
     app.get('/api/reports/tests/health', async (c) => {
         if (!index.ready)
             return notReady(c);
         const found = await catalog();
         const params = new URL(c.req.url).searchParams;
-        const document = () => catalogHealth(found, parseRootMappings(params));
+        // The mappings the operator configured, then those this request adds (one already configured is not counted twice).
+        const requested = parseRootMappings(params).filter(mapping => !configuredRoots.some(item => item.from === mapping.from && item.to === mapping.to));
+        const roots = [...configuredRoots, ...requested.map(mapping => ({ ...mapping, source: 'request' }))];
+        const document = () => catalogHealth(found, roots);
         return answer(c, found.version, document, () => healthMarkdown(document()), `health|${params.getAll('root').join('\u0001')}|${wantsMarkdown(c)}`);
     });
     app.get('/api/reports/tests/history', async (c) => {

package/dist/server/src/config.js

@@ -57,6 +57,7 @@ export const SERVER_SETTINGS = [
     { summary: 'Whose specs the report is laid over', key: 'outlineBranch', flag: '--outline-branch <branch>', env: ['ATLAS_OUTLINE_BRANCH'], default: '`main`, then `master`, then the newest', example: { value: 'trunk', read: c => c.outlineBranch, expected: 'trunk' } },
     { summary: 'Only layers recorded on these branches take part', key: 'include.branches', flag: '--branch <name>` (repeatable)', env: ['ATLAS_ONLY_BRANCH'], default: 'all', example: { value: 'main', read: c => c.include.branches, expected: ['main'] } },
     { summary: 'Leave out layers from modified checkouts and unknown origins', key: 'include.ignoreModified', flag: '--ignore-modified', env: ['ATLAS_IGNORE_MODIFIED'], default: 'no', example: { value: '1', read: c => c.include.ignoreModified, expected: true } },
+    { summary: 'Root mappings `from>to` that join spec paths a producer publishes to the paths the specs are recorded under, for the catalog health report (comma-separated; an empty `from` matches every path)', key: 'catalog.roots', flag: null, env: ['ATLAS_CATALOG_ROOTS'], default: 'none', example: { value: '>specs/,apps/>specs/web/', read: c => c.catalog.roots, expected: ['>specs/', 'apps/>specs/web/'] } },
     { summary: 'How often (seconds) the backends are looked at for layers written by something else', key: 'refreshSeconds', flag: '--refresh <seconds>', env: ['ATLAS_REFRESH_SECONDS'], default: '`10`', example: { value: '30', read: c => c.refreshSeconds, expected: 30 } },
     { summary: 'Let anyone look, not upload', key: 'auth.anonymousRead', flag: '--anonymous-read', env: ['ATLAS_ANONYMOUS_READ'], default: 'no', example: { value: '1', read: c => c.anonymousRead, expected: true } },
     { summary: 'Listen publicly with no tokens (something in front signs people in)', key: 'auth.insecure', flag: '--insecure', env: ['ATLAS_INSECURE'], default: 'no', example: { value: '1', read: c => c.insecure, expected: true } },
@@ -151,6 +152,9 @@ export function loadServerConfig(argv, env, cwd, read = file => readFileSync(fil
             limits[key] = Number(env[variable]);
     }
     merged.limits = limits;
+    const roots = list(env.ATLAS_CATALOG_ROOTS);
+    if (roots.length)
+        merged.catalog = { ...raw.catalog, roots };
     if (flags.insecure || truthy(env.ATLAS_INSECURE))
         auth.insecure = true;
     if (flags['anonymous-read'] || truthy(env.ATLAS_ANONYMOUS_READ))

package/dist/server/src/main.js

@@ -56,6 +56,7 @@ export function serverOptionsOf(config, backends, log) {
         backends, write: S3_BACKEND_ID,
         tokens: config.tokens, anonymousRead: config.anonymousRead,
         ...(config.outlineBranch ? { outlineBranch: config.outlineBranch } : {}), ...(include ? { include } : {}),
+        ...(config.catalog.roots.length ? { catalogRoots: config.catalog.roots } : {}),
         runTimeoutMs: config.runTimeoutSeconds * 1000, runStallMs: config.runStallSeconds * 1000, refreshMs: config.refreshSeconds * 1000, limits: config.limits, heartbeatMs: config.heartbeatSeconds * 1000,
         ...(config.log && log ? { log } : {})
     };

package/dist/server/src/openapi.js

@@ -313,10 +313,10 @@ const BASE_OPERATIONS = [
             '',
             '`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.'
+            '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; the labels `behavior-id` and `example-id` declare stable ids, which are counted and checked for ids shared by several checks. 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: 'root', in: 'query', description: 'A root mapping `from>to`, URL-encoded. Repeatable or comma-separated. It is added to the mappings the server is configured with (`catalog.roots`, `ATLAS_CATALOG_ROOTS`); `roots[].source` says which is which.', 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 }

package/docs/extending.md

@@ -30,7 +30,7 @@ carry any of these. Every one is optional.
 | `annotations[]` | Notes about the result: a warning, a deprecation, an accessibility finding, a coverage figure. |
 | `attempts[]` | Every try, when the check was retried. |
 | `tags[]` | Free labels to filter by: `smoke`, `payments`. |
-| `labels{}` | Facts about the result that are not its identity: `owner`, `severity`, `browser`, `build`. The viewer reads `build`, `platform`, `applies-to` and `applies-to-by` to tell whether evidence applies to a release (see [the viewer conventions](ui.md#behaviors-read-watch-inspect)). |
+| `labels{}` | Facts about the result that are not its identity: `owner`, `severity`, `browser`, `build`. The viewer reads `build`, `platform`, `applies-to` and `applies-to-by` to tell whether evidence applies to a release (see [the viewer conventions](ui.md#behaviors-read-watch-inspect)). `behavior-id` and `example-id` declare a stable id for the behavior and for one example of an outline, and `outline` names the outline; the [catalog health](server.md#reading-the-report-as-an-agent) report counts them and names an id shared by several checks. They never change which check a result belongs to. |
 | `scope{}` | What the evidence does and does not show: surface, device kind, synthetic data, scripted dependencies, audio, pacing, what was asserted and its limits. Unknown when absent. See [Evidence scope](rich-evidence.md#evidence-scope). |
 | `links[]` | Where to read more: the CI run, the issue, the trace client. |
 | `extensions{}` | Structured data of your own or a tool's, under a name you own. |

package/docs/reference/http-api.md

@@ -550,9 +550,9 @@ Diagnoses the report's metadata, so a domain filter or a coverage percentage can
 
 `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.
+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; the labels `behavior-id` and `example-id` declare stable ids, which are counted and checked for ids shared by several checks. Send `format=markdown` for Markdown.
 
-- `root` (query): A root mapping `from>to`, URL-encoded. Repeatable or comma-separated.
+- `root` (query): A root mapping `from>to`, URL-encoded. Repeatable or comma-separated. It is added to the mappings the server is configured with (`catalog.roots`, `ATLAS_CATALOG_ROOTS`); `roots[].source` says which is which.
 - `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.
 
@@ -566,12 +566,12 @@ Diagnoses the report's metadata, so a domain filter or a coverage percentage can
 
 `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.
+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; the labels `behavior-id` and `example-id` declare stable ids, which are counted and checked for ids shared by several checks. 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.
+- `root` (query): A root mapping `from>to`, URL-encoded. Repeatable or comma-separated. It is added to the mappings the server is configured with (`catalog.roots`, `ATLAS_CATALOG_ROOTS`); `roots[].source` says which is which.
 - `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`.

package/docs/reference/reports.md

@@ -806,6 +806,10 @@ Explains why the Specs and the Tests of a report may disagree, and what a produc
 - **Fallback identity.** A check whose id is its title has no stable id; renaming it starts a new check. Counted, not
   guessed at.
 
+- **Declared ids.** A producer may say what a check is with the labels `behavior-id` (the promise) and `example-id`
+  (one example of an outline). Atlas counts them and names ids that sit on more than one check; it does not join the
+  checks, because a check is still its spec path and id.
+
 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.
 
@@ -827,13 +831,30 @@ export const HEALTH_ITEM_LIMIT = …
 
 The most paths listed in one finding; its `count` is always the whole.
 
+#### `BEHAVIOR_ID_LABEL`
+
+```ts
+export const BEHAVIOR_ID_LABEL = …
+```
+
+The label a producer puts on a check to give its behavior (the promise) an id that outlives renames and moves.
+
+#### `EXAMPLE_ID_LABEL`
+
+```ts
+export const EXAMPLE_ID_LABEL = …
+```
+
+The label a producer puts on a check to give one example of a scenario outline an id of its own.
+
 #### `RootMapping`
 
 ```ts
-export type RootMapping = { readonly from: string; readonly to: string };
+export type RootMapping = { readonly from: string; readonly to: string; readonly source?: 'configuration' | 'request' };
 ```
 
-Declares that paths under `from` are the same specs as paths under `to`, e.g. `{ from: '', to: 'specs/' }`. Empty `from` matches every path.
+Declares that paths under `from` are the same specs as paths under `to`, e.g. `{ from: '', to: 'specs/' }`. Empty `from`
+matches every path. `source` says where it was declared (the server's configuration or the request); it changes nothing.
 
 #### `HealthItem`
 
@@ -860,6 +881,7 @@ export type HealthCode =
   | 'no-spec-definitions'
   | 'fallback-identity'
   | 'unused-root-mapping'
+  | 'declared-id-split'
   | 'spec-without-execution'
   | 'historical-only';
 ```

package/docs/reference/server.md

@@ -31,6 +31,8 @@ export type AtlasServerOptions = {
   /** The built viewer. Without it, only the API is served. */
   readonly site?: string;
   readonly outlineBranch?: string;
+  /** Root mappings `from>to` the catalog health report always applies (the `catalog.roots` setting), beside any `root` a request adds. */
+  readonly catalogRoots?: readonly string[];
   readonly include?: (layer: LayerHeader) => boolean;
   readonly refreshMs?: number;
   readonly limits?: { readonly maxObjectMiB?: number; readonly maxJsonMiB?: number; readonly maxStreams?: number };

package/docs/server.md

@@ -202,6 +202,7 @@ is said in words and the server does not start. The file has a published
 | Whose specs the report is laid over | `outlineBranch` | `--outline-branch <branch>` | `ATLAS_OUTLINE_BRANCH` | `main`, then `master`, then the newest |
 | Only layers recorded on these branches take part | `include.branches` | `--branch <name>` (repeatable) | `ATLAS_ONLY_BRANCH` | all |
 | Leave out layers from modified checkouts and unknown origins | `include.ignoreModified` | `--ignore-modified` | `ATLAS_IGNORE_MODIFIED` | no |
+| Root mappings `from>to` that join spec paths a producer publishes to the paths the specs are recorded under, for the catalog health report (comma-separated; an empty `from` matches every path) | `catalog.roots` |  | `ATLAS_CATALOG_ROOTS` | none |
 | How often (seconds) the backends are looked at for layers written by something else | `refreshSeconds` | `--refresh <seconds>` | `ATLAS_REFRESH_SECONDS` | `10` |
 | Let anyone look, not upload | `auth.anonymousRead` | `--anonymous-read` | `ATLAS_ANONYMOUS_READ` | no |
 | Listen publicly with no tokens (something in front signs people in) | `auth.insecure` | `--insecure` | `ATLAS_INSECURE` | no |
@@ -442,8 +443,16 @@ curl "$ATLAS_SERVER_URL/api/projects/$ATLAS_PROJECT/reports/tests?format=markdow
   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.
+  `outline` to say which scenario outline an example belongs to, and `behavior-id` / `example-id` to give a behavior
+  or one example a stable id of your own: Atlas counts them and names an id that sits on more than one check (a
+  rename or a move), but a check is still its spec path and id, so nothing is joined by them. A domain shared by nearly
+  every spec is flagged, but explicit domain metadata always stays authoritative. The document only reads: it changes
+  no status.
+- Mappings that should always apply are a setting, not a query parameter: `catalog.roots` in `atlas.server.json` (a list
+  of `from>to`) or `ATLAS_CATALOG_ROOTS` (comma-separated; it replaces the file's list). The health document applies
+  them, then adds the request's `?root=`, and says in `roots[].source` which is which. A mapping with no `>` stops the
+  server starting. The viewer's **Catalog health** tab shows the same document, and its mapping form (the `root`
+  address parameter) tries further mappings without changing the server.
 - 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,

package/docs/ui.md

@@ -96,6 +96,25 @@ when Watch is on screen.
 - The spec index searches titles, paths and declared domains, and can group by the domain from spec metadata (specs with
   none are listed under "No domain declared"; the Tests view reports domain problems).
 
+## Catalog health
+
+The **Catalog health** tab (`explorer/HealthView.tsx`, `?tab=health`; `@crvouga/atlas/reports/catalog-health`) explains why the Specs
+and the Tests disagree. The Specs list links to it ("Why do these counts differ from the Tests?"). On a server it reads
+`GET /api/reports/tests/health`; elsewhere the same document is worked out in the page from the specs and results it holds, and an
+older server without the route is told so in words.
+
+- Denominators are never one number: spec files, defined specs, specs with tests, specs executed and defined but not executed
+  (the coverage gaps, which add to no passed count), tests, outlines, examples and observations (an outline, its examples and
+  their per-environment results are told apart). Each figure has its meaning in its `title`.
+- A table walks from the Specs total to the Tests total, step by step, with the sentences below it. Findings are an `Accordion`
+  (warnings open), each with its severity as text, its code, how many it affects and the paths. Paths that might be one promise
+  are shown as "may be the same promise as ...; not merged": a similar title never joins two specs.
+- Root mappings (`from>to`) join spec paths. Those the server is configured with (`catalog.roots`, `ATLAS_CATALOG_ROOTS`) are
+  labelled "Configured on the server"; others are tried in the form and kept in the address (`root`), labelled "Tried here", and
+  change nothing on the server. A mapping that matched no path is a warning. Joined specs list every original path.
+- Domains are listed as declared; a domain shared by nearly every spec is a finding, never rewritten. Identity states how many
+  checks are known only by title, how many declare `behavior-id` / `example-id`, and the limits of both.
+
 ## UI catalog
 
 `/catalog` (`catalog/`) is the viewer's inventory of captured UI states ([the guide](ui-catalog.md)). It is computed in the page from
@@ -320,7 +339,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 |
 | UI catalog | Captured UI states per profile as cards with coverage badges, filters in the index column, surface coverage, an open state with its profiles side by side and where each picture came from, manifest download | AppShell navbar, SimpleGrid, Card, Image, MultiSelect, TextInput, Drawer, Accordion, Table, Badge, Alert |
-| Project home | Tests/runs/artifacts/compare tabs, a two-run comparison with promise, outcome, recording and figure tabs per behavior, a run's Artifacts (files of its layers, shared recordings, direct links), Watch playlist of a filtered set, metrics, search, status/environment/domain/artifact-tag filters, run and artifact facets with saved views, grouping, sorting, show more | Container, Tabs, SimpleGrid, Paper, TextInput, MultiSelect, Popover, Button, Accordion, Modal, Grid, Switch |
+| Project home | Tests/runs/artifacts/compare/catalog health tabs, a two-run comparison with promise, outcome, recording and figure tabs per behavior, a run's Artifacts (files of its layers, shared recordings, direct links), Watch playlist of a filtered set, metrics, search, status/environment/domain/artifact-tag filters, run and artifact facets with saved views, grouping, sorting, show more | Container, Tabs, SimpleGrid, Paper, TextInput, MultiSelect, Popover, Button, Accordion, Modal, Grid, Switch |
 | Test detail | Current outcomes, statistics, duration graph, product latency with budgets and baselines, 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 with title search and folder or declared-domain grouping, Gherkin rules/scenarios/examples with a coverage summary and Read / Watch / Inspect per behavior, Quint declarations/traces, DMN tables, source text | SpecHeader, Accordion, Tabs, Table, CodeHighlightTabs, ResultRow |
 | Statecharts | Graph, screen/event/journey details, developer metadata, chart test results | Mantine cards/navigation and product compositions; graph exception above |

package/llms-full.txt

@@ -1850,6 +1850,7 @@ is said in words and the server does not start. The file has a published
 | Whose specs the report is laid over | `outlineBranch` | `--outline-branch <branch>` | `ATLAS_OUTLINE_BRANCH` | `main`, then `master`, then the newest |
 | Only layers recorded on these branches take part | `include.branches` | `--branch <name>` (repeatable) | `ATLAS_ONLY_BRANCH` | all |
 | Leave out layers from modified checkouts and unknown origins | `include.ignoreModified` | `--ignore-modified` | `ATLAS_IGNORE_MODIFIED` | no |
+| Root mappings `from>to` that join spec paths a producer publishes to the paths the specs are recorded under, for the catalog health report (comma-separated; an empty `from` matches every path) | `catalog.roots` |  | `ATLAS_CATALOG_ROOTS` | none |
 | How often (seconds) the backends are looked at for layers written by something else | `refreshSeconds` | `--refresh <seconds>` | `ATLAS_REFRESH_SECONDS` | `10` |
 | Let anyone look, not upload | `auth.anonymousRead` | `--anonymous-read` | `ATLAS_ANONYMOUS_READ` | no |
 | Listen publicly with no tokens (something in front signs people in) | `auth.insecure` | `--insecure` | `ATLAS_INSECURE` | no |
@@ -2090,8 +2091,16 @@ curl "$ATLAS_SERVER_URL/api/projects/$ATLAS_PROJECT/reports/tests?format=markdow
   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.
+  `outline` to say which scenario outline an example belongs to, and `behavior-id` / `example-id` to give a behavior
+  or one example a stable id of your own: Atlas counts them and names an id that sits on more than one check (a
+  rename or a move), but a check is still its spec path and id, so nothing is joined by them. A domain shared by nearly
+  every spec is flagged, but explicit domain metadata always stays authoritative. The document only reads: it changes
+  no status.
+- Mappings that should always apply are a setting, not a query parameter: `catalog.roots` in `atlas.server.json` (a list
+  of `from>to`) or `ATLAS_CATALOG_ROOTS` (comma-separated; it replaces the file's list). The health document applies
+  them, then adds the request's `?root=`, and says in `roots[].source` which is which. A mapping with no `>` stops the
+  server starting. The viewer's **Catalog health** tab shows the same document, and its mapping form (the `root`
+  address parameter) tries further mappings without changing the server.
 - 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,
@@ -3195,7 +3204,7 @@ carry any of these. Every one is optional.
 | `annotations[]` | Notes about the result: a warning, a deprecation, an accessibility finding, a coverage figure. |
 | `attempts[]` | Every try, when the check was retried. |
 | `tags[]` | Free labels to filter by: `smoke`, `payments`. |
-| `labels{}` | Facts about the result that are not its identity: `owner`, `severity`, `browser`, `build`. The viewer reads `build`, `platform`, `applies-to` and `applies-to-by` to tell whether evidence applies to a release (see [the viewer conventions](ui.md#behaviors-read-watch-inspect)). |
+| `labels{}` | Facts about the result that are not its identity: `owner`, `severity`, `browser`, `build`. The viewer reads `build`, `platform`, `applies-to` and `applies-to-by` to tell whether evidence applies to a release (see [the viewer conventions](ui.md#behaviors-read-watch-inspect)). `behavior-id` and `example-id` declare a stable id for the behavior and for one example of an outline, and `outline` names the outline; the [catalog health](server.md#reading-the-report-as-an-agent) report counts them and names an id shared by several checks. They never change which check a result belongs to. |
 | `scope{}` | What the evidence does and does not show: surface, device kind, synthetic data, scripted dependencies, audio, pacing, what was asserted and its limits. Unknown when absent. See [Evidence scope](rich-evidence.md#evidence-scope). |
 | `links[]` | Where to read more: the CI run, the issue, the trace client. |
 | `extensions{}` | Structured data of your own or a tool's, under a name you own. |
@@ -4515,6 +4524,25 @@ when Watch is on screen.
 - The spec index searches titles, paths and declared domains, and can group by the domain from spec metadata (specs with
   none are listed under "No domain declared"; the Tests view reports domain problems).
 
+## Catalog health
+
+The **Catalog health** tab (`explorer/HealthView.tsx`, `?tab=health`; `@crvouga/atlas/reports/catalog-health`) explains why the Specs
+and the Tests disagree. The Specs list links to it ("Why do these counts differ from the Tests?"). On a server it reads
+`GET /api/reports/tests/health`; elsewhere the same document is worked out in the page from the specs and results it holds, and an
+older server without the route is told so in words.
+
+- Denominators are never one number: spec files, defined specs, specs with tests, specs executed and defined but not executed
+  (the coverage gaps, which add to no passed count), tests, outlines, examples and observations (an outline, its examples and
+  their per-environment results are told apart). Each figure has its meaning in its `title`.
+- A table walks from the Specs total to the Tests total, step by step, with the sentences below it. Findings are an `Accordion`
+  (warnings open), each with its severity as text, its code, how many it affects and the paths. Paths that might be one promise
+  are shown as "may be the same promise as ...; not merged": a similar title never joins two specs.
+- Root mappings (`from>to`) join spec paths. Those the server is configured with (`catalog.roots`, `ATLAS_CATALOG_ROOTS`) are
+  labelled "Configured on the server"; others are tried in the form and kept in the address (`root`), labelled "Tried here", and
+  change nothing on the server. A mapping that matched no path is a warning. Joined specs list every original path.
+- Domains are listed as declared; a domain shared by nearly every spec is a finding, never rewritten. Identity states how many
+  checks are known only by title, how many declare `behavior-id` / `example-id`, and the limits of both.
+
 ## UI catalog
 
 `/catalog` (`catalog/`) is the viewer's inventory of captured UI states ([the guide](ui-catalog.md)). It is computed in the page from
@@ -4739,7 +4767,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 |
 | UI catalog | Captured UI states per profile as cards with coverage badges, filters in the index column, surface coverage, an open state with its profiles side by side and where each picture came from, manifest download | AppShell navbar, SimpleGrid, Card, Image, MultiSelect, TextInput, Drawer, Accordion, Table, Badge, Alert |
-| Project home | Tests/runs/artifacts/compare tabs, a two-run comparison with promise, outcome, recording and figure tabs per behavior, a run's Artifacts (files of its layers, shared recordings, direct links), Watch playlist of a filtered set, metrics, search, status/environment/domain/artifact-tag filters, run and artifact facets with saved views, grouping, sorting, show more | Container, Tabs, SimpleGrid, Paper, TextInput, MultiSelect, Popover, Button, Accordion, Modal, Grid, Switch |
+| Project home | Tests/runs/artifacts/compare/catalog health tabs, a two-run comparison with promise, outcome, recording and figure tabs per behavior, a run's Artifacts (files of its layers, shared recordings, direct links), Watch playlist of a filtered set, metrics, search, status/environment/domain/artifact-tag filters, run and artifact facets with saved views, grouping, sorting, show more | Container, Tabs, SimpleGrid, Paper, TextInput, MultiSelect, Popover, Button, Accordion, Modal, Grid, Switch |
 | Test detail | Current outcomes, statistics, duration graph, product latency with budgets and baselines, 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 with title search and folder or declared-domain grouping, Gherkin rules/scenarios/examples with a coverage summary and Read / Watch / Inspect per behavior, Quint declarations/traces, DMN tables, source text | SpecHeader, Accordion, Tabs, Table, CodeHighlightTabs, ResultRow |
 | Statecharts | Graph, screen/event/journey details, developer metadata, chart test results | Mantine cards/navigation and product compositions; graph exception above |
@@ -5829,9 +5857,9 @@ Diagnoses the report's metadata, so a domain filter or a coverage percentage can
 
 `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.
+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; the labels `behavior-id` and `example-id` declare stable ids, which are counted and checked for ids shared by several checks. Send `format=markdown` for Markdown.
 
-- `root` (query): A root mapping `from>to`, URL-encoded. Repeatable or comma-separated.
+- `root` (query): A root mapping `from>to`, URL-encoded. Repeatable or comma-separated. It is added to the mappings the server is configured with (`catalog.roots`, `ATLAS_CATALOG_ROOTS`); `roots[].source` says which is which.
 - `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.
 
@@ -5845,12 +5873,12 @@ Diagnoses the report's metadata, so a domain filter or a coverage percentage can
 
 `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.
+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; the labels `behavior-id` and `example-id` declare stable ids, which are counted and checked for ids shared by several checks. 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.
+- `root` (query): A root mapping `from>to`, URL-encoded. Repeatable or comma-separated. It is added to the mappings the server is configured with (`catalog.roots`, `ATLAS_CATALOG_ROOTS`); `roots[].source` says which is which.
 - `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`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crvouga/atlas",
-  "version": "1.15.0",
+  "version": "1.16.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",

package/packages/schema/schemas/catalog-health.schema.json

@@ -229,6 +229,18 @@
           "maximum": 9007199254740991,
           "description": "Checks whose id equals their title"
         },
+        "declaredBehaviorIds": {
+          "description": "Checks that declare a `behavior-id` label",
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 9007199254740991
+        },
+        "declaredExampleIds": {
+          "description": "Checks that declare an `example-id` label",
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 9007199254740991
+        },
         "basis": {
           "type": "string"
         }
@@ -278,6 +290,14 @@
             "minimum": 0,
             "maximum": 9007199254740991,
             "description": "Distinct paths the mapping changed"
+          },
+          "source": {
+            "description": "Where it was declared: the server's `catalog.roots` setting or this request's `root` parameter",
+            "type": "string",
+            "enum": [
+              "configuration",
+              "request"
+            ]
           }
         },
         "required": [

package/packages/schema/schemas/server-config.schema.json

@@ -102,6 +102,23 @@
       },
       "additionalProperties": false
     },
+    "catalog": {
+      "default": {
+        "roots": []
+      },
+      "type": "object",
+      "properties": {
+        "roots": {
+          "default": [],
+          "description": "Root mappings `from>to` that relate spec paths a producer publishes to the paths the specs are recorded under (an empty `from` matches every path). The catalog health report applies them to every request, beside any `root` the request adds",
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        }
+      },
+      "additionalProperties": false
+    },
     "refreshSeconds": {
       "default": 10,
       "description": "How often the backends are looked at for layers written by something other than this server",

package/packages/server/openapi.json

@@ -3699,7 +3699,7 @@
           "Report"
         ],
         "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.\n\n`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.\n\nTwo 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.\n\nRole needed: `read`.",
+        "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.\n\n`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.\n\nTwo 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; the labels `behavior-id` and `example-id` declare stable ids, which are counted and checked for ids shared by several checks. Send `format=markdown` for Markdown.\n\nRole needed: `read`.",
         "x-atlas-role": "read",
         "security": [
           {
@@ -3714,7 +3714,7 @@
             "required": false,
             "name": "root",
             "in": "query",
-            "description": "A root mapping `from>to`, URL-encoded. Repeatable or comma-separated.",
+            "description": "A root mapping `from>to`, URL-encoded. Repeatable or comma-separated. It is added to the mappings the server is configured with (`catalog.roots`, `ATLAS_CATALOG_ROOTS`); `roots[].source` says which is which.",
             "example": ">specs/",
             "schema": {
               "type": "string"
@@ -3798,7 +3798,7 @@
           "Report"
         ],
         "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.\n\n`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.\n\nTwo 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.\n\nScoped 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.\n\nRole needed: `read`.",
+        "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.\n\n`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.\n\nTwo 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; the labels `behavior-id` and `example-id` declare stable ids, which are counted and checked for ids shared by several checks. Send `format=markdown` for Markdown.\n\nScoped 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.\n\nRole needed: `read`.",
         "x-atlas-role": "read",
         "security": [
           {
@@ -3825,7 +3825,7 @@
             "required": false,
             "name": "root",
             "in": "query",
-            "description": "A root mapping `from>to`, URL-encoded. Repeatable or comma-separated.",
+            "description": "A root mapping `from>to`, URL-encoded. Repeatable or comma-separated. It is added to the mappings the server is configured with (`catalog.roots`, `ATLAS_CATALOG_ROOTS`); `roots[].source` says which is which.",
             "example": ">specs/",
             "schema": {
               "type": "string"
@@ -21772,6 +21772,18 @@
                 "maximum": 9007199254740991,
                 "description": "Checks whose id equals their title"
               },
+              "declaredBehaviorIds": {
+                "description": "Checks that declare a `behavior-id` label",
+                "type": "integer",
+                "minimum": 0,
+                "maximum": 9007199254740991
+              },
+              "declaredExampleIds": {
+                "description": "Checks that declare an `example-id` label",
+                "type": "integer",
+                "minimum": 0,
+                "maximum": 9007199254740991
+              },
               "basis": {
                 "type": "string"
               }
@@ -21821,6 +21833,14 @@
                   "minimum": 0,
                   "maximum": 9007199254740991,
                   "description": "Distinct paths the mapping changed"
+                },
+                "source": {
+                  "description": "Where it was declared: the server's `catalog.roots` setting or this request's `root` parameter",
+                  "type": "string",
+                  "enum": [
+                    "configuration",
+                    "request"
+                  ]
                 }
               },
               "required": [

package/packages/visualizer/src/explorer/Explorer.tsx

@@ -59,6 +59,7 @@ import { patched, useExplorerNavigate, useExplorerSearch } from './navigate';
 import { Badges, EnvironmentChips, projectTitle, runName } from './parts';
 import { ArtifactsView } from './ArtifactsView';
 import { CompareView } from './CompareView';
+import { HealthView } from './HealthView';
 import { CollectionsView } from './collections';
 import { RunsView } from './RunsView';
 import { SearchNotes, TypedFilters } from './search-notes';
@@ -170,7 +171,7 @@ export function Explorer() {
   const model = catalog.model;
   const selected = search.test ? (model?.byKey.get(search.test) ?? null) : null;
   const empty = model !== null && model.tests.length === 0;
-  const split = !!search.test && search.tab !== 'runs' && search.tab !== 'artifacts' && search.tab !== 'collections' && search.tab !== 'compare';
+  const split = !!search.test && search.tab !== 'runs' && search.tab !== 'artifacts' && search.tab !== 'collections' && search.tab !== 'compare' && search.tab !== 'health';
   return (
     <Container size="xl" py="xl">
       <Box aria-label="Test explorer" component="article" miw={0}>
@@ -181,7 +182,7 @@ export function Explorer() {
           {model && (model.tests.length > 0 || model.summary.runs > 0) && (
             <Tabs
               value={search.tab ?? 'tests'}
-              onChange={(value) => go({ tab: value === 'runs' || value === 'artifacts' || value === 'collections' || value === 'compare' ? value : undefined, test: undefined, openRun: undefined, layer: undefined, artifact: undefined, collection: undefined, rev: undefined, pair: undefined })}
+              onChange={(value) => go({ tab: value === 'runs' || value === 'artifacts' || value === 'collections' || value === 'compare' || value === 'health' ? value : undefined, test: undefined, openRun: undefined, layer: undefined, artifact: undefined, collection: undefined, rev: undefined, pair: undefined })}
             >
               <Tabs.List aria-label="Explorer view">
                 <Tabs.Tab
@@ -206,6 +207,7 @@ export function Explorer() {
                 </Tabs.Tab>
                 <Tabs.Tab value="artifacts">Artifacts</Tabs.Tab>
                 <Tabs.Tab value="compare">Compare</Tabs.Tab>
+                <Tabs.Tab value="health">Catalog health</Tabs.Tab>
                 {!staticEvidence && <Tabs.Tab value="collections">Collections</Tabs.Tab>}
               </Tabs.List>
             </Tabs>
@@ -243,6 +245,9 @@ export function Explorer() {
                 </List.Item>
               ))}
             </List>
+            <Anchor mt="xs" display="inline-block" size="sm" renderRoot={(props) => <Link {...props} to="/" search={patched({ tab: 'health', test: undefined })} resetScroll={false} activeOptions={{ exact: true }} />}>
+              Why do these counts differ from the Tests?
+            </Anchor>
           </Box>
         )}
         {!model && !evidence.unavailable && (
@@ -273,6 +278,8 @@ export function Explorer() {
             <ArtifactsView />
           ) : search.tab === 'compare' ? (
             <CompareView />
+          ) : search.tab === 'health' ? (
+            <HealthView />
           ) : search.tab === 'collections' ? (
             <CollectionsView />
           ) : empty ? null : (

package/packages/visualizer/src/explorer/HealthView.tsx

@@ -0,0 +1,402 @@
+/**
+ * @module Catalog health view
+ *
+ * The Catalog health tab: why the Specs and the Tests of a report disagree, and what a producer or an operator can change.
+ * It shows the denominators apart (spec files, defined specs, specs with an executed test, tests, outlines, examples and
+ * per-environment observations), the steps from the Specs count to the Tests count, the domains in use, specs seen under
+ * more than one path, and every finding with the paths it affects. Two paths are one logical spec only when a root mapping
+ * relates them: the server's configured mappings are shown as such, and further `from>to` mappings can be tried here
+ * (they are the address's `root`, so a link reproduces the figures). Ambiguous paths are never merged by similar title.
+ * The tab only reads: it never changes a status, a count of passed checks or a domain.
+ */
+import { parseRootMappings, type CatalogHealth, type HealthFinding, type RootMapping } from '@crvouga/atlas/reports/catalog-health';
+import { Accordion, ActionIcon, Alert, Badge, Box, Button, Code, Group, List, Paper, SimpleGrid, Stack, Table, Text, TextInput, Title, Tooltip } from '@mantine/core';
+import { IconTrash } from '@tabler/icons-react';
+import { useMemo, useState } from 'react';
+
+import { plural } from '../evidence/format';
+import { useCatalogHealth } from './catalog';
+import { useExplorerNavigate, useExplorerSearch } from './navigate';
+
+const label = (root: { readonly from: string; readonly to: string }) => `${root.from}>${root.to}`;
+
+function Figure({ name, value, hint }: { name: string; value: number; hint: string }) {
+  return (
+    <Paper withBorder p="sm" title={hint}>
+      <Text size="xs" c="dimmed" component="div">
+        {name}
+      </Text>
+      <Text fw={700} size="xl" component="div" data-health-figure={name}>
+        {value}
+      </Text>
+    </Paper>
+  );
+}
+
+function Counts({ health }: { health: CatalogHealth }) {
+  const { specs, tests, scenarios } = health.counts;
+  return (
+    <Stack gap="md">
+      <Box component="section" aria-label="Spec counts">
+        <Title order={4} mb="xs">
+          Specs
+        </Title>
+        <SimpleGrid cols={{ base: 2, sm: 3, md: 5 }}>
+          <Figure name="Spec files" value={specs.files} hint="Files the report is laid over, before any root mapping. This is the number the Specs view shows." />
+          <Figure name="Defined specs" value={specs.defined} hint="Spec files, with those joined by a declared root mapping counted once." />
+          <Figure name="Specs with tests" value={specs.withTests} hint="Specs, defined or not, with at least one test. This is what the Tests view groups by." />
+          <Figure name="Specs executed" value={specs.executed} hint="Defined specs with a test that passed or failed: the denominator of execution coverage." />
+          <Figure name="Defined, not executed" value={specs.withoutExecution} hint="Defined specs with no passed or failed test: the coverage gaps. They add to no passed count." />
+        </SimpleGrid>
+      </Box>
+      <Box component="section" aria-label="Test counts">
+        <Title order={4} mb="xs">
+          Tests
+        </Title>
+        <SimpleGrid cols={{ base: 2, sm: 3, md: 5 }}>
+          <Figure name="Tests" value={tests.total} hint="Check identities: a spec path and an id, however many environments ran them." />
+          <Figure name="Tests passed" value={tests.passed} hint="Tests whose current status is passed." />
+          <Figure name="Tests with a spec" value={tests.withSpec} hint="Tests that name the spec they belong to." />
+          <Figure name="Tests without a spec" value={tests.withoutSpec} hint="Tests that name no spec; they are in no spec or domain group." />
+          <Figure name="Only in history" value={tests.historicalOnly} hint="Tests the history holds but the report has no current result for (removed, renamed or not re-run)." />
+        </SimpleGrid>
+      </Box>
+      <Box component="section" aria-label="Scenario counts">
+        <Title order={4} mb="xs">
+          Outlines, examples and observations
+        </Title>
+        <SimpleGrid cols={{ base: 2, sm: 3, md: 5 }}>
+          <Figure name="Outlines" value={scenarios.outlines} hint="Tests sharing the label outline count once; a test without it is its own outline." />
+          <Figure name="Examples" value={scenarios.examples} hint="Concrete examples: tests, however many environments ran them." />
+          <Figure name="Observations" value={scenarios.observations} hint="Current results per producer, environment and parameter set." />
+          <Figure name="Observations executed" value={scenarios.executedObservations} hint="Observations that passed or failed." />
+          <Figure name="Observations passed" value={scenarios.passedObservations} hint="Observations that passed." />
+        </SimpleGrid>
+      </Box>
+    </Stack>
+  );
+}
+
+function Reconciliation({ health }: { health: CatalogHealth }) {
+  const { reconciliation } = health;
+  let total = reconciliation.specs;
+  const rows = reconciliation.steps.map((step) => {
+    total += step.delta;
+    return (
+      <Table.Tr key={step.code}>
+        <Table.Td>{step.label}</Table.Td>
+        <Table.Td ta="right">{step.delta > 0 ? `+${step.delta}` : step.delta}</Table.Td>
+        <Table.Td ta="right">{total}</Table.Td>
+      </Table.Tr>
+    );
+  });
+  return (
+    <Box component="section" aria-label="Why Specs and Tests differ">
+      <Title order={3} mb="xs">
+        Why Specs and Tests differ
+      </Title>
+      <Table.ScrollContainer minWidth={420}>
+        <Table data-health-reconciliation>
+          <Table.Thead>
+            <Table.Tr>
+              <Table.Th scope="col">Step</Table.Th>
+              <Table.Th scope="col" ta="right">
+                Change
+              </Table.Th>
+              <Table.Th scope="col" ta="right">
+                Total
+              </Table.Th>
+            </Table.Tr>
+          </Table.Thead>
+          <Table.Tbody>
+            <Table.Tr>
+              <Table.Td>Spec files the Specs view lists</Table.Td>
+              <Table.Td />
+              <Table.Td ta="right">{reconciliation.specs}</Table.Td>
+            </Table.Tr>
+            {rows}
+            <Table.Tr>
+              <Table.Td fw={600}>Specs the Tests view groups its tests into</Table.Td>
+              <Table.Td />
+              <Table.Td ta="right" fw={600}>
+                {reconciliation.testSpecs}
+              </Table.Td>
+            </Table.Tr>
+          </Table.Tbody>
+        </Table>
+      </Table.ScrollContainer>
+      <List size="sm" mt="sm" data-health-explanation>
+        {reconciliation.explanation.map((line) => (
+          <List.Item key={line}>{line}</List.Item>
+        ))}
+      </List>
+    </Box>
+  );
+}
+
+function Finding({ item }: { item: HealthFinding }) {
+  return (
+    <Accordion.Item value={item.code} data-health-finding={item.code}>
+      <Accordion.Control>
+        <Group gap="xs" wrap="wrap">
+          <Badge variant="light" color={item.severity === 'warning' ? 'orange' : 'blue'} tt="none">
+            {item.severity === 'warning' ? 'Warning' : 'Note'}
+          </Badge>
+          <Code>{item.code}</Code>
+          <Text span size="sm" c="dimmed">
+            {item.count} affected
+          </Text>
+        </Group>
+      </Accordion.Control>
+      <Accordion.Panel>
+        <Stack gap="xs">
+          <Text component="div" size="sm">
+            {item.message}
+          </Text>
+          {item.items.length > 0 && (
+            <List size="sm" listStyleType="none">
+              {item.items.map((entry) => (
+                <List.Item key={entry.path}>
+                  <Code>{entry.path}</Code>
+                  {entry.candidates?.map((candidate) => (
+                    <Text key={candidate.path} component="div" size="xs" c="dimmed" ml="md">
+                      may be the same promise as <Code>{candidate.path}</Code> ({candidate.reason}); not merged
+                    </Text>
+                  ))}
+                </List.Item>
+              ))}
+            </List>
+          )}
+          {item.count > item.items.length && (
+            <Text size="xs" c="dimmed" component="div">
+              and {item.count - item.items.length} more
+            </Text>
+          )}
+        </Stack>
+      </Accordion.Panel>
+    </Accordion.Item>
+  );
+}
+
+function Mappings({ health, tried }: { health: CatalogHealth | undefined; tried: readonly RootMapping[] }) {
+  const go = useExplorerNavigate();
+  const [from, setFrom] = useState('');
+  const [to, setTo] = useState('');
+  const configured = (health?.roots ?? []).filter((root) => root.source === 'configuration');
+  const write = (list: readonly RootMapping[]) => go({ root: list.length ? list.map(label).join(',') : undefined }, { replace: true });
+  const known = [...configured, ...tried].some((root) => root.from === from.trim() && root.to === to.trim());
+  const matched = (root: RootMapping) => health?.roots.find((item) => item.from === root.from && item.to === root.to && item.source !== 'configuration')?.matched;
+  return (
+    <Box component="section" aria-label="Root mappings">
+      <Title order={3} mb="xs">
+        Root mappings
+      </Title>
+      <Text size="sm" c="dimmed" mb="sm">
+        Two spec paths are one spec only when a mapping says so. A mapping states that paths under one folder are the same specs as paths under another; Atlas never merges paths by a similar title. A mapping tried here is kept in the address and changes nothing on the server. To keep one, set <Code>catalog.roots</Code> or <Code>ATLAS_CATALOG_ROOTS</Code> on the server.
+      </Text>
+      {configured.length + tried.length > 0 && (
+        <List size="sm" listStyleType="none" mb="sm" aria-label="Declared root mappings">
+          {configured.map((root) => (
+            <List.Item key={`c${label(root)}`}>
+              <Group gap="xs" wrap="wrap">
+                <Code>{label(root)}</Code>
+                <Badge variant="light" tt="none">
+                  Configured on the server
+                </Badge>
+                <Text span size="xs" c="dimmed">
+                  changed {plural(root.matched, 'path', 'paths')}
+                </Text>
+              </Group>
+            </List.Item>
+          ))}
+          {tried.map((root) => (
+            <List.Item key={`t${label(root)}`}>
+              <Group gap="xs" wrap="wrap">
+                <Code>{label(root)}</Code>
+                <Badge variant="light" color="gray" tt="none">
+                  Tried here
+                </Badge>
+                {matched(root) !== undefined && (
+                  <Text span size="xs" c="dimmed">
+                    changed {plural(matched(root)!, 'path', 'paths')}
+                  </Text>
+                )}
+                <Tooltip label="Stop trying this mapping">
+                  <ActionIcon variant="subtle" color="gray" aria-label={`Stop trying ${label(root)}`} onClick={() => write(tried.filter((item) => item !== root))}>
+                    <IconTrash size={16} aria-hidden="true" />
+                  </ActionIcon>
+                </Tooltip>
+              </Group>
+            </List.Item>
+          ))}
+        </List>
+      )}
+      <form
+        onSubmit={(event) => {
+          event.preventDefault();
+          if (!to.trim() || known) return;
+          write([...tried, { from: from.trim(), to: to.trim() }]);
+          setFrom('');
+          setTo('');
+        }}
+      >
+        <Group align="flex-end" gap="md" wrap="wrap">
+          <TextInput label="Paths under" description="Leave empty to match every path" placeholder="checkout/" value={from} onChange={(event) => setFrom(event.currentTarget.value)} />
+          <TextInput label="are the same specs as paths under" description="Where the specs are recorded" placeholder="specs/checkout/" value={to} onChange={(event) => setTo(event.currentTarget.value)} />
+          <Button type="submit" disabled={!to.trim() || known}>
+            Try this mapping
+          </Button>
+        </Group>
+      </form>
+    </Box>
+  );
+}
+
+/** The Catalog health tab. */
+export function HealthView() {
+  const search = useExplorerSearch();
+  const tried = useMemo(() => (search.root ? parseRootMappings(new URLSearchParams([['root', search.root]])) : []), [search.root]);
+  const answer = useCatalogHealth(tried);
+  const health = answer.data && !answer.data.unsupported ? answer.data.health : undefined;
+  const warnings = health?.findings.filter((item) => item.severity === 'warning') ?? [];
+  return (
+    <Box aria-label="Catalog health" component="section" mb="lg">
+      <Title order={2} mb="sm">
+        Catalog health
+      </Title>
+      <Text component="div" c="dimmed" mb="md">
+        Specs, domains and coverage counts can disagree because of how specs are named and described, not because of a defect in a test. This explains each number, where the totals differ, and what to change at the source. It only reads: it changes no result.
+      </Text>
+      <Stack gap="lg">
+        <Mappings health={health} tried={tried} />
+        {answer.isPending && (
+          <Text role="status" component="div" c="dimmed">
+            Reading the catalog…
+          </Text>
+        )}
+        {answer.isError && (
+          <Alert role="alert" color="red">
+            The catalog health could not be read. {answer.error.message}
+            <Group mt="xs">
+              <Button type="button" variant="light" onClick={() => void answer.refetch()}>
+                Try again
+              </Button>
+            </Group>
+          </Alert>
+        )}
+        {answer.data?.unsupported && (
+          <Alert role="status" color="blue">
+            This server is older than the catalog health report, so it cannot explain these counts. Upgrade the server to read it.
+          </Alert>
+        )}
+        {health && (
+          <>
+            <Alert role="status" color={health.ok ? 'green' : 'orange'} title={health.ok ? 'No warnings' : plural(warnings.length, 'warning', 'warnings')} data-health-summary>
+              {health.ok ? 'Nothing found that makes a count or a domain filter misleading.' : 'These make a count or a domain filter misleading. Each says what to change at its source.'}
+            </Alert>
+            <Reconciliation health={health} />
+            <Counts health={health} />
+            {health.aliases.length > 0 && (
+              <Box component="section" aria-label="Specs under more than one path">
+                <Title order={3} mb="xs">
+                  Specs under more than one path
+                </Title>
+                <Text size="sm" c="dimmed" mb="xs">
+                  Joined because a root mapping relates them. Every original path stays inspectable.
+                </Text>
+                <Table.ScrollContainer minWidth={420}>
+                  <Table data-health-aliases>
+                    <Table.Thead>
+                      <Table.Tr>
+                        <Table.Th scope="col">Spec</Table.Th>
+                        <Table.Th scope="col">Original paths</Table.Th>
+                      </Table.Tr>
+                    </Table.Thead>
+                    <Table.Tbody>
+                      {health.aliases.map((alias) => (
+                        <Table.Tr key={alias.path}>
+                          <Table.Td>
+                            <Code>{alias.path}</Code>
+                          </Table.Td>
+                          <Table.Td>
+                            <Stack gap={2}>
+                              {alias.sources.map((source) => (
+                                <Code key={source}>{source}</Code>
+                              ))}
+                            </Stack>
+                          </Table.Td>
+                        </Table.Tr>
+                      ))}
+                    </Table.Tbody>
+                  </Table>
+                </Table.ScrollContainer>
+              </Box>
+            )}
+            <Box component="section" aria-label="Domains">
+              <Title order={3} mb="xs">
+                Domains
+              </Title>
+              <Text size="sm" c="dimmed" mb="xs">
+                A domain is what a spec&apos;s own metadata says. Explicit metadata is always authoritative; a domain shared by nearly every spec is reported as a finding below, not changed.
+              </Text>
+              {health.domains.length === 0 ? (
+                <Text component="div" c="dimmed">
+                  No spec declares a domain.
+                </Text>
+              ) : (
+                <Table.ScrollContainer minWidth={320}>
+                  <Table data-health-domains>
+                    <Table.Thead>
+                      <Table.Tr>
+                        <Table.Th scope="col">Domain</Table.Th>
+                        <Table.Th scope="col" ta="right">
+                          Specs
+                        </Table.Th>
+                      </Table.Tr>
+                    </Table.Thead>
+                    <Table.Tbody>
+                      {health.domains.map((domain) => (
+                        <Table.Tr key={domain.name}>
+                          <Table.Td>{domain.name}</Table.Td>
+                          <Table.Td ta="right">{domain.specs}</Table.Td>
+                        </Table.Tr>
+                      ))}
+                    </Table.Tbody>
+                  </Table>
+                </Table.ScrollContainer>
+              )}
+            </Box>
+            <Box component="section" aria-label="Findings">
+              <Title order={3} mb="xs">
+                Findings
+              </Title>
+              {health.findings.length === 0 ? (
+                <Text component="div" c="dimmed">
+                  Nothing to report.
+                </Text>
+              ) : (
+                <Accordion multiple defaultValue={warnings.map((item) => item.code)}>
+                  {health.findings.map((item) => (
+                    <Finding key={item.code} item={item} />
+                  ))}
+                </Accordion>
+              )}
+            </Box>
+            <Box component="section" aria-label="Identity">
+              <Title order={3} mb="xs">
+                Identity
+              </Title>
+              <Text size="sm" component="div" data-health-identity>
+                Fallback identity (known by title only): {health.identity.fallbackIdentity} of {health.identity.checks} checks.
+                {health.identity.declaredBehaviorIds !== undefined && ` Declared behavior ids: ${health.identity.declaredBehaviorIds}. Declared example ids: ${health.identity.declaredExampleIds ?? 0}.`}
+              </Text>
+              <Text size="sm" c="dimmed" component="div" mt="xs">
+                {health.identity.basis}
+              </Text>
+            </Box>
+          </>
+        )}
+      </Stack>
+    </Box>
+  );
+}

package/packages/visualizer/src/explorer/catalog.tsx

@@ -26,6 +26,7 @@ import {
   type FilterName,
   type QueryFacets
 } from '@crvouga/atlas/reports/artifact-query';
+import { catalogHealth, type CatalogHealth, type RootMapping } from '@crvouga/atlas/reports/catalog-health';
 import {
   artifactList,
   catalogModel,
@@ -371,3 +372,35 @@ export function useRunDetail(key: string | undefined) {
     retry: false
   });
 }
+
+/** What the Catalog health tab reads: the diagnostics, or that this server is too old to give them. */
+export type HealthAnswer = { readonly unsupported: false; readonly health: CatalogHealth } | { readonly unsupported: true };
+
+/**
+ * Why the Specs, domains and counts of the report disagree. From the server when it has one (it also applies the root
+ * mappings it is configured with, and says so in `roots[].source`); otherwise worked out here from the specs and
+ * results this page holds. A server without the route answers `unsupported`, and the page says so.
+ */
+export function useCatalogHealth(roots: readonly RootMapping[]) {
+  const catalog = useTestCatalog();
+  const asked = roots.map((root) => `${root.from}>${root.to}`);
+  return useQuery({
+    queryKey: ['catalog-health', catalog.version, asked.join('\u0001')],
+    queryFn: async ({ signal }): Promise<HealthAnswer> => {
+      if (catalog.source === 'server') {
+        const params = new URLSearchParams(asked.map((root) => ['root', root]));
+        try {
+          return { unsupported: false, health: await reportJson<CatalogHealth>(`/tests/health${params.size ? `?${params}` : ''}`, signal) };
+        } catch (error) {
+          if (notFound(error)) return { unsupported: true };
+          throw error;
+        }
+      }
+      return { unsupported: false, health: catalogHealth(catalog.model!, roots) };
+    },
+    enabled: catalog.model !== null,
+    placeholderData: keepPreviousData,
+    staleTime: Number.POSITIVE_INFINITY,
+    retry: false
+  });
+}

package/packages/visualizer/src/explorer/search.ts

@@ -2,7 +2,7 @@
  * @module Explorer address
  *
  * Everything the test explorer shows is in the address of the `/` route, so a link reproduces the view: the open test,
- * the words searched, the filters, the grouping, the order, the Runs tab with the run opened in it, the Compare tab with its two pinned runs (`base`, `cand`) and the behavior opened (`pair`), the exact layer a test's detail is pinned to, the recording and position of a shared moment in it (`clip`, `clipAt`), and the one file of a run's layer its Artifacts select. Filters that
+ * the words searched, the filters, the grouping, the order, the Runs tab with the run opened in it, the Compare tab with its two pinned runs (`base`, `cand`) and the behavior opened (`pair`), the Catalog health tab with the root mappings it tries (`root`), the exact layer a test's detail is pinned to, the recording and position of a shared moment in it (`clip`, `clipAt`), and the one file of a run's layer its Artifacts select. Filters that
  * take several values are comma-separated (`status=failed,flaky`); a comma or backslash inside a value is written `\,`
  * or `\\`, and the router encodes `#` and spaces. Anything unreadable is dropped, never an error.
  *
@@ -63,7 +63,9 @@ export const ExplorerSearchFields = {
   inRun: text,
   group: z.enum(TEST_GROUPS).optional().catch(undefined),
   sort: z.enum(EXPLORER_SORTS).optional().catch(undefined),
-  tab: z.enum(['runs', 'artifacts', 'collections', 'compare']).optional().catch(undefined),
+  tab: z.enum(['runs', 'artifacts', 'collections', 'compare', 'health']).optional().catch(undefined),
+  /** The root mappings (`from>to`, comma-separated) the Catalog health tab tries, beside those the server is configured with. */
+  root: text,
   /** The review collection opened in the Collections tab (its stable id), and the revision of it (default: the newest). */
   collection: text,
   rev: z.coerce.number().int().positive().optional().catch(undefined),
@@ -127,7 +129,8 @@ export type ExplorerSearch = {
   readonly inRun?: string;
   readonly group?: TestGroup;
   readonly sort?: ExplorerSort;
-  readonly tab?: 'runs' | 'artifacts' | 'collections' | 'compare';
+  readonly tab?: 'runs' | 'artifacts' | 'collections' | 'compare' | 'health';
+  readonly root?: string;
   readonly collection?: string;
   readonly rev?: number;
   readonly base?: string;