Merge pull request #136 from memovai/docs/wifi-onboarding-ap-guide

README.md

@@ -291,6 +291,7 @@ Technical details live in the `docs/` folder:
 
 - **[docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)** — system design, module map, task layout, memory budget, protocols, flash partitions
 - **[docs/TODO.md](docs/TODO.md)** — feature gap tracker and roadmap
+- **[docs/WIFI_ONBOARDING_AP.md](docs/WIFI_ONBOARDING_AP.md)** — how the local `MimiClaw-XXXX` onboarding/admin AP flow works
 - **[docs/tool-setup/](docs/tool-setup/README.md)** — configuration guides for external service integrations (Tavily, etc.)
 
 ## Contributing

README_CN.md

@@ -306,6 +306,7 @@ MimiClaw 内置 cron 调度器，让 AI 可以自主安排任务。LLM 可以通
 
 - **[docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)** — 系统设计、模块划分、任务布局、内存分配、协议、Flash 分区
 - **[docs/TODO.md](docs/TODO.md)** — 功能差距和路线图
+- **[docs/WIFI_ONBOARDING_AP.md](docs/WIFI_ONBOARDING_AP.md)** — 说明本地 `MimiClaw-XXXX` onboarding / 管理热点的使用方式
 - **[docs/im-integration/](docs/im-integration/README.md)** — IM 通道集成指南（飞书等）
 
 ## 贡献

README_JA.md

@@ -291,6 +291,7 @@ MimiClawにはcronスケジューラが内蔵されており、AIが自律的に
 
 - **[docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)** — システム設計、モジュール構成、タスクレイアウト、メモリバジェット、プロトコル、Flashパーティション
 - **[docs/TODO.md](docs/TODO.md)** — 機能ギャップとロードマップ
+- **[docs/WIFI_ONBOARDING_AP.md](docs/WIFI_ONBOARDING_AP.md)** — ローカル `MimiClaw-XXXX` onboarding / 管理アクセスポイントの使い方
 - **[docs/im-integration/](docs/im-integration/README.md)** — IMチャネル統合ガイド（Feishuなど）
 
 ## 貢献

docs/WIFI_ONBOARDING_AP.md

@@ -0,0 +1,100 @@
+# Wi-Fi AP Onboarding Guide
+
+This guide documents the Wi-Fi onboarding flow for firmware builds that include the MimiClaw onboarding portal.
+
+## What It Does
+
+When onboarding is enabled, MimiClaw can expose a local Wi-Fi access point such as `MimiClaw-XXXX` and serve a configuration page at `http://192.168.4.1`.
+
+Typical uses:
+
+- first-time Wi-Fi setup without editing firmware
+- updating saved Wi-Fi, model, proxy, or bot credentials later
+- recovering a device that can no longer join the previous router
+
+## Requirements
+
+- a firmware build with the Wi-Fi onboarding portal enabled
+- an ESP32-S3 board powered on and booted normally
+- a phone or laptop that can join the temporary `MimiClaw-XXXX` network
+
+## First-Time Setup
+
+1. Power on the device.
+2. Wait for the onboarding hotspot `MimiClaw-XXXX` to appear.
+3. Join that hotspot from your phone or laptop.
+4. Open `http://192.168.4.1` if the captive page does not open automatically.
+5. Fill in at least:
+   - `SSID`
+   - `Password`
+6. Add optional settings if needed:
+   - `API Key`
+   - `Model`
+   - `Provider`
+   - `Telegram`
+   - `Feishu`
+   - `Proxy`
+   - `Search`
+7. Click `Save & Restart`.
+8. Wait for the device to reboot and join your normal Wi-Fi network.
+
+## Updating Settings Later
+
+If the firmware keeps the admin AP online after normal Wi-Fi connection, you can reconnect to `MimiClaw-XXXX` later and open `http://192.168.4.1` again.
+
+The page should prefill the currently effective configuration so you can edit only the fields you want to change.
+
+## Config Priority
+
+The onboarding page follows the same config priority as the firmware:
+
+1. saved NVS values
+2. build-time defaults from `main/mimi_secrets.h`
+
+That means:
+
+- if a field exists in NVS, it overrides the build-time default
+- if you clear a saved field and reboot, the device falls back to `main/mimi_secrets.h`
+- if both NVS and build-time values are empty, the field stays empty
+
+## Clearing Saved Values
+
+On firmware versions that support clearing fields from the portal:
+
+- leaving a field blank and saving removes the corresponding NVS key
+- after reboot, the page shows the build-time fallback if one exists
+
+If you need to wipe all saved runtime settings, use:
+
+```text
+mimi> config_reset
+```
+
+## Troubleshooting
+
+### No `MimiClaw-XXXX` hotspot appears
+
+- verify that the running firmware actually includes the onboarding portal
+- if the device already connects successfully and does not keep the admin AP online, clear Wi-Fi config and reboot
+- confirm the board has finished booting before scanning for Wi-Fi
+
+### The page still shows old values
+
+- refresh the page manually
+- reconnect to the AP and open `http://192.168.4.1` again
+- if needed, restart the browser once to clear stale captive portal state
+
+### The build-time provider/model do not show up
+
+If the device already has `model` or `provider` saved in NVS, the saved values win over `main/mimi_secrets.h`.
+
+To return to build-time defaults:
+
+- clear those fields in the portal and save, or
+- run `config_reset`
+
+## Notes
+
+- The onboarding AP is typically local-only and intended for nearby configuration.
+- Current onboarding implementations may use an open AP for simplicity, so avoid leaving it exposed longer than necessary.
+- If your deployment needs stronger local protection, add an AP password before using the flow in production.

docs/tool-setup/README.md

@@ -2,6 +2,10 @@
 
 Configuration guides for MimiClaw's external service integrations.
 
+Related local setup guide:
+
+- [Wi-Fi AP Onboarding Guide](../WIFI_ONBOARDING_AP.md) — configure firmware builds that expose the local `MimiClaw-XXXX` onboarding/admin access point
+
 ## Guides
 
 | Guide | Service | Description |