diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index 4d2207e..cf1e73b 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -567,7 +567,8 @@ jobs:
       group: flatpak-remote
     steps:
       # Same pattern as publish-aur: an unconfigured remote skips the publish
-      # instead of failing the release.
+      # instead of failing the release. The skip is loud — a quiet one let the
+      # documented remote sit unpublished for releases at a time (#951).
       - name: Check remote credentials
         id: creds
         env:
@@ -576,7 +577,13 @@ jobs:
         run: |
           if [ -z "$FLATPAK_GPG_PRIVATE_KEY" ] || [ -z "$FLATPAK_REPO_TOKEN" ]; then
             echo "configured=false" >> "$GITHUB_OUTPUT"
-            echo "FLATPAK_GPG_PRIVATE_KEY and/or FLATPAK_REPO_TOKEN not set; skipping remote publish (docs/FLATPAK_REMOTE.md)"
+            msg="FLATPAK_GPG_PRIVATE_KEY and/or FLATPAK_REPO_TOKEN not set; skipping remote publish — the documented auto-update remote will not carry this release (docs/FLATPAK_REMOTE.md)"
+            echo "::warning::$msg"
+            {
+              echo "### :warning: Flatpak remote publish skipped"
+              echo
+              echo "$msg"
+            } >> "$GITHUB_STEP_SUMMARY"
           else
             echo "configured=true" >> "$GITHUB_OUTPUT"
           fi
diff --git a/docs/FLATPAK_REMOTE.md b/docs/FLATPAK_REMOTE.md
index 6ead646..5e3833d 100644
--- a/docs/FLATPAK_REMOTE.md
+++ b/docs/FLATPAK_REMOTE.md
@@ -52,8 +52,9 @@ prerelease tags, which never reach the remote.
    Actions):
    - `FLATPAK_GPG_PRIVATE_KEY` — the armored private key
    - `FLATPAK_GPG_PASSPHRASE` — optional
-   - `FLATPAK_REPO_TOKEN` — fine-grained PAT scoped to
-     `VocaHQ/vocalinux-flatpak` with Contents: read and write
+   - `FLATPAK_REPO_TOKEN` — a token with Contents: read and write on
+     `VocaHQ/vocalinux-flatpak`. The fine-grained PAT scoped to just that
+     repo is the recommended minimum; a broader classic PAT works too.
 5. **Variables (optional)** — same settings page, Variables tab:
    - `FLATPAK_REMOTE_REPO` — publish target (default
      `VocaHQ/vocalinux-flatpak`)