@tonyclaw/agent-inspector 3.1.32 → 4.0.2

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

@@ -1,625 +0,0 @@
-/**
- * Renders `~/.claude/skills/agent-inspector-onboard/SKILL.md` for the
- * `agent-inspector onboard` subcommand. The body is a multi-phase teaching
- * workflow with `EXPLAIN / DO / PAUSE` markers — Claude reads it and walks
- * the user through real actions (start the proxy, hit /api/health, post a
- * test request, poll /api/logs) instead of just printing a static tutorial.
- *
- * The template embeds platform-aware shell snippets inline (bash + PowerShell
- * side-by-side). Skills are pure Markdown — they can't `require()` from the
- * package at runtime, so the duplication is the price of portability.
- *
- * All PowerShell snippets that use `$env:` variables are written so they
- * work when invoked via the Bash tool. The pattern is:
- *   powershell -Command '<single-quoted block with $env:LITERAL>'
- * NOT
- *   powershell -Command "<double-quoted block with escaped \$env:>"
- * The latter collapses `$env:` to a literal in bash before PowerShell sees
- * it, producing garbled paths. Single-quoted bash arguments pass through
- * to PowerShell unchanged.
- */
-
-export type SkillOnboardContext = {
-  /** Package version (from `package.json`), stamped into the frontmatter. */
-  readonly version: string;
-  /** The default proxy port (mirrors `DEFAULT_PORT` in `src/cli.ts`). */
-  readonly port: number;
-  /** Public backend control/agent Base URL, including the configured Base Path. */
-  readonly baseUrl: string;
-  /** Optional composed or standalone UI URL. Undefined preserves the legacy composed default. */
-  readonly uiUrl?: string | null;
-  /** REST/SSE Base URL. Falls back to baseUrl for compatibility. */
-  readonly controlBaseUrl?: string;
-  /** Proxy/MCP Base URL. Falls back to baseUrl for compatibility. */
-  readonly agentBaseUrl?: 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
-   * means "no known tool detected — fall through to the curl example".
-   */
-  readonly detectedSummary: string;
-};
-
-/** The 9 phase headings the spec requires. The validator checks for these. */
-export const REQUIRED_PHASE_HEADINGS = [
-  "Phase 0: Idempotency check",
-  "Preflight",
-  "Phase 1: Welcome",
-  "Phase 2: Provider setup",
-  "Phase 3: Start proxy",
-  "Phase 4: Wire tool",
-  "Phase 4.5: Wire MCP server",
-  "Phase 5: First capture",
-  "Phase 6: Tour & wrap",
-] as const;
-
-export function renderSkillOnboard(ctx: SkillOnboardContext): string {
-  const { version, port, detectedSummary } = ctx;
-  const controlBaseUrl = ctx.controlBaseUrl ?? ctx.baseUrl;
-  const agentBaseUrl = ctx.agentBaseUrl ?? ctx.baseUrl;
-  const uiUrl = ctx.uiUrl === undefined ? ctx.baseUrl : ctx.uiUrl;
-  const mcpName = ctx.mcpName ?? "agent-inspector";
-  const targetKind = ctx.targetKind ?? "default";
-  const targetArguments = ctx.onboardTargetArguments ?? "";
-  const instanceName = ctx.instanceName ?? null;
-  const healthUrl = `${controlBaseUrl}/api/health`;
-  const runtimeUrl = `${controlBaseUrl}/api/runtime`;
-  const configUrl = `${controlBaseUrl}/api/config`;
-  const anthropicProxyUrl = `${agentBaseUrl}/proxy`;
-  const openAiProxyUrl = `${agentBaseUrl}/proxy/v1`;
-  const mcpUrl = `${agentBaseUrl}/api/mcp`;
-  const logsUrl = `${controlBaseUrl}/api/logs`;
-  const providersUrl = `${controlBaseUrl}/api/providers`;
-  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 control target ${controlBaseUrl}: 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 uses control Base URL \`${controlBaseUrl}\` and agent Base URL \`${agentBaseUrl}\`. 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 backend. Its public control and agent endpoints preserve the selected Base Path; a Web UI may be composed at the same URL, hosted separately, or intentionally absent in backend-only mode. 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 ${controlBaseUrl} 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 }`;
-  const providerScopeGuidance =
-    targetKind === "default"
-      ? "The unmanaged default target owns the local Agent Inspector data directory used by the file checks below."
-      : `The selected target is not the unmanaged default data directory. Do not inspect or edit local ~/.agent-inspector Provider files as a substitute. Query \`${providersUrl}\`, use the selected target's MCP Provider tools with explicit approval, or ask its operator to configure Providers. Skip local-file commands below.`;
-  const selectedUi =
-    uiUrl === null ? "not supplied (do not infer one from a backend URL)" : `\`${uiUrl}\``;
-  const uiTour =
-    uiUrl === null
-      ? "not supplied; continue with MCP/REST, and ask the operator for a standalone UI URL only if the user needs one"
-      : `\`${uiUrl}\` — use this explicit composed or standalone browser URL; do not replace it with the control or agent Base URL`;
-  return `---
-name: agent-inspector-onboard
-description: Guided setup for Agent Inspector v${version}: start or select the backend, wire your AI coding tool, and capture your first request with or without a Web UI.
-metadata:
-  author: agent-inspector
-  version: ${version}
----
-
-# Agent Inspector onboard
-
-Guide the user from "I just installed Agent Inspector" to "my coding agent can use the proxy, REST API, and MCP surface". The backend works in composed and headless deployments; treat the Web UI as an optional presentation surface.
-
-Environment detected by the installer:
-${detectedSummary || "  (no known AI tool detected — the user can still use the generic curl example in Phase 4)"}
-
-Selected Inspector surfaces:
-- UI URL: ${selectedUi}
-- Control Base URL: \`${controlBaseUrl}\`
-- Agent Base URL: \`${agentBaseUrl}\`
-- 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
-> continuing. Do not stream past a PAUSE based on context — the user has
-> not seen your output yet. Each PAUSE in the body below includes a sample
-> question you can adapt.
-
----
-
-## Phase 0: Idempotency check
-
-**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 \`${refreshCommand}\` before
-continuing so they are not guided by stale instructions.
-
-\`\`\`bash
-${statusCommand}
-\`\`\`
-
-\`\`\`powershell
-${statusCommand}
-\`\`\`
-
-**DO:** Then probe the three pieces of state this skill touches. Use targeted checks — do **not** read large JSON files into the conversation.
-
-**DO:** ${providerScopeGuidance}
-
-\`\`\`bash
-# 1. Is the backend already up?
-curl -fsS "${healthUrl}" 2>/dev/null && echo "BACKEND: up" || echo "BACKEND: down"
-
-# 2. Does the provider config have a real provider key?
-agent_inspector_data_dir() {
-  base="\${HOME:-/tmp}"
-  if [ -n "\${AGENT_INSPECTOR_DATA_DIR:-}" ]; then
-    case "$AGENT_INSPECTOR_DATA_DIR" in /*) printf '%s\n' "$AGENT_INSPECTOR_DATA_DIR" ;; *) printf '%s\n' "$base/$AGENT_INSPECTOR_DATA_DIR" ;; esac
-  elif [ -n "\${AGENT_INSPECTOR_CONFIG_DIR:-}" ]; then
-    case "$AGENT_INSPECTOR_CONFIG_DIR" in /*) printf '%s\n' "$AGENT_INSPECTOR_CONFIG_DIR" ;; *) printf '%s\n' "$base/$AGENT_INSPECTOR_CONFIG_DIR" ;; esac
-  else
-    printf '%s\n' "$base/.agent-inspector"
-  fi
-}
-DATA_DIR="$(agent_inspector_data_dir)"
-PROVIDERS="$DATA_DIR/providers.json"
-LEGACY_CONFIG="$DATA_DIR/config.json"
-if [ -f "$PROVIDERS" ] || [ -f "$LEGACY_CONFIG" ]; then
-  if grep -qE '"apiKey"[[:space:]]*:[[:space:]]*"sk-[^"]+"' "$PROVIDERS" "$LEGACY_CONFIG" 2>/dev/null; then
-    echo "CONFIG: has key (no REPLACE placeholder)"
-  elif grep -qE '"apiKey"[[:space:]]*:[[:space:]]*"REPLACE' "$PROVIDERS" "$LEGACY_CONFIG" 2>/dev/null; then
-    echo "CONFIG: missing or has placeholder key"
-  else
-    echo "CONFIG: missing or has placeholder key"
-  fi
-else
-  echo "CONFIG: file does not exist"
-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 '"${mcpName}"' "$PROJ_MCP"; then
-  echo "MCP: wired in $PROJ_MCP"
-elif [ -f "$HOME_MCP" ] && grep -q '"${mcpName}"' "$HOME_MCP"; then
-  echo "MCP: wired in $HOME_MCP"
-else
-  echo "MCP: not wired"
-fi
-\`\`\`
-
-\`\`\`powershell
-# Windows PowerShell — single-quoted so $env: expands correctly
-$port = ${port}
-function Resolve-AgentInspectorDataDir {
-  $base = $env:USERPROFILE
-  if (-not $base) { $base = $env:APPDATA }
-  if (-not $base) { $base = 'C:\\' }
-  if ($env:AGENT_INSPECTOR_DATA_DIR) {
-    if ([System.IO.Path]::IsPathRooted($env:AGENT_INSPECTOR_DATA_DIR)) { return $env:AGENT_INSPECTOR_DATA_DIR }
-    return (Join-Path $base $env:AGENT_INSPECTOR_DATA_DIR)
-  }
-  if ($env:AGENT_INSPECTOR_CONFIG_DIR) {
-    if ([System.IO.Path]::IsPathRooted($env:AGENT_INSPECTOR_CONFIG_DIR)) { return $env:AGENT_INSPECTOR_CONFIG_DIR }
-    return (Join-Path $base $env:AGENT_INSPECTOR_CONFIG_DIR)
-  }
-  return (Join-Path $base '.agent-inspector')
-}
-$dataDir = Resolve-AgentInspectorDataDir
-$providers = Join-Path $dataDir 'providers.json'
-$legacyConfig = Join-Path $dataDir 'config.json'
-
-# 1. Is the backend already up?
-try {
-  $null = Invoke-RestMethod -Uri "${healthUrl}" -TimeoutSec 2 -ErrorAction Stop
-  Write-Host 'BACKEND: up'
-} catch {
-  Write-Host 'BACKEND: down'
-}
-
-# 2. Does the config have a real provider key?
-if ((Test-Path $providers) -or (Test-Path $legacyConfig)) {
-  $content = ''
-  if (Test-Path $providers) { $content += Get-Content $providers -Raw }
-  if (Test-Path $legacyConfig) { $content += Get-Content $legacyConfig -Raw }
-  if ($content -match '"apiKey"[[:space:]]*:[[:space:]]*"(sk-[^"]+)"') {
-    Write-Host 'CONFIG: has key'
-  } elseif ($content -match 'REPLACE') {
-    Write-Host 'CONFIG: has placeholder key'
-  } else {
-    Write-Host 'CONFIG: missing key'
-  }
-} else {
-  Write-Host 'CONFIG: file does not exist'
-}
-
-# 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 -SimpleMatch '${mcpName}' -Quiet)) {
-  Write-Host "MCP: wired in $projMcp"
-} elseif ((Test-Path $homeMcp) -and (Select-String -Path $homeMcp -SimpleMatch '${mcpName}' -Quiet)) {
-  Write-Host "MCP: wired in $homeMcp"
-} else {
-  Write-Host 'MCP: not wired'
-}
-\`\`\`
-
-**DO:** Summarize the three checks in one line, then use \`AskUserQuestion\` to ask whether to skip the corresponding phases.
-
-> **PAUSE** — call \`AskUserQuestion\` with:
-> - header: \`Skip done\`
-> - question: \`Proxy/CONFIG/MCP state: <summary>. Skip the phases that are already done?\`
-> - options: \`["Yes, skip what's done", "No, walk me through everything again"]\`
-> Wait for the answer before moving to Preflight.
-
----
-
-## Preflight
-
-**EXPLAIN:** "Quick env sanity check — make sure Node and Claude Code are present."
-
-**DO:** Run the platform-appropriate commands below.
-
-\`\`\`bash
-# Unix / macOS / WSL
-node --version                                       # expect >= 18
-node -e "const fs=require('node:fs'),p=require('node:path');const names=process.platform==='win32'?['claude.cmd','claude.exe','claude']:['claude'];const found=(process.env.PATH||'').split(p.delimiter).some(d=>names.some(n=>fs.existsSync(p.join(d,n))));console.log(found?'claude-code: present':'claude-code: not detected')"
-\`\`\`
-
-\`\`\`powershell
-# Windows PowerShell — single-quoted so $env: expands correctly
-node --version                                       # expect >= 18
-node -e "const fs=require('node:fs'),p=require('node:path');const names=process.platform==='win32'?['claude.cmd','claude.exe','claude']:['claude'];const found=(process.env.PATH||'').split(p.delimiter).some(d=>names.some(n=>fs.existsSync(p.join(d,n))));console.log(found?'claude-code: present':'claude-code: not detected')"
-\`\`\`
-
-> **PAUSE** — if Node is older than 18, ask the user to install a newer version (https://nodejs.org) before continuing. Use \`AskUserQuestion\` with header \`Node version\`.
-
----
-
-## Phase 1: Welcome
-
-**EXPLAIN:**
-
-\`\`\`
-## Welcome to Agent Inspector!
-
-Agent Inspector is an agent observability and knowledge-capture platform for AI coding tools. Its backend owns the transparent model proxy, REST/SSE APIs, capture storage, and MCP server. The default CLI composes a Web UI at the same public Base URL, while \`--backend-only\` keeps every Coding Agent surface available without serving UI files.
-
-Agent Inspector starts in **Simple mode** by default. Simple mode is the right habit for everyday use: it keeps requests, responses, tools, timing, and token usage while avoiding heavier raw headers, raw response, and detailed SSE chunk artifacts. Use **Full mode** only when the user is debugging provider headers, raw response payloads, or SSE stream details.
-
-**What we'll do in the next ~10 minutes:**
-1. Add your first LLM provider (Anthropic or OpenAI key)
-2. Start the proxy in Simple mode
-3. Wire your AI tool to use it
-4. Capture a first request end-to-end
-5. Tour the key UI affordances
-
-Ready? Let's start with the provider.
-\`\`\`
-
-> **PAUSE** — use \`AskUserQuestion\` with header \`Ready?\` and options \`["Yes, let's go", "Wait, I have a question"]\`. Wait for the user before continuing.
-
----
-
-## Phase 2: Provider setup
-
-**DO:** ${providerScopeGuidance}
-
-**EXPLAIN:** "A 'provider' is an upstream LLM endpoint — Anthropic, OpenAI, MiniMax, etc. agent-inspector routes each request to the right upstream based on the model name. You need at least one provider configured for the proxy to forward traffic."
-
-**DO:** First, re-check whether \`<dataDir>/providers.json\` already has a real key (Phase 0 may have raced with a manual edit). Use the same data-dir resolution and \`grep -qE '"apiKey":"sk-'\` (bash) or \`Select-String\` (PowerShell) check from Phase 0. If a real key is present, skip the rest of this phase.
-
-**DO:** If no real key, ask the user for the provider type and API key via \`AskUserQuestion\`. The question should be a free-form text field (no fixed options) — the API key is a secret, so don't echo it back in the question UI.
-
-\`\`\`bash
-# After collecting the key, write the config
-agent_inspector_data_dir() {
-  base="\${HOME:-/tmp}"
-  if [ -n "\${AGENT_INSPECTOR_DATA_DIR:-}" ]; then
-    case "$AGENT_INSPECTOR_DATA_DIR" in /*) printf '%s\n' "$AGENT_INSPECTOR_DATA_DIR" ;; *) printf '%s\n' "$base/$AGENT_INSPECTOR_DATA_DIR" ;; esac
-  elif [ -n "\${AGENT_INSPECTOR_CONFIG_DIR:-}" ]; then
-    case "$AGENT_INSPECTOR_CONFIG_DIR" in /*) printf '%s\n' "$AGENT_INSPECTOR_CONFIG_DIR" ;; *) printf '%s\n' "$base/$AGENT_INSPECTOR_CONFIG_DIR" ;; esac
-  else
-    printf '%s\n' "$base/.agent-inspector"
-  fi
-}
-DATA_DIR="$(agent_inspector_data_dir)"
-mkdir -p "$DATA_DIR"
-PROVIDERS="$DATA_DIR/providers.json"
-NOW="$(date -u +"%Y-%m-%dT%H:%M:%SZ")"
-cat > "$PROVIDERS" <<JSON
-{
-  "providers": [
-    {
-      "id": "onboard-anthropic",
-      "name": "Anthropic",
-      "apiKey": "REPLACE_ME_BEFORE_WRITING",
-      "models": ["claude-sonnet-4-5-20250929"],
-      "format": "anthropic",
-      "anthropicBaseUrl": "https://api.anthropic.com",
-      "openaiBaseUrl": "",
-      "authHeader": "bearer",
-      "createdAt": "$NOW",
-      "updatedAt": "$NOW"
-    }
-  ]
-}
-JSON
-# Then patch the apiKey with the user-provided value (use jq if available)
-\`\`\`
-
-\`\`\`powershell
-# Windows PowerShell — single-quoted so $env: expands correctly
-function Resolve-AgentInspectorDataDir {
-  $base = $env:USERPROFILE
-  if (-not $base) { $base = $env:APPDATA }
-  if (-not $base) { $base = 'C:\\' }
-  if ($env:AGENT_INSPECTOR_DATA_DIR) {
-    if ([System.IO.Path]::IsPathRooted($env:AGENT_INSPECTOR_DATA_DIR)) { return $env:AGENT_INSPECTOR_DATA_DIR }
-    return (Join-Path $base $env:AGENT_INSPECTOR_DATA_DIR)
-  }
-  if ($env:AGENT_INSPECTOR_CONFIG_DIR) {
-    if ([System.IO.Path]::IsPathRooted($env:AGENT_INSPECTOR_CONFIG_DIR)) { return $env:AGENT_INSPECTOR_CONFIG_DIR }
-    return (Join-Path $base $env:AGENT_INSPECTOR_CONFIG_DIR)
-  }
-  return (Join-Path $base '.agent-inspector')
-}
-$dir  = Resolve-AgentInspectorDataDir
-$file = Join-Path $dir 'providers.json'
-New-Item -ItemType Directory -Force -Path $dir | Out-Null
-$now = (Get-Date).ToUniversalTime().ToString('o')
-$json = @{
-  providers = @(
-    @{
-      id = 'onboard-anthropic'
-      name = 'Anthropic'
-      apiKey = 'REPLACE_ME_BEFORE_WRITING'
-      models = @('claude-sonnet-4-5-20250929')
-      format = 'anthropic'
-      anthropicBaseUrl = 'https://api.anthropic.com'
-      openaiBaseUrl = ''
-      authHeader = 'bearer'
-      createdAt = $now
-      updatedAt = $now
-    }
-  )
-} | ConvertTo-Json -Depth 5
-$json | Set-Content -Path $file -Encoding UTF8
-# Then patch the apiKey with the user-provided value
-\`\`\`
-
-**DO:** Patch the placeholder with the actual key using \`jq\` (preferred) or a simple \`sed\`. Then read the file back to confirm the key is no longer \`REPLACE_ME_BEFORE_WRITING\`.
-
-**DO:** If the user declines to provide a key in the AskUserQuestion (selects "Skip for now"), do **not** write a placeholder config. Tell the user that Phase 5 (First capture) will be skipped, and that they can re-run the skill after adding a key.
-
-> **PAUSE** — use \`AskUserQuestion\` with header \`Provider key\` and options \`["Key is in, continue", "Skip for now, I'll add it later"]\`. Wait for the answer.
-
----
-
-## Phase 3: Start proxy
-
-**EXPLAIN:** "${startExplanation}"
-
-**DO:** Skip this phase entirely if the Phase 0 health check already reported \`BACKEND: up\` and the user opted to skip done phases.
-
-**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
-${bashStartSnippet}
-\`\`\`
-
-\`\`\`powershell
-# Windows PowerShell
-${powershellStartSnippet}
-\`\`\`
-
-Then wait for the selected backend health URL to be ready:
-
-\`\`\`bash
-for i in $(seq 1 20); do
-  curl -fsS "${healthUrl}" >/dev/null 2>&1 && echo "ready" && break
-  sleep 0.5
-done
-\`\`\`
-
-**DO:** Hit the health endpoint to confirm the backend is alive:
-
-\`\`\`bash
-curl -sS "${healthUrl}"
-\`\`\`
-
-**DO:** Read the token-free runtime discovery document. Report \`deploymentMode\` and capabilities; do not treat \`backend-only\` as a failure or infer that a UI is present.
-
-\`\`\`bash
-curl -sS "${runtimeUrl}"
-\`\`\`
-
-**DO:** Read \`/api/config\` and tell the user which capture mode is active. If deeper capture is required, offer \`${fullModeCommand}\`.
-
-\`\`\`bash
-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.
-
----
-
-## Phase 4: Wire tool
-
-**EXPLAIN:** "Now we tell your AI tool to send traffic through the proxy instead of directly to the upstream API. The exact env var depends on which tool you have."
-
-**DO:** Based on the \`Environment detected\` block at the top of this skill, print the matching wiring command. Examples for each supported tool:
-
-\`\`\`bash
-# Claude Code
-export ANTHROPIC_BASE_URL=${anthropicProxyUrl}
-claude
-
-# OpenCode
-export LLM_BASE_URL=${openAiProxyUrl}
-opencode
-
-# MiMo Code
-export OPENAI_BASE_URL=${openAiProxyUrl}
-mimo
-
-# 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
-than Agent Inspector, \`localhost\` points at the tool's own environment. Replace \`localhost\` with
-an Inspector address reachable from that environment, then verify the network/firewall path before
-debugging provider credentials.
-
-For a tool that wasn't auto-detected, fall through to the generic curl test in the next phase — the user can wire their tool later.
-
-> **PAUSE** — use \`AskUserQuestion\` with header \`Tool wired?\` and options \`["Yes, env var is set, claude is running", "No, I'm going to use the curl test instead"]\`. Wait for the answer.
-
----
-
-## Phase 4.5: Wire MCP server
-
-**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 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": {
-    "${mcpName}": {
-      "type": "http",
-      "url": "${mcpUrl}"
-    }
-  }
-}
-\`\`\`
-
-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 "${mcpUrl}" \\
-  -H "Content-Type: application/json" \\
-  -H "Accept: application/json, text/event-stream" \\
-  -d '{
-    "jsonrpc": "2.0",
-    "id": 1,
-    "method": "initialize",
-    "params": {
-      "protocolVersion": "2025-03-26",
-      "capabilities": {},
-      "clientInfo": { "name": "onboard-check", "version": "0" }
-    }
-  }' | grep -o '"name":"agent-inspector"' && echo "handshake OK"
-\`\`\`
-
-The \`grep -o '"name":"agent-inspector"'\` extracts only the serverInfo name — do not dump the full response. If the server returns session IDs, store the \`mcp-session-id\` header from the first response and use it for the follow-up \`tools/list\` call.
-
-> **PAUSE** — use \`AskUserQuestion\` with header \`MCP OK?\` and options \`["Yes, handshake returned 200", "No, the call failed"]\`. Wait for the answer.
-
----
-
-## Phase 5: First capture
-
-**EXPLAIN:** "Let's prove the proxy works end-to-end. We'll send one real request through it and confirm the log shows up in the API."
-
-**DO:** First, re-check the config. If the \`apiKey\` is still a \`REPLACE_ME_BEFORE_WRITING\` placeholder (user opted out in Phase 2), **skip the capture test** and tell the user to fill in their key and re-run the skill. A 401 from the upstream is fine if they did provide a real key — the proxy will still log the request.
-
-Fire a minimal Anthropic-format request through the proxy:
-
-\`\`\`bash
-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}" \\
-  -d '{"model":"claude-3-5-sonnet-20241022","max_tokens":1,"messages":[{"role":"user","content":"ping"}]}' \\
-  -o /tmp/agent-inspector-capture.json -w 'STATUS:%{http_code}\\n'
-\`\`\`
-
-**DO:** Poll the logs API for up to 5 seconds. A 200 with at least one entry means the request reached the proxy:
-
-\`\`\`bash
-for i in $(seq 1 10); do
-  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"
-    echo "$resp" | head -c 400
-    break
-  fi
-  sleep 0.5
-done
-\`\`\`
-
-**DO:** Diagnose the response based on the actual status and body. **Do not** default to "auth failure" for every 4xx.
-
-| Status | Body hint | Meaning |
-|--------|-----------|---------|
-| 200 | normal | Real success — the upstream returned data |
-| 401 | \`"unauthorized"\` or similar | Upstream rejected the key (expected with a test key) |
-| 403 | \`"Request not allowed"\` | **Proxy's allowlist** — not an auth failure, the proxy rejected the model/config. Show the user the proxy log. |
-| 403 | other text | Could be upstream ACL — different problem |
-| 5xx | anything | Upstream network error |
-
-> **PAUSE** — use \`AskUserQuestion\` with header \`Captured?\` and options matching the diagnosis above. Wait for the answer.
-
----
-
-## Phase 6: Tour & wrap
-
-**EXPLAIN:** "Everything's working. Here's the cheat sheet for the backend surfaces and the optional Web UI:"
-
-- **Runtime discovery**: \`${runtimeUrl}\` — token-free deployment mode, UI Base Path, control/agent Base URLs, and capabilities.
-- **Web UI**: ${uiTour}.
-- **MCP server**: \`${mcpUrl}\` — connect from the coding agent to query logs, replay, and test providers; it does not require a Web UI process.
-- **REST API**: \`/api/logs\`, \`/api/sessions\`, \`/api/providers\` — for scripting and shell-based inspection.
-- **Stop the proxy**:
-
-  \`\`\`bash
-${stopSnippet}
-  \`\`\`
-
-- **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; do not depend on a UI footer being available.
-
-> **PAUSE** — use \`AskUserQuestion\` with header \`All set?\` and options \`["All set, I'm done", "Wait, I want to revisit a phase"]\`. Wait for the answer.
-
-You're done. Happy inspecting.
-`;
-}