diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 4135cf8..658de93 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -42,36 +42,29 @@ jobs:
     - name: Test package
       run: uv run --with "clang<19" --group test pytest
       
-# Commented for now -- msys2 Clang (v15) and the clang Python package (v14) are incompatible
-#
-#  checks_windows:
-#    strategy:
-#      fail-fast: false
-#      matrix:
-#        python-version:
-#        - "3.8"
-#        - "3.9"
-#        runs-on:
-#        - windows-latest
-#    runs-on: ${{ matrix.runs-on }}
-#    name: Test • 🐍 ${{ matrix.python-version }} • ${{matrix.runs-on}}
-#    steps:
-#    - uses: actions/checkout@v7
-#    - uses: actions/setup-python@v7
-#      with:
-#        python-version: ${{ matrix.python-version }}
-#
-#    - name: Install package
-#      run: python -m pip install -e. --group test
-#
-#    - name: Install clang
-#      run: C:\msys64\usr\bin\pacman.exe -S clang64/mingw-w64-clang-x86_64-clang --noconfirm
-#
-#    - name: Test package
-#      env:
-#        LIBCLANG_PATH: C:\msys64\clang64\bin\libclang.dll 
-#      run: python -m pytest -n2
-  
+  checks_windows:
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version:
+        - "3.9"
+        - "3.14"
+    runs-on: windows-latest
+    name: Test • 🐍 ${{ matrix.python-version }} • windows-latest
+    steps:
+    - uses: actions/checkout@v7
+    - uses: actions/setup-python@v7
+      with:
+        python-version: ${{ matrix.python-version }}
+        allow-prereleases: true
+    - uses: astral-sh/setup-uv@v9.0.0
+
+    - name: Test package
+      env:
+        LIBCLANG_PATH: C:\Program Files\LLVM\bin\libclang.dll
+      run: uv run --with "clang<19" --group test pytest
+
+
   dist:
     runs-on: ubuntu-latest
     name: Build distribution
diff --git a/pybind11_mkdoc/mkdoc_lib.py b/pybind11_mkdoc/mkdoc_lib.py
index e706455..90bd583 100755
--- a/pybind11_mkdoc/mkdoc_lib.py
+++ b/pybind11_mkdoc/mkdoc_lib.py
@@ -17,6 +17,7 @@
 from concurrent.futures import ThreadPoolExecutor
 from glob import glob
 from itertools import repeat
+from pathlib import PurePosixPath
 
 from clang import cindex
 from clang.cindex import CursorKind
@@ -577,6 +578,10 @@ def _extract_file(filename, parameters):
     return output
 
 
+def _folder_version(d):
+    return [int(ver) for ver in re.findall(r"(?<!lib)(?<!\d)\d+", d)]
+
+
 def read_args(args):
     parameters = []
     filenames = []
@@ -588,27 +593,54 @@ def read_args(args):
 
     if platform.system() == "Darwin":
         dev_path = "/Applications/Xcode.app/Contents/Developer/"
-        lib_dir = dev_path + "Toolchains/XcodeDefault.xctoolchain/usr/lib/"
-        sdk_dir = dev_path + "Platforms/MacOSX.platform/Developer/SDKs"
-        libclang = lib_dir + "libclang.dylib"
+        clt_path = "/Library/Developer/CommandLineTools/"
 
         # cindex forbids (re)configuring the library once it has been loaded
-        if os.path.exists(libclang) and not cindex.Config.loaded:
-            cindex.Config.set_library_path(os.path.dirname(libclang))
-
-        if os.path.exists(sdk_dir):
-            sysroot_dir = os.path.join(sdk_dir, next(os.walk(sdk_dir))[1][0])
-            parameters.append("-isysroot")
-            parameters.append(sysroot_dir)
+        if "LIBCLANG_PATH" in os.environ:
+            library_file = os.environ["LIBCLANG_PATH"]
+            if not os.path.isfile(library_file):
+                msg = (
+                    f"LIBCLANG_PATH points to {library_file!r}, which is not a file. "
+                    "Set it to the path of libclang.dylib."
+                )
+                raise FileNotFoundError(msg)
+            if not cindex.Config.loaded:
+                cindex.Config.set_library_file(library_file)
+        else:
+            for libclang in (
+                dev_path + "Toolchains/XcodeDefault.xctoolchain/usr/lib/libclang.dylib",
+                clt_path + "usr/lib/libclang.dylib",
+            ):
+                if os.path.exists(libclang):
+                    if not cindex.Config.loaded:
+                        cindex.Config.set_library_path(os.path.dirname(libclang))
+                    break
+
+        for sdk_dir in (
+            dev_path + "Platforms/MacOSX.platform/Developer/SDKs",
+            clt_path + "SDKs",
+        ):
+            if os.path.exists(sdk_dir):
+                sdks = sorted(next(os.walk(sdk_dir))[1], key=_folder_version)
+                if "MacOSX.sdk" in sdks:
+                    sdk = "MacOSX.sdk"
+                elif sdks:
+                    sdk = sdks[-1]
+                else:
+                    continue
+                parameters.extend(["-isysroot", str(PurePosixPath(sdk_dir) / sdk)])
+                break
     elif platform.system() == "Windows":
         if "LIBCLANG_PATH" in os.environ:
             library_file = os.environ["LIBCLANG_PATH"]
-            if os.path.isfile(library_file):
-                if not cindex.Config.loaded:
-                    cindex.Config.set_library_file(library_file)
-            else:
-                msg = "Failed to find libclang.dll! Set the LIBCLANG_PATH environment variable to provide a path to it."
+            if not os.path.isfile(library_file):
+                msg = (
+                    f"LIBCLANG_PATH points to {library_file!r}, which is not a file. "
+                    "Set it to the path of libclang.dll."
+                )
                 raise FileNotFoundError(msg)
+            if not cindex.Config.loaded:
+                cindex.Config.set_library_file(library_file)
         else:
             library_file = ctypes.util.find_library("libclang.dll")
             if library_file is not None and not cindex.Config.loaded:
@@ -617,24 +649,32 @@ def read_args(args):
         # LLVM switched to a monolithical setup that includes everything under
         # /usr/lib/llvm{version_number}/. We glob for the library and select
         # the highest version
-        def folder_version(d):
-            return [int(ver) for ver in re.findall(r"(?<!lib)(?<!\d)\d+", d)]
-
         llvm_dir = max(
             (
                 path
                 for libdir in ["lib64", "lib", "lib32"]
                 for path in glob(f"/usr/{libdir}/llvm-*")
-                if os.path.exists(os.path.join(path, "lib", "libclang.so.1"))
+                if os.path.exists(str(PurePosixPath(path) / "lib" / "libclang.so.1"))
             ),
             default=None,
-            key=folder_version,
+            key=_folder_version,
         )
 
         # Ability to override LLVM/libclang paths
         if "LLVM_DIR_PATH" in os.environ:
             llvm_dir = os.environ["LLVM_DIR_PATH"]
-        elif llvm_dir is None:
+
+        if "LIBCLANG_PATH" in os.environ:
+            libclang_file = os.environ["LIBCLANG_PATH"]
+            if not os.path.isfile(libclang_file):
+                msg = (
+                    f"LIBCLANG_PATH points to {libclang_file!r}, which is not a file. "
+                    "Set it to the path of libclang.so.1."
+                )
+                raise FileNotFoundError(msg)
+        elif llvm_dir is not None:
+            libclang_file = str(PurePosixPath(llvm_dir) / "lib" / "libclang.so.1")
+        else:
             msg = (
                 "Failed to find a LLVM installation providing the file "
                 "/usr/lib{32,64}/llvm-{VER}/lib/libclang.so.1. Make sure that "
@@ -648,29 +688,28 @@ def folder_version(d):
             )
             raise FileNotFoundError(msg)
 
-        if "LIBCLANG_PATH" in os.environ:
-            libclang_dir = os.environ["LIBCLANG_PATH"]
-        else:
-            libclang_dir = os.path.join(llvm_dir, "lib", "libclang.so.1")
-
         if not cindex.Config.loaded:
-            cindex.Config.set_library_file(libclang_dir)
+            cindex.Config.set_library_file(libclang_file)
         cpp_dirs = []
 
         if "-stdlib=libc++" not in args:
-            cpp_dirs.append(max(glob("/usr/include/c++/*"), default=None, key=folder_version))
+            cpp_dirs.append(max(glob("/usr/include/c++/*"), default=None, key=_folder_version))
 
             cpp_dirs.append(
-                max(glob(f"/usr/include/{platform.machine()}-linux-gnu/c++/*"), default=None, key=folder_version)
+                max(glob(f"/usr/include/{platform.machine()}-linux-gnu/c++/*"), default=None, key=_folder_version)
             )
-        else:
-            cpp_dirs.append(os.path.join(llvm_dir, "include", "c++", "v1"))
+        elif llvm_dir is not None:
+            cpp_dirs.append(str(PurePosixPath(llvm_dir) / "include" / "c++" / "v1"))
 
         if "CLANG_INCLUDE_DIR" in os.environ:
             cpp_dirs.append(os.environ["CLANG_INCLUDE_DIR"])
-        else:
+        elif llvm_dir is not None:
             cpp_dirs.append(
-                max(glob(os.path.join(llvm_dir, "lib", "clang", "*", "include")), default=None, key=folder_version)
+                max(
+                    glob(str(PurePosixPath(llvm_dir) / "lib" / "clang" / "*" / "include")),
+                    default=None,
+                    key=_folder_version,
+                )
             )
 
         cpp_dirs.append(f"/usr/include/{platform.machine()}-linux-gnu")
diff --git a/tests/read_args_test.py b/tests/read_args_test.py
index 833cd42..b536ad0 100644
--- a/tests/read_args_test.py
+++ b/tests/read_args_test.py
@@ -1,13 +1,184 @@
-from pybind11_mkdoc.mkdoc_lib import read_args
+import os
+
+import pytest
+from clang import cindex
+
+from pybind11_mkdoc import mkdoc_lib
+
+CLT = "/Library/Developer/CommandLineTools/"
+XCODE = "/Applications/Xcode.app/Contents/Developer/"
+
+
+@pytest.fixture
+def config_calls(monkeypatch):
+    """Record cindex.Config.set_library_* calls instead of configuring libclang."""
+    calls = {}
+    monkeypatch.setattr(cindex.Config, "loaded", False)
+    monkeypatch.setattr(cindex.Config, "set_library_file", lambda p: calls.__setitem__("file", p))
+    monkeypatch.setattr(cindex.Config, "set_library_path", lambda p: calls.__setitem__("path", p))
+    return calls
+
+
+@pytest.fixture
+def clean_env(monkeypatch):
+    for var in ["LIBCLANG_PATH", "LLVM_DIR_PATH", "CLANG_INCLUDE_DIR", "CPP_INCLUDE_DIRS"]:
+        monkeypatch.delenv(var, raising=False)
+
+
+@pytest.fixture
+def linux(monkeypatch):
+    monkeypatch.setattr(mkdoc_lib.platform, "system", lambda: "Linux")
+
+
+@pytest.fixture
+def darwin(monkeypatch):
+    monkeypatch.setattr(mkdoc_lib.platform, "system", lambda: "Darwin")
+
+
+@pytest.fixture
+def windows(monkeypatch):
+    monkeypatch.setattr(mkdoc_lib.platform, "system", lambda: "Windows")
+
+
+def fake_walk(subdirs):
+    return lambda top: iter([(top, list(subdirs), [])])
+
+
+@pytest.mark.usefixtures("linux", "clean_env")
+def test_linux_libclang_path_without_llvm_dir(monkeypatch, config_calls, tmp_path):
+    lib = tmp_path / "libclang.so.1"
+    lib.touch()
+    monkeypatch.setattr(mkdoc_lib, "glob", lambda _pattern: [])
+    monkeypatch.setenv("LIBCLANG_PATH", str(lib))
+
+    _, filenames = mkdoc_lib.read_args(["foo.h"])
+
+    assert config_calls["file"] == str(lib)
+    assert filenames == ["foo.h"]
+
+
+@pytest.mark.usefixtures("linux", "clean_env")
+def test_linux_libclang_path_without_llvm_dir_libcpp(monkeypatch, config_calls, tmp_path):
+    lib = tmp_path / "libclang.so.1"
+    lib.touch()
+    monkeypatch.setattr(mkdoc_lib, "glob", lambda _pattern: [])
+    monkeypatch.setenv("LIBCLANG_PATH", str(lib))
+
+    parameters, _ = mkdoc_lib.read_args(["-stdlib=libc++", "foo.h"])
+
+    assert config_calls["file"] == str(lib)
+    assert "-stdlib=libc++" in parameters
+
+
+@pytest.mark.usefixtures("linux", "clean_env", "config_calls")
+def test_linux_no_llvm_dir_no_env_raises(monkeypatch):
+    monkeypatch.setattr(mkdoc_lib, "glob", lambda _pattern: [])
+
+    with pytest.raises(FileNotFoundError):
+        mkdoc_lib.read_args(["foo.h"])
+
+
+@pytest.mark.usefixtures("linux", "clean_env", "config_calls")
+def test_linux_libclang_path_missing_raises(monkeypatch, tmp_path):
+    monkeypatch.setattr(mkdoc_lib, "glob", lambda _pattern: [])
+    monkeypatch.setenv("LIBCLANG_PATH", str(tmp_path / "does_not_exist.so.1"))
+
+    with pytest.raises(FileNotFoundError):
+        mkdoc_lib.read_args(["foo.h"])
+
+
+@pytest.mark.usefixtures("darwin", "clean_env")
+def test_macos_xcode_preferred(monkeypatch, config_calls):
+    existing = {
+        XCODE + "Toolchains/XcodeDefault.xctoolchain/usr/lib/libclang.dylib",
+        XCODE + "Platforms/MacOSX.platform/Developer/SDKs",
+        CLT + "usr/lib/libclang.dylib",
+        CLT + "SDKs",
+    }
+    monkeypatch.setattr(os.path, "exists", lambda p: p in existing)
+    monkeypatch.setattr(os, "walk", fake_walk(["MacOSX.sdk"]))
+
+    parameters, _ = mkdoc_lib.read_args(["foo.h"])
+
+    assert config_calls["path"] == XCODE + "Toolchains/XcodeDefault.xctoolchain/usr/lib"
+    idx = parameters.index("-isysroot")
+    assert parameters[idx + 1] == XCODE + "Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk"
+
+
+@pytest.mark.usefixtures("darwin", "clean_env")
+def test_macos_command_line_tools_fallback(monkeypatch, config_calls):
+    existing = {CLT + "usr/lib/libclang.dylib", CLT + "SDKs"}
+    monkeypatch.setattr(os.path, "exists", lambda p: p in existing)
+    monkeypatch.setattr(os, "walk", fake_walk(["MacOSX.sdk", "MacOSX26.0.sdk"]))
+
+    parameters, _ = mkdoc_lib.read_args(["foo.h"])
+
+    assert config_calls["path"] == CLT + "usr/lib"
+    idx = parameters.index("-isysroot")
+    assert parameters[idx + 1] == CLT + "SDKs/MacOSX.sdk"
+
+
+@pytest.mark.usefixtures("darwin", "clean_env")
+def test_macos_libclang_path_env(monkeypatch, config_calls, tmp_path):
+    lib = tmp_path / "libclang.dylib"
+    lib.touch()
+    monkeypatch.setenv("LIBCLANG_PATH", str(lib))
+    monkeypatch.setattr(os.path, "exists", lambda _p: False)
+
+    parameters, _ = mkdoc_lib.read_args(["foo.h"])
+
+    assert config_calls["file"] == str(lib)
+    assert "-isysroot" not in parameters
+
+
+@pytest.mark.usefixtures("darwin", "clean_env", "config_calls")
+def test_macos_libclang_path_env_missing_raises(monkeypatch, tmp_path):
+    monkeypatch.setenv("LIBCLANG_PATH", str(tmp_path / "does_not_exist.dylib"))
+
+    with pytest.raises(FileNotFoundError):
+        mkdoc_lib.read_args(["foo.h"])
+
+
+@pytest.mark.usefixtures("windows", "clean_env")
+def test_windows_libclang_path_env(monkeypatch, config_calls, tmp_path):
+    lib = tmp_path / "libclang.dll"
+    lib.touch()
+    monkeypatch.setenv("LIBCLANG_PATH", str(lib))
+
+    _, filenames = mkdoc_lib.read_args(["foo.h"])
+
+    assert config_calls["file"] == str(lib)
+    assert filenames == ["foo.h"]
+
+
+@pytest.mark.usefixtures("windows", "clean_env", "config_calls")
+def test_windows_libclang_path_env_missing_raises(monkeypatch, tmp_path):
+    monkeypatch.setenv("LIBCLANG_PATH", str(tmp_path / "does_not_exist.dll"))
+
+    with pytest.raises(FileNotFoundError):
+        mkdoc_lib.read_args(["foo.h"])
+
+
+@pytest.mark.usefixtures("darwin", "clean_env", "config_calls")
+def test_macos_sdk_newest_numeric(monkeypatch):
+    existing = {CLT + "usr/lib/libclang.dylib", CLT + "SDKs"}
+    monkeypatch.setattr(os.path, "exists", lambda p: p in existing)
+    # No MacOSX.sdk; lexical sort would wrongly pick MacOSX9.sdk as newest
+    monkeypatch.setattr(os, "walk", fake_walk(["MacOSX9.sdk", "MacOSX10.1.sdk"]))
+
+    parameters, _ = mkdoc_lib.read_args(["foo.h"])
+
+    idx = parameters.index("-isysroot")
+    assert parameters[idx + 1] == CLT + "SDKs/MacOSX10.1.sdk"
 
 
 def test_default_std():
-    parameters, filenames = read_args(["sample.h"])
+    parameters, filenames = mkdoc_lib.read_args(["sample.h"])
     assert "-std=c++17" in parameters
     assert filenames == ["sample.h"]
 
 
 def test_explicit_std_wins():
-    parameters, _ = read_args(["-std=c++11", "sample.h"])
+    parameters, _ = mkdoc_lib.read_args(["-std=c++11", "sample.h"])
     assert "-std=c++11" in parameters
     assert "-std=c++17" not in parameters