From 627ba493aae720f3a9f0d77de690f918577e01d9 Mon Sep 17 00:00:00 2001 From: Imran Siddique Date: Thu, 20 Aug 2026 17:51:28 -0700 Subject: [PATCH] docs: give the site its own landing page instead of rendering the README trace.agentrust-io.com was the GitHub README verbatim: a centered icon, a five-line H1, six shields in colours the editorial palette does not use, and a "Full Documentation" badge linking to the page the reader is already on. About a screen and a half of chrome before the first sentence of content. - Adds index.md as the site landing page, in the shape Agent Manifest already uses: title, lead paragraph, the promise, a TL;DR, the claim table, a four-card "where to start", and status and governance. README.md stays the GitHub landing page and is excluded from the build so the project does not have two homepages. - Removes the htmltitle override in overrides/main.html, which only existed because README.md could not carry front matter, and lets the OG and Twitter titles use the real page title on the homepage too. Fixes found while doing it: - CODE_OF_CONDUCT.md, MAINTAINERS.md and CHARTER.md were linked from GOVERNANCE.md and ROADMAP.md but excluded from the build, so all three 404'd on the live site. Now published and in the nav. - docs/conformance-method.md was written but unreachable: not in the nav and not linked from anywhere. Now under Method. - The Spec badge said v0.1 while linking to, and describing, v0.2. - "Launching at Confidential Computing Summit, June 23 2026" read as a future event two months after the fact. - A crosswalk link to tests/test_acta_fixtures.py 404'd, because tests/ is not part of the published site. Points at GitHub now. The docs build goes from nine link warnings to zero. Co-Authored-By: Claude Opus 5 (1M context) Claude-Session: https://claude.ai/code/session_013EQx4N5BzTQbY8kvXUsdkY --- .github/workflows/docs.yml | 2 +- README.md | 4 +- docs/crosswalks/acta-decision-receipts.md | 2 +- index.md | 93 +++++++++++++++++++++++ mkdocs.yml | 13 ++-- overrides/main.html | 16 +--- 6 files changed, 106 insertions(+), 24 deletions(-) create mode 100644 index.md diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index ca03c14..12998ad 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -67,7 +67,7 @@ jobs: # host. exclude_docs drops the three that are served from the apex. if [ -d schema ]; then cp -r schema $BUILD/schema; fi - for fname in README.md CHANGELOG.md CONTRIBUTING.md GOVERNANCE.md ROADMAP.md LIMITATIONS.md PRIVACY.md CNAME robots.txt; do + for fname in index.md CHANGELOG.md CONTRIBUTING.md GOVERNANCE.md CHARTER.md CODE_OF_CONDUCT.md MAINTAINERS.md ROADMAP.md LIMITATIONS.md PRIVACY.md CNAME robots.txt; do if [ -f "$fname" ]; then cp "$fname" "$BUILD/$fname"; fi done diff --git a/README.md b/README.md index 7fb82d4..6adb783 100644 --- a/README.md +++ b/README.md @@ -20,7 +20,7 @@ [![Specification: Community Specification License 1.0](https://img.shields.io/badge/Specification-Community_Specification_License_1.0-blue.svg)](Governance/COMMUNITY-SPECIFICATION-LICENSE.md) [![Code: Apache 2.0](https://img.shields.io/badge/Code-Apache_2.0-lightgrey.svg)](LICENSE) -[![Spec](https://img.shields.io/badge/Spec-v0.1-0ea5e9)](spec/trace-v0.2.md) +[![Spec](https://img.shields.io/badge/Spec-v0.2-0ea5e9)](spec/trace-v0.2.md) [![PyPI](https://img.shields.io/pypi/v/agentrust-trace)](https://pypi.org/project/agentrust-trace/) [![CI](https://github.com/agentrust-io/trace-spec/actions/workflows/ci.yml/badge.svg)](https://github.com/agentrust-io/trace-spec/actions/workflows/ci.yml) [![Discord](https://img.shields.io/badge/Discord-Join-5865F2?logo=discord&logoColor=white&style=flat)](https://discord.gg/grgzFEHgkj) @@ -29,7 +29,7 @@ TRACE Specification is an LF Project, hosted at the Linux Foundation as its own series, "TRACE Specification, a Series of LF Projects, LLC".

-> **Developer Preview.** Launching at Confidential Computing Summit, June 23 2026. +> **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 hardware-attested AI agent governance records. TRACE defines the format, anchoring protocol, and verification rules for cryptographically provable evidence that an AI agent ran under a specific policy, in a verified hardware environment, on classified data, invoking identified tools, all bound into a single signed artifact rooted in silicon attestation. diff --git a/docs/crosswalks/acta-decision-receipts.md b/docs/crosswalks/acta-decision-receipts.md index 3d4f9f5..8f280c0 100644 --- a/docs/crosswalks/acta-decision-receipts.md +++ b/docs/crosswalks/acta-decision-receipts.md @@ -98,7 +98,7 @@ An Acta decision receipt proves that a specific policy decision, over a specific ## Conformance fixtures -Six real fixtures in [`examples/action-receipts/acta/`](../../examples/action-receipts/acta/), generated by an actual Ed25519 signer (generator committed alongside), covering the negative cases raised in [trace-spec#97](https://github.com/agentrust-io/trace-spec/issues/97) and [trace-spec#95](https://github.com/agentrust-io/trace-spec/issues/95): valid accepted, valid denied (negative controller-equivalent outcome), signature/key mismatch (mismatched key committed), broken chain (validly signed, wrong predecessor hash), stale policy digest, and mismatched session binding. Expected outcomes are machine-readable in `expected.json`, and [`tests/test_acta_fixtures.py`](../../tests/test_acta_fixtures.py) re-verifies every fixture in CI against the draft-02 envelope and the declared positive/negative results, using this repository's existing `rfc8785` and `cryptography` dependencies, so fixture or envelope drift fails the build. +Six real fixtures in [`examples/action-receipts/acta/`](../../examples/action-receipts/acta/), generated by an actual Ed25519 signer (generator committed alongside), covering the negative cases raised in [trace-spec#97](https://github.com/agentrust-io/trace-spec/issues/97) and [trace-spec#95](https://github.com/agentrust-io/trace-spec/issues/95): valid accepted, valid denied (negative controller-equivalent outcome), signature/key mismatch (mismatched key committed), broken chain (validly signed, wrong predecessor hash), stale policy digest, and mismatched session binding. Expected outcomes are machine-readable in `expected.json`, and [`tests/test_acta_fixtures.py`](https://github.com/agentrust-io/trace-spec/blob/main/tests/test_acta_fixtures.py) re-verifies every fixture in CI against the draft-02 envelope and the declared positive/negative results, using this repository's existing `rfc8785` and `cryptography` dependencies, so fixture or envelope drift fails the build. ## References diff --git a/index.md b/index.md new file mode 100644 index 0000000..2a90ae6 --- /dev/null +++ b/index.md @@ -0,0 +1,93 @@ +--- +title: Hardware-attested receipts for AI agent actions +description: TRACE is an open specification for hardware-attested AI agent governance records. A Trust Record states what ran, where, under which policy, touching which data, calling which tools, in a form any third party can verify without trusting the operator. +--- + +# 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, all bound into a single signed artifact rooted in silicon attestation. + +**A Trust Record answers what ran, where, under which policy, touching which data, and calling which tools, in a form any third party can verify without trusting the operator.** + +!!! tip "TL;DR" + - An audit log is written by the system being audited. A Trust Record is signed inside a TEE and checked against a hardware root, so the operator cannot author it after the fact. + - The current specification is **v0.2**, with a [conformance test suite](https://tests.agentrust-io.com) that scores a record by level. + - Install with `pip install agentrust-trace` and sign your first record in a few minutes. + - TRACE Specification is hosted at the Linux Foundation as its own series, [TRACE Specification, a Series of LF Projects, LLC](https://www.linuxfoundation.org/). + +```bash +pip install agentrust-trace +``` + +```python +from agentrust_trace import TrustRecord, sign_record + +record = TrustRecord( + subject="spiffe://trust.example.org/agent/payments-processor", + model_id="claude-sonnet-4-6", + platform="amd-sev-snp", + policy_hash="sha256:b2c3d4...", +) +signed = sign_record(record, key=signing_key) +``` + +## What a Trust Record proves + +Each question maps to a claim a third party can check without asking you. + +| Question | TRACE claim | +|---|---| +| What model ran? | `model.model_id` + `model.weights_digest` | +| Where did it run? | `runtime.platform` + `runtime.measurement` | +| Under which policy? | `policy.bundle_hash` + `policy.enforcement_mode` | +| What data did it touch? | `data_class` | +| Which tools were called? | `tool_transcript.hash` + `tool_transcript.call_count` | +| Is the record independently anchored? | `anchoring.receipt_uri` (SCITT) | + +## Where to start + +
+ +- __Run it__ + + --- + + Sign a record, verify it, and see what a failed check looks like. + + [Quickstart](docs/quickstart.md) + +- __Read it__ + + --- + + The normative specification, with the claim set, the anchoring protocol, and the verification rules. + + [TRACE v0.2](spec/trace-v0.2.md) + +- __Test it__ + + --- + + Score an implementation against the spec by conformance level before claiming compliance. + + [Conformance suite](https://tests.agentrust-io.com) + +- __Integrate it__ + + --- + + Emit and consume Trust Records from AGT, cMCP, and sandboxed agent runtimes. + + [Integration guides](docs/integration/agt.md) + +
+ +## What it is built on + +TRACE profiles existing IETF and IRTF work rather than replacing it: [RFC 9711 (EAT)](https://www.rfc-editor.org/rfc/rfc9711) for the claim envelope, [RFC 9334 (RATS)](https://www.rfc-editor.org/rfc/rfc9334) for the attester, verifier, and relying-party roles, and the SCITT draft for transparency-ledger anchoring. A related standardization track runs in [CoSAI WS4](https://github.com/oasis-open-projects/coalition-for-secure-ai). + +## Status and governance + +The specification is a **Developer Preview**. v0.2 is current and published with a conformance test suite. Read [Limitations](LIMITATIONS.md) for the scope boundaries before relying on it in production. + +TRACE Specification is an [LF Project](https://www.linuxfoundation.org/), hosted at the Linux Foundation as its own series, "TRACE Specification, a Series of LF Projects, LLC", under [LF Projects policies](https://lfprojects.org/policies/). See [Governance](GOVERNANCE.md) for how decisions are made and [Contributing](CONTRIBUTING.md) for how to propose a change. diff --git a/mkdocs.yml b/mkdocs.yml index 3d393bb..902e1f0 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -21,12 +21,10 @@ exclude_docs: | schema/trace-revocation-bundle.json LICENSE NOTICE + README.md ANTITRUST.md ADOPTERS.md - MAINTAINERS.md SECURITY.md - CHARTER.md - CODE_OF_CONDUCT.md pyproject.toml theme: @@ -88,7 +86,7 @@ plugins: conformance suite. sections: Getting started: - - README.md + - index.md - docs/quickstart.md - docs/trust-levels.md - docs/verification.md @@ -184,7 +182,7 @@ extra_css: - https://agentrust-io.com/design-system.css nav: - - Home: README.md + - Home: index.md - Getting Started: - Quickstart: docs/quickstart.md - Trust Levels: docs/trust-levels.md @@ -221,6 +219,8 @@ nav: - OWASP Agentic Top 10: docs/crosswalks/owasp-agentic-top-10.md - Acta Decision Receipts: docs/crosswalks/acta-decision-receipts.md - Test Suite: https://tests.agentrust-io.com + - Method: + - How the conformance vectors are built: docs/conformance-method.md - RFCs: - Composable zero-knowledge proofs: docs/rfcs/composable-zk-assurance.md - Project: @@ -228,6 +228,9 @@ nav: - Changelog: CHANGELOG.md - Contributing: CONTRIBUTING.md - Governance: GOVERNANCE.md + - Technical Charter: CHARTER.md + - Code of Conduct: CODE_OF_CONDUCT.md + - Maintainers: MAINTAINERS.md - Roadmap: ROADMAP.md - Privacy: PRIVACY.md - Scope: Governance/Scope.md diff --git a/overrides/main.html b/overrides/main.html index fc0d908..7cd12af 100644 --- a/overrides/main.html +++ b/overrides/main.html @@ -9,24 +9,10 @@ is not repeated here. #} -{# - The homepage is built from README.md, which mkdocs treats as the site index. - Material falls back to site_name when a page has no front-matter title, so the - homepage was titled with the bare string "TRACE". Front matter is not an option - here: README.md is also the GitHub landing page and YAML would render as noise - there. Inner pages keep their own titles through super(). -#} -{% block htmltitle %} - {% if page and page.is_homepage %} - Hardware-attested receipts for AI agent actions - {{ config.site_name }} - {% else %} - {{ super() }} - {% endif %} -{% endblock %} {% block extrahead %} {{ super() }} - {% set page_title = page.title ~ " - " ~ config.site_name if page and page.title and not page.is_homepage else config.site_name %} + {% set page_title = page.title ~ " - " ~ config.site_name if page and page.title else config.site_name %} {% set page_desc = page.meta.description if page and page.meta and page.meta.description else config.site_description %} {% set page_url = page.canonical_url if page and page.canonical_url else config.site_url %}