docs: add CONTRIBUTING.md and AGENTS.md

AGENTS.md

@@ -0,0 +1,68 @@
+# Agentic Coding Guide
+
+This file provides guidance for AI coding agents working in this repository.
+
+## Repository Purpose
+
+`setup-firefox` is a GitHub Action that installs Firefox on GitHub Actions runners. It supports stable, beta, devedition, nightly, and ESR releases, as well as specific version numbers.
+
+## 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, invokes installer, sets outputs
+  platform.ts            # OS/arch detection → Platform struct
+  versions.ts            # version alias resolution (latest, latest-beta, latest-esr, etc.)
+  DownloadURL.ts         # constructs the download URL for a given version and platform
+  DownloadURLFactory.ts  # factory that picks the right DownloadURL strategy for a version spec
+  installers.ts          # installer registry: maps platform to the right installer class
+  LinuxInstaller.ts      # Firefox installer for Linux
+  MacOSInstaller.ts      # Firefox installer for macOS
+  WindowsInstaller.ts    # Firefox installer for Windows
+  firefoxUtils.ts        # shared utilities (e.g. finding the installed binary)
+  errors.ts              # custom error types
+__test__/
+  DownloadURL.test.ts         # tests for URL construction
+  DownloadURLFactory.test.ts  # tests for URL factory dispatch
+  installers.test.ts          # tests for installer selection
+action.yml              # action metadata: inputs, outputs, runs.using: node24
+biome.json              # linter/formatter config
+```
+
+## Architecture
+
+Version resolution and download URL construction are separated:
+
+1. `versions.ts` resolves alias strings (e.g. `latest-beta`) to actual release version numbers by querying the Mozilla release API.
+2. `DownloadURLFactory.ts` picks the right `DownloadURL` strategy for the resolved version and platform.
+3. Platform-specific installer classes (`LinuxInstaller`, `MacOSInstaller`, `WindowsInstaller`) handle download, extraction, and PATH setup.
+
+## Testing
+
+Tests live in `__test__/` and use [Vitest](https://vitest.dev/).
+
+- Tests mock network/HTTP calls; no real requests are made at test time.
+- When adding support for a new version alias or platform, add or update the 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.
+- **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-firefox
+
+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: resolve incorrect Firefox binary path on macOS`
+- `feat: support latest-esr version 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

@@ -40,31 +40,7 @@ jobs:
 
 ## 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