diff --git a/DOCS.md b/DOCS.md
new file mode 100644
index 0000000..15170f1
--- /dev/null
+++ b/DOCS.md
@@ -0,0 +1,47 @@
+# Moltbot Assistant (Home Assistant Add-on)
+
+This add-on runs a Moltbot Assistant instance on Home Assistant OS (Supervisor add-on).
+
+> Note: Moltbot is the new name for the upstream Clawdbot project. Internally, this add-on may still use the `clawdbot` CLI/package as a compatibility layer.
+
+## Features
+- Ingress UI inside Home Assistant (no LAN port required)
+- Telegram channel support (bot token)
+- Optional Brave web search (Brave API key)
+- Optional Home Assistant long-lived token persisted in the add-on secrets folder
+- Optional web terminal inside Home Assistant (disabled by default)
+
+## 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 **Moltbot Assistant**
+
+## Configuration
+Configure via the add-on UI.
+
+Required:
+- `telegram_bot_token`
+
+Recommended:
+- `gateway_bind`: `loopback`
+- `gateway_token`: set a fixed token (Ingress proxy uses it server-side)
+
+Optional:
+- `telegram_allow_from`: comma-separated Telegram user IDs
+- `homeassistant_token`: written to `/config/secrets/homeassistant.token`
+- `brave_api_key`: exported as `BRAVE_API_KEY` (for web search)
+- `enable_terminal`: enables web terminal at `/terminal/`
+
+## UI / Ingress
+- The add-on uses **Ingress**. Open the add-on page to access the gateway UI.
+- If `enable_terminal=true`, the terminal is available under the same ingress base at `/terminal/`.
+
+## Security notes
+- Keep `gateway_bind=loopback` unless you know what you’re doing.
+- Terminal is powerful: only enable it if you trust all Home Assistant admins with shell access to the add-on container.
+
+## Troubleshooting
+- If Ingress loads but the gateway UI is unauthorized, verify `gateway_token` is set.
+- If Telegram doesn’t connect, verify the bot token using @BotFather and check add-on logs.
+- If search tools fail, check that `brave_api_key` is set and that your plan limits aren’t exceeded.
diff --git a/moltbot_assistant/icon.png b/moltbot_assistant/icon.png
new file mode 100644
index 0000000..533cc81
Binary files /dev/null and b/moltbot_assistant/icon.png differ
diff --git a/moltbot_assistant/logo.png b/moltbot_assistant/logo.png
new file mode 100644
index 0000000..533cc81
Binary files /dev/null and b/moltbot_assistant/logo.png differ
diff --git a/moltbot_assistant/run.sh b/moltbot_assistant/run.sh
index 4b06348..a7dd765 100644
--- a/moltbot_assistant/run.sh
+++ b/moltbot_assistant/run.sh
@@ -64,7 +64,7 @@ fi
 # Session lock cleanup helpers
 # ------------------------------------------------------------------------------
 
-# Returns 0 if a clawdbot gateway process appears to be running, else 1
+# Returns 0 if a gateway process appears to be running, else 1
 gateway_running() {
   pgrep -f "clawdbot.*gateway.*run" >/dev/null 2>&1
 }
@@ -214,7 +214,7 @@ EOF
 RUN_DOCTOR=$(jq -r '.run_doctor_on_start // false' "$OPTIONS_FILE")
 
 if [ "$RUN_DOCTOR" = "true" ]; then
-  echo "Running clawdbot doctor (auto-fix) ..."
+  echo "Running assistant doctor (auto-fix) ..."
   (timeout 60s clawdbot doctor --fix --yes) || true
 else
   echo "Skipping clawdbot doctor on startup (run_doctor_on_start=false)"
@@ -253,7 +253,7 @@ trap shutdown INT TERM
 NGINX_PID=""
 TTYD_PID=""
 
-echo "Starting Clawdbot Gateway..."
+echo "Starting Moltbot Assistant gateway (clawdbot-compatible)..."
 clawdbot gateway run &
 GW_PID=$!