@respan/cli 0.10.0 → 0.12.0

package/dist/lib/skill-refs.generated.js

@@ -1,19 +1,269 @@
 // AUTO-GENERATED by scripts/embed-skill-refs.mjs
-// Source: skills/references/{tracing,prompts,evals,monitors}.md
+// Source: skills/SKILL.md and skills/references/{tracing,gateway,prompts,evals,monitors}.md
 // Do not edit directly — edit the markdown sources and rebuild.
-export const TRACING_MD = `# Tracing Reference
+export const SKILL_MD = `# Respan
 
-Advanced tracing configuration: decorators, context propagation, processors, and span attributes.
+Use the Respan CLI and SDK for LLM observability — tracing, evals, prompts, datasets, and gateway routing.
+
+## When To Use
+
+- **Set up tracing** (instrument your app to capture LLM calls — install + decorators, propagation, processors) → read [references/tracing.md](references/tracing.md)
+- **Set up gateway** (route LLM calls through the Respan proxy — wiring + model switching, fallbacks, caching) → read [references/gateway.md](references/gateway.md)
+- **Prompt management** (create, version, deploy) → read [references/prompts.md](references/prompts.md)
+- **Evals** (datasets, evaluators, experiments) → read [references/evals.md](references/evals.md)
+- **Monitors & automation** (alerts, online evals, webhooks) → read [references/monitors.md](references/monitors.md)
+
+Tracing and gateway are separate setups — configure one at a time, never both in the same pass.
+
+## Core Principles
+
+1. **Read the reference first.** Each reference file has the exact setup steps, API patterns, MCP tools, and CLI commands.
+2. **Use MCP tools** for platform operations (prompts, datasets, evaluators, experiments, traces, logs).
+3. **Use CLI** when MCP is not available: \`respan traces list\`, \`respan prompts list\`, etc.
+4. **Fetch docs** for integration-specific details not covered in references.
+
+## Quick Reference
+
+| Task | Reference / Command |
+|------|--------------------|
+| Set up tracing (steps + decorators, propagation) | [references/tracing.md](references/tracing.md) |
+| Set up gateway (steps + features) | [references/gateway.md](references/gateway.md) |
+| Prompt management | [references/prompts.md](references/prompts.md) |
+| Evals & experiments | [references/evals.md](references/evals.md) |
+| Monitors & automation | [references/monitors.md](references/monitors.md) |
+| List traces | \`respan traces list --limit 10\` |
+| View a trace | \`respan traces get <id>\` |
+| Check auth | \`respan auth status\` |
+
+## Documentation Access
+
+Any doc page can be fetched as markdown:
+\`https://respan.ai/docs/integrations/openai-sdk.md\`
+\`https://respan.ai/docs/sdks/typescript-sdk/overview.md\`
+
+Full docs index: \`https://www.respan.ai/docs/llms.txt\`
+
+Platform: \`https://platform.respan.ai\`
+`;
+export const TRACING_MD = `# Tracing
+
+Set up and configure Respan SDK tracing: instrument an app to capture LLM calls as
+structured traces, then refine with decorators, context propagation, and processors.
+
+This file covers **both** the initial setup steps and the advanced reference. Tracing
+is a separate setup from the gateway — do one at a time, never both in the same pass.
 
 Docs: \`https://respan.ai/docs/documentation/features/tracing/traces/tracing-sdk.md\`
+Full docs index: \`https://www.respan.ai/docs/llms.txt\`
 
 ---
 
-## Decorators
+## Setup
+
+Use this section when the user asks to set up Respan tracing in their project.
 
-Wrap functions to create structured span hierarchies. All decorators share the same signature.
+### 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.
+
+The API key is stored in \`.env\` as \`RESPAN_API_KEY\`.
+
+### 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\` | — | \`respan-instrumentation-crewai\` | — | [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\` | — | \`respan-instrumentation-haystack\` | — | [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 (final test — always run this)
+
+As the final step, **run the user's program once with a small request** and confirm tracing works end to end:
 
-### Types
+- The app runs without errors
+- A trace appears at https://platform.respan.ai or via \`respan traces list --limit 5\`
+- If wrappers were added, the trace shows the expected nested span hierarchy
+
+If no trace appears, the instrumentation isn't taking effect — debug (init placement, missing \`flush()\`, wrong entrypoint) and re-run before declaring setup done.
+
+---
+
+## Reference
+
+Advanced tracing configuration: decorators, context propagation, processors, and span attributes.
+
+### Decorators
+
+Wrap functions to create structured span hierarchies. All decorators share the same signature.
 
 | Decorator | Purpose |
 |-----------|---------|
@@ -22,7 +272,7 @@ Wrap functions to create structured span hierarchies. All decorators share the s
 | \`@agent\` / \`withAgent\` | Agent loop span |
 | \`@tool\` / \`withTool\` | Tool/function call span |
 
-### Python
+#### Python
 
 \`\`\`python
 from respan import Respan, workflow, task, agent, tool
@@ -43,7 +293,7 @@ def write_draft(outline: str):
     return client.chat.completions.create(...)
 \`\`\`
 
-### TypeScript
+#### TypeScript
 
 \`\`\`typescript
 import { Respan, withWorkflow, withTask } from "@respan/respan";
@@ -61,7 +311,7 @@ const result = await withWorkflow({ name: "write_article" }, async () => {
 });
 \`\`\`
 
-### Decorator Parameters
+#### Decorator Parameters
 
 \`\`\`python
 @workflow(
@@ -77,17 +327,15 @@ const result = await withWorkflow({ name: "write_article" }, async () => {
 
 All parameters are optional. Without any, the function name is used as the span name.
 
-### Async Support
+#### Async Support
 
 Decorators work with \`async def\`, generators, and async generators automatically.
 
----
-
-## Context Propagation
+### Context Propagation
 
 Attach attributes to **all spans** within a scope, including auto-instrumented LLM calls.
 
-### propagate_attributes
+#### propagate_attributes
 
 \`\`\`python
 from respan import Respan, propagate_attributes
@@ -104,7 +352,7 @@ with propagate_attributes(
     result = run_pipeline()
 \`\`\`
 
-#### Available attributes
+##### Available attributes
 
 | Attribute | Description |
 |-----------|-------------|
@@ -118,7 +366,7 @@ with propagate_attributes(
 | \`metadata\` | Dict of custom key-value pairs (merged in nested contexts) |
 | \`prompt\` | Dict with \`prompt_id\` and \`variables\` for prompt logging |
 
-#### TypeScript
+##### TypeScript
 
 \`\`\`typescript
 const result = await respan.propagateAttributes(
@@ -133,14 +381,14 @@ const result = await respan.propagateAttributes(
 );
 \`\`\`
 
-#### Nesting behavior
+##### Nesting behavior
 
 - Nested \`propagate_attributes\` calls merge with the outer context
 - \`metadata\` dicts are merged (not replaced)
 - For duplicate keys, inner values override outer
 - Async-safe via \`contextvars\`
 
-### respan_span_attributes
+#### respan_span_attributes
 
 Attaches attributes to the **current active span only** (not auto-instrumented child spans):
 
@@ -156,9 +404,7 @@ with respan_span_attributes({
 
 Use \`propagate_attributes\` when you need attributes on all nested spans (most common). Use \`respan_span_attributes\` when you only want to tag the current span.
 
----
-
-## Imperative Span Creation
+### Imperative Span Creation
 
 For runtime-determined span names, use the client API instead of decorators:
 
@@ -172,9 +418,7 @@ with client.start_span(name="dynamic_step", kind="task") as span:
     # span is automatically closed and exported
 \`\`\`
 
----
-
-## Updating the Current Span
+### Updating the Current Span
 
 Add attributes or change status on the active span at runtime:
 
@@ -202,9 +446,7 @@ except Exception as e:
     client.record_exception(e)
 \`\`\`
 
----
-
-## Custom Processors
+### Custom Processors
 
 Route spans to multiple destinations with filtering:
 
@@ -231,9 +473,7 @@ def sensitive_step():
     ...
 \`\`\`
 
----
-
-## Flush
+### Flush
 
 Always call \`flush()\` before process exit to ensure all spans are exported:
 
@@ -245,9 +485,7 @@ respan.flush()
 
 In serverless/Lambda: call \`flush()\` at the end of every handler invocation.
 
----
-
-## Trace Hierarchy Example
+### Trace Hierarchy Example
 
 \`\`\`
 workflow: handle_request
@@ -263,19 +501,152 @@ workflow: handle_request
 
 LLM calls within decorated functions are automatically nested as child spans.
 `;
-export const GATEWAY_MD = `# Gateway Reference
+export const GATEWAY_MD = `# Gateway
+
+Set up and use the Respan **gateway** — routing an app's LLM calls through the Respan
+proxy for logging, caching, key management, fallbacks, and model switching.
 
-Route LLM calls through the Respan proxy for logging, caching, key management, fallbacks, and model switching.
+This file covers **both** the setup steps and the feature reference. Gateway is a
+separate setup from tracing — do one at a time, never both in the same pass. Gateway
+setup does **not** install instrumentation packages; it repoints the LLM client's base
+URL at the Respan proxy and applies the framework's specific wiring.
 
 Docs: \`https://respan.ai/docs/documentation/features/gateway/gateway-quickstart.md\`
+Full docs index: \`https://www.respan.ai/docs/llms.txt\`
 
 ---
 
 ## Setup
 
+Use this section when the user asks to set up the Respan gateway.
+
+### Hard Rules
+
+- **Interactive mode:** Ask the user questions when you need input. Do not assume.
+- **Only add Respan wiring.** Do not refactor or modify unrelated code.
+- **The gateway serves only the completion / text-generation operation**, exposed per provider:
+  - OpenAI-compatible → \`https://api.respan.ai/api/chat/completions\`
+  - Anthropic Messages → \`https://api.respan.ai/api/anthropic/\`
+  - Google Gemini → \`https://api.respan.ai/api/google/gemini/...\`
+
+  **Use the exact base path from the per-SDK gateway doc you fetch in Step 4** — it is authoritative. Do **NOT** repoint clients used for any other operation — embeddings, moderation, images, audio/speech, assistants, batch, fine-tuning — they are not supported and will fail (e.g. 404). Leave those untouched.
+- **Use chat completions, not the Responses API.** The gateway serves chat completions (\`/api/chat/completions\`), not the OpenAI Responses API (\`/api/responses\`). SDKs that *default* to the Responses API are still fully supported — you just switch them to chat-completions mode, per their per-SDK doc:
+  - **OpenAI Agents SDK** — Python: \`set_default_openai_client(AsyncOpenAI(base_url=..., api_key=os.environ["RESPAN_API_KEY"]))\` + \`set_default_openai_api("chat_completions")\` (TS: \`setDefaultOpenAIClient(...)\` + \`setOpenAIAPI("chat_completions")\`).
+  - **Vercel AI SDK / \`@ai-sdk/openai\`** — use \`provider.chat(model)\`, not the default \`provider(model)\` (which targets the Responses API).
+- **Scope the wiring — do not blanket-rewrite.** Wire only the client(s) that make the completion call you are setting up. Do **NOT** repoint every client instance in the repo (especially in example/monorepo projects with many independent scripts).
+- **Do NOT install instrumentation packages.** Gateway routing does not use them. (That is tracing setup — see \`tracing.md\`.)
+- **Do not guess APIs or doc slugs.** Use only the patterns from the live integration doc you fetch, and the exact slug from the map below.
+- **Pin exact versions** if you install a framework SDK that is genuinely missing.
+- **If the gateway is already wired up, do not duplicate work.** Check for an existing \`base_url\`/\`baseURL\` pointing at \`api.respan.ai\` first.
+- **Read the code before proposing changes.** Find where the client is actually instantiated.
+
+The API key is stored in \`.env\` as \`RESPAN_API_KEY\`. Gateway base URL: \`https://api.respan.ai/api\` (the proxy completions path is \`https://api.respan.ai/api/chat/completions\`).
+
+### 1. Detect
+
+Identify:
+- **Language & package manager** — \`package.json\` (JS/TS), \`pyproject.toml\` / \`requirements.txt\` (Python), \`Gemfile\` (Ruby). Detect the package manager from lock files.
+- **LLM library / framework in use** — match the project's dependencies against the **Detection → slug map** below.
+
+### 2. Map to slug
+
+Match the detected package(s) against the map. **Use the slug from the map verbatim — never auto-derive a slug from a display name** (the kebab-casing is irregular).
+
+Apply the **priority rule:** a high-level framework wins over the raw SDK beneath it.
+For example, a project with both \`crewai\` and \`openai\` maps to \`crew-ai\` (not \`open-ai-sdk\`),
+because their gateway wiring differs. **If two frameworks match, ask the user which to configure.**
+
+#### Detection → slug map
+
+URL pattern: \`https://respan.ai/docs/integrations/gateway/<slug>.md\`
+
+| Detected package(s) | Slug |
+|---|---|
+| \`@openai/agents\` / \`openai-agents\` | \`open-ai-agents\` |
+| \`claude-agent-sdk\` | \`claude-agent-sdk\` |
+| \`ai\` (Vercel AI SDK) | \`vercel-ai-sdk\` |
+| \`pydantic-ai\` | \`pydantic-ai\` |
+| \`crewai\` | \`crew-ai\` |
+| \`haystack-ai\` | \`haystack\` |
+| \`langchain\` | \`lang-chain\` |
+| \`llama-index\` | \`llama-index\` |
+| \`autogen\` / \`autogen-agentchat\` | \`auto-gen\` |
+| \`dspy\` / \`dspy-ai\` | \`ds-py\` |
+| \`google-adk\` | \`google-adk\` |
+| \`openai\` | \`open-ai-sdk\` |
+| \`anthropic\` / \`@anthropic-ai/sdk\` | \`anthropic-sdk\` |
+| \`google-genai\` / \`@google/genai\` | \`google-gen-ai\` |
+| \`litellm\` | \`lite-llm\` |
+| \`ruby_llm\` (gem) | \`ruby-llm\` |
+| \`google-cloud-aiplatform\` | \`vertex-ai\` |
+
+> Namespace note: OpenAI, Anthropic, and Vertex each have both an SDK-level gateway page (\`open-ai-sdk\`, \`anthropic-sdk\`, \`vertex-ai\`) and a \`model-providers/*\` page. The SDK-level slugs above are the correct targets for this map.
+
+### 3. Confirm
+
+Show the user what was detected and which doc will be used. Wait for confirmation.
+
+> Detected:
+> - Language: [TypeScript/Python/Ruby]
+> - Framework / SDK: [e.g. OpenAI Agents]
+> - Gateway doc: https://respan.ai/docs/integrations/gateway/open-ai-agents.md
+>
+> Set up the gateway for this? (yes/no)
+
+### 4. Fetch the live doc
+
+Fetch \`https://respan.ai/docs/integrations/gateway/<slug>.md\` for the chosen slug.
+Use the slug from the map verbatim.
+
+If a pinned URL fails to resolve, that signals the **map is stale** and the table should be
+updated — it does **not** mean you should guess an alternative slug.
+
+### 5. Read the project's client code
+
+Find where the LLM client / \`base_url\` is instantiated, and identify **which client(s) make
+completion / text-generation calls** (chat completions, Anthropic \`messages.create\`, Gemini
+\`generate_content\`) — that is the only path you repoint. This is the step that determines the
+correct wiring — do not skip it.
+
+If the project has multiple clients or many scripts (e.g. an examples repo), repoint **only**
+the completion ones. Leave clients that call embeddings, moderation, images, audio,
+assistants, batch, or fine-tuning exactly as they are — the gateway does not serve them.
+
+### 6. Apply the framework-specific wiring
+
+Apply the exact pattern from the fetched doc:
+
+- Ensure \`RESPAN_API_KEY\` is set (it is in \`.env\`).
+- Repoint \`base_url\` / \`baseURL\` to the gateway path from the fetched doc (e.g. \`https://api.respan.ai/api\` for OpenAI-compatible, \`…/api/anthropic/\` for Anthropic) — **only on the completion client(s)** identified in step 5, not on every client in the project.
+- Apply the framework's exact wiring — e.g. OpenAI Agents requires \`set_default_openai_client(AsyncOpenAI(base_url=...))\`, **not** env vars.
+- Install the framework SDK only if it is genuinely missing.
+- **Do NOT install instrumentation packages.**
+
+### 7. Verify (final test — always run this)
+
+As the final step, **run the user's program once with a small request** through the
+configured gateway and confirm it works:
+
+\`\`\`bash
+respan logs list --limit 5
+\`\`\`
+
+Confirm:
+- The app runs without errors
+- The request appears in the gateway logs (via the CLI above, or the Respan platform at https://platform.respan.ai)
+
+If no log entry appears, the request is not actually routing through the gateway — debug
+the \`base_url\`/wiring and re-run before declaring setup done.
+
+---
+
+## Reference
+
+### Wiring Patterns
+
 Point the LLM client's \`base_url\` at the Respan gateway. The Respan API key authenticates both the proxy and tracing.
 
-### Python (OpenAI SDK)
+#### Python (OpenAI SDK)
 
 \`\`\`python
 import os
@@ -292,7 +663,7 @@ response = client.chat.completions.create(
 )
 \`\`\`
 
-### TypeScript (OpenAI SDK)
+#### TypeScript (OpenAI SDK)
 
 \`\`\`typescript
 import OpenAI from "openai";
@@ -308,7 +679,7 @@ const response = await client.chat.completions.create({
 });
 \`\`\`
 
-### Python (Anthropic SDK)
+#### Python (Anthropic SDK)
 
 \`\`\`python
 import os
@@ -320,7 +691,7 @@ client = anthropic.Anthropic(
 )
 \`\`\`
 
-### Environment variables
+#### Environment variables
 
 Set once, works everywhere:
 
@@ -330,53 +701,9 @@ export OPENAI_API_KEY="$RESPAN_API_KEY"
 export OPENAI_BASE_URL="https://api.respan.ai/api"
 \`\`\`
 
----
-
-## Gateway + Tracing (Both)
-
-Combine SDK tracing and gateway routing:
-
-### Python
-
-\`\`\`python
-import os
-from openai import OpenAI
-from respan import Respan
-
-respan_api_key = os.environ["RESPAN_API_KEY"]
-respan_base_url = os.getenv("RESPAN_BASE_URL", "https://api.respan.ai/api")
-
-respan = Respan(api_key=respan_api_key, base_url=respan_base_url)
-
-client = OpenAI(
-    api_key=respan_api_key,
-    base_url=respan_base_url,
-)
-\`\`\`
-
-### TypeScript
-
-\`\`\`typescript
-import OpenAI from "openai";
-import { Respan } from "@respan/respan";
-
-const respanApiKey = process.env.RESPAN_API_KEY!;
-const respanBaseUrl = process.env.RESPAN_BASE_URL || "https://api.respan.ai/api";
-
-const respan = new Respan({ apiKey: respanApiKey, baseUrl: respanBaseUrl });
-await respan.initialize();
-
-const client = new OpenAI({
-  apiKey: respanApiKey,
-  baseURL: respanBaseUrl,
-});
-\`\`\`
-
----
-
-## Framework-Specific Gateway Setup
+### Framework-Specific Gateway Setup
 
-### CrewAI
+#### CrewAI
 
 \`\`\`python
 import os
@@ -387,7 +714,7 @@ from crewai import Agent, Task, Crew
 # CrewAI uses the env vars automatically
 \`\`\`
 
-### Haystack
+#### Haystack
 
 \`\`\`python
 import os
@@ -398,7 +725,7 @@ from haystack.components.generators import OpenAIGenerator
 # OpenAIGenerator picks up env vars automatically
 \`\`\`
 
-### OpenAI Agents SDK
+#### OpenAI Agents SDK
 
 \`\`\`python
 import os
@@ -406,7 +733,7 @@ os.environ["OPENAI_API_KEY"] = os.environ["RESPAN_API_KEY"]
 os.environ["OPENAI_BASE_URL"] = os.getenv("RESPAN_BASE_URL", "https://api.respan.ai/api")
 \`\`\`
 
-### Pydantic AI
+#### Pydantic AI
 
 \`\`\`python
 import os
@@ -417,9 +744,7 @@ from pydantic_ai import Agent
 agent = Agent(model="openai:gpt-4o-mini")
 \`\`\`
 
----
-
-## Model Switching
+### Model Switching
 
 The gateway supports 250+ models across providers. Use any model name:
 
@@ -439,11 +764,9 @@ response = client.chat.completions.create(model="llama-3.1-70b", ...)
 
 No code changes needed — just change the model string. View all models at \`https://platform.respan.ai/platform/models\`.
 
----
-
-## Advanced Features
+### Advanced Features
 
-### Fallback Models
+#### Fallback Models
 
 Automatic failover if the primary model fails:
 
@@ -457,7 +780,7 @@ response = client.chat.completions.create(
 )
 \`\`\`
 
-### Retries
+#### Retries
 
 \`\`\`python
 response = client.chat.completions.create(
@@ -469,7 +792,7 @@ response = client.chat.completions.create(
 )
 \`\`\`
 
-### Caching
+#### Caching
 
 Enable response caching to save cost on repeated calls:
 
@@ -484,7 +807,7 @@ response = client.chat.completions.create(
 )
 \`\`\`
 
-### Streaming
+#### Streaming
 
 Streaming works normally through the gateway:
 
@@ -498,7 +821,7 @@ for chunk in stream:
     print(chunk.choices[0].delta.content, end="")
 \`\`\`
 
-### Disable Logging
+#### Disable Logging
 
 For sensitive data, disable logging on specific requests:
 
@@ -512,9 +835,7 @@ response = client.chat.completions.create(
 )
 \`\`\`
 
----
-
-## Key Benefits
+### Key Benefits
 
 - **Unified key management** — one Respan API key for all providers
 - **Automatic logging** — every request logged as a span