docs: document preflight token checks

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.

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

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 ./...