@picked/client 0.0.70-next.6 → 0.0.70

package/dist/docs/sdk/feature-allocation.md

@@ -4,87 +4,108 @@ layout: docs
 
 # Allocation and exposure
 
-Reading a feature flag's bucket is what allocates a visitor to it. This page covers when that happens, how to observe it, and how to make sure a visitor is allocated before you report on it.
+A read of the bucket of a feature flag is what allocates a visitor to that feature flag. This
+page covers when that happens and how to watch it. It also covers how to be sure that
+Picked allocates a visitor before you report on that visitor.
 
-## Registering a feature flag is not deciding it
+## A registration is not a decision
 
-The SDK loads every feature flag in your project at startup, but it does not allocate visitors then. A feature flag stays undecided until something reads its bucket. The first read runs the `decide` function, stores the result, and reports the decision.
+The SDK loads every feature flag in your project at startup, but it allocates no visitor
+then. A feature flag stays undecided until something reads its bucket. The first read runs the
+`decide` function, stores the result, and reports the decision.
 
-That means you choose when a visitor is committed to a feature flag, simply by choosing when you read it.
+You therefore choose when Picked commits a visitor to a feature flag. You choose it by the
+point at which you read the feature flag.
 
-## Reading a bucket records an exposure
+## A read of a bucket records an exposure
 
-Because the first read is the decision, reading a bucket is the moment the visitor enters the test. Read every feature flag at startup and every visitor counts as exposed to every test, including ones they never reached.
+The first read is the decision, so a read of a bucket is the moment when the visitor
+enters the test. If you read every feature flag at startup, every visitor counts as exposed
+to every test. This includes a test that the visitor never reached.
 
 :::warning
-Avoid looping over every feature flag at startup to read its bucket. It commits every visitor to every test immediately and removes your ability to defer a decision until the data it depends on has arrived.
+Do not loop over every feature flag at startup to read its bucket. That commits every visitor
+to every test immediately. You then have no way to wait for the data that a decision
+needs.
 :::
 
-Read a feature flag at the point the decision matters — after the cart loads, after the quote returns, after you know who the visitor is.
+Read a feature flag at the point where the decision matters. That is after the cart loads,
+after the quote returns, or after you know who the visitor is.
 
-## Inspecting feature flags without deciding them
+## Check a feature flag without a decision
 
-`client.features.listStore` holds every registered feature flag. Each entry reports whether it has been decided yet, so you can inspect feature flags without committing anyone:
+`client.features.listStore` holds every registered feature flag. Each entry reports whether
+the feature flag is decided yet, so you can check a feature flag and commit nobody:
 
 ```ts
-for (const flag of client.features.listStore.getState()) {
-  console.log(flag.id, flag.isResolved)
+for (const feature flag of client.features.listStore.getState()) {
+  console.log(feature flag.id, feature flag.isResolved)
 }
 ```
 
-`getBucket()` behaves differently depending on that state:
+`getBucket()` behaves differently for each state:
 
-- **Resolved** — returns `{ id, bucket }` synchronously. Reading it changes nothing.
-- **Not resolved** — returns a promise. Awaiting it runs `decide` and commits the visitor.
+- **Resolved** — it returns `{ id, bucket }` at once. The read changes nothing.
+- **Not resolved** — it returns a promise. An `await` runs `decide` and commits the
+  visitor.
 
-`await` works for both, so you can treat them uniformly when you do intend to decide.
+`await` works for both states, so you can treat them the same way when you do intend
+to decide.
 
 ## When `feature_decide` fires
 
-A `feature_decide` event is emitted the first time a feature flag is decided for a visitor — and only then.
+The SDK sends a `feature_decide` event the first time that it decides a feature flag for a
+visitor, and only then.
 
 :::warning
-On later page loads the decision is restored from browser storage, and **no event is emitted**. A returning visitor produces no `feature_decide` events at all, even though they are still allocated.
+On a later page load the SDK restores the decision from browser storage, and it
+sends **no event**. A visitor who returns produces no `feature_decide` event at all,
+although Picked still allocates that visitor.
 
-An integration built only on `feature_decide` will therefore report nothing for returning visitors.
+An integration that reads only `feature_decide` therefore reports nothing for a
+visitor who returns.
 :::
 
-Use the right source for the question you are asking:
+Use the correct source for your question:
 
 | Question | Use |
 | --- | --- |
-| What is this visitor allocated to right now? | `client.features.listStore` |
-| Was a new decision just made? | `feature_decide` on `client.eventBus` |
-| What decisions happened before I subscribed? | `client.events` |
+| What is this visitor allocated to now? | `client.features.listStore` |
+| Did the SDK make a new decision? | `feature_decide` on `client.eventBus` |
+| Which decisions happened before I subscribed? | `client.events` |
 
-## Observing decisions
+## Watch for decisions
 
-`listStore` updates whenever a feature flag resolves, whether it was restored from storage or decided just now. Watching it gives you the current picture at all times:
+`listStore` updates each time that a feature flag resolves. It does this whether the SDK
+restored the feature flag from storage or decided it now. A watch on `listStore` therefore
+always gives you the current state:
 
 ```ts
 const buckets = new Map<string, string | boolean>()
 
-client.features.listStore.watch((flags) => {
-  for (const flag of flags) {
-    if (!flag.isResolved) continue
-    buckets.set(flag.id, flag.getBucket().bucket)
+client.features.listStore.watch((feature flags) => {
+  for (const feature flag of feature flags) {
+    if (!feature flag.isResolved) continue
+    buckets.set(feature flag.id, feature flag.getBucket().bucket)
   }
 })
 ```
 
-Use `feature_decide` when you need to know a decision was *made*, rather than what the current value is — for example to send your own exposure event:
+Use `feature_decide` when you need to know that the SDK *made* a decision, and not
+what the current value is. An example is your own exposure event:
 
 ```ts
 client.eventBus.watch((event) => {
   if (event.type !== 'feature_decide') return
   analytics.track('Experiment exposure', {
-    flag: event.feature.id,
+    feature flag: event.feature.id,
     bucket: event.feature.bucket,
   })
 })
 ```
 
-If you subscribe after startup, earlier events are still available. `client.events` holds every event fired since the client initialised:
+An earlier event is still available when you subscribe after startup. `client.events`
+holds every event since the client started:
 
 ```ts
 const earlier = client.events
@@ -92,38 +113,49 @@ const earlier = client.events
   .filter((entry) => entry.payload.type === 'feature_decide')
 ```
 
-## Deciding before you report
+## Decide before you report
 
-To guarantee a feature flag is decided before a downstream event fires, await it first:
+To be sure that the SDK decides a feature flag before a later event fires, `await` the feature flag
+first:
 
 ```ts
-const flag = client.features.getById('quote-experiment').getState()
+const feature flag = client.features.getById('quote-experiment').getState()
 
-if (flag) {
-  const { bucket } = await flag.getBucket()
+if (feature flag) {
+  const { bucket } = await feature flag.getBucket()
   trackViewQuote({ experiment: bucket })
 }
 ```
 
-Awaiting `getBucket()` resolves the feature flag if it has not been decided, and returns the stored value if it has. Either way the bucket is known before the next line runs.
+An `await` on `getBucket()` resolves the feature flag when it is undecided, and returns the
+stored value when it is decided. In both cases the bucket is known before the next
+line runs.
 
-## What Picked already reports
+## What Picked reports for you
 
-Before building your own tracking, note what the SDK sends already.
+Read this before you build a report of your own.
 
-Every Picked analytics event carries a `feature_list` context describing the feature flags this visitor has resolved:
+Every Picked analytics event carries a `feature_list` context. The context describes
+each feature flag that this visitor resolved:
 
 | Field | Description |
 | --- | --- |
-| `ab_feature` | Feature flag ID |
-| `ab_name` | Feature flag name |
-| `ab_key` | Version key, such as `v3` |
+| `ab_feature` | The feature flag ID |
+| `ab_name` | The feature flag name |
+| `ab_key` | The version key, such as `v3` |
 | `ab_bucket` | The resolved bucket |
 
-Only resolved feature flags appear, so the context reflects what the visitor was actually exposed to at the time the event fired.
+Only a resolved feature flag appears there. The context therefore shows what the visitor was
+exposed to at the time when the event fired.
 
-If the [Sentry plugin](https://www.npmjs.com/package/@picked/sentry) is installed, each decision also tags the Sentry scope as `picked.feature.<flag-id>` with the bucket as the value, so errors can be filtered by variant.
+The [Sentry plugin](https://www.npmjs.com/package/@picked/sentry) is optional. When
+it is installed, each decision also tags the Sentry scope as
+`picked.feature.<feature flag-id>`, with the bucket as the value. You can then filter your
+errors by the variant.
 
 ## Preview mode
 
-In [preview mode](/workspaces#preview) decisions are stored in session storage rather than local storage. They do not persist beyond the tab, and a preview visitor may be allocated differently from a production visitor. Treat preview allocations as disposable.
+In [preview mode](/workspaces#preview) the SDK stores a decision in session storage
+and not in local storage. The decision does not stay after you close the tab, and
+Picked can allocate a preview visitor differently from a production visitor. Treat a
+preview allocation as disposable.

package/dist/docs/sdk/features.md

@@ -4,29 +4,40 @@ layout: docs
 
 # Feature flags
 
-Feature flags let you run A/B tests and roll changes out gradually. Manage them from the dashboard, or define them in SDK code when you need your own decision logic.
+A feature flag lets you run an A/B test and roll a change out in stages. Control a
+feature flag from the dashboard, or define it in SDK code when you need your own decision
+rules.
 
 ## Where feature flags come from
 
-Most feature flags are managed from the dashboard. The [dynamic experiences plugin](/sdk/plugins/dynamic-experiences) fetches your project configuration at runtime and registers every feature flag automatically — you do not declare them in code.
+You control most feature flags from the dashboard. The
+[dynamic experiences plugin](/sdk/plugins/dynamic-experiences) reads the options of
+your project at runtime and registers every feature flag for you. You declare no feature flag in
+code.
 
-For a dashboard-managed feature flag, the SDK generates the definition:
+For a feature flag that you control from the dashboard, the SDK makes the definition:
 
 | Field | Value |
 | --- | --- |
-| `id` | The feature flag's dashboard key |
-| `key` | `v{version}` — for example `v3` |
-| `name` | The feature flag's dashboard name |
+| `id` | The dashboard key of the feature flag |
+| `key` | `v{version}`, for example `v3` |
+| `name` | The dashboard name of the feature flag |
 | `enabled` | The dashboard **Enabled** toggle |
-| `weight` | The dashboard **Weight**, 0–100 |
+| `weight` | The dashboard **Weight**, 0 to 100 |
 | `storage` | `local`, or `session` in [preview mode](/sdk/feature-allocation#preview-mode) |
-| `decide` | Generated — allocates by comparing the visitor's stable value for this feature flag against `weight` |
+| `decide` | Made by the SDK. It compares the stable value of the visitor for this feature flag against `weight`. |
 
-The generated `decide` derives from the visitor ID, the feature flag ID, and the weight alone, so a dashboard-managed feature flag cannot base its decision on your application's data. Define the feature flag in SDK code when you need that.
+The `decide` function that the SDK makes derives from the visitor ID, the ID of the
+feature flag, and the weight. A feature flag that you control from the dashboard
+therefore cannot use the data of your application. Define the feature flag in SDK code
+when you need that.
 
-## Defining feature flags in SDK code
+## Define a feature flag in SDK code
 
-Define feature flags when creating the Picked client by passing a `features` object. Use this when a decision depends on data only your application has. Each feature flag requires a unique identifier, a versioning key, a human-readable name, and a `decide` function:
+Define your feature flags when you create the Picked client. Pass a `features` object. Use
+this when a decision needs data that only your application holds. Each feature flag needs a
+unique identifier, a version key, a name that a person can read, and a `decide`
+function:
 
 ```ts
 import { createClient } from '@picked/client'
@@ -35,20 +46,20 @@ const client = createClient({
   projectId: 'your-project-id',
   features: {
     'summer-sale': {
-      key: 'summer-sale-v1', // Version key - change to invalidate cache
-      name: 'Summer Sale Experiment', // Human-readable name for analytics
+      key: 'summer-sale-v1', // The version key. Change it to invalidate the cache.
+      name: 'Summer Sale Experiment', // A name for analytics that a person can read.
       decide: async () => {
-        // Your decision logic here
+        // Put your decision rules here.
         const isEligible = await checkUserEligibility()
-        return isEligible // Returns boolean
+        return isEligible // Returns a boolean.
       },
-      storage: 'local', // Optional: 'local' (default) or 'session'
+      storage: 'local', // Optional: 'local' is the default, or 'session'.
     },
     'homepage-variant': {
       key: 'homepage-test-v2',
       name: 'Homepage A/B Test',
       decide: async () => {
-        // Return string for multi-variant tests
+        // Return a string for a test of more than two variants.
         return Math.random() < 0.5 ? 'variant-a' : 'variant-b'
       },
     },
@@ -56,7 +67,8 @@ const client = createClient({
 })
 ```
 
-Feature flags can also be defined as factory functions for lazy initialization:
+A feature flag can also be a factory function, which starts the feature flag only when it is
+first needed:
 
 ```ts
 features: {
@@ -70,25 +82,33 @@ features: {
 
 ## How feature flags work
 
-When a feature flag is registered, the SDK follows this execution order:
+After you register a feature flag, the SDK follows this order:
 
-1. **Registration** — feature flags are registered with the client at startup. Registering does not allocate anyone.
-2. **Cache check** — the SDK looks in browser storage for a decision from a previous visit, keyed by the feature flag `id` and `key`. If one exists the feature flag starts out already resolved, which is why a returning visitor is allocated before anything reads the feature flag.
-3. **Lazy evaluation** — with no cached decision, `decide` runs the first time something reads the bucket.
-4. **Storage** — the resolved bucket is written to browser storage.
-5. **Event emission** — a `feature_decide` event fires, but only for a decision made during this page view. A decision restored in step 2 emits nothing.
+1. **Registration** — the client registers each feature flag at startup. A registration
+   allocates nobody.
+2. **Cache check** — the SDK looks in browser storage for a decision from an earlier
+   visit. The cache key holds the feature flag `id` and `key`. When an entry is there, the
+   feature flag starts in a resolved state. This is why Picked allocates a visitor who
+   returns before anything reads the feature flag.
+3. **Lazy evaluation** — with no cached decision, `decide` runs the first time that
+   something reads the bucket.
+4. **Storage** — the SDK writes the resolved bucket to browser storage.
+5. **Event emission** — the SDK sends a `feature_decide` event, but only for a
+   decision that it makes during this page view. A decision that step 2 restores
+   sends nothing.
 
-See [Allocation and exposure](/sdk/feature-allocation) for what this means when tracking exposures.
+See [Allocation and exposure](/sdk/feature-allocation) for what this means when you
+track an exposure.
 
-## URL-based overrides
+## Overrides in the URL
 
-You can override feature flag decisions via URL search parameters for testing purposes:
+You can override a feature flag decision from the URL search parameters, for a test:
 
 ```
 https://example.com?picked-feature=my-feature:true
 ```
 
-Multiple overrides can be specified:
+You can give more than one override value:
 
 ```
 https://example.com?picked-feature=my-feature:true&picked-feature=homepage-variant:variant-a
@@ -96,11 +116,15 @@ https://example.com?picked-feature=my-feature:true&picked-feature=homepage-varia
 
 The format is `?picked-feature=<feature-id>:<bucket-value>`.
 
-This is useful for QA testing specific bucket values without modifying code. The override is persisted in session storage and will be cleared when the browser tab is closed.
+This is useful for QA, because you can test one bucket value and change no code. The
+SDK keeps the override value in session storage. The browser clears it when you close
+the tab.
 
-## Accessing feature flags
+## Read a feature flag
 
-Once feature flags are defined, you can read their resolved bucket values in your application code. The SDK provides framework hooks and a framework-agnostic event bus.
+After you define your feature flags, your application code can read the resolved
+bucket value of each one. The SDK gives you a hook for each framework, and an event
+bus that works with any framework.
 
 :::code-group
 
@@ -108,7 +132,7 @@ Once feature flags are defined, you can read their resolved bucket values in you
 import { createClient } from '@picked/client'
 
 const client = createClient({
-  /* Create client options here */
+  /* Put your client options here. */
 })
 
 client.eventBus.watch((event) => {
@@ -122,7 +146,7 @@ client.eventBus.watch((event) => {
 <script lang="ts">
   import { getFeatureResult } from '@picked/svelte/hooks'
 
-  // A store holding { id, bucket }, or undefined until the flag resolves
+  // A store that holds { id, bucket }, or undefined until the feature flag resolves.
   const result = getFeatureResult('my-feature')
 </script>
 
@@ -137,7 +161,7 @@ client.eventBus.watch((event) => {
 import { useFeatureResult } from '@picked/react/hooks'
 
 function MyComponent() {
-  // { id, bucket }, or undefined until the flag resolves
+  // { id, bucket }, or undefined until the feature flag resolves.
   const result = useFeatureResult('my-feature')
 
   return (
@@ -151,41 +175,46 @@ function MyComponent() {
 
 :::
 
-### Choosing an accessor
+### Choose an accessor
 
-Accessors differ in what they return, and in whether reading one resolves the feature flag. Resolving is what commits a visitor to a bucket and reports the decision — see [Allocation and exposure](/sdk/feature-allocation).
+Each accessor returns a different value. They also differ in whether a read resolves
+the feature flag. A read that resolves the feature flag commits the visitor to a bucket and reports
+the decision. See [Allocation and exposure](/sdk/feature-allocation).
 
-| API | Returns | Resolves the feature flag? |
+| API | Returns | Does a read resolve the feature flag? |
 | --- | --- | --- |
-| `useFeature` / `getFeature` | `() => Promise<bucket>` | Only when you call the returned function |
-| `useFeatureResult` / `getFeatureResult` | `{ id, bucket }`, `undefined` until resolved | Yes, as soon as the component renders |
-| `useFeatureEnabled` / `getFeatureEnabled` | `boolean \| undefined` — the dashboard **Enabled** toggle | No |
-| `client.features.listStore` | Every registered feature flag, each with an `isResolved` boolean | No |
-| `client.features.getById(id)` | A store holding a single feature flag | No |
+| `useFeature` / `getFeature` | `() => Promise<bucket>` | Only when you call the function that it returns |
+| `useFeatureResult` / `getFeatureResult` | `{ id, bucket }`, and `undefined` until it resolves | Yes, as soon as the component renders |
+| `useFeatureEnabled` / `getFeatureEnabled` | `boolean \| undefined`, the dashboard **Enabled** toggle | No |
+| `client.features.listStore` | Every registered feature flag, each with an `isResolved` feature flag | No |
+| `client.features.getById(id)` | A store that holds one feature flag | No |
 
 :::warning
-`useFeatureResult` and `getFeatureResult` resolve the feature flag as soon as the component renders, committing the visitor to a bucket at that moment.
+`useFeatureResult` and `getFeatureResult` resolve the feature flag as soon as the component
+renders. They commit the visitor to a bucket at that moment.
 
-If the decision should wait for data you do not have yet — a cart, a quote, a signed-in profile — use `useFeature` or `getFeature` and call the function they return once that data arrives.
+Some decisions must wait for data that you do not have yet, such as a cart, a quote,
+or a profile of a signed-in user. For those, use `useFeature` or `getFeature`. Call
+the function that they return after the data arrives.
 :::
 
-## Using feature flags in experience conditions
+## Use a feature flag in an experience condition
 
-Feature flags can be used with experience conditions via JSON logic:
+You can use a feature flag in an experience condition through JSON logic:
 
 ```ts
 const myExperience = createExperience({
-  // ... other config
+  // The other options go here.
   condition: {
     and: [
       {
         '==': [
           {
             invoke: {
-              var: 'features.summer-sale', // Reference the flag by ID
+              var: 'features.summer-sale', // Point at the feature flag by its ID.
             },
           },
-          true, // Check if bucket equals true
+          true, // Check that the bucket equals true.
         ],
       },
     ],
@@ -193,13 +222,15 @@ const myExperience = createExperience({
 })
 ```
 
-The ID in `features.<id>` is the feature flag's **Key** from the dashboard — the same value shown on the feature flag detail page.
+The ID in `features.<id>` is the **Key** of the feature flag from the dashboard. It is the
+same value that the detail page of the feature flag shows.
 
-Evaluating a condition reads the bucket, so a feature flag referenced by an experience condition is allocated at the moment that condition runs.
+An evaluation of a condition reads the bucket. Picked therefore allocates a visitor
+to a feature flag when the condition that points at it runs.
 
-## Listening to feature flag decisions
+## Watch for feature flag decisions
 
-Subscribe to the `feature_decide` event to track when feature flags are resolved:
+Subscribe to the `feature_decide` event to track when a feature flag resolves:
 
 ```ts
 client.eventBus.watch((event) => {
@@ -207,9 +238,9 @@ client.eventBus.watch((event) => {
 
   const { feature } = event
   console.log(`Flag "${feature.id}" resolved to bucket:`, feature.bucket)
-  // Example output: Flag "summer-sale" resolved to bucket: true
+  // Example output: the feature flag resolved to the bucket true.
 
-  // Send to analytics
+  // Send the decision to your analytics.
   analytics.track('Feature Decision', {
     featureId: feature.id,
     bucket: feature.bucket,
@@ -217,50 +248,73 @@ client.eventBus.watch((event) => {
 })
 ```
 
-## Versioning and cache invalidation
+## Versions and cache invalidation
 
-Feature flag decisions are cached in browser storage (localStorage, or sessionStorage in preview) under a key derived from the feature flag ID and version, so a visitor keeps the same decision across page loads.
+The SDK caches a feature flag decision in browser storage. It uses `localStorage`, or
+`sessionStorage` in a preview. The cache key derives from the feature flag ID and the version,
+so a visitor keeps the same decision across page loads.
 
 :::warning
-Bucket values that are strings, such as `'variant-a'`, are not yet restored correctly from storage — the visitor is treated as unallocated on their next page load. Boolean bucket values, which includes every feature flag managed from the dashboard, are unaffected. Tracked in PICK-1574.
+The SDK does not yet restore a string bucket value, such as `'variant-a'`, correctly
+from storage. It treats the visitor as unallocated on the next page load. A boolean
+bucket value is correct, and that includes every feature flag that you control from the
+dashboard. See PICK-1574.
 :::
 
-### How versioning works
+### How versions work
 
-When you create a feature flag in the dashboard, it starts at version 1. The SDK uses the version to build the cache key — for example, a feature flag at version 3 caches under `v3`.
+A feature flag that you create in the dashboard starts at version 1. The SDK uses the
+version to build the cache key. A feature flag at version 3 caches under `v3`.
 
-The version affects **caching only**. It is not part of the allocation calculation, which for dashboard-managed feature flags derives from the visitor ID, the feature flag ID, and the feature flag's weight.
+The version affects **the cache only**. It is not part of the allocation. For a feature flag
+that you control from the dashboard, the allocation derives from the visitor ID and
+the weight of the feature flag.
 
-### What happens when the version is incremented
+### What happens when you increment the version
 
-When you increment a feature flag's version in the dashboard:
+When you increment the version of a feature flag in the dashboard:
 
-1. **Cache keys change.** The old cache entry (e.g., `v3`) no longer matches the new key (`v4`), so the SDK treats the feature flag as undecided.
-2. **The `decide` function runs again.** On the next page load, the SDK calls `decide()` fresh and caches the new result.
-3. **Visitors are re-evaluated, not reshuffled.** For dashboard-managed feature flags allocation is deterministic, so re-evaluating the same visitor against an unchanged weight produces the same bucket.
+1. **The cache key changes.** The old entry, `v3`, no longer matches the new key,
+   `v4`. The SDK therefore treats the feature flag as undecided.
+2. **The `decide` function runs again.** On the next page load, the SDK calls
+   `decide()` again and caches the new result.
+3. **Picked evaluates each visitor again and moves nobody.** For a feature flag that you
+   control from the dashboard the allocation is deterministic. The same visitor
+   against an unchanged weight gives the same bucket.
 
 :::note
-Incrementing the version clears cached decisions and runs allocation again. It does not randomise visitors — with an unchanged weight, everyone lands where they were. Increment it after changing a weight, so visitors who already hold a cached decision are re-evaluated against the new one.
+The new version clears the cached decisions and runs the allocation again. It moves
+no visitor between groups. With an unchanged weight, everybody lands where they were.
+Increment the version after you change a weight, so that Picked evaluates a visitor
+with a cached decision against the new weight.
 :::
 
-### SDK `key` vs dashboard version
+### The SDK `key` and the dashboard version
 
-If you define feature flags statically in the SDK (not loaded from the dashboard), use the `key` field for manual versioning:
+For a feature flag that you define in SDK code, use the `key` field to set the version
+yourself. This applies when you do not read the feature flag from the dashboard:
 
 ```ts
 features: {
   'summer-sale': {
-    key: 'summer-sale-v2', // Change to invalidate cache
-    // ...
+    key: 'summer-sale-v2', // Change this to invalidate the cache.
+    // The other options go here.
   },
 }
 ```
 
-For feature flags managed through the dashboard, versioning is handled automatically — the dashboard appends the version number to the cache key used by the SDK.
+For a feature flag that you control from the dashboard, Picked sets the version for you. The
+dashboard adds the version number to the end of the cache key that the SDK uses.
 
 ## Best practices
 
-- **Use `session` storage for temporary tests**: Set `storage: 'session'` for short-lived experiments that shouldn't persist across browser sessions
-- **Keep `decide` functions fast**: Anything awaiting the feature flag — an experience condition, a component reading the result — waits for `decide` to finish, so avoid slow network calls inside it
-- **Allocate when the decision matters**: Defer reading a feature flag until the data it depends on has arrived, rather than reading every feature flag at startup. See [Allocation and exposure](/sdk/feature-allocation)
-- **Return consistent types**: Don't mix boolean and string returns for the same feature flag - pick one type and stick with it
+- **Use `session` storage for a short test**: set `storage: 'session'` for an
+  experiment that must not stay across browser sessions.
+- **Keep each `decide` function fast**: everything that waits for the feature flag waits for
+  `decide` to finish. This includes an experience condition and a component that
+  reads the result. Do not make a slow network call inside it.
+- **Allocate when the decision matters**: read a feature flag only after the data that it
+  needs arrives. Do not read every feature flag at startup. See
+  [Allocation and exposure](/sdk/feature-allocation).
+- **Return one type**: do not return a boolean from a feature flag one time and a string the
+  next. Choose one type and keep it.