docs: update schema.json and docs for new extend features

docs/site/content/docs/reference/configuration.mdx

@@ -26,7 +26,27 @@ Configure the behavior of `turbo` by using a `turbo.json` file in your Workspace
 Extend from the root `turbo.json` to create specific configuration for a package using [Package Configurations](/docs/reference/package-configurations).
 
 - The only valid value for `extends` is `["//"]` to inherit configuration from the root `turbo.json`.
-- If `extends` is used in the root `turbo.json`, it will be ignored.
+- If `extends` is used in the root `turbo.json`, an error will be thrown.
+
+#### `$TURBO_EXTENDS`
+
+<Callout type="good-to-know">
+  Two Future Flags exist to opt into new features to allow for more
+  configuration flexibility.
+</Callout>
+
+By default, keys are completely overridden when using [Package Configurations](/docs/reference/package-configurations). To append to parent configuration, use the `$TURBO_EXTENDS` microsyntax:
+
+```json title="packages/ui/turbo.json"
+{
+  "extends": ["//"],
+  "tasks": {
+    "build": {
+      "dependsOn": ["$TURBO_EXTENDS$", "special-task"]
+    }
+  }
+}
+```
 
 ### `globalDependencies`
 
@@ -199,6 +219,15 @@ Adds a tag to a package for use with [Boundaries](/docs/reference/boundaries).
 
 This key only works in [Package Configurations](/docs/reference/package-configurations). Using this key in a root `turbo.json` will result in an error.
 
+### `futureFlags`
+
+"Future flags" allow you to opt into experimental and beta features, and breaking changes prior to major releases.
+
+Current Future Flags:
+
+- `turboExtendsKeyword`: Enable usage of [`$TURBO_EXTENDS$` microsyntax](#turbo_extends)
+- `nonRootExtends`: Enable [extending Package Configurations from other packages](#TODO)
+
 ## Defining tasks
 
 ### `tasks`

packages/turbo-types/schemas/schema.json

@@ -105,7 +105,17 @@
         },
         "futureFlags": {
           "type": "object",
-          "additionalProperties": {},
+          "properties": {
+            "turboExtendsKeyword": {
+              "type": "boolean",
+              "description": "Enable `$TURBO_EXTENDS$`\n\n When enabled, allows using `$TURBO_EXTENDS$` in array fields.  This will change the default behavior of overriding the field to instead append."
+            },
+            "nonRootExtends": {
+              "type": "boolean",
+              "description": "Enable extending from a non-root `turbo.json`\n\nWhen enabled, allows using extends targeting `turbo.json`s other than root. All `turbo.json` must still extend from the root `turbo.json` first."
+            }
+          },
+          "additionalProperties": false,
           "description": "Opt into breaking changes prior to major releases, experimental features, and beta features.",
           "default": {}
         }

packages/turbo-types/schemas/schema.v2.json

@@ -105,7 +105,17 @@
         },
         "futureFlags": {
           "type": "object",
-          "additionalProperties": {},
+          "properties": {
+            "turboExtendsKeyword": {
+              "type": "boolean",
+              "description": "Enable `$TURBO_EXTENDS$`\n\n When enabled, allows using `$TURBO_EXTENDS$` in array fields.  This will change the default behavior of overriding the field to instead append."
+            },
+            "nonRootExtends": {
+              "type": "boolean",
+              "description": "Enable extending from a non-root `turbo.json`\n\nWhen enabled, allows using extends targeting `turbo.json`s other than root. All `turbo.json` must still extend from the root `turbo.json` first."
+            }
+          },
+          "additionalProperties": false,
           "description": "Opt into breaking changes prior to major releases, experimental features, and beta features.",
           "default": {}
         }

packages/turbo-types/src/types/config-v2.ts

@@ -196,7 +196,21 @@ export interface RootSchema extends BaseSchema {
    *
    * @defaultValue `{}`
    */
-  futureFlags?: Record<string, unknown>;
+  futureFlags?: {
+    /** Enable `$TURBO_EXTENDS$`
+     *
+     *   When enabled, allows using `$TURBO_EXTENDS$` in array fields.
+     *   This will change the default behavior of overriding the field to instead append.
+     */
+    turboExtendsKeyword?: boolean;
+
+    /** Enable extending from a non-root `turbo.json`
+     *
+     * When enabled, allows using extends targeting `turbo.json`s other than
+     * root. All `turbo.json` must still extend from the root `turbo.json` first.
+     */
+    nonRootExtends?: boolean;
+  };
 }
 
 export interface Pipeline {