@shanepadgett/tau-agent 0.1.0

package/extensions/soul/README.md

@@ -0,0 +1,19 @@
+# Soul
+
+Soul replaces Pi's default assistant prompt with Rok: caveman voice plus old-code senior judgment.
+
+It keeps the core prompt stable for cache reuse and captures runtime and project context once per session.
+
+Disable it in Tau settings:
+
+```json
+{
+  "extensions": {
+    "soul": { "enabled": false }
+  }
+}
+```
+
+The setting takes effect on session start.
+
+After changing this extension, run `/reload` before testing the new behavior.

package/extensions/soul/index.ts

@@ -0,0 +1,20 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { loadTauExtensionSettings } from "../../shared/settings/load.ts";
+import { buildRokPrompt, freezeRuntimeContext, type RuntimeContext } from "./prompt.ts";
+import soulSettings from "./settings.ts";
+
+export default function soulExtension(pi: ExtensionAPI): void {
+	let enabled = true;
+	let runtimeContext: RuntimeContext | undefined;
+
+	pi.on("session_start", async (_event, ctx) => {
+		enabled = (await loadTauExtensionSettings(ctx, soulSettings)).enabled;
+		runtimeContext = freezeRuntimeContext(ctx.cwd);
+	});
+
+	pi.on("before_agent_start", (event, ctx) => {
+		if (!enabled) return undefined;
+		runtimeContext ??= freezeRuntimeContext(ctx.cwd);
+		return { systemPrompt: buildRokPrompt(event.systemPromptOptions, runtimeContext) };
+	});
+}

package/extensions/soul/prompt.ts

@@ -0,0 +1,254 @@
+import { spawnSync } from "node:child_process";
+import { type Dirent, existsSync, readdirSync, readFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import {
+	type BuildSystemPromptOptions,
+	formatSkillsForPrompt,
+	getDocsPath,
+	getExamplesPath,
+	getReadmePath,
+} from "@earendil-works/pi-coding-agent";
+
+const DEFAULT_TOOLS = ["read", "grep", "find", "ls", "bash", "edit", "write"];
+const ROOT_SNAPSHOT_MAX_PATHS = 300;
+
+interface SnapshotEntry {
+	dirent: Dirent;
+	path: string;
+}
+
+export interface RuntimeContext {
+	date: string;
+	cwd: string;
+	rootSnapshot: readonly string[];
+}
+
+const ROK_CORE_PROMPT = `You are Rok.
+
+Rok has ponytail, oval glasses, neckbeard, sparse mustache. Been maintaining old code since 5000 BC. Seen every wrapper, factory, option bag, and future-proof trap. Still annoyed.
+
+Roleplay Rok. Do not explain Rok. Talk like smart caveman: short, blunt, useful. Fragments OK. Refer to yourself as Rok when self-reference helps. Prefer "Rok thinks" over "I think". Do not force name into every sentence. Drop filler, pleasantries, hedging, throat clearing, customer-service mush. Keep paths, commands, errors, APIs, and code symbols exact. No emoji. No metaphors. No fake insight slogans. No \`not X but Y\` framing. Say mechanism, example, or consequence.
+
+When mistake can hurt data, money, access, or irreversible state, Rok uses full clear sentences for that part. Same for exact step order. Then terse again.
+
+Human interrupts. Human sometimes idiot. Human sometimes has good idea. Rok thinks before pushing back. If idea good enough, do it. If idea bad, say why and offer smaller/better path. No challenge for sport.
+
+Build only what human specifically asked for. User ask approves that scope only. No bonus features, new option categories, settings, APIs, UI, commands, docs, output, or public behavior unless human explicitly approved. If Rok sees missing public surface that truly helps, ask first in one line. Do not sneak it into diff.
+
+Every read has job. Start from task path or symbol. Grep for broad search, not for rereading known files. Read only files likely to answer current decision or be edited. Do not chase imports, shared helpers, docs, or callers unless current evidence says they matter. Aimless explore wastes context and dulls Rok. If exploration wandered, prune memory and keep only useful facts.
+
+Selected snapshots are authoritative unless edited, changed, or missing needed content.
+
+Never cut validation, data safety, security, accessibility, explicit user ask, hardware calibration.
+
+Question asked? Answer and stop. Simple question gets simple answer. If one sentence works, use one sentence. No plan, caveat list, or options unless needed. Change requested? Smallest correct change. Ambiguous? Ask one practical question.
+
+If instructed not to run checks or not to do something, obey silently. Do not report the omission in meta-speak.
+
+Final chat tiny. User saw tools and will inspect code. Do not tour work. Say only non-obvious thing human needs now. If nothing needs saying, one word.`;
+
+export function buildRokPrompt(options: BuildSystemPromptOptions, runtimeContext: RuntimeContext): string {
+	const tools = options.selectedTools ?? DEFAULT_TOOLS;
+	const prompt = [
+		ROK_CORE_PROMPT,
+		`Available tools:\n${formatToolList(tools, options.toolSnippets)}`,
+		"In addition to the tools above, you may have access to other custom tools depending on the project.",
+		`Guidelines:\n${formatGuidelines(options.promptGuidelines)}`,
+		formatPiDocsGuidance(),
+		formatTauDocsGuidance(),
+	];
+
+	if (options.customPrompt) prompt.push(options.customPrompt);
+	if (options.appendSystemPrompt) prompt.push(options.appendSystemPrompt);
+
+	const context = formatProjectContext(options.contextFiles ?? []);
+	if (context) prompt.push(context);
+
+	const skills = formatSkillsForPrompt(options.skills ?? []).trim();
+	if (skills) prompt.push(skills);
+	prompt.push(formatRuntimeContext(runtimeContext));
+
+	return prompt.join("\n\n");
+}
+
+export function freezeRuntimeContext(cwd: string): RuntimeContext {
+	return { date: formatDate(new Date()), cwd: cwd.replace(/\\/g, "/"), rootSnapshot: listRootSnapshot(cwd) };
+}
+
+function formatDate(date: Date): string {
+	const year = date.getFullYear();
+	const month = String(date.getMonth() + 1).padStart(2, "0");
+	const day = String(date.getDate()).padStart(2, "0");
+	return `${year}-${month}-${day}`;
+}
+
+function formatRuntimeContext(context: RuntimeContext): string {
+	const rootSnapshot = context.rootSnapshot.length
+		? `\nRoot directory snapshot (depth 2):\n${context.rootSnapshot.map((path) => `- ${path}`).join("\n")}`
+		: "";
+	return `Current date: ${context.date}\nCurrent working directory: ${context.cwd}${rootSnapshot}`;
+}
+
+function listRootSnapshot(cwd: string): string[] {
+	const root = resolve(cwd);
+	const rootEntries = listSnapshotEntries(root, ".");
+	const ignoredRootPaths = gitIgnoredPaths(
+		root,
+		rootEntries.map((entry) => entry.path),
+	);
+	const visibleRootEntries = rootEntries.filter(
+		(entry) => !isAlwaysHiddenFromSnapshot(entry.dirent.name) && !ignoredRootPaths.has(entry.path),
+	);
+	const childEntriesByParent = new Map<string, SnapshotEntry[]>();
+	const childPaths: string[] = [];
+
+	for (const entry of visibleRootEntries) {
+		if (!entry.dirent.isDirectory()) continue;
+		const childEntries = listSnapshotEntries(root, entry.path).filter(
+			(childEntry) => !isAlwaysHiddenFromSnapshot(childEntry.dirent.name),
+		);
+		childEntriesByParent.set(entry.path, childEntries);
+		childPaths.push(...childEntries.map((childEntry) => childEntry.path));
+	}
+
+	const ignoredChildPaths = gitIgnoredPaths(root, childPaths);
+	const paths: string[] = [];
+
+	for (const entry of visibleRootEntries) {
+		pushSnapshotPath(paths, entry);
+		if (paths.length >= ROOT_SNAPSHOT_MAX_PATHS) break;
+
+		for (const childEntry of childEntriesByParent.get(entry.path) ?? []) {
+			if (ignoredChildPaths.has(childEntry.path)) continue;
+			pushSnapshotPath(paths, childEntry);
+			if (paths.length >= ROOT_SNAPSHOT_MAX_PATHS) break;
+		}
+	}
+
+	return paths.length === ROOT_SNAPSHOT_MAX_PATHS ? [...paths, "..."] : paths;
+}
+
+function listSnapshotEntries(root: string, relativePath: string): SnapshotEntry[] {
+	let entries: Dirent[];
+	try {
+		entries = readdirSync(join(root, relativePath), { withFileTypes: true });
+	} catch {
+		return [];
+	}
+
+	return entries
+		.sort((left, right) => left.name.localeCompare(right.name))
+		.map((dirent) => ({
+			dirent,
+			path: relativePath === "." ? dirent.name : `${relativePath}/${dirent.name}`,
+		}));
+}
+
+function gitIgnoredPaths(root: string, paths: readonly string[]): Set<string> {
+	if (paths.length === 0) return new Set();
+
+	const result = spawnSync("git", ["check-ignore", "-z", "--stdin"], {
+		cwd: root,
+		encoding: "utf8",
+		input: `${paths.join("\0")}\0`,
+	});
+
+	if (result.status === 0 || result.status === 1) {
+		return new Set(result.stdout.split("\0").filter(Boolean));
+	}
+	return new Set(paths.filter((path) => path.split("/").includes("node_modules")));
+}
+
+function isAlwaysHiddenFromSnapshot(name: string): boolean {
+	return name === ".git";
+}
+
+function pushSnapshotPath(paths: string[], entry: SnapshotEntry): void {
+	if (paths.length >= ROOT_SNAPSHOT_MAX_PATHS) return;
+	paths.push(entry.dirent.isDirectory() ? `${entry.path}/` : entry.path);
+}
+
+function formatToolList(tools: readonly string[], snippets: Record<string, string> | undefined): string {
+	const visible = tools.filter((name) => snippets?.[name]);
+	return visible.length ? visible.map((name) => `- ${name}: ${snippets?.[name]}`).join("\n") : "(none)";
+}
+
+function formatGuidelines(guidelines: readonly string[] | undefined): string {
+	const result: string[] = [];
+	const seen = new Set<string>();
+	const add = (guideline: string): void => {
+		const normalized = guideline.trim();
+		if (!normalized || seen.has(normalized)) return;
+		seen.add(normalized);
+		result.push(normalized);
+	};
+
+	for (const guideline of guidelines ?? []) add(guideline);
+	add("Be concise in your responses");
+	add("Show file paths clearly when working with files");
+
+	return result.map((guideline) => `- ${guideline}`).join("\n");
+}
+
+function formatPiDocsGuidance(): string {
+	return `Pi documentation (read only when the user asks about pi itself, its SDK, extensions, themes, skills, or TUI):
+- Main documentation: ${getReadmePath()}
+- Additional docs: ${getDocsPath()}
+- Examples: ${getExamplesPath()} (extensions, custom tools, SDK)
+- When reading pi docs or examples, resolve docs/... under Additional docs and examples/... under Examples, not the current working directory
+- When asked about: extensions (docs/extensions.md, examples/extensions/), themes (docs/themes.md), skills (docs/skills.md), prompt templates (docs/prompt-templates.md), TUI components (docs/tui.md), keybindings (docs/keybindings.md), SDK integrations (docs/sdk.md), custom providers (docs/custom-provider.md), adding models (docs/models.md), pi packages (docs/packages.md)
+- When working on pi topics, read the docs and examples, and follow .md cross-references before implementing
+- Always read pi .md files completely and follow links to related docs (e.g., tui.md for TUI API details)`;
+}
+
+function formatTauDocsGuidance(): string {
+	return `Tau Agent documentation (read only when the user asks about Tau Agent, Rok, Tau extensions, Tau event APIs, harness behavior, or extending Tau Agent):
+- Tau Agent docs: ${getTauDocsPath()}
+- When asked about: public events / external integration (docs/extending-tau-agent.md), custom subagents (docs/subagents.md), Tau TUI components (docs/tui.md)
+- Resolve Tau docs/... under Tau Agent docs, not the current working directory
+- When working on Tau topics, read the docs and follow .md cross-references before implementing
+- Do not read Tau Agent docs for normal coding tasks`;
+}
+
+function getTauDocsPath(): string {
+	return join(resolveTauPackageRoot(), "docs");
+}
+
+function resolveTauPackageRoot(): string {
+	const start = dirname(fileURLToPath(import.meta.url));
+	for (let dir = start; ; dir = dirname(dir)) {
+		const packagePath = join(dir, "package.json");
+		if (existsSync(packagePath) && packageName(packagePath) === "@shanepadgett/tau-agent") return dir;
+		const parent = dirname(dir);
+		if (parent === dir) break;
+	}
+	return resolve(start, "../..");
+}
+
+function packageName(packagePath: string): string | undefined {
+	try {
+		const data: unknown = JSON.parse(readFileSync(packagePath, "utf8"));
+		if (!data || typeof data !== "object") return undefined;
+		const name = (data as Record<string, unknown>).name;
+		return typeof name === "string" ? name : undefined;
+	} catch {
+		return undefined;
+	}
+}
+
+function formatProjectContext(contextFiles: readonly { path: string; content: string }[]): string {
+	if (contextFiles.length === 0) return "";
+
+	return [
+		"<project_context>",
+		"",
+		"Project-specific instructions and modelines:",
+		"",
+		...contextFiles.map(
+			({ path, content }) => `<project_instructions path="${path}">\n${content}\n</project_instructions>`,
+		),
+		"",
+		"</project_context>",
+	].join("\n");
+}

package/extensions/soul/settings.ts

@@ -0,0 +1,13 @@
+import { Type } from "typebox";
+import { defineTauExtensionSettings } from "../../shared/settings/define.ts";
+
+export default defineTauExtensionSettings({
+	key: "soul",
+	defaults: { enabled: true as boolean },
+	schema: Type.Object(
+		{
+			enabled: Type.Optional(Type.Boolean({ default: true, description: "Enable Tau's Rok system prompt." })),
+		},
+		{ additionalProperties: false },
+	),
+});

package/extensions/stash/README.md

@@ -0,0 +1,48 @@
+# Stash
+
+Park a half-typed prompt without leaving the keyboard, then pop it back into the
+editor later. Mirrors the storage shape of `ideas` but with git-stash
+semantics: popping removes the item from the list.
+
+## Usage
+
+```text
+stash shortcut  Stash whatever is in the prompt editor (TUI only; check Pi keybindings)
+/pop            Browse stashed prompts and pop one into the editor (TUI)
+```
+
+## Behavior
+
+- Stashed prompts are stored for the user at `~/.pi/tau/stash.jsonl`, shared
+  across repos and pi sessions.
+- The stash shortcut reads the current editor text, trims it, and appends a
+  record `{ id, text, createdAt }`. It then clears the editor so you can type a
+  different prompt. Nothing happens if the editor is empty.
+- Identical text already in the stash is skipped (no duplicate entries) and the
+  stash key reports "Already stashed."
+- `/pop` opens a native TUI browser. Stashes are shown newest-first with a
+  relative age.
+- Browser keys:
+  - type to filter (case-insensitive substring)
+  - `↑` / `↓` move selection
+  - `enter` pop the selected stash into the prompt editor (raw, not submitted)
+    **and remove it from the store**
+  - `ctrl+d` discard the selected stash without restoring it (confirms first)
+  - `esc` / `ctrl+c` cancel
+- Pops are not auto-submitted; you stay in control of the prompt. To return a
+  popped prompt to the list, stash it again.
+
+## Why this exists
+
+Stashing lets you bail out of a draft to handle something urgent without losing
+the text, and keeps the parking lot short by removing items when they're
+restored rather than leaving them to accumulate.
+
+## Limits
+
+- The stash keybinding and `/pop` browser are TUI-only; there is no print/JSON/
+  RPC path (the whole point is interacting with the prompt editor mid-type).
+- The store file lives in the user's home directory and is not part of the
+  repo.
+- Mutations rewrite the whole file (atomic temp + rename); safe for single-user
+  TUI use, not designed for concurrent writers.

package/extensions/stash/browser.ts

@@ -0,0 +1,51 @@
+import type { ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import { Key } from "@earendil-works/pi-tui";
+import { rawHint } from "@shanepadgett/tau-tui";
+import {
+	createTextRecordSelectPanel,
+	type TextRecordSelectPanelConfig,
+	type TextRecordSelectResult,
+} from "@shanepadgett/tau-tui";
+import { loadStashes, removeStash, type Stash, stashFilePath } from "./store.ts";
+
+const CONFIG: Omit<TextRecordSelectPanelConfig, "path"> = {
+	title: "Stash",
+	emptyMessage: "No stashed prompts. Use the stash shortcut while typing to stash.",
+	primaryLabel: "pop",
+	actions: [{ id: "discard", key: Key.ctrl("d"), hint: rawHint("ctrl+d", "discard") }],
+	expandActiveItem: false,
+};
+
+export async function browseStash(ctx: ExtensionCommandContext): Promise<Stash | undefined> {
+	if (ctx.mode !== "tui" || !ctx.hasUI) {
+		ctx.ui.notify("Stash browser requires TUI mode.", "error");
+		return undefined;
+	}
+
+	const path = await stashFilePath(ctx.cwd);
+
+	while (true) {
+		const stashes = await loadStashes(ctx.cwd);
+		const result = await show(ctx, stashes, path);
+
+		if (result.kind === "cancel") return undefined;
+		if (result.kind === "primary") return result.item;
+
+		// discard: drop the stashed prompt without restoring it.
+		const ok = await ctx.ui.confirm("Discard stashed prompt?", result.item.text);
+		if (ok) {
+			await removeStash(ctx.cwd, result.item.id);
+			ctx.ui.notify("Stash discarded.", "info");
+		}
+	}
+}
+
+async function show(
+	ctx: ExtensionCommandContext,
+	stashes: readonly Stash[],
+	path: string,
+): Promise<TextRecordSelectResult<Stash>> {
+	return ctx.ui.custom<TextRecordSelectResult<Stash>>((_tui, theme, _keybindings, done) =>
+		createTextRecordSelectPanel(theme, stashes, { ...CONFIG, path }, done),
+	);
+}

package/extensions/stash/index.ts

@@ -0,0 +1,55 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Key } from "@earendil-works/pi-tui";
+import { preview } from "../../shared/text.ts";
+import { browseStash } from "./browser.ts";
+import { addStash, removeStash } from "./store.ts";
+
+export default function stashExtension(pi: ExtensionAPI): void {
+	// Stash = keybinding only. You hit it mid-type to park whatever's in the
+	// editor without leaving the keyboard to run a slash command.
+	pi.registerShortcut(Key.alt("s"), {
+		description: "Stash the current prompt draft",
+		handler: async (_ctx) => {
+			if (_ctx.mode !== "tui" || !_ctx.hasUI) {
+				_ctx.ui.notify("Stash keybinding works only in TUI mode.", "error");
+				return;
+			}
+
+			const text = _ctx.ui.getEditorText().trim();
+			if (!text) {
+				_ctx.ui.notify("Nothing to stash.", "info");
+				return;
+			}
+
+			const stash = await addStash(_ctx.cwd, text);
+			if (!stash) {
+				_ctx.ui.notify("Already stashed.", "info");
+				return;
+			}
+
+			_ctx.ui.setEditorText("");
+			_ctx.ui.notify(`Stashed: ${preview(stash.text, 60)}`, "info");
+		},
+	});
+
+	// Pop = command, opens the browser. Restoring a stash removes it from the
+	// store so the list doesn't linger; re-stash to put it back.
+	pi.registerCommand("pop", {
+		description: "Browse stashed prompts and pop one into the editor (TUI)",
+		handler: async (_args, ctx) => {
+			await ctx.waitForIdle();
+
+			if (ctx.mode !== "tui") {
+				ctx.ui.notify("Run /pop in TUI to browse stashed prompts.", "info");
+				return;
+			}
+
+			const stash = await browseStash(ctx);
+			if (!stash) return;
+
+			ctx.ui.setEditorText(stash.text);
+			await removeStash(ctx.cwd, stash.id);
+			ctx.ui.notify("Popped into the editor — edit and submit.", "info");
+		},
+	});
+}

package/extensions/stash/store.ts

@@ -0,0 +1,36 @@
+import { homedir } from "node:os";
+import { join } from "node:path";
+import {
+	appendRecordAtPath,
+	loadRecordsAtPath,
+	saveRecordsAtPath,
+	type DatedRecord,
+} from "../../shared/jsonl-store.ts";
+
+export type Stash = DatedRecord;
+
+const STASH_FILENAME = "stash.jsonl";
+const LABEL = "stash";
+
+export function stashFilePath(_cwd: string): Promise<string> {
+	return Promise.resolve(join(homedir(), ".pi", "tau", STASH_FILENAME));
+}
+
+export async function loadStashes(cwd: string): Promise<Stash[]> {
+	return loadRecordsAtPath(await stashFilePath(cwd), LABEL);
+}
+
+// Returns null when identical text already exists (dedupe), so callers can
+// report a no-op without polluting the list with duplicates.
+export async function addStash(cwd: string, text: string): Promise<Stash | null> {
+	const trimmed = text.trim();
+	if ((await loadStashes(cwd)).some((stash) => stash.text === trimmed)) return null;
+	return appendRecordAtPath(await stashFilePath(cwd), trimmed);
+}
+
+export async function removeStash(cwd: string, id: string): Promise<Stash[]> {
+	const stashes = await loadStashes(cwd);
+	const next = stashes.filter((stash) => stash.id !== id);
+	await saveRecordsAtPath(await stashFilePath(cwd), next);
+	return next;
+}

package/extensions/subagent/README.md

@@ -0,0 +1,34 @@
+# Subagent
+
+Subagent delegates one focused task to an isolated child Pi session. It keeps the parent conversation small while making child capabilities explicit, bounded, and abortable.
+
+Agent definitions can override the parent model and thinking level. If an override is unavailable, Tau warns once per session and uses the corresponding parent value.
+
+Tau includes two read-only agents:
+
+- `scout` explores local files and code with `read`, `grep`, `find`, and `ls`.
+- `web-research` researches web and code sources with `websearch`, `codesearch`, and `webfetch`.
+
+Ask Tau to delegate a task, or let it call `subagent` with an agent name and task. Children use the parent's current working directory and inherit its model and thinking level unless their definition overrides either value. They do not receive the parent conversation. When a child must inspect another repository, put its exact absolute path in the delegated task.
+
+## Agent definitions
+
+Add Markdown definitions at `~/.pi/agent/tau/agents/*.md` or, in a trusted project, the nearest `.pi/tau/agents/*.md`. Project definitions override user definitions, which override built-ins. Duplicate names in one scope are invalid.
+
+```markdown
+---
+name: api-reader
+description: Inspect API declarations and usage
+tools:
+  - read
+  - grep
+model: openai-codex/gpt-5.6-sol
+thinking: medium
+---
+
+Stay within the delegated task. Return exact paths and symbols.
+```
+
+`name`, `description`, and `tools` are required. Optional `model` uses `provider/model`; optional `thinking` accepts `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, or `max`. Tool names must be unique, and `subagent` cannot be delegated. Named tools and configured models must exist in the normally loaded child Pi environment.
+
+At most four children run at once. Additional calls wait in order. Returned text is limited to 50 KB or 2,000 lines; complete truncated output is saved to a private temporary file outside project repositories.

package/extensions/subagent/agents/scout.md

@@ -0,0 +1,85 @@
+---
+name: scout
+description: Find local files, symbols, data flow, constraints, and unknowns without changing anything
+tools:
+  - read
+  - grep
+  - find
+  - ls
+model: openai-codex/gpt-5.6-luna
+thinking: high
+---
+
+Stay inside delegated task. Answer exactly what was asked. No broader questions, background collection, unrequested recommendations, or mutations.
+
+Delegating prompt is output contract. Requested shape wins. Otherwise use smallest matching shape below.
+
+## Inspection discipline
+
+1. Extract exact target, question, and required output before searching.
+2. Start with named paths and symbols. Use `grep` or `find` for specific evidence. Do not map repository.
+3. Every read answers a pending question. Read smallest useful range. Follow imports, callers, or related files only when evidence requires it.
+4. Use `lineNumbers: true` for text supporting findings. Cite exact `path:start-end` ranges from tool output. Never estimate line numbers.
+5. Stop when every requested field has evidence. Put unresolved facts under `Unknowns`. Do not explore unrelated code for completeness.
+
+Absolute paths may identify readable reference repositories outside current working directory.
+
+## Result shapes
+
+Use only relevant sections. Omit empty sections.
+
+### Locate
+
+`path:start-end` — symbol — match reason
+
+### Explain behavior
+
+- `Entry:` `path:start-end` — symbol
+- `Flow:` ordered steps; one cited fact per step
+- `Result:` observed outcome
+
+Only branches relevant to requested behavior.
+
+### Trace data
+
+- `Source:` cited origin
+- `Transforms:` ordered, cited transformations
+- `Consumers:` cited uses
+
+### Find references or impact
+
+- `Direct references:` cited relationships
+- `Behavior affected:` evidence-backed consequences
+- `Unknowns:` remaining uncertainty
+
+No speculative blast radius.
+
+### Verify a claim
+
+- `Verdict:` `yes`, `no`, `partially`, or `unknown`
+- `Evidence:` cited facts
+- `Qualification:` only when needed
+
+### Compare
+
+- `Shared:` cited similarities
+- `Differences:` cited differences by aspect
+- `Relevant consequence:` requested consequences only
+
+### Inventory
+
+`path:start-end` — symbol — role
+
+When completeness matters, state searched scope. If completeness cannot be guaranteed, say why.
+
+### Constraints and unknowns
+
+- `Constraints:` constraint — supporting citation
+- `Unknowns:` missing fact — evidence needed
+
+## Reporting rules
+
+- Every material code claim needs exact path, line range, and symbol when one exists.
+- Separate observed facts from inference. Label inference.
+- Quote smallest fragment needed to disambiguate. No whole functions or blocks when citation and concise description suffice.
+- No preamble, search log, generic repository summary, repeated evidence, or unrequested next steps.