@danypops/pi-lector 0.1.12 → 0.2.0

package/extension/src/apply-patch-operations.ts

@@ -0,0 +1,29 @@
+import type { ContentHash, EditOutcome } from "@danypops/lector";
+import { lectorClient, withWorkspace, workspaceForPath } from "./lector-client.ts";
+import { toWorkspaceRelativePath } from "./workspace-relative-path.ts";
+
+/**
+ * Thin wrapper over workspace.applyPatch -- distinct from both the generic edit tool
+ * (whole-file replace) and line_edit (per-line hash guards): applies a real unified diff's
+ * hunks, guarded by one whole-file expectedHash (a patch inherently describes a
+ * whole-file transformation from a known pre-image). `path` is an absolute file path, the
+ * same convention edit-operations.ts and line-edit-operations.ts already use.
+ */
+export interface ApplyPatchOperations {
+	applyPatch(path: string, expectedHash: ContentHash, patchText: string): Promise<EditOutcome>;
+}
+
+export function createLectorApplyPatchOperations(): ApplyPatchOperations {
+	return {
+		async applyPatch(path, expectedHash, patchText) {
+			return withWorkspace(
+				() => workspaceForPath(path),
+				async ({ workspaceId, root }) => {
+					const client = await lectorClient();
+					const relativePath = toWorkspaceRelativePath(root, path);
+					return client.call("workspace.applyPatch", { workspaceId, path: relativePath, expectedHash, patchText });
+				},
+			);
+		},
+	};
+}

package/extension/src/apply-patch-rendering.ts

@@ -0,0 +1,12 @@
+import type { EditOutcome } from "@danypops/lector";
+import type { LectorTheme } from "./lector-tui-theme.ts";
+
+export function formatApplyPatchCall(args: { path?: unknown }, theme: LectorTheme): string {
+	const path = typeof args.path === "string" ? args.path : "";
+	return `${theme.fg("toolTitle", theme.bold("apply_patch"))} ${theme.fg("accent", path)}`;
+}
+
+export function formatApplyPatchResult(result: EditOutcome | undefined, theme: LectorTheme): string {
+	if (!result) return theme.fg("dim", "No result.");
+	return theme.fg("accent", `${result.path}: ${result.previousHash ?? "(new)"} -> ${result.newHash}`);
+}

package/extension/src/code-intelligence-operations.ts

@@ -1,4 +1,4 @@
-import type { JobSnapshot, OperationOutputs, PopulateSymbolGraphResult, SymbolEdgeKind, SymbolNode } from "@danypops/lector";
+import type { JobSnapshot, OperationInputs, OperationOutputs, PopulateSymbolGraphResult, SymbolEdgeKind, SymbolNode } from "@danypops/lector";
 import { lectorClient, withWorkspace, workspaceForCodeIntelligencePath } from "./lector-client.ts";
 
 /**
@@ -17,7 +17,13 @@ import { lectorClient, withWorkspace, workspaceForCodeIntelligencePath } from ".
 export interface CodeIntelligenceOperations {
 	goToDefinition(path: string, line: number, character: number): Promise<OperationOutputs["workspace.goToDefinition"]>;
 	goToImplementation(path: string, line: number, character: number): Promise<OperationOutputs["workspace.goToImplementation"]>;
-	findReferences(path: string, line: number, character: number, includeDeclaration: boolean): Promise<OperationOutputs["workspace.findReferences"]>;
+	findReferences(
+		path: string,
+		line: number,
+		character: number,
+		includeDeclaration: boolean,
+		responseFormat?: OperationInputs["workspace.findReferences"]["responseFormat"],
+	): Promise<OperationOutputs["workspace.findReferences"]>;
 	hover(path: string, line: number, character: number): Promise<OperationOutputs["workspace.hover"]>;
 	documentSymbols(path: string): Promise<OperationOutputs["workspace.documentSymbols"]>;
 	diagnostics(path: string): Promise<OperationOutputs["workspace.diagnostics"]>;
@@ -29,6 +35,7 @@ export interface CodeIntelligenceOperations {
 	reachableFrom(path: string, line: number, character: number, maxDepth: number, kind?: SymbolEdgeKind): Promise<readonly SymbolNode[]>;
 	/** Never spawns a symbol index -- safe to call opportunistically (e.g. before deciding whether to enrich a result). */
 	hasWarmIndex(path: string): Promise<boolean>;
+	workspaceMap(path: string, maxNodes: number, maxEdges: number, maxEntries: number, maxBytes: number): Promise<OperationOutputs["workspace.map"]>;
 }
 
 export function createLectorCodeIntelligenceOperations(): CodeIntelligenceOperations {
@@ -51,12 +58,12 @@ export function createLectorCodeIntelligenceOperations(): CodeIntelligenceOperat
 				},
 			);
 		},
-		async findReferences(path, line, character, includeDeclaration) {
+		async findReferences(path, line, character, includeDeclaration, responseFormat) {
 			return withWorkspace(
 				() => workspaceForCodeIntelligencePath(path),
 				async ({ workspaceId }) => {
 					const client = await lectorClient();
-					return client.call("workspace.findReferences", { workspaceId, path, line, character, includeDeclaration });
+					return client.call("workspace.findReferences", { workspaceId, path, line, character, includeDeclaration, responseFormat });
 				},
 			);
 		},
@@ -153,5 +160,14 @@ export function createLectorCodeIntelligenceOperations(): CodeIntelligenceOperat
 				},
 			);
 		},
+		async workspaceMap(path, maxNodes, maxEdges, maxEntries, maxBytes) {
+			return withWorkspace(
+				() => workspaceForCodeIntelligencePath(path),
+				async ({ workspaceId }) => {
+					const client = await lectorClient();
+					return client.call("workspace.map", { workspaceId, maxNodes, maxEdges, maxEntries, maxBytes });
+				},
+			);
+		},
 	};
 }

package/extension/src/code-intelligence-rendering.ts

@@ -9,6 +9,7 @@ import type {
 	PopulateSymbolGraphResult,
 	SymbolNode,
 	WorkspaceLocation,
+	WorkspaceMapResult,
 } from "@danypops/lector";
 import { keyHint, type ThemeColor } from "@earendil-works/pi-coding-agent";
 import { colorForKind, formatLocation, type LectorTheme } from "./lector-tui-theme.ts";
@@ -239,3 +240,31 @@ export function formatReachableFromResult(symbols: readonly SymbolNode[] | undef
 	if (remaining > 0) lines.push(theme.fg("dim", `... ${remaining} more (${keyHint("app.tools.expand", "to expand")})`));
 	return lines.join("\n");
 }
+
+export function formatWorkspaceMapCall(args: { path?: unknown; maxEntries?: unknown }, theme: LectorTheme): string {
+	const path = typeof args.path === "string" ? args.path : "";
+	const maxEntries = typeof args.maxEntries === "number" ? ` (top ${args.maxEntries})` : "";
+	return `${theme.fg("toolTitle", theme.bold("workspace_map"))} ${theme.fg("dim", path)}${theme.fg("muted", maxEntries)}`;
+}
+
+export function formatWorkspaceMapResult(result: WorkspaceMapResult | undefined, expanded: boolean, theme: LectorTheme): string {
+	if (!result || result.entries.length === 0) return theme.fg("dim", "No ranked symbols (has the graph been populated for this workspace?).");
+
+	const displayCount = expanded ? result.entries.length : Math.min(result.entries.length, DEFAULT_VISIBLE_SYMBOLS);
+	const lines = [
+		theme.fg(
+			"muted",
+			`${result.entries.length} of ${result.totalRanked} ranked symbol${result.totalRanked === 1 ? "" : "s"}, most structurally central first:`,
+		),
+	];
+	for (const entry of result.entries.slice(0, displayCount)) {
+		const signature = entry.signature ? ` -- ${entry.signature}` : "";
+		lines.push(
+			`  ${theme.fg(colorForKind(entry.kind), entry.kind)} ${theme.bold(entry.name)}  ${formatLocation(theme, entry.path, entry.line, entry.character)}${signature}`,
+		);
+	}
+	const remaining = displayCount - result.entries.length;
+	if (remaining < 0) lines.push(theme.fg("dim", `... ${-remaining} more (${keyHint("app.tools.expand", "to expand")})`));
+	if (result.truncated) lines.push(theme.fg("warning", "budget-truncated -- raise --max-entries/--max-bytes for more"));
+	return lines.join("\n");
+}

package/extension/src/find-files-operations.ts

@@ -0,0 +1,25 @@
+import type { FindFilesResult } from "@danypops/lector";
+import { lectorClient, withWorkspace, workspaceForDirectory } from "./lector-client.ts";
+
+/**
+ * Thin wrapper over workspace.findFiles -- the `find`-shaped half of the classic grep+find pair,
+ * distinct from search_code (content). `directory` is required, same convention as
+ * find_symbols/search_code -- no implicit "whatever the session's cwd is" fallback.
+ */
+export interface FindFilesOperations {
+	findFiles(patterns: readonly string[], directory: string, maxResults: number, maxBytes: number): Promise<FindFilesResult>;
+}
+
+export function createLectorFindFilesOperations(): FindFilesOperations {
+	return {
+		async findFiles(patterns, directory, maxResults, maxBytes) {
+			return withWorkspace(
+				() => workspaceForDirectory(directory),
+				async ({ workspaceId }) => {
+					const client = await lectorClient();
+					return client.call("workspace.findFiles", { workspaceId, patterns, maxResults, maxBytes });
+				},
+			);
+		},
+	};
+}

package/extension/src/find-files-rendering.ts

@@ -0,0 +1,21 @@
+import type { FindFilesResult } from "@danypops/lector";
+import { keyHint } from "@earendil-works/pi-coding-agent";
+import type { LectorTheme } from "./lector-tui-theme.ts";
+
+const DEFAULT_VISIBLE_PATHS = 40;
+
+export function formatFindFilesCall(args: { directory?: unknown; patterns?: unknown }, theme: LectorTheme): string {
+	const directory = typeof args.directory === "string" ? args.directory : "";
+	const patterns = Array.isArray(args.patterns) ? args.patterns.filter((p): p is string => typeof p === "string") : [];
+	return `${theme.fg("toolTitle", theme.bold("find_files"))} ${theme.fg("accent", patterns.map((p) => `"${p}"`).join(", "))} ${theme.fg("dim", directory)}`;
+}
+
+export function formatFindFilesResult(result: FindFilesResult | undefined, expanded: boolean, theme: LectorTheme): string {
+	if (!result || result.paths.length === 0) return theme.fg("dim", "No files found.");
+	const displayCount = expanded ? result.paths.length : Math.min(DEFAULT_VISIBLE_PATHS, result.paths.length);
+	const lines = result.paths.slice(0, displayCount).map((path) => theme.fg("accent", path));
+	const remaining = result.paths.length - displayCount;
+	if (remaining > 0) lines.push(theme.fg("dim", `... ${remaining} more (${keyHint("app.tools.expand", "to expand")})`));
+	if (result.truncated) lines.push(theme.fg("warning", "(listing itself was truncated by maxResults/maxBytes -- results are incomplete)"));
+	return lines.join("\n");
+}

package/extension/src/find-symbols-operations.ts

@@ -1,4 +1,4 @@
-import type { SymbolSearchResult } from "@danypops/lector";
+import type { OperationInputs, SymbolSearchResult } from "@danypops/lector";
 import { lectorClient, withWorkspace, workspaceForDirectory } from "./lector-client.ts";
 
 /**
@@ -15,17 +15,17 @@ import { lectorClient, withWorkspace, workspaceForDirectory } from "./lector-cli
  * is no implicit fallback anywhere in this module.
  */
 export interface FindSymbolsOperations {
-	findSymbols(query: string, directory: string): Promise<SymbolSearchResult>;
+	findSymbols(query: string, directory: string, responseFormat?: OperationInputs["workspace.findSymbols"]["responseFormat"]): Promise<SymbolSearchResult>;
 }
 
 export function createLectorFindSymbolsOperations(): FindSymbolsOperations {
 	return {
-		async findSymbols(query, directory) {
+		async findSymbols(query, directory, responseFormat) {
 			return withWorkspace(
 				() => workspaceForDirectory(directory),
 				async ({ workspaceId }) => {
 					const client = await lectorClient();
-					return client.call("workspace.findSymbols", { workspaceId, query });
+					return client.call("workspace.findSymbols", { workspaceId, query, responseFormat });
 				},
 			);
 		},

package/extension/src/index.ts

@@ -1,8 +1,11 @@
 import { resolve } from "node:path";
 import type {
 	CallHierarchyEntry,
+	ContentHash,
 	Diagnostic,
 	DocumentSymbolEntry,
+	EditOutcome,
+	FindFilesResult,
 	GitDiffResult,
 	GitLogEntry,
 	GitStatusSummary,
@@ -10,19 +13,25 @@ import type {
 	IncomingCall,
 	IntelligenceProvenance,
 	JobSnapshot,
+	LineEdit,
+	LineEditOutcome,
 	OutgoingCall,
 	PackageSourceOperationResult,
 	PopulateSymbolGraphResult,
 	RepoFetchResult,
+	SymbolAnnotation,
 	SymbolNode,
 	SymbolSearchResult,
 	TextSearchResult,
 	WorkspaceLocation,
+	WorkspaceMapResult,
 	WorkspaceQueryOutcome,
 } from "@danypops/lector";
 import { createEditToolDefinition, createReadToolDefinition, createWriteToolDefinition, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { Text } from "@earendil-works/pi-tui";
 import { Type } from "typebox";
+import { createLectorApplyPatchOperations } from "./apply-patch-operations.ts";
+import { formatApplyPatchCall, formatApplyPatchResult } from "./apply-patch-rendering.ts";
 import { createLectorCodeIntelligenceOperations } from "./code-intelligence-operations.ts";
 import {
 	describePopulateSymbolGraphJob,
@@ -48,14 +57,20 @@ import {
 	formatPrepareCallHierarchyResult,
 	formatReachableFromCall,
 	formatReachableFromResult,
+	formatWorkspaceMapCall,
+	formatWorkspaceMapResult,
 } from "./code-intelligence-rendering.ts";
 import { createLectorCrossWorkspaceSearchOperations } from "./cross-workspace-search-operations.ts";
 import { formatCrossWorkspaceCall, formatFindSymbolsAcrossProjectsResult, formatSearchTextAcrossProjectsResult } from "./cross-workspace-search-rendering.ts";
 import { createLectorEditOperations } from "./edit-operations.ts";
+import { createLectorFindFilesOperations } from "./find-files-operations.ts";
+import { formatFindFilesCall, formatFindFilesResult } from "./find-files-rendering.ts";
 import { createLectorFindSymbolsOperations } from "./find-symbols-operations.ts";
 import { describeFindSymbolSources, formatFindSymbolsCall, formatFindSymbolsResult } from "./find-symbols-rendering.ts";
 import { createLectorGitOperations } from "./git-operations.ts";
 import { formatGitDiffCall, formatGitDiffResult, formatGitLogCall, formatGitLogResult, formatGitStatusCall, formatGitStatusResult } from "./git-rendering.ts";
+import { createLectorLineEditOperations } from "./line-edit-operations.ts";
+import { formatLineEditCall, formatLineEditResult } from "./line-edit-rendering.ts";
 import { nearestGitRoot } from "./nearest-workspace-root.ts";
 import { createLectorPackageSourceOperations } from "./package-source-operations.ts";
 import { formatPackageSourceCall, formatPackageSourceResult } from "./package-source-rendering.ts";
@@ -64,6 +79,8 @@ import { createLectorRepoFetchOperations } from "./repo-fetch-operations.ts";
 import { formatRepoFetchCall, formatRepoFetchResult } from "./repo-fetch-rendering.ts";
 import { createLectorSearchOperations } from "./search-operations.ts";
 import { formatSearchCall, formatSearchResult } from "./search-rendering.ts";
+import { type AnnotationAnchorInput, createLectorSymbolAnnotationOperations } from "./symbol-annotation-operations.ts";
+import { formatAnnotationDetail, formatAnnotationListSummary, formatAnnotationSummary } from "./symbol-annotation-rendering.ts";
 import {
 	type CachePresentationState,
 	cacheContextMessage,
@@ -180,10 +197,16 @@ export default function (pi: ExtensionAPI) {
 			parameters: Type.Object({
 				query: Type.String({ description: "Name or substring to search for, case-insensitive" }),
 				directory: Type.String({ description: "Directory of the project to search, absolute or relative to the current working directory" }),
+				responseFormat: Type.Optional(
+					Type.Union([Type.Literal("concise"), Type.Literal("detailed")], {
+						description:
+							'"concise" (default "detailed") drops containerName and per-symbol/top-level provenance detail to reduce payload size when you only need name/kind/location',
+					}),
+				),
 			}),
 			async execute(_toolCallId, params) {
 				const directory = resolve(cwd, params.directory);
-				const result = await findSymbolsOperations.findSymbols(params.query, directory);
+				const result = await findSymbolsOperations.findSymbols(params.query, directory, params.responseFormat);
 				const { symbols, provenance, truncated } = result;
 				const source = `${provenance.fidelity} via ${provenance.backend}${truncated ? " (truncated)" : ""}`;
 				const sourceDetails = describeFindSymbolSources(result);
@@ -311,10 +334,15 @@ export default function (pi: ExtensionAPI) {
 			parameters: Type.Object({
 				...positionParameters,
 				includeDeclaration: Type.Boolean({ description: "Include the declaration site itself among the results" }),
+				responseFormat: Type.Optional(
+					Type.Union([Type.Literal("concise"), Type.Literal("detailed")], {
+						description: '"concise" (default "detailed") narrows the provenance detail to reduce payload size',
+					}),
+				),
 			}),
 			async execute(_toolCallId, params) {
 				const path = resolve(cwd, params.path);
-				const details = await codeIntelligenceOperations.findReferences(path, params.line, params.character, params.includeDeclaration);
+				const details = await codeIntelligenceOperations.findReferences(path, params.line, params.character, params.includeDeclaration, params.responseFormat);
 				const text = details.locations.length === 0 ? "No references found." : details.locations.map((l) => `${l.path}:${l.line}:${l.character}`).join("\n");
 				return { content: [{ type: "text", text: `${describeIntelligenceSource(details.provenance)}\n${text}` }], details };
 			},
@@ -648,6 +676,138 @@ export default function (pi: ExtensionAPI) {
 			},
 		});
 
+		const symbolAnnotationOperations = createLectorSymbolAnnotationOperations();
+		function resolveAnchorInputs(anchors: readonly { path: string; line: number; character: number }[]): AnnotationAnchorInput[] {
+			return anchors.map((anchor) => ({ path: resolve(cwd, anchor.path), line: anchor.line, character: anchor.character }));
+		}
+		interface SymbolAnnotationToolDetails {
+			annotation?: SymbolAnnotation;
+			annotations?: readonly SymbolAnnotation[];
+			scrubbed?: boolean;
+			restored?: boolean;
+		}
+
+		pi.registerTool({
+			name: "symbol_annotations",
+			label: "Symbol Annotations",
+			description:
+				'Agent-authored narrative content anchored to one or more symbols in the workspace\'s persisted graph -- e.g. a "user story dataflow" note spanning every symbol touched end-to-end. Every anchor must resolve to a real, currently-known symbol (run populate_symbol_graph first). get/list live-check staleness against the current graph/workspace on every call and persist a correction before returning, so a returned status never disagrees with reality -- a stale annotation must be refreshed (re-authored and re-anchored) or scrubbed (soft-deleted, restorable) by an explicit decision; Lector never rewrites the narrative itself. Actions: create, get, list, refresh, scrub, restore.',
+			promptSnippet: "Attach, read, or invalidate narrative annotations on the symbol graph",
+			promptGuidelines: [
+				"Resolve real anchor positions first (find_symbols/document_symbols/go_to_definition) -- an anchor position must match populate_symbol_graph's own recorded position for that symbol, not just any occurrence of its name.",
+				"A stale annotation's body may no longer describe the code accurately -- read it, decide whether to refresh (re-author) or scrub (remove), never trust it as-is.",
+			],
+			parameters: Type.Object({
+				action: Type.String({ description: "create | get | list | refresh | scrub | restore" }),
+				path: Type.String({ description: "Absolute or cwd-relative path used to resolve which workspace this annotation belongs to" }),
+				id: Type.Optional(Type.String({ description: "Annotation id -- required for get/refresh/scrub/restore" })),
+				subtype: Type.Optional(Type.String({ description: 'Free-form kind, e.g. "user-story-dataflow" or "comment" -- required for create/refresh' })),
+				title: Type.Optional(Type.String({ description: "Required for create/refresh" })),
+				body: Type.Optional(Type.String({ description: "The narrative content -- required for create/refresh" })),
+				anchors: Type.Optional(
+					Type.Array(
+						Type.Object({
+							path: Type.String({ description: "Absolute or cwd-relative path to the anchored file" }),
+							line: Type.Number({ description: "1-indexed line number" }),
+							character: Type.Number({ description: "1-indexed character offset within the line" }),
+						}),
+						{ description: "At least one required for create/refresh -- each must resolve to a real, currently-known symbol" },
+					),
+				),
+				listStatus: Type.Optional(Type.String({ description: "fresh | stale | scrubbed -- for list; defaults to excluding scrubbed" })),
+				listSubtype: Type.Optional(Type.String({ description: "For list: filter by subtype" })),
+				maxResults: Type.Optional(Type.Number({ description: "For list: bounds the number of results" })),
+			}),
+			async execute(_toolCallId, params) {
+				const path = resolve(cwd, params.path);
+				const details: SymbolAnnotationToolDetails = {};
+				let text: string;
+				if (params.action === "create") {
+					if (!params.subtype || !params.title || params.body === undefined || !params.anchors || params.anchors.length === 0) {
+						throw new Error("symbol_annotations create requires subtype, title, body, and at least one anchor");
+					}
+					const { annotation } = await symbolAnnotationOperations.create(path, params.subtype, params.title, params.body, resolveAnchorInputs(params.anchors));
+					details.annotation = annotation;
+					text = formatAnnotationDetail(annotation);
+				} else if (params.action === "get") {
+					if (!params.id) throw new Error("symbol_annotations get requires id");
+					const { annotation } = await symbolAnnotationOperations.get(path, params.id);
+					details.annotation = annotation;
+					text = annotation ? formatAnnotationDetail(annotation) : `no annotation "${params.id}"`;
+				} else if (params.action === "list") {
+					const status = params.listStatus === "fresh" || params.listStatus === "stale" || params.listStatus === "scrubbed" ? params.listStatus : undefined;
+					const { annotations } = await symbolAnnotationOperations.list(path, { subtype: params.listSubtype, status, maxResults: params.maxResults });
+					details.annotations = annotations;
+					text = annotations.length === 0 ? "no annotations" : annotations.map(formatAnnotationDetail).join("\n\n");
+				} else if (params.action === "refresh") {
+					if (!params.id || !params.subtype || !params.title || params.body === undefined || !params.anchors || params.anchors.length === 0) {
+						throw new Error("symbol_annotations refresh requires id, subtype, title, body, and at least one anchor");
+					}
+					const { annotation } = await symbolAnnotationOperations.refresh(
+						path,
+						params.id,
+						params.subtype,
+						params.title,
+						params.body,
+						resolveAnchorInputs(params.anchors),
+					);
+					details.annotation = annotation;
+					text = annotation ? formatAnnotationDetail(annotation) : `no annotation "${params.id}"`;
+				} else if (params.action === "scrub") {
+					if (!params.id) throw new Error("symbol_annotations scrub requires id");
+					const { scrubbed } = await symbolAnnotationOperations.scrub(path, params.id);
+					details.scrubbed = scrubbed;
+					text = scrubbed ? `scrubbed ${params.id}` : `"${params.id}" was already scrubbed or does not exist`;
+				} else if (params.action === "restore") {
+					if (!params.id) throw new Error("symbol_annotations restore requires id");
+					const { restored } = await symbolAnnotationOperations.restore(path, params.id);
+					details.restored = restored;
+					text = restored ? `restored ${params.id}` : `"${params.id}" was not scrubbed or does not exist`;
+				} else {
+					throw new Error(`unknown symbol_annotations action: ${String(params.action)}`);
+				}
+				return { content: [{ type: "text", text }], details };
+			},
+			renderCall(args, theme, context) {
+				const action = typeof args.action === "string" ? args.action : "";
+				const id = typeof args.id === "string" ? ` ${args.id}` : "";
+				const text = context.lastComponent instanceof Text ? context.lastComponent : new Text("", 0, 0);
+				text.setText(`${theme.fg("toolTitle", theme.bold("symbol_annotations"))} ${theme.fg("accent", action)}${theme.fg("dim", id)}`);
+				return text;
+			},
+			renderResult(result, { isPartial }, theme, context) {
+				if (isPartial) return new Text(theme.fg("warning", "Working on annotation..."), 0, 0);
+				const text = context.lastComponent instanceof Text ? context.lastComponent : new Text("", 0, 0);
+				if (context.isError) {
+					const errorText = result.content
+						.filter((block) => block.type === "text")
+						.map((block) => block.text)
+						.join("\n");
+					text.setText(theme.fg("error", errorText || "symbol_annotations failed"));
+					return text;
+				}
+				const details = result.details as SymbolAnnotationToolDetails | undefined;
+				if (details?.annotations) {
+					text.setText(formatAnnotationListSummary(details.annotations, theme));
+					return text;
+				}
+				if (details?.annotation) {
+					text.setText(formatAnnotationSummary(details.annotation, theme));
+					return text;
+				}
+				if (details?.scrubbed !== undefined) {
+					text.setText(details.scrubbed ? theme.fg("success", "scrubbed") : theme.fg("muted", "already scrubbed or not found"));
+					return text;
+				}
+				if (details?.restored !== undefined) {
+					text.setText(details.restored ? theme.fg("success", "restored") : theme.fg("muted", "not scrubbed or not found"));
+					return text;
+				}
+				text.setText(theme.fg("muted", "done"));
+				return text;
+			},
+		});
+
 		pi.registerTool({
 			name: "reachable_from",
 			label: "Reachable From",
@@ -696,6 +856,57 @@ export default function (pi: ExtensionAPI) {
 			},
 		});
 
+		pi.registerTool({
+			name: "workspace_map",
+			label: "Workspace Map",
+			description:
+				"A ranked, budget-bounded summary of the workspace's most structurally central symbols (aider-repomap-shaped) -- signature-only, highest-ranked first by PageRank over the populated call/reference graph, not full file dumps. Use when orienting in an unfamiliar or large codebase instead of reading many files one by one. Requires populate_symbol_graph to have been run for this workspace first; returns empty otherwise.",
+			promptSnippet: "Get a ranked, signature-only overview of the workspace's most central symbols",
+			promptGuidelines: [
+				"Prefer this over reading many files to get oriented in a large or unfamiliar codebase -- it surfaces the most-referenced symbols first, not an arbitrary file order.",
+				"A budget-truncated result means real symbols were left out, not that the workspace only has this many -- raise maxEntries/maxBytes for more.",
+			],
+			parameters: Type.Object({
+				path: Type.String({ description: "Absolute or cwd-relative path used to resolve which workspace to map" }),
+				maxNodes: Type.Number({ description: "Bounds the raw fetch from the graph before ranking" }),
+				maxEdges: Type.Number({ description: "Bounds the raw fetch from the graph before ranking" }),
+				maxEntries: Type.Number({ description: "Hard cap on the number of ranked entries returned" }),
+				maxBytes: Type.Number({ description: "Soft byte budget -- stops adding entries once exceeded, even under maxEntries" }),
+			}),
+			async execute(_toolCallId, params) {
+				const path = resolve(cwd, params.path);
+				const result = await codeIntelligenceOperations.workspaceMap(path, params.maxNodes, params.maxEdges, params.maxEntries, params.maxBytes);
+				const text =
+					result.entries.length === 0
+						? "No ranked symbols (has the graph been populated for this workspace?)."
+						: result.entries
+								.map(
+									(entry) => `${entry.kind} ${entry.name} -- ${entry.path}:${entry.line}:${entry.character}${entry.signature ? ` -- ${entry.signature}` : ""}`,
+								)
+								.join("\n");
+				return { content: [{ type: "text", text }], details: { result } };
+			},
+			renderCall(args, theme, context) {
+				const text = context.lastComponent instanceof Text ? context.lastComponent : new Text("", 0, 0);
+				text.setText(formatWorkspaceMapCall(args as { path?: unknown; maxEntries?: unknown }, theme));
+				return text;
+			},
+			renderResult(result, { expanded, isPartial }, theme, context) {
+				if (isPartial) return new Text(theme.fg("warning", "Ranking workspace symbols..."), 0, 0);
+				if (context.isError) {
+					const errorText = result.content
+						.filter((block) => block.type === "text")
+						.map((block) => block.text)
+						.join("\n");
+					return new Text(theme.fg("error", errorText || "workspace_map failed"), 0, 0);
+				}
+				const details = result.details as { result?: WorkspaceMapResult } | undefined;
+				const text = context.lastComponent instanceof Text ? context.lastComponent : new Text("", 0, 0);
+				text.setText(formatWorkspaceMapResult(details?.result, expanded, theme));
+				return text;
+			},
+		});
+
 		const gitOperations = createLectorGitOperations();
 		pi.registerTool({
 			name: "git_status",
@@ -848,6 +1059,168 @@ export default function (pi: ExtensionAPI) {
 			},
 		});
 
+		const findFilesOperations = createLectorFindFilesOperations();
+		pi.registerTool({
+			name: "find_files",
+			label: "Find Files",
+			description:
+				"Find files by glob/name pattern, distinct from content search -- the `find` half of the classic grep+find pair. Backed by ripgrep's own --files listing, respects .gitignore, skips node_modules/.git/build output. Bounded by maxResults and maxBytes.",
+			promptSnippet: "Find files by path/name glob pattern, not content",
+			promptGuidelines: [
+				"Use find_files to locate files by path or name pattern (e.g. every *.test.ts under a directory) -- use search_code instead when you need to match file content, not just the path.",
+			],
+			parameters: Type.Object({
+				directory: Type.String({ description: "Directory inside the project to search, absolute or relative to the current working directory" }),
+				patterns: Type.Array(Type.String(), {
+					description: "Glob pattern(s) to match file paths against, OR'd together -- a file matching any one pattern is included",
+					minItems: 1,
+				}),
+				maxResults: Type.Number({ description: "Maximum number of file paths to return before truncating" }),
+				maxBytes: Type.Number({ description: "Maximum total bytes of matched path text before truncating" }),
+			}),
+			async execute(_toolCallId, params) {
+				const directory = resolve(cwd, params.directory);
+				const result = await findFilesOperations.findFiles(params.patterns, directory, params.maxResults, params.maxBytes);
+				const text = result.paths.length === 0 ? "No files found." : result.paths.join("\n");
+				return { content: [{ type: "text", text }], details: { result } };
+			},
+			renderCall(args, theme, context) {
+				const text = context.lastComponent instanceof Text ? context.lastComponent : new Text("", 0, 0);
+				text.setText(formatFindFilesCall(args as { directory?: unknown; patterns?: unknown }, theme));
+				return text;
+			},
+			renderResult(result, { expanded, isPartial }, theme, context) {
+				if (isPartial) return new Text(theme.fg("warning", "Finding files..."), 0, 0);
+				if (context.isError) {
+					const errorText = result.content
+						.filter((block) => block.type === "text")
+						.map((block) => block.text)
+						.join("\n");
+					return new Text(theme.fg("error", errorText || "find_files failed"), 0, 0);
+				}
+				const details = result.details as { result?: FindFilesResult } | undefined;
+				const text = context.lastComponent instanceof Text ? context.lastComponent : new Text("", 0, 0);
+				text.setText(formatFindFilesResult(details?.result, expanded, theme));
+				return text;
+			},
+		});
+
+		const lineEditOperations = createLectorLineEditOperations();
+		pi.registerTool({
+			name: "line_edit",
+			label: "Line Edit",
+			description:
+				"Applies one or more per-line-hash-guarded edits to a file, atomically -- distinct from the generic edit tool's whole-file hash guard. A concurrent change to a line no edit here references never invalidates this call, unlike a whole-file guard where any edit anywhere in the file forces a re-read. Each edit's lines must currently hold the given hash(es) (from read tool content: hash each line's exact text yourself, or retry using the actualHash a hash-mismatch failure reports). All edits in one call land together, or none do.",
+			promptSnippet: "Apply per-line hash-guarded edits to a file, atomically",
+			promptGuidelines: [
+				"Prefer line_edit over the generic edit tool when editing a large or heavily concurrent file where you only need to touch a few specific lines -- it survives a concurrent change elsewhere in the file that a whole-file hash guard would reject.",
+				"A line's hash is not given to you ahead of time -- compute it yourself from content you already read (same algorithm as lineHashOf: sha256 of the exact line text, first 8 hex characters), or attempt the edit and use the actualHash a hash-mismatch failure reports to retry.",
+			],
+			parameters: Type.Object({
+				path: Type.String({ description: "Absolute or workspace-relative path to the file to edit" }),
+				edits: Type.Array(
+					Type.Union([
+						Type.Object({
+							kind: Type.Literal("replace"),
+							startLine: Type.Number({ description: "1-indexed first line of the inclusive range to replace" }),
+							endLine: Type.Number({ description: "1-indexed last line of the inclusive range to replace (same as startLine for a single line)" }),
+							expectedStartHash: Type.String({ description: "The hash startLine must currently hold" }),
+							expectedEndHash: Type.String({
+								description: "The hash endLine must currently hold (same value as expectedStartHash when startLine === endLine)",
+							}),
+							lines: Type.Array(Type.String(), { description: "Replacement lines -- an empty array deletes the range" }),
+						}),
+						Type.Object({
+							kind: Type.Literal("insertBefore"),
+							atLine: Type.Number({ description: "1-indexed anchor line to insert before" }),
+							expectedHash: Type.String({ description: "The hash atLine must currently hold" }),
+							lines: Type.Array(Type.String(), { description: "Lines to insert" }),
+						}),
+						Type.Object({
+							kind: Type.Literal("insertAfter"),
+							atLine: Type.Number({ description: "1-indexed anchor line to insert after" }),
+							expectedHash: Type.String({ description: "The hash atLine must currently hold" }),
+							lines: Type.Array(Type.String(), { description: "Lines to insert" }),
+						}),
+					]),
+					{ description: "One or more edits, all applied atomically -- non-overlapping line ranges required", minItems: 1 },
+				),
+			}),
+			async execute(_toolCallId, params) {
+				const absolutePath = resolve(cwd, params.path);
+				// The Pi tool schema can only express plain strings for hash fields (TypeBox has no
+				// concept of Lector's branded LineHash) -- the daemon's own domain validation is the
+				// real runtime check regardless of what TypeScript sees at this call site.
+				const result = await lineEditOperations.lineEdit(absolutePath, params.edits as unknown as LineEdit[]);
+				return { content: [{ type: "text", text: `${result.path}: ${result.previousHash} -> ${result.newHash}` }], details: { result } };
+			},
+			renderCall(args, theme, context) {
+				const text = context.lastComponent instanceof Text ? context.lastComponent : new Text("", 0, 0);
+				text.setText(formatLineEditCall(args as { path?: unknown; edits?: unknown }, theme));
+				return text;
+			},
+			renderResult(result, { isPartial }, theme, context) {
+				if (isPartial) return new Text(theme.fg("warning", "Applying line edit..."), 0, 0);
+				if (context.isError) {
+					const errorText = result.content
+						.filter((block) => block.type === "text")
+						.map((block) => block.text)
+						.join("\n");
+					return new Text(theme.fg("error", errorText || "line_edit failed"), 0, 0);
+				}
+				const details = result.details as { result?: LineEditOutcome } | undefined;
+				const text = context.lastComponent instanceof Text ? context.lastComponent : new Text("", 0, 0);
+				text.setText(formatLineEditResult(details?.result, theme));
+				return text;
+			},
+		});
+
+		const applyPatchOperations = createLectorApplyPatchOperations();
+		pi.registerTool({
+			name: "apply_patch",
+			label: "Apply Patch",
+			description:
+				"Applies a real unified diff (as `diff -u` / `git diff` produce) to a file, guarded by the whole-file hash you last observed there -- distinct from line_edit's per-line guards and the generic edit tool's plain replace. Hunk context is searched for near its own line-number hint rather than trusted as an exact offset, so the patch still applies correctly even if the file shifted slightly (e.g. unrelated lines added elsewhere) since the diff was generated.",
+			promptSnippet: "Apply a real unified diff to a file, whole-file hash guarded",
+			promptGuidelines: [
+				"Use apply_patch when you already have a unified diff (e.g. from a prior read's content, or produced by a diffing step) rather than reconstructing the full post-patch content yourself for the generic edit tool.",
+				"If a hunk's context can no longer be found, the file has drifted too far from what the patch assumed -- re-read the file and regenerate the patch, the same response as a stale hash on any other Lector edit tool.",
+			],
+			parameters: Type.Object({
+				path: Type.String({ description: "Absolute or workspace-relative path to the file to patch" }),
+				expectedHash: Type.String({ description: "The whole-file hash you last observed at path (from a prior read)" }),
+				patchText: Type.String({
+					description: "Real unified-diff text with one or more @@ hunks (--- / +++ file-header lines are optional and ignored if present)",
+				}),
+			}),
+			async execute(_toolCallId, params) {
+				const absolutePath = resolve(cwd, params.path);
+				// TypeBox has no concept of Lector's branded ContentHash -- the daemon's own domain
+				// validation is the real runtime check regardless of what TypeScript sees here.
+				const result = await applyPatchOperations.applyPatch(absolutePath, params.expectedHash as ContentHash, params.patchText);
+				return { content: [{ type: "text", text: `${result.path}: ${result.previousHash ?? "(new)"} -> ${result.newHash}` }], details: { result } };
+			},
+			renderCall(args, theme, context) {
+				const text = context.lastComponent instanceof Text ? context.lastComponent : new Text("", 0, 0);
+				text.setText(formatApplyPatchCall(args as { path?: unknown }, theme));
+				return text;
+			},
+			renderResult(result, { isPartial }, theme, context) {
+				if (isPartial) return new Text(theme.fg("warning", "Applying patch..."), 0, 0);
+				if (context.isError) {
+					const errorText = result.content
+						.filter((block) => block.type === "text")
+						.map((block) => block.text)
+						.join("\n");
+					return new Text(theme.fg("error", errorText || "apply_patch failed"), 0, 0);
+				}
+				const details = result.details as { result?: EditOutcome } | undefined;
+				const text = context.lastComponent instanceof Text ? context.lastComponent : new Text("", 0, 0);
+				text.setText(formatApplyPatchResult(details?.result, theme));
+				return text;
+			},
+		});
+
 		const packageSourceOperations = createLectorPackageSourceOperations();
 		pi.registerTool({
 			name: "package_source",

package/extension/src/line-edit-operations.ts

@@ -0,0 +1,34 @@
+import { type LineEdit, type LineEditOutcome, type LineHash, lineHashOf } from "@danypops/lector";
+import { lectorClient, withWorkspace, workspaceForPath } from "./lector-client.ts";
+import { toWorkspaceRelativePath } from "./workspace-relative-path.ts";
+
+/**
+ * Thin wrapper over workspace.lineEdit -- distinct from the generic edit tool (backed by
+ * exactEdit's whole-file hash guard, see edit-operations.ts): every edit here is guarded by
+ * its own referenced line(s)' hash, so a concurrent change to a line no edit references never
+ * invalidates this one. `path` is an absolute file path, the same convention edit-operations.ts
+ * already uses -- the workspace is resolved from the file itself, not a separate directory arg.
+ */
+export interface LineEditOperations {
+	lineEdit(path: string, edits: readonly LineEdit[]): Promise<LineEditOutcome>;
+	/** Pure, no daemon round trip -- computes the hash a line must still hold from content the caller already has (e.g. from a prior read), rather than requiring a dedicated "give me line hashes" read operation. */
+	lineHash(line: string): LineHash;
+}
+
+export function createLectorLineEditOperations(): LineEditOperations {
+	return {
+		async lineEdit(path, edits) {
+			return withWorkspace(
+				() => workspaceForPath(path),
+				async ({ workspaceId, root }) => {
+					const client = await lectorClient();
+					const relativePath = toWorkspaceRelativePath(root, path);
+					return client.call("workspace.lineEdit", { workspaceId, path: relativePath, edits });
+				},
+			);
+		},
+		lineHash(line) {
+			return lineHashOf(line);
+		},
+	};
+}

package/extension/src/line-edit-rendering.ts

@@ -0,0 +1,13 @@
+import type { LineEditOutcome } from "@danypops/lector";
+import type { LectorTheme } from "./lector-tui-theme.ts";
+
+export function formatLineEditCall(args: { path?: unknown; edits?: unknown }, theme: LectorTheme): string {
+	const path = typeof args.path === "string" ? args.path : "";
+	const count = Array.isArray(args.edits) ? args.edits.length : 0;
+	return `${theme.fg("toolTitle", theme.bold("line_edit"))} ${theme.fg("accent", path)} ${theme.fg("dim", `(${count} edit${count === 1 ? "" : "s"})`)}`;
+}
+
+export function formatLineEditResult(result: LineEditOutcome | undefined, theme: LectorTheme): string {
+	if (!result) return theme.fg("dim", "No result.");
+	return theme.fg("accent", `${result.path}: ${result.previousHash} -> ${result.newHash}`);
+}

package/extension/src/symbol-annotation-operations.ts

@@ -0,0 +1,99 @@
+import type { OperationInputs, OperationOutputs } from "@danypops/lector";
+import { lectorClient, withWorkspace, workspaceForCodeIntelligencePath } from "./lector-client.ts";
+
+/** A bare symbol position an anchor is given as -- symbolNodeId and the anchor's baseline file hash are derived server-side, never supplied by the caller. */
+export interface AnnotationAnchorInput {
+	readonly path: string;
+	readonly line: number;
+	readonly character: number;
+}
+
+/**
+ * Thin wrappers over Lector's annotation operations. Anchored to a workspace
+ * via the first anchor's own path (workspaceForCodeIntelligencePath) --
+ * every operation that needs a workspace already has at least one real
+ * anchor position or an id whose workspace the caller already knows.
+ */
+export interface SymbolAnnotationOperations {
+	create(
+		path: string,
+		subtype: string,
+		title: string,
+		body: string,
+		anchors: readonly AnnotationAnchorInput[],
+	): Promise<OperationOutputs["workspace.createAnnotation"]>;
+	get(path: string, id: string): Promise<OperationOutputs["workspace.getAnnotation"]>;
+	list(
+		path: string,
+		options?: { subtype?: string; status?: OperationInputs["workspace.listAnnotations"]["status"]; maxResults?: number },
+	): Promise<OperationOutputs["workspace.listAnnotations"]>;
+	refresh(
+		path: string,
+		id: string,
+		subtype: string,
+		title: string,
+		body: string,
+		anchors: readonly AnnotationAnchorInput[],
+	): Promise<OperationOutputs["workspace.refreshAnnotation"]>;
+	scrub(path: string, id: string): Promise<OperationOutputs["workspace.scrubAnnotation"]>;
+	restore(path: string, id: string): Promise<OperationOutputs["workspace.restoreAnnotation"]>;
+}
+
+export function createLectorSymbolAnnotationOperations(): SymbolAnnotationOperations {
+	return {
+		async create(path, subtype, title, body, anchors) {
+			return withWorkspace(
+				() => workspaceForCodeIntelligencePath(path),
+				async ({ workspaceId }) => {
+					const client = await lectorClient();
+					return client.call("workspace.createAnnotation", { workspaceId, subtype, title, body, anchors });
+				},
+			);
+		},
+		async get(path, id) {
+			return withWorkspace(
+				() => workspaceForCodeIntelligencePath(path),
+				async ({ workspaceId }) => {
+					const client = await lectorClient();
+					return client.call("workspace.getAnnotation", { workspaceId, id });
+				},
+			);
+		},
+		async list(path, options = {}) {
+			return withWorkspace(
+				() => workspaceForCodeIntelligencePath(path),
+				async ({ workspaceId }) => {
+					const client = await lectorClient();
+					return client.call("workspace.listAnnotations", { workspaceId, subtype: options.subtype, status: options.status, maxResults: options.maxResults });
+				},
+			);
+		},
+		async refresh(path, id, subtype, title, body, anchors) {
+			return withWorkspace(
+				() => workspaceForCodeIntelligencePath(path),
+				async ({ workspaceId }) => {
+					const client = await lectorClient();
+					return client.call("workspace.refreshAnnotation", { workspaceId, id, subtype, title, body, anchors });
+				},
+			);
+		},
+		async scrub(path, id) {
+			return withWorkspace(
+				() => workspaceForCodeIntelligencePath(path),
+				async ({ workspaceId }) => {
+					const client = await lectorClient();
+					return client.call("workspace.scrubAnnotation", { workspaceId, id });
+				},
+			);
+		},
+		async restore(path, id) {
+			return withWorkspace(
+				() => workspaceForCodeIntelligencePath(path),
+				async ({ workspaceId }) => {
+					const client = await lectorClient();
+					return client.call("workspace.restoreAnnotation", { workspaceId, id });
+				},
+			);
+		},
+	};
+}

package/extension/src/symbol-annotation-rendering.ts

@@ -0,0 +1,26 @@
+import type { SymbolAnnotation } from "@danypops/lector";
+import type { LectorTheme } from "./lector-tui-theme.ts";
+
+const STATUS_COLOR: Record<SymbolAnnotation["status"], "success" | "warning" | "dim"> = {
+	fresh: "success",
+	stale: "warning",
+	scrubbed: "dim",
+};
+
+/** One-line summary: status, title, subtype, id, anchor count -- the body is intentionally omitted (it can be long prose; the tool result's own text content carries it in full). */
+export function formatAnnotationSummary(annotation: SymbolAnnotation, theme: LectorTheme): string {
+	const status = theme.fg(STATUS_COLOR[annotation.status], `[${annotation.status}]`);
+	const anchorCount = `${annotation.anchors.length} anchor${annotation.anchors.length === 1 ? "" : "s"}`;
+	return `${status} ${theme.bold(annotation.title)} ${theme.fg("muted", `(${annotation.subtype})`)} -- ${anchorCount} -- ${theme.fg("dim", annotation.id)}`;
+}
+
+/** Full text for a tool result: summary line, body, and every anchor's exact symbol position. */
+export function formatAnnotationDetail(annotation: SymbolAnnotation): string {
+	const anchorLines = annotation.anchors.map((anchor) => `  - ${anchor.symbolNodeId}`).join("\n");
+	return `[${annotation.status}] ${annotation.title} (${annotation.subtype})\nid: ${annotation.id}\n\n${annotation.body}\n\nAnchors:\n${anchorLines}`;
+}
+
+export function formatAnnotationListSummary(annotations: readonly SymbolAnnotation[], theme: LectorTheme): string {
+	if (annotations.length === 0) return theme.fg("muted", "no annotations");
+	return annotations.map((annotation) => formatAnnotationSummary(annotation, theme)).join("\n");
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@danypops/pi-lector",
-	"version": "0.1.12",
+	"version": "0.2.0",
 	"description": "Pi host adapter for Lector: overrides read/write/edit with a daemon-backed, hash-guarded filesystem",
 	"license": "MIT",
 	"type": "module",
@@ -19,7 +19,7 @@
 	},
 	"dependencies": {
 		"@danypops/daemon-kit": "^0.4.0",
-		"@danypops/lector": "^0.1.10"
+		"@danypops/lector": "^0.1.15"
 	},
 	"devDependencies": {
 		"@earendil-works/pi-ai": "^0.81.1",