ci(docs): deploy docs.aethersdr.com at release time, not on every merge to main #6556

Problem

The Docs workflow (.github/workflows/docs.yml) has failed on every push to main since 2026-10-17 15:31 UTC (first failure: 5813556e0, the KPA500 applet). It has failed 15 times in a row; the last success was 7864ef544 on 2026-10-16.

The failing step is Deploy to Cloudflare Pages:

✘ [ERROR] Error: Pages only supports files up to 25 MiB in size
  AetherSDR-Manual.pdf is 25.3 MiB in size

The PDF manual is copied into the site root (docs/user/build/AetherSDR-Manual.pdf) and uploaded with the rest of the site. The last good run wrote it at 24.9 MiB. It went over the limit as the user guide grew, and it will keep growing.

There is also a cost problem underneath. push on main is filtered to docs/user/**, and user-visible PRs now have to update docs/user/ in the same PR, so nearly every merge starts a full Docusaurus build, a PDF typeset and a Pages deploy. In Discord on 2026-10-17, @jensenpat reported that this made /pr-land merges slow (the last three took about 44 minutes each). He removed the doc rebuild from his local copy of the skill. That keeps the time cost out of his merges but leaves the docs going stale.

Proposal

Agreed in Discord (@jensenpat, @ten9876, @NF0T): publishing the docs is a release-time job.

1. Remove the push: branches: [main] trigger from docs.yml. Merges to main no longer build or deploy the docs.
2. Keep the pull_request build as it is. It is the broken-link and anchor check (onBrokenLinks: 'throw'), the generated-reference check and the PDF render check, and it only runs when a PR touches docs/user/** or tools/docs/**. It deploys nothing.
3. Deploy the site on release: published, alongside the existing release-pdf job. The site build and Pages deploy run against the release tag.
4. Take the PDF out of the Pages upload. Moving the deploy to release time does not fix the 25 MiB limit on its own. The release PDF would hit it the same way. The signed AetherSDR-Manual-<tag>.pdf + .asc is already attached to every GitHub release (no 25 MiB cap there). Point the site's PDF link at the release asset, and either drop https://docs.aethersdr.com/AetherSDR-Manual.pdf or turn it into a redirect (a Pages _redirects entry) to the latest release's asset.
5. Keep workflow_dispatch so a maintainer can redeploy by hand from the latest tag, for example after a docs-only fix between releases.

Trade-offs for a maintainer to decide

• Between releases, docs.aethersdr.com shows the last release. For the Stable version that is arguably correct, since the docs match the software users have installed. The Next version will no longer follow main. If Next should stay live, one option is to deploy it on a schedule (for example nightly, skipped when docs/user/** has not changed) rather than on every merge.
• A stable PDF URL. releases/latest/download/ needs a filename that does not change. The release job could upload an extra unversioned AetherSDR-Manual.pdf next to the tagged one so that the URL keeps working.
• PDF size. The PDF is 25 MiB for 97 pages, which suggests the screenshots are embedded at full resolution. Downscaling or recompressing images in tools/docs/build_pdf.py is worth a separate issue. It would not restore deploy-on-merge, but it would make the download smaller for users.

Acceptance

• Merging a PR that touches docs/user/** does not run a Pages deploy.
• A PR that touches docs/user/** still runs the link check and the PDF render check, and still uploads the PDF artifact.
• Publishing a release deploys the site from the tag and attaches the signed PDF, and the Pages upload contains no file over 25 MiB.
• The site's PDF link resolves.
• A manual workflow_dispatch run deploys successfully.

PR to follow.

73,
Ryan NF0T

👨🏼‍💻 Co-authored by Claude Opus 5.5