agent-inspect 1.0.3 → 1.2.0

package/CHANGELOG.md

@@ -1,5 +1,74 @@
 # Changelog
 
+## 1.2.0
+
+### Minor Changes
+
+- 5a7f785: v1.2.0: experimental persisted-event foundation (`PersistedInspectEvent` schemaVersion 0.2), validators, TraceEvent/InspectEvent converters, in-memory tree bridge, v0.2 fixtures, and docs. Manual trace writing remains schemaVersion 0.1; no storage or CLI behavior change.
+
+## 1.2.0 — Unreleased
+
+### 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
+
+Changeset `21ecc6f`: env-gated tracing, trace safety (redaction + size bounds), LangChain JSONL persistence, logging recipes, CJS/ESM type export compatibility, community docs.
+
+### Added
+
+- Added env-gated tracing with `maybeInspectRun()` using `AGENT_INSPECT`.
+- Added `enabled` option for `inspectRun` passthrough when tracing should be skipped.
+- Added default-on persisted trace safety for manual traces, including metadata redaction and event size bounds.
+- Added optional LangChain JSONL persistence with `persist: true` in `@agent-inspect/langchain`.
+- Added production-shaped logging guidance with pino, log4js, and NestJS JSON logging recipes.
+- Added community contribution scaffold, issue templates, and good-first-issue guidance.
+
+### Fixed
+
+- Fixed conditional type exports for ESM and CommonJS TypeScript consumers.
+- Improved package compatibility for TypeScript Node16/NodeNext consumers using `import` and `require`.
+- Updated public docs to avoid treating `docs-local` as primary contributor/user documentation.
+- Updated stale docs around LangChain persistence, redaction, and package boundaries.
+
+### Security
+
+- Redacts sensitive manual trace metadata before disk by default.
+- Allows explicit opt-out with `redact: false`.
+- Bounds persisted event and metadata size to reduce accidental large trace files.
+- Keeps JSON logs first-class and log4js parsing best-effort without unsafe JavaScript object parsing.
+
+### Documentation
+
+- Added/updated logging playbook for structured JSON logs ([docs/LOGGING-PLAYBOOK.md](docs/LOGGING-PLAYBOOK.md)).
+- 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.
+
+### Notes
+
+- LangChain adapter APIs remain experimental.
+- `persist: false` remains the default for `@agent-inspect/langchain`; `persist: true` is opt-in.
+- Existing manual trace schema remains `schemaVersion: "0.1"`.
+- Existing event names remain `run_started`, `run_completed`, `step_started`, and `step_completed`.
+- There is still no `step_failed` event; failures are represented as `step_completed` with `status: "error"`.
+- JSON logs remain first-class; log4js text parsing remains best-effort.
+- No vendor upload, network sink, dashboard, replay engine, or cost engine was added.
+- Root `agent-inspect` runtime dependencies remain `chalk`, `commander`, and `nanoid` only.
+
 ## 1.0.3
 
 ### Patch Changes
@@ -20,16 +89,6 @@
 
 - 575b093: docs: onboarding polish
 
-## Unreleased
-
-### Documentation
-
-- Improved README onboarding for new users.
-- Added comparison guide.
-- Added log-to-tree quickstart.
-- Added a quickstart demo example.
-- Clarified docs organization between user-facing `docs/` and internal `docs-local/`.
-
 ## 1.0.0
 
 ### Stable local tracing

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.1.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`:
@@ -133,7 +137,7 @@ 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.
 
-More detail: [docs/LOGS.md](docs/LOGS.md) · [docs/LOG-TO-TREE-QUICKSTART.md](docs/LOG-TO-TREE-QUICKSTART.md).
+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
 
@@ -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.
 - 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.1.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`**
@@ -189,7 +193,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**. 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
@@ -199,12 +203,18 @@ pnpm add agent-inspect @agent-inspect/langchain @langchain/core
 import { AgentInspectCallback } from "@agent-inspect/langchain";
 
 const callback = new AgentInspectCallback({
-  runName: "my-run",
+  runName: "support-agent",
+  traceDir: "./.agent-inspect",
+  persist: true,
   capture: "metadata-only",
 });
 
 await agent.invoke(input, { callbacks: [callback] });
+// In-memory events still available:
 const events = callback.getEvents();
+// Persisted runs are inspectable via CLI:
+// npx agent-inspect list --dir ./.agent-inspect
+// npx agent-inspect view <run-id> --dir ./.agent-inspect
 ```
 
 See [examples/08-langchain-adapter](examples/08-langchain-adapter/README.md) and [docs/ADAPTERS.md](docs/ADAPTERS.md).
@@ -236,6 +246,9 @@ The TUI is available as a separate optional package; its programmatic API is exp
 | [examples/recipes/tool-failure-retry](examples/recipes/tool-failure-retry) | Tool failure + retry |
 | [examples/recipes/multi-agent-handoff](examples/recipes/multi-agent-handoff) | Handoff |
 | [examples/recipes/proactive-agent-logs](examples/recipes/proactive-agent-logs) | Structured logs |
+| [examples/recipes/pino-json-logs](examples/recipes/pino-json-logs) | pino-shaped JSON |
+| [examples/recipes/log4js-json-layout](examples/recipes/log4js-json-layout) | log4js embedded JSON |
+| [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 |
 
@@ -245,10 +258,10 @@ The TUI is available as a separate optional package; its programmatic API is exp
 
 - **Local files by default** — no upload, no vendor sinks in core workflows.
 - **No API keys** required for core tracing and CLI inspection.
-- **Manual metadata** is user-controlled; traces and exports can contain sensitive data if you put it there.
+- **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
 
@@ -259,22 +272,36 @@ 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)
 - [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

@@ -63,11 +63,14 @@ AgentInspect aims to be safe-by-default for **log-derived attributes** and **exp
 
 Important limitations:
 
-- **Manual trace metadata is user-controlled.** If you attach secrets to `inspectRun({ metadata })` or step metadata, those values may appear in local trace files and could appear in some views/exports depending on your settings and what you choose to include.
+- **Manual trace metadata is user-controlled.** By default, `inspectRun()` and `step()` **redact common sensitive keys** before writing JSONL (`authorization`, `cookie`, `token`, `apiKey`, `password`, `secret`, `email` — case-insensitive). Pass **`redact: false`** to persist metadata as-is (explicit opt-out).
+- **Non-sensitive metadata and custom keys** are still written locally. Do not attach secrets you are unwilling to store on disk, even with redaction enabled (custom key names may bypass defaults).
+- **Size bounds** truncate long metadata values and cap serialized event size (default 64 KiB per line). Oversized events are truncated further or replaced with a `{ truncated: true, reason: "maxEventBytes" }` marker — instrumentation never throws into your app because of payload size.
+- **`@agent-inspect/langchain` with `persist: true`** writes the same local JSONL format as manual traces. Default **`capture: "metadata-only"`** does not persist full prompts/outputs; use **`capture: "preview"`** only when you accept truncated previews on disk.
 - Always **review exported files** before sharing them externally.
 - Avoid committing trace directories (`.agent-inspect-runs/`) to source control.
 
-For redaction design details, see `docs-local/architecture/REDACTION.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

@@ -5,11 +5,38 @@ AgentInspect is framework-agnostic at its core, but can optionally integrate wit
 - **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
+  - **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 persistence model (Strategy A)
+
+When `persist: true`:
+
+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`.
+
+```ts
+const callback = new AgentInspectCallback({
+  runName: "support-agent",
+  traceDir: "./.agent-inspect",
+  persist: true,
+  capture: "metadata-only",
+});
+```
+
+```bash
+npx agent-inspect list --dir ./.agent-inspect
+npx agent-inspect view <run-id> --dir ./.agent-inspect
+```
+
 See also:
 - `docs/MIGRATION.md` (what changed from early versions)
-- `docs-local/RELEASE-CHECKLIST.md` (maintainer-only release steps)
+- `docs/API.md` (LangChain adapter options: `persist`, `capture`, `traceDir`)
 

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,9 +26,13 @@ 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).
+  - **`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.
 - **`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(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`.
@@ -111,9 +115,16 @@ Diff is local and read-only. Programmatic diff surfaces are experimental until t
 `@agent-inspect/langchain` is an optional adapter package.
 
 - **`AgentInspectCallback`** (experimental)
+  - **`persist`**: default `false` — when `true`, maps callback lifecycle to schemaVersion `"0.1"` JSONL (`run_started` / `step_started` / `step_completed` / `run_completed`)
+  - **`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)
+  - **`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
 
@@ -121,23 +132,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.1.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

@@ -1,13 +1,49 @@
 ## Architecture
 
-This doc is a stable entry point for AgentInspect’s internal architecture and product boundaries.
+AgentInspect is a **local-first execution-tree debugger**: manual traces and log ingest produce inspectable step trees stored as JSONL on disk (default `.agent-inspect-runs/`), with a CLI for list/view/clean/logs/tail/export/diff workflows.
 
-- **Canonical architecture overview**: see `docs-local/architecture/ARCHITECTURE.md`
-- **Event model**: `docs-local/architecture/EVENT-MODEL.md`
-- **Tree building rules**: `docs-local/architecture/TREE-BUILDING-RULES.md`
-- **Schema evolution policy**: `docs-local/architecture/SCHEMA-EVOLUTION.md`
-- **Dependency policy**: `docs-local/architecture/DEPENDENCY-POLICY.md`
-- **Redaction design**: `docs-local/architecture/REDACTION.md`
+### Package layout
 
-If you’re new, start with `docs/GETTING-STARTED.md`, then `docs/API.md`, `docs/CLI.md`, and `docs/SCHEMA.md`.
+| Package | Published? | Role |
+| -------- | ---------- | ---- |
+| `agent-inspect` | Yes | Public tarball: core tracing APIs + CLI (`agent-inspect` binary) |
+| `@agent-inspect/core` | No (private) | Tracing, storage, log parsing, export, diff |
+| `@agent-inspect/cli` | No (private) | Commander CLI implementation |
+| `@agent-inspect/langchain` | Yes (optional) | LangChain.js callback adapter (experimental) |
+| `@agent-inspect/tui` | Yes (optional) | Ink/React terminal viewer (experimental) |
 
+Root `agent-inspect` uses **conditional exports** for ESM/CJS TypeScript consumers (`import.types` / `require.types`). Heavy dependencies (LangChain, Ink/React) stay in optional packages.
+
+### Event model and schema
+
+- 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 (release-readiness):** 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 future work. See [proposals/UNIFIED-PERSISTED-INSPECT-EVENT.md](./proposals/UNIFIED-PERSISTED-INSPECT-EVENT.md) and [implementation/V1.2.0-RELEASE-READINESS.md](./implementation/V1.2.0-RELEASE-READINESS.md).
+
+See [SCHEMA.md](./SCHEMA.md) for field reference and [API.md](./API.md) for public surfaces (stable vs experimental).
+
+### Safety and redaction
+
+- Instrumentation must **not throw into user code**; trace safety failures degrade gracefully.
+- **Manual metadata** is redacted before disk by default; `redact: false` opts out.
+- **Size bounds** cap persisted event and metadata size.
+- Log ingest: JSON first-class; log4js best-effort; no `eval` or JS object-literal parsing.
+
+See [SECURITY.md](../SECURITY.md) and [LIMITATIONS.md](./LIMITATIONS.md).
+
+### Optional adapters
+
+- **`@agent-inspect/langchain`**: in-memory by default; `persist: true` writes local JSONL. Experimental.
+- **`@agent-inspect/tui`**: interactive viewer; isolated from root deps. Experimental.
+
+See [ADAPTERS.md](./ADAPTERS.md).
+
+### Where to read next
+
+- New users: [GETTING-STARTED.md](./GETTING-STARTED.md)
+- CLI: [CLI.md](./CLI.md)
+- Structured logs: [LOGS.md](./LOGS.md), [LOGGING-PLAYBOOK.md](./LOGGING-PLAYBOOK.md)
+- Contributors: [CONTRIBUTING.md](../CONTRIBUTING.md), [docs/community/CONTRIBUTING.md](./community/CONTRIBUTING.md)
+
+Maintainer-only internal docs under `docs-local/` may contain additional historical architecture depth; they are not required for contributors.

package/docs/CLI.md

@@ -196,6 +196,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

@@ -4,7 +4,7 @@ AgentInspect supports local-only exports from run trees and traces. Exports are
 
 - **CLI usage**: `docs/CLI.md` (`export`)
 - **Schema + compatibility guarantees**: `docs/SCHEMA.md`
-- **Safety / redaction notes**: `docs/CLI.md`, `SECURITY.md`, and `docs-local/architecture/REDACTION.md`
+- **Safety / redaction notes**: `docs/CLI.md`, `SECURITY.md`, and `docs/SCHEMA.md` (redaction section)
 
 Notes:
 - Export formats (Markdown/HTML/OpenInference/OTLP JSON) are documented as **experimental / compatibility-oriented** in `docs/API.md`.