Research and document electric feature flags (#3666)

Co-authored-by: Claude <noreply@anthropic.com>

Author: balegas

website/docs/api/config.md

@@ -307,6 +307,44 @@ The amount of time a consumer process remains active without receiving transacti
 
 </EnvVarConfig>
 
+## Feature Flags
+
+Feature flags enable experimental or advanced features that are not yet enabled by default in production.
+
+### ELECTRIC_FEATURE_FLAGS
+
+<EnvVarConfig
+    name="ELECTRIC_FEATURE_FLAGS"
+    defaultValue=""
+    example="allow_subqueries,tagged_subqueries">
+
+**Available flags:**
+
+- `allow_subqueries` - Enables subquery support in shape WHERE clauses
+- `tagged_subqueries` - Enables improved multi-level dependency handling
+
+</EnvVarConfig>
+
+### allow_subqueries
+
+Enables support for subqueries in the WHERE clause of [shape](/docs/guides/shapes) definitions. When enabled, you can use queries in the form:
+
+```sql
+WHERE id IN (SELECT user_id FROM memberships WHERE org_id = 'org_123')
+```
+
+This allows creating shapes that filter based on related data in other tables, enabling more complex data synchronization patterns.
+
+**Status:** Experimental. Disabled by default in production.
+
+### tagged_subqueries
+
+Subqueries create dependency trees between shapes. Without this flag, when data moves into or out of a dependent shape, the shape is invalidated (returning a 409). With this flag enabled, move operations are handled correctly without invalidation.
+
+See [discussion #2931](https://github.com/electric-sql/electric/discussions/2931) for more details about this feature.
+
+**Status:** Experimental. Disabled by default in production. Requires `allow_subqueries` to be enabled.
+
 ## Caching
 
 ### ELECTRIC_CACHE_MAX_AGE