fix(ci): deploy the docs site from main after a release, not from the tag

docs.yml had an `on: release` trigger so the /download page could pick up
the new assets. It could never work: a release event runs with
github.ref = refs/tags/vX.Y.Z, and the github-pages environment allows
only `main` to deploy, so the deploy job failed on every stable release.
Pre-releases skipped the build entirely, which is why v1.8.0 was the
first release to surface it.

Replace the trigger with a workflow_dispatch fired by build.yml once the
release is published. Dispatching against main satisfies the environment
policy and publishes main's docs rather than the release branch snapshot.

Author: sepion02

.github/workflows/build.yml

@@ -507,3 +507,15 @@ jobs:
               --latest \
               --title "$TAG"
           fi
+
+      - name: Refresh the docs /download page
+        # Only a stable release changes what /releases/latest resolves to, so a
+        # pre-release would rebuild the site to byte-identical output.
+        #
+        # Dispatched against main on purpose: the github-pages environment only
+        # permits `main` to deploy, so docs.yml's old `on: release` trigger ran
+        # with a tag ref and failed its deploy every time. See docs.yml.
+        if: ${{ steps.release.outputs.is_prerelease == 'false' }}
+        env:
+          GH_TOKEN: ${{ secrets.OPENSCREEN_RELEASE_TOKEN }}
+        run: gh workflow run docs.yml --ref main --repo "$GITHUB_REPOSITORY"

.github/workflows/docs.yml

@@ -12,13 +12,17 @@ on:
       - "website/**"
       - ".github/workflows/docs.yml"
   # The /download page resolves the current release's assets at build time so it
-  # can link each platform to its actual file. Without this trigger that data
-  # would freeze at whatever the last website/** change saw, and the page would
-  # keep serving the previous version's binaries after every release.
-  # Pre-releases are skipped: /releases/latest ignores them, so the built output
-  # would be byte-identical.
-  release:
-    types: [published]
+  # can link each platform to its actual file. Without a post-release rebuild that
+  # data would freeze at whatever the last website/** change saw, and the page
+  # would keep serving the previous version's binaries after every release.
+  #
+  # That rebuild is a `workflow_dispatch` fired by build.yml once the release is
+  # published, NOT an `on: release` trigger. A release event runs with
+  # github.ref = refs/tags/vX.Y.Z, and the github-pages environment only allows
+  # `main` to deploy, so the deploy job failed on every stable release (it never
+  # surfaced earlier because pre-releases skipped the build entirely). Dispatching
+  # against main both satisfies that policy and publishes main's docs rather than
+  # the release branch's older snapshot.
   workflow_dispatch:
 
 # Cancel in-flight runs on the same ref so fast follow-up pushes
@@ -34,9 +38,6 @@ jobs:
   build:
     name: Build site
     runs-on: ubuntu-latest
-    # A pre-release does not change what /releases/latest resolves to, so
-    # rebuilding for one would burn a run to produce identical output.
-    if: github.event_name != 'release' || github.event.release.prerelease == false
     steps:
       - uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1
         with:
@@ -66,7 +67,7 @@ jobs:
     needs: build
     if: >-
       (github.event_name == 'push' && github.ref == 'refs/heads/main')
-      || github.event_name == 'release'
+      || (github.event_name == 'workflow_dispatch' && github.ref == 'refs/heads/main')
     environment:
       name: github-pages
       url: ${{ steps.deployment.outputs.page_url }}