@logicseek/hello-cc 0.1.1 → 0.1.3

package/docs/README.md

@@ -0,0 +1,24 @@
+# hello-cc Documentation
+
+Start with the [project README](../README.md) when you only need the project
+summary and first command. Use these docs when you need more detail.
+
+## User Docs
+
+- [User Guide](guide.md): install, start, Web console, coordination semantics,
+  workflow, stable peer identity, and environment behavior.
+- [Command Reference](commands.md): compact list of public commands and the
+  intended use of each command group.
+- [Changelog](../CHANGELOG.md): release notes for published versions.
+- Release notes: run `npm run release:check` and
+  `npm run release:github:dry-run` before publishing. Pushing a `v*` tag runs
+  `.github/workflows/github-release.yml`, which creates or updates the GitHub
+  Release description from the current changelog section. Use
+  `workflow_dispatch` to backfill older releases without a personal token.
+
+## Design And Implementation
+
+- [Design Notes](design.md): product boundary, project boundary, capability
+  levels, coordination semantics, and provider-session binding.
+- [Implementation Notes](implementation.md): architecture, protocol, command
+  surface, stack, shim behavior, and implementation plan.

package/docs/README.zh-CN.md

@@ -0,0 +1,24 @@
+# hello-cc 文档
+
+只需要项目简介和第一条命令时，先看[仓库 README](../README.zh-CN.md)。
+需要更多细节时，再看下面的文档。
+
+## 用户文档
+
+- [用户指南](guide.zh-CN.md)：安装、启动、Web 控制台、协作语义、工作流、稳定
+  peer 身份和环境变量行为。
+- [命令参考](commands.zh-CN.md)：公共命令的紧凑清单，以及每组命令的用途。
+- [更新日志](../CHANGELOG.md)：已发布版本的 release notes。
+- 发行说明：发布前运行 `npm run release:check` 和
+  `npm run release:github:dry-run`。推送 `v*` tag 会触发
+  `.github/workflows/github-release.yml`，根据当前 changelog 小节创建或更新
+  GitHub Release 描述。旧版本可用 `workflow_dispatch` 补写描述，不需要个人
+  token。
+
+## 设计和实现
+
+- [设计说明](design.md)：产品边界、项目边界、能力层级、协作语义和 provider
+  session 绑定。
+- [实现说明](implementation.md)：架构、协议、命令面、技术栈、shim 行为和实现计划。
+
+设计和实现文档目前只有英文版。

package/docs/commands.md

@@ -0,0 +1,135 @@
+# hello-cc Command Reference
+
+Use `hcc --help` for the current top-level command list. Most subcommands also
+accept `--help`, for example `hcc update --help`, `hcc peer --help`, and
+`hcc task --help`.
+
+## Install Maintenance
+
+```text
+hcc update [--tag TAG] [--registry URL] [--dry-run]
+hcc uninstall [--purge --yes]
+```
+
+`hcc update` updates the global npm install. `hcc uninstall` removes local
+hooks and shims; add `--purge --yes` only when you also want to remove the
+current project's `.hello-cc` data and guidance blocks.
+
+## Start And Stop
+
+```text
+hcc web [--host HOST] [--port N] [--token TEXT] [--local] [--no-token] [--no-discover] [--no-guidance]
+hcc down
+hcc up [--no-discover] [--no-guidance]
+```
+
+`hcc web` is the default entry. It initializes coordination, installs hooks and
+shims, starts or reuses the Web console, and returns the terminal to you. Bare
+`hcc web` listens on `0.0.0.0` and uses a saved URL token, generating one on
+first use. Use `--local` to bind only `127.0.0.1`, `--token` or `HCC_WEB_TOKEN`
+to replace the saved token, and
+`--no-token` only in trusted local/test environments. Use `hcc up` only when you
+want coordination without the Web console or shims.
+
+## Peers And Status
+
+```text
+hcc peers
+hcc status [--peer ID]
+hcc state [--peer ID] [--resource PATH] [--intent work|stop|finish]
+hcc scan [--register]
+hcc prompt --peer ID [--kind codex|claude|shell|other] [--role ROLE]
+hcc join --peer ID [--kind codex|claude|shell|other] [--role ROLE]
+hcc env --peer ID
+hcc heartbeat [--peer ID] [--renew-locks --ttl 900]
+hcc run --peer ID --kind codex|claude|shell --role ROLE -- COMMAND [ARGS...]
+```
+
+Use these commands to inspect live project state, register terminals, and run a
+CLI with `HCC_PEER`, `HCC_ROOT`, and `HCC_DB` set. `hcc state` does not execute
+coordination actions such as acking messages, claiming tasks, acquiring locks, or
+creating handoffs. It adds a unified collaboration timeline plus
+`automation.next_action.argv`, a machine-readable next coordination command for
+agents to execute explicitly. `automation.current_task` records the peer's active
+task when one exists.
+
+## Browser-Controllable Terminals
+
+```text
+hcc peer list
+hcc peer start PEER [--kind K] [--role R] [--cwd DIR] [--restart-env] -- COMMAND [ARGS...]
+hcc peer start PEER --kind codex --resume SESSION_ID [--restart-env]
+hcc peer start PEER --kind codex --last
+hcc peer start PEER --kind claude --resume SESSION_ID [--restart-env]
+hcc peer start PEER --kind claude --continue
+hcc peer attach PEER [--pane PANE] [--kind K] [--role R] [--cwd DIR]
+hcc peer stop PEER
+hcc inject PEER TEXT [--no-enter]
+```
+
+These commands create or attach tmux-backed terminals that can be viewed and
+controlled from the Web console.
+
+## Messages
+
+```text
+hcc msg send [--from ID] [--to ID|all] --body TEXT [--task N] [--kind note|task|handoff]
+hcc msg inbox [--peer ID] [--wait SEC] [--all] [--limit N]
+hcc msg ack [--peer ID] --id N
+hcc msg reply [--from ID] --id N --body TEXT [--to ID] [--kind reply]
+hcc msg thread --id N [--limit N]
+hcc ask PEER MESSAGE [--from ID] [--task N] [--inject]
+hcc broadcast MESSAGE [--from ID] [--task N] [--inject]
+```
+
+Messages are addressed mailbox items. `ask` and `broadcast` also support live
+terminal injection with `--inject`. Use `msg reply` when answering a specific
+message; the reply stays in the same thread and is sent back to the original
+sender by default. Use `msg thread` to inspect the full thread for one message.
+
+## Tasks
+
+```text
+hcc task create --title TEXT [--body TEXT] [--from ID] [--to ID] [--priority N]
+hcc task list [--status S] [--peer ID] [--all]
+hcc task claim [--peer ID] --id N
+hcc task next [--peer ID] [--force]
+hcc task create --title TEXT --parent N [--team-role ROLE]
+hcc task update [--peer ID] --id N --status running|review|blocked|done|abandoned [--summary TEXT] [--body TEXT] [--to ID]
+hcc task done [--peer ID] --id N --summary TEXT
+```
+
+Tasks are shared project facts. They remain visible until marked `done` or
+`abandoned`. `task next` returns your existing claimed/running/review/blocked
+task before claiming a new pending task; use `--force` only when intentionally
+taking another pending task.
+
+## Teams
+
+```text
+hcc team plan --from-task N [--item ROLE:TITLE] [--item PEER:ROLE:TITLE] [--workers A,B|codex:2,claude:1]
+hcc team start --from-task N [--item ROLE:TITLE] [--item PEER:ROLE:TITLE] [--workers A,B|codex:2,claude:1] [--force]
+hcc team status --task N
+```
+
+Teams are explicit parent-task splits. `team plan` is read-only and shows the
+subtasks that would be created. `team start` creates child tasks under the
+parent and optionally assigns them to worker peer IDs. It does not silently
+spawn model processes or override the current-task rule. `--workers` accepts
+explicit peer IDs or kind counts such as `codex:2,claude:1`.
+
+## Locks, Handoffs, And Events
+
+```text
+hcc lock acquire [--peer ID] --resource PATH [--task N] [--ttl SEC] [--reason TEXT]
+hcc lock renew [--peer ID] --resource PATH [--ttl SEC]
+hcc lock release [--peer ID] --resource PATH [--force]
+hcc lock list [--all]
+hcc handoff create [--from ID] --summary TEXT [--task N] [--to ID] [--changed-files JSON_OR_CSV] [--tests TEXT] [--risks TEXT]
+hcc handoff list [--task N] [--limit N]
+hcc event tail [--limit N]
+hcc gc [--older-than DAYS] [--yes]
+```
+
+Locks are advisory coordination locks with TTLs. Handoffs preserve the result,
+tests, changed files, and remaining risks when work moves between peers.

package/docs/commands.zh-CN.md

@@ -0,0 +1,126 @@
+# hello-cc 命令参考
+
+使用 `hcc --help` 查看当前顶层命令列表。大多数子命令也支持 `--help`，
+例如 `hcc update --help`、`hcc peer --help` 和 `hcc task --help`。
+
+## 安装维护
+
+```text
+hcc update [--tag TAG] [--registry URL] [--dry-run]
+hcc uninstall [--purge --yes]
+```
+
+`hcc update` 更新全局 npm 安装。`hcc uninstall` 移除本机 hooks 和 shims；
+只有在确定也要删除当前项目的 `.hello-cc` 数据和指导块时，才加
+`--purge --yes`。
+
+## 启动和停止
+
+```text
+hcc web [--host HOST] [--port N] [--token TEXT] [--local] [--no-token] [--no-discover] [--no-guidance]
+hcc down
+hcc up [--no-discover] [--no-guidance]
+```
+
+`hcc web` 是默认入口。它会初始化协作状态，安装 hooks 和 shims，启动或复用
+Web 控制台，然后把终端还给你。裸 `hcc web` 会监听 `0.0.0.0` 并使用固定
+URL token；首次使用时自动生成并保存。用 `--local` 可只绑定 `127.0.0.1`，
+用 `--token` 或 `HCC_WEB_TOKEN` 可替换保存的 token，只有在可信本地/测试环境才使用 `--no-token`。
+只想使用本地协作、不需要 Web 或 shims 时，再使用 `hcc up`。
+
+## Peers 和状态
+
+```text
+hcc peers
+hcc status [--peer ID]
+hcc state [--peer ID] [--resource PATH] [--intent work|stop|finish]
+hcc scan [--register]
+hcc prompt --peer ID [--kind codex|claude|shell|other] [--role ROLE]
+hcc join --peer ID [--kind codex|claude|shell|other] [--role ROLE]
+hcc env --peer ID
+hcc heartbeat [--peer ID] [--renew-locks --ttl 900]
+hcc run --peer ID --kind codex|claude|shell --role ROLE -- COMMAND [ARGS...]
+```
+
+这些命令用于查看项目状态、注册终端，以及用 `HCC_PEER`、`HCC_ROOT`、
+`HCC_DB` 环境运行 CLI。`hcc state` 不会执行确认消息、认领任务、获取锁或
+创建 handoff 这类协作动作；它会返回统一协作时间线，以及
+`automation.next_action.argv` 这种机器可读的下一步协作命令，供 agent 显式执行
+并留下审计记录。`automation.current_task` 会记录当前 peer 已经拥有的活动任务。
+
+## Web 可控终端
+
+```text
+hcc peer list
+hcc peer start PEER [--kind K] [--role R] [--cwd DIR] [--restart-env] -- COMMAND [ARGS...]
+hcc peer start PEER --kind codex --resume SESSION_ID [--restart-env]
+hcc peer start PEER --kind codex --last
+hcc peer start PEER --kind claude --resume SESSION_ID [--restart-env]
+hcc peer start PEER --kind claude --continue
+hcc peer attach PEER [--pane PANE] [--kind K] [--role R] [--cwd DIR]
+hcc peer stop PEER
+hcc inject PEER TEXT [--no-enter]
+```
+
+这些命令创建或接入 tmux-backed 终端，让 Web 控制台可以观察和操作它们。
+
+## 消息
+
+```text
+hcc msg send [--from ID] [--to ID|all] --body TEXT [--task N] [--kind note|task|handoff]
+hcc msg inbox [--peer ID] [--wait SEC] [--all] [--limit N]
+hcc msg ack [--peer ID] --id N
+hcc msg reply [--from ID] --id N --body TEXT [--to ID] [--kind reply]
+hcc msg thread --id N [--limit N]
+hcc ask PEER MESSAGE [--from ID] [--task N] [--inject]
+hcc broadcast MESSAGE [--from ID] [--task N] [--inject]
+```
+
+消息是带收件人的邮箱记录。`ask` 和 `broadcast` 加 `--inject` 后，也会把内容
+实时注入到终端。回复某条消息时使用 `msg reply`；默认会发回原 sender，并保留
+在同一个 thread 中。使用 `msg thread` 可以查看某条消息所在的完整线程。
+
+## 任务
+
+```text
+hcc task create --title TEXT [--body TEXT] [--from ID] [--to ID] [--priority N]
+hcc task list [--status S] [--peer ID] [--all]
+hcc task claim [--peer ID] --id N
+hcc task next [--peer ID] [--force]
+hcc task create --title TEXT --parent N [--team-role ROLE]
+hcc task update [--peer ID] --id N --status running|review|blocked|done|abandoned [--summary TEXT] [--body TEXT] [--to ID]
+hcc task done [--peer ID] --id N --summary TEXT
+```
+
+任务是项目共享事实。任务会一直可见，直到被标记为 `done` 或 `abandoned`。
+`task next` 会优先返回当前 peer 已经认领、运行、审查或阻塞中的任务；只有明确
+要再接一个 pending 任务时才使用 `--force`。
+
+## 团队
+
+```text
+hcc team plan --from-task N [--item ROLE:TITLE] [--item PEER:ROLE:TITLE] [--workers A,B|codex:2,claude:1]
+hcc team start --from-task N [--item ROLE:TITLE] [--item PEER:ROLE:TITLE] [--workers A,B|codex:2,claude:1] [--force]
+hcc team status --task N
+```
+
+团队是显式的父任务拆分。`team plan` 只读，只展示会创建哪些子任务。
+`team start` 会在父任务下创建子任务，并可把子任务分配给 worker peer。
+它不会静默启动模型进程，也不会绕过“先继续当前任务”的规则。`--workers`
+支持显式 peer ID，也支持 `codex:2,claude:1` 这种 kind 数量形式。
+
+## 锁、交接和事件
+
+```text
+hcc lock acquire [--peer ID] --resource PATH [--task N] [--ttl SEC] [--reason TEXT]
+hcc lock renew [--peer ID] --resource PATH [--ttl SEC]
+hcc lock release [--peer ID] --resource PATH [--force]
+hcc lock list [--all]
+hcc handoff create [--from ID] --summary TEXT [--task N] [--to ID] [--changed-files JSON_OR_CSV] [--tests TEXT] [--risks TEXT]
+hcc handoff list [--task N] [--limit N]
+hcc event tail [--limit N]
+hcc gc [--older-than DAYS] [--yes]
+```
+
+锁是带 TTL 的协作式 advisory lock。交接记录用于保存结果、测试、变更文件和
+剩余风险，方便工作在多个 peer 之间继续。

package/docs/design.md

@@ -170,12 +170,13 @@ Server polls/captures tmux pane output and broadcasts it to browsers.
 ```text
 peers         stable terminal identities and heartbeat
 peer_bindings provider session binding and runtime transport metadata
-tasks         task assignment, ownership, and lifecycle
-messages      direct or broadcast messages
+tasks         task assignment, ownership, hierarchy, and lifecycle
+messages      direct, broadcast, or threaded messages
 message_reads per-peer ack state
 locks         advisory exclusive locks with TTL
 handoffs      durable cross-session handoff summaries
 events        audit trail for observability
+schema_migrations applied SQLite schema version history
 ```
 
 ## Coordination Semantics
@@ -185,10 +186,17 @@ events        audit trail for observability
 - SQLite runs with WAL and `busy_timeout=5000`.
 - Tasks are project facts. They remain visible to all peers until status becomes
   `done` or `abandoned`.
+- Tasks can form explicit parent/child hierarchies for team splits. Team commands
+  create auditable child tasks; they do not silently spawn model processes.
 - Messages are addressed mailbox items. Read state is tracked per peer.
+- Message replies keep `reply_to` and `thread_id` so peer-visible collaboration
+  history can be reconstructed without terminal capture.
 - Broadcast messages use per-peer acknowledgement, so one peer cannot consume a
   message for everyone else.
 - Locks are advisory and TTL-based. Peers must follow the protocol.
+- `hcc state` and `/api/state` expose a derived timeline plus
+  `automation.next_action.argv`; the command is advisory and does not execute
+  coordination actions itself.
 
 ## Hook Path
 
@@ -196,8 +204,8 @@ The primary model-facing path is hook context injection, not project markdown.
 
 `hcc web` installs hooks that register sessions and inject hello-cc snapshots at
 session start and before model answers. The injected snapshot contains current
-peer identity, active peers, open tasks, unread messages, active locks, and the
-commands the model should use to inspect state.
+peer identity, active peers, open tasks, unread messages, active locks, the
+current task when one exists, and the next auditable coordination action.
 
 `CLAUDE.md`, `AGENTS.md`, and `.hello-cc/HCC.md` are fallback instruction
 layers. Existing root files are updated only inside a bounded hello-cc block.

package/docs/guide.md

@@ -1,9 +1,9 @@
 # hello-cc User Guide
 
-This guide contains the detailed usage notes that are intentionally kept out of
-the short project README.
+This guide covers the practical workflow for installing, starting, and using
+hello-cc. For a compact command list, use the [Command Reference](commands.md).
 
-## Install And Update
+## Install, Update, And Uninstall
 
 Install hello-cc globally:
 
@@ -14,11 +14,30 @@ npm install -g @logicseek/hello-cc
 Update an existing global install:
 
 ```bash
-npm install -g @logicseek/hello-cc@latest
+hcc update
 ```
 
-`hcc` does not have a self-update command. `hcc task update` updates a
-coordination task, not the installed package.
+`hcc update` runs `npm install -g @logicseek/hello-cc@latest`. Use
+`hcc update --help` to see the available update options. `hcc task update`
+updates a coordination task, not the installed package.
+
+Remove hooks and shims from this machine:
+
+```bash
+hcc uninstall
+```
+
+Remove the current project's `.hello-cc` data and guidance blocks too:
+
+```bash
+hcc uninstall --purge --yes
+```
+
+Remove the global npm package:
+
+```bash
+npm uninstall -g @logicseek/hello-cc
+```
 
 ## Default Entry
 
@@ -51,8 +70,8 @@ project: /path/to/project
 database: /path/to/project/.hello-cc/mesh.db
 runtime: /path/to/project/.hello-cc/runtime.json
 log: /path/to/project/.hello-cc/web.log
-open: http://<machine-ip>:8787/?project=%2Fpath%2Fto%2Fproject
-local: http://127.0.0.1:8787/?project=%2Fpath%2Fto%2Fproject
+open: http://<machine-ip>:8787/?token=<token>&project=%2Fpath%2Fto%2Fproject
+local: http://127.0.0.1:8787/?token=<token>&project=%2Fpath%2Fto%2Fproject
 shims: installed claude, codex
 PATH updated in ~/.bashrc; open a new terminal or source it
 stop: hcc down
@@ -138,6 +157,8 @@ Tasks and messages have different read semantics:
   `abandoned`.
 - Messages are addressed mailbox items. `hcc msg inbox` defaults to unread
   messages for the current peer, and `hcc msg ack` records per-peer read state.
+- Message replies are threaded. Use `hcc msg reply --id N --body "..."` when
+  answering a message, and use `hcc msg thread --id N` to read the full thread.
 - `ask` and `broadcast` write durable messages. With `--inject`, they also send
   live input to runtime-attached terminals.
 - Locks use SQLite transactions and TTLs. They are coordination locks, not a
@@ -156,8 +177,9 @@ into the model context:
 - open tasks
 - unread messages for the current peer
 - active locks
-- suggested commands such as `hcc status`, `hcc peers`, `hcc task list`,
-  `hcc msg inbox`, and `hcc lock list`
+- a machine-readable next action from `hcc state`
+- suggested commands such as `hcc status`, `hcc state`, `hcc peers`,
+  `hcc task list`, `hcc msg inbox`, and `hcc lock list`
 
 When an attached Claude/Codex session is asked what other sessions are doing,
 it should answer from the latest hello-cc state instead of generic isolation
@@ -183,31 +205,46 @@ claude -p 'Do you see hello-cc open tasks?' --debug hooks --debug-file /tmp/hcc-
 The debug log should contain `Hook UserPromptSubmit ... provided
 additionalContext` and the `hello-cc coordination` block.
 
+`hcc state --peer <peer> [--resource PATH]` exposes the same coordination state
+without performing coordination actions such as acking messages, claiming tasks,
+acquiring locks, sending messages, creating handoffs, or marking tasks done. It
+returns the existing project arrays plus a unified `timeline` and an
+`automation` object. The important machine field is
+`automation.next_action.argv`: agents can execute that explicit hcc command, so
+the coordination flow becomes auditable instead of being only a prompt
+instruction. `automation.current_task` carries the peer's active task so a
+resumed session keeps working on the same task until it is handed off, done, or
+blocked.
+
 ## Web Console
 
-Start local and LAN-visible control:
+Start local and LAN-visible control with token authentication:
 
 ```bash
 hcc web
 ```
 
-Use a token only when you want one:
+Bare `hcc web` stores its generated token and reuses it across restarts. Set a
+token explicitly when you want to replace the saved value:
 
 ```bash
-HCC_WEB_TOKEN='choose-a-long-token' hcc web --host 0.0.0.0 --port 8787
+HCC_WEB_TOKEN='choose-a-long-token' hcc web --port 8787
 ```
 
 Open from another machine on the same network:
 
 ```text
-http://<machine-ip>:8787/
+http://<machine-ip>:8787/?token=<token>
 ```
 
+Use `hcc web --local` to bind only `127.0.0.1`. Use `hcc web --no-token` only
+in a trusted local/test environment.
+
 The web console can:
 
 - switch between multiple registered project roots on one port
 - register another project path from the browser
-- show project state: peers, tasks, messages, locks, handoffs, events
+- show project state: next action, timeline, peers, tasks, and locks
 - operate local terminals: start Claude/Codex/shell, send keyboard input, view
   output, detach runtime control
 
@@ -221,63 +258,13 @@ Browser-controlled sessions are local tmux terminals:
 Already-open raw terminals cannot be captured or controlled unconditionally
 unless they started under tmux, screen, or a hello-cc shim. They can still
 participate in tasks, messages, and locks through hooks and `hcc` commands.
+For these coordination-only peers, the Web console shows collaboration through
+the Timeline rather than a terminal stream.
 
-## Common Commands
+## Command Reference
 
-```text
-# Default entry
-hcc web [--host HOST] [--port N] [--token TEXT] [--local] [--no-discover] [--no-guidance]
-hcc down
-
-# Local coordination without Web
-hcc up [--no-discover] [--no-guidance]
-
-# Peers and status
-hcc peers
-hcc status [--peer ID]
-hcc scan [--register]
-hcc prompt --peer ID [--kind codex|claude|shell|other] [--role ROLE]
-hcc join --peer ID [--kind codex|claude|shell|other] [--role ROLE]
-hcc env --peer ID
-hcc heartbeat [--peer ID] [--renew-locks --ttl 900]
-hcc run --peer ID --kind codex|claude|shell --role ROLE -- COMMAND [ARGS...]
-
-# Browser-controllable terminals
-hcc peer list
-hcc peer start PEER [--kind K] [--role R] [--cwd DIR] [--restart-env] -- COMMAND [ARGS...]
-hcc peer start PEER --kind codex --resume SESSION_ID [--restart-env]
-hcc peer start PEER --kind codex --last
-hcc peer start PEER --kind claude --resume SESSION_ID [--restart-env]
-hcc peer start PEER --kind claude --continue
-hcc peer attach PEER [--pane PANE] [--kind K] [--role R] [--cwd DIR]
-hcc peer stop PEER
-hcc inject PEER TEXT [--no-enter]
-
-# Messages
-hcc msg send [--from ID] [--to ID|all] --body TEXT [--task N] [--kind note|task|handoff]
-hcc msg inbox [--peer ID] [--wait SEC] [--all] [--limit N]
-hcc msg ack [--peer ID] --id N
-hcc ask PEER MESSAGE [--from ID] [--task N] [--inject]
-hcc broadcast MESSAGE [--from ID] [--task N] [--inject]
-
-# Tasks
-hcc task create --title TEXT [--body TEXT] [--from ID] [--to ID] [--priority N]
-hcc task list [--status S] [--peer ID] [--all]
-hcc task claim [--peer ID] --id N
-hcc task next [--peer ID]
-hcc task update [--peer ID] --id N --status running|review|blocked|done|abandoned [--summary TEXT] [--body TEXT] [--to ID]
-hcc task done [--peer ID] --id N --summary TEXT
-
-# Locks and handoffs
-hcc lock acquire [--peer ID] --resource PATH [--task N] [--ttl SEC] [--reason TEXT]
-hcc lock renew [--peer ID] --resource PATH [--ttl SEC]
-hcc lock release [--peer ID] --resource PATH [--force]
-hcc lock list [--all]
-hcc handoff create [--from ID] --summary TEXT [--task N] [--to ID] [--changed-files JSON_OR_CSV] [--tests TEXT] [--risks TEXT]
-hcc handoff list [--task N] [--limit N]
-hcc event tail [--limit N]
-hcc gc [--older-than DAYS] [--yes]
-```
+Use `hcc --help` for the command list and `hcc <command> --help` for a specific
+command. The maintained summary lives in the [Command Reference](commands.md).
 
 ## Stable Peer Identity
 
@@ -314,10 +301,35 @@ hcc task next
 hcc lock acquire --resource vllm/router --ttl 900 --reason "implement diagnostics"
 ```
 
+`task next` first returns the peer's current claimed/running/review/blocked task.
+Use `hcc task next --force` only when intentionally taking another pending task.
+
+Split a task into an explicit team when the work is genuinely parallel:
+
+```bash
+hcc team plan --from-task 12 \
+  --item "docs:Update user guide" \
+  --item "tests:Add regression" \
+  --workers codex:1,claude:1
+
+hcc team start --from-task 12 \
+  --item "docs:Update user guide" \
+  --item "tests:Add regression" \
+  --workers codex:1,claude:1
+
+hcc team status --task 12
+```
+
+`team plan` is read-only. `team start` creates child tasks and assignment
+messages, but it does not spawn hidden model processes. Agents still claim,
+lock, hand off, and finish their own child tasks through the normal commands.
+
 Message or inject:
 
 ```bash
 hcc msg send --to claude-a --body "Implementation is ready for review."
+hcc msg reply --id 12 --body "Reviewed; no blocker found."
+hcc msg thread --id 12
 hcc ask claude-a "Please review the current implementation." --inject
 hcc broadcast "Pause edits under vllm/router until this task finishes." --inject
 ```
@@ -341,7 +353,7 @@ hcc lock release --resource vllm/router
 | `HCC_PEER` | default peer identity |
 | `HCC_ROOT` | override project root |
 | `HCC_DB` | override database path |
-| `HCC_WEB_TOKEN` | optional token for web access |
+| `HCC_WEB_TOKEN` | replace and save the stable web access token |
 | `HCC_RUNTIME_URL` | direct runtime URL |
 | `HCC_NO_AUTO_INSTALL_TMUX=1` | disable tmux auto-install, mainly for tests |