@tonyclaw/agent-inspector 3.0.44 → 3.0.45

package/src/cli/templates/codex-skill-onboard.ts

@@ -11,6 +11,16 @@ export type CodexSkillOnboardContext = {
   readonly version: string;
   /** The default proxy port (mirrors `DEFAULT_PORT` in `src/cli.ts`). */
   readonly port: number;
+  /** Public UI base URL, including the configured base path. */
+  readonly baseUrl: string;
+  /** MCP config key selected by onboarding. */
+  readonly mcpName?: string;
+  /** Selected onboarding target type. */
+  readonly targetKind?: "default" | "instance" | "base-url";
+  /** Normalized registry name for a named target. */
+  readonly instanceName?: string | null;
+  /** CLI arguments that reproduce the selected target. */
+  readonly onboardTargetArguments?: string;
 };
 
 export const REQUIRED_CODEX_PHASE_HEADINGS = [
@@ -23,7 +33,35 @@ export const REQUIRED_CODEX_PHASE_HEADINGS = [
 ] as const;
 
 export function renderCodexSkillOnboard(ctx: CodexSkillOnboardContext): string {
-  const { version, port } = ctx;
+  const { version, baseUrl } = ctx;
+  const mcpName = ctx.mcpName ?? "agent-inspector";
+  const targetKind = ctx.targetKind ?? "default";
+  const targetArguments = ctx.onboardTargetArguments ?? "";
+  const instanceName = ctx.instanceName ?? null;
+  const healthUrl = `${baseUrl}/api/health`;
+  const configUrl = `${baseUrl}/api/config`;
+  const anthropicProxyUrl = `${baseUrl}/proxy`;
+  const openAiProxyUrl = `${baseUrl}/proxy/v1`;
+  const mcpUrl = `${baseUrl}/api/mcp`;
+  const mcpTomlKey = /^[A-Za-z0-9_-]+$/u.test(mcpName) ? mcpName : JSON.stringify(mcpName);
+  const statusCommand = `agent-inspector onboard --status${targetArguments}`;
+  const refreshCommand = `agent-inspector onboard --force${targetArguments}`;
+  const startCommand =
+    targetKind === "instance" && instanceName !== null
+      ? `agent-inspector instance start ${instanceName}`
+      : targetKind === "base-url"
+        ? `# Explicit target ${baseUrl}: do not start a replacement local runtime.`
+        : "agent-inspector --mode simple --background --no-open";
+  const fullModeCommand =
+    targetKind === "instance" && instanceName !== null
+      ? `agent-inspector instance restart ${instanceName} --mode full`
+      : targetKind === "base-url"
+        ? "ask the target operator to enable Full capture mode"
+        : "agent-inspector --mode full --force-restart";
+  const startExplanation =
+    targetKind === "base-url"
+      ? `The selected Inspector target is the explicit Base URL \`${baseUrl}\`. Do not start the default local runtime as a substitute; verify the selected target and ask its operator for help if it is unavailable.`
+      : `Start or reuse the selected Agent Inspector runtime before wiring MCP. Prefer the installed binary so Windows users get the branded runtime in Task Manager. Use \`${fullModeCommand}\` only when the user needs raw headers, raw response, or SSE chunks.`;
   return `---
 name: agent-inspector-onboard
 description: Guide Codex users through connecting Agent Inspector v${version} as a local MCP server.
@@ -39,7 +77,7 @@ Use this skill when the user wants to set up Agent Inspector inside Codex, conne
 Agent Inspector runs a local web UI, proxy, REST API, and MCP endpoint on the same port. The default MCP endpoint is:
 
 \`\`\`text
-http://localhost:${port}/api/mcp
+${mcpUrl}
 \`\`\`
 
 This skill is installed at \`~/.codex/skills/agent-inspector-onboard/SKILL.md\`.
@@ -47,8 +85,8 @@ Codex user-level configuration lives in \`~/.codex/config.toml\`. Codex supports
 
 Use exactly one MCP transport for the same Inspector instance:
 
-- Streamable HTTP MCP: configure \`url = "http://localhost:${port}/api/mcp"\`.
-- Stdio-only MCP clients: configure \`agent-inspector-mcp stdio --url http://localhost:${port}/api/mcp\`.
+- Streamable HTTP MCP: configure \`url = "${mcpUrl}"\`.
+- Stdio-only MCP clients: configure \`agent-inspector-mcp stdio --url ${mcpUrl}\`.
 
 Do not configure both transports in the same MCP client, or the client may show duplicate Inspector tools.
 
@@ -64,14 +102,14 @@ Check that the package and Codex home exist without printing secrets.
 
 \`\`\`powershell
 Get-Command agent-inspector -ErrorAction SilentlyContinue | Select-Object -ExpandProperty Source
-agent-inspector onboard --status
+${statusCommand}
 Test-Path (Join-Path $env:USERPROFILE ".codex")
 Test-Path (Join-Path $env:USERPROFILE ".codex\\config.toml")
 \`\`\`
 
 \`\`\`bash
 node -e "const fs=require('node:fs'),p=require('node:path');const names=process.platform==='win32'?['agent-inspector.cmd','agent-inspector.exe','agent-inspector']:['agent-inspector'];const found=(process.env.PATH||'').split(p.delimiter).some(d=>names.some(n=>fs.existsSync(p.join(d,n))));console.log(found?'agent-inspector: present':'agent-inspector: missing')"
-agent-inspector onboard --status
+${statusCommand}
 test -d "$HOME/.codex" && echo "codex home: present" || echo "codex home: missing"
 test -f "$HOME/.codex/config.toml" && echo "config: present" || echo "config: missing"
 \`\`\`
@@ -82,8 +120,8 @@ If \`agent-inspector\` is missing, ask the user to install it first:
 npm install -g @tonyclaw/agent-inspector
 \`\`\`
 
-If \`agent-inspector onboard --status\` reports \`outdated\` or \`missing\`, ask the user to run
-\`agent-inspector onboard --force\` and restart this skill before continuing.
+If \`${statusCommand}\` reports \`outdated\` or \`missing\`, ask the user to run
+\`${refreshCommand}\` and restart this skill before continuing.
 
 Do not read \`~/.codex/auth.json\`, token files, or unrelated Codex state files.
 
@@ -91,33 +129,33 @@ Do not read \`~/.codex/auth.json\`, token files, or unrelated Codex state files.
 
 ## Phase 1: Start Agent Inspector
 
-Start or reuse Agent Inspector before wiring MCP. Prefer the installed binary so Windows users get the branded runtime in Task Manager. Start onboarding in Simple mode; if the user needs raw headers, raw response, or SSE chunks later, restart with \`agent-inspector --mode full\`.
+${startExplanation}
 
 \`\`\`powershell
-agent-inspector --mode simple --background --no-open
-Invoke-RestMethod -Uri "http://localhost:${port}/api/health" -TimeoutSec 3
-Invoke-RestMethod -Uri "http://localhost:${port}/api/config" -TimeoutSec 3 | Select-Object captureMode
+${startCommand}
+Invoke-RestMethod -Uri "${healthUrl}" -TimeoutSec 3
+Invoke-RestMethod -Uri "${configUrl}" -TimeoutSec 3 | Select-Object captureMode
 \`\`\`
 
 \`\`\`bash
-agent-inspector --mode simple --background --no-open
-curl -fsS "http://localhost:${port}/api/health"
-curl -fsS "http://localhost:${port}/api/config" | grep -o '"captureMode":"[^"]*"'
+${startCommand}
+curl -fsS "${healthUrl}"
+curl -fsS "${configUrl}" | grep -o '"captureMode":"[^"]*"'
 \`\`\`
 
-If the health check fails, show only the relevant error and ask whether to diagnose startup before editing Codex config. If the active capture mode is not \`simple\`, explain that an existing process is already running and offer to restart with \`agent-inspector --mode simple --force-restart\`.
+If the health check fails, show only the relevant error and ask whether to diagnose the selected target before editing Codex config. If deeper capture is required, offer \`${fullModeCommand}\`.
 
 ---
 
 ## Phase 2: Wire Codex MCP
 
-Add an \`agent-inspector\` MCP server to \`~/.codex/config.toml\`. Preserve the user's existing config and merge the table instead of replacing the file.
+Add the \`${mcpName}\` MCP server to \`~/.codex/config.toml\`. Preserve the user's existing config and merge the table instead of replacing the file.
 
 Recommended user-level config for Codex builds that support Streamable HTTP MCP:
 
 \`\`\`toml
-[mcp_servers.agent-inspector]
-url = "http://localhost:${port}/api/mcp"
+[mcp_servers.${mcpTomlKey}]
+url = "${mcpUrl}"
 startup_timeout_sec = 30
 tool_timeout_sec = 60
 \`\`\`
@@ -125,9 +163,9 @@ tool_timeout_sec = 60
 Fallback config for a stdio-only MCP client:
 
 \`\`\`toml
-[mcp_servers.agent-inspector]
+[mcp_servers.${mcpTomlKey}]
 command = "agent-inspector-mcp"
-args = ["stdio", "--url", "http://localhost:${port}/api/mcp"]
+args = ["stdio", "--url", "${mcpUrl}"]
 \`\`\`
 
 The stdio command is only a bridge to the same HTTP MCP endpoint. It does not start a second Inspector server.
@@ -135,8 +173,8 @@ The stdio command is only a bridge to the same HTTP MCP endpoint. It does not st
 If the user's Codex environment is managed by an admin allowlist, they may also need a matching identity rule in the managed requirements layer:
 
 \`\`\`toml
-[mcp_servers.agent-inspector.identity]
-url = "http://localhost:${port}/api/mcp"
+[mcp_servers.${mcpTomlKey}.identity]
+url = "${mcpUrl}"
 \`\`\`
 
 When editing:
@@ -156,7 +194,7 @@ Tell the user that Codex loads MCP servers at session startup. After saving \`co
 Before restart, verify the HTTP endpoint itself:
 
 \`\`\`bash
-curl -sS -X POST "http://localhost:${port}/api/mcp" \\
+curl -sS -X POST "${mcpUrl}" \\
   -H "Content-Type: application/json" \\
   -H "Accept: application/json, text/event-stream" \\
   -d '{
@@ -203,13 +241,23 @@ Provider mutation tools expose and modify local provider configuration. Ask for
 
 ## Phase 5: Capture and memory review
 
-To capture Codex traffic through Agent Inspector, route a model client through:
+To capture traffic through Agent Inspector, use the protocol-correct base URL:
 
 \`\`\`text
-http://localhost:${port}/proxy
+Anthropic: ${anthropicProxyUrl}
+OpenAI Responses / Codex: ${openAiProxyUrl}
 \`\`\`
 
-For Anthropic-compatible tools, set \`ANTHROPIC_BASE_URL=http://localhost:${port}/proxy\`. For OpenAI-compatible tools, set \`OPENAI_BASE_URL=http://localhost:${port}/proxy\`.
+For Anthropic-compatible tools, set \`ANTHROPIC_BASE_URL=${anthropicProxyUrl}\`. For OpenAI-compatible tools and Codex Responses providers, set \`OPENAI_BASE_URL=${openAiProxyUrl}\`.
+
+Example Codex Responses provider snippet:
+
+\`\`\`toml
+[model_providers.agent-inspector]
+name = "Agent Inspector"
+base_url = "${openAiProxyUrl}"
+wire_api = "responses"
+\`\`\`
 
 If Codex or another AI tool runs in a different container, VM, WSL distro, or host than Agent
 Inspector, \`localhost\` points at the tool's own environment. Replace \`localhost\` with an Inspector
@@ -218,7 +266,7 @@ provider credentials.
 
 For a Provider Test memory probe, run a provider test in the Agent Inspector UI:
 
-1. Open \`http://localhost:${port}\`.
+1. Open \`${baseUrl}\`.
 2. Go to Settings -> Providers.
 3. Add or edit a Provider.
 4. Run Test.

package/src/cli/templates/skill-onboard.ts

@@ -24,6 +24,16 @@ export type SkillOnboardContext = {
   readonly version: string;
   /** The default proxy port (mirrors `DEFAULT_PORT` in `src/cli.ts`). */
   readonly port: number;
+  /** Public UI base URL, including the configured base path. */
+  readonly baseUrl: string;
+  /** MCP config key selected by onboarding. */
+  readonly mcpName?: string;
+  /** Selected onboarding target type. */
+  readonly targetKind?: "default" | "instance" | "base-url";
+  /** Normalized registry name for a named target. */
+  readonly instanceName?: string | null;
+  /** CLI arguments that reproduce the selected target. */
+  readonly onboardTargetArguments?: string;
   /**
    * One-line "detected tools" summary written into the Preflight phase so the
    * skill's instructions match the user's actual environment. Empty string
@@ -46,7 +56,53 @@ export const REQUIRED_PHASE_HEADINGS = [
 ] as const;
 
 export function renderSkillOnboard(ctx: SkillOnboardContext): string {
-  const { version, port, detectedSummary } = ctx;
+  const { version, port, baseUrl, detectedSummary } = ctx;
+  const mcpName = ctx.mcpName ?? "agent-inspector";
+  const targetKind = ctx.targetKind ?? "default";
+  const targetArguments = ctx.onboardTargetArguments ?? "";
+  const instanceName = ctx.instanceName ?? null;
+  const healthUrl = `${baseUrl}/api/health`;
+  const configUrl = `${baseUrl}/api/config`;
+  const anthropicProxyUrl = `${baseUrl}/proxy`;
+  const openAiProxyUrl = `${baseUrl}/proxy/v1`;
+  const mcpUrl = `${baseUrl}/api/mcp`;
+  const logsUrl = `${baseUrl}/api/logs`;
+  const statusCommand = `agent-inspector onboard --status${targetArguments}`;
+  const refreshCommand = `agent-inspector onboard --force${targetArguments}`;
+  const startCommand =
+    targetKind === "instance" && instanceName !== null
+      ? `agent-inspector instance start ${instanceName}`
+      : targetKind === "base-url"
+        ? `# Explicit target ${baseUrl}: do not start a replacement local runtime.`
+        : "agent-inspector --mode simple --background --no-open";
+  const fullModeCommand =
+    targetKind === "instance" && instanceName !== null
+      ? `agent-inspector instance restart ${instanceName} --mode full`
+      : targetKind === "base-url"
+        ? "ask the target operator to enable Full capture mode"
+        : "agent-inspector --mode full --force-restart";
+  const bashStartSnippet =
+    targetKind === "base-url" ? startCommand : `${startCommand} > /tmp/agent-inspector.log 2>&1`;
+  const windowsStartArguments =
+    targetKind === "instance" && instanceName !== null
+      ? `instance start ${instanceName}`
+      : "--mode simple --background --no-open";
+  const powershellStartSnippet =
+    targetKind === "base-url"
+      ? startCommand
+      : `$found = Get-Command agent-inspector -ErrorAction SilentlyContinue
+if (-not $found) { throw 'agent-inspector is not on PATH' }
+& $found.Source ${windowsStartArguments}`;
+  const startExplanation =
+    targetKind === "base-url"
+      ? `The selected Inspector target is the explicit Base URL \`${baseUrl}\`. Do not launch a default local runtime as a substitute; verify the selected target and ask its operator for help if it is unavailable.`
+      : `Start or reuse the selected Inspector runtime. It listens on port ${String(port)} and preserves the selected Base Path. Use \`${fullModeCommand}\` only when the user needs raw headers, raw response, or SSE chunks.`;
+  const stopSnippet =
+    targetKind === "instance" && instanceName !== null
+      ? `agent-inspector instance stop ${instanceName}`
+      : targetKind === "base-url"
+        ? `# Ask the operator of ${baseUrl} to stop the selected runtime.`
+        : `# Unix / macOS\n  lsof -ti:${String(port)} | xargs -r kill -9\n\n  # Windows PowerShell\n  Get-NetTCPConnection -LocalPort ${String(port)} | ForEach-Object { Stop-Process -Id $_.OwningProcess -Force }`;
   return `---
 name: agent-inspector-onboard
 description: Guided setup for Agent Inspector v${version}: start the proxy, wire your AI coding tool, capture your first request, and learn the Web UI.
@@ -62,7 +118,7 @@ Guide the user from "I just installed Agent Inspector" to "I can see my AI tool'
 Environment detected by the installer:
 ${detectedSummary || "  (no known AI tool detected — the user can still use the generic curl example in Phase 4)"}
 
-Default proxy port: \`${port}\` (override with \`PORT=<n> agent-inspector\` or \`--port <n>\`).
+Selected Inspector target: \`${baseUrl}\` (MCP key: \`${mcpName}\`).
 
 > **PAUSE protocol.** Every \`**PAUSE**\` marker in this skill is a real stop.
 > Use the \`AskUserQuestion\` tool to actually wait for the user before
@@ -77,22 +133,22 @@ Default proxy port: \`${port}\` (override with \`PORT=<n> agent-inspector\` or \
 **EXPLAIN:** "Before we do anything, let me see what's already set up. If some of the steps are already done, we can skip them."
 
 **DO:** First check whether the generated onboarding files match the installed npm package. If any
-entry is \`outdated\` or \`missing\`, tell the user to run \`agent-inspector onboard --force\` before
+entry is \`outdated\` or \`missing\`, tell the user to run \`${refreshCommand}\` before
 continuing so they are not guided by stale instructions.
 
 \`\`\`bash
-agent-inspector onboard --status
+${statusCommand}
 \`\`\`
 
 \`\`\`powershell
-agent-inspector onboard --status
+${statusCommand}
 \`\`\`
 
 **DO:** Then probe the three pieces of state this skill touches. Use targeted checks — do **not** read large JSON files into the conversation.
 
 \`\`\`bash
 # 1. Is the proxy already up?
-curl -fsS "http://localhost:${port}/api/health" 2>/dev/null && echo "PROXY: up" || echo "PROXY: down"
+curl -fsS "${healthUrl}" 2>/dev/null && echo "PROXY: up" || echo "PROXY: down"
 
 # 2. Does the provider config have a real provider key?
 agent_inspector_data_dir() {
@@ -123,9 +179,9 @@ fi
 # 3. Is the MCP server already wired? (project .mcp.json wins)
 PROJ_MCP=".mcp.json"
 HOME_MCP="$HOME/.claude.json"
-if [ -f "$PROJ_MCP" ] && grep -q '"agent-inspector"' "$PROJ_MCP"; then
+if [ -f "$PROJ_MCP" ] && grep -q '"${mcpName}"' "$PROJ_MCP"; then
   echo "MCP: wired in $PROJ_MCP"
-elif [ -f "$HOME_MCP" ] && grep -q '"agent-inspector"' "$HOME_MCP"; then
+elif [ -f "$HOME_MCP" ] && grep -q '"${mcpName}"' "$HOME_MCP"; then
   echo "MCP: wired in $HOME_MCP"
 else
   echo "MCP: not wired"
@@ -155,7 +211,7 @@ $legacyConfig = Join-Path $dataDir 'config.json'
 
 # 1. Is the proxy already up?
 try {
-  $null = Invoke-RestMethod -Uri "http://localhost:$port/api/health" -TimeoutSec 2 -ErrorAction Stop
+  $null = Invoke-RestMethod -Uri "${healthUrl}" -TimeoutSec 2 -ErrorAction Stop
   Write-Host 'PROXY: up'
 } catch {
   Write-Host 'PROXY: down'
@@ -180,9 +236,9 @@ if ((Test-Path $providers) -or (Test-Path $legacyConfig)) {
 # 3. Is the MCP server already wired? (project .mcp.json wins)
 $projMcp = Join-Path (Get-Location) '.mcp.json'
 $homeMcp = Join-Path $env:USERPROFILE '.claude.json'
-if ((Test-Path $projMcp) -and (Select-String -Path $projMcp -Pattern 'agent-inspector' -Quiet)) {
+if ((Test-Path $projMcp) -and (Select-String -Path $projMcp -SimpleMatch '${mcpName}' -Quiet)) {
   Write-Host "MCP: wired in $projMcp"
-} elseif ((Test-Path $homeMcp) -and (Select-String -Path $homeMcp -Pattern 'agent-inspector' -Quiet)) {
+} elseif ((Test-Path $homeMcp) -and (Select-String -Path $homeMcp -SimpleMatch '${mcpName}' -Quiet)) {
   Write-Host "MCP: wired in $homeMcp"
 } else {
   Write-Host 'MCP: not wired'
@@ -341,44 +397,26 @@ $json | Set-Content -Path $file -Encoding UTF8
 
 ## Phase 3: Start proxy
 
-**EXPLAIN:** "Time to start the proxy. It binds to port ${port} by default, starts in Simple mode for lower overhead, reuses an already-running healthy agent-inspector, and prints the URL. Use \`--force-restart\` only when you intentionally want to replace the existing process. If the user is diagnosing raw headers, raw response, or SSE chunks, restart with \`agent-inspector --mode full\`."
+**EXPLAIN:** "${startExplanation}"
 
 **DO:** Skip this phase entirely if the Phase 0 health check already reported \`PROXY: up\` and the user opted to skip done phases.
 
-**DO:** Otherwise, start the proxy with the explicit \`--background --no-open\` flags. On Windows, resolve the npm shim first and launch it through \`Start-Process -WindowStyle Hidden\` so setup does not flash a command window.
+**DO:** Otherwise, use the selected target command below. An explicit wrapper Base URL is connection-only and must not cause a replacement local runtime to start.
 
 \`\`\`bash
-# Unix / macOS / WSL
-agent-inspector --mode simple --background --no-open > /tmp/agent-inspector.log 2>&1
+${bashStartSnippet}
 \`\`\`
 
 \`\`\`powershell
-# Windows PowerShell — single-quoted so $env: expands correctly.
-# Locate the binary on PATH first (works for npm, pnpm, yarn, volta, fnm).
-# If not on PATH, fall back to the common npm global shim at $env:APPDATA.
-# As a last resort, let cmd /c resolve it through PATHEXT.
-$log = Join-Path $env:TEMP 'agent-inspector.log'
-$err = Join-Path $env:TEMP 'agent-inspector.err.log'
-$found = Get-Command agent-inspector -ErrorAction SilentlyContinue
-if ($found) {
-  $shim = $found.Source
-  $args = '--mode','simple','--background','--no-open'
-} elseif (Test-Path (Join-Path $env:APPDATA 'npm/agent-inspector.cmd')) {
-  $shim = Join-Path $env:APPDATA 'npm/agent-inspector.cmd'
-  $args = '--mode','simple','--background','--no-open'
-} else {
-  # bin not on PATH and not at the default npm prefix — let cmd resolve it
-  $shim = 'cmd.exe'
-  $args = '/c','agent-inspector','--mode','simple','--background','--no-open'
-}
-Start-Process -FilePath $shim -ArgumentList $args -RedirectStandardOutput $log -RedirectStandardError $err -WindowStyle Hidden
+# Windows PowerShell
+${powershellStartSnippet}
 \`\`\`
 
 Then wait for the port to be ready:
 
 \`\`\`bash
 for i in $(seq 1 20); do
-  curl -fsS "http://localhost:${port}/api/health" >/dev/null 2>&1 && echo "ready" && break
+  curl -fsS "${healthUrl}" >/dev/null 2>&1 && echo "ready" && break
   sleep 0.5
 done
 \`\`\`
@@ -386,13 +424,13 @@ done
 **DO:** Hit the health endpoint to confirm the proxy is alive:
 
 \`\`\`bash
-curl -sS "http://localhost:${port}/api/health"
+curl -sS "${healthUrl}"
 \`\`\`
 
-**DO:** Read \`/api/config\` and tell the user which capture mode is active. If it is not \`simple\` during onboarding, explain that an existing process is already running and offer to restart with \`agent-inspector --mode simple --force-restart\`.
+**DO:** Read \`/api/config\` and tell the user which capture mode is active. If deeper capture is required, offer \`${fullModeCommand}\`.
 
 \`\`\`bash
-curl -sS "http://localhost:${port}/api/config" | grep -o '"captureMode":"[^"]*"'
+curl -sS "${configUrl}" | grep -o '"captureMode":"[^"]*"'
 \`\`\`
 
 > **PAUSE** — if the health check fails, show the user the log file (\`/tmp/agent-inspector.log\` or \`%TEMP%\\agent-inspector.log\`) and diagnose. Common issues: another process on the port, firewall, missing providers. Use \`AskUserQuestion\` with header \`Proxy up?\` and options \`["Yes, proxy is up", "No, I see an error in the log"]\`. Wait for the answer.
@@ -407,18 +445,18 @@ curl -sS "http://localhost:${port}/api/config" | grep -o '"captureMode":"[^"]*"'
 
 \`\`\`bash
 # Claude Code
-export ANTHROPIC_BASE_URL=http://localhost:${port}/proxy
+export ANTHROPIC_BASE_URL=${anthropicProxyUrl}
 claude
 
 # OpenCode
-export LLM_BASE_URL=http://localhost:${port}/proxy
+export LLM_BASE_URL=${openAiProxyUrl}
 opencode
 
 # MiMo Code
-export OPENAI_BASE_URL=http://localhost:${port}/proxy
+export OPENAI_BASE_URL=${openAiProxyUrl}
 mimo
 
-# Cursor / Cody — set the OpenAI base URL in each tool's settings panel to http://localhost:${port}/proxy
+# Cursor / Cody — set the OpenAI base URL in each tool's settings panel to ${openAiProxyUrl}
 \`\`\`
 
 **Container/network note:** If the AI tool runs in a different container, VM, WSL distro, or host
@@ -434,32 +472,32 @@ For a tool that wasn't auto-detected, fall through to the generic curl test in t
 
 ## Phase 4.5: Wire MCP server
 
-**EXPLAIN:** "The proxy also exposes an MCP server at \`http://localhost:${port}/api/mcp\`. Your AI agent can query logs, replay requests, and test providers through it — no need to leave the editor."
+**EXPLAIN:** "The proxy also exposes an MCP server at \`${mcpUrl}\`. Your AI agent can query logs, replay requests, and test providers through it — no need to leave the editor."
 
 **DO:** Skip this phase if Phase 0 reported \`MCP: wired in <path>\` and the user opted to skip done phases.
 
 **DO:** Otherwise, check the project-level \`.mcp.json\` first (preferred — modern Claude Code convention), then fall back to \`~/.claude.json\`. Use the \`Read\` tool to inspect; do **not** \`cat\` a 40 KB file into the conversation.
 
-If neither has an \`agent-inspector\` entry, add one. The simplest path is to write to project \`.mcp.json\` (create it if missing):
+If neither has a \`${mcpName}\` entry, add one. The simplest path is to write to project \`.mcp.json\` (create it if missing):
 
 \`\`\`json
 // .mcp.json  (project root)
 {
   "mcpServers": {
-    "agent-inspector": {
+    "${mcpName}": {
       "type": "http",
-      "url": "http://localhost:${port}/api/mcp"
+      "url": "${mcpUrl}"
     }
   }
 }
 \`\`\`
 
-If \`mcpServers\` already exists in \`.mcp.json\`, merge the \`agent-inspector\` key into it via the \`Edit\` tool — do not overwrite other entries. If you can't create a project \`.mcp.json\` (no project root, permission, etc.), fall back to merging into \`~/.claude.json\` using the same \`Read\`/\`Edit\` pattern.
+If \`mcpServers\` already exists in \`.mcp.json\`, merge only the \`${mcpName}\` key into it via the \`Edit\` tool — do not overwrite other entries. If you can't create a project \`.mcp.json\` (no project root, permission, etc.), fall back to merging into \`~/.claude.json\` using the same \`Read\`/\`Edit\` pattern.
 
 **DO:** Verify the handshake. The MCP \`initialize\` request should return 200 with a \`serverInfo\` payload — that proves the server is mounted and reachable:
 
 \`\`\`bash
-curl -sS -X POST "http://localhost:${port}/api/mcp" \\
+curl -sS -X POST "${mcpUrl}" \\
   -H "Content-Type: application/json" \\
   -H "Accept: application/json, text/event-stream" \\
   -d '{
@@ -489,7 +527,7 @@ The \`grep -o '"name":"agent-inspector"'\` extracts only the serverInfo name —
 Fire a minimal Anthropic-format request through the proxy:
 
 \`\`\`bash
-curl -sS -X POST "http://localhost:${port}/proxy/v1/messages" \\
+curl -sS -X POST "${anthropicProxyUrl}/v1/messages" \\
   -H "Content-Type: application/json" \\
   -H "anthropic-version: 2023-06-01" \\
   -H "x-api-key: \${AGENT_INSPECTOR_API_KEY:-sk-no-key-needed-for-routing}" \\
@@ -501,7 +539,7 @@ curl -sS -X POST "http://localhost:${port}/proxy/v1/messages" \\
 
 \`\`\`bash
 for i in $(seq 1 10); do
-  resp=$(curl -sS "http://localhost:${port}/api/logs?limit=1")
+  resp=$(curl -sS "${logsUrl}?limit=1")
   count=$(echo "$resp" | grep -o '"total":[0-9]*' | head -1 | grep -o '[0-9]*$')
   if [ "\${count:-0}" -ge 1 ]; then
     echo "captured"
@@ -530,21 +568,17 @@ done
 
 **EXPLAIN:** "Everything's working. Here's the cheat sheet for the Web UI and the supporting surfaces:"
 
-- **Web UI**: \`http://localhost:${port}/\` — collapsible log rows, per-tab Copy/Expand in the log header, Diff with Raw (request body), Diff with Previous (compare adjacent requests), Replay (re-send a request), Export (JSON ZIP).
-- **MCP server**: \`http://localhost:${port}/api/mcp\` — connect from your coding agent to query logs, replay, and test providers without leaving the editor. Look for the "MCP Ready" badge in the Web UI header.
+- **Web UI**: \`${baseUrl}\` — collapsible log rows, per-tab Copy/Expand in the log header, Diff with Raw (request body), Diff with Previous (compare adjacent requests), Replay (re-send a request), Export (JSON ZIP).
+- **MCP server**: \`${mcpUrl}\` — connect from your coding agent to query logs, replay, and test providers without leaving the editor. Look for the "MCP Ready" badge in the Web UI header.
 - **REST API**: \`/api/logs\`, \`/api/sessions\`, \`/api/providers\` — for scripting and shell-based inspection.
 - **Stop the proxy**:
 
   \`\`\`bash
-  # Unix / macOS
-  lsof -ti:${port} | xargs -r kill -9
-
-  # Windows PowerShell — single-quoted so $env: expands correctly
-  Get-NetTCPConnection -LocalPort $port | ForEach-Object { Stop-Process -Id $_.OwningProcess -Force }
+${stopSnippet}
   \`\`\`
 
-- **Re-run onboard**: \`agent-inspector onboard --force\` refreshes this skill.
-- **Check onboard files**: \`agent-inspector onboard --status\` shows whether generated skills are
+- **Re-run onboard**: \`${refreshCommand}\` refreshes this skill.
+- **Check onboard files**: \`${statusCommand}\` shows whether generated skills are
   current, outdated, missing, newer, or custom.
 - **Full docs**: see the project README (linked from the Web UI footer).