agent-inspect 6.12.0 → 6.12.2

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## 6.12.2
+
+### Patch Changes
+
+- a3c0daa: Logical lifecycle projection for built-in checks and TraceContract: additive experimental `logicalEvents` (raw `events` unchanged), v0.1 start/complete pairing, stepId parent normalization, nested tool identity, and `metadata.tokens.*` safe metrics. Eval/gate/Evidence/MCP inherit via `runTraceChecks`. Includes anonymized pilot-shaped fixture and packed check→gate→bundle→verify E2E. No schema break; no new packages; no default network.
+
+## Unreleased
+
+## 6.12.1
+
+### Patch Changes
+
+- 2a53751: Example-heavy presentation patch: align website/README/starters/docs with the 6.12 hero flow (causal failure, MCP coding-agent loop, Evidence v2), fix incomplete redact/verify-safe command examples, and extend docs:commands to starters. Docs and presentation only — no runtime product expansion.
+
 ## 6.12.0
 
 ### Minor Changes

package/README.md

@@ -72,14 +72,32 @@ 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
+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
 ```
 
-`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)
+`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) · [Coding-agent loop](https://github.com/rajudandigam/agent-inspect/blob/main/docs/CODING-AGENT-LOOP.md)
+
+## Why AgentInspect
+
+**Unique position:** a local **evidence debugger** for TypeScript agents—not a hosted APM, eval host, or prompt registry. Complements LangSmith/Langfuse/Phoenix; owns the laptop → PR loop.
+
+**Proven mechanisms (shipped):**
+
+| Mechanism | What you get |
+| --------- | ------------ |
+| Faithful execution trees | Nested steps, tools, LLMs, status, duration on disk |
+| First causal failure | Conservative ordered engine for what failed first |
+| Deterministic checks / TraceContract (Beta) | Trajectory expectations without an LLM judge |
+| Share-checked Evidence v2 | `bundle` + `bundle verify` offline artifacts |
+| Read-only MCP coding-agent loop (Preview) | `mcp configure` + `@agent-inspect/mcp-server` over local traces |
+
+No fabricated adoption counts. External pilot evidence is still pending—see [Pilot kit](https://github.com/rajudandigam/agent-inspect/blob/main/docs/PRE-V7-PILOT-KIT.md).
 
 ## Choose your capture path
 
@@ -116,13 +134,16 @@ Support labels: [SUPPORT-LEVELS.md](https://github.com/rajudandigam/agent-inspec
 
 | 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) |
+| 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 + redact | [ci-eval-redact](https://github.com/rajudandigam/agent-inspect/tree/main/examples/starters/ci-eval-redact) · [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 |
+| Customer-owned team review | [Self-hosting](https://github.com/rajudandigam/agent-inspect/blob/main/docs/SELF-HOSTING.md) · Studio (optional) |
 | Design partner trial | [Pilot kit](https://github.com/rajudandigam/agent-inspect/blob/main/docs/PRE-V7-PILOT-KIT.md) |
 
+All blessed starters (no API keys): [examples/starters](https://github.com/rajudandigam/agent-inspect/tree/main/examples/starters)
+
 ## Safety and network behavior
 
 - Traces are **local JSONL** under `.agent-inspect/` (or `AGENT_INSPECT_TRACE_DIR`)
@@ -138,7 +159,7 @@ Details: [Safe sharing](https://github.com/rajudandigam/agent-inspect/blob/main/
 
 ## Project status
 
-**Current release:** **6.12.0** (eighteen linked npm packages). Technical launch candidate; external pilot evidence pending. Persisted schema **1.0**. Node.js **≥ 20**. **v7 not scheduled.**
+**Current release:** **6.12.2** (eighteen linked npm packages). Stable launch candidate; eight-week adoption checkpoint in progress; 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)
 

package/docs/ADOPTION.md

@@ -47,7 +47,7 @@ Copyable task kits (LangGraph, portable evidence, AI SDK, OpenAI Agents, CI): [I
 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
+4. **Share safely** — `redact <run-id> --dir .agent-inspect --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

package/docs/DEMO-SCRIPT.md

@@ -1,10 +1,13 @@
-# Live demo script (~3 minutes)
+# Live demo script (~4 minutes)
 
-**Audience:** TypeScript developers debugging AI agents.  
-**Prereqs:** Node 20+. Consumers: `npm install agent-inspect`. Monorepo: `pnpm build` at repo root.  
+**Audience:** TypeScript developers debugging AI agents.
+**Prereqs:** Node 20+. Consumers: `npm install agent-inspect@6.12.1`. Monorepo: `pnpm build` at repo root.
 **Website:** [https://agentinspect.vercel.app/](https://agentinspect.vercel.app/)
 
-**Blessed demo starter:** [broken-agent-debugging](../examples/starters/broken-agent-debugging/) — intentional tool failure, no API keys.
+**Blessed demo starters:**
+
+- [broken-agent-debugging](../examples/starters/broken-agent-debugging/) — intentional tool failure, no API keys
+- [coding-agent-debug-loop](../examples/starters/coding-agent-debug-loop/) — MCP inspect + share-checked evidence, no API keys
 
 ## Setup (before the call)
 
@@ -39,39 +42,52 @@ npx agent-inspect timeline <run-id> --dir .agent-inspect
 
 Optional: `npx agent-inspect serve --dir .agent-inspect` for browser viewer.
 
-## Beat 4 — Verify (30s)
+## Beat 4 — Verify / CI gate (30s)
 
 ```bash
 npx agent-inspect check <run-id> --dir .agent-inspect
 ```
 
 Optional flags: `--require-completed`, `--detect-stalls`, `--max-step-duration 30s`.
+For CI artifact demos: `npx agent-inspect artifacts <run-id> --dir .agent-inspect -o ./ci-out`.
 
-## Beat 5 — Share safely (30s)
+## Beat 5 — Share-checked evidence (Evidence v2) (45s)
 
 ```bash
+npx agent-inspect bundle <run-id> --dir .agent-inspect --format html -o ./evidence-out
+npx agent-inspect bundle verify ./evidence-out
+# lighter alternative:
 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 / verified-safe artifacts are safe to attach to a GitHub issue or Slack."
+"Share-checked evidence is best-effort local policy — not a compliance certification. Safe to attach to a GitHub issue or Slack when assessment allows."
 
-## Beat 6 — Fix and diff (optional, 30s)
+## Beat 6 — MCP coding-agent loop (optional, 45s)
+
+```bash
+npx agent-inspect mcp configure --client cursor
+cd ../coding-agent-debug-loop
+pnpm install && pnpm start && pnpm run inspect-mcp
+```
+
+Point to [CODING-AGENT-LOOP.md](./CODING-AGENT-LOOP.md). Stay read-only; do not claim a live partner session unless one is on the call.
+
+## Beat 7 — Fix and diff (optional, 30s)
 
 ```bash
 pnpm run fixed
 npx agent-inspect diff .agent-inspect/<broken-run>.jsonl .agent-inspect/<fixed-run>.jsonl
 ```
 
-## Beat 7 — Close (15s)
+## Beat 8 — Close (15s)
 
-"Starters for AI SDK, OpenAI Agents, LangChain, CI, and NestJS harness are in `examples/starters/`. Fresh repos: `npx agent-inspect init --yes`."
+"Starters for AI SDK, OpenAI Agents, LangChain, CI, NestJS harness, and the MCP coding-agent loop are in `examples/starters/`. Fresh repos: `npx agent-inspect init --yes`."
 
 ## Alternative opener (zero clone)
 
 ```bash
-npm install agent-inspect
+npm install agent-inspect@6.12.1
 npx agent-inspect init --yes
 node examples/agent-inspect-demo.mjs
 npx agent-inspect list --dir .agent-inspect
@@ -84,17 +100,6 @@ See [FIRST-TRACE-IN-5-MINUTES.md](./FIRST-TRACE-IN-5-MINUTES.md).
 - **VS Code:** F5 from `packages/vscode` (dev host) — Marketplace listing pending
 - **Doctor:** `npx agent-inspect doctor` when onboarding fails
 - **Framework:** switch to `examples/starters/ai-sdk` for adapter path
+- **CI starter:** `examples/starters/ci-eval-redact`
 
-Related: [VIDEO-WALKTHROUGH-SCRIPT.md](./VIDEO-WALKTHROUGH-SCRIPT.md) · [SCREENSHOTS.md](./SCREENSHOTS.md)
-
-
-## Optional MCP beat (30s)
-
-If time allows after inspect:
-
-```bash
-npx agent-inspect mcp configure --client cursor --dry-run
-npx @agent-inspect/mcp-server --dir .agent-inspect --help
-```
-
-Point to [CODING-AGENT-LOOP.md](./CODING-AGENT-LOOP.md) and the coding-agent-debug-loop starter. Stay read-only; do not claim a live partner session unless one is on the call.
+Related: [VIDEO-WALKTHROUGH-SCRIPT.md](./VIDEO-WALKTHROUGH-SCRIPT.md) · [SCREENSHOTS.md](./SCREENSHOTS.md) · [PRE-V7-PILOT-KIT.md](./PRE-V7-PILOT-KIT.md) · [EVIDENCE-FORMAT.md](./EVIDENCE-FORMAT.md)

package/docs/DESIGN-PARTNER-GUIDE.md

@@ -3,13 +3,15 @@
 Thank you for trying AgentInspect early. This doc is the **evaluation contract** — what we ask you to try, what we measure, and what we won't do.
 
 **Website:** [https://agentinspect.vercel.app/](https://agentinspect.vercel.app/) · **Docs:** [https://agentinspect.vercel.app/docs/](https://agentinspect.vercel.app/docs/)
+**Baseline:** `agent-inspect@6.12.0` (stable launch candidate; adoption checkpoint in progress)
 
 ## What we're validating
 
 1. **First trace < 30 minutes** from `npm install` (with `init` + a starter)
 2. **First CI check** on a real or fixture trace
-3. **Share-safe workflow** — redacted artifact attached to an issue or PR
-4. **Framework fit** — AI SDK, OpenAI Agents, or LangChain path feels native enough
+3. **Share-checked evidence** — `bundle` / `verify-safe` artifact attached to an issue or PR (not a compliance certification)
+4. **MCP coding-agent loop** (optional) — read-only inspect → fix → re-inspect with `@agent-inspect/mcp-server`
+5. **Framework fit** — AI SDK, OpenAI Agents, or LangChain path feels native enough
 
 ## Your path
 
@@ -18,20 +20,24 @@ Thank you for trying AgentInspect early. This doc is the **evaluation contract**
 | 1 | Run `init` + one starter | `list` shows a run |
 | 1 | `doctor` clean | No failed checks |
 | 2 | Wire adapter or `observe()` in your app | Real trace captured |
-| 2 | `check` or `eval` in CI | Job fails on bad fixture |
-| 3 | `redact --profile share` | Comfortable posting trace externally |
+| 2 | `check` or `artifacts` in CI | Job fails on bad fixture |
+| 3 | `bundle` + `bundle verify` (or `redact <run-id> --profile share` + `verify-safe <run-id>`) | Comfortable posting evidence externally |
+| 3–4 | Optional: `mcp configure` + [coding-agent-debug-loop](../examples/starters/coding-agent-debug-loop/) | Repeated local MCP debug loop |
 | 4 | Feedback session | Case study draft or structured notes |
 
 ## What we provide
 
-- Starters: [examples/starters/](../examples/starters/README.md)
+- Starters: [examples/starters/](../examples/starters/README.md) (incl. `broken-agent-debugging`, `coding-agent-debug-loop`, `ci-eval-redact`)
+- Evidence format: [EVIDENCE-FORMAT.md](./EVIDENCE-FORMAT.md)
+- MCP loop: [CODING-AGENT-LOOP.md](./CODING-AGENT-LOOP.md)
 - Office hours async via GitHub Discussions / Issues
 - [DEMO-SCRIPT.md](./DEMO-SCRIPT.md) for internal team demos
+- Pilot kit overview: [PRE-V7-PILOT-KIT.md](./PRE-V7-PILOT-KIT.md)
 
 ## What we ask from you
 
 - **Structured feedback** (template below) — not vague "looks good"
-- **Redacted traces** only — never raw secrets
+- **Share-checked / redacted artifacts only** — never raw secrets
 - Permission to quote anonymously unless you approve public case study
 
 ## Feedback template
@@ -40,15 +46,21 @@ Thank you for trying AgentInspect early. This doc is the **evaluation contract**
 ### Environment
 - Node version:
 - Framework:
-- AgentInspect version:
+- AgentInspect version: (please use 6.12.0)
 
 ### First trace
 - Time to first trace:
 - Blockers:
 
-### CI
-- check/eval used?
-- Rules that mattered:
+### CI / evidence
+- check / artifacts / bundle used?
+- Rules or gates that mattered:
+- Attached share-checked evidence? (yes/no)
+
+### MCP (if tried)
+- Client (Cursor / Claude Code / Codex / Gemini / other):
+- Repeated debug loop? (yes/no):
+- Blockers:
 
 ### Gaps
 - Missing docs:
@@ -65,6 +77,7 @@ We track adoption from **public signals** and **your reports** only. See [produc
 - Hosted dashboards or SaaS
 - Custom adapter development on our roadmap without demand gates
 - SLAs — this is open-source MIT software
+- Treating `verify-safe` / evidence assessment as a compliance certification
 
 ## Contact
 

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

@@ -58,6 +58,7 @@ npx agent-inspect check <run-id> --dir .agent-inspect
 ```bash
 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>
 ```
 
 Attach the share-profile bundle (or a redacted file) to a PR or issue — not raw traces.
@@ -72,11 +73,13 @@ npx agent-inspect redact <run-id> --dir .agent-inspect --profile share -o redact
 
 | If you use… | Go to |
 | ----------- | ----- |
+| Broken agent demo | [broken-agent-debugging starter](../examples/starters/broken-agent-debugging/README.md) |
+| Coding-agent MCP loop | [CODING-AGENT-LOOP.md](./CODING-AGENT-LOOP.md) · [coding-agent-debug-loop](../examples/starters/coding-agent-debug-loop/README.md) |
+| Contracts / CI gates | [TRACE-CONTRACTS.md](./TRACE-CONTRACTS.md) · [SUITES-COHORTS-GATES.md](./SUITES-COHORTS-GATES.md) |
 | 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) · [Suites / gates](./SUITES-COHORTS-GATES.md) |
+| CI tests | [CI artifacts](./CI-ARTIFACTS.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/)

package/docs/GOLDEN-PATH.md

@@ -1,6 +1,6 @@
-# Golden path (technical launch candidate)
+# Golden path (stable launch candidate)
 
-The 6.7.x technical launch candidate path. Be precise about what is automated today.
+The **6.12.0** stable launch candidate path. Be precise about what is automated today.
 
 ## Automated packed path (CI)
 

package/docs/KNOWN-ISSUES.md

@@ -34,6 +34,7 @@ AgentInspect is **local-first** and **CLI-first**. These behaviors are intention
 - **LangChain adapter** captures **metadata-oriented** signals by default; it does not replace full framework observability.
 - **LangChain `stream: true`** records chunk counts and timing only — not a full token replay. Per-token JSONL events are not emitted.
 - **Correlation metadata** (`correlationId`, `requestId`, `decisionId`, `groupId`) is written on `run_started` but **CLI list/view does not filter by correlation fields** yet.
+- **Built-in check/contract semantics (6.12.2+)** use an additive `logicalEvents` projection that pairs v0.1 start/complete rows. Custom rules that only read raw `context.events` still see bridged `running` TOOL starts and separate LOGIC completions—opt into `logicalEvents` for lifecycle-aware matching. Formal `TraceFacts` promotion is planned for 6.13.
 
 ## Structured log parsing
 

package/docs/PRE-V7-PILOT-KIT.md

@@ -1,45 +1,71 @@
 # Pre-v7 Pilot Kit
 
-**Purpose:** External design-partner and three-team pilot evidence for the 6.7.x technical launch candidate.  
+**Purpose:** External design-partner and three-team pilot evidence for the **6.12.0** stable launch candidate during the v6.12 adoption checkpoint.
 **Do not fabricate results.** Record only real partner outcomes in [implementation/PRE-V7-ADOPTION-EVIDENCE.md](implementation/PRE-V7-ADOPTION-EVIDENCE.md).
+**Do not invent partner names, emails, or acceptance rows.** Outreach templates (placeholders only) live in [implementation/ADOPTION-OUTREACH-CHECKLIST.md](implementation/ADOPTION-OUTREACH-CHECKLIST.md) — do not send outreach from this kit automatically.
 
 ## What is shipping for partners
 
 | Item | Version / path |
 |------|----------------|
-| npm | `agent-inspect@6.7.1` (and fixed-group packages) |
+| npm | `agent-inspect@6.12.0` (and fixed-group packages) |
 | Quickstart | `npx agent-inspect init --yes` → demo → `list` → `verify-safe` |
 | Packed E2E (maintainers) | `pnpm run pack:smoke` |
 | Demo script | [DEMO-SCRIPT.md](DEMO-SCRIPT.md) |
 | Design partner guide | [DESIGN-PARTNER-GUIDE.md](DESIGN-PARTNER-GUIDE.md) |
 | Broken-agent starter | `examples/starters/broken-agent-debugging` |
+| Coding-agent MCP loop | `examples/starters/coding-agent-debug-loop` · [CODING-AGENT-LOOP.md](CODING-AGENT-LOOP.md) |
+| Evidence v2 | `agent-inspect bundle` / `bundle verify` · [EVIDENCE-FORMAT.md](EVIDENCE-FORMAT.md) |
+| MCP configure | `npx agent-inspect mcp configure --client cursor` (also claude-code, codex, gemini) |
+| CI artifacts | `agent-inspect check` / `artifacts` · `examples/starters/ci-eval-redact` |
 | Studio (Beta) | `@agent-inspect/studio` — customer-owned, local |
 
 ## Partner trial checklist (copy per team)
 
-1. Install `agent-inspect@6.7.1` on Node ≥ 20.
+1. Install `agent-inspect@6.12.0` on Node ≥ 20.
 2. Complete five-minute quickstart (init → one run → verify-safe).
 3. Run at least one framework path (AI SDK, OpenAI Agents, or LangChain) **or** observe/manual path.
-4. Optionally run Studio against a local workspace.
-5. Optionally retain a CI check/suite gate on a PR.
-6. Return dated findings: blockers, what worked, whether they will keep using it.
+4. **Evidence path:** create a share-checked bundle and verify integrity:
+   ```bash
+   npx agent-inspect bundle <run-id> --dir .agent-inspect --format html -o ./evidence-out
+   npx agent-inspect bundle verify ./evidence-out
+   ```
+5. **MCP path (optional but preferred for §19 MCP indicator):** configure a client (dry-run first), then run the coding-agent debug loop starter:
+   ```bash
+   npx agent-inspect mcp configure --client cursor
+   cd examples/starters/coding-agent-debug-loop && pnpm install && pnpm start && pnpm run inspect-mcp
+   ```
+6. **CI path (optional):** retain `check` / `artifacts` (or `ci-eval-redact` starter) on a PR.
+7. Optionally run Studio against a local workspace.
+8. Return dated findings: blockers, what worked, whether they will keep using it.
 
-## Evidence required before distinct 6.8.0
+## Blessed demo flows (6.12.0)
 
-From the canonical roadmap:
+| Flow | Starter / commands | Shows |
+|------|-------------------|--------|
+| Broken → inspect → share | `broken-agent-debugging` + [DEMO-SCRIPT.md](DEMO-SCRIPT.md) | Tree, check, redact, verify-safe |
+| Evidence v2 | `bundle` → `bundle verify` | Share-checked offline evidence |
+| MCP coding-agent loop | `coding-agent-debug-loop` + `mcp configure` | Read-only inspect → fix → re-inspect → evidence |
+| CI retention | `ci-eval-redact` or `check`/`artifacts` in CI | Contract/gate on a PR |
 
-- One design-partner Studio trial (sign-off row)
-- Three **external** teams with golden-path trial
-- At least one retained CI contract/gate per pilot set
-- At least one Studio trial in the pilot set
-- Dated findings — no internal-only rows
+## Evidence required for a strong v7 go input
+
+From the adoption checkpoint / canonical roadmap §19:
+
+- 3–5 design partners with dated findings
+- 2–3 retained CI/evidence workflows (external)
+- 2 repeated MCP debug loops (external)
+- 1 public external integration / case study
+- Organic usage that persists beyond release spikes
+
+Empty / `_pending_` ledger rows mean “not yet evidenced,” not product failure.
 
 ## Maintainer stop condition
 
-When this kit is prepared and 6.7.1 is on npm:
+While the adoption checkpoint is active and external rows remain pending:
 
 ```text
-trainStatus: blocked-on-external-pilot
+trainStatus: in-progress (v6.12-adoption-checkpoint)
 ```
 
 Do **not** schedule or implement v7 until adoption gates in [implementation/release-trains/V7.0.0-READINESS-ASSESSMENT.md](implementation/release-trains/V7.0.0-READINESS-ASSESSMENT.md) are met and a maintainer explicitly authorizes a v7 train.

package/docs/SUPPORT-LEVELS.md

@@ -1,6 +1,6 @@
 # Support levels
 
-Canonical maturity labels for AgentInspect public packages and major surfaces (6.7.x).
+Canonical maturity labels for AgentInspect public packages and major surfaces (6.12.x fixed release line).
 
 ## Definitions
 

package/docs/TEAM-WORKFLOWS.md

@@ -7,7 +7,7 @@ How teams adopt AgentInspect without a hosted platform.
 1. `npm install agent-inspect && npx agent-inspect init --yes`
 2. Run demo: `node examples/agent-inspect-demo.mjs`
 3. `npx agent-inspect view <run-id>`
-4. Before posting issues: `npx agent-inspect redact --profile share`
+4. Before posting issues: `npx agent-inspect redact <run-id> --dir .agent-inspect --profile share -o safe.jsonl`
 
 ## PR / code review
 

package/docs/TECHNICAL-GUIDE.md

@@ -408,7 +408,7 @@ See [LIMITATIONS.md](./LIMITATIONS.md).
 | 2 | Eval failure — which step? | `check`, `@agent-inspect/vitest` | [ci-eval-redact](../examples/starters/ci-eval-redact/) |
 | 3 | CI PR artifact | upload + `redact` + `verify-safe` | [CI-ARTIFACTS.md](./CI-ARTIFACTS.md) |
 | 4 | Framework-native trace | adapter packages | [starters](../examples/starters/) |
-| 5 | Safe incident handoff | `redact --profile share` | [SAFE-TRACE-SHARING.md](./SAFE-TRACE-SHARING.md) |
+| 5 | Safe incident handoff | `redact <run-id> --profile share` | [SAFE-TRACE-SHARING.md](./SAFE-TRACE-SHARING.md) |
 | 6 | Multi-agent / sessions | `sessions`, `search`, `diff` | [USE-CASES.md](./USE-CASES.md) |
 | 7 | MCP tool tracing | `@agent-inspect/mcp` | [ADAPTERS.md](./ADAPTERS.md) |
 | 8 | Team adoption sprint | one agent, one check, one artifact | [DESIGN-PARTNER-GUIDE.md](./DESIGN-PARTNER-GUIDE.md) |
@@ -446,7 +446,7 @@ AgentInspect is a local-first TypeScript toolkit for AI agents. It writes execut
 When an agent calls the wrong tool or a test fails, flat logs are not enough. AgentInspect captures runs and nested steps locally, lets you `report` and `diff` failures, and gates CI with deterministic `check` rules — no LLM judge. Framework adapters exist for AI SDK, OpenAI Agents, and LangChain. Metadata-only by default; redact before posting traces anywhere.
 
 **120 seconds (technical):**  
-Add `observe()` or a framework adapter, get JSONL under `.agent-inspect/`, then use `agent-inspect list`, `view`, `report`, `check`, and `redact --profile share`. Sixteen npm packages cover adapters, eval, redaction, MCP tracing, harness fixtures, and test reporters. Schema 1.0 persisted events; readers handle 0.1/0.2/1.0. Not production APM — local debug and share-safe artifacts first.
+Add `observe()` or a framework adapter, get JSONL under `.agent-inspect/`, then use `agent-inspect list`, `view`, `report`, `check`, and `redact <run-id> --profile share`. Sixteen npm packages cover adapters, eval, redaction, MCP tracing, harness fixtures, and test reporters. Schema 1.0 persisted events; readers handle 0.1/0.2/1.0. Not production APM — local debug and share-safe artifacts first.
 
 ### 16.2 Pull quotes (factual)
 

package/docs/USE-CASES.md

@@ -17,7 +17,12 @@ 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`.
+**Safety:** Metadata-only default. Redact before sharing:
+
+```bash
+npx agent-inspect redact <run-id> --dir .agent-inspect --profile share -o safe.jsonl
+npx agent-inspect verify-safe <run-id> --dir .agent-inspect
+```
 
 **Starter:** [broken-agent-debugging](../examples/starters/broken-agent-debugging/README.md) (intentional failure) or [custom-observe](../examples/starters/custom-observe/README.md)
 
@@ -32,7 +37,7 @@ npx agent-inspect report <run-id> --dir .agent-inspect
 **Use:** `@agent-inspect/vitest` or `npx agent-inspect check`.
 
 ```bash
-npx agent-inspect check .agent-inspect/*.jsonl --require-completed
+npx agent-inspect check <run-id> --dir .agent-inspect
 ```
 
 **Starter:** [ci-eval-redact](../examples/starters/ci-eval-redact/README.md)
@@ -43,7 +48,7 @@ npx agent-inspect check .agent-inspect/*.jsonl --require-completed
 
 **Problem:** Reviewers need safe evidence without cloning your laptop.
 
-**Use:** CI upload + `redact --profile share` + `verify-safe`.
+**Use:** CI upload + `redact <run-id> --dir … --profile share` + `verify-safe <run-id>` + optional `bundle` / `bundle verify`.
 
 **Doc:** [CI artifacts](./CI-ARTIFACTS.md)
 
@@ -63,7 +68,7 @@ npx agent-inspect check .agent-inspect/*.jsonl --require-completed
 
 **Problem:** You need to paste a trace into Slack or a GitHub issue.
 
-**Use:** `@agent-inspect/redact` or CLI `redact` / `scan`.
+**Use:** `@agent-inspect/redact` or CLI `redact` / `scan` / `bundle` with a run id or path target.
 
 **Doc:** [Safe trace sharing](./SAFE-TRACE-SHARING.md)
 
@@ -77,23 +82,42 @@ npx agent-inspect check .agent-inspect/*.jsonl --require-completed
 
 ---
 
-## 7. MCP tool tracing
+## 7. Ask a coding agent what failed first (MCP)
+
+**Problem:** You want Cursor/Claude/Codex to inspect a local failing run without uploading traces.
+
+**Use:** `@agent-inspect/mcp-server` + `agent-inspect mcp configure` (dry-run by default).
+
+```bash
+npx agent-inspect mcp configure --client cursor
+cd examples/starters/coding-agent-debug-loop && pnpm start && pnpm run inspect-mcp
+```
+
+Ask the agent for `get_first_causal_failure` / `create_share_checked_evidence`.
+
+**Docs:** [CODING-AGENT-LOOP.md](./CODING-AGENT-LOOP.md) · **Starter:** [coding-agent-debug-loop](../examples/starters/coding-agent-debug-loop/README.md)
+
+**Not:** Remote MCP gateway or default network upload.
+
+---
+
+## 8. MCP client tool tracing
 
 **Problem:** Which MCP tools were listed, called, and where did they fail?
 
-**Use:** `@agent-inspect/mcp` (client tracing only).
+**Use:** `@agent-inspect/mcp` (client tracing only — distinct from the coding-agent MCP **server** loop above).
 
 ---
 
-## 8. Design partner adoption
+## 9. Design partner adoption
 
 **Problem:** Team wants one real agent instrumented in one sprint.
 
-**Doc:** [Design partner guide](./DESIGN-PARTNER-GUIDE.md)
+**Doc:** [Design partner guide](./DESIGN-PARTNER-GUIDE.md) · [Pilot kit](./PRE-V7-PILOT-KIT.md)
 
 ---
 
-## 9. VS Code trace review
+## 10. VS Code trace review
 
 **Problem:** Browse `.agent-inspect/` from the editor.
 
@@ -103,7 +127,7 @@ npx agent-inspect check .agent-inspect/*.jsonl --require-completed
 
 ---
 
-## 10. Existing structured logs
+## 11. Existing structured logs
 
 **Problem:** You cannot change app code; logs already exist.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-inspect",
-  "version": "6.12.0",
+  "version": "6.12.2",
   "license": "MIT",
   "type": "module",
   "description": "Debug, regression-test, and safely share TypeScript AI-agent behavior locally — no account, no default upload, metadata-only by default",
@@ -226,7 +226,7 @@
     "test:all": "pnpm run typecheck && pnpm run linked-versions:check && pnpm run build && pnpm run test && pnpm run size",
     "prepublish:checks": "pnpm run typecheck && pnpm run test && pnpm run test:coverage && pnpm run build && pnpm run fixtures:check && pnpm run recipes:check && pnpm run size && pnpm run linked-versions:check && pnpm run pack:smoke",
     "pack:dry-run": "pnpm run build && npm pack --dry-run",
-    "pack:smoke": "pnpm run build && node scripts/package-smoke.mjs && node scripts/packed-quickstart-e2e.mjs",
+    "pack:smoke": "pnpm run build && node scripts/package-smoke.mjs && node scripts/packed-quickstart-e2e.mjs && node scripts/packed-semantic-loop-e2e.mjs",
     "linked-versions:check": "node scripts/check-linked-versions.mjs",
     "docs:commands": "node scripts/validate-doc-commands.mjs",
     "docs:links": "node scripts/validate-doc-links.mjs",