docs: establish platform reference profile registry

README.md

@@ -375,9 +375,18 @@ If you're implementing a new language port, **start from the fixtures, not the s
 
 ## Where to go next
 
+[`references/`](references/README.md) is the open-source home for executable
+integrations with agent frameworks, transports, and runtimes. These profiles
+prove interoperability and document the receiver-side trust boundary. They do
+not replace **Ratify Verify**, the managed commercial surface for production
+trust configuration, revocation, policy, audit, observability, availability,
+and supported deployment adapters. Both use the same portable protocol and
+verification semantics—there is no managed-only wire format.
+
 | You want to… | Go to |
 |---|---|
 | **Run the demo and see the protocol work** | [`demos/README.md`](demos/README.md) |
+| **See integrations with specific agent platforms** | [`references/README.md`](references/README.md) |
 | **See the measured performance numbers** | [`docs/BENCHMARKS.md`](docs/BENCHMARKS.md) |
 | **Understand the threat model** | [`docs/EXPLAINED.md`](docs/EXPLAINED.md) |
 | **Read the normative spec** | [`SPEC.md`](SPEC.md) |
@@ -441,6 +450,8 @@ ratify-protocol/
 │
 ├── demos/                 End-to-end narrative demos: go/ python/ typescript/ rust/
 │
+├── references/            Platform-specific profiles, threat models, and executable gates
+│
 └── docs/
     ├── EXPLAINED.md           Architecture + threat model + real-time patterns
     ├── AGENT_TO_AGENT.md      A2A patterns (mutual auth, sub-delegation, receipts)

docs/EXPLAINED.md

@@ -112,11 +112,19 @@ a runtime dependency.
 
 A bundle moves freely across all five SDKs. Where verifiers differ is in operational surface — latency, compliance posture, integration ergonomics — not in cryptography.
 
-### Surface adapters (out of scope for this repository)
-
-The integration code that turns a `ProofBundle` into a "Zoom auth gate," "Twilio SIP attestation," "AWS API Gateway authorizer," etc. — the **surface adapters** — lives in separate repositories (`ratify/zoom-sdk`, `ratify/voice-sdk`, …). Those are the home of proprietary "last-mile" integration code and are not addressed by this specification.
-
-The protocol's contract stops at the `ProofBundle` wire format and the verifier algorithm. Anything above that — how a third-party platform's signaling layer is intercepted, how middleware is wired into a specific framework, how an incumbent product's auth model is mapped onto Ratify scopes — is integration work, not protocol work. Ratify Verify ships those adapters as commercial product; the specification does not prevent a third party from writing their own.
+### Open references and managed surface adapters
+
+Open, executable profiles under [`references/`](../references/README.md) show how
+Ratify composes with specific agent frameworks, transports, and runtimes. They
+are interoperability references: inspectable patterns, deterministic gates,
+and evidence—not hosted services or production support commitments.
+
+The protocol contract stops at the `ProofBundle` wire format and verifier
+semantics. Production last-mile adapters—such as supported Zoom, Twilio, or API
+gateway deployments—plus managed trust configuration, revocation, policy,
+audit, observability, and availability belong to Ratify Verify's commercial
+surface. Ratify Verify does not introduce a proprietary proof format, and the
+specification does not prevent anyone from building or operating an adapter.
 
 ---
 

references/README.md

@@ -0,0 +1,42 @@
+# Ratify reference profiles
+
+Reference profiles show how Ratify composes with a specific agent framework,
+transport, runtime, or platform without changing the Ratify verifier contract.
+They are larger and more platform-specific than the small examples in
+[`demos/`](../demos/README.md).
+
+These are open-source interoperability references, not hosted services or
+production support commitments. They make the integration pattern inspectable,
+portable, and reproducible. **Ratify Verify** is the separate managed commercial
+surface for operating the same protocol at scale: managed trust configuration,
+revocation, policy, audit retention, observability, availability, and supported
+deployment adapters. The proof bytes and verifier semantics remain portable;
+customers choose whether to operate them themselves or use the managed service.
+
+Every accepted profile should contain:
+
+- an explicit trust boundary and layer-separation statement;
+- exact tested dependency versions;
+- a deterministic path that does not depend on model judgment;
+- adversarial allow/deny cases with protected-handler invocation evidence;
+- a one-command published-package gate;
+- limitations and non-goals;
+- evidence generated from executed tests, not projected results; and
+- a disclosure of endorsement, partnership, and standardization status.
+
+## Registry
+
+| Profile | Status | Ratify version | Platform version | Gate |
+|---|---|---|---|---|
+
+## Lifecycle
+
+Profiles begin as independent drafts on feature branches. Passing tests do not
+make a profile official for the named platform. The registry entry must state
+whether a platform reviewed, contributed to, or endorsed the work.
+
+A profile remains in this repository while Ratify owns its maintenance and it
+shares the protocol release cadence. It may move to a dedicated or jointly
+maintained repository when it needs independent releases, external maintainers,
+or partner-owned governance. A move should leave a compatibility pointer at the
+old path so public evidence links do not silently break.