docs: clarify nested keys (#3001)

Request from SA team to surface nested field pattern on directive
reference page

docs/source/config.json

@@ -31,8 +31,8 @@
       "Composition": "/federated-types/composition",
       "Federated directives": "/federated-types/federated-directives",
       "Sharing types (value types)": "/federated-types/sharing-types",
-      "Entities (basics)": "/entities",
-      "Entities (advanced)": "/entities-advanced",
+      "Introduction to entities": "/entities",
+      "Advanced entities": "/entities-advanced",
       "Entity interfaces": "/federated-types/interfaces",
       "Migrating from schema stitching": "/migrating-from-stitching"
     },

docs/source/entities-advanced.mdx

@@ -23,7 +23,8 @@ type User @key(fields: "username domain") {
 
 #### Nested fields in compound `@key`s
 
-Compound keys can also include nested fields. In the following example, the `User` entity's `@key` consists of both a user's `id` and the `id` of that user's associated `Organization`:
+Nested fields are often used in compound keys.
+In the following example, the `User` entity's `@key` consists of both a user's `id` and the `id` of that user's associated `Organization`:
 
 ```graphql {1} title="Users subgraph"
 type User @key(fields: "id organization { id }") {
@@ -36,6 +37,12 @@ type Organization {
 }
 ```
 
+<Note>
+
+Though nested fields are most commonly used in compound keys, you can also use a nested field as a single `@key` field.
+
+</Note>
+
 ### Multiple `@key`s
 
 When different subgraphs interact with different fields of an entity, you may need to define multiple `@key`s for the entity. For example, a Reviews subgraph might refer to products by their ID, whereas an Inventory subgraph might use SKUs.

docs/source/federated-types/federated-directives.mdx

@@ -102,7 +102,7 @@ For more information on `@link`, see the [official spec](https://specs.apollo.de
 directive @key(fields: FieldSet!, resolvable: Boolean = true) repeatable on OBJECT | INTERFACE
 ```
 
-Designates an object type as an [entity](../entities/) and specifies its key fields (a set of fields that the subgraph can use to uniquely identify any instance of the entity).
+Designates an object type as an entity and specifies its key fields. Key fields are a set of fields that a subgraph can use to uniquely identify any instance of the entity.
 
 ```graphql {1}
 type Product @key(fields: "id") {
@@ -112,7 +112,16 @@ type Product @key(fields: "id") {
 }
 ```
 
-You can apply multiple `@key` directives to a single entity (to specify multiple valid sets of key fields), if your subgraph library supports repeatable directives:
+<Tip>
+
+To learn best practices and advanced use cases for `@key`, refer to the following guides:
+
+- [Introduction to entities](../entities#1-define-a-key)
+- [Advanced entities](../entities-advanced)
+
+</Tip>
+
+You can apply multiple `@key` directives to a single entity to specify multiple valid sets of key fields, if your subgraph library supports repeatable directives:
 
 ```graphql {1}
 type Product @key(fields: "upc") @key(fields: "sku") {
@@ -122,8 +131,12 @@ type Product @key(fields: "upc") @key(fields: "sku") {
 }
 ```
 
+<Note>
+
 To check whether your subgraph library supports repeatable directives, see the `repeatable @key` item in [Federation-compatible subgraph implementations](../building-supergraphs/supported-subgraphs/).
 
+</Note>
+
 In Apollo Federation 2.3 and later, you can also apply `@key` to `interface` definitions to create [entity interfaces](./interfaces/). If you apply `@key` to an `interface` in earlier versions of Federation 2, a composition error occurs.
 
 #### Arguments