From e08c782559354623a52bce5a71edf5bb717dd2b8 Mon Sep 17 00:00:00 2001
From: Tao <dtzp555@gmail.com>
Date: Sat, 28 Feb 2026 15:42:38 +1000
Subject: [PATCH] docs: add FAQ/security/changelog

---
 README.md         |  8 +++++++
 docs/CHANGELOG.md | 26 +++++++++++++++++++++++
 docs/FAQ.md       | 53 +++++++++++++++++++++++++++++++++++++++++++++++
 docs/SECURITY.md  | 30 +++++++++++++++++++++++++++
 4 files changed, 117 insertions(+)
 create mode 100644 docs/CHANGELOG.md
 create mode 100644 docs/FAQ.md
 create mode 100644 docs/SECURITY.md

diff --git a/README.md b/README.md
index bc73250..97168bc 100644
--- a/README.md
+++ b/README.md
@@ -22,6 +22,14 @@ git pull --ff-only
 ```
 
 Open [http://localhost:3333](http://localhost:3333) in your browser. For remote access, use `bash start.sh --host 0.0.0.0`.
+## Docs
+
+- English guide: docs/USAGE_GUIDE.en.md
+- 中文使用说明: docs/USAGE_GUIDE.zh-CN.md
+- FAQ: docs/FAQ.md
+- Security notes: docs/SECURITY.md
+- Changelog: docs/CHANGELOG.md
+
 
 ## Features
 
diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.md
new file mode 100644
index 0000000..01bf05f
--- /dev/null
+++ b/docs/CHANGELOG.md
@@ -0,0 +1,26 @@
+# Changelog
+
+This is a user-facing summary derived from `DEVLOG.md`.
+
+## v0.7.6
+- Docs: annotated screenshots with arrows for key UI controls.
+
+## v0.7.5
+- Docs: built-in CLI terminal instructions + screenshot (tab completion, favorites, streaming output).
+
+## v0.7.4
+- Docs: English + Chinese usage guides with redacted screenshots.
+
+## v0.7.1
+- Dashboard guidance block for Telegram-first workflow + safety checklist.
+- Model dropdown options sourced from `openclaw models list`.
+
+## v0.7.0
+- Dashboard redesign with circular CPU/RAM/DISK gauges and auto-refresh.
+- Sub-agent creation flow rewritten (BotFather → group → group id → form) including allowlist helper.
+
+## v0.6.6
+- Fix: sub-agents correctly grouped under main for older config formats.
+
+## v0.6.5
+- New Dashboard tab + cache-busting headers and version checks.
diff --git a/docs/FAQ.md b/docs/FAQ.md
new file mode 100644
index 0000000..6d61bdc
--- /dev/null
+++ b/docs/FAQ.md
@@ -0,0 +1,53 @@
+# OCM FAQ
+
+## Q: Telegram 群里经常显示 typing，但不回消息？
+
+Most common cause is **BotFather Group Privacy** being ON.
+
+Fix:
+- BotFather → Your bot → Bot Settings → **Group Privacy** → **Turn off**
+
+Also check:
+- `openclaw status` (gateway healthy?)
+- provider auth/rate limits (OCM → Auth page, and gateway logs)
+
+## Q: 如何获取 Telegram Group ID（Peer ID / -100...）？
+
+Typical workflow:
+
+```bash
+openclaw gateway logs --follow
+```
+
+Send a message in the target group; the gateway logs usually contain the peer id.
+
+## Q: 模型下拉列表为什么没有我想要的模型？
+
+OCM sources model options from the real CLI output:
+
+```bash
+openclaw models list
+```
+
+So if it doesn't show up in OCM, make sure it's registered/available in your OpenClaw environment.
+
+## Q: Dashboard 里 Gateway HTTP Ping 显示 Unreachable？
+
+Common reasons:
+- Gateway not running
+- Gateway binds to a different interface/port than OCM expects
+- Local firewall/proxy interference
+
+Try:
+- `openclaw status`
+- `openclaw gateway restart`
+
+## Q: OCM 会把我的 token/个人信息上传出去吗？
+
+OCM is designed as a **local** dashboard.
+
+That said, your local OpenClaw config contains sensitive information. Follow the safety guidance:
+- keep agent Telegram groups private
+- don't share raw screenshots without redaction
+
+See: `docs/SECURITY.md`.
diff --git a/docs/SECURITY.md b/docs/SECURITY.md
new file mode 100644
index 0000000..1d9495d
--- /dev/null
+++ b/docs/SECURITY.md
@@ -0,0 +1,30 @@
+# Security Notes
+
+OCM is a **local web UI** for managing OpenClaw. Security depends heavily on how you run OpenClaw and how you use Telegram.
+
+## Recommended defaults
+
+- **Run locally** and restrict host binding unless you intentionally expose it.
+- Treat OpenClaw config as secrets: tokens, provider keys, account ids.
+- Prefer separate workspaces for each agent/sub-agent.
+
+## Telegram safety
+
+Strongly recommended:
+
+- **One Telegram group = one agent boundary** (context + purpose + workspace)
+- Keep each agent group **private**: only you + the bot (and optionally your second account)
+- Do **not** invite other people (cost + security risk)
+
+Critical BotFather settings:
+- Allow Groups = ON
+- Group Privacy = OFF
+
+## Sharing screenshots
+
+If you share screenshots publicly:
+- blur personal paths (e.g. `/Users/<name>/...`)
+- blur Telegram group/peer IDs (e.g. `-100xxxxxxxxxx`)
+- blur any tokens/keys if visible
+
+This repo contains **redacted + annotated** screenshots under `docs/annotated-screenshots/`.