agent-inspect 6.17.1 → 6.17.3

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 6.17.3
+
+### Patch Changes
+
+- 737bb03: Docs updates (README mark/loop, case-study template, Evidence retention guidance, support reproduction), TraceFacts/Evidence/OTLP/CLI regression tests, and exclude the RUN boundary from `run.slowestNode`.
+
+## 6.17.2
+
+### Patch Changes
+
+- a7a7ea8: Union CLI check shorthands with preset select, resolve nested v0.1 LLM metadata in checks, and present Debug / Prevent / Share with curated showcase media.
+
 ## 6.17.1
 
 ### Patch Changes

package/README.md

@@ -1,27 +1,24 @@
 <p align="center">
-  <picture>
-    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/rajudandigam/agent-inspect/main/docs/assets/agent-inspect-logo-dark.svg?sanitize=true">
-    <img src="https://raw.githubusercontent.com/rajudandigam/agent-inspect/main/docs/assets/agent-inspect-logo.svg?sanitize=true" width="240" alt="AgentInspect">
-  </picture>
+  <img src="https://raw.githubusercontent.com/rajudandigam/agent-inspect/main/docs/assets/agent-inspect-logo-mark.svg?sanitize=true" width="56" height="56" alt="AgentInspect">
 </p>
+<p align="center"><strong>agent-inspect</strong></p>
+<p align="center">Local-first evidence for TypeScript AI agents</p>
 
-<h1 align="center">agent-inspect</h1>
+<h1 align="center">
+  See what your agent did.<br>
+  Catch the wrong path in CI.<br>
+  Keep the evidence local.
+</h1>
 
 <p align="center">
-  <strong>Debug and regression-test TypeScript AI agents from local evidence.</strong>
+  AgentInspect turns TypeScript agent runs into readable execution trees,
+  deterministic trajectory checks, and portable Evidence v2—without requiring
+  an account, collector, or default upload.
 </p>
 
-<p align="center">
-  AgentInspect captures framework-faithful execution trees, evaluates them with deterministic TraceFacts and TraceContract rules, creates integrity-verifiable Evidence v2, and lets coding assistants inspect the same local facts over read-only MCP—without a collector, account, or default upload.
-</p>
+<p align="center"><strong>Capture once. Debug, prevent, and share from the same local trace.</strong></p>
 
-<p align="center">
-  <em>See what your agent did. Prove the fix. Keep the evidence.</em>
-</p>
-
-<p align="center">
-  <sub>No account · no collector · no default upload · metadata-only by default</sub>
-</p>
+<p align="center"><sub>No account · no collector · no default upload · metadata-only by default</sub></p>
 
 <p align="center">
   <a href="https://agentinspect.vercel.app/">Website</a> ·
@@ -32,234 +29,201 @@
 
 <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>
+  <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 or newer"></a>
 </p>
 
 ```bash
 npm install agent-inspect
 ```
 
-## Four pillars
-
-| Pillar | What you get |
-| ------ | ------------ |
-| **Capture faithfully** | Framework-aware execution trees and local JSONL you own |
-| **Test behavior deterministically** | TraceFacts, TraceContract, checks, suites, gates, and experimental Vitest/Jest matchers |
-| **Produce portable evidence** | Offline Evidence v2 with integrity verification and share-policy disclosure |
-| **Debug with coding assistants locally** | Read-only MCP over the same TraceFacts — no collector required |
-
-```text
-1. Capture one real run
-2. Find the causal failure
-3. Ask your coding agent to inspect it
-4. Lock the fix with a contract
-5. Attach the share-checked evidence
-```
+<p align="center">
+  <img src="https://raw.githubusercontent.com/rajudandigam/agent-inspect/main/docs/assets/showcase/gif/debug-tree.gif" alt="AgentInspect lists a local demo-good run, then you inspect the execution tree from the same JSONL" width="900">
+</p>
+
+Agent code rarely fails as one function call. It plans, retrieves, calls tools, invokes a model, retries, and produces side effects. Flat logs show fragments. AgentInspect keeps the run as local JSONL and gives you one evidence loop from the same trace.
 
 <p align="center">
-  <img src="https://raw.githubusercontent.com/rajudandigam/agent-inspect/main/docs/assets/readme-product-loop.svg?sanitize=true" alt="Capture or import → understand → enforce → verify and bundle → review locally or in customer-owned Studio" width="900">
+  <img src="https://raw.githubusercontent.com/rajudandigam/agent-inspect/main/docs/assets/readme-product-loop.svg?sanitize=true" alt="Capture one local trace, then debug, prevent, and share from the same evidence loop" width="900">
 </p>
 
-## Five-minute path
+## One trace. Three jobs.
 
-Commands below match the packed quickstart. Replace `<run-id>` with a value from `list`.
+### Debug — read the execution path
 
-```bash
-npm install agent-inspect
-npx agent-inspect init --yes
-# or: npx agent-inspect init --framework langgraph --yes
-node examples/agent-inspect-demo.mjs
-npx agent-inspect list --dir .agent-inspect
-```
+See nested steps, tool calls, LLM calls, model and token metadata, durations, errors, and the first causal failure without sending the trace to an AgentInspect service.
 
 ```bash
-# After copying a run id from list:
+npx agent-inspect view <run-id> --dir .agent-inspect --summary
 npx agent-inspect report <run-id> --dir .agent-inspect
-npx agent-inspect check <run-id> --dir .agent-inspect
-npx agent-inspect bundle <run-id> --dir .agent-inspect --profile share
-npx agent-inspect verify-safe <run-id> --dir .agent-inspect
-npx agent-inspect bundle verify .agent-inspect/bundles/<run-id>
-# Optional coding-agent loop (dry-run by default):
-npx agent-inspect mcp configure --client cursor
+npx agent-inspect explain <run-id> --dir .agent-inspect
 ```
 
-Guides: [First trace in 5 minutes](https://agentinspect.vercel.app/docs/getting-started/) · [Golden path](https://github.com/rajudandigam/agent-inspect/blob/main/docs/GOLDEN-PATH.md) · [Coding-agent loop](https://github.com/rajudandigam/agent-inspect/blob/main/docs/CODING-AGENT-LOOP.md)
-
-## Why AgentInspect
-
-**Category:** the local evidence debugger and trajectory-test toolkit for TypeScript AI agents — not a hosted APM, eval host, or prompt registry. Complements LangSmith/Langfuse/Phoenix; owns the laptop → PR loop.
+Use manual instrumentation, official adapters, supported standards files, or structured logs you already emit.
 
-**Proof (public-safe):** Validated against production-shaped NestJS/LangGraph integrations. Fixture-backed across official adapters and packed consumer workflows.
+### Prevent — fail CI on the wrong trajectory
 
-| Mechanism | What you get |
-| --------- | ------------ |
-| Faithful execution trees | Nested steps, tools, LLMs, status, duration on disk |
-| TraceFacts / logical projection | Canonical tool identity and semantic parity without inventing hierarchy |
-| Deterministic checks / TraceContract (Beta) | Trajectory expectations without an LLM judge |
-| Experimental Vitest/Jest matchers | `toPassTraceContract` · `toHaveRequiredTool` |
-| Share-checked Evidence v2 | `bundle` + `bundle verify` with optional TraceFacts semantics |
-| Read-only MCP coding-agent loop (Preview) | `get_trace_facts` and related tools over local traces |
-
-## Choose your capture path
+<p align="center">
+  <img src="https://raw.githubusercontent.com/rajudandigam/agent-inspect/main/docs/assets/showcase/gif/check-pass-fail.gif" alt="The same deterministic AgentInspect check exits zero for demo-good and one for demo-regression" width="900">
+</p>
 
-| Path | Use when | Start |
-| ---- | -------- | ----- |
-| **Manual / observe** | Custom nesting or object methods | [Getting started](https://github.com/rajudandigam/agent-inspect/blob/main/docs/GETTING-STARTED.md) |
-| **AI SDK** | Vercel AI SDK `generateText` / `streamText` | [`@agent-inspect/ai-sdk`](https://www.npmjs.com/package/@agent-inspect/ai-sdk) |
-| **OpenAI Agents** | OpenAI Agents JS | [`@agent-inspect/openai-agents`](https://www.npmjs.com/package/@agent-inspect/openai-agents) |
-| **LangChain / LangGraph** | Callbacks / LangGraph | [`@agent-inspect/langchain`](https://www.npmjs.com/package/@agent-inspect/langchain) · `init --framework langgraph` |
-| **Structured logs** | Logs already emitted | [Log-to-tree](https://github.com/rajudandigam/agent-inspect/blob/main/docs/LOG-TO-TREE-QUICKSTART.md) |
-| **Harness** | Fixture runner for real projects | [`@agent-inspect/harness`](https://www.npmjs.com/package/@agent-inspect/harness) |
-| **CI reporters + matchers** | Failed-test artifacts and contracts | [`vitest`](https://www.npmjs.com/package/@agent-inspect/vitest) · [`jest`](https://www.npmjs.com/package/@agent-inspect/jest) |
-| **Standards files** | OpenInference / OTLP JSON | [Standards](https://github.com/rajudandigam/agent-inspect/blob/main/docs/STANDARDS.md) |
+Checks are deterministic and provider-free: the same trace and rules produce the same result. Start with a preset, then extend it with the expectations that matter to the workflow.
 
-Blessed starters (no API keys): [examples/starters](https://github.com/rajudandigam/agent-inspect/tree/main/examples/starters) · LangGraph gate/evidence recipe: [langgraph-gate-evidence](https://github.com/rajudandigam/agent-inspect/tree/main/examples/recipes/langgraph-gate-evidence)
+```bash
+npx agent-inspect check <run-id> --dir .agent-inspect \
+  --preset trajectory \
+  --required-tool retrieve_policy \
+  --fail-on-observation failed
+```
 
-## What you can do after capture
+A passing check exits `0`; a rule failure exits `1`. Invalid configuration and unreadable/unsupported inputs use separate documented exit codes. Use TraceContract, suites, cohorts, Vitest/Jest reporters, or `--evidence-on fail` when the workflow needs more than one CLI check.
 
-**Understand** — `what` / `view` / tree · timeline · report · diff · `buildTraceFacts`
+### Share — create reviewable offline evidence
 
-**Prevent regressions** — deterministic checks · TraceContract (Beta) · suites · cohorts · CI gates · Vitest/Jest reporters · experimental matchers (`toPassTraceContract`, `toHaveRequiredTool`)
+<p align="center">
+  <img src="https://raw.githubusercontent.com/rajudandigam/agent-inspect/main/docs/assets/showcase/gif/evidence-bundle.gif" alt="AgentInspect writes a share-checked Evidence v2 bundle to ./evidence and verifies the listed file hashes offline" width="900">
+</p>
 
-**Share safely** — redaction profiles · `scan` · `verify-safe` · Evidence v2 bundles · CI artifacts
+```bash
+npx agent-inspect verify-safe <run-id> --dir .agent-inspect
+npx agent-inspect bundle <run-id> --dir .agent-inspect --profile share --out ./evidence
+npx agent-inspect bundle verify ./evidence
+```
 
-**Debug with coding assistants** — `@agent-inspect/mcp-server` · `get_trace_facts` · first-causal-failure
+`verify-safe` is a best-effort local assessment and can report `SAFE`, `SAFE WITH WARNINGS`, `UNSAFE`, or `UNKNOWN`. `bundle` writes a redacted artifact and manifest; `bundle verify` rechecks the listed file hashes offline. “Share-checked” is not compliance certification—review the artifact before attaching it to a PR, incident, or support handoff.
 
-**Scale locally** — workspace · optional SQLite index (Beta) · viewer / TUI / VS Code · customer-owned Studio (Beta)
+## First local trace
 
-Support labels: [SUPPORT-LEVELS.md](https://github.com/rajudandigam/agent-inspect/blob/main/docs/SUPPORT-LEVELS.md) · Network: [NETWORK-BEHAVIOR.md](https://github.com/rajudandigam/agent-inspect/blob/main/docs/NETWORK-BEHAVIOR.md) · No-egress: [NO-EGRESS-POLICY.md](https://github.com/rajudandigam/agent-inspect/blob/main/docs/NO-EGRESS-POLICY.md)
+The generated demo is synthetic, keyless, and local. `npm install agent-inspect` does not copy repository examples; `init` writes them into the project.
 
-## Real-world scenarios
+```bash
+npm install agent-inspect
+npx agent-inspect init --yes
+node examples/agent-inspect-demo.mjs
+npx agent-inspect list --dir .agent-inspect
+```
 
-| Scenario | Start |
-| -------- | ----- |
-| Wrong tool / intentional failure | [broken-agent-debugging](https://github.com/rajudandigam/agent-inspect/tree/main/examples/starters/broken-agent-debugging) |
-| Coding-agent MCP debug loop | [coding-agent-debug-loop](https://github.com/rajudandigam/agent-inspect/tree/main/examples/starters/coding-agent-debug-loop) · [CODING-AGENT-LOOP](https://github.com/rajudandigam/agent-inspect/blob/main/docs/CODING-AGENT-LOOP.md) |
-| CI trajectory gate + Evidence | [ci-eval-redact](https://github.com/rajudandigam/agent-inspect/tree/main/examples/starters/ci-eval-redact) · [langgraph-gate-evidence](https://github.com/rajudandigam/agent-inspect/tree/main/examples/recipes/langgraph-gate-evidence) |
-| Safe incident handoff | [Safe sharing](https://github.com/rajudandigam/agent-inspect/blob/main/docs/SAFE-TRACE-SHARING.md) |
-| Multi-agent / session retry | [Sessions & outcomes](https://github.com/rajudandigam/agent-inspect/blob/main/docs/SESSIONS-AND-OUTCOMES.md) |
-| Customer-owned team review | [Self-hosting](https://github.com/rajudandigam/agent-inspect/blob/main/docs/SELF-HOSTING.md) · Studio (optional) |
+Copy the printed run ID, then inspect it:
 
-## Safety and network behavior
+```bash
+npx agent-inspect view <run-id> --dir .agent-inspect --summary
+npx agent-inspect check <run-id> --dir .agent-inspect --preset trajectory
+npx agent-inspect verify-safe <run-id> --dir .agent-inspect
+```
 
-- 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** — core does not send traces to AgentInspect
-- **Customer-owned Studio ingestion** is disabled by default and explicit when enabled
-- **MCP server** exposes configured local evidence to the connected client (Preview)
-- **Standards export** only when you run/configure it
-- Redaction is **best-effort**, not certification — review before posting
-- **Not** a chain-of-thought recorder
+For a fixed good/regression/PII walkthrough with stable run ids (`demo-good`, `demo-regression`, `demo-pii`), use the [canonical keyless showcase](https://github.com/rajudandigam/agent-inspect/tree/main/examples/starters/broken-agent-debugging). The richer [blessed starters](https://github.com/rajudandigam/agent-inspect/tree/main/examples/starters) cover framework-specific paths.
 
-Details: [Safe sharing](https://github.com/rajudandigam/agent-inspect/blob/main/docs/SAFE-TRACE-SHARING.md) · [Network behavior](https://github.com/rajudandigam/agent-inspect/blob/main/docs/NETWORK-BEHAVIOR.md) · [Security](SECURITY.md)
+## Use it with your stack
 
-## Project status
+| Stack | Install / command | Start |
+| --- | --- | --- |
+| Custom functions or classes | `agent-inspect` | [Getting started](https://github.com/rajudandigam/agent-inspect/blob/main/docs/GETTING-STARTED.md) |
+| LangChain / LangGraph | `agent-inspect` + `@agent-inspect/langchain` | [LangGraph guide](https://github.com/rajudandigam/agent-inspect/blob/main/docs/LANGGRAPH.md) |
+| AI SDK | `agent-inspect` + `@agent-inspect/ai-sdk` | [AI SDK guide](https://github.com/rajudandigam/agent-inspect/blob/main/docs/AI-SDK-ADOPTION.md) |
+| OpenAI Agents JS | `agent-inspect` + `@agent-inspect/openai-agents` | [Local processor guide](https://github.com/rajudandigam/agent-inspect/blob/main/docs/OPENAI-AGENTS-LOCAL.md) |
+| Existing structured logs | `npx agent-inspect logs ...` | [Log-to-tree quickstart](https://github.com/rajudandigam/agent-inspect/blob/main/docs/LOG-TO-TREE-QUICKSTART.md) |
+| OpenInference / OTLP JSON | `npx agent-inspect open ...` | [Standards](https://github.com/rajudandigam/agent-inspect/blob/main/docs/STANDARDS.md) |
+| Vitest / Jest CI | `@agent-inspect/vitest` / `@agent-inspect/jest` | [CI artifacts](https://github.com/rajudandigam/agent-inspect/blob/main/docs/CI-ARTIFACTS.md) |
 
-**Current release:** **6.17.1** · schema **1.0** · Node.js **≥ 20** · **MIT** · **actively maintained** (eighteen linked npm packages).
+See [support levels](https://github.com/rajudandigam/agent-inspect/blob/main/docs/SUPPORT-LEVELS.md) for Stable, Supported, Beta, Preview, and Experimental surfaces.
 
-The 6.16 line is actively maintained for correctness, compatibility, documentation, security, and framework evolution.
+## Programmatic trajectory checks
 
-[Roadmap](ROADMAP.md) · [Changelog](CHANGELOG.md) · [Public product facts](https://github.com/rajudandigam/agent-inspect/blob/main/docs/product/PUBLIC-PRODUCT-FACTS.md)
+```ts
+import { openTraceFile } from "agent-inspect/readers";
+import {
+  defineTraceContract,
+  evaluateTraceContractRead,
+} from "agent-inspect/checks";
 
-## What AgentInspect is not
+const read = await openTraceFile("./trace.jsonl");
+const contract = defineTraceContract({
+  run: { requireCompleted: true },
+  tools: { required: ["retrieve_policy"] },
+});
 
-- Hosted SaaS or maintainer-hosted dashboard
-- Production APM replacement
-- Eval dataset platform or LLM-as-judge by default
-- Prompt registry, pricing engine, or replay engine
-- Universal standards exporter
-- Compliance certification
+const result = evaluateTraceContractRead(read, contract);
+if (result.status !== "pass") process.exitCode = 1;
+```
 
-See [Compare](https://github.com/rajudandigam/agent-inspect/blob/main/docs/COMPARE.md).
+The full API also exposes TraceFacts for bounded, logical analysis of supported traces. See [programmatic trace analysis](https://github.com/rajudandigam/agent-inspect/blob/main/docs/PROGRAMMATIC-TRACE-ANALYSIS.md).
 
-<details>
-<summary><strong>Package family (18 linked packages · tiered presentation)</strong></summary>
+## Where AgentInspect fits
 
-Canonical tiers: [POSITIONING-AND-PORTFOLIO.md](https://github.com/rajudandigam/agent-inspect/blob/main/docs/POSITIONING-AND-PORTFOLIO.md) · [SUPPORT-LEVELS.md](https://github.com/rajudandigam/agent-inspect/blob/main/docs/SUPPORT-LEVELS.md).
+AgentInspect owns the laptop-to-PR evidence loop. It complements hosted observability, production trace retention, and broad eval platforms rather than replacing them.
 
-### Tier A — Flagship
+| Need | Best fit |
+| --- | --- |
+| Inspect one local TypeScript agent run immediately | AgentInspect |
+| Enforce deterministic tool/order/completion expectations in CI | AgentInspect |
+| Attach a redacted, hash-verifiable offline artifact | AgentInspect |
+| Monitor a production fleet with hosted dashboards and retention | Hosted observability / APM |
+| Manage prompts, datasets, and online LLM-judge experiments | Eval / prompt platforms |
 
-| Package | Purpose |
-| ------- | ------- |
-| [`agent-inspect`](https://www.npmjs.com/package/agent-inspect) | Core APIs + CLI + evidence |
-| [`@agent-inspect/redact`](https://www.npmjs.com/package/@agent-inspect/redact) | Deterministic redaction |
-| [`@agent-inspect/mcp-server`](https://www.npmjs.com/package/@agent-inspect/mcp-server) | Read-only MCP coding-agent loop (Preview) |
+See the factual [comparison guide](https://github.com/rajudandigam/agent-inspect/blob/main/docs/COMPARE.md).
 
-### Tier B — Official integrations
+## Safety and network behavior
 
-### Framework adapters
+- Traces are local JSONL under `.agent-inspect/` or `AGENT_INSPECT_TRACE_DIR`.
+- Capture is metadata-only by default; raw prompts and outputs require opt-in.
+- Write-time redaction is enabled by default. The `redact` command creates a separate redacted copy and does not mutate its source.
+- Core capture and inspection do not require an AgentInspect account, collector, or default upload.
+- Redaction and `verify-safe` are best-effort controls, not privacy, security, or compliance certification.
+- Optional MCP, standards export, and customer-owned Studio surfaces are explicit and have their own network boundaries.
+- AgentInspect is not a chain-of-thought recorder.
 
-| Package | Purpose |
-| ------- | ------- |
-| [`@agent-inspect/ai-sdk`](https://www.npmjs.com/package/@agent-inspect/ai-sdk) | AI SDK telemetry |
-| [`@agent-inspect/openai-agents`](https://www.npmjs.com/package/@agent-inspect/openai-agents) | OpenAI Agents processor |
-| [`@agent-inspect/langchain`](https://www.npmjs.com/package/@agent-inspect/langchain) | LangChain / LangGraph callbacks |
+Read [network behavior](https://github.com/rajudandigam/agent-inspect/blob/main/docs/NETWORK-BEHAVIOR.md), [no-egress policy](https://github.com/rajudandigam/agent-inspect/blob/main/docs/NO-EGRESS-POLICY.md), and [safe trace sharing](https://github.com/rajudandigam/agent-inspect/blob/main/docs/SAFE-TRACE-SHARING.md).
 
-### Tier B — Testing / evaluation
+## Optional coding-agent loop
 
-| Package | Purpose |
-| ------- | ------- |
-| [`@agent-inspect/harness`](https://www.npmjs.com/package/@agent-inspect/harness) | Fixture runner |
-| [`@agent-inspect/eval`](https://www.npmjs.com/package/@agent-inspect/eval) | Local eval heuristics |
-| [`@agent-inspect/vitest`](https://www.npmjs.com/package/@agent-inspect/vitest) | Vitest reporter + experimental matchers |
-| [`@agent-inspect/jest`](https://www.npmjs.com/package/@agent-inspect/jest) | Jest reporter + experimental matchers |
+`@agent-inspect/mcp-server` exposes configured local evidence to an MCP client through bounded, read-only tools. It is optional and currently Preview; the core debug/check/evidence loop does not require it.
 
-### Tier C — Optional supporting (Safety)
+```bash
+npx agent-inspect mcp configure --client cursor
+```
 
-| Package | Purpose |
-| ------- | ------- |
-| [`@agent-inspect/redact`](https://www.npmjs.com/package/@agent-inspect/redact) | Deterministic redaction |
-| [`@agent-inspect/guardrails`](https://www.npmjs.com/package/@agent-inspect/guardrails) | Deterministic guardrail rules |
-| [`@agent-inspect/circuit`](https://www.npmjs.com/package/@agent-inspect/circuit) | Loop / retry / timeout analyzers |
+Review the generated dry-run configuration and the [coding-agent loop guide](https://github.com/rajudandigam/agent-inspect/blob/main/docs/CODING-AGENT-LOOP.md) before enabling it.
 
-### Tier C — Optional supporting (Developer surfaces)
+<details>
+<summary><strong>Package family (18-package fixed release group)</strong></summary>
 
-| Package | Purpose |
-| ------- | ------- |
-| [`@agent-inspect/viewer`](https://www.npmjs.com/package/@agent-inspect/viewer) | Localhost viewer |
-| [`@agent-inspect/tui`](https://www.npmjs.com/package/@agent-inspect/tui) | Optional terminal UI |
-| [`@agent-inspect/mcp`](https://www.npmjs.com/package/@agent-inspect/mcp) | MCP client tracing |
-| [`@agent-inspect/mcp-server`](https://www.npmjs.com/package/@agent-inspect/mcp-server) | Read-only MCP server (Preview) |
+| Group | Packages |
+| --- | --- |
+| Core product | `agent-inspect`, `@agent-inspect/redact` |
+| Framework integrations | `@agent-inspect/ai-sdk`, `@agent-inspect/openai-agents`, `@agent-inspect/langchain` |
+| Testing and evaluation | `@agent-inspect/harness`, `@agent-inspect/eval`, `@agent-inspect/vitest`, `@agent-inspect/jest` |
+| Safety analysis | `@agent-inspect/guardrails`, `@agent-inspect/circuit` |
+| Developer surfaces | `@agent-inspect/viewer`, `@agent-inspect/tui`, `@agent-inspect/mcp`, `@agent-inspect/mcp-server` |
+| Local/team optional surfaces | `@agent-inspect/index-sqlite`, `@agent-inspect/studio` |
+| Extension SDK | `@agent-inspect/adapter-sdk` |
 
-### Tier C — Optional supporting (Team / self-hosted)
+The root package is enough for custom capture, the CLI, checks, and Evidence workflows. Install optional packages only for the integration or surface you use. `agent-inspect-vscode` is currently in the repository and is not presented as a published Marketplace extension.
 
-| Package | Purpose |
-| ------- | ------- |
-| [`@agent-inspect/index-sqlite`](https://www.npmjs.com/package/@agent-inspect/index-sqlite) | Optional SQLite index (Beta) |
-| [`@agent-inspect/studio`](https://www.npmjs.com/package/@agent-inspect/studio) | Customer-owned Studio (Beta) |
+</details>
 
-### Tier C — Optional supporting (Extension / interop)
+## What it is not
 
-| Package | Purpose |
-| ------- | ------- |
-| [`@agent-inspect/adapter-sdk`](https://www.npmjs.com/package/@agent-inspect/adapter-sdk) | Third-party adapters (Beta) |
+- A maintainer-hosted SaaS or production APM replacement
+- Hosted trace retention, a team dashboard service, or a prompt registry
+- An LLM-as-judge or dataset platform by default
+- A replay engine, automatic remediation system, or compliance certification
 
-`agent-inspect-vscode` is in-repo (Marketplace not published yet).
+## Status and documentation
 
-</details>
+**Current published baseline:** **6.17.2** · persisted schema `1.0` · Node.js `>=20` · MIT.
 
-## Documentation
+Legacy v0.1 and v0.2 traces remain readable. Check the npm badge and [changelog](CHANGELOG.md) for the current published version.
 
-| | Website | Repo |
-| - | ------- | ---- |
-| Getting started | [docs](https://agentinspect.vercel.app/docs/getting-started/) | [FIRST-TRACE](https://github.com/rajudandigam/agent-inspect/blob/main/docs/FIRST-TRACE-IN-5-MINUTES.md) |
-| TraceFacts / contracts | — | [TRACE-FACTS](https://github.com/rajudandigam/agent-inspect/blob/main/docs/TRACE-FACTS.md) · [TRACE-CONTRACTS](https://github.com/rajudandigam/agent-inspect/blob/main/docs/TRACE-CONTRACTS.md) |
-| Evidence / MCP / no-egress | — | [EVIDENCE-FORMAT](https://github.com/rajudandigam/agent-inspect/blob/main/docs/EVIDENCE-FORMAT.md) · [CODING-AGENT-LOOP](https://github.com/rajudandigam/agent-inspect/blob/main/docs/CODING-AGENT-LOOP.md) · [NO-EGRESS-POLICY](https://github.com/rajudandigam/agent-inspect/blob/main/docs/NO-EGRESS-POLICY.md) |
-| Safe sharing | [safe-sharing](https://agentinspect.vercel.app/docs/safe-sharing/) | [SAFE-TRACE-SHARING](https://github.com/rajudandigam/agent-inspect/blob/main/docs/SAFE-TRACE-SHARING.md) |
-| API / CLI | — | [API](docs/API.md) · [CLI](docs/CLI.md) (packed with npm) |
-| Full index | — | [docs/README.md](https://github.com/rajudandigam/agent-inspect/blob/main/docs/README.md) |
+- [First trace in five minutes](https://github.com/rajudandigam/agent-inspect/blob/main/docs/FIRST-TRACE-IN-5-MINUTES.md)
+- [CLI reference](https://github.com/rajudandigam/agent-inspect/blob/main/docs/CLI.md)
+- [Trace contracts](https://github.com/rajudandigam/agent-inspect/blob/main/docs/TRACE-CONTRACTS.md)
+- [Evidence format](https://github.com/rajudandigam/agent-inspect/blob/main/docs/EVIDENCE-FORMAT.md)
+- [Use cases](https://github.com/rajudandigam/agent-inspect/blob/main/docs/USE-CASES.md)
+- [Demos and screenshots](https://github.com/rajudandigam/agent-inspect/blob/main/docs/SCREENSHOTS.md)
+- [Full documentation index](https://github.com/rajudandigam/agent-inspect/blob/main/docs/README.md)
 
 ## Contributing
 
-[CONTRIBUTING.md](https://github.com/rajudandigam/agent-inspect/blob/main/CONTRIBUTING.md) · [Good first issues](https://github.com/rajudandigam/agent-inspect/blob/main/GOOD-FIRST-ISSUES.md) · [Discussions](https://github.com/rajudandigam/agent-inspect/discussions)
-
-**Redact traces before posting issues or PRs.**
-
-```bash
-pnpm add agent-inspect
-npx agent-inspect doctor
-```
+See [CONTRIBUTING.md](CONTRIBUTING.md), [good first issues](GOOD-FIRST-ISSUES.md), and [GitHub Discussions](https://github.com/rajudandigam/agent-inspect/discussions).
 
-Monorepo: `pnpm install && pnpm build && pnpm test`
+**Redact and review traces before posting them in issues or pull requests.**

package/docs/CLI.md

@@ -322,6 +322,7 @@ Options:
   - `trajectory`: completion/structure/relationship focus; excludes share-safety findings
   - `safety`: raw-content / secret / redaction focus
   - `comprehensive`: union of trajectory and safety
+  - Presets are a base select set. CLI shorthands on the same invocation (`--fail-on-observation`, `--required-tool`, `--forbidden-tool`, `--allowed-model`, `--max-total-tokens`, `--max-duration-ms`, `--max-step-duration`, `--detect-stalls`) extend that set; they are not dropped because the preset already selected rules. Config `checks.select` is not silently expanded with unrelated configured rules.
 - `--evidence-on <fail|always|never>`: write local Evidence v2 (no upload); omitted = never
 - `--evidence-dir <path>`: Evidence output directory or base path
 - `--evidence-profile <local|share|strict>`: redaction profile for Evidence (default `share`)

package/docs/GOLDEN-PATH.md

@@ -1,6 +1,6 @@
 # Golden path
 
-The recommended local evidence path for the current **6.14** release line.
+The recommended local evidence path for the current **6.17.x** release line.
 
 ## Automated packed path (CI)
 

package/docs/SAFE-TRACE-SHARING.md

@@ -28,6 +28,8 @@ Manual traces redact common sensitive keys **before disk** by default. Pass `red
 
 ## Before sharing
 
+When a maintainer or support responder needs reproducible evidence, follow the [safe support reproduction workflow](./SUPPORT-REPRODUCTION.md) to create and review a minimized Evidence bundle. Do not attach a raw trace directory.
+
 - 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.