feat(clients): harden MCP client surfaces and polish prerelease UX for b4

- make MCP initialize metadata report the CodeClone package version so clients can enforce runtime compatibility correctly
- harden the VS Code extension with a minimum supported CodeClone gate, uv-based setup guidance, moved-view icons, titled quick picks, and leaner editor actions aligned with current VS Code UX guidance
- improve the Claude Desktop bundle startup path and launcher handling, with refreshed tests and packaging flow
- refresh README, MCP/client docs, changelog, and related CI-facing metadata around the current VS Code, Claude, and Codex surfaces

Author: orenlab

.github/ISSUE_TEMPLATE/feature_request.yml

@@ -1,8 +1,8 @@
 name: ✨ Feature request
 description: Propose an enhancement to CodeClone
 title: "[Feature]: "
-labels: ["enhancement"]
-assignees: []
+labels: [ "enhancement" ]
+assignees: [ ]
 
 body:
   - type: markdown

.github/ISSUE_TEMPLATE/mcp_server.yml

@@ -1,8 +1,8 @@
 name: MCP server
 description: Report an MCP bug or propose an MCP workflow/tooling improvement
 title: "[MCP]: "
-labels: ["mcp"]
-assignees: []
+labels: [ "mcp" ]
+assignees: [ ]
 
 body:
   - type: markdown

.github/workflows/codeclone.yml

@@ -2,8 +2,8 @@ name: CodeClone
 
 on:
   pull_request:
-    types: [opened, synchronize, reopened]
-    paths: ["**/*.py"]
+    types: [ opened, synchronize, reopened ]
+    paths: [ "**/*.py" ]
 
 permissions:
   contents: read

CHANGELOG.md

@@ -4,9 +4,15 @@
 
 ### MCP server
 
-- Add `help(topic=...)` tool for workflow guidance, baseline semantics, and review-state routing.
+- Add `help(topic=...)` tool for workflow guidance, baseline semantics, analysis profile, and review-state routing
+  (tool count: 20 → 21).
+- Add `analysis_profile` help topic for explicit conservative-first / deeper-review threshold guidance.
+- Enrich `_SERVER_INSTRUCTIONS` with triage-first workflow, budget-aware drill-down, and conservative-first threshold
+  guidance so MCP-capable clients receive structured behavioral context on connect.
 - Optimize MCP payloads: short finding IDs (sha256-based for block clones), compact `derived` section projection,
   bounded `metrics_detail` with pagination.
+- Fix MCP initialize metadata so `serverInfo.version` reports the CodeClone package version rather than the underlying
+  `mcp` runtime version.
 
 ### Report contract
 
@@ -27,17 +33,27 @@
 - Add Health Score chapter: scoring inputs, report-only layers, phased expansion policy.
 - Document that future releases may lower scores due to broader scoring model, not only worse code.
 
-### IDE integration (preview)
+### IDE and client integration (preview)
 
 - Add VS Code extension (`codeclone-mcp` client) with baseline-aware triage, source drill-down, Explorer decorations,
   and HTML-report bridging.
+- Add conservative, deeper-review, and custom analysis profiles to the VS Code extension and pass them through to MCP.
+- Add limited Restricted Mode: onboarding works in untrusted workspaces, analysis stays gated until trust is granted.
 - Add Node unit tests, extension-host smoke tests, and `.vsix` packaging.
-- Add Claude Desktop `.mcpb` bundle wrapper for the local `codeclone-mcp` launcher with explicit launcher settings,
-  local-stdio enforcement, and deterministic package build smoke.
-- Add a native Codex plugin with repo-local discovery metadata, bundled `codeclone-mcp` config, and a
-  conservative-first CodeClone review skill.
+- Tighten the VS Code extension to current VS Code UX guidance: one primary editor action, titled Quick Picks,
+  per-view icons, non-button tree details, and a hard minimum local CodeClone version gate (`>= 2.0.0b4`).
+- Add Claude Desktop `.mcpb` bundle wrapper for the local `codeclone-mcp` launcher with pre-loaded review instructions,
+  explicit launcher settings, platform auto-discovery (macOS, Linux, Windows), local-stdio enforcement, signal
+  forwarding, and deterministic package build smoke.
+- Add a native Codex plugin with repo-local discovery metadata, bundled `codeclone-mcp` config, pre-loaded instructions,
+  and two skills: conservative-first full review and quick hotspot discovery.
 
-## [2.0.0b3] - 20260401
+### Internal
+
+- Extract shared `_json_io` module for deterministic JSON serialization across baseline, cache, and report paths.
+- Remove low-signal structural clone noise surfaced by stricter analysis passes without touching golden fixture debt.
+
+## [2.0.0b3] - 2026-04-01
 
 2.0.0b3 is the release where CodeClone stops looking like "a strong analyzer with extras" and starts looking like a
 coherent platform: canonical-report-first, agent-facing, CI-native, and product-grade.
@@ -95,7 +111,7 @@ coherent platform: canonical-report-first, agent-facing, CI-native, and product-
 
 - Ship Composite Action v2 with configurable quality gates, SARIF upload to Code Scanning, and PR summary comments.
 
-## [2.0.0b2] - 20260328
+## [2.0.0b2] - 2026-03-28
 
 ### Dependencies
 
@@ -109,7 +125,7 @@ coherent platform: canonical-report-first, agent-facing, CI-native, and product-
 - Keep Overview KPI micro-badges inside cards at extreme browser/mobile widths.
 - Restyle Report Provenance summary badges to match the card-style badge language used across the report.
 
-## [2.0.0b1] - 20260325
+## [2.0.0b1] - 2026-03-25
 
 Major upgrade: CodeClone evolves from a structural clone detector into a
 **baseline-aware code-health and CI governance tool** for Python.

README.md

@@ -57,7 +57,7 @@ Live sample report:
 ## Quick Start
 
 ```bash
-uv tool install codeclone
+uv tool install codeclone      # use --pre for beta
 
 codeclone .                    # analyze
 codeclone . --html             # HTML report
@@ -164,10 +164,10 @@ Optional read-only MCP server for AI agents and IDE clients.
 21 tools + 10 resources — never mutates source, baselines, or repo state.
 
 ```bash
-uv tool install "codeclone[mcp]"
+uv tool install "codeclone[mcp]"       # or: uv pip install "codeclone[mcp]"
 
-codeclone-mcp --transport stdio              # local (Claude Code, Codex, Copilot, Gemini CLI)
-codeclone-mcp --transport streamable-http    # remote / HTTP-only clients
+codeclone-mcp --transport stdio            # local (Claude Code, Codex, Copilot, Gemini CLI)
+codeclone-mcp --transport streamable-http  # remote / HTTP-only clients
 ```
 
 Docs:
@@ -177,11 +177,11 @@ Docs:
 
 ### Native Client Surfaces
 
-| Surface                   | Location                                                                                                                     | Purpose                                           |
-|---------------------------|------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------|
-| **VS Code extension**     | [`extensions/vscode-codeclone/`](https://github.com/orenlab/codeclone/tree/main/extensions/vscode-codeclone)                 | Triage-first structural review in the editor      |
-| **Claude Desktop bundle** | [`extensions/claude-desktop-codeclone/`](https://github.com/orenlab/codeclone/tree/main/extensions/claude-desktop-codeclone) | Local `.mcpb` install surface                     |
-| **Codex plugin**          | [`plugins/codeclone/`](https://github.com/orenlab/codeclone/tree/main/plugins/codeclone)                                     | Native Codex discovery, skill, and MCP definition |
+| Surface                   | Location                                                                                                                     | Purpose                                            |
+|---------------------------|------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------|
+| **VS Code extension**     | [`extensions/vscode-codeclone/`](https://github.com/orenlab/codeclone/tree/main/extensions/vscode-codeclone)                 | Triage-first structural review in the editor       |
+| **Claude Desktop bundle** | [`extensions/claude-desktop-codeclone/`](https://github.com/orenlab/codeclone/tree/main/extensions/claude-desktop-codeclone) | Local `.mcpb` install with pre-loaded instructions |
+| **Codex plugin**          | [`plugins/codeclone/`](https://github.com/orenlab/codeclone/tree/main/plugins/codeclone)                                     | Native discovery, two skills, and MCP definition   |
 
 All three are thin wrappers over the same `codeclone-mcp` contract — no second analysis engine.
 

codeclone/mcp_server.py

@@ -114,6 +114,8 @@ def build_mcp_server(
         log_level=log_level,
         dependencies=(f"codeclone=={__version__}",),
     )
+    # FastMCP otherwise reports the `mcp` package version in initialize/serverInfo.
+    mcp._mcp_server.version = __version__
 
     def tool(*args: Any, **kwargs: Any) -> Callable[[MCPCallable], MCPCallable]:
         return cast(

docs/book/20-mcp-interface.md

@@ -41,6 +41,9 @@ Current server characteristics:
 - process-count policy:
     - `processes` is an optional override
     - when omitted, MCP defers to the core CodeClone runtime
+- initialize metadata:
+    - `serverInfo.version` reflects the CodeClone package version
+    - clients may use it for compatibility checks
 - root contract:
     - analysis tools require an absolute repository root
     - relative roots such as `.` are rejected in MCP because server cwd may

docs/book/21-vscode-extension.md

@@ -61,7 +61,7 @@ The intended IDE path mirrors CodeClone MCP:
 1. `Analyze Workspace` or `Review Changes`
 2. compact overview and priority review
 3. review new regressions or production hotspots
-4. use `Analysis Depth` only when you need a higher-sensitivity follow-up
+4. use `Set Analysis Depth` only when you need a higher-sensitivity follow-up
 5. reveal source
 6. open canonical finding or remediation only when needed
 
@@ -118,6 +118,7 @@ The extension runs as a workspace extension and requires:
 - local filesystem access
 - local git access for changed-files review
 - a local `codeclone-mcp` launcher, or an explicitly configured launcher
+- CodeClone `2.0.0b4` or newer
 
 For this reason:
 

docs/claude-desktop-bundle.md

@@ -1,75 +1,39 @@
 # Claude Desktop Bundle
 
-CodeClone ships a local Claude Desktop bundle in
+Local `.mcpb` bundle wrapper for `codeclone-mcp` in
 `extensions/claude-desktop-codeclone/`.
 
-It is a small Node-based `.mcpb` wrapper around the local `codeclone-mcp`
-launcher.
+Installable package instead of hand-editing client JSON. Same canonical MCP
+surface used by CLI, VS Code, Codex, and Claude Code. The manifest includes
+pre-loaded instructions that guide Claude toward conservative-first,
+production-first structural review.
 
-## What it is for
-
-The bundle exists to make local CodeClone setup in Claude Desktop easier:
-
-- installable `.mcpb` package instead of hand-editing client JSON
-- the same read-only `codeclone-mcp` surface already used by other MCP clients
-- explicit local-stdio runtime
-- optional launcher override when `codeclone-mcp` is not already on `PATH`
-
-It does not bundle Python or CodeClone itself.
-
-## Install requirements
-
-Install CodeClone with the optional MCP extra first:
+## Install
 
 ```bash
-uv tool install "codeclone[mcp]"
-```
-
-If you want to keep the launcher inside an existing environment instead:
-
-```bash
-uv pip install "codeclone[mcp]"
-```
-
-Verify the launcher:
-
-```bash
-codeclone-mcp --help
+uv tool install "codeclone[mcp]"    # or: uv pip install "codeclone[mcp]"
+codeclone-mcp --help                # verify
 ```
 
 ## Bundle workflow
 
-1. Build the `.mcpb` package from `extensions/claude-desktop-codeclone/`.
-2. In Claude Desktop, open `Settings -> Extensions -> Advanced settings`.
-3. Install the generated `.mcpb`.
-4. If Claude Desktop cannot resolve `codeclone-mcp`, set an explicit launcher
-   command in the bundle settings.
-
-## Runtime model
-
-The bundle runs a small Node wrapper that launches `codeclone-mcp` via local
-`stdio`. Claude Desktop talks to the same canonical MCP surface as every other
-client — the bundle only handles launcher resolution.
+1. Build: `cd extensions/claude-desktop-codeclone && node scripts/build-mcpb.mjs`
+2. Claude Desktop: **Settings → Extensions → Install Extension** → select `.mcpb`
+3. If `codeclone-mcp` is not on `PATH`, set **CodeClone launcher command** in
+   the bundle settings to an absolute path.
 
 ## Settings
 
-### `CodeClone launcher command`
+| Setting                        | Purpose                                              |
+|--------------------------------|------------------------------------------------------|
+| **CodeClone launcher command** | Absolute path or bare command for `codeclone-mcp`    |
+| **Advanced launcher args**     | JSON array of extra args (transport is always stdio) |
 
-Optional absolute path or bare command name for `codeclone-mcp`.
-
-### `Advanced launcher args (JSON array)`
-
-Optional JSON array of additional launcher arguments for advanced setups.
-
-The bundle rejects transport and network-listener arguments because the Claude
-Desktop package is intentionally local-stdio-only.
-
-## Design decisions
+## Runtime model
 
-- **Small wrapper, not a shadow runtime** — Node only locates and launches
-  `codeclone-mcp`
-- **Setup honesty** — missing launchers fail with a clear install hint
-- **Local-only transport** — no streamable HTTP or remote-listener switches
+Node wrapper launches `codeclone-mcp` via local `stdio`. Auto-discovers the
+launcher in `~/.local/bin`, macOS `~/Library/Python/*/bin`, or Windows Python
+paths. Falls back to `PATH`.
 
 ## Privacy
 
@@ -78,10 +42,8 @@ See [Privacy Policy](privacy-policy.md).
 
 ## Current limits
 
-- the bundle expects a global or explicitly configured launcher; it does not
-  auto-discover repository-local virtual environments
-- it is a local install surface for Claude Desktop, not a hosted service layer
-- it does not change CodeClone MCP semantics or add bundle-only tools
+- expects a global or explicitly configured launcher
+- local install surface, not a hosted service layer
 
 For the underlying MCP contract, see:
 

docs/codex-plugin.md

@@ -1,74 +1,42 @@
 # Codex Plugin
 
 CodeClone ships a native Codex plugin in `plugins/codeclone/`.
-
-This is the Codex-native surface for CodeClone. It uses the local plugin model
-instead of pretending Codex wants a VS Code-style extension package.
-
-## What it is for
-
-The plugin gives Codex:
-
-- a repo-local discoverable plugin entry
-- a local MCP server definition for `codeclone-mcp`
-- a focused CodeClone review skill
-- starter prompts aligned with the canonical CodeClone workflow
-
-It stays read-only and does not create a second analysis model.
+Repo-local discovery via `.agents/plugins/marketplace.json`.
 
 ## What ships in the plugin
 
-- `.codex-plugin/plugin.json` for plugin metadata and prompts
-- `.mcp.json` for the local `codeclone-mcp --transport stdio` definition
-- `skills/codeclone-review/SKILL.md` for conservative-first, triage-first usage
-  guidance
-- `.agents/plugins/marketplace.json` for repo-local plugin discovery
+| File                         | Purpose                                            |
+|------------------------------|----------------------------------------------------|
+| `.codex-plugin/plugin.json`  | Plugin metadata, prompts, instructions             |
+| `.mcp.json`                  | Local `codeclone-mcp --transport stdio` definition |
+| `skills/codeclone-review/`   | Conservative-first full review skill               |
+| `skills/codeclone-hotspots/` | Quick hotspot discovery skill                      |
+| `assets/`                    | Plugin branding                                    |
 
-## Runtime model
+## Install
 
-Additive — Codex discovers the plugin from `.agents/plugins/marketplace.json`,
-gets a local MCP definition and a review skill. Does not mutate
-`~/.codex/config.toml` or install a second server binary.
-
-## Relationship to `codex mcp add`
+```bash
+uv tool install "codeclone[mcp]"    # or: uv pip install "codeclone[mcp]"
+codeclone-mcp --help                # verify
+```
 
-Codex already supports direct MCP registration:
+Manual MCP registration without the plugin:
 
 ```bash
 codex mcp add codeclone -- codeclone-mcp --transport stdio
 ```
 
-That path remains valid and is still the simplest manual setup.
-
-The plugin exists for the native Codex plugin/discovery surface:
-
-- plugin card metadata
-- local marketplace entry
-- bundled CodeClone review skill
-- repo-local MCP definition
-
-## Product decisions
+## Runtime model
 
-- **Codex-native path** — local plugin system for discovery and skills
-- **Canonical MCP first** — same `codeclone-mcp` server as every other client
-- **Skill-guided review** — workflow guidance, not a second analyzer
-- **No hidden config writes** — does not rewrite user MCP config
+Additive — Codex discovers the plugin from `.agents/plugins/marketplace.json`,
+gets a local MCP definition and two skills. Does not mutate
+`~/.codex/config.toml` or install a second server binary.
 
 ## Current limits
 
-- if you already registered `codeclone-mcp` manually in `~/.codex/config.toml`,
-  you may see a duplicate Codex MCP surface until you keep only one setup path
+- if you already registered `codeclone-mcp` manually, keep only one setup path
+  to avoid duplicate MCP surfaces
 - the bundled `.mcp.json` assumes `codeclone-mcp` resolves on `PATH`
-- explicit launcher overrides still belong in user config, not inside the
-  plugin manifest
-
-## Source of truth
-
-The Codex plugin is only a local presentation and discovery layer over:
-
-- `codeclone-mcp`
-- the canonical report semantics behind MCP
-- the existing CodeClone docs and contracts
 
 For the underlying interface contract, see: