CodeClone Docs

This site is built with MkDocs and published to orenlab.github.io/codeclone.

!!! note "Version Notice" This site currently documents the in-development v2.0.x line from main. For the latest stable CodeClone documentation (v1.4.4), see the v1.4.4 README and the v1.4.4 docs tree.

!!! note "Repository licensing" CodeClone source code is licensed under MPL-2.0. Documentation content under docs/ and the published docs site is licensed under MIT.

It has two documentation layers:

• Contracts 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.
• Architecture Narrative, CFG Semantics: deep-dive narrative docs (architecture and CFG semantics). These may include rationale and design intent, but must not contradict the contract book.

The published site also exposes a live sample report generated from the current repository build:

• Examples / Sample Report

Start Here

• Contracts and guarantees
• Architecture map (components + ownership)
• Terminology

Core Contracts

• Exit codes and failure policy
• Config and defaults
• Core pipeline and invariants
• Baseline contract (schema v2.1)
• Cache contract (schema v2.6)
• Report contract (schema v2.10)

Interfaces

• CLI behavior, modes, and UX
• MCP interface contract
• VS Code extension contract
• Claude Desktop bundle contract
• Codex plugin contract
• HTML report rendering contract

The VS Code extension docs cover the native IDE surface for canonical review facts, including optional Coverage Join overview data and version-gated MCP help topics when the connected server exposes them.

System Properties

• Security model and threat boundaries
• Determinism policy
• Tests as specification
• Compatibility and versioning rules

Quality Contracts

• Health Score model and evolution policy
• Metrics mode and quality gates
• Dead-code contract and test-boundary policy
• Suggestions and clone typing contract
• Reproducible Docker benchmarking
• Inline suppressions contract

Deep Dives

• Architecture narrative
• CFG design and semantics
• MCP integration for AI agents and clients
• VS Code extension usage guide
• Claude Desktop bundle usage guide
• Codex plugin usage guide
• Privacy Policy
• Terms of Use
• SARIF integration for IDE/code-scanning use
• Docs publishing and Pages workflow

Reference Appendices

• Status enums and typed contracts
• Schema layouts (baseline/cache/report)
• Error catalog (contract vs internal)

Local Preview

=== "Build the site"

```bash title="Validate the docs site"
uv run --with mkdocs --with mkdocs-material mkdocs build --strict
```

=== "Build the site and sample report"

```bash title="Generate the live sample report into the built site"
uv run --with mkdocs --with mkdocs-material mkdocs build --strict
uv run python scripts/build_docs_example_report.py --output-dir site/examples/report/live
```

!!! note "Generated output" site/ is generated output. It is used for local preview and GitHub Pages publishing, but it is not committed to git.

GitHub Pages publishing is handled by docs.yml via a custom Actions workflow.