diff --git a/README.md b/README.md
index aebe93a..11ec3b4 100644
--- a/README.md
+++ b/README.md
@@ -6,6 +6,24 @@ It provides a small, explicit core and framework-specific adapters that make it
 
 This repository contains the core building blocks and official server-side framework integrations.
 
+## 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 repo is the backend layer: the core and framework adapters your server mounts at `/auth` to carry browser cookies and native bearer tokens to the auth API.
+
+```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
+  style backend stroke-width:3px
+```
+
+[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.
+
 ---
 
 ## Philosophy
diff --git a/packages/core/README.md b/packages/core/README.md
index fbb4d80..65635b5 100644
--- a/packages/core/README.md
+++ b/packages/core/README.md
@@ -16,6 +16,10 @@ It is designed to be:
 
 If you are building a custom adapter (Express, Fastify, Next.js, Hono, etc.), this is the package you integrate with.
 
+## 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. The [compatibility matrix](https://docs.seamlessauth.com/build/ecosystem/#compatibility-matrix) lists which package versions work together.
+
 ---
 
 ## What This Package Is
diff --git a/packages/express/README.md b/packages/express/README.md
index 3da4433..6f41207 100644
--- a/packages/express/README.md
+++ b/packages/express/README.md
@@ -26,6 +26,10 @@ Pair this with:
 - **React SDK:** https://github.com/fells-code/seamless-auth-react
 - **Starter app:** https://github.com/fells-code/seamless-cli
 
+## 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. The [compatibility matrix](https://docs.seamlessauth.com/build/ecosystem/#compatibility-matrix) lists which package versions work together.
+
 ---
 
 ## Installation
diff --git a/packages/fastify/README.md b/packages/fastify/README.md
index 61c96ba..108852b 100644
--- a/packages/fastify/README.md
+++ b/packages/fastify/README.md
@@ -8,6 +8,10 @@ cookies they depend on, so the browser talks to your origin and never holds a
 token itself. The decisions all live in `@seamless-auth/core`; this package binds
 them to Fastify.
 
+## 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. The [compatibility matrix](https://docs.seamlessauth.com/build/ecosystem/#compatibility-matrix) lists which package versions work together.
+
 ## Install
 
 ```sh
diff --git a/packages/nextjs/README.md b/packages/nextjs/README.md
index 634d653..8ee496e 100644
--- a/packages/nextjs/README.md
+++ b/packages/nextjs/README.md
@@ -10,6 +10,10 @@ in server components and `proxy.ts`. The decisions all live in
 `@seamless-auth/core`; this package binds them to web-standard `Request` and
 `Response`.
 
+## 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. The [compatibility matrix](https://docs.seamlessauth.com/build/ecosystem/#compatibility-matrix) lists which package versions work together.
+
 ## Install
 
 ```sh