update uplink schema and merge main

docs/shared/link-directive.mdx

@@ -0,0 +1,13 @@
+Subgraph schemas opt in to Federation v2 features by applying the `@link` directive to the `schema` type. You can optionally add an `import` list to this definition to include each federation-specific directive that the subgraph schema uses. In the example below, the schema uses the `@key` and `@shareable` directives:
+
+```graphql
+extend schema
+  @link(url: "https://specs.apollo.dev/federation/v2.0",
+        import: ["@key", "@shareable"])
+```
+
+<Tip>
+
+You can use `@link` to distinguish between Federation v1 (no `@link`) and Federation v2 (required `@link`) schemas.
+
+</Tip>

docs/source/reference/federation/directives.mdx

@@ -6,6 +6,7 @@ description: Reference for GraphQL federation directives including @key, @extend
 
 import ProgressiveOverrideEnterprise from '../../../shared/progressive-override-enterprise.mdx';
 import EnterpriseDirective from '../../../shared/enterprise-directive.mdx';
+import LinkDirective from '../../../shared/link-directive.mdx';
 
 Apollo Federation defines a collection of directives that you use in your subgraph schemas to enable certain features.
 
@@ -73,6 +74,8 @@ type Book @fed__shareable {
 
 As shown, custom namespace prefixes also end in two underscores.
 
+## Managing schemas
+
 <MinVersion version="2.0">
 
 ### The `@link` directive
@@ -90,6 +93,8 @@ directive @link(
 
 This directive links definitions from an external specification to this schema. Every Federation 2 subgraph uses the `@link` directive to import the other federation-specific directives described in this article (see the syntax in [Importing directives](#importing-directives)).
 
+<LinkDirective />
+
 For more information on `@link`, see the [official spec](https://specs.apollo.dev/link/v1.0/).
 
 ## Managing types

docs/source/reference/federation/subgraph-spec.mdx

@@ -4,6 +4,8 @@ subtitle: Subgraph specification reference for server library developers
 description: Learn about Apollo Federation 2 subgraph specifications, enhanced introspection, and entity field resolution for GraphQL server libraries.
 ---
 
+import LinkDirective from '../../../shared/link-directive.mdx';
+
 This content is provided for developers adding federated subgraph support to a GraphQL server library, and for anyone curious about the inner workings of federation. You do not need to read this if you're building a supergraph with existing [subgraph-compatible libraries](/graphos/reference/federation/compatible-subgraphs), such as Apollo Server.
 
 Servers that are partially or fully compatible with this specification are tracked in Apollo's [subgraph compatibility repository](https://github.com/apollographql/apollo-federation-subgraph-compatibility).
@@ -13,6 +15,7 @@ For a GraphQL service to operate as an Apollo Federation 2 subgraph, it must do
 - Automatically extend its schema with all definitions listed in [Subgraph schema additions](#subgraph-schema-additions)
 - Correctly resolve the `Query._service` [enhanced introspection field](#fetch-service-capabilities)
 - Provide a mechanism for subgraph developers to resolve entity fields via the [`Query._entities` field](#resolving-entity-fields-with-query_entities)
+- Apply the [`@link` directive to the `schema` type](#apply-link-directive)
 
 Each of these requirements is described in the sections below.
 
@@ -408,6 +411,10 @@ For this reference resolver, the developer calls a `fetchProductByUPC` function,
 
 Your subgraph library does not need to use this reference resolver pattern. It just needs to provide and document some pattern for defining entity-fetching logic.
 
+## Apply @link directive
+
+<LinkDirective />
+
 ## Glossary of schema additions
 
 This section describes type and field definitions that a valid subgraph service must automatically add to its schema. These definitions are all listed above in [Subgraph schema additions](#subgraph-schema-additions).

docs/source/reference/federation/versions.mdx

@@ -981,6 +981,12 @@ Value types
 
 ## v1.1
 
+<Caution>
+
+Apollo Router Core and GraphOS Router v1.60 and later don't support Federation v1.x supergraphs.
+
+</Caution>
+
 #### Directive changes
 
 <table>
@@ -1018,6 +1024,12 @@ directive @tag(name: String!) repeatable on
 
 ## v1.0
 
+<Caution>
+
+Apollo Router Core and GraphOS Router v1.60 and later don't support Federation v1.x supergraphs.
+
+</Caution>
+
 #### Directive changes
 
 For details on these directives as defined in Federation 1, see the [Federation 1 subgraph spec](/federation/v1/federation-spec).

docs/source/schema-design/federated-schemas/entities/intro.mdx

@@ -1,24 +1,24 @@
 ---
 title: Introduction to Entities
-subtitle: Resolve federated types across multiple subgraphs
-description: Learn to define, contribute to, and reference object types that resolve their fields across multiple subgraphs in a federated GraphQL architecture.
+subtitle: Fundamental keyed object type of Apollo Federation
+description: Learn to define, contribute to, and reference entities, the fundamental object types of Apollo Federation that resolve their fields across one or more subgraphs.
 redirectFrom:
     - /federation/entities
 ---
 
-Federated schemas let multiple subgraphs collaboratively define and resolve fields for shared object types.
-This guide shows you how to define a shared object type called an _entity_.
+<Note>
+
+Before getting started with entities, you may want to check out the [Introduction to Apollo Federation](/graphos/schema-design/federated-schemas/federation) for a conceptual overview.
 
-Before you get started, you may want to check out the [Introduction to Apollo Federation](/graphos/schema-design/federated-schemas/federation) for a conceptual overview.
+</Note>
 
 ## Entity overview
 
-_Entities_ are a fundamental aspect of federated schemas.
-In a supergraph, an entity is an object type that can resolve its fields across multiple subgraphs.
-Each subgraph can contribute different fields to the entity and is responsible for resolving only the fields that it contributes.
-This enables subgraphs to adhere to the separation of concerns principle.
+In Apollo Federation, federated data objects are represented as _entities_. Entities are objects that can be fetched with one or more unique key fields. Like a row in a database table, an entity contains fields of various types, and it can be uniquely identified by a key field or set of fields.
 
-For example, this `Product` entity's fields are defined and resolved across two subgraphs:
+Entities are defined in subgraph schemas. Each subgraph can contribute different fields to an entity it defines and is responsible for _resolving_ it—returning only the fields that it contributes. This enables subgraphs to adhere to the separation of concerns principle.
+
+An _entity type_ is an object type that has been [defined as an entity](#defining-an-entity). Because an entity is keyed, an entity type's definition must have a `@key` directive. For example, this `Product` entity's fields are defined and resolved across two subgraphs:
 
 <CodeColumns>
 
@@ -45,7 +45,7 @@ Only object types can be entities.
 
 </Note>
 
-This guide goes over how to define entities in your subgraph schemas and code.
+The rest of this guide goes over how to define entities in your subgraph schemas and code.
 
 ## Defining an entity
 
@@ -54,6 +54,14 @@ To define an entity within a particular subgraph, you do the following:
 1. Apply the [`@key` directive](#1-define-a-key) to an object type.
 2. Define the object type's [reference resolver](#2-define-a-reference-resolver).
 
+<Tip>
+
+With Apollo Connectors, you add [connector directives](/graphos/schema-design/connectors/directives) instead of writing reference resolver code. 
+
+You can [set `entity: true`](/graphos/schema-design/connectors/directives#rules-for-entity-true) for the `@connect` directive to provide an entity resolver for its fields.
+
+</Tip>
+
 <ExpansionPanel title="Watch the video overview">
 
   <Wistia WistiaId="7geep7jxo6" />
@@ -117,12 +125,15 @@ Though not strictly required, it's best to use non-nullable fields for keys. If
 
 ### 2. Define a reference resolver
 
-The `@key` directive effectively tells the router, "This subgraph can resolve an instance of this entity if you provide its unique key." For this to be true, the subgraph must define a _reference resolver_ for the entity.
+The `@key` directive effectively tells the router, "This subgraph can resolve an instance of this entity if you provide its unique key." For this to be true, the subgraph must have a _reference resolver_ for the entity.
 
 <Note>
 
 This section describes how to create reference resolvers in Apollo Server.
-If you're using another [subgraph-compatible library](/graphos/reference/federation/compatible-subgraphs), see its documentation for creating reference resolvers or the equivalent functionality.
+
+- If you're using Apollo Connectors, the [connectors directives](/graphos/schema-design/connectors/directives) declare which REST endpoints to use to  resolve entity fields, so you don't write any reference resolvers.
+
+- If you're using another [subgraph-compatible library](/graphos/reference/federation/compatible-subgraphs), see its documentation for creating reference resolvers or the equivalent functionality.
 
 </Note>
 

docs/source/schema-design/federated-schemas/federation.mdx

@@ -1,27 +1,19 @@
 ---
 title: Introduction to Apollo Federation
-subtitle: Learn how federation combines your GraphQL APIs into a unified supergraph
-description: Learn how Apollo Federation can help you declaratively combine your services into a unified, federated GraphQL API using a microservices architecture.
+subtitle: Learn how federation orchestrates your APIs into a unified supergraph
+description: Learn how Apollo Federation helps you declaratively orchestrate your APIs and services into a unified, federated GraphQL API using a microservices architecture.
 redirectFrom:
     - /federation
 ---
 
-Apollo Federation lets you declaratively combine multiple APIs into a single, federated graph. This federated graph enables clients to interact with your APIs through a single request.
+Apollo Federation enables you to declaratively combine multiple APIs into a single federated GraphQL API. Federation serves as an API orchestration layer, where clients make a single GraphQL request and it coordinates multiple API calls to return a unified response.
 
-A client makes a request to the federated GraphQL API's single entry point called the _router_. The router intelligently orchestrates and distributes the request across your APIs and returns a unified response. For a client, the request and response cycle of querying the router looks the same as querying any GraphQL server.
+Clients makes requests to the federated GraphQL API's single entry point called the _router_. The router intelligently orchestrates and distributes the request across your APIs and returns a unified response. For a client, the request and response cycle of querying the router looks the same as querying any GraphQL API.
 
 <img src='../../images/federation.svg' class="dark:hidden"/>
 <img src='../../images/federation-dark.svg' class="hidden dark:block"/>
 
-<Note>
-
-Your federated GraphQL API, or _graph_, can be made of GraphQL APIs and other data sources.
-[Learn how Apollo Connectors](../connectors/) simplify incorporating REST APIs into your graph.
-
-</Note>
-
-
-To jump into building a federated GraphQL API, check out the [Apollo GraphOS Quickstart](/graphos/get-started/guides/quickstart).
+Your federated GraphQL API, or _graph_, can be made of GraphQL APIs, REST APIs, and other data sources.
 
 <ExpansionPanel title="Watch the video overview">
 
@@ -66,6 +58,10 @@ With Apollo Federation, clients can interact with the federated schema as if it
 
 With federation, every team contributes directly to the overall federated GraphQL schema. Each team can work independently without needing to maintain multiple API layers. This frees your platform team to focus on the quality of your API rather than keeping it up to date.
 
+### Connect APIs declaratively
+
+Apollo Federation is the foundation of Apollo Connectors, which allows you to integrate REST APIs into your federated graph by defining them declaratively in your GraphQL schema.
+
 ## Next steps
 
 Before continuing, it's helpful to know some terminology:
@@ -80,12 +76,18 @@ Different subgraphs in the same supergraph can use different server implementati
 
 Ready to get started? 
 
-- Create and run a federated graph with the [Quickstart](/graphos/get-started/guides/quickstart).
-
 - Connect REST APIs to your graph using Apollo Connectors with the [REST quickstart](/graphos/get-started/guides/rest-quickstart).
 
+- Create and run a federated graph with the [Quickstart](/graphos/get-started/guides/quickstart).
+
 ### Additional resources
 
-Depending on your goals, you have several options for learning more about federation: 
-- If you're new to federated architecture, this [overview article](https://graphql.com/learn/federated-architecture/) can familiarize the concepts.
-- If you learn best by doing, this [interactive course](https://www.apollographql.com/tutorials/voyage-part1) teaches you to build an example supergraph using Apollo Federation.
+If you're new to federated architecture, this [overview article](https://graphql.com/learn/federated-architecture/) can introduce the concepts.
+
+<OdysseyCallout>
+
+- To integrate existing APIs into a federated graph, this [interactive course](https://www.apollographql.com/tutorials/connectors-intro-rest) teaches you how to bring an existing REST API into a GraphQL API using Apollo Connectors.
+
+- To federate a GraphQL backend, this [interactive course](https://www.apollographql.com/tutorials/voyage-part1) teaches you how to build an example supergraph using Apollo Federation.
+
+</OdysseyCallout>

docs/source/schema-design/federated-schemas/ide-support.mdx

@@ -15,25 +15,7 @@ Apollo's [VS Code Extension](https://marketplace.visualstudio.com/items?itemName
 
 ## JetBrains
 
-The [GraphQL Plugin for JetBrains](https://plugins.jetbrains.com/plugin/8097-graphql/) provides federation-specific development features, such as autocomplete for federation directives. However, you must enable this federation support after installing the plugin. Otherwise, your IDE might display unexpected errors while you're working with a subgraph schema.
-
-### Setup
-
-To enable federation support, do the following in your IDE after installing the plugin:
-
-1. Open your IDE's **Settings** window.
-2. Expand the **Languages & Frameworks** section.
-3. Click **GraphQL**.
-4. Check the **Federation** checkbox.
-
-<img
-    class="screenshot"
-    alt="An animation showing the process of enabling Apollo Federation support in the GraphQL plugin for JetBrains (described above)"
-    src="../../images/JetBrains-plugin.webp"
-    width="600"
-/>
-
-This plugin supports all IntelliJ-based IDEs, including:
+Apollo's [JetBrains Plugin](https://plugins.jetbrains.com/plugin/20645-apollo-graphql) provides federation-specific development features, such as autocomplete for federation directives. This plugin supports all IntelliJ-based IDEs, including:
 
 - IntelliJ IDEA
 - PyCharm
@@ -44,8 +26,10 @@ This plugin supports all IntelliJ-based IDEs, including:
 - Rider
 - GoLand
 
+You must enable the Rover integration after installing the plugin. Otherwise, your IDE might display unexpected errors while you're working with a subgraph schema. See this [the dedicated documentation page](/graphos/schema-design/connectors/jetbrains#configuration) for configuration details.
+
 ## Additional resources
 
-If your graph uses the Apollo Router, make sure to enable [router configuration awareness](/graphos/reference/router/configuration#configuration-awareness-in-your-text-editor) in your editor.
+If your graph uses the Apollo Router Core or GraphOS Router, make sure to enable [router configuration awareness](/graphos/reference/router/configuration#configuration-awareness-in-your-text-editor) in your editor.
 
-If you're developing with Apollo Connectors, refer to the connectors-specific [VS Code Extension](/graphos/schema-design/connectors/vs-code) and [Vim/NeoVim](/graphos/schema-design/connectors/vim) pages.
+If you're developing with Apollo Connectors, refer to the connectors-specific [VS Code Extension](/graphos/schema-design/connectors/vs-code), [JetBrains IDEs](/graphos/schema-design/connectors/jetbrains), and [Vim/NeoVim](/graphos/schema-design/connectors/vim) pages.