diff --git a/.gitea/workflows/test.yml b/.gitea/workflows/test.yml
index a292681f..a230b085 100644
--- a/.gitea/workflows/test.yml
+++ b/.gitea/workflows/test.yml
@@ -78,7 +78,14 @@ jobs:
       - uses: subosito/flutter-action@v2
         with: { channel: stable, cache: true }
       - run: dart pub get
-      - run: dart doc --validate-links
+      - name: dart doc --validate-links (fail on warning)
+        run: |
+          set -o pipefail
+          dart doc --validate-links 2>&1 | tee dartdoc.log
+          if grep -q "^  warning:" dartdoc.log; then
+            echo "::error::dartdoc emitted warnings — see log above"
+            exit 1
+          fi
       - uses: actions/upload-artifact@v4
         with:
           name: dart-api-docs
diff --git a/.pql/pql-plan.json b/.pql/pql-plan.json
index 5509e599..cbd96917 100644
--- a/.pql/pql-plan.json
+++ b/.pql/pql-plan.json
@@ -1,5 +1,5 @@
 {
-  "exported_at": "2026-05-06T15:58:18Z",
+  "exported_at": "2026-05-06T15:58:27Z",
   "decisions": [
     {
       "id": "D-1",
diff --git a/CHANGELOG.md b/CHANGELOG.md
index b52a8bd0..f35ca2e3 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -19,9 +19,10 @@ heading, and (b) bumping `pubspec.yaml` `version:` in the same commit.
 ### Added
 
 - Staged `dart doc` CI job — generates and uploads an HTML API
-  reference for the public `lib/` surface, with `--validate-links` to
-  fail the build on broken references. Inert with the rest of the
-  workflow until Gitea Actions activates.
+  reference for the public `lib/` surface. The step wraps
+  `dart doc --validate-links` and grep-fails the build on any warning,
+  so broken doc refs and dangling links can't accumulate. Inert with
+  the rest of the workflow until Gitea Actions activates.
 - Mouse wheel scrolling in Claude pane — converts scroll events to
   PgUp/PgDown so Claude Code (and other TUI apps) scroll their
   history naturally.