diff --git a/README.md b/README.md
index 6084349ff7..ae21413552 100644
--- a/README.md
+++ b/README.md
@@ -1,599 +1,600 @@
-
-
-
-
-
- A smarter, self-hosted AI assistant — multi-user, multi-agent.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
- Highlights ·
- Overview ·
- Core Technology ·
- Features ·
- Roadmap ·
- Quick Start ·
- Contents
-
-
-
- English · 中文
-
-
----
-
-**Octop** is an open-source, self-hosted AI assistant. It's not just a tool — it's a digital life form that can operate in parallel. Through its multi-agent architecture, it builds an intelligent environment that is both independent and collaborative for teams, families, and individuals. Best of all, it runs entirely on your machine — the fully self-hosted design means privacy is never a compromise, while single-process startup makes the powerful web console, CLI, and IM integrations readily accessible.
-
-Chat through the Web Dashboard, Feishu, DingTalk, QQ, WeChat, Telegram, Discord, WeCom, or programmatic HTTP/SSE/WebSocket. Extend capabilities with the **expert library**, **Connectors** (OAuth + MCP), and **ACP** integration for IDE workflows.
-
-## ✨ Highlights
-
-| | Feature | Description |
-|---|---------|-------------|
-| 👥 | **Multi-user expert team** | One admin, shared household; built-in expert library and expert market — switch specialists per scenario |
-| 🤝 | **Cloud collaboration** | Link this Octop to another instance to browse peer experts and chat across instances; history stays on the expert's side |
-| 🎭 | **MBTI personas** | 16 personality templates plus an interactive quiz — give each agent a distinct character |
-| 🎯 | **AgentTeams** *(Beta)* | A coordinator schedules multiple experts on multi-step work; [details](docs/expert-teams.md) |
-| 🔒 | **Security built-in** | JWT multi-user isolation, tool approval, shell command guardrails, and PII redaction — data stays local |
-| 🔌 | **Connector ecosystem** | Tencent suite (Docs, Meeting, News, …); OAuth and MCP gateway extend resource boundaries — [supported connectors](docs/connectors.md) |
-| 💾 | **Pluggable workspace backends** | Local disk, Docker sandbox, PostgreSQL, or COS/S3 for agent files — separate from the control-plane DB |
-| 🧠 | **Portable memory** | Powered by [Octop Memory](https://github.com/TencentCloud/octop-memory); memory migrates with the workspace |
-| 📚 | **Knowledge base** | RAG over your documents; share corpora within a deployment and ground answers in your private data |
-| 🧩 | **Plugins** | Extend Octop with third-party plugins; bundled plugins are seeded and toggled on demand |
-| ↔️ | **ACP bidirectional** | `octop acp` for IDE/terminal AI; delegate to OpenCode / Claude Code with permission gates |
-| 💻 | **Terminal AI+** | Interactive shell in the browser — AI-assisted command execution and troubleshooting |
-| 🌐 | **Browser AI+** | Headless Chromium sessions for web automation, screenshots, and remote browsing |
-| 🖥️ | **Remote desktop** | Live screen and input from the dashboard on Linux, Windows, and macOS — remote office work and GUI apps; one-click isolated desktop on headless Linux |
-| 🪟 | **Desktop client** | Native Windows / macOS / Linux apps (and FnOS packages) alongside the web dashboard |
-| 🏠 | **Self-hosted** | Dashboard, CLI, IM channels, and cron in one `octop run` — all data under `~/.octop/` |
-
-## 📌 Overview
-
-Octop is a self-hosted AI assistant platform for households and small teams. It runs a single process that serves a web dashboard, a CLI, IM channels (Feishu, DingTalk, QQ, WeChat, Telegram, Discord, WeCom, and more), and cron automation — all sharing one control-plane database under `~/.octop/` (SQLite by default; PostgreSQL optional).
-
-> Octop's design goal: keep every conversation, workspace, and credential on your own machine, while giving each user a personal team of specialized agents they can switch between per task.
-
-
-🐾 What can you do with Octop
-
-- **Personal assistant** — let a dedicated agent write weekly reports, organize notes, and manage your schedule; memory persists with the workspace.
-- **Family sharing** — one admin account, the whole household; assign different agents and experts per member; share experts and knowledge bases when useful.
-- **Team helper** — AgentTeams or parallel agents, bridging Feishu / DingTalk / WeCom / WeChat to route tasks into group chats.
-- **Developer boost** — delegate coding tasks to OpenCode / Claude Code via ACP, or troubleshoot from the terminal with AI assistance.
-- **Web automation** — use Browser AI+ and remote desktop for forms, screenshots, and GUI apps.
-- **Scheduled tasks** — configure cron in natural language so the agent pushes or runs jobs on time every day.
-
-
-
-## 🧠 Core Technology
-
-| Layer | Technology |
-|-------|-----------|
-| **Language** | Python 3.12+ |
-| **Web framework** | FastAPI + uvicorn |
-| **Agent runtime** | [Octop Harness](https://github.com/TencentCloud/octop-harness) |
-| **Gateway** | [Octop Gateway](https://github.com/TencentCloud/octop-gateway) |
-| **Control plane DB** | SQLite (WAL, default) or PostgreSQL (optional) |
-| **Frontend** | React 18 + TypeScript + Vite + Ant Design |
-| **Scheduling** | APScheduler |
-| **ACP** | agent-client-protocol |
-| **Build / quality** | hatchling · ruff · mypy · pytest |
-
-Octop is built on the Octop Harness stack — a set of focused runtimes that Octop composes into one process:
-
-- **[Octop Harness](https://github.com/TencentCloud/octop-harness)** — Agent runtime: model routing, tools, skills, and conversation checkpointing.
-- **[Octop Gateway](https://github.com/TencentCloud/octop-gateway)** — multi-platform IM channel bridge that normalizes incoming messages into a single processing pipeline.
-- **[Octop Memory](https://github.com/TencentCloud/octop-memory)** — hierarchical recall with full-text search, so an agent's memory travels with its workspace.
-- **[Octop Browser](https://github.com/TencentCloud/octop-browser)** — CDP-based browser automation with persistent profiles for web tasks.
-
-Instead of an external queue or message broker, Octop routes every surface — Web UI, IM, and cron — through one in-process `HarnessProcessor`. The result is a single, restart-safe process whose entire state is rebuilt from the control-plane database on boot (local SQLite by default; PostgreSQL optional).
-
-## 🤔 Features
-
-### Server & auth
-- Multi-user JWT authentication with admin role
-- First-run setup wizard (`octop init`)
-- Interactive API docs at `/api/docs` (off by default — set `"enable_api_docs": true` in `config.json` to enable)
-
-### Experts
-- Multiple experts per user; each has its own workspace, providers, channels, and cron
-- 16 MBTI persona templates + custom system prompt
-- Expert library scanned at boot (`infra/agents/experts/library/`); expert market and in-deployment expert sharing
-- **AgentTeams** *(Beta)* — coordinator + member experts for multi-step tasks ([docs/expert-teams.md](docs/expert-teams.md))
-- Workspace backends (expert files): local disk, Docker sandbox, PostgreSQL, COS/S3, and other remote stores — distinct from the control-plane database
-
-### Channels & automation
-- IM channels: Feishu, DingTalk, QQ, WeChat, Telegram, Discord, WeCom, and more
-- Proactive cron jobs with natural-language and slash-command triggers
-- Unified message processing across Web UI, IM, and cron surfaces
-
-### Surfaces
-- **Web dashboard** — chat, experts / teams, connectors, channels, cron, knowledge, plugins, settings
-- **Desktop client** — native apps for Windows / macOS / Linux; FnOS packages for NAS
-- **CLI** — `octop run`, `octop chats`, `octop acp`, admin commands
-- **HTTP/SSE/WebSocket API** — full programmatic access
-- **Remote desktop** — dashboard control of the host desktop session
-
-### Knowledge & plugins
-- **Knowledge base** — RAG over your documents; optional sharing within the same deployment
-- **Plugins** — install and manage third-party plugins (`octop plugin`); bundled plugins are seeded and toggled on demand from the dashboard
-
-### ACP (Agent Client Protocol)
-
-Octop supports ACP in two directions:
-
-1. **Inbound** — external tools use **your** Octop agent
- ```bash
- octop acp --agent main # stdio ACP server for Zed, OpenCode, …
- ```
-
-2. **Outbound** — Octop delegates to external coding agents
- - Dashboard → **ACP** (`/acp`): configure runners (global per user)
- - Enable **acp_runner** per agent, then delegate in chat
-
-Built-in outbound runners include OpenCode, CodeBuddy, Claude Code, and Codex.
-
-Full setup: **[docs/acp.md](docs/acp.md)**.
-
-## 🧭 Roadmap
-
-Here are our mid-to-long term plans:
-
-**Shipped**
-- [x] **Shared resource pool** — a central pool of skills and sub-agents that any user can drop into a new expert without rebuilding from scratch.
-- [x] **Expert sharing** — publish your experts to other users in the same deployment, so good configurations are reused instead of recreated.
-- [x] **PC client** — native desktop apps for Windows / macOS / Linux alongside the web dashboard and IM channels.
-
-**In progress**
-- [ ] **AgentTeams** *(Beta)* — let one coordinator autonomously schedule and orchestrate multiple experts to tackle multi-step tasks.
-- [ ] **Mobile client** *(closed beta)* — native mobile apps currently in internal testing.
-
-**Planned**
-- [ ] **Browser & terminal polishing** — browser skill *recording* (capture a workflow and replay it as a skill) and a more capable terminal AI assistant.
-- [ ] **Self-evolution** — automatically distill everyday conversations into reusable skills, so the assistant grows with you.
-- [ ] **Managed Agents** — platform-hosted agent lifecycle (provision, scale, and operate agents without managing the full self-hosted stack yourself).
-- [ ] **Project** — project-scoped workspaces that group agents, files, and conversations around a shared goal.
-- [ ] **Cloud–edge continuum** — run Octop locally while offloading selected tasks to the cloud, so light work stays on-device and heavier jobs use remote capacity when you need it.
-- [ ] **Plugin marketplace** — a curated market to discover, install, and update third-party plugins without leaving Octop.
-- [ ] **Conversational control plane** — deepen Octop’s own skills so chat can cover the full dashboard surface: create experts, wire channels, manage knowledge bases, and scaffold plugins end-to-end.
-
-This roadmap may shift as the community grows; treat it as indicative only.
-
-## 🚀 Quick Start
-
-### Prerequisites
-
-- **macOS / Linux / Windows**
-- No pre-installed Python required — the installer uses [uv](https://docs.astral.sh/uv/) to provision Python 3.12 in an isolated venv under `~/.octop/`
-- A modern multi-core CPU with a few GB of RAM for the process plus model/embedding caches; enough disk for the database, agent workspaces, and document corpora
-
-### 1. Install
-
-**macOS / Linux** — one-line installer (recommended):
-
-```bash
-curl -fsSL https://finnie-1258344699.cos.ap-guangzhou.myqcloud.com/octop/install.sh | bash
-```
-
-**Windows (PowerShell)**:
-
-```powershell
-irm https://finnie-1258344699.cos.ap-guangzhou.myqcloud.com/octop/install.ps1 | iex
-```
-
-**Windows (cmd)** — download and run, or from a cloned repo:
-
-```bat
-curl -fsSL https://finnie-1258344699.cos.ap-guangzhou.myqcloud.com/octop/install.bat -o install.bat
-install.bat
-```
-
-After installation, open a **new terminal** or reload your shell:
-
-```bash
-source ~/.zshrc # Zsh
-# or
-source ~/.bashrc # Bash
-```
-
-The installer places `octop` on your PATH via `~/.octop/bin`. Optional extras:
-
-```bash
-# Download Playwright Chromium for browser automation (skipped if a system Chrome/Chromium is already present)
-curl -fsSL https://finnie-1258344699.cos.ap-guangzhou.myqcloud.com/octop/install.sh | bash -s -- --extras browser
-```
-
-See [scripts/README.md](scripts/README.md) for all install options (`--version`, `--from-source`, `--mirror`, Windows flags).
-
-**Desktop app** (GUI, no terminal) — grab the artifact for your platform from [GitHub Releases](https://github.com/TencentCloud/Octop/releases/latest):
-
-| Platform | Artifact |
-|----------|----------|
-| Windows | `Octop-desktop-windows-amd64-.exe` (64-bit) / `Octop-desktop-windows-arm64-.exe` (ARM64) — NSIS installer |
-| macOS | `Octop-desktop-darwin-arm64-.dmg` (Apple Silicon) / `Octop-desktop-darwin-amd64-.dmg` (Intel) |
-| Linux | `Octop-desktop-linux-amd64-.tar.gz` / `Octop-desktop-linux-arm64-.tar.gz` |
-| FnOS NAS | `Octop-fnos-docker-.fpk` (recommended on ARM; amd64/arm64 image) / `Octop-fnos-native-.fpk` (x86_64, no Docker) / `Octop-fnos-native-arm64-.fpk` (ARM64 fallback if no Docker) — install via App Center |
-
-See [desktop/README.md](desktop/README.md) for the desktop shell and [fnos/README.md](fnos/README.md) for the FnOS packaging guide.
-
-**Alternative — PyPI** (if you already manage Python yourself):
-
-```bash
-pip install octop
-# optional local ONNX embedding model cache (Models → Local): pip install "octop[local-embedding]"
-# Downloads catalog weights under ~/.octop/embedding_models; not chat, not Memory.
-# Browser automation uses the bundled Playwright package; install Chromium via the installer --extras browser,
-# the dashboard, or: python -m playwright install chromium
-```
-
-From a source checkout with uv:
-
-```bash
-uv sync --extra local-embedding
-```
-
-### 2. Initialize
-
-```bash
-octop init
-```
-
-The interactive wizard creates the SQLite database, JWT secret, and first admin account under `~/.octop/`.
-
-### 3. Run
-
-```bash
-# Foreground (API + Web dashboard)
-octop run
-
-# Custom host / port
-octop run --host 0.0.0.0 --port 8088
-
-# Register as a system service (systemd / launchd / Windows service)
-octop service start
-```
-
-Open **http://127.0.0.1:8088**. With Docker, a valid `OCTOP_DEFAULT_PASSWORD` creates the admin on first boot (credentials in `/data/.octop/credential.txt`); if it is unset or rejected, open the setup wizard (unlock password in `/data/.octop/octop-login.txt`). Interactive `octop init` / the setup wizard asks you to choose a password (≥8 characters, letters and digits).
-
-### Docker (recommended for production)
-
-```bash
-# Build and start
-docker compose -f docker/docker-compose.yml up -d
-
-# China mirror when ghcr.io is unreachable (no local build)
-docker compose -f docker/docker-compose.cn.yml up -d
-
-# Or build manually
-bash docker/docker_build.sh
-docker run -d \
- -p 8088:8088 \
- -v octop-data:/data/.octop \
- -e HOME=/data \
- -e OCTOP_DEFAULT_PASSWORD="" \
- octop:latest
-```
-
-Open `http://localhost:8088`. A valid `OCTOP_DEFAULT_PASSWORD` creates the admin on first boot and writes credentials to `/data/.octop/credential.txt`. If it is unset or rejected by the password policy, no admin is created — complete the setup wizard (unlock password in `/data/.octop/octop-login.txt`). Override the username via `OCTOP_ADMIN_USERNAME`.
-
-> **Password policy:** at least 8 characters with letters and digits.
-
-| Variable | Default | Description |
-|----------|---------|-------------|
-| `OCTOP_PORT` | `8088` | HTTP listen port |
-| `OCTOP_DEFAULT_PASSWORD` | _(unset)_ | First-run admin password (Docker bootstrap). Valid → create admin; unset or rejected → setup wizard |
-| `OCTOP_ADMIN_USERNAME` | `admin` | First-run admin username |
-| `OCTOP_DATA` | `~/.octop` | Host data directory (compose bind mount) |
-
-See [`.env.example`](.env.example) for the full list.
-
-To serve the dashboard under a reverse-proxy subpath (for example `https://example.com/octop/`), rebuild the frontend with `VITE_BASE_PATH=/octop/` and strip that prefix in the proxy (nginx `proxy_pass …/;`). The default build assumes the domain root.
-
-### Deploy with Cloud
-
-
- 
- 
-
-
-
-## 📑 Contents
-
-- [Highlights](#-highlights)
-- [Overview](#-overview)
-- [Core Technology](#-core-technology)
-- [Features](#-features)
-- [Roadmap](#-roadmap)
-- [Quick Start](#-quick-start)
-- **Deploy & Use**
- - [Install options](#-install-options)
- - [Configuration](#️-configuration)
- - [CLI reference](#-cli-reference)
- - [Web dashboard](#️-web-dashboard)
- - [Data directory](#-data-directory)
-- **Architecture & Dev**
- - [Architecture](#️-architecture)
- - [Project layout](#-project-layout)
- - [Development](#️-development)
-- **Project Info**
- - [Security & privacy](#-security--privacy)
- - [Contributing](#-contributing)
- - [Changelog](#-changelog)
- - [Related projects](#-related-projects)
- - [Community](#-community)
- - [License](#-license)
-
-## 📦 Install options
-
-| Method | Platform | Description |
-|--------|----------|-------------|
-| Remote one-liner | macOS / Linux | `curl …/octop/install.sh \| bash` |
-| Remote one-liner | Windows | `irm …/octop/install.ps1 \| iex` or `install.bat` |
-| Local script | macOS / Linux | `bash scripts/install.sh` |
-| Local script | Windows | `scripts\install.bat` or `install.ps1` |
-| PyPI | Any | `pip install octop` (optional extras such as `local-embedding`) |
-| Docker | Any | `docker/docker-compose.yml`; China mirror: `docker/docker-compose.cn.yml` |
-
-All install scripts provision an isolated environment at `~/.octop/venv` and a `~/.octop/bin/octop` wrapper — they do not touch system Python.
-
-### Upgrade
-
-`octop update` replaces only the wheel/binary — your `~/.octop/` database, workspaces, secrets, and `config.json` are preserved:
-
-```bash
-octop update # fetch and install the latest octop, then restart the service if one is registered
-```
-
-The schema migrates automatically on next boot; run `octop init` only if the setup wizard prompts for a migration. Always back up first (`octop backup`) before a cross-version upgrade.
-
-## ⚙️ Configuration
-
-All runtime state lives in `~/.octop/`. Manage it via CLI or edit files directly.
-
-```bash
-# LLM providers and models
-octop models
-octop provider list
-
-# IM channels
-octop channel list
-octop channel install
-
-# Skills (per agent)
-octop skills list --agent main
-
-# Cron jobs
-octop cron list
-octop cron create --help
-
-# Users (admin)
-octop user list
-```
-
-### Supported LLM providers
-
-OpenAI-compatible APIs, DashScope (Qwen), Ollama, and other presets — configure per agent in the dashboard or via `octop provider`.
-
-### Supported channels
-
-| Channel | Credentials |
-|---------|-------------|
-| **Feishu** | App ID, App Secret |
-| **DingTalk** | App Key, App Secret |
-| **QQ** | Bot AppID, Token |
-| **WeChat** | QR bind / account credentials; [CLI](docs/cli.md) |
-| **Telegram** | Bot Token |
-| **Discord** | Bot Token; all accessible channels allowed by default, optional channel/DM allowlists; [setup and testing](docs/discord-channel.md) |
-| **WeCom** | Corp ID, Agent Secret |
-| **Web Dashboard** | Enabled by default |
-
-Other kinds (e.g. Yuanbao, Xiaoyi, MQTT) are available via the gateway — see channel setup in the dashboard or CLI.
-
-### Supported connectors
-
-Built-in OAuth / MCP connectors include Tencent Docs, Tencent Meeting, Notion, TickTick, OpenAlex, Feishu CLI, WeCom CLI, Agent Mail, Obsidian, WeKnora, Dify, and more. Names and descriptions are localized (`en` / `zh`).
-
-Full catalog, auth kinds, and MCP modes: **[docs/connectors.md](docs/connectors.md)**. Custom MCP servers can be added in the dashboard.
-
-## 📖 CLI reference
-
-| Command | Description |
-|---------|-------------|
-| `octop init` | Bootstrap `~/.octop/` (DB, admin, JWT secret) |
-| `octop run` | Start Octop in the foreground |
-| `octop service start` | Install and start as a system service |
-| `octop service stop` | Stop the system service |
-| `octop agent` | Create, list, start/stop agents |
-| `octop channel` | Install and manage IM channels |
-| `octop chats` | REPL and session management |
-| `octop acp` | Stdio ACP server for IDE integration |
-| `octop cron` | Manage scheduled tasks |
-| `octop models` | Provider presets and model resolution |
-| `octop skills` | Enable/disable per-agent skills |
-| `octop plugin` | Install and manage third-party plugins |
-| `octop backup` | Export / restore backups |
-| `octop clean` | Remove CLI state or wipe `~/.octop/` |
-| `octop memory list` | List running agents eligible for memory maintenance; no database changes. |
-| `octop memory slim [--agent ID]` | Back up and slim SQLite memory through the running host; uses the selected agent or prompts by number. Shows terminal and dashboard progress. [Details](docs/memory-slim.md) |
-| `octop memory slim --all` | Sequentially maintain all eligible running agents, with per-agent progress; stops on the first failure. |
-| `octop update` | Check for and install updates |
-
-In signed-in dashboard or local CLI chat, `/memory slim` explains maintenance for the current agent;
-`/memory slim --all` lists your eligible agents. Add `--confirm` to start after reviewing the impact.
-Use `/memory status` for progress/results. Chat stays available until maintenance is confirmed and begins.
-External IM maintenance requires verified sender permissions and is not enabled yet.
-
-Full reference: **[docs/cli.md](docs/cli.md)**.
-
-## 🖥️ Web dashboard
-
-After `octop run`, open **http://127.0.0.1:8088**.
-
-
-
-
-
-- **Chat** — real-time conversation with experts and teams
-- **Experts** — create experts, pick templates / MBTI personas, share or publish experts, configure providers
-- **AgentTeams** *(Beta)* — coordinator + member experts for multi-step work
-- **Connectors** — OAuth apps and MCP gateways
-- **Channels** — IM platform setup
-- **Cron** — visual cron job management
-- **Knowledge base** — manage document corpora, semantic retrieval, and in-deployment sharing
-- **Plugins** — install, enable, and configure plugins
-- **Remote desktop** — live screen and input from the dashboard
-- **ACP** — configure outbound coding-agent runners
-- **Settings** — users, security, TLS, system
-
-Interactive API docs: **http://127.0.0.1:8088/api/docs** (disabled by default — enable by setting `"enable_api_docs": true` in `config.json`)
-
-## 📁 Data directory
-
-```
-~/.octop/ ← install & data root
-├── config.json # process config (optional database section)
-├── octop.db # SQLite — users, agents, channels, cron, …
-├── secrets/ # JWT secret, channel tokens
-├── agents// # per-agent workspace (SOUL.md, skills, …)
-├── security/tool_guard/ # shell command allow/deny rules
-├── logs/ # runtime logs
-├── venv/ # uv-managed Python (installer layout)
-└── bin/octop # PATH wrapper → venv/bin/octop
-```
-
-The control plane can also use PostgreSQL — set `database` in `config.json`, or `OCTOP_DATABASE_*` / the first-run wizard. With PostgreSQL, agent memory reuses the same DSN by default (per-agent schema); to keep file-based memory, set `"memory": { "backend": { "type": "sqlite" } }` in the agent config. See [docs/configuration.md](docs/configuration.md) and [docs/adr/002-database-backends.md](docs/adr/002-database-backends.md).
-
-See [docs/configuration.md](docs/configuration.md) for env vars and `config.json`.
-
-## 🏗️ Architecture
-
-```
-OctopServer
- ├─ DatabasePool SQLite (WAL) or PostgreSQL
- ├─ SharedServices DI root — every repo + config
- ├─ ExpertCatalog scans agents/experts/library/ at boot
- ├─ UserManager
- │ └─ HarnessAgentManager (per user)
- │ └─ AgentRuntime (per agent)
- │ ├─ HarnessAgent Agent runtime (octop-harness)
- │ ├─ HarnessProcessor IM / UI / cron entry point
- │ ├─ ChannelManager IM connections (octop-gateway)
- │ └─ CronManager APScheduler
- └─ FastAPI app (uvicorn)
-```
-
-Single process. Restart rebuilds state from the control-plane database (local SQLite by default; PostgreSQL optional).
-
-See [docs/architecture.md](docs/architecture.md), [docs/adr/001-single-process-model.md](docs/adr/001-single-process-model.md), and [docs/adr/002-database-backends.md](docs/adr/002-database-backends.md).
-
-## 📁 Project layout
-
-```
-src/octop/
- config.py env-var config
- launch.py OctopServer boot + uvicorn
- infra/ business core (agents, gateway, cron, db, users, …)
- api/ HTTP layer — FastAPI app, routers, JWT, SSE
- cli/ CLI layer — Click commands
- dashboard/ built React SPA (wheel artifact)
-
-dashboard/ frontend source (Vite) — edit here, run make build-frontend
-
-docker/ Docker Compose, entrypoint, build & deploy scripts
-tests/ unit/ + integration/
-```
-
-## 🛠️ Development
-
-**Prerequisites:** Python 3.12+, Node 18+, [uv](https://docs.astral.sh/uv/)
-
-```bash
-# Backend
-make install # pip install -e ".[dev]"
-make all # format-all + lint + typecheck + test (ship bar)
-
-# Frontend (separate terminal)
-make dev-frontend # Vite dev server on :5173 (override with VITE_DEV_PORT)
-make build-frontend # production build → src/octop/dashboard/
-cd dashboard && npx tsc -b
-```
-
-Individual targets: `make test`, `make lint`, `make typecheck`, `make format`.
-
-## 🔒 Security & privacy
-
-- **Local-first**: Config, chats, workspaces, and credentials live under `~/.octop/` on your machine.
-- **Multi-user isolation**: JWT auth with per-user agents and workspaces.
-- **PII redaction & tool approval**: sensitive data is redacted before it leaves the workspace, and risky tools or shell commands require explicit approval under the guardrail rules.
-- **Tool guardrails**: User-editable shell command rules under `~/.octop/security/tool_guard/`.
-- **No vendor lock-in**: Swap LLM providers, storage backends, and channels without rewriting agents.
-
-## 🤝 Contributing
-
-Contributions are welcome:
-
-1. Fork the repository
-2. Create a feature branch (`git checkout -b feature/amazing-feature`)
-3. Run `make all` (backend) or `make check-all` (full stack) before submitting
-4. Open a Pull Request
-
-See [CONTRIBUTING.md](CONTRIBUTING.md) for the full guide. Security issues: [SECURITY.md](SECURITY.md).
-
-Module boundaries and coding conventions: [AGENTS.md](AGENTS.md).
-
-## 📋 Changelog
-
-See [CHANGELOG.md](CHANGELOG.md) for release history.
-
-## 🔗 Related projects
-
-| Project | Description |
-|---------|-------------|
-| [Octop Harness](https://github.com/TencentCloud/octop-harness) | Agent runtime — model routing, tools, skills, checkpointing |
-| [Octop Gateway](https://github.com/TencentCloud/octop-gateway) | Multi-platform IM channel bridge |
-| [Octop Memory](https://github.com/TencentCloud/octop-memory) | Hierarchical recall and FTS search |
-| [Octop Browser](https://github.com/TencentCloud/octop-browser) | CDP browser automation with persistent profiles |
-| [Octop Pet](https://github.com/jubaoliang/OctopPet) | A desktop pet for Octop |
-
-## 💬 Community
-
-- **Discord** — join the English-speaking community: [discord.gg/QnWdhJxq9h](https://discord.gg/QnWdhJxq9h)
-
-### WeCom Customer Group (CN)
-
-For the customer WeCom support group, scan:
-
-
-
-
-
-> Please scan the QR code to join the group. For any questions or assistance, please contact the group admin directly.
-
-## 📄 License
-
-This project is licensed under the [MIT License](LICENSE).
-
-## ✨ Contributors
-
-Thanks to all contributors:
-
-
-
-
+
+
+
+
+
+ A smarter, self-hosted AI assistant — multi-user, multi-agent.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Highlights ·
+ Overview ·
+ Core Technology ·
+ Features ·
+ Roadmap ·
+ Quick Start ·
+ Contents
+
+
+
+ English · 中文
+
+
+---
+
+**Octop** is an open-source, self-hosted AI assistant. It's not just a tool — it's a digital life form that can operate in parallel. Through its multi-agent architecture, it builds an intelligent environment that is both independent and collaborative for teams, families, and individuals. Best of all, it runs entirely on your machine — the fully self-hosted design means privacy is never a compromise, while single-process startup makes the powerful web console, CLI, and IM integrations readily accessible.
+
+Chat through the Web Dashboard, Feishu, DingTalk, QQ, WeChat, Telegram, Discord, WeCom, or programmatic HTTP/SSE/WebSocket. Extend capabilities with the **expert library**, **Connectors** (OAuth + MCP), and **ACP** integration for IDE workflows.
+
+## ✨ Highlights
+
+| | Feature | Description |
+|---|---------|-------------|
+| 👥 | **Multi-user expert team** | One admin, shared household; built-in expert library and expert market — switch specialists per scenario |
+| 🤝 | **Cloud collaboration** | Link this Octop to another instance to browse peer experts and chat across instances; history stays on the expert's side |
+| 🎭 | **MBTI personas** | 16 personality templates plus an interactive quiz — give each agent a distinct character |
+| 🎯 | **AgentTeams** *(Beta)* | A coordinator schedules multiple experts on multi-step work; [details](docs/expert-teams.md) |
+| 🔒 | **Security built-in** | JWT multi-user isolation, tool approval, shell command guardrails, and PII redaction — data stays local |
+| 🔌 | **Connector ecosystem** | Tencent suite (Docs, Meeting, News, …); OAuth and MCP gateway extend resource boundaries — [supported connectors](docs/connectors.md) |
+| 💾 | **Pluggable workspace backends** | Local disk, Docker sandbox, PostgreSQL, or COS/S3 for agent files — separate from the control-plane DB |
+| 🧠 | **Portable memory** | Powered by [Octop Memory](https://github.com/TencentCloud/octop-memory); memory migrates with the workspace |
+| 📚 | **Knowledge base** | RAG over your documents; share corpora within a deployment and ground answers in your private data |
+| 🧩 | **Plugins** | Extend Octop with third-party plugins; bundled plugins are seeded and toggled on demand |
+| ↔️ | **ACP bidirectional** | `octop acp` for IDE/terminal AI; delegate to OpenCode / Claude Code with permission gates |
+| 💻 | **Terminal AI+** | Interactive shell in the browser — AI-assisted command execution and troubleshooting |
+| 🌐 | **Browser AI+** | Headless Chromium sessions for web automation, screenshots, and remote browsing |
+| 🖥️ | **Remote desktop** | Live screen and input from the dashboard on Linux, Windows, and macOS — remote office work and GUI apps; one-click isolated desktop on headless Linux |
+| 🪟 | **Desktop client** | Native Windows / macOS / Linux apps (and FnOS packages) alongside the web dashboard |
+| 🏠 | **Self-hosted** | Dashboard, CLI, IM channels, and cron in one `octop run` — all data under `~/.octop/` |
+
+## 📌 Overview
+
+Octop is a self-hosted AI assistant platform for households and small teams. It runs a single process that serves a web dashboard, a CLI, IM channels (Feishu, DingTalk, QQ, WeChat, Telegram, Discord, WeCom, and more), and cron automation — all sharing one control-plane database under `~/.octop/` (SQLite by default; PostgreSQL optional).
+
+> Octop's design goal: keep every conversation, workspace, and credential on your own machine, while giving each user a personal team of specialized agents they can switch between per task.
+
+
+🐾 What can you do with Octop
+
+- **Personal assistant** — let a dedicated agent write weekly reports, organize notes, and manage your schedule; memory persists with the workspace.
+- **Family sharing** — one admin account, the whole household; assign different agents and experts per member; share experts and knowledge bases when useful.
+- **Team helper** — AgentTeams or parallel agents, bridging Feishu / DingTalk / WeCom / WeChat to route tasks into group chats.
+- **Developer boost** — delegate coding tasks to OpenCode / Claude Code via ACP, or troubleshoot from the terminal with AI assistance.
+- **Web automation** — use Browser AI+ and remote desktop for forms, screenshots, and GUI apps.
+- **Scheduled tasks** — configure cron in natural language so the agent pushes or runs jobs on time every day.
+
+
+
+## 🧠 Core Technology
+
+| Layer | Technology |
+|-------|-----------|
+| **Language** | Python 3.12+ |
+| **Web framework** | FastAPI + uvicorn |
+| **Agent runtime** | [Octop Harness](https://github.com/TencentCloud/octop-harness) |
+| **Gateway** | [Octop Gateway](https://github.com/TencentCloud/octop-gateway) |
+| **Control plane DB** | SQLite (WAL, default) or PostgreSQL (optional) |
+| **Frontend** | React 18 + TypeScript + Vite + Ant Design |
+| **Scheduling** | APScheduler |
+| **ACP** | agent-client-protocol |
+| **Build / quality** | hatchling · ruff · mypy · pytest |
+
+Octop is built on the Octop Harness stack — a set of focused runtimes that Octop composes into one process:
+
+- **[Octop Harness](https://github.com/TencentCloud/octop-harness)** — Agent runtime: model routing, tools, skills, and conversation checkpointing.
+- **[Octop Gateway](https://github.com/TencentCloud/octop-gateway)** — multi-platform IM channel bridge that normalizes incoming messages into a single processing pipeline.
+- **[Octop Memory](https://github.com/TencentCloud/octop-memory)** — hierarchical recall with full-text search, so an agent's memory travels with its workspace.
+- **[Octop Browser](https://github.com/TencentCloud/octop-browser)** — CDP-based browser automation with persistent profiles for web tasks.
+
+Instead of an external queue or message broker, Octop routes every surface — Web UI, IM, and cron — through one in-process `HarnessProcessor`. The result is a single, restart-safe process whose entire state is rebuilt from the control-plane database on boot (local SQLite by default; PostgreSQL optional).
+
+## 🤔 Features
+
+### Server & auth
+- Multi-user JWT authentication with admin role
+- First-run setup wizard (`octop init`)
+- Interactive API docs at `/api/docs` (off by default — set `"enable_api_docs": true` in `config.json` to enable)
+
+### Experts
+- Multiple experts per user; each has its own workspace, providers, channels, and cron
+- 16 MBTI persona templates + custom system prompt
+- Expert library scanned at boot (`infra/agents/experts/library/`); expert market and in-deployment expert sharing
+- **AgentTeams** *(Beta)* — coordinator + member experts for multi-step tasks ([docs/expert-teams.md](docs/expert-teams.md))
+- Workspace backends (expert files): local disk, Docker sandbox, PostgreSQL, COS/S3, and other remote stores — distinct from the control-plane database
+
+### Channels & automation
+- IM channels: Feishu, DingTalk, QQ, WeChat, Telegram, Discord, WeCom, and more
+- Proactive cron jobs with natural-language and slash-command triggers
+- Unified message processing across Web UI, IM, and cron surfaces
+
+### Surfaces
+- **Web dashboard** — chat, experts / teams, connectors, channels, cron, knowledge, plugins, settings
+- **Desktop client** — native apps for Windows / macOS / Linux; FnOS packages for NAS
+- **CLI** — `octop run`, `octop chats`, `octop acp`, admin commands
+- **HTTP/SSE/WebSocket API** — full programmatic access
+- **Remote desktop** — dashboard control of the host desktop session
+
+### Knowledge & plugins
+- **Knowledge base** — RAG over your documents; optional sharing within the same deployment
+- **Plugins** — install and manage third-party plugins (`octop plugin`); bundled plugins are seeded and toggled on demand from the dashboard
+
+### ACP (Agent Client Protocol)
+
+Octop supports ACP in two directions:
+
+1. **Inbound** — external tools use **your** Octop agent
+ ```bash
+ octop acp --agent main # stdio ACP server for Zed, OpenCode, …
+ ```
+
+2. **Outbound** — Octop delegates to external coding agents
+ - Dashboard → **ACP** (`/acp`): configure runners (global per user)
+ - Enable **acp_runner** per agent, then delegate in chat
+
+Built-in outbound runners include OpenCode, CodeBuddy, Claude Code, and Codex.
+
+Full setup: **[docs/acp.md](docs/acp.md)**.
+
+## 🧭 Roadmap
+
+Here are our mid-to-long term plans:
+
+**Shipped**
+- [x] **Shared resource pool** — a central pool of skills and sub-agents that any user can drop into a new expert without rebuilding from scratch.
+- [x] **Expert sharing** — publish your experts to other users in the same deployment, so good configurations are reused instead of recreated.
+- [x] **PC client** — native desktop apps for Windows / macOS / Linux alongside the web dashboard and IM channels.
+
+**In progress**
+- [ ] **AgentTeams** *(Beta)* — let one coordinator autonomously schedule and orchestrate multiple experts to tackle multi-step tasks.
+- [ ] **Mobile client** *(closed beta)* — native mobile apps currently in internal testing.
+
+**Planned**
+- [ ] **Browser & terminal polishing** — browser skill *recording* (capture a workflow and replay it as a skill) and a more capable terminal AI assistant.
+- [ ] **Self-evolution** — automatically distill everyday conversations into reusable skills, so the assistant grows with you.
+- [ ] **Managed Agents** — platform-hosted agent lifecycle (provision, scale, and operate agents without managing the full self-hosted stack yourself).
+- [ ] **Project** — project-scoped workspaces that group agents, files, and conversations around a shared goal.
+- [ ] **Cloud–edge continuum** — run Octop locally while offloading selected tasks to the cloud, so light work stays on-device and heavier jobs use remote capacity when you need it.
+- [ ] **Plugin marketplace** — a curated market to discover, install, and update third-party plugins without leaving Octop.
+- [ ] **Conversational control plane** — deepen Octop’s own skills so chat can cover the full dashboard surface: create experts, wire channels, manage knowledge bases, and scaffold plugins end-to-end.
+
+This roadmap may shift as the community grows; treat it as indicative only.
+
+## 🚀 Quick Start
+
+### Prerequisites
+
+- **macOS / Linux / Windows**
+- No pre-installed Python required — the installer uses [uv](https://docs.astral.sh/uv/) to provision Python 3.12 in an isolated venv under `~/.octop/`
+- A modern multi-core CPU with a few GB of RAM for the process plus model/embedding caches; enough disk for the database, agent workspaces, and document corpora
+
+### 1. Install
+
+**macOS / Linux** — one-line installer (recommended):
+
+```bash
+curl -fsSL https://finnie-1258344699.cos.ap-guangzhou.myqcloud.com/octop/install.sh | bash
+```
+
+**Windows (PowerShell)**:
+
+```powershell
+irm https://finnie-1258344699.cos.ap-guangzhou.myqcloud.com/octop/install.ps1 | iex
+```
+
+**Windows (cmd)** — download and run, or from a cloned repo:
+
+```bat
+curl -fsSL https://finnie-1258344699.cos.ap-guangzhou.myqcloud.com/octop/install.bat -o install.bat
+install.bat
+```
+
+After installation, open a **new terminal** or reload your shell:
+
+```bash
+source ~/.zshrc # Zsh
+# or
+source ~/.bashrc # Bash
+```
+
+The installer places `octop` on your PATH via `~/.octop/bin`. Optional extras:
+
+```bash
+# Download Playwright Chromium for browser automation (skipped if a system Chrome/Chromium is already present)
+curl -fsSL https://finnie-1258344699.cos.ap-guangzhou.myqcloud.com/octop/install.sh | bash -s -- --extras browser
+```
+
+See [scripts/README.md](scripts/README.md) for all install options (`--version`, `--from-source`, `--mirror`, Windows flags).
+
+**Desktop app** (GUI, no terminal) — grab the artifact for your platform from [GitHub Releases](https://github.com/TencentCloud/Octop/releases/latest):
+
+| Platform | Artifact |
+|----------|----------|
+| Windows | `Octop-desktop-windows-amd64-.exe` (64-bit) / `Octop-desktop-windows-arm64-.exe` (ARM64) — NSIS installer |
+| macOS | `Octop-desktop-darwin-arm64-.dmg` (Apple Silicon) / `Octop-desktop-darwin-amd64-.dmg` (Intel) |
+| Linux | `Octop-desktop-linux-amd64-.tar.gz` / `Octop-desktop-linux-arm64-.tar.gz` |
+| FnOS NAS | `Octop-fnos-docker-.fpk` (recommended on ARM; amd64/arm64 image) / `Octop-fnos-native-.fpk` (x86_64, no Docker) / `Octop-fnos-native-arm64-.fpk` (ARM64 fallback if no Docker) — install via App Center |
+
+See [desktop/README.md](desktop/README.md) for the desktop shell and [fnos/README.md](fnos/README.md) for the FnOS packaging guide.
+
+**Alternative — PyPI** (if you already manage Python yourself):
+
+```bash
+pip install octop
+# optional local ONNX embedding model cache (Models → Local): pip install "octop[local-embedding]"
+# Downloads catalog weights under ~/.octop/embedding_models; not chat, not Memory.
+# Browser automation uses the bundled Playwright package; install Chromium via the installer --extras browser,
+# the dashboard, or: python -m playwright install chromium
+```
+
+From a source checkout with uv:
+
+```bash
+uv sync --extra local-embedding
+```
+
+### 2. Initialize
+
+```bash
+octop init
+```
+
+The interactive wizard creates the SQLite database, JWT secret, and first admin account under `~/.octop/`.
+
+### 3. Run
+
+```bash
+# Foreground (API + Web dashboard)
+octop run
+
+# Custom host / port
+octop run --host 0.0.0.0 --port 8088
+
+# Register as a system service (systemd / launchd / Windows service)
+octop service start
+```
+
+Open **http://127.0.0.1:8088**. With Docker, a valid `OCTOP_DEFAULT_PASSWORD` creates the admin on first boot (credentials in `/data/.octop/credential.txt`); if it is unset or rejected, open the setup wizard (unlock password in `/data/.octop/octop-login.txt`). Interactive `octop init` / the setup wizard asks you to choose a password (≥8 characters, letters and digits).
+
+### Docker (recommended for production)
+
+```bash
+# Build and start
+docker compose -f docker/docker-compose.yml up -d
+
+# China mirror when ghcr.io is unreachable (no local build)
+docker compose -f docker/docker-compose.cn.yml up -d
+
+# Or build manually
+bash docker/docker_build.sh
+docker run -d \
+ -p 8088:8088 \
+ -v octop-data:/data/.octop \
+ -e HOME=/data \
+ -e OCTOP_DEFAULT_PASSWORD="" \
+ octop:latest
+```
+
+Open `http://localhost:8088`. A valid `OCTOP_DEFAULT_PASSWORD` creates the admin on first boot and writes credentials to `/data/.octop/credential.txt`. If it is unset or rejected by the password policy, no admin is created — complete the setup wizard (unlock password in `/data/.octop/octop-login.txt`). Override the username via `OCTOP_ADMIN_USERNAME`.
+
+> **Password policy:** at least 8 characters with letters and digits.
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `OCTOP_PORT` | `8088` | HTTP listen port |
+| `OCTOP_DEFAULT_PASSWORD` | _(unset)_ | First-run admin password (Docker bootstrap). Valid → create admin; unset or rejected → setup wizard |
+| `OCTOP_ADMIN_USERNAME` | `admin` | First-run admin username |
+| `OCTOP_DATA` | `~/.octop` | Host data directory (compose bind mount) |
+
+See [`.env.example`](.env.example) for the full list.
+
+To serve the dashboard under a reverse-proxy subpath (for example `https://example.com/octop/`), rebuild the frontend with `VITE_BASE_PATH=/octop/` and strip that prefix in the proxy (nginx `proxy_pass …/;`). The default build assumes the domain root.
+
+### Deploy with Cloud
+
+
+ 
+ 
+
+
+
+## 📑 Contents
+
+- [Highlights](#-highlights)
+- [Overview](#-overview)
+- [Core Technology](#-core-technology)
+- [Features](#-features)
+- [Roadmap](#-roadmap)
+- [Quick Start](#-quick-start)
+- **Deploy & Use**
+ - [Install options](#-install-options)
+ - [Configuration](#️-configuration)
+ - [CLI reference](#-cli-reference)
+ - [Web dashboard](#️-web-dashboard)
+ - [Data directory](#-data-directory)
+- **Architecture & Dev**
+ - [Architecture](#️-architecture)
+ - [Project layout](#-project-layout)
+ - [Development](#️-development)
+- **Project Info**
+ - [Security & privacy](#-security--privacy)
+ - [Contributing](#-contributing)
+ - [Changelog](#-changelog)
+ - [Related projects](#-related-projects)
+ - [Community](#-community)
+ - [License](#-license)
+
+## 📦 Install options
+
+| Method | Platform | Description |
+|--------|----------|-------------|
+| Remote one-liner | macOS / Linux | `curl …/octop/install.sh \| bash` |
+| Remote one-liner | Windows | `irm …/octop/install.ps1 \| iex` or `install.bat` |
+| Local script | macOS / Linux | `bash scripts/install.sh` |
+| Local script | Windows | `scripts\install.bat` or `install.ps1` |
+| PyPI | Any | `pip install octop` (optional extras such as `local-embedding`) |
+| Docker | Any | `docker/docker-compose.yml`; China mirror: `docker/docker-compose.cn.yml` |
+
+All install scripts provision an isolated environment at `~/.octop/venv` and a `~/.octop/bin/octop` wrapper — they do not touch system Python.
+
+### Upgrade
+
+`octop update` replaces only the wheel/binary — your `~/.octop/` database, workspaces, secrets, and `config.json` are preserved:
+
+```bash
+octop update # fetch and install the latest octop, then restart the service if one is registered
+```
+
+The schema migrates automatically on next boot; run `octop init` only if the setup wizard prompts for a migration. Always back up first (`octop backup`) before a cross-version upgrade.
+
+## ⚙️ Configuration
+
+All runtime state lives in `~/.octop/`. Manage it via CLI or edit files directly.
+
+```bash
+# LLM providers and models
+octop models
+octop provider list
+
+# IM channels
+octop channel list
+octop channel install
+
+# Skills (per agent)
+octop skills list --agent main
+
+# Cron jobs
+octop cron list
+octop cron create --help
+
+# Users (admin)
+octop user list
+```
+
+### Supported LLM providers
+
+OpenAI-compatible APIs, DashScope (Qwen), Ollama, and other presets — configure per agent in the dashboard or via `octop provider`.
+
+### Supported channels
+
+| Channel | Credentials |
+|---------|-------------|
+| **Feishu** | App ID, App Secret |
+| **DingTalk** | App Key, App Secret |
+| **QQ** | Bot AppID, Token |
+| **WeChat** | QR bind / account credentials; [CLI](docs/cli.md) |
+| **Telegram** | Bot Token |
+| **Discord** | Bot Token; all accessible channels allowed by default, optional channel/DM allowlists; [setup and testing](docs/discord-channel.md) |
+| **WeCom** | Corp ID, Agent Secret |
+| **Web Dashboard** | Enabled by default |
+
+Other kinds (e.g. Yuanbao, Xiaoyi, MQTT) are available via the gateway — see channel setup in the dashboard or CLI.
+
+### Supported connectors
+
+Built-in OAuth / MCP connectors include Tencent Docs, Tencent Meeting, Notion, TickTick, OpenAlex, Feishu CLI, WeCom CLI, Agent Mail, Obsidian, WeKnora, Dify, and more. Names and descriptions are localized (`en` / `zh`).
+
+Full catalog, auth kinds, and MCP modes: **[docs/connectors.md](docs/connectors.md)**. Custom MCP servers can be added in the dashboard.
+
+## 📖 CLI reference
+
+| Command | Description |
+|---------|-------------|
+| `octop init` | Bootstrap `~/.octop/` (DB, admin, JWT secret) |
+| `octop run` | Start Octop in the foreground |
+| `octop service start` | Install and start as a system service |
+| `octop service stop` | Stop the system service |
+| `octop agent` | Create, list, start/stop agents |
+| `octop channel` | Install and manage IM channels |
+| `octop chats` | REPL and session management |
+| `octop acp` | Stdio ACP server for IDE integration |
+| `octop cron` | Manage scheduled tasks |
+| `octop models` | Provider presets and model resolution |
+| `octop skills` | Enable/disable per-agent skills |
+| `octop plugin` | Install and manage third-party plugins |
+| `octop backup` | Export / restore backups |
+| `octop clean` | Remove CLI state or wipe `~/.octop/` |
+| `octop memory list` | List running agents eligible for memory maintenance; no database changes. |
+| `octop memory slim [--agent ID]` | Back up and slim SQLite memory through the running host; uses the selected agent or prompts by number. Shows terminal and dashboard progress. [Details](docs/memory-slim.md) |
+| `octop memory slim --all` | Sequentially maintain all eligible running agents, with per-agent progress; stops on the first failure. |
+| `octop update` | Check for and install updates |
+
+In signed-in dashboard or local CLI chat, `/memory slim` explains maintenance for the current agent;
+`/memory slim --all` lists your eligible agents. Add `--confirm` to start after reviewing the impact.
+Use `/memory status` for progress/results. Chat stays available until maintenance is confirmed and begins.
+External IM maintenance requires verified sender permissions and is not enabled yet.
+
+Full reference: **[docs/cli.md](docs/cli.md)**.
+
+## 🖥️ Web dashboard
+
+After `octop run`, open **http://127.0.0.1:8088**.
+
+
+
+
+
+- **Chat** — real-time conversation with experts and teams
+- **Experts** — create experts, pick templates / MBTI personas, share or publish experts, configure providers
+- **AgentTeams** *(Beta)* — coordinator + member experts for multi-step work
+- **Connectors** — OAuth apps and MCP gateways
+- **Channels** — IM platform setup
+- **Cron** — visual cron job management
+- **Knowledge base** — manage document corpora, semantic retrieval, and in-deployment sharing
+- **Plugins** — install, enable, and configure plugins
+- **Remote desktop** — live screen and input from the dashboard
+- **ACP** — configure outbound coding-agent runners
+- **Settings** — users, security, TLS, system
+
+Interactive API docs: **http://127.0.0.1:8088/api/docs** (disabled by default — enable by setting `"enable_api_docs": true` in `config.json`)
+
+## 📁 Data directory
+
+```
+~/.octop/ ← install & data root
+├── config.json # process config (optional database section)
+├── octop.db # SQLite — users, agents, channels, cron, …
+├── secrets/ # JWT secret, channel tokens
+├── agents// # per-agent workspace (SOUL.md, skills, …)
+├── security/tool_guard/ # shell command allow/deny rules
+├── logs/ # runtime logs
+├── venv/ # uv-managed Python (installer layout)
+└── bin/octop # PATH wrapper → venv/bin/octop
+```
+
+The control plane can also use PostgreSQL — set `database` in `config.json`, or `OCTOP_DATABASE_*` / the first-run wizard. With PostgreSQL, agent memory reuses the same DSN by default (per-agent schema); to keep file-based memory, set `"memory": { "backend": { "type": "sqlite" } }` in the agent config. See [docs/configuration.md](docs/configuration.md) and [docs/adr/002-database-backends.md](docs/adr/002-database-backends.md).
+
+See [docs/configuration.md](docs/configuration.md) for env vars and `config.json`.
+
+## 🏗️ Architecture
+
+```
+OctopServer
+ ├─ DatabasePool SQLite (WAL) or PostgreSQL
+ ├─ SharedServices DI root — every repo + config
+ ├─ ExpertCatalog scans agents/experts/library/ at boot
+ ├─ UserManager
+ │ └─ HarnessAgentManager (per user)
+ │ └─ AgentRuntime (per agent)
+ │ ├─ HarnessAgent Agent runtime (octop-harness)
+ │ ├─ HarnessProcessor IM / UI / cron entry point
+ │ ├─ ChannelManager IM connections (octop-gateway)
+ │ └─ CronManager APScheduler
+ └─ FastAPI app (uvicorn)
+```
+
+Single process. Restart rebuilds state from the control-plane database (local SQLite by default; PostgreSQL optional).
+
+See [docs/architecture.md](docs/architecture.md), [docs/adr/001-single-process-model.md](docs/adr/001-single-process-model.md), and [docs/adr/002-database-backends.md](docs/adr/002-database-backends.md).
+
+## 📁 Project layout
+
+```
+src/octop/
+ config.py env-var config
+ launch.py OctopServer boot + uvicorn
+ infra/ business core (agents, gateway, cron, db, users, …)
+ api/ HTTP layer — FastAPI app, routers, JWT, SSE
+ cli/ CLI layer — Click commands
+ dashboard/ built React SPA (wheel artifact)
+
+dashboard/ frontend source (Vite) — edit here, run make build-frontend
+
+docker/ Docker Compose, entrypoint, build & deploy scripts
+tests/ unit/ + integration/
+```
+
+## 🛠️ Development
+
+**Prerequisites:** Python 3.12+, Node 18+, [uv](https://docs.astral.sh/uv/)
+
+```bash
+# Backend
+make install # pip install -e ".[dev]"
+make all # format-all + lint + typecheck + test (ship bar)
+
+# Frontend (separate terminal)
+make dev-frontend # Vite dev server on :5173 (override with VITE_DEV_PORT)
+make build-frontend # production build → src/octop/dashboard/
+cd dashboard && npx tsc -b
+```
+
+Individual targets: `make test`, `make lint`, `make typecheck`, `make format`.
+
+## 🔒 Security & privacy
+
+- **Local-first**: Config, chats, workspaces, and credentials live under `~/.octop/` on your machine.
+- **Multi-user isolation**: JWT auth with per-user agents and workspaces.
+- **PII redaction & tool approval**: sensitive data is redacted before it leaves the workspace, and risky tools or shell commands require explicit approval under the guardrail rules.
+- **Tool guardrails**: User-editable shell command rules under `~/.octop/security/tool_guard/`.
+- **No vendor lock-in**: Swap LLM providers, storage backends, and channels without rewriting agents.
+
+## 🤝 Contributing
+
+Contributions are welcome:
+
+1. Fork the repository
+2. Create a feature branch (`git checkout -b feature/amazing-feature`)
+3. Run `make all` (backend) or `make check-all` (full stack) before submitting
+4. Open a Pull Request
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for the full guide. Security issues: [SECURITY.md](SECURITY.md).
+
+Module boundaries and coding conventions: [AGENTS.md](AGENTS.md).
+
+## 📋 Changelog
+
+See [CHANGELOG.md](CHANGELOG.md) for release history.
+
+## 🔗 Related projects
+
+| Project | Description |
+|--------|-------------|
+| [Octop Harness](https://github.com/TencentCloud/octop-harness) | Agent runtime — model routing, tools, skills, checkpointing |
+| [Octop Gateway](https://github.com/TencentCloud/octop-gateway) | Multi-platform IM channel bridge |
+| [Octop Memory](https://github.com/TencentCloud/octop-memory) | Hierarchical recall and FTS search |
+| [Octop Browser](https://github.com/TencentCloud/octop-browser) | CDP browser automation with persistent profiles |
+| [Octop Pet](https://github.com/jubaoliang/OctopPet) | A desktop pet for Octop |
+| [OctopLink](https://github.com/dwc13775953197-spec/OctopLink) | HarmonyOS (ArkTS) native client — multi-agent, streaming, workspace, voice, memory, Bridge |
+
+## 💬 Community
+
+- **Discord** — join the English-speaking community: [discord.gg/QnWdhJxq9h](https://discord.gg/QnWdhJxq9h)
+
+### WeCom Customer Group (CN)
+
+For the customer WeCom support group, scan:
+
+
+
+
+
+> Please scan the QR code to join the group. For any questions or assistance, please contact the group admin directly.
+
+## 📄 License
+
+This project is licensed under the [MIT License](LICENSE).
+
+## ✨ Contributors
+
+Thanks to all contributors:
+
+
+
+