agent-inspect 1.3.0 → 1.4.0

package/CHANGELOG.md

@@ -1,12 +1,27 @@
 # Changelog
 
-## 1.3.0
+## 1.4.0
+
+### Added
 
-### Minor Changes
+- 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`.
 
-- 503d240: Correlation metadata, redaction profiles for share-safe exports, and LangChain streaming metadata support.
+### 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

@@ -20,7 +20,7 @@ agent-inspect gives those runs **structure**: an **execution tree** you can read
 
 ## Install
 
-Current npm release: **1.2.0**.
+Current npm release: **1.3.0** (`agent-inspect`, `@agent-inspect/langchain`; `@agent-inspect/tui` is **1.2.1** — patch-only alignment release).
 
 ```bash
 npm install agent-inspect
@@ -109,6 +109,21 @@ await maybeInspectRun("eval-case-42", async () => runAgent());
 AGENT_INSPECT=1 node eval-runner.mjs
 ```
 
+## What you can do today (v1.3.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`.
+- **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).
@@ -150,6 +165,9 @@ 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 |
 
 Full flags and behavior: [docs/CLI.md](docs/CLI.md).
 
@@ -164,31 +182,25 @@ 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.3.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`**
 
-**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.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 included in 1.x** as local-first extensions:
+**Also in 1.x** (local-first extensions):
 
-- 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.
+- **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:** 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.
+**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
 
@@ -272,25 +284,15 @@ 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) |
+| [Examples](examples/README.md) | [Adapters](docs/ADAPTERS.md) | [Compare with other tools](docs/COMPARE.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,34 @@ 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+)
+**Persistence model (Strategy A):**
 
-When `stream: true` on `AgentInspectCallback`:
+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
 
-- `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`.
+| `capture` | Behavior |
+| --------- | -------- |
+| `none` | Minimal metadata |
+| `metadata-only` | **Default** — model names, token usage, timing; no full text |
+| `preview` | Truncated previews via `maxPreviewChars` — review before sharing |
+
+### Streaming metadata (v1.3.0+)
 
 ```ts
 const callback = new AgentInspectCallback({
@@ -56,8 +78,66 @@ 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
+```
+
+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

@@ -166,23 +166,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)
 
-No deprecated APIs are declared as of 1.2.0.
+Read-only helpers for timeline, stats, and search over manual `TraceEvent` JSONL. Local files only.
 
-## 13. Removal / deprecation policy
+- **`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.4.0.
+
+## 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,9 @@ 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
 
 ## 2. Environment variables
 
@@ -162,7 +165,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 +254,64 @@ 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)
+
+### 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`
+
+### 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
+```
+
 ## 7. Optional TUI behavior
 
 `view --tui` delegates to `@agent-inspect/tui` and requires an interactive terminal. If the package is not installed, the CLI prints a short install hint.

package/docs/EXPORTS.md

@@ -1,26 +1,84 @@
-## Exports
+# Exports
 
-AgentInspect supports local-only exports from run trees and traces. Exports are intended for **compatibility and sharing**, but should be reviewed before sending to others.
+AgentInspect exports are **local-only**: they produce strings or files on disk. Nothing uploads to a vendor, collector, or hosted dashboard.
 
-- **CLI usage**: `docs/CLI.md` (`export`)
-- **Schema + compatibility guarantees**: `docs/SCHEMA.md`
-- **Safety / redaction notes**: `docs/CLI.md`, `SECURITY.md`, and `docs/SCHEMA.md` (redaction section)
+Use exports to share run summaries in PRs, postmortems, or internal threads — **after reviewing** the output. See [SAFE-TRACE-SHARING.md](./SAFE-TRACE-SHARING.md).
 
-## Share-safe exports (v1.3.0+)
+## CLI
 
-Use `--redaction-profile share` (PRs, issues, internal threads) or `strict` (external sharing) when generating an export copy:
+```bash
+agent-inspect export <run-id> --format <markdown|html|openinference|otlp-json> [options]
+```
+
+Full flags: [CLI.md](./CLI.md) §6.6.
+
+## Formats
+
+| Format | Purpose |
+| ------ | ------- |
+| `markdown` | Human-readable tree for PRs, issues, docs |
+| `html` | Standalone HTML snapshot for local viewing |
+| `openinference` | OpenInference-compatible JSON (compatibility-oriented) |
+| `otlp-json` | OTLP JSON shape (experimental; validate per backend) |
+
+All formats are **compatibility-oriented** for local inspection and handoff — not guaranteed to match every vendor schema version.
+
+## Common options
+
+| Flag | Notes |
+| ---- | ----- |
+| `--dir <path>` | Trace directory (default from `AGENT_INSPECT_TRACE_DIR` or `.agent-inspect`) |
+| `-o, --output <path>` | Write to file instead of stdout |
+| `--json` | JSON wrapper output (includes content when not writing to file) |
+| `--validate` | Validate exported payload shape before writing |
+| `--include-attributes` | Include bounded attributes — **review before sharing** |
+| `--no-metadata` | Omit summary/metadata sections |
+| `--no-errors` | Omit error sections |
+| `--redaction-profile <local\|share\|strict>` | Key-based redaction on the **export copy** (v1.3.0+) |
+
+## Redaction profiles (share-safe exports)
+
+Profiles apply to the **exported copy** only. Original JSONL traces on disk are **not mutated**.
+
+| Profile | Typical use |
+| ------- | ------------- |
+| `local` | Default — same key-based defaults as trace writing |
+| `share` | PRs, GitHub issues, internal Slack/email threads |
+| `strict` | External or public sharing — also redacts prompt/output/message-like keys |
 
 ```bash
-agent-inspect export <run-id> --format markdown --redaction-profile share
+npx agent-inspect export <run-id> --format markdown --redaction-profile share
+npx agent-inspect export <run-id> --format html --redaction-profile strict
+npx agent-inspect export <run-id> --format openinference --redaction-profile share --validate
 ```
 
-- Profiles are **key-based** redaction presets — not compliance-grade PII detection.
-- Export redaction operates on a **copy** of the run tree; original JSONL traces on disk are **not mutated**.
-- **Review** every export before posting — especially when `--include-attributes` is set.
+Redaction profiles are **key-based safeguards**, not compliance-grade PII detection. Always review exports manually.
+
+## Programmatic API
+
+Experimental helpers (local-only):
+
+- `exportRunTree`, `redactRunTreeForExport`
+- `exportMarkdown`, `exportHtml`, `exportOpenInference`, `exportOtlpJson`
+- `validateExport`, `validateExportContent`
+
+See [API.md](./API.md) §7.
+
+## What not to share
+
+Even with `--redaction-profile strict`, review exports for:
+
+- API keys, tokens, cookies, session IDs
+- Customer IDs, emails, phone numbers, internal hostnames
+- Full prompts, completions, tool I/O (especially with `--include-attributes`)
+- File paths that expose usernames or internal project names
 
-See [SAFE-TRACE-SHARING.md](./SAFE-TRACE-SHARING.md).
+Prefer the smallest useful artifact — a summary or synthetic reproduction beats a full production trace.
 
-Notes:
-- Export formats (Markdown/HTML/OpenInference/OTLP JSON) are documented as **experimental / compatibility-oriented** in `docs/API.md`.
-- AgentInspect does **not** upload anywhere; exports write local strings/files only.
+## Related docs
 
+- [CLI.md](./CLI.md) — `export` command reference
+- [SCHEMA.md](./SCHEMA.md) — trace event model and redaction notes
+- [SAFE-TRACE-SHARING.md](./SAFE-TRACE-SHARING.md) — checklist before posting
+- [API.md](./API.md) — `ExportOptions`, experimental export APIs
+- [LIMITATIONS.md](./LIMITATIONS.md) — compatibility and boundary notes

package/docs/GETTING-STARTED.md

@@ -60,6 +60,24 @@ AGENT_INSPECT=1 node eval-runner.mjs
 
 Enable tokens: `1`, `true`, `yes`, `on`, `enabled` (case-insensitive). Explicit `enabled: true | false` in options overrides the env var.
 
+### Correlation metadata (v1.3.0+)
+
+Attach optional correlation fields to `run_started` metadata — useful for eval cases, CI job IDs, and future stats views. They are **metadata only**, not run IDs. Review before sharing exports.
+
+```ts
+await inspectRun(
+  "support-agent",
+  async () => runAgent(),
+  {
+    correlationId: "eval-suite-2026-06",
+    requestId: "req-abc123",
+    groupId: "ci-job-42",
+  }
+);
+```
+
+Inside a traced run, adapters can read active fields via `getCurrentCorrelationMetadata()`.
+
 ### Install compatibility
 
 If `import` or `require` fails after install, see [KNOWN-ISSUES.md — Common install/runtime compatibility checks](./KNOWN-ISSUES.md#common-installruntime-compatibility-checks).
@@ -109,7 +127,14 @@ agent-inspect export minimal-success --dir fixtures/traces --format markdown
 agent-inspect export minimal-success --dir fixtures/traces --format openinference --validate
 ```
 
-Exports are **local-only** and do not upload anywhere.
+Share-safe copy for a PR or issue (v1.3.0+):
+
+```bash
+agent-inspect export minimal-success --dir fixtures/traces \
+  --format markdown --redaction-profile share
+```
+
+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
 
@@ -151,6 +176,9 @@ agent-inspect view <runId> --tui
 - [docs/API.md](./API.md)
 - [docs/CLI.md](./CLI.md)
 - [docs/SCHEMA.md](./SCHEMA.md)
+- [docs/EXPORTS.md](./EXPORTS.md)
+- [docs/SAFE-TRACE-SHARING.md](./SAFE-TRACE-SHARING.md)
+- [docs/ADAPTERS.md](./ADAPTERS.md)
 - [docs/LOGGING-PLAYBOOK.md](./LOGGING-PLAYBOOK.md)
 - [docs/COMPARE.md](./COMPARE.md)
 - [docs/LOG-TO-TREE-QUICKSTART.md](./LOG-TO-TREE-QUICKSTART.md)

package/docs/KNOWN-ISSUES.md

@@ -16,6 +16,12 @@ AgentInspect is **local-first** and **CLI-first**. These behaviors are intention
 
 - **Vendor sinks** (hosted dashboards, Langfuse/Braintrust/New Relic/Datadog native uploads, OTLP gRPC streaming, etc.) are **not implemented** in the core packages described here.
 - **LangChain adapter** captures **metadata-oriented** signals by default; it does not replace full framework observability.
+- **LangChain `stream: true`** records chunk counts and timing only — not a full token replay. Per-token JSONL events are not emitted.
+- **Correlation metadata** (`correlationId`, `requestId`, `decisionId`, `groupId`) is written on `run_started` but **CLI list/view does not filter by correlation fields** yet.
+
+## Structured log parsing
+
+- Ingest requires **line-delimited JSON** or a **recoverable JSON payload** in the log line (log4js-style is best-effort). Arbitrary printf-style text without JSON is not supported.
 
 ## UI / replay
 

package/docs/LIMITATIONS.md

@@ -9,9 +9,9 @@ This document states what AgentInspect **does not** provide today. It complement
 - **No vendor upload pipeline**: no built-in Langfuse/Braintrust/New Relic/Datadog direct exporters as live sinks.
 - **No automatic universal instrumentation** of every framework: integration is explicit (manual traces, log ingest, optional adapters).
 
-## Correlation metadata (v1.3.0 chunk 1)
+## Correlation metadata (v1.3.0)
 
-- **No CLI filter/query** by `correlationId`, `requestId`, `decisionId`, or `groupId` yet — fields are written to `run_started.metadata` and available via persisted converters; list/view/export filtering is future work.
+- **`list` / `view` / `export`** do not filter by correlation fields yet — `stats --correlation-id` / `--group-id` and `search` provide targeted read paths; full CLI filtering remains incremental.
 
 ## Persisted event model (v1.2.0 foundation)
 
@@ -48,6 +48,12 @@ This document states what AgentInspect **does not** provide today. It complement
 
 - **No cost engine**: no pricing tables, invoice-grade usage, or provider billing reconciliation.
 
+## Local observability commands (v1.4.0)
+
+- **`timeline`**, **`stats`**, and **`search`** scan local JSONL files — no database index; large directories may be slow.
+- **`search`** is deterministic exact/contains matching only — no semantic or fuzzy search.
+- **`stats`** is local file aggregation — not production fleet analytics.
+
 ## Scale
 
 - Designed for **developer machines** and **inner-loop debugging**, not petabyte log warehouses.