diff --git a/docs/docs.json b/docs/docs.json
index 2abfffc7..bc937b7c 100644
--- a/docs/docs.json
+++ b/docs/docs.json
@@ -252,6 +252,7 @@
               },
               "router/compliance-and-data-management",
               "router/query-batching",
+              "router/feature-flags",
               "router/subgraph-error-propagation",
               "router/file-upload",
               "router/access-logs",
diff --git a/docs/router/feature-flags.mdx b/docs/router/feature-flags.mdx
new file mode 100644
index 00000000..c4eeb2bd
--- /dev/null
+++ b/docs/router/feature-flags.mdx
@@ -0,0 +1,56 @@
+---
+title: "Feature Flags"
+description: "Route traffic through alternate subgraphs by toggling feature flags per request."
+icon: flag
+sidebarTitle: Feature Flags
+---
+
+## Overview
+
+Router-level feature flags let you swap a subgraph at request time without a redeploy. Each flag defines a replacement subgraph. When a request includes the matching header or cookie, the router resolves the target subgraph to the flagged replacement.
+
+<Info>
+ For a primer on Cosmo feature flags and rollout strategies, see the [concepts guide](/concepts/feature-flags).
+</Info>
+
+## Declare a Feature Flag
+
+Add the flag configuration in `router-compose.yaml`. Each flag defines one or more `feature_graphs` that describe the replacement subgraph to serve when the flag is active.
+
+```yaml router-compose.yaml
+feature_flags:
+  - name: test_checkout
+    feature_graphs:
+      - name: checkout_canary
+        subgraph_name: checkout
+        routing_url: https://api.example.com/checkout-canary/graphql
+        schema:
+          file: feature-flag_checkout.graphql
+subgraphs:
+  - name: checkout
+    routing_url: https://api.example.com/checkout/graphql
+    schema:
+      file: checkout.graphql
+```
+
+Key points:
+
+- `feature_flags[*].name` is the value you will send from the client (case sensitive).
+- `feature_graphs[*].subgraph_name` must match the corresponding entry under `subgraphs` (`checkout` in the example).
+- The router swaps the referenced `subgraph_name` with the replacement defined in `feature_graphs` when the flag is active.
+
+<Note>
+ Name feature flag schemas using the `feature-flag_*.graphql` convention and check in an empty placeholder subgraph file to keep composition predictable.
+</Note>
+
+## Trigger the Flag
+
+Activate a flag by sending the header (or matching cookie) with the desired flag name. All requests that include the header are routed through the replacement subgraph.
+
+```http
+GET /graphql HTTP/1.1
+Host: router.example.com
+X-Feature-Flag: test_checkout
+```
+
+When the router receives `X-Feature-Flag: test_checkout`, it composes the operation against the replacement schema and forwards traffic to the routing URLs declared in the flag configuration.