diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..614346f
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,316 @@
+# AGENTS.md — CodeClone (AI Agent Playbook)
+
+This document is the **source of truth** for how AI agents should work in this repository.
+It is optimized for **determinism**, **CI stability**, and **reproducible changes**.
+
+> Repository goal: maximize **honesty**, **reproducibility**, **determinism**, and **precision** for real‑world CI usage.
+
+---
+
+## 1) Operating principles (non‑negotiable)
+
+1. **Do not break CI contracts.**
+   - Treat baseline, cache, and report formats as **public APIs**.
+   - Any contract change must be **versioned**, documented, and accompanied by tests.
+
+2. **Determinism > cleverness.**
+   - Outputs must be stable across runs given identical inputs (same repo, tool version, python tag).
+
+3. **Evidence-based explainability.**
+   - The core engine produces **facts/metrics**.
+   - HTML/UI **renders facts**, it must not invent interpretations.
+
+4. **Safety first.**
+   - Never delete or overwrite user files outside repo.
+   - Any write must be atomic where relevant (e.g., baseline `.tmp` + `os.replace`).
+
+---
+
+## 2) Quick orientation
+
+CodeClone is an AST/CFG-informed clone detector for Python. It supports:
+- **function clones** (strongest signal)
+- **block clones** (sliding window of statements, may be noisy on boilerplate)
+- **segment clones** (report-only unless explicitly gated)
+
+Key artifacts:
+- `codeclone.baseline.json` — trusted baseline snapshot (for CI comparisons)
+- `.cache/codeclone/cache.json` — analysis cache (integrity-checked)
+- `.cache/codeclone/report.html|report.json|report.txt` — reports
+
+---
+
+## 3) One command to validate your change
+
+Run these locally before proposing changes:
+
+```bash
+uv run ruff check .
+uv run mypy .
+uv run pytest -q
+```
+
+If you touched baseline/cache/report contracts, also run the repo’s audit runner (or the scenario script if present).
+
+---
+
+## 4) Baseline contract (v1, stable)
+
+### Baseline file structure (canonical)
+
+```json
+{
+  "meta": {
+    "generator": { "name": "codeclone", "version": "X.Y.Z" },
+    "schema_version": "1.0",
+    "fingerprint_version": "1",
+    "python_tag": "cp313",
+    "created_at": "2026-02-08T14:20:15Z",
+    "payload_sha256": "…"
+  },
+  "clones": {
+    "functions": [],
+    "blocks": []
+  }
+}
+```
+
+### Rules
+
+- `schema_version` is **baseline schema**, not package version.
+- Compatibility is tied to:
+  - `fingerprint_version`
+  - `python_tag`
+  - `generator.name == "codeclone"`
+- `payload_sha256` is computed from a **canonical payload**:
+  - stable key order
+  - clone id lists are **sorted and unique**
+  - integrity check uses constant‑time compare (e.g., `hmac.compare_digest`)
+
+### Trust model
+
+- A baseline is either **trusted** (`baseline_status = ok`) or **untrusted**.
+- **Normal mode**:
+  - warn
+  - ignore untrusted baseline
+  - compare vs empty baseline
+- **CI gating mode** (`--ci` / `--fail-on-new`):
+  - fail‑fast if baseline untrusted
+  - exit code **2** for untrusted baseline
+
+### Legacy behavior
+
+- Legacy baselines (<= 1.3.x layout) must be treated as **untrusted** with explicit messaging and tests.
+
+---
+
+## 5) Cache contract (integrity + size guards)
+
+- Cache is an **optimization**, never a source of truth.
+- If cache is invalid or too large:
+  - warn
+  - proceed without cache
+  - ensure report meta reflects `cache_used=false`
+
+Never “fix” cache by silently mutating it; prefer regenerate.
+
+---
+
+## 6) Reports and explainability
+
+Reports come in:
+- HTML (`--html`)
+- JSON (`--json`)
+- Text (`--text`)
+
+### Report invariants
+
+- Ordering must be deterministic (stable sort keys).
+- All provenance fields must be consistent across formats:
+  - baseline loaded / status
+  - baseline fingerprint + schema versions
+  - baseline generator version
+  - cache path / cache used
+
+### Explainability contract (core owns facts)
+
+For each clone group (especially block clones), the **core** should be able to provide factual fields such as:
+
+- `match_rule`
+- `signature_kind`
+- `window_size` (block size) / `segment_size`
+- `merged_regions` flag and counts
+- `stmt_type_sequence` (normalized)
+- `stmt_type_histogram`
+- `has_control_flow` (if/for/while/try/match)
+- ratios (assert / assign / call)
+- `max_consecutive_<type>` (e.g., consecutive asserts)
+
+UI can show **hints** only when the predicate is **formal & exact** (100% confidence), e.g.:
+- `assert_only_block` (assert_ratio == 1.0 and consecutive_asserts == block_len)
+- `repeated_stmt_hash` (single stmt hash repeated across window)
+
+No UI-only heuristics that affect gating.
+
+---
+
+## 7) Noise policy (what is and isn’t a “fix”)
+
+### Acceptable fixes
+- Merge/report-layer improvements (e.g., merge sliding windows into maximal regions) **without changing gating**.
+- Better evidence surfaced in HTML to explain matches.
+
+### Not acceptable as a “quick fix”
+- Weakening detection rules to hide noisy test patterns, unless:
+  - it is configurable
+  - default remains honest
+  - the change is justified by real-world repos
+  - it includes tests for false-negative risk
+
+### Preferred remediation for test-only FPs
+- Refactor tests to avoid long repetitive statement sequences:
+  - replace chains of `assert "... in html"` with loops or aggregated checks.
+
+---
+
+## 8) How to propose changes (agent workflow)
+
+When you implement something:
+
+1. **State the intent** (what user-visible issue does it solve?)
+2. **List files touched** and why.
+3. **Call out contracts affected**:
+   - baseline / cache / report schema
+   - CLI exit codes / messages
+4. **Add/adjust tests** for:
+   - normal-mode behavior
+   - CI gating behavior
+   - determinism (identical output on rerun)
+   - legacy/untrusted scenarios where applicable
+5. Run:
+   - `ruff`, `mypy`, `pytest`
+
+Avoid changing unrelated files (locks, roadmap) unless required.
+
+---
+
+## 9) CLI behavior and exit codes
+
+Agents must preserve these semantics:
+
+- **0** — success (including “new clones detected” in non-gating mode)
+- **2** — baseline gating failure (untrusted/missing baseline when CI requires trusted baseline; invalid output extension, etc.)
+- **3** — analysis gating failure (e.g., `--fail-threshold` exceeded or new clones in `--ci` as designed)
+
+If you introduce a new exit reason, document it and add tests.
+
+---
+
+## 10) Release hygiene (for agent-assisted releases)
+
+Before cutting a release:
+
+- Confirm baseline schema compatibility is unchanged, or properly versioned.
+- Ensure changelog has:
+  - user-facing changes
+  - migration notes if any
+- Validate `twine check dist/*` for built artifacts.
+- Smoke test install in a clean venv:
+  - `pip install dist/*.whl`
+  - `codeclone --version`
+  - `codeclone . --ci` in a sample repo with baseline.
+
+---
+
+## 11) “Don’t do this” list
+
+- Don’t add hidden behavior differences between report formats.
+- Don’t make baseline compatibility depend on package patch/minor version.
+- Don’t add project-root hashes or unstable machine-local fields to baseline.
+- Don’t embed suppressions into baseline unless explicitly designed as a versioned contract.
+- Don’t introduce nondeterministic ordering (dict iteration, set ordering, filesystem traversal without sort).
+
+---
+
+## 12) Where to put new code
+
+## 13) Python language + typing rules (3.10 → 3.14)
+
+These rules are **repo policy**. If you need to violate one, you must explain why in the PR.
+
+### Supported Python versions
+- **Must run on Python 3.10, 3.11, 3.12, 3.13, 3.14**.
+- Do not rely on behavior that is new to only the latest version unless you provide a fallback.
+- Prefer **standard library** features that exist in 3.10+.
+
+### Modern syntax (allowed / preferred)
+Use modern syntax when it stays compatible with 3.10+:
+- `X | Y` unions, `list[str]` / `dict[str, int]` generics (PEP 604 / PEP 585)
+- `from __future__ import annotations` is allowed, but keep behavior consistent across 3.10–3.14.
+- `match/case` (PEP 634) is allowed, but only if it keeps determinism/readability.
+- `typing.Self` (3.11+) **avoid** in public APIs unless you gate it with `typing_extensions`.
+- Prefer `pathlib.Path` over `os.path` for new code (but keep hot paths pragmatic).
+
+### Typing standards
+- **Type hints are required** for all public functions, core pipeline surfaces, and any code that touches:
+  baseline, cache, fingerprints, report models, serialization, CLI exit behavior.
+- Keep **`Any` to an absolute minimum**:
+  - `Any` is allowed only at IO boundaries (JSON parsing, `argparse`, `subprocess`) and must be
+    *narrowed immediately* into typed structures (dataclasses / TypedDict / Protocol / enums).
+  - If `Any` appears in “core/domain” code, add a comment: `# Any: <reason>` and a TODO to remove.
+- Prefer **`Literal` / enums** for finite sets (e.g., status codes, kinds).
+- Prefer **`dataclasses`** (frozen where reasonable) for data models; keep models JSON‑serializable.
+- Use `collections.abc` types (`Iterable`, `Sequence`, `Mapping`) for inputs where appropriate.
+- Avoid `cast()` unless you also add an invariant check nearby.
+
+### Dataclasses / models
+- Models that cross module boundaries should be:
+  - explicitly typed
+  - immutable when possible (`frozen=True`)
+  - validated at construction (or via a dedicated `validate_*` function) if they are user‑provided.
+
+### Error handling
+- Prefer explicit, typed error types over stringly‑typed errors.
+- Exit codes are part of the public contract; do not change them without updating tests + docs.
+
+### Determinism requirements (language-level)
+- Never iterate over unordered containers (`set`, `dict`) without sorting first when it affects:
+  hashes, IDs, report ordering, baseline payloads, or UI output.
+- Use stable formatting (sorted keys, stable ordering) in JSON output.
+
+### Key PEPs to keep in mind
+- PEP 8, PEP 484 (typing), PEP 526 (variable annotations)
+- PEP 563 / PEP 649 (annotation evaluation changes across versions) — avoid relying on evaluation timing
+- PEP 585 (built-in generics), PEP 604 (X | Y unions)
+- PEP 634 (structural pattern matching)
+- PEP 612 (ParamSpec) / PEP 646 (TypeVarTuple) — only if it clearly helps, don’t overcomplicate
+
+
+
+Prefer these rules:
+
+- **Domain / contracts / enums** live near the domain owner (baseline statuses in baseline domain).
+- **Core logic** should not depend on HTML.
+- **Render** depends on report model, never the other way around.
+- If a module becomes a “god module”, split by:
+  - model (types)
+  - io/serialization
+  - rules/validation
+  - ui rendering
+
+Avoid deep package hierarchies unless they clearly reduce coupling.
+
+---
+
+## 14) Minimal checklist for PRs (agents)
+
+- [ ] Change is deterministic.
+- [ ] Contracts preserved or versioned.
+- [ ] Tests added for new behavior.
+- [ ] `ruff`, `mypy`, `pytest` green.
+- [ ] CLI messages remain helpful and stable (don’t break scripts).
+- [ ] Reports contain provenance fields and reflect trust model correctly.
+
+---
+
+If you are an AI agent and something here conflicts with an instruction from a maintainer in the PR/issue thread, **ask for clarification in the thread** and default to this document until resolved.
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 48213a3..efab51c 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,5 +1,159 @@
 # Changelog
 
+## [1.4.0] - 2026-02-12
+
+### Overview
+
+This release stabilizes the baseline contract for long-term CI reuse without changing clone-detection semantics. Key
+improvements include baseline schema standardization, enhanced cache efficiency, and hardened IO/contract behavior for
+CI environments.
+
+---
+
+### Baseline Schema & Compatibility
+
+**Stable v1 Schema**
+
+- Baseline now uses stable v1 schema with strict top-level `meta` + `clones` objects
+- Compatibility gated by `schema_version`, `fingerprint_version`, and `python_tag` (independent of package patch/minor
+  version)
+- Trust validation requires `meta.generator.name` to be `codeclone`
+- Legacy 1.3 baseline layouts treated as untrusted with explicit regeneration guidance
+
+**Integrity & Hash Calculation**
+
+- Baseline integrity uses canonical `payload_sha256` over semantic payload (`functions`, `blocks`,
+  `fingerprint_version`, `python_tag`)
+- Intentionally excluded from `payload_sha256`:
+    - `schema_version` (compatibility gate only)
+    - `meta.generator.name` (trust gate only)
+    - `meta.generator.version` and `meta.created_at` (informational only)
+- Hash inputs remain stable across future 1.x patch/minor releases
+- Baseline regeneration required only when `fingerprint_version` or `python_tag` changes
+
+**Migration Notes**
+
+- Early 1.4.0 development snapshots (before integrity canonicalization fix) may require one-time
+  `codeclone . --update-baseline`
+- After this one-time update, baselines are stable for long-term CI use
+
+---
+
+### File System & Storage
+
+**Atomic Operations**
+
+- Baseline writes use atomic `*.tmp` + `os.replace` pattern (same filesystem requirement)
+- Configurable size guards:
+    - `--max-baseline-size-mb`
+    - `--max-cache-size-mb`
+
+**Baseline Trust Model**
+
+- **Normal mode**: Untrusted baseline triggers warning and comparison against empty baseline
+- **CI preset** (`--ci`): Untrusted baseline causes fast-fail with exit code `2`
+- Deterministic behavior ensures predictable CI outcomes
+
+---
+
+### CLI & Exit Codes
+
+**Exit Code Contract** (explicit and stable)
+
+- `0` - Success
+- `2` - Contract error (unreadable files, untrusted baseline, integrity failures)
+- `3` - Gating failure (new clones, threshold violations)
+- `5` - Internal error
+
+**Exit Code Priority**
+
+- Contract errors (exit `2`) override gating failures (exit `3`) when both conditions present
+
+**CI/Gating Modes**
+
+- In CI/gating modes (`--ci`, `--fail-on-new`, `--fail-threshold`):
+    - Unreadable or decode-failed source files treated as contract errors (exit `2`)
+    - Prevents incomplete analysis from passing CI checks
+
+**Error Handling**
+
+- Standardized internal error UX: `INTERNAL ERROR` with reason and actionable next steps
+- New `--debug` flag (also `CODECLONE_DEBUG=1`) includes traceback + runtime environment details
+- CLI help now includes canonical exit-code descriptions plus `Repository` / `Issues` / `Docs` links
+
+---
+
+### Reporting Enhancements
+
+**JSON Report (v1.1 Schema)**
+
+- Compact deterministic layout with top-level `meta` + `files` + `groups`
+- Explicit `group_item_layout` for array-based group records
+- New `groups_split` structure with `new`/`known` keys per section
+- Deterministic `meta.groups_counts` aggregates
+- Legacy alias sections removed (`function_clones`, `block_clones`, `segment_clones`)
+
+**TXT Report (aligned to report meta v1.1)**
+
+- Normalized metadata/order as stable contract
+- Explicit section metrics: `loc` for functions, `size` for blocks/segments
+- Sections split into `(NEW)` and `(KNOWN)` for functions/blocks/segments
+- With untrusted baseline: `(KNOWN)` sections empty, all groups in `(NEW)`
+
+**HTML Report (aligned to report meta v1.1)**
+
+- New baseline split controls: `New duplicates` / `Known duplicates`
+- Consistent filtering behavior across report types
+- Block explainability now core-owned (`block_group_facts`)
+- Expanded `Report Provenance` section displays full meta information block
+
+**Cross-Format Metadata**
+
+- All formats (HTML/TXT/JSON) now include:
+    - `baseline_payload_sha256` and `baseline_payload_sha256_verified` for audit traceability
+    - Cache contract fields: `cache_schema_version`, `cache_status`, `cache_used`
+    - Baseline audit fields and trust status
+
+### Documentation
+
+- Added the contract documentation book `docs/book/`.
+
+---
+
+### Testing
+
+**Baseline Contract Testing**
+
+- Expanded matrix coverage:
+    - Legacy format handling
+    - Type/shape validation
+    - Compatibility mismatch scenarios
+    - Integrity failure cases
+    - Canonical hash determinism
+
+**Golden Snapshot Testing**
+
+- New detector golden snapshot fixture with canonical runtime policy
+- Golden assertions run on `cp313` (consistency)
+- Full invariant suite maintains matrix-wide coverage
+- Golden tests use same core `python_tag` source as CLI/baseline checks (prevents cross-layer drift)
+
+---
+
+### Roadmap Note
+
+Version 1.4.0 establishes a stable baseline/CI contract but revealed internal structure needs cleanup. Version 1.5 will
+focus on architecture refactoring for maintainability and orchestration, with strict constraints:
+
+**No changes to:**
+
+- Detection semantics
+- Fingerprint algorithms
+- Baseline hash inputs
+- Determinism guarantees
+
+The 1.4.0 contract remains stable and reliable for long-term CI integration.
+
 ## [1.3.0] - 2026-02-08
 
 ### Overview
@@ -59,8 +213,10 @@ codeclone . --update-baseline
 ### Cache & Security
 
 - Cache default moved to `<root>/.cache/codeclone/cache.json` with legacy path warning.
-- Cache schema was extended to include segment data (`CACHE_VERSION=1.1`).
+- Cache schema moved to compact signed payload format (`CACHE_VERSION=1.2`) with
+  relative file keys and fixed-array entries for faster IO and smaller files.
 - Cache integrity uses constant-time signature checks and deep schema validation.
+- Legacy `.cache_secret` is now treated as obsolete and triggers an explicit cleanup warning.
 - Invalid/oversized cache is ignored deterministically and rebuilt from source.
 - Added security regressions for traversal safety, report escaping, baseline/cache integrity,
   and deterministic report ordering across formats.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 47ccfdf..54f7748 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -6,20 +6,20 @@ CodeClone is an **AST + CFG-based code clone detector** focused on architectural
 not textual similarity.
 
 Contributions are welcome — especially those that improve **signal quality**, **CFG semantics**,
-and **real-world usability**.
+and **real-world CI usability**.
 
 ---
 
 ## Project Philosophy
 
-Before contributing, please understand the core principles of the project:
+Core principles:
 
 - **Low noise over high recall**
 - **Structural and control-flow similarity**, not semantic equivalence
 - **Deterministic and explainable behavior**
-- Optimized for **CI usage and architectural analysis**
+- Optimized for **CI usage** and architectural analysis
 
-If a change increases false positives or reduces explainability,
+If a change increases false positives, reduces determinism, or weakens explainability,
 it is unlikely to be accepted.
 
 ---
@@ -42,14 +42,16 @@ We especially welcome contributions in the following areas:
 
 Please use the appropriate **GitHub Issue Template**.
 
-When reporting bugs related to clone detection, include:
+When reporting issues related to clone detection, include:
 
-- minimal reproducible code snippets;
-- the Python version used;
+- minimal reproducible code snippets (preferred over screenshots);
+- the CodeClone version;
+- the Python version (`python_tag`, e.g. `cp313`);
 - whether the issue is primarily:
-  - AST-related,
-  - CFG-related,
-  - reporting / UI-related.
+    - AST-related,
+    - CFG-related,
+    - normalization-related,
+    - reporting / UI-related.
 
 Screenshots alone are usually insufficient for analysis.
 
@@ -73,12 +75,13 @@ Well-argued false-positive reports are valuable and appreciated.
 
 CFG behavior in CodeClone is intentionally conservative in the 1.x series.
 
-If proposing changes to CFG semantics, please include:
+If proposing changes to CFG semantics, include:
 
 - a description of the current behavior;
 - the proposed new behavior;
-- the expected impact on clone detection quality;
-- concrete code examples.
+- the expected impact on clone detection quality (noise/recall);
+- concrete code examples;
+- a note on determinism implications.
 
 Such changes often require design-level discussion and may be staged across versions.
 
@@ -87,19 +90,44 @@ Such changes often require design-level discussion and may be staged across vers
 ## Security & Safety Expectations
 
 - Assume **untrusted input** (paths and source code).
-- Add **negative tests** for any normalization or CFG change.
-- Changes must preserve determinism and avoid new false positives.
+- Prefer **fail-closed in gating modes** and **fail-open in normal modes** only when explicitly intended.
+- Add **negative tests** for any normalization/CFG change.
+- Changes must preserve determinism and avoid introducing new false positives.
 
 ---
 
 ## Baseline & CI
 
-- Baselines are **versioned**. Regenerate with `codeclone . --update-baseline`
-  when detection logic or CodeClone version changes.
-- Baselines in 1.3+ are tamper-evident (`generator`, `payload_sha256`).
-- Baseline verification must use the same Python `major.minor` version.
-- In `--fail-on-new` / `--ci`, untrusted baseline states fail fast. Outside gating
-  mode, baseline is ignored with warning and comparison proceeds against an empty baseline.
+### Baseline contract (v1)
+
+- The baseline schema is versioned (`meta.schema_version`).
+- Compatibility/trust gates include `schema_version`, `fingerprint_version`, `python_tag`,
+  and `meta.generator.name`.
+- Integrity is tamper-evident via `meta.payload_sha256` over canonical payload:
+  `clones.functions`, `clones.blocks`, `meta.fingerprint_version`, `meta.python_tag`.
+  `meta.schema_version`, `meta.generator.name`, `meta.generator.version`, and `created_at`
+  are excluded from payload hashing.
+
+### When baseline regeneration is required
+
+- Regenerate baseline with `codeclone . --update-baseline` when
+  `fingerprint_version` **or** `python_tag` changes.
+- Regeneration is **not** required for UI/report/CLI/cache/performance-only changes
+  if both `fingerprint_version` and `python_tag` are unchanged.
+
+### Gating behavior
+
+- In `--ci` (or explicit gating flags), **untrusted baseline states fail fast** as a contract error (exit 2).
+- Outside gating mode, an untrusted/missing baseline is ignored with a warning and comparison proceeds
+  against an empty baseline.
+
+### Exit codes contract
+
+- **0** — success
+- **2** — contract error (e.g., missing/untrusted baseline in gating, invalid output path/extension, incompatible
+  versions)
+- **3** — gating failure (new clones detected, `--fail-threshold` exceeded)
+- **5** — internal error (unexpected exception; please report)
 
 ---
 
@@ -108,9 +136,7 @@ Such changes often require design-level discussion and may be staged across vers
 ```bash
 git clone https://github.com/orenlab/codeclone.git
 cd codeclone
-python -m venv .venv
-source .venv/bin/activate
-pip install -e .[dev]
+uv sync --all-extras --dev
 ```
 
 Run tests:
@@ -131,8 +157,9 @@ uv run ruff format .
 
 ## Code Style
 
-- Python 3.10+
+- Python **3.10–3.14**
 - Type annotations are required
+- `Any` should be minimized; prefer precise types and small typed helpers
 - `mypy` must pass
 - `ruff check` must pass
 - Code must be formatted with `ruff format`
@@ -145,11 +172,11 @@ uv run ruff format .
 CodeClone follows **semantic versioning**:
 
 - **MAJOR**: fundamental detection model changes
-- **MINOR**: new detection capabilities (for example, CFG improvements)
+- **MINOR**: new detection capabilities (e.g., new detectors or major CFG/normalization behavior shifts)
 - **PATCH**: bug fixes, performance improvements, and UI/UX polish
 
-Baselines are versioned. Any change to detection behavior must include documentation
-and tests, and may require baseline regeneration.
+Any change that affects detection behavior must include documentation and tests,
+and may require a `fingerprint_version` bump (and thus baseline regeneration).
 
 ---
 
diff --git a/README.md b/README.md
index 7dea74c..96b7859 100644
--- a/README.md
+++ b/README.md
@@ -8,104 +8,47 @@
 ![Baseline](https://img.shields.io/badge/baseline-versioned-green?style=flat-square)
 [![License](https://img.shields.io/pypi/l/codeclone.svg?style=flat-square)](LICENSE)
 
-**CodeClone** is a Python code clone detector based on **normalized Python AST and Control Flow Graphs (CFG)**.
-It helps teams discover architectural duplication and prevent new copy-paste from entering the codebase via CI.
+**CodeClone** is a Python code clone detector based on **normalized AST and Control Flow Graphs (CFG)**.  
+It discovers architectural duplication and prevents new copy-paste from entering your codebase via CI.
 
-CodeClone is designed to help teams:
+---
+
+## Why CodeClone
+
+CodeClone focuses on **architectural duplication**, not text similarity. It detects structural patterns through:
 
-- discover **structural and control-flow duplication**,
-- identify architectural hotspots,
-- prevent *new* duplication via CI and pre-commit hooks.
+- **Normalized AST analysis** — robust to renaming, formatting, and minor refactors
+- **Control Flow Graphs** — captures execution logic, not just syntax
+- **Strict, explainable matching** — clear signals, not fuzzy heuristics
 
-Unlike token- or text-based tools, CodeClone operates on **normalized Python AST and CFG**, making it robust against
-renaming, formatting, and minor refactoring.
+Unlike token-based tools, CodeClone compares **structure and control flow**, making it ideal for finding:
+
+- Repeated service/orchestration patterns
+- Duplicated guard/validation blocks
+- Copy-pasted handler logic across modules
+- Recurring internal segments in large functions
 
 ---
 
-## Why CodeClone?
+## Core Capabilities
 
-Most existing tools detect *textual* duplication.
-CodeClone detects **structural and block-level duplication**, which usually signals missing abstractions or
-architectural drift.
+**Three Detection Levels:**
 
-Typical use cases:
+1. **Function clones (CFG fingerprint)**  
+   Strong structural signal for cross-layer duplication
 
-- duplicated service or orchestration logic across layers (API ↔ application),
-- repeated validation or guard blocks,
-- copy-pasted request / handler flows,
-- duplicated control-flow logic in routers, handlers, or services.
+2. **Block clones (statement windows)**  
+   Detects repeated local logic patterns
 
----
+3. **Segment clones (report-only)**  
+   Internal function repetition for explainability; not used for baseline gating
+
+**CI-Ready Features:**
 
-## Features
-
-### Function-level clone detection (Type-2, CFG-based)
-
-- Detects functions and methods with identical **control-flow structure**.
-- Based on **Control Flow Graph (CFG)** fingerprinting.
-- Robust to:
-    - variable renaming,
-    - constant changes,
-    - attribute renaming,
-    - formatting differences,
-    - docstrings and type annotations.
-- Ideal for spotting architectural duplication across layers.
-
-### Block-level clone detection (Type-3-lite)
-
-- Detects repeated **statement blocks** inside larger functions.
-- Uses sliding windows over CFG-normalized statement sequences.
-- Targets:
-    - validation blocks,
-    - guard clauses,
-    - repeated orchestration logic.
-- Carefully filtered to reduce noise:
-    - no overlapping windows,
-    - no clones inside the same function,
-    - no `__init__` noise,
-    - size and statement-count thresholds.
-
-### Segment-level internal clone detection
-
-- Detects repeated **segment windows** inside the same function.
-- Uses a two-step deterministic match (candidate signature → strict hash).
-- Included in reports for explainability, **not** in baseline/CI failure logic.
-
-### Control-Flow Awareness (CFG v1)
-
-- Each function is converted into a **Control Flow Graph**.
-- CFG nodes contain normalized AST statements.
-- CFG edges represent structural control flow:
-    - `if` / `else`
-    - `for` / `async for` / `while`
-    - `try` / `except` / `finally`
-    - `with` / `async with`
-    - `match` / `case` (Python 3.10+)
-- Current CFG semantics (v1):
-    - `and` / `or` are modeled as short-circuit micro-CFG branches,
-    - `try/except` links only from statements that may raise,
-    - `break` / `continue` are modeled as terminating loop transitions with explicit targets,
-    - `for/while ... else` semantics are preserved structurally,
-    - `match case` and `except` handler order is preserved structurally,
-    - after-blocks are explicit and always present,
-    - focus is on **structural similarity**, not precise runtime semantics.
-
-This design keeps clone detection **stable, deterministic, and low-noise**.
-
-### Low-noise by design
-
-- AST + CFG normalization instead of token matching.
-- Conservative defaults tuned for real-world Python projects.
-- Explicit thresholds for size and statement count.
-- No probabilistic scoring or heuristic similarity thresholds.
-- Safe commutative normalization and local logical equivalences only.
-- Focus on *architectural duplication*, not micro-similarities.
-
-### CI-friendly baseline mode
-
-- Establish a baseline of existing clones.
-- Fail CI **only when new clones are introduced**.
-- Safe for legacy codebases and incremental refactoring.
+- Deterministic output with stable ordering
+- Reproducible artifacts for audit trails
+- Baseline-driven gating to prevent new duplication
+- Fast incremental analysis with intelligent caching
 
 ---
 
@@ -115,160 +58,219 @@ This design keeps clone detection **stable, deterministic, and low-noise**.
 pip install codeclone
 ```
 
-Python 3.10+ is required.
+**Requirements:** Python 3.10+
+
+---
 
 ## Quick Start
 
-Run on a project:
+### Basic Analysis
 
 ```bash
+# Analyze current directory
 codeclone .
-```
 
-This will:
-
-- scan Python files,
-- build CFGs for functions,
-- detect function-level and block-level clones,
-- print a summary to stdout.
+# Check version
+codeclone --version
+```
 
-Generate reports:
+### Generate Reports
 
 ```bash
 codeclone . \
+  --html .cache/codeclone/report.html \
   --json .cache/codeclone/report.json \
   --text .cache/codeclone/report.txt
 ```
 
-Generate an HTML report:
+### CI Integration
 
 ```bash
-codeclone . --html .cache/codeclone/report.html
-```
-
-Check version:
+# 1. Generate baseline once (commit to repo)
+codeclone . --update-baseline
 
-```bash
-codeclone --version
+# 2. Add to CI pipeline
+codeclone . --ci
 ```
 
----
-
-## Reports and Metadata
-
-All report formats include provenance metadata for auditability:
-
-`codeclone_version`, `python_version`, `baseline_path`, `baseline_version`,
-`baseline_schema_version`, `baseline_python_version`, `baseline_loaded`,
-`baseline_status` (and cache metadata when available).
-
-baseline_status values:
-
-- `ok`
-- `missing`
-- `legacy`
-- `invalid`
-- `mismatch_version`
-- `mismatch_schema`
-- `mismatch_python`
-- `generator_mismatch`
-- `integrity_missing`
-- `integrity_failed`
-- `too_large`
+The `--ci` preset is equivalent to `--fail-on-new --no-color --quiet`.
 
 ---
 
-## Baseline Workflow (Recommended)
+## Baseline Workflow
 
-1. Create a baseline
+Baselines capture the **current state of duplication** in your codebase. Once committed, they serve as the reference
+point for CI checks.
 
-Run once on your current codebase:
+**Key points (contract-level):**
 
-```bash
-codeclone . --update-baseline
-```
+- Baseline file is versioned (`codeclone.baseline.json`) and used to classify clones as **NEW** vs **KNOWN**.
+- Compatibility is gated by `schema_version`, `fingerprint_version`, and `python_tag`.
+- Baseline trust is gated by `meta.generator.name` (`codeclone`) and integrity (`payload_sha256`).
+- In CI preset (`--ci`), an untrusted baseline is a contract error (exit `2`).
 
-Commit the generated baseline file to the repository.
+Full contract details: [`docs/book/06-baseline.md`](docs/book/06-baseline.md)
 
-Baselines are versioned. If CodeClone is upgraded, regenerate the baseline to keep
-CI deterministic and explainable.
-
-Baseline format in 1.3+ is tamper-evident (generator, payload_sha256) and validated
-before baseline comparison.
+---
 
-2. Trusted vs untrusted baseline behavior
+## Exit Codes
 
-Baseline states considered untrusted:
+CodeClone uses a deterministic exit code contract:
 
-- `invalid`
-- `too_large`
-- `generator_mismatch`
-- `integrity_missing`
-- `integrity_failed`
+| Code | Meaning                                                                     |
+|------|-----------------------------------------------------------------------------|
+| `0`  | Success — run completed without gating failures                             |
+| `2`  | Contract error — baseline missing/untrusted, invalid output extensions, incompatible versions, unreadable source files in CI/gating |
+| `3`  | Gating failure — new clones detected or threshold exceeded                  |
+| `5`  | Internal error — unexpected exception                                       |
 
-Behavior:
+**Priority:** Contract errors (`2`) override gating failures (`3`) when both occur.
 
-- in normal mode, untrusted baseline is ignored with a warning (comparison falls back to empty baseline);
-- in `--fail-on-new` / `--ci`, untrusted baseline fails fast (exit code 2).
+Full contract details: [`docs/book/03-contracts-exit-codes.md`](docs/book/03-contracts-exit-codes.md)
 
-3. Use in CI
+**Debug Support:**
 
 ```bash
-codeclone . --ci
-```
-
-or:
+# Show detailed error information
+codeclone . --debug
 
-```bash
-codeclone . --ci --html .cache/codeclone/report.html
+# Or via environment variable
+CODECLONE_DEBUG=1 codeclone .
 ```
 
-`--ci` is equivalent to `--fail-on-new --no-color --quiet`.
-
-Behavior:
-
-- existing clones are allowed,
-- the build fails if new clones appear,
-- refactoring that removes duplication is always allowed.
-
-`--fail-on-new` / `--ci` exits with a non-zero code when new clones are detected.
-
 ---
 
-### Cache
-
-By default, CodeClone stores the cache per project at:
-
-```bash
-<root>/.cache/codeclone/cache.json
+## Reports
+
+### Supported Formats
+
+- **HTML** (`--html`) — Interactive web report with filtering
+- **JSON** (`--json`) — Machine-readable structured data
+- **Text** (`--text`) — Plain text summary
+
+### Report Schema (JSON v1.1)
+
+The JSON report uses a compact deterministic layout:
+
+- Top-level: `meta`, `files`, `groups`, `groups_split`, `group_item_layout`
+- Optional top-level: `facts`
+- `groups_split` provides explicit **NEW / KNOWN** separation per section
+- `meta.groups_counts` provides deterministic per-section aggregates
+- `meta` follows a shared canonical contract across HTML/JSON/TXT
+
+Canonical report contract: [`docs/book/08-report.md`](docs/book/08-report.md)
+
+**Minimal shape (v1.1):**
+
+```json
+{
+  "meta": {
+    "report_schema_version": "1.1",
+    "codeclone_version": "1.4.0",
+    "python_version": "3.13",
+    "python_tag": "cp313",
+    "baseline_path": "/path/to/codeclone.baseline.json",
+    "baseline_fingerprint_version": "1",
+    "baseline_schema_version": "1.0",
+    "baseline_python_tag": "cp313",
+    "baseline_generator_name": "codeclone",
+    "baseline_generator_version": "1.4.0",
+    "baseline_payload_sha256": "<sha256>",
+    "baseline_payload_sha256_verified": true,
+    "baseline_loaded": true,
+    "baseline_status": "ok",
+    "cache_path": "/path/to/.cache/codeclone/cache.json",
+    "cache_used": true,
+    "cache_status": "ok",
+    "cache_schema_version": "1.2",
+    "files_skipped_source_io": 0,
+    "groups_counts": {
+      "functions": {
+        "total": 0,
+        "new": 0,
+        "known": 0
+      },
+      "blocks": {
+        "total": 0,
+        "new": 0,
+        "known": 0
+      },
+      "segments": {
+        "total": 0,
+        "new": 0,
+        "known": 0
+      }
+    }
+  },
+  "files": [],
+  "groups": {
+    "functions": {},
+    "blocks": {},
+    "segments": {}
+  },
+  "groups_split": {
+    "functions": {
+      "new": [],
+      "known": []
+    },
+    "blocks": {
+      "new": [],
+      "known": []
+    },
+    "segments": {
+      "new": [],
+      "known": []
+    }
+  },
+  "group_item_layout": {
+    "functions": [
+      "file_i",
+      "qualname",
+      "start",
+      "end",
+      "loc",
+      "stmt_count",
+      "fingerprint",
+      "loc_bucket"
+    ],
+    "blocks": [
+      "file_i",
+      "qualname",
+      "start",
+      "end",
+      "size"
+    ],
+    "segments": [
+      "file_i",
+      "qualname",
+      "start",
+      "end",
+      "size",
+      "segment_hash",
+      "segment_sig"
+    ]
+  },
+  "facts": {
+    "blocks": {}
+  }
+}
 ```
 
-You can override this path with `--cache-path` (`--cache-dir` is a legacy alias).
-
-If you used an older version of CodeClone, delete the legacy cache file at
-`~/.cache/codeclone/cache.json` and add `.cache/` to `.gitignore`.
-
-Cache integrity checks are strict: signature mismatch or oversized cache files are ignored
-with an explicit warning, then rebuilt from source.
-
-Cache entries are validated against expected structure/types; invalid entries are ignored
-deterministically.
-
 ---
 
-## Python Version Consistency for Baseline Checks
+## Cache
 
-Due to inherent differences in Python’s AST between interpreter versions, baseline
-generation and verification must be performed using the same Python version.
+Cache is an optimization layer only and is never a source of truth.
 
-This ensures deterministic and reproducible clone detection results.
+- Default path: `<root>/.cache/codeclone/cache.json`
+- Schema version: **v1.2**
+- Invalid or oversized cache is ignored with warning and rebuilt (fail-open)
 
-CI checks therefore pin baseline verification to a single Python version, while the
-test matrix continues to validate compatibility across Python 3.10–3.14.
+Full contract details: [`docs/book/07-cache.md`](docs/book/07-cache.md)
 
 ---
 
-## Using with pre-commit
+## Pre-commit Integration
 
 ```yaml
 repos:
@@ -289,73 +291,57 @@ repos:
 
 ### CodeClone Is
 
-- an architectural analysis tool,
-- a duplication radar,
-- a CI guard against copy-paste,
-- a control-flow-aware clone detector.
+- A structural clone detector for Python
+- A CI guard against new duplication
+- A deterministic analysis tool with auditable outputs
 
 ### CodeClone Is Not
 
-- a linter,
-- a formatter,
-- a semantic equivalence prover,
-- a runtime analyzer.
-
-## How It Works (High Level)
-
-1. Parse Python source into AST.
-2. Normalize AST (names, constants, attributes, annotations).
-3. Build a Control Flow Graph (CFG) per function.
-4. Compute stable CFG fingerprints.
-5. Extract segment windows for internal clone discovery.
-6. Detect function-level, block-level, and segment-level clones.
-7. Apply conservative filters to suppress noise.
-
-See the architectural overview:
-
-- [docs/architecture.md](docs/architecture.md)
+- A linter or code formatter
+- A semantic equivalence prover
+- A runtime execution analyzer
 
 ---
 
-## Control Flow Graph (CFG)
+## How It Works
 
-Starting from version 1.1.0, CodeClone uses a Control Flow Graph (CFG)
-to improve structural clone detection robustness.
+**High-level Pipeline:**
 
-The CFG is a structural abstraction, not a runtime execution model.
+1. **Parse** — Python source → AST
+2. **Normalize** — AST → canonical structure
+3. **CFG Construction** — per-function control flow graph
+4. **Fingerprinting** — stable hash computation
+5. **Grouping** — function/block/segment clone groups
+6. **Determinism** — stable ordering for reproducibility
+7. **Baseline Comparison** — new vs known clones (when requested)
 
-See full design and semantics:
+Learn more:
 
-- [docs/cfg.md](docs/cfg.md)
+- Architecture: [`docs/architecture.md`](docs/architecture.md)
+- CFG semantics: [`docs/cfg.md`](docs/cfg.md)
 
 ---
 
-## CLI Options
-
-| Option                        | Description                                                          | Default                              |
-|-------------------------------|----------------------------------------------------------------------|--------------------------------------|
-| `root`                        | Project root directory to scan                                       | `.`                                  |
-| `--version`                   | Print CodeClone version and exit                                     | -                                    |
-| `--min-loc`                   | Minimum function LOC to analyze                                      | `15`                                 |
-| `--min-stmt`                  | Minimum AST statements to analyze                                    | `6`                                  |
-| `--processes`                 | Number of worker processes                                           | `4`                                  |
-| `--cache-path FILE`           | Cache file path                                                      | `<root>/.cache/codeclone/cache.json` |
-| `--cache-dir FILE`            | Legacy alias for `--cache-path`                                      | -                                    |
-| `--max-cache-size-mb MB`      | Max cache size before ignore + warning                               | `50`                                 |
-| `--baseline FILE`             | Baseline file path                                                   | `codeclone.baseline.json`            |
-| `--max-baseline-size-mb MB`   | Max baseline size; untrusted baseline fails in CI, ignored otherwise | `5`                                  |
-| `--update-baseline`           | Regenerate baseline from current results                             | `False`                              |
-| `--fail-on-new`               | Fail if new function/block clone groups appear vs baseline           | `False`                              |
-| `--fail-threshold MAX_CLONES` | Fail if total clone groups (`function + block`) exceed threshold     | `-1` (disabled)                      |
-| `--ci`                        | CI preset: `--fail-on-new --no-color --quiet`                        | `False`                              |
-| `--html FILE`                 | Write HTML report (`.html`)                                          | -                                    |
-| `--json FILE`                 | Write JSON report (`.json`)                                          | -                                    |
-| `--text FILE`                 | Write text report (`.txt`)                                           | -                                    |
-| `--no-progress`               | Disable progress bar output                                          | `False`                              |
-| `--no-color`                  | Disable ANSI colors                                                  | `False`                              |
-| `--quiet`                     | Minimize output (warnings/errors still shown)                        | `False`                              |
-| `--verbose`                   | Show hash details for new clone groups in fail output                | `False`                              |
-
-## License
-
-MIT License
+## Documentation Map
+
+Use this map to pick the right level of detail:
+
+- **Contract book (canonical contracts/specs):** [`docs/book/`](docs/book/)
+    - Start here: [`docs/book/00-intro.md`](docs/book/00-intro.md)
+    - Exit codes and precedence: [`docs/book/03-contracts-exit-codes.md`](docs/book/03-contracts-exit-codes.md)
+    - Baseline contract (schema/trust/integrity): [`docs/book/06-baseline.md`](docs/book/06-baseline.md)
+    - Cache contract (schema/integrity/fail-open): [`docs/book/07-cache.md`](docs/book/07-cache.md)
+    - Report contract (schema v1.1 + NEW/KNOWN split): [`docs/book/08-report.md`](docs/book/08-report.md)
+    - CLI behavior: [`docs/book/09-cli.md`](docs/book/09-cli.md)
+    - HTML rendering: [`docs/book/10-html-render.md`](docs/book/10-html-render.md)
+    - Determinism policy: [`docs/book/12-determinism.md`](docs/book/12-determinism.md)
+    - Compatibility/versioning rules: [
+      `docs/book/14-compatibility-and-versioning.md`](docs/book/14-compatibility-and-versioning.md)
+- **Deep dives:**
+    - Architecture narrative: [`docs/architecture.md`](docs/architecture.md)
+    - CFG semantics: [`docs/cfg.md`](docs/cfg.md)
+
+## Links
+
+- **Issues:** <https://github.com/orenlab/codeclone/issues>
+- **PyPI:** <https://pypi.org/project/codeclone/>
diff --git a/SECURITY.md b/SECURITY.md
index 080e1ef..de26567 100644
--- a/SECURITY.md
+++ b/SECURITY.md
@@ -3,13 +3,14 @@
 ## Supported Versions
 
 CodeClone is a static analysis tool and does not execute analyzed code at runtime.
-Nevertheless, security and robustness are treated as first‑class concerns.
+Nevertheless, security and robustness are treated as first-class concerns.
 
 The following versions currently receive security updates:
 
 | Version | Supported |
 |---------|-----------|
-| 1.3.x   | Yes       |
+| 1.4.x   | Yes       |
+| 1.3.x   | No        |
 | 1.2.x   | No        |
 | 1.1.x   | No        |
 | 1.0.x   | No        |
@@ -38,15 +39,22 @@ Additional safeguards:
 
 - HTML report content is escaped in both text and attribute contexts to prevent script injection.
 - Reports are static and do not execute analyzed code.
+- Report explainability fields are generated in Python core; UI is rendering-only and does not infer semantics.
 - Scanner traversal is root-confined and prevents symlink-based path escape.
 - Baseline files are schema/type validated with size limits and tamper-evident integrity fields
-  (`generator`, `payload_sha256` for v1.3+).
+  (`meta.generator` as trust gate, `meta.payload_sha256` as integrity hash in baseline v1).
 - Baseline integrity is tamper-evident (audit signal), not tamper-proof cryptographic signing.
   An actor who can rewrite baseline content and recompute `payload_sha256` can still alter it.
-- In `--fail-on-new` / `--ci`, untrusted baseline states fail fast; otherwise baseline is ignored
+- Baseline hash covers canonical payload only (`clones.functions`, `clones.blocks`,
+  `meta.fingerprint_version`, `meta.python_tag`).
+- Baseline hash excludes non-semantic metadata (`created_at`, `meta.generator.version`).
+- `meta.schema_version` and `meta.generator.name` are validated as compatibility/trust gates and are
+  intentionally excluded from `payload_sha256`.
+- In `--ci` (or explicit `--fail-on-new`), untrusted baseline states fail fast; otherwise baseline is ignored
   with explicit warning and comparison proceeds against an empty baseline.
-- Cache files are HMAC-signed (constant-time comparison), size-limited, and ignored on mismatch.
-- Cache secrets are stored next to the cache (`.cache_secret`) and must not be committed.
+- Cache files are integrity-signed with canonical payload hashing (constant-time comparison),
+  size-limited, and ignored on mismatch.
+- Legacy cache secret files (`.cache/codeclone/.cache_secret`) are obsolete and should be removed.
 
 ---
 
diff --git a/codeclone.baseline.json b/codeclone.baseline.json
index 7dafea0..a50c904 100644
--- a/codeclone.baseline.json
+++ b/codeclone.baseline.json
@@ -1,10 +1,27 @@
 {
-  "functions": [],
-  "blocks": [],
-  "python_version": "3.13",
-  "baseline_version": "1.3.0",
-  "schema_version": 1,
-  "generator": "codeclone",
-  "payload_sha256": "92e80b05c857b796bb452de9e62985a1568874da468bc671998133975c94397a",
-  "created_at": "2026-02-08T09:54:31+00:00"
-}
\ No newline at end of file
+  "meta": {
+    "generator": {
+      "name": "codeclone",
+      "version": "1.4.0"
+    },
+    "schema_version": "1.0",
+    "fingerprint_version": "1",
+    "python_tag": "cp313",
+    "created_at": "2026-02-12T15:31:42Z",
+    "payload_sha256": "691c6cedd10e2a51d6038780f3ae9dffe763356dd2aba742b3980f131b79f217"
+  },
+  "clones": {
+    "functions": [
+      "efc8465229b381a3a50502d59d9539c0be3efe86|20-49"
+    ],
+    "blocks": [
+      "3c1b5cf24b4dfcd8e5736b735bfd3850940100d5|3c1b5cf24b4dfcd8e5736b735bfd3850940100d5|3c1b5cf24b4dfcd8e5736b735bfd3850940100d5|3c1b5cf24b4dfcd8e5736b735bfd3850940100d5",
+      "3c1b5cf24b4dfcd8e5736b735bfd3850940100d5|3c1b5cf24b4dfcd8e5736b735bfd3850940100d5|3c1b5cf24b4dfcd8e5736b735bfd3850940100d5|cb4fcbc1b2a65ec1346898fc0d660335e25d7cbc",
+      "8579659a9e8c9755a6d2f0b1d82dda8866fd243b|1912d2ee3c541cbf9e51f485348586afe1a00755|ee69aff0b7ea38927e5082ceef14115c805f6734|ee69aff0b7ea38927e5082ceef14115c805f6734",
+      "b4b5893be87edf98955f047cbf25ca755dc753b4|8579659a9e8c9755a6d2f0b1d82dda8866fd243b|1912d2ee3c541cbf9e51f485348586afe1a00755|ee69aff0b7ea38927e5082ceef14115c805f6734",
+      "b6ee70d0bd6ff4b593f127a137aed9ab41179145|cacc33d58f323481f65fed57873d1c840531859e|d60c0005a4c850c140378d1c82b81dde93a7ccab|d60c0005a4c850c140378d1c82b81dde93a7ccab",
+      "cacc33d58f323481f65fed57873d1c840531859e|d60c0005a4c850c140378d1c82b81dde93a7ccab|d60c0005a4c850c140378d1c82b81dde93a7ccab|b4b5893be87edf98955f047cbf25ca755dc753b4",
+      "ee69aff0b7ea38927e5082ceef14115c805f6734|fcd36b4275c94f1955fb55e1c1ca3c04c7c0bb26|3c1b5cf24b4dfcd8e5736b735bfd3850940100d5|3c1b5cf24b4dfcd8e5736b735bfd3850940100d5"
+    ]
+  }
+}
diff --git a/codeclone/_cli_args.py b/codeclone/_cli_args.py
index 49c0ad5..15cbdc5 100644
--- a/codeclone/_cli_args.py
+++ b/codeclone/_cli_args.py
@@ -9,12 +9,25 @@
 from __future__ import annotations
 
 import argparse
-from typing import cast
+import sys
+from typing import NoReturn, cast
 
 from . import ui_messages as ui
+from .contracts import ExitCode, cli_help_epilog
 
 
-class _HelpFormatter(argparse.ArgumentDefaultsHelpFormatter):
+class _ArgumentParser(argparse.ArgumentParser):
+    def error(self, message: str) -> NoReturn:
+        self.print_usage(sys.stderr)
+        self.exit(
+            int(ExitCode.CONTRACT_ERROR),
+            f"CONTRACT ERROR: {message}\n",
+        )
+
+
+class _HelpFormatter(
+    argparse.RawTextHelpFormatter, argparse.ArgumentDefaultsHelpFormatter
+):
     def _get_help_string(self, action: argparse.Action) -> str:
         if action.dest == "cache_path":
             return action.help or ""
@@ -22,10 +35,11 @@ def _get_help_string(self, action: argparse.Action) -> str:
 
 
 def build_parser(version: str) -> argparse.ArgumentParser:
-    ap = argparse.ArgumentParser(
+    ap = _ArgumentParser(
         prog="codeclone",
         description="AST and CFG-based code clone detector for Python.",
         formatter_class=_HelpFormatter,
+        epilog=cli_help_epilog(),
     )
     ap.add_argument(
         "--version",
@@ -158,4 +172,9 @@ def build_parser(version: str) -> argparse.ArgumentParser:
         action="store_true",
         help=ui.HELP_VERBOSE,
     )
+    out_group.add_argument(
+        "--debug",
+        action="store_true",
+        help=ui.HELP_DEBUG,
+    )
     return ap
diff --git a/codeclone/_cli_meta.py b/codeclone/_cli_meta.py
index fe6a04e..11fcca7 100644
--- a/codeclone/_cli_meta.py
+++ b/codeclone/_cli_meta.py
@@ -10,15 +10,49 @@
 
 import sys
 from pathlib import Path
-from typing import Any
+from typing import TypedDict
 
-from .baseline import Baseline
+from .baseline import Baseline, current_python_tag
+from .contracts import REPORT_SCHEMA_VERSION
 
 
 def _current_python_version() -> str:
     return f"{sys.version_info.major}.{sys.version_info.minor}"
 
 
+class ReportMeta(TypedDict):
+    """
+    Canonical report metadata contract shared by HTML, JSON, and TXT reports.
+
+    Key semantics:
+    - python_version: runtime major.minor string for human readability (e.g. "3.13")
+    - python_tag: runtime compatibility tag used by baseline/cache contracts
+      (e.g. "cp313")
+    - baseline_*: values loaded from baseline metadata for audit/provenance
+    - cache_*: cache status/provenance for run transparency
+    """
+
+    report_schema_version: str
+    codeclone_version: str
+    python_version: str
+    python_tag: str
+    baseline_path: str
+    baseline_fingerprint_version: str | None
+    baseline_schema_version: str | None
+    baseline_python_tag: str | None
+    baseline_generator_name: str | None
+    baseline_generator_version: str | None
+    baseline_payload_sha256: str | None
+    baseline_payload_sha256_verified: bool
+    baseline_loaded: bool
+    baseline_status: str
+    cache_path: str
+    cache_used: bool
+    cache_status: str
+    cache_schema_version: str | None
+    files_skipped_source_io: int
+
+
 def _build_report_meta(
     *,
     codeclone_version: str,
@@ -28,16 +62,32 @@ def _build_report_meta(
     baseline_status: str,
     cache_path: Path,
     cache_used: bool,
-) -> dict[str, Any]:
+    cache_status: str,
+    cache_schema_version: str | None,
+    files_skipped_source_io: int,
+) -> ReportMeta:
     return {
+        "report_schema_version": REPORT_SCHEMA_VERSION,
         "codeclone_version": codeclone_version,
         "python_version": _current_python_version(),
+        "python_tag": current_python_tag(),
         "baseline_path": str(baseline_path),
-        "baseline_version": baseline.baseline_version,
+        "baseline_fingerprint_version": baseline.fingerprint_version,
         "baseline_schema_version": baseline.schema_version,
-        "baseline_python_version": baseline.python_version,
+        "baseline_python_tag": baseline.python_tag,
+        "baseline_generator_name": baseline.generator,
+        "baseline_generator_version": baseline.generator_version,
+        "baseline_payload_sha256": baseline.payload_sha256,
+        "baseline_payload_sha256_verified": (
+            baseline_loaded
+            and baseline_status == "ok"
+            and isinstance(baseline.payload_sha256, str)
+        ),
         "baseline_loaded": baseline_loaded,
         "baseline_status": baseline_status,
         "cache_path": str(cache_path),
         "cache_used": cache_used,
+        "cache_status": cache_status,
+        "cache_schema_version": cache_schema_version,
+        "files_skipped_source_io": files_skipped_source_io,
     }
diff --git a/codeclone/_cli_paths.py b/codeclone/_cli_paths.py
index 4dcd72f..3f76906 100644
--- a/codeclone/_cli_paths.py
+++ b/codeclone/_cli_paths.py
@@ -14,6 +14,9 @@
 
 from rich.console import Console
 
+from .contracts import ExitCode
+from .ui_messages import fmt_contract_error
+
 
 def expand_path(p: str) -> Path:
     return Path(p).expanduser().resolve()
@@ -26,11 +29,20 @@ def _validate_output_path(
     label: str,
     console: Console,
     invalid_message: Callable[..., str],
+    invalid_path_message: Callable[..., str],
 ) -> Path:
     out = Path(path).expanduser()
     if out.suffix.lower() != expected_suffix:
         console.print(
-            invalid_message(label=label, path=out, expected_suffix=expected_suffix)
+            fmt_contract_error(
+                invalid_message(label=label, path=out, expected_suffix=expected_suffix)
+            )
+        )
+        sys.exit(ExitCode.CONTRACT_ERROR)
+    try:
+        return out.resolve()
+    except OSError as e:
+        console.print(
+            fmt_contract_error(invalid_path_message(label=label, path=out, error=e))
         )
-        sys.exit(2)
-    return out.resolve()
+        sys.exit(ExitCode.CONTRACT_ERROR)
diff --git a/codeclone/_cli_summary.py b/codeclone/_cli_summary.py
index 40df388..c320f39 100644
--- a/codeclone/_cli_summary.py
+++ b/codeclone/_cli_summary.py
@@ -51,7 +51,11 @@ def _build_summary_rows(
 
 
 def _build_summary_table(rows: list[tuple[str, int]]) -> Table:
-    summary_table = Table(title=ui.SUMMARY_TITLE, show_header=True)
+    summary_table = Table(
+        title=ui.SUMMARY_TITLE,
+        show_header=True,
+        width=ui.CLI_LAYOUT_WIDTH,
+    )
     summary_table.add_column("Metric")
     summary_table.add_column("Value", justify="right")
     for label, value in rows:
diff --git a/codeclone/_html_escape.py b/codeclone/_html_escape.py
index 16f7ae4..025ec44 100644
--- a/codeclone/_html_escape.py
+++ b/codeclone/_html_escape.py
@@ -9,24 +9,23 @@
 from __future__ import annotations
 
 import html
-from typing import Any
 
 
-def _escape_html(v: Any) -> str:
+def _escape_html(v: object) -> str:
     text = html.escape("" if v is None else str(v), quote=True)
     text = text.replace("`", "&#96;")
     text = text.replace("\u2028", "&#8232;").replace("\u2029", "&#8233;")
     return text
 
 
-def _escape_attr(v: Any) -> str:
+def _escape_attr(v: object) -> str:
     text = html.escape("" if v is None else str(v), quote=True)
     text = text.replace("`", "&#96;")
     text = text.replace("\u2028", "&#8232;").replace("\u2029", "&#8233;")
     return text
 
 
-def _meta_display(v: Any) -> str:
+def _meta_display(v: object) -> str:
     if isinstance(v, bool):
         return "true" if v else "false"
     if v is None:
diff --git a/codeclone/_html_snippets.py b/codeclone/_html_snippets.py
index 915cb1d..a21467f 100644
--- a/codeclone/_html_snippets.py
+++ b/codeclone/_html_snippets.py
@@ -14,12 +14,12 @@
 from collections.abc import Iterable
 from dataclasses import dataclass
 from functools import lru_cache
-from typing import Any, NamedTuple, cast
+from typing import NamedTuple, cast
 
 from .errors import FileProcessingError
 
 
-def pairwise(iterable: Iterable[Any]) -> Iterable[tuple[Any, Any]]:
+def pairwise(iterable: Iterable[object]) -> Iterable[tuple[object, object]]:
     a, b = itertools.tee(iterable)
     next(b, None)
     return zip(a, b, strict=False)
diff --git a/codeclone/_report_blocks.py b/codeclone/_report_blocks.py
new file mode 100644
index 0000000..a6369d6
--- /dev/null
+++ b/codeclone/_report_blocks.py
@@ -0,0 +1,94 @@
+"""
+CodeClone — AST and CFG-based code clone detector for Python
+focused on architectural duplication.
+
+Copyright (c) 2026 Den Rozhnovskiy
+Licensed under the MIT License.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from ._report_types import GroupItem, GroupMap
+
+
+# Any: values come from report item dictionaries populated from JSON-like data.
+def _coerce_positive_int(value: Any) -> int | None:
+    try:
+        integer = int(value)
+    except (TypeError, ValueError):
+        return None
+    return integer if integer > 0 else None
+
+
+def _block_item_sort_key(item: GroupItem) -> tuple[str, str, int, int]:
+    start_line = _coerce_positive_int(item.get("start_line")) or 0
+    end_line = _coerce_positive_int(item.get("end_line")) or 0
+    return (
+        str(item.get("filepath", "")),
+        str(item.get("qualname", "")),
+        start_line,
+        end_line,
+    )
+
+
+def _merge_block_items(items: list[GroupItem]) -> list[GroupItem]:
+    """
+    Merge overlapping/adjacent block windows into maximal ranges per function.
+    """
+    if not items:
+        return []
+
+    sorted_items = sorted(items, key=_block_item_sort_key)
+    merged: list[GroupItem] = []
+    current: GroupItem | None = None
+
+    for item in sorted_items:
+        start_line = _coerce_positive_int(item.get("start_line"))
+        end_line = _coerce_positive_int(item.get("end_line"))
+        if start_line is None or end_line is None or end_line < start_line:
+            continue
+
+        if current is None:
+            current = dict(item)
+            current["start_line"] = start_line
+            current["end_line"] = end_line
+            current["size"] = max(1, end_line - start_line + 1)
+            continue
+
+        same_owner = str(current.get("filepath", "")) == str(
+            item.get("filepath", "")
+        ) and str(current.get("qualname", "")) == str(item.get("qualname", ""))
+        if same_owner and start_line <= int(current["end_line"]) + 1:
+            current["end_line"] = max(int(current["end_line"]), end_line)
+            current["size"] = max(
+                1, int(current["end_line"]) - int(current["start_line"]) + 1
+            )
+            continue
+
+        merged.append(current)
+        current = dict(item)
+        current["start_line"] = start_line
+        current["end_line"] = end_line
+        current["size"] = max(1, end_line - start_line + 1)
+
+    if current is not None:
+        merged.append(current)
+
+    return merged
+
+
+def prepare_block_report_groups(block_groups: GroupMap) -> GroupMap:
+    """
+    Convert sliding block windows into maximal merged regions for reporting.
+    Block hash keys remain unchanged.
+    """
+    prepared: GroupMap = {}
+    for key, items in block_groups.items():
+        merged = _merge_block_items(items)
+        if merged:
+            prepared[key] = merged
+        else:
+            prepared[key] = sorted(items, key=_block_item_sort_key)
+    return prepared
diff --git a/codeclone/_report_explain.py b/codeclone/_report_explain.py
new file mode 100644
index 0000000..ad26cc0
--- /dev/null
+++ b/codeclone/_report_explain.py
@@ -0,0 +1,251 @@
+"""
+CodeClone — AST and CFG-based code clone detector for Python
+focused on architectural duplication.
+
+Copyright (c) 2026 Den Rozhnovskiy
+Licensed under the MIT License.
+"""
+
+from __future__ import annotations
+
+import ast
+from pathlib import Path
+
+from ._report_explain_contract import (
+    BLOCK_HINT_ASSERT_ONLY,
+    BLOCK_HINT_ASSERT_ONLY_LABEL,
+    BLOCK_HINT_ASSERT_ONLY_NOTE,
+    BLOCK_HINT_CONFIDENCE_DETERMINISTIC,
+    BLOCK_PATTERN_REPEATED_STMT_HASH,
+    resolve_group_compare_note,
+    resolve_group_display_name,
+)
+from ._report_types import GroupItem, GroupMap
+
+
+def _signature_parts(group_key: str) -> list[str]:
+    return [part for part in group_key.split("|") if part]
+
+
+def _parsed_file_tree(
+    filepath: str, *, ast_cache: dict[str, ast.AST | None]
+) -> ast.AST | None:
+    if filepath in ast_cache:
+        return ast_cache[filepath]
+
+    try:
+        source = Path(filepath).read_text("utf-8")
+        tree = ast.parse(source, filename=filepath)
+    except (OSError, SyntaxError):
+        tree = None
+    ast_cache[filepath] = tree
+    return tree
+
+
+def _is_assert_like_stmt(stmt: ast.stmt) -> bool:
+    if isinstance(stmt, ast.Assert):
+        return True
+    if isinstance(stmt, ast.Expr):
+        value = stmt.value
+        if isinstance(value, ast.Constant) and isinstance(value.value, str):
+            return True
+        if isinstance(value, ast.Call):
+            func = value.func
+            if isinstance(func, ast.Name):
+                return func.id.lower().startswith("assert")
+            if isinstance(func, ast.Attribute):
+                return func.attr.lower().startswith("assert")
+    return False
+
+
+def _assert_range_stats(
+    *,
+    filepath: str,
+    start_line: int,
+    end_line: int,
+    ast_cache: dict[str, ast.AST | None],
+    range_cache: dict[tuple[str, int, int], tuple[int, int, int]],
+) -> tuple[int, int, int]:
+    cache_key = (filepath, start_line, end_line)
+    if cache_key in range_cache:
+        return range_cache[cache_key]
+
+    tree = _parsed_file_tree(filepath, ast_cache=ast_cache)
+    if tree is None:
+        range_cache[cache_key] = (0, 0, 0)
+        return 0, 0, 0
+
+    stmts = [
+        node
+        for node in ast.walk(tree)
+        if isinstance(node, ast.stmt)
+        and int(getattr(node, "lineno", 0)) >= start_line
+        and int(getattr(node, "end_lineno", 0)) <= end_line
+    ]
+    if not stmts:
+        range_cache[cache_key] = (0, 0, 0)
+        return 0, 0, 0
+
+    ordered_stmts = sorted(
+        stmts,
+        key=lambda stmt: (
+            int(getattr(stmt, "lineno", 0)),
+            int(getattr(stmt, "end_lineno", 0)),
+            int(getattr(stmt, "col_offset", 0)),
+            int(getattr(stmt, "end_col_offset", 0)),
+            type(stmt).__name__,
+        ),
+    )
+
+    total = len(ordered_stmts)
+    assert_like = 0
+    max_consecutive = 0
+    current_consecutive = 0
+    for stmt in ordered_stmts:
+        if _is_assert_like_stmt(stmt):
+            assert_like += 1
+            current_consecutive += 1
+            if current_consecutive > max_consecutive:
+                max_consecutive = current_consecutive
+        else:
+            current_consecutive = 0
+
+    stats = (total, assert_like, max_consecutive)
+    range_cache[cache_key] = stats
+    return stats
+
+
+def _is_assert_only_range(
+    *,
+    filepath: str,
+    start_line: int,
+    end_line: int,
+    ast_cache: dict[str, ast.AST | None],
+    range_cache: dict[tuple[str, int, int], tuple[int, int, int]],
+) -> bool:
+    total, assert_like, _ = _assert_range_stats(
+        filepath=filepath,
+        start_line=start_line,
+        end_line=end_line,
+        ast_cache=ast_cache,
+        range_cache=range_cache,
+    )
+    return total > 0 and total == assert_like
+
+
+def _base_block_facts(group_key: str) -> dict[str, str]:
+    signature_parts = _signature_parts(group_key)
+    window_size = max(1, len(signature_parts))
+    repeated_signature = len(signature_parts) > 1 and all(
+        part == signature_parts[0] for part in signature_parts
+    )
+    facts: dict[str, str] = {
+        "match_rule": "normalized_sliding_window",
+        "block_size": str(window_size),
+        "signature_kind": "stmt_hash_sequence",
+        "merged_regions": "true",
+    }
+    if repeated_signature:
+        facts["pattern"] = BLOCK_PATTERN_REPEATED_STMT_HASH
+        facts["pattern_label"] = BLOCK_PATTERN_REPEATED_STMT_HASH
+        facts["pattern_display"] = f"{signature_parts[0][:12]} x{window_size}"
+    return facts
+
+
+def _enrich_with_assert_facts(
+    *,
+    facts: dict[str, str],
+    items: list[GroupItem],
+    ast_cache: dict[str, ast.AST | None],
+    range_cache: dict[tuple[str, int, int], tuple[int, int, int]],
+) -> None:
+    assert_only = True
+    total_statements = 0
+    assert_statements = 0
+    max_consecutive_asserts = 0
+
+    if not items:
+        assert_only = False
+
+    for item in items:
+        filepath = str(item.get("filepath", ""))
+        start_line = int(item.get("start_line", 0))
+        end_line = int(item.get("end_line", 0))
+
+        range_total = 0
+        range_assert = 0
+        range_max_consecutive = 0
+        if filepath and start_line > 0 and end_line > 0:
+            range_total, range_assert, range_max_consecutive = _assert_range_stats(
+                filepath=filepath,
+                start_line=start_line,
+                end_line=end_line,
+                ast_cache=ast_cache,
+                range_cache=range_cache,
+            )
+            total_statements += range_total
+            assert_statements += range_assert
+            max_consecutive_asserts = max(
+                max_consecutive_asserts, range_max_consecutive
+            )
+
+        if (
+            not filepath
+            or start_line <= 0
+            or end_line <= 0
+            or not _is_assert_only_range(
+                filepath=filepath,
+                start_line=start_line,
+                end_line=end_line,
+                ast_cache=ast_cache,
+                range_cache=range_cache,
+            )
+        ):
+            assert_only = False
+
+    if total_statements > 0:
+        ratio = round((assert_statements / total_statements) * 100)
+        facts["assert_ratio"] = f"{ratio}%"
+        facts["consecutive_asserts"] = str(max_consecutive_asserts)
+
+    if assert_only:
+        facts["hint"] = BLOCK_HINT_ASSERT_ONLY
+        facts["hint_label"] = BLOCK_HINT_ASSERT_ONLY_LABEL
+        facts["hint_confidence"] = BLOCK_HINT_CONFIDENCE_DETERMINISTIC
+        facts["hint_note"] = BLOCK_HINT_ASSERT_ONLY_NOTE
+
+
+def build_block_group_facts(block_groups: GroupMap) -> dict[str, dict[str, str]]:
+    """
+    Build deterministic explainability facts for block clone groups.
+
+    This is the source of truth for report-level block explanations.
+    Renderers (HTML/TXT/JSON) should only display these facts.
+    """
+    ast_cache: dict[str, ast.AST | None] = {}
+    range_cache: dict[tuple[str, int, int], tuple[int, int, int]] = {}
+    facts_by_group: dict[str, dict[str, str]] = {}
+
+    for group_key, items in block_groups.items():
+        facts = _base_block_facts(group_key)
+        _enrich_with_assert_facts(
+            facts=facts,
+            items=items,
+            ast_cache=ast_cache,
+            range_cache=range_cache,
+        )
+        group_arity = len(items)
+        peer_count = max(0, group_arity - 1)
+        facts["group_arity"] = str(group_arity)
+        facts["instance_peer_count"] = str(peer_count)
+        compare_note = resolve_group_compare_note(
+            group_arity=group_arity, peer_count=peer_count
+        )
+        if compare_note is not None:
+            facts["group_compare_note"] = compare_note
+        group_display_name = resolve_group_display_name(hint_id=facts.get("hint"))
+        if group_display_name is not None:
+            facts["group_display_name"] = group_display_name
+        facts_by_group[group_key] = facts
+
+    return facts_by_group
diff --git a/codeclone/_report_explain_contract.py b/codeclone/_report_explain_contract.py
new file mode 100644
index 0000000..543ad02
--- /dev/null
+++ b/codeclone/_report_explain_contract.py
@@ -0,0 +1,48 @@
+"""
+CodeClone — AST and CFG-based code clone detector for Python
+focused on architectural duplication.
+
+Copyright (c) 2026 Den Rozhnovskiy
+Licensed under the MIT License.
+"""
+
+from __future__ import annotations
+
+from typing import Final
+
+from .ui_messages import (
+    REPORT_BLOCK_GROUP_DISPLAY_NAME_ASSERT_PATTERN,
+    fmt_report_block_group_compare_note_n_way,
+)
+
+BLOCK_PATTERN_REPEATED_STMT_HASH: Final = "repeated_stmt_hash"
+
+BLOCK_HINT_ASSERT_ONLY: Final = "assert_only"
+BLOCK_HINT_ASSERT_ONLY_LABEL: Final = "Assert-only block"
+BLOCK_HINT_CONFIDENCE_DETERMINISTIC: Final = "deterministic"
+BLOCK_HINT_ASSERT_ONLY_NOTE: Final = (
+    "This block clone consists entirely of assert-only statements. "
+    "This often occurs in test suites."
+)
+
+
+def format_n_way_group_compare_note(*, peer_count: int) -> str:
+    return fmt_report_block_group_compare_note_n_way(peer_count=peer_count)
+
+
+def resolve_group_compare_note(*, group_arity: int, peer_count: int) -> str | None:
+    if group_arity > 2:
+        return format_n_way_group_compare_note(peer_count=peer_count)
+    return None
+
+
+def resolve_group_display_name(*, hint_id: str | None) -> str | None:
+    if hint_id == BLOCK_HINT_ASSERT_ONLY:
+        return REPORT_BLOCK_GROUP_DISPLAY_NAME_ASSERT_PATTERN
+    return None
+
+
+def format_group_instance_compare_meta(
+    *, instance_index: int, group_arity: int, peer_count: int
+) -> str:
+    return f"instance {instance_index}/{group_arity} • matches {peer_count} peers"
diff --git a/codeclone/_report_serialize.py b/codeclone/_report_serialize.py
index 54dcef5..9c1a576 100644
--- a/codeclone/_report_serialize.py
+++ b/codeclone/_report_serialize.py
@@ -9,23 +9,129 @@
 from __future__ import annotations
 
 import json
-from collections.abc import Mapping
-from typing import Any
+from collections.abc import Collection, Mapping
 
 from ._report_types import GroupItem, GroupMap
+from .contracts import REPORT_SCHEMA_VERSION
+
+FunctionRecord = tuple[int, str, int, int, int, int, str, str]
+BlockRecord = tuple[int, str, int, int, int]
+SegmentRecord = tuple[int, str, int, int, int, str, str]
+SplitLists = dict[str, list[str]]
+GroupsSplit = dict[str, SplitLists]
+
+GROUP_ITEM_LAYOUT: dict[str, list[str]] = {
+    "functions": [
+        "file_i",
+        "qualname",
+        "start",
+        "end",
+        "loc",
+        "stmt_count",
+        "fingerprint",
+        "loc_bucket",
+    ],
+    "blocks": ["file_i", "qualname", "start", "end", "size"],
+    "segments": [
+        "file_i",
+        "qualname",
+        "start",
+        "end",
+        "size",
+        "segment_hash",
+        "segment_sig",
+    ],
+}
+
+
+def _item_sort_key(item: GroupItem) -> tuple[str, int, int, str]:
+    return (
+        str(item.get("filepath", "")),
+        int(item.get("start_line", 0)),
+        int(item.get("end_line", 0)),
+        str(item.get("qualname", "")),
+    )
+
+
+def _collect_files(
+    *,
+    func_groups: GroupMap,
+    block_groups: GroupMap,
+    segment_groups: GroupMap,
+) -> list[str]:
+    files: set[str] = set()
+    for groups in (func_groups, block_groups, segment_groups):
+        for items in groups.values():
+            for item in items:
+                files.add(str(item.get("filepath", "")))
+    return sorted(files)
+
+
+def _encode_function_item(item: GroupItem, file_id: int) -> FunctionRecord:
+    return (
+        file_id,
+        str(item.get("qualname", "")),
+        int(item.get("start_line", 0)),
+        int(item.get("end_line", 0)),
+        int(item.get("loc", 0)),
+        int(item.get("stmt_count", 0)),
+        str(item.get("fingerprint", "")),
+        str(item.get("loc_bucket", "")),
+    )
+
+
+def _encode_block_item(item: GroupItem, file_id: int) -> BlockRecord:
+    return (
+        file_id,
+        str(item.get("qualname", "")),
+        int(item.get("start_line", 0)),
+        int(item.get("end_line", 0)),
+        int(item.get("size", 0)),
+    )
+
+
+def _encode_segment_item(item: GroupItem, file_id: int) -> SegmentRecord:
+    return (
+        file_id,
+        str(item.get("qualname", "")),
+        int(item.get("start_line", 0)),
+        int(item.get("end_line", 0)),
+        int(item.get("size", 0)),
+        str(item.get("segment_hash", "")),
+        str(item.get("segment_sig", "")),
+    )
+
+
+def _function_record_sort_key(record: FunctionRecord) -> tuple[int, str, int, int]:
+    return record[0], record[1], record[2], record[3]
+
+
+def _block_record_sort_key(record: BlockRecord) -> tuple[int, str, int, int]:
+    return record[0], record[1], record[2], record[3]
+
+
+def _segment_record_sort_key(record: SegmentRecord) -> tuple[int, str, int, int]:
+    return record[0], record[1], record[2], record[3]
+
+
+def _resolve_metric_value(item: GroupItem, metric_name: str) -> int:
+    raw_value = item.get(metric_name)
+    if raw_value is None:
+        fallback_metric = "size" if metric_name == "loc" else "loc"
+        raw_value = item.get(fallback_metric, 0)
+    return int(raw_value)
+
+
+def _baseline_is_trusted(meta: Mapping[str, object]) -> bool:
+    return (
+        meta.get("baseline_loaded") is True
+        and str(meta.get("baseline_status", "")).strip().lower() == "ok"
+    )
 
 
 def to_json(groups: GroupMap) -> str:
     def _sorted_items(items: list[GroupItem]) -> list[GroupItem]:
-        return sorted(
-            items,
-            key=lambda item: (
-                str(item.get("filepath", "")),
-                int(item.get("start_line", 0)),
-                int(item.get("end_line", 0)),
-                str(item.get("qualname", "")),
-            ),
-        )
+        return sorted(items, key=_item_sort_key)
 
     return json.dumps(
         {
@@ -47,46 +153,129 @@ def to_json_report(
     func_groups: GroupMap,
     block_groups: GroupMap,
     segment_groups: GroupMap,
-    meta: Mapping[str, Any] | None = None,
+    meta: Mapping[str, object] | None = None,
+    block_facts: Mapping[str, Mapping[str, str]] | None = None,
+    new_function_group_keys: Collection[str] | None = None,
+    new_block_group_keys: Collection[str] | None = None,
+    new_segment_group_keys: Collection[str] | None = None,
 ) -> str:
-    def _sorted_items(items: list[GroupItem]) -> list[GroupItem]:
-        return sorted(
-            items,
-            key=lambda item: (
-                str(item.get("filepath", "")),
-                int(item.get("start_line", 0)),
-                int(item.get("end_line", 0)),
-                str(item.get("qualname", "")),
-            ),
+    """
+    Serialize report JSON schema v1.1.
+
+    NEW/KNOWN split contract:
+    - if baseline is not trusted, all groups are NEW and KNOWN is empty
+    - if baseline is trusted, callers must pass `new_*_group_keys` computed by
+      the core baseline diff pipeline; keys absent from `new_*` are treated as KNOWN
+    """
+    meta_payload = dict(meta or {})
+    meta_payload["report_schema_version"] = REPORT_SCHEMA_VERSION
+
+    files = _collect_files(
+        func_groups=func_groups,
+        block_groups=block_groups,
+        segment_groups=segment_groups,
+    )
+    file_ids = {filepath: idx for idx, filepath in enumerate(files)}
+
+    function_groups: dict[str, list[FunctionRecord]] = {}
+    for group_key in sorted(func_groups):
+        function_records = [
+            _encode_function_item(item, file_ids[str(item.get("filepath", ""))])
+            for item in func_groups[group_key]
+        ]
+        function_groups[group_key] = sorted(
+            function_records, key=_function_record_sort_key
+        )
+
+    block_groups_out: dict[str, list[BlockRecord]] = {}
+    for group_key in sorted(block_groups):
+        block_records = [
+            _encode_block_item(item, file_ids[str(item.get("filepath", ""))])
+            for item in block_groups[group_key]
+        ]
+        block_groups_out[group_key] = sorted(block_records, key=_block_record_sort_key)
+
+    segment_groups_out: dict[str, list[SegmentRecord]] = {}
+    for group_key in sorted(segment_groups):
+        segment_records = [
+            _encode_segment_item(item, file_ids[str(item.get("filepath", ""))])
+            for item in segment_groups[group_key]
+        ]
+        segment_groups_out[group_key] = sorted(
+            segment_records, key=_segment_record_sort_key
         )
 
-    def _sorted_group_map(groups: GroupMap) -> GroupMap:
-        return {
-            k: _sorted_items(v)
-            for k, v in sorted(groups.items(), key=lambda kv: (-len(kv[1]), kv[0]))
+    baseline_trusted = _baseline_is_trusted(meta_payload)
+
+    def _split_for(
+        *,
+        keys: Collection[str],
+        new_keys: Collection[str] | None,
+    ) -> SplitLists:
+        sorted_keys = sorted(keys)
+        if not baseline_trusted:
+            return {"new": sorted_keys, "known": []}
+        if new_keys is None:
+            return {"new": sorted_keys, "known": []}
+        new_key_set = set(new_keys)
+        new_list = [group_key for group_key in sorted_keys if group_key in new_key_set]
+        known_list = [
+            group_key for group_key in sorted_keys if group_key not in new_key_set
+        ]
+        return {"new": new_list, "known": known_list}
+
+    groups_split: GroupsSplit = {
+        "functions": _split_for(
+            keys=function_groups.keys(),
+            new_keys=new_function_group_keys,
+        ),
+        "blocks": _split_for(
+            keys=block_groups_out.keys(),
+            new_keys=new_block_group_keys,
+        ),
+        "segments": _split_for(
+            keys=segment_groups_out.keys(),
+            new_keys=new_segment_group_keys,
+        ),
+    }
+    meta_payload["groups_counts"] = {
+        section_name: {
+            "total": len(section_split["new"]) + len(section_split["known"]),
+            "new": len(section_split["new"]),
+            "known": len(section_split["known"]),
         }
+        for section_name, section_split in groups_split.items()
+    }
 
-    meta_payload = dict(meta or {})
-    func_sorted = _sorted_group_map(func_groups)
-    block_sorted = _sorted_group_map(block_groups)
-    segment_sorted = _sorted_group_map(segment_groups)
-    return json.dumps(
-        {
-            "meta": meta_payload,
-            "function_clones": func_sorted,
-            "block_clones": block_sorted,
-            "segment_clones": segment_sorted,
-            # Backward-compatible keys.
-            "functions": func_sorted,
-            "blocks": block_sorted,
-            "segments": segment_sorted,
+    payload: dict[str, object] = {
+        "meta": meta_payload,
+        "files": files,
+        "groups": {
+            "functions": function_groups,
+            "blocks": block_groups_out,
+            "segments": segment_groups_out,
         },
+        "groups_split": groups_split,
+        "group_item_layout": GROUP_ITEM_LAYOUT,
+    }
+
+    if block_facts:
+        sorted_block_facts: dict[str, dict[str, str]] = {}
+        for group_key in sorted(block_facts):
+            sorted_block_facts[group_key] = {
+                fact_key: str(block_facts[group_key][fact_key])
+                for fact_key in sorted(block_facts[group_key])
+            }
+        payload["facts"] = {"blocks": sorted_block_facts}
+
+    return json.dumps(
+        payload,
         ensure_ascii=False,
         indent=2,
     )
 
 
-def to_text(groups: GroupMap) -> str:
+def to_text(groups: GroupMap, *, metric_name: str = "loc") -> str:
     lines: list[str] = []
     for i, (_, v) in enumerate(
         sorted(groups.items(), key=lambda kv: (-len(kv[1]), kv[0]))
@@ -105,56 +294,125 @@ def to_text(groups: GroupMap) -> str:
             [
                 f"- {item['qualname']} "
                 f"{item['filepath']}:{item['start_line']}-{item['end_line']} "
-                f"loc={item.get('loc', item.get('size'))}"
+                f"{metric_name}={_resolve_metric_value(item, metric_name)}"
                 for item in items
             ]
         )
     return "\n".join(lines).strip() + "\n"
 
 
-def _format_meta_text_value(value: Any) -> str:
+def _format_meta_text_value(value: object) -> str:
     if isinstance(value, bool):
         return "true" if value else "false"
     if value is None:
-        return "n/a"
+        return "(none)"
     text = str(value).strip()
-    return text if text else "n/a"
+    return text if text else "(none)"
 
 
 def to_text_report(
     *,
-    meta: Mapping[str, Any],
+    meta: Mapping[str, object],
     func_groups: GroupMap,
     block_groups: GroupMap,
     segment_groups: GroupMap,
+    new_function_group_keys: Collection[str] | None = None,
+    new_block_group_keys: Collection[str] | None = None,
+    new_segment_group_keys: Collection[str] | None = None,
 ) -> str:
+    """
+    Serialize deterministic TXT report.
+
+    NEW/KNOWN split follows the same contract as JSON v1.1.
+    """
+
+    baseline_trusted = _baseline_is_trusted(meta)
+
+    def _split_for(
+        *,
+        groups: GroupMap,
+        new_keys: Collection[str] | None,
+    ) -> SplitLists:
+        sorted_keys = sorted(groups.keys())
+        if not baseline_trusted:
+            return {"new": sorted_keys, "known": []}
+        if new_keys is None:
+            return {"new": sorted_keys, "known": []}
+        new_key_set = set(new_keys)
+        new_list = [group_key for group_key in sorted_keys if group_key in new_key_set]
+        known_list = [
+            group_key for group_key in sorted_keys if group_key not in new_key_set
+        ]
+        return {"new": new_list, "known": known_list}
+
+    groups_split: GroupsSplit = {
+        "functions": _split_for(groups=func_groups, new_keys=new_function_group_keys),
+        "blocks": _split_for(groups=block_groups, new_keys=new_block_group_keys),
+        "segments": _split_for(groups=segment_groups, new_keys=new_segment_group_keys),
+    }
+
     lines = [
         "REPORT METADATA",
+        "Report schema version: "
+        f"{_format_meta_text_value(meta.get('report_schema_version'))}",
         f"CodeClone version: {_format_meta_text_value(meta.get('codeclone_version'))}",
         f"Python version: {_format_meta_text_value(meta.get('python_version'))}",
+        f"Python tag: {_format_meta_text_value(meta.get('python_tag'))}",
         f"Baseline path: {_format_meta_text_value(meta.get('baseline_path'))}",
-        f"Baseline version: {_format_meta_text_value(meta.get('baseline_version'))}",
+        "Baseline fingerprint version: "
+        f"{_format_meta_text_value(meta.get('baseline_fingerprint_version'))}",
         "Baseline schema version: "
         f"{_format_meta_text_value(meta.get('baseline_schema_version'))}",
-        "Baseline Python version: "
-        f"{_format_meta_text_value(meta.get('baseline_python_version'))}",
+        "Baseline Python tag: "
+        f"{_format_meta_text_value(meta.get('baseline_python_tag'))}",
+        "Baseline generator name: "
+        f"{_format_meta_text_value(meta.get('baseline_generator_name'))}",
+        "Baseline generator version: "
+        f"{_format_meta_text_value(meta.get('baseline_generator_version'))}",
+        "Baseline payload sha256: "
+        f"{_format_meta_text_value(meta.get('baseline_payload_sha256'))}",
+        "Baseline payload verified: "
+        f"{_format_meta_text_value(meta.get('baseline_payload_sha256_verified'))}",
         f"Baseline loaded: {_format_meta_text_value(meta.get('baseline_loaded'))}",
         f"Baseline status: {_format_meta_text_value(meta.get('baseline_status'))}",
+        f"Cache path: {_format_meta_text_value(meta.get('cache_path'))}",
+        "Cache schema version: "
+        f"{_format_meta_text_value(meta.get('cache_schema_version'))}",
+        f"Cache status: {_format_meta_text_value(meta.get('cache_status'))}",
+        f"Cache used: {_format_meta_text_value(meta.get('cache_used'))}",
+        "Source IO skipped: "
+        f"{_format_meta_text_value(meta.get('files_skipped_source_io'))}",
     ]
-    if "cache_path" in meta:
-        lines.append(f"Cache path: {_format_meta_text_value(meta.get('cache_path'))}")
-    if "cache_used" in meta:
-        lines.append(f"Cache used: {_format_meta_text_value(meta.get('cache_used'))}")
-
-    sections = [
-        ("FUNCTION CLONES", func_groups),
-        ("BLOCK CLONES", block_groups),
-        ("SEGMENT CLONES", segment_groups),
-    ]
-    for title, groups in sections:
+
+    if not baseline_trusted:
+        lines.append("Note: baseline is untrusted; all groups are treated as NEW.")
+
+    sections = (
+        ("FUNCTION CLONES", "functions", func_groups, "loc"),
+        ("BLOCK CLONES", "blocks", block_groups, "size"),
+        ("SEGMENT CLONES", "segments", segment_groups, "size"),
+    )
+    for title, section_key, groups, metric_name in sections:
+        split = groups_split[section_key]
+        new_groups: GroupMap = {
+            group_key: groups[group_key]
+            for group_key in split["new"]
+            if group_key in groups
+        }
+        known_groups: GroupMap = {
+            group_key: groups[group_key]
+            for group_key in split["known"]
+            if group_key in groups
+        }
+
+        lines.append("")
+        lines.append(f"{title} (NEW) (groups={len(split['new'])})")
+        new_block = to_text(new_groups, metric_name=metric_name).rstrip()
+        lines.append(new_block if new_block else "(none)")
+
         lines.append("")
-        lines.append(title)
-        block = to_text(groups).rstrip()
-        lines.append(block if block else "(none)")
+        lines.append(f"{title} (KNOWN) (groups={len(split['known'])})")
+        known_block = to_text(known_groups, metric_name=metric_name).rstrip()
+        lines.append(known_block if known_block else "(none)")
 
     return "\n".join(lines).rstrip() + "\n"
diff --git a/codeclone/_report_types.py b/codeclone/_report_types.py
index 6fbe632..79a732f 100644
--- a/codeclone/_report_types.py
+++ b/codeclone/_report_types.py
@@ -10,5 +10,9 @@
 
 from typing import Any
 
+# Any: report items aggregate heterogeneous JSON-like payloads from multiple
+# pipelines (function/block/segment) and are narrowed at access sites.
 GroupItem = dict[str, Any]
+
+
 GroupMap = dict[str, list[GroupItem]]
diff --git a/codeclone/baseline.py b/codeclone/baseline.py
index 4e0894f..b63f88c 100644
--- a/codeclone/baseline.py
+++ b/codeclone/baseline.py
@@ -11,29 +11,101 @@
 import hashlib
 import hmac
 import json
+import os
+import re
+import sys
 from collections.abc import Mapping
 from datetime import datetime, timezone
+from enum import Enum
 from pathlib import Path
-from typing import Any
+from typing import Any, Final
 
 from . import __version__
+from .contracts import (
+    BASELINE_FINGERPRINT_VERSION,
+    BASELINE_SCHEMA_VERSION,
+)
 from .errors import BaselineValidationError
 
-BASELINE_SCHEMA_VERSION = 1
-MAX_BASELINE_SIZE_BYTES = 5 * 1024 * 1024
+# Any: baseline JSON parsing/serialization boundary. Values are validated
+# and narrowed before entering compatibility/integrity checks.
+
 BASELINE_GENERATOR = "codeclone"
+BASELINE_SCHEMA_MAJOR = 1
+BASELINE_SCHEMA_MAX_MINOR = 0
+MAX_BASELINE_SIZE_BYTES = 5 * 1024 * 1024
+
+
+class BaselineStatus(str, Enum):
+    OK = "ok"
+    MISSING = "missing"
+    TOO_LARGE = "too_large"
+    INVALID_JSON = "invalid_json"
+    INVALID_TYPE = "invalid_type"
+    MISSING_FIELDS = "missing_fields"
+    MISMATCH_SCHEMA_VERSION = "mismatch_schema_version"
+    MISMATCH_FINGERPRINT_VERSION = "mismatch_fingerprint_version"
+    MISMATCH_PYTHON_VERSION = "mismatch_python_version"
+    GENERATOR_MISMATCH = "generator_mismatch"
+    INTEGRITY_MISSING = "integrity_missing"
+    INTEGRITY_FAILED = "integrity_failed"
+
+
+BASELINE_UNTRUSTED_STATUSES: Final[frozenset[BaselineStatus]] = frozenset(
+    {
+        BaselineStatus.MISSING,
+        BaselineStatus.TOO_LARGE,
+        BaselineStatus.INVALID_JSON,
+        BaselineStatus.INVALID_TYPE,
+        BaselineStatus.MISSING_FIELDS,
+        BaselineStatus.MISMATCH_SCHEMA_VERSION,
+        BaselineStatus.MISMATCH_FINGERPRINT_VERSION,
+        BaselineStatus.MISMATCH_PYTHON_VERSION,
+        BaselineStatus.GENERATOR_MISMATCH,
+        BaselineStatus.INTEGRITY_MISSING,
+        BaselineStatus.INTEGRITY_FAILED,
+    }
+)
+
+
+def coerce_baseline_status(
+    raw_status: str | BaselineStatus | None,
+) -> BaselineStatus:
+    if isinstance(raw_status, BaselineStatus):
+        return raw_status
+    if isinstance(raw_status, str):
+        try:
+            return BaselineStatus(raw_status)
+        except ValueError:
+            return BaselineStatus.INVALID_TYPE
+    return BaselineStatus.INVALID_TYPE
+
+
+_TOP_LEVEL_KEYS = {"meta", "clones"}
+_META_REQUIRED_KEYS = {
+    "generator",
+    "schema_version",
+    "fingerprint_version",
+    "python_tag",
+    "created_at",
+    "payload_sha256",
+}
+_CLONES_REQUIRED_KEYS = {"functions", "blocks"}
+_FUNCTION_ID_RE = re.compile(r"^[0-9a-f]{40}\|(?:\d+-\d+|\d+\+)$")
+_BLOCK_ID_RE = re.compile(r"^[0-9a-f]{40}\|[0-9a-f]{40}\|[0-9a-f]{40}\|[0-9a-f]{40}$")
 
 
 class Baseline:
     __slots__ = (
-        "baseline_version",
         "blocks",
         "created_at",
+        "fingerprint_version",
         "functions",
         "generator",
+        "generator_version",
         "path",
         "payload_sha256",
-        "python_version",
+        "python_tag",
         "schema_version",
     )
 
@@ -41,104 +113,207 @@ def __init__(self, path: str | Path):
         self.path = Path(path)
         self.functions: set[str] = set()
         self.blocks: set[str] = set()
-        self.python_version: str | None = None
-        self.baseline_version: str | None = None
-        self.schema_version: int | None = None
         self.generator: str | None = None
-        self.payload_sha256: str | None = None
+        self.schema_version: str | None = None
+        self.fingerprint_version: str | None = None
+        self.python_tag: str | None = None
         self.created_at: str | None = None
+        self.payload_sha256: str | None = None
+        self.generator_version: str | None = None
 
     def load(self, *, max_size_bytes: int | None = None) -> None:
-        if not self.path.exists():
-            return
-        size_limit = (
-            MAX_BASELINE_SIZE_BYTES if max_size_bytes is None else max_size_bytes
-        )
-
         try:
-            size = self.path.stat().st_size
+            exists = self.path.exists()
         except OSError as e:
             raise BaselineValidationError(
-                f"Cannot stat baseline file at {self.path}: {e}"
+                f"Cannot stat baseline file at {self.path}: {e}",
+                status=BaselineStatus.INVALID_TYPE,
             ) from e
+        if not exists:
+            return
+
+        size_limit = (
+            MAX_BASELINE_SIZE_BYTES if max_size_bytes is None else max_size_bytes
+        )
+        size = _safe_stat_size(self.path)
         if size > size_limit:
             raise BaselineValidationError(
                 "Baseline file is too large "
-                f"({size} bytes, max {size_limit} bytes) at {self.path}",
-                status="too_large",
+                f"({size} bytes, max {size_limit} bytes) at {self.path}. "
+                "Increase --max-baseline-size-mb or regenerate baseline.",
+                status=BaselineStatus.TOO_LARGE,
             )
 
-        try:
-            data = json.loads(self.path.read_text("utf-8"))
-        except json.JSONDecodeError as e:
+        payload = _load_json_object(self.path)
+        if _is_legacy_baseline_payload(payload):
             raise BaselineValidationError(
-                f"Corrupted baseline file at {self.path}: {e}"
-            ) from e
+                "Baseline format is legacy (<=1.3.x) and must be regenerated. "
+                "Please run --update-baseline.",
+                status=BaselineStatus.MISSING_FIELDS,
+            )
+
+        _validate_top_level_structure(payload, path=self.path)
 
-        if not isinstance(data, dict):
+        meta_obj = payload.get("meta")
+        clones_obj = payload.get("clones")
+        if not isinstance(meta_obj, dict):
+            raise BaselineValidationError(
+                f"Invalid baseline schema at {self.path}: 'meta' must be object",
+                status=BaselineStatus.INVALID_TYPE,
+            )
+        if not isinstance(clones_obj, dict):
             raise BaselineValidationError(
-                f"Baseline payload must be an object at {self.path}"
+                f"Invalid baseline schema at {self.path}: 'clones' must be object",
+                status=BaselineStatus.INVALID_TYPE,
             )
 
-        functions = _require_str_list(data, "functions", path=self.path)
-        blocks = _require_str_list(data, "blocks", path=self.path)
-        python_version = _optional_str(data, "python_version", path=self.path)
-        baseline_version = _optional_str(data, "baseline_version", path=self.path)
-        schema_version = _optional_int(data, "schema_version", path=self.path)
-        generator = _optional_str_loose(data, "generator")
-        payload_sha256 = _optional_str_loose(data, "payload_sha256")
-        created_at = _optional_str(data, "created_at", path=self.path)
+        _validate_required_keys(meta_obj, _META_REQUIRED_KEYS, path=self.path)
+        _validate_required_keys(clones_obj, _CLONES_REQUIRED_KEYS, path=self.path)
+        _validate_exact_clone_keys(clones_obj, path=self.path)
+
+        generator, generator_version = _parse_generator_meta(meta_obj, path=self.path)
+        schema_version = _require_semver_str(meta_obj, "schema_version", path=self.path)
+        fingerprint_version = _require_str(
+            meta_obj, "fingerprint_version", path=self.path
+        )
+        python_tag = _require_python_tag(meta_obj, "python_tag", path=self.path)
+        created_at = _require_utc_iso8601_z(meta_obj, "created_at", path=self.path)
+        payload_sha256 = _require_str(meta_obj, "payload_sha256", path=self.path)
+
+        function_ids = _require_sorted_unique_ids(
+            clones_obj,
+            "functions",
+            pattern=_FUNCTION_ID_RE,
+            path=self.path,
+        )
+        block_ids = _require_sorted_unique_ids(
+            clones_obj,
+            "blocks",
+            pattern=_BLOCK_ID_RE,
+            path=self.path,
+        )
 
-        self.functions = set(functions)
-        self.blocks = set(blocks)
-        self.python_version = python_version
-        self.baseline_version = baseline_version
-        self.schema_version = schema_version
         self.generator = generator
-        self.payload_sha256 = payload_sha256
+        self.schema_version = schema_version
+        self.fingerprint_version = fingerprint_version
+        self.python_tag = python_tag
         self.created_at = created_at
+        self.payload_sha256 = payload_sha256
+        self.generator_version = generator_version
+        self.functions = set(function_ids)
+        self.blocks = set(block_ids)
 
     def save(self) -> None:
         self.path.parent.mkdir(parents=True, exist_ok=True)
-        now_utc = datetime.now(timezone.utc).replace(microsecond=0).isoformat()
-        self.path.write_text(
-            json.dumps(
-                _baseline_payload(
-                    self.functions,
-                    self.blocks,
-                    self.python_version,
-                    self.baseline_version,
-                    self.schema_version,
-                    self.generator,
-                    now_utc,
-                ),
-                indent=2,
-                ensure_ascii=False,
-            ),
-            "utf-8",
-        )
-
-    def is_legacy_format(self) -> bool:
-        return self.baseline_version is None or self.schema_version is None
+        payload = _baseline_payload(
+            functions=self.functions,
+            blocks=self.blocks,
+            generator=self.generator,
+            schema_version=self.schema_version,
+            fingerprint_version=self.fingerprint_version,
+            python_tag=self.python_tag,
+            generator_version=self.generator_version,
+            created_at=self.created_at,
+        )
+        _atomic_write_json(self.path, payload)
 
-    def verify_integrity(self) -> None:
-        if self.is_legacy_format():
-            return
+    def verify_compatibility(self, *, current_python_tag: str) -> None:
         if self.generator != BASELINE_GENERATOR:
             raise BaselineValidationError(
                 "Baseline generator mismatch: expected 'codeclone'.",
-                status="generator_mismatch",
+                status=BaselineStatus.GENERATOR_MISMATCH,
+            )
+        if self.schema_version is None:
+            raise BaselineValidationError(
+                "Baseline schema version is missing.",
+                status=BaselineStatus.MISSING_FIELDS,
+            )
+        if self.fingerprint_version is None:
+            raise BaselineValidationError(
+                "Baseline fingerprint version is missing.",
+                status=BaselineStatus.MISSING_FIELDS,
+            )
+        if self.python_tag is None:
+            raise BaselineValidationError(
+                "Baseline python_tag is missing.",
+                status=BaselineStatus.MISSING_FIELDS,
+            )
+
+        schema_major, schema_minor, _ = _parse_semver(
+            self.schema_version, key="schema_version", path=self.path
+        )
+        if schema_major != BASELINE_SCHEMA_MAJOR:
+            raise BaselineValidationError(
+                "Baseline schema version mismatch: "
+                f"baseline={self.schema_version}, "
+                f"supported_major={BASELINE_SCHEMA_MAJOR}.",
+                status=BaselineStatus.MISMATCH_SCHEMA_VERSION,
+            )
+        if schema_minor > BASELINE_SCHEMA_MAX_MINOR:
+            raise BaselineValidationError(
+                "Baseline schema version is newer than supported: "
+                f"baseline={self.schema_version}, "
+                f"max=1.{BASELINE_SCHEMA_MAX_MINOR}.",
+                status=BaselineStatus.MISMATCH_SCHEMA_VERSION,
+            )
+        if self.fingerprint_version != BASELINE_FINGERPRINT_VERSION:
+            raise BaselineValidationError(
+                "Baseline fingerprint version mismatch: "
+                f"baseline={self.fingerprint_version}, "
+                f"expected={BASELINE_FINGERPRINT_VERSION}.",
+                status=BaselineStatus.MISMATCH_FINGERPRINT_VERSION,
+            )
+        if self.python_tag != current_python_tag:
+            raise BaselineValidationError(
+                "Baseline python tag mismatch: "
+                f"baseline={self.python_tag}, current={current_python_tag}.",
+                status=BaselineStatus.MISMATCH_PYTHON_VERSION,
             )
+        self.verify_integrity()
+
+    def verify_integrity(self) -> None:
         if not isinstance(self.payload_sha256, str):
             raise BaselineValidationError(
                 "Baseline integrity payload hash is missing.",
-                status="integrity_missing",
+                status=BaselineStatus.INTEGRITY_MISSING,
+            )
+        if len(self.payload_sha256) != 64:
+            raise BaselineValidationError(
+                "Baseline integrity payload hash is missing.",
+                status=BaselineStatus.INTEGRITY_MISSING,
+            )
+        try:
+            int(self.payload_sha256, 16)
+        except ValueError as e:
+            raise BaselineValidationError(
+                "Baseline integrity payload hash is missing.",
+                status=BaselineStatus.INTEGRITY_MISSING,
+            ) from e
+        if self.schema_version is None:
+            raise BaselineValidationError(
+                "Baseline schema version is missing for integrity validation.",
+                status=BaselineStatus.MISSING_FIELDS,
             )
-        expected = _compute_payload_sha256(self.functions, self.blocks)
+        if self.fingerprint_version is None:
+            raise BaselineValidationError(
+                "Baseline fingerprint version is missing for integrity validation.",
+                status=BaselineStatus.MISSING_FIELDS,
+            )
+        if self.python_tag is None:
+            raise BaselineValidationError(
+                "Baseline python_tag is missing for integrity validation.",
+                status=BaselineStatus.MISSING_FIELDS,
+            )
+        expected = _compute_payload_sha256(
+            functions=self.functions,
+            blocks=self.blocks,
+            fingerprint_version=self.fingerprint_version,
+            python_tag=self.python_tag,
+        )
         if not hmac.compare_digest(self.payload_sha256, expected):
             raise BaselineValidationError(
                 "Baseline integrity check failed: payload_sha256 mismatch.",
-                status="integrity_failed",
+                status=BaselineStatus.INTEGRITY_FAILED,
             )
 
     @staticmethod
@@ -146,18 +321,22 @@ def from_groups(
         func_groups: Mapping[str, object],
         block_groups: Mapping[str, object],
         path: str | Path = "",
-        python_version: str | None = None,
-        baseline_version: str | None = None,
-        schema_version: int | None = None,
+        schema_version: str | None = None,
+        fingerprint_version: str | None = None,
+        python_tag: str | None = None,
+        generator_version: str | None = None,
     ) -> Baseline:
-        bl = Baseline(path)
-        bl.functions = set(func_groups.keys())
-        bl.blocks = set(block_groups.keys())
-        bl.python_version = python_version
-        bl.baseline_version = baseline_version
-        bl.schema_version = schema_version
-        bl.generator = BASELINE_GENERATOR
-        return bl
+        baseline = Baseline(path)
+        baseline.functions = set(func_groups.keys())
+        baseline.blocks = set(block_groups.keys())
+        baseline.generator = BASELINE_GENERATOR
+        baseline.schema_version = schema_version or BASELINE_SCHEMA_VERSION
+        baseline.fingerprint_version = (
+            fingerprint_version or BASELINE_FINGERPRINT_VERSION
+        )
+        baseline.python_tag = python_tag or current_python_tag()
+        baseline.generator_version = generator_version or __version__
+        return baseline
 
     def diff(
         self, func_groups: Mapping[str, object], block_groups: Mapping[str, object]
@@ -167,39 +346,194 @@ def diff(
         return new_funcs, new_blocks
 
 
+def _atomic_write_json(path: Path, payload: dict[str, Any]) -> None:
+    tmp_path = path.with_name(f"{path.name}.tmp")
+    data = json.dumps(payload, indent=2, ensure_ascii=False) + "\n"
+    with tmp_path.open("wb") as tmp_file:
+        tmp_file.write(data.encode("utf-8"))
+        tmp_file.flush()
+        os.fsync(tmp_file.fileno())
+    os.replace(tmp_path, path)
+
+
+def _safe_stat_size(path: Path) -> int:
+    try:
+        return path.stat().st_size
+    except OSError as e:
+        raise BaselineValidationError(
+            f"Cannot stat baseline file at {path}: {e}",
+            status=BaselineStatus.INVALID_TYPE,
+        ) from e
+
+
+def _load_json_object(path: Path) -> dict[str, Any]:
+    try:
+        raw = path.read_text("utf-8")
+    except OSError as e:
+        raise BaselineValidationError(
+            f"Cannot read baseline file at {path}: {e}",
+            status=BaselineStatus.INVALID_JSON,
+        ) from e
+    try:
+        data = json.loads(raw)
+    except json.JSONDecodeError as e:
+        raise BaselineValidationError(
+            f"Corrupted baseline file at {path}: {e}",
+            status=BaselineStatus.INVALID_JSON,
+        ) from e
+    if not isinstance(data, dict):
+        raise BaselineValidationError(
+            f"Baseline payload must be an object at {path}",
+            status=BaselineStatus.INVALID_TYPE,
+        )
+    return data
+
+
+def _validate_top_level_structure(payload: dict[str, Any], *, path: Path) -> None:
+    keys = set(payload.keys())
+    missing = _TOP_LEVEL_KEYS - keys
+    extra = keys - _TOP_LEVEL_KEYS
+    if missing:
+        raise BaselineValidationError(
+            f"Invalid baseline schema at {path}: missing top-level keys: "
+            f"{', '.join(sorted(missing))}",
+            status=BaselineStatus.MISSING_FIELDS,
+        )
+    if extra:
+        raise BaselineValidationError(
+            f"Invalid baseline schema at {path}: unexpected top-level keys: "
+            f"{', '.join(sorted(extra))}",
+            status=BaselineStatus.INVALID_TYPE,
+        )
+
+
+def _validate_required_keys(
+    obj: dict[str, Any], required: set[str], *, path: Path
+) -> None:
+    missing = required - set(obj.keys())
+    if missing:
+        raise BaselineValidationError(
+            f"Invalid baseline schema at {path}: missing required fields: "
+            f"{', '.join(sorted(missing))}",
+            status=BaselineStatus.MISSING_FIELDS,
+        )
+
+
+def _validate_exact_clone_keys(clones: dict[str, Any], *, path: Path) -> None:
+    keys = set(clones.keys())
+    extra = keys - _CLONES_REQUIRED_KEYS
+    if extra:
+        raise BaselineValidationError(
+            f"Invalid baseline schema at {path}: unexpected clone keys: "
+            f"{', '.join(sorted(extra))}",
+            status=BaselineStatus.INVALID_TYPE,
+        )
+
+
+def _is_legacy_baseline_payload(payload: dict[str, Any]) -> bool:
+    return "functions" in payload and "blocks" in payload
+
+
+def _parse_generator_meta(
+    meta_obj: dict[str, Any], *, path: Path
+) -> tuple[str, str | None]:
+    raw_generator = meta_obj.get("generator")
+
+    if isinstance(raw_generator, str):
+        generator_version = _optional_str(meta_obj, "generator_version", path=path)
+        if generator_version is None:
+            # Legacy alias for baselines produced before generator_version rename.
+            generator_version = _optional_str(meta_obj, "codeclone_version", path=path)
+        return raw_generator, generator_version
+
+    if isinstance(raw_generator, dict):
+        allowed_keys = {"name", "version"}
+        extra = set(raw_generator.keys()) - allowed_keys
+        if extra:
+            raise BaselineValidationError(
+                f"Invalid baseline schema at {path}: unexpected generator keys: "
+                f"{', '.join(sorted(extra))}",
+                status=BaselineStatus.INVALID_TYPE,
+            )
+        generator_name = _require_str(raw_generator, "name", path=path)
+        generator_version = _optional_str(raw_generator, "version", path=path)
+
+        if generator_version is None:
+            generator_version = _optional_str(meta_obj, "generator_version", path=path)
+            if generator_version is None:
+                generator_version = _optional_str(
+                    meta_obj, "codeclone_version", path=path
+                )
+
+        return generator_name, generator_version
+
+    raise BaselineValidationError(
+        f"Invalid baseline schema at {path}: 'generator' must be string or object",
+        status=BaselineStatus.INVALID_TYPE,
+    )
+
+
 def _baseline_payload(
+    *,
     functions: set[str],
     blocks: set[str],
-    python_version: str | None,
-    baseline_version: str | None,
-    schema_version: int | None,
     generator: str | None,
+    schema_version: str | None,
+    fingerprint_version: str | None,
+    python_tag: str | None,
+    generator_version: str | None,
     created_at: str | None,
 ) -> dict[str, Any]:
-    payload: dict[str, Any] = _canonical_payload(functions, blocks)
-    if python_version:
-        payload["python_version"] = python_version
-    payload["baseline_version"] = baseline_version or __version__
-    payload["schema_version"] = (
-        schema_version if schema_version is not None else BASELINE_SCHEMA_VERSION
+    resolved_generator = generator or BASELINE_GENERATOR
+    resolved_schema = schema_version or BASELINE_SCHEMA_VERSION
+    resolved_fingerprint = fingerprint_version or BASELINE_FINGERPRINT_VERSION
+    resolved_python_tag = python_tag or current_python_tag()
+    resolved_generator_version = generator_version or __version__
+    resolved_created_at = created_at or _utc_now_z()
+
+    sorted_functions = sorted(functions)
+    sorted_blocks = sorted(blocks)
+    payload_sha256 = _compute_payload_sha256(
+        functions=set(sorted_functions),
+        blocks=set(sorted_blocks),
+        fingerprint_version=resolved_fingerprint,
+        python_tag=resolved_python_tag,
     )
-    payload["generator"] = generator or BASELINE_GENERATOR
-    payload["payload_sha256"] = _compute_payload_sha256(functions, blocks)
-    if created_at:
-        payload["created_at"] = created_at
-    return payload
 
-
-def _canonical_payload(functions: set[str], blocks: set[str]) -> dict[str, list[str]]:
     return {
-        "functions": sorted(functions),
-        "blocks": sorted(blocks),
+        "meta": {
+            "generator": {
+                "name": resolved_generator,
+                "version": resolved_generator_version,
+            },
+            "schema_version": resolved_schema,
+            "fingerprint_version": resolved_fingerprint,
+            "python_tag": resolved_python_tag,
+            "created_at": resolved_created_at,
+            "payload_sha256": payload_sha256,
+        },
+        "clones": {
+            "functions": sorted_functions,
+            "blocks": sorted_blocks,
+        },
     }
 
 
-def _compute_payload_sha256(functions: set[str], blocks: set[str]) -> str:
+def _compute_payload_sha256(
+    *,
+    functions: set[str],
+    blocks: set[str],
+    fingerprint_version: str,
+    python_tag: str,
+) -> str:
+    canonical = {
+        "blocks": sorted(blocks),
+        "fingerprint_version": fingerprint_version,
+        "functions": sorted(functions),
+        "python_tag": python_tag,
+    }
     serialized = json.dumps(
-        _canonical_payload(functions, blocks),
+        canonical,
         sort_keys=True,
         separators=(",", ":"),
         ensure_ascii=False,
@@ -207,39 +541,108 @@ def _compute_payload_sha256(functions: set[str], blocks: set[str]) -> str:
     return hashlib.sha256(serialized.encode("utf-8")).hexdigest()
 
 
-def _require_str_list(data: dict[str, Any], key: str, *, path: Path) -> list[str]:
-    value = data.get(key)
-    if not isinstance(value, list) or not all(isinstance(v, str) for v in value):
+def current_python_tag() -> str:
+    """Return the interpreter compatibility tag as an immutable string."""
+    impl = sys.implementation.name
+    major, minor = sys.version_info[:2]
+    prefix = "cp" if impl == "cpython" else impl[:2]
+    return f"{prefix}{major}{minor}"
+
+
+def _utc_now_z() -> str:
+    return (
+        datetime.now(timezone.utc).replace(microsecond=0).strftime("%Y-%m-%dT%H:%M:%SZ")
+    )
+
+
+def _require_str(obj: dict[str, Any], key: str, *, path: Path) -> str:
+    value = obj.get(key)
+    if not isinstance(value, str):
         raise BaselineValidationError(
-            f"Invalid baseline schema at {path}: '{key}' must be list[str]"
+            f"Invalid baseline schema at {path}: '{key}' must be string",
+            status=BaselineStatus.INVALID_TYPE,
         )
     return value
 
 
-def _optional_str(data: dict[str, Any], key: str, *, path: Path) -> str | None:
-    value = data.get(key)
+def _optional_str(obj: dict[str, Any], key: str, *, path: Path) -> str | None:
+    value = obj.get(key)
     if value is None:
         return None
     if not isinstance(value, str):
         raise BaselineValidationError(
-            f"Invalid baseline schema at {path}: '{key}' must be string"
+            f"Invalid baseline schema at {path}: '{key}' must be string",
+            status=BaselineStatus.INVALID_TYPE,
         )
     return value
 
 
-def _optional_int(data: dict[str, Any], key: str, *, path: Path) -> int | None:
-    value = data.get(key)
-    if value is None:
-        return None
-    if not isinstance(value, int):
+def _require_semver_str(obj: dict[str, Any], key: str, *, path: Path) -> str:
+    value = _require_str(obj, key, path=path)
+    _parse_semver(value, key=key, path=path)
+    return value
+
+
+def _parse_semver(value: str, *, key: str, path: Path) -> tuple[int, int, int]:
+    parts = value.split(".")
+    if len(parts) not in {2, 3} or not all(part.isdigit() for part in parts):
+        raise BaselineValidationError(
+            f"Invalid baseline schema at {path}: '{key}' must be semver string",
+            status=BaselineStatus.INVALID_TYPE,
+        )
+    if len(parts) == 2:
+        major, minor = int(parts[0]), int(parts[1])
+        patch = 0
+    else:
+        major, minor, patch = int(parts[0]), int(parts[1]), int(parts[2])
+    return major, minor, patch
+
+
+def _require_python_tag(obj: dict[str, Any], key: str, *, path: Path) -> str:
+    value = _require_str(obj, key, path=path)
+    if not re.fullmatch(r"[a-z]{2}\d{2,3}", value):
         raise BaselineValidationError(
-            f"Invalid baseline schema at {path}: '{key}' must be integer"
+            f"Invalid baseline schema at {path}: '{key}' must look like 'cp313'",
+            status=BaselineStatus.INVALID_TYPE,
         )
     return value
 
 
-def _optional_str_loose(data: dict[str, Any], key: str) -> str | None:
-    value = data.get(key)
-    if isinstance(value, str):
-        return value
-    return None
+def _require_utc_iso8601_z(obj: dict[str, Any], key: str, *, path: Path) -> str:
+    value = _require_str(obj, key, path=path)
+    try:
+        datetime.strptime(value, "%Y-%m-%dT%H:%M:%SZ")
+    except ValueError as e:
+        raise BaselineValidationError(
+            f"Invalid baseline schema at {path}: '{key}' must be UTC ISO-8601 with Z",
+            status=BaselineStatus.INVALID_TYPE,
+        ) from e
+    return value
+
+
+def _require_sorted_unique_ids(
+    obj: dict[str, Any], key: str, *, pattern: re.Pattern[str], path: Path
+) -> list[str]:
+    value = obj.get(key)
+    if not isinstance(value, list):
+        raise BaselineValidationError(
+            f"Invalid baseline schema at {path}: '{key}' must be list[str]",
+            status=BaselineStatus.INVALID_TYPE,
+        )
+    if not all(isinstance(item, str) for item in value):
+        raise BaselineValidationError(
+            f"Invalid baseline schema at {path}: '{key}' must be list[str]",
+            status=BaselineStatus.INVALID_TYPE,
+        )
+    values = list(value)
+    if values != sorted(values) or len(values) != len(set(values)):
+        raise BaselineValidationError(
+            f"Invalid baseline schema at {path}: '{key}' must be sorted and unique",
+            status=BaselineStatus.INVALID_TYPE,
+        )
+    if not all(pattern.fullmatch(item) for item in values):
+        raise BaselineValidationError(
+            f"Invalid baseline schema at {path}: '{key}' has invalid id format",
+            status=BaselineStatus.INVALID_TYPE,
+        )
+    return values
diff --git a/codeclone/cache.py b/codeclone/cache.py
index 566e82e..3753148 100644
--- a/codeclone/cache.py
+++ b/codeclone/cache.py
@@ -12,20 +12,34 @@
 import hmac
 import json
 import os
-import secrets
-from collections.abc import Mapping
-from dataclasses import asdict
+from collections.abc import Mapping, Sequence
+from enum import Enum
 from pathlib import Path
-from typing import TYPE_CHECKING, Any, TypedDict, cast
+from typing import TYPE_CHECKING, TypedDict
 
 if TYPE_CHECKING:
     from .blocks import BlockUnit, SegmentUnit
     from .extractor import Unit
 
+from .baseline import current_python_tag
+from .contracts import BASELINE_FINGERPRINT_VERSION, CACHE_VERSION
 from .errors import CacheError
 
-OS_NAME = os.name
 MAX_CACHE_SIZE_BYTES = 50 * 1024 * 1024
+LEGACY_CACHE_SECRET_FILENAME = ".cache_secret"
+
+
+class CacheStatus(str, Enum):
+    OK = "ok"
+    MISSING = "missing"
+    TOO_LARGE = "too_large"
+    UNREADABLE = "unreadable"
+    INVALID_JSON = "invalid_json"
+    INVALID_TYPE = "invalid_type"
+    VERSION_MISMATCH = "version_mismatch"
+    PYTHON_TAG_MISMATCH = "python_tag_mismatch"
+    FINGERPRINT_MISMATCH = "mismatch_fingerprint_version"
+    INTEGRITY_FAILED = "integrity_failed"
 
 
 class FileStat(TypedDict):
@@ -72,115 +86,331 @@ class CacheEntry(TypedDict):
 
 class CacheData(TypedDict):
     version: str
+    python_tag: str
+    fingerprint_version: str
     files: dict[str, CacheEntry]
 
 
 class Cache:
-    __slots__ = ("data", "load_warning", "max_size_bytes", "path", "secret")
-    CACHE_VERSION = "1.1"
+    __slots__ = (
+        "cache_schema_version",
+        "data",
+        "fingerprint_version",
+        "legacy_secret_warning",
+        "load_status",
+        "load_warning",
+        "max_size_bytes",
+        "path",
+        "root",
+    )
+
+    _CACHE_VERSION = CACHE_VERSION
 
-    def __init__(self, path: str | Path, *, max_size_bytes: int | None = None):
+    def __init__(
+        self,
+        path: str | Path,
+        *,
+        root: str | Path | None = None,
+        max_size_bytes: int | None = None,
+    ):
         self.path = Path(path)
-        self.data: CacheData = {"version": self.CACHE_VERSION, "files": {}}
-        self.secret = self._load_secret()
-        self.load_warning: str | None = None
+        self.root = _resolve_root(root)
+        self.fingerprint_version = BASELINE_FINGERPRINT_VERSION
+        self.data: CacheData = _empty_cache_data(
+            version=self._CACHE_VERSION,
+            python_tag=current_python_tag(),
+            fingerprint_version=self.fingerprint_version,
+        )
+        self.legacy_secret_warning = self._detect_legacy_secret_warning()
+        self.cache_schema_version: str | None = None
+        self.load_status = CacheStatus.MISSING
+        self.load_warning: str | None = self.legacy_secret_warning
         self.max_size_bytes = (
             MAX_CACHE_SIZE_BYTES if max_size_bytes is None else max_size_bytes
         )
 
-    def _load_secret(self) -> bytes:
-        """Load or create cache signing secret."""
-        # Store secret in the same directory as the cache file, named .cache_secret
-        # If cache is at ~/.cache/codeclone/cache.json, secret is
-        # ~/.cache/codeclone/.cache_secret
-        secret_path = self.path.parent / ".cache_secret"
-        if secret_path.exists():
-            return secret_path.read_bytes()
-        else:
-            secret = secrets.token_bytes(32)
-            try:
-                self.path.parent.mkdir(parents=True, exist_ok=True)
-                secret_path.write_bytes(secret)
-                # Set restrictive permissions on secret file (Unix only)
-                if OS_NAME == "posix":
-                    secret_path.chmod(0o600)
-            except OSError:
-                pass
-            return secret
-
-    def _sign_data(self, data: Mapping[str, Any]) -> str:
-        """Create HMAC signature of cache data."""
-        # Sort keys for deterministic JSON serialization
-        data_str = json.dumps(data, sort_keys=True)
-        return hmac.new(self.secret, data_str.encode(), hashlib.sha256).hexdigest()
+    def _detect_legacy_secret_warning(self) -> str | None:
+        secret_path = self.path.parent / LEGACY_CACHE_SECRET_FILENAME
+        try:
+            if secret_path.exists():
+                return (
+                    f"Legacy cache secret file detected at {secret_path}; "
+                    "delete this obsolete file."
+                )
+        except OSError as e:
+            return f"Legacy cache secret check failed: {e}"
+        return None
+
+    def _set_load_warning(self, message: str | None) -> None:
+        if message is None:
+            self.load_warning = self.legacy_secret_warning
+            return
+        if self.legacy_secret_warning:
+            self.load_warning = f"{message}\n{self.legacy_secret_warning}"
+            return
+        self.load_warning = message
+
+    def _ignore_cache(
+        self,
+        message: str,
+        *,
+        status: CacheStatus,
+        schema_version: str | None = None,
+    ) -> None:
+        self._set_load_warning(message)
+        self.load_status = status
+        self.cache_schema_version = schema_version
+        self.data = _empty_cache_data(
+            version=self._CACHE_VERSION,
+            python_tag=current_python_tag(),
+            fingerprint_version=self.fingerprint_version,
+        )
+
+    def _sign_data(self, data: Mapping[str, object]) -> str:
+        """Create deterministic SHA-256 signature for canonical payload data."""
+        canonical = _canonical_json(data)
+        return hashlib.sha256(canonical.encode("utf-8")).hexdigest()
 
     def load(self) -> None:
-        if not self.path.exists():
+        try:
+            exists = self.path.exists()
+        except OSError as e:
+            self._ignore_cache(
+                f"Cache unreadable; ignoring cache: {e}",
+                status=CacheStatus.UNREADABLE,
+            )
+            return
+
+        if not exists:
+            self._set_load_warning(None)
+            self.load_status = CacheStatus.MISSING
+            self.cache_schema_version = None
             return
 
         try:
             size = self.path.stat().st_size
             if size > self.max_size_bytes:
-                self.load_warning = (
+                self._ignore_cache(
                     "Cache file too large "
-                    f"({size} bytes, max {self.max_size_bytes}); ignoring cache."
+                    f"({size} bytes, max {self.max_size_bytes}); ignoring cache.",
+                    status=CacheStatus.TOO_LARGE,
                 )
-                self.data = {"version": self.CACHE_VERSION, "files": {}}
                 return
 
-            raw = json.loads(self.path.read_text("utf-8"))
-            stored_sig = raw.get("_signature")
+            raw_obj: object = json.loads(self.path.read_text("utf-8"))
+            parsed = self._parse_cache_document(raw_obj)
+            if parsed is None:
+                return
+            self.data = parsed
+            self.load_status = CacheStatus.OK
+            self._set_load_warning(None)
 
-            # Extract data without signature for verification
-            data = {k: v for k, v in raw.items() if k != "_signature"}
+        except OSError as e:
+            self._ignore_cache(
+                f"Cache unreadable; ignoring cache: {e}",
+                status=CacheStatus.UNREADABLE,
+            )
+        except json.JSONDecodeError:
+            self._ignore_cache(
+                "Cache corrupted; ignoring cache.",
+                status=CacheStatus.INVALID_JSON,
+            )
 
-            # Verify signature
-            expected_sig = self._sign_data(data)
-            if not (
-                isinstance(stored_sig, str)
-                and hmac.compare_digest(stored_sig, expected_sig)
-            ):
-                self.load_warning = "Cache signature mismatch; ignoring cache."
-                self.data = {"version": self.CACHE_VERSION, "files": {}}
-                return
+    def _parse_cache_document(self, raw_obj: object) -> CacheData | None:
+        raw = _as_str_dict(raw_obj)
+        if raw is None:
+            self._ignore_cache(
+                "Cache format invalid; ignoring cache.",
+                status=CacheStatus.INVALID_TYPE,
+            )
+            return None
 
-            if data.get("version") != self.CACHE_VERSION:
-                self.load_warning = (
-                    "Cache version mismatch "
-                    f"(found {data.get('version')}); ignoring cache."
-                )
-                self.data = {"version": self.CACHE_VERSION, "files": {}}
-                return
+        # Legacy cache format: top-level {version, files, _signature}.
+        legacy_version = _as_str(raw.get("version"))
+        if legacy_version is not None:
+            self._ignore_cache(
+                f"Cache version mismatch (found {legacy_version}); ignoring cache.",
+                status=CacheStatus.VERSION_MISMATCH,
+                schema_version=legacy_version,
+            )
+            return None
 
-            # Basic structure check
-            if not isinstance(data.get("files"), dict):
-                self.load_warning = "Cache format invalid; ignoring cache."
-                self.data = {"version": self.CACHE_VERSION, "files": {}}
-                return
+        version = _as_str(raw.get("v"))
+        if version is None:
+            self._ignore_cache(
+                "Cache format invalid; ignoring cache.",
+                status=CacheStatus.INVALID_TYPE,
+            )
+            return None
+
+        if version != self._CACHE_VERSION:
+            self._ignore_cache(
+                f"Cache version mismatch (found {version}); ignoring cache.",
+                status=CacheStatus.VERSION_MISMATCH,
+                schema_version=version,
+            )
+            return None
+
+        sig = _as_str(raw.get("sig"))
+        payload_obj = raw.get("payload")
+        payload = _as_str_dict(payload_obj)
+        if sig is None or payload is None:
+            self._ignore_cache(
+                "Cache format invalid; ignoring cache.",
+                status=CacheStatus.INVALID_TYPE,
+                schema_version=version,
+            )
+            return None
+
+        expected_sig = self._sign_data(payload)
+        if not hmac.compare_digest(sig, expected_sig):
+            self._ignore_cache(
+                "Cache signature mismatch; ignoring cache.",
+                status=CacheStatus.INTEGRITY_FAILED,
+                schema_version=version,
+            )
+            return None
 
-            self.data = cast(CacheData, cast(object, data))
-            self.load_warning = None
+        runtime_tag = current_python_tag()
+        py_tag = _as_str(payload.get("py"))
+        if py_tag is None:
+            self._ignore_cache(
+                "Cache format invalid; ignoring cache.",
+                status=CacheStatus.INVALID_TYPE,
+                schema_version=version,
+            )
+            return None
+
+        if py_tag != runtime_tag:
+            self._ignore_cache(
+                "Cache python tag mismatch "
+                f"(found {py_tag}, expected {runtime_tag}); ignoring cache.",
+                status=CacheStatus.PYTHON_TAG_MISMATCH,
+                schema_version=version,
+            )
+            return None
 
-        except (json.JSONDecodeError, ValueError):
-            self.load_warning = "Cache corrupted; ignoring cache."
-            self.data = {"version": self.CACHE_VERSION, "files": {}}
+        fp_version = _as_str(payload.get("fp"))
+        if fp_version is None:
+            self._ignore_cache(
+                "Cache format invalid; ignoring cache.",
+                status=CacheStatus.INVALID_TYPE,
+                schema_version=version,
+            )
+            return None
+
+        if fp_version != self.fingerprint_version:
+            self._ignore_cache(
+                "Cache fingerprint version mismatch "
+                f"(found {fp_version}, expected {self.fingerprint_version}); "
+                "ignoring cache.",
+                status=CacheStatus.FINGERPRINT_MISMATCH,
+                schema_version=version,
+            )
+            return None
+
+        files_obj = payload.get("files")
+        files_dict = _as_str_dict(files_obj)
+        if files_dict is None:
+            self._ignore_cache(
+                "Cache format invalid; ignoring cache.",
+                status=CacheStatus.INVALID_TYPE,
+                schema_version=version,
+            )
+            return None
+
+        parsed_files: dict[str, CacheEntry] = {}
+        for wire_path, file_entry_obj in files_dict.items():
+            runtime_path = self._runtime_filepath_from_wire(wire_path)
+            parsed_entry = _decode_wire_file_entry(file_entry_obj, runtime_path)
+            if parsed_entry is None:
+                self._ignore_cache(
+                    "Cache format invalid; ignoring cache.",
+                    status=CacheStatus.INVALID_TYPE,
+                    schema_version=version,
+                )
+                return None
+            parsed_files[runtime_path] = parsed_entry
+
+        self.cache_schema_version = version
+        return {
+            "version": self._CACHE_VERSION,
+            "python_tag": runtime_tag,
+            "fingerprint_version": self.fingerprint_version,
+            "files": parsed_files,
+        }
 
     def save(self) -> None:
         try:
             self.path.parent.mkdir(parents=True, exist_ok=True)
+            wire_files: dict[str, object] = {}
+            for runtime_path in sorted(
+                self.data["files"], key=self._wire_filepath_from_runtime
+            ):
+                entry = self.get_file_entry(runtime_path)
+                if entry is None:
+                    continue
+                wire_path = self._wire_filepath_from_runtime(runtime_path)
+                wire_files[wire_path] = _encode_wire_file_entry(entry)
+
+            payload: dict[str, object] = {
+                "py": current_python_tag(),
+                "fp": self.fingerprint_version,
+                "files": wire_files,
+            }
+            signed_doc = {
+                "v": self._CACHE_VERSION,
+                "payload": payload,
+                "sig": self._sign_data(payload),
+            }
+
+            tmp_path = self.path.with_name(f"{self.path.name}.tmp")
+            tmp_path.write_text(_canonical_json(signed_doc), "utf-8")
+            os.replace(tmp_path, self.path)
+
+            self.data["version"] = self._CACHE_VERSION
+            self.data["python_tag"] = current_python_tag()
+            self.data["fingerprint_version"] = self.fingerprint_version
 
-            # Add signature
-            data_with_sig = {**self.data, "_signature": self._sign_data(self.data)}
-
-            self.path.write_text(
-                json.dumps(data_with_sig, ensure_ascii=False, indent=2),
-                "utf-8",
-            )
         except OSError as e:
             raise CacheError(f"Failed to save cache: {e}") from e
 
+    def _wire_filepath_from_runtime(self, runtime_filepath: str) -> str:
+        runtime_path = Path(runtime_filepath)
+        if self.root is None:
+            return runtime_path.as_posix()
+
+        try:
+            relative = runtime_path.relative_to(self.root)
+            return relative.as_posix()
+        except ValueError:
+            pass
+
+        try:
+            relative = runtime_path.resolve().relative_to(self.root.resolve())
+            return relative.as_posix()
+        except OSError:
+            return runtime_path.as_posix()
+        except ValueError:
+            return runtime_path.as_posix()
+
+    def _runtime_filepath_from_wire(self, wire_filepath: str) -> str:
+        wire_path = Path(wire_filepath)
+        if self.root is None or wire_path.is_absolute():
+            return str(wire_path)
+
+        combined = self.root / wire_path
+        try:
+            return str(combined.resolve(strict=False))
+        except OSError:
+            return str(combined)
+
     def get_file_entry(self, filepath: str) -> CacheEntry | None:
         entry = self.data["files"].get(filepath)
+        if entry is None:
+            wire_key = self._wire_filepath_from_runtime(filepath)
+            runtime_key = self._runtime_filepath_from_wire(wire_key)
+            entry = self.data["files"].get(runtime_key)
 
         if entry is None:
             return None
@@ -214,13 +444,54 @@ def put_file_entry(
         blocks: list[BlockUnit],
         segments: list[SegmentUnit],
     ) -> None:
-        self.data["files"][filepath] = {
+        runtime_path = self._runtime_filepath_from_wire(
+            self._wire_filepath_from_runtime(filepath)
+        )
+
+        unit_rows: list[UnitDict] = [
+            {
+                "qualname": unit.qualname,
+                "filepath": runtime_path,
+                "start_line": unit.start_line,
+                "end_line": unit.end_line,
+                "loc": unit.loc,
+                "stmt_count": unit.stmt_count,
+                "fingerprint": unit.fingerprint,
+                "loc_bucket": unit.loc_bucket,
+            }
+            for unit in units
+        ]
+
+        block_rows: list[BlockDict] = [
+            {
+                "block_hash": block.block_hash,
+                "filepath": runtime_path,
+                "qualname": block.qualname,
+                "start_line": block.start_line,
+                "end_line": block.end_line,
+                "size": block.size,
+            }
+            for block in blocks
+        ]
+
+        segment_rows: list[SegmentDict] = [
+            {
+                "segment_hash": segment.segment_hash,
+                "segment_sig": segment.segment_sig,
+                "filepath": runtime_path,
+                "qualname": segment.qualname,
+                "start_line": segment.start_line,
+                "end_line": segment.end_line,
+                "size": segment.size,
+            }
+            for segment in segments
+        ]
+
+        self.data["files"][runtime_path] = {
             "stat": stat_sig,
-            "units": cast(list[UnitDict], cast(object, [asdict(u) for u in units])),
-            "blocks": cast(list[BlockDict], cast(object, [asdict(b) for b in blocks])),
-            "segments": cast(
-                list[SegmentDict], cast(object, [asdict(s) for s in segments])
-            ),
+            "units": unit_rows,
+            "blocks": block_rows,
+            "segments": segment_rows,
         }
 
 
@@ -232,6 +503,286 @@ def file_stat_signature(path: str) -> FileStat:
     }
 
 
+def _empty_cache_data(
+    *,
+    version: str,
+    python_tag: str,
+    fingerprint_version: str,
+) -> CacheData:
+    return {
+        "version": version,
+        "python_tag": python_tag,
+        "fingerprint_version": fingerprint_version,
+        "files": {},
+    }
+
+
+def _canonical_json(data: object) -> str:
+    return json.dumps(data, sort_keys=True, separators=(",", ":"), ensure_ascii=False)
+
+
+def _as_str(value: object) -> str | None:
+    return value if isinstance(value, str) else None
+
+
+def _as_int(value: object) -> int | None:
+    return value if isinstance(value, int) else None
+
+
+def _as_list(value: object) -> list[object] | None:
+    return value if isinstance(value, list) else None
+
+
+def _as_str_dict(value: object) -> dict[str, object] | None:
+    if not isinstance(value, dict):
+        return None
+    for key in value:
+        if not isinstance(key, str):
+            return None
+    return value
+
+
+def _decode_wire_file_entry(value: object, filepath: str) -> CacheEntry | None:
+    obj = _as_str_dict(value)
+    if obj is None:
+        return None
+
+    stat_obj = obj.get("st")
+    stat_list = _as_list(stat_obj)
+    if stat_list is None or len(stat_list) != 2:
+        return None
+    mtime_ns = _as_int(stat_list[0])
+    size = _as_int(stat_list[1])
+    if mtime_ns is None or size is None:
+        return None
+
+    units: list[UnitDict] = []
+    blocks: list[BlockDict] = []
+    segments: list[SegmentDict] = []
+
+    units_obj = obj.get("u")
+    if units_obj is not None:
+        units_list = _as_list(units_obj)
+        if units_list is None:
+            return None
+        for unit_obj in units_list:
+            decoded_unit = _decode_wire_unit(unit_obj, filepath)
+            if decoded_unit is None:
+                return None
+            units.append(decoded_unit)
+
+    blocks_obj = obj.get("b")
+    if blocks_obj is not None:
+        blocks_list = _as_list(blocks_obj)
+        if blocks_list is None:
+            return None
+        for block_obj in blocks_list:
+            decoded_block = _decode_wire_block(block_obj, filepath)
+            if decoded_block is None:
+                return None
+            blocks.append(decoded_block)
+
+    segments_obj = obj.get("s")
+    if segments_obj is not None:
+        segments_list = _as_list(segments_obj)
+        if segments_list is None:
+            return None
+        for segment_obj in segments_list:
+            decoded_segment = _decode_wire_segment(segment_obj, filepath)
+            if decoded_segment is None:
+                return None
+            segments.append(decoded_segment)
+
+    return {
+        "stat": {"mtime_ns": mtime_ns, "size": size},
+        "units": units,
+        "blocks": blocks,
+        "segments": segments,
+    }
+
+
+def _decode_wire_unit(value: object, filepath: str) -> UnitDict | None:
+    row = _as_list(value)
+    if row is None or len(row) != 7:
+        return None
+
+    qualname = _as_str(row[0])
+    start_line = _as_int(row[1])
+    end_line = _as_int(row[2])
+    loc = _as_int(row[3])
+    stmt_count = _as_int(row[4])
+    fingerprint = _as_str(row[5])
+    loc_bucket = _as_str(row[6])
+
+    if (
+        qualname is None
+        or start_line is None
+        or end_line is None
+        or loc is None
+        or stmt_count is None
+        or fingerprint is None
+        or loc_bucket is None
+    ):
+        return None
+
+    return {
+        "qualname": qualname,
+        "filepath": filepath,
+        "start_line": start_line,
+        "end_line": end_line,
+        "loc": loc,
+        "stmt_count": stmt_count,
+        "fingerprint": fingerprint,
+        "loc_bucket": loc_bucket,
+    }
+
+
+def _decode_wire_block(value: object, filepath: str) -> BlockDict | None:
+    row = _as_list(value)
+    if row is None or len(row) != 5:
+        return None
+
+    qualname = _as_str(row[0])
+    start_line = _as_int(row[1])
+    end_line = _as_int(row[2])
+    size = _as_int(row[3])
+    block_hash = _as_str(row[4])
+
+    if (
+        qualname is None
+        or start_line is None
+        or end_line is None
+        or size is None
+        or block_hash is None
+    ):
+        return None
+
+    return {
+        "block_hash": block_hash,
+        "filepath": filepath,
+        "qualname": qualname,
+        "start_line": start_line,
+        "end_line": end_line,
+        "size": size,
+    }
+
+
+def _decode_wire_segment(value: object, filepath: str) -> SegmentDict | None:
+    row = _as_list(value)
+    if row is None or len(row) != 6:
+        return None
+
+    qualname = _as_str(row[0])
+    start_line = _as_int(row[1])
+    end_line = _as_int(row[2])
+    size = _as_int(row[3])
+    segment_hash = _as_str(row[4])
+    segment_sig = _as_str(row[5])
+
+    if (
+        qualname is None
+        or start_line is None
+        or end_line is None
+        or size is None
+        or segment_hash is None
+        or segment_sig is None
+    ):
+        return None
+
+    return {
+        "segment_hash": segment_hash,
+        "segment_sig": segment_sig,
+        "filepath": filepath,
+        "qualname": qualname,
+        "start_line": start_line,
+        "end_line": end_line,
+        "size": size,
+    }
+
+
+def _encode_wire_file_entry(entry: CacheEntry) -> dict[str, object]:
+    wire: dict[str, object] = {
+        "st": [entry["stat"]["mtime_ns"], entry["stat"]["size"]],
+    }
+
+    units = sorted(
+        entry["units"],
+        key=lambda unit: (
+            unit["qualname"],
+            unit["start_line"],
+            unit["end_line"],
+            unit["fingerprint"],
+        ),
+    )
+    if units:
+        wire["u"] = [
+            [
+                unit["qualname"],
+                unit["start_line"],
+                unit["end_line"],
+                unit["loc"],
+                unit["stmt_count"],
+                unit["fingerprint"],
+                unit["loc_bucket"],
+            ]
+            for unit in units
+        ]
+
+    blocks = sorted(
+        entry["blocks"],
+        key=lambda block: (
+            block["qualname"],
+            block["start_line"],
+            block["end_line"],
+            block["block_hash"],
+        ),
+    )
+    if blocks:
+        wire["b"] = [
+            [
+                block["qualname"],
+                block["start_line"],
+                block["end_line"],
+                block["size"],
+                block["block_hash"],
+            ]
+            for block in blocks
+        ]
+
+    segments = sorted(
+        entry["segments"],
+        key=lambda segment: (
+            segment["qualname"],
+            segment["start_line"],
+            segment["end_line"],
+            segment["segment_hash"],
+        ),
+    )
+    if segments:
+        wire["s"] = [
+            [
+                segment["qualname"],
+                segment["start_line"],
+                segment["end_line"],
+                segment["size"],
+                segment["segment_hash"],
+                segment["segment_sig"],
+            ]
+            for segment in segments
+        ]
+
+    return wire
+
+
+def _resolve_root(root: str | Path | None) -> Path | None:
+    if root is None:
+        return None
+    try:
+        return Path(root).resolve(strict=False)
+    except OSError:
+        return None
+
+
 def _is_file_stat_dict(value: object) -> bool:
     if not isinstance(value, dict):
         return False
@@ -275,10 +826,10 @@ def _is_segment_list(value: object) -> bool:
 
 
 def _has_typed_fields(
-    value: dict[str, object],
+    value: Mapping[str, object],
     *,
-    string_keys: tuple[str, ...],
-    int_keys: tuple[str, ...],
+    string_keys: Sequence[str],
+    int_keys: Sequence[str],
 ) -> bool:
     return all(isinstance(value.get(key), str) for key in string_keys) and all(
         isinstance(value.get(key), int) for key in int_keys
diff --git a/codeclone/cli.py b/codeclone/cli.py
index 0ef5832..667197c 100644
--- a/codeclone/cli.py
+++ b/codeclone/cli.py
@@ -2,10 +2,11 @@
 
 import os
 import sys
-from concurrent.futures import ProcessPoolExecutor, as_completed
+from collections.abc import Mapping, Sequence
+from concurrent.futures import Future, ProcessPoolExecutor, as_completed
 from dataclasses import asdict, dataclass
 from pathlib import Path
-from typing import Any, cast
+from typing import TYPE_CHECKING, cast
 
 from rich.console import Console
 from rich.panel import Panel
@@ -21,30 +22,44 @@
 from . import __version__
 from . import ui_messages as ui
 from ._cli_args import build_parser
-from ._cli_meta import _build_report_meta as _build_report_meta_impl
-from ._cli_meta import _current_python_version as _current_python_version_impl
-from ._cli_paths import _validate_output_path as _validate_output_path_impl
-from ._cli_paths import expand_path as _expand_path_impl
-from ._cli_summary import _build_summary_rows as _build_summary_rows_impl
-from ._cli_summary import _build_summary_table as _build_summary_table_impl
-from ._cli_summary import _print_summary as _print_summary_impl
-from ._cli_summary import _summary_value_style as _summary_value_style_impl
-from .baseline import BASELINE_SCHEMA_VERSION, Baseline
-from .cache import Cache, CacheEntry, FileStat, file_stat_signature
+from ._cli_meta import _build_report_meta
+from ._cli_paths import _validate_output_path
+from ._cli_summary import _print_summary
+from ._report_types import GroupItem
+from .baseline import (
+    BASELINE_UNTRUSTED_STATUSES,
+    Baseline,
+    BaselineStatus,
+    coerce_baseline_status,
+    current_python_tag,
+)
+from .cache import Cache, CacheEntry, CacheStatus, FileStat, file_stat_signature
+from .contracts import (
+    BASELINE_FINGERPRINT_VERSION,
+    BASELINE_SCHEMA_VERSION,
+    ISSUES_URL,
+    ExitCode,
+)
 from .errors import BaselineValidationError, CacheError
 from .extractor import extract_units_from_source
 from .html_report import build_html_report
 from .normalize import NormalizationConfig
 from .report import (
+    build_block_group_facts,
     build_block_groups,
     build_groups,
     build_segment_groups,
+    prepare_block_report_groups,
     prepare_segment_report_groups,
     to_json_report,
     to_text_report,
 )
 from .scanner import iter_py_files, module_name_from_path
 
+if TYPE_CHECKING:
+    from .blocks import BlockUnit, SegmentUnit
+    from .extractor import Unit
+
 # Custom theme for Rich
 custom_theme = Theme(
     {
@@ -68,26 +83,6 @@ def _make_console(*, no_color: bool) -> Console:
 
 MAX_FILE_SIZE = 10 * 1024 * 1024  # 10MB
 BATCH_SIZE = 100
-_VALID_BASELINE_STATUSES = {
-    "ok",
-    "missing",
-    "legacy",
-    "invalid",
-    "mismatch_version",
-    "mismatch_schema",
-    "mismatch_python",
-    "generator_mismatch",
-    "integrity_missing",
-    "integrity_failed",
-    "too_large",
-}
-_UNTRUSTED_BASELINE_STATUSES = {
-    "invalid",
-    "too_large",
-    "generator_mismatch",
-    "integrity_missing",
-    "integrity_failed",
-}
 
 
 @dataclass(slots=True)
@@ -97,14 +92,11 @@ class ProcessingResult:
     filepath: str
     success: bool
     error: str | None = None
-    units: list[Any] | None = None
-    blocks: list[Any] | None = None
-    segments: list[Any] | None = None
+    units: list[Unit] | None = None
+    blocks: list[BlockUnit] | None = None
+    segments: list[SegmentUnit] | None = None
     stat: FileStat | None = None
-
-
-def expand_path(p: str) -> Path:
-    return _expand_path_impl(p)
+    error_kind: str | None = None
 
 
 def process_file(
@@ -138,17 +130,31 @@ def process_file(
                     filepath=filepath,
                     success=False,
                     error=f"File too large: {st_size} bytes (max {MAX_FILE_SIZE})",
+                    error_kind="file_too_large",
                 )
         except OSError as e:
             return ProcessingResult(
-                filepath=filepath, success=False, error=f"Cannot stat file: {e}"
+                filepath=filepath,
+                success=False,
+                error=f"Cannot stat file: {e}",
+                error_kind="stat_error",
             )
 
         try:
             source = Path(filepath).read_text("utf-8")
         except UnicodeDecodeError as e:
             return ProcessingResult(
-                filepath=filepath, success=False, error=f"Encoding error: {e}"
+                filepath=filepath,
+                success=False,
+                error=f"Encoding error: {e}",
+                error_kind="source_read_error",
+            )
+        except OSError as e:
+            return ProcessingResult(
+                filepath=filepath,
+                success=False,
+                error=f"Cannot read file: {e}",
+                error_kind="source_read_error",
             )
 
         stat = file_stat_signature(filepath)
@@ -177,115 +183,35 @@ def process_file(
             filepath=filepath,
             success=False,
             error=f"Unexpected error: {type(e).__name__}: {e}",
+            error_kind="unexpected_error",
         )
 
 
 def print_banner() -> None:
     console.print(
-        Panel.fit(
+        Panel(
             ui.banner_title(__version__),
             border_style="blue",
             padding=(0, 2),
+            width=ui.CLI_LAYOUT_WIDTH,
+            expand=False,
         )
     )
 
 
-def _validate_output_path(path: str, *, expected_suffix: str, label: str) -> Path:
-    return _validate_output_path_impl(
-        path,
-        expected_suffix=expected_suffix,
-        label=label,
-        console=console,
-        invalid_message=ui.fmt_invalid_output_extension,
-    )
-
-
-def _current_python_version() -> str:
-    return _current_python_version_impl()
-
-
-def _build_report_meta(
+def _is_debug_enabled(
     *,
-    baseline_path: Path,
-    baseline: Baseline,
-    baseline_loaded: bool,
-    baseline_status: str,
-    cache_path: Path,
-    cache_used: bool,
-) -> dict[str, Any]:
-    return _build_report_meta_impl(
-        codeclone_version=__version__,
-        baseline_path=baseline_path,
-        baseline=baseline,
-        baseline_loaded=baseline_loaded,
-        baseline_status=baseline_status,
-        cache_path=cache_path,
-        cache_used=cache_used,
-    )
-
-
-def _summary_value_style(*, label: str, value: int) -> str:
-    return _summary_value_style_impl(label=label, value=value)
+    argv: Sequence[str] | None = None,
+    environ: Mapping[str, str] | None = None,
+) -> bool:
+    args = list(sys.argv[1:] if argv is None else argv)
+    debug_from_flag = any(arg == "--debug" for arg in args)
+    env = os.environ if environ is None else environ
+    debug_from_env = env.get("CODECLONE_DEBUG") == "1"
+    return debug_from_flag or debug_from_env
 
 
-def _build_summary_rows(
-    *,
-    files_found: int,
-    files_analyzed: int,
-    cache_hits: int,
-    files_skipped: int,
-    func_clones_count: int,
-    block_clones_count: int,
-    segment_clones_count: int,
-    suppressed_segment_groups: int,
-    new_clones_count: int,
-) -> list[tuple[str, int]]:
-    return _build_summary_rows_impl(
-        files_found=files_found,
-        files_analyzed=files_analyzed,
-        cache_hits=cache_hits,
-        files_skipped=files_skipped,
-        func_clones_count=func_clones_count,
-        block_clones_count=block_clones_count,
-        segment_clones_count=segment_clones_count,
-        suppressed_segment_groups=suppressed_segment_groups,
-        new_clones_count=new_clones_count,
-    )
-
-
-def _build_summary_table(rows: list[tuple[str, int]]) -> Any:
-    return _build_summary_table_impl(rows)
-
-
-def _print_summary(
-    *,
-    quiet: bool,
-    files_found: int,
-    files_analyzed: int,
-    cache_hits: int,
-    files_skipped: int,
-    func_clones_count: int,
-    block_clones_count: int,
-    segment_clones_count: int,
-    suppressed_segment_groups: int,
-    new_clones_count: int,
-) -> None:
-    _print_summary_impl(
-        console=console,
-        quiet=quiet,
-        files_found=files_found,
-        files_analyzed=files_analyzed,
-        cache_hits=cache_hits,
-        files_skipped=files_skipped,
-        func_clones_count=func_clones_count,
-        block_clones_count=block_clones_count,
-        segment_clones_count=segment_clones_count,
-        suppressed_segment_groups=suppressed_segment_groups,
-        new_clones_count=new_clones_count,
-    )
-
-
-def main() -> None:
+def _main_impl() -> None:
     ap = build_parser(__version__)
 
     cache_path_from_args = any(
@@ -307,8 +233,10 @@ def main() -> None:
     console = _make_console(no_color=args.no_color)
 
     if args.max_baseline_size_mb < 0 or args.max_cache_size_mb < 0:
-        console.print("[error]Size limits must be non-negative integers (MB).[/error]")
-        sys.exit(1)
+        console.print(
+            ui.fmt_contract_error("Size limits must be non-negative integers (MB).")
+        )
+        sys.exit(ExitCode.CONTRACT_ERROR)
 
     if not args.quiet:
         print_banner()
@@ -316,11 +244,13 @@ def main() -> None:
     try:
         root_path = Path(args.root).resolve()
         if not root_path.exists():
-            console.print(ui.ERR_ROOT_NOT_FOUND.format(path=root_path))
-            sys.exit(1)
-    except Exception as e:
-        console.print(ui.ERR_INVALID_ROOT_PATH.format(error=e))
-        sys.exit(1)
+            console.print(
+                ui.fmt_contract_error(ui.ERR_ROOT_NOT_FOUND.format(path=root_path))
+            )
+            sys.exit(ExitCode.CONTRACT_ERROR)
+    except OSError as e:
+        console.print(ui.fmt_contract_error(ui.ERR_INVALID_ROOT_PATH.format(error=e)))
+        sys.exit(ExitCode.CONTRACT_ERROR)
 
     if not args.quiet:
         console.print(ui.fmt_scanning_root(root_path))
@@ -330,15 +260,30 @@ def main() -> None:
     text_out_path: Path | None = None
     if args.html_out:
         html_out_path = _validate_output_path(
-            args.html_out, expected_suffix=".html", label="HTML"
+            args.html_out,
+            expected_suffix=".html",
+            label="HTML",
+            console=console,
+            invalid_message=ui.fmt_invalid_output_extension,
+            invalid_path_message=ui.fmt_invalid_output_path,
         )
     if args.json_out:
         json_out_path = _validate_output_path(
-            args.json_out, expected_suffix=".json", label="JSON"
+            args.json_out,
+            expected_suffix=".json",
+            label="JSON",
+            console=console,
+            invalid_message=ui.fmt_invalid_output_extension,
+            invalid_path_message=ui.fmt_invalid_output_path,
         )
     if args.text_out:
         text_out_path = _validate_output_path(
-            args.text_out, expected_suffix=".txt", label="text"
+            args.text_out,
+            expected_suffix=".txt",
+            label="text",
+            console=console,
+            invalid_message=ui.fmt_invalid_output_extension,
+            invalid_path_message=ui.fmt_invalid_output_path,
         )
 
     # Initialize Cache
@@ -358,14 +303,18 @@ def main() -> None:
                         legacy_path=legacy_resolved, new_path=cache_path
                     )
                 )
-    cache = Cache(cache_path, max_size_bytes=args.max_cache_size_mb * 1024 * 1024)
+    cache = Cache(
+        cache_path,
+        root=root_path,
+        max_size_bytes=args.max_cache_size_mb * 1024 * 1024,
+    )
     cache.load()
     if cache.load_warning:
         console.print(f"[warning]{cache.load_warning}[/warning]")
 
-    all_units: list[dict[str, Any]] = []
-    all_blocks: list[dict[str, Any]] = []
-    all_segments: list[dict[str, Any]] = []
+    all_units: list[GroupItem] = []
+    all_blocks: list[GroupItem] = []
+    all_segments: list[GroupItem] = []
     files_found = 0
     files_analyzed = 0
     cache_hits = 0
@@ -395,7 +344,9 @@ def _safe_process_file(fp: str) -> ProcessingResult | None:
             console.print(ui.fmt_worker_failed(e))
             return None
 
-    def _safe_future_result(future: Any) -> tuple[ProcessingResult | None, str | None]:
+    def _safe_future_result(
+        future: Future[ProcessingResult],
+    ) -> tuple[ProcessingResult | None, str | None]:
         try:
             return future.result(), None
         except Exception as e:
@@ -415,19 +366,19 @@ def _safe_future_result(future: Any) -> tuple[ProcessingResult | None, str | Non
                     cache_hits += 1
                     all_units.extend(
                         cast(
-                            list[dict[str, Any]],
+                            list[GroupItem],
                             cast(object, cached.get("units", [])),
                         )
                     )
                     all_blocks.extend(
                         cast(
-                            list[dict[str, Any]],
+                            list[GroupItem],
                             cast(object, cached.get("blocks", [])),
                         )
                     )
                     all_segments.extend(
                         cast(
-                            list[dict[str, Any]],
+                            list[GroupItem],
                             cast(object, cached.get("segments", [])),
                         )
                     )
@@ -446,30 +397,31 @@ def _safe_future_result(future: Any) -> tuple[ProcessingResult | None, str | Non
                         cache_hits += 1
                         all_units.extend(
                             cast(
-                                list[dict[str, Any]],
+                                list[GroupItem],
                                 cast(object, cached.get("units", [])),
                             )
                         )
                         all_blocks.extend(
                             cast(
-                                list[dict[str, Any]],
+                                list[GroupItem],
                                 cast(object, cached.get("blocks", [])),
                             )
                         )
                         all_segments.extend(
                             cast(
-                                list[dict[str, Any]],
+                                list[GroupItem],
                                 cast(object, cached.get("segments", [])),
                             )
                         )
                     else:
                         files_to_process.append(fp)
-    except Exception as e:
-        console.print(ui.ERR_SCAN_FAILED.format(error=e))
-        sys.exit(1)
+    except OSError as e:
+        console.print(ui.fmt_contract_error(ui.ERR_SCAN_FAILED.format(error=e)))
+        sys.exit(ExitCode.CONTRACT_ERROR)
 
     total_files = len(files_to_process)
     failed_files = []
+    source_read_failures: list[str] = []
 
     # Processing phase
     if total_files > 0:
@@ -493,7 +445,10 @@ def handle_result(result: ProcessingResult) -> None:
                     all_segments.extend([asdict(s) for s in result.segments])
             else:
                 files_skipped += 1
-                failed_files.append(f"{result.filepath}: {result.error}")
+                failure = f"{result.filepath}: {result.error}"
+                failed_files.append(failure)
+                if result.error_kind == "source_read_error":
+                    source_read_failures.append(failure)
 
         def process_sequential(with_progress: bool) -> None:
             nonlocal files_skipped
@@ -623,6 +578,11 @@ def process_sequential(with_progress: bool) -> None:
         if len(failed_files) > 10:
             console.print(f"  ... and {len(failed_files) - 10} more")
 
+    gating_mode = args.fail_on_new or args.fail_threshold >= 0
+    source_read_contract_failure = (
+        bool(source_read_failures) and gating_mode and not args.update_baseline
+    )
+
     # Analysis phase
     suppressed_segment_groups = 0
     if args.quiet:
@@ -650,132 +610,136 @@ def process_sequential(with_progress: bool) -> None:
                 console.print(ui.fmt_cache_save_failed(e))
 
     # Reporting
+    block_groups_report = prepare_block_report_groups(block_groups)
+    block_group_facts = build_block_group_facts(block_groups_report)
     func_clones_count = len(func_groups)
     block_clones_count = len(block_groups)
     segment_clones_count = len(segment_groups)
 
     # Baseline Logic
-    baseline_path = Path(args.baseline).expanduser().resolve()
+    baseline_arg_path = Path(args.baseline).expanduser()
+    try:
+        baseline_path = baseline_arg_path.resolve()
+        baseline_exists = baseline_path.exists()
+    except OSError as e:
+        console.print(
+            ui.fmt_contract_error(
+                ui.fmt_invalid_baseline_path(path=baseline_arg_path, error=e)
+            )
+        )
+        sys.exit(ExitCode.CONTRACT_ERROR)
 
     # If user didn't specify path, the default is ./codeclone.baseline.json.
 
     baseline = Baseline(baseline_path)
-    baseline_exists = baseline_path.exists()
     baseline_loaded = False
-    baseline_status = "missing"
-    baseline_failure_code: int | None = None
+    baseline_status = BaselineStatus.MISSING
+    baseline_failure_code: ExitCode | None = None
     baseline_trusted_for_diff = False
 
     if baseline_exists:
         try:
             baseline.load(max_size_bytes=args.max_baseline_size_mb * 1024 * 1024)
         except BaselineValidationError as e:
-            baseline_status = (
-                e.status if e.status in _VALID_BASELINE_STATUSES else "invalid"
-            )
+            baseline_status = coerce_baseline_status(e.status)
             if not args.update_baseline:
                 console.print(ui.fmt_invalid_baseline(e))
                 if args.fail_on_new:
-                    baseline_failure_code = 2
+                    baseline_failure_code = ExitCode.CONTRACT_ERROR
                 else:
                     console.print(ui.WARN_BASELINE_IGNORED)
         else:
-            baseline_loaded = True
-            baseline_status = "ok"
-            baseline_trusted_for_diff = True
             if not args.update_baseline:
-                if baseline.is_legacy_format():
-                    baseline_status = "legacy"
-                    console.print(ui.fmt_baseline_version_missing(__version__))
-                    baseline_failure_code = 2
-                    baseline_trusted_for_diff = False
+                try:
+                    baseline.verify_compatibility(
+                        current_python_tag=current_python_tag()
+                    )
+                except BaselineValidationError as e:
+                    baseline_status = coerce_baseline_status(e.status)
+                    console.print(ui.fmt_invalid_baseline(e))
+                    if args.fail_on_new:
+                        baseline_failure_code = ExitCode.CONTRACT_ERROR
+                    else:
+                        console.print(ui.WARN_BASELINE_IGNORED)
                 else:
-                    if baseline.baseline_version != __version__:
-                        assert baseline.baseline_version is not None
-                        baseline_status = "mismatch_version"
-                        console.print(
-                            ui.fmt_baseline_version_mismatch(
-                                baseline_version=baseline.baseline_version,
-                                current_version=__version__,
-                            )
-                        )
-                        baseline_failure_code = 2
-                        baseline_trusted_for_diff = False
-                    if baseline.schema_version != BASELINE_SCHEMA_VERSION:
-                        assert baseline.schema_version is not None
-                        if baseline_status == "ok":
-                            baseline_status = "mismatch_schema"
-                        console.print(
-                            ui.fmt_baseline_schema_mismatch(
-                                baseline_schema=baseline.schema_version,
-                                current_schema=BASELINE_SCHEMA_VERSION,
-                            )
-                        )
-                        baseline_failure_code = 2
-                        baseline_trusted_for_diff = False
-                    if baseline.python_version:
-                        current_version = _current_python_version()
-                        if baseline.python_version != current_version:
-                            if baseline_status == "ok":
-                                baseline_status = "mismatch_python"
-                            console.print(
-                                ui.fmt_baseline_python_mismatch(
-                                    baseline_python=baseline.python_version,
-                                    current_python=current_version,
-                                )
-                            )
-                            if args.fail_on_new:
-                                console.print(ui.ERR_BASELINE_SAME_PYTHON_REQUIRED)
-                                baseline_failure_code = 2
-                                baseline_trusted_for_diff = False
-                    if baseline_status == "ok":
-                        try:
-                            baseline.verify_integrity()
-                        except BaselineValidationError as e:
-                            status = (
-                                e.status
-                                if e.status in _VALID_BASELINE_STATUSES
-                                else "invalid"
-                            )
-                            baseline_status = status
-                            console.print(ui.fmt_invalid_baseline(e))
-                            baseline_trusted_for_diff = False
-                            if args.fail_on_new:
-                                baseline_failure_code = 2
-                            else:
-                                console.print(ui.WARN_BASELINE_IGNORED)
-            if baseline_status in _UNTRUSTED_BASELINE_STATUSES:
-                baseline_loaded = False
-                baseline_trusted_for_diff = False
+                    baseline_loaded = True
+                    baseline_status = BaselineStatus.OK
+                    baseline_trusted_for_diff = True
     else:
         if not args.update_baseline:
             console.print(ui.fmt_path(ui.WARN_BASELINE_MISSING, baseline_path))
 
+    if baseline_status in BASELINE_UNTRUSTED_STATUSES:
+        baseline_loaded = False
+        baseline_trusted_for_diff = False
+        if args.fail_on_new and not args.update_baseline:
+            baseline_failure_code = ExitCode.CONTRACT_ERROR
+
     if args.update_baseline:
         new_baseline = Baseline.from_groups(
             func_groups,
             block_groups,
             path=baseline_path,
-            python_version=f"{sys.version_info.major}.{sys.version_info.minor}",
-            baseline_version=__version__,
+            python_tag=current_python_tag(),
+            fingerprint_version=BASELINE_FINGERPRINT_VERSION,
             schema_version=BASELINE_SCHEMA_VERSION,
+            generator_version=__version__,
         )
-        new_baseline.save()
+        try:
+            new_baseline.save()
+        except OSError as e:
+            console.print(
+                ui.fmt_contract_error(
+                    ui.fmt_baseline_write_failed(path=baseline_path, error=e)
+                )
+            )
+            sys.exit(ExitCode.CONTRACT_ERROR)
         console.print(ui.fmt_path(ui.SUCCESS_BASELINE_UPDATED, baseline_path))
         baseline = new_baseline
         baseline_loaded = True
-        baseline_status = "ok"
+        baseline_status = BaselineStatus.OK
         baseline_trusted_for_diff = True
         # When updating, we don't fail on new, we just saved the new state.
         # But we might still want to print the summary.
 
+    try:
+        report_cache_path = cache_path.resolve()
+    except OSError:
+        report_cache_path = cache_path
+
+    raw_cache_status = getattr(cache, "load_status", None)
+    if isinstance(raw_cache_status, CacheStatus):
+        cache_status = raw_cache_status
+    elif isinstance(raw_cache_status, str):
+        try:
+            cache_status = CacheStatus(raw_cache_status)
+        except ValueError:
+            cache_status = (
+                CacheStatus.OK
+                if cache.load_warning is None
+                else CacheStatus.INVALID_TYPE
+            )
+    else:
+        cache_status = (
+            CacheStatus.OK if cache.load_warning is None else CacheStatus.INVALID_TYPE
+        )
+
+    raw_cache_schema_version = getattr(cache, "cache_schema_version", None)
+    cache_schema_version = (
+        raw_cache_schema_version if isinstance(raw_cache_schema_version, str) else None
+    )
+
     report_meta = _build_report_meta(
+        codeclone_version=__version__,
         baseline_path=baseline_path,
         baseline=baseline,
         baseline_loaded=baseline_loaded,
-        baseline_status=baseline_status,
-        cache_path=cache_path.resolve(),
-        cache_used=cache.load_warning is None,
+        baseline_status=baseline_status.value,
+        cache_path=report_cache_path,
+        cache_used=cache_status == CacheStatus.OK,
+        cache_status=cache_status.value,
+        cache_schema_version=cache_schema_version,
+        files_skipped_source_io=len(source_read_failures),
     )
 
     # Diff
@@ -786,6 +750,7 @@ def process_sequential(with_progress: bool) -> None:
     new_clones_count = len(new_func) + len(new_block)
 
     _print_summary(
+        console=console,
         quiet=args.quiet,
         files_found=files_found,
         files_analyzed=files_analyzed,
@@ -811,48 +776,88 @@ def _print_output_notice(message: str) -> None:
             output_notice_printed = True
         console.print(message)
 
+    def _write_report_output(*, out: Path, content: str, label: str) -> None:
+        try:
+            out.parent.mkdir(parents=True, exist_ok=True)
+            out.write_text(content, "utf-8")
+        except OSError as e:
+            console.print(
+                ui.fmt_contract_error(
+                    ui.fmt_report_write_failed(label=label, path=out, error=e)
+                )
+            )
+            sys.exit(ExitCode.CONTRACT_ERROR)
+
     if html_out_path:
         out = html_out_path
-        out.parent.mkdir(parents=True, exist_ok=True)
-        out.write_text(
-            build_html_report(
+        _write_report_output(
+            out=out,
+            content=build_html_report(
                 func_groups=func_groups,
-                block_groups=block_groups,
+                block_groups=block_groups_report,
                 segment_groups=segment_groups,
+                block_group_facts=block_group_facts,
+                new_function_group_keys=new_func,
+                new_block_group_keys=new_block,
                 report_meta=report_meta,
                 title="CodeClone Report",
                 context_lines=3,
                 max_snippet_lines=220,
             ),
-            "utf-8",
+            label="HTML",
         )
         html_report_path = str(out)
         _print_output_notice(ui.fmt_path(ui.INFO_HTML_REPORT_SAVED, out))
 
     if json_out_path:
         out = json_out_path
-        out.parent.mkdir(parents=True, exist_ok=True)
-        out.write_text(
-            to_json_report(func_groups, block_groups, segment_groups, report_meta),
-            "utf-8",
+        _write_report_output(
+            out=out,
+            content=to_json_report(
+                func_groups,
+                block_groups_report,
+                segment_groups,
+                report_meta,
+                block_group_facts,
+                new_function_group_keys=new_func,
+                new_block_group_keys=new_block,
+                new_segment_group_keys=set(segment_groups.keys()),
+            ),
+            label="JSON",
         )
         _print_output_notice(ui.fmt_path(ui.INFO_JSON_REPORT_SAVED, out))
 
     if text_out_path:
         out = text_out_path
-        out.parent.mkdir(parents=True, exist_ok=True)
-        out.write_text(
-            to_text_report(
+        _write_report_output(
+            out=out,
+            content=to_text_report(
                 meta=report_meta,
                 func_groups=func_groups,
-                block_groups=block_groups,
+                block_groups=block_groups_report,
                 segment_groups=segment_groups,
+                new_function_group_keys=new_func,
+                new_block_group_keys=new_block,
+                new_segment_group_keys=set(segment_groups.keys()),
             ),
-            "utf-8",
+            label="text",
         )
         _print_output_notice(ui.fmt_path(ui.INFO_TEXT_REPORT_SAVED, out))
 
+    if source_read_contract_failure:
+        console.print(
+            ui.fmt_contract_error(
+                ui.fmt_unreadable_source_in_gating(count=len(source_read_failures))
+            )
+        )
+        for failure in source_read_failures[:10]:
+            console.print(f"  • {failure}")
+        if len(source_read_failures) > 10:
+            console.print(f"  ... and {len(source_read_failures) - 10} more")
+        sys.exit(ExitCode.CONTRACT_ERROR)
+
     if baseline_failure_code is not None:
+        console.print(ui.fmt_contract_error(ui.ERR_BASELINE_GATING_REQUIRES_TRUSTED))
         sys.exit(baseline_failure_code)
 
     # Exit Codes
@@ -861,6 +866,7 @@ def _print_output_notice(message: str) -> None:
         if html_report_path is None and default_report.exists():
             html_report_path = str(default_report)
 
+        console.print(ui.fmt_gating_failure("New code clones detected."))
         console.print(f"\n{ui.FAIL_NEW_TITLE}")
         console.print(f"\n{ui.FAIL_NEW_SUMMARY_TITLE}")
         console.print(ui.FAIL_NEW_FUNCTION.format(count=len(new_func)))
@@ -880,16 +886,36 @@ def _print_output_notice(message: str) -> None:
                 console.print(f"\n{ui.FAIL_NEW_DETAIL_BLOCK}")
                 for h in sorted(new_block):
                     console.print(f"- {h}")
-        sys.exit(3)
+        sys.exit(ExitCode.GATING_FAILURE)
 
     if 0 <= args.fail_threshold < (func_clones_count + block_clones_count):
         total = func_clones_count + block_clones_count
-        console.print(ui.fmt_fail_threshold(total=total, threshold=args.fail_threshold))
-        sys.exit(2)
+        console.print(
+            ui.fmt_gating_failure(
+                ui.fmt_fail_threshold(total=total, threshold=args.fail_threshold)
+            )
+        )
+        sys.exit(ExitCode.GATING_FAILURE)
 
     if not args.update_baseline and not args.fail_on_new and new_clones_count > 0:
         console.print(ui.WARN_NEW_CLONES_WITHOUT_FAIL)
 
 
+def main() -> None:
+    try:
+        _main_impl()
+    except SystemExit:
+        raise
+    except Exception as e:
+        console.print(
+            ui.fmt_internal_error(
+                e,
+                issues_url=ISSUES_URL,
+                debug=_is_debug_enabled(),
+            )
+        )
+        sys.exit(ExitCode.INTERNAL_ERROR)
+
+
 if __name__ == "__main__":
     main()
diff --git a/codeclone/contracts.py b/codeclone/contracts.py
new file mode 100644
index 0000000..d8b27a1
--- /dev/null
+++ b/codeclone/contracts.py
@@ -0,0 +1,64 @@
+"""
+CodeClone — AST and CFG-based code clone detector for Python
+focused on architectural duplication.
+
+Copyright (c) 2026 Den Rozhnovskiy
+Licensed under the MIT License.
+"""
+
+from __future__ import annotations
+
+from enum import IntEnum
+from typing import Final
+
+BASELINE_SCHEMA_VERSION: Final = "1.0"
+BASELINE_FINGERPRINT_VERSION: Final = "1"
+
+CACHE_VERSION: Final = "1.2"
+REPORT_SCHEMA_VERSION: Final = "1.1"
+
+
+class ExitCode(IntEnum):
+    SUCCESS = 0
+    CONTRACT_ERROR = 2
+    GATING_FAILURE = 3
+    INTERNAL_ERROR = 5
+
+
+REPOSITORY_URL: Final = "https://github.com/orenlab/codeclone"
+ISSUES_URL: Final = "https://github.com/orenlab/codeclone/issues"
+DOCS_URL: Final = "https://github.com/orenlab/codeclone/tree/main/docs"
+
+EXIT_CODE_DESCRIPTIONS: Final[tuple[tuple[ExitCode, str], ...]] = (
+    (ExitCode.SUCCESS, "success"),
+    (
+        ExitCode.CONTRACT_ERROR,
+        (
+            "contract error (baseline missing/untrusted, invalid output "
+            "extensions, incompatible versions, unreadable source files in CI/gating)"
+        ),
+    ),
+    (
+        ExitCode.GATING_FAILURE,
+        "gating failure (new clones detected, threshold exceeded)",
+    ),
+    (
+        ExitCode.INTERNAL_ERROR,
+        "internal error (unexpected exception; please report)",
+    ),
+)
+
+
+def cli_help_epilog() -> str:
+    lines = ["Exit codes"]
+    for code, description in EXIT_CODE_DESCRIPTIONS:
+        lines.append(f"  - {int(code)} - {description}")
+    lines.extend(
+        [
+            "",
+            f"Repository: {REPOSITORY_URL}",
+            f"Issues: {ISSUES_URL}",
+            f"Docs: {DOCS_URL}",
+        ]
+    )
+    return "\n".join(lines)
diff --git a/codeclone/errors.py b/codeclone/errors.py
index 11e32b8..87b8ffa 100644
--- a/codeclone/errors.py
+++ b/codeclone/errors.py
@@ -36,6 +36,6 @@ class BaselineValidationError(BaselineSchemaError):
 
     __slots__ = ("status",)
 
-    def __init__(self, message: str, *, status: str = "invalid") -> None:
+    def __init__(self, message: str, *, status: str = "invalid_type") -> None:
         super().__init__(message)
         self.status = status
diff --git a/codeclone/extractor.py b/codeclone/extractor.py
index d0a6236..d3b81c7 100644
--- a/codeclone/extractor.py
+++ b/codeclone/extractor.py
@@ -9,6 +9,7 @@
 from __future__ import annotations
 
 import ast
+import math
 import os
 import signal
 from collections.abc import Iterator
@@ -49,6 +50,17 @@ class _ParseTimeoutError(Exception):
     pass
 
 
+def _consumed_cpu_seconds(resource_module: object) -> float:
+    """Return consumed CPU seconds for the current process."""
+    try:
+        usage = resource_module.getrusage(  # type: ignore[attr-defined]
+            resource_module.RUSAGE_SELF  # type: ignore[attr-defined]
+        )
+        return float(usage.ru_utime) + float(usage.ru_stime)
+    except Exception:
+        return 0.0
+
+
 @contextmanager
 def _parse_limits(timeout_s: int) -> Iterator[None]:
     if os.name != "posix" or timeout_s <= 0:
@@ -70,11 +82,18 @@ def _timeout_handler(_signum: int, _frame: object) -> None:
 
             old_limits = resource.getrlimit(resource.RLIMIT_CPU)
             soft, hard = old_limits
-            hard_ceiling = timeout_s if hard == resource.RLIM_INFINITY else max(1, hard)
+            consumed_cpu_s = _consumed_cpu_seconds(resource)
+            desired_soft = max(1, timeout_s + math.ceil(consumed_cpu_s))
             if soft == resource.RLIM_INFINITY:
-                new_soft = min(timeout_s, hard_ceiling)
+                candidate_soft = desired_soft
+            else:
+                # Never reduce finite soft limits and avoid immediate SIGXCPU
+                # when the process already consumed more CPU than timeout_s.
+                candidate_soft = max(soft, desired_soft)
+            if hard == resource.RLIM_INFINITY:
+                new_soft = candidate_soft
             else:
-                new_soft = min(timeout_s, soft, hard_ceiling)
+                new_soft = min(max(1, hard), candidate_soft)
             # Never lower hard limit: raising it back may be disallowed for
             # unprivileged processes and can lead to process termination later.
             resource.setrlimit(resource.RLIMIT_CPU, (new_soft, hard))
diff --git a/codeclone/html_report.py b/codeclone/html_report.py
index c7ddf36..6540e47 100644
--- a/codeclone/html_report.py
+++ b/codeclone/html_report.py
@@ -8,7 +8,7 @@
 
 from __future__ import annotations
 
-from typing import Any
+from collections.abc import Collection, Mapping
 
 from . import __version__
 from ._html_escape import _escape_attr, _escape_html, _meta_display
@@ -20,6 +20,9 @@
     _try_pygments,
     pairwise,
 )
+from ._report_explain_contract import format_group_instance_compare_meta
+from ._report_types import GroupItem, GroupMap
+from .contracts import DOCS_URL, ISSUES_URL, REPOSITORY_URL
 from .templates import FONT_CSS_URL, REPORT_TEMPLATE
 
 __all__ = [
@@ -37,21 +40,51 @@
 # ============================
 
 
-def _group_sort_key(items: list[dict[str, Any]]) -> tuple[int]:
+def _group_sort_key(items: list[GroupItem]) -> tuple[int]:
     return (-len(items),)
 
 
 def build_html_report(
     *,
-    func_groups: dict[str, list[dict[str, Any]]],
-    block_groups: dict[str, list[dict[str, Any]]],
-    segment_groups: dict[str, list[dict[str, Any]]],
-    report_meta: dict[str, Any] | None = None,
+    func_groups: GroupMap,
+    block_groups: GroupMap,
+    segment_groups: GroupMap,
+    block_group_facts: dict[str, dict[str, str]],
+    new_function_group_keys: Collection[str] | None = None,
+    new_block_group_keys: Collection[str] | None = None,
+    report_meta: Mapping[str, object] | None = None,
     title: str = "CodeClone Report",
     context_lines: int = 3,
     max_snippet_lines: int = 220,
 ) -> str:
     file_cache = _FileCache()
+    resolved_block_group_facts = block_group_facts
+
+    def _path_basename(value: object) -> str | None:
+        if not isinstance(value, str):
+            return None
+        text = value.strip()
+        if not text:
+            return None
+        normalized = text.replace("\\", "/").rstrip("/")
+        if not normalized:
+            return None
+        return normalized.rsplit("/", maxsplit=1)[-1]
+
+    meta = dict(report_meta or {})
+    baseline_loaded = bool(meta.get("baseline_loaded"))
+    baseline_status = str(meta.get("baseline_status", "")).strip().lower()
+
+    if baseline_loaded and baseline_status == "ok":
+        baseline_split_note = (
+            "Split is based on baseline: known duplicates are already "
+            "recorded in baseline, new duplicates are absent from baseline."
+        )
+    else:
+        baseline_split_note = (
+            "Baseline is not loaded or not trusted: "
+            "all duplicates are treated as new versus an empty baseline."
+        )
 
     func_sorted = sorted(
         func_groups.items(), key=lambda kv: (*_group_sort_key(kv[1]), kv[0])
@@ -139,59 +172,208 @@ def _svg_icon(size: int, stroke_width: str, body: str) -> str:
     # Section renderer
     # ----------------------------
 
+    def _display_group_key(
+        section_id: str, group_key: str, block_meta: dict[str, str] | None = None
+    ) -> str:
+        if section_id != "blocks":
+            return group_key
+
+        if block_meta and block_meta.get("pattern_display"):
+            return str(block_meta["pattern_display"])
+
+        return group_key
+
+    def _block_group_explanation_meta(
+        section_id: str, group_key: str
+    ) -> dict[str, str]:
+        if section_id != "blocks":
+            return {}
+
+        raw = resolved_block_group_facts.get(group_key, {})
+        return {str(k): str(v) for k, v in raw.items() if v is not None}
+
+    def _render_group_explanation(meta: Mapping[str, object]) -> str:
+        if not meta:
+            return ""
+
+        explain_items: list[tuple[str, str]] = []
+        if meta.get("match_rule"):
+            explain_items.append(
+                (f"match_rule: {meta['match_rule']}", "group-explain-item")
+            )
+        if meta.get("block_size"):
+            explain_items.append(
+                (f"block_size: {meta['block_size']}", "group-explain-item")
+            )
+        if meta.get("signature_kind"):
+            explain_items.append(
+                (f"signature_kind: {meta['signature_kind']}", "group-explain-item")
+            )
+        if meta.get("merged_regions"):
+            explain_items.append(
+                (f"merged_regions: {meta['merged_regions']}", "group-explain-item")
+            )
+        pattern_value = str(meta.get("pattern", "")).strip()
+        if pattern_value:
+            pattern_label = str(meta.get("pattern_label", pattern_value)).strip()
+            pattern_display = str(meta.get("pattern_display", "")).strip()
+            if pattern_display:
+                explain_items.append(
+                    (
+                        f"pattern: {pattern_label} ({pattern_display})",
+                        "group-explain-item",
+                    )
+                )
+            else:
+                explain_items.append(
+                    (f"pattern: {pattern_label}", "group-explain-item")
+                )
+
+        hint_id = str(meta.get("hint", "")).strip()
+        if hint_id:
+            hint_label = str(meta.get("hint_label", hint_id)).strip()
+            explain_items.append(
+                (f"hint: {hint_label}", "group-explain-item group-explain-warn")
+            )
+            if meta.get("hint_confidence"):
+                explain_items.append(
+                    (
+                        f"hint_confidence: {meta['hint_confidence']}",
+                        "group-explain-item group-explain-muted",
+                    )
+                )
+            if meta.get("assert_ratio"):
+                explain_items.append(
+                    (
+                        f"assert_ratio: {meta['assert_ratio']}",
+                        "group-explain-item group-explain-muted",
+                    )
+                )
+            if meta.get("consecutive_asserts"):
+                explain_items.append(
+                    (
+                        f"consecutive_asserts: {meta['consecutive_asserts']}",
+                        "group-explain-item group-explain-muted",
+                    )
+                )
+            hint_context_label = str(meta.get("hint_context_label", "")).strip()
+            if hint_context_label:
+                explain_items.append(
+                    (
+                        hint_context_label,
+                        "group-explain-item group-explain-muted",
+                    )
+                )
+
+        attrs = {
+            "data-match-rule": str(meta.get("match_rule", "")),
+            "data-block-size": str(meta.get("block_size", "")),
+            "data-signature-kind": str(meta.get("signature_kind", "")),
+            "data-merged-regions": str(meta.get("merged_regions", "")),
+            "data-pattern": str(meta.get("pattern", "")),
+            "data-pattern-label": str(meta.get("pattern_label", "")),
+            "data-hint": str(meta.get("hint", "")),
+            "data-hint-label": str(meta.get("hint_label", "")),
+            "data-hint-context-label": str(meta.get("hint_context_label", "")),
+            "data-hint-confidence": str(meta.get("hint_confidence", "")),
+            "data-assert-ratio": str(meta.get("assert_ratio", "")),
+            "data-consecutive-asserts": str(meta.get("consecutive_asserts", "")),
+        }
+        attr_html = " ".join(
+            f'{key}="{_escape_attr(value)}"' for key, value in attrs.items() if value
+        )
+        parts = [
+            f'<span class="{css_class}">{_escape_html(text)}</span>'
+            for text, css_class in explain_items
+        ]
+        note = ""
+        if isinstance(meta.get("hint_note"), str):
+            note_text = _escape_html(str(meta["hint_note"]))
+            note = f'<p class="group-explain-note">{note_text}</p>'
+        return f'<div class="group-explain" {attr_html}>{"".join(parts)}{note}</div>'
+
     def render_section(
         section_id: str,
         section_title: str,
-        groups: list[tuple[str, list[dict[str, Any]]]],
+        groups: list[tuple[str, list[GroupItem]]],
         pill_cls: str,
+        *,
+        novelty_by_group: Mapping[str, str] | None = None,
     ) -> str:
         if not groups:
             return ""
 
-        # build group DOM with data-search (for fast client-side search)
+        def _block_group_name(display_key: str, meta: dict[str, str]) -> str:
+            if meta.get("group_display_name"):
+                return str(meta["group_display_name"])
+            if len(display_key) > 56:
+                return f"{display_key[:24]}...{display_key[-16:]}"
+            return display_key
+
+        def _group_name(display_key: str, meta: dict[str, str]) -> str:
+            if section_id == "blocks":
+                return _block_group_name(display_key, meta)
+            return display_key
+
+        def _item_span_size(item: GroupItem) -> int:
+            start_line = int(item.get("start_line", 0))
+            end_line = int(item.get("end_line", 0))
+            return max(0, end_line - start_line + 1)
+
+        def _group_span_size(items: list[GroupItem]) -> int:
+            return max((_item_span_size(item) for item in items), default=0)
+
+        section_novelty = novelty_by_group or {}
+        has_novelty_filter = bool(section_novelty)
+
         out: list[str] = [
-            f'<section id="{section_id}" class="section" data-section="{section_id}">',
-            '<div class="section-head">',
+            f'<section id="{section_id}" class="section" data-section="{section_id}" '
+            f'data-has-novelty-filter="{"true" if has_novelty_filter else "false"}">',
+            '<div class="section-title">',
             f"<h2>{_escape_html(section_title)} "
-            f'<span class="pill {pill_cls}" data-count-pill="{section_id}">'
+            f'<span class="count-pill" data-count-pill="{section_id}">'
             f"{len(groups)} groups</span></h2>",
+            "</div>",
             f"""
-<div class="section-toolbar"
-     role="toolbar"
-     aria-label="{_escape_attr(section_title)} controls">
+<div class="toolbar" role="toolbar" aria-label="{_escape_attr(section_title)} controls">
   <div class="toolbar-left">
-    <div class="search-wrap">
+    <div class="search-box">
       <span class="search-ico">{ICONS["search"]}</span>
-      <input class="search"
-             id="search-{section_id}"
-             placeholder="Search..."
-             autocomplete="off" />
-      <button class="btn ghost"
-              type="button"
-              data-clear="{section_id}"
-              title="Clear search">{ICONS["clear"]}</button>
-    </div>
-    <div class="segmented">
-      <button class="btn seg"
-              type="button"
-              data-collapse-all="{section_id}">Collapse</button>
-      <button class="btn seg"
-              type="button"
-              data-expand-all="{section_id}">Expand</button>
+      <input
+        type="text"
+        id="search-{section_id}"
+        placeholder="Search..."
+        autocomplete="off"
+      />
+      <button
+        class="clear-btn"
+        type="button"
+        data-clear="{section_id}"
+        title="Clear search"
+      >{ICONS["clear"]}</button>
     </div>
+    <button class="btn" type="button" data-collapse-all="{section_id}">Collapse</button>
+    <button class="btn" type="button" data-expand-all="{section_id}">Expand</button>
   </div>
 
   <div class="toolbar-right">
-    <div class="pager">
-      <button class="btn"
-              type="button"
-              data-prev="{section_id}">{ICONS["prev"]}</button>
-      <span class="page-meta" data-page-meta="{section_id}">Page 1</span>
-      <button class="btn"
-              type="button"
-              data-next="{section_id}">{ICONS["next"]}</button>
+    <div class="pagination">
+      <button class="btn" type="button" data-prev="{section_id}">
+        {ICONS["prev"]}
+      </button>
+      <span class="page-meta" data-page-meta="{section_id}">
+        Page 1 / 1 • {len(groups)} groups
+      </span>
+      <button class="btn" type="button" data-next="{section_id}">
+        {ICONS["next"]}
+      </button>
     </div>
-    <select class="select" data-pagesize="{section_id}" title="Groups per page">
+    <select
+      class="select"
+      data-pagesize="{section_id}"
+      aria-label="Items per page"
+      title="Groups per page"
+    >
       <option value="5">5 / page</option>
       <option value="10" selected>10 / page</option>
       <option value="20">20 / page</option>
@@ -200,80 +382,169 @@ def render_section(
   </div>
 </div>
 """,
-            "</div>",  # section-head
             '<div class="section-body">',
         ]
 
         for idx, (gkey, items) in enumerate(groups, start=1):
+            group_id = f"{section_id}-{idx}"
             search_parts: list[str] = [str(gkey)]
             for it in items:
                 search_parts.append(str(it.get("qualname", "")))
                 search_parts.append(str(it.get("filepath", "")))
             search_blob = " ".join(search_parts).lower()
             search_blob_escaped = _escape_attr(search_blob)
-
+            block_meta = _block_group_explanation_meta(section_id, gkey)
+            display_key = _display_group_key(section_id, gkey, block_meta)
+            group_name = _group_name(display_key, block_meta)
+            group_span_size = _group_span_size(items)
+            group_arity = len(items)
+            if section_id == "blocks":
+                block_size_raw = block_meta.get("block_size", "").strip()
+                if block_size_raw.isdigit():
+                    group_span_size = int(block_size_raw)
+                arity_raw = block_meta.get("group_arity", "").strip()
+                if arity_raw.isdigit() and int(arity_raw) > 0:
+                    group_arity = int(arity_raw)
+            group_summary = (
+                f"{group_arity} instances • block size {group_span_size}"
+                if group_span_size > 0
+                else f"{group_arity} instances"
+            )
+            block_group_attrs = ""
+            if block_meta:
+                attrs = {
+                    "data-group-id": group_id,
+                    "data-clone-size": str(group_span_size),
+                    "data-items-count": str(group_arity),
+                    "data-match-rule": block_meta.get("match_rule"),
+                    "data-block-size": block_meta.get("block_size"),
+                    "data-signature-kind": block_meta.get("signature_kind"),
+                    "data-merged-regions": block_meta.get("merged_regions"),
+                    "data-pattern": block_meta.get("pattern"),
+                    "data-pattern-label": block_meta.get("pattern_label"),
+                    "data-hint": block_meta.get("hint"),
+                    "data-hint-label": block_meta.get("hint_label"),
+                    "data-hint-context-label": block_meta.get("hint_context_label"),
+                    "data-hint-confidence": block_meta.get("hint_confidence"),
+                    "data-assert-ratio": block_meta.get("assert_ratio"),
+                    "data-consecutive-asserts": block_meta.get("consecutive_asserts"),
+                    "data-boilerplate-asserts": block_meta.get("boilerplate_asserts"),
+                }
+                block_group_attrs = " ".join(
+                    f'{name}="{_escape_attr(value)}"'
+                    for name, value in attrs.items()
+                    if value
+                )
+            if block_group_attrs:
+                block_group_attrs = f" {block_group_attrs}"
+            if 'data-group-id="' not in block_group_attrs:
+                group_id_attr = _escape_attr(group_id)
+                block_group_attrs = (
+                    f' data-group-id="{group_id_attr}"{block_group_attrs}'
+                )
+            if 'data-clone-size="' not in block_group_attrs:
+                clone_size_attr = _escape_attr(str(group_span_size))
+                block_group_attrs += f' data-clone-size="{clone_size_attr}"'
+            if 'data-items-count="' not in block_group_attrs:
+                items_count_attr = _escape_attr(str(group_arity))
+                block_group_attrs += f' data-items-count="{items_count_attr}"'
+            arity_attr = _escape_attr(str(group_arity))
+            block_group_attrs += f' data-group-arity="{arity_attr}"'
+
+            metrics_button = ""
+            if section_id == "blocks":
+                metrics_button = (
+                    f'<button class="btn ghost" type="button" '
+                    f'data-metrics-btn="{_escape_attr(group_id)}">Info</button>'
+                )
+            group_novelty = section_novelty.get(gkey, "all")
             out.append(
                 f'<div class="group" data-group="{section_id}" '
                 f'data-group-index="{idx}" '
                 f'data-group-key="{_escape_attr(gkey)}" '
-                f'data-search="{search_blob_escaped}">'
+                f'data-novelty="{_escape_attr(group_novelty)}" '
+                f'data-search="{search_blob_escaped}"{block_group_attrs}>'
             )
 
             out.append(
                 '<div class="group-head">'
-                '<div class="group-left">'
-                f'<button class="chev" type="button" aria-label="Toggle group" '
-                f'data-toggle-group="{section_id}-{idx}">{ICONS["chev_down"]}</button>'
-                f'<div class="group-title">Group #{idx}</div>'
-                f'<span class="pill small {pill_cls}">{len(items)} items</span>'
+                '<div class="group-head-left">'
+                f'<button class="group-toggle" type="button" aria-label="Toggle group" '
+                f'data-toggle-group="{group_id}">{ICONS["chev_down"]}</button>'
+                '<div class="group-info">'
+                f'<div class="group-name">{_escape_html(group_name)}</div>'
+                f'<div class="group-summary">{_escape_html(group_summary)}</div>'
                 "</div>"
-                '<div class="group-right">'
-                f'<code class="gkey" title="{_escape_attr(gkey)}">'
-                f"{_escape_html(gkey)}</code>"
+                "</div>"
+                '<div class="group-head-right">'
+                f'<span class="clone-count-badge">{group_arity}</span>'
+                f"{metrics_button}"
                 "</div>"
                 "</div>"
             )
-
-            out.append(f'<div class="items" id="group-body-{section_id}-{idx}">')
-
-            for i in range(0, len(items), 2):
-                row_items = items[i : i + 2]
-                out.append('<div class="item-pair">')
-
-                for item in row_items:
-                    snippet = _render_code_block(
-                        filepath=item["filepath"],
-                        start_line=int(item["start_line"]),
-                        end_line=int(item["end_line"]),
-                        file_cache=file_cache,
-                        context=context_lines,
-                        max_lines=max_snippet_lines,
-                    )
-
-                    qualname = _escape_html(item["qualname"])
-                    qualname_attr = _escape_attr(item["qualname"])
-                    filepath = _escape_html(item["filepath"])
-                    filepath_attr = _escape_attr(item["filepath"])
-                    start_line = int(item["start_line"])
-                    end_line = int(item["end_line"])
+            if section_id == "blocks" and group_arity > 2:
+                compare_note = block_meta.get("group_compare_note", "").strip()
+                if compare_note:
                     out.append(
-                        f'<div class="item" data-qualname="{qualname_attr}" '
-                        f'data-filepath="{filepath_attr}" '
-                        f'data-start-line="{start_line}" '
-                        f'data-end-line="{end_line}">'
-                        f'<div class="item-head" title="{qualname_attr}">'
-                        f"{qualname}</div>"
-                        f'<div class="item-file" '
-                        f'title="{filepath_attr}:{start_line}-{end_line}">'
-                        f"{filepath}:{start_line}-{end_line}"
-                        f"</div>"
-                        f"{snippet.code_html}"
+                        '<div class="group-compare-note">'
+                        f"{_escape_html(compare_note)}"
                         "</div>"
                     )
 
-                out.append("</div>")  # item-pair
-
-            out.append("</div>")  # items
+            if section_id == "blocks":
+                explanation_html = _render_group_explanation(block_meta)
+                if explanation_html:
+                    out.append(explanation_html)
+
+            out.append(f'<div class="group-body items" id="group-body-{group_id}">')
+            for item_index, item in enumerate(items, start=1):
+                snippet = _render_code_block(
+                    filepath=item["filepath"],
+                    start_line=int(item["start_line"]),
+                    end_line=int(item["end_line"]),
+                    file_cache=file_cache,
+                    context=context_lines,
+                    max_lines=max_snippet_lines,
+                )
+                qualname = _escape_html(item["qualname"])
+                qualname_attr = _escape_attr(item["qualname"])
+                filepath = _escape_html(item["filepath"])
+                filepath_attr = _escape_attr(item["filepath"])
+                start_line = int(item["start_line"])
+                end_line = int(item["end_line"])
+                peer_count = 0
+                peer_count_raw = block_meta.get("instance_peer_count", "").strip()
+                if peer_count_raw.isdigit() and int(peer_count_raw) >= 0:
+                    peer_count = int(peer_count_raw)
+                compare_meta_html = ""
+                if section_id == "blocks" and "group_arity" in block_meta:
+                    compare_text = format_group_instance_compare_meta(
+                        instance_index=item_index,
+                        group_arity=group_arity,
+                        peer_count=peer_count,
+                    )
+                    compare_meta_html = (
+                        f'<div class="item-compare-meta">{compare_text}</div>'
+                    )
+                out.append(
+                    f'<div class="item" data-qualname="{qualname_attr}" '
+                    f'data-filepath="{filepath_attr}" '
+                    f'data-start-line="{start_line}" '
+                    f'data-end-line="{end_line}" '
+                    f'data-peer-count="{peer_count}" '
+                    f'data-instance-index="{item_index}">'
+                    '<div class="item-header">'
+                    f'<div class="item-title" title="{qualname_attr}">{qualname}</div>'
+                    f'<div class="item-loc" '
+                    f'title="{filepath_attr}:{start_line}-{end_line}">'
+                    f"{filepath}:{start_line}-{end_line}"
+                    "</div>"
+                    "</div>"
+                    f"{compare_meta_html}"
+                    f"{snippet.code_html}"
+                    "</div>"
+                )
+            out.append("</div>")  # group-body
             out.append("</div>")  # group
 
         out.append("</div>")  # section-body
@@ -300,92 +571,178 @@ def render_section(
 </div>
 """
 
+    new_function_key_set = set(new_function_group_keys or ())
+    new_block_key_set = set(new_block_group_keys or ())
+    function_novelty = {
+        group_key: ("new" if group_key in new_function_key_set else "known")
+        for group_key, _ in func_sorted
+    }
+    block_novelty = {
+        group_key: ("new" if group_key in new_block_key_set else "known")
+        for group_key, _ in block_sorted
+    }
+    novelty_enabled = bool(function_novelty) or bool(block_novelty)
+    total_new_groups = sum(1 for value in function_novelty.values() if value == "new")
+    total_new_groups += sum(1 for value in block_novelty.values() if value == "new")
+    total_known_groups = sum(
+        1 for value in function_novelty.values() if value == "known"
+    )
+    total_known_groups += sum(1 for value in block_novelty.values() if value == "known")
+    default_novelty = "new" if total_new_groups > 0 else "known"
+    global_novelty_html = ""
+    if novelty_enabled:
+        global_novelty_html = (
+            '<section class="global-novelty" id="global-novelty-controls" '
+            f'data-default-novelty="{default_novelty}">'
+            '<div class="global-novelty-head">'
+            "<h2>Duplicate Scope</h2>"
+            '<div class="novelty-tabs" role="tablist" '
+            'aria-label="Baseline split filter">'
+            '<button class="btn novelty-tab" type="button" '
+            'data-global-novelty="new">'
+            "New duplicates "
+            f'<span class="novelty-count">{total_new_groups}</span>'
+            "</button>"
+            '<button class="btn novelty-tab" type="button" '
+            'data-global-novelty="known">'
+            "Known duplicates "
+            f'<span class="novelty-count">{total_known_groups}</span>'
+            "</button>"
+            "</div>"
+            "</div>"
+            f'<p class="novelty-note">{_escape_html(baseline_split_note)}</p>'
+            "</section>"
+        )
+
     func_section = render_section(
-        "functions", "Function clones", func_sorted, "pill-func"
+        "functions",
+        "Function clones",
+        func_sorted,
+        "pill-func",
+        novelty_by_group=function_novelty,
+    )
+    block_section = render_section(
+        "blocks",
+        "Block clones",
+        block_sorted,
+        "pill-block",
+        novelty_by_group=block_novelty,
     )
-    block_section = render_section("blocks", "Block clones", block_sorted, "pill-block")
     segment_section = render_section(
         "segments", "Segment clones", segment_sorted, "pill-segment"
     )
-
-    meta = dict(report_meta or {})
-    meta_rows: list[tuple[str, Any]] = [
+    baseline_path_value = meta.get("baseline_path")
+    meta_rows: list[tuple[str, object]] = [
+        ("Report schema", meta.get("report_schema_version")),
         ("CodeClone", meta.get("codeclone_version", __version__)),
         ("Python", meta.get("python_version")),
-        ("Baseline", meta.get("baseline_path")),
-        ("Baseline version", meta.get("baseline_version")),
+        ("Baseline file", _path_basename(baseline_path_value)),
+        ("Baseline fingerprint", meta.get("baseline_fingerprint_version")),
         ("Baseline schema", meta.get("baseline_schema_version")),
-        ("Baseline Python", meta.get("baseline_python_version")),
+        ("Baseline Python tag", meta.get("baseline_python_tag")),
+        ("Baseline generator name", meta.get("baseline_generator_name")),
+        ("Baseline generator version", meta.get("baseline_generator_version")),
+        ("Baseline payload sha256", meta.get("baseline_payload_sha256")),
+        (
+            "Baseline payload verified",
+            meta.get("baseline_payload_sha256_verified"),
+        ),
         ("Baseline loaded", meta.get("baseline_loaded")),
         ("Baseline status", meta.get("baseline_status")),
+        ("Source IO skipped", meta.get("files_skipped_source_io")),
+        ("Baseline path", baseline_path_value),
     ]
     if "cache_path" in meta:
         meta_rows.append(("Cache path", meta.get("cache_path")))
+    if "cache_schema_version" in meta:
+        meta_rows.append(("Cache schema", meta.get("cache_schema_version")))
+    if "cache_status" in meta:
+        meta_rows.append(("Cache status", meta.get("cache_status")))
     if "cache_used" in meta:
         meta_rows.append(("Cache used", meta.get("cache_used")))
 
     meta_attrs = " ".join(
         [
+            (
+                'data-report-schema-version="'
+                f'{_escape_attr(meta.get("report_schema_version"))}"'
+            ),
             (
                 'data-codeclone-version="'
                 f'{_escape_attr(meta.get("codeclone_version", __version__))}"'
             ),
             f'data-python-version="{_escape_attr(meta.get("python_version"))}"',
-            f'data-baseline-path="{_escape_attr(meta.get("baseline_path"))}"',
-            f'data-baseline-version="{_escape_attr(meta.get("baseline_version"))}"',
+            f'data-baseline-file="{_escape_attr(_path_basename(baseline_path_value))}"',
+            f'data-baseline-path="{_escape_attr(baseline_path_value)}"',
+            (
+                'data-baseline-fingerprint-version="'
+                f'{_escape_attr(meta.get("baseline_fingerprint_version"))}"'
+            ),
             f'data-baseline-schema-version="{_escape_attr(meta.get("baseline_schema_version"))}"',
-            f'data-baseline-python-version="{_escape_attr(meta.get("baseline_python_version"))}"',
+            (
+                'data-baseline-python-tag="'
+                f'{_escape_attr(meta.get("baseline_python_tag"))}"'
+            ),
+            (
+                'data-baseline-generator-name="'
+                f'{_escape_attr(meta.get("baseline_generator_name"))}"'
+            ),
+            (
+                'data-baseline-generator-version="'
+                f'{_escape_attr(meta.get("baseline_generator_version"))}"'
+            ),
+            (
+                'data-baseline-payload-sha256="'
+                f'{_escape_attr(meta.get("baseline_payload_sha256"))}"'
+            ),
+            (
+                'data-baseline-payload-verified="'
+                f'{_escape_attr(_meta_display(meta.get("baseline_payload_sha256_verified")))}"'
+            ),
             f'data-baseline-loaded="{_escape_attr(_meta_display(meta.get("baseline_loaded")))}"',
             f'data-baseline-status="{_escape_attr(meta.get("baseline_status"))}"',
             f'data-cache-path="{_escape_attr(meta.get("cache_path"))}"',
+            (
+                'data-cache-schema-version="'
+                f'{_escape_attr(meta.get("cache_schema_version"))}"'
+            ),
+            f'data-cache-status="{_escape_attr(meta.get("cache_status"))}"',
             f'data-cache-used="{_escape_attr(_meta_display(meta.get("cache_used")))}"',
+            (
+                'data-files-skipped-source-io="'
+                f'{_escape_attr(meta.get("files_skipped_source_io"))}"'
+            ),
         ]
     )
 
-    def _meta_row_class(label: str) -> str:
-        if label in {"Baseline", "Cache path"}:
-            return "meta-row meta-row-wide"
-        return "meta-row"
-
-    def _is_path_field(label: str) -> bool:
-        """Check if field contains a file path."""
-        return label in {"Baseline", "Cache path"}
-
-    def _is_bool_field(label: str) -> bool:
-        """Check if field contains a boolean value."""
-        return label in {"Baseline loaded", "Cache used"}
-
-    def _format_meta_value(label: str, value: Any) -> str:
-        """Format meta value with appropriate styling."""
-        display_val = _meta_display(value)
-
-        # Boolean fields with badge styling
-        if _is_bool_field(label):
-            if isinstance(value, bool):
-                badge_class = "meta-bool-true" if value else "meta-bool-false"
-                badge_text = "true" if value else "false"
-                return f'<span class="meta-bool {badge_class}">{badge_text}</span>'
-            else:
-                return '<span class="meta-bool meta-bool-na">n/a</span>'
-
-        # Path fields with tooltip on hover
-        if _is_path_field(label) and display_val != "n/a":
-            escaped_path = _escape_html(display_val)
-            return (
-                f'<span class="meta-path">'
-                f"{escaped_path}"
-                f'<span class="meta-path-tooltip">{escaped_path}</span>'
-                f"</span>"
-            )
-
-        # Regular fields
-        return _escape_html(display_val)
+    def _meta_item_class(label: str) -> str:
+        cls = ["meta-item"]
+        if label in {"Baseline path", "Cache path", "Baseline payload sha256"}:
+            cls.append("meta-item-wide")
+        if label in {
+            "Baseline payload verified",
+            "Baseline loaded",
+            "Cache used",
+        }:
+            cls.append("meta-item-boolean")
+        return " ".join(cls)
+
+    def _meta_value_html(label: str, value: object) -> str:
+        if label in {
+            "Baseline payload verified",
+            "Baseline loaded",
+            "Cache used",
+        } and isinstance(value, bool):
+            badge_cls = "meta-bool-true" if value else "meta-bool-false"
+            text = "true" if value else "false"
+            return f'<span class="meta-bool {badge_cls}">{text}</span>'
+        return _escape_html(_meta_display(value))
 
     meta_rows_html = "".join(
         (
-            f'<div class="{_meta_row_class(label)}">'
-            f"<dt>{_escape_html(label)}</dt>"
-            f"<dd>{_format_meta_value(label, value)}</dd>"
+            f'<div class="{_meta_item_class(label)}">'
+            f'<div class="meta-label">{_escape_html(label)}</div>'
+            f'<div class="meta-value">{_meta_value_html(label, value)}</div>'
             "</div>"
         )
         for label, value in meta_rows
@@ -399,24 +756,19 @@ def _format_meta_value(label: str, value: Any) -> str:
         "</svg>"
     )
 
-    # Count non-n/a fields for badge
-    non_na_count = sum(1 for _, val in meta_rows if _meta_display(val) != "n/a")
-
     report_meta_html = (
-        f'<section class="meta-panel" id="report-meta" {meta_attrs}>'
+        f'<div class="meta-panel" id="report-meta" {meta_attrs}>'
         '<div class="meta-header">'
-        '<div class="meta-header-left">'
-        f'<div class="meta-toggle">{chevron_icon}</div>'
-        '<h3 class="meta-title">Report Provenance</h3>'
-        f'<span class="meta-badge">{non_na_count} fields</span>'
+        '<div class="meta-title">'
+        f"{chevron_icon}"
+        "Report Provenance"
         "</div>"
+        '<div class="meta-toggle collapsed">▸</div>'
         "</div>"
-        '<div class="meta-content">'
-        '<div class="meta-body">'
-        f'<dl class="meta-grid">{meta_rows_html}</dl>'
+        '<div class="meta-content collapsed">'
+        f'<div class="meta-grid">{meta_rows_html}</div>'
         "</div>"
         "</div>"
-        "</section>"
     )
 
     return REPORT_TEMPLATE.substitute(
@@ -424,6 +776,7 @@ def _format_meta_value(label: str, value: Any) -> str:
         version=__version__,
         pyg_dark=pyg_dark,
         pyg_light=pyg_light,
+        global_novelty_html=global_novelty_html,
         report_meta_html=report_meta_html,
         empty_state_html=empty_state_html,
         func_section=func_section,
@@ -431,4 +784,7 @@ def _format_meta_value(label: str, value: Any) -> str:
         segment_section=segment_section,
         icon_theme=ICONS["theme"],
         font_css_url=FONT_CSS_URL,
+        repository_url=_escape_attr(REPOSITORY_URL),
+        issues_url=_escape_attr(ISSUES_URL),
+        docs_url=_escape_attr(DOCS_URL),
     )
diff --git a/codeclone/report.py b/codeclone/report.py
index 99fa6d2..29d975d 100644
--- a/codeclone/report.py
+++ b/codeclone/report.py
@@ -8,6 +8,8 @@
 
 from __future__ import annotations
 
+from ._report_blocks import _merge_block_items, prepare_block_report_groups
+from ._report_explain import build_block_group_facts
 from ._report_grouping import build_block_groups, build_groups, build_segment_groups
 from ._report_segments import (
     _CONTROL_FLOW_STMTS,
@@ -43,11 +45,14 @@
     "_assign_targets_attribute_only",
     "_collect_file_functions",
     "_format_meta_text_value",
+    "_merge_block_items",
     "_merge_segment_items",
     "_segment_statements",
+    "build_block_group_facts",
     "build_block_groups",
     "build_groups",
     "build_segment_groups",
+    "prepare_block_report_groups",
     "prepare_segment_report_groups",
     "to_json",
     "to_json_report",
diff --git a/codeclone/templates.py b/codeclone/templates.py
index 3880e1a..ac70339 100644
--- a/codeclone/templates.py
+++ b/codeclone/templates.py
@@ -5,6 +5,7 @@
 Copyright (c) 2026 Den Rozhnovskiy
 Licensed under the MIT License.
 """
+# ruff: noqa: E501
 
 from __future__ import annotations
 
@@ -93,6 +94,13 @@
   --radius: 6px;
   --radius-lg: 8px;
   --radius-xl: 12px;
+  --control-height: 36px;
+  --control-height-sm: 30px;
+  --control-radius: 10px;
+  --badge-height: 22px;
+  --badge-pad-x: 10px;
+  --badge-font-size: 0.72rem;
+  --badge-radius: 999px;
 
   /* Transitions - Calm & Smooth */
   --transition-fast: 120ms cubic-bezier(0.4, 0, 0.2, 1);
@@ -146,11 +154,14 @@
 }
 
 body {
-  background: var(--surface-0);
+  background:
+    radial-gradient(1200px 520px at 20% -10%, rgba(59, 130, 246, 0.12), transparent 50%),
+    radial-gradient(900px 420px at 110% 0%, rgba(16, 185, 129, 0.08), transparent 50%),
+    var(--surface-0);
   color: var(--text-primary);
   font-family: var(--font-sans);
   font-size: var(--text-base);
-  line-height: var(--leading-normal);
+  line-height: 1.58;
   -webkit-font-smoothing: antialiased;
   -moz-osx-font-smoothing: grayscale;
 }
@@ -162,9 +173,9 @@
 
 /* Layout */
 .container {
-  max-width: 1400px;
+  max-width: 1520px;
   margin: 0 auto;
-  padding: 20px 20px 80px;
+  padding: 26px 24px 84px;
 }
 
 /* Topbar */
@@ -172,11 +183,11 @@
   position: sticky;
   top: 0;
   z-index: 100;
-  background: rgba(14, 17, 23, 0.95);
+  background: color-mix(in oklab, var(--surface-0) 88%, black 12%);
   backdrop-filter: blur(12px);
   -webkit-backdrop-filter: blur(12px);
   border-bottom: 1px solid var(--border-subtle);
-  box-shadow: var(--elevation-1);
+  box-shadow: var(--elevation-2);
 }
 
 html[data-theme="light"] .topbar {
@@ -187,9 +198,9 @@
   display: flex;
   align-items: center;
   justify-content: space-between;
-  height: 64px;
+  height: 72px;
   padding: 0 24px;
-  max-width: 1400px;
+  max-width: 1520px;
   margin: 0 auto;
 }
 
@@ -219,7 +230,11 @@
 .top-actions {
   display: flex;
   align-items: center;
-  gap: 8px;
+  gap: 10px;
+}
+
+.top-actions .btn {
+  min-width: 40px;
 }
 
 /* Buttons */
@@ -228,8 +243,9 @@
   align-items: center;
   justify-content: center;
   gap: 6px;
-  padding: 8px 14px;
-  border-radius: var(--radius);
+  height: var(--control-height);
+  padding: 0 12px;
+  border-radius: var(--control-radius);
   border: 1px solid var(--border-default);
   background: var(--surface-1);
   color: var(--text-primary);
@@ -237,11 +253,19 @@
   font-size: var(--text-sm);
   font-weight: 500;
   font-family: var(--font-sans);
-  transition: all var(--transition-base);
+  transition:
+    border-color var(--transition-base),
+    background var(--transition-base),
+    transform var(--transition-fast);
   white-space: nowrap;
   user-select: none;
 }
 
+.btn .icon {
+  width: 0.95em;
+  height: 0.95em;
+}
+
 .btn:hover {
   background: var(--surface-2);
   border-color: var(--border-strong);
@@ -257,19 +281,42 @@
 }
 
 .btn.ghost {
-  background: transparent;
-  border-color: transparent;
-  padding: 6px;
+  background: color-mix(in oklab, var(--surface-1) 80%, var(--surface-0) 20%);
+  border-color: var(--border-subtle);
+  padding: 0 10px;
 }
 
 .btn.ghost:hover {
   background: var(--surface-2);
+  border-color: var(--border-default);
+}
+
+/* Info button - unified with the rest of UI */
+.btn.ghost[data-metrics-btn] {
+  background: color-mix(in oklab, var(--surface-2) 90%, white 10%);
+  border: 1px solid var(--border-default);
+  color: var(--text-secondary);
+  padding: 0 11px;
+  font-size: var(--text-xs);
+  font-weight: 500;
+  border-radius: var(--radius);
+  transition:
+    border-color var(--transition-fast),
+    background var(--transition-fast),
+    color var(--transition-fast);
+}
+
+.btn.ghost[data-metrics-btn]:hover {
+  background: var(--accent-primary);
+  border-color: var(--accent-primary);
+  color: white;
 }
 
 .btn.primary {
   background: var(--accent-primary);
   border-color: var(--accent-primary);
   color: white;
+  font-weight: 600;
 }
 
 .btn.primary:hover {
@@ -277,22 +324,17 @@
   border-color: var(--accent-secondary);
 }
 
-.btn.seg {
-  border: none;
-  background: transparent;
-  height: 30px;
-  padding: 6px 12px;
-}
-
-.btn.seg:hover {
-  background: var(--surface-0);
+.btn.hotkey {
+  font-family: var(--font-mono);
+  font-size: var(--text-xs);
+  letter-spacing: 0.01em;
 }
 
 /* Form Elements */
 .select {
-  padding: 8px 32px 8px 12px;
-  height: 36px;
-  border-radius: var(--radius);
+  padding: 0 32px 0 12px;
+  height: var(--control-height);
+  border-radius: var(--control-radius);
   border: 1px solid var(--border-default);
   background: var(--surface-1);
   color: var(--text-primary);
@@ -313,22 +355,18 @@
 
 /* Sections */
 .section {
-  margin-top: 40px;
+  margin-top: 34px;
 }
 
-/* Meta Panel - Collapsible Pro Design 2025 */
+/* Meta Panel */
 .meta-panel {
-  margin-top: 22px;
-  margin-bottom: 20px;
+  margin-top: 14px;
+  margin-bottom: 18px;
   background: var(--surface-1);
   border: 1px solid var(--border-subtle);
-  border-radius: var(--radius-lg);
+  border-radius: 14px;
   overflow: hidden;
-  transition: all var(--transition-base);
-}
-
-.meta-panel:hover {
-  border-color: var(--border-default);
+  box-shadow: var(--elevation-1);
 }
 
 .meta-header {
@@ -338,56 +376,45 @@
   padding: 14px 16px;
   cursor: pointer;
   user-select: none;
-  transition: background var(--transition-fast);
+  border-bottom: 1px solid transparent;
+  transition:
+    background var(--transition-base),
+    border-color var(--transition-base);
 }
 
 .meta-header:hover {
   background: var(--surface-2);
+  border-bottom-color: var(--border-subtle);
 }
 
-.meta-header-left {
+.meta-title {
   display: flex;
   align-items: center;
-  gap: 12px;
+  gap: 10px;
+  font-size: 0.95rem;
+  font-weight: 600;
+  color: var(--text-primary);
 }
 
 .meta-toggle {
-  width: 18px;
-  height: 18px;
   display: flex;
   align-items: center;
   justify-content: center;
+  width: 24px;
+  height: 24px;
   transition: transform var(--transition-base);
   color: var(--text-tertiary);
-  flex-shrink: 0;
 }
 
 .meta-toggle.collapsed {
   transform: rotate(-90deg);
 }
 
-.meta-title {
-  font-size: var(--text-sm);
-  font-weight: 700;
-  color: var(--text-primary);
-  margin: 0;
-}
-
-.meta-badge {
-  font-size: 11px;
-  font-weight: 500;
-  color: var(--text-tertiary);
-  background: var(--surface-2);
-  padding: 2px 8px;
-  border-radius: var(--radius-sm);
-  border: 1px solid var(--border-subtle);
-}
-
 .meta-content {
-  overflow: hidden;
-  transition: max-height var(--transition-slow), opacity var(--transition-base);
-  max-height: 2000px;
+  max-height: none;
   opacity: 1;
+  overflow: visible;
+  transition: opacity var(--transition-base);
 }
 
 .meta-content.collapsed {
@@ -395,1016 +422,1330 @@
   opacity: 0;
 }
 
-.meta-body {
-  padding: 14px 16px 16px;
-  border-top: 1px solid var(--border-subtle);
-}
-
 .meta-grid {
-  margin: 0;
   display: grid;
-  grid-template-columns: repeat(auto-fit, minmax(300px, 1fr));
-  gap: 12px;
-  row-gap: 10px;
+  grid-template-columns: repeat(12, minmax(0, 1fr));
+  grid-auto-flow: row dense;
+  gap: 14px;
+  padding: 10px 16px 16px;
 }
 
-.meta-row {
+.meta-item {
   display: flex;
   flex-direction: column;
-  gap: 6px;
-  padding: 10px 12px;
-  background: var(--surface-0);
-  border: 1px solid var(--border-subtle);
-  border-radius: var(--radius);
-  transition: all var(--transition-fast);
-  margin: 0;
+  gap: 7px;
+  grid-column: span 4;
   min-width: 0;
+  padding: 12px 13px;
+  border: 1px solid var(--border-subtle);
+  border-radius: 10px;
+  background: color-mix(in oklab, var(--surface-0) 75%, var(--surface-1) 25%);
 }
 
-.meta-row:hover {
-  background: var(--surface-2);
-  border-color: var(--border-default);
-}
-
-.meta-row-wide {
+.meta-item-wide {
   grid-column: 1 / -1;
 }
 
-.meta-row dt {
-  color: var(--text-muted);
-  font-size: var(--text-xs);
-  font-weight: 600;
-  text-transform: uppercase;
-  letter-spacing: 0.02em;
-  display: flex;
+.meta-item-boolean .meta-value {
+  display: inline-flex;
   align-items: center;
-  gap: 6px;
-}
-
-.meta-row dd {
-  margin: 0;
-  color: var(--text-primary);
-  font-family: var(--font-mono);
-  font-size: var(--text-xs);
-  line-height: 1.4;
-  position: relative;
-  overflow: hidden;
-}
-
-/* Path truncation with hover tooltip */
-.meta-path {
-  display: block;
-  white-space: nowrap;
-  overflow: hidden;
-  text-overflow: ellipsis;
-  max-width: 100%;
-  cursor: help;
-  position: relative;
-  padding: 2px 0;
-}
-
-.meta-path:hover {
-  color: var(--accent-primary);
-}
-
-.meta-path-tooltip {
-  position: absolute;
-  left: 0;
-  bottom: calc(100% + 8px);
-  background: var(--surface-3);
-  color: var(--text-primary);
-  padding: 8px 12px;
-  border-radius: var(--radius);
-  font-size: var(--text-xs);
-  white-space: normal;
-  word-break: break-all;
-  border: 1px solid var(--border-default);
-  box-shadow: var(--elevation-3);
-  opacity: 0;
-  pointer-events: none;
-  transition: opacity var(--transition-fast);
-  z-index: 1000;
-  max-width: 600px;
-  min-width: 200px;
-}
-
-.meta-path:hover .meta-path-tooltip {
-  opacity: 1;
+  width: fit-content;
 }
 
-/* Boolean value badges */
 .meta-bool {
   display: inline-flex;
   align-items: center;
-  padding: 3px 8px;
-  border-radius: var(--radius-sm);
-  font-size: 11px;
-  font-weight: 500;
-  font-family: var(--font-sans);
+  gap: 6px;
+  padding: 2px 8px;
+  border-radius: 999px;
+  font-size: var(--text-xs);
+  font-weight: 600;
+  border: 1px solid var(--border-default);
 }
 
 .meta-bool-true {
   background: var(--success-subtle);
   color: var(--success);
-  border: 1px solid rgba(16, 185, 129, 0.3);
 }
 
 .meta-bool-false {
-  background: var(--surface-2);
-  color: var(--text-muted);
-  border: 1px solid var(--border-default);
+  background: var(--error-subtle);
+  color: var(--error);
 }
 
-.meta-bool-na {
-  background: var(--surface-2);
+.meta-label {
+  font-size: var(--text-xs);
   color: var(--text-tertiary);
-  border: 1px solid var(--border-subtle);
-  font-style: italic;
+  font-weight: 500;
+  text-transform: uppercase;
+  letter-spacing: 0.06em;
 }
 
-.section-head {
-  display: flex;
-  flex-direction: column;
-  gap: 16px;
-  margin-bottom: 20px;
+.meta-value {
+  font-size: var(--text-sm);
+  color: var(--text-primary);
+  font-family: var(--font-mono);
+  overflow-wrap: anywhere;
+  word-break: normal;
+  line-height: 1.42;
 }
 
-.section-head h2 {
-  font-size: var(--text-2xl);
-  font-weight: 700;
+/* Section Title */
+.section-title {
+  display: block;
+  margin: 0 0 10px;
+}
+
+.section-title h2 {
   display: flex;
   align-items: center;
-  gap: 12px;
-  letter-spacing: -0.01em;
+  gap: 10px;
+  font-size: clamp(1.5rem, 1.15rem + 1vw, 2rem);
+  font-weight: 700;
+  color: var(--text-primary);
+  letter-spacing: -0.02em;
+}
+
+.count-pill {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  min-height: var(--badge-height);
+  padding: 0 var(--badge-pad-x);
+  background: var(--accent-subtle);
+  color: var(--accent-primary);
+  border-radius: var(--badge-radius);
+  font-size: var(--badge-font-size);
+  font-weight: 600;
+  line-height: 1;
 }
 
 /* Toolbar */
-.section-toolbar {
-  display: flex;
-  justify-content: space-between;
+.toolbar {
+  display: grid;
+  grid-template-columns: minmax(0, 1fr) auto;
   align-items: center;
-  gap: 16px;
+  gap: 10px 14px;
+  margin-bottom: 16px;
   padding: 12px;
   background: var(--surface-1);
   border: 1px solid var(--border-subtle);
-  border-radius: var(--radius-lg);
-}
-
-.toolbar-left {
-  display: flex;
-  align-items: center;
-  gap: 12px;
-  flex: 1;
+  border-radius: 14px;
+  box-shadow: var(--elevation-1);
 }
 
+.toolbar-left,
 .toolbar-right {
   display: flex;
   align-items: center;
-  gap: 12px;
+  gap: 8px;
+  flex-wrap: wrap;
+  min-width: 0;
 }
 
-@media (max-width: 768px) {
-  .section-toolbar {
-    flex-direction: column;
-    align-items: stretch;
-  }
-
-  .toolbar-left,
-  .toolbar-right {
-    width: 100%;
-    justify-content: space-between;
-  }
-
-  .search-wrap {
-    min-width: 0;
-    flex: 1;
-  }
+.toolbar-right {
+  justify-content: flex-end;
 }
 
-/* Search */
-.search-wrap {
-  display: flex;
+.novelty-tabs {
+  display: inline-flex;
   align-items: center;
   gap: 8px;
-  padding: 8px 12px;
-  border-radius: var(--radius);
-  border: 1px solid var(--border-default);
-  background: var(--surface-0);
-  min-width: 280px;
-  transition: all var(--transition-base);
+  flex-wrap: wrap;
 }
 
-.search-wrap:focus-within {
-  border-color: var(--accent-primary);
+.global-novelty {
+  margin-top: 14px;
+  margin-bottom: 18px;
+  padding: 14px 16px 12px;
   background: var(--surface-1);
+  border: 1px solid var(--border-subtle);
+  border-radius: 14px;
+  box-shadow: var(--elevation-1);
 }
 
-.search-ico {
-  color: var(--text-muted);
+.global-novelty-head {
   display: flex;
-  flex-shrink: 0;
+  align-items: center;
+  justify-content: space-between;
+  gap: 12px;
+  flex-wrap: wrap;
 }
 
-.search {
-  width: 100%;
-  border: none;
-  outline: none;
-  background: transparent;
+.global-novelty-head h2 {
+  font-size: var(--text-lg);
+  font-weight: 700;
   color: var(--text-primary);
-  font-size: var(--text-sm);
-  font-family: var(--font-sans);
+  letter-spacing: -0.01em;
 }
 
-.search::placeholder {
-  color: var(--text-muted);
+.novelty-tab {
+  height: var(--control-height-sm);
+  padding: 0 10px;
+  font-size: var(--text-xs);
+  border-radius: 999px;
+  border: 1px solid var(--border-default);
+  background: var(--surface-0);
+  color: var(--text-secondary);
 }
 
-.segmented {
-  display: inline-flex;
+.novelty-tab:hover {
   background: var(--surface-2);
-  padding: 2px;
-  border-radius: var(--radius);
-}
-
-.pager {
-  display: inline-flex;
-  align-items: center;
-  gap: 8px;
-  font-size: var(--text-sm);
+  color: var(--text-primary);
 }
 
-.page-meta {
-  color: var(--text-secondary);
-  font-size: var(--text-sm);
-  white-space: nowrap;
-  min-width: 120px;
-  text-align: center;
-  font-variant-numeric: tabular-nums;
+.novelty-tab.is-active {
+  background: var(--accent-subtle);
+  border-color: color-mix(in oklab, var(--accent-primary) 45%, var(--border-default) 55%);
+  color: var(--accent-primary);
 }
 
-/* Pills */
-.pill {
+.novelty-count {
   display: inline-flex;
   align-items: center;
-  padding: 3px 10px;
-  border-radius: 12px;
-  font-size: var(--text-xs);
-  font-weight: 600;
+  justify-content: center;
+  min-width: 18px;
+  height: 18px;
+  margin-left: 4px;
+  padding: 0 6px;
+  border-radius: 999px;
+  background: color-mix(in oklab, var(--surface-2) 90%, var(--surface-0) 10%);
+  font-family: var(--font-mono);
+  font-size: 0.68rem;
   line-height: 1;
 }
 
-.pill.small {
-  padding: 2px 8px;
-  font-size: 11px;
+.novelty-note {
+  margin: 10px 2px 0;
+  color: var(--text-tertiary);
+  font-size: var(--text-xs);
+  line-height: 1.4;
 }
 
-.pill-func {
-  color: var(--accent-primary);
-  background: var(--accent-subtle);
-  border: 1px solid var(--accent-primary);
-  opacity: 0.9;
-}
+/* Search */
+.search-box {
+  position: relative;
+  width: clamp(260px, 38vw, 460px);
+}
 
-.pill-block {
-  color: var(--success);
-  background: var(--success-subtle);
-  border: 1px solid var(--success);
-  opacity: 0.9;
+.search-box input {
+  width: 100%;
+  height: var(--control-height);
+  padding: 0 34px 0 34px;
+  border-radius: var(--control-radius);
+  border: 1px solid var(--border-default);
+  background: var(--surface-0);
+  color: var(--text-primary);
+  font-size: var(--text-sm);
+  font-family: var(--font-sans);
+  transition: all var(--transition-base);
 }
 
-.pill-segment {
-  color: var(--warning);
-  background: var(--warning-subtle);
-  border: 1px solid var(--warning);
-  opacity: 0.9;
+.search-box input:focus {
+  outline: 2px solid var(--accent-primary);
+  outline-offset: 0;
+  border-color: var(--accent-primary);
+}
+
+.search-box input::placeholder {
+  color: var(--text-muted);
+}
+
+.search-box .search-ico {
+  position: absolute;
+  left: 10px;
+  top: 50%;
+  transform: translateY(-50%);
+  color: var(--text-muted);
+  font-size: 0.95rem;
+  pointer-events: none;
+  display: inline-flex;
+}
+
+.search-box .clear-btn {
+  position: absolute;
+  right: 6px;
+  top: 50%;
+  transform: translateY(-50%);
+  width: 24px;
+  height: 24px;
+  padding: 4px;
+  background: none;
+  border: none;
+  color: var(--text-muted);
+  cursor: pointer;
+  border-radius: var(--radius-sm);
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  transition: all var(--transition-base);
+  opacity: 0;
+  pointer-events: none;
+}
+
+.search-box .clear-btn:hover {
+  background: var(--surface-2);
+  color: var(--text-primary);
+}
+
+.search-box input:not(:placeholder-shown) + .clear-btn {
+  opacity: 1;
+  pointer-events: auto;
+}
+
+/* Pagination */
+.pagination {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+}
+
+.page-meta {
+  font-size: var(--text-sm);
+  color: var(--text-secondary);
+  white-space: nowrap;
+  min-width: 160px;
+  text-align: center;
 }
 
-/* Groups */
+/* Group Card */
 .group {
-  margin-bottom: 16px;
-  border: 1px solid var(--border-subtle);
-  border-radius: var(--radius-lg);
   background: var(--surface-1);
-  box-shadow: var(--elevation-1);
+  border: 1px solid var(--border-subtle);
+  border-radius: 14px;
+  margin-bottom: 18px;
   overflow: hidden;
-  transition: all var(--transition-base);
+  transition:
+    border-color var(--transition-base),
+    box-shadow var(--transition-base);
 }
 
 .group:hover {
-  box-shadow: var(--elevation-2);
-  border-color: var(--border-default);
+  border-color: color-mix(in oklab, var(--accent-primary) 35%, var(--border-default) 65%);
+  box-shadow: var(--elevation-3);
 }
 
 .group-head {
   display: flex;
-  justify-content: space-between;
   align-items: center;
-  gap: 12px;
-  padding: 14px 16px;
-  background: var(--surface-2);
-  border-bottom: 1px solid var(--border-subtle);
+  justify-content: space-between;
+  padding: 13px 14px;
   cursor: pointer;
-  transition: background var(--transition-fast);
-  min-width: 0;
+  user-select: none;
+  gap: 10px;
+  background: var(--surface-1);
+  border-bottom: 1px solid var(--border-subtle);
+  transition: background var(--transition-base);
 }
 
-.group:hover .group-head {
-  background: var(--surface-3);
+.group-head:hover {
+  background: var(--surface-2);
 }
 
-.group-left {
+.group-head-left {
   display: flex;
   align-items: center;
   gap: 10px;
+  flex: 1;
   min-width: 0;
 }
 
-.group-title {
-  font-weight: 600;
-  font-size: var(--text-base);
-  color: var(--text-primary);
+.group-toggle {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  width: 24px;
+  height: 24px;
+  flex-shrink: 0;
+  transition: transform var(--transition-base);
+  color: var(--text-tertiary);
 }
 
-.group-right {
+.group-info {
   display: flex;
-  align-items: center;
-  gap: 10px;
-  min-width: 0;
+  flex-direction: column;
+  gap: 4px;
   flex: 1;
-  justify-content: flex-end;
+  min-width: 0;
 }
 
-.gkey {
-  display: block;
-  font-family: var(--font-mono);
+.group-name {
+  font-size: 0.94rem;
+  font-weight: 600;
+  color: var(--text-primary);
+  font-family: var(--font-sans);
+  letter-spacing: 0;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.group-summary {
   font-size: var(--text-xs);
   color: var(--text-tertiary);
-  background: var(--surface-0);
-  padding: 3px 6px;
-  border-radius: var(--radius-sm);
-  border: 1px solid var(--border-subtle);
+  letter-spacing: 0.01em;
+}
+
+.group-head-right {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  flex-shrink: 0;
+}
+
+/* Primary badge: clone instances count */
+.clone-count-badge {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  min-height: var(--badge-height);
+  min-width: var(--badge-height);
+  gap: 4px;
+  padding: 0 var(--badge-pad-x);
+  background: var(--accent-subtle);
+  color: var(--accent-primary);
+  border-radius: var(--badge-radius);
+  font-size: var(--badge-font-size);
+  font-weight: 600;
+  line-height: 1;
   white-space: nowrap;
+}
+
+/* Group Body */
+.group-body {
+  background: color-mix(in oklab, var(--surface-1) 88%, var(--surface-0) 12%);
+  padding: 12px;
+}
+
+.items {
+  display: grid;
+  grid-template-columns: repeat(2, minmax(0, 1fr));
+  gap: 12px;
+  align-items: stretch;
+}
+
+/* Clone Item */
+.item {
+  display: flex;
+  flex-direction: column;
+  height: 100%;
+  padding: 0;
+  border: 1px solid color-mix(in oklab, var(--border-subtle) 70%, var(--surface-3) 30%);
+  border-radius: 10px;
+  background: var(--surface-0);
   overflow: hidden;
-  text-overflow: ellipsis;
-  max-width: min(52vw, 700px);
+  transition:
+    border-color var(--transition-base),
+    box-shadow var(--transition-base);
 }
 
-@media (max-width: 900px) {
-  .group-head {
-    flex-direction: column;
-    align-items: flex-start;
-  }
+.item:hover {
+  border-color: color-mix(in oklab, var(--accent-primary) 30%, var(--border-default) 70%);
+  box-shadow: var(--elevation-2);
+}
 
-  .group-right {
-    width: 100%;
-    justify-content: flex-start;
-  }
+.item-header {
+  display: grid;
+  grid-template-columns: minmax(0, 1fr) minmax(190px, auto);
+  gap: 8px;
+  align-items: start;
+  padding: 10px 12px 8px;
+  border-bottom: 1px solid var(--border-subtle);
+  background: color-mix(in oklab, var(--surface-1) 82%, var(--surface-0) 18%);
+  margin-bottom: 0;
+}
 
-  .gkey {
-    max-width: 100%;
-  }
+.item-title,
+.item-loc {
+  min-width: 0;
+}
+
+.item-title {
+  display: -webkit-box;
+  -webkit-line-clamp: 2;
+  -webkit-box-orient: vertical;
+  overflow: hidden;
+  font-size: var(--text-sm);
+  font-weight: 600;
+  color: var(--text-primary);
+  font-family: var(--font-mono);
+  line-height: 1.36;
+  overflow-wrap: anywhere;
+}
+
+.item-loc {
+  font-size: 11px;
+  color: var(--text-tertiary);
+  font-family: var(--font-mono);
+  line-height: 1.4;
+  white-space: normal;
+  text-align: right;
+  justify-self: end;
+  overflow-wrap: anywhere;
+  word-break: break-word;
+  max-width: 42ch;
+  opacity: 0.95;
+}
+
+.item .codebox {
+  flex: 1;
+  min-height: 0;
+  max-height: 460px;
+  margin-top: 0;
+  border: 0;
+  border-radius: 0;
+  box-shadow: none;
 }
 
-.chev {
+.item .codebox pre {
+  padding: 10px 12px 12px;
+}
+
+/* Group explainability facts */
+.group-explain {
   display: flex;
+  flex-wrap: wrap;
+  gap: 6px;
+  margin-top: 10px;
+  padding: 0 12px 10px;
+}
+
+.group-head + .group-explain {
+  margin-top: 12px;
+}
+
+.group-explain-item {
+  display: inline-flex;
   align-items: center;
   justify-content: center;
-  width: 24px;
-  height: 24px;
-  border-radius: var(--radius-sm);
+  min-height: var(--badge-height);
+  font-family: var(--font-mono);
+  font-size: var(--badge-font-size);
+  line-height: 1.1;
+  padding: 0 var(--badge-pad-x);
+  border-radius: var(--badge-radius);
   border: 1px solid var(--border-default);
-  background: var(--surface-1);
-  color: var(--text-muted);
-  padding: 0;
-  transition: all var(--transition-fast);
-  cursor: pointer;
+  background: color-mix(in oklab, var(--surface-2) 82%, var(--surface-1) 18%);
+  color: var(--text-secondary);
+  white-space: nowrap;
 }
 
-.chev:hover {
-  color: var(--text-primary);
-  border-color: var(--accent-primary);
+.group-explain-warn {
+  color: var(--warning);
+  border-color: color-mix(in oklab, var(--warning) 45%, var(--border-default) 55%);
+  background: color-mix(in oklab, var(--warning-subtle) 75%, var(--surface-2) 25%);
 }
 
-.chev svg {
-  transition: transform var(--transition-base);
+.group-explain-muted {
+  color: var(--text-tertiary);
 }
 
-/* Items */
-.items {
-  padding: 16px;
-  background: var(--surface-0);
+.group-explain-note {
+  flex-basis: 100%;
+  margin-top: 4px;
+  color: var(--text-tertiary);
+  font-size: 0.74rem;
+  line-height: 1.35;
 }
 
-.item-pair {
-  display: grid;
-  grid-template-columns: 1fr 1fr;
-  gap: 16px;
-  margin-bottom: 16px;
-  min-width: 0;
+.group-head .btn {
+  height: var(--control-height-sm);
+  padding: 0 10px;
+  font-size: 0.74rem;
 }
 
-.item-pair:last-child {
-  margin-bottom: 0;
+.group-head .btn.ghost {
+  background: var(--surface-0);
+  border-color: var(--border-subtle);
 }
 
-@media (max-width: 1200px) {
-  .item-pair {
-    grid-template-columns: 1fr;
-  }
+.group-head .btn.ghost:hover {
+  background: var(--surface-2);
+  border-color: var(--border-default);
 }
 
-.item {
+.group-compare-note {
+  margin: 12px 12px 0;
+  padding: 8px 10px;
   border: 1px solid var(--border-subtle);
-  border-radius: var(--radius-lg);
-  overflow: hidden;
-  display: flex;
-  flex-direction: column;
-  min-width: 0;
-  background: var(--surface-1);
+  border-radius: 8px;
+  background: color-mix(in oklab, var(--surface-1) 72%, var(--surface-0) 28%);
+  color: var(--text-tertiary);
+  font-size: var(--text-xs);
+  line-height: 1.45;
 }
 
-.item:hover {
-  border-color: var(--border-default);
+.group-compare-note + .group-explain {
+  margin-top: 10px;
 }
 
-.item-head {
-  padding: 10px 14px;
-  background: var(--surface-2);
-  border-bottom: 1px solid var(--border-subtle);
+.item-path {
   font-size: var(--text-sm);
-  font-weight: 600;
-  color: var(--accent-primary);
+  color: var(--text-secondary);
   font-family: var(--font-mono);
-  white-space: nowrap;
-  overflow: hidden;
-  text-overflow: ellipsis;
+  overflow-wrap: break-word;
+  word-break: break-all;
+  margin-top: 2px;
 }
 
-.item-file {
-  padding: 8px 14px;
-  background: var(--surface-3);
-  border-bottom: 1px solid var(--border-subtle);
-  font-family: var(--font-mono);
+.item-compare-meta {
+  padding: 0 12px 8px;
+  color: var(--text-muted);
   font-size: var(--text-xs);
-  color: var(--text-tertiary);
-  white-space: nowrap;
-  overflow: hidden;
-  text-overflow: ellipsis;
+  font-family: var(--font-mono);
+  line-height: 1.35;
 }
 
-/* Code Display */
+/* Code Block */
 .codebox {
-  position: relative;
-  margin: 0;
-  padding: 0;
-  font-family: var(--font-mono);
-  font-size: 13px;
-  line-height: 1.5;
-  overflow-x: auto;
-  overflow-y: auto;
-  background: var(--surface-0);
-  flex: 1;
-  max-width: 100%;
-  max-height: 600px;
+  background: color-mix(in oklab, var(--surface-0) 90%, black 10%);
+  border: 1px solid color-mix(in oklab, var(--border-subtle) 80%, var(--surface-3) 20%);
+  border-radius: 0 0 10px 10px;
+  overflow: auto;
+  box-shadow: inset 0 1px 0 rgba(255, 255, 255, 0.03);
 }
 
 .codebox pre {
   margin: 0;
-  padding: 14px;
-  white-space: pre;
-  word-wrap: normal;
-  overflow-wrap: normal;
-  min-width: max-content;
+  padding: 10px 12px;
+  font-family: var(--font-mono);
+  font-size: var(--text-sm);
+  line-height: 1.5;
 }
 
 .codebox code {
   display: block;
+  min-width: max-content;
+}
+
+.codebox .line,
+.codebox .hitline {
   white-space: pre;
-  word-wrap: normal;
-  overflow-wrap: normal;
-  font-family: inherit;
-  font-size: inherit;
-  color: var(--text-secondary);
 }
 
-/* Empty State */
-.empty {
-  padding: 60px 20px;
-  display: flex;
-  justify-content: center;
+.codebox .hitline {
+  background: var(--accent-muted);
+}
+
+/* Metrics modal */
+.metrics-modal {
+  position: fixed;
+  top: 0;
+  left: 0;
+  right: 0;
+  bottom: 0;
+  background: rgba(0, 0, 0, 0.7);
+  backdrop-filter: blur(4px);
+  -webkit-backdrop-filter: blur(4px);
+  z-index: 1000;
+  display: none;
   align-items: center;
+  justify-content: center;
+  padding: 20px;
+  animation: fadeIn var(--transition-base);
 }
 
-.empty-card {
-  text-align: center;
-  padding: 40px;
+.metrics-modal.active {
+  display: flex;
+}
+
+@keyframes fadeIn {
+  from {
+    opacity: 0;
+  }
+  to {
+    opacity: 1;
+  }
+}
+
+.metrics-card {
   background: var(--surface-1);
-  border: 1px solid var(--border-subtle);
+  border: 1px solid var(--border-default);
   border-radius: var(--radius-xl);
-  max-width: 500px;
+  max-width: 600px;
+  width: 100%;
+  max-height: 80vh;
+  overflow-y: auto;
+  box-shadow: var(--elevation-4);
+  animation: slideUp var(--transition-slow);
 }
 
-.empty-icon {
-  color: var(--success);
-  margin-bottom: 16px;
+.help-card {
+  max-width: min(1140px, 96vw);
+}
+
+@keyframes slideUp {
+  from {
+    opacity: 0;
+    transform: translateY(20px);
+  }
+  to {
+    opacity: 1;
+    transform: translateY(0);
+  }
+}
+
+.metrics-header {
   display: flex;
-  justify-content: center;
-  font-size: 48px;
+  align-items: center;
+  justify-content: space-between;
+  padding: 20px 24px;
+  border-bottom: 1px solid var(--border-subtle);
 }
 
-.empty-card h2 {
-  font-size: var(--text-xl);
-  margin-bottom: 10px;
+.metrics-header h3 {
+  font-size: var(--text-lg);
+  font-weight: 700;
   color: var(--text-primary);
 }
 
-.empty-card p {
+.metrics-close {
+  width: 32px;
+  height: 32px;
+  border-radius: var(--radius);
+  border: 1px solid var(--border-default);
+  background: var(--surface-2);
   color: var(--text-secondary);
-  line-height: var(--leading-relaxed);
-  margin-bottom: 6px;
+  cursor: pointer;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  transition: all var(--transition-base);
 }
 
-.empty-card .muted {
-  color: var(--text-muted);
+.metrics-close:hover {
+  background: var(--surface-3);
+  color: var(--text-primary);
+  border-color: var(--border-strong);
+}
+
+.metrics-body {
+  padding: 24px;
+}
+
+.metrics-section {
+  margin-bottom: 24px;
+}
+
+.metrics-section:last-child {
+  margin-bottom: 0;
+}
+
+.metrics-section-title {
   font-size: var(--text-sm);
+  font-weight: 600;
+  color: var(--text-secondary);
+  text-transform: uppercase;
+  letter-spacing: 0.05em;
+  margin-bottom: 12px;
 }
 
-/* Footer */
-.footer {
-  margin-top: 60px;
-  text-align: center;
-  color: var(--text-muted);
+.metrics-grid {
+  display: grid;
+  grid-template-columns: repeat(auto-fit, minmax(150px, 1fr));
+  gap: 12px;
+}
+
+.metric-item {
+  display: flex;
+  flex-direction: column;
+  gap: 6px;
+  padding: 12px;
+  background: var(--surface-2);
+  border: 1px solid var(--border-subtle);
+  border-radius: var(--radius);
+}
+
+.metric-label {
+  display: flex;
+  align-items: center;
+  gap: 6px;
+  font-size: var(--text-xs);
+  color: var(--text-tertiary);
+  font-weight: 500;
+}
+
+.metric-value {
+  font-size: var(--text-lg);
+  font-weight: 600;
+  color: var(--text-primary);
+  font-family: var(--font-mono);
+}
+
+.metric-value-compact {
   font-size: var(--text-sm);
-  border-top: 1px solid var(--border-subtle);
-  padding-top: 24px;
+  line-height: 1.4;
+  overflow-wrap: anywhere;
 }
 
-.kbd {
+.metric-badge {
   display: inline-flex;
   align-items: center;
-  justify-content: center;
-  padding: 2px 6px;
+  gap: 4px;
+  padding: 2px 8px;
+  border-radius: 4px;
+  font-size: var(--text-xs);
+  font-weight: 500;
+}
+
+.metric-badge.success {
+  background: var(--success-subtle);
+  color: var(--success);
+}
+
+.metric-badge.warning {
+  background: var(--warning-subtle);
+  color: var(--warning);
+}
+
+.metric-badge.error {
+  background: var(--error-subtle);
+  color: var(--error);
+}
+
+.metric-badge.info {
+  background: var(--info-subtle);
+  color: var(--info);
+}
+
+.metric-link-item {
+  padding: 0;
+  background: transparent;
+  border: 0;
+}
+
+.help-card .metrics-grid {
+  grid-template-columns: repeat(3, minmax(0, 1fr));
+}
+
+.help-card .metrics-section:first-child .metrics-grid {
+  grid-template-columns: repeat(4, minmax(0, 1fr));
+}
+
+.help-link {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 10px;
+  padding: 12px;
+  border: 1px solid var(--border-subtle);
+  border-radius: var(--radius);
   background: var(--surface-2);
-  border: 1px solid var(--border-default);
-  border-radius: var(--radius-sm);
+  color: var(--text-primary);
+  text-decoration: none;
+  transition: all var(--transition-base);
+}
+
+.help-link:hover {
+  border-color: var(--border-strong);
+  background: var(--surface-3);
+  transform: translateY(-1px);
+}
+
+.help-link-main {
+  min-width: 0;
+  display: flex;
+  flex-direction: column;
+  gap: 4px;
+}
+
+.help-link-title {
+  font-size: var(--text-sm);
+  font-weight: 600;
+  color: var(--text-primary);
+}
+
+.help-link-meta {
+  font-size: var(--text-xs);
   font-family: var(--font-mono);
-  font-size: 11px;
   color: var(--text-tertiary);
-  box-shadow: 0 1px 0 var(--border-subtle);
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+}
+
+.help-link-icon {
+  color: var(--text-muted);
+  flex-shrink: 0;
+}
+
+/* Code Preview */
+.code-preview {
+  margin-top: 8px;
+  background: var(--surface-0);
+  border: 1px solid var(--border-subtle);
+  border-radius: var(--radius);
+  padding: 12px;
+  font-family: var(--font-mono);
+  font-size: var(--text-sm);
+  color: var(--text-secondary);
+  overflow-x: auto;
+  white-space: pre-wrap;
+  word-break: break-word;
 }
 
-/* Toast Notifications */
+/* Toast notifications */
 .toast-container {
   position: fixed;
-  top: 80px;
-  right: 20px;
-  z-index: 1000;
+  bottom: 24px;
+  right: 24px;
+  z-index: 2000;
   display: flex;
   flex-direction: column;
-  gap: 10px;
+  gap: 8px;
   pointer-events: none;
 }
 
 .toast {
-  display: flex;
-  align-items: center;
-  gap: 10px;
-  padding: 12px 16px;
+  padding: 12px 18px;
   background: var(--surface-1);
   border: 1px solid var(--border-default);
   border-radius: var(--radius-lg);
   box-shadow: var(--elevation-3);
+  display: flex;
+  align-items: center;
+  gap: 10px;
   min-width: 280px;
   max-width: 400px;
-  transform: translateX(450px);
-  opacity: 0;
-  transition: all var(--transition-slow);
+  font-size: var(--text-sm);
+  color: var(--text-primary);
+  animation: slideInRight var(--transition-slow);
   pointer-events: auto;
 }
 
-.toast.toast-show {
-  transform: translateX(0);
-  opacity: 1;
+@keyframes slideInRight {
+  from {
+    opacity: 0;
+    transform: translateX(100%);
+  }
+  to {
+    opacity: 1;
+    transform: translateX(0);
+  }
 }
 
-.toast-icon {
-  font-size: var(--text-lg);
-  flex-shrink: 0;
+.toast.success {
+  border-left: 3px solid var(--success);
 }
 
-.toast-message {
-  flex: 1;
-  font-size: var(--text-sm);
-  color: var(--text-primary);
+.toast.warning {
+  border-left: 3px solid var(--warning);
 }
 
-.toast-close {
-  background: transparent;
-  border: none;
-  color: var(--text-muted);
-  cursor: pointer;
-  font-size: var(--text-lg);
-  padding: 0;
-  width: 20px;
-  height: 20px;
-  display: flex;
-  align-items: center;
-  justify-content: center;
-  transition: color var(--transition-fast);
+.toast.error {
+  border-left: 3px solid var(--error);
 }
 
-.toast-close:hover {
-  color: var(--text-primary);
+.toast.info {
+  border-left: 3px solid var(--info);
 }
 
-.toast-info { border-left: 3px solid var(--info); }
-.toast-success { border-left: 3px solid var(--success); }
-.toast-warning { border-left: 3px solid var(--warning); }
-.toast-error { border-left: 3px solid var(--error); }
-
 /* Command Palette */
-.command-palette {
+.cmd-palette {
   position: fixed;
-  inset: 0;
-  z-index: 2000;
+  top: 0;
+  left: 0;
+  right: 0;
+  bottom: 0;
+  background: rgba(0, 0, 0, 0.6);
+  backdrop-filter: blur(4px);
+  -webkit-backdrop-filter: blur(4px);
+  z-index: 1500;
   display: none;
+  align-items: flex-start;
+  justify-content: center;
+  padding-top: 100px;
 }
 
-.command-palette.show {
-  display: block;
-}
-
-.command-backdrop {
-  position: absolute;
-  inset: 0;
-  background: rgba(0, 0, 0, 0.7);
-  backdrop-filter: blur(4px);
-  -webkit-backdrop-filter: blur(4px);
-  animation: fadeIn 0.2s ease-out;
+.cmd-palette.active {
+  display: flex;
 }
 
-.command-dialog {
-  position: absolute;
-  top: 15%;
-  left: 50%;
-  transform: translateX(-50%);
-  width: min(90vw, 600px);
-  max-height: 70vh;
+.cmd-palette-content {
+  width: min(720px, 92vw);
+  max-height: min(76vh, 680px);
   background: var(--surface-1);
   border: 1px solid var(--border-default);
-  border-radius: var(--radius-lg);
+  border-radius: 16px;
   box-shadow: var(--elevation-4);
+  overflow: hidden;
   display: flex;
   flex-direction: column;
-  animation: slideDown 0.25s cubic-bezier(0.16, 1, 0.3, 1);
-}
-
-@keyframes fadeIn {
-  from { opacity: 0; }
-  to { opacity: 1; }
+  animation: slideDown var(--transition-slow);
 }
 
 @keyframes slideDown {
   from {
     opacity: 0;
-    transform: translateX(-50%) translateY(-10px);
+    transform: translateY(-20px);
   }
   to {
     opacity: 1;
-    transform: translateX(-50%) translateY(0);
+    transform: translateY(0);
   }
 }
 
-.command-input-wrap {
-  padding: 16px;
-  border-bottom: 1px solid var(--border-subtle);
-}
-
-.command-input {
+.cmd-search {
   width: 100%;
-  padding: 10px 12px;
-  background: var(--surface-0);
-  border: 1px solid var(--border-default);
-  border-radius: var(--radius);
+  padding: 14px 16px;
+  border: none;
+  border-bottom: 1px solid var(--border-subtle);
+  background: transparent;
   color: var(--text-primary);
-  font-size: var(--text-base);
+  font-size: 1.75rem;
+  line-height: 1.2;
   font-family: var(--font-sans);
 }
 
-.command-input:focus {
-  outline: 2px solid var(--accent-primary);
-  outline-offset: 2px;
-}
-
-.command-input::placeholder {
-  color: var(--text-muted);
+.cmd-search:focus {
+  outline: none;
 }
 
-.command-results {
+.cmd-list {
+  max-height: min(56vh, 460px);
   overflow-y: auto;
-  max-height: calc(70vh - 80px);
-  padding: 8px;
-}
-
-.command-section {
-  margin-bottom: 12px;
-}
-
-.command-section-title {
-  font-size: var(--text-xs);
-  font-weight: 600;
-  color: var(--text-muted);
-  text-transform: uppercase;
-  letter-spacing: 0.05em;
-  padding: 6px 12px;
-  margin-bottom: 4px;
+  overflow-x: hidden;
+  background: var(--surface-1);
 }
 
-.command-item {
-  display: flex;
-  align-items: center;
-  justify-content: space-between;
+.cmd-item {
   width: 100%;
-  padding: 10px 12px;
+  max-width: 100%;
+  min-height: 64px;
+  box-sizing: border-box;
+  appearance: none;
+  -webkit-appearance: none;
+  border: 0;
+  border-bottom: 1px solid var(--border-subtle);
+  border-radius: 0;
   background: transparent;
-  border: none;
-  border-radius: var(--radius);
   color: var(--text-primary);
-  font-size: var(--text-sm);
-  font-family: var(--font-sans);
+  font: inherit;
   text-align: left;
+  display: flex;
+  align-items: center;
+  gap: 12px;
+  padding: 12px 20px;
   cursor: pointer;
-  transition: background var(--transition-fast);
+  transition: background var(--transition-base);
 }
 
-.command-item:hover,
-.command-item.selected,
-.command-item[aria-selected='true'] {
-  background: var(--accent-muted);
+.cmd-item:last-child {
+  border-bottom: none;
+}
+
+.cmd-item:hover {
+  background: var(--surface-2);
+}
+
+.cmd-item.selected {
+  background: var(--surface-2);
+  box-shadow: inset 2px 0 0 var(--accent-primary);
 }
 
-.command-item-left {
+.cmd-item:focus-visible {
+  outline: 2px solid var(--accent-primary);
+  outline-offset: -2px;
+}
+
+.cmd-item-icon {
+  width: 20px;
+  height: 20px;
   display: flex;
   align-items: center;
-  gap: 10px;
+  justify-content: center;
+  color: var(--text-tertiary);
+}
+
+.cmd-item-text {
   flex: 1;
 }
 
-.command-icon {
-  font-size: var(--text-lg);
-  width: 20px;
-  text-align: center;
+.cmd-item-title {
+  font-size: var(--text-sm);
+  font-weight: 500;
+  color: var(--text-primary);
+  overflow-wrap: anywhere;
 }
 
-.command-shortcut {
+.cmd-item-desc {
+  font-size: var(--text-xs);
+  color: var(--text-tertiary);
+  margin-top: 2px;
+  overflow-wrap: anywhere;
+}
+
+.cmd-item-shortcut {
   font-size: var(--text-xs);
   color: var(--text-muted);
   font-family: var(--font-mono);
-  background: var(--surface-2);
   padding: 2px 6px;
-  border-radius: var(--radius-sm);
+  background: var(--surface-0);
   border: 1px solid var(--border-subtle);
+  border-radius: 4px;
 }
 
-.command-empty {
-  color: var(--text-muted);
+.cmd-empty {
+  padding: 16px 20px;
+  color: var(--text-tertiary);
   font-size: var(--text-sm);
-  padding: 12px;
 }
 
-/* Stats Dashboard */
+/* Footer */
+.report-footer {
+  margin-top: 24px;
+  padding-top: 12px;
+  border-top: 1px solid var(--border-subtle);
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  justify-content: center;
+  gap: 8px;
+  color: var(--text-tertiary);
+  font-size: var(--text-sm);
+}
+
+.footer-kbd {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  min-height: 22px;
+  padding: 0 8px;
+  border-radius: 6px;
+  border: 1px solid var(--border-default);
+  background: var(--surface-1);
+  color: var(--text-secondary);
+  font-family: var(--font-mono);
+  font-size: var(--text-xs);
+}
+
+.footer-sep {
+  color: var(--text-muted);
+}
+
+/* Stats and Charts */
 .stats-grid {
   display: grid;
-  grid-template-columns: repeat(auto-fit, minmax(200px, 1fr));
-  gap: 16px;
-  margin: 24px 0;
+  grid-template-columns: repeat(4, minmax(0, 1fr));
+  gap: 12px;
+  margin: 0 0 16px;
 }
 
 .stat-card {
-  padding: 16px 18px;
   background: var(--surface-1);
   border: 1px solid var(--border-subtle);
   border-radius: var(--radius-lg);
-  text-align: left;
-  display: grid;
-  grid-template-columns: auto 1fr;
-  grid-template-rows: auto auto;
-  gap: 2px 12px;
-  align-items: center;
-}
-
-.stat-icon {
-  grid-column: 1;
-  grid-row: 1 / span 2;
-  width: 38px;
-  height: 38px;
-  color: var(--text-tertiary);
-  opacity: 0.92;
-}
-
-.stat-icon .icon {
-  width: 100%;
-  height: 100%;
+  padding: 14px;
 }
 
 .stat-value {
-  grid-column: 2;
-  grid-row: 1;
   font-size: var(--text-2xl);
   font-weight: 700;
-  color: var(--text-primary);
-  line-height: 1.1;
+  font-family: var(--font-mono);
 }
 
 .stat-label {
-  grid-column: 2;
-  grid-row: 2;
-  font-size: var(--text-sm);
-  color: var(--text-muted);
-  margin: 0;
-}
-
-.stat-trend {
+  margin-top: 4px;
+  color: var(--text-tertiary);
   font-size: var(--text-sm);
-  font-weight: 600;
-}
-
-.stat-trend.up {
-  color: var(--success);
-}
-
-.stat-trend.down {
-  color: var(--error);
-}
-
-.stat-trend.neutral {
-  color: var(--text-muted);
 }
 
-/* Chart Container */
 .chart-container {
   background: var(--surface-1);
   border: 1px solid var(--border-subtle);
   border-radius: var(--radius-lg);
-  padding: 20px;
-  margin: 24px 0;
+  padding: 14px;
+  margin: 0 0 16px;
 }
 
 .chart-title {
-  font-size: var(--text-lg);
+  font-size: var(--text-base);
   font-weight: 600;
-  color: var(--text-primary);
-  margin-bottom: 16px;
+  margin-bottom: 10px;
 }
 
-.chart-canvas {
+#complexity-canvas {
   width: 100%;
-  height: 300px;
+  height: 220px;
+}
+
+/* Pygments token styles */
+${pyg_dark}
+${pyg_light}
+
+@media (max-width: 1280px) {
+  .meta-item {
+    grid-column: span 4;
+  }
+}
+
+@media (max-width: 980px) {
+  .meta-item {
+    grid-column: span 6;
+  }
+
+  .items {
+    grid-template-columns: 1fr;
+  }
 }
 
-@media print {
-  .topbar,
-  .section-toolbar,
-  .toast-container,
-  .command-palette,
-  .footer,
-  #command-btn,
-  #theme-toggle,
-  #export-btn {
-    display: none !important;
+@media (max-width: 1100px) {
+  .help-card .metrics-grid,
+  .help-card .metrics-section:first-child .metrics-grid {
+    grid-template-columns: repeat(2, minmax(0, 1fr));
+  }
+}
+
+/* Responsive */
+@media (max-width: 768px) {
+  .container {
+    padding: 16px 16px 60px;
+  }
+
+  .topbar-inner {
+    padding: 0 16px;
+  }
+
+  .brand h1 {
+    font-size: var(--text-lg);
+  }
+
+  .section-title h2 {
+    font-size: var(--text-xl);
+  }
+
+  .toolbar {
+    grid-template-columns: 1fr;
+    align-items: stretch;
+  }
+
+  .toolbar-left,
+  .toolbar-right {
+    width: 100%;
+    justify-content: flex-start;
+  }
+
+  .global-novelty-head {
+    align-items: flex-start;
+  }
+
+  .search-box {
+    width: 100%;
+  }
+
+  .pagination {
+    flex-wrap: wrap;
+  }
+
+  .meta-grid {
+    grid-template-columns: repeat(1, minmax(0, 1fr));
+  }
+
+  .meta-item,
+  .meta-item-wide {
+    grid-column: span 1;
+  }
+
+  .metrics-grid {
+    grid-template-columns: 1fr;
+  }
+
+  .help-card .metrics-grid,
+  .help-card .metrics-section:first-child .metrics-grid {
+    grid-template-columns: 1fr;
+  }
+
+  .global-novelty {
+    padding: 12px;
+  }
+
+  .items {
+    grid-template-columns: 1fr;
+  }
+
+  .stats-grid {
+    grid-template-columns: 1fr 1fr;
   }
 
-  body {
-    background: #fff;
-    color: #111;
+  .group-head {
+    padding: 12px;
   }
 
-  .container {
-    max-width: none;
-    padding: 0;
+  .group-head-left {
+    align-items: flex-start;
+    gap: 10px;
   }
 
-  .group,
-  .item {
-    break-inside: avoid;
+  .group-head-right {
+    margin-left: auto;
   }
 
-  .codebox {
-    max-height: none;
+  .item-header {
+    grid-template-columns: 1fr;
+    gap: 6px;
   }
-}
 
-/* Accessibility */
-@media (prefers-reduced-motion: reduce) {
-  *,
-  *::before,
-  *::after {
-    animation-duration: 0.01ms !important;
-    animation-iteration-count: 1 !important;
-    transition-duration: 0.01ms !important;
+  .item-loc {
+    text-align: left;
+    justify-self: start;
+    max-width: 100%;
   }
-}
 
-:focus-visible {
-  outline: 2px solid var(--accent-primary);
-  outline-offset: 2px;
+  .cmd-search {
+    font-size: 1.35rem;
+  }
 }
 
-/* Scrollbar */
-::-webkit-scrollbar {
-  width: 8px;
-  height: 8px;
-}
+/* Print Styles */
+@media print {
+  .topbar,
+  .toolbar,
+  .btn,
+  .toast-container,
+  .cmd-palette,
+  .metrics-modal {
+    display: none !important;
+  }
 
-::-webkit-scrollbar-track {
-  background: var(--surface-1);
-}
+  .group {
+    page-break-inside: avoid;
+    break-inside: avoid;
+  }
 
-::-webkit-scrollbar-thumb {
-  background: var(--surface-3);
-  border-radius: 4px;
-}
+  .group-body {
+    display: block !important;
+  }
 
-::-webkit-scrollbar-thumb:hover {
-  background: var(--surface-4);
+  .group-toggle {
+    display: none;
+  }
 }
-
-/* Syntax Highlighting */
-${pyg_dark}
-${pyg_light}
 </style>
 </head>
-
 <body>
-<!-- Toast Container -->
-<div class="toast-container"></div>
-
-<!-- Command Palette -->
-<div class="command-palette" id="command-palette" aria-hidden="true">
-  <div class="command-backdrop"></div>
-  <div
-    class="command-dialog"
-    role="dialog"
-    aria-modal="true"
-    aria-label="Command palette"
-  >
-    <div class="command-input-wrap">
-      <input
-        type="text"
-        class="command-input"
-        id="command-input"
-        placeholder="Type a command or search..."
-        aria-label="Command search"
-        autocomplete="off"
-      />
-    </div>
-    <div
-      class="command-results"
-      id="command-results"
-      role="listbox"
-      aria-label="Command results"
-    >
-      <!-- Populated dynamically -->
-    </div>
-  </div>
-</div>
 
-<!-- Topbar -->
 <div class="topbar">
   <div class="topbar-inner">
     <div class="brand">
-      <h1>${title}</h1>
-      <div class="sub">v${version}</div>
+      <h1>CodeClone Report</h1>
+      <span class="sub">v${version}</span>
     </div>
     <div class="top-actions">
-      <button class="btn" type="button" id="command-btn" title="Command Palette (⌘K)">
-        <svg
-          width="16"
-          height="16"
-          viewBox="0 0 24 24"
-          fill="none"
-          stroke="currentColor"
-          stroke-width="2"
-        >
-          <path d="M7 20l4-16m2 16l4-16M6 9h14M4 15h14"></path>
+      <button class="btn ghost" id="theme-toggle" aria-label="Toggle theme" title="Toggle theme (T)">
+        <svg class="icon" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
+          <circle cx="12" cy="12" r="5"/>
+          <path d="M12 1v2m0 18v2M4.22 4.22l1.42 1.42m12.72 12.72l1.42 1.42M1 12h2m18 0h2M4.22 19.78l1.42-1.42M18.36 5.64l1.42-1.42"/>
         </svg>
-        <span>⌘K</span>
       </button>
-      <button class="btn" type="button" id="theme-toggle" title="Toggle theme (T)">
-        ${icon_theme}
+      <button class="btn hotkey" id="help-btn" aria-label="Open help" title="Open help (⌘I)">
+        <span>⌘I</span>
       </button>
-      <button class="btn primary" type="button" id="export-btn" title="Export report">
-        <svg
-          width="16"
-          height="16"
-          viewBox="0 0 24 24"
-          fill="none"
-          stroke="currentColor"
-          stroke-width="2"
-        >
-          <path d="M21 15v4a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2v-4"></path>
-          <polyline points="7 10 12 15 17 10"></polyline>
-          <line x1="12" y1="15" x2="12" y2="3"></line>
+      <button class="btn hotkey" id="cmd-btn" aria-label="Open command palette" title="Open command palette (⌘K)">
+        <span>⌘K</span>
+      </button>
+      <button class="btn primary" id="export-btn" aria-label="Export report as JSON" title="Export report (⌘E)">
+        <svg class="icon" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
+          <path d="M21 15v4a2 2 0 01-2 2H5a2 2 0 01-2-2v-4m14-7l-5-5m0 0L7 8m5-5v12"/>
         </svg>
         Export
       </button>
@@ -1412,509 +1753,734 @@
   </div>
 </div>
 
-<!-- Main Content -->
 <div class="container">
-
-${report_meta_html}
-
-<!-- Stats Dashboard -->
-<div class="stats-grid" id="stats-dashboard" style="display: none;">
-  <!-- Populated dynamically -->
+  ${report_meta_html}
+  ${global_novelty_html}
+  <div class="stats-grid" id="stats-dashboard" style="display: none;"></div>
+  <div class="chart-container" id="complexity-chart" style="display: none;">
+    <h3 class="chart-title">Clone Group Distribution</h3>
+    <canvas id="complexity-canvas" width="1200" height="260"></canvas>
+  </div>
+  ${func_section}
+  ${block_section}
+  ${segment_section}
+  ${empty_state_html}
+  <footer class="report-footer" aria-label="Report footer">
+    <span>Generated by CodeClone v${version}</span>
+    <span class="footer-sep">•</span>
+    <span>search</span>
+    <span class="footer-kbd">/</span>
+    <span class="footer-sep">•</span>
+    <span>commands</span>
+    <span class="footer-kbd">⌘K</span>
+    <span class="footer-sep">•</span>
+    <span>help</span>
+    <span class="footer-kbd">⌘I</span>
+    <span class="footer-sep">•</span>
+    <span>theme</span>
+    <span class="footer-kbd">T</span>
+  </footer>
 </div>
 
-<!-- Charts -->
-<div class="chart-container" id="chart-container" style="display: none;">
-  <div class="chart-title">Clone Group Distribution</div>
-  <canvas id="complexity-chart" class="chart-canvas"></canvas>
+<!-- Command Palette -->
+<div class="cmd-palette" id="cmd-palette">
+  <div class="cmd-palette-content">
+    <input
+      type="text"
+      class="cmd-search"
+      id="cmd-search"
+      placeholder="Type a command..."
+      aria-label="Command search"
+    />
+    <div class="cmd-list" id="cmd-list"></div>
+  </div>
 </div>
 
-${empty_state_html}
-
-${func_section}
-${block_section}
-${segment_section}
-
-<div class="footer">
-  Generated by CodeClone v${version} •
-  <kbd class="kbd">/</kbd> search •
-  <kbd class="kbd">⌘K</kbd> commands •
-  <kbd class="kbd">T</kbd> theme
+<!-- Metrics modal template -->
+<div class="metrics-modal" id="metrics-modal">
+  <div class="metrics-card">
+    <div class="metrics-header">
+      <h3>Clone Group Metrics</h3>
+      <button class="metrics-close" id="metrics-close" aria-label="Close">
+        <svg class="icon" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
+          <path d="M18 6L6 18M6 6l12 12"/>
+        </svg>
+      </button>
+    </div>
+    <div class="metrics-body" id="metrics-body">
+      <!-- Filled dynamically by JavaScript -->
+    </div>
+  </div>
 </div>
+
+<!-- Help Modal -->
+<div class="metrics-modal" id="help-modal">
+  <div class="metrics-card help-card">
+    <div class="metrics-header">
+      <h3>Help & Support</h3>
+      <button class="metrics-close" id="help-close" aria-label="Close help">
+        <svg class="icon" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
+          <path d="M18 6L6 18M6 6l12 12"/>
+        </svg>
+      </button>
+    </div>
+    <div class="metrics-body">
+      <div class="metrics-section">
+        <div class="metrics-section-title">Quick Shortcuts</div>
+        <div class="metrics-grid">
+          <div class="metric-item">
+            <div class="metric-label">Command Palette</div>
+            <div class="metric-badge info">⌘K / Ctrl+K</div>
+          </div>
+          <div class="metric-item">
+            <div class="metric-label">Search</div>
+            <div class="metric-badge info">/</div>
+          </div>
+          <div class="metric-item">
+            <div class="metric-label">Toggle Theme</div>
+            <div class="metric-badge info">T</div>
+          </div>
+          <div class="metric-item">
+            <div class="metric-label">Close Overlays</div>
+            <div class="metric-badge info">Esc</div>
+          </div>
+        </div>
+      </div>
+      <div class="metrics-section">
+        <div class="metrics-section-title">Project Links</div>
+        <div class="metrics-grid">
+          <div class="metric-item metric-link-item">
+            <a
+              class="help-link"
+              href="${repository_url}"
+              target="_blank"
+              rel="noopener noreferrer"
+              title="${repository_url}"
+            >
+              <span class="help-link-main">
+                <span class="help-link-title">Open Repository</span>
+                <span class="help-link-meta">github.com/orenlab/codeclone</span>
+              </span>
+              <svg class="icon help-link-icon" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
+                <path d="M7 17L17 7"/>
+                <path d="M8 7h9v9"/>
+              </svg>
+            </a>
+          </div>
+          <div class="metric-item metric-link-item">
+            <a
+              class="help-link"
+              href="${issues_url}"
+              target="_blank"
+              rel="noopener noreferrer"
+              title="${issues_url}"
+            >
+              <span class="help-link-main">
+                <span class="help-link-title">Open Issues</span>
+                <span class="help-link-meta">github.com/orenlab/codeclone/issues</span>
+              </span>
+              <svg class="icon help-link-icon" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
+                <path d="M7 17L17 7"/>
+                <path d="M8 7h9v9"/>
+              </svg>
+            </a>
+          </div>
+          <div class="metric-item metric-link-item">
+            <a
+              class="help-link"
+              href="${docs_url}"
+              target="_blank"
+              rel="noopener noreferrer"
+              title="${docs_url}"
+            >
+              <span class="help-link-main">
+                <span class="help-link-title">Open Docs</span>
+                <span class="help-link-meta">github.com/orenlab/codeclone/docs</span>
+              </span>
+              <svg class="icon help-link-icon" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
+                <path d="M7 17L17 7"/>
+                <path d="M8 7h9v9"/>
+              </svg>
+            </a>
+          </div>
+        </div>
+      </div>
+    </div>
+  </div>
 </div>
 
+<!-- Toast Container -->
+<div class="toast-container" id="toast-container"></div>
+
 <script>
-(function() {
+(function () {
   'use strict';
 
-  // ========== Utilities ==========
-  const $$ = (sel) => document.querySelector(sel);
-  const $$$$ = (sel) => document.querySelectorAll(sel);
-  const svg = (parts) => parts.join('');
-  const ICONS = {
-    info: svg([
-      '<svg class="icon" viewBox="0 0 24 24" aria-hidden="true">',
-      '<circle cx="12" cy="12" r="10" fill="none" stroke="currentColor"',
-      ' stroke-width="2"></circle>',
-      '<path d="M12 10v7" fill="none" stroke="currentColor"',
-      ' stroke-width="2"></path>',
-      '<circle cx="12" cy="7" r="1.25" fill="currentColor"></circle>',
-      '</svg>'
-    ]),
-    success: svg([
-      '<svg class="icon" viewBox="0 0 24 24" aria-hidden="true">',
-      '<circle cx="12" cy="12" r="10" fill="none" stroke="currentColor"',
-      ' stroke-width="2"></circle>',
-      '<path d="M7 12l3 3 7-7" fill="none" stroke="currentColor"',
-      ' stroke-width="2"></path>',
-      '</svg>'
-    ]),
-    warning: svg([
-      '<svg class="icon" viewBox="0 0 24 24" aria-hidden="true">',
-      '<path d="M12 3l10 18H2L12 3z" fill="none" stroke="currentColor"',
-      ' stroke-width="2"></path>',
-      '<path d="M12 9v5" fill="none" stroke="currentColor"',
-      ' stroke-width="2"></path>',
-      '<circle cx="12" cy="17" r="1.25" fill="currentColor"></circle>',
-      '</svg>'
-    ]),
-    error: svg([
-      '<svg class="icon" viewBox="0 0 24 24" aria-hidden="true">',
-      '<circle cx="12" cy="12" r="10" fill="none" stroke="currentColor"',
-      ' stroke-width="2"></circle>',
-      '<path d="M8 8l8 8M16 8l-8 8" fill="none" stroke="currentColor"',
-      ' stroke-width="2"></path>',
-      '</svg>'
-    ]),
-    exportJson: svg([
-      '<svg class="icon" viewBox="0 0 24 24" aria-hidden="true">',
-      '<path d="M12 3v12" fill="none" stroke="currentColor"',
-      ' stroke-width="2"></path>',
-      '<path d="M7 10l5 5 5-5" fill="none" stroke="currentColor"',
-      ' stroke-width="2"></path>',
-      '<path d="M5 21h14" fill="none" stroke="currentColor"',
-      ' stroke-width="2"></path>',
-      '</svg>'
-    ]),
-    exportPdf: svg([
-      '<svg class="icon" viewBox="0 0 24 24" aria-hidden="true">',
-      '<path d="M6 2h9l5 5v15H6z" fill="none" stroke="currentColor"',
-      ' stroke-width="2"></path>',
-      '<path d="M15 2v5h5" fill="none" stroke="currentColor"',
-      ' stroke-width="2"></path>',
-      '</svg>'
-    ]),
-    stats: svg([
-      '<svg class="icon" viewBox="0 0 24 24" aria-hidden="true">',
-      '<path d="M4 20V10M10 20V4M16 20v-8M22 20V7" fill="none"',
-      ' stroke="currentColor" stroke-width="2"></path>',
-      '</svg>'
-    ]),
-    charts: svg([
-      '<svg class="icon" viewBox="0 0 24 24" aria-hidden="true">',
-      '<path d="M4 20h16" fill="none" stroke="currentColor"',
-      ' stroke-width="2"></path>',
-      '<path d="M6 16l4-4 4 3 4-6" fill="none" stroke="currentColor"',
-      ' stroke-width="2"></path>',
-      '</svg>'
-    ]),
-    refresh: svg([
-      '<svg class="icon" viewBox="0 0 24 24" aria-hidden="true">',
-      '<path d="M20 6v6h-6" fill="none" stroke="currentColor"',
-      ' stroke-width="2"></path>',
-      '<path d="M4 18v-6h6" fill="none" stroke="currentColor"',
-      ' stroke-width="2"></path>',
-      '<path d="M20 12a8 8 0 0 0-14-5" fill="none"',
-      ' stroke="currentColor" stroke-width="2"></path>',
-      '<path d="M4 12a8 8 0 0 0 14 5" fill="none"',
-      ' stroke="currentColor" stroke-width="2"></path>',
-      '</svg>'
-    ]),
-    search: svg([
-      '<svg class="icon" viewBox="0 0 24 24" aria-hidden="true">',
-      '<circle cx="11" cy="11" r="7" fill="none" stroke="currentColor"',
-      ' stroke-width="2"></circle>',
-      '<path d="M20 20l-3.5-3.5" fill="none" stroke="currentColor"',
-      ' stroke-width="2"></path>',
-      '</svg>'
-    ]),
-    scrollTop: svg([
-      '<svg class="icon" viewBox="0 0 24 24" aria-hidden="true">',
-      '<path d="M12 19V5" fill="none" stroke="currentColor"',
-      ' stroke-width="2"></path>',
-      '<path d="M5 12l7-7 7 7" fill="none" stroke="currentColor"',
-      ' stroke-width="2"></path>',
-      '</svg>'
-    ]),
-    scrollBottom: svg([
-      '<svg class="icon" viewBox="0 0 24 24" aria-hidden="true">',
-      '<path d="M12 5v14" fill="none" stroke="currentColor"',
-      ' stroke-width="2"></path>',
-      '<path d="M5 12l7 7 7-7" fill="none" stroke="currentColor"',
-      ' stroke-width="2"></path>',
-      '</svg>'
-    ]),
-    theme: svg([
-      '<svg class="icon" viewBox="0 0 24 24" aria-hidden="true">',
-      '<path d="M21 12a9 9 0 1 1-9-9 7 7 0 0 0 9 9z"',
-      ' fill="none" stroke="currentColor" stroke-width="2"></path>',
-      '</svg>'
-    ]),
-    expand: svg([
-      '<svg class="icon" viewBox="0 0 24 24" aria-hidden="true">',
-      '<path d="M8 3H3v5M21 8V3h-5M3 16v5h5M21 21v-5h-5"',
-      ' fill="none" stroke="currentColor" stroke-width="2"></path>',
-      '</svg>'
-    ]),
-    collapse: svg([
-      '<svg class="icon" viewBox="0 0 24 24" aria-hidden="true">',
-      '<path d="M8 3v5H3M21 8h-5V3M3 16h5v5M16 21v-5h5"',
-      ' fill="none" stroke="currentColor" stroke-width="2"></path>',
-      '</svg>'
-    ]),
-    cloneGroups: svg([
-      '<svg class="icon" viewBox="0 0 24 24" aria-hidden="true">',
-      '<rect x="3" y="4" width="8" height="8" fill="none"',
-      ' stroke="currentColor" stroke-width="2"></rect>',
-      '<rect x="13" y="4" width="8" height="8" fill="none"',
-      ' stroke="currentColor" stroke-width="2"></rect>',
-      '<rect x="3" y="14" width="8" height="8" fill="none"',
-      ' stroke="currentColor" stroke-width="2"></rect>',
-      '</svg>'
-    ]),
-    totalClones: svg([
-      '<svg class="icon" viewBox="0 0 24 24" aria-hidden="true">',
-      '<rect x="4" y="3" width="16" height="18" rx="2" fill="none"',
-      ' stroke="currentColor" stroke-width="2"></rect>',
-      '<path d="M8 7h8M8 11h8M8 15h5" fill="none"',
-      ' stroke="currentColor" stroke-width="2"></path>',
-      '</svg>'
-    ]),
-    avgGroup: svg([
-      '<svg class="icon" viewBox="0 0 24 24" aria-hidden="true">',
-      '<path d="M4 18h16M6 15l3-4 4 3 5-7" fill="none"',
-      ' stroke="currentColor" stroke-width="2"></path>',
-      '</svg>'
-    ]),
-    largestGroup: svg([
-      '<svg class="icon" viewBox="0 0 24 24" aria-hidden="true">',
-      '<path d="M12 3l3 6 6 1-4 4 1 6-6-3-6 3 1-6-4-4',
-      ' 6-1 3-6z" fill="none" stroke="currentColor" stroke-width="2"></path>',
-      '</svg>'
-    ])
-  };
+  const $$$$ = (s) => document.querySelectorAll(s);
+  const $$ = (s) => document.querySelector(s);
 
-  // ========== State Management ==========
   const state = {
-    theme: 'dark',
+    theme: localStorage.getItem('theme') || 'dark',
     commandPaletteOpen: false,
     chartVisible: false,
-    stats: {
-      totalGroups: 0,
-      totalItems: 0,
-      avgGroupSize: 0,
-      largestGroup: 0
-    }
+    stats: {},
+    currentMetrics: null,
+    helpModalOpen: false,
+    globalNovelty: 'all'
   };
+  const sectionRefreshers = [];
 
-  function getPrimarySearchInput() {
-    const inputs = Array.from($$$$('.search'));
-    for (const input of inputs) {
-      if (input.offsetParent !== null) return input;
-    }
-    return inputs[0] || null;
-  }
-
-  // ========== Theme Management ==========
+  // ========== Theme ==========
   function initTheme() {
-    const stored = localStorage.getItem('codeclone_theme');
-    const prefersDark = window.matchMedia('(prefers-color-scheme: dark)').matches;
-    const hour = new Date().getHours();
-    const isNight = hour < 7 || hour > 19;
-
-    state.theme = stored || (prefersDark || isNight ? 'dark' : 'light');
     document.documentElement.setAttribute('data-theme', state.theme);
   }
 
   function toggleTheme() {
     state.theme = state.theme === 'dark' ? 'light' : 'dark';
     document.documentElement.setAttribute('data-theme', state.theme);
-    localStorage.setItem('codeclone_theme', state.theme);
-    if (state.chartVisible) renderComplexityChart();
+    localStorage.setItem('theme', state.theme);
     showToast('Theme switched to ' + state.theme, 'info');
   }
 
-  // ========== Toast Notifications ==========
-  function showToast(message, type = 'info') {
-    const icons = {
-      info: ICONS.info,
-      success: ICONS.success,
-      warning: ICONS.warning,
-      error: ICONS.error
-    };
+  // ========== Toast ==========
+  function showToast(msg, type = 'info') {
+    const container = $$('#toast-container');
+    if (!container) return;
 
     const toast = document.createElement('div');
-    toast.className = 'toast toast-' + type;
-    toast.innerHTML =
-      '<span class="toast-icon">' + icons[type] + '</span>' +
-      '<span class="toast-message">' + message + '</span>' +
-      '<button class="toast-close" aria-label="Close">x</button>';
+    toast.className = 'toast ' + type;
 
-    const container = $$('.toast-container');
-    container.appendChild(toast);
-
-    setTimeout(() => toast.classList.add('toast-show'), 10);
+    const icons = {
+      success: '<svg class="icon" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M22 11.08V12a10 10 0 11-5.93-9.14"/><path d="M22 4L12 14.01l-3-3"/></svg>',
+      warning: '<svg class="icon" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M10.29 3.86L1.82 18a2 2 0 001.71 3h16.94a2 2 0 001.71-3L13.71 3.86a2 2 0 00-3.42 0z"/><path d="M12 9v4m0 4h.01"/></svg>',
+      error: '<svg class="icon" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><circle cx="12" cy="12" r="10"/><path d="M15 9l-6 6m0-6l6 6"/></svg>',
+      info: '<svg class="icon" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><circle cx="12" cy="12" r="10"/><path d="M12 16v-4m0-4h.01"/></svg>'
+    };
 
-    toast.querySelector('.toast-close').addEventListener('click', () => {
-      toast.classList.remove('toast-show');
-      setTimeout(() => toast.remove(), 300);
-    });
+    const safeMessage = escapeHtml(msg);
+    toast.innerHTML = (icons[type] || icons.info) + '<span>' + safeMessage + '</span>';
+    container.appendChild(toast);
 
     setTimeout(() => {
-      toast.classList.remove('toast-show');
+      toast.style.opacity = '0';
+      toast.style.transform = 'translateX(100%)';
       setTimeout(() => toast.remove(), 300);
-    }, 4000);
+    }, 3000);
+  }
+
+  function escapeHtml(value) {
+    return String(value ?? '')
+      .replaceAll('&', '&amp;')
+      .replaceAll('<', '&lt;')
+      .replaceAll('>', '&gt;')
+      .replaceAll('"', '&quot;')
+      .replaceAll("'", '&#39;');
+  }
+
+  // ========== Metrics Modal ==========
+  function openMetricsModal(groupData) {
+    const modal = $$('#metrics-modal');
+    const body = $$('#metrics-body');
+    if (!modal || !body) return;
+
+    state.currentMetrics = groupData;
+
+    // Build HTML with metrics
+    let html = '';
+
+    function formatPercent(value) {
+      const raw = String(value || '').trim();
+      if (!raw) return '';
+      const normalized = raw.replace(/%+$$/u, '');
+      if (!normalized) return '';
+      return normalized + '%';
+    }
+
+    // Section: General information
+    html += '<div class="metrics-section">';
+    html += '<div class="metrics-section-title">General Information</div>';
+    html += '<div class="metrics-grid">';
+
+    if (groupData.clone_size) {
+      html += '<div class="metric-item">';
+      html += '<div class="metric-label">';
+      html += '<svg class="icon" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M8 3v3a2 2 0 01-2 2H3m18 0h-3a2 2 0 01-2-2V3m0 18v-3a2 2 0 012-2h3M3 16h3a2 2 0 012 2v3"/></svg>';
+      html += 'Block Size';
+      html += '</div>';
+      html += '<div class="metric-value">' + escapeHtml(groupData.clone_size) + '</div>';
+      html += '</div>';
+    }
+
+    if (groupData.items_count) {
+      html += '<div class="metric-item">';
+      html += '<div class="metric-label">';
+      html += '<svg class="icon" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M17 21v-2a4 4 0 00-4-4H5a4 4 0 00-4 4v2"/><circle cx="9" cy="7" r="4"/><path d="M23 21v-2a4 4 0 00-3-3.87m-4-12a4 4 0 010 7.75"/></svg>';
+      html += 'Clone Instances';
+      html += '</div>';
+      html += '<div class="metric-value">' + escapeHtml(groupData.items_count) + '</div>';
+      html += '</div>';
+    }
+
+    html += '</div></div>';
+
+    // Section: Technical metrics
+    html += '<div class="metrics-section">';
+    html += '<div class="metrics-section-title">Technical Metrics</div>';
+    html += '<div class="metrics-grid">';
+
+    if (groupData.matchRule) {
+      html += '<div class="metric-item">';
+      html += '<div class="metric-label">';
+      html += '<svg class="icon" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M14 2H6a2 2 0 00-2 2v16a2 2 0 002 2h12a2 2 0 002-2V8z"/><path d="M14 2v6h6"/><path d="M16 13H8m8 4H8m2-8H8"/></svg>';
+      html += 'Match Rule';
+      html += '</div>';
+      html += '<div class="metric-badge info">' + escapeHtml(groupData.matchRule) + '</div>';
+      html += '</div>';
+    }
+
+    if (groupData.signature_kind) {
+      html += '<div class="metric-item">';
+      html += '<div class="metric-label">';
+      html += '<svg class="icon" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M12 2L2 7l10 5 10-5-10-5z"/><path d="M2 17l10 5 10-5M2 12l10 5 10-5"/></svg>';
+      html += 'Signature';
+      html += '</div>';
+      html += '<div class="metric-value metric-value-compact">' + escapeHtml(groupData.signature_kind) + '</div>';
+      html += '</div>';
+    }
+
+    const patternDisplayValue = groupData.pattern_label || groupData.pattern;
+    if (patternDisplayValue) {
+      html += '<div class="metric-item">';
+      html += '<div class="metric-label">';
+      html += '<svg class="icon" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><rect x="3" y="3" width="7" height="7"/><rect x="14" y="3" width="7" height="7"/><rect x="14" y="14" width="7" height="7"/><rect x="3" y="14" width="7" height="7"/></svg>';
+      html += 'Pattern';
+      html += '</div>';
+      html += '<div class="metric-value metric-value-compact">' + escapeHtml(patternDisplayValue) + '</div>';
+      html += '</div>';
+    }
+
+    html += '</div></div>';
+
+    // Section: Quality metrics
+    if (groupData.assert_ratio || groupData.hint_label || groupData.hint_confidence || groupData.merged_regions) {
+      html += '<div class="metrics-section">';
+      html += '<div class="metrics-section-title">Quality Metrics</div>';
+      html += '<div class="metrics-grid">';
+
+      if (groupData.assert_ratio) {
+        const ratioText = formatPercent(groupData.assert_ratio);
+        const ratio = parseFloat(ratioText);
+        const badgeClass = ratio >= 70 ? 'success' : ratio >= 40 ? 'warning' : 'error';
+        html += '<div class="metric-item">';
+        html += '<div class="metric-label">';
+        html += '<svg class="icon" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M22 11.08V12a10 10 0 11-5.93-9.14"/><path d="M22 4L12 14.01l-3-3"/></svg>';
+        html += 'Assert Ratio';
+        html += '</div>';
+        html += '<div class="metric-badge ' + badgeClass + '">' + escapeHtml(ratioText) + '</div>';
+        html += '</div>';
+      }
+
+      if (groupData.hint_label) {
+        html += '<div class="metric-item">';
+        html += '<div class="metric-label">';
+        html += '<svg class="icon" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M9.09 9a3 3 0 115.82 1c0 2-3 3-3 3"/><path d="M12 17h.01"/><circle cx="12" cy="12" r="10"/></svg>';
+        html += 'Hint';
+        html += '</div>';
+        html += '<div class="metric-badge warning">' + escapeHtml(groupData.hint_label) + '</div>';
+        html += '</div>';
+      }
+
+      if (groupData.hint_confidence) {
+        html += '<div class="metric-item">';
+        html += '<div class="metric-label">';
+        html += '<svg class="icon" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M12 2v20M17 5H9.5a3.5 3.5 0 000 7h5a3.5 3.5 0 010 7H6"/></svg>';
+        html += 'Confidence';
+        html += '</div>';
+        html += '<div class="metric-badge info">' + escapeHtml(groupData.hint_confidence) + '</div>';
+        html += '</div>';
+      }
+
+      if (groupData.merged_regions) {
+        html += '<div class="metric-item">';
+        html += '<div class="metric-label">';
+        html += '<svg class="icon" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M21 16V8a2 2 0 00-1-1.73l-7-4a2 2 0 00-2 0l-7 4A2 2 0 003 8v8a2 2 0 001 1.73l7 4a2 2 0 002 0l7-4A2 2 0 0021 16z"/></svg>';
+        html += 'Merged Regions';
+        html += '</div>';
+        html += '<div class="metric-badge warning">' + escapeHtml(groupData.merged_regions) + '</div>';
+        html += '</div>';
+      }
+
+      html += '</div></div>';
+    }
+
+    // Section: Assert statistics
+    if (groupData.consecutive_asserts || groupData.boilerplate_asserts) {
+      html += '<div class="metrics-section">';
+      html += '<div class="metrics-section-title">Assert Statistics</div>';
+      html += '<div class="metrics-grid">';
+
+      if (groupData.consecutive_asserts) {
+        html += '<div class="metric-item">';
+        html += '<div class="metric-label">';
+        html += '<svg class="icon" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M3 3l7.07 16.97 2.51-7.39 7.39-2.51L3 3z"/></svg>';
+        html += 'Consecutive Asserts';
+        html += '</div>';
+        html += '<div class="metric-value">' + escapeHtml(groupData.consecutive_asserts) + '</div>';
+        html += '</div>';
+      }
+
+      if (groupData.boilerplate_asserts) {
+        html += '<div class="metric-item">';
+        html += '<div class="metric-label">';
+        html += '<svg class="icon" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M9 11l3 3L22 4"/><path d="M21 12v7a2 2 0 01-2 2H5a2 2 0 01-2-2V5a2 2 0 012-2h11"/></svg>';
+        html += 'Boilerplate Asserts';
+        html += '</div>';
+        html += '<div class="metric-badge info">' + escapeHtml(groupData.boilerplate_asserts) + '</div>';
+        html += '</div>';
+      }
+
+      html += '</div></div>';
+    }
+
+    body.innerHTML = html;
+    modal.classList.add('active');
+    document.body.style.overflow = 'hidden';
+  }
+
+  function closeMetricsModal() {
+    const modal = $$('#metrics-modal');
+    if (!modal) return;
+
+    modal.classList.remove('active');
+    if (!state.helpModalOpen) {
+      document.body.style.overflow = '';
+    }
+    state.currentMetrics = null;
+  }
+
+  function openHelpModal() {
+    const modal = $$('#help-modal');
+    if (!modal) return;
+    modal.classList.add('active');
+    state.helpModalOpen = true;
+    document.body.style.overflow = 'hidden';
+  }
+
+  function closeHelpModal() {
+    const modal = $$('#help-modal');
+    if (!modal) return;
+    modal.classList.remove('active');
+    state.helpModalOpen = false;
+    if (!state.currentMetrics) {
+      document.body.style.overflow = '';
+    }
+  }
+
+  function scrollToSection(sectionId) {
+    const section = document.getElementById(sectionId);
+    if (!section) {
+      showToast('Section not found: ' + sectionId, 'warning');
+      return;
+    }
+    section.scrollIntoView({ behavior: 'smooth', block: 'start' });
   }
 
-  window.showToast = showToast;
+  function toggleMetaPanel(forceOpen) {
+    const toggle = $$('.meta-toggle');
+    const content = $$('.meta-content');
+    if (!toggle || !content) return;
+
+    const isCollapsed = toggle.classList.contains('collapsed');
+    const open = typeof forceOpen === 'boolean' ? forceOpen : isCollapsed;
+    toggle.classList.toggle('collapsed', !open);
+    content.classList.toggle('collapsed', !open);
+  }
 
   // ========== Command Palette ==========
+  const commands = [
+    {
+      icon: '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><circle cx="12" cy="12" r="5"/><path d="M12 1v2m0 18v2M4.22 4.22l1.42 1.42m12.72 12.72l1.42 1.42M1 12h2m18 0h2M4.22 19.78l1.42-1.42M18.36 5.64l1.42-1.42"/></svg>',
+      title: 'Toggle Theme',
+      desc: 'Switch between dark and light mode',
+      shortcut: 'T',
+      action: toggleTheme
+    },
+    {
+      icon: '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><circle cx="12" cy="12" r="10"/><path d="M9.1 9a3 3 0 115.8 1c0 2-3 3-3 3"/><path d="M12 17h.01"/></svg>',
+      title: 'Open Help',
+      desc: 'Open shortcuts and support links',
+      shortcut: '⌘I',
+      action: openHelpModal
+    },
+    {
+      icon: '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M21 15v4a2 2 0 01-2 2H5a2 2 0 01-2-2v-4m14-7l-5-5m0 0L7 8m5-5v12"/></svg>',
+      title: 'Export Report',
+      desc: 'Download report as JSON',
+      shortcut: '⌘E',
+      action: () => exportReport('json')
+    },
+    {
+      icon: '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M21 15v4a2 2 0 01-2 2H5a2 2 0 01-2-2v-4m14-7l-5-5m0 0L7 8m5-5v12"/></svg>',
+      title: 'Export as PDF',
+      desc: 'Open print dialog for PDF export',
+      shortcut: null,
+      action: () => exportReport('pdf')
+    },
+    {
+      icon: '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M3 3v18h18"/><path d="M18 17V9"/><path d="M13 17V5"/><path d="M8 17v-3"/></svg>',
+      title: 'Toggle Statistics',
+      desc: 'Show or hide stats dashboard',
+      shortcut: '⌘S',
+      action: showStats
+    },
+    {
+      icon: '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M3 3v18h18"/><path d="M7 14l4-4 3 3 5-6"/></svg>',
+      title: 'Toggle Charts',
+      desc: 'Show or hide clone distribution chart',
+      shortcut: null,
+      action: showCharts
+    },
+    {
+      icon: '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M9 18l6-6-6-6"/></svg>',
+      title: 'Expand All',
+      desc: 'Expand all clone groups',
+      action: expandAll
+    },
+    {
+      icon: '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M9 18l6-6-6-6"/></svg>',
+      title: 'Collapse All',
+      desc: 'Collapse all clone groups',
+      action: collapseAll
+    },
+    {
+      icon: '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M5 15l7-7 7 7"/></svg>',
+      title: 'Scroll to Top',
+      desc: 'Jump to the top of report',
+      action: () => window.scrollTo(0, 0)
+    },
+    {
+      icon: '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M19 9l-7 7-7-7"/></svg>',
+      title: 'Scroll to Bottom',
+      desc: 'Jump to the bottom of report',
+      action: () => window.scrollTo(0, document.body.scrollHeight)
+    },
+    {
+      icon: '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><circle cx="11" cy="11" r="8"/><path d="M21 21l-4.35-4.35"/></svg>',
+      title: 'Focus Search',
+      desc: 'Focus primary search input',
+      shortcut: '/',
+      action: () => {
+        const search = getPrimarySearchInput();
+        if (search) {
+          search.focus();
+          if (typeof search.select === 'function') search.select();
+        }
+      }
+    },
+    {
+      icon: '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M4 4v5h.58M20 20v-5h-.58"/><path d="M5.64 19.36A9 9 0 1020 15"/></svg>',
+      title: 'Refresh View',
+      desc: 'Reload the report page',
+      shortcut: '⌘R',
+      action: () => location.reload()
+    },
+    {
+      icon: '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M3 4h18M3 12h18M3 20h18"/></svg>',
+      title: 'Toggle Provenance',
+      desc: 'Expand or collapse report provenance',
+      action: () => toggleMetaPanel()
+    },
+    {
+      icon: '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M3 3h18v18H3z"/></svg>',
+      title: 'Go to Function clones',
+      desc: 'Scroll to function clone groups section',
+      action: () => scrollToSection('functions')
+    },
+    {
+      icon: '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M4 4h16v16H4z"/><path d="M4 10h16M10 4v16"/></svg>',
+      title: 'Go to Block clones',
+      desc: 'Scroll to block clone groups section',
+      action: () => scrollToSection('blocks')
+    },
+    {
+      icon: '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M4 4h16v16H4z"/><path d="M4 10h16M10 4v16"/><circle cx="16.5" cy="16.5" r="1.5"/></svg>',
+      title: 'Go to Segment clones',
+      desc: 'Scroll to segment clone groups section',
+      action: () => scrollToSection('segments')
+    }
+  ];
+
   function initCommandPalette() {
-    const palette = $$('#command-palette');
-    const input = $$('#command-input');
-    const results = $$('#command-results');
-    if (!palette || !input || !results) return;
-    let selectedIndex = -1;
+    const palette = $$('#cmd-palette');
+    const search = $$('#cmd-search');
+    const list = $$('#cmd-list');
+    const btn = $$('#cmd-btn');
+    if (!palette || !search || !list) return;
 
-    const commands = [
-      {
-        section: 'Actions',
-        items: [
-          {
-            icon: ICONS.exportJson,
-            label: 'Export as JSON',
-            shortcut: '⌘E',
-            action: () => exportReport('json')
-          },
-          {
-            icon: ICONS.exportPdf,
-            label: 'Export as PDF',
-            shortcut: null,
-            action: () => exportReport('pdf')
-          },
-          {
-            icon: ICONS.stats,
-            label: 'Toggle Statistics',
-            shortcut: '⌘S',
-            action: () => showStats()
-          },
-          {
-            icon: ICONS.charts,
-            label: 'Toggle Charts',
-            shortcut: null,
-            action: () => showCharts()
-          },
-          {
-            icon: ICONS.refresh,
-            label: 'Refresh View',
-            shortcut: '⌘R',
-            action: () => location.reload()
-          }
-        ]
-      },
-      {
-        section: 'Navigation',
-        items: [
-          {
-            icon: ICONS.search,
-            label: 'Focus Search',
-            shortcut: '/',
-            action: () => {
-              const search = getPrimarySearchInput();
-              if (!search) {
-                showToast('Search is not available in this report', 'warning');
-                return;
-              }
-              search.focus();
-              if (typeof search.select === 'function') search.select();
-            }
-          },
-          {
-            icon: ICONS.scrollTop,
-            label: 'Scroll to Top',
-            shortcut: null,
-            action: () => window.scrollTo(0, 0)
-          },
-          {
-            icon: ICONS.scrollBottom,
-            label: 'Scroll to Bottom',
-            shortcut: null,
-            action: () => window.scrollTo(0, document.body.scrollHeight)
-          }
-        ]
-      },
-      {
-        section: 'View',
-        items: [
-          {
-            icon: ICONS.theme,
-            label: 'Toggle Theme',
-            shortcut: 'T',
-            action: () => toggleTheme()
-          },
-          {
-            icon: ICONS.expand,
-            label: 'Expand All',
-            shortcut: null,
-            action: () => expandAll()
-          },
-          {
-            icon: ICONS.collapse,
-            label: 'Collapse All',
-            shortcut: null,
-            action: () => collapseAll()
-          }
-        ]
-      }
-    ];
+    let filtered = commands;
+    let selectedIndex = -1;
 
-    function getVisibleCommandItems() {
-      return Array.from(results.querySelectorAll('.command-item'));
+    function getItems() {
+      return Array.from(list.querySelectorAll('.cmd-item'));
     }
 
     function setSelected(index) {
-      const items = getVisibleCommandItems();
+      const items = getItems();
       if (!items.length) {
         selectedIndex = -1;
         return;
       }
       selectedIndex = (index + items.length) % items.length;
       items.forEach((item, idx) => {
-        const isSelected = idx === selectedIndex;
-        item.classList.toggle('selected', isSelected);
-        item.setAttribute('aria-selected', isSelected ? 'true' : 'false');
+        const selected = idx === selectedIndex;
+        item.classList.toggle('selected', selected);
+        item.setAttribute('aria-selected', selected ? 'true' : 'false');
       });
       items[selectedIndex].scrollIntoView({ block: 'nearest' });
     }
 
     function renderCommands(filter = '') {
       const f = filter.toLowerCase();
-      results.innerHTML = '';
-      let rendered = 0;
-
-      commands.forEach(section => {
-        const filtered = section.items.filter(item =>
-          !f || item.label.toLowerCase().includes(f)
-        );
-
-        if (filtered.length === 0) return;
-
-        const sectionEl = document.createElement('div');
-        sectionEl.className = 'command-section';
-        sectionEl.innerHTML =
-          '<div class="command-section-title">' +
-          section.section +
-          '</div>';
-
-        filtered.forEach((item) => {
-          const btn = document.createElement('button');
-          btn.className = 'command-item';
-          btn.type = 'button';
-          btn.setAttribute('role', 'option');
-          btn.setAttribute('aria-selected', 'false');
-          btn.innerHTML =
-            '<div class="command-item-left">' +
-            '<span class="command-icon">' + item.icon + '</span>' +
-            '<span>' + item.label + '</span>' +
+      filtered = commands.filter(
+        (c) =>
+          c.title.toLowerCase().includes(f) ||
+          (c.desc && c.desc.toLowerCase().includes(f))
+      );
+
+      if (!filtered.length) {
+        list.innerHTML = '<div class="cmd-empty">No matching commands</div>';
+        selectedIndex = -1;
+        return;
+      }
+
+      list.innerHTML = filtered
+        .map((c, i) => {
+          const safeTitle = escapeHtml(c.title || '');
+          const safeDesc = c.desc ? escapeHtml(c.desc) : '';
+          const safeShortcut = c.shortcut ? escapeHtml(c.shortcut) : '';
+          return (
+            '<button type="button" class="cmd-item" role="option" aria-selected="false" data-cmd-index="' +
+            i +
+            '">' +
+            '<div class="cmd-item-icon">' +
+            c.icon +
+            '</div>' +
+            '<div class="cmd-item-text">' +
+            '<div class="cmd-item-title">' +
+            safeTitle +
             '</div>' +
-            (item.shortcut
-              ? '<kbd class="command-shortcut">' + item.shortcut + '</kbd>'
-              : '');
-          btn.addEventListener('click', () => {
-            item.action();
+            (safeDesc ? '<div class="cmd-item-desc">' + safeDesc + '</div>' : '') +
+            '</div>' +
+            (safeShortcut
+              ? '<div class="cmd-item-shortcut">' + safeShortcut + '</div>'
+              : '') +
+            '</button>'
+          );
+        })
+        .join('');
+
+      getItems().forEach((el) => {
+        el.addEventListener('click', () => {
+          const idx = Number(el.getAttribute('data-cmd-index') || '0');
+          const cmd = filtered[idx];
+          if (cmd && typeof cmd.action === 'function') {
+            cmd.action();
             closeCommandPalette();
-          });
-          btn.addEventListener('mouseenter', () => {
-            const items = getVisibleCommandItems();
-            const hoverIndex = items.indexOf(btn);
-            if (hoverIndex >= 0) setSelected(hoverIndex);
-          });
-          sectionEl.appendChild(btn);
-          rendered += 1;
+          }
         });
-
-        results.appendChild(sectionEl);
       });
 
-      if (rendered === 0) {
-        const empty = document.createElement('div');
-        empty.className = 'command-empty';
-        empty.textContent = 'No matching commands';
-        results.appendChild(empty);
-      }
       setSelected(0);
     }
 
     function openCommandPalette() {
       state.commandPaletteOpen = true;
-      palette.classList.add('show');
-      palette.setAttribute('aria-hidden', 'false');
-      input.value = '';
+      palette.classList.add('active');
+      search.value = '';
       renderCommands();
-      input.focus();
+      search.focus();
     }
 
     function closeCommandPalette() {
       state.commandPaletteOpen = false;
-      palette.classList.remove('show');
-      palette.setAttribute('aria-hidden', 'true');
-      input.value = '';
+      palette.classList.remove('active');
     }
 
-    $$('#command-btn')?.addEventListener('click', openCommandPalette);
-    $$('.command-backdrop')?.addEventListener('click', closeCommandPalette);
+    window.openCommandPalette = openCommandPalette;
+    window.closeCommandPalette = closeCommandPalette;
+
+    $$('#help-btn')?.addEventListener('click', () => {
+      openHelpModal();
+    });
+
+    btn?.addEventListener('click', () => {
+      if (state.commandPaletteOpen) {
+        closeCommandPalette();
+      } else {
+        openCommandPalette();
+      }
+    });
+
+    palette.addEventListener('click', (e) => {
+      if (e.target === palette) closeCommandPalette();
+    });
 
-    input?.addEventListener('input', (e) => {
-      renderCommands(e.target.value);
+    search.addEventListener('input', (e) => {
+      renderCommands(e.target.value || '');
     });
 
-    input?.addEventListener('keydown', (e) => {
+    search.addEventListener('keydown', (e) => {
       if (e.key === 'Escape') {
         e.preventDefault();
         closeCommandPalette();
-      } else if (e.key === 'ArrowDown') {
+        return;
+      }
+      if (e.key === 'ArrowDown') {
         e.preventDefault();
         setSelected(selectedIndex + 1);
-      } else if (e.key === 'ArrowUp') {
+        return;
+      }
+      if (e.key === 'ArrowUp') {
         e.preventDefault();
         setSelected(selectedIndex - 1);
-      } else if (e.key === 'Enter') {
+        return;
+      }
+      if (e.key === 'Enter') {
         e.preventDefault();
-        const selected = $$('.command-item.selected');
-        if (selected) selected.click();
+        const items = getItems();
+        if (!items.length || selectedIndex < 0) return;
+        const selected = items[selectedIndex];
+        selected.click();
       }
     });
 
-    window.openCommandPalette = openCommandPalette;
-    window.closeCommandPalette = closeCommandPalette;
+    renderCommands();
   }
 
-  // ========== Statistics ==========
+  function getPrimarySearchInput() {
+    return $$('#search-blocks') || $$('#search-functions') || $$('#search-segments');
+  }
+
+  // ========== Stats ==========
   function calculateStats() {
     const groups = $$$$('.group');
     const items = $$$$('.item');
 
-    state.stats.totalGroups = groups.length;
-    state.stats.totalItems = items.length;
-    state.stats.avgGroupSize = groups.length > 0
-      ? Math.round(items.length / groups.length)
-      : 0;
-
+    const total = groups.length;
+    const clones = items.length;
+    const avgClones = total > 0 ? (clones / total).toFixed(1) : '0';
     let largest = 0;
-    groups.forEach(g => {
+    groups.forEach((g) => {
       const count = g.querySelectorAll('.item').length;
       if (count > largest) largest = count;
     });
-    state.stats.largestGroup = largest;
+
+    state.stats = {
+      total_groups: total,
+      total_clones: clones,
+      avg_clones: avgClones,
+      largest_group: largest
+    };
   }
 
   function showStats() {
@@ -1929,211 +2495,105 @@
     }
 
     calculateStats();
-
-    const stats = [
-      {
-        icon: ICONS.cloneGroups,
-        value: state.stats.totalGroups,
-        label: 'Clone Groups',
-        trend: null
-      },
-      {
-        icon: ICONS.totalClones,
-        value: state.stats.totalItems,
-        label: 'Total Clones',
-        trend: null
-      },
-      {
-        icon: ICONS.avgGroup,
-        value: state.stats.avgGroupSize,
-        label: 'Avg Group Size',
-        trend: null
-      },
-      {
-        icon: ICONS.largestGroup,
-        value: state.stats.largestGroup,
-        label: 'Largest Group',
-        trend: null
-      }
-    ];
-
-    dashboard.innerHTML = stats.map(s => {
-      const trend = s.trend
-        ? '<div class="stat-trend ' + s.trend.type + '">' + s.trend.text + '</div>'
-        : '';
-      return (
-        '<div class="stat-card">' +
-        '<div class="stat-icon">' + s.icon + '</div>' +
-        '<div class="stat-value">' + s.value + '</div>' +
-        '<div class="stat-label">' + s.label + '</div>' +
-        trend +
-        '</div>'
-      );
-    }).join('');
-
+    dashboard.innerHTML =
+      '<div class="stat-card"><div class="stat-value">' +
+      state.stats.total_groups +
+      '</div><div class="stat-label">Clone Groups</div></div>' +
+      '<div class="stat-card"><div class="stat-value">' +
+      state.stats.total_clones +
+      '</div><div class="stat-label">Total Clones</div></div>' +
+      '<div class="stat-card"><div class="stat-value">' +
+      state.stats.avg_clones +
+      '</div><div class="stat-label">Avg Group Size</div></div>' +
+      '<div class="stat-card"><div class="stat-value">' +
+      state.stats.largest_group +
+      '</div><div class="stat-label">Largest Group</div></div>';
     dashboard.style.display = 'grid';
     showToast('Statistics displayed', 'success');
   }
 
-  function collectSectionMetrics() {
-    const sections = [
-      { id: 'functions', label: 'Function', colorVar: '--accent-primary' },
-      { id: 'blocks', label: 'Block', colorVar: '--success' },
-      { id: 'segments', label: 'Segment', colorVar: '--warning' }
-    ];
-    return sections.map((section) => {
-      const groups = Array.from($$$$('.group[data-group="' + section.id + '"]'));
-      return {
-        label: section.label,
-        colorVar: section.colorVar,
-        value: groups.length
-      };
-    });
-  }
-
   function renderComplexityChart() {
-    const canvas = $$('#complexity-chart');
+    const canvas = $$('#complexity-canvas');
     if (!canvas) return;
     const ctx = canvas.getContext('2d');
     if (!ctx) return;
 
-    const rect = canvas.getBoundingClientRect();
-    const width = Math.max(320, Math.floor(rect.width || 320));
-    const height = Math.max(220, Math.floor(rect.height || 300));
-    const ratio = Math.max(1, window.devicePixelRatio || 1);
+    const labels = ['Function', 'Block', 'Segment'];
+    const values = [
+      $$$$('.group[data-group="functions"]').length,
+      $$$$('.group[data-group="blocks"]').length,
+      $$$$('.group[data-group="segments"]').length
+    ];
+    const max = Math.max(...values, 1);
 
-    canvas.width = Math.floor(width * ratio);
-    canvas.height = Math.floor(height * ratio);
-    ctx.setTransform(ratio, 0, 0, ratio, 0, 0);
+    const width = canvas.width;
+    const height = canvas.height;
     ctx.clearRect(0, 0, width, height);
-
-    const styles = getComputedStyle(document.documentElement);
-    const textPrimary = styles.getPropertyValue('--text-primary').trim() || '#d1d5db';
-    const textMuted = styles.getPropertyValue('--text-muted').trim() || '#9ca3af';
-    const gridColor = styles.getPropertyValue('--border-subtle').trim() || '#334155';
-    const sansFont =
-      'ui-sans-serif, -apple-system, BlinkMacSystemFont, Segoe UI, sans-serif';
-
-    const metrics = collectSectionMetrics();
-    const maxValue = Math.max(1, ...metrics.map((m) => m.value));
-    const yMax = Math.max(4, Math.ceil(maxValue / 4) * 4);
-    const left = 52;
-    const right = 18;
-    const top = 16;
-    const bottom = 40;
-    const chartWidth = width - left - right;
-    const chartHeight = height - top - bottom;
-
-    ctx.strokeStyle = gridColor;
-    ctx.lineWidth = 1;
-    for (let step = 0; step <= 4; step += 1) {
-      const y = top + (chartHeight * step) / 4;
-      ctx.beginPath();
-      ctx.moveTo(left, y);
-      ctx.lineTo(left + chartWidth, y);
-      ctx.stroke();
-
-      const value = Math.round(yMax - (yMax * step) / 4);
-      ctx.fillStyle = textMuted;
-      ctx.font = '12px ' + sansFont;
-      ctx.textAlign = 'right';
-      ctx.fillText(String(value), left - 8, y + 4);
-    }
-
-    const slot = chartWidth / metrics.length;
-    const barWidth = Math.max(40, Math.min(90, slot * 0.56));
-    metrics.forEach((metric, idx) => {
-      const x = left + slot * idx + (slot - barWidth) / 2;
-      const barHeight = (metric.value / yMax) * chartHeight;
-      const y = top + chartHeight - barHeight;
-      const color = styles.getPropertyValue(metric.colorVar).trim() || '#4f46e5';
-
-      ctx.fillStyle = color;
-      ctx.fillRect(x, y, barWidth, barHeight);
-
-      ctx.fillStyle = textPrimary;
-      ctx.font = '600 12px ' + sansFont;
-      ctx.textAlign = 'center';
-      ctx.fillText(String(metric.value), x + barWidth / 2, y - 6);
-
-      ctx.fillStyle = textMuted;
-      ctx.font = '12px ' + sansFont;
-      ctx.fillText(metric.label, x + barWidth / 2, top + chartHeight + 18);
+    ctx.fillStyle = '#9CA3AF';
+    ctx.font = '12px Inter, sans-serif';
+
+    const left = 50;
+    const bottom = 30;
+    const chartHeight = height - 50;
+    const barWidth = 90;
+    const gap = 140;
+    const startX = left + 40;
+
+    ctx.strokeStyle = '#374151';
+    ctx.beginPath();
+    ctx.moveTo(left, 20);
+    ctx.lineTo(left, chartHeight + 20);
+    ctx.lineTo(width - 20, chartHeight + 20);
+    ctx.stroke();
+
+    const colors = ['#60A5FA', '#10B981', '#F59E0B'];
+    values.forEach((val, i) => {
+      const h = Math.round((val / max) * (chartHeight - 20));
+      const x = startX + i * gap;
+      const y = chartHeight + 20 - h;
+      ctx.fillStyle = colors[i];
+      ctx.fillRect(x, y, barWidth, h);
+      ctx.fillStyle = '#D1D5DB';
+      ctx.fillText(String(val), x + barWidth / 2 - 5, y - 8);
+      ctx.fillText(labels[i], x + 12, chartHeight + 40);
     });
-
-    if (metrics.every((metric) => metric.value === 0)) {
-      ctx.fillStyle = textMuted;
-      ctx.font = '14px ' + sansFont;
-      ctx.textAlign = 'center';
-      ctx.fillText(
-        'No clone groups to visualize',
-        left + chartWidth / 2,
-        top + chartHeight / 2
-      );
-    }
   }
 
-  // ========== Charts ==========
   function showCharts() {
-    const container = $$('#chart-container');
-    if (!container) return;
-    const visible = container.style.display !== 'none';
-    if (visible) {
-      container.style.display = 'none';
+    const chart = $$('#complexity-chart');
+    if (!chart) return;
+    const isVisible = chart.style.display !== 'none';
+    if (isVisible) {
+      chart.style.display = 'none';
       state.chartVisible = false;
       showToast('Charts hidden', 'info');
       return;
     }
-    container.style.display = 'block';
+    chart.style.display = 'block';
     state.chartVisible = true;
     renderComplexityChart();
     showToast('Charts displayed', 'success');
   }
 
   function readReportMetaFromDom() {
-    const metaEl = $$('#report-meta');
-    if (!metaEl) return {};
-
-    const boolAttr = (name) => {
-      const value = (metaEl.getAttribute(name) || '').toLowerCase();
-      if (value === 'true') return true;
-      if (value === 'false') return false;
-      return null;
-    };
-    const textAttr = (name) => {
-      const value = (metaEl.getAttribute(name) || '').trim();
-      return value || null;
-    };
-    const intAttr = (name) => {
-      const value = textAttr(name);
-      if (value === null) return null;
-      const parsed = Number(value);
-      return Number.isFinite(parsed) ? parsed : null;
-    };
-
-    return {
-      codeclone_version: textAttr('data-codeclone-version'),
-      python_version: textAttr('data-python-version'),
-      baseline_path: textAttr('data-baseline-path'),
-      baseline_version: textAttr('data-baseline-version'),
-      baseline_schema_version: intAttr('data-baseline-schema-version'),
-      baseline_python_version: textAttr('data-baseline-python-version'),
-      baseline_loaded: boolAttr('data-baseline-loaded'),
-      baseline_status: textAttr('data-baseline-status'),
-      cache_path: textAttr('data-cache-path'),
-      cache_used: boolAttr('data-cache-used')
-    };
+    const meta = {};
+    $$$$('.meta-item').forEach((item) => {
+      const label = item.querySelector('.meta-label')?.textContent?.trim();
+      const value = item.querySelector('.meta-value')?.textContent?.trim();
+      if (label && value) {
+        meta[label] = value;
+      }
+    });
+    return meta;
   }
 
   // ========== Export ==========
   function exportReport(format) {
-    calculateStats();
     if (format === 'json') {
-      const groups = Array.from($$$$('.group')).map((groupEl) => ({
-        section: groupEl.getAttribute('data-group') || '',
-        group_index: Number(groupEl.getAttribute('data-group-index') || '0'),
-        group_key: groupEl.getAttribute('data-group-key') || '',
-        items: Array.from(groupEl.querySelectorAll('.item')).map((itemEl) => ({
+      const groups = Array.from($$$$('.group')).map((g) => ({
+        id: g.getAttribute('data-group-id') || '',
+        name: g.querySelector('.group-name')?.textContent?.trim() || '',
+        items: Array.from(g.querySelectorAll('.item')).map((itemEl) => ({
           qualname: itemEl.getAttribute('data-qualname') || '',
           filepath: itemEl.getAttribute('data-filepath') || '',
           start_line: Number(itemEl.getAttribute('data-start-line') || '0'),
@@ -2199,6 +2659,17 @@
       return;
     }
 
+    // Help: ⌘I or Ctrl+I
+    if ((e.metaKey || e.ctrlKey) && key === 'i') {
+      e.preventDefault();
+      if (state.helpModalOpen) {
+        closeHelpModal();
+      } else {
+        openHelpModal();
+      }
+      return;
+    }
+
     if (state.commandPaletteOpen) {
       if (key === 'escape') {
         e.preventDefault();
@@ -2251,10 +2722,16 @@
 
     // Escape - Close modals
     if (key === 'escape') {
-      const search = getPrimarySearchInput();
-      if (search && search.value) {
-        search.value = '';
-        search.dispatchEvent(new Event('input', { bubbles: true }));
+      if (state.helpModalOpen) {
+        closeHelpModal();
+      } else if (state.currentMetrics) {
+        closeMetricsModal();
+      } else {
+        const search = getPrimarySearchInput();
+        if (search && search.value) {
+          search.value = '';
+          search.dispatchEvent(new Event('input', { bubbles: true }));
+        }
       }
     }
   });
@@ -2281,6 +2758,84 @@
     });
   });
 
+  // ========== Metrics Button Handler ==========
+  $$$$('[data-metrics-btn]').forEach((btn) => {
+    btn.addEventListener('click', (e) => {
+      e.stopPropagation();
+      const groupId = btn.getAttribute('data-metrics-btn');
+      const groupEl = $$('.group[data-group-id="' + groupId + '"]');
+      if (!groupEl) return;
+
+      // Collect all group data-* attributes
+      const groupData = {
+        id: groupId,
+        clone_size: groupEl.getAttribute('data-clone-size'),
+        items_count: groupEl.getAttribute('data-items-count'),
+        matchRule: groupEl.getAttribute('data-match-rule'),
+        signature_kind: groupEl.getAttribute('data-signature-kind'),
+        pattern: groupEl.getAttribute('data-pattern'),
+        pattern_label: groupEl.getAttribute('data-pattern-label'),
+        hint_label: groupEl.getAttribute('data-hint-label'),
+        assert_ratio: groupEl.getAttribute('data-assert-ratio'),
+        hint_confidence: groupEl.getAttribute('data-hint-confidence'),
+        merged_regions: groupEl.getAttribute('data-merged-regions'),
+        consecutive_asserts: groupEl.getAttribute('data-consecutive-asserts'),
+        boilerplate_asserts: groupEl.getAttribute('data-boilerplate-asserts')
+      };
+
+      openMetricsModal(groupData);
+    });
+  });
+
+  // ========== Metrics Modal Close Handler ==========
+  $$('#metrics-close')?.addEventListener('click', closeMetricsModal);
+  $$('#metrics-modal')?.addEventListener('click', (e) => {
+    if (e.target.id === 'metrics-modal') {
+      closeMetricsModal();
+    }
+  });
+  $$('#help-close')?.addEventListener('click', closeHelpModal);
+  $$('#help-modal')?.addEventListener('click', (e) => {
+    if (e.target.id === 'help-modal') {
+      closeHelpModal();
+    }
+  });
+
+  function initGlobalNovelty() {
+    const panel = $$('#global-novelty-controls');
+    if (!panel) {
+      state.globalNovelty = 'all';
+      return;
+    }
+
+    const buttons = Array.from(panel.querySelectorAll('[data-global-novelty]'));
+    if (!buttons.length) {
+      state.globalNovelty = 'all';
+      return;
+    }
+
+    const defaultNovelty = panel.getAttribute('data-default-novelty') || 'new';
+    state.globalNovelty = defaultNovelty;
+
+    function applyGlobalNoveltyButtons() {
+      buttons.forEach((btn) => {
+        const value = btn.getAttribute('data-global-novelty') || '';
+        btn.classList.toggle('is-active', value === state.globalNovelty);
+      });
+    }
+
+    buttons.forEach((btn) => {
+      btn.addEventListener('click', () => {
+        const value = btn.getAttribute('data-global-novelty') || 'new';
+        state.globalNovelty = value;
+        applyGlobalNoveltyButtons();
+        sectionRefreshers.forEach((refresh) => refresh());
+      });
+    });
+
+    applyGlobalNoveltyButtons();
+  }
+
   // ========== Section Management ==========
   function initSection(sectionId) {
     const section = $$('section[data-section="' + sectionId + '"]');
@@ -2296,11 +2851,14 @@
     const btnCollapseAll = $$('[data-collapse-all="' + sectionId + '"]');
     const btnExpandAll = $$('[data-expand-all="' + sectionId + '"]');
     const pill = $$('[data-count-pill="' + sectionId + '"]');
+    const hasNoveltyFilter = section.getAttribute('data-has-novelty-filter') === 'true';
 
+    const defaultNovelty = section.getAttribute('data-default-novelty') || 'all';
     const sectionState = {
       q: '',
       page: 1,
       pageSize: parseInt(selPageSize?.value || '10', 10),
+      novelty: hasNoveltyFilter ? defaultNovelty : 'all',
       filtered: groups
     };
 
@@ -2338,14 +2896,21 @@
 
     function applyFilter() {
       const q = (sectionState.q || '').trim().toLowerCase();
-      if (!q) {
-        sectionState.filtered = groups;
-      } else {
-        sectionState.filtered = groups.filter(g => {
+      sectionState.novelty = hasNoveltyFilter ? state.globalNovelty : 'all';
+      let filteredGroups = groups;
+      if (sectionState.novelty !== 'all') {
+        filteredGroups = filteredGroups.filter(g => {
+          const novelty = g.getAttribute('data-novelty') || '';
+          return novelty === sectionState.novelty;
+        });
+      }
+      if (q) {
+        filteredGroups = filteredGroups.filter(g => {
           const blob = g.getAttribute('data-search') || '';
           return blob.indexOf(q) !== -1;
         });
       }
+      sectionState.filtered = filteredGroups;
       sectionState.page = 1;
       render();
     }
@@ -2395,47 +2960,33 @@
       });
     });
 
-    render();
+    sectionRefreshers.push(() => applyFilter());
+    applyFilter();
   }
 
   // ========== Event Listeners ==========
   $$('#theme-toggle')?.addEventListener('click', toggleTheme);
   $$('#export-btn')?.addEventListener('click', () => exportReport('json'));
-  window.addEventListener('resize', () => {
-    if (state.chartVisible) renderComplexityChart();
-  });
 
   // ========== Meta Panel Toggle ==========
   function initMetaPanel() {
     const header = $$('.meta-header');
     const toggle = $$('.meta-toggle');
-    const content = $$('.meta-content');
-
-    if (!header || !toggle || !content) return;
+    if (!header || !toggle) return;
 
     // Start collapsed by default to save space
-    const startCollapsed = true;
-    if (startCollapsed) {
-      toggle.classList.add('collapsed');
-      content.classList.add('collapsed');
-    }
+    toggleMetaPanel(false);
 
     header.addEventListener('click', (e) => {
-      const isCollapsed = toggle.classList.contains('collapsed');
-
-      if (isCollapsed) {
-        toggle.classList.remove('collapsed');
-        content.classList.remove('collapsed');
-      } else {
-        toggle.classList.add('collapsed');
-        content.classList.add('collapsed');
-      }
+      e.preventDefault();
+      toggleMetaPanel();
     });
   }
 
   // ========== Initialize ==========
   initTheme();
   initCommandPalette();
+  initGlobalNovelty();
   initMetaPanel();
   initSection('functions');
   initSection('blocks');
diff --git a/codeclone/ui_messages.py b/codeclone/ui_messages.py
index a777deb..f84880b 100644
--- a/codeclone/ui_messages.py
+++ b/codeclone/ui_messages.py
@@ -1,9 +1,25 @@
 from __future__ import annotations
 
+import platform
+import shlex
+import sys
+import traceback
 from pathlib import Path
 
+from . import __version__
+from .contracts import ISSUES_URL
+
 BANNER_SUBTITLE = "[italic]Architectural duplication detector[/italic]"
 
+MARKER_CONTRACT_ERROR = "[error]CONTRACT ERROR:[/error]"
+MARKER_GATING_FAILURE = "[error]GATING FAILURE:[/error]"
+MARKER_INTERNAL_ERROR = "[error]INTERNAL ERROR:[/error]"
+
+REPORT_BLOCK_GROUP_DISPLAY_NAME_ASSERT_PATTERN = "Assert pattern block"
+REPORT_BLOCK_GROUP_COMPARE_NOTE_N_WAY = (
+    "N-way group: each block matches {peer_count} peers in this group."
+)
+
 HELP_VERSION = "Print the CodeClone version and exit."
 HELP_ROOT = "Project root directory to scan."
 HELP_MIN_LOC = "Minimum Lines of Code (LOC) to consider."
@@ -27,8 +43,10 @@
 HELP_NO_COLOR = "Disable ANSI colors in output."
 HELP_QUIET = "Minimize output (still shows warnings and errors)."
 HELP_VERBOSE = "Print detailed hash identifiers for new clones."
+HELP_DEBUG = "Print debug details (traceback and environment) on internal errors."
 
 SUMMARY_TITLE = "Analysis Summary"
+CLI_LAYOUT_WIDTH = 40
 SUMMARY_LABEL_FILES_FOUND = "Files found"
 SUMMARY_LABEL_FILES_ANALYZED = "Files analyzed"
 SUMMARY_LABEL_CACHE_HITS = "Cache hits"
@@ -73,9 +91,23 @@
     "[error]Invalid {label} output extension: {path} "
     "(expected {expected_suffix}).[/error]"
 )
+ERR_INVALID_OUTPUT_PATH = (
+    "[error]Invalid {label} output path: {path} ({error}).[/error]"
+)
 ERR_ROOT_NOT_FOUND = "[error]Root path does not exist: {path}[/error]"
 ERR_INVALID_ROOT_PATH = "[error]Invalid root path: {error}[/error]"
 ERR_SCAN_FAILED = "[error]Scan failed: {error}[/error]"
+ERR_INVALID_BASELINE_PATH = "[error]Invalid baseline path: {path} ({error}).[/error]"
+ERR_BASELINE_WRITE_FAILED = (
+    "[error]Failed to write baseline file: {path} ({error}).[/error]"
+)
+ERR_REPORT_WRITE_FAILED = (
+    "[error]Failed to write {label} report: {path} ({error}).[/error]"
+)
+ERR_UNREADABLE_SOURCE_IN_GATING = (
+    "One or more source files could not be read in CI/gating mode.\n"
+    "Unreadable source files: {count}."
+)
 
 WARN_LEGACY_CACHE = (
     "[warning]Legacy cache file found at: {legacy_path}.[/warning]\n"
@@ -89,22 +121,20 @@
     "{error}\n"
     "Please regenerate the baseline with --update-baseline."
 )
-ERR_BASELINE_VERSION_MISMATCH = "[error]Baseline version mismatch.[/error]"
-ERR_BASELINE_SCHEMA_MISMATCH = "[error]Baseline schema version mismatch.[/error]"
-WARN_BASELINE_PYTHON_MISMATCH = "[warning]Baseline Python version mismatch.[/warning]"
-ERR_BASELINE_SAME_PYTHON_REQUIRED = (
-    "[error]Baseline checks require the same Python version to "
-    "ensure deterministic results. Please regenerate the "
-    "baseline using the current interpreter.[/error]"
-)
+ACTION_UPDATE_BASELINE = "Run: codeclone . --update-baseline"
 WARN_BASELINE_MISSING = (
     "[warning]Baseline file not found at: [bold]{path}[/bold][/warning]\n"
     "[dim]Comparing against an empty baseline. "
-    "Use --update-baseline to create it.[/dim]"
+    "Use --update-baseline to create it.[/dim]\n"
+    f"[dim]{ACTION_UPDATE_BASELINE}[/dim]"
 )
 WARN_BASELINE_IGNORED = (
     "[warning]Baseline is not trusted for this run and will be ignored.[/warning]\n"
-    "[dim]Comparison will proceed against an empty baseline.[/dim]"
+    "[dim]Comparison will proceed against an empty baseline.[/dim]\n"
+    f"[dim]{ACTION_UPDATE_BASELINE}[/dim]"
+)
+ERR_BASELINE_GATING_REQUIRES_TRUSTED = (
+    f"[error]CI requires a trusted baseline.[/error]\n{ACTION_UPDATE_BASELINE}"
 )
 SUCCESS_BASELINE_UPDATED = "✔ Baseline updated: {path}"
 
@@ -118,9 +148,7 @@
 FAIL_NEW_DETAIL_FUNCTION = "Details (function clone hashes):"
 FAIL_NEW_DETAIL_BLOCK = "Details (block clone hashes):"
 
-ERR_FAIL_THRESHOLD = (
-    "\n[error]❌ FAILED: Total clones ({total}) exceed threshold ({threshold})![/error]"
-)
+ERR_FAIL_THRESHOLD = "Total clones ({total}) exceed threshold ({threshold})."
 WARN_NEW_CLONES_WITHOUT_FAIL = (
     "\n[warning]New clones detected but --fail-on-new not set.[/warning]\n"
     "Run with --update-baseline to accept them as technical debt."
@@ -145,6 +173,26 @@ def fmt_invalid_output_extension(
     )
 
 
+def fmt_invalid_output_path(*, label: str, path: Path, error: object) -> str:
+    return ERR_INVALID_OUTPUT_PATH.format(label=label, path=path, error=error)
+
+
+def fmt_invalid_baseline_path(*, path: Path, error: object) -> str:
+    return ERR_INVALID_BASELINE_PATH.format(path=path, error=error)
+
+
+def fmt_baseline_write_failed(*, path: Path, error: object) -> str:
+    return ERR_BASELINE_WRITE_FAILED.format(path=path, error=error)
+
+
+def fmt_report_write_failed(*, label: str, path: Path, error: object) -> str:
+    return ERR_REPORT_WRITE_FAILED.format(label=label, path=path, error=error)
+
+
+def fmt_unreadable_source_in_gating(*, count: int) -> str:
+    return ERR_UNREADABLE_SOURCE_IN_GATING.format(count=count)
+
+
 def fmt_scanning_root(root: Path) -> str:
     return INFO_SCANNING_ROOT.format(root=root)
 
@@ -185,45 +233,6 @@ def fmt_invalid_baseline(error: object) -> str:
     return ERR_INVALID_BASELINE.format(error=error)
 
 
-def fmt_baseline_version_missing(current_version: str) -> str:
-    return (
-        f"{ERR_BASELINE_VERSION_MISMATCH}\n"
-        "Baseline version missing (legacy baseline format).\n"
-        f"Current version: {current_version}.\n"
-        "Please regenerate the baseline with --update-baseline."
-    )
-
-
-def fmt_baseline_version_mismatch(
-    *, baseline_version: str, current_version: str
-) -> str:
-    return (
-        f"{ERR_BASELINE_VERSION_MISMATCH}\n"
-        "Baseline was generated with CodeClone "
-        f"{baseline_version}.\n"
-        f"Current version: {current_version}.\n"
-        "Please regenerate the baseline with --update-baseline."
-    )
-
-
-def fmt_baseline_schema_mismatch(*, baseline_schema: int, current_schema: int) -> str:
-    return (
-        f"{ERR_BASELINE_SCHEMA_MISMATCH}\n"
-        f"Baseline schema: {baseline_schema}. "
-        f"Current schema: {current_schema}.\n"
-        "Please regenerate the baseline with --update-baseline."
-    )
-
-
-def fmt_baseline_python_mismatch(*, baseline_python: str, current_python: str) -> str:
-    return (
-        f"{WARN_BASELINE_PYTHON_MISMATCH}\n"
-        "Baseline was generated with Python "
-        f"{baseline_python}.\n"
-        f"Current interpreter: Python {current_python}."
-    )
-
-
 def fmt_path(template: str, path: Path) -> str:
     return template.format(path=path)
 
@@ -255,3 +264,60 @@ def fmt_summary_compact_clones(
 
 def fmt_fail_threshold(*, total: int, threshold: int) -> str:
     return ERR_FAIL_THRESHOLD.format(total=total, threshold=threshold)
+
+
+def fmt_contract_error(message: str) -> str:
+    return f"{MARKER_CONTRACT_ERROR}\n{message}"
+
+
+def fmt_gating_failure(message: str) -> str:
+    return f"{MARKER_GATING_FAILURE}\n{message}"
+
+
+def fmt_internal_error(
+    error: BaseException,
+    *,
+    issues_url: str = ISSUES_URL,
+    debug: bool = False,
+) -> str:
+    bug_report_url = issues_url.rstrip("/") + "/new?template=bug_report.yml"
+    error_name = type(error).__name__
+    error_text = str(error).strip() or "<no message>"
+    lines = [
+        MARKER_INTERNAL_ERROR,
+        "Unexpected exception.",
+        f"Reason: {error_name}: {error_text}",
+        "",
+        "Next steps:",
+        "- Re-run with --debug to include a traceback.",
+        f"- If this is reproducible, open an issue: {bug_report_url}.",
+        (
+            "- Attach: command line, CodeClone version, Python version, "
+            "and the report file if generated."
+        ),
+    ]
+    if not debug:
+        return "\n".join(lines)
+
+    traceback_lines = traceback.format_exception(
+        type(error), error, error.__traceback__
+    )
+    command_line = shlex.join(sys.argv)
+    lines.extend(
+        [
+            "",
+            "DEBUG DETAILS",
+            f"Platform: {platform.platform()}",
+            f"Python: {sys.version.split()[0]}",
+            f"CodeClone: {__version__}",
+            f"Command: {command_line}",
+            f"CWD: {Path.cwd()}",
+            "Traceback:",
+            "".join(traceback_lines).rstrip(),
+        ]
+    )
+    return "\n".join(lines)
+
+
+def fmt_report_block_group_compare_note_n_way(*, peer_count: int) -> str:
+    return REPORT_BLOCK_GROUP_COMPARE_NOTE_N_WAY.format(peer_count=peer_count)
diff --git a/docs/README.md b/docs/README.md
new file mode 100644
index 0000000..f2e7cfb
--- /dev/null
+++ b/docs/README.md
@@ -0,0 +1,47 @@
+# CodeClone Docs
+
+This directory has two documentation layers.
+
+- [`docs/book/`](book/): **contract-first** documentation. This is the canonical source for **schemas**, **statuses**, *
+  *exit codes**, **trust model**, and **determinism guarantees**. Everything here is derived from code + locked tests.
+- [`docs/architecture.md`](architecture.md), [`docs/cfg.md`](cfg.md): **deep-dive narrative** docs (architecture and CFG
+  semantics). These may include rationale and design intent, but must not contradict the contract book.
+
+## Start Here
+
+- Contracts and guarantees: [`docs/book/00-intro.md`](book/00-intro.md)
+- Architecture map (components + ownership): [`docs/book/01-architecture-map.md`](book/01-architecture-map.md)
+- Terminology: [`docs/book/02-terminology.md`](book/02-terminology.md)
+
+## Core Contracts
+
+- Exit codes and failure policy: [`docs/book/03-contracts-exit-codes.md`](book/03-contracts-exit-codes.md)
+- Config and defaults: [`docs/book/04-config-and-defaults.md`](book/04-config-and-defaults.md)
+- Core pipeline and invariants: [`docs/book/05-core-pipeline.md`](book/05-core-pipeline.md)
+- Baseline contract (schema v1): [`docs/book/06-baseline.md`](book/06-baseline.md)
+- Cache contract (schema v1.2): [`docs/book/07-cache.md`](book/07-cache.md)
+- Report contract (schema v1.1): [`docs/book/08-report.md`](book/08-report.md)
+
+## Interfaces
+
+- CLI behavior, modes, and UX: [`docs/book/09-cli.md`](book/09-cli.md)
+- HTML report rendering contract: [`docs/book/10-html-render.md`](book/10-html-render.md)
+
+## System Properties
+
+- Security model and threat boundaries: [`docs/book/11-security-model.md`](book/11-security-model.md)
+- Determinism policy: [`docs/book/12-determinism.md`](book/12-determinism.md)
+- Tests as specification: [`docs/book/13-testing-as-spec.md`](book/13-testing-as-spec.md)
+- Compatibility and versioning rules: [
+  `docs/book/14-compatibility-and-versioning.md`](book/14-compatibility-and-versioning.md)
+
+## Deep Dives
+
+- Architecture narrative: [`docs/architecture.md`](architecture.md)
+- CFG design and semantics: [`docs/cfg.md`](cfg.md)
+
+## Reference Appendices
+
+- Status enums and typed contracts: [`docs/book/appendix/a-status-enums.md`](book/appendix/a-status-enums.md)
+- Schema layouts (baseline/cache/report): [`docs/book/appendix/b-schema-layouts.md`](book/appendix/b-schema-layouts.md)
+- Error catalog (contract vs internal): [`docs/book/appendix/c-error-catalog.md`](book/appendix/c-error-catalog.md)
\ No newline at end of file
diff --git a/docs/architecture.md b/docs/architecture.md
index 2722a19..e6686b6 100644
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -1,5 +1,8 @@
 # CodeClone Architecture
 
+> Scope note: this file is an architecture narrative/deep-dive.  
+> Contract-level guarantees (schemas, statuses, exit codes, trust model, determinism) are defined in `docs/book/`.
+
 This document describes the high-level architecture of **CodeClone**.
 
 ---
@@ -133,15 +136,34 @@ Detected clone groups can be:
 
 All report formats include provenance metadata:
 
+- `report_schema_version`
 - `codeclone_version`
-- `python_version`
+- `python_version` (runtime major.minor, human-readable)
+- `python_tag` (runtime compatibility tag used by baseline/cache contracts)
 - `baseline_path`
-- `baseline_version`
+- `baseline_fingerprint_version`
 - `baseline_schema_version`
-- `baseline_python_version`
+- `baseline_python_tag`
+- `baseline_generator_name`
+- `baseline_generator_version`
+- `baseline_payload_sha256`
+- `baseline_payload_sha256_verified`
 - `baseline_loaded`
 - `baseline_status`
-  (`ok | missing | legacy | invalid | mismatch_version | mismatch_schema | mismatch_python | generator_mismatch | integrity_missing | integrity_failed | too_large`)
+  (
+  `ok | missing | too_large | invalid_json | invalid_type | missing_fields | mismatch_schema_version | mismatch_fingerprint_version | mismatch_python_version | generator_mismatch | integrity_missing | integrity_failed`;
+  `mismatch_python_version` is the status name used for `python_tag` mismatch)
+- `cache_path`
+- `cache_schema_version`
+- `cache_status`
+- `cache_used`
+- `files_skipped_source_io`
+
+Explainability contract (v1):
+
+- Explainability facts are produced only by Python core/report layer.
+- HTML/JS renderer is display-only and must not recalculate metrics or introduce new semantics.
+- UI can format, filter, and highlight facts, but cannot invent new hints.
 
 ---
 
@@ -150,35 +172,49 @@ All report formats include provenance metadata:
 Baseline comparison allows CI to fail **only on new clones**,
 enabling gradual architectural improvement.
 
-Baseline files are **versioned**. The baseline stores the CodeClone version and schema
-version used to generate it. Mismatches result in a hard stop and require regeneration.
-Baseline format in 1.3+ is tamper-evident (`generator`, `payload_sha256`) and validated
-before baseline diffing.
+Baseline files use a stable v1 contract. Compatibility is checked by
+`schema_version`, `fingerprint_version`, `python_tag`, and `generator.name`,
+not package patch/minor version.
+Regeneration is typically required when `fingerprint_version` or `python_tag` changes.
+Baseline integrity is tamper-evident via canonical `payload_sha256`, which covers
+`clones.functions`, `clones.blocks`, `meta.fingerprint_version`, and `meta.python_tag`.
+`schema_version` and `generator.name` are compatibility gates and intentionally
+excluded from the integrity hash.
+`created_at` and `generator.version` are informational metadata and do not affect
+integrity validation.
 
 Baseline validation order is deterministic:
 
 1. size guard (before JSON parse),
 2. JSON parse and root object/type checks,
-3. legacy/version/schema policy checks,
-4. Python version policy check,
-5. integrity checks (`generator`, `payload_sha256`) for v1.3+ baseline format only.
+3. required fields and type checks,
+4. compatibility checks (`generator`, `schema_version`, `fingerprint_version`, `python_tag`),
+5. integrity checks (`payload_sha256`).
 
 Baseline loading is strict: schema/type violations, integrity failures, generator mismatch,
 or oversized files are treated as untrusted input.
-In `--fail-on-new` / `--ci`, untrusted baseline states fail fast.
+In `--ci` (or explicit `--fail-on-new`), untrusted baseline states fail fast.
 Outside gating mode, untrusted baseline is ignored with warning and comparison proceeds
 against an empty baseline.
 Baseline size guard is configurable via `--max-baseline-size-mb`.
 
-## Python Version Consistency for Baseline Checks
+CLI exit code contract:
+
+- `0` success
+- `2` contract error (invalid arguments/output options, untrusted baseline, or unreadable source files in gating mode)
+- `3` gating failure (`--ci` new clones, or `--fail-threshold` exceeded)
+- `5` unexpected internal error (reserved)
+
+`5` is reserved only for unexpected internal exception paths (tool bug), not for
+baseline/options contract violations.
 
-Due to inherent differences in Python’s AST between interpreter versions, baseline
-generation and verification must be performed using the same Python version.
+## Python Tag Consistency for Baseline Checks
 
-This ensures deterministic and reproducible clone detection results.
+Due to inherent AST differences across interpreter builds, baseline compatibility
+is pinned to `python_tag` (for example `cp313`).
 
-CI checks therefore pin baseline verification to a single Python version, while the
-test matrix continues to validate compatibility across Python 3.10–3.14.
+This preserves deterministic and reproducible clone detection results while allowing
+patch updates within the same interpreter tag.
 
 ---
 
diff --git a/docs/book/00-intro.md b/docs/book/00-intro.md
new file mode 100644
index 0000000..637b2f2
--- /dev/null
+++ b/docs/book/00-intro.md
@@ -0,0 +1,66 @@
+# 00. Intro
+
+## Purpose
+This book is the executable contract for CodeClone behavior in v1.x. It describes only behavior that is present in code and/or locked by tests.
+
+## Public surface
+- CLI entrypoint: `codeclone/cli.py:main`
+- Package version: `codeclone/__init__.py:__version__`
+- Global contract constants: `codeclone/contracts.py`
+
+## Contracts
+CodeClone provides these guarantees when inputs are identical (same repository content, same Python tag, same tool version, same baseline/cache/report schemas):
+- Deterministic clone grouping and report serialization.
+- Explicit trust model for baseline/cache.
+- Stable exit-code categories for contract vs gating vs internal failures.
+
+Refs:
+- `codeclone/_report_serialize.py:to_json_report`
+- `codeclone/baseline.py:Baseline.verify_compatibility`
+- `codeclone/cache.py:Cache.load`
+- `codeclone/contracts.py:ExitCode`
+
+## Invariants (MUST)
+- Contract errors and gating failures are separate categories.
+- Baseline trust is explicit (`baseline_loaded`, `baseline_status`).
+- Cache is optimization-only; invalid cache never becomes source of truth.
+
+Refs:
+- `codeclone/cli.py:_main_impl`
+- `codeclone/baseline.py:BASELINE_UNTRUSTED_STATUSES`
+- `codeclone/cache.py:Cache._ignore_cache`
+
+## Failure modes
+| Condition | Behavior |
+| --- | --- |
+| Invalid/untrusted baseline in normal mode | Warning + compare against empty baseline |
+| Invalid/untrusted baseline in CI/gating mode | Contract error (exit 2) |
+| New clones in gating mode | Gating failure (exit 3) |
+| Unexpected runtime exception | Internal error (exit 5) |
+
+Refs:
+- `codeclone/cli.py:_main_impl`
+- `codeclone/cli.py:main`
+
+## Determinism / canonicalization
+- Filesystem traversal is sorted before processing.
+- Group keys and serialized arrays are sorted in report JSON/TXT.
+- Baseline and cache payload hashing uses canonical JSON serialization.
+
+Refs:
+- `codeclone/scanner.py:iter_py_files`
+- `codeclone/_report_serialize.py:to_json_report`
+- `codeclone/baseline.py:_compute_payload_sha256`
+- `codeclone/cache.py:_canonical_json`
+
+## Locked by tests
+- `tests/test_detector_golden.py::test_detector_output_matches_golden_fixture`
+- `tests/test_report.py::test_report_json_deterministic_group_order`
+- `tests/test_baseline.py::test_baseline_hash_canonical_determinism`
+- `tests/test_cache.py::test_cache_signature_validation_ignores_json_whitespace`
+- `tests/test_cli_unit.py::test_cli_help_text_consistency`
+
+## Non-guarantees
+- Cross-Python-tag clone IDs are not guaranteed identical.
+- UI wording and visual layout may evolve without schema bumps.
+- Performance characteristics are best-effort, not strict SLA.
diff --git a/docs/book/01-architecture-map.md b/docs/book/01-architecture-map.md
new file mode 100644
index 0000000..2051c72
--- /dev/null
+++ b/docs/book/01-architecture-map.md
@@ -0,0 +1,74 @@
+# 01. Architecture Map
+
+## Purpose
+Document the current module boundaries and ownership in the codebase.
+
+## Public surface
+Main ownership layers:
+- Core detection pipeline: scanner → extractor → cfg/normalize → grouping.
+- Contracts/IO: baseline, cache, CLI validation, exit semantics.
+- Report model/serialization: JSON/TXT generation and explainability facts.
+- Render layer: HTML rendering and template assets.
+
+## Data model
+| Layer | Modules | Responsibility |
+| --- | --- | --- |
+| Contracts | `codeclone/contracts.py`, `codeclone/errors.py` | Shared schema versions, URLs, exit-code enum, typed exceptions |
+| Discovery + parsing | `codeclone/scanner.py`, `codeclone/extractor.py` | Enumerate files, parse AST, extract function/block/segment units |
+| Structural analysis | `codeclone/cfg.py`, `codeclone/normalize.py`, `codeclone/blockhash.py`, `codeclone/fingerprint.py`, `codeclone/blocks.py` | CFG, normalization, statement hashes, block/segment windows |
+| Grouping + report core | `codeclone/_report_grouping.py`, `codeclone/_report_blocks.py`, `codeclone/_report_segments.py`, `codeclone/_report_explain.py` | Build groups, merge windows, suppress segment noise, compute explainability facts |
+| Report serialization | `codeclone/_report_serialize.py`, `codeclone/_cli_meta.py` | Canonical JSON/TXT schema + shared report metadata |
+| Rendering | `codeclone/html_report.py`, `codeclone/_html_escape.py`, `codeclone/_html_snippets.py`, `codeclone/templates.py` | HTML-only view layer over report model |
+| Runtime orchestration | `codeclone/cli.py`, `codeclone/_cli_args.py`, `codeclone/_cli_paths.py`, `codeclone/_cli_summary.py`, `codeclone/ui_messages.py` | CLI UX, status handling, outputs, error category markers |
+
+Refs:
+- `codeclone/report.py`
+- `codeclone/cli.py:_main_impl`
+
+## Contracts
+- Core pipeline does not depend on HTML modules.
+- HTML rendering receives already-computed report data/facts.
+- Baseline and cache contracts are validated before being trusted.
+
+Refs:
+- `codeclone/report.py`
+- `codeclone/html_report.py:build_html_report`
+- `codeclone/baseline.py:Baseline.load`
+- `codeclone/cache.py:Cache.load`
+
+## Invariants (MUST)
+- Report serialization is deterministic and schema-versioned.
+- UI is render-only and must not recompute detection semantics.
+- Status enums are domain-owned in baseline/cache modules.
+
+Refs:
+- `codeclone/_report_serialize.py:to_json_report`
+- `codeclone/_report_explain.py:build_block_group_facts`
+- `codeclone/baseline.py:BaselineStatus`
+- `codeclone/cache.py:CacheStatus`
+
+## Failure modes
+| Condition | Layer |
+| --- | --- |
+| Invalid CLI args / invalid output path | Runtime orchestration (`_cli_args`, `_cli_paths`) |
+| Baseline schema/integrity mismatch | Baseline contract layer |
+| Cache corruption/version mismatch | Cache contract layer (fail-open) |
+| HTML snippet read failure | Render layer fallback snippet |
+
+## Determinism / canonicalization
+- File iteration and group key ordering are explicit sorts.
+- Report serializer uses fixed record layouts and sorted keys.
+
+Refs:
+- `codeclone/scanner.py:iter_py_files`
+- `codeclone/_report_serialize.py:GROUP_ITEM_LAYOUT`
+
+## Locked by tests
+- `tests/test_report.py::test_report_json_compact_v11_contract`
+- `tests/test_html_report.py::test_html_report_uses_core_block_group_facts`
+- `tests/test_cache.py::test_cache_v12_uses_relpaths_when_root_set`
+- `tests/test_cli_unit.py::test_argument_parser_contract_error_marker_for_invalid_args`
+
+## Non-guarantees
+- Internal module split may change in v1.x if public contracts are preserved.
+- Import tree acyclicity is a policy goal, not currently enforced by tooling.
diff --git a/docs/book/02-terminology.md b/docs/book/02-terminology.md
new file mode 100644
index 0000000..284a1e3
--- /dev/null
+++ b/docs/book/02-terminology.md
@@ -0,0 +1,75 @@
+# 02. Terminology
+
+## Purpose
+Define terms exactly as used by code and tests.
+
+## Public surface
+- Baseline identifiers and statuses: `codeclone/baseline.py`
+- Cache statuses and compact layout: `codeclone/cache.py`
+- Report schema and group layouts: `codeclone/_report_serialize.py`
+
+## Data model
+- **fingerprint**: function-level CFG fingerprint (`sha1`) + LOC bucket key.
+- **block_hash**: ordered sequence of normalized statement hashes in a fixed window.
+- **segment_hash**: hash of ordered segment window.
+- **segment_sig**: hash of sorted segment window (candidate grouping signature).
+- **python_tag**: runtime compatibility tag like `cp313`.
+- **schema_version**:
+  - baseline schema (`meta.schema_version`) for baseline compatibility.
+  - cache schema (`v`) for cache compatibility.
+  - report schema (`meta.report_schema_version`) for report format compatibility.
+- **payload_sha256**: canonical baseline semantic hash.
+- **trusted baseline**: baseline loaded + status `ok`.
+
+Refs:
+- `codeclone/_report_grouping.py:build_groups`
+- `codeclone/blocks.py:extract_blocks`
+- `codeclone/blocks.py:extract_segments`
+- `codeclone/baseline.py:current_python_tag`
+- `codeclone/baseline.py:Baseline.verify_compatibility`
+
+## Contracts
+- New/known classification is key-based, not item-heuristic-based.
+- Baseline trust is status-driven.
+- Cache trust is status-driven and independent from baseline trust.
+
+Refs:
+- `codeclone/_report_serialize.py:_split_for`
+- `codeclone/cli.py:_main_impl`
+
+## Invariants (MUST)
+- Function group key format: `fingerprint|loc_bucket`.
+- Block group key format: `block_hash`.
+- Segment group key format: `segment_hash|qualname` (internal/report-only grouping path).
+
+Refs:
+- `codeclone/_report_grouping.py:build_groups`
+- `codeclone/_report_grouping.py:build_block_groups`
+- `codeclone/_report_grouping.py:build_segment_groups`
+
+## Failure modes
+| Condition | Result |
+| --- | --- |
+| Baseline generator name != `codeclone` | `generator_mismatch` |
+| Baseline python tag mismatch | `mismatch_python_version` |
+| Cache signature mismatch | `integrity_failed` cache status |
+
+Refs:
+- `codeclone/baseline.py:Baseline.verify_compatibility`
+- `codeclone/cache.py:Cache._parse_cache_document`
+
+## Determinism / canonicalization
+- Baseline clone ID lists must be sorted and unique.
+- Cache compact arrays are sorted by deterministic tuple keys before write.
+
+Refs:
+- `codeclone/baseline.py:_require_sorted_unique_ids`
+- `codeclone/cache.py:_encode_wire_file_entry`
+
+## Locked by tests
+- `tests/test_baseline.py::test_baseline_id_lists_must_be_sorted_and_unique`
+- `tests/test_report.py::test_report_json_group_order_is_lexicographic`
+- `tests/test_cache.py::test_cache_version_mismatch_warns`
+
+## Non-guarantees
+- Exact wording of status descriptions in UI is not a schema contract.
diff --git a/docs/book/03-contracts-exit-codes.md b/docs/book/03-contracts-exit-codes.md
new file mode 100644
index 0000000..46a47f6
--- /dev/null
+++ b/docs/book/03-contracts-exit-codes.md
@@ -0,0 +1,68 @@
+# 03. Contracts: Exit Codes
+
+## Purpose
+Define stable process exit semantics and category boundaries.
+
+## Public surface
+- Exit enum: `codeclone/contracts.py:ExitCode`
+- CLI categorization and exits: `codeclone/cli.py:_main_impl`, `codeclone/cli.py:main`
+- Error markers: `codeclone/ui_messages.py`
+
+## Data model
+| Exit code | Category | Meaning |
+| --- | --- | --- |
+| 0 | success | Run completed without gating failures |
+| 2 | contract error | Input/contract violation (baseline trust, output path/ext, unreadable source in gating) |
+| 3 | gating failure | Analysis succeeded but policy failed (`--fail-on-new`, `--fail-threshold`) |
+| 5 | internal error | Unexpected exception escaped `_main_impl` |
+
+Refs:
+- `codeclone/contracts.py:ExitCode`
+- `codeclone/_cli_args.py:_ArgumentParser.error`
+
+## Contracts
+- Contract errors must use `CONTRACT ERROR:` marker.
+- Gating failures must use `GATING FAILURE:` marker.
+- Internal errors are formatted by `fmt_internal_error`; traceback hidden unless debug enabled.
+
+Refs:
+- `codeclone/ui_messages.py:fmt_contract_error`
+- `codeclone/ui_messages.py:fmt_gating_failure`
+- `codeclone/ui_messages.py:fmt_internal_error`
+
+## Invariants (MUST)
+- `SystemExit` from contract/gating paths must pass through `main()` unchanged.
+- Only non-`SystemExit` exceptions in `main()` become exit 5.
+- In gating mode, unreadable source files force exit 2 even if clone gating would also fail.
+
+Refs:
+- `codeclone/cli.py:main`
+- `codeclone/cli.py:_main_impl`
+
+## Failure modes
+| Condition | Marker | Exit |
+| --- | --- | --- |
+| Invalid output extension | CONTRACT ERROR | 2 |
+| Untrusted baseline in CI/gating | CONTRACT ERROR | 2 |
+| Unreadable source in CI/gating | CONTRACT ERROR | 2 |
+| New clones with `--fail-on-new` | GATING FAILURE | 3 |
+| Threshold exceeded | GATING FAILURE | 3 |
+| Unexpected exception in main pipeline | INTERNAL ERROR | 5 |
+
+## Determinism / canonicalization
+- Help epilog strings are generated from static constants.
+- Error category markers are static constants.
+
+Refs:
+- `codeclone/contracts.py:cli_help_epilog`
+- `codeclone/ui_messages.py:MARKER_CONTRACT_ERROR`
+
+## Locked by tests
+- `tests/test_cli_unit.py::test_cli_help_text_consistency`
+- `tests/test_cli_unit.py::test_cli_internal_error_marker`
+- `tests/test_cli_unit.py::test_cli_internal_error_debug_flag_includes_traceback`
+- `tests/test_cli_inprocess.py::test_cli_unreadable_source_fails_in_ci_with_contract_error`
+- `tests/test_cli_inprocess.py::test_cli_contract_error_priority_over_gating_failure_for_unreadable_source`
+
+## Non-guarantees
+- Exact message body text may evolve; category marker and exit code are contract.
diff --git a/docs/book/04-config-and-defaults.md b/docs/book/04-config-and-defaults.md
new file mode 100644
index 0000000..a539a7b
--- /dev/null
+++ b/docs/book/04-config-and-defaults.md
@@ -0,0 +1,74 @@
+# 04. Config and Defaults
+
+## Purpose
+Describe effective runtime configuration and defaults that affect behavior.
+
+## Public surface
+- CLI parser and defaults: `codeclone/_cli_args.py:build_parser`
+- Effective cache default path logic: `codeclone/cli.py:_main_impl`
+- Debug mode sources: `codeclone/cli.py:_is_debug_enabled`
+
+## Data model
+Configuration sources, in precedence order:
+1. CLI flags (`argparse`)
+2. Environment (`CODECLONE_DEBUG=1` for debug diagnostics)
+3. Code defaults in parser and runtime
+
+Key defaults:
+- `root="."`
+- `--min-loc=15`
+- `--min-stmt=6`
+- `--processes=4`
+- `--baseline=codeclone.baseline.json`
+- `--max-baseline-size-mb=5`
+- `--max-cache-size-mb=50`
+- default cache path (when no cache flag is given): `<root>/.cache/codeclone/cache.json`
+
+Refs:
+- `codeclone/_cli_args.py:build_parser`
+- `codeclone/cli.py:_main_impl`
+
+## Contracts
+- `--ci` is a preset: enables `fail_on_new`, `no_color`, `quiet`.
+- `--quiet` implies `--no-progress`.
+- Negative size limits are contract errors.
+
+Refs:
+- `codeclone/cli.py:_main_impl`
+
+## Invariants (MUST)
+- Detection thresholds (`min-loc`, `min-stmt`) affect extraction.
+- Reporting flags (`--html/--json/--text`) affect output only.
+- `--cache-path` overrides project-local cache default; legacy alias `--cache-dir` maps to same destination.
+
+Refs:
+- `codeclone/extractor.py:extract_units_from_source`
+- `codeclone/_cli_args.py:build_parser`
+
+## Failure modes
+| Condition | Behavior |
+| --- | --- |
+| Invalid output extension/path | Contract error (2) |
+| Invalid root path | Contract error (2) |
+| Negative size limits | Contract error (2) |
+
+Refs:
+- `codeclone/_cli_paths.py:_validate_output_path`
+- `codeclone/cli.py:_main_impl`
+
+## Determinism / canonicalization
+- Parser help text and epilog are deterministic constants.
+- Summary metric labels are deterministic constants.
+
+Refs:
+- `codeclone/contracts.py:cli_help_epilog`
+- `codeclone/ui_messages.py:SUMMARY_LABEL_FILES_FOUND`
+
+## Locked by tests
+- `tests/test_cli_unit.py::test_cli_help_text_consistency`
+- `tests/test_cli_inprocess.py::test_cli_default_cache_dir_uses_root`
+- `tests/test_cli_inprocess.py::test_cli_cache_dir_override_respected`
+- `tests/test_cli_inprocess.py::test_cli_negative_size_limits_fail_fast`
+
+## Non-guarantees
+- CLI help section ordering is stable today but not versioned independently from the CLI contract.
diff --git a/docs/book/05-core-pipeline.md b/docs/book/05-core-pipeline.md
new file mode 100644
index 0000000..521247c
--- /dev/null
+++ b/docs/book/05-core-pipeline.md
@@ -0,0 +1,77 @@
+# 05. Core Pipeline
+
+## Purpose
+Describe the detection pipeline from file discovery to grouped clones.
+
+## Public surface
+Pipeline entrypoints:
+- Discovery: `codeclone/scanner.py:iter_py_files`
+- Per-file processing: `codeclone/cli.py:process_file`
+- Extraction: `codeclone/extractor.py:extract_units_from_source`
+- Grouping: `codeclone/_report_grouping.py`
+
+## Data model
+Stages:
+1. Discover Python files (`iter_py_files`, sorted traversal)
+2. Load from cache if `stat` signature matches
+3. Process changed files:
+   - read source
+   - AST parse with limits
+   - extract units/blocks/segments
+4. Build groups:
+   - function groups by `fingerprint|loc_bucket`
+   - block groups by `block_hash`
+   - segment groups by `segment_sig` then `segment_hash|qualname`
+5. Report-layer post-processing:
+   - merge block windows to maximal regions
+   - merge/suppress segment report groups
+
+Refs:
+- `codeclone/cli.py:_main_impl`
+- `codeclone/extractor.py:extract_units_from_source`
+- `codeclone/_report_blocks.py:prepare_block_report_groups`
+- `codeclone/_report_segments.py:prepare_segment_report_groups`
+
+## Contracts
+- Detection core (`extractor`, `normalize`, `cfg`, `blocks`) computes clone candidates.
+- Report-layer transformations do not change function/block grouping keys used for baseline diff.
+- Segment groups are report-only and do not participate in baseline diff/gating.
+
+Refs:
+- `codeclone/cli.py:_main_impl` (diff uses only function/block groups)
+- `codeclone/baseline.py:Baseline.diff`
+
+## Invariants (MUST)
+- `Files found = Files analyzed + Cache hits + Files skipped` warning if broken.
+- In gating mode, unreadable source IO (`source_read_error`) is a contract failure.
+- Parser time/resource protections are applied in POSIX mode via `_parse_limits`.
+
+Refs:
+- `codeclone/_cli_summary.py:_print_summary`
+- `codeclone/cli.py:_main_impl`
+- `codeclone/extractor.py:_parse_limits`
+
+## Failure modes
+| Condition | Behavior |
+| --- | --- |
+| File stat/read/encoding error | File skipped; tracked as failed file; source-read subset tracked separately |
+| Source read error in gating mode | Contract error exit 2 |
+| Parser timeout | `ParseError` returned through processing failure path |
+| Unexpected per-file exception | Captured as `ProcessingResult(error_kind="unexpected_error")` |
+
+## Determinism / canonicalization
+- File list is sorted.
+- Group sorting in reports is deterministic by key and stable item sort.
+
+Refs:
+- `codeclone/scanner.py:iter_py_files`
+- `codeclone/_report_serialize.py:_item_sort_key`
+
+## Locked by tests
+- `tests/test_scanner_extra.py::test_iter_py_files_deterministic_sorted_order`
+- `tests/test_cli_inprocess.py::test_cli_summary_cache_miss_metrics`
+- `tests/test_cli_inprocess.py::test_cli_unreadable_source_fails_in_ci_with_contract_error`
+- `tests/test_extractor.py::test_parse_limits_triggers_timeout`
+
+## Non-guarantees
+- Parallel scheduling order is not guaranteed; only final grouped output determinism is guaranteed.
diff --git a/docs/book/06-baseline.md b/docs/book/06-baseline.md
new file mode 100644
index 0000000..a52e6a0
--- /dev/null
+++ b/docs/book/06-baseline.md
@@ -0,0 +1,99 @@
+# 06. Baseline
+
+## Purpose
+Specify baseline schema v1, trust/compatibility checks, integrity hashing, and runtime behavior.
+
+## Public surface
+- Baseline object lifecycle: `codeclone/baseline.py:Baseline`
+- Baseline statuses: `codeclone/baseline.py:BaselineStatus`
+- Baseline status coercion: `codeclone/baseline.py:coerce_baseline_status`
+- CLI integration: `codeclone/cli.py:_main_impl`
+
+## Data model
+Canonical baseline shape:
+- Top-level keys: `meta`, `clones`
+- `meta` required keys: `generator`, `schema_version`, `fingerprint_version`, `python_tag`, `created_at`, `payload_sha256`
+- `clones` required keys: `functions`, `blocks`
+- `functions` and `blocks` are sorted/unique `list[str]`
+
+Refs:
+- `codeclone/baseline.py:_TOP_LEVEL_KEYS`
+- `codeclone/baseline.py:_META_REQUIRED_KEYS`
+- `codeclone/baseline.py:_CLONES_REQUIRED_KEYS`
+- `codeclone/baseline.py:_require_sorted_unique_ids`
+
+## Contracts
+Compatibility gates (`verify_compatibility`):
+- `generator == "codeclone"`
+- `schema_version` major/minor compatible with supported schema
+- `fingerprint_version == BASELINE_FINGERPRINT_VERSION`
+- `python_tag == current_python_tag()`
+- integrity verified via `payload_sha256`
+
+Integrity payload includes only:
+- `clones.functions`
+- `clones.blocks`
+- `meta.fingerprint_version`
+- `meta.python_tag`
+
+Integrity payload excludes:
+- `meta.schema_version`
+- `meta.generator.*`
+- `meta.created_at`
+
+Refs:
+- `codeclone/baseline.py:Baseline.verify_compatibility`
+- `codeclone/baseline.py:_compute_payload_sha256`
+
+## Invariants (MUST)
+- Legacy top-level baselines (`functions`/`blocks` at root) are untrusted and require regeneration.
+- Baseline writes are atomic (`*.tmp` + `os.replace`, same filesystem).
+- Baseline diff is set-based and ignores deleted baseline keys.
+
+Refs:
+- `codeclone/baseline.py:_is_legacy_baseline_payload`
+- `codeclone/baseline.py:_atomic_write_json`
+- `codeclone/baseline.py:Baseline.diff`
+
+## Failure modes
+| Condition | Status |
+| --- | --- |
+| File missing | `missing` |
+| Too large | `too_large` |
+| JSON decode failure | `invalid_json` |
+| Top-level shape/type mismatch | `invalid_type` / `missing_fields` |
+| Schema mismatch | `mismatch_schema_version` |
+| Fingerprint mismatch | `mismatch_fingerprint_version` |
+| Python tag mismatch | `mismatch_python_version` |
+| Generator mismatch | `generator_mismatch` |
+| Hash missing/invalid | `integrity_missing` |
+| Hash mismatch | `integrity_failed` |
+
+CLI behavior:
+- Normal mode: untrusted baseline is ignored, diff runs against empty baseline.
+- Gating mode (`--ci` / `--fail-on-new`): untrusted baseline is contract error (exit 2).
+
+Refs:
+- `codeclone/baseline.py:BaselineStatus`
+- `codeclone/cli.py:_main_impl`
+
+## Determinism / canonicalization
+- Clone IDs are serialized sorted.
+- Hash serialization uses canonical JSON (`sort_keys=True`, compact separators).
+- `payload_sha256` uses `hmac.compare_digest` during verification.
+
+Refs:
+- `codeclone/baseline.py:_baseline_payload`
+- `codeclone/baseline.py:_compute_payload_sha256`
+- `codeclone/baseline.py:Baseline.verify_integrity`
+
+## Locked by tests
+- `tests/test_baseline.py::test_baseline_roundtrip_v1`
+- `tests/test_baseline.py::test_baseline_payload_fields_contract_invariant`
+- `tests/test_baseline.py::test_baseline_payload_sha256_independent_of_schema_version`
+- `tests/test_baseline.py::test_baseline_verify_python_tag_mismatch`
+- `tests/test_cli_inprocess.py::test_cli_untrusted_baseline_fails_in_ci`
+
+## Non-guarantees
+- Baseline generator version (`meta.generator.version`) is informational and not a compatibility gate.
+- Baseline file ordering/indentation style is not part of compatibility contract.
diff --git a/docs/book/07-cache.md b/docs/book/07-cache.md
new file mode 100644
index 0000000..ecc7ff0
--- /dev/null
+++ b/docs/book/07-cache.md
@@ -0,0 +1,87 @@
+# 07. Cache
+
+## Purpose
+Define cache schema v1.2, integrity verification, and fail-open behavior.
+
+## Public surface
+- Cache object lifecycle: `codeclone/cache.py:Cache`
+- Cache statuses: `codeclone/cache.py:CacheStatus`
+- Stat signature source: `codeclone/cache.py:file_stat_signature`
+- CLI cache integration: `codeclone/cli.py:_main_impl`
+
+## Data model
+On-disk schema (`v == "1.2"`):
+- Top-level: `v`, `payload`, `sig`
+- `payload` keys: `py`, `fp`, `files`
+- `files` map stores compact per-file entries:
+  - `st`: `[mtime_ns, size]`
+  - optional `u` (units), `b` (blocks), `s` (segments)
+- file keys are wire relpaths when `root` is configured
+
+Refs:
+- `codeclone/cache.py:Cache._parse_cache_document`
+- `codeclone/cache.py:_encode_wire_file_entry`
+- `codeclone/cache.py:_decode_wire_file_entry`
+
+## Contracts
+- Cache is optimization-only; invalid cache never blocks analysis.
+- Any cache trust failure triggers warning + empty cache fallback.
+- Cache compatibility gates:
+  - version `v == CACHE_VERSION`
+  - `payload.py == current_python_tag()`
+  - `payload.fp == BASELINE_FINGERPRINT_VERSION`
+  - `sig` equals deterministic hash of canonical payload
+
+Refs:
+- `codeclone/cache.py:Cache.load`
+- `codeclone/cache.py:Cache._ignore_cache`
+- `codeclone/cache.py:Cache._sign_data`
+
+## Invariants (MUST)
+- Cache save writes canonical JSON and atomically replaces target file.
+- Empty sections (`u`, `b`, `s`) are omitted from written wire entries.
+- Legacy secret file `.cache_secret` is never used for trust; warning only.
+
+Refs:
+- `codeclone/cache.py:Cache.save`
+- `codeclone/cache.py:_encode_wire_file_entry`
+- `codeclone/cache.py:LEGACY_CACHE_SECRET_FILENAME`
+
+## Failure modes
+| Condition | `cache_status` |
+| --- | --- |
+| File missing | `missing` |
+| Too large | `too_large` |
+| Stat/read OSError | `unreadable` |
+| JSON decode failure | `invalid_json` |
+| Type/schema failure | `invalid_type` |
+| Version mismatch | `version_mismatch` |
+| Python tag mismatch | `python_tag_mismatch` |
+| Fingerprint mismatch | `mismatch_fingerprint_version` |
+| Signature mismatch | `integrity_failed` |
+
+CLI behavior: cache failures do not change exit code; analysis continues without cache.
+
+Refs:
+- `codeclone/cache.py:CacheStatus`
+- `codeclone/cli.py:_main_impl`
+
+## Determinism / canonicalization
+- Cache signatures are computed over canonical JSON payload.
+- Wire file paths and row arrays are sorted before write.
+
+Refs:
+- `codeclone/cache.py:_canonical_json`
+- `codeclone/cache.py:_wire_filepath_from_runtime`
+- `codeclone/cache.py:_encode_wire_file_entry`
+
+## Locked by tests
+- `tests/test_cache.py::test_cache_v12_uses_relpaths_when_root_set`
+- `tests/test_cache.py::test_cache_signature_validation_ignores_json_whitespace`
+- `tests/test_cache.py::test_cache_signature_mismatch_warns`
+- `tests/test_cache.py::test_cache_too_large_warns`
+- `tests/test_cli_inprocess.py::test_cli_reports_cache_too_large_respects_max_size_flag`
+
+## Non-guarantees
+- Cache file content stability across schema bumps is not guaranteed.
+- Cache payload is tamper-evident only; it is not secret-authenticated.
diff --git a/docs/book/08-report.md b/docs/book/08-report.md
new file mode 100644
index 0000000..3625b44
--- /dev/null
+++ b/docs/book/08-report.md
@@ -0,0 +1,92 @@
+# 08. Report
+
+## Purpose
+Define report schema v1.1 and shared metadata contract across JSON/TXT/HTML.
+
+## Public surface
+- JSON serializer: `codeclone/_report_serialize.py:to_json_report`
+- TXT serializer: `codeclone/_report_serialize.py:to_text_report`
+- Shared metadata builder: `codeclone/_cli_meta.py:_build_report_meta`
+- HTML renderer: `codeclone/html_report.py:build_html_report`
+
+## Data model
+JSON v1.1 top-level fields:
+- `meta`
+- `files`
+- `groups`
+- `groups_split`
+- `group_item_layout`
+- optional `facts`
+
+`group_item_layout` is explicit positional schema for compact arrays.
+
+Refs:
+- `codeclone/_report_serialize.py:GROUP_ITEM_LAYOUT`
+- `codeclone/contracts.py:REPORT_SCHEMA_VERSION`
+
+## Contracts
+Shared `meta` contract is produced once in CLI and consumed by all formats.
+Key fields include:
+- runtime: `codeclone_version`, `python_version`, `python_tag`, `report_schema_version`
+- deterministic aggregates: `groups_counts.{functions|blocks|segments}.{total,new,known}`
+- baseline provenance: `baseline_*`, including `baseline_payload_sha256` and verification flag
+- cache provenance: `cache_path`, `cache_used`, `cache_status`, `cache_schema_version`
+- IO transparency: `files_skipped_source_io`
+
+Refs:
+- `codeclone/_cli_meta.py:ReportMeta`
+- `codeclone/_cli_meta.py:_build_report_meta`
+
+NEW/KNOWN split contract:
+- Trusted baseline (`baseline_loaded=true` and `baseline_status=ok`):
+  - `new` from `new_*_group_keys`
+  - `known` is remaining keys
+- Untrusted baseline: all groups are NEW, KNOWN is empty
+
+Refs:
+- `codeclone/_report_serialize.py:_baseline_is_trusted`
+- `codeclone/_report_serialize.py:to_json_report`
+- `codeclone/_report_serialize.py:to_text_report`
+
+## Invariants (MUST)
+- `groups_split` is key-index only; clone payload stays in `groups`.
+- `groups_split[new] ∩ groups_split[known] = ∅` per section.
+- `groups_split[new] ∪ groups_split[known] = groups.keys()` per section.
+- Facts are core-owned (`build_block_group_facts`) and renderers only display them.
+
+Refs:
+- `codeclone/_report_serialize.py:to_json_report`
+- `codeclone/_report_explain.py:build_block_group_facts`
+
+## Failure modes
+| Condition | Behavior |
+| --- | --- |
+| Missing meta fields at render time | TXT/HTML render placeholders `(none)` or empty values |
+| Untrusted baseline | JSON/TXT classify all groups as NEW; HTML shows untrusted note |
+| Missing source snippets | HTML shows safe fallback snippet |
+
+Refs:
+- `codeclone/_report_serialize.py:_format_meta_text_value`
+- `codeclone/html_report.py:build_html_report`
+- `codeclone/_html_snippets.py:_render_code_block`
+
+## Determinism / canonicalization
+- `files` list is sorted and unique by collection strategy.
+- Group keys are serialized in sorted order.
+- Items are encoded and sorted by deterministic tuple keys.
+
+Refs:
+- `codeclone/_report_serialize.py:_collect_files`
+- `codeclone/_report_serialize.py:_function_record_sort_key`
+- `codeclone/_report_serialize.py:_block_record_sort_key`
+
+## Locked by tests
+- `tests/test_report.py::test_report_json_compact_v11_contract`
+- `tests/test_report.py::test_report_json_groups_split_trusted_baseline`
+- `tests/test_report.py::test_report_json_groups_split_untrusted_baseline`
+- `tests/test_report.py::test_to_text_report_trusted_baseline_split_sections`
+- `tests/test_report.py::test_to_text_report_untrusted_baseline_known_sections_empty`
+
+## Non-guarantees
+- Optional `facts` payload may expand in v1.x without changing clone group semantics.
+- HTML visual grouping controls are not part of JSON schema contract.
diff --git a/docs/book/09-cli.md b/docs/book/09-cli.md
new file mode 100644
index 0000000..fc6d136
--- /dev/null
+++ b/docs/book/09-cli.md
@@ -0,0 +1,77 @@
+# 09. CLI
+
+## Purpose
+Define observable CLI behavior: argument handling, summaries, error UI, and output writing.
+
+## Public surface
+- CLI runner: `codeclone/cli.py:main`, `codeclone/cli.py:_main_impl`
+- Parser: `codeclone/_cli_args.py:build_parser`
+- Summary renderer: `codeclone/_cli_summary.py:_print_summary`
+- Path validation: `codeclone/_cli_paths.py:_validate_output_path`
+- Message catalog: `codeclone/ui_messages.py`
+
+## Data model
+CLI modes:
+- Normal mode
+- Gating mode (`--ci`, `--fail-on-new`, `--fail-threshold>=0`)
+- Update mode (`--update-baseline`)
+
+Summary metrics:
+- files found/analyzed/cache hits/skipped
+- function/block/segment groups
+- suppressed segment groups
+- new vs baseline
+
+Refs:
+- `codeclone/_cli_summary.py:_build_summary_rows`
+
+## Contracts
+- Help output includes canonical exit-code section and project links.
+- Contract errors are prefixed by `CONTRACT ERROR:`.
+- Gating failures are prefixed by `GATING FAILURE:`.
+- Internal errors use `fmt_internal_error` with optional debug details.
+
+Refs:
+- `codeclone/contracts.py:cli_help_epilog`
+- `codeclone/ui_messages.py:fmt_contract_error`
+- `codeclone/ui_messages.py:fmt_internal_error`
+
+## Invariants (MUST)
+- Report writes (`--html/--json/--text`) are path-validated and write failures are contract errors.
+- Baseline update write failure is contract error.
+- In gating mode, unreadable source files are contract errors with higher priority than clone gating failure.
+
+Refs:
+- `codeclone/cli.py:_write_report_output`
+- `codeclone/cli.py:_main_impl`
+
+## Failure modes
+| Condition | User-facing category | Exit |
+| --- | --- | --- |
+| Invalid CLI flag | contract | 2 |
+| Invalid output extension/path | contract | 2 |
+| Baseline untrusted in CI/gating | contract | 2 |
+| Unreadable source in CI/gating | contract | 2 |
+| New clones with `--fail-on-new` | gating | 3 |
+| Threshold exceeded | gating | 3 |
+| Unexpected exception | internal | 5 |
+
+## Determinism / canonicalization
+- Summary metric ordering is fixed.
+- Compact summary mode (`--quiet`) is fixed-format text.
+- Help epilog is generated from static constants.
+
+Refs:
+- `codeclone/_cli_summary.py:_build_summary_rows`
+- `codeclone/contracts.py:EXIT_CODE_DESCRIPTIONS`
+
+## Locked by tests
+- `tests/test_cli_unit.py::test_cli_help_text_consistency`
+- `tests/test_cli_unit.py::test_argument_parser_contract_error_marker_for_invalid_args`
+- `tests/test_cli_inprocess.py::test_cli_summary_format_stable`
+- `tests/test_cli_inprocess.py::test_cli_unreadable_source_fails_in_ci_with_contract_error`
+- `tests/test_cli_inprocess.py::test_cli_contract_error_priority_over_gating_failure_for_unreadable_source`
+
+## Non-guarantees
+- Rich styling details are not part of machine-facing CLI contract.
+- Warning phrasing may evolve if category markers and exit semantics stay stable.
diff --git a/docs/book/10-html-render.md b/docs/book/10-html-render.md
new file mode 100644
index 0000000..8c58386
--- /dev/null
+++ b/docs/book/10-html-render.md
@@ -0,0 +1,73 @@
+# 10. HTML Render
+
+## Purpose
+Document HTML rendering as a pure view layer over report data/facts.
+
+## Public surface
+- Main renderer: `codeclone/html_report.py:build_html_report`
+- Escaping helpers: `codeclone/_html_escape.py`
+- Snippet/highlight helpers: `codeclone/_html_snippets.py`
+- Static template: `codeclone/templates.py:REPORT_TEMPLATE`
+
+## Data model
+Inputs to renderer:
+- grouped clone data (`func_groups`, `block_groups`, `segment_groups`)
+- block explainability facts (`block_group_facts`)
+- novelty key sets (`new_function_group_keys`, `new_block_group_keys`)
+- shared report metadata (`report_meta`)
+
+Output:
+- single self-contained HTML string
+
+Refs:
+- `codeclone/html_report.py:build_html_report`
+
+## Contracts
+- HTML must not recompute detection semantics; it renders facts from core/report layers.
+- Explainability hints shown in UI are sourced from `build_block_group_facts` data.
+- Provenance panel mirrors report metadata contract.
+
+Refs:
+- `codeclone/_report_explain.py:build_block_group_facts`
+- `codeclone/html_report.py:_render_group_explanation`
+- `codeclone/html_report.py:report_meta_html`
+
+## Invariants (MUST)
+- All user/content fields are escaped for text/attributes before insertion.
+- Missing file snippets render explicit fallback blocks.
+- Novelty controls reflect baseline trust split note and per-group novelty flags.
+
+Refs:
+- `codeclone/_html_escape.py:_escape_attr`
+- `codeclone/_html_snippets.py:_render_code_block`
+- `codeclone/html_report.py:global_novelty_html`
+
+## Failure modes
+| Condition | Behavior |
+| --- | --- |
+| Source file unreadable for snippet | Render fallback snippet with message |
+| Missing/invalid optional meta field | Render empty or `(none)`-equivalent display |
+| Pygments unavailable | Escape-only fallback code rendering |
+
+Refs:
+- `codeclone/_html_snippets.py:_FileCache.get_lines_range`
+- `codeclone/_html_snippets.py:_try_pygments`
+
+## Determinism / canonicalization
+- Section/group ordering follows sorted report inputs.
+- Metadata rows are built in fixed order.
+
+Refs:
+- `codeclone/html_report.py:build_html_report`
+- `codeclone/html_report.py:meta_rows`
+
+## Locked by tests
+- `tests/test_html_report.py::test_html_report_uses_core_block_group_facts`
+- `tests/test_html_report.py::test_html_report_escapes_meta_and_title`
+- `tests/test_html_report.py::test_html_report_escapes_script_breakout_payload`
+- `tests/test_html_report.py::test_html_report_missing_source_snippet_fallback`
+- `tests/test_html_report.py::test_html_and_json_group_order_consistent`
+
+## Non-guarantees
+- CSS/visual system and interaction details may evolve without schema bump.
+- HTML command palette action set is not a baseline/cache/report contract.
diff --git a/docs/book/11-security-model.md b/docs/book/11-security-model.md
new file mode 100644
index 0000000..56aadcc
--- /dev/null
+++ b/docs/book/11-security-model.md
@@ -0,0 +1,67 @@
+# 11. Security Model
+
+## Purpose
+Describe implemented protections and explicit security boundaries.
+
+## Public surface
+- Scanner path validation: `codeclone/scanner.py:iter_py_files`
+- File read limits and parser limits: `codeclone/cli.py:process_file`, `codeclone/extractor.py:_parse_limits`
+- Baseline/cache validation: `codeclone/baseline.py`, `codeclone/cache.py`
+- HTML escaping: `codeclone/_html_escape.py`, `codeclone/html_report.py`
+
+## Data model
+Security-relevant input classes:
+- filesystem paths (root/source/baseline/cache/report)
+- untrusted JSON files (baseline/cache)
+- untrusted source snippets and metadata rendered into HTML
+
+## Contracts
+- CodeClone parses source text; it does not execute repository Python code.
+- Sensitive root directories are blocked by scanner policy.
+- Symlink traversal outside root is skipped.
+- HTML report escapes text and attribute contexts before embedding.
+
+Refs:
+- `codeclone/extractor.py:_parse_with_limits`
+- `codeclone/scanner.py:SENSITIVE_DIRS`
+- `codeclone/scanner.py:iter_py_files`
+- `codeclone/_html_escape.py:_escape_html`
+
+## Invariants (MUST)
+- Baseline and cache integrity checks use constant-time comparison.
+- Size guards are enforced before parsing baseline/cache JSON.
+- Cache failures degrade safely (warning + ignore), baseline trust failures follow trust model.
+
+Refs:
+- `codeclone/baseline.py:Baseline.verify_integrity`
+- `codeclone/cache.py:Cache.load`
+- `codeclone/cli.py:_main_impl`
+
+## Failure modes
+| Condition | Security behavior |
+| --- | --- |
+| Symlink points outside root | File skipped |
+| Root under sensitive dirs | Validation error |
+| Oversized baseline | Baseline rejected |
+| Oversized cache | Cache ignored |
+| HTML-injected payload in metadata/source | Escaped output |
+
+## Determinism / canonicalization
+- Canonical JSON hashing for baseline/cache prevents formatting-only drift.
+- Security failures map to explicit statuses (baseline/cache enums).
+
+Refs:
+- `codeclone/baseline.py:_compute_payload_sha256`
+- `codeclone/cache.py:_canonical_json`
+- `codeclone/baseline.py:BaselineStatus`
+- `codeclone/cache.py:CacheStatus`
+
+## Locked by tests
+- `tests/test_security.py::test_scanner_path_traversal`
+- `tests/test_scanner_extra.py::test_iter_py_files_symlink_loop_does_not_traverse`
+- `tests/test_security.py::test_html_report_escapes_user_content`
+- `tests/test_html_report.py::test_html_report_escapes_script_breakout_payload`
+- `tests/test_cache.py::test_cache_too_large_warns`
+
+## Non-guarantees
+- Baseline/cache integrity is tamper-evident at file-content level; it is not cryptographic attestation against a privileged attacker.
diff --git a/docs/book/12-determinism.md b/docs/book/12-determinism.md
new file mode 100644
index 0000000..9a43aa8
--- /dev/null
+++ b/docs/book/12-determinism.md
@@ -0,0 +1,67 @@
+# 12. Determinism
+
+## Purpose
+Document deterministic behavior and canonicalization controls.
+
+## Public surface
+- Sorting and traversal: `codeclone/scanner.py`, `codeclone/_report_serialize.py`, `codeclone/cache.py`
+- Canonical hashing: `codeclone/baseline.py`, `codeclone/cache.py`
+- Golden detector snapshot policy: `tests/test_detector_golden.py`
+
+## Data model
+Deterministic outputs depend on:
+- fixed Python tag
+- fixed baseline/cache/report schemas
+- sorted file traversal
+- sorted group keys and item records
+- canonical JSON serialization for hashes
+
+## Contracts
+- JSON report uses deterministic ordering for files/groups/items.
+- TXT report uses deterministic metadata key order and group/item ordering.
+- Baseline hash is canonical and independent from non-payload metadata fields.
+- Cache signature is canonical and independent from JSON whitespace.
+
+Refs:
+- `codeclone/_report_serialize.py:to_json_report`
+- `codeclone/_report_serialize.py:to_text_report`
+- `codeclone/baseline.py:_compute_payload_sha256`
+- `codeclone/cache.py:_sign_data`
+
+## Invariants (MUST)
+- `files` list is lexicographically sorted.
+- `groups_split` key lists are lexicographically sorted.
+- Baseline clone lists are sorted and unique.
+- Golden detector test runs only on canonical Python tag from fixture metadata.
+
+Refs:
+- `codeclone/_report_serialize.py:_collect_files`
+- `codeclone/baseline.py:_require_sorted_unique_ids`
+- `tests/test_detector_golden.py::test_detector_output_matches_golden_fixture`
+
+## Failure modes
+| Condition | Determinism impact |
+| --- | --- |
+| Different Python tag | Clone IDs may differ; baseline considered incompatible |
+| Unsorted/non-canonical baseline IDs | Baseline rejected as invalid |
+| Cache signature mismatch | Cache ignored and recomputed |
+
+## Determinism / canonicalization
+Primary canonicalization points:
+- `json.dumps(..., sort_keys=True, separators=(",", ":"), ensure_ascii=False)` for baseline/cache payload hash/signature.
+- tuple-based sort keys for report record arrays.
+
+Refs:
+- `codeclone/baseline.py:_compute_payload_sha256`
+- `codeclone/cache.py:_canonical_json`
+- `codeclone/_report_serialize.py:_function_record_sort_key`
+
+## Locked by tests
+- `tests/test_report.py::test_report_json_deterministic_group_order`
+- `tests/test_report.py::test_report_json_deterministic_with_shuffled_units`
+- `tests/test_report.py::test_text_report_deterministic_group_order`
+- `tests/test_baseline.py::test_baseline_hash_canonical_determinism`
+- `tests/test_cache.py::test_cache_signature_validation_ignores_json_whitespace`
+
+## Non-guarantees
+- Determinism is not guaranteed across different `python_tag` values.
diff --git a/docs/book/13-testing-as-spec.md b/docs/book/13-testing-as-spec.md
new file mode 100644
index 0000000..60e5ec3
--- /dev/null
+++ b/docs/book/13-testing-as-spec.md
@@ -0,0 +1,62 @@
+# 13. Testing as Specification
+
+## Purpose
+Map critical contracts to tests that lock behavior.
+
+## Public surface
+Contract tests are concentrated in:
+- `tests/test_baseline.py`
+- `tests/test_cache.py`
+- `tests/test_report.py`
+- `tests/test_cli_inprocess.py`
+- `tests/test_cli_unit.py`
+- `tests/test_html_report.py`
+
+## Data model
+Test classes by role:
+- Unit contract tests (schema, validation, canonicalization)
+- Integration contract tests (CLI mode behavior, exit-code priority)
+- Golden detector snapshot (single canonical python tag)
+
+## Contracts
+The following matrix is treated as executable contract:
+
+| Contract | Tests |
+| --- | --- |
+| Baseline schema/integrity/compat gates | `tests/test_baseline.py` |
+| Cache fail-open + status mapping | `tests/test_cache.py`, `tests/test_cli_inprocess.py::test_cli_reports_cache_too_large_respects_max_size_flag` |
+| Exit code categories and markers | `tests/test_cli_unit.py`, `tests/test_cli_inprocess.py` |
+| Report schema v1.1 JSON/TXT split + layout | `tests/test_report.py` |
+| HTML render-only explainability + escaping | `tests/test_html_report.py` |
+| Scanner traversal safety | `tests/test_scanner_extra.py`, `tests/test_security.py` |
+
+## Invariants (MUST)
+- Every schema/status contract change requires tests and docs update.
+- Golden detector fixture is canonicalized to one Python tag.
+- Untrusted baseline behavior must be tested for both normal and gating modes.
+
+Refs:
+- `tests/test_detector_golden.py::test_detector_output_matches_golden_fixture`
+- `tests/test_cli_inprocess.py::test_cli_legacy_baseline_normal_mode_ignored_and_exit_zero`
+- `tests/test_cli_inprocess.py::test_cli_legacy_baseline_fail_on_new_fails_fast_exit_2`
+
+## Failure modes
+| Condition | Expected test signal |
+| --- | --- |
+| Baseline payload contract drift | baseline integrity/canonical tests fail |
+| Cache schema drift | cache version/parse tests fail |
+| Report schema drift | compact v1.1 layout tests fail |
+| Exit priority drift | CI inprocess tests fail |
+
+## Determinism / canonicalization
+- Determinism tests compare ordering and stable payloads, not runtime-specific timestamps.
+
+## Locked by tests
+- `tests/test_baseline.py::test_baseline_payload_fields_contract_invariant`
+- `tests/test_cache.py::test_cache_v12_missing_optional_sections_default_empty`
+- `tests/test_report.py::test_report_json_compact_v11_contract`
+- `tests/test_cli_inprocess.py::test_cli_contract_error_priority_over_gating_failure_for_unreadable_source`
+- `tests/test_html_report.py::test_html_and_json_group_order_consistent`
+
+## Non-guarantees
+- Test implementation details (fixtures/helper names) can change if contract assertions remain equivalent.
diff --git a/docs/book/14-compatibility-and-versioning.md b/docs/book/14-compatibility-and-versioning.md
new file mode 100644
index 0000000..0dc94fb
--- /dev/null
+++ b/docs/book/14-compatibility-and-versioning.md
@@ -0,0 +1,74 @@
+# 14. Compatibility and Versioning
+
+## Purpose
+Define when to bump baseline/cache/report/fingerprint versions and what breaks.
+
+## Public surface
+- Version constants: `codeclone/contracts.py`
+- Baseline compatibility checks: `codeclone/baseline.py:Baseline.verify_compatibility`
+- Cache compatibility checks: `codeclone/cache.py:Cache._parse_cache_document`
+- Report schema assignment: `codeclone/_report_serialize.py:to_json_report`
+
+## Data model
+Current contract versions:
+- `BASELINE_SCHEMA_VERSION = "1.0"`
+- `BASELINE_FINGERPRINT_VERSION = "1"`
+- `CACHE_VERSION = "1.2"`
+- `REPORT_SCHEMA_VERSION = "1.1"`
+
+Refs:
+- `codeclone/contracts.py`
+
+## Contracts
+Version bump rules:
+- Bump **baseline schema** only for baseline JSON layout/type changes.
+- Bump **fingerprint version** when detection semantics affecting function/block keys change.
+- Bump **cache schema** for cache wire format changes.
+- Bump **report schema** for JSON/TXT/HTML data contract changes.
+
+Baseline regeneration rules:
+- Required when `fingerprint_version` changes.
+- Required when `python_tag` changes.
+- Not required for package patch/minor changes alone if compatibility gates still pass.
+
+Refs:
+- `codeclone/baseline.py:Baseline.from_groups`
+- `codeclone/cli.py:_main_impl`
+
+## Invariants (MUST)
+- Contract changes must include tests and changelog/docs updates.
+- Schema mismatch must map to explicit statuses (not generic fallback).
+- Legacy baseline layout is untrusted and requires explicit regeneration.
+
+Refs:
+- `codeclone/baseline.py:BaselineStatus`
+- `codeclone/baseline.py:_is_legacy_baseline_payload`
+
+## Failure modes
+| Change type | User impact |
+| --- | --- |
+| Baseline schema bump | old baselines become untrusted until regenerated |
+| Fingerprint bump | baseline diff keys change; regeneration required |
+| Cache schema bump | old caches ignored and regenerated automatically |
+| Report schema bump | downstream JSON/TXT consumers must update |
+
+## Determinism / canonicalization
+- Version constants are explicit and imported where enforced.
+- Compatibility is code-driven, not documentation-driven.
+
+Refs:
+- `codeclone/contracts.py`
+- `codeclone/baseline.py:Baseline.verify_compatibility`
+
+## Locked by tests
+- `tests/test_baseline.py::test_baseline_verify_schema_too_new`
+- `tests/test_baseline.py::test_baseline_verify_fingerprint_mismatch`
+- `tests/test_cache.py::test_cache_v_field_version_mismatch_warns`
+- `tests/test_report.py::test_report_json_compact_v11_contract`
+
+## Non-guarantees
+- Backward compatibility is not promised across incompatible schema/fingerprint bumps.
+
+## 1.5 architecture note
+Planned for v1.5: architecture-layer review and module organization cleanup.
+No planned change to clone-detection semantics or determinism contracts unless accompanied by explicit fingerprint/schema version bumps and tests.
diff --git a/docs/book/README.md b/docs/book/README.md
new file mode 100644
index 0000000..cb52a7b
--- /dev/null
+++ b/docs/book/README.md
@@ -0,0 +1,45 @@
+# CodeClone Contracts Book
+
+This book is the contract-level documentation for CodeClone v1.x.
+
+All guarantees here are derived from code and locked tests.
+If a statement is not enforced by code/tests, it is explicitly marked as non-contractual.
+
+## How to read
+
+- Start with **Intro → Architecture map → Terminology**.
+- Then read the **contract spine**: Exit codes → Core pipeline → Baseline → Cache → Report.
+- Everything else is supporting detail, invariants, and reference.
+
+## Table of Contents
+
+- [00-intro.md](00-intro.md)
+- [01-architecture-map.md](01-architecture-map.md)
+- [02-terminology.md](02-terminology.md)
+
+### Contracts spine
+
+- [03-contracts-exit-codes.md](03-contracts-exit-codes.md)
+- [04-config-and-defaults.md](04-config-and-defaults.md)
+- [05-core-pipeline.md](05-core-pipeline.md)
+- [06-baseline.md](06-baseline.md)
+- [07-cache.md](07-cache.md)
+- [08-report.md](08-report.md)
+
+### Interfaces
+
+- [09-cli.md](09-cli.md)
+- [10-html-render.md](10-html-render.md)
+
+### System properties
+
+- [11-security-model.md](11-security-model.md)
+- [12-determinism.md](12-determinism.md)
+- [13-testing-as-spec.md](13-testing-as-spec.md)
+- [14-compatibility-and-versioning.md](14-compatibility-and-versioning.md)
+
+### Appendix
+
+- [appendix/a-status-enums.md](appendix/a-status-enums.md)
+- [appendix/b-schema-layouts.md](appendix/b-schema-layouts.md)
+- [appendix/c-error-catalog.md](appendix/c-error-catalog.md)
\ No newline at end of file
diff --git a/docs/book/appendix/a-status-enums.md b/docs/book/appendix/a-status-enums.md
new file mode 100644
index 0000000..ffbbe04
--- /dev/null
+++ b/docs/book/appendix/a-status-enums.md
@@ -0,0 +1,61 @@
+# Appendix A. Status Enums
+
+## Purpose
+Centralize machine-readable status value sets used across baseline/cache/report contracts.
+
+## Public surface
+- Baseline statuses: `codeclone/baseline.py:BaselineStatus`
+- Cache statuses: `codeclone/cache.py:CacheStatus`
+- Exit categories: `codeclone/contracts.py:ExitCode`
+
+## Data model
+### BaselineStatus
+- `ok`
+- `missing`
+- `too_large`
+- `invalid_json`
+- `invalid_type`
+- `missing_fields`
+- `mismatch_schema_version`
+- `mismatch_fingerprint_version`
+- `mismatch_python_version`
+- `generator_mismatch`
+- `integrity_missing`
+- `integrity_failed`
+
+### Baseline untrusted set
+Defined by `BASELINE_UNTRUSTED_STATUSES`.
+
+### CacheStatus
+- `ok`
+- `missing`
+- `too_large`
+- `unreadable`
+- `invalid_json`
+- `invalid_type`
+- `version_mismatch`
+- `python_tag_mismatch`
+- `mismatch_fingerprint_version`
+- `integrity_failed`
+
+### ExitCode
+- `0` success
+- `2` contract error
+- `3` gating failure
+- `5` internal error
+
+## Contracts
+- Status values are serialized into report metadata (`baseline_status`, `cache_status`).
+- CLI branches by enum values, not UI text.
+
+Refs:
+- `codeclone/_cli_meta.py:ReportMeta`
+- `codeclone/cli.py:_main_impl`
+
+## Locked by tests
+- `tests/test_baseline.py::test_coerce_baseline_status`
+- `tests/test_cache.py::test_cache_version_mismatch_warns`
+- `tests/test_cli_unit.py::test_cli_help_text_consistency`
+
+## Non-guarantees
+- Human-readable status messages can change while enum values stay stable.
diff --git a/docs/book/appendix/b-schema-layouts.md b/docs/book/appendix/b-schema-layouts.md
new file mode 100644
index 0000000..edff423
--- /dev/null
+++ b/docs/book/appendix/b-schema-layouts.md
@@ -0,0 +1,99 @@
+# Appendix B. Schema Layouts
+
+## Purpose
+Provide concise structural layouts for baseline/cache/report contracts.
+
+## Baseline schema (v1.0)
+```json
+{
+  "meta": {
+    "generator": {"name": "codeclone", "version": "1.4.0"},
+    "schema_version": "1.0",
+    "fingerprint_version": "1",
+    "python_tag": "cp313",
+    "created_at": "2026-02-11T12:00:00Z",
+    "payload_sha256": "..."
+  },
+  "clones": {
+    "functions": ["..."],
+    "blocks": ["..."]
+  }
+}
+```
+Refs:
+- `codeclone/baseline.py:_baseline_payload`
+
+## Cache schema (v1.2)
+```json
+{
+  "v": "1.2",
+  "payload": {
+    "py": "cp313",
+    "fp": "1",
+    "files": {
+      "rel/path.py": {
+        "st": [1730000000000000000, 2048],
+        "u": [["mod:f", 1, 10, 10, 3, "fp", "0-19"]],
+        "b": [["mod:f", 3, 6, 4, "h1|h2|h3|h4"]],
+        "s": [["mod:f", 3, 8, 6, "segment_hash", "segment_sig"]]
+      }
+    }
+  },
+  "sig": "..."
+}
+```
+Refs:
+- `codeclone/cache.py:Cache.save`
+- `codeclone/cache.py:_encode_wire_file_entry`
+
+## Report schema (v1.1)
+```json
+{
+  "meta": {
+    "report_schema_version": "1.1",
+    "codeclone_version": "1.4.0",
+    "python_version": "3.13",
+    "python_tag": "cp313",
+    "baseline_status": "ok",
+    "cache_status": "ok",
+    "groups_counts": {
+      "functions": {"total": 1, "new": 0, "known": 1},
+      "blocks": {"total": 7, "new": 0, "known": 7},
+      "segments": {"total": 0, "new": 0, "known": 0}
+    }
+  },
+  "files": ["/abs/path.py"],
+  "groups": {
+    "functions": {"group_key": [[0, "mod:f", 1, 20, 20, 6, "fp", "20-49"]]},
+    "blocks": {"group_key": [[0, "mod:f", 5, 8, 4]]},
+    "segments": {"group_key": [[0, "mod:f", 5, 10, 6, "h", "s"]]}
+  },
+  "groups_split": {
+    "functions": {"new": ["..."], "known": ["..."]},
+    "blocks": {"new": ["..."], "known": ["..."]},
+    "segments": {"new": ["..."], "known": []}
+  },
+  "group_item_layout": {
+    "functions": ["file_i", "qualname", "start", "end", "loc", "stmt_count", "fingerprint", "loc_bucket"],
+    "blocks": ["file_i", "qualname", "start", "end", "size"],
+    "segments": ["file_i", "qualname", "start", "end", "size", "segment_hash", "segment_sig"]
+  }
+}
+```
+Refs:
+- `codeclone/_report_serialize.py:to_json_report`
+- `codeclone/_report_serialize.py:GROUP_ITEM_LAYOUT`
+
+## TXT report sections
+```text
+REPORT METADATA
+...
+FUNCTION CLONES (NEW)
+FUNCTION CLONES (KNOWN)
+BLOCK CLONES (NEW)
+BLOCK CLONES (KNOWN)
+SEGMENT CLONES (NEW)
+SEGMENT CLONES (KNOWN)
+```
+Refs:
+- `codeclone/_report_serialize.py:to_text_report`
diff --git a/docs/book/appendix/c-error-catalog.md b/docs/book/appendix/c-error-catalog.md
new file mode 100644
index 0000000..77f5c95
--- /dev/null
+++ b/docs/book/appendix/c-error-catalog.md
@@ -0,0 +1,66 @@
+# Appendix C. Error Catalog
+
+## Purpose
+Map core error conditions to statuses, markers, and exits.
+
+## Contract/gating/internal categories
+| Category | Marker | Exit |
+| --- | --- | --- |
+| Contract error | `CONTRACT ERROR:` | 2 |
+| Gating failure | `GATING FAILURE:` | 3 |
+| Internal error | `INTERNAL ERROR:` | 5 |
+
+Refs:
+- `codeclone/ui_messages.py:MARKER_CONTRACT_ERROR`
+- `codeclone/contracts.py:ExitCode`
+
+## Baseline contract errors
+| Condition | Baseline status | CLI behavior |
+| --- | --- | --- |
+| Missing baseline | `missing` | normal: empty diff; gating: exit 2 |
+| Schema mismatch | `mismatch_schema_version` | normal: ignore baseline; gating: exit 2 |
+| Fingerprint mismatch | `mismatch_fingerprint_version` | normal: ignore baseline; gating: exit 2 |
+| Python tag mismatch | `mismatch_python_version` | normal: ignore baseline; gating: exit 2 |
+| Integrity mismatch | `integrity_failed` | normal: ignore baseline; gating: exit 2 |
+
+Refs:
+- `codeclone/cli.py:_main_impl`
+- `codeclone/baseline.py:BaselineStatus`
+
+## Cache degradation cases
+| Condition | Cache status | Behavior |
+| --- | --- | --- |
+| Missing cache file | `missing` | proceed without cache |
+| Version mismatch | `version_mismatch` | ignore cache + warning |
+| Invalid JSON/type | `invalid_json` / `invalid_type` | ignore cache + warning |
+| Signature mismatch | `integrity_failed` | ignore cache + warning |
+| Oversized cache | `too_large` | ignore cache + warning |
+
+Refs:
+- `codeclone/cache.py:CacheStatus`
+- `codeclone/cache.py:Cache._ignore_cache`
+
+## Source IO and gating
+| Condition | Behavior |
+| --- | --- |
+| Source read/decode failure in normal mode | file skipped; warning; continue |
+| Source read/decode failure in gating mode | contract error exit 2 |
+
+Refs:
+- `codeclone/cli.py:process_file`
+- `codeclone/cli.py:_main_impl`
+
+## Report write errors
+| Condition | Behavior |
+| --- | --- |
+| Baseline write OSError | contract error exit 2 |
+| HTML/JSON/TXT write OSError | contract error exit 2 |
+
+Refs:
+- `codeclone/cli.py:_main_impl`
+
+## Locked by tests
+- `tests/test_cli_inprocess.py::test_cli_report_write_error_is_contract_error`
+- `tests/test_cli_inprocess.py::test_cli_update_baseline_write_error_is_contract_error`
+- `tests/test_cli_inprocess.py::test_cli_unreadable_source_fails_in_ci_with_contract_error`
+- `tests/test_cli_unit.py::test_cli_internal_error_marker`
diff --git a/docs/cfg.md b/docs/cfg.md
index 21589da..7ed2a6b 100644
--- a/docs/cfg.md
+++ b/docs/cfg.md
@@ -1,5 +1,8 @@
 # Control Flow Graph (CFG) — Design and Semantics
 
+> Scope note: this file is a CFG deep-dive.  
+> Contract-level guarantees are documented in `docs/book/` (especially `05-core-pipeline.md` and `12-determinism.md`).
+
 This document describes the **Control Flow Graph (CFG)** model used by **CodeClone**,
 its design goals, semantics, and known limitations.
 
@@ -180,15 +183,15 @@ CFG v1 guarantees:
 
 This is critical for CI usage and baseline comparison.
 
-## Python Version Consistency for Baseline Checks
+## Python Tag Consistency for Baseline Checks
 
-Due to inherent differences in Python’s AST between interpreter versions, baseline
-generation and verification must be performed using the same Python version.
+Due to AST differences between interpreter versions, baseline compatibility is pinned to
+the same `python_tag` (for example `cp313`), not full patch version equality.
 
-This ensures deterministic and reproducible clone detection results.
+This keeps clone detection deterministic while allowing patch updates within the same tag.
 
-CI checks therefore pin baseline verification to a single Python version, while the
-test matrix continues to validate compatibility across Python 3.10–3.14.
+CI gating uses the baseline tag policy, while the test matrix validates runtime
+compatibility across Python 3.10-3.14.
 
 ---
 
diff --git a/pyproject.toml b/pyproject.toml
index 4de9503..33378ad 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "codeclone"
-version = "1.3.0"
+version = "1.4.0"
 description = "AST and CFG-based code clone detector for Python focused on architectural duplication"
 readme = { file = "README.md", content-type = "text/markdown" }
 license = { text = "MIT" }
diff --git a/tests/_report_fixtures.py b/tests/_report_fixtures.py
new file mode 100644
index 0000000..73e68e4
--- /dev/null
+++ b/tests/_report_fixtures.py
@@ -0,0 +1,22 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+REPEATED_STMT_HASH = "0e8579f84e518d186950d012c9944a40cb872332"
+
+REPEATED_ASSERT_SOURCE = (
+    "def f(html):\n"
+    "    assert 'a' in html\n"
+    "    assert 'b' in html\n"
+    "    assert 'c' in html\n"
+    "    assert 'd' in html\n"
+)
+
+
+def repeated_block_group_key(*, block_size: int = 4) -> str:
+    return "|".join([REPEATED_STMT_HASH] * block_size)
+
+
+def write_repeated_assert_source(path: Path) -> Path:
+    path.write_text(REPEATED_ASSERT_SOURCE, "utf-8")
+    return path
diff --git a/tests/conftest.py b/tests/conftest.py
new file mode 100644
index 0000000..91528d3
--- /dev/null
+++ b/tests/conftest.py
@@ -0,0 +1,39 @@
+from __future__ import annotations
+
+from collections.abc import Callable
+
+import pytest
+
+from codeclone.contracts import REPORT_SCHEMA_VERSION
+
+ReportMetaFactory = Callable[..., dict[str, object]]
+
+
+@pytest.fixture
+def report_meta_factory() -> ReportMetaFactory:
+    def _make(**overrides: object) -> dict[str, object]:
+        meta: dict[str, object] = {
+            "report_schema_version": REPORT_SCHEMA_VERSION,
+            "codeclone_version": "1.4.0",
+            "python_version": "3.13",
+            "python_tag": "cp313",
+            "baseline_path": "/repo/codeclone.baseline.json",
+            "baseline_fingerprint_version": "1",
+            "baseline_schema_version": "1.0",
+            "baseline_python_tag": "cp313",
+            "baseline_generator_name": "codeclone",
+            "baseline_generator_version": "1.4.0",
+            "baseline_payload_sha256": "a" * 64,
+            "baseline_payload_sha256_verified": True,
+            "baseline_loaded": True,
+            "baseline_status": "ok",
+            "cache_path": "/repo/.cache/codeclone/cache.json",
+            "cache_schema_version": "1.2",
+            "cache_status": "ok",
+            "cache_used": True,
+            "files_skipped_source_io": 0,
+        }
+        meta.update(overrides)
+        return meta
+
+    return _make
diff --git a/tests/fixtures/golden_project/alpha.py b/tests/fixtures/golden_project/alpha.py
new file mode 100644
index 0000000..3f8c993
--- /dev/null
+++ b/tests/fixtures/golden_project/alpha.py
@@ -0,0 +1,43 @@
+def transform_alpha(items: list[int]) -> tuple[list[int], int]:
+    if not items:
+        return [], 0
+
+    prepared: list[int] = []
+    total = 0
+    count = 0
+
+    for item in items:
+        doubled = item * 2
+        if doubled % 3 == 0:
+            prepared.append(doubled)
+        else:
+            prepared.append(doubled + 1)
+        total += prepared[-1]
+        count += 1
+
+    average = total // count if count else 0
+    marker = len(prepared)
+    audit = marker + average
+    checksum = audit + total
+    signature = checksum - marker
+    offset = signature + 1
+    window = offset + 2
+    anchor = window + 3
+    tail = anchor + 4
+    extra = tail + 5
+    checksum2 = extra + 6
+    checksum3 = checksum2 + 7
+    checksum4 = checksum3 + 8
+    checksum5 = checksum4 + 9
+    checksum6 = checksum5 + 10
+    checksum7 = checksum6 + 11
+    checksum8 = checksum7 + 12
+    checksum9 = checksum8 + 13
+    checksum10 = checksum9 + 14
+    checksum11 = checksum10 + 15
+    checksum12 = checksum11 + 16
+    checksum13 = checksum12 + 17
+    checksum14 = checksum13 + 18
+    checksum15 = checksum14 + 19
+
+    return prepared, checksum15
diff --git a/tests/fixtures/golden_project/beta.py b/tests/fixtures/golden_project/beta.py
new file mode 100644
index 0000000..493630e
--- /dev/null
+++ b/tests/fixtures/golden_project/beta.py
@@ -0,0 +1,43 @@
+def transform_beta(items: list[int]) -> tuple[list[int], int]:
+    if not items:
+        return [], 0
+
+    prepared: list[int] = []
+    total = 0
+    count = 0
+
+    for item in items:
+        doubled = item * 2
+        if doubled % 3 == 0:
+            prepared.append(doubled)
+        else:
+            prepared.append(doubled + 1)
+        total += prepared[-1]
+        count += 1
+
+    average = total // count if count else 0
+    marker = len(prepared)
+    audit = marker + average
+    checksum = audit + total
+    signature = checksum - marker
+    offset = signature + 1
+    window = offset + 2
+    anchor = window + 3
+    tail = anchor + 4
+    extra = tail + 5
+    checksum2 = extra + 6
+    checksum3 = checksum2 + 7
+    checksum4 = checksum3 + 8
+    checksum5 = checksum4 + 9
+    checksum6 = checksum5 + 10
+    checksum7 = checksum6 + 11
+    checksum8 = checksum7 + 12
+    checksum9 = checksum8 + 13
+    checksum10 = checksum9 + 14
+    checksum11 = checksum10 + 15
+    checksum12 = checksum11 + 16
+    checksum13 = checksum12 + 17
+    checksum14 = checksum13 + 18
+    checksum15 = checksum14 + 19
+
+    return prepared, checksum15
diff --git a/tests/fixtures/golden_project/golden_expected_ids.json b/tests/fixtures/golden_project/golden_expected_ids.json
new file mode 100644
index 0000000..a7bbbd1
--- /dev/null
+++ b/tests/fixtures/golden_project/golden_expected_ids.json
@@ -0,0 +1,17 @@
+{
+  "meta": {
+    "python_tag": "cp313"
+  },
+  "function_group_keys": [
+    "efc8465229b381a3a50502d59d9539c0be3efe86|20-49"
+  ],
+  "block_group_keys": [
+    "3c1b5cf24b4dfcd8e5736b735bfd3850940100d5|3c1b5cf24b4dfcd8e5736b735bfd3850940100d5|3c1b5cf24b4dfcd8e5736b735bfd3850940100d5|3c1b5cf24b4dfcd8e5736b735bfd3850940100d5",
+    "3c1b5cf24b4dfcd8e5736b735bfd3850940100d5|3c1b5cf24b4dfcd8e5736b735bfd3850940100d5|3c1b5cf24b4dfcd8e5736b735bfd3850940100d5|cb4fcbc1b2a65ec1346898fc0d660335e25d7cbc",
+    "8579659a9e8c9755a6d2f0b1d82dda8866fd243b|1912d2ee3c541cbf9e51f485348586afe1a00755|ee69aff0b7ea38927e5082ceef14115c805f6734|ee69aff0b7ea38927e5082ceef14115c805f6734",
+    "b4b5893be87edf98955f047cbf25ca755dc753b4|8579659a9e8c9755a6d2f0b1d82dda8866fd243b|1912d2ee3c541cbf9e51f485348586afe1a00755|ee69aff0b7ea38927e5082ceef14115c805f6734",
+    "b6ee70d0bd6ff4b593f127a137aed9ab41179145|cacc33d58f323481f65fed57873d1c840531859e|d60c0005a4c850c140378d1c82b81dde93a7ccab|d60c0005a4c850c140378d1c82b81dde93a7ccab",
+    "cacc33d58f323481f65fed57873d1c840531859e|d60c0005a4c850c140378d1c82b81dde93a7ccab|d60c0005a4c850c140378d1c82b81dde93a7ccab|b4b5893be87edf98955f047cbf25ca755dc753b4",
+    "ee69aff0b7ea38927e5082ceef14115c805f6734|fcd36b4275c94f1955fb55e1c1ca3c04c7c0bb26|3c1b5cf24b4dfcd8e5736b735bfd3850940100d5|3c1b5cf24b4dfcd8e5736b735bfd3850940100d5"
+  ]
+}
diff --git a/tests/test_baseline.py b/tests/test_baseline.py
index 9c98489..f74ecdc 100644
--- a/tests/test_baseline.py
+++ b/tests/test_baseline.py
@@ -1,296 +1,876 @@
 import json
+from collections.abc import Callable
 from pathlib import Path
 
 import pytest
 
 import codeclone.baseline as baseline_mod
-from codeclone.baseline import Baseline
-from codeclone.errors import BaselineSchemaError
+from codeclone.baseline import Baseline, BaselineStatus, coerce_baseline_status
+from codeclone.contracts import BASELINE_FINGERPRINT_VERSION, BASELINE_SCHEMA_VERSION
+from codeclone.errors import BaselineValidationError
+
+
+def _python_tag() -> str:
+    return baseline_mod.current_python_tag()
+
+
+def _func_id() -> str:
+    return f"{'a' * 40}|0-19"
+
+
+def _func_id_alt() -> str:
+    return f"{'b' * 40}|20-39"
+
+
+def _block_id() -> str:
+    return "|".join(["a" * 40, "b" * 40, "c" * 40, "d" * 40])
+
+
+def _block_id_alt() -> str:
+    return "|".join(["b" * 40, "c" * 40, "d" * 40, "e" * 40])
+
+
+def _trusted_payload(
+    *,
+    functions: list[str] | None = None,
+    blocks: list[str] | None = None,
+    schema_version: str = BASELINE_SCHEMA_VERSION,
+    fingerprint_version: str = BASELINE_FINGERPRINT_VERSION,
+    python_tag: str | None = None,
+    created_at: str | None = "2026-02-08T11:43:16Z",
+    generator_version: str = "1.4.0",
+) -> dict[str, object]:
+    payload = baseline_mod._baseline_payload(
+        functions=set(functions or [_func_id()]),
+        blocks=set(blocks or [_block_id()]),
+        generator="codeclone",
+        schema_version=schema_version,
+        fingerprint_version=fingerprint_version,
+        python_tag=python_tag or _python_tag(),
+        generator_version=generator_version,
+        created_at=created_at,
+    )
+    return payload
+
+
+def _write_payload(path: Path, payload: dict[str, object]) -> None:
+    path.write_text(json.dumps(payload, ensure_ascii=False, indent=2), "utf-8")
 
 
 def test_baseline_diff() -> None:
     baseline = Baseline("dummy")
     baseline.functions = {"f1"}
     baseline.blocks = {"b1"}
-
-    func_groups: dict[str, object] = {"f1": [], "f2": []}
-    block_groups: dict[str, object] = {"b1": [], "b2": []}
-
-    new_func, new_block = baseline.diff(func_groups, block_groups)
-
+    new_func, new_block = baseline.diff({"f1": [], "f2": []}, {"b1": [], "b2": []})
     assert new_func == {"f2"}
     assert new_block == {"b2"}
 
 
-def test_baseline_io(tmp_path: Path) -> None:
-    f = tmp_path / "baseline.json"
-    bl = Baseline(f)
-    bl.functions = {"f1", "f2"}
-    bl.blocks = {"b1"}
-    bl.save()
-
-    assert f.exists()
-    content = json.loads(f.read_text("utf-8"))
-    assert content["functions"] == ["f1", "f2"]
-    assert content["blocks"] == ["b1"]
-    assert "python_version" not in content
-    assert "baseline_version" in content
-    assert "schema_version" in content
-    assert content["generator"] == "codeclone"
-    assert isinstance(content["payload_sha256"], str)
-    assert isinstance(content["created_at"], str)
-
-    bl2 = Baseline(f)
-    bl2.load()
-    bl2.verify_integrity()
-    assert bl2.functions == {"f1", "f2"}
-    assert bl2.blocks == {"b1"}
-    assert isinstance(bl2.baseline_version, str)
-    assert bl2.schema_version == 1
+@pytest.mark.parametrize(
+    ("raw_status", "expected"),
+    [
+        (BaselineStatus.OK, BaselineStatus.OK),
+        ("ok", BaselineStatus.OK),
+        ("not-a-status", BaselineStatus.INVALID_TYPE),
+        (None, BaselineStatus.INVALID_TYPE),
+    ],
+)
+def test_coerce_baseline_status(
+    raw_status: str | BaselineStatus | None, expected: BaselineStatus
+) -> None:
+    assert coerce_baseline_status(raw_status) == expected
+
+
+def test_baseline_roundtrip_v1(tmp_path: Path) -> None:
+    baseline_path = tmp_path / "baseline.json"
+    baseline = Baseline(baseline_path)
+    baseline.functions = {_func_id()}
+    baseline.blocks = {_block_id()}
+    baseline.save()
+
+    payload = json.loads(baseline_path.read_text("utf-8"))
+    assert set(payload.keys()) == {"meta", "clones"}
+    assert set(payload["meta"].keys()) >= {
+        "generator",
+        "schema_version",
+        "fingerprint_version",
+        "python_tag",
+        "created_at",
+        "payload_sha256",
+    }
+    assert set(payload["clones"].keys()) == {"functions", "blocks"}
+    assert payload["meta"]["schema_version"] == BASELINE_SCHEMA_VERSION
+    assert payload["meta"]["fingerprint_version"] == BASELINE_FINGERPRINT_VERSION
+    assert payload["meta"]["python_tag"] == _python_tag()
+    assert isinstance(payload["meta"]["payload_sha256"], str)
+
+    loaded = Baseline(baseline_path)
+    loaded.load()
+    loaded.verify_compatibility(current_python_tag=_python_tag())
+    assert loaded.functions == {_func_id()}
+    assert loaded.blocks == {_block_id()}
+
+
+def test_baseline_save_atomic(tmp_path: Path) -> None:
+    baseline_path = tmp_path / "baseline.json"
+    baseline = Baseline(baseline_path)
+    baseline.functions = {_func_id()}
+    baseline.blocks = {_block_id()}
+    baseline.save()
+    assert baseline_path.exists()
+    assert not (tmp_path / "baseline.json.tmp").exists()
 
 
 def test_baseline_load_missing(tmp_path: Path) -> None:
-    f = tmp_path / "non_existent.json"
-    bl = Baseline(f)
-    bl.load()
-    assert bl.functions == set()
-    assert bl.blocks == set()
-
+    baseline = Baseline(tmp_path / "missing.json")
+    baseline.load()
+    assert baseline.functions == set()
+    assert baseline.blocks == set()
 
-def test_baseline_load_corrupted(tmp_path: Path) -> None:
-    f = tmp_path / "corrupt.json"
-    f.write_text("{invalid json", "utf-8")
-    bl = Baseline(f)
-    with pytest.raises(BaselineSchemaError, match="Corrupted baseline file"):
-        bl.load()
 
-
-def test_baseline_load_non_object_payload(tmp_path: Path) -> None:
-    f = tmp_path / "not_object.json"
-    f.write_text("[]", "utf-8")
-    bl = Baseline(f)
-    with pytest.raises(BaselineSchemaError, match="must be an object"):
-        bl.load()
+def test_baseline_load_too_large(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    baseline_path = tmp_path / "baseline.json"
+    _write_payload(baseline_path, _trusted_payload())
+    monkeypatch.setattr(baseline_mod, "MAX_BASELINE_SIZE_BYTES", 1)
+    baseline = Baseline(baseline_path)
+    with pytest.raises(BaselineValidationError, match="too large") as exc:
+        baseline.load()
+    assert exc.value.status == "too_large"
 
 
 def test_baseline_load_stat_error(
     tmp_path: Path, monkeypatch: pytest.MonkeyPatch
 ) -> None:
-    f = tmp_path / "baseline.json"
-    f.write_text(json.dumps({"functions": [], "blocks": []}), "utf-8")
+    baseline_path = tmp_path / "baseline.json"
+    _write_payload(baseline_path, _trusted_payload())
     original_exists = Path.exists
-    original_stat = Path.stat
 
-    def _exists(self: Path) -> bool:
-        if self == f:
-            return True
+    def _boom_exists(self: Path) -> bool:
+        if self == baseline_path:
+            raise OSError("blocked")
         return original_exists(self)
 
-    def _boom(self: Path, *args: object, **kwargs: object) -> object:
-        if self == f:
-            raise OSError("blocked")
-        return original_stat(self)
+    monkeypatch.setattr(Path, "exists", _boom_exists)
+    baseline = Baseline(baseline_path)
+    with pytest.raises(
+        BaselineValidationError, match="Cannot stat baseline file"
+    ) as exc:
+        baseline.load()
+    assert exc.value.status == "invalid_type"
+
 
-    monkeypatch.setattr(Path, "exists", _exists)
-    monkeypatch.setattr(Path, "stat", _boom)
-    bl = Baseline(f)
-    with pytest.raises(BaselineSchemaError, match="Cannot stat baseline file"):
-        bl.load()
+def test_baseline_load_invalid_json(tmp_path: Path) -> None:
+    baseline_path = tmp_path / "baseline.json"
+    baseline_path.write_text("{broken json", "utf-8")
+    baseline = Baseline(baseline_path)
+    with pytest.raises(BaselineValidationError, match="Corrupted baseline file") as exc:
+        baseline.load()
+    assert exc.value.status == "invalid_json"
 
 
-def test_baseline_load_invalid_schema(tmp_path: Path) -> None:
-    f = tmp_path / "invalid.json"
-    f.write_text(
-        json.dumps({"functions": ["f1"], "blocks": [1], "schema_version": 1}),
+def test_baseline_load_non_object_payload(tmp_path: Path) -> None:
+    baseline_path = tmp_path / "baseline.json"
+    baseline_path.write_text("[]", "utf-8")
+    baseline = Baseline(baseline_path)
+    with pytest.raises(BaselineValidationError, match="must be an object") as exc:
+        baseline.load()
+    assert exc.value.status == "invalid_type"
+
+
+def test_baseline_load_legacy_payload(tmp_path: Path) -> None:
+    baseline_path = tmp_path / "baseline.json"
+    baseline_path.write_text(
+        json.dumps({"functions": [], "blocks": [], "baseline_version": "1.3.0"}),
         "utf-8",
     )
-    bl = Baseline(f)
-    with pytest.raises(BaselineSchemaError, match="Invalid baseline schema"):
-        bl.load()
-
-
-def test_baseline_load_invalid_created_at_type(tmp_path: Path) -> None:
-    f = tmp_path / "invalid_created_at.json"
-    f.write_text(
-        json.dumps(
-            {
-                "functions": [],
-                "blocks": [],
-                "baseline_version": "1.3.0",
-                "schema_version": 1,
-                "created_at": 123,
-            }
-        ),
-        "utf-8",
+    baseline = Baseline(baseline_path)
+    with pytest.raises(BaselineValidationError, match="legacy") as exc:
+        baseline.load()
+    assert exc.value.status == "missing_fields"
+
+
+def test_baseline_load_missing_top_level_key(tmp_path: Path) -> None:
+    baseline_path = tmp_path / "baseline.json"
+    _write_payload(baseline_path, {"meta": {}})
+    baseline = Baseline(baseline_path)
+    with pytest.raises(BaselineValidationError, match="missing top-level keys") as exc:
+        baseline.load()
+    assert exc.value.status == "missing_fields"
+
+
+def test_baseline_load_extra_top_level_key(tmp_path: Path) -> None:
+    baseline_path = tmp_path / "baseline.json"
+    payload = _trusted_payload()
+    assert isinstance(payload, dict)
+    payload["extra"] = 1
+    _write_payload(baseline_path, payload)
+    baseline = Baseline(baseline_path)
+    with pytest.raises(
+        BaselineValidationError, match="unexpected top-level keys"
+    ) as exc:
+        baseline.load()
+    assert exc.value.status == "invalid_type"
+
+
+def test_baseline_load_meta_and_clones_must_be_objects(tmp_path: Path) -> None:
+    baseline_path = tmp_path / "baseline.json"
+    _write_payload(baseline_path, {"meta": [], "clones": {}})
+    baseline = Baseline(baseline_path)
+    with pytest.raises(BaselineValidationError, match="'meta' must be object"):
+        baseline.load()
+    _write_payload(baseline_path, {"meta": {}, "clones": []})
+    with pytest.raises(BaselineValidationError, match="'clones' must be object"):
+        baseline.load()
+
+
+def test_baseline_load_missing_required_meta_fields(tmp_path: Path) -> None:
+    baseline_path = tmp_path / "baseline.json"
+    _write_payload(
+        baseline_path,
+        {"meta": {"generator": "codeclone"}, "clones": {"functions": [], "blocks": []}},
     )
-    bl = Baseline(f)
-    with pytest.raises(BaselineSchemaError, match="'created_at' must be string"):
-        bl.load()
-
-
-def test_baseline_load_invalid_schema_version_type(tmp_path: Path) -> None:
-    f = tmp_path / "invalid_schema_version.json"
-    f.write_text(
-        json.dumps(
-            {
-                "functions": [],
-                "blocks": [],
-                "baseline_version": "1.3.0",
-                "schema_version": "1",
-            }
-        ),
-        "utf-8",
+    baseline = Baseline(baseline_path)
+    with pytest.raises(BaselineValidationError, match="missing required fields") as exc:
+        baseline.load()
+    assert exc.value.status == "missing_fields"
+
+
+def test_baseline_load_missing_required_clone_fields(tmp_path: Path) -> None:
+    baseline_path = tmp_path / "baseline.json"
+    payload = _trusted_payload()
+    assert isinstance(payload, dict)
+    payload["clones"] = {"functions": [_func_id()]}
+    _write_payload(baseline_path, payload)
+    baseline = Baseline(baseline_path)
+    with pytest.raises(BaselineValidationError, match="missing required fields") as exc:
+        baseline.load()
+    assert exc.value.status == "missing_fields"
+
+
+def test_baseline_load_unexpected_clone_fields(tmp_path: Path) -> None:
+    baseline_path = tmp_path / "baseline.json"
+    payload = _trusted_payload()
+    assert isinstance(payload, dict)
+    clones = payload["clones"]
+    assert isinstance(clones, dict)
+    clones["segments"] = []
+    _write_payload(baseline_path, payload)
+    baseline = Baseline(baseline_path)
+    with pytest.raises(BaselineValidationError, match="unexpected clone keys") as exc:
+        baseline.load()
+    assert exc.value.status == "invalid_type"
+
+
+@pytest.mark.parametrize(
+    ("container", "field", "value", "error_match"),
+    [
+        ("meta", "generator", 1, "'generator' must be string"),
+        ("meta", "schema_version", "x", "schema_version"),
+        ("meta", "fingerprint_version", 1, "'fingerprint_version' must be string"),
+        ("meta", "python_tag", "3.13", "python_tag"),
+        ("meta", "created_at", "2026-02-08T11:43:16+00:00", "created_at"),
+        ("meta", "payload_sha256", 1, "payload_sha256"),
+        ("clones", "functions", "x", "functions"),
+        ("clones", "blocks", "x", "blocks"),
+    ],
+)
+def test_baseline_type_matrix(
+    tmp_path: Path,
+    container: str,
+    field: str,
+    value: object,
+    error_match: str,
+) -> None:
+    baseline_path = tmp_path / "baseline.json"
+    payload = _trusted_payload()
+    target = payload[container]
+    assert isinstance(target, dict)
+    target[field] = value
+    _write_payload(baseline_path, payload)
+    baseline = Baseline(baseline_path)
+    with pytest.raises(BaselineValidationError, match=error_match) as exc:
+        baseline.load()
+    assert exc.value.status == "invalid_type"
+
+
+def test_baseline_id_lists_must_be_sorted_and_unique(tmp_path: Path) -> None:
+    baseline_path = tmp_path / "baseline.json"
+    payload = _trusted_payload()
+    clones = payload["clones"]
+    assert isinstance(clones, dict)
+    clones["functions"] = [_func_id(), _func_id()]
+    _write_payload(baseline_path, payload)
+    baseline = Baseline(baseline_path)
+    with pytest.raises(BaselineValidationError, match="sorted and unique") as exc:
+        baseline.load()
+    assert exc.value.status == "invalid_type"
+
+    payload = _trusted_payload()
+    clones = payload["clones"]
+    assert isinstance(clones, dict)
+    clones["functions"] = [f"{'b' * 40}|0-19", _func_id()]
+    _write_payload(baseline_path, payload)
+    with pytest.raises(BaselineValidationError, match="sorted and unique") as exc2:
+        baseline.load()
+    assert exc2.value.status == "invalid_type"
+
+
+def test_baseline_id_format_validation(tmp_path: Path) -> None:
+    baseline_path = tmp_path / "baseline.json"
+    payload = _trusted_payload(functions=["bad-id"])
+    _write_payload(baseline_path, payload)
+    baseline = Baseline(baseline_path)
+    with pytest.raises(BaselineValidationError, match="invalid id format") as exc:
+        baseline.load()
+    assert exc.value.status == "invalid_type"
+
+    payload = _trusted_payload(blocks=["bad-block-id"])
+    _write_payload(baseline_path, payload)
+    with pytest.raises(BaselineValidationError, match="invalid id format") as exc2:
+        baseline.load()
+    assert exc2.value.status == "invalid_type"
+
+
+def test_baseline_verify_generator_mismatch(tmp_path: Path) -> None:
+    baseline_path = tmp_path / "baseline.json"
+    payload = _trusted_payload()
+    assert isinstance(payload, dict)
+    meta = payload["meta"]
+    assert isinstance(meta, dict)
+    meta["generator"] = "eviltool"
+    _write_payload(baseline_path, payload)
+    baseline = Baseline(baseline_path)
+    baseline.load()
+    with pytest.raises(BaselineValidationError, match="generator mismatch") as exc:
+        baseline.verify_compatibility(current_python_tag=_python_tag())
+    assert exc.value.status == "generator_mismatch"
+
+
+def test_baseline_verify_schema_too_new(tmp_path: Path) -> None:
+    baseline_path = tmp_path / "baseline.json"
+    _write_payload(baseline_path, _trusted_payload(schema_version="1.1"))
+    baseline = Baseline(baseline_path)
+    baseline.load()
+    with pytest.raises(BaselineValidationError, match="newer than supported") as exc:
+        baseline.verify_compatibility(current_python_tag=_python_tag())
+    assert exc.value.status == "mismatch_schema_version"
+
+
+def test_baseline_verify_fingerprint_mismatch(tmp_path: Path) -> None:
+    baseline_path = tmp_path / "baseline.json"
+    _write_payload(baseline_path, _trusted_payload(fingerprint_version="2"))
+    baseline = Baseline(baseline_path)
+    baseline.load()
+    with pytest.raises(
+        BaselineValidationError, match="fingerprint version mismatch"
+    ) as exc:
+        baseline.verify_compatibility(current_python_tag=_python_tag())
+    assert exc.value.status == "mismatch_fingerprint_version"
+
+
+def test_baseline_verify_python_tag_mismatch(tmp_path: Path) -> None:
+    baseline_path = tmp_path / "baseline.json"
+    _write_payload(baseline_path, _trusted_payload(python_tag="cp999"))
+    baseline = Baseline(baseline_path)
+    baseline.load()
+    with pytest.raises(BaselineValidationError, match="python tag mismatch") as exc:
+        baseline.verify_compatibility(current_python_tag=_python_tag())
+    assert exc.value.status == "mismatch_python_version"
+
+
+def test_baseline_verify_integrity_missing(tmp_path: Path) -> None:
+    baseline_path = tmp_path / "baseline.json"
+    payload = _trusted_payload()
+    assert isinstance(payload, dict)
+    meta = payload["meta"]
+    assert isinstance(meta, dict)
+    meta["payload_sha256"] = "zz"
+    _write_payload(baseline_path, payload)
+    baseline = Baseline(baseline_path)
+    baseline.load()
+    with pytest.raises(BaselineValidationError, match="payload hash is missing") as exc:
+        baseline.verify_integrity()
+    assert exc.value.status == "integrity_missing"
+
+
+def test_baseline_verify_integrity_mismatch(tmp_path: Path) -> None:
+    baseline_path = tmp_path / "baseline.json"
+    payload = _trusted_payload()
+    assert isinstance(payload, dict)
+    clones = payload["clones"]
+    assert isinstance(clones, dict)
+    clones["functions"] = [_func_id(), f"{'b' * 40}|0-19"]
+    _write_payload(baseline_path, payload)
+    baseline = Baseline(baseline_path)
+    baseline.load()
+    with pytest.raises(BaselineValidationError, match="payload_sha256 mismatch") as exc:
+        baseline.verify_integrity()
+    assert exc.value.status == "integrity_failed"
+
+
+def test_baseline_integrity_fails_on_clone_removal(tmp_path: Path) -> None:
+    baseline_path = tmp_path / "baseline.json"
+    payload = _trusted_payload(blocks=[_block_id(), _block_id_alt()])
+    _write_payload(baseline_path, payload)
+    baseline = Baseline(baseline_path)
+    baseline.load()
+    baseline.blocks.remove(_block_id_alt())
+    with pytest.raises(BaselineValidationError, match="payload_sha256 mismatch") as exc:
+        baseline.verify_integrity()
+    assert exc.value.status == "integrity_failed"
+
+
+def test_baseline_integrity_fails_on_block_addition_without_rehash(
+    tmp_path: Path,
+) -> None:
+    baseline_path = tmp_path / "baseline.json"
+    payload = _trusted_payload(blocks=[_block_id()])
+    _write_payload(baseline_path, payload)
+    baseline = Baseline(baseline_path)
+    baseline.load()
+    baseline.blocks.add(_block_id_alt())
+    with pytest.raises(BaselineValidationError, match="payload_sha256 mismatch") as exc:
+        baseline.verify_integrity()
+    assert exc.value.status == "integrity_failed"
+
+
+@pytest.mark.parametrize(
+    "blocks",
+    [
+        [_block_id(), _block_id()],
+        [_block_id_alt(), _block_id()],
+    ],
+)
+def test_baseline_load_rejects_non_canonical_block_lists(
+    tmp_path: Path, blocks: list[str]
+) -> None:
+    baseline_path = tmp_path / "baseline.json"
+    payload = _trusted_payload()
+    clones = payload["clones"]
+    assert isinstance(clones, dict)
+    clones["blocks"] = blocks
+    _write_payload(baseline_path, payload)
+    baseline = Baseline(baseline_path)
+    with pytest.raises(BaselineValidationError, match="sorted and unique") as exc:
+        baseline.load()
+    assert exc.value.status == "invalid_type"
+
+
+def test_baseline_verify_compatibility_ignores_generator_version(
+    tmp_path: Path,
+) -> None:
+    baseline_path = tmp_path / "baseline.json"
+    _write_payload(baseline_path, _trusted_payload())
+    baseline = Baseline(baseline_path)
+    baseline.load()
+    baseline.generator_version = "9.9.9"
+    baseline.verify_compatibility(current_python_tag=_python_tag())
+
+
+def test_baseline_payload_fields_contract_invariant(tmp_path: Path) -> None:
+    baseline_path = tmp_path / "baseline.json"
+    _write_payload(
+        baseline_path,
+        _trusted_payload(functions=[_func_id()], blocks=[_block_id()]),
     )
-    bl = Baseline(f)
-    with pytest.raises(BaselineSchemaError, match="'schema_version' must be integer"):
-        bl.load()
+    baseline = Baseline(baseline_path)
+    baseline.load()
+
+    payload_mutators: list[Callable[[Baseline], None]] = [
+        lambda b: b.functions.add(_func_id_alt()),
+        lambda b: b.blocks.add(_block_id_alt()),
+        lambda b: setattr(b, "fingerprint_version", "2"),
+        lambda b: setattr(b, "python_tag", "cp399"),
+    ]
+    for mutate in payload_mutators:
+        probe = Baseline(baseline_path)
+        probe.load()
+        mutate(probe)
+        with pytest.raises(
+            BaselineValidationError, match="payload_sha256 mismatch"
+        ) as exc:
+            probe.verify_integrity()
+        assert exc.value.status == "integrity_failed"
+
+    non_payload_mutators: list[Callable[[Baseline], None]] = [
+        lambda b: setattr(b, "created_at", "2030-01-01T00:00:00Z"),
+        lambda b: setattr(b, "generator_version", "9.9.9"),
+        lambda b: setattr(b, "schema_version", "1.1"),
+    ]
+    for mutate in non_payload_mutators:
+        probe = Baseline(baseline_path)
+        probe.load()
+        baseline_hash = probe.payload_sha256
+        mutate(probe)
+        probe.verify_integrity()
+        assert probe.payload_sha256 == baseline_hash
+
+
+def test_baseline_hash_canonical_determinism() -> None:
+    hash_a = baseline_mod._compute_payload_sha256(
+        functions={"a" * 40 + "|0-19", "b" * 40 + "|0-19"},
+        blocks={_block_id()},
+        fingerprint_version="1",
+        python_tag="cp313",
+    )
+    hash_b = baseline_mod._compute_payload_sha256(
+        functions={"b" * 40 + "|0-19", "a" * 40 + "|0-19"},
+        blocks={_block_id()},
+        fingerprint_version="1",
+        python_tag="cp313",
+    )
+    assert hash_a == hash_b
 
 
-def test_baseline_load_too_large(
-    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+def test_baseline_payload_sha256_independent_of_created_at_and_generator_version() -> (
+    None
+):
+    payload_a = _trusted_payload(
+        created_at="2026-02-08T11:43:16Z",
+        generator_version="1.4.0",
+    )
+    payload_b = _trusted_payload(
+        created_at="2030-01-01T00:00:00Z",
+        generator_version="9.9.9",
+    )
+    meta_a = payload_a["meta"]
+    meta_b = payload_b["meta"]
+    assert isinstance(meta_a, dict)
+    assert isinstance(meta_b, dict)
+    assert meta_a["payload_sha256"] == meta_b["payload_sha256"]
+
+
+def test_baseline_payload_sha256_independent_of_schema_version() -> None:
+    payload_a = _trusted_payload(schema_version="1.0")
+    payload_b = _trusted_payload(schema_version="1.1")
+    meta_a = payload_a["meta"]
+    meta_b = payload_b["meta"]
+    assert isinstance(meta_a, dict)
+    assert isinstance(meta_b, dict)
+    assert meta_a["payload_sha256"] == meta_b["payload_sha256"]
+
+
+def test_baseline_schema_version_mutation_preserves_integrity_and_hash_on_save(
+    tmp_path: Path,
 ) -> None:
-    f = tmp_path / "large.json"
-    f.write_text(json.dumps({"functions": [], "blocks": []}), "utf-8")
-    monkeypatch.setattr(baseline_mod, "MAX_BASELINE_SIZE_BYTES", 1)
-    bl = Baseline(f)
-    with pytest.raises(BaselineSchemaError, match="too large"):
-        bl.load()
-
-
-def test_baseline_integrity_missing_payload(tmp_path: Path) -> None:
-    f = tmp_path / "missing_payload.json"
-    f.write_text(
-        json.dumps(
-            {
-                "functions": ["f1"],
-                "blocks": ["b1"],
-                "baseline_version": "1.3.0",
-                "schema_version": 1,
-                "generator": "codeclone",
-            }
-        ),
+    baseline_path = tmp_path / "baseline.json"
+    _write_payload(baseline_path, _trusted_payload(schema_version="1.0"))
+
+    baseline = Baseline(baseline_path)
+    baseline.load()
+    original_hash = baseline.payload_sha256
+    assert isinstance(original_hash, str)
+
+    baseline.schema_version = "1.1"
+    baseline.verify_integrity()
+    baseline.save()
+
+    payload = json.loads(baseline_path.read_text("utf-8"))
+    meta = payload["meta"]
+    assert isinstance(meta, dict)
+    assert meta["schema_version"] == "1.1"
+    assert meta["payload_sha256"] == original_hash
+
+    reloaded = Baseline(baseline_path)
+    reloaded.load()
+    reloaded.verify_integrity()
+    assert reloaded.payload_sha256 == original_hash
+
+
+def test_baseline_verify_integrity_ignores_created_at_and_generator_version(
+    tmp_path: Path,
+) -> None:
+    baseline_path = tmp_path / "baseline.json"
+    _write_payload(baseline_path, _trusted_payload())
+    baseline = Baseline(baseline_path)
+    baseline.load()
+    baseline.created_at = "2030-12-31T23:59:59Z"
+    baseline.generator_version = "9.9.9"
+    baseline.verify_integrity()
+
+
+def test_baseline_load_whitespace_and_key_order_do_not_break_integrity(
+    tmp_path: Path,
+) -> None:
+    baseline_path = tmp_path / "baseline.json"
+    payload = _trusted_payload()
+    meta = payload["meta"]
+    clones = payload["clones"]
+    assert isinstance(meta, dict)
+    assert isinstance(clones, dict)
+
+    custom_order_payload = {
+        "clones": {
+            "blocks": clones["blocks"],
+            "functions": clones["functions"],
+        },
+        "meta": {
+            "payload_sha256": meta["payload_sha256"],
+            "created_at": meta["created_at"],
+            "python_tag": meta["python_tag"],
+            "fingerprint_version": meta["fingerprint_version"],
+            "schema_version": meta["schema_version"],
+            "generator": meta["generator"],
+        },
+    }
+    baseline_path.write_text(
+        json.dumps(custom_order_payload, ensure_ascii=False, indent=4) + "\n\n",
         "utf-8",
     )
-    bl = Baseline(f)
-    bl.load()
-    with pytest.raises(BaselineSchemaError, match="payload hash is missing"):
-        bl.verify_integrity()
-
-
-def test_baseline_integrity_generator_mismatch(tmp_path: Path) -> None:
-    f = tmp_path / "generator_mismatch.json"
-    bl = Baseline(f)
-    bl.functions = {"f1"}
-    bl.blocks = {"b1"}
-    bl.save()
-    payload = json.loads(f.read_text("utf-8"))
-    payload["generator"] = "evil"
-    f.write_text(json.dumps(payload), "utf-8")
-    bl2 = Baseline(f)
-    bl2.load()
-    with pytest.raises(BaselineSchemaError, match="generator mismatch"):
-        bl2.verify_integrity()
-
-
-def test_baseline_integrity_generator_wrong_type(tmp_path: Path) -> None:
-    f = tmp_path / "generator_wrong_type.json"
-    bl = Baseline(f)
-    bl.functions = {"f1"}
-    bl.blocks = {"b1"}
-    bl.save()
-    payload = json.loads(f.read_text("utf-8"))
-    payload["generator"] = 123
-    f.write_text(json.dumps(payload), "utf-8")
-    bl2 = Baseline(f)
-    bl2.load()
-    with pytest.raises(BaselineSchemaError, match="generator mismatch"):
-        bl2.verify_integrity()
-
-
-def test_baseline_integrity_payload_mismatch(tmp_path: Path) -> None:
-    f = tmp_path / "tampered.json"
-    bl = Baseline(f)
-    bl.functions = {"f1"}
-    bl.blocks = {"b1"}
-    bl.save()
-    payload = json.loads(f.read_text("utf-8"))
-    payload["functions"] = ["tampered"]
-    f.write_text(json.dumps(payload), "utf-8")
-    bl2 = Baseline(f)
-    bl2.load()
-    with pytest.raises(BaselineSchemaError, match="payload_sha256 mismatch"):
-        bl2.verify_integrity()
-
-
-def test_baseline_integrity_payload_wrong_type(tmp_path: Path) -> None:
-    f = tmp_path / "payload_wrong_type.json"
-    bl = Baseline(f)
-    bl.functions = {"f1"}
-    bl.blocks = {"b1"}
-    bl.save()
-    payload = json.loads(f.read_text("utf-8"))
-    payload["payload_sha256"] = 1
-    f.write_text(json.dumps(payload), "utf-8")
-    bl2 = Baseline(f)
-    bl2.load()
-    with pytest.raises(BaselineSchemaError, match="payload hash is missing"):
-        bl2.verify_integrity()
-
-
-def test_baseline_verify_integrity_skips_legacy(tmp_path: Path) -> None:
-    f = tmp_path / "legacy.json"
-    f.write_text(json.dumps({"functions": [], "blocks": []}), "utf-8")
-    bl = Baseline(f)
-    bl.load()
-    bl.verify_integrity()
-
-
-def test_baseline_from_groups() -> None:
-    func_groups: dict[str, object] = {"f1": [], "f2": []}
-    block_groups: dict[str, object] = {"b1": []}
-    bl = Baseline.from_groups(
-        func_groups,
-        block_groups,
-        path="custom.json",
-        baseline_version="1.3.0",
-        schema_version=1,
+
+    baseline = Baseline(baseline_path)
+    baseline.load()
+    baseline.verify_compatibility(current_python_tag=_python_tag())
+    assert baseline.functions == {_func_id()}
+    assert baseline.blocks == {_block_id()}
+
+
+def test_baseline_save_sorts_clone_lists_deterministically(tmp_path: Path) -> None:
+    baseline_path = tmp_path / "baseline.json"
+    func_a = f"{'a' * 40}|0-19"
+    func_b = f"{'b' * 40}|0-19"
+    block_a = "|".join(["a" * 40, "b" * 40, "c" * 40, "d" * 40])
+    block_b = "|".join(["b" * 40, "c" * 40, "d" * 40, "e" * 40])
+    baseline = Baseline(baseline_path)
+    baseline.functions = {func_b, func_a}
+    baseline.blocks = {block_b, block_a}
+    baseline.save()
+
+    payload = json.loads(baseline_path.read_text("utf-8"))
+    clones = payload["clones"]
+    assert isinstance(clones, dict)
+    assert clones["functions"] == [func_a, func_b]
+    assert clones["blocks"] == [block_a, block_b]
+
+
+def test_baseline_from_groups_defaults() -> None:
+    baseline = Baseline.from_groups(
+        {"a" * 40 + "|0-19": []},
+        {_block_id(): []},
+        path="baseline.json",
     )
+    assert baseline.path == Path("baseline.json")
+    assert baseline.schema_version == BASELINE_SCHEMA_VERSION
+    assert baseline.fingerprint_version == BASELINE_FINGERPRINT_VERSION
+    assert baseline.python_tag == _python_tag()
+    assert baseline.generator == "codeclone"
+
+
+def test_baseline_verify_schema_major_mismatch(tmp_path: Path) -> None:
+    baseline_path = tmp_path / "baseline.json"
+    _write_payload(baseline_path, _trusted_payload(schema_version="2.0"))
+    baseline = Baseline(baseline_path)
+    baseline.load()
+    with pytest.raises(BaselineValidationError, match="schema version mismatch") as exc:
+        baseline.verify_compatibility(current_python_tag=_python_tag())
+    assert exc.value.status == "mismatch_schema_version"
+
+
+@pytest.mark.parametrize(
+    ("attr", "match_text"),
+    [
+        ("schema_version", "schema version is missing"),
+        ("fingerprint_version", "fingerprint version is missing"),
+        ("python_tag", "python_tag is missing"),
+    ],
+)
+def test_baseline_verify_compatibility_missing_fields(
+    tmp_path: Path, attr: str, match_text: str
+) -> None:
+    baseline_path = tmp_path / "baseline.json"
+    _write_payload(baseline_path, _trusted_payload())
+    baseline = Baseline(baseline_path)
+    baseline.load()
+    setattr(baseline, attr, None)
+    with pytest.raises(BaselineValidationError, match=match_text) as exc:
+        baseline.verify_compatibility(current_python_tag=_python_tag())
+    assert exc.value.status == "missing_fields"
+
+
+def test_baseline_verify_integrity_payload_not_string(tmp_path: Path) -> None:
+    baseline_path = tmp_path / "baseline.json"
+    _write_payload(baseline_path, _trusted_payload())
+    baseline = Baseline(baseline_path)
+    baseline.load()
+    baseline.payload_sha256 = None
+    with pytest.raises(BaselineValidationError, match="payload hash is missing") as exc:
+        baseline.verify_integrity()
+    assert exc.value.status == "integrity_missing"
+
+
+def test_baseline_verify_integrity_payload_non_hex(tmp_path: Path) -> None:
+    baseline_path = tmp_path / "baseline.json"
+    _write_payload(baseline_path, _trusted_payload())
+    baseline = Baseline(baseline_path)
+    baseline.load()
+    baseline.payload_sha256 = "g" * 64
+    with pytest.raises(BaselineValidationError, match="payload hash is missing") as exc:
+        baseline.verify_integrity()
+    assert exc.value.status == "integrity_missing"
+
+
+@pytest.mark.parametrize(
+    ("attr", "match_text"),
+    [
+        ("schema_version", "schema version is missing for integrity"),
+        ("fingerprint_version", "fingerprint version is missing for integrity"),
+        ("python_tag", "python_tag is missing for integrity"),
+    ],
+)
+def test_baseline_verify_integrity_missing_context_fields(
+    tmp_path: Path, attr: str, match_text: str
+) -> None:
+    baseline_path = tmp_path / "baseline.json"
+    _write_payload(baseline_path, _trusted_payload())
+    baseline = Baseline(baseline_path)
+    baseline.load()
+    setattr(baseline, attr, None)
+    with pytest.raises(BaselineValidationError, match=match_text) as exc:
+        baseline.verify_integrity()
+    assert exc.value.status == "missing_fields"
 
-    assert bl.functions == {"f1", "f2"}
-    assert bl.blocks == {"b1"}
-    assert bl.path == Path("custom.json")
-    assert bl.baseline_version == "1.3.0"
-    assert bl.schema_version == 1
 
+def test_baseline_safe_stat_size_oserror(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    path = tmp_path / "baseline.json"
 
-def test_baseline_python_version_roundtrip(tmp_path: Path) -> None:
-    f = tmp_path / "baseline.json"
-    bl = Baseline(f)
-    bl.functions = {"f1"}
-    bl.blocks = {"b1"}
-    bl.python_version = "3.13"
-    bl.save()
+    def _boom_stat(self: Path) -> object:
+        if self == path:
+            raise OSError("blocked")
+        return object()
 
-    content = json.loads(f.read_text("utf-8"))
-    assert content["python_version"] == "3.13"
-    assert "baseline_version" in content
-    assert content["schema_version"] == 1
+    monkeypatch.setattr(Path, "stat", _boom_stat)
+    with pytest.raises(
+        BaselineValidationError, match="Cannot stat baseline file"
+    ) as exc:
+        baseline_mod._safe_stat_size(path)
+    assert exc.value.status == "invalid_type"
 
-    bl2 = Baseline(f)
-    bl2.load()
-    assert bl2.python_version == "3.13"
-    assert isinstance(bl2.baseline_version, str)
-    assert bl2.schema_version == 1
 
+def test_baseline_load_json_read_error(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    path = tmp_path / "baseline.json"
+    path.write_text("{}", "utf-8")
 
-def test_baseline_payload_without_created_at() -> None:
-    payload = baseline_mod._baseline_payload(
-        {"f1"},
-        {"b1"},
-        python_version=None,
-        baseline_version="1.3.0",
-        schema_version=1,
-        generator="codeclone",
-        created_at=None,
+    def _boom_read(self: Path, *_args: object, **_kwargs: object) -> str:
+        if self == path:
+            raise OSError("blocked")
+        return "{}"
+
+    monkeypatch.setattr(Path, "read_text", _boom_read)
+    with pytest.raises(
+        BaselineValidationError, match="Cannot read baseline file"
+    ) as exc:
+        baseline_mod._load_json_object(path)
+    assert exc.value.status == "invalid_json"
+
+
+def test_baseline_optional_str_paths(tmp_path: Path) -> None:
+    path = tmp_path / "baseline.json"
+    assert baseline_mod._optional_str({}, "generator_version", path=path) is None
+    with pytest.raises(
+        BaselineValidationError,
+        match="'generator_version' must be string",
+    ) as exc:
+        baseline_mod._optional_str(
+            {"generator_version": 1},
+            "generator_version",
+            path=path,
+        )
+    assert exc.value.status == "invalid_type"
+
+
+def test_baseline_load_legacy_codeclone_version_alias(tmp_path: Path) -> None:
+    baseline_path = tmp_path / "baseline.json"
+    payload = _trusted_payload(generator_version="1.4.0")
+    meta = payload["meta"]
+    assert isinstance(meta, dict)
+    generator = meta.get("generator")
+    assert isinstance(generator, dict)
+    # Simulate pre-rename baseline metadata key.
+    meta["codeclone_version"] = generator.pop("version")
+    _write_payload(baseline_path, payload)
+
+    baseline = Baseline(baseline_path)
+    baseline.load()
+    assert baseline.generator_version == "1.4.0"
+
+
+def test_parse_generator_meta_string_legacy_alias(tmp_path: Path) -> None:
+    path = tmp_path / "baseline.json"
+    name, version = baseline_mod._parse_generator_meta(
+        {
+            "generator": "codeclone",
+            "codeclone_version": "1.4.0",
+        },
+        path=path,
+    )
+    assert name == "codeclone"
+    assert version == "1.4.0"
+
+
+def test_parse_generator_meta_string_prefers_generator_version(tmp_path: Path) -> None:
+    path = tmp_path / "baseline.json"
+    name, version = baseline_mod._parse_generator_meta(
+        {
+            "generator": "codeclone",
+            "generator_version": "1.4.2",
+            "codeclone_version": "1.4.0",
+        },
+        path=path,
     )
-    assert "created_at" not in payload
+    assert name == "codeclone"
+    assert version == "1.4.2"
+
+
+def test_parse_generator_meta_object_top_level_fallback(tmp_path: Path) -> None:
+    path = tmp_path / "baseline.json"
+    name, version = baseline_mod._parse_generator_meta(
+        {
+            "generator": {"name": "codeclone"},
+            "generator_version": "1.4.1",
+        },
+        path=path,
+    )
+    assert name == "codeclone"
+    assert version == "1.4.1"
+
+
+def test_parse_generator_meta_rejects_extra_generator_keys(tmp_path: Path) -> None:
+    path = tmp_path / "baseline.json"
+    with pytest.raises(
+        BaselineValidationError, match="unexpected generator keys"
+    ) as exc:
+        baseline_mod._parse_generator_meta(
+            {"generator": {"name": "codeclone", "version": "1.4.0", "extra": "x"}},
+            path=path,
+        )
+    assert exc.value.status == "invalid_type"
+
+
+def test_baseline_parse_semver_three_parts(tmp_path: Path) -> None:
+    path = tmp_path / "baseline.json"
+    assert baseline_mod._parse_semver("1.2.3", key="schema_version", path=path) == (
+        1,
+        2,
+        3,
+    )
+
+
+def test_baseline_require_sorted_unique_ids_non_string(tmp_path: Path) -> None:
+    path = tmp_path / "baseline.json"
+    with pytest.raises(
+        BaselineValidationError,
+        match="'functions' must be list\\[str\\]",
+    ) as exc:
+        baseline_mod._require_sorted_unique_ids(
+            {"functions": [1]},
+            "functions",
+            pattern=baseline_mod._FUNCTION_ID_RE,
+            path=path,
+        )
+    assert exc.value.status == "invalid_type"
diff --git a/tests/test_cache.py b/tests/test_cache.py
index 160c9bb..ba205b1 100644
--- a/tests/test_cache.py
+++ b/tests/test_cache.py
@@ -9,7 +9,7 @@
 
 import codeclone.cache as cache_mod
 from codeclone.blocks import BlockUnit, SegmentUnit
-from codeclone.cache import Cache
+from codeclone.cache import Cache, CacheStatus
 from codeclone.errors import CacheError
 from codeclone.extractor import Unit
 
@@ -67,6 +67,95 @@ def test_cache_roundtrip(tmp_path: Path) -> None:
     assert entry is not None
     assert entry["stat"]["size"] == 10
     assert entry["units"][0]["qualname"] == "mod:func"
+    assert loaded.load_status == CacheStatus.OK
+    assert loaded.cache_schema_version == Cache._CACHE_VERSION
+
+
+def test_get_file_entry_uses_wire_key_fallback(tmp_path: Path) -> None:
+    root = tmp_path / "project"
+    file_path = root / "pkg" / "module.py"
+    file_path.parent.mkdir(parents=True, exist_ok=True)
+    cache = Cache(tmp_path / "cache.json", root=root)
+    runtime_key = str(file_path.resolve())
+    cache.data["files"][runtime_key] = cast(
+        Any,
+        {
+            "stat": {"mtime_ns": 1, "size": 1},
+            "units": [],
+            "blocks": [],
+            "segments": [],
+        },
+    )
+    non_canonical = str(root / "pkg" / ".." / "pkg" / "module.py")
+    assert cache.get_file_entry(non_canonical) is not None
+
+
+def test_get_file_entry_missing_after_fallback_returns_none(tmp_path: Path) -> None:
+    root = tmp_path / "project"
+    root.mkdir()
+    cache = Cache(tmp_path / "cache.json", root=root)
+    assert cache.get_file_entry(str(root / "pkg" / "missing.py")) is None
+
+
+def test_cache_v12_uses_relpaths_when_root_set(tmp_path: Path) -> None:
+    project_root = tmp_path / "project"
+    target = project_root / "pkg" / "module.py"
+    target.parent.mkdir(parents=True, exist_ok=True)
+    target.write_text("def f():\n    return 1\n", "utf-8")
+
+    cache_path = project_root / ".cache" / "codeclone" / "cache.json"
+    cache = Cache(cache_path, root=project_root)
+    cache.put_file_entry(
+        str(target),
+        {"mtime_ns": 1, "size": 10},
+        [_make_unit(str(target))],
+        [_make_block(str(target))],
+        [_make_segment(str(target))],
+    )
+    cache.save()
+
+    raw = json.loads(cache_path.read_text("utf-8"))
+    payload = cast(dict[str, object], raw["payload"])
+    files = cast(dict[str, object], payload["files"])
+    assert "pkg/module.py" in files
+    assert str(target) not in files
+
+
+def test_cache_v12_missing_optional_sections_default_empty(tmp_path: Path) -> None:
+    cache_path = tmp_path / "cache.json"
+    cache = Cache(cache_path)
+    payload = {
+        "py": cache.data["python_tag"],
+        "fp": cache.data["fingerprint_version"],
+        "files": {"x.py": {"st": [1, 2]}},
+    }
+    signature = cache._sign_data(payload)
+    cache_path.write_text(
+        json.dumps({"v": cache._CACHE_VERSION, "payload": payload, "sig": signature}),
+        "utf-8",
+    )
+
+    cache.load()
+    entry = cache.get_file_entry("x.py")
+    assert entry is not None
+    assert entry["units"] == []
+    assert entry["blocks"] == []
+    assert entry["segments"] == []
+
+
+def test_cache_signature_validation_ignores_json_whitespace(tmp_path: Path) -> None:
+    cache_path = tmp_path / "cache.json"
+    cache = Cache(cache_path)
+    cache.put_file_entry("x.py", {"mtime_ns": 1, "size": 10}, [], [], [])
+    cache.save()
+
+    raw = json.loads(cache_path.read_text("utf-8"))
+    cache_path.write_text(json.dumps(raw, ensure_ascii=False, indent=2), "utf-8")
+
+    loaded = Cache(cache_path)
+    loaded.load()
+    assert loaded.load_warning is None
+    assert loaded.get_file_entry("x.py") is not None
 
 
 def test_cache_signature_mismatch_warns(tmp_path: Path) -> None:
@@ -76,15 +165,17 @@ def test_cache_signature_mismatch_warns(tmp_path: Path) -> None:
     cache.save()
 
     data = json.loads(cache_path.read_text("utf-8"))
-    data["_signature"] = "bad"
+    data["sig"] = "bad"
     cache_path.write_text(json.dumps(data), "utf-8")
 
     loaded = Cache(cache_path)
     loaded.load()
     assert loaded.load_warning is not None
     assert "signature" in loaded.load_warning
-    assert loaded.data["version"] == Cache.CACHE_VERSION
+    assert loaded.data["version"] == Cache._CACHE_VERSION
     assert loaded.data["files"] == {}
+    assert loaded.load_status == CacheStatus.INTEGRITY_FAILED
+    assert loaded.cache_schema_version == Cache._CACHE_VERSION
 
 
 def test_cache_version_mismatch_warns(tmp_path: Path) -> None:
@@ -101,20 +192,46 @@ def test_cache_version_mismatch_warns(tmp_path: Path) -> None:
     loaded.load()
     assert loaded.load_warning is not None
     assert "version" in loaded.load_warning
-    assert loaded.data["version"] == Cache.CACHE_VERSION
+    assert loaded.data["version"] == Cache._CACHE_VERSION
     assert loaded.data["files"] == {}
+    assert loaded.load_status == CacheStatus.VERSION_MISMATCH
+    assert loaded.cache_schema_version == "0.0"
+
+
+def test_cache_v_field_version_mismatch_warns(tmp_path: Path) -> None:
+    cache_path = tmp_path / "cache.json"
+    cache = Cache(cache_path)
+    payload = {
+        "py": cache.data["python_tag"],
+        "fp": cache.data["fingerprint_version"],
+        "files": {},
+    }
+    signature = cache._sign_data(payload)
+    cache_path.write_text(
+        json.dumps({"v": "0.0", "payload": payload, "sig": signature}), "utf-8"
+    )
+
+    loaded = Cache(cache_path)
+    loaded.load()
+    assert loaded.load_warning is not None
+    assert "version mismatch" in loaded.load_warning
+    assert loaded.data["files"] == {}
+    assert loaded.load_status == CacheStatus.VERSION_MISMATCH
+    assert loaded.cache_schema_version == "0.0"
 
 
 def test_cache_too_large_warns(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
     cache_path = tmp_path / "cache.json"
-    cache_path.write_text(json.dumps({"version": Cache.CACHE_VERSION, "files": {}}))
+    cache_path.write_text(json.dumps({"version": Cache._CACHE_VERSION, "files": {}}))
     monkeypatch.setattr(cache_mod, "MAX_CACHE_SIZE_BYTES", 1)
     cache = Cache(cache_path)
     cache.load()
     assert cache.load_warning is not None
     assert "too large" in cache.load_warning
-    assert cache.data["version"] == Cache.CACHE_VERSION
+    assert cache.data["version"] == Cache._CACHE_VERSION
     assert cache.data["files"] == {}
+    assert cache.load_status == CacheStatus.TOO_LARGE
+    assert cache.cache_schema_version is None
 
 
 def test_cache_entry_validation(tmp_path: Path) -> None:
@@ -329,6 +446,8 @@ def test_cache_load_missing_file(tmp_path: Path) -> None:
     cache = Cache(cache_path)
     cache.load()
     assert cache.load_warning is None
+    assert cache.load_status == CacheStatus.MISSING
+    assert cache.cache_schema_version is None
 
 
 def test_cache_entry_not_dict(tmp_path: Path) -> None:
@@ -338,6 +457,14 @@ def test_cache_entry_not_dict(tmp_path: Path) -> None:
     assert cache.get_file_entry("x.py") is None
 
 
+def test_file_stat_signature(tmp_path: Path) -> None:
+    file_path = tmp_path / "x.py"
+    file_path.write_text("print('x')\n", "utf-8")
+    stat = cache_mod.file_stat_signature(str(file_path))
+    assert stat["size"] == file_path.stat().st_size
+    assert isinstance(stat["mtime_ns"], int)
+
+
 def test_cache_load_corrupted_json(tmp_path: Path) -> None:
     cache_path = tmp_path / "cache.json"
     cache_path.write_text("{invalid json", "utf-8")
@@ -345,14 +472,71 @@ def test_cache_load_corrupted_json(tmp_path: Path) -> None:
     cache.load()
     assert cache.load_warning is not None
     assert "corrupted" in cache.load_warning
+    assert cache.load_status == CacheStatus.INVALID_JSON
+    assert cache.cache_schema_version is None
+
+
+def test_cache_load_unreadable_stat_graceful_ignore(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    cache_path = tmp_path / "cache.json"
+    cache_path.write_text('{"version":"1.0","files":{}}', "utf-8")
+    original_stat = Path.stat
+
+    def _raise_stat(self: Path, *args: object, **kwargs: object) -> os.stat_result:
+        if self == cache_path:
+            raise OSError("no stat")
+        return original_stat(self)
+
+    monkeypatch.setattr(Path, "stat", _raise_stat)
+    cache = Cache(cache_path)
+    cache.load()
+    assert cache.load_warning is not None
+    assert "unreadable" in cache.load_warning
+    assert cache.data["files"] == {}
+    assert cache.load_status == CacheStatus.UNREADABLE
+    assert cache.cache_schema_version is None
+
+
+def test_cache_load_unreadable_read_graceful_ignore(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    cache_path = tmp_path / "cache.json"
+    cache_path.write_text('{"version":"1.0","files":{}}', "utf-8")
+    original_read_text = Path.read_text
+
+    def _raise_read_text(
+        self: Path,
+        encoding: str | None = None,
+        errors: str | None = None,
+    ) -> str:
+        if self == cache_path:
+            raise OSError("no read")
+        return original_read_text(self, encoding=encoding, errors=errors)
+
+    monkeypatch.setattr(Path, "read_text", _raise_read_text)
+    cache = Cache(cache_path)
+    cache.load()
+    assert cache.load_warning is not None
+    assert "unreadable" in cache.load_warning
+    assert cache.data["files"] == {}
+    assert cache.load_status == CacheStatus.UNREADABLE
+    assert cache.cache_schema_version is None
 
 
 def test_cache_load_invalid_files_type(tmp_path: Path) -> None:
     cache_path = tmp_path / "cache.json"
     cache = Cache(cache_path)
-    data = {"version": cache.CACHE_VERSION, "files": []}
-    signature = cache._sign_data(data)
-    cache_path.write_text(json.dumps({**data, "_signature": signature}), "utf-8")
+    payload = {
+        "py": cache.data["python_tag"],
+        "fp": cache.data["fingerprint_version"],
+        "files": [],
+    }
+    signature = cache._sign_data(payload)
+    cache_path.write_text(
+        json.dumps({"v": cache._CACHE_VERSION, "payload": payload, "sig": signature}),
+        "utf-8",
+    )
     cache.load()
     assert cache.load_warning is not None
     assert "format" in cache.load_warning
@@ -371,7 +555,7 @@ def _raise_write_text(
         errors: str | None = None,
         newline: str | None = None,
     ) -> int:
-        if self == cache_path:
+        if self.name.endswith(".tmp"):
             raise OSError("nope")
         return original_write_text(
             self, data, encoding=encoding, errors=errors, newline=newline
@@ -383,55 +567,309 @@ def _raise_write_text(
         cache.save()
 
 
-def test_cache_secret_write_failure(
-    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+def test_cache_legacy_secret_warning_on_init(tmp_path: Path) -> None:
+    cache_path = tmp_path / "cache.json"
+    cache_path.parent.mkdir(parents=True, exist_ok=True)
+    legacy_secret = cache_path.parent / ".cache_secret"
+    legacy_secret.write_text("legacy", "utf-8")
+
+    cache = Cache(cache_path)
+    assert cache.load_warning is not None
+    assert "Legacy cache secret file detected" in cache.load_warning
+    assert "delete this obsolete file" in cache.load_warning
+
+
+def test_cache_legacy_secret_warning_preserved_after_successful_load(
+    tmp_path: Path,
 ) -> None:
     cache_path = tmp_path / "cache.json"
-    secret_path = cache_path.parent / ".cache_secret"
-    original_write_bytes = Path.write_bytes
+    cache_path.parent.mkdir(parents=True, exist_ok=True)
+    legacy_secret = cache_path.parent / ".cache_secret"
+    legacy_secret.write_text("legacy", "utf-8")
+    cache = Cache(cache_path)
+    cache.put_file_entry("x.py", {"mtime_ns": 1, "size": 10}, [], [], [])
+    cache.save()
 
-    def _raise_write_bytes(self: Path, data: bytes) -> int:
-        if self == secret_path:
-            raise OSError("nope")
-        return original_write_bytes(self, data)
+    loaded = Cache(cache_path)
+    loaded.load()
+    assert loaded.get_file_entry("x.py") is not None
+    assert loaded.load_warning is not None
+    assert "Legacy cache secret file detected" in loaded.load_warning
+
+
+def test_cache_legacy_secret_warning_combined_with_other_warning(
+    tmp_path: Path,
+) -> None:
+    cache_path = tmp_path / "cache.json"
+    cache_path.parent.mkdir(parents=True, exist_ok=True)
+    legacy_secret = cache_path.parent / ".cache_secret"
+    legacy_secret.write_text("legacy", "utf-8")
+    cache_path.write_text("{bad json", "utf-8")
 
-    monkeypatch.setattr(Path, "write_bytes", _raise_write_bytes)
     cache = Cache(cache_path)
-    assert isinstance(cache.secret, bytes)
-    assert len(cache.secret) == 32
+    cache.load()
+    assert cache.load_warning is not None
+    assert "Cache corrupted; ignoring cache." in cache.load_warning
+    assert "Legacy cache secret file detected" in cache.load_warning
 
 
-def test_cache_secret_chmod_failure(
+def test_cache_legacy_secret_check_oserror_sets_warning(
     tmp_path: Path, monkeypatch: pytest.MonkeyPatch
 ) -> None:
     cache_path = tmp_path / "cache.json"
     secret_path = cache_path.parent / ".cache_secret"
+    original_exists = Path.exists
 
-    original_write_bytes = Path.write_bytes
-    original_chmod = Path.chmod
+    def _exists_with_error(self: Path) -> bool:
+        if self == secret_path:
+            raise OSError("no access")
+        return original_exists(self)
 
-    def _write_bytes(self: Path, data: bytes) -> int:
-        return original_write_bytes(self, data)
+    monkeypatch.setattr(Path, "exists", _exists_with_error)
+    cache = Cache(cache_path)
+    assert cache.load_warning is not None
+    assert "Legacy cache secret check failed" in cache.load_warning
 
-    def _raise_chmod(self: Path, _mode: int) -> None:
-        if self == secret_path:
-            raise OSError("nope")
-        return original_chmod(self, _mode)
 
-    monkeypatch.setattr(Path, "write_bytes", _write_bytes)
-    monkeypatch.setattr(Path, "chmod", _raise_chmod)
-    monkeypatch.setattr(os, "name", "posix")
+def test_cache_load_invalid_top_level_type(tmp_path: Path) -> None:
+    cache_path = tmp_path / "cache.json"
+    cache_path.write_text("[]", "utf-8")
+    cache = Cache(cache_path)
+    cache.load()
+    assert cache.load_warning is not None
+    assert "format invalid" in cache.load_warning
+    assert cache.data["files"] == {}
+
+
+def test_cache_load_missing_v_field(tmp_path: Path) -> None:
+    cache_path = tmp_path / "cache.json"
+    cache = Cache(cache_path)
+    payload = {
+        "py": cache.data["python_tag"],
+        "fp": cache.data["fingerprint_version"],
+        "files": {},
+    }
+    sig = cache._sign_data(payload)
+    cache_path.write_text(json.dumps({"payload": payload, "sig": sig}), "utf-8")
+    cache.load()
+    assert cache.load_warning is not None
+    assert "format invalid" in cache.load_warning
+
+
+def test_cache_load_missing_payload_or_sig(tmp_path: Path) -> None:
+    cache_path = tmp_path / "cache.json"
+    cache = Cache(cache_path)
+    cache_path.write_text(
+        json.dumps({"v": cache._CACHE_VERSION, "payload": {}}), "utf-8"
+    )
+    cache.load()
+    assert cache.load_warning is not None
+    assert "format invalid" in cache.load_warning
+
+
+def test_cache_load_missing_python_tag_in_payload(tmp_path: Path) -> None:
+    cache_path = tmp_path / "cache.json"
+    cache = Cache(cache_path)
+    payload = {"fp": cache.data["fingerprint_version"], "files": {}}
+    sig = cache._sign_data(payload)
+    cache_path.write_text(
+        json.dumps({"v": cache._CACHE_VERSION, "payload": payload, "sig": sig}), "utf-8"
+    )
+    cache.load()
+    assert cache.load_warning is not None
+    assert "format invalid" in cache.load_warning
+
+
+def test_cache_load_python_tag_mismatch(tmp_path: Path) -> None:
+    cache_path = tmp_path / "cache.json"
+    cache = Cache(cache_path)
+    payload = {"py": "cp999", "fp": cache.data["fingerprint_version"], "files": {}}
+    sig = cache._sign_data(payload)
+    cache_path.write_text(
+        json.dumps({"v": cache._CACHE_VERSION, "payload": payload, "sig": sig}), "utf-8"
+    )
+    cache.load()
+    assert cache.load_warning is not None
+    assert "python tag mismatch" in cache.load_warning
+
 
+def test_cache_load_missing_fingerprint_version(tmp_path: Path) -> None:
+    cache_path = tmp_path / "cache.json"
     cache = Cache(cache_path)
-    assert isinstance(cache.secret, bytes)
+    payload = {"py": cache.data["python_tag"], "files": {}}
+    sig = cache._sign_data(payload)
+    cache_path.write_text(
+        json.dumps({"v": cache._CACHE_VERSION, "payload": payload, "sig": sig}), "utf-8"
+    )
+    cache.load()
+    assert cache.load_warning is not None
+    assert "format invalid" in cache.load_warning
 
 
-def test_cache_secret_non_posix(
+def test_cache_load_fingerprint_version_mismatch(tmp_path: Path) -> None:
+    cache_path = tmp_path / "cache.json"
+    cache = Cache(cache_path)
+    payload = {"py": cache.data["python_tag"], "fp": "old", "files": {}}
+    sig = cache._sign_data(payload)
+    cache_path.write_text(
+        json.dumps({"v": cache._CACHE_VERSION, "payload": payload, "sig": sig}), "utf-8"
+    )
+    cache.load()
+    assert cache.load_warning is not None
+    assert "fingerprint version mismatch" in cache.load_warning
+
+
+def test_cache_load_invalid_wire_file_entry(tmp_path: Path) -> None:
+    cache_path = tmp_path / "cache.json"
+    cache = Cache(cache_path)
+    payload = {
+        "py": cache.data["python_tag"],
+        "fp": cache.data["fingerprint_version"],
+        "files": {"x.py": {"st": "bad"}},
+    }
+    sig = cache._sign_data(payload)
+    cache_path.write_text(
+        json.dumps({"v": cache._CACHE_VERSION, "payload": payload, "sig": sig}), "utf-8"
+    )
+    cache.load()
+    assert cache.load_warning is not None
+    assert "format invalid" in cache.load_warning
+
+
+def test_cache_save_skips_none_entry_from_lookup(
     tmp_path: Path, monkeypatch: pytest.MonkeyPatch
 ) -> None:
     cache_path = tmp_path / "cache.json"
-    monkeypatch.setattr("codeclone.cache.OS_NAME", "nt")
     cache = Cache(cache_path)
-    secret_path = cache_path.parent / ".cache_secret"
-    assert secret_path.exists()
-    assert isinstance(cache.secret, bytes)
+    cache.data["files"]["x.py"] = cast(
+        Any,
+        {
+            "stat": {"mtime_ns": 1, "size": 1},
+            "units": [],
+            "blocks": [],
+            "segments": [],
+        },
+    )
+
+    def _always_none(_self: Cache, _path: str) -> None:
+        return None
+
+    monkeypatch.setattr(Cache, "get_file_entry", _always_none)
+    cache.save()
+    raw = json.loads(cache_path.read_text("utf-8"))
+    payload = cast(dict[str, object], raw["payload"])
+    files = cast(dict[str, object], payload["files"])
+    assert files == {}
+
+
+def test_wire_filepath_outside_root_falls_back_to_runtime_path(tmp_path: Path) -> None:
+    root = tmp_path / "project"
+    root.mkdir()
+    cache = Cache(tmp_path / "cache.json", root=root)
+    outside = tmp_path / "outside.py"
+    assert cache._wire_filepath_from_runtime(str(outside)) == outside.as_posix()
+
+
+def test_wire_filepath_resolve_oserror_falls_back_to_runtime_path(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    root = tmp_path / "project"
+    root.mkdir()
+    runtime = tmp_path / "outside.py"
+    cache = Cache(tmp_path / "cache.json", root=root)
+    original_resolve = Path.resolve
+
+    def _resolve_with_error(self: Path, *, strict: bool = False) -> Path:
+        if self == runtime:
+            raise OSError("resolve failed")
+        return original_resolve(self, strict=strict)
+
+    monkeypatch.setattr(Path, "resolve", _resolve_with_error)
+    assert cache._wire_filepath_from_runtime(str(runtime)) == runtime.as_posix()
+
+
+def test_wire_filepath_resolve_relative_success_path(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    root = tmp_path / "project"
+    root.mkdir()
+    runtime = tmp_path / "outside.py"
+    cache = Cache(tmp_path / "cache.json", root=root)
+    original_resolve = Path.resolve
+    resolved_runtime = root / "pkg" / "module.py"
+
+    def _resolve_with_mapping(self: Path, *, strict: bool = False) -> Path:
+        if self == runtime:
+            return resolved_runtime
+        if self == root:
+            return root
+        return original_resolve(self, strict=strict)
+
+    monkeypatch.setattr(Path, "resolve", _resolve_with_mapping)
+    assert cache._wire_filepath_from_runtime(str(runtime)) == "pkg/module.py"
+
+
+def test_runtime_filepath_from_wire_resolve_oserror(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    root = tmp_path / "project"
+    root.mkdir()
+    cache = Cache(tmp_path / "cache.json", root=root)
+    original_resolve = Path.resolve
+    combined = root / "pkg" / "module.py"
+
+    def _resolve_with_error(self: Path, *, strict: bool = False) -> Path:
+        if self == combined:
+            raise OSError("resolve failed")
+        return original_resolve(self, strict=strict)
+
+    monkeypatch.setattr(Path, "resolve", _resolve_with_error)
+    assert cache._runtime_filepath_from_wire("pkg/module.py") == str(combined)
+
+
+def test_as_str_dict_rejects_non_string_keys() -> None:
+    assert cache_mod._as_str_dict({1: "x"}) is None
+
+
+@pytest.mark.parametrize(
+    ("entry", "filepath"),
+    [
+        ("bad", "x.py"),
+        ({"st": "bad"}, "x.py"),
+        ({"st": [1]}, "x.py"),
+        ({"st": [1, "2"]}, "x.py"),
+        ({"st": [1, 2], "u": "bad"}, "x.py"),
+        ({"st": [1, 2], "u": [["q", 1, 2, 3, 4, "fp"]]}, "x.py"),
+        ({"st": [1, 2], "b": "bad"}, "x.py"),
+        ({"st": [1, 2], "b": [["q", 1, 2, 3]]}, "x.py"),
+        ({"st": [1, 2], "s": "bad"}, "x.py"),
+        ({"st": [1, 2], "s": [["q", 1, 2, 3, "h"]]}, "x.py"),
+    ],
+)
+def test_decode_wire_file_entry_invalid_variants(entry: object, filepath: str) -> None:
+    assert cache_mod._decode_wire_file_entry(entry, filepath) is None
+
+
+def test_decode_wire_item_type_failures() -> None:
+    assert cache_mod._decode_wire_unit(["q", 1, 2, 3, 4, "fp"], "x.py") is None
+    assert (
+        cache_mod._decode_wire_unit(["q", "1", 2, 3, 4, "fp", "0-19"], "x.py") is None
+    )
+    assert cache_mod._decode_wire_block(["q", 1, 2, 3], "x.py") is None
+    assert cache_mod._decode_wire_block(["q", 1, 2, "4", "hash"], "x.py") is None
+    assert cache_mod._decode_wire_segment(["q", 1, 2, 3, "h"], "x.py") is None
+    assert cache_mod._decode_wire_segment(["q", 1, 2, "3", "h", "sig"], "x.py") is None
+
+
+def test_resolve_root_oserror_returns_none(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    original_resolve = Path.resolve
+
+    def _resolve_with_error(self: Path, *, strict: bool = False) -> Path:
+        if self == tmp_path:
+            raise OSError("resolve failed")
+        return original_resolve(self, strict=strict)
+
+    monkeypatch.setattr(Path, "resolve", _resolve_with_error)
+    assert cache_mod._resolve_root(tmp_path) is None
diff --git a/tests/test_cli_inprocess.py b/tests/test_cli_inprocess.py
index e49a232..2573843 100644
--- a/tests/test_cli_inprocess.py
+++ b/tests/test_cli_inprocess.py
@@ -1,6 +1,5 @@
 from __future__ import annotations
 
-import hashlib
 import json
 import re
 import sys
@@ -13,8 +12,13 @@
 
 import codeclone.baseline as baseline
 from codeclone import __version__, cli
-from codeclone.baseline import BASELINE_SCHEMA_VERSION
 from codeclone.cache import Cache, file_stat_signature
+from codeclone.contracts import (
+    BASELINE_FINGERPRINT_VERSION,
+    BASELINE_SCHEMA_VERSION,
+    CACHE_VERSION,
+    REPORT_SCHEMA_VERSION,
+)
 from codeclone.errors import CacheError
 
 
@@ -141,35 +145,72 @@ def _baseline_payload(
     functions: list[str] | None = None,
     blocks: list[str] | None = None,
     python_version: str | None = None,
+    python_tag: str | None = None,
+    fingerprint_version: str | None = None,
     baseline_version: str | None = None,
-    schema_version: int | None = None,
+    schema_version: object | None = None,
     include_version_schema: bool = True,
     generator: str | None = "codeclone",
+    generator_version: str | None = None,
     payload_sha256: str | None = None,
 ) -> dict[str, object]:
-    function_list = [] if functions is None else functions
-    block_list = [] if blocks is None else blocks
-    payload: dict[str, object] = {"functions": function_list, "blocks": block_list}
-    if python_version is not None:
-        payload["python_version"] = python_version
+    function_list = sorted([] if functions is None else functions)
+    block_list = sorted([] if blocks is None else blocks)
     if include_version_schema:
-        payload["baseline_version"] = baseline_version or __version__
-        payload["schema_version"] = (
+        meta_fingerprint = (
+            fingerprint_version or baseline_version or BASELINE_FINGERPRINT_VERSION
+        )
+        meta_schema = (
             BASELINE_SCHEMA_VERSION if schema_version is None else schema_version
         )
-    if generator is not None:
-        payload["generator"] = generator
-    canonical = json.dumps(
-        {"functions": function_list, "blocks": block_list},
-        sort_keys=True,
-        separators=(",", ":"),
-        ensure_ascii=False,
-    )
-    payload["payload_sha256"] = (
-        payload_sha256
-        if payload_sha256 is not None
-        else hashlib.sha256(canonical.encode("utf-8")).hexdigest()
-    )
+        default_tag = baseline.current_python_tag()
+        version_suffix = f"{sys.version_info.major}{sys.version_info.minor}"
+        prefix = default_tag.removesuffix(version_suffix)
+        version_tag: str | None = None
+        if python_version:
+            ver_match = re.fullmatch(r"(\d+)\.(\d+)(?:\.\d+)?", python_version.strip())
+            if ver_match:
+                version_tag = f"{prefix}{ver_match.group(1)}{ver_match.group(2)}"
+        meta_python_tag = python_tag or version_tag or default_tag
+        meta_generator_version = generator_version or __version__
+
+        hash_value: str | None
+        if (
+            isinstance(meta_fingerprint, str)
+            and isinstance(meta_schema, str)
+            and isinstance(meta_python_tag, str)
+            and payload_sha256 is None
+        ):
+            hash_value = baseline._compute_payload_sha256(
+                functions=set(function_list),
+                blocks=set(block_list),
+                fingerprint_version=meta_fingerprint,
+                python_tag=meta_python_tag,
+            )
+        else:
+            hash_value = payload_sha256
+
+        meta: dict[str, object] = {
+            "generator": {
+                "name": generator if generator is not None else "codeclone",
+                "version": meta_generator_version,
+            },
+            "schema_version": meta_schema,
+            "fingerprint_version": meta_fingerprint,
+            "python_tag": meta_python_tag,
+            "created_at": "2026-02-08T11:43:16Z",
+            "payload_sha256": hash_value if hash_value is not None else "x" * 64,
+        }
+        return {
+            "meta": meta,
+            "clones": {"functions": function_list, "blocks": block_list},
+        }
+
+    payload: dict[str, object] = {"functions": function_list, "blocks": block_list}
+    if baseline_version is not None:
+        payload["baseline_version"] = baseline_version
+    if schema_version is not None:
+        payload["schema_version"] = schema_version
     return payload
 
 
@@ -179,10 +220,13 @@ def _write_baseline(
     functions: list[str] | None = None,
     blocks: list[str] | None = None,
     python_version: str | None = None,
+    python_tag: str | None = None,
+    fingerprint_version: str | None = None,
     baseline_version: str | None = None,
-    schema_version: int | None = None,
+    schema_version: object | None = None,
     include_version_schema: bool = True,
     generator: str | None = "codeclone",
+    generator_version: str | None = None,
     payload_sha256: str | None = None,
 ) -> Path:
     path.write_text(
@@ -191,10 +235,13 @@ def _write_baseline(
                 functions=functions,
                 blocks=blocks,
                 python_version=python_version,
+                python_tag=python_tag,
+                fingerprint_version=fingerprint_version,
                 baseline_version=baseline_version,
                 schema_version=schema_version,
                 include_version_schema=include_version_schema,
                 generator=generator,
+                generator_version=generator_version,
                 payload_sha256=payload_sha256,
             )
         ),
@@ -241,8 +288,12 @@ def _assert_baseline_failure_meta(
         _run_main(monkeypatch, args)
     out = capsys.readouterr().out
     assert expected_message in out
-    if not strict_fail:
+    if strict_fail:
+        assert "CI requires a trusted baseline" in out
+        assert "Run: codeclone . --update-baseline" in out
+    else:
         assert "Baseline is not trusted for this run and will be ignored" in out
+        assert "Run: codeclone . --update-baseline" in out
     payload_out = json.loads(json_out.read_text("utf-8"))
     meta = payload_out["meta"]
     assert meta["baseline_status"] == expected_status
@@ -272,6 +323,41 @@ def _compact_summary_metric(out: str, key: str) -> int:
     return int(match.group(1))
 
 
+def _current_py_minor() -> str:
+    return f"{sys.version_info.major}.{sys.version_info.minor}"
+
+
+def _prepare_source_and_baseline(tmp_path: Path) -> tuple[Path, Path]:
+    src = tmp_path / "a.py"
+    src.write_text("def f():\n    return 1\n", "utf-8")
+    baseline_path = _write_baseline(
+        tmp_path / "baseline.json",
+        python_version=_current_py_minor(),
+    )
+    return src, baseline_path
+
+
+def _prepare_single_source_cache(tmp_path: Path) -> tuple[Path, Path, Cache]:
+    src = tmp_path / "a.py"
+    src.write_text("def f():\n    return 1\n", "utf-8")
+    cache_path = tmp_path / "cache.json"
+    return src, cache_path, Cache(cache_path)
+
+
+def _source_read_error_result(filepath: str) -> cli.ProcessingResult:
+    return cli.ProcessingResult(
+        filepath=filepath,
+        success=False,
+        error="Cannot read file: [Errno 13] Permission denied",
+        error_kind="source_read_error",
+    )
+
+
+def _assert_unreadable_source_contract_error(out: str) -> None:
+    assert "CONTRACT ERROR:" in out
+    assert "could not be read in CI/gating mode" in out
+
+
 def test_cli_main_no_progress_parallel(
     tmp_path: Path,
     monkeypatch: pytest.MonkeyPatch,
@@ -605,6 +691,61 @@ def save(self) -> None:
     assert "Legacy cache file found at" not in out
 
 
+@pytest.mark.parametrize(
+    ("load_warning", "expected_status"),
+    [(None, "ok"), ("bad cache", "invalid_type")],
+)
+def test_cli_cache_status_string_fallback(
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+    load_warning: str | None,
+    expected_status: str,
+) -> None:
+    _src, baseline_path = _prepare_source_and_baseline(tmp_path)
+    json_out = tmp_path / "report.json"
+
+    class _CacheStub:
+        def __init__(self, _path: Path, **_kwargs: object) -> None:
+            self.load_warning = load_warning
+            self.load_status = "not-a-cache-status"
+            self.cache_schema_version = "1.2"
+
+        def load(self) -> None:
+            return None
+
+        def get_file_entry(self, _fp: str) -> None:
+            return None
+
+        def put_file_entry(
+            self,
+            _fp: str,
+            _stat: object,
+            _units: object,
+            _blocks: object,
+            _segments: object,
+        ) -> None:
+            return None
+
+        def save(self) -> None:
+            return None
+
+    monkeypatch.setattr(cli, "Cache", _CacheStub)
+    _patch_parallel(monkeypatch)
+    _run_main(
+        monkeypatch,
+        [
+            str(tmp_path),
+            "--baseline",
+            str(baseline_path),
+            "--json",
+            str(json_out),
+            "--no-progress",
+        ],
+    )
+    payload = json.loads(json_out.read_text("utf-8"))
+    assert payload["meta"]["cache_status"] == expected_status
+
+
 def test_cli_main_progress_fallback(
     tmp_path: Path,
     monkeypatch: pytest.MonkeyPatch,
@@ -673,7 +814,61 @@ def _boom(self: Path) -> Path:
     monkeypatch.setattr(Path, "resolve", _boom)
     with pytest.raises(SystemExit) as exc:
         _run_main(monkeypatch, ["bad"])
-    assert exc.value.code == 1
+    assert exc.value.code == 2
+
+
+def test_cli_unexpected_root_resolution_failure_is_internal(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+) -> None:
+    def _boom(self: Path) -> Path:
+        raise RuntimeError("boom")
+
+    monkeypatch.setattr(Path, "resolve", _boom)
+    with pytest.raises(SystemExit) as exc:
+        _run_main(monkeypatch, ["bad"])
+    assert exc.value.code == 5
+    out = capsys.readouterr().out
+    assert "INTERNAL ERROR:" in out
+
+
+def test_cli_unexpected_grouping_failure_is_internal(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+) -> None:
+    src = tmp_path / "a.py"
+    src.write_text("def f():\n    return 1\n", "utf-8")
+
+    def _boom(*_args: object, **_kwargs: object) -> object:
+        raise RuntimeError("boom")
+
+    _patch_parallel(monkeypatch)
+    monkeypatch.setattr(cli, "build_groups", _boom)
+    with pytest.raises(SystemExit) as exc:
+        _run_main(monkeypatch, [str(tmp_path), "--no-progress"])
+    assert exc.value.code == 5
+    out = capsys.readouterr().out
+    assert "INTERNAL ERROR:" in out
+
+
+def test_cli_unexpected_html_render_failure_is_internal(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+) -> None:
+    src = tmp_path / "a.py"
+    src.write_text("def f():\n    return 1\n", "utf-8")
+    html_out = tmp_path / "report.html"
+
+    def _boom(*_args: object, **_kwargs: object) -> str:
+        raise RuntimeError("render failed")
+
+    _patch_parallel(monkeypatch)
+    monkeypatch.setattr(cli, "build_html_report", _boom)
+    with pytest.raises(SystemExit) as exc:
+        _run_main(
+            monkeypatch,
+            [str(tmp_path), "--html", str(html_out), "--no-progress"],
+        )
+    assert exc.value.code == 5
+    out = capsys.readouterr().out
+    assert "INTERNAL ERROR:" in out
 
 
 def test_cli_main_outputs(
@@ -718,12 +913,7 @@ def test_cli_main_outputs(
 def test_cli_reports_include_audit_metadata_ok(
     tmp_path: Path, monkeypatch: pytest.MonkeyPatch
 ) -> None:
-    src = tmp_path / "a.py"
-    src.write_text("def f():\n    return 1\n", "utf-8")
-    baseline_path = _write_baseline(
-        tmp_path / "baseline.json",
-        python_version=f"{sys.version_info.major}.{sys.version_info.minor}",
-    )
+    _src, baseline_path = _prepare_source_and_baseline(tmp_path)
     html_out = tmp_path / "report.html"
     json_out = tmp_path / "report.json"
     text_out = tmp_path / "report.txt"
@@ -748,12 +938,18 @@ def test_cli_reports_include_audit_metadata_ok(
     meta = payload["meta"]
     assert meta["baseline_status"] == "ok"
     assert meta["baseline_loaded"] is True
-    assert meta["baseline_version"] == __version__
+    assert meta["baseline_fingerprint_version"] == BASELINE_FINGERPRINT_VERSION
     assert meta["baseline_schema_version"] == BASELINE_SCHEMA_VERSION
+    assert meta["baseline_generator_version"] == __version__
+    assert isinstance(meta["baseline_payload_sha256"], str)
+    assert meta["baseline_payload_sha256_verified"] is True
     assert meta["baseline_path"] == str(baseline_path.resolve())
-    assert "function_clones" in payload
-    assert "block_clones" in payload
-    assert "segment_clones" in payload
+    assert payload["meta"]["report_schema_version"] == REPORT_SCHEMA_VERSION
+    assert "files" in payload
+    assert "groups" in payload
+    assert "group_item_layout" in payload
+    assert set(payload["groups"]) == {"functions", "blocks", "segments"}
+    assert set(payload["group_item_layout"]) == {"functions", "blocks", "segments"}
 
     text = text_out.read_text("utf-8")
     assert "REPORT METADATA" in text
@@ -763,6 +959,7 @@ def test_cli_reports_include_audit_metadata_ok(
     html = html_out.read_text("utf-8")
     assert "Report Provenance" in html
     assert 'data-baseline-status="ok"' in html
+    assert 'data-baseline-payload-verified="true"' in html
     assert "Baseline schema" in html
 
 
@@ -788,11 +985,13 @@ def test_cli_reports_include_audit_metadata_missing_baseline(
     meta = payload["meta"]
     assert meta["baseline_status"] == "missing"
     assert meta["baseline_loaded"] is False
-    assert meta["baseline_version"] is None
+    assert meta["baseline_fingerprint_version"] is None
     assert meta["baseline_schema_version"] is None
+    assert meta["baseline_payload_sha256"] is None
+    assert meta["baseline_payload_sha256_verified"] is False
 
 
-def test_cli_reports_include_audit_metadata_version_mismatch(
+def test_cli_reports_include_audit_metadata_fingerprint_mismatch(
     tmp_path: Path,
     monkeypatch: pytest.MonkeyPatch,
     capsys: pytest.CaptureFixture[str],
@@ -806,26 +1005,24 @@ def test_cli_reports_include_audit_metadata_version_mismatch(
     )
     json_out = tmp_path / "report.json"
     _patch_parallel(monkeypatch)
-    with pytest.raises(SystemExit) as exc:
-        _run_main(
-            monkeypatch,
-            [
-                str(tmp_path),
-                "--baseline",
-                str(baseline_path),
-                "--json",
-                str(json_out),
-                "--no-progress",
-            ],
-        )
-    assert exc.value.code == 2
+    _run_main(
+        monkeypatch,
+        [
+            str(tmp_path),
+            "--baseline",
+            str(baseline_path),
+            "--json",
+            str(json_out),
+            "--no-progress",
+        ],
+    )
     out = capsys.readouterr().out
-    assert "Baseline version mismatch" in out
+    assert "fingerprint version mismatch" in out
     payload = json.loads(json_out.read_text("utf-8"))
     meta = payload["meta"]
-    assert meta["baseline_status"] == "mismatch_version"
-    assert meta["baseline_loaded"] is True
-    assert meta["baseline_version"] == "0.0.0"
+    assert meta["baseline_status"] == "mismatch_fingerprint_version"
+    assert meta["baseline_loaded"] is False
+    assert meta["baseline_fingerprint_version"] == "0.0.0"
 
 
 def test_cli_reports_include_audit_metadata_schema_mismatch(
@@ -838,30 +1035,28 @@ def test_cli_reports_include_audit_metadata_schema_mismatch(
     baseline_path = _write_baseline(
         tmp_path / "baseline.json",
         python_version=f"{sys.version_info.major}.{sys.version_info.minor}",
-        schema_version=999,
+        schema_version="1.1",
     )
     json_out = tmp_path / "report.json"
     _patch_parallel(monkeypatch)
-    with pytest.raises(SystemExit) as exc:
-        _run_main(
-            monkeypatch,
-            [
-                str(tmp_path),
-                "--baseline",
-                str(baseline_path),
-                "--json",
-                str(json_out),
-                "--no-progress",
-            ],
-        )
-    assert exc.value.code == 2
+    _run_main(
+        monkeypatch,
+        [
+            str(tmp_path),
+            "--baseline",
+            str(baseline_path),
+            "--json",
+            str(json_out),
+            "--no-progress",
+        ],
+    )
     out = capsys.readouterr().out
-    assert "Baseline schema version mismatch" in out
+    assert "schema version is newer than supported" in out
     payload = json.loads(json_out.read_text("utf-8"))
     meta = payload["meta"]
-    assert meta["baseline_status"] == "mismatch_schema"
-    assert meta["baseline_loaded"] is True
-    assert meta["baseline_schema_version"] == 999
+    assert meta["baseline_status"] == "mismatch_schema_version"
+    assert meta["baseline_loaded"] is False
+    assert meta["baseline_schema_version"] == "1.1"
 
 
 def test_cli_reports_include_audit_metadata_python_mismatch(
@@ -892,13 +1087,12 @@ def test_cli_reports_include_audit_metadata_python_mismatch(
         )
     assert exc.value.code == 2
     out = capsys.readouterr().out
-    assert "Baseline Python version mismatch" in out
-    assert "Baseline checks require the same Python version" in out
+    assert "python tag mismatch" in out
     payload = json.loads(json_out.read_text("utf-8"))
     meta = payload["meta"]
-    assert meta["baseline_status"] == "mismatch_python"
-    assert meta["baseline_loaded"] is True
-    assert meta["baseline_python_version"] == "0.0"
+    assert meta["baseline_status"] == "mismatch_python_version"
+    assert meta["baseline_loaded"] is False
+    assert meta["baseline_python_tag"] == "cp00"
 
 
 def test_cli_reports_include_audit_metadata_invalid_baseline(
@@ -928,7 +1122,7 @@ def test_cli_reports_include_audit_metadata_invalid_baseline(
     assert "Baseline is not trusted for this run and will be ignored" in out
     payload = json.loads(json_out.read_text("utf-8"))
     meta = payload["meta"]
-    assert meta["baseline_status"] == "invalid"
+    assert meta["baseline_status"] == "invalid_json"
     assert meta["baseline_loaded"] is False
 
 
@@ -941,49 +1135,16 @@ def test_cli_reports_include_audit_metadata_legacy_baseline(
     src.write_text("def f():\n    return 1\n", "utf-8")
     baseline_path = tmp_path / "baseline.json"
     baseline_path.write_text(
-        json.dumps({"functions": [], "blocks": [], "python_version": "3.13"}),
+        json.dumps(
+            {
+                "functions": [],
+                "blocks": [],
+                "python_version": "3.13",
+                "schema_version": BASELINE_SCHEMA_VERSION,
+            }
+        ),
         "utf-8",
     )
-    json_out = tmp_path / "report.json"
-    _patch_parallel(monkeypatch)
-    with pytest.raises(SystemExit) as exc:
-        _run_main(
-            monkeypatch,
-            [
-                str(tmp_path),
-                "--baseline",
-                str(baseline_path),
-                "--json",
-                str(json_out),
-                "--no-progress",
-            ],
-        )
-    assert exc.value.code == 2
-    out = capsys.readouterr().out
-    assert "legacy baseline format" in out
-    assert "payload_sha256" not in out
-    payload = json.loads(json_out.read_text("utf-8"))
-    meta = payload["meta"]
-    assert meta["baseline_status"] == "legacy"
-    assert meta["baseline_loaded"] is True
-
-
-def test_cli_reports_include_audit_metadata_integrity_failed(
-    tmp_path: Path,
-    monkeypatch: pytest.MonkeyPatch,
-    capsys: pytest.CaptureFixture[str],
-) -> None:
-    src = tmp_path / "a.py"
-    src.write_text("def f():\n    return 1\n", "utf-8")
-    baseline_path = _write_baseline(
-        tmp_path / "baseline.json",
-        python_version=f"{sys.version_info.major}.{sys.version_info.minor}",
-        functions=["f1"],
-    )
-    tampered = json.loads(baseline_path.read_text("utf-8"))
-    tampered["functions"] = ["tampered"]
-    baseline_path.write_text(json.dumps(tampered), "utf-8")
-
     json_out = tmp_path / "report.json"
     _patch_parallel(monkeypatch)
     _run_main(
@@ -998,27 +1159,36 @@ def test_cli_reports_include_audit_metadata_integrity_failed(
         ],
     )
     out = capsys.readouterr().out
-    assert "integrity check failed" in out
-    assert "Baseline is not trusted for this run and will be ignored" in out
+    assert "legacy" in out
     payload = json.loads(json_out.read_text("utf-8"))
     meta = payload["meta"]
-    assert meta["baseline_status"] == "integrity_failed"
+    assert meta["baseline_status"] == "missing_fields"
     assert meta["baseline_loaded"] is False
 
 
-def test_cli_reports_include_audit_metadata_generator_mismatch(
+def test_cli_legacy_baseline_normal_mode_ignored_and_exit_zero(
     tmp_path: Path,
     monkeypatch: pytest.MonkeyPatch,
     capsys: pytest.CaptureFixture[str],
 ) -> None:
     src = tmp_path / "a.py"
-    src.write_text("def f():\n    return 1\n", "utf-8")
-    baseline_path = _write_baseline(
-        tmp_path / "baseline.json",
-        python_version=f"{sys.version_info.major}.{sys.version_info.minor}",
-        generator="not-codeclone",
+    src.write_text(
+        "def f():\n    return 1\n\n\ndef g():\n    return 1\n",
+        "utf-8",
     )
-    json_out = tmp_path / "report.json"
+    baseline_path = tmp_path / "baseline.json"
+    baseline_path.write_text(
+        json.dumps(
+            {
+                "functions": [],
+                "blocks": [],
+                "python_version": "3.13",
+                "schema_version": BASELINE_SCHEMA_VERSION,
+            }
+        ),
+        "utf-8",
+    )
+
     _patch_parallel(monkeypatch)
     _run_main(
         monkeypatch,
@@ -1026,29 +1196,143 @@ def test_cli_reports_include_audit_metadata_generator_mismatch(
             str(tmp_path),
             "--baseline",
             str(baseline_path),
-            "--json",
-            str(json_out),
+            "--min-loc",
+            "1",
+            "--min-stmt",
+            "1",
             "--no-progress",
+            "--no-color",
         ],
     )
     out = capsys.readouterr().out
-    assert "generator mismatch" in out
+    assert "legacy (<=1.3.x)" in out
     assert "Baseline is not trusted for this run and will be ignored" in out
-    payload = json.loads(json_out.read_text("utf-8"))
-    meta = payload["meta"]
-    assert meta["baseline_status"] == "generator_mismatch"
-    assert meta["baseline_loaded"] is False
+    assert "Comparison will proceed against an empty baseline" in out
+    assert "Run: codeclone . --update-baseline" in out
+    assert "New clones detected but --fail-on-new not set." in out
 
 
-@pytest.mark.parametrize(
-    ("field", "bad_value", "expected_message", "expected_status"),
-    [
-        ("generator", 123, "generator mismatch", "generator_mismatch"),
-        (
-            "payload_sha256",
+def test_cli_legacy_baseline_fail_on_new_fails_fast_exit_2(
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+    capsys: pytest.CaptureFixture[str],
+) -> None:
+    src = tmp_path / "a.py"
+    src.write_text("def f():\n    return 1\n", "utf-8")
+    baseline_path = tmp_path / "baseline.json"
+    baseline_path.write_text(
+        json.dumps(
+            {
+                "functions": [],
+                "blocks": [],
+                "python_version": "3.13",
+                "schema_version": BASELINE_SCHEMA_VERSION,
+            }
+        ),
+        "utf-8",
+    )
+    _patch_parallel(monkeypatch)
+    with pytest.raises(SystemExit) as exc:
+        _run_main(
+            monkeypatch,
+            [
+                str(tmp_path),
+                "--baseline",
+                str(baseline_path),
+                "--fail-on-new",
+                "--no-progress",
+            ],
+        )
+    assert exc.value.code == 2
+    out = capsys.readouterr().out
+    assert "legacy (<=1.3.x)" in out
+    assert "Invalid baseline file" in out
+    assert "CI requires a trusted baseline" in out
+    assert "Run: codeclone . --update-baseline" in out
+
+
+def test_cli_reports_include_audit_metadata_integrity_failed(
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+    capsys: pytest.CaptureFixture[str],
+) -> None:
+    src = tmp_path / "a.py"
+    src.write_text("def f():\n    return 1\n", "utf-8")
+    baseline_path = _write_baseline(
+        tmp_path / "baseline.json",
+        python_version=f"{sys.version_info.major}.{sys.version_info.minor}",
+    )
+    tampered = json.loads(baseline_path.read_text("utf-8"))
+    clones = tampered["clones"]
+    assert isinstance(clones, dict)
+    clones["functions"] = [f"{'a' * 40}|0-19"]
+    baseline_path.write_text(json.dumps(tampered), "utf-8")
+
+    json_out = tmp_path / "report.json"
+    _patch_parallel(monkeypatch)
+    _run_main(
+        monkeypatch,
+        [
+            str(tmp_path),
+            "--baseline",
+            str(baseline_path),
+            "--json",
+            str(json_out),
+            "--no-progress",
+        ],
+    )
+    out = capsys.readouterr().out
+    assert "integrity check failed" in out
+    assert "Baseline is not trusted for this run and will be ignored" in out
+    payload = json.loads(json_out.read_text("utf-8"))
+    meta = payload["meta"]
+    assert meta["baseline_status"] == "integrity_failed"
+    assert meta["baseline_loaded"] is False
+
+
+def test_cli_reports_include_audit_metadata_generator_mismatch(
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+    capsys: pytest.CaptureFixture[str],
+) -> None:
+    src = tmp_path / "a.py"
+    src.write_text("def f():\n    return 1\n", "utf-8")
+    baseline_path = _write_baseline(
+        tmp_path / "baseline.json",
+        python_version=f"{sys.version_info.major}.{sys.version_info.minor}",
+        generator="not-codeclone",
+    )
+    json_out = tmp_path / "report.json"
+    _patch_parallel(monkeypatch)
+    _run_main(
+        monkeypatch,
+        [
+            str(tmp_path),
+            "--baseline",
+            str(baseline_path),
+            "--json",
+            str(json_out),
+            "--no-progress",
+        ],
+    )
+    out = capsys.readouterr().out
+    assert "generator mismatch" in out
+    assert "Baseline is not trusted for this run and will be ignored" in out
+    payload = json.loads(json_out.read_text("utf-8"))
+    meta = payload["meta"]
+    assert meta["baseline_status"] == "generator_mismatch"
+    assert meta["baseline_loaded"] is False
+
+
+@pytest.mark.parametrize(
+    ("field", "bad_value", "expected_message", "expected_status"),
+    [
+        ("generator", 123, "'generator' must be string", "invalid_type"),
+        (
+            "payload_sha256",
             1,
-            "integrity payload hash is missing",
-            "integrity_missing",
+            "'payload_sha256' must be string",
+            "invalid_type",
         ),
     ],
 )
@@ -1061,11 +1345,16 @@ def test_cli_reports_include_audit_metadata_integrity_field_type_errors(
     expected_message: str,
     expected_status: str,
 ) -> None:
+    def _mutate(payload: dict[str, object]) -> None:
+        meta = payload.get("meta")
+        assert isinstance(meta, dict)
+        meta[field] = bad_value
+
     _assert_baseline_failure_meta(
         tmp_path=tmp_path,
         monkeypatch=monkeypatch,
         capsys=capsys,
-        mutate_payload=lambda payload: payload.__setitem__(field, bad_value),
+        mutate_payload=_mutate,
         expected_message=expected_message,
         expected_status=expected_status,
     )
@@ -1082,7 +1371,9 @@ def test_cli_reports_include_audit_metadata_integrity_missing(
     payload = _baseline_payload(
         python_version=f"{sys.version_info.major}.{sys.version_info.minor}",
     )
-    del payload["payload_sha256"]
+    meta = payload["meta"]
+    assert isinstance(meta, dict)
+    del meta["payload_sha256"]
     baseline_path.write_text(json.dumps(payload), "utf-8")
     json_out = tmp_path / "report.json"
     _patch_parallel(monkeypatch)
@@ -1098,11 +1389,11 @@ def test_cli_reports_include_audit_metadata_integrity_missing(
         ],
     )
     out = capsys.readouterr().out
-    assert "integrity payload hash is missing" in out
+    assert "missing required fields" in out
     assert "Baseline is not trusted for this run and will be ignored" in out
     payload_out = json.loads(json_out.read_text("utf-8"))
     meta = payload_out["meta"]
-    assert meta["baseline_status"] == "integrity_missing"
+    assert meta["baseline_status"] == "missing_fields"
     assert meta["baseline_loaded"] is False
 
 
@@ -1173,7 +1464,9 @@ def f2():
     capsys.readouterr()
 
     payload = json.loads(baseline_path.read_text("utf-8"))
-    payload["generator"] = "not-codeclone"
+    meta = payload["meta"]
+    assert isinstance(meta, dict)
+    meta["generator"] = "not-codeclone"
     baseline_path.write_text(json.dumps(payload), "utf-8")
     json_out = tmp_path / "report.json"
     _run_main(
@@ -1205,15 +1498,15 @@ def f2():
         ("generator", "not-codeclone", "generator mismatch", "generator_mismatch"),
         (
             "payload_sha256",
-            "00",
+            "0" * 64,
             "integrity check failed",
             "integrity_failed",
         ),
         (
             "payload_sha256",
             None,
-            "integrity payload hash is missing",
-            "integrity_missing",
+            "missing required fields",
+            "missing_fields",
         ),
     ],
 )
@@ -1227,10 +1520,12 @@ def test_cli_untrusted_baseline_fails_in_ci(
     expected_status: str,
 ) -> None:
     def _mutate(payload: dict[str, object]) -> None:
+        meta = payload["meta"]
+        assert isinstance(meta, dict)
         if bad_value is None:
-            payload.pop(field, None)
+            meta.pop(field, None)
         else:
-            payload[field] = bad_value
+            meta[field] = bad_value
 
     _assert_baseline_failure_meta(
         tmp_path=tmp_path,
@@ -1271,7 +1566,7 @@ def test_cli_invalid_baseline_fails_in_ci(
     out = capsys.readouterr().out
     assert "Invalid baseline file" in out
     payload = json.loads(json_out.read_text("utf-8"))
-    assert payload["meta"]["baseline_status"] == "invalid"
+    assert payload["meta"]["baseline_status"] == "invalid_json"
     assert payload["meta"]["baseline_loaded"] is False
 
 
@@ -1313,14 +1608,11 @@ def test_cli_reports_cache_used_false_on_warning(
     monkeypatch: pytest.MonkeyPatch,
     capsys: pytest.CaptureFixture[str],
 ) -> None:
-    src = tmp_path / "a.py"
-    src.write_text("def f():\n    return 1\n", "utf-8")
-    cache_path = tmp_path / "cache.json"
-    cache = Cache(cache_path)
+    src, cache_path, cache = _prepare_single_source_cache(tmp_path)
     cache.put_file_entry(str(src), {"mtime_ns": 1, "size": 10}, [], [], [])
     cache.save()
     data = json.loads(cache_path.read_text("utf-8"))
-    data["_signature"] = "bad"
+    data["sig"] = "bad"
     cache_path.write_text(json.dumps(data), "utf-8")
 
     baseline_path = _write_baseline(
@@ -1347,6 +1639,8 @@ def test_cli_reports_cache_used_false_on_warning(
     payload = json.loads(json_out.read_text("utf-8"))
     meta = payload["meta"]
     assert meta["cache_used"] is False
+    assert meta["cache_status"] == "integrity_failed"
+    assert meta["cache_schema_version"] == CACHE_VERSION
 
 
 def test_cli_reports_cache_too_large_respects_max_size_flag(
@@ -1385,6 +1679,41 @@ def test_cli_reports_cache_too_large_respects_max_size_flag(
     payload = json.loads(json_out.read_text("utf-8"))
     meta = payload["meta"]
     assert meta["cache_used"] is False
+    assert meta["cache_status"] == "too_large"
+    assert meta["cache_schema_version"] is None
+
+
+def test_cli_reports_cache_meta_when_cache_missing(
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    src = tmp_path / "a.py"
+    src.write_text("def f():\n    return 1\n", "utf-8")
+    baseline_path = _write_baseline(
+        tmp_path / "baseline.json",
+        python_version=f"{sys.version_info.major}.{sys.version_info.minor}",
+    )
+    json_out = tmp_path / "report.json"
+    cache_path = tmp_path / "missing-cache.json"
+    _patch_parallel(monkeypatch)
+    _run_main(
+        monkeypatch,
+        [
+            str(tmp_path),
+            "--baseline",
+            str(baseline_path),
+            "--cache-path",
+            str(cache_path),
+            "--json",
+            str(json_out),
+            "--no-progress",
+        ],
+    )
+    payload = json.loads(json_out.read_text("utf-8"))
+    meta = payload["meta"]
+    assert meta["cache_used"] is False
+    assert meta["cache_status"] == "missing"
+    assert meta["cache_schema_version"] is None
 
 
 @pytest.mark.parametrize(
@@ -1422,6 +1751,67 @@ def test_cli_output_extension_validation(
     assert expected in out
 
 
+def test_cli_output_path_resolve_error_contract(
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+    capsys: pytest.CaptureFixture[str],
+) -> None:
+    src = tmp_path / "a.py"
+    src.write_text("def f():\n    return 1\n", "utf-8")
+    html_out = tmp_path / "report.html"
+    original_resolve = Path.resolve
+
+    def _raise_resolve(
+        self: Path, strict: bool = False
+    ) -> Path:  # pragma: no cover - signature mirror
+        if self == html_out:
+            raise OSError("no resolve")
+        return original_resolve(self, strict=strict)
+
+    monkeypatch.setattr(Path, "resolve", _raise_resolve)
+    with pytest.raises(SystemExit) as exc:
+        _run_main(monkeypatch, [str(tmp_path), "--html", str(html_out)])
+    assert exc.value.code == 2
+    out = capsys.readouterr().out
+    assert "CONTRACT ERROR:" in out
+    assert "Invalid HTML output path" in out
+
+
+def test_cli_report_write_error_is_contract_error(
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+    capsys: pytest.CaptureFixture[str],
+) -> None:
+    src = tmp_path / "a.py"
+    src.write_text("def f():\n    return 1\n", "utf-8")
+    html_out = tmp_path / "report.html"
+    original_write_text = Path.write_text
+
+    def _raise_write_text(
+        self: Path,
+        data: str,
+        encoding: str | None = None,
+        errors: str | None = None,
+        newline: str | None = None,
+    ) -> int:
+        if self == html_out:
+            raise OSError("disk full")
+        return original_write_text(
+            self, data, encoding=encoding, errors=errors, newline=newline
+        )
+
+    monkeypatch.setattr(Path, "write_text", _raise_write_text)
+    _patch_parallel(monkeypatch)
+    with pytest.raises(SystemExit) as exc:
+        _run_main(
+            monkeypatch, [str(tmp_path), "--html", str(html_out), "--no-progress"]
+        )
+    assert exc.value.code == 2
+    out = capsys.readouterr().out
+    assert "CONTRACT ERROR:" in out
+    assert "Failed to write HTML report" in out
+
+
 def test_cli_outputs_quiet_no_print(
     tmp_path: Path,
     monkeypatch: pytest.MonkeyPatch,
@@ -1523,6 +1913,37 @@ def f2():
     assert baseline.exists()
 
 
+def test_cli_update_baseline_write_error_is_contract_error(
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+    capsys: pytest.CaptureFixture[str],
+) -> None:
+    src = tmp_path / "a.py"
+    src.write_text("def f():\n    return 1\n", "utf-8")
+    baseline_path = tmp_path / "baseline.json"
+
+    def _raise_save(self: baseline.Baseline) -> None:
+        raise OSError("readonly fs")
+
+    monkeypatch.setattr(baseline.Baseline, "save", _raise_save)
+    _patch_parallel(monkeypatch)
+    with pytest.raises(SystemExit) as exc:
+        _run_main(
+            monkeypatch,
+            [
+                str(tmp_path),
+                "--baseline",
+                str(baseline_path),
+                "--update-baseline",
+                "--no-progress",
+            ],
+        )
+    assert exc.value.code == 2
+    out = capsys.readouterr().out
+    assert "CONTRACT ERROR:" in out
+    assert "Failed to write baseline file" in out
+
+
 def test_cli_update_baseline_with_invalid_existing_file(
     tmp_path: Path,
     monkeypatch: pytest.MonkeyPatch,
@@ -1547,8 +1968,13 @@ def test_cli_update_baseline_with_invalid_existing_file(
     assert "Baseline updated" in out
     assert "Invalid baseline file" not in out
     payload = json.loads(baseline_path.read_text("utf-8"))
-    assert payload.get("baseline_version") == __version__
-    assert payload.get("schema_version") == BASELINE_SCHEMA_VERSION
+    meta = payload["meta"]
+    assert isinstance(meta, dict)
+    assert meta.get("fingerprint_version") == BASELINE_FINGERPRINT_VERSION
+    assert meta.get("schema_version") == BASELINE_SCHEMA_VERSION
+    generator = meta.get("generator")
+    assert isinstance(generator, dict)
+    assert generator.get("version") == __version__
 
 
 def test_cli_baseline_missing_warning(
@@ -1571,6 +1997,33 @@ def test_cli_baseline_missing_warning(
     )
     out = capsys.readouterr().out
     assert "Baseline file not found" in out
+    assert "Run: codeclone . --update-baseline" in out
+
+
+def test_cli_baseline_missing_fails_in_ci(
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+    capsys: pytest.CaptureFixture[str],
+) -> None:
+    src = tmp_path / "a.py"
+    src.write_text("def f():\n    return 1\n", "utf-8")
+    baseline = tmp_path / "missing.json"
+    _patch_parallel(monkeypatch)
+    with pytest.raises(SystemExit) as exc:
+        _run_main(
+            monkeypatch,
+            [
+                str(tmp_path),
+                "--baseline",
+                str(baseline),
+                "--ci",
+                "--no-progress",
+            ],
+        )
+    assert exc.value.code == 2
+    out = capsys.readouterr().out
+    assert "Baseline file not found" in out
+    assert "CI requires a trusted baseline" in out
 
 
 def test_cli_new_clones_warning(
@@ -1629,11 +2082,11 @@ def test_cli_baseline_python_version_mismatch_warns(
         ],
     )
     out = capsys.readouterr().out
-    assert "Baseline was generated with Python 0.0." in out
-    assert "Current interpreter: Python" in out
+    assert "python tag mismatch" in out
+    assert "will be ignored" in out
 
 
-def test_cli_baseline_version_mismatch_fails(
+def test_cli_baseline_fingerprint_mismatch_fails(
     tmp_path: Path,
     monkeypatch: pytest.MonkeyPatch,
     capsys: pytest.CaptureFixture[str],
@@ -1654,15 +2107,16 @@ def test_cli_baseline_version_mismatch_fails(
                 str(tmp_path),
                 "--baseline",
                 str(baseline_path),
+                "--ci",
                 "--no-progress",
             ],
         )
     assert exc.value.code == 2
     out = capsys.readouterr().out
-    assert "Baseline version mismatch" in out
+    assert "fingerprint version mismatch" in out
 
 
-def test_cli_baseline_version_missing_fails(
+def test_cli_baseline_missing_fields_fails(
     tmp_path: Path,
     monkeypatch: pytest.MonkeyPatch,
     capsys: pytest.CaptureFixture[str],
@@ -1689,12 +2143,13 @@ def test_cli_baseline_version_missing_fails(
                 str(tmp_path),
                 "--baseline",
                 str(baseline_path),
+                "--ci",
                 "--no-progress",
             ],
         )
     assert exc.value.code == 2
     out = capsys.readouterr().out
-    assert "Baseline version missing" in out
+    assert "legacy (<=1.3.x)" in out
 
 
 def test_cli_baseline_schema_version_mismatch_fails(
@@ -1708,8 +2163,9 @@ def test_cli_baseline_schema_version_mismatch_fails(
     _write_baseline(
         baseline_path,
         python_version=f"{sys.version_info.major}.{sys.version_info.minor}",
-        schema_version=999,
+        schema_version="1.1",
     )
+    json_out = tmp_path / "report.json"
     _patch_parallel(monkeypatch)
     with pytest.raises(SystemExit) as exc:
         _run_main(
@@ -1718,15 +2174,20 @@ def test_cli_baseline_schema_version_mismatch_fails(
                 str(tmp_path),
                 "--baseline",
                 str(baseline_path),
+                "--json",
+                str(json_out),
+                "--ci",
                 "--no-progress",
             ],
         )
     assert exc.value.code == 2
     out = capsys.readouterr().out
-    assert "Baseline schema version mismatch" in out
+    assert "schema version is newer than supported" in out
+    payload = json.loads(json_out.read_text("utf-8"))
+    assert payload["meta"]["baseline_status"] == "mismatch_schema_version"
 
 
-def test_cli_baseline_version_and_schema_mismatch_status_prefers_version(
+def test_cli_baseline_schema_and_fingerprint_mismatch_status_prefers_schema(
     tmp_path: Path,
     monkeypatch: pytest.MonkeyPatch,
     capsys: pytest.CaptureFixture[str],
@@ -1737,7 +2198,7 @@ def test_cli_baseline_version_and_schema_mismatch_status_prefers_version(
         tmp_path / "baseline.json",
         python_version=f"{sys.version_info.major}.{sys.version_info.minor}",
         baseline_version="0.0.0",
-        schema_version=999,
+        schema_version="1.1",
     )
     json_out = tmp_path / "report.json"
     _patch_parallel(monkeypatch)
@@ -1750,18 +2211,19 @@ def test_cli_baseline_version_and_schema_mismatch_status_prefers_version(
                 str(baseline_path),
                 "--json",
                 str(json_out),
+                "--ci",
                 "--no-progress",
             ],
         )
     assert exc.value.code == 2
     out = capsys.readouterr().out
-    assert "Baseline version mismatch" in out
-    assert "Baseline schema version mismatch" in out
+    assert "schema version is newer than supported" in out
+    assert "fingerprint version mismatch" not in out
     payload = json.loads(json_out.read_text("utf-8"))
-    assert payload["meta"]["baseline_status"] == "mismatch_version"
+    assert payload["meta"]["baseline_status"] == "mismatch_schema_version"
 
 
-def test_cli_baseline_version_and_python_mismatch_status_prefers_version(
+def test_cli_baseline_fingerprint_and_python_mismatch_status_prefers_fingerprint(
     tmp_path: Path,
     monkeypatch: pytest.MonkeyPatch,
     capsys: pytest.CaptureFixture[str],
@@ -1784,15 +2246,16 @@ def test_cli_baseline_version_and_python_mismatch_status_prefers_version(
                 str(baseline_path),
                 "--json",
                 str(json_out),
+                "--ci",
                 "--no-progress",
             ],
         )
     assert exc.value.code == 2
     out = capsys.readouterr().out
-    assert "Baseline version mismatch" in out
-    assert "Baseline Python version mismatch" in out
+    assert "fingerprint version mismatch" in out
+    assert "Python version mismatch" not in out
     payload = json.loads(json_out.read_text("utf-8"))
-    assert payload["meta"]["baseline_status"] == "mismatch_version"
+    assert payload["meta"]["baseline_status"] == "mismatch_fingerprint_version"
 
 
 def test_cli_baseline_python_version_mismatch_fails(
@@ -1818,7 +2281,8 @@ def test_cli_baseline_python_version_mismatch_fails(
         )
     assert exc.value.code == 2
     out = capsys.readouterr().out
-    assert "Baseline checks require the same Python version" in out
+    assert "CONTRACT ERROR:" in out
+    assert "python tag mismatch" in out
 
 
 def test_cli_negative_size_limits_fail_fast(
@@ -1826,7 +2290,7 @@ def test_cli_negative_size_limits_fail_fast(
 ) -> None:
     with pytest.raises(SystemExit) as exc:
         _run_main(monkeypatch, ["--max-baseline-size-mb", "-1"])
-    assert exc.value.code == 1
+    assert exc.value.code == 2
     out = capsys.readouterr().out
     assert "non-negative integers" in out
 
@@ -1860,7 +2324,7 @@ def f2():
                 "--no-progress",
             ],
         )
-    assert exc.value.code == 2
+    assert exc.value.code == 3
 
 
 def test_cli_main_fail_on_new(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
@@ -1976,6 +2440,7 @@ def f2():
         )
     assert exc.value.code == 3
     out = capsys.readouterr().out
+    assert "GATING FAILURE:" in out
     _assert_fail_on_new_summary(out, include_blocks=False)
     assert "CodeClone v" not in out
 
@@ -2003,7 +2468,7 @@ def test_cli_cache_warning(
     cache.put_file_entry("x.py", {"mtime_ns": 1, "size": 1}, [], [], [])
     cache.save()
     data = json.loads(cache_path.read_text("utf-8"))
-    data["_signature"] = "bad"
+    data["sig"] = "bad"
     cache_path.write_text(json.dumps(data), "utf-8")
 
     _patch_parallel(monkeypatch)
@@ -2078,7 +2543,36 @@ def _raise_save(self: Cache) -> None:
 def test_cli_invalid_root(monkeypatch: pytest.MonkeyPatch) -> None:
     with pytest.raises(SystemExit) as exc:
         _run_main(monkeypatch, ["/path/does/not/exist"])
-    assert exc.value.code == 1
+    assert exc.value.code == 2
+
+
+def test_cli_invalid_baseline_path_error_contract(
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+    capsys: pytest.CaptureFixture[str],
+) -> None:
+    src = tmp_path / "a.py"
+    src.write_text("def f():\n    return 1\n", "utf-8")
+    baseline_path = tmp_path / "baseline.json"
+    original_resolve = Path.resolve
+
+    def _raise_resolve(
+        self: Path, strict: bool = False
+    ) -> Path:  # pragma: no cover - signature mirror
+        if self == baseline_path:
+            raise OSError("no resolve")
+        return original_resolve(self, strict=strict)
+
+    monkeypatch.setattr(Path, "resolve", _raise_resolve)
+    with pytest.raises(SystemExit) as exc:
+        _run_main(
+            monkeypatch,
+            [str(tmp_path), "--baseline", str(baseline_path), "--no-progress"],
+        )
+    assert exc.value.code == 2
+    out = capsys.readouterr().out
+    assert "CONTRACT ERROR:" in out
+    assert "Invalid baseline path" in out
 
 
 def test_cli_discovery_cache_hit(
@@ -2168,15 +2662,199 @@ def _bad_stat(_path: str) -> dict[str, int]:
     assert files_found == files_analyzed + cache_hits + files_skipped
 
 
-def test_cli_ci_discovery_cache_hit(
+def test_cli_unreadable_source_normal_mode_warns_and_continues(
     tmp_path: Path,
     monkeypatch: pytest.MonkeyPatch,
     capsys: pytest.CaptureFixture[str],
 ) -> None:
     src = tmp_path / "a.py"
     src.write_text("def f():\n    return 1\n", "utf-8")
-    cache_path = tmp_path / "cache.json"
-    cache = Cache(cache_path)
+
+    def _source_read_error(
+        fp: str, *_args: object, **_kwargs: object
+    ) -> cli.ProcessingResult:
+        return _source_read_error_result(fp)
+
+    monkeypatch.setattr(cli, "process_file", _source_read_error)
+    _patch_parallel(monkeypatch)
+    _run_main(monkeypatch, [str(tmp_path), "--no-progress"])
+    out = capsys.readouterr().out
+    assert "Cannot read file" in out
+    assert "CONTRACT ERROR:" not in out
+    assert _summary_metric(out, "Files skipped") == 1
+
+
+def test_cli_unreadable_source_fails_in_ci_with_contract_error(
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+    capsys: pytest.CaptureFixture[str],
+) -> None:
+    _src, baseline_path = _prepare_source_and_baseline(tmp_path)
+    json_out = tmp_path / "report.json"
+
+    def _source_read_error(
+        fp: str, *_args: object, **_kwargs: object
+    ) -> cli.ProcessingResult:
+        return _source_read_error_result(fp)
+
+    monkeypatch.setattr(cli, "process_file", _source_read_error)
+    _patch_parallel(monkeypatch)
+    with pytest.raises(SystemExit) as exc:
+        _run_main(
+            monkeypatch,
+            [
+                str(tmp_path),
+                "--ci",
+                "--baseline",
+                str(baseline_path),
+                "--json",
+                str(json_out),
+            ],
+        )
+    assert exc.value.code == 2
+    out = capsys.readouterr().out
+    _assert_unreadable_source_contract_error(out)
+    payload = json.loads(json_out.read_text("utf-8"))
+    assert payload["meta"]["files_skipped_source_io"] == 1
+
+
+def test_cli_reports_include_source_io_skipped_zero(
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    src = tmp_path / "a.py"
+    src.write_text("def f():\n    return 1\n", "utf-8")
+    json_out = tmp_path / "report.json"
+
+    _patch_parallel(monkeypatch)
+    _run_main(
+        monkeypatch,
+        [
+            str(tmp_path),
+            "--json",
+            str(json_out),
+            "--no-progress",
+        ],
+    )
+    payload = json.loads(json_out.read_text("utf-8"))
+    assert payload["meta"]["files_skipped_source_io"] == 0
+
+
+def test_cli_contract_error_priority_over_gating_failure_for_unreadable_source(
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+    capsys: pytest.CaptureFixture[str],
+) -> None:
+    _src, baseline_path = _prepare_source_and_baseline(tmp_path)
+
+    def _source_read_error(
+        fp: str, *_args: object, **_kwargs: object
+    ) -> cli.ProcessingResult:
+        return _source_read_error_result(fp)
+
+    def _diff(
+        _self: object, _f: dict[str, object], _b: dict[str, object]
+    ) -> tuple[set[str], set[str]]:
+        return {"f1"}, set()
+
+    monkeypatch.setattr(cli, "process_file", _source_read_error)
+    monkeypatch.setattr(baseline.Baseline, "diff", _diff)
+    _patch_parallel(monkeypatch)
+    with pytest.raises(SystemExit) as exc:
+        _run_main(
+            monkeypatch,
+            [
+                str(tmp_path),
+                "--fail-on-new",
+                "--baseline",
+                str(baseline_path),
+                "--no-progress",
+            ],
+        )
+    assert exc.value.code == 2
+    out = capsys.readouterr().out
+    _assert_unreadable_source_contract_error(out)
+    assert "GATING FAILURE:" not in out
+
+
+def test_cli_unreadable_source_ci_shows_overflow_summary(
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+    capsys: pytest.CaptureFixture[str],
+) -> None:
+    for i in range(11):
+        (tmp_path / f"f{i}.py").write_text("def f():\n    return 1\n", "utf-8")
+    _baseline = _write_baseline(
+        tmp_path / "baseline.json",
+        python_version=f"{sys.version_info.major}.{sys.version_info.minor}",
+    )
+
+    def _source_read_error(
+        fp: str, *_args: object, **_kwargs: object
+    ) -> cli.ProcessingResult:
+        return _source_read_error_result(fp)
+
+    monkeypatch.setattr(cli, "process_file", _source_read_error)
+    _patch_parallel(monkeypatch)
+    with pytest.raises(SystemExit) as exc:
+        _run_main(
+            monkeypatch,
+            [
+                str(tmp_path),
+                "--ci",
+                "--baseline",
+                str(_baseline),
+            ],
+        )
+    assert exc.value.code == 2
+    out = capsys.readouterr().out
+    _assert_unreadable_source_contract_error(out)
+    assert "... and 1 more" in out
+
+
+def test_cli_report_meta_cache_path_resolve_oserror_fallback(
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    _src, baseline_path = _prepare_source_and_baseline(tmp_path)
+    cache_path = tmp_path / "cache_for_meta.json"
+    json_out = tmp_path / "report.json"
+
+    original_resolve = Path.resolve
+    resolve_called = {"cache": False}
+
+    def _resolve(self: Path, strict: bool = False) -> Path:
+        if self == cache_path:
+            resolve_called["cache"] = True
+            raise OSError("resolve failed")
+        return original_resolve(self, strict=strict)
+
+    monkeypatch.setattr(Path, "resolve", _resolve)
+    _patch_parallel(monkeypatch)
+    _run_main(
+        monkeypatch,
+        [
+            str(tmp_path),
+            "--baseline",
+            str(baseline_path),
+            "--cache-path",
+            str(cache_path),
+            "--json",
+            str(json_out),
+            "--no-progress",
+        ],
+    )
+    payload = json.loads(json_out.read_text("utf-8"))
+    assert resolve_called["cache"] is True
+    assert payload["meta"]["cache_path"] == str(cache_path)
+
+
+def test_cli_ci_discovery_cache_hit(
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+    capsys: pytest.CaptureFixture[str],
+) -> None:
+    src, cache_path, cache = _prepare_single_source_cache(tmp_path)
     stat = file_stat_signature(str(src))
     cache.put_file_entry(
         str(src),
@@ -2276,14 +2954,37 @@ def test_cli_summary_no_color_has_no_ansi(
     assert "\x1b[" not in out
 
 
-def test_cli_scan_failed(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+def test_cli_scan_failed_is_internal_error(
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+    capsys: pytest.CaptureFixture[str],
+) -> None:
     def _boom(_root: str) -> Iterable[str]:
         raise RuntimeError("scan failed")
 
     monkeypatch.setattr(cli, "iter_py_files", _boom)
     with pytest.raises(SystemExit) as exc:
         _run_main(monkeypatch, [str(tmp_path)])
-    assert exc.value.code == 1
+    assert exc.value.code == 5
+    out = capsys.readouterr().out
+    assert "INTERNAL ERROR:" in out
+
+
+def test_cli_scan_oserror_is_contract_error(
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+    capsys: pytest.CaptureFixture[str],
+) -> None:
+    def _boom(_root: str) -> Iterable[str]:
+        raise OSError("scan denied")
+
+    monkeypatch.setattr(cli, "iter_py_files", _boom)
+    with pytest.raises(SystemExit) as exc:
+        _run_main(monkeypatch, [str(tmp_path)])
+    assert exc.value.code == 2
+    out = capsys.readouterr().out
+    assert "CONTRACT ERROR:" in out
+    assert "Scan failed" in out
 
 
 def test_cli_failed_files_report(
diff --git a/tests/test_cli_unit.py b/tests/test_cli_unit.py
index a9c3693..6f3c53a 100644
--- a/tests/test_cli_unit.py
+++ b/tests/test_cli_unit.py
@@ -6,10 +6,14 @@
 import pytest
 from rich.text import Text
 
+import codeclone._cli_summary as cli_summary
 import codeclone.cli as cli
 from codeclone import __version__
 from codeclone import ui_messages as ui
-from codeclone.cli import expand_path, process_file
+from codeclone._cli_args import build_parser
+from codeclone._cli_paths import expand_path
+from codeclone.cli import process_file
+from codeclone.contracts import DOCS_URL, ISSUES_URL, REPOSITORY_URL
 from codeclone.normalize import NormalizationConfig
 
 
@@ -50,6 +54,22 @@ def _boom(*_args: object, **_kwargs: object) -> str:
     assert "Encoding error" in result.error
 
 
+def test_process_file_read_oserror(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+) -> None:
+    src = tmp_path / "a.py"
+    src.write_text("def f():\n    return 1\n", "utf-8")
+
+    def _boom(*_args: object, **_kwargs: object) -> str:
+        raise OSError("read denied")
+
+    monkeypatch.setattr(Path, "read_text", _boom)
+    result = process_file(str(src), str(tmp_path), NormalizationConfig(), 1, 1)
+    assert result.success is False
+    assert result.error is not None
+    assert "Cannot read file" in result.error
+
+
 def test_process_file_unexpected_error(
     monkeypatch: pytest.MonkeyPatch, tmp_path: Path
 ) -> None:
@@ -113,28 +133,114 @@ def test_cli_help_text_consistency(
     assert "Legacy alias for --cache-path" in out
     assert "--max-baseline-size-mb MB" in out
     assert "--max-cache-size-mb MB" in out
+    assert "--debug" in out
     assert "CI preset: --fail-on-new --no-color --quiet." in out
     assert "total clone groups (function +" in out
     assert "block) exceed this number" in out
+    assert "Exit codes" in out
+    assert "0 - success" in out
+    assert "2 - contract error" in out
+    assert "baseline missing/untrusted" in out
+    assert "invalid output extensions" in out
+    assert "3 - gating failure" in out
+    assert "new clones detected" in out
+    assert "threshold exceeded" in out
+    assert "5 - internal error" in out
+    assert "please report" in out
+    assert f"Repository: {REPOSITORY_URL}" in out
+    assert f"Issues: {ISSUES_URL}" in out
+    assert f"Docs: {DOCS_URL}" in out
+    assert "\x1b[" not in out
+
+
+def test_cli_internal_error_marker(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+) -> None:
+    def _boom() -> None:
+        raise RuntimeError("boom")
+
+    monkeypatch.setattr(cli, "_main_impl", _boom)
+    with pytest.raises(SystemExit) as exc:
+        cli.main()
+    assert exc.value.code == 5
+    out = capsys.readouterr().out
+    assert "INTERNAL ERROR:" in out
+    assert "Unexpected exception." in out
+    assert "Reason: RuntimeError: boom" in out
+    assert "Next steps:" in out
+    assert "Re-run with --debug to include a traceback." in out
+    assert f"{ISSUES_URL}/new?template=bug_report.yml" in out
+    assert "Traceback:" not in out
+
+
+def test_cli_internal_error_debug_flag_includes_traceback(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+) -> None:
+    def _boom() -> None:
+        raise RuntimeError("boom")
+
+    monkeypatch.setattr(cli, "_main_impl", _boom)
+    monkeypatch.setattr(sys, "argv", ["codeclone", "--debug"])
+    with pytest.raises(SystemExit) as exc:
+        cli.main()
+    assert exc.value.code == 5
+    out = capsys.readouterr().out
+    assert "INTERNAL ERROR:" in out
+    assert "DEBUG DETAILS" in out
+    assert "Traceback:" in out
+    assert "Command: codeclone --debug" in out
+
+
+def test_cli_internal_error_debug_env_includes_traceback(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+) -> None:
+    def _boom() -> None:
+        raise RuntimeError("boom")
+
+    monkeypatch.setattr(cli, "_main_impl", _boom)
+    monkeypatch.setenv("CODECLONE_DEBUG", "1")
+    monkeypatch.setattr(sys, "argv", ["codeclone"])
+    with pytest.raises(SystemExit) as exc:
+        cli.main()
+    assert exc.value.code == 5
+    out = capsys.readouterr().out
+    assert "INTERNAL ERROR:" in out
+    assert "DEBUG DETAILS" in out
+    assert "Traceback:" in out
+
+
+def test_argument_parser_contract_error_marker_for_invalid_args(
+    capsys: pytest.CaptureFixture[str],
+) -> None:
+    parser = build_parser(__version__)
+    with pytest.raises(SystemExit) as exc:
+        parser.parse_args(["--unknown-flag"])
+    assert exc.value.code == 2
+    err = capsys.readouterr().err
+    assert "CONTRACT ERROR:" in err
 
 
 def test_summary_value_style_mapping() -> None:
-    assert cli._summary_value_style(label=ui.SUMMARY_LABEL_FUNCTION, value=0) == "dim"
     assert (
-        cli._summary_value_style(label=ui.SUMMARY_LABEL_FUNCTION, value=2)
+        cli_summary._summary_value_style(label=ui.SUMMARY_LABEL_FUNCTION, value=0)
+        == "dim"
+    )
+    assert (
+        cli_summary._summary_value_style(label=ui.SUMMARY_LABEL_FUNCTION, value=2)
         == "bold green"
     )
     assert (
-        cli._summary_value_style(label=ui.SUMMARY_LABEL_SUPPRESSED, value=1) == "yellow"
+        cli_summary._summary_value_style(label=ui.SUMMARY_LABEL_SUPPRESSED, value=1)
+        == "yellow"
     )
     assert (
-        cli._summary_value_style(label=ui.SUMMARY_LABEL_NEW_BASELINE, value=3)
+        cli_summary._summary_value_style(label=ui.SUMMARY_LABEL_NEW_BASELINE, value=3)
         == "bold red"
     )
 
 
 def test_build_summary_table_rows_and_styles() -> None:
-    rows = cli._build_summary_rows(
+    rows = cli_summary._build_summary_rows(
         files_found=2,
         files_analyzed=0,
         cache_hits=2,
@@ -145,7 +251,7 @@ def test_build_summary_table_rows_and_styles() -> None:
         suppressed_segment_groups=1,
         new_clones_count=1,
     )
-    table = cli._build_summary_table(rows)
+    table = cli_summary._build_summary_table(rows)
     assert table.title == ui.SUMMARY_TITLE
     assert table.columns[0]._cells == [label for label, _ in rows]
     value_cells = table.columns[1]._cells
@@ -157,7 +263,7 @@ def test_build_summary_table_rows_and_styles() -> None:
 
 
 def test_build_summary_rows_order() -> None:
-    rows = cli._build_summary_rows(
+    rows = cli_summary._build_summary_rows(
         files_found=1,
         files_analyzed=1,
         cache_hits=0,
@@ -186,7 +292,8 @@ def test_print_summary_invariant_warning(
     monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
 ) -> None:
     monkeypatch.setattr(cli, "console", cli._make_console(no_color=True))
-    cli._print_summary(
+    cli_summary._print_summary(
+        console=cli.console,
         quiet=False,
         files_found=1,
         files_analyzed=0,
diff --git a/tests/test_detector_golden.py b/tests/test_detector_golden.py
new file mode 100644
index 0000000..5c3a0e6
--- /dev/null
+++ b/tests/test_detector_golden.py
@@ -0,0 +1,61 @@
+from __future__ import annotations
+
+import json
+from dataclasses import asdict
+from pathlib import Path
+
+import pytest
+
+from codeclone.baseline import current_python_tag
+from codeclone.extractor import extract_units_from_source
+from codeclone.normalize import NormalizationConfig
+from codeclone.report import build_block_groups, build_groups
+from codeclone.scanner import module_name_from_path
+
+
+def _detect_group_keys(project_root: Path) -> tuple[list[str], list[str]]:
+    cfg = NormalizationConfig()
+    all_units: list[dict[str, object]] = []
+    all_blocks: list[dict[str, object]] = []
+
+    for path in sorted(project_root.glob("*.py")):
+        source = path.read_text("utf-8")
+        module_name = module_name_from_path(str(project_root), str(path))
+        units, blocks, _segments = extract_units_from_source(
+            source=source,
+            filepath=str(path),
+            module_name=module_name,
+            cfg=cfg,
+            min_loc=1,
+            min_stmt=1,
+        )
+        all_units.extend(asdict(unit) for unit in units)
+        all_blocks.extend(asdict(block) for block in blocks)
+
+    function_group_keys = sorted(build_groups(all_units).keys())
+    block_group_keys = sorted(build_block_groups(all_blocks).keys())
+    return function_group_keys, block_group_keys
+
+
+def test_detector_output_matches_golden_fixture() -> None:
+    fixture_root = Path("tests/fixtures/golden_project").resolve()
+    expected_path = fixture_root / "golden_expected_ids.json"
+    expected = json.loads(expected_path.read_text("utf-8"))
+    expected_meta = expected.get("meta", {})
+    assert isinstance(expected_meta, dict)
+    expected_python_tag = expected_meta.get("python_tag")
+    assert isinstance(expected_python_tag, str)
+
+    # Golden fixture is a detector snapshot for one canonical Python tag.
+    # Cross-version behavior is covered by contract/invariant tests.
+    runtime_tag = current_python_tag()
+    if runtime_tag != expected_python_tag:
+        pytest.skip(
+            "Golden detector fixture is canonicalized for "
+            f"{expected_python_tag}; runtime is {runtime_tag}."
+        )
+
+    function_group_keys, block_group_keys = _detect_group_keys(fixture_root)
+
+    assert function_group_keys == expected["function_group_keys"]
+    assert block_group_keys == expected["block_group_keys"]
diff --git a/tests/test_extractor.py b/tests/test_extractor.py
index 5cbb189..c1bc568 100644
--- a/tests/test_extractor.py
+++ b/tests/test_extractor.py
@@ -142,6 +142,90 @@ def setrlimit(_key: int, val: tuple[int, int]) -> None:
     )
 
 
+def test_parse_limits_accounts_for_consumed_cpu(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    calls: list[tuple[int, int]] = []
+
+    class _DummyUsage:
+        ru_utime = 7.2
+        ru_stime = 0.3
+
+    class _DummyResource:
+        RLIMIT_CPU = 0
+        RLIM_INFINITY = 10**9
+        RUSAGE_SELF = 0
+
+        @staticmethod
+        def getrlimit(_key: int) -> tuple[int, int]:
+            return (_DummyResource.RLIM_INFINITY, _DummyResource.RLIM_INFINITY)
+
+        @staticmethod
+        def setrlimit(_key: int, val: tuple[int, int]) -> None:
+            calls.append(val)
+
+        @staticmethod
+        def getrusage(_who: int) -> _DummyUsage:
+            return _DummyUsage()
+
+    monkeypatch.setattr(os, "name", "posix")
+    monkeypatch.setattr(signal, "getsignal", lambda *_args, **_kwargs: None)
+    monkeypatch.setattr(signal, "signal", lambda *_args, **_kwargs: None)
+    monkeypatch.setattr(signal, "setitimer", lambda *_args, **_kwargs: None)
+    monkeypatch.setitem(sys.modules, "resource", _DummyResource)
+
+    with extractor._parse_limits(5):
+        pass
+
+    assert calls
+    # ceil(7.5) + timeout(5) == 13
+    assert calls[0] == (13, _DummyResource.RLIM_INFINITY)
+    assert calls[-1] == (
+        _DummyResource.RLIM_INFINITY,
+        _DummyResource.RLIM_INFINITY,
+    )
+
+
+def test_parse_limits_raises_too_low_soft_limit_for_consumed_cpu(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    calls: list[tuple[int, int]] = []
+
+    class _DummyUsage:
+        ru_utime = 10.0
+        ru_stime = 0.0
+
+    class _DummyResource:
+        RLIMIT_CPU = 0
+        RLIM_INFINITY = 10**9
+        RUSAGE_SELF = 0
+
+        @staticmethod
+        def getrlimit(_key: int) -> tuple[int, int]:
+            return (2, 20)
+
+        @staticmethod
+        def setrlimit(_key: int, val: tuple[int, int]) -> None:
+            calls.append(val)
+
+        @staticmethod
+        def getrusage(_who: int) -> _DummyUsage:
+            return _DummyUsage()
+
+    monkeypatch.setattr(os, "name", "posix")
+    monkeypatch.setattr(signal, "getsignal", lambda *_args, **_kwargs: None)
+    monkeypatch.setattr(signal, "signal", lambda *_args, **_kwargs: None)
+    monkeypatch.setattr(signal, "setitimer", lambda *_args, **_kwargs: None)
+    monkeypatch.setitem(sys.modules, "resource", _DummyResource)
+
+    with extractor._parse_limits(5):
+        pass
+
+    # Raised from 2 to ceil(10)+5 to avoid immediate SIGXCPU.
+    assert calls[0] == (15, 20)
+    assert calls[-1] == (2, 20)
+
+
 def test_parse_limits_uses_finite_soft_limit_branch(
     monkeypatch: pytest.MonkeyPatch,
 ) -> None:
@@ -168,8 +252,8 @@ def setrlimit(_key: int, val: tuple[int, int]) -> None:
     with extractor._parse_limits(5):
         pass
 
-    # New soft is min(timeout, old_soft, hard_ceiling), hard is preserved.
-    assert calls[0] == (5, 20)
+    # Finite soft limits are never lowered.
+    assert calls[0] == (20, 20)
     assert calls[-1] == (20, 20)
 
 
diff --git a/tests/test_html_report.py b/tests/test_html_report.py
index 431d088..5e777af 100644
--- a/tests/test_html_report.py
+++ b/tests/test_html_report.py
@@ -1,9 +1,12 @@
 import importlib
 import json
+from collections.abc import Callable
 from pathlib import Path
+from typing import Any
 
 import pytest
 
+from codeclone.contracts import DOCS_URL, ISSUES_URL, REPOSITORY_URL
 from codeclone.errors import FileProcessingError
 from codeclone.html_report import (
     _FileCache,
@@ -11,10 +14,87 @@
     _pygments_css,
     _render_code_block,
     _try_pygments,
-    build_html_report,
     pairwise,
 )
-from codeclone.report import to_json_report
+from codeclone.html_report import (
+    build_html_report as _core_build_html_report,
+)
+from codeclone.report import build_block_group_facts, to_json_report
+from tests._report_fixtures import (
+    REPEATED_ASSERT_SOURCE,
+    repeated_block_group_key,
+)
+from tests._report_fixtures import (
+    REPEATED_STMT_HASH as _REPEATED_STMT_HASH,
+)
+
+_REPEATED_BLOCK_GROUP_KEY = repeated_block_group_key()
+
+
+def build_html_report(
+    *,
+    func_groups: dict[str, list[dict[str, Any]]],
+    block_groups: dict[str, list[dict[str, Any]]],
+    segment_groups: dict[str, list[dict[str, Any]]],
+    block_group_facts: dict[str, dict[str, str]] | None = None,
+    **kwargs: Any,
+) -> str:
+    resolved_block_group_facts = (
+        block_group_facts
+        if block_group_facts is not None
+        else build_block_group_facts(block_groups)
+    )
+    return _core_build_html_report(
+        func_groups=func_groups,
+        block_groups=block_groups,
+        segment_groups=segment_groups,
+        block_group_facts=resolved_block_group_facts,
+        **kwargs,
+    )
+
+
+def _repeated_assert_block_groups(
+    tmp_path: Path,
+    *,
+    qualnames: tuple[str, ...] = ("pkg.mod:f",),
+) -> tuple[str, dict[str, list[dict[str, Any]]]]:
+    test_file = tmp_path / "test_repeated_asserts.py"
+    test_file.write_text(REPEATED_ASSERT_SOURCE, "utf-8")
+    return _REPEATED_BLOCK_GROUP_KEY, {
+        _REPEATED_BLOCK_GROUP_KEY: [
+            {
+                "qualname": qualname,
+                "filepath": str(test_file),
+                "start_line": 2,
+                "end_line": 5,
+            }
+            for qualname in qualnames
+        ]
+    }
+
+
+def _build_repeated_assert_block_report(
+    tmp_path: Path,
+    *,
+    qualnames: tuple[str, ...] = ("pkg.mod:f",),
+    block_group_facts: dict[str, dict[str, str]] | None = None,
+    report_meta: dict[str, Any] | None = None,
+) -> tuple[str, str]:
+    group_key, block_groups = _repeated_assert_block_groups(
+        tmp_path, qualnames=qualnames
+    )
+    kwargs: dict[str, Any] = {}
+    if block_group_facts is not None:
+        kwargs["block_group_facts"] = block_group_facts
+    if report_meta is not None:
+        kwargs["report_meta"] = report_meta
+    html = build_html_report(
+        func_groups={},
+        block_groups=block_groups,
+        segment_groups={},
+        **kwargs,
+    )
+    return group_key, html
 
 
 def test_html_report_empty() -> None:
@@ -26,6 +106,15 @@ def test_html_report_empty() -> None:
     assert "No code clones detected" in html
 
 
+def test_html_report_requires_block_group_facts_argument() -> None:
+    with pytest.raises(TypeError):
+        _core_build_html_report(
+            func_groups={},
+            block_groups={},
+            segment_groups={},
+        )  # type: ignore[call-arg]
+
+
 def test_html_report_generation(tmp_path: Path) -> None:
     f1 = tmp_path / "a.py"
     f1.write_text("def f1():\n    pass\n", "utf-8")
@@ -73,26 +162,314 @@ def test_html_report_group_and_item_metadata_attrs(tmp_path: Path) -> None:
         title="Attrs",
     )
     assert 'data-group-key="hash1"' in html
-    assert '<code class="gkey" title="hash1">hash1</code>' in html
+    assert '<div class="group-name">hash1</div>' in html
     assert 'data-qualname="pkg.mod:f"' in html
     assert 'data-filepath="' in html
     assert 'data-start-line="1"' in html
     assert 'data-end-line="2"' in html
 
 
+def test_html_report_renders_novelty_tabs_and_group_flags(tmp_path: Path) -> None:
+    f = tmp_path / "a.py"
+    f.write_text("def f():\n    return 1\n", "utf-8")
+    html = build_html_report(
+        func_groups={
+            "known-func": [
+                {
+                    "qualname": "pkg.mod:known",
+                    "filepath": str(f),
+                    "start_line": 1,
+                    "end_line": 2,
+                }
+            ],
+            "new-func": [
+                {
+                    "qualname": "pkg.mod:new",
+                    "filepath": str(f),
+                    "start_line": 1,
+                    "end_line": 2,
+                }
+            ],
+        },
+        block_groups={},
+        segment_groups={},
+        new_function_group_keys={"new-func"},
+        report_meta={"baseline_loaded": True, "baseline_status": "ok"},
+    )
+    assert "New duplicates" in html
+    assert "Known duplicates" in html
+    assert 'id="global-novelty-controls"' in html
+    assert 'data-global-novelty="new"' in html
+    assert 'data-global-novelty="known"' in html
+    assert 'data-novelty-filter="functions"' not in html
+    assert 'data-group-key="new-func" data-novelty="new"' in html
+    assert 'data-group-key="known-func" data-novelty="known"' in html
+    assert "Split is based on baseline" in html
+
+
+def test_html_report_renders_untrusted_baseline_novelty_note(tmp_path: Path) -> None:
+    f = tmp_path / "a.py"
+    f.write_text("def f():\n    return 1\n", "utf-8")
+    html = build_html_report(
+        func_groups={
+            "new-func": [
+                {
+                    "qualname": "pkg.mod:new",
+                    "filepath": str(f),
+                    "start_line": 1,
+                    "end_line": 2,
+                }
+            ]
+        },
+        block_groups={},
+        segment_groups={},
+        new_function_group_keys={"new-func"},
+        report_meta={"baseline_loaded": False, "baseline_status": "missing"},
+    )
+    assert "Baseline is not loaded or not trusted" in html
+    assert 'data-group-key="new-func" data-novelty="new"' in html
+
+
+def test_html_report_renders_block_novelty_tabs_and_group_flags(tmp_path: Path) -> None:
+    f = tmp_path / "a.py"
+    f.write_text("def f():\n    return 1\n", "utf-8")
+    html = build_html_report(
+        func_groups={},
+        block_groups={
+            "known-block": [
+                {
+                    "qualname": "pkg.mod:known",
+                    "filepath": str(f),
+                    "start_line": 1,
+                    "end_line": 4,
+                }
+            ],
+            "new-block": [
+                {
+                    "qualname": "pkg.mod:new",
+                    "filepath": str(f),
+                    "start_line": 5,
+                    "end_line": 8,
+                }
+            ],
+        },
+        segment_groups={},
+        new_block_group_keys={"new-block"},
+        report_meta={"baseline_loaded": True, "baseline_status": "ok"},
+    )
+    assert 'section id="blocks"' in html
+    assert 'data-section="blocks" data-has-novelty-filter="true"' in html
+    assert 'data-group-key="new-block" data-novelty="new"' in html
+    assert 'data-group-key="known-block" data-novelty="known"' in html
+
+
+def test_html_report_block_group_includes_match_basis_and_compact_key() -> None:
+    group_key = _REPEATED_BLOCK_GROUP_KEY
+    html = build_html_report(
+        func_groups={},
+        block_groups={
+            group_key: [
+                {
+                    "qualname": "pkg.mod:f",
+                    "filepath": __file__,
+                    "start_line": 1,
+                    "end_line": 4,
+                }
+            ]
+        },
+        segment_groups={},
+    )
+    assert 'data-match-rule="normalized_sliding_window"' in html
+    assert 'data-block-size="4"' in html
+    assert 'data-signature-kind="stmt_hash_sequence"' in html
+    assert 'data-merged-regions="true"' in html
+    assert 'data-pattern="repeated_stmt_hash"' in html
+    assert f"{_REPEATED_STMT_HASH[:12]} x4" in html
+
+
+def test_html_report_block_group_includes_assert_only_explanation(
+    tmp_path: Path,
+) -> None:
+    _group_key, html = _build_repeated_assert_block_report(tmp_path)
+    assert 'data-hint="assert_only"' in html
+    assert 'data-hint-confidence="deterministic"' in html
+    assert 'data-assert-ratio="100%"' in html
+    assert 'data-consecutive-asserts="4"' in html
+    assert "Assert pattern block" in html
+    assert 'data-metrics-btn="blocks-1"' in html
+
+
+def test_html_report_block_group_n_way_compare_hint(tmp_path: Path) -> None:
+    _group_key, html = _build_repeated_assert_block_report(
+        tmp_path,
+        qualnames=("pkg.mod:f1", "pkg.mod:f2", "pkg.mod:f3"),
+    )
+    assert "N-way group: each block matches 2 peers in this group." in html
+    assert "instance 1/3 • matches 2 peers" in html
+    assert "instance 2/3 • matches 2 peers" in html
+    assert "instance 3/3 • matches 2 peers" in html
+    assert 'data-group-arity="3"' in html
+
+
+def test_html_report_uses_core_block_group_facts(tmp_path: Path) -> None:
+    _group_key, html = _build_repeated_assert_block_report(
+        tmp_path,
+        block_group_facts={
+            _REPEATED_BLOCK_GROUP_KEY: {
+                "match_rule": "core_contract",
+                "block_size": "99",
+                "signature_kind": "core_signature",
+                "merged_regions": "false",
+                "hint": "assert_only",
+                "hint_confidence": "deterministic",
+                "assert_ratio": "7%",
+                "consecutive_asserts": "1",
+                "hint_note": "Facts are owned by core.",
+            }
+        },
+    )
+    assert 'data-match-rule="core_contract"' in html
+    assert 'data-block-size="99"' in html
+    assert 'data-signature-kind="core_signature"' in html
+    assert 'data-merged-regions="false"' in html
+    assert 'data-assert-ratio="7%"' in html
+    assert 'data-consecutive-asserts="1"' in html
+
+
+def test_html_report_uses_core_hint_and_pattern_labels(tmp_path: Path) -> None:
+    _group_key, html = _build_repeated_assert_block_report(
+        tmp_path,
+        block_group_facts={
+            _REPEATED_BLOCK_GROUP_KEY: {
+                "pattern": "internal_pattern_id",
+                "pattern_label": "readable pattern",
+                "hint": "internal_hint_id",
+                "hint_label": "readable hint",
+            }
+        },
+    )
+    assert "pattern: readable pattern" in html
+    assert "hint: readable hint" in html
+    assert 'data-pattern-label="readable pattern"' in html
+    assert 'data-hint-label="readable hint"' in html
+
+
+def test_html_report_uses_core_hint_context_label(tmp_path: Path) -> None:
+    _group_key, html = _build_repeated_assert_block_report(
+        tmp_path,
+        block_group_facts={
+            _REPEATED_BLOCK_GROUP_KEY: {
+                "hint": "assert_only",
+                "hint_context_label": "Likely test boilerplate / repeated asserts",
+            }
+        },
+    )
+    assert "Likely test boilerplate / repeated asserts" in html
+    assert (
+        'data-hint-context-label="Likely test boilerplate / repeated asserts"' in html
+    )
+
+
+def test_html_report_blocks_without_explanation_meta(tmp_path: Path) -> None:
+    _group_key, html = _build_repeated_assert_block_report(
+        tmp_path, block_group_facts={}
+    )
+    assert '<div class="group-explain"' not in html
+    assert 'data-group-arity="1"' in html
+
+
+def test_html_report_respects_sparse_core_block_facts(tmp_path: Path) -> None:
+    _group_key, html = _build_repeated_assert_block_report(
+        tmp_path,
+        report_meta={
+            "baseline_path": "   ",
+            "cache_path": "/",
+            "baseline_status": "ok",
+        },
+        block_group_facts={
+            _REPEATED_BLOCK_GROUP_KEY: {
+                "match_rule": "core_sparse",
+                "pattern": "repeated_stmt_hash",
+                "hint": "assert_only",
+                "hint_confidence": "deterministic",
+            }
+        },
+    )
+    assert 'data-match-rule="core_sparse"' in html
+    assert 'data-pattern="repeated_stmt_hash"' in html
+    assert 'data-block-size="' not in html
+    assert 'data-signature-kind="' not in html
+    assert 'data-assert-ratio="' not in html
+    assert 'data-consecutive-asserts="' not in html
+
+
+def test_html_report_handles_root_only_baseline_path() -> None:
+    html = build_html_report(
+        func_groups={},
+        block_groups={},
+        segment_groups={},
+        report_meta={"baseline_path": "/", "cache_path": "/"},
+    )
+    assert 'data-baseline-file=""' in html
+
+
+def test_html_report_explanation_without_match_rule(tmp_path: Path) -> None:
+    _group_key, html = _build_repeated_assert_block_report(
+        tmp_path,
+        block_group_facts={
+            _REPEATED_BLOCK_GROUP_KEY: {
+                "hint": "assert_only",
+                "hint_confidence": "deterministic",
+            }
+        },
+    )
+    assert 'data-hint="assert_only"' in html
+    assert "match_rule:" not in html
+
+
+def test_html_report_n_way_group_without_compare_note(tmp_path: Path) -> None:
+    _group_key, html = _build_repeated_assert_block_report(
+        tmp_path,
+        qualnames=("pkg.mod:f1", "pkg.mod:f2", "pkg.mod:f3"),
+        block_group_facts={
+            _REPEATED_BLOCK_GROUP_KEY: {
+                "group_arity": "3",
+                "instance_peer_count": "2",
+            }
+        },
+    )
+    assert 'data-group-arity="3"' in html
+    assert '<div class="group-compare-note">' not in html
+
+
 def test_html_report_command_palette_full_actions_present() -> None:
     html = build_html_report(func_groups={}, block_groups={}, segment_groups={})
-    assert "Export as PDF" in html
+    assert "Export Report" in html
+    assert "Toggle Theme" in html
+    assert "Open Help" in html
+    assert "Expand All" in html
+    assert "Collapse All" in html
     assert "window.print();" in html
-    assert "No matching commands" in html
-    assert "ArrowDown" in html
-    assert "ArrowUp" in html
-    assert "Chart feature coming soon" not in html
-    assert "Clone Group Distribution" in html
-    assert 'id="stats-dashboard" style="display: none;"' in html
+    assert "Generated by CodeClone v" in html
+    assert '<span class="footer-kbd">⌘K</span>' in html
+    assert '<span class="footer-kbd">⌘I</span>' in html
+    assert "key === 'i'" in html
+    assert 'id="help-modal"' in html
 
 
-def test_html_report_includes_provenance_metadata(tmp_path: Path) -> None:
+def test_html_report_help_modal_links_present() -> None:
+    html = build_html_report(func_groups={}, block_groups={}, segment_groups={})
+    assert "Help & Support" in html
+    assert f'href="{REPOSITORY_URL}"' in html
+    assert f'href="{ISSUES_URL}"' in html
+    assert f'href="{DOCS_URL}"' in html
+    assert 'rel="noopener noreferrer"' in html
+
+
+def test_html_report_includes_provenance_metadata(
+    tmp_path: Path,
+    report_meta_factory: Callable[..., dict[str, object]],
+) -> None:
     f = tmp_path / "a.py"
     f.write_text("def f():\n    return 1\n", "utf-8")
     html = build_html_report(
@@ -108,28 +485,41 @@ def test_html_report_includes_provenance_metadata(tmp_path: Path) -> None:
         },
         block_groups={},
         segment_groups={},
-        report_meta={
-            "codeclone_version": "1.3.0",
-            "python_version": "3.13",
-            "baseline_path": "/repo/codeclone.baseline.json",
-            "baseline_version": "1.3.0",
-            "baseline_schema_version": 1,
-            "baseline_python_version": "3.13",
-            "baseline_loaded": True,
-            "baseline_status": "ok",
-            "cache_path": "/repo/.cache/codeclone/cache.json",
-            "cache_used": True,
-        },
+        report_meta=report_meta_factory(
+            codeclone_version="1.3.0",
+            baseline_schema_version=1,
+        ),
     )
-    assert "Report Provenance" in html
-    assert "CodeClone" in html
-    assert "Baseline schema" in html
-    assert 'data-baseline-status="ok"' in html
-    assert "/repo/codeclone.baseline.json" in html
-    assert 'data-cache-used="true"' in html
-
-
-def test_html_report_escapes_meta_and_title(tmp_path: Path) -> None:
+    expected = [
+        "Report Provenance",
+        "CodeClone",
+        "Baseline file",
+        "Baseline path",
+        "Baseline schema",
+        "Baseline generator version",
+        "Baseline payload sha256",
+        "Baseline payload verified",
+        "codeclone.baseline.json",
+        'data-baseline-status="ok"',
+        'data-baseline-payload-verified="true"',
+        'data-baseline-file="codeclone.baseline.json"',
+        "/repo/codeclone.baseline.json",
+        'data-cache-used="true"',
+        "Cache schema",
+        "Cache status",
+        'data-cache-schema-version="1.2"',
+        'data-cache-status="ok"',
+        'data-files-skipped-source-io="0"',
+        "Source IO skipped",
+    ]
+    for token in expected:
+        assert token in html
+
+
+def test_html_report_escapes_meta_and_title(
+    tmp_path: Path,
+    report_meta_factory: Callable[..., dict[str, object]],
+) -> None:
     f = tmp_path / "a.py"
     f.write_text("def f():\n    return 1\n", "utf-8")
     html = build_html_report(
@@ -146,11 +536,10 @@ def test_html_report_escapes_meta_and_title(tmp_path: Path) -> None:
         block_groups={},
         segment_groups={},
         title='<img src=x onerror="alert(1)">',
-        report_meta={
-            "baseline_path": '"/><script>alert(1)</script>',
-            "cache_path": 'x" onmouseover="alert(1)',
-            "baseline_status": "ok",
-        },
+        report_meta=report_meta_factory(
+            baseline_path='"/><script>alert(1)</script>',
+            cache_path='x" onmouseover="alert(1)',
+        ),
     )
     assert "<script>alert(1)</script>" not in html
     assert "&lt;img src=x onerror=&quot;alert(1)&quot;&gt;" in html
@@ -263,8 +652,8 @@ def test_html_and_json_group_order_consistent(tmp_path: Path) -> None:
     }
     html = build_html_report(func_groups=groups, block_groups={}, segment_groups={})
     json_report = json.loads(to_json_report(groups, {}, {}))
-    json_keys = list(json_report["function_clones"].keys())
-    assert json_keys == ["c", "a", "b"]
+    json_keys = list(json_report["groups"]["functions"].keys())
+    assert json_keys == ["a", "b", "c"]
     assert html.find('data-group-key="c"') < html.find('data-group-key="a"')
     assert html.find('data-group-key="a"') < html.find('data-group-key="b"')
 
@@ -570,9 +959,6 @@ def test_render_code_block_truncates_and_fallback(
 
 def test_pygments_css_get_style_defs_error(monkeypatch: pytest.MonkeyPatch) -> None:
     class _Fmt:
-        def __init__(self, *args: object, **kwargs: object) -> None:
-            return None
-
         def get_style_defs(self, _selector: str) -> str:
             raise RuntimeError("nope")
 
diff --git a/tests/test_report.py b/tests/test_report.py
index 0f16b59..8cfb179 100644
--- a/tests/test_report.py
+++ b/tests/test_report.py
@@ -1,20 +1,30 @@
 import ast
 import json
+from collections.abc import Callable
 from pathlib import Path
 from typing import cast
 
 import pytest
 
 import codeclone.report as report_mod
+from codeclone.contracts import REPORT_SCHEMA_VERSION
 from codeclone.report import (
+    GroupMap,
+    build_block_group_facts,
     build_block_groups,
     build_groups,
     build_segment_groups,
+    prepare_block_report_groups,
     prepare_segment_report_groups,
     to_json,
     to_json_report,
     to_text_report,
 )
+from tests._report_fixtures import (
+    REPEATED_STMT_HASH,
+    repeated_block_group_key,
+    write_repeated_assert_source,
+)
 
 
 def test_build_function_groups() -> None:
@@ -40,7 +50,180 @@ def test_block_groups_require_multiple_functions() -> None:
     assert len(groups) == 1
 
 
-def test_report_output_formats() -> None:
+def test_prepare_block_report_groups_merges_to_maximal_regions() -> None:
+    groups = {
+        "h": [
+            {
+                "block_hash": "h",
+                "filepath": "a.py",
+                "qualname": "mod:f",
+                "start_line": 20,
+                "end_line": 23,
+                "size": 4,
+            },
+            {
+                "block_hash": "h",
+                "filepath": "a.py",
+                "qualname": "mod:f",
+                "start_line": 10,
+                "end_line": 13,
+                "size": 4,
+            },
+            {
+                "block_hash": "h",
+                "filepath": "a.py",
+                "qualname": "mod:f",
+                "start_line": 13,
+                "end_line": 16,
+                "size": 4,
+            },
+            {
+                "block_hash": "h",
+                "filepath": "a.py",
+                "qualname": "mod:g",
+                "start_line": 10,
+                "end_line": 13,
+                "size": 4,
+            },
+        ]
+    }
+
+    prepared = prepare_block_report_groups(groups)
+    items = prepared["h"]
+    assert len(items) == 3
+
+    assert items[0]["qualname"] == "mod:f"
+    assert items[0]["start_line"] == 10
+    assert items[0]["end_line"] == 16
+    assert items[0]["size"] == 7
+
+    assert items[1]["qualname"] == "mod:f"
+    assert items[1]["start_line"] == 20
+    assert items[1]["end_line"] == 23
+    assert items[1]["size"] == 4
+
+    assert items[2]["qualname"] == "mod:g"
+    assert items[2]["start_line"] == 10
+    assert items[2]["end_line"] == 13
+    assert items[2]["size"] == 4
+
+
+def test_prepare_block_report_groups_skips_invalid_ranges() -> None:
+    groups = {
+        "h": [
+            {
+                "block_hash": "h",
+                "filepath": "a.py",
+                "qualname": "mod:f",
+                "start_line": "bad",
+                "end_line": 13,
+                "size": 4,
+            },
+            {
+                "block_hash": "h",
+                "filepath": "a.py",
+                "qualname": "mod:f",
+                "start_line": 30,
+                "end_line": 33,
+                "size": 4,
+            },
+        ]
+    }
+    prepared = prepare_block_report_groups(groups)
+    assert len(prepared["h"]) == 1
+    assert prepared["h"][0]["start_line"] == 30
+    assert prepared["h"][0]["end_line"] == 33
+
+
+def test_prepare_block_report_groups_all_invalid_ranges_fallback_sorted() -> None:
+    groups: GroupMap = {
+        "h": [
+            {
+                "block_hash": "h",
+                "filepath": "b.py",
+                "qualname": "mod:f",
+                "start_line": "bad",
+                "end_line": 13,
+                "size": 4,
+            },
+            {
+                "block_hash": "h",
+                "filepath": "a.py",
+                "qualname": "mod:f",
+                "start_line": None,
+                "end_line": 1,
+                "size": 4,
+            },
+        ]
+    }
+    prepared = prepare_block_report_groups(groups)
+    items = prepared["h"]
+    assert len(items) == 2
+    assert items[0]["filepath"] == "a.py"
+    assert items[1]["filepath"] == "b.py"
+
+
+def test_prepare_block_report_groups_handles_empty_item_list() -> None:
+    groups: GroupMap = {"h": []}
+    prepared = prepare_block_report_groups(groups)
+    assert prepared["h"] == []
+
+
+def test_build_block_group_facts_assert_only(tmp_path: Path) -> None:
+    group_key = repeated_block_group_key()
+    test_file = write_repeated_assert_source(tmp_path / "test_repeated_asserts.py")
+    facts = build_block_group_facts(
+        {
+            group_key: [
+                {
+                    "qualname": "pkg.mod:f",
+                    "filepath": str(test_file),
+                    "start_line": 2,
+                    "end_line": 5,
+                }
+            ]
+        }
+    )
+    group = facts[group_key]
+    assert group["match_rule"] == "normalized_sliding_window"
+    assert group["block_size"] == "4"
+    assert group["signature_kind"] == "stmt_hash_sequence"
+    assert group["merged_regions"] == "true"
+    assert group["pattern"] == "repeated_stmt_hash"
+    assert group["pattern_display"] == f"{REPEATED_STMT_HASH[:12]} x4"
+    assert group["hint"] == "assert_only"
+    assert group["hint_label"] == "Assert-only block"
+    assert group["hint_confidence"] == "deterministic"
+    assert group["assert_ratio"] == "100%"
+    assert group["consecutive_asserts"] == "4"
+    assert group["group_display_name"] == "Assert pattern block"
+    assert group["group_arity"] == "1"
+    assert group["instance_peer_count"] == "0"
+
+
+def test_build_block_group_facts_deterministic_item_order(tmp_path: Path) -> None:
+    group_key = repeated_block_group_key()
+    test_file = write_repeated_assert_source(tmp_path / "test_repeated_asserts.py")
+    item_a = {
+        "qualname": "pkg.mod:f",
+        "filepath": str(test_file),
+        "start_line": 2,
+        "end_line": 5,
+    }
+    item_b = {
+        "qualname": "pkg.mod:f",
+        "filepath": str(test_file),
+        "start_line": 2,
+        "end_line": 5,
+    }
+    facts_a = build_block_group_facts({group_key: [item_a, item_b]})
+    facts_b = build_block_group_facts({group_key: [item_b, item_a]})
+    assert facts_a == facts_b
+
+
+def test_report_output_formats(
+    report_meta_factory: Callable[..., dict[str, object]],
+) -> None:
     groups = {
         "k1": [
             {
@@ -68,18 +251,12 @@ def test_report_output_formats() -> None:
             },
         ],
     }
-    meta = {
-        "codeclone_version": "1.3.0",
-        "python_version": "3.13",
-        "baseline_path": "/tmp/codeclone.baseline.json",
-        "baseline_version": "1.3.0",
-        "baseline_schema_version": 1,
-        "baseline_python_version": "3.13",
-        "baseline_loaded": True,
-        "baseline_status": "ok",
-        "cache_path": "/tmp/cache.json",
-        "cache_used": True,
-    }
+    meta = report_meta_factory(
+        codeclone_version="1.3.0",
+        baseline_path="/tmp/codeclone.baseline.json",
+        baseline_schema_version=1,
+        cache_path="/tmp/cache.json",
+    )
     json_out = to_json(groups)
     report_out = to_json_report(groups, groups, {}, meta)
     text_out = to_text_report(
@@ -89,13 +266,42 @@ def test_report_output_formats() -> None:
         segment_groups={},
     )
 
-    assert "group_count" in json_out
-    assert '"meta"' in report_out
-    assert '"function_clones"' in report_out
-    assert '"baseline_schema_version": 1' in report_out
-    assert "REPORT METADATA" in text_out
-    assert "Baseline schema version: 1" in text_out
-    assert "Clone group #1" in text_out
+    expected_json = ["group_count"]
+    expected_report = [
+        '"meta"',
+        '"groups"',
+        '"groups_split"',
+        '"group_item_layout"',
+        f'"report_schema_version": "{REPORT_SCHEMA_VERSION}"',
+        '"baseline_schema_version": 1',
+        f'"baseline_payload_sha256": "{"a" * 64}"',
+        '"baseline_payload_sha256_verified": true',
+        '"cache_schema_version": "1.2"',
+        '"cache_status": "ok"',
+        '"files_skipped_source_io": 0',
+    ]
+    expected_text = [
+        "REPORT METADATA",
+        "Report schema version: 1.1",
+        "Python tag: cp313",
+        "Baseline schema version: 1",
+        "Baseline generator name: codeclone",
+        f"Baseline payload sha256: {'a' * 64}",
+        "Baseline payload verified: true",
+        "Cache schema version: 1.2",
+        "Cache status: ok",
+        "Source IO skipped: 0",
+        "FUNCTION CLONES (NEW) (groups=2)",
+        "FUNCTION CLONES (KNOWN) (groups=0)",
+        "Clone group #1",
+    ]
+
+    for token in expected_json:
+        assert token in json_out
+    for token in expected_report:
+        assert token in report_out
+    for token in expected_text:
+        assert token in text_out
 
 
 def test_report_json_deterministic_group_order() -> None:
@@ -126,7 +332,7 @@ def test_report_json_deterministic_group_order() -> None:
     assert out_a == out_b
 
 
-def test_report_json_group_order_prefers_size_then_key() -> None:
+def test_report_json_group_order_is_lexicographic() -> None:
     groups = {
         "b": [
             {
@@ -165,7 +371,7 @@ def test_report_json_group_order_prefers_size_then_key() -> None:
     }
     payload = to_json_report(groups, {}, {}, {"codeclone_version": "1.3.0"})
     report_obj = json.loads(payload)
-    assert list(report_obj["function_clones"].keys()) == ["c", "a", "b"]
+    assert list(report_obj["groups"]["functions"].keys()) == ["a", "b", "c"]
 
 
 def test_report_json_deterministic_with_shuffled_units() -> None:
@@ -198,6 +404,241 @@ def test_report_json_deterministic_with_shuffled_units() -> None:
     assert out_a == out_b
 
 
+def test_report_json_compact_v11_contract() -> None:
+    groups = {
+        "g1": [
+            {
+                "qualname": "m:a",
+                "filepath": "z.py",
+                "start_line": 3,
+                "end_line": 4,
+                "loc": 2,
+                "stmt_count": 1,
+                "fingerprint": "fp-z",
+                "loc_bucket": "0-19",
+            },
+            {
+                "qualname": "m:b",
+                "filepath": "a.py",
+                "start_line": 1,
+                "end_line": 2,
+                "loc": 2,
+                "stmt_count": 1,
+                "fingerprint": "fp-a",
+                "loc_bucket": "0-19",
+            },
+        ]
+    }
+    payload = json.loads(to_json_report(groups, {}, {}, {"codeclone_version": "1.4.0"}))
+
+    assert payload["meta"]["report_schema_version"] == REPORT_SCHEMA_VERSION
+    assert payload["files"] == ["a.py", "z.py"]
+    assert set(payload["groups"]) == {"functions", "blocks", "segments"}
+    assert payload["groups_split"] == {
+        "functions": {"new": ["g1"], "known": []},
+        "blocks": {"new": [], "known": []},
+        "segments": {"new": [], "known": []},
+    }
+    assert payload["meta"]["groups_counts"] == {
+        "functions": {"total": 1, "new": 1, "known": 0},
+        "blocks": {"total": 0, "new": 0, "known": 0},
+        "segments": {"total": 0, "new": 0, "known": 0},
+    }
+    assert payload["group_item_layout"] == {
+        "functions": [
+            "file_i",
+            "qualname",
+            "start",
+            "end",
+            "loc",
+            "stmt_count",
+            "fingerprint",
+            "loc_bucket",
+        ],
+        "blocks": ["file_i", "qualname", "start", "end", "size"],
+        "segments": [
+            "file_i",
+            "qualname",
+            "start",
+            "end",
+            "size",
+            "segment_hash",
+            "segment_sig",
+        ],
+    }
+    assert "function_clones" not in payload
+    assert "block_clones" not in payload
+    assert "segment_clones" not in payload
+
+    function_rows = payload["groups"]["functions"]["g1"]
+    assert function_rows == [
+        [0, "m:b", 1, 2, 2, 1, "fp-a", "0-19"],
+        [1, "m:a", 3, 4, 2, 1, "fp-z", "0-19"],
+    ]
+
+
+def test_report_json_block_records_do_not_repeat_group_hash() -> None:
+    block_group_key = "hash-a|hash-b|hash-c|hash-d"
+    payload = json.loads(
+        to_json_report(
+            {},
+            {
+                block_group_key: [
+                    {
+                        "qualname": "m:f",
+                        "filepath": "a.py",
+                        "start_line": 10,
+                        "end_line": 13,
+                        "size": 4,
+                    }
+                ]
+            },
+            {},
+            {"codeclone_version": "1.4.0"},
+        )
+    )
+    rows = payload["groups"]["blocks"][block_group_key]
+    assert rows == [[0, "m:f", 10, 13, 4]]
+
+
+def test_report_json_includes_sorted_block_facts() -> None:
+    payload = json.loads(
+        to_json_report(
+            {},
+            {},
+            {},
+            {"codeclone_version": "1.4.0"},
+            block_facts={
+                "group-b": {"z": "3", "a": "x"},
+                "group-a": {"k": "v"},
+            },
+        )
+    )
+    assert payload["facts"] == {
+        "blocks": {
+            "group-a": {"k": "v"},
+            "group-b": {"a": "x", "z": "3"},
+        }
+    }
+
+
+def test_report_json_groups_split_trusted_baseline() -> None:
+    func_groups = {
+        "func-known": [
+            {
+                "qualname": "m:fk",
+                "filepath": "a.py",
+                "start_line": 1,
+                "end_line": 2,
+                "loc": 2,
+                "stmt_count": 1,
+                "fingerprint": "fp-k",
+                "loc_bucket": "0-19",
+            }
+        ],
+        "func-new": [
+            {
+                "qualname": "m:fn",
+                "filepath": "b.py",
+                "start_line": 3,
+                "end_line": 4,
+                "loc": 2,
+                "stmt_count": 1,
+                "fingerprint": "fp-n",
+                "loc_bucket": "0-19",
+            }
+        ],
+    }
+    block_groups = {
+        "block-known": [
+            {
+                "qualname": "m:bk",
+                "filepath": "a.py",
+                "start_line": 10,
+                "end_line": 13,
+                "size": 4,
+            }
+        ],
+        "block-new": [
+            {
+                "qualname": "m:bn",
+                "filepath": "b.py",
+                "start_line": 20,
+                "end_line": 23,
+                "size": 4,
+            }
+        ],
+    }
+    segment_groups = {
+        "segment-new": [
+            {
+                "qualname": "m:sn",
+                "filepath": "b.py",
+                "start_line": 30,
+                "end_line": 35,
+                "size": 6,
+                "segment_hash": "seg-h",
+                "segment_sig": "seg-s",
+            }
+        ]
+    }
+    payload = json.loads(
+        to_json_report(
+            func_groups,
+            block_groups,
+            segment_groups,
+            {"baseline_loaded": True, "baseline_status": "ok"},
+            new_function_group_keys={"func-new"},
+            new_block_group_keys={"block-new"},
+            new_segment_group_keys={"segment-new"},
+        )
+    )
+    split = payload["groups_split"]
+    assert split["functions"] == {"new": ["func-new"], "known": ["func-known"]}
+    assert split["blocks"] == {"new": ["block-new"], "known": ["block-known"]}
+    assert split["segments"] == {"new": ["segment-new"], "known": []}
+    for section_name in ("functions", "blocks", "segments"):
+        new_keys = set(split[section_name]["new"])
+        known_keys = set(split[section_name]["known"])
+        group_keys = set(payload["groups"][section_name].keys())
+        assert new_keys.isdisjoint(known_keys)
+        assert new_keys | known_keys == group_keys
+        counts = payload["meta"]["groups_counts"][section_name]
+        assert counts["total"] == len(group_keys)
+        assert counts["new"] == len(new_keys)
+        assert counts["known"] == len(known_keys)
+
+
+def test_report_json_groups_split_untrusted_baseline() -> None:
+    func_groups = {
+        "func-a": [
+            {
+                "qualname": "m:f",
+                "filepath": "a.py",
+                "start_line": 1,
+                "end_line": 2,
+                "loc": 2,
+                "stmt_count": 1,
+                "fingerprint": "fp-a",
+                "loc_bucket": "0-19",
+            }
+        ]
+    }
+    payload = json.loads(
+        to_json_report(
+            func_groups,
+            {},
+            {},
+            {"baseline_loaded": False, "baseline_status": "integrity_failed"},
+            new_function_group_keys=set(),
+        )
+    )
+    split = payload["groups_split"]
+    assert split["functions"] == {"new": ["func-a"], "known": []}
+    assert split["blocks"] == {"new": [], "known": []}
+    assert split["segments"] == {"new": [], "known": []}
+
+
 def test_text_report_deterministic_group_order() -> None:
     groups = {
         "b": [
@@ -236,13 +677,116 @@ def test_to_text_report_handles_missing_meta_fields() -> None:
         block_groups={},
         segment_groups={},
     )
-    assert "CodeClone version: n/a" in text_out
-    assert "Baseline status: n/a" in text_out
-    assert "Cache path:" not in text_out
-    assert "Cache used:" not in text_out
-    assert "FUNCTION CLONES\n(none)" in text_out
-    assert "BLOCK CLONES\n(none)" in text_out
-    assert "SEGMENT CLONES\n(none)" in text_out
+    assert "Report schema version: (none)" in text_out
+    assert "CodeClone version: (none)" in text_out
+    assert "Baseline status: (none)" in text_out
+    assert "Cache path: (none)" in text_out
+    assert "Cache used: (none)" in text_out
+    assert "Note: baseline is untrusted; all groups are treated as NEW." in text_out
+    assert "FUNCTION CLONES (NEW) (groups=0)\n(none)" in text_out
+    assert "FUNCTION CLONES (KNOWN) (groups=0)\n(none)" in text_out
+    assert "BLOCK CLONES (NEW) (groups=0)\n(none)" in text_out
+    assert "BLOCK CLONES (KNOWN) (groups=0)\n(none)" in text_out
+    assert "SEGMENT CLONES (NEW) (groups=0)\n(none)" in text_out
+    assert "SEGMENT CLONES (KNOWN) (groups=0)\n(none)" in text_out
+
+
+def test_to_text_report_uses_section_specific_metric_labels() -> None:
+    text_out = to_text_report(
+        meta={"codeclone_version": "1.4.0"},
+        func_groups={
+            "f": [
+                {
+                    "qualname": "pkg:f",
+                    "filepath": "a.py",
+                    "start_line": 1,
+                    "end_line": 10,
+                    "loc": 11,
+                }
+            ]
+        },
+        block_groups={
+            "b": [
+                {
+                    "qualname": "pkg:b",
+                    "filepath": "b.py",
+                    "start_line": 20,
+                    "end_line": 23,
+                    "size": 4,
+                }
+            ]
+        },
+        segment_groups={
+            "s": [
+                {
+                    "qualname": "pkg:s",
+                    "filepath": "c.py",
+                    "start_line": 30,
+                    "end_line": 35,
+                    "size": 6,
+                }
+            ]
+        },
+    )
+    assert "loc=11" in text_out
+    assert "size=4" in text_out
+    assert "size=6" in text_out
+
+
+def test_to_text_report_trusted_baseline_split_sections() -> None:
+    text_out = to_text_report(
+        meta={"baseline_loaded": True, "baseline_status": "ok"},
+        func_groups={
+            "func-known": [
+                {
+                    "qualname": "pkg:known",
+                    "filepath": "a.py",
+                    "start_line": 1,
+                    "end_line": 2,
+                    "loc": 2,
+                }
+            ],
+            "func-new": [
+                {
+                    "qualname": "pkg:new",
+                    "filepath": "b.py",
+                    "start_line": 3,
+                    "end_line": 4,
+                    "loc": 2,
+                }
+            ],
+        },
+        block_groups={},
+        segment_groups={},
+        new_function_group_keys={"func-new"},
+    )
+    assert "Note: baseline is untrusted" not in text_out
+    assert "FUNCTION CLONES (NEW) (groups=1)" in text_out
+    assert "FUNCTION CLONES (KNOWN) (groups=1)" in text_out
+    assert "pkg:new b.py:3-4 loc=2" in text_out
+    assert "pkg:known a.py:1-2 loc=2" in text_out
+
+
+def test_to_text_report_untrusted_baseline_known_sections_empty() -> None:
+    text_out = to_text_report(
+        meta={"baseline_loaded": False, "baseline_status": "mismatch_schema_version"},
+        func_groups={
+            "func-a": [
+                {
+                    "qualname": "pkg:a",
+                    "filepath": "a.py",
+                    "start_line": 1,
+                    "end_line": 2,
+                    "loc": 2,
+                }
+            ]
+        },
+        block_groups={},
+        segment_groups={},
+    )
+    assert "Note: baseline is untrusted; all groups are treated as NEW." in text_out
+    assert "FUNCTION CLONES (NEW) (groups=1)" in text_out
+    assert "FUNCTION CLONES (KNOWN) (groups=0)\n(none)" in text_out
 
 
 def test_segment_groups_internal_only() -> None:
@@ -614,7 +1158,7 @@ def test_segment_helpers_cover_edge_cases(tmp_path: Path) -> None:
     class Dummy:
         body = None
 
-    dummy = cast(ast.FunctionDef, Dummy())
+    dummy = cast(ast.FunctionDef, cast(object, Dummy()))
     assert report_mod._segment_statements(dummy, 1, 2) == []
 
     func = ast.parse("def f():\n    x = 1\n").body[0]
diff --git a/tests/test_report_explain.py b/tests/test_report_explain.py
new file mode 100644
index 0000000..f2e7314
--- /dev/null
+++ b/tests/test_report_explain.py
@@ -0,0 +1,229 @@
+from pathlib import Path
+
+from codeclone._report_explain import build_block_group_facts
+from tests._report_fixtures import (
+    repeated_block_group_key,
+    write_repeated_assert_source,
+)
+
+
+def test_build_block_group_facts_handles_missing_file() -> None:
+    group_key = repeated_block_group_key()
+    facts = build_block_group_facts(
+        {
+            group_key: [
+                {
+                    "qualname": "pkg.mod:f",
+                    "filepath": "/definitely/missing/file.py",
+                    "start_line": 10,
+                    "end_line": 20,
+                }
+            ]
+        }
+    )
+    group = facts[group_key]
+    assert group["match_rule"] == "normalized_sliding_window"
+    assert group["pattern"] == "repeated_stmt_hash"
+    assert "hint" not in group
+    assert "assert_ratio" not in group
+
+
+def test_build_block_group_facts_handles_syntax_error_file(tmp_path: Path) -> None:
+    group_key = repeated_block_group_key()
+    broken = tmp_path / "broken.py"
+    broken.write_text("def f(:\n    pass\n", "utf-8")
+    facts = build_block_group_facts(
+        {
+            group_key: [
+                {
+                    "qualname": "pkg.mod:f",
+                    "filepath": str(broken),
+                    "start_line": 1,
+                    "end_line": 2,
+                }
+            ]
+        }
+    )
+    assert "hint" not in facts[group_key]
+
+
+def test_build_block_group_facts_assert_detection_with_calls(tmp_path: Path) -> None:
+    group_key = repeated_block_group_key()
+    test_file = tmp_path / "test_calls.py"
+    test_file.write_text(
+        "def f(checker):\n"
+        '    "doc"\n'
+        "    assert_ok(checker)\n"
+        "    checker.assert_ready(checker)\n",
+        "utf-8",
+    )
+    facts = build_block_group_facts(
+        {
+            group_key: [
+                {
+                    "qualname": "tests.mod:f",
+                    "filepath": str(test_file),
+                    "start_line": 2,
+                    "end_line": 4,
+                }
+            ]
+        }
+    )
+    group = facts[group_key]
+    assert group["hint"] == "assert_only"
+    assert group["assert_ratio"] == "100%"
+    assert group["consecutive_asserts"] == "3"
+
+
+def test_build_block_group_facts_non_assert_breaks_hint(tmp_path: Path) -> None:
+    group_key = repeated_block_group_key()
+    test_file = tmp_path / "test_mixed.py"
+    test_file.write_text(
+        "def f(html):\n"
+        "    assert 'a' in html\n"
+        "    check(html)\n"
+        "    assert 'b' in html\n",
+        "utf-8",
+    )
+    facts = build_block_group_facts(
+        {
+            group_key: [
+                {
+                    "qualname": "tests.mod:f",
+                    "filepath": str(test_file),
+                    "start_line": 2,
+                    "end_line": 4,
+                }
+            ]
+        }
+    )
+    group = facts[group_key]
+    assert "hint" not in group
+    assert group["assert_ratio"] == "67%"
+    assert group["consecutive_asserts"] == "1"
+
+
+def test_build_block_group_facts_non_repeated_signature_has_no_pattern() -> None:
+    group_key = (
+        "0e8579f84e518d186950d012c9944a40cb872332|"
+        "1e8579f84e518d186950d012c9944a40cb872332|"
+        "2e8579f84e518d186950d012c9944a40cb872332|"
+        "3e8579f84e518d186950d012c9944a40cb872332"
+    )
+    facts = build_block_group_facts({group_key: []})
+    group = facts[group_key]
+    assert group["block_size"] == "4"
+    assert "pattern" not in group
+
+
+def test_build_block_group_facts_handles_empty_stmt_range(tmp_path: Path) -> None:
+    group_key = repeated_block_group_key()
+    test_file = tmp_path / "module.py"
+    test_file.write_text("def f():\n    return 1\n", "utf-8")
+    facts = build_block_group_facts(
+        {
+            group_key: [
+                {
+                    "qualname": "mod:f",
+                    "filepath": str(test_file),
+                    "start_line": 100,
+                    "end_line": 200,
+                }
+            ]
+        }
+    )
+    group = facts[group_key]
+    assert "assert_ratio" not in group
+    assert "hint" not in group
+
+
+def test_build_block_group_facts_non_assert_call_shapes(tmp_path: Path) -> None:
+    group_key = repeated_block_group_key()
+    test_file = tmp_path / "module.py"
+    test_file.write_text(
+        "def f(checker, x):\n    checker.validate(x)\n    (lambda y: y)(x)\n    x\n",
+        "utf-8",
+    )
+    facts = build_block_group_facts(
+        {
+            group_key: [
+                {
+                    "qualname": "mod:f",
+                    "filepath": str(test_file),
+                    "start_line": 2,
+                    "end_line": 4,
+                }
+            ]
+        }
+    )
+    group = facts[group_key]
+    assert group["assert_ratio"] == "0%"
+    assert group["consecutive_asserts"] == "0"
+    assert "hint" not in group
+
+
+def test_build_block_group_facts_invalid_item_disables_assert_hint() -> None:
+    group_key = repeated_block_group_key()
+    facts = build_block_group_facts(
+        {
+            group_key: [
+                {
+                    "qualname": "mod:f",
+                    "filepath": "",
+                    "start_line": 0,
+                    "end_line": 0,
+                }
+            ]
+        }
+    )
+    group = facts[group_key]
+    assert "hint" not in group
+    assert "assert_ratio" not in group
+
+
+def test_build_block_group_facts_assert_only_without_test_context(
+    tmp_path: Path,
+) -> None:
+    group_key = repeated_block_group_key()
+    prod_file = tmp_path / "module.py"
+    prod_file.write_text(
+        "def f(html):\n"
+        "    assert 'a' in html\n"
+        "    assert 'b' in html\n"
+        "    assert 'c' in html\n"
+        "    assert 'd' in html\n",
+        "utf-8",
+    )
+    facts = build_block_group_facts(
+        {
+            group_key: [
+                {
+                    "qualname": "pkg.mod:f",
+                    "filepath": str(prod_file),
+                    "start_line": 2,
+                    "end_line": 5,
+                }
+            ]
+        }
+    )
+    group = facts[group_key]
+    assert group["hint"] == "assert_only"
+    assert "hint_context" not in group
+
+
+def test_build_block_group_facts_n_way_group_compare_facts(tmp_path: Path) -> None:
+    group_key = repeated_block_group_key()
+    test_file = write_repeated_assert_source(tmp_path / "test_repeated_asserts.py")
+    item = {
+        "qualname": "pkg.mod:f",
+        "filepath": str(test_file),
+        "start_line": 2,
+        "end_line": 5,
+    }
+    facts = build_block_group_facts({group_key: [item, item, item]})
+    group = facts[group_key]
+    assert group["group_arity"] == "3"
+    assert group["instance_peer_count"] == "2"
+    assert group["group_compare_note"] == (
+        "N-way group: each block matches 2 peers in this group."
+    )
diff --git a/tests/test_security.py b/tests/test_security.py
index 56d0b00..9bf64a1 100644
--- a/tests/test_security.py
+++ b/tests/test_security.py
@@ -9,6 +9,7 @@
 from codeclone.errors import ValidationError
 from codeclone.html_report import build_html_report
 from codeclone.normalize import NormalizationConfig
+from codeclone.report import build_block_group_facts
 from codeclone.scanner import iter_py_files
 
 
@@ -73,6 +74,7 @@ def test_html_report_escapes_user_content(tmp_path: Path) -> None:
         func_groups=func_groups,
         block_groups={},
         segment_groups={},
+        block_group_facts=build_block_group_facts({}),
         title="Security",
     )
     assert "<script>alert(1)</script>" not in html
diff --git a/uv.lock b/uv.lock
index 611e943..85fa919 100644
--- a/uv.lock
+++ b/uv.lock
@@ -189,7 +189,7 @@ wheels = [
 
 [[package]]
 name = "codeclone"
-version = "1.3.0"
+version = "1.4.0"
 source = { editable = "." }
 dependencies = [
     { name = "pygments" },
@@ -232,101 +232,115 @@ wheels = [
 
 [[package]]
 name = "coverage"
-version = "7.13.2"
+version = "7.13.4"
 source = { registry = "https://pypi.org/simple" }
-sdist = { url = "https://files.pythonhosted.org/packages/ad/49/349848445b0e53660e258acbcc9b0d014895b6739237920886672240f84b/coverage-7.13.2.tar.gz", hash = "sha256:044c6951ec37146b72a50cc81ef02217d27d4c3640efd2640311393cbbf143d3", size = 826523, upload-time = "2026-01-25T13:00:04.889Z" }
+sdist = { url = "https://files.pythonhosted.org/packages/24/56/95b7e30fa389756cb56630faa728da46a27b8c6eb46f9d557c68fff12b65/coverage-7.13.4.tar.gz", hash = "sha256:e5c8f6ed1e61a8b2dcdf31eb0b9bbf0130750ca79c1c49eb898e2ad86f5ccc91", size = 827239, upload-time = "2026-02-09T12:59:03.86Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/a4/2d/63e37369c8e81a643afe54f76073b020f7b97ddbe698c5c944b51b0a2bc5/coverage-7.13.2-cp310-cp310-macosx_10_9_x86_64.whl", hash = "sha256:f4af3b01763909f477ea17c962e2cca8f39b350a4e46e3a30838b2c12e31b81b", size = 218842, upload-time = "2026-01-25T12:57:15.3Z" },
-    { url = "https://files.pythonhosted.org/packages/57/06/86ce882a8d58cbcb3030e298788988e618da35420d16a8c66dac34f138d0/coverage-7.13.2-cp310-cp310-macosx_11_0_arm64.whl", hash = "sha256:36393bd2841fa0b59498f75466ee9bdec4f770d3254f031f23e8fd8e140ffdd2", size = 219360, upload-time = "2026-01-25T12:57:17.572Z" },
-    { url = "https://files.pythonhosted.org/packages/cd/84/70b0eb1ee19ca4ef559c559054c59e5b2ae4ec9af61398670189e5d276e9/coverage-7.13.2-cp310-cp310-manylinux1_i686.manylinux_2_28_i686.manylinux_2_5_i686.whl", hash = "sha256:9cc7573518b7e2186bd229b1a0fe24a807273798832c27032c4510f47ffdb896", size = 246123, upload-time = "2026-01-25T12:57:19.087Z" },
-    { url = "https://files.pythonhosted.org/packages/35/fb/05b9830c2e8275ebc031e0019387cda99113e62bb500ab328bb72578183b/coverage-7.13.2-cp310-cp310-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl", hash = "sha256:ca9566769b69a5e216a4e176d54b9df88f29d750c5b78dbb899e379b4e14b30c", size = 247930, upload-time = "2026-01-25T12:57:20.929Z" },
-    { url = "https://files.pythonhosted.org/packages/81/aa/3f37858ca2eed4f09b10ca3c6ddc9041be0a475626cd7fd2712f4a2d526f/coverage-7.13.2-cp310-cp310-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:9c9bdea644e94fd66d75a6f7e9a97bb822371e1fe7eadae2cacd50fcbc28e4dc", size = 249804, upload-time = "2026-01-25T12:57:22.904Z" },
-    { url = "https://files.pythonhosted.org/packages/b6/b3/c904f40c56e60a2d9678a5ee8df3d906d297d15fb8bec5756c3b0a67e2df/coverage-7.13.2-cp310-cp310-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:5bd447332ec4f45838c1ad42268ce21ca87c40deb86eabd59888859b66be22a5", size = 246815, upload-time = "2026-01-25T12:57:24.314Z" },
-    { url = "https://files.pythonhosted.org/packages/41/91/ddc1c5394ca7fd086342486440bfdd6b9e9bda512bf774599c7c7a0081e0/coverage-7.13.2-cp310-cp310-musllinux_1_2_aarch64.whl", hash = "sha256:7c79ad5c28a16a1277e1187cf83ea8dafdcc689a784228a7d390f19776db7c31", size = 247843, upload-time = "2026-01-25T12:57:26.544Z" },
-    { url = "https://files.pythonhosted.org/packages/87/d2/cdff8f4cd33697883c224ea8e003e9c77c0f1a837dc41d95a94dd26aad67/coverage-7.13.2-cp310-cp310-musllinux_1_2_i686.whl", hash = "sha256:76e06ccacd1fb6ada5d076ed98a8c6f66e2e6acd3df02819e2ee29fd637b76ad", size = 245850, upload-time = "2026-01-25T12:57:28.507Z" },
-    { url = "https://files.pythonhosted.org/packages/f5/42/e837febb7866bf2553ab53dd62ed52f9bb36d60c7e017c55376ad21fbb05/coverage-7.13.2-cp310-cp310-musllinux_1_2_riscv64.whl", hash = "sha256:49d49e9a5e9f4dc3d3dac95278a020afa6d6bdd41f63608a76fa05a719d5b66f", size = 246116, upload-time = "2026-01-25T12:57:30.16Z" },
-    { url = "https://files.pythonhosted.org/packages/09/b1/4a3f935d7df154df02ff4f71af8d61298d713a7ba305d050ae475bfbdde2/coverage-7.13.2-cp310-cp310-musllinux_1_2_x86_64.whl", hash = "sha256:ed2bce0e7bfa53f7b0b01c722da289ef6ad4c18ebd52b1f93704c21f116360c8", size = 246720, upload-time = "2026-01-25T12:57:32.165Z" },
-    { url = "https://files.pythonhosted.org/packages/e1/fe/538a6fd44c515f1c5197a3f078094cbaf2ce9f945df5b44e29d95c864bff/coverage-7.13.2-cp310-cp310-win32.whl", hash = "sha256:1574983178b35b9af4db4a9f7328a18a14a0a0ce76ffaa1c1bacb4cc82089a7c", size = 221465, upload-time = "2026-01-25T12:57:33.511Z" },
-    { url = "https://files.pythonhosted.org/packages/5e/09/4b63a024295f326ec1a40ec8def27799300ce8775b1cbf0d33b1790605c4/coverage-7.13.2-cp310-cp310-win_amd64.whl", hash = "sha256:a360a8baeb038928ceb996f5623a4cd508728f8f13e08d4e96ce161702f3dd99", size = 222397, upload-time = "2026-01-25T12:57:34.927Z" },
-    { url = "https://files.pythonhosted.org/packages/6c/01/abca50583a8975bb6e1c59eff67ed8e48bb127c07dad5c28d9e96ccc09ec/coverage-7.13.2-cp311-cp311-macosx_10_9_x86_64.whl", hash = "sha256:060ebf6f2c51aff5ba38e1f43a2095e087389b1c69d559fde6049a4b0001320e", size = 218971, upload-time = "2026-01-25T12:57:36.953Z" },
-    { url = "https://files.pythonhosted.org/packages/eb/0e/b6489f344d99cd1e5b4d5e1be52dfd3f8a3dc5112aa6c33948da8cabad4e/coverage-7.13.2-cp311-cp311-macosx_11_0_arm64.whl", hash = "sha256:c1ea8ca9db5e7469cd364552985e15911548ea5b69c48a17291f0cac70484b2e", size = 219473, upload-time = "2026-01-25T12:57:38.934Z" },
-    { url = "https://files.pythonhosted.org/packages/17/11/db2f414915a8e4ec53f60b17956c27f21fb68fcf20f8a455ce7c2ccec638/coverage-7.13.2-cp311-cp311-manylinux1_i686.manylinux_2_28_i686.manylinux_2_5_i686.whl", hash = "sha256:b780090d15fd58f07cf2011943e25a5f0c1c894384b13a216b6c86c8a8a7c508", size = 249896, upload-time = "2026-01-25T12:57:40.365Z" },
-    { url = "https://files.pythonhosted.org/packages/80/06/0823fe93913663c017e508e8810c998c8ebd3ec2a5a85d2c3754297bdede/coverage-7.13.2-cp311-cp311-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl", hash = "sha256:88a800258d83acb803c38175b4495d293656d5fac48659c953c18e5f539a274b", size = 251810, upload-time = "2026-01-25T12:57:42.045Z" },
-    { url = "https://files.pythonhosted.org/packages/61/dc/b151c3cc41b28cdf7f0166c5fa1271cbc305a8ec0124cce4b04f74791a18/coverage-7.13.2-cp311-cp311-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:6326e18e9a553e674d948536a04a80d850a5eeefe2aae2e6d7cf05d54046c01b", size = 253920, upload-time = "2026-01-25T12:57:44.026Z" },
-    { url = "https://files.pythonhosted.org/packages/2d/35/e83de0556e54a4729a2b94ea816f74ce08732e81945024adee46851c2264/coverage-7.13.2-cp311-cp311-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:59562de3f797979e1ff07c587e2ac36ba60ca59d16c211eceaa579c266c5022f", size = 250025, upload-time = "2026-01-25T12:57:45.624Z" },
-    { url = "https://files.pythonhosted.org/packages/39/67/af2eb9c3926ce3ea0d58a0d2516fcbdacf7a9fc9559fe63076beaf3f2596/coverage-7.13.2-cp311-cp311-musllinux_1_2_aarch64.whl", hash = "sha256:27ba1ed6f66b0e2d61bfa78874dffd4f8c3a12f8e2b5410e515ab345ba7bc9c3", size = 251612, upload-time = "2026-01-25T12:57:47.713Z" },
-    { url = "https://files.pythonhosted.org/packages/26/62/5be2e25f3d6c711d23b71296f8b44c978d4c8b4e5b26871abfc164297502/coverage-7.13.2-cp311-cp311-musllinux_1_2_i686.whl", hash = "sha256:8be48da4d47cc68754ce643ea50b3234557cbefe47c2f120495e7bd0a2756f2b", size = 249670, upload-time = "2026-01-25T12:57:49.378Z" },
-    { url = "https://files.pythonhosted.org/packages/b3/51/400d1b09a8344199f9b6a6fc1868005d766b7ea95e7882e494fa862ca69c/coverage-7.13.2-cp311-cp311-musllinux_1_2_riscv64.whl", hash = "sha256:2a47a4223d3361b91176aedd9d4e05844ca67d7188456227b6bf5e436630c9a1", size = 249395, upload-time = "2026-01-25T12:57:50.86Z" },
-    { url = "https://files.pythonhosted.org/packages/e0/36/f02234bc6e5230e2f0a63fd125d0a2093c73ef20fdf681c7af62a140e4e7/coverage-7.13.2-cp311-cp311-musllinux_1_2_x86_64.whl", hash = "sha256:c6f141b468740197d6bd38f2b26ade124363228cc3f9858bd9924ab059e00059", size = 250298, upload-time = "2026-01-25T12:57:52.287Z" },
-    { url = "https://files.pythonhosted.org/packages/b0/06/713110d3dd3151b93611c9cbfc65c15b4156b44f927fced49ac0b20b32a4/coverage-7.13.2-cp311-cp311-win32.whl", hash = "sha256:89567798404af067604246e01a49ef907d112edf2b75ef814b1364d5ce267031", size = 221485, upload-time = "2026-01-25T12:57:53.876Z" },
-    { url = "https://files.pythonhosted.org/packages/16/0c/3ae6255fa1ebcb7dec19c9a59e85ef5f34566d1265c70af5b2fc981da834/coverage-7.13.2-cp311-cp311-win_amd64.whl", hash = "sha256:21dd57941804ae2ac7e921771a5e21bbf9aabec317a041d164853ad0a96ce31e", size = 222421, upload-time = "2026-01-25T12:57:55.433Z" },
-    { url = "https://files.pythonhosted.org/packages/b5/37/fabc3179af4d61d89ea47bd04333fec735cd5e8b59baad44fed9fc4170d7/coverage-7.13.2-cp311-cp311-win_arm64.whl", hash = "sha256:10758e0586c134a0bafa28f2d37dd2cdb5e4a90de25c0fc0c77dabbad46eca28", size = 221088, upload-time = "2026-01-25T12:57:57.41Z" },
-    { url = "https://files.pythonhosted.org/packages/46/39/e92a35f7800222d3f7b2cbb7bbc3b65672ae8d501cb31801b2d2bd7acdf1/coverage-7.13.2-cp312-cp312-macosx_10_13_x86_64.whl", hash = "sha256:f106b2af193f965d0d3234f3f83fc35278c7fb935dfbde56ae2da3dd2c03b84d", size = 219142, upload-time = "2026-01-25T12:58:00.448Z" },
-    { url = "https://files.pythonhosted.org/packages/45/7a/8bf9e9309c4c996e65c52a7c5a112707ecdd9fbaf49e10b5a705a402bbb4/coverage-7.13.2-cp312-cp312-macosx_11_0_arm64.whl", hash = "sha256:78f45d21dc4d5d6bd29323f0320089ef7eae16e4bef712dff79d184fa7330af3", size = 219503, upload-time = "2026-01-25T12:58:02.451Z" },
-    { url = "https://files.pythonhosted.org/packages/87/93/17661e06b7b37580923f3f12406ac91d78aeed293fb6da0b69cc7957582f/coverage-7.13.2-cp312-cp312-manylinux1_i686.manylinux_2_28_i686.manylinux_2_5_i686.whl", hash = "sha256:fae91dfecd816444c74531a9c3d6ded17a504767e97aa674d44f638107265b99", size = 251006, upload-time = "2026-01-25T12:58:04.059Z" },
-    { url = "https://files.pythonhosted.org/packages/12/f0/f9e59fb8c310171497f379e25db060abef9fa605e09d63157eebec102676/coverage-7.13.2-cp312-cp312-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl", hash = "sha256:264657171406c114787b441484de620e03d8f7202f113d62fcd3d9688baa3e6f", size = 253750, upload-time = "2026-01-25T12:58:05.574Z" },
-    { url = "https://files.pythonhosted.org/packages/e5/b1/1935e31add2232663cf7edd8269548b122a7d100047ff93475dbaaae673e/coverage-7.13.2-cp312-cp312-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:ae47d8dcd3ded0155afbb59c62bd8ab07ea0fd4902e1c40567439e6db9dcaf2f", size = 254862, upload-time = "2026-01-25T12:58:07.647Z" },
-    { url = "https://files.pythonhosted.org/packages/af/59/b5e97071ec13df5f45da2b3391b6cdbec78ba20757bc92580a5b3d5fa53c/coverage-7.13.2-cp312-cp312-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:8a0b33e9fd838220b007ce8f299114d406c1e8edb21336af4c97a26ecfd185aa", size = 251420, upload-time = "2026-01-25T12:58:09.309Z" },
-    { url = "https://files.pythonhosted.org/packages/3f/75/9495932f87469d013dc515fb0ce1aac5fa97766f38f6b1a1deb1ee7b7f3a/coverage-7.13.2-cp312-cp312-musllinux_1_2_aarch64.whl", hash = "sha256:b3becbea7f3ce9a2d4d430f223ec15888e4deb31395840a79e916368d6004cce", size = 252786, upload-time = "2026-01-25T12:58:10.909Z" },
-    { url = "https://files.pythonhosted.org/packages/6a/59/af550721f0eb62f46f7b8cb7e6f1860592189267b1c411a4e3a057caacee/coverage-7.13.2-cp312-cp312-musllinux_1_2_i686.whl", hash = "sha256:f819c727a6e6eeb8711e4ce63d78c620f69630a2e9d53bc95ca5379f57b6ba94", size = 250928, upload-time = "2026-01-25T12:58:12.449Z" },
-    { url = "https://files.pythonhosted.org/packages/9b/b1/21b4445709aae500be4ab43bbcfb4e53dc0811c3396dcb11bf9f23fd0226/coverage-7.13.2-cp312-cp312-musllinux_1_2_riscv64.whl", hash = "sha256:4f7b71757a3ab19f7ba286e04c181004c1d61be921795ee8ba6970fd0ec91da5", size = 250496, upload-time = "2026-01-25T12:58:14.047Z" },
-    { url = "https://files.pythonhosted.org/packages/ba/b1/0f5d89dfe0392990e4f3980adbde3eb34885bc1effb2dc369e0bf385e389/coverage-7.13.2-cp312-cp312-musllinux_1_2_x86_64.whl", hash = "sha256:b7fc50d2afd2e6b4f6f2f403b70103d280a8e0cb35320cbbe6debcda02a1030b", size = 252373, upload-time = "2026-01-25T12:58:15.976Z" },
-    { url = "https://files.pythonhosted.org/packages/01/c9/0cf1a6a57a9968cc049a6b896693faa523c638a5314b1fc374eb2b2ac904/coverage-7.13.2-cp312-cp312-win32.whl", hash = "sha256:292250282cf9bcf206b543d7608bda17ca6fc151f4cbae949fc7e115112fbd41", size = 221696, upload-time = "2026-01-25T12:58:17.517Z" },
-    { url = "https://files.pythonhosted.org/packages/4d/05/d7540bf983f09d32803911afed135524570f8c47bb394bf6206c1dc3a786/coverage-7.13.2-cp312-cp312-win_amd64.whl", hash = "sha256:eeea10169fac01549a7921d27a3e517194ae254b542102267bef7a93ed38c40e", size = 222504, upload-time = "2026-01-25T12:58:19.115Z" },
-    { url = "https://files.pythonhosted.org/packages/15/8b/1a9f037a736ced0a12aacf6330cdaad5008081142a7070bc58b0f7930cbc/coverage-7.13.2-cp312-cp312-win_arm64.whl", hash = "sha256:2a5b567f0b635b592c917f96b9a9cb3dbd4c320d03f4bf94e9084e494f2e8894", size = 221120, upload-time = "2026-01-25T12:58:21.334Z" },
-    { url = "https://files.pythonhosted.org/packages/a7/f0/3d3eac7568ab6096ff23791a526b0048a1ff3f49d0e236b2af6fb6558e88/coverage-7.13.2-cp313-cp313-macosx_10_13_x86_64.whl", hash = "sha256:ed75de7d1217cf3b99365d110975f83af0528c849ef5180a12fd91b5064df9d6", size = 219168, upload-time = "2026-01-25T12:58:23.376Z" },
-    { url = "https://files.pythonhosted.org/packages/a3/a6/f8b5cfeddbab95fdef4dcd682d82e5dcff7a112ced57a959f89537ee9995/coverage-7.13.2-cp313-cp313-macosx_11_0_arm64.whl", hash = "sha256:97e596de8fa9bada4d88fde64a3f4d37f1b6131e4faa32bad7808abc79887ddc", size = 219537, upload-time = "2026-01-25T12:58:24.932Z" },
-    { url = "https://files.pythonhosted.org/packages/7b/e6/8d8e6e0c516c838229d1e41cadcec91745f4b1031d4db17ce0043a0423b4/coverage-7.13.2-cp313-cp313-manylinux1_i686.manylinux_2_28_i686.manylinux_2_5_i686.whl", hash = "sha256:68c86173562ed4413345410c9480a8d64864ac5e54a5cda236748031e094229f", size = 250528, upload-time = "2026-01-25T12:58:26.567Z" },
-    { url = "https://files.pythonhosted.org/packages/8e/78/befa6640f74092b86961f957f26504c8fba3d7da57cc2ab7407391870495/coverage-7.13.2-cp313-cp313-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl", hash = "sha256:7be4d613638d678b2b3773b8f687537b284d7074695a43fe2fbbfc0e31ceaed1", size = 253132, upload-time = "2026-01-25T12:58:28.251Z" },
-    { url = "https://files.pythonhosted.org/packages/9d/10/1630db1edd8ce675124a2ee0f7becc603d2bb7b345c2387b4b95c6907094/coverage-7.13.2-cp313-cp313-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:d7f63ce526a96acd0e16c4af8b50b64334239550402fb1607ce6a584a6d62ce9", size = 254374, upload-time = "2026-01-25T12:58:30.294Z" },
-    { url = "https://files.pythonhosted.org/packages/ed/1d/0d9381647b1e8e6d310ac4140be9c428a0277330991e0c35bdd751e338a4/coverage-7.13.2-cp313-cp313-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:406821f37f864f968e29ac14c3fccae0fec9fdeba48327f0341decf4daf92d7c", size = 250762, upload-time = "2026-01-25T12:58:32.036Z" },
-    { url = "https://files.pythonhosted.org/packages/43/e4/5636dfc9a7c871ee8776af83ee33b4c26bc508ad6cee1e89b6419a366582/coverage-7.13.2-cp313-cp313-musllinux_1_2_aarch64.whl", hash = "sha256:ee68e5a4e3e5443623406b905db447dceddffee0dceb39f4e0cd9ec2a35004b5", size = 252502, upload-time = "2026-01-25T12:58:33.961Z" },
-    { url = "https://files.pythonhosted.org/packages/02/2a/7ff2884d79d420cbb2d12fed6fff727b6d0ef27253140d3cdbbd03187ee0/coverage-7.13.2-cp313-cp313-musllinux_1_2_i686.whl", hash = "sha256:2ee0e58cca0c17dd9c6c1cdde02bb705c7b3fbfa5f3b0b5afeda20d4ebff8ef4", size = 250463, upload-time = "2026-01-25T12:58:35.529Z" },
-    { url = "https://files.pythonhosted.org/packages/91/c0/ba51087db645b6c7261570400fc62c89a16278763f36ba618dc8657a187b/coverage-7.13.2-cp313-cp313-musllinux_1_2_riscv64.whl", hash = "sha256:6e5bbb5018bf76a56aabdb64246b5288d5ae1b7d0dd4d0534fe86df2c2992d1c", size = 250288, upload-time = "2026-01-25T12:58:37.226Z" },
-    { url = "https://files.pythonhosted.org/packages/03/07/44e6f428551c4d9faf63ebcefe49b30e5c89d1be96f6a3abd86a52da9d15/coverage-7.13.2-cp313-cp313-musllinux_1_2_x86_64.whl", hash = "sha256:a55516c68ef3e08e134e818d5e308ffa6b1337cc8b092b69b24287bf07d38e31", size = 252063, upload-time = "2026-01-25T12:58:38.821Z" },
-    { url = "https://files.pythonhosted.org/packages/c2/67/35b730ad7e1859dd57e834d1bc06080d22d2f87457d53f692fce3f24a5a9/coverage-7.13.2-cp313-cp313-win32.whl", hash = "sha256:5b20211c47a8abf4abc3319d8ce2464864fa9f30c5fcaf958a3eed92f4f1fef8", size = 221716, upload-time = "2026-01-25T12:58:40.484Z" },
-    { url = "https://files.pythonhosted.org/packages/0d/82/e5fcf5a97c72f45fc14829237a6550bf49d0ab882ac90e04b12a69db76b4/coverage-7.13.2-cp313-cp313-win_amd64.whl", hash = "sha256:14f500232e521201cf031549fb1ebdfc0a40f401cf519157f76c397e586c3beb", size = 222522, upload-time = "2026-01-25T12:58:43.247Z" },
-    { url = "https://files.pythonhosted.org/packages/b1/f1/25d7b2f946d239dd2d6644ca2cc060d24f97551e2af13b6c24c722ae5f97/coverage-7.13.2-cp313-cp313-win_arm64.whl", hash = "sha256:9779310cb5a9778a60c899f075a8514c89fa6d10131445c2207fc893e0b14557", size = 221145, upload-time = "2026-01-25T12:58:45Z" },
-    { url = "https://files.pythonhosted.org/packages/9e/f7/080376c029c8f76fadfe43911d0daffa0cbdc9f9418a0eead70c56fb7f4b/coverage-7.13.2-cp313-cp313t-macosx_10_13_x86_64.whl", hash = "sha256:e64fa5a1e41ce5df6b547cbc3d3699381c9e2c2c369c67837e716ed0f549d48e", size = 219861, upload-time = "2026-01-25T12:58:46.586Z" },
-    { url = "https://files.pythonhosted.org/packages/42/11/0b5e315af5ab35f4c4a70e64d3314e4eec25eefc6dec13be3a7d5ffe8ac5/coverage-7.13.2-cp313-cp313t-macosx_11_0_arm64.whl", hash = "sha256:b01899e82a04085b6561eb233fd688474f57455e8ad35cd82286463ba06332b7", size = 220207, upload-time = "2026-01-25T12:58:48.277Z" },
-    { url = "https://files.pythonhosted.org/packages/b2/0c/0874d0318fb1062117acbef06a09cf8b63f3060c22265adaad24b36306b7/coverage-7.13.2-cp313-cp313t-manylinux1_i686.manylinux_2_28_i686.manylinux_2_5_i686.whl", hash = "sha256:838943bea48be0e2768b0cf7819544cdedc1bbb2f28427eabb6eb8c9eb2285d3", size = 261504, upload-time = "2026-01-25T12:58:49.904Z" },
-    { url = "https://files.pythonhosted.org/packages/83/5e/1cd72c22ecb30751e43a72f40ba50fcef1b7e93e3ea823bd9feda8e51f9a/coverage-7.13.2-cp313-cp313t-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl", hash = "sha256:93d1d25ec2b27e90bcfef7012992d1f5121b51161b8bffcda756a816cf13c2c3", size = 263582, upload-time = "2026-01-25T12:58:51.582Z" },
-    { url = "https://files.pythonhosted.org/packages/9b/da/8acf356707c7a42df4d0657020308e23e5a07397e81492640c186268497c/coverage-7.13.2-cp313-cp313t-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:93b57142f9621b0d12349c43fc7741fe578e4bc914c1e5a54142856cfc0bf421", size = 266008, upload-time = "2026-01-25T12:58:53.234Z" },
-    { url = "https://files.pythonhosted.org/packages/41/41/ea1730af99960309423c6ea8d6a4f1fa5564b2d97bd1d29dda4b42611f04/coverage-7.13.2-cp313-cp313t-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:f06799ae1bdfff7ccb8665d75f8291c69110ba9585253de254688aa8a1ccc6c5", size = 260762, upload-time = "2026-01-25T12:58:55.372Z" },
-    { url = "https://files.pythonhosted.org/packages/22/fa/02884d2080ba71db64fdc127b311db60e01fe6ba797d9c8363725e39f4d5/coverage-7.13.2-cp313-cp313t-musllinux_1_2_aarch64.whl", hash = "sha256:7f9405ab4f81d490811b1d91c7a20361135a2df4c170e7f0b747a794da5b7f23", size = 263571, upload-time = "2026-01-25T12:58:57.52Z" },
-    { url = "https://files.pythonhosted.org/packages/d2/6b/4083aaaeba9b3112f55ac57c2ce7001dc4d8fa3fcc228a39f09cc84ede27/coverage-7.13.2-cp313-cp313t-musllinux_1_2_i686.whl", hash = "sha256:f9ab1d5b86f8fbc97a5b3cd6280a3fd85fef3b028689d8a2c00918f0d82c728c", size = 261200, upload-time = "2026-01-25T12:58:59.255Z" },
-    { url = "https://files.pythonhosted.org/packages/e9/d2/aea92fa36d61955e8c416ede9cf9bf142aa196f3aea214bb67f85235a050/coverage-7.13.2-cp313-cp313t-musllinux_1_2_riscv64.whl", hash = "sha256:f674f59712d67e841525b99e5e2b595250e39b529c3bda14764e4f625a3fa01f", size = 260095, upload-time = "2026-01-25T12:59:01.066Z" },
-    { url = "https://files.pythonhosted.org/packages/0d/ae/04ffe96a80f107ea21b22b2367175c621da920063260a1c22f9452fd7866/coverage-7.13.2-cp313-cp313t-musllinux_1_2_x86_64.whl", hash = "sha256:c6cadac7b8ace1ba9144feb1ae3cb787a6065ba6d23ffc59a934b16406c26573", size = 262284, upload-time = "2026-01-25T12:59:02.802Z" },
-    { url = "https://files.pythonhosted.org/packages/1c/7a/6f354dcd7dfc41297791d6fb4e0d618acb55810bde2c1fd14b3939e05c2b/coverage-7.13.2-cp313-cp313t-win32.whl", hash = "sha256:14ae4146465f8e6e6253eba0cccd57423e598a4cb925958b240c805300918343", size = 222389, upload-time = "2026-01-25T12:59:04.563Z" },
-    { url = "https://files.pythonhosted.org/packages/8d/d5/080ad292a4a3d3daf411574be0a1f56d6dee2c4fdf6b005342be9fac807f/coverage-7.13.2-cp313-cp313t-win_amd64.whl", hash = "sha256:9074896edd705a05769e3de0eac0a8388484b503b68863dd06d5e473f874fd47", size = 223450, upload-time = "2026-01-25T12:59:06.677Z" },
-    { url = "https://files.pythonhosted.org/packages/88/96/df576fbacc522e9fb8d1c4b7a7fc62eb734be56e2cba1d88d2eabe08ea3f/coverage-7.13.2-cp313-cp313t-win_arm64.whl", hash = "sha256:69e526e14f3f854eda573d3cf40cffd29a1a91c684743d904c33dbdcd0e0f3e7", size = 221707, upload-time = "2026-01-25T12:59:08.363Z" },
-    { url = "https://files.pythonhosted.org/packages/55/53/1da9e51a0775634b04fcc11eb25c002fc58ee4f92ce2e8512f94ac5fc5bf/coverage-7.13.2-cp314-cp314-macosx_10_15_x86_64.whl", hash = "sha256:387a825f43d680e7310e6f325b2167dd093bc8ffd933b83e9aa0983cf6e0a2ef", size = 219213, upload-time = "2026-01-25T12:59:11.909Z" },
-    { url = "https://files.pythonhosted.org/packages/46/35/b3caac3ebbd10230fea5a33012b27d19e999a17c9285c4228b4b2e35b7da/coverage-7.13.2-cp314-cp314-macosx_11_0_arm64.whl", hash = "sha256:f0d7fea9d8e5d778cd5a9e8fc38308ad688f02040e883cdc13311ef2748cb40f", size = 219549, upload-time = "2026-01-25T12:59:13.638Z" },
-    { url = "https://files.pythonhosted.org/packages/76/9c/e1cf7def1bdc72c1907e60703983a588f9558434a2ff94615747bd73c192/coverage-7.13.2-cp314-cp314-manylinux1_i686.manylinux_2_28_i686.manylinux_2_5_i686.whl", hash = "sha256:e080afb413be106c95c4ee96b4fffdc9e2fa56a8bbf90b5c0918e5c4449412f5", size = 250586, upload-time = "2026-01-25T12:59:15.808Z" },
-    { url = "https://files.pythonhosted.org/packages/ba/49/f54ec02ed12be66c8d8897270505759e057b0c68564a65c429ccdd1f139e/coverage-7.13.2-cp314-cp314-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl", hash = "sha256:a7fc042ba3c7ce25b8a9f097eb0f32a5ce1ccdb639d9eec114e26def98e1f8a4", size = 253093, upload-time = "2026-01-25T12:59:17.491Z" },
-    { url = "https://files.pythonhosted.org/packages/fb/5e/aaf86be3e181d907e23c0f61fccaeb38de8e6f6b47aed92bf57d8fc9c034/coverage-7.13.2-cp314-cp314-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:d0ba505e021557f7f8173ee8cd6b926373d8653e5ff7581ae2efce1b11ef4c27", size = 254446, upload-time = "2026-01-25T12:59:19.752Z" },
-    { url = "https://files.pythonhosted.org/packages/28/c8/a5fa01460e2d75b0c853b392080d6829d3ca8b5ab31e158fa0501bc7c708/coverage-7.13.2-cp314-cp314-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:7de326f80e3451bd5cc7239ab46c73ddb658fe0b7649476bc7413572d36cd548", size = 250615, upload-time = "2026-01-25T12:59:21.928Z" },
-    { url = "https://files.pythonhosted.org/packages/86/0b/6d56315a55f7062bb66410732c24879ccb2ec527ab6630246de5fe45a1df/coverage-7.13.2-cp314-cp314-musllinux_1_2_aarch64.whl", hash = "sha256:abaea04f1e7e34841d4a7b343904a3f59481f62f9df39e2cd399d69a187a9660", size = 252452, upload-time = "2026-01-25T12:59:23.592Z" },
-    { url = "https://files.pythonhosted.org/packages/30/19/9bc550363ebc6b0ea121977ee44d05ecd1e8bf79018b8444f1028701c563/coverage-7.13.2-cp314-cp314-musllinux_1_2_i686.whl", hash = "sha256:9f93959ee0c604bccd8e0697be21de0887b1f73efcc3aa73a3ec0fd13feace92", size = 250418, upload-time = "2026-01-25T12:59:25.392Z" },
-    { url = "https://files.pythonhosted.org/packages/1f/53/580530a31ca2f0cc6f07a8f2ab5460785b02bb11bdf815d4c4d37a4c5169/coverage-7.13.2-cp314-cp314-musllinux_1_2_riscv64.whl", hash = "sha256:13fe81ead04e34e105bf1b3c9f9cdf32ce31736ee5d90a8d2de02b9d3e1bcb82", size = 250231, upload-time = "2026-01-25T12:59:27.888Z" },
-    { url = "https://files.pythonhosted.org/packages/e2/42/dd9093f919dc3088cb472893651884bd675e3df3d38a43f9053656dca9a2/coverage-7.13.2-cp314-cp314-musllinux_1_2_x86_64.whl", hash = "sha256:d6d16b0f71120e365741bca2cb473ca6fe38930bc5431c5e850ba949f708f892", size = 251888, upload-time = "2026-01-25T12:59:29.636Z" },
-    { url = "https://files.pythonhosted.org/packages/fa/a6/0af4053e6e819774626e133c3d6f70fae4d44884bfc4b126cb647baee8d3/coverage-7.13.2-cp314-cp314-win32.whl", hash = "sha256:9b2f4714bb7d99ba3790ee095b3b4ac94767e1347fe424278a0b10acb3ff04fe", size = 221968, upload-time = "2026-01-25T12:59:31.424Z" },
-    { url = "https://files.pythonhosted.org/packages/c4/cc/5aff1e1f80d55862442855517bb8ad8ad3a68639441ff6287dde6a58558b/coverage-7.13.2-cp314-cp314-win_amd64.whl", hash = "sha256:e4121a90823a063d717a96e0a0529c727fb31ea889369a0ee3ec00ed99bf6859", size = 222783, upload-time = "2026-01-25T12:59:33.118Z" },
-    { url = "https://files.pythonhosted.org/packages/de/20/09abafb24f84b3292cc658728803416c15b79f9ee5e68d25238a895b07d9/coverage-7.13.2-cp314-cp314-win_arm64.whl", hash = "sha256:6873f0271b4a15a33e7590f338d823f6f66f91ed147a03938d7ce26efd04eee6", size = 221348, upload-time = "2026-01-25T12:59:34.939Z" },
-    { url = "https://files.pythonhosted.org/packages/b6/60/a3820c7232db63be060e4019017cd3426751c2699dab3c62819cdbcea387/coverage-7.13.2-cp314-cp314t-macosx_10_15_x86_64.whl", hash = "sha256:f61d349f5b7cd95c34017f1927ee379bfbe9884300d74e07cf630ccf7a610c1b", size = 219950, upload-time = "2026-01-25T12:59:36.624Z" },
-    { url = "https://files.pythonhosted.org/packages/fd/37/e4ef5975fdeb86b1e56db9a82f41b032e3d93a840ebaf4064f39e770d5c5/coverage-7.13.2-cp314-cp314t-macosx_11_0_arm64.whl", hash = "sha256:a43d34ce714f4ca674c0d90beb760eb05aad906f2c47580ccee9da8fe8bfb417", size = 220209, upload-time = "2026-01-25T12:59:38.339Z" },
-    { url = "https://files.pythonhosted.org/packages/54/df/d40e091d00c51adca1e251d3b60a8b464112efa3004949e96a74d7c19a64/coverage-7.13.2-cp314-cp314t-manylinux1_i686.manylinux_2_28_i686.manylinux_2_5_i686.whl", hash = "sha256:bff1b04cb9d4900ce5c56c4942f047dc7efe57e2608cb7c3c8936e9970ccdbee", size = 261576, upload-time = "2026-01-25T12:59:40.446Z" },
-    { url = "https://files.pythonhosted.org/packages/c5/44/5259c4bed54e3392e5c176121af9f71919d96dde853386e7730e705f3520/coverage-7.13.2-cp314-cp314t-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl", hash = "sha256:6ae99e4560963ad8e163e819e5d77d413d331fd00566c1e0856aa252303552c1", size = 263704, upload-time = "2026-01-25T12:59:42.346Z" },
-    { url = "https://files.pythonhosted.org/packages/16/bd/ae9f005827abcbe2c70157459ae86053971c9fa14617b63903abbdce26d9/coverage-7.13.2-cp314-cp314t-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:e79a8c7d461820257d9aa43716c4efc55366d7b292e46b5b37165be1d377405d", size = 266109, upload-time = "2026-01-25T12:59:44.073Z" },
-    { url = "https://files.pythonhosted.org/packages/a2/c0/8e279c1c0f5b1eaa3ad9b0fb7a5637fc0379ea7d85a781c0fe0bb3cfc2ab/coverage-7.13.2-cp314-cp314t-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:060ee84f6a769d40c492711911a76811b4befb6fba50abb450371abb720f5bd6", size = 260686, upload-time = "2026-01-25T12:59:45.804Z" },
-    { url = "https://files.pythonhosted.org/packages/b2/47/3a8112627e9d863e7cddd72894171c929e94491a597811725befdcd76bce/coverage-7.13.2-cp314-cp314t-musllinux_1_2_aarch64.whl", hash = "sha256:3bca209d001fd03ea2d978f8a4985093240a355c93078aee3f799852c23f561a", size = 263568, upload-time = "2026-01-25T12:59:47.929Z" },
-    { url = "https://files.pythonhosted.org/packages/92/bc/7ea367d84afa3120afc3ce6de294fd2dcd33b51e2e7fbe4bbfd200f2cb8c/coverage-7.13.2-cp314-cp314t-musllinux_1_2_i686.whl", hash = "sha256:6b8092aa38d72f091db61ef83cb66076f18f02da3e1a75039a4f218629600e04", size = 261174, upload-time = "2026-01-25T12:59:49.717Z" },
-    { url = "https://files.pythonhosted.org/packages/33/b7/f1092dcecb6637e31cc2db099581ee5c61a17647849bae6b8261a2b78430/coverage-7.13.2-cp314-cp314t-musllinux_1_2_riscv64.whl", hash = "sha256:4a3158dc2dcce5200d91ec28cd315c999eebff355437d2765840555d765a6e5f", size = 260017, upload-time = "2026-01-25T12:59:51.463Z" },
-    { url = "https://files.pythonhosted.org/packages/2b/cd/f3d07d4b95fbe1a2ef0958c15da614f7e4f557720132de34d2dc3aa7e911/coverage-7.13.2-cp314-cp314t-musllinux_1_2_x86_64.whl", hash = "sha256:3973f353b2d70bd9796cc12f532a05945232ccae966456c8ed7034cb96bbfd6f", size = 262337, upload-time = "2026-01-25T12:59:53.407Z" },
-    { url = "https://files.pythonhosted.org/packages/e0/db/b0d5b2873a07cb1e06a55d998697c0a5a540dcefbf353774c99eb3874513/coverage-7.13.2-cp314-cp314t-win32.whl", hash = "sha256:79f6506a678a59d4ded048dc72f1859ebede8ec2b9a2d509ebe161f01c2879d3", size = 222749, upload-time = "2026-01-25T12:59:56.316Z" },
-    { url = "https://files.pythonhosted.org/packages/e5/2f/838a5394c082ac57d85f57f6aba53093b30d9089781df72412126505716f/coverage-7.13.2-cp314-cp314t-win_amd64.whl", hash = "sha256:196bfeabdccc5a020a57d5a368c681e3a6ceb0447d153aeccc1ab4d70a5032ba", size = 223857, upload-time = "2026-01-25T12:59:58.201Z" },
-    { url = "https://files.pythonhosted.org/packages/44/d4/b608243e76ead3a4298824b50922b89ef793e50069ce30316a65c1b4d7ef/coverage-7.13.2-cp314-cp314t-win_arm64.whl", hash = "sha256:69269ab58783e090bfbf5b916ab3d188126e22d6070bbfc93098fdd474ef937c", size = 221881, upload-time = "2026-01-25T13:00:00.449Z" },
-    { url = "https://files.pythonhosted.org/packages/d2/db/d291e30fdf7ea617a335531e72294e0c723356d7fdde8fba00610a76bda9/coverage-7.13.2-py3-none-any.whl", hash = "sha256:40ce1ea1e25125556d8e76bd0b61500839a07944cc287ac21d5626f3e620cad5", size = 210943, upload-time = "2026-01-25T13:00:02.388Z" },
+    { url = "https://files.pythonhosted.org/packages/44/d4/7827d9ffa34d5d4d752eec907022aa417120936282fc488306f5da08c292/coverage-7.13.4-cp310-cp310-macosx_10_9_x86_64.whl", hash = "sha256:0fc31c787a84f8cd6027eba44010517020e0d18487064cd3d8968941856d1415", size = 219152, upload-time = "2026-02-09T12:56:11.974Z" },
+    { url = "https://files.pythonhosted.org/packages/35/b0/d69df26607c64043292644dbb9dc54b0856fabaa2cbb1eeee3331cc9e280/coverage-7.13.4-cp310-cp310-macosx_11_0_arm64.whl", hash = "sha256:a32ebc02a1805adf637fc8dec324b5cdacd2e493515424f70ee33799573d661b", size = 219667, upload-time = "2026-02-09T12:56:13.33Z" },
+    { url = "https://files.pythonhosted.org/packages/82/a4/c1523f7c9e47b2271dbf8c2a097e7a1f89ef0d66f5840bb59b7e8814157b/coverage-7.13.4-cp310-cp310-manylinux1_i686.manylinux_2_28_i686.manylinux_2_5_i686.whl", hash = "sha256:e24f9156097ff9dc286f2f913df3a7f63c0e333dcafa3c196f2c18b4175ca09a", size = 246425, upload-time = "2026-02-09T12:56:14.552Z" },
+    { url = "https://files.pythonhosted.org/packages/f8/02/aa7ec01d1a5023c4b680ab7257f9bfde9defe8fdddfe40be096ac19e8177/coverage-7.13.4-cp310-cp310-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl", hash = "sha256:8041b6c5bfdc03257666e9881d33b1abc88daccaf73f7b6340fb7946655cd10f", size = 248229, upload-time = "2026-02-09T12:56:16.31Z" },
+    { url = "https://files.pythonhosted.org/packages/35/98/85aba0aed5126d896162087ef3f0e789a225697245256fc6181b95f47207/coverage-7.13.4-cp310-cp310-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:2a09cfa6a5862bc2fc6ca7c3def5b2926194a56b8ab78ffcf617d28911123012", size = 250106, upload-time = "2026-02-09T12:56:18.024Z" },
+    { url = "https://files.pythonhosted.org/packages/96/72/1db59bd67494bc162e3e4cd5fbc7edba2c7026b22f7c8ef1496d58c2b94c/coverage-7.13.4-cp310-cp310-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:296f8b0af861d3970c2a4d8c91d48eb4dd4771bcef9baedec6a9b515d7de3def", size = 252021, upload-time = "2026-02-09T12:56:19.272Z" },
+    { url = "https://files.pythonhosted.org/packages/9d/97/72899c59c7066961de6e3daa142d459d47d104956db43e057e034f015c8a/coverage-7.13.4-cp310-cp310-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:e101609bcbbfb04605ea1027b10dc3735c094d12d40826a60f897b98b1c30256", size = 247114, upload-time = "2026-02-09T12:56:21.051Z" },
+    { url = "https://files.pythonhosted.org/packages/39/1f/f1885573b5970235e908da4389176936c8933e86cb316b9620aab1585fa2/coverage-7.13.4-cp310-cp310-musllinux_1_2_aarch64.whl", hash = "sha256:aa3feb8db2e87ff5e6d00d7e1480ae241876286691265657b500886c98f38bda", size = 248143, upload-time = "2026-02-09T12:56:22.585Z" },
+    { url = "https://files.pythonhosted.org/packages/a8/cf/e80390c5b7480b722fa3e994f8202807799b85bc562aa4f1dde209fbb7be/coverage-7.13.4-cp310-cp310-musllinux_1_2_i686.whl", hash = "sha256:4fc7fa81bbaf5a02801b65346c8b3e657f1d93763e58c0abdf7c992addd81a92", size = 246152, upload-time = "2026-02-09T12:56:23.748Z" },
+    { url = "https://files.pythonhosted.org/packages/44/bf/f89a8350d85572f95412debb0fb9bb4795b1d5b5232bd652923c759e787b/coverage-7.13.4-cp310-cp310-musllinux_1_2_ppc64le.whl", hash = "sha256:33901f604424145c6e9c2398684b92e176c0b12df77d52db81c20abd48c3794c", size = 249959, upload-time = "2026-02-09T12:56:25.209Z" },
+    { url = "https://files.pythonhosted.org/packages/f7/6e/612a02aece8178c818df273e8d1642190c4875402ca2ba74514394b27aba/coverage-7.13.4-cp310-cp310-musllinux_1_2_riscv64.whl", hash = "sha256:bb28c0f2cf2782508a40cec377935829d5fcc3ad9a3681375af4e84eb34b6b58", size = 246416, upload-time = "2026-02-09T12:56:26.475Z" },
+    { url = "https://files.pythonhosted.org/packages/cb/98/b5afc39af67c2fa6786b03c3a7091fc300947387ce8914b096db8a73d67a/coverage-7.13.4-cp310-cp310-musllinux_1_2_x86_64.whl", hash = "sha256:9d107aff57a83222ddbd8d9ee705ede2af2cc926608b57abed8ef96b50b7e8f9", size = 247025, upload-time = "2026-02-09T12:56:27.727Z" },
+    { url = "https://files.pythonhosted.org/packages/51/30/2bba8ef0682d5bd210c38fe497e12a06c9f8d663f7025e9f5c2c31ce847d/coverage-7.13.4-cp310-cp310-win32.whl", hash = "sha256:a6f94a7d00eb18f1b6d403c91a88fd58cfc92d4b16080dfdb774afc8294469bf", size = 221758, upload-time = "2026-02-09T12:56:29.051Z" },
+    { url = "https://files.pythonhosted.org/packages/78/13/331f94934cf6c092b8ea59ff868eb587bc8fe0893f02c55bc6c0183a192e/coverage-7.13.4-cp310-cp310-win_amd64.whl", hash = "sha256:2cb0f1e000ebc419632bbe04366a8990b6e32c4e0b51543a6484ffe15eaeda95", size = 222693, upload-time = "2026-02-09T12:56:30.366Z" },
+    { url = "https://files.pythonhosted.org/packages/b4/ad/b59e5b451cf7172b8d1043dc0fa718f23aab379bc1521ee13d4bd9bfa960/coverage-7.13.4-cp311-cp311-macosx_10_9_x86_64.whl", hash = "sha256:d490ba50c3f35dd7c17953c68f3270e7ccd1c6642e2d2afe2d8e720b98f5a053", size = 219278, upload-time = "2026-02-09T12:56:31.673Z" },
+    { url = "https://files.pythonhosted.org/packages/f1/17/0cb7ca3de72e5f4ef2ec2fa0089beafbcaaaead1844e8b8a63d35173d77d/coverage-7.13.4-cp311-cp311-macosx_11_0_arm64.whl", hash = "sha256:19bc3c88078789f8ef36acb014d7241961dbf883fd2533d18cb1e7a5b4e28b11", size = 219783, upload-time = "2026-02-09T12:56:33.104Z" },
+    { url = "https://files.pythonhosted.org/packages/ab/63/325d8e5b11e0eaf6d0f6a44fad444ae58820929a9b0de943fa377fe73e85/coverage-7.13.4-cp311-cp311-manylinux1_i686.manylinux_2_28_i686.manylinux_2_5_i686.whl", hash = "sha256:3998e5a32e62fdf410c0dbd3115df86297995d6e3429af80b8798aad894ca7aa", size = 250200, upload-time = "2026-02-09T12:56:34.474Z" },
+    { url = "https://files.pythonhosted.org/packages/76/53/c16972708cbb79f2942922571a687c52bd109a7bd51175aeb7558dff2236/coverage-7.13.4-cp311-cp311-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl", hash = "sha256:8e264226ec98e01a8e1054314af91ee6cde0eacac4f465cc93b03dbe0bce2fd7", size = 252114, upload-time = "2026-02-09T12:56:35.749Z" },
+    { url = "https://files.pythonhosted.org/packages/eb/c2/7ab36d8b8cc412bec9ea2d07c83c48930eb4ba649634ba00cb7e4e0f9017/coverage-7.13.4-cp311-cp311-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:a3aa4e7b9e416774b21797365b358a6e827ffadaaca81b69ee02946852449f00", size = 254220, upload-time = "2026-02-09T12:56:37.796Z" },
+    { url = "https://files.pythonhosted.org/packages/d6/4d/cf52c9a3322c89a0e6febdfbc83bb45c0ed3c64ad14081b9503adee702e7/coverage-7.13.4-cp311-cp311-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:71ca20079dd8f27fcf808817e281e90220475cd75115162218d0e27549f95fef", size = 256164, upload-time = "2026-02-09T12:56:39.016Z" },
+    { url = "https://files.pythonhosted.org/packages/78/e9/eb1dd17bd6de8289df3580e967e78294f352a5df8a57ff4671ee5fc3dcd0/coverage-7.13.4-cp311-cp311-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:e2f25215f1a359ab17320b47bcdaca3e6e6356652e8256f2441e4ef972052903", size = 250325, upload-time = "2026-02-09T12:56:40.668Z" },
+    { url = "https://files.pythonhosted.org/packages/71/07/8c1542aa873728f72267c07278c5cc0ec91356daf974df21335ccdb46368/coverage-7.13.4-cp311-cp311-musllinux_1_2_aarch64.whl", hash = "sha256:d65b2d373032411e86960604dc4edac91fdfb5dca539461cf2cbe78327d1e64f", size = 251913, upload-time = "2026-02-09T12:56:41.97Z" },
+    { url = "https://files.pythonhosted.org/packages/74/d7/c62e2c5e4483a748e27868e4c32ad3daa9bdddbba58e1bc7a15e252baa74/coverage-7.13.4-cp311-cp311-musllinux_1_2_i686.whl", hash = "sha256:94eb63f9b363180aff17de3e7c8760c3ba94664ea2695c52f10111244d16a299", size = 249974, upload-time = "2026-02-09T12:56:43.323Z" },
+    { url = "https://files.pythonhosted.org/packages/98/9f/4c5c015a6e98ced54efd0f5cf8d31b88e5504ecb6857585fc0161bb1e600/coverage-7.13.4-cp311-cp311-musllinux_1_2_ppc64le.whl", hash = "sha256:e856bf6616714c3a9fbc270ab54103f4e685ba236fa98c054e8f87f266c93505", size = 253741, upload-time = "2026-02-09T12:56:45.155Z" },
+    { url = "https://files.pythonhosted.org/packages/bd/59/0f4eef89b9f0fcd9633b5d350016f54126ab49426a70ff4c4e87446cabdc/coverage-7.13.4-cp311-cp311-musllinux_1_2_riscv64.whl", hash = "sha256:65dfcbe305c3dfe658492df2d85259e0d79ead4177f9ae724b6fb245198f55d6", size = 249695, upload-time = "2026-02-09T12:56:46.636Z" },
+    { url = "https://files.pythonhosted.org/packages/b5/2c/b7476f938deb07166f3eb281a385c262675d688ff4659ad56c6c6b8e2e70/coverage-7.13.4-cp311-cp311-musllinux_1_2_x86_64.whl", hash = "sha256:b507778ae8a4c915436ed5c2e05b4a6cecfa70f734e19c22a005152a11c7b6a9", size = 250599, upload-time = "2026-02-09T12:56:48.13Z" },
+    { url = "https://files.pythonhosted.org/packages/b8/34/c3420709d9846ee3785b9f2831b4d94f276f38884032dca1457fa83f7476/coverage-7.13.4-cp311-cp311-win32.whl", hash = "sha256:784fc3cf8be001197b652d51d3fd259b1e2262888693a4636e18879f613a62a9", size = 221780, upload-time = "2026-02-09T12:56:50.479Z" },
+    { url = "https://files.pythonhosted.org/packages/61/08/3d9c8613079d2b11c185b865de9a4c1a68850cfda2b357fae365cf609f29/coverage-7.13.4-cp311-cp311-win_amd64.whl", hash = "sha256:2421d591f8ca05b308cf0092807308b2facbefe54af7c02ac22548b88b95c98f", size = 222715, upload-time = "2026-02-09T12:56:51.815Z" },
+    { url = "https://files.pythonhosted.org/packages/18/1a/54c3c80b2f056164cc0a6cdcb040733760c7c4be9d780fe655f356f433e4/coverage-7.13.4-cp311-cp311-win_arm64.whl", hash = "sha256:79e73a76b854d9c6088fe5d8b2ebe745f8681c55f7397c3c0a016192d681045f", size = 221385, upload-time = "2026-02-09T12:56:53.194Z" },
+    { url = "https://files.pythonhosted.org/packages/d1/81/4ce2fdd909c5a0ed1f6dedb88aa57ab79b6d1fbd9b588c1ac7ef45659566/coverage-7.13.4-cp312-cp312-macosx_10_13_x86_64.whl", hash = "sha256:02231499b08dabbe2b96612993e5fc34217cdae907a51b906ac7fca8027a4459", size = 219449, upload-time = "2026-02-09T12:56:54.889Z" },
+    { url = "https://files.pythonhosted.org/packages/5d/96/5238b1efc5922ddbdc9b0db9243152c09777804fb7c02ad1741eb18a11c0/coverage-7.13.4-cp312-cp312-macosx_11_0_arm64.whl", hash = "sha256:40aa8808140e55dc022b15d8aa7f651b6b3d68b365ea0398f1441e0b04d859c3", size = 219810, upload-time = "2026-02-09T12:56:56.33Z" },
+    { url = "https://files.pythonhosted.org/packages/78/72/2f372b726d433c9c35e56377cf1d513b4c16fe51841060d826b95caacec1/coverage-7.13.4-cp312-cp312-manylinux1_i686.manylinux_2_28_i686.manylinux_2_5_i686.whl", hash = "sha256:5b856a8ccf749480024ff3bd7310adaef57bf31fd17e1bfc404b7940b6986634", size = 251308, upload-time = "2026-02-09T12:56:57.858Z" },
+    { url = "https://files.pythonhosted.org/packages/5d/a0/2ea570925524ef4e00bb6c82649f5682a77fac5ab910a65c9284de422600/coverage-7.13.4-cp312-cp312-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl", hash = "sha256:2c048ea43875fbf8b45d476ad79f179809c590ec7b79e2035c662e7afa3192e3", size = 254052, upload-time = "2026-02-09T12:56:59.754Z" },
+    { url = "https://files.pythonhosted.org/packages/e8/ac/45dc2e19a1939098d783c846e130b8f862fbb50d09e0af663988f2f21973/coverage-7.13.4-cp312-cp312-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:b7b38448866e83176e28086674fe7368ab8590e4610fb662b44e345b86d63ffa", size = 255165, upload-time = "2026-02-09T12:57:01.287Z" },
+    { url = "https://files.pythonhosted.org/packages/2d/4d/26d236ff35abc3b5e63540d3386e4c3b192168c1d96da5cb2f43c640970f/coverage-7.13.4-cp312-cp312-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:de6defc1c9badbf8b9e67ae90fd00519186d6ab64e5cc5f3d21359c2a9b2c1d3", size = 257432, upload-time = "2026-02-09T12:57:02.637Z" },
+    { url = "https://files.pythonhosted.org/packages/ec/55/14a966c757d1348b2e19caf699415a2a4c4f7feaa4bbc6326a51f5c7dd1b/coverage-7.13.4-cp312-cp312-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:7eda778067ad7ffccd23ecffce537dface96212576a07924cbf0d8799d2ded5a", size = 251716, upload-time = "2026-02-09T12:57:04.056Z" },
+    { url = "https://files.pythonhosted.org/packages/77/33/50116647905837c66d28b2af1321b845d5f5d19be9655cb84d4a0ea806b4/coverage-7.13.4-cp312-cp312-musllinux_1_2_aarch64.whl", hash = "sha256:e87f6c587c3f34356c3759f0420693e35e7eb0e2e41e4c011cb6ec6ecbbf1db7", size = 253089, upload-time = "2026-02-09T12:57:05.503Z" },
+    { url = "https://files.pythonhosted.org/packages/c2/b4/8efb11a46e3665d92635a56e4f2d4529de6d33f2cb38afd47d779d15fc99/coverage-7.13.4-cp312-cp312-musllinux_1_2_i686.whl", hash = "sha256:8248977c2e33aecb2ced42fef99f2d319e9904a36e55a8a68b69207fb7e43edc", size = 251232, upload-time = "2026-02-09T12:57:06.879Z" },
+    { url = "https://files.pythonhosted.org/packages/51/24/8cd73dd399b812cc76bb0ac260e671c4163093441847ffe058ac9fda1e32/coverage-7.13.4-cp312-cp312-musllinux_1_2_ppc64le.whl", hash = "sha256:25381386e80ae727608e662474db537d4df1ecd42379b5ba33c84633a2b36d47", size = 255299, upload-time = "2026-02-09T12:57:08.245Z" },
+    { url = "https://files.pythonhosted.org/packages/03/94/0a4b12f1d0e029ce1ccc1c800944a9984cbe7d678e470bb6d3c6bc38a0da/coverage-7.13.4-cp312-cp312-musllinux_1_2_riscv64.whl", hash = "sha256:ee756f00726693e5ba94d6df2bdfd64d4852d23b09bb0bc700e3b30e6f333985", size = 250796, upload-time = "2026-02-09T12:57:10.142Z" },
+    { url = "https://files.pythonhosted.org/packages/73/44/6002fbf88f6698ca034360ce474c406be6d5a985b3fdb3401128031eef6b/coverage-7.13.4-cp312-cp312-musllinux_1_2_x86_64.whl", hash = "sha256:fdfc1e28e7c7cdce44985b3043bc13bbd9c747520f94a4d7164af8260b3d91f0", size = 252673, upload-time = "2026-02-09T12:57:12.197Z" },
+    { url = "https://files.pythonhosted.org/packages/de/c6/a0279f7c00e786be75a749a5674e6fa267bcbd8209cd10c9a450c655dfa7/coverage-7.13.4-cp312-cp312-win32.whl", hash = "sha256:01d4cbc3c283a17fc1e42d614a119f7f438eabb593391283adca8dc86eff1246", size = 221990, upload-time = "2026-02-09T12:57:14.085Z" },
+    { url = "https://files.pythonhosted.org/packages/77/4e/c0a25a425fcf5557d9abd18419c95b63922e897bc86c1f327f155ef234a9/coverage-7.13.4-cp312-cp312-win_amd64.whl", hash = "sha256:9401ebc7ef522f01d01d45532c68c5ac40fb27113019b6b7d8b208f6e9baa126", size = 222800, upload-time = "2026-02-09T12:57:15.944Z" },
+    { url = "https://files.pythonhosted.org/packages/47/ac/92da44ad9a6f4e3a7debd178949d6f3769bedca33830ce9b1dcdab589a37/coverage-7.13.4-cp312-cp312-win_arm64.whl", hash = "sha256:b1ec7b6b6e93255f952e27ab58fbc68dcc468844b16ecbee881aeb29b6ab4d8d", size = 221415, upload-time = "2026-02-09T12:57:17.497Z" },
+    { url = "https://files.pythonhosted.org/packages/db/23/aad45061a31677d68e47499197a131eea55da4875d16c1f42021ab963503/coverage-7.13.4-cp313-cp313-macosx_10_13_x86_64.whl", hash = "sha256:b66a2da594b6068b48b2692f043f35d4d3693fb639d5ea8b39533c2ad9ac3ab9", size = 219474, upload-time = "2026-02-09T12:57:19.332Z" },
+    { url = "https://files.pythonhosted.org/packages/a5/70/9b8b67a0945f3dfec1fd896c5cefb7c19d5a3a6d74630b99a895170999ae/coverage-7.13.4-cp313-cp313-macosx_11_0_arm64.whl", hash = "sha256:3599eb3992d814d23b35c536c28df1a882caa950f8f507cef23d1cbf334995ac", size = 219844, upload-time = "2026-02-09T12:57:20.66Z" },
+    { url = "https://files.pythonhosted.org/packages/97/fd/7e859f8fab324cef6c4ad7cff156ca7c489fef9179d5749b0c8d321281c2/coverage-7.13.4-cp313-cp313-manylinux1_i686.manylinux_2_28_i686.manylinux_2_5_i686.whl", hash = "sha256:93550784d9281e374fb5a12bf1324cc8a963fd63b2d2f223503ef0fd4aa339ea", size = 250832, upload-time = "2026-02-09T12:57:22.007Z" },
+    { url = "https://files.pythonhosted.org/packages/e4/dc/b2442d10020c2f52617828862d8b6ee337859cd8f3a1f13d607dddda9cf7/coverage-7.13.4-cp313-cp313-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl", hash = "sha256:b720ce6a88a2755f7c697c23268ddc47a571b88052e6b155224347389fdf6a3b", size = 253434, upload-time = "2026-02-09T12:57:23.339Z" },
+    { url = "https://files.pythonhosted.org/packages/5a/88/6728a7ad17428b18d836540630487231f5470fb82454871149502f5e5aa2/coverage-7.13.4-cp313-cp313-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:7b322db1284a2ed3aa28ffd8ebe3db91c929b7a333c0820abec3d838ef5b3525", size = 254676, upload-time = "2026-02-09T12:57:24.774Z" },
+    { url = "https://files.pythonhosted.org/packages/7c/bc/21244b1b8cedf0dff0a2b53b208015fe798d5f2a8d5348dbfece04224fff/coverage-7.13.4-cp313-cp313-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:f4594c67d8a7c89cf922d9df0438c7c7bb022ad506eddb0fdb2863359ff78242", size = 256807, upload-time = "2026-02-09T12:57:26.125Z" },
+    { url = "https://files.pythonhosted.org/packages/97/a0/ddba7ed3251cff51006737a727d84e05b61517d1784a9988a846ba508877/coverage-7.13.4-cp313-cp313-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:53d133df809c743eb8bce33b24bcababb371f4441340578cd406e084d94a6148", size = 251058, upload-time = "2026-02-09T12:57:27.614Z" },
+    { url = "https://files.pythonhosted.org/packages/9b/55/e289addf7ff54d3a540526f33751951bf0878f3809b47f6dfb3def69c6f7/coverage-7.13.4-cp313-cp313-musllinux_1_2_aarch64.whl", hash = "sha256:76451d1978b95ba6507a039090ba076105c87cc76fc3efd5d35d72093964d49a", size = 252805, upload-time = "2026-02-09T12:57:29.066Z" },
+    { url = "https://files.pythonhosted.org/packages/13/4e/cc276b1fa4a59be56d96f1dabddbdc30f4ba22e3b1cd42504c37b3313255/coverage-7.13.4-cp313-cp313-musllinux_1_2_i686.whl", hash = "sha256:7f57b33491e281e962021de110b451ab8a24182589be17e12a22c79047935e23", size = 250766, upload-time = "2026-02-09T12:57:30.522Z" },
+    { url = "https://files.pythonhosted.org/packages/94/44/1093b8f93018f8b41a8cf29636c9292502f05e4a113d4d107d14a3acd044/coverage-7.13.4-cp313-cp313-musllinux_1_2_ppc64le.whl", hash = "sha256:1731dc33dc276dafc410a885cbf5992f1ff171393e48a21453b78727d090de80", size = 254923, upload-time = "2026-02-09T12:57:31.946Z" },
+    { url = "https://files.pythonhosted.org/packages/8b/55/ea2796da2d42257f37dbea1aab239ba9263b31bd91d5527cdd6db5efe174/coverage-7.13.4-cp313-cp313-musllinux_1_2_riscv64.whl", hash = "sha256:bd60d4fe2f6fa7dff9223ca1bbc9f05d2b6697bc5961072e5d3b952d46e1b1ea", size = 250591, upload-time = "2026-02-09T12:57:33.842Z" },
+    { url = "https://files.pythonhosted.org/packages/d4/fa/7c4bb72aacf8af5020675aa633e59c1fbe296d22aed191b6a5b711eb2bc7/coverage-7.13.4-cp313-cp313-musllinux_1_2_x86_64.whl", hash = "sha256:9181a3ccead280b828fae232df12b16652702b49d41e99d657f46cc7b1f6ec7a", size = 252364, upload-time = "2026-02-09T12:57:35.743Z" },
+    { url = "https://files.pythonhosted.org/packages/5c/38/a8d2ec0146479c20bbaa7181b5b455a0c41101eed57f10dd19a78ab44c80/coverage-7.13.4-cp313-cp313-win32.whl", hash = "sha256:f53d492307962561ac7de4cd1de3e363589b000ab69617c6156a16ba7237998d", size = 222010, upload-time = "2026-02-09T12:57:37.25Z" },
+    { url = "https://files.pythonhosted.org/packages/e2/0c/dbfafbe90a185943dcfbc766fe0e1909f658811492d79b741523a414a6cc/coverage-7.13.4-cp313-cp313-win_amd64.whl", hash = "sha256:e6f70dec1cc557e52df5306d051ef56003f74d56e9c4dd7ddb07e07ef32a84dd", size = 222818, upload-time = "2026-02-09T12:57:38.734Z" },
+    { url = "https://files.pythonhosted.org/packages/04/d1/934918a138c932c90d78301f45f677fb05c39a3112b96fd2c8e60503cdc7/coverage-7.13.4-cp313-cp313-win_arm64.whl", hash = "sha256:fb07dc5da7e849e2ad31a5d74e9bece81f30ecf5a42909d0a695f8bd1874d6af", size = 221438, upload-time = "2026-02-09T12:57:40.223Z" },
+    { url = "https://files.pythonhosted.org/packages/52/57/ee93ced533bcb3e6df961c0c6e42da2fc6addae53fb95b94a89b1e33ebd7/coverage-7.13.4-cp313-cp313t-macosx_10_13_x86_64.whl", hash = "sha256:40d74da8e6c4b9ac18b15331c4b5ebc35a17069410cad462ad4f40dcd2d50c0d", size = 220165, upload-time = "2026-02-09T12:57:41.639Z" },
+    { url = "https://files.pythonhosted.org/packages/c5/e0/969fc285a6fbdda49d91af278488d904dcd7651b2693872f0ff94e40e84a/coverage-7.13.4-cp313-cp313t-macosx_11_0_arm64.whl", hash = "sha256:4223b4230a376138939a9173f1bdd6521994f2aff8047fae100d6d94d50c5a12", size = 220516, upload-time = "2026-02-09T12:57:44.215Z" },
+    { url = "https://files.pythonhosted.org/packages/b1/b8/9531944e16267e2735a30a9641ff49671f07e8138ecf1ca13db9fd2560c7/coverage-7.13.4-cp313-cp313t-manylinux1_i686.manylinux_2_28_i686.manylinux_2_5_i686.whl", hash = "sha256:1d4be36a5114c499f9f1f9195e95ebf979460dbe2d88e6816ea202010ba1c34b", size = 261804, upload-time = "2026-02-09T12:57:45.989Z" },
+    { url = "https://files.pythonhosted.org/packages/8a/f3/e63df6d500314a2a60390d1989240d5f27318a7a68fa30ad3806e2a9323e/coverage-7.13.4-cp313-cp313t-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl", hash = "sha256:200dea7d1e8095cc6e98cdabe3fd1d21ab17d3cee6dab00cadbb2fe35d9c15b9", size = 263885, upload-time = "2026-02-09T12:57:47.42Z" },
+    { url = "https://files.pythonhosted.org/packages/f3/67/7654810de580e14b37670b60a09c599fa348e48312db5b216d730857ffe6/coverage-7.13.4-cp313-cp313t-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:b8eb931ee8e6d8243e253e5ed7336deea6904369d2fd8ae6e43f68abbf167092", size = 266308, upload-time = "2026-02-09T12:57:49.345Z" },
+    { url = "https://files.pythonhosted.org/packages/37/6f/39d41eca0eab3cc82115953ad41c4e77935286c930e8fad15eaed1389d83/coverage-7.13.4-cp313-cp313t-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:75eab1ebe4f2f64d9509b984f9314d4aa788540368218b858dad56dc8f3e5eb9", size = 267452, upload-time = "2026-02-09T12:57:50.811Z" },
+    { url = "https://files.pythonhosted.org/packages/50/6d/39c0fbb8fc5cd4d2090811e553c2108cf5112e882f82505ee7495349a6bf/coverage-7.13.4-cp313-cp313t-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:c35eb28c1d085eb7d8c9b3296567a1bebe03ce72962e932431b9a61f28facf26", size = 261057, upload-time = "2026-02-09T12:57:52.447Z" },
+    { url = "https://files.pythonhosted.org/packages/a4/a2/60010c669df5fa603bb5a97fb75407e191a846510da70ac657eb696b7fce/coverage-7.13.4-cp313-cp313t-musllinux_1_2_aarch64.whl", hash = "sha256:eb88b316ec33760714a4720feb2816a3a59180fd58c1985012054fa7aebee4c2", size = 263875, upload-time = "2026-02-09T12:57:53.938Z" },
+    { url = "https://files.pythonhosted.org/packages/3e/d9/63b22a6bdbd17f1f96e9ed58604c2a6b0e72a9133e37d663bef185877cf6/coverage-7.13.4-cp313-cp313t-musllinux_1_2_i686.whl", hash = "sha256:7d41eead3cc673cbd38a4417deb7fd0b4ca26954ff7dc6078e33f6ff97bed940", size = 261500, upload-time = "2026-02-09T12:57:56.012Z" },
+    { url = "https://files.pythonhosted.org/packages/70/bf/69f86ba1ad85bc3ad240e4c0e57a2e620fbc0e1645a47b5c62f0e941ad7f/coverage-7.13.4-cp313-cp313t-musllinux_1_2_ppc64le.whl", hash = "sha256:fb26a934946a6afe0e326aebe0730cdff393a8bc0bbb65a2f41e30feddca399c", size = 265212, upload-time = "2026-02-09T12:57:57.5Z" },
+    { url = "https://files.pythonhosted.org/packages/ae/f2/5f65a278a8c2148731831574c73e42f57204243d33bedaaf18fa79c5958f/coverage-7.13.4-cp313-cp313t-musllinux_1_2_riscv64.whl", hash = "sha256:dae88bc0fc77edaa65c14be099bd57ee140cf507e6bfdeea7938457ab387efb0", size = 260398, upload-time = "2026-02-09T12:57:59.027Z" },
+    { url = "https://files.pythonhosted.org/packages/ef/80/6e8280a350ee9fea92f14b8357448a242dcaa243cb2c72ab0ca591f66c8c/coverage-7.13.4-cp313-cp313t-musllinux_1_2_x86_64.whl", hash = "sha256:845f352911777a8e722bfce168958214951e07e47e5d5d9744109fa5fe77f79b", size = 262584, upload-time = "2026-02-09T12:58:01.129Z" },
+    { url = "https://files.pythonhosted.org/packages/22/63/01ff182fc95f260b539590fb12c11ad3e21332c15f9799cb5e2386f71d9f/coverage-7.13.4-cp313-cp313t-win32.whl", hash = "sha256:2fa8d5f8de70688a28240de9e139fa16b153cc3cbb01c5f16d88d6505ebdadf9", size = 222688, upload-time = "2026-02-09T12:58:02.736Z" },
+    { url = "https://files.pythonhosted.org/packages/a9/43/89de4ef5d3cd53b886afa114065f7e9d3707bdb3e5efae13535b46ae483d/coverage-7.13.4-cp313-cp313t-win_amd64.whl", hash = "sha256:9351229c8c8407645840edcc277f4a2d44814d1bc34a2128c11c2a031d45a5dd", size = 223746, upload-time = "2026-02-09T12:58:05.362Z" },
+    { url = "https://files.pythonhosted.org/packages/35/39/7cf0aa9a10d470a5309b38b289b9bb07ddeac5d61af9b664fe9775a4cb3e/coverage-7.13.4-cp313-cp313t-win_arm64.whl", hash = "sha256:30b8d0512f2dc8c8747557e8fb459d6176a2c9e5731e2b74d311c03b78451997", size = 222003, upload-time = "2026-02-09T12:58:06.952Z" },
+    { url = "https://files.pythonhosted.org/packages/92/11/a9cf762bb83386467737d32187756a42094927150c3e107df4cb078e8590/coverage-7.13.4-cp314-cp314-macosx_10_15_x86_64.whl", hash = "sha256:300deaee342f90696ed186e3a00c71b5b3d27bffe9e827677954f4ee56969601", size = 219522, upload-time = "2026-02-09T12:58:08.623Z" },
+    { url = "https://files.pythonhosted.org/packages/d3/28/56e6d892b7b052236d67c95f1936b6a7cf7c3e2634bf27610b8cbd7f9c60/coverage-7.13.4-cp314-cp314-macosx_11_0_arm64.whl", hash = "sha256:29e3220258d682b6226a9b0925bc563ed9a1ebcff3cad30f043eceea7eaf2689", size = 219855, upload-time = "2026-02-09T12:58:10.176Z" },
+    { url = "https://files.pythonhosted.org/packages/e5/69/233459ee9eb0c0d10fcc2fe425a029b3fa5ce0f040c966ebce851d030c70/coverage-7.13.4-cp314-cp314-manylinux1_i686.manylinux_2_28_i686.manylinux_2_5_i686.whl", hash = "sha256:391ee8f19bef69210978363ca930f7328081c6a0152f1166c91f0b5fdd2a773c", size = 250887, upload-time = "2026-02-09T12:58:12.503Z" },
+    { url = "https://files.pythonhosted.org/packages/06/90/2cdab0974b9b5bbc1623f7876b73603aecac11b8d95b85b5b86b32de5eab/coverage-7.13.4-cp314-cp314-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl", hash = "sha256:0dd7ab8278f0d58a0128ba2fca25824321f05d059c1441800e934ff2efa52129", size = 253396, upload-time = "2026-02-09T12:58:14.615Z" },
+    { url = "https://files.pythonhosted.org/packages/ac/15/ea4da0f85bf7d7b27635039e649e99deb8173fe551096ea15017f7053537/coverage-7.13.4-cp314-cp314-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:78cdf0d578b15148b009ccf18c686aa4f719d887e76e6b40c38ffb61d264a552", size = 254745, upload-time = "2026-02-09T12:58:16.162Z" },
+    { url = "https://files.pythonhosted.org/packages/99/11/bb356e86920c655ca4d61daee4e2bbc7258f0a37de0be32d233b561134ff/coverage-7.13.4-cp314-cp314-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:48685fee12c2eb3b27c62f2658e7ea21e9c3239cba5a8a242801a0a3f6a8c62a", size = 257055, upload-time = "2026-02-09T12:58:17.892Z" },
+    { url = "https://files.pythonhosted.org/packages/c9/0f/9ae1f8cb17029e09da06ca4e28c9e1d5c1c0a511c7074592e37e0836c915/coverage-7.13.4-cp314-cp314-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:4e83efc079eb39480e6346a15a1bcb3e9b04759c5202d157e1dd4303cd619356", size = 250911, upload-time = "2026-02-09T12:58:19.495Z" },
+    { url = "https://files.pythonhosted.org/packages/89/3a/adfb68558fa815cbc29747b553bc833d2150228f251b127f1ce97e48547c/coverage-7.13.4-cp314-cp314-musllinux_1_2_aarch64.whl", hash = "sha256:ecae9737b72408d6a950f7e525f30aca12d4bd8dd95e37342e5beb3a2a8c4f71", size = 252754, upload-time = "2026-02-09T12:58:21.064Z" },
+    { url = "https://files.pythonhosted.org/packages/32/b1/540d0c27c4e748bd3cd0bd001076ee416eda993c2bae47a73b7cc9357931/coverage-7.13.4-cp314-cp314-musllinux_1_2_i686.whl", hash = "sha256:ae4578f8528569d3cf303fef2ea569c7f4c4059a38c8667ccef15c6e1f118aa5", size = 250720, upload-time = "2026-02-09T12:58:22.622Z" },
+    { url = "https://files.pythonhosted.org/packages/c7/95/383609462b3ffb1fe133014a7c84fc0dd01ed55ac6140fa1093b5af7ebb1/coverage-7.13.4-cp314-cp314-musllinux_1_2_ppc64le.whl", hash = "sha256:6fdef321fdfbb30a197efa02d48fcd9981f0d8ad2ae8903ac318adc653f5df98", size = 254994, upload-time = "2026-02-09T12:58:24.548Z" },
+    { url = "https://files.pythonhosted.org/packages/f7/ba/1761138e86c81680bfc3c49579d66312865457f9fe405b033184e5793cb3/coverage-7.13.4-cp314-cp314-musllinux_1_2_riscv64.whl", hash = "sha256:2b0f6ccf3dbe577170bebfce1318707d0e8c3650003cb4b3a9dd744575daa8b5", size = 250531, upload-time = "2026-02-09T12:58:26.271Z" },
+    { url = "https://files.pythonhosted.org/packages/f8/8e/05900df797a9c11837ab59c4d6fe94094e029582aab75c3309a93e6fb4e3/coverage-7.13.4-cp314-cp314-musllinux_1_2_x86_64.whl", hash = "sha256:75fcd519f2a5765db3f0e391eb3b7d150cce1a771bf4c9f861aeab86c767a3c0", size = 252189, upload-time = "2026-02-09T12:58:27.807Z" },
+    { url = "https://files.pythonhosted.org/packages/00/bd/29c9f2db9ea4ed2738b8a9508c35626eb205d51af4ab7bf56a21a2e49926/coverage-7.13.4-cp314-cp314-win32.whl", hash = "sha256:8e798c266c378da2bd819b0677df41ab46d78065fb2a399558f3f6cae78b2fbb", size = 222258, upload-time = "2026-02-09T12:58:29.441Z" },
+    { url = "https://files.pythonhosted.org/packages/a7/4d/1f8e723f6829977410efeb88f73673d794075091c8c7c18848d273dc9d73/coverage-7.13.4-cp314-cp314-win_amd64.whl", hash = "sha256:245e37f664d89861cf2329c9afa2c1fe9e6d4e1a09d872c947e70718aeeac505", size = 223073, upload-time = "2026-02-09T12:58:31.026Z" },
+    { url = "https://files.pythonhosted.org/packages/51/5b/84100025be913b44e082ea32abcf1afbf4e872f5120b7a1cab1d331b1e13/coverage-7.13.4-cp314-cp314-win_arm64.whl", hash = "sha256:ad27098a189e5838900ce4c2a99f2fe42a0bf0c2093c17c69b45a71579e8d4a2", size = 221638, upload-time = "2026-02-09T12:58:32.599Z" },
+    { url = "https://files.pythonhosted.org/packages/a7/e4/c884a405d6ead1370433dad1e3720216b4f9fd8ef5b64bfd984a2a60a11a/coverage-7.13.4-cp314-cp314t-macosx_10_15_x86_64.whl", hash = "sha256:85480adfb35ffc32d40918aad81b89c69c9cc5661a9b8a81476d3e645321a056", size = 220246, upload-time = "2026-02-09T12:58:34.181Z" },
+    { url = "https://files.pythonhosted.org/packages/81/5c/4d7ed8b23b233b0fffbc9dfec53c232be2e695468523242ea9fd30f97ad2/coverage-7.13.4-cp314-cp314t-macosx_11_0_arm64.whl", hash = "sha256:79be69cf7f3bf9b0deeeb062eab7ac7f36cd4cc4c4dd694bd28921ba4d8596cc", size = 220514, upload-time = "2026-02-09T12:58:35.704Z" },
+    { url = "https://files.pythonhosted.org/packages/2f/6f/3284d4203fd2f28edd73034968398cd2d4cb04ab192abc8cff007ea35679/coverage-7.13.4-cp314-cp314t-manylinux1_i686.manylinux_2_28_i686.manylinux_2_5_i686.whl", hash = "sha256:caa421e2684e382c5d8973ac55e4f36bed6821a9bad5c953494de960c74595c9", size = 261877, upload-time = "2026-02-09T12:58:37.864Z" },
+    { url = "https://files.pythonhosted.org/packages/09/aa/b672a647bbe1556a85337dc95bfd40d146e9965ead9cc2fe81bde1e5cbce/coverage-7.13.4-cp314-cp314t-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl", hash = "sha256:14375934243ee05f56c45393fe2ce81fe5cc503c07cee2bdf1725fb8bef3ffaf", size = 264004, upload-time = "2026-02-09T12:58:39.492Z" },
+    { url = "https://files.pythonhosted.org/packages/79/a1/aa384dbe9181f98bba87dd23dda436f0c6cf2e148aecbb4e50fc51c1a656/coverage-7.13.4-cp314-cp314t-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:25a41c3104d08edb094d9db0d905ca54d0cd41c928bb6be3c4c799a54753af55", size = 266408, upload-time = "2026-02-09T12:58:41.852Z" },
+    { url = "https://files.pythonhosted.org/packages/53/5e/5150bf17b4019bc600799f376bb9606941e55bd5a775dc1e096b6ffea952/coverage-7.13.4-cp314-cp314t-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:6f01afcff62bf9a08fb32b2c1d6e924236c0383c02c790732b6537269e466a72", size = 267544, upload-time = "2026-02-09T12:58:44.093Z" },
+    { url = "https://files.pythonhosted.org/packages/e0/ed/f1de5c675987a4a7a672250d2c5c9d73d289dbf13410f00ed7181d8017dd/coverage-7.13.4-cp314-cp314t-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:eb9078108fbf0bcdde37c3f4779303673c2fa1fe8f7956e68d447d0dd426d38a", size = 260980, upload-time = "2026-02-09T12:58:45.721Z" },
+    { url = "https://files.pythonhosted.org/packages/b3/e3/fe758d01850aa172419a6743fe76ba8b92c29d181d4f676ffe2dae2ba631/coverage-7.13.4-cp314-cp314t-musllinux_1_2_aarch64.whl", hash = "sha256:0e086334e8537ddd17e5f16a344777c1ab8194986ec533711cbe6c41cde841b6", size = 263871, upload-time = "2026-02-09T12:58:47.334Z" },
+    { url = "https://files.pythonhosted.org/packages/b6/76/b829869d464115e22499541def9796b25312b8cf235d3bb00b39f1675395/coverage-7.13.4-cp314-cp314t-musllinux_1_2_i686.whl", hash = "sha256:725d985c5ab621268b2edb8e50dfe57633dc69bda071abc470fed55a14935fd3", size = 261472, upload-time = "2026-02-09T12:58:48.995Z" },
+    { url = "https://files.pythonhosted.org/packages/14/9e/caedb1679e73e2f6ad240173f55218488bfe043e38da577c4ec977489915/coverage-7.13.4-cp314-cp314t-musllinux_1_2_ppc64le.whl", hash = "sha256:3c06f0f1337c667b971ca2f975523347e63ec5e500b9aa5882d91931cd3ef750", size = 265210, upload-time = "2026-02-09T12:58:51.178Z" },
+    { url = "https://files.pythonhosted.org/packages/3a/10/0dd02cb009b16ede425b49ec344aba13a6ae1dc39600840ea6abcb085ac4/coverage-7.13.4-cp314-cp314t-musllinux_1_2_riscv64.whl", hash = "sha256:590c0ed4bf8e85f745e6b805b2e1c457b2e33d5255dd9729743165253bc9ad39", size = 260319, upload-time = "2026-02-09T12:58:53.081Z" },
+    { url = "https://files.pythonhosted.org/packages/92/8e/234d2c927af27c6d7a5ffad5bd2cf31634c46a477b4c7adfbfa66baf7ebb/coverage-7.13.4-cp314-cp314t-musllinux_1_2_x86_64.whl", hash = "sha256:eb30bf180de3f632cd043322dad5751390e5385108b2807368997d1a92a509d0", size = 262638, upload-time = "2026-02-09T12:58:55.258Z" },
+    { url = "https://files.pythonhosted.org/packages/2f/64/e5547c8ff6964e5965c35a480855911b61509cce544f4d442caa759a0702/coverage-7.13.4-cp314-cp314t-win32.whl", hash = "sha256:c4240e7eded42d131a2d2c4dec70374b781b043ddc79a9de4d55ca71f8e98aea", size = 223040, upload-time = "2026-02-09T12:58:56.936Z" },
+    { url = "https://files.pythonhosted.org/packages/c7/96/38086d58a181aac86d503dfa9c47eb20715a79c3e3acbdf786e92e5c09a8/coverage-7.13.4-cp314-cp314t-win_amd64.whl", hash = "sha256:4c7d3cc01e7350f2f0f6f7036caaf5673fb56b6998889ccfe9e1c1fe75a9c932", size = 224148, upload-time = "2026-02-09T12:58:58.645Z" },
+    { url = "https://files.pythonhosted.org/packages/ce/72/8d10abd3740a0beb98c305e0c3faf454366221c0f37a8bcf8f60020bb65a/coverage-7.13.4-cp314-cp314t-win_arm64.whl", hash = "sha256:23e3f687cf945070d1c90f85db66d11e3025665d8dafa831301a0e0038f3db9b", size = 222172, upload-time = "2026-02-09T12:59:00.396Z" },
+    { url = "https://files.pythonhosted.org/packages/0d/4a/331fe2caf6799d591109bb9c08083080f6de90a823695d412a935622abb2/coverage-7.13.4-py3-none-any.whl", hash = "sha256:1af1641e57cf7ba1bd67d677c9abdbcd6cc2ab7da3bca7fa1e2b7e50e65f2ad0", size = 211242, upload-time = "2026-02-09T12:59:02.032Z" },
 ]
 
 [package.optional-dependencies]
@@ -336,51 +350,51 @@ toml = [
 
 [[package]]
 name = "cryptography"
-version = "46.0.4"
+version = "46.0.5"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
     { name = "cffi", marker = "platform_python_implementation != 'PyPy'" },
     { name = "typing-extensions", marker = "python_full_version < '3.11'" },
 ]
-sdist = { url = "https://files.pythonhosted.org/packages/78/19/f748958276519adf6a0c1e79e7b8860b4830dda55ccdf29f2719b5fc499c/cryptography-46.0.4.tar.gz", hash = "sha256:bfd019f60f8abc2ed1b9be4ddc21cfef059c841d86d710bb69909a688cbb8f59", size = 749301, upload-time = "2026-01-28T00:24:37.379Z" }
+sdist = { url = "https://files.pythonhosted.org/packages/60/04/ee2a9e8542e4fa2773b81771ff8349ff19cdd56b7258a0cc442639052edb/cryptography-46.0.5.tar.gz", hash = "sha256:abace499247268e3757271b2f1e244b36b06f8515cf27c4d49468fc9eb16e93d", size = 750064, upload-time = "2026-02-10T19:18:38.255Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/87/91/874b8910903159043b5c6a123b7e79c4559ddd1896e38967567942635778/cryptography-46.0.4-cp311-abi3-manylinux2014_aarch64.manylinux_2_17_aarch64.whl", hash = "sha256:5f14fba5bf6f4390d7ff8f086c566454bff0411f6d8aa7af79c88b6f9267aecc", size = 4275871, upload-time = "2026-01-28T00:23:09.439Z" },
-    { url = "https://files.pythonhosted.org/packages/c0/35/690e809be77896111f5b195ede56e4b4ed0435b428c2f2b6d35046fbb5e8/cryptography-46.0.4-cp311-abi3-manylinux2014_x86_64.manylinux_2_17_x86_64.whl", hash = "sha256:47bcd19517e6389132f76e2d5303ded6cf3f78903da2158a671be8de024f4cd0", size = 4423124, upload-time = "2026-01-28T00:23:11.529Z" },
-    { url = "https://files.pythonhosted.org/packages/1a/5b/a26407d4f79d61ca4bebaa9213feafdd8806dc69d3d290ce24996d3cfe43/cryptography-46.0.4-cp311-abi3-manylinux_2_28_aarch64.whl", hash = "sha256:01df4f50f314fbe7009f54046e908d1754f19d0c6d3070df1e6268c5a4af09fa", size = 4277090, upload-time = "2026-01-28T00:23:13.123Z" },
-    { url = "https://files.pythonhosted.org/packages/0c/d8/4bb7aec442a9049827aa34cee1aa83803e528fa55da9a9d45d01d1bb933e/cryptography-46.0.4-cp311-abi3-manylinux_2_28_ppc64le.whl", hash = "sha256:5aa3e463596b0087b3da0dbe2b2487e9fc261d25da85754e30e3b40637d61f81", size = 4947652, upload-time = "2026-01-28T00:23:14.554Z" },
-    { url = "https://files.pythonhosted.org/packages/2b/08/f83e2e0814248b844265802d081f2fac2f1cbe6cd258e72ba14ff006823a/cryptography-46.0.4-cp311-abi3-manylinux_2_28_x86_64.whl", hash = "sha256:0a9ad24359fee86f131836a9ac3bffc9329e956624a2d379b613f8f8abaf5255", size = 4455157, upload-time = "2026-01-28T00:23:16.443Z" },
-    { url = "https://files.pythonhosted.org/packages/0a/05/19d849cf4096448779d2dcc9bb27d097457dac36f7273ffa875a93b5884c/cryptography-46.0.4-cp311-abi3-manylinux_2_31_armv7l.whl", hash = "sha256:dc1272e25ef673efe72f2096e92ae39dea1a1a450dd44918b15351f72c5a168e", size = 3981078, upload-time = "2026-01-28T00:23:17.838Z" },
-    { url = "https://files.pythonhosted.org/packages/e6/89/f7bac81d66ba7cde867a743ea5b37537b32b5c633c473002b26a226f703f/cryptography-46.0.4-cp311-abi3-manylinux_2_34_aarch64.whl", hash = "sha256:de0f5f4ec8711ebc555f54735d4c673fc34b65c44283895f1a08c2b49d2fd99c", size = 4276213, upload-time = "2026-01-28T00:23:19.257Z" },
-    { url = "https://files.pythonhosted.org/packages/da/9f/7133e41f24edd827020ad21b068736e792bc68eecf66d93c924ad4719fb3/cryptography-46.0.4-cp311-abi3-manylinux_2_34_ppc64le.whl", hash = "sha256:eeeb2e33d8dbcccc34d64651f00a98cb41b2dc69cef866771a5717e6734dfa32", size = 4912190, upload-time = "2026-01-28T00:23:21.244Z" },
-    { url = "https://files.pythonhosted.org/packages/a6/f7/6d43cbaddf6f65b24816e4af187d211f0bc536a29961f69faedc48501d8e/cryptography-46.0.4-cp311-abi3-manylinux_2_34_x86_64.whl", hash = "sha256:3d425eacbc9aceafd2cb429e42f4e5d5633c6f873f5e567077043ef1b9bbf616", size = 4454641, upload-time = "2026-01-28T00:23:22.866Z" },
-    { url = "https://files.pythonhosted.org/packages/9e/4f/ebd0473ad656a0ac912a16bd07db0f5d85184924e14fc88feecae2492834/cryptography-46.0.4-cp311-abi3-musllinux_1_2_aarch64.whl", hash = "sha256:91627ebf691d1ea3976a031b61fb7bac1ccd745afa03602275dda443e11c8de0", size = 4405159, upload-time = "2026-01-28T00:23:25.278Z" },
-    { url = "https://files.pythonhosted.org/packages/d1/f7/7923886f32dc47e27adeff8246e976d77258fd2aa3efdd1754e4e323bf49/cryptography-46.0.4-cp311-abi3-musllinux_1_2_x86_64.whl", hash = "sha256:2d08bc22efd73e8854b0b7caff402d735b354862f1145d7be3b9c0f740fef6a0", size = 4666059, upload-time = "2026-01-28T00:23:26.766Z" },
-    { url = "https://files.pythonhosted.org/packages/f8/f5/559c25b77f40b6bf828eabaf988efb8b0e17b573545edb503368ca0a2a03/cryptography-46.0.4-cp314-cp314t-manylinux2014_aarch64.manylinux_2_17_aarch64.whl", hash = "sha256:078e5f06bd2fa5aea5a324f2a09f914b1484f1d0c2a4d6a8a28c74e72f65f2da", size = 4264508, upload-time = "2026-01-28T00:23:34.264Z" },
-    { url = "https://files.pythonhosted.org/packages/49/a1/551fa162d33074b660dc35c9bc3616fefa21a0e8c1edd27b92559902e408/cryptography-46.0.4-cp314-cp314t-manylinux2014_x86_64.manylinux_2_17_x86_64.whl", hash = "sha256:dce1e4f068f03008da7fa51cc7abc6ddc5e5de3e3d1550334eaf8393982a5829", size = 4409080, upload-time = "2026-01-28T00:23:35.793Z" },
-    { url = "https://files.pythonhosted.org/packages/b0/6a/4d8d129a755f5d6df1bbee69ea2f35ebfa954fa1847690d1db2e8bca46a5/cryptography-46.0.4-cp314-cp314t-manylinux_2_28_aarch64.whl", hash = "sha256:2067461c80271f422ee7bdbe79b9b4be54a5162e90345f86a23445a0cf3fd8a2", size = 4270039, upload-time = "2026-01-28T00:23:37.263Z" },
-    { url = "https://files.pythonhosted.org/packages/4c/f5/ed3fcddd0a5e39321e595e144615399e47e7c153a1fb8c4862aec3151ff9/cryptography-46.0.4-cp314-cp314t-manylinux_2_28_ppc64le.whl", hash = "sha256:c92010b58a51196a5f41c3795190203ac52edfd5dc3ff99149b4659eba9d2085", size = 4926748, upload-time = "2026-01-28T00:23:38.884Z" },
-    { url = "https://files.pythonhosted.org/packages/43/ae/9f03d5f0c0c00e85ecb34f06d3b79599f20630e4db91b8a6e56e8f83d410/cryptography-46.0.4-cp314-cp314t-manylinux_2_28_x86_64.whl", hash = "sha256:829c2b12bbc5428ab02d6b7f7e9bbfd53e33efd6672d21341f2177470171ad8b", size = 4442307, upload-time = "2026-01-28T00:23:40.56Z" },
-    { url = "https://files.pythonhosted.org/packages/8b/22/e0f9f2dae8040695103369cf2283ef9ac8abe4d51f68710bec2afd232609/cryptography-46.0.4-cp314-cp314t-manylinux_2_31_armv7l.whl", hash = "sha256:62217ba44bf81b30abaeda1488686a04a702a261e26f87db51ff61d9d3510abd", size = 3959253, upload-time = "2026-01-28T00:23:42.827Z" },
-    { url = "https://files.pythonhosted.org/packages/01/5b/6a43fcccc51dae4d101ac7d378a8724d1ba3de628a24e11bf2f4f43cba4d/cryptography-46.0.4-cp314-cp314t-manylinux_2_34_aarch64.whl", hash = "sha256:9c2da296c8d3415b93e6053f5a728649a87a48ce084a9aaf51d6e46c87c7f2d2", size = 4269372, upload-time = "2026-01-28T00:23:44.655Z" },
-    { url = "https://files.pythonhosted.org/packages/17/b7/0f6b8c1dd0779df2b526e78978ff00462355e31c0a6f6cff8a3e99889c90/cryptography-46.0.4-cp314-cp314t-manylinux_2_34_ppc64le.whl", hash = "sha256:9b34d8ba84454641a6bf4d6762d15847ecbd85c1316c0a7984e6e4e9f748ec2e", size = 4891908, upload-time = "2026-01-28T00:23:46.48Z" },
-    { url = "https://files.pythonhosted.org/packages/83/17/259409b8349aa10535358807a472c6a695cf84f106022268d31cea2b6c97/cryptography-46.0.4-cp314-cp314t-manylinux_2_34_x86_64.whl", hash = "sha256:df4a817fa7138dd0c96c8c8c20f04b8aaa1fac3bbf610913dcad8ea82e1bfd3f", size = 4441254, upload-time = "2026-01-28T00:23:48.403Z" },
-    { url = "https://files.pythonhosted.org/packages/9c/fe/e4a1b0c989b00cee5ffa0764401767e2d1cf59f45530963b894129fd5dce/cryptography-46.0.4-cp314-cp314t-musllinux_1_2_aarch64.whl", hash = "sha256:b1de0ebf7587f28f9190b9cb526e901bf448c9e6a99655d2b07fff60e8212a82", size = 4396520, upload-time = "2026-01-28T00:23:50.26Z" },
-    { url = "https://files.pythonhosted.org/packages/b3/81/ba8fd9657d27076eb40d6a2f941b23429a3c3d2f56f5a921d6b936a27bc9/cryptography-46.0.4-cp314-cp314t-musllinux_1_2_x86_64.whl", hash = "sha256:9b4d17bc7bd7cdd98e3af40b441feaea4c68225e2eb2341026c84511ad246c0c", size = 4651479, upload-time = "2026-01-28T00:23:51.674Z" },
-    { url = "https://files.pythonhosted.org/packages/d8/cc/8f3224cbb2a928de7298d6ed4790f5ebc48114e02bdc9559196bfb12435d/cryptography-46.0.4-cp38-abi3-manylinux2014_aarch64.manylinux_2_17_aarch64.whl", hash = "sha256:8bf75b0259e87fa70bddc0b8b4078b76e7fd512fd9afae6c1193bcf440a4dbef", size = 4275419, upload-time = "2026-01-28T00:23:58.364Z" },
-    { url = "https://files.pythonhosted.org/packages/17/43/4a18faa7a872d00e4264855134ba82d23546c850a70ff209e04ee200e76f/cryptography-46.0.4-cp38-abi3-manylinux2014_x86_64.manylinux_2_17_x86_64.whl", hash = "sha256:3c268a3490df22270955966ba236d6bc4a8f9b6e4ffddb78aac535f1a5ea471d", size = 4419058, upload-time = "2026-01-28T00:23:59.867Z" },
-    { url = "https://files.pythonhosted.org/packages/ee/64/6651969409821d791ba12346a124f55e1b76f66a819254ae840a965d4b9c/cryptography-46.0.4-cp38-abi3-manylinux_2_28_aarch64.whl", hash = "sha256:812815182f6a0c1d49a37893a303b44eaac827d7f0d582cecfc81b6427f22973", size = 4278151, upload-time = "2026-01-28T00:24:01.731Z" },
-    { url = "https://files.pythonhosted.org/packages/20/0b/a7fce65ee08c3c02f7a8310cc090a732344066b990ac63a9dfd0a655d321/cryptography-46.0.4-cp38-abi3-manylinux_2_28_ppc64le.whl", hash = "sha256:a90e43e3ef65e6dcf969dfe3bb40cbf5aef0d523dff95bfa24256be172a845f4", size = 4939441, upload-time = "2026-01-28T00:24:03.175Z" },
-    { url = "https://files.pythonhosted.org/packages/db/a7/20c5701e2cd3e1dfd7a19d2290c522a5f435dd30957d431dcb531d0f1413/cryptography-46.0.4-cp38-abi3-manylinux_2_28_x86_64.whl", hash = "sha256:a05177ff6296644ef2876fce50518dffb5bcdf903c85250974fc8bc85d54c0af", size = 4451617, upload-time = "2026-01-28T00:24:05.403Z" },
-    { url = "https://files.pythonhosted.org/packages/00/dc/3e16030ea9aa47b63af6524c354933b4fb0e352257c792c4deeb0edae367/cryptography-46.0.4-cp38-abi3-manylinux_2_31_armv7l.whl", hash = "sha256:daa392191f626d50f1b136c9b4cf08af69ca8279d110ea24f5c2700054d2e263", size = 3977774, upload-time = "2026-01-28T00:24:06.851Z" },
-    { url = "https://files.pythonhosted.org/packages/42/c8/ad93f14118252717b465880368721c963975ac4b941b7ef88f3c56bf2897/cryptography-46.0.4-cp38-abi3-manylinux_2_34_aarch64.whl", hash = "sha256:e07ea39c5b048e085f15923511d8121e4a9dc45cee4e3b970ca4f0d338f23095", size = 4277008, upload-time = "2026-01-28T00:24:08.926Z" },
-    { url = "https://files.pythonhosted.org/packages/00/cf/89c99698151c00a4631fbfcfcf459d308213ac29e321b0ff44ceeeac82f1/cryptography-46.0.4-cp38-abi3-manylinux_2_34_ppc64le.whl", hash = "sha256:d5a45ddc256f492ce42a4e35879c5e5528c09cd9ad12420828c972951d8e016b", size = 4903339, upload-time = "2026-01-28T00:24:12.009Z" },
-    { url = "https://files.pythonhosted.org/packages/03/c3/c90a2cb358de4ac9309b26acf49b2a100957e1ff5cc1e98e6c4996576710/cryptography-46.0.4-cp38-abi3-manylinux_2_34_x86_64.whl", hash = "sha256:6bb5157bf6a350e5b28aee23beb2d84ae6f5be390b2f8ee7ea179cda077e1019", size = 4451216, upload-time = "2026-01-28T00:24:13.975Z" },
-    { url = "https://files.pythonhosted.org/packages/96/2c/8d7f4171388a10208671e181ca43cdc0e596d8259ebacbbcfbd16de593da/cryptography-46.0.4-cp38-abi3-musllinux_1_2_aarch64.whl", hash = "sha256:dd5aba870a2c40f87a3af043e0dee7d9eb02d4aff88a797b48f2b43eff8c3ab4", size = 4404299, upload-time = "2026-01-28T00:24:16.169Z" },
-    { url = "https://files.pythonhosted.org/packages/e9/23/cbb2036e450980f65c6e0a173b73a56ff3bccd8998965dea5cc9ddd424a5/cryptography-46.0.4-cp38-abi3-musllinux_1_2_x86_64.whl", hash = "sha256:93d8291da8d71024379ab2cb0b5c57915300155ad42e07f76bea6ad838d7e59b", size = 4664837, upload-time = "2026-01-28T00:24:17.629Z" },
-    { url = "https://files.pythonhosted.org/packages/27/7a/f8d2d13227a9a1a9fe9c7442b057efecffa41f1e3c51d8622f26b9edbe8f/cryptography-46.0.4-pp311-pypy311_pp73-manylinux_2_28_aarch64.whl", hash = "sha256:c236a44acfb610e70f6b3e1c3ca20ff24459659231ef2f8c48e879e2d32b73da", size = 4216693, upload-time = "2026-01-28T00:24:25.758Z" },
-    { url = "https://files.pythonhosted.org/packages/c5/de/3787054e8f7972658370198753835d9d680f6cd4a39df9f877b57f0dd69c/cryptography-46.0.4-pp311-pypy311_pp73-manylinux_2_28_x86_64.whl", hash = "sha256:8a15fb869670efa8f83cbffbc8753c1abf236883225aed74cd179b720ac9ec80", size = 4382765, upload-time = "2026-01-28T00:24:27.577Z" },
-    { url = "https://files.pythonhosted.org/packages/8a/5f/60e0afb019973ba6a0b322e86b3d61edf487a4f5597618a430a2a15f2d22/cryptography-46.0.4-pp311-pypy311_pp73-manylinux_2_34_aarch64.whl", hash = "sha256:fdc3daab53b212472f1524d070735b2f0c214239df131903bae1d598016fa822", size = 4216066, upload-time = "2026-01-28T00:24:29.056Z" },
-    { url = "https://files.pythonhosted.org/packages/81/8e/bf4a0de294f147fee66f879d9bae6f8e8d61515558e3d12785dd90eca0be/cryptography-46.0.4-pp311-pypy311_pp73-manylinux_2_34_x86_64.whl", hash = "sha256:44cc0675b27cadb71bdbb96099cca1fa051cd11d2ade09e5cd3a2edb929ed947", size = 4382025, upload-time = "2026-01-28T00:24:30.681Z" },
+    { url = "https://files.pythonhosted.org/packages/ff/9e/6b4397a3e3d15123de3b1806ef342522393d50736c13b20ec4c9ea6693a6/cryptography-46.0.5-cp311-abi3-manylinux2014_aarch64.manylinux_2_17_aarch64.whl", hash = "sha256:c18ff11e86df2e28854939acde2d003f7984f721eba450b56a200ad90eeb0e6b", size = 4275637, upload-time = "2026-02-10T19:17:10.53Z" },
+    { url = "https://files.pythonhosted.org/packages/63/e7/471ab61099a3920b0c77852ea3f0ea611c9702f651600397ac567848b897/cryptography-46.0.5-cp311-abi3-manylinux2014_x86_64.manylinux_2_17_x86_64.whl", hash = "sha256:4d7e3d356b8cd4ea5aff04f129d5f66ebdc7b6f8eae802b93739ed520c47c79b", size = 4424742, upload-time = "2026-02-10T19:17:12.388Z" },
+    { url = "https://files.pythonhosted.org/packages/37/53/a18500f270342d66bf7e4d9f091114e31e5ee9e7375a5aba2e85a91e0044/cryptography-46.0.5-cp311-abi3-manylinux_2_28_aarch64.whl", hash = "sha256:50bfb6925eff619c9c023b967d5b77a54e04256c4281b0e21336a130cd7fc263", size = 4277528, upload-time = "2026-02-10T19:17:13.853Z" },
+    { url = "https://files.pythonhosted.org/packages/22/29/c2e812ebc38c57b40e7c583895e73c8c5adb4d1e4a0cc4c5a4fdab2b1acc/cryptography-46.0.5-cp311-abi3-manylinux_2_28_ppc64le.whl", hash = "sha256:803812e111e75d1aa73690d2facc295eaefd4439be1023fefc4995eaea2af90d", size = 4947993, upload-time = "2026-02-10T19:17:15.618Z" },
+    { url = "https://files.pythonhosted.org/packages/6b/e7/237155ae19a9023de7e30ec64e5d99a9431a567407ac21170a046d22a5a3/cryptography-46.0.5-cp311-abi3-manylinux_2_28_x86_64.whl", hash = "sha256:3ee190460e2fbe447175cda91b88b84ae8322a104fc27766ad09428754a618ed", size = 4456855, upload-time = "2026-02-10T19:17:17.221Z" },
+    { url = "https://files.pythonhosted.org/packages/2d/87/fc628a7ad85b81206738abbd213b07702bcbdada1dd43f72236ef3cffbb5/cryptography-46.0.5-cp311-abi3-manylinux_2_31_armv7l.whl", hash = "sha256:f145bba11b878005c496e93e257c1e88f154d278d2638e6450d17e0f31e558d2", size = 3984635, upload-time = "2026-02-10T19:17:18.792Z" },
+    { url = "https://files.pythonhosted.org/packages/84/29/65b55622bde135aedf4565dc509d99b560ee4095e56989e815f8fd2aa910/cryptography-46.0.5-cp311-abi3-manylinux_2_34_aarch64.whl", hash = "sha256:e9251e3be159d1020c4030bd2e5f84d6a43fe54b6c19c12f51cde9542a2817b2", size = 4277038, upload-time = "2026-02-10T19:17:20.256Z" },
+    { url = "https://files.pythonhosted.org/packages/bc/36/45e76c68d7311432741faf1fbf7fac8a196a0a735ca21f504c75d37e2558/cryptography-46.0.5-cp311-abi3-manylinux_2_34_ppc64le.whl", hash = "sha256:47fb8a66058b80e509c47118ef8a75d14c455e81ac369050f20ba0d23e77fee0", size = 4912181, upload-time = "2026-02-10T19:17:21.825Z" },
+    { url = "https://files.pythonhosted.org/packages/6d/1a/c1ba8fead184d6e3d5afcf03d569acac5ad063f3ac9fb7258af158f7e378/cryptography-46.0.5-cp311-abi3-manylinux_2_34_x86_64.whl", hash = "sha256:4c3341037c136030cb46e4b1e17b7418ea4cbd9dd207e4a6f3b2b24e0d4ac731", size = 4456482, upload-time = "2026-02-10T19:17:25.133Z" },
+    { url = "https://files.pythonhosted.org/packages/f9/e5/3fb22e37f66827ced3b902cf895e6a6bc1d095b5b26be26bd13c441fdf19/cryptography-46.0.5-cp311-abi3-musllinux_1_2_aarch64.whl", hash = "sha256:890bcb4abd5a2d3f852196437129eb3667d62630333aacc13dfd470fad3aaa82", size = 4405497, upload-time = "2026-02-10T19:17:26.66Z" },
+    { url = "https://files.pythonhosted.org/packages/1a/df/9d58bb32b1121a8a2f27383fabae4d63080c7ca60b9b5c88be742be04ee7/cryptography-46.0.5-cp311-abi3-musllinux_1_2_x86_64.whl", hash = "sha256:80a8d7bfdf38f87ca30a5391c0c9ce4ed2926918e017c29ddf643d0ed2778ea1", size = 4667819, upload-time = "2026-02-10T19:17:28.569Z" },
+    { url = "https://files.pythonhosted.org/packages/67/c8/581a6702e14f0898a0848105cbefd20c058099e2c2d22ef4e476dfec75d7/cryptography-46.0.5-cp314-cp314t-manylinux2014_aarch64.manylinux_2_17_aarch64.whl", hash = "sha256:5be7bf2fb40769e05739dd0046e7b26f9d4670badc7b032d6ce4db64dddc0678", size = 4265728, upload-time = "2026-02-10T19:17:35.569Z" },
+    { url = "https://files.pythonhosted.org/packages/dd/4a/ba1a65ce8fc65435e5a849558379896c957870dd64fecea97b1ad5f46a37/cryptography-46.0.5-cp314-cp314t-manylinux2014_x86_64.manylinux_2_17_x86_64.whl", hash = "sha256:fe346b143ff9685e40192a4960938545c699054ba11d4f9029f94751e3f71d87", size = 4408287, upload-time = "2026-02-10T19:17:36.938Z" },
+    { url = "https://files.pythonhosted.org/packages/f8/67/8ffdbf7b65ed1ac224d1c2df3943553766914a8ca718747ee3871da6107e/cryptography-46.0.5-cp314-cp314t-manylinux_2_28_aarch64.whl", hash = "sha256:c69fd885df7d089548a42d5ec05be26050ebcd2283d89b3d30676eb32ff87dee", size = 4270291, upload-time = "2026-02-10T19:17:38.748Z" },
+    { url = "https://files.pythonhosted.org/packages/f8/e5/f52377ee93bc2f2bba55a41a886fd208c15276ffbd2569f2ddc89d50e2c5/cryptography-46.0.5-cp314-cp314t-manylinux_2_28_ppc64le.whl", hash = "sha256:8293f3dea7fc929ef7240796ba231413afa7b68ce38fd21da2995549f5961981", size = 4927539, upload-time = "2026-02-10T19:17:40.241Z" },
+    { url = "https://files.pythonhosted.org/packages/3b/02/cfe39181b02419bbbbcf3abdd16c1c5c8541f03ca8bda240debc467d5a12/cryptography-46.0.5-cp314-cp314t-manylinux_2_28_x86_64.whl", hash = "sha256:1abfdb89b41c3be0365328a410baa9df3ff8a9110fb75e7b52e66803ddabc9a9", size = 4442199, upload-time = "2026-02-10T19:17:41.789Z" },
+    { url = "https://files.pythonhosted.org/packages/c0/96/2fcaeb4873e536cf71421a388a6c11b5bc846e986b2b069c79363dc1648e/cryptography-46.0.5-cp314-cp314t-manylinux_2_31_armv7l.whl", hash = "sha256:d66e421495fdb797610a08f43b05269e0a5ea7f5e652a89bfd5a7d3c1dee3648", size = 3960131, upload-time = "2026-02-10T19:17:43.379Z" },
+    { url = "https://files.pythonhosted.org/packages/d8/d2/b27631f401ddd644e94c5cf33c9a4069f72011821cf3dc7309546b0642a0/cryptography-46.0.5-cp314-cp314t-manylinux_2_34_aarch64.whl", hash = "sha256:4e817a8920bfbcff8940ecfd60f23d01836408242b30f1a708d93198393a80b4", size = 4270072, upload-time = "2026-02-10T19:17:45.481Z" },
+    { url = "https://files.pythonhosted.org/packages/f4/a7/60d32b0370dae0b4ebe55ffa10e8599a2a59935b5ece1b9f06edb73abdeb/cryptography-46.0.5-cp314-cp314t-manylinux_2_34_ppc64le.whl", hash = "sha256:68f68d13f2e1cb95163fa3b4db4bf9a159a418f5f6e7242564fc75fcae667fd0", size = 4892170, upload-time = "2026-02-10T19:17:46.997Z" },
+    { url = "https://files.pythonhosted.org/packages/d2/b9/cf73ddf8ef1164330eb0b199a589103c363afa0cf794218c24d524a58eab/cryptography-46.0.5-cp314-cp314t-manylinux_2_34_x86_64.whl", hash = "sha256:a3d1fae9863299076f05cb8a778c467578262fae09f9dc0ee9b12eb4268ce663", size = 4441741, upload-time = "2026-02-10T19:17:48.661Z" },
+    { url = "https://files.pythonhosted.org/packages/5f/eb/eee00b28c84c726fe8fa0158c65afe312d9c3b78d9d01daf700f1f6e37ff/cryptography-46.0.5-cp314-cp314t-musllinux_1_2_aarch64.whl", hash = "sha256:c4143987a42a2397f2fc3b4d7e3a7d313fbe684f67ff443999e803dd75a76826", size = 4396728, upload-time = "2026-02-10T19:17:50.058Z" },
+    { url = "https://files.pythonhosted.org/packages/65/f4/6bc1a9ed5aef7145045114b75b77c2a8261b4d38717bd8dea111a63c3442/cryptography-46.0.5-cp314-cp314t-musllinux_1_2_x86_64.whl", hash = "sha256:7d731d4b107030987fd61a7f8ab512b25b53cef8f233a97379ede116f30eb67d", size = 4652001, upload-time = "2026-02-10T19:17:51.54Z" },
+    { url = "https://files.pythonhosted.org/packages/0f/04/c85bdeab78c8bc77b701bf0d9bdcf514c044e18a46dcff330df5448631b0/cryptography-46.0.5-cp38-abi3-manylinux2014_aarch64.manylinux_2_17_aarch64.whl", hash = "sha256:7d1f30a86d2757199cb2d56e48cce14deddf1f9c95f1ef1b64ee91ea43fe2e18", size = 4275349, upload-time = "2026-02-10T19:17:58.419Z" },
+    { url = "https://files.pythonhosted.org/packages/5c/32/9b87132a2f91ee7f5223b091dc963055503e9b442c98fc0b8a5ca765fab0/cryptography-46.0.5-cp38-abi3-manylinux2014_x86_64.manylinux_2_17_x86_64.whl", hash = "sha256:039917b0dc418bb9f6edce8a906572d69e74bd330b0b3fea4f79dab7f8ddd235", size = 4420667, upload-time = "2026-02-10T19:18:00.619Z" },
+    { url = "https://files.pythonhosted.org/packages/a1/a6/a7cb7010bec4b7c5692ca6f024150371b295ee1c108bdc1c400e4c44562b/cryptography-46.0.5-cp38-abi3-manylinux_2_28_aarch64.whl", hash = "sha256:ba2a27ff02f48193fc4daeadf8ad2590516fa3d0adeeb34336b96f7fa64c1e3a", size = 4276980, upload-time = "2026-02-10T19:18:02.379Z" },
+    { url = "https://files.pythonhosted.org/packages/8e/7c/c4f45e0eeff9b91e3f12dbd0e165fcf2a38847288fcfd889deea99fb7b6d/cryptography-46.0.5-cp38-abi3-manylinux_2_28_ppc64le.whl", hash = "sha256:61aa400dce22cb001a98014f647dc21cda08f7915ceb95df0c9eaf84b4b6af76", size = 4939143, upload-time = "2026-02-10T19:18:03.964Z" },
+    { url = "https://files.pythonhosted.org/packages/37/19/e1b8f964a834eddb44fa1b9a9976f4e414cbb7aa62809b6760c8803d22d1/cryptography-46.0.5-cp38-abi3-manylinux_2_28_x86_64.whl", hash = "sha256:3ce58ba46e1bc2aac4f7d9290223cead56743fa6ab94a5d53292ffaac6a91614", size = 4453674, upload-time = "2026-02-10T19:18:05.588Z" },
+    { url = "https://files.pythonhosted.org/packages/db/ed/db15d3956f65264ca204625597c410d420e26530c4e2943e05a0d2f24d51/cryptography-46.0.5-cp38-abi3-manylinux_2_31_armv7l.whl", hash = "sha256:420d0e909050490d04359e7fdb5ed7e667ca5c3c402b809ae2563d7e66a92229", size = 3978801, upload-time = "2026-02-10T19:18:07.167Z" },
+    { url = "https://files.pythonhosted.org/packages/41/e2/df40a31d82df0a70a0daf69791f91dbb70e47644c58581d654879b382d11/cryptography-46.0.5-cp38-abi3-manylinux_2_34_aarch64.whl", hash = "sha256:582f5fcd2afa31622f317f80426a027f30dc792e9c80ffee87b993200ea115f1", size = 4276755, upload-time = "2026-02-10T19:18:09.813Z" },
+    { url = "https://files.pythonhosted.org/packages/33/45/726809d1176959f4a896b86907b98ff4391a8aa29c0aaaf9450a8a10630e/cryptography-46.0.5-cp38-abi3-manylinux_2_34_ppc64le.whl", hash = "sha256:bfd56bb4b37ed4f330b82402f6f435845a5f5648edf1ad497da51a8452d5d62d", size = 4901539, upload-time = "2026-02-10T19:18:11.263Z" },
+    { url = "https://files.pythonhosted.org/packages/99/0f/a3076874e9c88ecb2ecc31382f6e7c21b428ede6f55aafa1aa272613e3cd/cryptography-46.0.5-cp38-abi3-manylinux_2_34_x86_64.whl", hash = "sha256:a3d507bb6a513ca96ba84443226af944b0f7f47dcc9a399d110cd6146481d24c", size = 4452794, upload-time = "2026-02-10T19:18:12.914Z" },
+    { url = "https://files.pythonhosted.org/packages/02/ef/ffeb542d3683d24194a38f66ca17c0a4b8bf10631feef44a7ef64e631b1a/cryptography-46.0.5-cp38-abi3-musllinux_1_2_aarch64.whl", hash = "sha256:9f16fbdf4da055efb21c22d81b89f155f02ba420558db21288b3d0035bafd5f4", size = 4404160, upload-time = "2026-02-10T19:18:14.375Z" },
+    { url = "https://files.pythonhosted.org/packages/96/93/682d2b43c1d5f1406ed048f377c0fc9fc8f7b0447a478d5c65ab3d3a66eb/cryptography-46.0.5-cp38-abi3-musllinux_1_2_x86_64.whl", hash = "sha256:ced80795227d70549a411a4ab66e8ce307899fad2220ce5ab2f296e687eacde9", size = 4667123, upload-time = "2026-02-10T19:18:15.886Z" },
+    { url = "https://files.pythonhosted.org/packages/e9/6f/6cc6cc9955caa6eaf83660b0da2b077c7fe8ff9950a3c5e45d605038d439/cryptography-46.0.5-pp311-pypy311_pp73-manylinux_2_28_aarch64.whl", hash = "sha256:bc84e875994c3b445871ea7181d424588171efec3e185dced958dad9e001950a", size = 4218321, upload-time = "2026-02-10T19:18:22.349Z" },
+    { url = "https://files.pythonhosted.org/packages/3e/5d/c4da701939eeee699566a6c1367427ab91a8b7088cc2328c09dbee940415/cryptography-46.0.5-pp311-pypy311_pp73-manylinux_2_28_x86_64.whl", hash = "sha256:2ae6971afd6246710480e3f15824ed3029a60fc16991db250034efd0b9fb4356", size = 4381786, upload-time = "2026-02-10T19:18:24.529Z" },
+    { url = "https://files.pythonhosted.org/packages/ac/97/a538654732974a94ff96c1db621fa464f455c02d4bb7d2652f4edc21d600/cryptography-46.0.5-pp311-pypy311_pp73-manylinux_2_34_aarch64.whl", hash = "sha256:d861ee9e76ace6cf36a6a89b959ec08e7bc2493ee39d07ffe5acb23ef46d27da", size = 4217990, upload-time = "2026-02-10T19:18:25.957Z" },
+    { url = "https://files.pythonhosted.org/packages/ae/11/7e500d2dd3ba891197b9efd2da5454b74336d64a7cc419aa7327ab74e5f6/cryptography-46.0.5-pp311-pypy311_pp73-manylinux_2_34_x86_64.whl", hash = "sha256:2b7a67c9cd56372f3249b39699f2ad479f6991e62ea15800973b956f4b73e257", size = 4381252, upload-time = "2026-02-10T19:18:27.496Z" },
 ]
 
 [[package]]
@@ -424,14 +438,14 @@ wheels = [
 
 [[package]]
 name = "id"
-version = "1.5.0"
+version = "1.6.1"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
-    { name = "requests" },
+    { name = "urllib3" },
 ]
-sdist = { url = "https://files.pythonhosted.org/packages/22/11/102da08f88412d875fa2f1a9a469ff7ad4c874b0ca6fed0048fe385bdb3d/id-1.5.0.tar.gz", hash = "sha256:292cb8a49eacbbdbce97244f47a97b4c62540169c976552e497fd57df0734c1d", size = 15237, upload-time = "2024-12-04T19:53:05.575Z" }
+sdist = { url = "https://files.pythonhosted.org/packages/6d/04/c2156091427636080787aac190019dc64096e56a23b7364d3c1764ee3a06/id-1.6.1.tar.gz", hash = "sha256:d0732d624fb46fd4e7bc4e5152f00214450953b9e772c182c1c22964def1a069", size = 18088, upload-time = "2026-02-04T16:19:41.26Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/9f/cb/18326d2d89ad3b0dd143da971e77afd1e6ca6674f1b1c3df4b6bec6279fc/id-1.5.0-py3-none-any.whl", hash = "sha256:f1434e1cef91f2cbb8a4ec64663d5a23b9ed43ef44c4c957d02583d61714c658", size = 13611, upload-time = "2024-12-04T19:53:03.02Z" },
+    { url = "https://files.pythonhosted.org/packages/42/77/de194443bf38daed9452139e960c632b0ef9f9a5dd9ce605fdf18ca9f1b1/id-1.6.1-py3-none-any.whl", hash = "sha256:f5ec41ed2629a508f5d0988eda142e190c9c6da971100612c4de9ad9f9b237ca", size = 14689, upload-time = "2026-02-04T16:19:40.051Z" },
 ]
 
 [[package]]
@@ -756,11 +770,11 @@ wheels = [
 
 [[package]]
 name = "platformdirs"
-version = "4.5.1"
+version = "4.6.0"
 source = { registry = "https://pypi.org/simple" }
-sdist = { url = "https://files.pythonhosted.org/packages/cf/86/0248f086a84f01b37aaec0fa567b397df1a119f73c16f6c7a9aac73ea309/platformdirs-4.5.1.tar.gz", hash = "sha256:61d5cdcc6065745cdd94f0f878977f8de9437be93de97c1c12f853c9c0cdcbda", size = 21715, upload-time = "2025-12-05T13:52:58.638Z" }
+sdist = { url = "https://files.pythonhosted.org/packages/20/e5/474d0a8508029286b905622e6929470fb84337cfa08f9d09fbb624515249/platformdirs-4.6.0.tar.gz", hash = "sha256:4a13c2db1071e5846c3b3e04e5b095c0de36b2a24be9a3bc0145ca66fce4e328", size = 23433, upload-time = "2026-02-12T14:36:21.288Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/cb/28/3bfe2fa5a7b9c46fe7e13c97bda14c895fb10fa2ebf1d0abb90e0cea7ee1/platformdirs-4.5.1-py3-none-any.whl", hash = "sha256:d03afa3963c806a9bed9d5125c8f4cb2fdaf74a55ab60e5d59b3fde758104d31", size = 18731, upload-time = "2025-12-05T13:52:56.823Z" },
+    { url = "https://files.pythonhosted.org/packages/da/10/1b0dcf51427326f70e50d98df21b18c228117a743a1fc515a42f8dc7d342/platformdirs-4.6.0-py3-none-any.whl", hash = "sha256:dd7f808d828e1764a22ebff09e60f175ee3c41876606a6132a688d809c7c9c73", size = 19549, upload-time = "2026-02-12T14:36:19.743Z" },
 ]
 
 [[package]]