@salsita-ai/sdk 0.50.0-develop.b5468d6828 → 0.50.0-develop.b5d443db78

package/dist/docs/phoenix/quickstart.mdx

@@ -15,7 +15,7 @@ Build a working office desk configurator from an empty folder. You will describe
 
 ## Before you start
 
-Use Node.js 24 and pnpm 11. The tutorial uses the office desk model served by this documentation site at `/models/office-desk.gltf`; download it first. Real client projects normally start from `phoenix init`. This tutorial creates the four essential files by hand so you can see what Phoenix owns.
+Use Node.js 24 and any package manager; the commands below use pnpm, and with pnpm 11 the project also needs the `pnpm-workspace.yaml` in [Package manager](?path=/docs/phoenix-project-structure--docs#package-manager). The tutorial uses the office desk model served by this documentation site at `/models/office-desk.gltf`; download it first. Real client projects normally start from `phoenix init`. This tutorial creates the four essential files by hand so you can see what Phoenix owns.
 
 ## Step 0 — Create the project
 
@@ -40,17 +40,13 @@ Now add these four files.
   "dependencies": {
     "@salsita-ai/sdk": "0.48.0"
   },
-  "devDependencies": {
-    "@lingui/cli": "5.9.5",
-    "@lingui/swc-plugin": "5.11.0"
-  },
   "phoenix": {
     "applicationFlow": true
   }
 }
 ```
 
-Use the SDK version supplied by your team if it differs from the repository's current `0.48.0` version. `phoenix.applicationFlow` selects the application-spec project structure. The first sync uses Lingui while generating the rest of the dependencies, so its CLI and SWC plugin must also be present in the initial install.
+Use the SDK version supplied by your team if it differs from the repository's current `0.48.0` version. `phoenix.applicationFlow` selects the application-spec project structure. The SDK runs its own Lingui, so the SDK is the only dependency you write by hand; `phoenix deps` adds the packages it needs next to it in the install step below. A project started with `phoenix init` gets a `package.json` that already declares them.
 
 ### `.env`
 
@@ -97,13 +93,17 @@ components:
         layout: universal
 ```
 
-Install the SDK, then ask Phoenix to generate the rest of the project:
+Install the SDK, let it declare the packages it needs, such as React, three.js and MUI, install them, then ask Phoenix to generate the rest of the project:
 
 ```sh
 pnpm install
+pnpm phoenix deps
+pnpm install
 pnpm phoenix sync
 ```
 
+`phoenix sync` stops while `package.json` lacks one of those packages; after every SDK update, run `phoenix deps` and install again (see [`phoenix deps`](?path=/docs/phoenix-phoenix-cli--docs#phoenix-deps)). With npm, the same steps are `npm install`, `npx phoenix deps`, `npm install` and `npx phoenix sync`.
+
 `phoenix sync` keeps `spec/` and `src/` as your authored inputs and generates the application shell, types, and `.phoenix/` implementation. Start development without a server:
 
 ```sh
@@ -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

@@ -8,9 +8,9 @@ Your workspace's Studio shows the setup, the link to your configurator and the s
 
 ## Before you start
 
-- **Package access:** `@salsita-ai/sdk` is public on npm; `npx` and `pnpm install` download it without a registry token.
+- **Package access:** `@salsita-ai/sdk` is public on npm; any package manager downloads it without a registry token.
 - **Workspace details:** you need your workspace slug and its Phoenix region (`eu` or `us`), which you also received with your workspace.
-- **Tools:** Node.js and pnpm.
+- **Tools:** Node.js and a package manager. The commands below use pnpm; with npm, run `npm install` and `npx phoenix …` instead, with Yarn `yarn phoenix …`, with Bun `bunx phoenix …`.
 - **SDK build:** during the internal beta, use the `canary` build of the SDK, as the commands below do. It is published from every change to the platform, so it is newer than the last release.
 
 ## 1. Create a project
@@ -22,11 +22,11 @@ pnpm install
 pnpm phoenix sync
 ```
 
-`phoenix init [folder]` writes the starter project: `package.json`, `pnpm-workspace.yaml` 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 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.
+`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)).
 
-`pnpm-workspace.yaml` holds the pnpm settings the install needs: it allows the build scripts of the SDK's dependencies and exempts `@salsita-ai/*` packages from pnpm's minimum release age, so a build of the SDK published today installs. The file is yours to edit, for example to allow the build script of a dependency you add. `phoenix sync` adds these entries when they are missing and keeps the values you set. A project inside a pnpm monorepo gets no file of its own; the workspace root holds the settings.
+Phoenix writes no package-manager settings. With pnpm 11, add a `pnpm-workspace.yaml` that allows the build scripts of the SDK's dependencies before the first install; [Package manager](?path=/docs/phoenix-project-structure--docs#package-manager) has the file.
 
 The starter `spec/application.yaml` begins with `project: default`, which means the default project of the workspace you sign in to. Leave it as it is; a workspace has one 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-create-configurator` skill guides 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,16 +72,18 @@ 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.
 
-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.
+On the server, the install runs pnpm. It follows your `pnpm-lock.yaml` and `pnpm-workspace.yaml` when the project has them, so a pnpm project gets the same build scripts and package versions as on your computer; without them, pnpm resolves `package.json` with the settings the SDK needs. 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.
 
 If the build fails, is cancelled or takes too long, `phoenix deploy` prints the end of the build log and exits with an error. `--no-wait` returns as soon as the build starts.
 
-Studio's **Builds & deployments** page lists your builds and shows which one your configurator serves. Each build shows its progress, its error and the full build log while it runs.
+Studio's **Builds & deployments** page lists your builds, 20 to a page, and shows which one your configurator serves. Filter it to the live build or to the builds that failed. Each build shows its progress, its error and the full build log while it runs, and who deployed it with which CLI token.
+
+**Rebuild** on a build's page builds the files uploaded with that build again, with your environment variables as they are now, without a new `phoenix deploy`. Use it after changing a variable, or when a build failed for a reason on our side. If the rebuild succeeds it goes live, so rebuilding an older build rolls production back to it.
 
 `phoenix deploy` refuses symlinks, hard-linked files and other special files among the project files, because builds only accept regular files. Packing uses the system `tar`, which macOS, Linux and Windows 10 or later all include. The build runner checks the uploaded archive again and keeps only project files, so a file outside the list above never reaches the build.
 
@@ -95,9 +93,7 @@ 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, 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. 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.
+- 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.
 
 ## Known limits
 
@@ -107,5 +103,5 @@ Coding agents working in your project use the same command, guided by the genera
 - `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 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.
+- Your own environment variables are set in Studio under Environment, by a super admin of the workspace, and apply from the next deploy. After a change, **Redeploy #N now** there rebuilds your live build with the new values, without a new `phoenix deploy`; it appears once your own build is live. `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/docs/phoenix/sessions-and-access.mdx

@@ -427,6 +427,8 @@ The `readonly` web component property lets the host force view mode without chan
 
 Because an owner-token session can be forced read-only client-side while the server still accepts writes from that owner token, Phoenix skips persistence and logs a warning instead of updating the configuration. This guards against the configuration being silently overwritten by code paths that mutate state in read-only mode. UI that triggers significant changes (anything that produces a new revision) should still be disabled when `accessInfo.viewMode` is true — the warning is a backstop, not a substitute.
 
+The assistant follows the same read-only rule as the UI: its `apply` tool refuses changes while `accessInfo.viewMode` is true, that is with a read-revision token or while `readonly` is set, and makes them again once it is false. A switch of `readonly` takes effect at once, in both directions, and the configurator loads the configuration again. A change applied after `readonly` is cleared and before the configuration has loaded again is not saved; saving resumes once it has loaded. The `query` tool keeps working, including its dry-run mutations.
+
 ```html
 <salsita-configurator readonly></salsita-configurator>
 ```

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

@@ -33,6 +33,19 @@ invariants, actions, migrations, presets and the components declared in YAML. `c
 handler, element and transformer; it reads the frontend environment when it is imported, so a test that
 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. 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.
+
 A test passes the generated export to the helper and does not call the export's methods: they are how the
 SDK assembles an application, not an interface for tests, while the helper's call does not depend on that
 assembly.

package/dist/docs/phoenix/webhooks.mdx

@@ -36,7 +36,11 @@ Phoenix provides domain-aware builders through the global `phx.webhooks` namespa
 
 Your webhook is the default export of `src/webhooks/index.ts`. With the application-spec pipeline (see [Current and legacy project tooling](?path=/docs/phoenix-phoenix-cli--docs#current-and-legacy-project-tooling)), the file is yours to create; sync does not write it. A project without it gets a built-in webhook, so it builds and deploys with no webhook code. The built-in webhook has one handler, an anonymous auth handler, which the platform calls only when `spec/application.yaml` sets `useAuthHook`. The legacy pipeline writes the file with that webhook on the first sync.
 
-Create `src/webhooks/index.ts` when the project needs its own handlers: finalization, backend data, or an auth handler that does more than start an anonymous session. A project that sets `useAuthHook` or `useClerk` needs its own auth handler, because the built-in one answers only anonymous requests. The smallest file is the built-in webhook itself:
+Create `src/webhooks/index.ts` when the project needs its own handlers: finalization, backend data, or an auth handler that does more than start an anonymous session.
+
+If `useAuthHook` or `useClerk` is enabled without this file, sync, build, clean and dev report `AUTH_WITHOUT_PROJECT_WEBHOOK` and generation continues with the anonymous-only built-in webhook. This warning also applies when `useAuthHook: false` is explicit alongside `useClerk: true`. Add a default-exported webhook with the required Clerk or custom auth handlers, or disable the settings if they are unintended.
+
+The smallest file is the built-in webhook itself:
 
 ```ts
 // src/webhooks/index.ts
@@ -1374,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 => {

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

@@ -150,9 +150,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
 
@@ -473,7 +473,6 @@ components:
 
 ```ts
 import { createPlate } from '../../../../common/plate-rendering.js'
-import { phx } from '../../.phoenix/phx.js'
 
 export default phx.domain.implementCustomExpressions({
   Hole: {
@@ -597,8 +596,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/vertical.mdx

@@ -153,9 +153,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
 
@@ -462,7 +462,6 @@ components:
 
 ```ts
 import { createPlate } from '../../../../common/plate-rendering.js'
-import { phx } from '../../.phoenix/phx.js'
 
 export default phx.domain.implementCustomExpressions({
   Hole: {
@@ -575,8 +574,6 @@ export default phx.domain.implementCustomExpressions({
 ### ./src/invariants/invaraints.ts
 
 ```ts
-import { phx } from '../../.phoenix/phx.js'
-
 export default phx.domain.implementCustomInvariants({
   Plate: {
     noOvals: s => {

package/dist/docs/relations/aliases.mdx

@@ -289,8 +289,6 @@ components:
 ### ./src/expressions/expressions.ts
 
 ```ts
-import { phx } from '../../.phoenix/phx.js'
-
 export default phx.domain.implementCustomExpressions({
   Legs: {
     $legRecipes: () => {

package/dist/docs/relations/all-of-type.mdx

@@ -285,8 +285,6 @@ components:
 ### ./src/expressions/expressions.ts
 
 ```ts
-import { phx } from '../../.phoenix/phx.js'
-
 export default phx.domain.implementCustomExpressions({
   Range: {
     $width: s => {
@@ -396,8 +394,6 @@ export default phx.domain.implementCustomExpressions({
 ### ./src/invariants/invariants.ts
 
 ```ts
-import { phx } from '../../.phoenix/phx.js'
-
 export default phx.domain.implementCustomInvariants({
   Range: {
     minimumModuleCount: s => {