@pharaoh-so/mcp 0.3.52 → 0.3.54

package/.mcp.json

@@ -3,7 +3,7 @@
 		"pharaoh": {
 			"command": "npx",
 			"args": [
-				"@pharaoh-so/mcp@0.3.52"
+				"@pharaoh-so/mcp@0.3.54"
 			]
 		}
 	}

package/CHANGELOG.md

@@ -5,6 +5,26 @@ All notable changes to `@pharaoh-so/mcp` will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.3.54] - 2026-10-24
+
+### Added
+- The interactive setup (`npx @pharaoh-so/mcp` in a terminal) asks once whether to add one line to `~/.claude/CLAUDE.md`: "In repos Pharaoh has mapped, before searching or reading files, ask Pharaoh where the relevant code is, what calls it, and whether what you need already exists." Enter means yes. In Pharaoh's adoption benchmark, Claude Code called Pharaoh first when this line was in a CLAUDE.md, and rarely when the same sentence came from the server instructions or a plugin hook.
+- The line sits between `<!-- pharaoh-mcp:start … -->` and `<!-- pharaoh-mcp:end -->` markers. Setup appends that block or replaces the line inside it, and nothing else in the file changes. A symlinked file is left alone, and a proxy start (Claude Code launching the server) never asks or writes. Your answer is saved in `~/.pharaoh/claude-md-answer`, so a no stands.
+
+### Changed
+- `--clean` and `--logout` also remove that block, leaving the rest of the file byte for byte, and delete the saved answer so the next setup asks again.
+- `--logout` deletes the saved credentials first, so a cleanup step that fails can't leave them behind.
+
+## [0.3.53] - 2026-10-23
+
+### Changed
+- The Trace card is a compact receipt: the finding with its counts, a verdict such as risk, and one bar showing where the results sit (callers by module, dead or possibly unused, matches by module, code by module). The evidence opens on Details. A single-tool card is about 80px tall instead of 290 to 2,200px.
+- While a tool runs, the card says what Pharaoh is doing ("Tracing callers of parseEvent…"). Caveats such as an incomplete graph or a stale map stay visible while the evidence is closed.
+
+### Fixed
+- With no `claude` CLI on PATH, `npx @pharaoh-so/mcp` stops before sign-in and says why: setup registers Pharaoh through that CLI, and the Claude desktop app's built-in Claude Code isn't on PATH. The message gives the CLI installer. It used to link the desktop app download, write the slash commands anyway and end with "Pharaoh is ready".
+- When `claude mcp add` fails, setup ends without "Pharaoh is ready" and names the `claude mcp add` command to run by hand.
+
 ## [0.3.52] - 2026-10-23
 
 ### Added

package/dist/helpers.d.ts

@@ -1,13 +1,23 @@
-/**
- * Pure helper functions for the mcp-proxy CLI — no side effects on import.
- * Separated from index.ts so tests can import without triggering main().
- */
 import type { TokenResponse } from "./auth.js";
 import type { Credentials } from "./credentials.js";
 /** The npx command users run to set up Pharaoh. Single source of truth for all output. */
 export declare const NPX_COMMAND = "npx @pharaoh-so/mcp";
 /** Write one or more lines to stderr. */
 export declare function printLines(...lines: string[]): void;
+/**
+ * Ask a yes/no question that defaults to yes: Enter, `y` or `yes` is yes; `n`
+ * or `no` is no; anything else asks again. Ctrl-C exits (130). On a terminal,
+ * keys pressed before the question showed (an Enter while sign-in waited) are
+ * dropped, so only a key pressed after reading it answers.
+ *
+ * @param question - The prompt, ending in something like `[Y/n] `.
+ * @param input - Where the answer is read (defaults to stdin).
+ * @param output - Where the prompt is written (defaults to stderr, like every other line).
+ * @returns The answer, or null when input ended before one.
+ */
+export declare function askYesNo(question: string, input?: NodeJS.ReadableStream & {
+    isTTY?: boolean;
+}, output?: NodeJS.WritableStream): Promise<boolean | null>;
 /** Parse CLI arguments. */
 export declare function parseArgs(argv?: string[]): {
     server: string;

package/dist/helpers.js

@@ -1,3 +1,8 @@
+/**
+ * Pure helper functions for the mcp-proxy CLI — no side effects on import.
+ * Separated from index.ts so tests can import without triggering main().
+ */
+import { createInterface } from "node:readline/promises";
 import { isExpired } from "./credentials.js";
 const DEFAULT_SERVER = "https://mcp.pharaoh.so";
 /** The npx command users run to set up Pharaoh. Single source of truth for all output. */
@@ -6,6 +11,54 @@ export const NPX_COMMAND = "npx @pharaoh-so/mcp";
 export function printLines(...lines) {
     process.stderr.write(`${lines.join("\n")}\n`);
 }
+/** How long to read and drop input that was typed before a question showed. */
+const TYPE_AHEAD_MS = 50;
+/**
+ * Ask a yes/no question that defaults to yes: Enter, `y` or `yes` is yes; `n`
+ * or `no` is no; anything else asks again. Ctrl-C exits (130). On a terminal,
+ * keys pressed before the question showed (an Enter while sign-in waited) are
+ * dropped, so only a key pressed after reading it answers.
+ *
+ * @param question - The prompt, ending in something like `[Y/n] `.
+ * @param input - Where the answer is read (defaults to stdin).
+ * @param output - Where the prompt is written (defaults to stderr, like every other line).
+ * @returns The answer, or null when input ended before one.
+ */
+export async function askYesNo(question, input = process.stdin, output = process.stderr) {
+    if (input.isTTY)
+        await dropTypedAhead(input);
+    const rl = createInterface({ input, output });
+    rl.on("SIGINT", () => {
+        output.write("\n");
+        process.exit(130);
+    });
+    rl.setPrompt(question);
+    rl.prompt();
+    try {
+        // The iterator ends on EOF; rl.question never settles then.
+        for await (const reply of rl) {
+            const answer = reply.trim().toLowerCase();
+            if (answer === "" || answer === "y" || answer === "yes")
+                return true;
+            if (answer === "n" || answer === "no")
+                return false;
+            rl.prompt();
+        }
+        return null;
+    }
+    finally {
+        rl.close();
+    }
+}
+/** Read and drop the input already waiting, in raw mode so a half-typed line goes too. */
+async function dropTypedAhead(input) {
+    input.setRawMode?.(true);
+    const drop = () => { };
+    input.on("data", drop);
+    await new Promise((resolve) => setTimeout(resolve, TYPE_AHEAD_MS));
+    input.off("data", drop);
+    input.pause();
+}
 /** Parse CLI arguments. */
 export function parseArgs(argv = process.argv.slice(2)) {
     let server = DEFAULT_SERVER;
@@ -42,7 +95,7 @@ export function parseArgs(argv = process.argv.slice(2)) {
     return { server, logout };
 }
 export function printUsage() {
-    printLines("Usage: pharaoh-mcp [options]", "", "Options:", "  --server <url>    Pharaoh server URL (default: https://mcp.pharaoh.so)", "  --logout          Clear credentials, MCP config and the Claude Code plugin, then exit", "  --clean           Remove Pharaoh's MCP entries and plugin from Claude Code config", "  --install-skills  Reinstall the Claude Code plugin and OpenClaw skills", "  --version, -v     Print the version", "  --help, -h        Show this help", "", "Get started:", `  ${NPX_COMMAND}`, "");
+    printLines("Usage: pharaoh-mcp [options]", "", "Options:", "  --server <url>    Pharaoh server URL (default: https://mcp.pharaoh.so)", "  --logout          Clear credentials, MCP config, the Claude Code plugin and the CLAUDE.md line, then exit", "  --clean           Remove Pharaoh's MCP entries, plugin and CLAUDE.md line from Claude Code", "  --install-skills  Reinstall the Claude Code plugin and OpenClaw skills", "  --version, -v     Print the version", "  --help, -h        Show this help", "", "Get started:", `  ${NPX_COMMAND}`, "");
 }
 /**
  * Validate that a server-supplied SSE URL shares the same origin as the configured server.

package/dist/index.js

@@ -16,8 +16,8 @@ import { pollForToken, printActivationPrompt, printAuthSuccess, requestDeviceCod
 import { AuthRequiredBackend, createSseBackend } from "./backend.js";
 import { deleteCredentials, readCredentials, writeCredentials, } from "./credentials.js";
 import { createGateway } from "./gateway.js";
-import { formatTtl, parseArgs, printLines, printUsage, resolveSseUrl, tokenToCredentials, } from "./helpers.js";
-import { allowReadTools, describeAllowReadTools, formatKeptCommands, runInstallSkills, } from "./install-skills.js";
+import { askYesNo, formatTtl, parseArgs, printLines, printUsage, resolveSseUrl, tokenToCredentials, } from "./helpers.js";
+import { allowReadTools, CLAUDE_MD_QUESTION, describeAllowReadTools, describeClaudeMdOutcome, formatKeptCommands, offerClaudeMdLine, runInstallSkills, } from "./install-skills.js";
 import { handleRefreshFailure, tryMidSessionRefresh } from "./lifecycle.js";
 import { TenantSuspendedError, TokenExpiredError } from "./proxy.js";
 import { startInAuthRequiredMode, startInSseMode } from "./proxy-server.js";
@@ -61,17 +61,18 @@ async function main() {
         const { uninstallClaudePlugin } = await import("./install-skills.js");
         cleanSlate();
         uninstallClaudePlugin();
-        printLines("Pharaoh: cleaned all MCP entries and the plugin from Claude Code config");
+        printLines("Pharaoh: removed its MCP entries, plugin and ~/.claude/CLAUDE.md line from Claude Code");
         process.exit(0);
     }
     const { server, logout } = parseArgs(args);
     if (logout) {
         const { cleanSlate } = await import("./setup.js");
         const { uninstallClaudePlugin } = await import("./install-skills.js");
+        // Credentials first: a cleanup step that fails must never leave the tokens behind.
+        deleteCredentials();
         cleanSlate();
         uninstallClaudePlugin();
-        deleteCredentials();
-        printLines("Pharaoh: credentials, MCP config and the Claude Code plugin cleared");
+        printLines("Pharaoh: credentials, MCP config, the Claude Code plugin and the ~/.claude/CLAUDE.md line cleared");
         process.exit(0);
     }
     const isInteractive = Boolean(process.stdin.isTTY);
@@ -80,6 +81,13 @@ async function main() {
     // Running `npx @pharaoh-so/mcp` is the only command a user needs.
     if (isInteractive) {
         process.stderr.write(`${BANNER}\n`);
+        // Setup registers everything through the `claude` CLI on PATH. Without it,
+        // stop before sign-in: nothing is written and saved credentials stay.
+        const { claudeCliMissing, hasClaude, runSetup } = await import("./setup.js");
+        if (!hasClaude()) {
+            printLines(...claudeCliMissing());
+            process.exit(1);
+        }
         // Always re-authenticate for a fresh session
         deleteCredentials();
         const deviceCode = await requestDeviceCode(server);
@@ -92,10 +100,11 @@ async function main() {
         const newCreds = tokenToCredentials(token, sseUrl);
         writeCredentials(newCreds);
         printAuthSuccess(token.github_login ?? null, token.tenant_name ?? null, token.repos?.length ?? 0);
-        // Register MCP server + install skills (silent — user doesn't need internals)
+        // Register MCP server + install skills (silent — user doesn't need internals).
+        // runSetup has printed the failure and the command to run by hand; no success line.
+        if (!runSetup({ silent: true }))
+            process.exit(1);
         process.stderr.write("  Setting up...");
-        const { runSetup } = await import("./setup.js");
-        runSetup({ silent: true });
         const { keptCommands } = runInstallSkills(undefined, { silent: true });
         process.stderr.write(" done.\n");
         // Two things the user must hear about: their settings.json (the only
@@ -105,6 +114,11 @@ async function main() {
         const kept = formatKeptCommands(keptCommands);
         if (kept)
             printLines(kept);
+        // The one line agents act on (bench #1305) goes in the user's own
+        // ~/.claude/CLAUDE.md, so it's asked about once, here, never on a start.
+        const claudeMd = describeClaudeMdOutcome(await offerClaudeMdLine(() => askYesNo(CLAUDE_MD_QUESTION), Boolean(process.stdin.isTTY && process.stderr.isTTY)));
+        if (claudeMd)
+            printLines(claudeMd);
         // The registration is pinned to this version; upgrading is a deliberate
         // re-run. Interactive only, and quiet when the registry can't be reached.
         const latest = await fetchLatestVersion();

package/dist/install-skills.d.ts

@@ -7,8 +7,9 @@ import { type ClaudeCli } from "./setup.js";
  */
 export declare function claudePluginState(home?: string): "enabled" | "disabled" | "absent";
 /**
- * Uninstall Pharaoh's Claude Code plugin: through the CLI, then the local
- * marketplace directory and any pre-marketplace install.
+ * Uninstall Pharaoh's Claude Code plugin (through the CLI, then the local
+ * marketplace directory and any pre-marketplace install) and its block in
+ * ~/.claude/CLAUDE.md. Run by --clean and --logout.
  *
  * @param home - Home directory override (defaults to os.homedir()).
  * @param claude - `claude` CLI runner (defaults to the real CLI for `home`).
@@ -83,6 +84,29 @@ export declare function allowReadTools(home?: string): AllowReadToolsResult;
  * @param result - What `allowReadTools` returned.
  */
 export declare function describeAllowReadTools(result: AllowReadToolsResult): string;
+/** What the interactive setup asks before writing the line. */
+export declare const CLAUDE_MD_QUESTION = "Pharaoh: add one line to ~/.claude/CLAUDE.md so Claude checks Pharaoh before searching your code?\n  \"In repos Pharaoh has mapped, before searching or reading files, ask Pharaoh where the relevant code is, what calls it, and whether what you need already exists.\"\n[Y/n] ";
+/** What `offerClaudeMdLine` did; `describeClaudeMdOutcome` words it. */
+export type ClaudeMdOutcome = "added" | "updated" | "declined" | "kept" | "failed" | "current" | "answered" | "cancelled" | "no-terminal" | "no-claude";
+/**
+ * Offer the Pharaoh-first line in ~/.claude/CLAUDE.md. Interactive setup only,
+ * never a proxy start. Asks only when the block is absent and the user hasn't
+ * answered before; a stale block (an earlier yes) is updated without asking.
+ * The line is appended inside markers, and nothing else in the file changes.
+ *
+ * @param ask - Asks the user: true for yes, false for no, null when input ended.
+ * @param isTerminal - Whether stdin and stderr are a terminal; false asks and writes nothing.
+ * @param home - Home directory override (defaults to os.homedir()).
+ * @returns What happened, for `describeClaudeMdOutcome`.
+ */
+export declare function offerClaudeMdLine(ask: () => Promise<boolean | null>, isTerminal: boolean, home?: string): Promise<ClaudeMdOutcome>;
+/**
+ * The line the interactive setup prints for an `offerClaudeMdLine` outcome, or
+ * null when there is nothing to say (already current, already answered, no terminal).
+ *
+ * @param outcome - What `offerClaudeMdLine` returned.
+ */
+export declare function describeClaudeMdOutcome(outcome: ClaudeMdOutcome): string | null;
 /** What `runInstallSkills` wants the caller to tell the user. */
 export interface InstallResult {
     /** Files in ~/.claude/commands/ left as they were because they are not Pharaoh's. */

package/dist/install-skills.js

@@ -6,12 +6,12 @@
  * and OpenClaw skills in ~/.openclaw/skills/. Also merges the Pharaoh MCP
  * server config into OpenClaw.
  */
-import { cpSync, existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, writeFileSync, } from "node:fs";
+import { closeSync, constants, cpSync, existsSync, lstatSync, mkdirSync, openSync, readdirSync, readFileSync, renameSync, rmSync, writeFileSync, } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { ensurePharaohHome } from "./credentials.js";
-import { claudeCliFor } from "./setup.js";
+import { CLAUDE_CLI_SETUP_URL, claudeCliFor } from "./setup.js";
 import { getPackageVersion, PACKAGE_NAME, pinnedPackageSpec } from "./version.js";
 const __dirname = dirname(fileURLToPath(import.meta.url));
 /** Path to the bundled package root (one level up from dist/). */
@@ -202,8 +202,9 @@ function removeLegacyClaudePlugin(home) {
 /** Plugin id the pre-marketplace installer wrote into installed_plugins.json. */
 const LEGACY_PLUGIN_ID = "pharaoh@pharaoh-so";
 /**
- * Uninstall Pharaoh's Claude Code plugin: through the CLI, then the local
- * marketplace directory and any pre-marketplace install.
+ * Uninstall Pharaoh's Claude Code plugin (through the CLI, then the local
+ * marketplace directory and any pre-marketplace install) and its block in
+ * ~/.claude/CLAUDE.md. Run by --clean and --logout.
  *
  * @param home - Home directory override (defaults to os.homedir()).
  * @param claude - `claude` CLI runner (defaults to the real CLI for `home`).
@@ -213,6 +214,7 @@ export function uninstallClaudePlugin(home = homedir(), claude = claudeCliFor(ho
     claude(["plugin", "marketplace", "remove", MARKETPLACE_NAME]);
     rmSync(claudeMarketplaceDir(home), { recursive: true, force: true });
     removeLegacyClaudePlugin(home);
+    removeClaudeMdBlock(home);
 }
 /**
  * Copy every skill directory from `srcDir` to `dstDir`, prefixing both the
@@ -675,6 +677,199 @@ export function describeAllowReadTools(result) {
             return "Pharaoh: ~/.claude/settings.json is not valid JSON; left as is. Pharaoh's tools ask before they run.";
     }
 }
+// ── Claude Code instructions (~/.claude/CLAUDE.md) ──────────────────
+//
+// Agents acted on the Pharaoh-first line only from a CLAUDE.md, not from server
+// instructions or a hook (benchmarks/adoption/results/2026-10-23-everyday-auto-line.md).
+// The file is the user's: the interactive setup adds the line on a yes, inside
+// markers, and --clean/--logout remove exactly what it wrote.
+/** The Pharaoh-first line; same text as PHARAOH_SCOPED_LINE in scripts/adoption-grade.ts. */
+const PHARAOH_CLAUDE_MD_LINE = "In repos Pharaoh has mapped, before searching or reading files, ask Pharaoh where the relevant code is, what calls it, and whether what you need already exists.";
+/** What the interactive setup asks before writing the line. */
+export const CLAUDE_MD_QUESTION = `Pharaoh: add one line to ~/.claude/CLAUDE.md so Claude checks Pharaoh before searching your code?\n  "${PHARAOH_CLAUDE_MD_LINE}"\n[Y/n] `;
+/** File under ~/.pharaoh holding the user's answer, so setup asks once. */
+const CLAUDE_MD_ANSWER_FILE = "claude-md-answer";
+/**
+ * Open flags that refuse a symlink even if one is swapped in after the check
+ * (SC-7; O_NOFOLLOW is undefined on Windows). A new block is appended, so the
+ * user's bytes are never rewritten; a stale block or a removal rewrites the file.
+ */
+const NO_FOLLOW = constants.O_NOFOLLOW ?? 0;
+const APPEND_NO_FOLLOW = constants.O_WRONLY | constants.O_CREAT | constants.O_APPEND | NO_FOLLOW;
+const REWRITE_NO_FOLLOW = constants.O_WRONLY | constants.O_TRUNC | NO_FOLLOW;
+/** Write `text` to `path` opened with `flags` (APPEND_NO_FOLLOW or REWRITE_NO_FOLLOW). */
+function writeNoFollow(path, text, flags) {
+    const fd = openSync(path, flags);
+    try {
+        writeFileSync(fd, text);
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+/**
+ * Pharaoh's block. `pharaoh-mcp:start+nl` records that the installer also added
+ * the newline before it (the file didn't end in one), so removal takes it back too.
+ */
+function claudeMdBlock(addedNewline) {
+    const start = `<!-- pharaoh-mcp:start${addedNewline ? "+nl" : ""} (managed by npx ${PACKAGE_NAME}; --clean or --logout removes it) -->`;
+    return `${start}\n${PHARAOH_CLAUDE_MD_LINE}\n<!-- pharaoh-mcp:end -->\n`;
+}
+/**
+ * Find the one Pharaoh block in `text`: null when there is none, "broken"
+ * when a marker is missing its pair, repeated or out of order.
+ */
+function findClaudeMdBlock(text) {
+    const starts = [...text.matchAll(/^<!-- pharaoh-mcp:start(\+nl)?\b[^\n]*\n/gm)];
+    const ends = [...text.matchAll(/^<!-- pharaoh-mcp:end -->\n?/gm)];
+    if (starts.length === 0 && ends.length === 0)
+        return null;
+    const [start, end] = [starts[0], ends[0]];
+    const body = start ? start.index + start[0].length : 0;
+    if (starts.length !== 1 || ends.length !== 1 || end.index < body)
+        return "broken";
+    return {
+        from: start.index,
+        body,
+        to: end.index,
+        through: end.index + end[0].length,
+        addedNewline: start[1] !== undefined,
+    };
+}
+/** Read ~/.claude/CLAUDE.md without following a symlink. */
+function readClaudeMd(home) {
+    const path = join(home, ".claude", "CLAUDE.md");
+    const dir = lstatSync(join(home, ".claude"), { throwIfNoEntry: false });
+    if (!dir)
+        return { state: "no-claude", path, text: "", block: null };
+    const file = lstatSync(path, { throwIfNoEntry: false });
+    if (!dir.isDirectory() || (file && !file.isFile())) {
+        return { state: "kept", path, text: "", block: null };
+    }
+    const text = file ? readFileSync(path, "utf-8") : "";
+    const block = findClaudeMdBlock(text);
+    if (block === "broken")
+        return { state: "kept", path, text, block: null };
+    if (!block) {
+        return {
+            state: text.includes(PHARAOH_CLAUDE_MD_LINE) ? "current" : "absent",
+            path,
+            text,
+            block,
+        };
+    }
+    const current = text.slice(block.body, block.to) === `${PHARAOH_CLAUDE_MD_LINE}\n`;
+    return { state: current ? "current" : "stale", path, text, block };
+}
+/**
+ * Offer the Pharaoh-first line in ~/.claude/CLAUDE.md. Interactive setup only,
+ * never a proxy start. Asks only when the block is absent and the user hasn't
+ * answered before; a stale block (an earlier yes) is updated without asking.
+ * The line is appended inside markers, and nothing else in the file changes.
+ *
+ * @param ask - Asks the user: true for yes, false for no, null when input ended.
+ * @param isTerminal - Whether stdin and stderr are a terminal; false asks and writes nothing.
+ * @param home - Home directory override (defaults to os.homedir()).
+ * @returns What happened, for `describeClaudeMdOutcome`.
+ */
+export async function offerClaudeMdLine(ask, isTerminal, home = homedir()) {
+    if (!isTerminal)
+        return "no-terminal";
+    const answerPath = join(home, ".pharaoh", CLAUDE_MD_ANSWER_FILE);
+    try {
+        let file = readClaudeMd(home);
+        // A saved answer also silences the add-it-yourself line of "kept": a no stands.
+        const answered = lstatSync(answerPath, { throwIfNoEntry: false }) !== undefined;
+        if (answered && (file.state === "absent" || file.state === "kept"))
+            return "answered";
+        if (file.state === "absent") {
+            const yes = await ask();
+            if (yes === null)
+                return "cancelled";
+            if (!yes) {
+                saveClaudeMdAnswer(home, answerPath, "no");
+                return "declined";
+            }
+            file = readClaudeMd(home); // again: it may have changed while the user answered
+        }
+        if (file.state === "absent") {
+            const newline = file.text !== "" && !file.text.endsWith("\n");
+            writeNoFollow(file.path, `${newline ? "\n" : ""}${claudeMdBlock(newline)}`, APPEND_NO_FOLLOW);
+            saveClaudeMdAnswer(home, answerPath, "yes");
+            return "added";
+        }
+        if (file.state === "stale") {
+            const { body, to } = file.block;
+            const next = `${file.text.slice(0, body)}${PHARAOH_CLAUDE_MD_LINE}\n${file.text.slice(to)}`;
+            writeNoFollow(file.path, next, REWRITE_NO_FOLLOW);
+            return "updated";
+        }
+        return file.state;
+    }
+    catch {
+        // ALLOWED-CATCH: setup is done; the user gets the line to add by hand, and no saved answer, so the next setup asks again
+        return "failed";
+    }
+}
+/** Save the user's answer (0600). Never through a symlink: `wx` refuses any existing path. */
+function saveClaudeMdAnswer(home, answerPath, answer) {
+    try {
+        ensurePharaohHome(join(home, ".pharaoh"));
+        writeFileSync(answerPath, `${answer}\n`, { mode: 0o600, flag: "wx" });
+    }
+    catch {
+        // ALLOWED-CATCH: an answer that can't be saved only means the next setup asks again
+    }
+}
+/**
+ * The line the interactive setup prints for an `offerClaudeMdLine` outcome, or
+ * null when there is nothing to say (already current, already answered, no terminal).
+ *
+ * @param outcome - What `offerClaudeMdLine` returned.
+ */
+export function describeClaudeMdOutcome(outcome) {
+    const byHand = `To have Claude check Pharaoh first, add this line to it yourself:\n  ${PHARAOH_CLAUDE_MD_LINE}`;
+    switch (outcome) {
+        case "added":
+            return `Pharaoh: added the line to ~/.claude/CLAUDE.md, between pharaoh-mcp markers. npx ${PACKAGE_NAME} --clean removes it.`;
+        case "updated":
+            return "Pharaoh: updated its line in ~/.claude/CLAUDE.md.";
+        case "declined":
+            return "Pharaoh: left ~/.claude/CLAUDE.md as it is. Setup won't ask again.";
+        case "kept":
+            return `Pharaoh: left ~/.claude/CLAUDE.md as it is (it's a symlink, or its Pharaoh markers don't pair up). ${byHand}`;
+        case "failed":
+            return `Pharaoh: couldn't write ~/.claude/CLAUDE.md. ${byHand}`;
+        default:
+            return null;
+    }
+}
+/**
+ * Remove Pharaoh's block from ~/.claude/CLAUDE.md, taking out only bytes the
+ * installer wrote, and forget the answer so the next setup asks again. A file
+ * left empty stays: there's no telling whether the user had it before. Never
+ * throws: --clean and --logout go on to their other steps.
+ *
+ * @param home - Home directory override (defaults to os.homedir()).
+ */
+function removeClaudeMdBlock(home) {
+    try {
+        const { path, text, block } = readClaudeMd(home);
+        if (block) {
+            // The newline before a start+nl marker is Pharaoh's only while the block
+            // ends the file; once the user writes below it, it ends their line.
+            const ownsNewline = block.addedNewline && block.from > 0 && block.through === text.length;
+            const from = ownsNewline ? block.from - 1 : block.from;
+            writeNoFollow(path, text.slice(0, from) + text.slice(block.through), REWRITE_NO_FOLLOW);
+        }
+        rmSync(join(home, ".pharaoh", CLAUDE_MD_ANSWER_FILE), { force: true });
+    }
+    catch (err) {
+        // ALLOWED-CATCH: the other cleanup steps (credentials on --logout) must still run; the user is told what's left
+        const code = err.code;
+        process.stderr.write(`Pharaoh: couldn't remove its line from ~/.claude/CLAUDE.md${code ? ` (${code})` : ""}. Delete the pharaoh-mcp block by hand.\n`);
+    }
+}
 /**
  * Main entry point for --install-skills, also run on every proxy start.
  *
@@ -766,7 +961,7 @@ export function runInstallSkills(home = homedir(), options) {
             "Pharaoh: no supported skill platform detected.",
             "",
             "Supported platforms:",
-            "  • Claude Code — install from https://claude.ai/download",
+            `  • Claude Code — install the CLI from ${CLAUDE_CLI_SETUP_URL}`,
             "  • Codex      — install from https://developers.openai.com/codex",
             "  • OpenClaw   — install from https://openclaw.dev/install",
             "",

package/dist/setup.d.ts

@@ -1,5 +1,24 @@
 /** Runs one `claude` CLI command; true on success. */
 export type ClaudeCli = (args: string[]) => boolean;
+/** Anthropic's Claude Code CLI install page: every platform and install method. */
+export declare const CLAUDE_CLI_SETUP_URL = "https://code.claude.com/docs/en/setup";
+/**
+ * Whether a `claude` CLI on PATH starts. It is launched the way `runClaude`
+ * launches it, so the check and the commands agree, with no `which` (minimal
+ * containers lack it). The Claude desktop app's bundled copy isn't on PATH.
+ *
+ * @returns True when `claude --version` runs.
+ */
+export declare function hasClaude(): boolean;
+/**
+ * What setup prints when no `claude` CLI is on PATH: npx registers everything
+ * through that CLI, the desktop app's copy doesn't count, and the CLI shares
+ * ~/.claude with the desktop app, so installing it covers the Code tab too.
+ *
+ * @param platform - Picks the one-line installer (PowerShell on Windows).
+ * @returns The lines to print.
+ */
+export declare function claudeCliMissing(platform?: NodeJS.Platform): string[];
 /**
  * A `claude` CLI runner for the Claude Code config under `home`: true when the
  * command succeeded, false when it failed or `claude` isn't installed. Another

package/dist/setup.js

@@ -11,20 +11,54 @@ import { homedir } from "node:os";
 import { join } from "node:path";
 import { NPX_COMMAND, printLines } from "./helpers.js";
 import { pinnedPackageSpec } from "./version.js";
-/** Check if `claude` CLI is available in PATH. */
-function hasClaude() {
+/** Anthropic's Claude Code CLI install page: every platform and install method. */
+export const CLAUDE_CLI_SETUP_URL = "https://code.claude.com/docs/en/setup";
+/** Pharaoh's setup guide for agents other than Claude Code (stdio server, sign-in on first call). */
+const HEADLESS_SETUP_URL = "https://pharaoh.so/docs/connect/headless";
+/**
+ * Whether a `claude` CLI on PATH starts. It is launched the way `runClaude`
+ * launches it, so the check and the commands agree, with no `which` (minimal
+ * containers lack it). The Claude desktop app's bundled copy isn't on PATH.
+ *
+ * @returns True when `claude --version` runs.
+ */
+export function hasClaude() {
     try {
-        const which = process.platform === "win32" ? "where" : "which";
-        execFileSync(which, ["claude"], {
-            encoding: "utf-8",
-            stdio: ["pipe", "pipe", "pipe"],
-        });
+        execFileSync("claude", ["--version"], { stdio: "pipe", timeout: 10_000 });
         return true;
     }
     catch {
+        // A `claude` that can't be started is one setup can't use either.
         return false;
     }
 }
+/**
+ * What setup prints when no `claude` CLI is on PATH: npx registers everything
+ * through that CLI, the desktop app's copy doesn't count, and the CLI shares
+ * ~/.claude with the desktop app, so installing it covers the Code tab too.
+ *
+ * @param platform - Picks the one-line installer (PowerShell on Windows).
+ * @returns The lines to print.
+ */
+export function claudeCliMissing(platform = process.platform) {
+    // The shell goes in the label: anything after the command gets pasted with it.
+    const [shell, installer] = platform === "win32"
+        ? [" (PowerShell)", "irm https://claude.ai/install.ps1 | iex"]
+        : ["", "curl -fsSL https://claude.ai/install.sh | bash"];
+    return [
+        "Pharaoh: the claude command isn't on your PATH, so setup stopped.",
+        "",
+        "npx adds Pharaoh to Claude Code through the Claude Code CLI. The desktop app runs its own copy of Claude Code, and that copy isn't on your PATH.",
+        "",
+        `  Install the CLI${shell}: ${installer}`,
+        `  Other ways: ${CLAUDE_CLI_SETUP_URL}`,
+        `  Then, in a new terminal: ${NPX_COMMAND}`,
+        "",
+        "The CLI and the desktop app share ~/.claude, so the desktop app's Code tab gets Pharaoh too.",
+        `Not using Claude Code? OpenClaw: ${NPX_COMMAND} --install-skills. Other agents: ${HEADLESS_SETUP_URL}`,
+        "",
+    ];
+}
 /** Run a claude CLI command, returning true on success. Surfaces stderr on failure. */
 function runClaude(args, env = process.env) {
     try {
@@ -128,7 +162,7 @@ export function runSetup(options) {
     const silent = options?.silent ?? false;
     const home = options?.home ?? homedir();
     if (!options?.claude && !hasClaude()) {
-        printLines("Pharaoh: Claude Code CLI not found.", "", "Install Claude Code first: https://claude.ai/download", `Then re-run: ${NPX_COMMAND}`, "");
+        printLines(...claudeCliMissing());
         return false;
     }
     const claude = options?.claude ?? claudeCliFor(home);
@@ -142,9 +176,9 @@ export function runSetup(options) {
     claude(["mcp", "remove", "pharaoh", "-s", "project"]);
     // Step 3: Register as global stdio MCP server, pinned to the running version
     const spec = pinnedPackageSpec();
-    const added = claude(["mcp", "add", "--scope", "user", "pharaoh", "--", "npx", spec]);
-    if (!added) {
-        printLines("Pharaoh: failed to register MCP server.", `Try manually: ${NPX_COMMAND}`, "");
+    const addArgs = ["mcp", "add", "--scope", "user", "pharaoh", "--", "npx", spec];
+    if (!claude(addArgs)) {
+        printLines("Pharaoh: failed to register MCP server.", `Try manually: claude ${addArgs.join(" ")}`, "");
         return false;
     }
     if (!silent)

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "@pharaoh-so/mcp",
 	"mcpName": "so.pharaoh/pharaoh",
-	"version": "0.3.52",
+	"version": "0.3.54",
 	"description": "MCP proxy for Pharaoh — maps codebases into queryable knowledge graphs for AI agents. Enables Claude Code in headless environments (VPS, SSH, CI) via device flow auth.",
 	"type": "module",
 	"main": "dist/index.js",

package/trace-app.html

@@ -6,60 +6,117 @@
   <meta http-equiv="Content-Security-Policy" content="default-src 'none'; script-src 'unsafe-inline'; style-src 'unsafe-inline'; connect-src 'none'; img-src 'none'; font-src 'none'; object-src 'none'; frame-src 'none'; base-uri 'none'; form-action 'none'">
   <title>Pharaoh Trace</title>
   <style>
-    :root { color-scheme:dark; --bg:#171813; --text:#e5e6d8; --muted:#aaa995; --gold:#d4ad51; --yellow:#edc54c; --rule:#414236; --hover:#22251c; --error:#e3a18d; font:400 12px/1.45 ui-monospace,SFMono-Regular,Menlo,Consolas,"Liberation Mono",monospace; background:var(--bg); color:var(--text); }
-    :root[data-theme="light"] { color-scheme:light; --bg:#faf8f1; --text:#292b20; --muted:#656553; --gold:#866315; --yellow:#926700; --rule:#d8d4c5; --hover:#efede2; --error:#a13929; }
+    :root { color-scheme:dark; --stone:#2a2520; --rule:#3a352e; --track:#342e28; --hover:#332d27; --gold:#d4a843; --papyrus:#e8dcc8; --text:#c4b99a; --muted:#9d927b; --red:#f87171; --amber:#f0c855; --green:#4ade80;
+      --s0:#d4a843; --s1:#b08a3a; --s2:#8c6e31; --s3:#6e5728; --s4:#574522; --s-muted:#5f574a; --s-warning:#f0c855; --s-error:#ef4444;
+      --sans:"DM Sans",system-ui,-apple-system,"Segoe UI",sans-serif; --mono:ui-monospace,SFMono-Regular,"SF Mono",Menlo,Consolas,"Liberation Mono",monospace; }
+    :root[data-theme="light"] { color-scheme:light; --stone:#f7f3ea; --rule:#e2d8c4; --track:#ece4d3; --hover:#efe8da; --gold:#946c0f; --papyrus:#2a2520; --text:#4a4235; --muted:#71675a; --red:#b42318; --amber:#9a5b00; --green:#15803d;
+      --s0:#b08515; --s1:#c9a24a; --s2:#d9bb72; --s3:#e6cf98; --s4:#efdfb8; --s-muted:#cfc4ad; --s-warning:#e0a526; --s-error:#d93f2f; }
     * { box-sizing:border-box; }
-    body { margin:0; min-width:0; }
-    #trace { border-left:2px solid var(--gold); padding:9px 14px 8px; min-width:0; }
-    header { display:flex; flex-wrap:wrap; justify-content:space-between; align-items:baseline; gap:3px 14px; color:var(--muted); font-size:10px; }
-    #tool { overflow-wrap:anywhere; min-width:0; }
-    #status { white-space:nowrap; }
-    #status[data-state="ok"] { color:#4ade80; }
-    #status[data-state="pending"],.filled { color:var(--yellow); }
-    #status[data-state="error"] { color:var(--error); }
-    #trace[data-pending="true"] #status { animation:pending 1.4s ease-in-out infinite alternate; }
-    @keyframes pending { from { opacity:.55; } to { opacity:1; } }
-    #repo { font-size:14px; margin:4px 0 0; overflow-wrap:anywhere; }
-    #provenance { color:var(--muted); font-size:10px; overflow-wrap:anywhere; margin-top:2px; }
-    h1 { font-size:14px; line-height:1.5; font-weight:500; margin:6px 0 0; overflow-wrap:anywhere; }
-    #summary { margin:2px 0 0; color:var(--muted); overflow-wrap:anywhere; }
-    ul { list-style:none; padding:0; margin:4px 0 0; min-width:0; }
-    li { min-width:0; }
-    summary,.row { display:grid; grid-template-columns:18px minmax(0,1fr) auto; gap:6px; align-items:baseline; padding:2px 0; min-width:0; }
-    summary { list-style:none; min-height:24px; border-bottom:1px solid var(--rule); cursor:pointer; }
-    summary::-webkit-details-marker { display:none; }
-    summary:hover { background:var(--hover); }
-    summary:focus-visible { outline:2px solid var(--gold); outline-offset:2px; }
-    .branch { color:var(--gold); white-space:pre; }
-    details>summary .branch::after { content:"+"; }
-    details[open]>summary .branch::after { content:"−"; }
-    .label,.detail,.badge { overflow-wrap:anywhere; white-space:pre-wrap; min-width:0; unicode-bidi:plaintext; }
-    details[open]>summary .label { color:var(--gold); }
-    .detail { display:block; color:var(--muted); font-size:10px; margin-top:1px; }
-    .badge { color:var(--muted); font-size:10px; text-align:right; }
-    .badge[data-state="ok"] { color:#4ade80; }
-    .badge[data-state="warning"],.badge[data-state="pending"] { color:var(--yellow); }
-    .badge[data-state="error"] { color:var(--error); }
-    .children { margin:0 0 3px 17px; border-left:1px solid var(--rule); padding-left:9px; }
-    .meter { display:block; color:var(--muted); font-size:11px; margin:2px 0; overflow-wrap:anywhere; }
-    #notes { border-top:1px solid var(--rule); margin-top:6px; padding-top:5px; color:var(--muted); font-size:10px; }
-    #notes p { margin:2px 0; overflow-wrap:anywhere; white-space:pre-wrap; }
-    #fallback { font:inherit; font-size:11px; margin:6px 0 0; white-space:pre-wrap; overflow-wrap:anywhere; unicode-bidi:plaintext; }
+    html,body { margin:0; background:transparent; min-width:0; }
+    .label,.detail,.badge { overflow-wrap:anywhere; min-width:0; unicode-bidi:plaintext; }
+    .mark-s { font:600 12px var(--mono); width:1ch; }
+    #trace { background:var(--stone); color:var(--text); border:1px solid var(--rule); border-radius:6px; padding:9px 12px; font:13px/1.45 var(--sans); min-width:0; }
+    .head { display:flex; flex-wrap:wrap; align-items:baseline; gap:2px 10px; }
+    .mark { color:var(--gold); font-size:14px; line-height:1; }
+    .headline { flex:1 1 16em; margin:0; min-width:0; overflow-wrap:anywhere; }
+    #kind { color:var(--muted); }
+    #target { color:var(--papyrus); font:600 13px/1.45 var(--mono); }
+    #target,.legend > span,.rows .label { unicode-bidi:isolate; }
+    #title { color:var(--papyrus); font-weight:600; }
+    #summary { margin-left:8px; }
+    .num { color:var(--gold); font:600 12.5px var(--mono); }
+    .meta { margin-left:auto; display:flex; gap:10px; white-space:nowrap; font-size:12px; }
+    #verdict[data-state="error"] { color:var(--red); } #verdict[data-state="warning"] { color:var(--amber); } #verdict[data-state="ok"] { color:var(--green); }
+    #sha { color:var(--muted); font:11.5px var(--mono); }
+    .bar { position:relative; display:flex; gap:2px; height:6px; margin:8px 0 0; border-radius:3px; overflow:hidden; background:var(--track); }
+    .bar i,.mini i { display:block; flex:0 1 0; min-width:0; }
+    .bar i[data-shown] { min-width:3px; }
+    .s0 { background:var(--s0); } .s1 { background:var(--s1); } .s2 { background:var(--s2); } .s3 { background:var(--s3); } .s4 { background:var(--s4); }
+    .muted { background:var(--s-muted); } .warning { background:var(--s-warning); } .error { background:var(--s-error); }
+    .foot { display:flex; align-items:baseline; gap:4px 14px; margin-top:6px; flex-wrap:wrap; }
+    .legend { display:flex; flex-wrap:wrap; gap:2px 14px; margin:0; color:var(--muted); font-size:12px; min-width:0; flex:1 1 auto; }
+    #trace[data-reveal] .legend { opacity:0; }
+    .legend b { color:var(--text); font:500 11.5px var(--mono); margin-left:4px; }
+    .sw { display:inline-block; width:8px; height:8px; border-radius:1px; margin-right:5px; }
+    .toggle { margin-left:auto; display:flex; align-items:baseline; gap:4px; border:0; background:none; padding:2px 0; color:var(--gold); font:12px var(--sans); cursor:pointer; white-space:nowrap; }
+    .toggle:hover { color:var(--papyrus); }
+    .toggle:focus-visible,summary:focus-visible { outline:2px solid var(--gold); outline-offset:2px; border-radius:2px; }
+    .chev { display:inline-block; font-size:10px; }
+    .toggle[aria-expanded="true"] .chev { transform:rotate(90deg); }
+    .caveat { margin:6px 0 0; color:var(--amber); font-size:12px; overflow-wrap:anywhere; }
+    .caveat span + span::before { content:" · "; color:var(--muted); }
+    .rows { list-style:none; margin:4px 0 0; padding:0; }
+    .rows li { display:flex; flex-wrap:wrap; align-items:baseline; gap:0 8px; padding:4px 0 5px; border-top:1px solid var(--rule); min-width:0; }
+    .rows li:first-child { border-top:0; }
+    .rows .kind { color:var(--muted); font-size:12.5px; }
+    .rows .label { color:var(--papyrus); font:12.5px var(--mono); }
+    .rows .prose { color:var(--text); font:12.5px var(--sans); }
+    .rows .detail { color:var(--text); font-size:12.5px; }
+    .rows .end { margin-left:auto; font-size:12px; white-space:nowrap; }
+    .rows .more { color:var(--muted); font-size:12px; }
+    .rows .mini { display:flex; gap:1px; flex:1 0 100%; height:3px; margin-top:3px; border-radius:2px; overflow:hidden; background:var(--track); }
+    [data-state="ok"] > .mark-s { color:var(--green); } [data-state="warning"] > .mark-s, [data-state="pending"] > .mark-s { color:var(--amber); } [data-state="error"] > .mark-s, .end[data-state="error"] { color:var(--red); } .end[data-state="warning"] { color:var(--amber); }
+    .drawer { display:grid; grid-template-rows:0fr; }
+    .drawer[data-open] { grid-template-rows:1fr; }
+    .drawer-inner { overflow:hidden; min-height:0; }
+    .drawer[data-open] .drawer-inner { border-top:1px solid var(--rule); margin-top:8px; padding-top:4px; }
+    ul.tree,.tree ul { list-style:none; margin:0; padding:0; }
+    .tree ul { margin:0 0 4px 6px; padding-left:10px; border-left:1px solid var(--rule); }
+    .tree summary,.leaf { display:grid; grid-template-columns:minmax(0,1fr) auto; gap:10px; align-items:baseline; padding:3px 0; font-size:12.5px; min-width:0; }
+    .tree summary { list-style:none; cursor:pointer; color:var(--text); }
+    .tree summary::-webkit-details-marker { display:none; }
+    .tree summary:hover { background:var(--hover); }
+    .tree summary .label::before { content:"▸"; display:inline-block; color:var(--gold); font-size:10px; width:12px; }
+    .tree details[open] > summary .label::before { transform:rotate(90deg); }
+    .tree details[open] > summary .label { color:var(--gold); }
+    .leaf .label { color:var(--papyrus); font:12px var(--mono); }
+    .tree > li > .leaf { padding-left:12px; }
+    .tree > li > .leaf .label { color:var(--text); font:12.5px var(--sans); }
+    .tree .label .detail { color:var(--muted); font:11px var(--mono); margin-left:8px; }
+    .tree .label .caveat { color:var(--amber); font:11.5px var(--sans); margin:0 0 0 8px; }
+    .badge { color:var(--muted); font:11.5px var(--mono); text-align:right; white-space:nowrap; }
+    .badge[data-state="ok"] { color:var(--green); } .badge[data-state="warning"],.badge[data-state="pending"] { color:var(--amber); } .badge[data-state="error"] { color:var(--red); }
+    .meter { display:block; height:3px; margin-top:3px; border-radius:2px; background:var(--track); max-width:240px; }
+    .meter i { display:block; height:100%; border-radius:2px; background:var(--gold); }
+    .notes,.provenance { color:var(--muted); font-size:11.5px; margin:6px 0 2px; }
+    .notes p { margin:2px 0; overflow-wrap:anywhere; white-space:pre-wrap; }
+    #fallback { font:11.5px/1.5 var(--mono); color:var(--text); margin:6px 0 0; white-space:pre-wrap; overflow-wrap:anywhere; unicode-bidi:plaintext; }
+    @media(max-width:400px) { #trace { padding:8px 10px; } #summary { margin-left:0; } #summary:not([hidden]) { display:block; } .tree summary,.leaf { grid-template-columns:minmax(0,1fr); gap:0; } .badge { text-align:left; } }
+    /* Motion only for people who have not asked to reduce it. */
+    @media(prefers-reduced-motion:no-preference) {
+      .bar i,.mini i { transition:flex-grow .7s cubic-bezier(.22,.8,.24,1); }
+      .legend { transition:opacity .4s ease .2s; }
+      .chev { transition:transform .3s ease; }
+      .drawer { transition:grid-template-rows .3s ease; }
+      .tree summary .label::before { transition:transform .2s ease; }
+      #trace[data-state="pending"] .bar::after,#trace[data-state="waiting"] .bar::after { content:""; position:absolute; top:0; bottom:0; left:0; width:35%; background:linear-gradient(90deg,transparent,var(--gold),transparent); opacity:.55; animation:sweep 1.3s ease-in-out infinite; }
+      @keyframes sweep { from { transform:translateX(-100%); } to { transform:translateX(290%); } }
+    }
     [hidden] { display:none; }
-    @media(max-width:400px) { #trace { padding:8px 10px 7px; } summary,.row { grid-template-columns:15px minmax(0,1fr); gap:4px; } .badge { grid-column:2; text-align:left; } .children { margin-left:9px; padding-left:7px; } }
-    @media(prefers-reduced-motion:reduce) { #trace[data-pending="true"] #status { animation:none; } }
   </style>
 </head>
 <body>
-  <main id="trace" data-pending="false">
-    <header><span id="tool">Pharaoh result</span><span id="status" role="status" aria-live="polite" aria-atomic="true">waiting</span></header>
-    <div id="repo" hidden></div>
-    <div id="provenance" hidden></div>
-    <h1 id="title">Waiting for a tool result</h1>
-    <p id="summary" hidden></p>
-    <ul id="tree" aria-label="Result evidence" hidden></ul>
-    <pre id="fallback">The tool's text response remains available in chat.</pre>
-    <div id="notes" hidden></div>
+  <main id="trace" data-state="waiting">
+    <div class="head">
+      <span class="mark" aria-hidden="true">☥</span>
+      <p class="headline"><span id="kind"></span><span id="target"></span><span id="title">Pharaoh</span><span id="summary" role="status" aria-live="polite">Waiting for the tool</span></p>
+      <span id="meta" class="meta"><span id="verdict" hidden></span><span id="sha" hidden></span></span>
+    </div>
+    <div id="bar" class="bar" aria-hidden="true"></div>
+    <div id="foot" class="foot">
+      <p id="legend" class="legend"></p>
+      <button id="toggle" class="toggle" type="button" aria-expanded="false" aria-controls="drawer" hidden><span id="toggle-label">Details</span><span class="chev" aria-hidden="true">▸</span></button>
+    </div>
+    <p id="caveat" class="caveat" hidden></p>
+    <ul id="rows" class="rows" hidden></ul>
+    <div id="drawer" class="drawer" inert>
+      <div class="drawer-inner">
+        <ul id="tree" class="tree" aria-label="Result evidence"></ul>
+        <pre id="fallback" hidden></pre>
+        <div id="notes" class="notes" hidden></div>
+        <p id="provenance" class="provenance" hidden></p>
+      </div>
+    </div>
   </main>
   <script>
     (() => {
@@ -67,11 +124,18 @@
       const META_KEY = "so.pharaoh/trace";
       const PROTOCOL_VERSION = "2026-01-26";
       // Kept in parity with TRACE_LIMITS in trace-contract.ts by the resource test.
-      const LIMITS = { bytes:65536, nodes:120, depth:6, label:512, detail:2048, badge:128, summary:1024, notes:16, note:1024, repo:256 };
+      const LIMITS = { bytes:65536, nodes:120, depth:6, label:512, detail:2048, badge:128, summary:1024, notes:16, note:1024, repo:256, segments:8 };
       const MAX_TEXT = 32768;
+      const MAX_ROWS = 5;
+      const TONES = ["warning","error","muted"];
+      const STATES = ["ok","pending","warning","error"];
+      // What each tool is doing while it runs, shown with the argument it targets.
+      const VERBS = { get_blast_radius:"Tracing callers of", get_unused_code:"Checking reachability in", search_functions:"Searching for", get_codebase_map:"Mapping", get_module_context:"Reading module", pharaoh_recon:"Running recon on", pharaoh_account:"Checking account" };
       const root = document.getElementById("trace");
-      const fields = Object.fromEntries(["tool","status","repo","provenance","title","summary","tree","fallback","notes"].map(id => [id,document.getElementById(id)]));
+      const fields = Object.fromEntries(["kind","target","title","summary","meta","verdict","sha","bar","caveat","rows","foot","legend","toggle","toggle-label","drawer","tree","fallback","notes","provenance"].map(id => [id,document.getElementById(id)]));
+      const compact = new Intl.NumberFormat("en",{notation:"compact",maximumFractionDigits:1});
       const initId = "pharaoh-trace-initialize";
+      let tool = "";
       let ready = false;
       let closed = false;
       let cancelled = false;
@@ -81,37 +145,76 @@
       const record = value => value !== null && typeof value === "object" && !Array.isArray(value);
       const string = (value,max) => typeof value === "string" && value.length <= max;
       const send = message => { if (!closed) window.parent.postMessage({jsonrpc:"2.0",...message},"*"); };
-      function status(label,state) {
-        fields.status.textContent = label;
-        fields.status.dataset.state = state;
-        root.dataset.pending = String(state === "pending");
+      function element(tag,className,text) {
+        const node = document.createElement(tag);
+        if (className) node.className = className;
+        if (text !== undefined) node.textContent = text;
+        return node;
+      }
+      // Counts read at a glance: digit runs become gold monospace spans, everything else stays text.
+      function rich(target,text) {
+        target.replaceChildren();
+        for (const part of String(text || "").split(/(\b\d[\d,.]*\b)/)) {
+          if (part) target.append(/^\d/.test(part) ? element("span","num",part) : part);
+        }
       }
       function display(field,text) {
         fields[field].textContent = text || "";
         fields[field].hidden = !text;
       }
+      // "Impact: attachTraceView" reads as a muted kind and a monospace target.
+      const splitTitle = title => /^([^:]{1,40}): (.+)$/.exec(title);
+      function headline(title,summary) {
+        const split = splitTitle(title);
+        display("kind",split ? `${split[1]} ` : "");
+        display("target",split ? split[2] : "");
+        display("title",split ? "" : title);
+        rich(fields.summary,summary);
+        fields.summary.hidden = !summary;
+      }
+      // The toggle ends the legend line, or the headline when there is no legend.
+      function place(withLegend) {
+        (withLegend ? fields.foot : fields.meta).append(fields.toggle);
+        fields.foot.hidden = !withLegend;
+      }
+      function setOpen(open) {
+        fields.drawer.toggleAttribute("data-open",open);
+        fields.drawer.toggleAttribute("inert",!open);
+        fields.toggle.setAttribute("aria-expanded",String(open));
+        fields["toggle-label"].textContent = open ? "Hide" : "Details";
+      }
+      function clearResult() {
+        setOpen(false);
+        for (const field of ["bar","rows","legend","tree","notes"]) fields[field].replaceChildren();
+        for (const field of ["verdict","sha","caveat","provenance","fallback"]) display(field,"");
+        delete fields.verdict.dataset.state;
+        fields.sha.title = "";
+        fields.bar.hidden = true;
+        fields.rows.hidden = true;
+        fields.notes.hidden = true;
+        fields.toggle.hidden = true;
+      }
       function notes(items) {
-        fields.notes.replaceChildren();
-        for (const text of items) {
-          const paragraph = document.createElement("p");
-          paragraph.textContent = text;
-          fields.notes.append(paragraph);
-        }
+        for (const text of items) fields.notes.append(element("p","",text));
         fields.notes.hidden = items.length === 0;
       }
-      function clearResult() {
-        fields.tree.replaceChildren();
-        fields.tree.hidden = true;
-        display("summary","");
-        display("provenance","");
-        notes([]);
+      function caveats(items) {
+        fields.caveat.replaceChildren(...items.map(text => element("span","",text)));
+        fields.caveat.hidden = items.length === 0;
       }
       function fallback(title,text,notice,state="neutral") {
         clearResult();
-        fields.title.textContent = title;
+        root.dataset.state = state === "error" ? "error" : "ready";
+        const first = text.split("\n").find(line => line.trim()) || "";
+        headline(title,first.length > 160 ? `${first.slice(0,159)}…` : first);
         display("fallback",text);
-        status(state === "error" ? "[!] error" : state === "cancelled" ? "[||] cancelled" : "response received",state);
+        if (state === "error" || state === "cancelled") {
+          fields.verdict.dataset.state = state === "error" ? "error" : "warning";
+          display("verdict",state === "error" ? "Failed" : "Cancelled");
+        }
         if (notice) notes([notice]);
+        fields.toggle.hidden = !text;
+        place(false);
       }
       function readableText(result) {
         if (!record(result) || !Array.isArray(result.content)) return {text:"No readable text was returned. Read the tool response in chat.",omitted:false};
@@ -129,12 +232,20 @@
         }
         return {text:text || "No readable text was returned. Read the tool response in chat.",omitted};
       }
+      function validGlance(glance) {
+        if (glance === undefined) return true;
+        if (!record(glance)) return false;
+        if (glance.segments !== undefined && (!Array.isArray(glance.segments) || glance.segments.length > LIMITS.segments || !glance.segments.every(s => record(s) && string(s.label,LIMITS.badge) && Number.isFinite(s.value) && s.value >= 0 && (s.tone === undefined || TONES.includes(s.tone))))) return false;
+        if (glance.verdict !== undefined && (!record(glance.verdict) || !string(glance.verdict.label,LIMITS.badge) || (glance.verdict.status !== undefined && !["ok","warning","error"].includes(glance.verdict.status)))) return false;
+        return glance.caveat === undefined || string(glance.caveat,LIMITS.note);
+      }
       function validView(view) {
         try {
           if (!record(view) || view.version !== 1 || !string(view.title,LIMITS.label) || !view.title.trim() || !Array.isArray(view.nodes)) return false;
           if (new TextEncoder().encode(JSON.stringify(view)).byteLength > LIMITS.bytes) return false;
           if (view.repo !== undefined && !string(view.repo,LIMITS.repo)) return false;
           if (view.summary !== undefined && !string(view.summary,LIMITS.summary)) return false;
+          if (!validGlance(view.glance)) return false;
           if (view.notes !== undefined && (!Array.isArray(view.notes) || view.notes.length > LIMITS.notes || !view.notes.every(note => string(note,LIMITS.note)))) return false;
           if (view.freshness !== undefined) {
             const value = view.freshness;
@@ -145,71 +256,145 @@
             if (++count > LIMITS.nodes || depth > LIMITS.depth || !record(node) || !string(node.label,LIMITS.label) || !node.label.trim()) return false;
             if (node.detail !== undefined && !string(node.detail,LIMITS.detail)) return false;
             if (node.badge !== undefined && !string(node.badge,LIMITS.badge)) return false;
-            if (node.status !== undefined && !["ok","pending","warning","error"].includes(node.status)) return false;
+            if (node.status !== undefined && !STATES.includes(node.status)) return false;
             if (node.meter !== undefined && (!record(node.meter) || !Number.isFinite(node.meter.value) || !Number.isFinite(node.meter.total) || node.meter.total <= 0 || node.meter.value < 0 || node.meter.value > node.meter.total)) return false;
+            if (!validGlance(node.glance)) return false;
             return node.children === undefined || (Array.isArray(node.children) && node.children.every(child => visit(child,depth + 1)));
           };
           return view.nodes.every(node => visit(node,1));
         } catch { return false; }
       }
-      function element(tag,className,text) {
-        const node = document.createElement(tag);
-        if (className) node.className = className;
-        if (text !== undefined) node.textContent = text;
-        return node;
+      // Segments start empty and grow to their share once painted: the one motion on arrival.
+      function segments(target,items) {
+        const total = items.reduce((sum,item) => sum + item.value,0);
+        if (!total) return [];
+        let shade = 0;
+        return items.filter(item => item.value > 0).map((item,index) => {
+          const slice = element("i",item.tone || `s${Math.min(shade++,4)}`);
+          slice.style.transitionDelay = `${index * 70}ms`;
+          slice.dataset.share = String(item.value / total);
+          target.append(slice);
+          return slice;
+        });
+      }
+      function grow(slices) {
+        requestAnimationFrame(() => requestAnimationFrame(() => {
+          for (const slice of slices) { slice.style.flexGrow = slice.dataset.share; slice.dataset.shown = ""; }
+          delete root.dataset.reveal;
+        }));
+      }
+      function legend(items) {
+        let shade = 0;
+        for (const item of items.filter(item => item.value > 0)) {
+          const entry = element("span");
+          entry.append(element("span",`sw ${item.tone || `s${Math.min(shade++,4)}`}`),item.label,element("b","",compact.format(item.value)));
+          fields.legend.append(entry);
+        }
       }
-      function renderNode(node,last,open=false) {
+      function verdict(target,value) {
+        if (!value) return;
+        target.textContent = value.label;
+        if (value.status) target.dataset.state = value.status;
+        target.hidden = false;
+      }
+      // Sections (recon) and status lines (states, named checks) stay visible; groups open on demand.
+      function rowFor(node,slices) {
+        const item = element("li");
+        if (node.status) {
+          item.dataset.state = node.status;
+          item.append(element("span","mark-s",{ok:"✓",pending:"…",warning:"!",error:"×"}[node.status]));
+        }
+        const split = splitTitle(node.label);
+        if (split) item.append(element("span","kind",split[1]));
+        // Names read in monospace; sentences (state messages) read as prose.
+        item.append(element("span",split || !/\s/.test(node.label) ? "label" : "label prose",split ? split[2] : node.label));
+        if (node.detail) { const detail = element("span","detail"); rich(detail,node.detail); item.append(detail); }
+        const end = element("span","end",node.badge || "");
+        end.hidden = !node.badge;
+        if (node.glance?.verdict) { end.hidden = true; verdict(end,node.glance.verdict); }
+        item.append(end);
+        if (node.glance?.caveat) item.append(element("span","detail caveat",node.glance.caveat));
+        if (node.glance?.segments?.length) {
+          const mini = element("span","mini");
+          mini.setAttribute("aria-hidden","true");
+          slices.push(...segments(mini,node.glance.segments));
+          item.append(mini);
+        }
+        return item;
+      }
+      function renderNode(node) {
         const item = element("li");
         const group = Array.isArray(node.children) && node.children.length > 0;
-        const container = group ? element("details") : item;
-        if (group && open) container.open = true;
-        const row = element(group ? "summary" : "div",group ? "" : "row");
-        const branch = element("span","branch",group ? "" : last ? "└─" : "├─");
-        branch.setAttribute("aria-hidden","true");
+        const row = element(group ? "summary" : "div",group ? "" : "leaf");
         const label = element("span","label",node.label);
         if (node.detail) label.append(element("span","detail",node.detail));
-        const symbol = {ok:"[ok]",pending:"[...]",warning:"[!]",error:"[!]"}[node.status] || "";
-        const badge = element("span","badge",[symbol,node.badge].filter(Boolean).join(" "));
-        if (node.status) badge.dataset.state = node.status;
-        row.append(branch,label,badge);
-        container.append(row);
         if (node.meter) {
-          const filled = Math.round(node.meter.value / node.meter.total * 12);
           const meter = element("span","meter");
-          meter.append("[",element("span","filled","#".repeat(filled)),`${".".repeat(12-filled)}] ${node.meter.value} / ${node.meter.total}`);
+          meter.title = `${node.meter.value} / ${node.meter.total}`;
+          const fill = element("i");
+          fill.style.width = `${Math.max(1,Math.round(node.meter.value / node.meter.total * 100))}%`;
+          meter.append(fill);
           label.append(meter);
         }
-        if (group) {
-          const children = element("ul","children");
-          node.children.forEach((child,index) => { children.append(renderNode(child,index === node.children.length-1)); });
-          container.append(children);
-          item.append(container);
-        }
+        if (node.glance?.caveat) label.append(element("span","caveat",node.glance.caveat));
+        const symbol = {ok:"✓",pending:"…",warning:"!",error:"×"}[node.status] || "";
+        const badge = element("span","badge",[symbol,node.badge || node.glance?.verdict?.label].filter(Boolean).join(" "));
+        const state = node.status || node.glance?.verdict?.status;
+        if (state) badge.dataset.state = state;
+        row.append(label,badge);
+        if (!group) { item.append(row); return item; }
+        const details = element("details");
+        const children = element("ul");
+        for (const child of node.children) children.append(renderNode(child));
+        details.append(row,children);
+        item.append(details);
         return item;
       }
       function renderView(view) {
         clearResult();
-        fields.title.textContent = view.title;
-        display("repo",view.repo);
-        display("summary",view.summary);
-        display("fallback","");
-        if (view.freshness) {
-          const freshness = view.freshness;
-          display("provenance",[freshness.mappedCommit ? `mapped ${freshness.mappedCommit}` : "mapped commit unknown",freshness.lastAnalyzed ? `as of ${freshness.lastAnalyzed}` : "map time unknown",`status: ${freshness.status}`].join(" · "));
+        cancelled = false;
+        root.dataset.state = "ready";
+        root.dataset.reveal = "";
+        const glance = view.glance || {};
+        headline(view.title,view.summary);
+        verdict(fields.verdict,glance.verdict);
+        const freshness = view.freshness;
+        if (freshness?.mappedCommit) {
+          display("sha",`@${/^[0-9a-f]{7,}$/i.test(freshness.mappedCommit) ? freshness.mappedCommit.slice(0,7) : freshness.mappedCommit.slice(0,12)}`);
+          fields.sha.title = `Mapped ${freshness.mappedCommit}${freshness.lastAnalyzed ? ` as of ${freshness.lastAnalyzed}` : ""}`;
         }
-        const firstGroup = view.nodes.findIndex(node => node.children?.length);
-        view.nodes.forEach((node,index) => { fields.tree.append(renderNode(node,index === view.nodes.length-1,index === firstGroup)); });
-        fields.tree.hidden = view.nodes.length === 0;
+        if (freshness) display("provenance",[freshness.mappedCommit ? `Mapped ${freshness.mappedCommit}` : "Mapped commit unknown",freshness.lastAnalyzed ? `as of ${freshness.lastAnalyzed}` : "map time unknown",`status: ${freshness.status}`].join(" · "));
+        caveats([glance.caveat,freshness?.status === "stale" ? "Map is behind the latest push" : ""].filter(Boolean));
+        const slices = segments(fields.bar,glance.segments || []);
+        fields.bar.hidden = slices.length === 0;
+        legend(glance.segments || []);
+        // Up to MAX_ROWS rows, warnings and verdicts first, shown in their original order.
+        const candidates = view.nodes.filter(node => node.glance || node.status);
+        const urgent = node => node.status === "error" || node.status === "warning" || node.glance?.verdict || node.glance?.caveat;
+        const chosen = new Set([...new Set([...candidates.filter(urgent),...candidates])].slice(0,MAX_ROWS));
+        const visible = candidates.filter(node => chosen.has(node));
+        for (const node of visible) fields.rows.append(rowFor(node,slices));
+        if (candidates.length > visible.length) fields.rows.append(element("li","more",`+${candidates.length - visible.length} more in Details`));
+        fields.rows.hidden = visible.length === 0;
+        for (const node of view.nodes) if (!visible.includes(node) || node.children?.length) fields.tree.append(renderNode(node));
+        // One click on Details shows evidence: the first group is already open inside the drawer.
+        fields.tree.querySelector("details")?.setAttribute("open","");
         notes(view.notes || []);
-        status("[ok] result","ok");
+        fields.toggle.hidden = !fields.tree.childElementCount && fields.notes.hidden && fields.provenance.hidden;
+        place(fields.legend.childElementCount > 0);
+        grow(slices);
       }
       function input(params) {
         cancelled = false;
         clearResult();
-        display("fallback","Waiting for the tool response.");
-        fields.title.textContent = "Request in progress";
-        display("repo",record(params.arguments) && string(params.arguments.repo,LIMITS.repo) ? params.arguments.repo : "");
-        status("[>] working","pending");
+        root.dataset.state = "pending";
+        const args = record(params.arguments) ? params.arguments : {};
+        const target = ["entity","query","module","repo"].map(key => args[key]).find(value => string(value,LIMITS.repo) && value.trim());
+        const verb = Object.hasOwn(VERBS,tool) ? VERBS[tool] : "Querying the Pharaoh graph";
+        headline("","");
+        display("kind",target ? `${verb} ` : `${verb}…`);
+        display("target",target ? `${target}…` : "");
+        fields.bar.hidden = false;
       }
       function result(params) {
         if (cancelled) return;
@@ -226,7 +411,7 @@
       function context(params) {
         if (params.theme === "dark" || params.theme === "light") document.documentElement.dataset.theme = params.theme;
         const name = params.toolInfo?.tool?.name;
-        if (string(name,128)) fields.tool.textContent = name;
+        if (string(name,128)) tool = name;
       }
       function size() {
         if (!ready || closed || resizeFrame) return;
@@ -244,7 +429,9 @@
       const observer = typeof ResizeObserver === "function" ? new ResizeObserver(size) : null;
       observer?.observe(root);
       root.addEventListener("toggle",size,true);
+      root.addEventListener("transitionend",size);
       window.addEventListener("resize",size);
+      fields.toggle.addEventListener("click",() => { setOpen(fields.toggle.getAttribute("aria-expanded") !== "true"); size(); });
       function receive(event) {
         if (closed || event.source !== window.parent || !record(event.data) || event.data.jsonrpc !== "2.0") return;
         const message = event.data;
@@ -271,7 +458,7 @@
             clearTimeout(initTimeout);
             cancelAnimationFrame(resizeFrame);
             observer?.disconnect();
-            root.dataset.pending = "false";
+            root.dataset.state = "ready";
             window.removeEventListener("message",receive);
           } else send({id:message.id,error:{code:-32601,message:"Unsupported request"}});
           return;
@@ -289,7 +476,7 @@
       const initTimeout = setTimeout(() => {
         if (!ready && !closed) fallback("Text response available","Read the tool response in chat.","Trace has not received a host connection.");
       },10000);
-      send({id:initId,method:"ui/initialize",params:{appInfo:{name:"Pharaoh Trace",version:"1.1.0"},appCapabilities:{availableDisplayModes:["inline"]},protocolVersion:PROTOCOL_VERSION}});
+      send({id:initId,method:"ui/initialize",params:{appInfo:{name:"Pharaoh Trace",version:"1.2.0"},appCapabilities:{availableDisplayModes:["inline"]},protocolVersion:PROTOCOL_VERSION}});
     })();
   </script>
 </body>