@kyo-so/cli 0.8.0 → 0.9.1

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

@@ -34,11 +34,14 @@ Do not use this skill for every coding task. It is intended for deliberate revie
      - `plan_review`
      - `security_review`
      - `diff_review`
-   - If the MCP tools are unavailable, use the CLI fallback with JSON output:
-     - `plan_review` -> `npx -y @kyo-so/cli plan --goal <text> [--plan <path-or-text>] [--file <path>] --json`
-     - `security_review` -> `npx -y @kyo-so/cli security --goal <text> [--diff <path>] [--file <path>] --json`
-     - `diff_review` -> `npx -y @kyo-so/cli diff --base <ref> --head <ref> --json`
-   - `bunx @kyo-so/cli` may be used instead of `npx -y @kyo-so/cli`.
+   - 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`.
+   - 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`
+     - `diff_review` -> `diff --base <ref> --head <ref> --json`
    - The CLI also accepts `--repo-summary`, repeatable `--constraint`, and repeatable `--file` flags. For a large review, adjust an agent timeout with `--set agents.<agent>.timeoutMs=<ms>`.
    - Run the CLI without a config trust flag first. Inspect `audit.warnings` in the JSON result; if it contains `untrusted config was not executed`, or the command fails with an untrusted-config message, ask the user whether to rerun with `--trust-config` to use it or `--ignore-config` to skip it. Never add `--trust-config` without confirmation.
    - Keep `--json` enabled and interpret the returned `decision` exactly like the MCP result.

package/.agents/skills/kyoso-review/agents/openai.yaml

@@ -5,10 +5,3 @@ interface:
 
 policy:
   allow_implicit_invocation: false
-
-dependencies:
-  tools:
-    - type: "mcp"
-      value: "kyoso"
-      description: "Kyoso MCP server"
-      transport: "stdio"

package/CHANGELOG.md

@@ -7,6 +7,77 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.9.1] - 2026-07-13
+
+### Added
+
+- Claude Code Marketplace Plugin distribution with a shared Kyoso Skill and
+  version-pinned local stdio MCP server.
+- Best-effort post-publish reminders when either Plugin CLI pin lags the
+  released CLI version.
+
+### Changed
+
+- Move the Codex Plugin MCP definition to
+  `plugins/kyoso/.codex-plugin/mcp.json` so it cannot be auto-discovered by
+  Claude Code as a Plugin-root `.mcp.json`.
+- Document opt-in per-tool approval settings for avoiding Kyoso rejections in
+  Codex Auto mode, including the risk of sending selected code and review
+  context to configured external model providers. The Plugin keeps approvals
+  disabled by default.
+- Update the default `@agentclientprotocol/claude-agent-acp` adapter from
+  `0.57.0` to `0.58.1` for resumed-session model preservation, cancelled-turn
+  usage reporting, and streamed-thinking robustness.
+- Update `@modelcontextprotocol/server` from `2.0.0-beta.2` to
+  `2.0.0-beta.3`, restoring legacy `CallToolResult` parsing tolerance and
+  incorporating transport and authentication validation fixes.
+
+### Fixed
+
+- Updated the pinned Codex ACP adapter to `1.1.2`, whose bundled Codex model
+  catalog advertises reasoning-effort options for `gpt-5.6` family models.
+
+## [0.9.0] - 2026-07-11
+
+### Added
+
+- Codex Marketplace fixture with a version-pinned local stdio MCP, bundled
+  `kyoso-review` Skill, isolated runtime probe, and compatibility records for
+  Codex CLI 0.144.0-alpha.4 and 0.144.1.
+- `kyoso setup codex|claude-code --skill-only` for installing the canonical
+  Skill without reading or writing MCP configuration. The setup surface also
+  supports `--force` for Skill-only replacement and rejects MCP-only option
+  combinations.
+- Managed Skill updates with deterministic directory digests,
+  `.kyoso-install.json`, published 0.8.0 legacy adoption, user-change conflict
+  detection, symlink rejection, and staged backup/rename replacement.
+
+### Changed
+
+- Recover interrupted managed-Skill replacements from a fixed backup, fail
+  closed on ambiguous recovery state, and guard rename operations against
+  parent-directory replacement.
+- Audit traces now use a verified POSIX user state root (`$XDG_STATE_HOME` or
+  `$HOME/.local/state`) instead of a workspace-controlled `.kyoso/traces`
+  path. The new layout hashes the workspace realpath; existing workspace
+  traces are not migrated or deleted automatically.
+- The canonical bundled Skill continues to try Kyoso MCP tools, an installed
+  `kyoso` on `PATH`, `npx`, then `bunx`, without declaring MCP as a required
+  dependency. The generated Marketplace Plugin copy declares its bundled
+  `kyoso` MCP server as a dependency; a disabled Plugin MCP must be re-enabled
+  or migrated to CLI plus Skill-only rather than falling back to the CLI.
+- Codex MCP configuration resolves from `CODEX_HOME`, while global Codex Skill
+  installation continues to resolve from `HOME`.
+
+### Fixed
+
+- Harden Audit trace creation against workspace-controlled symlinks and races
+  with verified handles, exclusive creation, and fail-closed state-root
+  containment. Windows and runtimes without proven safe filesystem
+  capabilities disable Audit writing rather than using an insecure fallback;
+  Windows support will be re-enabled only after equivalent ownership, symlink,
+  and file-identity guarantees are implemented and verified.
+
 ## [0.8.0] - 2026-07-10
 
 ### Added

package/README.ja.md

@@ -36,6 +36,45 @@ backend が 1 つだけ有効な場合は、2 role の ensemble の代わりに
 
 グローバルインストールは不要です。Kyoso は `npx` または `bunx` で実行します。
 
+### 導入モード
+
+| モード             | 導入物                   |  MCP | 対象               |
+| ------------------ | ------------------------ | ---: | ------------------ |
+| Marketplace Plugin | Skill＋ローカルstdio MCP | あり | Codex／Claude Code |
+| CLI＋Skill-only    | npm CLI＋Skill           | なし | Codex／Claude Code |
+| 手動setup          | 手動MCP登録＋Skill       | あり | Codex／Claude Code |
+
+迷ったらMarketplace Pluginを選んでください。2コマンドでSkillとMCP serverをまとめて導入できます。手順は下の[Codex](#codex)／[Claude Code](#claude-code)節を参照してください。
+
+#### Marketplace Plugin
+
+PluginはSkillと公開済みのKyoso CLIの完全一致versionへpinしたMCP定義を同梱しますが、CLI本体は同梱しません。MCPの初回起動ではnpmへのnetwork accessが必要です。cache済みpackageでoffline起動できる場合はありますが、保証しません。manifestの`Read` capabilityは表示metadataであり、filesystem認可を追加するものではありません。
+
+PluginのSkillは同梱の`kyoso` MCP serverをdependencyとして宣言するため、Kyoso reviewの明示的な実行はCLI fallbackではなくMCPへ誘導されます。同梱Plugin MCPを無効化した場合は、Plugin Skillを利用不可として扱います。MCPを再有効化するか、Pluginを削除してCLI＋Skill-onlyへ移行してください。PluginはCLI fallback modeではありません。
+
+#### CLI＋Skill-only
+
+```bash
+# Global CLI＋Codex Skill
+npm install -g @kyo-so/cli
+kyoso setup codex --write --skill-only --global
+
+# Project CLI＋Codex Skill
+npm install -D @kyo-so/cli
+npx kyoso setup codex --write --skill-only
+```
+
+Claude Codeでは`codex`を`claude-code`へ置き換えます。既定はdry-runです。`--skill-only`はMCP設定を読み書きせず、`--runner`／`--command`とは併用できません。
+
+Skill-onlyは意図的にMCP dependencyを宣言しません。`npx`または`bunx`のpackage-runner fallbackに到達すると、Codex Auto modeはsandbox network escalation approvalを要求することがあります。PATH上に`kyoso`を導入すると、このfallbackを避けられます。
+
+#### 移行
+
+- 手動MCPからCLI＋Skill: CLIとSkillを先に導入し、`codex mcp remove kyoso`または`claude mcp remove kyoso --scope local|project|user`を実行します。
+- CLI＋SkillからPlugin: Pluginを追加してenabledを確認してから、手動MCP登録を削除します。手動コピーSkillは自動削除しません。
+- PluginからCLI＋Skill: CLIとSkillを先に導入し、`codex plugin remove kyoso@kyoso`を実行します。
+- CLI＋Skillから手動MCPへ戻す: `kyoso setup codex --write`または`kyoso setup claude-code --write`を実行します。
+
 ### Claude Only / Codex Only
 
 Kyoso は Claude だけ、または Codex だけでも実行できます。利用できない backend は `kyoso.toml` で無効化してください。例は `examples/claude-only.toml` と `examples/codex-only.toml` にあります。
@@ -54,21 +93,32 @@ claude setup-token
 
 このコマンドで得た `CLAUDE_CODE_OAUTH_TOKEN` を設定するか、直接 API 課金を使う場合は `ANTHROPIC_API_KEY` を設定します。
 
-2. MCP を登録し、review skill をインストールします。
+2. Marketplace Plugin を導入します(推奨)。
+
+```text
+/plugin marketplace add hokupod/kyoso
+/plugin install kyoso@kyoso
+```
+
+Plugin は Kyoso review Skill と、公開済み CLI version に pin したローカル stdio MCP server を導入します。Plugin で導入した場合、`kyoso setup claude-code` は不要です。
+
+3. または、MCP を登録して review skill をインストールします。
 
 ```bash
 npx @kyo-so/cli setup claude-code --write
 bunx @kyo-so/cli setup claude-code --write
 ```
 
-3. セットアップを確認します。
+手動で MCP を登録する場合は、`examples/claude-code-mcp.json` を使用します。
+
+4. セットアップを確認します。
 
 ```bash
 npx @kyo-so/cli doctor
 bunx @kyo-so/cli doctor
 ```
 
-4. Claude Code からレビューを依頼します。
+5. Claude Code からレビューを依頼します。
 
 ```text
 Use Kyoso plan_review on this plan before implementation.
@@ -82,21 +132,56 @@ Use Kyoso plan_review on this plan before implementation.
 codex login
 ```
 
-2. MCP を登録し、review skill をインストールします。
+2. Marketplace Plugin を導入します(推奨)。
+
+```bash
+codex plugin marketplace add hokupod/kyoso
+codex plugin add kyoso@kyoso
+```
+
+Codex desktopのPlugins pageまたは`/plugins`からKyosoを選ぶこともできます。追加したMarketplaceが見えない場合はdesktop appをrefresh／restartしてください。確認は`codex plugin list --marketplace kyoso --json`、削除は`codex plugin remove kyoso@kyoso`です。Plugin で導入した場合、`kyoso setup codex` は不要です。
+
+Codex Auto modeでは、approvalが必要なKyoso toolの呼び出しが拒否されることがあります。個人設定で事前承認するには、次を`~/.codex/config.toml`（`CODEX_HOME`を設定している場合は`$CODEX_HOME/config.toml`）へ追加します。**Kyosoを信頼し、選択したコードとレビュー用contextが設定済みの外部model providerへ送信されることを許容できる場合だけ設定してください。** Pluginの既定値では有効にしていません。
+
+```toml
+[plugins."kyoso@kyoso".mcp_servers.kyoso.tools.diff_review]
+approval_mode = "approve"
+
+[plugins."kyoso@kyoso".mcp_servers.kyoso.tools.plan_review]
+approval_mode = "approve"
+
+[plugins."kyoso@kyoso".mcp_servers.kyoso.tools.security_review]
+approval_mode = "approve"
+```
+
+Pluginではなく、MCP serverとして直接登録している場合（`kyoso setup codex --write` または手動設定）は、`plugins."kyoso@kyoso".` プレフィックスなしの `mcp_servers.kyoso` キーを使用します。
+
+```toml
+[mcp_servers.kyoso.tools.diff_review]
+approval_mode = "approve"
+
+[mcp_servers.kyoso.tools.plan_review]
+approval_mode = "approve"
+
+[mcp_servers.kyoso.tools.security_review]
+approval_mode = "approve"
+```
+
+3. または、MCP を登録して review skill をインストールします。
 
 ```bash
 npx @kyo-so/cli setup codex --write
 bunx @kyo-so/cli setup codex --write
 ```
 
-3. セットアップを確認します。
+4. セットアップを確認します。
 
 ```bash
 npx @kyo-so/cli doctor
 bunx @kyo-so/cli doctor
 ```
 
-4. Codex からレビューを依頼します。
+5. Codex からレビューを依頼します。
 
 ```text
 Use Kyoso diff_review on the current diff. I need a second opinion before merging.
@@ -141,6 +226,8 @@ kyoso doctor
 kyoso init
 kyoso setup codex
 kyoso setup claude-code
+kyoso setup codex --write --skill-only
+kyoso setup claude-code --write --skill-only
 ```
 
 ## Usage Examples
@@ -203,11 +290,13 @@ 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 を優先します。MCP server が未登録の場合は、記載された CLI fallback に従い、`npx -y @kyo-so/cli` または `bunx @kyo-so/cli` から JSON output を取得します。
+Skillは利用可能な最初の経路を使います。順序はKyoso MCP tools、PATH上のインストール済み`kyoso`、`npx -y @kyo-so/cli`、`bunx @kyo-so/cli`です。package runner fallbackはnetwork accessが必要になり、version driftも起こり得るため、MCPなしの通常経路にはインストール済みCLIを使います。
+
+`kyoso setup codex --write --skill-only`はcanonical Skill directoryを既定で`.agents/skills/kyoso-review/`へコピーします。`--global`を追加すると`~/.agents/skills/kyoso-review/`へコピーします。
 
-`npx @kyo-so/cli setup codex --write` と `bunx @kyo-so/cli setup codex --write` は、既定で `.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/`へコピーします。
 
-`npx @kyo-so/cli setup claude-code --write` と `bunx @kyo-so/cli setup claude-code --write` は、既定で `.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設定を削除・上書きしません。
 
 ## Safety Model
 
@@ -221,6 +310,10 @@ Repository content、plans、diffs、selected files は backend prompts 内で u
 
 Finding title は aggregation のため簡潔な英語に正規化されます。evidence、recommendations、summaries はユーザーの言語のままで構いません。
 
+Audit trace は workspace が制御するpathではなく、trusted user state root 配下へ書き込みます。対応するPOSIX runtimeでは、absoluteな`$XDG_STATE_HOME`が利用可能ならそれを、そうでなければ`$HOME/.local/state`を使用し、owner、permission、containment、symlinkを確認できた場合だけ書き込みます。検証またはsafe openに失敗した場合、別locationへ黙ってfallbackせず、そのreviewのAudit writeを無効化してsanitized warningを返し、review自体は継続します。
+
+Windows、および必要なfilesystem capabilityを証明できない環境では、Audit writeをfail-closeで無効化します。trusted state rootを変更できる、または検証済みinodeをrenameできるsame OS user権限のhostile processはこの保証の対象外です。この脅威にはOS sandboxまたはnative dirfd-based supportが必要です。
+
 ## Agent Auth
 
 Codex は利用可能な場合、local `codex` login を使用します。既定の subscription-backed path では API key は不要です。
@@ -266,15 +359,15 @@ effort は仕組みが異なります。Kyoso は env var を設定せず、sess
 
 ## Audit
 
-Audit traces は次の場所に書き込まれます。
+対応するPOSIX runtimeでは、Audit traces はuser state base（absoluteな`$XDG_STATE_HOME`、なければ`$HOME/.local/state`）配下の次の場所に書き込まれます。
 
 ```text
-.kyoso/traces/<yyyy-mm-dd>/<traceId>.jsonl
+<state-base>/kyoso/workspaces/<sha256(realpath(cwd))>/<logical audit.directory>/<yyyy-mm-dd>/<traceId>.jsonl
 ```
 
-Raw agent output と raw file contents は既定で無効です。
+`audit.directory`はlogicalなrelative directory（既定: `.kyoso/traces`）であり、workspace内のdirectoryではありません。既存のworkspace `.kyoso/traces`は自動で移行・削除されません。
 
-`.kyoso/traces/` を Git に含めないでください。`kyoso init` は `.kyoso/` を `.gitignore` に追加し、この repository も同じ設定にしています。`audit.includeRawAgentOutput` を有効にすると、traces に sensitive review output が残る場合があります。local retention policy に従って古い traces を定期的に削除してください。
+Raw agent output と raw file contents は既定で無効です。`audit.includeRawAgentOutput`を有効にすると、traces に sensitive review output が残る場合があります。local retention policy に従って古い traces を削除してください。Windowsまたは安全なfilesystem capabilityを証明できない環境では、Audit trace writeは無効のままで、reviewはsanitized warningを返します。
 
 ## Config
 

package/README.md

@@ -34,6 +34,45 @@ With a single backend enabled, one agent runs as `combined_reviewer` instead of
 
 No global install is required. Run Kyoso through `npx` or `bunx`.
 
+### Integration modes
+
+| Mode                | Installs                           | MCP | Clients             |
+| ------------------- | ---------------------------------- | --: | ------------------- |
+| Marketplace Plugin  | Skill plus local stdio MCP         | Yes | Codex / Claude Code |
+| CLI plus Skill-only | npm CLI plus Skill                 |  No | Codex / Claude Code |
+| Manual setup        | Manual MCP registration plus Skill | Yes | Codex / Claude Code |
+
+When in doubt, pick the Marketplace Plugin: two commands install the Skill and the MCP server together. Follow the [Codex](#codex) or [Claude Code](#claude-code) steps below.
+
+#### Marketplace Plugin
+
+The Plugin bundles the Skill and an MCP definition pinned to an exact published Kyoso CLI version; it does not bundle the CLI itself. Its first MCP start needs network access to npm. A cached package may work offline, but offline startup is not guaranteed. The manifest's `Read` capability is display metadata, not additional filesystem authorization.
+
+The Plugin Skill declares the bundled `kyoso` MCP server as a dependency, so explicit Kyoso reviews are directed through MCP rather than a CLI fallback. If you disable the bundled Plugin MCP, treat the Plugin Skill as unavailable: re-enable it, or remove the Plugin and install CLI plus Skill-only instead. The Plugin is not a CLI-fallback mode.
+
+#### CLI plus Skill-only
+
+```bash
+# Global CLI and Codex Skill
+npm install -g @kyo-so/cli
+kyoso setup codex --write --skill-only --global
+
+# Project CLI and Codex Skill
+npm install -D @kyo-so/cli
+npx kyoso setup codex --write --skill-only
+```
+
+Replace `codex` with `claude-code` for Claude Code. Dry-run remains the default. `--skill-only` never reads or writes MCP configuration and cannot be combined with `--runner` or `--command`.
+
+Skill-only intentionally does not declare an MCP dependency. When it reaches an `npx` or `bunx` package-runner fallback, Codex Auto mode can request a sandbox network escalation approval; installing `kyoso` on `PATH` avoids that fallback.
+
+#### Migration
+
+- Manual MCP to CLI plus Skill: install the CLI and Skill first, then run `codex mcp remove kyoso` or `claude mcp remove kyoso --scope local|project|user`.
+- CLI plus Skill to Plugin: add the Plugin, confirm it is enabled, then remove the manual MCP registration. Manually copied Skills are not removed automatically.
+- Plugin to CLI plus Skill: install the CLI and Skill first, then run `codex plugin remove kyoso@kyoso`.
+- CLI plus Skill back to manual MCP: run `kyoso setup codex --write` or `kyoso setup claude-code --write`.
+
 ### Claude Only / Codex Only
 
 Kyoso can run when only Claude or only Codex is available. Disable the missing backend in `kyoso.toml` using `examples/claude-only.toml` or `examples/codex-only.toml`.
@@ -52,21 +91,32 @@ claude setup-token
 
 Set `CLAUDE_CODE_OAUTH_TOKEN` from that command, or set `ANTHROPIC_API_KEY` for direct API billing.
 
-2. Register MCP and install the review skill.
+2. Install the Marketplace Plugin (recommended).
+
+```text
+/plugin marketplace add hokupod/kyoso
+/plugin install kyoso@kyoso
+```
+
+The Plugin installs the Kyoso review Skill and a local stdio MCP server pinned to a released CLI version. When you install the Plugin, `kyoso setup claude-code` is not required.
+
+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
 ```
 
-3. Verify the setup.
+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
 ```
 
-4. Ask for a review from Claude Code.
+5. Ask for a review from Claude Code.
 
 ```text
 Use Kyoso plan_review on this plan before implementation.
@@ -80,21 +130,56 @@ Use Kyoso plan_review on this plan before implementation.
 codex login
 ```
 
-2. Register MCP and install the review skill.
+2. Install the Marketplace Plugin (recommended).
+
+```bash
+codex plugin marketplace add hokupod/kyoso
+codex plugin add kyoso@kyoso
+```
+
+You can also select Kyoso from the Codex desktop Plugins page or `/plugins`; refresh or restart the desktop app if a newly added marketplace is not visible. Check the installation with `codex plugin list --marketplace kyoso --json`, and remove the Plugin with `codex plugin remove kyoso@kyoso`. When you install the Plugin, `kyoso setup codex` is not required.
+
+Codex Auto mode may reject Kyoso tool calls that require approval. To pre-approve them for your account, add the following to `~/.codex/config.toml` (or `$CODEX_HOME/config.toml` when `CODEX_HOME` is set). **Only do this if you trust Kyoso and accept that selected code and review context may be sent to the configured external model providers.** The Plugin does not enable this by default.
+
+```toml
+[plugins."kyoso@kyoso".mcp_servers.kyoso.tools.diff_review]
+approval_mode = "approve"
+
+[plugins."kyoso@kyoso".mcp_servers.kyoso.tools.plan_review]
+approval_mode = "approve"
+
+[plugins."kyoso@kyoso".mcp_servers.kyoso.tools.security_review]
+approval_mode = "approve"
+```
+
+When Kyoso is registered directly as an MCP server (`kyoso setup codex --write` or manual setup) instead of the Plugin, use the `mcp_servers.kyoso` keys without the `plugins."kyoso@kyoso".` prefix:
+
+```toml
+[mcp_servers.kyoso.tools.diff_review]
+approval_mode = "approve"
+
+[mcp_servers.kyoso.tools.plan_review]
+approval_mode = "approve"
+
+[mcp_servers.kyoso.tools.security_review]
+approval_mode = "approve"
+```
+
+3. Alternatively, register MCP and install the review skill.
 
 ```bash
 npx @kyo-so/cli setup codex --write
 bunx @kyo-so/cli setup codex --write
 ```
 
-3. Verify the setup.
+4. Verify the setup.
 
 ```bash
 npx @kyo-so/cli doctor
 bunx @kyo-so/cli doctor
 ```
 
-4. Ask for a review from Codex.
+5. Ask for a review from Codex.
 
 ```text
 Use Kyoso diff_review on the current diff. I need a second opinion before merging.
@@ -142,6 +227,8 @@ kyoso doctor
 kyoso init
 kyoso setup codex
 kyoso setup claude-code
+kyoso setup codex --write --skill-only
+kyoso setup claude-code --write --skill-only
 ```
 
 ## Usage Examples
@@ -204,11 +291,13 @@ 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 prefers the Kyoso MCP tools when available. If the MCP server is not registered, it follows its documented CLI fallback and requests JSON output from `npx -y @kyo-so/cli` or `bunx @kyo-so/cli`.
+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.
+
+`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/`.
 
-`npx @kyo-so/cli setup codex --write` and `bunx @kyo-so/cli setup codex --write` copy it 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/`.
 
-`npx @kyo-so/cli setup claude-code --write` and `bunx @kyo-so/cli setup claude-code --write` copy 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.
 
 ## Safety Model
 
@@ -222,6 +311,10 @@ Repository content, plans, diffs, and selected files are treated as untrusted da
 
 Finding titles are normalized to concise English for aggregation; evidence, recommendations, and summaries can remain in the user's language.
 
+Audit traces use a trusted user state root rather than a workspace-controlled path. On supported POSIX runtimes, Kyoso uses an absolute `$XDG_STATE_HOME` when available, otherwise `$HOME/.local/state`, only after ownership, permission, containment, and symlink checks succeed. It never silently falls back to another location: if verification or safe open fails, Audit writing is disabled for that review and a sanitized warning is returned while the review continues.
+
+Windows, and environments where the required filesystem capabilities cannot be proven, disable Audit writing fail closed. A hostile process running as the same OS user that can modify the trusted state root or rename an already verified inode is outside this guarantee; protecting against that threat requires an OS sandbox or native dirfd-based support.
+
 ## Agent Auth
 
 Codex uses the local `codex` login when available. No API key is required for the default subscription-backed path.
@@ -267,15 +360,15 @@ Effort works differently: Kyoso does not set an env var for it. Instead, it send
 
 ## Audit
 
-Audit traces are written to:
+On supported POSIX runtimes, Audit traces are written below the user state base (`$XDG_STATE_HOME` when absolute, otherwise `$HOME/.local/state`):
 
 ```text
-.kyoso/traces/<yyyy-mm-dd>/<traceId>.jsonl
+<state-base>/kyoso/workspaces/<sha256(realpath(cwd))>/<logical audit.directory>/<yyyy-mm-dd>/<traceId>.jsonl
 ```
 
-Raw agent output and raw file contents are disabled by default.
+`audit.directory` is a logical relative directory (default: `.kyoso/traces`), not a directory in the workspace. Existing workspace `.kyoso/traces` files are not migrated or deleted automatically.
 
-Keep `.kyoso/traces/` out of Git. `kyoso init` adds `.kyoso/` to `.gitignore`, and this repository does the same. If `audit.includeRawAgentOutput` is enabled, traces may persist sensitive review output; delete old traces regularly according to your local retention policy.
+Raw agent output and raw file contents are disabled by default. If `audit.includeRawAgentOutput` is enabled, traces may persist sensitive review output; delete old traces according to your local retention policy. On Windows or an environment without proven safe filesystem capabilities, Audit trace writing stays disabled and the review returns a sanitized warning.
 
 ## Config