@salsita-ai/sdk 0.49.0-develop.cbee856178 → 0.49.0-develop.f5fc5cfc25

package/dist/docs/3d-scene/cameras/locks.mdx

@@ -0,0 +1,439 @@
+# Camera - Locks
+
+Keep a user's chosen viewing angle or magnification while the configurator moves between related product views. Camera locks place cameras into named groups: give two cameras the same explicit group and the destination camera retains that part of the live view when it activates.
+
+- [Apply camera locks](#apply-camera-locks)
+- [Choose what to preserve](#choose-what-to-preserve)
+- [Understand transition behavior](#understand-transition-behavior)
+- [Try the example](#try-the-example)
+- [Example](#example)
+- [Complete Implementation](#complete-implementation)
+
+## Apply camera locks
+
+Assign the same literal group name to the outgoing and incoming cameras that should share a live view. For perspective cameras, `distanceLockGroup` preserves dolly distance and `rotationLockGroup` preserves the live azimuth and polar angles:
+
+```yaml
+components:
+  Scene:
+    fitRootPerspectiveCamera:
+      overview:
+        distanceLockGroup: product-view
+        rotationLockGroup: product-view
+  Product:
+    fitEntityPerspectiveCamera:
+      detail:
+        distanceLockGroup: product-view
+        rotationLockGroup: product-view
+```
+
+When the Product camera activates after the Scene camera, it still calculates its normal target from Product, but it uses the user's current distance and rotation. The same applies in the other direction. Group names have no predefined meaning; choose stable names that describe the related camera views in your configurator.
+
+Orthographic cameras use `zoomLockGroup` instead of `distanceLockGroup`:
+
+```yaml
+components:
+  Scene:
+    fitRootOrthographicCamera:
+      overview:
+        zoomLockGroup: product-view
+        rotationLockGroup: product-view
+  Product:
+    fitEntityOrthographicCamera:
+      detail:
+        zoomLockGroup: product-view
+        rotationLockGroup: product-view
+```
+
+Add the group property to every camera that participates. Group names match exactly and case-sensitively, including whitespace. A missing group, `null`, or a different string means that aspect follows the destination camera normally; two missing or `null` groups never create a lock.
+
+## Choose what to preserve
+
+Distance or zoom and rotation are independent. Configure only the behavior the product flow needs:
+
+- Set only `rotationLockGroup` to retain the viewing angle while the destination camera calculates its normal fit distance or zoom.
+- Set only `distanceLockGroup` on perspective cameras to retain dolly distance while applying the destination orientation.
+- Set only `zoomLockGroup` on orthographic cameras to retain zoom while applying the destination orientation.
+- Set both relevant groups to translate the retained view around the destination camera's newly calculated target.
+
+Lock groups are available on fit-root, fit-entity, fit-selection, and static cameras. A camera can belong to different groups for rotation and magnification by using different names for the two aspects.
+
+## Understand transition behavior
+
+The destination camera still owns its target, boundary behavior, and limits. Preserved distance and zoom are clamped to its configured limits. Preserved angles use the same limit resolution as a normally applied camera: finite two-sided ranges clamp during the transition, while a one-sided azimuth limit is placed on its allowed side within one revolution of the preserved angle, so the angle stays where it is and the limit is reached by orbiting toward it. This can intentionally crop a newly fitted target: a lock preserves the user's view rather than guaranteeing that all destination content remains visible.
+
+A matching group also applies when the active camera refits itself after mesh, bounds, or canvas-padding changes. This is useful with `fitMeshChanges`: geometry can change the target or fit while the chosen live aspects remain stable. A refit only preserves an aspect whose live value is a settled or user-chosen view: when it interrupts an unfinished transition that was still animating that aspect toward its destination, such as the first load, a Reset, or a switch from a camera with different groups, the refit completes the destination view instead of freezing the animation midway.
+
+Locks apply only between cameras of the same projection type. Switching between perspective and orthographic cameras uses the destination view normally, even when their group names match. Projection parameters such as perspective `fov` and orthographic `frustumSize` are not preserved; keep them consistent when a visual projection snap would be distracting.
+
+Reset Camera bypasses all locks for that action and restores the active camera's configured view. The next automatic transition uses locks normally again. Export rendering remains independent from the interactive camera's lock history.
+
+## Try the example
+
+The example uses dynamic expressions and sidebar switches only to make each lock easy to turn on and off while experimenting. A normal integration should use stable literal group names as shown above. Object B and the full-scene camera share a group, while Object A uses a different group:
+
+- Object A: a fit-selection camera with the `object-a` group.
+- Object B: a fit-entity camera activated by `$filter.selectedEntityIds`, with the `object-b-and-root` group.
+- Nothing selected: a fit-root camera with the `object-b-and-root` group.
+
+1. Leave both lock switches on, click Object B to select it, then orbit and zoom or dolly to an obvious view.
+2. Click the empty canvas to clear the selection. The target changes to the whole scene, but the live rotation and magnification stay because B and the root share both groups.
+3. Turn off one lock and repeat B → Nothing selected. The enabled aspect stays; the disabled aspect follows the destination camera.
+4. Click Object A to select it. Its groups are different, so the configured A view is applied normally.
+5. While B or Nothing selected is active, toggle **Show B extra part**. `fitMeshChanges` refits the same camera from mesh-derived bounds. An unlocked distance or zoom fits the larger shape while a locked rotation stays unchanged.
+6. With both locks enabled, switch Perspective ↔ Orthographic. Projection changes never preserve the live view.
+7. Change the live view and press the camera button in the toolbar. Reset Camera bypasses the locks once and restores the active camera's configured fit and angles.
+8. In the perspective view with nothing selected, dolly fully out to the root camera's `maxDistance` of 9000, then click Object B. The preserved distance is clamped to B's `maxDistance` of 6500, so the camera moves closer while the rotation stays. In the orthographic view, zoom fully in on Object B and clear the selection: B's `maxZoom` of 3.5 is clamped to the root camera's 3.
+
+For the camera activation rules used here, see [Fit Selection](?path=/docs/3d-scene-cameras-fit-selection--docs), [Fit Entity](?path=/docs/3d-scene-cameras-fit-entity--docs), [Fit Root](?path=/docs/3d-scene-cameras-fit-root--docs), and [Camera Transitions](?path=/docs/3d-scene-cameras-transitions--docs).
+
+## Example
+
+Use the sidebar to toggle each lock independently and change B's fitted mesh, the control over the canvas to switch projection, and the camera toolbar button to reset.
+
+## Complete Implementation
+
+{/* AUTO-GENERATED SECTION: This section is automatically updated by 'phoenix story build' */}
+
+<details>
+<summary>Click to view the complete implementation files</summary>
+
+### ./spec/domain.yaml
+
+```yaml
+model:
+  latest:
+    entityTypes:
+      - Scene
+      - ObjectA
+      - ObjectB
+    aliases:
+      RootEntity:
+        - Scene
+    shapes:
+      Scene:
+        lockRotation:
+          type: boolean
+        lockZoomOrDistance:
+          type: boolean
+        showBExtraPart:
+          type: boolean
+
+relations:
+  Scene:
+    $objectA:
+      kind: allOfType
+      target: ObjectA
+      cardinality: 1-1
+      composedOf: true
+    $objectB:
+      kind: allOfType
+      target: ObjectB
+      cardinality: 1-1
+      composedOf: true
+  ObjectA:
+    $scene:
+      kind: allOfType
+      target: Scene
+      cardinality: 1-1
+      composedOf: false
+  ObjectB:
+    $scene:
+      kind: allOfType
+      target: Scene
+      cardinality: 1-1
+      composedOf: false
+
+presets:
+  - name: Camera locks
+    description: Compare independent rotation and zoom or distance locks while changing camera targets.
+    rootEntityType: Scene
+    initialDomainEntities:
+      - id: Scene-1
+        type: Scene
+        lockRotation: true
+        lockZoomOrDistance: true
+        showBExtraPart: false
+      - id: ObjectA-1
+        type: ObjectA
+      - id: ObjectB-1
+        type: ObjectB
+
+viewStates:
+  - perspective
+  - orthographic
+
+# This example resolves lock groups from boolean attributes only so readers can
+# compare locked and unlocked behavior interactively. In an application, assign
+# stable literal lock groups directly to the related camera configurations.
+components:
+  Scene:
+    applicationConfig:
+      main:
+        layout: universal
+        ignoreSelectionInSidebar: true
+        miniSidebar: true
+        splitSidebar: true
+        distanceDataUnit: mm
+    toolbar:
+      main:
+        desktop:
+          - kind: toolbarButtonGroup
+            children:
+              - kind: resetCameraToolbarButton
+                props:
+                  icon: CameraRotate
+        mobile:
+          - kind: toolbarButtonGroup
+            children:
+              - kind: resetCameraToolbarButton
+    viewControls:
+      projection:
+        items:
+          - label: Perspective
+            value: perspective
+            icon: Eye
+          - label: Orthographic
+            value: orthographic
+            icon: Square
+    fitRootPerspectiveCamera:
+      nothingSelected:
+        near: 10
+        far: 20000
+        fov: 42
+        azimuthAngle: 0.55
+        polarAngle: 1.05
+        minDistance: 1200
+        maxDistance: 9000
+        distanceLockGroup:
+          $read: $distanceLockGroup
+        rotationLockGroup:
+          $read: $rotationLockGroup
+        fitMeshChanges: true
+        $filter:
+          viewStates: [perspective]
+    fitRootOrthographicCamera:
+      nothingSelected:
+        near: 10
+        far: 20000
+        frustumSize: 5000
+        distance: 6000
+        azimuthAngle: 0.55
+        polarAngle: 1.05
+        minZoom: 0.4
+        maxZoom: 3
+        zoomLockGroup:
+          $read: $distanceLockGroup
+        rotationLockGroup:
+          $read: $rotationLockGroup
+        fitMeshChanges: true
+        $filter:
+          viewStates: [orthographic]
+    attributeSwitch:
+      lockRotation:
+        value:
+          $bind: lockRotation
+      lockZoomOrDistance:
+        value:
+          $bind: lockZoomOrDistance
+      showBExtraPart:
+        value:
+          $bind: showBExtraPart
+
+  ObjectA:
+    fitSelectionPerspectiveCamera:
+      selected:
+        priority: 10
+        near: 10
+        far: 20000
+        fov: 42
+        azimuthAngle: -0.85
+        polarAngle: 1.25
+        minDistance: 700
+        maxDistance: 5000
+        distanceLockGroup:
+          $read: $distanceLockGroup
+        rotationLockGroup:
+          $read: $rotationLockGroup
+        $filter:
+          viewStates: [perspective]
+    fitSelectionOrthographicCamera:
+      selected:
+        priority: 10
+        near: 10
+        far: 20000
+        frustumSize: 5000
+        distance: 4000
+        azimuthAngle: -0.85
+        polarAngle: 1.25
+        minZoom: 0.5
+        maxZoom: 4
+        zoomLockGroup:
+          $read: $distanceLockGroup
+        rotationLockGroup:
+          $read: $rotationLockGroup
+        $filter:
+          viewStates: [orthographic]
+    sceneEntityBoxObject:
+      body:
+        width: 900
+        height: 1200
+        depth: 700
+        anchor: center
+    sceneEntityProperties:
+      main:
+        offsetX: -1600
+        offsetY: 600
+    sceneEntityLocalMaterialOverride:
+      main:
+        materialsToOverride: [BoxMaterial]
+        color: '#4f7cac'
+        roughness: 0.65
+    selectable:
+      main: {}
+
+  ObjectB:
+    fitEntityPerspectiveCamera:
+      selected:
+        priority: 10
+        near: 10
+        far: 20000
+        # Projection settings are intentionally identical to the root camera.
+        # Distance/zoom locks preserve controls state, not projection parameters;
+        # changing these would cause an immediate visual snap before the pan.
+        fov: 42
+        azimuthAngle: 1.0
+        polarAngle: 0.9
+        minDistance: 900
+        maxDistance: 6500
+        distanceLockGroup:
+          $read: $distanceLockGroup
+        rotationLockGroup:
+          $read: $rotationLockGroup
+        fitMeshChanges: true
+        $filter:
+          viewStates: [perspective]
+          selectedEntityIds:
+            $read: id
+    fitEntityOrthographicCamera:
+      selected:
+        priority: 10
+        near: 10
+        far: 20000
+        frustumSize: 5000
+        distance: 4500
+        azimuthAngle: 1.0
+        polarAngle: 0.9
+        minZoom: 0.4
+        maxZoom: 3.5
+        zoomLockGroup:
+          $read: $distanceLockGroup
+        rotationLockGroup:
+          $read: $rotationLockGroup
+        fitMeshChanges: true
+        $filter:
+          viewStates: [orthographic]
+          selectedEntityIds:
+            $read: id
+    sceneEntityBoxObject:
+      body:
+        width: 1100
+        height: 900
+        depth: 850
+        anchor: center
+      extra:
+        width: 1900
+        height: 350
+        depth: 500
+        anchor: center
+        $filter:
+          active:
+            $read: $showExtraPart
+    sceneEntityObjectProperties:
+      extra:
+        offsetX: 800
+        offsetY: 750
+        offsetZ: -250
+        $filter:
+          active:
+            $read: $showExtraPart
+    sceneEntityProperties:
+      main:
+        offsetX: 1600
+        offsetY: 450
+    sceneEntityLocalMaterialOverride:
+      main:
+        materialsToOverride: [BoxMaterial]
+        color: '#d9822b'
+        roughness: 0.65
+    selectable:
+      main: {}
+```
+
+### ./src/components/CameraLockControls.tsx
+
+```tsx
+import { propertyPageComponent } from '@salsita-ai/sdk/domain'
+import { AttributeSwitchSelector } from '@salsita-ai/sdk/react'
+import { PropertyContainer } from '@salsita-ai/sdk/ui'
+
+import { phx } from '../../.phoenix/phx.js'
+
+export default [
+  phx.domain.attachComponent
+    .withComponent(propertyPageComponent, 'main')
+    .withEntity('Scene')
+    .attach(s => ({
+      page: (
+        <PropertyContainer.Group spacing="large">
+          <PropertyContainer.Item
+            title="Try the camera locks"
+            description="Object B and the full-scene camera share lock groups, while Object A uses different groups. Orbit and zoom or dolly on Object B, then switch between camera targets to compare what is preserved. Disable either lock to make that part of the view follow the destination camera instead."
+          />
+          <AttributeSwitchSelector
+            entityId={s.id}
+            instanceName="lockRotation"
+            title="Lock rotation"
+            description="Preserve live azimuth and polar angles."
+          />
+          <AttributeSwitchSelector
+            entityId={s.id}
+            instanceName="lockZoomOrDistance"
+            title="Lock zoom / distance"
+            description="Preserve perspective distance or orthographic zoom."
+          />
+          <AttributeSwitchSelector
+            entityId={s.id}
+            instanceName="showBExtraPart"
+            title="Show B extra part"
+            description="Change B's mesh bounds to trigger a same-camera refit."
+          />
+        </PropertyContainer.Group>
+      ),
+    })),
+]
+```
+
+### ./src/expressions/camera-locks.ts
+
+```ts
+import { phx } from '../../.phoenix/phx.js'
+
+export default phx.domain.implementCustomExpressions({
+  Scene: {
+    $distanceLockGroup: s => (s.lockZoomOrDistance ? 'object-b-and-root' : null),
+    $rotationLockGroup: s => (s.lockRotation ? 'object-b-and-root' : null),
+  },
+  ObjectA: {
+    $distanceLockGroup: s => (s.$scene.lockZoomOrDistance ? 'object-a' : null),
+    $rotationLockGroup: s => (s.$scene.lockRotation ? 'object-a' : null),
+  },
+  ObjectB: {
+    $distanceLockGroup: s => (s.$scene.lockZoomOrDistance ? 'object-b-and-root' : null),
+    $rotationLockGroup: s => (s.$scene.lockRotation ? 'object-b-and-root' : null),
+    $showExtraPart: s => s.$scene.showBExtraPart,
+  },
+})
+```
+
+</details>

package/dist/docs/3d-scene/cameras/static.mdx

@@ -541,6 +541,8 @@ Choose perspective cameras for natural, immersive viewing experiences. Choose or
 
 ## Example
 
+To retain the user's live rotation, distance, or zoom when switching between static camera views that share a lock group, see the [Camera Locks example](?path=/docs/3d-scene-cameras-locks--docs).
+
 This example shows multiple static cameras combining both perspective and orthographic projections positioned to showcase the model from different specific angles. Each camera maintains its configured position while still allowing user interaction within defined limits.
 
 Try using the view controls at the top of the interface to switch between different camera perspectives. Notice how the 3D and Front views provide natural perspective viewing with depth, while the Top and Left views use true orthographic projection with `frustumSize` for technical accuracy. The orthographic views use `animateTransition: false` to provide instant, precise positioning ideal for technical examination.

package/dist/docs/3d-scene/cameras/transitions.mdx

@@ -117,6 +117,8 @@ The camera system uses memoization to maintain the same component instance when
 
 This example combines all three transition scenarios. Use the step navigation to see component instance changes, adjust the radius slider in "Bounding Box" view to see geometry-based transitions, and toggle the box visibility in "Fit Mesh" view to see mesh-change transitions.
 
+To preserve a user's live rotation, distance, or zoom across selected camera transitions, see the [Camera Locks example](?path=/docs/3d-scene-cameras-locks--docs).
+
 ## Complete Implementation
 
 {/* AUTO-GENERATED SECTION: This section is automatically updated by 'phoenix story build' */}

package/dist/docs/index.json

@@ -1,5 +1,5 @@
 {
-  "generatedAt": "2026-10-07T10:56:14.429Z",
+  "generatedAt": "2026-10-07T15:22:23.840Z",
   "categories": [
     {
       "name": "Phoenix",
@@ -1381,6 +1381,17 @@
               ],
               "source": "storybook-example"
             },
+            {
+              "title": "Locks",
+              "description": "Keep a user's chosen viewing angle or magnification while the configurator moves between related product views. Camera locks place cameras into named groups: give two cameras the same explicit group...",
+              "path": "docs/3d-scene/cameras/locks.mdx",
+              "category": [
+                "3d scene",
+                "Cameras",
+                "Locks"
+              ],
+              "source": "storybook-example"
+            },
             {
               "title": "Simple",
               "description": "This example demonstrates the default camera behavior in Phoenix configurators. When no camera components are configured, the system provides built-in camera controls with sensible defaults, giving...",

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

@@ -17,7 +17,7 @@ The Phoenix CLI (`phoenix` command) is the unified tool for all configurator dev
 `phoenix init [folder]` starts a configurator project in `[folder]` (default: the working directory):
 
 ```bash
-npx -p @salsita-ai/sdk phoenix init my-configurator
+npx -p @salsita-ai/sdk@canary phoenix init my-configurator
 cd my-configurator
 pnpm install
 pnpm phoenix sync
@@ -30,6 +30,7 @@ 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.
 
 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).
 
@@ -45,7 +46,7 @@ The starter `spec/application.yaml` starts with `project: default`. `project` na
 
 ### How `phoenix dev` authenticates
 
-- **Signed in with `phoenix login`** (SDK-builder workspaces): nothing else is needed. On start, `phoenix dev` asks the server for your development environment in the project; the server creates it on the first run. Every user gets their own development environment, so teammates don't overwrite each other's schema or webhook tunnel. The server comes from `--serverUrl`, then `SERVER_URL` in `.env`, then the region (`--region` or `PHOENIX_REGION`, default `eu`).
+- **Signed in with `phoenix login`** (SDK-builder workspaces): nothing else is needed. On start, `phoenix dev` asks the server for your development environment in the project; the server creates it on the first run. Every user gets their own development environment, so teammates don't overwrite each other's schema or webhook tunnel. The server comes from `--serverUrl`, then `SERVER_URL` in `.env`, then the region (`--region` or `PHOENIX_REGION`, default `eu`). `phoenix dev` hands that server to the preview as `SERVER_URL`, so the preview talks to the server the development deployment was prepared on even without a `.env`, and prints the preview address as `Preview: <url>` once the dev server is up (also written to `.phoenix/phoenix-dev.log`).
 - **With a Studio development environment**: create the project and a development environment in PHX Studio and paste its `.env` block (`SERVER_URL`, `PROJECT_SLUG`, `ENVIRONMENT_SLUG`, `DEVELOPMENT_KEY`) into `.env`. A `DEVELOPMENT_KEY` always takes precedence over the sign-in, and `PROJECT_SLUG` overrides the starter spec's `project: default`, which a development key cannot resolve.
 
 ## Local Development Setup
@@ -358,7 +359,7 @@ Removes all build artifacts (`.phoenix/`, `node_modules/`), reinstalls dependenc
 
 ### `phoenix sync`
 
-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.
+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.
 
 | Flag             | Env Variable    | Default | Description                    |
 | ---------------- | --------------- | ------- | ------------------------------ |
@@ -571,7 +572,7 @@ Signs the CLI in to the SDK-builder workspace `<customer>`:
 2. Studio sends a one-time code back to the CLI on `127.0.0.1`.
 3. The CLI exchanges the code for a token.
 
-The token is stored in `~/.phoenix/credentials.json`, readable only by you, per server; `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.
+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                                      |
 | --------------------- | ------------------------------------ | ------------------------------------------------ |
@@ -590,7 +591,7 @@ Revokes the token on the server and removes it from the credentials file. `--reg
 
 ### `phoenix deploy`
 
-Validates the spec, packs and uploads the project, starts its build on the server and follows it until the configurator is live. `--region` or `--serverUrl` selects the server, as for `login`; `--no-wait` returns as soon as the build starts.
+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. 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. `--region` or `--serverUrl` selects the server, as for `login`; `--no-wait` returns as soon as the build starts.
 
 ### `phoenix feedback <message>`
 

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

@@ -197,7 +197,7 @@ 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. Phoenix keeps them in step with the installed SDK, including the reference files inside a skill folder. Other skill folders are never touched.
+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. 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`.
 

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

@@ -4,27 +4,30 @@ An SDK-builder workspace lets you build one configurator from the application sp
 
 Your workspace comes with one project and one `production` environment. Its first deployment is a hello-world configurator, so you have a live link before you change anything.
 
-Your workspace's Studio shows the setup, the link to your configurator and the setup steps with your workspace filled in. Studio already names the CLI `salsita`, the name it is being renamed to; until that rename ships, use the `phoenix` commands on this page. If the first deployment fails, Studio shows why and lets you retry it.
+Your workspace's Studio shows the setup, the link to your configurator and the setup steps with your workspace filled in. If the first deployment fails, Studio shows why and lets you retry it.
 
 ## Before you start
 
 - **Package access:** `@salsita-ai/sdk` is public on npm; `npx` and `pnpm install` download it without a registry token.
 - **Workspace details:** you need your workspace slug and its Phoenix region (`eu` or `us`), which you also received with your workspace.
 - **Tools:** Node.js and pnpm.
+- **SDK build:** during the internal beta, use the `canary` build of the SDK, as the commands below do. It is published from every change to the platform, so it is newer than the last release.
 
 ## 1. Create a project
 
 ```bash
-npx -p @salsita-ai/sdk phoenix init my-configurator
+npx -p @salsita-ai/sdk@canary phoenix init my-configurator
 cd my-configurator
 pnpm install
 pnpm phoenix sync
 ```
 
-`phoenix init [folder]` writes the starter project: `package.json` and the starter spec, `spec/application.yaml` and `spec/configurator.yaml`, which describe one box you can resize and recolour. The starter depends on the same SDK version as the CLI that created it. `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. `phoenix sync` then adds the rest of the project: package scripts, webhooks, README and lint config.
 
 `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.
 
+`pnpm-workspace.yaml` holds the pnpm settings the install needs: it allows the build scripts of the SDK's dependencies and exempts `@salsita-ai/*` packages from pnpm's minimum release age, so a build of the SDK published today installs. The file is yours to edit, for example to allow the build script of a dependency you add. `phoenix sync` adds these entries when they are missing and keeps the values you set. A project inside a pnpm monorepo gets no file of its own; the workspace root holds the settings.
+
 The starter `spec/application.yaml` begins with `project: default`, which means the default project of the workspace you sign in to. Leave it as it is; a workspace has one project.
 
 ## 2. Sign in
@@ -54,12 +57,14 @@ The CLI stores the token in `~/.phoenix/credentials.json`, readable only by you,
 pnpm phoenix dev
 ```
 
-Signed in, `phoenix dev` needs no `.env` and nothing set up in Studio. When it starts, it asks the server for your development environment in the project the spec names. The server creates that environment the first time and finds it again on every later run. `phoenix dev` prints the workspace, project and environment it works in, prepares a development deployment there and opens the webhook tunnel, as for any Phoenix project (see [Phoenix CLI](?path=/docs/phoenix-phoenix-cli--docs)).
+Signed in, `phoenix dev` needs no `.env` and nothing set up in Studio. When it starts, it asks the server for your development environment in the project the spec names. The server creates that environment the first time and finds it again on every later run. `phoenix dev` prints the workspace, project and environment it works in, prepares a development deployment there and opens the webhook tunnel, as for any Phoenix project (see [Phoenix CLI](?path=/docs/phoenix-phoenix-cli--docs)). It then prints the address of the preview as `Preview: <url>`; the preview talks to the server the deployment was prepared on.
 
 Every user of the workspace gets their own development environment, so a teammate 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.
 
+Coding agents follow the generated `phoenix` skill: before their first change they start `phoenix dev` and open the preview in your browser, and after `phoenix deploy` starts a build they open its page in Studio.
+
 To build the configurator with your coding agent, give it your product documents, prices, pictures, drawings or models and ask it to create the configurator. The generated `phoenix-create-configurator` skill guides it through five stages: a representative first slice you can try early, a plan of the whole configuration experience, options and features added in small increments, finalization, and a complete review. It studies the SDK documentation before building, keeps a `configurator-spec.md` in the project as the record of what is decided and what remains open, and asks you only for decisions it cannot derive from your materials.
 
 ## 4. Deploy
@@ -71,11 +76,11 @@ pnpm phoenix deploy
 `phoenix deploy` goes through these steps:
 
 1. It validates the application spec.
-2. It packs the project files: the `.yaml` files in `spec`, everything in `src`, `mocks`, `assets`, `public` and `templates`, and `package.json`, `pnpm-lock.yaml`, `.gitignore`, `CLAUDE.md` and `.cursor/rules/phoenix.mdc`. Every `node_modules`, `.phoenix` and `__generated` folder, every `.DS_Store` and `._*` file and every `.env` and `.env.*` file are left out, at any depth.
+2. It packs the project files: the `.yaml` files in `spec`, everything in `src`, `mocks`, `assets`, `public` and `templates`, and `package.json`, `pnpm-lock.yaml`, `pnpm-workspace.yaml`, `.gitignore`, `CLAUDE.md` and `.cursor/rules/phoenix.mdc`. Every `node_modules`, `.phoenix` and `__generated` folder, every `.DS_Store` and `._*` file and every `.env` and `.env.*` file are left out, at any depth.
 3. It uploads the archive, which may be up to 200 MB.
-4. It starts the build and follows it until your configurator is live, then prints its URL.
+4. It starts the build, prints a link to the build's page in Studio and follows the build until your configurator is live, then prints its URL.
 
-On the server, the build runs without platform secrets. It sees only your own environment variables and the public platform values, the [build environment](?path=/docs/phoenix-phoenix-cli--docs) that `phoenix deployment:build-envs` writes. The trusted deploy step then publishes the frontend, webhooks and assets.
+On the server, the install follows your `pnpm-lock.yaml` and `pnpm-workspace.yaml`, so it allows the same build scripts and package versions as `pnpm install` on your computer. The build runs without platform secrets. It sees only your own environment variables and the public platform values, the [build environment](?path=/docs/phoenix-phoenix-cli--docs) that `phoenix deployment:build-envs` writes. The trusted deploy step then publishes the frontend, webhooks and assets.
 
 If the build fails, is cancelled or takes too long, `phoenix deploy` prints the end of the build log and exits with an error. `--no-wait` returns as soon as the build starts.
 
@@ -90,7 +95,7 @@ Tell us what is broken, confusing or missing, from wherever you are:
 - In Studio, **Send beta feedback** in the sidebar opens a short form.
 - In the terminal, `pnpm phoenix feedback "<message>" --type bug|idea|other` sends it with your sign-in. See the [CLI reference](?path=/docs/phoenix-phoenix-cli--docs).
 
-Coding agents working in your project use the same command, guided by the generated `phoenix-feedback` skill. They never send on their own: an agent shows you a draft, right away when the problem is crucial and otherwise at the end of the task, and sends it only after you approve it. They are told never to include secrets, customer data or your project's source.
+Coding agents working in your project use the same command, guided by the generated `phoenix-feedback` skill. They never send on their own: an agent shows you a draft, right away when the problem is crucial and otherwise at the end of the task, and sends it only after you approve it. They are told never to include secrets, customer data or your project's source. After a deploy goes live, the agent also asks you, once per conversation, to rate building with Phoenix from 0 to 10; it tells you the answer goes to the Phoenix team, shows the message and sends it only after you approve it.
 
 ## Known limits