autotel 4.3.0 → 5.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "autotel",
-  "version": "4.3.0",
+  "version": "5.0.0",
   "description": "Write Once, Observe Anywhere",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -35,6 +35,11 @@
       "import": "./dist/sampling.js",
       "require": "./dist/sampling.cjs"
     },
+    "./analysis": {
+      "types": "./dist/analysis.d.ts",
+      "import": "./dist/analysis.js",
+      "require": "./dist/analysis.cjs"
+    },
     "./event": {
       "types": "./dist/event.d.ts",
       "import": "./dist/event.js",
@@ -60,6 +65,11 @@
       "import": "./dist/metric.js",
       "require": "./dist/metric.cjs"
     },
+    "./slo": {
+      "types": "./dist/slo.d.ts",
+      "import": "./dist/slo.js",
+      "require": "./dist/slo.cjs"
+    },
     "./metric-testing": {
       "types": "./dist/metric-testing.d.ts",
       "import": "./dist/metric-testing.js",
@@ -280,8 +290,8 @@
     "@opentelemetry/sdk-metrics": "^2.9.0",
     "@opentelemetry/sdk-node": "^0.220.0",
     "@opentelemetry/sdk-trace-base": "^2.9.0",
-    "@opentelemetry/semantic-conventions": "^1.42.0",
-    "import-in-the-middle": "^3.3.1"
+    "@opentelemetry/semantic-conventions": "^1.43.0",
+    "import-in-the-middle": "^3.3.2"
   },
   "peerDependencies": {
     "@opentelemetry/auto-instrumentations-node": "^0.78.0",
@@ -336,7 +346,7 @@
     }
   },
   "devDependencies": {
-    "@arethetypeswrong/cli": "^0.18.4",
+    "@arethetypeswrong/cli": "^0.18.5",
     "@edge-runtime/vm": "^5.0.0",
     "@opentelemetry/auto-instrumentations-node": "^0.78.0",
     "@opentelemetry/context-async-hooks": "^2.9.0",
@@ -347,26 +357,26 @@
     "@opentelemetry/resource-detector-container": "^0.8.11",
     "@opentelemetry/resource-detector-gcp": "^0.55.0",
     "@opentelemetry/sdk-trace-node": "^2.9.0",
-    "@swc/core": "^1.15.43",
+    "@swc/core": "^1.15.46",
     "@total-typescript/ts-reset": "^0.6.1",
     "@total-typescript/tsconfig": "^1.0.4",
     "@types/eslint-config-prettier": "^6.11.3",
-    "@types/node": "^26.1.0",
-    "@typescript-eslint/eslint-plugin": "^8.63.0",
-    "@typescript-eslint/parser": "^8.63.0",
+    "@types/node": "^26.1.1",
+    "@typescript-eslint/eslint-plugin": "^8.65.0",
+    "@typescript-eslint/parser": "^8.65.0",
     "eslint-config-prettier": "^10.1.8",
     "eslint-plugin-unicorn": "^64.0.0",
     "pino": "^10.3.1",
-    "prettier": "^3.9.4",
+    "prettier": "^3.9.6",
     "rimraf": "^6.1.3",
-    "tsdown": "^0.22.3",
-    "tsx": "^4.23.0",
+    "tsdown": "^0.22.12",
+    "tsx": "^4.23.1",
     "typescript": "^6.0.3",
-    "typescript-eslint": "^8.63.0",
+    "typescript-eslint": "^8.65.0",
     "unplugin-swc": "^1.5.9",
     "vite-tsconfig-paths": "^6.1.1",
     "vitest": "^4.1.10",
-    "vitest-mock-extended": "^4.0.0",
+    "vitest-mock-extended": "^5.1.0",
     "winston": "^3.19.0",
     "yaml": "^2.9.0"
   },
@@ -384,7 +394,6 @@
     "dev": "tsdown --watch",
     "lint": "eslint src/**/*.ts",
     "lint:fix": "eslint src/**/*.ts --fix",
-    "format": "prettier --write .",
     "format:check": "prettier --check src/**/*.ts",
     "type-check": "tsc --noEmit",
     "test": "vitest run --config vitest.unit.config.ts",

package/skills/analyze-traces/SKILL.md

@@ -10,7 +10,7 @@ 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.
+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
 
@@ -24,7 +24,7 @@ This skill teaches an AI assistant how to read and reason about OpenTelemetry tr
 
 | Source                         | How to access                                                      |
 | ------------------------------ | ------------------------------------------------------------------ |
-| Local debug dump               | `.autotel/spans/*.ndjson` — one span per line, OTLP JSON shape     |
+| 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 |
@@ -79,18 +79,47 @@ Key conventions to recognise:
 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.
+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).
+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_reasons` containing `error` followed by another call.
+   - **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_reasons` containing `error` followed by another call.
+
+### "Which requests are affected?"
+
+A waterfall explains one slow request. It cannot tell you what the slow ones
+share. Run the core analysis loop instead: split the population on the symptom,
+then score every recorded field by how much the two groups disagree.
+
+```typescript
+import { compareCohorts } from 'autotel/analysis';
+
+const isSlow = (event) => Number(event['checkout.duration_ms']) >= 800;
+
+const ranked = compareCohorts({
+  outlier: events.filter(isSlow),
+  baseline: events.filter((event) => !isSlow(event)),
+});
+// [{ field: 'payment.provider', value: 'bank-beta', difference: 0.67, … }]
+```
+
+Feed it any array of flat records: `span.attributes` from a collector, wide
+events from `getRequestLogger()`, or rows returned by a backend query.
+
+The loop skips fields whose values never repeat. A request id takes a fresh
+value on every event, so it would bury the answer under noise. Bucket durations
+and payload sizes when you instrument them if you want the loop to rank them.
+
+The top row is a hypothesis. A field can move with the problem without causing
+it. You are done when you have named the cohort and confirmed the mechanism in
+two traces drawn from it.
 
 ### "Follow this user across services"
 
@@ -127,10 +156,10 @@ init({ service: 'my-app', debug: 'pretty', spanDumpPath: '.autotel/spans' });
 
 | Check                         | Query / heuristic                                                                                               |
 | ----------------------------- | --------------------------------------------------------------------------------------------------------------- |
-| **Span name cardinality**     | Top-K distinct `name` per service. Anything > a few hundred is a red flag — likely an unnormalised URL.         |
+| **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.                    |
+| **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
@@ -161,8 +190,8 @@ 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.
+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
 

package/skills/autotel-core/SKILL.md

@@ -4,7 +4,7 @@ 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.
 ---
 
-# Autotel — Core
+# 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.
 
@@ -29,17 +29,19 @@ Backend config rule of thumb: use `endpoint` for one OTLP destination, `destinat
 ## Setup
 
 ```typescript
-import { init, trace, getRequestLogger } from 'autotel';
+import { init, withTracing, 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;
-});
+const handler = withTracing({ name: 'http.request' })(
+  (ctx) => async (req: Request) => {
+    const log = getRequestLogger(ctx);
+    log.set({ path: req.url });
+    const result = await doWork(req);
+    log.emitNow();
+    return result;
+  },
+);
 ```
 
 ## Core Patterns
@@ -47,12 +49,14 @@ const handler = trace((ctx) => async (req: Request) => {
 **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);
-});
+const createUser = withTracing({ name: 'user.create' })(
+  (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:**
@@ -142,7 +146,7 @@ const handler = trace(async (req) => {
 Correct:
 
 ```typescript
-const handler = trace((ctx) => async (req) => {
+const handler = withTracing({ name: 'http.request' })((ctx) => async (req) => {
   const log = getRequestLogger(ctx);
   log.set({ route: req.url });
 });
@@ -156,4 +160,7 @@ Source: docs/AGENT-GUIDE.md
 
 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.
+See also:
+
+- `autotel-instrumentation/SKILL.md` for init and trace/span in depth
+- `autotel-request-logging/SKILL.md` for request logger usage

package/skills/autotel-events/SKILL.md

@@ -4,7 +4,7 @@ description: >
   track(), Event API, subscribers (e.g. PostHog). Configure subscribers in init(); use track() or Event for product/analytics events.
 ---
 
-# Autotel — Events
+# 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.
 

package/skills/autotel-frameworks/SKILL.md

@@ -1,17 +1,19 @@
 ---
 name: autotel-frameworks
 description: >
-  Hono, Fastify, TanStack Start, Cloudflare Workers. Middleware and init; getRequestLogger() in handlers. Load when adding Autotel to a web framework.
+  Hono, Fastify, TanStack Start, Cloudflare Workers, NestJS, SvelteKit, Elysia, Nuxt. Middleware and init; getRequestLogger() in handlers. Load when adding Autotel to a web framework.
 ---
 
-# Autotel — Framework Integration
+# 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.
+Use framework-specific middleware or wrappers to create a span per request; then call `getRequestLogger()` inside handlers. Most frameworks use `autotel-adapters` subpaths (or a thin wrapper package like `autotel-hono`, `autotel-tanstack`, `autotel-cloudflare`, `autotel-nuxt`).
 
 When adding new request/exception events in framework handlers, prefer correlated logs (`getRequestLogger().info/warn/error`) instead of introducing new `span.addEvent()` usage.
 
+For custom HTTP frameworks, start from `autotel-adapters/toolkit` (`defineFrameworkIntegration`, `createMiddlewareLogger`, `finishResponse` for streaming, `waitUntil` on edge runtimes).
+
 ## Setup
 
 ### Hono
@@ -46,13 +48,43 @@ See packages/autotel-tanstack and apps/example-tanstack-start: middleware and en
 
 ### 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.
+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. Pass `ctx.waitUntil` through adapter options so emit/drain completes after the response.
+
+### NestJS
+
+Use `AutotelInterceptor` from `autotel-adapters/nestjs` and `useLogger()` in controllers/services (see apps/example-nestjs):
+
+```typescript
+import { APP_INTERCEPTOR } from '@nestjs/core';
+import { AutotelInterceptor } from 'autotel-adapters/nestjs';
+
+@Module({
+  providers: [{ provide: APP_INTERCEPTOR, useClass: AutotelInterceptor }],
+})
+export class AppModule {}
+```
+
+### SvelteKit
+
+Add `autotelHandle()` in `hooks.server.ts` from `autotel-adapters/sveltekit`; call `useLogger()` in `+server.ts` / server loads. Use `finishResponse` semantics for streaming routes (see toolkit `stream-response`).
+
+### Elysia
+
+Wrap handlers with `withAutotelHandler()` from `autotel-adapters/elysia` (or the `autotel` alias); use `useLogger()` inside handlers (see apps/example-elysia).
+
+### Nuxt
+
+Add the `autotel-nuxt` module for zero-config Nitro wiring; server code can use `useLogger()` via `autotel-adapters/nitro` re-exports from `autotel-nuxt/runtime/nitro`.
 
 ## 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.
+**Framework-specific packages:** autotel-hono, autotel-tanstack, autotel-cloudflare, autotel-nuxt. Adapter subpaths: autotel-adapters/{express,fastify,next,nitro,nestjs,sveltekit,elysia,...}. Install the package for your framework and follow its README or CLAUDE.md.
+
+**Streaming responses:** defer `emitNow` until the body finishes via adapter `finishResponse` / toolkit `bindStreamingResponseLifecycle`.
+
+**Edge drain:** pass `waitUntil` (Cloudflare `ExecutionContext`, etc.) so async emit/drain does not block the response.
 
 ## Common Mistakes
 
@@ -87,4 +119,7 @@ Source: packages/autotel-hono, docs/AGENT-GUIDE.md
 
 Targets autotel v2.23.x.
 
-See also: autotel-instrumentation/SKILL.md — init and spans. autotel-request-logging/SKILL.md — request logger usage.
+See also:
+
+- `autotel-instrumentation/SKILL.md` for init and spans
+- `autotel-request-logging/SKILL.md` for request logger usage

package/skills/autotel-instrumentation/SKILL.md

@@ -4,7 +4,7 @@ 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.
 ---
 
-# Autotel — Instrumentation
+# Autotel: Instrumentation
 
 Wrap functions and handlers with `trace()`, `span()`, or `instrument()`. Call `init()` once at app startup. Keep init synchronous; use `safeRequire`/`requireModule` for optional dependencies.
 
@@ -13,7 +13,7 @@ For new event emission, prefer correlated logs (OTel Logs API path) over adding
 ## Setup
 
 ```typescript
-import { init, trace } from 'autotel';
+import { init, trace, withTracing } from 'autotel';
 
 init({ service: 'my-app' });
 
@@ -25,12 +25,14 @@ const handler = trace(async (req: Request) => {
 With span context (attributes, request logger):
 
 ```typescript
-const handler = trace((ctx) => async (req: Request) => {
-  ctx.setAttribute('http.route', '/api/checkout');
-  const log = getRequestLogger(ctx);
-  log.set({ path: req.url });
-  return processRequest(req);
-});
+const handler = withTracing({ name: 'http.request' })(
+  (ctx) => async (req: Request) => {
+    ctx.setAttribute('http.route', '/api/checkout');
+    const log = getRequestLogger(ctx);
+    log.set({ path: req.url });
+    return processRequest(req);
+  },
+);
 ```
 
 ## Core Patterns
@@ -142,4 +144,7 @@ Source: packages/autotel/package.json exports
 
 Targets autotel v2.23.x.
 
-See also: autotel-core/SKILL.md — when to use what. autotel-request-logging/SKILL.md — getRequestLogger requires active span.
+See also:
+
+- `autotel-core/SKILL.md` for when to use what
+- `autotel-request-logging/SKILL.md`, since `getRequestLogger` requires an active span

package/skills/autotel-request-logging/SKILL.md

@@ -4,33 +4,35 @@ description: >
   getRequestLogger(), set(), info/warn/error, emitNow(). One snapshot per request; requires active span. Use when adding request-scoped context or replacing scattered console.log.
 ---
 
-# Autotel — Request Logging
+# Autotel: Request Logging
 
 This skill builds on autotel-instrumentation. Read it first for init and span creation.
 
-Accumulate context with `getRequestLogger(ctx)`, `.set()`, and `.info()`/`.warn()`/`.error()`. Call `.emitNow()` (or rely on middleware) to emit one snapshot per request. Request logger requires an active span — use inside `trace()` or framework middleware.
+Accumulate context with `getRequestLogger(ctx)`, `.set()`, and `.info()`/`.warn()`/`.error()`. Call `.emitNow()` (or rely on middleware) to emit one snapshot per request. Request logger requires an active span. Use inside `trace()` or framework middleware.
 
 Preferred event model: treat request logger emissions as the default way to capture request-correlated events in new code. If a backend still expects span-event rendering, keep compatibility at export/processor level rather than adding new `span.addEvent()` calls in application code.
 
 ## Setup
 
 ```typescript
-import { init, trace, getRequestLogger } from 'autotel';
+import { init, withTracing, getRequestLogger } from 'autotel';
 
 init({ service: 'my-app' });
 
-const handler = trace((ctx) => async (req: Request, res: Response) => {
-  const log = getRequestLogger(ctx);
-  log.set({ method: req.method, path: req.url });
+const handler = withTracing({ name: 'http.request' })(
+  (ctx) => async (req: Request, res: Response) => {
+    const log = getRequestLogger(ctx);
+    log.set({ method: req.method, path: req.url });
 
-  const user = await getAuth(req);
-  log.set({ user: { id: user.id } });
+    const user = await getAuth(req);
+    log.set({ user: { id: user.id } });
 
-  const result = await doWork(req);
-  log.set({ result: { id: result.id } });
-  log.emitNow();
-  return res.json(result);
-});
+    const result = await doWork(req);
+    log.set({ result: { id: result.id } });
+    log.emitNow();
+    return res.json(result);
+  },
+);
 ```
 
 When the framework creates the span (e.g. Hono middleware), call `getRequestLogger()` with no args:
@@ -91,4 +93,7 @@ Source: packages/autotel/src/request-logger.ts
 
 Targets autotel v2.23.x.
 
-See also: autotel-instrumentation/SKILL.md — creating the span. autotel-structured-errors/SKILL.md — use .error() to record errors in the snapshot.
+See also:
+
+- `autotel-instrumentation/SKILL.md` for creating the span
+- `autotel-structured-errors/SKILL.md`, which uses `.error()` to record errors in the snapshot

package/skills/autotel-structured-errors/SKILL.md

@@ -4,7 +4,7 @@ description: >
   createStructuredError, parseError, recordStructuredError. API errors with message, why, fix, link; client parsing for UI. Use in API routes and client catch blocks.
 ---
 
-# Autotel — Structured Errors
+# Autotel: Structured Errors
 
 Throw errors with `createStructuredError({ message, why?, fix?, link?, status?, cause? })` in API routes and services. On the client, use `parseError(caught)` to get `message`, `status`, `why`, `fix`, `link` for toasts and UI.
 
@@ -122,4 +122,4 @@ Source: docs/AGENT-GUIDE.md
 
 Targets autotel v2.23.x.
 
-See also: autotel-request-logging/SKILL.md — use .error() to record errors in the request snapshot.
+See also: autotel-request-logging/SKILL.md. Use .error() to record errors in the request snapshot.

package/skills/build-audit-trails/SKILL.md

@@ -17,9 +17,9 @@ license: MIT
 
 # Build audit trails
 
-An _audit trail_ is a record of who did what to which resource, when, and whether it was permitted — durable, tamper-evident, and admissible. Operational telemetry (latency, errors, span shapes) is for engineers; audit trails are for compliance, security, and forensics. They overlap technically but differ on every other axis.
+An _audit trail_ is a record of who did what to which resource, when, and whether it was permitted. Durable, tamper-evident, and admissible. Operational telemetry (latency, errors, span shapes) is for engineers; audit trails are for compliance, security, and forensics. They overlap technically but differ on every other axis.
 
-autotel lets you express both with the same primitive — a span — but you should keep them on **separate processors** so an audit event never gets dropped by sampling, never gets redacted by a debug rule, and never goes to the same backend as your ops data.
+autotel lets you express both with the same primitive, a span, but you should keep them on **separate processors** so an audit event never gets dropped by sampling, never gets redacted by a debug rule, and never goes to the same backend as your ops data.
 
 ## When to use
 
@@ -251,14 +251,14 @@ Verify on the read side: recompute the HMAC over the same sorted attribute set (
 
 For multi-tenant or extra-strict (HIPAA), use Ed25519 with per-environment keys and rotate.
 
-## Step 5: Redaction — what stays and what goes
+## Step 5: Redaction: what stays and what goes
 
 | Field                    | In audit span? | Notes                                                                                 |
 | ------------------------ | -------------- | ------------------------------------------------------------------------------------- |
 | `enduser.id`             | ✅             | Internal user id; never the email                                                     |
 | `audit.resource.id`      | ✅             | Required for forensics                                                                |
 | `client.address`         | ✅             | Last-octet redaction acceptable for IPv4                                              |
-| Free-form payload bodies | ❌             | Never inline raw input — link by id (`audit.evidence.id`)                             |
+| Free-form payload bodies | ❌             | Never inline raw input: link by id (`audit.evidence.id`)                              |
 | Secret values            | ❌             | Use `audit.action=secret.read` + `audit.resource.id=sec_abc`, never the secret itself |
 | Authorization headers    | ❌             | Token names ok (`bearer.*`), values never                                             |
 
@@ -356,7 +356,7 @@ app.post('/secrets/:id/read', async (c) => {
 
 ### Cloudflare Workers
 
-`audit()` from inside `defineWorkerFetch` — `ctx.waitUntil` makes sure the audit span is exported before the response returns:
+`audit()` from inside `defineWorkerFetch`. `ctx.waitUntil` makes sure the audit span is exported before the response returns:
 
 ```typescript
 export default defineWorkerFetch(
@@ -452,9 +452,9 @@ To query the trail (denials, per-actor history, tamper detection) across Honeyco
 
 ## Glossary
 
-- **Audit span** — an OpenTelemetry span that records who did what to which resource, marked `audit` / `autotel.audit` so it is routed and retained separately from ops telemetry.
-- **Force-keep** — opting a span out of tail sampling so it is always exported; `forceKeepAuditEvent()` sets the autotel tail-keep flags.
-- **Denial** — an authorization decision that blocked an action; recorded with `audit.outcome = 'deny'` and a reason. Logging denials is as important as logging successes.
-- **Hash-chain** — linking each audit record to the hash of the previous one so removing or reordering records is detectable.
-- **Crypto-shredding** — satisfying an erasure request by destroying the per-subject encryption key rather than deleting the immutable record.
-- **Append-only store** — a backend that rejects updates and deletes (S3 Object Lock, immutable bucket, WORM storage), the destination for audit spans.
+- **Audit span**: an OpenTelemetry span that records who did what to which resource, marked `audit` / `autotel.audit` so it is routed and retained separately from ops telemetry.
+- **Force-keep**: opting a span out of tail sampling so it is always exported; `forceKeepAuditEvent()` sets the autotel tail-keep flags.
+- **Denial**: an authorization decision that blocked an action; recorded with `audit.outcome = 'deny'` and a reason. Logging denials is as important as logging successes.
+- **Hash-chain**: linking each audit record to the hash of the previous one so removing or reordering records is detectable.
+- **Crypto-shredding**: satisfying an erasure request by destroying the per-subject encryption key rather than deleting the immutable record.
+- **Append-only store**: a backend that rejects updates and deletes (S3 Object Lock, immutable bucket, WORM storage), the destination for audit spans.

package/skills/build-audit-trails/references/audit-queries.md

@@ -8,7 +8,7 @@ Run these against the **audit backend** (the append-only one), not your ops back
 
 A spike in denials is a security signal (credential stuffing, privilege probing).
 
-- **Honeycomb** — filter `autotel.audit = true` AND `audit.outcome = deny`, group by `audit.action` and `enduser.id`, visualize `COUNT`.
+- **Honeycomb**: filter `autotel.audit = true` AND `audit.outcome = deny`, group by `audit.action` and `enduser.id`, visualize `COUNT`.
 - **Grafana Tempo (TraceQL)**:
   ```
   { span.autotel.audit = true && span.audit.outcome = "deny" }
@@ -22,7 +22,7 @@ A spike in denials is a security signal (credential stuffing, privilege probing)
 
 Answer "everything user X did" for an access review or incident.
 
-- **Honeycomb** — filter `enduser.id = "usr_42"`, group by `audit.action`, `audit.resource.type`, order by timestamp.
+- **Honeycomb**: filter `enduser.id = "usr_42"`, group by `audit.action`, `audit.resource.type`, order by timestamp.
 - **TraceQL**:
   ```
   { span.enduser.id = "usr_42" && span.autotel.audit = true }
@@ -49,7 +49,7 @@ Answer "everyone who accessed secret `sec_abc`".
 
 Confirm sensitive actions are actually being recorded. Group audit spans by `audit.action` and compare against your list of auditable actions. An action that never appears is either never exercised or never audited; both deserve a look.
 
-- **Honeycomb** — group by `audit.action`, `COUNT`, over 30 days.
+- **Honeycomb**: group by `audit.action`, `COUNT`, over 30 days.
 
 ## Detect tampering or missing signatures
 

package/skills/debug-missing-spans/SKILL.md

@@ -18,7 +18,7 @@ When a span you expect isn't in the backend, the cause is somewhere in this chai
 code → SDK init → head sampler → processor → exporter → network → backend ingest → backend index
 ```
 
-This skill walks each link in order with a quick check you can run. Don't skip steps — the cause is rarely where you'd guess.
+This skill walks each link in order with a quick check you can run. Don't skip steps. The cause is rarely where you'd guess.
 
 ## Step 0: Reproduce locally with the pretty exporter
 
@@ -31,7 +31,7 @@ init({
 });
 ```
 
-If you see the span in stdout, the SDK + sampler are fine — skip to "exporter / network". If you don't, keep reading.
+If you see the span in stdout, the SDK + sampler are fine. Skip to "exporter / network". If you don't, keep reading.
 
 ## Step 1: Is the SDK actually initialised?
 
@@ -60,9 +60,9 @@ console.log('[autotel-debug] sampling:', getActiveConfig()?.sampling);
 
 Common gotchas:
 
-- `sampling.rates: { server: 5 }` — 5 % means 95 % of spans never start.
+- `sampling.rates: { server: 5 }`: 5 % means 95 % of spans never start.
 - Inheriting `OTEL_TRACES_SAMPLER_ARG=0.01` from the environment via the OTel default sampler.
-- Your test happens to hit the unsampled branch — instrument with `sampling: { rates: { server: 100 } }` while reproducing.
+- Your test happens to hit the unsampled branch: instrument with `sampling: { rates: { server: 100 } }` while reproducing.
 
 To force sampling for one request, send a `traceparent` with the sampled flag set:
 
@@ -72,13 +72,13 @@ traceparent: 00-<traceid>-<spanid>-01
 
 (`-01` at the end = sampled.) autotel's parent-based sampler will respect it.
 
-## Step 3: Cloudflare Workers — `ctx.waitUntil`
+## Step 3: Cloudflare Workers: `ctx.waitUntil`
 
 The single biggest cause of missing spans on the edge: **the response returned before the exporter flushed**.
 
 If you're using `addEventListener('fetch', …)` or a hand-rolled `fetch` in a module worker without wiring `ctx.waitUntil(…)` to the export call, async drains drop silently.
 
-Fix — switch to `defineWorkerFetch` or `wrapModule`, both of which wire `waitUntil` automatically:
+Fix. Switch to `defineWorkerFetch` or `wrapModule`, both of which wire `waitUntil` automatically:
 
 ```typescript
 import { defineWorkerFetch } from 'autotel-cloudflare';
@@ -164,16 +164,16 @@ curl -v -X POST $OTLP_ENDPOINT \
   -d '{"resourceSpans":[]}'
 ```
 
-Should return `200`. If it doesn't, the problem is between you and the Collector — not autotel.
+Should return `200`. If it doesn't, the problem is between you and the Collector. Not autotel.
 
 For Cloudflare Workers, run `wrangler tail` and look for `OTLPExporter` errors.
 
-## Step 7: Backend ingest — silent rejection
+## Step 7: Backend ingest: silent rejection
 
 Some backends accept the request with a 200 but drop the events:
 
 - **Honeycomb**: dataset must exist _and_ the API key must have write access to it. Mismatched key/dataset → silent drop.
-- **Datadog**: check `service` is set (resource attribute `service.name`) — they ignore spans without it.
+- **Datadog**: check `service` is set (resource attribute `service.name`): they ignore spans without it.
 - **Sentry**: SDK version mismatch on envelope → 200 but events disappear.
 - **Grafana Cloud Tempo**: spans without `service.name` go to a fallback service called `unknown_service`.
 
@@ -219,9 +219,9 @@ Don't conclude the span is missing until you've waited > 2× the expected lag.
 
 Some spans land, some don't:
 
-- **Trace context broken between services** — outbound HTTP calls aren't propagating `traceparent`. Confirm autotel's global fetch instrumentation is on (`instrumentation.instrumentGlobalFetch: true`, default).
-- **Async boundary loses context** — a `setTimeout` / queue callback ran outside the AsyncLocalStorage scope. Wrap with `trace()` or use `context.with()`.
-- **Cross-runtime call** — Node service → Workers → browser; verify `traceparent` arrives at each leg via response headers / network panel.
+- **Trace context broken between services**: outbound HTTP calls aren't propagating `traceparent`. Confirm autotel's global fetch instrumentation is on (`instrumentation.instrumentGlobalFetch: true`, default).
+- **Async boundary loses context**: a `setTimeout` / queue callback ran outside the AsyncLocalStorage scope. Wrap with `trace()` or use `context.with()`.
+- **Cross-runtime call**: Node service → Workers → browser; verify `traceparent` arrives at each leg via response headers / network panel.
 
 ## When the SDK itself crashes