diff --git a/README.md b/README.md
index 787c8b7..d3510bd 100644
--- a/README.md
+++ b/README.md
@@ -19,6 +19,23 @@ contracts built on top of them. Every layer of the stack validates against the s
 Because everything downstream imports these contracts, a change here is treated as
 breaking by default. See [Versioning and stability](#versioning-and-stability).
 
+## Start here
+
+New to Seamless Auth? The [self-hosted quickstart](https://docs.seamlessauth.com/start/quickstart/) runs the full stack locally with Docker. If Seamless hosts your auth instance, follow the [managed quickstart](https://docs.seamlessauth.com/start/managed-quickstart/) instead.
+
+This package is not a node in the diagram below because it sits under all of them: `seamless-auth-api`, the server adapters (through `@seamless-auth/core`), the React and React Native SDKs, the admin dashboard, and the CLI all validate against these schemas.
+
+```mermaid
+flowchart LR
+  browser["Browser<br/>@seamless-auth/react"] -- "signed httpOnly cookies" --> backend
+  native["Native app<br/>@seamless-auth/react-native"] -- "bearer tokens" --> backend
+  backend["Your backend<br/>@seamless-auth/express, fastify, or nextjs<br/>mounted at /auth"] -- "bearer token + service token" --> api
+  api["seamless-auth-api<br/>owns the session"] --> db[("Postgres")]
+  backend -. "verifies tokens with JWKS" .-> api
+```
+
+[How the pieces connect](https://docs.seamlessauth.com/start/overview/#how-the-pieces-connect) explains each hop. [Compatibility matrix](https://docs.seamlessauth.com/build/ecosystem/#compatibility-matrix) lists which package versions work together.
+
 ## Requirements
 
 |                      |                           |