autotel 2.22.0 → 2.23.1

package/dist/webhook.js

@@ -1,16 +1,16 @@
-import { trace } from './chunk-GZFH6P5U.js';
+import { trace } from './chunk-GY4CRZSV.js';
 import './chunk-SR35DG5A.js';
 import './chunk-B3ZHLLMP.js';
 import './chunk-WD4RP6IV.js';
 import './chunk-USSL3D6L.js';
-import './chunk-BS757SL2.js';
+import './chunk-724XLWR3.js';
 import './chunk-YTGF4L2C.js';
 import './chunk-X4RMFFMR.js';
 import './chunk-WGWSHJ2N.js';
 import './chunk-GYR5K654.js';
 import './chunk-SNINLBEE.js';
 import './chunk-6UQRVUN3.js';
-import './chunk-2RQDNGV3.js';
+import './chunk-3QXBFGKP.js';
 import './chunk-33WTKH7X.js';
 import './chunk-XND7WBVX.js';
 import './chunk-B33XPEKY.js';

package/dist/workflow-distributed.cjs

@@ -1,19 +1,19 @@
 'use strict';
 
 var chunkINJD3G4K_cjs = require('./chunk-INJD3G4K.cjs');
-var chunkVQFF2WMP_cjs = require('./chunk-VQFF2WMP.cjs');
+var chunk3ZFDJJWZ_cjs = require('./chunk-3ZFDJJWZ.cjs');
 require('./chunk-W4EUTSB2.cjs');
 require('./chunk-GML3FBOT.cjs');
 require('./chunk-D5LMF53P.cjs');
 require('./chunk-XRKAL7WJ.cjs');
-require('./chunk-QKUGUDXJ.cjs');
+require('./chunk-HSEIUH7F.cjs');
 require('./chunk-6YIDHH2S.cjs');
 require('./chunk-GVLK7YUU.cjs');
 require('./chunk-ZNMBW67B.cjs');
 require('./chunk-IOYFAFHJ.cjs');
 require('./chunk-ELW34S4C.cjs');
 require('./chunk-CU6IDACR.cjs');
-require('./chunk-ONK2Y22L.cjs');
+require('./chunk-6S5RUKU3.cjs');
 require('./chunk-YS6C2YJE.cjs');
 require('./chunk-BGVKKL2N.cjs');
 require('./chunk-AZ24DJAG.cjs');
@@ -59,7 +59,7 @@ var WorkflowBaggage = chunkINJD3G4K_cjs.createSafeBaggageSchema(workflowBaggageF
 function traceDistributedWorkflow(config) {
   const spanName = `workflow.${config.name}`;
   return (fnFactory) => {
-    return chunkVQFF2WMP_cjs.trace(
+    return chunk3ZFDJJWZ_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 chunkVQFF2WMP_cjs.trace(
+    return chunk3ZFDJJWZ_cjs.trace(
       { name: spanName, spanKind: api.SpanKind.INTERNAL },
       (baseCtx) => {
         return async (...args) => {

package/dist/workflow-distributed.js

@@ -1,17 +1,17 @@
 import { createSafeBaggageSchema } from './chunk-4IFSYQVX.js';
-import { trace } from './chunk-GZFH6P5U.js';
+import { trace } from './chunk-GY4CRZSV.js';
 import './chunk-SR35DG5A.js';
 import './chunk-B3ZHLLMP.js';
 import './chunk-WD4RP6IV.js';
 import './chunk-USSL3D6L.js';
-import './chunk-BS757SL2.js';
+import './chunk-724XLWR3.js';
 import './chunk-YTGF4L2C.js';
 import './chunk-X4RMFFMR.js';
 import './chunk-WGWSHJ2N.js';
 import './chunk-GYR5K654.js';
 import './chunk-SNINLBEE.js';
 import './chunk-6UQRVUN3.js';
-import './chunk-2RQDNGV3.js';
+import './chunk-3QXBFGKP.js';
 import './chunk-33WTKH7X.js';
 import './chunk-XND7WBVX.js';
 import './chunk-B33XPEKY.js';

package/dist/workflow.cjs

@@ -1,19 +1,19 @@
 'use strict';
 
-var chunk7NH625MS_cjs = require('./chunk-7NH625MS.cjs');
-require('./chunk-VQFF2WMP.cjs');
+var chunkBSZP4URK_cjs = require('./chunk-BSZP4URK.cjs');
+require('./chunk-3ZFDJJWZ.cjs');
 require('./chunk-W4EUTSB2.cjs');
 require('./chunk-GML3FBOT.cjs');
 require('./chunk-D5LMF53P.cjs');
 require('./chunk-XRKAL7WJ.cjs');
-require('./chunk-QKUGUDXJ.cjs');
+require('./chunk-HSEIUH7F.cjs');
 require('./chunk-6YIDHH2S.cjs');
 require('./chunk-GVLK7YUU.cjs');
 require('./chunk-ZNMBW67B.cjs');
 require('./chunk-IOYFAFHJ.cjs');
 require('./chunk-ELW34S4C.cjs');
 require('./chunk-CU6IDACR.cjs');
-require('./chunk-ONK2Y22L.cjs');
+require('./chunk-6S5RUKU3.cjs');
 require('./chunk-YS6C2YJE.cjs');
 require('./chunk-BGVKKL2N.cjs');
 require('./chunk-AZ24DJAG.cjs');
@@ -25,19 +25,19 @@ require('./chunk-JEQ2X3Z6.cjs');
 
 Object.defineProperty(exports, "getCurrentWorkflowContext", {
   enumerable: true,
-  get: function () { return chunk7NH625MS_cjs.getCurrentWorkflowContext; }
+  get: function () { return chunkBSZP4URK_cjs.getCurrentWorkflowContext; }
 });
 Object.defineProperty(exports, "isInWorkflow", {
   enumerable: true,
-  get: function () { return chunk7NH625MS_cjs.isInWorkflow; }
+  get: function () { return chunkBSZP4URK_cjs.isInWorkflow; }
 });
 Object.defineProperty(exports, "traceStep", {
   enumerable: true,
-  get: function () { return chunk7NH625MS_cjs.traceStep; }
+  get: function () { return chunkBSZP4URK_cjs.traceStep; }
 });
 Object.defineProperty(exports, "traceWorkflow", {
   enumerable: true,
-  get: function () { return chunk7NH625MS_cjs.traceWorkflow; }
+  get: function () { return chunkBSZP4URK_cjs.traceWorkflow; }
 });
 //# sourceMappingURL=workflow.cjs.map
 //# sourceMappingURL=workflow.cjs.map

package/dist/workflow.js

@@ -1,17 +1,17 @@
-export { getCurrentWorkflowContext, isInWorkflow, traceStep, traceWorkflow } from './chunk-QHT4MUED.js';
-import './chunk-GZFH6P5U.js';
+export { getCurrentWorkflowContext, isInWorkflow, traceStep, traceWorkflow } from './chunk-WCIIFRGL.js';
+import './chunk-GY4CRZSV.js';
 import './chunk-SR35DG5A.js';
 import './chunk-B3ZHLLMP.js';
 import './chunk-WD4RP6IV.js';
 import './chunk-USSL3D6L.js';
-import './chunk-BS757SL2.js';
+import './chunk-724XLWR3.js';
 import './chunk-YTGF4L2C.js';
 import './chunk-X4RMFFMR.js';
 import './chunk-WGWSHJ2N.js';
 import './chunk-GYR5K654.js';
 import './chunk-SNINLBEE.js';
 import './chunk-6UQRVUN3.js';
-import './chunk-2RQDNGV3.js';
+import './chunk-3QXBFGKP.js';
 import './chunk-33WTKH7X.js';
 import './chunk-XND7WBVX.js';
 import './chunk-B33XPEKY.js';

package/dist/yaml-config.d.cts

@@ -1,4 +1,4 @@
-import { A as AutotelConfig } from './init-BMiXSJNM.cjs';
+import { A as AutotelConfig } from './init-BC5aN8bh.cjs';
 import '@opentelemetry/sdk-trace-base';
 import '@opentelemetry/sdk-node';
 import '@opentelemetry/resources';
@@ -12,6 +12,7 @@ import '@opentelemetry/sdk-logs';
 import './filtering-span-processor.cjs';
 import './span-name-normalizer.cjs';
 import './attribute-redacting-processor.cjs';
+import './processors.cjs';
 
 /**
  * YAML configuration loader for autotel

package/dist/yaml-config.d.ts

@@ -1,4 +1,4 @@
-import { A as AutotelConfig } from './init-ByRbNTRo.js';
+import { A as AutotelConfig } from './init-_FG4IbhF.js';
 import '@opentelemetry/sdk-trace-base';
 import '@opentelemetry/sdk-node';
 import '@opentelemetry/resources';
@@ -12,6 +12,7 @@ import '@opentelemetry/sdk-logs';
 import './filtering-span-processor.js';
 import './span-name-normalizer.js';
 import './attribute-redacting-processor.js';
+import './processors.js';
 
 /**
  * YAML configuration loader for autotel

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "autotel",
-  "version": "2.22.0",
+  "version": "2.23.1",
   "description": "Write Once, Observe Anywhere",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -202,12 +202,30 @@
       "types": "./dist/test-span-collector.d.ts",
       "import": "./dist/test-span-collector.js",
       "require": "./dist/test-span-collector.cjs"
+    },
+    "./parse-error": {
+      "types": "./dist/parse-error.d.ts",
+      "import": "./dist/parse-error.js",
+      "require": "./dist/parse-error.cjs"
+    },
+    "./drain-pipeline": {
+      "types": "./dist/drain-pipeline.d.ts",
+      "import": "./dist/drain-pipeline.js",
+      "require": "./dist/drain-pipeline.cjs"
+    },
+    "./enrichers": {
+      "types": "./dist/enrichers.d.ts",
+      "import": "./dist/enrichers.js",
+      "require": "./dist/enrichers.cjs"
     }
   },
   "files": [
     "dist",
     "src",
-    "README.md"
+    "README.md",
+    "skills",
+    "!skills/_artifacts",
+    "bin"
   ],
   "keywords": [
     "opentelemetry",
@@ -230,29 +248,30 @@
   "license": "MIT",
   "dependencies": {
     "@opentelemetry/api": "^1.9.0",
-    "@opentelemetry/api-logs": "^0.212.0",
-    "@opentelemetry/exporter-metrics-otlp-http": "^0.212.0",
-    "@opentelemetry/exporter-trace-otlp-http": "^0.212.0",
-    "@opentelemetry/instrumentation": "^0.212.0",
-    "@opentelemetry/resources": "^2.5.1",
-    "@opentelemetry/sdk-metrics": "^2.5.1",
-    "@opentelemetry/sdk-node": "^0.212.0",
-    "@opentelemetry/sdk-trace-base": "^2.5.1",
+    "@tanstack/intent": "^0.0.13",
+    "@opentelemetry/api-logs": "^0.213.0",
+    "@opentelemetry/exporter-metrics-otlp-http": "^0.213.0",
+    "@opentelemetry/exporter-trace-otlp-http": "^0.213.0",
+    "@opentelemetry/instrumentation": "^0.213.0",
+    "@opentelemetry/resources": "^2.6.0",
+    "@opentelemetry/sdk-metrics": "^2.6.0",
+    "@opentelemetry/sdk-node": "^0.213.0",
+    "@opentelemetry/sdk-trace-base": "^2.6.0",
     "@opentelemetry/semantic-conventions": "^1.40.0",
     "import-in-the-middle": "^3.0.0"
   },
   "peerDependencies": {
-    "@opentelemetry/auto-instrumentations-node": "^0.70.1",
-    "@opentelemetry/exporter-logs-otlp-grpc": "^0.212.0",
-    "@opentelemetry/exporter-logs-otlp-http": "^0.212.0",
-    "@opentelemetry/exporter-metrics-otlp-grpc": "^0.212.0",
-    "@opentelemetry/exporter-trace-otlp-grpc": "^0.212.0",
-    "@opentelemetry/resource-detector-aws": "^2.12.0",
-    "@opentelemetry/resource-detector-container": "^0.8.3",
-    "@opentelemetry/resource-detector-gcp": "^0.47.0",
-    "@opentelemetry/sdk-logs": "^0.212.0",
-    "@opentelemetry/sdk-trace-node": "^2.5.1",
-    "@traceloop/node-server-sdk": "^0.22.7",
+    "@opentelemetry/auto-instrumentations-node": "^0.71.0",
+    "@opentelemetry/exporter-logs-otlp-grpc": "^0.213.0",
+    "@opentelemetry/exporter-logs-otlp-http": "^0.213.0",
+    "@opentelemetry/exporter-metrics-otlp-grpc": "^0.213.0",
+    "@opentelemetry/exporter-trace-otlp-grpc": "^0.213.0",
+    "@opentelemetry/resource-detector-aws": "^2.13.0",
+    "@opentelemetry/resource-detector-container": "^0.8.4",
+    "@opentelemetry/resource-detector-gcp": "^0.48.0",
+    "@opentelemetry/sdk-logs": "^0.213.0",
+    "@opentelemetry/sdk-trace-node": "^2.6.0",
+    "@traceloop/node-server-sdk": "^0.22.8",
     "pino": "^10.3.1",
     "pino-pretty": "^13.1.3",
     "yaml": "^2.8.2"
@@ -304,21 +323,21 @@
   "devDependencies": {
     "@arethetypeswrong/cli": "^0.18.2",
     "@edge-runtime/vm": "^5.0.0",
-    "@opentelemetry/auto-instrumentations-node": "^0.70.1",
-    "@opentelemetry/context-async-hooks": "^2.5.1",
-    "@opentelemetry/exporter-logs-otlp-grpc": "^0.212.0",
-    "@opentelemetry/exporter-logs-otlp-http": "^0.212.0",
-    "@opentelemetry/exporter-metrics-otlp-grpc": "^0.212.0",
-    "@opentelemetry/exporter-trace-otlp-grpc": "^0.212.0",
-    "@opentelemetry/resource-detector-aws": "^2.12.0",
-    "@opentelemetry/resource-detector-container": "^0.8.3",
-    "@opentelemetry/resource-detector-gcp": "^0.47.0",
-    "@opentelemetry/sdk-logs": "^0.212.0",
-    "@opentelemetry/sdk-trace-node": "^2.5.1",
+    "@opentelemetry/auto-instrumentations-node": "^0.71.0",
+    "@opentelemetry/context-async-hooks": "^2.6.0",
+    "@opentelemetry/exporter-logs-otlp-grpc": "^0.213.0",
+    "@opentelemetry/exporter-logs-otlp-http": "^0.213.0",
+    "@opentelemetry/exporter-metrics-otlp-grpc": "^0.213.0",
+    "@opentelemetry/exporter-trace-otlp-grpc": "^0.213.0",
+    "@opentelemetry/resource-detector-aws": "^2.13.0",
+    "@opentelemetry/resource-detector-container": "^0.8.4",
+    "@opentelemetry/resource-detector-gcp": "^0.48.0",
+    "@opentelemetry/sdk-logs": "^0.213.0",
+    "@opentelemetry/sdk-trace-node": "^2.6.0",
     "@total-typescript/ts-reset": "^0.6.1",
     "@total-typescript/tsconfig": "^1.0.4",
     "@types/eslint-config-prettier": "^6.11.3",
-    "@types/node": "^25.3.3",
+    "@types/node": "^25.3.5",
     "@typescript-eslint/eslint-plugin": "^8.56.1",
     "@typescript-eslint/parser": "^8.56.1",
     "eslint-config-prettier": "^10.1.8",
@@ -344,6 +363,9 @@
     "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",

package/skills/autotel-core/SKILL.md

@@ -0,0 +1,162 @@
+---
+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
+
+OpenTelemetry instrumentation for Node.js and edge. Instrument once; stream to any OTLP backend. Use `trace()`/`span()` for spans, `getRequestLogger()` for one snapshot per request, `createStructuredError`/`parseError` for errors, `track()` for product events.
+
+## When to Use What
+
+| Need                                  | API                                                              | Import                                 |
+| ------------------------------------- | ---------------------------------------------------------------- | -------------------------------------- |
+| Wrap a function with a span           | `trace(fn)`, `span('Name', fn)`                                  | `autotel`                              |
+| Request-scoped attributes + emit once | `getRequestLogger(ctx?)` → `.set()`, `.emitNow()`                | `autotel`                              |
+| Throw with why/fix/link               | `createStructuredError({ message, why?, fix?, link?, status? })` | `autotel`                              |
+| Parse API errors (client)             | `parseError(err)` → `message`, `why`, `fix`, `link`              | `autotel`                              |
+| Product/analytics events              | `track(name, attrs)` or `Event` from `autotel/event`             | `autotel`, `autotel/event`             |
+| Init (once at startup)                | `init({ service, ... })`                                         | `autotel` or `autotel/instrumentation` |
+| Testing                               | `createTraceCollector()`, `InMemorySpanExporter`                 | `autotel/testing`, `autotel/exporters` |
+
+Request logger requires an active span. Wrap HTTP handlers with `trace()` or framework middleware that creates a span, then call `getRequestLogger()` inside.
+
+## Setup
+
+```typescript
+import { init, trace, getRequestLogger } from 'autotel';
+
+init({ service: 'my-app' });
+
+const handler = trace((ctx) => async (req: Request) => {
+  const log = getRequestLogger(ctx);
+  log.set({ path: req.url });
+  const result = await doWork(req);
+  log.emitNow();
+  return result;
+});
+```
+
+## Core Patterns
+
+**Factory pattern when you need context (attributes, request logger):**
+
+```typescript
+const createUser = trace((ctx) => async (data: UserInput) => {
+  ctx.setAttribute('user.id', data.id);
+  const log = getRequestLogger(ctx);
+  log.set({ user: { id: data.id } });
+  return db.users.create(data);
+});
+```
+
+**Direct pattern when you don't need context:**
+
+```typescript
+const getUser = trace(async (id: string) => {
+  return db.users.findById(id);
+});
+```
+
+**Structured errors in API routes:**
+
+```typescript
+import { createStructuredError } from 'autotel';
+throw createStructuredError({
+  message: 'Not found',
+  status: 404,
+  why: `No user "${id}"`,
+  fix: 'Check the ID and try again',
+});
+```
+
+**Client: parseError for UI:**
+
+```typescript
+import { parseError } from 'autotel';
+const e = parseError(err);
+toast.error(e.message, { description: e.why });
+```
+
+## Common Mistakes
+
+### HIGH Call getRequestLogger() without active span
+
+Wrong:
+
+```typescript
+app.get('/api/x', () => {
+  const log = getRequestLogger();
+  log.set({ route: 'x' });
+});
+```
+
+Correct:
+
+```typescript
+app.use(autotelMiddleware()); // or wrap route with trace()
+app.get('/api/x', () => {
+  const log = getRequestLogger();
+  log.set({ route: 'x' });
+});
+```
+
+getRequestLogger() requires an active span. Register middleware that creates a span per request, or wrap the handler with `trace()`.
+
+Source: packages/autotel/src/request-logger.ts
+
+### HIGH Use await import() for init-time optional deps
+
+Wrong:
+
+```typescript
+const pkg = await import('optional-dep');
+```
+
+Correct:
+
+```typescript
+import { safeRequire } from 'autotel';
+const pkg = safeRequire('optional-dep');
+```
+
+init() must stay synchronous. Use node-require helpers for optional dependencies.
+
+Source: packages/autotel/CLAUDE.md
+
+### MEDIUM Use trace() without ctx when you need attributes or request logger
+
+Wrong:
+
+```typescript
+const handler = trace(async (req) => {
+  const log = getRequestLogger(); // may throw if span not set up for request logger
+});
+```
+
+Correct:
+
+```typescript
+const handler = trace((ctx) => async (req) => {
+  const log = getRequestLogger(ctx);
+  log.set({ route: req.url });
+});
+```
+
+Use the factory pattern `(ctx) => async (...)` when you need to set attributes or use the request logger.
+
+Source: docs/AGENT-GUIDE.md
+
+## Version
+
+Targets autotel v2.23.x.
+
+See also: autotel-instrumentation/SKILL.md — init and trace/span in depth. autotel-request-logging/SKILL.md — request logger usage.

package/skills/autotel-events/SKILL.md

@@ -0,0 +1,88 @@
+---
+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
+
+Send product and analytics events with `track(name, attributes)` or the `Event` class from `autotel/event`. Configure subscribers (e.g. PostHog) in `init()`; they receive events automatically.
+
+## Setup
+
+```typescript
+import { init, track } from 'autotel';
+import { PostHogSubscriber } from 'autotel-subscribers/posthog';
+
+init({
+  service: 'my-app',
+  subscribers: [new PostHogSubscriber({ apiKey: 'phc_...' })],
+});
+
+track('checkout.started', { userId: 'u_123', cartId: 'c_456' });
+```
+
+With Event instance (optional override of subscribers):
+
+```typescript
+import { Event } from 'autotel/event';
+
+const event = new Event('checkout');
+event.trackEvent('application.submitted', { jobId: '123', userId: '456' });
+```
+
+## Core Patterns
+
+**Simple track (uses subscribers from init):**
+
+```typescript
+track('signup.completed', { plan: 'pro', source: 'web' });
+```
+
+**Event with custom subscribers:**
+
+```typescript
+import { Event } from 'autotel/event';
+import { PostHogSubscriber } from 'autotel-subscribers/posthog';
+
+const event = new Event('onboarding', {
+  subscribers: [new PostHogSubscriber({ apiKey: 'phc_other_project' })],
+});
+event.trackEvent('step.completed', { step: 2 });
+```
+
+**Validation and config:** See `getEventsConfig()`, `getValidationConfig()` from init; event names and attributes can be validated.
+
+## Common Mistakes
+
+### MEDIUM Call track() before init() with subscribers
+
+Wrong:
+
+```typescript
+track('signup', { plan: 'pro' });
+```
+
+Correct:
+
+```typescript
+init({
+  service: 'my-app',
+  subscribers: [new PostHogSubscriber({ apiKey: 'phc_...' })],
+});
+track('signup', { plan: 'pro' });
+```
+
+Subscribers are configured in init(). track() sends to those subscribers; without init or without subscribers, events may not reach the backend.
+
+Source: packages/autotel/src/event.ts
+
+## Version
+
+Targets autotel v2.23.x.

package/skills/autotel-frameworks/SKILL.md

@@ -0,0 +1,97 @@
+---
+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
+
+This skill builds on autotel-instrumentation. Read it first for init() and span creation.
+
+Use framework-specific middleware or wrappers to create a span per request; then call `getRequestLogger()` inside handlers. Each framework package (autotel-hono, autotel-tanstack, autotel-cloudflare) provides the glue.
+
+## Setup
+
+### Hono
+
+```typescript
+import { Hono } from 'hono';
+import { init, getRequestLogger } from 'autotel';
+import { otel } from 'autotel-hono';
+
+init({ service: 'my-api' });
+
+const app = new Hono();
+app.use('*', otel({ serviceName: 'my-api' }));
+
+app.post('/api/checkout', async (c) => {
+  const log = getRequestLogger();
+  log.set({ route: 'checkout' });
+  const body = await c.req.json();
+  log.set({ cart: { items: body.items?.length } });
+  log.emitNow();
+  return c.json({ ok: true });
+});
+```
+
+### Fastify
+
+Use middleware or a wrapper that creates a span per request (see apps/example-fastify). Inside the route, wrap with `trace()` or ensure a span is active, then `getRequestLogger(ctx)` or `getRequestLogger()`.
+
+### TanStack Start
+
+See packages/autotel-tanstack and apps/example-tanstack-start: middleware and env config. Use `getRequestLogger()` inside server handlers when a span is active.
+
+### Cloudflare Workers
+
+See packages/autotel-cloudflare: init at top level, wrap the fetch handler so each request gets a span. Use `getRequestLogger()` or trace context inside the handler.
+
+## Core Patterns
+
+**Register middleware before routes:** Middleware creates the span; getRequestLogger() needs that active span.
+
+**Framework-specific packages:** autotel-hono, autotel-tanstack, autotel-cloudflare. Install the package for your framework and follow its README or CLAUDE.md.
+
+## Common Mistakes
+
+### HIGH Use getRequestLogger() in Hono without registering middleware first
+
+Wrong:
+
+```typescript
+const app = new Hono();
+app.get('/api/x', (c) => {
+  const log = getRequestLogger();
+  return c.json({});
+});
+```
+
+Correct:
+
+```typescript
+const app = new Hono();
+app.use('*', otel());
+app.get('/api/x', (c) => {
+  const log = getRequestLogger();
+  return c.json({});
+});
+```
+
+Middleware creates the span per request. Without it, getRequestLogger() has no active span and will throw.
+
+Source: packages/autotel-hono, docs/AGENT-GUIDE.md
+
+## Version
+
+Targets autotel v2.23.x.
+
+See also: autotel-instrumentation/SKILL.md — init and spans. autotel-request-logging/SKILL.md — request logger usage.