diff --git a/web/scripts/verify-dist.mjs b/web/scripts/verify-dist.mjs
index a2de9c3..14cb326 100644
--- a/web/scripts/verify-dist.mjs
+++ b/web/scripts/verify-dist.mjs
@@ -145,6 +145,29 @@ if (!existsSync(join(dist, "privacy/index.html"))) {
   problems.push("privacy/index.html missing — the store listing links it");
 }
 
+// The architecture diagram is inlined SVG under the same CSP as everything
+// else: `script-src` has no 'unsafe-inline' and `style-src` is bare 'self',
+// which covers inline SVG in the document. A regenerated diagram that brought
+// Mermaid's own <style> or a style attribute back would render as black boxes
+// in production and pass every local check, since nothing serves the CSP in
+// dev. Check the shipped bytes rather than trusting the render script.
+const architecture = join(dist, "architecture/index.html");
+if (!existsSync(architecture)) {
+  problems.push("architecture/index.html missing — the privacy policy links it");
+} else {
+  const page = readFileSync(architecture, "utf8");
+  if (!page.includes("<svg")) {
+    problems.push("architecture/index.html has no inline SVG — the diagram did not render");
+  }
+  if (/<style[\s>]/i.test(page)) {
+    problems.push("architecture/index.html has a <style> element, which style-src 'self' would drop");
+  }
+  // `font-style="normal"` is all over Mermaid's text, hence the boundary.
+  if (/(^|[\s"'])style\s*=/i.test(page)) {
+    problems.push("architecture/index.html has a style attribute, which style-src 'self' would drop");
+  }
+}
+
 if (problems.length > 0) {
   console.error(`verify-dist: FAILED (${problems.length} problem(s)):`);
   for (const p of problems) console.error(`  - ${p}`);
diff --git a/web/src/pages/architecture.astro b/web/src/pages/architecture.astro
new file mode 100644
index 0000000..00b8b03
--- /dev/null
+++ b/web/src/pages/architecture.astro
@@ -0,0 +1,263 @@
+---
+import Layout from "../layouts/Layout.astro";
+
+// The diagram is inlined rather than loaded, for the same reason the wordmark
+// is on the homepage: as one element in the document it takes the page's theme
+// tokens (see `.diagram` in global.css) instead of baking in one palette.
+//
+// It is inlined *pre-rendered*, because substandard.blog is served behind a
+// strict CSP with no `unsafe-inline` and no `unsafe-eval`: a client-side
+// Mermaid would need a script the CSP blocks. `npm --prefix web run diagram`
+// renders web/src/diagrams/architecture.mmd in headless Chrome and strips the
+// CSS the CSP would drop; nothing here ships a script.
+import diagram from "../diagrams/architecture.svg?raw";
+
+const REPO = "https://tangled.org/permadeath.com/substandard";
+const src = (path: string) => `${REPO}/blob/main/${path}`;
+
+// Who calls whom. Every row is a request the extension makes itself; links a
+// person clicks (a reader, a Bluesky profile) are left out, since they are
+// ordinary navigations and not the extension talking.
+const calls = [
+  {
+    from: "background worker",
+    to: "the site you are viewing",
+    what: "GET /.well-known/site.standard.publication",
+    why: "detect a publication, and check that its record points back at the site",
+  },
+  {
+    from: "background worker",
+    to: "plc.directory, public.api.bsky.app",
+    what: "DID documents, identity.resolveHandle",
+    why: "turn a DID into a PDS host, and a handle into a DID",
+  },
+  {
+    from: "background worker",
+    to: "the publication's PDS",
+    what: "repo.getRecord",
+    why: "the publication and document records the page's link tags name",
+  },
+  {
+    from: "background worker",
+    to: "your PDS",
+    what: "repo.listRecords",
+    why: "your own subscriptions, blocks and follows, to know what to show",
+  },
+  {
+    from: "popup",
+    to: "the owner's PDS",
+    what: "repo.getRecord, sync.getBlob",
+    why: "the owner's profile, and avatar or publication icon images",
+  },
+  {
+    from: "popup",
+    to: "constellation.microcosm.blue",
+    what: "GET /links/distinct-dids",
+    why: "who else has a subscription record pointing at this publication",
+  },
+  {
+    from: "popup",
+    to: "the labelers your account subscribes to",
+    what: "label.queryLabels",
+    why: "moderation labels on the publication and its owner",
+  },
+  {
+    from: "popup",
+    to: "your PDS",
+    what: "repo.createRecord, repo.deleteRecord",
+    why: "subscribe and unsubscribe; post feedback if you use the feedback form",
+  },
+  {
+    from: "offscreen document",
+    to: "your PDS and its authorization server",
+    what: "OAuth: authorization request, token, revoke",
+    why: "sign in, refresh, and sign out",
+  },
+];
+
+// Where anything that outlives a single request is kept. All of it is local;
+// there is no substandard-operated server for it to be kept on.
+const storage = [
+  {
+    where: "chrome.storage.session",
+    what: "per-tab detection state, well-known probe results, short-lived lookups",
+    life: "cleared when the browser closes",
+  },
+  {
+    where: "chrome.storage.local",
+    what: "your follow list, your chosen reader, and a non-secret session mirror (DID, handle, avatar URL)",
+    life: "until you clear it or uninstall",
+  },
+  {
+    where: "extension-origin IndexedDB and localStorage",
+    what: "OAuth tokens, DPoP keys and PKCE state, written by the OAuth client",
+    life: "until sign-out or uninstall",
+  },
+];
+---
+
+<Layout
+  title="substandard architecture"
+  description="The substandard extension's components, and which network calls each one makes."
+>
+  <header class="hero">
+    <h1>architecture</h1>
+  </header>
+
+  <main class="wide">
+    <section>
+      <h2>The moving parts</h2>
+      <p>
+        The extension runs as four separate contexts in your browser, and talks
+        to AT Protocol services directly. There is no substandard server in any
+        of these paths. Everything below is in the
+        <a href={REPO}>source repository</a>.
+      </p>
+      <figure class="diagram" set:html={diagram} />
+    </section>
+
+    <section>
+      <h2>The four contexts</h2>
+      <ul>
+        <li>
+          <strong>Content script</strong> (<a href={src("src/content.ts")}
+            ><code>src/content.ts</code></a
+          >) — runs in the page, reads its
+          <code>site.standard.publication</code> and
+          <code>site.standard.document</code> link tags, and reports those two
+          <code>at://</code> URIs to the worker. It reads nothing else from the page
+          and makes no network requests of its own.
+        </li>
+        <li>
+          <strong>Background service worker</strong> (<a
+            href={src("src/background.ts")}><code>src/background.ts</code></a
+          >) — keeps detection state per tab, sets the toolbar badge, and makes
+          the public reads: the well-known probe, identity resolution, and
+          unauthenticated record fetches.
+        </li>
+        <li>
+          <strong>Popup</strong> (<a href={src("src/popup")}
+            ><code>src/popup/</code></a
+          >) — the UI and its cards. It gathers the context around a
+          publication, and it is where writes to your PDS happen, using the
+          restored session.
+        </li>
+        <li>
+          <strong>Offscreen document</strong> (<a href={src("src/offscreen")}
+            ><code>src/offscreen/</code></a
+          >) — an invisible page that exists only to host the OAuth client,
+          which needs <code>window</code> and DOM storage that a service worker
+          does not have.
+        </li>
+      </ul>
+    </section>
+
+    <section>
+      <h2>What crosses the network</h2>
+      <p>
+        Public reads carry no cookies and no credentials
+        (<a href={src("src/lib/http.ts")}><code>src/lib/http.ts</code></a> sets
+        <code>credentials: "omit"</code>), and their answers are cached in your
+        browser. Only the last two rows are authenticated, and both go to your
+        own PDS. XRPC calls are named without their
+        <code>com.atproto.</code> prefix.
+      </p>
+      <div class="table-scroll">
+        <table>
+          <thead>
+            <tr>
+              <th>From</th>
+              <th>To</th>
+              <th>Call</th>
+              <th>For</th>
+            </tr>
+          </thead>
+          <tbody>
+            {
+              calls.map((call) => (
+                <tr>
+                  <td>{call.from}</td>
+                  <td>{call.to}</td>
+                  <td>
+                    <code>{call.what}</code>
+                  </td>
+                  <td>{call.why}</td>
+                </tr>
+              ))
+            }
+          </tbody>
+        </table>
+      </div>
+    </section>
+
+    <section>
+      <h2>What is written, and what is only read</h2>
+      <p>
+        The OAuth scope the extension asks for is listed in full in its
+        <a href="/client-metadata.json">client metadata</a>. It permits exactly
+        two kinds of write:
+      </p>
+      <ul>
+        <li>
+          <code>site.standard.graph.subscription</code> — created when you
+          subscribe, deleted when you unsubscribe, in your own repository.
+        </li>
+        <li>
+          <code>app.userinput.discussion</code> — created only when you submit
+          the feedback form.
+        </li>
+      </ul>
+      <p>
+        Everything else is read-only, including your follows, your blocks, your
+        profile and your labeler preferences. Nothing follows, blocks or posts
+        on your behalf: sharing to Bluesky opens a compose link rather than
+        writing a post.
+      </p>
+    </section>
+
+    <section>
+      <h2>What is stored, and where</h2>
+      <div class="table-scroll">
+        <table>
+          <thead>
+            <tr>
+              <th>Where</th>
+              <th>What</th>
+              <th>How long</th>
+            </tr>
+          </thead>
+          <tbody>
+            {
+              storage.map((row) => (
+                <tr>
+                  <td>
+                    <code>{row.where}</code>
+                  </td>
+                  <td>{row.what}</td>
+                  <td>{row.life}</td>
+                </tr>
+              ))
+            }
+          </tbody>
+        </table>
+      </div>
+      <p>
+        Tokens are never put in <code>chrome.storage</code>; the OAuth client
+        keeps them in the extension origin's own storage. Uninstalling the
+        extension removes all of it.
+      </p>
+    </section>
+
+    <section>
+      <h2>Why the extension asks for every site</h2>
+      <p>
+        Detection needs the well-known probe, and there is no list of which
+        sites publish on <a href="https://standard.site">standard.site</a>, so
+        the probe has to be able to run wherever you are. That is what the
+        host permissions in the manifest are for. The
+        <a href="/privacy">privacy policy</a> covers what that means for your data;
+        this page is its diagram.
+      </p>
+    </section>
+  </main>
+</Layout>
diff --git a/web/src/pages/index.astro b/web/src/pages/index.astro
index 4fda911..58fce30 100644
--- a/web/src/pages/index.astro
+++ b/web/src/pages/index.astro
@@ -167,6 +167,8 @@ const day = new Intl.DateTimeFormat("en", {
       <a href="https://tangled.org/permadeath.com/substandard/blob/main/LICENSE"
         >MIT licensed</a
       >
+      &middot;
+      <a href="/architecture">architecture</a>
     </p>
     <p>
       This site uses cookieless analytics
diff --git a/web/src/pages/privacy.astro b/web/src/pages/privacy.astro
index 9e64e6c..131f684 100644
--- a/web/src/pages/privacy.astro
+++ b/web/src/pages/privacy.astro
@@ -65,6 +65,11 @@ import Layout from "../layouts/Layout.astro";
         preference, your session — stays in your browser's local extension
         storage. Uninstalling the extension removes it.
       </p>
+      <p>
+        The <a href="/architecture">architecture page</a> is the diagram of all
+        of the above: which part of the extension makes each of those requests,
+        what it sends, and where each answer is kept.
+      </p>
     </section>
 
     <section>
diff --git a/web/src/styles/global.css b/web/src/styles/global.css
index 6d0da45..096bbfb 100644
--- a/web/src/styles/global.css
+++ b/web/src/styles/global.css
@@ -364,6 +364,134 @@ main li::marker {
   color: var(--muted);
 }
 
+/* The architecture diagram (/architecture). Mermaid's own stylesheet is
+   stripped at render time — `style-src 'self'` covers inline SVG, so a
+   <style> inside the figure would be dropped in production and the diagram
+   would render as black boxes on black lines. Everything it would have said
+   is restated here instead, which is also how the picture picks up the
+   theme's tokens rather than baking one palette into the file.
+
+   The geometry was measured at 16px system-ui, so that size is pinned rather
+   than inherited: a different one would spill the labels out of their boxes.
+   Below the diagram's natural width the figure scrolls instead of scaling,
+   because a 900px picture squeezed into a phone is unreadable long before it
+   stops fitting. */
+/* /architecture is the one page whose content is a picture and two reference
+   tables rather than paragraphs. At the 44rem the prose pages use, the
+   diagram needs a scrollbar on every desktop and the tables crush their
+   columns to one character; the column is widened for that page alone. */
+main.wide {
+  max-width: 62rem;
+}
+
+.diagram {
+  margin: 1.25rem 0 0;
+  overflow-x: auto;
+}
+
+.diagram svg {
+  display: block;
+  width: 100%;
+  min-width: 40rem;
+  height: auto;
+  font-family: system-ui, -apple-system, "Segoe UI", sans-serif;
+  font-size: 16px;
+}
+
+.diagram text {
+  fill: var(--fg);
+}
+
+/* Mermaid lays a node's label out from the node's centre and leaves the
+   centring to its stylesheet, so without this the labels run out of the
+   right-hand side of their boxes. Cluster labels are pre-offset and stay
+   left-anchored. */
+.diagram .node .label text {
+  text-anchor: middle;
+}
+
+/* Boxes inside the browser are solid cards; the services outside it are
+   dashed and unfilled, so the trust boundary reads without a legend. */
+.diagram .node rect {
+  fill: var(--card);
+  stroke: var(--fg);
+  stroke-width: 1.5px;
+  rx: 6;
+  ry: 6;
+}
+
+.diagram .node.outsideNode rect {
+  fill: var(--bg);
+  stroke: var(--muted);
+  stroke-dasharray: 5 4;
+}
+
+.diagram .cluster rect {
+  fill: none;
+  stroke: var(--line);
+  stroke-width: 2px;
+  rx: 10;
+  ry: 10;
+}
+
+.diagram .cluster-label text {
+  fill: var(--muted);
+}
+
+.diagram .flowchart-link {
+  fill: none;
+  stroke: var(--muted);
+  stroke-width: 1.5px;
+}
+
+.diagram .arrowMarkerPath {
+  fill: var(--muted);
+  stroke: none;
+}
+
+/* The label's backing plate knocks the edge out from under the text. */
+.diagram .edgeLabel .background {
+  fill: var(--bg);
+}
+
+.diagram .edgeLabel text {
+  fill: var(--muted);
+}
+
+/* Reference tables: what talks to what, and what is kept where. Narrow
+   screens scroll the table rather than crushing the columns. */
+.table-scroll {
+  overflow-x: auto;
+  margin: 1rem 0 0;
+}
+
+.table-scroll table {
+  border-collapse: collapse;
+  width: 100%;
+  min-width: 40rem;
+  font-size: 0.9rem;
+}
+
+.table-scroll th,
+.table-scroll td {
+  border-bottom: 1px solid var(--line);
+  padding: 0.45rem 0.6rem;
+  text-align: left;
+  vertical-align: top;
+  color: var(--muted);
+}
+
+.table-scroll th {
+  color: var(--fg);
+  font-weight: 650;
+}
+
+/* Identifiers carry the weight on /architecture: NSIDs, hostnames, paths. */
+main code {
+  font-size: 0.9em;
+  overflow-wrap: anywhere;
+}
+
 /* The footer rule is the mark's own squiggle: four honest humps, then the
    tail gives out. Masked so it takes the theme's red. */
 footer {