agent-inspect 1.0.1 → 1.0.3

package/README.md

@@ -1,10 +1,22 @@
 # agent-inspect
 
-Local execution trees for TypeScript AI agents.
+**Local execution trees for TypeScript AI agents.**
 
-AgentInspect helps you debug multi-step AI workflows locally by turning manual steps, structured logs, and agent callbacks into readable execution trees.
+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.
 
-No account. No cloud upload. No dashboard required.
+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.
+
+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.
+
+**No account. No cloud upload. No dashboard required.**
+
+## Why agent-inspect exists
+
+AI agents are no longer single function calls. They plan, call tools, invoke LLMs, branch, retry, fail, and run work in parallel. **Console logs are flat**; reconstructing causality from a wall of lines is slow and error-prone.
+
+**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.
+
+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**.
 
 ## Install
 
@@ -16,6 +28,12 @@ npm install agent-inspect
 pnpm add agent-inspect
 ```
 
+Verify the CLI is available:
+
+```bash
+npx agent-inspect --help
+```
+
 ## 60-second quickstart
 
 Create `demo.mjs`:
@@ -29,25 +47,25 @@ await inspectRun(
   "support-agent",
   async () => {
     const plan = await step("plan", async () => {
-      await delay(50);
-      return { query: "refund policy", intent: "support" };
+      await delay(40);
+      return { intent: "refund-policy", needsPolicy: true };
     });
 
-    const docs = await step.tool("search-docs", async () => {
-      await delay(75);
-      return ["Refunds are available within 30 days."];
+    const policy = await step.tool("retrieve-policy", async () => {
+      await delay(60);
+      return { text: "Refunds are available within 30 days of purchase." };
     });
 
-    return step.llm("answer", async () => {
-      await delay(100);
-      return `Based on ${docs.length} document(s), refunds are available within 30 days.`;
+    return step.llm("generate-answer", async () => {
+      await delay(80);
+      return `Policy: ${policy.text} (intent: ${plan.intent})`;
     });
   },
   { traceDir: "./.agent-inspect" }
 );
 ```
 
-Run it, then inspect it:
+Run it, then inspect the trace:
 
 ```bash
 node demo.mjs
@@ -56,488 +74,216 @@ npx agent-inspect view <run-id> --dir ./.agent-inspect
 npx agent-inspect view <run-id> --dir ./.agent-inspect --summary
 ```
 
-Simplified example output:
-
-```text
-Run run_abc123 (support-agent)
-├─ ✔ plan (50ms)
-├─ ✔ tool:search-docs (75ms)
-└─ ✔ llm:answer (100ms)
-
-Summary:
-  Steps: 3 (0 error)
-  Duration: 225ms
-```
-
-Want a runnable demo folder? See [examples/00-quickstart-demo](examples/00-quickstart-demo/README.md).
-
-## Why not just console.log?
-
-Console logs are great for quick values, but they’re flat. AgentInspect gives you:
-
-- run grouping and local trace files
-- explicit step boundaries (including nesting)
-- step types (`tool:*`, `llm:*`)
-- status + duration summaries
-- a CLI to list/view/export/diff runs
-- log ingestion workflows (`logs`, `tail`) when you already have structured logs
-
-## Inspect existing structured logs
+Full flow:
 
 ```bash
-npx agent-inspect logs ./agent.log \
-  --format json \
-  --run-id-key requestId \
-  --event-key event \
-  --timestamp-key timestamp
+npm install agent-inspect
+node demo.mjs
+npx agent-inspect list --dir ./.agent-inspect
 ```
 
-See the log-to-tree guide: [docs/LOG-TO-TREE-QUICKSTART.md](docs/LOG-TO-TREE-QUICKSTART.md).
-
-## When to use AgentInspect
-
-Use AgentInspect when:
-
-- you are building TypeScript/Node.js AI agents
-- you want local debugging before a hosted observability setup
-- console logs are too flat for multi-step execution
-- you want to inspect tool calls, LLM calls, failures, and durations locally
-- you want a lightweight CLI workflow with no account and no cloud upload
-- you want to compare two local runs
-- you want to turn structured logs into readable execution trees
-
-## When not to use AgentInspect
-
-Do not use AgentInspect as a replacement for:
-
-- production monitoring or alerting
-- hosted observability dashboards
-- long-term trace storage
-- eval dataset management
-- prompt management
-- cost analytics
-- replay/fork execution
-- vendor telemetry pipelines
+**Simplified example output** (actual CLI formatting may differ slightly):
 
-AgentInspect can complement tools like LangSmith, Langfuse, Braintrust, Phoenix/OpenInference, OpenTelemetry, New Relic, Datadog, etc. It does not replace their production/eval/dashboard workflows.
-
-## Security and privacy posture
-
-- local files only by default (no upload)
-- no vendor sinks
-- no API keys required
-- small root dependency footprint
-- traces can include **user-provided metadata**; review exports before sharing
-
-See `SECURITY.md`.
-
-## Documentation
-
-- **Getting started**: [docs/GETTING-STARTED.md](docs/GETTING-STARTED.md)
-- **API**: [docs/API.md](docs/API.md)
-- **CLI**: [docs/CLI.md](docs/CLI.md)
-- **Schema**: [docs/SCHEMA.md](docs/SCHEMA.md)
-- **Logs**: [docs/LOGS.md](docs/LOGS.md) and [docs/LOG-TO-TREE-QUICKSTART.md](docs/LOG-TO-TREE-QUICKSTART.md)
-- **Exports**: [docs/EXPORTS.md](docs/EXPORTS.md)
-- **Diff**: [docs/DIFF.md](docs/DIFF.md)
-- **Adapters**: [docs/ADAPTERS.md](docs/ADAPTERS.md)
-- **Compare with other tools**: [docs/COMPARE.md](docs/COMPARE.md)
-- **Known issues**: [docs/KNOWN-ISSUES.md](docs/KNOWN-ISSUES.md)
-- **Limitations**: [docs/LIMITATIONS.md](docs/LIMITATIONS.md)
+```text
+support-agent
+✔ plan
+✔ tool:retrieve-policy
+✔ llm:generate-answer
+```
 
-Screenshots/GIFs are planned; see [docs/SCREENSHOTS.md](docs/SCREENSHOTS.md).
+A runnable copy lives in [examples/00-quickstart-demo](examples/00-quickstart-demo/README.md).
 
-## Minimal API
+**Env-gated tracing** (eval harnesses, CI): use `maybeInspectRun` and set `AGENT_INSPECT=1` when you want a trace — otherwise no files are written.
 
 ```ts
-import { inspectRun, step } from "agent-inspect";
+import { maybeInspectRun } from "agent-inspect";
 
-await inspectRun("my-agent-run", async () => {
-  const plan = await step("plan", async () => ({ task: "research" }));
-  return step("act", async () => plan);
-});
+await maybeInspectRun("eval-case-42", async () => runAgent());
 ```
 
-## LLM and tool helpers
-
-```ts
-await step.llm("mock-gpt", async () => {
-  return planner.run();
-});
-
-await step.tool("searchHotels", async () => {
-  return searchHotels();
-});
+```bash
+AGENT_INSPECT=1 node eval-runner.mjs
 ```
 
-Helpers only label steps in the trace.
-
-They do not import or call vendor SDKs.
-
-## observe()
+## What the trace shows
 
-`observe()` wraps top-level `run`, `execute`, and `invoke`.
+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).
 
-For internal detail, add manual `step()` calls inside the agent.
-
-```ts
-import { observe } from "agent-inspect";
+## Works with structured logs you already have
 
-class MyAgent {
-  async run(input: string) {
-    return `ok: ${input}`;
-  }
-}
+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.
 
-const agent = observe(new MyAgent());
-await agent.run("hello");
+```bash
+npx agent-inspect logs ./agent.log \
+  --format json \
+  --run-id-key requestId \
+  --event-key event \
+  --timestamp-key timestamp
 ```
 
-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
+With a reusable ingest config:
 
-```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);
+```bash
+npx agent-inspect logs ./agent.log --config agent-inspect.logs.json
 ```
 
-Expected tree:
+- **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.
 
-```text
-hotel-booking
-✔ search-hotels
-✔ check-availability
-✔ finalize-booking
-```
+More detail: [docs/LOGS.md](docs/LOGS.md) · [docs/LOG-TO-TREE-QUICKSTART.md](docs/LOG-TO-TREE-QUICKSTART.md).
 
-### Example 2: Nested LLM and tool steps
+## CLI at a glance
 
-```ts
-import { inspectRun, step } from "agent-inspect";
+| 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) |
 
-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.";
-    });
+Full flags and behavior: [docs/CLI.md](docs/CLI.md).
 
-    return step("parse-plan", async () => {
-      return draft.replace("Plan: ", "").split(", ");
-    });
-  });
+## Real-world workflows
 
-  const hotels = await step.tool("searchHotels", async () => {
-    return [{ id: "h1", city: "Kyoto" }];
-  });
+- 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.
 
-  return step("finalize", async () => {
-    return { plan, hotel: hotels[0] };
-  });
-});
-```
+## What v1.0 stabilizes
 
-Expected tree:
+**agent-inspect 1.0** stabilizes the **local debugging foundation**:
 
-```text
-trip-planner
-✔ plan-trip
-  ✔ llm:mock-gpt
-  ✔ parse-plan
-✔ tool:searchHotels
-✔ finalize
-```
+- 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`**
 
-### Example 3: Error handling
+**Stable APIs:** `inspectRun()`, `maybeInspectRun()`, `step()`, `step.llm()`, `step.tool()`, `observe()`.
 
-```ts
-import { inspectRun, step } from "agent-inspect";
+Pass `enabled: false` to `inspectRun` for a no-trace passthrough. Use `maybeInspectRun` with `AGENT_INSPECT=1` (or `true` / `yes` / `on` / `enabled`) to toggle tracing in eval or CI jobs — see [docs/API.md](docs/API.md).
 
-try {
-  await inspectRun("pricing-flow", async () => {
-    await step("load-catalog", async () => ["sku-a", "sku-b"]);
+**Stable CLI workflows:** `agent-inspect list`, `agent-inspect view`, `agent-inspect clean`.
 
-    await step("fetch-dynamic-pricing", async () => {
-      throw new Error("Pricing API timeout");
-    });
+**Also included in 1.0** as local-first extensions:
 
-    await step("apply-discount", async () => {
-      return "this step will not run";
-    });
-  });
-} catch (error) {
-  console.error("Original error still propagated:", error);
-}
-```
-
-agent-inspect records the failed step, writes it to the trace file, and still rethrows the original error.
+- 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
 
-### Example 4: `observe()` wrapper
-
-```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";
-    });
+**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.
 
-    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?");
-```
+## Optional packages
 
-`observe()` wraps top-level `run`, `execute`, and `invoke` methods. For internal detail, add manual `step()` calls inside the agent.
+### LangChain callback adapter (`@agent-inspect/langchain`)
 
-## LangChain adapter (experimental)
-
-Install:
+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
 pnpm add agent-inspect @agent-inspect/langchain @langchain/core
 ```
 
-`@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",
+  runName: "my-run",
   capture: "metadata-only",
 });
 
-await agent.invoke(input, {
-  callbacks: [callback],
-});
-
+await agent.invoke(input, { callbacks: [callback] });
 const events = callback.getEvents();
 ```
 
-Behavior:
-
-- **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.
-- Events are collected **in memory** only (`getEvents()` / `clear()`). **No trace-file persistence** for adapter events yet; they are **not** written into the manual JSONL trace format.
-
-The LangChain adapter API remains **experimental** even though the core AgentInspect tracing API is stable in 1.0. See [examples/08-langchain-adapter](examples/08-langchain-adapter).
-
-## CLI
-
-List recent runs:
-
-```bash
-npx agent-inspect list
-```
-
-Common filters:
-
-```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
-```
-
-View a run:
-
-```bash
-npx agent-inspect view run_abc123
-```
-
-Alternate view modes:
-
-```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
-```
-
-Safely clean up old traces (recommended: start with `--dry-run`):
-
-```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
-```
-
-Safety notes:
-
-- `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`.
-
-Inspect structured logs:
-
-```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:
+See [examples/08-langchain-adapter](examples/08-langchain-adapter/README.md) and [docs/ADAPTERS.md](docs/ADAPTERS.md).
 
-- 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).
+### TUI viewer (`@agent-inspect/tui`)
 
-Live tail structured logs:
+Optional **Ink/React** package, installed separately. Use with an interactive terminal:
 
 ```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
+pnpm add agent-inspect @agent-inspect/tui
+npx agent-inspect view <run-id> --tui
 ```
 
-Use a custom trace directory:
+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
-npx agent-inspect list --dir ./traces
-npx agent-inspect view run_abc123 --dir ./traces
-```
-
-By default, traces are stored under `~/.agent-inspect/runs`.
-
-You can also set a default trace directory with:
+## Examples and recipes
 
-```bash
-AGENT_INSPECT_TRACE_DIR=./traces npx agent-inspect list
-```
-
-For local repo development after `pnpm build`:
-
-```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
-```
+| 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 |
 
-Example event shape:
+**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).
 
-```json
-{"schemaVersion":"0.1","event":"step_started","name":"search-hotels","type":"logic"}
-```
-
-You can inspect traces with standard tools:
-
-```bash
-cat ~/.agent-inspect/runs/run_abc123.jsonl
-cat ~/.agent-inspect/runs/run_abc123.jsonl | jq
-```
-
-## Runnable examples
-
-The repo includes runnable examples for manual tracing, log-to-tree, and the optional LangChain adapter:
-
-- `examples/00-quickstart-demo` — minimal install-and-try demo
-- `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` — structured log-to-tree example (`agent-inspect logs`, `tail`)
-- `examples/08-langchain-adapter` — optional LangChain callback adapter (`@agent-inspect/langchain`), provider-free simulated lifecycle (install from repo root; see example README)
-
-Run one locally:
-
-```bash
-pnpm build
-cd examples/01-basic
-pnpm install
-pnpm start
-```
+## Security and privacy posture
 
-Then inspect traces:
+- **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).
 
-```bash
-node ../../packages/cli/dist/index.cjs list
-node ../../packages/cli/dist/index.cjs view run_abc123
-```
+See [SECURITY.md](SECURITY.md).
 
-Do not commit `node_modules`. Example dependencies are installed locally when you run `pnpm install`.
+## agent-inspect comparison
 
-Supporting material:
+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.
 
-- [examples/README.md](examples/README.md)
+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`.