docs: improve portal guidance and examples

docs/DEVELOPMENT.md

@@ -7,12 +7,21 @@ lib_deps =
     WiFiManager=symlink:///path/to/WiFiManager
 ```
 
-The ESP32 environments pin the PlatformIO-compatible pioarduino 51.03.05
-platform package, which packages official Arduino-ESP32 3.0.5. This avoids the
-known six-second asynchronous scan failure in the older 2.0.17 framework. Core
-3 also requires the `SOC_WIFI_SUPPORTED`, `Network/src`, and ESP8266-transport
-ignore settings shown in this repository `platformio.ini`; keep those settings
-when adding an ESP32 environment.
+## Target pins
+
+The ESP32 test environments pin the pioarduino `51.03.05` platform package,
+which selects Arduino-ESP32 3.0.5 / ESP-IDF 5.1.4+. This is a test-target
+contract, not a library-manifest dependency: a consuming application chooses
+its own `platform` and must validate the complete framework/toolchain stack.
+Core 3 Wi-Fi builds need the C++14, `SOC_WIFI_SUPPORTED`, `Network/src`, and
+ESP8266-transport ignore settings in this repository's `platformio.ini`; keep
+those settings together when adding an ESP32 environment.
+
+ESP8266 test environments pin framework commit `521ae60` for the upstream
+Postmortem large-jump linker fix. The exact rationale and update rule are in
+the shared [ESP8266 linker-workaround note](https://github.com/alexhopeoconnor/arduino-home-assistant/blob/main/docs/ESP8266-LINKER-WORKAROUND.md).
+For the pioarduino release-to-Core mapping and the scoped repair for a stale
+global PlatformIO tool package, see [DeviceFramework's toolchain guide](https://github.com/alexhopeoconnor/DeviceFramework/blob/main/docs/TOOLCHAINS.md).
 
 Start a release with `bump-version.sh`. It updates package metadata and canonical installation snippets, then creates the changelog section. Replace its generated TODO with the release summary and update any behavioural documentation before running:
 
@@ -22,6 +31,8 @@ Start a release with `bump-version.sh`. It updates package metadata and canonica
 ./scripts/check-docs.sh
 ./scripts/test.sh compile --platform esp8266
 ./scripts/test.sh compile --platform esp32
+./scripts/test.sh examples --platform esp8266
+./scripts/test.sh examples --platform esp32
 ./scripts/prepare-release.sh vMAJOR.MINOR.PATCH --tag
 ```
 

docs/PORTAL_API.md

@@ -65,7 +65,7 @@ A normal accepted save returns 202 and directs the portal to poll /api/wifi/conn
 
 ~~~json
 {
-  "state": "idle | waiting | success | failed",
+  "state": "success",
   "message": "human readable status",
   "wifiStatus": "WL_CONNECTED",
   "stationIp": "192.168.1.42",
@@ -73,7 +73,11 @@ A normal accepted save returns 202 and directs the portal to poll /api/wifi/conn
 }
 ~~~
 
-stationIp and redirectUrl are present only after success. If WiFiManager uses a non-default HTTP port, redirectUrl includes it.
+`state` is one of `idle`, `waiting`, `success`, or `failed`. The example shows
+a successful join; `stationIp` and `redirectUrl` are present only in that state.
+If the portal server is not on port 80, `redirectUrl` includes that port. When
+connect-on-save is disabled, a saved configuration has no station address and
+the built-in portal remains open.
 
 After observing success, the built-in portal POSTs /api/wifi/connect-complete. A 409 response means successful handoff is not ready; otherwise WiFiManager keeps the portal alive briefly, receives the acknowledgement, and then closes after a grace delay. Browser captive redirects can still fail, so the portal keeps the station address visible.
 

docs/STATION_PROFILES.md

@@ -18,18 +18,36 @@ A candidate submitted by the portal or another application subsystem is only com
 
 ## Direct WiFiManager use
 
-Implement a small store appropriate to the application. WiFiManager neither allocates nor owns it:
+Implement a small store appropriate to the application. The manager neither allocates nor owns it. This complete in-memory version makes the ownership and return contract visible; use the buildable EEPROM example when the profiles must survive a restart:
 
-~~~cpp
-class MyProfileStore final : public WiFiManagerStationProfileStore {
+```cpp
+class MemoryProfileStore final : public WiFiManagerStationProfileStore {
 public:
-    bool load(WiFiManagerStationProfiles& profiles) override;
-    bool save(const WiFiManagerStationProfiles& profiles) override;
-    bool clear() override;
+    bool load(WiFiManagerStationProfiles& profiles) override {
+        if (!hasProfiles_) return false;  // No saved primary profile: open the portal.
+        profiles = profiles_;
+        return true;
+    }
+
+    bool save(const WiFiManagerStationProfiles& profiles) override {
+        profiles_ = profiles;
+        hasProfiles_ = true;
+        return true;  // A durable store must return false when its write fails.
+    }
+
+    bool clear() override {
+        profiles_ = {};
+        hasProfiles_ = false;
+        return true;
+    }
+
+private:
+    WiFiManagerStationProfiles profiles_{};
+    bool hasProfiles_ = false;
 };
 
 WiFiManager wifi;
-MyProfileStore profiles;
+MemoryProfileStore profiles;  // Must outlive WiFiManager's asynchronous connection work.
 
 void setup() {
     wifi.setStationProfileStore(&profiles);
@@ -38,11 +56,11 @@ void setup() {
 }
 
 void loop() {
-    wifi.process();
+    wifi.process();  // Advances profile retries and serves the fallback portal.
 }
-~~~
+```
 
-The store must return a complete WiFiManagerStationProfiles value. Each enabled profile has a NUL-terminated SSID of at most 32 characters and an optional NUL-terminated password of at most 64 characters. Keep slot 0 enabled; set hasPassword to false for an open network.
+This memory-only store intentionally loses profiles on restart. The store must return a complete `WiFiManagerStationProfiles` value. Each enabled profile has a NUL-terminated SSID of at most 32 characters and an optional NUL-terminated password of at most 64 characters. Keep slot 0 enabled; set `hasPassword = false` for an open network.
 
 When load() returns false, WiFiManager treats the profile set as unavailable and opens the normal configuration portal. When save() or clear() returns false, getStationStatus().storageSaveFailed is set and the status message explains the failure.