@salsita-ai/sdk 0.50.0-develop.da8d27f5d7 → 0.50.0-develop.db8514eccf

package/dist/docs/phoenix/finalization.mdx

@@ -355,4 +355,4 @@ Now that you understand finalization workflows, explore these related topics:
 - **[Admin](?path=/docs/phoenix-admin--docs)** - Learn about admin finalization and published data generation
 - **[Best Practices](?path=/docs/phoenix-best-practices--docs)** - Follow proven patterns for finalization implementation
 
-For hands-on practice, explore the finalize demo in the **[Quickstart](?path=/docs/phoenix-quickstart--docs)** guide.
+For hands-on practice, explore the Precision demo (`packages/demos/demo-precision/`) for finalization resources — PDF, CSV, images, email attachments and callbacks — and the Catalog Builder demo (`packages/demos/demo-catalog-builder/`) for the finalization data lifecycle and access links.

package/dist/docs/phoenix/integration/headless-mode-external.mdx

@@ -51,11 +51,11 @@ For details on the server-side token exchange, see [Authentication](?path=/docs/
 
 The `power` attribute controls the configurator's state:
 
-| Value       | Behavior                                                                                                                                                 |
-| ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `"off"`     | Completely inactive. No rendering, no session, no network requests beyond loading the bundle.                                                            |
-| `"standby"` | Session initialized, assets preloaded (3D models, textures), but not rendered. Faster power-on, but consumes bandwidth and counts toward session quotas. |
-| `"on"`      | Fully active and visible.                                                                                                                                |
+| Value       | Behavior                                                                                                                                                                                                                 |
+| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `"off"`     | Completely inactive. No rendering, no session, no network requests beyond loading the bundle.                                                                                                                            |
+| `"standby"` | Session initialized and any textures listed in `resourcesConfig.prefetchTextureUrls` prefetched; nothing is rendered and no models are loaded. Faster power-on, but consumes bandwidth and counts toward session quotas. |
+| `"on"`      | Fully active and visible.                                                                                                                                                                                                |
 
 A typical flow: power on at login (`"standby"`), then toggle between `"on"` and `"standby"` as the user opens and closes the configurator. Use `"off"` only before the user has authenticated.
 

package/dist/docs/phoenix/integration/widget-mode-external.mdx

@@ -28,11 +28,11 @@ The configurator fills its parent container. Set a height on the element or a wr
 
 The `power` attribute controls whether the configurator is active. It accepts three values:
 
-| Value       | Behavior                                                                                                                                                                                             |
-| ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `"off"`     | Configurator is completely inactive. No rendering, no session initialization, no network requests beyond loading the bundle. Lowest resource usage.                                                  |
-| `"standby"` | Configurator initializes its session and preloads assets (3D models, textures), but does not render. Subsequent power-on is faster, but consumes bandwidth and counts toward monthly session quotas. |
-| `"on"`      | Configurator is fully active and visible.                                                                                                                                                            |
+| Value       | Behavior                                                                                                                                                                                                                                              |
+| ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `"off"`     | Configurator is completely inactive. No rendering, no session initialization, no network requests beyond loading the bundle. Lowest resource usage.                                                                                                   |
+| `"standby"` | Configurator initializes its session and prefetches any textures listed in `resourcesConfig.prefetchTextureUrls`, but does not render or load models. Subsequent power-on is faster, but consumes bandwidth and counts toward monthly session quotas. |
+| `"on"`      | Configurator is fully active and visible.                                                                                                                                                                                                             |
 
 ### Choosing the Initial Power
 

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

@@ -327,15 +327,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:
@@ -457,6 +491,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,9 +682,11 @@ 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.
 
@@ -592,28 +707,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
 

package/dist/docs/phoenix/project-structure.mdx

@@ -40,6 +40,7 @@ project-root/
 | `components/`   | Phoenix system components (ECS)                                        |
 | `elements/`     | Page elements (pages, providers)                                       |
 | `expressions/`  | Domain logic expressions                                               |
+| `actions/`      | Implementations of the domain actions declared under `actions:`        |
 | `invariants/`   | Domain constraints                                                     |
 | `transformers/` | Data transformation logic                                              |
 | `handlers/`     | Event & lifecycle handlers                                             |
@@ -188,7 +189,7 @@ type CustomMaterial = Phx['AdminModel']['CustomMaterial']
 
 ### DO NOT EDIT (Fully Auto-Generated)
 
-- **Everything in `.phoenix/`** - Completely regenerated on each build
+- **Everything in `.phoenix/`** - Completely regenerated on each build. The one exception is `.phoenix/variants/`, where a coding agent writes the option files for `phoenix variants`; a rebuild keeps it
 - `tsconfig.json`, `eslint.config.js`, `prettier.config.js`, `.prettierignore`
 - `.linguirc`, `.nvmrc`
 - `src/locales/**/*.ts` - Compiled from `.po` catalogs
@@ -197,7 +198,7 @@ type CustomMaterial = Phx['AdminModel']['CustomMaterial']
 
 ### Agent Guidance
 
-Coding agents (Claude Code, Codex, Cursor) read `AGENTS.md` and the Phoenix agent skills. `AGENTS.md` is written once with the build commands, the do-not-edit list and a pointer to the skills; after that it is yours. The `phoenix`, `phoenix-cli`, `phoenix-feedback` and `phoenix-review` skills carry the SDK conventions, CLI tooling and review checklist, and the `phoenix-create-configurator` skill walks the agent from your product documents and assets to a reviewed configurator in five stages. Phoenix keeps them in step with the installed SDK, including the reference files inside a skill folder. During the internal beta, a project created from a canary build of the SDK gets one more section in the `phoenix` skill: once per conversation the agent checks for a newer canary and, after telling you, updates the project's SDK and runs `phoenix sync`. Other skill folders are never touched.
+Coding agents (Claude Code, Codex, Cursor) read `AGENTS.md` and the Phoenix agent skills. `AGENTS.md` is written once with the build commands, the do-not-edit list and a pointer to the skills; after that it is yours. The `phoenix`, `phoenix-cli`, `phoenix-feedback` and `phoenix-review` skills carry the SDK conventions, CLI tooling and review checklist, and the `phoenix-create-configurator` skill walks the agent from your product documents and assets to a reviewed configurator in five stages. The `phoenix-variants` skill has the agent show you several options over the dev preview when a decision is a matter of taste, and build the one you pick. Phoenix keeps them in step with the installed SDK, including the reference files inside a skill folder. During the internal beta, a project created from a canary build of the SDK gets one more section in the `phoenix` skill: once per conversation the agent checks for a newer canary and, after telling you, updates the project's SDK and runs `phoenix sync`. Other skill folders are never touched.
 
 Projects created by earlier SDK versions had this guidance in `CLAUDE.md`, `.cursor/rules/phoenix.mdc` and `commands/review.md`. Sync removes the SDK block from the first two, keeps your own text around it, deletes a file that held nothing else, and deletes the review commands; use the `phoenix-review` skill instead of `/review`.
 
@@ -249,6 +250,7 @@ project-root/
 │   ├── components/                # Phoenix system components (ECS)
 │   ├── elements/                  # UI elements (pages, providers)
 │   ├── expressions/               # Domain logic expressions
+│   ├── actions/                   # Domain action implementations
 │   ├── invariants/                # Domain constraints
 │   ├── transformers/              # Data transformation logic
 │   ├── handlers/                  # Event & lifecycle handlers
@@ -314,6 +316,7 @@ project-root/
 │   │   └── builders.ts
 │   ├── .swc/                      # SWC transpiled sources
 │   ├── .lingui/                   # Compiled i18n catalogs
+│   ├── variants/                  # Option files of `phoenix variants`, written by coding agents
 │   ├── dist/                      # Build output
 │   │   ├── frontend/              # Frontend bundles
 │   │   └── webhooks/              # Webhook bundles
@@ -362,6 +365,7 @@ Domain logic files define the business rules and computed properties of your con
 | Purpose      | Location            | Example Files                                  |
 | ------------ | ------------------- | ---------------------------------------------- |
 | Expressions  | `src/expressions/`  | `table.ts`, `legs.ts`, `module.ts`             |
+| Actions      | `src/actions/`      | `move-part.ts`, `swap-cabinets.ts`             |
 | Invariants   | `src/invariants/`   | `top.ts`, `legs.ts`                            |
 | Transformers | `src/transformers/` | `fix-table-top-material-update-transformer.ts` |
 | Migrations   | `src/migrations/`   | `v2.ts`, `v3.ts`, `v4.ts`                      |
@@ -510,7 +514,7 @@ The `application.yaml` file contains global application-level settings. These fi
 | Field                | Type     | Description                                                                                                                                                                                       |
 | -------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `project`            | `string` | Server project `phoenix dev` develops in: a project slug, or `default` for the default project of the signed-in workspace. Read only by the CLI; overridden by `--projectSlug` and `PROJECT_SLUG` |
-| `applicationVersion` | `string` | Semantic version (`x.y.z`) exported as `ApplicationVersion` constant and stored on the deployment record                                                                                          |
+| `applicationVersion` | `string` | Semantic version (`x.y.z`) exported as `ApplicationVersion` constant, stored on the deployment record and named in the banner comment of built bundles                                            |
 | `webComponentTag`    | `string` | Custom HTML web component tag name for embedding                                                                                                                                                  |
 | `pageTitle`          | `string` | Browser page title                                                                                                                                                                                |
 

package/dist/docs/phoenix/sdk-builder-workflow.mdx

@@ -36,11 +36,11 @@ The starter `spec/application.yaml` begins with `project: default`, which means
 pnpm phoenix login <workspace>
 ```
 
-`phoenix login` opens Studio, where you approve the sign-in. Studio sends a one-time code back to the CLI on `127.0.0.1`, and the CLI exchanges it for a personal token. The code only works for the CLI that asked for it and expires after five minutes. Use `--no-open` to print the link instead of opening a browser.
+`phoenix login` opens Studio, where you name the token and approve the sign-in. Only a super admin of the workspace can open Studio, so only a super admin can approve it. The CLI suggests `phoenix CLI on <computer>`; a name of your own, such as the agent and the machine, tells your tokens apart later. Studio sends a one-time code back to the CLI on `127.0.0.1`, the CLI exchanges it for a personal token and returns the browser to Studio, which confirms the sign-in. The code only works for the CLI that asked for it and expires after five minutes. **Deny** stops the waiting CLI at once and creates no token. Use `--no-open` to print the link instead of opening a browser.
 
 The CLI stores the token in `~/.phoenix/credentials.json`, readable only by you, with one entry per server. `PHOENIX_CREDENTIALS_FILE` moves the file. The token acts for you in your workspace until you revoke it. It stops working when you are removed from the workspace or banned.
 
-`pnpm phoenix logout` revokes the token and removes it from the file. Studio's **CLI tokens** page lists your tokens with when they were last used, and revokes any of them, for example one left on another computer.
+`pnpm phoenix logout` revokes the token and removes it from the file. Studio's **CLI tokens** page lists your tokens by the names you gave them, with when they were last used, and revokes any of them, for example one left on another computer. A revoked token leaves the list.
 
 `login`, `logout` and `deploy` follow the region, not the `SERVER_URL` in the project's `.env`. `dev` follows the region too when `.env` has no `SERVER_URL`:
 
@@ -59,7 +59,7 @@ pnpm phoenix dev
 
 Signed in, `phoenix dev` needs no `.env` and nothing set up in Studio. When it starts, it asks the server for your development environment in the project the spec names. The server creates that environment the first time and finds it again on every later run. `phoenix dev` prints the workspace, project and environment it works in, prepares a development deployment there and opens the webhook tunnel, as for any Phoenix project (see [Phoenix CLI](?path=/docs/phoenix-phoenix-cli--docs)). It then prints the address of the preview as `Preview: <url>`; the preview talks to the server the deployment was prepared on.
 
-Every user of the workspace gets their own development environment, so a teammate who clones the project and signs in doesn't overwrite your schema or take over your webhooks. The development environment is separate from `production`: nothing you do in `phoenix dev` changes the live configurator.
+Every user who signs the CLI in gets their own development environment, so a teammate (a super admin of the workspace, like you) who clones the project and signs in doesn't overwrite your schema or take over your webhooks. The development environment is separate from `production`: nothing you do in `phoenix dev` changes the live configurator.
 
 `pnpm dev:local` still runs the project without any server, with state kept in the browser.
 
@@ -77,8 +77,9 @@ pnpm phoenix deploy
 
 1. It validates the application spec.
 2. It packs the project files: the `.yaml` files in `spec`, everything in `src`, `mocks`, `assets`, `public` and `templates`, and `package.json`, `pnpm-lock.yaml`, `pnpm-workspace.yaml`, `.gitignore`, `CLAUDE.md` and `.cursor/rules/phoenix.mdc`. Every `node_modules`, `.phoenix` and `__generated` folder, every `.DS_Store` and `._*` file and every `.env` and `.env.*` file are left out, at any depth.
-3. It uploads the archive, which may be up to 200 MB.
-4. It starts the build, prints a link to the build's page in Studio and follows the build until your configurator is live, then prints its URL.
+3. It asks the server for a build. The server compares your domain model with the deployed one and refuses, before anything is uploaded, a model that changed under an already deployed model version; see [Migrations](?path=/docs/phoenix-migrations--docs).
+4. It uploads the archive, which may be up to 200 MB.
+5. It starts the build, prints a link to the build's page in Studio and follows the build until your configurator is live, then prints its URL.
 
 On the server, the install follows your `pnpm-lock.yaml` and `pnpm-workspace.yaml`, so it allows the same build scripts and package versions as `pnpm install` on your computer. The build runs without platform secrets. It sees only your own environment variables and the public platform values, the [build environment](?path=/docs/phoenix-phoenix-cli--docs) that `phoenix deployment:build-envs` writes. The trusted deploy step then publishes the frontend, webhooks and assets.
 
@@ -93,15 +94,18 @@ Studio's **Builds & deployments** page lists your builds and shows which one you
 Tell us what is broken, confusing or missing, from wherever you are:
 
 - In Studio, **Send beta feedback** in the sidebar opens a short form.
-- In the terminal, `pnpm phoenix feedback "<message>" --type bug|idea|other` sends it with your sign-in. See the [CLI reference](?path=/docs/phoenix-phoenix-cli--docs).
+- In the terminal, `pnpm phoenix feedback "<message>" --type bug|idea|other` sends it with your sign-in, and `--file <path>` sends a text file instead of the argument. See the [CLI reference](?path=/docs/phoenix-phoenix-cli--docs).
+- On a build's page in Studio, **Download sources** downloads the archive `phoenix deploy` uploaded for that build, so a report only needs to name the build.
 
-Coding agents working in your project use the same command, guided by the generated `phoenix-feedback` skill. They never send on their own: an agent shows you a draft, right away when the problem is crucial and otherwise at the end of the task, and sends it only after you approve it. They are told never to include secrets, customer data or your project's source. After a deploy goes live, the agent also asks you, once per conversation, to rate building with Phoenix from 0 to 10; it tells you the answer goes to the Phoenix team, shows the message and sends it only after you approve it.
+Coding agents working in your project use the same command, guided by the generated `phoenix-feedback` skill. They never send on their own: an agent shows you a draft, right away when the problem is crucial and otherwise at the end of the task, and sends it only after you approve it. A report names the build with its Studio page link and the live configurator, says what the agent was doing, what happened and what it expected, quotes the exact error and ends with a condensed conversation log. Agents are told never to include secrets, credentials or personal data; parts of your project and your own words go in only through a draft you approved. When you are done with the configurator, the agent also asks you, once per conversation, to evaluate the run: minutes spent, then scores from 0 to 10 for the agent's guidance, functionality, UX, 3D quality, UI visuals and the overall result, and your comments. It asks one question at a time, never picks a score for you, tells you the answers go to the Phoenix team, shows the message and sends it only after you approve it.
 
 ## Known limits
 
 - You can deploy once the workspace's first deployment is live. Until then, `phoenix deploy` tells you the workspace is still being set up.
+- The first deployment is the starter, so the starter's model is version 1 in production. Replacing it with your own model needs the starter's model kept as `v1` and a migration to version 2; [Migrations](?path=/docs/phoenix-migrations--docs) shows the migration for replacing a model entirely.
 - One workspace has one project, one `production` environment and one development environment per user.
 - `phoenix deploy` always deploys to the workspace's default project; it doesn't read `project` from the spec yet.
 - Only `phoenix dev` works from the sign-in. `phoenix deployment:prepare-dev` still needs the `.env` block of a Studio development environment.
 - Every deploy uploads the whole project; there are no incremental uploads.
-- Your own environment variables can't use platform names such as `LAMBDA_FUNCTION_NAME` or the `AWS_` prefix. A deploy that sets them fails before it registers.
+- Your own environment variables are set in Studio under Environment, by a super admin of the workspace, and apply from the next deploy. `phoenix dev` doesn't receive them: your development environment has its own variables. A build reads them from `process.env`; a webhook reads the ones the spec declares under `env.webhook`, through `phx.webhooksEnv` (see [Webhooks](?path=/docs/phoenix-webhooks--docs)). They can't use platform names such as `LAMBDA_FUNCTION_NAME`, the `AWS_` prefix, the identity provider settings such as `CLERK_API_KEY`, or names the CLI and the deploy tooling read themselves, such as `SERVER_URL` or `NODE_OPTIONS`; Studio refuses those names.
+- Only super admins of a workspace can open its Studio. Admins and users see a page that says so.

package/dist/domain/actions/action-factory.d.ts

@@ -0,0 +1,10 @@
+import type { ActionImplementations, ActionTypes } from '../core/action.js';
+import type { $DomainEntity, DomainEntity } from '../core/model.js';
+/**
+ * Creates the `implementActions` factory the generated `domain-spec.ts` exposes as
+ * `phx.domain.implementActions`. A module in `src/actions/` implements any subset of the declared
+ * actions and gets each parameter and result typed from the spec; a name the spec does not declare
+ * is a type error, since its implementation would have to be `never`. The generated barrel merges
+ * the modules and checks that every declared action is implemented.
+ */
+export declare const createActionFactory: <ENTITIES extends DomainEntity<string>, ALLOWED_ROOT_ENTITIES extends ENTITIES, $MAP extends Record<ENTITIES['type'], $DomainEntity<ENTITIES>>, PUBLISHED_DATA extends Record<string, unknown>, SESSION_DATA extends Record<string, unknown>, FRONTEND_DATA extends Record<string, unknown>, NAVIGATION_STATES extends string, VIEW_STATES extends string, TOOL_STATES extends string, EXPORT_STATES extends string, ACTION_TYPES extends ActionTypes>() => <IMPLEMENTATIONS extends Partial<ActionImplementations<ENTITIES, ALLOWED_ROOT_ENTITIES, $MAP, PUBLISHED_DATA, SESSION_DATA, FRONTEND_DATA, NAVIGATION_STATES, VIEW_STATES, TOOL_STATES, EXPORT_STATES, ACTION_TYPES>>>(implementations: IMPLEMENTATIONS & Readonly<Record<Exclude<keyof IMPLEMENTATIONS, keyof ACTION_TYPES>, never>>) => IMPLEMENTATIONS;

package/dist/domain/actions/action-factory.js

@@ -0,0 +1 @@
+export const createActionFactory=()=>t=>t;

package/dist/domain/actions/prepare-action-implementations.d.ts

@@ -0,0 +1,15 @@
+import type { ActionDefinitions, AnyActionImplementations } from '../core/index.js';
+/** The declared actions that have no implementation, and the implementations of undeclared names. */
+export interface ActionImplementationConflicts {
+    readonly missing: readonly string[];
+    readonly extra: readonly string[];
+}
+/** Compares the names of the declared actions with the implemented ones. */
+export declare const findActionImplementationConflicts: (declared: readonly string[], implementations: AnyActionImplementations) => ActionImplementationConflicts;
+/**
+ * Validates the implemented actions against the declared ones, as `prepareDomainExpressions` does
+ * for expressions: a declared action without an implementation throws, so the domain is not
+ * instantiated with an action that can only fail when it is called; an implementation of an
+ * undeclared name is logged. Returns the implementations unchanged.
+ */
+export declare const prepareActionImplementations: (definitions: ActionDefinitions, implementations: AnyActionImplementations) => AnyActionImplementations;

package/dist/domain/actions/prepare-action-implementations.js

@@ -0,0 +1,5 @@
+export const findActionImplementationConflicts=(e,n)=>{let t=Object.keys(n);return{missing:e.filter(e=>!t.includes(e)),extra:t.filter(n=>!e.includes(n))}};export const prepareActionImplementations=(e,n)=>{let{missing:t,extra:i}=findActionImplementationConflicts(Object.values(e).map(e=>e.name),n);if(0===t.length&&0===i.length)return n;let o=Error("Domain cannot be instantiated because there are conflicts between declared and implemented actions."+(t.length>0?`
+
+Missing actions: ${t.join(", ")}. Add each to a default export of phx.domain.implementActions({ ... }) in src/actions/.`:"")+(i.length>0?`
+
+Extra actions: ${i.join(", ")}. Declare each under "actions" in a spec file or remove its implementation.`:"")+"\n");if(t.length>0)throw o;return console.error(o),n};

package/dist/domain/application/application-config.d.ts

@@ -112,7 +112,8 @@ export interface AssistantFieldOptions {
  * the recipe groups `meta { childRecipes }` and `addChild` expose, in manifest order, and absent
  * means none; `replaceRecipes` lists the same for `meta { replaceRecipes }` and `replaceEntity`;
  * `fieldOptions` lists, per entity type, the options edges `meta` exposes for its
- * writable fields, and absent means none. Consumed by the configurator GraphQL system.
+ * writable fields, and absent means none; `actions` maps each custom `Mutation` field to the
+ * declared action it runs, and absent means none. Consumed by the configurator GraphQL system.
  */
 export interface AssistantManifest {
     readonly sdl: string;
@@ -122,6 +123,7 @@ export interface AssistantManifest {
     readonly childRecipes?: Readonly<Record<string, readonly AssistantRecipeGroup[]>>;
     readonly replaceRecipes?: Readonly<Record<string, readonly AssistantRecipeGroup[]>>;
     readonly fieldOptions?: Readonly<Record<string, readonly AssistantFieldOptions[]>>;
+    readonly actions?: Readonly<Record<string, string>>;
 }
 export type AdminPagesSpec = {
     readonly presets?: boolean | {