release-skill 0.1.3 → 0.1.5

package/.claude-plugin/marketplace.json

@@ -9,7 +9,7 @@
     {
       "name": "release-skill",
       "source": "./",
-      "version": "0.1.3",
+      "version": "0.1.5",
       "description": "Safe preparation and frozen GitHub/npm production publishing with full happy end verification"
     }
   ]

package/.claude-plugin/plugin.json

@@ -1,10 +1,10 @@
 {
   "name": "release-skill",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "description": "Safe preparation and frozen GitHub/npm production publishing with full happy end verification",
   "author": {
     "name": "release-skill contributors"
   },
   "license": "MIT",
-  "skills": "./skills/"
+  "skills": "./adapters/claude/skills/"
 }

package/.codex-plugin/plugin.json

@@ -1,12 +1,12 @@
 {
   "name": "release-skill",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "description": "Safe preparation and frozen GitHub/npm production publishing with full happy end verification",
   "author": {
     "name": "release-skill contributors"
   },
   "license": "MIT",
-  "skills": "./skills/",
+  "skills": "./adapters/codex/skills/",
   "interface": {
     "displayName": "Release Skill",
     "shortDescription": "Safe preparation and frozen GitHub/npm publishing",
@@ -19,7 +19,7 @@
     ],
     "defaultPrompt": [
       "Assess this project for release readiness.",
-      "Prepare a release plan for version 0.1.3.",
+      "Prepare a release plan for version 0.1.5.",
       "Help me understand the release workflow."
     ]
   }

package/CHANGELOG.md

@@ -3,6 +3,62 @@
 All notable changes to the `release-skill` plugin will be documented in this
 file. The format is based on [Keep a Changelog](https://keepachangelog.com/).
 
+## [0.1.5] - 2026-07-21
+
+### Added
+
+- **Explicit marketplace install timeout (`timeoutMs`)**: Claude and Codex
+  plugin marketplace distributions now accept an optional `timeoutMs` integer
+  field (range 30,000--900,000 ms; default 300,000 ms). The resolved value is
+  frozen into each marketplace install action's `parameters.timeoutMs` during
+  `prepare`, making it part of the plan digest, approval binding, and plan
+  integrity. The `plugin-marketplace` adapter's marketplace add, plugin install,
+  and plugin list commands all use the same frozen timeout, replacing the
+  previous hardcoded 30-second limit that caused `PARTIAL` failures on real
+  network installations requiring 40--105 seconds.
+- **Old plan backward compatibility**: plans created before v0.1.5 that lack
+  `parameters.timeoutMs` on marketplace install actions default to 300,000 ms,
+  so existing `PARTIAL` runs can be reconciled without upgrading the plan.
+
+### Fixed
+
+- **Marketplace consumer install timeout**: v0.1.4 production releases hit
+  `PARTIAL` because Claude Code and Codex plugin marketplace add commands
+  required 40--105 seconds on real networks, while the adapter hardcoded a
+  30-second subprocess timeout. The timeout is now explicitly configurable per
+  distribution and verified through injected-executor tests. Invalid values
+  (non-integer, non-finite, out-of-range) fail closed rather than being
+  silently clamped.
+
+## [0.1.4] - 2026-07-19
+
+### Added
+
+- **Docs version hard gate**: the English and Chinese README and INSTALL each
+  carry a machine-readable `release-skill:release-version` marker that must
+  equal the `package.json` version, and the CHANGELOG must carry a formal
+  heading for the current version. Any drift fails closed in
+  `pnpm test:release` before prepare. A release freezes only the current
+  truth: human docs are never auto-refreshed and must be updated, reviewed,
+  and approved first.
+- **Auditable frozen commit timestamps**: production `prepare` samples the
+  plan freeze time once, validates it before any Git write, and binds it to
+  `GIT_AUTHOR_DATE`/`GIT_COMMITTER_DATE` and each unit's
+  `frozenSnapshot.commitTimestamp` (schema-required); plans missing the field
+  are rejected instead of silently rebuilt.
+
+### Fixed
+
+- **Self-contained installed CLI smoke**: the v0.1.3 self-release selected
+  `help --json`, which correctly treats Git as a required environment
+  dependency, while npm smoke intentionally exposes only the Node runtime.
+  The CLI now supports `--version --json`, and self-release verification uses
+  that dependency-free entry to bind the installed CLI name and exact version
+  without widening the isolated process `PATH`.
+- Added a real subprocess regression that runs the installed-style version
+  entry with the Node-only `PATH` and proves an unrelated injected path is not
+  inherited.
+
 ## [0.1.3] - 2026-07-19
 
 > `0.1.2` was an internal release candidate and was never published to npm or

package/INSTALL.md

@@ -2,6 +2,7 @@
 
 [简体中文](INSTALL.zh-CN.md)
 
+<!-- release-skill:release-version: 0.1.5 -->
 ## Prerequisites
 
 - Node.js 22.0.0 or later
@@ -9,8 +10,9 @@
 
 ## Install from npm (recommended)
 
-v0.1.1 is published and verified. For a newer source candidate such as v0.1.3,
-use the npm path only after `npm view release-skill version` returns that exact
+A public version is complete only after its immutable production plan has been
+approved, published, and reached `VERIFIED`. For a newer source checkout, use
+the npm path only after `npm view release-skill version` returns that exact
 version; before then, use the source checkout instructions below.
 
 ```bash
@@ -63,22 +65,71 @@ instructions above; do not mix the two entry paths in one run.
 "${CLI[@]}" help
 ```
 
-If `.release-skill/project.yaml` is absent, discover first-use facts and
-candidates without writing files:
+If `.release-skill/project.yaml` is absent, keep the full read-only report in a
+temporary file and inspect only its deterministic `compactSummary`:
 
 ```bash
-"${CLI[@]}" setup --root /path/to/your/project --json
+PROJECT=/path/to/your/project
+SETUP_SESSION="$(mktemp -d "${TMPDIR:-/tmp}/release-setup.XXXXXX")"
+REPORT="$SETUP_SESSION/discovery.json"
+ANSWERS="$SETUP_SESSION/answers.json"
+BOUND_REPORT="$SETUP_SESSION/bound.json"
+printf 'SETUP_SESSION=%s\nPROJECT=%s\n' "$SETUP_SESSION" "$PROJECT"
+
+"${CLI[@]}" setup --root "$PROJECT" --json > "$REPORT" || test "$?" -eq 2
+node -e 'const fs=require("node:fs");const r=JSON.parse(fs.readFileSync(process.argv[1],"utf8"));if(!r.compactSummary){console.error("compactSummary missing");process.exit(2)}process.stdout.write(JSON.stringify(r.compactSummary,null,2)+"\n")' "$REPORT"
 ```
 
-`NEEDS_INPUT` and `LOCAL_ONLY_DETECTED` intentionally return exit code 2. They
-are decision states, not an internal crash; automation should inspect the JSON
-`status`.
+The summary is a review view, not authorization; `setupDigest` binds the full
+facts, candidates, and answers. If `proposalConflicts` is non-empty, a human
+must correct the conflicting repository/mapping authority and rerun setup.
+Do not guess. With no conflicts, mechanically extract the proposal:
 
-Review release units, legacy `public-release.json` migration hints, tags,
-branch strategies, previous-public-baseline decisions, and gate candidates.
-Setup never executes a discovered script automatically. Provide a complete
-answers JSON, dry-run again to obtain the digest that binds current facts and
-answers, then create the configuration exactly once:
+```bash
+SETUP_SESSION='/session-directory-absolute-path-printed-above'
+PROJECT='/project-absolute-path-printed-above'
+REPORT="$SETUP_SESSION/discovery.json"
+ANSWERS="$SETUP_SESSION/answers.json"
+BOUND_REPORT="$SETUP_SESSION/bound.json"
+node -e 'const fs=require("node:fs");const r=JSON.parse(fs.readFileSync(process.argv[1],"utf8"));if((r.proposalConflicts??[]).length){console.error("proposal conflicts require human resolution");process.exit(2)}if(!r.recommendedAnswers){console.error("recommendedAnswers missing");process.exit(2)}fs.writeFileSync(process.argv[2],JSON.stringify(r.recommendedAnswers,null,2)+"\n",{flag:"wx",mode:0o600})' "$REPORT" "$ANSWERS"
+"${CLI[@]}" setup --root "$PROJECT" --answers "$ANSWERS" --json > "$BOUND_REPORT"
+node -e 'const fs=require("node:fs");const r=JSON.parse(fs.readFileSync(process.argv[1],"utf8"));if(!r.compactSummary||!r.setupDigest){console.error("bound setup report incomplete");process.exit(2)}process.stdout.write(JSON.stringify({compactSummary:r.compactSummary,setupDigest:r.setupDigest},null,2)+"\n")' "$BOUND_REPORT"
+printf 'SETUP_SESSION=%s\nPROJECT=%s\n' "$SETUP_SESSION" "$PROJECT"
+```
+
+After one explicit human confirmation of the bound summary and exact digest,
+create once with that confirmed digest literal. The result must be
+`CONFIG_CREATED`; a second setup must be `ALREADY_CONFIGURED`, then run assess.
+
+```bash
+SETUP_SESSION=<session-directory-absolute-path-printed-above>
+PROJECT=<project-absolute-path-printed-above>
+ANSWERS="$SETUP_SESSION/answers.json"
+CREATED_REPORT="$SETUP_SESSION/created.json"
+POST_REPORT="$SETUP_SESSION/post-setup.json"
+ASSESS_REPORT="$SETUP_SESSION/assess.json"
+"${CLI[@]}" setup --root "$PROJECT" --answers "$ANSWERS" \
+  --write --confirm-setup <confirmed-setupDigest> --json > "$CREATED_REPORT"
+"${CLI[@]}" setup --root "$PROJECT" --json > "$POST_REPORT"
+set +e
+"${CLI[@]}" assess --root "$PROJECT" --offline --json > "$ASSESS_REPORT"
+ASSESS_EXIT=$?
+set -e
+[ "$ASSESS_EXIT" -eq 0 ] || [ "$ASSESS_EXIT" -eq 1 ] || exit "$ASSESS_EXIT"
+node -e 'const fs=require("node:fs");const [c,p,a]=process.argv.slice(1).map(x=>JSON.parse(fs.readFileSync(x,"utf8")));if(c.status!=="CONFIG_CREATED"||p.status!=="ALREADY_CONFIGURED"||!["ASSESSED","NEEDS_INPUT","BLOCKED"].includes(a.status)){process.exit(2)}process.stdout.write(JSON.stringify({created:c.status,postSetup:p.status,assessment:{status:a.status,summary:a.summary,gapCount:(a.gaps??[]).length,blockingCodes:(a.gaps??[]).filter(g=>g.severity==="error").map(g=>g.code)}},null,2)+"\n")' "$CREATED_REPORT" "$POST_REPORT" "$ASSESS_REPORT"
+node -e 'require("node:fs").rmSync(process.argv[1],{recursive:true,force:false})' "$SETUP_SESSION"
+```
+
+Indirect interpreter/package-manager scripts are `SIDE_EFFECTS_UNPROVEN` and
+remain unselected. Register a project-specific hook/gate only through a reviewed
+incremental edit: edit `projectConfig.hooks`, or edit `verificationGates` and
+add the same id to `selectedGateIds`, then rerun the bound dry-run. Human files use `mode: preserve`; explicit cross-unit shared
+sources use `sourceScope: workspace`.
+
+### Advanced schema reference—not the first-run path
+
+The following wrapper documents the schema. Do not hand-write it during normal
+setup; use the mechanically extracted `recommendedAnswers`.
 
 ```json
 {
@@ -116,25 +167,11 @@ answers, then create the configuration exactly once:
 }
 ```
 
-The wrapper is complete, but its values are examples. Replace every repository,
-channel, baseline, and public-file decision with reviewed project facts; use
-`mode: none` only when no public version exists.
-
-When selecting a reported gate, add the complete gate definition to
-`projectConfig.verificationGates` and copy its id into `selectedGateIds`. The
-id must come from the current `gateCandidates`. A snapshot-gate command and all
-of its dependencies must be present in `publicFiles`; it cannot see tests,
-development dependencies, or `node_modules` that exist only in the parent
-workspace. The full [README setup section](README.md#first-use-discover-then-let-a-human-finalize)
-contains complete no-gate and one-gate answers examples.
-
-```bash
-"${CLI[@]}" setup --root /path/to/your/project \
-  --answers /path/to/setup-answers.json --json
-"${CLI[@]}" setup --root /path/to/your/project \
-  --answers /path/to/setup-answers.json \
-  --write --confirm-setup <setupDigest> --json
-```
+This wrapper is reference data only. Normal setup uses the machine proposal;
+`mode: none` is valid only when no public version exists. When a reviewed gate
+is added incrementally, its id must exactly match `selectedGateIds`, and a
+snapshot gate plus its dependencies must be present in `publicFiles`. See the
+[README setup section](README.md#first-use-deterministic-setup-without-loading-the-full-report).
 
 An existing config is never regenerated or overwritten. A project with no
 discoverable GitHub/npm channel reports `LOCAL_ONLY_DETECTED` rather than

package/INSTALL.zh-CN.md

@@ -2,6 +2,7 @@
 
 [English](INSTALL.md)
 
+<!-- release-skill:release-version: 0.1.5 -->
 ## 前置条件
 
 - Node.js 22.0.0 或更高版本
@@ -9,9 +10,9 @@
 
 ## 从 npm 安装（推荐）
 
-v0.1.1 已公开发布并完成验证。对于 v0.1.3 这样的更新源码候选，只有当
-`npm view release-skill version` 返回该精确版本后才使用 npm 安装；在此之前请使用
-下文的源码检出方式。
+公开版本只有在不可变生产计划经过批准、发布并达到 `VERIFIED` 后才算完整。对于更新的
+源码检出，只有当 `npm view release-skill version` 返回该精确版本后才使用 npm 安装；
+在此之前请使用下文的源码检出方式。
 
 ```bash
 npm install -g release-skill
@@ -61,18 +62,67 @@ CLI=(node "$RELEASE_SKILL_HOME/packages/release-skill/bin/release-skill.mjs")
 "${CLI[@]}" help
 ```
 
-如果项目尚无 `.release-skill/project.yaml`，先只读发现事实和候选：
+如果项目尚无 `.release-skill/project.yaml`，把完整只读报告写入临时文件，只查看其中
+确定性的 `compactSummary`（紧凑摘要）：
 
 ```bash
-"${CLI[@]}" setup --root /path/to/your/project --json
+PROJECT=/path/to/your/project
+SETUP_SESSION="$(mktemp -d "${TMPDIR:-/tmp}/release-setup.XXXXXX")"
+REPORT="$SETUP_SESSION/discovery.json"
+ANSWERS="$SETUP_SESSION/answers.json"
+BOUND_REPORT="$SETUP_SESSION/bound.json"
+printf 'SETUP_SESSION=%s\nPROJECT=%s\n' "$SETUP_SESSION" "$PROJECT"
+
+"${CLI[@]}" setup --root "$PROJECT" --json > "$REPORT" || test "$?" -eq 2
+node -e 'const fs=require("node:fs");const r=JSON.parse(fs.readFileSync(process.argv[1],"utf8"));if(!r.compactSummary){console.error("compactSummary missing");process.exit(2)}process.stdout.write(JSON.stringify(r.compactSummary,null,2)+"\n")' "$REPORT"
 ```
 
-`NEEDS_INPUT` 和 `LOCAL_ONLY_DETECTED` 按设计返回退出码 2。它们表示待人工决策，不是
-内部崩溃；自动化应读取 JSON 的 `status`。
+紧凑摘要只是审阅视图，不是授权；`setupDigest` 仍绑定完整事实、候选和 answers。若
+`proposalConflicts` 非空，必须由人工修正冲突的仓库/映射权威事实后重跑 setup，不能
+猜测选边。没有冲突时，机械提取机器提案：
 
-人工审阅发布单元、旧 `public-release.json` 迁移提示、tag、分支策略、前序公开基线
-和 gate 候选。setup 不会自动执行发现到的脚本。建立完整 answers JSON，再运行一次
-dry-run（只读试运行），取得同时绑定当前事实与人工答案的摘要，然后只创建一次配置：
+```bash
+SETUP_SESSION='/上一步打印的会话目录绝对路径'
+PROJECT='/上一步打印的项目绝对路径'
+REPORT="$SETUP_SESSION/discovery.json"
+ANSWERS="$SETUP_SESSION/answers.json"
+BOUND_REPORT="$SETUP_SESSION/bound.json"
+node -e 'const fs=require("node:fs");const r=JSON.parse(fs.readFileSync(process.argv[1],"utf8"));if((r.proposalConflicts??[]).length){console.error("proposal conflicts require human resolution");process.exit(2)}if(!r.recommendedAnswers){console.error("recommendedAnswers missing");process.exit(2)}fs.writeFileSync(process.argv[2],JSON.stringify(r.recommendedAnswers,null,2)+"\n",{flag:"wx",mode:0o600})' "$REPORT" "$ANSWERS"
+"${CLI[@]}" setup --root "$PROJECT" --answers "$ANSWERS" --json > "$BOUND_REPORT"
+node -e 'const fs=require("node:fs");const r=JSON.parse(fs.readFileSync(process.argv[1],"utf8"));if(!r.compactSummary||!r.setupDigest){console.error("bound setup report incomplete");process.exit(2)}process.stdout.write(JSON.stringify({compactSummary:r.compactSummary,setupDigest:r.setupDigest},null,2)+"\n")' "$BOUND_REPORT"
+printf 'SETUP_SESSION=%s\nPROJECT=%s\n' "$SETUP_SESSION" "$PROJECT"
+```
+
+人工只确认一次绑定摘要和精确摘要值，然后使用已确认字面量首次创建。结果必须是
+`CONFIG_CREATED`；第二次 setup 必须是 `ALREADY_CONFIGURED`，随后运行 assess。
+
+```bash
+SETUP_SESSION=<上一步打印的会话目录绝对路径>
+PROJECT=<上一步打印的项目绝对路径>
+ANSWERS="$SETUP_SESSION/answers.json"
+CREATED_REPORT="$SETUP_SESSION/created.json"
+POST_REPORT="$SETUP_SESSION/post-setup.json"
+ASSESS_REPORT="$SETUP_SESSION/assess.json"
+"${CLI[@]}" setup --root "$PROJECT" --answers "$ANSWERS" \
+  --write --confirm-setup <已确认的 setupDigest> --json > "$CREATED_REPORT"
+"${CLI[@]}" setup --root "$PROJECT" --json > "$POST_REPORT"
+set +e
+"${CLI[@]}" assess --root "$PROJECT" --offline --json > "$ASSESS_REPORT"
+ASSESS_EXIT=$?
+set -e
+[ "$ASSESS_EXIT" -eq 0 ] || [ "$ASSESS_EXIT" -eq 1 ] || exit "$ASSESS_EXIT"
+node -e 'const fs=require("node:fs");const [c,p,a]=process.argv.slice(1).map(x=>JSON.parse(fs.readFileSync(x,"utf8")));if(c.status!=="CONFIG_CREATED"||p.status!=="ALREADY_CONFIGURED"||!["ASSESSED","NEEDS_INPUT","BLOCKED"].includes(a.status)){process.exit(2)}process.stdout.write(JSON.stringify({created:c.status,postSetup:p.status,assessment:{status:a.status,summary:a.summary,gapCount:(a.gaps??[]).length,blockingCodes:(a.gaps??[]).filter(g=>g.severity==="error").map(g=>g.code)}},null,2)+"\n")' "$CREATED_REPORT" "$POST_REPORT" "$ASSESS_REPORT"
+node -e 'require("node:fs").rmSync(process.argv[1],{recursive:true,force:false})' "$SETUP_SESSION"
+```
+
+解释器/包管理器间接脚本以 `SIDE_EFFECTS_UNPROVEN` 排除且默认不选。项目特有 hook/gate
+只能经人工审阅后增量注册：hook 编辑 `projectConfig.hooks`；gate 编辑
+`verificationGates` 并将同一 id 加入 `selectedGateIds`，然后重跑绑定 dry-run。人工文件使用 `mode: preserve`；显式跨单元共享源使用
+`sourceScope: workspace`。
+
+### 进阶 schema 参考——不是首次运行主路径
+
+下面的外壳只说明 schema。正常 setup 不应手写，而应机械提取 `recommendedAnswers`。
 
 ```json
 {
@@ -110,22 +160,10 @@ dry-run（只读试运行），取得同时绑定当前事实与人工答案的
 }
 ```
 
-这个外壳完整，但其中的值只是示例。仓库、渠道、基线与公开文件都必须替换为本项目
-经审阅的事实；只有确认不存在历史公开版本时才可使用 `mode: none`。
-
-选择已报告的 gate 时，把完整定义加入 `projectConfig.verificationGates`，并把同一 id
-复制进 `selectedGateIds`。id 必须来自当前 `gateCandidates`。snapshot gate 命令及
-全部依赖必须包含在 `publicFiles`；它看不到仅存在于父工作空间的测试、开发依赖或
-`node_modules`。完整的无 gate 与单 gate answers 示例见
-[README 首次接入章节](README.zh-CN.md#首次接入先发现再由人工定稿)。
-
-```bash
-"${CLI[@]}" setup --root /path/to/your/project \
-  --answers /path/to/setup-answers.json --json
-"${CLI[@]}" setup --root /path/to/your/project \
-  --answers /path/to/setup-answers.json \
-  --write --confirm-setup <setupDigest> --json
-```
+这个外壳仅供参考。正常 setup 必须使用机器提案；只有确认不存在历史公开版本时才可
+使用 `mode: none`。人工增量加入 gate 时，其 id 必须与 `selectedGateIds` 精确一致，
+snapshot gate 及其依赖必须存在于 `publicFiles`。详见
+[README 首次接入章节](README.zh-CN.md#首次接入不加载完整报告的确定性流程)。
 
 已有配置永远不会被重新生成或覆盖。无法发现 GitHub/npm 渠道的项目返回
 `LOCAL_ONLY_DETECTED`，不会冒充生产就绪。

package/README.md

@@ -2,6 +2,7 @@
 
 [简体中文](README.zh-CN.md) · Installation: [English](INSTALL.md) / [简体中文](INSTALL.zh-CN.md)
 
+<!-- release-skill:release-version: 0.1.5 -->
 Release preparation for Claude Code and Codex, with human-edited files kept intact.
 
 release-skill helps a maintainer answer three questions: what will be released,
@@ -10,21 +11,25 @@ reviewed artifacts first and publishes those same artifacts later; it does not
 regenerate a README or re-pack the live workspace at the last step.
 
 <!-- release-skill:capability:external-write-boundary -->
-> **Current boundary:** v0.1.1 completed a real production release to GitHub and
-> npm, followed by exact npm installation and Claude/Codex consumer installation
-> verification from the frozen Git ref. The same workflow also has a local
-> production-equivalent protocol suite using the real release-skill CLI and
-> frozen artifacts, local bare Git remotes, and protocol fakes for `gh`, `npm`,
-> Claude, and Codex. The suite does not provide OS-level network isolation, and
-> it does not prove that another project's credentials, permissions, rate limits,
-> or eventual-consistency behavior will match this release. Treat each project's
-> first production run as a monitored canary. `prepare --online` observes bound
-> previous-public baselines and fails closed on drift; remote uniqueness checks
-> run during publish global preflight.
+> **Current boundary:** v0.1.5 is the current release. v0.1.1 completed a real production release
+> to GitHub and npm — the first production-verified milestone — followed by
+> exact npm installation and Claude/Codex consumer installation verification
+> from the frozen Git ref; "current release" and "first production-verified
+> milestone" are two distinct facts and must not be conflated. The same
+> workflow also has a local production-equivalent protocol suite using the
+> real release-skill CLI and frozen artifacts, local bare Git remotes, and
+> protocol fakes for `gh`, `npm`, Claude, and Codex. The suite does not
+> provide OS-level network isolation, and it does not prove that another
+> project's credentials, permissions, rate limits, or eventual-consistency
+> behavior will match this release. Treat each project's first production run
+> as a monitored canary. `prepare --online` observes bound previous-public
+> baselines and fails closed on drift; remote uniqueness checks run during
+> publish global preflight.
 
 <!-- release-skill:capability:safe-first-command -->
-> **v0.1.1 production verified.** The npm-installed CLI is the supported user
-> entry. Source checkout is the development/contributor fallback.
+> **Production path verified since the v0.1.1 milestone; v0.1.5 is the current
+> release.** The npm-installed CLI is the supported user entry. Source checkout
+> is the development/contributor fallback.
 >
 > **Start here:**
 > - npm install: `npm install -g release-skill` → `release-skill help`
@@ -55,6 +60,13 @@ slogans, examples, prose, formatting, and later human edits.
   intervention; the tool does not force or overwrite them.
 - Only files listed in `publicFiles` are copied. Add translated READMEs, images,
   demos, and linked documents explicitly when they belong in the release.
+- A release freezes only the current truth: `prepare` never refreshes or
+  rewrites human docs. Maintainers update README, INSTALL, and CHANGELOG first
+  — including the machine-readable `release-skill:release-version` markers,
+  which must equal the `package.json` version, and the formal CHANGELOG
+  heading for the current version — then prepare, review, and approve. A
+  pre-release gate fails closed when any doc version marker or the CHANGELOG
+  current-version entry drifts.
 
 This is the preservation contract: **copy current truth, freeze reviewed
 truth, and never rewrite human truth.**
@@ -104,26 +116,81 @@ First keep local plans, approvals, and frozen artifacts out of Git:
 !.release-skill/project.yaml
 ```
 
-### First use: discover, then let a human finalize
+### First use: deterministic setup without loading the full report
 
-When the project has no configuration, start with read-only setup. It scans
-packages, plugin manifests, Git remotes, legacy `public-release.json`, and
-quality scripts. It reports release-unit, tag, branch, previous-baseline, and
-verification-gate candidates, but never treats README prose as instructions or
-automatically selects or executes a script:
+Setup is read-only by default. Keep its potentially large report in temporary
+files; show the user or Agent only the deterministic `compactSummary` review
+view. The summary does not replace authorization: `setupDigest` still binds the
+complete facts, candidates, and answers.
 
 ```bash
-release-skill setup --root /absolute/path/to/my-project --json
+PROJECT=/absolute/path/to/my-project
+SETUP_SESSION="$(mktemp -d "${TMPDIR:-/tmp}/release-setup.XXXXXX")"
+REPORT="$SETUP_SESSION/discovery.json"
+ANSWERS="$SETUP_SESSION/answers.json"
+BOUND_REPORT="$SETUP_SESSION/bound.json"
+printf 'SETUP_SESSION=%s\nPROJECT=%s\n' "$SETUP_SESSION" "$PROJECT"
+
+release-skill setup --root "$PROJECT" --json > "$REPORT" || test "$?" -eq 2
+node -e 'const fs=require("node:fs");const r=JSON.parse(fs.readFileSync(process.argv[1],"utf8"));if(!r.compactSummary){console.error("compactSummary missing");process.exit(2)}process.stdout.write(JSON.stringify(r.compactSummary,null,2)+"\n")' "$REPORT"
+```
+
+`NEEDS_INPUT` and `LOCAL_ONLY_DETECTED` intentionally exit with code 2. If
+`proposalConflicts` is non-empty—including `PUBLIC_REPO_AUTHORITY_CONFLICT` or
+a public-file mapping conflict—stop and let a human correct the conflicting
+repository or mapping authority, then rerun setup. Do not guess a winner.
+
+With no conflicts, copy the machine proposal mechanically. The Agent must not
+rewrite or transcribe it:
+
+```bash
+SETUP_SESSION='/session-directory-absolute-path-printed-above'
+PROJECT='/project-absolute-path-printed-above'
+REPORT="$SETUP_SESSION/discovery.json"
+ANSWERS="$SETUP_SESSION/answers.json"
+BOUND_REPORT="$SETUP_SESSION/bound.json"
+node -e 'const fs=require("node:fs");const r=JSON.parse(fs.readFileSync(process.argv[1],"utf8"));if((r.proposalConflicts??[]).length){console.error("proposal conflicts require human resolution");process.exit(2)}if(!r.recommendedAnswers){console.error("recommendedAnswers missing");process.exit(2)}fs.writeFileSync(process.argv[2],JSON.stringify(r.recommendedAnswers,null,2)+"\n",{flag:"wx",mode:0o600})' "$REPORT" "$ANSWERS"
+
+release-skill setup --root "$PROJECT" --answers "$ANSWERS" --json > "$BOUND_REPORT"
+node -e 'const fs=require("node:fs");const r=JSON.parse(fs.readFileSync(process.argv[1],"utf8"));if(!r.compactSummary||!r.setupDigest){console.error("bound setup report incomplete");process.exit(2)}process.stdout.write(JSON.stringify({compactSummary:r.compactSummary,setupDigest:r.setupDigest},null,2)+"\n")' "$BOUND_REPORT"
+printf 'SETUP_SESSION=%s\nPROJECT=%s\n' "$SETUP_SESSION" "$PROJECT"
 ```
 
-`NEEDS_INPUT` and `LOCAL_ONLY_DETECTED` intentionally exit with code 2. They
-are unresolved decision states, not a crash. Automation should inspect the JSON
-`status` instead of treating every nonzero setup result as an internal failure.
+Review that bound summary and exact digest once. After explicit human
+confirmation, use the confirmed digest literal to create the configuration:
 
-After review, create an answers JSON containing the complete `projectConfig`.
-Its `selectedGateIds` must exactly match `projectConfig.verificationGates[].id`;
-use an explicit empty array when no project-specific gate is selected. Dry-run
-again with those answers, review the new `setupDigest`, then create the config:
+```bash
+SETUP_SESSION=<session-directory-absolute-path-printed-above>
+PROJECT=<project-absolute-path-printed-above>
+ANSWERS="$SETUP_SESSION/answers.json"
+CREATED_REPORT="$SETUP_SESSION/created.json"
+POST_REPORT="$SETUP_SESSION/post-setup.json"
+ASSESS_REPORT="$SETUP_SESSION/assess.json"
+release-skill setup --root "$PROJECT" --answers "$ANSWERS" \
+  --write --confirm-setup <confirmed-setupDigest> --json > "$CREATED_REPORT"
+release-skill setup --root "$PROJECT" --json > "$POST_REPORT"
+set +e
+release-skill assess --root "$PROJECT" --offline --json > "$ASSESS_REPORT"
+ASSESS_EXIT=$?
+set -e
+[ "$ASSESS_EXIT" -eq 0 ] || [ "$ASSESS_EXIT" -eq 1 ] || exit "$ASSESS_EXIT"
+node -e 'const fs=require("node:fs");const [c,p,a]=process.argv.slice(1).map(x=>JSON.parse(fs.readFileSync(x,"utf8")));if(c.status!=="CONFIG_CREATED"||p.status!=="ALREADY_CONFIGURED"||!["ASSESSED","NEEDS_INPUT","BLOCKED"].includes(a.status)){process.exit(2)}process.stdout.write(JSON.stringify({created:c.status,postSetup:p.status,assessment:{status:a.status,summary:a.summary,gapCount:(a.gaps??[]).length,blockingCodes:(a.gaps??[]).filter(g=>g.severity==="error").map(g=>g.code)}},null,2)+"\n")' "$CREATED_REPORT" "$POST_REPORT" "$ASSESS_REPORT"
+node -e 'require("node:fs").rmSync(process.argv[1],{recursive:true,force:false})' "$SETUP_SESSION"
+```
+
+The write must return `CONFIG_CREATED`; the next setup must return
+`ALREADY_CONFIGURED`. Existing configuration is never regenerated—make only
+reviewed incremental edits. Discovered interpreter/package-manager scripts are
+`SIDE_EFFECTS_UNPROVEN` and are not selected automatically. Add a project-specific
+hook or gate only after human review: edit `projectConfig.hooks`, or edit
+`verificationGates` and add the same id to `selectedGateIds`, then rerun the
+bound dry-run. Keep human files at `mode: preserve`, and
+use `sourceScope: workspace` only for explicit cross-unit shared sources.
+
+#### Advanced schema reference—not the first-use path
+
+The wrapper below illustrates the schema only. Do not hand-write it during the
+normal setup path; mechanically extract `recommendedAnswers` as shown above.
 
 ```json
 {
@@ -161,15 +228,12 @@ again with those answers, review the new `setupDigest`, then create the config:
 }
 ```
 
-This is a complete schema-shaped wrapper, not authoritative project data.
-Replace every repository, channel, baseline, and public-file decision with the
-reviewed facts from your project; use `mode: none` only when no public version
-exists.
+This is a schema reference, not an onboarding template. Normal setup must use
+the machine proposal. `mode: none` is valid only when no public version exists.
 
-To select one reported gate, keep the same complete `projectConfig`, add a
-top-level `verificationGates` array inside it, and make the wrapper's
-`selectedGateIds` identical. For example, when dry-run reported
-`my-project-script-test`:
+The following reference shows the exact relationship between a manually
+reviewed gate and `selectedGateIds`. Apply that relationship only as an
+incremental edit to the extracted machine proposal:
 
 ```json
 {
@@ -407,8 +471,8 @@ publication. The source checkout remains the development/contributor fallback.
    ```bash
    "${CLI[@]}" setup --root "$PROJECT" --json
    ```
-   Complete the answers and exact `setupDigest` confirmation described above;
-   skip this step when configuration already exists.
+   Follow the mechanical `compactSummary` and `recommendedAnswers` path above;
+   confirm the bound `setupDigest` once, and skip this step when configuration exists.
 3. **Readiness assessment (read-only):**
    ```bash
    "${CLI[@]}" assess --root "$PROJECT" --offline --json
@@ -562,10 +626,12 @@ releaseUnits:
         plugin: my-plugin
         marketplace: my-plugin
         entrySkill: my-plugin-help
+        timeoutMs: 300000     # optional; range 30000-900000; default 300000
       - type: codex-plugin
         plugin: my-plugin
         marketplace: my-plugin
         entrySkill: my-plugin-help
+        timeoutMs: 300000     # optional; range 30000-900000; default 300000
     publicFiles:
       - from: packages/plugin/.claude-plugin/plugin.json
         to: .claude-plugin/plugin.json
@@ -612,6 +678,14 @@ the entry Skill, and all required public files. A CLI smoke (`smokeBin`) is
 optional for plugin units and only applies when the published npm package
 exposes a CLI binary.
 
+Plugin distributions may declare `timeoutMs` (range 30,000--900,000 ms; default
+300,000 ms). This sets the subprocess timeout for the marketplace add, plugin
+install, and plugin list commands. On real networks these commands can take
+40--105 seconds; the default 300-second timeout avoids false `PARTIAL` failures.
+The resolved value is frozen into the plan and approved along with all other
+action parameters. Old plans without `timeoutMs` default to 300,000 ms at
+execution time for backward compatibility.
+
 ### PARTIAL recovery and reconcile
 
 When `publish` succeeds at some checkpoints but fails at others, the run enters