chore: Backport #40 and #43 to v2

CONTRIBUTING.md

@@ -1,4 +1,4 @@
-## Contributing
+# Contributing
 
 [fork]: https://github.com/github/accessibility-scanner/fork
 [pr]: https://github.com/github/accessibility-scanner/compare
@@ -9,13 +9,29 @@ Contributions to this project are [released](https://help.github.com/articles/gi
 
 Please note that this project is released with a [Contributor Code of Conduct](CODE_OF_CONDUCT.md). By participating in this project you agree to abide by its terms.
 
-## Submitting a pull request
+## How you can contribute
 
-Thank you for your interest in this GitHub action, however, right now we are not taking contributions.
+We are not accepting pull requests at this time. However, we welcome and encourage you to:
 
+- **Test the a11y scanner** and share your experiences
+- **Create issues** to report bugs, unexpected behavior, or documentation improvements
+- **Share feedback** about your use cases and workflows
+
+### Creating issues
+
+When creating an issue, please provide:
+
+- A clear and descriptive title
+- Detailed steps to reproduce (for bugs)
+- Expected vs. actual behavior
+- Your environment details (OS, browser, GitHub Actions runner, etc.)
+- Any relevant logs or screenshots
+
+### Feature requests
+
+While we welcome feature requests, please note that we cannot guarantee that any feature request will be implemented or prioritized. We review all suggestions and consider them as part of our ongoing development process.
 
 ## Resources
 
 - [How to Contribute to Open Source](https://opensource.guide/how-to-contribute/)
-- [Using Pull Requests](https://help.github.com/articles/about-pull-requests/)
 - [GitHub Support](https://support.github.com)

README.md

@@ -1,29 +1,36 @@
 # AI-powered Accessibility Scanner
 
-The AI-powered Accessibility Scanner (a11y scanner) is a GitHub Action that detects accessibility barriers across your digital products, creates trackable issues, and leverages Copilot for AI-powered fixes.
+The AI-powered Accessibility Scanner (a11y scanner) is a GitHub Action that detects accessibility barriers across your digital products, creates trackable issues, and leverages GitHub Copilot for AI-powered fixes.
 
 The a11y scanner helps teams:
 
 - 🔍 Scan websites, files, repositories, and dynamic content for accessibility issues
-- 📝 Create actionable GitHub issues that can be assigned to Copilot
-- 🤖 Propose fixes with Copilot, with humans reviewing before merging
+- 📝 Create actionable GitHub issues that can be assigned to GitHub Copilot
+- 🤖 Propose fixes with GitHub Copilot, with humans reviewing before merging
 
-> ⚠️ **Note:** The a11y scanner is currently in beta. It can help identify accessibility gaps but cannot guarantee fully accessible code suggestions. Always review before merging!
+> ⚠️ **Note:** The a11y scanner is currently in public preview. Feature development work is still ongoing. It can help identify accessibility gaps but cannot guarantee fully accessible code suggestions. Always review before merging!
+
+🎥 **[Watch the demo video](https://youtu.be/CvRJcEzCSQM)** to see the a11y scanner in action.
 
 ---
 
 ## Requirements
 
-This project is a GitHub Actions action. A GitHub Actions workflow is required to run it, and you must have available GitHub Actions minutes.
+To use the a11y scanner, you'll need:
+
+- **GitHub Actions** enabled in your repository
+- **GitHub Issues** enabled in your repository
+- **Available GitHub Actions minutes** for your account
+- **Admin access** to add repository secrets
+- **GitHub Copilot** (optional) - The a11y scanner works without GitHub Copilot and will still create issues for accessibility findings. However, without GitHub Copilot, you won't be able to automatically assign issues to GitHub Copilot for AI-powered fix suggestions and PR creation.
 
-📚 [Understanding GitHub Actions](https://docs.github.com/en/actions/get-started/understand-github-actions) | [Quickstart for GitHub Actions](https://docs.github.com/en/actions/get-started/quickstart) | [Writing workflows](https://docs.github.com/en/actions/how-tos/write-workflows) | [GitHub Actions billing](https://docs.github.com/en/billing/concepts/product-billing/github-actions)
-## Getting Started
+## Getting started
 
-### 1. Add a Workflow File
+### 1. Add a workflow file
 
 Create a workflow file in `.github/workflows/` (e.g., `a11y-scan.yml`) in your repository:
 
-```YAML
+```yaml
 name: Accessibility Scanner
 on: workflow_dispatch # This configures the workflow to run manually, instead of (e.g.) automatically in every PR. Check out https://docs.github.com/en/actions/reference/workflows-and-actions/workflow-syntax#on for more options.
 
@@ -36,49 +43,64 @@ jobs:
           urls: | # Provide a newline-delimited list of URLs to scan; more information below.
             REPLACE_THIS
           repository: REPLACE_THIS/REPLACE_THIS # Provide a repository name-with-owner (in the format "primer/primer-docs"). This is where issues will be filed and where Copilot will open PRs; more information below.
-          token: ${{ secrets.GH_TOKEN }} # This token must have write access to the repo above (contents, issues, and PRs); more information below. Note: GitHub Actions’ `GITHUB_TOKEN` (https://docs.github.com/en/actions/tutorials/authenticate-with-github_token) cannot be used here.
-          cache_key: REPLACE_THIS # Provide a filename that will be used when caching results. We recommend including the name or domain of the site being scanning.
+          token: ${{ secrets.GH_TOKEN }} # This token must have write access to the repo above (contents, issues, and PRs); more information below. Note: GitHub Actions' GITHUB_TOKEN cannot be used here.
+          cache_key: REPLACE_THIS # Provide a filename that will be used when caching results. We recommend including the name or domain of the site being scanned.
+          # login_url: # Optional: URL of the login page if authentication is required
+          # username: # Optional: Username for authentication
+          # password: ${{ secrets.PASSWORD }} # Optional: Password for authentication (use secrets!)
+          # auth_context: # Optional: Stringified JSON object for complex authentication
+          # skip_copilot_assignment: false # Optional: Set to true to skip assigning issues to GitHub Copilot (or if you don't have GitHub Copilot)
 ```
 
 > 👉 Update all `REPLACE_THIS` placeholders with your actual values. See [Action Inputs](#action-inputs) for details.
 
-Required Permissions:
+**Required permissions:**
 
 - Write access to add or update workflows
 - Admin access to add repository secrets
 
-📚 [Understanding GitHub Actions](https://docs.github.com/en/actions/get-started/understand-github-actions) | [Managing GitHub Actions settings](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-github-actions-settings-for-a-repository) | [Writing workflows](https://docs.github.com/en/actions/how-tos/write-workflows)
+📚 Learn more
+- [Quickstart for GitHub Actions](https://docs.github.com/en/actions/get-started/quickstart)
+- [Understanding GitHub Actions](https://docs.github.com/en/actions/get-started/understand-github-actions)
+- [Writing workflows](https://docs.github.com/en/actions/how-tos/write-workflows)
+- [Managing GitHub Actions settings](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-github-actions-settings-for-a-repository)
+- [GitHub Actions billing](https://docs.github.com/en/billing/concepts/product-billing/github-actions)
 
 ---
 
-### 2. Create a Token and Add a Secret
+### 2. Create a token and add a secret
 
-The a11y scanner requires a Personal Access Token (PAT) as repository secret:
+The a11y scanner requires a Personal Access Token (PAT) as a repository secret:
 
-#### The `GH_TOKEN` is a fine-grained PAT with
+**The `GH_TOKEN` is a fine-grained PAT with:**
 
 - `actions: write`
 - `contents: write`
 - `issues: write`
 - `pull-requests: write`
 - `metadata: read`
-- Scope: Your target repository (where issues and PRs will be created) and the repository containing your workflow
+- **Scope:** Your target repository (where issues and PRs will be created) and the repository containing your workflow
 
-> 👉 GitHub Actions' default `GITHUB_TOKEN` cannot be used here.
+> 👉 GitHub Actions' default [GITHUB_TOKEN](https://docs.github.com/en/actions/tutorials/authenticate-with-github_token) cannot be used here.
 
-📚 [Creating a fine-grained PAT](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token) | [Creating repository secrets](https://docs.github.com/en/actions/how-tos/write-workflows/choose-what-workflows-do/use-secrets#creating-secrets-for-a-repository)
+📚 Learn more
+- [Creating a fine-grained PAT](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token)
+- [Creating repository secrets](https://docs.github.com/en/actions/how-tos/write-workflows/choose-what-workflows-do/use-secrets#creating-secrets-for-a-repository)
 
 ---
 
-### 3. Run Your First Scan
+### 3. Run your first scan
 
-Trigger the workflow manually or automatically based on your configuration. The scanner will run and create issues for any accessibility findings. When issues are assigned to Copilot, always review proposed fixes before merging.
+Trigger the workflow manually or automatically based on your configuration. The a11y scanner will run and create issues for any accessibility findings. When issues are assigned to GitHub Copilot, always review proposed fixes before merging.
 
-📚 [Running a workflow manually](https://docs.github.com/en/actions/how-tos/manage-workflow-runs/manually-run-a-workflow#running-a-workflow)
+📚 Learn more
+- [View workflow run history](https://docs.github.com/en/actions/how-tos/monitor-workflows/view-workflow-run-history)
+- [Running a workflow manually](https://docs.github.com/en/actions/how-tos/manage-workflow-runs/manually-run-a-workflow#running-a-workflow)
+- [Re-run workflows and jobs](https://docs.github.com/en/actions/how-tos/manage-workflow-runs/re-run-workflows-and-jobs)
 
 ---
 
-## Action Inputs
+## Action inputs
 
 | Input | Required | Description | Example |
 |-------|----------|-------------|---------|
@@ -88,54 +110,54 @@ Trigger the workflow manually or automatically based on your configuration. The
 | `cache_key` | Yes | Key for caching results across runs<br>Allowed: `A-Za-z0-9._/-` | `cached_results-primer.style-main.json` |
 | `login_url` | No | If scanned pages require authentication, the URL of the login page | `https://github.com/login` |
 | `username` | No | If scanned pages require authentication, the username to use for login | `some-user` |
-| `password` | No | If scanned pages require authentication, the password to use for login | `correct-horse-battery-staple` |
-| `auth_context` | No | If scanned pages require authentication, a stringified JSON object containing username, password, cookies, and/or localStorage from an authenticated session | `{"username":"some-user","password":"correct-horse-battery-staple","cookies":[{"name":"theme-preference","value":"light","domain":"primer.style","path":"/"}],"localStorage":{"https://primer.style":{"theme-preference":"light"}}}` |
-| `skip_copilot_assignment` | No | Whether to skip assigning filed issues to Copilot | `true` |
+| `password` | No | If scanned pages require authentication, the password to use for login | `${{ secrets.PASSWORD }}` |
+| `auth_context` | No | If scanned pages require authentication, a stringified JSON object containing username, password, cookies, and/or localStorage from an authenticated session | `{"username":"some-user","password":"***","cookies":[...]}` |
+| `skip_copilot_assignment` | No | Whether to skip assigning filed issues to GitHub Copilot. Set to `true` if you don't have GitHub Copilot or prefer to handle issues manually | `true` |
 
 ---
 
 ## Authentication
 
 If access to a page requires logging-in first, and logging-in requires only a username and password, then provide the `login_url`, `username`, and `password` inputs.
 
-If your login flow is more complex—if it requires two-factor authentication, single sign-on, passkeys, etc.–and you have a custom action that [authenticates with Playwright](https://playwright.dev/docs/auth) and persists authenticated session state to a file, then provide the `auth_context` input. (If `auth_context` is provided, `login_url`, `username`, and `password` will be ignored.)
+If your login flow is more complex—if it requires two-factor authentication, single sign-on, passkeys, etc.—and you have a custom action that [authenticates with Playwright](https://playwright.dev/docs/auth) and persists authenticated session state to a file, then provide the `auth_context` input. (If `auth_context` is provided, `login_url`, `username`, and `password` will be ignored.)
 
 > [!IMPORTANT]
-> Don’t put passwords in your workflow as plain text; instead reference a [repository secret](https://docs.github.com/en/actions/how-tos/write-workflows/choose-what-workflows-do/use-secrets#creating-secrets-for-a-repository).
+> Don't put passwords in your workflow as plain text; instead reference a [repository secret](https://docs.github.com/en/actions/how-tos/write-workflows/choose-what-workflows-do/use-secrets#creating-secrets-for-a-repository).
 
 ---
 
-## Configuring Copilot
+## Configuring GitHub Copilot
 
-The a11y scanner leverages Copilot coding agent, which can be configured with custom instructions:
+The a11y scanner leverages GitHub Copilot coding agent, which can be configured with custom instructions:
 
-- Repository-wide: `.github/copilot-instructions.md`
-- Directory/file-scoped: `.github/instructions/*.instructions.md`
+- **Repository-wide:** `.github/copilot-instructions.md`
+- **Directory/file-scoped:** `.github/instructions/*.instructions.md`
 
-📚 [Adding repository custom instructions](https://docs.github.com/en/copilot/how-tos/configure-custom-instructions/add-repository-instructions) | [Copilot .instructions.md support](https://github.blog/changelog/2025-07-23-github-copilot-coding-agent-now-supports-instructions-md-custom-instructions/) | [Copilot agents.md support](https://github.blog/changelog/2025-08-28-copilot-coding-agent-now-supports-agents-md-custom-instructions)
+📚 Learn more
+- [Adding repository custom instructions](https://docs.github.com/en/copilot/how-tos/configure-custom-instructions/add-repository-instructions)
+- [Optimizing GitHub Copilot for accessibility](https://accessibility.github.com/documentation/guide/copilot-instructions)
+- [GitHub Copilot .instructions.md support](https://github.blog/changelog/2025-07-23-github-copilot-coding-agent-now-supports-instructions-md-custom-instructions/)
+- [GitHub Copilot agents.md support](https://github.blog/changelog/2025-08-28-copilot-coding-agent-now-supports-agents-md-custom-instructions)
 
 ---
 
 ## Feedback
 
-Please refer to the [CONTRIBUTING](./CONTRIBUTING.md) file for more information.
+💬 We welcome your feedback! To submit feedback or report issues, please create an issue in this repository. For more information on contributing, please refer to the [CONTRIBUTING](./CONTRIBUTING.md) file.
 
 ## License 
 
-This project is licensed under the terms of the MIT open source license. Please refer to the [LICENSE](./LICENSE) file for the full terms.
+📄 This project is licensed under the terms of the MIT open source license. Please refer to the [LICENSE](./LICENSE) file for the full terms.
 
 ## Maintainers 
 
-Please refer to the [CODEOWNERS](./.github/CODEOWNERS) file for more information.
+🔧 Please refer to the [CODEOWNERS](./.github/CODEOWNERS) file for more information.
 
 ## Support
 
-Please refer to the [SUPPORT](./SUPPORT.md) file for more information.
+❓ Please refer to the [SUPPORT](./SUPPORT.md) file for more information.
 
 ## Acknowledgement
 
-Thank you to our beta testers for their help in testing this project.
-
----
-
-*Last updated: 2025-10-09*
+✨ Thank you to our beta testers for their help with making this project!

SUPPORT.md

@@ -1,19 +1,21 @@
 # Support
 
-## How to file issues and get help
+## How to get help
 
-This project uses GitHub Issues to track bugs and feature requests. Please search the existing issues before filing new issues to avoid duplicates. For new issues, file your bug or feature request as a new issue.
+This project uses GitHub Issues to track bugs, feature requests, and support inquiries. Please search the existing issues before filing new issues to avoid duplicates.
 
 For help or questions about using this project, please open an issue for support requests, usage questions, or general inquiries. At this time, GitHub Discussions are not enabled. All communication should occur via issues.
 
-## Project Maintenance Status
+For information about contributing to this project, including how to create issues and what types of contributions we accept, please refer to the [CONTRIBUTING](./CONTRIBUTING.md) file.
+
+## Project maintenance status
 
 This repo `github/accessibility-scanner` is under active development and maintained by GitHub staff during the public preview state. We will do our best to respond to support, feature requests, and community questions in a timely manner.
 
-## Important Notice
+## Important notice
 
-This project is a work in progress, and we do not guarantee that code fixes or suggestions produced by Copilot will be fully accessible. Please use caution when applying the suggestions it provides. Always confirm or verify Copilot's recommendations with an accessibility subject matter expert before using them in production.
+The a11y scanner is currently in public preview and feature development work is still ongoing. This project cannot guarantee that code fixes or suggestions produced by GitHub Copilot will be fully accessible. Please use caution when applying the suggestions it provides. Always confirm or verify GitHub Copilot's recommendations with an accessibility subject matter expert before using them in production.
 
-## GitHub Support Policy
+## GitHub support policy
 
 Support for this project is limited to the resources listed above (GitHub Issues).