agent-inspect 1.4.0 → 1.6.0

package/CHANGELOG.md

@@ -1,7 +1,70 @@
 # Changelog
 
+## 1.6.0
+
+Released **2026-06-25**.
+
+### Added
+
+- Added experimental `agent-inspect/writers` subpath with `TraceWriter`, `fileWriter`, `bufferedFileWriter`, `compositeWriter`, `memoryWriter`, and `nullWriter` as the first v1.6 runtime foundation slice.
+- Added experimental `createInspectorRuntime()` as the low-level instance-scoped runtime foundation.
+- Added experimental `createInspector()` public instance API for isolated local tracing with explicit writers.
+- Added experimental `agent-inspect/readers` subpath with the `TraceReader` contract, deterministic format detection, `readTrace()`, and `openTrace()` for future local ingestion readers.
+- Added the default AgentInspect JSONL reader behind `readTrace()` / `openTrace()` for v0.1, v0.2, and mixed local trace files.
+- Added local OpenInference JSON and OTLP JSON readers behind `agent-inspect/readers`.
+- Added `agent-inspect open` for local AgentInspect JSONL, OpenInference JSON, OTLP JSON, directory, and stdin ingestion through the canonical reader pipeline.
+- Added deterministic runtime/universal-ingestion recipe coverage for memory writer, buffered writer, `createInspector()`, explicit formats, stdin, and safe shutdown.
+
+### Changed
+
+- Shared inspection commands now route AgentInspect JSONL loading through the canonical reader pipeline where compatible.
+
+### Fixed
+
+- Corrects the published CLI version path so `agent-inspect --version` reports the public package version.
+- Makes `list`, `stats`, and `search` use the canonical dual-format read path for v0.1 and v0.2 trace files.
+- Applies `report --redaction-profile share|strict` to the complete report, not only the execution tree section.
+- Preserves mixed v0.1/v0.2 source ordering during normalization.
+- Preserves error stack fidelity when converting persisted v0.2 events; `error.name` is no longer mapped to v0.1 `stack`.
+- Preserves supported token usage fields across converters and inspection summaries: `input`, `output`, `total`, and `cached`.
+
+### Notes
+
+- Manual trace writing remains `schemaVersion: "0.1"`.
+- v0.2 remains an experimental persisted-event foundation and dual-read input format, not the default writer.
+- No provider pricing, token counting, cost engine, vendor upload, hosted ingestion, replay, or default telemetry behavior is included.
+- This release includes corrective work accumulated after v1.5.0 plus the v1.6.0 runtime/reader foundation.
+
+## 1.5.0
+
+Released **2026-06-24**.
+
+### Added
+
+- Added non-breaking package subpath exports: `agent-inspect/advanced`, `/persisted`, `/logs`, `/exporters`, `/diff` (root `"."` export unchanged).
+- Added `agent-inspect what <runId>` — concise local run summary (`--json`, `--no-correlation`).
+- Added `agent-inspect report <runId>` — markdown/HTML inspection report (`what` + timeline + execution tree).
+- Added core helpers: `buildRunWhatSummary`, `renderRunWhat`, `buildRunReport`.
+- Added canonical dual-format read path: `parseTraceJsonl`, `persistedInspectEventToTraceEvents`; `readTraceEvents` accepts v0.1 and v0.2 JSONL.
+- Added [TRACE-VOCABULARY-V1.5.md](docs/proposals/TRACE-VOCABULARY-V1.5.md) RFC and `fixtures/traces-v0.2/llm-tokens-and-streaming.jsonl`.
+- Added [what-report-inspect recipe](examples/recipes/what-report-inspect/) and CI artifact updates for `what`/`report`.
+
+### Changed
+
+- Inspection CLI commands (`view`, `timeline`, `stats`, `search`, `diff`, `export`, `what`, `report`) use shared dual-format read path (v0.1 + v0.2).
+
+### Notes
+
+- Manual trace writing remains `schemaVersion: "0.1"`.
+- v0.2 read is normalization for inspection — not a write-path switch.
+- Token fields in reports are user-supplied metadata only; core does not count tokens.
+- No vendor upload, hosted dashboard, or cost engine.
+- Linked release aligns `@agent-inspect/tui` with `agent-inspect` and `@agent-inspect/langchain` (all **1.5.0**).
+
 ## 1.4.0
 
+Released **2026-06-12**.
+
 ### Added
 
 - Added `docs/CI-ARTIFACTS.md` and `examples/recipes/github-actions-artifact/` for CI trace artifact workflows.

package/README.md

@@ -10,6 +10,8 @@ The tool starts with **manual traces** and **existing structured logs**, and ext
 
 **No account. No cloud upload. No dashboard required.**
 
+**Visual demos:** [docs/SCREENSHOTS.md](docs/SCREENSHOTS.md) — curated terminal recordings (synthetic fixtures only).
+
 ## Why agent-inspect exists
 
 AI agents are no longer single function calls. They plan, call tools, invoke LLMs, branch, retry, fail, and run work in parallel. **Console logs are flat**; reconstructing causality from a wall of lines is slow and error-prone.
@@ -20,7 +22,7 @@ agent-inspect gives those runs **structure**: an **execution tree** you can read
 
 ## Install
 
-Current npm release: **1.3.0** (`agent-inspect`, `@agent-inspect/langchain`; `@agent-inspect/tui` is **1.2.1** — patch-only alignment release).
+Current npm release: **1.6.0** (`agent-inspect`, `@agent-inspect/langchain`, `@agent-inspect/tui` — all aligned).
 
 ```bash
 npm install agent-inspect
@@ -109,18 +111,19 @@ await maybeInspectRun("eval-case-42", async () => runAgent());
 AGENT_INSPECT=1 node eval-runner.mjs
 ```
 
-## What you can do today (v1.3.0)
+## What you can do today (v1.6.0)
 
 - **Trace manually** with `inspectRun`, `step`, `step.llm`, `step.tool`, and `observe` — local JSONL under `.agent-inspect/` by default.
 - **Toggle tracing** with `maybeInspectRun` and `AGENT_INSPECT=1` in eval harnesses or CI.
 - **Correlate runs** with optional `correlationId`, `requestId`, `decisionId`, and `groupId` on `run_started` metadata.
 - **Redact before disk** with default key-based redaction, or choose `redactionProfile`: `local`, `share`, or `strict`.
-- **Inspect from the CLI** — `list`, `view`, `clean`, `logs`, `tail`, `export`, `diff`, `timeline`, `stats`, `search`.
+- **Inspect from the CLI** — `list`, `view`, `clean`, `logs`, `tail`, `export`, `open`, `diff`, `timeline`, `stats`, `search`, `what`, `report`.
 - **Export share-safe copies** — `export --redaction-profile share` (or `strict`) writes local Markdown/HTML/OpenInference/OTLP JSON only.
 - **Parse structured logs** you already emit (JSON first-class; log4js best-effort).
 - **Optional LangChain adapter** — metadata-only by default; optional `persist: true` and `stream: true` streaming metadata (no full token capture by default).
 - **Optional TUI** — `view --tui` when `@agent-inspect/tui` is installed.
 - **Persisted-event foundation (v1.2.0+)** — in-memory `PersistedInspectEvent` converters; manual writing stays `schemaVersion: "0.1"`.
+- **Experimental v1.6.0 APIs** — `agent-inspect/writers`, `agent-inspect/readers`, `createInspector()`, and `agent-inspect open` for local AgentInspect/OpenInference/OTLP ingestion.
 
 Nothing uploads traces by default. Review exports before sharing — see [safe trace sharing](docs/SAFE-TRACE-SHARING.md).
 
@@ -128,6 +131,10 @@ Nothing uploads traces by default. Review exports before sharing — see [safe t
 
 Each run produces a **JSONL** trace: `run_started` / `run_completed`, `step_started` / `step_completed`, with **nested steps**, **tool/LLM** types where you use `step.tool` / `step.llm`, and **durations** on completed steps. Failures are recorded on `step_completed` with `status: "error"` (there is no separate `step_failed` event). See [docs/SCHEMA.md](docs/SCHEMA.md).
 
+![Nested execution tree from a local JSONL trace](https://raw.githubusercontent.com/rajudandigam/agent-inspect/main/docs/assets/demos/execution-tree.gif)
+
+*Synthetic demo — [examples/02-nested-steps](examples/02-nested-steps/README.md). More visuals: [SCREENSHOTS.md](docs/SCREENSHOTS.md).*
+
 ## Works with structured logs you already have
 
 Many production systems already emit **line-delimited JSON** or text logs with embedded JSON (e.g. via **pino**, **winston**, **log4js**, **NestJS** loggers, job runners, or custom event streams). agent-inspect can turn those into **local grouped timelines/trees** without wrapping every function.
@@ -152,6 +159,8 @@ npx agent-inspect logs ./agent.log --config agent-inspect.logs.json
 - **Flat timeline by default**; nesting when parent relationships are explicit or configured.
 - **Confidence labels** (`explicit`, `correlated`, `heuristic`, `unknown`) describe how attribution was inferred.
 
+**Visual:** JSON log → tree recording is [documented in SCREENSHOTS.md](docs/SCREENSHOTS.md#json-logs--tree) (re-record pending; command above is the canonical flow).
+
 More detail: [docs/LOGS.md](docs/LOGS.md) · [docs/LOG-TO-TREE-QUICKSTART.md](docs/LOG-TO-TREE-QUICKSTART.md) · [docs/LOGGING-PLAYBOOK.md](docs/LOGGING-PLAYBOOK.md) (pino, log4js, NestJS).
 
 ## CLI at a glance
@@ -164,10 +173,17 @@ More detail: [docs/LOGS.md](docs/LOGS.md) · [docs/LOG-TO-TREE-QUICKSTART.md](do
 | `logs` | Turn existing structured logs into a local tree/timeline |
 | `tail` | Watch structured logs while the app runs |
 | `export` | Write Markdown / HTML / OpenInference-compatible JSON / OTLP JSON **locally** |
+| `open` | Read AgentInspect JSONL, OpenInference JSON, or OTLP JSON locally |
 | `diff` | Compare two local runs (read-only) |
 | `timeline` | Chronological view of one run |
 | `stats` | Local aggregates over a trace directory |
 | `search` | Deterministic search over local traces |
+| `what` | Concise summary of one run |
+| `report` | Markdown/HTML inspection report (what + timeline + tree) |
+
+![Timeline with slow-step focus for one run](https://raw.githubusercontent.com/rajudandigam/agent-inspect/main/docs/assets/demos/timeline.gif)
+
+*Synthetic demo — `agent-inspect timeline` on [fixtures/traces](fixtures/traces). Gallery: [SCREENSHOTS.md](docs/SCREENSHOTS.md).*
 
 Full flags and behavior: [docs/CLI.md](docs/CLI.md).
 
@@ -182,16 +198,24 @@ Full flags and behavior: [docs/CLI.md](docs/CLI.md).
 
 ## Stable foundation (AgentInspect 1.x)
 
-**agent-inspect 1.x** (current: **1.3.0**) is the **local-first trace workbench** for TypeScript AI agents:
+**agent-inspect 1.x** (current: **1.6.0**) is the **local-first trace workbench** for TypeScript AI agents:
 
 - Instrument runs with `inspectRun` and `step`
 - Write **local JSONL traces** (`schemaVersion: "0.1"` — compatibility retained)
-- Inspect with **`list`**, **`view`**, **`clean`**, **`logs`**, **`tail`**, **`export`**, **`diff`**
+- Inspect with **`list`**, **`view`**, **`clean`**, **`logs`**, **`tail`**, **`export`**, **`diff`**, **`timeline`**, **`stats`**, **`search`**
 
 **Stable APIs:** `inspectRun()`, `maybeInspectRun()`, `step()`, `step.llm()`, `step.tool()`, `observe()`, `getCurrentCorrelationMetadata()`.
 
 Pass `enabled: false` to `inspectRun` for a no-trace passthrough. Use `maybeInspectRun` with `AGENT_INSPECT=1` to toggle tracing in eval or CI — see [docs/API.md](docs/API.md).
 
+**Shipped in 1.6.0:** experimental writer subpath (`agent-inspect/writers`), isolated `createInspector()` API via `agent-inspect/advanced`, local trace readers via `agent-inspect/readers`, OpenInference/OTLP JSON readers, universal `agent-inspect open`, and deterministic [runtime-and-ingestion recipe](examples/recipes/runtime-and-ingestion/). These remain local-only and do not add upload behavior. Linked release aligns all three npm packages at **1.6.0**.
+
+**Shipped in 1.5.0:** non-breaking subpath exports; `what` and `report` CLI; dual-format read path (v0.1 + v0.2 JSONL); [what-report-inspect recipe](examples/recipes/what-report-inspect/). Linked release aligns all three npm packages at **1.5.0**.
+
+**Roadmap beyond current release work:** future work continues from the local runtime and universal ingestion foundation before broadening framework adapters. See [ROADMAP.md](ROADMAP.md).
+
+**Shipped in 1.4.0:** CI artifact recipe ([docs/CI-ARTIFACTS.md](docs/CI-ARTIFACTS.md)); `timeline`, `stats`, and `search` CLI; core helpers `buildRunTimeline`, `buildTraceStats`, `searchTraces`. Linked release aligns all three npm packages at **1.4.0**.
+
 **Shipped in 1.3.0:** correlation metadata; redaction profiles (`local` / `share` / `strict`); `export --redaction-profile`; LangChain `stream: true` metadata (chunk counts, duration — no full token capture by default).
 
 **Also in 1.x** (local-first extensions):
@@ -264,6 +288,9 @@ The TUI is available as a separate optional package; its programmatic API is exp
 | [examples/recipes/nestjs-json-logging](examples/recipes/nestjs-json-logging) | NestJS JSON logs |
 | [examples/recipes/retry-fallback](examples/recipes/retry-fallback) | Fallback pattern |
 | [examples/recipes/parallel-tools](examples/recipes/parallel-tools) | Parallel tools |
+| [examples/recipes/github-actions-artifact](examples/recipes/github-actions-artifact) | CI trace artifacts |
+| [examples/recipes/what-report-inspect](examples/recipes/what-report-inspect/) | `what` + `report` inspection |
+| [examples/recipes/runtime-and-ingestion](examples/recipes/runtime-and-ingestion/) | v1.6 runtime writers + universal ingestion |
 
 **Recipes** are deterministic and require **no external services** by default. Index: [examples/README.md](examples/README.md), [examples/recipes/README.md](examples/recipes/README.md).
 
@@ -290,7 +317,8 @@ For a detailed comparison, see [Compare with other tools](docs/COMPARE.md).
 | [Install smoke test](docs/INSTALL-SMOKE-TEST.md) | [CLI](docs/CLI.md) | [Security](SECURITY.md) |
 | [Log-to-tree quickstart](docs/LOG-TO-TREE-QUICKSTART.md) | [Schema](docs/SCHEMA.md) | [Limitations](docs/LIMITATIONS.md) |
 | [Logging playbook](docs/LOGGING-PLAYBOOK.md) | [Exports](docs/EXPORTS.md) | [Known issues](docs/KNOWN-ISSUES.md) |
-| [Examples](examples/README.md) | [Adapters](docs/ADAPTERS.md) | [Compare with other tools](docs/COMPARE.md) |
+| [CI artifacts](docs/CI-ARTIFACTS.md) | [Adapters](docs/ADAPTERS.md) | [Compare with other tools](docs/COMPARE.md) |
+| [Visual demos](docs/SCREENSHOTS.md) | [Examples](examples/README.md) | |
 
 Also: [Architecture](docs/ARCHITECTURE.md) · [Logs & tail](docs/LOGS.md) · [Diff](docs/DIFF.md) · [Changelog](CHANGELOG.md) · [Roadmap](ROADMAP.md) · [Contributing](CONTRIBUTING.md) · [Good first issues](GOOD-FIRST-ISSUES.md)
 

package/docs/ADAPTERS.md

@@ -51,6 +51,10 @@ npx agent-inspect view <run-id> --dir ./.agent-inspect
 npx agent-inspect export <run-id> --format markdown --redaction-profile share
 ```
 
+![LangChain callback with persist true writing inspectable JSONL](../assets/demos/langchain-persistence.gif)
+
+*Synthetic demo — [examples/08-langchain-adapter](../../examples/08-langchain-adapter/README.md).*
+
 **Persistence model (Strategy A):**
 
 1. **Standalone session** — one AgentInspect run per callback instance until the root LangChain run completes.
@@ -121,6 +125,8 @@ npm install agent-inspect @agent-inspect/tui
 npx agent-inspect view <run-id> --tui
 ```
 
+![Optional Ink TUI viewer for a local trace](../assets/demos/tui-viewer.gif)
+
 Requires an interactive terminal. See [API.md](./API.md) §10.
 
 ---

package/docs/API.md

@@ -9,6 +9,16 @@ AgentInspect is a **local-first execution-tree debugger**. It is not a SaaS, not
 - **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.
 
+**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).
+
+```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";
+```
+
 Notes:
 
 - The core guarantee of v1.x is **stable local debugging**: manual tracing + CLI inspection.
@@ -31,7 +41,7 @@ import { inspectRun, maybeInspectRun, step, observe } from "agent-inspect";
   - **`maxMetadataValueLength`**: max string length for metadata values (default `2000`).
   - **`maxPreviewLength`**: max string length for preview-like keys containing `preview` (default `500`).
   - **`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 future stats/cohort views. They are **metadata only** — they do not replace `runId`. Treat sensitive IDs as trace data before sharing exports.
+  - **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.
 - **`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.
@@ -164,11 +174,11 @@ Related types: `PersistedInspectEvent`, `PersistedEventSourceType`, `PersistedEv
 
 - Manual trace **writing** remains `schemaVersion: "0.1"`.
 - v0.2 is **not written by default**; use converters and `fixtures/traces-v0.2/` samples for validation.
-- Storage dual-read and CLI integration are future work.
+- 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.
 
-## 12. Local observability helpers (v1.4.0)
+## 12. Local observability helpers (v1.4.0+)
 
-Read-only helpers for timeline, stats, and search over manual `TraceEvent` JSONL. Local files only.
+Read-only helpers for timeline, stats, and search over local JSONL traces. v0.1 manual traces remain the default writer; v0.2 persisted-event files are accepted where the shared dual-format read path is used. Local files only.
 
 - **`buildRunTimeline`**, **`renderTimeline`** — chronological run view; types `RunTimeline`, `TimelineEntry`
 - **`buildTraceStats`**, **`renderTraceStats`** — directory aggregates; type `TraceStats`
@@ -176,23 +186,137 @@ Read-only helpers for timeline, stats, and search over manual `TraceEvent` JSONL
 
 CLI wrappers: `agent-inspect timeline`, `stats`, `search` — see [CLI.md](./CLI.md).
 
-## 13. Deprecated APIs
+## 13. Report and what helpers (v1.5.0+)
+
+Read-only helpers for concise inspection summaries and local reports:
+
+- **`buildRunWhatSummary`**, **`renderRunWhat`** — summarize status, duration, step counts, correlation metadata, slowest step, errors, and supplied token usage.
+- **`buildRunReport`** — render Markdown or HTML reports from local trace events.
+
+Report redaction profiles are key-based safeguards applied to the complete rendered report input, not only to the tree section. Review generated reports before sharing; this is not compliance-grade DLP.
+
+## 14. 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.
+
+Import from `agent-inspect/writers`:
+
+```ts
+import {
+  bufferedFileWriter,
+  compositeWriter,
+  fileWriter,
+  memoryWriter,
+  nullWriter,
+} from "agent-inspect/writers";
+import type {
+  BufferedFileWriterOptions,
+  CompositeTraceWriterOptions,
+  FileTraceWriterOptions,
+  TraceWriter,
+  TraceWriterStats,
+} from "agent-inspect/writers";
+```
+
+- **`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.
+- **`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.
+- **`nullWriter()`**: accepts events without retaining them for disabled mode, overhead comparisons, and no-output tests.
+
+No network writer or vendor sink exists in this package.
+
+## 15. 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.
+
+Import from `agent-inspect/advanced`:
+
+```ts
+import { createInspector } from "agent-inspect/advanced";
+import { memoryWriter } from "agent-inspect/writers";
+
+const writer = memoryWriter();
+const inspector = createInspector({
+  writer,
+  capture: { onSuccess: "metadata-only", onError: "metadata-only" },
+});
+
+await inspector.run("support-agent", async () => {
+  await inspector.step("plan", async () => "ok");
+  await inspector.tool("retrieve-policy", async () => "policy");
+  return inspector.llm("fixture-model", async () => "done");
+});
+
+await inspector.flush();
+```
+
+Public methods:
+
+- **`run(name, fn, options?)`**: starts an isolated run context and writes run lifecycle events.
+- **`step(name, fn, options?)`**: writes nested step lifecycle events when called inside the same inspector's run context; outside a context it passes through.
+- **`tool(name, fn, options?)`** / **`llm(name, fn, options?)`**: convenience wrappers that set `type` and metadata.
+- **`observe(name, fn, options?)`**: returns an async wrapper that records the function call as an inspector step.
+- **`getDiagnostics()`**: returns instrumentation error counts and writer stats without requiring direct runtime access.
+- **`flush()`** / **`close()`**: delegate to the configured writer through the runtime.
+
+`capture` is explicit and metadata-only. `onSuccess: "metadata-only"` records safe type/length/key-count summaries in `outputSummary`; `onError: "metadata-only"` records thrown-value type/name summaries. It does not store raw return values, prompts, outputs, or thrown objects. Use `"none"` to disable a capture side.
+
+`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`.
+
+These APIs are experimental during v1.x. They do not add a default network writer or vendor sink.
+
+## 16. Experimental trace readers (v1.6)
+
+`agent-inspect/readers` exposes the experimental local trace reader contract and detection pipeline. It includes AgentInspect JSONL for v0.1, v0.2, and mixed local trace files, plus local OpenInference JSON and OTLP JSON compatibility readers.
+
+Import from `agent-inspect/readers`:
+
+```ts
+import {
+  DEFAULT_TRACE_READERS,
+  agentInspectJsonlReader,
+  detectTraceFormat,
+  openInferenceJsonReader,
+  openTrace,
+  otlpJsonReader,
+  readTrace,
+} from "agent-inspect/readers";
+import type { TraceReader } from "agent-inspect/readers";
+```
+
+- **`TraceInput`**: file, directory, string, buffer, or stdin input descriptor.
+- **`TraceReader`**: experimental reader interface with `format`, `detect(input)`, and `read(input)`.
+- **`detectTraceFormat(input, { readers?, format? })`**: deterministic, conservative format detection. Explicit `format` acts as an override only when a matching reader is registered.
+- **`readTrace(input, { readers?, format? })`**: detects a reader and returns `TraceReadResult`; unsupported or ambiguous input throws `TraceReadError`.
+- **`openTrace(input, options?)`**: alias for `readTrace()` and the API path used by the universal `agent-inspect open` command.
+- **`agentInspectJsonlReader`**: built-in local AgentInspect JSONL reader for v0.1, v0.2, and mixed files/directories.
+- **`openInferenceJsonReader`**: local OpenInference JSON compatibility reader. Prompt/output-like attributes are summarized and bounded rather than stored as raw content.
+- **`otlpJsonReader`**: local OTLP/HTTP JSON trace payload reader. Resource, scope, span, status, event, and parent metadata are preserved where possible with warnings for unsupported fields.
+- **`DEFAULT_TRACE_READERS`**: ordered built-in reader registry used when no custom `readers` array is supplied.
+
+The reader contract does not silently accept arbitrary JSON and does not add OTel SDK, database, hosted ingestion, or network upload dependencies.
+
+## 17. Deprecated APIs
 
 No deprecated APIs are declared as of 1.4.0.
 
-## 14. Removal / deprecation policy
+## 18. Removal / deprecation policy
 
 - Stable APIs are not removed in v1.x.
 - 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.
 
-## 15. Backward compatibility policy
+## 19. Backward compatibility policy
 
 - Manual trace JSONL (`schemaVersion: "0.1"`) remains readable.
 - Additive schema changes are allowed in minor versions.
 - Breaking changes require a major version.
 - Unknown fields should be ignored where safe.
 
-## 16. Examples
+## 20. Examples
 
 ### Minimal manual trace
 
@@ -206,4 +330,3 @@ await inspectRun("demo-agent", async () => {
   return { plan, hits, answer };
 });
 ```
-

package/docs/ARCHITECTURE.md

@@ -39,6 +39,10 @@ See [SECURITY.md](../SECURITY.md) and [LIMITATIONS.md](./LIMITATIONS.md).
 
 See [ADAPTERS.md](./ADAPTERS.md).
 
+### Architecture proposals
+
+Maintainer-owned RFCs and planning proposals are indexed in [proposals/README.md](./proposals/README.md). The active post-v1.5 roadmap is [implementation/ROADMAP-V1.6-TO-V3.md](./implementation/ROADMAP-V1.6-TO-V3.md).
+
 ### Where to read next
 
 - New users: [GETTING-STARTED.md](./GETTING-STARTED.md)

package/docs/CLI.md

@@ -25,10 +25,13 @@ Core commands:
 - `logs` — parse structured logs into local execution trees
 - `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
 - `diff` — compare two manual traces (local, read-only)
 - `timeline` — chronological view of one run (local JSONL)
 - `stats` — local aggregate stats over a trace directory
 - `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
 
 ## 2. Environment variables
 
@@ -190,7 +193,36 @@ npx agent-inspect export <run-id> --format markdown --redaction-profile share
 npx agent-inspect export <run-id> --format html --redaction-profile strict
 ```
 
-### 6.7 `diff`
+### 6.7 `open`
+
+Open any local trace format supported by the canonical reader pipeline. This command is read-only: it does not mutate input files, upload traces, or run agents.
+
+```bash
+agent-inspect open [input] [options]
+```
+
+`input` may be a file, directory, `-` for stdin, or omitted to read stdin.
+
+Options:
+
+- `--format <agent-inspect-jsonl|openinference-json|otlp-json>`: explicit reader format override
+- `--run <run-id>`: select a run when input contains multiple runs
+- `--json`: print structured JSON output
+- `--diagnostics`: print reader warnings and unsupported fields in human output
+
+Examples:
+
+```bash
+npx agent-inspect open fixtures/traces/minimal-success.jsonl --format agent-inspect-jsonl
+npx agent-inspect open fixtures/traces-v0.2/manual-basic.jsonl --format agent-inspect-jsonl
+npx agent-inspect open packages/core/test/fixtures/openinference-basic.json --format openinference-json
+npx agent-inspect open packages/core/test/fixtures/otlp-basic.json --format otlp-json
+cat packages/core/test/fixtures/openinference-basic.json | npx agent-inspect open - --format openinference-json --json
+```
+
+When a directory or payload contains multiple runs, `open` lists the run ids and exits until you pass `--run <run-id>`.
+
+### 6.8 `diff`
 
 Compare two manual trace runs. Diff is **local** and **read-only** (does not rerun agents).
 
@@ -254,7 +286,7 @@ Differences:
 
 More examples, including timing-only and structure-only diffs, are in `docs/DIFF.md`.
 
-### 6.8 `timeline`
+### 6.9 `timeline`
 
 Chronological step list for one manual trace. Read-only; does not mutate JSONL files.
 
@@ -268,7 +300,9 @@ Options:
 - `--json` — structured `RunTimeline` JSON
 - `--focus slow` — show only the slowest steps by duration (top N)
 
-### 6.9 `stats`
+![Timeline with slow-step focus](../assets/demos/timeline.gif)
+
+### 6.10 `stats`
 
 Local aggregate statistics over trace files in a directory. Read-only.
 
@@ -284,7 +318,11 @@ Options:
 - `--group-id <id>` — filter by `run_started.metadata.groupId`
 - `--json`
 
-### 6.10 `search`
+![Directory-level stats over local traces](../assets/demos/stats.gif)
+
+Use `--correlation-id` or `--group-id` to filter runs by `run_started` metadata (see [API.md](./API.md)).
+
+### 6.11 `search`
 
 Deterministic search over local traces (substring / exact filters). No semantic search.
 
@@ -312,6 +350,62 @@ npx agent-inspect search --kind tool --name search
 npx agent-inspect search --duration ">100ms" --json
 ```
 
+![Search traces by status error](../assets/demos/search.gif)
+
+### 6.12 `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).
+
+```bash
+agent-inspect what <run-id> [options]
+```
+
+Options:
+
+- `--dir <path>`
+- `--json` — structured `RunWhatSummary` JSON
+- `--no-correlation` — omit correlation ids from human output
+
+Example:
+
+```bash
+npx agent-inspect what minimal-success --dir fixtures/traces
+```
+
+Sample output:
+
+```
+What: minimal-success
+Status: success · Duration: 120ms · Steps: 1 (1 logic)
+Outcome: Completed successfully.
+Slowest: plan (100ms, logic)
+```
+
+### 6.13 `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).
+
+```bash
+agent-inspect report <run-id> [options]
+```
+
+Options:
+
+- `--dir <path>`
+- `--format <markdown|html>` — default `markdown`
+- `-o, --output <path>` — write to file
+- `--json` — JSON wrapper (includes `content` when writing to stdout)
+- `--include-attributes` — bounded attributes in the execution tree section
+- `--no-errors` — omit error details from the execution tree section
+- `--no-correlation` — omit correlation ids from what section
+- `--redaction-profile <local|share|strict>` — key-based redaction profile applied to the complete report (default `local`); review output before sharing
+
+Example:
+
+```bash
+npx agent-inspect report minimal-success --dir fixtures/traces --format html -o report.html
+```
+
 ## 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.
@@ -326,4 +420,3 @@ See:
 
 - `docs/KNOWN-ISSUES.md`
 - `docs/LIMITATIONS.md`
-

package/docs/DIFF.md

@@ -10,6 +10,14 @@ Notes:
 - `diff` is read-only and does **not** rerun agents; “differences” do not necessarily imply failure (command errors do).
 - `diff` reads local trace files only. It is useful for local debugging, but it is not production APM or hosted observability.
 
+![Diff comparing a success run and an error run](assets/demos/diff-runs.gif)
+
+```bash
+agent-inspect diff minimal-success minimal-error --dir fixtures/traces
+```
+
+More visuals: [SCREENSHOTS.md](./SCREENSHOTS.md).
+
 ## CLI examples
 
 The examples below use the checked-in fixture traces, so they are safe to copy and run locally:

package/docs/EXPORTS.md

@@ -23,6 +23,19 @@ Full flags: [CLI.md](./CLI.md) §6.6.
 
 All formats are **compatibility-oriented** for local inspection and handoff — not guaranteed to match every vendor schema version.
 
+### Markdown export
+
+![Export a run to Markdown locally](assets/demos/markdown-export.gif)
+
+```bash
+agent-inspect export minimal-success --dir fixtures/traces --format markdown
+```
+
+### HTML, OpenInference, OTLP
+
+- **HTML:** export writes a local file; a rendered-report visual is pending re-record ([RECORDING.md](./assets/demos/RECORDING.md)). Use `agent-inspect export <run-id> --format html -o report.html` and open the file locally.
+- **OpenInference / OTLP JSON:** compatibility-oriented shapes for local handoff — validate with `--validate` before sharing. No dedicated GIF; see format tables below.
+
 ## Common options
 
 | Flag | Notes |

package/docs/GETTING-STARTED.md

@@ -2,6 +2,8 @@
 
 AgentInspect is a **local-first execution-tree debugger** for TypeScript AI agents. It helps you produce and inspect an execution tree of steps, safely and deterministically, without uploading data anywhere.
 
+**Visual demos:** [SCREENSHOTS.md](./SCREENSHOTS.md)
+
 ## 1. Install
 
 ```bash
@@ -58,6 +60,10 @@ await maybeInspectRun("eval-case-42", async () => {
 AGENT_INSPECT=1 node eval-runner.mjs
 ```
 
+![Env-gated tracing with maybeInspectRun](../assets/demos/env-gated-tracing.gif)
+
+*When `AGENT_INSPECT` is unset, no trace files are written.*
+
 Enable tokens: `1`, `true`, `yes`, `on`, `enabled` (case-insensitive). Explicit `enabled: true | false` in options overrides the env var.
 
 ### Correlation metadata (v1.3.0+)
@@ -136,7 +142,19 @@ agent-inspect export minimal-success --dir fixtures/traces \
 
 Exports are **local-only** and do not upload anywhere. Review output before sharing — see [SAFE-TRACE-SHARING.md](./SAFE-TRACE-SHARING.md).
 
-## 8. Diff two runs
+## 8. Local observability (v1.4.0+)
+
+After traces exist under a directory:
+
+```bash
+agent-inspect timeline <run-id> --dir ./.agent-inspect
+agent-inspect stats --dir ./.agent-inspect --since 7d
+agent-inspect search --dir ./.agent-inspect --status error --limit 10
+```
+
+For CI artifact workflows, see [CI-ARTIFACTS.md](./CI-ARTIFACTS.md) and [github-actions-artifact recipe](../examples/recipes/github-actions-artifact/).
+
+## 9. Diff two runs
 
 ```bash
 agent-inspect diff minimal-success minimal-error --dir fixtures/traces