@salsita-ai/sdk 0.50.0-develop.801a817d3f → 0.50.0-develop.8f6deac646

package/dist/docs/complex-use-cases/navigation-reset-selection.mdx

@@ -18,7 +18,7 @@ The `createResetSelectionOnNavigationTransformer` automatically deselects entiti
 
 ## Guide
 
-The `createResetSelectionOnNavigationTransformer` is added through the `.withTransformers()` method. It automatically injects a deselect update when navigating to specified states.
+The `createResetSelectionOnNavigationTransformer` is added as a file in `src/transformers/`. It automatically injects a deselect update when navigating to specified states.
 
 ### Step 1: Import the transformer
 
@@ -28,19 +28,25 @@ Import the transformer function from the domain package:
 import { createResetSelectionOnNavigationTransformer } from '@salsita-ai/sdk/domain'
 ```
 
-### Step 2: Add the transformer to your config
+### Step 2: Add the transformer to your project
 
-Use the `.withTransformers()` method on the builder:
+Create the transformer in a file under `src/transformers/`:
 
 ```typescript
-const config = configuratorBuilder
-  .withTransformers(ctx => [
-    {
-      priority: 32,
-      transformer: createResetSelectionOnNavigationTransformer([ApplicationTypes.NavigationState.SecondStep], ctx),
-    },
-  ])
-  .buildConfig()
+// src/transformers/reset-selection.ts
+import { createResetSelectionOnNavigationTransformer } from '@salsita-ai/sdk/domain'
+
+export default phx.frontend.createTransformer(ctx =>
+  createResetSelectionOnNavigationTransformer([phx.applicationTypes.NavigationState.SecondStep], ctx)
+)
+```
+
+Each file in `src/transformers/` default-exports one transformer and is picked up by its location. The `transformers` section of the spec turns it on by name. For a transformer made with `build(name)` that is the name passed to `build(...)`, which must match the file name with case and dashes ignored (`fix-finish.ts` and `fixFinish` match). For a plain-function export it is the file name:
+
+```yaml
+# spec/application.yaml
+transformers:
+  - name: reset-selection
 ```
 
 The transformer takes two arguments:
@@ -97,7 +103,7 @@ When the transformer triggers, any selected entity is deselected automatically.
  *
  * @param navigationStates - Array of navigation state names that trigger deselection
  * @param ctx - Domain context providing access to the navigation system
- * @returns Update transformer that can be registered in withTransformers
+ * @returns Update transformer to return from a transformer file in src/transformers/
  *
  * @example
  * // Deselect when entering the summary step

package/dist/docs/index.json

@@ -1,5 +1,5 @@
 {
-  "generatedAt": "2026-10-10T09:40:17.085Z",
+  "generatedAt": "2026-10-13T17:25:35.625Z",
   "categories": [
     {
       "name": "Phoenix",

package/dist/docs/layouts/custom-price.mdx

@@ -78,24 +78,22 @@ Your custom component has full access to the Material-UI theme and SDK utilities
 
 ### Step 3: Attach the component to your entity
 
-Use the configurator builder to attach your custom price component to the root entity:
+Attach your custom price component to the root entity in a file under `src/components/`. The generated code picks the
+file up by its location and registers its default export:
 
 ```typescript
-const config = configuratorBuilder
-  .withComponentOptics([
-    attachComponent
-      .withEntity('Scene')
-      .withComponent(customPriceFooterComponent, 'default')
-      .attach(
-        memoEval(
-          (s) => [s.$price],
-          (price) => ({
-            node: <AppPrice price={price} />,
-          })
-        )
-      ),
-  ])
-  .buildConfig()
+// src/components/custom-price.tsx
+export default phx.domain.attachComponent
+  .withEntity('Scene')
+  .withComponent(customPriceFooterComponent, 'default')
+  .attach(
+    memoEval(
+      (s) => [s.$price],
+      (price) => ({
+        node: <AppPrice price={price} />,
+      })
+    )
+  )
 ```
 
 The `memoEval` function takes two arguments:

package/dist/docs/layouts/sidebar/tabs.mdx

@@ -179,27 +179,30 @@ When a selected entity has no `sidebarTabs`, its property pages replace the root
 You can use transformers to automatically navigate to specific tabs when entities are selected or deselected:
 
 ```typescript
-const config = configuratorBuilder
-  .withTransformers(ctx => {
-    return [
-      // Navigate to BuckyBall's first tab when selected
-      phx.frontend.transformerBuilder.when
-        .entity(['BuckyBall'])
-        .selected()
-        .then.navigateTo('BuckyBallTab1')
-        .build('Navigate to BuckyBallTab1')
-        .register(ctx),
-
-      // Return to global tab1 when BuckyBall is deselected
-      phx.frontend.transformerBuilder.when
-        .entity(['BuckyBall'])
-        .deselected()
-        .then.navigateTo('tab1')
-        .build('Navigate to Tab1')
-        .register(ctx),
-    ]
-  })
-  .buildConfig()
+// src/transformers/bucky-ball-tab.ts
+export default phx.frontend.transformerBuilder.when
+  .entity(['BuckyBall'])
+  .selected()
+  .then.navigateTo('BuckyBallTab1')
+  .build('buckyBallTab')
+```
+
+```typescript
+// src/transformers/tab.ts
+export default phx.frontend.transformerBuilder.when
+  .entity(['BuckyBall'])
+  .deselected()
+  .then.navigateTo('tab1')
+  .build('tab')
+```
+
+Each file in `src/transformers/` default-exports one transformer and is picked up by its location. The `transformers` section of the spec turns it on by name. For a transformer made with `build(name)` that is the name passed to `build(...)`, which must match the file name with case and dashes ignored (`fix-finish.ts` and `fixFinish` match). For a plain-function export it is the file name:
+
+```yaml
+# spec/application.yaml
+transformers:
+  - name: buckyBallTab
+  - name: tab
 ```
 
 This creates smooth navigation flows where selecting specific entities automatically switches to their relevant tabs, and deselecting returns to a default tab state.

package/dist/docs/other-features/domain-actions.mdx

@@ -83,7 +83,7 @@ export default phx.domain.implementActions({
 })
 ```
 
-Throw to reject a call: the message reaches the user through the control's hint and the assistant through the failed mutation, so say what went wrong and what to send instead. An action declared without an implementation, or an implementation of a name the spec does not declare, is a type error. A declared action without an implementation also stops the domain from initializing, and under `phoenix dev` the editor reports it as a `MISSING_ACTION_IMPLEMENTATIONS` diagnostic and does not apply the change; an implementation of an undeclared name is logged.
+Throw to reject a call: the message reaches the user through the control's hint and the assistant through the failed mutation, so say what went wrong and what to send instead. An implementation of a name the spec does not declare is a type error. A declared action without an implementation is not: it stops the domain from initializing, and under `phoenix dev` the editor reports it as a `MISSING_ACTION_IMPLEMENTATIONS` diagnostic and does not apply the change; an implementation of an undeclared name is logged.
 
 ## Run it from the UI
 

package/dist/docs/other-features/side-effects.mdx

@@ -66,48 +66,59 @@ With following control structure. The top input selects the material, the bottom
 The transformer is used to change the finish if necessary and show the notification.
 
 ```typescript
-configuratorBuilder
-  .withTransformers(domainContext => [
-    phx.frontend.transformerBuilder.when
-      .entity(['Plate'])
-      .modified({ atFields: ['material'] })
-      .causes.self.violation(['finishNotAvailable'])
-      .then.applySideEffect(({ update, getOld$Entity }) => {
-        const oldPlate = getOld$Entity()
-        const newMaterial = update.stateDelta.material
-
-        const validMaterial =
-          availableMaterials.find(m => m.material === newMaterial && m.finish === oldPlate.finish) ??
-          availableMaterials.find(m => m.material === newMaterial)
-
-        if (!validMaterial || validMaterial.finish === oldPlate.finish) {
-          return []
-        }
-
-        // create an additional update that will fix the material finish
-        const fixUpdate = phx.frontend.updates.DomainEntityModification({
-          entityId: oldPlate.id,
-          stateDelta: {
-            finish: validMaterial.finish,
-          },
-          updateTag: 'fix.finish',
-          hint: msg`Material finish was adjusted`, // specify a hint for the user (side effect)
-        })
-
-        return [fixUpdate]
-      })
-      .build('Fix material finish')
-      .register(domainContext),
-  ])
-  .buildConfig()
+// src/transformers/fix-finish.ts
+import { msg } from '@lingui/core/macro'
+
+import { availableMaterials } from '../_shared/materials.js'
+
+export default phx.frontend.transformerBuilder.when
+  .entity(['Plate'])
+  .modified({ atFields: ['material'] })
+  .causes.self.violation(['finishNotAvailable'])
+  .then.applySideEffect(({ update, getOld$Entity }) => {
+    const oldPlate = getOld$Entity()
+    const newMaterial = update.stateDelta.material
+
+    const validMaterial =
+      availableMaterials.find(m => m.material === newMaterial && m.finish === oldPlate.finish) ??
+      availableMaterials.find(m => m.material === newMaterial)
+
+    if (!validMaterial || validMaterial.finish === oldPlate.finish) {
+      return []
+    }
+
+    // create an additional update that will fix the material finish
+    const fixUpdate = phx.frontend.updates.DomainEntityModification({
+      entityId: oldPlate.id,
+      stateDelta: {
+        finish: validMaterial.finish,
+      },
+      updateTag: 'fix.finish',
+      hint: msg`Material finish was adjusted`, // specify a hint for the user (side effect)
+    })
+
+    return [fixUpdate]
+  })
+  .build('fix-finish')
+```
+
+Each file in `src/transformers/` default-exports one transformer and is picked up by its location. The `transformers` section of the spec turns it on by name. For a transformer made with `build(name)` that is the name passed to `build(...)`, which must match the file name with case and dashes ignored (`fix-finish.ts` and `fixFinish` match). For a plain-function export it is the file name:
+
+```yaml
+# spec/application.yaml
+transformers:
+  - name: fix-finish
 ```
 
 ### Hints and the AI assistant
 
 In a configurator with the AI assistant, the assistant is told the same hints: they arrive as
 `sideEffects` with the result of its changes and in the dry-runs of recipes and options, so it can
-tell the user what else happened. Set `agentHint` beside `hint` when the assistant needs different
-wording, for example with ids or values a snackbar would not show:
+tell the user what else happened. The hints also explain what the user changed between two messages:
+every message carries a change record of the configuration, and each of its lines ends with the hint
+of the last update that touched it, or with the `updateTag` when the update has none. Set `agentHint`
+beside `hint` when the assistant needs different wording, for example with ids or values a snackbar
+would not show:
 
 ```ts
 phx.frontend.updates.DomainEntityModification({
@@ -120,7 +131,9 @@ phx.frontend.updates.DomainEntityModification({
 ```
 
 - `agentHint` is a plain string, never shown to the user and not localized.
-- `agentHint: null` keeps the update from the assistant while the user still gets the `hint`.
+- `agentHint: null` keeps the wording from the assistant while the user still gets the `hint`: the
+  update is left out of `sideEffects`, and the change record explains its line by the `updateTag`. It
+  does not hide the change itself, which the assistant can always read from the configuration.
 - `agentHint` without a `hint` tells only the assistant.
 
 ## Example

package/dist/docs/other-features/transformers.mdx

@@ -102,7 +102,7 @@ export const removeExtraneousBranchesAndLeavesWhenShortened = phx.frontend.trans
     - With `overrideMatchinUpdates(ctx => /* side effect updates */)` the updates returned by the provided callback will replace the original **matched update**. This will be triggered for every matching update. Note that this action is not available in events which are not bound to a specific update - such as a violation check without a defined cause.
     - With `overrideAllUpdates(ctx => /* side effect updates */)` the updates returned by the provided callback will replace all original updates. This will be triggered only once for a single run of the transformer. This allows for implementation of transformers that behave similarly as the raw `UpdateTransformer`
   - High-level actions: `select`, `deselect`, `navigate`, `changeView` - more on these in the other examples.
-- `build(name)` is the final step to create the transformer. Assign a descriptive name (no restrictions) to easily identify the transformer while tracing. Note that this returns a `RegistrableTransformer` which needs to be registered using the `register(domainContext)` method. This is usually done in the `.withTransformers()` method of the configurator builder.
+- `build(name)` is the final step to create the transformer. The name identifies the transformer while tracing, and it is the name the `transformers` section of the spec refers to, so it must match the file name with case and dashes ignored (`fix-finish.ts` and `fixFinish` match). Note that this returns a `RegistrableTransformer`. Default-export it from a file in `src/transformers/` and list the name passed to `build(...)` in the `transformers` section of the spec; the generated code registers it. The shorter snippets on this page use descriptive names for readability; the complete implementation below uses names that match its files.
 
 ### Side-Effect on Update Causing Another Entity's Violation
 

package/dist/docs/phoenix/admin.mdx

@@ -427,43 +427,28 @@ For technical details about data transformation and storage, see [Data Sources -
 
 ## Web Component Integration
 
-Admin functionality integrates through the configurator builder rather than requiring separate web component setup.
+Admin functionality is part of the same application as the configurator and needs no separate web component setup.
 
-### Configurator Builder Setup
+### Registering Admin Components
 
-In phx-cli projects, frontend entry is auto-generated in `.phoenix/`. Admin components are registered through `src/admin/components/`:
+The frontend entry is generated into `.phoenix/`, so a project never calls the configurator builder itself. Every file
+in `src/admin/components/` is picked up by its location and its default export is registered as admin components:
 
 ```typescript
 // src/admin/components/admin-components.tsx
-import { configuratorBuilder } from '.phoenix/frontend.js'
-import { customAdminOptics } from './optics.js'
-import { NotAuthenticatedPage } from '../pages/NotAuthenticatedPage.js'
-
-const config = configuratorBuilder
-  .withComponentOptics(customConfiguratorComponents)
-  .withAdminComponentOptics(customAdminOptics) // Register admin components
-  .buildConfig({
-    deploymentId: phx.runtimeConfig.DEPLOYMENT_ID,
-    persistence: {
-      type: 'server',
-      serverUrl: phx.runtimeConfig.SERVER_URL,
-    },
-    ui: {
-      notAuthenticatedPage: <NotAuthenticatedPage />, // Show when user not authenticated
-    },
-    // ... other config
-  })
+// ... customAdminOptics as defined in the example above
 
-phx.frontend.mountApplication(config)
+export default customAdminOptics
 ```
 
-Admin component files go in `src/admin/components/` and are automatically discovered by phx-cli.
+The page shown to a user who is not authenticated is an element. Create it with
+`phx.frontend.createNotAuthenticatedPage(...)` in a file under `src/elements/`.
 
 ### Built-in Admin Integration
 
 Phoenix automatically provides admin functionality when:
 
-1. Admin components are registered via `withAdminComponentOptics()`
+1. Admin components are default-exported from files in `src/admin/components/`
 2. Admin configuration exists in `phoenix.config.ts`
 3. User has admin session token
 

package/dist/docs/phoenix/deployments.mdx

@@ -464,7 +464,7 @@ Error: Failed to upload to S3
 
 - Run `deployment:prepare` again to get fresh presigned URLs
 - Check that `.upload-links.json` exists and is readable
-- Use `--skipUpload` / `-su` flag to test without uploading assets
+- Use `--skipUpload` / `--su` flag to test without uploading assets
 
 ### "Server URL is required"
 

package/dist/docs/phoenix/expression-context.mdx

@@ -35,15 +35,23 @@ interface ExpressionContext<
 
   // System services
   readonly domain: Domain // Access to domain model and other entities
-  readonly componentReader: ComponentReader // Read component states across all entities
   readonly migrate: MigrateFunction // Data migration utilities
-  readonly sketchingProjections: SketchingProjections // Sketching system projections
-  readonly collisionProjections: CollisionProjections // Collision detection projections
+  readonly componentReader: ComponentReader // Read component states across all entities
+
+  // Projections
+  readonly positionProjections: PositionProjections // World matrices of scene entities
+  readonly sketchingProjections: SketchingProjections // Shapes and connections of a sketch
+  readonly collisionProjections: CollisionProjections // Collision meshes and collisions between entities
+  readonly constraintProjections: ConstraintProjections // Spatial constraints an entity violates
+  readonly snappingProjections: SnappingProjections // Snap points, edges, planes and matches
+  readonly projectedEntitiesProjections: ProjectedEntitiesProjections // Data of projected entities
 }
 ```
 
 The context includes data sources (session, published, frontend, backend), system services (domain access, component reader, projections), and application state (mode, role). Each part serves a different purpose in expression calculations.
 
+The SDK declares the context in two parts. `CoreExpressionContext` holds the mode, the role, the data sources, `domain` and `migrate`. `RuntimeExpressionContext` holds the component reader and the projections. An editor hover or a type error therefore shows `ctx` as `OpenExpressionContext<..., RuntimeExpressionContext<AnyDomainEntity>>`, which has the members listed above. A helper of your own that takes the context declares its parameter as `ExpressionContext` with the five types of your project.
+
 ### Configurator Modes
 
 The `mode` property indicates the current operational context of the configurator. Different modes enable different functionality and access levels. Expressions can check the mode to change their behavior.

package/dist/docs/phoenix/localization.mdx

@@ -116,28 +116,9 @@ After running `pnpm lingui:compile`, your custom translations will override the
 - Adapt translations for your target audience
 - Maintain consistency with your existing product language
 
-**Frontend integration**:
-
-```typescript
-import { configuratorBuilder } from 'project-domain'
-import { createI18n } from 'project-i18n'
-
-const i18n = createI18n()
-
-export const config = configuratorBuilder
-  .withComponentOptics(customComponents)
-  .withPresets(presets)
-  .withI18n(i18n) // Register i18n service with configurator
-  .buildConfig({
-    features: {
-      availableLocales: ['en', 'de', 'cs'],
-    },
-    services: {
-      logger,
-    },
-    // ... other configuration
-  })
-```
+**Frontend integration**: the generated `.phoenix` code creates the i18n service from `.phoenix/i18n.ts` and registers
+it with the application, so there is nothing to wire by hand. The languages come from `availableLocales` in
+`spec/application.yaml`.
 
 ## Working with YAML Domain Specifications
 

package/dist/docs/phoenix/phoenix-cli.mdx

@@ -257,11 +257,14 @@ The frontend reads these at runtime from the generated config:
 | Variable                         | Required | Default                 |
 | -------------------------------- | -------- | ----------------------- |
 | `IS_DEV`                         | No       | `false` (`true` in dev) |
+| `ASSISTANT_STRICT_THREADS`       | No       | `false`                 |
 | `AWS_S3_PUBLIC_RESOURCES_BUCKET` | Yes      | —                       |
 | `AWS_S3_RESOURCES_REGION`        | Yes      | —                       |
 | `DEPLOYMENT_RESOURCES_PATH`      | No       | `deployment-resources`  |
 | Clerk vars (if enabled)          | Yes      | —                       |
 
+A development environment keeps the AI assistant's conversation when the assistant setup (manifest, instructions, AI settings) changes, and applies the new setup from the next message on. Set `ASSISTANT_STRICT_THREADS=true` in `.env` to try the behavior of every other environment locally, where a changed setup locks the conversation and the next message continues it in a summarized one. The variable has no effect outside a development environment.
+
 ### Precedence
 
 Environment variables are resolved in this order (highest to lowest priority):
@@ -283,20 +286,20 @@ The Phoenix CLI auto-generates config files that read these variables:
 
 Starts the full development environment: Vite dev server, development webhook tunnel, domain-cli watcher, and editor WebSocket server.
 
-| Flag                   | Env Variable       | Default              | Description                                                                     |
-| ---------------------- | ------------------ | -------------------- | ------------------------------------------------------------------------------- |
-| `--workspace`          | —                  | from `.phoenix.json` | Override workspace mode                                                         |
-| `--editor`             | `ENABLE_EDITOR`    | `true`               | Enable editor file generation                                                   |
-| `--editorWsPort`       | `EDITOR_WS_PORT`   | `3020`               | Editor WebSocket port                                                           |
-| `--debug`              | `DEBUG`            | `false`              | Verbose logging                                                                 |
-| `--projectSlug`        | `PROJECT_SLUG`     | `local`              | Project slug                                                                    |
-| `--environmentSlug`    | `ENVIRONMENT_SLUG` | package.json name    | Environment slug                                                                |
-| `--withLingui`         | `WITH_LINGUI`      | `false`              | Enable i18n extraction/compilation and watch i18n sources during dev            |
-| `--persistence`        | `PERSISTENCE_MODE` | `server`             | Persistence mode                                                                |
-| `--force` / `-f`       | `FORCE_REBUILD`    | `false`              | Force full rebuild, skip cache                                                  |
-| `--serverUrl`          | `SERVER_URL`       | the region's server  | Phoenix server URL                                                              |
-| `--region`             | `PHOENIX_REGION`   | `eu`                 | Region of the signed-in workspace, used when no server URL is set               |
-| `--skipUpload` / `-su` | `SKIP_UPLOAD`      | `false`              | Skip the S3 asset upload when the development deployment is prepared at startup |
+| Flag                    | Env Variable       | Default              | Description                                                                     |
+| ----------------------- | ------------------ | -------------------- | ------------------------------------------------------------------------------- |
+| `--workspace`           | —                  | from `.phoenix.json` | Override workspace mode                                                         |
+| `--editor`              | `ENABLE_EDITOR`    | `true`               | Enable editor file generation                                                   |
+| `--editorWsPort`        | `EDITOR_WS_PORT`   | `3020`               | Editor WebSocket port                                                           |
+| `--debug`               | `DEBUG`            | `false`              | Verbose logging                                                                 |
+| `--projectSlug`         | `PROJECT_SLUG`     | `local`              | Project slug                                                                    |
+| `--environmentSlug`     | `ENVIRONMENT_SLUG` | package.json name    | Environment slug                                                                |
+| `--withLingui`          | `WITH_LINGUI`      | `false`              | Enable i18n extraction/compilation and watch i18n sources during dev            |
+| `--persistence`         | `PERSISTENCE_MODE` | `server`             | Persistence mode                                                                |
+| `--force` / `-f`        | `FORCE_REBUILD`    | `false`              | Force full rebuild, skip cache                                                  |
+| `--serverUrl`           | `SERVER_URL`       | the region's server  | Phoenix server URL                                                              |
+| `--region`              | `PHOENIX_REGION`   | `eu`                 | Region of the signed-in workspace, used when no server URL is set               |
+| `--skipUpload` / `--su` | `SKIP_UPLOAD`      | `false`              | Skip the S3 asset upload when the development deployment is prepared at startup |
 
 In `server` persistence mode the project comes from `--projectSlug`, `PROJECT_SLUG` or `project` in the spec, and the credential from `DEVELOPMENT_KEY` or the `phoenix login` sign-in; see [Starting a New Project](#starting-a-new-project). When signed in, the environment is always your own development environment and `--environmentSlug` is ignored.
 
@@ -491,6 +494,85 @@ phoenix screenshot -o preview.png -w 1920 --height 1080
 | `--height`        | `1080`  | Image height in pixels         |
 | `--format` / `-f` | `png`   | Image format (`png` or `jpeg`) |
 
+### `phoenix variants`
+
+Show several options over the configurator and wait for your pick. It is built for coding agents: when a decision is a matter of taste, such as the edge of a table top, how glossy a finish is or where a control sits, the agent writes one file per option, you choose in the browser, and the command hands your answer back to the agent.
+
+```bash
+phoenix variants .phoenix/variants/table-edge --title 'Which edge suits the table?' --description 'Only the edge of the top differs.'
+```
+
+Every `<id>.variant.js` script or `<id>.html` page in the folder is one option, shown in file-name order. Each script edits frontend project files on top of the same captured baseline. Original is always the first choice and restores that baseline. Switching options removes the previous option's edits and applies the selected script; the editor dialog has any number of choices on the left and your already loaded configurator on the right.
+
+```js
+// .phoenix/variants/brand/blue.variant.js
+export const title = 'Blue brand'
+export const description = 'A blue primary colour with the current layout.'
+
+export default ({ read, write, remove }) => {
+  const file = 'src/handlers/theme.ts'
+  write(file, read(file).replace("main: '#E93335'", "main: '#2364aa'"))
+}
+```
+
+`read(path)` always reads the baseline. `write(path, contents)` replaces or creates a file; `remove(path)` deletes it. Scripts run in the browser and collect edits; Phoenix validates and writes the batch locally. Supported files are YAML under `spec/` outside `spec/admin/`, and TypeScript under `src/components`, `transformers`, `handlers`, `elements` and `_`-prefixed shared folders. Expressions, actions and invariants also run on the server, so a script cannot edit them.
+
+For standalone UI or branding proposals, write self-contained HTML files. Each page renders in its own iframe when selected; its `<title>` names the option and `<meta name="description" content="...">` describes it. HTML and scripts may share a set if their file names give distinct option ids.
+
+```html
+<!-- .phoenix/variants/brand/blue.html -->
+<!doctype html>
+<title>Blue studio</title>
+<meta name="description" content="A calm blue identity with generous spacing." />
+<style>
+  body {
+    margin: 0;
+    padding: 40px;
+    background: #f0f5fa;
+    color: #163b66;
+    font-family: sans-serif;
+  }
+</style>
+<h1>Made for your everyday.</h1>
+<button>Design your table</button>
+```
+
+Scripts run once per selection. The completed file batch calls the existing rebuild queue directly, without a separate file-change event stream or a watcher that reapplies the option.
+
+Use script options for controls, layout, brand, lights, visual effects, materials, positions, components, elements and transformers. Changes to the model, schemas, data or deployment settings are rejected before any files are written. Environment files, webhooks, their shared implementation dependencies, dependencies and uploaded assets cannot be overridden. Files connected through symbolic links are also excluded, so restoring the baseline preserves the original files. No server preparation or webhook rebuild runs for a variant transaction.
+
+Picking a script keeps its exact implementation in the project. Picking an HTML page returns the selected proposal for the agent to implement; the page itself changes no project source files. Choosing Original keeps the captured baseline. Users finish by confirming Original or another option. Escape stays available to the configurator, and clicking the backdrop leaves the comparison open. The agent can use `--close` to restore the baseline source files without giving an answer. Phoenix records recovery information on disk and restores interrupted previews at the next `phoenix dev` start. It never overwrites a file edited outside the preview: switching options over such an edit is refused, and when the comparison ends, or is restored at the next start, that file is left as it is with a warning in the dev log while the others are restored. Other source changes made while a comparison is open are rebuilt once it ends.
+
+Answers are held for four seconds with Undo and Send now.
+
+The command prints the outcome as JSON. After `chosen` it removes the folder:
+
+| `status`  | Meaning                                                                                                                                      |
+| --------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
+| `chosen`  | An option was picked: `choice` is its id, or `null` for Original; `label` is its name.                                                       |
+| `waiting` | The wait ran out. The preview stays open: the same command attaches to it again, and an answer given in between is returned by the next run. |
+| `closed`  | The preview was closed without an answer, by `--close` or by another set of options taking its place. The folder is kept.                    |
+
+| Flag                   | Default                       | Description                                               |
+| ---------------------- | ----------------------------- | --------------------------------------------------------- |
+| `--title` / `-t`       | `Which option do you prefer?` | Question shown above the options                          |
+| `--description` / `-d` | —                             | A line saying what differs between the options            |
+| `--timeout`            | `540`                         | Seconds to wait for the answer                            |
+| `--keep`               | `false`                       | Keep the folder after the answer                          |
+| `--close`              | `false`                       | Close the open preview without an answer; needs no folder |
+| `--port` / `-p`        | `3020`                        | Editor WebSocket port                                     |
+
+Known limits:
+
+- Variant transactions start rebuilding immediately, bypassing the normal file-watcher debounce. Hot reload still needs to parse and apply the updated implementation. There is no wait for UI or scene loading to settle; allow a visible transition to finish before judging or choosing.
+- Only one option is displayed at a time; simultaneous comparison is not supported.
+- For script options and Original, the dialog moves the existing configurator into the preview and returns it on close, preserving the loaded scene, camera and UI state. Opening the dialog starts no second application or initial loading screen. Configuration interactions still change the current configuration; restoring source files does not undo them.
+- Custom scripts are trusted project code. Their file API stages edits; scripts must not make network requests or other side effects.
+- Binary assets, CSS files, locale catalog changes, dependency changes and edits requiring a full application restart are unsupported.
+- Storybook `story-dev` has no variant previews. A project on the legacy pipeline has no variant previews; the command says so and exits.
+
+Generated projects carry the `phoenix-variants` agent skill, which tells coding agents when to offer options, how to write each kind and what to do with your answer.
+
 ## SDK Development
 
 ### `phoenix link`
@@ -603,7 +685,7 @@ SDK-builder workspaces sign the CLI in with a personal API token instead of proj
 
 Signs the CLI in to the SDK-builder workspace `<customer>`:
 
-1. Opens Studio, where you name the token and approve the sign-in (use `--no-open` to only print the link). The page shows the workspace, your account, the computer the CLI runs on and how long the link still works. The CLI suggests the name `phoenix CLI on <computer>`; change it so you can tell your machines and agents apart later.
+1. Opens Studio, where you name the token and approve the sign-in (use `--no-open` to only print the link). Only a super admin of the workspace can open its Studio, so only a super admin can sign the CLI in. The page shows the workspace, your account, the computer the CLI runs on and how long the link still works. The CLI suggests the name `phoenix CLI on <computer>`; change it so you can tell your machines and agents apart later.
 2. Studio sends a one-time code back to the CLI on `127.0.0.1`.
 3. The CLI exchanges the code for a token with the name you approved, and sends the browser back to Studio, which confirms the sign-in.
 
@@ -611,12 +693,12 @@ Signs the CLI in to the SDK-builder workspace `<customer>`:
 
 The token is stored in `~/.phoenix/credentials.json`, readable only by you, per server, together with the Studio URL of the sign-in; `PHOENIX_CREDENTIALS_FILE` moves the file. The token works until you revoke it. Signing in again to the same server revokes the token it replaces; the CLI warns if the server could not revoke it.
 
-| Flag                  | Default                              | Description                                      |
-| --------------------- | ------------------------------------ | ------------------------------------------------ |
-| `--region`            | `eu`                                 | Phoenix region of the workspace: `eu` or `us`    |
-| `--serverUrl` / `-su` | the region's server                  | Phoenix server URL, for a local or custom server |
-| `--studioUrl`         | the workspace's Studio in the region | Studio URL of the workspace                      |
-| `--open`              | `true`                               | Open the approval page in your browser           |
+| Flag                   | Default                              | Description                                      |
+| ---------------------- | ------------------------------------ | ------------------------------------------------ |
+| `--region`             | `eu`                                 | Phoenix region of the workspace: `eu` or `us`    |
+| `--serverUrl` / `--su` | the region's server                  | Phoenix server URL, for a local or custom server |
+| `--studioUrl`          | the workspace's Studio in the region | Studio URL of the workspace                      |
+| `--open`               | `true`                               | Open the approval page in your browser           |
 
 The sign-in follows the region, not the `SERVER_URL` in a project's `.env`: that variable names the server of the project's own environment. The CLI prints the server it signs in to.
 
@@ -649,7 +731,7 @@ Pass the message as the argument for a short note, or `--file` for a longer repo
 | `--agent`              | —              | —                             | Name of the coding agent that writes the feedback         |
 | `--projectSlug` / `-p` | `PROJECT_SLUG` | `project` of the spec, if any | Workspace project the feedback is about                   |
 | `--region`             | —              | `eu`                          | Phoenix region of the workspace: `eu` or `us`             |
-| `--serverUrl` / `-su`  | —              | the region's server           | Phoenix server URL, for a local or custom server          |
+| `--serverUrl` / `--su` | —              | the region's server           | Phoenix server URL, for a local or custom server          |
 
 A message holds at most 100,000 characters, from the argument or from the file. Besides the message and the flags, the CLI sends only the SDK version, the operating system and the Node.js version; no file of the project is attached, and the Phoenix team reads a build's sources through the build's page in Studio. The project must belong to the signed-in workspace, otherwise the server refuses the feedback; without a project, the feedback is sent on its own.