bump HarborForge.PlexumPlugin → bc1ab7b

snake_case SlotStatus alignment + scheduler decision logs (see
plugin repo's commit for the sim e2e findings).

.gitmodules

@@ -24,3 +24,6 @@
 	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,101 +1,148 @@
 # HarborForge
 
-Agent/人类协同任务管理平台
+Agent / human collaborative task-management platform — manages the full
+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:
 
 ```
 HarborForge/
-├── HarborForge.Backend/    # 后端 (FastAPI + MySQL)
-├── HarborForge.Frontend/   # 前端 (React + Vite)
-├── docker-compose.yml      # Docker 部署配置
-├── nginx-host.conf.example # 宿主机 nginx 配置示例
-└── .env.example            # 环境变量模板
+├── AbstractWizard/             # Go, secure first-time setup service (SSH tunnel, port 8080)
+├── HarborForge.Backend/        # Python/FastAPI, core REST API + RBAC (port 8000)
+├── HarborForge.Frontend/       # React + TypeScript + Vite single-page app (port 3000)
+├── HarborForge.Cli/            # Go command-line client `hf`
+├── HarborForge.Monitor/        # Go host telemetry client (optional local bridge 9100)
+├── HarborForge.OpenclawPlugin/ # Node OpenClaw plugin `harbor-forge`
+├── HarborForge.Test/           # Integration tests (backend pytest / frontend Playwright)
+├── docker-compose.yml          # Docker orchestration
+├── nginx-host.conf.example     # Host nginx config example
+└── .env.example                # Environment variable template
 ```
 
-## 快速开始
+## Quick start
 
 ```bash
-# 克隆并初始化子模块
-git clone https://git.hangman-lab.top/zhi/HarborForge.git
+# 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
+
+# Start the services
 docker compose up -d
 ```
 
-## 首次部署 — 初始化向导
+## First deployment — setup wizard
 
-HarborForge 使用 [AbstractWizard](https://git.hangman-lab.top/hzhang/AbstractWizard) 进行安全初始化。
-Wizard 仅监听 `127.0.0.1`，必须通过 SSH 隧道访问。
+HarborForge uses [AbstractWizard](./AbstractWizard) for secure
+initialization. The wizard listens on `127.0.0.1` only and must be
+reached over an SSH tunnel.
 
 ```bash
-# 1. SSH 隧道映射 wizard 端口到本地
+# 1. SSH tunnel: forward the wizard port to your machine
 ssh -L 18080:127.0.0.1:18080 user@your-server
 
-# 2. 浏览器访问前端（或通过宿主机 nginx）
-#    前端检测到后端未就绪 → 自动跳转初始化向导
+# 2. Open the frontend in a browser (or via the host nginx).
+#    If the backend is not initialized, it redirects to the setup wizard.
 
-# 3. 在向导中配置:
-#    - 数据库连接信息
-#    - 管理员账号
-#    - 默认项目（可选）
+# 3. In the wizard, configure: database connection, admin account,
+#    default project (optional).
 
-# 4. 配置保存后，后端自动检测到配置并启动
-#    刷新页面 → 进入登录界面
+# 4. Once saved, the backend detects the config and starts; refresh
+#    the page → login screen.
 ```
 
-### 启动流程
+### Startup flow
 
 ```
 docker compose up
-  ├── mysql       → 数据库启动
-  ├── wizard      → AbstractWizard 启动 (127.0.0.1:18080)
-  ├── backend     → 等待配置文件... (轮询 /config/harborforge.json)
-  └── frontend    → 检测后端状态
-                    ├── 后端未就绪 → 显示初始化向导 (SSH 隧道连 wizard)
-                    └── 后端就绪   → 正常登录界面
+  ├── mysql    → database starts
+  ├── wizard   → AbstractWizard starts (127.0.0.1, SSH-tunnel access)
+  ├── backend  → blocks waiting for the config file (polls /config/harborforge.json)
+  └── frontend → checks backend state
+                 ├── backend not ready → shows the setup wizard (SSH tunnel to wizard)
+                 └── backend ready     → normal login screen
 ```
 
-### 安全模型
+### Security model
 
-- Wizard 端口绑定 `127.0.0.1`，不暴露到外部网络
-- 初始化必须通过 SSH 隧道完成（与 AbstractWizard 安全模型一致）
-- 配置完成后 Wizard 自动切换为只读模式
-- 配置通过 Docker volume 共享给后端（不走网络）
+- The wizard port binds to `127.0.0.1` and is never exposed to the
+  external network; initialization must be done over an SSH tunnel.
+- Config is shared with the backend via a Docker volume (never over the
+  network); the backend mounts it read-only.
 
-## 部署架构
+## Deployment architecture
 
 ```
-宿主机 nginx (80/443)
+Host nginx (80/443)
   ├── /     → frontend (Docker, port 3000)
   └── /api/ → backend  (Docker, port 8000)
 
-Docker 内部 (不暴露):
-  wizard (127.0.0.1:18080) → 配置管理，SSH 隧道访问
-  wizard_config volume     → wizard 写入，backend 读取
+Internal to Docker (not exposed):
+  wizard (127.0.0.1) → config management, SSH-tunnel access
+  wizard_config vol  → written by wizard, read-only for the backend
+  mysql (127.0.0.1)  → data persistence
 ```
 
-## 子模块
+## Submodules
 
-- [HarborForge.Backend](https://git.hangman-lab.top/zhi/HarborForge.Backend) - FastAPI 后端 API
-- [HarborForge.Frontend](https://git.hangman-lab.top/zhi/HarborForge.Frontend) - React 前端
+| Submodule | Stack | Role |
+|-----------|-------|------|
+| [AbstractWizard](./AbstractWizard) | Go | First-time setup wizard; atomic config writes + backups; init/readonly modes |
+| [HarborForge.Backend](./HarborForge.Backend) | Python / FastAPI / SQLAlchemy / MySQL | Core API: users, projects, tasks, milestones, proposals, RBAC, webhooks, worklogs, notifications |
+| [HarborForge.Frontend](./HarborForge.Frontend) | React 18 / TS / Vite | SPA, ~20 pages; auto-detects an uninitialized backend → setup wizard |
+| [HarborForge.Cli](./HarborForge.Cli) | Go | Permission-aware command-line client `hf` |
+| [HarborForge.Monitor](./HarborForge.Monitor) | Go | Standalone host telemetry client, heartbeat reporting |
+| [HarborForge.OpenclawPlugin](./HarborForge.OpenclawPlugin) | Node / TS | OpenClaw plugin; bridges telemetry; can install the `hf` skills and calendar scheduling |
+| [HarborForge.Test](./HarborForge.Test) | pytest / Playwright | Backend and frontend integration tests |
 
-## 端口
+## Core domain model
 
-| 服务 | 默认端口 | 绑定 | 环境变量 |
-|------|----------|------|----------|
-| Frontend | 3000 | 0.0.0.0 | `FRONTEND_PORT` |
-| Backend | 8000 | 0.0.0.0 | `BACKEND_PORT` |
-| MySQL | 3306 | 127.0.0.1 | `MYSQL_PORT` |
-| Wizard | 18080 | 127.0.0.1 | `WIZARD_PORT` |
+- **Milestone**: `open → freeze → undergoing → completed` (freeze
+  requires exactly one release task)
+- **Task** (issue / story / test / maintenance / research / review /
+  resolution): `pending → open → undergoing → completed`; completion
+  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
 
-- 🔧 初始化向导 — 首次部署配置（SSH 隧道）
-- 📊 仪表盘 — 统计概览
-- 📋 Issues — 创建、列表、详情、状态变更、评论
-- 📁 项目 — 项目管理、成员、关联 issue
-- 🏁 里程碑 — 进度追踪、完成百分比
-- 🔔 通知 — 实时通知中心、未读计数
+| Service | Container port | Bind | Env var |
+|---------|----------------|------|---------|
+| Frontend | 3000 | see compose | `FRONTEND_PORT` |
+| Backend  | 8000 | see 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
+> server-side wizard.
+
+## Security
+
+Before deploying, you must:
+
+- **Set a strong random `SECRET_KEY`** (e.g. `openssl rand -hex 32`).
+  The backend refuses to start on a weak/default/short key.
+- Not use the placeholder passwords from `.env.example`; set a strong
+  MySQL password.
+- Never commit a `.env` containing real secrets.
+
+The backend's auth / RBAC / SSRF hardening is documented in the
+"Security" section of the
+[HarborForge.Backend README](./HarborForge.Backend).
+
+## Frontend
+
+The frontend uses a centralized custom design system (the industrial
+"Foundry Deck" theme); see the
+[HarborForge.Frontend README](./HarborForge.Frontend) for details.