@crvouga/atlas 0.14.0 → 0.16.0

package/docs/reference/reports.md

@@ -4,6 +4,209 @@ Layered evidence for any kind of spec: publishing layers, stores (folder, S3, an
 
 > Generated from the doc comments of `packages/reports/src` by `bun run docs`. Do not edit: change the comment next to the code.
 
+### Reviewer tags in a store
+
+Source: `packages/reports/src/artifact-tag-store.ts`. Import: `@crvouga/atlas/reports/artifact-tag-store`
+
+Where a reviewer's tags for attachments are kept: one small immutable object per edit under
+`curation/artifact-tags/`, named by time and a random id so editors never overwrite one another, and never changed
+or deleted afterwards. The layers they are about are not touched. The list of edits is the audit trail: who changed
+which tags of which attachment, and when. `foldArtifactTags` turns it into the tags that stand now.
+
+See docs/server.md#tagging-artifacts
+
+#### `ARTIFACT_TAGS_PREFIX`
+
+```ts
+export const ARTIFACT_TAGS_PREFIX = …
+```
+
+The prefix of every recorded edit in a store.
+
+#### `ArtifactTagError`
+
+```ts
+export class ArtifactTagError extends Error
+```
+
+The edit was not acceptable (`status` is the HTTP status to answer).
+
+#### `recordArtifactTags`
+
+```ts
+export async function recordArtifactTags(store: ObjectStore, input: unknown, by: string, atMs: number): Promise<ArtifactTagEntry>
+```
+
+Validates an edit (`ArtifactTagEditSchema`), normalizes its tags and records it as a new object in `store`, by
+`by` at `atMs`. Throws {@link ArtifactTagError} for a body that is not an edit, a tag that is not a tag (empty, or
+over 64 characters) or an edit that changes nothing. Recording the same edit twice records two entries.
+
+#### `readArtifactTagEntries`
+
+```ts
+export async function readArtifactTagEntries(store: ObjectStore): Promise<ArtifactTagEntry[]>
+```
+
+Every recorded edit in `store`, oldest first. An object that cannot be read as an edit is skipped (unknown, never
+guessed at). A store with none gives an empty list. Transport errors throw.
+
+### Artifact tags
+
+Source: `packages/reports/src/artifact-tags.ts`. Import: `@crvouga/atlas/reports/artifact-tags`
+
+The tags of one attachment (a recording, a screenshot, a trace): how a tag is normalized so `demo` and `#demo`
+are the same tag, which tags an attachment shows (its producer's, its reviewers', and those it inherits from its
+check and run), and how a reviewer's edits fold into the tags that stand now. Pure functions, safe in a browser.
+
+Tags describe evidence; they never decide a status, a slot or a winner. A producer writes `tags` on the attachment
+inside an immutable layer. A reviewer's tags live apart, as an append-only list of edits that the server records
+with who made each and when (`artifact-tag-store.ts`); the layer is never rewritten.
+
+See docs/rich-evidence.md#tagging-artifacts-and-demos
+
+#### `MAX_TAG_LENGTH`
+
+```ts
+export const MAX_TAG_LENGTH = …
+```
+
+The longest a normalized tag may be, in characters.
+
+#### `normalizeTag`
+
+```ts
+export function normalizeTag(raw: string): string | null
+```
+
+Normalizes a tag so equal tags compare equal: Unicode NFC, any leading `#` removed, surrounding whitespace
+trimmed, letters lower-cased and each run of whitespace inside turned into one `-`. Every other character is kept,
+so `Smoke`, `#smoke` and ` smoke ` are `smoke`, and `team/payments` or `release=2` stay as they are. Returns
+`null` for a tag that is empty after that (`''`, `'#'`, `'  '`) or longer than {@link MAX_TAG_LENGTH}.
+
+**Example**
+
+```ts
+normalizeTag('#Demo'); // 'demo'
+normalizeTag('release candidate'); // 'release-candidate'
+normalizeTag('#'); // null
+```
+
+#### `normalizeTags`
+
+```ts
+export function normalizeTags(raw: Iterable<string> | undefined): string[]
+```
+
+Normalizes every tag with {@link normalizeTag}, dropping the ones that are not tags and the repeats; the first of each keeps its place.
+
+#### `displayTag`
+
+```ts
+export const displayTag = …
+```
+
+The tag as a person sees it: `#demo`.
+
+#### `artifactRef`
+
+```ts
+export function artifactRef(attachment: Pick<Attachment, 'id' | 'bundleKey' | 'name'>): string
+```
+
+How an edit names an attachment: `id:<id>` when it has an `id`, else `key:<bundleKey>` (its bytes), else
+`name:<name>`. It is stable for a layer, which never changes. Two attachments in one check with the same bytes and
+no `id` share a reference, and so share reviewer tags; give them an `id` to tag them apart.
+
+#### `ArtifactTarget`
+
+```ts
+export type ArtifactTarget = {
+  readonly layer: string;
+  readonly check: string;
+  readonly kind?: string | undefined;
+  readonly artifact: string;
+};
+```
+
+Where a reviewer's tags are about: one attachment of one check of one archived layer.
+
+#### `ArtifactTagEntry`
+
+```ts
+export type ArtifactTagEntry = {
+  readonly id: string;
+  readonly target: ArtifactTarget;
+  readonly add: readonly string[];
+  readonly remove: readonly string[];
+  readonly by: string;
+  readonly atMs: number;
+};
+```
+
+One recorded edit. Entries are never changed or removed.
+
+#### `targetKey`
+
+```ts
+export const targetKey = …
+```
+
+A string that is equal for equal targets (the part `kind` is optional and then does not matter).
+
+#### `ReviewerTag`
+
+```ts
+export type ReviewerTag = { readonly tag: string; readonly by: string; readonly atMs: number };
+```
+
+A tag a reviewer added: who added it last, and when.
+
+#### `foldArtifactTags`
+
+```ts
+export function foldArtifactTags(entries: readonly ArtifactTagEntry[]): Map<string, ReviewerTag[]>
+```
+
+Folds the recorded edits (in any order) into the reviewer tags that stand now, by target (see {@link targetKey}).
+Edits apply oldest first, ties by `id`; a tag added, removed and added again stands, with the time and author of
+the last add. A target whose tags were all removed is absent. Entries that are not understood are ignored.
+
+#### `TagSource`
+
+```ts
+export type TagSource = 'artifact' | 'reviewer' | 'inherited';
+```
+
+Where a shown tag comes from: the attachment's own producer (`artifact`), a reviewer after the upload (`reviewer`), or the check or run around it (`inherited`).
+
+#### `ArtifactTag`
+
+```ts
+export type ArtifactTag = { readonly tag: string; readonly source: TagSource; readonly by?: string; readonly atMs?: number };
+```
+
+One tag an attachment shows, with its source and, for a reviewer's tag, who added it and when.
+
+#### `artifactTagsOf`
+
+```ts
+export function artifactTagsOf(attachment: Pick<Attachment, 'tags'>, options: { readonly reviewer?: readonly ReviewerTag[]; readonly inherited?: Iterable<string> } = {}): ArtifactTag[]
+```
+
+The tags one attachment shows, normalized and without repeats: its producer's own (`artifact`), then the
+reviewers' (`reviewer`), then those of its check and run that it does not have itself (`inherited`). A tag it has
+more than once is shown once, by the first source above.
+
+#### `hasArtifactTag`
+
+```ts
+export function hasArtifactTag(tags: readonly ArtifactTag[], wanted: string, options: { readonly inherited?: boolean } = {}): boolean
+```
+
+Does an attachment match a tag (either spelling)? An exact query (`inherited: false`, the default) matches only the
+tags the attachment has itself, from its producer or a reviewer; an inherited query also matches the tags it
+inherits from its check and run. The two differ for a recording that is untagged under a tagged run.
+
 ### Reading the files attachments name
 
 Source: `packages/reports/src/attachment-files.ts`. Import: `@crvouga/atlas/reports/attachment-files`
@@ -1222,8 +1425,37 @@ read when someone asks for it. Undefined when there is none.
 
 Several holders (for example a check and its layer) are summed: `attachments` also counts those on steps and
 attempts, `steps` counts only each holder's own top-level steps, tags are de-duplicated, and for a repeated
-label the later holder wins. `roles` are the attachments' roles (or, without one, what their media type or file
-name implies), sorted and distinct.
+label the later holder wins. `artifactTags` are the attachments' own normalized tags and are never inherited. `roles` are the attachments' roles (or, without one, what their media type or file
+name implies), sorted and distinct. `videos` lists every attachment whose effective media type is video, with the
+check, retry attempt or step that holds it (see {@link isVideoAttachment}).
+
+#### `summarizeLayerEvidence`
+
+```ts
+export function summarizeLayerEvidence(...holders: readonly EvidenceHolder[]): EvidenceSummary | undefined
+```
+
+Like {@link summarizeEvidence} for a layer and its parts: the same summary, but a video attached to the layer or a
+part is owned by the `layer`, not by a check.
+
+#### `isVideoAttachment`
+
+```ts
+export function isVideoAttachment(attachment: Pick<Attachment, 'name' | 'role' | 'contentType'>): boolean
+```
+
+Whether an attachment is a video, by its effective media type: the producer's `contentType`, else the one its file
+name implies. A role never decides this on its own (`demo` on a PNG is not a video), except that a `video` role
+settles a file whose type nothing says (`application/octet-stream`).
+
+#### `videoCounts`
+
+```ts
+export function videoCounts(videos: readonly VideoRef[] | undefined): VideoCounts | undefined
+```
+
+Counts references, distinct playable recordings and unplayable references. Undefined when there is no reference, so
+"no video" and "nothing known about video" look the same on the wire.
 
 #### `roleOfType`
 
@@ -1406,6 +1638,51 @@ export type StatusCounts = Readonly<Record<EvidenceStatus, number>>;
 
 How many results have each status (`passed`, `failed`, `running`, `not-run`).
 
+#### `VideoOwner`
+
+```ts
+export type VideoOwner = 'layer' | 'check' | 'attempt' | 'step';
+```
+
+Who holds a recording: the whole layer (or one of its parts), one check, one retry attempt of a check, or one step.
+
+#### `VideoRef`
+
+```ts
+export type VideoRef = {
+  /** The attachment's name, for a person. */
+  readonly name: string;
+  readonly owner: VideoOwner;
+  /** The try that holds it, when `owner` is `attempt` or the step is inside one. */
+  readonly attempt?: number;
+  /** The name of the step that holds it, when `owner` is `step`. */
+  readonly step?: string;
+  /** What identifies the bytes (digest, bundle key or address); references with the same one are the same recording. Absent when `available` is false. */
+  readonly recording?: string;
+  /** False when the reference names no bytes at all (no bundle key, address or inline text), so it can never be played. */
+  readonly available: boolean;
+};
+```
+
+One reference to a video, found by its effective media type (the producer's `contentType`, else the one the file
+name implies; a `video` role alone counts only when nothing else says what the file is). A reference is not a
+recording: the same bytes referenced from three checks are three references and one recording.
+
+#### `VideoCounts`
+
+```ts
+export type VideoCounts = {
+  /** Every reference to a video, playable or not. */
+  readonly references: number;
+  /** Distinct playable recordings: identical bytes referenced twice are one. */
+  readonly recordings: number;
+  /** References that name no bytes. A report that predates availability metadata has none of these and none of the others. */
+  readonly unavailable: number;
+};
+```
+
+Video availability as counts: references, distinct playable recordings (deduplicated), and references that cannot be played.
+
 #### `EvidenceSummary`
 
 ```ts
@@ -1418,9 +1695,13 @@ export type EvidenceSummary = {
   readonly attempts: number;
   readonly links: number;
   readonly tags: readonly string[];
+  /** The normalized tags of the attachments themselves (`#demo` is `demo`), sorted and distinct. Absent when no attachment is tagged. Unlike `tags` they are never inherited from a check or run. */
+  readonly artifactTags?: readonly string[];
   readonly labels: Readonly<Record<string, string>>;
   /** The distinct roles of its attachments (or what their media types say), to show what kind of evidence there is. */
   readonly roles: readonly string[];
+  /** Its references to videos, wherever they are held (layer, check, attempt, step). Only there when it has any. */
+  readonly videos?: readonly VideoRef[];
 };
 ```
 
@@ -7514,6 +7795,10 @@ export type TestSummary = {
   readonly outcomes: readonly TestOutcome[];
   readonly stats: TestStats;
   readonly tags: readonly string[];
+  /** The normalized tags of the attachments of its current results (`demo`, shown as `#demo`). Never inherited from a check or run; the `tags` above are. Absent in documents of older servers. */
+  readonly artifactTags?: readonly string[];
+  /** The normalized tags its attachments inherit from their check and run (those of the results that have attachments), apart from `artifactTags`. What an inherited artifact query also matches. */
+  readonly inheritedArtifactTags?: readonly string[];
   readonly labels: Readonly<Record<string, string>>;
   /** What its current results carry: attachments, steps, retries, and the kinds of attachment. */
   readonly evidence: { readonly attachments: number; readonly steps: number; readonly attempts: number; readonly roles: readonly string[] };
@@ -7604,6 +7889,8 @@ export type CatalogFacets = {
   readonly domains: readonly FacetValue[];
   readonly specs: readonly (CatalogSpec & { readonly tests: number; readonly counts: StatusCounts })[];
   readonly tags: readonly FacetValue[];
+  /** The tags of attachments, normalized. Absent in documents of older servers. */
+  readonly artifactTags?: readonly FacetValue[];
   readonly branches: readonly FacetValue[];
   readonly labels: Readonly<Record<string, readonly FacetValue[]>>;
 };
@@ -7641,6 +7928,10 @@ export type TestQuery = {
   /** Spec paths (`specs/...`). */
   readonly spec?: readonly string[];
   readonly tag?: readonly string[];
+  /** Only tests with an attachment carrying this tag (`demo` and `#demo` are the same), not counting tags inherited from a check or run: the exact artifact query. `tag` is the inherited one. */
+  readonly artifactTag?: readonly string[];
+  /** With `artifactTag`: also match the tags an attachment inherits from its check and run (a recording without a tag of its own under a run tagged `demo`). Default false: the exact query. */
+  readonly inherited?: boolean;
   /** Only tests recorded in this run (a key from `runList`). */
   readonly run?: string;
   readonly sort?: TestSort;
@@ -7715,20 +8006,39 @@ export type RunSummary = {
   readonly totalDurationMs: number | null;
   /** Up to twenty tests that failed in it. */
   readonly failing: readonly { readonly key: string; readonly title: string; readonly environment: string | null; readonly detail: string }[];
+  /**
+   * Its videos, from the run's layers and from the last result of each test: references, distinct playable recordings
+   * and references that cannot be played. Absent when it has none, and in a report that carries no video information.
+   */
+  readonly videos?: VideoCounts;
 };
 ```
 
 A run: the layers that name the same execution (`run.id`), else share a CI run URL, else a branch and commit. When,
 where, and how its tests went.
 
+#### `RunQuery`
+
+```ts
+export type RunQuery = {
+  /** Only runs that have at least one playable video recording. `total` then counts only those. */
+  readonly video?: boolean;
+};
+```
+
+What `runList` can be asked.
+
 #### `RunList`
 
 ```ts
 export type RunList = {
   readonly schemaVersion: typeof TEST_CATALOG_VERSION;
   readonly version: string;
+  /** Runs that matched, before `limit`. */
   readonly total: number;
   readonly runs: readonly RunSummary[];
+  /** How many of all runs (whatever was asked, before `limit`) have a playable video recording. */
+  readonly withVideo?: number;
 };
 ```
 
@@ -7749,6 +8059,8 @@ export type RunResult = {
   readonly at: number;
   readonly layer: string;
   readonly detail: string;
+  /** Every video its evidence references, with who holds it (check, retry attempt or step). Absent when there is none. */
+  readonly videos?: readonly VideoRef[];
 };
 ```
 
@@ -7899,13 +8211,23 @@ export function testHistory(model: CatalogModel, key: string): TestHistoryDocume
 
 One test and its recorded results, or null when the report has no test with that key.
 
+#### `hasVideo`
+
+```ts
+export function hasVideo(run: Pick<RunSummary, 'videos'>): boolean
+```
+
+Whether a run has at least one playable video recording.
+
 #### `runList`
 
 ```ts
-export function runList(history: TestHistory, version: string, limit = 100): RunList
+export function runList(history: TestHistory, version: string, limit = 100, query: RunQuery = {}): RunList
 ```
 
-Every run the history knows of, newest first, `limit` at most (default 100).
+Every run the history knows of, newest first, `limit` at most (default 100). With `query.video` only the runs that
+have a playable video recording: the filter and `total` apply to every run before `limit`, and nothing is read from
+any recording's bytes. `withVideo` always counts every run that has one.
 
 #### `runDetail`
 
@@ -7921,7 +8243,7 @@ One run with every result it recorded, or null when no run has that key.
 export function parseTestQuery(params: URLSearchParams): TestQuery
 ```
 
-Reads a `TestQuery` from URL search parameters: `q`, `sort`, `offset`, `limit`, `run`, and repeatable or comma-separated `status`, `environment`, `producer`, `domain`, `spec`, `tag`.
+Reads a `TestQuery` from URL search parameters: `q`, `sort`, `offset`, `limit`, `run`, and repeatable or comma-separated `status`, `environment`, `producer`, `domain`, `spec`, `tag`, `artifactTag`, and `inherited=1`.
 
 #### `formatMs`
 

package/docs/reference/schema.md

@@ -69,6 +69,22 @@ export const BackendInfoSchema = …
 
 A backend as the report shows it: where results came from, and whether it could be read.
 
+#### `VideoRefSchema`
+
+```ts
+export const VideoRefSchema = …
+```
+
+One reference to a video held by a layer, check, retry attempt or step, found by the attachment's effective media type.
+
+#### `VideoCountsSchema`
+
+```ts
+export const VideoCountsSchema = …
+```
+
+Video references as counts: how many are referenced, how many distinct recordings can be played, how many cannot.
+
 #### `EvidenceSummarySchema`
 
 ```ts
@@ -185,6 +201,38 @@ export const ChecksResultSchema = …
 
 `POST /api/checks` answered: the layer that was written.
 
+#### `ArtifactTargetSchema`
+
+```ts
+export const ArtifactTargetSchema = …
+```
+
+Which attachment a reviewer's tags belong to: one attachment of one check of one archived layer.
+
+#### `ArtifactTagEditSchema`
+
+```ts
+export const ArtifactTagEditSchema = …
+```
+
+The body of `POST /api/reports/artifact-tags`: tags to add to and to remove from one attachment. At least one tag overall.
+
+#### `ArtifactTagEntrySchema`
+
+```ts
+export const ArtifactTagEntrySchema = …
+```
+
+One recorded edit of an attachment's reviewer tags. Entries are never changed or removed: they are the audit trail.
+
+#### `ArtifactTagsSchema`
+
+```ts
+export const ArtifactTagsSchema = …
+```
+
+`GET /api/reports/artifact-tags`: every recorded edit, oldest first. Fold them with `foldArtifactTags`.
+
 #### `HelloEventSchema`
 
 ```ts

package/docs/rich-evidence.md

@@ -26,6 +26,7 @@ decided exactly as before ([the report contract](report-contract.md)). Evidence
 | `steps` (`parentId`, `offsetMs`, `durationMs`, `status`, `kind`) | check, attempt | Draws the check's timeline: nested steps, when each started, how long it took, which one failed. |
 | `attempts` | check | Every try of a retried check, with its own status, detail, steps and attachments. A check that passed after failing is flaky. |
 | `tags`, `labels` | check, layer | Filters and groups (`smoke`, `flaky`, an owner, a browser). |
+| `tags` | attachment | Marks one recording or screenshot, for example `demo`: shown as a `#demo` chip, and searchable. See [Tagging artifacts and demos](#tagging-artifacts-and-demos). |
 | `annotations`, `links` | check, step, attempt, layer | Notes, warnings and issue links next to the result. |
 | `specPath` | check | The spec a check belongs to (a `.feature`, a test file), relative to the repository. Checks are grouped by it. |
 | `specs[]` (`path`, `domain`, `kind`, `title`) | layer | Names each spec and its group (`domain`), so a server can group checks by spec with a title even when no [spec set](integrating.md#tell-atlas-which-spec-a-check-belongs-to) has been published. |
@@ -34,6 +35,33 @@ decided exactly as before ([the report contract](report-contract.md)). Evidence
 Send `sha`, `branch` and `runUrl` on every layer too. They never change a result, but they tie results to a commit
 and to the CI run that produced them.
 
+## Tagging artifacts and demos
+
+To mark one recording as a demo, tag the attachment itself. A tag on a check says something about the result; a tag on
+an attachment says something about that file, and no Gherkin tag, label, environment or producer name is needed:
+
+```ts
+{ name: 'checkout.webm', role: 'video', tags: ['demo'], labels: { audience: 'business' } }
+```
+
+The viewer shows it as a `#demo` chip on the artifact card. Selecting the chip filters the result's evidence to the
+attachments with that tag, and says how many match. Tags describe evidence; they never change a status or a slot.
+
+- **One spelling.** A tag is normalized before it is compared or stored: a leading `#` is dropped, letters are
+  lower-cased, each run of whitespace becomes `-`, and surrounding space is trimmed, so `demo`, `#demo` and `#Demo ` are
+  `demo`. Empty tags and tags over 64 characters are not tags and are ignored (or refused, when a reviewer enters them).
+  Everything else is a valid tag (`team/payments`, `release=2`), and repeats are shown once.
+- **Inherited.** An attachment is also searchable by the tags of its check and its run. The viewer says `inherited` on
+  such a chip, and a switch decides whether the filter counts them: a recording without a tag of its own under a run
+  tagged `demo` is found by the inherited query and not by the exact one. In the API,
+  `GET /api/reports/tests?artifactTag=demo` is exact and adding `&inherited=1` includes inherited tags.
+- **Reviewers.** After upload, a person with a publish token can add tags to an attachment (the viewer's *Add tag*
+  button) and remove the ones a reviewer added. Those tags are not written into the layer, which is immutable: the
+  server keeps them as an audit trail (who, when, which tags) and the viewer shows them as `added by <name>`, apart
+  from the producer's tags. See [Tagging artifacts](server.md#tagging-artifacts). A producer's own tags stay as uploaded.
+- **Older layers.** A layer without attachment tags reads exactly as before. Tags on an attachment that cannot be read
+  (not a list of strings) are dropped, and the attachment, check and layer stay.
+
 ## Labels describe, parameters split
 
 A result's **slot** is its producer, check id, part kind, spec, environment and **parameters**. The newest completed

package/docs/server.md

@@ -216,6 +216,26 @@ against a server unchanged. A client uploads **in dependency order**: blobs, the
 entry that makes it visible. The server checks each step and says no to a catalog entry whose manifest is not
 there (`409`), so nothing half-uploaded is ever shown.
 
+## Tagging artifacts
+
+A reviewer can mark a recording `#demo` after it was uploaded without uploading it again. The layer is immutable, so the
+tag is kept beside it: each edit is one small object under `curation/artifact-tags/` in the write backend (or the live
+store of a relay), named by time, never changed or removed. It records the attachment (layer, check, and the attachment's
+`id`, else its bytes' key, else its name), the normalized tags added and removed, the name of the token that made the
+edit, and the server's time. Nothing about the layer, its results or the report's winners changes.
+
+- `GET /api/reports/artifact-tags` (read) returns every edit, oldest first. Fold them to get the tags that stand now: the
+  last edit of a tag wins.
+- `POST /api/reports/artifact-tags` (publish, `Authorization: Bearer`) records an edit. A read token, an anonymous reader
+  and the browser's sign-in box are refused (`403`/`401`) like any upload, so a read-only visitor can see the tags and
+  not change them. The viewer asks for a token when a reviewer adds a tag and keeps it only in that tab.
+- Producer tags (`tags` on the attachment) and reviewer tags are kept apart everywhere: the viewer says who added a
+  reviewer tag and when, and a reviewer can remove only reviewer tags. `capabilities.artifactTags` on `/api/server` says
+  a server has this.
+
+See [Tagging artifacts and demos](rich-evidence.md#tagging-artifacts-and-demos) for the tag rules. Reviewer tags are
+shown in the viewer's evidence; the tests API (`artifactTag`) searches the producers' tags.
+
 ## Streaming
 
 `GET /api/events` is a server-sent-events stream:
@@ -256,7 +276,7 @@ with `format=markdown` (or `Accept: text/markdown`), and takes the project prefi
 | Only some: `q` (all words), `status` (or `flaky`), `environment`, `producer`, `domain`, `spec`, `tag`, `run`; `sort`, `offset`, `limit` | `GET /api/reports/tests?status=failed&environment=ios` |
 | One test: every recorded result (status, duration, environment, branch, commit, CI run), newest first | `GET /api/reports/tests/history?key=<key>` |
 | Why Specs, domains and counts disagree: ambiguous spec paths, shared domains, gaps, a reconciliation of the totals | `GET /api/reports/tests/health` |
-| The runs that recorded the report (by CI run URL, else branch and commit) | `GET /api/reports/runs` |
+| The runs that recorded the report (by CI run URL, else branch and commit); `?video=true` keeps those with a playable video | `GET /api/reports/runs` |
 | Every test one run recorded | `GET /api/reports/runs/detail?key=<run key>` |
 
 ```sh
@@ -330,6 +350,10 @@ curl "$ATLAS_SERVER_URL/api/projects/$ATLAS_PROJECT/reports/tests?format=markdow
 | `GET /api/projects/{project}/reports/tests/health` | read | Why specs, domains and counts disagree. |
 | `GET /api/reports/tests/history` | read | One test and every result recorded for it. |
 | `GET /api/projects/{project}/reports/tests/history` | read | One test and every result recorded for it. |
+| `GET /api/reports/artifact-tags` | read | Reviewer tags of attachments: every recorded edit. |
+| `GET /api/projects/{project}/reports/artifact-tags` | read | Reviewer tags of attachments: every recorded edit. |
+| `POST /api/reports/artifact-tags` | publish | Tag or untag one attachment after upload. |
+| `POST /api/projects/{project}/reports/artifact-tags` | publish | Tag or untag one attachment after upload. |
 | `GET /api/reports/runs` | read | The runs that recorded the report. |
 | `GET /api/projects/{project}/reports/runs` | read | The runs that recorded the report. |
 | `GET /api/reports/runs/detail` | read | Every test one run recorded. |