agent-inspect 1.1.0 → 1.3.0

package/CHANGELOG.md

@@ -1,12 +1,54 @@
 # Changelog
 
-## 1.1.0
+## 1.3.0
 
 ### Minor Changes
 
-- 21ecc6f: v1.1.0: env-gated tracing, trace safety (redaction + size bounds), LangChain JSONL persistence, logging recipes, CJS/ESM type export compatibility, community docs.
+- 503d240: Correlation metadata, redaction profiles for share-safe exports, and LangChain streaming metadata support.
+
+## 1.3.0 — Unreleased
+
+### Added
+
+- Added correlation metadata on `inspectRun` / `maybeInspectRun` (`correlationId`, `requestId`, `decisionId`, `groupId`) and `getCurrentCorrelationMetadata()`.
+- Added redaction profiles (`local`, `share`, `strict`) for trace safety and share-safe exports.
+- Added `redactionProfile` on `InspectRunOptions` and `ExportOptions`.
+- Added `--redaction-profile` to `agent-inspect export`.
+- Added LangChain streaming metadata support (`stream: true`) for token chunk counts and duration.
+- Added bounded preview behavior for preview capture mode (`maxStreamPreviewChars`).
+
+### Notes
+
+- LangChain `capture: "metadata-only"` remains default; full stream text is not captured by default.
+- LangChain streaming does not emit per-token JSONL events.
+- Redaction profiles are key-based safeguards, not compliance-grade PII detection.
+- Export redaction does not upload anywhere and does not mutate original traces.
+- No vendor upload, hosted dashboard, or OTLP HTTP sink was added.
+- Manual trace writing remains `schemaVersion: "0.1"`; v0.2 is not written by default.
+
+## 1.2.0
+
+Released **2026-06-11**. Changeset `5a7f785`.
+
+### Added
+
+- Added experimental `PersistedInspectEvent` model (`schemaVersion: "0.2"`) as a source-agnostic event foundation.
+- Added validator for persisted events (`isPersistedInspectEvent`).
+- Added converters from legacy `schemaVersion: "0.1"` manual trace events to persisted events.
+- Added converters between `InspectEvent` and `PersistedInspectEvent`.
+- Added in-memory helpers to build run trees from persisted events (`persistedInspectEventsToRunTrees`, `traceEventsToPersistedRunTrees`).
+- Added canonical v0.2 fixture samples under `fixtures/traces-v0.2/`.
+
+### Notes
+
+- Existing manual trace writing remains `schemaVersion: "0.1"`.
+- v0.2 is not written by default in this release.
+- CLI read/write behavior is unchanged.
+- No vendor upload, hosted dashboard, OTLP HTTP sink, replay engine, or cost engine was added.
+
+## 1.1.0
 
-## 1.1.0 — Unreleased
+Changeset `21ecc6f`: env-gated tracing, trace safety (redaction + size bounds), LangChain JSONL persistence, logging recipes, CJS/ESM type export compatibility, community docs.
 
 ### Added
 
@@ -34,7 +76,7 @@
 ### Documentation
 
 - Added/updated logging playbook for structured JSON logs ([docs/LOGGING-PLAYBOOK.md](docs/LOGGING-PLAYBOOK.md)).
-- Updated public roadmap to separate completed v1.1-prep work from Now/Next/Future.
+- Updated public roadmap after the 1.1.0 release (Released recently / Now / Next / Future).
 - Updated contributor/community docs for package boundaries and optional packages.
 - Added clearer community onboarding and issue-draft guidance.
 

package/README.md

@@ -4,7 +4,7 @@
 
 agent-inspect helps you understand what happened inside an AI agent run — **locally**. It turns manual steps, tool calls, LLM calls, structured logs, failures, durations, and run metadata into **readable execution trees** you can inspect from the terminal.
 
-It is built for TypeScript/Node.js developers and teams shipping real agentic products — not just toy demos. Use it **before** a hosted observability platform, **alongside** one, or as the **local debugging layer** underneath enterprise observability.
+It is built for TypeScript/Node.js developers and teams shipping real agentic products — not just toy demos. Use it for **local TypeScript agent debugging**, **eval iteration**, and **CI trace artifacts**. It **complements** production observability platforms; it does **not** replace them.
 
 The tool starts with **manual traces** and **existing structured logs**, and extends into **optional framework callbacks** and **standards-aligned local export** — without turning the core into a SaaS or a vendor pipeline.
 
@@ -20,6 +20,8 @@ agent-inspect gives those runs **structure**: an **execution tree** you can read
 
 ## Install
 
+Current npm release: **1.2.0**.
+
 ```bash
 npm install agent-inspect
 ```
@@ -34,6 +36,8 @@ Verify the CLI is available:
 npx agent-inspect --help
 ```
 
+For a clean npm/pnpm install checklist with ESM, CJS, and CLI checks, see [Clean install smoke test](docs/INSTALL-SMOKE-TEST.md).
+
 ## 60-second quickstart
 
 Create `demo.mjs`:
@@ -153,14 +157,14 @@ Full flags and behavior: [docs/CLI.md](docs/CLI.md).
 
 - Debug a **failed tool call** or thrown error in a support or ops agent.
 - See **which step dominated latency** in a multi-step planner or RAG pipeline.
-- **Diff two runs** after a prompt, model, or routing change.
+- **Diff two runs** after a prompt, model, or routing change (see [diff examples](docs/DIFF.md)).
 - Point **`logs`** / **`tail`** at existing job or service logs to get a **local execution view** without shipping data upstream.
-- **Export** a run to Markdown for a PR, postmortem, or internal thread — then review before sharing.
+- **Export** a run to Markdown for a PR, postmortem, or internal thread — use `--redaction-profile share` for share-safe copies, then review before sharing.
 - Keep traces **on disk** while still using enterprise observability elsewhere.
 
-## What v1.0 stabilizes
+## Stable foundation (AgentInspect 1.x)
 
-**agent-inspect 1.0** stabilizes the **local debugging foundation**:
+**agent-inspect 1.x** (current: **1.2.0**) stabilizes the **local debugging foundation**:
 
 - Instrument a run with `inspectRun` and `step`
 - Write **local JSONL traces** (`schemaVersion: "0.1"` — compatibility retained)
@@ -173,7 +177,7 @@ Pass `enabled: false` to `inspectRun` for a no-trace passthrough. Use `maybeInsp
 
 **Stable CLI workflows:** `agent-inspect list`, `agent-inspect view`, `agent-inspect clean`.
 
-**Also included in 1.0** as local-first extensions:
+**Also included in 1.x** as local-first extensions:
 
 - Structured log inspection: **`logs`**
 - Live log tailing: **`tail`**
@@ -182,6 +186,7 @@ Pass `enabled: false` to `inspectRun` for a no-trace passthrough. Use `maybeInsp
 - 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.
 
 **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.
 
@@ -189,7 +194,7 @@ Pass `enabled: false` to `inspectRun` for a no-trace passthrough. Use `maybeInsp
 
 ### LangChain callback adapter (`@agent-inspect/langchain`)
 
-Optional package: official **LangChain.js callbacks** (`BaseCallbackHandler`), **metadata-oriented by default**, **no monkey-patching**, **no vendor sink**. The LangChain adapter is available in 1.0, but its programmatic API remains experimental and may evolve independently of the stable core tracing API.
+Optional package: official **LangChain.js callbacks** (`BaseCallbackHandler`), **metadata-oriented by default**, **no monkey-patching**, **no vendor sink**. Optional **`stream: true`** records chunk counts and stream duration **without storing full token text by default**. The LangChain adapter ships with 1.x; its programmatic API remains experimental and may evolve independently of the stable core tracing API.
 
 ```bash
 pnpm add agent-inspect @agent-inspect/langchain @langchain/core
@@ -257,7 +262,7 @@ The TUI is available as a separate optional package; its programmatic API is exp
 - **Manual metadata** is user-controlled. By default, common sensitive keys are **redacted before disk**; pass `redact: false` to opt out. Long metadata is truncated and events are capped at 64 KiB per JSONL line. Review traces and exports before sharing.
 - **Review exports** before sharing (especially with richer attribute flags).
 
-See [SECURITY.md](SECURITY.md).
+See [SECURITY.md](SECURITY.md) and the [safe trace sharing checklist](docs/SAFE-TRACE-SHARING.md).
 
 ## agent-inspect comparison
 
@@ -268,6 +273,7 @@ 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)
@@ -280,11 +286,23 @@ For a detailed comparison, see [Compare with other tools](docs/COMPARE.md).
 - [Adapters](docs/ADAPTERS.md)
 - [Compare with other tools](docs/COMPARE.md)
 - [Security](SECURITY.md)
-- [Changelog](CHANGELOG.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)
 
+## Contributing
+
+AgentInspect welcomes docs, fixtures, examples, and carefully scoped CLI improvements.
+
+- **Good first issues:** [GOOD-FIRST-ISSUES.md](GOOD-FIRST-ISSUES.md) — live batches [#7–#14](https://github.com/rajudandigam/agent-inspect/issues?q=is%3Aissue+is%3Aopen) and [#18–#30](https://github.com/rajudandigam/agent-inspect/issues/18) (comment on an issue before opening a PR)
+- **Discussions:** [github.com/rajudandigam/agent-inspect/discussions](https://github.com/rajudandigam/agent-inspect/discussions) — feedback, stack survey, integration ideas
+- **Roadmap:** [ROADMAP.md](ROADMAP.md) — Now / Next / Future direction (non-committal)
+- **Contributing guide:** [CONTRIBUTING.md](CONTRIBUTING.md) — validation commands, PR expectations, scope boundaries
+
+**Security:** Traces and logs may contain secrets. **Redact before sharing** in issues, Discussions, PRs, or exports. See [SECURITY.md](SECURITY.md) and the [safe trace sharing checklist](docs/SAFE-TRACE-SHARING.md).
+
 ## Development
 
 From a clone of this repo:

package/SECURITY.md

@@ -70,7 +70,7 @@ Important limitations:
 - Always **review exported files** before sharing them externally.
 - Avoid committing trace directories (`.agent-inspect-runs/`) to source control.
 
-For schema-level redaction notes, see `docs/SCHEMA.md` (redaction section) and `docs/API.md`.
+For a practical pre-share workflow, see `docs/SAFE-TRACE-SHARING.md`. For schema-level redaction notes, see `docs/SCHEMA.md` (redaction section) and `docs/API.md`.
 
 ## Dependency and security review process
 

package/docs/ADAPTERS.md

@@ -8,6 +8,7 @@ AgentInspect is framework-agnostic at its core, but can optionally integrate wit
   - **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`
@@ -36,7 +37,27 @@ npx agent-inspect list --dir ./.agent-inspect
 npx agent-inspect view <run-id> --dir ./.agent-inspect
 ```
 
+### LangChain streaming metadata (v1.3.0+)
+
+When `stream: true` on `AgentInspectCallback`:
+
+- `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`.
+
+```ts
+const callback = new AgentInspectCallback({
+  stream: true,
+  capture: "metadata-only",
+  persist: true,
+});
+```
+
 See also:
 - `docs/MIGRATION.md` (what changed from early versions)
-- `docs/API.md` (LangChain adapter options: `persist`, `capture`, `traceDir`)
+- `docs/API.md` (LangChain adapter options: `persist`, `capture`, `stream`, `traceDir`)
+- `docs/SAFE-TRACE-SHARING.md` (review exports before sharing)
 

package/docs/API.md

@@ -1,4 +1,4 @@
-# API (AgentInspect 1.0)
+# API (AgentInspect 1.x)
 
 This document describes the **public TypeScript API surface** of AgentInspect and classifies each area as **stable** or **experimental**.
 
@@ -11,9 +11,9 @@ AgentInspect is a **local-first execution-tree debugger**. It is not a SaaS, not
 
 Notes:
 
-- The core guarantee of v1.0 is **stable local debugging**: manual tracing + CLI inspection.
+- The core guarantee of v1.x is **stable local debugging**: manual tracing + CLI inspection.
 - Export formats (OpenInference / OTLP JSON) are **local-only** and **compatibility-oriented**. They do **not** upload anywhere.
-- There are **zero production sinks** in v1.0; sink/uploader APIs are not stable.
+- There are **zero production sinks** in v1.x; sink/uploader APIs are not stable.
 
 ## 2. Stable core APIs (manual tracing)
 
@@ -26,16 +26,21 @@ import { inspectRun, maybeInspectRun, step, observe } from "agent-inspect";
 ```
 
 - **`inspectRun(name, fn, options?)`**: wraps a workflow in a local JSONL trace (`run_started` / `run_completed`), prints terminal progress, and swallows instrumentation failures (user errors are re-thrown). **Traces by default** when `enabled` is omitted or `true`. Pass **`enabled: false`** to run `fn` with no trace file, no execution context, and no terminal output.
-  - **`redact`**: default `true` — redacts sensitive metadata keys before disk (`authorization`, `cookie`, `token`, `apiKey`, `password`, `secret`, `email`). Pass `false` to persist metadata as-is. Pass `{ rules?: RedactionRule[] }` for custom rules (defaults still apply).
+  - **`redact`**: default `true` — redacts sensitive metadata keys before disk (`authorization`, `cookie`, `token`, `apiKey`, `password`, `secret`, `email`). Pass `false` to persist metadata as-is. Pass `{ rules?: RedactionRule[] }` for custom rules (defaults still apply). **`redact: false` wins** over `redactionProfile` for trace writing.
+  - **`redactionProfile`**: optional preset — `local` (default), `share`, or `strict`. Adds extra key-based redaction and tighter metadata string bounds for trace writing. Key-based only — not compliance-grade DLP.
   - **`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.
 - **`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.
   - **`step.llm(model, fn)`**: convenience wrapper (`type: "llm"`, `metadata.model`).
   - **`step.tool(toolName, fn)`**: convenience wrapper (`type: "tool"`, `metadata.toolName`).
 - **`observe(agent, options?)`**: proxy wrapper that traces top-level `run` / `execute` / `invoke` methods via `inspectRun`.
+- **`getCurrentCorrelationMetadata()`**: returns active run correlation fields (`correlationId`, `requestId`, `decisionId`, `groupId`) inside `inspectRun` / `maybeInspectRun`; `undefined` outside a traced run or when none were set.
+- **`RedactionProfile`**: `"local" | "share" | "strict"` — see `redactionProfile` on `InspectRunOptions` and `ExportOptions`.
+- **`resolveRedactionProfile(profile?)`**: resolves profile extra keys and metadata caps (for advanced integrations).
 
 ## 3. Stable local inspection APIs
 
@@ -95,7 +100,8 @@ The CLI `tail` workflow is supported. The programmatic accumulator is experiment
 
 Exports are **read-only**, **local-only**, and **compatibility-oriented**. They do not upload, stream, or integrate vendor SDKs.
 
-- **`exportRunTree`**
+- **`exportRunTree`**, **`redactRunTreeForExport`**
+- **`ExportOptions.redactionProfile`**: `local` (default), `share`, or `strict` — applies key-based redaction to an exported copy without mutating the source tree.
 - **`exportMarkdown`**, **`exportHtml`**
 - **`exportOpenInference`** (OpenInference-compatible JSON)
 - **`exportOtlpJson`** (OTLP JSON, experimental until verified per backend)
@@ -119,12 +125,14 @@ Diff is local and read-only. Programmatic diff surfaces are experimental until t
   - **`runName`**: default `"langchain-agent"` for standalone persisted runs
   - **`traceDir`**: defaults via `resolveTraceDir` / `AGENT_INSPECT_TRACE_DIR`
   - **`capture`**: `"none"` | `"metadata-only"` (default) | `"preview"` (truncated previews, opt-in)
+  - **`stream`**: default `false` — when `true`, records streaming lifecycle metadata (`chunkCount`, `streamDurationMs`, etc.) on LLM end/error; does **not** capture full token text by default
+  - **`maxStreamPreviewChars`**: bounds `streamPreview` when `capture: "preview"` and `stream: true` (defaults to `maxPreviewChars`)
   - **`redact`**: custom `RedactionRule[]` applied before disk (core defaults still apply via shared redactor)
   - **`runId`**: optional id for standalone persisted runs
   - In-memory **`getEvents()`** / **`clear()`** unchanged when `persist` is false
 - Metadata helpers: `extractModelName`, `extractTokenUsage`, `safePreview`, `toPlainMetadata`
 
-Rationale: v1.0 includes one official adapter and **zero production sinks**, so adapter surfaces remain experimental.
+Rationale: v1.x includes one official adapter and **zero production sinks**, so adapter surfaces remain experimental.
 
 ## 10. Experimental `@agent-inspect/tui` APIs
 
@@ -132,23 +140,49 @@ Rationale: v1.0 includes one official adapter and **zero production sinks**, so
 
 - `runTraceViewer`, `loadTraceForTui`, `buildTuiTraceModel`, etc.
 
-## 11. Deprecated APIs
+## 11. Experimental persisted-event foundation (v1.2.0)
 
-No deprecated APIs are declared in v1.0 Pass 1.
+These helpers expose the **source-agnostic `PersistedInspectEvent` model** (`schemaVersion: "0.2"`). They are **local-only**, **in-memory**, and **do not change** storage write/read or CLI behavior in v1.2.0.
 
-## 12. Removal / deprecation policy
+Import from `agent-inspect`:
+
+| API | Role |
+| --- | ---- |
+| `isPersistedInspectEvent` | Runtime validator for v0.2 persisted events |
+| `traceEventToPersistedInspectEvent` | Convert one v0.1 `TraceEvent` |
+| `traceEventsToPersistedInspectEvents` | Batch v0.1 → v0.2 |
+| `inspectEventToPersistedInspectEvent` | Convert one in-memory `InspectEvent` |
+| `inspectEventsToPersistedInspectEvents` | Batch `InspectEvent` → v0.2 |
+| `persistedInspectEventToInspectEvent` | Convert one v0.2 event to `InspectEvent` |
+| `persistedInspectEventsToInspectEvents` | Batch v0.2 → `InspectEvent` |
+| `persistedInspectEventsToRunTrees` | Build `InspectRunTree[]` from v0.2 events (via `TreeBuilder`) |
+| `traceEventsToPersistedRunTrees` | v0.1 `TraceEvent[]` → persisted model → trees |
+
+Related types: `PersistedInspectEvent`, `PersistedEventSourceType`, `PersistedEventStatus`, `TraceEventToPersistedOptions`, `InspectEventToPersistedOptions`, `PersistedToInspectEventOptions`, `PersistedTreeBridgeOptions`.
+
+**Notes:**
+
+- Manual trace **writing** remains `schemaVersion: "0.1"`.
+- v0.2 is **not written by default**; use converters and `fixtures/traces-v0.2/` samples for validation.
+- Storage dual-read and CLI integration are future work.
+
+## 12. Deprecated APIs
+
+No deprecated APIs are declared as of 1.2.0.
+
+## 13. 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.
 
-## 13. Backward compatibility policy
+## 14. 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.
 
-## 14. Examples
+## 15. Examples
 
 ### Minimal manual trace
 

package/docs/ARCHITECTURE.md

@@ -19,6 +19,7 @@ Root `agent-inspect` uses **conditional exports** for ESM/CJS TypeScript consume
 - Manual traces use **`schemaVersion: "0.1"`** JSONL events (`run_started`, `step_started`, `step_completed`, `run_completed`).
 - Failures use `step_completed` with `status: "error"` — there is no `step_failed` event.
 - Log-derived runs use confidence labels (`explicit`, `correlated`, `heuristic`, `unknown`) and conservative tree-building rules.
+- **v1.2.0 persisted-event foundation (released):** source-agnostic `PersistedInspectEvent` helpers (`schemaVersion: "0.2"`) — types, validators, converters, and in-memory tree bridge. Existing **`TreeBuilder`** remains the canonical tree builder. v0.2 bridge works **in memory only**; storage dual-read and CLI integration are v1.3+ / post-foundation work. See [proposals/UNIFIED-PERSISTED-INSPECT-EVENT.md](./proposals/UNIFIED-PERSISTED-INSPECT-EVENT.md) and [implementation/V1.3.0-RELEASE-TRAIN.md](./implementation/V1.3.0-RELEASE-TRAIN.md).
 
 See [SCHEMA.md](./SCHEMA.md) for field reference and [API.md](./API.md) for public surfaces (stable vs experimental).
 

package/docs/CLI.md

@@ -1,4 +1,4 @@
-# CLI (AgentInspect 1.0)
+# CLI (AgentInspect 1.x)
 
 This document describes the **stable CLI surface** of AgentInspect.
 
@@ -178,6 +178,14 @@ Options:
 - `--include-attributes`: include bounded attributes (review before sharing)
 - `--no-metadata`: omit summary/metadata sections
 - `--no-errors`: omit error sections
+- `--redaction-profile <profile>`: redaction profile for exported copies — `local` (default), `share`, or `strict`. Key-based safety only; review exports before sharing.
+
+Examples:
+
+```bash
+npx agent-inspect export <run-id> --format markdown --redaction-profile share
+npx agent-inspect export <run-id> --format html --redaction-profile strict
+```
 
 ### 6.7 `diff`
 
@@ -196,6 +204,53 @@ Options:
 - `--focus <all|errors|structure|outputs>`
 - `--check <all|structure|outputs|errors|timing>`
 
+Fixture examples:
+
+```bash
+agent-inspect diff minimal-success minimal-error --dir fixtures/traces
+agent-inspect diff minimal-success long-running --dir fixtures/traces --check timing --duration-threshold 1ms
+agent-inspect diff minimal-success nested-3-levels --dir fixtures/traces --check structure --ignore-duration
+```
+
+**Simplified example output** (actual CLI formatting may differ slightly):
+
+```text
+Run diff
+Left:  minimal-success
+Right: minimal-error
+
+Summary:
+  Differences: 4
+  Errors: 0
+  Warnings: 3
+  Info: 1
+
+First divergence:
+  run-status at (run)
+    left: success
+    right: error
+
+Differences:
+  [warning] run-status
+    Run completion status differs
+    left: success
+    right: error
+  [info] duration
+    Run duration differs
+    left: 120
+    right: 70
+  [warning] step-removed plan
+    Step only in left run: plan
+    left: step_root
+    right: (undefined)
+  [warning] step-added failing-step
+    Step only in right run: failing-step
+    left: (undefined)
+    right: step_fail
+```
+
+More examples, including timing-only and structure-only diffs, are in `docs/DIFF.md`.
+
 ## 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

@@ -8,4 +8,131 @@ AgentInspect can compare two runs (manual traces) locally and render a diff summ
 Notes:
 - Programmatic diff APIs are documented as **experimental** in `docs/API.md`.
 - `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.
 
+## CLI examples
+
+The examples below use the checked-in fixture traces, so they are safe to copy and run locally:
+
+```bash
+agent-inspect diff minimal-success minimal-error --dir fixtures/traces
+agent-inspect diff minimal-success long-running --dir fixtures/traces --check timing --duration-threshold 1ms
+agent-inspect diff minimal-success nested-3-levels --dir fixtures/traces --check structure --ignore-duration
+```
+
+If you are running from a source checkout before installing the package globally, use the built CLI path instead:
+
+```bash
+node packages/cli/dist/index.cjs diff minimal-success minimal-error --dir fixtures/traces
+```
+
+### Success run vs error run
+
+This compares a successful run with a run that ended in an error. It shows the run status change, a duration difference, and the step-level structure difference (`plan` removed, `failing-step` added).
+
+**Simplified example output** (actual CLI formatting may differ slightly):
+
+```text
+Run diff
+Left:  minimal-success
+Right: minimal-error
+
+Summary:
+  Differences: 4
+  Errors: 0
+  Warnings: 3
+  Info: 1
+
+First divergence:
+  run-status at (run)
+    left: success
+    right: error
+
+Differences:
+  [warning] run-status
+    Run completion status differs
+    left: success
+    right: error
+  [info] duration
+    Run duration differs
+    left: 120
+    right: 70
+  [warning] step-removed plan
+    Step only in left run: plan
+    left: step_root
+    right: (undefined)
+  [warning] step-added failing-step
+    Step only in right run: failing-step
+    left: (undefined)
+    right: step_fail
+```
+
+### Duration-only timing check
+
+Use `--check timing` when you only want timing differences. `--duration-threshold` can hide tiny deltas.
+
+```bash
+agent-inspect diff minimal-success long-running --dir fixtures/traces --check timing --duration-threshold 1ms
+```
+
+**Simplified example output**:
+
+```text
+Run diff
+Left:  minimal-success
+Right: long-running
+
+Summary:
+  Differences: 1
+  Errors: 0
+  Warnings: 0
+  Info: 1
+
+First divergence:
+  duration at (run)
+    left: 120
+    right: 45
+
+Differences:
+  [info] duration
+    Run duration differs
+    left: 120
+    right: 45
+```
+
+### Step structure / rename-style changes
+
+When a prompt, model, or routing change renames or restructures steps, the current diff output represents that as `step-removed` plus `step-added`. Use `--ignore-duration` if the structure is what matters.
+
+```bash
+agent-inspect diff minimal-success nested-3-levels --dir fixtures/traces --check structure --ignore-duration
+```
+
+**Simplified example output**:
+
+```text
+Run diff
+Left:  minimal-success
+Right: nested-3-levels
+
+Summary:
+  Differences: 2
+  Errors: 0
+  Warnings: 2
+  Info: 0
+
+First divergence:
+  step-removed at plan
+    left: step_root
+    right: (undefined)
+
+Differences:
+  [warning] step-removed plan
+    Step only in left run: plan
+    left: step_root
+    right: (undefined)
+  [warning] step-added outer
+    Step only in right run: outer
+    left: (undefined)
+    right: step_outer
+```

package/docs/EXPORTS.md

@@ -6,6 +6,20 @@ AgentInspect supports local-only exports from run trees and traces. Exports are
 - **Schema + compatibility guarantees**: `docs/SCHEMA.md`
 - **Safety / redaction notes**: `docs/CLI.md`, `SECURITY.md`, and `docs/SCHEMA.md` (redaction section)
 
+## Share-safe exports (v1.3.0+)
+
+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 --redaction-profile share
+```
+
+- 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.
+
+See [SAFE-TRACE-SHARING.md](./SAFE-TRACE-SHARING.md).
+
 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.

package/docs/GETTING-STARTED.md

@@ -14,6 +14,8 @@ The `agent-inspect` package includes the CLI binary via its `bin` field:
 npx agent-inspect --help
 ```
 
+For a clean install verification path covering npm, pnpm, ESM import, CJS require, and CLI help, see [Clean install smoke test](./INSTALL-SMOKE-TEST.md).
+
 For local repo development (this monorepo), build and run the CLI from `packages/cli`:
 
 ```bash
@@ -33,7 +35,7 @@ await inspectRun("demo-agent", async () => {
 });
 ```
 
-This writes a local JSONL trace with stable v1.0 event names:
+This writes a local JSONL trace with stable event names (`schemaVersion: "0.1"`):
 
 - `run_started`, `run_completed`
 - `step_started`, `step_completed`
@@ -58,6 +60,10 @@ 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.
 
+### 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).
+
 To skip tracing in code without env vars: `inspectRun(name, fn, { enabled: false })`.
 
 ## 3. View runs
@@ -151,4 +157,3 @@ agent-inspect view <runId> --tui
 - [docs/KNOWN-ISSUES.md](./KNOWN-ISSUES.md)
 - [docs/LIMITATIONS.md](./LIMITATIONS.md)
 - [ROADMAP.md](../ROADMAP.md)
-