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

package/dist/docs/other-features/client-side-rendering/declarative.mdx

@@ -126,7 +126,7 @@ The SDK waits up to 10 seconds for each canvas flush and logs a `Force flush tim
 
 ### Known gaps
 
-Images render offscreen, and the live canvas shows a still of the current view while they generate, so animations pause until generation finishes. Without [Postprocessing](?path=/docs/other-features-client-side-rendering-postprocessing--docs), tone mapping and the sRGB conversion run once over the finished image instead of per material, as on the canvas. The scene renders over a transparent background, and a background colour (a Color `scene.background`, the image's `backgroundColor`, or white for JPEG) is composited behind it afterwards. That means:
+Images render offscreen, and the live canvas shows a still of the current view while they generate, so animations pause until generation finishes. Exports run one after another, never interleaved, and while one is waiting or running the built-in universal layout does not respond: a press shows that the configurator is exporting. Afterwards it shows the configuration as currently committed. Without [Postprocessing](?path=/docs/other-features-client-side-rendering-postprocessing--docs), tone mapping and the sRGB conversion run once over the finished image instead of per material, as on the canvas. The scene renders over a transparent background, and a background colour (a Color `scene.background`, the image's `backgroundColor`, or white for JPEG) is composited behind it afterwards. That means:
 
 - materials with `toneMapped: false` are tone mapped in exported images;
 - a texture or environment `scene.background` in an sRGB colour space is tone mapped in exported images, while the canvas draws it without tone mapping;

package/dist/docs/phoenix/configurator-interface.mdx

@@ -391,7 +391,7 @@ Use these factories to customize the preset-selection screen without changing ho
 - `createPresetPageAction` adds project-specific content below the default preset cards.
 - `createPresetDeviceNotSupported` adds project-specific overlay content above the default preset cards.
 
-Without `createPresetUi`, Phoenix renders its built-in preset screen, which is the default `PresetUi` registration in `defaultConfiguratorElements`. The action and the overlay are parts of that built-in screen and render nothing until the project registers them.
+Without `createPresetUi`, Phoenix renders its built-in preset screen, which is the default `PresetUi` registration in `defaultConfiguratorElements`. The action and the overlay are parts of that built-in screen and render nothing until the project registers them. `createPresetUi` and the element's name, `PresetUiName`, are also exported from `@salsita-ai/sdk/react`.
 
 ```typescript
 const PresetScreen = phx.frontend.createPresetUi(CustomPresetScreen)
@@ -413,7 +413,7 @@ export default phx.frontend.createConfigurationNotFoundPage(({ onBack }) => (
 ))
 ```
 
-The helper types the page's props as `ConfigurationNotFoundPageProps` from `@salsita-ai/sdk/react`. A layout element registered under the name `ConfigurationNotFoundPage` with `createCustomPhoenixLayoutElement` replaces the page too, but its component is typed as taking only `children`.
+The helper types the page's props as `ConfigurationNotFoundPageProps` from `@salsita-ai/sdk/react`, which also exports the helper and the element's name, `ConfigurationNotFoundPageName`. A layout element registered under the name `ConfigurationNotFoundPage` with `createCustomPhoenixLayoutElement` replaces the page too, but its component is typed as taking only `children`.
 
 - The page receives one optional prop, `onBack`, which returns to the start of the configurator. It is set when a configuration fails to load or is opened without a valid access key. It is not set on the start page itself, so a page that offers a way back shows it only when `onBack` is set.
 - The configurator renders the element in four cases: a configuration fails to load, for example because its ID does not exist or the server rejects its access key; a configuration is opened without an access key for it; a signed-in user whose role may not create configurations (`acl.canCreate`) opens the start page; the preset screen has no preset category to show, for example because the host's `presetTags` match no preset. The last case happens inside the built-in preset screen, so a project that replaces it with `createPresetUi` decides what to show itself.
@@ -434,7 +434,7 @@ export default phx.frontend.createConfiguratorErrorPage(({ reason, onRetry }) =>
 ))
 ```
 
-The helper types the page's props as `ConfiguratorErrorPageProps` from `@salsita-ai/sdk/react`. A layout element registered under the name `ConfiguratorErrorPage` with `createCustomPhoenixLayoutElement` replaces the page too, but its component is typed as taking only `children`.
+The helper types the page's props as `ConfiguratorErrorPageProps` from `@salsita-ai/sdk/react`, which also exports the helper and the element's name, `ConfiguratorErrorPageName`. A layout element registered under the name `ConfiguratorErrorPage` with `createCustomPhoenixLayoutElement` replaces the page too, but its component is typed as taking only `children`.
 
 - The page receives two props. `reason` says what failed: `uncaughtError` when rendering the configurator failed with an error nothing else handled, `presetCreationFailed` when starting a configuration from the only preset failed. `onRetry` tries again: after `uncaughtError` it renders the configurator again, after `presetCreationFailed` it reloads the page. The error itself is not passed; it is logged to the console.
 - The configurator renders the element in two cases: an error reaches the configurator's error boundary, which wraps everything from the scene resources and the session down to the pages, including a failure while the application starts; and creating a configuration fails on a start screen with a single preset. The element is available in both, because the spec and its elements are part of the application before the configurator renders.
@@ -451,6 +451,7 @@ export default phx.frontend.createAppLoader(({ phases }) => <span>{phases[0]?.la
 ```
 
 - Phoenix keeps the overlay, its place over the safe area and its fade-in; the element is only what it shows.
+- `createAppLoader`, the props type `AppLoaderContentProps` and the element's name, `AppLoaderContentName`, are also exported from `@salsita-ai/sdk/react`.
 - The overlay stays up while a loading phase runs: the session, the project's data, the configuration and the 3D scene. It waits for the scene only when the loaded configuration's layout mounts a canvas, as the built-in layouts and `LayoutSlots.SharedCanvas` do. A `ConfiguratorLayout` without a canvas is not held by the loader: the overlay leaves once the configuration is up.
 - The top-level `appLoader: legacy` key in the spec turns the overlay off.
 - The built-in content is the default `AppLoaderContent` registration in `defaultConfiguratorElements`, see below.
@@ -546,7 +547,7 @@ export default phx.frontend.createCustomPhoenixLayoutElement('ConfiguratorLayout
 - `LayoutSlots.DesktopSidebar` is the built-in desktop sidebar as one piece: the spec's tabs, back button, property pages and sidebar footer with their spacing, scrolling and empty states, and the assistant panel. Use it when the spec's property pages are what the customer should see and only their place changes, for example a sidebar on the left; build the controls yourself when they have to look like the brand's own. Without `width` it fills its container, so the layout positions and sizes that container; `miniSidebar` does not shrink it, so a layout that honours it reads `LayoutSlots.useSidebarContent().hasMiniSidebar` and lets the container take the sidebar's height. Its tabs sit outside it on the left; `side="start"` puts them on its right, for a sidebar on the left. In fullscreen it stays in place, transparent and inert, so a layout that wants the space back removes it while `phx.frontend.useIsFullscreenActive()` is set. See [Sidebar in a Custom Layout](?path=/docs/layouts-sidebar-in-a-custom-layout--docs).
 - Nothing of the built-in layouts is rendered for it. A project layout finalizes over the spec's `finalizeAction` components, see the finalize paragraph of [Hooks for a Project Layout](#hooks-for-a-project-layout). The `finalizePage` and `finalizeButton` components are legacy: they cannot be declared in YAML, only in TypeScript, and `Legacy.CommonFinalizePage`, which is deprecated, shows a `finalizePage` for projects that still have one. `LayoutDialog` renders only what the project registers with `createLayoutDialog` and is not part of the finalize flow. The preview start screen is `DesktopPreview` or `MobilePreview`, which the layout shows while `phx.frontend.usePreview().isPreview` is set. Both previews frame the scene themselves, so the layout renders the component that calls `phx.frontend.useSceneSafeArea()` only while `isPreview` is not set; it then measures when it mounts after the preview. The assistant panel is available to a project layout only inside `LayoutSlots.DesktopSidebar`.
 - The layout reads the state it has to react to from hooks, listed with what each returns in [Hooks for a Project Layout](#hooks-for-a-project-layout).
-- Messages for the user come one of two ways. `LayoutSlots.Services` shows violations of a rejected change, side-effect hints, errors and failed saves as the built-in snackbars, which render into `LayoutSlots.DesktopSnackbarsRoot` or `LayoutSlots.MobileSnackbarsRoot` wherever the layout mounts it. `phx.frontend.useConfiguratorMessages(onMessage)` hands the same messages to the layout's own UI instead, with their text resolved, as the toast in [Custom Layout](?path=/docs/layouts-custom-layout--docs#show-messages) does; mount one of the two, not both, or every message is shown twice. A failure to save the configuration, and the first successful save after it, are messages too, so a layout that mounts neither shows no sign of a failed save. An error of the built-in finalize and other actions stays a snackbar either way. It renders into the snackbar root, so a layout that mounts none shows it outside the configurator, in the page's `body`. A failure to start a configuration from a preset is not a message of the hook either: it happens on the preset screen, before any `ConfiguratorLayout` mounts. In production with more than one preset it is a snackbar there, also on a preset screen replaced with `createPresetUi` (see [Preset UI](#preset-ui)), which reads the error from `phx.frontend.usePresetSelection().selectionError` and mounts `PresetSnackbarsRoot` to keep the snackbar inside the configurator. With a single preset it is the [Configurator Error Page](#configurator-error-page). A finalize action the layout runs with `phx.frontend.useFinalizeActions` or `phx.frontend.useFinalizeAction` reports its error as the action's `error` instead, neither as a message nor as a snackbar.
+- Messages for the user come one of two ways. `LayoutSlots.Services` shows violations of a rejected change, side-effect hints, errors and failed saves as the built-in snackbars, which render into `LayoutSlots.DesktopSnackbarsRoot` or `LayoutSlots.MobileSnackbarsRoot` wherever the layout mounts it; the theme styles them, see [Layout Slots → Styling the snackbars](?path=/docs/phoenix-layout-slots--docs#styling-the-snackbars). `phx.frontend.useConfiguratorMessages(onMessage)` hands the same messages to the layout's own UI instead, with their text resolved, as the toast in [Custom Layout](?path=/docs/layouts-custom-layout--docs#show-messages) does; mount one of the two, not both, or every message is shown twice. A failure to save the configuration, and the first successful save after it, are messages too, so a layout that mounts neither shows no sign of a failed save. An error of the built-in finalize and other actions stays a snackbar either way. It renders into the snackbar root, so a layout that mounts none shows it outside the configurator, in the page's `body`. A failure to start a configuration from a preset is not a message of the hook either: it happens on the preset screen, before any `ConfiguratorLayout` mounts. In production with more than one preset it is a snackbar there, also on a preset screen replaced with `createPresetUi` (see [Preset UI](#preset-ui)), which reads the error from `phx.frontend.usePresetSelection().selectionError` and mounts `PresetSnackbarsRoot` to keep the snackbar inside the configurator. With a single preset it is the [Configurator Error Page](#configurator-error-page). A finalize action the layout runs with `phx.frontend.useFinalizeActions` or `phx.frontend.useFinalizeAction` reports its error as the action's `error` instead, neither as a message nor as a snackbar.
 - Any project layout element named `ConfiguratorLayout` takes over the page.
 
 `defaultConfiguratorElements`, exported from `@salsita-ai/sdk/configurator`, holds the built-in UI as a `ConfiguratorLayout` registration that renders the layout the spec selects, the built-in not-found page as a `ConfigurationNotFoundPage` registration, the built-in not-authenticated page as a `NotAuthenticatedPage` registration, the built-in preset screen as a `PresetUi` registration, the built-in error page as a `ConfiguratorErrorPage` registration, the app loader's built-in content as an `AppLoaderContent` registration, and the built-in in-scene controls under the names of [In-Scene Controls](#in-scene-controls). Generated code registers these defaults with `withDefaultElements`, apart from the project's elements, so the built-in UI is a registration like any other; a project element registered under the same name wins over a default. The list also holds the configurator's built-in controls and layout elements under the kinds the spec names them by, such as `attributeSelect` or `undoToolbarButton`, so a project element registered under one of those names replaces the built-in one wherever the spec names that kind. A config assembled by hand, without generated code, calls `withDefaultElements(defaultConfiguratorElements)` too; the lists are the only way the built-in elements are registered, so without it the page shows a "not found" box instead of the configurator, and a project layout shows one in place of every built-in control. The admin mounts a full configurator, so its list, `defaultAdminElements` from `@salsita-ai/sdk/admin`, holds the configurator's defaults followed by the admin's built-in pages, sidebars and actions; generated admin code passes it to `withDefaultElements` in place of `defaultConfiguratorElements`, because each call replaces the defaults passed before.
@@ -598,7 +599,7 @@ Texts from the spec, such as option titles and the `detail` fields, are `Localiz
 
 **Steps and tabs**
 
-A project layout builds its steps and tabs from the spec, so the structure stays in `navigationSteps`, `sidebarTabs` and `horizontalTabs`, where `$filter` switches it, and the layout decides how it looks. `phx.frontend.useStepNavigation()` gives a wizard its steps with a `status` each, and `next`, `previous` and `goTo`; `phx.frontend.useTabNavigation()` gives tabs with `isActive` each, and `select`. Both enter a navigation state, so controls, cameras and components filtered by `navigationStates` follow. Neither hides anything in read mode or blocks a step on violations: a layout that should not move on while the configuration is invalid combines `canGoNext` with `useStateValidity()`, and a stepper that offers only earlier steps enables the steps whose `status` is `'complete'`.
+A project layout builds its steps and tabs from the spec, so the structure stays in `navigationSteps`, `sidebarTabs` and `horizontalTabs`, where `$filter` switches it, and the layout decides how it looks. `phx.frontend.useStepNavigation()` gives a wizard its steps with a `status` each, and `next`, `previous` and `goTo`; `phx.frontend.useTabNavigation()` gives tabs with `isActive` each, and `select`. Both enter a navigation state, so controls, cameras and components filtered by `navigationStates` follow. Neither hides anything in read mode or blocks a step on violations: a layout that should not move on while the configuration has a problem requires `phx.frontend.useStateValidity().severity !== 'warning'` besides `canGoNext`, because a change with a `fixable` or `fatal` violation is rejected and the committed configuration is never invalid, while a `warning` stays and blocks finalizing. A stepper that offers only earlier steps enables the steps whose `status` is `'complete'`.
 
 ```tsx
 export const Wizard = () => {
@@ -647,6 +648,7 @@ A layout builds its toolbar from `phx.frontend.useToolbarActions()`, which retur
 | `phx.frontend.useStateValidity()`                 | The validity of the last committed state: `{ valid: true, severity: null }`, or `{ valid: true, severity: 'notice' \| 'warning', entityViolations }`. A change that leaves a `fixable` or `fatal` violation is rejected and never committed, and neither is a change during which an error was thrown, so neither is seen here.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
 | `phx.frontend.useFinalizeViolations()`            | `{ disabled, hints, violations }`. `disabled` is `true` while a `warning`, `fixable` or `fatal` violation holds or the configuration failed to save; `hints` is the violations' text, or `undefined`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
 | `phx.frontend.useConfiguratorMessages(onMessage)` | Nothing. It calls `onMessage(message)` once per message: `{ kind: 'violation', entityId, violation, text }` for each violation of the rejected state, including notices and warnings already present, so `violation.severity` tells the reason for the rejection (`fixable` or `fatal`) from them, `{ kind: 'sideEffect', text }` for each hint of a committed update, `{ kind: 'error', error, text }` when an error is thrown while a change is validated, with `text` the generic "Oops, something went wrong", `{ kind: 'saveError', error, text }` each time saving the configuration fails, with `error` what the save rejected with and `text` a generic message, and `{ kind: 'saveRecovery', text }` when a save succeeds after a failed one, with `text` "Configuration updated". `text` is resolved to the current language; a violation's is its `message`, or its `type` without one, and the built-in snackbar prefixes it with `entityId`. Hints committed before the layout mounted are not delivered, nor is a save that failed before it mounted; when the most recent change was rejected or threw, its messages are delivered again when the hook mounts. `onMessage` may be a new function on every render. On `phx.frontend` the message is typed by the project, so `violation.type` narrows to its violation types; from `@salsita-ai/sdk/react` the type is `ConfiguratorMessage`. |
+| `phx.frontend.useConfigurationSaveState()`        | `{ revisionId, isSaving, failure }`, the save status of the configuration. An editable configuration saves every committed change on its own, three seconds after the last one, and a read-only one never saves. `revisionId` is the revision the configuration is at: the loaded one, then the one the latest save created. `isSaving` is `true` while a save runs. `failure` is `{ error, timestamp }` of the latest failed save, with `timestamp` in milliseconds since the epoch, and `null` once a later save succeeds or another configuration loads. A layout shows a save indicator with it; the messages of a failed save and of its recovery come from `useConfiguratorMessages`. Besides `phx.frontend`, `@salsita-ai/sdk/react` exports it.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
 | `phx.frontend.useFinalizeAction(handler)`         | `{ run, isPending, error, disabled, hints }` for the `finalizeAction` whose `handler` it is given; see the Finalize paragraph below for how to call it. `run()` records the finalize-button click for analytics and runs the project's handler, does nothing while `disabled` or `isPending`, and returns a promise that resolves once the handler has settled and never rejects; `error` is what the handler's last run rejected with, or `null`; `disabled` and `hints` are those of `useFinalizeViolations()`. The type of the result is `UseFinalizeActionResult` from `@salsita-ai/sdk/configurator`, which also exports the hook.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
 | `phx.frontend.useFinalizeActions()`               | `{ actions, primary, secondary, disabled, hints }`: every active `finalizeAction` of the spec in spec order, `primary` the first `'primary'` one, or else the first, or `null`, and `secondary` the others; see the Finalize paragraph below. Each action is `{ key, handler, variant, label, title, icon, run, isPending, error, disabled }`, with `label` and `title` resolved; `run()` records the finalize-button click for analytics and runs the action's handler, does nothing while `disabled` or `isPending`, and returns a promise that never rejects. `disabled` and `hints` are those of `useFinalizeViolations()`. Besides `phx.frontend`, `@salsita-ai/sdk/react` exports it.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
 
@@ -654,7 +656,7 @@ A layout builds its toolbar from `phx.frontend.useToolbarActions()`, which retur
 
 **Finalize**
 
-A project layout finalizes over the spec's `finalizeAction` components, each `{ variant, label, title, icon, handler }`, where `variant` is `'primary'` or `'secondary'` and `handler` names the project's handler registered with `phx.frontend.createPhoenixHandler`. `phx.frontend.useFinalizeActions()` is the convenient way: it lists them with what a button needs, runs their handlers itself, and can be called anywhere in the layout, including a dialog the layout opens with `useModal`, as often as it likes. It returns:
+A project layout finalizes over the spec's `finalizeAction` components, each `{ variant, label, title, icon, handler }`, where `variant` is `'primary'` or `'secondary'` and `handler` names the project's handler registered with `phx.frontend.createPhoenixHandler`. `phx.frontend.useFinalizeActions()` is the convenient way: it lists them with what a button needs, runs their handlers itself, and can be called anywhere in the layout, including a dialog the layout opens with `useModal`, as often as it likes; [Custom Layout](?path=/docs/layouts-custom-layout--docs#request-a-quote) offers its primary action this way in its review step. It returns:
 
 - `actions`, every active `finalizeAction` in spec order, and `primary` and `secondary`, the same actions split as the built-in footer splits them: `primary` is the first `'primary'` action, or else the first action, or `null` without any, and `secondary` the others in spec order.
 - `disabled` and `hints`, those of `useFinalizeViolations()`: finalizing is not possible while a `warning`, `fixable` or `fatal` violation holds or the configuration failed to save, and `hints` says why.
@@ -698,7 +700,7 @@ export const Finalize = () => {
 
 The configurator runs the handlers outside the layout, beside it, whenever a configuration is open, also in read mode and on every step. A handler can use what the configurator provides, such as `useModal`, but not a provider the layout itself adds; such a handler fails to load and shows as that action's `error`. An action's `isPending` and `error` are kept while the layout re-renders and while its components unmount and mount again.
 
-To run a single action the layout already knows, `phx.frontend.useFinalizeAction(handler)` runs it in the layout itself and returns `{ run, isPending, error, disabled, hints }`, with the same meaning. It runs the project's handler factory, which calls hooks, so the layout calls it once per component, never in a loop or conditionally, and wraps that component in `<PhoenixHandlerBoundary name={handler}>` from `@salsita-ai/sdk/react`, so an edited handler takes effect without a reload. Its `isPending` and `error` belong to the mounted component: when it unmounts during a run, the handler keeps running, and a component mounted afterwards starts with `isPending` false and no `error`. [Custom Layout](?path=/docs/layouts-custom-layout--docs#request-a-quote) runs a finalize action this way from its review step.
+To run a single action the layout already knows, `phx.frontend.useFinalizeAction(handler)` runs it in the layout itself and returns `{ run, isPending, error, disabled, hints }`, with the same meaning. It runs the project's handler factory, which calls hooks, so the layout calls it once per component, never in a loop or conditionally, and wraps that component in `<PhoenixHandlerBoundary name={handler}>` from `@salsita-ai/sdk/react`, so an edited handler takes effect without a reload. Its `isPending` and `error` belong to the mounted component: when it unmounts during a run, the handler keeps running, and a component mounted afterwards starts with `isPending` false and no `error`.
 
 Neither hook checks read mode, so the layout hides finalizing while `accessInfo.viewMode` is `true`, as above.
 

package/dist/docs/phoenix/domain-model.mdx

@@ -842,7 +842,10 @@ Phoenix automatically:
 During `phoenix dev`, schema-compatible configurator changes can refresh the mounted application in
 place. Changes to the domain model itself are rejected from live application and require a restart;
 this preserves the last valid runtime and loaded configuration until migration and deployment can be
-coordinated atomically.
+coordinated atomically. With server persistence, restart `phoenix dev` itself: it logs an error that
+asks for the restart, and registers the changed model with its development deployment when it starts
+again. Then open the preview address it prints rather than a tab whose address has `?cid=`, which
+loads a configuration saved with the earlier model.
 
 ### The phx Global Namespace
 

package/dist/docs/phoenix/layout-slots.mdx

@@ -44,6 +44,27 @@ export const Toolbar = () => (
 - `SharedCanvas` fills its nearest positioned ancestor and paints an opaque background, so the layout positions its own UI after it in the markup.
 - Snackbars are raised by `Services`, for violations, side-effect hints, validation errors and a failed save, and also by the built-in finalize and footer actions when their handler fails. A layout that shows these messages its own way calls `phx.frontend.useConfiguratorMessages(onMessage)` instead of mounting `Services`, and then shows the failed save too, see [Configurator Interface → Hooks for a Project Layout](?path=/docs/phoenix-configurator-interface--docs#hooks-for-a-project-layout); the other snackbars still need a root. They render into the snackbar root the layout mounts; with no root mounted they render into the page's `document.body`, outside the configurator. The desktop root is a zero-height element the snackbars stack upwards from, so the layout places it where their bottom edge belongs. The phone root leaves them fixed to the viewport, see `MobileSnackbarsRoot`. A finalize action the layout runs with `phx.frontend.useFinalizeActions` or `phx.frontend.useFinalizeAction` raises no snackbar; its error is the action's `error`.
 
+### Styling the snackbars
+
+Every snackbar of the configurator and the admin, raised by `Services`, a failed save, a failed preset creation or a built-in action, renders as `PhxSnackbar` from `@salsita-ai/sdk/ui`: an MUI `Alert` with the snackbar's variant as its severity, inside notistack's `SnackbarContent`. A project restyles the configurator's snackbars in its theme, from [`createGetThemeHandler`](?path=/docs/layouts-custom-theme-handler--docs), under `components.PhxSnackbar` (the admin's snackbars follow the admin's own theme, which ignores the theme handler):
+
+```ts
+// Part of the ThemeOptions a theme handler returns
+const components: ThemeOptions['components'] = {
+  PhxSnackbar: {
+    styleOverrides: {
+      alert: ({ theme }) => ({ borderRadius: 0, boxShadow: theme.shadows[3] }),
+      actionButton: { fontWeight: 600, textTransform: 'none' },
+    },
+  },
+}
+```
+
+- `styleOverrides` styles three slots: `content`, notistack's outer element; `alert`, the `Alert` with the message; and `actionButton`, a button such as **Dismiss**.
+- `defaultProps.slotProps` passes props to the slots, such as `{ alert: { variant: 'filled' } }`, and `defaultProps.slots` replaces a slot's component. The `MuiAlert` and `MuiButton` overrides of the theme reach the snackbars too.
+- A snackbar's button is described as data, not as an element: the code that raises it passes `actionButton: { label, onClick }` to notistack's `enqueueSnackbar`, and `PhxSnackbar` renders it in the `actionButton` slot, an MUI `Button` with `color="inherit"` and `size="small"`, after the snackbar's notistack `action` if it has one. `onClick` receives the snackbar's key, to close it with `closeSnackbar`. A project's own snackbars take the same option, typed by `SnackbarActionButton` from `@salsita-ai/sdk/react`, so their buttons follow the theme; an element passed as `action` renders as it is.
+- Where the snackbars appear is the snackbar root's job, see `DesktopSnackbarsRoot` and `MobileSnackbarsRoot`.
+
 ## Desktop sidebar
 
 | Member                        | Shows                                                                                                                                                                                                                                                                                                                                                                                                                                   | Fed by                                                                                                                                                                                                                                                                                                     | With nothing configured                                                                                                                                                                                                                                                                                                          | Read mode                                                                                                                                                                                                  |

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

@@ -40,7 +40,31 @@ pnpm phoenix dev
 3. Adds the `dev`, `build`, `deploy`, `check` and `fix` scripts to `package.json` (see [Project Scripts](#project-scripts)). A script the project already has under one of those names keeps its command.
 4. Writes a starter spec (`spec/application.yaml`, `spec/configurator.yaml`) with one resizable, recolorable box, and switches `package.json` to the application-spec pipeline.
 
-The next steps it prints use the package manager you ran it with, or name none when it cannot tell. It asks nothing, writes no `.env` and contacts no server. `phoenix sync` then generates every other project file, including the agent skills described in [Project Structure](?path=/docs/phoenix-project-structure--docs). The `.gitignore` is among them only when the folder is inside a git repository, so run `git init` before the first sync, or sync again after it.
+The next steps it prints use the package manager you ran it with, or name none when it cannot tell. It asks nothing, writes no `.env` and contacts no Phoenix server. It does send the operational telemetry described below unless telemetry is disabled. `phoenix sync` then generates every other project file, including the agent skills described in [Project Structure](?path=/docs/phoenix-project-structure--docs). The `.gitignore` is among them only when the folder is inside a git repository, so run `git init` before the first sync, or sync again after it.
+
+### CLI telemetry
+
+Operational CLI telemetry is enabled by default. Recognized top-level `phoenix` commands send lifecycle events directly to Amplitude's US ingestion endpoint. Current commands record both started and completed events. Legacy commands retain their existing exit behavior, so completion may be absent when they exit directly, including when legacy `dev` stops.
+
+For `phoenix dev`, `cli_dev_server_ready` records that startup finished and the server is listening; it does not prove that a browser connected or the application works. Its `duration_ms` measures startup time. With the current application-spec pipeline, the command stays open until its existing shutdown path emits completion, whose duration covers the whole run. A normal stop is not evidence of abandonment, and a missing completion (for example after a forced kill) means the outcome is unknown.
+
+Aliases are recorded as their canonical command names. Delivery failures never change the command result, and the CLI stops waiting for each delivery after one second.
+
+Before a successful `phoenix login`, telemetry uses only random anonymous identifiers. Failed login attempts remain anonymous. The CLI stores an installation UUID, work-session UUID and last activity time in `~/.phoenix/telemetry.json`; a work session continues while commands occur less than 30 minutes apart.
+
+After a successful login, the login completion and later commands from that installation include the stable authenticated builder user ID and the internal workspace UUID. Amplitude uses the unchanged installation ID to associate the earlier anonymous command path with that user. A later successful login replaces the stored user and workspace association. The state file never contains a login token, email address, machine fingerprint, project path or project content. Because the installation ID belongs to the operating-system user profile, people who share that profile also share its command history and latest association.
+
+The events contain only:
+
+- schema version, source (`cli`) and command name;
+- unique event and command-attempt IDs;
+- occurrence time, phase, safe outcome/failure category and duration;
+- SDK version, traffic classification (`unknown` before authentication, `general` after it) and work-session ID;
+- after successful login only, the authenticated builder user ID and workspace UUID.
+
+The CLI never sends raw arguments, local paths, environment values, credentials, source/specification content, URLs, free text or raw error messages. The shipped Amplitude ingestion API key is public and only selects the destination project; it grants no read or administrative access. Events sent by a public client can be forged and are observations, not authoritative proof of deployment or server state.
+
+Set `PHOENIX_TELEMETRY_DISABLED=1` to opt out. The opted-out CLI neither sends telemetry nor creates or updates the state file. `PHOENIX_TELEMETRY_FILE` overrides the state path for tests and other isolated environments.
 
 ### Which project `phoenix dev` develops in
 
@@ -164,6 +188,8 @@ A project has one generated env file. Phoenix keeps it in `.phoenix/`, as `.phoe
 - The deployment and environment commands (`deployment:prepare`, `deployment:prepare-dev`, `deployment:prepare-local`, `deployment:build-envs` and the others with an `--outFile` option) write `.env.generated` in the project root unless `--outFile` or `OUT_FILE` names another file. Deploy pipelines read it there. Once one of them has written it, `phoenix dev` and `phoenix build` use it.
 - Everything that reads environment variables follows the same rule: the root `.env.generated` when it exists, otherwise `.phoenix/.env.generated`. The two files are never merged.
 - `phoenix clean` removes `.phoenix/` and with it `.phoenix/.env.generated`; the next `phoenix dev` prepares the development deployment again. A root `.env.generated` stays.
+- `phoenix dev` starts on the deployment the file names, and prepares a new one when the file was written for another project, environment or server, when the spec registers something on the server the deployment was not prepared with (the domain model, the published data schema, the auth hook, the roles that may create configurations, or the assistant), and on `--force`. A running `phoenix dev` does not prepare again after such a change: it logs an error that asks for a restart.
+- Asset contents do not trigger preparation. After changing uploaded assets, restart with `phoenix dev --force` to prepare and upload them again.
 
 This holds for a project on the application-spec pipeline. In a project on the legacy pipeline (see [Current and legacy project tooling](#current-and-legacy-project-tooling)), `phoenix dev` always reads and writes `.env.generated` in the project root.
 
@@ -305,14 +331,16 @@ Starts the full development environment: Vite dev server, development webhook tu
 | `--environmentSlug`     | `ENVIRONMENT_SLUG` | package.json name    | Environment slug                                                                |
 | `--withLingui`          | `WITH_LINGUI`      | `false`              | Enable i18n extraction/compilation and watch i18n sources during dev            |
 | `--persistence`         | `PERSISTENCE_MODE` | `server`             | Persistence mode                                                                |
-| `--force` / `-f`        | `FORCE_REBUILD`    | `false`              | Force full rebuild, skip cache                                                  |
+| `--force` / `-f`        | `FORCE_REBUILD`    | `false`              | Force full rebuild, skip cache, and prepare the development deployment again    |
 | `--serverUrl`           | `SERVER_URL`       | the region's server  | Phoenix server URL                                                              |
 | `--region`              | `PHOENIX_REGION`   | `eu`                 | Region of the signed-in workspace, used when no server URL is set               |
 | `--skipUpload` / `--su` | `SKIP_UPLOAD`      | `false`              | Skip the S3 asset upload when the development deployment is prepared at startup |
 
 With the application-spec pipeline, `phoenix dev` creates an empty `src/` folder when the project has none, so that it rebuilds when the first source file, such as `src/webhooks/index.ts`, is added.
 
-With the application-spec pipeline, the SDK's own Lingui CLI runs with the configuration in `.phoenix/.linguirc`, both for `--withLingui` and when `phoenix sync` and `phoenix build` extract and compile the catalogs; see [Root Level Files](?path=/docs/phoenix-project-structure--docs#root-level-files). The dev server and `phoenix build` compile the Lingui macros (`msg`, `t`, `Trans` and the others, imported from `@lingui/core/macro`, `@lingui/react/macro` or `@lingui/macro`) with the SDK's own Lingui macro plugin and the same configuration, so the project needs neither `babel-plugin-macros` nor `@lingui/macro` for them. Babel macros of other packages are not compiled.
+By default, with the application-spec pipeline, `phoenix dev` bootstraps missing compiled catalogs for every configured locale at startup, so a fresh project can start without a prior sync. It compiles existing `.po` translations as they are and extracts a locale only when its `.po` source is also missing. Existing compiled catalogs and `.po` sources stay unchanged. New or changed messages still need `phoenix sync` or continuous updates enabled by `--withLingui` or `WITH_LINGUI=true`.
+
+The SDK's own Lingui CLI uses the configuration generated in `.phoenix/.linguirc`, both for `--withLingui` and when `phoenix sync` and `phoenix build` extract and compile the catalogs; see [Root Level Files](?path=/docs/phoenix-project-structure--docs#root-level-files). The dev server and `phoenix build` compile the Lingui macros (`msg`, `t`, `Trans` and the others, imported from `@lingui/core/macro`, `@lingui/react/macro` or `@lingui/macro`) with the SDK's own Lingui macro plugin and the same configuration, so the project needs neither `babel-plugin-macros` nor `@lingui/macro` for them. Babel macros of other packages are not compiled.
 
 In `server` persistence mode the project comes from `--projectSlug`, `PROJECT_SLUG` or `project` in the spec, and the credential from `DEVELOPMENT_KEY` or the `phoenix login` sign-in; see [Starting a New Project](#starting-a-new-project). When signed in, the environment is always your own development environment and `--environmentSlug` is ignored.
 
@@ -320,6 +348,7 @@ The dev server watches for changes in:
 
 - `spec/**/*.yaml` — Domain specification files
 - `src/**/*.{ts,tsx,yaml,yml,json,html,css}` — Source files
+- `package.json` — Root dependency declarations; changes recheck the SDK's peers. A mismatch is reported without stopping dev, and correcting the manifest triggers another rebuild. Install changed dependencies with your package manager; changes to installed packages can still require restarting dev.
 - `.env` — Environment file; a change restarts the Vite dev server
 - `.env.generated`, `.phoenix/.env.generated` — Generated env files; a change rebuilds the project files. Only a file that exists when `phoenix dev` starts is watched: a root `.env.generated` that a deployment command creates while dev runs is not watched; restart `phoenix dev` to use it.
 
@@ -336,7 +365,11 @@ Restart the application after fixing either failure; a subscriber or generation
 observed the attempted update.
 
 Domain-model changes are not applied live yet. Phoenix rejects them with a restart-required
-diagnostic so the mounted application cannot observe a new model with old configuration data. Other
+diagnostic so the mounted application cannot observe a new model with old configuration data. With
+server persistence, `phoenix dev` logs an error that asks for its own restart, because the
+development deployment keeps the schema it was prepared with until `phoenix dev` starts again and
+prepares it. After the restart, open the preview address it prints: a tab whose address has `?cid=`
+loads a configuration saved with the earlier model, which the new model rejects. Other
 generated bootstrap, admin, data, environment, and host-integration surfaces should also be treated
 as restart-required unless their feature documentation explicitly states live-update support.
 
@@ -609,7 +642,7 @@ Known limits:
 - 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.
+Generated projects carry the `phoenix` agent skill, whose linked Variants guide tells coding agents when to offer options, how to write each kind and what to do with your answer.
 
 ## SDK Development
 
@@ -750,7 +783,7 @@ Revokes the token on the server and removes it from the credentials file. `--reg
 
 ### `phoenix deploy`
 
-Validates the spec, 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.
+Validates the spec, 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 in the Feedback guide linked from the `phoenix` 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.
 
 To keep the conversation that led to a build, place a reviewed UTF-8 transcript in `conversation.log` at the project root before deploying. Deploy automatically includes it in the private source archive. Download the build's sources from Studio to read it; access is the same as for the rest of that build's sources. The build extractor skips the log, so it is not an application build input or a public asset. Missing logs produce a warning and deployment continues. Directories, links and special files at that path are rejected.
 
@@ -779,7 +812,7 @@ Pass the message as the argument for a short note, or `--file` for a longer repo
 
 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 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.
+Generated projects carry the `phoenix` agent skill. Its linked Feedback guide 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

@@ -199,21 +199,21 @@ 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                  |
+| 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.
 
@@ -242,9 +242,13 @@ With the application-spec pipeline, the Lingui configuration is `.phoenix/.lingu
 
 ### Agent Guidance
 
-Coding agents (Claude Code, Codex, Cursor) read the Phoenix agent skills. An `AGENTS.md` is yours to add for your own instructions; sync does not write one. 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, runs `phoenix deps`, installs, then runs `phoenix sync`. Other skill folders are never touched.
+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.
 
-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`.
+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`.
 
 ### Markers for Partial Auto-Generation
 

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

@@ -65,7 +65,7 @@ Every user who signs the CLI in gets their own development environment, so a tea
 
 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.
+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
 
@@ -85,7 +85,9 @@ On the server, the install runs pnpm. It follows your `pnpm-lock.yaml` and `pnpm
 
 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.
 
@@ -97,7 +99,7 @@ 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-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.
+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
 
@@ -107,5 +109,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/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

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

@@ -9,6 +9,7 @@ import type { AdminIntegrationService } from '#package/react-sdk';
 import type { $DomainEntity, DataCellValue, DataSchema, DomainEntity, DomainFactory, ProductPreset } from '../core/index.js';
 import type { AnalyticsSystem, RegistrableTransformer, TransformerFactory } from '../domain-context/index.js';
 import type { ElementRegistration, ProjectModule } from '../domain-runtime/index.js';
+import type { AdminPagesSection } from '../spec/index.js';
 import type { AssistantResolvedManifest } from './assistant/index.js';
 import type { WebComponentEventDescriptor } from './web-component-event.js';
 import type { WebComponentPropertyDescriptor } from './web-component-property.js';
@@ -55,30 +56,11 @@ export type DataSpec = {
 export type ChunksSpec = Readonly<Record<string, {
     readonly scope: string;
 }>>;
-export type AdminPagesSpec = {
-    readonly presets?: boolean | {
-        readonly categoryNavigationState?: string;
-        readonly presetNavigationState?: string;
-    };
-    readonly recipes?: ReadonlyArray<{
-        readonly name: string;
-        readonly navigationState?: string;
-    }>;
-    readonly pages?: ReadonlyArray<{
-        readonly key: string;
-        readonly title: string;
-        readonly icon?: string;
-        readonly navigationState?: string;
-        readonly entity?: string;
-        readonly component?: string;
-        readonly actionsComponent?: string;
-        readonly connectedDataEntry?: string;
-        readonly sidebar?: {
-            readonly title: string;
-            readonly component: string;
-        };
-    }>;
-};
+/**
+ * The admin pages of an application config: the `$adminPages` section of the application spec as
+ * written, which `createAdminPagesFromSpec` turns into admin pages; see {@link AdminPagesSection}.
+ */
+export type AdminPagesSpec = AdminPagesSection;
 type PersistenceConfig = {
     readonly type: 'server';
     /**

package/dist/domain/application/assistant/assistant-manifest.d.ts

@@ -1,3 +1,4 @@
+import type { AssistantFormElementDescriptor } from './form/index.js';
 /**
  * Where one exposed assistant GraphQL field reads its value on the `$` entity: a stored field name,
  * or an expression name including its `$`. `localized` marks a localizable value that resolves to a
@@ -7,18 +8,28 @@ export interface AssistantFieldSource {
     readonly source: string;
     readonly localized?: true;
 }
+/**
+ * What the integrator promises about a list of choices, so the agent can read it once and reuse it:
+ * `sameForAllInstances` when every entity of the type gets the same list, `constantDuringSession`
+ * when the list does not change during a session. A hint only adds a sentence to the description of
+ * the recipe group or options edge it is declared on; nothing verifies it.
+ */
+export declare const ASSISTANT_HINTS: readonly ['sameForAllInstances', 'constantDuringSession'];
+export type AssistantResolvedHint = (typeof ASSISTANT_HINTS)[number];
 /**
  * One recipe group the assistant manifest exposes on an entity type: a `childEntityRecipes` instance
  * under `childRecipes`, a `replaceEntityRecipes` instance under `replaceRecipes`. `groupId` is the
- * name the agent addresses the group by, `instanceName` the component instance it reads,
- * `description` the manifest's text replacing the component's group description, and `dryRuns`
- * whether the recipes of the group can be dry-run.
+ * name of its field on `<Type>ChildRecipes` or `<Type>ReplaceRecipes` and the id the agent passes to
+ * `addChild` or `replaceEntity`, `instanceName` the component instance it reads, `description` the
+ * manifest's text for that field, `dryRuns` whether the recipes of the group can be dry-run, and
+ * `hints` the sentences of the field's description saying when the agent can reuse what it read.
  */
 export interface AssistantRecipeGroup {
     readonly groupId: string;
     readonly instanceName: string;
     readonly description?: string;
     readonly dryRuns: boolean;
+    readonly hints: readonly AssistantResolvedHint[];
 }
 /**
  * The options edge of one writable field the assistant manifest links to its component. `field` is
@@ -35,6 +46,16 @@ export interface AssistantFieldOptions {
     readonly validate: boolean;
     readonly dryRuns: boolean;
 }
+/**
+ * One view the assistant manifest lets the agent take a screenshot of an entity from: `view` is the
+ * value of the `<Type>ScreenshotView` enum the agent asks for it by, `instanceName` the
+ * `agentScreenshot` component instance that renders it, and `description` what the view shows.
+ */
+export interface AssistantScreenshotView {
+    readonly view: string;
+    readonly instanceName: string;
+    readonly description: string;
+}
 /**
  * Experimental assistant manifest generated from the application spec `assistant` section. `sdl` is
  * the GraphQL schema text rebuilt from the resolved manifest; `fields` maps each GraphQL object type's exposed
@@ -46,7 +67,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; `actions` maps each custom `Mutation` field to the
+ * writable fields, and absent means none; `screenshots` lists, per entity type, the views
+ * `meta { screenshot }` renders, and absent means none; `actions` maps each custom `Mutation` field to the
  * declared action it runs, and absent means none; `lenses` holds the generated lens fragments, and
  * absent means none: `declarations` is the text the prompt shows, each lens once with its relations
  * spreading the lens itself, and `definitions` the valid GraphQL injected into an operation that
@@ -63,9 +85,12 @@ 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 screenshots?: Readonly<Record<string, readonly AssistantScreenshotView[]>>;
     readonly actions?: Readonly<Record<string, string>>;
     readonly lenses?: {
         readonly declarations: string;
         readonly definitions: string;
     };
+    /** The project's own form elements, in YAML order; absent means none. */
+    readonly formElements?: readonly AssistantFormElementDescriptor[];
 }

package/dist/domain/application/assistant/assistant-manifest.js

@@ -1 +1 @@
-export{};
+export const ASSISTANT_HINTS=["sameForAllInstances","constantDuringSession"];