From aa2f2bb6af157fbe122c22850b57f65d0f7ce4c4 Mon Sep 17 00:00:00 2001
From: Chris Lenfest <clenfest@apollographql.com>
Date: Wed, 31 Jul 2024 11:58:08 -0500
Subject: [PATCH 1/2] Add specific language to context docs that reference
 resolvers are necessary for contextual fields

---
 docs/source/entities/use-contexts.mdx | 25 +++++++++++++++++++++++++
 1 file changed, 25 insertions(+)

diff --git a/docs/source/entities/use-contexts.mdx b/docs/source/entities/use-contexts.mdx
index e782e4b53..9baaa4660 100644
--- a/docs/source/entities/use-contexts.mdx
+++ b/docs/source/entities/use-contexts.mdx
@@ -191,3 +191,28 @@ type Transaction @key(fields: "id") {
   ): Int!
 }
 ``` 
+
+## A note on resolvers
+Fields that can be used contextually must be resolvable via a reference resolver. Since a query plan to fetch a contextual field is doing so based on the entity on which the `@context` directive is set, we need to make sure that all subgraphs that resolve that entity support can look up their fields based on entity keys. In the above example, if the first subgraph had a single query to retrieve the logged in user:
+
+```graphql
+type Query {
+  me: User!
+} 
+```
+A resolver that did the following would not correctly support contextual variables:
+```typescript
+Query: {
+  me: () => ({
+    id: 1, userCurrency: { id: 431, currencyCode: 'USD'}
+  })
+}
+```
+This is because the fetch set to subgraph 1 to retrieve the `isoCode` would be done on the entity. Therefore a section to resolve a User by keys would need to be added:
+```typescript
+User: () => {
+  __resolveReference(partialUser) {
+    return fetchUserById(partialUser.id);
+  }
+}
+```
\ No newline at end of file

From e6087bafe2ef67d46d2de8f1955f87e1af5467c2 Mon Sep 17 00:00:00 2001
From: Maria Elisabeth Schreiber <maria.schreiber@apollographql.com>
Date: Tue, 13 Aug 2024 15:45:15 -0400
Subject: [PATCH 2/2] Copyedit

---
 docs/source/entities/use-contexts.mdx | 15 +++++++++++----
 1 file changed, 11 insertions(+), 4 deletions(-)

diff --git a/docs/source/entities/use-contexts.mdx b/docs/source/entities/use-contexts.mdx
index 9baaa4660..10dc4acb5 100644
--- a/docs/source/entities/use-contexts.mdx
+++ b/docs/source/entities/use-contexts.mdx
@@ -193,22 +193,29 @@ type Transaction @key(fields: "id") {
 ``` 
 
 ## A note on resolvers
-Fields that can be used contextually must be resolvable via a reference resolver. Since a query plan to fetch a contextual field is doing so based on the entity on which the `@context` directive is set, we need to make sure that all subgraphs that resolve that entity support can look up their fields based on entity keys. In the above example, if the first subgraph had a single query to retrieve the logged in user:
 
-```graphql
+Fields that are used with the context directives must be resolvable via a [reference resolver](/federation/entities/#2-define-a-reference-resolver). Query plans that fetch contextual fields are based on the entity where the `@context` directive is set. Therefore, all subgraphs that resolve that entity must support looking up their fields based on the entity's `@keys` fields.
+
+Take the [previous example](#referencing-fields-across-subgraphs). Suppose the first subgraph has a single query to retrieve the logged in user:
+
+```graphql disableCopy showLineNumbers=false
 type Query {
   me: User!
 } 
 ```
-A resolver that did the following would not correctly support contextual variables:
-```typescript
+
+The following example resolver would not correctly support contextual variables:
+
+```typescript title="❌ Incorrect example" disableCopy showLineNumbers=false
 Query: {
   me: () => ({
     id: 1, userCurrency: { id: 431, currencyCode: 'USD'}
   })
 }
 ```
+
 This is because the fetch set to subgraph 1 to retrieve the `isoCode` would be done on the entity. Therefore a section to resolve a User by keys would need to be added:
+
 ```typescript
 User: () => {
   __resolveReference(partialUser) {