@salsita-ai/sdk 0.50.0-develop.2331d4a6b7 → 0.50.0-develop.42cf9563b0

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/admin.mdx

@@ -421,7 +421,7 @@ export const handler = webhookBuilder
 
 The publishing workflow validates admin state, transforms entities, and stores JSON to S3. Configurators access published data via `ctx.publishedData` in expressions.
 
-For implementation examples, see `packages/demos/demo-finalize/src/handlers/map-published-revision-data.ts`.
+For implementation examples, see `packages/demos/demo-catalog-builder/src/handlers/map-published-chunked-data.ts`.
 
 For technical details about data transformation and storage, see [Data Sources - Published Data](?path=/docs/phoenix-data-sources--docs#published-data).
 
@@ -515,4 +515,4 @@ Ready to implement admin functionality in your Phoenix project? Here's what to e
 - **[Sessions and Access](?path=/docs/phoenix-sessions-and-access--docs)** - Understand admin authentication and permissions
 - **[Connected Data Sources](?path=/docs/phoenix-connected-data-sources--docs)** - Wire `$data` entries to Google Sheets or Excel; requires the embedded admin mode
 
-For hands-on examples, check out the finalize demo (`packages/demos/demo-finalize/`) which shows spec-driven admin using `createAdminPages` for presets and recipes. This demo demonstrates the YAML-based admin approach with publishing workflows rather than custom admin UI components.
+For hands-on examples, check out the Catalog Builder demo (`packages/demos/demo-catalog-builder/`), which shows spec-driven admin pages over connected and generated data, custom catalog pages beside them, admin model migrations, and the publishing workflow.

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/finalization.mdx

@@ -355,4 +355,4 @@ Now that you understand finalization workflows, explore these related topics:
 - **[Admin](?path=/docs/phoenix-admin--docs)** - Learn about admin finalization and published data generation
 - **[Best Practices](?path=/docs/phoenix-best-practices--docs)** - Follow proven patterns for finalization implementation
 
-For hands-on practice, explore the finalize demo in the **[Quickstart](?path=/docs/phoenix-quickstart--docs)** guide.
+For hands-on practice, explore the Precision demo (`packages/demos/demo-precision/`) for finalization resources — PDF, CSV, images, email attachments and callbacks — and the Catalog Builder demo (`packages/demos/demo-catalog-builder/`) for the finalization data lifecycle and access links.

package/dist/docs/phoenix/integration/headless-mode-external.mdx

@@ -51,11 +51,11 @@ For details on the server-side token exchange, see [Authentication](?path=/docs/
 
 The `power` attribute controls the configurator's state:
 
-| Value       | Behavior                                                                                                                                                 |
-| ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `"off"`     | Completely inactive. No rendering, no session, no network requests beyond loading the bundle.                                                            |
-| `"standby"` | Session initialized, assets preloaded (3D models, textures), but not rendered. Faster power-on, but consumes bandwidth and counts toward session quotas. |
-| `"on"`      | Fully active and visible.                                                                                                                                |
+| Value       | Behavior                                                                                                                                                                                                                 |
+| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `"off"`     | Completely inactive. No rendering, no session, no network requests beyond loading the bundle.                                                                                                                            |
+| `"standby"` | Session initialized and any textures listed in `resourcesConfig.prefetchTextureUrls` prefetched; nothing is rendered and no models are loaded. Faster power-on, but consumes bandwidth and counts toward session quotas. |
+| `"on"`      | Fully active and visible.                                                                                                                                                                                                |
 
 A typical flow: power on at login (`"standby"`), then toggle between `"on"` and `"standby"` as the user opens and closes the configurator. Use `"off"` only before the user has authenticated.
 

package/dist/docs/phoenix/integration/widget-mode-external.mdx

@@ -28,11 +28,11 @@ The configurator fills its parent container. Set a height on the element or a wr
 
 The `power` attribute controls whether the configurator is active. It accepts three values:
 
-| Value       | Behavior                                                                                                                                                                                             |
-| ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `"off"`     | Configurator is completely inactive. No rendering, no session initialization, no network requests beyond loading the bundle. Lowest resource usage.                                                  |
-| `"standby"` | Configurator initializes its session and preloads assets (3D models, textures), but does not render. Subsequent power-on is faster, but consumes bandwidth and counts toward monthly session quotas. |
-| `"on"`      | Configurator is fully active and visible.                                                                                                                                                            |
+| Value       | Behavior                                                                                                                                                                                                                                              |
+| ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `"off"`     | Configurator is completely inactive. No rendering, no session initialization, no network requests beyond loading the bundle. Lowest resource usage.                                                                                                   |
+| `"standby"` | Configurator initializes its session and prefetches any textures listed in `resourcesConfig.prefetchTextureUrls`, but does not render or load models. Subsequent power-on is faster, but consumes bandwidth and counts toward monthly session quotas. |
+| `"on"`      | Configurator is fully active and visible.                                                                                                                                                                                                             |
 
 ### Choosing the Initial Power
 

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

@@ -327,15 +327,49 @@ as restart-required unless their feature documentation explicitly states live-up
 
 Builds the project for production deployment.
 
-| Flag             | Env Variable    | Default | Description                    |
-| ---------------- | --------------- | ------- | ------------------------------ |
-| `--onlyFrontend` | —               | —       | Build only the frontend bundle |
-| `--onlyWebhook`  | —               | —       | Build only webhooks            |
-| `--force` / `-f` | `FORCE_REBUILD` | `false` | Force full rebuild, skip cache |
-| `--debug`        | `DEBUG`         | `false` | Verbose logging                |
+| Flag              | Env Variable    | Default | Description                                         |
+| ----------------- | --------------- | ------- | --------------------------------------------------- |
+| `--onlyFrontend`  | —               | —       | Build only the frontend bundle                      |
+| `--onlyWebhook`   | —               | —       | Build only webhooks                                 |
+| `--force` / `-f`  | `FORCE_REBUILD` | `false` | Force full rebuild, skip cache                      |
+| `--banner <text>` | —               | —       | Replaces the application line of the banner comment |
+| `--debug`         | `DEBUG`         | `false` | Verbose logging                                     |
 
 The build target can also be controlled via `BUILD_TARGET` env (`frontend`, `webhook`, or `both`).
 
+#### Banner comment
+
+Every JavaScript file the frontend build emits (the configurator, admin and embedded bundles, and the editor's entry and lazy chunks) starts with a comment that identifies the build, so `head -n 5 <bundle.js>` tells two deployed bundles of nearly the same size apart:
+
+```js
+/*!
+ * App version: 1.2.3; Commit: 9fd79ce0f4c1a2b3d4e5f60718293a4b5c6d7e8f
+ * Built with Salsita SDK 3.4.0. Copyright (c) Salsita s.r.o. All rights reserved.
+ * Third-party licences: THIRD-PARTY-LICENSES.txt
+ */
+```
+
+The first line is the application's. By default it holds `applicationVersion` from `spec/application.yaml` and the commit checked out in the project, read with `git rev-parse HEAD`. Where git cannot read a commit for the project (no checkout, git missing or refusing the repository, or the project's `package.json` is not tracked by the repository around it), the line holds the version only and `--debug` logs it; this is the case for a platform build from uploaded sources.
+
+`--banner <text>` replaces that line with your own text, for example when CI knows a release name the spec does not:
+
+```sh
+pnpm phoenix build --banner "Release: ${RELEASE_NAME}; Commit: ${COMMIT_SHA}"
+```
+
+The line is **public**: it ships in every bundle. The default publishes the application version and the commit SHA; pass `--banner ""` to leave the line out, and never put a secret or internal detail in your own text. The text is written as comment text only. Each line of a multi-line value (or each repeated `--banner`) becomes its own comment line and `*/` is written as `*\/`. There is no environment-variable fallback, and the option has no effect on webhook output or with `--onlyWebhook`. Lazy chunks keep their hashed file name when only the banner text changes.
+
+The banner and the licences file below are produced by the application-spec pipeline; the legacy pipeline's build ignores `--banner`.
+
+#### Third-party licences
+
+The frontend build writes `.phoenix/dist/frontend/THIRD-PARTY-LICENSES.txt` next to the bundles and the banner comment points to it. It lists every third-party package whose code or styles are in any of the frontend bundles, once each, sorted by name and version, with the package's version, the licence declared in its `package.json` and the text of its licence file (`LICENSE*`, `LICENCE*` or `COPYING*`). A package that ships no licence file is listed without the text. Your project's own source is not listed.
+
+Deploy the file together with the bundles, so the notices those licences ask for travel with every copy. The build lists licences; it does not judge whether a licence suits your product. Two kinds of package are not in the list, so add their notices yourself when you use them:
+
+- packages used only inside a web worker, which are bundled separately;
+- packages a stylesheet reaches on its own, through CSS `@import`, Sass `@use` or `url()`. A stylesheet imported from JavaScript or TypeScript (`import 'some-font/index.css'`) is listed.
+
 #### Bundle-size budgets
 
 Application-spec projects can set gzip-size limits for the standalone configurator and webhook bundles. Add the optional `budgets` section to a spec YAML file:
@@ -596,26 +630,30 @@ Revokes the token on the server and removes it from the credentials file. `--reg
 
 Validates the spec, adds the pnpm settings `phoenix init` writes to `pnpm-workspace.yaml` when they are missing, packs and uploads the project, starts its build on the server and follows it until the configurator is live. Before the upload the server compares the domain model with the deployed one: a model that changed under an already deployed model version is refused with the reason, and needs a new model version and a [migration](?path=/docs/phoenix-migrations--docs). Once the build starts it prints `Follow the build in Studio: <url>`, the build's page in the Studio you signed in through; a sign-in stored by an older CLI has no Studio URL, so sign in again to get the link. `--region` or `--serverUrl` selects the server, as for `login`; `--no-wait` returns as soon as the build starts.
 
-### `phoenix feedback <message>`
+### `phoenix feedback [message]`
 
 Sends feedback about the SDK, the CLI, the documentation or Studio to the Phoenix team. It needs `phoenix login`: the server records the workspace, user and API token of the sign-in, so the message itself needs no introduction.
 
 ```bash
 phoenix feedback "phoenix build reports a missing entity when a module file is empty" --type bug
+phoenix feedback --file report.txt --type bug
 ```
 
-| Flag                   | Env            | Default                       | Description                                          |
-| ---------------------- | -------------- | ----------------------------- | ---------------------------------------------------- |
-| `--type`               | —              | `other`                       | What the feedback is about: `bug`, `idea` or `other` |
-| `--contact`            | —              | —                             | How to reach you, when you want a reply              |
-| `--agent`              | —              | —                             | Name of the coding agent that writes the feedback    |
-| `--projectSlug` / `-p` | `PROJECT_SLUG` | `project` of the spec, if any | Workspace project the feedback is about              |
-| `--region`             | —              | `eu`                          | Phoenix region of the workspace: `eu` or `us`        |
-| `--serverUrl` / `-su`  | —              | the region's server           | Phoenix server URL, for a local or custom server     |
+Pass the message as the argument for a short note, or `--file` for a longer report: the content of the file is the message, read as UTF-8, so quotes, backticks and new lines arrive unchanged. Giving both, or neither, is an error.
+
+| Flag                   | Env            | Default                       | Description                                               |
+| ---------------------- | -------------- | ----------------------------- | --------------------------------------------------------- |
+| `--file`               | —              | —                             | Text file that holds the message, instead of the argument |
+| `--type`               | —              | `other`                       | What the feedback is about: `bug`, `idea` or `other`      |
+| `--contact`            | —              | —                             | How to reach you, when you want a reply                   |
+| `--agent`              | —              | —                             | Name of the coding agent that writes the feedback         |
+| `--projectSlug` / `-p` | `PROJECT_SLUG` | `project` of the spec, if any | Workspace project the feedback is about                   |
+| `--region`             | —              | `eu`                          | Phoenix region of the workspace: `eu` or `us`             |
+| `--serverUrl` / `-su`  | —              | the region's server           | Phoenix server URL, for a local or custom server          |
 
-A message holds at most 5000 characters. Besides the message and the flags, the CLI sends only the SDK version, the operating system and the Node.js version; nothing of the project's files is attached. The project must belong to the signed-in workspace, otherwise the server refuses the feedback; without a project, the feedback is sent on its own.
+A message holds at most 100,000 characters, from the argument or from the file. Besides the message and the flags, the CLI sends only the SDK version, the operating system and the Node.js version; no file of the project is attached, and the Phoenix team reads a build's sources through the build's page in Studio. The project must belong to the signed-in workspace, otherwise the server refuses the feedback; without a project, the feedback is sent on its own.
 
-Generated projects carry the `phoenix-feedback` agent skill. It tells coding agents when to draft feedback, to show you the draft and send it only after you approve it, and what must never go into it: secrets, customer data and the project's source. The command needs a server with API 1.40.0 or newer.
+Generated projects carry the `phoenix-feedback` agent skill. It tells coding agents when to draft feedback, to show you the draft and send it only after you approve it, and how to write a report: the build id with its Studio page link, the live configurator link, what the agent was doing, what happened and what was expected, the exact error or output, the workaround and a condensed conversation log. When you say you are done, or a deploy went live and you confirm the run is finished, the agent asks you to evaluate the run, one question at a time: minutes spent, then a score from 0 to 10 for the agent's guidance, the configurator's functionality, its UX, the quality of the 3D, the UI visuals and the overall result, then your comments. It never picks a score for you and sends nothing when you decline. Secrets, credentials and personal data never go into a message; file paths, spec and code snippets and your own words may, once you approved the draft that contains them. The command needs a server with API 1.40.0 or newer; a message over 5000 characters needs API 1.43.0 or newer.
 
 ## Next Steps
 

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`                      |
@@ -510,7 +513,7 @@ The `application.yaml` file contains global application-level settings. These fi
 | Field                | Type     | Description                                                                                                                                                                                       |
 | -------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `project`            | `string` | Server project `phoenix dev` develops in: a project slug, or `default` for the default project of the signed-in workspace. Read only by the CLI; overridden by `--projectSlug` and `PROJECT_SLUG` |
-| `applicationVersion` | `string` | Semantic version (`x.y.z`) exported as `ApplicationVersion` constant and stored on the deployment record                                                                                          |
+| `applicationVersion` | `string` | Semantic version (`x.y.z`) exported as `ApplicationVersion` constant, stored on the deployment record and named in the banner comment of built bundles                                            |
 | `webComponentTag`    | `string` | Custom HTML web component tag name for embedding                                                                                                                                                  |
 | `pageTitle`          | `string` | Browser page title                                                                                                                                                                                |
 

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

@@ -94,9 +94,10 @@ Studio's **Builds & deployments** page lists your builds and shows which one you
 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).
+- In the terminal, `pnpm phoenix feedback "<message>" --type bug|idea|other` sends it with your sign-in, and `--file <path>` sends a text file instead of the argument. See the [CLI reference](?path=/docs/phoenix-phoenix-cli--docs).
+- On a build's page in Studio, **Download sources** downloads the archive `phoenix deploy` uploaded for that build, so a report only needs to name the build.
 
-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.
+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. A report names the build with its Studio page link and the live configurator, says what the agent was doing, what happened and what it expected, quotes the exact error and ends with a condensed conversation log. Agents are told never to include secrets, credentials or personal data; parts of your project and your own words go in only through a draft you approved. When you are done with the configurator, the agent also asks you, once per conversation, to evaluate the run: minutes spent, then scores from 0 to 10 for the agent's guidance, functionality, UX, 3D quality, UI visuals and the overall result, and your comments. It asks one question at a time, never picks a score for you, tells you the answers go to the Phoenix team, shows the message and sends it only after you approve it.
 
 ## Known limits