@logicseek/hello-cc 0.1.1 → 0.1.2

package/CHANGELOG.md

@@ -0,0 +1,81 @@
+# Changelog
+
+This project keeps one changelog file. Add one section per release, with the
+newest version first. Do not create a new changelog file for every release.
+
+Before publishing, run:
+
+```bash
+npm run release:check
+npm run release:notes
+```
+
+Use the output of `npm run release:notes` as the GitHub Release description for
+the current `package.json` version.
+
+## 0.1.2
+
+### Summary
+
+hello-cc 0.1.2 tightens the public release surface after the first scoped npm
+publish. It adds a first-class update command, makes uninstall discoverable in
+top-level help, and reorganizes the documentation so the npm package page and
+GitHub release notes have a clear, detailed description of what changed.
+
+### Highlights
+
+- Added `hcc update`, which updates the global npm install by running
+  `npm install -g @logicseek/hello-cc@latest`.
+- Added `hcc update --tag`, `hcc update --registry`, and `hcc update --dry-run`
+  for controlled upgrades and release verification.
+- Made `hcc uninstall` visible in top-level `hcc --help`, matching the README
+  and command reference.
+- Kept uninstall behavior conservative: `hcc uninstall` removes hooks and
+  shims, while `hcc uninstall --purge --yes` is required to remove project data.
+- Split documentation into a short README, a user guide, command reference, and
+  documentation index in both English and Chinese.
+- Restored the Star History chart at the bottom of both README files.
+- Included README-linked package assets in the npm tarball so the package page
+  renders the project logo correctly.
+
+### Documentation
+
+- `README.md` and `README.zh-CN.md` now focus on product positioning, install
+  and maintenance commands, quick start, a basic workflow, and links to docs.
+- `docs/guide.md` and `docs/guide.zh-CN.md` describe practical usage and avoid
+  embedding the full command list.
+- `docs/commands.md` and `docs/commands.zh-CN.md` provide the compact command
+  reference.
+- `docs/README.md` and `docs/README.zh-CN.md` provide the documentation index.
+- English documentation links now point to English user docs, and Chinese
+  documentation links point to Chinese user docs.
+
+### Validation
+
+The 0.1.2 release should be validated with:
+
+```bash
+git diff --check
+node --check bin/hcc.mjs
+node --check scripts/regression.mjs
+node --check lib/setup.mjs
+node --check lib/discover.mjs
+npm pack --dry-run --json
+npm publish --dry-run --registry=https://registry.npmjs.org/ --access public
+npm test
+```
+
+The package dry run should include `CHANGELOG.md`, `assets/logo.svg`, and the
+English and Chinese command reference files.
+
+The expected full regression marker is:
+
+```text
+FULL_REGRESSION_OK
+```
+
+### Release Notes Source
+
+Use this changelog section as the source for the GitHub Release notes for
+`v0.1.2`. The npm package metadata keeps a short description, while the package
+README and this changelog provide the detailed release description.

package/README.md

@@ -37,7 +37,7 @@ doing.
 - **One console, many projects**: one local Web runtime can switch between
   registered project roots.
 
-## Install
+## Install And Manage
 
 Node.js 24 or newer is required.
 
@@ -48,7 +48,7 @@ npm install -g @logicseek/hello-cc
 Update an existing global install:
 
 ```bash
-npm install -g @logicseek/hello-cc@latest
+hcc update
 ```
 
 Or run it without a global install:
@@ -57,6 +57,18 @@ Or run it without a global install:
 npx @logicseek/hello-cc web
 ```
 
+Remove hooks and shims from this machine:
+
+```bash
+hcc uninstall
+```
+
+Remove the global npm package:
+
+```bash
+npm uninstall -g @logicseek/hello-cc
+```
+
 ## Quick Start
 
 Run this inside the project you want agents to share:
@@ -110,12 +122,14 @@ generic session-isolation assumptions.
 
 ## Documentation
 
-- [User Guide](docs/guide.md): setup, Web console, commands, workflows, and
-  environment behavior.
+- [Documentation Index](docs/README.md): all user and implementation docs.
+- [User Guide](docs/guide.md): setup, Web console, workflows, coordination
+  semantics, and environment behavior.
+- [Command Reference](docs/commands.md): compact public command list.
+- [Changelog](CHANGELOG.md): release notes for published versions.
 - [Design Notes](docs/design.md): product boundaries and coordination model.
 - [Implementation Notes](docs/implementation.md): architecture and internal
   protocol.
-- [中文用户指南](docs/guide.zh-CN.md)
 
 ## Testing
 
@@ -129,3 +143,11 @@ temporary tmux sessions, and a temporary Web runtime to test the main flows.
 ## License
 
 [Apache-2.0](LICENSE)
+
+---
+
+<p align="center">
+  <a href="https://star-history.com/#Dullne/hello-cc&Date">
+    <img src="https://api.star-history.com/svg?repos=Dullne/hello-cc&type=Date" width="600" alt="Star History Chart">
+  </a>
+</p>

package/README.zh-CN.md

@@ -26,7 +26,7 @@
 - **resume 友好的稳定身份**：当 provider 暴露 session id 时，恢复会话会映射回稳定 peer。
 - **一个控制台管理多个项目**：单个本地 Web runtime 可以在多个 project root 之间切换。
 
-## 安装
+## 安装和维护
 
 需要 Node.js 24 或更新版本。
 
@@ -37,7 +37,7 @@ npm install -g @logicseek/hello-cc
 更新已有的全局安装：
 
 ```bash
-npm install -g @logicseek/hello-cc@latest
+hcc update
 ```
 
 也可以不全局安装，直接运行：
@@ -46,6 +46,18 @@ npm install -g @logicseek/hello-cc@latest
 npx @logicseek/hello-cc web
 ```
 
+移除本机 hooks 和 shims：
+
+```bash
+hcc uninstall
+```
+
+移除全局 npm 包：
+
+```bash
+npm uninstall -g @logicseek/hello-cc
+```
+
 ## 快速开始
 
 在需要多个 agent 共享状态的项目中运行：
@@ -95,10 +107,10 @@ hcc task done --id 1 --summary "Done"
 
 ## 文档
 
-- [用户指南](docs/guide.zh-CN.md)：安装、Web 控制台、常用命令、协作流程和环境变量行为。
-- [设计说明](docs/design.md)：产品边界和协作模型。
-- [实现说明](docs/implementation.md)：架构和内部协议。
-- [English User Guide](docs/guide.md)
+- [文档目录](docs/README.zh-CN.md)：全部用户文档和实现文档入口。
+- [用户指南](docs/guide.zh-CN.md)：安装、Web 控制台、协作流程、协作语义和环境变量行为。
+- [命令参考](docs/commands.zh-CN.md)：紧凑公共命令清单。
+- [更新日志](CHANGELOG.md)：已发布版本的 release notes。
 
 ## 测试
 
@@ -111,3 +123,11 @@ npm test
 ## License
 
 [Apache-2.0](LICENSE)
+
+---
+
+<p align="center">
+  <a href="https://star-history.com/#Dullne/hello-cc&Date">
+    <img src="https://api.star-history.com/svg?repos=Dullne/hello-cc&type=Date" width="600" alt="Star History Chart">
+  </a>
+</p>

package/assets/logo.svg

@@ -0,0 +1,84 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 240 240" width="240" height="240">
+  <defs>
+    <filter id="outerGlow" x="-10%" y="-10%" width="120%" height="120%">
+      <feGaussianBlur stdDeviation="4" result="blur"/>
+      <feMerge><feMergeNode in="blur"/><feMergeNode in="SourceGraphic"/></feMerge>
+    </filter>
+    <radialGradient id="bgGrad" cx="40%" cy="35%" r="70%">
+      <stop offset="0%" stop-color="#1a2028"/>
+      <stop offset="100%" stop-color="#0a0c0f"/>
+    </radialGradient>
+    <!-- Text gradient: white → teal, connects wordmark to mesh -->
+    <linearGradient id="textGrad" x1="0" y1="0" x2="0" y2="1">
+      <stop offset="0%" stop-color="#eef2f6"/>
+      <stop offset="100%" stop-color="#40c4aa"/>
+    </linearGradient>
+  </defs>
+
+  <!-- Badge -->
+  <circle cx="120" cy="120" r="114" fill="url(#bgGrad)" filter="url(#outerGlow)"/>
+  <circle cx="120" cy="120" r="113" fill="none" stroke="#303640" stroke-width="1.5"/>
+  <circle cx="120" cy="120" r="105" fill="none" stroke="#40c4aa" stroke-width="0.4" opacity="0.25"/>
+
+  <!--
+    Mesh pentagon — center (120, 108), circumradius R=65
+    Shifted down 8px from previous (was 100) for visual balance
+
+    Top:          (120,  43)
+    Upper-right:  (182,  88)
+    Lower-right:  (158, 161)
+    Lower-left:   ( 82, 161)
+    Upper-left:   ( 58,  88)
+  -->
+
+  <!-- Connections -->
+  <g stroke="#40c4aa" stroke-width="1.4" opacity="0.20" fill="none">
+    <line x1="120" y1="43"  x2="182" y2="88"/>
+    <line x1="120" y1="43"  x2="158" y2="161"/>
+    <line x1="120" y1="43"  x2="82"  y2="161"/>
+    <line x1="120" y1="43"  x2="58"  y2="88"/>
+    <line x1="182" y1="88"  x2="158" y2="161"/>
+    <line x1="182" y1="88"  x2="82"  y2="161"/>
+    <line x1="182" y1="88"  x2="58"  y2="88"/>
+    <line x1="158" y1="161" x2="82"  y2="161"/>
+    <line x1="158" y1="161" x2="58"  y2="88"/>
+    <line x1="82"  y1="161" x2="58"  y2="88"/>
+  </g>
+
+  <!-- Spoke lines from center hub -->
+  <g stroke="#40c4aa" stroke-width="0.8" opacity="0.12">
+    <line x1="120" y1="108" x2="120" y2="43"/>
+    <line x1="120" y1="108" x2="182" y2="88"/>
+    <line x1="120" y1="108" x2="158" y2="161"/>
+    <line x1="120" y1="108" x2="82"  y2="161"/>
+    <line x1="120" y1="108" x2="58"  y2="88"/>
+  </g>
+
+  <!-- Node halos — all equal (flat peer mesh, no hierarchy) -->
+  <circle cx="120" cy="43"  r="14" fill="none" stroke="#40c4aa" stroke-width="1" opacity="0.20"/>
+  <circle cx="182" cy="88"  r="14" fill="none" stroke="#40c4aa" stroke-width="1" opacity="0.20"/>
+  <circle cx="158" cy="161" r="14" fill="none" stroke="#40c4aa" stroke-width="1" opacity="0.20"/>
+  <circle cx="82"  cy="161" r="14" fill="none" stroke="#40c4aa" stroke-width="1" opacity="0.20"/>
+  <circle cx="58"  cy="88"  r="14" fill="none" stroke="#40c4aa" stroke-width="1" opacity="0.20"/>
+
+  <!-- All 5 nodes — same size, same style -->
+  <circle cx="120" cy="43"  r="10" fill="#40c4aa" opacity="0.85"/>
+  <circle cx="182" cy="88"  r="10" fill="#40c4aa" opacity="0.85"/>
+  <circle cx="158" cy="161" r="10" fill="#40c4aa" opacity="0.85"/>
+  <circle cx="82"  cy="161" r="10" fill="#40c4aa" opacity="0.85"/>
+  <circle cx="58"  cy="88"  r="10" fill="#40c4aa" opacity="0.85"/>
+
+  <!-- Center hub -->
+  <circle cx="120" cy="108" r="6" fill="#8ee8d8" opacity="1.0"/>
+
+  <!-- "hcc" wordmark -->
+  <text
+    x="120" y="210"
+    font-family="ui-monospace, SFMono-Regular, Menlo, Consolas, monospace"
+    font-size="30"
+    font-weight="700"
+    fill="url(#textGrad)"
+    text-anchor="middle"
+    letter-spacing="5"
+  >hcc</text>
+</svg>

package/bin/hcc.mjs

@@ -16,9 +16,10 @@ const _libDir = path.resolve(fileURLToPath(import.meta.url), '..', '..', 'lib');
 async function loadDiscover() { return import(path.join(_libDir, 'discover.mjs')); }
 async function loadSetup()    { return import(path.join(_libDir, 'setup.mjs')); }
 
-const VERSION = '0.1.1';
+const VERSION = '0.1.2';
 const PRODUCT_NAME = 'hello-cc';
 const CLI_NAME = 'hcc';
+const NPM_PACKAGE_NAME = '@logicseek/hello-cc';
 const DEFAULT_LOCK_TTL = 900;
 const ACTIVE_PEER_TTL = 600;
 // Directory under .hello-cc/ for optional external PTY buffer files.
@@ -128,6 +129,14 @@ function parseOpts(args, spec = {}) {
   return opts;
 }
 
+function wantsHelp(args) {
+  const stop = args.indexOf('--');
+  const scan = stop >= 0 ? args.slice(0, stop) : args;
+  const index = scan.findIndex((arg) => arg === '--help' || arg === '-h');
+  if (index < 0) return false;
+  return index <= 1 || !String(scan[index - 1] || '').startsWith('--');
+}
+
 function validateOpts(command, opts, allowed = []) {
   const allowedSet = new Set(['_', ...allowed]);
   for (const key of Object.keys(opts)) {
@@ -2289,7 +2298,7 @@ async function cmdPeers(ctx, args) {
 
 async function cmdTask(ctx, args) {
   const sub = args[0];
-  if (!sub || sub === '--help' || sub === '-h') return helpTask();
+  if (!sub || wantsHelp(args)) return helpTask();
   if (sub === 'create') return taskCreate(ctx, args.slice(1));
   if (sub === 'list') return taskList(ctx, args.slice(1));
   if (sub === 'claim') return taskClaim(ctx, args.slice(1));
@@ -2467,7 +2476,7 @@ async function taskDone(ctx, args) {
 
 async function cmdMsg(ctx, args) {
   const sub = args[0];
-  if (!sub || sub === '--help' || sub === '-h') return helpMsg();
+  if (!sub || wantsHelp(args)) return helpMsg();
   if (sub === 'send') return msgSend(ctx, args.slice(1));
   if (sub === 'inbox') return msgInbox(ctx, args.slice(1));
   if (sub === 'ack') return msgAck(ctx, args.slice(1));
@@ -2598,7 +2607,7 @@ async function cmdInject(ctx, args) {
 
 async function cmdPeer(ctx, args) {
   const sub = args[0];
-  if (!sub || sub === '--help' || sub === '-h') return helpPeer();
+  if (!sub || wantsHelp(args)) return helpPeer();
   if (sub === 'list') return peerList(ctx, args.slice(1));
   if (sub === 'start') return peerStart(ctx, args.slice(1));
   if (sub === 'attach') return peerAttach(ctx, args.slice(1));
@@ -2748,7 +2757,7 @@ async function peerStop(ctx, args) {
 
 async function cmdLock(ctx, args) {
   const sub = args[0];
-  if (!sub || sub === '--help' || sub === '-h') return helpLock();
+  if (!sub || wantsHelp(args)) return helpLock();
   if (sub === 'acquire') return lockAcquire(ctx, args.slice(1));
   if (sub === 'release') return lockRelease(ctx, args.slice(1));
   if (sub === 'renew') return lockRenew(ctx, args.slice(1));
@@ -2847,7 +2856,7 @@ async function lockList(ctx, args) {
 
 async function cmdHandoff(ctx, args) {
   const sub = args[0];
-  if (!sub || sub === '--help' || sub === '-h') return helpHandoff();
+  if (!sub || wantsHelp(args)) return helpHandoff();
   if (sub === 'create') return handoffCreate(ctx, args.slice(1));
   if (sub === 'list') return handoffList(ctx, args.slice(1));
   throw new CliError('BAD_ARGS', `Unknown handoff command: ${sub}`);
@@ -2900,7 +2909,7 @@ async function handoffList(ctx, args) {
 
 async function cmdEvent(ctx, args) {
   const sub = args[0];
-  if (!sub || sub === '--help' || sub === '-h') return helpEvent();
+  if (!sub || wantsHelp(args)) return helpEvent();
   if (sub === 'tail') return eventTail(ctx, args.slice(1));
   throw new CliError('BAD_ARGS', `Unknown event command: ${sub}`);
 }
@@ -5539,6 +5548,8 @@ Commands:
   web                          Start coordination, shims, tmux, and browser console
   up                           Initialize local coordination only
   down                         Stop the running hello-cc web runtime
+  update                       Update the global npm install of hello-cc
+  uninstall                    Remove hooks, shims, and optional project data
   init                         Initialize .hello-cc/mesh.db and guidance
   register --peer ID           Register or update a peer session identity
   join --peer ID               Register this shell and print eval-able env
@@ -5780,6 +5791,24 @@ Stops the web runtime started by hcc web for this project.
 `);
 }
 
+function helpUpdate() {
+  console.log(`${CLI_NAME} update
+
+Usage:
+  ${CLI_NAME} update [--tag TAG] [--registry URL] [--dry-run]
+
+Examples:
+  ${CLI_NAME} update
+  ${CLI_NAME} update --tag latest
+  ${CLI_NAME} update --dry-run
+
+Updates the global npm install by running:
+  npm install -g ${NPM_PACKAGE_NAME}@TAG
+
+The default TAG is latest.
+`);
+}
+
 function helpWeb() {
   console.log(`${CLI_NAME} web
 
@@ -6103,6 +6132,46 @@ async function cmdSetup(ctx, args) {
   log('\nDone. Run `hcc web` for the default coordinated terminal experience.');
 }
 
+// ─── hcc update ──────────────────────────────────────────────────────────────
+
+async function cmdUpdate(ctx, args) {
+  if (args[0] === '--help' || args[0] === '-h') return helpUpdate();
+
+  const opts = parseOpts(args, { booleans: ['dry-run'] });
+  validateOpts('update', opts, ['tag', 'registry', 'dry-run']);
+  const tag = opts.tag || 'latest';
+  if (!/^[A-Za-z0-9._+-]+$/.test(tag)) {
+    throw new CliError('BAD_ARGS', '--tag must be an npm dist-tag or version');
+  }
+
+  const packageSpec = `${NPM_PACKAGE_NAME}@${tag}`;
+  const npmArgs = ['install', '-g', packageSpec];
+  if (opts.registry) npmArgs.push('--registry', opts.registry);
+  const command = shellCommand(['npm', ...npmArgs]);
+  const data = { package: NPM_PACKAGE_NAME, tag, registry: opts.registry || null, command, dry_run: Boolean(opts['dry-run']) };
+
+  if (opts['dry-run']) {
+    printResult(ctx, data, () => `would run: ${command}`);
+    return;
+  }
+
+  const result = spawnSync('npm', npmArgs, {
+    encoding: ctx.json ? 'utf8' : undefined,
+    stdio: ctx.json ? ['ignore', 'pipe', 'pipe'] : 'inherit'
+  });
+  if (result.error) {
+    throw new CliError('UPDATE_FAILED', `npm update command failed: ${result.error.message}`);
+  }
+  if (result.status !== 0) {
+    const output = ctx.json
+      ? [result.stdout, result.stderr].filter(Boolean).join('\n').trim()
+      : '';
+    throw new CliError('UPDATE_FAILED', output || `npm exited with status ${result.status}`);
+  }
+
+  printResult(ctx, data, () => `updated ${packageSpec}`);
+}
+
 // ─── hcc uninstall ───────────────────────────────────────────────────────────
 
 async function cmdUninstall(ctx, args) {
@@ -6326,6 +6395,7 @@ async function dispatch(ctx, rest) {
   if (command === '--version' || command === 'version') return console.log(VERSION);
   if (command === 'up') return cmdUp(ctx, args);
   if (command === 'down') return cmdDown(ctx, args);
+  if (command === 'update') return cmdUpdate(ctx, args);
   if (command === 'uninstall') return cmdUninstall(ctx, args);
   if (command === 'init') return cmdInit(ctx, args);
   if (command === 'register') return cmdRegister(ctx, args);

package/docs/README.md

@@ -0,0 +1,22 @@
+# 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` before publishing, and use
+  `npm run release:notes` to print the current changelog section for GitHub
+  Release notes.
+
+## 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,22 @@
+# 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:notes` 输出当前版本的 changelog 小节，作为 GitHub
+  Release 描述。
+
+## 设计和实现
+
+- [设计说明](design.md)：产品边界、项目边界、能力层级、协作语义和 provider
+  session 绑定。
+- [实现说明](implementation.md)：架构、协议、命令面、技术栈、shim 行为和实现计划。
+
+设计和实现文档目前只有英文版。

package/docs/commands.md

@@ -0,0 +1,104 @@
+# 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-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. 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 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.
+
+## 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 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`.
+
+## 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]
+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`.
+
+## 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,101 @@
+# 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-discover] [--no-guidance]
+hcc down
+hcc up [--no-discover] [--no-guidance]
+```
+
+`hcc web` 是默认入口。它会初始化协作状态，安装 hooks 和 shims，启动或复用
+Web 控制台，然后把终端还给你。只想使用本地协作、不需要 Web 或 shims 时，
+再使用 `hcc up`。
+
+## Peers 和状态
+
+```text
+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...]
+```
+
+这些命令用于查看项目状态、注册终端，以及用 `HCC_PEER`、`HCC_ROOT`、
+`HCC_DB` 环境运行 CLI。
+
+## 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 ask PEER MESSAGE [--from ID] [--task N] [--inject]
+hcc broadcast MESSAGE [--from ID] [--task N] [--inject]
+```
+
+消息是带收件人的邮箱记录。`ask` 和 `broadcast` 加 `--inject` 后，也会把内容
+实时注入到终端。
+
+## 任务
+
+```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]
+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`。
+
+## 锁、交接和事件
+
+```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/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
 
@@ -222,62 +241,10 @@ 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.
 
-## 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
 

package/docs/guide.zh-CN.md

@@ -1,8 +1,9 @@
 # hello-cc 用户指南
 
-这份文档保存详细使用说明，README 只保留项目入口和快速开始。
+这份文档说明安装、启动和日常使用流程。紧凑命令清单见
+[命令参考](commands.zh-CN.md)。
 
-## 安装和更新
+## 安装、更新和卸载
 
 全局安装 hello-cc：
 
@@ -13,10 +14,29 @@ npm install -g @logicseek/hello-cc
 更新已有的全局安装：
 
 ```bash
-npm install -g @logicseek/hello-cc@latest
+hcc update
 ```
 
-`hcc` 没有自更新命令。`hcc task update` 更新的是协作任务状态，不是安装包版本。
+`hcc update` 会执行 `npm install -g @logicseek/hello-cc@latest`。使用
+`hcc update --help` 可以查看更新选项。`hcc task update` 更新的是协作任务状态，不是安装包版本。
+
+移除本机 hooks 和 shims：
+
+```bash
+hcc uninstall
+```
+
+同时移除当前项目的 `.hello-cc` 数据和指导块：
+
+```bash
+hcc uninstall --purge --yes
+```
+
+移除全局 npm 包：
+
+```bash
+npm uninstall -g @logicseek/hello-cc
+```
 
 ## 默认入口
 
@@ -194,62 +214,10 @@ Web 操作的是 hello-cc 管理的本机 tmux 终端：
 
 已经打开的普通 raw 终端不能被无条件捕获或控制，除非它原本就在 tmux、screen 或 hello-cc shim 之下。它仍然可以通过 hooks 和 `hcc` 命令参与任务、消息和锁。
 
-## 常用命令
+## 命令参考
 
-```text
-# 默认入口
-hcc web [--host HOST] [--port N] [--token TEXT] [--local] [--no-discover] [--no-guidance]
-hcc down
-
-# 本地协调，无 Web
-hcc up [--no-discover] [--no-guidance]
-
-# 对等节点和状态
-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...]
-
-# Web 可控终端
-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]
-
-# 消息
-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]
-
-# 任务
-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
-
-# 锁和交接
-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]
-```
+使用 `hcc --help` 查看命令列表，使用 `hcc <command> --help` 查看单个命令。
+维护中的命令摘要见 [命令参考](commands.zh-CN.md)。
 
 ## 稳定 peer 身份
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@logicseek/hello-cc",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Local control plane for coordinating Claude Code, Codex, and other coding CLI sessions.",
   "type": "module",
   "bin": {
@@ -11,8 +11,10 @@
     "bin/",
     "lib/",
     "scripts/",
+    "assets/",
     "README.md",
     "README.zh-CN.md",
+    "CHANGELOG.md",
     "LICENSE",
     "docs/"
   ],
@@ -20,6 +22,8 @@
     "node": ">=24.0.0"
   },
   "scripts": {
+    "release:notes": "node ./scripts/release-notes.mjs",
+    "release:check": "node ./scripts/release-notes.mjs --check",
     "smoke": "node ./bin/hcc.mjs --help",
     "test": "node ./scripts/regression.mjs",
     "test:regression": "node ./scripts/regression.mjs"

package/scripts/regression.mjs

@@ -1124,7 +1124,17 @@ async function downGcPackWorkflow() {
   await stopRuntime();
   await waitFor(() => !fs.existsSync(path.join(root, '.hello-cc', 'runtime.json')), 'runtime cleanup', 5000);
   hcc(['gc', '--older-than', '0', '--yes']);
-  run('npm', ['pack', '--dry-run']);
+  const pack = JSON.parse(run('npm', ['pack', '--dry-run', '--json']));
+  const files = new Set(pack[0]?.files?.map((entry) => entry.path) || []);
+  for (const file of ['assets/logo.svg', 'CHANGELOG.md', 'docs/commands.md', 'docs/commands.zh-CN.md']) {
+    if (!files.has(file)) fail(`npm package missing ${file}`);
+  }
+  const releaseCheck = run('npm', ['run', 'release:check']);
+  if (!releaseCheck.includes('release notes ok: 0.1.2')) fail(`release check output wrong:\n${releaseCheck}`);
+  const releaseNotes = run('npm', ['run', 'release:notes']);
+  if (!releaseNotes.includes('## 0.1.2') || !releaseNotes.includes('### Summary')) {
+    fail(`release notes output wrong:\n${releaseNotes}`);
+  }
 }
 
 function oldNameScan() {
@@ -1157,12 +1167,51 @@ function syntaxAndHelp() {
   run(process.execPath, ['--check', path.join(repoRoot, 'lib', 'setup.mjs')]);
   run(process.execPath, ['--check', path.join(repoRoot, 'lib', 'discover.mjs')]);
   const mainHelp = run(process.execPath, [hccBin, '--help']);
-  if (mainHelp.includes('setup') || mainHelp.includes('uninstall') || mainHelp.includes('--web-managed')) {
+  if (mainHelp.includes('setup') || mainHelp.includes('--web-managed')) {
     fail(`public help exposes maintenance or removed commands:\n${mainHelp}`);
   }
+  if (!mainHelp.includes('  update                       Update the global npm install of hello-cc')) {
+    fail(`main help missing update command:\n${mainHelp}`);
+  }
+  if (!mainHelp.includes('  uninstall                    Remove hooks, shims, and optional project data')) {
+    fail(`main help missing uninstall command:\n${mainHelp}`);
+  }
+  const updateHelp = run(process.execPath, [hccBin, 'update', '--help']);
+  if (!updateHelp.includes('hcc update') || !updateHelp.includes('npm install -g @logicseek/hello-cc@TAG')) {
+    fail(`update help missing expected content:\n${updateHelp}`);
+  }
+  const uninstallHelp = run(process.execPath, [hccBin, 'uninstall', '--help']);
+  if (!uninstallHelp.includes('hcc uninstall') || !uninstallHelp.includes('hcc uninstall [--purge --yes]')) {
+    fail(`uninstall help missing expected content:\n${uninstallHelp}`);
+  }
+  const updateDryRun = run(process.execPath, [hccBin, 'update', '--dry-run']);
+  if (!updateDryRun.includes('would run: npm install -g @logicseek/hello-cc@latest')) {
+    fail(`update dry-run output wrong:\n${updateDryRun}`);
+  }
+  const updateJson = JSON.parse(run(process.execPath, [hccBin, '--json', 'update', '--dry-run', '--tag', '0.1.2']));
+  if (!updateJson.ok || updateJson.data.command !== 'npm install -g @logicseek/hello-cc@0.1.2') {
+    fail(`update json dry-run output wrong:\n${JSON.stringify(updateJson)}`);
+  }
+  const updateBuildJson = JSON.parse(run(process.execPath, [hccBin, '--json', 'update', '--dry-run', '--tag', '1.2.3+build.1']));
+  if (!updateBuildJson.ok || updateBuildJson.data.command !== 'npm install -g @logicseek/hello-cc@1.2.3+build.1') {
+    fail(`update build-metadata dry-run output wrong:\n${JSON.stringify(updateBuildJson)}`);
+  }
   const runHelp = run(process.execPath, [hccBin, 'run', '--help']);
   if (runHelp.includes('--web-managed')) fail(`run help exposes removed --web-managed:\n${runHelp}`);
-  if (!run(process.execPath, [hccBin, 'peer', '--help']).includes('peer attach')) fail('peer attach missing from help');
+  const subcommandHelpCases = [
+    ['task', 'done', 'hcc task done'],
+    ['msg', 'ack', 'hcc msg ack'],
+    ['peer', 'attach', 'peer attach'],
+    ['lock', 'release', 'hcc lock release'],
+    ['handoff', 'create', 'hcc handoff create'],
+    ['event', 'tail', 'hcc event tail']
+  ];
+  for (const [group, subcommand, expected] of subcommandHelpCases) {
+    const help = run(process.execPath, [hccBin, group, subcommand, '--help']);
+    if (!help.includes(expected)) {
+      fail(`${group} ${subcommand} help missing expected content:\n${help}`);
+    }
+  }
   const removed = runMaybe(process.execPath, [hccBin, '--root', root, 'run', '--peer', 'bad', '--kind', 'shell', '--web-managed', '--', 'bash']);
   if (removed.status === 0 || !String(removed.stderr || removed.stdout).includes('unknown option --web-managed')) {
     fail(`run --web-managed was not rejected:\n${removed.stdout}\n${removed.stderr}`);

package/scripts/release-notes.mjs

@@ -0,0 +1,112 @@
+#!/usr/bin/env node
+
+import fs from 'node:fs';
+import path from 'node:path';
+import process from 'node:process';
+
+const repoRoot = path.resolve(import.meta.dirname, '..');
+
+function usage() {
+  console.log(`release-notes
+
+Usage:
+  node scripts/release-notes.mjs [--version VERSION] [--check]
+
+Reads CHANGELOG.md and prints the section for VERSION. If VERSION is omitted,
+the current package.json version is used.
+
+Keep one top-level CHANGELOG.md file. For each release, add a new section:
+
+  ## 0.1.3
+
+The printed section is the source for GitHub Release notes and detailed npm
+package release descriptions.
+`);
+}
+
+function readJson(file) {
+  return JSON.parse(fs.readFileSync(file, 'utf8'));
+}
+
+function parseArgs(argv) {
+  const opts = { check: false, help: false, version: null };
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === '--help' || arg === '-h') {
+      opts.help = true;
+    } else if (arg === '--check') {
+      opts.check = true;
+    } else if (arg === '--version') {
+      opts.version = argv[++i];
+      if (opts.version === undefined) throw new Error('Missing value for --version');
+    } else if (arg.startsWith('--version=')) {
+      opts.version = arg.slice('--version='.length);
+    } else {
+      throw new Error(`Unknown argument: ${arg}`);
+    }
+  }
+  return opts;
+}
+
+function releaseSection(markdown, version) {
+  const lines = markdown.split(/\r?\n/);
+  const heading = `## ${version}`;
+  const start = lines.findIndex((line) => line.trim() === heading);
+  if (start < 0) return null;
+
+  let end = lines.length;
+  for (let i = start + 1; i < lines.length; i += 1) {
+    if (/^##\s+/.test(lines[i])) {
+      end = i;
+      break;
+    }
+  }
+  return lines.slice(start, end).join('\n').trimEnd();
+}
+
+function validateSection(section, version) {
+  const problems = [];
+  if (!section) {
+    problems.push(`CHANGELOG.md is missing section ## ${version}`);
+    return problems;
+  }
+  if (!section.includes('### Summary')) problems.push(`## ${version} is missing ### Summary`);
+  if (!section.includes('### Highlights')) problems.push(`## ${version} is missing ### Highlights`);
+  if (section.includes('TODO') || section.includes('TBD')) problems.push(`## ${version} still contains TODO/TBD text`);
+  const bulletCount = (section.match(/^- /gm) || []).length;
+  if (bulletCount < 2) problems.push(`## ${version} should include at least two release-note bullets`);
+  return problems;
+}
+
+function main() {
+  const opts = parseArgs(process.argv.slice(2));
+  if (opts.help) {
+    usage();
+    return;
+  }
+
+  const pkg = readJson(path.join(repoRoot, 'package.json'));
+  const version = opts.version || pkg.version;
+  const changelog = fs.readFileSync(path.join(repoRoot, 'CHANGELOG.md'), 'utf8');
+  const section = releaseSection(changelog, version);
+  const problems = validateSection(section, version);
+
+  if (opts.check) {
+    if (problems.length) {
+      console.error(problems.join('\n'));
+      process.exitCode = 1;
+      return;
+    }
+    console.log(`release notes ok: ${version}`);
+    return;
+  }
+
+  if (problems.length) {
+    console.error(problems.join('\n'));
+    process.exitCode = 1;
+    return;
+  }
+  console.log(section);
+}
+
+main();