pi-fovea 0.3.2 → 0.4.0

package/README.md

@@ -17,7 +17,7 @@ _See the whole repo on every prompt, sharp where you work and cheap everywhere e
 
 </div>
 
-pi-fovea hands the model a map of your repo on every prompt. The repo compiles once into a code graph across languages, where symbols, files, and route anchors join into one network. Each question becomes an interest vector that diffuses over the graph as heat. The renderer converts the field into a token-capped view: full signatures near your task, one-liners a hop away, a skeleton of the rest.
+pi-fovea hands the model a map of your repo on every prompt. The repo compiles once into a code graph across languages, where symbols, files, and route anchors join into one network. Each question becomes an interest vector that diffuses over the graph as heat. The renderer converts the field into a token-capped view: exact source locations and full signatures near your task, typed one-hop relationships next, and a skeleton of the rest.
 
 After each assistant turn the map re-syncs incrementally. Detection reads content hashes instead of tool events, so edits made by pi's edit/write tools, a fabric_exec inner `pi.edit`, a bash heredoc, a subagent, or an editor save outside the session all land identically. A clean turn stays silent. A turn that moves route anchors or warms files you have not looked at says so.
 
@@ -26,9 +26,33 @@ After each assistant turn the map re-syncs incrementally. Detection reads conten
 | Command | Ask | Answer |
 |---|---|---|
 | `fovea_sketch` | where is everything? | the repo as a silhouette, with feature anchors and inferred regions ranked by mass |
-| `fovea_focus` | what is this? | centered on a symbol, route path, or env key: hot nodes as signatures, neighbors as one-liners |
+| `fovea_focus` | what is this? | centered on a symbol, route path, or env key: exact hot signatures, typed direct relationships, then warm one-liners |
 | `fovea_dwell` | what else? | diffuses the field one step further and returns the delta |
 | `fovea_impact` | what does this touch? | warms everything a file, symbol, or PR base reaches across languages |
+| `grep` *(default override)* | where does this concept lead? | the same graph-backed focus through grep's familiar `pattern/path/glob/...` signature |
+
+Focus normalizes camelCase and common inflections, so an approximate name such as `switchServer` can resolve `switchingServers`. If a query is still uncertain, Fovea returns nearby symbols with locations instead of a dead miss. Direct graph edges are labeled (caller, callee, route, shared literal, co-change), while unrelated same-file siblings remain collapsed.
+
+The **Replace grep** toggle makes Fovea own Pi's `grep` tool slot. It is on by default. Familiar calls such as `grep({ pattern: "CreateUser", path: "src" })` navigate the code graph first; use `bash` with `rg` only when you need exact matching lines. Disable the toggle to restore the previous grep implementation. Changing the toggle reloads extensions so pi-fabric captures the same override and `pi.grep(...)` follows it inside `fabric_exec`.
+
+### pi-fabric
+
+Captured extension tools live under Fabric's `extensions` provider. Use the direct proxy when the action is known:
+
+```ts
+const result = await extensions.fovea_focus({ query: "CreateUserHandler", maxTokens: 2000 });
+return result.text;
+```
+
+For dynamic discovery, pass an object to `tools.search` and keep the returned namespaced ref:
+
+```ts
+const [action] = await tools.search({ query: "fovea_focus", limit: 5 });
+if (!action) return "Fovea is not captured";
+return tools.call({ ref: action.ref, args: { query: "CreateUserHandler" } });
+```
+
+The stable explicit ref is `extensions.fovea_focus`, not bare `fovea_focus` or `fovea.fovea_focus`.
 
 Two slash commands on top:
 
@@ -99,6 +123,7 @@ Global settings live in `~/.pi/agent/fovea.json`. A trusted repo-level override
 | `sync.ackClean` | `false` | toast after clean structural turns |
 | `sync.warmFileThreshold` | `2` | warmed files unseen by the model that justify turning red |
 | `tools.defaultBudget` | `2000` | fallback maxTokens for the fovea_* tools |
+| `tools.replaceGrep` | `true` | replace Pi's grep slot with graph-backed Fovea navigation |
 
 ## How routes are found
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-fovea",
-  "version": "0.3.2",
+  "version": "0.4.0",
   "description": "Token-budgeted repo mapping for agent sessions: foveated heat diffusion over a cross-language code graph, with progressive disclosure.",
   "type": "module",
   "license": "MIT",

package/skills/pi-fovea/SKILL.md

@@ -10,8 +10,8 @@ pi-fovea maintains a cross-language code graph of the working repository — rou
 ## The loop
 
 1. **`fovea_sketch`** — silhouettes only. Route/anchor inventory plus directory blobs ranked by heat. Start here in an unfamiliar repo. ~256–1024 tokens.
-2. **`fovea_focus` `<query>`** — point at a symbol name, route path (`/api/users/{id}`), env key, or file path. Hot nodes come back with full signatures; warm neighbors as one-liners; the periphery stays collapsed. Already-shown nodes are suppressed, so repeated focus calls stay cheap.
-3. **`fovea_dwell`** — optional second look. If a focus footer says more nodes are lit below the token threshold, dwell (diffusion time ×2) surfaces exactly those newcomers.
+2. **`fovea_focus` `<query>`** — point at a symbol name (close spellings work), route path (`/api/users/{id}`), env key, or file path. Hot nodes carry exact source locations and signatures; direct callers/callees and other typed edges are labeled; the periphery stays collapsed. A true miss suggests nearby symbols. Already-shown nodes are suppressed, so repeated focus calls stay cheap.
+3. **`fovea_dwell`** — optional second look. If a focus footer reports a remaining low-acuity periphery, dwell (diffusion time ×2) returns newly warmed neighbors.
 4. **`fovea_impact`** — blast radius. Seed with explicit repo-relative `files`, symbol names for what-if analysis, or uncommitted changes (`base` works PR-style against a ref). Output is the predicted co-change cascade ordered by warmth.
 
 All four accept `maxTokens` (256–16000). Budget is roughly 4 chars per token.
@@ -32,8 +32,9 @@ Sync is **mutation-path agnostic**: pi's edit/write tools, a pi-fabric `fabric_e
 
 When writing or editing code **inside a `fabric_exec` program**, the fovea tools exist but the fabric sandbox has no built-in knowledge of them (it lazy-loads tools). Key points:
 
-- Inside `fabric_exec`, discover them once with `await tools.search("fovea")` and call them through `tools.call({ ref, args })` — e.g. `{ ref: "fovea_focus", args: { query: "CreateUserHandler" } }`. They are ordinary pi tools; there is no fabric-specific wrapper.
-- Prefer a single `fovea_impact` call over hand-rolled grep fan-outs when computing what an edit touches — the graph already resolved imports/calls across Go, TypeScript, Python, and Java.
+- Inside `fabric_exec`, captured extension tools use the `extensions` provider. For a known action call `await extensions.fovea_focus({ query: "CreateUserHandler", maxTokens: 6000 })`.
+- For dynamic discovery, use `const hits = await tools.search({ query: "fovea_focus" })`, then call the returned namespaced ref with `tools.call({ ref: hits[0].ref, args: { query: "CreateUserHandler", maxTokens: 6000 } })`. The stable explicit ref is `extensions.fovea_focus`; bare `fovea_focus` and `fovea.fovea_focus` are invalid.
+- Prefer a single `extensions.fovea_impact(...)` call over hand-rolled grep fan-outs when computing what an edit touches — the graph already resolved imports/calls across Go, TypeScript, Python, and Java.
 - Any file mutation performed by the program (including `pi.edit`/`pi.write` calls inside the sandbox) is picked up by turn sync automatically, so post-edit verification does not need a re-sketch.
 - The sketch `details` field carries counts (`files`, `nodes`, `anchors`); the hot-node list is the graph's highest-value entry points. On an unfamiliar repo, fetch it once and reuse instead of rediscovering entry points per call.
 
@@ -43,4 +44,4 @@ The same engine runs headlessly as the `fovea` binary (repo root scan, plus JSON
 
 ## Settings
 
-`/fovea settings` in the TUI, or `fovea.config.json` at repo or user level. Relevant knobs: `sync.enabled`, `sync.budget`, `sync.warmFileThreshold` (files that must escape before a red sync fires), `tools.defaultBudget`.
+`/fovea settings` in the TUI, or `fovea.json` under `~/.pi/agent/` or a trusted repo's `.pi/` directory. Relevant knobs: `sync.enabled`, `sync.budget`, `sync.warmFileThreshold` (files that must escape before a red sync fires), `tools.defaultBudget`, and `tools.replaceGrep` (default on; installs a grep-compatible Fovea override and reloads extensions).

package/src/core/astgrep.ts

@@ -83,10 +83,52 @@ export const groupByLang = (files: string[]): Map<string, string[]> => {
   return m;
 };
 
-// `ast-grep outline` — uniform symbol source across languages. Text format:
-//   <file>
-//   <line>: <signature source line>
-//        <kind>: <name>        (children: methods/fields, indented)
+// `ast-grep outline` is the uniform symbol source across languages.
+// Expanded JSON is primary; the legacy text view remains as a compatibility fallback.
+export interface OutlineRange {
+  start: { line: number; column: number };
+  end?: { line: number; column: number };
+}
+
+export interface OutlineSymbol {
+  role: "item" | "member";
+  symbolType: string;
+  name: string;
+  range: OutlineRange;
+  signature: string;
+  astKind?: string;
+  members?: OutlineSymbol[];
+}
+
+export interface OutlineFile {
+  path: string;
+  language: string;
+  items: OutlineSymbol[];
+}
+
+// Expanded JSON preserves each member's own range and signature. Return
+// undefined when the installed ast-grep predates this interface so callers can
+// fall back without presenting parent locations as exact member locations.
+export const outlineStructured = (files: string[], lang: string, cwd: string): OutlineFile[] | undefined => {
+  const out: OutlineFile[] = [];
+  for (let i = 0; i < files.length; i += CHUNK) {
+    const stdout = run(
+      ["outline", "--json=compact", "--view=expanded", ...files.slice(i, i + CHUNK)],
+      cwd,
+    );
+    if (!stdout.trim()) return undefined;
+    try {
+      const parsed = JSON.parse(stdout) as OutlineFile[];
+      if (!Array.isArray(parsed)) return undefined;
+      for (const file of parsed) out.push(file);
+    } catch {
+      return undefined;
+    }
+  }
+  void lang;
+  return out;
+};
+
 export const outline = (files: string[], lang: string, cwd: string): string => {
   let out = "";
   for (let i = 0; i < files.length; i += CHUNK) {

package/src/core/build.ts

@@ -30,7 +30,7 @@ export interface FileFacts {
   sigs?: FileSigs;
 }
 
-const CACHE_VERSION = 6; // bump when extractor semantics change
+const CACHE_VERSION = 7; // bump when extractor semantics change
 const IGNORE_DIRS = new Set([".git", "node_modules", "dist", "vendor", ".venv", "venv", "target", "coverage", ".next", "build", "__pycache__", ".pi", ".pi-fovea", "deps", "_build", ".tox", "Pods"]);
 const MAX_FILES = 24000;
 // Generated dependency manifests are enormous and carry no first-class routes.

package/src/core/config.ts

@@ -22,6 +22,8 @@ interface FoveaSyncConfig {
 interface FoveaToolsConfig {
   /** Budget applied when a fovea_* tool call omits maxTokens. */
   defaultBudget: number;
+  /** Replace Pi's grep slot with a graph-backed fovea_focus adapter. */
+  replaceGrep: boolean;
 }
 
 export interface FoveaConfig {
@@ -38,6 +40,7 @@ export const DEFAULT_FOVEA_CONFIG: FoveaConfig = {
   },
   tools: {
     defaultBudget: 2000,
+    replaceGrep: true,
   },
 };
 
@@ -81,6 +84,7 @@ const applyPartial = (base: FoveaConfig, partial: unknown): FoveaConfig => {
     },
     tools: {
       defaultBudget: intValue("tools.defaultBudget", tools.defaultBudget, base.tools.defaultBudget),
+      replaceGrep: boolValue(tools.replaceGrep, base.tools.replaceGrep),
     },
   };
 };

package/src/core/extract.ts

@@ -9,7 +9,10 @@ import {
   groupByLang,
   isConfigFile,
   outline,
+  outlineStructured,
   patternRunAll,
+  type OutlineFile,
+  type OutlineSymbol,
 } from "./astgrep.js";
 import type {
   CallSite,
@@ -102,6 +105,104 @@ export const deriveName = (sig: string, lang: string, parentHint?: string): Name
   return { name: first.replace(/^[*&]+/, "") || "?", kind: "decl" };
 };
 
+const OUTLINE_KINDS: Record<string, NodeKind> = {
+  class: "class",
+  struct: "class",
+  object: "class",
+  interface: "interface",
+  trait: "interface",
+  protocol: "interface",
+  enum: "type",
+  type: "type",
+  alias: "type",
+  function: "function",
+  method: "method",
+  field: "field",
+  property: "field",
+  constant: "decl",
+  variable: "decl",
+};
+
+const outlineKind = (symbol: OutlineSymbol, lang: string): NodeKind => {
+  if (symbol.symbolType === "constructor") return "method";
+  const mapped = OUTLINE_KINDS[symbol.symbolType];
+  if (symbol.role === "member" && mapped) return mapped;
+  const derived = deriveName(symbol.signature, lang).kind;
+  if (derived !== "decl") return derived;
+  return mapped ?? derived;
+};
+
+const identifierRe = (name: string): RegExp =>
+  new RegExp(`(^|[^A-Za-z0-9_$])${name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}([^A-Za-z0-9_$]|$)`);
+
+const topLocation = (
+  file: string,
+  item: OutlineSymbol,
+  cwd: string,
+  sourceCache: Map<string, string[]>,
+): { line: number; sig: string } => {
+  let line = item.range.start.line + 1;
+  let sig = cleanSig(item.signature || item.name);
+  if (item.name && (!identifierRe(item.name).test(sig) || /^@/.test(sig))) {
+    let lines = sourceCache.get(file);
+    if (!lines) {
+      try {
+        lines = readFileSync(join(cwd, file), "utf8").split("\n");
+      } catch {
+        lines = [];
+      }
+      sourceCache.set(file, lines);
+    }
+    const end = Math.min(lines.length - 1, item.range.end?.line ?? item.range.start.line + 12);
+    for (let i = item.range.start.line; i <= end; i++) {
+      const candidate = lines[i];
+      if (candidate && identifierRe(item.name).test(candidate)) {
+        line = i + 1;
+        sig = cleanSig(candidate);
+        break;
+      }
+    }
+  }
+  return { line, sig };
+};
+
+const parseStructuredOutline = (files: OutlineFile[], cwd: string): SymbolRec[] => {
+  const out: SymbolRec[] = [];
+  const sourceCache = new Map<string, string[]>();
+  for (const record of files) {
+    const file = record.path.replace(/^\.\//, "");
+    const concreteParents = new Set(
+      record.items.filter((item) => item.symbolType !== "object").map((item) => item.name),
+    );
+    for (const item of record.items) {
+      const kind = outlineKind(item, record.language);
+      let name = item.name;
+      if (kind === "method") {
+        const derived = deriveName(item.signature, record.language);
+        if (derived.kind === "method" && derived.name.includes(".")) name = derived.name;
+      }
+      // Rust impl/object outlines repeat the concrete type. Keep its members,
+      // but do not emit a duplicate parent node when the struct is local.
+      if (!(item.symbolType === "object" && concreteParents.has(item.name))) {
+        const location = topLocation(file, item, cwd, sourceCache);
+        out.push({ name, kind, file, line: location.line, sig: location.sig, lang: record.language });
+      }
+      for (const member of item.members ?? []) {
+        const memberKind = outlineKind(member, record.language);
+        out.push({
+          name: `${item.name}.${member.name}`,
+          kind: memberKind,
+          file,
+          line: member.range.start.line + 1,
+          sig: cleanSig(member.signature || `${memberKind} ${item.name}.${member.name}`),
+          lang: record.language,
+        });
+      }
+    }
+  }
+  return dedupe(out, (symbol) => `${symbol.name}@${symbol.file}`);
+};
+
 const parseOutlineText = (text: string, lang: string): SymbolRec[] => {
   const out: SymbolRec[] = [];
   let file = "";
@@ -128,7 +229,8 @@ const parseOutlineText = (text: string, lang: string): SymbolRec[] => {
           name: `${top.name}.${name}`,
           kind: kindOf(child[2]!),
           file,
-          line: top.line, // outline children carry no line; point at parent
+          line: top.line,
+          lineApproximate: true,
           sig: `${kindOf(child[2]!)} ${top.name}.${name}`,
           lang,
         });
@@ -145,11 +247,19 @@ const parseOutlineText = (text: string, lang: string): SymbolRec[] => {
 export const extractSymbols = (files: string[], cwd: string): SymbolRec[] => {
   const out: SymbolRec[] = [];
   for (const [lang, langFiles] of groupByLang(files)) {
+    const structured = outlineStructured(langFiles, lang, cwd);
+    if (structured) {
+      const parsed = parseStructuredOutline(structured, cwd);
+      if (parsed.length || structured.some((file) => file.items.length > 0)) {
+        pushAll(out, parsed);
+        continue;
+      }
+    }
     const text = outline(langFiles, lang, cwd);
     if (!text.trim()) continue;
     pushAll(out, parseOutlineText(text, lang));
   }
-  return out.filter((s) => s.file);
+  return out.filter((symbol) => symbol.file);
 };
 
 // --- imports ------------------------------------------------------------------

package/src/core/ops.ts

@@ -11,11 +11,11 @@ import { hasAstGrep } from "./astgrep.js";
 import { assembleGraph, listFiles, loadFacts, type FileFacts } from "./build.js";
 import { loadRepoRules } from "./anchors.js";
 import { buildCsr, chebyshevVectors, chooseOrder, heatField, type Csr } from "./heat.js";
-import { revealFoveated, revealGroups, tokenEstimate, type GroupLine } from "./render.js";
+import { formatNodeLocation, revealFoveated, revealGroups, tokenEstimate, type GroupLine } from "./render.js";
 import { getSession, TK_ORDER } from "./session.js";
 import { detectBasins } from "./basins.js";
 import { classifyLiteral, normalizeLiteral, buildJoinIndex, type JoinIndex } from "./join.js";
-import type { Graph } from "./types.js";
+import type { Graph, NodeRec } from "./types.js";
 
 export interface OpResult {
   text: string;
@@ -81,7 +81,87 @@ export const ensureState = (root: string): RepoState => {
 
 // --- seed resolution ------------------------------------------------------------
 
-export interface SeedResolution { seeds: number[]; note: string; }
+export interface SeedSuggestion {
+  index: number;
+  name: string;
+  file: string;
+  line: number;
+  lineApproximate?: boolean;
+  score: number;
+}
+
+export interface SeedResolution {
+  seeds: number[];
+  note: string;
+  suggestions: SeedSuggestion[];
+}
+
+const QUERY_STOP_WORDS = new Set([
+  "a", "an", "and", "are", "do", "does", "find", "for", "happen", "happens", "how",
+  "in", "is", "of", "on", "please", "the", "this", "to", "what", "where", "which", "with",
+]);
+
+const stemIdentifier = (term: string): string => {
+  if (term.length > 5 && term.endsWith("ing")) return term.slice(0, -3);
+  if (term.length > 4 && term.endsWith("ies")) return `${term.slice(0, -3)}y`;
+  if (term.length > 4 && /(ches|shes|sses|xes|zes)$/.test(term)) return term.slice(0, -2);
+  if (term.length > 3 && term.endsWith("s") && !term.endsWith("ss")) return term.slice(0, -1);
+  return term;
+};
+
+const identifierTerms = (value: string): string[] => {
+  const split = value
+    .replace(/([a-z0-9])([A-Z])/g, "$1 $2")
+    .replace(/([A-Z]+)([A-Z][a-z])/g, "$1 $2")
+    .toLowerCase()
+    .split(/[^a-z0-9]+/)
+    .filter((term) => term.length > 1 && !QUERY_STOP_WORDS.has(term))
+    .map(stemIdentifier)
+    .filter((term) => !QUERY_STOP_WORDS.has(term));
+  return [...new Set(split)];
+};
+
+const shortSymbolName = (name: string): string => name.slice(name.lastIndexOf(".") + 1);
+
+const diceSimilarity = (a: string, b: string): number => {
+  if (a === b) return 1;
+  if (a.length < 2 || b.length < 2) return 0;
+  const left = new Map<string, number>();
+  for (let i = 0; i < a.length - 1; i++) {
+    const pair = a.slice(i, i + 2);
+    left.set(pair, (left.get(pair) ?? 0) + 1);
+  }
+  let overlap = 0;
+  for (let i = 0; i < b.length - 1; i++) {
+    const pair = b.slice(i, i + 2);
+    const count = left.get(pair) ?? 0;
+    if (count > 0) {
+      overlap++;
+      left.set(pair, count - 1);
+    }
+  }
+  return (2 * overlap) / (a.length + b.length - 2);
+};
+
+const symbolSimilarity = (query: string, node: NodeRec): number => {
+  const queryTerms = identifierTerms(query);
+  const candidateTerms = identifierTerms(shortSymbolName(node.name));
+  const candidateSet = new Set(candidateTerms);
+  const shared = queryTerms.filter((term) => candidateSet.has(term)).length;
+  const coverage = queryTerms.length ? shared / queryTerms.length : 0;
+  const precision = candidateTerms.length ? shared / candidateTerms.length : 0;
+  const tokenScore = 0.72 * coverage + 0.28 * precision;
+  const charScore = diceSimilarity(queryTerms.join(""), candidateTerms.join(""));
+  return Math.max(tokenScore, charScore);
+};
+
+const sameIdentifierTerms = (query: string, name: string): boolean => {
+  const queryTerms = identifierTerms(query);
+  const candidateTerms = identifierTerms(shortSymbolName(name));
+  if (!queryTerms.length || queryTerms.length !== candidateTerms.length) return false;
+  const candidateSet = new Set(candidateTerms);
+  return queryTerms.every((term) => candidateSet.has(term));
+};
 
 export const resolveSeeds = (state: RepoState, query: string): SeedResolution => {
   const g = state.graph;
@@ -134,6 +214,13 @@ export const resolveSeeds = (state: RepoState, query: string): SeedResolution =>
       }
     }
   }
+  if (scored.size === 0) {
+    g.nodes.forEach((node, i) => {
+      if (node.kind !== "file" && node.kind !== "anchor" && sameIdentifierTerms(q, node.name)) {
+        bump(i, 0.7);
+      }
+    });
+  }
   // File path suffix (e.g. "web/api.ts").
   for (const f of g.files) {
     if (f === q || f.endsWith(`/${q}`)) {
@@ -148,7 +235,22 @@ export const resolveSeeds = (state: RepoState, query: string): SeedResolution =>
   const seeds = ranked.map(([i]) => i);
   const names = ranked.slice(0, 4).map(([i, s]) => `${g.nodes[i]!.name}${s < 1 ? "~" : ""}`);
   const note = seeds.length ? `${seeds.length} seeds (${names.join(", ")}${seeds.length > 4 ? ", …" : ""})` : "no seeds matched";
-  return { seeds, note };
+  const suggestions = seeds.length
+    ? []
+    : g.nodes
+      .map((node, index) => ({ node, index, score: symbolSimilarity(q, node) }))
+      .filter(({ node, score }) => node.kind !== "file" && node.kind !== "anchor" && score >= 0.34)
+      .sort((a, b) => b.score - a.score || a.node.name.localeCompare(b.node.name) || a.node.file.localeCompare(b.node.file))
+      .slice(0, 5)
+      .map(({ node, index, score }) => ({
+        index,
+        name: node.name,
+        file: node.file,
+        line: node.line,
+        lineApproximate: node.lineApproximate,
+        score,
+      }));
+  return { seeds, note, suggestions };
 };
 
 const seedVector = (n: number, seeds: number[]): Float64Array => {
@@ -260,12 +362,38 @@ export const focus = (root: string, query: string, budget?: number): OpResult =>
   const g = state.graph;
   const session = getSession(root);
   const B = clampBudget(budget, 2000);
-  const { seeds, note } = resolveSeeds(state, query);
+  const { seeds, note, suggestions } = resolveSeeds(state, query);
   if (!seeds.length) {
+    const renderMiss = (count: number): string => {
+      const nearby = suggestions.slice(0, count).map((suggestion) => {
+        const node = g.nodes[suggestion.index]!;
+        return `  ? ${node.name} — ${formatNodeLocation(node)} — ${node.sig}`;
+      });
+      const guidance = suggestions.length
+        ? "Retry fovea_focus with one of these names, a route path (/api/...), or a file path."
+        : "Try a symbol name, a route path (/api/...), or a file path. Run fovea_sketch for the map silhouette first.";
+      return [
+        `fovea focus "${query}": ${note}.`,
+        ...(nearby.length ? ["Nearby symbols:", ...nearby] : []),
+        guidance,
+      ].join("\n");
+    };
+    let shown = suggestions.length;
+    let text = renderMiss(shown);
+    while (shown > 0 && tokenEstimate(text) > B) text = renderMiss(--shown);
     return {
-      text: `fovea focus "${query}": ${note}. Try a symbol name, a route path (/api/...), or a file path. Run fovea_sketch for the map silhouette first.`,
-      tokens: 0,
-      details: { seeds: 0 },
+      text,
+      tokens: tokenEstimate(text),
+      details: {
+        seeds: 0,
+        suggestions: suggestions.slice(0, shown).map(({ name, file, line, lineApproximate, score }) => ({
+          name,
+          file,
+          line,
+          lineApproximate,
+          score: Number(score.toFixed(3)),
+        })),
+      },
     };
   }
   const key = `${state.version}:${[...seeds].sort((a, b) => a - b).join(",")}`;
@@ -280,6 +408,7 @@ export const focus = (root: string, query: string, budget?: number): OpResult =>
   const fit = revealFoveated(g, field, {
     header: `fovea focus "${query}" · ${note} · t=${t}`,
     disclosed: session.disclosed,
+    seeds,
     budget: B,
   });
   for (const id of fit.revealedIds) session.disclosed.add(id);
@@ -315,6 +444,7 @@ export const dwell = (root: string, factor?: number, budget?: number): OpResult
   const fit = revealFoveated(g, field, {
     header: `fovea dwell · t ${from}→${to} · delta`,
     disclosed: session.disclosed,
+    seeds: session.seeds,
     budget: B,
   });
   for (const id of fit.revealedIds) session.disclosed.add(id);

package/src/core/render.ts

@@ -4,13 +4,73 @@
 // Budget conformance is a prefix fit: candidates sorted by heat, binary search
 // on prefix length — aider's render-and-count loop generalized to a field.
 
-import type { Graph } from "./types.js";
+import type { Edge, EdgeKind, Graph, NodeRec } from "./types.js";
 
 export const tokenEstimate = (text: string): number => Math.ceil(text.length / 4);
 
 export const HOT_TIER = 0.3;
 export const WARM_TIER = 0.02;
 export const HEAT_EPS = 1e-9;
+export const MAX_UNRELATED_WARM_PER_FILE = 4;
+
+export const formatNodeLocation = (node: NodeRec): string => {
+  if (node.kind === "file" || node.line <= 0) return node.file;
+  if (node.lineApproximate) return `${node.file} (member line unavailable)`;
+  return `${node.file}:${node.line}`;
+};
+
+interface DirectRelation {
+  kind: EdgeKind;
+  label: string;
+  priority: number;
+  weight: number;
+}
+
+const RELATION_PRIORITY: Record<EdgeKind, number> = {
+  contains: 0,
+  cochange: 1,
+  imports: 2,
+  join: 3,
+  anchors: 4,
+  tests: 5,
+  inherits: 6,
+  invokes: 7,
+};
+
+const relationLabel = (edge: Edge, seedAtA: boolean, candidate: NodeRec): string => {
+  switch (edge.kind) {
+    case "invokes": return seedAtA ? "→ callee" : "← caller";
+    case "imports": return seedAtA ? "→ import" : "← importer";
+    case "tests": return seedAtA ? "→ subject" : "← test";
+    case "inherits": return seedAtA ? "→ parent" : "← subclass";
+    case "anchors": return seedAtA ? candidate.kind === "file" ? "→ feature file" : "→ handler" : "← route";
+    case "join": return "↔ shared literal";
+    case "cochange": return "↔ co-change";
+    case "contains": return seedAtA ? "◇ member" : "◇ file";
+  }
+};
+
+const directRelations = (g: Graph, seeds: ReadonlySet<number>): Map<number, DirectRelation> => {
+  const out = new Map<number, DirectRelation>();
+  for (const edge of g.edges) {
+    const aSeed = seeds.has(edge.a);
+    const bSeed = seeds.has(edge.b);
+    if (aSeed === bSeed) continue;
+    const node = aSeed ? edge.b : edge.a;
+    const relation: DirectRelation = {
+      kind: edge.kind,
+      label: relationLabel(edge, aSeed, g.nodes[node]!),
+      priority: RELATION_PRIORITY[edge.kind],
+      weight: edge.w,
+    };
+    const current = out.get(node);
+    if (!current || relation.priority > current.priority ||
+      (relation.priority === current.priority && relation.weight > current.weight)) {
+      out.set(node, relation);
+    }
+  }
+  return out;
+};
 
 export interface FitResult {
   text: string;
@@ -33,6 +93,7 @@ export interface RevealOptions {
   header?: string;
   disclosed?: ReadonlySet<string>;
   exclude?: ReadonlySet<string>; // hard exclusion (e.g. seeds for impact)
+  seeds?: readonly number[];
   budget: number;
   maxCandidates?: number;
 }
@@ -47,17 +108,25 @@ export const revealFoveated = (
   if (vmax <= 0) {
     return { text: `${opts.header ?? "fovea"}\n(nothing lit — field is zero)`, tokens: 0, shown: 0, suppressed: 0, litTotal: 0, truncated: false, revealedIds: [] };
   }
+  const seedSet = new Set(opts.seeds ?? []);
+  const relations = directRelations(g, seedSet);
   const candidates: number[] = [];
   let suppressed = 0;
   for (let i = 0; i < g.nodes.length; i++) {
     const h = field[i]! / vmax;
-    if (h < WARM_TIER * 0.1 || field[i]! < HEAT_EPS) continue;
+    const direct = relations.get(i);
+    if ((!direct || direct.kind === "contains") && (h < WARM_TIER * 0.1 || field[i]! < HEAT_EPS)) continue;
     const id = g.nodes[i]!.id;
     if (opts.exclude?.has(id)) continue;
     if (opts.disclosed?.has(id)) { suppressed++; continue; }
     candidates.push(i);
   }
-  candidates.sort(cmpNodes(g, field));
+  const byHeat = cmpNodes(g, field);
+  candidates.sort((a, b) => {
+    const aPriority = seedSet.has(a) ? 2 : relations.get(a)?.kind === "contains" ? 0 : relations.has(a) ? 1 : 0;
+    const bPriority = seedSet.has(b) ? 2 : relations.get(b)?.kind === "contains" ? 0 : relations.has(b) ? 1 : 0;
+    return bPriority - aPriority || byHeat(a, b);
+  });
   const cap = opts.maxCandidates ?? 400;
   const capped = candidates.slice(0, cap);
   const litTotal = capped.length;
@@ -67,19 +136,39 @@ export const revealFoveated = (
   // budget can shrink the periphery too; appending is byte-monotone, hence the
   // binary search is exact and the output can never exceed the budget.
   const glowCounts = new Map<string, number>();
+  const warmPerFile = new Map<string, number>();
   const lines: string[] = [];
   const ids: string[] = [];
   for (const i of capped) {
-    const n = g.nodes[i]!;
+    const node = g.nodes[i]!;
     const h = field[i]! / vmax;
-    if (h >= HOT_TIER) {
-      lines.push(n.kind === "file" ? `▒ ${n.file}` : n.kind === "anchor" ? `⚑ ${n.sig}` : `▲ ${n.file}:${n.line}  ${n.sig}`);
-      ids.push(n.id);
-    } else if (h >= WARM_TIER) {
-      lines.push(`  · ${n.name} (${n.kind}) ${n.file}:${n.line}`);
-      ids.push(n.id);
+    const relation = relations.get(i);
+    const semanticRelation = relation && relation.kind !== "contains" ? relation : undefined;
+    const context = seedSet.has(i) ? "  [focus]" : relation ? `  [${relation.label}]` : "";
+    if (h >= HOT_TIER || seedSet.has(i)) {
+      lines.push(
+        node.kind === "file"
+          ? `▒ ${node.file}${context}`
+          : node.kind === "anchor"
+            ? `⚑ ${node.sig}${context}`
+            : `▲ ${formatNodeLocation(node)}  ${node.sig}${context}`,
+      );
+      ids.push(node.id);
+    } else if (h >= WARM_TIER || semanticRelation) {
+      const warmCount = warmPerFile.get(node.file) ?? 0;
+      if (!semanticRelation && node.kind !== "file" && warmCount >= MAX_UNRELATED_WARM_PER_FILE) {
+        glowCounts.set(node.file, (glowCounts.get(node.file) ?? 0) + 1);
+        continue;
+      }
+      if (!semanticRelation && node.kind !== "file") warmPerFile.set(node.file, warmCount + 1);
+      lines.push(
+        semanticRelation
+          ? `  ${semanticRelation.label}  ${node.name} (${node.kind}) ${formatNodeLocation(node)}`
+          : `  · ${node.name} (${node.kind}) ${formatNodeLocation(node)}`,
+      );
+      ids.push(node.id);
     } else {
-      glowCounts.set(n.file, (glowCounts.get(n.file) ?? 0) + 1);
+      glowCounts.set(node.file, (glowCounts.get(node.file) ?? 0) + 1);
     }
   }
   const glowLines = [...glowCounts.entries()]
@@ -89,11 +178,12 @@ export const revealFoveated = (
   const individual = lines.length;
 
   const header = `${opts.header ?? "fovea"} · lit ${litTotal}${suppressed ? `, ${suppressed} seen` : ""}`;
+  const collapsed = litTotal - individual;
   const renderK = (k: number): string => {
     const shownIndiv = Math.min(k, individual);
-    const remaining = litTotal - shownIndiv;
+    const remaining = collapsed + individual - shownIndiv;
     const footer = remaining > 0
-      ? `\n… ${remaining} lit below threshold — call fovea_dwell to expand (t grows, periphery sharpens)`
+      ? `\n… ${remaining} low-acuity nodes remain collapsed or outside budget — fovea_dwell returns newly warmed neighbors`
       : "";
     return header + "\n" + items.slice(0, k).join("\n") + footer;
   };

package/src/core/types.ts

@@ -22,7 +22,7 @@ export type EdgeKind =
   | "tests"      // test file -> unit under test
   | "join"       // shared normalized literal (cross-language bridge)
   | "anchors"    // route anchor -> handler symbol (site-collapsed feature hub)
-| "cochange";  // git-history co-change conductance   // route anchor -> handler symbol
+  | "cochange";  // git-history co-change conductance
 
 export interface NodeRec {
   id: string;        // stable identity: "name@file" (methods: "Type.name@file")
@@ -30,6 +30,7 @@ export interface NodeRec {
   kind: NodeKind;
   file: string;      // repo-relative path
   line: number;      // 1-indexed
+  lineApproximate?: boolean; // legacy outlines only know the enclosing declaration
   sig: string;       // one-line signature for foveated rendering
   lang: string;      // ast-grep language name, or "config" / "text"
 }
@@ -65,6 +66,7 @@ export interface SymbolRec {
   kind: NodeKind;
   file: string;
   line: number;
+  lineApproximate?: boolean;
   sig: string;
   lang: string;
 }

package/src/index.ts

@@ -17,6 +17,15 @@ const BudgetParam = Type.Optional(
 const RootParam = Type.Optional(
   Type.String({ description: "Repo root to map. Defaults to the session working directory." }),
 );
+const GrepParams = Type.Object({
+  pattern: Type.String({ description: "Symbol, route, environment key, or file query for the Fovea code graph." }),
+  path: Type.Optional(Type.String({ description: "Compatibility path hint. Used as a fallback graph seed when pattern finds no node." })),
+  glob: Type.Optional(Type.String({ description: "Accepted for grep-call compatibility; Fovea navigation is graph-based rather than glob-filtered." })),
+  ignoreCase: Type.Optional(Type.Boolean({ description: "Accepted for grep-call compatibility; Fovea symbol matching is already case-insensitive." })),
+  literal: Type.Optional(Type.Boolean({ description: "Accepted for grep-call compatibility; the pattern is interpreted as a graph query." })),
+  context: Type.Optional(Type.Number({ description: "Accepted for grep-call compatibility; graph neighbors replace line context." })),
+  limit: Type.Optional(Type.Number({ description: "Accepted for grep-call compatibility; output is controlled by tools.defaultBudget." })),
+});
 
 const text = (s: string) => ({ type: "text" as const, text: s });
 
@@ -31,11 +40,54 @@ export default function fovea(pi: ExtensionAPI) {
     return cfg;
   };
 
-  pi.on("session_start", async (event) => {
+  let grepOverrideRegistered = false;
+  const registerGrepOverride = (): void => {
+    if (grepOverrideRegistered) return;
+    grepOverrideRegistered = true;
+    pi.registerTool({
+      name: "grep",
+      label: "grep (Fovea)",
+      description:
+        "Navigate the pi-fovea code graph through grep's familiar argument shape. Finds symbols, routes, environment keys, files, and their warm dependencies; it does not perform literal line matching. Use bash with rg only when exact text or regex matches are required.",
+      promptSnippet: "Navigate the Fovea code graph with a grep-compatible query",
+      promptGuidelines: [
+        "Use grep for graph-backed repository navigation before exact text search; when the Fovea override is active, grep centers the code graph on pattern and returns warm dependencies rather than matching lines.",
+        "Use bash with rg only when an exact literal or regular-expression text match is required after the Fovea-backed grep result.",
+      ],
+      parameters: GrepParams,
+      async execute(_id, params, _signal, _onUpdate, ctx) {
+        const root = ctx.cwd;
+        const budget = configFor(root, ctx.isProjectTrusted()).tools.defaultBudget;
+        const pattern = params.pattern.trim();
+        const pathHint = params.path?.replace(/^@/, "").trim();
+        let query = pattern || pathHint || params.pattern;
+        try {
+          let result = focus(root, query, budget);
+          if (Number(result.details.seeds ?? 0) === 0 && pathHint && pathHint !== "." && pathHint !== query) {
+            query = pathHint;
+            result = focus(root, query, budget);
+          }
+          return {
+            content: [text(result.text.replace(/^fovea focus/, "fovea grep"))],
+            details: { ...result.details, backend: "fovea", query },
+          };
+        } catch (error) {
+          return {
+            content: [text(String(error instanceof Error ? error.message : error))],
+            details: { backend: "fovea", query },
+            isError: true,
+          };
+        }
+      },
+    });
+  };
+
+  pi.on("session_start", async (event, ctx) => {
     if (event.reason === "new" || event.reason === "fork") {
       resetSessions();
       resetSyncBaselines();
     }
+    if (configFor(ctx.cwd, ctx.isProjectTrusted()).tools.replaceGrep) registerGrepOverride();
   });
 
   // Turn-sync loop. The tracker below is a hint accumulator only: pi's
@@ -104,9 +156,9 @@ export default function fovea(pi: ExtensionAPI) {
     name: "fovea_focus",
     label: "Fovea Focus",
     description:
-      "Center the fovea on a query (symbol name, route path like /api/users/{id}, env key, or file). Returns a foveated field: hot nodes with full signatures, warm nodes as one-liners, the periphery collapsed. Sets the session focus that fovea_dwell deepens. Only new information is returned — already-shown nodes are suppressed.",
+      "Center the fovea on a query (symbol name or close spelling, route path like /api/users/{id}, env key, or file). Returns exact hot signatures, typed direct relationships, warm one-liners, and a collapsed periphery. Misses include nearby symbols. Sets the session focus that fovea_dwell deepens; already-shown nodes are suppressed.",
     parameters: Type.Object({
-      query: Type.String({ description: "Symbol name, route path, env key, or repo-relative file path." }),
+      query: Type.String({ description: "Symbol name or close spelling, route path, env key, or repo-relative file path." }),
       root: RootParam,
       maxTokens: BudgetParam,
     }),
@@ -125,7 +177,7 @@ export default function fovea(pi: ExtensionAPI) {
     name: "fovea_dwell",
     label: "Fovea Dwell",
     description:
-      "Let the current focus diffuse longer (heat time t grows, default x2) and return only the newly-luminous periphery. Use after fovea_focus when the footer says more nodes are lit below threshold.",
+      "Let the current focus diffuse longer (heat time t grows, default x2) and return only newly warmed neighbors. Use after fovea_focus when its footer reports a remaining low-acuity periphery.",
     parameters: Type.Object({
       factor: Type.Optional(Type.Number({ description: "Multiply diffusion time by this (default 2).", minimum: 1.1, maximum: 16 })),
       root: RootParam,
@@ -179,14 +231,18 @@ export default function fovea(pi: ExtensionAPI) {
     handler: async (args, ctx) => {
       const sub = args.trim().split(/\s+/)[0] ?? "status";
       if (sub === "settings") {
-        await openFoveaSettings(ctx, { onConfigApplied: () => configs.clear() });
+        const result = await openFoveaSettings(ctx, { onConfigApplied: () => configs.clear() });
+        if (result.grepRegistrationChanged) {
+          ctx.ui.notify("Reloading extensions to apply the grep tool change…", "info");
+          await ctx.reload();
+        }
         return;
       }
       try {
         const s = sketch(ctx.cwd, 256);
         const cfg = configFor(ctx.cwd, ctx.isProjectTrusted());
         ctx.ui.notify(
-          `pi-fovea: ${s.details.files ?? 0} files, ${s.details.nodes ?? 0} nodes, ${s.details.anchors ?? 0} anchors · sync ${cfg.sync.enabled ? "on" : "off"}`,
+          `pi-fovea: ${s.details.files ?? 0} files, ${s.details.nodes ?? 0} nodes, ${s.details.anchors ?? 0} anchors · sync ${cfg.sync.enabled ? "on" : "off"} · grep ${cfg.tools.replaceGrep ? "fovea" : "native"}`,
           "info",
         );
       } catch (e) {

package/src/ui/settings.ts

@@ -194,6 +194,11 @@ const buildItems = (
         "How many undisclosed files must warm up during sync to justify a red message. Higher = fewer interruptions; route anchor shifts always escalate.",
       submenu: numericSubmenu(theme, THRESHOLDS, "Warm file threshold", "Disclosed-file warming count that escalates sync to red."),
     }),
+    setting("tools.replaceGrep", "Replace grep", config.tools.replaceGrep ? "true" : "false", {
+      description:
+        "Register a grep-compatible tool backed by fovea_focus instead of literal text search. Default on; changing it reloads extensions so Pi and Fabric see the new tool slot.",
+      values: BOOLEANS,
+    }),
     setting("tools.defaultBudget", "Default tool budget", String(config.tools.defaultBudget), {
       description: "Token budget applied when a fovea_* tool call omits maxTokens.",
       submenu: numericSubmenu(theme, BUDGETS, "Default tool budget", "Fallback maxTokens for fovea tools."),
@@ -206,13 +211,17 @@ export interface FoveaSettingsDeps {
   onConfigApplied?: () => void;
 }
 
+export interface FoveaSettingsResult {
+  grepRegistrationChanged: boolean;
+}
+
 export const openFoveaSettings = async (
   context: ExtensionContext,
   deps: FoveaSettingsDeps = {},
-): Promise<void> => {
+): Promise<FoveaSettingsResult> => {
   if (context.mode !== "tui") {
     context.ui.notify("Fovea settings are available in TUI mode", "warning");
-    return;
+    return { grepRegistrationChanged: false };
   }
   const agentDir = getAgentDir();
   const scopes = {
@@ -221,6 +230,7 @@ export const openFoveaSettings = async (
     projectTrusted: context.isProjectTrusted(),
   };
   let config = loadFoveaConfig(scopes);
+  const initialReplaceGrep = config.tools.replaceGrep;
   let dirty = false;
 
   const apply = (id: string, value: unknown): void => {
@@ -249,6 +259,7 @@ export const openFoveaSettings = async (
   });
 
   if (dirty) context.ui.notify("Fovea settings saved.", "info");
+  return { grepRegistrationChanged: config.tools.replaceGrep !== initialReplaceGrep };
 };
 
 // Local in-place merge so subsequent edits in the same overlay start from the