codesearch-mcp 0.2.2-alpha → 0.3.0-alpha

package/dist/src/tools/GetDependentsTool.d.ts

@@ -1,8 +1,10 @@
 import type { IMcpToolHandler, ToolDefinition, ToolResponse } from '../interfaces/IMcpToolHandler';
 import type { ISearcher } from '../interfaces/ISearcher';
+import type { ILogger } from '../interfaces/ILogger';
 export declare class GetDependentsTool implements IMcpToolHandler {
     private searcher;
-    constructor(searcher: ISearcher);
+    private logger;
+    constructor(searcher: ISearcher, logger: ILogger);
     definition(): ToolDefinition;
     handle(args: Record<string, unknown>): Promise<ToolResponse>;
 }

package/dist/src/tools/GetDependentsTool.js

@@ -2,52 +2,67 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.GetDependentsTool = void 0;
 const format_helpers_1 = require("./format-helpers");
-const format_helpers_2 = require("./format-helpers");
 class GetDependentsTool {
     searcher;
-    constructor(searcher) {
+    logger;
+    constructor(searcher, logger) {
         this.searcher = searcher;
+        this.logger = logger;
     }
     definition() {
         return {
             name: 'get_dependents',
-            description: 'Show which files import a given file (reverse graph). Use before refactoring to find all callers and avoid breaking changes. depType values: import | import-default | import-namespace | reexport | reexport-namespace.',
+            description: 'Show which files import a given file (reverse graph), in any project. Use before refactoring to find all callers and avoid breaking changes. The direct section prints one line per importing file, with the names imported and the enclosing declarations that use them — only those resolved unambiguously, so the list can be partial or absent.',
             inputSchema: {
                 type: 'object',
                 properties: {
-                    file_path: { type: 'string', description: 'File path as returned by search_codebase' },
-                    project: { type: 'string', description: 'Project name (use list_projects to find it)' },
-                    symbol: { type: 'string', description: 'Exported symbol name. Two behaviors: (1) if graph dependents exist, narrows them to imports of this symbol; (2) if the import graph returns zero results, triggers a whole-word text-search fallback (grep -F -w) across all .ts/.tsx/.js/.jsx files in the project to find runtime usages — DI containers, singletons, dynamic lookups, string references. Capped at 200 matches.' },
+                    file_path: { type: 'string', description: (0, format_helpers_1.pathArgDescription)() },
+                    symbol: { type: 'string', description: 'Exported symbol name. Two behaviors: (1) if graph dependents exist, narrows them to imports of this symbol; (2) if the import graph returns zero results, triggers a whole-word text-search fallback (grep -F -w) across all .ts/.tsx/.js/.jsx files of the project owning the file to find runtime usages — DI containers, singletons, dynamic lookups, string references. Capped at 200 matches.' },
                     transitive: { type: 'boolean', description: 'Include transitive (indirect) dependents. Default: false.' },
                 },
-                required: ['file_path', 'project'],
+                required: ['file_path'],
             },
         };
     }
     async handle(args) {
-        const filePath = String(args.file_path);
-        const project = String(args.project);
+        const input = args.file_path == null ? '' : String(args.file_path);
         const symbol = args.symbol ? String(args.symbol) : null;
         const transitive = Boolean(args.transitive);
-        const rows = await this.searcher.getDependents(filePath, project, symbol, transitive);
+        const resolved = await this.searcher.resolveToolPath(input);
+        if (!resolved.ok)
+            return (0, format_helpers_1.pathErrorResponse)(this.logger, 'get_dependents', 'file_path', input, input, resolved);
+        const filePath = resolved.relPath;
+        const rows = await this.searcher.getDependents(filePath, symbol, transitive);
         if (rows.length > 0) {
-            return (0, format_helpers_1.textResponse)((0, format_helpers_2.formatDependents)(filePath, rows, transitive));
+            return (0, format_helpers_1.textResponse)((0, format_helpers_1.formatDependents)(filePath, rows, transitive));
         }
+        const failure = await this.searcher.checkGraphPath(filePath);
+        if (failure)
+            return (0, format_helpers_1.pathErrorResponse)(this.logger, 'get_dependents', 'file_path', input, filePath, failure);
         const header = `**Dependents of** \`${filePath}\`\n\n**Direct:** No direct import dependents found.`;
         if (!symbol) {
             return (0, format_helpers_1.textResponse)(`${header}\n\nTip: pass \`symbol\` to trigger a text-search fallback for runtime usages (e.g. via singleton or container).`);
         }
-        const { matches, truncated } = await this.searcher.grepSymbol(symbol, project, filePath);
-        if (matches.length === 0) {
-            return (0, format_helpers_1.textResponse)(`${header}\n\n**Fallback \`[text search]\` for \`${symbol}\`:** No results.`);
+        const rootDir = this.searcher.fallbackRoot(filePath);
+        if (rootDir === null)
+            return (0, format_helpers_1.textResponse)(header);
+        const fallbackHeader = `**Fallback \`[text search]\` for \`${symbol}\`:**`;
+        const grep = await this.searcher.grepSymbol(symbol, rootDir, filePath);
+        if (!grep.ok) {
+            return (0, format_helpers_1.textResponse)(`${header}\n\n${fallbackHeader} failed`);
+        }
+        if (grep.matches.length === 0) {
+            return (0, format_helpers_1.textResponse)(`${header}\n\n${fallbackHeader} No results.`);
         }
         const grouped = new Map();
-        for (const m of matches) {
+        for (const m of grep.matches) {
             if (!grouped.has(m.filePath))
                 grouped.set(m.filePath, []);
             grouped.get(m.filePath).push(m.line);
         }
-        const fallbackLines = [`\n**Fallback \`[text search]\` for \`${symbol}\`:**${truncated ? ' *(truncated to 200 results)*' : ''}`];
+        const notes = (grep.truncated ? ' *(truncated to 200 results)*' : '') +
+            (grep.partial ? ' *(partial — some files could not be searched)*' : '');
+        const fallbackLines = [`\n${fallbackHeader}${notes}`];
         for (const [fp, lines] of grouped) {
             fallbackLines.push(`  ~ \`${fp}\`:${lines.join(', ')}`);
         }

package/dist/src/tools/ListFilesTool.d.ts

@@ -1,8 +1,10 @@
 import type { IMcpToolHandler, ToolDefinition, ToolResponse } from '../interfaces/IMcpToolHandler';
 import type { ISearcher } from '../interfaces/ISearcher';
+import type { ILogger } from '../interfaces/ILogger';
 export declare class ListFilesTool implements IMcpToolHandler {
     private searcher;
-    constructor(searcher: ISearcher);
+    private logger;
+    constructor(searcher: ISearcher, logger: ILogger);
     definition(): ToolDefinition;
     handle(args: Record<string, unknown>): Promise<ToolResponse>;
 }

package/dist/src/tools/ListFilesTool.js

@@ -4,36 +4,38 @@ exports.ListFilesTool = void 0;
 const format_helpers_1 = require("./format-helpers");
 class ListFilesTool {
     searcher;
-    constructor(searcher) {
+    logger;
+    constructor(searcher, logger) {
         this.searcher = searcher;
+        this.logger = logger;
     }
     definition() {
         return {
             name: 'list_files',
-            description: 'List files and directories in a project path as an indented tree. Use to understand project structure before reading files.',
+            description: 'List files and directories under a workspace directory as an indented tree. Use to understand project structure before reading files; list_projects prints each project\'s directory.',
             inputSchema: {
                 type: 'object',
                 properties: {
-                    path: { type: 'string', description: 'Directory path relative to the project root (e.g. "src/components" or "." for root)' },
-                    project: { type: 'string', description: 'Project name (from list_projects)' },
+                    path: { type: 'string', description: (0, format_helpers_1.pathArgDescription)('directory') },
                     depth: { type: 'number', description: 'Tree depth: 1 = immediate children only, up to 5. Default: 2.' },
                     pattern: { type: 'string', description: 'Optional filename filter (substring or extension like ".ts"). Only matching files are shown.' },
                 },
-                required: ['path', 'project'],
+                required: ['path'],
             },
         };
     }
     async handle(args) {
-        const relPath = String(args.path ?? '.');
-        const project = String(args.project ?? '');
+        const input = args.path == null ? '' : String(args.path);
         const rawDepth = Number(args.depth);
         const depth = isNaN(rawDepth) || rawDepth < 1 ? 2 : Math.min(5, rawDepth);
         const pattern = args.pattern ? String(args.pattern) : null;
-        const { tree, error } = this.searcher.listFiles(relPath, project, depth, pattern);
-        if (error) {
-            return (0, format_helpers_1.textResponse)(`list_files error: ${error}`);
-        }
-        return (0, format_helpers_1.textResponse)(`**${project}/${relPath}**\n\`\`\`\n${tree}\n\`\`\``);
+        const resolved = await this.searcher.resolveToolPath(input);
+        if (!resolved.ok)
+            return (0, format_helpers_1.pathErrorResponse)(this.logger, 'list_files', 'path', input, input, resolved, 'directory');
+        const result = await this.searcher.listFiles(resolved.relPath, depth, pattern);
+        if (!result.ok)
+            return (0, format_helpers_1.pathErrorResponse)(this.logger, 'list_files', 'path', input, resolved.relPath, result, 'directory');
+        return (0, format_helpers_1.textResponse)(`**Directory:** ${resolved.relPath}\n\`\`\`\n${result.tree}\n\`\`\``);
     }
 }
 exports.ListFilesTool = ListFilesTool;

package/dist/src/tools/ListProjectsTool.js

@@ -10,7 +10,7 @@ class ListProjectsTool {
     definition() {
         return {
             name: 'list_projects',
-            description: 'List all indexed projects with their chunk counts and metadata (description, stack, notes, relations from .ragmeta.json).',
+            description: 'List all indexed projects with their chunk counts, workspace-relative directory (`path:`) and metadata (description, stack, notes, relations from .ragmeta.json).',
             inputSchema: { type: 'object', properties: {} },
         };
     }
@@ -21,6 +21,10 @@ class ListProjectsTool {
         }
         return (0, format_helpers_1.textResponse)(rows.map(r => {
             const lines = [`${r.serviceName}: ${r.chunks} chunks`];
+            if (r.relPath) {
+                const state = !r.rootError ? '' : r.rootError === 'ENOENT' ? ' (not on disk)' : ` (${r.rootError})`;
+                lines.push(`  path: ${r.relPath}${state}`);
+            }
             if (r.packageName)
                 lines.push(`  package: ${r.packageName}`);
             if (r.type)

package/dist/src/tools/ReadFileRangeTool.d.ts

@@ -1,8 +1,10 @@
 import type { IMcpToolHandler, ToolDefinition, ToolResponse } from '../interfaces/IMcpToolHandler';
 import type { ISearcher } from '../interfaces/ISearcher';
+import type { ILogger } from '../interfaces/ILogger';
 export declare class ReadFileRangeTool implements IMcpToolHandler {
     private searcher;
-    constructor(searcher: ISearcher);
+    private logger;
+    constructor(searcher: ISearcher, logger: ILogger);
     definition(): ToolDefinition;
     handle(args: Record<string, unknown>): Promise<ToolResponse>;
 }

package/dist/src/tools/ReadFileRangeTool.js

@@ -4,17 +4,19 @@ exports.ReadFileRangeTool = void 0;
 const format_helpers_1 = require("./format-helpers");
 class ReadFileRangeTool {
     searcher;
-    constructor(searcher) {
+    logger;
+    constructor(searcher, logger) {
         this.searcher = searcher;
+        this.logger = logger;
     }
     definition() {
         return {
             name: 'read_file_range',
-            description: 'Read a specific line range from an indexed source file. Use this when a search result looks incomplete — read the surrounding lines to get full context.',
+            description: 'Read a specific line range from a file under the workspace, indexed or not. Use this when a search result looks incomplete — read the surrounding lines to get full context.',
             inputSchema: {
                 type: 'object',
                 properties: {
-                    file_path: { type: 'string', description: 'File path as returned by search_codebase' },
+                    file_path: { type: 'string', description: (0, format_helpers_1.pathArgDescription)() },
                     start_line: { type: 'number', description: 'First line to read (1-based). Use the **Line** number from search_codebase results. Default: 1.' },
                     end_line: { type: 'number', description: 'Last line to read (1-based, inclusive). Default: start_line + 99.' },
                 },
@@ -23,16 +25,15 @@ class ReadFileRangeTool {
         };
     }
     async handle(args) {
-        const filePath = String(args.file_path);
+        const input = args.file_path == null ? '' : String(args.file_path);
         const startLine = Math.max(1, Number(args.start_line) || 1);
         const endLine = Number(args.end_line) || startLine + 99;
-        const range = await this.searcher.readFileRange(filePath, startLine, endLine);
-        if (!range.ok) {
-            const message = range.reason === 'invalid_path' ? `Invalid file path (outside workspace): ${filePath}` :
-                range.reason === 'not_indexed' ? `File is not indexed: ${filePath}. Run indexing first.` :
-                    `File was deleted from disk after indexing: ${filePath}. Re-run indexing to update.`;
-            return (0, format_helpers_1.textResponse)(message);
-        }
+        const resolved = await this.searcher.resolveToolPath(input);
+        if (!resolved.ok)
+            return (0, format_helpers_1.pathErrorResponse)(this.logger, 'read_file_range', 'file_path', input, input, resolved);
+        const range = await this.searcher.readFileRange(resolved.relPath, startLine, endLine);
+        if (!range.ok)
+            return (0, format_helpers_1.pathErrorResponse)(this.logger, 'read_file_range', 'file_path', input, resolved.relPath, range);
         const numbered = range.lines.map((line, i) => `${startLine + i}: ${line}`).join('\n');
         let text = `**File:** ${range.filePath}\n**Lines:** ${range.startLine}–${range.endLine}\n\`\`\`\n${numbered}\n\`\`\``;
         if (range.hasMore) {

package/dist/src/tools/ReadFileTool.d.ts

@@ -1,8 +1,10 @@
 import type { IMcpToolHandler, ToolDefinition, ToolResponse } from '../interfaces/IMcpToolHandler';
 import type { ISearcher } from '../interfaces/ISearcher';
+import type { ILogger } from '../interfaces/ILogger';
 export declare class ReadFileTool implements IMcpToolHandler {
     private searcher;
-    constructor(searcher: ISearcher);
+    private logger;
+    constructor(searcher: ISearcher, logger: ILogger);
     definition(): ToolDefinition;
     handle(args: Record<string, unknown>): Promise<ToolResponse>;
 }

package/dist/src/tools/ReadFileTool.js

@@ -4,17 +4,19 @@ exports.ReadFileTool = void 0;
 const format_helpers_1 = require("./format-helpers");
 class ReadFileTool {
     searcher;
-    constructor(searcher) {
+    logger;
+    constructor(searcher, logger) {
         this.searcher = searcher;
+        this.logger = logger;
     }
     definition() {
         return {
             name: 'read_file',
-            description: 'Read a file by absolute path. Returns contents with line numbers. Truncates at max_lines with a hint to continue with read_file_range.',
+            description: 'Read a complete file under the workspace, indexed or not. Returns contents with line numbers. Truncates at max_lines with a hint to continue with read_file_range.',
             inputSchema: {
                 type: 'object',
                 properties: {
-                    file_path: { type: 'string', description: 'Absolute path to the file. Note: search_codebase returns relative paths — construct the absolute path from your workspace root.' },
+                    file_path: { type: 'string', description: (0, format_helpers_1.pathArgDescription)() },
                     max_lines: { type: 'number', description: 'Maximum lines to return (default 300, max 1000)' },
                 },
                 required: ['file_path'],
@@ -22,15 +24,15 @@ class ReadFileTool {
         };
     }
     async handle(args) {
-        const filePath = String(args.file_path ?? '');
+        const input = args.file_path == null ? '' : String(args.file_path);
         const rawMax = Number(args.max_lines);
         const maxLines = isNaN(rawMax) || rawMax < 1 ? 300 : Math.min(1000, rawMax);
-        const result = await this.searcher.readFileAbsolute(filePath, maxLines);
-        if (!result.ok) {
-            const message = result.reason === 'invalid_path' ? `Invalid path (outside workspace): ${filePath}` :
-                `File not found on disk: ${filePath}`;
-            return (0, format_helpers_1.textResponse)(message);
-        }
+        const resolved = await this.searcher.resolveToolPath(input);
+        if (!resolved.ok)
+            return (0, format_helpers_1.pathErrorResponse)(this.logger, 'read_file', 'file_path', input, input, resolved);
+        const result = await this.searcher.readFile(resolved.relPath, maxLines);
+        if (!result.ok)
+            return (0, format_helpers_1.pathErrorResponse)(this.logger, 'read_file', 'file_path', input, resolved.relPath, result);
         const numbered = result.lines.map((line, i) => `${i + 1}: ${line}`).join('\n');
         let text = `**File:** ${result.filePath}\n**Lines:** 1–${result.endLine}\n\`\`\`\n${numbered}\n\`\`\``;
         if (result.hasMore) {

package/dist/src/tools/SearchCodebaseTool.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.SearchCodebaseTool = void 0;
 const format_helpers_1 = require("./format-helpers");
+const result_shaping_1 = require("../search/result-shaping");
 class SearchCodebaseTool {
     searcher;
     defaultLimit;
@@ -28,6 +29,8 @@ class SearchCodebaseTool {
                     include_neighbors: { type: 'boolean', description: 'Also include the chunk before and after each result from the same file (Small-to-Big retrieval). Useful when results look truncated.' },
                     include_graph_context: { type: 'boolean', description: 'Append direct imports and dependents list to each result. Shows "Imports: X · Y" and "Used by: Z" without extra tool calls.' },
                     threshold: { type: 'number', description: `Max cosine distance (0–1). Lower = stricter. Default: ${this.defaultThreshold}. Use 0.40–0.45 for precise technical queries, 0.55–0.60 for broad exploration.` },
+                    per_file: { type: 'number', description: `Max results from one file (integer ≥ 1, default ${result_shaping_1.DEFAULT_PER_FILE}). Skipped results are backfilled from the next candidates. Raise it when one file is expected to hold several answers (e.g. several methods of one class).` },
+                    rerank: { type: 'boolean', description: 'Override whether this call reranks, regardless of config. false skips reranking (use for "what does X do" / "where is X" lookups described without an exact name — reranking measurably hurts these; if you know the exact symbol name, use find_symbol instead). true forces reranking on if a reranker is configured (no-op otherwise). Omit to use config.reranker.enabled (fine for conceptual/architectural queries, where reranking is roughly neutral).' },
                 },
                 required: ['query'],
             },
@@ -45,11 +48,13 @@ class SearchCodebaseTool {
         const threshold = rawThreshold != null && !isNaN(parsedThreshold)
             ? Math.min(1, Math.max(0, parsedThreshold))
             : undefined;
+        const rerank = typeof args.rerank === 'boolean' ? args.rerank : undefined;
+        const perFile = Number.isInteger(args.per_file) && args.per_file >= 1 ? args.per_file : result_shaping_1.DEFAULT_PER_FILE;
         const { query, translated } = await this.searcher.prepareQuery(raw);
-        const results = await this.searcher.searchChunks(query, limit, project, threshold);
+        const results = await this.searcher.searchChunks(query, limit, project, threshold, rerank, perFile);
         this.logger.debug('SearchCodebaseTool: handle', {
             query: raw.slice(0, 120), project, threshold: threshold ?? this.defaultThreshold,
-            limit, translated, count: results.length, ms: Date.now() - t0,
+            limit, perFile, translated, count: results.length, ms: Date.now() - t0,
         });
         if (results.length === 0) {
             return (0, format_helpers_1.textResponse)('No relevant results found.');

package/dist/src/tools/format-helpers.d.ts

@@ -1,8 +1,17 @@
-import type { ChunkRow, DependencyRow, GraphContext } from '../services/SearcherService';
+import type { ChunkRow, DependencyRow, GraphContext, FileRangeResult, PathFailure, PathRefusal } from '../services/SearcherService';
 import type { ToolResponse } from '../interfaces/IMcpToolHandler';
+import type { ILogger } from '../interfaces/ILogger';
 export declare function textResponse(text: string): ToolResponse;
 export declare function errorResponse(text: string): ToolResponse;
 export declare function formatChunk(r: ChunkRow, label?: string): string;
 export declare function formatGraphContext(ctx: GraphContext | undefined): string;
 export declare function formatDependencies(filePath: string, rows: DependencyRow[], transitive: boolean): string;
 export declare function formatDependents(filePath: string, rows: DependencyRow[], transitive: boolean): string;
+export type PathKind = 'file' | 'directory';
+export declare const PATH_EXAMPLE: Record<PathKind, string>;
+export declare function pathArgDescription(kind?: PathKind): string;
+export type PathError = PathRefusal | PathFailure | Extract<FileRangeResult, {
+    reason: 'past_end' | 'bad_range';
+}>;
+export declare function pathErrorText(argName: string, input: string, relPath: string, err: PathError, kind?: PathKind): string;
+export declare function pathErrorResponse(logger: ILogger, tool: string, argName: string, input: string, relPath: string, err: PathError, kind?: PathKind): ToolResponse;

package/dist/src/tools/format-helpers.js

@@ -1,11 +1,15 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.PATH_EXAMPLE = void 0;
 exports.textResponse = textResponse;
 exports.errorResponse = errorResponse;
 exports.formatChunk = formatChunk;
 exports.formatGraphContext = formatGraphContext;
 exports.formatDependencies = formatDependencies;
 exports.formatDependents = formatDependents;
+exports.pathArgDescription = pathArgDescription;
+exports.pathErrorText = pathErrorText;
+exports.pathErrorResponse = pathErrorResponse;
 function textResponse(text) {
     return { content: [{ type: 'text', text }] };
 }
@@ -24,13 +28,87 @@ function formatGraphContext(ctx) {
         parts.push(`**Used by:** ${ctx.usedBy.join(' · ')}`);
     return parts.length > 0 ? '\n' + parts.join('\n') : '';
 }
+const MAX_NAMES = 8;
+const MAX_IN = 3;
+function nameEntry(r) {
+    switch (r.depType) {
+        case 'import': return r.toSymbol ? { text: r.toSymbol, isReexport: false } : null;
+        case 'import-default': return { text: r.toSymbol ?? 'default', isReexport: false };
+        case 'import-namespace': return { text: r.toSymbol ?? '* as namespace', isReexport: false };
+        case 'import-side-effect': return { text: 'side-effect', isReexport: false };
+        case 'reexport': return r.toSymbol ? { text: r.toSymbol, isReexport: true } : null;
+        case 'reexport-namespace': return { text: r.toSymbol ?? 'export *', isReexport: true };
+        default: return null;
+    }
+}
+function codeSpan(value) {
+    const text = value.replace(/\s+/g, ' ');
+    const fence = '`'.repeat(Math.max(0, ...(text.match(/`+/g) ?? []).map(run => run.length)) + 1);
+    const pad = text.startsWith('`') || text.endsWith('`') ? ' ' : '';
+    return `${fence}${pad}${text}${pad}${fence}`;
+}
+function capped(values, max) {
+    const shown = values.slice(0, max);
+    const more = values.length - shown.length;
+    const text = shown.map(codeSpan).join(', ');
+    return more > 0 ? `${text} (+${more} more)` : text;
+}
+function groupNames(rows) {
+    const plain = [];
+    const reexport = [];
+    for (const r of rows) {
+        const e = nameEntry(r);
+        if (!e)
+            continue;
+        const bucket = e.isReexport ? reexport : plain;
+        if (!bucket.includes(e.text))
+            bucket.push(e.text);
+    }
+    const total = plain.length + reexport.length;
+    const shownPlainCount = Math.min(plain.length, MAX_NAMES);
+    const shownReexportCount = Math.min(reexport.length, MAX_NAMES - shownPlainCount);
+    const more = total - shownPlainCount - shownReexportCount;
+    const parts = [];
+    if (shownPlainCount > 0) {
+        parts.push(plain.slice(0, shownPlainCount).map(codeSpan).join(', '));
+    }
+    if (shownReexportCount > 0) {
+        parts.push(`re-export ${reexport.slice(0, shownReexportCount).map(codeSpan).join(', ')}`);
+    }
+    let text = parts.join(', ');
+    if (more > 0)
+        text += ` (+${more} more)`;
+    return text;
+}
+function groupIn(rows) {
+    const values = [];
+    for (const r of rows) {
+        if (r.fromSymbol && !values.includes(r.fromSymbol))
+            values.push(r.fromSymbol);
+    }
+    return capped(values, MAX_IN);
+}
+function groupByFile(rows, key) {
+    const groups = new Map();
+    for (const r of rows) {
+        const k = r[key];
+        if (!groups.has(k))
+            groups.set(k, []);
+        groups.get(k).push(r);
+    }
+    return groups;
+}
+function directHeader(fileCount) {
+    return `**Direct:** ${fileCount} file${fileCount === 1 ? '' : 's'}`;
+}
 function formatDependencies(filePath, rows, transitive) {
     const direct = rows.filter(r => !transitive || (r.depth ?? 1) === 1);
     const indirect = transitive ? rows.filter(r => (r.depth ?? 1) > 1) : [];
-    const lines = [`**Dependencies of** \`${filePath}\`\n`, '**Direct:**'];
-    for (const r of direct) {
-        const sym = r.toSymbol ? ` (${r.depType} \`${r.toSymbol}\`)` : ` (${r.depType})`;
-        lines.push(`  → \`${r.toFile}\`${sym}`);
+    const groups = groupByFile(direct, 'toFile');
+    const lines = [`**Dependencies of** \`${filePath}\`\n`, directHeader(groups.size)];
+    for (const [toFile, groupRows] of groups) {
+        const names = groupNames(groupRows);
+        lines.push(`  → \`${toFile}\`${names ? ` — ${names}` : ''}`);
     }
     if (indirect.length > 0) {
         lines.push('\n**Transitive:**');
@@ -43,10 +121,15 @@ function formatDependencies(filePath, rows, transitive) {
 function formatDependents(filePath, rows, transitive) {
     const direct = rows.filter(r => !transitive || (r.depth ?? 1) === 1);
     const indirect = transitive ? rows.filter(r => (r.depth ?? 1) > 1) : [];
-    const lines = [`**Dependents of** \`${filePath}\`\n`, '**Direct:**'];
-    for (const r of direct) {
-        const sym = r.fromSymbol ? ` (in \`${r.fromSymbol}\`)` : '';
-        lines.push(`  ← \`${r.fromFile}\`${sym}`);
+    const groups = groupByFile(direct, 'fromFile');
+    const lines = [`**Dependents of** \`${filePath}\`\n`, directHeader(groups.size)];
+    for (const [fromFile, groupRows] of groups) {
+        const names = groupNames(groupRows);
+        const inPart = groupIn(groupRows);
+        let line = `  ← \`${fromFile}\`${names ? ` — ${names}` : ''}`;
+        if (inPart)
+            line += ` · in ${inPart}`;
+        lines.push(line);
     }
     if (indirect.length > 0) {
         lines.push('\n**Transitive:**');
@@ -56,3 +139,57 @@ function formatDependents(filePath, rows, transitive) {
     }
     return lines.join('\n');
 }
+exports.PATH_EXAMPLE = { file: 'my-app/src/index.ts', directory: 'my-app/src' };
+function pathArgDescription(kind = 'file') {
+    const root = kind === 'directory' ? ', "." for the workspace root' : '';
+    const noun = kind === 'directory' ? 'directory' : 'path';
+    return `Workspace-relative ${noun}, as printed by search_codebase (e.g. ${exports.PATH_EXAMPLE[kind]})${root}`;
+}
+function acceptedForm(example) {
+    return `Paths are workspace-relative, as printed by search_codebase — e.g. ${example}.`;
+}
+function notIndexedExplanation(e) {
+    const excluded = (why) => `This file is not indexed (${why}), so the graph has no data for it. Use read_file or Grep instead.`;
+    switch (e.kind) {
+        case 'no_project': return excluded('it is outside every project');
+        case 'type': return excluded('files of this type are not indexed');
+        case 'ignored_dir': return excluded(`${e.segment}/ is an ignored directory`);
+        case 'ragignore': return excluded('it matches .ragignore');
+        case 'project_not_indexed': return `Project ${e.project} is not in the index. If it is not selected, select it with rag-index --select; then run rag-index.`;
+        case 'unknown':
+            return 'The file exists on disk but the index has no data for it: either it was added after the last index run ' +
+                '(run rag-index), or it has no indexable content (empty, comments only, or imports of external packages only).';
+    }
+}
+function pathErrorText(argName, input, relPath, err, kind = 'file') {
+    const example = exports.PATH_EXAMPLE[kind];
+    switch (err.reason) {
+        case 'invalid':
+            return err.missing
+                ? `Missing ${argName}\n${acceptedForm(example)}`
+                : `Invalid path (\\ is not a separator): ${input}\n${acceptedForm(example)}`;
+        case 'absolute':
+            return `Absolute path: ${input} — use ${err.relative}\n${acceptedForm(err.relative)}`;
+        case 'outside_workspace':
+            return `${input} is outside the workspace\n${acceptedForm(example)}`;
+        case 'not_found': {
+            const lines = [`Not found: ${relPath}`, acceptedForm(err.candidates[0] ?? example)];
+            if (err.candidates.length > 0)
+                lines.push('Did you mean:', ...err.candidates.map(c => `- ${c}`));
+            return lines.join('\n');
+        }
+        case 'deleted':
+            return `Deleted from disk: ${relPath}\nThe index still holds this file, but it no longer exists on disk. Run rag-index to update the index.`;
+        case 'not_indexed':
+            return `Not indexed: ${relPath}\n${notIndexedExplanation(err.explanation)}`;
+        case 'not_a_file': return `Not a file: ${relPath}`;
+        case 'not_a_directory': return `Not a directory: ${relPath}`;
+        case 'unreadable': return `Cannot read: ${relPath} (${err.code})`;
+        case 'past_end': return `${relPath} has ${err.lineCount} lines; start_line ${err.startLine} is past the end`;
+        case 'bad_range': return `end_line ${err.endLine} is before start_line ${err.startLine}`;
+    }
+}
+function pathErrorResponse(logger, tool, argName, input, relPath, err, kind = 'file') {
+    logger.warn('Tool path error', { tool, input, reason: err.reason });
+    return errorResponse(pathErrorText(argName, input, relPath, err, kind));
+}

package/dist/src/web/dashboard.d.ts

@@ -1,9 +1 @@
-/**
- * Renders the RAG dashboard as a single self-contained HTML page (inline CSS +
- * JS), mirroring the approach in graph.ts. The page is schema-driven: it fetches
- * /api/schema (from buildJsonSchema — the same source as Step 1's editor support)
- * and /api/config, then renders a typed form. The Graph tab embeds the full
- * standalone graph page (GET /graph — same buildHtml as project-graph.html) in
- * an iframe rather than re-implementing the network here.
- */
 export declare function renderDashboardHtml(): string;

package/dist/src/web/dashboard.js

@@ -1,14 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.renderDashboardHtml = renderDashboardHtml;
-/**
- * Renders the RAG dashboard as a single self-contained HTML page (inline CSS +
- * JS), mirroring the approach in graph.ts. The page is schema-driven: it fetches
- * /api/schema (from buildJsonSchema — the same source as Step 1's editor support)
- * and /api/config, then renders a typed form. The Graph tab embeds the full
- * standalone graph page (GET /graph — same buildHtml as project-graph.html) in
- * an iframe rather than re-implementing the network here.
- */
 function renderDashboardHtml() {
     return `<!DOCTYPE html>
 <html lang="en">
@@ -168,7 +160,12 @@ function renderDashboardHtml() {
     if (spec.type === 'boolean') {
       const cb = document.createElement('input');
       cb.type = 'checkbox'; cb.dataset.key = key; cb.dataset.type = 'boolean';
-      cb.checked = value === true;
+      cb.checked = isUnset ? def === true : value === true;
+      // An absent boolean can resolve from context (reranker.enabled), so it is saved only once changed.
+      if (isUnset) {
+        cb.dataset.unset = '1';
+        cb.addEventListener('change', () => { delete cb.dataset.unset; });
+      }
       return cb;
     }
     if (Array.isArray(enumVals)) return selectEl(key, enumVals, value, def);
@@ -236,7 +233,7 @@ function renderDashboardHtml() {
     document.querySelectorAll('[data-key]').forEach(el => {
       const key = el.dataset.key, type = el.dataset.type;
       let val;
-      if (type === 'boolean') val = el.checked;
+      if (type === 'boolean') { if (el.dataset.unset) return; val = el.checked; }
       else if (el.value === '') return; // unset → omit (stay minimal)
       else if (type === 'number') { const n = Number(el.value); if (Number.isNaN(n)) return; val = n; }
       else val = el.value;