@zhalker/gentle-shell-codegraph-subagents 0.1.0 → 0.2.0

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 zhalker
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2026 zhalker
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,46 +1,61 @@
-# @zhalker/gentle-shell-codegraph-subagents
-
-Pi package that keeps CodeGraph reachable from gentle-shell subagents. On every session start it checks the global agent definitions and `mcp.json` and fixes what gentle-ai or the gentle-pi package left behind. Nothing is rewritten when everything is already right.
-
-> **This package edits files in your Pi configuration.** On every session start it rewrites the agent definitions in `~/.pi/agent/agents/` and `~/.pi/agent/subagents/` and the `codegraph` entry in `~/.pi/agent/mcp.json`. It keeps a one-time backup of each file it changes as `<file>.pre-codegraph-subagents.bak`. Read "What it does" before installing, and see "Uninstall" to go back.
-
-Upstream issue: Gentleman-Programming/gentle-shell#2804. License: MIT.
-
-## What it does
-
-In `~/.pi/agent/agents/` and `~/.pi/agent/subagents/` (or `$PI_CODING_AGENT_DIR`):
-
-- Removes the blocks gentle-ai writes between `<!-- gentle-ai:pi-codegraph-tool -->` / `<!-- gentle-ai:pi-codegraph-guidance -->` and `<!-- /gentle-ai:pi-codegraph -->`.
-- Removes the dead `mcp` entry (the retired `pi-mcp-adapter` proxy) and the `"*": false` entry from every `tools:` list.
-- Adds `mcp__codegraph__codegraph_explore` to `gentle-ai-explore`, `gentle-ai-verify`, `gentle-ai-worker`, `jd-fix-agent`, `jd-judge-a` and `jd-judge-b`, removes the `codegraph` extension tool from `gentle-ai-explore`, and rewrites that agent's own CodeGraph instructions to use the MCP tool.
-- Leaves the `review-*` agents without CodeGraph.
-
-In `mcp.json`: sets `"exposure": "direct"` on the `codegraph` server. Without it Pi never declares the server's tools to the model and the `tools:` entry above matches nothing.
-
-In a subagent that only reads and holds `mcp__codegraph__codegraph_explore` (the explorer), a `before_agent_start` hook also runs `codegraph explore <task>` once before the first model call and hands the output to the model as a message, bounded to 20 s and 12,000 characters. If the project has no `.codegraph/` index, the CLI is missing or fails, nothing is added and the run continues as before.
-
-Before the first change to a file it saves the original next to it as `<file>.pre-codegraph-subagents.bak`; later changes never overwrite that backup.
-
-## Install
-
-```
-pi install npm:@zhalker/gentle-shell-codegraph-subagents
-```
-
-Changes apply on the next session start. Reinstalling, or running `gentle-ai sync` again, is corrected the same way on the following start.
-
-## Uninstall
-
-Remove the package, then copy each `*.pre-codegraph-subagents.bak` over its original if you want the previous files back.
-
-## Known limits
-
-- Only the global agent directory is handled, not `<project>/.pi/agents/`.
-- The explorer prefetch is recognised by the child's tool set (read-only plus the CodeGraph MCP tool), because gentle-pi does not tell the child which agent it is.
-- The rewrite of the explorer's own instructions matches known sentences; if gentle-pi rewords them, they are left as they are.
-- The `codegraph` MCP server has to exist in `mcp.json`; the package never creates it.
-- Tested with Pi 1.4.0 and node 24.
-
-## Development
-
-`npm test` runs the unit tests with Node's built-in runner.
+# @zhalker/gentle-shell-codegraph-subagents
+
+Pi package that keeps CodeGraph reachable from gentle-shell subagents. On every session start it checks the global agent definitions and `mcp.json` and fixes what gentle-ai or the gentle-pi package left behind. Nothing is rewritten when everything is already right.
+
+> **This package edits files in your Pi configuration.** On every session start it rewrites the agent definitions in `~/.pi/agent/agents/` and `~/.pi/agent/subagents/` and the `codegraph` entry in `~/.pi/agent/mcp.json`. It keeps a one-time backup of each file it changes as `<file>.pre-codegraph-subagents.bak`. Read "What it does" before installing, and see "Uninstall" to go back.
+
+Upstream issue: Gentleman-Programming/gentle-shell#2804. License: MIT.
+
+## What it does
+
+In `~/.pi/agent/agents/` and `~/.pi/agent/subagents/` (or `$PI_CODING_AGENT_DIR`):
+
+- Removes the blocks gentle-ai writes between `<!-- gentle-ai:pi-codegraph-tool -->` / `<!-- gentle-ai:pi-codegraph-guidance -->` and `<!-- /gentle-ai:pi-codegraph -->`.
+- Removes the dead `mcp` entry (the retired `pi-mcp-adapter` proxy) and the `"*": false` entry from every `tools:` list.
+- Adds `mcp__codegraph__codegraph_explore` to `gentle-ai-explore`, `gentle-ai-verify`, `gentle-ai-worker`, `jd-fix-agent`, `jd-judge-a` and `jd-judge-b`, removes the `codegraph` extension tool from `gentle-ai-explore`, and rewrites that agent's own CodeGraph instructions to use the MCP tool. Adds a routing marker to `gentle-ai-worker` for its first-prompt skill reminder.
+- Leaves the `review-*` agents without CodeGraph.
+
+The package also provides the `codegraph-workflow` skill. When Pi loads this packaged skill, the extension adds a reminder before the first user prompt of the parent session and the first prompt of `gentle-ai-worker` children. It does not add the reminder to other children. Pi handles skill name collisions; if Pi selects a different skill with that name, the extension does not direct the model to it as if it were the packaged skill. A local package is discovered in place rather than copied to the user's skills directory.
+
+In `mcp.json`: selects `"direct"` for `codegraph_explore` under `toolExposure`, without changing the server-wide exposure. Explicit tool settings (including matching patterns), disabled servers, and hidden servers are preserved. At session start Pi warns when the CodeGraph MCP server is not configured, without creating it, or when direct subagent access may be unavailable; it also warns if a hidden server has an explicit direct explore exception, which Pi can still expose. Trusted project MCP configuration and servers registered by extensions are considered. A configuration change may require a reload before Pi uses it.
+
+In a subagent that only reads and holds `mcp__codegraph__codegraph_explore` (the explorer), a `before_agent_start` hook also runs `codegraph_explore` for its task once before the first model call and hands the output to the model as a message, bounded to 20 s and 12,000 characters. It asks the project's running CodeGraph daemon directly (the same text as the CLI, locally ~75 ms against ~590 ms); when there is no usable daemon it runs `codegraph explore <task>` instead, and it never starts a daemon. If the project has no `.codegraph/` index, the package's init lock is held, or neither way works, nothing is added and the run continues as before.
+
+In the directory where Pi starts, a new session also looks after the CodeGraph index, in the background (the session never waits for it):
+
+- If `.codegraph/` exists, it runs `codegraph sync`. The CodeGraph file watcher does not work on SMB mounts, so without this the index stays as it was.
+- If there is no `.codegraph/`, but there is a `.git` and one of `composer.json`, `package.json`, `pyproject.toml`, `go.mod`, `Cargo.toml`, `Gemfile`, `pom.xml`, `build.gradle` or `build.gradle.kts`, it runs `codegraph init -y`. In any other directory nothing is created.
+- When there is an index (existing, or just created), it then warms the project's CodeGraph daemon: a short MCP client runs one small `codegraph_explore` and disconnects, and the daemon stays up for as long as your session keeps it. The first real call of the orchestrator and of every subagent is then fast (locally 620-650 ms cold against ~70 ms warm). The explorer's pre-fetch asks that same daemon, so it gets the same speed-up.
+- Pi shows a notice when each step starts ("syncing the CodeGraph index...", "creating the CodeGraph index of this project...", "warming up CodeGraph...") and another when it ends ("CodeGraph index synced", "CodeGraph index created", "CodeGraph ready"), or a warning if it failed.
+- Concurrent rewrites of agent files and `mcp.json` are tolerated (an existing backup is kept, and transient collisions are retried). A per-project lock in the user's temp folder coordinates package-started initializations: a session that finds it held skips init, sync and warm-up, and the explorer skips its prefetch. When a session exits during init, the package also checks CodeGraph's writer lock. On Windows it conservatively holds the package lock for 60 seconds after spawning the shell, covering the period before CodeGraph writes its own lock. Locks are treated as stale after 11 minutes.
+- Subagent children and `/reload` do nothing; startup, new, resume and fork do.
+
+Before the first change to a file it saves the original next to it as `<file>.pre-codegraph-subagents.bak`; later changes never overwrite that backup.
+
+## Install
+
+```
+pi install npm:@zhalker/gentle-shell-codegraph-subagents
+```
+
+Changes apply on the next session start. Reinstalling, or running `gentle-ai sync` again, is corrected the same way on the following start.
+
+## Uninstall
+
+Remove the package, then copy each `*.pre-codegraph-subagents.bak` over its original if you want the previous files back.
+
+## Known limits
+
+- Only the global agent directory is handled, not `<project>/.pi/agents/`.
+- The warm-up has only been measured on local disks, not on a network share. It never kills the processes it starts, because the daemon is shared with your own sessions.
+- CodeGraph's own `init` can hang when two start at once, or when a daemon opens the project just after the index is created. The package lock only coordinates sessions sharing the same user temp folder; it cannot prevent access by a terminal, another tool, another user, or Pi's own MCP connection. On Windows, if the session and shell exit before CodeGraph writes its own lock and that takes more than 60 seconds, the package cannot tell that init is still running. The 11-minute stale-lock limit can also expire while a process remains alive.
+- The index sync is a background command: a prefetch that runs before it finishes can see the previous index. The sync only looks at the directory where Pi starts, not at parents or subfolders. Treat prefetched results as navigation hints, not authoritative evidence: they can be stale, incomplete, truncated or incorrect; verify findings against source files.
+- Asking the daemon directly relies on two internal details of CodeGraph: the registry in `~/.codegraph/daemons/` and the hello line with `protocol: 1`. If either changes, or the daemon answers anything unexpected, the CLI is used, as before. A daemon that is there but does not answer within 20 s is not retried through the CLI.
+- The explorer prefetch requires the launcher to set `GENTLE_PI_AGENTS_CHILD=1` and `GENTLE_PI_AGENTS_REQUESTED_TOOLS` to the child's declared comma-separated tool list. It recognizes a read-only child with the CodeGraph MCP tool and no writing tools; this declaration does not prove the MCP tool actually connected. Without these launcher variables the prefetch is skipped. The first 300 sanitized characters of the task become the query, so verbose instructions can broaden the result; the returned context is capped at 12,000 characters.
+- The rewrite of the explorer's own instructions matches known sentences; if gentle-pi rewords them, they are left as they are.
+- The `codegraph` MCP server has to be configured or registered by an extension; the package never creates it. When Pi is launched from a GUI or service, its `PATH` may differ from your shell. An absolute MCP server command can fix the server launch, but this package's `init`, `sync` and CLI fallback still need `codegraph` on Pi's `PATH`.
+- Tested with Pi 1.4.0 and node 24.
+
+## Development
+
+`npm test` runs the unit tests with Node's built-in runner.

package/extensions/index.ts

@@ -1,38 +1,99 @@
-import { existsSync } from "node:fs";
-import { getAgentDir, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import { applyCodegraphSubagents } from "../src/apply.ts";
-import { exploreWithCodegraph, prefetchForExplorer } from "../src/prefetch.ts";
-
-// Reapplied on every session start so a reinstall (pi install, gentle-shell install)
-// or a gentle-ai sync that rewrote the agent files is corrected on the next launch.
-export default function (pi: ExtensionAPI) {
-	pi.on("session_start", async (_event, ctx) => {
-		try {
-			const { changed, errors } = applyCodegraphSubagents(getAgentDir());
-			if (!ctx.hasUI) return;
-			if (changed.length > 0) ctx.ui.notify(`gentle-shell-codegraph-subagents: updated ${changed.length} file(s)`, "info");
-			if (errors.length > 0) ctx.ui.notify(`gentle-shell-codegraph-subagents: ${errors.length} file(s) skipped: ${errors[0]}`, "warning");
-		} catch {
-			// Never block a session over this.
-		}
-	});
-
-	// Only the explorer child: hand it `codegraph explore` for its task before its first model call.
-	// Without .codegraph, the CLI, or in time, the run goes on exactly as before.
-	pi.on("before_agent_start", async (event) => {
-		try {
-			const prompt = event.messageType === "user" ? event.prompt : undefined;
-			const content = await prefetchForExplorer({
-				env: process.env,
-				prompt,
-				cwd: process.cwd(),
-				exists: existsSync,
-				explore: exploreWithCodegraph,
-			});
-			if (content === undefined) return undefined;
-			return { message: { customType: "codegraph-prefetch", content, display: false } };
-		} catch {
-			return undefined;
-		}
-	});
-}
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { getAgentDir, type ExtensionAPI, type ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { applyCodegraphSubagents, readExposureWarning, readMissingServerWarning } from "../src/apply.ts";
+import { prepareProject, runCodegraph, type SessionStartReason } from "../src/autoindex.ts";
+import { exploreViaDaemon } from "../src/daemonclient.ts";
+import { realInitLock } from "../src/initlock.ts";
+import { PREFETCH_TIMEOUT_MS, exploreDaemonFirst, exploreWithCodegraph, prefetchForExplorer } from "../src/prefetch.ts";
+import { warmUpDaemon } from "../src/warmup.ts";
+import { chooseSkillReminder, SKILL_REMINDER_TYPE } from "../src/skill-reminder.ts";
+
+// Starts the index sync (or first init) and then the daemon warm-up in the background; the session never waits for them.
+function startAutoIndex(reason: SessionStartReason, ctx: ExtensionContext): void {
+	const say = (text: string, level: "info" | "warning") => {
+		if (ctx.hasUI) ctx.ui.notify(`gentle-shell-codegraph-subagents: ${text}`, level);
+	};
+	prepareProject({
+		cwd: ctx.cwd,
+		env: process.env,
+		reason,
+		exists: existsSync,
+		run: runCodegraph,
+		lock: realInitLock,
+		warm: (cwd) => warmUpDaemon(cwd),
+		onStart: (action) => say(action === "init" ? "creating the CodeGraph index of this project..." : "syncing the CodeGraph index...", "info"),
+		onIndexed: (result) => {
+			if (result.joined) say("another session is creating the CodeGraph index of this project", "info");
+			else if (!result.ok) say(`codegraph ${result.action} failed in ${ctx.cwd}`, "warning");
+			else say(result.action === "init" ? "CodeGraph index created" : "CodeGraph index synced", "info");
+		},
+		onWarmStart: () => say("warming up CodeGraph...", "info"),
+	})
+		.then((result) => {
+			if (result.warm === "ok") say("CodeGraph ready", "info");
+			else if (result.warm === "failed") say(`CodeGraph warm-up failed in ${ctx.cwd}`, "warning");
+		})
+		.catch(() => {
+			// The session may already be gone; nothing to report to.
+		});
+}
+
+// Reapplied on every session start so a reinstall (pi install, gentle-shell install)
+// or a gentle-ai sync that rewrote the agent files is corrected on the next launch.
+export default function (pi: ExtensionAPI) {
+	let firstPromptSeen = false;
+	pi.on("session_start", async (event, ctx) => {
+		startAutoIndex(event.reason, ctx);
+		try {
+			const { changed, errors } = applyCodegraphSubagents(getAgentDir());
+			if (!ctx.hasUI) return;
+			if (changed.length > 0) ctx.ui.notify(`gentle-shell-codegraph-subagents: updated ${changed.length} file(s)`, "info");
+			if (errors.length > 0) ctx.ui.notify(`gentle-shell-codegraph-subagents: ${errors.length} file(s) skipped: ${errors[0]}`, "warning");
+			const registered = pi.getMcpServers?.().some((server) => server.name === "codegraph") ?? false;
+			if (process.env.GENTLE_PI_AGENTS_CHILD !== "1" && readMissingServerWarning(getAgentDir(), ctx.cwd, ctx.isProjectTrusted(), registered)) {
+				ctx.ui.notify("gentle-shell-codegraph-subagents: CodeGraph MCP server was not found in the current configuration. Subagents may not have direct access; configure the server to enable it.", "warning");
+			}
+			const exposure = readExposureWarning(getAgentDir(), ctx.cwd, ctx.isProjectTrusted());
+			if (exposure === "hidden-with-direct") ctx.ui.notify("gentle-shell-codegraph-subagents: CodeGraph server is hidden, but its direct explore exception is configured to expose that tool. Your settings were preserved.", "warning");
+			else if (exposure) ctx.ui.notify(`gentle-shell-codegraph-subagents: CodeGraph explore is configured as ${exposure}; direct subagent access may be unavailable. Your setting was preserved.`, "warning");
+		} catch {
+			// Never block a session over this.
+		}
+	});
+
+	// Only the explorer child: hand it `codegraph explore` for its task before its first model call.
+	// Without .codegraph, the CLI, or in time, the run goes on exactly as before.
+	pi.on("before_agent_start", async (event, ctx) => {
+		try {
+			const alreadySent = firstPromptSeen || ctx.sessionManager.getBranch().some((entry) => entry.type === "custom_message" && entry.customType === SKILL_REMINDER_TYPE);
+			const reminder = chooseSkillReminder({
+				expectedPath: join(import.meta.dirname, "..", "skills", "codegraph-workflow", "SKILL.md"),
+				skills: event.systemPromptOptions?.skills ?? [],
+				child: process.env.GENTLE_PI_AGENTS_CHILD === "1",
+				systemPrompt: event.systemPrompt,
+				alreadySent,
+				isUserPrompt: event.messageType === "user",
+			});
+			if (event.messageType === "user") firstPromptSeen = true;
+			const prompt = event.messageType === "user" ? event.prompt : undefined;
+			const content = await prefetchForExplorer({
+				env: process.env,
+				prompt,
+				cwd: process.cwd(),
+				exists: existsSync,
+				initRunning: (cwd) => realInitLock.isHeld(cwd),
+				explore: (query, cwd) =>
+					exploreDaemonFirst(query, cwd, {
+						daemon: (q, c) => exploreViaDaemon(c, q, PREFETCH_TIMEOUT_MS),
+						cli: exploreWithCodegraph,
+					}),
+			});
+			if (reminder) return { message: { customType: SKILL_REMINDER_TYPE, content: [reminder, content].filter(Boolean).join("\n\n"), display: false } };
+			if (content === undefined) return undefined;
+			return { message: { customType: "codegraph-prefetch", content, display: false } };
+		} catch {
+			return undefined;
+		}
+	});
+}

package/package.json

@@ -1,20 +1,39 @@
-{
-  "name": "@zhalker/gentle-shell-codegraph-subagents",
-  "version": "0.1.0",
-  "description": "Pi package that keeps CodeGraph reachable from gentle-shell subagents: normalizes agent tool lists and the codegraph MCP exposure on every session start, and pre-fetches CodeGraph for the explorer.",
-  "license": "MIT",
-  "author": "zhalker",
-  "type": "module",
-  "keywords": ["pi-package", "pi", "codegraph", "subagents", "gentle-shell", "gentle-ai", "mcp"],
-  "files": ["extensions", "src", "README.md", "LICENSE"],
-  "pi": {
-    "extensions": ["./extensions/index.ts"]
-  },
-  "scripts": {
-    "test": "node --test \"test/*.test.ts\"",
-    "prepublishOnly": "npm test"
-  },
-  "peerDependencies": {
-    "@earendil-works/pi-coding-agent": "*"
-  }
-}
+{
+  "name": "@zhalker/gentle-shell-codegraph-subagents",
+  "version": "0.2.0",
+  "description": "Pi package that keeps CodeGraph reachable from gentle-shell subagents: normalizes agent tool lists and the codegraph MCP exposure on every session start, and pre-fetches CodeGraph for the explorer.",
+  "license": "MIT",
+  "author": "zhalker",
+  "type": "module",
+  "keywords": [
+    "pi-package",
+    "pi",
+    "codegraph",
+    "subagents",
+    "gentle-shell",
+    "gentle-ai",
+    "mcp"
+  ],
+  "files": [
+    "extensions",
+    "src",
+    "skills",
+    "README.md",
+    "LICENSE"
+  ],
+  "pi": {
+    "extensions": [
+      "./extensions/index.ts"
+    ],
+    "skills": [
+      "./skills"
+    ]
+  },
+  "scripts": {
+    "test": "node --test \"test/*.test.ts\"",
+    "prepublishOnly": "npm test"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*"
+  }
+}

package/skills/codegraph-workflow/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: codegraph-workflow
+description: "Trigger: investigate, analyze, refactor, fix, or review code. Use CodeGraph to navigate indexed code before broad symbol searches."
+---
+
+# CodeGraph workflow
+
+## Activation Contract
+
+Use this workflow for code investigation, analysis, refactoring, fixes,
+or review. For unrelated tasks, do not invoke CodeGraph just because
+this skill is available.
+
+## Hard Rules
+
+- When an applicable index and a CodeGraph tool are available, use
+  CodeGraph before broad symbol searches.
+- Do not run `codegraph index` before every query.
+- Do not initialize or update an index independently of the package's
+  startup policy or explicit user authorization.
+- Treat CodeGraph results as navigation hints, not authoritative source.
+  Confirm relevant behavior and findings against the source files.
+
+## Decision Gates
+
+- For exact strings, filenames, configuration, or a known file, use the
+  appropriate file or search tool directly.
+- If CodeGraph is unavailable, fails, or has no applicable index, continue
+  with the available read and search tools. Do not repeatedly retry it.
+- If indexing or synchronization is still running, do not assume the
+  results are current. Do not start another index operation.
+- When working across projects or worktrees, use only an index and a
+  project path the current tool and the user's scope permit.
+
+## Delegation
+
+- If a subagent cannot use CodeGraph, the parent may query it and include
+  relevant findings and paths in the handoff.
+- Respect each subagent's tool restrictions. Do not require `bash` from
+  a read-only explorer.
+
+## Output Contract
+
+When relevant, report unavailable or potentially stale index evidence and
+distinguish CodeGraph findings from behavior verified in source.