agent-inspect 6.7.1 → 6.7.3

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## 6.7.3
+
+### Patch Changes
+
+- ac6747d: Corrective patch after 6.7.2: TraceContract allowed-status handling, OpenInference nano timestamp strings, cohort maxRelativeDelta for all numeric metrics, Windows path portability, CLI search --session exit codes, diff/normalizer correctness, Studio auth timing / ingest / bundle dedup, and related test hardening. No schema break; no new product surface.
+
+## Unreleased
+
+## 6.7.2
+
+### Patch Changes
+
+- 9c1f54c: Product presentation patch: rebuild README/docs/package guides/website for the 6.7.x launch candidate, fix public CLI command targets, add docs/link/public-truth validation, and slim the public roadmap. Docs and presentation only — no runtime product expansion.
+
 ## 6.7.1
 
 ### Patch Changes
@@ -199,17 +213,15 @@
 
 - 70f3fb2: v3.1 adoption train: public `@agent-inspect/harness`, `agent-inspect init` and `doctor` commands, adoption starters, and onboarding docs.
 
-## Unreleased
-
-README adoption polish (brand header, product-loop visual, npm link hygiene). Docs-only; no runtime feature changes.
+## Historical (pre-3.5 train notes)
 
-See [docs/implementation/reviews/README-ADOPTION-POLISH-REVIEW.md](docs/implementation/reviews/README-ADOPTION-POLISH-REVIEW.md).
+The v3.0→v3.5 feature train is complete. Older in-progress notes below are kept for history.
 
----
+### README adoption polish (shipped in 3.5.x docs)
 
-## Historical (pre-3.5 train notes)
+README adoption polish (brand header, product-loop visual, npm link hygiene). Docs-only; no runtime feature changes.
 
-The v3.0→v3.5 feature train is complete. Older in-progress notes below are kept for history.
+See [docs/implementation/reviews/README-ADOPTION-POLISH-REVIEW.md](docs/implementation/reviews/README-ADOPTION-POLISH-REVIEW.md).
 
 ### v3.1 (shipped in 3.1.0)
 
@@ -263,9 +275,9 @@ The v3.0→v3.5 feature train is complete. Older in-progress notes below are kep
 
   Adds the public optional `@agent-inspect/vitest` and `@agent-inspect/jest` reporter packages, the shared experimental `agent-inspect/reporters` helpers, and the `agent-inspect ci-summary` workflow for deterministic local reporter manifests and CI artifacts.
 
-## Unreleased
+### Draft notes (superseded by 2.3.0 / 2.4.0 releases)
 
-### Draft v2.4.0 Notes
+#### Draft v2.4.0 Notes
 
 - Added session/workflow causality model and `agent-inspect/advanced` session index helpers (`buildSessionIndex`, scope/cohort helpers, session fixtures).
 - Added `agent-inspect sessions` and `agent-inspect session` CLI for multi-run handoff/retry navigation with timeline, critical-path, diagnostics, and JSON output.
@@ -273,7 +285,7 @@ The v3.0→v3.5 feature train is complete. Older in-progress notes below are kep
 - Added public optional `@agent-inspect/mcp` for local MCP **client** `tools/list` and `tools/call` telemetry with bounded summaries and `source.type: mcp-client` metadata.
 - No schema version change, no MCP gateway/server, no timestamp-only causality inference, and no root/core dependency on MCP SDKs.
 
-### Draft v2.3.0 Notes
+#### Draft v2.3.0 Notes
 
 - Hardened the official adapter paths for AI SDK, OpenAI Agents JS, and LangChain/LangGraph with no-network recipes, local-only defaults, clearer lifecycle coverage, and executable adapter conformance evidence.
 - AI SDK coverage now includes route-style telemetry factory guidance, per-request integration isolation, tool/stream/error/parallel fixtures, token metadata, and the required `recordInputs: false` / `recordOutputs: false` host settings.

package/README.md

@@ -8,11 +8,16 @@
 <h1 align="center">agent-inspect</h1>
 
 <p align="center">
-  <strong>Trace, check, and safely share TypeScript AI-agent runs locally.</strong>
+  <strong>Debug, regression-test, and safely share TypeScript AI-agent behavior—locally.</strong>
 </p>
 
 <p align="center">
-  <sub>No account · no upload · no hosted dashboard · metadata-only by default</sub>
+  <sub>No account · no default upload · metadata-only by default · optional customer-owned Studio</sub>
+</p>
+
+<p align="center">
+  AgentInspect turns agent runs into <strong>customer-owned evidence</strong>: execution trees,
+  deterministic contracts, CI gates, verified-safe bundles, and optional self-hosted review.
 </p>
 
 <p align="center">
@@ -29,151 +34,191 @@
   <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
+```
 
 ## Three workflows
 
-| Workflow | What you do | Start |
-| -------- | ----------- | ----- |
-| **Debug one run** | Capture → inspect → find first error | [60-second quickstart](#60-second-quickstart) |
-| **Prevent one regression** | Typed contracts, suites, CI gates | [Checks](docs/API.md#checks) · [`suite`](docs/CLI.md) |
-| **Share one safe artifact** | Redact → verify-safe → bundle | [Safe sharing](docs/SAFE-TRACE-SHARING.md) |
+| Workflow | What you do |
+| -------- | ----------- |
+| **Debug one run** | Capture/import → tree / timeline / report → first causal failure |
+| **Prevent one regression** | TraceContract / `check` → suite / cohort → CI gate |
+| **Share one safe artifact** | Redact → `verify-safe` → offline bundle → optional Studio review |
 
-```bash
-npm install agent-inspect
-```
+**Review as a team (optional):** workspace + optional SQLite index → customer-owned [Studio Beta](https://github.com/rajudandigam/agent-inspect/tree/main/packages/studio) (no AgentInspect-hosted cloud).
+
+<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">
+</p>
+
+## Five-minute path
 
-## 60-second quickstart
+Commands below match the packed quickstart. Replace `<run-id>` with a value from `list`.
 
 ```bash
+npm install agent-inspect
 npx agent-inspect init --yes
 node examples/agent-inspect-demo.mjs
 npx agent-inspect list --dir .agent-inspect
+```
+
+```bash
+# After copying a run id from list:
 npx agent-inspect view <run-id> --dir .agent-inspect
 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
 ```
 
-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)
+`init` scaffolds config and a demo script; the **demo** writes the trace. Guide: [First trace in 5 minutes](https://agentinspect.vercel.app/docs/getting-started/) · [repo](https://github.com/rajudandigam/agent-inspect/blob/main/docs/FIRST-TRACE-IN-5-MINUTES.md) · [Golden path](https://github.com/rajudandigam/agent-inspect/blob/main/docs/GOLDEN-PATH.md)
 
-<p align="center">
-  <img src="https://raw.githubusercontent.com/rajudandigam/agent-inspect/main/docs/assets/readme-product-loop.svg?sanitize=true" alt="Capture, inspect, check, redact — local JSONL only" width="720">
-</p>
-
-## Choose your path
+## Choose your capture path
 
 | 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 | [`@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 runner / bootstrap | [`@agent-inspect/harness`](packages/harness/README.md) · [NestJS](docs/NESTJS.md) |
+| **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** | Callbacks / LangGraph-via-LangChain | [`@agent-inspect/langchain`](https://www.npmjs.com/package/@agent-inspect/langchain) |
+| **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** | Failed-test artifacts | [`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) |
 
 Blessed starters (no API keys): [examples/starters](https://github.com/rajudandigam/agent-inspect/tree/main/examples/starters)
 
-## What it helps with
+## What you can do after capture
+
+**Understand** — `what` / `view` / tree · timeline · report · diff · sessions / activity  
+
+**Prevent regressions** — deterministic checks · typed TraceContract (Beta) · suites · cohorts · CI gates · Vitest/Jest reporters (artifact reporters today; TraceContract matchers not shipped)  
+
+**Share safely** — redaction profiles · `scan` · `verify-safe` · offline bundles · CI artifacts  
+
+**Scale locally** — workspace · optional SQLite index (Beta) · observed outcomes · viewer / TUI / VS Code  
+
+**Review as a team** — customer-owned Studio Beta · explicit file / GitHub / HTTP ingest (disabled by default) · no maintainer cloud  
+
+**Interoperate** — read-only MCP server (Preview) · OpenInference-compatible / OTLP GenAI-aligned mapping with known-loss reporting  
 
-- **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 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
+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)
 
 ## Real-world scenarios
 
-| 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) |
+| Scenario | Start |
+| -------- | ----- |
+| Wrong tool call | [broken-agent starter](https://github.com/rajudandigam/agent-inspect/tree/main/examples/starters/broken-agent-debugging) |
+| CI trajectory gate | [CI artifacts](https://github.com/rajudandigam/agent-inspect/blob/main/docs/CI-ARTIFACTS.md) |
+| 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 |
+| Design partner trial | [Pilot kit](https://github.com/rajudandigam/agent-inspect/blob/main/docs/PRE-V7-PILOT-KIT.md) |
 
-## Package map
+## Safety and network behavior
+
+- 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
+
+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)
+
+## Project status
+
+**Current release:** **6.7.3** (eighteen linked npm packages). Technical launch candidate; external pilot evidence pending. Persisted schema **1.0**. Node.js **≥ 20**. **v7 not scheduled.**
+
+[Roadmap](ROADMAP.md) · [Pilot kit](https://github.com/rajudandigam/agent-inspect/blob/main/docs/PRE-V7-PILOT-KIT.md) · [Changelog](CHANGELOG.md)
+
+## What AgentInspect is not
+
+- 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 or completed external adoption proof
+
+See [Compare](https://github.com/rajudandigam/agent-inspect/blob/main/docs/COMPARE.md).
+
+<details>
+<summary><strong>Package family (18 public packages)</strong></summary>
+
+### Framework adapters
 
 | Package | Purpose |
 | ------- | ------- |
 | [`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 |
-| [`@agent-inspect/harness`](packages/harness/README.md) | Fixture runner for real projects |
-| [`@agent-inspect/redact`](packages/redact/README.md) | Deterministic redaction |
-| [`@agent-inspect/eval`](packages/eval/README.md) | Local eval heuristics |
-| [`@agent-inspect/vitest`](packages/vitest/README.md) | Vitest reporter |
-| [`@agent-inspect/jest`](packages/jest/README.md) | Jest reporter |
-| [`@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/viewer`](packages/viewer/README.md) | Localhost viewer |
-| [`@agent-inspect/adapter-sdk`](packages/adapter-sdk/README.md) | Third-party adapters |
-| [`@agent-inspect/index-sqlite`](packages/index-sqlite/README.md) | Optional SQLite index |
-| [`@agent-inspect/studio`](packages/studio/README.md) | Customer-owned Studio (Beta) |
-| [`@agent-inspect/tui`](packages/tui/README.md) | Optional terminal UI |
-| `agent-inspect-vscode` | VS Code extension (in-repo; not on Marketplace yet) |
-
-## Safety model
+| [`@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 callbacks |
 
-- 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 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 — review exports before posting
+### Testing / evaluation
 
-Details: [Safe sharing](https://agentinspect.vercel.app/docs/safe-sharing/) · [repo](docs/SAFE-TRACE-SHARING.md) · [Security](SECURITY.md)
+| 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 |
+| [`@agent-inspect/jest`](https://www.npmjs.com/package/@agent-inspect/jest) | Jest reporter |
 
-## Documentation
+### Safety
 
-| | 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) |
+| 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 |
 
-Full index: [docs/README.md](docs/README.md)
+### Developer surfaces
 
-## What AgentInspect is not
+| 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) |
 
-- 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 provider pricing engine
-- Default telemetry uploader or replay engine
+### Team / self-hosted
 
-See [Compare](https://agentinspect.vercel.app/docs/compare/).
+| 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) |
 
-## Install details
+### Extension / interop
 
-Current release: **6.7.1** (eighteen linked npm packages). Technical launch candidate; external pilot evidence pending. Persisted trace schema **1.0**. Requires **Node.js >= 20**.
+| Package | Purpose |
+| ------- | ------- |
+| [`@agent-inspect/adapter-sdk`](https://www.npmjs.com/package/@agent-inspect/adapter-sdk) | Third-party adapters (Beta) |
 
-```bash
-pnpm add agent-inspect
-npx agent-inspect doctor
-```
+`agent-inspect-vscode` is in-repo (Marketplace not published yet).
+
+</details>
 
-Monorepo development: `pnpm install && pnpm build && pnpm test`
+## Documentation
+
+| | 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) |
+| Contracts / suites / gates | — | [TRACE-CONTRACTS](https://github.com/rajudandigam/agent-inspect/blob/main/docs/TRACE-CONTRACTS.md) · [SUITES-COHORTS-GATES](https://github.com/rajudandigam/agent-inspect/blob/main/docs/SUITES-COHORTS-GATES.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) |
 
 ## Contributing
 
-[CONTRIBUTING.md](CONTRIBUTING.md) · [Good first issues](GOOD-FIRST-ISSUES.md) · [Discussions](https://github.com/rajudandigam/agent-inspect/discussions) · [Changelog](CHANGELOG.md)
+[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
+```
+
+Monorepo: `pnpm install && pnpm build && pnpm test`

package/docs/ADOPTION.md

@@ -20,7 +20,7 @@ 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
+npx agent-inspect verify-safe <run-id> --dir .agent-inspect
 ```
 
 No API keys required for the init demo. See [examples/starters/](../examples/starters/README.md).

package/docs/BUNDLES.md

@@ -0,0 +1,67 @@
+# Shareable trace bundles
+
+AgentInspect **bundles** are local, offline folders you can attach to PRs, incident threads, or internal reviews. They combine redacted trace copies, HTML reports, safety check results, and a human summary — without mutating source traces or calling the network.
+
+## Quick start
+
+```bash
+# Single run (default share profile + automatic verify-safe)
+npx agent-inspect bundle <runId> --dir ./.agent-inspect
+
+# Session or time window
+npx agent-inspect bundle --session <sessionId> --dir ./.agent-inspect
+npx agent-inspect bundle --since 24h --profile strict --dir ./.agent-inspect
+
+# Explicit output folder (.zip suffix is stripped — folder-first MVP)
+npx agent-inspect bundle <runId> --out ./my-bundle --json
+```
+
+When a workspace exists, default output goes under `.agent-inspect/bundles/`.
+
+## Bundle layout
+
+```text
+trace.html                 # offline HTML (index for multi-run)
+trace.jsonl                # redacted JSONL copy
+summary.md                 # human overview
+metadata.json              # manifest (version, profile, safe status)
+check-results.json         # verify-safe results per run
+redaction-report.json      # detector summary (no secret values)
+eval-results.json          # placeholder unless eval artifacts are added later
+performance-summary.json   # placeholder unless perf artifacts are added later
+assets/runs/<runId>.*      # per-run HTML + JSONL mirrors
+```
+
+## Safety defaults
+
+| Setting | Default |
+| ------- | ------- |
+| Redaction profile | `share` |
+| verify-safe | Runs automatically before write |
+| UNSAFE traces | Command fails unless `--allow-unsafe` |
+| Source traces | Read-only; never modified |
+
+Profiles:
+
+- **`share`** — PR / internal support (default)
+- **`strict`** — external or public sharing
+- **`local`** — minimal redaction for local archives only
+
+## When to use bundles vs other commands
+
+| Need | Command |
+| ---- | ------- |
+| One redacted file | `redact` |
+| Safety scan only | `verify-safe` |
+| CI artifact set | `artifacts` |
+| PR-ready evidence folder | **`bundle`** |
+
+## Review before sharing
+
+Bundles are **derived copies**, not compliance certification. Always review `summary.md`, `check-results.json`, and `trace.html` before attaching to tickets or PRs.
+
+See also [SAFE-TRACE-SHARING.md](./SAFE-TRACE-SHARING.md) and [CLI.md §6.24](./CLI.md#624-bundle).
+
+## RFC
+
+Design details: [proposals/SHAREABLE-BUNDLES-V4.3.md](./proposals/SHAREABLE-BUNDLES-V4.3.md).

package/docs/COMPARE.md

@@ -10,11 +10,12 @@ AgentInspect is a local-first trace workbench for TypeScript AI agents: capture
 | --------- | ------------ | --------------------------------------- | --------------------------- | ------------------------------- |
 | Where traces live | Local JSONL on your disk | Vendor or self-hosted backend | Vendor backend | Your collector + backend |
 | Account / setup | None; `npm install` + CLI | Account or deployment | Account | SDK + collector + backend |
-| Primary surface | CLI (`view`, `report`, `diff`, `check`), local viewer, in-repo VS Code extension | Web dashboards | Web dashboards, eval UI | Dashboards, alerting |
+| Primary surface | CLI (`view`, `report`, `diff`, `check`, suites/gates), local viewer, optional Studio Beta | Web dashboards | Web dashboards, eval UI | Dashboards, alerting |
 | Evals | Deterministic local heuristics and CI gates (`check`, `eval`, `circuit`, `guardrails`) | Platform evals | Datasets, scoring, regressions at scale | Not the focus |
 | Retention / fleet view | Not the goal | Strong | Strong | Strong |
 | Data sharing | Explicit `redact` + `scan` / `verify-safe` before you share a file | Team access controls | Team access controls | Org pipelines |
-| Network behavior | No upload; everything stays local unless you share a file | Uploads traces by design | Uploads by design | Ships telemetry by design |
+| Network behavior | No default upload; explicit customer-owned ingest only | Uploads traces by design | Uploads by design | Ships telemetry by design |
+| Team review | Optional customer-owned Studio Beta (not maintainer-hosted) | Strong | Strong | Strong |
 
 If you need hosted retention, fleet dashboards, dataset management, or org-wide pipelines, use one of those platforms alongside AgentInspect. Boundaries are listed in [LIMITATIONS.md](./LIMITATIONS.md); concrete inner-loop workflows in [USE-CASES.md](./USE-CASES.md).
 

package/docs/DEMO-SCRIPT.md

@@ -42,19 +42,20 @@ 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
+npx agent-inspect check <run-id> --dir .agent-inspect
 ```
 
-Mention `--detect-stalls` and `--max-step-duration 30s` for long-running agents.
+Optional flags: `--require-completed`, `--detect-stalls`, `--max-step-duration 30s`.
 
 ## 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
+npx agent-inspect redact <run-id> --dir .agent-inspect --profile share -o safe.jsonl
+npx agent-inspect verify-safe <run-id> --dir .agent-inspect
+# or: npx agent-inspect verify-safe safe.jsonl
 ```
 
-"Redacted copy is safe to attach to a GitHub issue or Slack."
+"Redacted / verified-safe artifacts are safe to attach to a GitHub issue or Slack."
 
 ## Beat 6 — Fix and diff (optional, 30s)
 

package/docs/EXPORTS.md

@@ -36,6 +36,14 @@ agent-inspect export minimal-success --dir fixtures/traces --format markdown
 - **HTML:** export writes a local file; a rendered-report visual is pending re-record ([RECORDING.md](./assets/demos/RECORDING.md)). Use `agent-inspect export <run-id> --format html -o report.html` and open the file locally.
 - **OpenInference / OTLP JSON:** compatibility-oriented shapes for local handoff — validate with `--validate` before sharing. No dedicated GIF; see format tables below.
 
+### Fixture-backed export evidence
+
+The canonical OpenInference export of a persisted schema **1.0** trace is committed at
+[`fixtures/standards/openinference-export-golden.json`](../fixtures/standards/openinference-export-golden.json)
+(generated from `fixtures/traces-v1.0/manual-basic.jsonl`; regeneration is asserted byte-stable in
+`packages/core/test/exporters/openinference-export-golden.test.ts`). Nanosecond timestamps are decimal strings,
+matching the import fixtures and the OTLP exporter.
+
 ## Common options
 
 | Flag | Notes |
@@ -90,6 +98,7 @@ Prefer the smallest useful artifact — a summary or synthetic reproduction beat
 
 ## Related docs
 
+- [STANDARDS-GRADUATION.md](./STANDARDS-GRADUATION.md) — export → review → optional import path
 - [CLI.md](./CLI.md) — `export` command reference
 - [SCHEMA.md](./SCHEMA.md) — trace event model and redaction notes
 - [SAFE-TRACE-SHARING.md](./SAFE-TRACE-SHARING.md) — checklist before posting

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

@@ -1,13 +1,23 @@
 # First trace in 5 minutes
 
-Goal: install → one trace → one check → one share-safe artifact.
+Goal: install → one trace → one check → one share-safe bundle.
 
 **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
-npx agent-inspect check .agent-inspect/*.jsonl && npx agent-inspect verify-safe --dir .agent-inspect
+npm install agent-inspect
+npx agent-inspect init --yes
+node examples/agent-inspect-demo.mjs
+npx agent-inspect list --dir .agent-inspect
+```
+
+Copy a `<run-id>` from `list`, then:
+
+```bash
+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
 ```
 
 ## Minutes 0–1: Install
@@ -18,7 +28,8 @@ npm install agent-inspect
 npx agent-inspect init --yes
 ```
 
-Creates `agent-inspect.config.ts`, `.agent-inspect/`, and `examples/agent-inspect-demo.mjs`.
+Creates `agent-inspect.config.ts`, `.agent-inspect/`, and `examples/agent-inspect-demo.mjs`.  
+`init` scaffolds files; it does **not** write a trace by itself.
 
 ## Minutes 1–2: Run
 
@@ -39,17 +50,23 @@ npx agent-inspect report <run-id> --dir .agent-inspect
 ## Minutes 3–4: Check
 
 ```bash
-npx agent-inspect check .agent-inspect/*.jsonl
+npx agent-inspect check <run-id> --dir .agent-inspect
 ```
 
 ## Minutes 4–5: Share-safe artifact
 
 ```bash
-npx agent-inspect redact --profile share --dir .agent-inspect
-npx agent-inspect verify-safe --dir .agent-inspect
+npx agent-inspect bundle <run-id> --dir .agent-inspect --profile share
+npx agent-inspect verify-safe <run-id> --dir .agent-inspect
 ```
 
-Attach redacted JSONL to a PR or issue — not raw traces.
+Attach the share-profile bundle (or a redacted file) to a PR or issue — not raw traces.
+
+Optional file redaction:
+
+```bash
+npx agent-inspect redact <run-id> --dir .agent-inspect --profile share -o redacted.jsonl
+```
 
 ## Next steps
 
@@ -58,7 +75,8 @@ Attach redacted JSONL to a PR or issue — not raw traces.
 | 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) |
+| CI tests | [CI artifacts](./CI-ARTIFACTS.md) · [Suites / gates](./SUITES-COHORTS-GATES.md) |
+| Golden path | [GOLDEN-PATH.md](./GOLDEN-PATH.md) |
 | Broken agent demo | [broken-agent-debugging starter](../examples/starters/broken-agent-debugging/README.md) |
 
 Full index: [docs/README.md](./README.md) · Website docs: [agentinspect.vercel.app/docs](https://agentinspect.vercel.app/docs/)