Add helpful error for missing permissions

When the upload returns 403, surface a clear message telling the
caller to set security-events:write on their job, with a link to
the README's permissions section.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

action.yml

@@ -72,7 +72,15 @@ runs:
             && mv __body_tmp.json __body.json
         fi
 
-        gh api --method PUT "/repos/${{ github.repository }}/code-coverage/report" \
-          --input __body.json
+        UPLOAD_OUTPUT=$(gh api --method PUT "/repos/${{ github.repository }}/code-coverage/report" \
+          --input __body.json 2>&1) || {
+          if echo "$UPLOAD_OUTPUT" | grep -qi "not authorized"; then
+            echo "::error::Coverage upload returned 403 Forbidden. Ensure the calling job has 'security-events: write' permission. See https://github.com/code-quality-org/upload-code-coverage-action#permissions"
+          else
+            echo "::error::Coverage upload failed: $UPLOAD_OUTPUT"
+          fi
+          rm -f __coverage_b64.txt __body.json
+          exit 1
+        }
 
         rm -f __coverage_b64.txt __body.json