agent-inspect 1.8.0 → 2.0.0

package/docs/API.md

@@ -1,4 +1,4 @@
-# API (AgentInspect 1.x)
+# API
 
 This document describes the **public TypeScript API surface** of AgentInspect and classifies each area as **stable** or **experimental**.
 
@@ -6,24 +6,54 @@ AgentInspect is a **local-first execution-tree debugger**. It is not a SaaS, not
 
 ## 1. Stability policy
 
-- **Stable**: intended to be compatible across v1.x. Breaking changes require v2.0.
-- **Experimental**: available for adoption, but subject to refinement (including naming/shape changes) before a future stability declaration. Experimental APIs may change in v1.x.
+- **Stable**: intended to stay compatible within the current major version.
+- **Experimental**: available for adoption, but subject to refinement (including naming/shape changes) before a future stability declaration.
 
-**1.x subpath exports:** Additive subpaths (`/logs`, `/exporters`, `/persisted`, `/diff`, `/advanced`, `/writers`, `/readers`) narrow the import surface for experimental and advanced APIs. Root `"."` imports remain valid through v1.x. Design: [API-BOUNDARY-V1.5.md](./implementation/API-BOUNDARY-V1.5.md).
+Use the root import for stable beginner APIs. Use subpaths for advanced, experimental, or lower-level workflows.
+
+```ts
+import {
+  createInspector,
+  observe,
+  inspectRun,
+  maybeInspectRun,
+  step,
+  getCurrentCorrelationMetadata,
+} from "agent-inspect";
+```
+
+**v2 root API contract:** do not add new root exports casually. Advanced, experimental, and lower-level helpers belong on the subpath where the API lives. The stable root value set is:
+
+```ts
+import {
+  createInspector,
+  observe,
+  inspectRun,
+  maybeInspectRun,
+  step,
+  getCurrentCorrelationMetadata,
+} from "agent-inspect";
+```
+
+**Subpath exports:** Subpaths (`/logs`, `/exporters`, `/persisted`, `/diff`, `/advanced`, `/writers`, `/readers`, `/checks`) narrow the import surface for experimental and advanced APIs. Design history: [API-BOUNDARY-V1.5.md](./implementation/API-BOUNDARY-V1.5.md).
 
 ```ts
-import { inspectRun, step } from "agent-inspect";
 import { parseLogsToTrees } from "agent-inspect/logs";
 import { exportMarkdown } from "agent-inspect/exporters";
 import { memoryWriter } from "agent-inspect/writers";
 import { openTrace } from "agent-inspect/readers";
+import { runTraceChecks } from "agent-inspect/checks";
+import { diffTraceEvents } from "agent-inspect/diff";
+import { traceEventsToPersistedInspectEvents } from "agent-inspect/persisted";
+import { createInspectorRuntime } from "agent-inspect/advanced";
 ```
 
 Notes:
 
-- The core guarantee of v1.x is **stable local debugging**: manual tracing + CLI inspection.
+- The core guarantee is **stable local debugging**: manual tracing + CLI inspection.
 - Export formats (OpenInference / OTLP JSON) are **local-only** and **compatibility-oriented**. They do **not** upload anywhere.
-- There are **zero production sinks** in v1.x; sink/uploader APIs are not stable.
+- There are **zero production sinks**; sink/uploader APIs are not stable.
+- Advanced APIs are available from `agent-inspect/advanced`, `agent-inspect/readers`, `agent-inspect/writers`, `agent-inspect/checks`, `agent-inspect/diff`, `agent-inspect/exporters`, `agent-inspect/logs`, and `agent-inspect/persisted`.
 
 ## 2. Stable core APIs (manual tracing)
 
@@ -32,7 +62,13 @@ These are the recommended entry points for manual instrumentation. They are desi
 Import from `agent-inspect`:
 
 ```ts
-import { inspectRun, maybeInspectRun, step, observe } from "agent-inspect";
+import {
+  observe,
+  inspectRun,
+  maybeInspectRun,
+  step,
+  getCurrentCorrelationMetadata,
+} from "agent-inspect";
 ```
 
 - **`inspectRun(name, fn, options?)`**: wraps a workflow in a local JSONL trace (`run_started` / `run_completed`), prints terminal progress, and swallows instrumentation failures (user errors are re-thrown). **Traces by default** when `enabled` is omitted or `true`. Pass **`enabled: false`** to run `fn` with no trace file, no execution context, and no terminal output.
@@ -43,14 +79,14 @@ import { inspectRun, maybeInspectRun, step, observe } from "agent-inspect";
   - **`maxEventBytes`**: max UTF-8 bytes per serialized JSONL event (default `65536`). Oversized events are truncated; instrumentation never throws into user code.
   - **Correlation metadata (v1.3.0+):** optional `correlationId`, `requestId`, `decisionId`, and `groupId` strings. When set, they are written on `run_started.metadata` (not on every step). Top-level correlation options override the same keys in `options.metadata`. Useful for eval cases, CI job IDs, request tracing, and `stats --correlation-id` / `--group-id`. They are **metadata only** — they do not replace `runId`. Treat sensitive IDs as trace data before sharing exports.
 - **`maybeInspectRun(name, fn, options?)`**: same as `inspectRun` when tracing is enabled; otherwise passthrough. Enablement: explicit **`options.enabled`** wins; when omitted, reads **`AGENT_INSPECT`** (`1`, `true`, `yes`, `on`, `enabled` — case-insensitive). Unset or other values disable tracing. Use in eval harnesses, CI, or jobs where tracing should be toggled by environment.
-- **`isAgentInspectEnabled(value?)`**: returns whether a string (or `process.env.AGENT_INSPECT`) matches an enable token.
+- **`isAgentInspectEnabled(value?)`**: advanced helper available from `agent-inspect/advanced`; returns whether a string (or `process.env.AGENT_INSPECT`) matches an enable token.
 - **`step(name, fn, options?)`**: traces a named unit of work inside `inspectRun` (`step_started` / `step_completed`). Step `metadata` inherits the parent run's redaction and size-bound settings.
   - **`step.llm(model, fn)`**: convenience wrapper (`type: "llm"`, `metadata.model`).
   - **`step.tool(toolName, fn)`**: convenience wrapper (`type: "tool"`, `metadata.toolName`).
 - **`observe(agent, options?)`**: proxy wrapper that traces top-level `run` / `execute` / `invoke` methods via `inspectRun`.
 - **`getCurrentCorrelationMetadata()`**: returns active run correlation fields (`correlationId`, `requestId`, `decisionId`, `groupId`) inside `inspectRun` / `maybeInspectRun`; `undefined` outside a traced run or when none were set.
 - **`RedactionProfile`**: `"local" | "share" | "strict"` — see `redactionProfile` on `InspectRunOptions` and `ExportOptions`.
-- **`resolveRedactionProfile(profile?)`**: resolves profile extra keys and metadata caps (for advanced integrations).
+- **`resolveRedactionProfile(profile?)`**: advanced helper available from `agent-inspect/advanced`; resolves profile extra keys and metadata caps for integrations.
 
 ## 3. Stable local inspection APIs
 
@@ -90,7 +126,7 @@ These APIs support local workflows like listing traces, extracting metadata/summ
 
 ## 5. Experimental log parsing APIs
 
-These are compatibility-oriented utilities for turning structured logs into normalized `InspectEvent` and grouped trees. They remain conservative: **no eval**, **no parsing JS object literals**, JSON logs first-class, log4js best-effort.
+Advanced ingestion: use this when your app already emits structured logs. These are compatibility-oriented utilities for turning structured logs into normalized `InspectEvent` and grouped trees. They remain conservative: **no eval**, **no parsing JS object literals**, JSON logs first-class, log4js best-effort.
 
 - **`parseLogsToTrees`**
 - **`JsonLogParser`**, **`Log4jsParser`**
@@ -152,7 +188,7 @@ Rationale: v1.x includes one official adapter and **zero production sinks**, so
 
 ## 11. Experimental `@agent-inspect/ai-sdk` APIs
 
-`@agent-inspect/ai-sdk` is an optional v1.7 adapter package for Vercel AI SDK v6 telemetry integrations. It is experimental and published as part of the v1.7.0 linked release.
+`@agent-inspect/ai-sdk` is an optional adapter package for Vercel AI SDK v6 telemetry integrations. It is experimental and published as part of the aligned v1.8.0 package set.
 
 Import from `@agent-inspect/ai-sdk`:
 
@@ -188,7 +224,7 @@ Recipe: [examples/recipes/ai-sdk-local-telemetry](../examples/recipes/ai-sdk-loc
 
 ## 12. Experimental `@agent-inspect/vitest` APIs
 
-`@agent-inspect/vitest` is an optional experimental package for local Vitest failure artifacts. In the v1.8 train it remains private/unpublished until release readiness. It does not add a Vitest dependency to root/core, does not upload artifacts, and does not infer trace relationships by timestamp.
+`@agent-inspect/vitest` is an optional experimental workspace package for local Vitest failure artifacts. It remains private/unpublished. It does not add a Vitest dependency to root/core, does not upload artifacts, and does not infer trace relationships by timestamp.
 
 Import from `@agent-inspect/vitest`:
 
@@ -220,7 +256,7 @@ Artifacts are safe structural summaries. They include bounded test identity, sta
 
 ## 13. Experimental `@agent-inspect/jest` APIs
 
-`@agent-inspect/jest` is an optional experimental package for local Jest failure artifacts. In the v1.8 train it remains private/unpublished until release readiness. It does not add a Jest dependency to root/core, does not upload artifacts, and does not infer trace relationships by timestamp.
+`@agent-inspect/jest` is an optional experimental workspace package for local Jest failure artifacts. It remains private/unpublished. It does not add a Jest dependency to root/core, does not upload artifacts, and does not infer trace relationships by timestamp.
 
 Import from `@agent-inspect/jest`:
 
@@ -262,7 +298,7 @@ Artifacts are safe structural summaries. They include bounded test identity, sta
 
 ## 14. Experimental `@agent-inspect/openai-agents` APIs
 
-`@agent-inspect/openai-agents` is an optional experimental package for OpenAI Agents JS tracing processor integration. In the v1.8 train it remains private/unpublished until the manual first-publication gate, but runtime metadata mapping is implemented locally.
+`@agent-inspect/openai-agents` is an optional experimental package for OpenAI Agents JS tracing processor integration. It is public in the aligned v1.8.0 package set and records runtime metadata locally.
 
 Import from `@agent-inspect/openai-agents`:
 
@@ -293,29 +329,29 @@ The processor records local v0.2 persisted events for trace/run, agent, generati
 
 ## 15. Experimental persisted-event foundation (v1.2.0)
 
-These helpers expose the **source-agnostic `PersistedInspectEvent` model** (`schemaVersion: "0.2"`). They are **local-only**, **in-memory**, and **do not change** storage write/read or CLI behavior in v1.2.0.
+These helpers expose the **source-agnostic `PersistedInspectEvent` model**. They are **local-only** and support v0.2 compatibility plus the stable schema 1.0 persisted contract.
 
-Import from `agent-inspect`:
+Import from `agent-inspect/persisted`:
 
 | API | Role |
 | --- | ---- |
-| `isPersistedInspectEvent` | Runtime validator for v0.2 persisted events |
+| `isPersistedInspectEvent` | Runtime validator for supported persisted events |
 | `traceEventToPersistedInspectEvent` | Convert one v0.1 `TraceEvent` |
 | `traceEventsToPersistedInspectEvents` | Batch v0.1 → v0.2 |
 | `inspectEventToPersistedInspectEvent` | Convert one in-memory `InspectEvent` |
-| `inspectEventsToPersistedInspectEvents` | Batch `InspectEvent` → v0.2 |
-| `persistedInspectEventToInspectEvent` | Convert one v0.2 event to `InspectEvent` |
-| `persistedInspectEventsToInspectEvents` | Batch v0.2 → `InspectEvent` |
-| `persistedInspectEventsToRunTrees` | Build `InspectRunTree[]` from v0.2 events (via `TreeBuilder`) |
+| `inspectEventsToPersistedInspectEvents` | Batch `InspectEvent` → persisted events |
+| `persistedInspectEventToInspectEvent` | Convert one persisted event to `InspectEvent` |
+| `persistedInspectEventsToInspectEvents` | Batch persisted events → `InspectEvent` |
+| `persistedInspectEventsToRunTrees` | Build `InspectRunTree[]` from persisted events (via `TreeBuilder`) |
 | `traceEventsToPersistedRunTrees` | v0.1 `TraceEvent[]` → persisted model → trees |
 
 Related types: `PersistedInspectEvent`, `PersistedEventSourceType`, `PersistedEventStatus`, `TraceEventToPersistedOptions`, `InspectEventToPersistedOptions`, `PersistedToInspectEventOptions`, `PersistedTreeBridgeOptions`.
 
 **Notes:**
 
-- Manual trace **writing** remains `schemaVersion: "0.1"`.
-- v0.2 is **not written by default**; use converters and `fixtures/traces-v0.2/` samples for validation.
-- Inspection read paths normalize v0.1 and v0.2 JSONL for local CLI/API use. v0.2 remains experimental as a persisted-event foundation and is not the default writer.
+- Manual global trace **writing** remains `schemaVersion: "0.1"`.
+- `createInspector()` and built-in persisted writer paths target schema 1.0 rows.
+- Inspection read paths normalize v0.1, v0.2, and v1.0 JSONL for local CLI/API use. v0.2 remains a compatibility foundation.
 
 ## 16. Local observability helpers (v1.4.0+)
 
@@ -338,7 +374,7 @@ Report redaction profiles are key-based safeguards applied to the complete rende
 
 ## 18. Experimental trace writers (v1.6)
 
-Trace writers are the first slice of the v1.6 runtime foundation. They are experimental during v1.x and intended for tests, adapters, and future `createInspector` work.
+Trace writers are the local persistence contract for tests, adapters, and `createInspector()` workflows.
 
 Import from `agent-inspect/writers`:
 
@@ -360,7 +396,7 @@ import type {
 ```
 
 - **`TraceWriter`**: async `write(event)`, optional `flush()`, optional `close()`, optional `getStats()`.
-- **`fileWriter({ dir?, filePath? })`**: appends v0.2 `PersistedInspectEvent` JSONL rows to local disk. By default it derives one file per `event.runId`; `filePath` writes all events to an explicit local file. Filesystem and serialization failures are reflected in writer stats instead of being thrown into application code.
+- **`fileWriter({ dir?, filePath? })`**: appends `PersistedInspectEvent` JSONL rows to local disk. `createInspector()` emits schema 1.0 rows by default; compatibility adapters may still pass readable v0.2 rows. By default it derives one file per `event.runId`; `filePath` writes all events to an explicit local file. Filesystem and serialization failures are reflected in writer stats instead of being thrown into application code.
 - **`bufferedFileWriter({ dir?, filePath?, maxQueueSize?, flushIntervalMs?, maxBatchSize?, overflow? })`**: buffers local JSONL writes with bounded queue behavior. Overflow supports `drop-oldest` and `drop-newest`; neither mode throws into application code.
 - **`compositeWriter([...writers])`**: fans out events to multiple explicit local/custom writers. A failing child writer does not prevent other children from receiving events; failures are reflected in composite stats.
 - **`memoryWriter()`**: stores cloned `PersistedInspectEvent` rows in memory for tests, adapter fixtures, and eval harnesses.
@@ -370,12 +406,12 @@ No network writer or vendor sink exists in this package.
 
 ## 19. Experimental inspector API/runtime (v1.6)
 
-`createInspector()` is the experimental public instance API for local-first tracing with explicit writers. It owns an instance-specific runtime context, records v0.2 persisted inspect events, preserves application return values/errors, and exposes diagnostics plus deterministic `flush()`/`close()` lifecycle hooks.
+`createInspector()` is the public instance API for local-first tracing with explicit writers. It owns an instance-specific runtime context, records schema 1.0 persisted inspect events, preserves application return values/errors, and exposes diagnostics plus deterministic `flush()`/`close()` lifecycle hooks.
 
-Import from `agent-inspect/advanced`:
+Import from `agent-inspect`:
 
 ```ts
-import { createInspector } from "agent-inspect/advanced";
+import { createInspector } from "agent-inspect";
 import { memoryWriter } from "agent-inspect/writers";
 
 const writer = memoryWriter();
@@ -406,9 +442,9 @@ Public methods:
 
 `traceDir` and `silent` on `createInspector()` are context metadata for compatibility with existing helpers. They do not configure persistence or terminal output. Prefer writer-owned output configuration such as `fileWriter({ dir })` or `fileWriter({ filePath })`.
 
-`createInspectorRuntime()` is also available from `agent-inspect/advanced` as the low-level isolation primitive. Most users should prefer `createInspector()` and `inspector.getDiagnostics()`. Root exports for the runtime remain available for 1.x compatibility, but new advanced usage should import from `agent-inspect/advanced`.
+`createInspectorRuntime()` is available from `agent-inspect/advanced` as the low-level isolation primitive. Most users should prefer `createInspector()` and `inspector.getDiagnostics()`.
 
-These APIs are experimental during v1.x. They do not add a default network writer or vendor sink.
+The low-level runtime helpers remain on `agent-inspect/advanced`. These APIs do not add a default network writer or vendor sink.
 
 ## 20. Experimental trace readers (v1.6)
 
@@ -461,16 +497,67 @@ The checks API is experimental in v1.x. The `agent-inspect check` CLI uses this
 
 Recipes: [deterministic-ci-checks](../examples/recipes/deterministic-ci-checks/README.md) for check/baseline/artifact workflows, and [test-reporter-artifacts](../examples/recipes/test-reporter-artifacts/README.md) for Vitest/Jest reporter configuration patterns.
 
-## 22. Deprecated APIs
+## 22. Experimental local explain APIs (v1.9)
+
+`buildLocalExplanation()` creates a deterministic local explanation payload from a reader-selected `InspectRunTree`. It performs no network I/O, does not call model providers, and separates observed facts from deterministic inference labels.
+
+Import from `agent-inspect`:
+
+```ts
+import { buildLocalExplanation } from "agent-inspect/advanced";
+```
+
+- **`buildLocalExplanation(run, options?)`**:
+  - **`mode: "dry-run"`**: returns redacted observed facts and no inference labels.
+  - **`mode: "local"`** (default): returns observed facts plus deterministic local inference labels.
+  - **`redactionProfile`**: `local`, `share`, or `strict`; profile keys are redacted before the payload is returned.
+
+CLI wrapper: `agent-inspect explain <trace-path-or-run-id> --dry-run --json`.
+
+Provider design gate:
+
+- No provider payload is submitted in v1.9 implementation chunks; `--provider <provider>` is reserved and rejected with `PROVIDER_NOT_IMPLEMENTED`.
+- The reviewable provider payload contract is the `ExplainResult` object: `mode`, `runId`, optional `name` / `status`, `redactionProfile`, `facts`, `inferences`, and `notes`.
+- Provider implementations must require explicit provider selection and documented environment requirements. The current local API reads no provider credentials.
+- Provider prompts must use redacted facts only, label inferred claims, and must not request raw chain-of-thought.
+- Provider packages or SDKs must not become root/core runtime dependencies.
+
+## 23. Experimental `@agent-inspect/harness` APIs
+
+`@agent-inspect/harness` is a private experimental workspace package during the v1.9 release train. It provides a no-framework fixture runner for local targets and recipes; first public package publication remains a manual maintainer gate.
+
+Import from `@agent-inspect/harness` inside the workspace:
+
+```ts
+import { createFixtureRunner, defineTarget } from "@agent-inspect/harness";
+```
+
+- **`defineTarget(definition)`**: returns a typed target definition with `resolve(app, context)` and `invoke(target, input, context)` hooks.
+- **`createFixtureRunner(options)`**: returns a local runner with:
+  - **`listTargets()`**: deterministic target metadata listing.
+  - **`runTarget(name, input, options?)`**: bootstrap, resolve, invoke, and shutdown lifecycle.
+  - **`runFromArgv(argv?, io?)`**: CLI-friendly execution with target listing, JSON fixture files, JSON stdin, JSON stdout, stderr summaries, trace flags, and expected-output comparison.
+  - **`getDiagnostics()`**: deterministic diagnostics for missing targets, bootstrap failures, resolve failures, invocation failures, and shutdown failures.
+- **`trace`** options use existing AgentInspect local APIs only:
+  - **`mode: "run-if-enabled"`** (default): uses `maybeInspectRun()` and writes no trace unless `options.enabled` or `AGENT_INSPECT` enables tracing.
+  - **`mode: "run"`**: explicitly wraps the target invocation in `inspectRun()`.
+  - **`mode: "observe"`**: proxies the resolved target with `observe()` for `run` / `execute` / `invoke` methods when enabled.
+  - **`mode: "off"`**: invokes the target without AgentInspect tracing.
+
+The harness package does not add root/core dependencies, does not upload traces, does not call providers, and does not capture raw prompts or outputs by itself. It writes only local AgentInspect traces when explicitly enabled by runner options or environment-gated tracing.
+
+Recipes: [harness-basic](../examples/recipes/harness-basic/README.md) and [harness-adapter-local](../examples/recipes/harness-adapter-local/README.md).
+
+## 24. Deprecated APIs
 
 No deprecated APIs are declared as of 1.4.0.
 
-## 23. Removal / deprecation policy
+## 25. Removal / deprecation policy
 
-- Stable APIs are not removed in v1.x.
+- Stable APIs are not removed within the current major version.
 - If removal is necessary, the API should be **deprecated** first, documented, and kept for a reasonable window (target: at least one minor line) unless security requires faster action.
 
-## 24. Backward compatibility policy
+## 26. Backward compatibility policy
 
 - Manual trace JSONL (`schemaVersion: "0.1"`) remains readable.
 - Additive schema changes are allowed in minor versions.

package/docs/CLI.md

@@ -1,4 +1,4 @@
-# CLI (AgentInspect 1.x)
+# CLI
 
 This document describes the **stable CLI surface** of AgentInspect.
 
@@ -26,6 +26,7 @@ Core commands:
 - `tail` — live-tail logs into updating local trees
 - `export` — export manual traces to Markdown/HTML/OpenInference/OTLP JSON (local only)
 - `open` — read supported local trace files, directories, or stdin through the canonical reader pipeline
+- `migrate` — convert one local AgentInspect JSONL file to schema 1.0 with dry-run or explicit output
 - `check` — run deterministic local trace checks with stable JSON and exit codes
 - `scan` — best-effort local safety scan for trace capture risks
 - `verify-safe` — best-effort local trace safety verification
@@ -36,6 +37,7 @@ Core commands:
 - `search` — deterministic local search over traces
 - `what` — concise summary of a single run (local JSONL)
 - `report` — markdown or HTML inspection report for a single run
+- `explain` — deterministic local facts/inferences for a trace, with dry-run payloads
 
 ## 2. Environment variables
 
@@ -138,7 +140,7 @@ Recommendation: run with `--dry-run` first.
 
 ### 6.4 `logs`
 
-Parse structured logs into local execution trees.
+Advanced ingestion: use this when your app already emits structured logs. Parse those logs into local execution trees.
 
 ```bash
 agent-inspect logs <file> [options]
@@ -242,7 +244,36 @@ cat packages/core/test/fixtures/openinference-basic.json | npx agent-inspect ope
 
 When a directory or payload contains multiple runs, `open` lists the run ids and exits until you pass `--run <run-id>`.
 
-### 6.8 `check`
+### 6.8 `migrate`
+
+Convert one local AgentInspect JSONL trace file to the stable schema 1.0 persisted contract. This command is local and non-destructive by default: it does not upload traces, run agents, mutate the input file, or overwrite originals.
+
+```bash
+agent-inspect migrate <input.jsonl> --to 1.0 --dry-run
+agent-inspect migrate <input.jsonl> --to 1.0 --output <output.jsonl>
+```
+
+Options:
+
+- `--to 1.0`: required target schema version
+- `--dry-run`: print deterministic counts and warnings without writing output
+- `-o, --output <path>`: write migrated schema 1.0 JSONL to a separate file
+- `--force`: accepted only for explicit output validation; input overwrite is still refused
+
+Input support:
+
+- v0.1 manual trace rows are converted to schema 1.0 persisted rows.
+- v0.2 and v1.0 persisted rows are preserved/upgraded through the shared persisted contract.
+- malformed JSON and unsupported schema rows are reported as line warnings.
+
+Examples:
+
+```bash
+npx agent-inspect migrate fixtures/traces/minimal-success.jsonl --to 1.0 --dry-run
+npx agent-inspect migrate fixtures/traces/minimal-success.jsonl --to 1.0 --output fixtures/traces/minimal-success.v1.jsonl
+```
+
+### 6.9 `check`
 
 Run deterministic checks against a local trace. This command is local and read-only: it does not rerun agents, call models, upload traces, or mutate input files.
 
@@ -291,7 +322,7 @@ npx agent-inspect check trace.jsonl --max-duration-ms 30000 --required-tool sear
 
 Recipe: [examples/recipes/deterministic-ci-checks](../examples/recipes/deterministic-ci-checks/README.md)
 
-### 6.9 `scan` and `verify-safe`
+### 6.10 `scan` and `verify-safe`
 
 Run best-effort local safety verification for supported trace inputs. These commands are local and read-only: they do not rerun agents, call models, upload traces, mutate input files, or certify compliance.
 
@@ -330,7 +361,7 @@ npx agent-inspect verify-safe minimal-success --dir fixtures/traces
 npx agent-inspect verify-safe trace.jsonl --max-string-length 8192 --json
 ```
 
-### 6.10 `artifacts`
+### 6.11 `artifacts`
 
 Create deterministic local CI artifacts for supported trace inputs. This command is local and read-only for trace inputs: it does not rerun agents, call models, upload files, use GitHub APIs, or mutate repository state. It writes only to `--output-dir` and, when requested, a local step-summary file.
 
@@ -370,7 +401,7 @@ npx agent-inspect artifacts candidate.jsonl --baseline baseline.jsonl --output-d
 
 Recipe and sample workflow: [examples/recipes/deterministic-ci-checks](../examples/recipes/deterministic-ci-checks/README.md)
 
-### 6.11 `diff`
+### 6.12 `diff`
 
 Compare two manual trace runs. Diff is **local** and **read-only** (does not rerun agents).
 
@@ -434,7 +465,7 @@ Differences:
 
 More examples, including timing-only and structure-only diffs, are in `docs/DIFF.md`.
 
-### 6.12 `timeline`
+### 6.13 `timeline`
 
 Chronological step list for one manual trace. Read-only; does not mutate JSONL files.
 
@@ -450,7 +481,7 @@ Options:
 
 ![Timeline with slow-step focus](../assets/demos/timeline.gif)
 
-### 6.13 `stats`
+### 6.14 `stats`
 
 Local aggregate statistics over trace files in a directory. Read-only.
 
@@ -470,7 +501,7 @@ Options:
 
 Use `--correlation-id` or `--group-id` to filter runs by `run_started` metadata (see [API.md](./API.md)).
 
-### 6.14 `search`
+### 6.15 `search`
 
 Deterministic search over local traces (substring / exact filters). No semantic search.
 
@@ -500,7 +531,7 @@ npx agent-inspect search --duration ">100ms" --json
 
 ![Search traces by status error](../assets/demos/search.gif)
 
-### 6.15 `what`
+### 6.16 `what`
 
 Concise human-readable summary of one local trace run. Read-only; accepts v0.1 manual JSONL and v0.2 persisted-event JSONL through the shared dual-format normalization path. Vocabulary: [TRACE-VOCABULARY-V1.5.md](./proposals/TRACE-VOCABULARY-V1.5.md).
 
@@ -529,7 +560,7 @@ Outcome: Completed successfully.
 Slowest: plan (100ms, logic)
 ```
 
-### 6.16 `report`
+### 6.17 `report`
 
 Generate a local inspection report combining **what happened**, **timeline**, and **execution tree** sections. The command reads local v0.1 manual JSONL and v0.2 persisted-event JSONL through the shared dual-format normalization path without mutating them. Distinct from `export` (which targets shareable tree snapshots and standards formats).
 
@@ -554,6 +585,39 @@ Example:
 npx agent-inspect report minimal-success --dir fixtures/traces --format html -o report.html
 ```
 
+### 6.18 `explain`
+
+Explain a local trace using deterministic facts and local inference labels. This command reads through the same local reader pipeline as `open` / `check`; it does not call a model provider, upload traces, replay agents, or mutate input files.
+
+```bash
+agent-inspect explain <trace-path-or-run-id> [options]
+```
+
+Options:
+
+- `--dir <path>` — trace directory for run-id lookup
+- `--format <agent-inspect-jsonl|openinference-json|otlp-json>` — explicit input format
+- `--run <run-id>` — select a run when the trace contains multiple runs
+- `--dry-run` — emit only the redacted facts payload, with no local inference labels
+- `--provider <provider>` — reserved for an explicit future provider mode; currently rejected without network calls
+- `--json` — print deterministic JSON output
+- `--redaction-profile <local|share|strict>` — key-based redaction profile for the explanation payload (default `local`)
+
+Examples:
+
+```bash
+npx agent-inspect explain minimal-success --dir fixtures/traces
+npx agent-inspect explain fixtures/traces/minimal-success.jsonl --dry-run --json --redaction-profile strict
+```
+
+Provider design gate:
+
+- Current behavior is local only. `--provider <provider>` exits with a user-facing `PROVIDER_NOT_IMPLEMENTED` error and performs no provider call.
+- `--dry-run --json` is the payload review surface. The provider payload contract is the returned `explanation` object: `mode`, `runId`, optional `name` / `status`, `redactionProfile`, `facts`, `inferences`, and `notes`.
+- Provider chunks must require explicit provider selection, document required environment variables, and keep credentials out of trace data and dry-run output.
+- Provider prompts must ask for concise explanations from redacted facts only. They must not request, expose, or preserve raw chain-of-thought.
+- Cloud provider behavior is never selected by default and must be reviewed before implementation. Local provider support must still be explicit and opt-in.
+
 ## 7. Optional TUI behavior
 
 `view --tui` delegates to `@agent-inspect/tui` and requires an interactive terminal. If the package is not installed, the CLI prints a short install hint.

package/docs/EXPORTS.md

@@ -75,7 +75,7 @@ Experimental helpers (local-only):
 - `exportMarkdown`, `exportHtml`, `exportOpenInference`, `exportOtlpJson`
 - `validateExport`, `validateExportContent`
 
-See [API.md](./API.md) §7.
+Import these from `agent-inspect/exporters`. See [API.md](./API.md) §7.
 
 ## What not to share