diff --git a/CLAUDE.md b/CLAUDE.md
index 50232314..29affb6e 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -77,6 +77,17 @@ tests/                      # pytest — mirrors src/ structure
 pyproject.toml              # hatchling + hatch-vcs, ASTRA + Snakemake as deps
 ```
 
+## Documentation versioning (mike)
+
+The whole docs site is versioned with [mike](https://github.com/squidfunk/mike) — specifically squidfunk's fork, which Zensical's versioning provider depends on. Each release deploys a full copy of the site to a subdirectory of the `gh-pages` branch (`/0.0.9/`, `/latest/`, etc.). Mike is enabled via `[project.extra.version] provider = "mike"` in `zensical.toml`; the version dropdown in the header is rendered natively.
+
+Release flow: after release, run `just docs-deploy X.Y.Z` — which runs `mike deploy --push --update-aliases X.Y.Z latest`. 
+This builds the site at the current commit and pushes a new version snapshot + updates the `latest` alias on `gh-pages`.
+
+First-time setup: after the first `docs-deploy`, run `just docs-set-default latest` once so the bare site root redirects to `/latest/`.
+
+Hosting: mike pushes to `gh-pages`. The hosting platform (Cloudflare Pages, GitHub Pages, etc.) must be configured to serve from `gh-pages`, not `main`. Without this, `mike deploy` runs successfully but the site doesn't pick up versioned URLs in production.
+
 ## Development Commands
 
 ```bash
diff --git a/justfile b/justfile
index 42b41a54..af446cb7 100644
--- a/justfile
+++ b/justfile
@@ -67,6 +67,21 @@ docs-serve-port port="8080": docs-install
 docs-clean:
     rm -rf site/
 
+# Deploy a versioned snapshot of the docs to gh-pages via mike, updating
+# the named alias (default: latest). Run after `just release`.
+docs-deploy version alias='latest': docs-install
+  uv run mike deploy --push --update-aliases {{version}} {{alias}}
+
+docs-set-default alias='latest':
+  uv run mike set-default --push {{alias}}
+
+docs-versions:
+  uv run mike list
+
+docs-delete-version version:
+  uv run mike delete --push {{version}}
+
+
 # ── Package ────────────────────────────────────────────────────────────────────
 
 # Build the wheel and sdist
diff --git a/pyproject.toml b/pyproject.toml
index 4f5f1212..37ceafab 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -40,8 +40,16 @@ dev = [
 ]
 docs = [
     "zensical>=0.0.33",
+    # squidfunk's mike fork — required by zensical's versioning provider.
+    # Not on PyPI; install from git.
+    "mike @ git+https://github.com/squidfunk/mike.git ; python_version >= '3.10'",
 ]
 
+# Versioning is handled by mike (https://github.com/squidfunk/mike).
+# Each version of the site is deployed as a subdirectory under site_url
+# (e.g. /0.0.9/, /latest/). The picker is rendered natively in the header.
+[project.extra.version]
+provider = "mike"
 
 [project.scripts]
 lc = "lightcone.cli:main"