docs(ux): clarify output flags and metric semantics in --help and README (closes #180)

[Wolfvin]

Closes #180

What changed

• scan --help, summary --help, trace --help now print a Notes: epilog (via RawDescriptionHelpFormatter) pointing at --format compact / --lite, and (for scan) the incremental-vs-first-scan behavior.
• README.md: new ## Interpreting Signals section (4 bullets, ~10 lines) right after Impact Risk Levels — explicit reference_count = popularity not criticality, trace --direction up to find callers, --format compact / --lite for noise reduction, first scan builds the SQLite graph.
• SKILL.md: new ## Reading the Output — Signal vs. Metric section between Status & Flag Reference and Integration with AI Agent — a 4-row table covering reference_count, status: dead, status: duplicate_ref, high_complexity, plus the same noise-reduction + incremental-scan notes.
• Worker-skills CONTEXT.md PR (separate repo): Wolfvin/worker-skills#<fill-in> adds a ## How to read CodeLens output section with the same signal-vs-metric distinction in Indonesian (matching the rest of CONTEXT.md).

Sebelum → Sesudah

• scan --help: no Notes → 4-line Notes epilog mentioning incremental + --format compact / --lite
• summary --help: no Notes → 3-line Notes epilog mentioning --format compact / --lite / --detail minimal
• trace --help: no Notes → 4-line Notes epilog mentioning direction + --format compact / --lite / pagination
• README: no Interpreting section → 4-bullet section
• SKILL.md: no Reading-the-Output section → table + notes section

How this was verified

• python3 scripts/codelens.py scan --help renders epilog with preserved line breaks
• python3 scripts/codelens.py summary --help renders epilog
• python3 scripts/codelens.py trace --help renders epilog
• pytest tests/test_cli.py::TestArgparseFormatConflictRegression — 4/4 pass (help-does-not-crash, command-count-does-not-crash, no-duplicate-f-in-subparsers, parser-construction-no-argparse-error)
• No new test failures introduced (see Findings)

Findings (pre-existing, not from this PR)

• tests/test_cli.py::test_scan_with_format_long_does_not_crash and test_scan_with_format_short_does_not_crash: hit 60s subprocess timeout scanning CodeLens itself on this environment. Not argparse-related — the assertion would have passed if the scan completed. CI on a faster runner should be fine.
• tests/test_formatters_phase2.py::test_help_lists_new_formats: pre-existing failure (verified by stashing this PR and rerunning on main). The test runs secrets --format text --help but text is not in the global --format argparse choices — looks like a stale test or a separate bug, out of scope here.
• tests/test_codelensignore.py::TestBackwardCompat::test_actual_target_dir_is_ignored: pre-existing on main.
• tests/test_confidence.py::TestFormatterIntegration::test_json_format_has_schema_version and 2 siblings: pre-existing on main (KeyError: schema_version).
• tests/test_adr.py::TestMcpToolRegistration::* (4 tests): pre-existing on main.
• tests/test_universal_grammar_loader.py::TestLoadGrammar::* (2 tests): pre-existing on main, network/install-related.
• Collection errors on test_lsp_server.py, test_rule_engine.py, test_rule_matcher.py: missing optional deps (lsprotocol, tree_sitter) on this box — environmental.

KISS: stuck to DoD exactly — scan/summary/trace help + README section + CONTEXT.md. Did not touch --format choices, the dispatcher, or other commands help text. CONTEXT.md update lives in a separate worker-skills PR (different repo).

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud