@axonpush/wizard 0.0.5 → 0.0.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@axonpush/wizard",
-  "version": "0.0.5",
+  "version": "0.0.6",
   "description": "AI-powered wizard to integrate AxonPush into your AI agent project",
   "type": "module",
   "bin": {
@@ -17,16 +17,55 @@
     "start": "bun dist/bin.js",
     "typecheck": "tsc --noEmit"
   },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/axonpush/wizard"
+  },
+  "keywords": [
+    "axonpush",
+    "observability",
+    "tracing",
+    "opentelemetry",
+    "otel",
+    "ai",
+    "agents",
+    "ai-agents",
+    "llm",
+    "sdk",
+    "wizard",
+    "cli",
+    "langchain",
+    "langgraph",
+    "openai",
+    "openai-agents",
+    "anthropic",
+    "claude",
+    "vercel-ai",
+    "mastra",
+    "crewai",
+    "llamaindex",
+    "google-adk",
+    "logging",
+    "pino",
+    "winston",
+    "loguru",
+    "structlog",
+    "typescript",
+    "python"
+  ],
   "dependencies": {
     "@anthropic-ai/claude-agent-sdk": "^0.2.87",
-    "chalk": "^5.4.1",
-    "ora": "^8.2.0",
-    "prompts": "^2.4.2",
+    "ink": "^6.8.0",
+    "ink-select-input": "^6.2.0",
+    "ink-spinner": "^5.0.0",
+    "ink-text-input": "^6.0.0",
+    "js-toml": "^1.0.3",
+    "react": "^19.2.4",
     "yargs": "^17.7.2"
   },
   "devDependencies": {
     "@types/bun": "latest",
-    "@types/prompts": "^2.4.9",
+    "@types/react": "^19.2.14",
     "@types/yargs": "^17.0.33",
     "typescript": "^5.7.0"
   }

package/skills/anthropic/SKILL.md

@@ -50,3 +50,7 @@ tracer = AxonPushAnthropicTracer(
 4. Add imports and create the tracer
 5. Replace `anthropic_client.messages.create(...)` with `tracer.create_message(anthropic_client, ...)`
 6. For tool results, add `tracer.send_tool_result(tool_use_id, result)` calls
+
+## Fail-Open
+
+The SDK is fail-open by default (`fail_open=True`). If AxonPush is unreachable, tracing calls are silently suppressed — the Anthropic integration will never crash or block the user's application.

package/skills/crewai/SKILL.md

@@ -52,3 +52,7 @@ axonpush_callbacks = AxonPushCrewCallbacks(
 5. Add `step_callback=axonpush_callbacks.on_step` and `task_callback=axonpush_callbacks.on_task_complete` to `Crew()`
 6. Add `axonpush_callbacks.on_crew_start()` before `crew.kickoff()`
 7. Add `axonpush_callbacks.on_crew_end(result)` after
+
+## Fail-Open
+
+The SDK is fail-open by default (`fail_open=True`). If AxonPush is unreachable, tracing callbacks are silently suppressed — the CrewAI integration will never crash or block the user's application.

package/skills/{core → custom}/SKILL.md

@@ -1,11 +1,11 @@
 ---
-name: core
-description: Integrate AxonPush event publishing directly without framework-specific callbacks
+name: custom
+description: Integrate AxonPush event publishing directly for custom or unsupported frameworks
 ---
 
-# AxonPush Core SDK Integration
+# AxonPush Custom Framework Integration
 
-Integrate AxonPush event publishing directly (no framework-specific callbacks).
+Integrate AxonPush event publishing directly for custom or unsupported frameworks.
 
 ## What gets added
 
@@ -41,3 +41,7 @@ axonpush_client = AxonPush(
 3. Find the main entry point of the project
 4. Add imports and create the client as a module-level singleton
 5. Add example publish calls at key points (e.g., start, end, error handling)
+
+## Fail-Open
+
+The SDK is fail-open by default (`fail_open=True`). If AxonPush is unreachable, publish calls return `None` instead of raising — the SDK will never crash or block the user's application.

package/skills/deepagents/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: deepagents
+description: Integrate AxonPush tracing into a LangChain Deep Agents project
+---
+
+# AxonPush + Deep Agents Integration
+
+Integrate AxonPush tracing into a project using LangChain Deep Agents (`deepagents` package).
+
+## What gets added
+
+- `AxonPushDeepAgentHandler` that auto-traces chain/LLM/tool lifecycle events with Deep Agent-specific awareness
+- Planning events: `planning.update`, `planning.complete` (when `write_todos` is called)
+- Subagent events: `subagent.spawn`, `subagent.complete` (when `task` tool delegates work)
+- Filesystem events: `filesystem.read`, `filesystem.write` (for `read_file`, `write_file`, `edit_file`, `ls`, `glob`, `grep`)
+- Sandbox events: `sandbox.execute` (for `execute` tool)
+- Standard events: `chain.start/end`, `llm.start/end`, `tool.*.start`, `tool.end`
+
+## Reference Code
+
+```python
+import os
+from deepagents import create_deep_agent
+from axonpush import AxonPush
+from axonpush.integrations.deepagents import AxonPushDeepAgentHandler
+
+axonpush_client = AxonPush(
+    api_key=os.environ["AXONPUSH_API_KEY"],
+    tenant_id=os.environ["AXONPUSH_TENANT_ID"],
+    base_url=os.environ.get("AXONPUSH_BASE_URL", "https://api.axonpush.xyz"),
+)
+
+axonpush_handler = AxonPushDeepAgentHandler(
+    client=axonpush_client,
+    channel_id=int(os.environ["AXONPUSH_CHANNEL_ID"]),
+    agent_id="deep-agent",
+)
+
+agent = create_deep_agent(
+    tools=[],
+    system_prompt="You are a helpful assistant.",
+)
+
+# Run with AxonPush tracing
+result = agent.invoke(
+    {"messages": [{"role": "user", "content": "Research AI frameworks"}]},
+    config={"callbacks": [axonpush_handler]},
+)
+```
+
+## Steps
+
+1. Install `axonpush[deepagents]` using the project's package manager
+2. Add AXONPUSH_API_KEY, AXONPUSH_TENANT_ID, AXONPUSH_BASE_URL, AXONPUSH_CHANNEL_ID to .env
+3. Find the main file where `create_deep_agent()` or `agent.invoke()` is called
+4. Add the imports and client initialization (as module-level code)
+5. Add `config={"callbacks": [axonpush_handler]}` to `.invoke()` calls
+
+## Fail-Open
+
+The SDK is fail-open by default (`fail_open=True`). If AxonPush is unreachable, tracing callbacks are silently suppressed — the Deep Agents integration will never crash or block the user's application.

package/skills/langchain/SKILL.md

@@ -45,3 +45,7 @@ axonpush_handler = AxonPushCallbackHandler(
 3. Find the main file where chains/agents are invoked
 4. Add the imports and client initialization (as module-level code)
 5. Add `config={"callbacks": [axonpush_handler]}` to `.invoke()` calls
+
+## Fail-Open
+
+The SDK is fail-open by default (`fail_open=True`). If AxonPush is unreachable, tracing callbacks are silently suppressed — the LangChain integration will never crash or block the user's application.

package/skills/openai-agents/SKILL.md

@@ -47,3 +47,7 @@ axonpush_hooks = AxonPushRunHooks(
 - OpenAI Agents SDK is **async-only**, so use `AsyncAxonPush` (not `AxonPush`)
 - Make sure to close the client when done: `await axonpush_client.close()`
 - Or use `async with AsyncAxonPush(...) as client:` context manager
+
+## Fail-Open
+
+The SDK is fail-open by default (`fail_open=True`). If AxonPush is unreachable, tracing hooks are silently suppressed — the OpenAI Agents integration will never crash or block the user's application.

package/skills/otel-python/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: otel-python
+description: Wire AxonPushSpanExporter into a Python project's OpenTelemetry TracerProvider
+---
+
+# AxonPush + OpenTelemetry (Python) Integration
+
+Forward OpenTelemetry spans from a Python service into AxonPush via `AxonPushSpanExporter`.
+
+## What gets added
+
+- `AxonPushSpanExporter` attached to the project's `TracerProvider` through a `BatchSpanProcessor`
+- Every OTel span is re-emitted as an `app.span` event with full trace_id, span_id, attributes, events, and links preserved
+
+## Install
+
+Requires the `otel` extra:
+
+```bash
+pip install "axonpush[otel]"
+# or: uv add "axonpush[otel]"
+# or: poetry add "axonpush[otel]"
+```
+
+## Reference Code — New Provider
+
+Use this path when the project does **not** already have a `TracerProvider`.
+
+```python
+import os
+from opentelemetry import trace
+from opentelemetry.sdk.resources import Resource
+from opentelemetry.sdk.trace import TracerProvider
+from opentelemetry.sdk.trace.export import BatchSpanProcessor
+
+from axonpush import AxonPush
+from axonpush.integrations.otel import AxonPushSpanExporter
+
+axonpush_client = AxonPush(
+    api_key=os.environ["AXONPUSH_API_KEY"],
+    tenant_id=os.environ["AXONPUSH_TENANT_ID"],
+    base_url=os.environ.get("AXONPUSH_BASE_URL", "https://api.axonpush.xyz"),
+)
+
+provider = TracerProvider(resource=Resource.create({"service.name": "my-service"}))
+provider.add_span_processor(
+    BatchSpanProcessor(
+        AxonPushSpanExporter(
+            client=axonpush_client,
+            channel_id=int(os.environ["AXONPUSH_CHANNEL_ID"]),
+            service_name="my-service",
+        )
+    )
+)
+trace.set_tracer_provider(provider)
+
+tracer = trace.get_tracer(__name__)
+```
+
+## Reference Code — Existing Provider
+
+Use this path when the project already calls `trace.set_tracer_provider(...)` or uses an auto-instrumentation entrypoint. Never register a second global provider — attach to the existing one.
+
+```python
+from opentelemetry import trace
+from opentelemetry.sdk.trace import TracerProvider
+from opentelemetry.sdk.trace.export import BatchSpanProcessor
+
+from axonpush import AxonPush
+from axonpush.integrations.otel import AxonPushSpanExporter
+
+provider = trace.get_tracer_provider()
+if isinstance(provider, TracerProvider):
+    provider.add_span_processor(
+        BatchSpanProcessor(
+            AxonPushSpanExporter(
+                client=AxonPush(api_key=os.environ["AXONPUSH_API_KEY"], tenant_id=os.environ["AXONPUSH_TENANT_ID"]),
+                channel_id=int(os.environ["AXONPUSH_CHANNEL_ID"]),
+                service_name="my-service",
+            )
+        )
+    )
+```
+
+## Steps
+
+1. Install `axonpush[otel]` using the project's package manager
+2. Add `AXONPUSH_API_KEY`, `AXONPUSH_TENANT_ID`, `AXONPUSH_BASE_URL`, `AXONPUSH_CHANNEL_ID` to `.env`
+3. Detect whether a `TracerProvider` already exists in the project (search for `set_tracer_provider`, `TracerProvider(`, or auto-instrumentation setup in the main module)
+4. If one exists, attach `AxonPushSpanExporter` to it via `BatchSpanProcessor`
+5. If none exists, create one (see "New Provider") using the project name as `service.name`
+6. Use `BatchSpanProcessor`, never `SimpleSpanProcessor`, in production
+
+## Fail-Open
+
+`AxonPush(fail_open=True)` is the default. If AxonPush is unreachable the exporter silently drops spans — no application impact.

package/skills/otel-ts/SKILL.md

@@ -0,0 +1,89 @@
+---
+name: otel-ts
+description: Wire AxonPushSpanExporter into a TypeScript/Node project's OpenTelemetry TracerProvider
+---
+
+# AxonPush + OpenTelemetry (TypeScript) Integration
+
+Forward OpenTelemetry spans from a Node.js service into AxonPush via `AxonPushSpanExporter`.
+
+## What gets added
+
+- `AxonPushSpanExporter` attached to the project's `TracerProvider` through a `BatchSpanProcessor`
+- Every OTel span is re-emitted as an `app.span` event with full traceId, spanId, attributes, events, and links preserved
+
+## Install
+
+`@opentelemetry/api` and `@opentelemetry/sdk-trace-base` are optional peer dependencies. Install them alongside `@axonpush/sdk`:
+
+```bash
+bun add @axonpush/sdk @opentelemetry/api @opentelemetry/sdk-trace-base @opentelemetry/sdk-trace-node
+# or pnpm / yarn / npm equivalents
+```
+
+## Reference Code — New Provider
+
+```typescript
+import { AxonPush } from "@axonpush/sdk";
+import { AxonPushSpanExporter } from "@axonpush/sdk/integrations/otel";
+import { NodeTracerProvider } from "@opentelemetry/sdk-trace-node";
+import { BatchSpanProcessor } from "@opentelemetry/sdk-trace-base";
+import { Resource } from "@opentelemetry/resources";
+import { SemanticResourceAttributes } from "@opentelemetry/semantic-conventions";
+
+const axonpush = new AxonPush({
+  apiKey: process.env.AXONPUSH_API_KEY!,
+  tenantId: process.env.AXONPUSH_TENANT_ID!,
+  baseUrl: process.env.AXONPUSH_BASE_URL,
+});
+
+const provider = new NodeTracerProvider({
+  resource: new Resource({ [SemanticResourceAttributes.SERVICE_NAME]: "my-service" }),
+});
+
+provider.addSpanProcessor(
+  new BatchSpanProcessor(
+    new AxonPushSpanExporter({
+      client: axonpush,
+      channelId: Number(process.env.AXONPUSH_CHANNEL_ID),
+      serviceName: "my-service",
+    }),
+  ),
+);
+
+provider.register();
+```
+
+## Reference Code — Existing Provider
+
+Use this path when the project already registers a `TracerProvider` (e.g. via `provider.register()` or `@opentelemetry/sdk-node`). Attach to the existing provider rather than creating a second one.
+
+```typescript
+import { trace } from "@opentelemetry/api";
+import { BatchSpanProcessor, BasicTracerProvider } from "@opentelemetry/sdk-trace-base";
+import { AxonPushSpanExporter } from "@axonpush/sdk/integrations/otel";
+
+const provider = trace.getTracerProvider() as unknown as BasicTracerProvider;
+provider.addSpanProcessor(
+  new BatchSpanProcessor(
+    new AxonPushSpanExporter({
+      client: axonpush,
+      channelId: Number(process.env.AXONPUSH_CHANNEL_ID),
+      serviceName: "my-service",
+    }),
+  ),
+);
+```
+
+## Steps
+
+1. Install `@axonpush/sdk @opentelemetry/api @opentelemetry/sdk-trace-base @opentelemetry/sdk-trace-node` using the project's package manager
+2. Add `AXONPUSH_API_KEY`, `AXONPUSH_TENANT_ID`, `AXONPUSH_BASE_URL`, `AXONPUSH_CHANNEL_ID` to `.env`
+3. Detect whether a `TracerProvider` already exists in the project (search for `provider.register()`, `NodeTracerProvider(`, `NodeSDK(`, or auto-instrumentation setup)
+4. If one exists, attach `AxonPushSpanExporter` to it via `BatchSpanProcessor`
+5. If none exists, create one (see "New Provider") using the project name as `service.name`
+6. Use `BatchSpanProcessor`, never `SimpleSpanProcessor`, in production
+
+## Fail-Open
+
+`new AxonPush({ failOpen: true })` is the default. If AxonPush is unreachable the exporter silently drops spans — no application impact.

package/skills/ts-anthropic/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: ts-anthropic
+description: Integrate AxonPush tracing into a TypeScript Anthropic SDK project
+---
+
+# AxonPush + Anthropic/Claude (TypeScript) Integration
+
+Integrate AxonPush tracing into a TypeScript project using the Anthropic SDK.
+
+## What gets added
+
+- `AxonPushAnthropicTracer` that wraps `messages.create()` to trace conversations, tool use, and responses
+- Events: `conversation.turn`, `tool.*.start`, `agent.response`, `tool.result`
+
+## Reference Code
+
+```typescript
+import { AxonPush } from "@axonpush/sdk";
+import { AxonPushAnthropicTracer } from "@axonpush/sdk/integrations/anthropic";
+
+const axonpush = new AxonPush({
+  apiKey: process.env.AXONPUSH_API_KEY!,
+  tenantId: process.env.AXONPUSH_TENANT_ID!,
+  baseUrl: process.env.AXONPUSH_BASE_URL,
+});
+
+const tracer = new AxonPushAnthropicTracer({
+  client: axonpush,
+  channelId: Number(process.env.AXONPUSH_CHANNEL_ID),
+  agentId: "claude-agent",
+});
+
+// Instead of: const response = await anthropic.messages.create(params)
+// Use:        const response = await tracer.createMessage(anthropic, params)
+
+// For tool results:
+// tracer.sendToolResult(toolUseId, result)
+```
+
+## Steps
+
+1. Install `@axonpush/sdk` using the project's package manager
+2. Add AXONPUSH_API_KEY, AXONPUSH_TENANT_ID, AXONPUSH_BASE_URL, AXONPUSH_CHANNEL_ID to .env
+3. Find files that call `client.messages.create()` (the Anthropic API)
+4. Add imports and create the tracer
+5. Replace `anthropic.messages.create(params)` with `tracer.createMessage(anthropic, params)`
+6. For tool results, add `tracer.sendToolResult(toolUseId, result)` calls
+
+## Fail-Open
+
+The SDK is fail-open by default (`failOpen: true`). If AxonPush is unreachable, tracing calls are silently suppressed.

package/skills/ts-custom/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: ts-custom
+description: Integrate AxonPush event publishing directly for custom TypeScript frameworks
+---
+
+# AxonPush Custom Framework Integration (TypeScript)
+
+Integrate AxonPush event publishing directly for custom or unsupported TypeScript frameworks.
+
+## What gets added
+
+- `AxonPush` client for publishing custom events
+- Use `client.events.publish()` to send events from anywhere in your code
+
+## Reference Code
+
+```typescript
+import { AxonPush } from "@axonpush/sdk";
+
+const axonpush = new AxonPush({
+  apiKey: process.env.AXONPUSH_API_KEY!,
+  tenantId: process.env.AXONPUSH_TENANT_ID!,
+  baseUrl: process.env.AXONPUSH_BASE_URL,
+});
+
+// Publish events from your code:
+// await axonpush.events.publish({
+//   identifier: "my.event",
+//   payload: { key: "value" },
+//   channelId: Number(process.env.AXONPUSH_CHANNEL_ID),
+//   agentId: "my-agent",
+//   eventType: "custom",
+// });
+```
+
+## Steps
+
+1. Install `@axonpush/sdk` using the project's package manager
+2. Add AXONPUSH_API_KEY, AXONPUSH_TENANT_ID, AXONPUSH_BASE_URL, AXONPUSH_CHANNEL_ID to .env
+3. Find the main entry point of the project
+4. Add imports and create the client as a module-level singleton
+5. Add example publish calls at key points (e.g., start, end, error handling)
+
+## Fail-Open
+
+The SDK is fail-open by default (`failOpen: true`). If AxonPush is unreachable, publish calls are silently suppressed.

package/skills/ts-google-adk/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: ts-google-adk
+description: Integrate AxonPush tracing into a Google ADK project
+---
+
+# AxonPush + Google ADK Integration
+
+Integrate AxonPush tracing into a project using the Google AI Development Kit.
+
+## What gets added
+
+- `axonPushADKCallbacks` with agent, model, and tool lifecycle callbacks
+- Events: `agent.start`, `agent.end`, `llm.start`, `llm.end`, `tool.*.start`, `tool.*.end`
+
+## Reference Code
+
+```typescript
+import { AxonPush } from "@axonpush/sdk";
+import { axonPushADKCallbacks } from "@axonpush/sdk/integrations/google-adk";
+
+const axonpush = new AxonPush({
+  apiKey: process.env.AXONPUSH_API_KEY!,
+  tenantId: process.env.AXONPUSH_TENANT_ID!,
+  baseUrl: process.env.AXONPUSH_BASE_URL,
+});
+
+const callbacks = axonPushADKCallbacks({
+  client: axonpush,
+  channelId: Number(process.env.AXONPUSH_CHANNEL_ID),
+  agentId: "google-adk",
+});
+
+// Register callbacks on your ADK agent:
+// callbacks.beforeAgent(agent);
+// callbacks.afterAgent(agent, output);
+// callbacks.beforeModel(model, params);
+// callbacks.afterModel(model, response);
+// callbacks.beforeTool(tool, input);
+// callbacks.afterTool(tool, output);
+```
+
+## Steps
+
+1. Install `@axonpush/sdk` using the project's package manager
+2. Add AXONPUSH_API_KEY, AXONPUSH_TENANT_ID, AXONPUSH_BASE_URL, AXONPUSH_CHANNEL_ID to .env
+3. Find the main file where the ADK agent is configured
+4. Add imports and create the callbacks
+5. Register the callbacks at the appropriate lifecycle points
+
+## Fail-Open
+
+The SDK is fail-open by default (`failOpen: true`). If AxonPush is unreachable, callbacks are silently suppressed.

package/skills/ts-langchain/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: ts-langchain
+description: Integrate AxonPush tracing into a TypeScript LangChain project
+---
+
+# AxonPush + LangChain (TypeScript) Integration
+
+Integrate AxonPush tracing into a TypeScript LangChain project.
+
+## What gets added
+
+- `AxonPushCallbackHandler` that auto-traces chain/LLM/tool lifecycle events
+- Events: `chain.start`, `chain.end`, `llm.start`, `llm.end`, `tool.*.start`, `tool.end`
+
+## Reference Code
+
+```typescript
+import { AxonPush } from "@axonpush/sdk";
+import { AxonPushCallbackHandler } from "@axonpush/sdk/integrations/langchain";
+
+const axonpush = new AxonPush({
+  apiKey: process.env.AXONPUSH_API_KEY!,
+  tenantId: process.env.AXONPUSH_TENANT_ID!,
+  baseUrl: process.env.AXONPUSH_BASE_URL,
+});
+
+const handler = new AxonPushCallbackHandler({
+  client: axonpush,
+  channelId: Number(process.env.AXONPUSH_CHANNEL_ID),
+  agentId: "my-agent",
+});
+
+// For any chain:
+// const result = await chain.invoke(input, { callbacks: [handler] });
+
+// For an agent executor:
+// const result = await agentExecutor.invoke(input, { callbacks: [handler] });
+```
+
+## Steps
+
+1. Install `@axonpush/sdk` using the project's package manager
+2. Add AXONPUSH_API_KEY, AXONPUSH_TENANT_ID, AXONPUSH_BASE_URL, AXONPUSH_CHANNEL_ID to .env
+3. Find the main file where chains/agents are invoked
+4. Add the imports and client initialization (as module-level code)
+5. Add `{ callbacks: [handler] }` to `.invoke()` calls
+
+## Fail-Open
+
+The SDK is fail-open by default (`failOpen: true`). If AxonPush is unreachable, tracing callbacks are silently suppressed.

package/skills/ts-langgraph/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: ts-langgraph
+description: Integrate AxonPush tracing into a TypeScript LangGraph project
+---
+
+# AxonPush + LangGraph (TypeScript) Integration
+
+Integrate AxonPush tracing into a TypeScript LangGraph project.
+
+## What gets added
+
+- `AxonPushLangGraphHandler` that extends `AxonPushCallbackHandler` with graph node-level tracing
+- Events: `chain.start`, `chain.end`, `graph.node.start`, `graph.node.end`, `llm.start`, `llm.end`, `tool.*.start`, `tool.end`
+
+## Reference Code
+
+```typescript
+import { AxonPush } from "@axonpush/sdk";
+import { AxonPushLangGraphHandler } from "@axonpush/sdk/integrations/langgraph";
+
+const axonpush = new AxonPush({
+  apiKey: process.env.AXONPUSH_API_KEY!,
+  tenantId: process.env.AXONPUSH_TENANT_ID!,
+  baseUrl: process.env.AXONPUSH_BASE_URL,
+});
+
+const handler = new AxonPushLangGraphHandler({
+  client: axonpush,
+  channelId: Number(process.env.AXONPUSH_CHANNEL_ID),
+  agentId: "langgraph-agent",
+});
+
+// const result = await graph.invoke(input, { callbacks: [handler] });
+```
+
+## Steps
+
+1. Install `@axonpush/sdk` using the project's package manager
+2. Add AXONPUSH_API_KEY, AXONPUSH_TENANT_ID, AXONPUSH_BASE_URL, AXONPUSH_CHANNEL_ID to .env
+3. Find the main file where the LangGraph graph is invoked
+4. Add the imports and client initialization (as module-level code)
+5. Add `{ callbacks: [handler] }` to `.invoke()` calls
+
+## Fail-Open
+
+The SDK is fail-open by default (`failOpen: true`). If AxonPush is unreachable, tracing callbacks are silently suppressed.

package/skills/ts-llamaindex/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: ts-llamaindex
+description: Integrate AxonPush tracing into a TypeScript LlamaIndex project
+---
+
+# AxonPush + LlamaIndex (TypeScript) Integration
+
+Integrate AxonPush tracing into a TypeScript LlamaIndex project.
+
+## What gets added
+
+- `AxonPushLlamaIndexHandler` with LLM, embedding, retriever, and query lifecycle methods
+- Events: `llm.start`, `llm.end`, `llm.token`, `embedding.start`, `embedding.end`, `retriever.query`, `retriever.result`, `query.start`, `query.end`
+
+## Reference Code
+
+```typescript
+import { AxonPush } from "@axonpush/sdk";
+import { AxonPushLlamaIndexHandler } from "@axonpush/sdk/integrations/llamaindex";
+
+const axonpush = new AxonPush({
+  apiKey: process.env.AXONPUSH_API_KEY!,
+  tenantId: process.env.AXONPUSH_TENANT_ID!,
+  baseUrl: process.env.AXONPUSH_BASE_URL,
+});
+
+const handler = new AxonPushLlamaIndexHandler({
+  client: axonpush,
+  channelId: Number(process.env.AXONPUSH_CHANNEL_ID),
+  agentId: "llamaindex",
+});
+
+// Call handler methods at the appropriate points:
+// handler.onQueryStart("What is...");
+// handler.onLLMStart("gpt-4", 1);
+// handler.onLLMEnd(output);
+// handler.onRetrieverStart("What is...");
+// handler.onRetrieverEnd(5);
+// handler.onQueryEnd(response);
+```
+
+## Steps
+
+1. Install `@axonpush/sdk` using the project's package manager
+2. Add AXONPUSH_API_KEY, AXONPUSH_TENANT_ID, AXONPUSH_BASE_URL, AXONPUSH_CHANNEL_ID to .env
+3. Find the main query engine or retrieval pipeline
+4. Add imports and create the handler
+5. Call the appropriate handler methods at each lifecycle point
+
+## Fail-Open
+
+The SDK is fail-open by default (`failOpen: true`). If AxonPush is unreachable, handler calls are silently suppressed.