chore(docs, licence): documentation has been updated and the recognition of codeclone license types for GitHub (dual-license model) has been improved. This change does not change the licensing model, but is of a technical nature.

Author: orenlab

LICENSE-MIT

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Denis Rozhnovskiy
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

LICENSE-docs

@@ -0,0 +1,22 @@
+# License Scope
+
+CodeClone uses a dual-license layout in this repository.
+
+## Default mapping
+
+- Source code and other implementation files are licensed under
+  [MPL-2.0](LICENSE).
+- Documentation content, including the `docs/` tree and published docs-site
+  content, is licensed under [MIT](LICENSE-MIT).
+
+## File-level overrides
+
+If a file or bundled third-party artifact includes its own license notice, that
+file-level notice takes precedence over this default mapping.
+
+## Notes
+
+- Keep [LICENSE](LICENSE) and [LICENSE-MIT](LICENSE-MIT) as canonical license
+  texts for tooling and GitHub license detection.
+- Use this file to describe scope, not to redefine the underlying license
+  texts.

LICENSES.md

@@ -283,11 +283,11 @@ Report contract: [Report contract](https://orenlab.github.io/codeclone/book/08-r
 [HTML render](https://orenlab.github.io/codeclone/book/10-html-render/)
 
 <details>
-<summary>Canonical JSON report shape (v2.8)</summary>
+<summary>Canonical JSON report shape (v2.9)</summary>
 
 ```json
 {
-  "report_schema_version": "2.8",
+  "report_schema_version": "2.9",
   "meta": {
     "codeclone_version": "2.0.0b6",
     "project_name": "...",
@@ -356,15 +356,27 @@ Report contract: [Report contract](https://orenlab.github.io/codeclone/book/08-r
   "metrics": {
     "summary": {
       "...": "...",
-      "coverage_adoption": { "...": "..." },
-      "coverage_join": { "...": "..." },
-      "api_surface": { "...": "..." }
+      "coverage_adoption": {
+        "...": "..."
+      },
+      "coverage_join": {
+        "...": "..."
+      },
+      "api_surface": {
+        "...": "..."
+      }
     },
     "families": {
       "...": "...",
-      "coverage_adoption": { "...": "..." },
-      "coverage_join": { "...": "..." },
-      "api_surface": { "...": "..." }
+      "coverage_adoption": {
+        "...": "..."
+      },
+      "coverage_join": {
+        "...": "..."
+      },
+      "api_surface": {
+        "...": "..."
+      }
     }
   },
   "derived": {
@@ -470,8 +482,8 @@ in [Benchmarking contract](https://orenlab.github.io/codeclone/book/18-benchmark
 
 ## License
 
-- **Code:** MPL-2.0
-- **Documentation:** MIT
+- **Code:** MPL-2.0 (`LICENSE`)
+- **Documentation and docs-site content:** MIT (`LICENSE-MIT`)
 
 Versions released before this change remain under their original license terms.
 
@@ -480,4 +492,4 @@ Versions released before this change remain under their original license terms.
 - **Docs:** <https://orenlab.github.io/codeclone/>
 - **Issues:** <https://github.com/orenlab/codeclone/issues>
 - **PyPI:** <https://pypi.org/project/codeclone/>
-- **Licenses:** [MPL-2.0](LICENSE) · [MIT docs](LICENSE-docs)
+- **Licenses:** [MPL-2.0](LICENSE) · [MIT docs](LICENSE-MIT) · [Scope map](LICENSES.md)

README.md

@@ -4,11 +4,15 @@ This site is built with MkDocs and published to
 [orenlab.github.io/codeclone](https://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](https://github.com/orenlab/codeclone/blob/v1.4.4/README.md)
-and the
-[`v1.4.4` docs tree](https://github.com/orenlab/codeclone/tree/v1.4.4/docs).
+    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](https://github.com/orenlab/codeclone/blob/v1.4.4/README.md)
+    and the
+    [`v1.4.4` docs tree](https://github.com/orenlab/codeclone/tree/v1.4.4/docs).
+
+!!! 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:
 
@@ -91,13 +95,22 @@ help topics when the connected server exposes them.
 
 ## Local Preview
 
-Build the docs site with MkDocs, then generate the sample report into the built
-site:
+=== "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
+    ```
 
-```bash
-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`](https://github.com/orenlab/codeclone/blob/main/.github/workflows/docs.yml)

docs/README.md

@@ -53,7 +53,7 @@ Fragment-level admission thresholds (pyproject.toml only, advanced tuning):
 
 Example project-level config:
 
-```toml
+```toml title="Minimal [tool.codeclone] configuration"
 [tool.codeclone]
 min_loc = 10
 min_stmt = 6
@@ -138,14 +138,17 @@ This is the exact accepted `[tool.codeclone]` key set from
 `codeclone/config/spec.py` and `codeclone/config/pyproject_loader.py`; unknown
 keys are contract errors.
 
-Important:
-
-- The tables above list `pyproject.toml` keys, not CLI flag spellings.
-- CLI flags may map to the same internal destination under a different name.
-  Example: `coverage_xml` in `pyproject.toml` corresponds to CLI
-  `--coverage FILE`.
-- The same pattern applies to report outputs such as `html_out` ↔ `--html` and
-  `json_out` ↔ `--json`.
+!!! note "Pyproject keys vs CLI flags"
+    The tables above list `[tool.codeclone]` keys, not CLI flag spellings.
+    CLI flags may map to the same internal destination under a different name.
+    Example: `coverage_xml` in `pyproject.toml` corresponds to CLI
+    `--coverage FILE`. The same pattern applies to report outputs such as
+    `html_out` ↔ `--html` and `json_out` ↔ `--json`.
+
+!!! warning "Metrics-mode conflicts are enforced"
+    Metrics update/gating flags are runtime contracts, not hints. Combinations
+    such as `skip_metrics=true` together with metrics gating or metrics
+    baseline update flags are contract errors.
 
 Notes:
 

docs/book/04-config-and-defaults.md

@@ -5,6 +5,11 @@
 Define observable CLI behavior: argument handling, summaries, output writing,
 and exit routing.
 
+!!! note "Observable surface only"
+    This chapter covers scripting-visible behavior and user-facing CLI output
+    categories. Rich styling details may evolve as long as markers, exit
+    semantics, and deterministic output contracts stay stable.
+
 ## Public surface
 
 - Public entrypoint: `codeclone/main.py:main`
@@ -83,6 +88,11 @@ Refs:
 
 ## Failure modes
 
+!!! warning "Failure precedence"
+    Contract failures take precedence over gating failures. In CI and scripted
+    flows, invalid config or unreadable sources must surface as exit `2` before
+    any clone or metrics gate can fail with exit `3`.
+
 | Condition                                                         | User-facing category | Exit |
 |-------------------------------------------------------------------|----------------------|------|
 | Invalid CLI flag                                                  | contract             | `2`  |