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

CONTRIBUTING.md

@@ -1,5 +1,7 @@
 # Contributing to TRACE
 
+This page explains how to propose a change to TRACE and what reviewers will ask for. Small fixes such as typos and broken links can go straight to a pull request; changes to the rules every implementation must follow need more discussion and a named organization behind them, as described below.
+
 TRACE is an open specification. Contributions are welcome in four areas: the specification text, the JSON Schema, the examples, and the conformance test suite (in [trace-spec/conformance](https://github.com/agentrust-io/trace-spec/tree/main/conformance)).
 
 ## Running the reference-library checks
@@ -31,6 +33,8 @@ The check you just fixed is not that something.
 
 ## Before a pull request is reviewed
 
+In short: the automated tests must pass, and a bug fix must come with a test that would have caught the bug.
+
 A pull request gets a full review once every `test` job of the `CI` workflow,
 which runs the checks above, succeeds on its head commit. Other checks on the
 pull request, such as the maintainer-approval gate, do not hold a review,
@@ -86,7 +90,7 @@ This adds `Signed-off-by: Your Name <you@example.com>`. PRs without DCO sign-off
 
 ### Spec changes (normative text)
 
-Changes to `spec/trace-v0.2.md` that affect what implementations must do. Normative text is any statement using an RFC 2119 keyword in uppercase: what a conformant implementation MUST, SHOULD or MAY do. A normative change binds every implementation of TRACE, including implementations whose authors are not in the discussion.
+These are changes to the rules every TRACE implementation has to follow, so they carry the most weight and the most process. Changes to `spec/trace-v0.2.md` that affect what implementations must do. Normative text is any statement using an RFC 2119 keyword in uppercase: what a conformant implementation MUST, SHOULD or MAY do. A normative change binds every implementation of TRACE, including implementations whose authors are not in the discussion.
 
 **Anyone may propose a Normative Change, however only Normative Contributions with an organizational sponsor willing to implement and maintain that element in the specification will be accepted.**
 

LIMITATIONS.md

@@ -1,35 +1,37 @@
 # Known Limitations
 
-This document describes what TRACE does not do, and where layered defenses are needed. Honest scope boundaries prevent misplaced trust.
+This page lists what TRACE does not do, so you know where you still need other safeguards. Read it before you rely on a TRACE record for anything that matters. A TRACE record (also called a Trust Record or claim) is a signed receipt describing one AI agent run; most of what follows is about the gap between "this receipt is genuine" and "what it describes really happened".
 
 ## What a TRACE claim does not prevent
 
 **Operator-forged software-only records**
-A TRACE claim at Level 0 (software-only signing) is signed by a key held in software. A privileged operator with root access can produce a valid-looking Level 0 record for a run that never happened, or that violated policy. Level 0 is suitable for development and audit-trail tooling only, not for third-party verification.
+Level 0 is the entry level, where a record is signed with an ordinary software key and no hardware evidence. Whoever runs the machine can read that key. A privileged operator with root access can produce a valid-looking Level 0 record for a run that never happened, or that violated policy. Level 0 is suitable for development and audit-trail tooling only, not for third-party verification.
 
 **Replay of a valid past record**
-A TRACE claim proves a specific run happened; it does not prevent a verifier from being shown a valid record from an earlier run. Verifiers that rely on recency must bound `iat` in both directions (maximum age and allowed future clock skew), check `exp` when present, require nonce binding to a challenge, or anchor records to a public transparency log and check for freshness.
+A genuine old record stays genuine, so someone can show you last week's record and pass it off as today's. A TRACE claim proves a specific run happened; it does not prevent a verifier from being shown a valid record from an earlier run. Verifiers that rely on recency must bound `iat` in both directions (maximum age and allowed future clock skew), check `exp` when present, require nonce binding to a challenge, or anchor records to a public transparency log and check for freshness.
 
 **Policy correctness**
-The `policy.bundle_hash` field attests that a specific policy was in force at runtime. It does not attest that the policy achieves the intended security outcome. Policy review is a separate control.
+A record can show which rules the agent ran under, but not whether those rules were any good. The `policy.bundle_hash` field attests that a specific policy was in force at runtime. It does not attest that the policy achieves the intended security outcome. Policy review is a separate control.
 
 **What happened inside the model**
-The call transcript records tool invocations, arguments, and responses that are observable at the gateway boundary. It does not record the model's internal chain-of-thought, intermediate reasoning, or context window contents. Reasoning that influences behavior without producing a tool call is not captured.
+TRACE sees what the agent did, not what the model thought. The call transcript records tool invocations, arguments, and responses that are observable at the gateway boundary. It does not record the model's internal chain-of-thought, intermediate reasoning, or context window contents. Reasoning that influences behavior without producing a tool call is not captured.
 
 **Cross-boundary data propagation**
-The call graph summary uses temporal adjacency to approximate data flow between tool calls. It cannot definitively prove which specific data from one tool response influenced which subsequent call. The `provenance_disclaimer` field in every call graph summary is required for this reason.
+TRACE can show that one tool call came after another, but not prove that data from the first actually fed the second. The call graph summary uses temporal adjacency to approximate data flow between tool calls. It cannot definitively prove which specific data from one tool response influenced which subsequent call. The `provenance_disclaimer` field in every call graph summary is required for this reason.
 
 **TEE side-channel attacks**
-Hardware attestation proves the TRACE signing key and policy engine were measured in silicon before execution. It does not protect against side-channel attacks (cache timing, power analysis) targeting the TEE itself. TEE-level side-channel defense is the responsibility of the TEE platform vendor.
+A TEE (trusted execution environment) is a sealed area of a processor that even the machine's operator cannot look into. Hardware attestation, the processor's signed report of what is running inside it, proves the TRACE signing key and policy engine were measured in silicon before execution. It does not protect against side-channel attacks (cache timing, power analysis) targeting the TEE itself. TEE-level side-channel defense is the responsibility of the TEE platform vendor.
 
 **Revocation of the signing key after issuance**
-If the TRACE signing key is compromised after records are issued, existing records remain cryptographically valid. Key monitoring, rapid revocation, and transparency log integration are the required controls: TRACE provides the anchoring mechanism but cannot detect compromise itself.
+If a signing key is stolen later, everything it already signed still checks out. If the TRACE signing key is compromised after records are issued, existing records remain cryptographically valid. Key monitoring, rapid revocation, and transparency log integration are the required controls: TRACE provides the anchoring mechanism but cannot detect compromise itself.
 
 **Pure offline verification cannot prove non-revocation**
-Signature validity is permanent; trust is not. Nothing inside a record can retract the key that signed it, so a record signed by a since-revoked key verifies offline forever. Spec §3.2.1 accordingly requires verifiers to consult current revocation status at verification time, which is by definition an online step. `verify_record()` takes a `revocation` store, either a container of revoked identifiers or a callable performing a live CRL, status-endpoint, or SCITT lookup. It rejects a listed key, and fails closed when the store cannot answer. Without that store, verification is offline and its result means "this record was validly signed by this key", not "this key is still trusted".
+Checking a record with no network connection tells you it was signed by a given key, but not whether that key has since been withdrawn. Signature validity is permanent; trust is not. Nothing inside a record can retract the key that signed it, so a record signed by a since-revoked key verifies offline forever. Spec §3.2.1 accordingly requires verifiers to consult current revocation status at verification time, which is by definition an online step. `verify_record()` takes a `revocation` store, either a container of revoked identifiers or a callable performing a live CRL, status-endpoint, or SCITT lookup. It rejects a listed key, and fails closed when the store cannot answer. Without that store, verification is offline and its result means "this record was validly signed by this key", not "this key is still trusted".
 
 ## Platform state is not appraised
 
+An AMD processor's signed report says which software is running and, separately, how the machine itself is configured. The checks described here cover the first part only, so a report from a machine with weaker security settings passes just as cleanly.
+
 <!-- This is the source copy of the marked block. cmcp and ca2a carry it
      verbatim and their limitations-parity workflows check it against this
      file, so a change here has to land before theirs. The paragraph after
@@ -64,12 +66,14 @@ appraise it even where the producer checked it. The spec does not assert it for
 
 ## What Level 0 does not provide
 
-Level 0 provides software signatures without hardware-rooted assurance. A privileged operator may extract the signing key; a valid signature does not establish that execution was protected by a TEE.
+Level 0 is useful for development and for keeping an audit trail, but it is not evidence an outside party should accept on its own. Level 0 provides software signatures without hardware-rooted assurance. A privileged operator may extract the signing key; a valid signature does not establish that execution was protected by a TEE.
 
-TRACE verification levels describe technical evidence, not legal compliance. Article 12 of the EU AI Act requires a logging capability; it does not prescribe a TRACE level or tamper-evident format. See the [regulatory context in the specification](spec/trace-v0.2.md#1-problem). Neither a TRACE level nor transparency-log anchoring alone establishes compliance with the EU AI Act or DORA. Deployment-specific obligations require a separate assessment.
+TRACE levels describe the strength of technical evidence; they say nothing about legal compliance. Article 12 of the EU AI Act requires a logging capability; it does not prescribe a TRACE level or tamper-evident format. See the [regulatory context in the specification](spec/trace-v0.2.md#1-problem). Neither a TRACE level nor transparency-log anchoring alone establishes compliance with the EU AI Act or DORA. Deployment-specific obligations require a separate assessment.
 
 ## What the SDK does not do
 
+The SDK is the `agentrust-trace` Python library that signs and checks records. These jobs sit outside it:
+
 - **Evaluate Cedar policy**: the SDK includes the Cedar policy field in the claim; evaluation requires the Cedar engine (included in AGT or cMCP)
 - **Store or index records**: the SDK produces and verifies TRACE claim documents; storage, rotation, and retrieval are the caller's responsibility
 - **Anchor to a transparency log**: the SDK generates records suitable for SCITT anchoring; submission to a transparency log requires a separate SCITT client
@@ -78,7 +82,7 @@ TRACE verification levels describe technical evidence, not legal compliance. Art
 
 ## Performance
 
-Hardware attestation adds latency at the point of claim generation (not per-tool-call):
+Hardware evidence makes signing a record slower, once per record rather than on every tool call:
 
 | Provider | Typical claim signing latency |
 |---|---|

MAINTAINERS.md

@@ -1,5 +1,7 @@
 # Maintainers
 
+This page lists who reviews and decides changes to TRACE, and how a regular contributor can take on one of those roles.
+
 ## Project Lead
 
 | Name | Affiliation | GitHub | Contact |

README.md

@@ -33,9 +33,9 @@ Community updates and contributor highlights: [AgenTrust on LinkedIn](https://ww
 
 > **Developer Preview.** Launched at Confidential Computing Summit, 23 June 2026. Spec v0.2 is current. See [LIMITATIONS.md](LIMITATIONS.md) before relying on it in production.
 
-An open specification for portable, signed runtime evidence about AI agent runs. TRACE defines the format, anchoring protocol, and verification rules for a record of what an agent ran, where, under which policy, touching which data, and calling which tools, signed so any third party can check it offline. A v0.2 signature proves who produced a record and that it has not changed; hardware provenance needs attestation verified against a trusted root, which the proposed [v0.3 runtime evidence profile](docs/rfcs/runtime-evidence-profile.md) adds.
+TRACE is an open format for a signed receipt of an AI agent run: what ran, where, under which rules, on what kind of data, and which tools it called. Anyone holding the receipt (a Trust Record) can check it on their own computer, without asking the operator. This repository holds the specification, the JSON schema, test vectors and the `agentrust-trace` Python library.
 
-A TRACE Trust Record answers: _what ran, where, under which policy, touching which data, calling which tools_, in a form any third party can check offline without asking the operator.
+A v0.2 signature proves who made a record and that it has not changed. It does not prove the hardware claims inside it: that needs a signed report from the processor itself (attestation), checked against the chip maker's root certificate, which the proposed [v0.3 runtime evidence profile](docs/rfcs/runtime-evidence-profile.md) adds.
 
 ## What a Trust Record claims
 
@@ -100,7 +100,7 @@ Hosted at the Linux Foundation as its own series, "TRACE Specification, a Series
 
 ### What is TRACE?
 
-TRACE (Trust, Runtime Attestation, and Compliance Evidence) is an open specification for hardware-attested AI agent governance records. It defines the record format, the anchoring protocol, and the verification rules for cryptographic evidence that an AI agent ran under a specific policy, in a verified hardware environment, on a given data class, invoking identified tools.
+TRACE (Trust, Runtime Attestation, and Compliance Evidence) is an open specification for signed records of AI agent runs. It defines the record format, how records are published to a public log, and the rules for checking them. A record states that an agent ran under a specific policy, on a stated platform, on a given class of data, calling identified tools; the signature makes those statements tamper-evident, and hardware attestation, where present, is what backs the platform claim.
 
 ### What does a TRACE Trust Record prove?
 
@@ -116,11 +116,11 @@ Install the library with `pip install agentrust-trace`, sign a record with `sign
 
 ### How does TRACE relate to AGT and cMCP?
 
-TRACE is the evidence format. AGT and cMCP produce and consume Trust Records, so you can connect them into an end-to-end agent governance pipeline. See the integration guides for details.
+TRACE is the evidence format. AGT and cMCP write and read Trust Records, so you can connect them so that every agent action ends in a record someone else can check. See the integration guides for details.
 
 ### What is the current status of TRACE?
 
-The current specification is TRACE v0.2, published with a conformance test suite. See the Limitations page for scope boundaries before relying on it in production.
+The current specification is TRACE v0.2, published with a conformance test suite, as a Developer Preview. TRACE is a Series of LF Projects, and a proposal to bring it into the Agentic AI Foundation as a Sandbox project is in progress ([aaif/project-proposals #42](https://github.com/aaif/project-proposals/issues/42)). See the Limitations page for what it does not cover before relying on it in production.
 
 ## Contributing