diff --git a/.github/workflows/update-openapi.yml b/.github/workflows/update-openapi.yml
deleted file mode 100644
index 5aab78ef0..000000000
--- a/.github/workflows/update-openapi.yml
+++ /dev/null
@@ -1,40 +0,0 @@
-name: Update OpenAPI JSON
-
-on:
-  push:
-    paths:
-      - 'app/Http/Controllers/Api/**/*.php'
-      - 'app/OpenApi/**/*.php'
-
-jobs:
-  update-openapi:
-    runs-on: ubuntu-24.04
-
-    steps:
-    - name: Checkout repository
-      uses: actions/checkout@v5
-      with:
-        ref: ${{ github.event.pull_request.head.ref }}
-        repository: ${{ github.event.pull_request.head.repo.full_name }}
-
-    - name: Set up PHP
-      uses: shivammathur/setup-php@v2
-      with:
-        php-version: '8.3'
-
-    - name: Install dependencies
-      run: composer install -q --no-ansi --no-interaction --no-scripts --no-progress
-
-    - name: Generate OpenAPI JSON
-      run: ./vendor/bin/openapi ./app/Http/Controllers/Api ./app/OpenApi -o openapi_temp.json -f json
-
-    - name: Commit OpenAPI JSON if changed
-      run: |
-        if ! diff -q openapi.json openapi_temp.json; then
-          mv openapi_temp.json openapi.json
-          git config user.name "GitHub Action"
-          git config user.email "actions@github.com"
-          git add openapi.json
-          git commit -m "Update OpenAPI JSON"
-          git push
-        fi
diff --git a/.github/workflows/validate-openapi.yml b/.github/workflows/validate-openapi.yml
new file mode 100644
index 000000000..751ca222d
--- /dev/null
+++ b/.github/workflows/validate-openapi.yml
@@ -0,0 +1,49 @@
+name: Validate OpenAPI JSON
+
+on:
+  pull_request:
+    paths:
+      - 'app/Http/Controllers/Api/**/*.php'
+      - 'app/OpenApi/**/*.php'
+
+jobs:
+  update-openapi:
+    runs-on: ubuntu-24.04
+
+    steps:
+      - name: Checkout PR branch
+        uses: actions/checkout@v5
+        with:
+          fetch-depth: 0
+          ref: ${{ github.event.pull_request.head.ref }}
+          repository: ${{ github.event.pull_request.head.repo.full_name }}
+
+      - name: Set up PHP
+        uses: shivammathur/setup-php@v2
+        with:
+          php-version: '8.4'
+
+      - name: Install dependencies
+        run: composer install -q --no-ansi --no-interaction --no-scripts --no-progress
+
+      # Generate OpenAPI file into a temp location
+      - name: Generate OpenAPI JSON
+        run: ./vendor/bin/openapi ./app/Http/Controllers/Api ./app/OpenApi -o openapi_temp.json -f json
+
+      # Compare the generated file to the committed file
+      - name: Validate OpenAPI JSON is up to date
+        run: |
+          if ! diff -q openapi.json openapi_temp.json; then
+            echo "❌ OpenAPI documentation is out of sync!"
+            echo ""
+            echo "API code was modified but openapi.json was NOT updated."
+            echo ""
+            echo "Please regenerate the OpenAPI JSON and commit it:"
+            echo "    ./vendor/bin/openapi ./app/Http/Controllers/Api ./app/OpenApi -o openapi.json -f json"
+            echo ""
+            exit 1
+          fi
+
+      - name: ✓ OpenAPI is up to date
+        if: success()
+        run: echo "✅ OpenAPI documentation matches the committed version!"
\ No newline at end of file