docs: run zensical in strict mode

.github/workflows/ci.yml

@@ -120,6 +120,25 @@ jobs:
           tests/test_aiohttp.py
           tests/test_litestar.py
 
+  docs:
+    name: Docs
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
+        with:
+          enable-cache: true
+
+      - name: Install dependencies
+        run: uv sync --frozen
+
+      - name: Build site (strict)
+        run: uv run zensical build --strict
+
   coverage:
     name: Coverage
     runs-on: ubuntu-latest

.github/workflows/docs.yml

@@ -29,7 +29,7 @@ jobs:
         run: uv sync --frozen
 
       - name: Build site
-        run: uv run zensical build
+        run: uv run zensical build --strict
 
       - name: Upload Pages artifact
         uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9 # v5.0.0

CHANGELOG.md

@@ -187,6 +187,11 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
   the action's default, and `SECURITY.md` documents where to fetch and verify
   them.
 
+### Fixed
+
+- Migration-guide links now use the anchors generated by Zensical, and the
+  docs workflow runs in strict mode so broken links fail CI.
+
 ## [2.1.3] - 2026-07-31
 
 ### Fixed

CONTRIBUTING.md

@@ -27,6 +27,7 @@ uv run pyright                # type checking (strict)
 uv run pyrefly check          # type checking (strict, third opinion)
 uv run pytest --cov           # tests with coverage
 uv run zizmor .github/workflows/   # GitHub Actions audit
+uv run zensical build --strict # docs, including broken links
 ```
 
 `zizmor` needs a GitHub token for four of its audits (`impostor-commit`,

docs/migration.md

@@ -73,7 +73,7 @@ breaker = CircuitBreaker(
 | `fail_max` | `minimum_number_of_calls` + `failure_rate_threshold` | Streak → rate; see [above](#the-one-conceptual-change). |
 | `reset_timeout` | `Config.wait_duration_in_open` | Direct, in seconds. |
 | `success_threshold` | `Config.permitted_calls_in_half_open` | Probes admitted before the breaker re-decides. interlock decides on the probe *rate*, not a fixed success count. |
-| `exclude=[...]` | a `FailureClassifier` | See [below](#exclude--failureclassifier). |
+| `exclude=[...]` | a `FailureClassifier` | See [below](#exclude-failureclassifier). |
 | `name=` | `name=` | Same. |
 | `state_storage=CircuitRedisStorage(...)` | `storage=RedisStorage(...)` | See [below](#redis-shared-state). |
 | `listeners=[...]` | `listener=` | See [below](#listeners). |
@@ -245,8 +245,8 @@ def external_call(): ...
 |---|---|---|
 | `failure_threshold` | `minimum_number_of_calls` + `failure_rate_threshold` | Streak → rate. |
 | `recovery_timeout` | `Config.wait_duration_in_open` | Direct, in seconds. |
-| `expected_exception` | a `FailureClassifier` | Only these count as failures; see [below](#expected_exception--failureclassifier). |
-| `fallback_function` | `FallbackStrategy` in a pipeline | See [below](#fallback_function--fallbackstrategy). |
+| `expected_exception` | a `FailureClassifier` | Only these count as failures; see [below](#expected_exception-failureclassifier). |
+| `fallback_function` | `FallbackStrategy` in a pipeline | See [below](#fallback_function-fallbackstrategy). |
 | `name=` | `name=` | interlock requires a name explicitly. |
 
 interlock separates the breaker object from the decorator: build one