Align provisioning recipes with profile mode

docs/API_REFERENCE.md

@@ -96,7 +96,8 @@ See [Network configuration](NETWORK_CONFIGURATION.md) for deployment constraints
 | --- | --- |
 | requestAsyncScan(forceRefresh) | Requests a non-blocking scan. |
 | getScanSnapshot(), getScanRuntimeState(), getScanState() | Returns scan lifecycle state. |
-| isScanRunning(), hasValidScanResults(), getScanResults() | Reads scan progress and cached visible results. |
+| isScanRunning(), hasValidScanResults() | Reads scan progress and cached-result validity. |
+| getScanResults() | Returns WiFiManager-owned cached visible results; do not retain references after a new scan or portal shutdown. |
 | getRSSIasQuality(rssi) | Converts RSSI to WiFiManager quality. |
 | getLastConxResult(), getWLStatusString(), getModeString() | Formats connection and mode diagnostics. |
 | hasEnteredConfigPortal(), getConfigPortalConnectState() | Reads portal-session history and last submission state. |

docs/NETWORK_CONFIGURATION.md

@@ -2,6 +2,8 @@
 
 These APIs configure WiFiManager's AP, station, scan, and reconnection behavior. Set them during boot, before starting a connection or portal flow, so an installer sees one consistent configuration.
 
+The current ESP8266 and ESP32 implementations apply AP static addressing through WiFi.softAPConfig() and station static addressing through WiFi.config(). Station static configuration is used by legacy connections, portal save-and-connect attempts, and the station-profile controller.
+
 This page is an advanced deployment reference. Use these settings only when the local network and the product's operating policy require them; WiFiManager's defaults are appropriate for many devices.
 
 ## Access-point setup network
@@ -18,6 +20,21 @@ This page is an advanced deployment reference. Use these settings only when the
 
 A hidden AP can make field setup harder because an installer must enter the SSID manually. Treat it as a deployment decision, not a general security control. If setHttpPort() changes the default, publish the full portal address in the product's installation procedure.
 
+## A fixed setup-portal address
+
+Give the setup AP a fixed address when an installer procedure needs a stable local portal address:
+
+~~~cpp
+wifi.setAPStaticIPConfig(
+    IPAddress(192, 168, 8, 1),
+    IPAddress(192, 168, 8, 1),
+    IPAddress(255, 255, 255, 0));
+wifi.setWiFiAPChannel(6);
+wifi.setWiFiAPHidden(false);
+~~~
+
+This is applied before WiFiManager starts its SoftAP. The usual portal address becomes http://192.168.8.1/. If setHttpPort() selects a non-default port, include that port in the installer instructions and expect the station handoff URL to include it too.
+
 ## Station address and credential behavior
 
 Use a station static address only when the network owner has reserved and documented it:
@@ -75,7 +92,7 @@ if (wifi.hasValidScanResults()) {
 | setScanDispPerc(enabled) | Uses percentage rather than quality icons in the portal. |
 | getRSSIasQuality(rssi) | Converts RSSI for display. |
 
-Read scan results as a snapshot. Do not retain references across a new scan or portal shutdown.
+WiFiManager owns the scan cache. It keeps the cache and its allocation while a portal is active so nearby networks can be rendered without repeated allocation churn; it clears and releases that storage when the portal fully closes. Treat getScanResults() as a snapshot and do not retain references, iterators, or pointers across a new scan or portal shutdown.
 
 ## Connection and timeout policy
 

docs/PORTAL_CONTENT.md

@@ -9,14 +9,18 @@ This matches the product-firmware pattern used by real consumers: load configura
 ~~~cpp
 #include <WiFiManager.h>
 
+constexpr int kBrokerHostLength = 64;
+
 WiFiManager wifi;
 WiFiManagerParameter brokerHost(
-    "broker_host", "MQTT broker", settings.mqttHost.c_str(), 64);
+    "broker_host", "MQTT broker", "", kBrokerHostLength);
 
 void setupPortal() {
+    // The application has already loaded settings before this point.
+    brokerHost.setValue(settings.mqttHost.c_str(), kBrokerHostLength);
     wifi.portalAddParameter(&brokerHost);
 
-    wifi.setSaveParamsCallback([](WiFiManager::WiFiManagerRequestArgs args) {
+    wifi.setSaveParamsCallback([](WiFiManager::WiFiManagerRequestArgs) {
         const String candidate = brokerHost.getValue();
 
         if (!isValidHostname(candidate)) {

docs/recipes/FIELD_INSTALLER_PROVISIONING.md

@@ -5,7 +5,7 @@ A field-installed controller or sensor often needs more time for setup than a de
 ## Flow
 
 1. Boot with the product's normal configuration.
-2. Try the configured station flow.
+2. Try the stored primary/fallback profile set.
 3. If Wi-Fi is unavailable, start the local setup AP and portal.
 4. Keep the portal available for the installation window.
 5. On a successful connection, let the application start services or reboot according to its own policy.
@@ -13,9 +13,12 @@ A field-installed controller or sensor often needs more time for setup than a de
 
 ~~~cpp
 constexpr unsigned long kInstallerWindowSeconds = 15 * 60;
+MyProfileStore profileStore;
 
 void setup() {
     configureProductPortal();
+    wifi.setStationProfileStore(&profileStore);
+    wifi.setStationRecoveryInterval(30000);
     wifi.setConfigPortalTimeout(kInstallerWindowSeconds);
 
     wifi.setAPCallback([](WiFiManager*) {
@@ -28,12 +31,12 @@ void setup() {
         recordSetupTimeout();
     });
 
-    wifi.autoConnect(deviceSetupName(), deviceSetupPassword());
+    wifi.startStationConnection(deviceSetupName(), deviceSetupPassword());
 }
 
 void loop() {
     wifi.process();
-    runApplicationWork();
+    // Do not start or recreate an application server while the portal owns its port.
 }
 ~~~
 
@@ -53,6 +56,8 @@ Use getConfigPortalActive(), didConfigPortalConnectSucceed(), and getConfigPorta
 
 ## Product boundary
 
-WiFiManager supplies the local portal and timer. The product decides what happens after timeout: keep retrying profiles, sleep, wait for a physical action, or operate in an offline mode. Do not treat autoConnect() returning false as a reason to reboot immediately; the portal may be the intended next state.
+WiFiManager supplies the local portal and timer. The product decides what happens after timeout: keep retrying profiles, sleep, wait for a physical action, or operate in an offline mode. If startStationConnection() returns false because no usable stored profile exists, the portal may be the intended next state rather than a reason to reboot immediately.
+
+For a product that deliberately uses one platform-saved network rather than primary/fallback profiles, the smaller legacy equivalent is wifi.autoConnect(deviceSetupName(), deviceSetupPassword()). It has the same local portal fallback, but no application-owned profile store, candidate verification, or fallback network.
 
 Continue with [Provisioning lifecycle](../PROVISIONING_LIFECYCLE.md) or [Provisioning state feedback](PROVISIONING_STATE_FEEDBACK.md).

docs/recipes/LOCAL_WEB_SERVICE_HANDOFF.md

@@ -7,17 +7,22 @@ A real consuming framework does this from the AP callback: it shuts down its nor
 ## Automatic recovery handoff
 
 ~~~cpp
+MyProfileStore profileStore;
+
 void setup() {
+    wifi.setStationProfileStore(&profileStore);
+    wifi.setStationRecoveryInterval(30000);
+
     wifi.setAPCallback([](WiFiManager*) {
         stopApplicationWebServer();  // Releases port 80 for WiFiManager.
         setIndicator(IndicatorState::Setup);
     });
 
-    wifi.autoConnect("Device Setup", "setup-password");
+    wifi.startStationConnection("Device Setup", "setup-password");
 }
 ~~~
 
-The AP callback runs after AP mode begins and before the portal routes are registered. It is the appropriate hook for automatic portal fallback. If the application explicitly starts setup itself, release its server before calling startConfigPortal().
+The AP callback runs after AP mode begins and before the portal routes are registered. It is the appropriate hook for automatic portal fallback. This profile-controller form matches the consuming firmware's recovery flow. If a product deliberately uses one platform-saved network instead, replace startStationConnection(...) with wifi.autoConnect(...); the same AP callback ordering applies. If the application explicitly starts setup itself, release its server before calling startConfigPortal().
 
 ## After a successful connection
 

docs/recipes/PRODUCT_SETTINGS_AND_WIFI.md

@@ -12,8 +12,12 @@ A connected device often needs more than an SSID and password: a device name, br
 6. Separately observe a successful Wi-Fi configuration/save if product services need a connected station first.
 
 ~~~cpp
+constexpr int kBrokerHostLength = 64;
+WiFiManagerParameter brokerHost(
+    "broker_host", "MQTT broker", "", kBrokerHostLength);
+
 void configurePortalFromSettings() {
-    brokerHost.setValue(settings.mqttHost.c_str(), 64);
+    brokerHost.setValue(settings.mqttHost.c_str(), kBrokerHostLength);
     wifi.portalAddParameter(&brokerHost);
 
     wifi.setSaveParamsCallback([](WiFiManager::WiFiManagerRequestArgs) {