@kyo-so/cli 0.16.8 → 0.16.10

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

@@ -39,8 +39,8 @@ 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 --package=@kyo-so/cli kyoso`.
-     3. `bunx --package @kyo-so/cli kyoso`.
+     2. `npx -y --package=kyoso-cli@npm:@kyo-so/cli kyoso`.
+     3. `bunx --package kyoso-cli@npm:@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`

package/CHANGELOG.md

@@ -7,6 +7,61 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.16.10] - 2026-08-24
+
+### Changed
+
+- Update the default Codex ACP adapter to
+  `@agentclientprotocol/codex-acp@1.6.2`.
+- Update `@agentclientprotocol/sdk` to `1.4.0`.
+- Update the CI and package toolchain to Bun and `@types/bun` `1.4.0`.
+- Select the CLI package through the npm alias `kyoso-cli@npm:@kyo-so/cli` in
+  every package-runner path: generated `kyoso setup` registrations, Marketplace
+  Plugin MCP definitions, Skill CLI fallbacks, manual-registration examples,
+  and documentation. Without the alias, a package runner invoked from a
+  checkout whose own package name is `@kyo-so/cli` can resolve that workspace
+  instead of the published package — which is what happens when Kyoso is used
+  to review Kyoso. Existing unaliased registrations are unaffected: the
+  explicit package-and-executable form stays `current` with or without the
+  alias, so nothing is demoted and setup preserves those entries. An available
+  npx registration remains `ready`; a bunx registration remains `unverified`
+  until its Bun capability is verified by setup. `kyoso doctor` adds a warning
+  naming the aliased spec to write, carrying over a complete SemVer pin when
+  the registration has one; applying it is a hand edit. During the upgrade
+  window the reverse also holds: an aliased registration written by hand from
+  the updated examples is reported as `custom/unverified` by a doctor that
+  predates the alias. Upgrade the CLI before rerunning doctor.
+- Extract the Plugin CLI pin from the aliased argv in
+  `.github/workflows/release.yml`, matching the alias adopted above.
+- Promote the Marketplace Plugin to `0.7.18` and pin its Codex and Claude Code
+  MCP definitions and Skill fallbacks to `@kyo-so/cli@0.16.9`.
+
+### Removed
+
+- Remove the tracked `.codex/config.toml`. Its project-local
+  `mcp_servers.kyoso` entry silently took precedence over the installed Plugin
+  and over a maintainer's own MCP registration, so every dogfooding review ran
+  an unintended runtime. That entry also resolved the CLI through `@latest`
+  rather than an exact pin and passed
+  `--safe-chain-skip-minimum-package-age`, waiving the minimum-package-age
+  check. Forwarding the generated credential set is normal for a Kyoso MCP
+  entry; what this project's own documentation tells users to avoid is handing
+  that set to an unpinned, age-check-waived resolution. `.gitignore` now covers
+  `.codex/` and a project-root `.mcp.json` — the Claude Code equivalent, which
+  shadows the Plugin the same way — so a local copy of either stays out of
+  `git add`.
+
+## [0.16.9] - 2026-08-20
+
+### Changed
+
+- Promote the Marketplace Plugin to `0.7.16` and pin its Codex and Claude Code
+  MCP definitions and Skill fallbacks to `@kyo-so/cli@0.16.8`.
+- Update the default Codex ACP adapter to
+  `@agentclientprotocol/codex-acp@1.4.0`.
+- Update the default Claude ACP adapter to
+  `@agentclientprotocol/claude-agent-acp@0.69.0`.
+
 ## [0.16.8] - 2026-08-19
 
 ### Changed

package/README.ja.md

@@ -92,8 +92,8 @@ Plugin は Kyoso review Skill と、公開済み CLI version に pin したロ
 3. または、MCP を登録して review skill をインストールします。
 
 ```bash
-npx -y --package=@kyo-so/cli kyoso setup claude-code --write
-bunx --package @kyo-so/cli kyoso setup claude-code --write
+npx -y --package=kyoso-cli@npm:@kyo-so/cli kyoso setup claude-code --write
+bunx --package kyoso-cli@npm:@kyo-so/cli kyoso setup claude-code --write
 ```
 
 手動で MCP を登録する場合は、`examples/claude-code-mcp.json` を使用します。
@@ -101,8 +101,8 @@ bunx --package @kyo-so/cli kyoso setup claude-code --write
 4. セットアップを確認します。
 
 ```bash
-npx -y --package=@kyo-so/cli kyoso doctor
-bunx --package @kyo-so/cli kyoso doctor
+npx -y --package=kyoso-cli@npm:@kyo-so/cli kyoso doctor
+bunx --package kyoso-cli@npm:@kyo-so/cli kyoso doctor
 ```
 
 5. Claude Code からレビューを依頼します。
@@ -133,15 +133,15 @@ Codex Auto modeでは、approvalが必要なKyoso toolの呼び出しが拒否
 3. または、MCP を登録して review skill をインストールします。
 
 ```bash
-npx -y --package=@kyo-so/cli kyoso setup codex --write
-bunx --package @kyo-so/cli kyoso setup codex --write
+npx -y --package=kyoso-cli@npm:@kyo-so/cli kyoso setup codex --write
+bunx --package kyoso-cli@npm:@kyo-so/cli kyoso setup codex --write
 ```
 
 4. セットアップを確認します。
 
 ```bash
-npx -y --package=@kyo-so/cli kyoso doctor
-bunx --package @kyo-so/cli kyoso doctor
+npx -y --package=kyoso-cli@npm:@kyo-so/cli kyoso doctor
+bunx --package kyoso-cli@npm:@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
 
-package-runner の実行経路では、package と executable を必ず別指定します: `npx -y --package=@kyo-so/cli kyoso` と `bunx --package @kyo-so/cli kyoso` です。workflowで固定する場合は、`@kyo-so/cli@0.16.7` のようにpackage名へcomplete SemVer pinを付けます。以下の例の `kyoso` は、すでにインストールされた executable の省略形です。Naming note: npm パッケージは `@kyo-so/cli` (製品名 Kyo-so に対応) で、インストールされる CLI コマンドは短い `kyoso` です。
+package-runner の実行経路では、npm package をローカル alias `kyoso-cli` としてインストールします: `npx -y --package=kyoso-cli@npm:@kyo-so/cli kyoso` と `bunx --package kyoso-cli@npm:@kyo-so/cli kyoso` です。いずれも package と executable を別指定するため multi-bin package の binary 推測に依存せず、alias によって package 名が `@kyo-so/cli` である checkout が公開 package を隠すことも防ぎます。workflowで固定する場合は、`kyoso-cli@npm:@kyo-so/cli@0.16.9` のように実 package 名へcomplete SemVer pinを付けます。以下の例の `kyoso` は、すでにインストールされた executable の省略形です。Naming note: npm パッケージは `@kyo-so/cli` (製品名 Kyo-so に対応)、package-runner の alias は `kyoso-cli`、インストールされる CLI コマンドは短い `kyoso` です。
+
+alias 導入前に書かれた登録は引き続きサポートされ、`current` として分類されます。npx が利用可能な npx 登録は `ready` のままですが、bunx 登録は setup が必要な Bun capability を検証するまで `unverified` のままです。`kyoso doctor` は alias が無いことを警告して書き換え先の spec を示します。setup はこの登録を保持するため、修復は手動編集になります。
 
 Bun fallback は Bun `1.3.14` で検証済みです。古い Bun では npx 形式またはインストール済みの `kyoso` を使い、複数bin packageからの Bun のbinary推論に依存しないでください。
 
@@ -217,7 +219,7 @@ Kyoso を Codex または Claude Code の MCP server として登録し、client
 # See examples/codex-config.toml
 [mcp_servers.kyoso]
 command = "npx"
-args = ["-y", "--package=@kyo-so/cli", "kyoso", "mcp"]
+args = ["-y", "--package=kyoso-cli@npm:@kyo-so/cli", "kyoso", "mcp"]
 ```
 
 client request の例:
@@ -229,8 +231,8 @@ Use Kyoso plan_review on this plan and the selected auth files. I need a second
 ## MCP
 
 ```bash
-npx -y --package=@kyo-so/cli kyoso mcp --network model_only
-bunx --package @kyo-so/cli kyoso mcp --network model_only
+npx -y --package=kyoso-cli@npm:@kyo-so/cli kyoso mcp --network model_only
+bunx --package kyoso-cli@npm:@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 ではありません。
@@ -247,7 +249,7 @@ 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 --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は停止します。
+Skillは利用可能な最初の経路を使います。順序はKyoso MCP tools、PATH上のインストール済み`kyoso`、`npx -y --package=kyoso-cli@npm:@kyo-so/cli kyoso`、`bunx --package kyoso-cli@npm:@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/`へコピーします。
 
@@ -257,7 +259,7 @@ managed installはcanonical directoryのdigestとCLI versionを`.kyoso-install.j
 
 ### 手動 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を検証します。
+最初に `kyoso setup codex` または `kyoso setup claude-code` を実行し、既存登録を確認します。dry-run と `--write` は既存の MCP entry をすべて保持します。`--write --force` は生成時allowlist内のenvを持つ認識済み完全一致 legacy npx Kyoso commandを、上記の alias 付きpackageとexecutableを分離した形式へ移行します。完全一致 legacy bunx command は `--runner` を省略するとprobeせず保持します。`--write --runner bunx --force` は Bun を検証して alias 付き bunx 形式へ移行し、`--write --runner npx --force` は意図的にnpx形式へ移行します。いずれもlegacy commandにcomplete SemVer pinがあった場合は保持します。currentの明示bunx登録は`--write --runner bunx`で確認でき、setupは登録bytesを変えずにBunを検証します。packageとexecutableを分離した形式は alias の有無にかかわらず current 扱いなので、alias 導入前の登録は移行せず保持されます。doctor が alias 不足を警告し、書き換え先の spec を示します。
 
 `--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 を再実行してください。
 
@@ -573,7 +575,8 @@ 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 -y --package=@kyo-so/cli@<version> kyoso` が一時的に block される場合があります。`latest` や ambient `kyoso` へfallbackせず、その exact version を待ってください。
+- Fresh npm release: safe-chain などの minimum-package-age protection により、publish 直後は `npx -y --package=kyoso-cli@npm:@kyo-so/cli@<version> kyoso` が一時的に block される場合があります。`latest` や ambient `kyoso` へfallbackせず、その exact version を待ってください。
+- alias 付き登録が `custom/unverified` と表示される: `kyoso-cli` alias より前の `kyoso doctor` はこれを認識できず、現在の examples から写した entry が unverified に見えます。CLI を更新してから doctor を再実行してください。
 - 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 -y --package=@kyo-so/cli kyoso setup claude-code --write
-bunx --package @kyo-so/cli kyoso setup claude-code --write
+npx -y --package=kyoso-cli@npm:@kyo-so/cli kyoso setup claude-code --write
+bunx --package kyoso-cli@npm:@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 -y --package=@kyo-so/cli kyoso doctor
-bunx --package @kyo-so/cli kyoso doctor
+npx -y --package=kyoso-cli@npm:@kyo-so/cli kyoso doctor
+bunx --package kyoso-cli@npm:@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 -y --package=@kyo-so/cli kyoso setup codex --write
-bunx --package @kyo-so/cli kyoso setup codex --write
+npx -y --package=kyoso-cli@npm:@kyo-so/cli kyoso setup codex --write
+bunx --package kyoso-cli@npm:@kyo-so/cli kyoso setup codex --write
 ```
 
 4. Verify the setup.
 
 ```bash
-npx -y --package=@kyo-so/cli kyoso doctor
-bunx --package @kyo-so/cli kyoso doctor
+npx -y --package=kyoso-cli@npm:@kyo-so/cli kyoso doctor
+bunx --package kyoso-cli@npm:@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
 
-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.16.7`. 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 package-runner execution paths install the npm package under the local alias `kyoso-cli`: `npx -y --package=kyoso-cli@npm:@kyo-so/cli kyoso` and `bunx --package kyoso-cli@npm:@kyo-so/cli kyoso`. Both forms select the package and the executable separately, so neither relies on binary inference from a multi-bin package, and the alias prevents a checkout whose own package name is `@kyo-so/cli` from shadowing the published package. Add a complete SemVer pin after the real package name when a workflow needs one, for example `kyoso-cli@npm:@kyo-so/cli@0.16.9`. 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), the package-runner alias is `kyoso-cli`, and the installed CLI command is the shorter `kyoso`.
+
+Registrations written before the alias remain supported and classified as `current`. An available npx registration remains `ready`; a bunx registration remains `unverified` until its Bun capability is verified by setup. `kyoso doctor` warns that the alias is missing and names the spec to write; setup preserves such an entry, so that repair is a hand edit.
 
 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.
 
@@ -228,7 +230,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", "--package=@kyo-so/cli", "kyoso", "mcp"]
+args = ["-y", "--package=kyoso-cli@npm:@kyo-so/cli", "kyoso", "mcp"]
 ```
 
 Example client request:
@@ -240,8 +242,8 @@ Use Kyoso plan_review on this plan and the selected auth files. I need a second
 ## MCP
 
 ```bash
-npx -y --package=@kyo-so/cli kyoso mcp --network model_only
-bunx --package @kyo-so/cli kyoso mcp --network model_only
+npx -y --package=kyoso-cli@npm:@kyo-so/cli kyoso mcp --network model_only
+bunx --package kyoso-cli@npm:@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.
@@ -258,7 +260,7 @@ 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 --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`.
+The Skill uses the first available path: Kyoso MCP tools, an installed `kyoso` on `PATH`, `npx -y --package=kyoso-cli@npm:@kyo-so/cli kyoso`, then `bunx --package kyoso-cli@npm:@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/`.
 
@@ -268,7 +270,7 @@ Managed installs record the canonical directory digest and CLI version in `.kyos
 
 ### 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.
+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 aliased 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 aliased 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. The explicit package-and-executable form counts as current with or without the alias, so an entry written before the alias is preserved rather than migrated; doctor warns about the missing alias and names the aliased spec to write.
 
 `--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.
 
@@ -584,7 +586,8 @@ 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 -y --package=@kyo-so/cli@<version> kyoso` after publish. Wait for the exact version instead of falling back to `latest` or an ambient `kyoso`.
+- Fresh npm release: minimum-package-age protection in tools such as safe-chain may briefly block `npx -y --package=kyoso-cli@npm:@kyo-so/cli@<version> kyoso` after publish. Wait for the exact version instead of falling back to `latest` or an ambient `kyoso`.
+- Aliased registration reported as `custom/unverified`: a `kyoso doctor` that predates the `kyoso-cli` alias and does not recognize it, so an entry copied from the current examples looks unverified. Update the CLI before rerunning doctor.
 - 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 -y --package=@kyo-so/cli kyoso setup claude-code --write
-bunx --package @kyo-so/cli kyoso setup claude-code --write
+npx -y --package=kyoso-cli@npm:@kyo-so/cli kyoso setup claude-code --write
+bunx --package kyoso-cli@npm:@kyo-so/cli kyoso setup claude-code --write
 ```
 
 需要手动注册 MCP 时，请使用 `examples/claude-code-mcp.json`。
@@ -101,8 +101,8 @@ bunx --package @kyo-so/cli kyoso setup claude-code --write
 4. 验证 setup。
 
 ```bash
-npx -y --package=@kyo-so/cli kyoso doctor
-bunx --package @kyo-so/cli kyoso doctor
+npx -y --package=kyoso-cli@npm:@kyo-so/cli kyoso doctor
+bunx --package kyoso-cli@npm:@kyo-so/cli kyoso doctor
 ```
 
 5. 从 Claude Code 请求 review。
@@ -133,15 +133,15 @@ codex plugin add kyoso@kyoso
 3. 或者，注册 MCP 并安装 review skill。
 
 ```bash
-npx -y --package=@kyo-so/cli kyoso setup codex --write
-bunx --package @kyo-so/cli kyoso setup codex --write
+npx -y --package=kyoso-cli@npm:@kyo-so/cli kyoso setup codex --write
+bunx --package kyoso-cli@npm:@kyo-so/cli kyoso setup codex --write
 ```
 
 4. 验证 setup。
 
 ```bash
-npx -y --package=@kyo-so/cli kyoso doctor
-bunx --package @kyo-so/cli kyoso doctor
+npx -y --package=kyoso-cli@npm:@kyo-so/cli kyoso doctor
+bunx --package kyoso-cli@npm:@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
 
-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.16.7`。下面的示例把已安装 executable 简写为 `kyoso`。Naming note: npm package 是 `@kyo-so/cli` (对应产品名 Kyo-so)，安装后的 CLI command 是更短的 `kyoso`。
+package-runner 执行路径会把 npm package 安装为本地 alias `kyoso-cli`：`npx -y --package=kyoso-cli@npm:@kyo-so/cli kyoso` 与 `bunx --package kyoso-cli@npm:@kyo-so/cli kyoso`。两种形式都分别指定 package 和 executable，因此都不依赖 multi-bin package 的 binary 推断；alias 还能防止 package 名同为 `@kyo-so/cli` 的 checkout 遮蔽已发布的 package。需要固定 workflow 时，在真实 package 名后加 complete SemVer pin，例如 `kyoso-cli@npm:@kyo-so/cli@0.16.9`。下面的示例把已安装 executable 简写为 `kyoso`。Naming note: npm package 是 `@kyo-so/cli` (对应产品名 Kyo-so)，package-runner alias 是 `kyoso-cli`，安装后的 CLI command 是更短的 `kyoso`。
+
+alias 之前写入的注册仍然受支持，并被分类为 `current`。npx 可用时 npx 注册保持 `ready`；bunx 注册在 setup 验证其所需的 Bun capability 之前保持 `unverified`。`kyoso doctor` 会警告缺少 alias 并给出应写入的 spec；setup 会保留该 entry，因此这项修复需手动编辑。
 
 Bun fallback 已在 Bun `1.3.14` 上验证。旧版 Bun 请使用 npx 形式或已安装的 `kyoso`，不要依赖 Bun 从多 bin package 推断 binary。
 
@@ -217,7 +219,7 @@ kyoso security \
 # See examples/codex-config.toml
 [mcp_servers.kyoso]
 command = "npx"
-args = ["-y", "--package=@kyo-so/cli", "kyoso", "mcp"]
+args = ["-y", "--package=kyoso-cli@npm:@kyo-so/cli", "kyoso", "mcp"]
 ```
 
 client request 示例：
@@ -229,8 +231,8 @@ Use Kyoso plan_review on this plan and the selected auth files. I need a second
 ## MCP
 
 ```bash
-npx -y --package=@kyo-so/cli kyoso mcp --network model_only
-bunx --package @kyo-so/cli kyoso mcp --network model_only
+npx -y --package=kyoso-cli@npm:@kyo-so/cli kyoso mcp --network model_only
+bunx --package kyoso-cli@npm:@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。
@@ -247,7 +249,7 @@ 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 --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会停止。
+Skill使用第一个可用路径，顺序是Kyoso MCP tools、PATH上已安装的`kyoso`、`npx -y --package=kyoso-cli@npm:@kyo-so/cli kyoso`、`bunx --package kyoso-cli@npm:@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/`。
 
@@ -257,7 +259,7 @@ managed install会把canonical directory digest和CLI version记录到`.kyoso-in
 
 ### 手动 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。
+先运行 `kyoso setup codex` 或 `kyoso setup claude-code` 检查现有注册。dry-run 与 `--write` 会保留所有现有 MCP entry。`--write --force` 会把环境字段限于生成时allowlist的完全匹配 legacy npx Kyoso command迁移为上文带 alias 的 package-and-executable 形式。对于完全匹配的 legacy bunx command，省略 `--runner` 会保留它且不执行probe；使用 `--write --runner bunx --force` 可验证 Bun 并迁移为带 alias 的 bunx，或使用 `--write --runner npx --force` 有意迁移为 npx。每种迁移都会保留 legacy command 中的 complete SemVer pin。对于当前的显式bunx注册，可运行`--write --runner bunx`；setup会验证Bun且不改变注册bytes。package-and-executable 形式无论是否带 alias 都算作 current，因此 alias 之前写入的注册会被保留而非迁移；doctor 会警告缺少 alias 并给出应写入的 spec。
 
 `--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。
 
@@ -573,7 +575,8 @@ 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 -y --package=@kyo-so/cli@<version> kyoso`。请等待该 exact version，不要 fallback 到 `latest` 或 ambient `kyoso`。
+- Fresh npm release: safe-chain 等 minimum-package-age protection 可能会在 publish 后短时间内 block `npx -y --package=kyoso-cli@npm:@kyo-so/cli@<version> kyoso`。请等待该 exact version，不要 fallback 到 `latest` 或 ambient `kyoso`。
+- 带 alias 的注册被报告为 `custom/unverified`：早于 `kyoso-cli` alias 的 `kyoso doctor` 无法识别它，因此从当前 examples 复制的 entry 看起来是 unverified。请更新 CLI 后再运行 doctor。
 - 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。