@@ -0,0 +1,161 @@
+name: API Breakage Detection
+
+on:
+  pull_request:
+    paths:
+      - 'packages/**'
+      - 'tools/snapi/**'
+  push:
+    branches:
+      - main
+    paths:
+      - 'packages/**'
+      - 'tools/snapi/**'
+
+concurrency:
+  group: api-breakage-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  detect-api-changes:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pull-requests: write
+      statuses: write
+
+    env:
+      GCS_PROJECT_ID: ${{ secrets.GCS_PROJECT_ID }}
+      GCS_BUCKET: ${{ secrets.GCS_BUCKET }}
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0  # Need full history
+
+      - name: Setup
+        id: config
+        uses: ./.github/actions/init-blacksmith
+        with:
+          turbo-signature: ${{ secrets.TURBO_REMOTE_CACHE_SIGNATURE_KEY }}
+          turbo-team: ${{ vars.TURBO_TEAM }}
+          turbo-token: ${{ secrets.TURBO_TOKEN }}
+
+      - name: Build packages
+        run: pnpm build
+
+      - name: Build Brkr-Brkr
+        run: pnpm turbo build --filter=@clerk/snapi
+
+      - name: Run API breakage detection (PR)
+        if: github.event_name == 'pull_request'
+        id: api-check-pr
+        run: |
+          # Generate current snapshots
+          node tools/snapi/dist/cli.js snapshot --config snapi.config.json
+          
+          # Run breaking changes detection
+          echo "🔍 Detecting API changes..."
+          if node tools/snapi/dist/cli.js detect --config snapi.config.json --format markdown --output api-changes-report.md; then
+            echo "api_check_passed=true" >> $GITHUB_OUTPUT
+          else
+            echo "api_check_passed=false" >> $GITHUB_OUTPUT
+          fi
+
+      - name: Update baseline cache (main branch)
+        if: github.ref == 'refs/heads/main' && github.event_name == 'push'
+        run: |
+          node tools/snapi/dist/cli.js snapshot --config snapi.config.json --force
+          
+          # Store as artifacts for backup
+          echo "COMMIT_SHA=$(git rev-parse HEAD)" >> $GITHUB_ENV
+
+      - name: Upload baseline snapshots (main branch)
+        if: github.ref == 'refs/heads/main' && github.event_name == 'push'
+        uses: actions/upload-artifact@v4
+        with:
+          name: api-baseline-${{ env.COMMIT_SHA }}
+          path: .api-snapshots/
+          retention-days: 90
+
+      - name: Comment on PR
+        if: github.event_name == 'pull_request'
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const fs = require('fs');
+            
+            // Read the generated report
+            let reportContent = '';
+            try {
+              reportContent = fs.readFileSync('api-changes-report.md', 'utf8');
+            } catch (error) {
+              reportContent = '❌ **Error**: Could not generate API changes report.\n\n' + error.message;
+            }
+            
+            // Find existing comment
+            const comments = await github.rest.issues.listComments({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              issue_number: context.issue.number
+            });
+            
+            const existingComment = comments.data.find(
+              comment => comment.user.login === 'github-actions[bot]' && 
+                        comment.body.includes('API Changes Report')
+            );
+            
+            const commentBody = `## 🔍 API Changes Report
+            
+            ${reportContent}
+            
+            ---
+            <sub>🤖 This comment was automatically generated by the API Breakage Detector</sub>`;
+            
+            if (existingComment) {
+              // Update existing comment
+              await github.rest.issues.updateComment({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                comment_id: existingComment.id,
+                body: commentBody
+              });
+            } else {
+              // Create new comment
+              await github.rest.issues.createComment({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                issue_number: context.issue.number,
+                body: commentBody
+              });
+            }
+
+      - name: Set commit status
+        if: github.event_name == 'pull_request'
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const apiCheckPassed = '${{ steps.api-check-pr.outputs.api_check_passed }}' === 'true';
+            
+            await github.rest.repos.createCommitStatus({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              sha: context.payload.pull_request.head.sha,
+              state: apiCheckPassed ? 'success' : 'failure',
+              target_url: `${context.payload.pull_request.html_url}/checks`,
+              description: apiCheckPassed ? 
+                'No breaking API changes detected' : 
+                'Breaking API changes detected - review required',
+              context: 'snapi'
+            });
+
+      - name: Upload API snapshots and reports
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: api-debug-${{ github.run_id }}
+          path: |
+            .api-snapshots/
+            api-changes-report.md
+          retention-days: 7 
@@ -40,6 +40,7 @@ testem.log
 /typings
 **/coverage/**
 *.tsbuildinfo
+.tmp
 
 # System Files
 .DS_Store
@@ -99,3 +100,10 @@ scripts/.env
 # typedoc
 .typedoc/docs
 .typedoc/docs.json
+
+# API Breakage Detection
+.api-snapshots/current/
+.api-snapshots/temp/
+.api-snapshots/.baseline-cache.json
+# Keep baseline snapshots in Git for CI
+!.api-snapshots/baseline/
@@ -4,6 +4,10 @@
   "private": true,
   "license": "MIT",
   "scripts": {
+    "api:check": "pnpm --filter=snapi run build && pnpm --filter=snapi run detect",
+    "api:init": "pnpm --filter=snapi run build && pnpm --filter=snapi run init --output snapi.config.json",
+    "api:snapshot": "pnpm --filter=snapi run build && pnpm --filter=snapi run snapshot",
+    "api:suppress": "pnpm --filter=snapi run build && pnpm --filter=snapi run suppress",
     "build": "FORCE_COLOR=1 turbo build --concurrency=${TURBO_CONCURRENCY:-80%}",
     "build:declarations": "FORCE_COLOR=1 turbo build:declarations --concurrency=${TURBO_CONCURRENCY:-80%} --filter=@clerk/nextjs --filter=@clerk/clerk-react --filter=@clerk/shared --filter=@clerk/types",
     "bundlewatch": "turbo bundlewatch",