Refresh README/DOCS for new onboarding flow; bump add-on to 0.5.8

DOCS.md

@@ -1,107 +1,104 @@
 # OpenClaw Assistant (Home Assistant Add-on)
 
-This add-on runs a OpenClaw Assistant instance on Home Assistant OS (Supervisor add-on).
+This add-on runs **OpenClaw** inside **Home Assistant OS (HAOS)**.
 
-> Note: The upstream project has gone through renames. This add-on installs **OpenClaw**.
+The project deliberately keeps the add-on thin:
+- Home Assistant provides the container lifecycle + Ingress
+- OpenClaw provides onboarding/configuration and all assistant features
 
-## What this add-on provides
+## UI / Ingress behavior
 
-### 1) Ingress page (embedded)
-The add-on’s **Ingress UI** is intentionally kept simple and reliable:
-- a landing page
-- an **embedded web terminal** (optional)
-- a button/link that opens the **Gateway Web UI in a separate browser tab** (not embedded)
+### Ingress page (inside Home Assistant)
+The add-on’s Ingress UI is intentionally simple and reliable:
+- A landing page
+- An embedded **web terminal** (ttyd)
+- A button that opens the **Gateway Web UI** in a separate tab
 
-This avoids Home Assistant Ingress websocket edge-cases.
+### Gateway Web UI (separate tab)
+The Gateway Web UI requires WebSockets. Rather than tunneling it through HA Ingress,
+we open it directly using a user-provided base URL (`gateway_public_url`).
 
-### 2) Gateway Web UI (separate tab)
-The Gateway Web UI requires websockets. Instead of trying to tunnel that through HA Ingress,
-we open it directly using a user-provided public/base URL.
+## OpenClaw configuration philosophy
+
+### We do NOT overwrite OpenClaw config
+OpenClaw’s config/state lives under:
+- `/config/.openclaw/` (inside the container)
+
+The add-on **does not** rewrite OpenClaw’s configuration on each start.
+You should use OpenClaw’s own interactive tooling:
+- `openclaw setup`
+- `openclaw onboard`
+- `openclaw configure`
+
+### Minimal bootstrap (first boot only)
+If `/config/.openclaw/openclaw.json` is missing, the add-on bootstraps a minimal strict-JSON config so that
+`openclaw gateway run` can start:
+- `gateway.mode = local`
+- `gateway.auth.mode = token`
+- `gateway.auth.token` generated
+
+After that, onboarding/configure can expand the config normally.
 
 ## Installation
-1. Home Assistant → Settings → Add-ons → Add-on store
-2. Add repository URL:
-   - Add-on store → ⋮ → Repositories → paste the GitHub repo URL
-3. Install **OpenClaw Assistant**
 
-## Configuration overview
-All configuration is done via the add-on UI (Options).
+1) Home Assistant → Settings → Add-ons → Add-on store
+2) Add repository URL:
+- Add-on store → ⋮ → Repositories → paste:
+  - `https://github.com/techartdev/OpenClawHomeAssistant`
+3) Install **OpenClaw Assistant**
 
-### Required
-- `telegram_bot_token`
+## First-time setup checklist
 
-### Recommended baseline (safe defaults)
-- `gateway_bind: loopback`
-- `gateway_port: 18789`
-- `gateway_token: ""` (auto-generated by gateway when loopback)
-- `enable_terminal: false`
+1) Open the add-on page (Ingress)
+2) Use the terminal and run:
+   - `openclaw onboard`
+   - or `openclaw configure`
+3) Optional (recommended): set `gateway_public_url` in add-on options.
+   - Example (LAN): `http://192.168.1.10:18789`
+   - Example (public): `https://example.duckdns.org:12345`
 
-### Terminal (Ingress) setup
-To enable the embedded web terminal:
-- Set `enable_terminal: true`
+Once `gateway_public_url` is set and OpenClaw has a gateway token, the landing page will show an “Open Gateway Web UI” button.
 
-Then open the add-on Ingress page. You will see a terminal iframe.
+## Add-on options (custom / HA-specific)
 
-Security note: the terminal is powerful. Only enable if you trust HA admins with shell access
-inside the add-on container.
+### Terminal (Ingress)
+- `enable_terminal` (default `true`)
 
-### Gateway Web UI (separate tab) setup
-To open the gateway UI in a separate tab reliably:
+Security note: the terminal gives shell access inside the add-on container.
+Enable it only if you trust your HA admins.
 
-1) Expose the gateway:
-- Set `gateway_bind: lan`
-- Set `gateway_port` (default `18789`)
-- Set a **fixed** `gateway_token` (required when `gateway_bind=lan`)
+### Gateway UI link
+- `gateway_public_url` (optional)
 
-2) Tell the add-on what URL to open:
-- Set `gateway_public_url` to a base URL that the browser can reach (recommended: **no trailing slash**).
+This does not expose anything by itself; it just controls what URL the Ingress button opens.
 
-Examples:
-- LAN only: `http://homeassistant.local:18789` (or `http://192.168.1.10:18789`)
-- Public domain with port-forward: `https://example.duckdns.org:12345`
-  - (in that case your router/NAT must forward `12345` → HA host → gateway port)
+### Home Assistant token
+- `homeassistant_token` (optional)
 
-The Ingress landing page button will open:
-
-`<gateway_public_url>/?token=<gateway_token>`
-
-Notes:
-- This is intentionally **not embedded**.
-- This avoids the unreliable “ingress websocket proxy” path.
-
-## Optional options
-- `telegram_allow_from`: comma-separated Telegram user IDs (locks DMs)
-- `brave_api_key`: exported as `BRAVE_API_KEY` (for web search)
-- `homeassistant_token`: written to `/config/secrets/homeassistant.token` inside the container
+If set, it is written to:
+- `/config/secrets/homeassistant.token`
 
 ### Router SSH (generic)
-This add-on supports a **generic SSH configuration** for a router/firewall (or any LAN network device)
-when you want the assistant to automate local network changes (e.g., port forwarding, DNS records,
-firewall rules).
+These options are for custom automations that need SSH access to a router/firewall or other LAN device:
+- `router_ssh_host`
+- `router_ssh_user`
+- `router_ssh_key_path` (default `/data/keys/router_ssh`)
 
-Config fields:
-- `router_ssh_host`: host/IP of the router (reachable from the HA host network)
-- `router_ssh_user`: SSH username
-- `router_ssh_key_path`: path to the private key file inside the add-on (default: `/data/keys/router_ssh`)
-
-How to provide the SSH key:
-- Put the private key file under the add-on config directory so it appears in-container at `/data/keys/...`.
-- Ensure permissions are restricted (recommended `chmod 600`).
-
-Back-compat:
-- Older versions used MikroTik-branded names: `mikrotik_host`, `mikrotik_ssh_user`, `mikrotik_ssh_key_path`.
-  These are still accepted but **deprecated**.
+How to provide the key:
+- Put the private key file under the add-on config directory so it appears in-container at `/data/keys/...`
+- Recommended permissions: `chmod 600`
 
 ## Troubleshooting
 
-### Terminal doesn’t show
+### Ingress loads but Gateway button is missing
+- Set `gateway_public_url` in add-on options.
+- If `gateway_public_url` is set but the button is still hidden, OpenClaw likely has not produced a gateway token yet.
+  Use the terminal and run `openclaw onboard` / `openclaw configure`.
+
+### Gateway UI opens but doesn’t connect
+- Confirm the browser can reach `gateway_public_url` (LAN routing / DNS / NAT).
+- WebSockets must be allowed end-to-end.
+
+### Terminal isn’t visible
 - Ensure `enable_terminal=true`
-- Check add-on logs for `Starting web terminal (ttyd)`
-
-### Gateway button opens but UI says unauthorized
-- Ensure `gateway_token` is set when using `gateway_bind=lan`.
-- Ensure the opened URL includes `?token=...` (the add-on button does this automatically).
-
-### Gateway button opens but cannot connect
-- Confirm the browser can reach `gateway_public_url`.
-- Confirm your NAT/port-forward rules.
+- Check logs for `Starting web terminal (ttyd)`