@danieljvdm/dev-kit 1.0.2 → 2.0.0

package/skills/sentry/references/snapshots/github-actions-fanout.md

@@ -0,0 +1,206 @@
+# Fan-out GitHub Actions Workflow for SnapshotPreviews
+
+Use this when a SnapshotPreviews project needs multiple simulator destinations or device
+families, parallel rendering, matrix execution, or selective/large-suite CI. This is the
+maintained multi-simulator pattern: build once, render each simulator in parallel with
+`test-without-building`, export each simulator to its own subdirectory, aggregate
+artifacts, then upload once.
+
+Do not replace this with a sequential loop of multiple `xcodebuild test` invocations in
+the simple workflow.
+Sequential multi-simulator rendering is slower and not the recommended path.
+
+Do not use this template for Point-Free `swift-snapshot-testing` or another existing
+generator. For `swift-snapshot-testing`, use `github-actions-swift-snapshot-testing.md`;
+for other generators, preserve the generator and adapt its existing CI/upload path.
+
+This pattern follows the public
+[EmergeTools HackerNews SnapshotPreviews workflow](https://github.com/EmergeTools/hackernews/blob/main/.github/workflows/ios_sentry_upload_snapshots.yml).
+
+Adapt target names, paths, Xcode version, simulator list, package setup, and
+Fastlane/CLI upload to the project.
+
+```yaml
+name: Upload iOS snapshots to Sentry
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+permissions:
+  contents: read
+
+env:
+  DERIVED_DATA_PATH: ${{ github.workspace }}/DerivedData-snapshot-upload
+  SNAPSHOT_UPLOAD_BASE_DIR: ${{ github.workspace }}/snapshot-images
+  BUILD_PRODUCTS_ARCHIVE: ${{ github.workspace }}/snapshot-build-products.tar.gz
+  XCTESTRUN_FILENAME: MyAppSnapshotTests.xctestrun
+  SNAPSHOT_PROJECT: MyApp.xcodeproj
+  SNAPSHOT_SCHEME: MyApp
+  BUILD_DESTINATION: platform=iOS Simulator,name=iPhone 17 Pro Max,arch=arm64
+
+  # GitHub Actions does not inherit local sentry-cli config.
+  # Define SENTRY_AUTH_TOKEN as a repository secret and SENTRY_ORG/SENTRY_PROJECT as repository variables.
+  SENTRY_AUTH_TOKEN: ${{ secrets.SENTRY_AUTH_TOKEN }}
+  SENTRY_ORG: ${{ vars.SENTRY_ORG }}
+  SENTRY_PROJECT: ${{ vars.SENTRY_PROJECT }}
+  SENTRY_APP_ID: com.example.MyApp
+
+jobs:
+  build_for_testing:
+    runs-on: macos-26
+
+    steps:
+      # On PRs, checkout builds the merge candidate; sentry-cli labels uploads from GitHub event head/base SHAs.
+      - name: Checkout
+        uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - name: Select Xcode
+        run: sudo xcode-select -s /Applications/Xcode_26.5.app
+
+      - name: Prepare DerivedData directory
+        run: mkdir -p "${DERIVED_DATA_PATH}"
+
+      - name: Cache Swift Package Manager
+        uses: actions/cache@v4
+        with:
+          path: |
+            ~/Library/Caches/org.swift.swiftpm
+            ${{ env.DERIVED_DATA_PATH }}/SourcePackages
+          key: ${{ runner.os }}-spm-${{ hashFiles('**/Package.resolved') }}
+          restore-keys: ${{ runner.os }}-spm-
+
+      - name: Build snapshot tests
+        run: |
+          xcodebuild build-for-testing \
+            -project "${SNAPSHOT_PROJECT}" \
+            -scheme "${SNAPSHOT_SCHEME}" \
+            -sdk iphonesimulator \
+            -destination "${BUILD_DESTINATION}" \
+            -derivedDataPath "${DERIVED_DATA_PATH}" \
+            -resultBundlePath SnapshotBuildForTesting.xcresult \
+            -skipPackagePluginValidation \
+            ONLY_ACTIVE_ARCH=YES \
+            CODE_SIGNING_ALLOWED=NO
+
+      - name: Normalize xctestrun path
+        run: |
+          XCTESTRUN_SOURCE="$(find "${DERIVED_DATA_PATH}/Build/Products" -name '*.xctestrun' -print -quit)"
+          if [ -z "${XCTESTRUN_SOURCE}" ]; then
+            echo "No .xctestrun file found under ${DERIVED_DATA_PATH}/Build/Products" >&2
+            exit 1
+          fi
+          cp "${XCTESTRUN_SOURCE}" "${DERIVED_DATA_PATH}/Build/Products/${XCTESTRUN_FILENAME}"
+
+      - name: Archive test products
+        run: tar -C "${DERIVED_DATA_PATH}/Build" -czf "${BUILD_PRODUCTS_ARCHIVE}" Products
+
+      - name: Upload build products artifact
+        uses: actions/upload-artifact@v7
+        with:
+          name: snapshot-build-products
+          path: ${{ env.BUILD_PRODUCTS_ARCHIVE }}
+          if-no-files-found: error
+
+  generate_snapshots:
+    runs-on: macos-26
+    needs: build_for_testing
+
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - simulator_name: iPhone 17 Pro Max
+            slug: iphone-17-pro-max
+          - simulator_name: iPhone 17e
+            slug: iphone-17e
+          - simulator_name: iPad Air 11-inch (M4)
+            slug: ipad-air-11-inch-m4
+
+    env:
+      # Export each simulator to a separate subdirectory. SnapshotPreviews filenames are preview-based,
+      # so the same preview rendered on multiple devices would otherwise collide during aggregation.
+      TEST_RUNNER_SNAPSHOTS_EXPORT_DIR: ${{ github.workspace }}/snapshot-images/${{ matrix.slug }}
+
+    steps:
+      # On PRs, checkout builds the merge candidate; sentry-cli labels uploads from GitHub event head/base SHAs.
+      - name: Checkout
+        uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - name: Select Xcode
+        run: sudo xcode-select -s /Applications/Xcode_26.5.app
+
+      - name: Download build products artifact
+        uses: actions/download-artifact@v5
+        with:
+          name: snapshot-build-products
+          path: ${{ github.workspace }}
+
+      - name: Extract test products
+        run: |
+          mkdir -p "${DERIVED_DATA_PATH}/Build"
+          tar -C "${DERIVED_DATA_PATH}/Build" -xzf "${BUILD_PRODUCTS_ARCHIVE}"
+
+      - name: Boot simulator
+        run: xcrun simctl boot "${{ matrix.simulator_name }}" || true
+
+      - name: Prepare snapshot export directory
+        run: mkdir -p "${TEST_RUNNER_SNAPSHOTS_EXPORT_DIR}"
+
+      - name: Generate snapshot images
+        run: |
+          xcodebuild test-without-building \
+            -xctestrun "${DERIVED_DATA_PATH}/Build/Products/${XCTESTRUN_FILENAME}" \
+            -destination "platform=iOS Simulator,name=${{ matrix.simulator_name }},arch=arm64" \
+            -resultBundlePath "SnapshotResults-${{ matrix.slug }}.xcresult"
+
+      - name: Upload snapshots artifact
+        uses: actions/upload-artifact@v7
+        with:
+          name: snapshots-${{ matrix.slug }}
+          path: ${{ env.TEST_RUNNER_SNAPSHOTS_EXPORT_DIR }}
+          if-no-files-found: error
+
+  upload_snapshots:
+    runs-on: macos-26
+    needs: generate_snapshots
+
+    steps:
+      # On PRs, checkout builds the merge candidate; sentry-cli labels uploads from GitHub event head/base SHAs.
+      - name: Checkout
+        uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - name: Download generated snapshots
+        uses: actions/download-artifact@v5
+        with:
+          path: ${{ env.SNAPSHOT_UPLOAD_BASE_DIR }}
+          pattern: snapshots-*
+
+      - name: List aggregated snapshot files
+        run: |
+          find "${SNAPSHOT_UPLOAD_BASE_DIR}" -type f | sort
+          echo "Total PNG images: $(find "${SNAPSHOT_UPLOAD_BASE_DIR}" -type f -name '*.png' | wc -l | tr -d ' ')"
+
+      - name: Install sentry-cli
+        run: curl -sL https://sentry.io/get-cli/ | bash
+
+      - name: Upload snapshots to Sentry
+        run: |
+          sentry-cli snapshots upload "${SNAPSHOT_UPLOAD_BASE_DIR}" \
+            --org "${SENTRY_ORG}" \
+            --project "${SENTRY_PROJECT}" \
+            --app-id "${SENTRY_APP_ID}"
+```
+
+For selective PR rendering, add a separate manifest job with
+`TEST_RUNNER_SNAPSHOTS_ALL_IMAGE_NAMES_FILE`, aggregate all shard manifests with
+`sort -u`, and pass `--all-image-file-names-file` only for pull-request uploads.
+Do not add this complexity unless selective testing is actually required.

package/skills/sentry/references/snapshots/github-actions-simple.md

@@ -0,0 +1,102 @@
+# Simple GitHub Actions Workflow for SnapshotPreviews
+
+Use this when adding Sentry Snapshots CI for a SnapshotPreviews Apple app with one
+simulator destination.
+Start here by default for single-device SnapshotPreviews onboarding.
+
+Do not extend this template with sequential loops over multiple simulators.
+If the user asks for multiple simulator destinations or device families, use
+`github-actions-fanout.md` instead.
+
+Do not use this template for Point-Free `swift-snapshot-testing` or another existing
+generator. For `swift-snapshot-testing`, use `github-actions-swift-snapshot-testing.md`;
+for other generators, preserve the generator and adapt its existing CI/upload path.
+
+For a public production SnapshotPreviews workflow, compare against the
+[EmergeTools HackerNews fan-out workflow](https://github.com/EmergeTools/hackernews/blob/main/.github/workflows/ios_sentry_upload_snapshots.yml).
+This simple template intentionally keeps the same upload model but removes matrix
+fan-out and build-product sharing.
+
+Before adapting this template:
+
+1. Verify the runner image has the required Xcode, SDK, and simulator.
+   Do not guess from memory.
+2. Prefer the project’s existing shared scheme and single simulator destination.
+3. Keep base-branch uploads full.
+   Add selective flags only for selective PR uploads.
+4. Use Fastlane instead of direct `sentry-cli` when the project already has a Sentry
+   Fastlane lane.
+
+```yaml
+name: Upload iOS snapshots to Sentry
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+permissions:
+  contents: read
+
+env:
+  SNAPSHOT_EXPORT_DIR: ${{ github.workspace }}/snapshot-images
+  SNAPSHOT_PROJECT: MyApp.xcodeproj
+  SNAPSHOT_SCHEME: MyApp
+  SNAPSHOT_DESTINATION: platform=iOS Simulator,name=iPhone 17 Pro Max,arch=arm64
+
+  # Define SENTRY_AUTH_TOKEN as a repository secret and SENTRY_ORG/SENTRY_PROJECT as repository variables.
+  SENTRY_AUTH_TOKEN: ${{ secrets.SENTRY_AUTH_TOKEN }}
+  SENTRY_ORG: ${{ vars.SENTRY_ORG }}
+  SENTRY_PROJECT: ${{ vars.SENTRY_PROJECT }}
+  SENTRY_APP_ID: com.example.MyApp
+jobs:
+  upload_snapshots:
+    runs-on: macos-26
+
+    steps:
+      # On PRs, checkout builds the merge candidate; sentry-cli labels uploads from GitHub event head/base SHAs.
+      - name: Checkout
+        uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - name: Select Xcode
+        run: sudo xcode-select -s /Applications/Xcode_26.5.app
+
+      - name: Resolve Swift packages
+        run: |
+          xcodebuild -resolvePackageDependencies \
+            -project "${SNAPSHOT_PROJECT}" \
+            -scheme "${SNAPSHOT_SCHEME}"
+
+      - name: Render snapshots
+        env:
+          TEST_RUNNER_SNAPSHOTS_EXPORT_DIR: ${{ env.SNAPSHOT_EXPORT_DIR }}
+        run: |
+          xcodebuild test \
+            -project "${SNAPSHOT_PROJECT}" \
+            -scheme "${SNAPSHOT_SCHEME}" \
+            -sdk iphonesimulator \
+            -destination "${SNAPSHOT_DESTINATION}" \
+            -skipPackagePluginValidation \
+            CODE_SIGNING_ALLOWED=NO
+
+      - name: Install sentry-cli
+        run: curl -sL https://sentry.io/get-cli/ | bash
+
+      - name: Upload snapshots to Sentry
+        run: |
+          sentry-cli snapshots upload "${SNAPSHOT_EXPORT_DIR}" \
+            --org "${SENTRY_ORG}" \
+            --project "${SENTRY_PROJECT}" \
+            --app-id "${SENTRY_APP_ID}"
+```
+
+If using Fastlane, replace the install/upload steps with the project’s existing Ruby
+setup and lane, for example:
+
+```yaml
+- name: Upload snapshots to Sentry
+  run: bundle exec fastlane ios upload_sentry_snapshots path:"${SNAPSHOT_EXPORT_DIR}"
+```

package/skills/sentry/references/snapshots/github-actions-swift-snapshot-testing.md

@@ -0,0 +1,118 @@
+# GitHub Actions Workflow for Point-Free swift-snapshot-testing
+
+Use this when a project already uses Point-Free `swift-snapshot-testing` and the user
+wants GitHub Actions/CI upload to Sentry Snapshots.
+Do not run the `appleSnapshots` wizard or use the SnapshotPreviews workflow templates
+for this path.
+
+This pattern follows the public
+[EmergeTools HackerNews workflow](https://github.com/EmergeTools/hackernews/blob/main/.github/workflows/ios_sentry_upload_swift_snapshots.yml).
+Run the existing XCTest suite in record mode, allow the recording step to fail because
+`swift-snapshot-testing` treats recording as test failures, then upload the generated
+`__Snapshots__` directory to Sentry.
+
+Before adapting this template:
+
+1. Locate the test target/class that owns the `assertSnapshot` calls.
+2. Confirm the generated `__Snapshots__/<TestClass>/` path.
+3. Prefer the project’s existing Ruby/Fastlane setup if it already uploads snapshots.
+4. Keep local test behavior unchanged; set record mode only in CI through the
+   environment.
+
+```yaml
+name: Upload iOS swift-snapshot-testing snapshots to Sentry
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+permissions:
+  contents: read
+
+env:
+  SNAPSHOT_PROJECT: MyApp.xcodeproj
+  SNAPSHOT_SCHEME: MyApp
+  SNAPSHOT_DESTINATION: platform=iOS Simulator,name=iPhone 17 Pro Max,arch=arm64
+  SNAPSHOT_TEST_IDENTIFIER: MyAppTests/MyAppSnapshotTest
+  SNAPSHOT_OUTPUT_DIR: MyAppTests/__Snapshots__/MyAppSnapshotTest
+
+  # Define SENTRY_AUTH_TOKEN as a repository secret and SENTRY_ORG/SENTRY_PROJECT as repository variables.
+  SENTRY_AUTH_TOKEN: ${{ secrets.SENTRY_AUTH_TOKEN }}
+  SENTRY_ORG: ${{ vars.SENTRY_ORG }}
+  SENTRY_PROJECT: ${{ vars.SENTRY_PROJECT }}
+  SENTRY_APP_ID: com.example.MyApp.swift-snapshot-testing
+
+jobs:
+  upload_swift_snapshots:
+    runs-on: macos-26
+
+    env:
+      # Propagates SNAPSHOT_TESTING_RECORD=all into the iOS test runner.
+      TEST_RUNNER_SNAPSHOT_TESTING_RECORD: all
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - name: Select Xcode
+        run: sudo xcode-select -s /Applications/Xcode_26.5.app
+
+      - name: Resolve Swift packages
+        run: |
+          xcodebuild -resolvePackageDependencies \
+            -project "${SNAPSHOT_PROJECT}" \
+            -scheme "${SNAPSHOT_SCHEME}"
+
+      - name: Boot simulator
+        run: xcrun simctl boot "iPhone 17 Pro Max" || true
+
+      - name: Generate snapshot images
+        continue-on-error: true
+        run: |
+          xcodebuild test \
+            -project "${SNAPSHOT_PROJECT}" \
+            -scheme "${SNAPSHOT_SCHEME}" \
+            -sdk iphonesimulator \
+            -destination "${SNAPSHOT_DESTINATION}" \
+            -only-testing:"${SNAPSHOT_TEST_IDENTIFIER}" \
+            -resultBundlePath SnapshotResults-swift-snapshots.xcresult \
+            -skipPackagePluginValidation \
+            CODE_SIGNING_ALLOWED=NO
+
+      - name: List generated images
+        run: |
+          find "${SNAPSHOT_OUTPUT_DIR}" -type f | sort
+          echo "Total PNG images: $(find "${SNAPSHOT_OUTPUT_DIR}" -type f -name '*.png' | wc -l | tr -d ' ')"
+
+      - name: Install sentry-cli
+        run: curl -sL https://sentry.io/get-cli/ | bash
+
+      - name: Upload snapshots to Sentry
+        run: |
+          sentry-cli snapshots upload "${SNAPSHOT_OUTPUT_DIR}" \
+            --org "${SENTRY_ORG}" \
+            --project "${SENTRY_PROJECT}" \
+            --app-id "${SENTRY_APP_ID}"
+```
+
+If using Fastlane, replace the install/upload steps with the project’s existing lane,
+for example:
+
+```yaml
+- name: Upload snapshots to Sentry
+  run: bundle exec fastlane ios upload_sentry_snapshots_swift_snapshot_testing
+```
+
+Rules:
+
+- Use `TEST_RUNNER_SNAPSHOT_TESTING_RECORD=all`, not `SNAPSHOT_TESTING_RECORD=all`, so
+  the value reaches the iOS test runner.
+- Keep `continue-on-error: true` on the recording test step; otherwise recording
+  failures prevent upload.
+- Upload the generated `__Snapshots__` directory that contains PNG images.
+- Use a stable `--app-id`. If the same app also uploads SnapshotPreviews images, give
+  this generator a distinct app id to avoid mixing baselines.

package/skills/sentry/references/snapshots/index.md

@@ -0,0 +1,19 @@
+# Apple snapshots
+
+Inspect the existing image generator, Xcode host and test targets, output path,
+and CI. Preserve a named or working generator. SnapshotPreviews requires a host
+app and hosted XCTest target; these requirements do not apply to every generator.
+Resolve missing targets only when they are needed by the selected workflow.
+
+- New SnapshotPreviews setup: [wizard setup](wizard-setup.md).
+- Existing SnapshotPreviews or selective rendering: [rendering](snapshot-previews.md).
+- Upload images from any generator: [uploads](snapshots.md).
+- One-destination SnapshotPreviews CI: [simple CI](github-actions-simple.md).
+- Multiple destinations or selective SnapshotPreviews CI: [fanout](github-actions-fanout.md).
+- Point-Free snapshot testing CI: [existing generator](github-actions-swift-snapshot-testing.md).
+
+Configure only the requested generation or upload path. Follow repository test
+policy; ordinary telemetry setup does not authorize adding snapshot tests. Inspect
+the produced images and manifest, then verify the authorized upload. Preserve a
+full base manifest when using selective PR uploads. Report an unavailable host,
+credential, or CI run without claiming deployed verification.

package/skills/sentry/references/snapshots/snapshot-previews.md

@@ -0,0 +1,100 @@
+# SnapshotPreviews Details
+
+Use this reference when the project uses Sentry’s first-party SnapshotPreviews library
+and needs SnapshotPreviews-specific metadata, rendering preferences, selective
+rendering, or troubleshooting.
+
+Wizard setup, target disambiguation, and manual fallback live in `wizard-setup.md`.
+Shared upload guidance for `sentry-cli`, Fastlane, manifests, and CI lives in
+`snapshots.md`.
+
+## Metadata and Rendering Preferences
+
+Add `SnapshotPreferences` to the preview-declaring target only when default
+SnapshotPreviews sidecar metadata is insufficient.
+See Sentry’s SnapshotPreviews metadata docs:
+https://docs.sentry.io/platforms/apple/snapshots/snapshotpreviews-metadata/
+
+```swift
+import SnapshotPreferences
+
+#Preview("Map") {
+  MapPreview()
+    .snapshotTags(["screen": "map"])
+    .snapshotAdditionalContext(["fixture": "city-route"])
+}
+```
+
+| Modifier                                    | Use when                                                                        |
+| ------------------------------------------- | ------------------------------------------------------------------------------- |
+| `.snapshotTags([String: String])`           | Sentry needs searchable filters beyond defaults.                                |
+| `.snapshotAdditionalContext([String: Any])` | Reviewers need extra sidecar context.                                           |
+| `.snapshotDiffThreshold(Float?)`            | A deterministic snapshot still has tolerated visual noise.                      |
+| `.snapshotAccessibility(true)`              | Need an accessibility-overlay variant on iOS.                                   |
+| `.snapshotRenderingMode(.coreAnimation)`    | Default renderer is wrong for blur, maps, video, or renderer-sensitive content. |
+| `.snapshotExpansion(false)`                 | Expanded scroll views create unstable or unhelpful images.                      |
+
+Rules:
+
+- Prefer deterministic previews over thresholds.
+- Avoid live network, timers, animations, current-clock dates, locale-dependent data,
+  and real user data.
+- Use fixed fixtures and mocked dependencies.
+
+## Selective Rendering
+
+Use for PRs that should render only changed/high-signal SnapshotPreviews while
+preserving Sentry comparison semantics.
+
+1. Generate the full image-name manifest without rendering:
+
+```bash
+TEST_RUNNER_SNAPSHOTS_ALL_IMAGE_NAMES_FILE="$PWD/all-image-names.txt" \
+xcodebuild test \
+  -scheme MyApp \
+  -sdk iphonesimulator \
+  -destination 'platform=iOS Simulator,name=iPhone 16 Pro'
+```
+
+2. Render the subset with `snapshotPreviews()`, `snapshotPreviewModules()`,
+   `excludedSnapshotPreviews()`, `excludedSnapshotPreviewModules()`, or `-only-testing:`
+   while `TEST_RUNNER_SNAPSHOTS_EXPORT_DIR` is set.
+
+3. Upload the rendered subset using the full manifest.
+   Read `snapshots.md` for the upload command and manifest flags.
+
+Rules:
+
+- `TEST_RUNNER_`-prefixed environment variables are forwarded into the app/test process.
+- Sharded simulators export into separate subdirectories.
+- Sharded manifests must be merged and de-duplicated with `sort -u` before upload.
+- Generate the manifest and rendered subset from the same commit.
+
+## GitHub Actions Notes
+
+Do not duplicate workflow templates here.
+
+| CI shape                                                              | Read                       |
+| --------------------------------------------------------------------- | -------------------------- |
+| One simulator destination                                             | `github-actions-simple.md` |
+| Multiple simulators/device families, parallel rendering, large suites | `github-actions-fanout.md` |
+
+Before writing workflows:
+
+- Verify current runner image, Xcode path, SDKs, and simulator names from existing CI or
+  current runner docs.
+- Use `fetch-depth: 0` so `sentry-cli` can resolve base/head commits.
+- Prefer existing Fastlane upload lanes when present; upload configuration lives in
+  `snapshots.md`.
+
+## Troubleshooting
+
+| Issue                       | Fix                                                                                                                                 |
+| --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
+| No generated tests/previews | Confirm previews are loaded by the hosted app/test process, build conditions match, and test target depends on `SnapshottingTests`. |
+| Package-only project        | Ask for the host app/test target; standalone `swift test` rendering is not supported.                                               |
+| Export directory empty      | Set `TEST_RUNNER_SNAPSHOTS_EXPORT_DIR`; ensure `TEST_RUNNER_SNAPSHOTS_ALL_IMAGE_NAMES_FILE` is not also set.                        |
+| Manifest mismatch           | Regenerate manifest and subset from same commit; merge shard manifests.                                                             |
+| Image too large             | Keep images below 40M pixels; constrain preview layout or use `.snapshotExpansion(false)`.                                          |
+| Flaky snapshots             | Remove nondeterminism first; then try rendering mode or per-preview diff threshold.                                                 |
+| Duplicate path warnings     | Make display names unique and avoid overlapping shard filters.                                                                      |

package/skills/sentry/references/snapshots/snapshots.md

@@ -0,0 +1,123 @@
+# Sentry Snapshots Upload
+
+Use this reference after an image source has been selected and the project can produce
+PNG or JPEG snapshots.
+The image source can be Sentry’s first-party SnapshotPreviews, Point-Free
+`swift-snapshot-testing`, or a custom generator.
+
+This skill integrates generated snapshot images with Sentry’s Snapshot service.
+It does not replace existing third-party generators.
+If the project already has an image generator, preserve it and upload the images it
+already produces.
+
+For SnapshotPreviews-specific generation, metadata, and selective rendering mechanics,
+read `snapshot-previews.md`.
+
+## Image Source Rules
+
+- Preserve the selected image source.
+- Point `sentry-cli snapshots upload` or Fastlane at the directory containing generated
+  `.png` or `.jpg`/`.jpeg` files.
+- For existing generators, do not run the `appleSnapshots` wizard; it configures
+  Sentry’s first-party SnapshotPreviews flow.
+- For Point-Free `swift-snapshot-testing`, keep `SnapshotTesting` linked from the XCTest
+  target or package test target that owns `assertSnapshot` calls; do not link it into
+  the app/library target just to satisfy Sentry upload.
+- For Point-Free `swift-snapshot-testing`, set `TEST_RUNNER_SNAPSHOT_TESTING_RECORD=all`
+  so CI pushes `SNAPSHOT_TESTING_RECORD=all` into the iOS test runner without hardcoding
+  record mode in tests.
+  This keeps local Xcode diffing normal while CI records images for Sentry to diff as a
+  service.
+- For Point-Free `swift-snapshot-testing`, upload the relevant
+  `__Snapshots__/<TestClass>/` directory, and allow the recording test step to continue
+  so upload still runs.
+- Add JSON sidecars only when the project needs Sentry display names, tags, custom
+  context, or per-image thresholds.
+  SnapshotPreviews can emit sidecars through its own metadata API; other generators
+  should use Sentry’s generic sidecar schema:
+  https://docs.sentry.io/product/snapshots/uploading-snapshots/#json-metadata
+
+## Fastlane Upload
+
+Use when the project already has Fastlane or wants upload logic in `fastlane/Fastfile`.
+
+```ruby
+lane :upload_sentry_snapshots do |options|
+  sentry_upload_snapshots(
+    auth_token: ENV["SENTRY_AUTH_TOKEN"],
+    org_slug: "your-org",
+    project_slug: "your-ios-project",
+    app_id: "com.example.MyApp",
+    path: options[:path]
+  )
+end
+```
+
+```bash
+bundle exec fastlane ios upload_sentry_snapshots path:"$PWD/snapshot-images"
+```
+
+Verify exact `fastlane-plugin-sentry` action parameter names against the installed
+plugin version before finalizing.
+
+## `sentry-cli` Upload Flags
+
+```bash
+sentry-cli snapshots upload "$PWD/snapshot-images" \
+  --org your-org \
+  --project your-ios-project \
+  --app-id com.example.MyApp
+```
+
+| Flag                                 | Purpose                                                                          |
+| ------------------------------------ | -------------------------------------------------------------------------------- |
+| `--app-id <APP_ID>`                  | Required stable application identifier; usually bundle id.                       |
+| `--diff-threshold <0.0-1.0>`         | Global changed-pixel threshold; prefer per-image sidecar values when available.  |
+| `--selective`                        | Marks upload as a subset. Use a manifest when removals/renames must be detected. |
+| `--all-image-file-names-file <PATH>` | Full suite image-name manifest; implies `--selective`.                           |
+| `--all-image-file-names <NAMES>`     | Inline comma-separated manifest; conflicts with file variant.                    |
+| `--base-sha <SHA>`                   | Base commit when CI cannot expose a merge base.                                  |
+
+Rules:
+
+- Auth comes from `SENTRY_AUTH_TOKEN` or `--auth-token`.
+- PR number without resolvable base SHA fails upload; pass `--base-sha` or check out
+  full history.
+- Images above 40 million pixels are rejected.
+- Base branch uploads the full snapshot set without selective flags.
+- PR subset uploads should include the full image-name manifest so Sentry can detect
+  removals and renames.
+- Every uploaded image must appear in the manifest.
+- Generate the manifest and rendered subset from the same commit.
+- Sharded manifests must be merged and de-duplicated with `sort -u` before upload.
+- `--selective` without a manifest cannot detect removals or renames.
+
+## GitHub Actions Notes
+
+Do not duplicate workflow templates here.
+
+| CI shape                                                                                    | Read                                                                      |
+| ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- |
+| SnapshotPreviews with one simulator destination                                             | `github-actions-simple.md`                                                |
+| SnapshotPreviews with multiple simulators/device families, parallel rendering, large suites | `github-actions-fanout.md`                                                |
+| Point-Free `swift-snapshot-testing`                                                         | `github-actions-swift-snapshot-testing.md`                                |
+| Other existing generator                                                                    | Adapt the project’s existing CI and upload the generated image directory. |
+
+Before writing workflows:
+
+- Verify current runner image, Xcode path, SDKs, and simulator names from existing CI or
+  current runner docs.
+- Use `fetch-depth: 0` so `sentry-cli` can resolve base/head commits.
+- Prefer existing Fastlane upload lanes when present.
+
+## Troubleshooting
+
+| Issue                       | Fix                                                                                                   |
+| --------------------------- | ----------------------------------------------------------------------------------------------------- |
+| Upload says no images found | Point upload at the directory containing PNGs; hidden files/directories are skipped.                  |
+| Auth failure                | Set `SENTRY_AUTH_TOKEN` or `--auth-token`; confirm `--org` and `--project`.                           |
+| PR upload needs base SHA    | Check out full history or pass `--base-sha`.                                                          |
+| Manifest mismatch           | Regenerate manifest and subset from same commit; merge shard manifests.                               |
+| Image too large             | Keep images below 40M pixels; constrain snapshot layout or renderer output.                           |
+| Flaky snapshots             | Remove nondeterminism first; then use generator-specific diff tolerance or Sentry sidecar thresholds. |
+| Wrong comparisons in Sentry | Use stable `--app-id`, usually bundle id, not project slug.                                           |