@kyo-so/cli 0.13.0 → 0.14.0

package/.agents/skills/kyoso-review/SKILL.md

@@ -39,8 +39,9 @@ Do not use this skill for every coding task. It is intended for deliberate revie
    - If the typed contract contains non-goals or accepted risks and MCP is unavailable, stop and explain that the CLI fallback cannot preserve those trusted fields. A focus-only contract may use the CLI fallback.
    - If the MCP tools are unavailable, use the first available CLI path with JSON output:
      1. An installed `kyoso` executable on `PATH`.
-     2. `npx -y @kyo-so/cli`.
-     3. `bunx @kyo-so/cli`.
+     2. `npx -y --package=@kyo-so/cli kyoso`.
+     3. `bunx --package @kyo-so/cli kyoso`.
+     - The Bun fallback requires a Bun version that supports `bunx --package`; if it does not, return to the npx or PATH fallback.
    - Append the review command to the selected CLI path:
      - `plan_review` -> `plan --goal <text> [--plan <path-or-text>] [--file <path>] --json`
      - `security_review` -> `security --goal <text> [--diff <path>] [--file <path>] --json`

package/CHANGELOG.md

@@ -7,6 +7,41 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.14.0] - 2026-07-19
+
+### Changed
+
+- Promote the Marketplace Plugin to `0.7.2` and make its Codex and Claude Code
+  MCP definitions explicitly launch the `kyoso` executable from
+  `@kyo-so/cli@0.13.1`, avoiding ambiguous npm executable inference.
+- Align new manual MCP setup, Skill fallbacks, documentation, and client
+  examples with explicit npx/bunx package-and-executable commands. Existing
+  custom, execution-altering environment, or unknown registrations remain
+  untouched; `--write --force` migrates a safe exact legacy npx command. Legacy
+  bunx is preserved without a `--runner` and requires explicit `--runner bunx`
+  verification or intentional `--runner npx` migration. Current bunx
+  registrations can be capability-checked without changing their bytes.
+- Add local multi-bin package smoke, exact published npx/bunx artifact smoke,
+  PATH-sentinel fallback detection, and fail-closed promotion verification with
+  rollback after a post-write failure. These durable CLI changes ship with the
+  next CLI release; they do not retroactively alter the already-recovered
+  Plugin `0.7.2` artifact.
+
+## [0.13.1] - 2026-07-17
+
+### Changed
+
+- Update `@modelcontextprotocol/server` from `2.0.0-beta.3` to
+  `2.0.0-beta.4`, adopting the shared `@modelcontextprotocol/core` runtime
+  dependency and lazy validation-schema construction.
+- Update the default `@agentclientprotocol/claude-agent-acp` adapter from
+  `0.58.1` to `0.59.0` for background-subagent lifetime handling, result-text
+  forwarding, and refined streamed tool calls.
+- Promote the Marketplace Plugin to `0.7.0` and pin its Codex and Claude Code
+  MCP definitions to `@kyo-so/cli@0.13.0`, delivering output-budget
+  recalibration, execution identity reporting, shared deadlines, and bounded
+  ACP transport through the Plugin runtime.
+
 ## [0.13.0] - 2026-07-17
 
 ### Added

package/README.ja.md

@@ -92,8 +92,8 @@ Plugin は Kyoso review Skill と、公開済み CLI version に pin したロ
 3. または、MCP を登録して review skill をインストールします。
 
 ```bash
-npx @kyo-so/cli setup claude-code --write
-bunx @kyo-so/cli setup claude-code --write
+npx -y --package=@kyo-so/cli kyoso setup claude-code --write
+bunx --package @kyo-so/cli kyoso setup claude-code --write
 ```
 
 手動で MCP を登録する場合は、`examples/claude-code-mcp.json` を使用します。
@@ -101,8 +101,8 @@ bunx @kyo-so/cli setup claude-code --write
 4. セットアップを確認します。
 
 ```bash
-npx @kyo-so/cli doctor
-bunx @kyo-so/cli doctor
+npx -y --package=@kyo-so/cli kyoso doctor
+bunx --package @kyo-so/cli kyoso doctor
 ```
 
 5. Claude Code からレビューを依頼します。
@@ -133,15 +133,15 @@ Codex Auto modeでは、approvalが必要なKyoso toolの呼び出しが拒否
 3. または、MCP を登録して review skill をインストールします。
 
 ```bash
-npx @kyo-so/cli setup codex --write
-bunx @kyo-so/cli setup codex --write
+npx -y --package=@kyo-so/cli kyoso setup codex --write
+bunx --package @kyo-so/cli kyoso setup codex --write
 ```
 
 4. セットアップを確認します。
 
 ```bash
-npx @kyo-so/cli doctor
-bunx @kyo-so/cli doctor
+npx -y --package=@kyo-so/cli kyoso doctor
+bunx --package @kyo-so/cli kyoso doctor
 ```
 
 5. Codex からレビューを依頼します。
@@ -154,7 +154,9 @@ Use Kyoso diff_review on the current diff. I need a second opinion before mergin
 
 ## CLI
 
-通常の実行経路は `npx @kyo-so/cli` と `bunx @kyo-so/cli` です。以下の例では、この prefix を `kyoso` と省略しています。Naming note: npm パッケージは `@kyo-so/cli` (製品名 Kyo-so に対応) で、インストールされる CLI コマンドは短い `kyoso` です。
+package-runner の実行経路では、package と executable を必ず別指定します: `npx -y --package=@kyo-so/cli kyoso` と `bunx --package @kyo-so/cli kyoso` です。workflowで固定する場合は、`@kyo-so/cli@0.13.1` のようにpackage名へcomplete SemVer pinを付けます。以下の例の `kyoso` は、すでにインストールされた executable の省略形です。Naming note: npm パッケージは `@kyo-so/cli` (製品名 Kyo-so に対応) で、インストールされる CLI コマンドは短い `kyoso` です。
+
+Bun fallback は Bun `1.3.14` で検証済みです。古い Bun では npx 形式またはインストール済みの `kyoso` を使い、複数bin packageからの Bun のbinary推論に依存しないでください。
 
 ```bash
 kyoso plan --goal "Review this OAuth callback plan" --plan plan.md
@@ -198,7 +200,7 @@ Kyoso を Codex または Claude Code の MCP server として登録し、client
 # See examples/codex-config.toml
 [mcp_servers.kyoso]
 command = "npx"
-args = ["-y", "@kyo-so/cli", "mcp", "--network", "model_only"]
+args = ["-y", "--package=@kyo-so/cli", "kyoso", "mcp"]
 ```
 
 client request の例:
@@ -210,8 +212,8 @@ Use Kyoso plan_review on this plan and the selected auth files. I need a second
 ## MCP
 
 ```bash
-npx @kyo-so/cli mcp --network model_only
-bunx @kyo-so/cli mcp --network model_only
+npx -y --package=@kyo-so/cli kyoso mcp --network model_only
+bunx --package @kyo-so/cli kyoso mcp --network model_only
 ```
 
 `--network` を省略すると、Kyoso は `model_only` を使用します。これは Kyoso が backend agents からの通信を model-provider traffic のみにすることを期待する policy-level constraint です。OS-level network isolation ではありません。
@@ -228,13 +230,19 @@ MCP stdout は protocol messages 専用です。logs は stderr または local
 
 同梱の `kyoso-review` skill は意図的に狭い用途にしています。Kyoso、multi-agent review、plan review、security review、CISA Secure by Design review、diff review を明示的に依頼したときだけ trigger されるべきです。
 
-Skillは利用可能な最初の経路を使います。順序はKyoso MCP tools、PATH上のインストール済み`kyoso`、`npx -y @kyo-so/cli`、`bunx @kyo-so/cli`です。package runner fallbackはnetwork accessが必要になり、version driftも起こり得るため、MCPなしの通常経路にはインストール済みCLIを使います。typed [review contract](#review-contract-と-finding-admission) にnon-goalsまたはaccepted risksがありMCPを利用できない場合、CLI fallbackは`focus`しか保持できないためSkillは停止します。
+Skillは利用可能な最初の経路を使います。順序はKyoso MCP tools、PATH上のインストール済み`kyoso`、`npx -y --package=@kyo-so/cli kyoso`、`bunx --package @kyo-so/cli kyoso`です。package runner fallbackはnetwork accessが必要になり、pinなしでは新しいreleaseへ解決され得るため、MCPなしの通常経路にはインストール済みCLIを使います。typed [review contract](#review-contract-と-finding-admission) にnon-goalsまたはaccepted risksがありMCPを利用できない場合、CLI fallbackは`focus`しか保持できないためSkillは停止します。
 
 `kyoso setup codex --write --skill-only`はcanonical Skill directoryを既定で`.agents/skills/kyoso-review/`へコピーします。`--global`を追加すると`~/.agents/skills/kyoso-review/`へコピーします。
 
 `kyoso setup claude-code --write --skill-only`は既定で`.claude/skills/kyoso-review/`へコピーします。`--global`を追加すると`~/.claude/skills/kyoso-review/`へコピーします。
 
-managed installはcanonical directoryのdigestとCLI versionを`.kyoso-install.json`へ記録します。現行または既知historical copyはadoptして自動更新します。変更済み／未知のcopyはconflictとして残し、上書きしません。`--force`はそのSkill directoryだけを置換し、MCP設定を削除・上書きしません。
+managed installはcanonical directoryのdigestとCLI versionを`.kyoso-install.json`へ記録します。現行または既知historical copyはadoptして自動更新します。変更済み／未知のcopyはconflictとして残し、上書きしません。`--force`はそのmanaged Skillを置換できます。manual MCPに対する例外は次節の限定移行だけであり、custom／unknown登録、選択した安全な対象外のglobal／nested登録、Marketplace Plugin／cacheは変更しません。
+
+### 手動 MCP の移行
+
+最初に `kyoso setup codex` または `kyoso setup claude-code` を実行し、既存登録を確認します。dry-run と `--write` は既存の MCP entry をすべて保持します。`--write --force` は生成時allowlist内のenvを持つ認識済み完全一致 legacy npx Kyoso commandを、上記のpackageとexecutableを分離した形式へ移行します。完全一致 legacy bunx command は `--runner` を省略するとprobeせず保持します。`--write --runner bunx --force` は Bun を検証して明示bunx形式へ移行し、`--write --runner npx --force` は意図的にnpx形式へ移行します。いずれもlegacy commandにcomplete SemVer pinがあった場合は保持します。currentの明示bunx登録は`--write --runner bunx`で確認でき、setupは登録bytesを変えずにBunを検証します。
+
+`--force` が対象にできるのは managed Skill の置換と、上記runner policyに従う安全な完全一致 legacy MCP entry の移行だけです。`NODE_OPTIONS`などexecutionを変え得るenv、custom `--command` entry、unknown structure、選択対象外の global / nested registration、Marketplace Plugin / cache は変更しません。`kyoso doctor` は保持したentryを ready とせず、`legacy`、`custom-unverified`、`unknown` として表示します。examplesを使って手動修復してから doctor を再実行してください。
 
 ## Review contract と finding admission
 
@@ -537,7 +545,7 @@ Windows、および必要なfilesystem capabilityを証明できない環境で
 ## Troubleshooting
 
 - MCP timeout: client timeoutはreview-wide deadlineより長くしてください。35分presetではCodexに2160秒、Claude Codeに`MCP_TOOL_TIMEOUT=2160000`を設定します。[Timeouts](#timeouts)を参照してください。
-- Fresh npm release: safe-chain などの minimum-package-age protection により、publish 直後は `npx @kyo-so/cli` の解決が一時的に block される場合があります。
+- Fresh npm release: safe-chain などの minimum-package-age protection により、publish 直後は `npx -y --package=@kyo-so/cli@<version> kyoso` が一時的に block される場合があります。`latest` や ambient `kyoso` へfallbackせず、その exact version を待ってください。
 - Deprecated TypeScript config: `--trust-config` を渡さない限り、untrusted `kyoso.config.ts` は skip されます。新規設定は `kyoso.toml` を使ってください。
 - OpenRouter key missing: 空でないCodex `model`、Kyoso processへ転送された`OPENROUTER_API_KEY`、clientの再起動を確認し、`kyoso doctor`を実行してください。Marketplace Plugin `0.4.0`以降はこの変数名をKyoso processへ転送し、それ以前のversionは転送しません。既存MCP registrationはsetupで再書換えされません。
 

package/README.md

@@ -90,8 +90,8 @@ The Plugin installs the Kyoso review Skill and a local stdio MCP server pinned t
 3. Alternatively, register MCP and install the review skill.
 
 ```bash
-npx @kyo-so/cli setup claude-code --write
-bunx @kyo-so/cli setup claude-code --write
+npx -y --package=@kyo-so/cli kyoso setup claude-code --write
+bunx --package @kyo-so/cli kyoso setup claude-code --write
 ```
 
 For manual MCP registration, use `examples/claude-code-mcp.json`.
@@ -99,8 +99,8 @@ For manual MCP registration, use `examples/claude-code-mcp.json`.
 4. Verify the setup.
 
 ```bash
-npx @kyo-so/cli doctor
-bunx @kyo-so/cli doctor
+npx -y --package=@kyo-so/cli kyoso doctor
+bunx --package @kyo-so/cli kyoso doctor
 ```
 
 5. Ask for a review from Claude Code.
@@ -131,15 +131,15 @@ Codex Auto mode may reject Kyoso tool calls that require approval. To pre-approv
 3. Alternatively, register MCP and install the review skill.
 
 ```bash
-npx @kyo-so/cli setup codex --write
-bunx @kyo-so/cli setup codex --write
+npx -y --package=@kyo-so/cli kyoso setup codex --write
+bunx --package @kyo-so/cli kyoso setup codex --write
 ```
 
 4. Verify the setup.
 
 ```bash
-npx @kyo-so/cli doctor
-bunx @kyo-so/cli doctor
+npx -y --package=@kyo-so/cli kyoso doctor
+bunx --package @kyo-so/cli kyoso doctor
 ```
 
 5. Ask for a review from Codex.
@@ -152,7 +152,9 @@ Manual setup examples are kept in `examples/codex-config.toml` and `examples/cla
 
 ## CLI
 
-`npx @kyo-so/cli` and `bunx @kyo-so/cli` are the normal execution paths. The examples below abbreviate that prefix as `kyoso`. Naming note: the npm package is `@kyo-so/cli` (matching the product name Kyo-so), while the installed CLI command is the shorter `kyoso`.
+The package-runner execution paths always select the package and executable separately: `npx -y --package=@kyo-so/cli kyoso` and `bunx --package @kyo-so/cli kyoso`. Add a complete SemVer pin after the package name when a workflow needs one, for example `@kyo-so/cli@0.13.1`. The examples below abbreviate an already installed executable as `kyoso`. Naming note: the npm package is `@kyo-so/cli` (matching the product name Kyo-so), while the installed CLI command is the shorter `kyoso`.
+
+The Bun fallback is verified on Bun `1.3.14`. On an older Bun, use the npx form or an installed `kyoso`; do not rely on Bun inferring a binary from a multi-bin package.
 
 ```bash
 kyoso plan --goal "Review this OAuth callback plan" --plan plan.md
@@ -196,7 +198,7 @@ Register Kyoso with Codex or Claude Code as an MCP server, then call `plan_revie
 # See examples/codex-config.toml
 [mcp_servers.kyoso]
 command = "npx"
-args = ["-y", "@kyo-so/cli", "mcp", "--network", "model_only"]
+args = ["-y", "--package=@kyo-so/cli", "kyoso", "mcp"]
 ```
 
 Example client request:
@@ -208,8 +210,8 @@ Use Kyoso plan_review on this plan and the selected auth files. I need a second
 ## MCP
 
 ```bash
-npx @kyo-so/cli mcp --network model_only
-bunx @kyo-so/cli mcp --network model_only
+npx -y --package=@kyo-so/cli kyoso mcp --network model_only
+bunx --package @kyo-so/cli kyoso mcp --network model_only
 ```
 
 When `--network` is omitted, Kyoso uses `model_only`. This means Kyoso expects only model-provider traffic from backend agents. It is a policy-level constraint, not OS-level network isolation.
@@ -226,13 +228,19 @@ MCP stdout is reserved for protocol messages. Logs go to stderr or local audit t
 
 The bundled `kyoso-review` skill is intentionally narrow. It should trigger only when you explicitly ask for Kyoso, multi-agent review, plan review, security review, CISA Secure by Design review, or diff review.
 
-The Skill uses the first available path: Kyoso MCP tools, an installed `kyoso` on `PATH`, `npx -y @kyo-so/cli`, then `bunx @kyo-so/cli`. The package-runner fallbacks may need network access and can drift to a newer version, so an installed CLI is the normal MCP-less path. If a typed [review contract](#review-contract-and-finding-admission) contains non-goals or accepted risks and MCP is unavailable, the Skill stops because the CLI fallback can preserve only `focus`.
+The Skill uses the first available path: Kyoso MCP tools, an installed `kyoso` on `PATH`, `npx -y --package=@kyo-so/cli kyoso`, then `bunx --package @kyo-so/cli kyoso`. The package-runner fallbacks may need network access and can resolve a newer unpinned release, so an installed CLI is the normal MCP-less path. If a typed [review contract](#review-contract-and-finding-admission) contains non-goals or accepted risks and MCP is unavailable, the Skill stops because the CLI fallback can preserve only `focus`.
 
 `kyoso setup codex --write --skill-only` copies the canonical Skill directory to `.agents/skills/kyoso-review/` by default. Add `--global` to copy it to `~/.agents/skills/kyoso-review/`.
 
 `kyoso setup claude-code --write --skill-only` copies it to `.claude/skills/kyoso-review/` by default. Add `--global` to copy it to `~/.claude/skills/kyoso-review/`.
 
-Managed installs record the canonical directory digest and CLI version in `.kyoso-install.json`. Exact current or known historical copies are adopted and updated automatically. A changed or unknown copy is reported as a conflict and left untouched; `--force` replaces only that Skill directory and never removes or overwrites MCP configuration.
+Managed installs record the canonical directory digest and CLI version in `.kyoso-install.json`. Exact current or known historical copies are adopted and updated automatically. A changed or unknown copy is reported as a conflict and left untouched; `--force` can replace that managed Skill. Its only manual-MCP exception is the limited migration below: it never rewrites custom or unknown registrations, global/nested registrations outside the selected safe target, or Marketplace Plugin/cache entries.
+
+### Manual MCP migration
+
+Run `kyoso setup codex` or `kyoso setup claude-code` first to inspect the existing registration. Dry-run and `--write` preserve every existing MCP entry. `--write --force` migrates an exact recognized legacy npx Kyoso command with a generated-safe environment to the explicit package-and-executable form shown above. For an exact legacy bunx command, omitting `--runner` preserves it without probing; use `--write --runner bunx --force` to verify Bun and migrate it to explicit bunx, or `--write --runner npx --force` to intentionally migrate it to npx. Each migration keeps a complete SemVer pin when the legacy command had one. A current explicit bunx registration can be checked with `--write --runner bunx`; setup verifies Bun without changing the registration bytes.
+
+`--force` can replace a managed Skill and migrate only the safe exact legacy MCP entries under the runner policy above. It never changes an entry with execution-altering environment fields such as `NODE_OPTIONS`, a custom `--command` entry, an unknown structure, global or nested registrations outside the selected safe target, or a Marketplace Plugin/cache. `kyoso doctor` reports preserved entries as `legacy`, `custom-unverified`, or `unknown` rather than ready; repair those entries manually from the examples, then rerun doctor.
 
 ## Review contract and finding admission
 
@@ -535,7 +543,7 @@ Windows, and environments where the required filesystem capabilities cannot be p
 ## Troubleshooting
 
 - MCP timeout: keep the client timeout longer than the review-wide deadline. For the 35-minute preset, use 2160 seconds in Codex or `MCP_TOOL_TIMEOUT=2160000` in Claude Code. See [Timeouts](#timeouts).
-- Fresh npm release: minimum-package-age protection in tools such as safe-chain may briefly block `npx @kyo-so/cli` resolution after publish.
+- Fresh npm release: minimum-package-age protection in tools such as safe-chain may briefly block `npx -y --package=@kyo-so/cli@<version> kyoso` after publish. Wait for the exact version instead of falling back to `latest` or an ambient `kyoso`.
 - Deprecated TypeScript config: untrusted `kyoso.config.ts` is skipped unless you pass `--trust-config`; prefer `kyoso.toml`.
 - OpenRouter key missing: confirm a non-empty Codex `model`, an `OPENROUTER_API_KEY` forwarded to the Kyoso process, and a restarted client; run `kyoso doctor`. Marketplace Plugin `0.4.0` and later forward this variable name to the Kyoso process; earlier versions do not. Existing MCP registrations are not rewritten by setup.
 

package/README.zh-CN.md

@@ -92,8 +92,8 @@ Plugin 会安装 Kyoso review Skill 和 pin 到已发布 CLI version 的本地 s
 3. 或者，注册 MCP 并安装 review skill。
 
 ```bash
-npx @kyo-so/cli setup claude-code --write
-bunx @kyo-so/cli setup claude-code --write
+npx -y --package=@kyo-so/cli kyoso setup claude-code --write
+bunx --package @kyo-so/cli kyoso setup claude-code --write
 ```
 
 需要手动注册 MCP 时，请使用 `examples/claude-code-mcp.json`。
@@ -101,8 +101,8 @@ bunx @kyo-so/cli setup claude-code --write
 4. 验证 setup。
 
 ```bash
-npx @kyo-so/cli doctor
-bunx @kyo-so/cli doctor
+npx -y --package=@kyo-so/cli kyoso doctor
+bunx --package @kyo-so/cli kyoso doctor
 ```
 
 5. 从 Claude Code 请求 review。
@@ -133,15 +133,15 @@ codex plugin add kyoso@kyoso
 3. 或者，注册 MCP 并安装 review skill。
 
 ```bash
-npx @kyo-so/cli setup codex --write
-bunx @kyo-so/cli setup codex --write
+npx -y --package=@kyo-so/cli kyoso setup codex --write
+bunx --package @kyo-so/cli kyoso setup codex --write
 ```
 
 4. 验证 setup。
 
 ```bash
-npx @kyo-so/cli doctor
-bunx @kyo-so/cli doctor
+npx -y --package=@kyo-so/cli kyoso doctor
+bunx --package @kyo-so/cli kyoso doctor
 ```
 
 5. 从 Codex 请求 review。
@@ -154,7 +154,9 @@ Use Kyoso diff_review on the current diff. I need a second opinion before mergin
 
 ## CLI
 
-`npx @kyo-so/cli` 和 `bunx @kyo-so/cli` 是正常执行路径。下面的示例将此前缀简写为 `kyoso`。Naming note: npm package 是 `@kyo-so/cli` (对应产品名 Kyo-so)，安装后的 CLI command 是更短的 `kyoso`。
+package-runner 执行路径始终分别指定 package 和 executable：`npx -y --package=@kyo-so/cli kyoso` 与 `bunx --package @kyo-so/cli kyoso`。需要固定 workflow 时，在 package 名后加 complete SemVer pin，例如 `@kyo-so/cli@0.13.1`。下面的示例把已安装 executable 简写为 `kyoso`。Naming note: npm package 是 `@kyo-so/cli` (对应产品名 Kyo-so)，安装后的 CLI command 是更短的 `kyoso`。
+
+Bun fallback 已在 Bun `1.3.14` 上验证。旧版 Bun 请使用 npx 形式或已安装的 `kyoso`，不要依赖 Bun 从多 bin package 推断 binary。
 
 ```bash
 kyoso plan --goal "Review this OAuth callback plan" --plan plan.md
@@ -198,7 +200,7 @@ kyoso security \
 # See examples/codex-config.toml
 [mcp_servers.kyoso]
 command = "npx"
-args = ["-y", "@kyo-so/cli", "mcp", "--network", "model_only"]
+args = ["-y", "--package=@kyo-so/cli", "kyoso", "mcp"]
 ```
 
 client request 示例：
@@ -210,8 +212,8 @@ Use Kyoso plan_review on this plan and the selected auth files. I need a second
 ## MCP
 
 ```bash
-npx @kyo-so/cli mcp --network model_only
-bunx @kyo-so/cli mcp --network model_only
+npx -y --package=@kyo-so/cli kyoso mcp --network model_only
+bunx --package @kyo-so/cli kyoso mcp --network model_only
 ```
 
 省略 `--network` 时，Kyoso 使用 `model_only`。这意味着 Kyoso 期望 backend agents 只产生 model-provider traffic。这是 policy-level constraint，不是 OS-level network isolation。
@@ -228,13 +230,19 @@ MCP stdout 专用于 protocol messages。Logs 会写到 stderr 或 local audit t
 
 内置的 `kyoso-review` skill 有意保持范围很窄。只有当你明确请求 Kyoso、multi-agent review、plan review、security review、CISA Secure by Design review 或 diff review 时，才应触发它。
 
-Skill使用第一个可用路径，顺序是Kyoso MCP tools、PATH上已安装的`kyoso`、`npx -y @kyo-so/cli`、`bunx @kyo-so/cli`。package runner fallback可能需要network access，也可能发生version drift，因此MCP-less正常路径应使用已安装CLI。如果 typed [review contract](#review-contract-与-finding-admission) 包含non-goals或accepted risks且MCP不可用，CLI fallback只能保留`focus`，因此Skill会停止。
+Skill使用第一个可用路径，顺序是Kyoso MCP tools、PATH上已安装的`kyoso`、`npx -y --package=@kyo-so/cli kyoso`、`bunx --package @kyo-so/cli kyoso`。package runner fallback可能需要network access，且未 pin 时可能解析到更新 release，因此MCP-less正常路径应使用已安装CLI。如果 typed [review contract](#review-contract-与-finding-admission) 包含non-goals或accepted risks且MCP不可用，CLI fallback只能保留`focus`，因此Skill会停止。
 
 `kyoso setup codex --write --skill-only`默认将canonical Skill directory复制到`.agents/skills/kyoso-review/`。添加`--global`后复制到`~/.agents/skills/kyoso-review/`。
 
 `kyoso setup claude-code --write --skill-only`默认复制到`.claude/skills/kyoso-review/`。添加`--global`后复制到`~/.claude/skills/kyoso-review/`。
 
-managed install会把canonical directory digest和CLI version记录到`.kyoso-install.json`。当前或已知historical copy会被adopt并自动更新；修改过或未知的copy会报告conflict并保持不变。`--force`只替换该Skill directory，不会删除或覆盖MCP配置。
+managed install会把canonical directory digest和CLI version记录到`.kyoso-install.json`。当前或已知historical copy会被adopt并自动更新；修改过或未知的copy会报告conflict并保持不变。`--force`可以替换该managed Skill。它对manual MCP的唯一例外是下文的有限迁移：绝不会重写custom或unknown注册、所选安全目标之外的global／nested注册，或Marketplace Plugin／cache。
+
+### 手动 MCP 迁移
+
+先运行 `kyoso setup codex` 或 `kyoso setup claude-code` 检查现有注册。dry-run 与 `--write` 会保留所有现有 MCP entry。`--write --force` 会把环境字段限于生成时allowlist的完全匹配 legacy npx Kyoso command迁移为上文的显式package-and-executable形式。对于完全匹配的 legacy bunx command，省略 `--runner` 会保留它且不执行probe；使用 `--write --runner bunx --force` 可验证 Bun 并迁移为显式 bunx，或使用 `--write --runner npx --force` 有意迁移为 npx。每种迁移都会保留 legacy command 中的 complete SemVer pin。对于当前的显式bunx注册，可运行`--write --runner bunx`；setup会验证Bun且不改变注册bytes。
+
+`--force` 只能替换 managed Skill，并按上述runner policy迁移安全且完全匹配的 legacy MCP entry。它绝不会修改`NODE_OPTIONS`等可能改变execution的env、custom `--command` entry、unknown structure、所选安全目标之外的 global / nested registration，或 Marketplace Plugin / cache。`kyoso doctor` 不会把保留的 entry 标记为 ready，而会显示为 `legacy`、`custom-unverified` 或 `unknown`；请依据 examples 手动修复后再运行 doctor。
 
 ## Review contract 与 finding admission
 
@@ -537,7 +545,7 @@ Windows，以及无法证明所需 filesystem capability 的环境，会 fail-cl
 ## Troubleshooting
 
 - MCP timeout: client timeout应长于review-wide deadline。35分钟preset在Codex中使用2160秒，在Claude Code中使用`MCP_TOOL_TIMEOUT=2160000`。请参阅[Timeouts](#timeouts)。
-- Fresh npm release: safe-chain 等 minimum-package-age protection 可能会在 publish 后短时间内 block `npx @kyo-so/cli` resolution。
+- Fresh npm release: safe-chain 等 minimum-package-age protection 可能会在 publish 后短时间内 block `npx -y --package=@kyo-so/cli@<version> kyoso`。请等待该 exact version，不要 fallback 到 `latest` 或 ambient `kyoso`。
 - Deprecated TypeScript config: 除非传入 `--trust-config`，否则 untrusted `kyoso.config.ts` 会被 skip；新配置请使用 `kyoso.toml`。
 - OpenRouter key missing: 确认 Codex `model` 非空、`OPENROUTER_API_KEY` 已 forward 给 Kyoso process，并已重启 client；再运行 `kyoso doctor`。Marketplace Plugin `0.4.0` 及更高版本会将此变量名 forward 给 Kyoso process，旧版本不会。setup 也不会重写已有 MCP registration。