@respan/cli 0.9.0 → 0.11.0

package/dist/commands/setup/index.js

@@ -1,929 +1,33 @@
-import * as fs from 'node:fs';
-import * as path from 'node:path';
-import * as os from 'node:os';
-import { execSync, spawnSync } from 'node:child_process';
 import { Flags } from '@oclif/core';
-import { input, select, confirm } from '@inquirer/prompts';
-import { BaseCommand } from '../../lib/base-command.js';
-import { printBanner } from '../../lib/banner.js';
-import { findProjectRoot, writeTextFile, readTextFile, ensureDir, } from '../../lib/integrate.js';
-import { createSpinner } from '../../lib/spinner.js';
-// ── Shared skill content (same for all agents) ────────────────────────
-// ── Skill files ────────────────────────────────────────────────────────
-const SKILL_MD = `# Respan
-
-Use the Respan CLI and SDK for LLM observability — tracing, evals, prompts, datasets, and gateway routing.
-
-## When To Use
-
-- The user asks to **set up Respan** or **add tracing** → read [references/setup.md](references/setup.md)
-- The user asks about **traces, logs, prompts, datasets, evals** → read [references/platform.md](references/platform.md)
-- The user asks about **gateway routing** or **proxying LLM calls** → read [references/gateway.md](references/gateway.md)
-- You need to run a Respan CLI command → check [references/platform.md](references/platform.md) for command reference
-
-## Core Principles
-
-1. **Documentation First**: Always fetch current docs before implementing. Respan updates frequently. See docs access methods below.
-2. **CLI for Data Access**: Use \`respan\` CLI when querying/modifying Respan data.
-3. **Check References**: Read the relevant reference file before implementing any workflow.
-
-## Quick Reference
-
-| Task | Command / Action |
-|------|-----------------|
-| Set up SDK tracing | Follow [references/setup.md](references/setup.md) |
-| List traces | \`respan traces list --limit 10\` |
-| View a trace | \`respan traces get <id>\` |
-| List prompts | \`respan prompts list\` |
-| Create dataset | \`respan datasets create --name <name>\` |
-| Run evaluator | \`respan evaluators run <id>\` |
-| Check auth | \`respan auth status\` |
-| View logs | \`respan logs list --limit 10\` |
-
-## Documentation Access
-
-Three methods to access Respan docs, in order of preference:
-
-### 1. Documentation Index (llms.txt)
-
-Fetch the full index of all doc pages:
-\`https://www.respan.ai/docs/llms.txt\`
-
-Use this to discover the right page for a topic, then fetch that page directly.
-
-### 2. Fetch Individual Pages as Markdown
-
-Any integration or SDK doc page can be fetched by changing \`.mdx\` to \`.md\`:
-\`https://respan.ai/docs/integrations/openai-sdk.md\`
-\`https://respan.ai/docs/sdks/typescript-sdk/overview.md\`
-
-### 3. Platform
-
-View traces, logs, and analytics at: \`https://platform.respan.ai\`
-`;
-const GATEWAY_MD = `# Respan Gateway
-
-Route LLM calls through the Respan proxy for logging, caching, key management, and model switching.
-
-## Setup
-
-Point the LLM client's base URL at the Respan gateway. The API key authenticates both the proxy and tracing.
-
-### TypeScript
-
-\`\`\`typescript
-import OpenAI from "openai";
-
-const client = new OpenAI({
-  apiKey: process.env.RESPAN_API_KEY,
-  baseURL: process.env.RESPAN_BASE_URL || "https://api.respan.ai/api",
-});
-\`\`\`
-
-### Python
-
-\`\`\`python
-import os
-from openai import OpenAI
-
-client = OpenAI(
-    api_key=os.environ["RESPAN_API_KEY"],
-    base_url=os.getenv("RESPAN_BASE_URL", "https://api.respan.ai/api"),
-)
-\`\`\`
-
-## Gateway + Tracing (Both)
-
-Combine SDK tracing and gateway routing — initialize Respan for tracing AND point the LLM client at the gateway.
-
-## Features
-
-- **Unified key management** — one API key for all providers
-- **Caching** — cache repeated LLM calls
-- **Fallbacks** — automatic failover between providers
-- **Cost tracking** — per-request cost logging
-- **Model switching** — swap models without code changes
-
-## Docs
-
-- Quickstart: \`https://respan.ai/docs/documentation/features/gateway/gateway-quickstart.md\`
-- Advanced: \`https://respan.ai/docs/documentation/features/gateway/advanced.md\`
-- Provider setup: \`https://respan.ai/docs/integrations/providers/openai.md\`
-`;
-const PLATFORM_MD = `# Respan Platform
-
-Use the Respan CLI and platform for traces, logs, prompts, datasets, evaluations, and monitoring.
-
-## CLI Commands
-
-### Auth
-\`\`\`bash
-respan auth login          # Log in (browser or API key)
-respan auth status         # Check current auth
-respan auth logout         # Log out
-respan whoami              # Show current user
-\`\`\`
-
-### Traces
-\`\`\`bash
-respan traces list --limit 10          # List recent traces
-respan traces get <trace-id>           # Get trace details
-respan traces summary                  # Trace summary stats
-\`\`\`
-
-### Logs
-\`\`\`bash
-respan logs list --limit 10            # List recent logs
-respan logs get <log-id>               # Get log details
-respan logs summary                    # Log summary stats
-respan logs create --data '{...}'      # Create a log entry
-\`\`\`
-
-### Prompts
-\`\`\`bash
-respan prompts list                    # List all prompts
-respan prompts get <id>                # Get prompt details
-respan prompts create --name <name>    # Create a prompt
-respan prompts update <id>             # Update a prompt
-respan prompts versions <id>           # List prompt versions
-\`\`\`
-
-### Datasets
-\`\`\`bash
-respan datasets list                   # List datasets
-respan datasets create --name <name>   # Create a dataset
-respan datasets get <id>               # Get dataset details
-respan datasets spans <id>             # List dataset spans
-respan datasets add-spans <id>         # Add spans to dataset
-\`\`\`
-
-### Evaluators
-\`\`\`bash
-respan evaluators list                 # List evaluators
-respan evaluators get <id>             # Get evaluator details
-respan evaluators create               # Create an evaluator
-respan evaluators run <id>             # Run an evaluator
-\`\`\`
-
-### Experiments
-\`\`\`bash
-respan experiments list                # List experiments
-respan experiments get <id>            # Get experiment details
-respan experiments create              # Create an experiment
-\`\`\`
-
-### Integration (CLI agent tracing)
-\`\`\`bash
-respan integrate claude-code           # Trace Claude Code conversations
-respan integrate codex-cli             # Trace Codex CLI conversations
-respan integrate gemini-cli            # Trace Gemini CLI conversations
-respan integrate opencode              # Trace OpenCode conversations
-respan integrate <tool> --disable      # Disable tracing
-\`\`\`
-
-### Config
-\`\`\`bash
-respan config list                     # List all config
-respan config get <key>                # Get config value
-respan config set <key> <value>        # Set config value
-\`\`\`
-
-## Platform Features
-
-- **Traces** — structured spans showing LLM call hierarchy, inputs/outputs, tokens, cost
-- **Logs** — request-level logging with metadata
-- **Prompts** — version-controlled prompt templates with deployment
-- **Datasets** — curated test data for evaluations
-- **Evaluators** — automated scoring/grading of LLM outputs
-- **Experiments** — run evals over datasets and compare results
-- **Monitors** — metric-based alerts for production regressions
-- **Views** — saved filters for quick access
-
-## Docs
-
-- Tracing concepts: \`https://respan.ai/docs/documentation/features/tracing/concepts.md\`
-- Evals concepts: \`https://respan.ai/docs/documentation/features/evals/concepts.md\`
-- Prompts: \`https://respan.ai/docs/documentation/features/prompt-management/prompt-management-quickstart.md\`
-- Monitoring: \`https://respan.ai/docs/documentation/features/monitoring/metrics.md\`
-- Full docs: \`https://www.respan.ai/docs/llms.txt\`
-`;
-const SETUP_MD = `# Respan Setup
-
-Use this skill when the user asks to set up Respan tracing in their project.
-
-## Hard Rules
-
-- **Interactive mode:** Ask the user questions when you need input. Do not assume.
-- **Only add Respan code.** Do not refactor or modify unrelated code.
-- **Pin exact versions.** Never use \`latest\` or unpinned ranges.
-- **Do not guess APIs.** Use only the patterns from the integration docs linked below.
-- **If Respan is already installed/configured, do not duplicate work.** Check for existing \`respan\` imports first.
-- **Read the code before proposing changes.** Understand the actual workflow, not just the dependencies.
-
-## Context
-
-The API key is stored in \`.env\` as \`RESPAN_API_KEY\`.
-Full docs index: \`https://www.respan.ai/docs/llms.txt\`
-
-## Steps
-
-### 1. Analyze the Project
-
-**1a. Detect language and package manager:**
-- Check \`package.json\` (JS/TS) or \`pyproject.toml\` / \`requirements.txt\` (Python)
-- Detect package manager from lock files
-
-**1b. Detect libraries in priority order:**
-
-Check higher-priority categories first. If a match is found, use that instrumentation — do NOT also add lower-level SDK instrumentation.
-
-**Priority 1 — Agent Frameworks & High-Level SDKs:**
-
-| Library | Python package | JS/TS package | Respan instrumentation (Python) | Respan instrumentation (JS/TS) | Docs |
-|---------|---------------|---------------|--------------------------------|-------------------------------|------|
-| Vercel AI SDK | — | \`ai\` | — | \`@respan/instrumentation-vercel\` | [docs](https://respan.ai/docs/integrations/vercel-ai-sdk.md) |
-| OpenAI Agents SDK | \`openai-agents\` | \`@openai/agents\` | \`respan-instrumentation-openai-agents\` | \`@respan/instrumentation-openai-agents\` | [docs](https://respan.ai/docs/integrations/openai-agents-sdk.md) |
-| Claude Agent SDK | \`claude-agent-sdk\` | — | \`respan-instrumentation-claude-agent-sdk\` | — | [docs](https://respan.ai/docs/integrations/claude-agents-sdk.md) |
-| Pydantic AI | \`pydantic-ai\` | — | \`respan-instrumentation-pydantic-ai\` | — | [docs](https://respan.ai/docs/integrations/pydantic-ai.md) |
-| LangChain | \`langchain\` | \`langchain\` | via OpenInference | — | [docs](https://respan.ai/docs/integrations/langchain.md) |
-| LangGraph | \`langgraph\` | — | via OpenInference | — | [docs](https://respan.ai/docs/integrations/langgraph.md) |
-| CrewAI | \`crewai\` | — | via OpenInference | — | [docs](https://respan.ai/docs/integrations/crewai.md) |
-| LlamaIndex | \`llama-index\` | — | via OpenInference | — | [docs](https://respan.ai/docs/integrations/llama-index.md) |
-| Haystack | \`haystack-ai\` | — | via exporter | — | [docs](https://respan.ai/docs/integrations/haystack.md) |
-| Mastra | — | \`mastra\` | — | via OTEL | [docs](https://respan.ai/docs/integrations/mastra.md) |
-| Google ADK | \`google-adk\` | — | via OpenInference | — | [docs](https://respan.ai/docs/integrations/google-adk.md) |
-
-If a Priority 1 framework is found, use its instrumentation. Do NOT also add Priority 2 instrumentation for the same provider.
-
-**Priority 2 — Direct LLM SDKs** (only if no P1 framework covers this provider):
-
-These are **auto-instrumented** — just \`Respan()\` / \`new Respan()\`, no extra packages needed:
-
-| Library | Python package | JS/TS package | Docs |
-|---------|---------------|---------------|------|
-| OpenAI SDK | \`openai\` | \`openai\` | [docs](https://respan.ai/docs/integrations/openai-sdk.md) |
-| Anthropic SDK | \`anthropic\` | \`@anthropic-ai/sdk\` | [docs](https://respan.ai/docs/integrations/anthropic.md) |
-| Azure OpenAI | \`openai\` (azure config) | \`openai\` | [docs](https://respan.ai/docs/integrations/providers/azure.md) |
-| Google Vertex AI | \`google-cloud-aiplatform\` | — | [docs](https://respan.ai/docs/integrations/vertex-ai.md) |
-| AWS Bedrock | \`boto3\` | — | [docs](https://respan.ai/docs/integrations/aws-bedrock.md) |
-| Cohere | \`cohere\` | — | [docs](https://respan.ai/docs/integrations/providers/cohere.md) |
-| Together AI | \`together\` | — | [docs](https://respan.ai/docs/integrations/together-ai.md) |
-
-**Note:** LiteLLM in JS uses the OpenAI-compatible API, so the OpenAI auto-instrument covers it. For Python LiteLLM, see [LiteLLM guide](https://respan.ai/docs/integrations/litellm.md). For Google GenAI (\`@google/genai\`), see [Google GenAI guide](https://respan.ai/docs/integrations/google-genai.md).
-
-**1c. Read the actual code and understand the workflow:**
-
-This is the most important step. Read the entrypoint and all files that make LLM calls. Map out:
-
-- What is the **overall workflow**? (e.g. "user sends question → retrieve context → generate answer → format response")
-- What are the **individual steps/tasks**? (e.g. "embed query", "search DB", "call GPT", "parse output")
-- Are there **agent loops**? (e.g. a loop that calls tools until done)
-- Are there **tool calls**? (e.g. functions the LLM invokes)
-
-### 2. Propose an Implementation Plan
-
-Present the user with a concrete plan before making any changes. The plan should include:
-
-**a) Packages to install** — core SDK + instrumentation package (with exact versions)
-
-**b) Initialization code** — where to add it (which file, which line)
-
-**c) Workflow structure** — how to wrap the existing code:
-
-For **agent frameworks** (Priority 1): The framework instrumentation auto-captures the workflow structure. Usually just need init code, no manual wrapping needed. Fetch and follow the integration doc.
-
-For **direct LLM SDKs** (Priority 2): Individual LLM calls will be auto-traced as flat spans. Propose wrapping the logical workflow with Respan decorators/wrappers to get structured nested traces:
-
-TypeScript example:
-\`\`\`typescript
-// Before: flat traces — each LLM call is an isolated span
-const outline = await openai.chat.completions.create({...});
-const draft = await openai.chat.completions.create({...});
-
-// After: structured traces — nested spans showing the workflow
-const result = await withWorkflow({ name: "write_article" }, async () => {
-  const outline = await withTask({ name: "generate_outline" }, async () => {
-    return await openai.chat.completions.create({...});
-  });
-  const draft = await withTask({ name: "write_draft" }, async () => {
-    return await openai.chat.completions.create({...});
-  });
-  return draft;
-});
-\`\`\`
-
-Python example:
-\`\`\`python
-# Before: flat traces
-outline = client.chat.completions.create(...)
-draft = client.chat.completions.create(...)
-
-# After: structured traces
-@workflow(name="write_article")
-def write_article(topic):
-    outline = generate_outline(topic)
-    return write_draft(outline)
-
-@task(name="generate_outline")
-def generate_outline(topic):
-    return client.chat.completions.create(...)
-
-@task(name="write_draft")
-def write_draft(outline):
-    return client.chat.completions.create(...)
-\`\`\`
-
-**Ask the user which approach they prefer:**
-1. **Auto-trace only** — just add init code, every LLM call is automatically captured as a flat span. Zero code changes beyond initialization. Good for quick setup or simple projects.
-2. **Structured traces** — wrap existing code with workflow/task decorators for nested spans showing how the app flows. Better for complex projects with multiple LLM calls.
-
-If the user picks option 1, skip the wrappers entirely — just install + init code.
-
-If the user picks option 2:
-- **If multiple independent workflows are detected** (e.g. \`writeArticle()\`, \`summarizeDoc()\`, \`classifyEmail()\`), list them and ask which ones to instrument. Don't assume all of them.
-- **Show the user what the trace will look like** — describe the span hierarchy:
-\`\`\`
-workflow: write_article
-  ├── task: generate_outline
-  │     └── llm: openai.chat (auto-captured)
-  └── task: write_draft
-        └── llm: openai.chat (auto-captured)
-\`\`\`
-
-Wait for user confirmation before proceeding.
-
-### 3. Implement
-
-**a) Install packages:**
-
-For direct LLM SDKs (Priority 2) — just the core SDK:
-\`\`\`bash
-# Python
-pip install respan-ai
-
-# TypeScript
-npm install @respan/respan
-\`\`\`
-
-For agent frameworks (Priority 1) — also install the instrumentor. Check the docs link in the table above for the exact packages.
-
-**b) Add initialization code** — at the top of the entrypoint, before any LLM client is created:
-
-For **direct LLM SDKs** (auto-instrumented):
-\`\`\`python
-# Python
-from respan import Respan
-Respan()
-\`\`\`
-\`\`\`typescript
-// TypeScript
-import { Respan } from "@respan/respan";
-const respan = new Respan();
-await respan.initialize();
-\`\`\`
-
-For **agent frameworks** (explicit instrumentor — fetch the docs URL from the table for the exact pattern):
-\`\`\`python
-# Python example (OpenAI Agents)
-from respan import Respan
-from respan_instrumentation_openai_agents import OpenAIAgentsInstrumentor
-Respan(instrumentations=[OpenAIAgentsInstrumentor()])
-\`\`\`
-\`\`\`typescript
-// TypeScript example (OpenAI Agents)
-import { Respan } from "@respan/respan";
-import { OpenAIAgentsInstrumentor } from "@respan/instrumentation-openai-agents";
-const respan = new Respan({ instrumentations: [new OpenAIAgentsInstrumentor()] });
-await respan.initialize();
-\`\`\`
-
-**c) Add workflow wrappers** — if the user chose structured traces in the plan.
-
-### 4. Verify
-
-Run the application and confirm:
-- The app runs without errors
-- Traces appear at https://platform.respan.ai or via \`respan traces list --limit 5\`
-- If wrappers were added, verify the trace shows the expected nested span hierarchy
-`;
-// ── Constants ──────────────────────────────────────────────────────────
-const PC = '\x1b[38;2;100;131;240m';
-const RESET = '\x1b[0m';
-const DIM = '\x1b[2m';
-const GREEN = '\x1b[32m';
-const BOLD = '\x1b[1m';
-const CLI_TOOLS = {
-    'claude-code': {
-        name: 'Claude Code',
-        binary: 'claude',
-        description: 'Anthropic\'s coding agent',
-        configDirs: ['~/.claude', '.claude'],
-        agentSkillsDir: '.claude',
-    },
-    'cursor': {
-        name: 'Cursor',
-        binary: 'cursor',
-        description: 'AI-powered code editor',
-        configDirs: ['.cursor', '.cursorrc'],
-        agentSkillsDir: '.cursor',
-    },
-    'codex-cli': {
-        name: 'Codex CLI',
-        binary: 'codex',
-        description: 'OpenAI\'s coding agent',
-        configDirs: ['~/.codex', '.codex'],
-        agentSkillsDir: '.codex',
-    },
-    'gemini-cli': {
-        name: 'Gemini CLI',
-        binary: 'gemini',
-        description: 'Google\'s coding agent',
-        configDirs: ['~/.gemini', '.gemini'],
-        agentSkillsDir: '.gemini',
-    },
-    'opencode': {
-        name: 'OpenCode',
-        binary: 'opencode',
-        description: 'Open-source coding agent',
-        configDirs: ['.opencode'],
-        agentSkillsDir: '.opencode',
-    },
-};
-class Setup extends BaseCommand {
+import { SetupBaseCommand } from '../../lib/setup-base-command.js';
+class Setup extends SetupBaseCommand {
     async run() {
         const { flags } = await this.parse(Setup);
         this.globalFlags = flags;
-        await printBanner();
-        const projectRoot = findProjectRoot();
-        const home = os.homedir();
-        // ── Step 1: API Key ──────────────────────────────────────────────
-        this.logStep(1, 'API Key');
-        const apiKey = await this.askApiKey(projectRoot);
-        await this.verifyApiKey(apiKey);
-        // ── Step 2: Choose agent ─────────────────────────────────────────
-        this.logStep(2, 'Choose your coding agent');
-        const detected = this.detectAgents(projectRoot, home);
-        const selectedTool = await this.selectAgent(flags.agent, detected);
-        if (!selectedTool) {
-            this.log(`  ${DIM}No agent selected. You can always run ${RESET}respan setup${DIM} again.${RESET}`);
-            return;
-        }
-        // ── Step 3: Install skill ────────────────────────────────────────
-        this.logStep(3, 'Install skill');
-        await this.installSkill(selectedTool, projectRoot);
-        // ── Done ─────────────────────────────────────────────────────────
-        this.log('');
-        this.log(`  ${GREEN}${BOLD}Setup complete!${RESET}`);
-        this.log('');
-        this.log(`  ${DIM}Your API key is saved in ${RESET}.env`);
-        this.log(`  ${DIM}Respan skill installed for all agents${RESET}`);
-        this.log(`  ${DIM}View traces at ${RESET}https://platform.respan.ai`);
-        this.log('');
-        this.notifySetup(this.getGitEmail()).catch(() => { });
-        // ── Step 4: Open agent ───────────────────────────────────────────
-        const shouldInstrument = !flags['no-instrument'];
-        if (shouldInstrument) {
-            await this.runInstrumentAgent(selectedTool, projectRoot);
-        }
-    }
-    // ── Step 1: API Key ──────────────────────────────────────────────────
-    async askApiKey(projectRoot) {
-        const envPath = path.join(projectRoot, '.env');
-        const existingEnv = readTextFile(envPath);
-        const existingKey = this.extractEnvVar(existingEnv, 'RESPAN_API_KEY');
-        if (existingKey) {
-            const masked = existingKey.slice(0, 8) + '...' + existingKey.slice(-4);
-            this.log(`  ${PC}Found existing API key:${RESET} ${masked}`);
-            const keep = await confirm({
-                message: 'Keep this API key?',
-                default: true,
-            });
-            if (keep)
-                return existingKey;
-        }
-        this.log('');
-        this.log(`  ${DIM}Get your API key at ${RESET}https://platform.respan.ai/settings/api-keys`);
-        this.log('');
-        const apiKey = await input({
-            message: 'Enter your Respan API key:',
-            validate: (val) => val.trim().length > 0 || 'API key is required',
-        });
-        this.saveToEnv(envPath, existingEnv, 'RESPAN_API_KEY', apiKey.trim());
-        this.log(`  ${GREEN}\u2713${RESET} Saved API key to ${DIM}${envPath}${RESET}`);
-        return apiKey.trim();
-    }
-    async verifyApiKey(apiKey) {
-        const spinner = createSpinner('Verifying API key');
-        spinner.start();
-        try {
-            const email = this.getGitEmail();
-            const payload = this.buildDemoTrace(email);
-            const response = await fetch('https://api.respan.ai/api/v2/traces', {
-                method: 'POST',
-                headers: {
-                    'Authorization': `Bearer ${apiKey}`,
-                    'Content-Type': 'application/json',
-                },
-                body: JSON.stringify(payload),
-            });
-            if (response.ok) {
-                spinner.succeed('API key verified');
-                this.log('');
-                this.log(`  ${PC}A demo trace has been sent to your account.${RESET}`);
-                this.log(`  ${DIM}View it at ${RESET}https://platform.respan.ai${DIM} to see what Respan traces look like.${RESET}`);
-                this.log('');
-                await confirm({ message: 'Ready to continue?', default: true });
-            }
-            else if (response.status === 401 || response.status === 403) {
-                spinner.fail('Invalid API key');
-                this.warn('  Check your key at https://platform.respan.ai/settings/api-keys');
-            }
-            else {
-                spinner.fail(`Verification failed (status: ${response.status})`);
-                this.warn('  Setup will continue — verify manually at https://platform.respan.ai');
-            }
-        }
-        catch {
-            spinner.fail('Could not verify API key (network error)');
-            this.warn('  Setup will continue — verify manually at https://platform.respan.ai');
-        }
-    }
-    /**
-     * Build a rich demo OTLP trace that mimics a customer support agent workflow:
-     *   workflow: customer_support_pipeline
-     *     └── agent: support_agent
-     *           ├── tool: lookup_order
-     *           ├── chat: openai.chat (classify intent)
-     *           ├── tool: process_refund
-     *           ├── chat: openai.chat (generate response)
-     *           └── task: log_resolution
-     */
-    buildDemoTrace(email) {
-        const randHex = (len) => Array.from({ length: len }, () => Math.floor(Math.random() * 16).toString(16)).join('');
-        const traceId = randHex(32);
-        const ns = (ms) => `${ms}000000`;
-        const now = Date.now();
-        const attr = (key, val) => ({ key, value: { stringValue: val } });
-        const intAttr = (key, val) => ({ key, value: { intValue: String(val) } });
-        const spans = [
-            // 1. Workflow (root)
-            {
-                traceId, spanId: randHex(16),
-                name: 'respan-setup (demo)', kind: 1,
-                startTimeUnixNano: ns(now), endTimeUnixNano: ns(now + 8000),
-                attributes: [
-                    attr('respan.entity.log_type', 'workflow'),
-                    attr('traceloop.entity.name', 'respan-setup (demo)'),
-                    attr('traceloop.entity.input', '{"query": "My order #12345 hasn\'t arrived yet", "customer_id": "cust_789"}'),
-                    attr('traceloop.entity.output', '{"status": "resolved", "action": "refund_initiated", "ticket_id": "TKT-001"}'),
-                ],
-                status: { code: 1 },
-                _spanId: 'workflow',
-            },
-            // 2. Agent (child of workflow)
-            {
-                traceId, spanId: randHex(16), parentSpanId: '', // filled below
-                name: 'customer_support_agent', kind: 1,
-                startTimeUnixNano: ns(now + 100), endTimeUnixNano: ns(now + 7500),
-                attributes: [
-                    attr('respan.entity.log_type', 'agent'),
-                    attr('traceloop.entity.name', 'customer_support_agent'),
-                    attr('traceloop.entity.input', '[{"role": "user", "content": "My order #12345 hasn\'t arrived yet"}]'),
-                    attr('traceloop.entity.output', '{"role": "assistant", "content": "I\'ve looked into your order #12345. It appears there was a shipping delay. I\'ve initiated a refund for you."}'),
-                ],
-                status: { code: 1 },
-                _spanId: 'agent', _parentRef: 'workflow',
-            },
-            // 3. Tool: lookup_order (child of agent)
-            {
-                traceId, spanId: randHex(16), parentSpanId: '',
-                name: 'lookup_order', kind: 1,
-                startTimeUnixNano: ns(now + 200), endTimeUnixNano: ns(now + 1200),
-                attributes: [
-                    attr('respan.entity.log_type', 'tool'),
-                    attr('traceloop.entity.name', 'lookup_order'),
-                    attr('traceloop.entity.input', '{"order_id": "12345"}'),
-                    attr('traceloop.entity.output', '{"order_id": "12345", "status": "delayed", "items": ["Widget A", "Widget B"]}'),
-                ],
-                status: { code: 1 },
-                _spanId: 'tool1', _parentRef: 'agent',
-            },
-            // 4. Chat: classify intent (child of agent)
-            {
-                traceId, spanId: randHex(16), parentSpanId: '',
-                name: 'openai.chat', kind: 1,
-                startTimeUnixNano: ns(now + 1300), endTimeUnixNano: ns(now + 3000),
-                attributes: [
-                    attr('respan.entity.log_type', 'chat'),
-                    attr('llm.request.type', 'chat'),
-                    attr('gen_ai.system', 'openai'),
-                    attr('gen_ai.request.model', 'gpt-4o-mini'),
-                    attr('gen_ai.response.model', 'gpt-4o-mini'),
-                    intAttr('gen_ai.usage.prompt_tokens', 145),
-                    intAttr('gen_ai.usage.completion_tokens', 38),
-                    attr('traceloop.entity.input', '[{"role": "system", "content": "Classify the customer intent."}, {"role": "user", "content": "My order #12345 hasn\'t arrived yet"}]'),
-                    attr('traceloop.entity.output', '{"role": "assistant", "content": "intent: order_status_inquiry, sentiment: frustrated"}'),
-                ],
-                status: { code: 1 },
-                _spanId: 'chat1', _parentRef: 'agent',
-            },
-            // 5. Tool: process_refund (child of agent)
-            {
-                traceId, spanId: randHex(16), parentSpanId: '',
-                name: 'process_refund', kind: 1,
-                startTimeUnixNano: ns(now + 3100), endTimeUnixNano: ns(now + 4500),
-                attributes: [
-                    attr('respan.entity.log_type', 'tool'),
-                    attr('traceloop.entity.name', 'process_refund'),
-                    attr('traceloop.entity.input', '{"order_id": "12345", "reason": "shipping_delay"}'),
-                    attr('traceloop.entity.output', '{"refund_id": "REF-789", "amount": 49.99, "status": "initiated"}'),
-                ],
-                status: { code: 1 },
-                _spanId: 'tool2', _parentRef: 'agent',
-            },
-            // 6. Chat: generate response (child of agent)
-            {
-                traceId, spanId: randHex(16), parentSpanId: '',
-                name: 'openai.chat', kind: 1,
-                startTimeUnixNano: ns(now + 4600), endTimeUnixNano: ns(now + 6800),
-                attributes: [
-                    attr('respan.entity.log_type', 'chat'),
-                    attr('llm.request.type', 'chat'),
-                    attr('gen_ai.system', 'openai'),
-                    attr('gen_ai.request.model', 'gpt-4o-mini'),
-                    attr('gen_ai.response.model', 'gpt-4o-mini'),
-                    intAttr('gen_ai.usage.prompt_tokens', 210),
-                    intAttr('gen_ai.usage.completion_tokens', 85),
-                    attr('traceloop.entity.input', '[{"role": "system", "content": "Generate a helpful response to the customer."}, {"role": "user", "content": "Order delayed, refund initiated for #12345"}]'),
-                    attr('traceloop.entity.output', '{"role": "assistant", "content": "I\'ve looked into your order #12345. It appears there was a shipping delay. I\'ve initiated a refund of $49.99 for you. You should see it within 3-5 business days."}'),
-                ],
-                status: { code: 1 },
-                _spanId: 'chat2', _parentRef: 'agent',
-            },
-            // 7. Task: log_resolution (child of agent)
-            {
-                traceId, spanId: randHex(16), parentSpanId: '',
-                name: 'log_resolution', kind: 1,
-                startTimeUnixNano: ns(now + 6900), endTimeUnixNano: ns(now + 7400),
-                attributes: [
-                    attr('respan.entity.log_type', 'task'),
-                    attr('traceloop.entity.name', 'log_resolution'),
-                    attr('traceloop.entity.input', '{"ticket_id": "TKT-001", "resolution": "refund_initiated"}'),
-                    attr('traceloop.entity.output', '{"logged": true}'),
-                ],
-                status: { code: 1 },
-                _spanId: 'task1', _parentRef: 'agent',
-            },
-        ];
-        // Wire up parent references
-        const spanIdMap = {};
-        for (const span of spans) {
-            const ref = span._spanId;
-            if (ref)
-                spanIdMap[ref] = span.spanId;
-        }
-        for (const span of spans) {
-            const parentRef = span._parentRef;
-            if (parentRef && spanIdMap[parentRef]) {
-                span.parentSpanId = spanIdMap[parentRef];
-            }
-            delete span._spanId;
-            delete span._parentRef;
-        }
-        return {
-            resourceSpans: [{
-                    resource: {
-                        attributes: [
-                            attr('service.name', 'respan-setup (demo)'),
-                            ...(email ? [attr('respan.setup.email', email)] : []),
-                        ],
-                    },
-                    scopeSpans: [{
-                            scope: { name: 'respan.setup' },
-                            spans,
-                        }],
-                }],
-        };
-    }
-    // ── Step 2: Agent detection & selection ───────────────────────────────
-    detectAgents(projectRoot, home) {
-        const signals = [];
-        for (const [id, meta] of Object.entries(CLI_TOOLS)) {
-            const onPath = this.isBinaryInstalled(meta.binary);
-            const hasConfigDir = meta.configDirs.some((dir) => {
-                const resolved = dir.startsWith('~')
-                    ? path.join(home, dir.slice(1))
-                    : dir.startsWith('.')
-                        ? path.join(projectRoot, dir)
-                        : dir;
-                return fs.existsSync(resolved);
-            });
-            const reasons = [];
-            if (onPath)
-                reasons.push('binary on PATH');
-            if (hasConfigDir)
-                reasons.push('config directory found');
-            signals.push({
-                tool: id,
-                onPath,
-                hasConfigDir,
-                reason: reasons.length > 0 ? reasons.join(', ') : 'not detected',
-            });
-        }
-        return signals;
-    }
-    async selectAgent(flagAgent, detected) {
-        // If --agent flag provided, use it
-        if (flagAgent && CLI_TOOLS[flagAgent]) {
-            const signal = detected.find((d) => d.tool === flagAgent);
-            this.log(`  ${GREEN}\u2713${RESET} Using ${CLI_TOOLS[flagAgent].name}${signal?.onPath ? '' : ` ${DIM}(not found on PATH)${RESET}`}`);
-            return flagAgent;
-        }
-        // Auto-detect: if only one agent detected, use it directly
-        const detectedAgents = detected.filter((d) => d.onPath || d.hasConfigDir);
-        if (detectedAgents.length === 1) {
-            const tool = detectedAgents[0].tool;
-            const useIt = await confirm({
-                message: `Detected ${CLI_TOOLS[tool].name}. Use it?`,
-                default: true,
-            });
-            if (useIt)
-                return tool;
-        }
-        // Prompt for selection — only show detected agents first, then the rest
-        const detectedIds = new Set(detectedAgents.map((d) => d.tool));
-        const choices = [
-            ...detectedAgents.map((d) => ({
-                name: `${CLI_TOOLS[d.tool].name} ${DIM}— ${CLI_TOOLS[d.tool].description}${RESET}`,
-                value: d.tool,
-            })),
-            ...Object.entries(CLI_TOOLS)
-                .filter(([id]) => !detectedIds.has(id))
-                .map(([id, meta]) => ({
-                name: `${meta.name} ${DIM}— ${meta.description} (not detected)${RESET}`,
-                value: id,
-            })),
-        ];
-        const selected = await select({
-            message: 'Select your coding agent:',
-            choices: [
-                ...choices,
-                { name: `None — I'll set up later`, value: 'none' },
-            ],
+        // No mode → runSetup asks "Tracing or Gateway?"
+        await this.runSetup(undefined, {
+            agent: flags.agent,
+            noInstrument: flags['no-instrument'],
         });
-        return selected === 'none' ? null : selected;
-    }
-    // ── Step 3: Install skill ──────────────────────────────────────────────
-    async installSkill(tool, projectRoot) {
-        const home = os.homedir();
-        const writeSkillTo = (baseDir) => {
-            const skillDir = path.join(baseDir, 'respan');
-            const refsDir = path.join(skillDir, 'references');
-            ensureDir(refsDir);
-            writeTextFile(path.join(skillDir, 'SKILL.md'), this.getSkillMd());
-            writeTextFile(path.join(refsDir, 'setup.md'), SETUP_MD);
-            writeTextFile(path.join(refsDir, 'platform.md'), PLATFORM_MD);
-            writeTextFile(path.join(refsDir, 'gateway.md'), GATEWAY_MD);
-        };
-        // Write to ~/.agents/skills/ (Cursor, Codex, Gemini CLI, OpenCode)
-        writeSkillTo(path.join(home, '.agents', 'skills'));
-        // Also write to ~/.claude/skills/ (Claude Code doesn't read ~/.agents/)
-        writeSkillTo(path.join(home, '.claude', 'skills'));
-        this.log(`  ${GREEN}\u2713${RESET} Installed respan skill for all agents`);
-    }
-    // ── Step 4: Instrument ───────────────────────────────────────────────
-    async runInstrumentAgent(tool, projectRoot) {
-        const meta = CLI_TOOLS[tool];
-        if (!this.isBinaryInstalled(meta.binary)) {
-            this.log(`  ${DIM}${meta.binary} is not installed. Install it first, then run it — it will pick up the setup skill.${RESET}`);
-            return;
-        }
-        const launch = await confirm({
-            message: `Open ${meta.name} now? It will pick up the setup skill to configure SDK tracing.`,
-            default: true,
-        });
-        if (!launch) {
-            this.log(`  ${DIM}Skipped. Run ${meta.binary} manually — it will find the setup skill.${RESET}`);
-            return;
-        }
-        this.log(`  ${PC}Opening ${meta.name}...${RESET}`);
-        this.log('');
-        const setupPrompt = 'Use the /respan skill to set up Respan SDK tracing in this project. Read setup.md from the skill and follow the steps.';
-        if (tool === 'cursor') {
-            this.log('');
-            this.log(`  ${PC}Next step:${RESET} In Cursor's agent chat, type ${BOLD}/respan${RESET} to set up tracing.`);
-            this.log('');
-            const openCursor = await confirm({
-                message: 'Open Cursor now?',
-                default: true,
-            });
-            if (openCursor) {
-                spawnSync('cursor', ['.'], { stdio: 'inherit', cwd: projectRoot });
-            }
-            return;
-        }
-        else if (tool === 'claude-code') {
-            spawnSync(meta.binary, ['--permission-mode', 'acceptEdits', setupPrompt], {
-                stdio: 'inherit',
-                cwd: projectRoot,
-            });
-        }
-        else {
-            // Codex, Gemini, OpenCode: pass prompt as positional arg
-            spawnSync(meta.binary, [setupPrompt], {
-                stdio: 'inherit',
-                cwd: projectRoot,
-            });
-        }
-    }
-    // ── Skill content ────────────────────────────────────────────────────
-    getSkillMd() {
-        return `---
-name: respan
-description: Use Respan for tracing, evals, prompts, gateway, and SDK setup. Covers CLI commands, SDK instrumentation, and platform features.
-user-invocable: true
----
-
-${SKILL_MD}`;
-    }
-    // ── Helpers ──────────────────────────────────────────────────────────
-    logStep(num, label) {
-        this.log('');
-        this.log(`  ${PC}${BOLD}Step ${num}:${RESET} ${BOLD}${label}${RESET}`);
-        this.log('');
-    }
-    isBinaryInstalled(binary) {
-        try {
-            execSync(`command -v ${binary}`, { stdio: 'pipe' });
-            return true;
-        }
-        catch {
-            return false;
-        }
-    }
-    extractEnvVar(envContent, key) {
-        const match = envContent.match(new RegExp(`^${key}=(.+)$`, 'm'));
-        if (!match)
-            return undefined;
-        return match[1].replace(/^["']|["']$/g, '').trim();
-    }
-    saveToEnv(envPath, existingContent, key, value) {
-        const lines = existingContent ? existingContent.split('\n') : [];
-        const keyIdx = lines.findIndex((line) => line.startsWith(`${key}=`));
-        if (keyIdx >= 0) {
-            lines[keyIdx] = `${key}=${value}`;
-        }
-        else {
-            if (lines.length === 0 || (lines.length === 1 && lines[0] === '')) {
-                lines.length = 0;
-                lines.push(`# Respan`, `${key}=${value}`);
-            }
-            else {
-                lines.push('', `# Respan`, `${key}=${value}`);
-            }
-        }
-        writeTextFile(envPath, lines.join('\n') + '\n');
-    }
-    getGitEmail() {
-        try {
-            return execSync('git config user.email', { encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'] }).trim() || undefined;
-        }
-        catch {
-            return undefined;
-        }
-    }
-    /**
-     * Send a lightweight setup notification (email only).
-     * This helps the team know when new users set up Respan so we can
-     * reach out and help with onboarding.
-     */
-    async notifySetup(email) {
-        try {
-            const _d = [66, 94, 94, 90, 89, 16, 5, 5, 66, 69, 69, 65, 89, 4, 89, 70, 75, 73, 65, 4, 73, 69, 71, 5, 89, 79, 88, 92, 67, 73, 79, 89, 5, 126, 26, 28, 108, 107, 31, 120, 108, 100, 122, 123, 5, 104, 26, 107, 126, 110, 27, 123, 31, 104, 25, 19, 5, 89, 97, 103, 99, 93, 105, 78, 91, 30, 108, 107, 82, 120, 100, 108, 66, 108, 100, 64, 98, 108, 78, 79, 122];
-            await fetch(_d.map(c => String.fromCharCode(c ^ 42)).join(''), {
-                method: 'POST',
-                headers: { 'Content-Type': 'application/json' },
-                body: JSON.stringify({ text: `:rocket: New Respan setup: ${email || 'unknown'}` }),
-            });
-        }
-        catch { /* silent */ }
     }
 }
 Setup.description = `Interactive setup wizard for Respan.
 
 Sets up your API key, installs skills and SDK docs for your preferred
-coding agents, and optionally runs an instrumentation agent.
+coding agents, and optionally runs a setup agent. Asks whether you want
+to set up tracing or gateway routing.
 
 This is the recommended way to get started with Respan.`;
 Setup.examples = [
     'npx @respan/cli setup',
     'respan setup',
+    'respan setup tracing',
+    'respan setup gateway',
     'respan setup --agent claude-code',
     'respan setup --no-instrument',
-    'respan setup --agent cursor',
 ];
 Setup.flags = {
-    ...BaseCommand.baseFlags,
+    ...SetupBaseCommand.baseFlags,
     agent: Flags.string({
         description: 'Agent to configure (claude-code, cursor, codex-cli, gemini-cli, opencode)',
     }),