ucn 5.4.1 → 5.5.0

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

@@ -5,99 +5,22 @@ description: AST code intelligence for JavaScript/TypeScript, Python, Go, Rust,
 
 # UCN
 
-Use UCN to gather compact, auditable code evidence before reading large files or changing a symbol.
+UCN answers semantic questions about a codebase from a tree-sitter index: where a symbol is defined, who calls it, what it calls, what a change touches, which tests reach it. Every answer labels its evidence and accounts for every line it looked at; nothing is silently dropped.
+
+## When to use it
+
+- Semantic questions in a supported language (JavaScript/TypeScript/TSX, Python, Go, Rust, Java, C, C++, C#, HTML inline scripts): definitions, callers, callees, impact, tests, dependencies, public API, dead code.
+- Use text search for literals, messages, configuration, filenames, Markdown, and unsupported languages. Below roughly 500 LOC, reading the files directly is usually faster.
+- An empty UCN result is a statement about the indexed text, never proof that nothing reaches a symbol at runtime.
 
 ## Core workflow
 
-1. Run `ucn repo` in an unfamiliar repository. Add `--deep` when readiness or index health matters. If it reports skipped unsupported source, use grep/ripgrep and a language-native analyzer for those files; never interpret an `UNSUPPORTED` or `PARTIAL` scope as a semantic zero.
-2. Pin a symbol with `ucn find <name>`, then pass its `path:line:name` handle to later commands.
-3. Run `ucn show <handle>` for the default summary, callers, and callees. Request extra projections with `--sections=source,tests,types,dependencies,example,related`.
-4. Before a change, run `ucn impact <handle>` and `ucn tests <handle> --depth=3`.
-5. After a signature change, run `ucn check <handle>`. Before committing, run target-less `ucn check`.
-6. Read exact code with `ucn source <handle>` or `ucn source path/to/file:10-30` only when inspection is needed.
-
-Prefer `--json` for automation. Every CLI JSON response uses `{ meta, data }`;
-`meta.command` uses the native surface spelling and may include the internal
-`canonicalCommand`. MCP returns text through one `ucn` tool and keeps contract
-metadata visible when truncating results.
-
-## One contract across surfaces
-
-CLI, MCP, and interactive mode resolve the same 18 public commands through one registry, execute the same handlers, and use the same public formatters. CLI spells multiword commands with hyphens; MCP uses snake case. For example, use `audit-async` in CLI and `audit_async` in MCP.
-
-The release board independently cross-checks overlapping stable-handle answers from `find`, `show`, `source`, `impact`, `tests`, `check`, and caller `trace`. Target identity, source and direct-test projections, caller tiers, evidence reasons, totals, and accounting must agree exactly; a mismatch is a failing witness rather than an interpretation left to an agent.
-
-Publish-blocking semantic gates also compare stratified samples from pinned real repositories with independent language-native oracles: ts-morph, Pyright, gopls, rust-analyzer, JDT LS, clangd, and Roslyn. This validates the measured static evidence classes; it does not turn dynamic dispatch, generated code, reflection, or external dependencies into complete runtime knowledge.
-
-MCP keeps its process and project index warm across calls. CLI and MCP share
-the same text budget: broad sweep commands (`repo`, `entrypoints`,
-`endpoints`, `deadcode`, `deps`, `check`, `audit-async`) default to 3K output
-characters, all other commands to 10K, with a 100K hard ceiling. Use CLI
-`--max-chars`, MCP `max_chars`, a narrower file/directory scope, or a smaller
-section projection when necessary. Truncated output keeps the head of the
-answer, a notice stating the full size and limit, and the accounting/contract
-lines needed to interpret what remains; the requested limit includes all
-three. The text block is the whole response on every surface.
-
-Persistent indexes live in a per-user, project-keyed cache rather than the analyzed repository. Set `UCN_CACHE_DIR` to override the cache root; CLI `--no-cache` bypasses persistence and `--clear-cache` removes the current project's cache. Legacy `<project>/.ucn-cache` directories are migrated on first use. Concurrent invocations on a cold cache share one build: the first process takes a build lock, the others wait for its cache (`Waiting for another ucn process building the index...` on stderr) instead of rebuilding; a lock left by a dead process is broken automatically.
-
-Files named `*.min.js`, `*.bundle.js`, and `*.map` are disclosed as skipped
-bundled sources; they make observed-text completeness partial. Pass
-`--include-bundled` (MCP `include_bundled=true`) to index the JavaScript files.
-This option bypasses the shared cache and still respects user exclusions.
-Source maps remain disclosed but unindexed; inspect them with text tools.
-
-Supported source families are JavaScript/TypeScript/TSX, Python, Go, Rust, Java, C, C++, C#, and HTML inline JavaScript/event handlers. C/C++ uses `compile_commands.json` when available to classify headers and resolve include paths. Recoverable preprocessor branches contribute AST-proven source facts, so a single selected configuration does not silently erase definitions or calls; disagreeing conditional macro identities stay visible as unverified. C++ resolution uses namespace ownership, static overload shape (including arrays), and macro-parameter requalification. C# resolution uses declared property/field receiver types plus overload and hiding discipline. This is portable AST analysis, not a compiler build; macros, templates, generated code, reflection, and external dependency semantics can remain unverified.
-
-`repo` refines its HOT list exactly for up to 400 candidate definitions per
-run; when a large repository exhausts that budget the HOT header says so and
-the ranking is approximate. `repo --sections=stats --hot` is always exact.
-
-`repo` readiness is task-specific. Its headline is navigation readiness;
-refactor, deletion, semantic recall, and the sampled evidence mix are separate
-dimensions. The confirmed/unverified percentage is a classification profile,
-not an accuracy grade.
-
-## Interpret evidence correctly
-
-For caller-bearing `show`, `impact`, `trace`, `tests`, and `check` views:
-
-- `CONFIRMED` has binding, receiver, import, or ownership evidence for the pinned target.
-- `UNVERIFIED` is a possible target with insufficient identity evidence. Review it before a breaking change. When same-name definitions cause the ambiguity, `show` lists their stable handles once above the sites so the competing targets are explicit.
-- `ACCOUNT` partitions observed literal-name lines into confirmed, unverified, non-call, excluded, and unresolved buckets. In mixed-language repositories it also counts occurrences in unsupported-language source files.
-- `CONTRACT` states the scope and completeness of that observed-text partition. When unsupported-language files contain the name, it says so explicitly and the partition-complete claim is limited to supported languages.
-- `WARNING` identifies unreadable, unparsed, or partially indexed files, and lists unsupported-language occurrence sites (file:line plus the line text) so nothing grep would show is hidden. `usages` and `tests` carry the same disclosure as a note.
-- `FILTERED` means query options hid evidence.
-
-When the selected definition is a property/getter/setter, `impact` adds a
-separate `PROPERTY ACCESS SITES` band. Confirmed reads/writes have receiver
-identity; matching attribute syntax with an unresolved receiver stays
-unverified. These are change dependencies, not fabricated caller edges, so
-the caller `ACCOUNT` remains a call-shaped partition. Reads and writes include
-access kind and token column; getter/setter handles describe the same property.
-Unambiguous inherited properties share that owner evidence.
-
-When the selected definition is a type, interface, enum, trait, or record,
-`impact` adds a `TYPE REFERENCE SITES` band: annotation and reference sites
-confirmed by an import link to the definition's file (or package scope in
-Go/Java), the rest visible as unverified with a reason. `DEPENDENCY SITES`
-counts them; `CALL SITES` stays call-shaped.
-
-Target-less `impact` and `check` diff the working tree against `HEAD` AND
-include untracked, non-ignored source files as whole-file additions, so new
-modules are checked before `git add`. `--staged` keeps its index-only meaning.
-The changed-path note also counts untracked documentation and configuration.
-Classes, interfaces, types, and fields appear in separate declaration bands
-with their dependency sites. Modified/deleted declarations block `check` until
-reviewed with the language toolchain: arity checks cannot validate shape or
-inheritance compatibility.
-
-An observed-text zero is not semantic zero or safe-delete proof. Numeric evidence values are ordinal ranking weights, not probabilities.
-
-When a plain name selects more than one definition, action-oriented commands
-(`impact`, `tests`, `check`, and `plan`) carry the same ambiguity warning as
-`show`/`source`/`trace`. Prefer a stable handle; never treat the auto-selected
-definition as an implicit repository-wide target.
+1. `ucn repo` in an unfamiliar repository; `--deep` adds index health and readiness. Skipped unsupported source is listed with a handoff: use text search and a language-native tool for those files. An `UNSUPPORTED` or `PARTIAL` scope is never a semantic zero.
+2. `ucn find <name>` pins a definition. Pass its `path:line:name` handle to every later command. A plain name that matches several definitions carries an ambiguity warning in `show`, `source`, `trace`, `impact`, `tests`, `check` and `plan`; never treat the auto-selected definition as the repository-wide target.
+3. `ucn show <handle>` gives the summary, callers and callees. Add `--sections=source,tests,types,dependencies,example,related` for more.
+4. Before a change: `ucn impact <handle>` and `ucn tests <handle> --depth=3`.
+5. After a signature change: `ucn check <handle>`; before committing: target-less `ucn check`. Both compare a changed declaration with its parameters at `--base` (default `HEAD`), so the call sites bound to the old declaration are checked against the new one; a site that fits no remaining overload is a mismatch, never an excluded other-target line.
+6. `ucn source <handle>` or `ucn source path/to/file:10-30` for exact code, only when inspection is needed.
 
 ## Choose a command
 
@@ -122,53 +45,57 @@ definition as an implicit repository-wide target.
 | Generate review candidates | `ucn deadcode`; `ucn audit-async` |
 | Resolve runtime frames | `ucn stacktrace <text>` |
 
-## In a shell, next to grep
+## Read the evidence
+
+Caller-bearing views (`show`, `impact`, `trace`, `tests`, `check`) tier every candidate:
+
+- `CONFIRMED`: binding, receiver, import, or ownership evidence for the pinned target.
+- `UNVERIFIED`: call syntax that may reach the target, with the reason identity could not be established. Review it before a breaking change. When same-name definitions compete, `show` lists their stable handles once above the sites.
+- Excluded sites (another definition's caller, an incompatible receiver, an external package, an arity mismatch) are counted as other-target lines in `ACCOUNT`, each with its reason in JSON.
+
+Trust lines close every answer and survive truncation:
+
+- `ACCOUNT` partitions every line where the name occurs: confirmed, unverified, non-call (definition, import, reference, other text), other-target, unaccounted. In mixed-language repositories it also counts occurrences in unsupported-language source files.
+- `CONTRACT` states what that partition covers. Semantic completeness is never claimed: aliases, generated code, reflection and runtime dispatch may exist.
+- `WARNING` lists unreadable, unparsed or partially indexed files and unsupported-language occurrence sites with their line text, so nothing text search would show is hidden. `usages` and `tests` carry the same disclosure as a note.
+- `FILTERED` means query options hid evidence. `CALLEE ACCOUNT` and `TREE ACCOUNT` do the same for callees and `trace` trees.
+
+A property/getter/setter target adds `PROPERTY ACCESS SITES` to `impact` (reads and writes with access kind; receiver identity confirms, an unresolved receiver stays unverified). A type target adds `TYPE REFERENCE SITES` (confirmed by an import link to the definition's file, or package scope in Go/Java). `DEPENDENCY SITES` counts them; `CALL SITES` stays call-shaped. Target-less `impact` and `check` diff the working tree against `HEAD` (`--staged` for the index), include untracked non-ignored source as whole-file additions, and put classes, interfaces, types and fields in declaration bands; a modified or deleted declaration makes `check` `BLOCKED` until reviewed with the language toolchain.
+
+Numeric evidence values are ordinal ranking weights, not probabilities. An observed-text zero is not a semantic zero or safe-delete proof.
+
+## In a shell
 
-`ucn` is a Bash tool as much as an MCP tool. Two flags make it compose like
-`grep -n` so a shell-first agent can keep its reflexes and still get symbol
-answers:
+`--lines` and `--raw` make `ucn` compose like `grep -n`:
 
 ```bash
 ucn find handleRequest --lines            # path:line:signature   # kind
 ucn show handleRequest --lines            # callers as path:line:text; unverified ones end in "\t# unverified: <reason>"
 ucn show handleRequest --lines --sections=callees
-ucn usages handleRequest --lines          # every literal-name occurrence; non-call kinds tagged "# import" / "# definition"
+ucn usages handleRequest --lines          # every literal-name line; kinds tagged "# import" / "# definition" / "# reference"
 ucn search 'retry(' --lines               # grep -n output, code-aware scope
 ucn impact handleRequest --lines
 ucn source handleRequest --raw            # the code and nothing else, ready for an exact-string edit
 ucn source src/server.js:40-80 --raw
 ```
 
-Records go to stdout; the `ACCOUNT` / `CONTRACT` lines, notes, and the
-same-name disambiguation go to stderr prefixed `# ` (MCP keeps them in the one
-text block, and `--raw` appends its note as one trailing `# ` line there).
-`usages --lines` emits one record per source line, combining occurrence kinds
-and disclosing repeated occurrences (including JSX open/close tags). JSON keeps
-the individual occurrence records. Definition handles start at decorators when
-present, while usages point at token lines (`nameLine` identifies the declaration
-token when it differs from `startLine`). Structural `search --unused` keeps its
-safety note and decorator tags in shell output; runtime registrations can appear
-and zero call edges do not prove a symbol is safe to delete.
-`--lines` lists the whole band without default row/character caps, so pipe through
-`grep -v '# unverified'` for the confirmed tier. To count distinct source lines
-per file, use `cut -d: -f1,2 | sort -u | cut -d: -f1 | sort | uniq -c`;
-JSON usage records can count a source line more than once.
-Nothing to list prints nothing and exits 1, grep's
-contract; errors exit 2. Explicit `--top`/`--limit` still apply and disclose
-omissions. `show --lines` accepts only callers/callees sections; target-less
-`impact --lines` lists Git-diff callers with per-target accounting. Closing a
-pipe with `head` is supported. `source --raw` extracts full large classes too;
-`--max-lines` truncation is disclosed on stderr. An explicit `--max-chars`
-fails before stdout if the complete shell output exceeds it. Unusual path
-characters (backslash/tab/CR/LF) are escaped; use JSON for exact filenames.
-`trace` and `tests` scripting uses `--json`. Use `grep` for literals, messages, configuration, and unsupported
-languages; use `ucn ... --lines` when the question is a symbol, a caller, or a
-definition, and `--raw` when the next step is an edit.
-
-Command errors exit 2 in ordinary text mode as well. CLI JSON preserves its
-own contract: successful empty results exit 0; command errors exit 1 with
-`meta.ok: false` and an `error` field. A target-less `check` exits 1 when
-`TRUST` is `BLOCKED`, 0 otherwise; a check that could not run exits 2.
+Records go to stdout; `ACCOUNT`/`CONTRACT`, notes and same-name disambiguation go to stderr as `# ` lines (MCP keeps them in the one text block; `--raw` appends its note as one trailing `# ` line there). `--lines` has no default row cap; explicit `--top`/`--limit` disclose what they omit; an explicit `--max-chars` fails before any output instead of truncating records. `grep -v '# unverified'` keeps the confirmed tier. `usages --lines` emits one record per source line and tags combined kinds; JSON keeps individual occurrences. `show --lines` accepts only the callers/callees sections (default callers); target-less `impact --lines` lists Git-diff callers with per-target accounting. `source --raw` extracts whole functions and large classes; `--max-lines` truncation is disclosed on stderr. Unusual path characters (backslash, tab, CR, LF) are escaped; use `--json` for exact filenames, and for `trace`/`tests` scripting. Closing the pipe with `head` is supported.
+
+Exit codes: 0 success; 1 for an empty `--lines` listing, a blocking `check` (target-less `check` with `TRUST: BLOCKED`, or `check <handle>` reporting a mismatch or an unverified call site), or a JSON command error (`meta.ok: false` plus `error`); 2 for a text-mode command error or a `check` that could not run. An exception inside UCN prints `Internal error: ...` on every surface (CLI JSON adds `meta.internalError: true`); it says nothing about the code, so rerun with a narrower target or report it.
+
+## Surfaces, JSON and output budgets
+
+CLI, MCP and interactive mode run the same 18 commands through one registry, the same handlers and the same formatters. CLI spells multiword commands with hyphens (`audit-async`), MCP uses snake case (`audit_async`) through one `ucn` tool. `--json` returns `{ meta, data }`: `meta.command` keeps the surface spelling and may add `canonicalCommand`, `meta.contract` carries the truth boundary, and public `file` paths are relative to `meta.pathBase`. Definition handles start at a decorator when present; `nameLine` is the declaration token's line.
+
+Text output has a character budget on both CLI and MCP: 3K for broad sweeps (`repo`, `entrypoints`, `endpoints`, `deadcode`, `deps`, `check`, `audit-async`), 10K for every other command, 100K ceiling (`--max-chars=N` / `max_chars`; `--all` lifts caps where a command supports it). Room for every trust line is reserved before any body text. A truncated answer keeps its head, a notice with the full size and the limit, and the trust lines; `show` and `impact` keep a head of every tier with a `+N more` line each, so a long confirmed list never hides the unverified band. A budget too small for the trust lines withholds the answer and names the budget that would carry them (`answer withheld; 0 of 3 trust line(s) shown. Raise --max-chars to at least 498.`). Narrow with a handle, `--file`, `--in` or `--sections` before raising the budget.
+
+## Index and discovery
+
+Indexes live in a per-user, project-keyed cache outside the repository (`UCN_CACHE_DIR` overrides the root; `--no-cache` bypasses it; `--clear-cache` removes the project's cache; a `.ucn-cache` directory left in a project is migrated on first use). MCP keeps the process and index warm across calls. Concurrent cold starts share one build: the first process takes a build lock and the others wait for its cache (`Waiting for another ucn process building the index...` on stderr); a lock left by a dead process is broken automatically.
+
+Discovery applies the project's `.gitignore` files (root and nested) with git's own matching rules; git-tracked files are indexed even when a rule matches them, and a failing `git ls-files` is disclosed as a partial index (`git-listing-failed` in `repo --sections=health` and in caller contracts), never a silently smaller one. `*.min.js`, `*.bundle.js` and `*.map` are skipped and disclosed, which makes observed-text completeness partial; `--include-bundled` (MCP `include_bundled=true`) indexes the JavaScript bundles, respecting user exclusions and bypassing the shared cache. Source maps stay unindexed; inspect them with text tools.
+
+C/C++ uses `compile_commands.json` when present for header classification and include paths. Project C/C++ function-like macros and Rust `macro_rules!` invocations are expanded, and what they generate is indexed at the invocation (`[via macro NAME]`). This is portable AST analysis, not a compiler build: macros, templates, generated code, reflection and external dependency semantics can stay unverified, and no conditional branch is asserted as the one a build activates.
 
 ## Breaking-change protocol
 
@@ -182,94 +109,7 @@ own contract: successful empty results exit 0; command errors exit 1 with
 
 ## Deletion protocol
 
-Treat `deadcode` as a candidate generator. Before deletion, inspect `usages`, `impact`, `entrypoints`, `api`, and `repo --sections=health --deep`; then corroborate with the compiler/type checker and tests. Computed dispatch such as `handlers[key]()` is a reported blind spot; registry members reached by a modeled computed receiver are withheld. Statically named reflection such as `getattr(obj, "run")` is positive liveness evidence, so every matching member spelling is withheld; recognized dynamic reflection is counted and warned because it cannot be attributed to one member. Unknown decorators/annotations and member-assigned event handlers are also withheld by default because they can be the registration itself. All remaining candidates are still review-only. Never delete solely from `deadcode` or an observed-text-zero result.
-
-`usages` includes comment/string/docstring occurrences and non-code text
-(JSX children, HTML markup and attributes) in an `OTHER TEXT` section unless
-`--code-only` is set, so it lists every line the `ACCOUNT` counts. This is a
-literal-name inventory, not exact target binding. Identifier boundaries are
-Unicode-aware and match `grep -w`: `hit` never matches inside `hitΔ`, while
-`$` is a boundary (`buy${...}`, `$fail`, `ws$close()` all count).
-
-Aliased and qualified calls resolve in every language: Rust `use m::f as g; g()`
-is a caller of `f` (listed as a beyond-text caller, since the line holds no
-target token); Java `pkg.Type.method()` and C# `Ns.Type.Method()` /
-`using T = Ns.Type; T.Method()` pick the type the qualifier names when several
-same-name types exist. A qualifier the resolver cannot place stays visible as
-`method-ambiguous`, never confirmed by first-definition order.
-
-`endpoints` labels test routes and requests with `[test]` (JSON `isTest`).
-Use `--exclude-tests` for a production inventory or `--in=api/` for a directory.
-
-`endpoints` recognizes client receivers by evidence (a receiver typed to an
-HTTP client class, or bound to a pytest fixture that constructs one), not only
-by name. Request-shaped calls with a path literal on an unrecognized receiver
-are listed under `Possible client requests` (JSON `uncertainRequests`),
-counted in `meta`, never in the inventory. `search` treats its term literally by default; pass `--regex` only
-when regular-expression semantics are intended. Ordinary regex patterns run
-through an RE2-compatible linear-time engine; unsafe nested repetition is
-rejected, and unsupported advanced syntax should be handed to ripgrep.
-
-`find` activity counts are definition-pinned: confirmed plus visible unverified
-call candidates. Calls proved to belong to another same-name target are
-disclosed separately and excluded from the activity total.
-Broad queries rank candidates by inexpensive approximate usage totals before
-applying the row limit; only returned definitions receive caller adjudication.
-The selection note discloses that approximation. `find`, text `search`,
-`deadcode`, `api`, and `repo --sections=files` default to at most 500 results
-(structural `search`: 50). Use an explicit `--limit=N` to request more;
-`usages` and `--lines` have no default row cap.
-
-Automatic test filtering follows the language's conventions: Python `spec.py`
-and `chart_spec.py` are production paths; `test_*.py`, `*_test.py`, and test
-directories remain test paths. Structural search discloses hidden test files,
-including empty results; `--include-tests` gives the full indexed inventory.
-Explicit `--exclude=spec` still means the requested path exclusion.
-
-Public JSON source `file` fields are relative to `meta.pathBase` (the absolute
-project root). Dependency edge paths use the same base. Both absolute and
-relative indexed-file handles are accepted. Definition handles retain their
-decorator span; use `nameLine` for the name token rather than joining usages
-to a handle's start line.
-
-Callable references passed to another function remain visible when a project
-method or function could be their target. An ordinary attribute read with no
-callable member candidate stays a non-call reference in ACCOUNT and `usages`.
-The caller model includes callback dependencies; it does not prove that the
-receiving function invokes every passed callable.
-
-`audit-async` checks recognized async producers. In JS/TS/HTML it also checks
-captured promises used in arithmetic, conditions, or resolved-value member
-access within the same lexical scope. Awaiting, returning, promise handlers,
-reassignment, and shadowed bindings are distinguished. It is a bounded AST
-audit, not a compiler-wide proof that every missing await has been found.
-
-For `plan --rename-to`, the selected declaration is only the starting point.
-When the index proves the relationship, the rename unit closes over
-overload/signature groups, base and override declarations, Rust trait slots,
-Go interface slots and their satisfiers, exact call and value-reference tokens,
-imports/exports, Python `__all__` strings, and module-attribute references.
-Exact token/expression spans keep a foreign same-named occurrence on the same
-line unchanged. Open external interfaces, incomplete ownership, unresolved
-dispatch, or an inexact token route to `needsReview` instead of a synthesized
-edit. Comment/string occurrences in indexed source appear in `reviewItems` and
-are never rewritten automatically; the result also tells you to search
-documentation, configuration, generated files, and unsupported languages for
-the old spelling. Read `changeSummary` and every review item. `plan` previews
-only: it does not modify files, run a compiler, or prove runtime compatibility.
-
-For `deps --cycles`, `eager` means every edge executes at module scope.
-`deferred` means at least one edge does not: a function-local import (Python
-`def`/`lambda` bodies; JS/TS `require()`/`import()` inside any function,
-including `() => require()` thunks), a Python `if TYPE_CHECKING:` import, or a
-TypeScript type-only import. Each deferred edge names its reason. A deferred
-chain is not an unconditional import-time cycle; function-local chains stay
-visible because invoking that function during initialization can still matter.
-Cycles are enumerated completely and independently of build history (capped at
-500 with a disclosed truncation; groups above 2000 files skip enumeration);
-`CYCLE GROUPS` and the files-in-cycles count remain complete even when the
-enumerated cycle counts are lower bounds. `CYCLE GROUPS` lists each strongly connected
-file set, the unit a refactor has to break.
+`deadcode` is a candidate generator, never deletion proof. Before deleting, inspect `usages`, `impact`, `entrypoints`, `api`, and `repo --sections=health --deep`, then corroborate with the compiler/type checker and tests. Members that reflection (exact names or literal-fragment patterns), computed dispatch, runtime protocols (Python dunders, Java serialization callbacks, C# pattern members, JS `toJSON`/`then`), unknown decorators, event-handler assignment, an outside base class, or macro expansion may reach are withheld or warned; the `deadcode` notes in the command reference list them. Never delete solely from `deadcode` or an observed-text-zero result.
 
 ## Efficient use
 
@@ -279,26 +119,8 @@ file set, the unit a refactor has to break.
 - Use `--all` only when that command's output reports a supported cap; otherwise narrow the query or raise `--max-chars`.
 - Use `search` or ordinary repository search for text, filenames, configuration, and unsupported syntax.
 
-Read [references/commands.md](references/commands.md) for all public commands and flags. Read [references/trust-contract.md](references/trust-contract.md) before building automation that gates changes on UCN output.
-
-
-### Inspect confirmation provenance
-
-Caller and callee JSON carries compact `provenance`: `rule`, contributing `rules`
-when there is more than one, `validation`, and the receiver's source and origin
-line when recorded. Incomplete proofs include a `diagnostic`, also shown in text.
-Callees retain compact `siteProvenance` for each distinct occurrence; their summary
-uses the weakest confirmed site's rule. Exclusions expose counts by rule and
-validation under `account.excluded.evidenceSummary`. Full declaration, import,
-and member-lookup facts remain on engine results and in oracle reports.
-
-A lone project owner of a method name does not identify an untyped receiver.
-Such candidates stay unverified with `single-owner`; importing the class does not
-change that. `provenance-incomplete` means the available facts cannot establish
-this declaration. Inspect the site and diagnostic before editing it. Neither
-reason is permission to discard a possible caller. `validation: unsupported`
-means the witness collector does not yet cover that path (for example a wildcard
-re-export or an external inherited member). Its existing classification is kept
-in report-only mode; it is not a validated proof. Missing or inconsistent facts
-on a supported lookup still route unverified. Full rule migration is tracked as
-#356. Ordinal evidence weights are not probabilities.
+## References
+
+- [references/commands.md](references/commands.md): every command, flag and default, exit codes, and per-command notes (`find` activity counts, `usages` inventory, `plan` rename closure, `endpoints` matching, `deadcode` withholding, `audit-async` findings, `deps --cycles`).
+- [references/trust-contract.md](references/trust-contract.md): evidence classes, trust lines, account fields, provenance, truncation metadata, and a machine policy for automation that gates changes on UCN output.
+- [references/resolution-rules.md](references/resolution-rules.md): how UCN decides identity per language (what confirms, what stays unverified with which reason, what is excluded).