ci(docs): versioned mdBook deploys + version-pinned release-note links

.github/workflows/ci.yml

@@ -1700,6 +1700,10 @@ jobs:
         with:
           github_token: ${{ secrets.GITHUB_TOKEN }}
           publish_dir: ./book
+          # 'latest' docs stay at the site root (existing URLs unaffected).
+          # keep_files preserves the per-release /vX.Y.Z/ subdirs that
+          # release.yml publishes — a plain deploy would wipe them.
+          keep_files: true
 
   # CVC reference simulation for timing correctness validation
   cvc-reference:

.github/workflows/release.yml

@@ -129,6 +129,7 @@ jobs:
         id: notes
         env:
           IS_PRERELEASE: ${{ steps.meta.outputs.is_prerelease }}
+          TAG: ${{ github.ref_name }}
         run: |
           set -euo pipefail
           ver="${{ steps.meta.outputs.version }}"
@@ -147,6 +148,15 @@ jobs:
             echo "no [$ver] section; prerelease → using [Unreleased] draft notes" >&2
             extract "Unreleased" > notes.md || true
           fi
+          # Version-pin doc links: rewrite `docs/foo.md` refs to the mdBook page
+          # published for THIS release (docs-version job deploys to gh-pages
+          # /<tag>/). Produces a clickable [docs/foo.md](…/<tag>/foo.html). \x60
+          # is a backtick (kept out of the raw shell to avoid interpolation).
+          if [ -s notes.md ]; then
+            sed -i -E \
+              "s#\x60docs/([A-Za-z0-9/_-]+)\.md\x60#[docs/\1.md](https://gpu-eda.github.io/Jacquard/${TAG}/\1.html)#g" \
+              notes.md
+          fi
           if [ ! -s notes.md ]; then
             echo "no matching CHANGELOG section; using auto-generated notes" >&2
             echo "AUTO=true" >> "$GITHUB_OUTPUT"
@@ -276,3 +286,33 @@ jobs:
           git commit -m "jacquard ${TAG#v}"
           git push
           echo "Pushed jacquard ${TAG#v} to ${tap_repo}."
+
+  # Publish a frozen copy of the docs for this release to gh-pages /<tag>/, so
+  # the release notes can link to version-pinned mdBook pages (the site root
+  # tracks main / "latest"). `keep_files: true` on both this deploy and the
+  # main-branch deploy (ci.yml) means version subdirs accumulate without
+  # wiping each other. Runs for real tags only (skips workflow_dispatch
+  # dry-runs, whose ref is a branch); independent of the binary build.
+  docs-version:
+    name: Publish versioned docs
+    if: startsWith(github.ref, 'refs/tags/v')
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          submodules: false
+      - name: Install mdbook
+        run: |
+          mkdir -p ~/.cargo/bin
+          curl -sSL https://github.com/rust-lang/mdBook/releases/download/v0.4.44/mdbook-v0.4.44-x86_64-unknown-linux-gnu.tar.gz \
+            | tar -xz -C ~/.cargo/bin
+          echo "$HOME/.cargo/bin" >> "$GITHUB_PATH"
+      - name: Build mdbook
+        run: mdbook build
+      - name: Deploy versioned docs to gh-pages /<tag>/
+        uses: peaceiris/actions-gh-pages@v4
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./book
+          destination_dir: ${{ github.ref_name }}
+          keep_files: true

CHANGELOG.md

@@ -9,6 +9,13 @@ the public contracts in `docs/release-process.md` follow stricter rules).
 
 ## [Unreleased]
 
+A substantial feature release: a **behavioral-RTL on-ramp** (synthesize Verilog /
+SystemVerilog directly, no external tools), a complete **cell-model IR** that
+makes the binary self-contained for standard cells and adds SKY130 + IHP SG13G2,
+**plural QSPI memory with a writable PSRAM mode** across Metal / CUDA / HIP, and
+new **GPU frame-capture** + **device-timestamp cosim profiling**. Full detail
+below; docs links point to the version-pinned pages for this release.
+
 ### Added
 
 - **Behavioral-RTL on-ramp (ADR 0021).** `jacquard sim` and `jacquard cosim`

docs/release-process.md

@@ -92,6 +92,26 @@ placeholder the job overwrites. Requires the one-time org setup:
 `secrets.HOMEBREW_TAP_TOKEN` (a token with `contents: write` on both tap
 repos) and the `gpu-eda/homebrew-tap-prerelease` repo.
 
+## Release notes & versioned docs (automated)
+
+Release notes come from the CHANGELOG, and doc links are pinned to the release
+— both automatic in `release.yml`:
+
+- **Notes body** = the CHANGELOG section for the tag's version. A prerelease
+  (`X.Y.Z-rc.N`) has no dated section, so the extractor falls back to
+  `[Unreleased]` — RCs ship the same curated draft you'll ship at promotion.
+  So: **write the notes in `[Unreleased]`**, including a one-sentence summary
+  lead-in before `### Added` (it becomes the release intro).
+- **Doc links are version-pinned.** The extractor rewrites `` `docs/foo.md` ``
+  references into `[docs/foo.md](https://gpu-eda.github.io/Jacquard/<tag>/foo.html)`
+  — the mdBook page frozen for *this* release. So keep CHANGELOG doc references
+  as repo-relative `` `docs/foo.md` `` (clean in-repo); the workflow does the
+  URL rewrite.
+- **Versioned docs deploy.** The `docs-version` job publishes the book to
+  gh-pages `/(tag)/` on every release tag (`keep_files: true`), while the
+  `main` push keeps deploying "latest" to the site root. Version subdirs
+  accumulate side by side; the pinned links above resolve to them.
+
 ## Staging validation (release candidates)
 
 Optional but recommended before a user-facing release: prove the