From dd512a9ebc2bf048a93e5c4932d7937045aebbf6 Mon Sep 17 00:00:00 2001
From: shrugs <mattgcondon@gmail.com>
Date: Wed, 3 Jun 2026 11:02:56 -0500
Subject: [PATCH 1/3] docs(ensnode.io): emotional red/green narrative framing
 in Why ENSNode pages

Apply caution-frame (red :::danger) / solution-frame (green :::tip) panels
with nested LinkCards across the high-visibility Why ENSNode pages, per
docs feedback. Pairs with the card-in-aside styling from PR #2233.

- keep-ens-working: red panel above the fold linking to Key Limitations;
  Next Steps split into a red (problem) and green (solution) panel.
- why-ensnode index: lead with the stakes (red panel), then the solution
  (green panel), then a single "How ENSNode delivers" proof cluster that
  folds in the former One unified API / Multichain / Full-stack sections
  (removing the awkward standalone "Multichain by default" heading).
- ensv2-readiness: "Be ready!" panel blue -> green + Omnigraph card;
  Key Limitations wrapped in a red panel.
---
 .../integrate/why-ensnode/ensv2-readiness.mdx | 25 +++++--
 .../docs/docs/integrate/why-ensnode/index.mdx | 66 +++++++++----------
 .../why-ensnode/keep-ens-working.mdx          | 18 ++++-
 3 files changed, 67 insertions(+), 42 deletions(-)

diff --git a/docs/ensnode.io/src/content/docs/docs/integrate/why-ensnode/ensv2-readiness.mdx b/docs/ensnode.io/src/content/docs/docs/integrate/why-ensnode/ensv2-readiness.mdx
index 82f38dd0d..9e428d524 100644
--- a/docs/ensnode.io/src/content/docs/docs/integrate/why-ensnode/ensv2-readiness.mdx
+++ b/docs/ensnode.io/src/content/docs/docs/integrate/why-ensnode/ensv2-readiness.mdx
@@ -5,20 +5,31 @@ description: How building with ENSNode today prepares your application for ENSv2
 
 import { LinkCard, Aside } from "@astrojs/starlight/components";
 
-<Aside type="note" icon="approve-check-circle" title="Be ready!">
+<Aside type="tip" icon="approve-check-circle" title="Be ready!">
   Build with the **ENS Omnigraph** today and your app will support **ENSv2** the moment it launches
   — with zero downtime or code changes.
+
+  <LinkCard
+    title="ENS Omnigraph API"
+    href="/docs/integrate/omnigraph"
+    description="The ENSv2-ready, unified GraphQL API over both ENSv1 and ENSv2 — start here."
+  />
 </Aside>
 
 ## Historical limitations of building on ENS
 
-Full access to ENS data formerly required two separate data-fetching strategies working in parallel: **ENS resolution** (RPC calls with CCIP-Read, e.g. via `viem` or `wagmi`) and **indexed ENS data** (the ENS Subgraph). Neither system alone was complete — resolution is "close to the metal" and the Subgraph carries a long list of [Key Limitations](/docs/integrate/ens-subgraph/key-limitations). And **with ENSv2, the complexity of ENS's onchain state space meaningfully increases**.
+Full access to ENS data formerly required two separate data-fetching strategies working in parallel: **ENS resolution** (RPC calls with CCIP-Read, e.g. via `viem` or `wagmi`) and **indexed ENS data** (the ENS Subgraph). Neither system alone was complete — resolution is "close to the metal" and the Subgraph carries a long list of [Key Limitations](/docs/integrate/ens-subgraph/key-limitations).
 
-<LinkCard
-  title="Key Limitations of the ENS Subgraph"
-  description="The full breakdown of what the Subgraph can't do — and why it breaks with ENSv2."
-  href="/docs/integrate/ens-subgraph/key-limitations"
-/>
+<Aside type="danger" title="🚨 It only gets harder with ENSv2">
+  **With ENSv2, the complexity of ENS's onchain state space meaningfully increases** — and the
+  Subgraph's limitations turn from inconveniences into breaking failures.
+
+  <LinkCard
+    title="Key Limitations of the ENS Subgraph 🚨"
+    description="The full breakdown of what the Subgraph can't do — and why it breaks with ENSv2."
+    href="/docs/integrate/ens-subgraph/key-limitations"
+  />
+</Aside>
 
 ## How ENSNode solves this
 
diff --git a/docs/ensnode.io/src/content/docs/docs/integrate/why-ensnode/index.mdx b/docs/ensnode.io/src/content/docs/docs/integrate/why-ensnode/index.mdx
index a69936821..674e09c5f 100644
--- a/docs/ensnode.io/src/content/docs/docs/integrate/why-ensnode/index.mdx
+++ b/docs/ensnode.io/src/content/docs/docs/integrate/why-ensnode/index.mdx
@@ -7,29 +7,48 @@ import { LinkCard, CardGrid } from "@astrojs/starlight/components";
 
 ENSNode is the full-stack ENSv2 development platform — a single, unified API over **both ENSv1 and ENSv2**, with first-class multichain support and the integration surfaces (React, TypeScript, GraphQL, Postgres) you need to ship.
 
-## Built for ENSv2 from day one
+## The Subgraph won't survive ENSv2
 
 [ENSv2](https://ens.domains/ensv2) is a fundamental change to ENS's onchain data model. The legacy ENS Subgraph wasn't designed for it, and it never will be — single-chain, no resolution, no understanding of the new ENSv2 Namegraph. Apps that stay on the Subgraph will be left behind the moment ENSv2 launches.
 
+:::danger[🚨 What's at stake]
+Indexed ENS data is critical infrastructure for ENS — and the legacy ENS Subgraph is fundamentally unsuitable for ENSv2. When ENSv2 launches, that gap becomes breaking for many of ENS's most important apps.
+
+<LinkCard
+  title="Keep ENS apps working 🚨"
+  description="Much of the ENS ecosystem quietly relies on the Subgraph today, and risks going dark when ENSv2 launches."
+  href="/docs/integrate/ens-subgraph"
+/>
+<LinkCard
+  title="Overcome critical limitations of the ENS Subgraph 🚨"
+  description="Why the Subgraph falls short today, and breaks with ENSv2."
+  href="/docs/integrate/ens-subgraph/key-limitations"
+/>
+:::
+
+## ENSNode is built for ENSv2
+
 ENSNode is built around ENSv2 from the ground up. The same query works against an ENSv1 name today and an ENSv2 name the moment it goes live — with **zero downtime or code changes** in your app.
 
+:::tip[✅ Ready the moment ENSv2 launches]
+Adopt the ENS Omnigraph today and your app is ENSv2-ready before ENSv2 even ships — no rewrite, no scramble, no downtime.
+
 <LinkCard
   title="ENSv2 Readiness"
   description="What you need to do to prepare your app for ENSv2."
   href="/docs/integrate/why-ensnode/ensv2-readiness"
 />
+:::
 
-## One unified API over ENSv1 + ENSv2
-
-The [ENS Omnigraph](/docs/integrate/omnigraph) is a single GraphQL API that returns a polymorphic, unified view of every ENS Domain — regardless of whether it lives in an ENSv1 Nametree, the ENSv2 Namegraph, on mainnet, or on an L2 subregistry such as base.eth subnames on Base.
+## How ENSNode delivers
 
-![ENS Omnigraph diagram](/ens-omnigraph-diagram.png)
+Three capabilities make ENSNode the foundation for ENSv2 apps:
 
-ENSv1 and ENSv2 coexist after the ENSv2 launch. The Omnigraph simplifies that split: your code asks for `domain(by: { name: "vitalik.eth" })` and gets a typed result, regardless of whether the underlying domain is on ENSv1 or ENSv2.
+**One unified API over ENSv1 + ENSv2** — The [ENS Omnigraph](/docs/integrate/omnigraph) is a single GraphQL API that returns a polymorphic, unified view of every ENS Domain — regardless of whether it lives in an ENSv1 Nametree, the ENSv2 Namegraph, on mainnet, or on an L2 subregistry such as base.eth subnames on Base. ENSv1 and ENSv2 coexist after the ENSv2 launch; your code asks for `domain(by: { name: "vitalik.eth" })` and gets a typed result, regardless of which protocol version the underlying domain is on.
 
-## Multichain by default
+![ENS Omnigraph diagram](/ens-omnigraph-diagram.png)
 
-ENSNode provides the world's best indexing coverage for ENS, spanning every chain that matters, including:
+**Multichain by default** — ENSNode provides the world's best indexing coverage for ENS, spanning every chain that matters:
 
 - **Mainnet** — the canonical ENS root and `.eth` registrations
 - **Basenames** (`.base.eth`) on Base
@@ -38,32 +57,13 @@ ENSNode provides the world's best indexing coverage for ENS, spanning every chai
 
 No more wiring up a per-chain Subgraph, reconciling overlapping ENS Nametrees, or writing CCIP-Read logic in your app — ENSNode handles forward and reverse resolution, including offchain gateways, server-side.
 
-## Full-stack integration surfaces
-
-Whatever your stack looks like, there's an ENSNode integration shaped for it.
-
-  <LinkCard
-    title="ENSNode integration options"
-    description="Explore the different ways to integrate with ENSNode based on your stack, runtime, and needs."
-    href="/docs/integrate/integration-options"
-  />
-
-## Why it matters beyond your app
+**Full-stack integration surfaces** — whatever your stack looks like, there's an ENSNode integration shaped for it: React, TypeScript, GraphQL, or direct Postgres access.
 
-Indexed ENS data is critical infrastructure for ENS — and the legacy ENS Subgraph is fundamentally unsuitable for ENSv2. Closing that gap is required for many of ENS's most important apps.
-
-<CardGrid>
-  <LinkCard
-    title="Keep ENS apps working 🚨"
-    description="Much of the ENS ecosystem quietly relies on the Subgraph today, and risks going dark when ENSv2 launches."
-    href="/docs/integrate/ens-subgraph"
-  />
-  <LinkCard
-    title="Overcome critical limitations of the ENS Subgraph 🚨"
-    description="Why the Subgraph falls short today, and breaks with ENSv2."
-    href="/docs/integrate/ens-subgraph/key-limitations"
-  />
-</CardGrid>
+<LinkCard
+  title="ENSNode integration options"
+  description="Explore the different ways to integrate with ENSNode based on your stack, runtime, and needs."
+  href="/docs/integrate/integration-options"
+/>
 
 ## Join those already building on ENSNode
 
diff --git a/docs/ensnode.io/src/content/docs/docs/integrate/why-ensnode/keep-ens-working.mdx b/docs/ensnode.io/src/content/docs/docs/integrate/why-ensnode/keep-ens-working.mdx
index f5da1a3a4..c4f5a28b0 100644
--- a/docs/ensnode.io/src/content/docs/docs/integrate/why-ensnode/keep-ens-working.mdx
+++ b/docs/ensnode.io/src/content/docs/docs/integrate/why-ensnode/keep-ens-working.mdx
@@ -7,6 +7,16 @@ import { LinkCard } from "@astrojs/starlight/components";
 import UpgradeToOmnigraphRequiredTable from "@components/molecules/upgrade-to-omnigraph-required-table/index.astro";
 import ENSSubgraphDependentApp from "@components/molecules/upgrade-to-omnigraph-required-table/ENSSubgraphDependentApp.astro";
 
+:::danger[🚨 These apps go dark when ENSv2 launches]
+Hundreds of apps quietly read ENS data through the ENS Subgraph today. **The moment ENSv2 launches, the Subgraph stops being a reliable source of ENS data** — and every app that depends on it is at risk until it upgrades to the ENS Omnigraph API.
+
+<LinkCard
+  title="Key Limitations of the ENS Subgraph 🚨"
+  href="/docs/integrate/ens-subgraph/key-limitations"
+  description="The full list of ways the ENS Subgraph falls short today — and why each one breaks with ENSv2."
+/>
+:::
+
 ## The ENS Subgraph is not ENSv2 compatible
 
 Over the years, the ENS Subgraph quietly became one of the most depended-on pieces of infrastructure in ENS. An enormous swath of the ENS ecosystem — and much of the broader web3 / Ethereum ecosystem — reads ENS data through it, directly or indirectly.
@@ -326,18 +336,22 @@ A growing set of companies and apps have already moved onto ENSNode — [see who
 
 ## Next Steps
 
-Next, consider the key limitations of the legacy ENS Subgraph.
+:::danger[🚨 The problem only gets worse]
+Every one of the Subgraph's [Key Limitations](/docs/integrate/ens-subgraph/key-limitations) turns from an inconvenience today into a breaking failure the moment ENSv2 launches. Staying on the Subgraph is not an option.
 
 <LinkCard
   href="/docs/integrate/ens-subgraph/key-limitations"
   title="Key Limitations of the Subgraph 🚨"
   description="The full list of ways the ENS Subgraph falls short — and gets worse with ENSv2."
 />
+:::
 
-Or, prepare your app or platform for ENSv2 by adopting ENSNode's Omnigraph API.
+:::tip[✅ The path forward: the ENS Omnigraph API]
+Prepare your app or platform for ENSv2 by adopting ENSNode's Omnigraph API — one unified, typed GraphQL API over **both ENSv1 and ENSv2**, multichain by default, with zero downtime or code changes when ENSv2 goes live.
 
 <LinkCard
   href="/docs/integrate/omnigraph"
   title="ENS Omnigraph API"
   description="The ENSv2-ready replacement. Start here for new integrations."
 />
+:::

From 3b054e165dd6470331874d4760796bbc42d18181 Mon Sep 17 00:00:00 2001
From: shrugs <mattgcondon@gmail.com>
Date: Wed, 3 Jun 2026 16:28:13 -0500
Subject: [PATCH 2/3] remove unnecessary line

---
 .../src/content/docs/docs/integrate/why-ensnode/index.mdx       | 2 --
 1 file changed, 2 deletions(-)

diff --git a/docs/ensnode.io/src/content/docs/docs/integrate/why-ensnode/index.mdx b/docs/ensnode.io/src/content/docs/docs/integrate/why-ensnode/index.mdx
index 674e09c5f..8c637129e 100644
--- a/docs/ensnode.io/src/content/docs/docs/integrate/why-ensnode/index.mdx
+++ b/docs/ensnode.io/src/content/docs/docs/integrate/why-ensnode/index.mdx
@@ -42,8 +42,6 @@ Adopt the ENS Omnigraph today and your app is ENSv2-ready before ENSv2 even ship
 
 ## How ENSNode delivers
 
-Three capabilities make ENSNode the foundation for ENSv2 apps:
-
 **One unified API over ENSv1 + ENSv2** — The [ENS Omnigraph](/docs/integrate/omnigraph) is a single GraphQL API that returns a polymorphic, unified view of every ENS Domain — regardless of whether it lives in an ENSv1 Nametree, the ENSv2 Namegraph, on mainnet, or on an L2 subregistry such as base.eth subnames on Base. ENSv1 and ENSv2 coexist after the ENSv2 launch; your code asks for `domain(by: { name: "vitalik.eth" })` and gets a typed result, regardless of which protocol version the underlying domain is on.
 
 ![ENS Omnigraph diagram](/ens-omnigraph-diagram.png)

From 6d90a844ef0c5127e4ba921da3d10d86e38ed207 Mon Sep 17 00:00:00 2001
From: shrugs <mattgcondon@gmail.com>
Date: Wed, 3 Jun 2026 16:58:33 -0500
Subject: [PATCH 3/3] docs: standardize Key Limitations card title; fix
 keep-ens-working href

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 .../src/content/docs/docs/integrate/why-ensnode/index.mdx     | 4 ++--
 .../docs/docs/integrate/why-ensnode/keep-ens-working.mdx      | 2 +-
 2 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/docs/ensnode.io/src/content/docs/docs/integrate/why-ensnode/index.mdx b/docs/ensnode.io/src/content/docs/docs/integrate/why-ensnode/index.mdx
index 8c637129e..d7cf14a18 100644
--- a/docs/ensnode.io/src/content/docs/docs/integrate/why-ensnode/index.mdx
+++ b/docs/ensnode.io/src/content/docs/docs/integrate/why-ensnode/index.mdx
@@ -17,10 +17,10 @@ Indexed ENS data is critical infrastructure for ENS — and the legacy ENS Subgr
 <LinkCard
   title="Keep ENS apps working 🚨"
   description="Much of the ENS ecosystem quietly relies on the Subgraph today, and risks going dark when ENSv2 launches."
-  href="/docs/integrate/ens-subgraph"
+  href="/docs/integrate/why-ensnode/keep-ens-working"
 />
 <LinkCard
-  title="Overcome critical limitations of the ENS Subgraph 🚨"
+  title="Key Limitations of the ENS Subgraph 🚨"
   description="Why the Subgraph falls short today, and breaks with ENSv2."
   href="/docs/integrate/ens-subgraph/key-limitations"
 />
diff --git a/docs/ensnode.io/src/content/docs/docs/integrate/why-ensnode/keep-ens-working.mdx b/docs/ensnode.io/src/content/docs/docs/integrate/why-ensnode/keep-ens-working.mdx
index c4f5a28b0..29cdeee27 100644
--- a/docs/ensnode.io/src/content/docs/docs/integrate/why-ensnode/keep-ens-working.mdx
+++ b/docs/ensnode.io/src/content/docs/docs/integrate/why-ensnode/keep-ens-working.mdx
@@ -341,7 +341,7 @@ Every one of the Subgraph's [Key Limitations](/docs/integrate/ens-subgraph/key-l
 
 <LinkCard
   href="/docs/integrate/ens-subgraph/key-limitations"
-  title="Key Limitations of the Subgraph 🚨"
+  title="Key Limitations of the ENS Subgraph 🚨"
   description="The full list of ways the ENS Subgraph falls short — and gets worse with ENSv2."
 />
 :::