holo-codex 0.1.0 → 0.1.2

package/CHANGELOG.md

@@ -0,0 +1,21 @@
+# Changelog
+
+## 0.1.2
+
+- Added the manual GitHub Actions Release workflow for npm Trusted Publishing, dry-run tarball validation, and registry install smoke.
+- Added audited maintainer override support for lifecycle gates so verified release and merge operations can proceed with recorded evidence.
+- Relaxed the hook allowlist for maintainer-owned commands after verified evidence is present.
+- Hardened Codex hook and MCP startup compatibility for current Codex configurations.
+- Fixed dashboard Cleanup status consistency so sidebar substages and the main cleanup checklist use the same cleanup evidence.
+- Added the `next_issue_selected` cleanup checklist item to keep cleanup progress complete and visible.
+- Validated the release path with the existing GitHub Actions Release workflow, tarball checks, and dashboard smoke requirements.
+- Kept #16, #17, #18, and #19 as follow-up improvements outside this release-prep PR.
+
+## 0.1.1
+
+- Fixed the bundled Codex plugin hooks schema for newer Codex config parsers.
+- Kept stable runtime identifiers unchanged: `agent-loop`, `.agent-loop/`, and `autonomous-pr-loop`.
+
+## 0.1.0
+
+- Initial public npm release of HOLO-Codex.

package/README.md

@@ -4,62 +4,109 @@
 
 ![HOLO-Codex README hero](./assets/brand/holo-codex-readme-hero.png)
 
-HOLO-Codex, short for **Human On Loop Codex**, turns long-running Codex workflows into observable, recoverable, human-on-loop systems. The operator sets goals and boundaries, observes progress, and steps in only when a real gate needs attention.
+[![npm version](https://img.shields.io/npm/v/holo-codex?color=0f766e)](https://www.npmjs.com/package/holo-codex)
+[![npm downloads](https://img.shields.io/npm/dm/holo-codex)](https://www.npmjs.com/package/holo-codex)
+[![GitHub release](https://img.shields.io/github/v/release/tizerluo/HOLO-Codex)](https://github.com/tizerluo/HOLO-Codex/releases)
+[![CI](https://github.com/tizerluo/HOLO-Codex/actions/workflows/ci.yml/badge.svg)](https://github.com/tizerluo/HOLO-Codex/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
+![Node >=22.5](https://img.shields.io/badge/node-%3E%3D22.5-339933)
 
-The supervisor owns durable workflow state, evidence, gates, worker orchestration, Codex hooks, the MCP control plane, and the local dashboard. Workers perform scoped tasks and return structured output.
+HOLO-Codex, short for **Human On Loop Codex**, turns long-running Codex workflows into observable, recoverable systems that you can supervise without living inside chat history.
 
-## What It Provides
+Codex can plan, edit, test, review, and hand work across agents. HOLO-Codex gives that work a local control plane: workflow state, evidence, gates, hooks, review status, recovery actions, and a dashboard you can open while the work is running.
 
-- A Codex plugin under `plugins/autonomous-pr-loop/`.
-- The `agent-loop` CLI for local loop state, hooks, dashboard, workflow evidence, and rollback-safe local install.
-- Local SQLite state under `.agent-loop/`.
-- A local dashboard for Mission Control, workflow board, observability, gates, review/CI state, workers, artifacts, recovery, notifications, policy config, and theme modes.
-- stdio MCP control plane.
-- Codex hooks for policy checks and observability.
-- TypeScript + Vitest test suite.
-- Bilingual display support for `zh-CN`, `en-US`, and `system` locale selection.
-- Workflow profiles, role profiles, `generic-loop`, and the first bundled workflow: `pr-loop`.
+## Quickstart
 
-This is not a hosted service. It does not run GitHub webhooks or cloud workers.
+Install the package and attach HOLO-Codex to a target repository:
 
-## Compatibility Names
+```bash
+npm install --global holo-codex
+agent-loop --repo /path/to/repo init
+agent-loop install-hooks --repo /path/to/repo
+agent-loop --repo /path/to/repo dashboard
+```
+
+Open the printed loopback URL. The dashboard unlocks locally without putting a token in the URL.
 
-HOLO-Codex is the public product name. Some stable runtime identifiers intentionally keep their legacy names for compatibility:
+Plugin enablement is separate from the CLI install:
 
-- CLI command: `agent-loop`
-- Runtime state directory: `.agent-loop/`
-- Plugin id and MCP server id: `autonomous-pr-loop`
-- Source directory: `plugins/autonomous-pr-loop/`
-- npm package name: `holo-codex`
-- Local marketplace entry name: `codex-auto-pr-loop`
+```bash
+codex plugin marketplace add "$(npm root -g)/holo-codex"
+```
 
-Do not treat those names as a second product. They are compatibility identifiers.
+Then enable the `autonomous-pr-loop` plugin in Codex. The CLI is called `agent-loop` for compatibility.
 
-## First Workflow: PR Delivery
+## Why HOLO-Codex?
+
+| Problem | What HOLO-Codex adds |
+| --- | --- |
+| Long Codex tasks disappear into a thread. | A workflow board shows the current stage, state source, evidence, and next action. |
+| Manual decisions, review reports, and CI signals live in different places. | Evidence is recorded as append-only workflow events and surfaced in the dashboard. |
+| Recovery gets hard after a pause, gate, failed worker, or context switch. | Gates, recovery actions, timeline, artifacts, and hook diagnostics stay tied to the run. |
+
+## What It Gives You
+
+- Workflow Board for long Codex workflows, including stage status, evidence counts, and current-stage details.
+- Evidence Trail for plans, implementation notes, tests, reviews, PR actions, CI checks, merge readiness, and cleanup.
+- Gates and Recovery for policy blocks, human approval, stale runs, and historical gate re-evaluation.
+- Hook-based Observability that routes Codex hook events by repo, worktree, and session context.
+- Local Dashboard for Mission Control, observability, gates, review/CI state, workers, artifacts, notifications, policy config, and theme modes.
+- CLI and stdio MCP control plane for scripts, skills, and Codex plugin actions.
+- Review and CI visibility through structured review evidence, severity summaries, PR comment links, and merge readiness checks.
+
+HOLO-Codex is local-first. It is not a hosted service, and it does not run cloud workers or GitHub webhooks for you.
 
-PR delivery is the first complete workflow shipped with HOLO-Codex. It is the strongest sample of the loop model, not the product boundary.
+## How It Fits Together
 
-Typical flow:
+```mermaid
+flowchart LR
+  A["Codex skill or commander"] --> B["agent-loop CLI / MCP"]
+  B --> C["Local workflow state<br/>.agent-loop SQLite"]
+  B --> D["Codex hooks<br/>repo / worktree / session routing"]
+  C --> E["Dashboard workflow board"]
+  D --> E
+  E --> F["Gates and recovery"]
+  E --> G["Review, CI, PR, cleanup evidence"]
+```
+
+The dashboard and MCP tools read persisted loop state. They do not depend on the chat transcript being intact.
+
+## First Workflow: PR Delivery
+
+PR delivery is the first bundled workflow. It is the strongest sample today, not the product boundary.
 
 ```text
-sync main
-bind work item
-plan
-build
-verify
-open PR
-run review / CI
-fix findings
-check merge readiness
-merge
-cleanup
+Work Item -> Plan -> Build -> Verify -> PR -> Review -> Merge Readiness -> Cleanup
 ```
 
-The dashboard and MCP tools read persisted loop state. They do not rely on chat history.
+The bundled PR workflow can bind a GitHub issue, track implementation evidence, collect tester and reviewer reports, show PR and CI readiness, and keep cleanup visible after merge.
+
+The same control-plane model can support other long-running Codex workflows:
+
+- release preparation
+- repo hygiene
+- security review
+- docs publishing
+- migrations
+- evaluations
+- customer issue triage
+
+## Compatibility Names
+
+HOLO-Codex is the public product name. Some runtime identifiers keep older names so existing installs and local state do not break:
 
-The same control-plane model can support other long-running Codex workflows such as release preparation, repo hygiene, security review, docs publishing, migrations, evaluations, and customer-issue triage.
+| Public concept | Stable identifier |
+| --- | --- |
+| CLI command | `agent-loop` |
+| Runtime state directory | `.agent-loop/` |
+| Plugin id and MCP server id | `autonomous-pr-loop` |
+| Source directory | `plugins/autonomous-pr-loop/` |
+| npm package | `holo-codex` |
+| Local marketplace entry | `codex-auto-pr-loop` |
 
-## Install
+These are compatibility identifiers, not separate products.
+
+## Install Details
 
 Canonical public source:
 
@@ -74,69 +121,56 @@ Requirements:
 - GitHub CLI `gh`
 - Codex CLI / plugin support
 - `pnpm` when installing from source or using rollback-snapshot local install
-- Optional but recommended: GitNexus via `npx gitnexus`
+- Optional: GitNexus via `npx gitnexus`
 
 Install from npm:
 
 ```bash
 npm install --global holo-codex
-# Replace /path/to/repo with the repository you want HOLO-Codex to supervise.
 agent-loop --repo /path/to/repo init
 agent-loop install-hooks --repo /path/to/repo
 agent-loop --repo /path/to/repo doctor
 ```
 
-The npm package installs the `agent-loop` CLI. `agent-loop install-hooks` installs or refreshes the hook router and target binding without reinstalling the global CLI. To remove an npm install, run `agent-loop hooks unbind --repo /path/to/repo`, remove HOLO-Codex router entries from `~/.codex/hooks.json` only when no target repositories still use them, and then run `npm uninstall --global holo-codex`.
+The npm package installs the `agent-loop` CLI. `agent-loop install-hooks` installs or refreshes the hook router and target binding without reinstalling the global CLI.
+
+To remove an npm install:
+
+```bash
+agent-loop hooks unbind --repo /path/to/repo
+npm uninstall --global holo-codex
+```
+
+Remove HOLO-Codex router entries from `~/.codex/hooks.json` only when no target repositories still use them.
 
-Install from source when developing HOLO-Codex or when you want to inspect the source checkout directly:
+Install from source when developing HOLO-Codex or when you want to inspect the checkout:
 
 ```bash
 git clone https://github.com/tizerluo/HOLO-Codex.git
 cd HOLO-Codex
 pnpm install
 pnpm build:hooks
-# Replace /path/to/repo with the repository you want HOLO-Codex to supervise.
 pnpm agent-loop local install --repo /path/to/repo
 agent-loop --repo /path/to/repo status
 ```
 
-`pnpm agent-loop ...` is the source checkout command. `agent-loop ...` is the global convenience command for day-to-day use from any directory after npm or local source install. Use `agent-loop local snapshots prune --keep 10` to preview old snapshot cleanup, and add `--apply` only when you want to delete valid old snapshots.
+`pnpm agent-loop ...` runs from the source checkout. `agent-loop ...` is the global command after npm or local source install.
 
-For a complete local install, upgrade, reinstall, uninstall, and smoke-test checklist, see [Local Release Readiness](./docs/local-release-readiness.md).
+For the full install, upgrade, reinstall, uninstall, rollback, and smoke-test checklist, see [Local Release Readiness](./docs/local-release-readiness.md).
 
-Add HOLO-Codex to the local Codex plugin marketplace. For npm installs:
+## Initialize A Repo
 
-```bash
-codex plugin marketplace add "$(npm root -g)/holo-codex"
-```
-
-For source installs:
-
-```bash
-codex plugin marketplace add /path/to/HOLO-Codex
-```
-
-Then enable the `autonomous-pr-loop` plugin in Codex. Plugin enablement and global CLI installation are separate steps.
-
-## Initialize State
-
-Run from the target repository root:
+Run from the target repository root or pass `--repo`:
 
 ```bash
 agent-loop --repo /path/to/repo init
 agent-loop --repo /path/to/repo doctor
-agent-loop --repo /path/to/repo status
-```
-
-Install Codex hooks:
-
-```bash
 agent-loop install-hooks --repo /path/to/repo
 ```
 
-This installs one stable hook router into `~/.codex/hooks.json`, preserves existing user hooks, and records the target repository binding under `~/.codex/agent-loop/hook-bindings.json`.
+Hook installation writes one router into `~/.codex/hooks.json`, preserves existing hooks, and records target repository bindings under `~/.codex/agent-loop/hook-bindings.json`.
 
-Multi-repo note: multiple repositories can share the same `CODEX_HOME`; hook events are routed by Codex cwd/worktree/session context before any repo state is written or policy is applied. A separate `CODEX_HOME` remains useful for high-isolation sandbox testing.
+Multiple repositories can share the same `CODEX_HOME`. Hook events are routed by Codex cwd, worktree, and session context before any repository state is written or policy is applied. A separate `CODEX_HOME` is still useful for high-isolation sandbox testing.
 
 Runtime files are written to `.agent-loop/` and must not be committed.
 
@@ -146,7 +180,7 @@ Runtime files are written to `.agent-loop/` and must not be committed.
 agent-loop --repo /path/to/repo dashboard
 ```
 
-The command prints a loopback URL on stdout and a fallback session token on stderr:
+The command prints a loopback URL:
 
 ```text
 dashboard started
@@ -154,9 +188,9 @@ url: http://127.0.0.1:<port>/
 targetRepoRoot: /path/to/repo
 ```
 
-Dashboard mutations require the local session token and go through the shared controller. The UI does not write SQLite directly. Loopback dashboard sessions unlock through a same-origin session bootstrap; the stderr token is only a fallback for static UI or recovery. Do not copy it into docs, logs, PR bodies, commits, artifacts, or screenshots.
+Dashboard mutations require the local session token and go through the shared controller. The UI does not write SQLite directly. Loopback dashboard sessions unlock through a same-origin bootstrap; the stderr token is only a fallback for static UI or recovery. Do not copy it into docs, logs, PR bodies, commits, artifacts, or screenshots.
 
-Dashboard-visible delivery work is produced by persisted `agent-loop` actions and workflow evidence. Direct terminal edits or commander decisions are not automatically visible unless they are recorded through agent-loop events, artifacts, or PR comments. For the current self-maintenance flow, see [Self-bootstrap workflow](./docs/self-bootstrap.md). For an end-to-end audit template, see [Agent-loop-first Delivery Audit Checklist](./docs/checklists/agent-loop-first-delivery-audit.md).
+Dashboard-visible delivery work comes from persisted `agent-loop` actions and workflow evidence. Direct terminal edits or commander decisions become visible only when they are recorded as agent-loop events, artifacts, or PR comments.
 
 ## Common CLI
 
@@ -182,7 +216,7 @@ Human-readable CLI output supports `--locale zh-CN|en-US|system`. JSON output re
 
 ## Workflow Profiles And Themes
 
-The default workflow remains `pr-loop` with `default_pr_loop` and `default_pr_roles`. Policy Config can also select `generic-loop` with built-in profiles for research reports, document preparation, repo hygiene, weekly review, and data extraction workflows. For a concrete non-PR workflow, see the [generic-loop repo hygiene example](./docs/examples/generic-loop-repo-hygiene.md).
+The default workflow is `pr-loop` with `default_pr_loop` and `default_pr_roles`. Policy Config can also select `generic-loop` with built-in profiles for research reports, document preparation, repo hygiene, weekly review, and data extraction workflows. For a concrete non-PR workflow, see the [generic-loop repo hygiene example](./docs/examples/generic-loop-repo-hygiene.md).
 
 Dashboard theme is a local browser preference. It supports `light`, `dark`, and `system`, and does not write to repo config or SQLite.
 
@@ -192,9 +226,41 @@ Dashboard theme is a local browser preference. It supports `light`, `dark`, and
 - The supervisor owns Git and GitHub lifecycle actions.
 - Destructive Git/GitHub commands are blocked by command policy and hooks.
 - Merge readiness depends on config, review/CI evidence, open review comments, scope guard, and policy decisions.
-- Never store secrets in code, docs, logs, artifacts, commits, or PR bodies.
+- HOLO-Codex must not store secrets, raw prompts, raw transcripts, dashboard tokens, or raw hook payloads in docs, logs, artifacts, commits, or PR bodies.
 - Hooks cover the Codex tool loop, not manual commands run in an external terminal.
 
+See [Trust and Safety](./docs/trust-and-safety.md) and [Security](./SECURITY.md).
+
+## FAQ
+
+### Is HOLO-Codex hosted?
+
+No. HOLO-Codex runs locally. The dashboard, SQLite state, hooks, and CLI live on your machine.
+
+### Does it replace Codex?
+
+No. Codex still does the work. HOLO-Codex gives long Codex workflows state, evidence, gates, recovery, and a dashboard.
+
+### Why is the CLI still called `agent-loop`?
+
+`agent-loop` is the stable runtime command. Keeping it avoids breaking existing installs, scripts, hooks, and local state.
+
+### Why is the plugin id still `autonomous-pr-loop`?
+
+That id is part of the existing plugin and MCP wiring. HOLO-Codex is the public product name; `autonomous-pr-loop` is a compatibility identifier.
+
+### Does it auto-merge PRs?
+
+No. HOLO-Codex can track merge readiness and evidence, but the supervisor controls Git and GitHub lifecycle actions.
+
+### Does it require GitHub?
+
+The bundled PR delivery workflow expects GitHub and `gh`. The underlying loop model can support non-PR workflows through `generic-loop`.
+
+### Where is state stored?
+
+Repository runtime state lives under `.agent-loop/`. Hook routing bindings live under `~/.codex/agent-loop/`. Runtime files should not be committed.
+
 ## Development
 
 ```bash

package/README.zh-CN.md

@@ -4,62 +4,109 @@
 
 ![HOLO-Codex README hero](./assets/brand/holo-codex-readme-hero.png)
 
-HOLO-Codex 是 **Human On Loop Codex** 的缩写，它把长流程 Codex workflow 变成可观察、可恢复、可人工接管的 loop。人设定目标和边界、观察进展，并只在真实 gate 需要关注时回到环上。
+[![npm version](https://img.shields.io/npm/v/holo-codex?color=0f766e)](https://www.npmjs.com/package/holo-codex)
+[![npm downloads](https://img.shields.io/npm/dm/holo-codex)](https://www.npmjs.com/package/holo-codex)
+[![GitHub release](https://img.shields.io/github/v/release/tizerluo/HOLO-Codex)](https://github.com/tizerluo/HOLO-Codex/releases)
+[![CI](https://github.com/tizerluo/HOLO-Codex/actions/workflows/ci.yml/badge.svg)](https://github.com/tizerluo/HOLO-Codex/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
+![Node >=22.5](https://img.shields.io/badge/node-%3E%3D22.5-339933)
 
-Supervisor 负责持久化 workflow 状态、evidence、gates、worker 编排、Codex hooks、MCP control plane 和本地 dashboard。Worker 只做受控任务并返回结构化输出。
+HOLO-Codex 是 **Human On Loop Codex** 的缩写。它把长流程 Codex workflow 变成可观察、可恢复、可人工接管的系统，让你不用一直守在聊天记录里猜它做到了哪一步。
 
-## 提供能力
+Codex 负责计划、改代码、测试、review 和调用子代理。HOLO-Codex 负责把这些工作落到本地 control plane 上：workflow 状态、evidence、gates、hooks、review 状态、恢复动作，以及一个可以边跑边看的 dashboard。
 
-- `plugins/autonomous-pr-loop/` 下的 Codex 插件。
-- `agent-loop` CLI：管理本地 loop 状态、hooks、dashboard、workflow evidence 和可回滚本地安装。
-- `.agent-loop/` 下的本地 SQLite 状态。
-- 本地 dashboard：Mission Control、workflow board、Observability Console、Gate、Review/CI、Worker、Artifact、Notifications、Recovery、Policy Config、主题模式。
-- stdio MCP control plane。
-- 用于 policy 检查和 observability 的 Codex hooks。
-- TypeScript + Vitest 测试套件。
-- `zh-CN`、`en-US`、`system` 双语显示支持。
-- workflow profile、role profile、`generic-loop`，以及第一个内置 workflow：`pr-loop`。
+## 快速开始
 
-这不是托管服务，不提供 GitHub webhook daemon 或云端 worker。
+安装 npm package，并把 HOLO-Codex 接到一个目标仓库：
 
-## 兼容名称
+```bash
+npm install --global holo-codex
+agent-loop --repo /path/to/repo init
+agent-loop install-hooks --repo /path/to/repo
+agent-loop --repo /path/to/repo dashboard
+```
 
-HOLO-Codex 是公开产品名。一些稳定运行时标识会继续保留旧名称，以避免破坏已有安装和本地状态：
+打开命令打印出来的本地 URL。Dashboard 会在本机自动解锁，不会把 token 放进 URL。
 
-- CLI 命令：`agent-loop`
-- 运行态目录：`.agent-loop/`
-- Plugin id 和 MCP server id：`autonomous-pr-loop`
-- 源码目录：`plugins/autonomous-pr-loop/`
-- npm package 名：`holo-codex`
-- 本地 marketplace 条目名：`codex-auto-pr-loop`
+Codex plugin 启用和 CLI 安装是两件事：
 
-这些是兼容标识，不是第二个产品名。
+```bash
+codex plugin marketplace add "$(npm root -g)/holo-codex"
+```
 
-## 第一个工作流：PR 交付
+然后在 Codex 里启用 `autonomous-pr-loop` 插件。CLI 继续叫 `agent-loop`，这是兼容已有安装和本地状态的名字。
+
+## 为什么需要 HOLO-Codex
 
-PR 交付是 HOLO-Codex 随附的第一个完整 workflow，也是 loop 模型最强的样板，但不是产品边界。
+| 问题 | HOLO-Codex 补上的东西 |
+| --- | --- |
+| 长流程 Codex 任务容易消失在一个聊天线程里。 | Workflow board 会显示当前阶段、状态来源、证据和下一步。 |
+| 人工决策、review report、CI 信号分散在不同地方。 | Evidence 会作为 append-only workflow event 记录下来，并显示在 dashboard。 |
+| 一旦暂停、遇到 gate、worker 失败或切上下文，恢复成本很高。 | Gate、recovery、timeline、artifact 和 hook 诊断都会绑定到同一个 run。 |
 
-典型流程：
+## 它提供什么
+
+- Workflow Board：展示长流程 Codex workflow 的阶段状态、证据数量和当前阶段详情。
+- Evidence Trail：记录计划、实现、测试、review、PR、CI、merge readiness 和 cleanup。
+- Gates and Recovery：处理 policy block、人工批准、stale run 和历史 gate re-evaluate。
+- Hook-based Observability：按 repo、worktree、session context 路由 Codex hook events。
+- Local Dashboard：包含 Mission Control、Observability Console、Gate、Review/CI、Worker、Artifact、Notifications、Recovery、Policy Config 和主题模式。
+- CLI 和 stdio MCP control plane：供脚本、skills 和 Codex plugin 调用。
+- Review and CI visibility：通过结构化 review evidence、severity summary、PR comment link 和 merge readiness 追踪交付状态。
+
+HOLO-Codex 是 local-first 工具。它不是托管服务，也不会替你运行云端 worker 或 GitHub webhook daemon。
+
+## 它如何工作
+
+```mermaid
+flowchart LR
+  A["Codex skill or commander"] --> B["agent-loop CLI / MCP"]
+  B --> C["Local workflow state<br/>.agent-loop SQLite"]
+  B --> D["Codex hooks<br/>repo / worktree / session routing"]
+  C --> E["Dashboard workflow board"]
+  D --> E
+  E --> F["Gates and recovery"]
+  E --> G["Review, CI, PR, cleanup evidence"]
+```
+
+Dashboard 和 MCP tools 读取持久化 loop 状态，不依赖聊天记录还在不在。
+
+## 第一个工作流：PR 交付
+
+PR 交付是 HOLO-Codex 随附的第一个完整 workflow，也是目前最完整的样板，但它不是产品边界。
 
 ```text
-sync main
-bind work item
-plan
-build
-verify
-open PR
-run review / CI
-fix findings
-check merge readiness
-merge
-cleanup
+Work Item -> Plan -> Build -> Verify -> PR -> Review -> Merge Readiness -> Cleanup
 ```
 
-Dashboard 和 MCP tools 读取持久化 loop 状态，不依赖聊天历史。
+内置 PR workflow 可以绑定 GitHub issue、追踪实现证据、收集 tester 和 reviewer report、显示 PR/CI readiness，并在 merge 后继续保留 cleanup 状态。
+
+同一套 control plane 以后也可以承载其他长流程 Codex workflow：
+
+- release 准备
+- repo hygiene
+- security review
+- docs publishing
+- migration
+- evaluation
+- customer issue triage
+
+## 兼容名称
+
+HOLO-Codex 是公开产品名。一些运行时标识会继续保留旧名称，避免破坏已有安装、脚本、hooks 和本地状态：
 
-同一套 control plane 也可以承载其他长流程 Codex workflow，例如 release 准备、仓库卫生审计、安全审查、文档发布、迁移、评测和客户 issue 分诊。
+| 公开概念 | 稳定标识 |
+| --- | --- |
+| CLI 命令 | `agent-loop` |
+| 运行态目录 | `.agent-loop/` |
+| Plugin id 和 MCP server id | `autonomous-pr-loop` |
+| 源码目录 | `plugins/autonomous-pr-loop/` |
+| npm package | `holo-codex` |
+| 本地 marketplace 条目 | `codex-auto-pr-loop` |
+
+这些是兼容标识，不是第二个产品名。
 
-## 安装
+## 安装细节
 
 公开源码入口：
 
@@ -74,19 +121,27 @@ https://github.com/tizerluo/HOLO-Codex
 - GitHub CLI `gh`
 - Codex CLI / plugin support
 - 从源码安装或使用 snapshot/rollback local install 时需要 `pnpm`
-- 可选但推荐：GitNexus，使用 `npx gitnexus`
+- 可选：GitNexus，使用 `npx gitnexus`
 
 从 npm 安装：
 
 ```bash
 npm install --global holo-codex
-# 将 /path/to/repo 替换成你要让 HOLO-Codex 监督的目标仓库。
 agent-loop --repo /path/to/repo init
 agent-loop install-hooks --repo /path/to/repo
 agent-loop --repo /path/to/repo doctor
 ```
 
-npm package 会安装 `agent-loop` CLI。`agent-loop install-hooks` 会安装或刷新 hook router 和目标仓库绑定，不会重新安装全局 CLI。移除 npm 安装时，先运行 `agent-loop hooks unbind --repo /path/to/repo`；确认没有任何目标仓库还在使用 HOLO-Codex router 后，再从 `~/.codex/hooks.json` 手动移除 HOLO-Codex router entries，最后运行 `npm uninstall --global holo-codex`。
+npm package 会安装 `agent-loop` CLI。`agent-loop install-hooks` 会安装或刷新 hook router 和目标仓库绑定，不会重新安装全局 CLI。
+
+移除 npm 安装：
+
+```bash
+agent-loop hooks unbind --repo /path/to/repo
+npm uninstall --global holo-codex
+```
+
+只有确认没有任何目标仓库还在使用 HOLO-Codex router 后，才从 `~/.codex/hooks.json` 移除 HOLO-Codex router entries。
 
 开发 HOLO-Codex 或需要直接检查源码 checkout 时，从源码安装：
 
@@ -95,48 +150,27 @@ git clone https://github.com/tizerluo/HOLO-Codex.git
 cd HOLO-Codex
 pnpm install
 pnpm build:hooks
-# 将 /path/to/repo 替换成你要让 HOLO-Codex 监督的目标仓库。
 pnpm agent-loop local install --repo /path/to/repo
 agent-loop --repo /path/to/repo status
 ```
 
-`pnpm agent-loop ...` 是源码 checkout 内的命令。`agent-loop ...` 是 npm 或本地源码安装后从任意目录日常使用的全局命令。用 `agent-loop local snapshots prune --keep 10` 预览旧 snapshot 清理；确认要删除时再加 `--apply`。
-
-完整的本地安装、升级、重装、卸载和 smoke test 清单见：[Local Release Readiness](./docs/local-release-readiness.md)。
-
-把 HOLO-Codex 加入本地 Codex plugin marketplace。npm 安装时：
-
-```bash
-codex plugin marketplace add "$(npm root -g)/holo-codex"
-```
-
-源码安装时：
+`pnpm agent-loop ...` 是源码 checkout 内的命令。`agent-loop ...` 是 npm 或本地源码安装后从任意目录使用的全局命令。
 
-```bash
-codex plugin marketplace add /path/to/HOLO-Codex
-```
+完整的安装、升级、重装、卸载、rollback 和 smoke test 清单见：[Local Release Readiness](./docs/local-release-readiness.md)。
 
-然后在 Codex 中启用 `autonomous-pr-loop` 插件。Codex plugin 启用和全局 CLI 安装是两件事。
+## 初始化一个仓库
 
-## 初始化状态
-
-在目标仓库根目录执行：
+在目标仓库根目录执行，或显式传 `--repo`：
 
 ```bash
 agent-loop --repo /path/to/repo init
 agent-loop --repo /path/to/repo doctor
-agent-loop --repo /path/to/repo status
-```
-
-安装 Codex hooks：
-
-```bash
 agent-loop install-hooks --repo /path/to/repo
 ```
 
-这会向 `~/.codex/hooks.json` 安装一组稳定 hook router，保留已有用户 hooks，并在 `~/.codex/agent-loop/hook-bindings.json` 记录目标仓库绑定。
+Hook 安装会向 `~/.codex/hooks.json` 写入一组 router，保留已有 hooks，并在 `~/.codex/agent-loop/hook-bindings.json` 记录目标仓库绑定。
 
-多仓库注意：多个仓库可以共用同一个 `CODEX_HOME`；hook event 会先按 Codex cwd/worktree/session context 路由，再写入仓库状态或执行 policy。独立 `CODEX_HOME` 仍适合高隔离 sandbox 测试。
+多个仓库可以共用同一个 `CODEX_HOME`。Hook event 会先按 Codex cwd、worktree 和 session context 路由，再写入仓库状态或执行 policy。独立 `CODEX_HOME` 仍适合高隔离 sandbox 测试。
 
 运行态文件写入 `.agent-loop/`，不要提交。
 
@@ -146,7 +180,7 @@ agent-loop install-hooks --repo /path/to/repo
 agent-loop --repo /path/to/repo dashboard
 ```
 
-命令会在 stdout 打印 loopback URL，并在 stderr 单独打印 fallback session token：
+命令会打印一个本地 URL：
 
 ```text
 dashboard 已启动
@@ -154,9 +188,9 @@ url: http://127.0.0.1:<port>/
 targetRepoRoot: /path/to/repo
 ```
 
-Dashboard mutation 必须带本地 session token，并统一走 controller。UI 不直接写 SQLite。本地 loopback dashboard 会用同源 session bootstrap 自动解锁。stderr token 只作为静态 UI 或恢复场景的 fallback；不要把它复制到 docs、日志、PR body、commit、artifact 或截图里。
+Dashboard mutation 必须带本地 session token，并统一走 controller。UI 不直接写 SQLite。本地 loopback dashboard 会用同源 bootstrap 自动解锁。stderr token 只作为静态 UI 或恢复场景的 fallback，不要把它复制到 docs、日志、PR body、commit、artifact 或截图里。
 
-Dashboard 能看到的交付工作来自持久化的 `agent-loop` 动作和 workflow evidence。直接在终端改文件或 commander 决策不会自动出现在 dashboard，除非它们被记录成 agent-loop event、artifact 或 PR comment。当前自维护流程见：[自举维护流程](./docs/self-bootstrap.md)。端到端审计模板见：[Agent-loop-first Delivery Audit Checklist](./docs/checklists/agent-loop-first-delivery-audit.md)。
+Dashboard 能看到的交付工作来自持久化的 `agent-loop` 动作和 workflow evidence。直接在终端改文件或 commander 决策不会自动出现在 dashboard，除非它们被记录成 agent-loop event、artifact 或 PR comment。
 
 ## 常用 CLI
 
@@ -182,9 +216,9 @@ agent-loop --repo /path/to/repo dashboard
 
 ## Workflow Profiles 和主题
 
-默认 workflow 仍是 `pr-loop`，使用 `default_pr_loop` 和 `default_pr_roles`。Policy Config 也可以选择 `generic-loop`，并使用内置的调研报告、文档准备、仓库卫生审计、周报、数据抽取 workflow profiles。具体非 PR 工作流可参考：[generic-loop 仓库卫生审计示例](./docs/examples/generic-loop-repo-hygiene.md)。
+默认 workflow 是 `pr-loop`，使用 `default_pr_loop` 和 `default_pr_roles`。Policy Config 也可以选择 `generic-loop`，并使用内置的调研报告、文档准备、仓库卫生审计、周报、数据抽取 workflow profiles。具体非 PR 工作流可参考：[generic-loop 仓库卫生审计示例](./docs/examples/generic-loop-repo-hygiene.md)。
 
-Dashboard 主题是浏览器本地显示偏好，支持 `light`、`dark`、`system`，不会写入 repo config 或 SQLite。
+Dashboard 主题是浏览器本地显示偏好，支持 `light`、`dark` 和 `system`，不会写入 repo config 或 SQLite。
 
 ## 安全边界
 
@@ -192,9 +226,41 @@ Dashboard 主题是浏览器本地显示偏好，支持 `light`、`dark`、`syst
 - Supervisor 负责 Git 和 GitHub 生命周期。
 - 破坏性 Git/GitHub 命令由 command policy 和 hooks 阻止。
 - Merge readiness 由 config、review/CI evidence、open review comments、scope guard 和 policy decisions 共同决定。
-- 不要把密钥写入代码、文档、日志、artifacts、commit 或 PR body。
+- HOLO-Codex 不应该把 secrets、raw prompts、raw transcripts、dashboard tokens 或 raw hook payloads 写入 docs、日志、artifacts、commit 或 PR body。
 - Hooks 只覆盖 Codex tool loop，不拦截外部 Terminal 手动命令。
 
+更多细节见：[信任与安全](./docs/trust-and-safety.md) 和 [安全政策](./SECURITY.md)。
+
+## FAQ
+
+### HOLO-Codex 是托管服务吗？
+
+不是。HOLO-Codex 在本机运行。Dashboard、SQLite 状态、hooks 和 CLI 都在你的机器上。
+
+### 它会替代 Codex 吗？
+
+不会。Codex 还是负责做事。HOLO-Codex 给长流程 Codex 工作补上状态、证据、gate、恢复动作和 dashboard。
+
+### 为什么 CLI 还叫 `agent-loop`？
+
+`agent-loop` 是稳定运行时命令。保留这个名字可以避免破坏已有安装、脚本、hooks 和本地状态。
+
+### 为什么 plugin id 还是 `autonomous-pr-loop`？
+
+这个 id 已经接入现有 plugin 和 MCP wiring。HOLO-Codex 是公开产品名，`autonomous-pr-loop` 是兼容标识。
+
+### 它会自动 merge PR 吗？
+
+不会。HOLO-Codex 可以追踪 merge readiness 和 evidence，但 Git 和 GitHub 生命周期动作仍由 supervisor 控制。
+
+### 它必须依赖 GitHub 吗？
+
+内置 PR delivery workflow 需要 GitHub 和 `gh`。底层 loop 模型可以通过 `generic-loop` 承载非 PR workflow。
+
+### 状态存在哪里？
+
+仓库运行态状态在 `.agent-loop/` 下。Hook routing bindings 在 `~/.codex/agent-loop/` 下。运行态文件不要提交。
+
 ## 开发
 
 ```bash