@salsita-ai/sdk 0.50.0-develop.5a0bcdee42 → 0.50.0-develop.5ac9723d62

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

@@ -44,11 +44,21 @@ project-root/
 | `invariants/`   | Domain constraints                                                     |
 | `transformers/` | Data transformation logic                                              |
 | `handlers/`     | Event & lifecycle handlers                                             |
-| `webhooks/`     | Webhook implementations                                                |
+| `webhooks/`     | Webhook implementations, entered through `index.ts`                    |
 | `migrations/`   | Data schema migrations (v\*.ts) - auto-created based on model versions |
 | `locales/`      | Locale catalogs (`.po` sources; compiled `.ts`, do not edit)           |
 | `_*`            | Shared code folders at any depth (not auto-imported)                   |
 
+Every file in `components/`, `elements/`, `expressions/`, `actions/`, `invariants/`, `transformers/` and `handlers/`
+(and their `admin/` counterparts) is imported by its location, so its default export must be what that folder's `phx`
+factory returns, or an array of those. A file that exports anything else, such as a plain React component in
+`elements/`, stops the application at start with an `Invalid default export in <file>` error that names the expected
+shape. When several files in `handlers/`, `elements/`, `transformers/`, `components/`, `admin/elements/` and
+`admin/components/` are wrong, the error lists all of them, one numbered line per file. Keep plain components and helpers in a `_*` folder.
+
+With the application-spec pipeline, sync does not write `src/webhooks/index.ts`, and a project without it gets a
+built-in webhook; see [Webhook Entry Point](?path=/docs/phoenix-webhooks--docs#webhook-entry-point).
+
 ### Admin Folders (src/admin/)
 
 The `admin/` folder supports these admin-specific categories:
@@ -70,9 +80,10 @@ a file can share its name with a file in another entity folder.
 
 Two naming limits still apply:
 
-- Transformer file names must be unique across all subfolders of `src/transformers/`, because each transformer
-  registers under its file name. Application-spec projects also treat names that differ only in letter case or dashes
-  as the same name.
+- Transformer file names must be unique across all subfolders of `src/transformers/`, and names that differ only in
+  letter case or dashes count as the same name: each `transformers:` entry of the spec names the file that holds its
+  transformer that way. The transformer the file builds carries the entry's name exactly, as `build('clampWidth')`
+  does for the entry `clampWidth`.
 - Files named `index.ts` inside entity folders are not auto-registered, except in application-spec projects. Give
   entity files descriptive names instead.
 
@@ -126,18 +137,37 @@ export default [CabinetModule, DrawerModule, ShelfModule]
 
 Phoenix auto-flattens both patterns during build. Use array exports when logically grouping related items in one file.
 
-## Dependencies Merging
+## Dependencies
+
+In a project on the application-spec pipeline, `package.json` is the project's own: `phoenix sync`, `phoenix dev` and `phoenix build` never write it. The SDK lists the packages its code imports from the project's install as peer dependencies (React, three.js, MUI, Lingui and others), and the project declares them next to `@salsita-ai/sdk`. [`phoenix deps`](?path=/docs/phoenix-phoenix-cli--docs#phoenix-deps) adds the missing ones and moves out-of-range ones into the SDK's range; run it, then install, after every SDK update. With pnpm, and the same through any other package manager (`npm install`, `npx phoenix deps` with npm):
+
+```bash
+pnpm add @salsita-ai/sdk@<version>
+pnpm phoenix deps
+pnpm install
+pnpm phoenix sync
+```
+
+`phoenix sync`, `phoenix dev` and `phoenix build`, also on the platform when a deploy builds, check `package.json` before they generate any file. When a peer is missing, or declared at a version whose lowest match falls outside the SDK's range, they stop and list each such peer with the range the SDK needs and what `package.json` declares. A peer counts in `dependencies`, `devDependencies` or `optionalDependencies`, and a specifier that is not a version range, such as `workspace:` or `link:`, counts as declared. Add your own dependencies to `package.json` as usual; Phoenix leaves them, the Node.js and package-manager versions and the rest of the file as you wrote them.
 
-When running `phx sync` or `phx build`, Phoenix manages `package.json` dependencies:
+In a project on the legacy pipeline (see [Current and legacy project tooling](?path=/docs/phoenix-phoenix-cli--docs#current-and-legacy-project-tooling)), `phoenix sync` and `phoenix build` merge the SDK's required dependencies into `package.json` instead, at exact versions over the ones you set, and keep every other dependency.
 
-| Behavior              | Description                                                    |
-| --------------------- | -------------------------------------------------------------- |
-| Phoenix deps override | Required Phoenix dependencies override user-specified versions |
-| Versions pinned       | All Phoenix deps use exact versions (no ^ or ~)                |
-| User deps preserved   | Non-conflicting user dependencies are kept                     |
-| Manual deps safe      | Dependencies not in Phoenix's required list remain untouched   |
+### Package manager
 
-To add custom dependencies, add them normally to `package.json`. Phoenix preserves them unless they conflict with required framework dependencies.
+A project installs with any package manager: pnpm, npm, Yarn or Bun. Phoenix writes no package-manager settings and no `packageManager` field; the lockfile, `pnpm-workspace.yaml`, `.npmrc` and `.yarnrc.yml` are the project's own. Run `phoenix` through the package manager the project uses, such as `pnpm phoenix sync` or `npx phoenix sync`.
+
+A project that installs with pnpm 11 needs a `pnpm-workspace.yaml` in its root before the first install. pnpm 11 stops an install until every dependency build script is allowed or denied, and the SDK's dependencies have three. An install that skipped a build script writes a placeholder entry under `allowBuilds` instead of `true` or `false`; replace it, because the platform build stops on it and `phoenix deploy` refuses it. Its default minimum release age also refuses a package published only recently, so the exclusion lets the project install an SDK build on the day it is released; it is optional:
+
+```yaml
+allowBuilds:
+  '@swc/core': true
+  esbuild: true
+  es5-ext: false
+minimumReleaseAgeExclude:
+  - '@salsita-ai/*'
+```
+
+The file is yours to extend, for example to allow the build script of a dependency you add. In a pnpm monorepo, these settings go into the workspace root's `pnpm-workspace.yaml`. [`phoenix deploy`](?path=/docs/phoenix-phoenix-cli--docs#phoenix-deploy) packs `pnpm-lock.yaml` and `pnpm-workspace.yaml` when the project has them, and the platform build, which installs with pnpm, follows them.
 
 ## Global Interfaces
 
@@ -150,9 +180,9 @@ Phoenix generates typed interfaces available globally:
 
 Types are auto-generated in `.phoenix/` from your domain schema:
 
-- `.phoenix/configurator-interface.ts` - Configurator interface types
-- `.phoenix/admin-interface.ts` - Admin interface types
-- `.phoenix/globals.d.ts` - Global type definitions
+- `.phoenix/configurator-globals.ts` - assigns `phx.frontend`
+- `.phoenix/admin-globals.ts` - assigns `phx.frontend.admin`
+- `.phoenix/globals.d.ts` - the type of the `phx` global
 
 Access in code:
 
@@ -170,53 +200,68 @@ type CustomMaterial = Phx['AdminModel']['CustomMaterial']
 
 ### Root Level Files
 
-| File                                                   | Auto-Generated? | Notes                                  |
-| ------------------------------------------------------ | --------------- | -------------------------------------- |
-| `package.json`                                         | Partially       | Dependencies merged, scripts preserved |
-| `tsconfig.json`                                        | Yes             | Managed by Phoenix                     |
-| `eslint.config.js`                                     | Yes             | Managed by Phoenix                     |
-| `prettier.config.js`                                   | Yes             | Managed by Phoenix                     |
-| `.prettierignore`                                      | Yes             | Managed by Phoenix                     |
-| `.linguirc`                                            | Yes             | Managed by Phoenix                     |
-| `.nvmrc`                                               | Yes             | Managed by Phoenix                     |
-| `.gitignore`                                           | Partially       | User entries between markers preserved |
-| `.env`                                                 | No              | Git-ignored, local config              |
-| `.env.example`                                         | No              | Template for env vars                  |
-| `.env.generated`                                       | Yes             | Auto-generated IDs, git-ignored        |
-| `README.md`                                            | No              | Project documentation                  |
-| `AGENTS.md`                                            | Once            | Coding-agent instructions, yours after |
-| `.claude/skills/phoenix*/`, `.agents/skills/phoenix*/` | Yes             | Phoenix agent skills                   |
+| File                                                 | Auto-Generated? | Notes                                         |
+| ---------------------------------------------------- | --------------- | --------------------------------------------- |
+| `package.json`                                       | No              | Yours; see Dependencies                       |
+| `tsconfig.json`                                      | Once            | Yours; see below                              |
+| `eslint.config.js`                                   | Once            | Yours; see below                              |
+| `prettier.config.js`                                 | Once            | Yours; see below                              |
+| `.prettierignore`                                    | No              | Optional and your own; see below              |
+| `pnpm-workspace.yaml`                                | No              | Only with pnpm; see Package manager           |
+| `.gitignore`                                         | Partially       | Only in a git repository; see Markers         |
+| `.env`                                               | No              | Git-ignored, local config                     |
+| `.env.example`                                       | No              | Template for env vars                         |
+| `.env.generated`                                     | Yes             | Optional, git-ignored; see below              |
+| `README.md`                                          | No              | Project documentation                         |
+| `AGENTS.md`                                          | No              | Project-owned instructions; preserved by sync |
+| `.claude/skills/phoenix/`, `.agents/skills/phoenix/` | Yes             | SDK-managed files; see below                  |
 
-### DO NOT EDIT (Fully Auto-Generated)
+With the application-spec pipeline, sync does not write `README.md`, `.env.example`, `.env.ci` or the `README.md` files in `assets/public/` and `assets/private/`. These files are yours to create and edit; sync preserves them. The legacy pipeline writes `README.md`, `.env.example`, `.env.ci` and the asset-folder `README.md` files when they are missing.
 
-- **Everything in `.phoenix/`** - Completely regenerated on each build. The one exception is `.phoenix/variants/`, where a coding agent writes the option files for `phoenix variants`; a rebuild keeps it
-- `tsconfig.json`, `eslint.config.js`, `prettier.config.js`, `.prettierignore`
-- `.linguirc`, `.nvmrc`
-- `src/locales/**/*.ts` - Compiled from `.po` catalogs
-- `.env.generated`
-- `phoenix` and `phoenix-*` skill folders under `.claude/skills/` and `.agents/skills/` — rewritten on every sync with anything else inside them removed, and other `phoenix`-prefixed skill folders are removed; to customise a skill, copy it to a folder whose name does not start with `phoenix`
+Phoenix keeps the generated env file, with the IDs and values of the prepared deployment, in `.phoenix/` unless the project has a `.env.generated` in its root, which then is the one that counts. `phoenix dev` creates no `.env.generated` in the project root; the deployment and environment commands write it there. See [The generated env file](?path=/docs/phoenix-phoenix-cli--docs#the-generated-env-file).
+
+With the application-spec pipeline (see [Current and legacy project tooling](?path=/docs/phoenix-phoenix-cli--docs#current-and-legacy-project-tooling)), Phoenix does not write a `.prettierignore`, and a fresh clone or CI checkout of a project has none. `phoenix check` and `phoenix fix` do not read one: they skip `.phoenix/`, `dist/`, the compiled catalogs in `src/locales/` and `.linguirc` on their own, and the package manager's files in the project root, which belong to whichever package manager the project uses: `pnpm-lock.yaml`, `pnpm-workspace.yaml`, `package-lock.json`, `npm-shrinkwrap.json`, `yarn.lock`, `.yarnrc.yml`, `bun.lock` and `bun.lockb`. A project that runs Prettier directly, as `prettier --check .` or from an editor, can add its own `.prettierignore`. To commit it, add a `!.prettierignore` line after the Phoenix block of `.gitignore`, because that block lists the file. The legacy pipeline writes `.prettierignore` on every sync.
+
+With the application-spec pipeline, the project's TypeScript settings are in `.phoenix/tsconfig.json`, which sync rewrites with the rest of `.phoenix/`. The root `tsconfig.json` is the one editors and tools find: sync writes it only when the project has none, as a single line that extends the generated settings, and it is yours to commit and to add to:
+
+```json
+{ "extends": "./.phoenix/tsconfig.json" }
+```
 
-### Agent Guidance
+The only root `tsconfig.json` sync replaces is the full file earlier SDK versions generated there, recognised by its settings; any other stays as it is. `phoenix dev`, `phoenix build` and the webhook bundle do not resolve `paths` aliases, so an alias added to the root file passes `phoenix check` and fails the build. `phoenix check` type-checks with the root `tsconfig.json`, or with `.phoenix/tsconfig.json` when the project has none. The legacy pipeline writes the full `tsconfig.json` on every sync.
 
-Coding agents (Claude Code, Codex, Cursor) read `AGENTS.md` and the Phoenix agent skills. `AGENTS.md` is written once with the build commands, the do-not-edit list and a pointer to the skills; after that it is yours. The `phoenix`, `phoenix-cli`, `phoenix-feedback` and `phoenix-review` skills carry the SDK conventions, CLI tooling and review checklist, and the `phoenix-create-configurator` skill walks the agent from your product documents and assets to a reviewed configurator in five stages. The `phoenix-variants` skill has the agent show you several options over the dev preview when a decision is a matter of taste, and build the one you pick. Phoenix keeps them in step with the installed SDK, including the reference files inside a skill folder. During the internal beta, a project created from a canary build of the SDK gets one more section in the `phoenix` skill: once per conversation the agent checks for a newer canary and, after telling you, updates the project's SDK and runs `phoenix sync`. Other skill folders are never touched.
+With the application-spec pipeline, sync writes `eslint.config.js` and `prettier.config.js` only when the project has none, each re-exporting the SDK's shared configuration so editors find it. They are yours to commit and to change. The only ones sync replaces are the files earlier SDK versions generated there; any other stays as it is. `phoenix check` and `phoenix fix` lint and format with the project's files, and with the SDK's configurations when a file is missing (see [`phoenix check`](?path=/docs/phoenix-phoenix-cli--docs#phoenix-check)). Sync formats the files it generates in the project root, such as `tsconfig.json`, with the same Prettier configuration, so `phoenix check` accepts them; while the project's configuration cannot be loaded, as before the first install, they get the SDK's settings. The legacy pipeline writes both files on every sync.
 
-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`.
+With the application-spec pipeline, the Lingui configuration is `.phoenix/.linguirc`, which sync rewrites with the rest of `.phoenix/` from `availableLocales` in `spec/application.yaml`. Phoenix passes that file to Lingui every time it extracts or compiles the catalogs and to its Vite builds, so a `.linguirc` in the project root is not read and can be deleted. To run Lingui yourself, name the file: `npx lingui extract --config .phoenix/.linguirc`, from the project root. The legacy pipeline writes `.linguirc` in the project root on every sync.
+
+### DO NOT EDIT (Fully Auto-Generated)
+
+- **Generated files in `.phoenix/`** — Rewritten on each build. In application-spec projects, `.phoenix/workspace/` is project-owned: sync, build and clean preserve it, and deploy includes it in the private source archive rather than build inputs or public assets. Rebuilds also keep `.phoenix/variants/`, which holds variant option files, and `.phoenix/.env.generated`, the generated env file of `phoenix dev`.
+- `src/locales/**/*.ts` - Compiled from `.po` catalogs
+- `.env.generated`
+- The SDK-managed `phoenix` and `phoenix-*` folders under `.claude/skills/` and `.agents/skills/` — sync rewrites the current bundle, removes unrecognized files inside it and deletes retired folders with those prefixes. Keep custom files outside those prefixes. Sync also removes the SDK blocks from legacy `CLAUDE.md` and `.cursor/rules/phoenix.mdc`, preserves surrounding project text, deletes files left empty and removes the legacy review-command files.
 
 ### Markers for Partial Auto-Generation
 
-`.gitignore` preserves custom entries between markers:
+`.gitignore` holds the Phoenix entries between two marker lines. Sync rewrites that block and keeps everything outside it. With the application-spec pipeline the block does not list the files sync writes once, `tsconfig.json`, `eslint.config.js` and `prettier.config.js`, so a project commits them. It ignores generated entries inside `.phoenix/` but leaves `.phoenix/workspace/` available for version control, so working records can travel with a checkout:
 
 ```gitignore
-# phoenix-start
-# ... Phoenix-managed ignores ...
-# phoenix-end
+# ===== BEGIN PHOENIX AUTO-GENERATED =====
+# ... other Phoenix-managed ignores ...
+**/.phoenix/*
+!**/.phoenix/workspace/
+# ===== END PHOENIX AUTO-GENERATED =====
 
-# Your custom ignores below (preserved)
+# Your custom ignores (preserved)
 my-custom-folder/
 ```
 
+With the application-spec pipeline (see [Current and legacy project tooling](?path=/docs/phoenix-phoenix-cli--docs#current-and-legacy-project-tooling)), sync writes `.gitignore` only when the project is inside a git repository: the project folder or one of its parent folders holds a `.git` entry. Outside a repository it neither creates the file nor changes one that is already there. Run `git init` before the first sync, or sync again after it, to get the file. The legacy pipeline writes the file in every project.
+
 ### Safe to Edit
 
+- `.phoenix/workspace/` (application-spec project records and specification sources; include durable records in version control)
+- `docs/` (client documents such as rendered specification PDFs; deploy includes them in the private source archive, not in build inputs or public assets)
 - `src/` (except compiled `src/locales/**/*.ts` files)
 - `spec/`
 - `public/`
@@ -226,7 +271,9 @@ my-custom-folder/
 - `templates/`
 - `package.json` (scripts section, custom dependencies)
 - `.env`, `.env.example`, `.env.ci`
-- `README.md`, `AGENTS.md`
+- `tsconfig.json` (application-spec pipeline; keep it extending `.phoenix/tsconfig.json`)
+- `eslint.config.js`, `prettier.config.js` (application-spec pipeline; sync writes them once, and they are the project's afterwards)
+- `README.md`
 
 ## File Naming Conventions
 
@@ -307,32 +354,32 @@ project-root/
 │
 ├── blender/                       # 3D model source files (Blender)
 │
-├── .phoenix/                      # AUTO-GENERATED (DO NOT EDIT)
-│   ├── domain/                    # Compiled domain specs
-│   │   ├── model/                 # Configurator model
-│   │   └── admin-model/           # Admin model
-│   ├── webhooks/                  # Generated webhook files
-│   │   ├── index.ts
-│   │   └── builders.ts
-│   ├── .swc/                      # SWC transpiled sources
-│   ├── .lingui/                   # Compiled i18n catalogs
-│   ├── variants/                  # Option files of `phoenix variants`, written by coding agents
+├── .phoenix/                      # Generated output, except the project-owned workspace/
+│   ├── workspace/                 # Specification sources and project records, available for version control
+│   ├── variants/                  # Option files of `phoenix variants`; kept by rebuilds, removed by clean
 │   ├── dist/                      # Build output
-│   │   ├── frontend/              # Frontend bundles
-│   │   └── webhooks/              # Webhook bundles
 │   ├── public -> ../public        # Symlink to public
+│   ├── application-spec.json      # The parsed application spec
+│   ├── domain-spec.ts             # Domain model and reflections; assigns `phx.domain`
+│   ├── spec-code.ts               # Code generated from the spec
+│   ├── spec-messages.ts           # Messages of the spec
 │   ├── domain.ts                  # Domain exports
 │   ├── configurator.ts            # Configurator entry
+│   ├── configurator-config.ts     # Configurator configuration
+│   ├── configurator-globals.ts    # Assigns `phx.frontend`
+│   ├── embedded-configurator.ts   # Embedded configurator entry
 │   ├── admin.ts                   # Admin entry
+│   ├── admin-config.ts            # Admin configuration
+│   ├── admin-globals.ts           # Assigns `phx.frontend.admin`
 │   ├── embedded-admin.ts          # Embedded admin entry
+│   ├── webhook.ts                 # Webhook entry
+│   ├── webhook-builders.ts        # Assigns `phx.webhooks`
 │   ├── editor.tsx                 # Editor component
-│   ├── frontend.config.ts         # Frontend configuration
-│   ├── webhooks.config.ts         # Webhook configuration
-│   ├── phoenix.config.ts          # Phoenix framework config
-│   ├── configurator-interface.ts  # Configurator interface types
-│   ├── admin-interface.ts         # Admin interface types
-│   ├── i18n.ts                    # i18n initialization
-│   ├── globals.d.ts               # Global type definitions
+│   ├── frontend.config.ts         # Frontend runtime configuration
+│   ├── webhooks.config.ts         # Webhook runtime configuration
+│   ├── globals.d.ts               # The type of the `phx` global
+│   ├── tsconfig.json              # TypeScript settings, extended by the root tsconfig.json
+│   ├── .linguirc                  # Lingui configuration
 │   ├── index.html                 # Configurator HTML entry
 │   └── admin.html                 # Admin HTML entry
 │
@@ -496,7 +543,7 @@ Assets are split between two locations with different deployment strategies:
 
 Localization files enable multi-language support in your configurator.
 
-Translatable messages are authored in TypeScript and TSX source files using `@lingui/macro`.
+Translatable messages are authored in TypeScript and TSX source files using Lingui's macros: `msg` from `@lingui/core/macro` and `<Trans>` from `@lingui/react/macro`.
 
 Locale catalogs live in `src/locales/<lang>/`. Phoenix creates and updates the `messages.po` source catalogs; edit their `msgstr` values to provide translations. The `messages.ts` files are compiled from those catalogs and must not be edited directly.
 
@@ -511,12 +558,12 @@ The `application.yaml` file contains global application-level settings. These fi
 
 ### Core Application
 
-| 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, 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                                                                                                                                                                                |
+| Field                | Type     | Description                                                                                                                                                                                                                            |
+| -------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `project`            | `string` | Server project for `phoenix dev` and `phoenix deploy`: a project slug, or `default` for the signed-in workspace’s default project. The dev command allows `--projectSlug` and `PROJECT_SLUG` overrides; deploy reads the spec directly |
+| `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                                                                                                                                                                                                                     |
 
 ### Internationalization
 

package/dist/docs/phoenix/quickstart.mdx

@@ -15,7 +15,7 @@ Build a working office desk configurator from an empty folder. You will describe
 
 ## Before you start
 
-Use Node.js 24 and pnpm 11. The tutorial uses the office desk model served by this documentation site at `/models/office-desk.gltf`; download it first. Real client projects normally start from `phoenix init`. This tutorial creates the four essential files by hand so you can see what Phoenix owns.
+Use Node.js 24 and any package manager; the commands below use pnpm, and with pnpm 11 the project also needs the `pnpm-workspace.yaml` in [Package manager](?path=/docs/phoenix-project-structure--docs#package-manager). The tutorial uses the office desk model served by this documentation site at `/models/office-desk.gltf`; download it first. Real client projects normally start from `phoenix init`. This tutorial creates the four essential files by hand so you can see what Phoenix owns.
 
 ## Step 0 — Create the project
 
@@ -40,17 +40,13 @@ Now add these four files.
   "dependencies": {
     "@salsita-ai/sdk": "0.48.0"
   },
-  "devDependencies": {
-    "@lingui/cli": "5.9.5",
-    "@lingui/swc-plugin": "5.11.0"
-  },
   "phoenix": {
     "applicationFlow": true
   }
 }
 ```
 
-Use the SDK version supplied by your team if it differs from the repository's current `0.48.0` version. `phoenix.applicationFlow` selects the application-spec project structure. The first sync uses Lingui while generating the rest of the dependencies, so its CLI and SWC plugin must also be present in the initial install.
+Use the SDK version supplied by your team if it differs from the repository's current `0.48.0` version. `phoenix.applicationFlow` selects the application-spec project structure. The SDK runs its own Lingui, so the SDK is the only dependency you write by hand; `phoenix deps` adds the packages it needs next to it in the install step below. A project started with `phoenix init` gets a `package.json` that already declares them.
 
 ### `.env`
 
@@ -97,17 +93,21 @@ components:
         layout: universal
 ```
 
-Install the SDK, then ask Phoenix to generate the rest of the project:
+Install the SDK, let it declare the packages it needs, such as React, three.js and MUI, install them, then ask Phoenix to generate the rest of the project:
 
 ```sh
 pnpm install
+pnpm phoenix deps
+pnpm install
 pnpm phoenix sync
 ```
 
-`phoenix sync` keeps `spec/` and `src/` as your authored inputs and generates the application shell, scripts, types, and `.phoenix/` implementation. Start the generated development script without a server:
+`phoenix sync` stops while `package.json` lacks one of those packages; after every SDK update, run `phoenix deps` and install again (see [`phoenix deps`](?path=/docs/phoenix-phoenix-cli--docs#phoenix-deps)). With npm, the same steps are `npm install`, `npx phoenix deps`, `npm install` and `npx phoenix sync`.
+
+`phoenix sync` keeps `spec/` and `src/` as your authored inputs and generates the application shell, types, and `.phoenix/` implementation. Start development without a server:
 
 ```sh
-pnpm dev:local
+pnpm phoenix dev --persistence local-storage
 ```
 
 Open the URL printed by the command. The application shell loads with the default `<salsita-configurator>` element and an empty 3D scene.
@@ -267,7 +267,7 @@ export default phx.domain.implementCustomExpressions({
 })
 ```
 
-Application projects receive `phx` as a global. Storybook examples cannot rely on that project environment, so the complete example below imports it from `../../.phoenix/phx.js`; that import is the only intentional difference.
+Application projects receive `phx` as a global. Storybook examples cannot rely on that project environment, so the example's files import it from `../../.phoenix/phx.js`; a project leaves that import out, the only intentional difference.
 
 After sync, the property panel offers Grey, Black, and White. Selecting one updates the domain field, recomputes `$frameColor`, and smoothly changes the real `metalMaterial` in the model. Explore the individual pieces in [Attribute List Selector](?path=/docs/controls-select-attribute-listselect--docs) and [Material Transition](?path=/docs/3d-scene-materials-transition--docs).
 
@@ -1092,8 +1092,6 @@ components:
 ### ./src/expressions/table.ts
 
 ```ts
-import { phx } from '../../.phoenix/phx.js'
-
 const FRAME_COLORS = {
   Grey: '#6f7378',
   Black: '#202124',

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

@@ -1,6 +1,6 @@
 # SDK Builder Workflow
 
-An SDK-builder workspace lets you build one configurator from the application spec and develop and deploy it from your terminal. You don't need a repository, a CI pipeline, project keys or a development key. You write `spec/` and `src/`, run `phoenix dev` to develop and `phoenix deploy` to go live, and the platform builds and deploys the project for you.
+An SDK-builder workspace lets you build configurators from application specs and develop and deploy them from your terminal. You don't need a repository, a CI pipeline, project keys or a development key. You write `spec/` and `src/`, run `phoenix dev` to develop and `phoenix deploy` to go live, and the platform builds and deploys the project for you.
 
 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.
 
@@ -8,9 +8,9 @@ Your workspace's Studio shows the setup, the link to your configurator and the s
 
 ## Before you start
 
-- **Package access:** `@salsita-ai/sdk` is public on npm; `npx` and `pnpm install` download it without a registry token.
+- **Package access:** `@salsita-ai/sdk` is public on npm; any package manager downloads 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.
+- **Tools:** Node.js and a package manager. The commands below use pnpm; with npm, run `npm install` and `npx phoenix …` instead, with Yarn `yarn phoenix …`, with Bun `bunx phoenix …`.
 - **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
@@ -22,13 +22,13 @@ pnpm install
 pnpm phoenix sync
 ```
 
-`phoenix init [folder]` writes the starter project: `package.json`, `pnpm-workspace.yaml` and the starter spec, `spec/application.yaml` and `spec/configurator.yaml`, which describe one box you can resize and recolour. The starter depends on the same SDK version as the CLI that created it. `phoenix sync` then adds the rest of the project: package scripts, webhooks, README and lint config.
+`phoenix init [folder]` writes the starter project: `package.json` and the starter spec, `spec/application.yaml` and `spec/configurator.yaml`, which describe one box you can resize and recolour. The starter depends on the same SDK version as the CLI that created it and on the packages the SDK requires next to it (React, three.js, MUI, Lingui and the others, with their type packages), with ESLint and Prettier at the versions the SDK uses itself. Its `package.json` has the `dev`, `build`, `deploy`, `check` and `fix` scripts, which are yours to change. `phoenix sync` then adds the TypeScript, lint and formatting config and the other generated files described in [Project Structure](?path=/docs/phoenix-project-structure--docs#root-level-files). It writes no webhook code: a project without `src/webhooks/index.ts` gets a built-in webhook (see [Webhook Entry Point](?path=/docs/phoenix-webhooks--docs#webhook-entry-point)). It writes a `.gitignore` only when the folder is inside a git repository; run `git init` before the first sync, or sync again after it, to get the file.
 
-`init` only writes these files: it asks nothing and contacts no server. It refuses a folder that already has a `spec/` folder. A `package.json` already in the folder is kept, as long as it depends on the SDK.
+`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, and gains only the entries it lacks (see [Starting a New Project](?path=/docs/phoenix-phoenix-cli--docs#starting-a-new-project)).
 
-`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.
+Phoenix writes no package-manager settings. With pnpm 11, add a `pnpm-workspace.yaml` that allows the build scripts of the SDK's dependencies before the first install; [Package manager](?path=/docs/phoenix-project-structure--docs#package-manager) has the file.
 
-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.
+The starter `spec/application.yaml` begins with `project: default`, which means the default project of the workspace you sign in to. To develop and deploy another project in that workspace, set `project` to its actual slug. Staff can create or move projects into your workspace; choose the project in Studio's **Project** selector to see its overview, builds, environment variables and allowed sites.
 
 ## 2. Sign in
 
@@ -36,7 +36,7 @@ The starter `spec/application.yaml` begins with `project: default`, which means
 pnpm phoenix login <workspace>
 ```
 
-`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.
+`phoenix login` opens Studio, where you name the token and approve the sign-in. Only a super admin of the workspace can open Studio, so only a super admin can approve it. The CLI suggests `phoenix CLI on <computer>`; a name of your own, such as its purpose 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.
 
@@ -44,12 +44,12 @@ The CLI stores the token in `~/.phoenix/credentials.json`, readable only by you,
 
 `login`, `logout` and `deploy` follow the region, not the `SERVER_URL` in the project's `.env`. `dev` follows the region too when `.env` has no `SERVER_URL`:
 
-| Flag                  | Default                              | Description                                      |
-| --------------------- | ------------------------------------ | ------------------------------------------------ |
-| `--region`            | `eu`                                 | Phoenix region of the workspace: `eu` or `us`    |
-| `--serverUrl` / `-su` | the region's server                  | Phoenix server URL, for a local or custom server |
-| `--studioUrl`         | the workspace's Studio in the region | Studio URL of the workspace (`login`)            |
-| `--open`              | `true`                               | Open the approval page in your browser (`login`) |
+| Flag                   | Default                              | Description                                      |
+| ---------------------- | ------------------------------------ | ------------------------------------------------ |
+| `--region`             | `eu`                                 | Phoenix region of the workspace: `eu` or `us`    |
+| `--serverUrl` / `--su` | the region's server                  | Phoenix server URL, for a local or custom server |
+| `--studioUrl`          | the workspace's Studio in the region | Studio URL of the workspace (`login`)            |
+| `--open`               | `true`                               | Open the approval page in your browser (`login`) |
 
 ## 3. Develop
 
@@ -59,13 +59,9 @@ 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)). 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.
+Every user who signs the CLI in gets their own development environment, so a teammate (a super admin of the workspace, like you) who clones the project and signs in doesn't overwrite your schema or take over your webhooks. The development environment is separate from `production`: nothing you do in `phoenix dev` changes the live configurator.
 
-`pnpm dev:local` still runs the project without any server, with state kept in the browser.
-
-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.
+`pnpm phoenix dev --persistence local-storage` still runs the project without any server, with state kept in the browser.
 
 ## 4. Deploy
 
@@ -76,16 +72,18 @@ 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`, `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.
+2. It packs the project files: the `.yaml` files in `spec`, everything in `src`, `mocks`, `assets`, `public` and `templates`, and `package.json`, `tsconfig.json`, `pnpm-lock.yaml`, `pnpm-workspace.yaml`, `.gitignore`, `CLAUDE.md` and `.cursor/rules/phoenix.mdc`. Project-owned `.phoenix/workspace/` records and the client documents in `docs/` also travel in the private source archive; they are excluded from build inputs and public assets. Other `.phoenix` contents, every `node_modules` and `__generated` folder, every `.DS_Store` and `._*` file and every `.env` and `.env.*` file are left out.
 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.
+On the server, the install runs pnpm. It follows your `pnpm-lock.yaml` and `pnpm-workspace.yaml` when the project has them, so a pnpm project gets the same build scripts and package versions as on your computer; without them, pnpm resolves `package.json` with the settings the SDK needs. 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.
 
-Studio's **Builds & deployments** page lists your builds and shows which one your configurator serves. Each build shows its progress, its error and the full build log while it runs.
+Studio's **Builds & deployments** page lists your builds, 20 to a page, and shows which one your configurator serves. Filter it to the live build or to the builds that failed. Each build shows its progress, its error and the full build log while it runs, and who deployed it with which CLI token.
+
+**Rebuild** on a build's page builds the files uploaded with that build again, with your environment variables as they are now, without a new `phoenix deploy`. Use it after changing a variable, or when a build failed for a reason on our side. If the rebuild succeeds it goes live, so rebuilding an older build rolls production back to it.
 
 `phoenix deploy` refuses symlinks, hard-linked files and other special files among the project files, because builds only accept regular files. Packing uses the system `tar`, which macOS, Linux and Windows 10 or later all include. The build runner checks the uploaded archive again and keeps only project files, so a file outside the list above never reaches the build.
 
@@ -95,16 +93,15 @@ 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, 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. 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.
+- 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.
 
 ## 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.
+- You can deploy once the selected project's production setup is ready. Until then, `phoenix deploy` tells you that project's setup is incomplete.
 - 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.
+- Each project uses its `production` environment and has a development environment per user. Creating or moving projects requires staff.
+- `phoenix deploy` reads `project` from the application spec. Omitted or `default` selects the workspace’s original default project. After moving a project into another workspace, sign in to that workspace and set the actual moved project slug before deploying. Targeting a nondefault project requires server API 1.61.0 or newer; the CLI stops before upload if the server cannot confirm support.
 - Only `phoenix dev` works from the sign-in. `phoenix deployment:prepare-dev` still needs the `.env` block of a Studio development environment.
 - Every deploy uploads the whole project; there are no incremental uploads.
-- Your own environment variables can't use platform names such as `LAMBDA_FUNCTION_NAME` or the `AWS_` prefix. A deploy that sets them fails before it registers.
+- Your own environment variables are set in Studio under Environment, by a super admin of the workspace, and apply from the next deploy. After a change, **Redeploy #N now** there rebuilds your live build with the new values, without a new `phoenix deploy`; it appears once your own build is live. `phoenix dev` doesn't receive them: your development environment has its own variables. A build reads them from `process.env`; a webhook reads the ones the spec declares under `env.webhook`, through `phx.webhooksEnv` (see [Webhooks](?path=/docs/phoenix-webhooks--docs)). They can't use platform names such as `LAMBDA_FUNCTION_NAME`, the `AWS_` prefix, the identity provider settings such as `CLERK_API_KEY`, or names the CLI and the deploy tooling read themselves, such as `SERVER_URL` or `NODE_OPTIONS`; Studio refuses those names.
+- Only super admins of a workspace can open its Studio. Admins and users see a page that says so.