From 72e80f236ecfc46ae51a853bfbf16f5254bc26aa Mon Sep 17 00:00:00 2001
From: Alex Hope-O'Connor <alex.hope.oconnor@pomonaqld.au>
Date: Sun, 20 Sep 2026 19:43:52 +1000
Subject: [PATCH] build: share maintained ESP32 cache

---
 docs/compatibility.md | 15 +++++++++------
 scripts/test.sh       |  7 ++++---
 2 files changed, 13 insertions(+), 9 deletions(-)

diff --git a/docs/compatibility.md b/docs/compatibility.md
index 7c85068..1e0c7de 100644
--- a/docs/compatibility.md
+++ b/docs/compatibility.md
@@ -27,9 +27,10 @@ two maintained lanes:
 | `esp32` | ESP32 Dev Module | pioarduino `55.03.311` / Arduino-ESP32 3.3.11 / ESP-IDF 5.5.5 | Maintained baseline |
 
 Every lane pins its complete framework stack. The ESP32 runner keeps its
-maintained pioarduino graph in a persistent repository cache so stale global
-metadata cannot select an uploader or compiler by accident. The ESP8266
-framework pin is independent of the ESP32 baseline; see the [linker
+maintained pioarduino graph in the persistent cache shared by these maintained
+framework repositories, so stale global metadata cannot select an uploader or
+compiler by accident without redownloading matching inputs for every repository.
+The ESP8266 framework pin is independent of the ESP32 baseline; see the [linker
 workaround](ESP8266-LINKER-WORKAROUND.md).
 
 Run the current ESP32 lane locally with:
@@ -39,10 +40,12 @@ Run the current ESP32 lane locally with:
 ./scripts/test.sh examples --platform esp32
 ```
 
-The script keeps that lane in a dedicated persistent PlatformIO Core/cache
-directory by default (`${XDG_CACHE_HOME:-$HOME/.cache}/arduinoha-platformio/core-3.3.11`).
+The script keeps that lane in the persistent PlatformIO Core/cache shared by
+the maintained framework repositories by default
+(`${XDG_CACHE_HOME:-$HOME/.cache}/arduino-framework-platformio/core-3.3.11`).
 This prevents stale global `tool-esptoolpy` metadata from shadowing the current
-pioarduino package-form uploader. Set `ARDUINOHA_PLATFORMIO_CORE_DIR`,
+pioarduino package-form uploader while avoiding duplicate Core 3.3.11
+downloads. Set `ARDUINOHA_PLATFORMIO_CORE_DIR`,
 `ARDUINOHA_PLATFORMIO_PACKAGES_DIR`, and
 `ARDUINOHA_PLATFORMIO_CACHE_DIR` for a dedicated disk. The script never clears
 that cache or repairs it by overriding one compiler package.
diff --git a/scripts/test.sh b/scripts/test.sh
index d565988..d273f75 100755
--- a/scripts/test.sh
+++ b/scripts/test.sh
@@ -21,10 +21,11 @@ pio_for_platform() {
     fi
 
     # Keep Core 3.3.11's package-form esptool and generated pioarduino
-    # environment in a persistent repository cache. It is never cleared by
-    # this script, and isolates this tested graph from stale global metadata.
+    # environment in the persistent cache shared by the maintained framework
+    # repositories. It is never cleared by this script, and isolates this
+    # tested graph from stale global metadata without duplicate downloads.
     local core_dir packages_dir cache_dir
-    core_dir="${ARDUINOHA_PLATFORMIO_CORE_DIR:-${XDG_CACHE_HOME:-$HOME/.cache}/arduinoha-platformio/core-3.3.11}"
+    core_dir="${ARDUINOHA_PLATFORMIO_CORE_DIR:-${XDG_CACHE_HOME:-$HOME/.cache}/arduino-framework-platformio/core-3.3.11}"
     packages_dir="${ARDUINOHA_PLATFORMIO_PACKAGES_DIR:-$core_dir/packages}"
     cache_dir="${ARDUINOHA_PLATFORMIO_CACHE_DIR:-$core_dir/cache}"
     install -d -m 700 "$core_dir" "$packages_dir" "$cache_dir"