diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
index a568f30..1915b86 100644
--- a/.github/workflows/docs.yml
+++ b/.github/workflows/docs.yml
@@ -53,19 +53,32 @@ jobs:
             uv run mike set-default --push latest
           fi
 
+      # Publish to GitHub Pages only on tag releases (or a manual dispatch),
+      # never on ordinary main pushes. A release fires two Docs runs in quick
+      # succession -- the main-merge "dev" deploy and the tag deploy -- and when
+      # two Pages deployments land within minutes GitHub's CDN can leave the
+      # origin stuck on the earlier one (the active/successful deploy never wins
+      # at the edge). Both these steps and the deploy job below build the
+      # artifact from gh-pages HEAD, which is cumulative and already correct, so
+      # gating publish to tags yields exactly one deployment per release.
+      # dev docs still land in gh-pages on every main push; they reach the live
+      # site at the next release (or via a manual workflow_dispatch).
       - name: Checkout gh-pages for Pages upload
+        if: startsWith(github.ref, 'refs/tags/v') || github.event_name == 'workflow_dispatch'
         uses: actions/checkout@v4
         with:
           ref: gh-pages
           path: gh-pages-build
 
       - name: Upload Pages artifact
+        if: startsWith(github.ref, 'refs/tags/v') || github.event_name == 'workflow_dispatch'
         uses: actions/upload-pages-artifact@v3
         with:
           path: gh-pages-build
 
   deploy:
     needs: build
+    if: startsWith(github.ref, 'refs/tags/v') || github.event_name == 'workflow_dispatch'
     runs-on: ubuntu-latest
     permissions:
       pages: write
@@ -77,3 +90,25 @@ jobs:
       - name: Deploy to GitHub Pages
         id: deployment
         uses: actions/deploy-pages@v4
+
+      # Safety net for the GitHub-side stale-origin flake: confirm the released
+      # version actually shows up in the live versions.json. If it doesn't, the
+      # deploy "succeeded" but the CDN is serving an older artifact -- fail
+      # loudly so it's caught here instead of by a human, and re-run this job to
+      # republish the (already correct) gh-pages HEAD. Cache-bust each poll to
+      # bypass the ~10 min edge cache on versions.json and hit the origin.
+      - name: Verify released version is live
+        if: startsWith(github.ref, 'refs/tags/v')
+        run: |
+          VERSION="${GITHUB_REF_NAME#v}"
+          BASE="https://john-ramsey.github.io/macrotrace/versions.json"
+          for i in $(seq 1 24); do
+            if curl -fsSL "${BASE}?cb=${GITHUB_RUN_ID}-${i}" | grep -q "\"${VERSION}\""; then
+              echo "✓ ${VERSION} is live"
+              exit 0
+            fi
+            echo "waiting for ${VERSION} at origin (attempt ${i}/24)..."
+            sleep 15
+          done
+          echo "::error::${VERSION} not live after ~6min. The deploy succeeded but GitHub Pages is serving a stale artifact -- re-run this deploy job to republish gh-pages HEAD."
+          exit 1
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 1820833..7b6cec2 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -3,6 +3,26 @@
 Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/);
 versions follow [SemVer](https://semver.org/).
 
+## 0.3.1 — 2026-07-16
+
+- **Fixed:** macrotrace could not be installed with `uv` on a clean
+  environment. `uv add macrotrace` / `uv pip install macrotrace` failed
+  building `numba==0.53.1` ("Cannot install on Python version 3.13.x; only
+  versions >=3.6,<3.10 are supported"). macrotrace's `numpy` requirement had
+  no upper bound, and no released numba supports numpy >= 2.5 — so once numpy
+  2.5.0 landed on PyPI (2026-06-21), uv backtracked numba to 0.53.1 (March
+  2021, no wheels for supported Pythons) instead of backtracking numpy.
+  `numpy` is now capped at `<2.5`, which resolves to numba 0.66.0 + numpy
+  2.4.x. The cap is temporary and will be lifted when numba supports numpy
+  2.5.
+
+  **0.3.0 and earlier are uninstallable via uv on any fresh install since
+  2026-06-21** — this is triggered by upstream numpy, not by anything that
+  changed in those releases, so pinning to an older macrotrace does not
+  help. Upgrade to 0.3.1 instead. Installs via `pip` were never affected
+  (pip honours numba's `Requires-Python` and excludes 0.53.1), as were
+  existing environments and lockfiles resolved before 2026-06-21.
+
 ## 0.3.0 — 2026-06-15
 
 - **Breaking:** Naive date inputs (`as_of`, the vintage/data windows,
diff --git a/pyproject.toml b/pyproject.toml
index 1e20a69..550c954 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -31,7 +31,11 @@ classifiers = [
 
 dependencies = [
     "darts>=0.35.0",
-    "numpy>=2.2.4",
+    # Temporary ceiling: no released numba supports numpy>=2.5, and darts
+    # pulls numba in transitively. Without this, uv backtracks numba to
+    # 0.53.1 (Python 3.6-3.9 only) rather than backtracking numpy, and the
+    # install fails building numba's sdist. Lift when numba supports 2.5.
+    "numpy>=2.2.4,<2.5",
     "openpyxl>=3.1.0",
     "pandas>=2.2.3",
     "peewee>=4.0",
diff --git a/uv.lock b/uv.lock
index 9c9791c..dc8732e 100644
--- a/uv.lock
+++ b/uv.lock
@@ -1587,7 +1587,7 @@ docs = [
 [package.metadata]
 requires-dist = [
     { name = "darts", specifier = ">=0.35.0" },
-    { name = "numpy", specifier = ">=2.2.4" },
+    { name = "numpy", specifier = ">=2.2.4,<2.5" },
     { name = "openpyxl", specifier = ">=3.1.0" },
     { name = "pandas", specifier = ">=2.2.3" },
     { name = "peewee", specifier = ">=4.0" },