agent-inspect 1.0.0 → 1.0.1

package/CHANGELOG.md

@@ -0,0 +1,99 @@
+# Changelog
+
+## 1.0.1
+
+### Patch Changes
+
+- 575b093: docs: onboarding polish
+
+## Unreleased
+
+### Documentation
+
+- Improved README onboarding for new users.
+- Added comparison guide.
+- Added log-to-tree quickstart.
+- Added a quickstart demo example.
+- Clarified docs organization between user-facing `docs/` and internal `docs-local/`.
+
+## 1.0.0
+
+### Stable local tracing
+
+- Stable manual tracing entry points: `inspectRun`, `step`, `step.llm`, `step.tool`, `observe`
+- v0.1 JSONL trace compatibility retained (schemaVersion `"0.1"`)
+
+### Local inspection CLI
+
+- Stable CLI workflows: `list`, `view`, `clean`
+- Safety-critical cleanup verifies traces before deletion
+
+### Structured logs and live tail
+
+- Local log-to-tree parsing and live tail workflows (`logs`, `tail`) with confidence labeling
+- Best-effort log4js parsing; JSON logs first-class; no unsafe object parsing
+
+### Optional LangChain adapter
+
+- `@agent-inspect/langchain` optional adapter package (experimental surface)
+
+### Optional TUI
+
+- `@agent-inspect/tui` optional Ink/React viewer (experimental programmatic surface)
+
+### Standards-aligned local export
+
+- Markdown/HTML exports for sharing traces locally
+- OpenInference-compatible JSON export (experimental; verify against backends)
+- OTLP JSON export (experimental; JSON mapping only, no OTLP gRPC)
+
+### Diff and compare
+
+- Local, read-only diff of two manual traces (`diff`)
+
+### Fixtures, recipes, and hardening (v0.9)
+
+- Canonical fixtures under `fixtures/` plus validation scripts
+- Runnable recipes under `examples/recipes/` with deterministic expected output markers
+- Package smoke checks and adoption hardening tests
+
+### Documentation and stability
+
+- Added/updated API/CLI/schema/getting-started docs for v1.0 stabilization
+- Added stability and compatibility tests to prevent accidental surface breaks
+
+### Known limitations
+
+- Local-first only; no SaaS/dashboard; no vendor sinks; no replay; no cost engine
+
+## Historical notes (v0.1–v0.9)
+
+AgentInspect started as a minimal manual tracing MVP (v0.1) and evolved through:
+
+- local inspection improvements (metadata, filtering, safety checks)
+- structured log ingestion (JSON first-class, log4js best-effort)
+- conservative tree building rules with confidence labels
+- incremental live tail rendering
+- standards-aligned local exports (experimental)
+- run diff and compare
+- fixtures, recipes, and hardening focused on adoption
+
+For detailed intent and sequencing (planning docs), see:
+
+- `docs-local/roadmap/VERSION-ROADMAP.md`
+- `docs-local/strategy/PRODUCT-PRINCIPLES.md`
+
+# agent-inspect
+
+## 0.1.2
+
+### Patch Changes
+
+- 62afb94: fix CI/publish smoke + vitest config
+
+## 0.1.1
+
+### Patch Changes
+
+- bd719ef: Prepare npm publishing (Trusted Publishing via GitHub Actions OIDC) and polish documentation.
+- 76791b8: Improve README, release docs, and npm publishing guidance.

package/README.md

@@ -1,24 +1,10 @@
 # agent-inspect
 
-agent-inspect is a local-first execution-tree debugger for TypeScript AI agents.
+Local execution trees for TypeScript AI agents.
 
-## Why
+AgentInspect helps you debug multi-step AI workflows locally by turning manual steps, structured logs, and agent callbacks into readable execution trees.
 
-AI agents are multi-step. Console logs are flat.
-
-agent-inspect turns runs into structured execution trees with JSONL traces and CLI inspection.
-
-agent-inspect is designed for inner-loop debugging, not as a replacement for production observability platforms.
-
-## What you get
-
-- Execution-tree tracing for TypeScript agent workflows
-- Nested `step()` support with parent-child relationships
-- `step.llm()` and `step.tool()` helpers for agent-aware traces
-- Local JSONL trace files
-- Real-time terminal output while the agent runs
-- CLI commands to inspect previous runs
-- No accounts, API keys, dashboards, or cloud ingestion
+No account. No cloud upload. No dashboard required.
 
 ## Install
 
@@ -26,86 +12,140 @@ agent-inspect is designed for inner-loop debugging, not as a replacement for pro
 npm install agent-inspect
 ```
 
-## Documentation (v1.0 stabilization)
-
-- [Getting started](docs/GETTING-STARTED.md)
-- [API reference](docs/API.md)
-- [CLI reference](docs/CLI.md)
-- [Schema reference](docs/SCHEMA.md)
-- [Security policy](SECURITY.md)
-- [Migration guide](docs/MIGRATION.md)
-- [Release checklist](docs/RELEASE-CHECKLIST.md)
-- [Changelog](CHANGELOG.md)
-- [Known issues](docs/KNOWN-ISSUES.md)
-- [Limitations](docs/LIMITATIONS.md)
-- [V1 readiness checklist (non-binding)](docs/V1-READINESS-CHECKLIST.md)
+```bash
+pnpm add agent-inspect
+```
 
-## See your first trace
+## 60-second quickstart
 
-Run a traced workflow, then inspect it with the CLI.
+Create `demo.mjs`:
 
-```ts
+```js
 import { inspectRun, step } from "agent-inspect";
 
-await inspectRun("hello-agent", async () => {
-  const plan = await step("plan", async () => "search hotels");
-  return step("finalize", async () => ({ plan, status: "done" }));
-});
+const delay = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+
+await inspectRun(
+  "support-agent",
+  async () => {
+    const plan = await step("plan", async () => {
+      await delay(50);
+      return { query: "refund policy", intent: "support" };
+    });
+
+    const docs = await step.tool("search-docs", async () => {
+      await delay(75);
+      return ["Refunds are available within 30 days."];
+    });
+
+    return step.llm("answer", async () => {
+      await delay(100);
+      return `Based on ${docs.length} document(s), refunds are available within 30 days.`;
+    });
+  },
+  { traceDir: "./.agent-inspect" }
+);
 ```
 
+Run it, then inspect it:
+
 ```bash
-npx agent-inspect list
-npx agent-inspect view run_abc123
+node demo.mjs
+npx agent-inspect list --dir ./.agent-inspect
+npx agent-inspect view <run-id> --dir ./.agent-inspect
+npx agent-inspect view <run-id> --dir ./.agent-inspect --summary
 ```
 
-Replace `run_abc123` with the run id printed by `agent-inspect list`.
+Simplified example output:
 
-### Optional TUI viewer
+```text
+Run run_abc123 (support-agent)
+├─ ✔ plan (50ms)
+├─ ✔ tool:search-docs (75ms)
+└─ ✔ llm:answer (100ms)
 
-The core `agent-inspect` package stays lightweight and does not bundle Ink or React. For a keyboard-driven terminal UI over existing traces, install the optional package:
+Summary:
+  Steps: 3 (0 error)
+  Duration: 225ms
+```
 
-```bash
-pnpm add agent-inspect @agent-inspect/tui
+Want a runnable demo folder? See [examples/00-quickstart-demo](examples/00-quickstart-demo/README.md).
 
-npx agent-inspect view run_abc123 --tui
-```
+## Why not just console.log?
 
-The plain CLI remains the default. `--tui` requires an interactive terminal; for scripts or CI, use `agent-inspect view` or `agent-inspect view --json`. There is no live tail TUI yet.
+Console logs are great for quick values, but they’re flat. AgentInspect gives you:
 
-### Export traces
+- run grouping and local trace files
+- explicit step boundaries (including nesting)
+- step types (`tool:*`, `llm:*`)
+- status + duration summaries
+- a CLI to list/view/export/diff runs
+- log ingestion workflows (`logs`, `tail`) when you already have structured logs
 
-Export existing manual JSONL traces locally — **no upload**, **no vendor SDKs**. Markdown is handy for PRs and issues; HTML is a single offline file. OpenInference export is **OpenInference-compatible JSON** (not a guarantee for every backend). OTLP JSON uses **OTel GenAI-aligned attributes** where applicable and is **experimental** until validated against a specific collector.
+## Inspect existing structured logs
 
 ```bash
-npx agent-inspect export run_abc123 --format markdown
-npx agent-inspect export run_abc123 --format html -o run.html
-npx agent-inspect export run_abc123 --format openinference -o trace.openinference.json
-npx agent-inspect export run_abc123 --format otlp-json -o trace.otlp.json
-npx agent-inspect export run_abc123 --format openinference --validate
+npx agent-inspect logs ./agent.log \
+  --format json \
+  --run-id-key requestId \
+  --event-key event \
+  --timestamp-key timestamp
 ```
 
-Review exported files for sensitive data before sharing. Attribute payloads are bounded and redacted by default; use `--include-attributes` only when you intend to share richer detail.
+See the log-to-tree guide: [docs/LOG-TO-TREE-QUICKSTART.md](docs/LOG-TO-TREE-QUICKSTART.md).
 
-### Compare runs
+## When to use AgentInspect
 
-Diff is **local** and **read-only**: it compares two existing AgentInspect JSONL traces and does **not** rerun agents, mutate trace files, or write output traces. It does **not** claim semantic equivalence and does **not** call an LLM.
+Use AgentInspect when:
 
-Finding differences does **not** change the exit code by default (exit code `1` is reserved for command errors such as a missing run).
+- you are building TypeScript/Node.js AI agents
+- you want local debugging before a hosted observability setup
+- console logs are too flat for multi-step execution
+- you want to inspect tool calls, LLM calls, failures, and durations locally
+- you want a lightweight CLI workflow with no account and no cloud upload
+- you want to compare two local runs
+- you want to turn structured logs into readable execution trees
 
-```bash
-npx agent-inspect diff run_a run_b
-npx agent-inspect diff run_a run_b --json
-npx agent-inspect diff run_a run_b --ignore-duration
-npx agent-inspect diff run_a run_b --duration-threshold 500ms
-npx agent-inspect diff run_a run_b --focus errors
-npx agent-inspect diff run_a run_b --check structure
-```
+## When not to use AgentInspect
+
+Do not use AgentInspect as a replacement for:
+
+- production monitoring or alerting
+- hosted observability dashboards
+- long-term trace storage
+- eval dataset management
+- prompt management
+- cost analytics
+- replay/fork execution
+- vendor telemetry pipelines
+
+AgentInspect can complement tools like LangSmith, Langfuse, Braintrust, Phoenix/OpenInference, OpenTelemetry, New Relic, Datadog, etc. It does not replace their production/eval/dashboard workflows.
 
-Useful for comparing passing vs failing runs and spotting the **first divergence** in execution order.
+## Security and privacy posture
 
-### Fixtures and hardening (v0.9)
+- local files only by default (no upload)
+- no vendor sinks
+- no API keys required
+- small root dependency footprint
+- traces can include **user-provided metadata**; review exports before sharing
 
-**v0.9** adds canonical [**fixtures/**](fixtures/README.md), validation (`pnpm fixtures:check`), **recipe examples** under [**examples/recipes/**](examples/recipes/README.md) (`pnpm recipes:check`), and docs aimed at adoption—not new tracing features. Recipes use mocks only and require no API keys or external services by default. Good starting points: **rag-pipeline**, **tool-failure-retry**, **proactive-agent-logs**. See [**Known issues**](docs/KNOWN-ISSUES.md), [**Limitations**](docs/LIMITATIONS.md), and the non-binding [**v1 readiness checklist**](docs/V1-READINESS-CHECKLIST.md).
+See `SECURITY.md`.
+
+## Documentation
+
+- **Getting started**: [docs/GETTING-STARTED.md](docs/GETTING-STARTED.md)
+- **API**: [docs/API.md](docs/API.md)
+- **CLI**: [docs/CLI.md](docs/CLI.md)
+- **Schema**: [docs/SCHEMA.md](docs/SCHEMA.md)
+- **Logs**: [docs/LOGS.md](docs/LOGS.md) and [docs/LOG-TO-TREE-QUICKSTART.md](docs/LOG-TO-TREE-QUICKSTART.md)
+- **Exports**: [docs/EXPORTS.md](docs/EXPORTS.md)
+- **Diff**: [docs/DIFF.md](docs/DIFF.md)
+- **Adapters**: [docs/ADAPTERS.md](docs/ADAPTERS.md)
+- **Compare with other tools**: [docs/COMPARE.md](docs/COMPARE.md)
+- **Known issues**: [docs/KNOWN-ISSUES.md](docs/KNOWN-ISSUES.md)
+- **Limitations**: [docs/LIMITATIONS.md](docs/LIMITATIONS.md)
+
+Screenshots/GIFs are planned; see [docs/SCREENSHOTS.md](docs/SCREENSHOTS.md).
 
 ## Minimal API
 
@@ -278,7 +318,7 @@ await agent.run("How do I reset my password?");
 
 `observe()` wraps top-level `run`, `execute`, and `invoke` methods. For internal detail, add manual `step()` calls inside the agent.
 
-## LangChain adapter (v0.5, experimental)
+## LangChain adapter (experimental)
 
 Install:
 
@@ -309,9 +349,9 @@ Behavior:
 - **Preview** mode is opt-in (`capture: "preview"`) with truncation via `maxPreviewChars` (default `200`).
 - **Parent** links use LangChain `parentRunId`, surfaced as `parentId` on `InspectEvent` with `confidence: "explicit"`.
 - **No** cost calculation; token fields are informational only.
-- In this pass, events are collected **in memory** only (`getEvents()` / `clear()`). **No trace-file persistence** for adapter events yet; they are **not** written into v0.1 JSONL manual traces.
+- Events are collected **in memory** only (`getEvents()` / `clear()`). **No trace-file persistence** for adapter events yet; they are **not** written into the manual JSONL trace format.
 
-The API is **experimental** before v1.0. See [examples/08-langchain-adapter](examples/08-langchain-adapter).
+The LangChain adapter API remains **experimental** even though the core AgentInspect tracing API is stable in 1.0. See [examples/08-langchain-adapter](examples/08-langchain-adapter).
 
 ## CLI
 
@@ -445,15 +485,16 @@ cat ~/.agent-inspect/runs/run_abc123.jsonl | jq
 
 ## Runnable examples
 
-The repo includes five runnable MVP manual-tracing examples, the v0.3 structured log-to-tree example, and the v0.5 LangChain adapter example:
+The repo includes runnable examples for manual tracing, log-to-tree, and the optional LangChain adapter:
 
+- `examples/00-quickstart-demo` — minimal install-and-try demo
 - `examples/01-basic` — `inspectRun()` + `step()`
 - `examples/02-nested-steps` — nested execution tree hierarchy
 - `examples/03-parallel-steps` — `Promise.all` sibling isolation
 - `examples/04-error-handling` — failed steps and error traces
 - `examples/05-observe-wrapper` — `observe()` wrapper with internal steps
-- `examples/06-log-to-tree` — v0.3 structured log-to-tree example (includes historical spike prototype and production `agent-inspect logs` usage)
-- `examples/08-langchain-adapter` — v0.5 LangChain callback adapter (`@agent-inspect/langchain`), provider-free simulated lifecycle (install from repo root; see example README)
+- `examples/06-log-to-tree` — structured log-to-tree example (`agent-inspect logs`, `tail`)
+- `examples/08-langchain-adapter` — optional LangChain callback adapter (`@agent-inspect/langchain`), provider-free simulated lifecycle (install from repo root; see example README)
 
 Run one locally:
 
@@ -477,29 +518,6 @@ Supporting material:
 
 - [examples/README.md](examples/README.md)
 
-## Original MVP scope
-
-Included:
-
-- `inspectRun()`
-- `step()`
-- `step.llm()`
-- `step.tool()`
-- `observe()`
-- JSONL traces
-- CLI `list` and `view`
-
-Current scope also includes:
-
-- CLI `clean` (safe deletion with verification)
-- CLI `logs` (structured log-to-tree)
-- CLI `tail` (live log tailing into grouped timelines)
-- LangChain callback adapter via `@agent-inspect/langchain`
-- Optional TUI viewer via `@agent-inspect/tui`
-- Standards-aligned **local** exports (`export`: Markdown, HTML, OpenInference-compatible JSON, OTLP JSON mapping)
-- Run diff / compare (`diff`: two local traces, read-only)
-- Canonical **fixtures** under [`fixtures/`](fixtures/README.md) plus `pnpm fixtures:check` for deterministic samples
-
 Not included:
 
 - Live TUI / streaming trace updates in the TUI

package/SECURITY.md

@@ -0,0 +1,77 @@
+# Security policy
+
+AgentInspect is a **local-first** debugging tool. It does **not** upload your traces or logs anywhere, and it does not include vendor sink integrations in the core package.
+
+This document describes how to report vulnerabilities and how to think about data safety when using AgentInspect.
+
+## Supported status
+
+AgentInspect is in active development. Security fixes are accepted and prioritized based on impact and exploitability.
+
+There is **no formal SLA**. If a fix is needed, it should land as a patch release once verified.
+
+## Reporting vulnerabilities
+
+- If **GitHub Security Advisories** are enabled for this repository, please report via a private advisory.
+- Otherwise, open a GitHub issue with **minimal sensitive detail** and request a private contact path for the full report.
+
+### What to include in a report
+
+- A clear description of the issue and expected impact
+- Steps to reproduce (prefer a small repro repo or minimized snippet)
+- Affected package(s) and version(s)
+- Platform info (Node version, OS)
+- Any mitigations/workarounds you found
+
+### Please do not include
+
+- real API keys or tokens
+- production log files
+- customer/user PII
+- full unredacted traces
+
+If you need to include sample data, use synthetic placeholders (for example, `example.test` emails and fake tokens).
+
+## Scope
+
+In scope:
+
+- vulnerabilities in trace/log parsing that could lead to code execution, path traversal, or data disclosure
+- unsafe redaction defaults (obvious secrets displayed where the product promises safety)
+- package supply-chain / dependency boundary issues that cause heavy or unsafe dependencies to be pulled into the main `agent-inspect` install
+
+## Out of scope
+
+- production monitoring SLAs or uptime guarantees (AgentInspect is not a production observability platform)
+- vendor sink behavior (not implemented in core)
+- network upload security (AgentInspect does not upload)
+- replay sandboxing (replay is not implemented)
+- cost calculation correctness (cost engine is not implemented)
+
+## Data handling model (local-first)
+
+- Manual tracing writes local JSONL files (see `docs/SCHEMA.md`).
+- The CLI reads and renders local files.
+- Exports generate local strings/files only (Markdown/HTML/OpenInference/OTLP JSON); they do not upload anywhere.
+
+## Redaction expectations
+
+AgentInspect aims to be safe-by-default for **log-derived attributes** and **exported payloads**:
+
+- Log ingestion applies redaction to parsed attributes using configured rules (with conservative defaults).
+- Exporters default to redacted output and bounded attribute previews.
+
+Important limitations:
+
+- **Manual trace metadata is user-controlled.** If you attach secrets to `inspectRun({ metadata })` or step metadata, those values may appear in local trace files and could appear in some views/exports depending on your settings and what you choose to include.
+- Always **review exported files** before sharing them externally.
+- Avoid committing trace directories (`.agent-inspect-runs/`) to source control.
+
+For redaction design details, see `docs-local/architecture/REDACTION.md`.
+
+## Dependency and security review process
+
+- Prefer Node.js built-ins over new dependencies.
+- Do not add vendor SDKs, OpenTelemetry SDKs, or framework dependencies to the main `agent-inspect` package.
+- Keep optional integrations (`@agent-inspect/langchain`, `@agent-inspect/tui`) separate so users do not pull them in by default.
+

package/docs/ADAPTERS.md

@@ -0,0 +1,15 @@
+## Adapters
+
+AgentInspect is framework-agnostic at its core, but can optionally integrate with frameworks via adapter packages.
+
+- **LangChain.js adapter** (optional): `@agent-inspect/langchain`
+  - Documented as **experimental** in `docs/API.md`
+  - Requires `@langchain/core` as a peer dependency
+- **Interactive TUI** (optional): `@agent-inspect/tui`
+  - Documented as **experimental** in `docs/API.md`
+  - Intended for CLI integration; programmatic TUI APIs may change
+
+See also:
+- `docs/MIGRATION.md` (what changed from early versions)
+- `docs-local/RELEASE-CHECKLIST.md` (maintainer-only release steps)
+

package/docs/API.md

@@ -0,0 +1,152 @@
+# API (AgentInspect 1.0)
+
+This document describes the **public TypeScript API surface** of AgentInspect and classifies each area as **stable** or **experimental**.
+
+AgentInspect is a **local-first execution-tree debugger**. It is not a SaaS, not a production APM, not a sink/uploader, and not a replay engine.
+
+## 1. Stability policy
+
+- **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.
+
+Notes:
+
+- The core guarantee of v1.0 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.0; sink/uploader APIs are not stable.
+
+## 2. Stable core APIs (manual tracing)
+
+These are the recommended entry points for manual instrumentation. They are designed to be dependency-light and safe-by-default.
+
+Import from `agent-inspect`:
+
+```ts
+import { inspectRun, step, observe } 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).
+- **`step(name, fn, options?)`**: traces a named unit of work inside `inspectRun` (`step_started` / `step_completed`).
+  - **`step.llm(model, fn)`**: convenience wrapper (`type: "llm"`, `metadata.model`).
+  - **`step.tool(toolName, fn)`**: convenience wrapper (`type: "tool"`, `metadata.toolName`).
+- **`observe(agent, options?)`**: proxy wrapper that traces top-level `run` / `execute` / `invoke` methods via `inspectRun`.
+
+## 3. Stable local inspection APIs
+
+These APIs support local workflows like listing traces, extracting metadata/summaries, and safety checks for deletion.
+
+- **`TraceDirectory`**, **`resolveTraceDir`**
+- **`extractMetadata`**, **`buildRunSummary`**
+- **`filterTraces`**
+- **`isAgentInspectTrace`** (conservative trace verifier for cleanup)
+- **`parseDuration`**, **`formatDuration`**
+- Types: **`TraceMetadata`**, **`RunSummary`**
+
+## 4. Stable event/config model types
+
+### Manual trace JSONL model (stable)
+
+- **`TraceSchemaVersion`** (`"0.1"`)
+- **`TraceEvent`** union and specific event types:
+  - `RunStartedEvent` (`event: "run_started"`)
+  - `RunCompletedEvent` (`event: "run_completed"`)
+  - `StepStartedEvent` (`event: "step_started"`)
+  - `StepCompletedEvent` (`event: "step_completed"`)
+- Related types: `StepType`, `StepStatus`, `RunStatus`, `ErrorInfo`, `StepMetadata`, `TokenMetadata`
+
+### Log-derived normalized model (stable as a model, not necessarily the parsing APIs)
+
+- **`InspectKind`**
+- **`AttributionConfidence`**
+- **`InspectEvent`**, **`InspectNode`**, **`InspectRunTree`**
+- **`EventSource`**
+
+### Log ingest config types (stable)
+
+- **`LogIngestConfig`**
+- **`LogEventMapping`**
+- **`RedactionRule`**, **`RedactionStrategy`**
+
+## 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.
+
+- **`parseLogsToTrees`**
+- **`JsonLogParser`**, **`Log4jsParser`**
+- **`EventNormalizer`**
+- **`TreeBuilder`**
+- **`Redactor`**
+- **`renderRunTree`**, **`renderRunTrees`**
+- **`parseLogLine`**
+
+## 6. Experimental live tail APIs
+
+The CLI `tail` workflow is supported. The programmatic accumulator is experimental.
+
+- **`LiveLogAccumulator`**
+
+## 7. Experimental standards export APIs
+
+Exports are **read-only**, **local-only**, and **compatibility-oriented**. They do not upload, stream, or integrate vendor SDKs.
+
+- **`exportRunTree`**
+- **`exportMarkdown`**, **`exportHtml`**
+- **`exportOpenInference`** (OpenInference-compatible JSON)
+- **`exportOtlpJson`** (OTLP JSON, experimental until verified per backend)
+- **`validateExport`**, `validateExportContent` (validation helpers)
+
+## 8. Experimental diff APIs
+
+Diff is local and read-only. Programmatic diff surfaces are experimental until the comparison semantics are explicitly frozen.
+
+- **`diffRuns`**
+- **`diffTraceEvents`**
+- **`renderRunDiff`**
+- **`manualTraceEventsToComparableRun`**
+
+## 9. Experimental `@agent-inspect/langchain` APIs
+
+`@agent-inspect/langchain` is an optional adapter package.
+
+- **`AgentInspectCallback`** (experimental)
+- Metadata helpers: `extractModelName`, `extractTokenUsage`, `safePreview`, `toPlainMetadata`
+
+Rationale: v1.0 includes one official adapter and **zero production sinks**, so adapter surfaces remain experimental.
+
+## 10. Experimental `@agent-inspect/tui` APIs
+
+`@agent-inspect/tui` is an optional package. CLI integration via `agent-inspect view --tui` is supported; programmatic TUI APIs remain experimental.
+
+- `runTraceViewer`, `loadTraceForTui`, `buildTuiTraceModel`, etc.
+
+## 11. Deprecated APIs
+
+No deprecated APIs are declared in v1.0 Pass 1.
+
+## 12. 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.
+
+## 13. 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.
+
+## 14. Examples
+
+### Minimal manual trace
+
+```ts
+import { inspectRun, step } from "agent-inspect";
+
+await inspectRun("demo-agent", async () => {
+  const plan = await step("plan", async () => "ok");
+  const hits = await step.tool("search", async () => ({ count: 2 }));
+  const answer = await step.llm("fixture-model", async () => "done");
+  return { plan, hits, answer };
+});
+```
+

package/docs/ARCHITECTURE.md

@@ -0,0 +1,13 @@
+## Architecture
+
+This doc is a stable entry point for AgentInspect’s internal architecture and product boundaries.
+
+- **Canonical architecture overview**: see `docs-local/architecture/ARCHITECTURE.md`
+- **Event model**: `docs-local/architecture/EVENT-MODEL.md`
+- **Tree building rules**: `docs-local/architecture/TREE-BUILDING-RULES.md`
+- **Schema evolution policy**: `docs-local/architecture/SCHEMA-EVOLUTION.md`
+- **Dependency policy**: `docs-local/architecture/DEPENDENCY-POLICY.md`
+- **Redaction design**: `docs-local/architecture/REDACTION.md`
+
+If you’re new, start with `docs/GETTING-STARTED.md`, then `docs/API.md`, `docs/CLI.md`, and `docs/SCHEMA.md`.
+