docs: add CONTRIBUTING.md and AGENTS.md

AGENTS.md

@@ -0,0 +1,78 @@
+# Agentic Coding Guide
+
+This file provides guidance for AI coding agents working in this repository.
+
+## Repository Purpose
+
+`setup-chrome` is a GitHub Action that installs Google Chrome, Chromium, and optionally ChromeDriver on GitHub Actions runners. It supports stable/beta/dev/canary channels, specific version numbers, commit positions (snapshot builds), and the latest snapshot.
+
+## Commands
+
+```bash
+pnpm install --frozen-lockfile   # install dependencies
+pnpm lint                        # lint with Biome (CI mode, no auto-fix)
+pnpm lint:fix                    # lint with auto-fix
+pnpm test                        # run all unit tests with Vitest
+pnpm test -- --reporter=verbose  # verbose test output
+npx vitest run __test__/<file>.test.ts  # run a single test file
+pnpm build                       # compile TypeScript → dist/index.js
+pnpm package                     # copy action.yml + README.md into dist/
+```
+
+## Project Layout
+
+```
+src/
+  index.ts              # action entry point: reads inputs, selects installer, sets outputs
+  installer.ts          # Installer interface (checkInstalled, download, install for browser+driver)
+  version.ts            # version string parser → typed spec (latest | channel | snapshot | four-parts)
+  platform.ts           # OS/arch detection → Platform struct
+  latest_installer.ts   # installs the latest snapshot build
+  snapshot_installer.ts # installs a specific snapshot by commit position
+  version_installer.ts  # installs a known-good version via Chrome for Testing API
+  channel_linux.ts      # channel installer for Linux (stable/beta/dev/canary)
+  channel_macos.ts      # channel installer for macOS
+  channel_windows.ts    # channel installer for Windows
+  chrome_for_testing.ts # client for the Chrome for Testing JSON API
+  snapshot_bucket.ts    # client for the Chromium snapshot GCS bucket
+  cache.ts              # tool-cache helpers for caching installed binaries
+  dependencies.ts       # install system dependencies on Linux (apt)
+__test__/
+  *.test.ts             # Vitest unit tests, one file per source module
+  data/                 # JSON fixtures for API responses (excluded from linting)
+action.yml              # action metadata: inputs, outputs, runs.using: node24
+biome.json              # linter/formatter config (space indent; useLiteralKeys and noUselessElse off)
+```
+
+## Architecture
+
+Version resolution follows a strategy pattern. `version.ts` parses the input string into one of four types, and `index.ts` selects the appropriate `Installer` implementation:
+
+| Version spec        | Installer class               | Source                    |
+|---------------------|-------------------------------|---------------------------|
+| `latest`            | `LatestInstaller`             | Chromium snapshot bucket  |
+| `stable/beta/dev/canary` | `*ChannelInstaller`      | Platform package manager  |
+| `1295939` (commit)  | `SnapshotInstaller`           | Chromium snapshot bucket  |
+| `120.0.6099.x`      | `KnownGoodVersionInstaller`   | Chrome for Testing API    |
+
+All installer classes implement the `Installer` interface from `installer.ts`. Each provides methods for both browser and ChromeDriver installation.
+
+The action uses `actions-swing` as a shared utility library — check there before adding new utility functions.
+
+## Testing
+
+Tests live in `__test__/` and use [Vitest](https://vitest.dev/). Test files mirror source file names (e.g., `version.test.ts` tests `version.ts`).
+
+- JSON fixtures for mocked API responses are in `__test__/data/` — do not lint this directory.
+- Tests mock network calls; no real HTTP requests are made.
+- When adding a new installer or version format, add a corresponding test file.
+
+## Conventions
+
+- **TypeScript strict mode** — all types must be explicit; avoid `any`.
+- **Linter:** Biome — run `pnpm lint` before committing. `useLiteralKeys` and `noUselessElse` rules are disabled.
+- **Formatter:** Biome with space indentation.
+- **Node.js ≥ 24** is required (specified in `package.json` engines and `action.yml`).
+- **Conventional Commits** are required for all commits (`feat:`, `fix:`, `chore:`, etc.).
+- **Never commit `dist/`** — it is built by CI and deployed to the `latest` branch on release.
+- The `action.yml` `main` field points to `index.js` inside `dist/`, not the TypeScript source.

CONTRIBUTING.md

@@ -0,0 +1,64 @@
+# Contributing to setup-chrome
+
+Thank you for your interest in contributing!
+
+## Development Setup
+
+**Prerequisites:** Node.js ≥ 24, [pnpm](https://pnpm.io/)
+
+```bash
+# Install dependencies
+pnpm install
+```
+
+## Development Workflow
+
+```bash
+# Lint (CI mode, no auto-fix)
+pnpm lint
+
+# Lint with auto-fix
+pnpm lint:fix
+
+# Run unit tests
+pnpm test
+
+# Run tests with verbose output
+pnpm test -- --reporter=verbose
+
+# Run a single test file
+npx vitest run __test__/<file>.test.ts
+
+# Build (compiles TypeScript → dist/index.js via @vercel/ncc)
+pnpm build
+
+# Package (copies action.yml + README.md into dist/)
+pnpm package
+```
+
+## Submitting Changes
+
+1. Fork the repository and create a branch from `master`.
+2. Make your changes with tests where applicable.
+3. Run `pnpm lint` and `pnpm test` to verify everything passes.
+4. Open a pull request against `master`.
+
+**Important:** All commit messages must follow [Conventional Commits][] — this is required for the automated release process to correctly determine version bumps and generate changelog entries.
+
+Examples:
+- `fix: handle missing chromedriver binary on Windows`
+- `feat: add support for chrome-version input alias`
+- `chore: update dependencies`
+
+## Release Process
+
+Releases are automated with [Release Please](https://github.com/googleapis/release-please):
+
+1. Merge changes to `master` following Conventional Commits.
+2. Release Please opens or updates a release PR with version bumps and changelog updates.
+3. Squash and merge the release PR.
+4. CI builds `dist/`, pushes it to the `latest` branch, and creates signed `vX` and `vX.Y.Z` tags.
+
+> **Note:** Never commit generated `dist/` files to the source branch — they are built and published automatically by CI.
+
+[Conventional Commits]: https://www.conventionalcommits.org/en/v1.0.0/

README.md

@@ -113,31 +113,7 @@ steps:
 
 ## Contributing
 
-### Local development
-
-```bash
-# Instal dependencies
-pnpm install
-
-# Run tests
-pnpm lint
-pnpm test
-
-# Build and create package in dist/
-pnpm build
-pnpm package
-```
-
-## Release
-
-Releases are automated with Release Please.  All changes must follow [Conventional Commits][], since Release Please derives versions and changelog entries from commit messages.
-
-1. Merge some changes to the main branch.
-2. Release Please opens or updates a release PR with version bumps and changelog updates.
-3. Squash and merge the release PR to the main branch with a commit message that follows [Conventional Commits][].
-4. Create a GitHub release and publish the action to the marketplace.
-
-[Conventional Commits]: https://www.conventionalcommits.org/en/v1.0.0/
+See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, workflow, and release process.
 
 ## License