From b1aaff9f3bab41e8466d100c7322525f41baa6de Mon Sep 17 00:00:00 2001
From: Micheal Wilkinson <micheal.wilkinson@createfuture.com>
Date: Sat, 21 Mar 2026 13:17:39 +0000
Subject: [PATCH] docs: document preflight token checks

---
 AGENTS.md    | 4 +++-
 CHANGELOG.md | 2 ++
 README.md    | 8 ++++++++
 3 files changed, 13 insertions(+), 1 deletion(-)

diff --git a/AGENTS.md b/AGENTS.md
index a2a9ef1..47be289 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -30,7 +30,8 @@ Apply these checks before invoking actions:
 
 - Checkout repository first.
 - For prepare/publish flows that depend on tags/history, use full history checkout (`fetch-depth: 0`).
-- Use valid credentials in `github.token` (or explicit token input for `publish` when needed).
+- Use valid credentials for release/comment API calls. On GitHub, `secrets.GITHUB_TOKEN` is used; on self-hosted Gitea, set `secrets.GITEA_TOKEN`.
+- `do-release` and `decorate-pr` now run preflight API checks and fail fast when token credentials are missing or insufficient.
 - Set required vars/secrets for coverage uploads:
   - `vars.ARTEFACT_BUCKET_NAME`
   - `vars.ARTEFACT_BUCKET_ENDPONT`
@@ -241,3 +242,4 @@ Use these rules to avoid common automation mistakes:
 - Do not mix action tags in one workflow update.
 - Do not assume a release workflow will run from a tag push in all environments; reusable workflow call paths are supported.
 - Do not treat `VOCIFERATE_REPOSITORY_URL` as a full repository URL; it must be a base URL.
+- Do not bypass preflight failures with broad retry loops; fix token scope/secret wiring first.
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 22eb65a..15fb5e8 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -15,6 +15,8 @@ A `### Breaking` section is used in addition to Keep a Changelog's standard sect
 
 ### Changed
 
+- Documented release/PR-decoration preflight token and API-access checks, including `GITHUB_TOKEN`/`GITEA_TOKEN` behavior for self-hosted Gitea.
+
 ### Removed
 
 ### Fixed
diff --git a/README.md b/README.md
index 01ae8f7..3774285 100644
--- a/README.md
+++ b/README.md
@@ -95,6 +95,11 @@ Reads the matching section from `CHANGELOG.md` and creates or updates the
 Gitea/GitHub release with those notes. The `version` input is optional — when
 omitted it is derived from the current tag ref automatically.
 
+The reusable `Do Release` workflow now runs preflight checks before publish to
+fail fast when the release token is missing or lacks API access. On
+self-hosted Gitea, set `secrets.GITEA_TOKEN`; on GitHub, `secrets.GITHUB_TOKEN`
+is used automatically.
+
 The `publish` action outputs `release-id` so you can upload additional release
 assets after it runs:
 
@@ -135,6 +140,9 @@ Run your coverage tests first, then call the action to generate `coverage.html`,
 
 Decorate pull requests with coverage badges, coverage percentages, and unreleased changelog entries. The action creates a new comment or updates an existing one on each run.
 
+`decorate-pr` also runs a preflight comment API check so workflows fail early
+with a clear message when token permissions are insufficient.
+
 ```yaml
 - name: Run tests with coverage
   run: go test -covermode=atomic -coverprofile=coverage.out ./...