diff --git a/AGENT.md b/AGENT.md
index 1c03228..47dd1ae 100644
--- a/AGENT.md
+++ b/AGENT.md
@@ -16,6 +16,7 @@ This repository contains the Firefox WebExtension **Proxy Switcher Fork By WT**.
 - `options.html`, `options.js`, `options.css` — profiles, domains, management actions, and Advanced Settings.
 - `icons/` — extension icon sizes referenced by `manifest.json`.
 - `Makefile` — build and cleanup commands.
+- `.github/workflows/release.yml` — per-push package builds, workflow artifacts, and release-triggered AMO/Chrome Web Store publishing.
 
 ## Development rules
 
@@ -28,6 +29,7 @@ This repository contains the Firefox WebExtension **Proxy Switcher Fork By WT**.
 - When changing an icon, update every size referenced by the manifest and verify the XPI contains the new paths.
 - Never hand-edit or retain stale `META-INF` signatures after changing files. Build artifacts must be signed again before distribution.
 - Do not commit generated `web-ext-artifacts/` packages unless explicitly requested.
+- Keep publishing credentials only in GitHub Secrets. The release workflow expects AMO JWT credentials and Chrome Web Store OAuth credentials.
 
 ## Validation
 
diff --git a/README.md b/README.md
index 3c95156..0585596 100644
--- a/README.md
+++ b/README.md
@@ -94,6 +94,18 @@ The package is created at `web-ext-artifacts/proxyswitcherforkbywt.xpi`. This lo
 
 For Chrome/Chromium, run `make build-chrome`. That creates `web-ext-artifacts/proxyswitcherforkbywt-chrome.zip` from `manifest.chrome.json` and the shared UI files.
 
+## GitHub Actions release publishing
+
+`.github/workflows/release.yml` builds both packages on every push. The run exposes a downloadable `extension-packages-<commit>` artifact containing the Firefox XPI and Chrome ZIP. When a GitHub Release is published, it checks that both manifests match the release tag, submits the Firefox package to AMO for signing and review, uploads and submits the Chrome package through the Chrome Web Store API v2, and attaches the signed Firefox XPI and Chrome ZIP to the release card.
+
+Configure these repository or environment secrets before publishing:
+
+- `AMO_JWT_ISSUER` and `AMO_JWT_SECRET` — AMO API credentials for `web-ext sign`.
+- `CWS_PUBLISHER_ID` and `CWS_EXTENSION_ID` — Chrome Web Store publisher and existing item IDs.
+- `CWS_CLIENT_ID`, `CWS_CLIENT_SECRET`, and `CWS_REFRESH_TOKEN` — Google OAuth credentials with Chrome Web Store API access.
+
+The stores must already contain their initial listings and required privacy information. Store review still applies; the workflow submits the update and does not bypass review. Never commit any of these credentials.
+
 To remove generated packages:
 
 ```sh