agent-inspect 1.3.0 → 1.5.0

package/CHANGELOG.md

@@ -1,12 +1,55 @@
 # Changelog
 
-## 1.3.0
+## 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
 
-### Minor Changes
+- 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**).
 
-- 503d240: Correlation metadata, redaction profiles for share-safe exports, and LangChain streaming metadata support.
+## 1.4.0
+
+Released **2026-06-12**.
+
+### Added
+
+- Added `docs/CI-ARTIFACTS.md` and `examples/recipes/github-actions-artifact/` for CI trace artifact workflows.
+- Added `agent-inspect timeline <runId>` — chronological local run view (`--json`, `--focus slow`).
+- Added `agent-inspect stats` — local aggregate stats (`--since`, `--correlation-id`, `--group-id`, `--json`).
+- Added `agent-inspect search` — deterministic local trace search (`--status`, `--kind`, `--name`, `--tool`, `--duration`, `--json`).
+- Added core helpers: `buildRunTimeline`, `buildTraceStats`, `searchTraces`.
+
+### Notes
+
+- CI artifact upload is configured in user CI (e.g. GitHub Actions `upload-artifact`) — AgentInspect does not upload.
+- Search is exact/contains matching only — no semantic search or index database.
+- Stats/search scan local files linearly — intended for developer-machine scale.
+- No Vitest/Jest reporter package in this release.
+- Manual trace writing remains `schemaVersion: "0.1"`.
+- Linked release aligns `@agent-inspect/tui` with `agent-inspect` and `@agent-inspect/langchain` (all **1.4.0**).
+
+## 1.3.0
 
-## 1.3.0 — Unreleased
+Released **2026-06-12**.
 
 ### Added
 

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.2.0**.
+Current npm release: **1.5.0** (`agent-inspect`, `@agent-inspect/langchain`, `@agent-inspect/tui` — all aligned).
 
 ```bash
 npm install agent-inspect
@@ -109,10 +111,29 @@ await maybeInspectRun("eval-case-42", async () => runAgent());
 AGENT_INSPECT=1 node eval-runner.mjs
 ```
 
+## What you can do today (v1.5.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`, `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"`.
+
+Nothing uploads traces by default. Review exports before sharing — see [safe trace sharing](docs/SAFE-TRACE-SHARING.md).
+
 ## What the trace shows
 
 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.
@@ -137,6 +158,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
@@ -150,6 +173,15 @@ More detail: [docs/LOGS.md](docs/LOGS.md) · [docs/LOG-TO-TREE-QUICKSTART.md](do
 | `tail` | Watch structured logs while the app runs |
 | `export` | Write Markdown / HTML / OpenInference-compatible JSON / 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).
 
@@ -164,31 +196,29 @@ Full flags and behavior: [docs/CLI.md](docs/CLI.md).
 
 ## Stable foundation (AgentInspect 1.x)
 
-**agent-inspect 1.x** (current: **1.2.0**) stabilizes the **local debugging foundation**:
+**agent-inspect 1.x** (current: **1.5.0**) is the **local-first trace workbench** for TypeScript AI agents:
 
-- Instrument a run with `inspectRun` and `step`
+- Instrument runs with `inspectRun` and `step`
 - Write **local JSONL traces** (`schemaVersion: "0.1"` — compatibility retained)
-- Inspect runs with **`list`** and **`view`**
-- Safely remove old trace files with **`clean`**
+- Inspect with **`list`**, **`view`**, **`clean`**, **`logs`**, **`tail`**, **`export`**, **`diff`**, **`timeline`**, **`stats`**, **`search`**
 
-**Stable APIs:** `inspectRun()`, `maybeInspectRun()`, `step()`, `step.llm()`, `step.tool()`, `observe()`.
+**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` (or `true` / `yes` / `on` / `enabled`) to toggle tracing in eval or CI jobs — see [docs/API.md](docs/API.md).
+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).
 
-**Stable CLI workflows:** `agent-inspect list`, `agent-inspect view`, `agent-inspect clean`.
+**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**.
 
-**Also included in 1.x** as local-first extensions:
+**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**.
 
-- Structured log inspection: **`logs`**
-- Live log tailing: **`tail`**
-- Local exports: **`export`** (Markdown, HTML, OpenInference-compatible JSON, OTLP JSON — files only)
-- Local run comparison: **`diff`**
-- Optional **`@agent-inspect/langchain`** callback adapter
-- Optional **`@agent-inspect/tui`** terminal viewer
-- **Fixtures** and **recipes** for deterministic checks and adoption patterns
-- **v1.2.0** — experimental persisted-event foundation (`PersistedInspectEvent`, converters, in-memory tree bridge) for future source-agnostic local inspection. Manual trace writing remains **`schemaVersion: "0.1"`**; v0.2 is **not written by default**; CLI behavior unchanged; no vendor upload.
+**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).
 
-**Honest boundaries:** programmatic log parsing, export, and diff APIs; LangChain and TUI programmatic surfaces; and OpenInference/OTLP JSON exports are **experimental or compatibility-oriented**. Nothing performs **vendor upload** by default.
+**Also in 1.x** (local-first extensions):
+
+- **v1.2.0** — experimental persisted-event foundation (`PersistedInspectEvent`, converters, in-memory tree bridge). Manual writing remains **`schemaVersion: "0.1"`**; v0.2 is **not written by default**.
+- Optional **`@agent-inspect/langchain`** and **`@agent-inspect/tui`**
+- **Fixtures** and **recipes** for deterministic adoption patterns
+
+**Honest boundaries:** log parsing, export, diff, LangChain/TUI programmatic APIs, and OpenInference/OTLP JSON exports are **experimental or compatibility-oriented**. Nothing performs **vendor upload** by default.
 
 ## Optional packages
 
@@ -252,6 +282,7 @@ 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 |
 
 **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).
 
@@ -272,25 +303,16 @@ For a detailed comparison, see [Compare with other tools](docs/COMPARE.md).
 
 ## Documentation
 
-- [Getting started](docs/GETTING-STARTED.md)
-- [Clean install smoke test](docs/INSTALL-SMOKE-TEST.md)
-- [API stability & experimental surfaces](docs/API.md)
-- [CLI reference](docs/CLI.md)
-- [Schema (`schemaVersion: "0.1"`)](docs/SCHEMA.md)
-- [Architecture (links to deeper design notes)](docs/ARCHITECTURE.md)
-- [Logs & tail](docs/LOGS.md)
-- [Log-to-tree quickstart](docs/LOG-TO-TREE-QUICKSTART.md)
-- [Logging playbook](docs/LOGGING-PLAYBOOK.md)
-- [Exports](docs/EXPORTS.md)
-- [Diff](docs/DIFF.md)
-- [Adapters](docs/ADAPTERS.md)
-- [Compare with other tools](docs/COMPARE.md)
-- [Security](SECURITY.md)
-- [Safe trace sharing checklist](docs/SAFE-TRACE-SHARING.md)
-- [Changelog](CHANGELOG.md) — **upcoming [1.3.0](CHANGELOG.md#130--unreleased)** on `main` (not yet on npm): correlation metadata, share-safe export profiles, LangChain streaming metadata
-- [Known issues](docs/KNOWN-ISSUES.md)
-- [Limitations](docs/LIMITATIONS.md)
-- [Screenshot checklist (planned assets)](docs/SCREENSHOTS.md)
+| Start here | Reference | Safety & boundaries |
+| ---------- | --------- | ------------------- |
+| [Getting started](docs/GETTING-STARTED.md) | [API](docs/API.md) | [Safe trace sharing](docs/SAFE-TRACE-SHARING.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) |
+| [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)
 
 ## Contributing
 

package/docs/ADAPTERS.md

@@ -1,27 +1,38 @@
-## Adapters
+# Adapters
 
-AgentInspect is framework-agnostic at its core, but can optionally integrate with frameworks via adapter packages.
+AgentInspect is **framework-agnostic** at its core. Optional adapter packages integrate specific frameworks without monkey-patching, vendor sinks, or network upload.
 
-- **LangChain.js adapter** (optional): `@agent-inspect/langchain`
-  - Documented as **experimental** in `docs/API.md`
-  - Requires `@langchain/core` as a peer dependency
-  - **In-memory by default** (`getEvents()` / `clear()`)
-  - **Optional JSONL persistence** (`persist: true`) maps callback lifecycle to schemaVersion `"0.1"` manual events (`run_started`, `step_started`, `step_completed`, `run_completed`) so `list` / `view` / `export` / `diff` work without a separate schema
-  - **Metadata-only capture by default**; `capture: "preview"` is opt-in with truncation
-  - **Optional streaming metadata** (`stream: true`) — chunk counts, timing, and bounded previews only; **no full token stream** captured by default
-  - **No monkey-patching**, **no vendor sinks**, **no network upload**
-- **Interactive TUI** (optional): `@agent-inspect/tui`
-  - Documented as **experimental** in `docs/API.md`
-  - Intended for CLI integration; programmatic TUI APIs may change
+## LangChain.js (`@agent-inspect/langchain`)
 
-### LangChain persistence model (Strategy A)
+**Status:** experimental — programmatic API may evolve independently of stable core tracing.
 
-When `persist: true`:
+### Install
 
-1. **Standalone callback session** — one AgentInspect run per `AgentInspectCallback` instance until the root LangChain run completes.
-2. **Inside `inspectRun`** — callback steps append to the active manual run (no extra `run_started` / `run_completed`).
-3. **Parent mapping** — LangChain `parentRunId` maps to AgentInspect `parentId` when the parent step was already persisted; unknown parents stay at run root (no invented hierarchy).
-4. **Step types** — `LLM` → `llm`, `TOOL` → `tool`, `DECISION` → `decision`, other kinds → `logic`.
+```bash
+npm install agent-inspect @agent-inspect/langchain @langchain/core
+```
+
+### Basic callback (in-memory)
+
+```ts
+import { AgentInspectCallback } from "@agent-inspect/langchain";
+
+const callback = new AgentInspectCallback({
+  runName: "support-agent",
+  capture: "metadata-only", // default
+});
+
+await agent.invoke(input, { callbacks: [callback] });
+
+const events = callback.getEvents();
+callback.clear();
+```
+
+- **No monkey-patching** — pass the callback explicitly to LangChain.
+- **Metadata-only by default** — does not capture full prompts/outputs unless you opt into `capture: "preview"`.
+- **No vendor sink** — events stay in memory unless you set `persist: true`.
+
+### Persist to local JSONL
 
 ```ts
 const callback = new AgentInspectCallback({
@@ -30,23 +41,38 @@ const callback = new AgentInspectCallback({
   persist: true,
   capture: "metadata-only",
 });
+
+await agent.invoke(input, { callbacks: [callback] });
 ```
 
 ```bash
 npx agent-inspect list --dir ./.agent-inspect
 npx agent-inspect view <run-id> --dir ./.agent-inspect
+npx agent-inspect export <run-id> --format markdown --redaction-profile share
 ```
 
-### LangChain streaming metadata (v1.3.0+)
+![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.
+2. **Inside `inspectRun`** — callback steps append to the active manual run (no extra `run_started` / `run_completed`).
+3. **Parent mapping** — LangChain `parentRunId` maps to AgentInspect `parentId` when the parent step was persisted; unknown parents stay at run root.
+4. **Step types** — `LLM` → `llm`, `TOOL` → `tool`, `DECISION` → `decision`, other kinds → `logic`.
+
+Written events use `schemaVersion: "0.1"` manual trace names.
+
+### Capture modes
 
-When `stream: true` on `AgentInspectCallback`:
+| `capture` | Behavior |
+| --------- | -------- |
+| `none` | Minimal metadata |
+| `metadata-only` | **Default** — model names, token usage, timing; no full text |
+| `preview` | Truncated previews via `maxPreviewChars` — review before sharing |
 
-- `handleLLMNewToken` updates **in-memory streaming stats** only (no per-token JSONL lines).
-- On LLM end/error, metadata such as `chunkCount`, `firstChunkAt`, `lastChunkAt`, `streamDurationMs`, and `streamedCharCount` attach to the LLM completion event.
-- **`capture: "metadata-only"`** (default) does **not** store token text.
-- **`capture: "preview"`** may include a **bounded** `streamPreview` via `maxStreamPreviewChars` (defaults to `maxPreviewChars`).
-- With **`persist: true`**, streaming metadata is written on the LLM `step_started` metadata at completion time (deferred write for streaming LLM steps).
-- Inspect persisted runs locally: `agent-inspect list`, `view`, `export --redaction-profile share`.
+### Streaming metadata (v1.3.0+)
 
 ```ts
 const callback = new AgentInspectCallback({
@@ -56,8 +82,68 @@ const callback = new AgentInspectCallback({
 });
 ```
 
-See also:
-- `docs/MIGRATION.md` (what changed from early versions)
-- `docs/API.md` (LangChain adapter options: `persist`, `capture`, `stream`, `traceDir`)
-- `docs/SAFE-TRACE-SHARING.md` (review exports before sharing)
+When `stream: true`:
+
+- `handleLLMNewToken` updates **in-memory stats only** — no per-token JSONL lines.
+- On LLM end/error: `chunkCount`, `firstChunkAt`, `lastChunkAt`, `streamDurationMs`, `streamedCharCount`.
+- **`capture: "metadata-only"`** does **not** store raw token text.
+- **`capture: "preview"`** may include bounded `streamPreview` via `maxStreamPreviewChars`.
+- With **`persist: true`**, streaming metadata is written on the LLM step at completion (deferred write for streaming LLM steps).
+
+Streaming metadata is for **local inspection and timing** — not replay or cassette playback.
+
+### Correlation inside `inspectRun`
+
+When the callback runs inside `inspectRun` / `maybeInspectRun`, correlation fields from `getCurrentCorrelationMetadata()` attach to LLM lifecycle events.
+
+### Options reference
+
+| Option | Default | Notes |
+| ------ | ------- | ----- |
+| `persist` | `false` | Write local JSONL |
+| `runName` | `"langchain-agent"` | Standalone persisted run name |
+| `traceDir` | from env / `.agent-inspect` | |
+| `capture` | `"metadata-only"` | |
+| `stream` | `false` | Streaming lifecycle metadata |
+| `maxStreamPreviewChars` | `maxPreviewChars` | Bounds preview when `capture: "preview"` |
+| `redact` | — | Custom `RedactionRule[]` before disk |
+
+Full API: [API.md](./API.md) §9.
+
+### Example
+
+[examples/08-langchain-adapter](../examples/08-langchain-adapter/README.md)
+
+---
+
+## TUI (`@agent-inspect/tui`)
+
+**Status:** experimental programmatic API; CLI integration is the intended usage.
+
+```bash
+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.
+
+---
+
+## Future adapters (not shipped)
+
+Direction only — see [ROADMAP.md](../ROADMAP.md):
+
+- **Vercel AI SDK** — optional callback-style adapter (metadata-first, no vendor sink)
+- **NestJS / logging bridges** — deeper recipes or helper patterns beyond [LOGGING-PLAYBOOK.md](./LOGGING-PLAYBOOK.md)
+
+No automatic universal instrumentation. Integrations remain explicit and opt-in.
+
+---
+
+## Related docs
 
+- [API.md](./API.md) — adapter options and stability policy
+- [SAFE-TRACE-SHARING.md](./SAFE-TRACE-SHARING.md) — review exports before sharing
+- [LIMITATIONS.md](./LIMITATIONS.md) — LangChain streaming and metadata boundaries

package/docs/API.md

@@ -9,6 +9,14 @@ 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.
 
+**v1.5.0 subpath exports:** Additive subpaths (`/logs`, `/exporters`, `/persisted`, `/diff`, `/advanced`) 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";
+```
+
 Notes:
 
 - The core guarantee of v1.x is **stable local debugging**: manual tracing + CLI inspection.
@@ -31,7 +39,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.
@@ -166,23 +174,33 @@ Related types: `PersistedInspectEvent`, `PersistedEventSourceType`, `PersistedEv
 - 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.
 
-## 12. Deprecated APIs
+## 12. Local observability helpers (v1.4.0)
+
+Read-only helpers for timeline, stats, and search over manual `TraceEvent` JSONL. Local files only.
+
+- **`buildRunTimeline`**, **`renderTimeline`** — chronological run view; types `RunTimeline`, `TimelineEntry`
+- **`buildTraceStats`**, **`renderTraceStats`** — directory aggregates; type `TraceStats`
+- **`searchTraces`**, **`parseDurationFilter`**, **`loadTraceMetadataList`** — deterministic search; types `TraceSearchResult`, `TraceSearchOptions`
+
+CLI wrappers: `agent-inspect timeline`, `stats`, `search` — see [CLI.md](./CLI.md).
+
+## 13. Deprecated APIs
 
-No deprecated APIs are declared as of 1.2.0.
+No deprecated APIs are declared as of 1.4.0.
 
-## 13. Removal / deprecation policy
+## 14. 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.
 
-## 14. Backward compatibility policy
+## 15. 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.
 
-## 15. Examples
+## 16. Examples
 
 ### Minimal manual trace
 

package/docs/CLI.md

@@ -26,6 +26,11 @@ Core commands:
 - `tail` — live-tail logs into updating local trees
 - `export` — export manual traces to Markdown/HTML/OpenInference/OTLP JSON (local only)
 - `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
 
@@ -162,7 +167,7 @@ Important: `tail` is a local developer tool, not a production monitor.
 
 ### 6.6 `export`
 
-Export a manual trace run to local formats. **No upload**.
+Export a manual trace run to local formats. **No upload.** Export redaction operates on a **copy** of the run tree — original JSONL files are not modified. Review every export before sharing, even with `--redaction-profile strict`.
 
 ```bash
 agent-inspect export <run-id> --format <markdown|html|openinference|otlp-json> [options]
@@ -251,6 +256,126 @@ Differences:
 
 More examples, including timing-only and structure-only diffs, are in `docs/DIFF.md`.
 
+### 6.8 `timeline`
+
+Chronological step list for one manual trace. Read-only; does not mutate JSONL files.
+
+```bash
+agent-inspect timeline <run-id> [options]
+```
+
+Options:
+
+- `--dir <path>`
+- `--json` — structured `RunTimeline` JSON
+- `--focus slow` — show only the slowest steps by duration (top N)
+
+![Timeline with slow-step focus](../assets/demos/timeline.gif)
+
+### 6.9 `stats`
+
+Local aggregate statistics over trace files in a directory. Read-only.
+
+```bash
+agent-inspect stats [options]
+```
+
+Options:
+
+- `--dir <path>`
+- `--since <duration>` — e.g. `7d`, `24h`
+- `--correlation-id <id>` — filter by `run_started.metadata.correlationId`
+- `--group-id <id>` — filter by `run_started.metadata.groupId`
+- `--json`
+
+![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.10 `search`
+
+Deterministic search over local traces (substring / exact filters). No semantic search.
+
+```bash
+agent-inspect search [options]
+```
+
+Options:
+
+- `--dir <path>`
+- `--since <duration>`
+- `--status <success|error|running|unknown>`
+- `--kind <kind>` / `--type <type>` — manual step type (`llm`, `tool`, `logic`, …)
+- `--name <query>` — substring on run or step name
+- `--tool <query>` — substring on tool step name or `metadata.toolName`
+- `--duration <expr>` — e.g. `>5s`, `>=500ms`
+- `--limit <number>` — default 50
+- `--json`
+
+Examples:
+
+```bash
+npx agent-inspect search --status error --dir ./.agent-inspect
+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.11 `what`
+
+Concise human-readable summary of one manual trace run. Read-only; uses local v0.1 JSONL (v0.2 dual-read lands in v1.5.0 Chunks 7–8). 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.12 `report`
+
+Generate a local inspection report combining **what happened**, **timeline**, and **execution tree** sections. Read-only over v0.1 JSONL. 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 tree section
+- `--no-errors` — omit error details from tree section
+- `--no-correlation` — omit correlation ids from what section
+- `--redaction-profile <local|share|strict>` — tree section redaction (default `local`)
+
+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.

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: