@salsita-ai/sdk 0.50.0-develop.da8d27f5d7 → 0.50.0-develop.ea458ea381

package/dist/docs/index.json

@@ -1,5 +1,5 @@
 {
-  "generatedAt": "2026-10-08T09:21:48.882Z",
+  "generatedAt": "2026-10-08T15:23:30.576Z",
   "categories": [
     {
       "name": "Phoenix",
@@ -26,7 +26,7 @@
         },
         {
           "title": "Best Practices",
-          "description": "1. **YAML is king** - 99% of configuration should be in spec/\\*.yaml files 2. **Custom code locations** (in order of preference): - `src/expressions/` - Computed/derived properties -...",
+          "description": "1. **YAML is king** - 99% of configuration should be in spec/\\*.yaml files 2. **Custom code locations** (in order of preference): - `src/expressions/` - Computed/derived properties - `src/actions/` -...",
           "path": "docs/phoenix/best-practices.mdx",
           "category": [
             "Phoenix",
@@ -2479,6 +2479,16 @@
           ],
           "source": "storybook-example"
         },
+        {
+          "title": "Domain Actions",
+          "description": "A plate carries holes, and a hole can be nudged by an offset as long as it stays on the plate. The arrow buttons of a selected hole and the AI assistant both make this change, so the rule (\"stay on...",
+          "path": "docs/other-features/domain-actions.mdx",
+          "category": [
+            "Other features",
+            "Domain Actions"
+          ],
+          "source": "storybook-example"
+        },
         {
           "title": "Not Found (404)",
           "description": "Error page that is displayed when the configuration is not accesible.",

package/dist/docs/other-features/domain-actions.mdx

@@ -0,0 +1,418 @@
+# Domain Actions
+
+- [Use case](#use-case)
+- [Declare the action](#declare-the-action)
+- [Implement it](#implement-it)
+- [Run it from the UI](#run-it-from-the-ui)
+- [Expose it to the assistant](#expose-it-to-the-assistant)
+- [Known gaps](#known-gaps)
+- [Example](#example)
+
+## Use case
+
+A plate carries holes, and a hole can be nudged by an offset as long as it stays on the plate. The arrow buttons of a selected hole and the AI assistant both make this change, so the rule ("stay on the plate") has to live in one place.
+
+An **action** is that place: a named domain operation you declare once under `actions:`, implement in `src/actions/` with generated parameter and result types, and run from any control through `actionSystem.prepareAction()`. The same action is exposed to the assistant as a custom mutation by naming it under `assistant.actions`. Use an action whenever a change is more than writing one field: a swap, a move among siblings, a change that touches several entities at once.
+
+## Declare the action
+
+`params` and `result` are maps of named JSON schemas, with the same `phx:` refs, `references`, `tsType` and `import` as entity shapes. A param whose schema allows `null` is optional; every other param is required. A result member typed `phx:$DomainEntity` is the enhanced entity after the change.
+
+```yaml
+actions:
+  nudgeHole:
+    description: Moves a hole by an offset on the plate; the move fails when the hole would leave the plate
+    params:
+      holeId:
+        $ref: phx:DomainEntityId
+        references: Hole
+        description: The hole to move
+      dx:
+        type: integer
+        description: Offset along the x axis, in plate units
+      dy:
+        type: integer
+        description: Offset along the y axis, in plate units
+    result:
+      hole:
+        $ref: phx:$DomainEntity
+        references: Hole
+        description: The hole at its new position
+      plate:
+        $ref: phx:$DomainEntity
+        references: Plate
+        description: The plate after the move
+```
+
+Generation derives the types `ActionTypes`, `ActionName`, `ActionParams<'nudgeHole'>` and `ActionResult<'nudgeHole'>` from it: here `ActionParams<'nudgeHole'>` is `{ holeId: Hole['id']; dx: number; dy: number }` and `ActionResult<'nudgeHole'>` is `{ hole: $Hole; plate: $Plate }`. The `description` of the action, of a param and of a result member becomes the doc comment of its generated property, so it shows in the editor wherever the action is implemented or called.
+
+## Implement it
+
+A file in `src/actions/` default-exports `phx.domain.implementActions({...})` with any subset of the declared actions. The implementation receives the validated parameters, the state the action runs on, and a context with the `expressionContext`, the domain `systems`, `getIdSequence()` for entities it creates and the typed `updates` factory. It returns the updates it wants applied and `readResult`, which reads the result from the state those updates produced, including whatever the transformers added. It never stages or commits anything.
+
+```ts
+// src/actions/nudge-hole.ts
+export default phx.domain.implementActions({
+  nudgeHole: ({ holeId, dx, dy }, state, { systems: { domain }, updates }) => {
+    // `references: Hole` types the id, but any entity id passes the runtime check, so the entity is verified here.
+    const hole = state.entities.find(entity => entity.id === holeId)
+
+    if (hole?.type !== 'Hole') {
+      throw new Error(
+        `"${holeId}" is not a hole of the plate, so it cannot be nudged. Query the plate's holes and use an id they return.`
+      )
+    }
+
+    const x = hole.x + dx
+    const y = hole.y + dy
+
+    if (Math.abs(x) > 150 || Math.abs(y) > 150) {
+      throw new Error(
+        `Nudging "${holeId}" by (${dx}, ${dy}) would put it at (${x}, ${y}), outside the plate. Keep both coordinates between -150 and 150.`
+      )
+    }
+
+    return {
+      updates: [updates.DomainEntityModification({ entityId: hole.id, stateDelta: { x, y }, updateTag: 'nudgeHole' })],
+      readResult: ({ state: nudged }) => ({
+        hole: domain.get$Entity(holeId, nudged),
+        plate: domain.getRoot$Entity(nudged),
+      }),
+    }
+  },
+})
+```
+
+Throw to reject a call: the message reaches the user through the control's hint and the assistant through the failed mutation, so say what went wrong and what to send instead. An action declared without an implementation, or an implementation of a name the spec does not declare, is a type error. A declared action without an implementation also stops the domain from initializing, and under `phoenix dev` the editor reports it as a `MISSING_ACTION_IMPLEMENTATIONS` diagnostic and does not apply the change; an implementation of an undeclared name is logged.
+
+## Run it from the UI
+
+`phx.frontend.useDomain().actionSystem.prepareAction(name, args, state)` validates `args` against the declared params and returns `{ updates, readResult }`. Hand the updates to `useUpdateControl()` like any other change: it dry-runs them for hints and commits them on click.
+
+```tsx
+export default phx.frontend.createCustomPhoenixEntityElement('NudgeControl', ({ entityId }) => {
+  const { actionSystem } = phx.frontend.useDomain()
+  const state = phx.frontend.useCommittedState()
+  const prepare = phx.frontend.useUpdateControl()
+
+  const left = prepare(actionSystem.prepareAction('nudgeHole', { holeId: entityId, dx: -20, dy: 0 }, state).updates)
+
+  return (
+    <Button disabled={left.disabled} title={left.hints} onClick={left.update}>
+      ←
+    </Button>
+  )
+})
+```
+
+`prepareAction` throws for arguments that do not fit the params, for an unknown action and for whatever the implementation rejects, so a control that may ask for an impossible move catches the error and shows its message, as the example's control does.
+
+## Expose it to the assistant
+
+Naming the action under `assistant.actions` adds a `Mutation` field with one argument per param and a `<Name>Result` type whose entity members are traversable edges. `as` renames the field, `description` replaces the action's.
+
+```yaml
+assistant:
+  actions:
+    nudgeHole:
+```
+
+```graphql
+type Mutation {
+  nudgeHole(holeId: ID!, dx: Int!, dy: Int!): NudgeHoleResult!
+}
+
+type NudgeHoleResult {
+  hole: Hole!
+  plate: Plate!
+}
+```
+
+The field runs the same `prepareAction`, applies the updates through the same validation as every other mutation, and fails with the action's message when the call is rejected.
+
+## Known gaps
+
+- `references` on a `phx:DomainEntityId` param types the parameter and the GraphQL argument, but at runtime any entity id passes the params check: the implementation verifies that the id names an entity of the expected type, as the example does.
+- Actions exist in the configurator domain only; the admin domain declares none.
+- The result of `readResult` is not validated at runtime: the generated TypeScript type and the GraphQL coercion are the checks.
+- The assistant cannot dry-run a custom mutation the way it dry-runs recipes and field options.
+- `useDomain()` types `prepareAction` with the generic action map, so the name and the arguments are not checked against your `ActionTypes` at that call site; the implementation side is fully typed.
+
+## Example
+
+Select a hole and nudge it with the arrows. A move that would leave the plate is disabled with the action's message.
+
+## 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:
+      - Plate
+      - Hole
+    aliases:
+      RootEntity:
+        - Plate
+    shapes:
+      Hole:
+        x:
+          type: number
+        y:
+          type: number
+
+relations:
+  Plate:
+    $holes:
+      kind: allOfType
+      target: Hole
+      cardinality: 0-N
+      composedOf: true
+  Hole:
+    $plate:
+      kind: allOfType
+      target: Plate
+      cardinality: 1-1
+      composedOf: false
+
+expressions:
+  Hole:
+    $radius:
+      type: number
+
+# A named domain operation: declared once, implemented in src/actions/, run by the NudgeControl
+# element and by the assistant alike.
+actions:
+  nudgeHole:
+    description: Moves a hole by an offset on the plate; the move fails when the hole would leave the plate
+    params:
+      holeId:
+        $ref: phx:DomainEntityId
+        references: Hole
+        description: The hole to move
+      dx:
+        type: integer
+        description: Offset along the x axis, in plate units
+      dy:
+        type: integer
+        description: Offset along the y axis, in plate units
+    result:
+      hole:
+        $ref: phx:$DomainEntity
+        references: Hole
+        description: The hole at its new position
+      plate:
+        $ref: phx:$DomainEntity
+        references: Plate
+        description: The plate after the move
+
+assistant:
+  ai:
+    provider: openai
+    model: balanced
+    reasoning: low
+  entities:
+    Plate:
+      $holes:
+        description: The holes of the plate
+    Hole:
+      x:
+      y:
+  actions:
+    nudgeHole:
+
+presets:
+  - rootEntityType: 'Plate'
+    initialDomainEntities:
+      - id: 'Plate-1'
+        type: 'Plate'
+      - id: 'Hole-1'
+        type: 'Hole'
+        x: -60
+        y: 40
+      - id: 'Hole-2'
+        type: 'Hole'
+        x: 70
+        y: -50
+
+components:
+  Plate:
+    applicationConfig:
+      main:
+        layout: 'universal'
+    staticPerspectiveCamera:
+      main:
+        distance: 400
+        priority: 1
+        polarAngle: 1.2
+        azimuthAngle: -0.2
+    sceneEntityProperties:
+      main:
+        offsetX: -100
+        offsetY: -100
+        offsetZ: -10
+    sceneEntityObject:
+      Plate:
+        object:
+          $read: $render
+    detail:
+      main:
+        title: 'Plate'
+        subtitle: 'A plate with holes'
+        description: 'Select a hole to nudge it.'
+  Hole:
+    sceneEntityProperties:
+      main:
+        offsetX:
+          $read: x
+        offsetY:
+          $read: y
+    sceneEntitySelectHotspot:
+      main:
+        offsetX: 15
+        offsetY: 15
+        offsetZ: 30
+    detail:
+      main:
+        title: 'Hole'
+        subtitle: 'A hole in the plate'
+        description: 'Nudge it with the arrows; a hole cannot leave the plate.'
+    propertyPage:
+      main:
+        children:
+          - kind: propertyContainerGroup
+            props:
+              spacing: large
+            children:
+              - kind: customElement
+                props:
+                  name: NudgeControl
+```
+
+### ./src/actions/nudge-hole.ts
+
+```ts
+import { phx } from '../../.phoenix/phx.js'
+
+/** How far a hole may sit from the plate's center on either axis, in plate units. */
+const REACH = 150
+
+export default phx.domain.implementActions({
+  nudgeHole: ({ holeId, dx, dy }, state, { systems: { domain }, updates }) => {
+    // `references: Hole` types the id, but any entity id passes the runtime check, so the entity is verified here.
+    const hole = state.entities.find(entity => entity.id === holeId)
+
+    if (hole?.type !== 'Hole') {
+      throw new Error(
+        `"${holeId}" is not a hole of the plate, so it cannot be nudged. Query the plate's holes and use an id they return.`
+      )
+    }
+
+    const x = hole.x + dx
+    const y = hole.y + dy
+
+    if (Math.abs(x) > REACH || Math.abs(y) > REACH) {
+      throw new Error(
+        `Nudging "${holeId}" by (${dx}, ${dy}) would put it at (${x}, ${y}), outside the plate. Keep both coordinates between ${-REACH} and ${REACH}.`
+      )
+    }
+
+    return {
+      updates: [updates.DomainEntityModification({ entityId: hole.id, stateDelta: { x, y }, updateTag: 'nudgeHole' })],
+      readResult: ({ state: nudged }) => ({
+        hole: domain.get$Entity(holeId, nudged),
+        plate: domain.getRoot$Entity(nudged),
+      }),
+    }
+  },
+})
+```
+
+### ./src/elements/NudgeControl.tsx
+
+```tsx
+import { Button, Stack } from '@mui/material'
+
+import { PropertyContainer } from '@salsita-ai/sdk/ui'
+
+import { phx } from '../../.phoenix/phx.js'
+
+const STEP = 20
+
+/** Nudges the selected hole with the same `nudgeHole` action the assistant calls, one step at a time. */
+export default phx.frontend.createCustomPhoenixEntityElement('NudgeControl', ({ entityId }) => {
+  const { actionSystem } = phx.frontend.useDomain()
+  const state = phx.frontend.useCommittedState()
+  const prepare = phx.frontend.useUpdateControl()
+  const hole = state.entities.find(entity => entity.id === entityId)
+
+  if (hole?.type !== 'Hole') {
+    return <></>
+  }
+
+  // An action throws when the move leaves the plate; the button for that direction is then disabled with the message.
+  const nudge = (dx: number, dy: number) => {
+    try {
+      return prepare(actionSystem.prepareAction('nudgeHole', { holeId: hole.id, dx, dy }, state).updates)
+    } catch (error) {
+      return { disabled: true, hints: error instanceof Error ? error.message : String(error), update: () => {} }
+    }
+  }
+
+  const directions = [
+    { label: '←', dx: -STEP, dy: 0 },
+    { label: '→', dx: STEP, dy: 0 },
+    { label: '↑', dx: 0, dy: STEP },
+    { label: '↓', dx: 0, dy: -STEP },
+  ]
+
+  return (
+    <PropertyContainer.Item title="Nudge" description={`Moves the hole by ${STEP} units.`}>
+      <Stack direction="row" spacing={1}>
+        {directions.map(({ label, dx, dy }) => {
+          const control = nudge(dx, dy)
+
+          return (
+            <Button
+              key={label}
+              variant="outlined"
+              disabled={control.disabled}
+              title={control.hints ?? undefined}
+              onClick={event => {
+                event.stopPropagation()
+                control.update()
+              }}
+            >
+              {label}
+            </Button>
+          )
+        })}
+      </Stack>
+    </PropertyContainer.Item>
+  )
+})
+```
+
+### ./src/expressions/plate.ts
+
+```ts
+import { createPlate } from '../../../../common/plate-rendering.js'
+import { phx } from '../../.phoenix/phx.js'
+
+export default phx.domain.implementCustomExpressions({
+  Hole: {
+    $radius: () => 10,
+  },
+  Plate: {
+    $render: plate => createPlate({ features: plate.$holes }),
+  },
+})
+```
+
+</details>

package/dist/docs/phoenix/best-practices.mdx

@@ -5,6 +5,7 @@
 1. **YAML is king** - 99% of configuration should be in spec/\*.yaml files
 2. **Custom code locations** (in order of preference):
    - `src/expressions/` - Computed/derived properties
+   - `src/actions/` - Named domain operations declared under `actions:`
    - `src/invariants/` - Business rule constraints
    - `src/transformers/` - Automatic state fixers
    - `src/handlers/` - Event & lifecycle handlers

package/dist/docs/phoenix/migrations.mdx

@@ -18,6 +18,8 @@ Each version defines its own:
 
 This versioning allows you to track changes over time and ensure proper migration paths.
 
+The version number is not written anywhere: `latest` is the highest numbered version plus one, so a model with only `latest` is version 1. Once a version has been deployed it cannot change, because saved configurations depend on it. `phoenix deploy` refuses a model that differs from the one deployed under the same version, before anything is uploaded. To change a deployed model, keep it unchanged as `v<N>`, make the change in `latest` and add the migration to version N+1. Development environments replace the deployed model instead, so `phoenix dev` accepts every change.
+
 ## Model File Structure
 
 It's recommended to split your model versions into separate files for better maintainability:
@@ -39,9 +41,11 @@ The CLI generates separate TypeScript types for each version, which helps ensure
 
 ```typescript
 // The Migration type ensures you handle all entity types
-type Migration<FromEntity, ToEntity> = (state: FromEntity[]) => ToEntity[]
+type Migration<FromEntity, ToEntity> = (state: readonly FromEntity[]) => readonly ToEntity[]
 ```
 
+The types of each version are generated as global namespaces: `ModelV1`, `ModelV2`, and so on. `ModelV1.AnyDomainEntity` is the union of all entities of version 1, and `ModelV1.<EntityType>` is one of them. The admin model has its own namespaces, `AdminV1`, `AdminV2`, and so on. A migration needs no import for them.
+
 ## Migration File Location
 
 Migration files are organized in the `src/migrations/` directory with a specific naming convention:
@@ -63,11 +67,16 @@ Each migration file should export a function named `migrateToVN` where N is the
 
 ```typescript
 // src/migrations/v2.ts
-export const migrateToV2: Migration<V1Entity, V2Entity> = state => {
+import type { Migration } from '@salsita-ai/sdk/domain'
+
+export const migrateToV2: Migration<ModelV1.AnyDomainEntity, ModelV2.AnyDomainEntity> = state => {
   // Transform entities from v1 to v2
+  return state
 }
 ```
 
+Keep the `Migration<...>` type on the export, with its `readonly` arrays: the generated domain file passes each migration to the migration builder, and a function typed with mutable arrays does not type-check there.
+
 **Note:** Migrations start from version 2. There is no migration TO v1 since v1 is the initial version. The first migration you write will be `migrateToV2`.
 
 The `ts-pattern` library is recommended for implementing migrations as it provides type-safe pattern matching.
@@ -77,11 +86,15 @@ The `ts-pattern` library is recommended for implementing migrations as it provid
 Migrations are implemented as functions that transform entities from one version to another. Each migration handles the transition between consecutive versions:
 
 ```typescript
-export const migrateToV4: Migration<V3Entity, V4Entity> = state => {
+import { match } from 'ts-pattern'
+
+import type { Migration } from '@salsita-ai/sdk/domain'
+
+export const migrateToV4: Migration<ModelV3.AnyDomainEntity, ModelV4.AnyDomainEntity> = state => {
   return state.map(entity => {
     return (
       match(entity)
-        .returnType<V4Entity>()
+        .returnType<ModelV4.AnyDomainEntity>()
         .with({ type: 'Burner' }, value => ({ ...value, y: 0 }))
         .with({ type: 'Cabinet' }, value => ({ ...value, y: 0 }))
         // ... handle other entities
@@ -91,6 +104,33 @@ export const migrateToV4: Migration<V3Entity, V4Entity> = state => {
 }
 ```
 
+### Renaming an Entity Type
+
+An entity id starts with its entity type, such as `Box-1`, and is typed per entity type (`DomainEntityId<'Box'>`). The runtime validates that an entity's id matches its type, so an entity that keeps its data under a new type name needs a new id, and every relation that points at it must be rewritten to that id. The id is built from a string, which TypeScript cannot check, so this is one place where a cast is needed:
+
+```typescript
+import { parseDomainEntityId } from '@salsita-ai/sdk/domain'
+
+const toTableId = (id: ModelV1.Box['id']) =>
+  // The id is rebuilt for the new type name; nothing narrower than a cast can type a template string as an id
+  `Table-${parseDomainEntityId(id).sequenceNumber}` as ModelV2.Table['id']
+```
+
+### Replacing the Model Entirely
+
+When the new model has nothing in common with the deployed one, there is nothing to convert. This is the case when a project that was first deployed as the starter gets its real model: the starter's `Box` model is version 1 in production, and a deployed version cannot change. Keep the deployed model as `v1`, define the real model in `latest`, and let the migration return the starting state of the new model, the `initialDomainEntities` of its preset:
+
+```typescript
+// src/migrations/v2.ts
+import type { Migration } from '@salsita-ai/sdk/domain'
+
+export const migrateToV2: Migration<ModelV1.AnyDomainEntity, ModelV2.AnyDomainEntity> = () => [
+  // the entities of the new model's preset
+]
+```
+
+No entity of a type that the new version no longer has may stay in the returned state: the migrated state is validated against the latest model, and an unknown entity type fails the load.
+
 ## Migration Runtime
 
 Migrations are executed automatically every time the domain is loaded, both in the client application and in webhooks. During this process:
@@ -114,7 +154,7 @@ When implementing migrations:
 
 4. **Testing**: Thoroughly test migrations with real-world data to ensure they handle all edge cases, use existing configurations from previous versions.
 
-5. **Version Bumping**: Consider bumping the model version for both breaking changes (removing fields, changing types) and additive changes where existing data needs proper defaults. If you add a new required field, existing configurations need a migration to set that field's default value.
+5. **Version Bumping**: Every change to a model that has been deployed needs a new version, whether it is breaking (removing fields, changing types) or additive. If you add a new required field, existing configurations need a migration to set that field's default value; a change that needs no conversion still needs a migration that returns the state unchanged.
 
 ## Admin Model Migrations
 

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

@@ -569,9 +569,11 @@ SDK-builder workspaces sign the CLI in with a personal API token instead of proj
 
 Signs the CLI in to the SDK-builder workspace `<customer>`:
 
-1. Opens Studio, where you approve the sign-in (use `--no-open` to only print the link).
+1. Opens Studio, where you name the token and approve the sign-in (use `--no-open` to only print the link). The page shows the workspace, your account, the computer the CLI runs on and how long the link still works. The CLI suggests the name `phoenix CLI on <computer>`; change it so you can tell your machines and agents apart later.
 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.
+3. The CLI exchanges the code for a token with the name you approved, and sends the browser back to Studio, which confirms the sign-in.
+
+**Deny** in Studio stops the CLI at once: it exits with `The sign-in was denied in Studio` and no token is created. The link works for five minutes and only for the CLI that printed it; after that, Studio shows that it no longer works and the CLI gives up.
 
 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.
 
@@ -592,7 +594,7 @@ Revokes the token on the server and removes it from the credentials file. `--reg
 
 ### `phoenix deploy`
 
-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.
+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. `--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

@@ -40,6 +40,7 @@ project-root/
 | `components/`   | Phoenix system components (ECS)                                        |
 | `elements/`     | Page elements (pages, providers)                                       |
 | `expressions/`  | Domain logic expressions                                               |
+| `actions/`      | Implementations of the domain actions declared under `actions:`        |
 | `invariants/`   | Domain constraints                                                     |
 | `transformers/` | Data transformation logic                                              |
 | `handlers/`     | Event & lifecycle handlers                                             |
@@ -249,6 +250,7 @@ project-root/
 │   ├── components/                # Phoenix system components (ECS)
 │   ├── elements/                  # UI elements (pages, providers)
 │   ├── expressions/               # Domain logic expressions
+│   ├── actions/                   # Domain action implementations
 │   ├── invariants/                # Domain constraints
 │   ├── transformers/              # Data transformation logic
 │   ├── handlers/                  # Event & lifecycle handlers
@@ -362,6 +364,7 @@ Domain logic files define the business rules and computed properties of your con
 | Purpose      | Location            | Example Files                                  |
 | ------------ | ------------------- | ---------------------------------------------- |
 | Expressions  | `src/expressions/`  | `table.ts`, `legs.ts`, `module.ts`             |
+| Actions      | `src/actions/`      | `move-part.ts`, `swap-cabinets.ts`             |
 | Invariants   | `src/invariants/`   | `top.ts`, `legs.ts`                            |
 | Transformers | `src/transformers/` | `fix-table-top-material-update-transformer.ts` |
 | Migrations   | `src/migrations/`   | `v2.ts`, `v3.ts`, `v4.ts`                      |

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

@@ -36,11 +36,11 @@ The starter `spec/application.yaml` begins with `project: default`, which means
 pnpm phoenix login <workspace>
 ```
 
-`phoenix login` opens Studio, where you approve the sign-in. Studio sends a one-time code back to the CLI on `127.0.0.1`, and the CLI exchanges it for a personal token. The code only works for the CLI that asked for it and expires after five minutes. Use `--no-open` to print the link instead of opening a browser.
+`phoenix login` opens Studio, where you name the token and approve the sign-in. The CLI suggests `phoenix CLI on <computer>`; a name of your own, such as the agent and the machine, tells your tokens apart later. Studio sends a one-time code back to the CLI on `127.0.0.1`, the CLI exchanges it for a personal token and returns the browser to Studio, which confirms the sign-in. The code only works for the CLI that asked for it and expires after five minutes. **Deny** stops the waiting CLI at once and creates no token. Use `--no-open` to print the link instead of opening a browser.
 
 The CLI stores the token in `~/.phoenix/credentials.json`, readable only by you, with one entry per server. `PHOENIX_CREDENTIALS_FILE` moves the file. The token acts for you in your workspace until you revoke it. It stops working when you are removed from the workspace or banned.
 
-`pnpm phoenix logout` revokes the token and removes it from the file. Studio's **CLI tokens** page lists your tokens with when they were last used, and revokes any of them, for example one left on another computer.
+`pnpm phoenix logout` revokes the token and removes it from the file. Studio's **CLI tokens** page lists your tokens by the names you gave them, with when they were last used, and revokes any of them, for example one left on another computer. A revoked token leaves the list.
 
 `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`:
 
@@ -77,8 +77,9 @@ pnpm phoenix deploy
 
 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`, `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, prints a link to the build's page in Studio and follows the build until your configurator is live, then prints its URL.
+3. It asks the server for a build. The server compares your domain model with the deployed one and refuses, before anything is uploaded, a model that changed under an already deployed model version; see [Migrations](?path=/docs/phoenix-migrations--docs).
+4. It uploads the archive, which may be up to 200 MB.
+5. 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 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.
 
@@ -100,6 +101,7 @@ Coding agents working in your project use the same command, guided by the genera
 ## Known limits
 
 - You can deploy once the workspace's first deployment is live. Until then, `phoenix deploy` tells you the workspace is still being set up.
+- The first deployment is the starter, so the starter's model is version 1 in production. Replacing it with your own model needs the starter's model kept as `v1` and a migration to version 2; [Migrations](?path=/docs/phoenix-migrations--docs) shows the migration for replacing a model entirely.
 - One workspace has one project, one `production` environment and one development environment per user.
 - `phoenix deploy` always deploys to the workspace's default project; it doesn't read `project` from the spec yet.
 - Only `phoenix dev` works from the sign-in. `phoenix deployment:prepare-dev` still needs the `.env` block of a Studio development environment.

package/dist/domain/actions/action-factory.d.ts

@@ -0,0 +1,10 @@
+import type { ActionImplementations, ActionTypes } from '../core/action.js';
+import type { $DomainEntity, DomainEntity } from '../core/model.js';
+/**
+ * Creates the `implementActions` factory the generated `domain-spec.ts` exposes as
+ * `phx.domain.implementActions`. A module in `src/actions/` implements any subset of the declared
+ * actions and gets each parameter and result typed from the spec; a name the spec does not declare
+ * is a type error, since its implementation would have to be `never`. The generated barrel merges
+ * the modules and checks that every declared action is implemented.
+ */
+export declare const createActionFactory: <ENTITIES extends DomainEntity<string>, ALLOWED_ROOT_ENTITIES extends ENTITIES, $MAP extends Record<ENTITIES['type'], $DomainEntity<ENTITIES>>, PUBLISHED_DATA extends Record<string, unknown>, SESSION_DATA extends Record<string, unknown>, FRONTEND_DATA extends Record<string, unknown>, NAVIGATION_STATES extends string, VIEW_STATES extends string, TOOL_STATES extends string, EXPORT_STATES extends string, ACTION_TYPES extends ActionTypes>() => <IMPLEMENTATIONS extends Partial<ActionImplementations<ENTITIES, ALLOWED_ROOT_ENTITIES, $MAP, PUBLISHED_DATA, SESSION_DATA, FRONTEND_DATA, NAVIGATION_STATES, VIEW_STATES, TOOL_STATES, EXPORT_STATES, ACTION_TYPES>>>(implementations: IMPLEMENTATIONS & Readonly<Record<Exclude<keyof IMPLEMENTATIONS, keyof ACTION_TYPES>, never>>) => IMPLEMENTATIONS;

package/dist/domain/actions/action-factory.js

@@ -0,0 +1 @@
+export const createActionFactory=()=>t=>t;