From 483f8f0a341198418b34b417da5f5932fcca8290 Mon Sep 17 00:00:00 2001
From: Chris Busillo <info@shinycomputers.com>
Date: Sun, 26 Apr 2026 16:03:08 -0400
Subject: [PATCH] Document publish operations

---
 AGENTS.md  |  4 ++++
 RELEASE.md | 41 +++++++++++++++++++++++++++++++++++++----
 2 files changed, 41 insertions(+), 4 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index c6b4c79..b7a8f82 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -42,6 +42,10 @@ This repository is maintained as a careful, community-oriented Python client for
 - Do not publish releases from unreviewed local state.
 - Build and validate distributions before release.
 - Use TestPyPI before first publishing under a new distribution name.
+- Run the manual `Publish` workflow from a `v*` release tag only.
+- Keep the `testpypi` environment unblocked by manual review.
+- Keep the `pypi` environment protected by maintainer approval.
+- Trusted publishers must match project `printnode_community`, owner `cbusillo`, repository `printnode_community`, workflow `publish.yml`, and environment `testpypi` or `pypi`.
 - Update `CHANGELOG.md` for user-visible changes.
 - Keep release notes clear about whether this is an official PrintNode release or a community-maintained fork.
 - Preserve `printnode_community` as the import package.
diff --git a/RELEASE.md b/RELEASE.md
index 8c6229b..1ba9203 100644
--- a/RELEASE.md
+++ b/RELEASE.md
@@ -8,7 +8,8 @@ The historical PyPI distribution name is `PrintNodeApi`, but upstream has not re
 
 PyPI normalizes `printnode-community` and `printnode_community` as the same project name. Prefer documenting `uv add printnode_community` and `python -m pip install printnode_community` so the install command visually matches the import namespace.
 
-Before the first release, verify that `printnode_community` is still available on both PyPI and TestPyPI, then configure trusted publishing for that name.
+Before the first release, verify that `printnode_community` is still available
+on both PyPI and TestPyPI, then configure trusted publishing for that name.
 
 ## Versioning
 
@@ -66,10 +67,42 @@ deactivate
 
 Configure two GitHub environments before publishing:
 
-- `testpypi`
-- `pypi`
+- `testpypi`: no required reviewer, so TestPyPI dry runs do not pause.
+- `pypi`: require maintainer approval before production publishing.
 
-Both environments should require manual approval. Configure each environment as a trusted publisher in the corresponding PyPI project before running the workflow.
+Configure each environment as a trusted publisher in the corresponding PyPI
+project before running the workflow. TestPyPI and PyPI are separate services;
+both need their own pending publisher.
+
+Use these exact values on TestPyPI:
+
+```text
+Project name: printnode_community
+Owner: cbusillo
+Repository: printnode_community
+Workflow: publish.yml
+Environment: testpypi
+```
+
+Use these exact values on PyPI:
+
+```text
+Project name: printnode_community
+Owner: cbusillo
+Repository: printnode_community
+Workflow: publish.yml
+Environment: pypi
+```
+
+If publish fails with `invalid-publisher`, compare the claims in the failed
+Actions log with the pending publisher. The expected TestPyPI claims include:
+
+```text
+sub: repo:cbusillo/printnode_community:environment:testpypi
+repository: cbusillo/printnode_community
+job_workflow_ref: cbusillo/printnode_community/.github/workflows/publish.yml@refs/tags/v0.3.0
+ref: refs/tags/v0.3.0
+```
 
 The `Publish` workflow uses GitHub OpenID Connect through `id-token: write`; do not add PyPI API tokens unless trusted publishing is unavailable.