WIP 959a2

Author: anthonyshew

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`