ucn 3.8.23 → 3.8.26

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

@@ -71,6 +71,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.
@@ -91,15 +93,56 @@ ucn deadcode --exclude=test         # Skip test files (most useful)
 ucn deadcode --include-decorated    # Include framework-registered functions
 ```
 
-### 7. `entrypoints` — Detect framework entry points
+### 7. `brief` — One-screen "before-I-touch-this" summary
+
+AST-only summary of a function: typed signature, first sentence of docstring,
+side-effect classification (fs/network/process/global_mutation), and complexity
+metrics (branches, depth, line count). Lighter than `about`, more useful than
+`fn` when you don't need the body.
+
+```bash
+ucn brief fetch_user
+# fetch_user(user_id: int): dict
+#   svc.py:4-8  (5 lines)
+#   "Fetch a user from the API."
+#   async: no  |  side_effects: [fs, network, process]  |  complexity: branches=2, depth=2
+```
+
+### 8. `doctor` — Project trust report
+
+One command that tells you how much UCN trusts the index for this project:
+file/symbol counts, language breakdown, dynamic-import / eval / reflection
+blind spots, parse failures, and a verdict (HIGH/MEDIUM/LOW). Add `--deep` to
+sample resolution coverage and bucket edges by confidence.
+
+```bash
+ucn doctor                # fast: counts + blind spots + verdict
+ucn doctor --deep         # also samples resolution coverage
+ucn doctor --in=src/core  # scope to a subtree
+```
+
+### 9. `check` — Pre-commit summary
+
+Composes `diff-impact` + `verify` + `affected-tests` into one output. Lists
+changed/added/deleted functions, flags signature drift across call sites,
+calls out new functions with no callers, and recommends which tests to run.
+
+```bash
+ucn check                  # vs HEAD
+ucn check --base=main      # vs main branch
+ucn check --staged         # only staged changes
+```
+
+### 10. `entrypoints` — Detect framework entry points
 
 Lists functions registered as framework handlers (HTTP routes, DI beans, job schedulers, etc.). Detects patterns across Express, FastAPI, Flask, Spring, Gin, Actix, Celery, pytest, and more.
 
 ```bash
-ucn entrypoints                          # All detected entry points
+ucn entrypoints                          # All detected entry points (tests included by default)
 ucn entrypoints --type=http              # HTTP routes only
 ucn entrypoints --framework=express      # Specific framework
 ucn entrypoints --file=routes/           # Scoped to files
+ucn entrypoints --exclude-tests          # Hide test fixtures (JUnit @Test, pytest, Rust #[test], etc.)
 ```
 
 ## When to Use the Other Commands
@@ -117,10 +160,10 @@ ucn entrypoints --file=routes/           # Scoped to files
 | Understanding who depends on a file | `ucn exporters <file>` | Which files import it |
 | See what a file exports | `ucn file-exports <file>` | All exported functions, classes, variables with signatures |
 | Quick project overview | `ucn toc` | Every file with function/class counts and line counts |
-| Project complexity stats | `ucn stats` | File counts, symbol counts, lines by language. `--functions` for per-function line counts |
+| 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 |
@@ -133,13 +176,72 @@ ucn entrypoints --file=routes/           # Scoped to files
 | File-level dependency tree | `ucn graph <file> --depth=1` | Visual import tree. Setting `--depth=N` expands all children. Can be noisy — use depth=1 for large projects. For function-level flow, use `trace` instead |
 | Are there circular dependencies? | `ucn circular-deps` | Detect circular import chains. `--file=<pattern>` filters to cycles involving a file. `--exclude=test` skips test files |
 | What are the framework entry points? | `ucn entrypoints` | Lists all detected routes, DI beans, tasks, etc. Filter: `--type=http`, `--framework=express` |
+| Polyglot route ↔ request matching | `ucn endpoints --bridge` | Server routes (Express/Fastify/Koa/NestJS/Flask/FastAPI/Spring/JAX-RS/Gin/Echo/Chi/Fiber/axum/actix/Next.js) ↔ client requests (fetch/axios/requests/httpx/RestTemplate/WebClient/reqwest). Match confidence: EXACT, PARTIAL, UNCERTAIN. Filter with `--method`, `--prefix`, `--server-only`, `--client-only`, `--unmatched`, `--hide-uncertain` |
 | Find which tests cover a function | `ucn tests <name>` | Test files and test function names. Scope with `--file`, `--class-name`, `--exclude`, `--calls-only` |
-| Extract specific lines from a file | `ucn lines --file=<file> --range=10-20` | Pull a line range without reading the whole file |
+| Extract specific lines from a file | `ucn lines 10-20 --file=<file>` | Pull a line range without reading the whole file |
 | Find type definitions | `ucn typedef <name>` | Interfaces, enums, structs, traits, type aliases |
 | See a project's public API | `ucn api` or `ucn api --file=<file>` | All exported/public symbols with signatures |
 | Drill into context results | `ucn expand <N>` | Show source code for item N from a previous `context` call |
 | Best usage example of a function | `ucn example <name>` | Finds and scores the best call site with surrounding context |
 | Debug a stack trace | `ucn stacktrace --stack="<trace>"` | Parses stack frames and shows source context per frame |
+| Quick look before touching a function | `ucn brief <name>` | Signature + docstring + side effects + complexity, one screen |
+| Project trust report | `ucn doctor [--deep]` | Index coverage, blind spots, parse failures, verdict |
+| 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:
+
+| Flag | What it means | Why it matters |
+|------|--------------|---------------|
+| `inLoop` | Call is inside a `for`/`while`/comprehension | N+1 query risk, repeated work, performance hot path |
+| `inTry` | Call is wrapped in try/catch (or equivalent) | Errors are handled — different from "must fix" code paths |
+| `inCallback` | Call sits inside a callback/lambda/closure that's not the enclosing function | Async deferred work, may run on a different stack frame |
+| `inTestCase` | Call originates from inside a test function | Isolate production callers from test setup |
+| `awaited` | Call's parent is `await` / `Promise.then` (JS/TS/Python) | Confirms async coordination — its absence on async callees signals a missing-await bug |
+
+`audit-async` is the focused tool for the `awaited=false` case across an entire async function body.
+
+## Confidence Scores
+
+`about` and `context` show confidence per caller/callee edge by default (e.g. `confidence: 0.65 (scope-match)`). Resolution labels (high to low):
+
+| 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` |
+
+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
+
+## Symbol Handles (stable IDs)
+
+Every result that lists a symbol emits a **handle** in the form `relativePath:line:name` (e.g. `core/api.ts:42:handler`). Pass it back to any name-accepting command and resolution is pinned to that exact definition — no name disambiguation, no `--file` needed.
+
+```bash
+ucn find handler                  # → emits  src/api.ts:42:handler
+ucn brief src/api.ts:42:handler   # pins to that exact one
+ucn impact src/api.ts:42:handler  # same
+```
+
+The shorter `relativePath:line` form (no `:name`) also works — UCN looks up the symbol by location. Plain names (`handler`) still work for the fuzzy/heuristic path.
 
 ## Command Format
 
@@ -157,14 +259,15 @@ ucn [target] <command> [name] [--flags]
 
 | Flag | When to use it |
 |------|---------------|
-| `--class-name=X` | Scope to specific class (e.g., `--class-name=Repository` for method `save`). Works with `fn`, `about`, `context`, `impact`, `tests`, `example`, `typedef`, `verify`, `plan` |
+| `--class-name=X` | Scope to specific class (e.g., `--class-name=Repository` for method `save`). Works with `about`, `context`, `impact`, `blast`, `smart`, `trace`, `reverse-trace`, `example`, `related`, `brief`, `find`, `usages`, `tests`, `affected-tests`, `fn`, `verify`, `plan`, `typedef` |
 | `--file=<pattern>` | Disambiguate when a name exists in multiple files (e.g., `--file=api`) |
 | `--exclude=test,mock` | Focus on production code only |
 | `--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 in `about`, `trace`, `graph`, `related` |
+| `--all` | Expand truncated sections. Applies to `about`, `blast`, `trace`, `reverse-trace`, `related`, `find`, `toc`, `fn`, `class`, `graph`, `diff-impact` |
 | `--include-tests` | Include test files in usage counts (`about`) and results (`find`, `usages`, `deadcode`). Callers always include tests. |
-| `--include-methods` | Include `obj.method()` calls in `context`/`smart` (only direct calls shown by default) |
+| `--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` |
 | `--base=<ref>` | Git ref for diff-impact (default: HEAD) |
 | `--staged` | Analyze staged changes (diff-impact) |
 | `--no-cache` | Force re-index after editing files |
@@ -172,19 +275,22 @@ ucn [target] <command> [name] [--flags]
 | `--context=N` | Lines of surrounding context in `usages`/`search` output |
 | `--no-regex` | Force plain text search (regex is default) |
 | `--functions` | Show per-function line counts in `stats` (complexity audit) |
-| `--json` | Machine-readable JSON output (wrapped in `{meta, data}`) |
+| `--hot` | List top N most-called functions in `stats` (use with `--top=N`, default 10). Best orientation primitive when entering a new repo |
+| `--diverse` | Cluster `example` call sites by argument shape and return one representative per cluster (use with `--top=N`, default 3) |
+| `--git` | Attach git enrichment to `about` / `brief`: last commit (ISO + author) and recent change count (last 30 days). Skipped silently when not a git repo |
+| `--json` | Machine-readable JSON output. Some commands wrap in `{meta, data}` (e.g., `find`, `deadcode`); others return flat objects (e.g., `about`, `impact`, `verify`, `plan`, `imports`) — check each command's output shape |
 | `--code-only` | Exclude matches in comments and strings (`search`/`usages`) |
 | `--with-types` | Include related type definitions in `smart`/`about` output |
 | `--detailed` | Show full symbol listing per file in `toc` |
 | `--top-level` | Show only top-level functions in `toc` (exclude nested/indented) |
 | `--top=N` | Limit result count (default: 10 for most commands) |
-| `--limit=N` | Limit result count for `find`, `usages`, `search`, `deadcode`, `api`, `toc`, `entrypoints`, `diff-impact` |
+| `--limit=N` | Limit result count for `find`, `usages`, `toc`, `search`, `deadcode`, `entrypoints`, `endpoints`, `diff-impact`, `check`, `api`, `doctor`, `audit-async` |
 | `--max-files=N` | Max files to index (for large projects with 10K+ files) |
 | `--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 in `context`/`smart`/`about` |
-| `--no-confidence` | Hide confidence scores (shown by default) in `context`/`about` |
+| `--include-uncertain` | Include ambiguous/uncertain matches. Applies to `about`, `context`, `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) |
 | `--add-param=<name>` | Add a parameter (`plan` command). Combine with `--default=<value>` |
@@ -193,6 +299,13 @@ ucn [target] <command> [name] [--flags]
 | `--include-exported` | Include exported symbols in `deadcode` results |
 | `--include-decorated` | Include decorated/annotated symbols in `deadcode` results |
 | `--framework=X` | Filter `entrypoints` by framework (e.g., `express`, `spring`, `celery`) |
+| `--bridge` | Match server routes to client requests (`endpoints`). Confidence tiers: EXACT, PARTIAL, UNCERTAIN |
+| `--server-only` | Only list server routes (`endpoints`) |
+| `--client-only` | Only list client requests (`endpoints`) |
+| `--unmatched` | Only show routes/requests with no match (`endpoints`, pair with `--bridge`) |
+| `--method=GET` | Filter by HTTP method (`endpoints`) |
+| `--prefix=/api` | Filter routes/requests by path prefix (`endpoints`) |
+| `--hide-uncertain` | Hide UNCERTAIN-confidence bridges (`endpoints`) |
 | `--type=<kind>` | Structural search: `function`, `class`, `call`, `method`, `type`. Triggers index query instead of text grep |
 | `--param=<name>` | Structural search: filter by parameter name or type (e.g., `--param=Request`) |
 | `--receiver=<name>` | Structural search: filter calls by receiver (e.g., `--receiver=db` for all db.* calls) |
@@ -202,6 +315,8 @@ ucn [target] <command> [name] [--flags]
 | `--unused` | Structural search: only symbols with zero callers |
 | `--no-follow-symlinks` | Don't follow symbolic links during file discovery |
 | `--workers=N` | Parallel build workers (auto-detect by default; `0` to disable; env: `UCN_WORKERS`) |
+| `--deep` | `doctor` only: sample resolution coverage. Slower but produces confidence histogram. |
+| `--compact` | One-line-per-item output for `about`/`context`/`find`/`usages`/`impact`. Halves token cost; same info. |
 
 ## Workflow Integration
 

package/README.md

@@ -51,21 +51,21 @@ ucn deadcode --exclude=test    # unused code, AST-verified
 $ ucn trace build --depth=2
 
 build
-├── detectProjectPattern (core/discovery.js:399) 1x
-│   ├── checkDir (core/discovery.js:403) 2x
-│   └── shouldIgnore (core/discovery.js:347) 1x
-├── parseGitignore (core/discovery.js:130) 1x
-├── expandGlob (core/discovery.js:190) 1x
-│   ├── parseGlobPattern (core/discovery.js:226) 1x
-│   ├── walkDir (core/discovery.js:283) 1x
-│   └── compareNames (core/discovery.js:169) 1x
-├── indexFile (core/project.js:273) 1x
-│   ├── addSymbol (core/project.js:343) 4x
-│   ├── detectLanguage (languages/index.js:157) 1x
+├── detectProjectPattern (core/discovery.js:431) 1x
+├── parseGitignore (core/discovery.js:131) 1x
+├── expandGlob (core/discovery.js:191) 1x
+│   ├── parseGlobPattern (core/discovery.js:227) 1x
+│   ├── walkDir (core/discovery.js:284) 1x
+│   └── 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
 │   ├── parse (core/parser.js:69) 1x
-│   └── extractImports (core/imports.js:19) 1x
-├── buildImportGraph (core/project.js:549) 1x
-└── buildInheritanceGraph (core/project.js:627) 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
 ```
 
 One command. No files opened. Every function located by file and line.
@@ -81,26 +81,28 @@ $ ucn about expandGlob
 
 expandGlob (function)
 ════════════════════════════════════════════════════════════
-core/discovery.js:190-221
-expandGlob (pattern, options = {})
+core/discovery.js:191-222  →  core/discovery.js:191:expandGlob
+expandGlob (pattern: string, options: number = {}) : string[]
 
-CALLERS (3):
-  cli/index.js:859 [runGlobCommand]
+CALLERS (7):
+  confidence: 0 high (>0.8), 7 medium (0.5-0.8), 0 low (<0.5)
+  cli/index.js:1190 [runGlobCommand]
     const files = expandGlob(pattern);
-  core/cache.js:274 [isCacheStale]
+    confidence: 0.65 (scope-match)
+  core/cache.js:417 [isCacheStale]
     const currentFiles = expandGlob(pattern, globOpts);
-  core/project.js:195 [build]
-    const files = expandGlob(pattern, globOpts);
+    confidence: 0.65 (scope-match)
+  ... (5 more)
 
 CALLEES (3):
-  parseGlobPattern [utility] - core/discovery.js:226
-  walkDir [utility] - core/discovery.js:283
-  compareNames [utility] - core/discovery.js:169
+  parseGlobPattern [utility] - core/discovery.js:227
+  walkDir [utility] {fs} - core/discovery.js:284
+  compareNames [utility] - core/discovery.js:170
 
-TESTS: 6 matches in 2 file(s)
+TESTS: 5 matches in 1 file(s)
 ```
 
-Need to trace execution upward instead? `ucn reverse-trace fn` walks the caller chain back to entry points.
+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.
 
 ## Change code without breaking things
 
@@ -109,38 +111,100 @@ Before touching a function, check if all existing call sites match its signature
 ```
 $ ucn verify expandGlob
 
-expandGlob (pattern, options = {})
+Verification: expandGlob
+════════════════════════════════════════════════════════════
+core/discovery.js:191
+expandGlob (pattern: string, options: number = {}) : string[]
+
 Expected arguments: 1-2
 
-STATUS: ✓ All calls valid (7 calls, 0 mismatches)
+STATUS: ✓ All calls valid
+  Total calls: 7
+  Valid: 7
+  Mismatches: 0
+  Uncertain: 0
+  Patterns: 4 in try, 4 in callback
 ```
 
+The `Patterns:` line surfaces structural classification of each call site — `inLoop`, `inTry`, `inCallback`, `inTestCase`, `awaited` — so you can spot risky call sites (e.g., calls inside loops, missing `await`) at a glance. Same line appears on `impact` and inside `about`.
+
 Then preview the refactoring. UCN shows exactly what needs to change and where:
 
 ```
 $ ucn plan expandGlob --rename-to=expandGlobPattern
 
+Refactoring plan: rename
+════════════════════════════════════════════════════════════
+core/discovery.js:191
+
 SIGNATURE CHANGE:
-  Before: expandGlob (pattern, options = {})
-  After:  expandGlobPattern (pattern, options = {})
+  Before: expandGlob (pattern: string, options: number = {}) : string[]
+  After:  expandGlobPattern (pattern: string, options: number = {}) : string[]
 
-CHANGES NEEDED: 7 across 4 files
+CHANGES NEEDED: 11
+  Files affected: 4
 
-cli/index.js :859
-  const files = expandGlob(pattern);
-  → const files = expandGlobPattern(pattern);
+BY FILE:
 
-core/cache.js :274
-  const currentFiles = expandGlob(pattern, globOpts);
-  → const currentFiles = expandGlobPattern(pattern, globOpts);
+cli/index.js (2 changes)
+  :1190
+    const files = expandGlob(pattern);
+    → Rename to: const files = expandGlobPattern(pattern);
+  :15
+    const { expandGlob, findProjectRoot } = require('../core/discovery');
+    → Update import: const { expandGlobPattern, findProjectRoot } = require('../core/discovery');
 
-core/project.js :195
-  const files = expandGlob(pattern, globOpts);
-  → const files = expandGlobPattern(pattern, globOpts);
+... (more changes in core/cache.js, core/project.js, test/integration.test.js)
 ```
 
 Run `ucn diff-impact --staged` before committing to see what you changed and who calls it.
 
+Or wrap the same checks in a single command:
+
+```
+$ ucn check --staged
+
+Pre-commit Check vs HEAD
+════════════════════════════════════════════════════════════
+Changed: 3 functions
+  parseFlags (cli/index.js:165) [MODIFIED]  2 callers
+  ...
+```
+
+`ucn check` composes `diff-impact` + `verify` + `affected-tests` in one shot — flags ADDED functions with no callers, signature drift across call sites, and recommends which tests to run.
+
+## Get the lay of the land in a new repo
+
+```
+$ ucn brief fetch_user
+fetch_user(user_id: int): dict
+  svc.py:4-8  (5 lines)
+  "Fetch a user from the API."
+  async: no  |  side_effects: [fs, network, process]  |  complexity: branches=2, depth=2
+```
+
+`brief` is the lighter alternative to `about` — typed signature, first sentence of the docstring, side-effect classification, and complexity, all in one screen. Pair with `--git` to see who last touched it and how often.
+
+```
+$ ucn doctor
+
+UCN Trust Report — /path/to/project
+Index: 144 files, 1569 symbols
+Languages: javascript (74%), typescript (13%), java (4%), python (3%), rust (3%), go (3%)
+Cache: fresh, 221ms build
+...
+Trust level: HIGH
+```
+
+`doctor` reports how much UCN trusts the index — file/symbol counts, blind spots (dynamic imports, eval, reflection), parse failures, and a verdict. Use `--deep` to also sample resolution coverage.
+
+`entrypoints` lists detected framework handlers (HTTP routes, DI beans, jobs, tests):
+
+```
+ucn entrypoints --type=http --framework=spring   # narrow to one framework
+ucn entrypoints --exclude-tests                  # tests are included by default
+```
+
 ## Find what to clean up
 
 Which tests should you run after a change? `affected-tests` walks the blast radius and finds every test that touches the affected functions:
@@ -148,11 +212,22 @@ Which tests should you run after a change? `affected-tests` walks the blast radi
 ```
 $ ucn affected-tests expandGlob
 
-1 function changed → 18 functions affected (depth 3)
-Summary: 18 affected → 12 test files, 11/18 functions covered (61%)
+affected-tests: expandGlob
+════════════════════════════════════════════════════════════
+core/discovery.js:191
+1 function changed → 15 functions affected (depth 3)
+
+Test files to run (19):
 
-Uncovered (7): runGlobCommand, runProjectCommand, ...
+  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, ...
   ⚠ These affected functions have no test references
+
+Summary: 15 affected → 19 test files, 5/15 functions covered (33%)
 ```
 
 ## Find unused code
@@ -160,19 +235,47 @@ Uncovered (7): runGlobCommand, runProjectCommand, ...
 ```
 $ ucn deadcode --exclude=test
 
-Dead code: 1 unused symbol(s)
+Dead code: 3 unused symbol(s)
+
+core/bridge.js
+  [  90-  92] endsWithWildcard (function)
+  [ 258- 265] parsePythonDecorator (function)
+core/search.js
+  [1409-1445] _testBodyReferencesClass (function)
+
+325 exported symbol(s) excluded (all have callers). Use --include-exported to audit them.
+```
+
+Find missing-await bugs:
 
-core/discovery.js
-  [ 162- 166] legacyResolve (function)
 ```
+ucn audit-async
+```
+
+Lists async calls inside async functions that lack `await` (JS/TS/Python).
+
+## Map your API surface across languages
+
+UCN can match server routes to client requests across the supported languages — Express/Fastify/Koa/NestJS/Next.js, Flask/FastAPI, Spring/JAX-RS, Go net/http (Gin/Echo/Chi/Fiber), axum/actix-web on the server side; fetch/axios, requests/httpx, RestTemplate/WebClient, reqwest on the client side.
+
+```bash
+ucn endpoints --bridge
+
+# Filters
+ucn endpoints --bridge --unmatched          # routes with no client / clients with no server
+ucn endpoints --bridge --method=POST
+ucn endpoints --bridge --prefix=/api
+```
+
+Match confidence: `EXACT` (literal-literal), `PARTIAL` (server param ↔ client literal), `UNCERTAIN` (template-literal client). Use `--hide-uncertain` to drop the noisy tier.
 
 ## Extract without reading the whole file
 
 ```
 $ ucn fn compareNames
 
-core/discovery.js:169
-[ 169- 177] compareNames(a, b)
+core/discovery.js:170
+[ 170- 178] compareNames(a, b)
 ────────────────────────────────────────────────────────────
 function compareNames(a, b) {
     const aLower = a.toLowerCase();
@@ -258,114 +361,7 @@ cp -r "$(npm root -g)/ucn/.claude/skills/ucn" ~/.agents/skills/
 
 ## Full help
 
-```text
-UCN - Universal Code Navigator
-
-Supported: JavaScript, TypeScript, Python, Go, Rust, Java, HTML
-
-Usage:
-  ucn [command] [args]            Project mode (current directory)
-  ucn <file> [command] [args]     Single file mode
-  ucn <dir> [command] [args]      Project mode (specific directory)
-  ucn "pattern" [command] [args]  Glob pattern mode
-  (Default output is text; add --json for machine-readable JSON)
-
-═══════════════════════════════════════════════════════════════════════════════
-UNDERSTAND CODE
-═══════════════════════════════════════════════════════════════════════════════
-  about <name>        Full picture (definition, callers, callees, tests, code)
-  context <name>      Who calls this + what it calls (numbered for expand)
-  smart <name>        Function + all dependencies inline
-  impact <name>       What breaks if changed (call sites grouped by file)
-  blast <name>        Transitive blast radius (callers of callers, --depth=N)
-  trace <name>        Call tree visualization (--depth=N expands all children)
-  reverse-trace <name> Upward call chain to entry points (--depth=N, default 5)
-  related <name>      Find similar functions (same file, shared deps)
-  example <name>      Best usage example with context
-
-═══════════════════════════════════════════════════════════════════════════════
-FIND CODE
-═══════════════════════════════════════════════════════════════════════════════
-  find <name>         Find symbol definitions (supports glob: find "handle*")
-  usages <name>       All usages grouped: definitions, calls, imports, references
-  toc                 Table of contents (compact; --detailed lists all symbols)
-  search <term>       Text search (regex default, --context=N, --exclude=, --in=)
-                      Structural: --type=function|class|call --param= --returns= --decorator= --exported --unused
-  tests <name>        Find test files for a function
-  affected-tests <n>  Tests affected by a change (blast + test detection, --depth=N)
-
-═══════════════════════════════════════════════════════════════════════════════
-EXTRACT CODE
-═══════════════════════════════════════════════════════════════════════════════
-  fn <name>[,n2,...]  Extract function(s) (comma-separated for bulk, --file)
-  class <name>        Extract class
-  lines <range>       Extract line range (e.g., lines 50-100)
-  expand <N>          Show code for item N from context output
-
-═══════════════════════════════════════════════════════════════════════════════
-FILE DEPENDENCIES
-═══════════════════════════════════════════════════════════════════════════════
-  imports <file>      What does file import
-  exporters <file>    Who imports this file
-  file-exports <file> What does file export
-  graph <file>        Full dependency tree (--depth=N, --direction=imports|importers|both)
-  circular-deps       Detect circular import chains (--file=, --exclude=)
-
-═══════════════════════════════════════════════════════════════════════════════
-REFACTORING HELPERS
-═══════════════════════════════════════════════════════════════════════════════
-  plan <name>         Preview refactoring (--add-param, --remove-param, --rename-to)
-  verify <name>       Check all call sites match signature
-  diff-impact         What changed in git diff and who calls it (--base, --staged)
-  deadcode            Find unused functions/classes
-  entrypoints         Detect framework entry points (routes, DI, tasks)
-
-═══════════════════════════════════════════════════════════════════════════════
-OTHER
-═══════════════════════════════════════════════════════════════════════════════
-  api                 Show exported/public symbols
-  typedef <name>      Find type definitions
-  stats               Project statistics (--functions for per-function line counts)
-  stacktrace <text>   Parse stack trace, show code at each frame (alias: stack)
-
-Common Flags:
-  --file <pattern>    Filter by file path (e.g., --file=routes)
-  --exclude=a,b       Exclude patterns (e.g., --exclude=test,mock)
-  --in=<path>         Only in path (e.g., --in=src/core)
-  --depth=N           Trace/graph depth (default: 3, also expands all children)
-  --direction=X       Graph direction: imports, importers, or both (default: both)
-  --all               Expand truncated sections (about, trace, graph, related)
-  --top=N             Limit results (find, deadcode)
-  --limit=N           Limit result count (find, usages, search, deadcode, api, toc)
-  --max-files=N       Max files to index (large projects)
-  --context=N         Lines of context around matches
-  --json              Machine-readable output
-  --code-only         Filter out comments and strings
-  --with-types        Include type definitions
-  --include-tests     Include test files
-  --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
-  --no-confidence     Hide confidence scores (shown by default)
-  --min-confidence=N  Filter edges below confidence threshold (0.0-1.0)
-  --include-exported  Include exported symbols in deadcode
-  --no-regex          Force plain text search (regex is default)
-  --functions         Show per-function line counts (stats command)
-  --include-decorated Include decorated/annotated symbols in deadcode
-  --framework=X       Filter entrypoints by framework (e.g., --framework=express,spring)
-  --exact             Exact name match only (find)
-  --calls-only        Only show call/test-case matches (tests)
-  --case-sensitive    Case-sensitive text search (search)
-  --detailed          List all symbols in toc (compact by default)
-  --top-level         Show only top-level functions in toc
-  --max-lines=N       Max source lines for class (large classes show summary)
-  --no-cache          Disable caching
-  --clear-cache       Clear cache before running
-  --base=<ref>        Git ref for diff-impact (default: HEAD)
-  --staged            Analyze staged changes (diff-impact)
-  --no-follow-symlinks  Don't follow symbolic links
-  -i, --interactive   Keep index in memory for multiple queries
-```
+Run `ucn --help` for the full command list and flags.
 
 ---