agent-inspect 1.7.0 → 1.9.0

package/docs/API.md

@@ -9,14 +9,42 @@ AgentInspect is a **local-first execution-tree debugger**. It is not a SaaS, not
 - **Stable**: intended to be compatible across v1.x. Breaking changes require v2.0.
 - **Experimental**: available for adoption, but subject to refinement (including naming/shape changes) before a future stability declaration. Experimental APIs may change in v1.x.
 
-**1.x subpath exports:** Additive subpaths (`/logs`, `/exporters`, `/persisted`, `/diff`, `/advanced`, `/writers`, `/readers`) narrow the import surface for experimental and advanced APIs. Root `"."` imports remain valid through v1.x. Design: [API-BOUNDARY-V1.5.md](./implementation/API-BOUNDARY-V1.5.md).
+Use the root import for stable beginner APIs. Use subpaths for advanced, experimental, or lower-level workflows.
+
+```ts
+import {
+  observe,
+  inspectRun,
+  maybeInspectRun,
+  step,
+  getCurrentCorrelationMetadata,
+} from "agent-inspect";
+```
+
+**v1.9 root API direction:** do not add new root exports casually. Existing root imports keep working through v1.x for compatibility, but new advanced examples should use the subpath where the API lives. The intended stable root set for v2 is:
+
+```ts
+import {
+  createInspector,
+  observe,
+  inspectRun,
+  maybeInspectRun,
+  step,
+  getCurrentCorrelationMetadata,
+} from "agent-inspect";
+```
+
+**1.x subpath exports:** Additive subpaths (`/logs`, `/exporters`, `/persisted`, `/diff`, `/advanced`, `/writers`, `/readers`, `/checks`) narrow the import surface for experimental and advanced APIs. Root `"."` imports remain valid through v1.x. Design: [API-BOUNDARY-V1.5.md](./implementation/API-BOUNDARY-V1.5.md).
 
 ```ts
-import { inspectRun, step } from "agent-inspect";
 import { parseLogsToTrees } from "agent-inspect/logs";
 import { exportMarkdown } from "agent-inspect/exporters";
 import { memoryWriter } from "agent-inspect/writers";
 import { openTrace } from "agent-inspect/readers";
+import { runTraceChecks } from "agent-inspect/checks";
+import { diffTraceEvents } from "agent-inspect/diff";
+import { traceEventsToPersistedInspectEvents } from "agent-inspect/persisted";
+import { createInspector } from "agent-inspect/advanced";
 ```
 
 Notes:
@@ -24,6 +52,7 @@ Notes:
 - The core guarantee of v1.x is **stable local debugging**: manual tracing + CLI inspection.
 - Export formats (OpenInference / OTLP JSON) are **local-only** and **compatibility-oriented**. They do **not** upload anywhere.
 - There are **zero production sinks** in v1.x; sink/uploader APIs are not stable.
+- Advanced root exports in v1.x are compatibility aliases. Prefer `agent-inspect/advanced`, `agent-inspect/readers`, `agent-inspect/writers`, `agent-inspect/checks`, `agent-inspect/diff`, `agent-inspect/exporters`, `agent-inspect/logs`, and `agent-inspect/persisted` for new code.
 
 ## 2. Stable core APIs (manual tracing)
 
@@ -32,7 +61,13 @@ These are the recommended entry points for manual instrumentation. They are desi
 Import from `agent-inspect`:
 
 ```ts
-import { inspectRun, maybeInspectRun, step, observe } from "agent-inspect";
+import {
+  observe,
+  inspectRun,
+  maybeInspectRun,
+  step,
+  getCurrentCorrelationMetadata,
+} from "agent-inspect";
 ```
 
 - **`inspectRun(name, fn, options?)`**: wraps a workflow in a local JSONL trace (`run_started` / `run_completed`), prints terminal progress, and swallows instrumentation failures (user errors are re-thrown). **Traces by default** when `enabled` is omitted or `true`. Pass **`enabled: false`** to run `fn` with no trace file, no execution context, and no terminal output.
@@ -90,7 +125,7 @@ These APIs support local workflows like listing traces, extracting metadata/summ
 
 ## 5. Experimental log parsing APIs
 
-These are compatibility-oriented utilities for turning structured logs into normalized `InspectEvent` and grouped trees. They remain conservative: **no eval**, **no parsing JS object literals**, JSON logs first-class, log4js best-effort.
+Advanced ingestion: use this when your app already emits structured logs. These are compatibility-oriented utilities for turning structured logs into normalized `InspectEvent` and grouped trees. They remain conservative: **no eval**, **no parsing JS object literals**, JSON logs first-class, log4js best-effort.
 
 - **`parseLogsToTrees`**
 - **`JsonLogParser`**, **`Log4jsParser`**
@@ -152,7 +187,7 @@ Rationale: v1.x includes one official adapter and **zero production sinks**, so
 
 ## 11. Experimental `@agent-inspect/ai-sdk` APIs
 
-`@agent-inspect/ai-sdk` is an optional v1.7 adapter package for Vercel AI SDK v6 telemetry integrations. It is experimental during the v1.7 train and remains private until release readiness.
+`@agent-inspect/ai-sdk` is an optional adapter package for Vercel AI SDK v6 telemetry integrations. It is experimental and published as part of the aligned v1.8.0 package set.
 
 Import from `@agent-inspect/ai-sdk`:
 
@@ -164,9 +199,10 @@ import { agentInspect } from "@agent-inspect/ai-sdk";
   - **`writer`**: optional explicit local `TraceWriter` for tests, recipes, and controlled runtime integration.
   - **`traceDir`**: optional local directory that creates a file writer inside the adapter package.
   - **`runName`**: optional local run name.
-  - **`capture`**: `"metadata-only"` (default) or `"preview"` (reserved for explicit bounded capture).
-  - **`redactionProfile`** and **`maxPreviewChars`**: reserved for bounded/redacted future preview behavior.
-  - **`getDiagnostics()`**: exposes isolated adapter write failures without throwing into AI SDK callbacks.
+  - **`capture`**: `"metadata-only"` (default) or `"preview"`; `preview` currently emits a diagnostic and falls back to metadata-only.
+  - **`redactionProfile`** and **`maxPreviewChars`**: preview-only knobs; when preview capture is unsupported or not selected, they emit diagnostics instead of silently doing nothing.
+  - **`getDiagnostics()`**: exposes isolated adapter write, lifecycle/configuration, flush, and close failures without throwing into AI SDK callbacks.
+  - **`getWriterStats()`**, **`flush()`**, and **`close()`**: explicit writer lifecycle helpers. Failures are captured in diagnostics.
 
 Every AI SDK call using the adapter must keep telemetry local and metadata-only:
 
@@ -179,15 +215,89 @@ experimental_telemetry: {
 }
 ```
 
-The adapter records local v0.2 persisted events for run, LLM step, and tool lifecycle metadata. By default it does not persist raw prompts, messages, generated text, stream chunks, tool inputs, tool outputs, headers, request bodies, response bodies, or user `experimental_context`.
+The adapter records local v0.2 persisted events for run, LLM step, and tool lifecycle metadata. It does not persist raw prompts, messages, generated text, stream chunks, tool inputs, tool outputs, headers, request bodies, response bodies, or user `experimental_context`. Unsupported preview capture options are explicit diagnostics and keep this metadata-only behavior.
 
 No network writer, OpenTelemetry exporter, provider wrapper, or global monkey-patch is part of this package.
 
 Recipe: [examples/recipes/ai-sdk-local-telemetry](../examples/recipes/ai-sdk-local-telemetry/).
 
-## 12. Experimental `@agent-inspect/openai-agents` APIs
+## 12. Experimental `@agent-inspect/vitest` APIs
+
+`@agent-inspect/vitest` is an optional experimental workspace package for local Vitest failure artifacts. It remains private/unpublished. It does not add a Vitest dependency to root/core, does not upload artifacts, and does not infer trace relationships by timestamp.
+
+Import from `@agent-inspect/vitest`:
+
+```ts
+import { createAgentInspectVitestReporter } from "@agent-inspect/vitest";
+```
+
+- **`createAgentInspectVitestReporter(options?)`**: returns a structural Vitest reporter facade with `onTestCaseResult`, `onTaskUpdate`, and `onFinished` hooks.
+  - **`artifactDir`**: local output directory for safe artifacts; defaults to `.agent-inspect/vitest-artifacts`.
+  - **`githubSummary`**: optional GitHub step-summary file path. The reporter appends bounded structural counts only and does not use the GitHub API.
+  - **`retainSuccessful`**: `false`/undefined keeps no passing-test artifacts; `true` keeps up to `maxSuccessfulTraces`; a number keeps up to that many passing-test artifacts.
+  - **`maxSuccessfulTraces`**: upper bound for passing-test artifacts, capped by the reporter.
+  - **`resolveTrace(test)`**: optional explicit association resolver when task metadata is not convenient.
+  - **`onDiagnostic(diagnostic)`**: observes non-fatal reporter/artifact failures.
+  - **`getDiagnostics()`** and **`getArtifacts()`** expose reporter state for tests and custom harnesses.
+- **`agentInspectVitestReporter`**: alias for `createAgentInspectVitestReporter`.
+
+Trace association must be explicit. The default resolver reads `meta.agentInspect`, `meta["agent-inspect"]`, `meta.trace`, `context.meta.agentInspect`, or result metadata when present:
+
+```ts
+ctx.task.meta.agentInspect = {
+  runId: "support-agent",
+  tracePath: ".agent-inspect/support-agent.jsonl",
+  artifactLabel: "support-agent",
+};
+```
+
+Artifacts are safe structural summaries. They include bounded test identity, status, trace run id, and trace filename, but they do not read or embed raw trace contents, prompts, generated outputs, request/response bodies, headers, API keys, secrets, or tool payloads. Reporter/artifact failures are diagnostics and do not replace original Vitest failures.
+
+## 13. Experimental `@agent-inspect/jest` APIs
+
+`@agent-inspect/jest` is an optional experimental workspace package for local Jest failure artifacts. It remains private/unpublished. It does not add a Jest dependency to root/core, does not upload artifacts, and does not infer trace relationships by timestamp.
+
+Import from `@agent-inspect/jest`:
+
+```ts
+import { AgentInspectJestReporter, createAgentInspectJestReporter } from "@agent-inspect/jest";
+```
+
+- **`AgentInspectJestReporter`**: default Jest custom reporter class for `reporters: [["@agent-inspect/jest", options]]`.
+- **`createAgentInspectJestReporter(options?)`**: returns a structural reporter facade with `onTestResult` and `onRunComplete` hooks for tests and custom harnesses.
+  - **`artifactDir`**: local output directory for safe artifacts; defaults to `.agent-inspect/jest-artifacts`.
+  - **`githubSummary`**: optional GitHub step-summary file path. The reporter appends bounded structural counts only and does not use the GitHub API.
+  - **`retainSuccessful`**: `false`/undefined keeps no passing-test artifacts; `true` keeps up to `maxSuccessfulTraces`; a number keeps up to that many passing-test artifacts.
+  - **`maxSuccessfulTraces`**: upper bound for passing-test artifacts, capped by the reporter.
+  - **`associations`**: explicit trace associations keyed by `file::fullName`, `basename::fullName`, or `fullName`.
+  - **`resolveTrace(test)`**: optional explicit association resolver for normalized Jest assertion results.
+  - **`onDiagnostic(diagnostic)`**: observes non-fatal reporter/artifact failures.
+  - **`getDiagnostics()`** and **`getArtifacts()`** expose reporter state for tests and custom harnesses.
+- **`agentInspectJestReporter`**: alias for `createAgentInspectJestReporter`.
+
+Jest association is explicit because Jest assertion results do not expose Vitest-style mutable task metadata:
+
+```js
+reporters: [
+  [
+    "@agent-inspect/jest",
+    {
+      associations: {
+        "agent.test.cjs::agent suite agent workflow": {
+          runId: "support-agent",
+          tracePath: ".agent-inspect/support-agent.jsonl",
+        },
+      },
+    },
+  ],
+],
+```
+
+Artifacts are safe structural summaries. They include bounded test identity, status, trace run id, and trace filename, but they do not read or embed raw trace contents, prompts, generated outputs, request/response bodies, headers, API keys, secrets, or tool payloads. Reporter/artifact failures are diagnostics and do not replace original Jest failures.
+
+## 14. Experimental `@agent-inspect/openai-agents` APIs
 
-`@agent-inspect/openai-agents` is an optional v1.7 scaffold for future OpenAI Agents JS tracing processor integration. Runtime span mapping is not implemented yet.
+`@agent-inspect/openai-agents` is an optional experimental package for OpenAI Agents JS tracing processor integration. It is public in the aligned v1.8.0 package set and records runtime metadata locally.
 
 Import from `@agent-inspect/openai-agents`:
 
@@ -195,11 +305,16 @@ Import from `@agent-inspect/openai-agents`:
 import { agentInspectProcessor } from "@agent-inspect/openai-agents";
 ```
 
-- **`agentInspectProcessor(options?)`**: returns a local-only scaffold object with diagnostics.
+- **`agentInspectProcessor(options?)`**: returns a local-only OpenAI Agents `TracingProcessor`.
   - **`installMode`**: always `"setTraceProcessors"` to document the safe replacement install path.
-  - **`localOnly`**: always `true`; the scaffold performs no network I/O and does not install itself globally.
-  - **`writer`**, **`traceDir`**, **`workflowName`**, **`capture`**, **`redactionProfile`**, and **`maxPreviewChars`** are reserved for the later runtime mapping chunk.
-  - **`getDiagnostics()`**: exposes scaffold diagnostics and reports `runtimeMappingImplemented: false`.
+  - **`localOnly`**: always `true`; the processor performs no network I/O and does not install itself globally.
+  - **`writer`**: optional explicit local `TraceWriter` for tests, recipes, and controlled runtime integration.
+  - **`traceDir`**: optional local directory that creates a file writer inside the adapter package.
+  - **`workflowName`**: optional local run name overriding the SDK trace name.
+  - **`capture`**: `"metadata-only"` (default) or `"preview"`; `preview` currently emits a diagnostic and falls back to metadata-only.
+  - **`redactionProfile`** and **`maxPreviewChars`**: preview-only knobs; when preview capture is unsupported or not selected, they emit diagnostics instead of silently doing nothing.
+  - **`getDiagnostics()`**: exposes isolated processor write, lifecycle/configuration, flush, and shutdown failures without throwing into OpenAI Agents callbacks.
+  - **`getWriterStats()`**, **`forceFlush()`**, and **`shutdown()`**: explicit writer lifecycle helpers. Failures are captured in diagnostics.
 
 Safe future usage must replace processors explicitly:
 
@@ -209,11 +324,13 @@ setTraceProcessors([agentInspectProcessor({ traceDir: "./.agent-inspect" })]);
 
 Do not use `addTraceProcessor()` as the default AgentInspect path; that leaves existing/default processors in place and can preserve backend export behavior in server runtimes.
 
-## 13. Experimental persisted-event foundation (v1.2.0)
+The processor records local v0.2 persisted events for trace/run, agent, generation/response, function/tool, handoff, guardrail, MCP tools, custom, transcription, and speech span metadata where safely representable. It does not persist raw prompts, messages, generated text, function inputs/outputs, arbitrary custom data, trace exporter credentials, headers, request bodies, response bodies, or hosted tool payloads by default.
+
+## 15. Experimental persisted-event foundation (v1.2.0)
 
 These helpers expose the **source-agnostic `PersistedInspectEvent` model** (`schemaVersion: "0.2"`). They are **local-only**, **in-memory**, and **do not change** storage write/read or CLI behavior in v1.2.0.
 
-Import from `agent-inspect`:
+Import from `agent-inspect/persisted`:
 
 | API | Role |
 | --- | ---- |
@@ -235,7 +352,7 @@ Related types: `PersistedInspectEvent`, `PersistedEventSourceType`, `PersistedEv
 - v0.2 is **not written by default**; use converters and `fixtures/traces-v0.2/` samples for validation.
 - Inspection read paths normalize v0.1 and v0.2 JSONL for local CLI/API use. v0.2 remains experimental as a persisted-event foundation and is not the default writer.
 
-## 14. Local observability helpers (v1.4.0+)
+## 16. Local observability helpers (v1.4.0+)
 
 Read-only helpers for timeline, stats, and search over local JSONL traces. v0.1 manual traces remain the default writer; v0.2 persisted-event files are accepted where the shared dual-format read path is used. Local files only.
 
@@ -245,7 +362,7 @@ Read-only helpers for timeline, stats, and search over local JSONL traces. v0.1
 
 CLI wrappers: `agent-inspect timeline`, `stats`, `search` — see [CLI.md](./CLI.md).
 
-## 15. Report and what helpers (v1.5.0+)
+## 17. Report and what helpers (v1.5.0+)
 
 Read-only helpers for concise inspection summaries and local reports:
 
@@ -254,7 +371,7 @@ Read-only helpers for concise inspection summaries and local reports:
 
 Report redaction profiles are key-based safeguards applied to the complete rendered report input, not only to the tree section. Review generated reports before sharing; this is not compliance-grade DLP.
 
-## 16. Experimental trace writers (v1.6)
+## 18. Experimental trace writers (v1.6)
 
 Trace writers are the first slice of the v1.6 runtime foundation. They are experimental during v1.x and intended for tests, adapters, and future `createInspector` work.
 
@@ -286,7 +403,7 @@ import type {
 
 No network writer or vendor sink exists in this package.
 
-## 17. Experimental inspector API/runtime (v1.6)
+## 19. Experimental inspector API/runtime (v1.6)
 
 `createInspector()` is the experimental public instance API for local-first tracing with explicit writers. It owns an instance-specific runtime context, records v0.2 persisted inspect events, preserves application return values/errors, and exposes diagnostics plus deterministic `flush()`/`close()` lifecycle hooks.
 
@@ -328,7 +445,7 @@ Public methods:
 
 These APIs are experimental during v1.x. They do not add a default network writer or vendor sink.
 
-## 18. Experimental trace readers (v1.6)
+## 20. Experimental trace readers (v1.6)
 
 `agent-inspect/readers` exposes the experimental local trace reader contract and detection pipeline. It includes AgentInspect JSONL for v0.1, v0.2, and mixed local trace files, plus local OpenInference JSON and OTLP JSON compatibility readers.
 
@@ -359,23 +476,94 @@ import type { TraceReader } from "agent-inspect/readers";
 
 The reader contract does not silently accept arbitrary JSON and does not add OTel SDK, database, hosted ingestion, or network upload dependencies.
 
-## 19. Deprecated APIs
+## 21. Experimental Checks
+
+`agent-inspect/checks` exposes the experimental deterministic trace-check engine foundation. It consumes normalized reader output, runs supplied pure rules in stable order, and returns aggregate findings/diagnostics. It does not read files, discover config, call providers, perform network I/O, mutate inputs, or create a new persisted schema.
+
+Import from `agent-inspect/checks`:
+
+```ts
+import { runTraceChecks } from "agent-inspect/checks";
+import type { TraceCheckRule, TraceCheckResult } from "agent-inspect/checks";
+```
+
+- **`runTraceChecks({ read }, { rules?, select?, runId? })`**: executes provided rules against a `TraceReadResult` from `agent-inspect/readers`.
+- **Built-in rule factories**: run, tool, LLM, structure, retrieval, guardrail, decision, safety, and baseline helpers including `createRunStatusRule`, `createToolUsageRule`, `createLlmUsageRule`, `createStructureOrphanRule`, `createStructureCycleRule`, `createStructureRelationshipRule`, `createRetrievalRule`, `createGuardrailRule`, `createDecisionRule`, `createSafetyRawContentRule`, `createSafetySecretPatternRule`, and `createBaselineRegressionRule`.
+- **`TraceCheckRule`**: synchronous pure rule contract.
+- **`TraceCheckResult`**: deterministic aggregate result with findings, evidence, summary counts, and execution diagnostics.
+
+The checks API is experimental in v1.x. The `agent-inspect check` CLI uses this API for local reader-backed checks and deterministic JSON output; `agent-inspect artifacts` reuses the same safe findings for local CI artifact bundles and optional step-summary file output. Built-in rules operate on normalized event metadata, tree relationships, bounded summaries, token counts, and normalized baseline facts; safety and baseline findings identify event IDs and field paths rather than emitting raw prompts, outputs, secrets, headers, request/response bodies, or full tool payloads.
+
+Recipes: [deterministic-ci-checks](../examples/recipes/deterministic-ci-checks/README.md) for check/baseline/artifact workflows, and [test-reporter-artifacts](../examples/recipes/test-reporter-artifacts/README.md) for Vitest/Jest reporter configuration patterns.
+
+## 22. Experimental local explain APIs (v1.9)
+
+`buildLocalExplanation()` creates a deterministic local explanation payload from a reader-selected `InspectRunTree`. It performs no network I/O, does not call model providers, and separates observed facts from deterministic inference labels.
+
+Import from `agent-inspect`:
+
+```ts
+import { buildLocalExplanation } from "agent-inspect";
+```
+
+- **`buildLocalExplanation(run, options?)`**:
+  - **`mode: "dry-run"`**: returns redacted observed facts and no inference labels.
+  - **`mode: "local"`** (default): returns observed facts plus deterministic local inference labels.
+  - **`redactionProfile`**: `local`, `share`, or `strict`; profile keys are redacted before the payload is returned.
+
+CLI wrapper: `agent-inspect explain <trace-path-or-run-id> --dry-run --json`.
+
+Provider design gate:
+
+- No provider payload is submitted in v1.9 implementation chunks; `--provider <provider>` is reserved and rejected with `PROVIDER_NOT_IMPLEMENTED`.
+- The reviewable provider payload contract is the `ExplainResult` object: `mode`, `runId`, optional `name` / `status`, `redactionProfile`, `facts`, `inferences`, and `notes`.
+- Provider implementations must require explicit provider selection and documented environment requirements. The current local API reads no provider credentials.
+- Provider prompts must use redacted facts only, label inferred claims, and must not request raw chain-of-thought.
+- Provider packages or SDKs must not become root/core runtime dependencies.
+
+## 23. Experimental `@agent-inspect/harness` APIs
+
+`@agent-inspect/harness` is a private experimental workspace package during the v1.9 release train. It provides a no-framework fixture runner for local targets and recipes; first public package publication remains a manual maintainer gate.
+
+Import from `@agent-inspect/harness` inside the workspace:
+
+```ts
+import { createFixtureRunner, defineTarget } from "@agent-inspect/harness";
+```
+
+- **`defineTarget(definition)`**: returns a typed target definition with `resolve(app, context)` and `invoke(target, input, context)` hooks.
+- **`createFixtureRunner(options)`**: returns a local runner with:
+  - **`listTargets()`**: deterministic target metadata listing.
+  - **`runTarget(name, input, options?)`**: bootstrap, resolve, invoke, and shutdown lifecycle.
+  - **`runFromArgv(argv?, io?)`**: CLI-friendly execution with target listing, JSON fixture files, JSON stdin, JSON stdout, stderr summaries, trace flags, and expected-output comparison.
+  - **`getDiagnostics()`**: deterministic diagnostics for missing targets, bootstrap failures, resolve failures, invocation failures, and shutdown failures.
+- **`trace`** options use existing AgentInspect local APIs only:
+  - **`mode: "run-if-enabled"`** (default): uses `maybeInspectRun()` and writes no trace unless `options.enabled` or `AGENT_INSPECT` enables tracing.
+  - **`mode: "run"`**: explicitly wraps the target invocation in `inspectRun()`.
+  - **`mode: "observe"`**: proxies the resolved target with `observe()` for `run` / `execute` / `invoke` methods when enabled.
+  - **`mode: "off"`**: invokes the target without AgentInspect tracing.
+
+The harness package does not add root/core dependencies, does not upload traces, does not call providers, and does not capture raw prompts or outputs by itself. It writes only local AgentInspect traces when explicitly enabled by runner options or environment-gated tracing.
+
+Recipes: [harness-basic](../examples/recipes/harness-basic/README.md) and [harness-adapter-local](../examples/recipes/harness-adapter-local/README.md).
+
+## 24. Deprecated APIs
 
 No deprecated APIs are declared as of 1.4.0.
 
-## 20. Removal / deprecation policy
+## 25. Removal / deprecation policy
 
 - Stable APIs are not removed in v1.x.
 - If removal is necessary, the API should be **deprecated** first, documented, and kept for a reasonable window (target: at least one minor line) unless security requires faster action.
 
-## 21. Backward compatibility policy
+## 26. Backward compatibility policy
 
 - Manual trace JSONL (`schemaVersion: "0.1"`) remains readable.
 - Additive schema changes are allowed in minor versions.
 - Breaking changes require a major version.
 - Unknown fields should be ignored where safe.
 
-## 22. Examples
+## 25. Examples
 
 ### Minimal manual trace
 

package/docs/CLI.md

@@ -26,12 +26,17 @@ Core commands:
 - `tail` — live-tail logs into updating local trees
 - `export` — export manual traces to Markdown/HTML/OpenInference/OTLP JSON (local only)
 - `open` — read supported local trace files, directories, or stdin through the canonical reader pipeline
+- `check` — run deterministic local trace checks with stable JSON and exit codes
+- `scan` — best-effort local safety scan for trace capture risks
+- `verify-safe` — best-effort local trace safety verification
+- `artifacts` — create safe local CI trace artifact bundles and optional step summaries
 - `diff` — compare two manual traces (local, read-only)
 - `timeline` — chronological view of one run (local JSONL)
 - `stats` — local aggregate stats over a trace directory
 - `search` — deterministic local search over traces
 - `what` — concise summary of a single run (local JSONL)
 - `report` — markdown or HTML inspection report for a single run
+- `explain` — deterministic local facts/inferences for a trace, with dry-run payloads
 
 ## 2. Environment variables
 
@@ -44,6 +49,20 @@ Core commands:
 - **0**: command succeeded (even if a diff reports “differences”)
 - **1**: command error (invalid args, missing files, missing runs, parse failures, validation failures, etc.)
 
+Exception: `check` uses CI-oriented semantic exit codes:
+
+- **0**: all selected checks passed
+- **1**: checks ran and at least one error-severity rule failed
+- **2**: invalid arguments or invalid config
+- **3**: trace input could not be read
+- **4**: unsupported or ambiguous trace format
+
+Exception: `scan` and `verify-safe` use local safety status exit codes:
+
+- **0**: status is SAFE or SAFE WITH WARNINGS
+- **1**: status is UNSAFE
+- **2**: status is UNKNOWN, including unreadable, unsupported, ambiguous, or invalid inputs
+
 AgentInspect favors **human-readable errors without stack traces** for expected user mistakes.
 
 ## 4. JSON output policy
@@ -59,6 +78,8 @@ Many commands support `--json` for scripting. JSON output is intended to be:
 - Log-derived output includes **confidence** labels and avoids inventing parent-child relationships.
 - Redaction defaults are conservative (e.g. `authorization`, `cookie`, `token`, `apiKey`, `password`, `secret`, `email`).
 - Exported payloads are **redacted by default** unless explicitly configured otherwise.
+- `scan` and `verify-safe` are best-effort local checks, not compliance, privacy, security, or regulatory certifications.
+- `artifacts` renders structural summaries and check evidence only; it does not include raw prompt/output bodies, request/response bodies, headers, API keys, secrets, or full tool payloads.
 
 ## 6. Command reference
 
@@ -118,7 +139,7 @@ Recommendation: run with `--dry-run` first.
 
 ### 6.4 `logs`
 
-Parse structured logs into local execution trees.
+Advanced ingestion: use this when your app already emits structured logs. Parse those logs into local execution trees.
 
 ```bash
 agent-inspect logs <file> [options]
@@ -222,7 +243,135 @@ cat packages/core/test/fixtures/openinference-basic.json | npx agent-inspect ope
 
 When a directory or payload contains multiple runs, `open` lists the run ids and exits until you pass `--run <run-id>`.
 
-### 6.8 `diff`
+### 6.8 `check`
+
+Run deterministic checks against a local trace. This command is local and read-only: it does not rerun agents, call models, upload traces, or mutate input files.
+
+```bash
+agent-inspect check <trace-path-or-run-id> [options]
+```
+
+`<trace-path-or-run-id>` may be a trace file, directory, `-` for stdin, or a run id resolved with `--dir`.
+
+Options:
+
+- `--dir <path>`: trace directory for run-id lookup
+- `--format <agent-inspect-jsonl|openinference-json|otlp-json>`: explicit reader format override
+- `--run <run-id>`: select a run when input contains multiple runs
+- `--config <path>`: check config (`.json`, `.js`, `.mjs`, or `.cjs`)
+- `--json`: print deterministic `TraceCheckResult` JSON
+- `--rule <id>`: select a rule id; repeatable
+- `--max-duration-ms <number>`: add `run.duration`
+- `--required-tool <name>` / `--forbidden-tool <name>`: add `tool.usage`
+- `--allowed-model <model>` / `--max-total-tokens <number>`: add `llm.usage`
+
+By default, `check` runs `run.status`. Additional built-in rules can be selected with `--rule` or config when their options are available.
+
+Config files use this shape:
+
+```json
+{
+  "checks": {
+    "select": ["run.status", "run.duration"],
+    "run": { "maxDurationMs": 30000 },
+    "tool": { "required": ["search_docs"] },
+    "llm": { "allowedModels": ["gpt-4.1-mini"], "maxTotalTokens": 12000 }
+  }
+}
+```
+
+YAML is not supported. TypeScript config files (`.ts`, `.mts`, `.cts`) fail clearly unless a future explicit loader strategy is added; use precompiled JavaScript config instead.
+
+Examples:
+
+```bash
+npx agent-inspect check fixtures/traces-v0.2/manual-basic.jsonl --json
+npx agent-inspect check minimal-success --dir fixtures/traces --rule run.status
+npx agent-inspect check trace.jsonl --max-duration-ms 30000 --required-tool search_docs --json
+```
+
+Recipe: [examples/recipes/deterministic-ci-checks](../examples/recipes/deterministic-ci-checks/README.md)
+
+### 6.9 `scan` and `verify-safe`
+
+Run best-effort local safety verification for supported trace inputs. These commands are local and read-only: they do not rerun agents, call models, upload traces, mutate input files, or certify compliance.
+
+```bash
+agent-inspect scan <trace-path-or-run-id> [options]
+agent-inspect verify-safe <trace-path-or-run-id> [options]
+```
+
+`<trace-path-or-run-id>` may be a trace file, directory, `-` for stdin, or a run id resolved with `--dir`.
+
+Statuses:
+
+- `SAFE`: no safety findings and no reader warnings.
+- `SAFE WITH WARNINGS`: no safety findings, but the reader reported warnings or unsupported fields.
+- `UNSAFE`: safety findings were detected.
+- `UNKNOWN`: the input could not be read, normalized, or selected conservatively.
+
+Options:
+
+- `--dir <path>`: trace directory for run-id lookup
+- `--format <agent-inspect-jsonl|openinference-json|otlp-json>`: explicit reader format override
+- `--run <run-id>`: select a run when input contains multiple runs
+- `--json`: print deterministic JSON safety result
+- `--max-string-length <number>`: unsafe threshold for string values
+- `--max-array-length <number>`: unsafe threshold for array values
+- `--max-object-keys <number>`: unsafe threshold for object key counts
+- `--max-serialized-bytes <number>`: unsafe threshold for serialized values
+
+The scan looks for raw prompt/output-like capture paths, unredacted sensitive-looking keys, secret-like string patterns, and oversized values. It reports evidence paths rather than raw prompt, output, request/response, header, API key, secret, or full tool payload values. Secret detection is best-effort and should not be treated as exhaustive.
+
+Examples:
+
+```bash
+npx agent-inspect scan fixtures/traces-v0.2/manual-basic.jsonl --json
+npx agent-inspect verify-safe minimal-success --dir fixtures/traces
+npx agent-inspect verify-safe trace.jsonl --max-string-length 8192 --json
+```
+
+### 6.10 `artifacts`
+
+Create deterministic local CI artifacts for supported trace inputs. This command is local and read-only for trace inputs: it does not rerun agents, call models, upload files, use GitHub APIs, or mutate repository state. It writes only to `--output-dir` and, when requested, a local step-summary file.
+
+```bash
+agent-inspect artifacts <trace-path-or-run-id> --output-dir <path> [options]
+```
+
+Generated files:
+
+- `trace.json`: structural trace summary only
+- `check.json`: safety check result
+- `diff.json`: baseline diff result, or `not_requested`
+- `summary.md`: safe Markdown CI summary
+- `report.html`: safe HTML CI summary
+- `manifest.json`: deterministic file/status manifest
+
+Options:
+
+- `--output-dir <path>`: required local artifact directory
+- `--dir <path>`: trace directory for run-id lookup
+- `--format <agent-inspect-jsonl|openinference-json|otlp-json>`: explicit reader format override
+- `--run <run-id>`: select a run when input contains multiple runs
+- `--baseline <trace-path-or-run-id>`: optional baseline trace for diff artifacts
+- `--baseline-run <run-id>`: select a run from the baseline trace
+- `--github-summary <path>`: append the safe Markdown summary to this file, such as `$GITHUB_STEP_SUMMARY`
+- `--json`: print deterministic `manifest.json` content
+
+The artifact command runs safety checks before rendering and only includes structural counts, statuses, bounded check findings, diagnostics, and evidence paths. Baseline diff artifacts use normalized baseline checks and also avoid raw prompt/output/tool payload values. `--github-summary` is plain local file output; AgentInspect does not call GitHub APIs or upload artifacts.
+
+Examples:
+
+```bash
+npx agent-inspect artifacts fixtures/traces-v0.2/manual-basic.jsonl --output-dir ./artifacts --json
+npx agent-inspect artifacts minimal-success --dir fixtures/traces --output-dir ./artifacts --github-summary "$GITHUB_STEP_SUMMARY"
+npx agent-inspect artifacts candidate.jsonl --baseline baseline.jsonl --output-dir ./artifacts
+```
+
+Recipe and sample workflow: [examples/recipes/deterministic-ci-checks](../examples/recipes/deterministic-ci-checks/README.md)
+
+### 6.11 `diff`
 
 Compare two manual trace runs. Diff is **local** and **read-only** (does not rerun agents).
 
@@ -286,7 +435,7 @@ Differences:
 
 More examples, including timing-only and structure-only diffs, are in `docs/DIFF.md`.
 
-### 6.9 `timeline`
+### 6.12 `timeline`
 
 Chronological step list for one manual trace. Read-only; does not mutate JSONL files.
 
@@ -302,7 +451,7 @@ Options:
 
 ![Timeline with slow-step focus](../assets/demos/timeline.gif)
 
-### 6.10 `stats`
+### 6.13 `stats`
 
 Local aggregate statistics over trace files in a directory. Read-only.
 
@@ -322,7 +471,7 @@ Options:
 
 Use `--correlation-id` or `--group-id` to filter runs by `run_started` metadata (see [API.md](./API.md)).
 
-### 6.11 `search`
+### 6.14 `search`
 
 Deterministic search over local traces (substring / exact filters). No semantic search.
 
@@ -352,7 +501,7 @@ npx agent-inspect search --duration ">100ms" --json
 
 ![Search traces by status error](../assets/demos/search.gif)
 
-### 6.12 `what`
+### 6.15 `what`
 
 Concise human-readable summary of one local trace run. Read-only; accepts v0.1 manual JSONL and v0.2 persisted-event JSONL through the shared dual-format normalization path. Vocabulary: [TRACE-VOCABULARY-V1.5.md](./proposals/TRACE-VOCABULARY-V1.5.md).
 
@@ -381,7 +530,7 @@ Outcome: Completed successfully.
 Slowest: plan (100ms, logic)
 ```
 
-### 6.13 `report`
+### 6.16 `report`
 
 Generate a local inspection report combining **what happened**, **timeline**, and **execution tree** sections. The command reads local v0.1 manual JSONL and v0.2 persisted-event JSONL through the shared dual-format normalization path without mutating them. Distinct from `export` (which targets shareable tree snapshots and standards formats).
 
@@ -406,6 +555,39 @@ Example:
 npx agent-inspect report minimal-success --dir fixtures/traces --format html -o report.html
 ```
 
+### 6.17 `explain`
+
+Explain a local trace using deterministic facts and local inference labels. This command reads through the same local reader pipeline as `open` / `check`; it does not call a model provider, upload traces, replay agents, or mutate input files.
+
+```bash
+agent-inspect explain <trace-path-or-run-id> [options]
+```
+
+Options:
+
+- `--dir <path>` — trace directory for run-id lookup
+- `--format <agent-inspect-jsonl|openinference-json|otlp-json>` — explicit input format
+- `--run <run-id>` — select a run when the trace contains multiple runs
+- `--dry-run` — emit only the redacted facts payload, with no local inference labels
+- `--provider <provider>` — reserved for an explicit future provider mode; currently rejected without network calls
+- `--json` — print deterministic JSON output
+- `--redaction-profile <local|share|strict>` — key-based redaction profile for the explanation payload (default `local`)
+
+Examples:
+
+```bash
+npx agent-inspect explain minimal-success --dir fixtures/traces
+npx agent-inspect explain fixtures/traces/minimal-success.jsonl --dry-run --json --redaction-profile strict
+```
+
+Provider design gate:
+
+- Current behavior is local only. `--provider <provider>` exits with a user-facing `PROVIDER_NOT_IMPLEMENTED` error and performs no provider call.
+- `--dry-run --json` is the payload review surface. The provider payload contract is the returned `explanation` object: `mode`, `runId`, optional `name` / `status`, `redactionProfile`, `facts`, `inferences`, and `notes`.
+- Provider chunks must require explicit provider selection, document required environment variables, and keep credentials out of trace data and dry-run output.
+- Provider prompts must ask for concise explanations from redacted facts only. They must not request, expose, or preserve raw chain-of-thought.
+- Cloud provider behavior is never selected by default and must be reviewed before implementation. Local provider support must still be explicit and opt-in.
+
 ## 7. Optional TUI behavior
 
 `view --tui` delegates to `@agent-inspect/tui` and requires an interactive terminal. If the package is not installed, the CLI prints a short install hint.