@herbertgao/pi-extensions 2026.8.15 → 2026.9.1

package/node_modules/pi-lens/scripts/analyze-pi-lens-logs.mjs

@@ -221,6 +221,35 @@ function createState(files) {
 				progress: [],
 			},
 		},
+		// #2526: the config stack's positive-observability rows. `resolved`
+		// counts `config_resolved` phase records; `legacyWithoutRecords` counts
+		// the rows that carry a deprecated document but produced no
+		// migration/notice record — the deprecation machinery gone silent.
+		//
+		// Round 2, F2: the session->row relation is a JOIN on the session id both
+		// sides carry, not a subtraction of two counts.
+		//
+		// Round 3, S1: the session-side half of the join is no longer a
+		// PREDICTION. `pendingSessions` holds every session id that published a
+		// `config_resolution_pending` mark — written by `loadLSPConfig` itself,
+		// at the instant a resolution is actually attempted, never by a
+		// `runtime-session.ts` handler guessing from `no-lsp`/subagent/warm-attach
+		// flags ahead of time. A session that never reaches that call (quick or
+		// minimal mode's second-and-later session in a process, for the same
+		// root) never gets a mark, so it is silently excluded rather than
+		// counted against. `resolvedSessions` holds every session id a
+		// resolution actually reported, from EITHER sink (the latency row or the
+		// sessionstart line — one call writes both, so this is one fact
+		// surviving an independent rotation of either log, not a second source
+		// of truth).
+		config: {
+			resolved: 0,
+			pendingSessions: new Map(),
+			resolvedSessions: new Set(),
+			legacyDocuments: 0,
+			legacyWithoutRecords: 0,
+			examples: [],
+		},
 		diagnostics: {
 			bySeverity: counter(),
 			byTool: counter(),
@@ -351,7 +380,44 @@ async function analyzeLatency(files, state) {
 			} else if (entry.type === "phase") {
 				const phase = entry.phase ?? "unknown";
 				state.latency.phaseCounts.inc(phase);
-				if (/_timeout$/.test(phase)) state.latency.phaseTimeouts.inc(phase);
+				if (phase.endsWith("_timeout")) state.latency.phaseTimeouts.inc(phase);
+				if (phase === "config_resolved") {
+					// #2526. Counted here rather than derived from phaseCounts so the
+					// legacy/record cross-check reads the same row it counts.
+					state.config.resolved += 1;
+					const md = entry.metadata ?? {};
+					// #2526 R2 F2 / #2552 R4: the join key is (session, root), not
+					// session alone — see `configJoinKey`'s doc comment. `entry.filePath`
+					// is this row's root (the same `configResolutionKey(cwd)` value the
+					// pending mark's `root=` carries); a row from a build that predates
+					// the session id carries none, and simply joins to nothing.
+					if (
+						typeof md.sessionId === "string" &&
+						md.sessionId.length > 0 &&
+						typeof entry.filePath === "string" &&
+						entry.filePath.length > 0
+					) {
+						state.config.resolvedSessions.add(
+							configJoinKey(md.sessionId, entry.filePath),
+						);
+					}
+					const documents = Array.isArray(md.documents) ? md.documents : [];
+					const legacy = documents.filter((doc) => doc?.legacy === true);
+					state.config.legacyDocuments += legacy.length;
+					// A deprecated document that produced NO record means the
+					// migration notices went silent — the user is on a removal
+					// schedule and is never told. Zero records with zero legacy
+					// documents is the correct canonical-only answer, not a smell.
+					if (legacy.length > 0 && Number(md.recordCount ?? 0) === 0) {
+						state.config.legacyWithoutRecords += 1;
+						pushTop(
+							state.config.examples,
+							summarizeConfigResolved(entry, "legacy document with 0 records"),
+							limit * 3,
+							byDuration,
+						);
+					}
+				}
 				if (
 					phase === "total" &&
 					(entry.durationMs ?? 0) >= thresholds.totalSlowMs
@@ -636,6 +702,40 @@ async function analyzeSessionStart(files, state) {
 				trackProject(state, cwd);
 			}
 
+			// #2526 R3 S1: this session's config-resolution PENDING mark, published
+			// by `loadLSPConfig` itself at the instant a resolution is actually
+			// attempted — never a start-line prediction from `no-lsp`/subagent/
+			// warm-attach flags. A session that never calls `loadLSPConfig` (quick
+			// or minimal mode's second-and-later session in a process, for the
+			// same root) never writes this line, and is correctly absent from the
+			// join rather than counted against.
+			//
+			// #2552 R4: `root=` is REQUIRED in the match — a warm MCP process keeps
+			// one session id for its whole life but marks once per served root
+			// (`configJoinKey`'s doc comment), so a line missing it cannot be
+			// attributed to a specific root and is left out of the join rather than
+			// guessed into a wrong one.
+			const pending =
+				/session_start config_resolution_pending session=(\S+) root=(.*)$/.exec(
+					message,
+				);
+			if (pending) {
+				const [, sessionId, root] = pending;
+				state.config.pendingSessions.set(configJoinKey(sessionId, root), {
+					ts: iso(ts),
+					sessionId,
+					root,
+				});
+			}
+			// The loader's own line is the second half of the join, so a rotated
+			// latency.log cannot manufacture a deficit on its own.
+			const resolvedSession =
+				/config resolved .*\bsession=(\S+) root=(.*)$/.exec(message);
+			if (resolvedSession) {
+				const [, sessionId, root] = resolvedSession;
+				state.config.resolvedSessions.add(configJoinKey(sessionId, root));
+			}
+
 			const total = /session_start total:\s*(\d+)ms/.exec(message);
 			if (total && Number(total[1]) >= thresholds.startupSlowMs) {
 				state.smellTotals.inc("slow-session-start");
@@ -899,6 +999,23 @@ function iso(date) {
 	return date?.toISOString?.() ?? "unknown";
 }
 
+/**
+ * The config-resolution join key (#2552 review round 4). A warm MCP process
+ * keeps ONE session id for its entire life but calls `loadLSPConfig` once per
+ * SERVED ROOT (#2526 review round 2, F3's premise, reintroduced one layer up
+ * here) — joining on session id alone let one root's row silently clear every
+ * OTHER root's deficit under the same session id. `root` is whatever string
+ * the producer already wrote (the pending mark's `root=`, or the row's own
+ * `filePath` — both come from the SAME `configResolutionKey(cwd)` call in
+ * `clients/lsp/config.ts`, which folds separators, canonicalizes, then folds
+ * again — `normalizeFilePath(path.resolve(normalizeFilePath(cwd)))`, in that
+ * order (#2518 review F6; resolving first breaks POSIX backslash names), so they compare equal without this script re-deriving any
+ * path normalization of its own).
+ */
+function configJoinKey(sessionId, root) {
+	return `${sessionId} ${root}`;
+}
+
 function counter() {
 	const map = new Map();
 	return {
@@ -985,6 +1102,33 @@ function summarizeLatency(entry) {
 	};
 }
 
+/**
+ * A `config_resolved` row (#2526), summarised for a smell example.
+ *
+ * Deliberately NOT `summarizeLatency`: that helper's metadata whitelist would
+ * drop every field this row carries, so the example would print a phase name
+ * and nothing a reader could act on.
+ */
+function summarizeConfigResolved(entry, note) {
+	const md = entry.metadata ?? {};
+	const documents = Array.isArray(md.documents) ? md.documents : [];
+	return {
+		ts: entry.ts,
+		durationMs: entry.durationMs,
+		phase: entry.phase,
+		project: projectOf(entry.filePath),
+		note,
+		documents: documents
+			.map(
+				(doc) =>
+					`${doc?.tier ?? "?"}:${doc?.file ?? "?"}${doc?.legacy ? " (legacy)" : ""}`,
+			)
+			.slice(0, 8),
+		recordCount: md.recordCount,
+		deniedServers: md.deniedServers,
+	};
+}
+
 function summarizeWorkspaceSweep(entry) {
 	const md = entry.metadata ?? {};
 	const bits = [];
@@ -1193,6 +1337,43 @@ function buildReport(state) {
 		`session_start background tasks >= ${thresholds.backgroundSlowMs}ms`,
 		state.session.slowTasks.slice(0, limit),
 	);
+	// #2526: config resolution has to prove it HAPPENED. Two shapes, one smell:
+	//
+	// (a) a session that has a `config_resolution_pending` mark and produced no
+	//     `config_resolved` row. Round 3, S1: the pending mark is written by
+	//     `loadLSPConfig` itself, at the instant a resolution is actually
+	//     attempted — never predicted from a handler's own flags ahead of time.
+	//     Round 2, F2 established the JOIN itself: on the session id both sides
+	//     carry, never a subtraction of two counts (subtracting counted quick
+	//     sessions' rows against full sessions' start lines — different
+	//     populations — which both masked total silence and charged
+	//     `--no-lsp`/subagent sessions with a permanent deficit they could never
+	//     clear).
+	//     Round 4, #2552 review: the join is on (session, root), not session
+	//     alone — a warm MCP process keeps one session id for its whole life but
+	//     marks once per SERVED ROOT (`configJoinKey`'s doc comment), so one
+	//     root's row must not clear another root's deficit under the same id.
+	// (b) a legacy document present with zero records — the deprecation
+	//     machinery went silent while the user is on a removal schedule.
+	const pendingConfigResolution = [...state.config.pendingSessions.entries()];
+	const unresolvedSessions = pendingConfigResolution.filter(
+		([key]) => !state.config.resolvedSessions.has(key),
+	);
+	for (const [, value] of unresolvedSessions.slice(0, limit * 3)) {
+		state.config.examples.push({
+			ts: value.ts,
+			session: value.sessionId,
+			root: value.root,
+			note: "session had a config_resolution_pending mark and produced no config_resolved row",
+		});
+	}
+	addSmell(
+		smells,
+		"config-resolution",
+		unresolvedSessions.length + state.config.legacyWithoutRecords,
+		`Sessions with a config_resolution_pending mark but no config_resolved row (${unresolvedSessions.length} of ${pendingConfigResolution.length}) or a legacy config document that produced no migration record (${state.config.legacyWithoutRecords})`,
+		state.config.examples.slice(0, limit),
+	);
 	addSmell(
 		smells,
 		"cascade-fallbacks",
@@ -1352,6 +1533,16 @@ function buildReport(state) {
 			rotations: state.session.rotations.toJSON(),
 			errors: state.session.errors.slice(0, limit),
 		},
+		// #2526: the positive-observability counters behind the
+		// `config-resolution` smell, so a reader can see WHY it fired (or that
+		// it correctly did not) without re-deriving the deficit.
+		config: {
+			resolved: state.config.resolved,
+			sessionsPendingResolution: pendingConfigResolution.length,
+			sessionsWithoutResolution: unresolvedSessions.length,
+			legacyDocuments: state.config.legacyDocuments,
+			legacyWithoutRecords: state.config.legacyWithoutRecords,
+		},
 		actionable: {
 			events: state.actionable.events.toJSON(),
 			reports: state.actionable.reports,

package/node_modules/pi-lens/scripts/install-selftest.mjs

@@ -17,7 +17,9 @@
  * Force-imports the modules whose TOP-LEVEL bare imports are the documented
  * failure points, plus the bare specifiers directly, and checks the two
  * build-script-provided assets (ast-grep CLI binary + tree-sitter grammars)
- * that pnpm/bun skip by default. It runs no model and needs no credentials.
+ * that pnpm/bun skip by default. It also resolves the `pi.skills` manifest
+ * entries the way pi does, from the installed package root (#2587). It runs no
+ * model and needs no credentials.
  *
  * WHAT IT NO LONGER COVERS (#1926)
  * pi supplies `typebox` and `@earendil-works/pi-tui` from its own runtime, so
@@ -47,6 +49,7 @@ import { createRequire } from "node:module";
 import * as path from "node:path";
 import { fileURLToPath } from "node:url";
 import { HOST_PROVIDED_PACKAGES } from "./lib/host-provided-deps.mjs";
+import { collectSkillEntryPaths } from "./lib/skills-predicate.mjs";
 
 const here = path.dirname(fileURLToPath(import.meta.url));
 const pkgRoot = path.resolve(here, "..");
@@ -242,6 +245,56 @@ try {
 }
 record("tree-sitter grammars", "asset", hasCoreGrammar, grammarDetail);
 
+// --- 4. pi.skills manifest resolution, AS INSTALLED (#2587) ----------------
+// Guards the recurrence of #2587: a `pi.skills` entry that resolves outside the
+// installed package, so pi registers none of the shipped skills. This probe runs
+// from the INSTALLED package (`require.resolve("pi-lens/scripts/…")`), so it sees
+// the real layout — hoisted node_modules, pnpm's symlink store, bun, yarn — which
+// is exactly where `../../skills` escaped and where a static check on the source
+// tree cannot look. Replicates pi's own resolver, `PackageManager#collectFiles\
+// FromManifestEntries` in `@earendil-works/pi-coding-agent`
+// `dist/core/package-manager.js`: a non-glob entry is `resolve(packageRoot, entry)`
+// (verified identical in 0.78.1 / 0.84.1 / 0.85.1).
+//
+// #2626 review round 2 (F2): the "does this dir have a skill" walk used to be
+// a hand-rolled `countSkillFiles` here AND a second, differently-wrong one in
+// `clients/skills-resolver.ts`. Both now derive from the ONE structural
+// predicate in `./lib/skills-predicate.mjs`, which replicates pi's actual
+// `loadSkillsFromDirInternal` walk (see that module's header for the exact
+// discovery rules and the two documented scope gaps).
+{
+	const pkgJson = JSON.parse(
+		fs.readFileSync(path.join(pkgRoot, "package.json"), "utf8"),
+	);
+	const entries = pkgJson.pi?.skills ?? [];
+	if (entries.length === 0) {
+		record("pi.skills declared", "manifest", false, "pi.skills is empty");
+	}
+	for (const entry of entries) {
+		const label = `pi.skills "${entry}"`;
+		// pi globs entries containing * or ? through a different branch; this
+		// probe only replicates the non-glob one.
+		if (/[*?]/.test(entry)) {
+			record(label, "manifest", true, "glob entry — not probed");
+			continue;
+		}
+		const resolved = path.resolve(pkgRoot, entry);
+		if (resolved !== pkgRoot && !resolved.startsWith(pkgRoot + path.sep)) {
+			record(label, "manifest", false, `escapes the package: ${resolved}`);
+			continue;
+		}
+		const found = collectSkillEntryPaths(resolved).length;
+		record(
+			label,
+			"manifest",
+			found > 0,
+			found > 0
+				? `${found} SKILL.md under ${resolved}`
+				: `no SKILL.md under ${resolved}`,
+		);
+	}
+}
+
 // --- Report ----------------------------------------------------------------
 const pad = Math.max(...results.map((r) => r.name.length));
 let hardFail = 0;
@@ -249,7 +302,10 @@ let softFail = 0;
 for (const r of results) {
 	const soft = (r.kind === "asset" || r.kind === "tool") && allowSoft;
 	const status = r.ok ? "PASS" : soft ? "WARN" : "FAIL";
-	if (!r.ok) soft ? softFail++ : hardFail++;
+	if (!r.ok) {
+		if (soft) softFail++;
+		else hardFail++;
+	}
 	console.log(
 		`  [${status}] ${r.name.padEnd(pad)} ${r.detail ? "— " + r.detail : ""}`,
 	);

package/node_modules/pi-lens/scripts/lib/skills-predicate.mjs

@@ -0,0 +1,129 @@
+// The ONE structural replica of pi's own skill-loading walk (#2626 review
+// round 2, F1/F2).
+//
+// Two independent detectors used to answer "does this directory tree hold a
+// skill pi would load" with two DIFFERENT, hand-rolled heuristics that both
+// diverged from pi's real resolver:
+//   - `clients/skills-resolver.ts` (a `SKILL.md` one level down only, no
+//     recursion, no root `.md` acceptance, no symlink-follow, no dot/
+//     node_modules skip)
+//   - `scripts/install-selftest.mjs`'s `countSkillFiles` (recursed
+//     UNBOUNDED — would double-count a `SKILL.md` sitting inside another
+//     skill's own resource subdirectory — with no dot/node_modules skip, no
+//     root `.md` acceptance, no symlink handling)
+// Neither matched `loadSkillsFromDirInternal` in
+// `@earendil-works/pi-coding-agent` `dist/core/skills.js` (mirrored by
+// `collectSkillEntries` in `dist/core/package-manager.js`, byte-identical
+// walk, confirmed against the 0.85.1 tarball). This module is the fold: BOTH
+// consumers now derive from `collectSkillEntryPaths` below.
+//
+// Discovery rules, replicated from `loadSkillsFromDirInternal` (verified
+// against the extracted 0.85.1 `skills.js`):
+//   1. If `dir` directly contains a (non-symlink-broken) `SKILL.md`, `dir` IS
+//      one skill root — return immediately, do NOT look at `dir`'s other
+//      entries or recurse into its subdirectories (a `SKILL.md` inside a
+//      skill's own reference/ subfolder is the skill's OWN resource, not a
+//      second skill).
+//   2. Otherwise, skip dot-prefixed entries and `node_modules`; recurse into
+//      every remaining subdirectory (same two rules, one level down); at the
+//      OUTERMOST call only (`isRoot`), a loose `*.md` file directly in `dir`
+//      also counts (pi's `includeRootFiles`, true only for the top call).
+//   3. A symlink is followed via `statSync` (broken symlink = skip) for BOTH
+//      the `SKILL.md` check and the directory/file classification in step 2.
+//
+// Deliberately NOT replicated (out of #2626's scope — packaging/path
+// resolution, not skill-content validation):
+//   - `.gitignore`/`.ignore`/`.fdignore` matching inside the skills tree.
+//   - frontmatter parsing: pi additionally requires a non-empty `description`
+//     field before a discovered file becomes a loaded skill. A `SKILL.md`
+//     file that exists but fails THAT validation is a content-authoring
+//     defect a maintainer would see in normal use, not a silent zero.
+// Both gaps mean this predicate can be a bit more OPTIMISTIC than pi's true
+// count in a pathological case (an ignored or description-less file still
+// counts as "found" here); it is never more PESSIMISTIC — every real skill
+// pi loads is found by this walk too — which is the direction #2626 cares
+// about (never claim "no skills" when pi would load one).
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+/**
+ * Symlink-aware entry classification, mirroring `loadSkillsFromDirInternal`'s
+ * own `entry.isSymbolicLink() ? statSync(fullPath) : entry`.
+ * @param {string} fullPath
+ * @param {import("node:fs").Dirent} entry
+ * @returns {"file" | "dir" | "other"}
+ */
+export function resolvedEntryKind(fullPath, entry) {
+	if (entry.isSymbolicLink()) {
+		try {
+			const stats = fs.statSync(fullPath);
+			if (stats.isDirectory()) return "dir";
+			if (stats.isFile()) return "file";
+			return "other";
+		} catch {
+			return "other"; // broken symlink
+		}
+	}
+	if (entry.isDirectory()) return "dir";
+	if (entry.isFile()) return "file";
+	return "other";
+}
+
+/**
+ * The structural walk over an ALREADY-READ directory listing — split out
+ * from `collectSkillEntryPaths` so a caller that already has `entries` (a
+ * top-level ENOENT/EACCES distinction, say) is not forced into a second
+ * `readdirSync`.
+ * @param {string} dir
+ * @param {import("node:fs").Dirent[]} entries
+ * @param {boolean} isRoot
+ * @returns {string[]} absolute paths of every `SKILL.md` (or, at the root,
+ *   loose `.md`) file pi's own resolver would treat as a skill entry point.
+ */
+export function scanEntriesForSkills(dir, entries, isRoot) {
+	for (const entry of entries) {
+		if (
+			entry.name === "SKILL.md" &&
+			resolvedEntryKind(path.join(dir, entry.name), entry) === "file"
+		) {
+			return [path.join(dir, entry.name)];
+		}
+	}
+	const found = [];
+	for (const entry of entries) {
+		if (entry.name.startsWith(".") || entry.name === "node_modules") {
+			continue;
+		}
+		const fullPath = path.join(dir, entry.name);
+		const kind = resolvedEntryKind(fullPath, entry);
+		if (kind === "dir") {
+			found.push(...collectSkillEntryPaths(fullPath, false));
+			continue;
+		}
+		if (isRoot && kind === "file" && entry.name.endsWith(".md")) {
+			found.push(fullPath);
+		}
+	}
+	return found;
+}
+
+/**
+ * Every skill entry point under `dir`, recursively, per pi's discovery
+ * rules. Fail-closed: a `readdirSync` error at `dir` (absent, unreadable) or
+ * any recursed-into subdirectory returns `[]` for that branch rather than
+ * throwing — matching `loadSkillsFromDirInternal`'s own bare `try { … }
+ * catch {}` per directory.
+ * @param {string} dir
+ * @param {boolean} [isRoot]
+ * @returns {string[]}
+ */
+export function collectSkillEntryPaths(dir, isRoot = true) {
+	let entries;
+	try {
+		entries = fs.readdirSync(dir, { withFileTypes: true });
+	} catch {
+		return [];
+	}
+	return scanEntriesForSkills(dir, entries, isRoot);
+}

package/node_modules/pi-lens/scripts/rpc-load-check.mjs

@@ -61,7 +61,9 @@ function handle(line) {
 	if (m.type === "response" && m.command === "get_commands") {
 		const cmds = (m.data && m.data.commands) || [];
 		const lens = cmds.filter(
-			(c) => /^lens-/.test(c.name) || String(c.path || "").includes("pi-lens"),
+			(c) =>
+				String(c.name || "").startsWith("lens-") ||
+				String(c.path || "").includes("pi-lens"),
 		);
 		console.log(
 			`total commands: ${cmds.length}; pi-lens commands: ${lens.map((c) => c.name).join(", ") || "(none)"}`,

package/node_modules/pi-mcp-adapter/CHANGELOG.md

@@ -7,6 +7,33 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.32.1] - 2026-09-01
+
+### Fixed
+- The published package now includes the updated public helper build artifacts for the `2.32.0` config and MCP Apps changes.
+
+## [2.32.0] - 2026-09-01
+
+### Highlights
+- You can now enable and disable MCP servers directly from the `/mcp` panel.
+- `/mcp setup` is clearer about where new shared servers will be saved.
+- MCP App views that use browser storage now render reliably without exposing host session access.
+- Long-running sessions handle MCP 2026 input flows, catalog updates, and UI resource refreshes more reliably.
+- OAuth reuse and per-server status messages are less confusing.
+
+### Added
+- The `/mcp` panel now supports enabling and disabling servers in place with `ctrl+d` on a server row. Saving persists the `disabled` flag to the project Pi layer and reloads the session, matching `/mcp disable` and `/mcp enable`. Thanks to [@ericykim](https://github.com/ericykim) for PR #479.
+
+### Changed
+- `/mcp setup` now lets you choose project `.mcp.json` or global `~/.config/mcp/mcp.json` as the write target for new shared MCP servers, while keeping Pi-owned files and compatibility inputs in the advanced flow. The bundled `mcp-scripting` skill is manual-only by default. Thanks to [@w-winter](https://github.com/w-winter) for #477.
+
+### Fixed
+- MCP 2026 multi-round input flows now work more reliably across proxy, direct, resource, and UI-resource calls, with clearer no-UI errors and cancellation cleanup.
+- MCP 2026-07-28 catalog listens now recover from dropped listens, refresh quietly when catalogs change, and notify open UIs when resources update. (#468)
+- MCP App views now load through a separate loopback sandbox proxy origin so storage APIs work without exposing host session capabilities. Thanks to [@drewbitt](https://github.com/drewbitt) for #480.
+- Implicit OAuth now reuses URL-bound stored credentials while preserving anonymous fallback. Thanks to [@wilt00](https://github.com/wilt00) for #471.
+- Per-server proxy lists now distinguish cached lazy tools from servers that need authentication while preserving active failure backoff. Thanks to [@inattendu](https://github.com/inattendu) for PR #474.
+
 ## [2.31.0] - 2026-08-28
 
 ### Highlights

package/node_modules/pi-mcp-adapter/README.md

@@ -32,9 +32,9 @@ The adapter reads standard MCP files automatically. No extra setup needed if you
 
 | You already have... | What happens |
 |---------------------|--------------|
-| `.mcp.json` or `~/.config/mcp/mcp.json` | Pi uses it immediately. The first time you open `/mcp`, you'll see a short heads-up explaining which file Pi detected and that Pi only writes adapter-specific overrides to its own files. |
+| `.mcp.json` or `~/.config/mcp/mcp.json` | Pi uses it immediately. Use `.mcp.json` for project/team sharing and `~/.config/mcp/mcp.json` for all projects. The first time you open `/mcp`, you'll see a short heads-up explaining which file Pi detected and that Pi only writes adapter-specific overrides to its own files. |
 | Host-specific configs (Cursor, Claude Code, Codex, etc.) but no standard MCP files | Run `/mcp setup` to adopt those host configs into Pi. The setup flow shows exactly what it found, lets you pick which ones to import, and previews the exact file changes before writing. |
-| Nothing configured yet | Run `/mcp setup` to scaffold a minimal `.mcp.json`, add a curated known server, quick-add RepoPrompt, or inspect what the adapter discovered on your machine. |
+| Nothing configured yet | Run `/mcp setup`, choose project `.mcp.json` or global `~/.config/mcp/mcp.json`, then scaffold a minimal config, add a curated known server, quick-add RepoPrompt, or inspect what the adapter discovered on your machine. |
 
 If you prefer the terminal, you can also run `pi-mcp-adapter init` after install to scan for host-specific configs and add missing compatibility imports to the Pi agent dir (`~/.pi/agent/mcp.json` by default, or `$PI_CODING_AGENT_DIR/mcp.json` when set).
 
@@ -53,16 +53,16 @@ Preferred project config: `.mcp.json`
 }
 ```
 
-Preferred user-global shared config: `~/.config/mcp/mcp.json`. Pi also reads the tool-agnostic global paths `~/.agents/mcp.json` and `~/.agents/mcp/mcp.json`.
+Preferred user-global shared config: `~/.config/mcp/mcp.json` (for all projects). Pi also reads the tool-agnostic global paths `~/.agents/mcp.json` and `~/.agents/mcp/mcp.json` as compatibility inputs.
 
-Pi also reads Pi-owned override files for settings and host-specific compatibility:
+Pi-owned files are not additional normal setup choices. They hold Pi-specific settings, compatibility imports, and adapter-only overrides:
 
 - `<Pi agent dir>/mcp.json` — Pi global override (`~/.pi/agent/mcp.json` by default)
 - `.pi/mcp.json` — Pi project override
 
-Host-specific configs are detected and shown by `/mcp setup` and `pi-mcp-adapter init`, but they are not loaded automatically. The normal `/mcp` panel does not scan host-specific files when `settings.hostConfigDiscovery` is `"off"`. To explicitly opt in to host-config fallback discovery, set `settings.hostConfigDiscovery` to `"on"` or run `pi-mcp-adapter init --discover-host-configs`. The default is `"off"`; `"prompt"` is available for integrations that want detection without activation. Host configs are lower precedence than every shared and Pi-owned source, and `/mcp setup` continues to offer explicit import adoption. Discovery reports source paths, provenance, and same-name conflicts; it never writes to external host files or silently launches commands from them.
+Host-specific configs are detected and shown by `/mcp setup` and `pi-mcp-adapter init`, but they are compatibility inputs rather than normal setup paths and are not loaded automatically. The normal `/mcp` panel does not scan host-specific files when `settings.hostConfigDiscovery` is `"off"`. To explicitly opt in to host-config fallback discovery, set `settings.hostConfigDiscovery` to `"on"` or run `pi-mcp-adapter init --discover-host-configs`. The default is `"off"`; `"prompt"` is available for integrations that want detection without activation. Host configs are lower precedence than every shared and Pi-owned source, and `/mcp setup` continues to offer explicit import adoption. Discovery reports source paths, provenance, and same-name conflicts; it never writes to external host files or silently launches commands from them.
 
-Precedence is:
+Precedence is (later entries win):
 
 1. `~/.config/mcp/mcp.json`
 2. `~/.agents/mcp.json`
@@ -302,7 +302,7 @@ Use `"auto"` to probe for MCP 2026-07-28 and conservatively fall back to the cla
 
 Use `"2026-07-28"` to pin that revision. Pinning has no legacy or SSE fallback and fails if the server does not offer the requested version.
 
-The stable SDK handles era-specific request envelopes, result decoding, list-changed subscriptions, cancellation, and multi-round-trip sampling/elicitation. The adapter keeps strict OAuth issuer validation in every mode. Adapter-level roots support, standard MCP logging presentation, and configuration/UI for protocol cache hints are not yet implemented.
+The stable SDK handles era-specific request envelopes, result decoding, list-changed subscriptions, cancellation, and multi-round-trip sampling/elicitation. The SDK's embedded-input progress callback does not expose the originating tool or resource identity, so the adapter cannot maintain a durable per-tool waiting status row; interactive sessions keep the existing input dialog visible, and proxy calls show request progress when UI is available. The adapter keeps strict OAuth issuer validation in every mode. Adapter-level roots support, standard MCP logging presentation, and configuration/UI for protocol cache hints are not yet implemented.
 
 For pre-registered browser OAuth clients, set `oauth.redirectUri` to the exact callback registered with the provider, for example `"http://localhost:3118/callback"`. Dynamic clients normally omit it and use a lazy OS-assigned localhost callback port. A configured `https://` callback runs in manual mode because the adapter cannot receive a callback on another host. After authorization, copy the full callback URL from the browser address bar and paste it into `/mcp-auth` or `mcp({ action: "auth-complete", ... })`.
 
@@ -412,7 +412,7 @@ When any enabled server uses `eager` or `keep-alive`, initialization also starts
 | `strictDirectToolArguments` | Validate direct-tool inputs against their advertised schemas and recover one JSON string layer for object and array properties (default: false). |
 | `directToolResultDetails` | Direct-tool result details: `"lean"` (default) or `"bounded"` to retain the guarded raw MCP result. |
 | `warnOnLargeDirectTools` | Show the advisory when 75 or more direct tools resolve (default: `true`). Set to `false` to suppress only this advisory. |
-| `freezeDirectTools` | Keep direct-tool registration stable after the initial sync so automatic reconnects and list-change notifications do not rebuild the system prompt. Use `mcp({ connect: "server" })` or `/mcp reconnect <server>` to refresh deliberately. Default: false. |
+| `freezeDirectTools` | Keep direct-tool registration stable after the initial sync so metadata updates and explicit reconnects do not rebuild the system prompt. Proxy/search/cache metadata still refreshes. Default: false. |
 | `scriptMode` | Register the MCP-only `mcpScript` plain-JavaScript tool (default: true). Set to `false` to hide it. |
 | `disableProxyTool` | Hide the `mcp` proxy tool once configured direct tools are fully available from cache. |
 | `autoAuth` | Auto-run OAuth on `connect`/tool calls when a server needs auth, then retry once (default: false). |
@@ -484,7 +484,7 @@ Set `"outputGuard": false` — or the env kill switch `MCP_OUTPUT_GUARD=0` — t
 
 For multi-call MCP work, write ordinary JavaScript: discover, inspect, call, loop, filter, chain, or fan out, then return one result. Run that code with the default-on `mcpScript` tool. For a single MCP call, search, describe, status check, or auth action, use `mcp` instead. Set `settings.scriptMode` to `false` to hide the scripting tool.
 
-The bundled `mcp-scripting` skill is a separate Pi package resource. To hide that skill while keeping the adapter extension installed, replace the package entry in Pi settings with the object form and disable package skills:
+The bundled `mcp-scripting` skill is a separate Pi package resource and is manual-only by default, so its description is not added to the model's automatic skill context. Use `/skill:mcp-scripting` when you want its detailed workflow. To remove the manual skill command as well while keeping the adapter extension and `mcpScript` tool installed, replace the package entry in Pi settings with the object form and disable package skills:
 
 ```json
 {
@@ -624,13 +624,13 @@ Models sometimes encode an object or array argument as a JSON string. Set `setti
 
 Set `settings.directToolResultDetails` to `"bounded"` when an extension needs structured MCP result fields in Pi's direct-tool result details. The same output guard limits apply. Small leading structured fields stay available, while large fields receive bounded summaries and the complete guarded result follows the output guard's spill-file policy. The default `"lean"` mode keeps the existing server and tool metadata only.
 
-If prompt-cache stability matters more than automatic direct-tool hot-loading, set `settings.freezeDirectTools` to `true`. The initial direct-tool sync still runs, but later automatic reconnects, lazy-connects, and list-change notifications keep the registered tool surface unchanged. Deliberate refreshes through `mcp({ connect: "server" })` or `/mcp reconnect <server>` still update direct tools.
+If prompt-cache stability matters more than direct-tool hot-loading, set `settings.freezeDirectTools` to `true`. The initial direct-tool sync still runs, but later metadata updates and explicit reconnects keep the registered tool surface unchanged while proxy/search/cache metadata refreshes normally.
 
 When you change direct-tool toggles in `/mcp`, the extension updates direct tool registration in the current session. Broader setup writes from `/mcp setup` still use Pi's normal reload flow because they can add or restructure MCP config files.
 
-**Interactive configuration:** Run `/mcp` to open an interactive panel showing all servers with connection status, tools, and direct/proxy toggles. You can reconnect servers and toggle tools between direct and proxy from the same overlay. For OAuth, press Enter on a server that needs auth or `ctrl+a` on any OAuth server. The Save action defaults to `ctrl+s` and can be remapped with the `mcp.panel.save` keybinding.
+**Interactive configuration:** Run `/mcp` to open an interactive panel showing all servers with connection status, tools, and direct/proxy toggles. You can reconnect servers, toggle tools between direct and proxy, and enable or disable servers (`ctrl+d`) from the same overlay. For OAuth, press Enter on a server that needs auth or `ctrl+a` on any OAuth server. The Save action defaults to `ctrl+s` and can be remapped with the `mcp.panel.save` keybinding.
 
-**Guided first-run setup:** Run `/mcp setup` to inspect detected shared MCP files, adopt compatibility imports from other hosts, open discovered config paths, preview exact before/after file diffs for writes, scaffold a minimal project `.mcp.json`, add a curated known server (DeepWiki, Context7, Notion, GitHub, or Chrome DevTools), or quick-add RepoPrompt into a standard/shared MCP file.
+**Guided first-run setup:** Run `/mcp setup` to choose the normal write target for new shared servers — project `.mcp.json` or global `~/.config/mcp/mcp.json` — inspect detected shared MCP files, adopt compatibility imports from other hosts, open discovered config paths, preview exact before/after file diffs for writes, scaffold a minimal selected config, add a curated known server (DeepWiki, Context7, Notion, GitHub, or Chrome DevTools), or quick-add RepoPrompt into a standard/shared MCP file.
 
 **Subagent integration:** If you use the subagent extension, agents can request direct MCP tools in their frontmatter with `mcp:server-name` syntax. See the subagent README for details.
 
@@ -712,7 +712,7 @@ Supported compatibility imports: `cursor`, `claude-code`, `claude-desktop`, `ope
 
 ### Project Config
 
-Prefer `.mcp.json` for project-local shared MCP config. Use `.pi/mcp.json` only when you need a Pi-specific project override. Project files override both user-global shared MCP config and Pi global overrides.
+Prefer `.mcp.json` for project-local shared MCP config and `~/.config/mcp/mcp.json` for user-global shared MCP config. Use `.pi/mcp.json` only when you need a Pi-specific project override. Project files override both user-global shared MCP config and Pi global overrides.
 
 ## Usage