agent-inspect 1.0.1 → 1.0.2

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 1.0.2
+
+### Patch Changes
+
+- c72f044: docs: polish README
+
 ## 1.0.1
 
 ### Patch Changes

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,33 +74,32 @@ npx agent-inspect view <run-id> --dir ./.agent-inspect
 npx agent-inspect view <run-id> --dir ./.agent-inspect --summary
 ```
 
-Simplified example output:
+Full flow:
+
+```bash
+npm install agent-inspect
+node demo.mjs
+npx agent-inspect list --dir ./.agent-inspect
+```
+
+**Simplified example output** (actual CLI formatting may differ slightly):
 
 ```text
-Run run_abc123 (support-agent)
-├─ ✔ plan (50ms)
-├─ ✔ tool:search-docs (75ms)
-└─ ✔ llm:answer (100ms)
-
-Summary:
-  Steps: 3 (0 error)
-  Duration: 225ms
+support-agent
+✔ plan
+✔ tool:retrieve-policy
+✔ llm:generate-answer
 ```
 
-Want a runnable demo folder? See [examples/00-quickstart-demo](examples/00-quickstart-demo/README.md).
+A runnable copy lives in [examples/00-quickstart-demo](examples/00-quickstart-demo/README.md).
 
-## Why not just console.log?
+## What the trace shows
 
-Console logs are great for quick values, but they’re flat. AgentInspect gives you:
+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).
 
-- 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
+## Works with structured logs you already have
 
-## Inspect existing structured logs
+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 logs ./agent.log \
@@ -92,452 +109,167 @@ npx agent-inspect logs ./agent.log \
   --timestamp-key timestamp
 ```
 
-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
-
-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)
-
-Screenshots/GIFs are planned; see [docs/SCREENSHOTS.md](docs/SCREENSHOTS.md).
-
-## Minimal API
-
-```ts
-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);
-});
-```
-
-## 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";
+With a reusable ingest config:
 
-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
+```bash
+npx agent-inspect logs ./agent.log --config agent-inspect.logs.json
 ```
 
-### Example 2: Nested LLM and tool steps
+- **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.
 
-```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.";
-    });
-
-    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] };
-  });
-});
-```
+More detail: [docs/LOGS.md](docs/LOGS.md) · [docs/LOG-TO-TREE-QUICKSTART.md](docs/LOG-TO-TREE-QUICKSTART.md).
 
-Expected tree:
+## CLI at a glance
 
-```text
-trip-planner
-✔ plan-trip
-  ✔ llm:mock-gpt
-  ✔ parse-plan
-✔ tool:searchHotels
-✔ finalize
-```
+| 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) |
 
-### Example 3: Error handling
+Full flags and behavior: [docs/CLI.md](docs/CLI.md).
 
-```ts
-import { inspectRun, step } from "agent-inspect";
+## Real-world workflows
 
-try {
-  await inspectRun("pricing-flow", async () => {
-    await step("load-catalog", async () => ["sku-a", "sku-b"]);
+- 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.
 
-    await step("fetch-dynamic-pricing", async () => {
-      throw new Error("Pricing API timeout");
-    });
+## What v1.0 stabilizes
 
-    await step("apply-discount", async () => {
-      return "this step will not run";
-    });
-  });
-} catch (error) {
-  console.error("Original error still propagated:", error);
-}
-```
+**agent-inspect 1.0** stabilizes the **local debugging foundation**:
 
-agent-inspect records the failed step, writes it to the trace file, and still rethrows the original error.
+- 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 4: `observe()` wrapper
+**Stable APIs:** `inspectRun()`, `step()`, `step.llm()`, `step.tool()`, `observe()`.
 
-```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";
-    });
+**Stable CLI workflows:** `agent-inspect list`, `agent-inspect view`, `agent-inspect clean`.
 
-    const articles = await step.tool("retrieveArticles", async () => {
-      return ["Reset your password from the login page."];
-    });
+**Also included in 1.0** as local-first extensions:
 
-    return step.llm("mock-support-model", async () => {
-      return `Category: ${category}. ${articles[0]}`;
-    });
-  }
-}
+- 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
 
-const agent = observe(new CustomerSupportAgent());
-await agent.run("How do I reset my password?");
-```
+**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.
 
-`observe()` wraps top-level `run`, `execute`, and `invoke` methods. For internal detail, add manual `step()` calls inside the agent.
+## Optional packages
 
-## LangChain adapter (experimental)
+### LangChain callback adapter (`@agent-inspect/langchain`)
 
-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`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-inspect",
-  "version": "1.0.1",
+  "version": "1.0.2",
   "license": "MIT",
   "type": "module",
   "description": "Local-first execution-tree debugger for TypeScript AI agents",

package/docs/MIGRATION.md

@@ -1,109 +0,0 @@
-# Migration guide (to AgentInspect 1.0)
-
-This guide summarizes how to move from early AgentInspect MVP usage to **AgentInspect 1.0**.
-
-AgentInspect remains local-first: it does not introduce any network upload or vendor sink workflows.
-
-## Scope
-
-Covered:
-
-- manual tracing (`inspectRun`, `step`, `observe`)
-- trace directory behavior
-- CLI commands (`list`, `view`, `clean`, `logs`, `tail`, `export`, `diff`)
-- optional packages (`@agent-inspect/langchain`, `@agent-inspect/tui`)
-- schema compatibility guarantees
-
-Not covered:
-
-- publish/version bump workflows (see `docs-local/RELEASE-CHECKLIST.md`)
-- vendor sinks (not implemented)
-- replay (not implemented)
-- cost engine (not implemented)
-
-## Manual tracing API
-
-If you were using:
-
-```ts
-import { inspectRun, step } from "agent-inspect";
-```
-
-that remains the recommended stable path. AgentInspect 1.0 is specifically about keeping these entry points compatible.
-
-### Event names and failure representation
-
-Manual JSONL event names remain stable:
-
-- `run_started`
-- `run_completed`
-- `step_started`
-- `step_completed`
-
-There is **no `step_failed` event**. Step failures are represented as:
-
-- `step_completed` with `status: "error"`
-
-Existing `schemaVersion: "0.1"` traces remain readable. No migration command is required.
-
-## Trace directory behavior
-
-- `AGENT_INSPECT_TRACE_DIR` is supported.
-- When unset, AgentInspect uses its default local directory (see `docs/CLI.md` and `docs/API.md`).
-- Trace files are JSONL and are not automatically rewritten.
-
-## CLI changes and additive commands
-
-Manual inspection commands (`list`, `view`) are stable and local-only.
-
-The following commands are additive workflows that remain local-only:
-
-- `logs`: parse structured logs into normalized trees
-- `tail`: live-tail structured logs in the terminal
-- `export`: export a manual trace as Markdown/HTML/OpenInference-compatible JSON/OTLP JSON (local-only)
-- `diff`: compare two manual traces (local, read-only)
-
-### `clean` is safety-critical
-
-`clean` verifies traces before deletion using conservative heuristics. If a file cannot be verified as an AgentInspect trace, it is skipped.
-
-## Logs and tail
-
-- JSON logs are first-class.
-- log4js parsing is best-effort.
-- No JS object literal parsing or `eval`.
-- Redaction is applied to log-derived attributes based on config/default rules.
-
-## Export and share safety
-
-- Exports are **generated locally** and do not upload anywhere.
-- Exporters default to **redacted** and **bounded** attribute previews.
-- Always review exports before sharing.
-
-## Diff and compare
-
-- Diff compares two existing local traces.
-- Diff does not rerun agents, mutate trace files, or call an LLM.
-
-## Optional LangChain adapter
-
-`@agent-inspect/langchain` is optional and separate from core. It uses `@langchain/core` as a **peer dependency**.
-
-## Optional TUI
-
-`@agent-inspect/tui` is optional and separate from core. It contains `ink`/`react` dependencies so the main `agent-inspect` install remains lean.
-
-## Breaking changes
-
-This stabilization effort aims to avoid breaking changes. If a breaking change is ever required:
-
-- it requires a major version
-- it must preserve trace readability where possible
-- it must be explicitly documented
-
-## Known non-migrations
-
-- No vendor sink migration exists because there are **no vendor sinks** in core.
-- No replay migration exists because replay is **not implemented**.
-- No cost engine migration exists because cost calculation is **not implemented**.
-