Enhance quick start guide and update documentation for v0.2.0

CITATION.cff

@@ -11,8 +11,9 @@ authors:
     # email: "you@example.com"
 repository-code: "https://github.com/keting/half"
 license: Apache-2.0
-version: "0.1.0"
-date-released: "2026-04-22"
+doi: 10.5281/zenodo.19809712
+version: "0.2.1"
+date-released: "2026-04-27"
 keywords:
   - ai-agents
   - coding-agents

README.md

@@ -1,5 +1,6 @@
 [English](./README.md) | [简体中文](./README.zh-CN.md)
 
+[![DOI](https://zenodo.org/badge/1196783873.svg)](https://doi.org/10.5281/zenodo.19809712)
 [![CI](https://github.com/keting/half/actions/workflows/ci.yml/badge.svg)](https://github.com/keting/half/actions/workflows/ci.yml)
 
 # HALF - Human-AI Loop Framework
@@ -23,6 +24,22 @@ A task management console for teams orchestrating multiple AI coding agents
   short-term reset windows, and long-term reset windows so planners do not
   dispatch work to an unavailable agent.
 
+## Product Preview
+
+The built-in demo project gives first-time users a non-empty workspace for
+understanding the project board, task dependencies, and agent availability.
+
+| Plan DAG | Available agents | Agent settings |
+|---|---|---|
+| <img src="./docs/images/readme-plan-dag.png" alt="Demo plan DAG" width="300"> | <img src="./docs/images/readme-available-agents.png" alt="Available demo agents" width="300"> | <img src="./docs/images/readme-agent-settings.png" alt="Demo agent settings" width="220"> |
+
+<details>
+<summary>Project board screenshot</summary>
+
+<img src="./docs/images/readme-project-board.png" alt="Demo project board" width="520">
+
+</details>
+
 ## What HALF is not
 
 - A replacement for Jira, Linear, or a general-purpose project management
@@ -119,6 +136,8 @@ Application code lives under [`src/`](./src). Documentation lives under
 - [`docs/project-structure.md`](./docs/project-structure.md) - code
   organization for contributors
 - [`docs/ui-style.md`](./docs/ui-style.md) - UI and interaction principles
+- [`docs/quickstart.md`](./docs/quickstart.md) - step-by-step setup guide with
+  troubleshooting
 
 The **API reference** is auto-generated by FastAPI and available at
 `http://localhost:8000/docs` (Swagger UI) or `http://localhost:8000/redoc`
@@ -142,6 +161,26 @@ Open `http://localhost:3000` and log in as `admin` with the password you set.
 The `HALF_ADMIN_PASSWORD` value must be set in `.env` before the first
 deployment; HALF uses it to create the initial `admin` account.
 
+### First Steps
+
+After logging in:
+
+1. **Explore the Demo Project** - A browsable demo `(Demo) 修复一个bug` is
+   pre-loaded with sample tasks. Review it to understand the task board, DAG
+   view, and handoff prompts.
+2. **Create Your Own Project** - Click "新建项目" and configure:
+   - Git repository URL (must be accessible from the container)
+   - Collaboration directory (relative path for outputs)
+   - **At least one Agent must be selected** from the pre-seeded demo agents
+   - Polling intervals and timeout settings
+3. **Generate a Plan** - Select a process template and provide required inputs
+   (e.g., doc paths, test URLs) to generate the task DAG.
+4. **Dispatch Tasks** - Start tasks from the task board; HALF generates prompts
+   for you to paste into your agent's UI.
+
+See [docs/quickstart.md](./docs/quickstart.md) for a detailed walkthrough and
+troubleshooting.
+
 ## Demo Project
 
 On first startup, HALF seeds a browsable demo project by default:
@@ -229,6 +268,21 @@ to report vulnerabilities.
 
 See [`CONTRIBUTING.md`](./CONTRIBUTING.md).
 
+## Citation
+
+If you use HALF in your research, teaching, or software engineering
+experiments, please cite the archived Zenodo project record:
+
+Keting. (2026). HALF: Human-AI Loop Framework. Zenodo.
+https://doi.org/10.5281/zenodo.19809712
+
+The citation metadata is also available in [`CITATION.cff`](./CITATION.cff).
+
+DOI maintenance note: HALF uses the Zenodo Concept DOI for repository-level
+citation and metadata. Version-specific DOIs are managed by Zenodo and are not
+written back into the repository for every release. For exact reproducibility,
+use the version-specific DOI shown on the corresponding Zenodo record.
+
 ## Screenshots
 
 Screenshots will be added in v0.2.

README.zh-CN.md

@@ -1,5 +1,6 @@
 [English](./README.md) | [简体中文](./README.zh-CN.md)
 
+[![DOI](https://zenodo.org/badge/1196783873.svg)](https://doi.org/10.5281/zenodo.19809712)
 [![CI](https://github.com/keting/half/actions/workflows/ci.yml/badge.svg)](https://github.com/keting/half/actions/workflows/ci.yml)
 
 # HALF - Human-AI Loop Framework
@@ -8,8 +9,7 @@
 coding agent（Claude Code、Codex、Copilot、GLM、Kimi 等）的协作。
 
 > [!WARNING]
-> **v0.x / 早期开源版本。** 接口和数据模型可能会在次版本间发生变化，暂不建
-> 议用于生产级多租户场景。
+> **v0.x / 早期开源版本。** 接口和数据模型可能会在次版本间发生变化，暂不建议用于生产级多租户场景。
 
 ## HALF 是什么
 
@@ -20,6 +20,22 @@ coding agent（Claude Code、Codex、Copilot、GLM、Kimi 等）的协作。
 - **agent 可用性模型。** 跟踪每个 agent 的订阅到期时间、短周期重置窗口和
   长周期重置窗口，避免规划器把任务派发给当前不可用的 agent。
 
+## 产品预览
+
+内置 Demo 项目会为首次使用者提供一个非空工作区，用于理解项目看板、任务
+依赖关系和 agent 可用性。
+
+| Plan DAG | 可用 agents | Agent 设置 |
+|---|---|---|
+| <img src="./docs/images/readme-plan-dag.png" alt="Demo Plan DAG" width="300"> | <img src="./docs/images/readme-available-agents.png" alt="可用 Demo agents" width="300"> | <img src="./docs/images/readme-agent-settings.png" alt="Demo agent 设置" width="220"> |
+
+<details>
+<summary>项目看板截图</summary>
+
+<img src="./docs/images/readme-project-board.png" alt="Demo 项目看板" width="520">
+
+</details>
+
 ## HALF 不是什么
 
 - 不是 Jira、Linear 或通用项目管理工具的替代品。
@@ -104,6 +120,8 @@ agent 产品，尤其是订阅式产品，主要面向个人或团队直接交
 - [`docs/project-structure.md`](./docs/project-structure.md) - 面向贡献者
   的代码组织说明
 - [`docs/ui-style.md`](./docs/ui-style.md) - UI 与交互原则
+- [`docs/quickstart.md`](./docs/quickstart.md) - 详细的快速上手指南和故障
+  排除
 
 **API 参考文档** 由 FastAPI 自动生成。后端启动后，可访问
 `http://localhost:8000/docs`（Swagger UI）或
@@ -127,6 +145,22 @@ docker compose up -d
 `HALF_ADMIN_PASSWORD` 必须在第一次部署前写入 `.env`；HALF 会用它创建初
 始 `admin` 账号。
 
+### 首次使用步骤
+
+登录后：
+
+1. **浏览 Demo 项目** - 预置的 `(Demo) 修复一个bug` 包含示例任务。查看任务
+   看板、DAG 视图和 handoff prompt，了解产品形态。
+2. **创建自己的项目** - 点击"新建项目"并配置：
+   - Git 仓库地址（需确保容器内可访问）
+   - 协作目录（用于存放输出的相对路径）
+   - **必须选择至少一个 Agent**（从预置的 demo agents 中选择）
+   - 轮询间隔和超时设置
+3. **生成 Plan** - 选择流程模板并填写必填参数，生成任务 DAG。
+4. **派发任务** - 从任务看板启动任务；HALF 生成 prompt 供你粘贴到 agent UI。
+
+详细步骤和故障排除请参阅 [docs/quickstart.md](./docs/quickstart.md)。
+
 ## Demo 项目
 
 首次启动时，HALF 默认会创建一个可浏览的 Demo 项目：
@@ -210,6 +244,19 @@ HALF 通常以自托管方式部署。用于生产环境时，请保持
 
 贡献说明请参阅 [`CONTRIBUTING.md`](./CONTRIBUTING.md)。
 
+## 引用
+
+如果你在研究、教学或软件工程实验中使用 HALF，请引用 Zenodo 项目归档记录：
+
+Keting. (2026). HALF: Human-AI Loop Framework. Zenodo.
+https://doi.org/10.5281/zenodo.19809712
+
+引用元数据也可以在 [`CITATION.cff`](./CITATION.cff) 中查看。
+
+DOI 维护说明：HALF 使用 Zenodo Concept DOI 作为仓库级引用和元数据 DOI。
+版本级 DOI 由 Zenodo 管理，不会在每个 release 后都回写到仓库。若需要精确
+复现某个版本，请使用对应 Zenodo 记录中显示的版本级 DOI。
+
 ## 截图
 
 截图将在 v0.2 版本补充。

docs/architecture.md

@@ -1,6 +1,6 @@
 # HALF 架构说明
 
-> **对应版本**：v0.1.0
+> **对应版本**：v0.2.1
 > 本文档描述当前代码已经实现的系统结构、关键设计决策和公开面。以代码为事实源头；文档与代码不一致时，代码为准。
 
 ---

docs/project-structure.md

@@ -1,6 +1,6 @@
 # 代码结构导览
 
-> **对应版本**：v0.1.0
+> **对应版本**：v0.2.1
 > 本文档帮助想要修改 HALF 代码的贡献者快速定位对应模块。以 `main` 分支的当前真实目录结构为准。
 
 ---

docs/quickstart.md

@@ -0,0 +1,191 @@
+# HALF Quick Start Guide
+
+This guide walks through running HALF for the first time in a clean environment.
+
+## Prerequisites
+
+- Docker 20.10+ and Docker Compose v2+
+- 2GB available RAM
+- Ports 3000 (frontend) and 8000 (backend) available, or configure custom ports
+
+## Step 1: Configure Environment
+
+```bash
+cd src
+cp .env.example .env
+```
+
+Edit `.env` and set the **required** values:
+
+```bash
+# Generate a secure random key:
+# python3 -c 'import secrets; print(secrets.token_urlsafe(48))'
+HALF_SECRET_KEY=your-generated-secret-key
+
+# Must be at least 8 characters
+HALF_ADMIN_PASSWORD=YourSecurePass123
+```
+
+Optional settings:
+
+```bash
+# Set to 'false' to start without the demo project
+HALF_DEMO_SEED_ENABLED=true
+
+# Allow self-registration (default: false, only enable for internal demos)
+HALF_ALLOW_REGISTER=false
+```
+
+## Step 2: Start Services
+
+```bash
+docker compose up -d --build
+```
+
+Wait for services to be healthy (usually 10-30 seconds):
+
+```bash
+docker compose ps
+```
+
+You should see:
+- `src-backend-1` status: `healthy`
+- `src-frontend-1` status: `running`
+
+## Step 3: First Login
+
+Open `http://localhost:3000` in your browser.
+
+Login credentials:
+- Username: `admin`
+- Password: The `HALF_ADMIN_PASSWORD` value you set in `.env`
+
+## Step 4: Explore the Demo Project
+
+On first startup, HALF seeds a demo project:
+
+- **Name**: `(Demo) 修复一个bug`
+- **Repository**: `https://github.com/keting/half.git`
+- **Status**: Contains 5 tasks in various states (completed, ready, blocked)
+
+Navigate to the project to see:
+1. **Task Board** - Kanban view of tasks by status
+2. **DAG View** - Visual dependency graph
+3. **Task Queue** - Tasks ready for execution
+4. **Handoff Prompts** - Generated prompts for agents
+
+The demo is read-only exploration. HALF does not execute agents automatically.
+
+## Step 5: Create Your First Project
+
+1. Click "新建项目" (New Project)
+2. Fill in the form:
+   - **项目名称**: Your project name
+   - **项目目标**: Description of what you want to achieve
+   - **Git 仓库地址**: Repository URL (e.g., `https://github.com/your/repo.git`)
+   - **协作目录**: Relative path for outputs (e.g., `projects/my-project`)
+   - **轮询间隔**: How often to check for task completion (seconds)
+   - **任务超时**: Task timeout in minutes
+
+3. **Select Agents** (Required)
+   - At least one agent must be selected
+   - Pre-seeded demo agents: Claude Max, Codex Pro, Copilot Pro
+   - Configure co-location settings per agent
+
+4. Click "创建项目"
+
+## Step 6: Generate a Plan
+
+1. Open your project
+2. Click "生成 Plan" (Generate Plan)
+3. Select a **流程模板** (Process Template)
+4. Fill in required inputs:
+   - `docPath`: Path to your PRD or spec document
+   - `test_url`: URL for testing (if applicable)
+   - Other template-specific inputs
+5. Select which agents to use for plan generation
+6. Click "生成 Plan"
+
+HALF will:
+- Generate a task DAG based on the template
+- Assign tasks to selected agents
+- Create handoff prompts for each task
+
+## Step 7: Dispatch and Execute Tasks
+
+1. Go to the **任务列表** (Task List) tab
+2. Find tasks with status "待处理" (Pending)
+3. Click "派发" (Dispatch) to generate the prompt
+4. Copy the prompt and paste it into your agent's UI
+5. The agent works in the Git repository
+6. HALF polls for `result.json` to detect completion
+
+## Troubleshooting
+
+### Services fail to start
+
+**Check logs:**
+```bash
+docker compose logs backend
+docker compose logs frontend
+```
+
+**Port conflicts:**
+If ports 3000 or 8000 are in use, edit `docker-compose.yml`:
+```yaml
+frontend:
+  ports:
+    - "3001:80"  # Change host port
+
+backend:
+  ports:
+    - "8001:8000"  # Change host port
+```
+
+**Weak password error:**
+HALF refuses to start with weak defaults. Ensure:
+- `HALF_SECRET_KEY` is set and sufficiently random
+- `HALF_ADMIN_PASSWORD` is at least 8 characters
+
+### Login fails
+
+- Verify `HALF_ADMIN_PASSWORD` in `.env`
+- Check browser console for CORS errors
+- Ensure you're using `http://localhost:3000`, not `https`
+
+### "At least one agent must be selected" error
+
+When creating a project, you must:
+1. Select at least one agent from the list
+2. Configure agent assignments with co-location settings
+
+### Demo project not showing
+
+Check if seeding is enabled:
+```bash
+HALF_DEMO_SEED_ENABLED=true docker compose up -d
+```
+
+### Git repository access fails
+
+For private repositories, copy `src/docker-compose.override.yml.example` to
+`src/docker-compose.override.yml` and mount a dedicated deploy key. Do not mount
+your whole `~/.ssh` directory into the container.
+
+Alternatively, use HTTPS with a deploy token in the repository URL.
+
+## Next Steps
+
+- Read [architecture.md](./architecture.md) for system design
+- Read [task-lifecycle.md](./task-lifecycle.md) for task state transitions
+- Review the API docs at `http://localhost:8000/docs`
+
+## Clean Up
+
+To remove all data and start fresh:
+
+```bash
+docker compose down -v
+```
+
+This removes containers and volumes (SQLite database, cloned repos).