@salsita-ai/sdk 0.50.0-develop.b335a15889 → 0.50.0-develop.bc08a38ffe

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

@@ -0,0 +1,114 @@
+# 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.
+
+## 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`.
+
+## 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                                                                                                              |
+
+## 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.
@@ -158,27 +157,19 @@ spec/application.yaml → Server prepares environment → CLI writes .env.genera
 
 ### 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
 
@@ -231,7 +222,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,11 +248,14 @@ 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):
@@ -283,20 +277,20 @@ 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 |
 
 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.
 
@@ -396,6 +390,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 |
@@ -690,12 +686,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.
 
@@ -709,6 +705,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.
@@ -728,7 +728,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.
 

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

@@ -49,6 +49,13 @@ project-root/
 | `locales/`      | Locale catalogs (`.po` sources; compiled `.ts`, do not edit)           |
 | `_*`            | Shared code folders at any depth (not auto-imported)                   |
 
+Every file in `components/`, `elements/`, `expressions/`, `actions/`, `invariants/`, `transformers/` and `handlers/`
+(and their `admin/` counterparts) is imported by its location, so its default export must be what that folder's `phx`
+factory returns, or an array of those. A file that exports anything else, such as a plain React component in
+`elements/`, stops the application at start with an `Invalid default export in <file>` error that names the expected
+shape. When several files in `handlers/`, `elements/`, `transformers/`, `components/`, `admin/elements/` and
+`admin/components/` are wrong, the error lists all of them, one numbered line per file. Keep plain components and helpers in a `_*` folder.
+
 ### Admin Folders (src/admin/)
 
 The `admin/` folder supports these admin-specific categories:
@@ -172,25 +179,29 @@ type CustomMaterial = Phx['AdminModel']['CustomMaterial']
 
 | File                                                   | Auto-Generated? | Notes                                  |
 | ------------------------------------------------------ | --------------- | -------------------------------------- |
-| `package.json`                                         | Partially       | Dependencies merged, scripts preserved |
+| `package.json`                                         | Partially       | Dependencies merged, scripts untouched |
 | `tsconfig.json`                                        | Yes             | Managed by Phoenix                     |
 | `eslint.config.js`                                     | Yes             | Managed by Phoenix                     |
 | `prettier.config.js`                                   | Yes             | Managed by Phoenix                     |
-| `.prettierignore`                                      | Yes             | Managed by Phoenix                     |
+| `.prettierignore`                                      | No              | Optional and your own; see below       |
 | `.linguirc`                                            | Yes             | Managed by Phoenix                     |
 | `.nvmrc`                                               | Yes             | Managed by Phoenix                     |
-| `.gitignore`                                           | Partially       | User entries between markers preserved |
+| `.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             | Auto-generated IDs, git-ignored        |
 | `README.md`                                            | No              | Project documentation                  |
-| `AGENTS.md`                                            | Once            | Coding-agent instructions, yours after |
+| `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.
+
+With the application-spec pipeline (see [Current and legacy project tooling](?path=/docs/phoenix-phoenix-cli--docs#current-and-legacy-project-tooling)), Phoenix does not write a `.prettierignore`, and a fresh clone or CI checkout of a project has none. `phoenix check` and `phoenix fix` do not read one: they skip `.phoenix/`, `dist/`, the compiled catalogs in `src/locales/`, `pnpm-lock.yaml` and `.linguirc` on their own. A project that runs Prettier directly, as `prettier --check .` or from an editor, can add its own `.prettierignore`. To commit it, add a `!.prettierignore` line after the Phoenix block of `.gitignore`, because that block lists the file. The legacy pipeline writes `.prettierignore` on every sync.
+
 ### DO NOT EDIT (Fully Auto-Generated)
 
 - **Everything in `.phoenix/`** - Completely regenerated on each build. The one exception is `.phoenix/variants/`, where a coding agent writes the option files for `phoenix variants`; a rebuild keeps it
-- `tsconfig.json`, `eslint.config.js`, `prettier.config.js`, `.prettierignore`
+- `tsconfig.json`, `eslint.config.js`, `prettier.config.js`
 - `.linguirc`, `.nvmrc`
 - `src/locales/**/*.ts` - Compiled from `.po` catalogs
 - `.env.generated`
@@ -198,23 +209,25 @@ type CustomMaterial = Phx['AdminModel']['CustomMaterial']
 
 ### Agent Guidance
 
-Coding agents (Claude Code, Codex, Cursor) read `AGENTS.md` and the Phoenix agent skills. `AGENTS.md` is written once with the build commands, the do-not-edit list and a pointer to the skills; after that it is yours. The `phoenix`, `phoenix-cli`, `phoenix-feedback` and `phoenix-review` skills carry the SDK conventions, CLI tooling and review checklist, and the `phoenix-create-configurator` skill walks the agent from your product documents and assets to a reviewed configurator in five stages. The `phoenix-variants` skill has the agent show you several options over the dev preview when a decision is a matter of taste, and build the one you pick. Phoenix keeps them in step with the installed SDK, including the reference files inside a skill folder. During the internal beta, a project created from a canary build of the SDK gets one more section in the `phoenix` skill: once per conversation the agent checks for a newer canary and, after telling you, updates the project's SDK and runs `phoenix sync`. Other skill folders are never touched.
+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 and runs `phoenix sync`. Other skill folders are never touched.
 
 Projects created by earlier SDK versions had this guidance in `CLAUDE.md`, `.cursor/rules/phoenix.mdc` and `commands/review.md`. Sync removes the SDK block from the first two, keeps your own text around it, deletes a file that held nothing else, and deletes the review commands; use the `phoenix-review` skill instead of `/review`.
 
 ### Markers for Partial Auto-Generation
 
-`.gitignore` preserves custom entries between markers:
+`.gitignore` holds the Phoenix entries between two marker lines. Sync rewrites that block and keeps everything outside it:
 
 ```gitignore
-# phoenix-start
+# ===== BEGIN PHOENIX AUTO-GENERATED =====
 # ... Phoenix-managed ignores ...
-# phoenix-end
+# ===== END PHOENIX AUTO-GENERATED =====
 
-# Your custom ignores below (preserved)
+# Your custom ignores (preserved)
 my-custom-folder/
 ```
 
+With the application-spec pipeline (see [Current and legacy project tooling](?path=/docs/phoenix-phoenix-cli--docs#current-and-legacy-project-tooling)), sync writes `.gitignore` 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 it neither creates the file nor changes one that is already there. Run `git init` before the first sync, or sync again after it, to get the file. The legacy pipeline writes the file in every project.
+
 ### Safe to Edit
 
 - `src/` (except compiled `src/locales/**/*.ts` files)

package/dist/docs/phoenix/quickstart.mdx

@@ -104,10 +104,10 @@ pnpm install
 pnpm phoenix sync
 ```
 
-`phoenix sync` keeps `spec/` and `src/` as your authored inputs and generates the application shell, scripts, types, and `.phoenix/` implementation. Start the generated development script without a server:
+`phoenix sync` keeps `spec/` and `src/` as your authored inputs and generates the application shell, types, and `.phoenix/` implementation. Start development without a server:
 
 ```sh
-pnpm dev:local
+pnpm phoenix dev --persistence local-storage
 ```
 
 Open the URL printed by the command. The application shell loads with the default `<salsita-configurator>` element and an empty 3D scene.

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

@@ -22,7 +22,7 @@ pnpm install
 pnpm phoenix sync
 ```
 
-`phoenix init [folder]` writes the starter project: `package.json`, `pnpm-workspace.yaml` and the starter spec, `spec/application.yaml` and `spec/configurator.yaml`, which describe one box you can resize and recolour. The starter depends on the same SDK version as the CLI that created it. `phoenix sync` then adds the rest of the project: package scripts, webhooks, README and lint config.
+`phoenix init [folder]` writes the starter project: `package.json`, `pnpm-workspace.yaml` and the starter spec, `spec/application.yaml` and `spec/configurator.yaml`, which describe one box you can resize and recolour. The starter depends on the same SDK version as the CLI that created it, and its `package.json` has the `dev`, `build`, `deploy`, `check` and `fix` scripts, which are yours to change. `phoenix sync` then adds the rest of the project: webhooks and lint config. It writes a `.gitignore` only when the folder is inside a git repository; run `git init` before the first sync, or sync again after it, to get the file.
 
 `init` only writes these files: it asks nothing and contacts no server. It refuses a folder that already has a `spec/` folder. A `package.json` already in the folder is kept, as long as it depends on the SDK.
 
@@ -44,12 +44,12 @@ The CLI stores the token in `~/.phoenix/credentials.json`, readable only by you,
 
 `login`, `logout` and `deploy` follow the region, not the `SERVER_URL` in the project's `.env`. `dev` follows the region too when `.env` has no `SERVER_URL`:
 
-| 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 (`login`)            |
-| `--open`              | `true`                               | Open the approval page in your browser (`login`) |
+| 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 (`login`)            |
+| `--open`               | `true`                               | Open the approval page in your browser (`login`) |
 
 ## 3. Develop
 
@@ -61,7 +61,7 @@ Signed in, `phoenix dev` needs no `.env` and nothing set up in Studio. When it s
 
 Every user who signs the CLI in gets their own development environment, so a teammate (a super admin of the workspace, like you) who clones the project and signs in doesn't overwrite your schema or take over your webhooks. The development environment is separate from `production`: nothing you do in `phoenix dev` changes the live configurator.
 
-`pnpm dev:local` still runs the project without any server, with state kept in the browser.
+`pnpm phoenix dev --persistence local-storage` still runs the project without any server, with state kept in the browser.
 
 Coding agents follow the generated `phoenix` skill: before their first change they start `phoenix dev` and open the preview in your browser, and after `phoenix deploy` starts a build they open its page in Studio.