@salsita-ai/sdk 0.50.0-develop.a926ccd94f → 0.50.0-develop.ab6a7ca8ae

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

@@ -0,0 +1,116 @@
+# Layout Slots
+
+A project layout registered as `ConfiguratorLayout` builds its UI from its own components and from the pieces of the built-in layout it wants to keep. Those pieces are the members of `LayoutSlots`, from `@salsita-ai/sdk/configurator`. This page lists every member: what it shows, what in the spec or the configurator's state feeds it, what it renders when the spec configures nothing for it, and what it does in read mode. [Configurator Interface → Loaded Configuration UI](?path=/docs/phoenix-configurator-interface--docs#loaded-configuration-ui) says what a project layout has to mount, and its [Hooks for a Project Layout](?path=/docs/phoenix-configurator-interface--docs#hooks-for-a-project-layout) list the hooks for a layout that draws its own UI.
+
+- [How the slots behave](#how-the-slots-behave)
+- [Canvas and services](#canvas-and-services)
+- [Desktop sidebar](#desktop-sidebar)
+- [Header, toolbar and controls](#header-toolbar-and-controls)
+- [Banners and branding](#banners-and-branding)
+- [Page footer](#page-footer)
+- [Phone layout](#phone-layout)
+- [Others](#others)
+
+## How the slots behave
+
+```tsx
+import { LayoutSlots } from '@salsita-ai/sdk/configurator'
+
+// Part of a ConfiguratorLayout: the built-in toolbar, placed by the layout in the bottom right corner
+export const Toolbar = () => (
+  <div style={{ position: 'absolute', insetBlockEnd: 24, insetInlineEnd: 24 }}>
+    <LayoutSlots.DesktopToolbar />
+  </div>
+)
+```
+
+- A slot takes no props unless its row names them, and reads what it shows from the spec and the configurator's state. It renders inside the configurator only, under a `ConfiguratorLayout`.
+- A slot brings its own look but not its place: it adds no padding or scrolling around itself, so the layout puts it in a container. Two members differ: `SharedCanvas` fills its nearest positioned ancestor, and `DesktopSidebar` brings the sidebar's spacing and scrolling with it.
+- Read mode means `useAccessService().accessInfo.viewMode` is `true`: a configuration shared for viewing is open, or the host sets the `readonly` property. "No change" in the read-mode column means the slot renders the same for a viewer, so the layout decides whether a viewer sees it.
+- `Desktop*` and `Mobile*` members are twins that differ in size and arrangement; [Phone layout](#phone-layout) lists the phone ones. The container's width, not the window's, decides which one fits: `useActiveViewports()` from `@salsita-ai/sdk/react` returns the breakpoints the container satisfies. The built-in layout uses the `Desktop*` members while `desktop` is active, for a container wider than 768 pixels, and the `Mobile*` members otherwise, while `mobile` is active; `phone` means narrower than 480 pixels and `tablet` between 480 and 1024.
+
+## Canvas and services
+
+| Member                 | Shows                                                                                                                                                                                                                                                                                                                        | Fed by                                                        | With nothing configured | Read mode |
+| ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- | ----------------------- | --------- |
+| `SharedCanvas`         | The 3D scene, in a container that is `position: absolute; inset: 0` with the scene's background colour. The scene is hidden for a moment while the preview expands or collapses.                                                                                                                                             | The scene of the spec, through `Canvas`                       | Always renders          | No change |
+| `Canvas`               | The WebGL canvas alone, or `GPUIssuePage` when the browser has no WebGL or no GPU acceleration. It reports the scene-assets loading phase the app loader waits for.                                                                                                                                                          | The scene, the canvas settings and the `CanvasLoader` element | Always renders          | No change |
+| `Services`             | Nothing visible: it mounts `InvariantViolations` and `SideEffects`, which show the messages of `useConfiguratorMessages()` as snackbars                                                                                                                                                                                      | The configurator's state                                      | Always mounted          | No change |
+| `InvariantViolations`  | When a change is rejected, a snackbar for each violation of the rejected state, including notices and warnings already present, as `<entity id>: <message>` (a `notice` as info, a `warning` as warning, `fixable` and `fatal` as error), and "Oops, something went wrong" for an error thrown while the state was validated | The spec's invariants                                         | Nothing                 | No change |
+| `SideEffects`          | An info snackbar for each committed update that carries a hint                                                                                                                                                                                                                                                               | The hints of committed updates                                | Nothing                 | No change |
+| `DesktopSnackbarsRoot` | The element the snackbars are rendered into: a stack anchored to its bottom edge, at most 320 pixels wide                                                                                                                                                                                                                    | Every snackbar the configurator raises                        | An empty element        | No change |
+
+- Mount `SharedCanvas`, not `Canvas`: `Canvas` suspends while it probes the GPU on its first mount, and `SharedCanvas` holds the boundary that catches it. Without either, the app loader stays on screen unless the project sets `appLoader: legacy`.
+- `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`, and also by the built-in finalize and footer actions when their handler fails and when saving the configuration fails. A layout that shows violations, side-effect hints and validation errors its own way calls `phx.frontend.useConfiguratorMessages(onMessage)` instead of mounting `Services`, 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.useFinalizeAction` raises no snackbar; its error is the hook's `error`.
+
+## Desktop sidebar
+
+| Member                        | Shows                                                                                                                                                                                                                                                                                            | Fed by                                                                                                                                                                                                                                                                                                     | With nothing configured                                                                                                                                                                                                                                                                                                          | Read mode                                                                                                                                                                                                  |
+| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `DesktopSidebar`              | The whole built-in desktop sidebar: tabs, back button, property pages and sidebar footer with their spacing, scrolling and empty states, and the assistant panel. Props: `width`, and `side` (`'start'` or `'end'`, typed `DesktopSidebarSide`; `DesktopSidebarProps` types both)                | The members below                                                                                                                                                                                                                                                                                          | As its parts                                                                                                                                                                                                                                                                                                                     | As its parts. In fullscreen it stays in place, transparent and inert                                                                                                                                       |
+| `DesktopSidebarTabs`          | Tabs that switch the navigation state                                                                                                                                                                                                                                                            | The `sidebarTabs` components of the selected entity; the `horizontalTabs` component is not shown here                                                                                                                                                                                                      | Nothing; also nothing while the summary is shown                                                                                                                                                                                                                                                                                 | No change                                                                                                                                                                                                  |
+| `useSidebarTabs()`            | A hook, `{ tabs, activeTab, onChange }`: each tab is `{ label, icon, value, isActive }`, `activeTab` is the active tab's value or `'none'`, and `onChange(value)` switches to that tab's first navigation state                                                                                  | As `DesktopSidebarTabs`                                                                                                                                                                                                                                                                                    | `tabs` is empty                                                                                                                                                                                                                                                                                                                  | No change                                                                                                                                                                                                  |
+| `DesktopSidebarBackButton`    | A "Back" button. Props: the MUI `Button` props and `icon`, also settable in the theme as `PhxDesktopSidebarBackButton`; the application config's `sidebarBackIcon` takes precedence over both                                                                                                    | The sidebar's way back: a navigation state to pop, a stacked property page, or a selected entity other than the root, unless the application config sets `showSelectionBackButton` to `false` or sets `ignoreSelectionInSidebar`                                                                           | Nothing while there is no way back                                                                                                                                                                                                                                                                                               | No change                                                                                                                                                                                                  |
+| `DesktopSidebarContent`       | The property pages of the selected entity with its entity header, a stacked page opened from them, or the summary page while the summary is shown. With the application config's `ignoreSelectionInSidebar` set, every `propertyPage` of every entity shows under the root, whatever is selected | `propertyPage`, `entityHeader`, `simpleSummary` and `customSummaryPage` components, and `ignoreSelectionInSidebar`                                                                                                                                                                                         | Nothing                                                                                                                                                                                                                                                                                                                          | **No change: the controls stay editable.** Limit them with `$filter.modes`, or render something else in read mode                                                                                          |
+| `useSidebarContent(options?)` | A hook, `{ content, goBack, hasMiniSidebar, hasSplitSidebar }`: `content` is what `DesktopSidebarContent` shows, `goBack` is the back action or `null`. `options` sets the `HeaderContainer` and `BodyContainer` components the content is wrapped in                                            | As `DesktopSidebarContent`                                                                                                                                                                                                                                                                                 | `content` is empty                                                                                                                                                                                                                                                                                                               | No change                                                                                                                                                                                                  |
+| `EntityHeader`                | An entity's title, subtitle, description and thumbnail, with its primary and secondary buttons, such as delete or replace. Props, typed `EntityHeaderProps`: `entityId` and `headerComponent`                                                                                                    | The texts and thumbnail from the entity's `detail` component (the title falls back to the entity type); the buttons from the `entityHeader` component passed in                                                                                                                                            | —                                                                                                                                                                                                                                                                                                                                | No change                                                                                                                                                                                                  |
+| `DesktopSidebarFooter`        | The price and the actions                                                                                                                                                                                                                                                                        | `basicSidebarFooter`, `universalSidebarFooter`, `readSidebarFooter`, `hiddenSidebarFooter` or `customSidebarFooter`. The basic footer offers a `finalizeButton`, else a button for a `finalizePage`, else a disabled button; the universal footer offers the `finalizeAction` and `otherAction` components | The basic footer: the price and a finalize button. With a `navigationSteps` component of two or more steps, previous and next step buttons and the finalize button only on the last step; with a summary and no steps, a **Summary** button until the summary is shown; in a preset embed, **Save Template** instead of finalize | With nothing configured, the read footer: price only. The basic footer hides its buttons. **The universal footer still shows its finalize and other actions to a viewer**; limit them with `$filter.modes` |
+
+A sidebar footer with `universalSidebarFooter` does not check read mode, although the component's own description says its buttons are hidden then. A viewer of a shared configuration sees its actions. The `custom` footer renders its children unchanged as well.
+
+## Header, toolbar and controls
+
+| Member                | Shows                                                                                                                        | Fed by                                                                                | With nothing configured                                                                                                                                                                                                                                                                                                                                                                         | Read mode                                                                                                            |
+| --------------------- | ---------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
+| `DesktopHeader`       | The floating, fixed or custom header                                                                                         | The first `floatingHeader`, `fixedHeader`, `hiddenHeader` or `customHeader` component | The floating header. Nothing with `hiddenHeader` or in fullscreen                                                                                                                                                                                                                                                                                                                               | The floating header shows the back button instead of the step navigation; the fixed header hides its horizontal tabs |
+| `DesktopToolbar`      | The toolbar's button groups                                                                                                  | The `toolbar` component's `desktop` list, or else a default set                       | Default buttons: fullscreen and camera reset; language with more than one locale; share unless sharing is disabled; measurements with more than one dimension or with `indicatorSwitch` on (the default), and help in that group when the project registers a `ToolbarHelp` element; undo and redo; the assistant when the spec has an `assistant` section. In fullscreen, only the exit button | The default set drops share and undo/redo; a configured `toolbar` is shown unchanged                                 |
+| `DesktopViewControls` | A toggle between view states                                                                                                 | The root entity's `viewControls` component and the active view state                  | Nothing without the component or without an active view state                                                                                                                                                                                                                                                                                                                                   | No change                                                                                                            |
+| `DesktopToolControls` | A vertical group of tool buttons that switch the tool state                                                                  | The root entity's `toolControls` component                                            | Nothing without the component                                                                                                                                                                                                                                                                                                                                                                   | No change                                                                                                            |
+| `ToolControls`        | The same component as `DesktopToolControls` and `MobileToolControls`                                                         | As `DesktopToolControls`                                                              | Nothing without the component                                                                                                                                                                                                                                                                                                                                                                   | No change                                                                                                            |
+| `DesktopCallToAction` | **The button that leaves a tool mode, not the finalize button.** Clicking it switches to the component's `exitTo` tool state | An `exitToolModeFab` component, usually filtered to the tool states it belongs to     | Nothing. It throws when more than one is active                                                                                                                                                                                                                                                                                                                                                 | Nothing                                                                                                              |
+
+Instead of `DesktopViewControls` or `MobileViewControls`, a layout can build its own view buttons with `phx.frontend.useActiveViewState()` and `phx.frontend.useSetViewState()`, which need no `viewControls` component, see [Hooks for a Project Layout](?path=/docs/phoenix-configurator-interface--docs#hooks-for-a-project-layout).
+
+## Banners and branding
+
+| Member                                 | Shows                                                                                                                                                                                                              | Fed by                                                                                                                                                                                                                       | With nothing configured           | Read mode                                                                                                                     |
+| -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
+| `DesktopReadonlyBanner`                | "You're viewing a read-only configuration" with an **Edit configuration** button that opens `CloneToEditDialog`. Props: the MUI `Alert` props and `icon`, also settable in the theme as `PhxDesktopReadonlyBanner` | `useIsCloningAllowed()`; its icon from the application config's `readonlyBannerIcon`                                                                                                                                         | Nothing unless cloning is allowed | **It does not check read mode.** The layout renders it only in read mode, as the built-in layout does while not in fullscreen |
+| `MobileReadonlyBanner`                 | An **Edit** button that opens `CloneToEditDialog`. Props: the MUI `Button` props and `icon`, also settable in the theme as `PhxMobileReadonlyBanner`                                                               | As `DesktopReadonlyBanner`                                                                                                                                                                                                   | Nothing unless cloning is allowed | As `DesktopReadonlyBanner`                                                                                                    |
+| `CloneToEditDialog`                    | The "Edit configuration" dialog that creates an editable copy of the configuration and opens it. Props, typed `CloneToEditDialogProps`: `open` and `onClose`                                                       | The open configuration                                                                                                                                                                                                       | —                                 | —                                                                                                                             |
+| `useIsCloningAllowed()`                | A hook, `boolean`: `true` when the application config sets `shareCloneToEdit` and the session's role may create configurations                                                                                     | The application config and the session                                                                                                                                                                                       | `false`                           | Does not check read mode                                                                                                      |
+| `DesktopPoweredBy` / `MobilePoweredBy` | The "Powered by Salsita" mark, a link                                                                                                                                                                              | Its props `visible`, `variant` (`'black'` or `'white'`), `href`, `title`, `slots` and `slotProps`. All but `href` and `title` are also settable in the theme as `PhxDesktopBrandingPoweredBy` / `PhxMobileBrandingPoweredBy` | The mark                          | No change                                                                                                                     |
+
+## Page footer
+
+| Member                           | Shows                                                   | Fed by                                                                                  | With nothing configured | Read mode |
+| -------------------------------- | ------------------------------------------------------- | --------------------------------------------------------------------------------------- | ----------------------- | --------- |
+| `DesktopFooter` / `MobileFooter` | A footer below the whole layout, not the sidebar footer | The project's `LayoutFooter` element, registered with `phx.frontend.createLayoutFooter` | Nothing                 | No change |
+
+## Phone layout
+
+The phone twins read the same spec as their desktop members.
+
+| Member                    | Shows                                                                     | Differences from the desktop member                                                                                                                                                                                                                                                                                                                                                       |
+| ------------------------- | ------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `MobileHeader`            | The header                                                                | The floating and fixed headers show a back button and the branding; the back button is hidden with steps and in read mode                                                                                                                                                                                                                                                                 |
+| `MobileToolbar`           | The toolbar                                                               | Reads the `toolbar` component's `mobile` list, rendered in reverse order. The default set has undo and redo, camera reset, fullscreen and the assistant, and drops undo and redo in read mode                                                                                                                                                                                             |
+| `MobileHamburgerMenu`     | A menu button that opens the remaining actions in a dialog                | Reads the `toolbar` component's `mobileMenu` list, or else share, measurements, language and help under the same conditions as the desktop toolbar; share is dropped in read mode. Nothing when the list is empty. Props: `icon` and `closeIcon`, also settable in the theme as `PhxMobileHamburgerMenu`; the application config's `hamburgerIcon` and `toolbarCloseIcon` take precedence |
+| `MobileTabs`              | Scrollable tabs that switch the navigation state                          | Reads the selected entity's `sidebarTabs` or the `horizontalTabs` component, and throws when both are active or when more than one of either is active. Nothing without tabs or while the summary is shown. Unlike the desktop fixed header, it keeps horizontal tabs in read mode                                                                                                        |
+| `MobileViewControls`      | A toolbar button with the active view's icon that opens the list of views | Nothing without the component, an active view state or that view's icon                                                                                                                                                                                                                                                                                                                   |
+| `MobileToolControls`      | The tool buttons                                                          | Same component as `DesktopToolControls`                                                                                                                                                                                                                                                                                                                                                   |
+| `MobileCallToAction`      | The button that leaves a tool mode                                        | Same as `DesktopCallToAction`                                                                                                                                                                                                                                                                                                                                                             |
+| `MobileSidebarBackButton` | A "Back" button                                                           | Same as `DesktopSidebarBackButton`, smaller, with `sidebarBackIcon` taking precedence the same way; its theme name is `PhxMobileSidebarBackButton`                                                                                                                                                                                                                                        |
+| `MobileSidebarContent`    | The property pages                                                        | Same content as `DesktopSidebarContent`                                                                                                                                                                                                                                                                                                                                                   |
+| `MobileSidebarFooter`     | The price and the actions                                                 | Same as `DesktopSidebarFooter`; the universal footer adds the step label and progress                                                                                                                                                                                                                                                                                                     |
+| `MobileSnackbarsRoot`     | The element the snackbars are rendered into                               | It does not position the snackbars: they keep notistack's `position: fixed` and sit at the viewport's edge wherever the root is. The built-in phone layout positions them with its own styles; a project layout styles `notistackSnackbarClasses.container` from `@salsita-ai/sdk/ui`                                                                                                     |
+
+## Others
+
+| Member                    | Shows                                                                                                                           |
+| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
+| `GPUIssuePage`            | `WebGLNotSupported` or `GPUAccelerationDisabled`, chosen by its `issue` prop. `Canvas` renders it; a layout does not need it    |
+| `GPUIssue`                | The two values of that prop, `'no-gpu'` and `'no-acceleration'`, as a constant and a type                                       |
+| `WebGLNotSupported`       | A full-page message that WebGL is not supported, with a **Go To Homepage** button that returns to the configurator's start page |
+| `GPUAccelerationDisabled` | A full-page message that GPU acceleration is disabled, with the same button                                                     |

package/dist/docs/phoenix/localization.mdx

@@ -116,28 +116,9 @@ After running `pnpm lingui:compile`, your custom translations will override the
 - Adapt translations for your target audience
 - Maintain consistency with your existing product language
 
-**Frontend integration**:
-
-```typescript
-import { configuratorBuilder } from 'project-domain'
-import { createI18n } from 'project-i18n'
-
-const i18n = createI18n()
-
-export const config = configuratorBuilder
-  .withComponentOptics(customComponents)
-  .withPresets(presets)
-  .withI18n(i18n) // Register i18n service with configurator
-  .buildConfig({
-    features: {
-      availableLocales: ['en', 'de', 'cs'],
-    },
-    services: {
-      logger,
-    },
-    // ... other configuration
-  })
-```
+**Frontend integration**: the generated `.phoenix` code creates the i18n service from `.phoenix/i18n.ts` and registers
+it with the application, so there is nothing to wire by hand. The languages come from `availableLocales` in
+`spec/application.yaml`.
 
 ## Working with YAML Domain Specifications
 

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

@@ -29,10 +29,11 @@ pnpm phoenix dev
 
 1. Refuses to run when a `spec/` folder already exists, so it never touches an existing project.
 2. Writes a `package.json` that depends on the CLI's SDK version when the folder has none. An existing `package.json` is kept, as long as it depends on the SDK.
-3. Writes a starter spec (`spec/application.yaml`, `spec/configurator.yaml`) with one resizable, recolorable box, and switches `package.json` to the application-spec pipeline.
-4. Writes `pnpm-workspace.yaml` with the pnpm settings the first install needs: the build scripts of the SDK's dependencies are allowed or denied, and `@salsita-ai/*` packages are exempt from pnpm's minimum release age. A project inside a pnpm monorepo gets no file; the workspace root holds these settings.
+3. Adds the `dev`, `build`, `deploy`, `check` and `fix` scripts to `package.json` (see [Project Scripts](#project-scripts)). A script the project already has under one of those names keeps its command.
+4. Writes a starter spec (`spec/application.yaml`, `spec/configurator.yaml`) with one resizable, recolorable box, and switches `package.json` to the application-spec pipeline.
+5. Writes `pnpm-workspace.yaml` with the pnpm settings the first install needs: the build scripts of the SDK's dependencies are allowed or denied, and `@salsita-ai/*` packages are exempt from pnpm's minimum release age. A project inside a pnpm monorepo gets no file; the workspace root holds these settings.
 
-It asks nothing, writes no `.env` and contacts no server. `phoenix sync` then generates every other project file, including `AGENTS.md` and the agent skills described in [Project Structure](?path=/docs/phoenix-project-structure--docs).
+It asks nothing, writes no `.env` and contacts no server. `phoenix sync` then generates every other project file, including the agent skills described in [Project Structure](?path=/docs/phoenix-project-structure--docs). The `.gitignore` is among them only when the folder is inside a git repository, so run `git init` before the first sync, or sync again after it.
 
 ### Which project `phoenix dev` develops in
 
@@ -114,8 +115,6 @@ For quick local development without a server, use:
 
 ```bash
 phoenix dev --persistence local-storage
-# or use the shortcut script:
-pnpm dev:local
 ```
 
 **Important:** The server must be running before `deployment:prepare-local` when using `server` persistence mode.
@@ -139,7 +138,7 @@ The same streams are available in the editor's **Logs** sidebar panel with per-s
 Runs all code quality checks in sequence:
 
 1. **TypeScript** — Type checking with `tsc`
-2. **ESLint** — Linting rules
+2. **ESLint** — Linting rules, over `src/`; a project with no files there passes
 3. **Prettier** — Code formatting
 
 ### `phoenix fix`
@@ -148,41 +147,44 @@ Auto-fixes ESLint and Prettier issues. Equivalent to running `eslint --fix` and
 
 ## Environment Variables
 
-When you run `deployment:prepare-local` or `deployment:prepare`, the CLI communicates with the Phoenix server, which generates environment variables and writes them to `.env.generated`.
+When you run `deployment:prepare-local` or `deployment:prepare`, the CLI communicates with the Phoenix server, which generates environment variables and writes them to `.env.generated`. `phoenix dev` does the same for its development deployment when it starts.
+
+### The generated env file
+
+A project has one generated env file. Phoenix keeps it in `.phoenix/`, as `.phoenix/.env.generated`, unless the project has a `.env.generated` in its root, which then is the one that counts.
+
+- `phoenix dev` reads and writes `.phoenix/.env.generated` in a project without a root `.env.generated`, and creates no file in the project root. In a project that has a root `.env.generated`, it reads and writes that file and `.phoenix/.env.generated` is not used.
+- 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.
+
+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.
 
 ### Data Flow
 
 ```
-spec/application.yaml → Server prepares environment → CLI writes .env.generated → Frontend/Webhooks read it
+spec/application.yaml → Server prepares environment → CLI writes the generated env file → Frontend/Webhooks read it
 ```
 
 ### Project Scripts
 
-When you run `phoenix sync` or `phoenix clean`, the CLI auto-generates standardized scripts in your `package.json`. These scripts are enforced — they cannot be overridden by custom scripts with the same name.
-
-| Script                     | Command                                                 | Purpose                                       |
-| -------------------------- | ------------------------------------------------------- | --------------------------------------------- |
-| `dev`                      | `phoenix dev`                                           | Dev server with hot reload                    |
-| `dev:local`                | `phoenix dev --persistence local-storage`               | Dev without server dependency                 |
-| `build`                    | `phoenix build`                                         | Production build                              |
-| `clean`                    | `phoenix clean`                                         | Clean all artifacts and rebuild               |
-| `sync`                     | `phoenix sync`                                          | Sync generated code and dependencies          |
-| `check`                    | `phoenix check`                                         | Run all checks (TypeScript, ESLint, Prettier) |
-| `ts:check`                 | `phoenix check`                                         | Alias for `check`                             |
-| `fix`                      | `phoenix fix`                                           | Auto-fix lint and formatting issues           |
-| `lint:fix`                 | `eslint src --fix`                                      | ESLint fix only                               |
-| `prettify:fix`             | `prettier --write .`                                    | Prettier fix only                             |
-| `verify:fix`               | `phoenix build && phoenix fix && phoenix check --types` | Build, fix, then type-check                   |
-| `test`                     | `vitest --passWithNoTests run`                          | Run tests                                     |
-| `test:watch`               | `vitest`                                                | Tests in watch mode                           |
-| `prepare:ci`               | `phoenix prepare:ci`                                    | CI environment setup                          |
-| `deployment:prepare-local` | `phoenix deployment:prepare-local`                      | Prepare local environment                     |
-
-Custom scripts you add to `package.json` are preserved during sync. Deprecated scripts (like `environment:create`, `deployment:register`) are automatically removed.
+`phoenix init` writes five scripts into `package.json`, each a shortcut for the CLI command of the same name:
+
+| Script   | Command          | Purpose                                       |
+| -------- | ---------------- | --------------------------------------------- |
+| `dev`    | `phoenix dev`    | Dev server with hot reload                    |
+| `build`  | `phoenix build`  | Production build                              |
+| `deploy` | `phoenix deploy` | Build and publish the project                 |
+| `check`  | `phoenix check`  | Run all checks (TypeScript, ESLint, Prettier) |
+| `fix`    | `phoenix fix`    | Auto-fix lint and formatting issues           |
+
+The scripts are yours: change, rename or delete them, and add your own. `phoenix sync` and `phoenix clean` leave the `scripts` section of `package.json` as it is, so they add no script, restore none you removed and remove none. Every CLI command also runs without a script, as `pnpm phoenix <command>`.
+
+A project may have other scripts than these five, such as `sync`, `test` or `verify:fix`; they are its own and stay as they are. All of this holds for a project on the application-spec pipeline, which `phoenix init` selects. In a project on the legacy pipeline (see [Current and legacy project tooling](#current-and-legacy-project-tooling)), `phoenix sync` and `phoenix clean` write their own set of scripts into `package.json` on every run, over scripts of the same name.
 
 ### Server-Generated Variables
 
-These are automatically computed by the server and written to `.env.generated`:
+These are automatically computed by the server and written to the generated env file:
 
 | Variable                         | Purpose                                                 |
 | -------------------------------- | ------------------------------------------------------- |
@@ -231,7 +233,7 @@ A build pipeline that receives the source archive of a [`phoenix deploy`](#phoen
 - it refuses an archive over 200 MB, one that extracts to more than 1 GB, or one with more than 100,000 files;
 - it refuses links, special files, absolute paths, paths that leave the folder, names with control characters, and entries that repeat or collide with an earlier one;
 - it refuses an archive it cannot read to the end, such as a truncated upload;
-- it extracts only project files, the same set `phoenix deploy` packs, and reports the entries it left out.
+- it extracts only project files and reports the entries it left out, including the optional `conversation.log` that deploy keeps in the private archive for review.
 
 `<folder>` must be new or empty. When the command refuses an archive, it removes the folder, so a partly extracted project is never built.
 
@@ -257,17 +259,20 @@ The frontend reads these at runtime from the generated config:
 | Variable                         | Required | Default                 |
 | -------------------------------- | -------- | ----------------------- |
 | `IS_DEV`                         | No       | `false` (`true` in dev) |
+| `ASSISTANT_STRICT_THREADS`       | No       | `false`                 |
 | `AWS_S3_PUBLIC_RESOURCES_BUCKET` | Yes      | —                       |
 | `AWS_S3_RESOURCES_REGION`        | Yes      | —                       |
 | `DEPLOYMENT_RESOURCES_PATH`      | No       | `deployment-resources`  |
 | Clerk vars (if enabled)          | Yes      | —                       |
 
+A development environment keeps the AI assistant's conversation when the assistant setup (manifest, instructions, AI settings) changes, and applies the new setup from the next message on. Set `ASSISTANT_STRICT_THREADS=true` in `.env` to try the behavior of every other environment locally, where a changed setup locks the conversation and the next message continues it in a summarized one. The variable has no effect outside a development environment.
+
 ### Precedence
 
 Environment variables are resolved in this order (highest to lowest priority):
 
 1. Process environment variables (shell)
-2. `.env.generated` (created by deployment commands)
+2. [The generated env file](#the-generated-env-file): `.env.generated` in the project root when the project has one, otherwise `.phoenix/.env.generated`
 3. `.env` (manual overrides)
 
 ### Generated Config Files
@@ -283,20 +288,22 @@ The Phoenix CLI auto-generates config files that read these variables:
 
 Starts the full development environment: Vite dev server, development webhook tunnel, domain-cli watcher, and editor WebSocket server.
 
-| Flag                   | Env Variable       | Default              | Description                                                                     |
-| ---------------------- | ------------------ | -------------------- | ------------------------------------------------------------------------------- |
-| `--workspace`          | —                  | from `.phoenix.json` | Override workspace mode                                                         |
-| `--editor`             | `ENABLE_EDITOR`    | `true`               | Enable editor file generation                                                   |
-| `--editorWsPort`       | `EDITOR_WS_PORT`   | `3020`               | Editor WebSocket port                                                           |
-| `--debug`              | `DEBUG`            | `false`              | Verbose logging                                                                 |
-| `--projectSlug`        | `PROJECT_SLUG`     | `local`              | Project slug                                                                    |
-| `--environmentSlug`    | `ENVIRONMENT_SLUG` | package.json name    | Environment slug                                                                |
-| `--withLingui`         | `WITH_LINGUI`      | `false`              | Enable i18n extraction/compilation and watch i18n sources during dev            |
-| `--persistence`        | `PERSISTENCE_MODE` | `server`             | Persistence mode                                                                |
-| `--force` / `-f`       | `FORCE_REBUILD`    | `false`              | Force full rebuild, skip cache                                                  |
-| `--serverUrl`          | `SERVER_URL`       | the region's server  | Phoenix server URL                                                              |
-| `--region`             | `PHOENIX_REGION`   | `eu`                 | Region of the signed-in workspace, used when no server URL is set               |
-| `--skipUpload` / `-su` | `SKIP_UPLOAD`      | `false`              | Skip the S3 asset upload when the development deployment is prepared at startup |
+| Flag                    | Env Variable       | Default              | Description                                                                     |
+| ----------------------- | ------------------ | -------------------- | ------------------------------------------------------------------------------- |
+| `--workspace`           | —                  | from `.phoenix.json` | Override workspace mode                                                         |
+| `--editor`              | `ENABLE_EDITOR`    | `true`               | Enable editor file generation                                                   |
+| `--editorWsPort`        | `EDITOR_WS_PORT`   | `3020`               | Editor WebSocket port                                                           |
+| `--debug`               | `DEBUG`            | `false`              | Verbose logging                                                                 |
+| `--projectSlug`         | `PROJECT_SLUG`     | `local`              | Project slug                                                                    |
+| `--environmentSlug`     | `ENVIRONMENT_SLUG` | package.json name    | Environment slug                                                                |
+| `--withLingui`          | `WITH_LINGUI`      | `false`              | Enable i18n extraction/compilation and watch i18n sources during dev            |
+| `--persistence`         | `PERSISTENCE_MODE` | `server`             | Persistence mode                                                                |
+| `--force` / `-f`        | `FORCE_REBUILD`    | `false`              | Force full rebuild, skip cache                                                  |
+| `--serverUrl`           | `SERVER_URL`       | the region's server  | Phoenix server URL                                                              |
+| `--region`              | `PHOENIX_REGION`   | `eu`                 | Region of the signed-in workspace, used when no server URL is set               |
+| `--skipUpload` / `--su` | `SKIP_UPLOAD`      | `false`              | Skip the S3 asset upload when the development deployment is prepared at startup |
+
+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.
 
 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.
 
@@ -304,7 +311,8 @@ The dev server watches for changes in:
 
 - `spec/**/*.yaml` — Domain specification files
 - `src/**/*.{ts,tsx,yaml,yml,json,html,css}` — Source files
-- `.env`, `.env.generated` — Environment files (triggers full Vite restart)
+- `.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.
 
 When linked SDK packages are detected (`phoenix link`), changes to SDK dist files are also watched.
 
@@ -396,6 +404,8 @@ Removes all build artifacts (`.phoenix/`, `node_modules/`), reinstalls dependenc
 
 Syncs project dependencies and regenerates all project files without building Vite bundles or webhooks. Faster than `clean` — use this for routine updates after changing spec files or upgrading dependencies. Before installing, it adds the pnpm settings `phoenix init` writes to a standalone project's `pnpm-workspace.yaml` when they are missing; values you set there are kept.
 
+With the application-spec pipeline (see [Current and legacy project tooling](#current-and-legacy-project-tooling)), `.gitignore` is written only when the project is inside a git repository: the project folder or one of its parent folders holds a `.git` entry. Outside a repository, sync neither creates the file nor changes one that is already there, and the same holds for `dev`, `build` and `clean`. Run `git init` before the first sync, or sync again after it, to get the file. The legacy pipeline writes `.gitignore` in every project.
+
 | Flag             | Env Variable    | Default | Description                    |
 | ---------------- | --------------- | ------- | ------------------------------ |
 | `--force` / `-f` | `FORCE_REBUILD` | `false` | Force full rebuild, skip cache |
@@ -491,6 +501,85 @@ phoenix screenshot -o preview.png -w 1920 --height 1080
 | `--height`        | `1080`  | Image height in pixels         |
 | `--format` / `-f` | `png`   | Image format (`png` or `jpeg`) |
 
+### `phoenix variants`
+
+Show several options over the configurator and wait for your pick. It is built for coding agents: when a decision is a matter of taste, such as the edge of a table top, how glossy a finish is or where a control sits, the agent writes one file per option, you choose in the browser, and the command hands your answer back to the agent.
+
+```bash
+phoenix variants .phoenix/variants/table-edge --title 'Which edge suits the table?' --description 'Only the edge of the top differs.'
+```
+
+Every `<id>.variant.js` script or `<id>.html` page in the folder is one option, shown in file-name order. Each script edits frontend project files on top of the same captured baseline. Original is always the first choice and restores that baseline. Switching options removes the previous option's edits and applies the selected script; the editor dialog has any number of choices on the left and your already loaded configurator on the right.
+
+```js
+// .phoenix/variants/brand/blue.variant.js
+export const title = 'Blue brand'
+export const description = 'A blue primary colour with the current layout.'
+
+export default ({ read, write, remove }) => {
+  const file = 'src/handlers/theme.ts'
+  write(file, read(file).replace("main: '#E93335'", "main: '#2364aa'"))
+}
+```
+
+`read(path)` always reads the baseline. `write(path, contents)` replaces or creates a file; `remove(path)` deletes it. Scripts run in the browser and collect edits; Phoenix validates and writes the batch locally. Supported files are YAML under `spec/` outside `spec/admin/`, and TypeScript under `src/components`, `transformers`, `handlers`, `elements` and `_`-prefixed shared folders. Expressions, actions and invariants also run on the server, so a script cannot edit them.
+
+For standalone UI or branding proposals, write self-contained HTML files. Each page renders in its own iframe when selected; its `<title>` names the option and `<meta name="description" content="...">` describes it. HTML and scripts may share a set if their file names give distinct option ids.
+
+```html
+<!-- .phoenix/variants/brand/blue.html -->
+<!doctype html>
+<title>Blue studio</title>
+<meta name="description" content="A calm blue identity with generous spacing." />
+<style>
+  body {
+    margin: 0;
+    padding: 40px;
+    background: #f0f5fa;
+    color: #163b66;
+    font-family: sans-serif;
+  }
+</style>
+<h1>Made for your everyday.</h1>
+<button>Design your table</button>
+```
+
+Scripts run once per selection. The completed file batch calls the existing rebuild queue directly, without a separate file-change event stream or a watcher that reapplies the option.
+
+Use script options for controls, layout, brand, lights, visual effects, materials, positions, components, elements and transformers. Changes to the model, schemas, data or deployment settings are rejected before any files are written. Environment files, webhooks, their shared implementation dependencies, dependencies and uploaded assets cannot be overridden. Files connected through symbolic links are also excluded, so restoring the baseline preserves the original files. No server preparation or webhook rebuild runs for a variant transaction.
+
+Picking a script keeps its exact implementation in the project. Picking an HTML page returns the selected proposal for the agent to implement; the page itself changes no project source files. Choosing Original keeps the captured baseline. Users finish by confirming Original or another option. Escape stays available to the configurator, and clicking the backdrop leaves the comparison open. The agent can use `--close` to restore the baseline source files without giving an answer. Phoenix records recovery information on disk and restores interrupted previews at the next `phoenix dev` start. It never overwrites a file edited outside the preview: switching options over such an edit is refused, and when the comparison ends, or is restored at the next start, that file is left as it is with a warning in the dev log while the others are restored. Other source changes made while a comparison is open are rebuilt once it ends.
+
+Answers are held for four seconds with Undo and Send now.
+
+The command prints the outcome as JSON. After `chosen` it removes the folder:
+
+| `status`  | Meaning                                                                                                                                      |
+| --------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
+| `chosen`  | An option was picked: `choice` is its id, or `null` for Original; `label` is its name.                                                       |
+| `waiting` | The wait ran out. The preview stays open: the same command attaches to it again, and an answer given in between is returned by the next run. |
+| `closed`  | The preview was closed without an answer, by `--close` or by another set of options taking its place. The folder is kept.                    |
+
+| Flag                   | Default                       | Description                                               |
+| ---------------------- | ----------------------------- | --------------------------------------------------------- |
+| `--title` / `-t`       | `Which option do you prefer?` | Question shown above the options                          |
+| `--description` / `-d` | —                             | A line saying what differs between the options            |
+| `--timeout`            | `540`                         | Seconds to wait for the answer                            |
+| `--keep`               | `false`                       | Keep the folder after the answer                          |
+| `--close`              | `false`                       | Close the open preview without an answer; needs no folder |
+| `--port` / `-p`        | `3020`                        | Editor WebSocket port                                     |
+
+Known limits:
+
+- Variant transactions start rebuilding immediately, bypassing the normal file-watcher debounce. Hot reload still needs to parse and apply the updated implementation. There is no wait for UI or scene loading to settle; allow a visible transition to finish before judging or choosing.
+- Only one option is displayed at a time; simultaneous comparison is not supported.
+- For script options and Original, the dialog moves the existing configurator into the preview and returns it on close, preserving the loaded scene, camera and UI state. Opening the dialog starts no second application or initial loading screen. Configuration interactions still change the current configuration; restoring source files does not undo them.
+- Custom scripts are trusted project code. Their file API stages edits; scripts must not make network requests or other side effects.
+- Binary assets, CSS files, locale catalog changes, dependency changes and edits requiring a full application restart are unsupported.
+- Storybook `story-dev` has no variant previews. A project on the legacy pipeline has no variant previews; the command says so and exits.
+
+Generated projects carry the `phoenix-variants` agent skill, which tells coding agents when to offer options, how to write each kind and what to do with your answer.
+
 ## SDK Development
 
 ### `phoenix link`
@@ -603,7 +692,7 @@ SDK-builder workspaces sign the CLI in with a personal API token instead of proj
 
 Signs the CLI in to the SDK-builder workspace `<customer>`:
 
-1. Opens Studio, where you name the token and approve the sign-in (use `--no-open` to only print the link). The page shows the workspace, your account, the computer the CLI runs on and how long the link still works. The CLI suggests the name `phoenix CLI on <computer>`; change it so you can tell your machines and agents apart later.
+1. Opens Studio, where you name the token and approve the sign-in (use `--no-open` to only print the link). Only a super admin of the workspace can open its Studio, so only a super admin can sign the CLI in. The page shows the workspace, your account, the computer the CLI runs on and how long the link still works. The CLI suggests the name `phoenix CLI on <computer>`; change it so you can tell your machines and agents apart later.
 2. Studio sends a one-time code back to the CLI on `127.0.0.1`.
 3. The CLI exchanges the code for a token with the name you approved, and sends the browser back to Studio, which confirms the sign-in.
 
@@ -611,12 +700,12 @@ Signs the CLI in to the SDK-builder workspace `<customer>`:
 
 The token is stored in `~/.phoenix/credentials.json`, readable only by you, per server, together with the Studio URL of the sign-in; `PHOENIX_CREDENTIALS_FILE` moves the file. The token works until you revoke it. Signing in again to the same server revokes the token it replaces; the CLI warns if the server could not revoke it.
 
-| Flag                  | Default                              | Description                                      |
-| --------------------- | ------------------------------------ | ------------------------------------------------ |
-| `--region`            | `eu`                                 | Phoenix region of the workspace: `eu` or `us`    |
-| `--serverUrl` / `-su` | the region's server                  | Phoenix server URL, for a local or custom server |
-| `--studioUrl`         | the workspace's Studio in the region | Studio URL of the workspace                      |
-| `--open`              | `true`                               | Open the approval page in your browser           |
+| Flag                   | Default                              | Description                                      |
+| ---------------------- | ------------------------------------ | ------------------------------------------------ |
+| `--region`             | `eu`                                 | Phoenix region of the workspace: `eu` or `us`    |
+| `--serverUrl` / `--su` | the region's server                  | Phoenix server URL, for a local or custom server |
+| `--studioUrl`          | the workspace's Studio in the region | Studio URL of the workspace                      |
+| `--open`               | `true`                               | Open the approval page in your browser           |
 
 The sign-in follows the region, not the `SERVER_URL` in a project's `.env`: that variable names the server of the project's own environment. The CLI prints the server it signs in to.
 
@@ -630,6 +719,10 @@ Revokes the token on the server and removes it from the credentials file. `--reg
 
 Validates the spec, adds the pnpm settings `phoenix init` writes to `pnpm-workspace.yaml` when they are missing, packs and uploads the project, starts its build on the server and follows it until the configurator is live. Before the upload the server compares the domain model with the deployed one: a model that changed under an already deployed model version is refused with the reason, and needs a new model version and a [migration](?path=/docs/phoenix-migrations--docs). Once the build starts it prints `Follow the build in Studio: <url>`, the build's page in the Studio you signed in through; a sign-in stored by an older CLI has no Studio URL, so sign in again to get the link. After `Your configurator is live at <url>` it prints one line for coding agents, which tells them to offer the run evaluation of the `phoenix-feedback` skill once you have nothing more to build; you can ignore it when you run the command yourself. `--region` or `--serverUrl` selects the server, as for `login`; `--no-wait` returns as soon as the build starts.
 
+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.
+
+The Phoenix agent skill explains how to prepare the transcript: prefer a native session export; otherwise mark a reconstruction as incomplete. Preserve available user/assistant messages and tool calls, cap individual tool results at 16 KiB with explicit truncation markers, and reference images rather than embedding them. Include the agent, export time, source and known omissions. Review and redact credentials or unrelated sensitive content before approving upload. The CLI uploads the file as supplied; it does not collect agent history, redact content, check freshness or verify completeness. Remove the file from the project root to deploy without it. The log counts toward the source archive's existing size limits; there is no separate conversation upload or viewer.
+
 ### `phoenix feedback [message]`
 
 Sends feedback about the SDK, the CLI, the documentation or Studio to the Phoenix team. It needs `phoenix login`: the server records the workspace, user and API token of the sign-in, so the message itself needs no introduction.
@@ -649,7 +742,7 @@ Pass the message as the argument for a short note, or `--file` for a longer repo
 | `--agent`              | —              | —                             | Name of the coding agent that writes the feedback         |
 | `--projectSlug` / `-p` | `PROJECT_SLUG` | `project` of the spec, if any | Workspace project the feedback is about                   |
 | `--region`             | —              | `eu`                          | Phoenix region of the workspace: `eu` or `us`             |
-| `--serverUrl` / `-su`  | —              | the region's server           | Phoenix server URL, for a local or custom server          |
+| `--serverUrl` / `--su` | —              | the region's server           | Phoenix server URL, for a local or custom server          |
 
 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.