pi-fovea 0.3.3 → 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,11 +26,13 @@ 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-fovea",
-  "version": "0.3.3",
+  "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.

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/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

@@ -156,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,
     }),
@@ -177,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,