pi-fovea 0.3.3 → 0.4.1

package/README.md

@@ -17,21 +17,23 @@ _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.
+At agent start Fovea establishes or checks its semantic baseline, so out-of-band edits made while Pi was idle enter context before the first model call. After each assistant turn it re-syncs again. Detection does not trust tool events: edits made by Pi tools, fabric_exec, bash, subagents, or an editor land identically, while comment- and formatting-only drift stays silent. A meaningful post-turn change is delivered as a **steer**, and Fovea triggers the continuation itself if the agent would otherwise wait.
 
 ## What the model gets
 
 | 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_dwell` | what else? | diffuses the field one step further and returns the delta |
+| `fovea_sketch` | where is everything? | production-first silhouette; test and fixture architecture stays collapsed |
+| `fovea_focus` | what is this? | exact matches, typed relationships, suggested reads, optional source scopes, and deterministic `fresh` views |
+| `fovea_dwell` | what else? | widens the current focus and returns newly relevant neighbors |
 | `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 |
+| `grep` *(default hybrid)* | graph or text? | bare identifiers, qualified symbols, repo paths, and routes use Fovea; search options and obvious regex retain native grep |
 
-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`.
+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 **Hybrid grep** toggle is on by default. `grep({ pattern: "CreateUser" })`, `grep({ pattern: "Controller.create" })`, and route paths can navigate the graph. Calls with text-search options and obvious regexes delegate to Pi's native grep unchanged; a graph miss also falls back to native text. Disable the toggle for a purely native slot. Changing it reloads extensions so Pi and pi-fabric capture the same behavior.
 
 ### pi-fabric
 
@@ -52,10 +54,12 @@ 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:
+Runtime slash controls:
 
-- `/fovea status` for graph stats and sync state
-- `/fovea settings` for an overlay in your TUI, styled after pi-fabric's `/fabric settings`
+- `/fovea status` for loaded versions, graph coverage, and active modes
+- `/fovea settings` for a TUI configuration overlay
+- `/fovea reset` for a fresh focus and sync baseline
+- `/fovea reload` to activate updated extension source
 
 ## Install
 
@@ -97,14 +101,18 @@ fovea status /path/to/repo
 
 ## Turn sync
 
-Turn sync is on by default. After every assistant turn the graph is re-synced against your edits: unchanged files cost nothing because every parsed fact sits behind its content hash. The verdict is **green** or **red**:
+Continuous sync is on by default. Before an agent starts, Fovea establishes its baseline or injects any out-of-band drift before the first model call. After every assistant turn it compares extracted symbols, calls, imports, literals, and anchors again. Content hashes keep the unchanged fast path cheap, while comment- and formatting-only edits do not wake the model.
+
+A meaningful change found before agent start is injected directly into that run. A post-turn route or dependency change is sent with `deliverAs: "steer"`; if the agent would otherwise settle, `triggerTurn` starts the continuation automatically. The compact update names directly changed files, route deltas, newly relevant files, and causal channels such as calls, imports, shared literals, tests, or co-change history. Clean turns remain silent unless `sync.ackClean` is enabled.
 
-- **green**: silence in the model's context. A clean-toast shows only if you enable `sync.ackClean`.
-- **red**: a capped custom message naming route anchors that appeared or disappeared, plus files warmed by the edit cascade that the model has not focused on yet.
+Runtime controls:
 
-The first sync seeds the baseline. The first drift after it calibrates the warm neighborhood, so a steady feature cone stays quiet. Sub sequent drift turns red.
+- `/fovea status` — loaded package/ast-grep versions, indexed coverage, anchor scopes, sync and grep modes.
+- `/fovea reset` — clear focus disclosure/depth and establish a fresh sync baseline.
+- `/fovea reload` — hot-reload extensions and activate newly installed source.
+- `/fovea settings` — configure sync, budgets, and hybrid grep.
 
-Turn it off per repo or globally: `/fovea settings` → Turn sync, or
+Turn sync off per repo or globally through settings, or with:
 
 ```sh
 FOVEA_TURN_SYNC=off pi
@@ -116,12 +124,12 @@ Global settings live in `~/.pi/agent/fovea.json`. A trusted repo-level override
 
 | Key | Default | Meaning |
 | --- | :-----: | ------- |
-| `sync.enabled` | `true` | the turn-sync loop |
-| `sync.budget` | `1024` | token cap for the red report seen by the model |
+| `sync.enabled` | `true` | pre-agent and post-turn continuous sync |
+| `sync.budget` | `1024` | token cap for proactive steering context |
 | `sync.ackClean` | `false` | toast after clean structural turns |
-| `sync.warmFileThreshold` | `2` | warmed files unseen by the model that justify turning red |
+| `sync.warmFileThreshold` | `2` | newly relevant files that justify proactive model steering |
 | `tools.defaultBudget` | `2000` | fallback maxTokens for the fovea_* tools |
-| `tools.replaceGrep` | `true` | replace Pi's grep slot with graph-backed Fovea navigation |
+| `tools.replaceGrep` | `true` | install hybrid native-text / bare-query graph grep |
 
 ## How routes are found
 
@@ -170,7 +178,7 @@ $$
 v(t) = e^{-tL} \cdot s \quad \text{with} \quad L = I - D^{-1/2} W D^{-1/2}
 $$
 
-The four tools are the same operator at four timescales: sketch at $t=16$ with hub and anchor seeds, focus at $t=4$ with your query as seed, dwell doubling $t$ per call with a disclosed-set delta, and impact using the changed files as seed.
+The four tools are the same operator at four timescales: sketch at $t=16$ with production hub and anchor seeds, focus at $t=2$ with your query as seed, dwell doubling $t$ within that focus, and impact using changed files as seeds. Changing focus resets to the sharp timescale and its own disclosure scope.
 
 The kernel is evaluated with a Chebyshev expansion. Rescale $M = L - I$ so the spectrum sits in $[-1,1]$; then with $T_k$ the Chebyshev polynomials and $I_k$ the modified Bessel functions:
 
@@ -188,7 +196,7 @@ $$
 
 Measured against eight cloned projects, corpus junk sits below $\hat{p} \approx 0.27$ and real route shapes above $\hat{p} \approx 0.75$. The cutoff stays mid-cliff regardless of repo size.
 
-Lineage: spectral-graph wavelets evaluated by shared Chebyshev recurrence, progressive image coding where the budget is a bitrate over significance-ordered coefficients, and foveated rendering. Aider's PageRank repo map is the fixed-timescale special case of this field. The full walkthrough of conductance tiers, specificity bridges, hub gravity, and basins lives in [docs/heat-diffusion.md](docs/heat-diffusion.md).
+Lineage: spectral-graph wavelets evaluated by shared Chebyshev recurrence, progressive image coding where the budget is a bitrate over significance-ordered coefficients, and foveated rendering. Aider's PageRank repo map is the fixed-timescale special case of this field. The full walkthrough of conductance tiers, specificity bridges, hub gravity, and inferred regions lives in [docs/heat-diffusion.md](docs/heat-diffusion.md).
 
 ## Languages
 

package/cli.ts

@@ -56,7 +56,9 @@ try {
   let out = "";
   if (cmd === "status") {
     const s = sketch(rootAt(0), 256);
-    out = `${s.details.files} files, ${s.details.nodes} nodes, ${s.details.anchors} anchors`;
+    const testAnchors = Number(s.details.testAnchors ?? 0);
+    out = `${s.details.files} files, ${s.details.nodes} symbols, ${s.details.productionAnchors ?? s.details.anchors} production anchors` +
+      (testAnchors ? `, ${testAnchors} test/fixture anchors collapsed` : "");
   } else if (cmd === "sketch") {
     const root = rootAt(0);
     const B = numAt(pos[0] === root && pos.length > 1 ? 1 : 0) ?? 1400;

package/package.json

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

@@ -9,22 +9,22 @@ 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.
-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.
+1. **`fovea_sketch`** — production-first silhouette. Shipped routes and source regions lead; test and fixture architecture is collapsed. Start here in an unfamiliar repo. ~256–1024 tokens.
+2. **`fovea_focus` `<query>`** — point at a symbol name (close spellings work), route, env key, or file. The active seed and direct relationships always remain visible; previously seen periphery is suppressed only within that focus. A different focus resets to sharp context. Use `path`, `language`, or `kind` to scope output and `fresh: true` for a reproducible full view. Structured details include nodes and suggested read windows.
+3. **`fovea_dwell`** — optional second look. If focus says more results remain, dwell widens only the current focus and returns newly relevant neighbors.
+4. **`fovea_impact`** — blast radius. Seed with repo-relative `files`, symbols, uncommitted changes, or a PR `base`. Output is likely review order with causal channels (calls, imports, literals, routes, tests, inheritance, co-change).
 
 All four accept `maxTokens` (256–16000). Budget is roughly 4 chars per token.
 
 ## Working rules
 
-- **Never bulk-read to find things.** Read what focus surfaced; let the graph answer "where is X" and "what uses X" instead of spawning searches.
+- **Do not bulk-read to discover structure.** Focus first, then read its suggested ranges. Native grep semantics remain available whenever grep receives path/glob/literal/context/limit options or an obvious regex; unresolved graph queries fall back to native text.
 - **Impact before destructive edits.** One `fovea_impact` call is cheaper than rediscovering dependents by breaking them.
 - **Sketch is the safe opening bid.** If unsure, pay for a sketch; it almost never exceeds a few hundred tokens.
 
 ## Turn sync
 
-After each assistant turn, pi-fovea diffs content hashes against its baseline. If edits moved route anchors or warmed files outside the session's disclosed set, a `[fovea turn sync]` message arrives in the next turn with the delta; otherwise everything stays silent. Treat that message as ground truth about mid-session state changes.
+Before an agent starts, pi-fovea establishes its baseline or injects out-of-band semantic drift into that run. After each assistant turn it compares again; meaningful route/dependency drift is delivered as a **steer**, and Fovea triggers a continuation if the agent would otherwise stop. Treat its changed files, route deltas, and causal channels as continuous task context. Comment- and formatting-only edits stay silent.
 
 Sync is **mutation-path agnostic**: pi's edit/write tools, a pi-fabric `fabric_exec` program's inner `pi.edit`, a bash heredoc, a subagent, or an editor save outside the session all register identically. Content hashes are the source of truth; tool events are not consulted for detection. In repos with no `.git` directory this is also the only drift signal — do not fall back to `git status` assumptions.
 
@@ -36,7 +36,7 @@ When writing or editing code **inside a `fabric_exec` program**, the fovea tools
 - 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.
+- Sketch `details` carries coverage counts; its compact text names the highest-value entry points. On an unfamiliar repo, fetch it once and reuse it instead of rediscovering entry points per call.
 
 ## CLI
 
@@ -44,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.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).
+Use `/fovea status` for loaded version and index coverage, `/fovea reset` for fresh state, `/fovea reload` after updates, and `/fovea settings` for configuration. Files live under `~/.pi/agent/fovea.json` or trusted `.pi/fovea.json`. `tools.replaceGrep` installs hybrid grep: native text semantics plus bare-query graph navigation.

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/basins.ts

@@ -15,11 +15,14 @@ const MIN_BASIN_SIZE = 4;
 
 // eligible marks nodes that may seed a basin (symbols, not files/anchors: a
 // file's contains-star has ~zero triangle density and yields useless seeds).
+// include optionally constrains every member, for operation-specific views
+// such as production-first sketching without changing the underlying graph.
 export const detectBasins = (
   adjacency: Map<number, Array<{ to: number; kind: string; w: number }>>,
   conductance: Float64Array,
   n: number,
   eligible?: (i: number) => boolean,
+  include?: (i: number) => boolean,
 ): Basin[] => {
   // Triangle density: fraction of a node's neighbors that are co-neighbors.
   // Cheap O(deg^2) sampling with degree cap — hubs are star points anyway.
@@ -60,12 +63,14 @@ export const detectBasins = (
     const order: number[] = [seed];
     let internal = 0;
     const boundary = new Map<number, number>();
-    for (const e of adjacency.get(seed) ?? []) boundary.set(e.to, (boundary.get(e.to) ?? 0) + e.w);
+    for (const e of adjacency.get(seed) ?? []) {
+      if (!include || include(e.to)) boundary.set(e.to, (boundary.get(e.to) ?? 0) + e.w);
+    }
     while (order.length < MAX_BASIN_SIZE && boundary.size) {
       let best = -1;
       let bestRatio = -1;
       for (const [j, inW] of boundary) {
-        if (claimed.has(j) || members.has(j)) continue;
+        if (claimed.has(j) || members.has(j) || (include && !include(j))) continue;
         const total = [...(adjacency.get(j) ?? [])].reduce((s, e) => s + e.w, 0);
         const ratio = total > 0 ? inW / total : 0;
         if (ratio > bestRatio) { bestRatio = ratio; best = j; }
@@ -79,7 +84,7 @@ export const detectBasins = (
       internal += boundary.get(best) ?? 0;
       boundary.delete(best);
       for (const e of adjacency.get(best) ?? []) {
-        if (members.has(e.to)) continue;
+        if (members.has(e.to) || (include && !include(e.to))) continue;
         boundary.set(e.to, (boundary.get(e.to) ?? 0) + e.w);
       }
       const cut = [...boundary.values()].reduce((a, b2) => a + b2, 0);

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

@@ -11,18 +11,18 @@ import path from "node:path";
 interface FoveaSyncConfig {
   /** turn_end feedback loop on/off (the default-on, opt-out knob). */
   enabled: boolean;
-  /** Token budget for the red (issues) message. */
+  /** Token budget for proactive model steering context. */
   budget: number;
   /** Also send a tiny model-visible ack on clean turns (default false: silent green). */
   ackClean: boolean;
-  /** Number of newly-warm undisclosed files that justifies a red message on its own. */
+  /** Number of newly relevant files that justifies proactive steering on its own. */
   warmFileThreshold: number;
 }
 
 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. */
+  /** Install hybrid grep: native text semantics plus bare-query Fovea navigation. */
   replaceGrep: boolean;
 }
 

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