@salsita-ai/sdk 0.50.0-develop.8f6deac646 → 0.50.0-develop.9267bdc12e

package/dist/docs/other-features/side-effects.mdx

@@ -32,17 +32,14 @@ finishNotAvailable:
 ```
 
 ```ts
-const violationExpressions = invariantBuilder
-  .withInvariants(
-    implementCustomInvariants({
-      Plate: {
-        finishNotAvailable: s => {
-          return availableMaterials.some(state => state.material === s.material && state.finish === s.finish)
-        },
-      },
-    })
-  )
-  .buildViolationExpressions()
+// src/invariants/invariants.ts
+export default phx.domain.implementCustomInvariants({
+  Plate: {
+    finishNotAvailable: s => {
+      return availableMaterials.some(state => state.material === s.material && state.finish === s.finish)
+    },
+  },
+})
 ```
 
 With following control structure. The top input selects the material, the bottom one selects the finish.

package/dist/docs/other-features/violation-messages.mdx

@@ -153,10 +153,10 @@ The `formatControlViolationMessage` function is where the magic happens. It rece
 3. **Actionable guidance**: Tell users exactly what values are valid or how to fix the problem
 4. **Consistent terminology**: Use the same terms and units throughout your application
 
-Implement violations with custom message formatting in your domain TypeScript file:
+Implement violations with custom message formatting in a file of `src/invariants/`:
 
 ```typescript
-// domain/index.ts
+// src/invariants/invariants.ts
 
 // Pre-define translatable labels for nested localization
 const colorLabels = {
@@ -166,60 +166,56 @@ const colorLabels = {
   yellow: msg`yellow`,
 } as const
 
-const violationExpressions = invariantBuilder
-  .withInvariants(
-    implementCustomInvariants({
-      Scene: {
-        itIsNotZero: s => {
-          if (s.x !== 0) {
-            return [
-              {
-                type: 'itIsNotZero',
-                severity: 'fatal',
-                message: 'Scene is not zero',
-                controlViolationPriority: 1,
-                formatControlViolationMessage: () => {
-                  return msg({
-                    message: `Scene is not zero: The position would be ${s.x} which is not equal to 0`,
-                  })
-                },
-              },
-            ]
-          }
-          return []
-        },
-        // ... tooMuchRight omitted for brevity ...
-
-        // Static violation: severity, message and controlViolationPriority
-        // are declared in YAML. Implementation only returns a boolean.
-        wayTooFarRight: s => s.x < 200,
-
-        colorPositionIncompatible: s => {
-          const compatibleColors = ['red', 'blue', 'green'] as const
-          if (s.x >= 200 && !compatibleColors.includes(s.color)) {
-            return [
-              {
-                type: 'colorPositionIncompatible',
-                severity: 'fatal',
-                message: 'Color is not compatible with far right position',
-                controlViolationPriority: 3,
-                formatControlViolationMessage: (_emission, { i18n }) => {
-                  const labels = new Intl.ListFormat(i18n.locale, {
-                    style: 'long',
-                    type: 'disjunction',
-                  }).format(compatibleColors.map(c => i18n.t(colorLabels[c])))
-
-                  return msg({ message: `Far right position is only available for ${labels}` })
-                },
-              },
-            ]
-          }
-          return []
-        },
-      },
-    })
-  )
-  .buildViolationExpressions()
+export default phx.domain.implementCustomInvariants({
+  Buckyball: {
+    itIsNotZero: s => {
+      if (s.x !== 0) {
+        return [
+          {
+            type: 'itIsNotZero',
+            severity: 'fatal',
+            message: 'Scene is not zero',
+            controlViolationPriority: 1,
+            formatControlViolationMessage: () => {
+              return msg({
+                message: `Scene is not zero: The position would be ${s.x} which is not equal to 0`,
+              })
+            },
+          },
+        ]
+      }
+      return []
+    },
+    // ... tooMuchRight omitted for brevity ...
+
+    // Static violation: severity, message and controlViolationPriority
+    // are declared in YAML. Implementation only returns a boolean.
+    wayTooFarRight: s => s.x < 200,
+
+    colorPositionIncompatible: s => {
+      const compatibleColors = ['red', 'blue', 'green'] as const
+      if (s.x >= 200 && !compatibleColors.includes(s.color)) {
+        return [
+          {
+            type: 'colorPositionIncompatible',
+            severity: 'fatal',
+            message: 'Color is not compatible with far right position',
+            controlViolationPriority: 3,
+            formatControlViolationMessage: (_emission, { i18n }) => {
+              const labels = new Intl.ListFormat(i18n.locale, {
+                style: 'long',
+                type: 'disjunction',
+              }).format(compatibleColors.map(c => i18n.t(colorLabels[c])))
+
+              return msg({ message: `Far right position is only available for ${labels}` })
+            },
+          },
+        ]
+      }
+      return []
+    },
+  },
+})
 ```
 
 ### Internationalization with Dynamic Content

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

@@ -25,8 +25,9 @@ The configurator interface is generated in `.phoenix/configurator-interface.ts`:
 
 ```typescript
 // .phoenix/configurator-interface.ts (AUTO-GENERATED - DO NOT EDIT)
-import {'{'} createConfiguratorInterface {'}'} from '@salsita-ai/sdk/configurator'
-import {'{'} configuratorBuilder {'}'} from './domain.js'
+import { createConfiguratorInterface } from '@salsita-ai/sdk/configurator'
+
+import { configuratorBuilder } from './domain.js'
 
 export const configuratorInterface = createConfiguratorInterface(configuratorBuilder)
 
@@ -64,9 +65,9 @@ type CustomMaterial = Phx['AdminModel']['CustomMaterial']
 Access the configurator interface via `phx.frontend`:
 
 ```typescript
-export const CustomComponent = () => {'{'}
+export const CustomComponent = () => {
   // Access domain systems
-  const {'{'} navigationSystem, storeSystem {'}'} = phx.frontend.useDomain()
+  const { navigationSystem, storeSystem } = phx.frontend.useDomain()
 
   // Entity state hooks
   const rootEntity = phx.frontend.useRootEntityState()
@@ -76,11 +77,11 @@ export const CustomComponent = () => {'{'}
   const selectEntity = phx.frontend.useSelectEntity()
 
   // Type-safe entity access
-  if (selectedEntity && Cabinet.is(selectedEntity)) {'{'}
+  if (selectedEntity && Cabinet.is(selectedEntity)) {
     // selectedEntity is now typed as $Cabinet
     console.log(selectedEntity.width, selectedEntity.$area)
-  {'}'}
-{'}'}
+  }
+}
 ```
 
 ## Core Hooks
@@ -90,16 +91,16 @@ The configurator interface provides 100+ hooks organized by category. Use TypeSc
 ### Domain & Application Context
 
 ```typescript
-const ExampleComponent = () => {'{'}
+const ExampleComponent = () => {
   // Core domain systems
-  const {'{'} navigationSystem, storeSystem, entitySystem {'}'} = phx.frontend.useDomain()
+  const { navigationSystem, storeSystem, entitySystem } = phx.frontend.useDomain()
 
   // Domain application context
-  const {'{'} configurationPersistSystem {'}'} = phx.frontend.useDomainApplication()
+  const { configurationPersistSystem } = phx.frontend.useDomainApplication()
 
   // Full configurator context
-  const {'{'} imageRenderingSystem {'}'} = phx.frontend.useConfigurator()
-{'}'}
+  const { imageRenderingSystem } = phx.frontend.useConfigurator()
+}
 ```
 
 ### State Subscriptions
@@ -160,6 +161,10 @@ const toolState = phx.frontend.useActiveToolState()
 const navigate = phx.frontend.useNavigate()
 const pushNavigate = phx.frontend.usePushNavigate()
 const popNavigate = phx.frontend.usePopNavigate()
+
+// Fullscreen: a flag in the configurator's state that the layout honours; it does not put the browser into fullscreen
+const isFullscreen = phx.frontend.useIsFullscreenActive()
+const setFullscreen = phx.frontend.useSetFullscreen() // setFullscreen(true) or setFullscreen(false)
 ```
 
 ### Controls
@@ -209,7 +214,7 @@ const validity = phx.frontend.useStateValidity()
 const controlViolations = phx.frontend.useControlViolations(entityId, controlId)
 
 // Finalize violations
-const {'{'} disabled, hints {'}'} = phx.frontend.useFinalizeViolations()
+const { disabled, hints } = phx.frontend.useFinalizeViolations()
 
 // Map violations to hints
 const mapViolationHints = phx.frontend.useMapViolationHints()
@@ -284,89 +289,89 @@ The interface provides factory functions for creating handlers and providers:
 
 ```typescript
 // Runs early in app startup, before session auth
-const OnApplicationStart = phx.frontend.createOnApplicationStartProvider(({'{'} children {'}'}) => {'{'}
-  return <YourProvider>{'{'}children{'}'}</YourProvider>
-{'}'})
+const OnApplicationStart = phx.frontend.createOnApplicationStartProvider(({ children }) => {
+  return <YourProvider>{children}</YourProvider>
+})
 
 // Runs after session auth, before domain data loading
-const OnSessionReady = phx.frontend.createOnSessionReadyProvider(({'{'} children {'}'}) => {'{'}
-  return <YourProvider>{'{'}children{'}'}</YourProvider>
-{'}'})
+const OnSessionReady = phx.frontend.createOnSessionReadyProvider(({ children }) => {
+  return <YourProvider>{children}</YourProvider>
+})
 
 // Runs after published data is parsed, before frontend/backend loading
-const OnPublishedDataReady = phx.frontend.createOnPublishedDataReadyProvider(({'{'} children {'}'}) => {'{'}
-  return <YourProvider>{'{'}children{'}'}</YourProvider>
-{'}'})
+const OnPublishedDataReady = phx.frontend.createOnPublishedDataReadyProvider(({ children }) => {
+  return <YourProvider>{children}</YourProvider>
+})
 
 // Runs after frontend collection and parsing, before backend loading
-const OnFrontendDataReady = phx.frontend.createOnFrontendDataReadyProvider(({'{'} children {'}'}) => {'{'}
-  return <YourProvider>{'{'}children{'}'}</YourProvider>
-{'}'})
+const OnFrontendDataReady = phx.frontend.createOnFrontendDataReadyProvider(({ children }) => {
+  return <YourProvider>{children}</YourProvider>
+})
 
 // Runs after backend loading, before preset selection and configurator initialization
-const OnBackendDataReady = phx.frontend.createOnBackendDataReadyProvider(({'{'} children {'}'}) => {'{'}
-  return <YourProvider>{'{'}children{'}'}</YourProvider>
-{'}'})
+const OnBackendDataReady = phx.frontend.createOnBackendDataReadyProvider(({ children }) => {
+  return <YourProvider>{children}</YourProvider>
+})
 
 // Runs after routing and preset selection are ready
-const OnRoutingReady = phx.frontend.createOnRoutingReadyProvider(({'{'} children {'}'}) => {'{'}
-  return <YourProvider>{'{'}children{'}'}</YourProvider>
-{'}'})
+const OnRoutingReady = phx.frontend.createOnRoutingReadyProvider(({ children }) => {
+  return <YourProvider>{children}</YourProvider>
+})
 
 // Wraps OwnerUi and ReadUi pages
-const OnConfiguratorReady = phx.frontend.createOnConfiguratorReadyProvider(({'{'} children {'}'}) => {'{'}
-  return <YourProvider>{'{'}children{'}'}</YourProvider>
-{'}'})
+const OnConfiguratorReady = phx.frontend.createOnConfiguratorReadyProvider(({ children }) => {
+  return <YourProvider>{children}</YourProvider>
+})
 ```
 
 ### Data Handlers
 
 ```typescript
 // Collect frontend data during initialization
-const collectFrontendData = phx.frontend.createCollectFrontendDataHandler(async (context) => {'{'}
-  return {'{'} customData: await fetchCustomData() {'}'}
-{'}'})
+const collectFrontendData = phx.frontend.createCollectFrontendDataHandler(async context => {
+  return { customData: await fetchCustomData() }
+})
 
 // Override which published chunks are fetched by the frontend.
 // See Publishing page for full documentation.
-const filterPublishedChunks = phx.frontend.createFilterPublishedChunksHandler(() => {'{'}
+const filterPublishedChunks = phx.frontend.createFilterPublishedChunksHandler(() => {
   const session = phx.frontend.useSession()
 
-  return useMemo(() => {'{'}
+  return useMemo(() => {
     if (session.sessionPayload?.role === 'admin') return ['styling', 'catalog-na']
     return ['styling']
-  {'}'}, [session.sessionPayload?.role])
-{'}'})
+  }, [session.sessionPayload?.role])
+})
 
 // Runs after preset data is loaded
-const onPresetLoaded = phx.frontend.createOnPresetLoadedHandler((entities, presetData) => {'{'}
+const onPresetLoaded = phx.frontend.createOnPresetLoadedHandler((entities, presetData) => {
   // Can modify preset entities before rendering
   return entities
-{'}'})
+})
 
 // Intercept navigation to index/presets page
-const onGoToIndex = phx.frontend.createOnGoToIndexHandler(() => {'{'}
+const onGoToIndex = phx.frontend.createOnGoToIndexHandler(() => {
   // Custom logic before navigating
-{'}'})
+})
 ```
 
 ### UI Components
 
 ```typescript
 // Custom Phoenix layout element
-const MyLayoutElement = phx.frontend.createCustomPhoenixLayoutElement(() => {'{'}
+const MyLayoutElement = phx.frontend.createCustomPhoenixLayoutElement('MyLayoutElement', () => {
   return <div>Custom Layout</div>
-{'}'})
+})
 
 // Custom Phoenix entity element
-const MyEntityElement = phx.frontend.createCustomPhoenixEntityElement(() => {'{'}
+const MyEntityElement = phx.frontend.createCustomPhoenixEntityElement('MyEntityElement', () => {
   return <mesh>...</mesh>
-{'}'})
+})
 
 // Custom page when auth fails
-const NotAuthenticatedPage = phx.frontend.createNotAuthenticatedPage(() => {'{'}
+const NotAuthenticatedPage = phx.frontend.createNotAuthenticatedPage(() => {
   return <div>Please log in</div>
-{'}'})
+})
 ```
 
 ### Preset UI
@@ -383,21 +388,56 @@ const PresetAction = phx.frontend.createPresetPageAction(PresetHelpAction)
 const PresetOverlay = phx.frontend.createPresetDeviceNotSupported(SmallScreenNotice)
 ```
 
+### Loaded Configuration UI
+
+A layout element registered under the name `ConfiguratorLayout` replaces the whole UI of a loaded configuration, in owner and in read mode, whatever `layout` the spec sets. Without it, Phoenix renders the layout the spec selects. [Custom Layout](?path=/docs/layouts-custom-layout--docs) is a worked example: a fully custom product page with its panel on the left, built from the scene, the safe-area hook and state hooks.
+
+```typescript
+// src/elements/ConfiguratorLayout.tsx
+import { LayoutSlots, useSceneSafeArea } from '@salsita-ai/sdk/configurator'
+
+const SIDEBAR_WIDTH = 320
+
+export default phx.frontend.createCustomPhoenixLayoutElement('ConfiguratorLayout', () => {
+  const { containerRef, safeAreaRef } = useSceneSafeArea()
+
+  return (
+    <div ref={containerRef} style={{ position: 'absolute', inset: 0 }}>
+      <LayoutSlots.Services />
+      <LayoutSlots.SharedCanvas />
+      <aside style={{ position: 'absolute', insetBlock: 0, insetInlineStart: 0, inlineSize: SIDEBAR_WIDTH }}>
+        Project sidebar
+      </aside>
+      <div
+        ref={safeAreaRef}
+        style={{ position: 'absolute', insetBlock: 0, insetInlineStart: SIDEBAR_WIDTH, insetInlineEnd: 0, pointerEvents: 'none' }}
+      />
+    </div>
+  )
+})
+```
+
+- `LayoutSlots.SharedCanvas` renders the scene. It is absolutely positioned and fills its nearest positioned ancestor, so the layout's root is positioned and covers the page. The layout positions its own UI above the canvas and after it in the markup, as the `aside` does; unpositioned content is painted under the canvas.
+- `useSceneSafeArea()`, called without arguments, tells the camera which part of the canvas the UI leaves free. Attach `containerRef` to the element that covers the whole canvas and `safeAreaRef` to the region the scene should stay visible in: the hook measures the gap between the two and the camera frames the scene inside the safe area. Without it the scene is framed in the whole canvas. The safe-area element lies over the canvas, so it sets `pointerEvents: 'none'` to leave orbiting and clicking to the scene. A `canvasPadding` component in the spec scales the measured gaps, see [Canvas Padding](?path=/docs/layouts-canvas-padding--docs).
+- The layout has to mount `LayoutSlots.SharedCanvas`, or the project sets `appLoader: legacy`. Otherwise the app loader stays on screen.
+- The layout composes the rest from what `@salsita-ai/sdk/configurator` exports: `LayoutSlots.Services` and the other members of `LayoutSlots`.
+- Nothing of the built-in layouts is rendered for it. `Legacy.CommonFinalizePage` shows the page of the `finalizePage` component in a dialog while one of its finalize navigation states is active, so a layout that shows a finalize button mounts it; without it the button changes the navigation state and nothing appears. It is marked deprecated and is the only exported piece that does this. `LayoutDialog` renders only what the project registers with `createLayoutDialog` and is not part of the finalize flow. The preview start screen is `DesktopPreview` or `MobilePreview`, which the layout shows while `usePreview().isPreview` is set. Both previews frame the scene themselves, so the layout renders the component that calls `useSceneSafeArea()` only while `isPreview` is not set; it then measures when it mounts after the preview. The assistant panel is not available to a project layout.
+- The layout reads the state it has to react to from hooks. Read mode: `phx.frontend.useAccessService().accessInfo.viewMode`. Fullscreen: `phx.frontend.useIsFullscreenActive()` reads it and `phx.frontend.useSetFullscreen()` sets it; the layout decides what to hide. Preview: `usePreview()` from `@salsita-ai/sdk/configurator`.
+- Any project layout element named `ConfiguratorLayout` takes over the page.
+
 ## TransformerBuilder
 
 Use `transformerBuilder` to create entity transformers:
 
 ```typescript
 // Create a transformer that runs when specific conditions are met
-const cabinetTransformer = phx.frontend.transformerBuilder
-  .when(Cabinet.is)
-  .do((cabinet, context) => {'{'}
-    // Transform cabinet data
-    return {'{'}
-      ...cabinet,
-      $computedField: calculateSomething(cabinet)
-    {'}'}
-  {'}'})
+const cabinetTransformer = phx.frontend.transformerBuilder.when(Cabinet.is).do((cabinet, context) => {
+  // Transform cabinet data
+  return {
+    ...cabinet,
+    $computedField: calculateSomething(cabinet),
+  }
+})
 ```
 
 **Note**: The deprecated `createTransformer` function should not be used for new implementations.
@@ -407,19 +447,19 @@ const cabinetTransformer = phx.frontend.transformerBuilder
 The `updates` factory creates type-safe entity updates:
 
 ```typescript
-const {'{'} storeSystem {'}'} = phx.frontend.useDomain()
+const { storeSystem } = phx.frontend.useDomain()
 
 // Create new entity
-const createUpdates = phx.frontend.updates.create({'{'}
+const createUpdates = phx.frontend.updates.create({
   type: 'Cabinet',
   width: 800,
   height: 2000,
-{'}'})
+})
 
 // Modify existing entity
-const modifyUpdates = phx.frontend.updates.modify(cabinetId, {'{'}
+const modifyUpdates = phx.frontend.updates.modify(cabinetId, {
   width: 1000,
-{'}'})
+})
 
 // Delete entity
 const deleteUpdates = phx.frontend.updates.delete(cabinetId)

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

@@ -565,9 +565,13 @@ A relation pair can have at most one composition owner. For an ownership relatio
 Relations are validated when the application spec is parsed:
 
 - **Every relation must be declared from both sides.** A relation on `A` targeting `B` needs a counterpart declared on `B` (or on an alias containing `B`) pointing back at `A` — with the opposite kind (`direct` ↔ `indirect`, `allOfType` ↔ `allOfType`) and the same `field`. A missing or mismatched counterpart fails parsing with `RELATION_MISSING_COUNTERPART`. Self‑referencing relations (target is the declaring type) act as their own counterpart and are exempt.
+- **The field of a relation must hold references to the entities the relation relates to.** A `direct` relation reads a field of the entity it is declared on, and the field must reference exactly the entity types of the target. An `indirect` relation reads a field of the target, and the field must reference exactly the entity types the relation is declared on. A field that is not a `DomainEntityId` with `references` fails parsing with `RELATION_FIELD_NOT_REFERENCE`, and one that references other entity types with `RELATION_FIELD_REFERENCES_OTHER_TYPES`.
+- **The field of a `direct` relation must hold its references the way the cardinality needs.** `1-1` needs one reference that is never `null`, `0-1` one reference or `null`, and `0-N` or `1-N` an array of references. Anything else fails parsing with `RELATION_FIELD_CARDINALITY_MISMATCH`. An `indirect` relation takes any of the three, because its cardinality counts the entities that point back.
 - **At most one side may carry `composedOf: true`.** A pair may have one owner or no owner. Two owning sides fail parsing with `RELATION_COUNTERPART_COMPOSED_OF_MISMATCH` because the pair would define ownership in both directions.
 - **Every entity type must be reachable from the root** through `composedOf` edges, otherwise parsing fails with `RELATION_ENTITY_NOT_IN_COMPOSITION_TREE`.
 
+**What the field checks leave out.** A field whose schema states its type as text (`tsType`) or combines schemas with `allOf` is not checked, because the parser cannot tell what it holds. With a wrong field of that kind a `direct` relation fails when it is read, and an `indirect` relation finds no related entities and fails only if its cardinality requires one. When an alias holds the field, the relation is accepted if the field fits in at least one entity type of the alias.
+
 **Why both sides?** The two declarations feed two different runtime systems. The `direct` side owns the id field and generates the reference bookkeeping: dangling ids are pruned when the referenced entity is deleted, and ids are written on create and replace. The `composedOf: true` side generates the composition edge: cascade deletes, the scene hierarchy, and the reachability check. Because these can be different entities — a parent may collect children by reverse lookup (`indirect` + `composedOf: true`) while each child stores the id — dropping either declaration silently disables one of the systems: without the parent side, deleting the parent leaves its children orphaned; without the child side, deleted entities leave dangling ids behind. The missing side also cannot be generated automatically, because the stored id field is compatible with many different relations: the reverse accessor's name is public API, and its cardinality (`0-N`, `1-N`, or a `0-1` slot) changes the generated types, state validation, and UI affordances without changing the stored data at all. Requiring both declarations turns these mistakes into parse errors instead of runtime surprises, and the redundancy lets the parser cross‑check the pair — a typo in `field` or a doubled owner is caught immediately.
 
 ### Picking a relation kind

package/dist/docs/phoenix/getting-started.mdx

@@ -86,7 +86,7 @@ For inspiration and real-world implementation patterns, examine deployed Salsita
 
 When you encounter challenges or need to implement specific features, use these resources in order:
 
-**AI-Powered Assistance**: Every Phoenix project ships `AGENTS.md` and Phoenix agent skills, so coding agents in your project already know the SDK conventions and CLI. Start by using AI coding assistants in the `configurator-phoenix` project. While they may not solve complex problems directly, they can point you toward relevant examples or search terms that will help you find the right solution.
+**AI-Powered Assistance**: Every Phoenix project ships Phoenix agent skills, so coding agents in your project already know the SDK conventions and CLI. Start by using AI coding assistants in the `configurator-phoenix` project. While they may not solve complex problems directly, they can point you toward relevant examples or search terms that will help you find the right solution.
 
 **Storybook Documentation**: Search the Phoenix Storybook for functionality similar to what you need. When you find relevant examples, examine the corresponding code in the configurator-phoenix stories to understand the implementation details.
 

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
 
@@ -399,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 |

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

@@ -178,25 +178,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`
@@ -204,23 +208,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)