diff --git a/README.md b/README.md
index 0dcb0f1..fb05260 100644
--- a/README.md
+++ b/README.md
@@ -36,6 +36,17 @@ Omit `flutter-version` to track a channel instead (default `stable`):
 Run it after checkout and before any `flutter` command. It replaces roughly
 20 lines per job; we were carrying nine copies before extracting this.
 
+## Caching
+
+The pub cache step snapshots the directory `flutter pub get` writes to on
+the current runner, resolved from the `PUB_CACHE` env var that
+[subosito/flutter-action](https://github.com/subosito/flutter-action)
+exports for the job. That path is `~/.pub-cache` on Linux and macOS and the
+`LOCALAPPDATA` Pub Cache on Windows, so the same workflow caches the right
+directory on every runner OS. Leave the key (`${{ runner.os }}-pub-...`) as
+is for cross-OS safety: a cache built on Windows is not reused on Ubuntu,
+and vice versa.
+
 ## License
 
 AGPL-3.0
diff --git a/action.yml b/action.yml
index fd7f808..c21af1e 100644
--- a/action.yml
+++ b/action.yml
@@ -28,7 +28,14 @@ runs:
     - name: Cache pub
       uses: actions/cache@v6
       with:
-        path: ~/.pub-cache
+        # subosito/flutter-action@v2 exports PUB_CACHE to the job environment,
+        # pointing at the directory `flutter pub get` actually populates
+        # (~/.pub-cache on Linux and macOS, the LOCALAPPDATA Pub Cache on
+        # Windows). Cache that path directly so this step stays in sync with
+        # the SDK install step on every runner OS. Hardcoding ~/.pub-cache
+        # instead misses the real cache directory on Windows runners, where
+        # Flutter writes pub packages to %LOCALAPPDATA%\Pub\Cache by default.
+        path: ${{ env.PUB_CACHE }}
         key: ${{ runner.os }}-pub-${{ hashFiles('pubspec.lock') }}
         restore-keys: |
           ${{ runner.os }}-pub-