docs: Add Snapshots EA product documentation

docs/product/snapshots/index.mdx

@@ -0,0 +1,29 @@
+---
+title: Snapshots
+sidebar_order: 138
+description: Detect visual changes by comparing PNG snapshots against a baseline on every pull request.
+new: true
+---
+
+<Include name="feature-available-for-user-group-early-adopter" />
+
+Snapshots catches visual regressions before they reach users. Your CI pipeline generates PNG screenshots, uploads them to Sentry, and Sentry compares each image against a baseline from your main branch using pixel-level diffing.
+
+When a snapshot changes, Sentry posts a failing GitHub Check on your pull request. You review the diff in Sentry's comparison viewer and approve or reject the changes.
+
+## How It Works
+
+1. **Generate snapshots** — Your CI job produces PNG screenshots however you like: Playwright, Storybook, simulator captures, or any tool that outputs PNGs.
+2. **Upload to Sentry** — `sentry-cli` uploads the snapshot directory along with Git metadata so Sentry can associate each upload with a commit.
+3. **Sentry diffs against the baseline** — Sentry finds the most recent snapshot set from your base branch (matched by `app_id`) and categorizes each image as added, removed, modified, renamed, or unchanged.
+4. **Result posted to your PR** — A "Snapshot Testing" GitHub Check appears on the pull request. It passes if nothing changed and fails if any snapshots need approval.
+5. **Review and approve** — Click through to Sentry's comparison viewer to inspect diffs, then approve to resolve the failing check.
+
+## Prerequisites
+
+- **Early Adopter access** — Enable the Early Adopter toggle in your [organization settings](/organization/early-adopter-features/).
+- **Auth token** — A Sentry auth token with `project:write` scope (personal token) or `org:ci` scope (org-level token).
+- **sentry-cli >= 3.3.4** — The `build snapshots` command requires version 3.3.4 or later.
+- **GitHub integration** — Install the [Sentry GitHub App](/organization/integrations/source-code-mgmt/github/) and grant it access to your repository so Sentry can post Check Runs.
+
+<PageGrid />

docs/product/snapshots/reviewing-snapshots/index.mdx

@@ -0,0 +1,44 @@
+---
+title: Reviewing Snapshots
+sidebar_order: 20
+description: Review snapshot diffs on your pull request and approve changes.
+---
+
+<Include name="feature-available-for-user-group-early-adopter" />
+
+## Status Checks
+
+After you upload snapshots from a pull request branch, a **Snapshot Testing** GitHub Check appears on the pull request. If no snapshots changed, the check passes. If any snapshots were added, removed, or modified, the check fails and requires approval.
+
+IMAGE: GitHub Check showing Snapshot Testing results on a pull request
+
+## Comparison Viewer
+
+Click **Details** on the GitHub Check to open Sentry's comparison viewer. The viewer has two panels:
+
+- **Sidebar** — Lists all snapshots grouped by status: modified, added, removed, renamed, and unchanged. Click a snapshot to view it.
+- **Main panel** — Displays the selected snapshot's diff with three viewing modes:
+  - **Split** — Side-by-side view of base and current branch with a diff overlay highlighting changed pixels.
+  - **Wipe** — Drag a slider across the image to compare base and current branch.
+  - **Onion** — Overlay both images with an adjustable opacity slider.
+
+IMAGE: Sentry Snapshot comparison viewer showing a modified image with split diff
+
+## Approve Changes
+
+There are two ways to approve snapshot changes:
+
+- Click the **Approve** button on the GitHub Check Run.
+- Click **Approve** in the Sentry comparison viewer.
+
+Approval resolves the failing check. If new changes are pushed to the PR, the check resets and requires approval again.
+
+## Settings
+
+Configure snapshot behavior in **Project Settings > Mobile Builds > Snapshots**.
+
+| Setting                   | Default | Description                                           |
+| ------------------------- | :-----: | ----------------------------------------------------- |
+| Status Checks Enabled     |   On    | Post GitHub Check Runs for snapshot comparisons.      |
+| Fail on Added Snapshots   |   Off   | Require approval when new snapshots are added.        |
+| Fail on Removed Snapshots |   On    | Require approval when existing snapshots are removed. |

docs/product/snapshots/uploading-snapshots/index.mdx

@@ -0,0 +1,128 @@
+---
+title: Uploading Snapshots
+sidebar_order: 10
+description: Structure your snapshot directory and upload from CI with sentry-cli.
+---
+
+<Include name="feature-available-for-user-group-early-adopter" />
+
+Snapshots can be used with any frontend screenshot framework. We have examples in different platform documentaiton pages (TODO: EXAMPLES). This page covers the general upload structure and metadata schema.
+
+## Snapshots Upload Structure
+
+Each snapshot consists of two files: a `.png` image and a `.json` metadata sidecar with the same base name. You can organize snapshots into subdirectories — the CLI reads the entire directory tree.
+
+```
+snapshots/
+├── homepage.png
+├── homepage.json
+├── settings/
+│   ├── profile.png
+│   ├── profile.json
+│   ├── billing.png
+│   └── billing.json
+```
+
+Filenames are the identity key for each snapshot. Keep them stable across runs so Sentry can accurately diff head against base.
+
+## Metadata
+
+The `.json` sidecar describes its paired `.png`:
+
+```json
+{
+  "display_name": "Billing Page",
+  "group": "Settings"
+}
+```
+
+| Field          | Type   | Description                                                |
+| -------------- | ------ | ---------------------------------------------------------- |
+| `display_name` | string | Human-readable label shown in the comparison viewer.       |
+| `group`        | string | Groups related snapshots in the comparison viewer sidebar. |
+
+TODO: IMAGE OF DISPLAY NAME AND GROUP
+
+## Upload With CI
+
+To see the workflow Sentry uses on its own codebase, view the [frontend snapshots workflow](https://github.com/getsentry/sentry/blob/master/.github/workflows/frontend-snapshots.yml).
+
+Below is a complete GitHub Actions workflow you can copy into your repository. Replace the placeholder values with your own snapshot generation command, app ID, and Sentry project slug.
+
+```yml {filename:.github/workflows/snapshots.yml}
+name: Snapshots
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.head_ref || github.run_id }}
+  cancel-in-progress: true
+
+env:
+  SNAPSHOT_OUTPUT_DIR: .artifacts/snapshots
+
+jobs:
+  snapshots:
+    runs-on: ubuntu-24.04
+    timeout-minutes: 20
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          # Use PR head SHA, not the merge commit — avoids phantom diffs
+          ref: ${{ github.event.pull_request.head.sha || github.sha }}
+
+      # -------------------------------------------------------
+      # YOUR SNAPSHOT GENERATION STEP(S) HERE
+      # -------------------------------------------------------
+      # Generate PNG + JSON pairs into $SNAPSHOT_OUTPUT_DIR.
+      # Examples:
+      #   - Playwright screenshots
+      #   - Storybook captures
+      #   - iOS/Android simulator screenshots
+      #   - Any tool that produces PNGs
+      # -------------------------------------------------------
+      - name: Generate snapshots
+        run: <your-snapshot-command>
+
+      - name: Install sentry-cli
+        if: ${{ !cancelled() }}
+        run: curl -sL https://sentry.io/get-cli/ | SENTRY_CLI_VERSION=3.3.4 sh
+
+      - name: Upload snapshots
+        if: ${{ !cancelled() }}
+        env:
+          SENTRY_AUTH_TOKEN: ${{ secrets.SENTRY_SNAPSHOTS_AUTH_TOKEN }}
+        run: |
+          ARGS=(
+            --auth-token "$SENTRY_AUTH_TOKEN"
+            build snapshots "${{ env.SNAPSHOT_OUTPUT_DIR }}"
+            --app-id <your-app-id>
+            --project <your-sentry-project>
+            --head-sha "${{ github.event.pull_request.head.sha || github.sha }}"
+            --vcs-provider github
+            --head-repo-name "${{ github.repository }}"
+          )
+
+          if [[ "${{ github.event_name }}" == "pull_request" ]]; then
+            ARGS+=(
+              --base-sha "${{ github.event.pull_request.base.sha }}"
+              --base-repo-name "${{ github.repository }}"
+              --head-ref "${{ github.head_ref }}"
+              --base-ref "${{ github.base_ref }}"
+              --pr-number "${{ github.event.number }}"
+            )
+          fi
+
+          sentry-cli "${ARGS[@]}"
+```
+
+A few things to note about this workflow:
+
+- **Checkout at PR head SHA** — Using `ref: ${{ github.event.pull_request.head.sha || github.sha }}` avoids phantom diffs caused by the merge commit GitHub generates by default.
+- **Upload even on partial failure** — The `if: ${{ !cancelled() }}` condition ensures partial results still get uploaded if some snapshot tests fail.
+- **Keep `--app-id` consistent** — The `app_id` ties head and base uploads together. Sentry finds the baseline by matching the same `app_id` at the `base_sha`. Use one `app_id` per logical app or bundle.
+
+Other CI systems work by passing the same flags to `sentry-cli build snapshots` explicitly.