ucn 3.8.25 → 4.0.0

package/.claude/skills/ucn/SKILL.md

@@ -57,8 +57,11 @@ Walks UP the caller chain recursively. Shows the full tree of functions affected
 ucn blast helper                     # callers of callers (depth 3)
 ucn blast helper --depth=5           # deeper chain
 ucn blast helper --exclude=test      # skip test callers
+ucn blast helper --expand-unverified # follow unverified edges too (marked ⚠, possible impact)
 ```
 
+The tree trunk is confirmed-evidence-only; dispatch-possible/ambiguous caller candidates appear in an `UNVERIFIED EDGES` section (see "Reading Tiered Output" below).
+
 ### 4. `trace` — Understand execution flow (downward)
 
 Draws the call tree downward from any function. Compact by default; setting `--depth=N` shows the full tree to that depth with all children expanded.
@@ -71,6 +74,8 @@ ucn trace generate_report --all      # all children at default depth
 
 Shows the entire pipeline — what `generate_report` calls, what those functions call, etc. — as an indented tree. No file reading needed. Invaluable for understanding orchestrator functions or entry points.
 
+**Prefer `trace` over chained `about` calls.** If you find yourself running `ucn about` 4–5 times in a row to follow a call chain (entry → leaves), one `ucn trace <fn> --depth=N` returns the same information in a single call. Use `--depth=N` to limit how deep the tree goes.
+
 ### 5. `fn` / `class` — Extract without reading the whole file
 
 Pull one or more functions out of a large file. Supports comma-separated names for bulk extraction.
@@ -83,12 +88,13 @@ ucn class MarketDataFetcher
 
 ### 6. `deadcode` — Find unused code
 
-Lists all functions and classes with zero callers across the project. Framework entry points (Express routes, Spring controllers, Celery tasks, etc.) are automatically excluded.
+Lists all functions and classes with zero callers across the project. Framework entry points (Express routes, Spring controllers, Celery tasks, etc.) and exported/public API symbols — including methods of exported classes in JS/TS/Python — are automatically excluded (`--include-exported` audits them). Interface/trait method declarations are labeled `[declared on interface X — contract surface, not executable code]`: unreferenced is true, but deleting one changes the API contract, not dead logic.
 
 ```bash
 ucn deadcode                        # Everything
 ucn deadcode --exclude=test         # Skip test files (most useful)
 ucn deadcode --include-decorated    # Include framework-registered functions
+ucn deadcode --include-exported     # Audit exported/public API symbols too
 ```
 
 ### 7. `brief` — One-screen "before-I-touch-this" summary
@@ -161,7 +167,7 @@ ucn entrypoints --exclude-tests          # Hide test fixtures (JUnit @Test, pyte
 | Project complexity stats | `ucn stats` | File counts, symbol counts, lines by language. `--functions` for per-function line counts. `--hot --top=N` for the most-called functions (orientation primitive on a new repo) |
 | Find by glob pattern | `ucn find "handle*"` | Locate definitions matching a glob (supports * and ?) |
 | Text search with context | `ucn search term --context=3` | Like grep -C 3, shows surrounding lines |
-| Regex search (default) | `ucn search '\d+'` | Search supports regex by default (alternation, character classes, etc.) |
+| Regex search (default) | `ucn search '\d+'` | JavaScript regex (V8 engine). See "Regex notes" below for syntax — alternation is `a|b`, not grep-style |
 | Text search filtered | `ucn search term --exclude=test` | Search only in matching files |
 | Structural search (index) | `ucn search --type=function --param=Request` | Query the symbol table, not text. Finds functions by param, return type, decorator, etc. |
 | Find all db.* calls | `ucn search --type=call --receiver=db` | Search call sites by receiver — something grep can't do |
@@ -187,6 +193,16 @@ ucn entrypoints --exclude-tests          # Hide test fixtures (JUnit @Test, pyte
 | Pre-commit summary | `ucn check [--base=main]` | Changed funcs + signature drift + affected tests in one shot |
 | Find missing-await bugs | `ucn audit-async` | Lists async calls inside async functions that lack `await`. JS/TS/Python only. Filter with `--file`, `--exclude`, `--limit` |
 
+## Regex Notes (`search` command)
+
+`search` uses **JavaScript regex** (the V8 engine), not grep BRE/ERE. Common gotchas:
+
+- Alternation is `a|b`, **not** `a\|b`. `ucn search "flask|fastapi|django"` works; `ucn search "flask\|fastapi\|django"` matches the literal string.
+- `(`, `[`, `{` outside character classes do **not** need escaping for literal match in most cases — but normal JS regex semantics apply (you can still escape them for clarity).
+- Wrap the pattern in single quotes so the shell does not interpret special characters (`*`, `?`, `\`, `$`, etc.).
+- Default is case-insensitive; pass `--case-sensitive` to flip.
+- `--no-regex` forces literal-string search if you need to match regex metacharacters as text without escaping.
+
 ## Reading Call-Site Patterns
 
 `verify`, `impact`, and `about` annotate call sites with structural classification flags. Watch for these in summary lines (`Patterns: 4 in try, 4 in callback`) and per-call-site entries:
@@ -201,23 +217,32 @@ ucn entrypoints --exclude-tests          # Hide test fixtures (JUnit @Test, pyte
 
 `audit-async` is the focused tool for the `awaited=false` case across an entire async function body.
 
-## Confidence Scores
+## Reading Tiered Output (about / context / impact / trace / blast / reverse-trace / affected-tests)
+
+Caller answers are a **partition of every text occurrence** of the symbol — nothing is silently hidden. Sections:
+
+- `CALLERS — CONFIRMED (N, X prod + Y test):` — edges with binding/receiver/import evidence. Prod callers listed first, then a `test callers:` subheader. An `evidence:` line aggregates resolution labels for the section.
+- `CALLERS — UNVERIFIED (N) — call syntax, no binding/receiver evidence:` — name-matched call sites the engine could not verify, one line each with the reason (`method-no-evidence`, `ambiguous-binding`, `call-not-resolved`). Capped at 10; `--all` lifts the cap. **Treat these as possible callers when refactoring.**
+- `NON-CALL OCCURRENCES: N (...)` — imports/definitions/references/other-text, counts only (drill in with `ucn usages <name>`).
+- `ACCOUNT:` — the reconciliation line. Every ground line is in exactly one bucket; `0 unaccounted` means the partition is complete. `+N beyond-text callers` are alias-resolved call sites plain text search would miss.
+- `WARNING: N unparsed file(s) ...` — files containing the symbol that failed to parse. Their lines were NOT analyzed — fall back to text search for those files.
+- `FILTERED: N hidden by flags` — entries your display flags hid (they still count in ACCOUNT).
+
+**Trust rules:** a CONFIRMED(0) + UNVERIFIED(0) answer with `0 unaccounted` and no WARNING means the symbol genuinely has no callers — safe to act on, same as a clean grep. Any UNVERIFIED entries or WARNINGs mean: verify those sites before a breaking change.
+
+Resolution labels in `evidence:` lines (high to low): `exact-binding` (0.98, import/binding evidence) · `same-class` (0.92) · `receiver-hint` (0.80, inferred receiver type) · `scope-match` (0.65, import/receiver-binding scope evidence) · `name-only` (0.40) · `uncertain` (0.25). Confirmed tier = scope-match and above. JSON output keeps per-edge decimals plus `tier`.
+
+Flags: `--min-confidence=0.7` filters confirmed edges (hidden count appears in FILTERED). `--include-uncertain` is an **implied no-op** for about/context/impact/trace/blast/reverse-trace/affected-tests (everything is shown, tiered); it keeps its meaning for `smart`/`verify`. `--include-methods` is an implied no-op for about/context/impact.
+
+### Tree commands (trace / blast / reverse-trace / affected-tests)
 
-`about` and `context` show confidence per caller/callee edge by default (e.g. `confidence: 0.65 (scope-match)`). Resolution labels (high to low):
+The tree trunk holds **confirmed edges only**. Unverified caller candidates render in an `UNVERIFIED EDGES` section with parent attribution (`at <node> (hop N): file:line [enclosing fn] (reason)`) and are **not expanded by default** — pass `--expand-unverified` to follow them; every downstream node is then marked `[⚠ via <reason>]` / `[⚠ unverified chain]` and counted as *possibly affected*, never confirmed. Unresolved callee calls (`trace` down) render as `[unverified] name — reason` leaves under their node. Reconciliation lines:
 
-| Label | Score | Meaning |
-|-------|-------|---------|
-| `exact-binding` | 0.98 | Import or binding evidence — direct call |
-| `same-class` | 0.92 | Method call resolved within the enclosing class |
-| `receiver-hint` | 0.80 | Receiver type inferred (Go/Java/Rust) — e.g. `f.run()` where `f: Filter` |
-| `scope-match` | 0.65 | Symbol resolved by name within a file/package scope |
-| `name-only` | 0.40 | Name match only, no binding/scope evidence — review before trusting |
-| `uncertain` | 0.25 | Ambiguous — multiple candidates, hidden unless `--include-uncertain` |
+- `ACCOUNT:` — the root hop's text-ground partition (same as context/impact).
+- `TREE ACCOUNT:` — interior conservation: nodes expanded, confirmed/unverified/excluded edge counts by reason, depth-limit cuts.
+- `CALLEE ACCOUNT:` (trace down) — every call site in every expanded node lands in confirmed/unverified/external/excluded/filtered.
 
-Filter or hide:
-- `--min-confidence=0.7` — keep only high-confidence edges (≥ same-class)
-- `--hide-confidence` — silence the scores (legacy `--no-confidence` is a silent alias)
-- `--include-uncertain` — include otherwise-filtered low-confidence matches
+`reverse-trace` marks `★ entry point` only when a node has **zero candidates in both tiers**; zero confirmed with unverified candidates shows `⚠ no confirmed callers — N unverified` instead. `affected-tests` splits its answer into the confirmed band (`Test files to run`, coverage, `Uncovered`) and a `POSSIBLY AFFECTED` band (functions + test files reachable only through unverified chains).
 
 ## Symbol Handles (stable IDs)
 
@@ -253,9 +278,10 @@ ucn [target] <command> [name] [--flags]
 | `--in=src/core` | Limit search to a subdirectory |
 | `--depth=N` | Control tree depth for `trace`, `graph`, and detail level for `find` (default 3). Also expands all children — no breadth limit |
 | `--all` | Expand truncated sections. Applies to `about`, `blast`, `trace`, `reverse-trace`, `related`, `find`, `toc`, `fn`, `class`, `graph`, `diff-impact` |
+| `--expand-unverified` | `blast`/`reverse-trace`: follow unverified caller edges in the tree. Downstream nodes are marked as unverified chains — possible, not confirmed, impact |
 | `--include-tests` | Include test files in usage counts (`about`) and results (`find`, `usages`, `deadcode`). Callers always include tests. |
 | `--exclude-tests` | Exclude test entries from `entrypoints` (tests are included by default since they ARE entry points). |
-| `--include-methods` | Include `obj.method()` calls in caller/callee analysis. `impact` defaults to true (show all callable sites); other commands default to false (use `--no-include-methods` to opt out). Applies to `about`, `context`, `impact`, `verify`, `blast`, `smart`, `trace`, `reverse-trace`, `affected-tests` |
+| `--include-methods` | Include `obj.method()` calls in caller/callee analysis. Implied (no-op) for `about`/`context`/`impact` — method calls are always analyzed and tiered by receiver evidence. Applies to `verify`, `blast`, `smart`, `trace`, `reverse-trace`, `affected-tests` |
 | `--base=<ref>` | Git ref for diff-impact (default: HEAD) |
 | `--staged` | Analyze staged changes (diff-impact) |
 | `--no-cache` | Force re-index after editing files |
@@ -277,7 +303,7 @@ ucn [target] <command> [name] [--flags]
 | `--max-lines=N` | Max source lines for `class` (large classes show summary by default) |
 | `--case-sensitive` | Case-sensitive text search (default: case-insensitive) |
 | `--exact` | Exact name match only in `find`/`typedef` (no substring) |
-| `--include-uncertain` | Include ambiguous/uncertain matches. Applies to `about`, `context`, `blast`, `smart`, `trace`, `reverse-trace`, `affected-tests` |
+| `--include-uncertain` | Include ambiguous/uncertain matches. Implied (no-op) for `about`/`context`/`impact` — unverified callers are always shown in their own tier. Applies to `blast`, `smart`, `trace`, `reverse-trace`, `affected-tests` |
 | `--hide-confidence` | Hide confidence scores (shown by default) in `context`/`about` |
 | `--min-confidence=N` | Filter edges below confidence threshold (e.g., `--min-confidence=0.7` keeps only high-confidence edges) |
 | `--calls-only` | Only show call/test-case matches in `tests` (skip file-level results) |

package/README.md

@@ -34,6 +34,8 @@ UCN is deliberately lightweight:
 - **No language servers** - tree-sitter does the parsing, no compilation needed
 - **MCP is optional** - only needed if you connect UCN to an AI agent, the CLI and Skill work on their own
 
+And it's built to be **trusted**: every "who calls this?" splits into what UCN can prove and what it can't — each flagged with a reason, nothing silently dropped, [measured in CI against real compilers and language servers](#answers-you-can-trust).
+
 ---
 
 ```bash
@@ -59,16 +61,20 @@ build
 │   └── compareNames (core/discovery.js:170) 1x
 ├── parallelBuild (core/parallel-build.js:25) 1x
 ├── indexFile (core/project.js:310) 1x
-│   ├── addSymbol (core/project.js:398) 4x
-│   ├── detectLanguage (languages/index.js:209) 1x
+│   ├── addSymbol (core/project.js:410) 4x
+│   ├── detectLanguage (languages/index.js:288) 1x
 │   ├── parse (core/parser.js:69) 1x
 │   ├── extractImports (core/imports.js:19) 1x
 │   └── extractExports (core/imports.js:44) 1x
-├── buildImportGraph (core/project.js:631) 1x
-└── buildInheritanceGraph (core/project.js:636) 1x
+├── buildImportGraph (core/project.js:648) 1x
+└── buildInheritanceGraph (core/project.js:653) 1x
+    … calls UCN can't prove a receiver for (arr.push(), obj.get()) show as
+      [unverified] leaves — abridged here
+
+CALLEE ACCOUNT: 23 nodes · 329 call sites = 43 confirmed + 151 unverified + 34 builtin + 101 excluded
 ```
 
-One command. No files opened. Every function located by file and line.
+One command, no files opened — and the `CALLEE ACCOUNT:` line proves all 329 calls were sorted, nothing dropped.
 
 ---
 
@@ -84,25 +90,81 @@ expandGlob (function)
 core/discovery.js:191-222  →  core/discovery.js:191:expandGlob
 expandGlob (pattern: string, options: number = {}) : string[]
 
-CALLERS (7):
-  confidence: 0 high (>0.8), 7 medium (0.5-0.8), 0 low (<0.5)
-  cli/index.js:1190 [runGlobCommand]
+USAGES: 6 total
+  3 calls, 3 imports, 0 references
+
+CALLERS — CONFIRMED (7, 3 prod + 4 test):
+  evidence: scope-match (all)
+  cli/index.js:1201 [runGlobCommand]
     const files = expandGlob(pattern);
-    confidence: 0.65 (scope-match)
-  core/cache.js:417 [isCacheStale]
+  core/cache.js:466 [isCacheStale]
     const currentFiles = expandGlob(pattern, globOpts);
-    confidence: 0.65 (scope-match)
-  ... (5 more)
+  core/project.js:192 [build]
+    files = expandGlob(pattern, globOpts);
+  test callers:
+  test/integration.test.js:167
+    const files = expandGlob('**/*.go', { root: tmpDir });
+  ... (3 more test callers)
 
 CALLEES (3):
-  parseGlobPattern [utility] - core/discovery.js:227
-  walkDir [utility] {fs} - core/discovery.js:284
-  compareNames [utility] - core/discovery.js:170
+  evidence: exact-binding (all)
+  parseGlobPattern [utility] - core/discovery.js:227 (1x)
+  walkDir [utility] {fs} - core/discovery.js:284 (1x)
+  compareNames [utility] - core/discovery.js:170 (1x)
+
+ACCOUNT: "expandGlob" occurs on 14 lines in 6 files: 7 confirmed, 0 unverified,
+  7 non-call (4 import, 1 definition, 1 reference, 1 other-text), 0 other-target, 0 unaccounted
 
 TESTS: 5 matches in 1 file(s)
 ```
 
-Each caller comes with a confidence score (`exact-binding`, `same-class`, `receiver-hint`, `scope-match`, `name-only`) so you can tell direct calls from name-only matches. Add `--hide-confidence` to silence the scores, or `--min-confidence=0.7` to drop everything below `same-class`. Add `--git` to see who last touched the function. Need to trace execution upward instead? `ucn reverse-trace fn` walks the caller chain back to entry points.
+Callers split into **CONFIRMED** (binding/receiver/import evidence — prod first, then tests) and **UNVERIFIED** (found but unproven, each with a reason). The `ACCOUNT:` line reconciles every occurrence; `0 unaccounted` means nothing was hidden. Tune with `--min-confidence` / `--hide-confidence` / `--git`; walk callers *upward* with `ucn reverse-trace fn`.
+
+## Answers you can trust
+
+UCN doesn't just find a name — it tells you how sure it is. Every answer from `about`, `context`, and `impact` partitions *every* place the name appears into buckets you can act on:
+
+```
+$ ucn impact saveCache
+
+CALL SITES: 2 confirmed + 9 unverified
+
+test/regression-go.test.js (2 calls)
+  :2004
+    saveCache(index, cachePath);
+
+UNVERIFIED CALL SITES (9) — call syntax, no binding/receiver evidence:
+  mcp/server.js:779: index.saveCache(); (method-ambiguous)
+  test/cache.test.js:1779: index.saveCache(); (method-ambiguous)
+  ... (7 more)
+
+ACCOUNT: "saveCache" occurs on 47 lines in 8 files: 2 confirmed, 9 unverified,
+  9 non-call (2 import, 1 definition, 0 reference, 6 other-text), 27 other-target, 0 unaccounted
+```
+
+UCN sorts every one of the 47 places the name appears:
+
+- **2 confirmed** — call sites it can prove resolve to *this* `saveCache`.
+- **9 unverified** — real call sites it found but won't claim. `index.saveCache()` has an untyped receiver, so UCN can't prove which `saveCache` runs; it shows the site and the reason (`method-ambiguous`) instead of guessing.
+- **27 other-target** — occurrences that belong to a *different* `saveCache`, kept separate so they never pollute the answer.
+- **9 non-call** — imports, the definition, plain text.
+- **`0 unaccounted`** — the partition is complete. Nothing was dropped on the floor.
+
+The payoff: a **confirmed** answer is safe to refactor against, and an empty result with `0 unaccounted` means the symbol truly has no callers. UCN never hides a caller — and never invents one.
+
+### Measured against ground truth
+
+This isn't a promise — it's a gate. CI re-derives UCN's caller answers from real compilers and language servers and fails the build if a single true call edge is neither shown nor accounted for:
+
+| Language | Oracle | Confirmed-tier precision |
+|---|---|---|
+| TypeScript / JavaScript | ts-morph | 99.4–100% |
+| Python | pyright (LSP) | 97.7–99.9% |
+| Go | gopls | 99.9–100% |
+| Rust | rust-analyzer | 98.9–100% |
+| Java | jdtls | 96.2% |
+
+Ten pinned real-world repos (zod, express, httpx, rich, cobra, grpc-go, ripgrep, cursive, gson, preact-signals), three sampling seeds, every run gated at `missing-unexplained = 0`. The tree commands — `trace`, `blast`, `reverse-trace`, `affected-tests` — follow the same rule: confirmed trunk, uncertain branches flagged (`--expand-unverified` to follow). Run `ucn doctor` for the trust report on *your* repo.
 
 ## Change code without breaking things
 
@@ -217,33 +279,36 @@ affected-tests: expandGlob
 core/discovery.js:191
 1 function changed → 15 functions affected (depth 3)
 
-Test files to run (19):
+Test files to run (20):
 
   test/integration.test.js (covers: expandGlob, build, idx, setupProject)
     L47: index.build(null, { quiet: true });  [call]
     L167: const files = expandGlob('**/*.go', { root: tmpDir });  [call]
     ...
 
-Uncovered (10): runGlobCommand, main, runProjectCommand, ...
+POSSIBLY AFFECTED (1) — reachable only through unverified call edges:
+  doctor
+
+Uncovered (10): runGlobCommand, main, runProjectCommand, runFileCommand, evaluateRepo, ...
   ⚠ These affected functions have no test references
 
-Summary: 15 affected → 19 test files, 5/15 functions covered (33%)
+Summary: 15 affected → 20 test files, 5/15 functions covered (33%) · 1 possibly affected (unverified chains)
 ```
 
+The confirmed closure is what you run; `POSSIBLY AFFECTED` lists functions reached only through unverified edges — extra tests worth a look, kept separate.
+
 ## Find unused code
 
 ```
 $ ucn deadcode --exclude=test
 
-Dead code: 3 unused symbol(s)
+Dead code: 2 unused symbol(s)
 
-core/bridge.js
-  [  90-  92] endsWithWildcard (function)
-  [ 258- 265] parsePythonDecorator (function)
-core/search.js
-  [1409-1445] _testBodyReferencesClass (function)
+core/output/analysis.js
+  [  29-  32] formatHistogramLine (function)
+  [  41-  44] shouldShowReachability (function)
 
-325 exported symbol(s) excluded (all have callers). Use --include-exported to audit them.
+353 exported symbol(s) excluded (all have callers). Use --include-exported to audit them.
 ```
 
 Find missing-await bugs:
@@ -297,6 +362,7 @@ function compareNames(a, b) {
 - **Coverage** - every command, every supported language, every surface (CLI, MCP, interactive)
 - **Systematic** - a harness exercises all command and flag combinations against real multi-language fixtures
 - **Test types** - unit, integration, per-language regression, formatter, cache, MCP edge cases, architecture parity guards
+- **Ground truth** - caller accuracy is measured against ts-morph, pyright, gopls, rust-analyzer, and jdtls on 10 pinned real repos, gated on zero unexplained edges (see [Answers you can trust](#answers-you-can-trust))
 
 ---
 
@@ -369,8 +435,9 @@ Run `ucn --help` for the full command list and flags.
 
 - Single-project scope - follows imports within the project, not into `node_modules` or `site-packages`
 - No runtime execution - static analysis only
-- Dynamic dispatch and reflection are only partially visible or invisible
-- JS, TS, and Python method calls can be uncertain when receiver type is unknown
+- Reflection (Python `getattr`, Java reflection) is invisible - the target is built at runtime
+- Interface/trait dispatch can't be resolved to a single impl, but candidates are surfaced as `possible-dispatch` in the unverified tier, never silently dropped
+- JS, TS, and Python method calls on an untyped receiver can't always be proven - UCN surfaces these in the UNVERIFIED tier with a reason rather than dropping or guessing them ([Answers you can trust](#answers-you-can-trust))
 - Large repos take a few seconds on the first query, then use cache
 
 If you need compiler diagnostics, taint analysis, or runtime semantics, those are different tools for different jobs. UCN trades that depth for speed, portability, and zero setup.

package/cli/index.js

@@ -197,6 +197,7 @@ function parseFlags(tokens) {
         includeExported: tokens.includes('--include-exported') || undefined,
         includeDecorated: tokens.includes('--include-decorated') || undefined,
         includeUncertain: tokens.includes('--include-uncertain') || undefined,
+        expandUnverified: tokens.includes('--expand-unverified') || undefined,
         includeMethods: tokens.some(a => a === '--include-methods=false' || a === '--no-include-methods') ? false : tokens.some(a => a === '--include-methods' || (a.startsWith('--include-methods=') && a !== '--include-methods=false')) ? true : undefined,
         detailed: tokens.includes('--detailed') || undefined,
         topLevel: tokens.includes('--top-level') || undefined,
@@ -279,11 +280,11 @@ flags.followSymlinks = !args.includes('--no-follow-symlinks');
 
 // Known flags for validation
 const knownFlags = new Set([
-    '--help', '-h', '--mcp',
+    '--help', '-h', '--version', '-v', '--mcp',
     '--json', '--verbose', '--no-quiet', '--quiet',
     '--code-only', '--with-types', '--top-level', '--exact', '--case-sensitive',
     '--no-cache', '--clear-cache', '--include-tests', '--exclude-tests',
-    '--include-exported', '--include-decorated', '--expand', '--interactive', '-i', '--all', '--include-methods', '--no-include-methods', '--include-uncertain', '--detailed', '--calls-only',
+    '--include-exported', '--include-decorated', '--expand', '--interactive', '-i', '--all', '--include-methods', '--no-include-methods', '--include-uncertain', '--expand-unverified', '--detailed', '--calls-only',
     '--file', '--context', '--exclude', '--not', '--in',
     '--depth', '--direction', '--add-param', '--remove-param', '--rename-to',
     '--default', '--top', '--no-follow-symlinks',
@@ -303,6 +304,12 @@ if (args.includes('--help') || args.includes('-h')) {
     process.exit(0);
 }
 
+// Handle version flag — read from package.json (single source of truth, shared with MCP serverInfo)
+if (args.includes('--version') || args.includes('-v')) {
+    console.log(require('../package.json').version);
+    process.exit(0);
+}
+
 // Validate flags
 const unknownFlags = args.filter(a => {
     if (!a.startsWith('-')) return false;
@@ -653,6 +660,16 @@ function runProjectCommand(rootDir, command, arg) {
                 console.error(`Warning: ${flagToCli(key)} has no effect on '${toCliName(canonical)}'.`);
             }
         }
+        // Tiered-output contract: unverified callers are always shown for
+        // these commands, so the legacy reveal flags are implied no-ops.
+        if (['about', 'context', 'impact', 'trace', 'blast', 'reverseTrace', 'affectedTests'].includes(canonical)) {
+            if (flags.includeUncertain) {
+                console.error(`Note: --include-uncertain is implied for '${toCliName(canonical)}' — unverified candidates are always shown (tiered).`);
+            }
+            if (['about', 'context', 'impact'].includes(canonical) && flags.includeMethods) {
+                console.error(`Note: --include-methods is implied for '${toCliName(canonical)}' — method calls are tiered by receiver evidence.`);
+            }
+        }
     }
 
     switch (canonical) {
@@ -1514,7 +1531,7 @@ Common Flags:
   --in=<path>         Only in path (e.g., --in=src/core)
   --depth=N           Max depth: blast=3, trace=3, reverse-trace=5, graph=2, affected-tests=3
   --direction=X       Graph direction: imports, importers, or both (default: both)
-  --all               Show full results: all callers/callees (about), full tree (trace/blast),
+  --all               Show full results: all callers/callees + unverified (about/context), full tree (trace/blast),
                         all names (related/find/fn/class/toc), all changed (diff-impact)
   --top=N             Limit callers/callees (about), similar functions (related), search results
   --limit=N           Limit result count (find, usages, search, deadcode, api, toc, entrypoints, diff-impact)
@@ -1527,8 +1544,13 @@ Common Flags:
   --include-tests     Include test files in usage counts (about) and results (find, usages, deadcode)
   --exclude-tests     Exclude test files (entrypoints — tests are included by default)
   --class-name=X      Scope to specific class (e.g., --class-name=Repository)
-  --include-methods   Include method calls (obj.fn) in caller/callee analysis
-  --include-uncertain Include ambiguous/uncertain matches
+  --include-methods   Include method calls (obj.fn) in trace/blast/smart/verify analysis
+                        (implied for about/context/impact — method calls are tiered by evidence)
+  --include-uncertain Include ambiguous/uncertain matches in smart/verify
+                        (implied for about/context/impact/trace/blast/reverse-trace/affected-tests —
+                        unverified candidates always shown, tiered)
+  --expand-unverified Follow unverified caller edges in blast/reverse-trace trees
+                        (downstream nodes marked as unverified chains — possible, not confirmed, impact)
   --hide-confidence   Hide confidence scores (shown by default in about, context)
   --min-confidence=N  Filter low-confidence edges (about, context, blast, trace,
                         reverse-trace, smart, affected-tests)
@@ -1561,6 +1583,7 @@ Common Flags:
   --staged            Analyze staged changes (diff-impact)
   --no-follow-symlinks  Don't follow symbolic links
   -i, --interactive   Keep index in memory for multiple queries
+  -v, --version       Print the UCN version and exit
 
 Quick Start:
   ucn toc                             # See project structure