agent-inspect 1.4.0 → 1.5.0

package/CHANGELOG.md

@@ -1,7 +1,35 @@
 # Changelog
 
+## 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.5.0** (`agent-inspect`, `@agent-inspect/langchain`, `@agent-inspect/tui` — all aligned).
 
 ```bash
 npm install agent-inspect
@@ -109,13 +111,13 @@ 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.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`.
+- **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).
@@ -128,6 +130,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 +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
@@ -168,6 +176,12 @@ More detail: [docs/LOGS.md](docs/LOGS.md) · [docs/LOG-TO-TREE-QUICKSTART.md](do
 | `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 +196,20 @@ 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.5.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.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**.
+
+**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 +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).
 
@@ -290,7 +309,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,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.

package/docs/CLI.md

@@ -29,6 +29,8 @@ Core commands:
 - `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
 
@@ -268,6 +270,8 @@ Options:
 - `--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.
@@ -284,6 +288,10 @@ Options:
 - `--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.
@@ -312,6 +320,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.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:

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

package/docs/LIMITATIONS.md

@@ -17,7 +17,7 @@ This document states what AgentInspect **does not** provide today. It complement
 
 - **v0.2 is not the default persisted trace file format.** `inspectRun()` / `step()` still write `schemaVersion: "0.1"` JSONL.
 - **CLI commands** (`list`, `view`, `export`, `diff`, `logs`, `tail`) still primarily operate on current v0.1 trace and log paths.
-- **v0.2 read/write integration** (dual-format storage, CLI consumption) is future work — v1.2.0 ships in-memory converters and canonical fixtures only.
+- **v0.2 read integration** — inspection CLI reads v0.2 JSONL via dual-format normalization (v1.5.0). Default **write** path remains v0.1; `list` metadata for v0.2-only files may be limited.
 
 ## LangChain streaming (v1.3.0)
 
@@ -54,6 +54,8 @@ This document states what AgentInspect **does not** provide today. It complement
 - **`search`** is deterministic exact/contains matching only — no semantic or fuzzy search.
 - **`stats`** is local file aggregation — not production fleet analytics.
 
+Visual demos: [SCREENSHOTS.md](./SCREENSHOTS.md) · [CLI.md](./CLI.md)
+
 ## Scale
 
 - Designed for **developer machines** and **inner-loop debugging**, not petabyte log warehouses.

package/docs/LOGS.md

@@ -7,8 +7,30 @@ AgentInspect can parse **existing logs** (line-delimited JSON, and best-effort l
 - **Production-shaped playbook**: `docs/LOGGING-PLAYBOOK.md` (pino, log4js, NestJS recipes)
 - **Field mapping and redaction**: `docs/API.md` (log ingest APIs) and `docs/SCHEMA.md`
 - **Safety constraints**: JSON logs first-class; log4js best-effort; no `eval`; no JavaScript object-literal parsing as a log interchange format (see `SECURITY.md`)
+- **Visual demos**: [SCREENSHOTS.md](./SCREENSHOTS.md#use-existing-logs)
 
 Notes:
 - Log parsing APIs are documented as **experimental** in `docs/API.md`.
 - Log-derived events include **confidence labels**; AgentInspect is conservative about inferring parent/child structure.
 
+### JSON logs → tree (visual pending)
+
+Animated demo is **pending re-record** — a staging capture showed tool/LLM summary counts that did not match displayed events. Use the canonical command below; see [assets/demos/RECORDING.md](./assets/demos/RECORDING.md).
+
+```bash
+agent-inspect logs fixtures/logs/minimal-success.json.log \
+  --format json \
+  --run-id-key runId \
+  --event-key event \
+  --timestamp-key timestamp
+```
+
+Run: [examples/06-log-to-tree](../examples/06-log-to-tree/README.md)
+
+### Live tail (visual pending)
+
+`agent-inspect tail` updates a local tree as new log lines arrive. Recording guide: [RECORDING.md](./assets/demos/RECORDING.md).
+
+### log4js (best-effort)
+
+See [examples/recipes/log4js-json-layout](../examples/recipes/log4js-json-layout/README.md). Visual pending re-record.

package/docs/SCHEMA.md

@@ -129,7 +129,7 @@ Unknown status must **not** be treated as success.
 ## 6. Metadata policy
 
 - Runs may include `metadata` on `run_started`.
-- **Correlation metadata (v1.3.0+):** optional `correlationId`, `requestId`, `decisionId`, and `groupId` on `run_started.metadata` when passed via `inspectRun` / `maybeInspectRun` options. Event names remain unchanged (`run_started`, `step_started`, `step_completed`, `run_completed`). CLI list/view does not filter by correlation fields yet.
+- **Correlation metadata (v1.3.0+):** optional `correlationId`, `requestId`, `decisionId`, and `groupId` on `run_started.metadata` when passed via `inspectRun` / `maybeInspectRun` options. Event names remain unchanged (`run_started`, `step_started`, `step_completed`, `run_completed`). `stats --correlation-id` and `--group-id` filter by these fields; `list` / `view` do not filter by correlation yet.
 - Steps may include `metadata` on `step_started`.
 - Manual traces intentionally avoid full prompt/output capture by default.
 - **Redaction (default on):** before disk, `inspectRun` / `step` redact sensitive keys using the shared `Redactor` defaults (`authorization`, `cookie`, `token`, `apiKey`, `password`, `secret`, `email`). Opt out with `redact: false`.
@@ -142,6 +142,8 @@ Unknown status must **not** be treated as success.
 - Readers should ignore unknown fields where safe.
 - Breaking schema changes require a major version.
 
+**v1.5 vocabulary (kinds, token metadata, streaming attributes):** [TRACE-VOCABULARY-V1.5.md](./proposals/TRACE-VOCABULARY-V1.5.md)
+
 ## 8. Malformed lines
 
 Manual trace reading:

package/docs/SCREENSHOTS.md

@@ -1,14 +1,195 @@
-## Screenshots / GIFs (planned)
+# Visual demos
 
-This repo does not currently include screenshots or recorded GIFs in the npm package.
+Curated terminal recordings for AgentInspect **1.4.0**. They show what the local trace workbench captures and how to inspect it — without a hosted dashboard or vendor upload.
 
-Recommended captures to add (when convenient):
+**Synthetic output only:** demos use committed [fixtures](../fixtures/README.md), [examples](../examples/README.md), and recipes. No external LLM calls or API keys.
 
-- [ ] Basic trace tree (`inspectRun` + `step`)
-- [ ] Failed tool call / failed step rendering
-- [ ] `agent-inspect logs` output (JSON logs)
-- [ ] `agent-inspect diff` output
-- [ ] Optional TUI (`agent-inspect view <run-id> --tui`)
+**npm note:** GIFs live in `docs/assets/demos/` for GitHub documentation. They are **not** shipped in the `agent-inspect` npm tarball.
 
-<!-- Add screenshots after running `examples/00-quickstart-demo` locally. -->
+**Re-record guide:** [assets/demos/RECORDING.md](assets/demos/RECORDING.md)  
+**Maintainer audit:** [implementation/VISUAL-DEMO-AUDIT.md](implementation/VISUAL-DEMO-AUDIT.md)
 
+---
+
+## Start tracing
+
+Manual `inspectRun` / `step` traces written as local JSONL.
+
+### Quickstart (install → trace → view)
+
+![Quickstart: install, run a traced script, list and view the run](assets/demos/quickstart.gif)
+
+Run: [examples/00-quickstart-demo](../examples/00-quickstart-demo/README.md)  
+Also: [GETTING-STARTED.md](GETTING-STARTED.md)
+
+### Nested execution tree
+
+![Nested steps rendered as an execution tree in the terminal](assets/demos/execution-tree.gif)
+
+Run: [examples/02-nested-steps](../examples/02-nested-steps/README.md)  
+Command: `agent-inspect view <run-id> --dir <trace-dir>`
+
+### Parallel sibling steps
+
+![Parallel tool steps under one parent in the execution tree](assets/demos/parallel-execution.gif)
+
+Run: [examples/03-parallel-steps](../examples/03-parallel-steps/README.md)
+
+### Error handling
+
+![Failed step recorded on step_completed with status error](assets/demos/error-handling.gif)
+
+Run: [examples/04-error-handling](../examples/04-error-handling/README.md)
+
+### `observe()` wrapper
+
+![observe() wrapper tracing an agent-like object](assets/demos/observe-wrapper.gif)
+
+Run: [examples/05-observe-wrapper](../examples/05-observe-wrapper/README.md) · API: [API.md](API.md)
+
+### Env-gated tracing (`maybeInspectRun`)
+
+![AGENT_INSPECT=1 toggles tracing; unset leaves no trace files](assets/demos/env-gated-tracing.gif)
+
+Docs: [GETTING-STARTED.md](GETTING-STARTED.md) · [API.md](API.md) (`maybeInspectRun`)
+
+---
+
+## Use existing logs
+
+Turn structured logs you already emit into a **local** grouped timeline or tree.
+
+### JSON logs → tree
+
+**Status:** animated demo pending re-record (staging asset had summary-count mismatch).  
+**Command:**
+
+```bash
+agent-inspect logs ./your.json.log \
+  --format json \
+  --run-id-key runId \
+  --event-key event \
+  --timestamp-key timestamp
+```
+
+Run: [examples/06-log-to-tree](../examples/06-log-to-tree/README.md) · [LOGS.md](LOGS.md) · [LOG-TO-TREE-QUICKSTART.md](LOG-TO-TREE-QUICKSTART.md)
+
+### Live tail
+
+**Status:** animated demo pending re-record.  
+**Command:** `agent-inspect tail <log-file> [mapping flags]` — see [LOGS.md](LOGS.md).
+
+### log4js (best-effort)
+
+**Status:** pending re-record. Documented in [LOGS.md](LOGS.md); recipe: [log4js-json-layout](../examples/recipes/log4js-json-layout/README.md).
+
+---
+
+## Inspect and compare
+
+Read-only CLI over local JSONL traces.
+
+### Chronological timeline (`--focus slow`)
+
+![Timeline with slow-step focus highlighting longest steps](assets/demos/timeline.gif)
+
+```bash
+agent-inspect timeline <run-id> --dir fixtures/traces --focus slow
+```
+
+Docs: [CLI.md](CLI.md) § timeline
+
+### Local stats
+
+![Aggregate stats over a trace directory](assets/demos/stats.gif)
+
+```bash
+agent-inspect stats --dir fixtures/traces
+```
+
+Filter by correlation: `agent-inspect stats --correlation-id <id>` or `--group-id <id>`.  
+Docs: [CLI.md](CLI.md) § stats
+
+### Deterministic search
+
+![Search traces by status error](assets/demos/search.gif)
+
+```bash
+agent-inspect search --dir fixtures/traces --status error --limit 5
+```
+
+Docs: [CLI.md](CLI.md) § search
+
+### Diff two runs
+
+![Diff comparing success and error runs](assets/demos/diff-runs.gif)
+
+```bash
+agent-inspect diff minimal-success minimal-error --dir fixtures/traces
+```
+
+Docs: [DIFF.md](DIFF.md)
+
+### Markdown export
+
+![Export a run to Markdown locally](assets/demos/markdown-export.gif)
+
+```bash
+agent-inspect export minimal-success --dir fixtures/traces --format markdown
+```
+
+Docs: [EXPORTS.md](EXPORTS.md)
+
+### HTML / OpenInference / OTLP
+
+- **HTML:** rendered-report visual pending re-record; export command in [EXPORTS.md](EXPORTS.md).
+- **OpenInference / OTLP JSON:** compatibility-oriented local formats — see prose and `--validate` in [EXPORTS.md](EXPORTS.md), not dedicated GIFs.
+
+---
+
+## Integrations and optional UI
+
+### LangChain persistence
+
+![LangChain callback with persist true writing inspectable JSONL](assets/demos/langchain-persistence.gif)
+
+Run: [examples/08-langchain-adapter](../examples/08-langchain-adapter/README.md) · [ADAPTERS.md](ADAPTERS.md)
+
+Streaming metadata (`stream: true`) demo pending re-record until `chunkCount` / `streamDurationMs` are non-null.
+
+### Optional TUI (`@agent-inspect/tui`)
+
+![Optional Ink TUI viewer for a local trace](assets/demos/tui-viewer.gif)
+
+Requires optional package: `pnpm add @agent-inspect/tui`  
+Command: `agent-inspect view <run-id> --tui`  
+Docs: [ADAPTERS.md](ADAPTERS.md)
+
+---
+
+## Safety and sharing
+
+### Default metadata redaction
+
+![Sensitive metadata keys redacted before disk](assets/demos/redaction.gif)
+
+Profiles (`local` / `share` / `strict`) and export redaction: [SAFE-TRACE-SHARING.md](SAFE-TRACE-SHARING.md)
+
+### Event size bounds
+
+Described in [LIMITATIONS.md](LIMITATIONS.md) — no GIF (static explanation preferred).
+
+### Correlation metadata
+
+Described in [API.md](API.md) — optional `correlationId`, `requestId`, `decisionId`, `groupId` on `run_started`.
+
+---
+
+## Planned checklist (completed items)
+
+- [x] Basic trace tree (`inspectRun` + `step`)
+- [x] Failed step rendering
+- [x] `agent-inspect logs` output (JSON) — **re-record pending**
+- [x] `agent-inspect diff` output
+- [x] Optional TUI (`view --tui`)
+- [x] `timeline`, `stats`, `search` (v1.4.0)