@respan/cli 0.14.1 → 0.15.0

package/dist/lib/setup-base-command.js

@@ -1,761 +1,15 @@
-import * as path from 'node:path';
-import * as os from 'node:os';
-import * as fs from 'node:fs';
-import { execSync, spawnSync } from 'node:child_process';
-import { Flags } from '@oclif/core';
-import { input, select, confirm } from '@inquirer/prompts';
 import { BaseCommand } from './base-command.js';
-import { getCredential, setCredential, getActiveProfile } from './config.js';
-import { DEFAULT_BASE_URL, ENTERPRISE_BASE_URL } from './auth.js';
-import { printBanner } from './banner.js';
-import { findProjectRoot, writeTextFile, readTextFile, ensureDir, extractEnvVar, } from './integrate.js';
-import { createSpinner } from './spinner.js';
-import { PC, RESET, DIM, GREEN, BOLD } from './colors.js';
-import { CLI_TOOLS, detectAgents, isBinaryInstalled, } from './agents.js';
-import { getSkillMd } from './skill-content.js';
-import { TRACING_MD, GATEWAY_MD, PROMPTS_MD, EVALS_MD, MONITORS_MD, } from './skill-refs.generated.js';
-/**
- * Intermediate base class for the `respan setup` family of commands
- * (`setup`, `setup tracing`, `setup gateway`).
- *
- * It deliberately sits between the concrete commands and {@link BaseCommand}
- * so that setup-only concerns (interactive prompts, the agent registry, and
- * multi-kilobyte skill content) never leak onto the root command class that
- * every other command extends.
- */
+/** Compatibility entry point. Setup instructions are maintained in the docs. */
 export class SetupBaseCommand extends BaseCommand {
-    // ── Orchestrator ───────────────────────────────────────────────────────
-    /**
-     * Shared setup flow for all three entry points.
-     *
-     *   1. askEndpoint()      // saved endpoint (confirm reuse) → environment prompt
-     *   2. askApiKey()        // .env → global credential → prompt
-     *   3. if mode is undefined → ask "Tracing or Gateway?" (interactive only)
-     *   4. verifyApiKey(mode) // both re-prompt on a rejected key; can pause setup
-     *   5. selectAgent()      // drives only the launch
-     *   6. installSkill()     // full bundle, for all agents, regardless of selection
-     *   7. launchAgent(mode)  // only if an agent was selected
-     */
-    async runSetup(mode, opts = {}) {
-        await printBanner();
-        const projectRoot = findProjectRoot();
-        const home = os.homedir();
-        // Step numbers are assigned sequentially. The mode question only runs for
-        // bare `respan setup`, so the concrete `setup tracing` / `setup gateway`
-        // commands renumber the later steps instead of leaving a gap.
-        let step = 1;
-        this.logStep(step++, 'Endpoint');
-        const baseUrl = await this.askEndpoint(projectRoot);
-        this.logStep(step++, 'API Key');
-        const apiKey = await this.askApiKey(projectRoot, baseUrl);
-        // Ask the mode only when a concrete command didn't already pin it.
-        const resolvedMode = mode ?? (await this.askMode(step));
-        if (mode === undefined)
-            step++;
-        const verified = await this.verifyApiKey(apiKey, resolvedMode, projectRoot, baseUrl);
-        if (!verified) {
-            const ready = resolvedMode === 'gateway' ? 'your gateway access is ready' : 'you have a valid API key';
-            this.log('');
-            this.log(`  ${DIM}Setup paused. Run ${RESET}respan setup ${resolvedMode}${DIM} again once ${ready}.${RESET}`);
-            return;
-        }
-        let selectedTool = null;
-        if (!opts.noInstrument) {
-            this.logStep(step++, 'Open which coding agent?');
-            const detected = detectAgents(projectRoot, home);
-            selectedTool = await this.selectAgent(opts.agent, detected);
-        }
-        // Install the full skill bundle for every agent, regardless of selection.
-        this.logStep(step++, 'Install skill');
-        await this.installSkill();
-        // ── 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}`);
-        const dashboard = this.dashboardUrl(baseUrl);
-        if (resolvedMode === 'gateway') {
-            this.log(`  ${DIM}View logs at ${RESET}${dashboard}`);
-        }
-        else {
-            this.log(`  ${DIM}View traces at ${RESET}${dashboard}`);
-        }
-        this.log('');
-        this.notifySetup(this.getGitEmail()).catch(() => { });
-        // Open the agent only if one was selected.
-        if (selectedTool) {
-            await this.launchAgent(selectedTool, projectRoot, resolvedMode);
-        }
-        else if (!opts.noInstrument) {
-            this.log(`  ${DIM}No agent selected, but the skill is installed. Open your agent any time and use the ${RESET}/respan${DIM} skill.${RESET}`);
-        }
-    }
-    // ── Step 1: Endpoint ─────────────────────────────────────────────────
-    /**
-     * Resolve which Respan endpoint this project should target, mirroring the
-     * environment prompt in `respan auth login`.
-     *
-     * First run: ask "Respan Platform or Enterprise?" and remember the choice.
-     * Later runs: offer the saved endpoint and confirm before reusing it, so a
-     * user who switched environments isn't silently pinned to the old one. An
-     * explicit `--base-url` flag wins and skips the prompt for scripted flows.
-     */
-    async askEndpoint(projectRoot) {
-        // Explicit flag wins — CI/scripted parity with `auth login --base-url`.
-        const flagBaseUrl = this.globalFlags['base-url'];
-        if (flagBaseUrl) {
-            // `--base-url` is documented as a per-command override, so honor it for
-            // this run (verification + project .env) but don't rewrite the saved
-            // credential — that would silently redirect every other CLI command too.
-            const normalized = flagBaseUrl.replace(/\/+$/, '');
-            this.persistBaseUrlToEnv(projectRoot, normalized);
-            this.log(`  ${GREEN}✓${RESET} Using endpoint ${DIM}${this.endpointLabel(normalized)}${RESET}`);
-            return normalized;
-        }
-        // Returning users: reuse the endpoint from their saved credential
-        // (the same store `auth login` writes) on confirmation.
-        const saved = getCredential()?.baseUrl;
-        if (saved) {
-            const reuse = await confirm({
-                message: `Use your saved endpoint (${this.endpointLabel(saved)})?`,
-                default: true,
-            });
-            if (reuse) {
-                this.persistBaseUrlToEnv(projectRoot, saved);
-                return saved;
-            }
-        }
-        // First time (or switching environments) — same choices as auth login.
-        const enterprise = await select({
-            message: 'Select your environment:',
-            choices: [
-                { name: 'Respan Platform', value: false },
-                { name: 'Enterprise', value: true },
-            ],
-        });
-        const baseUrl = enterprise ? ENTERPRISE_BASE_URL : DEFAULT_BASE_URL;
-        this.rememberEndpoint(baseUrl);
-        this.persistBaseUrlToEnv(projectRoot, baseUrl);
-        return baseUrl;
-    }
-    /**
-     * Persist the chosen endpoint onto the existing saved credential — the same
-     * `~/.respan/credentials.json` store `auth login` uses. Only updates a
-     * credential that already exists; a first-time key is saved (with this
-     * baseUrl) later in {@link askApiKey}, so we never create a second store.
-     */
-    rememberEndpoint(baseUrl) {
-        const profile = getActiveProfile();
-        const cred = getCredential(profile);
-        if (cred && cred.baseUrl !== baseUrl) {
-            setCredential(profile, { ...cred, baseUrl });
-        }
-    }
-    /** Friendly name for the known endpoints; falls back to the raw URL. */
-    endpointLabel(baseUrl) {
-        if (baseUrl === DEFAULT_BASE_URL)
-            return 'Respan Platform';
-        if (baseUrl === ENTERPRISE_BASE_URL)
-            return 'Enterprise';
-        return baseUrl;
-    }
-    /** Dashboard origin that pairs with an ingest endpoint. */
-    dashboardUrl(baseUrl) {
-        return baseUrl === ENTERPRISE_BASE_URL
-            ? 'https://enterprise.respan.ai'
-            : 'https://platform.respan.ai';
-    }
-    /**
-     * Pin the SDK's RESPAN_BASE_URL in `.env` when the endpoint isn't the
-     * default. The SDK already targets the Respan Platform out of the box, so we
-     * leave `.env` untouched for that choice and only write the override that a
-     * non-default endpoint actually needs (with the `/api` suffix the SDK wants).
-     */
-    persistBaseUrlToEnv(projectRoot, baseUrl) {
-        if (baseUrl === DEFAULT_BASE_URL)
-            return;
-        const normalized = baseUrl.replace(/\/+$/, '');
-        const sdkBaseUrl = normalized.endsWith('/api') ? normalized : `${normalized}/api`;
-        const envPath = path.join(projectRoot, '.env');
-        const existingEnv = readTextFile(envPath);
-        this.saveToEnv(envPath, existingEnv, 'RESPAN_BASE_URL', sdkBaseUrl);
-        this.log(`  ${GREEN}✓${RESET} Saved endpoint to ${DIM}.env (RESPAN_BASE_URL)${RESET}`);
-    }
-    /** Resolve the OTLP traces ingest URL for a base URL (with/without /api). */
-    resolveTracesEndpoint(baseUrl) {
-        const normalized = baseUrl.replace(/\/+$/, '');
-        return normalized.endsWith('/api') ? `${normalized}/v2/traces` : `${normalized}/api/v2/traces`;
-    }
-    /** Resolve the gateway chat-completions URL for a base URL (with/without /api). */
-    resolveCompletionsEndpoint(baseUrl) {
-        const normalized = baseUrl.replace(/\/+$/, '');
-        return normalized.endsWith('/api') ? `${normalized}/chat/completions` : `${normalized}/api/chat/completions`;
-    }
-    async askMode(step) {
-        this.logStep(step, 'What to set up');
-        return select({
-            message: 'What would you like to set up?',
-            choices: [
-                {
-                    name: `Tracing ${DIM}— instrument your app to capture LLM calls as structured traces${RESET}`,
-                    value: 'tracing',
-                },
-                {
-                    name: `Gateway ${DIM}— route LLM requests through the Respan proxy for logging, caching, and key management${RESET}`,
-                    value: 'gateway',
-                },
-            ],
-        });
-    }
-    // ── Step 2: API Key ──────────────────────────────────────────────────
-    async askApiKey(projectRoot, baseUrl = DEFAULT_BASE_URL) {
-        const envPath = path.join(projectRoot, '.env');
-        const existingEnv = readTextFile(envPath);
-        const existingKey = extractEnvVar(existingEnv, 'RESPAN_API_KEY');
-        // 1. A key already in .env is the project source of truth — use it as-is.
-        if (existingKey) {
-            const masked = existingKey.slice(0, 8) + '...' + existingKey.slice(-4);
-            this.log(`  ${GREEN}✓${RESET} Using API key from ${DIM}.env${RESET} ${DIM}(${masked})${RESET}`);
-            return existingKey;
-        }
-        // 2. Offer the global credential (if it is an API key) for reuse.
-        const globalCred = getCredential();
-        if (globalCred && globalCred.type === 'api_key' && globalCred.apiKey) {
-            const masked = globalCred.apiKey.slice(0, 8) + '...' + globalCred.apiKey.slice(-4);
-            const useGlobal = await confirm({
-                message: `Use your saved Respan key (${masked})?`,
-                default: true,
-            });
-            if (useGlobal) {
-                this.saveToEnv(envPath, existingEnv, 'RESPAN_API_KEY', globalCred.apiKey);
-                this.log(`  ${GREEN}✓${RESET} Saved API key to ${DIM}${envPath}${RESET}`);
-                return globalCred.apiKey;
-            }
-        }
-        // 3. No usable key — collect one from the chosen endpoint's dashboard.
+    async runSetup(mode, _opts = {}) {
+        this.log('respan setup is deprecated. Paste a setup prompt into your coding agent instead.');
+        this.log('The agent follows the official guide and uses the CLI to verify the result.');
         this.log('');
-        this.log(`  ${DIM}Get your API key at ${RESET}${this.dashboardUrl(baseUrl)}/settings/api-keys`);
-        this.log('');
-        const entered = await input({
-            message: 'Enter your Respan API key:',
-            validate: (val) => val.trim().length > 0 || 'API key is required',
-        });
-        const apiKey = entered.trim();
-        this.saveToEnv(envPath, existingEnv, 'RESPAN_API_KEY', apiKey);
-        this.log(`  ${GREEN}✓${RESET} Saved API key to ${DIM}${envPath}${RESET}`);
-        // 4. Offer to persist it globally for other projects.
-        const saveGlobal = await confirm({
-            message: 'Save this key globally for use in other projects?',
-            default: true,
-        });
-        if (saveGlobal) {
-            setCredential('default', { type: 'api_key', apiKey, baseUrl });
-            this.log(`  ${GREEN}✓${RESET} Saved globally ${DIM}(~/.respan/credentials.json)${RESET}`);
-        }
-        return apiKey;
-    }
-    /**
-     * Verify the key for the chosen mode. Both paths re-prompt on a rejected key
-     * and return false if the user abandons the check, so the caller can pause
-     * setup instead of reporting success with a key that doesn't work.
-     */
-    async verifyApiKey(apiKey, mode, projectRoot, baseUrl) {
-        return mode === 'gateway'
-            ? this.verifyGatewayKey(apiKey, projectRoot, baseUrl)
-            : this.verifyTracingKey(apiKey, projectRoot, baseUrl);
-    }
-    /** Prompt for a replacement key and persist it to the project .env. */
-    async reenterApiKey(envPath) {
-        const existingEnv = readTextFile(envPath);
-        const entered = await input({
-            message: 'Enter your Respan API key:',
-            validate: (val) => val.trim().length > 0 || 'API key is required',
-        });
-        const key = entered.trim();
-        this.saveToEnv(envPath, existingEnv, 'RESPAN_API_KEY', key);
-        return key;
-    }
-    async verifyTracingKey(apiKey, projectRoot, baseUrl) {
-        const envPath = path.join(projectRoot, '.env');
-        const tracesUrl = this.resolveTracesEndpoint(baseUrl);
-        const dashboard = this.dashboardUrl(baseUrl);
-        let key = apiKey;
-        // eslint-disable-next-line no-constant-condition
-        while (true) {
-            const spinner = createSpinner('Verifying API key');
-            spinner.start();
-            let status = 0;
-            try {
-                const response = await fetch(tracesUrl, {
-                    method: 'POST',
-                    headers: {
-                        'Authorization': `Bearer ${key}`,
-                        'Content-Type': 'application/json',
-                    },
-                    body: JSON.stringify(this.buildDemoTrace(this.getGitEmail())),
-                });
-                status = response.status;
-            }
-            catch {
-                // Network/transient failure — tracing is lenient, so warn and continue.
-                spinner.fail('Could not verify API key (network error)');
-                this.warn(`  Setup will continue, please verify manually at ${dashboard}`);
-                return true;
-            }
-            if (status >= 200 && status < 300) {
-                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}${dashboard}${DIM} to see what Respan traces look like.${RESET}`);
-                this.log('');
-                await confirm({ message: 'Ready to continue?', default: true });
-                return true;
-            }
-            // A rejected key is the one failure we can fix here — re-prompt so a stale
-            // .env key doesn't dead-end every run under a green "Setup complete!".
-            if (status === 401 || status === 403) {
-                spinner.fail('Invalid API key');
-                const reenter = await confirm({
-                    message: 'That key was rejected. Enter a different API key?',
-                    default: true,
-                });
-                if (!reenter)
-                    return false;
-                key = await this.reenterApiKey(envPath);
-                continue;
-            }
-            // Any other status — don't block setup on an unknown server state.
-            spinner.fail(`Verification failed (status: ${status})`);
-            this.warn(`  Setup will continue, please verify manually at ${dashboard}`);
-            return true;
+        if (mode !== 'gateway') {
+            this.log('Help me set up Respan tracing: fetch and follow https://www.respan.ai/docs/documentation/agent-setup.md');
         }
-    }
-    /**
-     * Gateway verification gates on a real request succeeding: there is no
-     * credit-balance endpoint, so a 200 is the only proof of a valid key with a
-     * positive balance. A rejected key (401/403) re-prompts; any other failure
-     * loops on the user's say-so. Returns true on success, false if abandoned.
-     */
-    async verifyGatewayKey(apiKey, projectRoot, baseUrl) {
-        const envPath = path.join(projectRoot, '.env');
-        const completionsUrl = this.resolveCompletionsEndpoint(baseUrl);
-        const dashboard = this.dashboardUrl(baseUrl);
-        let key = apiKey;
-        // eslint-disable-next-line no-constant-condition
-        while (true) {
-            const spinner = createSpinner('Verifying gateway access');
-            spinner.start();
-            let status = 0;
-            let networkError = false;
-            try {
-                const response = await fetch(completionsUrl, {
-                    method: 'POST',
-                    headers: {
-                        'Authorization': `Bearer ${key}`,
-                        'Content-Type': 'application/json',
-                    },
-                    body: JSON.stringify(this.buildDemoCompletion()),
-                });
-                status = response.status;
-                if (response.ok) {
-                    spinner.succeed('Gateway access verified');
-                    this.log('');
-                    this.log(`  ${PC}A demo request was routed through the gateway.${RESET}`);
-                    this.log(`  ${DIM}View it at ${RESET}${dashboard}${DIM} or run ${RESET}respan logs list --limit 5`);
-                    this.log('');
-                    await confirm({ message: 'Ready to continue?', default: true });
-                    return true;
-                }
-            }
-            catch {
-                networkError = true;
-            }
-            // A rejected key won't pass on retry — offer to enter a different one.
-            if (status === 401 || status === 403) {
-                spinner.fail('Invalid API key');
-                const reenter = await confirm({
-                    message: 'That key was rejected. Enter a different API key?',
-                    default: true,
-                });
-                if (!reenter)
-                    return false;
-                key = await this.reenterApiKey(envPath);
-                continue;
-            }
-            // 402 means no credits; anything else (429, 5xx, network) is a transient
-            // failure — don't point those users at the billing page.
-            spinner.fail(networkError
-                ? 'Could not reach the gateway (network error)'
-                : `Gateway request failed (status: ${status})`);
-            this.log('');
-            if (status === 402) {
-                this.log(`  ${DIM}A positive credit balance is required to use the gateway.${RESET}`);
-                this.log(`  ${DIM}Add credits at ${RESET}https://platform.respan.ai/platform/api/billing`);
-            }
-            else {
-                this.log(`  ${DIM}The request didn't go through. This may be temporary, please try again.${RESET}`);
-            }
-            this.log('');
-            const recheck = await confirm({
-                message: 'Re-check now? (choose No to exit setup)',
-                default: true,
-            });
-            if (!recheck)
-                return false;
-            // loop -> fires a fresh probe
-        }
-    }
-    /**
-     * 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.input_tokens', 145),
-                    intAttr('gen_ai.usage.output_tokens', 38),
-                    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.input_tokens', 210),
-                    intAttr('gen_ai.usage.output_tokens', 85),
-                    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,
-                        }],
-                }],
-        };
-    }
-    /**
-     * Minimal chat completion sent through the gateway to prove auth + routing
-     * and drop a real logged request into the user's account.
-     */
-    buildDemoCompletion() {
-        return {
-            model: 'gpt-4o-mini',
-            messages: [
-                { role: 'user', content: 'Hello from respan setup! Reply with a short greeting.' },
-            ],
-            max_tokens: 32,
-        };
-    }
-    // ── Agent selection ───────────────────────────────────────────────────
-    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}✓${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' },
-            ],
-        });
-        return selected === 'none' ? null : selected;
-    }
-    // ── Install skill ──────────────────────────────────────────────────────
-    async installSkill() {
-        const home = os.homedir();
-        // Only a recognisably-ours, real directory is safe to wipe. Never delete a
-        // symlink (e.g. one linked from a dotfiles repo) or a dir holding files we
-        // didn't write — overwrite those in place instead.
-        const isManagedSkillDir = (skillDir) => {
-            try {
-                if (fs.lstatSync(skillDir).isSymbolicLink())
-                    return false;
-                const skillMd = path.join(skillDir, 'SKILL.md');
-                return fs.existsSync(skillMd) && fs.readFileSync(skillMd, 'utf-8').startsWith('---\nname: respan');
-            }
-            catch {
-                return false;
-            }
-        };
-        const writeSkillTo = (baseDir) => {
-            const skillDir = path.join(baseDir, 'respan');
-            const refsDir = path.join(skillDir, 'references');
-            // Wipe a prior install so docs we've since renamed or removed (e.g. the
-            // old tracing-setup.md / gateway-setup.md / setup.md) don't linger as
-            // orphans — but only when the dir is genuinely ours (see above).
-            if (isManagedSkillDir(skillDir)) {
-                fs.rmSync(skillDir, { recursive: true, force: true });
-            }
-            ensureDir(refsDir);
-            writeTextFile(path.join(skillDir, 'SKILL.md'), getSkillMd());
-            writeTextFile(path.join(refsDir, 'tracing.md'), TRACING_MD);
-            writeTextFile(path.join(refsDir, 'gateway.md'), GATEWAY_MD);
-            writeTextFile(path.join(refsDir, 'prompts.md'), PROMPTS_MD);
-            writeTextFile(path.join(refsDir, 'evals.md'), EVALS_MD);
-            writeTextFile(path.join(refsDir, 'monitors.md'), MONITORS_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}✓${RESET} Installed respan skill for all agents`);
-    }
-    // ── Launch agent ────────────────────────────────────────────────────────
-    async launchAgent(tool, projectRoot, mode) {
-        const meta = CLI_TOOLS[tool];
-        const what = mode === 'gateway' ? 'gateway routing' : 'SDK tracing';
-        if (!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 ${what}.`,
-            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 = mode === 'gateway'
-            ? 'Use the /respan skill to set up Respan gateway routing in this project. Read gateway.md from the skill and follow the Setup steps to route the detected framework through the gateway.'
-            : 'Use the /respan skill to set up Respan SDK tracing in this project. Read tracing.md from the skill and follow the Setup steps.';
-        if (tool === 'cursor') {
-            this.log('');
-            this.log(`  ${PC}Next step:${RESET} In Cursor's agent chat, type ${BOLD}/respan${RESET} to set up ${what}.`);
-            this.log('');
-            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,
-            });
-        }
-    }
-    // ── Helpers ──────────────────────────────────────────────────────────
-    logStep(num, label) {
-        this.log('');
-        this.log(`  ${PC}${BOLD}Step ${num}:${RESET} ${BOLD}${label}${RESET}`);
-        this.log('');
-    }
-    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'}` }),
-            });
+        if (mode !== 'tracing') {
+            this.log('Help me set up the Respan gateway: fetch and follow https://www.respan.ai/docs/documentation/agent-setup.md');
         }
-        catch { /* silent */ }
     }
 }
-// setup is an interactive wizard with no structured output — hide the
-// inherited --json/--csv flags so --help doesn't advertise dead options.
-SetupBaseCommand.baseFlags = {
-    ...BaseCommand.baseFlags,
-    json: Flags.boolean({ hidden: true, default: false }),
-    csv: Flags.boolean({ hidden: true, default: false }),
-};