docs: rewrite top-level README — full component map

List all 7 submodules with stack/role, correct architecture and ports,
replace stale Issues model with tasks/milestones/proposals, add Security
notes (mandatory strong SECRET_KEY) and cross-links to component READMEs.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

.gitmodules

@@ -24,6 +24,3 @@
 	path = HarborForge.Cli
 	url = https://git.hangman-lab.top/zhi/HarborForge.Cli.git
 	branch = main
-[submodule "HarborForge.PlexumPlugin"]
-	path = HarborForge.PlexumPlugin
-	url = https://git.hangman-lab.top/zhi/HarborForge.PlexumPlugin.git

README.md

@@ -1,148 +1,128 @@
 # HarborForge
 
-Agent / human collaborative task-management platform — manages the full
+Agent / 人类协同任务管理平台 —— 用严格的状态机管理 提案 → 里程碑 → 任务 的完整生命周期，配套 CLI、监控与 OpenClaw 集成。
-proposal → milestone → task lifecycle with strict state machines, plus a
-CLI, monitoring, and OpenClaw integration.
 
-## Repository layout
+## 项目结构
 
-This is the umbrella repository; every component is a git submodule:
+本仓库是 umbrella 仓库，所有组件以 git 子模块形式组织：
 
 ```
 HarborForge/
-├── AbstractWizard/             # Go, secure first-time setup service (SSH tunnel, port 8080)
+├── AbstractWizard/             # Go，安全初始化服务（SSH 隧道，端口 8080）
-├── HarborForge.Backend/        # Python/FastAPI, core REST API + RBAC (port 8000)
+├── HarborForge.Backend/        # Python/FastAPI，核心 REST API + RBAC（端口 8000）
-├── HarborForge.Frontend/       # React + TypeScript + Vite single-page app (port 3000)
+├── HarborForge.Frontend/       # React + TypeScript + Vite，单页前端（端口 3000）
-├── HarborForge.Cli/            # Go command-line client `hf`
+├── HarborForge.Cli/            # Go，命令行客户端 `hf`
-├── HarborForge.Monitor/        # Go host telemetry client (optional local bridge 9100)
+├── HarborForge.Monitor/        # Go，主机遥测客户端（可选本地 bridge 9100）
-├── HarborForge.OpenclawPlugin/ # Node OpenClaw plugin `harbor-forge`
+├── HarborForge.OpenclawPlugin/ # Node，OpenClaw 插件 `harbor-forge`
-├── HarborForge.Test/           # Integration tests (backend pytest / frontend Playwright)
+├── HarborForge.Test/           # 集成测试（后端 pytest / 前端 Playwright）
-├── docker-compose.yml          # Docker orchestration
+├── docker-compose.yml          # Docker 编排配置
-├── nginx-host.conf.example     # Host nginx config example
+├── nginx-host.conf.example     # 宿主机 nginx 配置示例
-└── .env.example                # Environment variable template
+└── .env.example                # 环境变量模板
 ```
 
-## Quick start
+## 快速开始
 
 ```bash
-# Clone and initialize all submodules
+# 克隆并初始化所有子模块
 git clone --recurse-submodules https://git.hangman-lab.top/zhi/HarborForge.git
 cd HarborForge
-# If already cloned without submodules:
+# 若已克隆但未初始化子模块：
 git submodule update --init --recursive
 
-# Configure environment (do NOT use the defaults — see "Security")
+# 配置环境变量（不要使用默认值，见“安全”一节）
 cp .env.example .env
-# Edit .env: set at minimum a strong random SECRET_KEY and DB passwords
+# 编辑 .env，至少设置强随机 SECRET_KEY 与数据库口令
 
-# Start the services
+# 启动服务
 docker compose up -d
 ```
 
-## First deployment — setup wizard
+## 首次部署 — 初始化向导
 
-HarborForge uses [AbstractWizard](./AbstractWizard) for secure
+HarborForge 使用 [AbstractWizard](./AbstractWizard) 进行安全初始化。Wizard 仅监听 `127.0.0.1`，必须通过 SSH 隧道访问。
-initialization. The wizard listens on `127.0.0.1` only and must be
-reached over an SSH tunnel.
 
 ```bash
-# 1. SSH tunnel: forward the wizard port to your machine
+# 1. SSH 隧道映射 wizard 端口到本地
 ssh -L 18080:127.0.0.1:18080 user@your-server
 
-# 2. Open the frontend in a browser (or via the host nginx).
+# 2. 浏览器访问前端（或通过宿主机 nginx）
-#    If the backend is not initialized, it redirects to the setup wizard.
+#    前端检测到后端未就绪 → 自动跳转初始化向导
 
-# 3. In the wizard, configure: database connection, admin account,
+# 3. 在向导中配置：数据库连接、管理员账号、默认项目（可选）
-#    default project (optional).
 
-# 4. Once saved, the backend detects the config and starts; refresh
+# 4. 配置保存后，后端自动检测到配置并启动；刷新页面 → 登录界面
-#    the page → login screen.
 ```
 
-### Startup flow
+### 启动流程
 
 ```
 docker compose up
-  ├── mysql    → database starts
+  ├── mysql    → 数据库启动
-  ├── wizard   → AbstractWizard starts (127.0.0.1, SSH-tunnel access)
+  ├── wizard   → AbstractWizard 启动（127.0.0.1，SSH 隧道访问）
-  ├── backend  → blocks waiting for the config file (polls /config/harborforge.json)
+  ├── backend  → 阻塞等待配置文件（轮询 /config/harborforge.json）
-  └── frontend → checks backend state
+  └── frontend → 检测后端状态
-                 ├── backend not ready → shows the setup wizard (SSH tunnel to wizard)
+                 ├── 后端未就绪 → 显示初始化向导（SSH 隧道连 wizard）
-                 └── backend ready     → normal login screen
+                 └── 后端就绪   → 正常登录界面
 ```
 
-### Security model
+### 安全模型
 
-- The wizard port binds to `127.0.0.1` and is never exposed to the
+- Wizard 端口绑定 `127.0.0.1`，不暴露到外部网络；初始化必须经 SSH 隧道完成。
-  external network; initialization must be done over an SSH tunnel.
+- 配置通过 Docker volume 共享给后端（不走网络），后端以只读方式挂载。
-- Config is shared with the backend via a Docker volume (never over the
-  network); the backend mounts it read-only.
 
-## Deployment architecture
+## 部署架构
 
 ```
-Host nginx (80/443)
+宿主机 nginx (80/443)
-  ├── /     → frontend (Docker, port 3000)
+  ├── /     → frontend (Docker, 端口 3000)
-  └── /api/ → backend  (Docker, port 8000)
+  └── /api/ → backend  (Docker, 端口 8000)
 
-Internal to Docker (not exposed):
+Docker 内部（不对外）:
-  wizard (127.0.0.1) → config management, SSH-tunnel access
+  wizard (127.0.0.1) → 配置管理，SSH 隧道访问
-  wizard_config vol  → written by wizard, read-only for the backend
+  wizard_config vol  → wizard 写入，backend 只读读取
-  mysql (127.0.0.1)  → data persistence
+  mysql (127.0.0.1)  → 数据持久化
 ```
 
-## Submodules
+## 子模块
 
-| Submodule | Stack | Role |
+| 子模块 | 技术栈 | 作用 |
-|-----------|-------|------|
+|--------|--------|------|
-| [AbstractWizard](./AbstractWizard) | Go | First-time setup wizard; atomic config writes + backups; init/readonly modes |
+| [AbstractWizard](./AbstractWizard) | Go | 首次安装向导，安全写配置（原子写 + 备份），init/readonly 模式 |
-| [HarborForge.Backend](./HarborForge.Backend) | Python / FastAPI / SQLAlchemy / MySQL | Core API: users, projects, tasks, milestones, proposals, RBAC, webhooks, worklogs, notifications |
+| [HarborForge.Backend](./HarborForge.Backend) | Python / FastAPI / SQLAlchemy / MySQL | 核心 API：用户、项目、任务、里程碑、提案、RBAC、Webhook、工时、通知 |
-| [HarborForge.Frontend](./HarborForge.Frontend) | React 18 / TS / Vite | SPA, ~20 pages; auto-detects an uninitialized backend → setup wizard |
+| [HarborForge.Frontend](./HarborForge.Frontend) | React 18 / TS / Vite | SPA，~20 页面；自动检测未初始化 → 引导安装向导 |
-| [HarborForge.Cli](./HarborForge.Cli) | Go | Permission-aware command-line client `hf` |
+| [HarborForge.Cli](./HarborForge.Cli) | Go | 权限感知命令行客户端 `hf` |
-| [HarborForge.Monitor](./HarborForge.Monitor) | Go | Standalone host telemetry client, heartbeat reporting |
+| [HarborForge.Monitor](./HarborForge.Monitor) | Go | 独立主机遥测客户端，心跳上报 |
-| [HarborForge.OpenclawPlugin](./HarborForge.OpenclawPlugin) | Node / TS | OpenClaw plugin; bridges telemetry; can install the `hf` skills and calendar scheduling |
+| [HarborForge.OpenclawPlugin](./HarborForge.OpenclawPlugin) | Node / TS | OpenClaw 插件，桥接遥测，可安装 `hf` 技能与日历调度 |
-| [HarborForge.Test](./HarborForge.Test) | pytest / Playwright | Backend and frontend integration tests |
+| [HarborForge.Test](./HarborForge.Test) | pytest / Playwright | 后端与前端集成测试 |
 
-## Core domain model
+## 核心业务模型
 
-- **Milestone**: `open → freeze → undergoing → completed` (freeze
+- **里程碑**：`open → freeze → undergoing → completed`（freeze 时须恰好 1 个 release 任务）
-  requires exactly one release task)
+- **任务**（issue / story / test / maintenance / research / review / resolution）：`pending → open → undergoing → completed`，完成须带评论
-- **Task** (issue / story / test / maintenance / research / review /
+- **提案**：用户提 propose → 管理者 accept → 自动在里程碑内创建 feature story 任务；reject 可重开
-  resolution): `pending → open → undergoing → completed`; completion
+- **RBAC**：细粒度权限 + 项目角色层级（guest < viewer < member < dev < mgr < admin）
-  requires a comment
-- **Proposal**: a user proposes → a manager accepts → a feature-story
-  task is auto-created in a milestone; rejected proposals can reopen
-- **RBAC**: fine-grained permissions + a project role hierarchy
-  (guest < viewer < member < dev < mgr < admin)
 
-## Ports
+## 端口
 
-| Service | Container port | Bind | Env var |
+| 服务 | 容器端口 | 绑定 | 环境变量 |
-|---------|----------------|------|---------|
+|------|----------|------|----------|
-| Frontend | 3000 | see compose | `FRONTEND_PORT` |
+| Frontend | 3000 | 见 compose | `FRONTEND_PORT` |
-| Backend  | 8000 | see compose | `BACKEND_PORT` |
+| Backend  | 8000 | 见 compose | `BACKEND_PORT` |
 | MySQL    | 3306 | 127.0.0.1  | `MYSQL_PORT` |
 | Wizard   | 8080 | 127.0.0.1  | `WIZARD_PORT` |
 
-> The SSH-tunnel example uses local port `18080` forwarding to the
+> SSH 隧道示例使用本地端口 `18080` 转发到服务器 wizard。
-> server-side wizard.
 
-## Security
+## 安全
 
-Before deploying, you must:
+部署前务必：
 
-- **Set a strong random `SECRET_KEY`** (e.g. `openssl rand -hex 32`).
+- **设置强随机 `SECRET_KEY`**（如 `openssl rand -hex 32`）。后端在检测到弱/默认/过短密钥时会拒绝启动。
-  The backend refuses to start on a weak/default/short key.
+- 不要使用 `.env.example` 中的占位口令；为 MySQL 设置强口令。
-- Not use the placeholder passwords from `.env.example`; set a strong
+- 不要将含真实密钥的 `.env` 提交进版本库。
-  MySQL password.
-- Never commit a `.env` containing real secrets.
 
-The backend's auth / RBAC / SSRF hardening is documented in the
+后端的鉴权/RBAC/SSRF 加固详见 [HarborForge.Backend 的 README](./HarborForge.Backend) “Security” 一节。
-"Security" section of the
-[HarborForge.Backend README](./HarborForge.Backend).
 
-## Frontend
+## 前端
 
-The frontend uses a centralized custom design system (the industrial
+前端采用集中式自定义设计系统（“Foundry Deck” 工业主题），细节见 [HarborForge.Frontend 的 README](./HarborForge.Frontend)。
-"Foundry Deck" theme); see the
-[HarborForge.Frontend README](./HarborForge.Frontend) for details.