@salsita-ai/sdk 0.49.0 → 0.50.0-develop.016963b09e

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/migrations.mdx

@@ -18,6 +18,8 @@ Each version defines its own:
 
 This versioning allows you to track changes over time and ensure proper migration paths.
 
+The version number is not written anywhere: `latest` is the highest numbered version plus one, so a model with only `latest` is version 1. Once a version has been deployed it cannot change, because saved configurations depend on it. `phoenix deploy` refuses a model that differs from the one deployed under the same version, before anything is uploaded. To change a deployed model, keep it unchanged as `v<N>`, make the change in `latest` and add the migration to version N+1. Development environments replace the deployed model instead, so `phoenix dev` accepts every change.
+
 ## Model File Structure
 
 It's recommended to split your model versions into separate files for better maintainability:
@@ -39,9 +41,11 @@ The CLI generates separate TypeScript types for each version, which helps ensure
 
 ```typescript
 // The Migration type ensures you handle all entity types
-type Migration<FromEntity, ToEntity> = (state: FromEntity[]) => ToEntity[]
+type Migration<FromEntity, ToEntity> = (state: readonly FromEntity[]) => readonly ToEntity[]
 ```
 
+The types of each version are generated as global namespaces: `ModelV1`, `ModelV2`, and so on. `ModelV1.AnyDomainEntity` is the union of all entities of version 1, and `ModelV1.<EntityType>` is one of them. The admin model has its own namespaces, `AdminV1`, `AdminV2`, and so on. A migration needs no import for them.
+
 ## Migration File Location
 
 Migration files are organized in the `src/migrations/` directory with a specific naming convention:
@@ -63,11 +67,16 @@ Each migration file should export a function named `migrateToVN` where N is the
 
 ```typescript
 // src/migrations/v2.ts
-export const migrateToV2: Migration<V1Entity, V2Entity> = state => {
+import type { Migration } from '@salsita-ai/sdk/domain'
+
+export const migrateToV2: Migration<ModelV1.AnyDomainEntity, ModelV2.AnyDomainEntity> = state => {
   // Transform entities from v1 to v2
+  return state
 }
 ```
 
+Keep the `Migration<...>` type on the export, with its `readonly` arrays: the generated domain file passes each migration to the migration builder, and a function typed with mutable arrays does not type-check there.
+
 **Note:** Migrations start from version 2. There is no migration TO v1 since v1 is the initial version. The first migration you write will be `migrateToV2`.
 
 The `ts-pattern` library is recommended for implementing migrations as it provides type-safe pattern matching.
@@ -77,11 +86,15 @@ The `ts-pattern` library is recommended for implementing migrations as it provid
 Migrations are implemented as functions that transform entities from one version to another. Each migration handles the transition between consecutive versions:
 
 ```typescript
-export const migrateToV4: Migration<V3Entity, V4Entity> = state => {
+import { match } from 'ts-pattern'
+
+import type { Migration } from '@salsita-ai/sdk/domain'
+
+export const migrateToV4: Migration<ModelV3.AnyDomainEntity, ModelV4.AnyDomainEntity> = state => {
   return state.map(entity => {
     return (
       match(entity)
-        .returnType<V4Entity>()
+        .returnType<ModelV4.AnyDomainEntity>()
         .with({ type: 'Burner' }, value => ({ ...value, y: 0 }))
         .with({ type: 'Cabinet' }, value => ({ ...value, y: 0 }))
         // ... handle other entities
@@ -91,6 +104,33 @@ export const migrateToV4: Migration<V3Entity, V4Entity> = state => {
 }
 ```
 
+### Renaming an Entity Type
+
+An entity id starts with its entity type, such as `Box-1`, and is typed per entity type (`DomainEntityId<'Box'>`). The runtime validates that an entity's id matches its type, so an entity that keeps its data under a new type name needs a new id, and every relation that points at it must be rewritten to that id. The id is built from a string, which TypeScript cannot check, so this is one place where a cast is needed:
+
+```typescript
+import { parseDomainEntityId } from '@salsita-ai/sdk/domain'
+
+const toTableId = (id: ModelV1.Box['id']) =>
+  // The id is rebuilt for the new type name; nothing narrower than a cast can type a template string as an id
+  `Table-${parseDomainEntityId(id).sequenceNumber}` as ModelV2.Table['id']
+```
+
+### Replacing the Model Entirely
+
+When the new model has nothing in common with the deployed one, there is nothing to convert. This is the case when a project that was first deployed as the starter gets its real model: the starter's `Box` model is version 1 in production, and a deployed version cannot change. Keep the deployed model as `v1`, define the real model in `latest`, and let the migration return the starting state of the new model, the `initialDomainEntities` of its preset:
+
+```typescript
+// src/migrations/v2.ts
+import type { Migration } from '@salsita-ai/sdk/domain'
+
+export const migrateToV2: Migration<ModelV1.AnyDomainEntity, ModelV2.AnyDomainEntity> = () => [
+  // the entities of the new model's preset
+]
+```
+
+No entity of a type that the new version no longer has may stay in the returned state: the migrated state is validated against the latest model, and an unknown entity type fails the load.
+
 ## Migration Runtime
 
 Migrations are executed automatically every time the domain is loaded, both in the client application and in webhooks. During this process:
@@ -114,7 +154,7 @@ When implementing migrations:
 
 4. **Testing**: Thoroughly test migrations with real-world data to ensure they handle all edge cases, use existing configurations from previous versions.
 
-5. **Version Bumping**: Consider bumping the model version for both breaking changes (removing fields, changing types) and additive changes where existing data needs proper defaults. If you add a new required field, existing configurations need a migration to set that field's default value.
+5. **Version Bumping**: Every change to a model that has been deployed needs a new version, whether it is breaking (removing fields, changing types) or additive. If you add a new required field, existing configurations need a migration to set that field's default value; a change that needs no conversion still needs a migration that returns the state unchanged.
 
 ## Admin Model Migrations
 

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

@@ -29,10 +29,11 @@ pnpm phoenix dev
 
 1. Refuses to run when a `spec/` folder already exists, so it never touches an existing project.
 2. Writes a `package.json` that depends on the CLI's SDK version when the folder has none. An existing `package.json` is kept, as long as it depends on the SDK.
-3. Writes a starter spec (`spec/application.yaml`, `spec/configurator.yaml`) with one resizable, recolorable box, and switches `package.json` to the application-spec pipeline.
-4. Writes `pnpm-workspace.yaml` with the pnpm settings the first install needs: the build scripts of the SDK's dependencies are allowed or denied, and `@salsita-ai/*` packages are exempt from pnpm's minimum release age. A project inside a pnpm monorepo gets no file; the workspace root holds these settings.
+3. Adds the `dev`, `build`, `deploy`, `check` and `fix` scripts to `package.json` (see [Project Scripts](#project-scripts)). A script the project already has under one of those names keeps its command.
+4. Writes a starter spec (`spec/application.yaml`, `spec/configurator.yaml`) with one resizable, recolorable box, and switches `package.json` to the application-spec pipeline.
+5. Writes `pnpm-workspace.yaml` with the pnpm settings the first install needs: the build scripts of the SDK's dependencies are allowed or denied, and `@salsita-ai/*` packages are exempt from pnpm's minimum release age. A project inside a pnpm monorepo gets no file; the workspace root holds these settings.
 
-It asks nothing, writes no `.env` and contacts no server. `phoenix sync` then generates every other project file, including `AGENTS.md` and the agent skills described in [Project Structure](?path=/docs/phoenix-project-structure--docs).
+It asks nothing, writes no `.env` and contacts no server. `phoenix sync` then generates every other project file, including the agent skills described in [Project Structure](?path=/docs/phoenix-project-structure--docs). The `.gitignore` is among them only when the folder is inside a git repository, so run `git init` before the first sync, or sync again after it.
 
 ### Which project `phoenix dev` develops in
 
@@ -114,8 +115,6 @@ For quick local development without a server, use:
 
 ```bash
 phoenix dev --persistence local-storage
-# or use the shortcut script:
-pnpm dev:local
 ```
 
 **Important:** The server must be running before `deployment:prepare-local` when using `server` persistence mode.
@@ -158,27 +157,19 @@ spec/application.yaml → Server prepares environment → CLI writes .env.genera
 
 ### Project Scripts
 
-When you run `phoenix sync` or `phoenix clean`, the CLI auto-generates standardized scripts in your `package.json`. These scripts are enforced — they cannot be overridden by custom scripts with the same name.
-
-| Script                     | Command                                                 | Purpose                                       |
-| -------------------------- | ------------------------------------------------------- | --------------------------------------------- |
-| `dev`                      | `phoenix dev`                                           | Dev server with hot reload                    |
-| `dev:local`                | `phoenix dev --persistence local-storage`               | Dev without server dependency                 |
-| `build`                    | `phoenix build`                                         | Production build                              |
-| `clean`                    | `phoenix clean`                                         | Clean all artifacts and rebuild               |
-| `sync`                     | `phoenix sync`                                          | Sync generated code and dependencies          |
-| `check`                    | `phoenix check`                                         | Run all checks (TypeScript, ESLint, Prettier) |
-| `ts:check`                 | `phoenix check`                                         | Alias for `check`                             |
-| `fix`                      | `phoenix fix`                                           | Auto-fix lint and formatting issues           |
-| `lint:fix`                 | `eslint src --fix`                                      | ESLint fix only                               |
-| `prettify:fix`             | `prettier --write .`                                    | Prettier fix only                             |
-| `verify:fix`               | `phoenix build && phoenix fix && phoenix check --types` | Build, fix, then type-check                   |
-| `test`                     | `vitest --passWithNoTests run`                          | Run tests                                     |
-| `test:watch`               | `vitest`                                                | Tests in watch mode                           |
-| `prepare:ci`               | `phoenix prepare:ci`                                    | CI environment setup                          |
-| `deployment:prepare-local` | `phoenix deployment:prepare-local`                      | Prepare local environment                     |
-
-Custom scripts you add to `package.json` are preserved during sync. Deprecated scripts (like `environment:create`, `deployment:register`) are automatically removed.
+`phoenix init` writes five scripts into `package.json`, each a shortcut for the CLI command of the same name:
+
+| Script   | Command          | Purpose                                       |
+| -------- | ---------------- | --------------------------------------------- |
+| `dev`    | `phoenix dev`    | Dev server with hot reload                    |
+| `build`  | `phoenix build`  | Production build                              |
+| `deploy` | `phoenix deploy` | Build and publish the project                 |
+| `check`  | `phoenix check`  | Run all checks (TypeScript, ESLint, Prettier) |
+| `fix`    | `phoenix fix`    | Auto-fix lint and formatting issues           |
+
+The scripts are yours: change, rename or delete them, and add your own. `phoenix sync` and `phoenix clean` leave the `scripts` section of `package.json` as it is, so they add no script, restore none you removed and remove none. Every CLI command also runs without a script, as `pnpm phoenix <command>`.
+
+A project may have other scripts than these five, such as `sync`, `test` or `verify:fix`; they are its own and stay as they are. All of this holds for a project on the application-spec pipeline, which `phoenix init` selects. In a project on the legacy pipeline (see [Current and legacy project tooling](#current-and-legacy-project-tooling)), `phoenix sync` and `phoenix clean` write their own set of scripts into `package.json` on every run, over scripts of the same name.
 
 ### Server-Generated Variables
 
@@ -257,11 +248,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 +277,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.
 
@@ -327,15 +321,49 @@ as restart-required unless their feature documentation explicitly states live-up
 
 Builds the project for production deployment.
 
-| Flag             | Env Variable    | Default | Description                    |
-| ---------------- | --------------- | ------- | ------------------------------ |
-| `--onlyFrontend` | —               | —       | Build only the frontend bundle |
-| `--onlyWebhook`  | —               | —       | Build only webhooks            |
-| `--force` / `-f` | `FORCE_REBUILD` | `false` | Force full rebuild, skip cache |
-| `--debug`        | `DEBUG`         | `false` | Verbose logging                |
+| Flag              | Env Variable    | Default | Description                                         |
+| ----------------- | --------------- | ------- | --------------------------------------------------- |
+| `--onlyFrontend`  | —               | —       | Build only the frontend bundle                      |
+| `--onlyWebhook`   | —               | —       | Build only webhooks                                 |
+| `--force` / `-f`  | `FORCE_REBUILD` | `false` | Force full rebuild, skip cache                      |
+| `--banner <text>` | —               | —       | Replaces the application line of the banner comment |
+| `--debug`         | `DEBUG`         | `false` | Verbose logging                                     |
 
 The build target can also be controlled via `BUILD_TARGET` env (`frontend`, `webhook`, or `both`).
 
+#### Banner comment
+
+Every JavaScript file the frontend build emits (the configurator, admin and embedded bundles, and the editor's entry and lazy chunks) starts with a comment that identifies the build, so `head -n 5 <bundle.js>` tells two deployed bundles of nearly the same size apart:
+
+```js
+/*!
+ * App version: 1.2.3; Commit: 9fd79ce0f4c1a2b3d4e5f60718293a4b5c6d7e8f
+ * Built with Salsita SDK 3.4.0. Copyright (c) Salsita s.r.o. All rights reserved.
+ * Third-party licences: THIRD-PARTY-LICENSES.txt
+ */
+```
+
+The first line is the application's. By default it holds `applicationVersion` from `spec/application.yaml` and the commit checked out in the project, read with `git rev-parse HEAD`. Where git cannot read a commit for the project (no checkout, git missing or refusing the repository, or the project's `package.json` is not tracked by the repository around it), the line holds the version only and `--debug` logs it; this is the case for a platform build from uploaded sources.
+
+`--banner <text>` replaces that line with your own text, for example when CI knows a release name the spec does not:
+
+```sh
+pnpm phoenix build --banner "Release: ${RELEASE_NAME}; Commit: ${COMMIT_SHA}"
+```
+
+The line is **public**: it ships in every bundle. The default publishes the application version and the commit SHA; pass `--banner ""` to leave the line out, and never put a secret or internal detail in your own text. The text is written as comment text only. Each line of a multi-line value (or each repeated `--banner`) becomes its own comment line and `*/` is written as `*\/`. There is no environment-variable fallback, and the option has no effect on webhook output or with `--onlyWebhook`. Lazy chunks keep their hashed file name when only the banner text changes.
+
+The banner and the licences file below are produced by the application-spec pipeline; the legacy pipeline's build ignores `--banner`.
+
+#### Third-party licences
+
+The frontend build writes `.phoenix/dist/frontend/THIRD-PARTY-LICENSES.txt` next to the bundles and the banner comment points to it. It lists every third-party package whose code or styles are in any of the frontend bundles, once each, sorted by name and version, with the package's version, the licence declared in its `package.json` and the text of its licence file (`LICENSE*`, `LICENCE*` or `COPYING*`). A package that ships no licence file is listed without the text. Your project's own source is not listed.
+
+Deploy the file together with the bundles, so the notices those licences ask for travel with every copy. The build lists licences; it does not judge whether a licence suits your product. Two kinds of package are not in the list, so add their notices yourself when you use them:
+
+- packages used only inside a web worker, which are bundled separately;
+- packages a stylesheet reaches on its own, through CSS `@import`, Sass `@use` or `url()`. A stylesheet imported from JavaScript or TypeScript (`import 'some-font/index.css'`) is listed.
+
 #### Bundle-size budgets
 
 Application-spec projects can set gzip-size limits for the standalone configurator and webhook bundles. Add the optional `budgets` section to a spec YAML file:
@@ -362,6 +390,8 @@ Removes all build artifacts (`.phoenix/`, `node_modules/`), reinstalls dependenc
 
 Syncs project dependencies and regenerates all project files without building Vite bundles or webhooks. Faster than `clean` — use this for routine updates after changing spec files or upgrading dependencies. Before installing, it adds the pnpm settings `phoenix init` writes to a standalone project's `pnpm-workspace.yaml` when they are missing; values you set there are kept.
 
+With the application-spec pipeline (see [Current and legacy project tooling](#current-and-legacy-project-tooling)), `.gitignore` is written only when the project is inside a git repository: the project folder or one of its parent folders holds a `.git` entry. Outside a repository, sync neither creates the file nor changes one that is already there, and the same holds for `dev`, `build` and `clean`. Run `git init` before the first sync, or sync again after it, to get the file. The legacy pipeline writes `.gitignore` in every project.
+
 | Flag             | Env Variable    | Default | Description                    |
 | ---------------- | --------------- | ------- | ------------------------------ |
 | `--force` / `-f` | `FORCE_REBUILD` | `false` | Force full rebuild, skip cache |
@@ -457,6 +487,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`
@@ -569,18 +678,20 @@ 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 approve the sign-in (use `--no-open` to only print the link).
+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.
+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.
+
+**Deny** in Studio stops the CLI at once: it exits with `The sign-in was denied in Studio` and no token is created. The link works for five minutes and only for the CLI that printed it; after that, Studio shows that it no longer works and the CLI gives up.
 
 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.
 
@@ -592,28 +703,32 @@ Revokes the token on the server and removes it from the credentials file. `--reg
 
 ### `phoenix deploy`
 
-Validates the spec, adds the pnpm settings `phoenix init` writes to `pnpm-workspace.yaml` when they are missing, packs and uploads the project, starts its build on the server and follows it until the configurator is live. Once the build starts it prints `Follow the build in Studio: <url>`, the build's page in the Studio you signed in through; a sign-in stored by an older CLI has no Studio URL, so sign in again to get the link. `--region` or `--serverUrl` selects the server, as for `login`; `--no-wait` returns as soon as the build starts.
+Validates the spec, adds the pnpm settings `phoenix init` writes to `pnpm-workspace.yaml` when they are missing, packs and uploads the project, starts its build on the server and follows it until the configurator is live. Before the upload the server compares the domain model with the deployed one: a model that changed under an already deployed model version is refused with the reason, and needs a new model version and a [migration](?path=/docs/phoenix-migrations--docs). Once the build starts it prints `Follow the build in Studio: <url>`, the build's page in the Studio you signed in through; a sign-in stored by an older CLI has no Studio URL, so sign in again to get the link. After `Your configurator is live at <url>` it prints one line for coding agents, which tells them to offer the run evaluation of the `phoenix-feedback` skill once you have nothing more to build; you can ignore it when you run the command yourself. `--region` or `--serverUrl` selects the server, as for `login`; `--no-wait` returns as soon as the build starts.
 
-### `phoenix feedback <message>`
+### `phoenix feedback [message]`
 
 Sends feedback about the SDK, the CLI, the documentation or Studio to the Phoenix team. It needs `phoenix login`: the server records the workspace, user and API token of the sign-in, so the message itself needs no introduction.
 
 ```bash
 phoenix feedback "phoenix build reports a missing entity when a module file is empty" --type bug
+phoenix feedback --file report.txt --type bug
 ```
 
-| Flag                   | Env            | Default                       | Description                                          |
-| ---------------------- | -------------- | ----------------------------- | ---------------------------------------------------- |
-| `--type`               | —              | `other`                       | What the feedback is about: `bug`, `idea` or `other` |
-| `--contact`            | —              | —                             | How to reach you, when you want a reply              |
-| `--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     |
+Pass the message as the argument for a short note, or `--file` for a longer report: the content of the file is the message, read as UTF-8, so quotes, backticks and new lines arrive unchanged. Giving both, or neither, is an error.
+
+| Flag                   | Env            | Default                       | Description                                               |
+| ---------------------- | -------------- | ----------------------------- | --------------------------------------------------------- |
+| `--file`               | —              | —                             | Text file that holds the message, instead of the argument |
+| `--type`               | —              | `other`                       | What the feedback is about: `bug`, `idea` or `other`      |
+| `--contact`            | —              | —                             | How to reach you, when you want a reply                   |
+| `--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          |
 
-A message holds at most 5000 characters. Besides the message and the flags, the CLI sends only the SDK version, the operating system and the Node.js version; nothing of the project's files is attached. 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.
+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.
 
-Generated projects carry the `phoenix-feedback` agent skill. It tells coding agents when to draft feedback, to show you the draft and send it only after you approve it, and what must never go into it: secrets, customer data and the project's source. The command needs a server with API 1.40.0 or newer.
+Generated projects carry the `phoenix-feedback` agent skill. It tells coding agents when to draft feedback, to show you the draft and send it only after you approve it, and how to write a report: the build id with its Studio page link, the live configurator link, what the agent was doing, what happened and what was expected, the exact error or output, the workaround and a condensed conversation log. When you say you are done, or a deploy went live and you confirm the run is finished, the agent asks you to evaluate the run, one question at a time: minutes spent, then a score from 0 to 10 for the agent's guidance, the configurator's functionality, its UX, the quality of the 3D, the UI visuals and the overall result, then your comments. It never picks a score for you and sends nothing when you decline. Secrets, credentials and personal data never go into a message; file paths, spec and code snippets and your own words may, once you approved the draft that contains them. The command needs a server with API 1.40.0 or newer; a message over 5000 characters needs API 1.43.0 or newer.
 
 ## Next Steps