release-skill 0.1.5 → 0.1.7

package/adapters/codex/bin/release-skill.mjs

@@ -23,12 +23,32 @@ try {
 }
 
 if (!bundleExists) {
+  // Fail closed with static text only: never interpolate bundlePath (or any
+  // other machine-specific value) so a copied/installed launcher cannot leak
+  // absolute paths, usernames, or host layout on stdout/stderr. This branch
+  // is self-contained by design — it must not import src/* or rely on the
+  // missing bundle's redaction helpers.
   console.error(
-    `Error: release-skill bundle not found at:\n  ${bundlePath}\n` +
-    `The bundle is required for installed-plugin execution.\n` +
-    `Reinstall the plugin or run 'node scripts/build-bundle.mjs' in the source checkout.`,
+    `Error: release-skill bundle not found (release-skill.bundle.mjs).\n` +
+    `The self-contained bundle is required for installed-plugin execution.\n` +
+    `Reinstall the plugin, or run 'node scripts/build-bundle.mjs' in a source checkout to rebuild it.`,
   );
   process.exit(1);
 }
 
-await import(bundlePath);
+// The bundle owns the command lifecycle: its entry awaits command completion
+// and exits with the real business exit code (success, business errors,
+// handled async rejections, unknown commands). The launcher only guards the
+// load itself: if the bundle cannot be evaluated (corrupt or incompatible
+// build), fail closed with static text only — module-load failures carry
+// absolute paths in their messages, so the failure is never interpolated.
+try {
+  await import(bundlePath);
+} catch {
+  console.error(
+    `Error: release-skill bundle failed to load (release-skill.bundle.mjs).\n` +
+    `The self-contained bundle is required for installed-plugin execution.\n` +
+    `Reinstall the plugin, or run 'node scripts/build-bundle.mjs' in a source checkout to rebuild it.`,
+  );
+  process.exit(1);
+}

package/adapters/codex/native/safe-write/binding.gyp

@@ -24,7 +24,8 @@
             "xcode_settings": {
               "GCC_ENABLE_CPP_EXCEPTIONS": "YES",
               "CLANG_CXX_LANGUAGE_STANDARD": "c++20",
-              "MACOSX_DEPLOYMENT_TARGET": "11.0"
+              "MACOSX_DEPLOYMENT_TARGET": "11.0",
+              "GCC_GENERATE_DEBUGGING_SYMBOLS": "NO"
             }
           }
         ],

package/adapters/codex/native/safe-write/prebuilds.json

@@ -3,7 +3,7 @@
   "prebuilds": {
     "darwin-arm64": {
       "path": "prebuilds/darwin-arm64/safe_write.node",
-      "sha256": "a0e39732c359f3faa23715e6d17d8bc5fec5c5b86e0390220e1beb9f5def2d2e",
+      "sha256": "f5ffc367a1c49fed812dc430246cd8b07fb722653cc9738acabcedb17d6bab67",
       "exports": [
         "openRoot",
         "openDir",

package/adapters/codex/schemas/.render-manifest.json

@@ -2,8 +2,8 @@
   "source": "schemas",
   "files": {
     "approval-record.schema.json": {
-      "digest": "38df0f095cc4b5be650a04513f8ea10cef5a6c3d0780ab38b0c5ee559d6ac7a5",
-      "bytes": 2611
+      "digest": "2ddac883435110e2c036cfadb00ce0c4d347a97d674b2c4ea9fcda3d72f81b8b",
+      "bytes": 3135
     },
     "artifact-lock.schema.json": {
       "digest": "6a5f4c826540b849571f173118bcbd778dfaceb4133034036ae565c3e9e353e5",
@@ -14,24 +14,24 @@
       "bytes": 1546
     },
     "artifact-policy.schema.json": {
-      "digest": "fa28b3856f2ed48b666458120c9b9d84d42c9ebfbec13bc866e8d71ecef6dea7",
-      "bytes": 2117
+      "digest": "86c9cab024ebe9c7f8ec3358fcc12d05b8ed246ab59da2b0acc6a517f31274ea",
+      "bytes": 2488
     },
     "evidence-event.schema.json": {
       "digest": "b7e14522a5aba818cab191545f23d2323be0e4c80566e9d3e4da576103a00490",
       "bytes": 2390
     },
     "release-plan.schema.json": {
-      "digest": "3647a554d7f8b1041078301b4de06c9aade0e1083ba8f6492cf4d3a825ea40ef",
-      "bytes": 4084
+      "digest": "13baa16d9a762cc04c7f28fc9d31ed81d381008c71eb044f4e97de252b4cc324",
+      "bytes": 22942
     },
     "release-project.schema.json": {
-      "digest": "6ae488bbad12563323892cc65f236a0ca3443aa6c0f4a17d69095a5c1af2574e",
-      "bytes": 6218
+      "digest": "4e46d6b1956a14d01471e7cf1cde3c0a6971c4f8844603fedd2a52f3535a43b6",
+      "bytes": 24167
     },
     "release-run.schema.json": {
-      "digest": "eeb16507f0d852ed1c53b0fbeeeda0ab1c15abea63554d6f4c127f75ca1dc673",
-      "bytes": 4037
+      "digest": "74f087f8815f00997c6ad3bac033660b9b69de226a6f5c48a96194dba0fa872c",
+      "bytes": 8917
     }
   }
 }

package/adapters/codex/schemas/release-project.schema.json

@@ -445,6 +445,9 @@
                 }
               ]
             }
+          },
+          "releaseDocuments": {
+            "$ref": "#/definitions/releaseDocuments"
           }
         },
         "allOf": [
@@ -634,6 +637,121 @@
         }
       }
     },
+    "releaseDocuments": {
+      "type": "object",
+      "description": "Optional configuration-driven multilingual release-document refresh for one release unit. Absence preserves legacy behaviour. Lexical layer only; runtime path, locale-membership and collision checks apply additionally.",
+      "required": [
+        "notesSource",
+        "locales",
+        "changelogs",
+        "readmes"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "notesSource": {
+          "type": "string",
+          "minLength": 1,
+          "pattern": "^(?!/)(?!\\.\\/)(?!.*\\\\)(?!.*:)(?!\\.\\.(/|$))(?!\\.$)(?!.*\\/\\.\\.\\/)(?!.*\\/\\.\\.$)(?!.*\\/\\.\\/)(?!.*\\/\\/)(?!.*\\0)(?!.*\\/\\.$)(?!.*\\/$)(?!.*\\{(?!version\\}))(?!.*(?<!\\{version)\\}).+\\.(?:yaml|yml|json)$"
+        },
+        "locales": {
+          "type": "array",
+          "minItems": 1,
+          "uniqueItems": true,
+          "items": {
+            "type": "string",
+            "pattern": "^[a-zA-Z]{2,3}(?:-[A-Za-z0-9]{2,8})*$"
+          }
+        },
+        "changelogs": {
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "$ref": "#/definitions/releaseDocumentsChangelog"
+          }
+        },
+        "readmes": {
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "$ref": "#/definitions/releaseDocumentsReadme"
+          }
+        }
+      }
+    },
+    "releaseDocumentsChangelog": {
+      "type": "object",
+      "required": [
+        "path",
+        "locale"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "path": {
+          "type": "string",
+          "minLength": 1,
+          "pattern": "^(?!/)(?!\\.\\/)(?!.*\\\\)(?!.*:)(?!\\.\\.(/|$))(?!\\.$)(?!.*\\/\\.\\.\\/)(?!.*\\/\\.\\.$)(?!.*\\/\\.\\/)(?!.*\\/\\/)(?!.*\\0)(?!.*\\/\\.$)(?!.*\\/$).*$"
+        },
+        "locale": {
+          "type": "string",
+          "pattern": "^[a-zA-Z]{2,3}(?:-[A-Za-z0-9]{2,8})*$"
+        }
+      }
+    },
+    "releaseDocumentsReadme": {
+      "type": "object",
+      "required": [
+        "path",
+        "locale",
+        "regions"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "path": {
+          "type": "string",
+          "minLength": 1,
+          "pattern": "^(?!/)(?!\\.\\/)(?!.*\\\\)(?!.*:)(?!\\.\\.(/|$))(?!\\.$)(?!.*\\/\\.\\.\\/)(?!.*\\/\\.\\.$)(?!.*\\/\\.\\/)(?!.*\\/\\/)(?!.*\\0)(?!.*\\/\\.$)(?!.*\\/$).*$"
+        },
+        "locale": {
+          "type": "string",
+          "pattern": "^[a-zA-Z]{2,3}(?:-[A-Za-z0-9]{2,8})*$"
+        },
+        "regions": {
+          "type": "array",
+          "minItems": 1,
+          "uniqueItems": true,
+          "items": {
+            "type": "string",
+            "pattern": "^[a-z0-9][a-z0-9._-]*$"
+          }
+        },
+        "versionMarkers": {
+          "type": "array",
+          "minItems": 1,
+          "uniqueItems": true,
+          "items": {
+            "$ref": "#/definitions/releaseDocumentsVersionMarker"
+          }
+        }
+      }
+    },
+    "releaseDocumentsVersionMarker": {
+      "type": "object",
+      "required": [
+        "id",
+        "pattern"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "id": {
+          "type": "string",
+          "pattern": "^[a-z0-9][a-z0-9._-]*$"
+        },
+        "pattern": {
+          "type": "string",
+          "minLength": 1
+        }
+      }
+    },
     "verificationGate": {
       "type": "object",
       "required": [

package/adapters/codex/skills/release-help/SKILL.md

@@ -42,8 +42,24 @@ description: "Discoverable entry point for release-skill: dependency and environ
 node "$RELEASE_SKILL_ENTRY" help --json
 node "$RELEASE_SKILL_ENTRY" setup --root <path> --json
 node "$RELEASE_SKILL_ENTRY" assess --root <path> --offline --json
+# 发布文档刷新：默认只读演练
+node "$RELEASE_SKILL_ENTRY" docs refresh --unit <id> --json
+# 摘要确认后的本地写入（三项绑定缺一不可）
+node "$RELEASE_SKILL_ENTRY" docs refresh --unit <id> \
+  --write --confirm-refresh <refreshDigest> --ack-local-document-write --json
 ```
 
+## 发布文档刷新（docs refresh）
+
+发布单元配置 `releaseDocuments` 后，一份结构化双语说明源可确定性刷新 README 受管区域、唯一版本标记的机器值和 CHANGELOG 当前版本受管条目。核心 CLI 不联网、不调用大模型、不自动翻译；只改写声明过的受管区域、版本标记机器值和当前受管条目，区域外字节逐字保留。`prepare` 只检查新鲜度，不写工作树。
+
+- **配置**：`releaseDocuments.notesSource`（说明源路径，只允许 `{version}` 占位符与 `.yaml`/`.yml`/`.json` 后缀）、`locales`（如 `[en, zh-CN]`）、`changelogs`（path + locale）、`readmes`（path + locale + `regions` 受管区域 id + `versionMarkers` 版本标记模式）。版本标记模式必须与 README 现有唯一标记精确匹配，`{version}` 代表机器版本值，刷新只替换该值；零次或多次匹配失败关闭。
+- **说明源**：`version` 必须与单元版本精确一致，`date` 为 `YYYY-MM-DD`，每个配置语种恰好出现一次且 `summary`、变更项非空，`security`/`breaking`/`added`/`changed`/`deprecated`/`removed`/`fixed` 至少一个类别含条目。YAML alias、重复键、未知字段和语种回退都失败关闭。
+- **只读演练**：`docs refresh --unit <id> --json` 输出逐文件相对路径、locale、新旧摘要、`version`、`locales`、`inputDigest`、`refreshDigest` 和 `nextCommand.argv`；候选无变化时 `status: "clean"`。
+- **确认写入**：必须同时提供 `--write`、精确 `--confirm-refresh <refreshDigest>` 和 `--ack-local-document-write`，全部目标作为一个事务提交；成功后立即复演必须为 `clean`。
+
+**授权边界**：本地发布文档写入授权只覆盖声明的本地文档目标，不是 hook、Git 提交、push、publish 或安装的授权。写入后必须审阅、提交，再重新 prepare。
+
 ## 故障路由
 
 | 场景 | 处理 |
@@ -57,6 +73,11 @@ node "$RELEASE_SKILL_ENTRY" assess --root <path> --offline --json
 | 项目配置不存在 | 路由 `release-setup`，默认只读；不得直接生成或覆盖 README/配置 |
 | assess 失败 | 运行 `node "$RELEASE_SKILL_ENTRY" assess --offline --json` 获取详情 |
 | 请求生产发布 | 已有公开版本先调用 `release-prepare --online --production` 观察 bound 基线；人工审阅后再路由 `release-publish` |
+| RELEASE_DOCS_INVALID | 配置或说明源语义非法（重复键、alias、未知字段、版本漂移等）；修正配置或说明源后重新演练 |
+| RELEASE_DOCS_TRANSLATION_MISSING | 配置语种缺失或多余；补齐说明源语种，与 `releaseDocuments.locales` 完全一致，不得回退 |
+| RELEASE_DOCS_CONFLICT | 目标含非受管同版本条目、受管标记损坏或人工冲突；人工修复目标并保留人工修改后重新演练 |
+| RELEASE_DOCS_REFRESH_STALE | 确认绑定后候选已变化；重新演练取得新 `refreshDigest` 再确认写入 |
+| RELEASE_DOCS_STALE | prepare 检测到文档未刷新；按 `docs refresh` → 审阅 → 提交 → 重新 prepare 恢复 |
 
 ## 后续引导
 

package/adapters/codex/skills/release-prepare/SKILL.md

@@ -30,13 +30,16 @@ description: Freeze an immutable release plan with local configuration, document
 
 **不确定性停止**: 遇到无法确定的配置项或版本冲突时，Agent 必须停止并上报用户。
 
+**发布文档新鲜度门**: 配置了 `releaseDocuments` 的单元在 hook 授权门前先执行同一只读规划器：`clean` 继续；`changes` 抛 `RELEASE_DOCS_STALE`，详情列出相对路径、语种、`refreshDigest` 和精确演练/写入参数数组。prepare 只检查、不写工作树。正式 prepare 前先运行只读演练；有变化时向用户展示文件/语种/版本/`refreshDigest`，只有在用户明确授权"本地发布文档写入"后，才执行带 `--write --confirm-refresh <refreshDigest> --ack-local-document-write` 三项绑定的写入，随后运行聚焦校验，要求维护者审阅并提交刷新结果，再重新 prepare。该授权不扩展为 hook、提交、push 或 publish 授权。
+
 ## 正向执行路径
 
 1. 使用插件根相对路径运行 CLI：`CLI="node $RELEASE_SKILL_ENTRY"`
-2. 运行 `${CLI} prepare --root <path> --offline --json`
-3. 若遇到 hook/gate 授权门失败，分别展示命令和风险，获取授权后只增加实际需要的 `--acknowledge-hook-side-effects` / `--acknowledge-gate-side-effects`
-4. 检查 exit code 0，读取 JSON 返回的 immutable `planPath=plans/<planDigest>.json`，再从该文件读取 `status`、`units`、`externalActions`
-5. 向用户展示 targetVersion、externalActions、planDigest 和 planPath；后续 approve/publish 只能使用该 immutable planPath，等待确认后再 approve
+2. 配置含 `releaseDocuments` 时，先运行只读演练 `${CLI} docs refresh --unit <id> --json`；`status: "changes"` 时展示逐文件路径/语种/版本/`refreshDigest`，取得"本地发布文档写入"明确授权后才执行 `nextCommand.argv` 写入，审阅并提交刷新结果后再继续；`status: "clean"` 时直接进入 prepare
+3. 运行 `${CLI} prepare --root <path> --offline --json`
+4. 若遇到 hook/gate 授权门失败，分别展示命令和风险，获取授权后只增加实际需要的 `--acknowledge-hook-side-effects` / `--acknowledge-gate-side-effects`
+5. 检查 exit code 0，读取 JSON 返回的 immutable `planPath=plans/<planDigest>.json`，再从该文件读取 `status`、`units`、`externalActions`
+6. 向用户展示 targetVersion、externalActions、planDigest 和 planPath；后续 approve/publish 只能使用该 immutable planPath，等待确认后再 approve
 
 若用户明确要求 GitHub+npm 生产发布，加入 `--production`。该模式还会封存独立
 Git commit/tree 和 npm tarball，并把路径、SHA/integrity、branch/tag 写入计划。
@@ -55,6 +58,11 @@ prepare 后若人工继续修改 README 或任何源文件，应保留修改并
 ## 确定性脚本调用
 
 ```bash
+# 发布文档新鲜度：prepare 前只读演练（配置了 releaseDocuments 的单元）
+node "$RELEASE_SKILL_ENTRY" docs refresh --unit <id> --json
+# 仅在用户明确授权“本地发布文档写入”后执行（三项绑定缺一不可）
+node "$RELEASE_SKILL_ENTRY" docs refresh --unit <id> \
+  --write --confirm-refresh <refreshDigest> --ack-local-document-write --json
 node "$RELEASE_SKILL_ENTRY" prepare --root <path> --offline --json
 # 生产 happy end：bound 基线必须 online；远端目标唯一性仍由 publish 全局预检
 node "$RELEASE_SKILL_ENTRY" prepare --root <path> --online --production --json
@@ -66,8 +74,9 @@ node "$RELEASE_SKILL_ENTRY" prepare --root <path> --offline --acknowledge-gate-s
 
 ## 执行顺序
 
-1. 校验配置 schema → 2. Hook 授权门 → 3. 运行 hooks → 4. 捕获 Git baseline →
-5. 逐 unit 观察前序公开基线 → 6. 生成快照/扫描/README → 7. 版本解析 → 8. 原子写入 plan
+1. 校验配置 schema → 2. 版本解析与发布文档新鲜度门（只读，RELEASE_DOCS_STALE）→
+3. Hook 授权门 → 4. 运行 hooks 并复检文档新鲜度 → 5. 捕获 Git baseline →
+6. 逐 unit 观察前序公开基线 → 7. 生成快照/扫描/README → 8. 原子写入 plan
 
 ## 故障路由
 
@@ -78,6 +87,8 @@ node "$RELEASE_SKILL_ENTRY" prepare --root <path> --offline --acknowledge-gate-s
 | GATE_FAILED (bound + offline) | 改用 `--online --production`，不得把 unobserved-offline plan 交给 publish |
 | GATE_FAILED (前序基线漂移) | 先取得并比较实际远端内容；人工选择 merge/adopt/reject。merge/adopt 都必须把接受内容落回 human-owned 权威源，并把 `previousPublicBaseline` 更新为接受状态的精确 repo/ref/commit 后重新 online production prepare；reject 停止调查，禁止改 `mode: none` 绕过 |
 | GATE_FAILED (其他) | 修复门失败原因后重试；以 CLI exit code 为准 |
+| RELEASE_DOCS_STALE | 文档相对说明源已陈旧；按详情运行只读演练，展示文件/语种/版本/摘要，经用户授权“本地发布文档写入”后执行写入，审阅提交再重新 prepare |
+| RELEASE_DOCS_INVALID / TRANSLATION_MISSING / CONFLICT / REFRESH_STALE | 修复配置/说明源/目标或重新演练取得新 `refreshDigest`；不得扩大写入范围绕过 |
 | SECRET_DETECTED | 移除密钥并更新 allowlist |
 | CONFIG_INVALID | 检查 version.source 和 package.json |
 

package/adapters/codex/skills/release-publish/SKILL.md

@@ -24,7 +24,9 @@ description: 从已批准且摘要确认的生产计划发布冻结 Git branch/t
 不得把沙箱通过描述成真实发布成功。
 
 只发布 `prepare --production` 封存的 Git object 和 npm tarball，不从活动工作区重新
-打包，不生成或覆盖 README。远端 branch/tag/Release/npm version 已存在、查询不确定、
+打包，不生成或覆盖 README，也永不隐式刷新工作树中的发布文档；
+遇到 `RELEASE_DOCS_STALE` 或文档陈旧只能回到 `docs refresh` → 人工审阅 → 提交 →
+重新 prepare。远端 branch/tag/Release/npm version 已存在、查询不确定、
 认证失败或摘要漂移时，在全局预检阶段停止并交给人工。禁止覆盖、删除和自动回滚；
 新建 ref 的 create-only CAS（`--force-with-lease=<ref>:`）只断言目标不存在，不授权覆盖。
 

package/adapters/codex/skills/release-reconcile/SKILL.md

@@ -26,7 +26,7 @@ marketplace 隔离消费者 checkpoint，但只恢复到 `PUBLISHED`；最终 np
 
 ## 职责与边界
 
-查询远端实际状态，对照冻结计划识别一致/不一致检查点。已成功的步骤幂等跳过，只重试安全且未完成的步骤。远端冲突时停止并要求人工决策。不删除远端资源。`--run` 必需；重试需 `--approval`。
+查询远端实际状态，对照冻结计划识别一致/不一致检查点。已成功的步骤幂等跳过，只重试安全且未完成的步骤。远端冲突时停止并要求人工决策。不删除远端资源。`--run` 必需；重试需 `--approval`。reconcile 永不隐式刷新工作树中的发布文档；陈旧文档只能回到 `docs refresh` → 人工审阅 → 提交 → 重新 prepare。
 
 **阶段通过规则**: 本阶段的通过只能由 CLI exit code 0 和结构化状态码 `PUBLISHED` 确认。随后必须以 reconcile 返回的新 `runPath` 执行 verify；只有 verify 的 `VERIFIED` 才是完整终态。
 

package/bin/release-skill-cli.mjs

@@ -4,10 +4,22 @@ import { basename, dirname, join, resolve } from 'node:path';
 import { execFile as execFileCb } from 'node:child_process';
 import { promisify } from 'node:util';
 import { parseNodeMajor, meetsMinimum, computeReadinessStatus } from '../src/core/node-version.mjs';
+import { registerPathRedactor } from '../src/core/errors.mjs';
+import { redactSensitivePaths } from '../src/core/redact.mjs';
+
+// Install the path-redaction choke point eagerly and synchronously (static
+// imports, no top-level await) so every ReleaseError constructed on any
+// command path is redacted from the very first statement — in source mode and
+// in the self-contained bundle alike. The bundle evaluates these static
+// imports during its top level, before any lazy command initialization or
+// handler runs; keeping this module graph free of top-level await is also
+// what lets the bundled artifacts tree settle (AC-7: the launcher must never
+// exit 13 "Detected unsettled top-level await" for a command it owns).
+registerPathRedactor(redactSensitivePaths);
 
 const execFile = promisify(execFileCb);
 
-const COMMANDS = new Set(['help', 'setup', 'assess', 'prepare', 'approve', 'publish', 'reconcile', 'verify', 'artifacts']);
+const COMMANDS = new Set(['help', 'setup', 'assess', 'prepare', 'approve', 'publish', 'reconcile', 'verify', 'artifacts', 'docs']);
 
 /**
  * Check if a command is available and get its version.
@@ -128,6 +140,11 @@ function getCapabilityMaturity() {
       mode: 'offline local writes',
       description: 'Freeze a release plan with snapshots and gates',
     },
+    docs: {
+      available: true,
+      mode: 'read-only dry-run / explicit local document write',
+      description: 'Refresh declared README managed regions and CHANGELOG current-version entries from one structured notes source; write requires --write, exact --confirm-refresh, and --ack-local-document-write; never commits, pushes, or publishes',
+    },
     publish: {
       available: true,
       mode: 'controlled production (protocol-tested; no OS/network sandbox)',
@@ -162,6 +179,7 @@ Commands:
   reconcile  Resume PARTIAL state from evidence; conflicts require a human
   verify     Fresh remote and consumer verification; only this reaches VERIFIED
   artifacts  Artifact status, inspect, update/apply, resolution, and diagnostics
+  docs       Refresh declared release documents (read-only dry-run by default)
 
 Options:
   --root <path>    Project root directory (default: cwd)
@@ -175,6 +193,9 @@ Options:
   --answers <path> Human-reviewed setup answers JSON
   --write          Create an absent project.yaml during setup; never overwrites
   --confirm-setup <digest> Confirm exact setup facts and answers before create
+  --unit <id>      Release unit whose declared release documents are refreshed (docs refresh)
+  --confirm-refresh <sha256:...> Confirm the exact dry-run refreshDigest before any document write
+  --ack-local-document-write Acknowledge the explicit local release-document write (docs refresh --write)
   --acknowledge-hook-side-effects Acknowledge unsandboxed legacy hook execution
   --acknowledge-gate-side-effects Acknowledge unsandboxed local verification gate execution
   --json           Output results as JSON
@@ -189,6 +210,7 @@ Safety:
   - prepare output goes to .release-skill/ directory only
   - User-configured hooks may write anywhere and perform remote operations
   - To ensure zero remote writes, disable hooks or audit them separately
+  - docs refresh --write rewrites only declared README managed regions and the current CHANGELOG entry after exact refreshDigest confirmation; it never commits, pushes, tags, publishes, or installs.
   - publish requires explicit approval and an exact plan-digest confirmation
   - publish consumes frozen Git/npm artifacts, never the live workspace
   - existing remote objects and uncertain checks stop for human intervention
@@ -206,9 +228,25 @@ const positional = args.filter(a => !a.startsWith('--'));
 const command = positional[0];
 
 if (!command && (args.includes('--version') || args.includes('-v'))) {
-  const { createRequire } = await import('node:module');
-  const require = createRequire(import.meta.url);
-  const pkg = require('../package.json');
+  // The version probe must be install-closure independent: the npm closure
+  // resolves ../package.json from bin/, but the Claude and Codex adapter
+  // closures ship the bundle at a different depth with no package.json at
+  // all. Bundled closures therefore carry the package identity as a
+  // build-time constant (__bundlePkg) injected by the esbuild banner in
+  // scripts/build-bundle.mjs; only source mode reads the file.
+  let pkg;
+  if (typeof __bundlePkg !== 'undefined') {
+    pkg = __bundlePkg;
+  } else {
+    // Source mode only (the bundle always carries __bundlePkg). Deliberately
+    // not a require('../package.json'): esbuild would inline it into the
+    // bundle as the one remaining bundle-relative file dependency, which is
+    // exactly what breaks the adapter closures.
+    const { readFileSync } = await import('node:fs');
+    const { fileURLToPath } = await import('node:url');
+    const pkgPath = join(dirname(fileURLToPath(import.meta.url)), '..', 'package.json');
+    pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
+  }
   if (hasJson) {
     console.log(JSON.stringify({
       command: 'version',
@@ -269,6 +307,7 @@ if (!command || command === 'help') {
         setup: 'read-only by default; create-once requires answers plus exact setupDigest confirmation',
         assess: 'read-only (default); --output writes local report',
         prepare: 'offline local writes; configured hooks/gates require their explicit side-effect acknowledgements',
+        docs: 'read-only dry-run by default; write requires --write, exact --confirm-refresh, and --ack-local-document-write; never commits, pushes, or publishes',
         onlinePrepare: 'previous-public-baseline observation available; production mode freezes publish artifacts and fails closed on drift or unknown state',
         publish: 'GitHub/npm plus configured Claude/Codex consumer checkpoints are protocol-tested without an OS/network sandbox; approval and exact digest confirmation required',
         reconcile: 'PARTIAL recovery is protocol-tested without an OS/network sandbox; remote conflicts require human intervention',
@@ -802,6 +841,126 @@ if (command === 'artifacts') {
   }
 }
 
+// --- Docs command routing ---
+if (command === 'docs') {
+  try {
+    const { ReleaseError, MISSING_PARAMETERS } = await import('../src/core/errors.mjs');
+
+    // --root is extracted and validated here (the router resolves the project
+    // root): a following flag is never accepted as the path, and a duplicated
+    // --root is an explicit parameter error (previously silently ignored).
+    const rootIndexes = [];
+    for (let i = 0; i < args.length; i += 1) {
+      if (args[i] === '--root') rootIndexes.push(i);
+    }
+    if (rootIndexes.length > 1) {
+      throw new ReleaseError(
+        MISSING_PARAMETERS,
+        'docs received --root more than once',
+        { reason: 'DUPLICATE_PARAMETER', field: '--root' },
+      );
+    }
+    let rawRoot = process.cwd();
+    if (rootIndexes.length === 1) {
+      rawRoot = args[rootIndexes[0] + 1];
+      if (typeof rawRoot !== 'string' || rawRoot.length === 0 || rawRoot.startsWith('-')) {
+        throw new ReleaseError(
+          MISSING_PARAMETERS,
+          'docs --root requires a path value',
+          { reason: 'MISSING_VALUE', field: '--root' },
+        );
+      }
+    }
+    const root = resolve(rawRoot);
+
+    // The docs subcommand is the first bare positional token after the `docs`
+    // command token itself. Valued flags and their values are skipped so
+    // `--root <path>` can never be mistaken for the subcommand; any flag
+    // outside the recognized docs set (including unregistered valued flags)
+    // is rejected here so its value can never be mistaken for the subcommand.
+    const valuedDocsFlags = new Set(['--root', '--unit', '--confirm-refresh']);
+    const booleanDocsFlags = new Set(['--json', '--write', '--ack-local-document-write']);
+    let docsSubcommand;
+    let sawCommandToken = false;
+    for (let i = 0; i < args.length; i += 1) {
+      const token = args[i];
+      if (typeof token !== 'string') continue;
+      if (token.startsWith('--')) {
+        const eq = token.indexOf('=');
+        const flag = eq === -1 ? token : token.slice(0, eq);
+        if (valuedDocsFlags.has(flag)) {
+          if (eq === -1) i += 1; // space-separated form: skip the value too
+          continue;
+        }
+        if (booleanDocsFlags.has(flag)) continue;
+        throw new ReleaseError(
+          MISSING_PARAMETERS,
+          `docs does not accept ${flag}`,
+          { reason: 'UNRECOGNIZED_PARAMETER', parameter: flag },
+        );
+      }
+      if (token.startsWith('-') && token.length > 1) {
+        throw new ReleaseError(
+          MISSING_PARAMETERS,
+          `docs does not accept ${token}`,
+          { reason: 'UNRECOGNIZED_PARAMETER', parameter: token },
+        );
+      }
+      if (!sawCommandToken) {
+        sawCommandToken = true; // the `docs` command token itself
+        continue;
+      }
+      docsSubcommand = token;
+      break;
+    }
+
+    const { runDocsCommand } = await import('../src/commands/docs.mjs');
+    const result = await runDocsCommand({ subcommand: docsSubcommand, args, root });
+
+    if (hasJson) {
+      console.log(JSON.stringify(result, null, 2));
+    } else if (result.mode === 'dry-run') {
+      console.log(`Status: ${result.status}`);
+      console.log(`Unit: ${result.unitId}`);
+      console.log(`Version: ${result.version}`);
+      console.log(`Refresh digest: ${result.refreshDigest}`);
+      for (const file of result.files) {
+        const marker = file.changed ? '' : ' (unchanged)';
+        console.log(`  ${file.path} ${file.kind} ${file.locale} ${file.change}${marker}`);
+      }
+      if (result.nextCommand?.argv) {
+        console.log(`Next: ${result.nextCommand.argv.join(' ')}`);
+      }
+      if (result.nextCommand?.writeArgv) {
+        console.log(`Next (write): ${result.nextCommand.writeArgv.join(' ')}`);
+      }
+    } else {
+      console.log(`Status: ${result.status}`);
+      console.log(`Unit: ${result.unitId}`);
+      console.log(`Version: ${result.version}`);
+      console.log(`Refresh digest: ${result.refreshDigest}`);
+      if (result.refreshed) {
+        console.log(`Transaction: ${result.transactionId}`);
+        for (const path of result.refreshedPaths ?? []) {
+          console.log(`  refreshed ${path}`);
+        }
+      }
+    }
+
+    process.exit(0);
+  } catch (err) {
+    // docs parameter errors must surface the stable JSON error shape even in
+    // text mode (CLI parameter validation precedes any service I/O).
+    console.log(JSON.stringify({
+      error: err.code ?? 'UNKNOWN_ERROR',
+      message: err.message,
+      details: err.details ?? {},
+      exitCode: err.exitCode ?? 1,
+    }));
+    process.exit(err.exitCode ?? 1);
+  }
+}
+
 // Placeholder: remaining commands will be wired in later tasks
 console.error(`Command '${command}' is not yet implemented.`);
 process.exit(1);