When to use: a quick health check of a file before or after editing it.
Limitations: one file at a time; some smells need a tree-sitter adapter
(Python, JS, TS/TSX, Java, Go) or PMD, see the analyzers field.
Returns: {path, language, score 1-10, category, optimal, analyzers}.

When to use: to decide what to refactor, or to check that an edit did not
add smells. Fix the findings with the highest severity first.
Limitations: static analysis of a single file; duplication within the
file only (needs PMD). analyzers lists which analyzers ran and which
smells were unavailable for this language.
Returns: {score, category, findings:[{smell, level, function,
start_line, end_line (null for whole-file findings), value, threshold,
severity, message, hint, details}],
pmd_violations?, analyzers:{lizard, tree_sitter, pmd, unavailable_smells}}.

When to use: before every commit made by an agent.
Limitations: tracked files only (untracked files are skipped); compares
the working tree with HEAD using HEAD's root rules file for both sides.
Returns: {quality_gate: passed|failed, counts, rules_changed?,
files:[{path, verdict (improved|degraded|stable|removed|unknown),
old_score, new_score, new_findings, worsened, improved, fixed}],
cross_file_duplication?: CPD copies and renamed clones between changed files (informational),
analyzers?}.

When to use: before opening or merging a pull request.
Limitations: compares committed HEAD content only; uncommitted edits are
ignored. The merge base's root rules file is used for both sides.
Returns: {quality_gate, merge_base, counts, rules_changed?, files:[{path, verdict, ...}],
cross_file_duplication?, analyzers?}.

When to use: after editing .codehealth/rules.json.
Limitations: checks structure, rule names and threshold names only.
Returns: {rules_file, valid, errors}.

When to use: before overriding a threshold, to see names and defaults.
Limitations: shows defaults, not a repository's overrides.
Languages without their own template fall back to the baseline values
(template: false).
Returns: {language, template, thresholds:[{name, value, operator, published, description}], rules:[names]}.

When to use: to silence or soften a smell for part of a repository.
Limitations: writes the rules file in the repository root; the first
matching rule set wins, so a new specific glob is placed first.
Returns: {rules_file, rule, weight, matching_content_path}.

When to use: when a team agrees on a different limit, e.g. longer functions in tests.
Limitations: names must come from rules_config_list_thresholds.
Returns: {rules_file, threshold, value, matching_content_path}.

When to use: to understand a finding or how the score is computed.
Limitations: static documentation; pass a smell name or 'score' as topic.
Returns: {topic, text}.