autotel 3.0.0 → 3.0.4

package/dist/semantic-helpers.cjs

@@ -1,16 +1,16 @@
 'use strict';
 
-var chunkL7JDUDJD_cjs = require('./chunk-L7JDUDJD.cjs');
-require('./chunk-MOK3E54E.cjs');
+var chunkAAYCDHH6_cjs = require('./chunk-AAYCDHH6.cjs');
+require('./chunk-WSGAHSZQ.cjs');
 require('./chunk-NCSMD3TK.cjs');
 require('./chunk-VQTCQKHQ.cjs');
-require('./chunk-CJ4PD2TZ.cjs');
-require('./chunk-563EL6O6.cjs');
+require('./chunk-KKGM42RQ.cjs');
+require('./chunk-BPO2PQ3T.cjs');
 require('./chunk-OC6X2VIN.cjs');
 require('./chunk-CEAQK2QY.cjs');
 require('./chunk-ZNMBW67B.cjs');
 require('./chunk-IOYFAFHJ.cjs');
-require('./chunk-CMNGGTQL.cjs');
+require('./chunk-NXLRY2CE.cjs');
 require('./chunk-CU6IDACR.cjs');
 require('./chunk-6S5RUKU3.cjs');
 require('./chunk-YS6C2YJE.cjs');
@@ -24,19 +24,19 @@ require('./chunk-JEQ2X3Z6.cjs');
 
 Object.defineProperty(exports, "traceDB", {
   enumerable: true,
-  get: function () { return chunkL7JDUDJD_cjs.traceDB; }
+  get: function () { return chunkAAYCDHH6_cjs.traceDB; }
 });
 Object.defineProperty(exports, "traceHTTP", {
   enumerable: true,
-  get: function () { return chunkL7JDUDJD_cjs.traceHTTP; }
+  get: function () { return chunkAAYCDHH6_cjs.traceHTTP; }
 });
 Object.defineProperty(exports, "traceLLM", {
   enumerable: true,
-  get: function () { return chunkL7JDUDJD_cjs.traceLLM; }
+  get: function () { return chunkAAYCDHH6_cjs.traceLLM; }
 });
 Object.defineProperty(exports, "traceMessaging", {
   enumerable: true,
-  get: function () { return chunkL7JDUDJD_cjs.traceMessaging; }
+  get: function () { return chunkAAYCDHH6_cjs.traceMessaging; }
 });
 //# sourceMappingURL=semantic-helpers.cjs.map
 //# sourceMappingURL=semantic-helpers.cjs.map

package/dist/semantic-helpers.js

@@ -1,14 +1,14 @@
-export { traceDB, traceHTTP, traceLLM, traceMessaging } from './chunk-7HNQYHK4.js';
-import './chunk-DAAJLUTO.js';
+export { traceDB, traceHTTP, traceLLM, traceMessaging } from './chunk-HBLWOI6P.js';
+import './chunk-F3TNRW2P.js';
 import './chunk-DSMSIVTG.js';
 import './chunk-SEO6NAQT.js';
-import './chunk-QG3U5ONP.js';
-import './chunk-W35FVJBC.js';
+import './chunk-Z7VAOK5X.js';
+import './chunk-ZDPIWKWD.js';
 import './chunk-3SDILILG.js';
 import './chunk-A4E5AQFK.js';
 import './chunk-WGWSHJ2N.js';
 import './chunk-GYR5K654.js';
-import './chunk-TDNKIHKT.js';
+import './chunk-JVWJDHDB.js';
 import './chunk-6UQRVUN3.js';
 import './chunk-3QXBFGKP.js';
 import './chunk-33WTKH7X.js';

package/dist/webhook.cjs

@@ -1,16 +1,16 @@
 'use strict';
 
 var chunk4P6ZOARG_cjs = require('./chunk-4P6ZOARG.cjs');
-var chunkMOK3E54E_cjs = require('./chunk-MOK3E54E.cjs');
+var chunkWSGAHSZQ_cjs = require('./chunk-WSGAHSZQ.cjs');
 require('./chunk-NCSMD3TK.cjs');
 require('./chunk-VQTCQKHQ.cjs');
-var chunkCJ4PD2TZ_cjs = require('./chunk-CJ4PD2TZ.cjs');
-require('./chunk-563EL6O6.cjs');
+var chunkKKGM42RQ_cjs = require('./chunk-KKGM42RQ.cjs');
+require('./chunk-BPO2PQ3T.cjs');
 require('./chunk-OC6X2VIN.cjs');
 require('./chunk-CEAQK2QY.cjs');
 require('./chunk-ZNMBW67B.cjs');
 require('./chunk-IOYFAFHJ.cjs');
-require('./chunk-CMNGGTQL.cjs');
+require('./chunk-NXLRY2CE.cjs');
 require('./chunk-CU6IDACR.cjs');
 require('./chunk-6S5RUKU3.cjs');
 require('./chunk-YS6C2YJE.cjs');
@@ -158,7 +158,7 @@ function createParkingLot(config) {
     },
     traceCallback(callbackConfig) {
       return (fnFactory) => {
-        return chunkMOK3E54E_cjs.trace(
+        return chunkWSGAHSZQ_cjs.trace(
           {
             name: callbackConfig.name,
             spanKind: api.SpanKind.SERVER
@@ -202,7 +202,7 @@ function createParkingLot(config) {
                   const error = new Error(
                     `Required parked context not found for key: ${correlationKey}`
                   );
-                  chunkCJ4PD2TZ_cjs.recordStructuredError(baseCtx, error);
+                  chunkKKGM42RQ_cjs.recordStructuredError(baseCtx, error);
                   throw error;
                 }
               }

package/dist/webhook.js

@@ -1,14 +1,14 @@
 import { emitCorrelatedEvent } from './chunk-KIL5CUN6.js';
-import { trace } from './chunk-DAAJLUTO.js';
+import { trace } from './chunk-F3TNRW2P.js';
 import './chunk-DSMSIVTG.js';
 import './chunk-SEO6NAQT.js';
-import { recordStructuredError } from './chunk-QG3U5ONP.js';
-import './chunk-W35FVJBC.js';
+import { recordStructuredError } from './chunk-Z7VAOK5X.js';
+import './chunk-ZDPIWKWD.js';
 import './chunk-3SDILILG.js';
 import './chunk-A4E5AQFK.js';
 import './chunk-WGWSHJ2N.js';
 import './chunk-GYR5K654.js';
-import './chunk-TDNKIHKT.js';
+import './chunk-JVWJDHDB.js';
 import './chunk-6UQRVUN3.js';
 import './chunk-3QXBFGKP.js';
 import './chunk-33WTKH7X.js';

package/dist/workflow-distributed.cjs

@@ -2,16 +2,16 @@
 
 var chunk4P6ZOARG_cjs = require('./chunk-4P6ZOARG.cjs');
 var chunkINJD3G4K_cjs = require('./chunk-INJD3G4K.cjs');
-var chunkMOK3E54E_cjs = require('./chunk-MOK3E54E.cjs');
+var chunkWSGAHSZQ_cjs = require('./chunk-WSGAHSZQ.cjs');
 require('./chunk-NCSMD3TK.cjs');
 require('./chunk-VQTCQKHQ.cjs');
-require('./chunk-CJ4PD2TZ.cjs');
-require('./chunk-563EL6O6.cjs');
+require('./chunk-KKGM42RQ.cjs');
+require('./chunk-BPO2PQ3T.cjs');
 require('./chunk-OC6X2VIN.cjs');
 require('./chunk-CEAQK2QY.cjs');
 require('./chunk-ZNMBW67B.cjs');
 require('./chunk-IOYFAFHJ.cjs');
-require('./chunk-CMNGGTQL.cjs');
+require('./chunk-NXLRY2CE.cjs');
 require('./chunk-CU6IDACR.cjs');
 require('./chunk-6S5RUKU3.cjs');
 require('./chunk-YS6C2YJE.cjs');
@@ -59,7 +59,7 @@ var WorkflowBaggage = chunkINJD3G4K_cjs.createSafeBaggageSchema(workflowBaggageF
 function traceDistributedWorkflow(config) {
   const spanName = `workflow.${config.name}`;
   return (fnFactory) => {
-    return chunkMOK3E54E_cjs.trace(
+    return chunkWSGAHSZQ_cjs.trace(
       { name: spanName, spanKind: api.SpanKind.INTERNAL },
       (baseCtx) => {
         return async (...args) => {
@@ -158,7 +158,7 @@ function traceDistributedWorkflow(config) {
 function traceDistributedStep(config) {
   const spanName = `workflow.step.${config.name}`;
   return (fnFactory) => {
-    return chunkMOK3E54E_cjs.trace(
+    return chunkWSGAHSZQ_cjs.trace(
       { name: spanName, spanKind: api.SpanKind.INTERNAL },
       (baseCtx) => {
         return async (...args) => {

package/dist/workflow-distributed.js

@@ -1,15 +1,15 @@
 import { emitCorrelatedEvent } from './chunk-KIL5CUN6.js';
 import { createSafeBaggageSchema } from './chunk-4IFSYQVX.js';
-import { trace } from './chunk-DAAJLUTO.js';
+import { trace } from './chunk-F3TNRW2P.js';
 import './chunk-DSMSIVTG.js';
 import './chunk-SEO6NAQT.js';
-import './chunk-QG3U5ONP.js';
-import './chunk-W35FVJBC.js';
+import './chunk-Z7VAOK5X.js';
+import './chunk-ZDPIWKWD.js';
 import './chunk-3SDILILG.js';
 import './chunk-A4E5AQFK.js';
 import './chunk-WGWSHJ2N.js';
 import './chunk-GYR5K654.js';
-import './chunk-TDNKIHKT.js';
+import './chunk-JVWJDHDB.js';
 import './chunk-6UQRVUN3.js';
 import './chunk-3QXBFGKP.js';
 import './chunk-33WTKH7X.js';

package/dist/workflow.cjs

@@ -1,17 +1,17 @@
 'use strict';
 
-var chunkDWOBIBLY_cjs = require('./chunk-DWOBIBLY.cjs');
+var chunkAY2SY3MO_cjs = require('./chunk-AY2SY3MO.cjs');
 require('./chunk-4P6ZOARG.cjs');
-require('./chunk-MOK3E54E.cjs');
+require('./chunk-WSGAHSZQ.cjs');
 require('./chunk-NCSMD3TK.cjs');
 require('./chunk-VQTCQKHQ.cjs');
-require('./chunk-CJ4PD2TZ.cjs');
-require('./chunk-563EL6O6.cjs');
+require('./chunk-KKGM42RQ.cjs');
+require('./chunk-BPO2PQ3T.cjs');
 require('./chunk-OC6X2VIN.cjs');
 require('./chunk-CEAQK2QY.cjs');
 require('./chunk-ZNMBW67B.cjs');
 require('./chunk-IOYFAFHJ.cjs');
-require('./chunk-CMNGGTQL.cjs');
+require('./chunk-NXLRY2CE.cjs');
 require('./chunk-CU6IDACR.cjs');
 require('./chunk-6S5RUKU3.cjs');
 require('./chunk-YS6C2YJE.cjs');
@@ -25,19 +25,19 @@ require('./chunk-JEQ2X3Z6.cjs');
 
 Object.defineProperty(exports, "getCurrentWorkflowContext", {
   enumerable: true,
-  get: function () { return chunkDWOBIBLY_cjs.getCurrentWorkflowContext; }
+  get: function () { return chunkAY2SY3MO_cjs.getCurrentWorkflowContext; }
 });
 Object.defineProperty(exports, "isInWorkflow", {
   enumerable: true,
-  get: function () { return chunkDWOBIBLY_cjs.isInWorkflow; }
+  get: function () { return chunkAY2SY3MO_cjs.isInWorkflow; }
 });
 Object.defineProperty(exports, "traceStep", {
   enumerable: true,
-  get: function () { return chunkDWOBIBLY_cjs.traceStep; }
+  get: function () { return chunkAY2SY3MO_cjs.traceStep; }
 });
 Object.defineProperty(exports, "traceWorkflow", {
   enumerable: true,
-  get: function () { return chunkDWOBIBLY_cjs.traceWorkflow; }
+  get: function () { return chunkAY2SY3MO_cjs.traceWorkflow; }
 });
 //# sourceMappingURL=workflow.cjs.map
 //# sourceMappingURL=workflow.cjs.map

package/dist/workflow.js

@@ -1,15 +1,15 @@
-export { getCurrentWorkflowContext, isInWorkflow, traceStep, traceWorkflow } from './chunk-3QMFLJHJ.js';
+export { getCurrentWorkflowContext, isInWorkflow, traceStep, traceWorkflow } from './chunk-4LF6FV2V.js';
 import './chunk-KIL5CUN6.js';
-import './chunk-DAAJLUTO.js';
+import './chunk-F3TNRW2P.js';
 import './chunk-DSMSIVTG.js';
 import './chunk-SEO6NAQT.js';
-import './chunk-QG3U5ONP.js';
-import './chunk-W35FVJBC.js';
+import './chunk-Z7VAOK5X.js';
+import './chunk-ZDPIWKWD.js';
 import './chunk-3SDILILG.js';
 import './chunk-A4E5AQFK.js';
 import './chunk-WGWSHJ2N.js';
 import './chunk-GYR5K654.js';
-import './chunk-TDNKIHKT.js';
+import './chunk-JVWJDHDB.js';
 import './chunk-6UQRVUN3.js';
 import './chunk-3QXBFGKP.js';
 import './chunk-33WTKH7X.js';

package/package.json

@@ -1,11 +1,14 @@
 {
   "name": "autotel",
-  "version": "3.0.0",
+  "version": "3.0.4",
   "description": "Write Once, Observe Anywhere",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "type": "module",
-  "sideEffects": false,
+  "sideEffects": [
+    "./dist/chunk-*.js",
+    "./dist/chunk-*.cjs"
+  ],
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
@@ -225,9 +228,7 @@
     "dist",
     "src",
     "README.md",
-    "skills",
-    "!skills/_artifacts",
-    "bin"
+    "skills"
   ],
   "keywords": [
     "opentelemetry",
@@ -250,33 +251,32 @@
   "license": "MIT",
   "dependencies": {
     "@opentelemetry/api": "^1.9.1",
-    "@opentelemetry/api-logs": "^0.215.0",
-    "@opentelemetry/exporter-logs-otlp-http": "^0.215.0",
-    "@opentelemetry/exporter-metrics-otlp-http": "^0.215.0",
-    "@opentelemetry/exporter-trace-otlp-http": "^0.215.0",
-    "@opentelemetry/instrumentation": "^0.215.0",
-    "@opentelemetry/resources": "^2.7.0",
-    "@opentelemetry/sdk-logs": "^0.215.0",
-    "@opentelemetry/sdk-metrics": "^2.7.0",
-    "@opentelemetry/sdk-node": "^0.215.0",
-    "@opentelemetry/sdk-trace-base": "^2.7.0",
+    "@opentelemetry/api-logs": "^0.216.0",
+    "@opentelemetry/exporter-logs-otlp-http": "^0.216.0",
+    "@opentelemetry/exporter-metrics-otlp-http": "^0.216.0",
+    "@opentelemetry/exporter-trace-otlp-http": "^0.216.0",
+    "@opentelemetry/instrumentation": "^0.216.0",
+    "@opentelemetry/resources": "^2.7.1",
+    "@opentelemetry/sdk-logs": "^0.216.0",
+    "@opentelemetry/sdk-metrics": "^2.7.1",
+    "@opentelemetry/sdk-node": "^0.216.0",
+    "@opentelemetry/sdk-trace-base": "^2.7.1",
     "@opentelemetry/semantic-conventions": "^1.40.0",
-    "import-in-the-middle": "^3.0.1",
-    "@tanstack/intent": "^0.0.36"
+    "import-in-the-middle": "^3.0.1"
   },
   "peerDependencies": {
-    "@opentelemetry/auto-instrumentations-node": "^0.73.0",
-    "@opentelemetry/exporter-logs-otlp-grpc": "^0.215.0",
-    "@opentelemetry/exporter-metrics-otlp-grpc": "^0.215.0",
-    "@opentelemetry/exporter-trace-otlp-grpc": "^0.215.0",
-    "@opentelemetry/resource-detector-aws": "^2.15.0",
-    "@opentelemetry/resource-detector-container": "^0.8.6",
-    "@opentelemetry/resource-detector-gcp": "^0.50.0",
-    "@opentelemetry/sdk-trace-node": "^2.7.0",
+    "@opentelemetry/auto-instrumentations-node": "^0.74.0",
+    "@opentelemetry/exporter-logs-otlp-grpc": "^0.216.0",
+    "@opentelemetry/exporter-metrics-otlp-grpc": "^0.216.0",
+    "@opentelemetry/exporter-trace-otlp-grpc": "^0.216.0",
+    "@opentelemetry/resource-detector-aws": "^2.16.0",
+    "@opentelemetry/resource-detector-container": "^0.8.7",
+    "@opentelemetry/resource-detector-gcp": "^0.51.0",
+    "@opentelemetry/sdk-trace-node": "^2.7.1",
     "@traceloop/node-server-sdk": "^0.26.0",
     "pino": "^10.3.1",
     "pino-pretty": "^13.1.3",
-    "yaml": "^2.8.3"
+    "yaml": "^2.8.4"
   },
   "peerDependenciesMeta": {
     "@opentelemetry/auto-instrumentations-node": {
@@ -319,22 +319,22 @@
   "devDependencies": {
     "@arethetypeswrong/cli": "^0.18.2",
     "@edge-runtime/vm": "^5.0.0",
-    "@opentelemetry/auto-instrumentations-node": "^0.73.0",
-    "@opentelemetry/context-async-hooks": "^2.7.0",
-    "@opentelemetry/exporter-logs-otlp-grpc": "^0.215.0",
-    "@opentelemetry/exporter-metrics-otlp-grpc": "^0.215.0",
-    "@opentelemetry/exporter-trace-otlp-grpc": "^0.215.0",
-    "@opentelemetry/resource-detector-aws": "^2.15.0",
-    "@opentelemetry/resource-detector-container": "^0.8.6",
-    "@opentelemetry/resource-detector-gcp": "^0.50.0",
-    "@opentelemetry/sdk-trace-node": "^2.7.0",
-    "@swc/core": "^1.15.30",
+    "@opentelemetry/auto-instrumentations-node": "^0.74.0",
+    "@opentelemetry/context-async-hooks": "^2.7.1",
+    "@opentelemetry/exporter-logs-otlp-grpc": "^0.216.0",
+    "@opentelemetry/exporter-metrics-otlp-grpc": "^0.216.0",
+    "@opentelemetry/exporter-trace-otlp-grpc": "^0.216.0",
+    "@opentelemetry/resource-detector-aws": "^2.16.0",
+    "@opentelemetry/resource-detector-container": "^0.8.7",
+    "@opentelemetry/resource-detector-gcp": "^0.51.0",
+    "@opentelemetry/sdk-trace-node": "^2.7.1",
+    "@swc/core": "^1.15.32",
     "@total-typescript/ts-reset": "^0.6.1",
     "@total-typescript/tsconfig": "^1.0.4",
     "@types/eslint-config-prettier": "^6.11.3",
     "@types/node": "^25.6.0",
-    "@typescript-eslint/eslint-plugin": "^8.59.0",
-    "@typescript-eslint/parser": "^8.59.0",
+    "@typescript-eslint/eslint-plugin": "^8.59.1",
+    "@typescript-eslint/parser": "^8.59.1",
     "eslint-config-prettier": "^10.1.8",
     "eslint-plugin-unicorn": "^64.0.0",
     "pino": "^10.3.1",
@@ -343,13 +343,13 @@
     "tsup": "^8.5.1",
     "tsx": "^4.21.0",
     "typescript": "^6.0.3",
-    "typescript-eslint": "^8.59.0",
+    "typescript-eslint": "^8.59.1",
     "unplugin-swc": "^1.5.9",
     "vite-tsconfig-paths": "^6.1.1",
     "vitest": "^4.1.5",
     "vitest-mock-extended": "^4.0.0",
     "winston": "^3.19.0",
-    "yaml": "^2.8.3"
+    "yaml": "^2.8.4"
   },
   "repository": {
     "type": "git",
@@ -359,15 +359,12 @@
     "url": "https://github.com/jagreehal/autotel/issues"
   },
   "homepage": "https://github.com/jagreehal/autotel#readme",
-  "bin": {
-    "intent": "./bin/intent.js"
-  },
   "scripts": {
     "build": "tsup",
     "ci": "npm run build && npm run check-format && npm run check-exports && npm run lint && npm run test",
     "dev": "tsup --watch",
-    "lint": "npx eslint src/**/*.ts",
-    "lint:fix": "npx eslint src/**/*.ts --fix",
+    "lint": "eslint src/**/*.ts",
+    "lint:fix": "eslint src/**/*.ts --fix",
     "format": "prettier --write .",
     "format:check": "prettier --check src/**/*.ts",
     "type-check": "tsc --noEmit",
@@ -375,6 +372,7 @@
     "test:watch": "vitest --config vitest.unit.config.ts",
     "test:integration": "vitest run --config vitest.integration.config.ts",
     "test:integration:watch": "vitest --config vitest.integration.config.ts",
+    "test:e2e": "vitest run --config vitest.e2e.config.ts",
     "test:all": "pnpm test && pnpm test:integration",
     "check-format": "prettier --check ./src",
     "check-exports": "attw --pack . --ignore-rules false-esm no-resolution cjs-resolves-to-esm",

package/skills/analyze-traces/SKILL.md

@@ -0,0 +1,178 @@
+---
+name: analyze-traces
+description: >
+  Analyze OpenTelemetry traces and structured logs from a running autotel service to debug errors,
+  investigate latency, follow requests across services, and surface cardinality / attribute hygiene
+  problems. Works with traces from any OTLP backend (Honeycomb, Grafana Tempo, Datadog, Jaeger,
+  Sentry, Axiom, HyperDX, …) plus the local `.autotel/spans/` dump and `InMemorySpanExporter` in tests.
+license: MIT
+---
+
+# Analyze traces
+
+This skill teaches an AI assistant how to read and reason about OpenTelemetry traces produced by autotel — whether they're sitting in a backend, exported to a local JSON dump, or captured in a test.
+
+## When to use
+
+- Debugging a failing endpoint after deploy
+- Investigating latency regressions (p50 / p95 / p99 spike)
+- Following a single request across browser → server → queue → worker
+- Auditing attribute hygiene (cardinality, PII leak risk, noise)
+- Spot-checking that a new instrumentation actually produces the spans you expected
+
+## Input formats
+
+| Source                         | How to access                                                      |
+| ------------------------------ | ------------------------------------------------------------------ |
+| Local debug dump               | `.autotel/spans/*.ndjson` — one span per line, OTLP JSON shape     |
+| `InMemorySpanExporter` (tests) | `exporter.getFinishedSpans()`                                      |
+| Backend (interactive)          | Jaeger / Tempo / Honeycomb UI; Datadog Trace Search; etc.          |
+| Backend (programmatic)         | Honeycomb Query API, Tempo `/api/search`, Datadog Logs / Trace API |
+
+## The shape of an autotel span
+
+```json
+{
+  "name": "POST /api/checkout",
+  "context": { "traceId": "…", "spanId": "…" },
+  "parentSpanId": "…",
+  "kind": "SERVER",
+  "startTimeUnixNano": "…",
+  "endTimeUnixNano": "…",
+  "status": { "code": "OK" },
+  "attributes": {
+    "service.name": "checkout",
+    "http.request.method": "POST",
+    "url.full": "https://api.example.com/api/checkout",
+    "http.response.status_code": 200,
+    "user.id": "usr_123",
+    "user.plan": "enterprise",
+    "cart.items": 3,
+    "cart.total": 14999,
+    "_correlationId": "01J…"
+  },
+  "events": [
+    {
+      "name": "log.emit.manual",
+      "attributes": { "level": "info", "stage": "validated" }
+    }
+  ],
+  "links": [],
+  "resource": {
+    "service.name": "checkout",
+    "deploy.id": "v2025.05.04-1"
+  }
+}
+```
+
+Key conventions to recognise:
+
+- `service.name` distinguishes services in a multi-service trace.
+- `_correlationId` (autotel-specific) is stable within a logical unit of work even across forked child spans (`_parentCorrelationId` ties them).
+- `gen_ai.*` attributes follow OpenTelemetry gen-ai semantic conventions for LLM calls.
+- `exception.*` attributes (auto-set by `createStructuredError`) carry `type`, `message`, `stacktrace`.
+
+## Common investigations
+
+### "Why is endpoint X failing?"
+
+1. Find the trace: filter `service.name = "<svc>" AND http.route = "<route>" AND status = error` for the last hour.
+2. Open the slowest / latest matching trace.
+3. Inspect the root span's `exception.message` and `exception.stacktrace`.
+4. Walk down the child spans — the deepest span with `status.code = ERROR` is usually the culprit.
+5. If using `createStructuredError`, look for `code`, `why`, `internal.*` attributes. They usually answer the "why" without you reading code.
+
+### "Why is endpoint X slow?"
+
+1. Find a slow trace: `service.name = "<svc>" AND http.route = "<route>" AND duration > p99(duration)`.
+2. View the waterfall — pinpoint the longest child span by self-time (not wall time).
+3. Common offenders:
+   - **Sequential awaits that should be parallel** — sibling spans run end-to-end instead of overlapping.
+   - **N+1 queries** — many short same-named spans (`SELECT * FROM …`) under one parent.
+   - **Cold starts** — `faas.coldstart=true` in Workers or Lambda.
+   - **Tool retries** — gen-ai spans with `gen_ai.response.finish_reason = error` followed by another call.
+
+### "Follow this user across services"
+
+Use `_correlationId` (or `user.id` if you have it):
+
+```
+service.name in (web, api, worker) AND _correlationId = "01J…"
+ORDER BY startTime
+```
+
+Each service contributes spans with the same `traceId` (W3C trace context propagation handles this automatically with autotel's global fetch instrumentation).
+
+### "Did the new instrumentation actually fire?"
+
+In a test, dump the in-memory exporter:
+
+```typescript
+import { InMemorySpanExporter } from 'autotel/exporters';
+const exporter = new InMemorySpanExporter();
+// … run the code under test
+const spans = exporter.getFinishedSpans();
+console.log(spans.map((s) => ({ name: s.name, attrs: s.attributes })));
+```
+
+Or live, point the SDK at a local file dump:
+
+```typescript
+init({ service: 'my-app', debug: 'pretty', spanDumpPath: '.autotel/spans' });
+```
+
+…then `tail -f .autotel/spans/*.ndjson | jq` while exercising the feature.
+
+## Cardinality / hygiene audits
+
+| Check                         | Query / heuristic                                                                                               |
+| ----------------------------- | --------------------------------------------------------------------------------------------------------------- |
+| **Span name cardinality**     | Top-K distinct `name` per service. Anything > a few hundred is a red flag — likely an unnormalised URL.         |
+| **Per-attribute cardinality** | `unique(attribute_value)` per `attribute_key`. UUIDs / emails / `Date.now()` ids in attributes blow up storage. |
+| **Missing `service.name`**    | Spans where the resource attribute is empty or `"app"` — fix at the SDK init.                                   |
+| **PII smell**                 | Look for raw `@`, leading digit-runs of length 16, or `eyJ` prefixes — your redactor is off.                    |
+| **Health-check noise**        | Spans with `http.route in (/healthz, /ready)`. Drop with `FilteringSpanProcessor`.                              |
+
+## Reading gen-ai traces
+
+LLM calls produce a parent span (kind `CLIENT`) with children for each tool call:
+
+| Attribute                                                  | Meaning                                  |
+| ---------------------------------------------------------- | ---------------------------------------- |
+| `gen_ai.system`                                            | Provider (`openai`, `anthropic`, …)      |
+| `gen_ai.request.model`                                     | Model id                                 |
+| `gen_ai.usage.input_tokens` / `output_tokens`              | Token count                              |
+| `gen_ai.usage.cache_read_tokens` / `cache_creation_tokens` | Cache hits                               |
+| `gen_ai.response.finish_reason`                            | `stop`, `tool_calls`, `length`, `error`  |
+| `gen_ai.tool.name`                                         | Tool invoked (on tool-call child spans)  |
+| `gen_ai.cost.usd`                                          | Estimated cost (if pricing map provided) |
+
+Common findings:
+
+- High `gen_ai.usage.input_tokens` with low `cache_read_tokens` → enable prompt caching.
+- Many sequential tool-call spans → consider parallel tool calls if the model supports it.
+- `gen_ai.response.finish_reason = length` → bump `max_tokens`.
+
+## When the trace is missing
+
+If you expected a span and there isn't one:
+
+1. **Sampling.** Did head sampling drop it? Check `sampling.rates` and `recordedSpans` in any subscriber.
+2. **Workers without `waitUntil`.** Did the request return before the exporter flushed? Move to `defineWorkerFetch` / `wrapModule`.
+3. **`instrumentation.disabled = true`** — check env-conditional config.
+4. **Exporter rejected.** Check service logs for `OTLP exporter` 4xx / 5xx — bad token, wrong dataset.
+
+## Output format
+
+When summarising an investigation, lead with the **decision-changing fact**, then the supporting evidence:
+
+```
+Failure cause: payment.declined (Stripe code: insufficient_funds)
+- Trace: 9d3a…b21
+- 38 / 412 checkout requests in the last hour failed with status=402.
+- All in eu-west-1, all on plan=free.
+- exception.cause.stripeChargeId starts with ch_3M…
+- Suggest: surface the structured `fix` field to the client; current 402 body returns generic message.
+```
+
+Keep raw span dumps out of the summary; link to the trace ID instead.

package/skills/autotel-core/SKILL.md

@@ -2,13 +2,6 @@
 name: autotel-core
 description: >
   When to use trace vs span vs request logger vs events in Autotel. Init once at startup, package exports (autotel, autotel/event, autotel/testing). Use for setup and choosing the right API.
-type: core
-library: autotel
-library_version: '2.23.0'
-sources:
-  - jagreehal/autotel:AGENTS.md
-  - jagreehal/autotel:docs/AGENT-GUIDE.md
-  - jagreehal/autotel:packages/autotel/CLAUDE.md
 ---
 
 # Autotel — Core

package/skills/autotel-events/SKILL.md

@@ -2,12 +2,6 @@
 name: autotel-events
 description: >
   track(), Event API, subscribers (e.g. PostHog). Configure subscribers in init(); use track() or Event for product/analytics events.
-type: core
-library: autotel
-library_version: '2.23.0'
-sources:
-  - jagreehal/autotel:packages/autotel/src/event.ts
-  - jagreehal/autotel:packages/autotel/src/event-subscriber.ts
 ---
 
 # Autotel — Events

package/skills/autotel-frameworks/SKILL.md

@@ -2,15 +2,6 @@
 name: autotel-frameworks
 description: >
   Hono, Fastify, TanStack Start, Cloudflare Workers. Middleware and init; getRequestLogger() in handlers. Load when adding Autotel to a web framework.
-type: framework
-library: autotel
-library_version: '2.23.0'
-requires:
-  - autotel-instrumentation
-sources:
-  - jagreehal/autotel:packages/autotel-hono/src/index.ts
-  - jagreehal/autotel:docs/AGENT-GUIDE.md
-  - jagreehal/autotel:AGENTS.md
 ---
 
 # Autotel — Framework Integration

package/skills/autotel-instrumentation/SKILL.md

@@ -2,13 +2,6 @@
 name: autotel-instrumentation
 description: >
   trace(), span(), instrument(), init(). Factory vs direct pattern, name inference. Sync init; use node-require for optional deps. Load when wrapping handlers or functions with spans.
-type: core
-library: autotel
-library_version: '2.23.0'
-sources:
-  - jagreehal/autotel:docs/ARCHITECTURE.md
-  - jagreehal/autotel:packages/autotel/src/functional.ts
-  - jagreehal/autotel:packages/autotel/CLAUDE.md
 ---
 
 # Autotel — Instrumentation