helloagents 3.0.29 → 3.0.31

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "helloagents",
-  "version": "3.0.29",
+  "version": "3.0.31",
   "description": "HelloAGENTS — The orchestration kernel that makes any AI CLI smarter. Adds intelligent routing, quality verification (Ralph Loop), safety guards, and notifications.",
   "author": {
     "name": "HelloWind",

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "helloagents",
-  "version": "3.0.29",
+  "version": "3.0.31",
   "description": "HelloAGENTS — Quality-driven orchestration kernel for AI CLIs with intelligent routing, quality verification (Ralph Loop), safety guards, and notifications.",
   "author": {
     "name": "HelloWind",

package/README.md

@@ -8,7 +8,7 @@
 
 **A workflow layer for AI coding CLIs: skills, project knowledge, delivery checks, safer config writes, and resumable execution.**
 
-[![Version](https://img.shields.io/badge/version-3.0.29-orange.svg)](./package.json)
+[![Version](https://img.shields.io/badge/version-3.0.31-orange.svg)](./package.json)
 [![npm](https://img.shields.io/npm/v/helloagents.svg)](https://www.npmjs.com/package/helloagents)
 [![Node](https://img.shields.io/badge/node-%3E%3D18-339933.svg)](./package.json)
 [![Skills](https://img.shields.io/badge/skills-14-6366f1.svg)](./skills)
@@ -100,7 +100,7 @@ HelloAGENTS includes 14 `hello-*` skills. They are loaded only when the current
 | `hello-reflect` | reusable lessons and knowledge updates |
 
 All UI work first follows the shared UI quality baseline.
-In global mode, activated projects, or explicit UI workflows, `hello-ui` adds deeper design-contract execution, design-system mapping, and visual validation on top of that baseline.
+In global mode, in initialized projects, or in explicit UI workflows, `hello-ui` adds deeper design-contract execution, design-system mapping, and visual validation on top of that baseline.
 When visual evidence is required, HelloAGENTS records it in the current session `artifacts/visual.json`.
 
 ### 2) Commands for different work styles
@@ -116,7 +116,8 @@ Commands run inside the AI CLI chat with a `~` prefix. The command skill is read
 | `~prd` | Modern product requirements document through guided dimension-by-dimension exploration |
 | `~loop` | Iterative improvement with metric, guard command, keep/revert decisions |
 | `~wiki` | Create or sync only the project knowledge base |
-| `~init` | Full project setup: knowledge base plus project-level rule files and package-root links |
+| `~init` | Same as `~wiki` |
+| `~global` | Initialize project-level global mode |
 | `~test` | Write tests for a target module or recent change |
 | `~verify` | Review, run verification commands, fix failures, and close out |
 | `~commit` | Generate a conventional commit message and sync knowledge |
@@ -146,9 +147,9 @@ The knowledge base helps future turns understand the repo without re-discovering
 | `plans/<feature>/` | active plan packages |
 | `archive/` | archived plan packages |
 
-`~wiki` creates or updates the knowledge base only.
+`~wiki` and `~init` create or update the knowledge base only.
 
-`~init` does more: it creates or updates the knowledge base, writes project-level rule files, and refreshes project-level HelloAGENTS package-root links for supported hosts.
+`~global` does more: it creates or updates the knowledge base, writes the project-level global-mode marker, and refreshes project-level HelloAGENTS package-root links for supported hosts.
 
 ### 4) Structured plan packages
 
@@ -264,7 +265,7 @@ Type:
 ~help
 ```
 
-You should see the 13 chat commands and the current settings.
+You should see the 14 chat commands and the current settings.
 
 ### 4) Create project knowledge
 
@@ -274,10 +275,10 @@ For knowledge base only:
 ~wiki
 ```
 
-For full project setup:
+For project-level global mode:
 
 ```text
-~init
+~global
 ```
 
 ## CLI Management
@@ -330,7 +331,7 @@ HELLOAGENTS=codex:global npm install -g helloagents
 HELLOAGENTS=claude:standby npm update -g helloagents
 
 # Switch to the beta branch and sync all CLIs in standby mode
-HELLOAGENTS=all:standby npm install -g github:hellowind777/helloagents#beta
+HELLOAGENTS=all:standby npm install -g https://github.com/hellowind777/helloagents/archive/refs/heads/beta.tar.gz
 
 # Clean Gemini integration before package uninstall
 npm explore -g helloagents -- npm run uninstall -- gemini --standby
@@ -350,7 +351,7 @@ $env:HELLOAGENTS="codex:global"; npm install -g helloagents
 $env:HELLOAGENTS="claude:standby"; npm update -g helloagents
 
 # Switch to the beta branch and sync all CLIs in standby mode
-$env:HELLOAGENTS="all:standby"; npm install -g github:hellowind777/helloagents#beta
+$env:HELLOAGENTS="all:standby"; npm install -g https://github.com/hellowind777/helloagents/archive/refs/heads/beta.tar.gz
 
 # Clean Gemini integration before package uninstall
 npm explore -g helloagents -- npm run uninstall -- gemini --standby
@@ -415,13 +416,13 @@ The PowerShell wrapper now forwards the same npm arguments as `install.sh`, so i
 ```bash
 helloagents switch-branch beta
 helloagents switch-branch beta claude --global
-helloagents branch github:hellowind777/helloagents#beta --all --standby
+helloagents branch beta --all --standby
 ```
 
 Use normal npm commands when you only want to change the package and not sync host CLIs immediately:
 
 ```bash
-npm install -g github:hellowind777/helloagents#beta
+npm install -g https://github.com/hellowind777/helloagents/archive/refs/heads/beta.tar.gz
 npm update -g helloagents
 npm explore -g helloagents -- npm run uninstall -- --all --standby
 npm uninstall -g helloagents
@@ -467,14 +468,14 @@ Codex global mode is installed by HelloAGENTS automatically through the local-pl
 | Implement from a clear request or active plan | `~build "finish task 2 in the plan"` |
 | Build a full product requirement document | `~prd "modern dashboard for operations team"` |
 | Iterate toward a metric | `~loop "reduce bundle size" --metric "npm run size" --direction lower` |
-| Create or refresh project knowledge only | `~wiki` |
-| Fully activate project workflow | `~init` |
+| Create or refresh project knowledge only | `~wiki` / `~init` |
+| Initialize project-level global mode | `~global` |
 | Validate current work | `~verify` |
 | Generate commit message and sync knowledge | `~commit` |
 
-### Activated vs unactivated projects
+### Knowledge base vs project-level global mode
 
-In standby mode, unactivated projects get lighter rules and explicit `~command` entry points. A project becomes activated when `.helloagents/` exists, usually through `~wiki` or `~init`.
+In standby mode, projects that are not initialized get lighter rules and explicit `~command` entry points. A project enters project-level global mode after `~global` writes `<!-- HELLOAGENTS_PROFILE: full -->`.
 
 In global mode, HelloAGENTS applies full rules by default.
 
@@ -488,16 +489,13 @@ By default, project knowledge lives in the project:
 .helloagents/
 ```
 
-This directory acts as both:
-
-- the activation signal
-- the local knowledge, plan, state, and runtime directory
+This directory is the local knowledge, plan, state, and runtime directory.
 
 ### Repo-shared mode
 
 When `project_store_mode = "repo-shared"`:
 
-- local `.helloagents/` keeps activation and runtime files
+- local `.helloagents/` keeps project-local state and runtime files
 - stable knowledge and plan files move to `~/.helloagents/projects/<repo-key>/`
 - multiple worktrees of the same git repo can share the same stable knowledge
 
@@ -510,9 +508,9 @@ Runtime state and evidence remain local to the working project:
 - `.helloagents/sessions/<workspace>/<session>/artifacts/*.json`
 - `.helloagents/sessions/<workspace>/<session>/artifacts/loop-results.tsv`
 
-### Unactivated or temporary sessions
+### Temporary sessions outside project-local storage
 
-If neither the current directory nor its parents contain an activated `.helloagents/` directory, HelloAGENTS does not write project files automatically. Temporary runtime state is kept under the user-level directory:
+For read-only work with no local output, if neither the current directory nor its parents contain a project-local `.helloagents/` directory, HelloAGENTS keeps short-lived runtime state under the user-level directory:
 
 ```text
 ~/.helloagents/runtime/<scope-key>/
@@ -520,15 +518,17 @@ If neither the current directory nor its parents contain an activated `.helloage
 
 This only stores short-lived `capsule.json`, `events.jsonl`, and `artifacts/`. It is not project knowledge. Expired transient sessions are removed by TTL cleanup.
 
+Once the task creates or modifies local files, or otherwise leaves local output in the current project, HelloAGENTS creates the project-local `.helloagents/sessions/.../STATE.md` automatically instead of keeping that task only in the user-level transient runtime.
+
 ### Knowledge creation rules
 
 | Command or setting | Behavior |
 |--------------------|----------|
-| `~wiki` | creates or syncs the knowledge base only |
-| `~init` | creates knowledge base plus project-level rule files and package-root links |
+| `~wiki` / `~init` | creates or syncs the knowledge base only |
+| `~global` | creates knowledge base plus project-level global-mode marker and package-root links |
 | `kb_create_mode = 0` | disables automatic knowledge updates |
-| `kb_create_mode = 1` | updates knowledge automatically for coding tasks in activated projects or global mode |
-| `kb_create_mode = 2` | updates knowledge more aggressively in activated projects or global mode |
+| `kb_create_mode = 1` | syncs knowledge automatically only when the KB already exists |
+| `kb_create_mode = 2` | for coding tasks, auto-creates or syncs the KB when it already exists or the project is in global mode |
 
 ## Workflow and Delivery
 
@@ -616,7 +616,7 @@ Default shape:
 | `notify_level` | `0` | `0` off, `1` desktop, `2` sound, `3` both |
 | `ralph_loop_enabled` | `true` | run verification for explicit `~verify` / `~loop` or required closeout gates |
 | `guard_enabled` | `true` | block dangerous commands |
-| `kb_create_mode` | `1` | control automatic knowledge base updates |
+| `kb_create_mode` | `1` | `0` off, `1` sync existing KB automatically, `2` auto-create or sync the KB for coding tasks |
 | `project_store_mode` | `"local"` | `local` or `repo-shared` |
 | `auto_commit_enabled` | `true` | auto-create a local commit at closeout when verification passed and the working tree changed; `false` skips only the automatic commit |
 | `commit_attribution` | `""` | optional text appended to commit messages |
@@ -668,11 +668,11 @@ Run all tests:
 npm test
 ```
 
-The current suite includes 124 tests and covers:
+The current suite covers:
 
 - install, update, cleanup, uninstall, branch switching, and mode switching
 - one-shot shell and PowerShell lifecycle dispatch, plus wrapper mode-routing rules for install, update, cleanup, uninstall, and branch switching
-- Claude, Gemini, and Codex config merge, restore, and native/global cleanup behavior
+- Claude, Gemini, and Codex host integration behavior
 - Codex managed `model_instructions_file`, `notify`, `hooks.json`, hook trust state, local plugin, marketplace, and cache behavior
 - Codex cleanup of legacy managed notify variants on Windows and canonical managed notify restoration rules
 - Codex `/goal` feature toggles, long-running route context, and goal-aware command contracts
@@ -697,15 +697,15 @@ Both.
 - `skills/` defines task-specific behavior
 - `scripts/` provides runtime helpers for routing, guard, notify, verification, state, and evidence
 
-### Should I use `~wiki` or `~init`?
+### Should I use `~wiki`, `~init`, or `~global`?
 
-Use `~wiki` when you only want project knowledge.
+Use `~wiki` or `~init` when you only want project knowledge.
 
-Use `~init` when you also want project-level rule files and project-level HelloAGENTS package-root links.
+Use `~global` when you also want project-level global mode.
 
 ### What is the difference between standby and global?
 
-`standby` is lighter and explicit. It deploys rules to selected CLIs and keeps full project workflow behind project activation.
+`standby` is lighter and explicit. It deploys rules to selected CLIs and keeps project-level global mode behind `~global`.
 
 `global` applies full rules broadly. Claude and Gemini use native plugin/extension installs. Codex uses the local-plugin path.
 

package/README_CN.md

@@ -8,7 +8,7 @@
 
 **面向 AI 编码 CLI 的工作流层：技能、知识库、交付检查、更安全的配置写入，以及可恢复的执行流程。**
 
-[![Version](https://img.shields.io/badge/version-3.0.29-orange.svg)](./package.json)
+[![Version](https://img.shields.io/badge/version-3.0.31-orange.svg)](./package.json)
 [![npm](https://img.shields.io/npm/v/helloagents.svg)](https://www.npmjs.com/package/helloagents)
 [![Node](https://img.shields.io/badge/node-%3E%3D18-339933.svg)](./package.json)
 [![Skills](https://img.shields.io/badge/skills-14-6366f1.svg)](./skills)
@@ -100,7 +100,7 @@ HelloAGENTS 内置 14 个 `hello-*` 技能。技能只在当前阶段需要时
 | `hello-reflect` | 可复用经验和知识更新 |
 
 所有 UI 任务都会先受共享的 UI 质量基线约束。
-在全局模式、已激活项目或明确的 UI 工作流里，`hello-ui` 会在该基线之上补充设计契约执行、设计系统映射与视觉验收。
+在全局模式、已初始化项目或明确的 UI 工作流里，`hello-ui` 会在该基线之上补充设计契约执行、设计系统映射与视觉验收。
 当需要视觉证据时，HelloAGENTS 会写入当前会话的 `artifacts/visual.json`。
 
 ### 2）面向不同工作方式的命令
@@ -116,7 +116,8 @@ HelloAGENTS 内置 14 个 `hello-*` 技能。技能只在当前阶段需要时
 | `~prd` | 通过逐维度讨论生成现代产品需求文档 |
 | `~loop` | 设置指标和守卫命令，循环改进、保留或回滚 |
 | `~wiki` | 只创建或同步项目知识库 |
-| `~init` | 完整项目初始化：知识库、项目级规则文件和包根链接 |
+| `~init` | 同 `~wiki` |
+| `~global` | 初始化项目级全局模式 |
 | `~test` | 为指定模块或最近变更编写测试 |
 | `~verify` | 审查、运行验证命令、修复失败并收尾 |
 | `~commit` | 生成规范化提交信息并同步知识库 |
@@ -146,9 +147,9 @@ HelloAGENTS 可以在 `.helloagents/` 下创建和维护项目知识库。
 | `plans/<feature>/` | 活跃方案包 |
 | `archive/` | 已归档方案包 |
 
-`~wiki` 只创建或更新知识库。
+`~wiki` 和 `~init` 只创建或更新知识库。
 
-`~init` 做得更多：创建或更新知识库、写入项目级规则文件，并刷新各宿主项目级 HelloAGENTS 包根链接。
+`~global` 做得更多：创建或更新知识库、写入项目级全局模式标记，并刷新各宿主项目级 HelloAGENTS 包根链接。
 
 ### 4）结构化方案包
 
@@ -209,7 +210,7 @@ HelloAGENTS 不把“命令通过”和“任务完成”简单画等号。交
 - `.helloagents/sessions/<workspace>/<session>/artifacts/closeout.json`
 - `.helloagents/sessions/<workspace>/<session>/artifacts/loop-results.tsv`
 
-交付门控、守卫和循环提示使用执行性表述，例如处理路径、收尾动作和视觉验收动作。阻塞流程会说明下一步要做什么，而不是把可执行步骤写成泛化建议。最终收尾还会强制只保留一个 HelloAGENTS 外层块，避免同一条回复重复输出完成标题。
+交付门控、守卫和循环提示使用执行性表述，例如处理路径、收尾动作和视觉验收动作。阻塞流程会说明下一步要做什么，而不是把可执行步骤写成泛化建议。最终回复还会强制只保留一个 HelloAGENTS 外层块，避免同一条回复重复输出完成标题。
 
 ### 7）更安全的安装、更新、清理和诊断
 
@@ -264,7 +265,7 @@ helloagents install --all --global
 ~help
 ```
 
-应能看到 13 个对话命令和当前设置。
+应能看到 14 个对话命令和当前设置。
 
 ### 4）创建项目知识
 
@@ -274,10 +275,10 @@ helloagents install --all --global
 ~wiki
 ```
 
-完整初始化项目：
+初始化项目级全局模式：
 
 ```text
-~init
+~global
 ```
 
 ## CLI 管理
@@ -330,7 +331,7 @@ HELLOAGENTS=codex:global npm install -g helloagents
 HELLOAGENTS=claude:standby npm update -g helloagents
 
 # 切换到 beta 分支并同步全部 CLI，标准模式
-HELLOAGENTS=all:standby npm install -g github:hellowind777/helloagents#beta
+HELLOAGENTS=all:standby npm install -g https://github.com/hellowind777/helloagents/archive/refs/heads/beta.tar.gz
 
 # 卸载包前清理 Gemini 集成
 npm explore -g helloagents -- npm run uninstall -- gemini --standby
@@ -350,7 +351,7 @@ $env:HELLOAGENTS="codex:global"; npm install -g helloagents
 $env:HELLOAGENTS="claude:standby"; npm update -g helloagents
 
 # 切换到 beta 分支并同步全部 CLI，标准模式
-$env:HELLOAGENTS="all:standby"; npm install -g github:hellowind777/helloagents#beta
+$env:HELLOAGENTS="all:standby"; npm install -g https://github.com/hellowind777/helloagents/archive/refs/heads/beta.tar.gz
 
 # 卸载包前清理 Gemini 集成
 npm explore -g helloagents -- npm run uninstall -- gemini --standby
@@ -415,13 +416,13 @@ PowerShell 包装脚本现在会传递与 `install.sh` 相同的 npm 参数，
 ```bash
 helloagents switch-branch beta
 helloagents switch-branch beta claude --global
-helloagents branch github:hellowind777/helloagents#beta --all --standby
+helloagents branch beta --all --standby
 ```
 
 如果只想切换包本身，暂不同步宿主 CLI，可以直接使用 npm：
 
 ```bash
-npm install -g github:hellowind777/helloagents#beta
+npm install -g https://github.com/hellowind777/helloagents/archive/refs/heads/beta.tar.gz
 npm update -g helloagents
 npm explore -g helloagents -- npm run uninstall -- --all --standby
 npm uninstall -g helloagents
@@ -467,14 +468,14 @@ Codex 全局模式由 HelloAGENTS 通过本地插件路径自动安装。
 | 按明确请求或活跃方案实现 | `~build "finish task 2 in the plan"` |
 | 生成完整产品需求文档 | `~prd "modern dashboard for operations team"` |
 | 按指标迭代优化 | `~loop "reduce bundle size" --metric "npm run size" --direction lower` |
-| 只创建或刷新项目知识 | `~wiki` |
-| 完整激活项目工作流 | `~init` |
+| 只创建或刷新项目知识 | `~wiki` / `~init` |
+| 初始化项目级全局模式 | `~global` |
 | 验证当前工作 | `~verify` |
 | 生成提交信息并同步知识库 | `~commit` |
 
-### 已激活项目与未激活项目
+### 知识库与项目级全局模式
 
-标准模式下，未激活项目只获得轻量规则和显式 `~command` 入口。项目中出现 `.helloagents/` 后才进入项目级工作流，通常由 `~wiki` 或 `~init` 创建。
+标准模式下，未初始化的项目只获得轻量规则和显式 `~command` 入口。执行 `~global` 后，项目级规则文件会写入 `<!-- HELLOAGENTS_PROFILE: full -->`，项目才进入项目级全局模式。
 
 全局模式下，HelloAGENTS 默认启用完整规则。
 
@@ -488,9 +489,8 @@ Codex 全局模式由 HelloAGENTS 通过本地插件路径自动安装。
 .helloagents/
 ```
 
-这个目录同时承担：
+这个目录承担：
 
-- 激活信号
 - 本地知识库目录
 - 方案目录
 - 状态与运行态目录
@@ -499,7 +499,7 @@ Codex 全局模式由 HelloAGENTS 通过本地插件路径自动安装。
 
 当 `project_store_mode = "repo-shared"` 时：
 
-- 本地 `.helloagents/` 保留激活和运行态文件
+- 本地 `.helloagents/` 保留项目本地状态和运行态文件
 - 稳定知识和方案文件写到 `~/.helloagents/projects/<repo-key>/`
 - 同一 git 仓库的多个 worktree 可以共享这些稳定资料
 
@@ -512,9 +512,9 @@ Codex 全局模式由 HelloAGENTS 通过本地插件路径自动安装。
 - `.helloagents/sessions/<workspace>/<session>/artifacts/*.json`
 - `.helloagents/sessions/<workspace>/<session>/artifacts/loop-results.tsv`
 
-### 未激活或临时会话
+### 项目本地存储之外的临时会话
 
-如果当前目录及其父级没有项目激活目录 `.helloagents/`，HelloAGENTS 不会自动写入项目目录。临时运行态写到用户级目录：
+如果当前任务是只读、且当前目录及其父级还没有项目本地 `.helloagents/` 目录，HelloAGENTS 会把短期运行态写到用户级目录：
 
 ```text
 ~/.helloagents/runtime/<scope-key>/
@@ -522,15 +522,17 @@ Codex 全局模式由 HelloAGENTS 通过本地插件路径自动安装。
 
 这里仅保存短期的 `capsule.json`、`events.jsonl` 和 `artifacts/`，不作为项目知识库。过期临时会话会按 TTL 清理。
 
+一旦任务会创建或修改本地文件，或会在当前项目留下本地输出，HelloAGENTS 就会自动创建项目本地 `.helloagents/sessions/.../STATE.md`，而不是只停留在用户级临时运行态。
+
 ### 知识创建规则
 
 | 命令或配置 | 行为 |
 |------------|------|
-| `~wiki` | 只创建或同步知识库 |
-| `~init` | 创建知识库，同时写入项目级规则文件和包根链接 |
+| `~wiki` / `~init` | 只创建或同步知识库 |
+| `~global` | 创建知识库，同时写入项目级全局模式标记和包根链接 |
 | `kb_create_mode = 0` | 关闭自动知识更新 |
-| `kb_create_mode = 1` | 已激活项目或全局模式中，编码任务自动更新知识 |
-| `kb_create_mode = 2` | 已激活项目或全局模式中，更积极地更新知识 |
+| `kb_create_mode = 1` | 仅在知识库已存在时自动同步 |
+| `kb_create_mode = 2` | 编码任务在知识库已存在或全局模式下自动创建或同步 |
 
 ## 工作流与交付
 
@@ -614,11 +616,11 @@ UI 任务遵循以下优先级：
 | 键 | 默认值 | 含义 |
 |----|--------|------|
 | `output_language` | `""` | 默认跟随用户语言 |
-| `output_format` | `true` | 主代理最终收尾必须使用 HelloAGENTS 格式；中间输出和子代理输出保持自然 |
+| `output_format` | `true` | 主代理最终回复必须使用 HelloAGENTS 格式；中间输出和子代理输出保持自然 |
 | `notify_level` | `0` | `0` 关闭，`1` 桌面通知，`2` 声音，`3` 两者 |
 | `ralph_loop_enabled` | `true` | 显式 `~verify` / `~loop` 或收尾要求时运行验证 |
 | `guard_enabled` | `true` | 拦截危险命令 |
-| `kb_create_mode` | `1` | 控制知识库自动更新 |
+| `kb_create_mode` | `1` | `0` 关闭，`1` 自动同步已有知识库，`2` 编码任务自动创建或同步知识库 |
 | `project_store_mode` | `"local"` | `local` 或 `repo-shared` |
 | `auto_commit_enabled` | `true` | 验证完成且工作区有变更时自动创建本地提交；`false` 只跳过自动提交 |
 | `commit_attribution` | `""` | 提交信息附加署名 |
@@ -670,11 +672,11 @@ Codex 默认走规则文件驱动。
 npm test
 ```
 
-当前测试共 124 项，覆盖：
+当前测试覆盖：
 
 - 安装、更新、清理、卸载、分支切换和模式切换
 - shell 与 PowerShell 一键脚本分发链路，以及包装脚本在安装、更新、清理、卸载和分支切换中的模式传递规则
-- Claude、Gemini、Codex 的配置合并、恢复，以及原生全局清理行为
+- Claude、Gemini、Codex 的宿主集成行为
 - Codex 受管 `model_instructions_file`、`notify`、`hooks.json`、hook trust 状态、本地插件、marketplace 和缓存行为
 - Windows 下 Codex 旧式受管 notify 变体的清理，以及受管 notify 恢复规则
 - Codex `/goal` 功能开关、长程路由上下文和 goal 感知命令契约
@@ -699,15 +701,15 @@ npm test
 - `skills/` 定义任务类型相关行为
 - `scripts/` 提供选路、Guard、通知、验证、状态和证据等运行时辅助能力
 
-### 应该用 `~wiki` 还是 `~init`？
+### 应该用 `~wiki`、`~init` 还是 `~global`？
 
-只想创建项目知识库，用 `~wiki`。
+只想创建项目知识库，用 `~wiki` 或 `~init`。
 
-还想写入项目级规则文件和宿主项目级 HelloAGENTS 包根链接，用 `~init`。
+还想初始化项目级全局模式，用 `~global`。
 
 ### standby 和 global 有什么区别？
 
-`standby` 更轻量、更显式。它只把规则部署到指定 CLI，完整项目流程由项目激活触发。
+`standby` 更轻量、更显式。它只把规则部署到指定 CLI，项目级全局模式由 `~global` 触发。
 
 `global` 默认更广泛地启用完整规则。Claude 和 Gemini 使用原生插件 / 扩展；Codex 使用本地插件路径。
 

package/bootstrap-lite.md

@@ -6,7 +6,7 @@
 配置文件: ~/.helloagents/helloagents.json
 `output_language` 非空时，所有用户可见文本使用该语言；为空则跟随用户当前语言。
 会话级缓存优先：当前上下文已有"当前用户设置"、原始 JSON 或读取摘要，且覆盖所需配置项时，直接复用。
-仅在缺少所需项、用户要求刷新，或本轮修改后需要核验时读取；对 Codex 来说，首次对话前若当前上下文仍缺少所需配置项，必须先读取一次 `~/.helloagents/helloagents.json`，压缩/恢复后的首次对话同样先重读一次；输出格式只在缺少 `output_format` 已知值时触发读取。
+仅在缺少所需项、用户要求刷新，或本次修改后需要核验时读取；对 Codex 来说，首次对话前若当前上下文仍缺少所需配置项，必须先读取一次 `~/.helloagents/helloagents.json`，压缩/恢复后的首次对话同样先重读一次；输出格式只在缺少 `output_format` 已知值时触发读取。
 同一会话内，同一路径的配置文件、模块、SKILL、模板只读一次并跨轮复用；读取失败必须明示，并按默认值或已知设置执行。
 
 ## 通用交付规则（强制）
@@ -107,8 +107,8 @@
 ## 交互、停顿与收尾
 ### 输出格式
 适用条件：
-- 当 `helloagents.json` 的 `output_format` 为 `true` 时，主代理必须在本轮最后一条、且确认**不再继续调用工具、不再继续执行**的**收尾消息**中使用输出格式。
-- 若某个 skill 在本轮明确要求输出停顿、确认或总结，也仅当该消息同时是**本轮最终收尾消息**时，才可使用输出格式。
+- 当 `helloagents.json` 的 `output_format` 为 `true` 时，主代理必须在每轮对话最后一条、且确认**不再继续调用工具、不再继续执行**的**最终回复**中使用输出格式。
+- 若某个 skill 在当前对话明确要求输出停顿、确认或总结，也仅当该消息同时是**当前对话的最终回复**时，才可使用输出格式。
 
 排除条件：
 - 当 `output_format` 为 `false` 时，所有回复保持自然输出，不得使用输出格式。
@@ -126,16 +126,16 @@
 图标：💡直接响应（一次性答复 / 只读分析） | ⚡快速执行（低风险直接执行） | 🔵规划流程（方案 / 规划产出） | ✅完成（已完成且无待确认动作） | ❓等待输入（等待用户输入 / 授权） | ⚠️警告（存在重要风险或限制） | ❌错误（发生错误或已阻塞）
 
 使用约束：
-- 首行必须保留 `【HelloAGENTS】` 和连字符 `-`，不得省略；状态图标与收尾内容必须一致。正文仍在等待用户输入、确认、授权或补充信息（含确认是否执行已给出的方案或修改）时，只能使用 `❓等待输入`；仅在本轮执行已完成且不存在待确认动作时，才能使用 `✅完成`。同一条最终收尾消息只使用一次该格式；若主体需要分段，在同一个外层块内分节，不得在正文中再次输出 `【HelloAGENTS】` 或第二个 `🔄 下一步`。
+- 首行必须保留 `【HelloAGENTS】` 和连字符 `-`，不得省略；状态图标与收尾内容必须一致。正文仍在等待用户输入、确认、授权或补充信息（含确认是否执行已给出的方案或修改）时，只能使用 `❓等待输入`；仅在当前对话执行已完成且不存在待确认动作时，才能使用 `✅完成`。同一条最终回复只使用一次该格式；若主体需要分段，在同一个外层块内分节，不得在正文中再次输出 `【HelloAGENTS】` 或第二个 `🔄 下一步`。
 - `🔄 下一步` 必须写真正的下一步动作，不写单纯当前状态或条件式能力表述。若正在等待确认，写清待确认动作；若仍有已授权且可继续执行的动作，不得收尾，必须继续执行；若当前任务已完整结束且确无合理后续，可明确写出任务已结束、无后续动作，不补条件式邀约。
 
 ### 收尾状态信号
-- `turn-state` 只在运行时必须识别本轮“完成 / 等待输入 / 阻塞”时写入；普通问候、普通问答、T0 只读分析和一次性解释不调用
-- 必须调用场景：显式 `~auto` / `~loop`；非只读任务完成验证并进入收尾；需要让运行时识别本轮已完成、等待输入或已阻塞时；已进入项目连续流程或方案包闭环
+- `turn-state` 只在运行时必须识别当前对话“完成 / 等待输入 / 阻塞”时写入；普通问候、普通问答、T0 只读分析和一次性解释不调用
+- 必须调用场景：显式 `~auto` / `~loop`；非只读任务完成验证并进入收尾；需要让运行时识别当前对话已完成、等待输入或已阻塞时；已进入项目连续流程或方案包闭环
 - 首选参数式调用，保证一次完成：`helloagents-turn-state write --kind complete --role main`；也可用 stdin JSON。不要查找、读取或拼接 `turn-state.mjs` 源码路径
-- 本轮已完成且不再等待用户输入 → `helloagents-turn-state write --kind complete --role main`
+- 当前对话已完成且不再等待用户输入 → `helloagents-turn-state write --kind complete --role main`
 - 因阻塞判定等待用户输入、确认、授权或补充信息（含未授权的外部副作用确认） → 写 `kind=waiting`、`role=main`，并同时写 `reasonCategory` 与 `reason`
-- 因错误、缺少前置条件或外部依赖而本轮停下 → 写 `kind=blocked`、`role=main`，并同时写 `reasonCategory` 与 `reason`
+- 因错误、缺少前置条件或外部依赖而当前对话停下 → 写 `kind=blocked`、`role=main`，并同时写 `reasonCategory` 与 `reason`
 - `reasonCategory` 只允许：`ambiguity`、`missing-input`、`missing-file`、`missing-credential`、`unauthorized-side-effect`、`high-risk-confirmation`、`external-dependency`、`error`
 - 显式 `~auto` / `~loop` 下，`waiting` / `blocked` 还必须写入 `blocker.target`、`blocker.evidence`、`blocker.requiredAction`；阶段汇报、单轮探测完成、路线调整或“下一步建议”不构成停下理由
 - 子代理不得写 turn-state；子代理结束只直接返回结果，不为主代理代写完成态
@@ -173,7 +173,7 @@
 以下情况才构成中途停下并请求用户输入的正当理由：
 - 需求存在影响执行结果的真实歧义
 - 缺少继续执行所必需的信息、文件、路径或凭据
-- 将产生外部副作用，但本轮尚未获得对应授权（含等待确认是否实施已给方案）
+- 将产生外部副作用，但当前任务尚未获得对应授权（含等待确认是否实施已给方案）
 - 操作属于高风险或不可逆，按安全规则必须确认
 除上述情况外，默认继续执行。
 
@@ -198,20 +198,20 @@
 - `T3` — 高风险或不可逆操作（权限、安全、支付、数据库、生产发布等）→ 先 `~plan` / `~prd`，再 `~build` / `~verify`
 
 ### 完成判定
-- 未激活项目且未进入方案包 / `contract.json` / 证据文件时，声称完成前必须完成与任务类型匹配的必要检查；无法执行的检查必须明确说明，不得直接宣称完成
-- 当前项目已激活，或已存在方案包 / `contract.json` / 证据文件时，以完整流程、对应 skill 与运行时交付约束为准，不得降级为本节
+- 当前项目未初始化，且未进入方案包 / `contract.json` / 证据文件时，声称完成前必须完成与任务类型匹配的必要检查；无法执行的检查必须明确说明，不得直接宣称完成
+- 当前项目已初始化，或已存在方案包 / `contract.json` / 证据文件时，以完整流程、对应 skill 与运行时交付约束为准，不得降级为本节
 - 只读分析、创意探索、方案比较、中间进度和阻塞汇报不适用本节
 - Codex `/goal` 只作为外层长程续跑与预算控制；HelloAGENTS 仍负责方案、执行、验证和收尾。若 active goal 的目标已全部完成，先完成 HelloAGENTS 验证、收尾检查与本地版本检查点，再调用 `update_goal` 标记 complete；不得因预算接近耗尽、单轮结束或准备停下而标记 complete
-- 本地版本检查点：非只读任务完成验证且产生工作区变更时，若 `auto_commit_enabled=true`，最终收尾前自动执行本地提交；若 `auto_commit_enabled=false`，跳过这一步。先检查 `git status --short`；若不是 git 仓库或无变更则跳过。若发现 `.env`、密钥、凭据、明显不应提交的大文件或二进制产物，停止提交并说明风险；否则执行 `git add -A`，使用当前回复语言生成简洁 conventional commit message 后执行 `git commit`。显式 `~commit` 不受这个开关影响。不自动远程 `git push`，除非用户明确要求
+- 本地版本检查点：非只读任务完成验证且产生工作区变更时，若 `auto_commit_enabled=true`，最终回复前自动执行本地提交；若 `auto_commit_enabled=false`，跳过这一步。先检查 `git status --short`；若不是 git 仓库或无变更则跳过。若发现 `.env`、密钥、凭据、明显不应提交的大文件或二进制产物，停止提交并说明风险；否则执行 `git add -A`，使用当前回复语言生成简洁 conventional commit message 后执行 `git commit`。显式 `~commit` 不受这个开关影响。不自动远程 `git push`，除非用户明确要求
 
 ### 命令路由
 - `~do` 是 `~build` 的兼容别名；`~design` 是 `~plan` 的兼容别名；`~review` 是 `~verify` 的兼容别名
 - `~test` — 为指定模块或最近变更编写测试
-- 路径定义：`{HELLOAGENTS_READ_ROOT}` = 本轮已确定的 HelloAGENTS 读取根目录，统一用于读取 `skills/` 与 `templates/`
+- 路径定义：`{HELLOAGENTS_READ_ROOT}` = 当前对话已确定的 HelloAGENTS 读取根目录，统一用于读取 `skills/` 与 `templates/`
 - `~command` 路由：用户输入 `~xxx` 时，立即读取对应的 SKILL.md 并按其流程执行，不要自行探索或猜测。若当前上下文已解析出具体命令技能文件路径，直接使用它；否则先确定当前技能根目录：
-  - 优先使用当前上下文中已注入的“本轮 HelloAGENTS 读取根目录”
+  - 优先使用当前上下文中已注入的“当前对话 HelloAGENTS 读取根目录”
   - 若当前上下文未注入，则使用稳定运行根目录 `~/.helloagents/helloagents`
-  - 宿主固定链接（Codex `~/.codex/helloagents`、Claude `~/.claude/helloagents`、Gemini `~/.gemini/helloagents`）只作为兼容别名，不作为优先探测路径
+- 宿主固定链接（Codex `~/.codex/helloagents`、Claude `~/.claude/helloagents`、Gemini `~/.gemini/helloagents`）只作为兼容别名，不作为优先探测路径
   - 仍无法确定时，明确说明缺少 HelloAGENTS 读取根目录；不要递归扫描 `$HOME`、`Downloads`、项目目录或旧版本目录
   确定根目录后读取其中的 `skills/commands/{name}/SKILL.md`；标准模式下即使项目目录存在本地 HelloAGENTS skills，也不要读取项目路径。不要扫描整个目录，也不要对同一命令重复探测多个路径。
 包内脚本优先使用稳定命令入口；涉及 turn-state 时按“收尾状态信号”执行。
@@ -220,19 +220,19 @@
 ### .helloagents/ 目录
 路径: {CWD}/.helloagents/
 所有文件的创建和更新必须按 templates/ 目录中对应模板的格式执行，不可自由发挥格式。
-- `.helloagents/` 表示项目级存储路径，也是标准模式的项目激活信号
+- `.helloagents/` 表示项目本地存储路径，负责知识、方案、状态与运行态；它不再作为项目是否已初始化的判定信号
 - `state_path` 指向的状态文件、当前会话 `capsule.json`、`events.jsonl`、`artifacts/*.json`、`artifacts/loop-results.tsv` 等运行态文件始终保留在项目本地 `.helloagents/sessions/{workspace}/{session}/`
 - `state_path` 是状态文件的唯一位置。宿主提供会话标识时，写入 `.helloagents/sessions/{workspace}/{session}/STATE.md`；没有稳定会话标识时，写入 `.helloagents/sessions/{workspace}/default/STATE.md`
 - `{workspace}` 为当前 Git 分支、`detached-{sha}` 或非 Git 项目的 `workspace`；`.helloagents/sessions/active.json` 只记录当前活跃会话索引，避免同一会话被拆成多个目录
 - 若 helloagents.json 中 `project_store_mode = "repo-shared"`，`context.md`、`guidelines.md`、`CHANGELOG.md`、`verify.yaml`、`DESIGN.md`、`modules/`、`plans/`、`archive/` 改按当前上下文中已注入的“当前项目存储”/“项目知识/方案目录”解析；未注入具体路径时，按当前存储模式自行解析，不要假定这些文件一定实际位于当前工作树中
-templates/ 查找路径（按优先级；首次确定模板根目录后，本轮复用）：
+templates/ 查找路径（按优先级；首次确定模板根目录后，本会话复用）：
 按上文 `~command` 路由中的相同技能根目录规则确定；确定根目录后读取其中的 `templates/`。
 
 ### 流程状态（不受 `kb_create_mode` 控制，始终可写）
 - 状态文件（`state_path`）— ≤70 行，用来记录“上次做到哪里”。判断当前任务时，当前用户消息、显式命令、活跃方案包 / PRD、代码与验证证据优先于状态文件
   内容：主线目标、正在做什么、关键上下文（决策/变更/假设）、下一步（具体可执行动作含文件路径）、阻塞项
   适用边界：
-  - 强制创建并持续更新：`~wiki`、`~init`、`~plan`、`~build`、`~auto`、`~prd`、`~loop`，以及已激活项目的连续任务
+  - 强制创建并持续更新：`~wiki`、`~init`、`~global`、`~plan`、`~build`、`~auto`、`~prd`、`~loop`，以及任何会创建/修改本地文件、会在当前工作区留下实际输出或操作记录的非只读任务
   - 强制更新，不要求首次创建：`~clean`，主代理汇总子代理结果后
   - 已有则更新：`~verify`、`~review`（兼容别名）、`~test`、`~commit`
   - 不创建：`~help`、`~idea`、普通问答、一次性只读任务、子代理自身执行过程、压缩/恢复钩子
@@ -253,7 +253,7 @@ templates/ 查找路径（按优先级；首次确定模板根目录后，本轮
 - archive/_index.md — 归档索引
 
 ### 知识记录（受 `kb_create_mode` 控制）
-- 0=关闭；1=已激活项目或全局模式中的编码任务自动同步；2=已激活项目或全局模式中始终同步
+- 0=关闭；1=知识库已存在时自动同步；2=编码任务在知识库已存在或全局模式下自动创建或同步
 - context.md — 项目架构、技术栈、目录结构、模块索引
 - guidelines.md — 编码约定（仅含非显而易见的约定）
 - CHANGELOG.md — 变更历史
@@ -268,7 +268,7 @@ templates/ 查找路径（按优先级；首次确定模板根目录后，本轮
 - artifacts/closeout.json — 当前会话最近一次成功收尾的交付证据快照
 
 ### 主线判断依据
-1. 当前用户最新消息、显式 `~command`、本轮已确认的范围与结论
+1. 当前用户最新消息、显式 `~command`、当前对话已确认的范围与结论
 2. 当前活跃方案包 / PRD、代码与验证证据
 3. 当前状态文件（`state_path`，只用于补齐最近进度）
 4. 其他知识记录与历史归档