docs: add CONTRIBUTING.md and AGENTS.md

AGENTS.md

@@ -0,0 +1,58 @@
+# Agentic Coding Guide
+
+This file provides guidance for AI coding agents working in this repository.
+
+## Repository Purpose
+
+`release-firefox-addon` is a GitHub Action that publishes a Firefox add-on to AMO (addons.mozilla.org) using the AMO API with JWT-based authentication.
+
+## 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 build                       # compile TypeScript → dist/index.js
+pnpm package                     # copy action.yml + README.md into dist/
+```
+
+> ℹ️ There is no automated test suite in this repository. Verify behaviour manually or with integration tests against the AMO API.
+
+## Project Layout
+
+```
+src/
+  index.ts   # action entry point: reads inputs, calls AMO API, sets outputs
+  amo.ts     # AMO API client (upload version, poll status, retrieve version info)
+action.yml   # action metadata: inputs, outputs, runs.using: node24
+biome.json   # linter/formatter config
+```
+
+## Architecture
+
+The action flow is:
+
+1. Read `addon-id`, `addon-path`, optional `source-path`, and JWT credentials from inputs.
+2. Use `amo.ts` to upload the add-on zip (and optional source zip) to the AMO API.
+3. Poll until the upload is processed, then set version outputs (`version`, `version-id`, `version-edit-url`).
+
+`amo.ts` constructs signed JWT tokens from `auth-api-issuer` and `auth-api-secret` using the `jsonwebtoken` library. The `uuid` library is used for unique upload identifiers.
+
+### Source code submission
+
+If the add-on contains minified or transpiled files, AMO requires a source zip. Pass the `source-path` input and include an `approval-note` explaining how to build the project so reviewers can verify the code.
+
+### Channel
+
+The `channel` input controls whether the version is published publicly (`listed`) or unlisted (`unlisted`). Default is `listed`.
+
+## 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.
+- **Never commit AMO API credentials** — always use GitHub Actions secrets.
+- The `action.yml` `main` field points to `index.js` inside `dist/`, not the TypeScript source.

CONTRIBUTING.md

@@ -0,0 +1,68 @@
+# Contributing to release-firefox-addon
+
+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
+```
+
+## AMO API Credentials for Local Testing
+
+To test against the AMO (addons.mozilla.org) API, you need JWT credentials (`auth-api-issuer` and `auth-api-secret`). You can obtain them from the [AMO Developer Hub](https://addons.mozilla.org/en-US/developers/addon/api/key/).
+
+## 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 unlisted channel upload errors`
+- `feat: support release-note locales`
+- `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

@@ -66,6 +66,10 @@ All supported outputs are the following:
 | `version-id`       | 'ID of the uploaded version in numeric format. |
 | `version-edit-url` | 'URL of the edit page of the uploaded version. |
 
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, workflow, and release process.
+
 ## License
 
 [MIT](LICENSE)