@salsita-ai/sdk 0.50.0-develop.f16492b14e → 0.50.0-develop.f354d3576d

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

@@ -80,9 +80,10 @@ a file can share its name with a file in another entity folder.
 
 Two naming limits still apply:
 
-- Transformer file names must be unique across all subfolders of `src/transformers/`, because each transformer
-  registers under its file name. Application-spec projects also treat names that differ only in letter case or dashes
-  as the same name.
+- Transformer file names must be unique across all subfolders of `src/transformers/`, and names that differ only in
+  letter case or dashes count as the same name: each `transformers:` entry of the spec names the file that holds its
+  transformer that way. The transformer the file builds carries the entry's name exactly, as `build('clampWidth')`
+  does for the entry `clampWidth`.
 - Files named `index.ts` inside entity folders are not auto-registered, except in application-spec projects. Give
   entity files descriptive names instead.
 
@@ -155,7 +156,7 @@ In a project on the legacy pipeline (see [Current and legacy project tooling](?p
 
 A project installs with any package manager: pnpm, npm, Yarn or Bun. Phoenix writes no package-manager settings and no `packageManager` field; the lockfile, `pnpm-workspace.yaml`, `.npmrc` and `.yarnrc.yml` are the project's own. Run `phoenix` through the package manager the project uses, such as `pnpm phoenix sync` or `npx phoenix sync`.
 
-A project that installs with pnpm 11 needs a `pnpm-workspace.yaml` in its root before the first install. pnpm 11 stops an install until every dependency build script is allowed or denied, and the SDK's dependencies have three. Its default minimum release age also refuses a package published only recently, so the exclusion lets the project install an SDK build on the day it is released; it is optional:
+A project that installs with pnpm 11 needs a `pnpm-workspace.yaml` in its root before the first install. pnpm 11 stops an install until every dependency build script is allowed or denied, and the SDK's dependencies have three. An install that skipped a build script writes a placeholder entry under `allowBuilds` instead of `true` or `false`; replace it, because the platform build stops on it and `phoenix deploy` refuses it. Its default minimum release age also refuses a package published only recently, so the exclusion lets the project install an SDK build on the day it is released; it is optional:
 
 ```yaml
 allowBuilds:
@@ -179,9 +180,9 @@ Phoenix generates typed interfaces available globally:
 
 Types are auto-generated in `.phoenix/` from your domain schema:
 
-- `.phoenix/configurator-interface.ts` - Configurator interface types
-- `.phoenix/admin-interface.ts` - Admin interface types
-- `.phoenix/globals.d.ts` - Global type definitions
+- `.phoenix/configurator-globals.ts` - assigns `phx.frontend`
+- `.phoenix/admin-globals.ts` - assigns `phx.frontend.admin`
+- `.phoenix/globals.d.ts` - the type of the `phx` global
 
 Access in code:
 
@@ -199,23 +200,23 @@ type CustomMaterial = Phx['AdminModel']['CustomMaterial']
 
 ### Root Level Files
 
-| File                                                 | Auto-Generated? | Notes                                 |
-| ---------------------------------------------------- | --------------- | ------------------------------------- |
-| `package.json`                                       | No              | Yours; see Dependencies               |
-| `tsconfig.json`                                      | Once            | Yours; see below                      |
-| `eslint.config.js`                                   | Once            | Yours; see below                      |
-| `prettier.config.js`                                 | Once            | Yours; see below                      |
-| `.prettierignore`                                    | No              | Optional and your own; see below      |
-| `pnpm-workspace.yaml`                                | No              | Only with pnpm; see Package manager   |
-| `.gitignore`                                         | Partially       | Only in a git repository; see Markers |
-| `.env`                                               | No              | Git-ignored, local config             |
-| `.env.example`                                       | No              | Template for env vars                 |
-| `.env.generated`                                     | Yes             | Optional, git-ignored; see below      |
-| `README.md`                                          | No              | Project documentation                 |
-| `AGENTS.md`                                          | No              | Your own coding-agent instructions    |
-| `.claude/skills/phoenix/`, `.agents/skills/phoenix/` | Yes             | Phoenix agent skills                  |
-
-Sync does not write `README.md`, `AGENTS.md`, `.env.example`, `.env.ci` or the `README.md` files in `assets/public/` and `assets/private/`. Earlier SDK versions wrote them once; a project that has them keeps them, and they are yours to edit.
+| File                                                 | Auto-Generated? | Notes                                         |
+| ---------------------------------------------------- | --------------- | --------------------------------------------- |
+| `package.json`                                       | No              | Yours; see Dependencies                       |
+| `tsconfig.json`                                      | Once            | Yours; see below                              |
+| `eslint.config.js`                                   | Once            | Yours; see below                              |
+| `prettier.config.js`                                 | Once            | Yours; see below                              |
+| `.prettierignore`                                    | No              | Optional and your own; see below              |
+| `pnpm-workspace.yaml`                                | No              | Only with pnpm; see Package manager           |
+| `.gitignore`                                         | Partially       | Only in a git repository; see Markers         |
+| `.env`                                               | No              | Git-ignored, local config                     |
+| `.env.example`                                       | No              | Template for env vars                         |
+| `.env.generated`                                     | Yes             | Optional, git-ignored; see below              |
+| `README.md`                                          | No              | Project documentation                         |
+| `AGENTS.md`                                          | No              | Project-owned instructions; preserved by sync |
+| `.claude/skills/phoenix/`, `.agents/skills/phoenix/` | Yes             | SDK-managed files; see below                  |
+
+With the application-spec pipeline, sync does not write `README.md`, `.env.example`, `.env.ci` or the `README.md` files in `assets/public/` and `assets/private/`. These files are yours to create and edit; sync preserves them. The legacy pipeline writes `README.md`, `.env.example`, `.env.ci` and the asset-folder `README.md` files when they are missing.
 
 Phoenix keeps the generated env file, with the IDs and values of the prepared deployment, in `.phoenix/` unless the project has a `.env.generated` in its root, which then is the one that counts. `phoenix dev` creates no `.env.generated` in the project root; the deployment and environment commands write it there. See [The generated env file](?path=/docs/phoenix-phoenix-cli--docs#the-generated-env-file).
 
@@ -229,34 +230,26 @@ With the application-spec pipeline, the project's TypeScript settings are in `.p
 
 The only root `tsconfig.json` sync replaces is the full file earlier SDK versions generated there, recognised by its settings; any other stays as it is. `phoenix dev`, `phoenix build` and the webhook bundle do not resolve `paths` aliases, so an alias added to the root file passes `phoenix check` and fails the build. `phoenix check` type-checks with the root `tsconfig.json`, or with `.phoenix/tsconfig.json` when the project has none. The legacy pipeline writes the full `tsconfig.json` on every sync.
 
-With the application-spec pipeline, sync writes `eslint.config.js` and `prettier.config.js` only when the project has none, each re-exporting the SDK's shared configuration so editors find it. They are yours to commit and to change. The only ones sync replaces are the files earlier SDK versions generated there; any other stays as it is. `phoenix check` and `phoenix fix` lint and format with the project's files, and with the SDK's configurations when a file is missing (see [`phoenix check`](?path=/docs/phoenix-phoenix-cli--docs#phoenix-check)). Sync formats the files it generates in the project root, such as the agent skills, with the same Prettier configuration, so `phoenix check` accepts them; while the project's configuration cannot be loaded, as before the first install, they get the SDK's settings. The legacy pipeline writes both files on every sync.
+With the application-spec pipeline, sync writes `eslint.config.js` and `prettier.config.js` only when the project has none, each re-exporting the SDK's shared configuration so editors find it. They are yours to commit and to change. The only ones sync replaces are the files earlier SDK versions generated there; any other stays as it is. `phoenix check` and `phoenix fix` lint and format with the project's files, and with the SDK's configurations when a file is missing (see [`phoenix check`](?path=/docs/phoenix-phoenix-cli--docs#phoenix-check)). Sync formats the files it generates in the project root, such as `tsconfig.json`, with the same Prettier configuration, so `phoenix check` accepts them; while the project's configuration cannot be loaded, as before the first install, they get the SDK's settings. The legacy pipeline writes both files on every sync.
 
 With the application-spec pipeline, the Lingui configuration is `.phoenix/.linguirc`, which sync rewrites with the rest of `.phoenix/` from `availableLocales` in `spec/application.yaml`. Phoenix passes that file to Lingui every time it extracts or compiles the catalogs and to its Vite builds, so a `.linguirc` in the project root is not read and can be deleted. To run Lingui yourself, name the file: `npx lingui extract --config .phoenix/.linguirc`, from the project root. The legacy pipeline writes `.linguirc` in the project root on every sync.
 
 ### DO NOT EDIT (Fully Auto-Generated)
 
-- **Everything in `.phoenix/`** - Completely regenerated on each build. The exceptions are `.phoenix/variants/`, where a coding agent writes the option files for `phoenix variants`, and `.phoenix/.env.generated`, the generated env file of `phoenix dev`; a rebuild keeps both
+- **Generated files in `.phoenix/`** — Rewritten on each build. In application-spec projects, `.phoenix/workspace/` is project-owned: sync, build and clean preserve it, and deploy includes it in the private source archive rather than build inputs or public assets. Rebuilds also keep `.phoenix/variants/`, which holds variant option files, and `.phoenix/.env.generated`, the generated env file of `phoenix dev`.
 - `src/locales/**/*.ts` - Compiled from `.po` catalogs
 - `.env.generated`
-- `phoenix` and `phoenix-*` skill folders under `.claude/skills/` and `.agents/skills/` — rewritten on every sync with anything else inside them removed, and other `phoenix`-prefixed skill folders are removed; to customise a skill, copy it to a folder whose name does not start with `phoenix`
-
-### Agent Guidance
-
-Coding agents (Claude Code, Codex, Cursor) enter through the single `phoenix` skill under `.claude/skills/phoenix/` or `.agents/skills/phoenix/`. Its `SKILL.md` routes to the existing project, CLI, configurator workflow, code review, variants and feedback guides in `references/`. Agents read the guides for their task rather than the whole tree. The configurator workflow retains its five stages and supporting discovery, UX, asset-conversion and appearance-review references.
-
-Phoenix keeps this guidance in step with the installed SDK. During the internal beta, a project created from a canary build gets the canary-update instructions in the linked project guide: once per conversation the agent checks for a newer canary and, after telling you, updates the SDK, runs `phoenix deps`, installs, then runs `phoenix sync`.
-
-An `AGENTS.md` is yours to add; sync does not write one. Sync removes retired `phoenix-*` skill folders but leaves unrelated skills alone. If your own instructions name an earlier separate skill such as `phoenix-review`, point them at `phoenix` and the same task instead.
-
-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; ask `phoenix` to review instead of using `/review`.
+- The SDK-managed `phoenix` and `phoenix-*` folders under `.claude/skills/` and `.agents/skills/` — sync rewrites the current bundle, removes unrecognized files inside it and deletes retired folders with those prefixes. Keep custom files outside those prefixes. Sync also removes the SDK blocks from legacy `CLAUDE.md` and `.cursor/rules/phoenix.mdc`, preserves surrounding project text, deletes files left empty and removes the legacy review-command files.
 
 ### Markers for Partial Auto-Generation
 
-`.gitignore` holds the Phoenix entries between two marker lines. Sync rewrites that block and keeps everything outside it. With the application-spec pipeline the block does not list the files sync writes once, `tsconfig.json`, `eslint.config.js` and `prettier.config.js`, so a project commits them:
+`.gitignore` holds the Phoenix entries between two marker lines. Sync rewrites that block and keeps everything outside it. With the application-spec pipeline the block does not list the files sync writes once, `tsconfig.json`, `eslint.config.js` and `prettier.config.js`, so a project commits them. It ignores generated entries inside `.phoenix/` but leaves `.phoenix/workspace/` available for version control, so working records can travel with a checkout:
 
 ```gitignore
 # ===== BEGIN PHOENIX AUTO-GENERATED =====
-# ... Phoenix-managed ignores ...
+# ... other Phoenix-managed ignores ...
+**/.phoenix/*
+!**/.phoenix/workspace/
 # ===== END PHOENIX AUTO-GENERATED =====
 
 # Your custom ignores (preserved)
@@ -267,6 +260,8 @@ With the application-spec pipeline (see [Current and legacy project tooling](?pa
 
 ### Safe to Edit
 
+- `.phoenix/workspace/` (application-spec project records and specification sources; include durable records in version control)
+- `docs/` (client documents such as rendered specification PDFs; deploy includes them in the private source archive, not in build inputs or public assets)
 - `src/` (except compiled `src/locales/**/*.ts` files)
 - `spec/`
 - `public/`
@@ -278,7 +273,7 @@ With the application-spec pipeline (see [Current and legacy project tooling](?pa
 - `.env`, `.env.example`, `.env.ci`
 - `tsconfig.json` (application-spec pipeline; keep it extending `.phoenix/tsconfig.json`)
 - `eslint.config.js`, `prettier.config.js` (application-spec pipeline; sync writes them once, and they are the project's afterwards)
-- `README.md`, `AGENTS.md`
+- `README.md`
 
 ## File Naming Conventions
 
@@ -359,32 +354,30 @@ project-root/
 │
 ├── blender/                       # 3D model source files (Blender)
 │
-├── .phoenix/                      # AUTO-GENERATED (DO NOT EDIT)
-│   ├── domain/                    # Compiled domain specs
-│   │   ├── model/                 # Configurator model
-│   │   └── admin-model/           # Admin model
-│   ├── webhooks/                  # Generated webhook files
-│   │   ├── index.ts
-│   │   └── builders.ts
-│   ├── .swc/                      # SWC transpiled sources
-│   ├── .lingui/                   # Compiled i18n catalogs
-│   ├── variants/                  # Option files of `phoenix variants`, written by coding agents
+├── .phoenix/                      # Generated output, except the project-owned workspace/
+│   ├── workspace/                 # Specification sources and project records, available for version control
+│   ├── variants/                  # Option files of `phoenix variants`; kept by rebuilds, removed by clean
 │   ├── dist/                      # Build output
-│   │   ├── frontend/              # Frontend bundles
-│   │   └── webhooks/              # Webhook bundles
 │   ├── public -> ../public        # Symlink to public
+│   ├── application-spec.json      # The parsed application spec
+│   ├── domain-spec.ts             # Domain model and reflections; assigns `phx.domain`
+│   ├── spec-code.ts               # Code generated from the spec
+│   ├── spec-messages.ts           # Messages of the spec
 │   ├── domain.ts                  # Domain exports
 │   ├── configurator.ts            # Configurator entry
+│   ├── configurator-config.ts     # Configurator configuration
+│   ├── configurator-globals.ts    # Assigns `phx.frontend`
+│   ├── embedded-configurator.ts   # Embedded configurator entry
 │   ├── admin.ts                   # Admin entry
+│   ├── admin-config.ts            # Admin configuration
+│   ├── admin-globals.ts           # Assigns `phx.frontend.admin`
 │   ├── embedded-admin.ts          # Embedded admin entry
+│   ├── webhook.ts                 # Webhook entry
+│   ├── webhook-builders.ts        # Assigns `phx.webhooks`
 │   ├── editor.tsx                 # Editor component
-│   ├── frontend.config.ts         # Frontend configuration
-│   ├── webhooks.config.ts         # Webhook configuration
-│   ├── phoenix.config.ts          # Phoenix framework config
-│   ├── configurator-interface.ts  # Configurator interface types
-│   ├── admin-interface.ts         # Admin interface types
-│   ├── i18n.ts                    # i18n initialization
-│   ├── globals.d.ts               # Global type definitions
+│   ├── frontend.config.ts         # Frontend runtime configuration
+│   ├── webhooks.config.ts         # Webhook runtime configuration
+│   ├── globals.d.ts               # The type of the `phx` global
 │   ├── tsconfig.json              # TypeScript settings, extended by the root tsconfig.json
 │   ├── .linguirc                  # Lingui configuration
 │   ├── index.html                 # Configurator HTML entry

package/dist/docs/phoenix/quickstart.mdx

@@ -267,7 +267,7 @@ export default phx.domain.implementCustomExpressions({
 })
 ```
 
-Application projects receive `phx` as a global. Storybook examples cannot rely on that project environment, so the complete example below imports it from `../../.phoenix/phx.js`; that import is the only intentional difference.
+Application projects receive `phx` as a global. Storybook examples cannot rely on that project environment, so the example's files import it from `../../.phoenix/phx.js`; a project leaves that import out, the only intentional difference.
 
 After sync, the property panel offers Grey, Black, and White. Selecting one updates the domain field, recomputes `$frameColor`, and smoothly changes the real `metalMaterial` in the model. Explore the individual pieces in [Attribute List Selector](?path=/docs/controls-select-attribute-listselect--docs) and [Material Transition](?path=/docs/3d-scene-materials-transition--docs).
 
@@ -1092,8 +1092,6 @@ components:
 ### ./src/expressions/table.ts
 
 ```ts
-import { phx } from '../../.phoenix/phx.js'
-
 const FRAME_COLORS = {
   Grey: '#6f7378',
   Black: '#202124',

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

@@ -22,7 +22,7 @@ pnpm install
 pnpm phoenix sync
 ```
 
-`phoenix init [folder]` writes the starter project: `package.json` and the starter spec, `spec/application.yaml` and `spec/configurator.yaml`, which describe one box you can resize and recolour. The starter depends on the same SDK version as the CLI that created it and on the packages the SDK requires next to it (React, three.js, MUI, Lingui and the others, with their type packages), with ESLint and Prettier at the versions the SDK uses itself. Its `package.json` has the `dev`, `build`, `deploy`, `check` and `fix` scripts, which are yours to change. `phoenix sync` then adds the rest of the project: the TypeScript, lint and formatting config and the agent skills. It writes no webhook code: a project without `src/webhooks/index.ts` gets a built-in webhook (see [Webhook Entry Point](?path=/docs/phoenix-webhooks--docs#webhook-entry-point)). It writes a `.gitignore` only when the folder is inside a git repository; run `git init` before the first sync, or sync again after it, to get the file.
+`phoenix init [folder]` writes the starter project: `package.json` and the starter spec, `spec/application.yaml` and `spec/configurator.yaml`, which describe one box you can resize and recolour. The starter depends on the same SDK version as the CLI that created it and on the packages the SDK requires next to it (React, three.js, MUI, Lingui and the others, with their type packages), with ESLint and Prettier at the versions the SDK uses itself. Its `package.json` has the `dev`, `build`, `deploy`, `check` and `fix` scripts, which are yours to change. `phoenix sync` then adds the TypeScript, lint and formatting config and the other generated files described in [Project Structure](?path=/docs/phoenix-project-structure--docs#root-level-files). It writes no webhook code: a project without `src/webhooks/index.ts` gets a built-in webhook (see [Webhook Entry Point](?path=/docs/phoenix-webhooks--docs#webhook-entry-point)). It writes a `.gitignore` only when the folder is inside a git repository; run `git init` before the first sync, or sync again after it, to get the file.
 
 `init` only writes these files: it asks nothing and contacts no server. It refuses a folder that already has a `spec/` folder. A `package.json` already in the folder is kept, as long as it depends on the SDK, and gains only the entries it lacks (see [Starting a New Project](?path=/docs/phoenix-phoenix-cli--docs#starting-a-new-project)).
 
@@ -36,7 +36,7 @@ The starter `spec/application.yaml` begins with `project: default`, which means
 pnpm phoenix login <workspace>
 ```
 
-`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.
+`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 its purpose 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.
 
@@ -63,10 +63,6 @@ Every user who signs the CLI in gets their own development environment, so a tea
 
 `pnpm phoenix dev --persistence local-storage` still runs the project without any server, with state kept in the browser.
 
-Coding agents follow the generated `phoenix` skill: before their first change they start `phoenix dev` and open the preview in your browser, and after `phoenix deploy` starts a build they open its page in Studio.
-
-To build the configurator with your coding agent, give it your product documents, prices, pictures, drawings or models and ask it to create the configurator. The generated `phoenix` skill’s Configurator workflow guide takes it through five stages: a representative first slice you can try early, a plan of the whole configuration experience, options and features added in small increments, finalization, and a complete review. It studies the SDK documentation before building, keeps a `configurator-spec.md` in the project as the record of what is decided and what remains open, and asks you only for decisions it cannot derive from your materials.
-
 ## 4. Deploy
 
 ```bash
@@ -76,7 +72,7 @@ pnpm phoenix deploy
 `phoenix deploy` goes through these steps:
 
 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`, `tsconfig.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.
+2. It packs the project files: the `.yaml` files in `spec`, everything in `src`, `mocks`, `assets`, `public` and `templates`, and `package.json`, `tsconfig.json`, `pnpm-lock.yaml`, `pnpm-workspace.yaml`, `.gitignore`, `CLAUDE.md` and `.cursor/rules/phoenix.mdc`. Project-owned `.phoenix/workspace/` records and the client documents in `docs/` also travel in the private source archive; they are excluded from build inputs and public assets. Other `.phoenix` contents, every `node_modules` and `__generated` folder, every `.DS_Store` and `._*` file and every `.env` and `.env.*` file are left out.
 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.
@@ -99,8 +95,6 @@ Tell us what is broken, confusing or missing, from wherever you are:
 - 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` skill’s Feedback guide. 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.

package/dist/docs/phoenix/state-management.mdx

@@ -315,14 +315,15 @@ const update = phx.frontend.updates.DomainEntityModification({
   updateTag: 'UserResizing',
 })
 
-// Component modification
+// Component modification (distanceDimensionComponent from '@salsita-ai/sdk/domain')
 const componentUpdate = phx.frontend.updates.ComponentModification({
   componentInstance: {
     entityId: 'Cabinet-1',
-    componentType: selectionComponent,
-    instanceName: 'main',
+    componentType: distanceDimensionComponent,
+    instanceName: 'width',
   },
-  writableState: { selected: true },
+  writableState: { value: 1200 },
+  updateTag: 'UserResizing',
 })
 ```
 
@@ -356,7 +357,7 @@ storeSystem.commit()
 
 During commitment:
 
-- OnBeforeCommit hooks can intercept or modify the commit
+- `onBeforeCommit` hooks can hold the commit by returning `false`, for example to ask the user first; a held commit resets the rendered slice, and the hook can commit the same emission later through the `emit` callback it receives. A hook cannot change what is committed
 - Final validation occurs
 - Committed state is emitted to committed slice
 - All attempts (valid or invalid) are emitted to potentiallyInvalid slice
@@ -426,7 +427,7 @@ Validation produces structured results indicating state validity:
 type StateValidationResult =
   | { valid: true, severity: null }  // Perfect state
   | { valid: true, severity: 'warning' | 'notice', entityViolations: [...] }  // Valid with warnings
-  | { valid: false, severity: 'fatal' | 'fixable', entityViolations: [...] }  // Invalid but recoverable
+  | { valid: false, severity: 'fatal' | 'fixable', entityViolations: [...] }  // Invalid, never committed
   | { valid: false, severity: 'uncaught', error: Error }  // Critical error
 ```
 
@@ -434,7 +435,7 @@ type StateValidationResult =
 
 Different violation severities have different behavioral impacts:
 
-**Notice**: Informational only, doesn't affect functionality
+**Notice**: Informational only: the change is committed and saved, and nothing is blocked
 
 ```typescript
 // Example: Suggesting better material combinations
@@ -445,7 +446,7 @@ Different violation severities have different behavioral impacts:
 }
 ```
 
-**Warning**: Alerts user but allows operation
+**Warning**: The change is committed and saved, but the configuration cannot be finalized
 
 ```typescript
 // Example: Performance warnings
@@ -456,18 +457,18 @@ Different violation severities have different behavioral impacts:
 }
 ```
 
-**Fixable**: Prevents some actions but can be auto-corrected
+**Fixable**: Rejected like `fatal`; marks a violation that a project [transformer](?path=/docs/other-features-transformers--docs) repairs before validation. Nothing corrects it automatically: without such a transformer the change is not committed.
 
 ```typescript
 // Example: Dimension constraints
 {
   type: 'dimensionTooLarge',
   severity: 'fixable',
-  message: 'Cabinet width exceeds room width, adjusting automatically'
+  message: 'Cabinet width exceeds room width'
 }
 ```
 
-**Fatal**: Prevents finalization and major operations
+**Fatal**: The change is never committed: it does not reach the rendered state, the undo stack or the saved configuration
 
 ```typescript
 // Example: Critical business rules
@@ -488,8 +489,8 @@ const emission = storeSystem.stage(updates)
 if (emission.validity.valid) {
   // State is valid, can be rendered
   renderState(emission.state)
-} else if (emission.validity.severity === 'fatal') {
-  // Fatal errors prevent rendering updates
+} else if (emission.validity.severity === 'fatal' || emission.validity.severity === 'fixable') {
+  // The change is rejected: the rendered slice keeps the last valid state
   showErrors(emission.validity.entityViolations)
 }
 
@@ -552,9 +553,10 @@ Phoenix uses `useSyncExternalStore` to efficiently synchronize store state with
 // Select specific entities
 const cabinets = phx.frontend.useStoreSelector(state => state.state.entities.filter(e => e.type === 'Cabinet'), [])
 
-// Select computed values with dependencies
-const totalPrice = phx.frontend.useStoreSelector(
-  state => state.state.entities.filter(e => e.type === 'Cabinet').reduce((sum, cabinet) => sum + cabinet.$price, 0),
+// Select computed values: `state.state.entities` holds raw entities without `$` fields,
+// so read expressions and relations from an enhanced entity, here the root `Room`
+const totalPrice = phx.frontend.useRootEntitySelector(
+  room => room.$cabinets.reduce((sum, cabinet) => sum + cabinet.$price, 0),
   []
 )
 

package/dist/docs/phoenix/testing.mdx

@@ -36,7 +36,12 @@ uses it stubs `phx.frontendEnv` first.
 A test that mounts the configurator's UI builds from `configuratorConfig`: it carries the SDK's default
 elements, the built-in layout, preset screen, not-found, not-authenticated and error pages, app loader content,
 controls, toolbar buttons and sidebar-footer pieces, which `configuratorBuilder` does not, so a test that mounts the UI from `createTestApplicationConfig(configuratorBuilder)`
-shows a "not found" box in place of every built-in element. Code that assembles a config without the
+shows a "not found" box in place of every built-in element. The defaults also hold the configurator's
+visual providers and the error page and dialog its runtime renders, and a config without them runs the
+lifecycle without them, with a plain error message in place of the error page. Without them nothing
+provides the responsive context, so an SDK layout slot that reads it, for example
+`LayoutSlots.SharedCanvas`, stops the configurator with that plain error message instead of showing a
+"not found" box, and snackbar messages have no host. Code that assembles a config without the
 generated files calls `.withDefaultElements(defaultConfiguratorElements)` on its configurator builder, with
 the list from `@salsita-ai/sdk/configurator`, or `defaultAdminElements` from `@salsita-ai/sdk/admin` for
 the admin.

package/dist/docs/phoenix/webhooks.mdx

@@ -1378,6 +1378,10 @@ export const emailTask = phx.webhooks.taskFactory.createSendEmailTask((resources
 
 The Backend Data Handler allows you to fetch data on the server that will be automatically made available both in the domain (client-side) and in webhook contexts. Its main purpose is to securely fetch data using API keys or other sensitive credentials that cannot be exposed to the client, while making that data available throughout your application.
 
+Responses of at least 32 KiB are automatically gzip-compressed when the caller accepts gzip and the base64 representation is smaller. Project handlers return the same `backendData` object; the API and configurator receive decoded JSON. This also works through `phoenix dev` when both the server and CLI support gzip. Older tunnel clients keep plain JSON.
+
+Compression does not remove platform limits: the complete encoded development-tunnel request must fit within 5 MiB, and deployed webhooks remain subject to Lambda's buffered response limit. The tunnel accepts up to 100 MiB of decoded gzip data. Data that does not compress enough must be reduced or split. Binary responses appear as a byte-count placeholder in the development tunnel inspector.
+
 ### Defining a Backend Data Handler
 
 Backend data handlers are defined inline in the webhook builder:

package/dist/docs/recipes-and-delete/delete-entity.mdx

@@ -58,9 +58,9 @@ invariants:
 **Dry run behavior:**
 
 - Recipe validation: Each recipe shows violation hints based on what would happen if executed
-- Fatal violations: Recipes that would cause fatal violations are disabled and cannot be clicked
-- Warning violations: Recipes that cause warnings show indicators but remain clickable
-- Fixable violations: Violations listed in fixableViolations are ignored in the UI hints
+- Fatal and fixable violations: Recipes that would cause a `fatal` or `fixable` violation are disabled and cannot be clicked
+- Warning and notice violations: Recipes that cause only `warning` or `notice` violations stay clickable and show no hint
+- Fixable violations: Violation types listed in `fixableViolations` are left out of the hint text; the recipe stays disabled
 
 ## TypeScript Interfaces
 
@@ -227,7 +227,6 @@ components:
 
 ```ts
 import { createPlate } from '../../../../common/plate-rendering.js'
-import { phx } from '../../.phoenix/phx.js'
 
 export default phx.domain.implementCustomExpressions({
   Hole: {
@@ -275,8 +274,6 @@ export default phx.domain.implementCustomExpressions({
 ### ./src/invariants/plate.ts
 
 ```ts
-import { phx } from '../../.phoenix/phx.js'
-
 export default phx.domain.implementCustomInvariants({
   Plate: {
     one54: s => {

package/dist/docs/recipes-and-delete/dynamic-root-entity.mdx

@@ -205,8 +205,6 @@ components:
 ```ts
 import { memoOnce } from '@salsita-ai/sdk/common/utils'
 
-import { phx } from '../../.phoenix/phx.js'
-
 export default phx.domain.implementCustomExpressions({
   BuckyBall: {
     $replaceRecipes: memoOnce(() => [

package/dist/docs/recipes-and-delete/grouped-button.mdx

@@ -293,7 +293,6 @@ components:
 
 ```ts
 import { createPlate } from '../../../../common/plate-rendering.js'
-import { phx } from '../../.phoenix/phx.js'
 
 export default phx.domain.implementCustomExpressions({
   Hole: {
@@ -406,8 +405,6 @@ export default phx.domain.implementCustomExpressions({
 ### ./src/invariants/invariants.ts
 
 ```ts
-import { phx } from '../../.phoenix/phx.js'
-
 export default phx.domain.implementCustomInvariants({
   Plate: {
     noOvals: s => {

package/dist/docs/recipes-and-delete/grouped-panel.mdx

@@ -407,7 +407,6 @@ components:
 
 ```ts
 import { createPlate } from '../../../../common/plate-rendering.js'
-import { phx } from '../../.phoenix/phx.js'
 
 export default phx.domain.implementCustomExpressions({
   Hole: {
@@ -520,8 +519,6 @@ export default phx.domain.implementCustomExpressions({
 ### ./src/invariants/invariants.ts
 
 ```ts
-import { phx } from '../../.phoenix/phx.js'
-
 export default phx.domain.implementCustomInvariants({
   Plate: {
     noOvals: s => {

package/dist/docs/recipes-and-delete/horizontal.mdx

@@ -149,9 +149,9 @@ invariants:
 **Dry run behavior:**
 
 - Recipe validation: Each recipe shows violation hints based on what would happen if executed
-- Fatal violations: Recipes that would cause fatal violations are disabled and cannot be clicked
-- Warning violations: Recipes that cause warnings show indicators but remain clickable
-- Fixable violations: Violations listed in fixableViolations are ignored in the UI hints
+- Fatal and fixable violations: Recipes that would cause a `fatal` or `fixable` violation are disabled and cannot be clicked
+- Warning and notice violations: Recipes that cause only `warning` or `notice` violations stay clickable and show no hint
+- Fixable violations: Violation types listed in `fixableViolations` are left out of the hint text; the recipe stays disabled
 
 ## TypeScript Interfaces
 
@@ -456,7 +456,6 @@ invariants:
 
 ```ts
 import { createPlate } from '../../../../common/plate-rendering.js'
-import { phx } from '../../.phoenix/phx.js'
 
 export default phx.domain.implementCustomExpressions({
   Hole: {
@@ -580,8 +579,6 @@ export default phx.domain.implementCustomExpressions({
 ### ./src/invariants/invariants.ts
 
 ```ts
-import { phx } from '../../.phoenix/phx.js'
-
 export default phx.domain.implementCustomInvariants({
   Plate: {
     noOvals: s => {

package/dist/docs/recipes-and-delete/recipe-hierarchy-lists.mdx

@@ -514,7 +514,6 @@ transformers:
 ```ts
 import { getConsoleRenderingComponents } from '../../../../common/console-rendering.js'
 import { getMonitorRenderingComponents } from '../../../../common/monitor-rendering.js'
-import { phx } from '../../.phoenix/phx.js'
 
 export default [
   ...getConsoleRenderingComponents('Console', phx.domain.attachComponent),
@@ -527,8 +526,6 @@ export default [
 ```ts
 import type { DomainEntityId } from '@salsita-ai/sdk/domain'
 
-import { phx } from '../../.phoenix/phx.js'
-
 export default phx.domain.implementCustomExpressions({
   Room: {
     $childRecipes: s => {

package/dist/docs/recipes-and-delete/recipe-hierarchy-selection.mdx

@@ -359,7 +359,6 @@ transformers:
 ```ts
 import { getConsoleRenderingComponents } from '../../../../common/console-rendering.js'
 import { getMonitorRenderingComponents } from '../../../../common/monitor-rendering.js'
-import { phx } from '../../.phoenix/phx.js'
 
 export default [
   ...getConsoleRenderingComponents('RedSpecialConsole', phx.domain.attachComponent, '#CC0000'),
@@ -373,8 +372,6 @@ export default [
 ```ts
 import type { DomainEntityId } from '@salsita-ai/sdk/domain'
 
-import { phx } from '../../.phoenix/phx.js'
-
 export default phx.domain.implementCustomExpressions({
   Room: {
     $specialConsoleOptions: () => {
@@ -427,8 +424,6 @@ export default phx.domain.implementCustomExpressions({
 ### ./src/transformers/deselect-special.ts
 
 ```ts
-import { phx } from '../../.phoenix/phx.js'
-
 export default phx.frontend.transformerBuilder.when
   .entity(['RedSpecialConsole', 'BlueSpecialConsole'])
   .replacedWith(['RedSpecialConsole', 'BlueSpecialConsole'])

package/dist/docs/recipes-and-delete/replace-dropdown.mdx

@@ -137,9 +137,9 @@ invariants:
 **Dry run behavior:**
 
 - Recipe validation: Each recipe shows violation hints based on what would happen if executed
-- Fatal violations: Recipes that would cause fatal violations are disabled and cannot be clicked
-- Warning violations: Recipes that cause warnings show indicators but remain clickable
-- Fixable violations: Violations listed in fixableViolations are ignored in the UI hints
+- Fatal and fixable violations: Recipes that would cause a `fatal` or `fixable` violation are disabled and cannot be clicked
+- Warning and notice violations: Recipes that cause only `warning` or `notice` violations stay clickable and show no hint
+- Fixable violations: Violation types listed in `fixableViolations` are left out of the hint text; the recipe stays disabled
 
 ## TypeScript Interfaces
 
@@ -482,7 +482,6 @@ components:
 
 ```ts
 import { createPlate } from '../../../../common/plate-rendering.js'
-import { phx } from '../../.phoenix/phx.js'
 
 export default phx.domain.implementCustomExpressions({
   Hole: {
@@ -708,8 +707,6 @@ export default phx.domain.implementCustomExpressions({
 ### ./src/invariants/invariants.ts
 
 ```ts
-import { phx } from '../../.phoenix/phx.js'
-
 export default phx.domain.implementCustomInvariants({
   Plate: {
     noOvals: s => {

package/dist/docs/recipes-and-delete/replace-panel.mdx

@@ -486,8 +486,6 @@ components:
 ### ./src/expressions/feature.ts
 
 ```ts
-import { phx } from '../../.phoenix/phx.js'
-
 export default phx.domain.implementCustomExpressions({
   Feature: {
     $circularRecipes: s => {
@@ -586,8 +584,6 @@ export default phx.domain.implementCustomExpressions({
 ### ./src/expressions/hole.ts
 
 ```ts
-import { phx } from '../../.phoenix/phx.js'
-
 export default phx.domain.implementCustomExpressions({
   Hole: {
     $radius: () => 10,
@@ -605,7 +601,6 @@ export default phx.domain.implementCustomExpressions({
 
 ```ts
 import { createPlate } from '../../../../common/plate-rendering.js'
-import { phx } from '../../.phoenix/phx.js'
 
 export default phx.domain.implementCustomExpressions({
   Plate: {
@@ -709,8 +704,6 @@ export default phx.domain.implementCustomExpressions({
 ### ./src/invariants/invariants.ts
 
 ```ts
-import { phx } from '../../.phoenix/phx.js'
-
 export default phx.domain.implementCustomInvariants({
   Plate: {
     noOvals: s => {