agent-inspect 3.4.0 → 3.5.1

package/docs/ADOPTION.md

@@ -0,0 +1,67 @@
+# Adoption guide
+
+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.
+
+## Who this is for
+
+- TypeScript/Node teams shipping AI agents (not toy demos)
+- Developers who want **structure** without a hosted observability account
+- Maintainers who need **deterministic CI artifacts** (check, eval, redact)
+
+## 5-minute path
+
+See [FIRST-TRACE-IN-5-MINUTES.md](./FIRST-TRACE-IN-5-MINUTES.md).
+
+```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 view <run-id> --dir .agent-inspect
+npx agent-inspect verify-safe --dir .agent-inspect
+```
+
+No API keys required for the init demo. See [examples/starters/](../examples/starters/README.md).
+
+## Choose a starter
+
+| Goal | Starter |
+| ---- | ------- |
+| Manual `inspectRun` / `step` | [custom-observe](../examples/starters/custom-observe/) |
+| Vercel AI SDK | [ai-sdk](../examples/starters/ai-sdk/) — see [AI-SDK-ADOPTION.md](./AI-SDK-ADOPTION.md) |
+| OpenAI Agents JS | [openai-agents](../examples/starters/openai-agents/) — see [OPENAI-AGENTS-LOCAL.md](./OPENAI-AGENTS-LOCAL.md) |
+| LangChain | [langchain](../examples/starters/langchain/) |
+| CI eval + redact | [ci-eval-redact](../examples/starters/ci-eval-redact/) |
+| Broken agent debug | [broken-agent-debugging](../examples/starters/broken-agent-debugging/) |
+| NestJS harness | [harness-nestjs](../examples/starters/harness-nestjs/) — see [NESTJS.md](./NESTJS.md) |
+| VS Code (dev host) | [VSCODE.md](./VSCODE.md) — extension in-repo; Marketplace publish is manual |
+
+## Daily workflow
+
+1. **Capture** — `observe()` / adapter / manual steps → `.agent-inspect/*.jsonl`
+2. **Inspect** — `list`, `view`, `timeline`, `report`, optional `serve` viewer
+3. **Verify** — `check`, `eval`, `@agent-inspect/circuit` rules in CI
+4. **Share safely** — `redact --profile share` before attaching traces to issues/PRs
+5. **Scale** — when directories grow, see [SCALE-LIMITS.md](./SCALE-LIMITS.md) and `agent-inspect index build`
+
+## CI checklist
+
+- Persist `.agent-inspect/` or upload as CI artifacts ([CI-ARTIFACTS.md](./CI-ARTIFACTS.md))
+- Run `agent-inspect check` with `--require-completed` on fixture traces
+- Run `agent-inspect eval` / `verify-safe` where applicable
+- Never commit raw traces with secrets — use `redact` profiles
+
+## When not to use AgentInspect alone
+
+Use a production observability platform when you need hosted dashboards, fleet-wide sampling, or org-wide retention. AgentInspect complements that stack for the **inner loop**. See [COMPARE.md](./COMPARE.md).
+
+## Presenting AgentInspect
+
+- Live demo: [DEMO-SCRIPT.md](./DEMO-SCRIPT.md)
+- Recorded walkthrough: [VIDEO-WALKTHROUGH-SCRIPT.md](./VIDEO-WALKTHROUGH-SCRIPT.md)
+- Elevator pitch: [PITCH.md](./PITCH.md)
+- Design partners: [DESIGN-PARTNER-GUIDE.md](./DESIGN-PARTNER-GUIDE.md)
+
+## Measuring adoption (no default telemetry)
+
+Track funnel metrics manually or from npm/GitHub public signals. See [product/ADOPTION-METRICS.md](./product/ADOPTION-METRICS.md).

package/docs/CI-ARTIFACTS.md

@@ -0,0 +1,108 @@
+# CI trace artifacts
+
+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
+
+1. Install `agent-inspect` in CI.
+2. Enable tracing with `AGENT_INSPECT=1` and `maybeInspectRun` (or `inspectRun` when always-on is intended).
+3. Set `AGENT_INSPECT_TRACE_DIR` (default `.agent-inspect`).
+4. Run your job/tests.
+5. Create safe CI artifacts: `agent-inspect artifacts <run-id> --output-dir ./artifacts`.
+6. For reporter manifests, create a local CI summary: `agent-inspect ci-summary <manifest...> --output ./artifacts/reporter-summary.md`.
+7. Optional legacy exports: `agent-inspect export <run-id> --redaction-profile share`.
+8. Optional inspection reports: `agent-inspect what <run-id>` and `agent-inspect report <run-id> --format html`.
+9. Upload files with your CI artifact step.
+
+## Environment variables
+
+| Variable | Purpose |
+| -------- | ------- |
+| `AGENT_INSPECT=1` | Enables `maybeInspectRun` tracing |
+| `AGENT_INSPECT_TRACE_DIR` | Trace output directory |
+| `AGENT_INSPECT_SILENT=true` | Suppress live terminal tree in CI logs |
+
+## Export before upload
+
+Prefer **`--redaction-profile share`** for internal PR/issue attachments; use **`strict`** for wider sharing.
+
+For a deterministic CI bundle with structural JSON, safe Markdown/HTML summaries, safety check output, optional baseline diff output, and optional GitHub step-summary output:
+
+```bash
+npx agent-inspect artifacts <run-id> --dir ./.agent-inspect \
+  --output-dir ./artifacts --github-summary "$GITHUB_STEP_SUMMARY"
+```
+
+This command writes local files only. It does not call GitHub APIs or upload artifacts.
+
+For Vitest/Jest reporter artifacts, summarize shared `schemaVersion: "0.1"` reporter manifests without reading trace contents:
+
+```bash
+npx agent-inspect ci-summary .agent-inspect/jest-artifacts/tests/**/report.json \
+  --output ./artifacts/reporter-summary.md \
+  --github-summary "$GITHUB_STEP_SUMMARY"
+```
+
+`ci-summary` writes local files only. It validates reporter artifact paths as relative paths and includes bounded structural metadata: package/framework, test status counts, trace filenames, artifact paths, redaction profile, and diagnostic counts.
+
+```bash
+npx agent-inspect export <run-id> --dir ./.agent-inspect \
+  --format markdown --redaction-profile share -o ./artifacts/trace.md
+```
+
+Formats: `markdown`, `html`, `openinference`, `otlp-json` — all local files only.
+
+## What and report (v1.5)
+
+For quick human review in CI logs or local debugging:
+
+```bash
+npx agent-inspect what <run-id> --dir ./.agent-inspect
+```
+
+For a fuller inspection artifact (what + timeline + execution tree):
+
+```bash
+npx agent-inspect report <run-id> --dir ./.agent-inspect \
+  --format html --redaction-profile share -o ./artifacts/report.html
+```
+
+Recipe: [examples/recipes/what-report-inspect](../examples/recipes/what-report-inspect/README.md)
+
+## GitHub Actions example
+
+Recipes:
+
+- [examples/recipes/deterministic-ci-checks](../examples/recipes/deterministic-ci-checks/README.md) for v1.8 `check`, baseline, safe artifact, and step-summary workflows.
+- [examples/recipes/github-actions-artifact](../examples/recipes/github-actions-artifact/README.md) for share-safe trace exports and reporter manifest summaries.
+
+Sample workflows: [deterministic checks workflow](../examples/recipes/deterministic-ci-checks/workflow-example.yml), [share-safe export workflow](../examples/recipes/github-actions-artifact/workflow-example.yml)
+
+```yaml
+- uses: actions/upload-artifact@v4
+  with:
+    name: agent-inspect-traces
+    path: |
+      ./.agent-inspect
+      ./artifacts
+```
+
+## Inspect artifacts locally after download
+
+```bash
+npx agent-inspect list --dir ./.agent-inspect
+npx agent-inspect view <run-id> --dir ./.agent-inspect
+npx agent-inspect what <run-id> --dir ./.agent-inspect
+npx agent-inspect report <run-id> --dir ./.agent-inspect --format markdown
+npx agent-inspect timeline <run-id> --dir ./.agent-inspect
+npx agent-inspect stats --dir ./.agent-inspect
+npx agent-inspect search --dir ./.agent-inspect --status error
+```
+
+## Safety checklist
+
+- Review exports — redaction profiles are key-based, not compliance-grade DLP.
+- Do not commit trace directories or artifacts with secrets.
+- AgentInspect does not replace production observability platforms.
+
+See [SAFE-TRACE-SHARING.md](./SAFE-TRACE-SHARING.md).

package/docs/COMPARE.md

@@ -63,8 +63,21 @@ AgentInspect avoids SDK/collector setup for local debugging:
 | No-account CLI tracing | Strong fit |
 | Deterministic local eval heuristics | Good fit |
 | Share-safe local redaction copy | Good fit |
+| VS Code trace sidebar (in-repo / dev host) | Good fit — Marketplace listing separate |
 | Production dashboards | Not the goal |
 | Hosted eval datasets | Not the goal |
 | Prompt management | Not the goal |
 | Standards-aligned local export | Partial (compatibility-oriented) |
 | Full observability platform | Use a dedicated platform |
+
+## v3.5 positioning (local inner loop)
+
+AgentInspect v3.5 is the **adoption release** — not new runtime surface. Use it when:
+
+- You want **traces on disk** before/alongside hosted tools
+- You need **CI gates** (`check`, `eval`, `circuit`) without a vendor account
+- You want **metadata-only** defaults and explicit `redact` before sharing
+
+Keep using LangSmith, Langfuse, Braintrust, Phoenix, or OTel when you need hosted retention, fleet dashboards, dataset management, or org-wide production pipelines. AgentInspect is complementary.
+
+**Full adoption path:** [ADOPTION.md](./ADOPTION.md)

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

@@ -0,0 +1,56 @@
+# First trace in 5 minutes
+
+Goal: install → one trace → one check → one share-safe artifact.
+
+## Minutes 0–1: Install
+
+```bash
+mkdir my-agent-debug && cd my-agent-debug
+npm install agent-inspect
+npx agent-inspect init --yes
+```
+
+Creates `agent-inspect.config.ts`, `.agent-inspect/`, and `examples/agent-inspect-demo.mjs`.
+
+## Minutes 1–2: Run
+
+```bash
+node examples/agent-inspect-demo.mjs
+```
+
+No API keys. Deterministic local trace.
+
+## Minutes 2–3: Inspect
+
+```bash
+npx agent-inspect list --dir .agent-inspect
+npx agent-inspect view <run-id> --dir .agent-inspect
+npx agent-inspect report <run-id> --dir .agent-inspect
+```
+
+## Minutes 3–4: Check
+
+```bash
+npx agent-inspect check .agent-inspect/*.jsonl
+```
+
+## Minutes 4–5: Share-safe artifact
+
+```bash
+npx agent-inspect redact --profile share --dir .agent-inspect
+npx agent-inspect verify-safe --dir .agent-inspect
+```
+
+Attach redacted JSONL to a PR or issue — not raw traces.
+
+## Next steps
+
+| If you use… | Go to |
+| ----------- | ----- |
+| AI SDK | [AI SDK adoption](./AI-SDK-ADOPTION.md) |
+| OpenAI Agents | [OpenAI Agents local](./OPENAI-AGENTS-LOCAL.md) |
+| LangChain | [Adapters](./ADAPTERS.md) |
+| 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)

package/docs/GETTING-STARTED.md

@@ -12,8 +12,11 @@ pnpm add agent-inspect
 
 ### Quick bootstrap (v3.1+)
 
+See also [FIRST-TRACE-IN-5-MINUTES.md](./FIRST-TRACE-IN-5-MINUTES.md) and [ONE-PAGE-QUICKSTART.md](./ONE-PAGE-QUICKSTART.md).
+
 ```bash
-npx agent-inspect init
+npx agent-inspect init --yes
+node examples/agent-inspect-demo.mjs
 npx agent-inspect doctor
 ```
 

package/docs/ONE-PAGE-QUICKSTART.md

@@ -0,0 +1,15 @@
+# One-page quickstart
+
+```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 view <run-id> --dir .agent-inspect
+npx agent-inspect report <run-id> --dir .agent-inspect
+npx agent-inspect verify-safe --dir .agent-inspect
+```
+
+**Paths:** [Getting started](./GETTING-STARTED.md) · [Adoption](./ADOPTION.md) · [Starters](https://github.com/rajudandigam/agent-inspect/tree/main/examples/starters)
+
+**Safety:** Traces are local files. No upload by default. Redact before sharing.

package/docs/PERFORMANCE.md

@@ -0,0 +1,54 @@
+# Performance
+
+AgentInspect is **local-first** and optimized for developer workflows, not production APM. Use this guide to set expectations and run the repo baseline.
+
+## Quick baseline
+
+After `pnpm build`:
+
+```bash
+pnpm perf:baseline
+```
+
+The script prints deterministic timings for parse, normalize, tree build, diff, export, and checks on synthetic data. Warnings appear when a step exceeds internal soft thresholds.
+
+## Comfortable ranges (v3.4)
+
+| Workload | Comfortable | Warning | Not designed for |
+| -------- | ----------- | ------- | ---------------- |
+| Trace runs in one directory | ≤ 1,000 | 1,000–10,000 | > 10,000 without archive/split |
+| Events per run (check/view) | ≤ 10,000 | 10,000–50,000 | > 100,000 single JSONL |
+| Single trace file size | ≤ 10 MB | 50 MB+ | Multi-GB logs |
+| `list` / `search` / `stats` | Sub-second on SSD for ≤1k runs | Seconds+ above warn threshold | Full scans of huge dirs every request |
+
+See [SCALE-LIMITS.md](./SCALE-LIMITS.md) for CLI warnings and indexer guidance.
+
+## What affects performance
+
+- **Directory size:** `list`, `search`, and `stats` read metadata from every trace file unless an optional index is used.
+- **Event count:** `view`, `check`, `report`, and `timeline` scale with events in the selected run.
+- **Exports:** OpenInference and OTLP export walk the full tree.
+- **Viewer:** `agent-inspect serve` loads one run at a time; startup is dominated by read + render.
+
+## Optional index
+
+For large directories (≥ 1,000 runs), build a rebuildable metadata index:
+
+```bash
+agent-inspect index build --dir .agent-inspect
+agent-inspect index status --dir .agent-inspect
+```
+
+The index is optional, local, and safe to delete (`agent-inspect index clean`).
+
+## Stall and timeout checks
+
+Use deterministic check rules on completed traces:
+
+```bash
+agent-inspect check run_abc --dir .agent-inspect --max-step-duration 30s
+agent-inspect check run_abc --dir .agent-inspect --require-completed
+agent-inspect check run_abc --dir .agent-inspect --detect-stalls
+```
+
+These complement `@agent-inspect/circuit` analyzers for loop/retry detection.

package/docs/SAFE-TRACE-SHARING.md

@@ -0,0 +1,89 @@
+# Safe trace sharing checklist
+
+AgentInspect traces, log-ingest outputs, and exports are local files. They may still contain sensitive metadata that you attached manually, collected from logs, or included through optional preview settings. Use this checklist before sharing an artifact in a GitHub issue, Discussion, PR, support thread, or public post.
+
+This guide is practical sharing guidance, not a guarantee that any artifact is safe to publish. Redaction profiles are **key-based safeguards**, not compliance-grade DLP.
+
+## Quick presets (v1.3.0+)
+
+- **`--redaction-profile share`** — PRs, GitHub issues, Slack/email threads inside your org. Redacts correlation IDs, customer/user IDs, and common contact fields.
+- **`--redaction-profile strict`** — external sharing or public posts. Also redacts prompt/output/message-like metadata keys.
+- **Default (`local`)** — same as before; still review before sharing.
+
+```bash
+npx agent-inspect export <run-id> --format markdown --redaction-profile share
+npx agent-inspect export <run-id> --format html --redaction-profile strict
+npx agent-inspect redact trace.jsonl --profile share --json
+```
+
+Original trace files under `.agent-inspect-runs/` are **not modified** by export or `redact` copy workflows.
+
+### Default redaction before disk
+
+![Sensitive metadata keys redacted in trace output](../assets/demos/redaction.gif)
+
+Manual traces redact common sensitive keys **before disk** by default. Pass `redact: false` only when you accept the risk locally.
+
+## Before sharing
+
+- Use **`--redaction-profile share`** for PR/issue attachments; use **`strict`** when sharing outside your team.
+- **Review** the exported file — profiles do not detect all sensitive data.
+- Treat traces written with `redact: false` as sensitive. Review every event before sharing them outside your team.
+- Inspect manual metadata passed to `inspectRun()`, `step()`, `step.tool()`, `step.llm()`, or `observe()`.
+- Inspect log-derived fields from `logs` / `tail` ingest configs, including custom `run-id`, `event`, `parent`, timestamp, and attribute mappings.
+- Avoid posting raw prompts, completions, tool inputs, or tool outputs in public threads unless the content is approved for public disclosure.
+- Prefer Markdown export for issue or PR sharing when a summarized tree is enough.
+
+## Remove or replace sensitive values
+
+Search the artifact for:
+
+- API keys, bearer tokens, cookies, session IDs, JWTs, OAuth codes, and webhook secrets
+- passwords, private keys, certificates, signing secrets, and database URLs
+- email addresses, phone numbers, physical addresses, usernames, and customer IDs
+- internal hostnames, service URLs, ticket IDs, order IDs, account IDs, and tenant IDs
+- proprietary prompts, system instructions, model outputs, retrieved documents, and tool responses
+- file paths that expose user names, project names, or internal directory layouts
+
+Replace sensitive data with clear placeholders such as `example.test`, `user@example.test`, `CUSTOMER_ID_REDACTED`, or `TOKEN_REDACTED`.
+
+## Export and ingest-specific checks
+
+- Markdown / HTML exports: review rendered text and copied snippets, not only the source trace.
+- Eval JSON / Markdown: review failed-rule messages, expected/actual summaries, source IDs, and evidence paths before attaching them to PRs or issues.
+- Redacted copies from `agent-inspect redact`: review the output file itself; findings show detector/path/action evidence but do not certify full safety.
+- OpenInference / OTLP JSON exports: check attributes, span names, events, and resource metadata.
+- Structured log ingest configs: confirm mapped keys do not pull in full request bodies, headers, raw prompts, or unbounded output fields.
+- LangChain adapter traces: keep `capture: "metadata-only"` for shareable examples; review `capture: "preview"` traces carefully because previews can include prompt or output fragments.
+
+## When to use each profile
+
+| Situation | Profile | Format tip |
+| --------- | ------- | ---------- |
+| Local debugging only | `local` (default) | Full CLI `view` is fine on your machine |
+| PR or GitHub issue attachment | `share` | `export --format markdown --redaction-profile share` |
+| External blog, public forum, customer-facing | `strict` | Review twice; prefer synthetic/minimal repro |
+| Local JSON/JSONL copy for review | `share` or `strict` | `redact <file> --profile share --json` |
+| Security incident or secret leak suspicion | — | Do not post traces publicly; use [SECURITY.md](../SECURITY.md) |
+
+## Guardrails and circuits (v2.5 planning)
+
+- Optional `@agent-inspect/guardrails` and `@agent-inspect/circuit` packages evaluate local text/JSON/trace patterns deterministically.
+- They reuse `@agent-inspect/redact` for PII-style findings where applicable — same best-effort limits as redaction profiles.
+- They are **not** compliance tools and do not guarantee an artifact is safe to publish.
+- Circuits detect repetition, retries, and width in traces or explicit counters; they do not stop runaway agents unless your code enforces results.
+
+## What this guide does not claim
+
+- Redaction profiles are **not** GDPR/HIPAA/SOC2 compliance tools.
+- Export redaction does **not** upload anywhere — it only shapes a local copy.
+- No automated scan guarantees an artifact is safe to publish.
+
+## Final review
+
+- Open the exact file you plan to share and search for common sensitive strings: `token`, `secret`, `authorization`, `cookie`, `password`, `email`, `apiKey`, `key`, `jwt`, `bearer`.
+- Confirm any screenshots do not show terminal history, environment variables, browser account data, or private repository names.
+- Share the smallest useful artifact: a summary, selected excerpt, or minimized synthetic reproduction is better than a full trace.
+- If the artifact includes production or customer data, do not share it publicly. Use a private security or support channel.
+
+See [SECURITY.md](../SECURITY.md) for the security policy and redaction expectations.

package/docs/USE-CASES.md

@@ -0,0 +1,116 @@
+# Use cases
+
+Problem-oriented guide for AgentInspect. Each case links to a starter or doc.
+
+## 1. Wrong tool call
+
+**Problem:** The agent picked `search_docs` instead of `refund_policy`.
+
+**Why logs alone are hard:** Provider logs show a tool name, not parent run context or sibling steps.
+
+**Use:** `agent-inspect` CLI + local trace tree.
+
+```bash
+npx agent-inspect view <run-id> --dir .agent-inspect
+npx agent-inspect report <run-id> --dir .agent-inspect
+```
+
+**Output:** Step tree with tool metadata (not raw payloads by default).
+
+**Safety:** Metadata-only default. Redact before sharing: `npx agent-inspect redact --profile share`.
+
+**Starter:** [custom-observe](../examples/starters/custom-observe/README.md)
+
+**Not:** Live model replay or hosted trace UI.
+
+---
+
+## 2. Eval failure — which step broke?
+
+**Problem:** A Vitest eval failed; you need the failing step, not just the assertion message.
+
+**Use:** `@agent-inspect/vitest` or `npx agent-inspect check`.
+
+```bash
+npx agent-inspect check .agent-inspect/*.jsonl --require-completed
+```
+
+**Starter:** [ci-eval-redact](../examples/starters/ci-eval-redact/README.md)
+
+---
+
+## 3. CI trace artifact on a failed PR
+
+**Problem:** Reviewers need safe evidence without cloning your laptop.
+
+**Use:** CI upload + `redact --profile share` + `verify-safe`.
+
+**Doc:** [CI artifacts](./CI-ARTIFACTS.md)
+
+---
+
+## 4. Framework-native trace (AI SDK / OpenAI Agents / LangChain)
+
+**Problem:** Manual `step()` calls do not match framework lifecycle.
+
+**Use:** `@agent-inspect/ai-sdk`, `@agent-inspect/openai-agents`, or `@agent-inspect/langchain`.
+
+**Starters:** [examples/starters](../examples/starters/README.md)
+
+---
+
+## 5. Safe incident handoff
+
+**Problem:** You need to paste a trace into Slack or a GitHub issue.
+
+**Use:** `@agent-inspect/redact` or CLI `redact` / `scan`.
+
+**Doc:** [Safe trace sharing](./SAFE-TRACE-SHARING.md)
+
+---
+
+## 6. Multi-agent / session debugging
+
+**Problem:** Handoffs and retries span multiple runs.
+
+**Use:** `agent-inspect sessions`, `search`, `diff`.
+
+---
+
+## 7. MCP tool tracing
+
+**Problem:** Which MCP tools were listed, called, and where did they fail?
+
+**Use:** `@agent-inspect/mcp` (client tracing only).
+
+---
+
+## 8. Design partner adoption
+
+**Problem:** Team wants one real agent instrumented in one sprint.
+
+**Doc:** [Design partner guide](./DESIGN-PARTNER-GUIDE.md)
+
+---
+
+## 9. VS Code trace review
+
+**Problem:** Browse `.agent-inspect/` from the editor.
+
+**Use:** In-repo `packages/vscode` (F5 dev). Not on Marketplace yet.
+
+**Doc:** [VS Code](./VSCODE.md)
+
+---
+
+## 10. Existing structured logs
+
+**Problem:** You cannot change app code; logs already exist.
+
+**Use:** `agent-inspect/logs` entry + CLI import helpers.
+
+**Doc:** [Log-to-tree quickstart](./LOG-TO-TREE-QUICKSTART.md)
+
+---
+
+See also: [Real-world scenarios](./REAL-WORLD-SCENARIOS.md) · [Team workflows](./TEAM-WORKFLOWS.md)

package/docs/assets/agent-inspect-loop.svg

@@ -0,0 +1,22 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 720 120" role="img" aria-label="AgentInspect loop: trace, check, redact">
+  <defs>
+    <marker id="arrow" markerWidth="8" markerHeight="8" refX="6" refY="3" orient="auto">
+      <path d="M0,0 L6,3 L0,6 Z" fill="#334155"/>
+    </marker>
+  </defs>
+  <rect width="720" height="120" fill="#f8fafc" rx="8"/>
+  <g font-family="system-ui,sans-serif" font-size="14" fill="#0f172a">
+    <rect x="24" y="36" width="140" height="48" rx="8" fill="#dbeafe" stroke="#3b82f6"/>
+    <text x="94" y="66" text-anchor="middle">Trace</text>
+    <rect x="220" y="36" width="140" height="48" rx="8" fill="#dcfce7" stroke="#22c55e"/>
+    <text x="290" y="66" text-anchor="middle">Check</text>
+    <rect x="416" y="36" width="140" height="48" rx="8" fill="#fef3c7" stroke="#f59e0b"/>
+    <text x="486" y="66" text-anchor="middle">Redact</text>
+    <rect x="572" y="36" width="124" height="48" rx="8" fill="#f1f5f9" stroke="#64748b"/>
+    <text x="634" y="66" text-anchor="middle">Share</text>
+    <line x1="164" y1="60" x2="212" y2="60" stroke="#334155" marker-end="url(#arrow)"/>
+    <line x1="360" y1="60" x2="408" y2="60" stroke="#334155" marker-end="url(#arrow)"/>
+    <line x1="556" y1="60" x2="564" y2="60" stroke="#334155" marker-end="url(#arrow)"/>
+    <text x="360" y="108" text-anchor="middle" font-size="12" fill="#64748b">local files only � no upload by default</text>
+  </g>
+</svg>

package/docs/assets/package-map.svg

@@ -0,0 +1,31 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 720 280" role="img" aria-label="AgentInspect package map">
+  <rect width="720" height="280" fill="#f8fafc" rx="8"/>
+  <g font-family="system-ui,sans-serif" font-size="12" fill="#0f172a">
+    <rect x="280" y="20" width="160" height="40" rx="6" fill="#1e293b" stroke="#0f172a"/>
+    <text x="360" y="45" text-anchor="middle" fill="#fff" font-weight="600">agent-inspect</text>
+    <text x="360" y="72" text-anchor="middle" font-size="11" fill="#64748b">core + CLI</text>
+    <line x1="360" y1="60" x2="120" y2="110" stroke="#94a3b8"/>
+    <line x1="360" y1="60" x2="280" y2="110" stroke="#94a3b8"/>
+    <line x1="360" y1="60" x2="440" y2="110" stroke="#94a3b8"/>
+    <line x1="360" y1="60" x2="600" y2="110" stroke="#94a3b8"/>
+    <rect x="40" y="110" width="160" height="36" rx="4" fill="#dbeafe" stroke="#3b82f6"/>
+    <text x="120" y="133" text-anchor="middle">Framework adapters</text>
+    <rect x="40" y="156" width="48" height="28" rx="4" fill="#fff" stroke="#cbd5e1"/><text x="64" y="174" text-anchor="middle" font-size="10">ai-sdk</text>
+    <rect x="96" y="156" width="48" height="28" rx="4" fill="#fff" stroke="#cbd5e1"/><text x="120" y="174" text-anchor="middle" font-size="10">oai</text>
+    <rect x="152" y="156" width="48" height="28" rx="4" fill="#fff" stroke="#cbd5e1"/><text x="176" y="174" text-anchor="middle" font-size="10">lc</text>
+    <rect x="220" y="110" width="120" height="36" rx="4" fill="#dcfce7" stroke="#22c55e"/>
+    <text x="280" y="133" text-anchor="middle">Quality</text>
+    <rect x="220" y="156" width="56" height="28" rx="4" fill="#fff" stroke="#cbd5e1"/><text x="248" y="174" text-anchor="middle" font-size="10">eval</text>
+    <rect x="284" y="156" width="56" height="28" rx="4" fill="#fff" stroke="#cbd5e1"/><text x="312" y="174" text-anchor="middle" font-size="10">vitest</text>
+    <rect x="380" y="110" width="120" height="36" rx="4" fill="#fef3c7" stroke="#f59e0b"/>
+    <text x="440" y="133" text-anchor="middle">Safety</text>
+    <rect x="380" y="156" width="56" height="28" rx="4" fill="#fff" stroke="#cbd5e1"/><text x="408" y="174" text-anchor="middle" font-size="10">redact</text>
+    <rect x="444" y="156" width="56" height="28" rx="4" fill="#fff" stroke="#cbd5e1"/><text x="472" y="174" text-anchor="middle" font-size="10">guard</text>
+    <rect x="520" y="110" width="160" height="36" rx="4" fill="#f3e8ff" stroke="#a855f7"/>
+    <text x="600" y="133" text-anchor="middle">Inspect UX</text>
+    <rect x="520" y="156" width="48" height="28" rx="4" fill="#fff" stroke="#cbd5e1"/><text x="544" y="174" text-anchor="middle" font-size="10">viewer</text>
+    <rect x="576" y="156" width="48" height="28" rx="4" fill="#fff" stroke="#cbd5e1"/><text x="600" y="174" text-anchor="middle" font-size="10">tui</text>
+    <rect x="632" y="156" width="48" height="28" rx="4" fill="#fff" stroke="#cbd5e1"/><text x="656" y="174" text-anchor="middle" font-size="10">mcp</text>
+    <text x="360" y="250" text-anchor="middle" font-size="11" fill="#64748b">All packages: local-first � no default upload</text>
+  </g>
+</svg>

package/docs/assets/trace-check-redact.svg

@@ -0,0 +1,19 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 640 200" role="img" aria-label="Trace to check to redact workflow">
+  <rect width="640" height="200" fill="#fff" rx="8"/>
+  <g font-family="system-ui,sans-serif" font-size="13" fill="#0f172a">
+    <text x="32" y="32" font-weight="600">Workflow</text>
+    <rect x="32" y="48" width="160" height="56" rx="6" fill="#eff6ff" stroke="#2563eb"/>
+    <text x="112" y="72" text-anchor="middle">.agent-inspect/</text>
+    <text x="112" y="90" text-anchor="middle" font-size="11" fill="#475569">JSONL trace</text>
+    <text x="220" y="80" font-size="18">�</text>
+    <rect x="248" y="48" width="160" height="56" rx="6" fill="#f0fdf4" stroke="#16a34a"/>
+    <text x="328" y="72" text-anchor="middle">check / eval</text>
+    <text x="328" y="90" text-anchor="middle" font-size="11" fill="#475569">deterministic rules</text>
+    <text x="436" y="80" font-size="18">�</text>
+    <rect x="464" y="48" width="144" height="56" rx="6" fill="#fffbeb" stroke="#d97706"/>
+    <text x="536" y="72" text-anchor="middle">redact</text>
+    <text x="536" y="90" text-anchor="middle" font-size="11" fill="#475569">share profile</text>
+    <text x="32" y="140" font-size="12" fill="#64748b">CLI: list � view � report � verify-safe</text>
+    <text x="32" y="160" font-size="12" fill="#64748b">Packages: @agent-inspect/eval � @agent-inspect/redact</text>
+  </g>
+</svg>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-inspect",
-  "version": "3.4.0",
+  "version": "3.5.1",
   "license": "MIT",
   "type": "module",
   "description": "Local-first execution-tree debugger for TypeScript AI agents",
@@ -128,6 +128,7 @@
     "SECURITY.md",
     "CHANGELOG.md",
     "docs/GETTING-STARTED.md",
+    "docs/ADOPTION.md",
     "docs/API.md",
     "docs/CLI.md",
     "docs/SCHEMA.md",
@@ -142,7 +143,16 @@
     "docs/ADAPTER-CONFORMANCE.md",
     "docs/COMPARE.md",
     "docs/LOG-TO-TREE-QUICKSTART.md",
-    "docs/SCREENSHOTS.md"
+    "docs/SCREENSHOTS.md",
+    "docs/SAFE-TRACE-SHARING.md",
+    "docs/CI-ARTIFACTS.md",
+    "docs/PERFORMANCE.md",
+    "docs/FIRST-TRACE-IN-5-MINUTES.md",
+    "docs/ONE-PAGE-QUICKSTART.md",
+    "docs/USE-CASES.md",
+    "docs/assets/agent-inspect-loop.svg",
+    "docs/assets/trace-check-redact.svg",
+    "docs/assets/package-map.svg"
   ],
   "sideEffects": false,
   "keywords": [