@crvouga/atlas 1.12.0 → 1.14.0

package/dist/schema/src/critique.js

@@ -0,0 +1,96 @@
+/**
+ * @module The `atlas.critique` evidence schema
+ *
+ * What an automated reviewer (a critic) says about one captured UI. It is not a new layer format: a critique is a
+ * check inside a part of kind `critique`, and the opinion rides in the check's `extensions["atlas.critique"]`, so by the
+ * rules of docs/extending.md it can never decide a result. The check's `status` says only whether the critic ran
+ * (`passed` a verdict was produced, `failed` the critic could not produce one, `running`, `not-run`).
+ *
+ * Everything except `schema`, `subject` and `critic` is optional, so a single score (a model-based critic) and rich
+ * findings (an LLM critic) are one shape. Every object is open, and `kind`, `category`, `severity`, `label` and `reason`
+ * are open strings: a value nobody has heard of is kept and shown generically, never rejected. A reader that cannot read
+ * the whole extension drops it and keeps the check and its status (`readCritique` in `@crvouga/atlas/critics`).
+ *
+ * @see docs/critics.md
+ * @see docs/extending.md
+ */
+import { z } from 'zod/v4';
+/** The key under which a critique is stored in a check's `extensions`. */
+export const CRITIQUE_EXTENSION = 'atlas.critique';
+/** The version of the `atlas.critique` extension a reader of this release understands. A critique of another version is unknown, not wrong. */
+export const CRITIQUE_SCHEMA_VERSION = 1;
+/** The `kind` of the report part that holds critiques. Parts of this kind are opinions: never counted, never part of the gate. */
+export const CRITIQUE_PART_KIND = 'critique';
+/** The prefix of the `producer` of a layer of critiques: `critic.<critic name>`. */
+export const CRITIC_PRODUCER_PREFIX = 'critic.';
+/** The region of the image a finding is about, in the stated unit (`px` of the stored image, or `normalized` 0..1). */
+export const CritiqueRegionSchema = z.looseObject({
+    unit: z.string().min(1).describe('`px` (pixels of the stored image) or `normalized` (0..1 of its width and height). Open vocabulary'),
+    x: z.number(),
+    y: z.number(),
+    w: z.number().nonnegative(),
+    h: z.number().nonnegative()
+});
+/** One thing a critic found: where, what kind, how bad, why, and what to do. Nothing is required. */
+export const CritiqueFindingSchema = z.looseObject({
+    id: z.string().min(1).optional().describe('Stable within the critique, so a reviewer can mark this finding valid or not'),
+    category: z.string().min(1).optional().describe('Open vocabulary: `spacing`, `contrast`, `alignment`, `overflow`, `hierarchy`…'),
+    severity: z.string().min(1).optional().describe('Open vocabulary, conventionally `info`, `minor`, `major`'),
+    confidence: z.number().min(0).max(1).optional(),
+    region: CritiqueRegionSchema.optional(),
+    rationale: z.string().optional(),
+    suggestion: z.string().optional()
+});
+/**
+ * How a score reads in context. A raw score is not absolute: a loading overlay is compared with other loading overlays,
+ * not with full screens, and a change against the same entry's previous image is more telling than the level.
+ */
+export const CritiqueRelativeSchema = z.looseObject({
+    stateKind: z.string().min(1).describe('The kind of UI state the score is relative to: `screen`, `overlay`, `loading`, `error`, `empty`…'),
+    percentile: z.number().min(0).max(100).optional().describe('Where the score falls among the project\'s scores of the same state kind, 0..100, higher is better'),
+    sampleSize: z.number().int().nonnegative().optional().describe('How many scores of that state kind the percentile is over'),
+    previousScore: z.number().optional().describe('The same entry\'s score for its previous image, from the same critic'),
+    delta: z.number().optional().describe('`score` minus `previousScore`')
+});
+/** The judgement: a score and how to read it, a label, a confidence. A critic that cannot score may give only a label. */
+export const CritiqueVerdictSchema = z.looseObject({
+    score: z.number().optional().describe('A finite number. `scale` says what it means'),
+    scale: z.string().optional().describe('For example `0..1, higher is better`'),
+    label: z.string().optional().describe('Open vocabulary, conventionally `ok` or `needs-polish`'),
+    confidence: z.number().min(0).max(1).optional(),
+    relative: CritiqueRelativeSchema.optional()
+});
+/** Why a critic produced no verdict: a reason code in an open vocabulary (`error`, `timeout`, `rate-limited`, `invalid-output`) and a message that holds no credential. */
+export const CritiqueFailureSchema = z.looseObject({
+    reason: z.string().min(1),
+    message: z.string().optional()
+});
+/**
+ * The `atlas.critique` extension, version 1: the image judged (`subject`), who judged (`critic`, `model`,
+ * `parameters`), the opinion (`verdict`, `findings`) or why there is none (`failure`), and what it cost (`usage`).
+ * The prompt is recorded only as a hash (`parameters.rubric`). Emitted as `critique.schema.json`.
+ */
+export const CritiqueSchema = z.looseObject({
+    schema: z.number().int().positive().describe('The version of this extension. 1'),
+    subject: z.looseObject({
+        entryKey: z.string().min(1).describe('The catalog entry that was judged'),
+        imageSha256: z.string().min(1).describe('The hash of the exact image bytes that were judged. When the entry\'s image changes, this critique judged an earlier image'),
+        state: z.string().min(1).optional().describe('The kind of UI state: `screen`, `overlay`, `loading`, `error`, `empty`…')
+    }),
+    critic: z.looseObject({
+        name: z.string().min(1),
+        version: z.string().min(1).describe('Of the critic\'s own logic. A newer version replaces an older one'),
+        kind: z.string().min(1).optional().describe('Open vocabulary: `model`, `llm`, `ml`, `heuristic`…')
+    }),
+    model: z.looseObject({ id: z.string().min(1), provider: z.string().optional() }).optional(),
+    parameters: z.record(z.string(), z.unknown()).optional().describe('Everything else that explains the result: temperature, seed, the SHA-256 of the rubric'),
+    verdict: CritiqueVerdictSchema.optional(),
+    findings: z.array(CritiqueFindingSchema).optional(),
+    failure: CritiqueFailureSchema.optional(),
+    usage: z.looseObject({
+        inputTokens: z.number().nonnegative().optional(),
+        outputTokens: z.number().nonnegative().optional(),
+        latencyMs: z.number().nonnegative().optional(),
+        costUsd: z.number().nonnegative().optional()
+    }).optional()
+});

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

@@ -2,7 +2,7 @@
  * @module Schema package entry point (`@crvouga/atlas/schema`)
  *
  * Re-exports every Zod schema, constant and inferred type of the Atlas contract: the layer format and report status
- * (`layer`), the statechart run manifest (`manifest`, `common`), the spec file formats (`spec`), the run index and
+ * (`layer`), the `atlas.critique` evidence of automated UI reviewers (`critique`), the statechart run manifest (`manifest`, `common`), the spec file formats (`spec`), the run index and
  * report sources the viewer reads (`runs-index`, `report-sources`) and the server configuration (`server-config`).
  * The JSON Schemas shipped in `schemas/` are generated from these by `bun run schemas`.
  *
@@ -14,6 +14,7 @@ export * from './runs-index.js';
 export * from './spec.js';
 export * from './report-sources.js';
 export * from './layer.js';
+export * from './critique.js';
 export * from './server-config.js';
 export * from './user-state.js';
 export * from './api.js';

package/dist/schema/src/index.js

@@ -2,7 +2,7 @@
  * @module Schema package entry point (`@crvouga/atlas/schema`)
  *
  * Re-exports every Zod schema, constant and inferred type of the Atlas contract: the layer format and report status
- * (`layer`), the statechart run manifest (`manifest`, `common`), the spec file formats (`spec`), the run index and
+ * (`layer`), the `atlas.critique` evidence of automated UI reviewers (`critique`), the statechart run manifest (`manifest`, `common`), the spec file formats (`spec`), the run index and
  * report sources the viewer reads (`runs-index`, `report-sources`) and the server configuration (`server-config`).
  * The JSON Schemas shipped in `schemas/` are generated from these by `bun run schemas`.
  *
@@ -14,6 +14,7 @@ export * from './runs-index.js';
 export * from './spec.js';
 export * from './report-sources.js';
 export * from './layer.js';
+export * from './critique.js';
 export * from './server-config.js';
 export * from './user-state.js';
 export * from './api.js';

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

@@ -11,9 +11,13 @@
  * @see docs/server.md
  */
 import { z } from 'zod/v4';
-/** What a bearer token may do: `read` (look), `publish` (also upload) or `admin` (also remove scratch objects). */
+/**
+ * What a bearer token may do: `read` (look), `critic` (also publish critiques, and nothing else), `publish` (also upload
+ * anything) or `admin` (also remove scratch objects).
+ */
 export declare const ServerRoleSchema: z.ZodEnum<{
     read: "read";
+    critic: "critic";
     publish: "publish";
     admin: "admin";
 }>;
@@ -27,6 +31,7 @@ export declare const ServerTokenSchema: z.ZodObject<{
     name: z.ZodString;
     role: z.ZodEnum<{
         read: "read";
+        critic: "critic";
         publish: "publish";
         admin: "admin";
     }>;
@@ -45,6 +50,7 @@ export declare const ServerConfigSchema: z.ZodObject<{
             name: z.ZodString;
             role: z.ZodEnum<{
                 read: "read";
+                critic: "critic";
                 publish: "publish";
                 admin: "admin";
             }>;

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

@@ -11,8 +11,11 @@
  * @see docs/server.md
  */
 import { z } from 'zod/v4';
-/** What a bearer token may do: `read` (look), `publish` (also upload) or `admin` (also remove scratch objects). */
-export const ServerRoleSchema = z.enum(['read', 'publish', 'admin']);
+/**
+ * What a bearer token may do: `read` (look), `critic` (also publish critiques, and nothing else), `publish` (also upload
+ * anything) or `admin` (also remove scratch objects).
+ */
+export const ServerRoleSchema = z.enum(['read', 'critic', 'publish', 'admin']);
 /**
  * A bearer token: a name for logs, a role, and the token itself or the name of the environment variable that holds it
  * (exactly one of the two).
@@ -20,7 +23,7 @@ export const ServerRoleSchema = z.enum(['read', 'publish', 'admin']);
 export const ServerTokenSchema = z
     .strictObject({
     name: z.string().min(1).describe('Shown in logs, never the token itself'),
-    role: ServerRoleSchema.describe('`read` may look. `publish` may also upload. `admin` may also remove scratch objects'),
+    role: ServerRoleSchema.describe('`read` may look. `critic` may also publish critiques (layers of producer `critic.*` whose parts are all of kind `critique`). `publish` may also upload. `admin` may also remove scratch objects'),
     token: z.string().min(12).optional().describe('The token. Prefer `tokenEnv`, so the file holds no secret'),
     tokenEnv: z.string().optional().describe('The name of the environment variable that holds the token')
 })

package/dist/server/src/app.js

@@ -28,6 +28,7 @@ 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 { 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';
 import { artifactList, artifactsMarkdown, catalogMarkdown, catalogModel, historyMarkdown, parseTestQuery, runDetail, runList, runMarkdown, runsMarkdown, testCatalog, testHistory } from '../../reports/src/test-catalog.js';
 import { llmsTxt } from './llms.js';
@@ -418,6 +419,7 @@ function createProjectApplication(options) {
         }
         return model.value;
     };
+    let uiModel;
     const wantsMarkdown = (c) => {
         const format = c.req.query('format');
         return format === 'markdown' || format === 'md' || (format === undefined && /\btext\/markdown\b/.test(c.req.header('accept') ?? ''));
@@ -502,6 +504,19 @@ function createProjectApplication(options) {
         const document = () => artifactList(index.history, found.version, parseArtifactFilter(search), { limit: number('limit', 100), offset: number('offset', 0), domainOf: path => domains.get(path) });
         return answer(c, found.version, document, () => artifactsMarkdown(document()), `artifacts|${search.toString()}|${wantsMarkdown(c)}`);
     });
+    app.get('/api/reports/ui-catalog', async (c) => {
+        if (!index.ready)
+            return notReady(c);
+        const snapshot = index.snapshot();
+        const search = new URL(c.req.url).searchParams;
+        const number = (name, fallback) => (/^\d+$/.test(search.get(name) ?? '') ? Number(search.get(name)) : fallback);
+        // The catalog is a function of the report, so it is built once per version and narrowed per question.
+        if (uiModel?.version !== snapshot.version)
+            uiModel = { version: snapshot.version, value: uiCatalog(snapshot.layers, { version: snapshot.version, backends: snapshot.backends, notices: snapshot.notices }) };
+        const whole = uiModel.value;
+        const document = () => pageUiCatalog(filterUiCatalog(whole, parseUiCatalogQuery(search)), { limit: number('limit', 200), offset: number('offset', 0) });
+        return answer(c, snapshot.version, document, () => uiCatalogMarkdown(document()), `ui-catalog|${search.toString()}|${wantsMarkdown(c)}`);
+    });
     app.get('/api/reports/runs/detail', async (c) => {
         if (!index.ready)
             return notReady(c);

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

@@ -1,7 +1,7 @@
 /**
  * @module Authentication and roles
  *
- * Who is asking, and may they. Tokens have a role (`read` < `publish` < `admin`) and are compared in constant time. Reading
+ * Who is asking, and may they. Tokens have a role (`read` < `critic` < `publish` < `admin`) and are compared in constant time. Reading
  * accepts a Bearer token or the browser's sign-in box (any user name, the token as the password); changing anything needs
  * the Bearer header, because a browser sends the sign-in box's credentials to any page that asks, which would let another
  * site upload with them. A server with no tokens is open, and refuses to listen beyond this machine unless told it may.

package/dist/server/src/auth.js

@@ -1,13 +1,13 @@
 /**
  * @module Authentication and roles
  *
- * Who is asking, and may they. Tokens have a role (`read` < `publish` < `admin`) and are compared in constant time. Reading
+ * Who is asking, and may they. Tokens have a role (`read` < `critic` < `publish` < `admin`) and are compared in constant time. Reading
  * accepts a Bearer token or the browser's sign-in box (any user name, the token as the password); changing anything needs
  * the Bearer header, because a browser sends the sign-in box's credentials to any page that asks, which would let another
  * site upload with them. A server with no tokens is open, and refuses to listen beyond this machine unless told it may.
  */
 import { timingSafeEqual } from 'node:crypto';
-const RANK = { read: 1, publish: 2, admin: 3 };
+const RANK = { read: 1, critic: 2, publish: 3, admin: 4 };
 function same(a, b) {
     const left = Buffer.from(a), right = Buffer.from(b);
     return left.length === right.length && timingSafeEqual(left, right);

package/dist/server/src/config.js

@@ -60,7 +60,7 @@ export const SERVER_SETTINGS = [
     { 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 } },
-    { summary: 'The admin token (also `ATLAS_PUBLISH_TOKEN` and `ATLAS_READ_TOKEN` for the other roles, or `auth.tokens` in the file)', key: 'auth.tokens', flag: null, env: ['ATLAS_TOKEN'], default: 'none: the server is open and listens on this machine only', example: { value: 'admin-token-123456', read: c => c.tokens.map(token => token.role), expected: ['admin'] } },
+    { summary: 'The admin token (also `ATLAS_PUBLISH_TOKEN`, `ATLAS_CRITIC_TOKEN` and `ATLAS_READ_TOKEN` for the other roles, or `auth.tokens` in the file)', key: 'auth.tokens', flag: null, env: ['ATLAS_TOKEN'], default: 'none: the server is open and listens on this machine only', example: { value: 'admin-token-123456', read: c => c.tokens.map(token => token.role), expected: ['admin'] } },
     { summary: 'The configuration file', key: '(the file itself)', flag: '--config <file>', env: ['ATLAS_CONFIG'], default: '`./atlas.server.json` when it exists', example: { value: 'custom.json', read: c => path.basename(c.configFile ?? ''), expected: 'custom.json' } },
     { summary: 'Largest uploaded object in MiB', key: 'limits.maxObjectMiB', flag: null, env: ['ATLAS_MAX_OBJECT_MIB'], default: '`256`', example: { value: '64', read: c => c.limits.maxObjectMiB, expected: 64 } },
     { summary: 'Largest JSON upload in MiB', key: 'limits.maxJsonMiB', flag: null, env: ['ATLAS_MAX_JSON_MIB'], default: '`32`', example: { value: '8', read: c => c.limits.maxJsonMiB, expected: 8 } },
@@ -172,7 +172,7 @@ export function loadServerConfig(argv, env, cwd, read = file => readFileSync(fil
             throw new ConfigError(`Token "${item.name}" reads ${item.tokenEnv} and it is not set`);
         tokens.push({ name: item.name, role: item.role, token });
     }
-    for (const [variable, role, name] of [['ATLAS_TOKEN', 'admin', 'admin'], ['ATLAS_PUBLISH_TOKEN', 'publish', 'publish'], ['ATLAS_READ_TOKEN', 'read', 'read']]) {
+    for (const [variable, role, name] of [['ATLAS_TOKEN', 'admin', 'admin'], ['ATLAS_PUBLISH_TOKEN', 'publish', 'publish'], ['ATLAS_CRITIC_TOKEN', 'critic', 'critic'], ['ATLAS_READ_TOKEN', 'read', 'read']]) {
         if (env[variable])
             tokens.push({ name, role, token: env[variable].trim() });
     }

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

@@ -1,7 +1,7 @@
 /** 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 declare const API_VERSION = "1.5.0";
-/** Who may call an operation: `none` (anyone), or the least role that may (`read` < `publish` < `admin`). */
-export type Role = 'none' | 'read' | 'publish' | 'admin';
+export declare const API_VERSION = "1.6.0";
+/** Who may call an operation: `none` (anyone), or the least role that may (`read` < `critic` < `publish` < `admin`). */
+export type Role = 'none' | 'read' | 'critic' | 'publish' | 'admin';
 type JsonSchema = Record<string, unknown>;
 type Param = {
     readonly name: string;

package/dist/server/src/openapi.js

@@ -14,10 +14,10 @@
  */
 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, CatalogHealthSchema, TestHistorySchema, TestReliabilitySchema, RunListSchema, RunDetailSchema, ArtifactListSchema, ArtifactTagEditSchema, ArtifactTagEntrySchema, ArtifactTagsSchema, ReviewCollectionRequestSchema, ReviewCollectionSchema, ReviewCollectionListSchema, ReviewCollectionDetailSchema, ReviewNoteInputSchema, ReviewNoteSchema, ReviewManifestSchema } 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, TestReliabilitySchema, RunListSchema, RunDetailSchema, ArtifactListSchema, UiCatalogSchema, ArtifactTagEditSchema, ArtifactTagEntrySchema, ArtifactTagsSchema, ReviewCollectionRequestSchema, ReviewCollectionSchema, ReviewCollectionListSchema, ReviewCollectionDetailSchema, ReviewNoteInputSchema, ReviewNoteSchema, ReviewManifestSchema } from '../../schema/src/api.js';
 import { LiveRunSchema, LiveRunStartSchema, LiveRunUpdateSchema, ServerEditableSettingsSchema, ServerSettingsSnapshotSchema, GcPolicySchema, GcSnapshotSchema, GcRunResultSchema, 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.5.0';
+export const API_VERSION = '1.6.0';
 /** The JSON Schema of a Zod schema, as OpenAPI 3.1 embeds it. `output` for what the server sends, `input` for what it accepts. */
 function schemaOf(schema, io = 'output') {
     const { $schema: _dialect, ...json } = z.toJSONSchema(schema, { target: 'draft-2020-12', unrepresentable: 'any', io });
@@ -38,7 +38,7 @@ const COMPONENTS = {
     Outline: [OutlineSchema, 'output'], EvidencePage: [EvidencePageSchema, 'output'], LayerRows: [LayerRowsSchema, 'output'], CheckDetail: [CheckDetailSchema, 'output'],
     ArtifactTagEdit: [ArtifactTagEditSchema, 'input'], ArtifactTagEntry: [ArtifactTagEntrySchema, 'output'], ArtifactTags: [ArtifactTagsSchema, 'output'],
     ReviewCollectionRequest: [ReviewCollectionRequestSchema, 'input'], ReviewCollection: [ReviewCollectionSchema, 'output'], ReviewCollectionList: [ReviewCollectionListSchema, 'output'], ReviewCollectionDetail: [ReviewCollectionDetailSchema, 'output'], ReviewNoteInput: [ReviewNoteInputSchema, 'input'], ReviewNote: [ReviewNoteSchema, 'output'], ReviewManifest: [ReviewManifestSchema, 'output'],
-    TestCatalog: [TestCatalogSchema, 'output'], CatalogHealth: [CatalogHealthSchema, 'output'], TestHistory: [TestHistorySchema, 'output'], TestReliability: [TestReliabilitySchema, 'output'], RunList: [RunListSchema, 'output'], ArtifactList: [ArtifactListSchema, 'output'], RunDetail: [RunDetailSchema, 'output'],
+    TestCatalog: [TestCatalogSchema, 'output'], CatalogHealth: [CatalogHealthSchema, 'output'], TestHistory: [TestHistorySchema, 'output'], TestReliability: [TestReliabilitySchema, 'output'], RunList: [RunListSchema, 'output'], ArtifactList: [ArtifactListSchema, 'output'], UiCatalog: [UiCatalogSchema, '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']
 };
@@ -246,7 +246,7 @@ const BASE_OPERATIONS = [
         responses: { '200': { description: 'It exists.' }, '401': UNAUTHORIZED, '404': problem('No such object.') }
     },
     {
-        route: 'PUT /api/store/*', path: '/api/store/{key}', operationId: 'putObject', tag: 'Store protocol', role: 'publish',
+        route: 'PUT /api/store/*', path: '/api/store/{key}', operationId: 'putObject', tag: 'Store protocol', role: 'critic',
         summary: 'Upload an object',
         description: [
             'The write half of the `ObjectStore` interface. The server checks what it can from the bytes in hand and says no to what would corrupt the report for everyone:',
@@ -257,7 +257,9 @@ const BASE_OPERATIONS = [
             '- a **run manifest** must have passed its privacy scan;',
             '- keys are immutable: the same bytes again are `200` (a retry), other bytes under the same key are `409`.',
             '',
-            'Upload in dependency order: blobs, then the manifest, then the catalog entry. `atlas report publish`, `atlas report stream` and `httpStore` do. Needs a `Bearer` token of role `publish` or `admin`; a browser\'s sign-in box is refused.'
+            'Upload in dependency order: blobs, then the manifest, then the catalog entry. `atlas report publish`, `atlas report stream` and `httpStore` do. Needs a `Bearer` token of role `publish` or `admin`; a browser\'s sign-in box is refused.',
+            '',
+            'A token of role `critic` may upload only what a critic publishes: blobs, and layers (and their catalog entries) whose `producer` is `critic.<name>` and whose parts are all of kind `critique`. Anything else is `403` with the rule it broke, and nothing is stored.'
         ].join('\n'),
         parameters: [KEY, { name: 'content-type', in: 'header', description: 'Stored with the object and returned when it is read.', schema: str }],
         body: { description: 'The object\'s bytes.', contentType: 'application/octet-stream', schema: { type: 'string', format: 'binary' }, required: true },
@@ -458,6 +460,26 @@ const BASE_OPERATIONS = [
         ],
         responses: { '200': json('The matching results and the facets.', 'ArtifactList'), '304': { description: 'Unchanged since the `If-None-Match` ETag.' }, '401': UNAUTHORIZED, '503': NOT_READY }
     },
+    {
+        route: 'GET /api/reports/ui-catalog', path: '/api/reports/ui-catalog', operationId: 'getUiCatalog', tag: 'Report', role: 'read',
+        summary: 'The UI catalog: captured UI states per profile, and what is still expected',
+        description: 'A browsable inventory of the product\'s user interface, computed from the winning results of the `ui-state` and `ui-plan` parts of every layer (see the UI catalog guide). Each state is a check id; each cell is one profile of it (the layer\'s environment and parameters) with its coverage: `captured` only when the winning capture passed, `failed`, `capturing`, `skipped`, or `missing` when a plan expects it and nothing has been captured. A picture is read from the cell\'s `capture.image.path` under the reports API root, or `uri`. What is expected is itself a layer, so a shard that never published leaves its states `missing`, never captured. The document equals what the viewer computes from the same report. Narrow it by `q` (words), `coverage`, `profile` (a profile `key`), `area`, `route`, `cohort`, `flag`, `surface` and `producer`: AND across parameters, OR within one; a state keeps only the cells that match `profile` and `coverage`. Page the states with `limit` and `offset`. Viewers need not poll: they hold the report over `/api/events` and read changes with `/api/reports/evidence/effective?since=`.',
+        parameters: [
+            { name: 'limit', in: 'query', description: 'At most this many states (default 200).', schema: { type: 'integer', minimum: 0 } },
+            { name: 'offset', in: 'query', description: 'Skip this many states (default 0).', schema: { type: 'integer', minimum: 0 } },
+            { name: 'q', in: 'query', description: 'Words that must all appear in a state\'s id, title, route, fixture, cohort, area, flags, surfaces or producers.', schema: str },
+            { name: 'coverage', in: 'query', description: 'Coverage values: `captured`, `failed`, `capturing`, `skipped`, `missing`. Comma-separated.', schema: str },
+            { name: 'profile', in: 'query', description: 'Profile keys, as listed in `profiles[].key`.', schema: str },
+            { name: 'area', in: 'query', description: 'Areas.', schema: str },
+            { name: 'route', in: 'query', description: 'Routes.', schema: str },
+            { name: 'cohort', in: 'query', description: 'Cohorts.', schema: str },
+            { name: 'flag', in: 'query', description: 'Feature flags a state was captured with.', schema: str },
+            { name: 'surface', in: 'query', description: 'Surfaces a state covers.', schema: str },
+            { name: 'producer', in: 'query', description: 'Producers that captured or planned a state.', schema: str },
+            { name: 'format', in: 'query', description: '`markdown` for Markdown instead of JSON.', schema: { type: 'string', enum: ['json', 'markdown'] } }
+        ],
+        responses: { '200': json('The catalog.', 'UiCatalog'), '304': { description: 'Unchanged since the `If-None-Match` ETag.' }, '401': UNAUTHORIZED, '503': NOT_READY }
+    },
     {
         route: 'GET /api/reports/runs/detail', path: '/api/reports/runs/detail', operationId: 'getReportRun', tag: 'Report', role: 'read',
         summary: 'Every test one run recorded',
@@ -590,6 +612,7 @@ export const NOT_OPERATIONS = new Map([
 const SECURITY = {
     none: [],
     read: [{ bearer: [] }, { basic: [] }],
+    critic: [{ bearer: [] }],
     publish: [{ bearer: [] }],
     admin: [{ bearer: [] }]
 };
@@ -623,7 +646,7 @@ export function openApiDocument(options = {}) {
             description: [
                 'One Atlas node serves multiple projects. Clients select a project using ?project=<slug>, X-Atlas-Project, or /api/projects/<slug>/… . Each project has independent specs, layers, recordings, status, and event streams. Within each project, the newest completed result of every check wins its slot. Unqualified requests address the legacy default project.',
                 '',
-                '**Authentication.** With tokens configured, send `Authorization: Bearer <token>`. Roles: `read` < `publish` < `admin`. Uploading needs a Bearer token; a browser\'s HTTP Basic sign-in (any user name, the token as the password) is accepted for reading only. A server with no tokens is open and listens on this machine only unless told otherwise.',
+                '**Authentication.** With tokens configured, send `Authorization: Bearer <token>`. Roles: `read` < `critic` < `publish` < `admin`. A `critic` token may read, and publish critiques (layers of automated reviewers) and nothing else. Uploading needs a Bearer token; a browser\'s HTTP Basic sign-in (any user name, the token as the password) is accepted for reading only. A server with no tokens is open and listens on this machine only unless told otherwise.',
                 '',
                 '**Errors** are [RFC 9457](https://www.rfc-editor.org/rfc/rfc9457) problem documents (`application/problem+json`) with a `detail` that says what to do. `401` send a token, `403` that token may not, `409` upload what this depends on first or you are changing something immutable, `413` too large, `422` not valid, `503` still starting (retry after `Retry-After`).',
                 '',

package/dist/server/src/store-api.js

@@ -12,6 +12,7 @@ import { Hono } from 'hono';
 import { isPaged } from '../../reports/src/object-store.js';
 import { readBytes } from '../../reports/src/object-io.js';
 import { UNTRUSTED_HEADERS } from '../../reports/src/attachment-response.js';
+import { criticScopeViolation } from '../../critics/src/scope.js';
 import { classify, isCatalog, Refusal, sameBytes, validateUpload, validKey } from './validate.js';
 /** Read a request body, refusing as soon as it is over the limit rather than after holding it all. */
 export async function readLimited(request, limit) {
@@ -55,6 +56,40 @@ const decode = (c, prefix) => {
         return null;
     }
 };
+const decoder = new TextDecoder();
+/**
+ * What a critic-role token may upload: blobs, and layers (and the catalog entries that make them visible) whose producer
+ * is `critic.<name>` and whose parts are all of kind `critique`. Anything else, including a key that is not a layer at
+ * all, is refused with `403` and the rule it broke, before anything is stored. Blobs are checked against their name by
+ * the upload validation, so on their own they are harmless.
+ */
+async function assertCriticMayStore(name, bytes, store) {
+    const known = classify(name);
+    if (known?.kind === 'blob')
+        return;
+    if (known?.kind !== 'layer' && known?.kind !== 'layer-catalog')
+        throw new Refusal(403, `A critic token may upload only critiques, not "${name}". Use a publish token for anything else.`);
+    let text;
+    if (known.kind === 'layer')
+        text = decoder.decode(bytes);
+    else {
+        const stored = await store.get(`layers/manifests/${known.id}.json`);
+        // A catalog entry for a layer that is not there is refused by the upload validation, as for everyone.
+        if (!stored)
+            return;
+        text = decoder.decode(await readBytes(stored.body));
+    }
+    let layer;
+    try {
+        layer = JSON.parse(text);
+    }
+    catch {
+        return;
+    }
+    const violation = criticScopeViolation(layer ?? {});
+    if (violation)
+        throw new Refusal(403, violation);
+}
 /**
  * The store protocol: the seven operations of an object store over HTTP, for what the server keeps. A client
  * that publishes to it uses the same code that publishes to a folder or a bucket. It differs from a bucket in
@@ -134,7 +169,8 @@ export function storeApi(options) {
         return new Response(stored.body, { headers });
     });
     app.put('/*', async (c) => {
-        const verdict = auth.check(c.req.raw, 'publish');
+        // A critic may upload too, but only what a critic publishes (see `assertCriticMayStore`).
+        const verdict = auth.check(c.req.raw, 'critic');
         if (!verdict.ok)
             return refuse(c, verdict.status, verdict.message);
         const name = key(c);
@@ -143,6 +179,8 @@ export function storeApi(options) {
         try {
             const bytes = await readLimited(c.req.raw, options.maxObjectBytes);
             return await exclusive(name, async () => {
+                if (verdict.identity.role === 'critic')
+                    await assertCriticMayStore(name, bytes, store);
                 const kind = await validateUpload(name, bytes, store, layer => { recent.set(layer.id, layer); if (recent.size > 8)
                     recent.delete(recent.keys().next().value); });
                 // A blob's name is the digest of what is in it, which was just checked: one that is there is this one, however it was compressed.

package/docs/agents.md

@@ -103,6 +103,7 @@ The complete public export map is generated from the package manifest (wildcards
 @crvouga/atlas/vitest
 @crvouga/atlas/schema
 @crvouga/atlas/server
+@crvouga/atlas/critics
 @crvouga/atlas/reports/*
 @crvouga/atlas/schemas/*
 @crvouga/atlas/openapi.json