docs: sync help text, README, and AI docs with recent features

Author: DropFan

README.md

@@ -93,6 +93,12 @@ grade: legacy debt never blocks a PR, only the changes do ("clean as
 you code"). The delta ("B 87.9 → C 77.2") renders in console, markdown
 (great for PR comments), and JSON.
 
+On very large codebases, `--no-dup-scan` skips line-duplication
+collection to save memory; the health score then omits the duplication
+dimension (it is not scored as clean — the remaining weights are
+renormalized), and machine-readable output reports the scoring model as
+`default-no-dup` instead of `default`.
+
 ### Hotspot Detection
 
 Find the riskiest files by combining git change frequency (churn) with code complexity — files that change often AND are complex are the most likely sources of bugs.
@@ -275,6 +281,12 @@ depth = 10
 
 # Show git info
 git_info = true
+
+# Skip line-duplication analysis (health score omits the duplication dimension)
+no_dup_scan = true
+
+# Custom language definitions (relative paths resolve against this file's directory)
+languages_file = "my-langs.toml"
 ```
 
 ## Custom Languages

crates/codelens/src/cli.rs

@@ -16,7 +16,7 @@ const STYLES: Styles = Styles::styled()
 #[command(
     name = "codelens",
     version,
-    about = "High performance code analysis tool — stats, health scores, hotspots, trends, and cost estimation\n\n\
+    about = "High performance code analysis tool — stats, health scores, hotspots, coupling, diffs, trends, and cost estimation\n\n\
         Author: Tiger <DropFan@Gmail.com>\n\
         GitHub: https://github.com/DropFan/codelens",
     styles = STYLES,
@@ -62,7 +62,8 @@ pub enum Command {
         commit. Strong coupling between files that the module structure does not connect \
         reveals hidden dependencies and refactoring targets. Requires a git repository.\n\n\
         Noise controls: --min-shared (minimum shared commits), --min-coupling (minimum \
-        coupling percentage), --max-changeset (bulk commits above this size are ignored)."
+        coupling percentage), --max-changeset (bulk commits above this size are ignored). \
+        Test files are excluded by default; --include-tests restores them."
     )]
     Coupling(CouplingArgs),
     /// Compare two git refs: health delta, complexity delta, regressions.
@@ -167,6 +168,7 @@ pub struct CouplingArgs {
     pub since: String,
 
     /// Only show files coupled to this file (repo-relative path).
+    /// Pointing at a test file implies --include-tests.
     #[arg(long = "for", value_name = "FILE")]
     pub focus: Option<PathBuf>,
 
@@ -196,7 +198,8 @@ pub struct CouplingArgs {
 
 #[derive(Args, Debug)]
 pub struct DiffArgs {
-    /// Base git ref, or "FROM..TO" combined form.
+    /// Base git ref, or "FROM..TO" combined form ("FROM...TO" compares
+    /// from the merge base).
     pub from: String,
 
     /// Target git ref (defaults to the working tree).
@@ -365,7 +368,8 @@ pub struct FilterArgs {
     #[arg(short, long)]
     pub depth: Option<usize>,
 
-    /// Count extensions as another language, e.g. "jsp:html,tpl:php".
+    /// Count extensions as another language, e.g. "jsp:html,tpl:php"
+    /// (MATLAB repos: "m:matlab", since .m defaults to Objective-C).
     #[arg(long, value_name = "EXT:LANG,...")]
     pub count_as: Option<String>,
 
@@ -399,9 +403,8 @@ pub struct FilterArgs {
 #[derive(Args, Debug)]
 pub struct OutputArgs {
     /// Output format [default: console].
-    ///
-    /// Left as `Option` so config-file values are only overridden when the
-    /// user explicitly passes the flag.
+    // Left as `Option` so config-file values are only overridden when the
+    // user explicitly passes the flag.
     #[arg(short, long, value_enum)]
     pub format: Option<OutputFormatArg>,
 
@@ -472,8 +475,9 @@ pub struct AdvancedArgs {
     #[arg(long, global = true)]
     pub no_config: bool,
 
-    /// Load custom language definitions from a TOML file, merged on top
-    /// of the built-in languages (verify with --list-languages).
+    /// Load custom language definitions from a TOML file, added on top
+    /// of the built-in languages; a definition with the same id replaces
+    /// the built-in entirely (verify with --list-languages).
     #[arg(long, global = true, value_name = "PATH")]
     pub languages_file: Option<PathBuf>,
 
@@ -562,6 +566,8 @@ const EXAMPLES: &str = "\
   \x1b[1;36mcodelens --top 20 --sort code\x1b[0m   \x1b[2m# Show top 20 by code lines\x1b[0m
   \x1b[1;36mcodelens --git-info\x1b[0m             \x1b[2m# Include git information\x1b[0m
   \x1b[1;36mcodelens --list-languages\x1b[0m       \x1b[2m# List supported languages\x1b[0m
+  \x1b[1;36mcodelens --no-dup-scan\x1b[0m          \x1b[2m# Skip duplication scan (saves memory)\x1b[0m
+  \x1b[1;36mcodelens --languages-file my.toml\x1b[0m  \x1b[2m# Custom language definitions\x1b[0m
 
 \x1b[1;32mHealth\x1b[0m \x1b[2m(code health score):\x1b[0m
   \x1b[1;36mcodelens health .\x1b[0m               \x1b[2m# Health report for current directory\x1b[0m
@@ -574,6 +580,16 @@ const EXAMPLES: &str = "\
   \x1b[1;36mcodelens hotspot . --since 6m\x1b[0m   \x1b[2m# Hotspots in last 6 months\x1b[0m
   \x1b[1;36mcodelens hotspot . --top 5\x1b[0m      \x1b[2m# Show top 5 hotspots\x1b[0m
 
+\x1b[1;32mCoupling\x1b[0m \x1b[2m(files changing together):\x1b[0m
+  \x1b[1;36mcodelens coupling .\x1b[0m             \x1b[2m# Coupled pairs, tests excluded by default\x1b[0m
+  \x1b[1;36mcodelens coupling . --include-tests\x1b[0m  \x1b[2m# Include test files\x1b[0m
+  \x1b[1;36mcodelens coupling . --for src/api.rs\x1b[0m  \x1b[2m# Files coupled to one file\x1b[0m
+
+\x1b[1;32mDiff\x1b[0m \x1b[2m(compare two git refs):\x1b[0m
+  \x1b[1;36mcodelens diff main\x1b[0m              \x1b[2m# main vs working tree\x1b[0m
+  \x1b[1;36mcodelens diff v1.0..v2.0\x1b[0m        \x1b[2m# Two refs\x1b[0m
+  \x1b[1;36mcodelens diff main --fail-on-regression\x1b[0m  \x1b[2m# Gate CI on health regressions\x1b[0m
+
 \x1b[1;32mTrend\x1b[0m \x1b[2m(snapshot comparison):\x1b[0m
   \x1b[1;36mcodelens trend --save\x1b[0m           \x1b[2m# Save a snapshot\x1b[0m
   \x1b[1;36mcodelens trend --save --label v1.0\x1b[0m  \x1b[2m# Save with label\x1b[0m

crates/codelens/src/mcp.rs

@@ -3,7 +3,10 @@
 //! `codelens mcp` speaks the Model Context Protocol so coding agents
 //! (Claude Code, Cursor, ...) can query repository statistics, health
 //! scores, hotspots, and change coupling before editing code. Tools
-//! return compact JSON strings mirroring the `-f json` CLI output.
+//! return compact JSON strings mirroring the shape of the `-f json` CLI
+//! output. Known divergence: `change_coupling` here pairs ALL files in
+//! history (no tree restriction, test files included), while the CLI
+//! default excludes test files.
 
 use std::path::PathBuf;
 
@@ -53,6 +56,7 @@ pub struct GitWindowArgs {
     #[serde(default)]
     pub path: Option<String>,
     /// Time window like "30d", "6m", "1y", or YYYY-MM-DD; defaults to "90d".
+    /// Only honored by hotspots and change_coupling; code_health ignores it.
     #[serde(default)]
     pub since: Option<String>,
     /// Maximum entries to return; defaults to 10.

docs/ai-integration.md

@@ -25,7 +25,7 @@ claude mcp add codelens -- codelens mcp
 | `repo_overview` | 仓库概览：文件/行数/语言分布/复杂度/测试占比/token 估算 |
 | `code_health` | 健康报告：项目评分（A-F）、六维度得分（含重复度）、最差目录与文件 |
 | `hotspots` | 变更热点：又复杂又频繁改动的文件（最可能出 bug），含代码年龄与作者集中度（知识孤岛标记） |
-| `change_coupling` | 变更耦合：总是一起改的文件对（改 A 通常还要改 B） |
+| `change_coupling` | 变更耦合：总是一起改的文件对（改 A 通常还要改 B）。注意：MCP 路径目前包含测试文件，与 CLI 默认（排除测试）口径不同 |
 | `file_metrics` | 单文件指标：行数、圈/认知复杂度、嵌套深度、健康分 |
 
 典型用法：代理在改一个文件前先查 `hotspots` 和 `change_coupling`，知道"这个文件风险多高、动它会牵连谁"；改完后用 `code_health` 确认没有劣化。
@@ -38,12 +38,12 @@ MCP 属于默认开启的 cargo feature；如需更小的二进制，可用 `car
 
 ```bash
 codelens . -f json                 # 仓库统计（含 token 估算、测试占比、ULOC）
-codelens health . -f json          # 健康报告（六维度）
+codelens health . -f json          # 健康报告（默认六维度；--no-dup-scan 时省略重复度维度）
 codelens health . --baseline main -f json   # 相对 main 分支的健康回归
 codelens diff main -f json                   # 改动前后健康分对比（改完代码后验证）
 codelens hotspot . -f json --top 10          # 热点文件（含知识孤岛）
 codelens hotspot . --functions -f json       # 函数级热点
-codelens coupling . -f json                  # 变更耦合
+codelens coupling . -f json                  # 变更耦合（默认排除测试文件，--include-tests 找回）
 ```
 
 可以把这段加进项目的 `CLAUDE.md` / `AGENTS.md`，代理会自己学会用：
@@ -53,7 +53,7 @@ codelens coupling . -f json                  # 变更耦合
 改动前先了解风险：
 - `codelens health <path> -f json` — 文件健康分（A-F），低分文件谨慎重构
 - `codelens hotspot . -f json` — 高频修改且复杂的文件，改动需额外小心
-- `codelens coupling . --for <file> -f json` — 改这个文件通常还要同步改什么
+- `codelens coupling . --for <file> -f json` — 改这个文件通常还要同步改什么（默认不含测试文件配对，需要含测试时加 --include-tests）
 ```
 
 ## 上下文窗口预估