diff --git a/CHANGELOG.md b/CHANGELOG.md
index c40039f..7707f3b 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -12,9 +12,13 @@ own `CHANGELOG.md` (generated from `CHANGELOG.template.md` during init).
 
 ### Added
 
-- "Repository secrets" section in `README.md` documenting the GitHub Actions secrets the bundled workflows expect (`PS_GALLERY_KEY`, `CODECOV_TOKEN`, `GITGUARDIAN_API_KEY`) — required vs. optional, source, and failure mode when missing.
+- "Repository secrets" section in `README.md` documenting the GitHub Actions secrets the bundled workflows expect (`PSGALLERY_API_KEY`, `CODECOV_TOKEN`, `GITGUARDIAN_API_KEY`) — required vs. optional, source, and failure mode when missing.
 - `Initialize-Template.ps1` now mentions configuring GitHub repository secrets in its post-init "Next steps" output, between the build-test step and the first push.
 
+### Changed
+
+- Renamed required PowerShell Gallery publish secret `PS_GALLERY_KEY` → `PSGALLERY_API_KEY` so the secret name matches the env var name PowerShellBuild reads (eliminating the previous mapping caveat). New modules created from the template after this change pick up the new name automatically. **Migration for existing modules:** create a new `PSGALLERY_API_KEY` repo secret with the same value, update `.github/workflows/PublishModuleToPowerShellGallery.yaml` to reference `secrets.PSGALLERY_API_KEY`, then delete the old `PS_GALLERY_KEY` secret.
+
 ## [2026.04.29] - 2026-04-29
 
 ### Added
diff --git a/README.md b/README.md
index 78f2a07..4264b2f 100644
--- a/README.md
+++ b/README.md
@@ -70,13 +70,13 @@ The bundled GitHub Actions workflows expect the following secrets to be set in y
 
 | Secret | Workflow | Required? | Source | Failure if missing |
 |---|---|---|---|---|
-| `PS_GALLERY_KEY` | `PublishModuleToPowerShellGallery.yaml` | Required to publish | [PowerShell Gallery API keys](https://www.powershellgallery.com/account/apikeys) (scope to your module name) | Publish job fails at the PowerShellBuild authentication assertion |
+| `PSGALLERY_API_KEY` | `PublishModuleToPowerShellGallery.yaml` | Required to publish | [PowerShell Gallery API keys](https://www.powershellgallery.com/account/apikeys) (scope to your module name) | Publish job fails at the PowerShellBuild authentication assertion |
 | `CODECOV_TOKEN` | `CI.yaml` | Optional | [Codecov](https://about.codecov.io/) after linking the repository | Coverage upload step is gated with `fail_ci_if_error: false`, so CI still passes — no coverage data is uploaded |
 | `GITGUARDIAN_API_KEY` | `ggshield.yaml` | Required for that workflow to pass | [GitGuardian dashboard](https://dashboard.gitguardian.com/) (free tier available) | Workflow fails on every push with "Invalid GitGuardian API key" |
 
 `GITHUB_TOKEN` is automatically provided by GitHub Actions and does not need to be set.
 
-The publish workflow exposes `secrets.PS_GALLERY_KEY` to its job as the env var `PSGALLERY_API_KEY` — the variable PowerShellBuild reads when publishing. Set the secret as `PS_GALLERY_KEY`.
+The publish workflow exposes this secret to its job under the same env var name (`PSGALLERY_API_KEY`), which is the variable PowerShellBuild reads.
 
 ## Placeholders