@@ -0,0 +1,38 @@
+# PR gate for the composite action. Keeps action.yml + example/workflow YAML
+# structurally valid on every change so a broken action can't merge.
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Validate YAML is well-formed
+        shell: bash
+        run: |
+          set -euo pipefail
+          for f in action.yml examples/*.yml .github/workflows/*.yml; do
+            python3 -c "import sys,yaml; list(yaml.safe_load_all(open('$f')))" \
+              && echo "ok: $f" || { echo "invalid YAML: $f"; exit 1; }
+          done
+
+      - name: Validate action.yml structure
+        shell: bash
+        run: |
+          set -euo pipefail
+          test -f action.yml || { echo "action.yml missing"; exit 1; }
+          for key in name description runs inputs outputs; do
+            grep -qE "^${key}:" action.yml || { echo "action.yml missing '${key}:'"; exit 1; }
+          done
+          grep -qE "using: 'composite'|using: composite" action.yml \
+            || { echo "action.yml must be a composite action"; exit 1; }
+          echo "action.yml is structurally valid."
@@ -0,0 +1,76 @@
+# Release pipeline for the BrowserStack Accessibility DevTools Action.
+#
+# v1 is a composite action (action.yml) that shells out to bash + the published
+# CLI, so there is nothing to bundle yet. This pipeline is a STUB that:
+#   - builds any bundled `dist/` if/when the action gains JS entrypoints (esbuild),
+#   - verifies action.yml is valid,
+#   - documents the (manual, admin-only) Marketplace publish step.
+#
+# Marketplace publishing needs a GitHub ORG ADMIN and is intentionally NOT
+# automated here (see the "publish" job note below).
+name: Release
+
+on:
+  push:
+    tags:
+      - 'v*'
+  workflow_dispatch:
+    inputs:
+      version:
+        description: 'Release version tag (e.g. v1.0.0)'
+        required: true
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+
+      # Bundle a dist/ IF the action grows JS entrypoints (esbuild pattern).
+      # Guarded so the stub is a no-op for the current pure-composite action.
+      - name: Build bundled dist (esbuild)
+        shell: bash
+        run: |
+          set -euo pipefail
+          if [ -f package.json ] && jq -e '.scripts.build' package.json >/dev/null 2>&1; then
+            npm ci
+            # Example bundling target for a future JS action entrypoint:
+            #   npx esbuild src/index.ts --bundle --platform=node \
+            #     --target=node20 --outfile=dist/index.js
+            npm run build
+            echo "Bundled dist/ produced."
+          else
+            echo "No package.json build script — pure composite action, nothing to bundle."
+          fi
+
+      - name: Validate action.yml
+        shell: bash
+        run: |
+          set -euo pipefail
+          test -f action.yml || { echo "action.yml missing"; exit 1; }
+          # Minimal structural sanity: required top-level keys present.
+          for key in name description runs inputs outputs; do
+            grep -qE "^${key}:" action.yml || { echo "action.yml missing '${key}:'"; exit 1; }
+          done
+          echo "action.yml looks structurally valid."
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    steps:
+      - name: Marketplace publish (manual, org-admin only)
+        shell: bash
+        run: |
+          echo "GitHub Marketplace publishing is a MANUAL step and requires a GitHub org admin."
+          echo "Steps (performed in the GitHub UI by an admin):"
+          echo "  1. Draft a release for the pushed tag."
+          echo "  2. Tick 'Publish this Action to the GitHub Marketplace'."
+          echo "  3. Select category (Code quality / Utilities), accept the agreement, publish."
+          echo "This job is a placeholder and does not publish automatically."
@@ -0,0 +1,6 @@
+node_modules/
+*.log
+.DS_Store
+.env
+# Bundled output is produced by the release pipeline when/if JS entrypoints land.
+dist/
@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 BrowserStack
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
@@ -1,2 +1,124 @@
-# browserstack-accessibility-devtools-action
-A package to support Accessibility Devtools Action
+# BrowserStack Accessibility DevTools for GitHub
+
+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 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>
+
+---
+
+## Prerequisites
+
+1. **Install the BrowserStack Accessibility GitHub App** on your organization or
+   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`. 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]
+
+permissions:
+  contents: read # read the PR's changed files
+  pull-requests: read # resolve the PR
+  id-token: write # prove the run came from your CI (required)
+
+concurrency:
+  group: a11y-${{ github.event.pull_request.number || github.event.issue.number }}
+  cancel-in-progress: true
+
+jobs:
+  a11y:
+    if: >
+      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 }}
+          fail-on-severity: error
+```
+
+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. 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
+> 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).                                           |
+| `fail-on-severity` | `error` | Fail the check when findings at/above this severity exist: `error`, `warning`, or `none` (never fails). |
+| `ai-agent`         | —       | Optional. Bare agent name to `@mention` for AI remediation hand-off — see below.                        |
+
+## Outputs
+
+| Output           | Description                          |
+| ---------------- | ------------------------------------ |
+| `result`         | `pass` or `fail`.                    |
+| `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 summary comment. |
+
+## AI remediation hand-off
+
+Set `ai-agent` to the bare name of an agent you already use (e.g. `coderabbitai`).
+When findings are posted, the App `@mentions` it on the comment, and your agent
+acts under **your** own credentials and billing.
+
+> This feature will be supported 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.
+
+## Support
+
+<https://www.browserstack.com/support>