chore(docs): polishing documentation

Author: orenlab

CHANGELOG.md

@@ -7,54 +7,55 @@ coherent platform: canonical-report-first, agent-facing, CI-native, and product-
 
 ### Licensing & packaging
 
-Re-license source code to MPL-2.0 while keeping documentation under MIT. Ship dual `LICENSE` / `LICENSE-docs` files and
-sync SPDX headers.
+- Re-license source code to MPL-2.0 while keeping documentation under MIT.
+- Ship dual `LICENSE` / `LICENSE-docs` files and sync SPDX headers.
 
 ### MCP server (new)
 
-- Optional `codeclone[mcp]` extra with `codeclone-mcp` launcher (`stdio` and `streamable-http` transports).
-- 20 read-only tools + 7 fixed resources + 3 run-scoped URI templates: analysis, diff-aware changed-files, run
-  comparison, findings / hotspots / remediation, granular checks, gate preview, and in-memory-only review/session
-  markers.
-- Bounded run retention (`--history-limit`), `--allow-remote` guard, `cache_policy=refresh` rejected to preserve
+- Add optional `codeclone[mcp]` extra with `codeclone-mcp` launcher (`stdio` and `streamable-http`).
+- Introduce a read-only MCP surface with 20 tools, fixed resources, and run-scoped URIs for analysis, changed-files
+  review, run comparison, findings / hotspots / remediation, granular checks, and gate preview.
+- Add bounded run retention (`--history-limit`), `--allow-remote` guard, and reject `cache_policy=refresh` to preserve
   read-only semantics.
-- Agent-optimised payloads: short MCP run/finding ids, slim summary inventory, compact summary/default finding cards,
-  single-dimension `health` in `check_*`, bounded `metrics_detail`, and compact changed-files / compare-runs responses
-  — all without changing the canonical report contract.
-- `cache.freshness` marker and `get_production_triage` / `codeclone://latest/triage` for compact production-first
+- Optimize MCP payloads for agents with short ids, compact summaries/cards, bounded `metrics_detail`, and slim
+  changed-files / compare-runs responses — without changing the canonical report contract.
+- Make MCP explicitly triage-first and budget-aware: clients are guided toward summary/triage → hotspots / `check_*` →
+  single-finding drill-down instead of broad early listing.
+- Add `cache.freshness` marker and `get_production_triage` / `codeclone://latest/triage` for compact production-first
   overview.
-- Honest run comparison: `compare_runs` reports `mixed` / `incomparable` instead of misleading single verdicts;
-  `clones_only` runs surface `health: unavailable` instead of zeroed placeholders.
-- Safety hardening: MCP analysis now requires an absolute repository root and rejects relative roots like `.`, so the
-  server cannot silently analyze the wrong directory when its cwd differs from the client workspace.
+- Improve run-comparison honesty: `compare_runs` now reports `mixed` / `incomparable`, and `clones_only` runs surface
+  `health: unavailable` instead of placeholder values.
+- Harden repository safety: MCP analysis now requires an absolute repository root and rejects relative roots like `.`
+  to avoid analyzing the wrong directory.
 - Fix hotlist key resolution for `production_hotspots` and `test_fixture_hotspots`.
 - Bump cache schema to `2.3` (stale metric entries rebuilt, not reused).
 
 ### Report contract
 
 - Bump canonical report schema to `2.2`.
 - Add canonical `meta.analysis_thresholds.design_findings` provenance and move threshold-aware design findings fully
-  into the canonical report, so MCP/HTML read the same design-finding universe instead of re-synthesizing it.
+  into the canonical report, so MCP and HTML read the same design-finding universe.
 - Add `derived.overview.directory_hotspots` and render it in the HTML Overview tab as `Hotspots by Directory`.
 
 ### CLI
 
-- `--changed-only`, `--diff-against`, `--paths-from-git-diff` for changed-scope review and gating with first-class
-  summary output.
+- Add `--changed-only`, `--diff-against`, and `--paths-from-git-diff` for changed-scope review and gating with
+  first-class summary output.
 
 ### SARIF
 
-- Stable `primaryLocationLineHash` (line numbers excluded), run-unique `automationDetails.id` / `startTimeUtc`, explicit
-  `kind: "fail"`, ancillary fields moved to `properties`.
+- Stabilize `primaryLocationLineHash` (line numbers excluded), add run-unique `automationDetails.id` /
+  `startTimeUtc`, set explicit `kind: "fail"`, and move ancillary fields to `properties`.
 
 ### HTML report
 
-- IDE picker (PyCharm, IDEA, VS Code, Cursor, Fleet, Zed) with persistent selection; clickable file-path deep links
-  across all tabs; stable `finding-{id}` anchors.
+- Add `Hotspots by Directory` to the Overview tab, surfacing directory-level concentration for `all`, `clones`, and low-cohesion findings with scope-aware badges and compact counts.
+- Add IDE picker (PyCharm, IDEA, VS Code, Cursor, Fleet, Zed) with persistent selection.
+- Add clickable file-path deep links across all tabs and stable `finding-{id}` anchors.
 
 ### GitHub Action
 
-- Composite Action v2: configurable quality gates, SARIF upload to Code Scanning, PR summary comments.
+- Ship Composite Action v2 with configurable quality gates, SARIF upload to Code Scanning, and PR summary comments.
 
 ## [2.0.0b2]
 

README.md

@@ -19,10 +19,9 @@
 ---
 
 CodeClone provides deterministic structural code quality analysis for Python.
-It detects architectural duplication via normalized AST and Control Flow Graphs,
-computes quality metrics, and enforces CI gates — all with **baseline-aware
+It detects architectural duplication, computes quality metrics, and enforces CI gates — all with **baseline-aware
 governance** that separates **known** technical debt from **new** regressions.
-An optional MCP interface exposes the same pipeline to AI agents and IDEs.
+An optional MCP interface exposes the same canonical analysis pipeline to AI agents and IDEs.
 
 Docs: [orenlab.github.io/codeclone](https://orenlab.github.io/codeclone/) ·
 Live sample report:
@@ -41,10 +40,11 @@ Live sample report:
 - **Structural findings** — duplicated branch families, clone guard/exit divergence and clone-cohort drift (report-only)
 - **Quality metrics** — cyclomatic complexity, coupling (CBO), cohesion (LCOM4), dependency cycles, dead code, health
   score
-- **Baseline governance** — known debt stays accepted; CI blocks only new clones and metric regressions
+- **Baseline governance** — separates accepted **legacy** debt from **new regressions** and lets CI fail **only** on
+  what changed
 - **Reports** — interactive HTML, deterministic JSON/TXT plus Markdown and SARIF projections from one canonical report
-- **MCP server** — optional MCP surface for AI agents, IDEs, and MCP-capable clients; read-only with respect to repo and
-  persisted artifacts, budget-aware, and designed as a guided control surface for agentic development
+- **MCP server** — optional read-only MCP surface for AI agents and IDEs, designed as a budget-aware guided control
+  surface for agentic development
 - **CI-first** — deterministic output, stable ordering, exit code contract, pre-commit support
 - **Fast** — incremental caching, parallel processing, warm-run optimization, and reproducible benchmark coverage
 
@@ -167,13 +167,15 @@ codeclone-mcp --transport stdio
 codeclone-mcp --transport streamable-http --port 8000
 ```
 
-20 tools + 10 resources — deterministic, baseline-aware, and read-only. Never mutates source files, baselines, or repo
-state.
-Payloads are optimised for LLM context: compact summaries by default, full detail on demand.
+20 tools + 10 resources — deterministic, baseline-aware, and read-only.
+Never mutates source files, baselines, or repo state.
+
+Payloads are optimized for LLM context: compact summaries by default, full detail on demand.
 The cheapest useful path is also the most obvious path: first-pass triage stays compact, and deeper detail is explicit.
-Recommended budget-first flow for agents: `analyze_repository` or
-`analyze_changed_paths` → `get_run_summary` or `get_production_triage` →
-`list_hotspots` or `check_*` → `get_finding` → `get_remediation`.
+
+Recommended agent flow:
+`analyze_repository` or `analyze_changed_paths` → `get_run_summary` or `get_production_triage` →
+`list_hotspots` or `check_*` → `get_finding` → `get_remediation`
 
 Docs:
 [MCP usage guide](https://orenlab.github.io/codeclone/mcp/)
@@ -242,8 +244,7 @@ All report formats are rendered from one canonical JSON report document.
 - `--timestamped-report-paths` appends a UTC timestamp to default report filenames for bare report flags such as
   `--html` or `--json`. Explicit report paths are not rewritten.
 
-The published docs site also includes a live example HTML/JSON/SARIF report
-generated from the current `codeclone` repository during the docs build.
+The docs site also includes live example HTML/JSON/SARIF reports generated from the current `codeclone` repository.
 
 Structural findings include:
 
@@ -270,7 +271,7 @@ class Middleware:  # codeclone: ignore[dead-code]
 Dynamic/runtime false positives are resolved via explicit inline suppressions, not via broad heuristics.
 
 <details>
-<summary>JSON report shape (v2.2)</summary>
+<summary>Canonical JSON report shape (v2.2)</summary>
 
 ```json
 {