feat: add my comments

Author: akshitsinha

src/content/docs/flagship/concepts.mdx

@@ -5,7 +5,7 @@ sidebar:
   order: 3
 ---
 
-Flagship organizes feature flags into apps. You define flags with variations and targeting rules, then evaluate them at the edge with low latency.
+Flagship organizes feature flags into apps. You define flags with variations and targeting rules, then evaluate them at the edge.
 
 ## How it works
 
@@ -83,7 +83,7 @@ Each rule contains:
 - An optional **percentage rollout** that splits traffic across variations.
 - A **variation** to serve when the rule matches.
 
-Conditions within a rule can be grouped with `AND`/`OR` operators and nested up to six levels deep.
+Conditions within a rule can be grouped with `AND`/`OR` operators.
 
 Refer to [Targeting rules](/flagship/targeting/) and [Operators](/flagship/targeting/operators/) for the full list of operators and configuration options.
 
@@ -110,4 +110,4 @@ When you change a flag in the dashboard, the change propagates globally within s
 
 During the brief propagation window, some regions may still serve the previous flag value. After propagation completes, all subsequent evaluations return the updated value.
 
-This model is optimized for low-latency evaluation at the edge. You do not need to redeploy your Worker or restart your application to pick up flag changes.
+You do not need to redeploy your Worker or restart your application to pick up flag changes.

src/content/docs/flagship/index.mdx

@@ -18,7 +18,7 @@ import {
 
 <Description>
 
-Evaluate feature flags at the edge with low latency in Cloudflare Workers.
+Evaluate feature flags at the edge in Cloudflare Workers.
 
 </Description>
 
@@ -78,7 +78,7 @@ Build serverless applications on Cloudflare's global network. Flagship integrate
 
 <RelatedProduct header="KV" href="/kv/" product="kv">
 
-Store key-value data at the edge. Flagship uses Cloudflare's global infrastructure to deliver flag configurations with low latency.
+Store key-value data at the edge. Flagship uses Cloudflare's global infrastructure to deliver flag configurations.
 
 </RelatedProduct>
 

src/content/docs/flagship/reference/limits.mdx

@@ -13,7 +13,7 @@ Flagship enforces the following limits.
 | ------------------------------- | -------- |
 | Apps per account                | 10,000   |
 | Flags per app                   | 5,000    |
-| Condition nesting depth         | 6 levels |
+
 | Flag configuration size per app | 25 MB    |
 
 :::note
@@ -22,5 +22,4 @@ The apps-per-account and flags-per-app limits are soft limits. If your use case
 
 ## Notes
 
-- Condition nesting depth counts from the top-level condition group. A flat list of conditions (no nesting) has a depth of 1.
 - Flag configuration size refers to the total serialized size of all flags within a single app, including their variations and rules.

src/content/docs/flagship/sdk/client-provider.mdx

@@ -5,17 +5,27 @@ sidebar:
   order: 2
 ---
 
-The `FlagshipClientProvider` implements the OpenFeature web provider interface for browser applications. It pre-fetches all flag values on initialization and resolves evaluations synchronously from an in-memory cache.
+The `FlagshipClientProvider` implements the OpenFeature web provider interface for browser applications. It pre-fetches a declared set of flag values on initialization and resolves evaluations synchronously from an in-memory cache.
 
 This makes the provider suitable for client-side rendering where synchronous access to flag values is required.
 
 :::caution[Important]
 The client provider requires an API token to fetch flag values. This token is not scoped to a single app, so anyone with the token can **evaluate flags** across all apps in your account. App-scoped tokens are coming soon. Until then, use the client provider with caution in public-facing applications.
 :::
 
+## prefetchFlags
+
+`prefetchFlags` is a required array of flag keys that the provider fetches during initialization and on every context change. Only flags listed in this array are available for synchronous evaluation — any flag key not included returns a `FLAG_NOT_FOUND` error at resolution time.
+
+**Fetch behavior:**
+
+- **On initialization** — all flags in `prefetchFlags` are fetched in parallel and stored in an in-memory cache. The provider transitions to `READY` once all fetches complete (individual failures are non-fatal).
+- **On context change** — the cache is invalidated and all flags are re-fetched for the new context. This is required by the [static context paradigm](https://openfeature.dev/specification/glossary/#static-context-paradigm) used by the OpenFeature web SDK, where context is set globally and providers are expected to re-evaluate when it changes.
+- **At resolution time** — evaluations are served synchronously from the cache. No network request is made during `getBooleanValue`, `getStringValue`, etc.
+
 ## Setup
 
-The following example initializes the provider and evaluates a flag in a browser application.
+The following example initializes the provider with a set of pre-fetched flags and evaluates them in a browser application.
 
 ```ts
 import { OpenFeature } from "@openfeature/web-sdk";
@@ -26,14 +36,18 @@ await OpenFeature.setProviderAndWait(
 		appId: "your-app-id",
 		accountId: "your-account-id",
 		authToken: "your-api-token",
+		prefetchFlags: ["promo-banner", "dark-mode", "max-uploads"],
 	}),
 );
 
+// Set evaluation context globally. The provider re-fetches all prefetchFlags
+// whenever the context changes.
+await OpenFeature.setContext({ targetingKey: "user-42", plan: "enterprise" });
+
 const client = OpenFeature.getClient();
 
-const showBanner = client.getBooleanValue("promo-banner", false, {
-	targetingKey: "user-42",
-});
+// Synchronous — served from the in-memory cache.
+const showBanner = client.getBooleanValue("promo-banner", false);
 
 if (showBanner) {
 	document.getElementById("banner").style.display = "block";
@@ -46,14 +60,15 @@ if (showBanner) {
 
 ## Configuration options
 
-| Option      | Type     | Required | Description                                                                                           |
-| ----------- | -------- | -------- | ----------------------------------------------------------------------------------------------------- |
-| `appId`     | `string` | Yes      | The Flagship app ID from the Cloudflare dashboard.                                                    |
-| `accountId` | `string` | Yes      | Your Cloudflare account ID.                                                                           |
-| `authToken` | `string` | Yes      | A Cloudflare [API token](/fundamentals/api/get-started/create-token/) with Flagship read permissions. |
+| Option          | Type       | Required | Description                                                                                           |
+| --------------- | ---------- | -------- | ----------------------------------------------------------------------------------------------------- |
+| `appId`         | `string`   | Yes      | The Flagship app ID from the Cloudflare dashboard.                                                    |
+| `accountId`     | `string`   | Yes      | Your Cloudflare account ID.                                                                           |
+| `authToken`     | `string`   | Yes      | A Cloudflare [API token](/fundamentals/api/get-started/create-token/) with Flagship read permissions. |
+| `prefetchFlags` | `string[]` | Yes      | Flag keys to fetch on initialization and on every context change. Flags not in this list return `FLAG_NOT_FOUND` at evaluation time. |
 
 ## When to use the client provider
 
 Use the client provider in browser applications, single-page apps, or any client-side JavaScript environment.
 
-Evaluations are synchronous, so they do not block rendering. Flag values are fetched once during initialization. To refresh flag values, re-initialize the provider.
+Evaluations are synchronous, so they do not block rendering. Flag values are fetched once during initialization and re-fetched whenever the evaluation context changes. To force a refresh, update the context via `OpenFeature.setContext(...)`.

src/content/docs/flagship/targeting/index.mdx

@@ -31,15 +31,32 @@ Each condition compares an attribute from the evaluation context against a value
 
 ## Logical grouping
 
-Conditions within a rule can be grouped using `AND`/`OR` logical operators. Groups can be nested up to six levels deep for complex targeting logic.
+Conditions within a rule are combined with `AND` and `OR` operators. The grouping follows a simple rule: **`OR` starts a new group, `AND` stays in the current group**. Equivalently, `AND` binds tighter than `OR`.
 
-For example, to target enterprise users in the US or Canada:
+You can think of the condition list as being split at every `OR` boundary. Each segment between `OR`s forms its own group, and all `AND`s inside that segment belong to the same group. The rule matches when any one group matches entirely.
 
-- `AND`:
-  - `plan equals "enterprise"`
-  - `OR`:
-    - `country equals "US"`
-    - `country equals "CA"`
+For example:
+
+```
+IF   country IN ["US", "CA"]
+AND  plan equals "enterprise"
+OR   email ends_with "cloudflare.com"
+OR   beta_tester equals true
+AND  user_age_days > 30
+```
+
+This evaluates as:
+
+```
+(country IN ["US", "CA"] AND plan equals "enterprise")
+OR (email ends_with "cloudflare.com")
+OR (beta_tester equals true AND user_age_days > 30)
+```
+
+The rule matches users who are either:
+- in the US or Canada **and** on the enterprise plan, or
+- using a `cloudflare.com` email address, or
+- a beta tester **and** have been a user for more than 30 days.
 
 ## Learn more
 

src/content/docs/flagship/targeting/percentage-rollouts.mdx

@@ -17,6 +17,12 @@ Flagship uses consistent hashing on a configurable attribute to assign users to
 
 By default, the bucketing attribute is `targetingKey`. You can configure which attribute to use for bucketing when you set up the rollout in the dashboard.
 
+:::caution[Random assignment without targetingKey]
+If `targetingKey` is not present in the evaluation context and no alternative bucketing attribute is configured, Flagship cannot produce a stable hash. In this case the rollout bucket is assigned randomly on each evaluation, meaning the same user may receive different flag values across requests.
+
+Always provide a stable `targetingKey` (or configure a consistent bucketing attribute) to guarantee sticky bucketing.
+:::
+
 ## Example
 
 Consider a flag `new-checkout` with the following rules: