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

LIMITATIONS.md

@@ -1,5 +1,30 @@
 # Limitations
 
+This page says what cA2A proves today, what it does not, and what is still being
+built, so you can decide how much to rely on it. Read it before you rely on any
+hardware claim.
+
+cA2A 0.4.0 (published as `ca2a-runtime`) is a developer preview with a runnable,
+tested profile and runtime. This document states plainly what is built, what
+remains before 1.0, and what is out of scope, so no claim in the documentation runs
+ahead of the code. This is a deliberate discipline: proof, not promises.
+
+In short:
+
+- **Works offline today, no hardware needed:** checking that a chain of permissions
+  starts at an authority you trust and only narrows at each handoff, refusing
+  revoked grants when you supply a revocation list, encrypting a task to one agent,
+  and checking signed records of each handoff.
+- **Checked on real hardware, with limits:** AMD SEV-SNP and Intel TDX reports from
+  real Azure and GCP machines; an Azure agent calling a GCP agent in one direction;
+  two GCP machines run by one operator checking each other in both directions.
+  Two machines run by different operators checking each other has not yet been shown.
+- **Off unless you turn it on:** checking the platform settings inside a hardware
+  report (such as whether SMT is on), and authenticating the answer that comes back
+  from a call.
+- **Not done at all:** publishing or fetching revocation data. A checker knows only
+  about the revocations in the snapshot you hand it.
+
 ## Opt-in response authentication
 
 `send_task(require_authenticated_response=True)` authenticates readable
@@ -11,8 +36,6 @@ MAC key. Hardware assurance still requires explicit hardware appraisal; the new
 profile has software/HTTP tests and no new live-hardware validation. See the
 [profile and deployment limits](docs/spec/response-authentication.md).
 
-cA2A 0.2 is a Developer Preview with a runnable, tested profile and runtime. This document states plainly what is built, what remains before 1.0, and what is out of scope, so no claim in the documentation runs ahead of the code. This is a deliberate discipline: proof, not promises.
-
 ## What is built
 
 - The delegation credential model and offline chain verifier: trusted-root checks, signatures, scope attenuation, depth and validity bounds, duplicate credential IDs within a chain, and cross-chain splice rejection. These checks do not maintain a global history of used credentials.

README.md

@@ -27,9 +27,11 @@ Community updates and contributor highlights: [AgenTrust on LinkedIn](https://ww
 
 [![PyPI](https://img.shields.io/pypi/v/ca2a-runtime)](https://pypi.org/project/ca2a-runtime/)
 
-> **Developer Preview.** cA2A 0.2 ships the profile, offline verifier, enforced peer runtime, sealed channel, signed TRACE provenance, and fail-closed SEV-SNP, TDX, and TPM appraisal. It may still introduce breaking changes before 1.0. See [ROADMAP.md](ROADMAP.md) and [LIMITATIONS.md](LIMITATIONS.md) for the remaining hardware and interoperability work.
+> **Developer Preview.** cA2A 0.4.0 ([`ca2a-runtime`](https://pypi.org/project/ca2a-runtime/) on PyPI) ships the profile, offline verifier, enforced peer runtime, sealed channel, signed TRACE provenance, and fail-closed SEV-SNP, TDX, and TPM appraisal. It may still introduce breaking changes before 1.0. See [ROADMAP.md](ROADMAP.md) and [LIMITATIONS.md](LIMITATIONS.md) for the remaining hardware and interoperability work.
 
-**cA2A (Confidential A2A) is the secure, confidential way to do agent-to-agent delegation on the [Agent2Agent (A2A)](https://a2a-protocol.org/) protocol.** It layers attested, attenuated delegation, a sealed peer channel, and an offline-verifiable provenance record on top of A2A, without replacing the transport. If you are looking for a secure version of A2A for multi-agent systems, this is the AgenTrust profile for it.
+**cA2A (Confidential A2A) lets one AI agent hand work to another on the [Agent2Agent (A2A)](https://a2a-protocol.org/) protocol and leaves proof of who allowed what.** Each handoff carries a signed permission slip that can only narrow, the receiving agent can be asked for a hardware-signed report of what software it runs (attestation), the task can be encrypted so only that agent can read it, and each step leaves a signed record anyone can check offline. It adds these to A2A without replacing how A2A sends messages. New to these terms? See [the plain-English glossary](https://agentrust-io.com/#plain-terms).
+
+In technical terms: cA2A layers attested, attenuated delegation, a sealed peer channel, and an offline-verifiable provenance record on top of A2A, without replacing the transport. If you are looking for a secure version of A2A for multi-agent systems, this is the AgenTrust profile for it.
 
 Agent A delegates a task to Agent B. B delegates part of it to C. Who authorized what? Did B stay inside the authority A actually held? Was the task payload readable by anyone between them? If a regulator asks, can you prove the answer for every hop?
 

ROADMAP.md

@@ -1,5 +1,9 @@
 # cA2A Roadmap
 
+This page lists what cA2A has delivered, release by release, and what is left before
+a stable 1.0. It is for anyone planning to adopt cA2A or contribute to it. For what
+the current release does and does not prove, read [LIMITATIONS.md](LIMITATIONS.md).
+
 cA2A is an extension of the agentrust-io stack, not a rewrite. The build tiers below track how much each piece leans on primitives that already exist in [agent-manifest](https://github.com/agentrust-io/agent-manifest), [cmcp](https://github.com/agentrust-io/cmcp), and [trace-spec](https://github.com/agentrust-io/trace-spec).
 
 ## Reused as-is (Tier 0)
@@ -30,13 +34,14 @@ Already implemented and tested elsewhere; cA2A depends on it rather than reimple
 
 Real hardware attestation verification (SEV-SNP VCEK chain, Intel TDX quote via QVL/PCS, TPM AK cert + checkquote) is shared with cMCP. Appraisal against genuine SEV-SNP and TDX evidence has landed; the work below tracks what remains before broadly claiming mutual, cross-operator hardware assurance.
 
-- **SEV-SNP verifier: landed and validated on real evidence.** Report parsing, VCEK chain verification, ECDSA-P384 report-signature verification, and measurement/report-data binding, all fail-closed, run against a genuine Azure CVM report (see [docs/hardware-validation.md](docs/hardware-validation.md)). Report generation is implemented via configfs-TSM but is not yet hardware-validated, and Azure's paravisor shape is out of scope for it. See `ca2a_verify.sev_snp` and [docs/spec/attestation.md](docs/spec/attestation.md).
-- **TDX verifier: landed and validated on real evidence.** DCAP Quote v4 parsing (including the nested type-6 QE certification data), PCK chain to the genuine Intel SGX Root CA, QE report signature, attestation-key binding, quote signature, and MRTD binding, all fail-closed, run against a genuine GCP C3 quote. Quote generation is implemented via configfs-TSM but is not yet hardware-validated. See `ca2a_verify.tdx`.
+- **SEV-SNP verifier: landed and validated on real evidence.** Report parsing, VCEK chain verification, ECDSA-P384 report-signature verification, and measurement/report-data binding, all fail-closed, run against a genuine Azure CVM report (see [docs/hardware-validation.md](docs/hardware-validation.md)). Report generation is implemented via configfs-TSM and was run on real silicon on 2026-08-24 (GCP `n2d-standard-4`, AMD Milan); Azure's paravisor shape is out of scope for it. See `ca2a_verify.sev_snp` and [docs/spec/attestation.md](docs/spec/attestation.md).
+- **TDX verifier: landed and validated on real evidence.** DCAP Quote v4 parsing (including the nested type-6 QE certification data), PCK chain to the genuine Intel SGX Root CA, QE report signature, attestation-key binding, quote signature, and MRTD binding, all fail-closed, run against a genuine GCP C3 quote. Quote generation is implemented via configfs-TSM and was run on real silicon on 2026-08-24 (GCP `c3-standard-4`). See `ca2a_verify.tdx`.
 - **TPM 2.0 verifier: landed.** TPMS_ATTEST parsing, AK chain to a caller-supplied vendor root, AK signature (ECDSA or RSA), magic/type checks, and qualifying-data/PCR-digest binding, all fail-closed. Quote generation requires a real TPM. See `ca2a_verify.tpm`.
 - **Cross-operator attestation (C6): validated in software.** A two-operator harness (SEV-SNP verifier + measurement pinning + sealed channel) shows independent keys, mutual attestation, confidential cross-operator delegation, and binary-swap detection. All six claims (C1-C6) are now validated experiments.
 - **Live attested peer: landed.** The `verifier` seam has been driven off a real SEV-SNP quote on an Azure confidential VM, so `verify_offer` returned `assurance="hardware"` and a payload was sealed to a hardware-vouched channel key; measurement mismatch and stale nonce both rejected. See [docs/hardware-validation.md](docs/hardware-validation.md).
 - **Cross-operator, cross-TEE run: landed.** An Azure SEV-SNP peer appraised a GCP Intel TDX peer's real quote, sealed a delegated task to the attested key, and the TDX enclave opened it, enforced the attenuated scope, allowed `tool:search` and refused `tool:purchase` with a denial record returned across the boundary. See [docs/hardware-validation.md](docs/hardware-validation.md).
-- **Pending:** a hardware run of the SEV-SNP and TDX collectors (both implemented against configfs-TSM, neither yet exercised on silicon), mutual attestation on real silicon in both directions (the protocol now supports it in software mode and is off by default; that hardware run was one-directional), simultaneous attestation (which needs a commitment step neither peer can back out of, a larger protocol than what landed), and the TPM certificate-chain path. TPM parsing, bindings and the AK signature are validated against a real Azure vTPM quote; SEV-SNP and TDX appraisal of real evidence is done. The transport that parses A2A messages into a `PeerRequest` has **landed** (`ca2a_runtime.transport.a2a_adapter`), running in software mode; the hardware seam is the `verifier` callable in `ca2a_runtime.attestation`.
+- **Collectors on silicon: landed 2026-08-24.** Both the SEV-SNP and TDX collectors produced real evidence on GCP that this codebase's own verifiers appraised to the vendor roots. See [docs/hardware-validation.md](docs/hardware-validation.md).
+- **Pending:** mutual attestation on real silicon across operators (on 2026-09-17 two GCP SEV-SNP guests in one project under one operator appraised each other in both directions; see [the mutual hardware procedure](docs/mutual-hardware-acceptance.md); the protocol is off by default), simultaneous attestation (which needs a commitment step neither peer can back out of, a larger protocol than what landed), and the TPM certificate-chain path. TPM parsing, bindings and the AK signature are validated against a real Azure vTPM quote; SEV-SNP and TDX appraisal of real evidence is done. The transport that parses A2A messages into a `PeerRequest` has **landed** (`ca2a_runtime.transport.a2a_adapter`), running in software mode; the hardware seam is the `verifier` callable in `ca2a_runtime.attestation`.
 
 ## v1.0 exit criteria: Stable profile
 

docs/SPEC.md

@@ -1,5 +1,7 @@
 # cA2A Profile Specification
 
+This is the front page of the cA2A specification: the rules an implementation follows so that one AI agent can hand work to another with a checkable permission, hardware proof, an encrypted task and a signed record of each handoff. Implementers and reviewers start here; it lists the design principles and links to each part of the rules.
+
 Status: draft, v0.1. This document describes the cA2A profile: a binding on A2A that makes agent-to-agent delegation attested, attenuated, confidential, and provable.
 
 ## Scope of this document

docs/concepts.md

@@ -1,32 +1,34 @@
 # How It Works
 
-cA2A layers delegation and peer trust checks onto A2A communication. Start with the [offline chain example](quickstart.md) to see grant validation; the live runtime adds caller authentication, local policy, optional appraisal, and payload handling.
+This page explains, in order, what cA2A checks when one agent hands work to another, and where each check's protection stops. Read it after the [offline chain example](quickstart.md), which shows the first check on its own. A live call between agents adds more: confirming who the caller is, applying the receiving agent's own rules, optionally checking hardware proof, and handling the encrypted task.
 
 ## The gap cA2A closes
 
-A signed identity document does not establish every authority or runtime property needed for a delegated task. The relying party must decide which root issuers, capabilities, measurements, and evidence it accepts. See the [threat model](spec/threat-model.md).
+A signed identity document says who an agent is. It does not say what that agent may do on someone else's behalf, or what software it is actually running. The agent receiving the work (the relying party) has to decide for itself which starting authorities, permissions, hardware measurements and evidence it accepts. The [threat model](spec/threat-model.md) lists the attacks this guards against.
 
 ## The four primitives
 
 ### 1. Attenuated delegation
 
-Each child grant is signed by the parent subject and must narrow or preserve the parent's scope. Verification checks trusted roots, signatures, parent links, credential IDs, depth, and validity windows. A valid chain establishes a grant; it does not authenticate the caller currently presenting it. The live path separately checks proof of possession of the leaf key. See [delegation chains](spec/delegation-chain.md).
+"Attenuated" means the permission can only stay the same or get smaller at each handoff. Each child grant is signed by the agent that received the parent grant, and its scope (its list of permissions) must fit inside the parent's. The checker confirms the chain starts at a trusted root and that signatures, parent links, credential IDs, chain length and time windows are all valid.
+
+A valid chain proves a grant was made. It does not prove that whoever is presenting it right now is the agent it was given to, so on a live call cA2A also asks the caller to prove it holds the final agent's private key. See [delegation chains](spec/delegation-chain.md).
 
 ### 2. Runtime attestation
 
-A provider produces evidence intended to bind a key to a measured runtime. The relying party must verify that evidence and apply its own measurement and assurance requirements. Software evidence does not establish hardware provenance. See [attestation](spec/attestation.md) and [limitations](../LIMITATIONS.md).
+Attestation is a report, signed by the processor, that says what software is running and ties the agent's encryption key to it. A provider (the part of cA2A that talks to TPM, AMD SEV-SNP or Intel TDX hardware) produces that report. The relying party checks it and applies its own rules about which measurements and how much assurance it requires. A report produced in software mode proves nothing about hardware. See [attestation](spec/attestation.md) and [limitations](../LIMITATIONS.md).
 
 ### 3. Sealed peer channel
 
-The caller encrypts a payload to the callee's appraised channel key. Hardware isolation depends on the verified provider and key binding. In software mode, this does not protect the key or plaintext from a privileged host. See [sealed channels](spec/sealed-channel.md).
+The caller encrypts the task to a key the receiving agent (the callee) published and the caller checked, so only the holder of the matching private key can read it. Whether that key is protected by hardware depends on the hardware report that vouched for it. In software mode, an administrator of the machine could still read the key and the task. See [sealed channels](spec/sealed-channel.md).
 
 ### 4. Provenance record
 
-Linked TRACE records carry the decision and parent references. Verifiers check signatures and links separately from credential-chain validation. The offline grant example does not execute a task or establish a provenance DAG. See [the TRACE A2A profile](spec/trace-a2a-profile.md).
+Each handoff leaves a signed TRACE record of the decision, pointing back to the record before it, so the records together show the path the work took. Checking those records is separate from checking the permission chain. The offline grant example does not run a task or produce these records. See [the TRACE A2A profile](spec/trace-a2a-profile.md).
 
 ## How they compose on a peer call
 
-The diagram follows the callee's inbound runtime checks. It shows the accepted path; a failed required check stops processing before payload opening.
+The diagram follows the checks the receiving agent runs on an incoming call, in order. It shows the path when everything passes; a failed required check stops the call before the task is decrypted.
 
 Scroll the diagram horizontally on smaller screens. The text below explains the same boundaries.
 
@@ -52,12 +54,15 @@ flowchart TB
 
 </div>
 
-Before sending a sealed payload, the caller must obtain and appraise the callee's channel offer. That outbound step and the callee's appraisal of the caller are distinct directions. The runtime box is a process boundary in software mode; verified confidential-computing deployments can add hardware isolation. The surrounding agents and their tools do not automatically move inside it.
+Before sending an encrypted task, the caller first fetches and checks the callee's key offer. That check (the caller checking the callee) is separate from the callee checking the caller. In software mode the runtime box in the diagram is just a separate process; on verified confidential-computing hardware it can also be hardware-isolated. The agents and tools around it do not move inside it automatically.
+
+What the caller may actually do is the overlap of what it was delegated and what the callee's own rules allow. A delegation cannot grant something the callee's rules refuse.
 
-The effective authority is the intersection of the delegated scope and local policy. Delegation cannot grant a capability that local policy refuses. Invalid chains or holder proofs are rejected before policy decisions and do not receive signed denial records; authenticated policy and appraisal denials have their own evidence behavior. See the [peer implementation](https://github.com/agentrust-io/ca2a/blob/main/src/ca2a_runtime/peer.py) for the exact ordering and failure paths.
+??? info "Technical detail: denial records and ordering"
+    Invalid chains or holder proofs are rejected before policy decisions and do not receive signed denial records; authenticated policy and appraisal denials have their own evidence behavior. See the [peer implementation](https://github.com/agentrust-io/ca2a/blob/main/src/ca2a_runtime/peer.py) for the exact ordering and failure paths.
 
 ## Profile, not protocol
 
-The profile defines trust fields and checks. The reference HTTP transport makes the peer path runnable, and an A2A SDK bridge is also available. Transport choice does not establish hardware assurance or replace the relying party's trust policy.
+cA2A is a profile: a set of extra fields and checks added to A2A messages. It does not replace A2A's way of sending messages. A small reference web server ships so you can run the whole path, and a bridge to the official A2A software development kit is also available. Which transport you use does not add hardware assurance or replace the relying party's own trust rules.
 
 Continue with [configuration](configuration.md), the [profile](spec/profile.md), or the [limitations](../LIMITATIONS.md).