opencode-skills-collection 4.1.18 → 4.1.20

package/bundled-skills/talking-avatar-video/SKILL.md

@@ -11,7 +11,7 @@ author: beatra-ai
 tags: [talking-avatar, talking-head, text-to-video, mcp, paid-api, beatra]
 tools: [claude, codex, cursor, gemini]
 license: "MIT-0"
-license_source: "https://github.com/beatra-ai/talking-avatar-video-skill/blob/251c968deebb1c8f1dbfd0a8404e8e1be1528ac6/LICENSE"
+license_source: "https://github.com/beatra-ai/talking-avatar-video-skill/blob/03e427c1220ef7efcfee083b37f4f31aa98311ab/LICENSE"
 ---
 
 # Talking Avatar Video Skill
@@ -24,21 +24,20 @@ Turn one portrait and a short script into a talking avatar video, from inside Cl
 This catalog entry is a **reviewed pointer, not the executable package**. It
 contains no client code and performs no Beatra operation by itself. The package
 it points to bundles three standard-library Python scripts that make network
-calls, store a credential, and can replace their own files. Read
+calls and store a credential. It has no self-updater: it never downloads
+code and never changes its own files. Read
 [Install](#install-pinned-verified-approved-twice) and
 [Security & Safety Notes](#security--safety-notes) before activating it.
 
 | Pinned identity | Value |
 | --- | --- |
-| Package | `talking-avatar-video` `0.2.1` |
-| Archive | `https://cdn.beatra.ai/agent-packages/talking-avatar-video/v0.2.1/talking-avatar-video-skill-0.2.1.zip` |
-| Archive SHA-256 | `cb62d8e3fa65b48f3c3f1803e2008e1b9c25ff057c0a35184e8fcc7d9771eb80` |
-| Source tree | [`beatra-ai/talking-avatar-video-skill@251c968`](https://github.com/beatra-ai/talking-avatar-video-skill/tree/251c968deebb1c8f1dbfd0a8404e8e1be1528ac6/skills/talking-avatar-video) (full SHA `251c968deebb1c8f1dbfd0a8404e8e1be1528ac6`) |
+| Package | `talking-avatar-video` `0.3.0` |
+| Source commit | [`beatra-ai/talking-avatar-video-skill@03e427c`](https://github.com/beatra-ai/talking-avatar-video-skill/tree/03e427c1220ef7efcfee083b37f4f31aa98311ab/skills/talking-avatar-video) (full SHA `03e427c1220ef7efcfee083b37f4f31aa98311ab`) |
+| Package tree | `e44d57ecf111824bd4081ff26c9f6e7b4b3bd0d2` (Git tree ID of `skills/talking-avatar-video` at that commit) |
 | License | MIT No Attribution (MIT-0) |
 
-The archive holds regular files only (no symlinks, no executable bits, no
-binaries). Confirm that with the inspect commands below. Every file must be
-byte-identical to the source tree at the pinned commit.
+The pinned tree holds regular files only (no symlinks, no executable bits, no
+binaries). Confirm that with the inspect commands below.
 
 ## When to Use This Skill
 
@@ -48,72 +47,55 @@ byte-identical to the source tree at the pinned commit.
 
 ## Install (pinned, verified, approved twice)
 
-### Step 1: Download and verify into a review directory
+### Step 1: Fetch the pinned tree into a review directory
 
-Explain that this downloads an external package from `cdn.beatra.ai`, then ask
+Explain that this fetches an external package from `github.com`, then ask
 for approval. Only after approval:
 
 ```bash
 umask 077
 review_dir="$(mktemp -d)"
 cd "$review_dir" || exit 1
-curl -fsSLO "https://cdn.beatra.ai/agent-packages/talking-avatar-video/v0.2.1/talking-avatar-video-skill-0.2.1.zip"
-printf '%s  %s\n' \
-  'cb62d8e3fa65b48f3c3f1803e2008e1b9c25ff057c0a35184e8fcc7d9771eb80' \
-  'talking-avatar-video-skill-0.2.1.zip' | shasum -a 256 -c -
+git clone --quiet --filter=blob:none --no-checkout https://github.com/beatra-ai/talking-avatar-video-skill.git src
+git -C src checkout --quiet 03e427c1220ef7efcfee083b37f4f31aa98311ab -- skills/talking-avatar-video
+test "$(git -C src rev-parse '03e427c1220ef7efcfee083b37f4f31aa98311ab:skills/talking-avatar-video')" = 'e44d57ecf111824bd4081ff26c9f6e7b4b3bd0d2' && echo TREE-OK
 ```
 
-Stop if the check does not print `OK`. The expected digest comes from this
-catalog entry, not from a file on the same CDN.
+Stop if the last command does not print `TREE-OK`. The expected commit and
+tree IDs come from this catalog entry, not from the package or its website,
+and Git addresses every fetched object by its hash.
 
 ### Step 2: Inspect before activation
 
 ```bash
-unzip -l talking-avatar-video-skill-0.2.1.zip
-unzip -q talking-avatar-video-skill-0.2.1.zip
-find talking-avatar-video -type l -print            # expect no output
-find talking-avatar-video -type f -perm -111 -print # expect no output
-grep -n '"auto_update": True' talking-avatar-video/scripts/mcp_client.py
+git -C src ls-tree -r 03e427c1220ef7efcfee083b37f4f31aa98311ab -- skills/talking-avatar-video | awk '$1 != "100644"'  # expect no output
+grep -n -E 'maybe_auto_update|download_update|_apply_update' src/skills/talking-avatar-video/scripts/mcp_client.py  # expect no output
 ```
 
-Optionally confirm byte identity with the public source tree (a second,
-independent host):
-
-```bash
-git clone --quiet --filter=blob:none --no-checkout https://github.com/beatra-ai/talking-avatar-video-skill.git src
-git -C src checkout --quiet 251c968deebb1c8f1dbfd0a8404e8e1be1528ac6 -- skills/talking-avatar-video
-(cd talking-avatar-video && find . -type f | LC_ALL=C sort | xargs shasum -a 256) > archive.sha
-(cd src/skills/talking-avatar-video && find . -type f | LC_ALL=C sort | xargs shasum -a 256) > tree.sha
-cmp archive.sha tree.sha && echo IDENTICAL
-```
+The first check lists any symlink, executable, or submodule entry; the second
+finds the entry points of the self-updater that earlier versions shipped.
 
-Report to the user what the review found: `SKILL.md`, `manifest.json`, the
-bundled Markdown references, and `scripts/authorize.py`,
+Report to the user what the review found: `SKILL.md`, `manifest.json`,
+`install-source.json` (the one-line marker `{"schema_version":1,"source":"github"}`),
+the bundled Markdown references, and `scripts/authorize.py`,
 `scripts/mcp_client.py`, `scripts/uninstall.py` (Python 3.10+, standard
 library only, no dependency installation, no lifecycle hooks). Summarize the
-network, credential, local-state, telemetry, and self-update behavior listed
-under [Security & Safety Notes](#security--safety-notes).
+network, credential, local-state, telemetry, and version-notice behavior
+listed under [Security & Safety Notes](#security--safety-notes).
 
-### Step 3: Copy in and disable self-update before any other command
+### Step 3: Copy in
 
 Ask for a **second, separate** approval, because this changes agent
 configuration. Then copy the reviewed tree to the host's skills directory
-(Claude Code shown; use the equivalent path for other hosts) and immediately
-turn off silent self-update for that exact path:
+(Claude Code shown; use the equivalent path for other hosts):
 
 ```bash
 dest="$HOME/.claude/skills/talking-avatar-video"
-test ! -e "$dest" || { echo "destination exists; stop and ask the user"; exit 1; }
-cp -R talking-avatar-video "$dest"
-python3 "$dest/scripts/mcp_client.py" update --auto off
+test ! -e "$dest" && test ! -L "$dest" || { echo "destination exists; stop and ask the user"; exit 1; }
+cp -R "src/skills/talking-avatar-video" "$dest"
 ```
 
-The last command must print
-`Automatic Beatra package updates are disabled.` It writes only
-`~/.beatra/updates/<id>/state.json` and makes no network request. Run it
-before `authorize.py`, `verify`, `tools`, `upload`, or `call`: in this
-pinned version self-update is **on by default**. The setting is keyed to the
-resolved install path, so repeat it after moving or re-copying the directory.
+There is no update switch to turn off in this version.
 
 ### Step 4: Authorize as its own decision
 
@@ -156,16 +138,17 @@ arguments; never submit a replacement while the task is running.
 
 ## Update
 
-This entry does not endorse the package's silent self-update. Keep
-`update --auto off` in place and do not run `update --auto on` or a bare
-`update` without explicit approval.
+This pinned version cannot update itself: it has no code that downloads or
+replaces package files. `update` only reports what the store or tool that
+installed the copy offers; for a copy installed by the steps above it finds
+no such record and says to update the way you installed it. See the version
+notice under [Security & Safety Notes](#security--safety-notes).
 
-To move to a newer version, repeat Steps 1 to 3 for that version in a new
-review directory, verify its digest against the matching tree in `beatra-ai/talking-avatar-video-skill`
-(a version not listed in this entry has not been reviewed here), show the
-user the file-level changes against the installed copy, and replace the
-directory only after approval. `update --check` reports the available version
-from `beatra.ai` without changing files.
+To move to a newer version, repeat Steps 1 to 3 for that commit in a new
+review directory, show the user the file-level changes against the installed
+copy (for example `git -C src diff --stat 03e427c <new-commit> -- skills/talking-avatar-video`),
+and replace the directory only after approval. A version not listed in this
+entry has not been reviewed here.
 
 ## Uninstall
 
@@ -177,21 +160,25 @@ python3 "$dest/scripts/uninstall.py"
 
 Read the JSON decision. `disconnected` means this was the last Beatra skill on
 the device: the token was revoked (when `revoked` is `true`) and the files
-`credentials.json`, `installation.json`, `host.json`, `skills.json`, and
-`registrations.json` under `~/.beatra` were removed. `keep_connection` means
-another Beatra skill still uses the shared token, which stays. Then, after
-confirming the path with the user, delete `$dest`.
+`credentials.json`, `installation.json`, `host.json`, `skills.json`,
+`network.json`, `balance-holds.json`, `pending_authorization.json`, and
+`.authorize.lock` under `~/.beatra` were removed. `keep_connection` means
+another Beatra skill still uses the shared token, which stays.
+`revoke_retry` means the server refused the revocation and nothing changed;
+run it again shortly. The script never deletes the package directory: after
+confirming the path it prints with the user, delete `$dest`.
 
 `uninstall.py` does not remove `~/.beatra/updates/`. When the decision is
 `disconnected` and no other Beatra skill is installed, remove that directory
-too; otherwise leave it. A token that could not be revoked expires after 15
-days idle and can be revoked at once in the Beatra Console under Agents.
+and then the empty `~/.beatra`; otherwise leave them. A token that could not
+be revoked expires after 15 days idle and can be revoked at once in the
+Beatra Console under Agents.
 
 ## Best Practices
 
 - ✅ Keep one approval per paid call, per upload set, and per install step.
 - ✅ Report net charged credits from the terminal task, not the estimate.
-- ❌ Do not re-enable self-update or install an unreviewed version silently.
+- ❌ Do not replace the installed copy with an unreviewed version silently.
 - ❌ Do not print, paste, or move the token out of `~/.beatra/credentials.json`.
 - ❌ Do not retry a paid call with a new request ID after an uncertain response.
 
@@ -202,27 +189,42 @@ days idle and can be revoked at once in the Beatra Console under Agents.
   upstream model providers and can change; the service is provided as is.
 - Outputs are probabilistic, not guaranteed unique or non-infringing, and need
   human review before publication.
-- This catalog entry reviews only the pinned archive above. A newer version is
+- This catalog entry reviews only the pinned tree above. A newer version is
   a different review.
 
 ## Security & Safety Notes
 
 `risk: critical` is deliberate.
 
-- **Network.** Authorization uses `api.beatra.ai`; every tool call and upload
-  goes to `mcp.beatra.ai`. With self-update left on, the client also fetches
-  `https://beatra.ai/skills/talking-avatar-video/install.json` and archives from
-  `cdn.beatra.ai`.
-- **Self-update (on by default in this pinned version).** Before `verify`,
-  `tools`, `upload`, or `call`, the client checks for a newer release at most
-  once every 24 hours and, if one exists, replaces package-owned files without
-  per-update preview or approval. It pins host and path, verifies checksums
-  from Beatra's own discovery document and CDN, and rolls back on failure, but
-  those digests are not independently anchored. This entry therefore requires
-  `update --auto off` before first use, as in Step 3.
+- **Network.** Every request is HTTPS and refuses redirects. Authorization
+  uses `api.beatra.ai` and tool calls go to `mcp.beatra.ai`; an upload is a
+  `PUT` of the approved file to the HTTPS address the server returns, without
+  the bearer token. Unless a cached decision is still valid (10 minutes to 7
+  days), each run first asks `https://api.beatra.ai/skill-route`, and also
+  `https://api.beatra.cn/skill-route` when the first is slow or answers `cn`,
+  which network to use. These probes carry no credential or package identity.
+  When the answer is `cn`, authorization and tool calls go to `api.beatra.cn`
+  and `mcp.beatra.cn` with the same bearer token, and the version notice
+  reads from `www.beatra.cn`; Beatra serves these `.cn` hosts from mainland
+  China.
+  `python3 "$dest/scripts/mcp_client.py" network --use ai` pins the `.ai`
+  hosts and stops the probes; a failed version-notice read can still retry
+  once on the other network.
+- **Version notice, no self-update.** This version has no code that downloads
+  or replaces package files and writes nothing inside the install directory.
+  Before `verify`, `tools`, `upload`, or `call`, at most once every 24 hours
+  per install path, it records the check time and looks, read-only, for
+  records another installer left beside the package (ClawHub `origin.json`,
+  SkillHub or `skills` CLI lock entries, `gh skill` frontmatter). A copy
+  installed by the steps above normally has none and makes no request. When
+  one is found, it reads `https://beatra.ai/skills/talking-avatar-video/sources.json`
+  (no credential, 3-second timeout, 64 KiB cap) and, if that installer offers a
+  newer version, prints one line to stderr with the installer's own update
+  command. It never runs the command.
 - **Uploads and third parties.** Prompts and uploaded media are sent to Beatra
   and forwarded to the third-party model provider executing the task. Beatra
-  is hosted outside mainland China. See the
+  runs the service outside mainland China; on the `cn` route (see Network)
+  requests reach it through Beatra's hosts in mainland China. See the
   [privacy policy](https://beatra.ai/en/privacy).
 - **Likeness and reference media.** Uploaded portraits or reference clips are sent to Beatra and the model provider. Require approval for that exact file set.
 - **Billing.** Paid tools consume prepaid credits. Credits for tasks that fail
@@ -230,20 +232,37 @@ days idle and can be revoked at once in the Beatra Console under Agents.
   automatically; otherwise purchases are non-refundable, and actual usage can
   exceed the estimate and leave a negative balance. See the
   [terms](https://beatra.ai/en/terms).
-- **Credentials.** `authorize.py` runs an OAuth device flow, opens the browser,
-  and stores one bearer token in `~/.beatra/credentials.json` (directory
-  `0700`, file `0600`). The token never goes into argv, environment variables,
-  or output. It carries full Beatra scope, including `wallet:spend`, has a
-  sliding 15-day idle lifetime, and is shared by every Beatra skill on the
-  device.
+- **Credentials.** `authorize.py` runs an OAuth device flow, opens the browser
+  on the approval page, and stores one bearer token in
+  `~/.beatra/credentials.json` (directory `0700`, file `0600`). The token never
+  goes into argv, environment variables, or output. It carries full Beatra
+  scope, including `wallet:spend`, has a sliding 15-day idle lifetime, and is
+  shared by every Beatra skill on the device. While the user has not yet
+  selected Allow, the pending device code is kept in
+  `~/.beatra/pending_authorization.json` (`0600`) so a rerun finishes the same
+  approval instead of opening a new one. When `verify`, `tools`, `upload`, or
+  `call` finds no working token, the client makes one check of that saved
+  approval and stores the token if the user has already selected Allow; it
+  never starts a new authorization or opens a browser.
 - **Local state.** `~/.beatra/` also holds `installation.json` (random
   installation reference), `host.json` (agent platform and hostname),
-  `skills.json` (installed Beatra skill paths), `registrations.json`, and
-  `updates/<id>/state.json` plus update backups when updates run.
-- **Telemetry.** The device flow sends the hostname as the device name, the
-  package slug and version, and the detected agent platform (for example
-  `claude-code`, from environment variables). On first use the client makes a
-  non-billable `beatra.installations.register` call, and every tool call adds
+  `skills.json` (installed Beatra skill paths), `network.json` (route
+  decision, with a country code when the route answer includes one),
+  `balance-holds.json` (after an insufficient-credit refusal, that tool is
+  answered locally for up to 30 minutes; `call --recheck-balance` sends one
+  call), a short-lived `.authorize.lock`, and, per install path,
+  `updates/<id>/state.json` (last version check), `source.json` (install
+  source), and `registration.json` (last registration). Files are `0600`
+  except `host.json`, which follows the umask.
+- **Telemetry.** Authorization sends the hostname as the device name, the
+  package slug and version, the detected agent platform (for example
+  `claude-code`, from environment variables), and the installation reference.
+  After connecting, at most once a day unless the version, platform, route, or
+  install source changes, the client makes a non-billable
+  `beatra.installations.register` call with those package and platform
+  fields, the release channel, the network route, the install source
+  (`github` for this tree), and coarse runtime facts: OS and OS version, CPU
+  architecture, Python version, locale, and UTC offset. Every tool call adds
   `source_package_slug` and `source_platform`. There is no opt-out for these
   fields.
 - **Retention.** Account data is kept for the life of the account. Task
@@ -255,6 +274,6 @@ days idle and can be revoked at once in the Beatra Console under Agents.
 
 ## Additional Resources
 
-- [Source tree at the pinned commit](https://github.com/beatra-ai/talking-avatar-video-skill/tree/251c968deebb1c8f1dbfd0a8404e8e1be1528ac6/skills/talking-avatar-video)
+- [Source tree at the pinned commit](https://github.com/beatra-ai/talking-avatar-video-skill/tree/03e427c1220ef7efcfee083b37f4f31aa98311ab/skills/talking-avatar-video)
 - [Product page](https://beatra.ai/skills/talking-avatar-video)
 - [Terms](https://beatra.ai/en/terms) and [privacy policy](https://beatra.ai/en/privacy)

package/bundled-skills/uiverify-triage-visual-changes/SKILL.md

@@ -0,0 +1,304 @@
+---
+name: uiverify-triage-visual-changes
+description: "Triage a UI Verify visual regression build from your coding agent over MCP: sort changed screenshots into regressions, intended changes and noise, then accept baselines."
+category: testing
+risk: critical
+source: "https://github.com/uiverify/uiverify/tree/main/packages/skills/skills/triage-visual-changes"
+source_repo: uiverify/uiverify
+source_type: official
+date_added: "2026-10-19"
+author: igrlk
+tags: [visual-testing, visual-regression, screenshot-testing, mcp, storybook, playwright, vitest]
+tools: [claude-code, codex, cursor, gemini]
+license: "MIT"
+license_source: "https://github.com/uiverify/uiverify/blob/main/LICENSE"
+---
+
+# Triage a UI Verify build from your agent
+
+When a build comes back **changed**, the dashboard shows a triptych per story (baseline / candidate /
+diff). This skill does that review from your agent over the **UI Verify MCP** — read what changed, look
+at the pixels when a number is ambiguous, then summarize or accept.
+
+## When to Use This Skill
+
+- Use when a UI Verify build reports changed or failed stories and the user wants the agent to review them instead of the dashboard.
+- Use when the user asks to triage a build, summarize the visual regressions for a PR comment, or accept the new baselines.
+- Use when the user wants the before-and-after of a pull request's UI changes, or to reply to or resolve a reviewer's comment on a diff.
+- Requires a UI Verify project that uploads builds from CI, and the UI Verify MCP server connected in the agent.
+
+## Connect the MCP (once)
+
+The server is a remote Streamable-HTTP MCP at `https://uiverify.ai/mcp`. You log in once with your UI
+Verify account in the browser (OAuth), and that one connection reaches every project in every team you
+are a member of, so there is no per-project setup and no API key in the config. **Add it as a real MCP
+server in your agent — don't hand-roll `curl` against the endpoint.** Over raw `curl` the image tools come
+back as MCP image blocks a shell can't render, so the pixels are useless to a script; a native client shows
+them to the model directly.
+
+**Claude Code** — run in the project root:
+```sh
+claude mcp add --scope project --transport http uiverify https://uiverify.ai/mcp
+```
+
+Then restart Claude Code, run `/mcp`, pick `uiverify`, and log in. `--scope project` writes the server to
+the committed `.mcp.json`; it holds no secret, so the whole team gets it and each teammate logs in with
+their own account.
+
+**Cursor** — add to `.cursor/mcp.json` (commit it to share), then log in from Cursor's MCP settings:
+```json
+{
+  "mcpServers": {
+    "uiverify": { "url": "https://uiverify.ai/mcp" }
+  }
+}
+```
+
+Any other MCP client (VS Code, Codex, Copilot, Gemini): point it at the same Streamable-HTTP URL and it
+asks you to log in. Restart the agent session after adding the server so the tools load. If a client can
+only reach it over HTTP by hand, prefer the `get_diff` tool (it returns downloadable image **URLs**) over
+`render_diff_image` (inline pixels) — see the tool table below.
+
+Tools it exposes:
+
+| Tool | Does | Key args |
+|---|---|---|
+| `list_projects` | Every project you can access, with its `projectId`, team, name, type, repo, and last build time. Only needed when you can access several projects: a `commitSha` / `prNumber` lookup and `list_builds` then take a `projectId` (with one project it is used automatically, and a call that's ambiguous returns an error listing them) | none |
+| `list_builds` | Recent builds + gate status, to find the one to inspect | `projectId?`, `branch?`, `status?`, `limit?` |
+| `get_build` | Lean triage of one build — the gate + `counts {total, changed, failed, unchanged}`, a build-wide `comments {total, unresolved}` review-comment tally, the AI tally, and the **first page (25)** of changed/failed stories (each with a `diffResultId`, diff %, and when AI review is on the judge's `aiVerdict`, `aiConfidence`, and for a regression `aiFlagReason` = its one-line "what looks unintended"), the page carrying a `nextCursor`. It does **not** dump the unchanged list — `counts.unchanged` is the signpost; page the rest with `list_build_stories`. `comments.unresolved > 0` means a human/agent left an open note — read it with `list_comments` before you accept | one of `commitSha` / `prNumber` / `buildId` |
+| `list_build_stories` | Page through one build's stories by status — the only way to browse the full changed / failed / **unchanged** set beyond `get_build`'s first page. `counts.unchanged` from `get_build` is the exact count it pages. Every changed-story row (here and in `get_build`) carries its own `comments {total, unresolved}` | selector, `status: changed \| unchanged \| failed`, `cursor?`, `limit?` (default 25, max 100) |
+| `get_diff` | Per-story diff metrics + **presigned image URLs** (baseline / candidate / diff) you can download to a file or link straight into a PR; when AI review is on, the judge's full call: `aiVerdict`, `aiConfidence`, `aiSummary` (what changed), `aiReasoning` (why), `aiFlagReason`; and a per-story `comments {total, unresolved}` (same signpost as `get_build`, scoped to the one story). Pass `storyId` to pull one story **even if it didn't change** — you get its current baseline URL, so you can show "identical to baseline" on a passed build | same selector, optional `storyId` |
+| `render_diff_image` | The actual **pixels** of one image, inline for the vision model to look at (not a URL): `baseline` / `candidate` / `diff`, or `before_after` for a before-and-after crop zoomed to the changed region — one crop per region, stacked, when the story moved in several far-apart places (a header and a footer). When the story has an unresolved review comment, a text note saying so comes **before** the image | `diffResultId` (or `storyId` for a story that didn't change), `which` |
+| `get_pr_changeset` | The **cumulative** "This PR vs base" changeset: what the *whole pull request* did to the UI vs the branch it merges into — `new` / `changed` / `removed` stories, each with review status (and the judge's verdict when AI review is on), plus `counts {new, changed, removed, unchanged}` and the **first page (25)** of each list. **Distinct from `get_build`**, which is one commit's gate: this survives in-PR accepts **and** merge, and catches an added-then-accepted story and a **removed** one that no single build's diff can see | one of `commitSha` / `prNumber` / `buildId` |
+| `list_pr_stories` | Page one bucket of the PR-vs-base changeset beyond `get_pr_changeset`'s first page | selector, `kind: new \| changed \| removed`, `cursor?`, `limit?` |
+| `review_diff` | Record a decision on one story. `accept` and `ignore` are **refused** while the story has an unresolved review comment; `deny` always works | `diffResultId`, `decision: accept \| deny \| ignore` |
+| `accept_build` | Accept **every** changed story in a build at once. **Refused, accepting nothing,** while any changed story has an unresolved review comment — the error names those stories | same selector |
+| `list_comments` | Read the review comments a designer/QA (or another agent) left on a build's diffs — every live comment across the build, each carrying its `diffResultId`, `authorType`, `body`, `side`, `parentId` (a reply's thread root), `anchor` (a point/region on the image), and `resolved`. This is the thing `get_build`/`get_diff`'s `comments` count points you to | one of `commitSha` / `prNumber` / `buildId` |
+| `post_comment` | Leave a comment (or a threaded reply) on one story's diff — e.g. reply to a reviewer's question, or flag a regression back to them. Authored as the **agent**; a new root comment is refused if a newer build exists on the branch (comment on the latest), but replies are always allowed | selector + `diffResultId`, `body`, `side?`, `anchor?`, `parentId?` (reply to a root's id) |
+| `resolve_comment` | Resolve (or reopen) a comment thread once its note is addressed | `commentId` (thread root), `resolved` |
+| `update_comment` / `delete_comment` | Edit or remove a comment — the agent may only touch **agent-authored** comments | `commentId` (+ `body` for update) |
+
+The comment tools (`list_comments` and the writes) are behind the team's image-comments feature; if they
+are not exposed on your MCP connection, your team does not have it enabled, and `get_build`/`get_diff`
+will simply report `comments {total: 0, unresolved: 0}`.
+
+## Recipe 1 — "Triage this build"
+
+Bucket the changes so the human sees signal, not 60 rows. Call `get_build` for the PR — it carries the
+AI judge's call per story (`aiVerdict`, and for a regression the `aiFlagReason`) for the **first page** of
+changes; if `counts.changed` is larger than that page, keep paging `list_build_stories { status:
+"changed" }` on the `nextCursor` until it runs out, so no regression slips past the page boundary. **Read the judge before
+you form your own view, and for anything that actually changed content, adjudicate it against the
+before image, not in isolation:**
+
+- **Render BOTH images, not just the diff.** `render_diff_image` `which: "baseline"` **and**
+  `which: "candidate"` and compare them. The green diff mask tells you *where* pixels moved, never
+  *whether the result is good* — a code block that went dark-on-dark, text that lost contrast, a
+  control that's now clipped all look like "some pixels changed" in the mask and only reveal
+  themselves as regressions in the before/after. Judging the candidate alone is how "it has colours
+  now → improvement" passes an illegible block. Pull `get_diff` for the judge's `aiReasoning` /
+  `aiFlagReason` on the ones it flagged.
+
+- **Read the human's comments before you decide.** If `get_build`'s `comments.unresolved > 0` (or a
+  `get_diff` story shows `comments`), a designer/QA or another agent has left a note on this build —
+  `list_comments` reads them, each tied to its `diffResultId` so you can match a note to the story in your
+  buckets. A comment is context the pixels don't carry ("this spacing is intentional, don't revert it" /
+  "the logo is wrong here"), so read it before you bucket the story. You can't accept over one anyway:
+  `accept_build` and `review_diff` accept/ignore refuse a story with an **unresolved** comment. The loop is
+  read the note → do what it asks (often a code change and a new push) → `resolve_comment` → accept.
+  Never resolve a note just to unblock the accept; resolve it because you addressed it.
+
+Report in four buckets, with real story names and % deltas:
+
+1. **Regression — a real change that's wrong** — content changed and the after is broken or worse:
+   illegible/low-contrast text, clipping, overlap, missing content, a control that stopped reading as
+   itself. **A regression the current PR *caused* is still a regression** — "my diff explains it"
+   says nothing about whether it's correct. Never accept these; they're the reason to triage.
+2. **Intended change** — content changed and the after is correct and matches the PR's stated intent
+   (a deliberate restyle, new copy, a genuinely new story). These still want a human eye, but they're
+   accept candidates.
+3. **Cosmetic reflow** — real diff pixels, but the diff image shows the *same* content shifted a few px
+   (a row moved down ~5px, text ghosted lower). Not a content change.
+4. **Rendering noise — safe to accept** — sub-0.4% jitter on chart edges / anti-aliased lines. Pure
+   render jitter.
+
+**The judge's `regression` verdict is a reason to look harder, never to dismiss.** If you're about to
+call a story the judge flagged "intended anyway", you need a concrete reason from the before/after that
+refutes its `aiFlagReason` — not "it's a colour change, probably fine." When you can't refute it, trust
+it.
+
+Example output shape:
+> **67 changed stories → buckets.**
+> **⚠️ Regressions (2)** — real changes that look wrong, do NOT accept: `SetupWizard/Playwright` (8.3%,
+> code block now dark-on-dark / illegible — judge flagged `regression`), `Card/Compact` (5.1%, title
+> clipped) …
+> **1. Intended changes (11)** — content changed, looks correct, accept candidates: `Hero/Default` (14%,
+> new headline copy), …
+> **2. Cosmetic reflow (9)** — real pixels, vertical shift only: `EventStatusCard/All Variants` (4.1%,
+> rows shifted ~5px), `TestingInit/Playground` (3.7%), …
+> **3. Chart anti-aliasing noise (6)** — sub-0.4% edge jitter, safe to accept: `FunnelChart/Smaller
+> Screen` (3.2%), `UpliftChart` (single 1px mark), …
+> **New stories (12)** — first baseline, nothing to compare: `Button/AllVariants`, …
+
+Never accept from inside the triage step — surface the buckets and let the human decide, or do it
+explicitly in recipe 3.
+
+## Recipe 2 — "Summarize the visual regressions"
+
+Same read, but output the changes that need a human — the ⚠️ regressions first, then the intended
+content changes — in a PR-comment shape, one line each, no reflow/noise. This is the comment to drop on
+the PR:
+
+> 🔎 **Visual review — 1 regression, 2 intended** (of 67 flagged; 64 reflow/noise, listed below the fold)
+> - ⚠️ `SetupWizard/Playwright` — code block dark-on-dark, illegible (8.3%, judge: regression)
+> - `Pricing/Card` — CTA button color changed blue→green (12.4%)
+> - `Nav/Header` — logo 8px larger (3.1%)
+
+## Recipe 3 — "Accept all the new baselines"
+
+When the changes are all intended (a deliberate restyle) or all noise **and you've confirmed no
+regression is hiding in the list** (bucket ⚠️ empty), advance every changed story's baseline in one call:
+
+```
+accept_build { prNumber: 123 }
+```
+
+Don't let "the headline change is intended" halo onto the whole build — a global CSS or theme change
+sweeps into stories the PR never meant to touch, and "the PR caused it" is not "the PR intended it."
+Each changed story earns its bucket on its own before-and-after.
+
+For a targeted accept (some real, some not), loop `review_diff` per `diffResultId` with
+`accept` / `ignore` / `deny` instead — accept the intended ones, ignore the noise, leave real
+regressions for a human.
+
+## Recipe 4 — "Put the before/after in the PR"
+
+Keep the human in the PR instead of sending them to the dashboard. After you've triaged, post the
+changed stories inline:
+
+- **The fastest single image:** `render_diff_image` `which: "before_after"` gives you one PNG, before and
+  after side by side, cropped to the changed region (one crop per region, stacked, if the story moved in
+  several far-apart places) — the least to eyeball. Save it and attach it.
+- **Downloadable files / durable links:** `get_diff` returns presigned `baselineUrl` / `candidateUrl` /
+  `diffUrl`. Download them (`curl -L "$url" -o before.png`) to attach to the PR, or drop the build link
+  and the URLs into a comment. Always include the build link (`https://uiverify.ai/builds/<id>`) so the
+  reviewer can open the full triptych.
+
+A good PR comment: the one-line-per-regression summary from Recipe 2, the before/after image for the
+regressions, and the build link. Post it, don't make them go looking.
+
+## Recipe 5 — "What did this whole PR do to the UI?"
+
+`get_build` answers one commit — *is anything unreviewed on this build*. It does **not** prove the
+**whole PR** did what you intended, and it's blind to two things by construction: a story you **added and
+accepted earlier in the PR** (the latest build renders it clean, so it never shows as changed) and a
+**removed** story (a deleted or renamed baseline — no build renders it, so no per-build diff flags it).
+`get_pr_changeset` is the only surface that catches both, so run it before you call a PR done.
+
+Pull it for the PR and read the whole head-vs-base picture:
+
+```
+get_pr_changeset { prNumber: 123 }                  → new / changed / removed vs the base branch
+list_pr_stories  { prNumber: 123, kind: "removed" } → page any one bucket
+```
+
+Hold every entry to one bar: **can you attribute it to something this PR's diff actually did?**
+
+- **Yes, and it's correct** → the intended visual impact of the PR.
+- **A change you can't attribute to your own diff** → stop. Don't accept it, don't dismiss it as flake,
+  don't "re-run and see." Say so and flag it for a human — the likely cause is a baseline that moved when
+  it shouldn't have, which is silent by construction.
+- **A `removed` story you didn't intend** → an accidental deletion (or an unintended rename, which reads
+  as a remove plus an add). Flag it loudly; don't let a green check ship it.
+
+The changeset is GA — no flag to enable, and on a **public** project anyone can read it for a build
+without logging in.
+
+## Recipe 6 — "Answer or resolve a review comment"
+
+When a reviewer's note is a question you can answer, or points at something you just fixed, close the loop
+from the agent instead of making them chase you. Read the thread with `list_comments`, then:
+
+- **Reply in the thread** — `post_comment { diffResultId, body, parentId }` where `parentId` is the root
+  comment's `id` (a reply inherits the root's side and needs no anchor of its own). Use it to answer
+  "why did this move?" with the diff you made, or to confirm "fixed in the next push."
+- **Flag a regression back** — `post_comment { diffResultId, body, anchor? }` as a new root, to point the
+  reviewer at a story you're leaving for them (pair it with the ⚠️ bucket from Recipe 1).
+- **Resolve** — `resolve_comment { commentId, resolved: true }` once the note is addressed (you made the
+  change it asked for, or answered the question). Resolve **before** you accept: an open thread makes
+  `accept_build` / `review_diff` refuse that story. Only reach for this when the thread is genuinely done;
+  the open comment is the signal that stops a premature accept.
+
+Your key authors comments as the **agent**, and can only edit/delete comments it authored — never touch a
+human's comment.
+
+## Passed build? You can still show the pixels
+
+A build with no changes shows no triptych — but the components still rendered, and "nothing changed" is
+only trustworthy if you can see it. **Enumerate the unchanged set** with `list_build_stories { status:
+"unchanged" }` (page it on the returned `nextCursor`), then pull any story's current image by id:
+`get_diff { buildId, storyId }` for its baseline URL, or `render_diff_image { storyId, which: "baseline" }`
+for the pixels. Use it to
+confirm a component looks right on a green build, or to hand the reviewer "here it is, identical to
+baseline" without opening the dashboard.
+
+## Guardrails
+
+- **Read before you write.** Always `get_build` (and `render_diff_image` for anything ambiguous) before
+  `review_diff` / `accept_build`. Don't accept a build you haven't looked at.
+- **Compare before-and-after, never the after alone.** For any story that changed content, render
+  `which: "baseline"` AND `which: "candidate"` and look at both — the diff mask shows where, the pair
+  shows whether it got worse (contrast/legibility, clipping, layout). "It has colours / it moved" is not
+  "it's better."
+- **The AI judge's `regression` is a signal to trust by default.** Overriding it needs a concrete reason
+  from the before/after that refutes its `aiFlagReason`, not a hand-wave. Attributable-to-this-PR is not
+  a reason to dismiss it.
+- **Bulk-accept is a baseline change.** `accept_build` makes the candidate the new truth for every
+  changed story — only reach for it when you've confirmed there's no real regression hiding in the list.
+- **An unresolved comment blocks the accept.** `get_build`'s `comments.unresolved > 0` means a human left
+  a note you haven't read — `list_comments` it and honor it before `review_diff` / `accept_build`. A
+  reviewer commenting "don't accept this" that an agent bulk-accepts anyway is exactly the failure this
+  count exists to prevent.
+- **Distinguish "new story" from "changed story."** A first-baseline story has nothing to diff; it's not
+  a regression, just needs a baseline. Bucket it separately.
+
+## Examples
+
+### Example 1: Triage the build for a pull request
+
+The user says: "Triage the UI Verify build for PR 123."
+
+```
+get_build { prNumber: 123 }
+render_diff_image { diffResultId: "<diffResultId from get_build>", which: "before_after" }
+```
+
+Bucket each changed story as a regression, cosmetic reflow or rendering noise from its before-and-after, then report the regressions by story name.
+
+### Example 2: Accept the intended changes
+
+The user says: "Those all come from the new button style, accept them."
+
+```
+accept_build { prNumber: 123 }
+```
+
+Only after every changed story was looked at and none is a regression. For a mixed build, call `review_diff { diffResultId: "<id>", decision: "accept" }` for each intended story instead.
+
+## Limitations
+
+- Needs a UI Verify account and a project whose CI uploads builds with the `uiverify` CLI (Storybook, Playwright or Vitest); with no build there is nothing to triage.
+- Needs network access to the hosted MCP server at `https://uiverify.ai/mcp` and a one-time browser login, which the agent cannot complete on its own.
+- AI verdict fields appear only when AI review is on for the project, and the comment tools only when the team has image comments enabled.
+- Over raw HTTP the image tools return MCP image blocks a shell cannot show; use a native MCP client, or `get_diff` for image URLs.
+
+## Security & Safety Notes
+
+- `review_diff` (accept) and `accept_build` change the project's baselines on the service, and later builds are compared against them. Look at the before and after first, and never bulk-accept a build that may hide a regression.
+- The server refuses accept and ignore while a story has an unresolved review comment; read it with `list_comments` and honour it.
+- `get_diff` returns presigned image URLs that work for anyone holding them until they expire. Share them only where the team would share the screenshot.
+- Each person connects with their own OAuth login; there is no API key in `.mcp.json`.
+
+## Catalog adaptation
+
+Copied from the official MIT source above at commit `181d9e4` with its instructions unchanged; this catalog adds When to Use This Skill, Examples, Limitations and Security & Safety Notes.