docs: plain-language pass on the docs site and README

README.md

@@ -1,34 +1,36 @@
-# AgentTrust Telemetry
+# AgenTrust Telemetry
 
 Community updates and contributor highlights: [AgenTrust on LinkedIn](https://www.linkedin.com/company/agentrust-io/).
 
-Portable governance telemetry and verifiable evidence for AI-agent runtimes.
+AgenTrust Telemetry is a shared format for the governance facts an AI agent produces while it runs: which rule allowed or blocked an action, who approved it, how many tokens and how much money it used, what kind of data moved where, and what the agent actually did. It is for teams that build or run agents and want those facts in one consistent, checkable form instead of scattered across separate logs. You get JSON schemas, test fixtures, and Python and TypeScript libraries that attach these facts to the OpenTelemetry traces your application already produces (OpenTelemetry is the common open standard for application traces, logs and metrics).
 
-This repository defines a backend-neutral contract for policy decisions, approval lifecycles, usage, classified data flows, and evidence lifecycle events. It composes with OpenTelemetry; it is not a tracing backend, policy engine, agent framework, or dashboard.
+In technical terms, this repository defines a backend-neutral contract, a fixed set of event formats that works with any monitoring or storage system, for policy decisions, approval lifecycles, usage, classified data flows, and evidence lifecycle events. It works alongside OpenTelemetry. It is not a tracing backend, policy engine, agent framework, or dashboard.
 
 > **Status:** alpha contract `0.1.0-alpha.6`. No stable SDK API or compatibility guarantee exists yet.
 
 ## Why
 
-Agent applications can already emit model and tool traces, but governance facts are often trapped in policy-engine logs, approval databases, cost modules, and proprietary dashboards. AgentTrust Telemetry gives those facts one privacy-conscious contract and correlates them with the OpenTelemetry trace already produced by the application.
+Agent applications can already record their model and tool calls as traces. The governance facts usually live somewhere else: in policy-engine logs, approval databases, cost modules and vendor dashboards. AgenTrust Telemetry puts those facts into one format that leaves out private content such as prompts, outputs and credentials, and links each fact to the OpenTelemetry trace the application already produces.
 
-The application keeps its collector, backend, policy engine, workflow framework, and UI.
+You keep your own collector, backend, policy engine, workflow framework and UI.
 
 ## Event families
 
-| Family | Purpose |
+Every event belongs to one of six families.
+
+| Family | What it records |
 |---|---|
-| Policy decision | Allow, deny, challenge, error, enforcement mode, policy identity and timing |
-| Approval lifecycle | Requested through terminal decision and execution outcome, bound to an action digest |
-| Usage | Per-call/run token and cost facts with explicit cost provenance |
-| Data flow | Classified source-to-destination metadata without payload capture |
-| Action execution | Resolved tool, MCP, A2A, file, HTTP, and database attempts |
-| Evidence lifecycle | Run checkpoints, completeness, and optional TRACE finalization status |
+| Policy decision | Whether a rule allowed, denied or challenged an action (or failed with an error), the enforcement mode, which policy decided, and how long it took |
+| Approval lifecycle | A human approval from request to final decision and what happened next, tied to a digest (a fingerprint) of the exact action |
+| Usage | Tokens and cost per call or per run, with where each cost figure came from |
+| Data flow | What kind of data moved from which source to which destination, without copying the data itself |
+| Action execution | Each attempted tool, MCP, A2A, file, HTTP or database action and how it ended |
+| Evidence lifecycle | Checkpoints for a run, whether its record is complete, and the status of an optional TRACE receipt |
 
 ## Current contents
 
 - JSON Schema 2020-12 event contracts in `spec/schema/`.
-- Valid and invalid conformance fixtures in `conformance/fixtures/`.
+- Valid and invalid conformance fixtures (sample events the schemas must accept or reject) in `conformance/fixtures/`.
 - An independent Python conformance runner in `conformance/runner/`.
 - Contract tests in `tests/`.
 
@@ -40,7 +42,7 @@ python conformance/runner/validate.py
 python -m unittest discover -s tests -v
 ```
 
-The validator checks schema conformance and the metadata-only privacy invariant. It does not yet validate OTLP projection or TRACE mapping.
+The validator checks that each event matches its schema and carries metadata only, never private content. It does not yet check the OpenTelemetry (OTLP) output or the TRACE mapping.
 
 ## Python reference SDK
 
@@ -57,11 +59,11 @@ client = TelemetryClient(SchemaValidator.bundled())
 result = client.emit(normalized_event)
 ```
 
-The SDK uses the caller's current OpenTelemetry span when `opentelemetry-api` is installed. It never installs a provider or exporter. A caller may additionally supply a structured-log emitter.
+When `opentelemetry-api` is installed, the SDK attaches each event to the OpenTelemetry span (one timed step in a trace) that is active when you call it. It never installs a provider or exporter, so your existing OpenTelemetry setup stays in charge. You can also pass in your own structured-log emitter.
 
-For synchronous cross-process agent calls, propagate the caller's W3C context and
-durable AgenTrust identifiers, then use the extracted context as the receiving
-span's remote parent:
+When one agent calls another in a different process and waits for the answer,
+pass along the caller's W3C trace context and the AgenTrust run and agent IDs,
+then use the extracted context as the parent of the receiving span:
 
 ```python
 from agentrust_telemetry import extract_context, inject_context
@@ -74,10 +76,10 @@ with tracer.start_as_current_span("worker", context=remote.otel_context):
     event.update(remote.event_fields(agent_id="worker"))
 ```
 
-For asynchronous queue handoffs, start a new trace with
-`links=[remote.link()]`. This preserves causality without representing queued
-work as a synchronous child span. Propagated metadata is untrusted input and
-does not establish agent identity or authorization.
+When work goes through a queue instead, start a new trace with
+`links=[remote.link()]`. The two traces stay connected, and the queued work is
+not shown as a direct child step. Treat propagated metadata as untrusted input:
+it does not prove who an agent is or what it is allowed to do.
 
 Run the synthetic example:
 
@@ -95,12 +97,14 @@ npm ci
 npm run check
 ```
 
-It validates the same fixtures and privacy profile as Python and preserves
-nanosecond wire timestamps as decimal strings. It does not install an OTel
-provider, exporter, or global propagator.
+It validates the same fixtures and privacy rules as the Python SDK and keeps
+nanosecond timestamps as decimal strings, so no precision is lost. It does not
+install an OpenTelemetry provider, exporter, or global propagator.
 
-Run the complete AGT-compatible governance, OTel, durable-evidence, and TRACE
-reference workflow (Python 3.11+ with test extras installed):
+To see the whole path in one run, use the reference workflow. It takes
+AGT-compatible governance events, writes them to OpenTelemetry, keeps a durable
+evidence chain, and finishes with a signed TRACE record (Python 3.11+ with test
+extras installed):
 
 ```shell
 python -m pip install -e ".[test]"
@@ -109,11 +113,11 @@ python examples/governed_workflow.py
 
 ## Contract principles
 
-- `run_id` is durable execution correlation; `trace_id` is an optional W3C operational trace context.
-- Standard OpenTelemetry fields take precedence over AgentTrust extensions.
+- `run_id` ties together everything from one agent run and is kept for the long term; `trace_id` is an optional W3C trace ID for day-to-day operations.
+- Where a standard OpenTelemetry field exists, it takes precedence over an AgenTrust extension.
 - Raw prompts, output, source code, tool arguments/results, credentials, and authorization tokens are prohibited in the metadata-only profile.
-- Operational telemetry can be lossy; evidence completeness must never be overstated.
-- An event reports a fact observed elsewhere. This project does not make authorization decisions.
+- Operational telemetry can lose data; evidence completeness must never be overstated.
+- An event reports something that was observed elsewhere. This project does not decide what is authorized.
 
 ## Architecture and project policy
 

docs/action-events.md

@@ -1,5 +1,12 @@
 # Action execution events
 
+This page explains the event that records each action an agent tried to take,
+such as calling a tool or sending an HTTP request, and how that action is matched
+to a human approval. Read it if you produce or check these events. In short,
+every action carries a digest (a fingerprint of exactly what was done), and an
+action that needed approval has to point to an approval for that same
+fingerprint, given before the action ran.
+
 `action.executed` records one resolved action attempt. It covers tools, MCP,
 A2A, file, HTTP, database, and explicitly identified other actions.
 

docs/adapters.md

@@ -1,5 +1,11 @@
 # Event factories and policy adapters
 
+Adapters turn records from policy and approval tools you may already run (OPA,
+Cedar and the Agent Governance Toolkit, AGT) into AgenTrust Telemetry events, so
+you do not have to write that mapping yourself. This page is for developers
+wiring one of those tools in. It says what each adapter copies, what it leaves
+out on purpose, and what it cannot prove.
+
 `EventFactory` owns normalized envelope construction: specification version,
 producer identity, event UUID, timestamp, correlation fields, schema validation,
 and privacy validation. Its generic `build` method supports every event family,

docs/architecture.md

@@ -1,8 +1,14 @@
 # Architecture
 
+This page shows where AgenTrust Telemetry sits: between the places governance
+facts come from (policy checks, approvals, usage and data hooks) and the places
+you send them (your own OpenTelemetry backend, and an evidence record that can
+become a TRACE receipt). Read it to understand the parts, how events are linked
+to each other, and what the project depends on.
+
 ## Boundary
 
-AgentTrust Telemetry is a schema-first instrumentation layer between governance sources and adopter-owned telemetry/evidence destinations.
+AgenTrust Telemetry is a schema-first instrumentation layer between governance sources and adopter-owned telemetry/evidence destinations.
 
 ```text
 policy / approval / usage / data hooks
@@ -43,7 +49,7 @@ A caller-owned structured-log emitter may receive a defensive deep copy of the v
 
 The Node reference package in `packages/typescript` shares the normative schemas,
 metadata-only privacy gate, normalized event factory, OTel span/log projection,
-and W3C plus AgentTrust context propagation semantics. Its schema copies are
+and W3C plus AgenTrust context propagation semantics. Its schema copies are
 byte-compared to `spec/schema` in CI. It requires a caller-owned OTel provider,
 exporters, and global propagator.
 

docs/data-flow-classification.md

@@ -1,5 +1,11 @@
 # Data-flow classification
 
+When an agent moves data, for example reading a customer record and passing it to
+a tool, this event records what kind of data it was and where it went, without
+copying the data. This page is for developers who plug in their own classifier
+(the code that decides how sensitive a piece of data is). It explains what the
+helper guards against and what it cannot guarantee.
+
 `classified_data_flow` is a closed metadata boundary around an adopter-owned
 classifier. Raw content is passed to `classifier.classify` and is never inserted
 into the event. The classifier must return `ClassificationResult`; dictionaries

docs/evidence-chain.md

@@ -1,5 +1,11 @@
 # Evidence chain profile
 
+The evidence chain links every accepted event to the one before it with a hash,
+so that editing, dropping or reordering an event afterwards can be detected. The
+chain is not signed: it shows the events are consistent with each other, and it
+does not prove who wrote them. This page gives the exact recipe for developers
+who need to recompute or check the chain.
+
 Status: experimental `rfc8785-jcs-v1` for contract `0.1.0-alpha.6`.
 
 Each accepted event is validated and privacy-checked before entering the chain.

docs/otel-genai-compatibility.md

@@ -1,12 +1,18 @@
 # OpenTelemetry GenAI compatibility
 
-Status: pinned compatibility assessment for AgentTrust contract `0.1.0-alpha.6`.
+OpenTelemetry has its own draft conventions for AI traces and metrics, called the
+GenAI semantic conventions. This page says, field by field, where AgenTrust
+Telemetry uses the same thing, where it adds something new, and where the two
+only look alike. Read it if you already use OpenTelemetry GenAI instrumentation
+and want to know what to keep.
+
+Status: pinned compatibility assessment for AgenTrust contract `0.1.0-alpha.6`.
 
 The machine-readable matrix is [`compatibility/otel-genai.json`](../compatibility/otel-genai.json).
 It is pinned to OpenTelemetry's dedicated GenAI semantic-conventions repository
 at commit `a685613a207a580163353b8e48a7ad88967e7b42` (2026-08-15).
 Those conventions are in Development status. At the pinned revision the upstream
-schema URL is still unpublished, so AgentTrust does not advertise one.
+schema URL is still unpublished, so AgenTrust does not advertise one.
 
 Primary upstream references:
 
@@ -19,25 +25,25 @@ Primary upstream references:
 ## Compatibility meanings
 
 - `exact`: the same field has the same semantics, subject to its stated precondition.
-- `extension`: AgentTrust adds a governance or evidence concept OTel does not define.
+- `extension`: AgenTrust adds a governance or evidence concept OTel does not define.
 - `complementary`: both signals may describe the same operation from different layers.
 - `non_equivalent`: names or subject matter overlap, but substitution would be incorrect.
 - `deferred`: OTel owns the signal or it conflicts with the metadata-only profile.
 
-AgentTrust currently has one exact GenAI attribute mapping: a stable `agent_id` may
+AgenTrust currently has one exact GenAI attribute mapping: a stable `agent_id` may
 project to `gen_ai.agent.id`. It does not use that attribute for a transient process
-instance. W3C trace and span context is also native rather than an AgentTrust extension.
+instance. W3C trace and span context is also native rather than an AgenTrust extension.
 
 The `agentrust.usage.tokens` Counter is deliberately **not** represented as
 `gen_ai.client.token.usage`. The pinned OTel convention defines a per-operation
 Histogram whose well-known token types are `input` and `output` (custom values
 are permitted). The same pinned revision already defines span attributes for
 `gen_ai.usage.cache_read.input_tokens`, `gen_ai.usage.cache_creation.input_tokens`
 and `gen_ai.usage.reasoning.output_tokens`; see the model-span reference above.
-AgentTrust records additive facts attributed to `model_call`, `agent_step`,
+AgenTrust records additive facts attributed to `model_call`, `agent_step`,
 `task`, `agent_run` or `workflow_run`. Its distinction is attribution scope and
 instrument semantics, not the existence of cache or reasoning token categories.
-Applications should retain their existing GenAI instrumentation and use AgentTrust
+Applications should retain their existing GenAI instrumentation and use AgenTrust
 events for governance attribution.
 
 Likewise, `action.executed` does not replace `gen_ai.execute_tool` spans: it includes

docs/otel-projection.md

@@ -1,5 +1,10 @@
 # OpenTelemetry projection profile
 
+This page describes exactly how an AgenTrust event is copied into OpenTelemetry:
+as an event on the current span, as a structured log, and as metrics. It is for
+developers checking what will show up in their tracing or metrics backend, and
+what the SDK does when one of those outputs fails.
+
 Status: experimental for contract `0.1.0-alpha.6`.
 
 The normalized JSON event is the source contract. OpenTelemetry is a projection, not an alternative event model.

docs/trace-finalization.md

@@ -1,8 +1,14 @@
 # TRACE finalization
 
+TRACE is the AgenTrust format for signed receipts of what an agent run did. This
+page explains how to turn a finished, complete set of telemetry events into one
+signed TRACE record, what you have to supply (including the signing key), and
+when the step refuses to produce a record. A record made this way is marked
+software-only, because it carries no hardware attestation.
+
 Status: experimental. Python requires 3.11+ and `agentrust-telemetry[trace]`.
 TypeScript requires a caller-supplied official TRACE codec because no official
-AgentTrust TRACE Node package is currently published.
+AgenTrust TRACE Node package is currently published.
 
 `finalize_trace` maps a sealed, explicitly complete evidence snapshot into the
 official TRACE v0.2 model, signs it with a caller-supplied key, validates it, and

docs/usage-attribution.md

@@ -1,6 +1,10 @@
 # Usage and cost attribution
 
-`usage.recorded` reports measurements observed by an adapter. AgentTrust
+This page covers how token counts and costs are recorded and added up per run or
+per workflow. The project records only numbers that a provider or your own code
+supplies, and it never guesses a missing cost.
+
+`usage.recorded` reports measurements observed by an adapter. AgenTrust
 Telemetry does not count tokens, resolve model prices, or infer a missing cost.
 
 Use `usage_record()` for call-level facts and supply `CostObservation` only when