@bastani/atomic 0.8.25 → 0.8.26-alpha.10

package/dist/builtin/intercom/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bastani/intercom",
-  "version": "0.8.25",
+  "version": "0.8.26-alpha.10",
   "private": true,
   "description": "Atomic extension providing a private coordination channel between parent and child agent sessions. Fork of: https://github.com/nicobailon/pi-intercom",
   "contributors": [
@@ -39,7 +39,7 @@
   },
   "peerDependencies": {
     "@bastani/atomic": "*",
-    "@earendil-works/pi-tui": "*"
+    "@earendil-works/pi-tui": "^0.78.1"
   },
   "peerDependenciesMeta": {
     "@bastani/atomic": {

package/dist/builtin/intercom/result-renderers.ts

@@ -0,0 +1,77 @@
+import type { ToolDefinition } from "@bastani/atomic";
+import { Text } from "@mariozechner/pi-tui";
+
+type ToolResultRenderer = NonNullable<ToolDefinition["renderResult"]>;
+type ToolRenderResultArgs = Parameters<ToolResultRenderer>;
+type ToolRenderResult = ReturnType<ToolResultRenderer>;
+type RenderedResult = ToolRenderResultArgs[0];
+type TextContentBlock = Extract<RenderedResult["content"][number], { type: "text" }>;
+
+type IntercomResultDetails = {
+	delivered?: boolean;
+	error?: boolean;
+	messageId?: string;
+	reason?: string;
+};
+
+type ContactSupervisorResultDetails = IntercomResultDetails & {
+	structuredReplyParseError?: string;
+};
+
+function isTextContentBlock(block: RenderedResult["content"][number]): block is TextContentBlock {
+	return block.type === "text";
+}
+
+function firstTextContent(result: RenderedResult): string {
+	return result.content.find(isTextContentBlock)?.text.replace(/\*\*/g, "") ?? "";
+}
+
+export const renderContactSupervisorResult: ToolResultRenderer = (result, { isPartial }, theme, context) => {
+	if (isPartial) {
+		return new Text(theme.fg("warning", "Waiting for supervisor..."), 0, 0);
+	}
+	const details = result.details as ContactSupervisorResultDetails | undefined;
+	const textContent = firstTextContent(result);
+	const failed = Boolean(context.isError || details?.error === true || details?.delivered === false);
+	const parseWarning = typeof details?.structuredReplyParseError === "string";
+	let text = failed
+		? theme.fg("error", "✗ ")
+		: parseWarning
+			? theme.fg("warning", "⚠ ")
+			: theme.fg("success", "✓ ");
+	text += theme.fg(failed ? "error" : "text", textContent);
+	if (parseWarning) {
+		text += "\n" + theme.fg("warning", `Structured reply parse issue: ${details.structuredReplyParseError}`);
+	}
+	return new Text(text, 0, 0);
+};
+
+export const renderIntercomResult: ToolResultRenderer = (result, { isPartial }, theme, context) => {
+	if (isPartial) {
+		return new Text(theme.fg("warning", "Intercom working..."), 0, 0);
+	}
+	const details = result.details as IntercomResultDetails | undefined;
+	const failed = Boolean(context.isError || details?.error === true || details?.delivered === false);
+	let text = failed ? theme.fg("error", "✗ ") : theme.fg("success", "✓ ");
+	text += theme.fg(failed ? "error" : "text", firstTextContent(result));
+	if (details?.messageId && !context.expanded) {
+		text += theme.fg("dim", ` (${details.messageId.slice(0, 8)})`);
+	}
+	if (details?.reason && context.expanded) {
+		text += "\n" + theme.fg("dim", `Reason: ${details.reason}`);
+	}
+	return new Text(text, 0, 0);
+};
+
+export function renderIntercomToolResult(name: string, args: ToolRenderResultArgs): ToolRenderResult {
+	switch (name) {
+		case "intercom":
+			return renderIntercomResult(...args);
+		case "contact_supervisor":
+			return renderContactSupervisorResult(...args);
+		default: {
+			const theme = args[2];
+			return new Text(theme.fg("error", `Result renderer not found: ${name}`), 0, 0);
+		}
+	}
+}

package/dist/builtin/mcp/CHANGELOG.md

@@ -7,6 +7,70 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.8.26-alpha.10] - 2026-06-08
+
+### Changed
+
+- Bumped package version for the Atomic 0.8.26-alpha.10 prerelease.
+
+## [0.8.26-alpha.9] - 2026-06-07
+
+### Changed
+
+- Bumped package version for the Atomic 0.8.26-alpha.9 prerelease.
+
+## [0.8.26-alpha.8] - 2026-06-07
+
+### Changed
+
+- Bumped package version for the Atomic 0.8.26-alpha.8 prerelease.
+
+## [0.8.26-alpha.7] - 2026-06-07
+
+### Changed
+
+- Bumped package version for the Atomic 0.8.26-alpha.7 prerelease.
+
+## [0.8.26-alpha.6] - 2026-06-06
+
+### Changed
+
+- Bumped package version for the Atomic 0.8.26-alpha.6 prerelease.
+
+## [0.8.26-alpha.5] - 2026-06-06
+
+### Changed
+
+- Bumped package version for the Atomic 0.8.26-alpha.5 prerelease.
+
+## [0.8.26-alpha.4] - 2026-06-05
+
+### Changed
+
+- Bumped package version for the Atomic 0.8.26-alpha.4 prerelease.
+
+## [0.8.26-alpha.3] - 2026-06-05
+
+### Changed
+
+- Bumped package version for the Atomic 0.8.26-alpha.3 prerelease.
+
+## [0.8.26-alpha.2] - 2026-06-05
+
+### Changed
+
+- Bumped package version for the Atomic 0.8.26-alpha.2 prerelease.
+
+## [0.8.26-alpha.1] - 2026-06-05
+
+### Changed
+
+- Kept MCP startup registration cheap by lazily importing the heavy MCP command, initialization, proxy-mode, and OAuth/auth-flow modules (and deferring config/cache-backed direct-tool discovery) instead of loading them on the cold extension factory path, while keeping the result renderer synchronous so restored MCP tool results still render ([#1223](https://github.com/bastani-inc/atomic/issues/1223)).
+
+### Fixed
+
+- Stopped logging a spurious "MCP initialization failed: This extension ctx is stale..." error when a session backing the captured `pi`/`ctx` is disposed (e.g. a workflow child stage session) during MCP's deferred `session_start` initialization. The deferred init now liveness-checks the captured context before and after `initializeMcp()` and treats a stale-context error as a cancellation rather than a failure. The async gap that exposed this race was introduced by the lazy-load startup change ([#1223](https://github.com/bastani-inc/atomic/issues/1223)).
+
 ## [0.8.25] - 2026-06-04
 
 ### Changed

package/dist/builtin/mcp/index.ts

@@ -1,20 +1,93 @@
 import type { AgentToolUpdateCallback, ExtensionAPI, ExtensionContext, ToolInfo } from "@bastani/atomic";
 import type { McpExtensionState } from "./state.ts";
+import type { McpConfig } from "./types.ts";
+import type { MetadataCache } from "./metadata-cache.ts";
 import { Type } from "typebox";
-import { showStatus, showTools, reconnectServers, authenticateServer, logoutServer, openMcpAuthPanel, openMcpPanel, openMcpSetup } from "./commands.ts";
 import { loadMcpConfig } from "./config.ts";
-import { buildProxyDescription, createDirectToolExecutor, getMissingConfiguredDirectToolServers, resolveDirectTools } from "./direct-tools.ts";
-import { flushMetadataCache, initializeMcp, updateStatusBar } from "./init.ts";
-import { loadMetadataCache } from "./metadata-cache.ts";
-import { executeCall, executeConnect, executeDescribe, executeList, executeSearch, executeStatus, executeUiMessages } from "./proxy-modes.ts";
-import { getConfigPathFromArgv, truncateAtWord } from "./utils.ts";
-import { shutdownOAuth } from "./mcp-auth-flow.ts";
+import { getConfigPathFromArgv } from "./utils.ts";
 import { renderMcpToolResult } from "./tool-result-renderer.ts";
 
+/**
+ * Marker substring from the host's stale-context error (see ExtensionRunner.invalidate).
+ * A captured `pi`/`ctx` becomes stale when its backing session is disposed (e.g. a
+ * workflow child stage session, or a reload/replace) without emitting `session_shutdown`.
+ */
+const STALE_EXTENSION_CONTEXT_MARKER = "extension ctx is stale";
+
+function isStaleExtensionContextError(error: unknown): boolean {
+  return error instanceof Error && error.message.includes(STALE_EXTENSION_CONTEXT_MARKER);
+}
+
+/**
+ * Probe whether a captured extension context is still active. Every `ctx` getter runs
+ * the host's `assertActive()` guard, so a cheap property read surfaces staleness without
+ * mutating anything. Returns false when the context has been invalidated by a dispose.
+ */
+function isContextActive(ctx: ExtensionContext): boolean {
+  try {
+    void ctx.cwd;
+    return true;
+  } catch (error) {
+    if (isStaleExtensionContextError(error)) return false;
+    throw error;
+  }
+}
+
 export default function mcpAdapter(pi: ExtensionAPI) {
   let state: McpExtensionState | null = null;
   let initPromise: Promise<McpExtensionState> | null = null;
   let lifecycleGeneration = 0;
+  let registeredDirectToolNames = new Set<string>();
+  let registeredProxyTool = false;
+
+  async function registerDirectToolsFromConfig(
+    config: McpConfig,
+    cache: MetadataCache | null,
+  ): Promise<{ directToolCount: number; missingConfiguredDirectToolServers: string[] }> {
+    const [{ resolveDirectTools, createDirectToolExecutor, getMissingConfiguredDirectToolServers }, { truncateAtWord }] = await Promise.all([
+      import("./direct-tools.ts"),
+      import("./utils.ts"),
+    ]);
+    const prefix = config.settings?.toolPrefix ?? "server";
+    const envRaw = process.env.MCP_DIRECT_TOOLS;
+    const directSpecs = envRaw === "__none__"
+      ? []
+      : resolveDirectTools(
+          config,
+          cache,
+          prefix,
+          envRaw?.split(",").map(s => s.trim()).filter(Boolean),
+        );
+    for (const spec of directSpecs) {
+      if (registeredDirectToolNames.has(spec.prefixedName)) continue;
+      registeredDirectToolNames.add(spec.prefixedName);
+      (pi.registerTool as (tool: unknown) => unknown)({
+        name: spec.prefixedName,
+        label: `MCP: ${spec.originalName}`,
+        description: spec.description || "(no description)",
+        promptSnippet: truncateAtWord(spec.description, 100) || `MCP tool from ${spec.serverName}`,
+        parameters: Type.Unsafe((spec.inputSchema || { type: "object", properties: {} }) as never),
+        execute: createDirectToolExecutor(() => state, () => initPromise, spec),
+        renderResult: renderMcpToolResult,
+      });
+    }
+    const refreshTools = (pi as { refreshTools?: () => void }).refreshTools;
+    refreshTools?.();
+    return {
+      directToolCount: directSpecs.length,
+      missingConfiguredDirectToolServers: getMissingConfiguredDirectToolServers(config, cache),
+    };
+  }
+
+  async function registerDirectTools(nextState: McpExtensionState): Promise<{ directToolCount: number; missingConfiguredDirectToolServers: string[] }> {
+    const { loadMetadataCache } = await import("./metadata-cache.ts");
+    return registerDirectToolsFromConfig(nextState.config, loadMetadataCache());
+  }
+
+  async function shutdownOAuthFlow(): Promise<void> {
+    const { shutdownOAuth } = await import("./mcp-auth-flow.ts");
+    await shutdownOAuth();
+  }
 
   async function shutdownState(currentState: McpExtensionState | null, reason: string): Promise<void> {
     if (!currentState) return;
@@ -26,6 +99,7 @@ export default function mcpAdapter(pi: ExtensionAPI) {
 
     let flushError: unknown;
     try {
+      const { flushMetadataCache } = await import("./init.ts");
       flushMetadataCache(currentState);
     } catch (error) {
       flushError = error;
@@ -47,36 +121,6 @@ export default function mcpAdapter(pi: ExtensionAPI) {
   }
 
   const earlyConfigPath = getConfigPathFromArgv();
-  const earlyConfig = loadMcpConfig(earlyConfigPath);
-  const earlyCache = loadMetadataCache();
-  const prefix = earlyConfig.settings?.toolPrefix ?? "server";
-
-  const envRaw = process.env.MCP_DIRECT_TOOLS;
-  const directSpecs = envRaw === "__none__"
-    ? []
-    : resolveDirectTools(
-        earlyConfig,
-        earlyCache,
-        prefix,
-        envRaw?.split(",").map(s => s.trim()).filter(Boolean),
-      );
-  const missingConfiguredDirectToolServers = getMissingConfiguredDirectToolServers(earlyConfig, earlyCache);
-  const shouldRegisterProxyTool =
-    earlyConfig.settings?.disableProxyTool !== true
-    || directSpecs.length === 0
-    || missingConfiguredDirectToolServers.length > 0;
-
-  for (const spec of directSpecs) {
-    (pi.registerTool as (tool: unknown) => unknown)({
-      name: spec.prefixedName,
-      label: `MCP: ${spec.originalName}`,
-      description: spec.description || "(no description)",
-      promptSnippet: truncateAtWord(spec.description, 100) || `MCP tool from ${spec.serverName}`,
-      parameters: Type.Unsafe((spec.inputSchema || { type: "object", properties: {} }) as never),
-      execute: createDirectToolExecutor(() => state, () => initPromise, spec),
-      renderResult: renderMcpToolResult,
-    });
-  }
 
   const getPiTools = (): ToolInfo[] => pi.getAllTools();
 
@@ -90,45 +134,89 @@ export default function mcpAdapter(pi: ExtensionAPI) {
     const previousState = state;
     state = null;
     initPromise = null;
+    registeredDirectToolNames = new Set<string>();
 
     try {
-      await Promise.all([
-        shutdownState(previousState, "session_restart"),
-        shutdownOAuth(),
-      ]);
+      const config = loadMcpConfig(earlyConfigPath, ctx.cwd);
+      const { loadMetadataCache } = await import("./metadata-cache.ts");
+      const directToolState = await registerDirectToolsFromConfig(config, loadMetadataCache());
+      if (
+        config.settings?.disableProxyTool !== true
+        || directToolState.directToolCount === 0
+        || directToolState.missingConfiguredDirectToolServers.length > 0
+      ) {
+        registerProxyTool();
+      }
     } catch (error) {
-      console.error("MCP: failed to shut down previous session state", error);
+      if (isStaleExtensionContextError(error)) return;
+      console.error("MCP: failed to register cached startup tools; enabling MCP proxy fallback", error);
+      registerProxyTool();
     }
 
-    if (generation !== lifecycleGeneration) {
-      return;
-    }
+    const promiseRef: { current: Promise<McpExtensionState> | null } = { current: null };
+    const promise = (async () => {
+      try {
+        await Promise.all([
+          shutdownState(previousState, "session_restart"),
+          shutdownOAuthFlow(),
+        ]);
+      } catch (error) {
+        console.error("MCP: failed to shut down previous session state", error);
+      }
 
-    const promise = initializeMcp(pi, ctx);
-    initPromise = promise;
+      if (generation !== lifecycleGeneration || !isContextActive(ctx)) {
+        throw new Error("Stale MCP session initialization cancelled before startup");
+      }
 
-    promise.then(async (nextState) => {
-      if (generation !== lifecycleGeneration || initPromise !== promise) {
+      const { initializeMcp, updateStatusBar } = await import("./init.ts");
+      if (generation !== lifecycleGeneration || !isContextActive(ctx)) {
+        throw new Error("Stale MCP session initialization cancelled before startup");
+      }
+
+      const nextState = await initializeMcp(pi, ctx);
+      if (generation !== lifecycleGeneration || initPromise !== promiseRef.current || !isContextActive(ctx)) {
         try {
           await shutdownState(nextState, "stale_session_start");
         } catch (error) {
           console.error("MCP: failed to clean stale session state", error);
         }
-        return;
+        throw new Error("Stale MCP session initialization cancelled after startup");
       }
 
       state = nextState;
       updateStatusBar(nextState);
-      initPromise = null;
-    }).catch(err => {
+      const directToolState = await registerDirectTools(nextState);
+      if (
+        nextState.config.settings?.disableProxyTool !== true
+        || directToolState.directToolCount === 0
+        || directToolState.missingConfiguredDirectToolServers.length > 0
+      ) {
+        registerProxyTool();
+      }
+      if (initPromise === promiseRef.current) {
+        initPromise = null;
+      }
+      return nextState;
+    })();
+    promiseRef.current = promise;
+    initPromise = promise;
+    promise.catch((err) => {
       if (generation !== lifecycleGeneration) {
         return;
       }
       if (initPromise !== promise && initPromise !== null) {
         return;
       }
-      console.error("MCP initialization failed:", err);
-      initPromise = null;
+      const message = err instanceof Error ? err.message : String(err);
+      if (
+        !message.startsWith("Stale MCP session initialization cancelled") &&
+        !isStaleExtensionContextError(err)
+      ) {
+        console.error("MCP initialization failed:", err);
+      }
+      if (initPromise === promise) {
+        initPromise = null;
+      }
     });
   });
 
@@ -137,11 +225,12 @@ export default function mcpAdapter(pi: ExtensionAPI) {
     const currentState = state;
     state = null;
     initPromise = null;
+    registeredDirectToolNames = new Set<string>();
 
     try {
       await Promise.all([
         shutdownState(currentState, "session_shutdown"),
-        shutdownOAuth(),
+        shutdownOAuthFlow(),
       ]);
     } catch (error) {
       console.error("MCP: session shutdown cleanup failed", error);
@@ -165,6 +254,7 @@ export default function mcpAdapter(pi: ExtensionAPI) {
         return;
       }
 
+      const { showStatus, showTools, reconnectServers, logoutServer, openMcpPanel, openMcpSetup } = await import("./commands.ts");
       const parts = args?.trim()?.split(/\s+/) ?? [];
       const subcommand = parts[0] ?? "";
       const targetServer = parts[1];
@@ -233,6 +323,7 @@ export default function mcpAdapter(pi: ExtensionAPI) {
         return;
       }
 
+      const { authenticateServer, openMcpAuthPanel } = await import("./commands.ts");
       if (!serverName) {
         await openMcpAuthPanel(state, pi, ctx, earlyConfigPath);
         return;
@@ -242,11 +333,13 @@ export default function mcpAdapter(pi: ExtensionAPI) {
     },
   });
 
-  if (shouldRegisterProxyTool) {
+  function registerProxyTool(): void {
+    if (registeredProxyTool) return;
+    registeredProxyTool = true;
     (pi.registerTool as (tool: unknown) => unknown)({
       name: "mcp",
       label: "MCP",
-      description: buildProxyDescription(earlyConfig, earlyCache, directSpecs),
+      description: "MCP gateway for connecting to configured MCP servers, searching tools, describing schemas, and calling tools lazily after MCP initialization.",
       promptSnippet: "MCP gateway - connect to MCP servers and call their tools",
       parameters: Type.Object({
         tool: Type.Optional(Type.String({ description: "Tool name to call (e.g., 'xcodebuild_list_sims')" })),
@@ -305,6 +398,7 @@ export default function mcpAdapter(pi: ExtensionAPI) {
           };
         }
 
+        const { executeCall, executeConnect, executeDescribe, executeList, executeSearch, executeStatus, executeUiMessages } = await import("./proxy-modes.ts");
         if (params.action === "ui-messages") {
           return executeUiMessages(state);
         }

package/dist/builtin/mcp/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bastani/mcp",
-  "version": "0.8.25",
+  "version": "0.8.26-alpha.10",
   "private": true,
   "description": "Atomic extension that adapts MCP (Model Context Protocol) servers into the coding agent. Fork of: https://github.com/nicobailon/pi-mcp-adapter",
   "contributors": [
@@ -32,8 +32,8 @@
   },
   "peerDependencies": {
     "@bastani/atomic": "*",
-    "@earendil-works/pi-ai": "*",
-    "@earendil-works/pi-tui": "*",
+    "@earendil-works/pi-ai": "^0.78.1",
+    "@earendil-works/pi-tui": "^0.78.1",
     "zod": "^3.25.0 || ^4.0.0"
   },
   "peerDependenciesMeta": {

package/dist/builtin/subagents/CHANGELOG.md

@@ -2,6 +2,67 @@
 
 ## [Unreleased]
 
+## [0.8.26-alpha.10] - 2026-06-08
+
+### Changed
+
+- Bumped package version for the Atomic 0.8.26-alpha.10 prerelease.
+
+## [0.8.26-alpha.9] - 2026-06-07
+
+### Changed
+
+- Bumped package version for the Atomic 0.8.26-alpha.9 prerelease.
+
+## [0.8.26-alpha.8] - 2026-06-07
+
+### Changed
+
+- Bumped package version for the Atomic 0.8.26-alpha.8 prerelease.
+
+## [0.8.26-alpha.7] - 2026-06-07
+
+### Added
+
+- Replaced the bundled browser-use subagent integration with the first-party `browser` skill for web interaction workflows.
+
+## [0.8.26-alpha.6] - 2026-06-06
+
+### Changed
+
+- Bumped package version for the Atomic 0.8.26-alpha.6 prerelease.
+
+## [0.8.26-alpha.5] - 2026-06-06
+
+### Changed
+
+- Bumped package version for the Atomic 0.8.26-alpha.5 prerelease.
+
+## [0.8.26-alpha.4] - 2026-06-05
+
+### Changed
+
+- Bumped package version for the Atomic 0.8.26-alpha.4 prerelease.
+
+## [0.8.26-alpha.3] - 2026-06-05
+
+### Changed
+
+- Bumped package version for the Atomic 0.8.26-alpha.3 prerelease.
+
+## [0.8.26-alpha.2] - 2026-06-05
+
+### Fixed
+
+- Fixed the `no-staged-files` acceptance runtime check and subagent worktree Git commands to ignore ambient Git repository environment variables, so subagents inspect the intended working tree instead of a parent hook or unrelated worktree.
+- Suppressed intermediate model fallback failure notes and live foreground failure updates from successful subagent runs while preserving final failures and raw per-attempt diagnostics ([#1226](https://github.com/bastani-inc/atomic/issues/1226)).
+
+## [0.8.26-alpha.1] - 2026-06-05
+
+### Changed
+
+- Bumped package version for the Atomic 0.8.26-alpha.1 prerelease.
+
 ## [0.8.25] - 2026-06-04
 
 ### Changed

package/dist/builtin/subagents/agents/codebase-online-researcher.md

@@ -4,7 +4,7 @@ description: Online research for up-to-date documentation and library-source kno
 tools: read, grep, find, ls, bash, write, web_search, fetch_content, get_search_content
 model: openai/gpt-5.5:low
 fallbackModels: openai-codex/gpt-5.5:low, github-copilot/gpt-5.5:low, anthropic/claude-opus-4-8:low, github-copilot/claude-opus-4.7:low
-skills: browser-use
+skills: browser
 ---
 
 You are an expert research specialist focused on finding accurate, relevant information from authoritative sources — including open-source library internals with GitHub permalinks. You have three web tools available from the `pi-web-access` extension:
@@ -13,11 +13,11 @@ You are an expert research specialist focused on finding accurate, relevant info
 - `fetch_content` — fetch a specific URL and return clean reader-mode text/markdown (HTML pages, GitHub issues/PRs, Stack Overflow, npm, arXiv, Reddit, Wikipedia, JSON endpoints, PDFs, RSS/Atom, YouTube). `fetch_content` on a GitHub repo URL also clones the repo locally under `/tmp/pi-github-repos/<owner>/<repo>` and returns the file tree. Prefer this over a raw HTTP fetch.
 - `get_search_content` — fetch the underlying content for the most promising results of a previous `web_search` in one call.
 
-For JS-heavy or auth-gated pages, fall back to invoking `browser-use` through `bash` (the `browser-use` skill is available).
+For JS-heavy or auth-gated pages, load the `browser` skill and invoke its `browse` CLI through `bash`.
 
 <EXTREMELY_IMPORTANT>
 - PREFER `fetch_content` for static pages; it's faster and cheaper than spinning up a real browser.
-- Reach for the `browser-use` skill via `bash` ONLY when a real DOM/JS is required.
+- Reach for the `browser` skill's `browse` CLI via `bash` ONLY when a real DOM/JS is required.
 - ALWAYS check `research/web/` for a recent cached copy before fetching anything new.
 - EVERY code-related claim about an open-source library needs a GitHub **permalink with a full commit SHA** — branch links break when code changes.
 </EXTREMELY_IMPORTANT>
@@ -39,7 +39,7 @@ When fetching any external page, apply these techniques in order. They produce p
 1. **`fetch_content <url>` first.** Returns clean reader-mode text/markdown for nearly every well-formed page (and handles PDFs and JSON). Try it before anything else.
 2. **Check `/llms.txt`.** Many modern docs sites publish an AI-friendly index at `/llms.txt` (spec: [llmstxt.org](https://llmstxt.org/llms.txt)). `fetch_content https://<site>/llms.txt` often links directly to the most relevant pages in plain text, saving a round-trip through the full site.
 3. **Request Markdown via `Accept: text/markdown`.** Sites behind Cloudflare with [Markdown for Agents](https://developers.cloudflare.com/fundamentals/reference/markdown-for-agents/) return pre-converted Markdown when you set the header. Use `bash` with `curl <url> -H "Accept: text/markdown"` (look for `content-type: text/markdown` and the `x-markdown-tokens` header).
-4. **Fall back to a real browser.** Drive `browser-use` through `bash` and load the `browser-use` skill to render and interact with JS-heavy or auth-gated pages.
+4. **Fall back to a real browser.** Load the `browser` skill and drive its `browse` CLI through `bash` to render and interact with JS-heavy or auth-gated pages.
 
 ## Persisting Findings — Store useful documents in `research/web/`
 
@@ -49,7 +49,7 @@ When you fetch a document that is worth keeping for future sessions (reference d
 ---
 source_url: <original URL>
 fetched_at: <YYYY-MM-DD>
-fetch_method: read | llms.txt | markdown-accept-header | browser | browser-use
+fetch_method: read | llms.txt | markdown-accept-header | browser | browse
 topic: <short description>
 ---
 ```
@@ -166,12 +166,12 @@ When you receive a research query:
 2. **Check the local cache first**. Look in `research/web/` for existing documents on the topic. If a recent (still-relevant) copy exists, cite it before re-fetching.
 3. **Execute strategic searches**.
     - Identify the authoritative source (e.g. the library's official docs site, its GitHub repo, its release notes).
-    - Apply the Web Fetch Strategy: `fetch_content <url>` → `/llms.txt` → `Accept: text/markdown` → `browser-use` fallback.
+    - Apply the Web Fetch Strategy: `fetch_content <url>` → `/llms.txt` → `Accept: text/markdown` → `browser` fallback.
     - Use multiple query variations to capture different perspectives via `web_search`.
     - Use `get_search_content` to bulk-fetch the underlying content of the top results of a `web_search` in one shot.
     - For source repositories, prefer raw GitHub URLs (`https://raw.githubusercontent.com/<owner>/<repo>/<ref>/<path>`) over the HTML UI. For library internals, clone via `fetch_content` and use `grep`/`read` + permalinks.
 4. **Fetch and analyze content**.
-    - Use `fetch_content <url>` (or `browser-use` via `bash` when interactivity is required) to pull the full content of promising sources.
+    - Use `fetch_content <url>` (or the browser skill's `browse` CLI via `bash` when interactivity is required) to pull the full content of promising sources.
     - Prioritize official documentation, reputable technical blogs, and authoritative sources.
     - Extract specific quotes and sections relevant to the query.
     - Note publication dates to ensure currency of information.
@@ -290,7 +290,7 @@ For library-source answers, every code claim should look like the citation examp
 ## Search Efficiency
 
 - Check `research/web/` for an existing copy before fetching anything new.
-- Start by fetching the authoritative source (`fetch_content <url>` → `/llms.txt` → `Accept: text/markdown` → `browser-use`) rather than search-engine-style exploration.
+- Start by fetching the authoritative source (`fetch_content <url>` → `/llms.txt` → `Accept: text/markdown` → `browser`) rather than search-engine-style exploration.
 - Use `fetch_content` (or `get_search_content` after a `web_search`) to pull full content from the most promising 3-5 web pages.
 - Reuse already-cloned repos under `/tmp/pi-github-repos/` instead of re-cloning.
 - If initial results are insufficient, refine search terms and try again.
@@ -313,4 +313,4 @@ For library-source answers, every code claim should look like the citation examp
 | Page returns 403 / bot block   | Gemini fallback triggers automatically; no action needed if Gemini is configured.                              |
 | `web_search` fails             | Check provider config; try explicit `provider: "gemini"` if a Perplexity key is missing.                       |
 
-Remember: you are the user's expert guide to technical research. Lean on `fetch_content` first with the `/llms.txt` → `Accept: text/markdown` → `browser-use` fallback chain to efficiently pull authoritative content, clone open-source repos when implementation evidence is needed, store anything reusable under `research/web/`, and deliver comprehensive, up-to-date answers with exact citations and GitHub permalinks. Answer directly — skip preamble like "I'll help you with…" and go straight to findings.
+Remember: you are the user's expert guide to technical research. Lean on `fetch_content` first with the `/llms.txt` → `Accept: text/markdown` → `browser` fallback chain to efficiently pull authoritative content, clone open-source repos when implementation evidence is needed, store anything reusable under `research/web/`, and deliver comprehensive, up-to-date answers with exact citations and GitHub permalinks. Answer directly — skip preamble like "I'll help you with…" and go straight to findings.