agent-inspect 3.5.3 → 3.5.4

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 3.5.4
+
+### Patch Changes
+
+- 1ffe989: v3.5.4 README adoption polish: centered brand header, product-loop visual, npm package files for linked docs/assets. Docs-only; no runtime API changes.
+
 ## 3.5.3
 
 ### Patch Changes
@@ -50,9 +56,9 @@
 
 ## Unreleased
 
-Post-v3.5 adoption polish (docs, package READMEs, npm presentation). No runtime feature changes planned without a new RFC.
+README adoption polish (brand header, product-loop visual, npm link hygiene). Docs-only; no runtime feature changes.
 
-See [docs/implementation/release-trains/V3.5.X-ADOPTION-POLISH-PLAN.md](docs/implementation/release-trains/V3.5.X-ADOPTION-POLISH-PLAN.md).
+See [docs/implementation/reviews/README-ADOPTION-POLISH-REVIEW.md](docs/implementation/reviews/README-ADOPTION-POLISH-REVIEW.md).
 
 ---
 

package/README.md

@@ -1,11 +1,37 @@
-# agent-inspect
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="docs/assets/agent-inspect-logo-dark.svg">
+    <img src="docs/assets/agent-inspect-logo.svg" width="240" alt="AgentInspect">
+  </picture>
+</p>
 
-**Local-first TypeScript toolkit: trace what happened, check what should have happened, redact what must not leave your machine.**
+<h1 align="center">agent-inspect</h1>
 
-No account · no upload · no hosted dashboard · metadata-only by default
+<p align="center">
+  <strong>Trace, check, and safely share TypeScript AI-agent runs locally.</strong>
+</p>
 
-[![npm version](https://img.shields.io/npm/v/agent-inspect.svg)](https://www.npmjs.com/package/agent-inspect)
-[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+<p align="center">
+  <sub>No account · no upload · no hosted dashboard · metadata-only by default</sub>
+</p>
+
+<p align="center">
+  <a href="https://agentinspect.vercel.app/">Website</a> ·
+  <a href="https://agentinspect.vercel.app/docs/">Docs</a> ·
+  <a href="https://www.npmjs.com/package/agent-inspect">npm</a> ·
+  <a href="https://github.com/rajudandigam/agent-inspect">GitHub</a>
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/agent-inspect"><img src="https://img.shields.io/npm/v/agent-inspect.svg" alt="npm version"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-blue.svg" alt="MIT license"></a>
+  <a href="package.json"><img src="https://img.shields.io/badge/node-%3E%3D20-brightgreen" alt="Node.js >= 20"></a>
+  <a href="https://www.typescriptlang.org/"><img src="https://img.shields.io/badge/TypeScript-strict-3178c6" alt="TypeScript"></a>
+</p>
+
+agent-inspect turns AI-agent runs into readable **local execution trees**: framework events, observed objects, tool calls, LLM steps, retries, failures, timings, sessions, and CI artifacts — without an account, collector, or hosted dashboard.
+
+**Default loop:** capture locally → inspect / report / diff → check in CI → redact before sharing.
 
 ```bash
 npm install agent-inspect
@@ -22,46 +48,56 @@ npx agent-inspect report <run-id> --dir .agent-inspect
 npx agent-inspect verify-safe --dir .agent-inspect
 ```
 
-**North star:** install → one trace → one failure check → one share-safe artifact in under five minutes. See [First trace in 5 minutes](docs/FIRST-TRACE-IN-5-MINUTES.md).
+Install → one trace → one failure check → one share-safe artifact in under five minutes.
+Guide: [First trace in 5 minutes](https://agentinspect.vercel.app/docs/getting-started/) · [repo](docs/FIRST-TRACE-IN-5-MINUTES.md)
+
+<p align="center">
+  <img src="docs/assets/readme-product-loop.svg" alt="Capture, inspect, check, redact — local JSONL only" width="720">
+</p>
 
 ## Choose your path
 
-| Path | When | Start here |
-| ---- | ---- | ---------- |
+| Path | Use when | Start |
+| ---- | -------- | ----- |
 | **AI SDK** | Vercel AI SDK `generateText` / `streamText` | [`@agent-inspect/ai-sdk`](packages/ai-sdk/README.md) · [guide](docs/AI-SDK-ADOPTION.md) |
-| **OpenAI Agents** | OpenAI Agents JS local tracing | [`@agent-inspect/openai-agents`](packages/openai-agents/README.md) · [guide](docs/OPENAI-AGENTS-LOCAL.md) |
-| **LangChain** | Callback adapter, LangGraph-via-LangChain | [`@agent-inspect/langchain`](packages/langchain/README.md) |
-| **Observe** | Existing class with `run` / `execute` | [Getting started § observe](docs/GETTING-STARTED.md) |
-| **Manual** | Custom control flow | `inspectRun` + `step` in [API](docs/API.md) |
+| **OpenAI Agents** | OpenAI Agents JS | [`@agent-inspect/openai-agents`](packages/openai-agents/README.md) · [guide](docs/OPENAI-AGENTS-LOCAL.md) |
+| **LangChain** | Callbacks / LangGraph-via-LangChain | [`@agent-inspect/langchain`](packages/langchain/README.md) |
+| **Observe** | Object/class with `run` / `execute` / `invoke` | [Getting started](docs/GETTING-STARTED.md) |
+| **Manual** | Custom spans and nesting | `inspectRun` + `step` in [API](docs/API.md) |
 | **Logs** | Structured logs already emitted | [Log-to-tree](docs/LOG-TO-TREE-QUICKSTART.md) |
-| **CI / tests** | Failed test artifacts | [`@agent-inspect/vitest`](packages/vitest/README.md) · [`@agent-inspect/jest`](packages/jest/README.md) |
-| **Real projects** | Fixture harness | [`@agent-inspect/harness`](packages/harness/README.md) |
+| **CI / tests** | Failed-test artifacts | [`@agent-inspect/vitest`](packages/vitest/README.md) · [`@agent-inspect/jest`](packages/jest/README.md) |
+| **Real projects** | Fixture runner / bootstrap | [`@agent-inspect/harness`](packages/harness/README.md) · [NestJS](docs/NESTJS.md) |
 
 Blessed starters (no API keys): [examples/starters](https://github.com/rajudandigam/agent-inspect/tree/main/examples/starters)
 
 ## What it helps with
 
-- **Wrong tool call** — see tool steps, args metadata, and parent run in the tree
-- **Baseline vs candidate** — `diff` two runs locally
-- **Eval / test failures** — `check`, `eval`, Vitest/Jest reporters
-- **PR artifacts** — [CI artifacts](docs/CI-ARTIFACTS.md) + `redact --profile share`
+- **Wrong tool call** — tool steps, args metadata, and parent run in one tree
+- **Failed eval / test** — `check`, `eval`, Vitest/Jest reporters on failure
+- **Baseline vs candidate** — local `diff` of two runs
+- **PR trace artifact** — [CI artifacts](docs/CI-ARTIFACTS.md) + `redact --profile share`
+- **Safe incident handoff** — [safe sharing](https://agentinspect.vercel.app/docs/safe-sharing/) before Slack or GitHub
 - **Multi-agent / sessions** — `sessions`, `search`, handoff metadata
-- **MCP tools** — [`@agent-inspect/mcp`](packages/mcp/README.md) client tracing
-- **VS Code** — in-repo extension (`packages/vscode`); [dev guide](docs/VSCODE.md) — Marketplace listing manual
+- **MCP tool calls** — [`@agent-inspect/mcp`](packages/mcp/README.md) client tracing
+- **VS Code review** — in-repo extension ([dev guide](docs/VSCODE.md); Marketplace not published yet)
+- **Existing logs** — parse structured logs when you cannot instrument
 
 ## Real-world scenarios
 
-| Scenario | Doc |
-| -------- | --- |
-| Local debugging | [USE-CASES.md](docs/USE-CASES.md) |
-| CI failure review | [USE-CASES.md](docs/USE-CASES.md) § CI trace artifact |
-| Team adoption | [TEAM-WORKFLOWS.md](docs/TEAM-WORKFLOWS.md) · [Design partners](docs/DESIGN-PARTNER-GUIDE.md) |
+| Scenario | Where to start |
+| -------- | -------------- |
+| Local debugging | [Use cases](docs/USE-CASES.md) · [broken-agent starter](https://github.com/rajudandigam/agent-inspect/tree/main/examples/starters/broken-agent-debugging) |
+| CI failure review | [CI artifacts](docs/CI-ARTIFACTS.md) · [ci-eval-redact](https://github.com/rajudandigam/agent-inspect/tree/main/examples/starters/ci-eval-redact) |
+| Team adoption | [Team workflows](docs/TEAM-WORKFLOWS.md) · [Design partners](docs/DESIGN-PARTNER-GUIDE.md) |
+| Safe sharing | [Safe sharing](https://agentinspect.vercel.app/docs/safe-sharing/) · [repo](docs/SAFE-TRACE-SHARING.md) |
+| Framework-native tracing | [Adapters](docs/ADAPTERS.md) · package READMEs above |
+| Design partner trial | [Design partner guide](docs/DESIGN-PARTNER-GUIDE.md) · [Demo script](docs/DEMO-SCRIPT.md) |
 
 ## Package map
 
 | Package | Purpose |
 | ------- | ------- |
-| [`agent-inspect`](https://www.npmjs.com/package/agent-inspect) | Core + CLI |
+| [`agent-inspect`](https://www.npmjs.com/package/agent-inspect) | Core APIs + CLI |
 | [`@agent-inspect/ai-sdk`](packages/ai-sdk/README.md) | AI SDK telemetry |
 | [`@agent-inspect/openai-agents`](packages/openai-agents/README.md) | OpenAI Agents processor |
 | [`@agent-inspect/langchain`](packages/langchain/README.md) | LangChain callbacks |
@@ -73,45 +109,51 @@ Blessed starters (no API keys): [examples/starters](https://github.com/rajudandi
 | [`@agent-inspect/mcp`](packages/mcp/README.md) | MCP client tracing |
 | [`@agent-inspect/mcp-server`](packages/mcp-server/README.md) | Read-only trace MCP server |
 | [`@agent-inspect/guardrails`](packages/guardrails/README.md) | Deterministic guardrail rules |
-| [`@agent-inspect/circuit`](packages/circuit/README.md) | Loop/retry/timeout analyzers |
+| [`@agent-inspect/circuit`](packages/circuit/README.md) | Loop / retry / timeout analyzers |
 | [`@agent-inspect/viewer`](packages/viewer/README.md) | Localhost viewer |
 | [`@agent-inspect/adapter-sdk`](packages/adapter-sdk/README.md) | Third-party adapters |
 | [`@agent-inspect/tui`](packages/tui/README.md) | Optional terminal UI |
-| `agent-inspect-vscode` | VS Code extension (in-repo, not on Marketplace yet) |
+| `agent-inspect-vscode` | VS Code extension (in-repo; not on Marketplace yet) |
 
 ## Safety model
 
-- Traces are **local JSONL files** under `.agent-inspect/` (or `AGENT_INSPECT_TRACE_DIR`)
+- Traces are **local JSONL** under `.agent-inspect/` (or `AGENT_INSPECT_TRACE_DIR`)
 - **Metadata-only by default** — no raw prompts/outputs unless you opt in
 - **No hidden upload** — AgentInspect does not send traces to the cloud
-- **Redaction profiles** — `local` / `share` / `strict` via [`@agent-inspect/redact`](packages/redact/README.md) or CLI
+- **Redaction profiles** — `local` / `share` / `strict` via CLI or [`@agent-inspect/redact`](packages/redact/README.md)
 - **`scan` / `verify-safe`** — check artifacts before sharing
-- **Not** a chain-of-thought recorder or compliance engine
+- **Not** a chain-of-thought recorder or compliance engine — review exports before posting
 
-Details: [Safe trace sharing](docs/SAFE-TRACE-SHARING.md) · [Security](SECURITY.md)
+Details: [Safe sharing](https://agentinspect.vercel.app/docs/safe-sharing/) · [repo](docs/SAFE-TRACE-SHARING.md) · [Security](SECURITY.md)
 
 ## Documentation
 
-| Start | Reference | Adoption |
-| ----- | --------- | -------- |
-| [Getting started](docs/GETTING-STARTED.md) | [API](docs/API.md) | [Adoption](docs/ADOPTION.md) |
-| [First trace in 5 min](docs/FIRST-TRACE-IN-5-MINUTES.md) | [CLI](docs/CLI.md) | [Demo script](docs/DEMO-SCRIPT.md) |
-| [Use cases](docs/USE-CASES.md) | [Adapters](docs/ADAPTERS.md) | [Compare](docs/COMPARE.md) |
-| [Examples](https://github.com/rajudandigam/agent-inspect/tree/main/examples) | [Performance](docs/PERFORMANCE.md) | [Pitch](docs/PITCH.md) |
+| | Website | Repo |
+| - | ------- | ---- |
+| Getting started | [docs/getting-started](https://agentinspect.vercel.app/docs/getting-started/) | [GETTING-STARTED.md](docs/GETTING-STARTED.md) |
+| Safe sharing | [docs/safe-sharing](https://agentinspect.vercel.app/docs/safe-sharing/) | [SAFE-TRACE-SHARING.md](docs/SAFE-TRACE-SHARING.md) |
+| Compare | [docs/compare](https://agentinspect.vercel.app/docs/compare/) | [COMPARE.md](docs/COMPARE.md) |
+| API / CLI | — | [API.md](docs/API.md) · [CLI.md](docs/CLI.md) |
+| Adoption | — | [ADOPTION.md](docs/ADOPTION.md) · [USE-CASES.md](docs/USE-CASES.md) |
+| Technical guide | — | [TECHNICAL-GUIDE.md](docs/TECHNICAL-GUIDE.md) |
+| Examples | — | [starters](https://github.com/rajudandigam/agent-inspect/tree/main/examples/starters) |
+| Visual demos | — | [SCREENSHOTS.md](docs/SCREENSHOTS.md) |
 
-Full index: [docs/README.md](docs/README.md) · Visual demos: [SCREENSHOTS.md](docs/SCREENSHOTS.md)
+Full index: [docs/README.md](docs/README.md)
 
 ## What AgentInspect is not
 
 - Hosted SaaS or dashboard product
 - Production APM replacement (use LangSmith, Langfuse, OTel, etc. alongside)
 - Eval dataset platform or LLM-as-judge service
-- Prompt registry or pricing engine
+- Prompt registry or provider pricing engine
 - Default telemetry uploader or replay engine
 
+See [Compare](https://agentinspect.vercel.app/docs/compare/).
+
 ## Install details
 
-Current release: **3.5.2** (sixteen linked npm packages). Persisted trace schema **1.0**.
+Current release: **3.5.3** (sixteen linked npm packages). Persisted trace schema **1.0**. Requires **Node.js >= 20**.
 
 ```bash
 pnpm add agent-inspect

package/docs/ADOPTION.md

@@ -2,6 +2,8 @@
 
 AgentInspect is **local-first**: traces stay on disk, checks run in CI, and sharing is opt-in via redaction. This guide is the blessed path from zero to a working team workflow.
 
+**Website:** [https://agentinspect.vercel.app/](https://agentinspect.vercel.app/) · **Docs:** [https://agentinspect.vercel.app/docs/](https://agentinspect.vercel.app/docs/) · **Getting started:** [https://agentinspect.vercel.app/docs/getting-started/](https://agentinspect.vercel.app/docs/getting-started/)
+
 ## Who this is for
 
 - TypeScript/Node teams shipping AI agents (not toy demos)
@@ -10,7 +12,7 @@ AgentInspect is **local-first**: traces stay on disk, checks run in CI, and shar
 
 ## 5-minute path
 
-See [FIRST-TRACE-IN-5-MINUTES.md](./FIRST-TRACE-IN-5-MINUTES.md).
+See [FIRST-TRACE-IN-5-MINUTES.md](./FIRST-TRACE-IN-5-MINUTES.md) or the [docs site getting started](https://agentinspect.vercel.app/docs/getting-started/).
 
 ```bash
 npm install agent-inspect

package/docs/AI-SDK-ADOPTION.md

@@ -0,0 +1,109 @@
+# AI SDK adoption guide
+
+Blessed path for **Vercel AI SDK** + AgentInspect — local traces only, metadata-first by default.
+
+## Install
+
+```bash
+npm install agent-inspect @agent-inspect/ai-sdk ai
+```
+
+Or bootstrap a project:
+
+```bash
+npx agent-inspect init --framework ai-sdk
+```
+
+## Minimal `generateText`
+
+```ts
+import { generateText } from "ai";
+import { agentInspect } from "@agent-inspect/ai-sdk";
+
+await generateText({
+  model: yourModel,
+  prompt: "Hello",
+  experimental_telemetry: {
+    isEnabled: true,
+    recordInputs: false,
+    recordOutputs: false,
+    integrations: [
+      agentInspect({
+        traceDir: ".agent-inspect",
+        runName: "support-agent",
+        capture: "metadata-only",
+      }),
+    ],
+  },
+});
+```
+
+## `streamText` (metadata-only)
+
+```ts
+import { streamText } from "ai";
+import { agentInspect } from "@agent-inspect/ai-sdk";
+
+const result = streamText({
+  model: yourModel,
+  prompt: "Hello",
+  experimental_telemetry: {
+    isEnabled: true,
+    recordInputs: false,
+    recordOutputs: false,
+    integrations: [
+      agentInspect({
+        traceDir: ".agent-inspect",
+        runName: "stream-demo",
+        capture: "metadata-only",
+      }),
+    ],
+  },
+});
+
+for await (const _chunk of result.textStream) {
+  // consume stream
+}
+```
+
+Streaming lifecycle metadata is captured; raw token streams are not persisted by default.
+
+## Tool calls
+
+Tool spans appear when the model invokes tools. Keep `recordInputs` / `recordOutputs` false unless you explicitly accept content capture risk.
+
+## Next.js route handler
+
+See [examples/recipes/ai-sdk-next-route](../../examples/recipes/ai-sdk-next-route/) — one `agentInspect()` integration per request, no network, metadata-only defaults.
+
+## Privacy controls
+
+| Setting | Required default | Why |
+| ------- | ---------------- | --- |
+| `recordInputs: false` | yes | Prevents AI SDK from recording prompts into telemetry payloads |
+| `recordOutputs: false` | yes | Prevents model output capture in telemetry |
+| `capture: "metadata-only"` | yes (adapter) | AgentInspect adapter redacts/bounds persisted fields |
+
+## Inspect locally
+
+```bash
+npx agent-inspect list --dir .agent-inspect
+npx agent-inspect open .agent-inspect/<run>.jsonl
+npx agent-inspect check .agent-inspect/<run>.jsonl
+```
+
+## Troubleshooting
+
+| Symptom | Fix |
+| ------- | --- |
+| No trace file | Ensure `experimental_telemetry.isEnabled: true` and integrations include `agentInspect()` |
+| Empty trace | Confirm `AGENT_INSPECT` is not `0` |
+| Prompts in trace | Set `recordInputs: false` and `recordOutputs: false` on the AI SDK call |
+| Wrong directory | Pass `traceDir` to `agentInspect()` or set `AGENT_INSPECT_TRACE_DIR` |
+
+## Recipes (no network)
+
+- [ai-sdk-local-telemetry](../../examples/recipes/ai-sdk-local-telemetry/)
+- [ai-sdk-next-route](../../examples/recipes/ai-sdk-next-route/)
+
+See also [ADAPTERS.md](./ADAPTERS.md) and [ADAPTER-CONFORMANCE.md](./ADAPTER-CONFORMANCE.md).

package/docs/ARCHITECTURE.md

@@ -1,5 +1,7 @@
 ## Architecture
 
+> **Adoption-focused overview:** see [TECHNICAL-GUIDE.md](./TECHNICAL-GUIDE.md) for a comprehensive technical guide (v3.5.3) suitable for blogs and outreach.
+
 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.
 
 ### Package layout

package/docs/CI-ARTIFACTS.md

@@ -1,5 +1,7 @@
 # CI trace artifacts
 
+**Docs site:** [https://agentinspect.vercel.app/docs/ci/](https://agentinspect.vercel.app/docs/ci/)
+
 AgentInspect helps you **write and export traces locally** in CI. Uploading artifacts is done by **your CI platform** (e.g. GitHub Actions `upload-artifact`) — AgentInspect does not upload anywhere.
 
 ## Quick pattern

package/docs/COMPARE.md

@@ -2,6 +2,8 @@
 
 AgentInspect is a local-first execution-tree debugger for TypeScript AI agents. It’s designed for inner-loop debugging, deterministic local eval heuristics, redaction, and quick inspection — not as a replacement for hosted observability, dataset evaluation, or production monitoring platforms.
 
+**Docs site:** [https://agentinspect.vercel.app/docs/compare/](https://agentinspect.vercel.app/docs/compare/)
+
 ## AgentInspect vs console.log
 
 - **console.log is flat**: logs are a stream of lines without run grouping or step boundaries.

package/docs/DEMO-SCRIPT.md

@@ -0,0 +1,87 @@
+# Live demo script (~3 minutes)
+
+**Audience:** TypeScript developers debugging AI agents.  
+**Prereqs:** Node 20+. Consumers: `npm install agent-inspect`. Monorepo: `pnpm build` at repo root.  
+**Website:** [https://agentinspect.vercel.app/](https://agentinspect.vercel.app/)
+
+**Blessed demo starter:** [broken-agent-debugging](../examples/starters/broken-agent-debugging/) — intentional tool failure, no API keys.
+
+## Setup (before the call)
+
+```bash
+cd examples/starters/broken-agent-debugging
+pnpm install && pnpm start
+npx agent-inspect list --dir .agent-inspect
+```
+
+Copy a `<run-id>` for beats below.
+
+## Beat 1 — Problem (30s)
+
+"Console logs are flat. When an agent picks the wrong tool or a step throws, you can't see parent/child relationships or which step failed first."
+
+## Beat 2 — Capture (45s)
+
+```bash
+pnpm start                    # writes failing trace to .agent-inspect/
+npx agent-inspect list --dir .agent-inspect
+```
+
+Point out: run id, status, duration — **no upload**, metadata-only by default.
+
+## Beat 3 — Inspect (45s)
+
+```bash
+npx agent-inspect report <run-id> --dir .agent-inspect
+npx agent-inspect view <run-id> --dir .agent-inspect
+npx agent-inspect timeline <run-id> --dir .agent-inspect
+```
+
+Optional: `npx agent-inspect serve --dir .agent-inspect` for browser viewer.
+
+## Beat 4 — Verify (30s)
+
+```bash
+npx agent-inspect check .agent-inspect/*.jsonl --require-completed
+```
+
+Mention `--detect-stalls` and `--max-step-duration 30s` for long-running agents.
+
+## Beat 5 — Share safely (30s)
+
+```bash
+npx agent-inspect redact .agent-inspect/*.jsonl --profile share -o safe.jsonl
+npx agent-inspect verify-safe safe.jsonl
+```
+
+"Redacted copy is safe to attach to a GitHub issue or Slack."
+
+## Beat 6 — Fix and diff (optional, 30s)
+
+```bash
+pnpm run fixed
+npx agent-inspect diff .agent-inspect/<broken-run>.jsonl .agent-inspect/<fixed-run>.jsonl
+```
+
+## Beat 7 — Close (15s)
+
+"Starters for AI SDK, OpenAI Agents, LangChain, CI, and NestJS harness are in `examples/starters/`. Fresh repos: `npx agent-inspect init --yes`."
+
+## Alternative opener (zero clone)
+
+```bash
+npm install agent-inspect
+npx agent-inspect init --yes
+node examples/agent-inspect-demo.mjs
+npx agent-inspect list --dir .agent-inspect
+```
+
+See [FIRST-TRACE-IN-5-MINUTES.md](./FIRST-TRACE-IN-5-MINUTES.md).
+
+## Optional beats
+
+- **VS Code:** F5 from `packages/vscode` (dev host) — Marketplace listing pending
+- **Doctor:** `npx agent-inspect doctor` when onboarding fails
+- **Framework:** switch to `examples/starters/ai-sdk` for adapter path
+
+Related: [VIDEO-WALKTHROUGH-SCRIPT.md](./VIDEO-WALKTHROUGH-SCRIPT.md) · [SCREENSHOTS.md](./SCREENSHOTS.md)

package/docs/DESIGN-PARTNER-GUIDE.md

@@ -0,0 +1,71 @@
+# Design partner guide
+
+Thank you for trying AgentInspect early. This doc is the **evaluation contract** — what we ask you to try, what we measure, and what we won't do.
+
+**Website:** [https://agentinspect.vercel.app/](https://agentinspect.vercel.app/) · **Docs:** [https://agentinspect.vercel.app/docs/](https://agentinspect.vercel.app/docs/)
+
+## What we're validating
+
+1. **First trace < 30 minutes** from `npm install` (with `init` + a starter)
+2. **First CI check** on a real or fixture trace
+3. **Share-safe workflow** — redacted artifact attached to an issue or PR
+4. **Framework fit** — AI SDK, OpenAI Agents, or LangChain path feels native enough
+
+## Your path
+
+| Week | Task | Success signal |
+| ---- | ---- | -------------- |
+| 1 | Run `init` + one starter | `list` shows a run |
+| 1 | `doctor` clean | No failed checks |
+| 2 | Wire adapter or `observe()` in your app | Real trace captured |
+| 2 | `check` or `eval` in CI | Job fails on bad fixture |
+| 3 | `redact --profile share` | Comfortable posting trace externally |
+| 4 | Feedback session | Case study draft or structured notes |
+
+## What we provide
+
+- Starters: [examples/starters/](../examples/starters/README.md)
+- Office hours async via GitHub Discussions / Issues
+- [DEMO-SCRIPT.md](./DEMO-SCRIPT.md) for internal team demos
+
+## What we ask from you
+
+- **Structured feedback** (template below) — not vague "looks good"
+- **Redacted traces** only — never raw secrets
+- Permission to quote anonymously unless you approve public case study
+
+## Feedback template
+
+```markdown
+### Environment
+- Node version:
+- Framework:
+- AgentInspect version:
+
+### First trace
+- Time to first trace:
+- Blockers:
+
+### CI
+- check/eval used?
+- Rules that mattered:
+
+### Gaps
+- Missing docs:
+- Missing framework coverage:
+- Would not adopt because:
+```
+
+## Metrics (no hidden telemetry)
+
+We track adoption from **public signals** and **your reports** only. See [product/ADOPTION-METRICS.md](./product/ADOPTION-METRICS.md).
+
+## Out of scope for partners
+
+- Hosted dashboards or SaaS
+- Custom adapter development on our roadmap without demand gates
+- SLAs — this is open-source MIT software
+
+## Contact
+
+Open a GitHub issue with label `design-partner` or email the maintainer listed in the repo.

package/docs/FIRST-TRACE-IN-5-MINUTES.md

@@ -2,6 +2,8 @@
 
 Goal: install → one trace → one check → one share-safe artifact.
 
+**Docs site:** [https://agentinspect.vercel.app/docs/getting-started/](https://agentinspect.vercel.app/docs/getting-started/)
+
 ```bash
 npm install agent-inspect && npx agent-inspect init --yes && node examples/agent-inspect-demo.mjs
 npx agent-inspect list --dir .agent-inspect && npx agent-inspect report <run-id> --dir .agent-inspect
@@ -59,4 +61,4 @@ Attach redacted JSONL to a PR or issue — not raw traces.
 | CI tests | [CI artifacts](./CI-ARTIFACTS.md) |
 | Broken agent demo | [broken-agent-debugging starter](../examples/starters/broken-agent-debugging/README.md) |
 
-Full index: [docs/README.md](./README.md)
+Full index: [docs/README.md](./README.md) · Website docs: [agentinspect.vercel.app/docs](https://agentinspect.vercel.app/docs/)

package/docs/GETTING-STARTED.md

@@ -2,6 +2,8 @@
 
 AgentInspect is a **local-first execution-tree debugger** for TypeScript AI agents. It helps you produce and inspect an execution tree of steps, safely and deterministically, without uploading data anywhere.
 
+**Website:** [https://agentinspect.vercel.app/](https://agentinspect.vercel.app/) · **Docs site:** [https://agentinspect.vercel.app/docs/getting-started/](https://agentinspect.vercel.app/docs/getting-started/)
+
 **Visual demos:** [SCREENSHOTS.md](./SCREENSHOTS.md)
 
 ## 1. Install

package/docs/NESTJS.md

@@ -0,0 +1,46 @@
+# NestJS + AgentInspect (harness path)
+
+AgentInspect does **not** ship a production NestJS interceptor in v3.2. Use **`@agent-inspect/harness`** to bootstrap real Nest apps for local fixture runs.
+
+## Recommended path (v3.2)
+
+1. `npx agent-inspect init` or use [examples/starters/harness-nestjs](../examples/starters/harness-nestjs/)
+2. Wire `createFixtureRunner()` with your `TestingModule` / app bootstrap
+3. Run targets with JSON fixtures — no real model calls by default
+
+```ts
+import { createFixtureRunner, defineTarget } from "@agent-inspect/harness";
+
+await createFixtureRunner({
+  name: "nestjs-support",
+  trace: { mode: "run-if-enabled", traceDir: ".agent-inspect" },
+  bootstrap: async () => {
+    const moduleRef = await Test.createTestingModule({ /* ... */ }).compile();
+    return moduleRef.createNestApplication();
+  },
+  shutdown: async (app) => {
+    await app?.close?.();
+  },
+  targets: {
+    ask: defineTarget({
+      resolve: (app) => app.get(SupportAgent),
+      invoke: (agent, input) => agent.run(input),
+    }),
+  },
+}).runFromArgv();
+```
+
+## Out of scope (v3.2)
+
+- `@agent-inspect/nestjs` production package (demand-gated)
+- Redis/SQS mocking in harness
+- Global monkey-patching of Nest providers
+
+## Structured logs alternative
+
+If you only need log ingestion, see [examples/recipes/nestjs-json-logging](../examples/recipes/nestjs-json-logging/).
+
+## Related
+
+- [`@agent-inspect/harness`](../packages/harness/README.md)
+- [examples/starters/harness-nestjs](../examples/starters/harness-nestjs/)

package/docs/OPENAI-AGENTS-LOCAL.md

@@ -0,0 +1,52 @@
+# OpenAI Agents JS — local-only tracing
+
+How to use `@agent-inspect/openai-agents` without sending traces to OpenAI's default export pipeline.
+
+## Two processor modes
+
+| Mode | API | OpenAI default export | AgentInspect traces |
+| ---- | --- | --------------------- | ------------------- |
+| **Additional processor** | `addTraceProcessor(agentInspect(...))` | May still run | Local JSONL via AgentInspect |
+| **Replacement list** | `setTraceProcessors([agentInspect(...)])` | Disabled when list is only AgentInspect | Local only |
+
+For **local-only** debugging, prefer **`setTraceProcessors`** with only the AgentInspect processor unless you explicitly need OpenAI's export.
+
+```ts
+import { setTraceProcessors } from "@openai/agents";
+import { agentInspect } from "@agent-inspect/openai-agents";
+
+setTraceProcessors([
+  agentInspect({
+    traceDir: ".agent-inspect",
+    capture: "metadata-only",
+  }),
+]);
+```
+
+## What maps to AgentInspect steps
+
+- Agent runs → run / step spans
+- Tool calls → `TOOL` steps with metadata
+- Handoffs → correlated steps when metadata is present
+- Guardrails → bounded metadata (no certification claims)
+- MCP tool calls → tool steps when the Agents SDK exposes MCP spans
+
+## Privacy
+
+- Default `metadata-only` capture
+- No automatic upload from AgentInspect
+- Replacing processors does not by itself redact OpenAI SDK network traffic — review OpenAI SDK settings separately
+
+## Recipes
+
+- [openai-agents-local-processor](../../examples/recipes/openai-agents-local-processor/)
+
+## Troubleshooting
+
+| Symptom | Check |
+| ------- | ----- |
+| Traces also appear in OpenAI dashboard | You may be using `addTraceProcessor` alongside default export — switch to `setTraceProcessors` for local-only |
+| No local files | Confirm processor is registered before agent runs; check `traceDir` |
+| Missing tool spans | Ensure tools run inside a traced agent session |
+
+See [ADAPTERS.md](./ADAPTERS.md).