docs(fix): 修正审计抓出的文档/UX 失实（成员制/hooks/跨机auth警告/printHelp）

docs/09-v3协作系统规格.md

@@ -145,7 +145,7 @@ adapter 暴露成 `abg send --to <agent>` 或 MCP 工具一个 `to` 参数。
 
 新增事件类型，结构化字段（见附录 A schema）：`summary`（一句话人类可读）、`repo`、`branch`、`commit?`、`contract?`、`unblocks?`（房间内相关性高亮用）。
 
-- **发布侧**：复用 `plugins/agentbridge/hooks/hooks.json`，把 agent 完成钩子（Claude `TaskCompleted`/`Stop`、Cursor `stop`、OpenCode `session.idle`……）接到 `abg publish`，干完自动发进当前 room。再补 MCP 工具 `announce` 作为 agent 主动宣布的手动路径。
+- **发布侧**：复用 `plugins/agentbridge/hooks/hooks.json`，把 agent 完成钩子（Claude `Stop`、Cursor `stop`、OpenCode `session.idle`……）接到 `abg publish`，干完自动发进当前 room。再补 MCP 工具 `announce` 作为 agent 主动宣布的手动路径。
 - **订阅侧**：复用现有 channel 推送（`claude-adapter.ts`）/ `turn/start` 注入（`codex-adapter.ts`），新增对该事件类型的分支。
 - **完成的判断权（MVP）**：默认 agent 钩子触发 = **软通知**（"一轮结束"≠"真完成"，仅作进度）；可选由人确认 `abg done` 下硬判断。**不做 CI 背书那一档**（与跨 room 一起砍，见第 10 节）。
 - **噪音控制（重要）**：多人多 agent 下每个 `Stop` 都发会刷屏。`abg publish` 内必须做**去重 + 节流**（如同一 `(agentId, repo, branch)` 短时间窗内合并、空内容轮次不发），附录 C 说明。
@@ -509,17 +509,21 @@ interface TaskCompletedEvent {
 ```jsonc
 {
   "hooks": {
-    "TaskCompleted": [
-      { "hooks": [ {
-        "type": "command",
-        "command": "abg publish --from-hook",  // 组装 task_completed 发进当前 room；自身不应再触发发布(防回环)
-        "async": true, "timeout": 30
-      } ] }
+    "Stop": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash \"${CLAUDE_PLUGIN_ROOT}/scripts/publish-completion.sh\""
+          }
+        ]
+      }
     ]
   }
 }
 ```
-> 无 `TaskCompleted` 的 agent 退用其完成钩子（Cursor `stop`、OpenCode `session.idle`），并在 `abg publish` 内做**去重/节流**，避免把每轮普通回复当"完成"广播。
+> Claude Code 实际使用 `Stop` 钩子（**每轮 Claude 停止响应时触发**，非会话终结）；`TaskCompleted` 在 Claude Code 中**不存在**。命令通过 `publish-completion.sh` 脚本组装并发布完成事件，内置去重/节流，避免每轮普通回复都广播。字段 `async`/`timeout` 不属于 Claude Code hooks.json 规范，不需要填写。
 
 ## 附录 D：Adapter 接口（Edge 层每个 agent 实现）
 

docs/10-跨网部署与运维.md

@@ -22,7 +22,7 @@
 1. **网络层（Tailscale ACL）**：设备没打 `tag:agent` → 连 `100.x:4700` 直接被 tailnet ACL 拒，WS 都建立不起来。
 2. **应用层（broker PSK）**：已在 tailnet 内的设备，仍需 `abg auth login` 签发的 token；握手失败 broker 直接 4401 关连接，且从不回显 token。
 
-> 🔸 **重要边界：鉴权 ≠ room 授权**。当前 MVP 是「单团队、共享 tailnet、扁平信任」模型——broker 的 `subscribe` 不做 room 成员校验，**任何通过 PSK 的身份能订阅任意 room**。ACL 限的是"哪些设备能碰 broker"，**限不了一个 token 能进哪些 room**（per-room 授权是 §11.2 演进档）。别误以为 ACL/PSK 提供了房间级隔离。
+> 🔐 **三层叠加**：Tailscale ACL（设备层）+ PSK（应用层连接）+ **成员制授权**（room 层）。broker 的 `subscribe` 和 `publish` 都经过 `isMember` 门控，**非成员一律拒绝（closed-by-default，fail-closed）**；被 `abg room remove` 踢出后，存活订阅在下次成员复检（≤ 缓存 TTL，默认 3s）时被驱逐——窃听窗口 ≤ 3s，不再到断连为止。
 
 ---
 
@@ -63,6 +63,7 @@ abg broker start --host 100.x.y.z --port 4700
 abg auth login --id <email|github> --name <显示名>   # → 打印 token
 ```
 
+- ⚠️ **必须在 broker 机上跑**：token 签进**本机** store，而 broker 只认**自己** store 里的 token。边机自己跑 `abg auth login` 自签的 token broker **不认（4401）**。跨机正确做法是在 broker 机为每个参与者签发 + 带外分发——真正的一条龙 `abg auth issue`（broker 侧签发）/ `abg auth login --token`（边机安装）/ `abg room invite` **正在实现**；在那之前跨机靠 broker 机签发 + 边机手动写 `<state>/auth-token`。
 - token 落 `<state>/auth-token`（0600）+ `collab.db`（0700 目录）；broker 从不回显。
 - **带外分发**（IM / 密码器），勿提交 git。
 - ⚠️ **目前没有 revoke/rotation CLI**：泄漏的 PSK 永久有效。临时手段=换 token 重签 + 清理旧库（token hashing at rest / revoke 列入 backlog）。

docs/manual/manual-en.md

@@ -28,7 +28,7 @@
 
 **Release install:**
 ```bash
-abg install:global        # install/update the global abg + agentbridge commands + plugin
+bun run install:global    # install/update the global abg + agentbridge commands + plugin
 ```
 
 **Testing (from the repo):**
@@ -112,8 +112,14 @@ Distribute each person's token **out of band** (IM / password manager; never com
 # (a) point at the remote broker (Tailscale 100.x or MagicDNS)
 export AGENTBRIDGE_BROKER_URL=ws://100.x.y.z:4700/ws
 
-# (b) place the admin-issued token (abg auth login writes it locally)
-abg auth login --id bob@team.dev --name Bob          # local login state
+# (b) ⚠️ Cross-machine auth is NOT yet functional — do NOT follow this step
+# Problem: abg auth login creates a brand-new self-signed token locally, but the
+# broker only accepts tokens already in its own collab.db store; a locally-created
+# token is unknown to the broker → connection rejected with 4401.
+# Current workaround: the admin issues the token on the broker machine (§3.2(b)),
+# delivers it out-of-band, and the participant writes it into <state>/auth-token
+# on their machine (path shown by `abg doctor`).
+# ⚠️ A proper `abg auth issue` / `abg auth login --token` command is in progress (feat/v3-xnet-onboarding).
 
 # (c) map the current working directory to the room (auto-joins this dir next time)
 abg join checkout

docs/manual/manual.html

@@ -65,7 +65,7 @@ <h2><span class="zh">0 · 5 分钟理解</span><span class="en">0 · Understand
   <!-- 1 install -->
   <h2><span class="zh">1 · 安装</span><span class="en">1 · Install</span></h2>
   <p><span class="zh">运行时是 <b>Bun</b>。正式发布后：</span><span class="en">Runtime is <b>Bun</b>. After release:</span></p>
-  <pre>abg install:global   <span class="c"># <span class="zh">安装/更新全局命令 + 插件</span><span class="en">install/update global commands + plugin</span></span></pre>
+  <pre>bun run install:global   <span class="c"># <span class="zh">安装/更新全局命令 + 插件</span><span class="en">install/update global commands + plugin</span></span></pre>
   <p><span class="zh">测试期（从仓库）：</span><span class="en">During testing (from the repo):</span></p>
   <pre>bun install
 bun run build:cli
@@ -104,6 +104,7 @@ <h3><span class="zh">② 每台参与者机：连 broker + 落 token + 起 agent
 abg join checkout    <span class="c"># <span class="zh">关联当前目录→房间</span><span class="en">map cwd → room</span></span>
 abg claude           <span class="c"># <span class="zh">或 abg codex</span><span class="en">or abg codex</span></span>
 abg init</pre>
+    <p class="sub"><span class="zh">⚠️ 注意：上面的 <code>abg auth login --id</code> 跨机当前<b>不通</b>——边机自签的 token 不在 broker 机的库里，会被拒（4401）。正在补 <code>abg auth issue</code>（broker 侧签发）+ <code>abg auth login --token</code>（边机安装）+ <code>abg room invite</code> 一条龙；在那之前跨机请按 <a href="../10-跨网部署与运维.md">docs/10</a> 的手动流程。</span><span class="en">⚠️ The <code>abg auth login --id</code> step above does NOT work cross-machine yet (an edge-signed token isn't in the broker's store → 4401); a real onboarding flow is being added.</span></p>
   </div>
 
   <div class="step">

docs/manual/使用手册.md

@@ -28,7 +28,7 @@
 
 **正式安装（发布后）**：
 ```bash
-abg install:global        # 安装/更新全局 abg + agentbridge 命令 + 插件
+bun run install:global    # 安装/更新全局 abg + agentbridge 命令 + 插件
 ```
 
 **测试期（从仓库）**：
@@ -112,9 +112,12 @@ abg room list                                        # 看所有房间
 # (a) 指向远程 broker（Tailscale 100.x 或 MagicDNS）
 export AGENTBRIDGE_BROKER_URL=ws://100.x.y.z:4700/ws
 
-# (b) 放入管理员发来的 token（abg auth login 写本地，或直接落 auth-token 文件）
-abg auth login --id bob@team.dev --name Bob          # 本机登录态
-# （token 与 broker 端一致即可被鉴权）
+# (b) ⚠️ 跨机 auth 当前不通，勿照此操作
+# 问题：abg auth login 在本机自签新 token，但 broker 只认 broker 机 collab.db 里的 token；
+# 本机自签的 token 不在 broker store → 连接时收到 4401 鉴权失败。
+# 当前手动流程：由管理员在 broker 机上签发 token（§3.2(b)），带外发给参与者，
+# 手动写入参与者机的 <state>/auth-token 文件（路径见 abg doctor 输出）。
+# ⚠️ 正式的 abg auth issue / abg auth login --token 子命令尚在开发中，见 feat/v3-xnet-onboarding。
 
 # (c) 把当前工作目录关联到房间（今后该目录自动加入）
 abg join checkout

docs/test-plans/13-acceptance.md

@@ -55,4 +55,4 @@ docker compose -f docker/docker-compose.scenario.yml logs -f
 
 ## 真·三机（后续）
 
-家里机 + 公司 MacBook + Mac mini 的真实跨机测试：先在各机装 v3 build（建议合并后 `abg install:global`）、各机 `abg auth login` + 同房间、一台 `abg broker start --host 100.x`、起真实 Claude 会话。步骤见 [docs/10](../10-跨网部署与运维.md)。
+家里机 + 公司 MacBook + Mac mini 的真实跨机测试：先在各机装 v3 build（建议合并后 `bun run install:global`）、一台 `abg broker start --host 100.x`、**在 broker 机**为各参与者签发 token（⚠️ 边机自己 `abg auth login` 自签的 token broker 不认 4401；跨机签发/安装的 `abg auth issue` / `auth login --token` / `room invite` 一条龙正在实现）、参与者带外拿 token + join 同房间、起真实 Claude 会话。步骤见 [docs/10](../10-跨网部署与运维.md)。