feat: make Codex bootstrap releases self-documenting

Author: codex

.github/workflows/codex-bootstrap-release.yml

@@ -406,6 +406,7 @@ jobs:
               raise SystemExit("invalid release tag")
           provenance_name = f"drclaw-{tag}.provenance.json"
           expected = {
+              "README.md",
               "SHA256SUMS",
               "install.sh",
               "remote-install.sh",
@@ -486,5 +487,5 @@ jobs:
             --repo "${GITHUB_REPOSITORY}" \
             --verify-tag \
             --title "Dr. Claw Codex bootstrap ${RELEASE_TAG}" \
-            --generate-notes \
+            --notes-file release-artifacts/README.md \
             release-artifacts/*

CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## Codex bootstrap v0.2.9 - 2026-08-25
+
+Release tag: `codex-bootstrap-v0.2.9`
+
+### Highlights
+- Added a checksum-covered bilingual `README.md` to every offline release kit and GitHub Release.
+- Replaced generic auto-generated GitHub notes with release-specific, fully pinned online installation, offline verification, activation, and security instructions.
+- Added visible English and Chinese root README entry points plus a complete English Codex server deployment guide.
+- Strengthened the documented online identity contract by pinning the annotated tag object as well as the raw-script commit and peeled commit.
+
+### Validation
+- The release workflow requires x64, native ARM64, Python 3.9–3.13, Codex contract, Web, release-kit, checksum, live tag, and publish gates before creating the Release.
+- The offline wrapper rejects any missing, extra, symlinked, untrusted-mode, or checksum-mismatched asset, including its release README.
+
 ## Dr. Claw v1.1.1 - 2026-03-30
 
 ### Highlights

README.md

@@ -44,6 +44,7 @@
 - [Overview](#overview)
 - [What's New](#whats-new)
 - [Highlights](#highlights)
+- [One-command Codex Server Deployment](#one-command-codex-server-deployment)
 - [Quick Start](#quick-start)
 - [Configuration](#configuration)
 - [OpenClaw Integration](#openclaw-integration)
@@ -181,6 +182,14 @@ Dr. Claw is a general-purpose AI research assistant designed to help researchers
 </details>
 
 
+## One-command Codex Server Deployment
+
+To reproduce the Dr. Claw Codex setup on a new Linux `x86_64` or `aarch64` server, use the immutable [`codex-bootstrap-v0.2.9` release](https://github.com/OpenLAIR/dr-claw/releases/tag/codex-bootstrap-v0.2.9). The Release page contains the exact one-command installer pinned to its full commit and annotated tag object, plus an offline bundle and `SHA256SUMS`.
+
+The `--full` path installs the safe Codex profile, global `AGENTS.md`, the on-demand router for the complete 172-skill library, the Dr. Claw control CLI, and the Web application, then runs a strict credential-free doctor. Codex login, connector OAuth, API keys, SSH/Duo state, caches, and existing projects are never copied.
+
+See the [English deployment guide](docs/codex-bootstrap.md) or the [complete Chinese operations guide](bootstrap/codex/README.zh-CN.md) for prerequisites, online/offline installation, Delta behavior, service activation, updates, and rollback.
+
 ## Quick Start
 
 > **Desktop App (Beta):** Want to skip the setup below? Download the latest `.dmg` (macOS) or `.exe` (Windows) installer from [GitHub Releases](https://github.com/OpenLAIR/dr-claw/releases) and run it directly. The desktop app is currently in beta — for a more stable experience, follow the full installation steps below.

README.zh-CN.md

@@ -44,6 +44,7 @@
 - [Overview](#overview)
 - [最新动态](#最新动态)
 - [亮点](#亮点)
+- [Codex 服务器一键部署](#codex-服务器一键部署)
 - [快速开始](#快速开始)
 - [配置说明](#配置说明)
 - [接入 OpenClaw](#接入-openclaw)
@@ -182,6 +183,14 @@ Dr. Claw 是一个面向不同研究方向的通用 AI 研究助手，帮助研
 </details>
 
 
+## Codex 服务器一键部署
+
+若要在新的 Linux `x86_64` 或 `aarch64` 服务器上完整复现 Dr. Claw Codex 环境，请使用不可变的 [`codex-bootstrap-v0.2.9` Release](https://github.com/OpenLAIR/dr-claw/releases/tag/codex-bootstrap-v0.2.9)。Release 页面会直接给出同时固定完整 commit 与 annotated tag object 的一键命令，并提供离线 bundle 与 `SHA256SUMS`。
+
+`--full` 会安装 safe Codex profile、全局 `AGENTS.md`、按需路由完整 172 个 skill 的 router、Dr. Claw 控制 CLI 与 Web 应用，并执行严格的无凭据 doctor。Codex 登录态、connector OAuth、API key、SSH/Duo、缓存和已有项目永远不会被迁移。
+
+完整前置条件、在线/离线安装、Delta 行为、服务启动、升级与回滚见 [Codex 部署操作手册](bootstrap/codex/README.zh-CN.md)；英文版见 [One-command Codex server deployment](docs/codex-bootstrap.md)。
+
 ## 快速开始
 
 > **桌面应用（Beta）：** 想跳过以下安装步骤？可以直接从 [GitHub Releases](https://github.com/OpenLAIR/dr-claw/releases) 下载最新的 `.dmg`（macOS）或 `.exe`（Windows）安装包运行。桌面应用目前为 Beta 版本 — 如需更稳定的体验，请按照下方完整安装步骤操作。

bootstrap/codex/README.zh-CN.md

@@ -69,7 +69,7 @@
 
 必须以最终实际运行 Codex 的非 root Unix 用户执行本方案；管理员应先 `sudo -iu <USER>`，再 clone 和安装。`--home` 只用于同一用户的隔离测试，不是跨用户 provision 开关；安装器会拒绝 root、owner 不匹配、受保护系统目录后代和隐式符号链接写穿。`$CODEX_HOME` 必须是 `$HOME` 内的专用目录；新建权限为 `0700`，已有目录及其自 HOME 起的现存祖先不得由其他主体替换或写入。唯一例外是上一表所述、经过 POSIX ACL 完整验证的 root-owned Delta HOME；例外不会向 HOME 以下受管目录传播。
 
-生产部署必须由维护者批准一个 immutable Git tag 或完整 commit SHA。当前 manifest 固定到 `codex-bootstrap-v0.2.8`；`audited_base_commit` 只是编写本方案时检查的起始树，不是可部署 revision。实际安装还必须把该 annotated tag 与 release provenance 中的完整 commit SHA 绑定；不要部署 moving branch，也不要移动既有 tag。
+生产部署必须由维护者批准一个 immutable annotated Git tag。当前 manifest 固定到 `codex-bootstrap-v0.2.9`；`audited_base_commit` 只是编写本方案时检查的起始树，不是可部署 revision。实际安装必须同时固定 release provenance 中的 tag object SHA 与 peeled commit SHA；不要部署 moving branch，也不要移动既有 tag。
 
 ## 四、NCSA Delta：先建立交互连接
 
@@ -119,13 +119,13 @@ scontrol show config | grep -Ei 'ClusterName|SlurmctldHost|SlurmVersion'
 
 ### 0. 推荐：GitHub 固定 release 的一命令入口
 
-发布者先把 `manifest.json` 的 `bundle_release_ref` 设置为 release tag，并记录该 tag 对应的完整 commit SHA。`codex-bootstrap-release.yml` 会在只读 job 完成 Python、Node、真实 Codex 和隔离 Web 验收，再调用同一 release-kit builder 生成 tar、Git bundle、离线入口、checksums 和 provenance；单独的写权限 job 只发布这些已验证文件。仓库还应给 `codex-bootstrap-v*` 配置 protected tag rule，并把 `codex-bootstrap-release` environment 设为需维护者批准。目标服务器以最终运行 Codex 的**非 root 用户**执行下面一条命令；raw 脚本 URL 固定到 commit，tag 再由 `--expected-commit` 绑定到同一个 commit，所以 tag 被移动时安装会失败：
+发布者先把 `manifest.json` 的 `bundle_release_ref` 设置为 release tag，并记录该 tag 对应的 tag object 与完整 commit SHA。`codex-bootstrap-release.yml` 会在只读 job 完成 Python、Node、真实 Codex 和隔离 Web 验收，再调用同一 release-kit builder 生成 tar、Git bundle、带双语 README 的离线入口、checksums 和 provenance；单独的写权限 job 只发布这些已验证文件，并直接使用受 checksum 保护的 README 作为 GitHub Release 正文。仓库还应给 `codex-bootstrap-v*` 配置 protected tag rule，并把 `codex-bootstrap-release` environment 设为需维护者批准。目标服务器以最终运行 Codex 的**非 root 用户**执行下面一条命令；raw 脚本 URL 固定到 commit，tag object 与 peeled commit 再分别由 `--expected-tag-object` 和 `--expected-commit` 固定，任一发布身份漂移都会失败：
 
 ```bash
-bash -c 'set -Eeuo pipefail; curl -fsSL "https://raw.githubusercontent.com/OpenLAIR/dr-claw/<FULL_COMMIT_SHA>/bootstrap/codex/remote-install.sh" | bash -s -- --ref "<RELEASE_TAG>" --expected-commit "<FULL_COMMIT_SHA>" --full'
+bash -c 'set -Eeuo pipefail; curl -fsSL "https://raw.githubusercontent.com/OpenLAIR/dr-claw/<FULL_COMMIT_SHA>/bootstrap/codex/remote-install.sh" | bash -s -- --ref "<RELEASE_TAG>" --expected-commit "<FULL_COMMIT_SHA>" --expected-tag-object "<ANNOTATED_TAG_OBJECT_SHA>" --full'
 ```
 
-先做零写入预览时，在末尾加 `--dry-run`。若维护者只发布完整 SHA，也可把 raw URL 和 `--ref` 都设为该 SHA，不传 `--expected-commit`。不要在 URL 中嵌入 Git token；私有 fork 使用目标机 credential helper 或 SSH agent，并显式传不含凭据的 `--repo-url`。
+先做零写入预览时，在末尾加 `--dry-run`。若维护者只发布完整 SHA，也可把 raw URL 和 `--ref` 都设为该 SHA，不传 `--expected-commit` 或 `--expected-tag-object`。不要在 URL 中嵌入 Git token；私有 fork 使用目标机 credential helper 或 SSH agent，并显式传不含凭据的 `--repo-url`。
 
 远程入口会：
 
@@ -150,7 +150,7 @@ bash bootstrap/codex/remote-install.sh --help
 在 release tag 所在的 clean checkout 上生成一个新的、不可覆盖的目录：
 
 ```bash
-release_tag=codex-bootstrap-v0.2.8
+release_tag=codex-bootstrap-v0.2.9
 release_commit=$(git rev-parse "${release_tag}^{commit}")
 kit_parent="$PWD/../drclaw-release-output-private"
 (umask 077; mkdir "$kit_parent")
@@ -172,7 +172,7 @@ builder 只接受与 manifest、HEAD 和完整 SHA 一致的 annotated tag；拒
 完整搬运该目录到新服务器后，只需一条离线命令，不必先从 bundle 手动提取脚本：
 
 ```bash
-bash /path/to/drclaw-codex-bootstrap-v0.2.8-offline/install.sh --full
+bash /path/to/drclaw-codex-bootstrap-v0.2.9-offline/install.sh --full
 ```
 
 wrapper 会先拒绝目录中的任何额外 entry、symlink、缺失文件、owner/mode 异常或 checksum inventory 漂移，并验证每个 payload，再把同目录 bundle 交给现有远程安装器；tag object 与 peeled commit 两个身份也同时固定。Git bundle 为了保留发布身份与 commit 原始 SHA 必须携带其可达 Git 历史，因此 builder 会扫描**全部可达历史路径，以及所有可达 blob、commit 和 tag payload**，而不只检查当前 tree；允许的 community gitlink 只记录路径与 object ID，bundle/archive 都不携带其仓库内容。内部 checksum 可证明搬运完整性；抵抗“payload 与 checksum 同时被替换”仍需通过独立可信渠道保存并核对 provenance sidecar 的 SHA256。

bootstrap/codex/STATUS-2026-08-19.zh-CN.md

@@ -2,7 +2,7 @@
 
 初始记录：2026-08-19（America/Chicago）
 最近续作：2026-08-25（America/New_York）
-状态：**v0.2.2 的本地验收和 tag 保持不变。`codex-bootstrap-v0.2.3` 至 `codex-bootstrap-v0.2.7` 均已不可变推送，但都没有发布 Release；当前候选是新的 `codex-bootstrap-v0.2.8`，尚未创建或推送。**
+状态：**`codex-bootstrap-v0.2.8` 已通过 x64、native ARM64、Python 3.9–3.13 与 publish 全部 gate 并发布 GitHub Release；当前候选 `codex-bootstrap-v0.2.9` 用于补齐 checksum 覆盖的双语 Release README、精确一键命令与中英文 GitHub 文档入口。v0.2.2–v0.2.8 的历史 tag 均保持不可变。**
 
 这份文件记录本轮工作的真实边界：已经做了什么、验证到了哪里、哪些方案被拒绝、现在还有哪些问题、恢复时应从哪里继续。第八节以前保留 2026-08-19 的历史暂停证据；本节以下的 2026-08-20 与 2026-08-25 更新优先于其中已经解决的旧问题。它不替代正式使用文档 [`README.zh-CN.md`](README.zh-CN.md) 和应用安装文档 [`APP_INSTALL.zh-CN.md`](APP_INSTALL.zh-CN.md)。
 
@@ -18,6 +18,12 @@
 
 `codex-bootstrap-v0.2.3` 的 GitHub workflow `#32888891747` 已保留为失败证据：所有 validation job 都在 `actions/checkout` 中发现 `community-tools/autoresearch` 的 gitlink 没有 `.gitmodules` URL 而失败，因此没有执行代码测试，publish job 被安全跳过。已从历史提交 `de72da9991bbbf239546152a9ac6e15c56338228` 恢复两个原始、默认不初始化的社区 gitlink 映射，并让 release-kit 在本地要求 `.gitmodules` 路径与 manifest allowlist 精确一致。`codex-bootstrap-v0.2.4` 的 GitHub workflow `#32891263604` 已证明 checkout 与 Python 3.9–3.13 matrix 恢复正常，但 x86_64 与 native ARM64 的 Web smoke 均未完成，publish 安全跳过。`codex-bootstrap-v0.2.5` 的 workflow `#32893368825` 已证明 x86_64 的核心与完整 Web doctor，以及 Python 3.9–3.13 matrix 都通过；但 release-kit 正确拒绝 GitHub Actions 组可写的 `RUNNER_TEMP` 作为输出父目录，而 ARM64 预览正确拒绝 Actions 注入的 `PIP_INDEX_URL` 包镜像环境。`codex-bootstrap-v0.2.6` 的 workflow `#32895824047` 证明私有输出目录让 x86_64 release-kit 能完成长时间源审计后再进入其 runner-mount 限制，同时 Python matrix 保持全绿；ARM64 在清除包镜像后继续按 target HOME 祖先权限合同拒绝 `RUNNER_TEMP`。v0.2.7 把 release-kit 和 ARM64 的 disposable HOME 都放到 root-owned sticky `/tmp`，并将 builder/ARM64 的 fail-closed 阶段写入 GitHub annotation；这不会输出 payload、凭据或用户环境值。修复不能移动 v0.2.3 至 v0.2.6；因此 manifest/app bundle version 与 immutable release ref 前移到 `0.2.7`。在创建 annotated `codex-bootstrap-v0.2.7` 前，仍必须完成：干净源码测试、最终 release kit、隔离 fresh/latest-Codex 合同和 source 的 GitHub push；tag 推送后还必须等待 x86_64、Python matrix 与 native ARM64 workflow 绿灯，才允许 workflow publish job 创建 GitHub Release。若任一项失败，保留对应 tag 不动，修复后创建更高的新 tag。
 
+### 0.00 2026-08-25 v0.2.8 最终验收与 v0.2.9 文档闭环
+
+`codex-bootstrap-v0.2.8` 的 annotated tag object 为 `bc3c812541a32b060abfdc59bf6a780f3b056f40`，peeled commit 为 `e4775dbf5a3f94628e86950001a5f6b458744a57`。GitHub workflow `#32899018601` 的 x64 validate、native ARM64、Python 3.9–3.13 matrix 与 publish job 全部成功；Release `#376721397` 的 9 个资产、provenance、sidecar 和 `SHA256SUMS` 已从 GitHub 实际下载并在本地复算一致。在线 raw-commit 安装器的零写入 dry-run 与隔离真实官方 Codex core install/strict doctor 也通过，doctor 为 0 failures。
+
+第二次按用户“GitHub 文档与版本维护好、真正开箱即用”的标准复核时发现，v0.2.8 Release 正文仍是 GitHub 自动生成的通用项目 changelog，根 README 也没有明显的 Codex 服务器部署入口；功能资产正确，但交付发现性和 copy/paste 体验尚未完全闭环。v0.2.9 因此只在不放宽任何安全合同的前提下补齐：checksum 覆盖并随离线包发布的双语 `README.md`、由 provenance 身份自动填入的精确在线命令、离线/激活/安全边界说明、英文完整部署文档和中英文根 README 入口。发布 job 将直接使用已验证 README 作为 Release 正文，不再使用无关的自动 PR changelog。
+
 ### 0.0 2026-08-25 v0.2.7 发布尝试的更正记录
 
 `codex-bootstrap-v0.2.7` 已以 annotated tag 推送，tag object 为 `1030f301efb8d331a0ef8ad5189acc8d6ced8d35`，peeled commit 为 `263306c9889fe1abb350e0bb3af873c4bf87307c`。GitHub workflow `#32898034985` 的 Python 3.9–3.13 matrix 全绿，但 publish 被安全跳过：Actions checkout 中的 local tag representation 没有保留 annotated tag object，release-kit builder 与 ARM64 的 local-source verification 因而正确拒绝 lightweight tag。v0.2.8 会在每个 release-sensitive job 中显式 fetch 并验证 exact annotated tag object；ARM64 dry-run 也会清除 CI 注入的 `TMPDIR`/`XDG_RUNTIME_DIR`，让 root-owned sticky `/tmp` 成为唯一 staging root。上述修复不放宽 release、权限或凭据合同，也不会移动、删除或重用 v0.2.7。
@@ -82,7 +88,7 @@
 - skill runtime inventory：24 个 skill 仍含 Claude-specific 提示、33 个提到 MCP，source installed/discoverable 不等于外部 provider/credential 已激活；
 - isolated app service 使用 `service=none`，因此 doctor 正确提示需要在真实 login HOME 下由批准的 supervisor 启动。
 
-`v0.2.2` 是完整的历史验收基线；`v0.2.3` 是保留的 checkout-failure 证据，`v0.2.4` 是保留的 Web smoke failure 证据，`v0.2.5`、`v0.2.6` 与 `v0.2.7` 是 CI 边界 failure 证据。为使 runner 的 annotated-tag、临时目录安全合同和 ARM64 远程预览同时一致，本次会从干净源码创建新的 `v0.2.8` release。绝不移动、删除或复用 `v0.1.0`、`v0.2.0`、`v0.2.1`、`v0.2.2`、`v0.2.3`、`v0.2.4`、`v0.2.5`、`v0.2.6` 或 `v0.2.7` tags；未来只可继续创建更高的新 tag。
+`v0.2.2` 是完整的历史验收基线；`v0.2.3` 是保留的 checkout-failure 证据，`v0.2.4` 是保留的 Web smoke failure 证据，`v0.2.5`、`v0.2.6` 与 `v0.2.7` 是 CI 边界 failure 证据，`v0.2.8` 是首个全部 gate 成功并发布的功能基线。v0.2.9 只补齐自解释 Release/离线 README 与公开文档入口，不改变已经通过的安装安全边界。绝不移动、删除或复用任何 v0.1.0–v0.2.8 tag；未来只可继续创建更高的新 tag。
 
 ## 一、暂停时的准确结论
 

bootstrap/codex/app-manifest.json

@@ -1,6 +1,6 @@
 {
   "schema_version": 1,
-  "bundle_version": "0.2.8",
+  "bundle_version": "0.2.9",
   "application": {
     "name": "Dr. Claw Web",
     "package_name": "dr-claw",