# Screenery

> Screenery is a registry for product screenshots. CI pushes screenshots on
> every build, and each one gets a stable URL:
> https://cdn.screenery.dev/{org}/{project}/{asset}@latest.png. A push to the
> default branch changes the image behind every README, docs page or help
> centre that embeds it. The same push can fail the job on a visual regression
> against a baseline. On a pull request it posts a comment that shows what
> changed, and a reviewer or an agent approves or rejects each changed
> screenshot; a required GitHub check can block the merge until every change
> is approved. An MCP server lets AI agents set this up and compare a pull
> request's screenshots with @latest.

This file indexes www.screenery.dev, the documentation for people. The agent
guide is on app.screenery.dev, the console's origin. The Agents section below
links it. The docs pages are plain HTML and need no JavaScript to read.

Every page on www is also available as Markdown. Send `Accept: text/markdown`
to the page's URL, or add `.md` to it: https://www.screenery.dev/docs/action.md.
For `/` and the index pages that end in `/`, add `index.md`.

## Docs

- [Docs index](https://www.screenery.dev/docs/): every page below, grouped by topic
- [Getting started](https://www.screenery.dev/docs/getting-started): choose a setup path, push from CI, and embed one @latest URL in a README
- [GitHub Action](https://www.screenery.dev/docs/action): reference for screenery/push@v1, its permissions, inputs, outputs, fork pull requests and pinning
- [Screenshot URLs](https://www.screenery.dev/docs/urls): the URL grammar, formats, caching, visibility levels, signed URLs, read tokens and embedding
- [How @latest moves](https://www.screenery.dev/docs/latest): channels, which builds move @latest, wilting alerts for screenshots no build pushes any more, promoting by hand, and which CI jobs may move the default branch
- [Promotion rules](https://www.screenery.dev/docs/rules): the default release and pull-request rules, tag prefixes for monorepos, the rule log, pruning, rollback and channel mode
- [Chat notifications](https://www.screenery.dev/docs/notifications): post to Slack, Discord or Microsoft Teams when a build changes screenshots or a channel is reviewed; chat targets, conditions, Send a test, and why only public screenshots get a picture
- [Visual testing](https://www.screenery.dev/docs/visual-testing): the optional diff gate that compares each screenshot with a committed baseline and fails the job on a regression without pushing
- [Sharded test runs](https://www.screenery.dev/docs/sharding): split a test run across machines with `--shard 2/4`; each shard stores its screenshots and one combined build moves the channels once every shard is in
- [Pull-request comments](https://www.screenery.dev/docs/pr-comments): the preview comment on pull requests, possibly flaky screenshots, the gallery and README Markdown each push writes, and verify-publish receipts
- [Reviewing screenshots](https://www.screenery.dev/docs/review): approve or reject each changed screenshot of a pull request in the console or from an agent; the review state, carry-over, and why approving moves no channel
- [Playwright and Argos](https://www.screenery.dev/docs/playwright): publish Playwright toHaveScreenshot goldens or an Argos upload folder as they are
- [Cypress](https://www.screenery.dev/docs/cypress): name each cy.screenshot(), keep failure screenshots out, and publish the rest
- [Vitest browser mode](https://www.screenery.dev/docs/vitest): keep toMatchScreenshot as the gate and publish its references from one folder
- [Storybook](https://www.screenery.dev/docs/storybook): capture every story with a short Playwright script and publish the PNGs
- [CLI reference](https://www.screenery.dev/docs/cli): every command of the screenery CLI, with flags, exit codes and environment variables
- [Credentials](https://www.screenery.dev/docs/credentials): GitHub OIDC with no stored secret, SCREENERY_TOKEN, read and embed tokens, screenery login, and which credential each command uses
- [Docs plugins](https://www.screenery.dev/docs/docs-plugins): remark-screenery for Docusaurus and other remark pipelines, and starlight-screenery for Astro Starlight, turn `![Alt](screenery:home)` into the @latest CDN URL at build time
- [AI agents](https://www.screenery.dev/docs/agents): connect a coding agent over MCP, locally or through the hosted server, install the plugin, and let the agent set up a repository
- [Clips, evals and demos](https://www.screenery.dev/docs/clip-eval): capture live pages onto @clip, publish LLM UI evals onto @eval, and publish demo GIFs and videos
- [Monitoring live pages](https://www.screenery.dev/docs/monitoring): clip your live site on a schedule, compare each capture with the version you approved, get a chat message or an asset.changed webhook when it drifts, and approve drift by promoting it

## Agents

- [Agent guide index](https://app.screenery.dev/llms.txt): MCP install commands for Claude Code, Codex, Cursor, VS Code and other hosts, plus the hosted endpoint
- [Full agent guide](https://app.screenery.dev/llms-full.txt): onboarding by hand, the URL grammar, the MCP server's runbook and the MCP matrix, in one Markdown file
- [Hosted MCP server](https://app.screenery.dev/mcp): the remote MCP endpoint. A person approves the agent once, in the console
- [auth.md](https://app.screenery.dev/auth.md): how an agent gets credentials. Every flow ends with a signed-in person approving it
- [Skills](https://app.screenery.dev/skills.txt): Markdown skills for Screenery jobs, each one a file an agent fetches and writes to .claude/skills/
- [Plugin](https://github.com/screenery/agents): the hosted MCP server and every skill in one install for Claude Code, Codex and Cursor

## Guides

- [Guides index](https://www.screenery.dev/guides/): every guide below, grouped by topic
- [Keep documentation screenshots up to date](https://www.screenery.dev/guides/keep-docs-screenshots-up-to-date): four ways to stop docs screenshots going stale, and how to take them from tests in CI
- [Screenshot automation for docs and READMEs](https://www.screenery.dev/guides/screenshot-automation): desktop apps, URL screenshot APIs and tests in CI compared, then a Playwright example that signs in, captures named screenshots and publishes them
- [Self-updating screenshots in Mintlify docs](https://www.screenery.dev/guides/mintlify-screenshots): an @latest URL inside Mintlify's Frame component, light and dark variants with ?theme=dark, and the CI workflow that refreshes them
- [README screenshots that update themselves](https://www.screenery.dev/guides/readme-screenshots): add a screenshot to a GitHub README and have each build replace it at the same URL
- [We renamed our app and never retook a screenshot](https://www.screenery.dev/guides/rebrand-without-retaking-screenshots): Auspex Fatalis became Pairings Up, and every screenshot in its help pages and Discord posts followed the day the rebrand merged
- [Pheidi swapped its homepage mockups for screenshots from its tests](https://www.screenery.dev/guides/replace-mockups-with-real-screenshots): a hand-exported hero and a hand-drawn calendar replaced by screenshots its tests take on every merge, with a fixed-size crop for a week too tall for one screen
- [Markdown image syntax](https://www.screenery.dev/guides/markdown-images): paths, linked images, size with `<img width>`, alignment, alt text and dark mode on GitHub
- [Playwright visual regression testing](https://www.screenery.dev/guides/playwright-visual-testing): how toHaveScreenshot works, thresholds and masks, and why committed baselines break across machines
- [Playwright screenshots in GitHub Actions](https://www.screenery.dev/guides/playwright-screenshots-github-actions): one workflow that runs Playwright on each pull request and publishes the screenshots at stable URLs
- [playwright --update-snapshots](https://www.screenery.dev/guides/playwright-update-snapshots): what each mode writes, why goldens made on a Mac fail on Linux CI, and three workflows that avoid it
- [Claude Code and Playwright MCP](https://www.screenery.dev/guides/claude-code-playwright-mcp-screenshots): set up Playwright MCP in Claude Code and let the agent compare a pull request's screenshots with @latest
- [Same seed, same pixels](https://www.screenery.dev/guides/same-seed-same-pixels): how merge.tel made its screenshot seed deterministic, and what to do so your own Screenery diffs only change when your UI does

## Comparisons

- [Visual regression testing tools compared](https://www.screenery.dev/compare/): six visual testing tools and three docs screenshot tools next to Screenery, with prices checked October 2026
- [Screenery vs Percy](https://www.screenery.dev/compare/percy): Percy re-renders pages in several browsers; Screenery publishes the screenshots your tests took
- [Screenery vs Chromatic](https://www.screenery.dev/compare/chromatic): the Storybook platform, and when a Playwright team needs something else
- [Screenery vs Argos](https://www.screenery.dev/compare/argos): share links that expire, against URLs that follow your default branch
- [Screenery vs Applitools Eyes](https://www.screenery.dev/compare/applitools): Visual AI and enterprise controls, against pixel diffs and published URLs
- [Moving from BackstopJS](https://www.screenery.dev/compare/backstopjs): turn backstop.json scenarios into one Playwright test, then publish
- [Moving from Lost Pixel](https://www.screenery.dev/compare/lost-pixel): keep your shots running after the April 2026 archive, then move them to Playwright
- [LaunchBrightly alternative](https://www.screenery.dev/compare/launchbrightly): recorded recipes that refresh help centre screenshots, against screenshots from your own tests
- [Promptless alternative](https://www.screenery.dev/compare/promptless): an agent that signs in and re-takes docs screenshots, against screenshots from your own tests
- [Ferndesk alternative](https://www.screenery.dev/compare/ferndesk): screenshots kept inside one hosted help centre, against URLs any docs tool can embed

## Tools

- [Tools index](https://www.screenery.dev/tools/): every free tool below
- [Compare two screenshots](https://www.screenery.dev/tools/compare-screenshots): a free pixel diff that runs in the browser and uploads nothing

## Optional

- [Homepage](https://www.screenery.dev/): the product overview, with Screenery's own console embedded at its @latest URL
- [The screenery CLI on npm](https://www.npmjs.com/package/screenery): the package behind npx screenery and the MCP server
- [screenery/push](https://github.com/screenery/push): source of the GitHub Action
- [API error reference](https://app.screenery.dev/errors/): every error code the control API returns
- [Console](https://app.screenery.dev/): the Screenery console. Sign in with GitHub
- [Privacy](https://www.screenery.dev/privacy): what Screenery collects, where it is stored, who else handles it, and how long it is kept