ucn 3.7.2 → 3.7.4

package/README.md

@@ -1,12 +1,40 @@
 # UCN - Universal Code Navigator
 
-UCN is designed to work with large files and codebases, helping AI agents ingest exactly the data they need. Its surgical output discourages agents from cutting corners, and without UCN, agents working with large codebases tend to skip parts of the code structure, assuming they have "enough data."
+UCN gives AI agents call-graph-level understanding of code. Instead of reading entire files, agents ask structural questions like: "who calls this function", "what breaks if I change it", "what's unused", and get precise, AST-verified answers. UCN parses JS/TS, Python, Go, Rust, Java, and HTML inline scripts with tree-sitter, then exposes 28 navigation commands as a CLI tool, MCP server, or agent skill.
 
-Supported languages: JS/TS, Python, Go, Rust, Java. Also parses HTML files (inline scripts and event handlers).
+Designed for large codebases where agents waste context on reading large files. UCN's surgical output means agents spend tokens on reasoning, not on ingesting thousands of lines to find three callers, discourages agents from cutting corners, as without UCN, agents working with large codebases tend to skip parts of the code structure, assuming they have "enough data".
+
+Everything runs locally on your machine and nothing leaves your project.
 
 ---
 
-## Three Ways to Use UCN
+## What UCN does
+
+Precise answers without reading files.
+
+```
+  TASK                                    COMMAND
+  ─────────────────────                   ─────────────────────
+
+  Pull one function from                  $ ucn fn handleRequest
+  a 2000-line file                        → 20 lines, just that function
+
+  Who calls this? Will they               $ ucn impact handleRequest
+  break if I change it?                   → 8 call sites, with arguments
+
+  What happens when                       $ ucn trace main --depth=3
+  main() runs?                            → full call tree, no file reads
+
+  What can I safely delete?               $ ucn deadcode
+                                          → unused functions, AST-verified
+
+  What depends on this file               $ ucn graph src/routes.ts
+  before I move it?                       → imports and importers tree
+```
+
+---
+
+## Three Ways to it: ucn mcp, ucn skill, ucn cli
 
 ```
   ┌──────────────────────────────────────────────────────────────────────┐
@@ -15,7 +43,7 @@ Supported languages: JS/TS, Python, Go, Rust, Java. Also parses HTML files (inli
   │      $ ucn about myFunc     Works standalone, no agent required.     │
   │                                                                      │
   │   2. MCP Server             Any MCP-compatible AI agent connects     │
-  │      $ ucn --mcp            and gets 28 tools automatically.         │
+  │      $ ucn --mcp            and gets 28 commands automatically.         │
   │                                                                      │
   │   3. Agent Skill            Drop-in skill for Claude Code and        │
   │      /ucn about myFunc      OpenAI Codex CLI. No server needed.      │
@@ -25,9 +53,9 @@ Supported languages: JS/TS, Python, Go, Rust, Java. Also parses HTML files (inli
 
 ---
 
-## The Problem
+## How agents understand code today
 
-Typically, AI agents working with code do something like this:
+AI agents working with code typically do this:
 
 ```
   grep "functionName"      →  47 matches, 23 files
@@ -53,28 +81,7 @@ Typically, AI agents working with code do something like this:
 
 ---
 
-## The Solution
-
-UCN parses the code with tree-sitter and offers semantic navigation tools.
-
-Instead of reading entire files, ask precise questions:
-
-```
-  ┌──────────────────────────────────────┐
-  │                                      │
-  │   "Who calls this function?"         │──→  list of actual callers
-  │                                      │
-  │   "What breaks if I change this?"    │──→  every call site, with arguments
-  │                                      │
-  │   "Show me this function and         │──→  source + dependencies inline
-  │    everything it depends on"         │
-  │                                      │
-  └──────────────────────────────────────┘
-```
-
----
-
-## How It Works
+## How UCN works: tree-sitter, locally
 
 ```
   ┌──────────────────────────────────────────────┐
@@ -87,29 +94,27 @@ Instead of reading entire files, ask precise questions:
                           ▼
                  ┌───────────────────┐
                  │   UCN MCP Server  │
-                 │   28 tools        │
+                 │   28 commands     │
                  │   runs locally    │
                  └────────┬──────────┘
                           │
                     tree-sitter AST
                           │
-      ┌───────────────────┴─────────────────┐
-      │          Supported Languages        │
-      │ JS/TS, Python, Go, Rust, Java, HTML │
-      └─────────────────────────────────────┘
+        ┌─────────────────┴───────────────────┐
+        │          Supported Languages        │
+        │ JS/TS, Python, Go, Rust, Java, HTML │
+        └─────────────────────────────────────┘
 ```
 
-No cloud. No API keys. Parses locally, stays local.
-
 ---
 
-## Before & After
+## Before and after UCN
 
 ```
   WITHOUT UCN                              WITH UCN
   ──────────────────────                   ──────────────────────
 
-  grep "processOrder"                      ucn_impact "processOrder"
+  grep "processOrder"                      ucn impact "processOrder"
        │                                        │
        ▼                                        ▼
   34 matches, mostly noise                 8 call sites, grouped by file,
@@ -118,7 +123,7 @@ No cloud. No API keys. Parses locally, stays local.
   read service.ts  (800 lines)                  │
        │                                        │
        ▼                                        │
-  read handler.ts  (600 lines)             ucn_smart "processOrder"
+  read handler.ts  (600 lines)             ucn smart "processOrder"
        │                                        │
        ▼                                        ▼
   read batch.ts    (400 lines)             function + all dependencies
@@ -141,13 +146,13 @@ No cloud. No API keys. Parses locally, stays local.
   Context spent on file contents           Context spent on reasoning
 ```
 
-After editing code:
+After editing code, before committing:
 
 ```
   WITHOUT UCN                              WITH UCN
   ──────────────────────                   ──────────────────────
 
-  git diff                                 ucn_diff_impact
+  git diff                                 ucn diff_impact
        │                                        │
        ▼                                        ▼
   see changed lines, but which             13 modified functions
@@ -158,7 +163,7 @@ After editing code:
   to function boundaries                   Each function shown with:
        │                                     • which lines changed
        ▼                                     • every downstream caller
-  ucn_impact on each function                • caller context
+  ucn impact on each function                • caller context
   you identified (repeat 5-10x)                 │
        │                                        ▼
        ▼                                   Done. Full blast radius.
@@ -170,7 +175,7 @@ After editing code:
 
 ---
 
-## grep vs AST
+## Text search vs AST
 
 ```
   Code: processOrder(items, user)
@@ -190,7 +195,7 @@ After editing code:
 
 
   ┌─────────────────────────────────────────────────────────────────┐
-  │  ucn_context "processOrder"                                     │
+  │  ucn context "processOrder"                                     │
   │                                                                 │
   │    Callers:                                                     │
   │      handleCheckout    src/api/checkout.ts:45                   │
@@ -206,11 +211,11 @@ After editing code:
   └─────────────────────────────────────────────────────────────────┘
 ```
 
-The tradeoff: grep works on any language and any text. UCN only works on supported languages but gives structural understanding within those.
+The tradeoff: text search works on any language and any text. UCN only works on 5 languages + HTML, but gives structural understanding within those.
 
 ---
 
-## See It in Action
+## UCN commands in action
 
 Extract a function from a large file without reading it:
 
@@ -461,7 +466,7 @@ ucn --interactive                   # Multiple queries, index stays in memory
 
 ---
 
-## Workflows
+## UCN workflows
 
 Investigating a bug:
 ```bash
@@ -492,7 +497,7 @@ ucn toc                                   # Project overview
 
 ---
 
-## Limitations (and how we handle them)
+## Limitations
 
 ```
   ┌──────────────────────────┬──────────────────────────────────────────┐
@@ -500,8 +505,9 @@ ucn toc                                   # Project overview
   ├──────────────────────────┼──────────────────────────────────────────┤
   │                          │                                          │
   │  5 languages + HTML      │  JS/TS, Python, Go, Rust, Java.          │
-  │  (no C, Ruby, PHP, etc.) │  Agents fall back to grep for the rest.  │
-  │                          │  UCN complements, doesn't replace.       │
+  │  (no C, Ruby, PHP, etc.) │  Agents fall back to text search for     │
+  │                          │  the rest. UCN complements, doesn't      │
+  │                          │  replace.                                │
   │                          │                                          │
   ├──────────────────────────┼──────────────────────────────────────────┤
   │                          │                                          │
@@ -535,38 +541,40 @@ ucn toc                                   # Project overview
 
 ---
 
-## All 28 Tools
+## All 28 Commands
+
+All commands are accessible through a single `ucn` MCP tool with a `command` parameter.
 
 ```
   UNDERSTAND                          MODIFY SAFELY
   ─────────────────────               ─────────────────────
-  ucn_about     everything in one     ucn_impact      all call sites
+  about         everything in one     impact          all call sites
                 call: definition,                     with arguments
                 callers, callees,
-                tests, source         ucn_diff_impact what changed in a
+                tests, source         diff_impact     what changed in a
                                                       git diff + who
-  ucn_context   callers + callees                     calls it
+  context       callers + callees                     calls it
                 (quick overview)
-                                      ucn_verify      check all sites
-  ucn_smart     function + helpers                    match signature
+                                      verify          check all sites
+  smart         function + helpers                    match signature
                 expanded inline
-                                      ucn_plan        preview a refactor
-  ucn_trace     call tree — map                       before doing it
+                                      plan            preview a refactor
+  trace         call tree — map                       before doing it
                 a whole pipeline
 
 
   FIND & NAVIGATE                     ARCHITECTURE
   ─────────────────────               ─────────────────────
-  ucn_find      locate definitions    ucn_imports     file dependencies
-  ucn_usages    all occurrences       ucn_exporters   who depends on it
-  ucn_fn        extract a function    ucn_graph       dependency tree
-  ucn_class     extract a class       ucn_related     sibling functions
-  ucn_toc       project overview      ucn_tests       find tests
-  ucn_deadcode  unused functions      ucn_stacktrace  error trace context
-  ucn_search    text search           ucn_api         public API surface
-  ucn_example   best usage example    ucn_typedef     type definitions
-  ucn_lines     extract line range    ucn_file_exports file's exports
-  ucn_expand    drill into context    ucn_stats       project size stats
+  find          locate definitions    imports         file dependencies
+  usages        all occurrences       exporters       who depends on it
+  fn            extract a function    graph           dependency tree
+  class         extract a class       related         sibling functions
+  toc           project overview      tests           find tests
+  deadcode      unused functions      stacktrace      error trace context
+  search        text search           api             public API surface
+  example       best usage example    typedef         type definitions
+  lines         extract line range    file_exports    file's exports
+  expand        drill into context    stats           project size stats
 ```
 
 ---

package/core/output.js

@@ -829,7 +829,7 @@ function formatRelated(related, options = {}) {
     // Same file
     let relatedTruncated = false;
     if (related.sameFile.length > 0) {
-        const maxSameFile = options.showAll ? Infinity : 8;
+        const maxSameFile = options.top || (options.showAll ? Infinity : 8);
         lines.push(`SAME FILE (${related.sameFile.length}):`);
         for (const f of related.sameFile.slice(0, maxSameFile)) {
             const params = f.params ? `(${f.params})` : '';

package/core/project.js

@@ -2188,18 +2188,12 @@ class ProjectIndex {
      * @returns {Array} Imports with resolved paths
      */
     imports(filePath) {
-        const normalizedPath = path.isAbsolute(filePath)
-            ? filePath
-            : path.join(this.root, filePath);
+        const resolved = this.resolveFilePathForQuery(filePath);
+        if (typeof resolved !== 'string') return resolved;
 
+        const normalizedPath = resolved;
         const fileEntry = this.files.get(normalizedPath);
         if (!fileEntry) {
-            // Try to find by relative path
-            for (const [absPath, entry] of this.files) {
-                if (entry.relativePath === filePath || absPath.endsWith(filePath)) {
-                    return this.imports(absPath);
-                }
-            }
             return { error: 'file-not-found', filePath };
         }
 
@@ -2275,24 +2269,10 @@ class ProjectIndex {
      * @returns {Array} Files that import this file
      */
     exporters(filePath) {
-        const normalizedPath = path.isAbsolute(filePath)
-            ? filePath
-            : path.join(this.root, filePath);
-
-        // Try to find the file
-        let targetPath = normalizedPath;
-        if (!this.files.has(normalizedPath)) {
-            for (const [absPath, entry] of this.files) {
-                if (entry.relativePath === filePath || absPath.endsWith(filePath)) {
-                    targetPath = absPath;
-                    break;
-                }
-            }
-        }
+        const resolved = this.resolveFilePathForQuery(filePath);
+        if (typeof resolved !== 'string') return resolved;
 
-        if (!this.files.has(targetPath)) {
-            return { error: 'file-not-found', filePath };
-        }
+        const targetPath = resolved;
 
         const importers = this.exportGraph.get(targetPath) || [];
 
@@ -2432,7 +2412,18 @@ class ProjectIndex {
     api(filePath, options = {}) {
         const results = [];
 
-        for (const [absPath, fileEntry] of (filePath ? [[this.findFile(filePath), this.files.get(this.findFile(filePath))]] : this.files.entries())) {
+        let fileIterator;
+        if (filePath) {
+            const resolved = this.resolveFilePathForQuery(filePath);
+            if (typeof resolved !== 'string') return resolved;
+            const fileEntry = this.files.get(resolved);
+            if (!fileEntry) return { error: 'file-not-found', filePath };
+            fileIterator = [[resolved, fileEntry]];
+        } else {
+            fileIterator = this.files.entries();
+        }
+
+        for (const [absPath, fileEntry] of fileIterator) {
             if (!fileEntry) continue;
 
             // Skip test files by default (test classes aren't part of public API)
@@ -2487,9 +2478,12 @@ class ProjectIndex {
     }
 
     /**
-     * Find a file by path (supports partial paths)
+     * Resolve a file path query to an indexed file (with ambiguity detection)
+     * @param {string} filePath - File path to resolve
+     * @returns {string|{error: string, filePath: string, candidates?: string[]}}
      */
-    findFile(filePath) {
+    resolveFilePathForQuery(filePath) {
+        // 1. Exact absolute/relative path match
         const normalizedPath = path.isAbsolute(filePath)
             ? filePath
             : path.join(this.root, filePath);
@@ -2498,13 +2492,34 @@ class ProjectIndex {
             return normalizedPath;
         }
 
-        // Try partial match
+        // 2. Collect ALL suffix/partial candidates
+        const candidates = [];
         for (const [absPath, entry] of this.files) {
-            if (entry.relativePath === filePath || absPath.endsWith(filePath)) {
-                return absPath;
+            if (entry.relativePath === filePath || absPath.endsWith('/' + filePath)) {
+                candidates.push(absPath);
             }
         }
 
+        if (candidates.length === 0) {
+            return { error: 'file-not-found', filePath };
+        }
+        if (candidates.length === 1) {
+            return candidates[0];
+        }
+        return {
+            error: 'file-ambiguous',
+            filePath,
+            candidates: candidates.map(c => this.files.get(c)?.relativePath || path.relative(this.root, c))
+        };
+    }
+
+    /**
+     * Find a file by path (supports partial paths)
+     * Backward-compatible wrapper — returns null on error.
+     */
+    findFile(filePath) {
+        const result = this.resolveFilePathForQuery(filePath);
+        if (typeof result === 'string') return result;
         return null;
     }
 
@@ -2514,11 +2529,10 @@ class ProjectIndex {
      * @returns {Array} Exported symbols from that file
      */
     fileExports(filePath) {
-        const absPath = this.findFile(filePath);
-        if (!absPath) {
-            return { error: 'file-not-found', filePath };
-        }
+        const resolved = this.resolveFilePathForQuery(filePath);
+        if (typeof resolved !== 'string') return resolved;
 
+        const absPath = resolved;
         const fileEntry = this.files.get(absPath);
         if (!fileEntry) {
             return [];
@@ -2960,24 +2974,10 @@ class ProjectIndex {
         const rawDepth = options.maxDepth ?? 5;
         const maxDepth = Math.max(0, rawDepth);
 
-        const absPath = path.isAbsolute(filePath)
-            ? filePath
-            : path.resolve(this.root, filePath);
-
-        // Try to find file if not exact match
-        let targetPath = absPath;
-        if (!this.files.has(absPath)) {
-            for (const [p, entry] of this.files) {
-                if (entry.relativePath === filePath || p.endsWith(filePath)) {
-                    targetPath = p;
-                    break;
-                }
-            }
-        }
+        const resolved = this.resolveFilePathForQuery(filePath);
+        if (typeof resolved !== 'string') return resolved;
 
-        if (!this.files.has(targetPath)) {
-            return { error: 'file-not-found', filePath };
-        }
+        const targetPath = resolved;
 
         const buildSubgraph = (dir) => {
             const visited = new Set();
@@ -3176,7 +3176,8 @@ class ProjectIndex {
         }
         // Sort by number of shared parts
         related.similarNames.sort((a, b) => b.sharedParts.length - a.sharedParts.length);
-        if (!options.all) related.similarNames = related.similarNames.slice(0, 10);
+        const similarLimit = options.top || (options.all ? Infinity : 10);
+        if (related.similarNames.length > similarLimit) related.similarNames = related.similarNames.slice(0, similarLimit);
 
         // 3. Shared callers - functions called by the same callers
         const myCallers = new Set(this.findCallers(name).map(c => c.callerName).filter(Boolean));
@@ -3194,7 +3195,7 @@ class ProjectIndex {
                 }
             }
             // Sort by shared caller count
-            const maxShared = options.all ? Infinity : 5;
+            const maxShared = options.top || (options.all ? Infinity : 5);
             const sorted = Array.from(callerCounts.entries())
                 .sort((a, b) => b[1] - a[1])
                 .slice(0, maxShared);
@@ -3230,7 +3231,7 @@ class ProjectIndex {
                 // Sort by shared callee count
                 const sorted = Array.from(calleeCounts.entries())
                     .sort((a, b) => b[1] - a[1])
-                    .slice(0, options.all ? Infinity : 5);
+                    .slice(0, options.top || (options.all ? Infinity : 5));
                 for (const [symName, count] of sorted) {
                     const sym = this.symbols.get(symName)?.[0];
                     if (sym) {

package/mcp/server.js

@@ -371,9 +371,10 @@ server.registerTool(
                 const err = requireName(name);
                 if (err) return err;
                 const index = getIndex(project_dir);
-                const result = index.related(name, { file, all: top !== undefined });
+                const result = index.related(name, { file, top, all: top !== undefined });
                 return toolResult(output.formatRelated(result, {
                     showAll: top !== undefined,
+                    top,
                     allHint: 'Repeat with top set higher to show all.'
                 }));
             }
@@ -499,6 +500,10 @@ server.registerTool(
                     note = `Note: Found ${matches.length} definitions for "${name}". Showing ${match.relativePath}:${match.startLine}. Use file parameter to disambiguate.\n\n`;
                 }
 
+                if (max_lines !== undefined && (!Number.isInteger(max_lines) || max_lines < 1)) {
+                    return toolError(`Invalid max_lines: ${max_lines}. Must be a positive integer.`);
+                }
+
                 const classLineCount = match.endLine - match.startLine + 1;
 
                 // Large class: show summary by default, truncated source with max_lines
@@ -537,10 +542,14 @@ server.registerTool(
                     return toolError('Line range is required (e.g. "10-20" or "15").');
                 }
                 const index = getIndex(project_dir);
-                const filePath = index.findFile(file);
-                if (!filePath) {
+                const resolved = index.resolveFilePathForQuery(file);
+                if (typeof resolved !== 'string') {
+                    if (resolved.error === 'file-ambiguous') {
+                        return toolError(`Ambiguous file "${file}". Candidates:\n${resolved.candidates.map(c => '  ' + c).join('\n')}`);
+                    }
                     return toolError(`File not found: ${file}`);
                 }
+                const filePath = resolved;
 
                 const parts = range.split('-');
                 const start = parseInt(parts[0], 10);
@@ -552,12 +561,18 @@ server.registerTool(
                 if (start < 1) {
                     return toolError(`Invalid start line: ${start}. Line numbers must be >= 1`);
                 }
+                if (end < 1) {
+                    return toolError(`Invalid end line: ${end}. Line numbers must be >= 1`);
+                }
+                if (end < start) {
+                    return toolError(`Invalid range: end line (${end}) must be >= start line (${start})`);
+                }
 
                 const content = fs.readFileSync(filePath, 'utf-8');
                 const fileLines = content.split('\n');
 
-                const startLine = Math.min(start, end);
-                const endLine = Math.max(start, end);
+                const startLine = start;
+                const endLine = end;
 
                 if (startLine > fileLines.length) {
                     return toolError(`Line ${startLine} is out of bounds. File has ${fileLines.length} lines.`);
@@ -645,6 +660,7 @@ server.registerTool(
                 const index = getIndex(project_dir);
                 const result = index.imports(file);
                 if (result?.error === 'file-not-found') return toolError(`File not found in project: ${file}`);
+                if (result?.error === 'file-ambiguous') return toolError(`Ambiguous file "${file}". Candidates:\n${result.candidates.map(c => '  ' + c).join('\n')}`);
                 return toolResult(output.formatImports(result, file));
             }
 
@@ -655,6 +671,7 @@ server.registerTool(
                 const index = getIndex(project_dir);
                 const result = index.exporters(file);
                 if (result?.error === 'file-not-found') return toolError(`File not found in project: ${file}`);
+                if (result?.error === 'file-ambiguous') return toolError(`Ambiguous file "${file}". Candidates:\n${result.candidates.map(c => '  ' + c).join('\n')}`);
                 return toolResult(output.formatExporters(result, file));
             }
 
@@ -665,6 +682,7 @@ server.registerTool(
                 const index = getIndex(project_dir);
                 const result = index.fileExports(file);
                 if (result?.error === 'file-not-found') return toolError(`File not found in project: ${file}`);
+                if (result?.error === 'file-ambiguous') return toolError(`Ambiguous file "${file}". Candidates:\n${result.candidates.map(c => '  ' + c).join('\n')}`);
                 return toolResult(output.formatFileExports(result, file));
             }
 
@@ -675,6 +693,7 @@ server.registerTool(
                 const index = getIndex(project_dir);
                 const result = index.graph(file, { direction: direction || 'both', maxDepth: depth ?? 2 });
                 if (result?.error === 'file-not-found') return toolError(`File not found in project: ${file}`);
+                if (result?.error === 'file-ambiguous') return toolError(`Ambiguous file "${file}". Candidates:\n${result.candidates.map(c => '  ' + c).join('\n')}`);
                 return toolResult(output.formatGraph(result, {
                     showAll: depth !== undefined,
                     file,
@@ -745,8 +764,10 @@ server.registerTool(
 
             case 'api': {
                 const index = getIndex(project_dir);
-                const symbols = index.api(file || undefined);
-                return toolResult(output.formatApi(symbols, file || '.'));
+                const result = index.api(file || undefined);
+                if (result?.error === 'file-not-found') return toolError(`File not found in project: ${file}`);
+                if (result?.error === 'file-ambiguous') return toolError(`Ambiguous file "${file}". Candidates:\n${result.candidates.map(c => '  ' + c).join('\n')}`);
+                return toolResult(output.formatApi(result, file || '.'));
             }
 
             case 'stats': {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "ucn",
-  "version": "3.7.2",
-  "description": "Universal Code Navigator — function relationships, call trees, and impact analysis across large codebases without reading entire files.",
+  "version": "3.7.4",
+  "description": "Universal Code Navigator — AST-based call graph analysis for AI agents. Find callers, trace impact, detect dead code across JS/TS, Python, Go, Rust, Java, and HTML. CLI, MCP server, and agent skill.",
   "main": "index.js",
   "bin": {
     "ucn": "cli/index.js",
@@ -11,19 +11,31 @@
     "test": "node --test test/parser.test.js test/accuracy.test.js test/systematic-test.js test/mcp-edge-cases.js"
   },
   "keywords": [
+    "mcp",
+    "mcp-server",
+    "model-context-protocol",
     "code-navigation",
+    "code-analysis",
+    "static-analysis",
+    "call-graph",
+    "callers",
+    "impact-analysis",
+    "dead-code",
+    "deadcode",
     "ast",
-    "parser",
     "tree-sitter",
+    "parser",
+    "skill",
+    "agent-skill",
+    "cli",
+    "ai-agent",
     "javascript",
     "typescript",
     "python",
     "go",
     "rust",
     "java",
-    "html",
-    "ai",
-    "agent"
+    "html"
   ],
   "author": "Constantin-Mihail Leoca (https://github.com/mleoca)",
   "repository": {

package/test/mcp-edge-cases.js

@@ -358,6 +358,59 @@ const tests = [
         desc: 'lines - extract lines 1-5 from discovery.js',
         args: { command: 'lines', project_dir: PROJECT_DIR, file: 'core/discovery.js', range: '1-5' }
     },
+
+    // ========================================================================
+    // Correctness Assertions
+    // ========================================================================
+    {
+        category: 'Correctness',
+        tool: 'ucn',
+        desc: 'api(file=nonexistent) returns isError',
+        args: { command: 'api', project_dir: PROJECT_DIR, file: 'nonexistent/path/to/file.js' },
+        assert: (res, text, isError) => isError === true || 'Expected isError: true for nonexistent file'
+    },
+    {
+        category: 'Correctness',
+        tool: 'ucn',
+        desc: 'api(file=nonexistent) message contains "not found"',
+        args: { command: 'api', project_dir: PROJECT_DIR, file: 'nonexistent.js' },
+        assert: (res, text, isError) => (isError && /not found/i.test(text)) || 'Expected file-not-found error message'
+    },
+    {
+        category: 'Correctness',
+        tool: 'ucn',
+        desc: 'lines(range="5-0") returns validation error',
+        args: { command: 'lines', project_dir: PROJECT_DIR, file: 'core/discovery.js', range: '5-0' },
+        assert: (res, text, isError) => isError === true || 'Expected isError: true for invalid range'
+    },
+    {
+        category: 'Correctness',
+        tool: 'ucn',
+        desc: 'class(max_lines=-1) returns validation error',
+        args: { command: 'class', project_dir: PROJECT_DIR, name: 'ProjectIndex', max_lines: -1 },
+        assert: (res, text, isError) => isError === true || 'Expected isError: true for negative max_lines'
+    },
+    {
+        category: 'Correctness',
+        tool: 'ucn',
+        desc: 'lines - unique partial file resolves successfully',
+        args: { command: 'lines', project_dir: PROJECT_DIR, file: 'core/discovery.js', range: '1-3' },
+        assert: (res, text, isError) => isError === false || 'Expected success for unique partial file'
+    },
+    {
+        category: 'Correctness',
+        tool: 'ucn',
+        desc: 'file_exports(file=utils.js) returns ambiguity error',
+        args: { command: 'file_exports', project_dir: PROJECT_DIR, file: 'utils.js' },
+        assert: (res, text, isError) => (isError && /ambiguous/i.test(text)) || 'Expected file-ambiguous error for utils.js'
+    },
+    {
+        category: 'Correctness',
+        tool: 'ucn',
+        desc: 'imports(file=utils.js) returns ambiguity error',
+        args: { command: 'imports', project_dir: PROJECT_DIR, file: 'utils.js' },
+        assert: (res, text, isError) => (isError && /ambiguous/i.test(text)) || 'Expected file-ambiguous error for utils.js'
+    },
 ];
 
 // ============================================================================
@@ -406,6 +459,15 @@ async function run() {
                 const preview = text.substring(0, 120).replace(/\n/g, '\\n');
                 status = 'PASS';
                 detail = `${isError ? 'ERROR response' : 'OK'}: "${preview}" (${elapsed}ms)`;
+
+                // Run assertion if provided
+                if (t.assert && status === 'PASS') {
+                    const assertResult = t.assert(res, text, isError);
+                    if (assertResult !== true) {
+                        status = 'FAIL';
+                        detail = `ASSERTION: ${assertResult} (${elapsed}ms)`;
+                    }
+                }
             } else {
                 status = 'PASS';
                 detail = `Empty result (${elapsed}ms)`;