feat: align client surfaces with coverage join and always-on adoption metrics

- remove typing_coverage/docstring_coverage toggles from CLI, pyproject config, runtime plumbing, and docs
- always collect adoption facts in metrics mode and keep unified metrics baselines writing adoption snapshots
- surface Coverage Join facts in the VS Code overview and gate the optional coverage help topic by server version
- harden the VS Code Coverage Join path against null metrics payloads and add formatter regression coverage
- sync Claude Desktop and Codex plugin guidance with canonical coverage/adoption/API MCP surfaces
- refresh HTML quality/clones/dead-code/dependencies presentation with shared stat-card summaries
- update repo pyproject and contract/docs/tests to match the simplified metrics model

Author: orenlab

CHANGELOG.md

@@ -28,6 +28,8 @@ across MCP/HTML/clients; tightens MCP launcher/runtime behavior.
 - Surface effective analysis profile in report meta, MCP summary/triage, and HTML subtitle.
 - Add `health_scope`, `focus`, `new_by_source_kind` to MCP summary/triage.
 - Make baseline mismatch explicit (python tags + no-valid-baseline signal).
+- Surface `Coverage Join` facts and the optional `coverage` MCP help topic in
+  the VS Code extension when the connected server supports them.
 - Prefer workspace-local launchers over `PATH` (Poetry fallback).
 - Add `workspace_root` to force project `.venv` selection.
 

README.md

@@ -16,7 +16,7 @@
   <a href="https://github.com/orenlab/codeclone/actions/workflows/tests.yml"><img src="https://github.com/orenlab/codeclone/actions/workflows/tests.yml/badge.svg?branch=main&style=flat-square" alt="Tests"></a>
   <a href="https://github.com/orenlab/codeclone/actions/workflows/benchmark.yml"><img src="https://github.com/orenlab/codeclone/actions/workflows/benchmark.yml/badge.svg?style=flat-square" alt="Benchmark"></a>
   <a href="https://pypi.org/project/codeclone/"><img src="https://img.shields.io/pypi/pyversions/codeclone.svg?style=flat-square" alt="Python"></a>
-  <a href="https://github.com/orenlab/codeclone"><img src="https://img.shields.io/badge/codeclone-87%20(B)-green" alt="codeclone 89 (B)"></a>
+  <a href="https://github.com/orenlab/codeclone"><img src="https://img.shields.io/badge/codeclone-89%20(B)-green" alt="codeclone 89 (B)"></a>
   <a href="#license"><img src="https://img.shields.io/badge/license-MPL--2.0-brightgreen?style=flat-square" alt="License"></a>
 </p>
 
@@ -50,7 +50,8 @@ Live sample report:
 - **Reports** — interactive HTML, deterministic JSON/TXT plus Markdown and SARIF projections from one canonical report
 - **MCP server** — optional read-only surface for AI agents and IDEs, designed as a budget-aware guided control
   surface for agentic development
-- **VS Code extension** — preview native client for CodeClone MCP with triage-first structural review
+- **VS Code extension** — preview native client for CodeClone MCP with triage-first structural review, factual
+  `Coverage Join` overview support, and bounded in-IDE help topics
 - **Native client surfaces** — preview Claude Desktop bundle and Codex plugin over the same canonical MCP contract
 - **CI-first** — deterministic output, stable ordering, exit code contract, pre-commit support
 - **Fast** — incremental caching, parallel processing, warm-run optimization, and reproducible benchmark coverage

codeclone/_cli_args.py

@@ -214,18 +214,6 @@ def build_parser(version: str) -> _ArgumentParser:
         flag="--ci",
         help_text=ui.HELP_CI,
     )
-    _add_bool_optional_argument(
-        baselines_ci_group,
-        flag="--typing-coverage",
-        help_text=ui.HELP_TYPING_COVERAGE,
-        default=True,
-    )
-    _add_bool_optional_argument(
-        baselines_ci_group,
-        flag="--docstring-coverage",
-        help_text=ui.HELP_DOCSTRING_COVERAGE,
-        default=True,
-    )
     _add_bool_optional_argument(
         baselines_ci_group,
         flag="--api-surface",

codeclone/_cli_baselines.py

@@ -62,8 +62,6 @@ class _BaselineArgs(Protocol):
     fail_on_typing_regression: bool
     fail_on_docstring_regression: bool
     fail_on_api_break: bool
-    typing_coverage: bool
-    docstring_coverage: bool
     api_surface: bool
     ci: bool
 
@@ -388,7 +386,7 @@ def _update_metrics_baseline_if_requested(
     new_metrics_baseline = MetricsBaseline.from_project_metrics(
         project_metrics=project_metrics,
         path=metrics_baseline_path,
-        include_adoption=args.typing_coverage or args.docstring_coverage,
+        include_adoption=True,
         include_api_surface=args.api_surface,
     )
     try:

codeclone/_cli_config.py

@@ -56,8 +56,6 @@ class _ConfigKeySpec:
     "fail_dead_code": _ConfigKeySpec(bool),
     "fail_health": _ConfigKeySpec(int),
     "fail_on_new_metrics": _ConfigKeySpec(bool),
-    "typing_coverage": _ConfigKeySpec(bool),
-    "docstring_coverage": _ConfigKeySpec(bool),
     "api_surface": _ConfigKeySpec(bool),
     "coverage_xml": _ConfigKeySpec(str, allow_none=True),
     "fail_on_typing_regression": _ConfigKeySpec(bool),

codeclone/_cli_runtime.py

@@ -42,8 +42,6 @@ class _RuntimeArgs(Protocol):
     min_typing_coverage: int
     min_docstring_coverage: int
     coverage_min: int
-    typing_coverage: bool
-    docstring_coverage: bool
     api_surface: bool
     update_metrics_baseline: bool
     skip_metrics: bool
@@ -181,10 +179,7 @@ def metrics_computed(args: _RuntimeArgs) -> tuple[str, ...]:
         computed.append("dependencies")
     if not args.skip_dead_code:
         computed.append("dead_code")
-    if bool(getattr(args, "typing_coverage", True)) or bool(
-        getattr(args, "docstring_coverage", True)
-    ):
-        computed.append("coverage_adoption")
+    computed.append("coverage_adoption")
     if bool(getattr(args, "api_surface", False)):
         computed.append("api_surface")
     if bool(getattr(args, "coverage_xml", None)):

codeclone/_html_css.py

@@ -668,8 +668,8 @@
 /* Fact-list: compact label ··· value rows inside overview-summary-item cards. */
 .overview-fact-list{display:flex;flex-direction:column;gap:var(--sp-2)}
 .overview-fact-row{display:flex;align-items:baseline;justify-content:space-between;gap:var(--sp-3);
-  font-size:.8rem;padding-bottom:6px}
-.overview-fact-row:last-child{padding-bottom:0}
+  font-size:.8rem;padding-bottom:6px;border-bottom:1px solid var(--border)}
+.overview-fact-row:last-child{padding-bottom:0;border-bottom:none}
 .overview-fact-label{color:var(--text-muted)}
 .overview-fact-value{display:inline-flex;align-items:baseline;gap:6px;
   color:var(--text-primary);font-weight:600;font-variant-numeric:tabular-nums;text-align:right}

codeclone/_html_report/_sections/_clones.py

@@ -12,7 +12,7 @@
 from typing import TYPE_CHECKING, Literal
 
 from ... import _coerce
-from ..._html_badges import _source_kind_badge_html
+from ..._html_badges import _micro_badges, _source_kind_badge_html, _stat_card
 from ..._html_data_attrs import _build_data_attrs
 from ..._html_escape import _escape_html
 from ..._html_filters import CLONE_TYPE_OPTIONS, SPREAD_OPTIONS, _render_select
@@ -27,6 +27,7 @@
 from ...report.json_contract import clone_group_id
 from ...report.suggestions import classify_clone_type
 from .._components import Tone, insight_block
+from .._glossary import glossary_tip
 from .._icons import ICONS
 from .._tables import render_rows_table
 from .._tabs import render_split_tabs
@@ -740,12 +741,66 @@ def render_clones_panel(ctx: ReportContext) -> tuple[str, bool, int, int]:
             "from active review."
         )
     clones_tone: Tone = "warn" if ctx.clone_groups_total > 0 else "ok"
+
+    # Stat cards
+    avg_per_group = (
+        f"{ctx.clone_instances_total / max(1, ctx.clone_groups_total):.1f}"
+        if ctx.clone_groups_total > 0
+        else "0"
+    )
+    high_spread = sum(
+        1
+        for gs in (ctx.func_sorted, ctx.block_sorted, ctx.segment_sorted)
+        for _, items in gs
+        if len({str(it.get("filepath", "")) for it in items}) > 1
+    )
+    clone_cards = [
+        _stat_card(
+            "Clone groups",
+            ctx.clone_groups_total,
+            detail=_micro_badges(
+                ("functions", len(ctx.func_sorted)),
+                ("blocks", len(ctx.block_sorted)),
+                ("segments", len(ctx.segment_sorted)),
+            ),
+            value_tone="warn" if ctx.clone_groups_total > 0 else "good",
+            glossary_tip_fn=glossary_tip,
+        ),
+        _stat_card(
+            "Instances",
+            ctx.clone_instances_total,
+            detail=_micro_badges(("avg/group", avg_per_group)),
+            value_tone="warn" if ctx.clone_instances_total > 0 else "good",
+            glossary_tip_fn=glossary_tip,
+        ),
+    ]
+    if novelty_enabled:
+        clone_cards.append(
+            _stat_card(
+                "New groups",
+                total_new,
+                detail=_micro_badges(("known", total_known)),
+                value_tone="bad" if total_new > 0 else "good",
+                glossary_tip_fn=glossary_tip,
+            ),
+        )
+    clone_cards.append(
+        _stat_card(
+            "High spread",
+            high_spread,
+            value_tone="warn" if high_spread > 0 else "muted",
+            glossary_tip_fn=glossary_tip,
+        ),
+    )
+    clone_cards_html = f'<div class="stat-cards">{"".join(clone_cards)}</div>'
+
     panel = (
         insight_block(
             question="Where is duplication concentrated right now?",
             answer=clones_answer,
             tone=clones_tone,
         )
+        + clone_cards_html
         + panel
     )