agent-inspect 1.0.0 → 1.0.2

package/README.md

@@ -1,525 +1,275 @@
 # agent-inspect
 
-agent-inspect is a local-first execution-tree debugger for TypeScript AI agents.
+**Local execution trees for TypeScript AI agents.**
 
-## Why
+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.
 
-AI agents are multi-step. Console logs are flat.
+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.
 
-agent-inspect turns runs into structured execution trees with JSONL traces and CLI inspection.
+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.
 
-agent-inspect is designed for inner-loop debugging, not as a replacement for production observability platforms.
+**No account. No cloud upload. No dashboard required.**
 
-## What you get
+## Why agent-inspect exists
 
-- Execution-tree tracing for TypeScript agent workflows
-- Nested `step()` support with parent-child relationships
-- `step.llm()` and `step.tool()` helpers for agent-aware traces
-- Local JSONL trace files
-- Real-time terminal output while the agent runs
-- CLI commands to inspect previous runs
-- No accounts, API keys, dashboards, or cloud ingestion
+AI agents are no longer single function calls. They plan, call tools, invoke LLMs, branch, retry, fail, and run work in parallel. **Console logs are flat**; reconstructing causality from a wall of lines is slow and error-prone.
 
-## Install
-
-```bash
-npm install agent-inspect
-```
-
-## Documentation (v1.0 stabilization)
+**Hosted observability** is valuable in production, but it can be heavy for the **inner loop**: local runs, fast iteration, and debugging before anything reaches a collector or dashboard.
 
-- [Getting started](docs/GETTING-STARTED.md)
-- [API reference](docs/API.md)
-- [CLI reference](docs/CLI.md)
-- [Schema reference](docs/SCHEMA.md)
-- [Security policy](SECURITY.md)
-- [Migration guide](docs/MIGRATION.md)
-- [Release checklist](docs/RELEASE-CHECKLIST.md)
-- [Changelog](CHANGELOG.md)
-- [Known issues](docs/KNOWN-ISSUES.md)
-- [Limitations](docs/LIMITATIONS.md)
-- [V1 readiness checklist (non-binding)](docs/V1-READINESS-CHECKLIST.md)
+agent-inspect gives those runs **structure**: an **execution tree** you can read and diff on disk, with a **CLI-first** workflow and **no vendor lock-in**.
 
-## See your first trace
-
-Run a traced workflow, then inspect it with the CLI.
-
-```ts
-import { inspectRun, step } from "agent-inspect";
-
-await inspectRun("hello-agent", async () => {
-  const plan = await step("plan", async () => "search hotels");
-  return step("finalize", async () => ({ plan, status: "done" }));
-});
-```
-
-```bash
-npx agent-inspect list
-npx agent-inspect view run_abc123
-```
-
-Replace `run_abc123` with the run id printed by `agent-inspect list`.
-
-### Optional TUI viewer
-
-The core `agent-inspect` package stays lightweight and does not bundle Ink or React. For a keyboard-driven terminal UI over existing traces, install the optional package:
+## Install
 
 ```bash
-pnpm add agent-inspect @agent-inspect/tui
-
-npx agent-inspect view run_abc123 --tui
+npm install agent-inspect
 ```
 
-The plain CLI remains the default. `--tui` requires an interactive terminal; for scripts or CI, use `agent-inspect view` or `agent-inspect view --json`. There is no live tail TUI yet.
-
-### Export traces
-
-Export existing manual JSONL traces locally — **no upload**, **no vendor SDKs**. Markdown is handy for PRs and issues; HTML is a single offline file. OpenInference export is **OpenInference-compatible JSON** (not a guarantee for every backend). OTLP JSON uses **OTel GenAI-aligned attributes** where applicable and is **experimental** until validated against a specific collector.
-
 ```bash
-npx agent-inspect export run_abc123 --format markdown
-npx agent-inspect export run_abc123 --format html -o run.html
-npx agent-inspect export run_abc123 --format openinference -o trace.openinference.json
-npx agent-inspect export run_abc123 --format otlp-json -o trace.otlp.json
-npx agent-inspect export run_abc123 --format openinference --validate
+pnpm add agent-inspect
 ```
 
-Review exported files for sensitive data before sharing. Attribute payloads are bounded and redacted by default; use `--include-attributes` only when you intend to share richer detail.
-
-### Compare runs
-
-Diff is **local** and **read-only**: it compares two existing AgentInspect JSONL traces and does **not** rerun agents, mutate trace files, or write output traces. It does **not** claim semantic equivalence and does **not** call an LLM.
-
-Finding differences does **not** change the exit code by default (exit code `1` is reserved for command errors such as a missing run).
+Verify the CLI is available:
 
 ```bash
-npx agent-inspect diff run_a run_b
-npx agent-inspect diff run_a run_b --json
-npx agent-inspect diff run_a run_b --ignore-duration
-npx agent-inspect diff run_a run_b --duration-threshold 500ms
-npx agent-inspect diff run_a run_b --focus errors
-npx agent-inspect diff run_a run_b --check structure
+npx agent-inspect --help
 ```
 
-Useful for comparing passing vs failing runs and spotting the **first divergence** in execution order.
-
-### Fixtures and hardening (v0.9)
-
-**v0.9** adds canonical [**fixtures/**](fixtures/README.md), validation (`pnpm fixtures:check`), **recipe examples** under [**examples/recipes/**](examples/recipes/README.md) (`pnpm recipes:check`), and docs aimed at adoption—not new tracing features. Recipes use mocks only and require no API keys or external services by default. Good starting points: **rag-pipeline**, **tool-failure-retry**, **proactive-agent-logs**. See [**Known issues**](docs/KNOWN-ISSUES.md), [**Limitations**](docs/LIMITATIONS.md), and the non-binding [**v1 readiness checklist**](docs/V1-READINESS-CHECKLIST.md).
+## 60-second quickstart
 
-## Minimal API
+Create `demo.mjs`:
 
-```ts
+```js
 import { inspectRun, step } from "agent-inspect";
 
-await inspectRun("my-agent-run", async () => {
-  const plan = await step("plan", async () => ({ task: "research" }));
-  return step("act", async () => plan);
-});
-```
+const delay = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
 
-## LLM and tool helpers
-
-```ts
-await step.llm("mock-gpt", async () => {
-  return planner.run();
-});
-
-await step.tool("searchHotels", async () => {
-  return searchHotels();
-});
-```
-
-Helpers only label steps in the trace.
-
-They do not import or call vendor SDKs.
-
-## observe()
-
-`observe()` wraps top-level `run`, `execute`, and `invoke`.
-
-For internal detail, add manual `step()` calls inside the agent.
-
-```ts
-import { observe } from "agent-inspect";
-
-class MyAgent {
-  async run(input: string) {
-    return `ok: ${input}`;
-  }
-}
-
-const agent = observe(new MyAgent());
-await agent.run("hello");
-```
-
-See [examples/05-observe-wrapper](examples/05-observe-wrapper) for a top-level observed run with internal `step()`, `step.tool()`, and `step.llm()` calls.
-
-## Usage examples
-
-### Example 1: Basic workflow
-
-```ts
-import { inspectRun, step } from "agent-inspect";
-
-const result = await inspectRun("hotel-booking", async () => {
-  const hotels = await step("search-hotels", async () => {
-    return ["Tokyo Grand Hotel", "Tokyo Central Inn"];
-  });
-
-  const availability = await step("check-availability", async () => {
-    return { hotel: hotels[0], rooms: 2 };
-  });
-
-  return step("finalize-booking", async () => {
-    return `confirmed:${availability.hotel}`;
-  });
-});
-
-console.log(result);
-```
-
-Expected tree:
-
-```text
-hotel-booking
-✔ search-hotels
-✔ check-availability
-✔ finalize-booking
-```
-
-### Example 2: Nested LLM and tool steps
-
-```ts
-import { inspectRun, step } from "agent-inspect";
-
-await inspectRun("trip-planner", async () => {
-  const plan = await step("plan-trip", async () => {
-    const draft = await step.llm("mock-gpt", async () => {
-      return "Plan: museum, dinner, evening walk.";
+await inspectRun(
+  "support-agent",
+  async () => {
+    const plan = await step("plan", async () => {
+      await delay(40);
+      return { intent: "refund-policy", needsPolicy: true };
     });
 
-    return step("parse-plan", async () => {
-      return draft.replace("Plan: ", "").split(", ");
-    });
-  });
-
-  const hotels = await step.tool("searchHotels", async () => {
-    return [{ id: "h1", city: "Kyoto" }];
-  });
-
-  return step("finalize", async () => {
-    return { plan, hotel: hotels[0] };
-  });
-});
-```
-
-Expected tree:
-
-```text
-trip-planner
-✔ plan-trip
-  ✔ llm:mock-gpt
-  ✔ parse-plan
-✔ tool:searchHotels
-✔ finalize
-```
-
-### Example 3: Error handling
-
-```ts
-import { inspectRun, step } from "agent-inspect";
-
-try {
-  await inspectRun("pricing-flow", async () => {
-    await step("load-catalog", async () => ["sku-a", "sku-b"]);
-
-    await step("fetch-dynamic-pricing", async () => {
-      throw new Error("Pricing API timeout");
+    const policy = await step.tool("retrieve-policy", async () => {
+      await delay(60);
+      return { text: "Refunds are available within 30 days of purchase." };
     });
 
-    await step("apply-discount", async () => {
-      return "this step will not run";
+    return step.llm("generate-answer", async () => {
+      await delay(80);
+      return `Policy: ${policy.text} (intent: ${plan.intent})`;
     });
-  });
-} catch (error) {
-  console.error("Original error still propagated:", error);
-}
+  },
+  { traceDir: "./.agent-inspect" }
+);
 ```
 
-agent-inspect records the failed step, writes it to the trace file, and still rethrows the original error.
-
-### Example 4: `observe()` wrapper
+Run it, then inspect the trace:
 
-```ts
-import { observe, step } from "agent-inspect";
-
-class CustomerSupportAgent {
-  async run(question: string): Promise<string> {
-    const category = await step("triage-question", async () => {
-      return question.toLowerCase().includes("password")
-        ? "account-access"
-        : "general";
-    });
-
-    const articles = await step.tool("retrieveArticles", async () => {
-      return ["Reset your password from the login page."];
-    });
-
-    return step.llm("mock-support-model", async () => {
-      return `Category: ${category}. ${articles[0]}`;
-    });
-  }
-}
-
-const agent = observe(new CustomerSupportAgent());
-await agent.run("How do I reset my password?");
+```bash
+node demo.mjs
+npx agent-inspect list --dir ./.agent-inspect
+npx agent-inspect view <run-id> --dir ./.agent-inspect
+npx agent-inspect view <run-id> --dir ./.agent-inspect --summary
 ```
 
-`observe()` wraps top-level `run`, `execute`, and `invoke` methods. For internal detail, add manual `step()` calls inside the agent.
-
-## LangChain adapter (v0.5, experimental)
-
-Install:
+Full flow:
 
 ```bash
-pnpm add agent-inspect @agent-inspect/langchain @langchain/core
+npm install agent-inspect
+node demo.mjs
+npx agent-inspect list --dir ./.agent-inspect
 ```
 
-`@langchain/core` is a **peer dependency** of `@agent-inspect/langchain`. The adapter uses official LangChain.js **callbacks** only (extends `BaseCallbackHandler`): **no** monkey-patching, **no** `agent-inspect/auto`, **no** vendor observability sinks.
-
-```ts
-import { AgentInspectCallback } from "@agent-inspect/langchain";
-
-const callback = new AgentInspectCallback({
-  runName: "support-agent-eval",
-  capture: "metadata-only",
-});
-
-await agent.invoke(input, {
-  callbacks: [callback],
-});
+**Simplified example output** (actual CLI formatting may differ slightly):
 
-const events = callback.getEvents();
+```text
+support-agent
+✔ plan
+✔ tool:retrieve-policy
+✔ llm:generate-answer
 ```
 
-Behavior:
+A runnable copy lives in [examples/00-quickstart-demo](examples/00-quickstart-demo/README.md).
 
-- **Metadata-only** capture by default (model, tags, token usage when present, counts). **No** full prompt/output capture by default.
-- **Preview** mode is opt-in (`capture: "preview"`) with truncation via `maxPreviewChars` (default `200`).
-- **Parent** links use LangChain `parentRunId`, surfaced as `parentId` on `InspectEvent` with `confidence: "explicit"`.
-- **No** cost calculation; token fields are informational only.
-- In this pass, events are collected **in memory** only (`getEvents()` / `clear()`). **No trace-file persistence** for adapter events yet; they are **not** written into v0.1 JSONL manual traces.
+## What the trace shows
 
-The API is **experimental** before v1.0. See [examples/08-langchain-adapter](examples/08-langchain-adapter).
+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).
 
-## CLI
+## Works with structured logs you already have
 
-List recent runs:
+Many production systems already emit **line-delimited JSON** or text logs with embedded JSON (e.g. via **pino**, **winston**, **log4js**, **NestJS** loggers, job runners, or custom event streams). agent-inspect can turn those into **local grouped timelines/trees** without wrapping every function.
 
 ```bash
-npx agent-inspect list
+npx agent-inspect logs ./agent.log \
+  --format json \
+  --run-id-key requestId \
+  --event-key event \
+  --timestamp-key timestamp
 ```
 
-Common filters:
+With a reusable ingest config:
 
 ```bash
-npx agent-inspect list --status success
-npx agent-inspect list --status error
-npx agent-inspect list --status running
-npx agent-inspect list --status unknown
-npx agent-inspect list --name hotel
-npx agent-inspect list --since 24h
-npx agent-inspect list --json
+npx agent-inspect logs ./agent.log --config agent-inspect.logs.json
 ```
 
-View a run:
+- **JSON logs** are first-class.
+- **log4js-style** lines are **best-effort** when a recoverable JSON payload is present.
+- **No `eval`**, no JavaScript object-literal parsing as a log interchange format.
+- **Flat timeline by default**; nesting when parent relationships are explicit or configured.
+- **Confidence labels** (`explicit`, `correlated`, `heuristic`, `unknown`) describe how attribution was inferred.
 
-```bash
-npx agent-inspect view run_abc123
-```
+More detail: [docs/LOGS.md](docs/LOGS.md) · [docs/LOG-TO-TREE-QUICKSTART.md](docs/LOG-TO-TREE-QUICKSTART.md).
 
-Alternate view modes:
+## CLI at a glance
 
-```bash
-npx agent-inspect view run_abc123 --summary
-npx agent-inspect view run_abc123 --metadata
-npx agent-inspect view run_abc123 --errors-only
-npx agent-inspect view run_abc123 --json --summary
-```
+| Command | Use it for |
+| -------- | ---------- |
+| `list` | Find recent runs |
+| `view` | Inspect one run as a tree |
+| `clean` | Safely remove old trace files |
+| `logs` | Turn existing structured logs into a local tree/timeline |
+| `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) |
 
-Safely clean up old traces (recommended: start with `--dry-run`):
+Full flags and behavior: [docs/CLI.md](docs/CLI.md).
 
-```bash
-npx agent-inspect clean --older-than 7d --dry-run
-npx agent-inspect clean --older-than 7d
-npx agent-inspect clean --keep 100 --dry-run
-npx agent-inspect clean --keep 100 --yes
-npx agent-inspect clean --dir ./traces --older-than 7d --dry-run
-```
+## Real-world workflows
 
-Safety notes:
+- 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.
+- 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.
 
-- `clean` **verifies each file** as an AgentInspect trace before deleting.
-- Arbitrary JSONL files are **not deleted**.
-- Malformed JSONL files are **not deleted**.
-- Without `--dry-run`, `clean` requires confirmation unless `--yes` is provided.
-- In non-interactive terminals, deletion requires `--yes`.
+## What v1.0 stabilizes
 
-Inspect structured logs:
+**agent-inspect 1.0** stabilizes the **local debugging foundation**:
 
-```bash
-npx agent-inspect logs ./agent.log --format json
-npx agent-inspect logs ./agent.log --format log4js
-npx agent-inspect logs ./agent.log --format auto
-npx agent-inspect logs ./agent.log --config agent-inspect.logs.json
-npx agent-inspect logs ./agent.log --json
-npx agent-inspect logs ./agent.log --summary
-npx agent-inspect logs ./agent.log --warnings all
-```
-
-Log ingestion notes:
-
-- JSON logs are first-class.
-- log4js text logs are best-effort: only embedded **valid JSON payloads** are supported.
-- JavaScript object-literal payloads are intentionally unsupported.
-- No eval is used.
-- Flat timeline is default (nesting only with explicit `parentId`).
-- Confidence labels explain attribution.
-- Redaction is applied to sensitive attributes (based on config).
+- Instrument a run 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`**
 
-Live tail structured logs:
+**Stable APIs:** `inspectRun()`, `step()`, `step.llm()`, `step.tool()`, `observe()`.
 
-```bash
-npx agent-inspect tail --file ./agent.log --format json
-npx agent-inspect tail --file ./agent.log --format log4js --config agent-inspect.logs.json
-npm run dev 2>&1 | npx agent-inspect tail --format log4js --config agent-inspect.logs.json
-npx agent-inspect tail --file ./agent.log --format auto --once
-npx agent-inspect tail --file ./agent.log --json --once
-```
+**Stable CLI workflows:** `agent-inspect list`, `agent-inspect view`, `agent-inspect clean`.
 
-Use a custom trace directory:
+**Also included in 1.0** as local-first extensions:
 
-```bash
-npx agent-inspect list --dir ./traces
-npx agent-inspect view run_abc123 --dir ./traces
-```
+- 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
 
-By default, traces are stored under `~/.agent-inspect/runs`.
+**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.
 
-You can also set a default trace directory with:
+## Optional packages
 
-```bash
-AGENT_INSPECT_TRACE_DIR=./traces npx agent-inspect list
-```
+### LangChain callback adapter (`@agent-inspect/langchain`)
 
-For local repo development after `pnpm build`:
+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.
 
 ```bash
-node packages/cli/dist/index.cjs list
-node packages/cli/dist/index.cjs view run_abc123
-```
-
-## Local traces
-
-agent-inspect writes one JSONL file per run.
-
-Default location:
-
-```text
-~/.agent-inspect/runs
+pnpm add agent-inspect @agent-inspect/langchain @langchain/core
 ```
 
-Example event shape:
-
-```json
-{"schemaVersion":"0.1","event":"step_started","name":"search-hotels","type":"logic"}
-```
+```ts
+import { AgentInspectCallback } from "@agent-inspect/langchain";
 
-You can inspect traces with standard tools:
+const callback = new AgentInspectCallback({
+  runName: "my-run",
+  capture: "metadata-only",
+});
 
-```bash
-cat ~/.agent-inspect/runs/run_abc123.jsonl
-cat ~/.agent-inspect/runs/run_abc123.jsonl | jq
+await agent.invoke(input, { callbacks: [callback] });
+const events = callback.getEvents();
 ```
 
-## Runnable examples
-
-The repo includes five runnable MVP manual-tracing examples, the v0.3 structured log-to-tree example, and the v0.5 LangChain adapter example:
+See [examples/08-langchain-adapter](examples/08-langchain-adapter/README.md) and [docs/ADAPTERS.md](docs/ADAPTERS.md).
 
-- `examples/01-basic` — `inspectRun()` + `step()`
-- `examples/02-nested-steps` — nested execution tree hierarchy
-- `examples/03-parallel-steps` — `Promise.all` sibling isolation
-- `examples/04-error-handling` — failed steps and error traces
-- `examples/05-observe-wrapper` — `observe()` wrapper with internal steps
-- `examples/06-log-to-tree` — v0.3 structured log-to-tree example (includes historical spike prototype and production `agent-inspect logs` usage)
-- `examples/08-langchain-adapter` — v0.5 LangChain callback adapter (`@agent-inspect/langchain`), provider-free simulated lifecycle (install from repo root; see example README)
+### TUI viewer (`@agent-inspect/tui`)
 
-Run one locally:
+Optional **Ink/React** package, installed separately. Use with an interactive terminal:
 
 ```bash
-pnpm build
-cd examples/01-basic
-pnpm install
-pnpm start
+pnpm add agent-inspect @agent-inspect/tui
+npx agent-inspect view <run-id> --tui
 ```
 
-Then inspect traces:
+The TUI is available as a separate optional package; its programmatic API is experimental, while the CLI integration (`view --tui`) is the intended usage. Details: [docs/ADAPTERS.md](docs/ADAPTERS.md).
 
-```bash
-node ../../packages/cli/dist/index.cjs list
-node ../../packages/cli/dist/index.cjs view run_abc123
-```
+## Examples and recipes
 
-Do not commit `node_modules`. Example dependencies are installed locally when you run `pnpm install`.
+| Example | Shows |
+| ------- | ----- |
+| [examples/00-quickstart-demo](examples/00-quickstart-demo/README.md) | Fast install-and-try trace |
+| [examples/01-basic](examples/01-basic) | `inspectRun` + `step` |
+| [examples/02-nested-steps](examples/02-nested-steps) | Nested tree |
+| [examples/03-parallel-steps](examples/03-parallel-steps) | Parallel siblings |
+| [examples/04-error-handling](examples/04-error-handling) | Failed steps |
+| [examples/05-observe-wrapper](examples/05-observe-wrapper) | `observe()` |
+| [examples/06-log-to-tree](examples/06-log-to-tree) | `logs` / `tail` |
+| [examples/08-langchain-adapter](examples/08-langchain-adapter/README.md) | LangChain callbacks |
+| [examples/recipes/rag-pipeline](examples/recipes/rag-pipeline) | RAG-shaped flow |
+| [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/retry-fallback](examples/recipes/retry-fallback) | Fallback pattern |
+| [examples/recipes/parallel-tools](examples/recipes/parallel-tools) | Parallel tools |
 
-Supporting material:
+**Recipes** are deterministic and require **no external services** by default. Index: [examples/README.md](examples/README.md), [examples/recipes/README.md](examples/recipes/README.md).
 
-- [examples/README.md](examples/README.md)
+## Security and privacy posture
 
-## Original MVP scope
+- **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.
+- **Review exports** before sharing (especially with richer attribute flags).
 
-Included:
+See [SECURITY.md](SECURITY.md).
 
-- `inspectRun()`
-- `step()`
-- `step.llm()`
-- `step.tool()`
-- `observe()`
-- JSONL traces
-- CLI `list` and `view`
+## agent-inspect comparison
 
-Current scope also includes:
+It can **complement** LangSmith, Langfuse, Braintrust, Phoenix/OpenInference, OpenTelemetry, New Relic, Datadog, and similar platforms — but it does **not** replace their production or eval workflows.
 
-- CLI `clean` (safe deletion with verification)
-- CLI `logs` (structured log-to-tree)
-- CLI `tail` (live log tailing into grouped timelines)
-- LangChain callback adapter via `@agent-inspect/langchain`
-- Optional TUI viewer via `@agent-inspect/tui`
-- Standards-aligned **local** exports (`export`: Markdown, HTML, OpenInference-compatible JSON, OTLP JSON mapping)
-- Run diff / compare (`diff`: two local traces, read-only)
-- Canonical **fixtures** under [`fixtures/`](fixtures/README.md) plus `pnpm fixtures:check` for deterministic samples
+For a detailed comparison, see [Compare with other tools](docs/COMPARE.md).
 
-Not included:
+## Documentation
 
-- Live TUI / streaming trace updates in the TUI
-- Direct vendor sinks or uploads (Phoenix, Langfuse, Braintrust, New Relic, Datadog, …)
-- Live OTLP streaming / OTLP gRPC
-- Production monitoring platforms
-- Additional framework adapters beyond LangChain
-- Token cost calculation
-- Replay / fork execution
-- SQLite
-- Dashboards
-- Multi-run statistical eval dashboards
-- Semantic / LLM-powered trace comparison
-- OpenTelemetry SDK instrumentation (exports are generated strings only)
+- [Getting started](docs/GETTING-STARTED.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)
+- [Exports](docs/EXPORTS.md)
+- [Diff](docs/DIFF.md)
+- [Adapters](docs/ADAPTERS.md)
+- [Compare with other tools](docs/COMPARE.md)
+- [Security](SECURITY.md)
+- [Changelog](CHANGELOG.md)
+- [Known issues](docs/KNOWN-ISSUES.md)
+- [Limitations](docs/LIMITATIONS.md)
+- [Screenshot checklist (planned assets)](docs/SCREENSHOTS.md)
 
 ## Development
 
+From a clone of this repo:
+
 ```bash
 pnpm install
 pnpm build
 pnpm test
 pnpm test:all
 ```
+
+To run the CLI from source after a build: `node packages/cli/dist/index.cjs --help`.