@opengsd/gsd-pi 1.2.0-dev.5457a158 → 1.2.0-dev.84c56d87

package/src/resources/extensions/gsd/tests/token-tool-gating.test.ts

@@ -10,6 +10,7 @@ import { DISCUSS_TOOLS_ALLOWLIST } from "../constants.ts";
 import { buildMinimalAutoGsdToolSet, buildMinimalGsdToolSet, buildMinimalGsdWorkflowToolSet, buildRequestScopedGsdToolSet, MINIMAL_AUTO_BASE_TOOL_NAMES, MINIMAL_GSD_TOOL_NAMES, requestHasGsdCustomType, restoreGsdWorkflowTools, scopeGsdWorkflowToolsForDispatch } from "../bootstrap/register-hooks.ts";
 import { filterToolsForProvider } from "../model-router.ts";
 import { applyUnitSkillVisibility } from "../skill-scope.ts";
+import { drainLogs } from "../workflow-logger.ts";
 
 test("buildMinimalGsdToolSet preserves non-GSD tools and replaces broad GSD surface", () => {
   const result = buildMinimalGsdToolSet([
@@ -103,6 +104,40 @@ test("buildMinimalAutoGsdToolSet keeps unit-specific completion tools without al
   assert.ok(!result.includes("gsd_complete_slice"));
 });
 
+test("buildMinimalAutoGsdToolSet warns when plan-milestone required tools are unresolved", () => {
+  drainLogs();
+  const result = buildMinimalAutoGsdToolSet(
+    [
+      "ask_user_questions",
+      "bash",
+      "read",
+      "gsd_milestone_status",
+      "gsd_plan_milestone",
+    ],
+    "plan-milestone",
+    [
+      "ask_user_questions",
+      "bash",
+      "read",
+      "gsd_milestone_status",
+      "gsd_plan_milestone",
+    ],
+  );
+
+  assert.ok(result.includes("gsd_plan_milestone"));
+  assert.ok(!result.includes("gsd_plan_slice"));
+
+  const logs = drainLogs();
+  assert.ok(
+    logs.some((entry) =>
+      entry.component === "bootstrap" &&
+      entry.message.includes("buildMinimalAutoGsdToolSet(plan-milestone)") &&
+      entry.message.includes("gsd_plan_slice")
+    ),
+    `expected missing gsd_plan_slice bootstrap warning, got ${JSON.stringify(logs)}`,
+  );
+});
+
 test("buildMinimalAutoGsdToolSet scopes run-uat to UAT-specific and read-only tools", () => {
   const active = ["ask_user_questions", "bash", "read", "edit", "write", "gsd_summary_save"];
   const registered = [

package/src/resources/extensions/gsd/tests/uat-policy.test.ts

@@ -5,7 +5,6 @@ import {
   classifyUatContent,
   getDeclaredUatType,
   getUatBrowserToolSupportError,
-  hasUatBrowserToolSurface,
   isPartialEligibleUatType,
   resolveEffectiveUatType,
   shouldDispatchUatForContent,
@@ -13,6 +12,12 @@ import {
   uatTypeIncludesBrowser,
   validateUatModePolicy,
 } from "../uat-policy.ts";
+import {
+  assertBrowserAutomationContractAvailable,
+  assertBrowserAutomationContractMissing,
+  assertBrowserBackedUatCanDispatch,
+  BROWSER_AUTOMATION_CONTRACT_TOOLS,
+} from "./browser-automation-contract-fixture.ts";
 
 describe("uat-policy", () => {
   it("defaults missing UAT mode to artifact-driven", () => {
@@ -63,14 +68,14 @@ describe("uat-policy", () => {
     }
   });
 
-  it("detects direct and MCP-shaped browser tool surfaces", () => {
-    assert.equal(hasUatBrowserToolSurface(["read", "browser_navigate"]), true);
-    assert.equal(hasUatBrowserToolSurface(["read", "mcp__gsd-browser__browser_navigate"]), true);
-    assert.equal(hasUatBrowserToolSurface(["read", "mcp__gsd-browser__*"]), true);
-    assert.equal(hasUatBrowserToolSurface(["read", "mcp__browser-uat__*"]), true);
-    assert.equal(hasUatBrowserToolSurface(["read", "mcp__gsd-workflow__*"]), false);
-    assert.equal(hasUatBrowserToolSurface(["read", "gsd_uat_exec"]), false);
-    assert.equal(hasUatBrowserToolSurface(undefined), false);
+  it("detects Browser Automation Contract capability across adapters", () => {
+    assertBrowserAutomationContractAvailable(BROWSER_AUTOMATION_CONTRACT_TOOLS.piProvider);
+    assertBrowserAutomationContractAvailable(BROWSER_AUTOMATION_CONTRACT_TOOLS.externalMcpClient);
+    assertBrowserAutomationContractAvailable(BROWSER_AUTOMATION_CONTRACT_TOOLS.externalMcpWildcard);
+    assertBrowserAutomationContractAvailable(BROWSER_AUTOMATION_CONTRACT_TOOLS.otherBrowserMcp);
+    assertBrowserAutomationContractMissing(BROWSER_AUTOMATION_CONTRACT_TOOLS.workflowOnly);
+    assertBrowserAutomationContractMissing(BROWSER_AUTOMATION_CONTRACT_TOOLS.withoutBrowser);
+    assertBrowserAutomationContractMissing(undefined);
   });
 
   it("reports missing browser tools only for browser-backed UAT with a known tool snapshot", () => {
@@ -92,26 +97,16 @@ describe("uat-policy", () => {
       }),
       null,
     );
-    assert.equal(
-      getUatBrowserToolSupportError({
-        uatType: "human-experience",
-        activeTools: ["read", "gsd_uat_exec"],
-        registeredTools: ["browser_navigate"],
-        milestoneId: "M001",
-        sliceId: "S01",
-      }),
-      null,
-    );
-    assert.equal(
-      getUatBrowserToolSupportError({
-        uatType: "human-experience",
-        activeTools: ["read", "gsd_uat_exec"],
-        registeredTools: ["mcp__gsd-browser__*"],
-        milestoneId: "M001",
-        sliceId: "S01",
-      }),
-      null,
-    );
+    assertBrowserBackedUatCanDispatch({
+      uatType: "human-experience",
+      activeTools: BROWSER_AUTOMATION_CONTRACT_TOOLS.withoutBrowser,
+      registeredTools: BROWSER_AUTOMATION_CONTRACT_TOOLS.piProvider,
+    });
+    assertBrowserBackedUatCanDispatch({
+      uatType: "human-experience",
+      activeTools: BROWSER_AUTOMATION_CONTRACT_TOOLS.withoutBrowser,
+      registeredTools: BROWSER_AUTOMATION_CONTRACT_TOOLS.externalMcpWildcard,
+    });
 
     const error = getUatBrowserToolSupportError({
       uatType: "browser-executable",

package/src/resources/extensions/gsd/tests/web-app-uat.test.ts

@@ -15,6 +15,10 @@ function scaffoldProject(root: string, pkg: Record<string, unknown>): void {
   writeFileSync(join(root, "package.json"), JSON.stringify(pkg, null, 2));
 }
 
+const LEGACY_ENGINE = { engine: "legacy", source: "probe", reason: "test" } as const;
+const MANAGED_ENGINE = { engine: "gsd-browser", source: "probe", reason: "test" } as const;
+const OFF_ENGINE = { engine: "off", source: "env", reason: "test" } as const;
+
 describe("web-app-uat guidance", () => {
   test("returns null for non-web projects", () => {
     const root = mkdtempSync(join(tmpdir(), "gsd-web-uat-"));
@@ -36,15 +40,54 @@ describe("web-app-uat guidance", () => {
         scripts: { dev: "vite" },
       });
       assert.equal(detectWebApp(root), true);
-      const block = buildWebAppUatGuidanceBlock(root);
+      const block = buildWebAppUatGuidanceBlock(root, LEGACY_ENGINE);
       assert.ok(block);
       assert.match(block!, /browser-executable/);
+      assert.match(block!, /Playwright-backed `browser_\*` tools/);
       assert.match(block!, /Playwright scaffolding/);
     } finally {
       rmSync(root, { recursive: true, force: true });
     }
   });
 
+  test("describes the managed gsd-browser engine when it is the resolved backing", () => {
+    const root = mkdtempSync(join(tmpdir(), "gsd-web-uat-"));
+    try {
+      scaffoldProject(root, {
+        dependencies: { react: "19.0.0" },
+        scripts: { dev: "vite" },
+      });
+      const block = buildWebAppUatGuidanceBlock(root, MANAGED_ENGINE);
+      assert.ok(block);
+      assert.match(block!, /managed gsd-browser engine/);
+      assert.match(block!, /browser-executable/);
+      assert.doesNotMatch(block!, /Playwright-backed/);
+    } finally {
+      rmSync(root, { recursive: true, force: true });
+    }
+  });
+
+  test("steers to runtime-executable UAT when browser tools are off", () => {
+    const root = mkdtempSync(join(tmpdir(), "gsd-web-uat-"));
+    try {
+      scaffoldProject(root, {
+        dependencies: { react: "19.0.0" },
+        scripts: { dev: "vite" },
+      });
+      const block = buildWebAppUatGuidanceBlock(root, OFF_ENGINE);
+      assert.ok(block);
+      assert.match(block!, /browser tools are disabled/);
+      assert.doesNotMatch(block!, /- `browser-executable`/);
+      // mixed/live-runtime require browser tools per UAT_MODE_POLICIES, so the
+      // bullet must drop out too — recommending them would dead-end at dispatch.
+      assert.doesNotMatch(block!, /- `mixed`/);
+      assert.doesNotMatch(block!, /interactive `browser_\*` checks/);
+      assert.match(block!, /runtime-executable/);
+    } finally {
+      rmSync(root, { recursive: true, force: true });
+    }
+  });
+
   test("detects existing Playwright and npm script", () => {
     const root = mkdtempSync(join(tmpdir(), "gsd-web-uat-"));
     try {

package/src/resources/extensions/gsd/uat-policy.ts

@@ -1,6 +1,7 @@
 // Project/App: gsd-pi
 // File Purpose: Central UAT mode policy for dispatch, tool presentation, and result validation.
 
+import { hasBrowserContractPrefix } from "../shared/browser-contract.js";
 import { extractUatType } from "./files.js";
 import type { UatType } from "./files.js";
 import { hasBrowserRequiredText } from "./browser-evidence.js";
@@ -126,7 +127,7 @@ export function uatTypeIncludesBrowser(uatType: string | undefined): boolean {
 export function isUatBrowserToolName(toolName: string): boolean {
   const parsed = parseMcpToolName(toolName);
   const canonicalName = parsed?.toolName ?? toolName;
-  if (canonicalName.startsWith("browser_")) return true;
+  if (hasBrowserContractPrefix(canonicalName)) return true;
   return parsed?.toolName === "*" && parsed.serverName.toLowerCase().includes("browser");
 }
 

package/src/resources/extensions/gsd/unit-registry.ts

@@ -24,6 +24,7 @@
 // implicit in auto-prompts.ts builders).
 
 import type { CanonicalWorkflowToolName } from "@opengsd/contracts";
+import { BROWSER_CONTRACT_TOOL_NAMES } from "../shared/browser-contract.js";
 import type { GSDModelPhaseKey } from "./preferences-types.js";
 import type { WorkflowMcpAdapterToolName } from "./workflow-tool-surface.js";
 
@@ -82,26 +83,12 @@ export const RUN_UAT_READ_ONLY_TOOL_NAMES = [
   "read",
 ] as const;
 
-export const RUN_UAT_BROWSER_TOOL_NAMES = [
-  "browser_navigate",
-  "browser_click",
-  "browser_type",
-  "browser_fill_form",
-  "browser_click_ref",
-  "browser_fill_ref",
-  "browser_wait_for",
-  "browser_assert",
-  "browser_verify",
-  "browser_screenshot",
-  "browser_snapshot_refs",
-  "browser_find",
-  "browser_get_console_logs",
-  "browser_get_network_logs",
-  "browser_evaluate",
-  "browser_reload",
-  "browser_batch",
-  "browser_act",
-] as const;
+/**
+ * Browser tools presented to run-uat. A derived view of the Browser Automation
+ * Contract vocabulary (shared/browser-contract.ts) — the contract module is the
+ * only place browser tool names are declared.
+ */
+export const RUN_UAT_BROWSER_TOOL_NAMES = BROWSER_CONTRACT_TOOL_NAMES;
 
 // ─── The registry ─────────────────────────────────────────────────────────
 

package/src/resources/extensions/gsd/web-app-uat.ts

@@ -1,10 +1,12 @@
 // Project/App: gsd-pi
-// File Purpose: Web-app detection and Playwright/UAT guidance for planning and slice closeout.
+// File Purpose: Web-app detection and browser-UAT guidance for planning and slice closeout.
 
 import { existsSync, readFileSync } from "node:fs";
 import { resolve } from "node:path";
 
+import { resolveAmbientBrowserEngineResolution, type BrowserEngineResolution } from "../browser-tools/engine/selection.js";
 import { detectWebApp } from "../browser-tools/web-app-detect.js";
+import { UAT_MODE_POLICIES, type UatType } from "./uat-policy.js";
 
 export { detectWebApp };
 
@@ -47,24 +49,61 @@ export function findPlaywrightTestScript(projectRoot: string): string | null {
   return null;
 }
 
+function describeBrowserToolBacking(engineResolution: BrowserEngineResolution): string {
+  switch (engineResolution.engine) {
+    case "gsd-browser":
+      return "This project looks browser-facing. GSD exposes `browser_*` tools backed by the managed gsd-browser engine for run-uat.";
+    case "legacy":
+      return "This project looks browser-facing. GSD exposes Playwright-backed `browser_*` tools for run-uat.";
+    case "off":
+      return "This project looks browser-facing, but Pi browser tools are disabled (GSD_BROWSER_ENGINE=off) — prefer `runtime-executable` UAT with automated browser test commands.";
+  }
+}
+
+// One bullet per recommended UAT mode; `mode` keys into UAT_MODE_POLICIES so
+// modes that require browser tools drop out of the guidance when the resolved
+// engine provides none (mixed/live-runtime share one bullet and one policy bit).
+const UAT_MODE_GUIDANCE: ReadonlyArray<{ mode: UatType; bullet: string }> = [
+  {
+    mode: "browser-executable",
+    bullet: "- `browser-executable` — navigate to `http://localhost:…`, click, screenshot, assert via `browser_*` tools during run-uat",
+  },
+  {
+    mode: "runtime-executable",
+    bullet: "- `runtime-executable` — run an automated browser test command via `gsd_uat_exec` (for example `npx playwright test`)",
+  },
+  {
+    mode: "mixed",
+    bullet: "- `mixed` / `live-runtime` — combine runtime startup checks with interactive browser verification",
+  },
+];
+
 /**
  * Markdown block injected into plan/complete-slice prompts when the project
- * looks browser-facing. Returns null for CLI/library-only repos.
+ * looks browser-facing. Returns null for CLI/library-only repos. Guidance is
+ * composed from the resolved Browser Automation Engine so prompts never claim
+ * an engine the runtime is not using; `engineResolution` is injectable for
+ * tests and defaults to the ambient resolution.
  */
-export function buildWebAppUatGuidanceBlock(projectRoot: string): string | null {
+export function buildWebAppUatGuidanceBlock(
+  projectRoot: string,
+  engineResolution?: BrowserEngineResolution,
+): string | null {
   if (!detectWebApp(projectRoot)) return null;
 
+  const resolvedEngine = engineResolution ?? resolveAmbientBrowserEngineResolution(projectRoot);
+  const browserToolsAvailable = resolvedEngine.engine !== "off";
   const playwrightScript = findPlaywrightTestScript(projectRoot);
   const hasPlaywright = hasPlaywrightTestDependency(projectRoot) || playwrightScript !== null;
   const lines = [
     "### Web App UAT (detected)",
     "",
-    "This project looks browser-facing. GSD exposes Playwright-backed `browser_*` tools by default for run-uat.",
+    describeBrowserToolBacking(resolvedEngine),
     "",
     "**UAT modes (pick one per slice — do not use `artifact-driven` for browser steps):**",
-    "- `browser-executable` — navigate to `http://localhost:…`, click, screenshot, assert via `browser_*` tools during run-uat",
-    "- `runtime-executable` — run an automated browser test command via `gsd_uat_exec` (for example `npx playwright test`)",
-    "- `mixed` / `live-runtime` — combine runtime startup checks with interactive browser verification",
+    ...UAT_MODE_GUIDANCE
+      .filter(({ mode }) => browserToolsAvailable || !UAT_MODE_POLICIES[mode].browserTools)
+      .map(({ bullet }) => bullet),
     "",
     "**Planning / closeout rules:**",
     "- Preconditions must name the dev-server command and URL (for example `npm run dev` → `http://localhost:3000`)",
@@ -93,8 +132,12 @@ export function buildWebAppUatGuidanceBlock(projectRoot: string): string | null
       "**Playwright scaffolding (first UI slice):** no `playwright` / `@playwright/test` dependency yet.",
       "- Add a planning task that installs Playwright, adds `playwright.config.ts`, and creates a minimal smoke spec (for example `e2e/smoke.spec.ts`)",
       "- Task `verify` should run `npx playwright test` (or the focused spec) with a safe, simple command",
-      "- Until specs exist, use `browser-executable` UAT with localhost preconditions and interactive `browser_*` checks at slice closeout",
     );
+    if (browserToolsAvailable) {
+      lines.push(
+        "- Until specs exist, use `browser-executable` UAT with localhost preconditions and interactive `browser_*` checks at slice closeout",
+      );
+    }
   }
 
   return lines.join("\n");

package/src/resources/extensions/search-the-web/native-search.ts

@@ -243,9 +243,11 @@ export function registerNativeSearchHooks(pi: NativeSearchPI): { getIsAnthropic:
       // Anthropic-only tool never leaks into OpenAI Responses requests.
       isAnthropic = isAnthropicProvider && payloadLooksAnthropic !== false;
     } else {
-      // Last resort: session-restore paths where the SDK doesn't pass model.
-      // The model-name prefix is best-effort and assumes direct Anthropic.
-      isAnthropic = payloadLooksAnthropic === true;
+      // No authoritative provider info available (no event.model, no model_select).
+      // Do NOT inject native web_search — guessing on model name alone causes 400
+      // "unsupported_value" errors when the actual provider (copilot, openrouter,
+      // proxy, etc.) doesn't expose the server-side search tool (#648).
+      isAnthropic = false;
     }
     if (!isAnthropic) return;
 

package/src/resources/extensions/shared/browser-contract.ts

@@ -0,0 +1,66 @@
+// Project/App: gsd-pi
+// File Purpose: Browser Automation Contract — the single source for the canonical
+// Pi-facing browser tool vocabulary. Engine adapters (legacy Playwright, managed
+// gsd-browser), UAT policy, dispatch preflight, and evidence detection all derive
+// their browser tool knowledge from this module instead of re-listing names.
+
+/**
+ * Canonical `browser_*` tool names of the Browser Automation Contract.
+ *
+ * These are the product-level names Units see regardless of which Browser
+ * Automation Engine serves them (ADR-024). Adding a capability here is the
+ * one-line vocabulary change; the engine adapters and presentation surfaces
+ * are typed against this list, so missing coverage fails typecheck.
+ */
+export const BROWSER_CONTRACT_TOOL_NAMES = [
+  "browser_navigate",
+  "browser_click",
+  "browser_type",
+  "browser_fill_form",
+  "browser_click_ref",
+  "browser_fill_ref",
+  "browser_wait_for",
+  "browser_assert",
+  "browser_verify",
+  "browser_screenshot",
+  "browser_snapshot_refs",
+  "browser_find",
+  "browser_get_console_logs",
+  "browser_get_network_logs",
+  "browser_evaluate",
+  "browser_reload",
+  "browser_batch",
+  "browser_act",
+] as const;
+
+export type BrowserContractToolName = (typeof BROWSER_CONTRACT_TOOL_NAMES)[number];
+
+const BROWSER_CONTRACT_TOOL_NAME_SET: ReadonlySet<string> = new Set(BROWSER_CONTRACT_TOOL_NAMES);
+
+export function isBrowserContractToolName(name: string): name is BrowserContractToolName {
+  return BROWSER_CONTRACT_TOOL_NAME_SET.has(name);
+}
+
+/**
+ * Whether a canonical (non-MCP-prefixed) tool name belongs to the browser tool
+ * family. Broader than the contract list on purpose: an External MCP Client or
+ * host integration may supply additional `browser_*` tools that still satisfy
+ * browser-backed UAT.
+ */
+export function hasBrowserContractPrefix(canonicalToolName: string): boolean {
+  return canonicalToolName.startsWith("browser_");
+}
+
+/**
+ * Contract tool names whose appearance in prose marks browser-backed UAT
+ * activity (requirement or evidence language). Consumed by the
+ * browser-evidence regexes so textual detection stays derived from the
+ * contract vocabulary.
+ */
+export const BROWSER_EVIDENCE_SIGNAL_TOOL_NAMES = [
+  "browser_assert",
+  "browser_batch",
+  "browser_find",
+  "browser_verify",
+  "browser_snapshot_refs",
+] as const satisfies readonly BrowserContractToolName[];

package/src/resources/extensions/shared/gsd-browser-cli.ts

@@ -55,6 +55,14 @@ function parseGsdBrowserVersion(output: string): string | null {
   return output.match(/\b(\d+\.\d+\.\d+)\b/)?.[1] ?? null;
 }
 
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return !!value && typeof value === "object" && !Array.isArray(value);
+}
+
+function resolveExplicitGsdBrowserCliPath(env: NodeJS.ProcessEnv): string | undefined {
+  return env.GSD_BROWSER_CLI_PATH?.trim() || env.GSD_BROWSER_BIN_PATH?.trim() || undefined;
+}
+
 function resolveBundledGsdBrowserPackageVersion(): string | null {
   try {
     const requireFromHere = createRequire(import.meta.url);
@@ -66,20 +74,28 @@ function resolveBundledGsdBrowserPackageVersion(): string | null {
   }
 }
 
+// The `gsd-browser --version` subprocess result cannot change mid-session (the
+// engine-switch guard forbids restarting with a different engine), and both the
+// availability probe and the launch-config resolution ask for it at session
+// start — memoize so the up-to-2s spawn happens once per process.
+let cachedPathProbeVersion: string | null | undefined;
+
 function resolvePathGsdBrowserVersion(env: NodeJS.ProcessEnv): string | null {
   const explicit = env.GSD_BROWSER_PATH_VERSION?.trim();
   if (explicit) return parseGsdBrowserVersion(explicit);
+  if (cachedPathProbeVersion !== undefined) return cachedPathProbeVersion;
 
   try {
-    return parseGsdBrowserVersion(execFileSync("gsd-browser", ["--version"], {
+    cachedPathProbeVersion = parseGsdBrowserVersion(execFileSync("gsd-browser", ["--version"], {
       encoding: "utf-8",
       env,
       stdio: ["ignore", "pipe", "ignore"],
       timeout: 2000,
     }));
   } catch {
-    return null;
+    cachedPathProbeVersion = null;
   }
+  return cachedPathProbeVersion;
 }
 
 function shouldPreferPathGsdBrowser(env: NodeJS.ProcessEnv): boolean {
@@ -91,7 +107,7 @@ function shouldPreferPathGsdBrowser(env: NodeJS.ProcessEnv): boolean {
 }
 
 export function resolveBundledGsdBrowserCliPath(env: NodeJS.ProcessEnv = process.env): string | null {
-  const explicit = env.GSD_BROWSER_CLI_PATH?.trim() || env.GSD_BROWSER_BIN_PATH?.trim();
+  const explicit = resolveExplicitGsdBrowserCliPath(env);
   if (explicit) return explicit;
 
   try {
@@ -115,6 +131,45 @@ export function resolveBundledGsdBrowserCliPath(env: NodeJS.ProcessEnv = process
   return null;
 }
 
+export type GsdBrowserCliAvailability =
+  | { available: true; via: "explicit-env" | "bundled" | "path"; detail: string }
+  | { available: false; detail: string };
+
+/**
+ * Cheap availability probe for the gsd-browser CLI: explicit env overrides,
+ * then the bundled @opengsd/gsd-browser binary (filesystem checks only), then
+ * a PATH lookup (one short subprocess, memoized). Used by Browser Automation
+ * Engine resolution to decide whether the managed engine is provable before
+ * preferring it over legacy Playwright. `via` names the provable source, not
+ * necessarily the launch source — resolveGsdBrowserMcpLaunchConfig may still
+ * prefer a newer PATH CLI over the bundled one.
+ */
+export function resolveGsdBrowserCliAvailability(env: NodeJS.ProcessEnv = process.env): GsdBrowserCliAvailability {
+  const explicitCommand = env.GSD_BROWSER_MCP_COMMAND?.trim();
+  if (explicitCommand) {
+    return { available: true, via: "explicit-env", detail: `GSD_BROWSER_MCP_COMMAND=${explicitCommand}` };
+  }
+
+  const explicitCliPath = resolveExplicitGsdBrowserCliPath(env);
+  if (explicitCliPath) {
+    return existsSync(explicitCliPath)
+      ? { available: true, via: "explicit-env", detail: `CLI at ${explicitCliPath}` }
+      : { available: false, detail: `configured gsd-browser CLI path does not exist: ${explicitCliPath}` };
+  }
+
+  const bundledCliPath = resolveBundledGsdBrowserCliPath(env);
+  if (bundledCliPath) {
+    return { available: true, via: "bundled", detail: `bundled CLI at ${bundledCliPath}` };
+  }
+
+  const pathVersion = resolvePathGsdBrowserVersion(env);
+  if (pathVersion) {
+    return { available: true, via: "path", detail: `gsd-browser ${pathVersion} on PATH` };
+  }
+
+  return { available: false, detail: "no bundled or PATH gsd-browser CLI found" };
+}
+
 export function buildGsdBrowserSessionName(projectRoot: string, suffix?: string): string {
   const resolvedProjectRoot = resolve(projectRoot);
   const base = sanitizeSessionSegment(basename(resolvedProjectRoot)) || "project";
@@ -123,6 +178,35 @@ export function buildGsdBrowserSessionName(projectRoot: string, suffix?: string)
   return cleanSuffix ? `gsd-${base}-${hash}-${cleanSuffix}` : `gsd-${base}-${hash}`;
 }
 
+/**
+ * Recognize an MCP server config (from .mcp.json / Claude settings) as a
+ * gsd-browser server. Paired with resolveGsdBrowserMcpLaunchConfig: this module
+ * writes the config shape, so it also owns recognizing it. New launch shapes
+ * are taught here, in one place.
+ */
+export function isGsdBrowserMcpServerConfig(config: unknown): boolean {
+  if (!isRecord(config)) return false;
+
+  const command = typeof config.command === "string" ? config.command : "";
+  if (command.includes("gsd-browser") || command.includes("@opengsd/gsd-browser")) {
+    return true;
+  }
+
+  if (isRecord(config.env)) {
+    const env = config.env;
+    if (
+      typeof env.GSD_BROWSER_CLI_PATH === "string"
+      || typeof env.GSD_BROWSER_BIN_PATH === "string"
+      || typeof env.GSD_BROWSER_MCP_COMMAND === "string"
+    ) {
+      return true;
+    }
+  }
+
+  const args = Array.isArray(config.args) ? config.args.filter((arg): arg is string => typeof arg === "string") : [];
+  return args.some((arg) => arg.includes("gsd-browser") || arg.includes("@opengsd/gsd-browser"));
+}
+
 export function resolveGsdBrowserMcpLaunchConfig(
   projectRoot: string,
   env: NodeJS.ProcessEnv = process.env,
@@ -133,7 +217,7 @@ export function resolveGsdBrowserMcpLaunchConfig(
   const explicitArgs = parseJsonEnv<unknown>(env, "GSD_BROWSER_MCP_ARGS");
   const explicitEnv = parseJsonEnv<Record<string, string>>(env, "GSD_BROWSER_MCP_ENV");
   const explicitCommand = env.GSD_BROWSER_MCP_COMMAND?.trim();
-  const explicitCliPath = env.GSD_BROWSER_CLI_PATH?.trim() || env.GSD_BROWSER_BIN_PATH?.trim();
+  const explicitCliPath = resolveExplicitGsdBrowserCliPath(env);
   const preferPathCli = !explicitCommand && !explicitCliPath && shouldPreferPathGsdBrowser(env);
   const bundledCliPath = !explicitCommand && !explicitCliPath && !preferPathCli
     ? resolveBundledGsdBrowserCliPath(env)

package/src/resources/skills/create-skill/references/executable-code.md

@@ -45,7 +45,7 @@ skill-name/
 **Reference pattern**: In SKILL.md, reference scripts using the `scripts/` path:
 
 ```bash
-python ~/.claude/skills/skill-name/scripts/analyze.py input.har
+python ~/.agents/skills/skill-name/scripts/analyze.py input.har
 ```
 </scripts_directory>
 </file_organization>

package/src/resources/skills/create-skill/workflows/add-reference.md

@@ -10,16 +10,21 @@
 ## Step 1: Select the Skill
 
 ```bash
-ls ~/.claude/skills/
+# User-global skills
+ls ~/.agents/skills/ 2>/dev/null
+# Project-local skills
+ls .agents/skills/ 2>/dev/null
 ```
 
 Present numbered list, ask: "Which skill needs a new reference?"
 
+Determine `{skill-path}`: use `.agents/skills/{skill-name}` (project-local) if found there, otherwise `~/.agents/skills/{skill-name}` (user-global). Project-local takes precedence because the skill catalog loads it first on name collision.
+
 ## Step 2: Analyze Current Structure
 
 ```bash
-cat ~/.claude/skills/{skill-name}/SKILL.md
-ls ~/.claude/skills/{skill-name}/references/ 2>/dev/null
+cat {skill-path}/SKILL.md
+ls {skill-path}/references/ 2>/dev/null
 ```
 
 Determine:

package/src/resources/skills/create-skill/workflows/add-script.md

@@ -12,6 +12,8 @@ Ask (if not already provided):
 - Which skill needs a script?
 - What operation should the script perform?
 
+Determine `{skill-path}`: use `.agents/skills/{skill-name}` (project-local) if found there, otherwise `~/.agents/skills/{skill-name}` (user-global). Project-local takes precedence because the skill catalog loads it first on name collision.
+
 ## Step 2: Analyze Script Need
 
 Confirm this is a good script candidate:
@@ -24,7 +26,7 @@ If not a good fit, suggest alternatives (inline code in workflow, reference exam
 ## Step 3: Create Scripts Directory
 
 ```bash
-mkdir -p ~/.claude/skills/{skill-name}/scripts
+mkdir -p {skill-path}/scripts
 ```
 
 ## Step 4: Design Script
@@ -58,7 +60,7 @@ set -euo pipefail
 ## Step 6: Make Executable (if bash)
 
 ```bash
-chmod +x ~/.claude/skills/{skill-name}/scripts/{script-name}.sh
+chmod +x {skill-path}/scripts/{script-name}.sh
 ```
 
 ## Step 7: Update Workflow to Use Script

package/src/resources/skills/create-skill/workflows/add-template.md

@@ -12,6 +12,8 @@ Ask (if not already provided):
 - Which skill needs a template?
 - What output does this template structure?
 
+Determine `{skill-path}`: use `.agents/skills/{skill-name}` (project-local) if found there, otherwise `~/.agents/skills/{skill-name}` (user-global). Project-local takes precedence because the skill catalog loads it first on name collision.
+
 ## Step 2: Analyze Template Need
 
 Confirm this is a good template candidate:
@@ -24,7 +26,7 @@ If not a good fit, suggest alternatives (workflow guidance, reference examples).
 ## Step 3: Create Templates Directory
 
 ```bash
-mkdir -p ~/.claude/skills/{skill-name}/templates
+mkdir -p {skill-path}/templates
 ```
 
 ## Step 4: Design Template Structure