diff --git a/.github/workflows/CLAUDE.md b/.github/workflows/CLAUDE.md
index 04bdfa5..b597853 100644
--- a/.github/workflows/CLAUDE.md
+++ b/.github/workflows/CLAUDE.md
@@ -78,6 +78,21 @@ The safe approach is to coordinate the merge order explicitly with the user.
 
 ## Expanding the matrix
 
-The PostgreSQL version matrix (`pg: [17, 16, 15, 14, 13, 12]`) is hardcoded in
+The PostgreSQL version matrix (`pg: [18, 17, 16, 15, 14, 13, 12]`) is hardcoded in
 `run-tests.yml`. GitHub Actions does not support passing a matrix as a workflow_call
 input. To add or remove a PG version, edit `run-tests.yml` directly.
+
+## Doc-only bypass
+
+Both repos' CI skip the Postgres test matrix (not just the paired-PR requirement)
+when every changed file in a PR is pure documentation — extension `*.md`, `*.asc`,
+`*.adoc`, `*.asciidoc`, anywhere including under `.claude/`, but never under
+`.github/` (workflow definitions carry real behavioral weight regardless of
+extension). `claude-review` is a separate workflow gated by its own `if:` and
+always still runs.
+
+- **pgxntool**: `check-test-pr` in `ci.yml` checks this first, before the
+  paired-test-PR lookup — a doc-only PR needs neither a paired branch nor the
+  `commit-with-no-tests` label.
+- **pgxntool-test**: the `resolve` job's `doc-only` output gates the `test` job
+  directly.
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 28ba601..eaa0bc5 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -2,6 +2,7 @@ name: CI
 
 permissions:
   contents: read        # required by actions/checkout in the reusable test workflow
+  pull-requests: read   # list changed files for the doc-only check
 
 concurrency:
   group: ci-pr-${{ github.event.pull_request.number }}
@@ -22,8 +23,44 @@ jobs:
     outputs:
       pgxntool-ref: ${{ steps.pgxntool-ref.outputs.ref }}
       pgxntool-owner: ${{ steps.pgxntool-ref.outputs.owner }}
+      doc-only: ${{ steps.doc-only.outputs.doc-only }}
 
     steps:
+      # DOC-ONLY BYPASS: skip the Postgres test matrix (the `test` job below)
+      # when every changed file is pure documentation. Files under .github/
+      # are never doc-only even if their extension matches (they're workflow
+      # definitions with real behavioral weight). Everything else — including
+      # .claude/*.md prompt and command docs, which carry no execution weight
+      # themselves — counts.
+      #
+      # This does NOT affect claude-review: that's a separate workflow gated
+      # by its own `if:`, unaffected by this job's outputs.
+      - name: Check doc-only
+        id: doc-only
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          REPO: ${{ github.repository }}
+          PR_NUMBER: ${{ github.event.pull_request.number }}
+        run: |
+          # Include previous_filename too: a rename like src/foo.sql ->
+          # docs/foo.md must not read as doc-only just because the new name
+          # matches — the old path is a real code change.
+          files=$(gh api "repos/$REPO/pulls/$PR_NUMBER/files" --paginate \
+            --jq '.[] | .filename, (.previous_filename // empty)')
+          doc_only=true
+          [ -z "$files" ] && doc_only=false
+          while IFS= read -r f; do
+            case "$f" in
+              .github/*) doc_only=false ;;
+              *.md|*.asc|*.adoc|*.asciidoc) ;;
+              *) doc_only=false ;;
+            esac
+          done <<<"$files"
+          echo "doc-only=$doc_only" >> "$GITHUB_OUTPUT"
+          echo "doc-only: $doc_only"
+          echo "changed files:"
+          echo "$files"
+
       - name: Resolve pgxntool branch
         id: pgxntool-ref
         # PR-controlled values (head_ref, head owner) are passed via env, never
@@ -72,6 +109,7 @@ jobs:
 
   test:
     needs: resolve
+    if: needs.resolve.outputs.doc-only != 'true'
     # run-tests.yml is the single source of truth for all test steps.
     # See .github/workflows/CLAUDE.md for architecture notes, including
     # the cross-repo reusable workflow tradeoffs and merge order constraints.
diff --git a/.github/workflows/run-tests.yml b/.github/workflows/run-tests.yml
index 04c101f..7d1664b 100644
--- a/.github/workflows/run-tests.yml
+++ b/.github/workflows/run-tests.yml
@@ -39,7 +39,7 @@ jobs:
       PGXNTOOL_TEST_REF: ${{ inputs.pgxntool-test-ref }}
     strategy:
       matrix:
-        pg: [17, 16, 15, 14, 13, 12]
+        pg: [18, 17, 16, 15, 14, 13, 12]
 
     steps:
       - name: Start PostgreSQL ${{ matrix.pg }}