CodeClone Docs

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

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.

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.5)
• Report contract (schema v2.8)

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 docs site with MkDocs, then generate the 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

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