Clarify managed variables docs

Author: strawgate

docs/how-to-guides/client-side-feature-flags.md

@@ -6,7 +6,7 @@ This guide shows how to set up a **JavaScript/TypeScript web application** using
 
 ## Prerequisites
 
-1. **Create your variables** in the Logfire UI (Settings > Variables) and mark them as **external** — see [External Variables and OFREP](../reference/advanced/managed-variables/external.md)
+1. **Create your variables** in the Logfire UI (**Runtime > Managed Variables**) and mark them as **External** — see [External Variables and OFREP](../reference/advanced/managed-variables/external.md)
 2. **Create an API key** with the `project:read_external_variables` scope — this restricted scope is safe to use in client-side code since it only exposes variables you've explicitly marked as external
 
 ## Installation

docs/reference/advanced/managed-variables/external.md

@@ -8,7 +8,7 @@ There are two fundamentally different ways to read managed variables, and the ch
 
 ### Pull-Based (Logfire SDK)
 
-When you use `logfire.variable.get()` (or the `.get()` method on a variable created with `logfire.var()`), the SDK **pulls the full variable configuration** from the server and evaluates it locally:
+When you call `.get()` on a variable created with `logfire.var()`, the SDK **pulls the full variable configuration** from the server and evaluates it locally:
 
 1. The SDK fetches all variable definitions, versions, labels, and rollout rules in a single request
 2. A background thread polls for updates (or listens via SSE)
@@ -26,7 +26,7 @@ The OFREP endpoints take a different approach — every evaluation is a **server
 2. The server evaluates the variable using the context and returns only the resolved value
 3. The client never sees the full configuration, other versions, or rollout rules
 
-This is less efficient (one network request per evaluation or batch), but the full configuration is **never exposed** to the client. A client would have to brute-force individual keys to discover what variables exist.
+This is less efficient (one network request per evaluation or batch), but the full configuration is **never exposed** to the client. Single-flag evaluation returns only the requested variable's resolved value, while bulk evaluation returns resolved values for the variables the token is allowed to access.
 
 **Requires:** `project:read_variables` or `project:read_external_variables` scope.
 
@@ -46,7 +46,7 @@ By default, variables are **internal** — they are only accessible with an API
 | `project:write_variables` | Create, update, and delete variables and variable types |
 
 !!! warning "API key scope and SDK access"
-    An API key with only the `project:read_external_variables` scope **cannot be used with `logfire.variable.get()`** or any of the pull-based SDK variable methods. The SDK's pull-based approach requires `project:read_variables` because it fetches the full configuration. The `project:read_external_variables` scope only grants access to the OFREP evaluation endpoints.
+    An API key with only the `project:read_external_variables` scope **cannot be used with `.get()` on variables created with `logfire.var()`** or any of the pull-based SDK variable methods. The SDK's pull-based approach requires `project:read_variables` because it fetches the full configuration. The `project:read_external_variables` scope only grants access to the OFREP evaluation endpoints.
 
 ### Setting a Variable as External
 
@@ -103,7 +103,7 @@ POST /v1/ofrep/v1/evaluate/flags
 
 - `targetingKey` is required and is used for deterministic rollout selection.
 - Any additional fields in `context` become attributes for conditional rules.
-- The OFREP response maps labels to the `variant` field for compatibility with OpenFeature clients.
+- The OFREP response maps the selected label or target to the `variant` field for compatibility with OpenFeature clients. For example, the variant can be a label such as `production`, the automatic `latest` target, or `null` when no remote value is resolved.
 
 **Caching (bulk endpoint):**
 
@@ -114,9 +114,9 @@ These endpoints require an API key with the `project:read_variables` or `project
 
 ### Response Behavior
 
-When the server resolves a variable successfully, the OFREP response includes the resolved `value`, a `variant` (the label name), and `reason: "TARGETING_MATCH"`.
+When the server resolves a variable successfully, the OFREP response includes the resolved `value`, a `variant`, and a `reason` such as `"STATIC"`, `"SPLIT"`, or `"TARGETING_MATCH"`.
 
-When no value can be resolved — either because the variable has no versions, or because no label matches the evaluation context (e.g., rollout weights sum to less than 1.0 and no latest version fallback exists) — the server returns:
+When no remote value can be resolved — for example, because the variable has no versions yet or routing selects **Code default** — the server returns:
 
 ```json
 {

docs/reference/advanced/managed-variables/index.md

@@ -39,11 +39,11 @@ And two labels pointing to those versions:
 
 To roll out v3 to everyone, just move the `production` label from v2 to v3. To roll back, move it back to v2. No new versions need to be created — the label is just a pointer.
 
-!!! tip "Code default fallback"
-    If no labels are configured in the rollout, or if rollout weights sum to less than 1.0, the remaining traffic uses the **code default** (the `default` value passed to `logfire.var()`). To direct remaining traffic to the latest version instead, create a label that references `latest` and include it in your rollout.
+!!! tip "Latest and Code default"
+    In the Logfire UI, every variable has an automatic `latest` entry that points to the most recently created version. New variables start by routing traffic to `latest`, but `latest` has no value until you create the first version. The **Targeting** tab also shows **Code default**, which is the `default` value passed to `logfire.var()` in your application.
 
 !!! note "Code default as safety net"
-    The `default` value you pass to `logfire.var()` serves as an always-available fallback hard-coded into your source code. If no versions have been created yet, or if the remote configuration is unreachable due to a networking issue, or if a remote value fails validation against your type, the SDK returns the code default instead of raising an error. This means your application always has a working value — the remote configuration improves it, but never breaks it.
+    The `default` value you pass to `logfire.var()` serves as an always-available fallback hard-coded into your source code. If no remote value can be resolved, if the remote configuration is unreachable due to a networking issue, or if a remote value fails validation against your type, the SDK returns the code default instead of raising an error. This means your application always has a working value — the remote configuration improves it, but never breaks it.
 
 ## Structured Configuration
 

docs/reference/advanced/managed-variables/ui.md

@@ -1,11 +1,11 @@
 # Managing Variables in the Logfire UI
 
-The Logfire web UI provides a complete interface for managing your variables without any code changes. You can find it under **Settings > Variables** in your project. The page includes two tabs:
+The Logfire web UI provides a complete interface for managing your variables without any code changes. You can find it under **Runtime > Managed Variables** in your project. The page includes two tabs:
 
 - **Variables**: browse, create, and manage your managed variables
 - **Types**: define reusable JSON schemas for custom variable types
 
-Clicking a variable opens its **detail page**, which has four tabs: **Values**, **Targeting**, **History**, and **Settings**.
+Clicking a variable opens its **detail page**, which has **Values**, **Targeting**, **Optimize**, and **History** tabs. Users with write access also see **Settings**.
 
 ![Variables list](../images/variables-list.png)
 
@@ -31,26 +31,28 @@ For **Custom Types**, the schema is derived from the type and shown read-only; e
 
 The **Values tab** is the primary interface for viewing and editing your variable's content. It combines label management with value editing in a single view.
 
-The left sidebar shows all labels (both active and inactive), while the right panel displays the value for the selected label. Each label in the sidebar shows its name and what it points to (e.g., a version number, another label, or "latest").
+The left sidebar shows the automatic `latest` entry plus all labels (both active and inactive), while the right panel displays the value for the selected entry. Each label in the sidebar shows its name and what it points to (e.g., a version number, another label, `latest`, or **Code default**).
 
-- Select a label in the sidebar to view its current value
+- Select `latest` or a label in the sidebar to view its current value
 - Click the **copy** button to copy the displayed value to your clipboard
 - Click the **compare** button to diff the selected label's value against another label — useful for reviewing differences between production and staging prompts, for example
-- Click **Edit** to modify the value, then **Save new version** to create a new version and assign it to the selected label
-- Click **Add label** to create new labels pointing to a specific version, another label, the latest version, or the code default
+- Click **Edit** to modify the value, then **Save new version** to create a new version. When `latest` is selected, the new version becomes the latest version. When a label is selected, the new version is assigned to that label.
+- Click **Add label** to create new labels pointing to a specific version, another label, `latest`, or **Code default**
 
 ![Variable detail values](../images/variable-detail-values.png)
 
-**Labels** are mutable pointers to specific versions. They work like Docker tags or git branch names — you can move them to point at any version at any time.
+`latest` is always present and points to the most recently created version. A new variable has no versions yet, so `latest` has no value until you create the first version.
+
+**Labels** are mutable pointers to specific versions or targets. They work like Docker tags or git branch names — you can move them to point at any version, another label, `latest`, or **Code default** at any time.
 
 Common label patterns:
 
 - **`production`** / **`staging`** / **`canary`**: Environment-based labels for gradual rollouts
 - **`control`** / **`treatment`**: A/B testing labels
 - **`stable`** / **`experimental`**: Risk-based labels
 
-!!! note "No labels = code default"
-    If a variable has no labels configured in its routing, your application serves the code default (the `default` value passed to `logfire.var()`). To serve the latest version instead, create a label that references `latest` and include it in your routing.
+!!! note "Code default"
+    **Code default** is the `default` value passed to `logfire.var()` in your application. Use it when you want some traffic to ignore remote versions and keep using the value from code.
 
 ## Browsing Version History
 
@@ -70,13 +72,12 @@ The **History tab** lets you browse all saved versions:
 
 ## Configuring Label Routing
 
-The **Targeting tab > Default** section controls what percentage of requests receive each labeled version. The weights are entered as percentages (0–100%) and must sum to 100% or less:
+The **Targeting tab > Default** section controls what percentage of requests receive each label, `latest`, or **Code default**. The editable weights are entered as percentages (0-100%) and must sum to 100% or less. **Code default** is the remaining percentage after label and `latest` weights are allocated.
 
 - Set `production` to `90` and `canary` to `10` for a 10% canary deployment
 - Set `control` to `50` and `treatment` to `50` for a 50/50 A/B test
-- To send some traffic to the latest version, create a label that references `latest` and include it in the routing — for example, a `latest` label referencing latest at `10` and `control` at `50` sends 10% of traffic to the latest version, 50% to the control label, and the remaining 40% falls back to the code default
-- If weights sum to less than 100%, the remaining percentage uses the **code default**
-- If no labels are in the routing (empty), all traffic uses the code default
+- Set `latest` to `10` and `control` to `50` to send 10% of traffic to the most recently created version, 50% to the control label, and the remaining 40% to **Code default**
+- New variables start with `latest` at `100`, so all traffic uses the newest version once one exists
 
 ## Targeting with Conditional Rules
 
@@ -100,4 +101,4 @@ For example, to give enterprise customers the production experience:
 ![Variable detail targeting](../images/variable-detail-routing.png)
 
 !!! important "Variable names must match"
-    The variable name in the UI must exactly match the `name` parameter in your `logfire.var()` call. If they don't match, your application will use the code default instead of the remote configuration.
+    The variable name in the UI must exactly match the `name` parameter in your `logfire.var()` call. If they don't match, your application will use **Code default** instead of the remote configuration.