chore(docs): update docs

Author: orenlab

CHANGELOG.md

@@ -6,8 +6,8 @@
 
 This release improves clone-detection precision and explainability with deterministic
 normalization and CFG upgrades, adds segment-level internal clone reporting, refreshes
-the HTML report UI, and introduces baseline versioning. This is a breaking change for CI
-workflows that rely on existing baselines.
+the HTML report UI, and introduces baseline versioning. It is a breaking CI change for
+workflows that reuse old baselines.
 
 ### Clone Detection Accuracy
 
@@ -26,7 +26,7 @@ workflows that rely on existing baselines.
 
 - **Exception linking**  
   Linked `try/except` only to statements that may raise (calls, attribute access, indexing,
-  `await`, `yield from`, `raise`) instead of blanket connections.
+  `await`, `yield from`, `raise`) instead of blanket links.
 
 ### Segment‑Level Detection
 
@@ -35,10 +35,10 @@ workflows that rely on existing baselines.
 
 - **Candidate generation**  
   Used an order‑insensitive signature for candidate grouping and a strict segment hash for
-  final confirmation; segment matches do not affect baseline or CI failure logic.
+  final confirmation. Segment matches do not affect baseline or CI failure logic.
 - **Noise reduction (report‑only)**  
   Merged overlapping segment windows into a single span per function and suppressed
-  boilerplate‑only groups (attribute assignment wiring) using deterministic AST criteria.
+  boilerplate-only groups (attribute assignment wiring) with deterministic AST criteria.
 
 ### Baseline & CI
 
@@ -59,25 +59,23 @@ codeclone . --update-baseline
 - Added `--cache-path` (legacy alias: `--cache-dir`) and clarified cache help text.
 - Added `--ci` preset (`--fail-on-new --no-color --quiet`).
 - Improved `--fail-on-new` output with aggregated counts and clear next steps.
-- Validate report output extensions (`.html`, `.json`, `.txt`) and fail fast on mismatches.
+- Added strict report output extension validation (`.html`, `.json`, `.txt`).
 
 ### HTML Report UI
 
 - **Visual refresh**  
-  Introduced a redesigned, modern HTML report layout with a sticky top bar and improved
-  typography and spacing.
+  Introduced a modernized HTML report layout with a sticky top bar and improved spacing.
 
 - **Interactive tooling**  
-  Added a command palette, keyboard shortcuts, toast notifications, and quick actions for
-  common tasks (export, stats, charts, navigation).
+  Added a command palette, keyboard shortcuts, toast notifications, and quick actions
+  (export, stats, charts, navigation).
 
 - **Reporting widgets**  
-  Added a stats dashboard and chart container to surface high‑level clone metrics directly
-  in the report.
+  Added a stats dashboard and chart container for high-level clone metrics.
 
 - **Icon system**  
   Replaced emoji glyphs with inline SVG icons for consistent rendering and a fully
-  self‑contained UI.
+  self-contained UI.
 
 - **Segment reporting**  
   Added a dedicated “Segment clones” section and summary metric in HTML/TXT/JSON outputs.

README.md

@@ -278,6 +278,30 @@ See full design and semantics:
 
 ---
 
+## 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`                                  | -                                    |
+| `--baseline FILE`             | Baseline file path                                               | `codeclone.baseline.json`            |
+| `--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

docs/architecture.md

@@ -23,7 +23,8 @@ CodeClone processes Python projects in the following stages:
 
 - Recursively scans `.py` files.
 - Applies cache-based skipping using file stat signatures.
-- Default cache location is project‑local: `<root>/.cache/codeclone/cache.json` (override via `--cache-dir`).
+- Default cache location is project-local: `<root>/.cache/codeclone/cache.json`
+  (override via `--cache-path`, legacy alias: `--cache-dir`).
 
 ---