feat(DEVA11Y-657): automatic PR trigger, honest inputs, real outputs + severity gate

Addresses review feedback (inputs must be real, not for show; guide users to the
automatic detection flow; VS Code output format) and the flag audit.

action.yml:
- Automatic flow (primary): trigger on pull_request opened/synchronize/reopened/
  ready_for_review (actor = PR author, no commenter gate). Manual @mention stays
  as the secondary flow (with the commenter permission pre-check).
- Trim inputs to the ones that do something: username, access-key,
  fail-on-severity. Removed comment / check-gate / comment-mode /
  inline-suggestions / sarif (now always-on server defaults) and
  remediation / ai-agent (deferred preview). check-gate is folded into
  fail-on-severity (none = never fail).
- Real gate + outputs: parse the CLI's `[deva11y-result]` line into
  error-count / warning-count / findings-count / comment-url, and fail the run
  per fail-on-severity (a real `warning` gate, and `error` actually fails now —
  previously --pr-scan always exited 0 so the check never failed). Operational
  errors (FUP/permission/error) always fail. Dropped the sarif-file output
  (SARIF is uploaded server-side; there is no local file).

README + example:
- Automatic-first quick start (on: pull_request + issue_comment), @main (no v1 pin).
- Inputs/outputs tables reflect reality; describe what actually gets posted
  (sticky comment, inline comments in VS Code format, Check Run, SARIF).
- Inline are review comments, not one-click suggestion blocks (findings carry
  how-to-fix text, not literal replacement code) — corrected the earlier claim.
- Single support link; removed the internal-note remediation section.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: Crash0v3rrid3

README.md

@@ -1,15 +1,15 @@
 # BrowserStack Accessibility DevTools for GitHub
 
-Catch accessibility issues on your pull requests. Comment
-**`@AccessibilityDevTools`** on a PR and BrowserStack scans the changed code,
-then posts the findings right back on the PR — as a summary comment, inline
-suggestions, and an optional merge check.
+Catch accessibility issues on your pull requests. BrowserStack scans the changed
+code on every PR and posts the findings right back on the PR — a summary comment,
+inline comments on the offending lines, a merge check, and a SARIF upload to the
+Security tab.
 
 - 🔎 **Scans only what changed** in the PR (fast, even on large repos).
-- 💬 **Results on the PR** — a summary comment and inline, one‑click suggestions.
-- ✅ **Optional merge gate** — fail the check when accessibility errors are found.
-- 🤖 **Optional agent hand‑off (preview)** — the findings comment can `@mention` a PR
-  agent you already use, which then acts under _your_ credentials.
+- 💬 **Results on the PR** — a sticky summary comment and inline comments.
+- ✅ **Merge gate** — fail the check when accessibility issues are found (configurable).
+- 🔐 **Zero write credentials on your runner** — every write is posted by the
+  BrowserStack Accessibility App; your workflow's `GITHUB_TOKEN` stays read-only.
 
 Learn more: <https://www.browserstack.com/docs/accessibility-dev-tools/features/remediate-github>
 
@@ -18,19 +18,24 @@ Learn more: <https://www.browserstack.com/docs/accessibility-dev-tools/features/
 ## Prerequisites
 
 1. **Install the BrowserStack Accessibility GitHub App** on your organization or
-   repository (a one‑time step, done by a repo/org admin).
+   repository (a one-time step, done by a repo/org admin).
 2. **Add a BrowserStack Service Account key** as repository or organization
    **Actions secrets**:
    - `BROWSERSTACK_USERNAME`
    - `BROWSERSTACK_ACCESS_KEY`
 
 ## Quick start
 
-Add `.github/workflows/browserstack-a11y.yml`:
+Add `.github/workflows/browserstack-a11y.yml`. It runs **automatically on every
+pull request**, and can also be re-run on demand by commenting
+`@AccessibilityDevTools` on the PR:
 
 ```yaml
 name: BrowserStack Accessibility DevTools
+
 on:
+  pull_request:
+    types: [opened, synchronize, reopened, ready_for_review]
   issue_comment:
     types: [created]
 
@@ -40,101 +45,69 @@ permissions:
   id-token: write # prove the run came from your CI (required)
 
 concurrency:
-  group: a11y-${{ github.event.issue.number }}
+  group: a11y-${{ github.event.pull_request.number || github.event.issue.number }}
   cancel-in-progress: true
 
 jobs:
   a11y:
-    # Fires on a PR comment mentioning @AccessibilityDevTools. The action then verifies
-    # the commenter has write/maintain/admin permission before scanning.
     if: >
-      github.event.issue.pull_request &&
-      contains(github.event.comment.body, '@AccessibilityDevTools')
+      github.event_name == 'pull_request' ||
+      (github.event.issue.pull_request &&
+       contains(github.event.comment.body, '@AccessibilityDevTools'))
     runs-on: ubuntu-latest
     timeout-minutes: 15
     steps:
       - uses: browserstack/browserstack-accessibility-devtools-action@main
         with:
           username: ${{ secrets.BROWSERSTACK_USERNAME }}
           access-key: ${{ secrets.BROWSERSTACK_ACCESS_KEY }}
-          comment: true
-          check-gate: true
           fail-on-severity: error
-          # inline-suggestions: true
-          # sarif: true
-          # comment-mode: update
-          # remediation: true       # preview; off by default
-          # ai-agent: coderabbitai  # bare name; the App posts "@coderabbitai"
-```
-
-Then, on any pull request, comment:
-
-```
-@AccessibilityDevTools
 ```
 
-The scan runs and results appear on the PR within a couple of minutes.
+That's it — open a PR and the results appear within a couple of minutes. To
+re-run manually, comment `@AccessibilityDevTools` on the PR.
 
 ## How it works
 
-1. You comment **`@AccessibilityDevTools`** on the PR.
-2. The workflow runs BrowserStack's accessibility CLI against the PR's changed
-   files, authenticated by your Service Account key.
-3. Results are posted back to the PR **by the BrowserStack Accessibility App**
-   (a branded bot), so your workflow's default token never needs write access.
+1. On a pull request (or an `@AccessibilityDevTools` comment), the workflow runs
+   BrowserStack's accessibility CLI against the PR's changed files, authenticated
+   by your Service Account key.
+2. Results are posted back to the PR **by the BrowserStack Accessibility App** (a
+   branded bot), so your workflow's default token never needs write access.
 
-> **Why `id-token: write`?** GitHub mints a short‑lived, repo‑scoped OpenID
+> **Why `id-token: write`?** GitHub mints a short-lived, repo-scoped OpenID
 > Connect token that proves the request genuinely came from this repository's CI
 > run. BrowserStack verifies it before posting. It carries **no** personal
 > identity and grants no standing access.
 
+## What gets posted
+
+On every scan the App posts, automatically:
+
+- a **sticky summary comment** (one per PR, updated in place across runs);
+- **inline comments** on the offending lines, in the same format as the
+  BrowserStack VS Code extension: `(rule): <description>` followed by how to fix it;
+- a **Check Run** with the pass/fail result;
+- a **SARIF upload** to GitHub code scanning (Security tab).
+
 ## Inputs
 
-| Input                | Default  | Description                                                                                                                              |
-| -------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
-| `username`           | —        | **Required.** Service Account username (store as a secret).                                                                              |
-| `access-key`         | —        | **Required.** Service Account access key (store as a secret).                                                                            |
-| `comment`            | `true`   | Post a summary findings comment on the PR.                                                                                               |
-| `check-gate`         | `true`   | Publish a Check Run / commit status for the PR.                                                                                          |
-| `fail-on-severity`   | `error`  | Fail the check at this severity and above: `error`, `warning`, or `none`.                                                                |
-| `inline-suggestions` | `false`  | Add one‑click suggestion blocks on offending lines.                                                                                      |
-| `sarif`              | `false`  | Publish results to GitHub code scanning (Security tab). Uploaded by the App server-side — your workflow token needs no extra permission. |
-| `comment-mode`       | `update` | `update` a single sticky comment across runs, or post a `new` one each time.                                                             |
-| `remediation`        | `false`  | Enable the optional agent hand‑off (preview; see below).                                                                                 |
-| `ai-agent`           | —        | Required when `remediation: true`. The agent's name (e.g. `coderabbitai`, `claude`); we @‑mention it.                                    |
+| Input              | Default | Description                                                                                             |
+| ------------------ | ------- | ------------------------------------------------------------------------------------------------------- |
+| `username`         | —       | **Required.** Service Account username (store as a secret).                                             |
+| `access-key`       | —       | **Required.** Service Account access key (store as a secret).                                           |
+| `fail-on-severity` | `error` | Fail the check when findings at/above this severity exist: `error`, `warning`, or `none` (never fails). |
 
 ## Outputs
 
 | Output           | Description                          |
 | ---------------- | ------------------------------------ |
 | `result`         | `pass` or `fail`.                    |
-| `error-count`    | Number of error‑severity findings.   |
-| `warning-count`  | Number of warning‑severity findings. |
+| `error-count`    | Number of error-severity findings.   |
+| `warning-count`  | Number of warning-severity findings. |
 | `findings-count` | Total findings.                      |
-| `comment-url`    | Link to the posted PR comment.       |
-| `sarif-file`     | Path to the SARIF file (if enabled). |
-
-## Optional: agent hand‑off (preview)
-
-Set `remediation: true` and name your agent with `ai-agent`. When findings are
-posted, the App `@mentions` that agent on the PR (for example, `@coderabbitai`), and
-**your** agent acts under **your** credentials and billing.
-
-**Prerequisite:** if your agent ignores bot authors by default, allow‑list the
-**BrowserStack Accessibility** bot in its configuration.
-
-```yaml
-with:
-  username: ${{ secrets.BROWSERSTACK_USERNAME }}
-  access-key: ${{ secrets.BROWSERSTACK_ACCESS_KEY }}
-  remediation: true
-  ai-agent: coderabbitai # BrowserStack posts "@coderabbitai"
-```
-
-> This feature is a preview and is off by default. Hand‑off is supported only if
-> your AI agent accepts triggers from a bot/App comment; behaviour varies by agent,
-> and it is a silent no‑op if the agent isn't configured to accept it.
+| `comment-url`    | Link to the posted PR summary comment. |
 
 ## Support
 
-- <https://www.browserstack.com/support>
+<https://www.browserstack.com/support>