diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
new file mode 100644
index 0000000..b72663b
--- /dev/null
+++ b/.github/workflows/docs.yml
@@ -0,0 +1,28 @@
+name: Deploy Docs
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - "docs/**"
+      - "mkdocs.yml"
+      - ".github/workflows/docs.yml"
+  workflow_dispatch:
+
+concurrency:
+  group: docs-deploy
+  cancel-in-progress: true
+
+permissions:
+  contents: write
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: extractions/setup-just@v2
+      - uses: astral-sh/setup-uv@v3
+      - run: just docs-deploy
diff --git a/.readthedocs.yaml b/.readthedocs.yaml
deleted file mode 100644
index ccc1ee6..0000000
--- a/.readthedocs.yaml
+++ /dev/null
@@ -1,13 +0,0 @@
-version: 2
-
-build:
-  os: "ubuntu-22.04"
-  tools:
-    python: "3.12"
-
-python:
-  install:
-    - requirements: docs/requirements.txt
-
-mkdocs:
-  configuration: mkdocs.yml
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 0bfbb37..8dc80b3 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -1,6 +1,6 @@
 # Contributing
 
 The contributing guide is published as part of the project documentation:
-**https://httpware.readthedocs.io/en/latest/dev/contributing/**
+**https://httpware.modern-python.org/dev/contributing/**
 
 Source: [`docs/dev/contributing.md`](docs/dev/contributing.md).
diff --git a/Justfile b/Justfile
index 493f3b3..7d9310e 100644
--- a/Justfile
+++ b/Justfile
@@ -29,3 +29,8 @@ publish:
     uv version $GITHUB_REF_NAME
     uv build
     uv publish --token $PYPI_TOKEN
+
+# Force-pushes built site to gh-pages; CI runs this on push to main.
+# Manual invocation from a stale checkout will roll the live site back.
+docs-deploy:
+    uvx --with-requirements docs/requirements.txt mkdocs gh-deploy --force
diff --git a/docs/CNAME b/docs/CNAME
new file mode 100644
index 0000000..2eef52d
--- /dev/null
+++ b/docs/CNAME
@@ -0,0 +1 @@
+httpware.modern-python.org
diff --git a/docs/recipes/modern-di.md b/docs/recipes/modern-di.md
index bac0a30..35eb0bb 100644
--- a/docs/recipes/modern-di.md
+++ b/docs/recipes/modern-di.md
@@ -1,6 +1,6 @@
 # Wiring `AsyncClient` into `modern-di`
 
-If you wire your app's dependencies with [`modern-di`](https://modern-di.readthedocs.io/) and want connection-pool teardown and middleware composition to flow through the container's lifecycle, this is the bridge. Both libraries ship under the [`modern-python`](https://github.com/modern-python) org.
+If you wire your app's dependencies with [`modern-di`](https://modern-di.modern-python.org/) and want connection-pool teardown and middleware composition to flow through the container's lifecycle, this is the bridge. Both libraries ship under the [`modern-python`](https://github.com/modern-python) org.
 
 ## The minimal wire-up
 
@@ -34,7 +34,7 @@ Breaking that down:
 
 A common first instinct here is `finalizer=lambda c: c.aclose()`. **That does not work** — the lambda itself is sync, so `modern-di` calls it synchronously and discards the returned coroutine unawaited. The underlying connection pool leaks. Pass the unbound async method directly, or wrap in `async def`.
 
-See the [`modern-di` factories docs](https://modern-di.readthedocs.io/providers/factories/) for the broader `CacheSettings` story (scopes, `clear_cache`, sync vs async finalizers).
+See the [`modern-di` factories docs](https://modern-di.modern-python.org/providers/factories/) for the broader `CacheSettings` story (scopes, `clear_cache`, sync vs async finalizers).
 
 ## Adding a second backend hits a type collision
 
@@ -135,4 +135,4 @@ Each cached singleton owns its own `AsyncBulkhead` and `AsyncRetry` state — wh
 - **[Quick-Start](../index.md)** — the base `AsyncClient` API.
 - **[Middleware guide](../middleware.md)** — what `AsyncBulkhead` and `AsyncRetry` are doing in `kwargs[middleware]`.
 - **[Resilience reference](../resilience.md)** — every parameter on `AsyncRetry`, `RetryBudget`, `AsyncBulkhead`.
-- **[`modern-di` factories](https://modern-di.readthedocs.io/providers/factories/)** — `CacheSettings`, scopes, the broader provider story.
+- **[`modern-di` factories](https://modern-di.modern-python.org/providers/factories/)** — `CacheSettings`, scopes, the broader provider story.
diff --git a/mkdocs.yml b/mkdocs.yml
index 5456fdb..24f9cba 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -1,5 +1,5 @@
 site_name: httpware
-site_url: https://httpware.readthedocs.io/
+site_url: https://httpware.modern-python.org
 repo_url: https://github.com/modern-python/httpware
 docs_dir: docs
 edit_uri: edit/main/docs/
diff --git a/planning/engineering.md b/planning/engineering.md
index 2f7c16d..21cb66c 100644
--- a/planning/engineering.md
+++ b/planning/engineering.md
@@ -142,7 +142,7 @@ Post-pivot, the roadmap has three categories. Topic slugs in `planning/specs/` a
   - **v0.8.0:** sync `Client` with full feature parity (middleware chain, decoder seam, `Retry`, `Bulkhead`, `stream()`); async surface renamed to `Async*`/`async_*` prefix; `attempt_timeout=` removed from `AsyncRetry`. Breaking release for every public async middleware import.
 - **Epic 4 — Streaming: SHIPPED in v0.5.** `AsyncClient.stream()` context manager + Retry refuses streamed-body requests. See [`planning/archive/specs/2026-06-05-streaming-design.md`](archive/specs/2026-06-05-streaming-design.md) and [`planning/archive/plans/2026-06-05-streaming-plan.md`](archive/plans/2026-06-05-streaming-plan.md).
 - **Epic 5 — Observability: SHIPPED in v0.6** — re-scoped from the original 4-story plan. `Retry` and `Bulkhead` emit operational events via stdlib `logging` + opt-in OpenTelemetry span events. Stories `5-1` (Layer 1 middleware hooks) and `5-4` (standalone OTel middleware) RETIRED — `opentelemetry-instrumentation-httpx` already covers transport-level tracing; a separate httpware middleware would duplicate it. See [`planning/archive/specs/2026-06-05-observability-design.md`](archive/specs/2026-06-05-observability-design.md) and [`planning/archive/plans/2026-06-05-observability-plan.md`](archive/plans/2026-06-05-observability-plan.md).
-- **Epic 6 — Ship v1.0: SHIPPED.** `6-2` docs site live at <https://httpware.readthedocs.io/> (mkdocs-material, hand-written content only, auto-publishing from `main`). Stories `6-3` (benchmarks) and `6-5` (Trusted Publishers + Sigstore release flow) RETIRED — neither carries enough value to maintain. Tag-driven release via the existing `publish.yml` workflow stays as-is.
+- **Epic 6 — Ship v1.0: SHIPPED.** `6-2` docs site live at <https://httpware.modern-python.org/> (mkdocs-material, hand-written content only, auto-publishing from `main`). Stories `6-3` (benchmarks) and `6-5` (Trusted Publishers + Sigstore release flow) RETIRED — neither carries enough value to maintain. Tag-driven release via the existing `publish.yml` workflow stays as-is.
 - **Carry-forward decoder:** `1-6` msgspec decoder via extras — second `ResponseDecoder` adapter, already implemented; verified surviving in the pivot.
 - **Middleware protocol:** `2-1` and `2-2` already implemented in the pivot (protocol, chain, phase decorators).
 
diff --git a/planning/plans/2026-06-06-modern-di-recipe-plan.md b/planning/plans/2026-06-06-modern-di-recipe-plan.md
index 2f2a9d3..3c692a9 100644
--- a/planning/plans/2026-06-06-modern-di-recipe-plan.md
+++ b/planning/plans/2026-06-06-modern-di-recipe-plan.md
@@ -170,7 +170,7 @@ Write `docs/recipes/modern-di.md` with the full content below.
 ````markdown
 # Wiring `AsyncClient` into `modern-di`
 
-If you wire your app's dependencies with [`modern-di`](https://modern-di.readthedocs.io/) and want connection-pool teardown and middleware composition to flow through the container's lifecycle, this is the bridge. Both libraries ship under the [`modern-python`](https://github.com/modern-python) org.
+If you wire your app's dependencies with [`modern-di`](https://modern-di.modern-python.org/) and want connection-pool teardown and middleware composition to flow through the container's lifecycle, this is the bridge. Both libraries ship under the [`modern-python`](https://github.com/modern-python) org.
 
 ## The minimal wire-up
 
@@ -204,7 +204,7 @@ Breaking that down:
 
 A common first instinct here is `finalizer=lambda c: c.aclose()`. **That does not work** — the lambda itself is sync, so `modern-di` calls it synchronously and discards the returned coroutine unawaited. The underlying connection pool leaks. Pass the unbound async method directly, or wrap in `async def`.
 
-See the [`modern-di` factories docs](https://modern-di.readthedocs.io/providers/factories/) for the broader `CacheSettings` story (scopes, `clear_cache`, sync vs async finalizers).
+See the [`modern-di` factories docs](https://modern-di.modern-python.org/providers/factories/) for the broader `CacheSettings` story (scopes, `clear_cache`, sync vs async finalizers).
 
 ## Adding a second backend hits a type collision
 
@@ -304,7 +304,7 @@ Each cached singleton owns its own `Bulkhead` and `Retry` state — what you wan
 - **[Quick-Start](../index.md)** — the base `AsyncClient` API.
 - **[Middleware guide](../middleware.md)** — what `Bulkhead` and `Retry` are doing in `kwargs[middleware]`.
 - **[Resilience reference](../resilience.md)** — every parameter on `Retry`, `RetryBudget`, `Bulkhead`.
-- **[`modern-di` factories](https://modern-di.readthedocs.io/providers/factories/)** — `CacheSettings`, scopes, the broader provider story.
+- **[`modern-di` factories](https://modern-di.modern-python.org/providers/factories/)** — `CacheSettings`, scopes, the broader provider story.
 ````
 
 - [ ] **Step 2: Update `mkdocs.yml` to add the `Recipes` nav section**
diff --git a/planning/plans/2026-06-08-mkdocs-gh-pages-migration-plan.md b/planning/plans/2026-06-08-mkdocs-gh-pages-migration-plan.md
new file mode 100644
index 0000000..be92571
--- /dev/null
+++ b/planning/plans/2026-06-08-mkdocs-gh-pages-migration-plan.md
@@ -0,0 +1,620 @@
+# mkdocs GitHub Pages Migration Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Move httpware's docs hosting from ReadTheDocs to GitHub Pages at `httpware.modern-python.org`, modeled on the `modern-di` pipeline, as a single structural PR.
+
+**Architecture:** A GitHub Actions workflow (`docs.yml`) runs `just docs-deploy` on every push to `main` that touches docs, mkdocs config, or the workflow itself. The recipe uses `uvx --with-requirements docs/requirements.txt mkdocs gh-deploy --force`, which builds the site and force-pushes it to the `gh-pages` branch. A `docs/CNAME` file pins the custom domain across deploys. ReadTheDocs config is deleted as part of the cutover.
+
+**Tech Stack:** GitHub Actions, mkdocs + mkdocs-material, `just`, `uv` / `uvx`, GitHub Pages.
+
+**Spec:** [`planning/specs/2026-06-08-mkdocs-gh-pages-migration-design.md`](../specs/2026-06-08-mkdocs-gh-pages-migration-design.md)
+
+---
+
+## Working assumptions
+
+- You are working on a branch off `main` (not directly on `main`). If unsure, create one: `git checkout -b docs/migrate-to-gh-pages`.
+- `just`, `uv` (which provides `uvx`), and Python ≥3.11 are installed locally.
+- DNS for `httpware.modern-python.org` and the Settings → Pages bootstrap are OPERATIONAL prerequisites and are NOT part of this plan — they're called out in the spec for the PR description.
+- The current working directory throughout the plan is the repo root: `/Users/kevinsmith/src/pypi/httpware` (or your equivalent checkout).
+
+## File map
+
+**Create:**
+- `docs/CNAME` — pins the custom domain.
+- `.github/workflows/docs.yml` — GitHub Actions deploy workflow.
+
+**Modify:**
+- `Justfile` — add `docs-deploy` recipe.
+- `mkdocs.yml` — flip `site_url`.
+- `pyproject.toml` — flip `docs` project URL.
+- `CONTRIBUTING.md` — flip docs link, drop RTD versioning path.
+- `planning/engineering.md` — flip RTD URL.
+- `docs/recipes/modern-di.md` — flip two dead `modern-di.readthedocs.io` URLs.
+- `planning/plans/2026-06-06-modern-di-recipe-plan.md` — flip two dead modern-di URLs.
+- `planning/specs/2026-06-06-modern-di-recipe-design.md` — flip one dead modern-di URL.
+
+**Delete:**
+- `.readthedocs.yaml`.
+
+---
+
+## Task 1: Add the `docs-deploy` recipe to the Justfile
+
+**Files:**
+- Modify: `Justfile`
+
+- [ ] **Step 1: Append the recipe to the Justfile**
+
+Append to the bottom of `Justfile` (after the existing `publish:` recipe):
+
+```
+# Force-pushes built site to gh-pages; CI runs this on push to main.
+# Manual invocation from a stale checkout will roll the live site back.
+docs-deploy:
+    uvx --with-requirements docs/requirements.txt mkdocs gh-deploy --force
+```
+
+The comment is intentional — `--force` makes local invocation destructive if `main` is stale.
+
+- [ ] **Step 2: Verify the recipe is registered**
+
+Run: `just --list`
+
+Expected output includes:
+```
+Available recipes:
+    default
+    docs-deploy   # Force-pushes built site to gh-pages; CI runs this on push to main.
+    install
+    lint
+    lint-ci
+    publish
+    test *args
+    test-branch
+```
+
+- [ ] **Step 3: Smoke-test that the mkdocs build still succeeds with the current config**
+
+This catches any pre-existing site-build failure before the cutover changes. Run:
+
+```
+uvx --with-requirements docs/requirements.txt mkdocs build --strict --site-dir /tmp/httpware-docs-smoke
+```
+
+Expected: `INFO    -  Documentation built in <N>s` with no warnings (because `--strict`).
+
+If this fails with broken-link warnings unrelated to this PR, STOP and surface them — that's a pre-existing problem, not a migration issue.
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add Justfile
+git commit -m "build(just): add docs-deploy recipe for mkdocs gh-deploy"
+```
+
+---
+
+## Task 2: Add `docs/CNAME` to pin the custom domain
+
+**Files:**
+- Create: `docs/CNAME`
+
+- [ ] **Step 1: Create the file**
+
+Content of `docs/CNAME` (single line, no trailing data):
+
+```
+httpware.modern-python.org
+```
+
+- [ ] **Step 2: Verify mkdocs treats it as a static asset**
+
+Run: `uvx --with-requirements docs/requirements.txt mkdocs build --strict --site-dir /tmp/httpware-docs-smoke`
+
+Then check the build output includes the CNAME file at the root:
+
+```bash
+test -f /tmp/httpware-docs-smoke/CNAME && cat /tmp/httpware-docs-smoke/CNAME
+```
+
+Expected: prints `httpware.modern-python.org`. If the file is absent, mkdocs is not copying it — abort and investigate before continuing.
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add docs/CNAME
+git commit -m "docs(cname): pin httpware.modern-python.org for GitHub Pages"
+```
+
+---
+
+## Task 3: Flip `site_url` in `mkdocs.yml`
+
+**Files:**
+- Modify: `mkdocs.yml` line 2
+
+- [ ] **Step 1: Edit the file**
+
+Change line 2 of `mkdocs.yml` from:
+
+```yaml
+site_url: https://httpware.readthedocs.io/
+```
+
+to:
+
+```yaml
+site_url: https://httpware.modern-python.org
+```
+
+(No trailing slash, matching the modern-di convention.)
+
+- [ ] **Step 2: Verify the build still passes and the new URL is baked in**
+
+Run: `uvx --with-requirements docs/requirements.txt mkdocs build --strict --site-dir /tmp/httpware-docs-smoke`
+
+Expected: build succeeds. Then confirm the new URL is embedded:
+
+```bash
+grep -c "httpware.modern-python.org" /tmp/httpware-docs-smoke/index.html
+```
+
+Expected: a positive integer (the URL appears in canonical/og meta tags).
+
+```bash
+grep -c "httpware.readthedocs.io" /tmp/httpware-docs-smoke/index.html
+```
+
+Expected: `0`. If positive, find the leftover reference and resolve it before proceeding.
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add mkdocs.yml
+git commit -m "docs(mkdocs): switch site_url to httpware.modern-python.org"
+```
+
+---
+
+## Task 4: Update the `docs` project URL in `pyproject.toml`
+
+**Files:**
+- Modify: `pyproject.toml` line 42
+
+- [ ] **Step 1: Edit the file**
+
+Change line 42 of `pyproject.toml` from:
+
+```toml
+docs = "https://httpware.readthedocs.io"
+```
+
+to:
+
+```toml
+docs = "https://httpware.modern-python.org"
+```
+
+- [ ] **Step 2: Verify the project still resolves**
+
+Run: `uv lock --check`
+
+Expected: exits 0 with no output (or a brief "Resolved N packages in <time>" line). If it errors with anything other than network issues, the TOML edit went wrong — re-check the file.
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add pyproject.toml
+git commit -m "build(pyproject): point project.urls.docs at GitHub Pages site"
+```
+
+---
+
+## Task 5: Update the docs URL in `CONTRIBUTING.md`
+
+**Files:**
+- Modify: `CONTRIBUTING.md` line 4
+
+- [ ] **Step 1: Edit the file**
+
+Change line 4 of `CONTRIBUTING.md` from:
+
+```
+**https://httpware.readthedocs.io/en/latest/dev/contributing/**
+```
+
+to:
+
+```
+**https://httpware.modern-python.org/dev/contributing/**
+```
+
+(The `/en/latest/` segment is ReadTheDocs-specific versioning; GH Pages serves the site at the root, and the page lives at `dev/contributing.md` per `mkdocs.yml`.)
+
+- [ ] **Step 2: Confirm the target path matches `mkdocs.yml`**
+
+Run:
+
+```bash
+grep -A1 "Development:" mkdocs.yml
+```
+
+Expected output contains `Contributing: dev/contributing.md`. This confirms the URL `httpware.modern-python.org/dev/contributing/` resolves to the same page as before.
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add CONTRIBUTING.md
+git commit -m "docs(contributing): repoint at GitHub Pages docs URL"
+```
+
+---
+
+## Task 6: Update `planning/engineering.md` reference
+
+**Files:**
+- Modify: `planning/engineering.md` line 145
+
+- [ ] **Step 1: Edit the file**
+
+On line 145 of `planning/engineering.md`, change:
+
+```
+`6-2` docs site live at <https://httpware.readthedocs.io/>
+```
+
+to:
+
+```
+`6-2` docs site live at <https://httpware.modern-python.org/>
+```
+
+(Keep the trailing slash — it's the angle-bracket autolink form.)
+
+- [ ] **Step 2: Verify there are no remaining `httpware.readthedocs.io` references**
+
+Run:
+
+```bash
+grep -rn "httpware.readthedocs.io" . --include="*.md" --include="*.toml" --include="*.yml" --include="*.yaml" --include="*.json" --include="*.txt" --include="Justfile" 2>/dev/null | grep -v "\.venv\|\.git\|planning/archive\|planning/audit"
+```
+
+Expected: zero matches (excluding `.readthedocs.yaml` itself, which we delete in Task 9).
+
+Run again, without excluding `.readthedocs.yaml`:
+
+```bash
+grep -rn "httpware.readthedocs.io" . --include="*.md" --include="*.toml" --include="*.yml" --include="*.yaml" --include="*.json" --include="*.txt" --include="Justfile" 2>/dev/null | grep -v "\.venv\|\.git"
+```
+
+If anything in active (non-`planning/archive`, non-`planning/audit`) files shows up, fix it before continuing.
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add planning/engineering.md
+git commit -m "docs(planning): repoint engineering.md docs URL"
+```
+
+---
+
+## Task 7: Fix dead `modern-di.readthedocs.io` URLs in live docs
+
+**Files:**
+- Modify: `docs/recipes/modern-di.md` lines 37 and 138
+
+- [ ] **Step 1: Edit line 37**
+
+Change:
+
+```
+See the [`modern-di` factories docs](https://modern-di.readthedocs.io/providers/factories/) for the broader `CacheSettings` story (scopes, `clear_cache`, sync vs async finalizers).
+```
+
+to:
+
+```
+See the [`modern-di` factories docs](https://modern-di.modern-python.org/providers/factories/) for the broader `CacheSettings` story (scopes, `clear_cache`, sync vs async finalizers).
+```
+
+- [ ] **Step 2: Edit line 138**
+
+Change:
+
+```
+- **[`modern-di` factories](https://modern-di.readthedocs.io/providers/factories/)** — `CacheSettings`, scopes, the broader provider story.
+```
+
+to:
+
+```
+- **[`modern-di` factories](https://modern-di.modern-python.org/providers/factories/)** — `CacheSettings`, scopes, the broader provider story.
+```
+
+- [ ] **Step 3: Verify no remaining `modern-di.readthedocs.io` in `docs/`**
+
+Run:
+
+```bash
+grep -rn "modern-di.readthedocs.io" docs/ 2>/dev/null
+```
+
+Expected: zero matches.
+
+- [ ] **Step 4: Rebuild the docs to confirm no broken links from this change**
+
+Run: `uvx --with-requirements docs/requirements.txt mkdocs build --strict --site-dir /tmp/httpware-docs-smoke`
+
+Expected: build succeeds. (mkdocs does not validate external URLs — this is just a "did I break the markdown?" check.)
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add docs/recipes/modern-di.md
+git commit -m "docs(recipes): retarget modern-di factories link at its new GH Pages site"
+```
+
+---
+
+## Task 8: Fix dead `modern-di.readthedocs.io` URLs in planning artifacts
+
+**Files:**
+- Modify: `planning/plans/2026-06-06-modern-di-recipe-plan.md` lines 207 and 307
+- Modify: `planning/specs/2026-06-06-modern-di-recipe-design.md` line 209
+
+- [ ] **Step 1: Edit `planning/plans/2026-06-06-modern-di-recipe-plan.md` line 207**
+
+Change:
+
+```
+See the [`modern-di` factories docs](https://modern-di.readthedocs.io/providers/factories/) for the broader `CacheSettings` story (scopes, `clear_cache`, sync vs async finalizers).
+```
+
+to:
+
+```
+See the [`modern-di` factories docs](https://modern-di.modern-python.org/providers/factories/) for the broader `CacheSettings` story (scopes, `clear_cache`, sync vs async finalizers).
+```
+
+- [ ] **Step 2: Edit `planning/plans/2026-06-06-modern-di-recipe-plan.md` line 307**
+
+Change:
+
+```
+- **[`modern-di` factories](https://modern-di.readthedocs.io/providers/factories/)** — `CacheSettings`, scopes, the broader provider story.
+```
+
+to:
+
+```
+- **[`modern-di` factories](https://modern-di.modern-python.org/providers/factories/)** — `CacheSettings`, scopes, the broader provider story.
+```
+
+- [ ] **Step 3: Edit `planning/specs/2026-06-06-modern-di-recipe-design.md` line 209**
+
+Change:
+
+```
+- `modern-di` **Factories** docs (https://modern-di.readthedocs.io/providers/factories/) — `CacheSettings`, scopes, the broader provider story.
+```
+
+to:
+
+```
+- `modern-di` **Factories** docs (https://modern-di.modern-python.org/providers/factories/) — `CacheSettings`, scopes, the broader provider story.
+```
+
+- [ ] **Step 4: Verify no remaining `modern-di.readthedocs.io` references outside archive**
+
+Run:
+
+```bash
+grep -rn "modern-di.readthedocs.io" . --include="*.md" 2>/dev/null | grep -v "\.venv\|\.git\|planning/archive\|planning/audit"
+```
+
+Expected: zero matches.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add planning/plans/2026-06-06-modern-di-recipe-plan.md planning/specs/2026-06-06-modern-di-recipe-design.md
+git commit -m "docs(planning): retarget modern-di factories link in planning artifacts"
+```
+
+---
+
+## Task 9: Delete `.readthedocs.yaml`
+
+**Files:**
+- Delete: `.readthedocs.yaml`
+
+- [ ] **Step 1: Remove the file via git**
+
+Run:
+
+```bash
+git rm .readthedocs.yaml
+```
+
+Expected: `rm '.readthedocs.yaml'`.
+
+- [ ] **Step 2: Confirm the file is gone and staged for removal**
+
+Run: `git status`
+
+Expected: under "Changes to be committed:" you see `deleted:   .readthedocs.yaml`.
+
+- [ ] **Step 3: Commit**
+
+```bash
+git commit -m "build(rtd): drop .readthedocs.yaml; cutting over to GitHub Pages"
+```
+
+---
+
+## Task 10: Add the GitHub Actions deploy workflow
+
+**Files:**
+- Create: `.github/workflows/docs.yml`
+
+- [ ] **Step 1: Create the workflow file**
+
+Write to `.github/workflows/docs.yml`:
+
+```yaml
+name: Deploy Docs
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - "docs/**"
+      - "mkdocs.yml"
+      - ".github/workflows/docs.yml"
+  workflow_dispatch:
+
+concurrency:
+  group: docs-deploy
+  cancel-in-progress: true
+
+permissions:
+  contents: write
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: extractions/setup-just@v2
+      - uses: astral-sh/setup-uv@v3
+      - run: just docs-deploy
+```
+
+This is the exact contents of `modern-di/.github/workflows/docs.yml` (commit `a3c5aa7` on 2026-06-07). Key elements:
+
+- `fetch-depth: 0` — `mkdocs gh-deploy` needs full history to manage the `gh-pages` branch.
+- `permissions: contents: write` — required to push `gh-pages`.
+- `concurrency` block — newer runs supersede older in-flight ones to avoid racing force-pushes.
+- Path filters keep code-only PRs from triggering a docs rebuild.
+
+- [ ] **Step 2: Validate the YAML parses**
+
+Run:
+
+```bash
+python3 -c "import yaml; yaml.safe_load(open('.github/workflows/docs.yml'))" && echo "YAML OK"
+```
+
+Expected: `YAML OK`.
+
+- [ ] **Step 3: Sanity-check the workflow side-by-side against modern-di's**
+
+Run:
+
+```bash
+diff .github/workflows/docs.yml ../modern-di/.github/workflows/docs.yml
+```
+
+Expected: no output (files identical). If the path `../modern-di` doesn't exist on this machine, skip — the YAML validation in step 2 is the load-bearing check.
+
+- [ ] **Step 4: Final mkdocs strict build**
+
+One last local rebuild to confirm everything still composes:
+
+```bash
+uvx --with-requirements docs/requirements.txt mkdocs build --strict --site-dir /tmp/httpware-docs-smoke
+test -f /tmp/httpware-docs-smoke/CNAME && grep -q "httpware.modern-python.org" /tmp/httpware-docs-smoke/CNAME && echo "CNAME present and correct"
+grep -q "httpware.modern-python.org" /tmp/httpware-docs-smoke/index.html && echo "site_url baked into index.html"
+```
+
+Expected: `CNAME present and correct` and `site_url baked into index.html`, with no warnings from `mkdocs build --strict`.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add .github/workflows/docs.yml
+git commit -m "ci(docs): add GitHub Pages deploy workflow for mkdocs"
+```
+
+---
+
+## Task 11: Open the PR
+
+**Files:** none
+
+- [ ] **Step 1: Push the branch**
+
+```bash
+git push -u origin HEAD
+```
+
+- [ ] **Step 2: Open the PR with operational prerequisites in the description**
+
+```bash
+gh pr create --title "docs: migrate to GitHub Pages (httpware.modern-python.org)" --body "$(cat <<'EOF'
+## Summary
+
+- Replaces ReadTheDocs with GitHub Pages as the authoritative docs host, modeled on the sibling `modern-di` setup.
+- New URL: `https://httpware.modern-python.org`.
+- Adds `.github/workflows/docs.yml`, `docs/CNAME`, and a `docs-deploy` recipe in the Justfile.
+- Deletes `.readthedocs.yaml` (clean cutover).
+- Repoints all references: `mkdocs.yml`, `pyproject.toml`, `CONTRIBUTING.md`, `planning/engineering.md`. Also fixes already-dead `modern-di.readthedocs.io` URLs in `docs/recipes/modern-di.md` and two planning artifacts.
+
+Spec: `planning/specs/2026-06-08-mkdocs-gh-pages-migration-design.md`
+
+## Operational prerequisites (NOT in this diff)
+
+These must be done by a repo admin around the merge — flagging here so they don't get forgotten:
+
+1. **DNS**: add a `CNAME` record `httpware.modern-python.org` → `modern-python.github.io` on the `modern-python.org` zone.
+2. **First-deploy bootstrap**: after the first workflow run, go to **Settings → Pages** and set **Source = Deploy from a branch**, **Branch = `gh-pages` / (root)**.
+3. **HTTPS**: once Pages serves the custom domain, tick **Enforce HTTPS** in Settings → Pages.
+
+## Follow-up (separate work, not blocking merge)
+
+- Archive the ReadTheDocs project at `readthedocs.org/projects/httpware/` so the old URL stops serving stale content.
+
+## Test plan
+
+- [ ] Mkdocs `--strict` build succeeds locally.
+- [ ] `CNAME` lands in the built site at root.
+- [ ] `httpware.modern-python.org` baked into `index.html`.
+- [ ] After merge: `Deploy Docs` workflow run on `main` succeeds.
+- [ ] After admin completes prereqs above: `https://httpware.modern-python.org/` loads and matches current RTD content.
+
+🤖 Generated with [Claude Code](https://claude.com/claude-code)
+EOF
+)"
+```
+
+Expected: PR URL printed. Capture it for handoff.
+
+- [ ] **Step 3: Confirm the diff is what you expect**
+
+Run:
+
+```bash
+gh pr diff
+```
+
+Expected files in the diff (skim, don't memorize): `.github/workflows/docs.yml` (added), `.readthedocs.yaml` (deleted), `CONTRIBUTING.md`, `Justfile`, `docs/CNAME` (added), `docs/recipes/modern-di.md`, `mkdocs.yml`, `planning/engineering.md`, `planning/plans/2026-06-06-modern-di-recipe-plan.md`, `planning/specs/2026-06-06-modern-di-recipe-design.md`, `pyproject.toml`.
+
+That's 11 files total (1 added workflow + 1 added CNAME + 1 deleted RTD config + 8 modified). No surprises.
+
+---
+
+## Post-merge verification (for the human, not the agent)
+
+These steps happen on `main` after the PR merges, in coordination with the repo admin completing the DNS + Settings → Pages prerequisites. They are NOT executed by the implementation agent.
+
+1. Watch the first `Deploy Docs` workflow run on `main` succeed.
+2. Confirm `git ls-remote origin gh-pages` returns a non-empty SHA (branch was created).
+3. Confirm the `gh-pages` branch contains `CNAME` with `httpware.modern-python.org`.
+4. After admin sets Pages source + DNS resolves, load `https://httpware.modern-python.org/` and verify content matches the previous RTD site.
+5. Push a trivial docs edit in a follow-up commit; confirm the workflow re-triggers and the live site updates within ~2 minutes.
+
+If any post-merge step fails, the rollback is `git revert` of the merge commit. ReadTheDocs remains live and unaltered until manually archived, so reverting cleanly restores the prior state.
diff --git a/planning/specs/2026-06-06-modern-di-recipe-design.md b/planning/specs/2026-06-06-modern-di-recipe-design.md
index 1585475..94624a9 100644
--- a/planning/specs/2026-06-06-modern-di-recipe-design.md
+++ b/planning/specs/2026-06-06-modern-di-recipe-design.md
@@ -206,7 +206,7 @@ Prose anchors the existing "chain is frozen at construction" invariant — middl
 - httpware **Quick-Start** — base `AsyncClient` API.
 - httpware **Middleware guide** — what `Bulkhead` and `Retry` are doing in `kwargs[middleware]`.
 - httpware **Resilience reference** — every parameter on `Retry`, `RetryBudget`, `Bulkhead`.
-- `modern-di` **Factories** docs (https://modern-di.readthedocs.io/providers/factories/) — `CacheSettings`, scopes, the broader provider story.
+- `modern-di` **Factories** docs (https://modern-di.modern-python.org/providers/factories/) — `CacheSettings`, scopes, the broader provider story.
 
 ## mkdocs.yml change
 
diff --git a/planning/specs/2026-06-08-mkdocs-gh-pages-migration-design.md b/planning/specs/2026-06-08-mkdocs-gh-pages-migration-design.md
new file mode 100644
index 0000000..d82f44b
--- /dev/null
+++ b/planning/specs/2026-06-08-mkdocs-gh-pages-migration-design.md
@@ -0,0 +1,116 @@
+# Spec: Migrate docs hosting from ReadTheDocs to GitHub Pages
+
+**Date:** 2026-06-08
+**Topic slug:** `mkdocs-gh-pages-migration`
+**Status:** Approved, awaiting plan
+
+## Goal
+
+Replace ReadTheDocs (`httpware.readthedocs.io`) with GitHub Pages (`httpware.modern-python.org`) as the authoritative host for the mkdocs site, modeled on `modern-di`'s setup. Single structural PR — docs content unchanged.
+
+## Motivation
+
+- Parity with the sibling `modern-di` project, which already runs this pipeline.
+- Custom subdomain on `modern-python.org` reads as part of the org rather than a generic ReadTheDocs project.
+- Removes ReadTheDocs as a third-party build dependency; the workflow lives in the repo alongside `ci.yml` / `publish.yml`.
+
+## Non-goals
+
+- Archiving the ReadTheDocs project on `readthedocs.org` (manual web-UI action; flagged as a post-merge follow-up).
+- Changing docs content, navigation, or theme.
+- Versioned docs (mkdocs `mike` style). Site stays single-version, latest-only.
+
+## Architecture
+
+```
+push to main (docs/** | mkdocs.yml | .github/workflows/docs.yml changed)
+        │
+        ▼
+ docs.yml workflow ── checkout (fetch-depth: 0) ── setup-just ── setup-uv
+        │
+        ▼
+ just docs-deploy  →  uvx --with-requirements docs/requirements.txt mkdocs gh-deploy --force
+        │
+        ▼
+ mkdocs writes built site to gh-pages branch (force-push)
+        │
+        ▼
+ GitHub Pages serves gh-pages, sees docs/CNAME → routes httpware.modern-python.org
+```
+
+This is a direct mirror of `modern-di`'s pipeline (its current `docs.yml`, last touched 2026-06-07 in commit `a3c5aa7`).
+
+## File changes
+
+### Add
+
+- **`.github/workflows/docs.yml`** — verbatim port of `modern-di/.github/workflows/docs.yml`:
+  - Triggers: `push` to `main` filtered on `docs/**`, `mkdocs.yml`, `.github/workflows/docs.yml`; plus `workflow_dispatch` for manual reruns.
+  - `concurrency: { group: docs-deploy, cancel-in-progress: true }` so newer runs supersede older in-flight ones.
+  - `permissions: contents: write` — required for `mkdocs gh-deploy --force` to push the `gh-pages` branch.
+  - Single `deploy` job: `actions/checkout@v4` with `fetch-depth: 0`, `extractions/setup-just@v2`, `astral-sh/setup-uv@v3`, `just docs-deploy`.
+
+- **`docs/CNAME`** — single line `httpware.modern-python.org`. Lives under `docs/` so mkdocs treats it as a static asset and copies it into the built site on every deploy. Without this, every `gh-deploy --force` wipes the custom-domain setting GitHub stores on `gh-pages` (modern-di learned this the hard way in commit `5eac5fa`).
+
+- **Justfile `docs-deploy` recipe** — append:
+  ```
+  # Force-pushes built site to gh-pages; CI runs this on push to main.
+  # Manual invocation from a stale checkout will roll the live site back.
+  docs-deploy:
+      uvx --with-requirements docs/requirements.txt mkdocs gh-deploy --force
+  ```
+  Uses `uvx` (not `uv run`) so CI doesn't need a full project `uv sync` just to publish docs. The warning comment is intentional — `--force` makes local invocation from an out-of-date `main` destructive.
+
+### Modify
+
+- **`mkdocs.yml`** line 2: `site_url: https://httpware.readthedocs.io/` → `site_url: https://httpware.modern-python.org`.
+- **`pyproject.toml`** line 42: `docs = "https://httpware.readthedocs.io"` → `docs = "https://httpware.modern-python.org"`.
+- **`CONTRIBUTING.md`** line 4: `https://httpware.readthedocs.io/en/latest/dev/contributing/` → `https://httpware.modern-python.org/dev/contributing/`. Drop the `/en/latest/` segment — that's ReadTheDocs versioning; GH Pages serves at the root.
+- **`planning/engineering.md`** line 145: replace RTD URL with the new one.
+- **`docs/recipes/modern-di.md`** lines 37 and 138: replace `https://modern-di.readthedocs.io/providers/factories/` with `https://modern-di.modern-python.org/providers/factories/`. (modern-di already moved to GH Pages; its RTD URL is dead.)
+- **`planning/plans/2026-06-06-modern-di-recipe-plan.md`** lines 207 and 307, and **`planning/specs/2026-06-06-modern-di-recipe-design.md`** line 209: same modern-di URL replacement.
+
+### Delete
+
+- **`.readthedocs.yaml`** — RTD config file. After deletion, RTD will keep building from the latest commit it saw, but the project effectively becomes unmaintained.
+
+### Unchanged
+
+- **`docs/requirements.txt`** — already `mkdocs` + `mkdocs-material`, identical to modern-di's. Consumed by `uvx --with-requirements`.
+- All other files in `docs/`, the existing `ci.yml` and `publish.yml` workflows.
+
+## Operational prerequisites (NOT code changes — flag in PR description)
+
+These must happen for the deployed site to actually serve. They are outside the PR's diff but inside the work's scope.
+
+1. **DNS:** A `CNAME` record for `httpware.modern-python.org` → `modern-python.github.io` must exist before the custom domain resolves. Org-level action on `modern-python.org`'s DNS.
+2. **First-deploy bootstrap:** The `gh-pages` branch doesn't exist yet. The first workflow run creates it via `gh-deploy --force`. After it runs, a repo admin must go to **Settings → Pages** and set **Source = Deploy from a branch**, **Branch = `gh-pages` / (root)**. One-time manual step; can't be done from a workflow.
+3. **HTTPS:** Once Pages serves the custom domain, tick **Enforce HTTPS** in Settings → Pages (auto-eligible after Let's Encrypt provisions).
+
+## Post-merge follow-ups (out of scope for this PR)
+
+1. **Archive the ReadTheDocs project** at `readthedocs.org/projects/httpware/` so `httpware.readthedocs.io` stops serving stale content. Manual web-UI action.
+2. Update any external references that point at the old URL (PyPI project page picks up `pyproject.toml` automatically on next publish; GitHub repo "About" sidebar may need a manual nudge).
+
+## Edge cases and verification
+
+- **Concurrency:** `cancel-in-progress: true` on the `docs-deploy` group prevents two simultaneous force-pushes racing each other.
+- **CNAME preservation:** Verified by inspecting the `gh-pages` branch after the first deploy — `CNAME` must be present at root with the custom domain.
+- **Path filter correctness:** The workflow trigger watches `docs/**`, `mkdocs.yml`, and `.github/workflows/docs.yml`. Other changes (code, tests, planning) won't trigger a docs rebuild — matches modern-di's behavior.
+- **Manual local rollback risk:** `just docs-deploy` from a developer machine on a stale `main` will roll the live site back. The warning comment in the Justfile is the only mitigation; we accept this trade-off (modern-di does too) because the alternative — locking the recipe behind an env check — adds complexity disproportionate to the risk.
+
+## Testing
+
+The workflow itself can't be unit-tested. Verification path:
+
+1. After merge, watch the first `Deploy Docs` workflow run on `main` succeed.
+2. Confirm the `gh-pages` branch exists and contains `CNAME` with the custom domain.
+3. Complete the operational prerequisites (DNS + Settings → Pages).
+4. Load `https://httpware.modern-python.org/` and verify the rendered site matches the current RTD content.
+5. Touch a doc file in a follow-up PR; confirm the workflow re-triggers and the site updates.
+
+If any step fails, the rollback is to revert the PR — RTD remains live and unaltered, so the old URL keeps serving.
+
+## Scope check
+
+This is a single-PR structural change. No decomposition needed. Aligns with the stated preference: clean cutover landing as one structural PR before any substantive follow-up work.
diff --git a/pyproject.toml b/pyproject.toml
index 8db3ed5..be65b8f 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -39,7 +39,7 @@ all = ["httpware[pydantic,msgspec,otel]"]
 
 [project.urls]
 repository = "https://github.com/modern-python/httpware"
-docs = "https://httpware.readthedocs.io"
+docs = "https://httpware.modern-python.org"
 
 [build-system]
 requires = ["uv_build>=0.11,<1.0"]