feat(ci): Attach the command reference to each release

The website only ever documents the newest release, so anyone staying on an
older version has nothing to read. Attach the generated markdown to the release
itself, which is also the copy to reach for offline.

Packaged in the docs workflow rather than by goreleaser: docgen already runs
there, and goreleaser's before hooks cannot write into dist, which it requires
to be empty when it starts. The trade-off is that the archive is not in
checksums.txt and so not covered by the release attestation.

Only tag_name and files are passed to action-gh-release, which leaves the body,
draft and prerelease fields of an existing release alone — release-please owns
the notes.

Author: khvn26

.github/workflows/docs.yml

@@ -1,8 +1,5 @@
 name: Docs
 
-# The published reference must describe a version people can install, so it is
-# built from release tags rather than from main. workflow_dispatch is here for
-# fixing the site itself (theme, landing page) without cutting a release.
 on:
   push:
     tags: ["v*"]
@@ -11,7 +8,7 @@ on:
 permissions:
   contents: read
 
-# One deployment at a time: GitHub Pages rejects concurrent deploys.
+# GitHub Pages rejects concurrent deploys.
 concurrency:
   group: pages
   cancel-in-progress: false
@@ -21,10 +18,7 @@ jobs:
     runs-on: ubuntu-latest
     permissions:
       contents: read
-      # configure-pages reads the site's base URL from the Pages API. It never
-      # creates the site: enablement defaults to false, so Pages has to be set
-      # to build from Actions by hand, and read is all this job needs.
-      pages: read
+      pages: read # read the site's base URL from the Pages API
     steps:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
@@ -43,8 +37,6 @@ jobs:
         run: go run ./cmd/docgen -out website/content
       - name: Build site
         working-directory: website
-        # configure-pages reports the correct base URL, which differs between a
-        # project site (/flagsmith-cli/) and a custom domain.
         run: hugo --minify --baseURL "${{ steps.pages.outputs.base_url }}/"
       - uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9 # v5.0.0
         with:
@@ -62,3 +54,29 @@ jobs:
     steps:
       - uses: actions/deploy-pages@cd2ce8fcbc39b97be8ca5fce6e763baed58fa128 # v5.0.0
         id: deployment
+
+  # The site only ever documents the newest release, so attach a copy to the
+  # release itself for anyone staying on an older version.
+  archive:
+    if: github.ref_type == 'tag'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write # upload a release asset
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - uses: actions/setup-go@b7ad1dad31e06c5925ef5d2fc7ad053ef454303e # v7.0.0
+        with:
+          go-version-file: go.mod
+      - name: Package the reference
+        run: |
+          go run ./cmd/docgen -out "$RUNNER_TEMP/reference"
+          tar -czf "$RUNNER_TEMP/flagsmith_${GITHUB_REF_NAME}_reference.tar.gz" -C "$RUNNER_TEMP" reference
+      # Only tag_name and files are set: release-please owns the notes, and this
+      # action leaves body, draft and prerelease alone when they are not passed.
+      - uses: softprops/action-gh-release@3d0d9888cb7fd7b750713d6e236d1fcb99157228 # v3.0.2
+        with:
+          tag_name: ${{ github.ref_name }}
+          files: ${{ runner.temp }}/flagsmith_*_reference.tar.gz
+          fail_on_unmatched_files: true