@salsita-ai/sdk 0.50.0-develop.f16492b14e → 0.50.0-develop.f354d3576d

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

@@ -327,7 +327,7 @@ components:
           $read: $description # This will auto-generate $description expression
 ```
 
-The code generator will automatically create an expression with the same name and infer the return type based on usage context.
+The code generator creates an expression with the same name and infers its type from where it is read. The inferred expression is a custom expression like any declared one: implement it in `src/expressions/`, otherwise the application reports `MISSING_IMPLEMENTATION` when it loads.
 
 The type of an expression must share values with the type every component expects where it is read, and with its declared type. An expression declared as a number and read into a `title`, or one read both into a `title` and into `offsetX`, has no value its implementation could return, so the build reports `EXPRESSION_READ_TYPE_CONFLICT` at the expression and names each place it is read. A type given only as `tsType` is not checked here.
 
@@ -469,11 +469,9 @@ export default phx.domain.implementCustomExpressions({
 })
 ```
 
-> **Removed:** `$codeRef` with an inline `code:` block was previously documented for this purpose.
-> It was never evaluated — the parser carried it through as plain data — so specs using it silently
-> shipped an object where a number was expected. It now reports
-> `ENHANCED_JSON_VALUE_CODE_REF_NOT_SUPPORTED`. Replace `$codeRef: { code: 4 * 25.4 }` with
-> `$eval: '4 * 25.4'`.
+> `$codeRef` with an inline `code:` block is not supported and reports
+> `ENHANCED_JSON_VALUE_CODE_REF_NOT_SUPPORTED`. Write `$eval: '4 * 25.4'` instead of
+> `$codeRef: { code: 4 * 25.4 }`.
 
 ## Aliases
 
@@ -530,19 +528,21 @@ invariants:
   ChairParts: # Applied to all chair parts
     materialRequired:
       type: 'materialMissing'
-      severity: 'error'
+      severity: 'warning'
       message: 'Material must be selected for all chair parts'
 
 components:
   ChairParts: # Applied to all chair parts
-    materialSelector:
+    price:
       main:
-        value:
-          $bind: materialId
+        price:
+          $read: $price
 ```
 
 This approach reduces duplication and ensures consistent behavior across related entities.
 
+The invariant is a `warning` because a chair part without a material is a configuration in progress, not an impossible one: the user can keep configuring, and only finalizing is blocked until every part has a material. A `fatal` severity would reject every change while a part has no material, including the change that adds the part. See [Violation Severity](#violation-severity).
+
 ## Relations
 
 Relations connect your entities into a tree that represents both structure and ownership. This tree drives what appears under what in the scene, how selection and navigation move up and down, and which items get deleted together when you remove a parent. It must be a proper tree (no cycles) and every entity needs to belong to it.
@@ -647,10 +647,12 @@ invariants:
         - 'aspectRatioInvalid'
 ```
 
-Implementation returns an array of violations. Each violation object requires `type`, `severity`, and `message`. Optionally, you can add `controlViolationPriority` (same as in static YAML) and `formatControlViolationMessage` — a function that receives the current `stateEmission` and an `{ i18n }` context, enabling runtime-computed, translatable messages:
+Implementation returns an array of violations. Each violation object requires `type` and `severity`; `message` is optional and is the text users see for the violation. Optionally, you can add `controlViolationPriority` (same as in static YAML) and `formatControlViolationMessage` — a function that receives the current `stateEmission` and an `{ i18n }` context, enabling runtime-computed, translatable messages:
 
 ```typescript
 // src/invariants/cabinet.ts
+import { msg } from '@lingui/core/macro'
+
 export default phx.domain.implementCustomInvariants({
   Cabinet: {
     materialConstraints: self => {
@@ -718,11 +720,14 @@ For a full working example of priority-based filtering and runtime message forma
 
 ### Violation Severity
 
-Different severities have different behaviors:
+The severity decides what a violation blocks. An invariant takes one of four severities:
+
+- **`fatal`**: the change that causes the violation is never committed. It does not reach the scene, the undo stack or the saved configuration, and controls disable the options that would cause it, with the violation message as the hint.
+- **`fixable`**: rejected the same way as `fatal`. Use it for a situation your project repairs: a [transformer](?path=/docs/other-features-transformers--docs) that reacts to the violation returns the updates that fix it, so the change commits without the violation. Phoenix repairs nothing on its own; without such a transformer, `fixable` behaves exactly like `fatal`.
+- **`warning`**: the change is committed and saved, but the configuration cannot be finalized while the violation lasts. Its message shows on the finalize action.
+- **`notice`**: the change is committed and saved, and nothing is blocked. Its message shows on the finalize action as information.
 
-- **Warning**: Shows a warning but allows the configuration to continue
-- **Error**: Prevents certain actions but doesn't block finalization
-- **Fatal**: Prevents finalizing the configuration
+If the initial state already has a `fatal` or `fixable` violation, the transformers run once on it; when the violation remains, the configurator does not start. See the [Violation Severity example](?path=/docs/other-features-violation-severity--docs) to try each level.
 
 ### Common types
 

package/dist/docs/phoenix/expression-context.mdx

@@ -66,7 +66,7 @@ The `mode` property indicates the current operational context of the configurato
 
 Projections are SDK-defined expressions that provide reusable functionality across projects. They expose complex calculations and relationships that would otherwise require custom implementation.
 
-The Phoenix SDK includes projection systems for common tasks. Each projection system handles a specific domain like geometry, pricing, or layout. Projects can use these projections without implementing the underlying logic.
+The Phoenix SDK includes projection systems for common tasks. Each projection system handles one domain: positions, sketching, collisions, spatial constraints, snapping and projected entities, the `*Projections` members of the context listed above. Projects can use these projections without implementing the underlying logic.
 
 **Sketching Projections Example**:
 
@@ -82,7 +82,6 @@ export default phx.domain.implementCustomExpressions({
       const sketchingKey = 'floorplan'
       try {
         const shape = ctx.sketchingProjections.getEntityLine(line.id, state, sketchingKey)
-        const connections = ctx.sketchingProjections.getConnections(state, sketchingKey)
         return {
           isTerminal: shape.isTerminal,
           hasStartConnection: shape.start.connection !== null,
@@ -96,34 +95,9 @@ export default phx.domain.implementCustomExpressions({
 })
 ```
 
-This example shows different types of calculations with sketching projections. Connection checking tells you how shapes connect to each other. The traverse method lets you walk through connected shapes. Area calculations use coordinate data to compute geometric properties.
+This example reads how a line connects to the rest of the sketch: `getEntityLine` returns the line's shape with its start and end connections. `getSketching(state, key)` returns all shapes and connections of a sketch, and `getEntityShape` and `getEntityRectangle` return the shape of one entity.
 
-Each projection method handles error cases when entities aren't part of the sketching system. This makes expressions safe to use across different entity types.
-
-**Future Projection Systems (Hypothetical)**:
-
-> **Note**: The following projection systems are hypothetical and not yet implemented. They illustrate how the projection pattern could extend to other domains.
-
-Phoenix can extend projections to other domains. Future projection systems might handle pricing, layout, or other complex calculations:
-
-```typescript
-// HYPOTHETICAL: These projection systems do not exist yet
-export default phx.domain.implementCustomExpressions({
-  Product: {
-    // Pricing projections - calculate complex pricing across projects
-    $finalPrice: (product, state, ctx) => {
-      return ctx.pricingProjections?.calculatePrice(product.id, state)
-    },
-
-    // Layout projections - spatial arrangement calculations
-    $spatialRelations: (product, state, ctx) => {
-      return ctx.layoutProjections?.getNeighbors(product.id, state)
-    },
-  },
-})
-```
-
-These examples show how projections could work in other areas. A pricing projection might calculate discounts, taxes, and complex pricing rules. A layout projection might determine spatial arrangements and object relationships.
+A projection method throws when the entity has no shape of that kind in the sketching, so the expression catches the error and returns a default.
 
 Projections provide tested, optimized solutions for common problems that many configurators need to solve. They let you leverage sophisticated SDK functionality without reimplementing complex logic in each project.
 

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

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

package/dist/docs/phoenix/localization.mdx

@@ -19,13 +19,13 @@ Phoenix provides a localization system built on **Lingui** that enables multi-la
 
 The localization architecture has two layers that work together automatically. **SDK translations** provide the built-in platform UI components, error messages, and system text. **Project catalogs** contain your domain-specific translations for entities, validation messages, and custom UI components.
 
-These translation sources merge automatically at runtime. The system uses lazy loading where translation catalogs compile to TypeScript modules and load only when needed.
+These translation sources merge automatically at runtime. The translation catalogs compile to TypeScript modules that are bundled with the application.
 
 The translation workflow follows a clear pattern: Lingui extracts translatable strings from your code using `msg()` macros and `$msg` syntax, translators work with standard `.po` files for each language, those files compile into TypeScript modules for your application, and the SDK and project catalogs merge into a unified translation system during initialization.
 
 ## Getting Your Project Set Up
 
-Phoenix uses the **phx-cli** to automatically manage localization setup. When you configure `availableLocales` in your `spec/application.yaml`, the CLI creates and maintains the necessary i18n structure.
+The Phoenix CLI manages the localization setup. When you list the project's languages in the top-level `availableLocales` key of a spec file, such as `spec/application.yaml`, the CLI creates and maintains the necessary i18n structure.
 
 ### Enabling Localization
 
@@ -39,7 +39,7 @@ availableLocales:
   - cs
 ```
 
-Running `phx sync` automatically creates the i18n directory structure:
+Running `pnpm phoenix sync` creates the i18n directory structure:
 
 ```
 project-root/
@@ -57,68 +57,79 @@ project-root/
 ├── spec/
 │   └── application.yaml           # Contains availableLocales
 ├── .phoenix/
-│   ├── .lingui/                   # Compiled i18n catalogs
-│   └── i18n.ts                    # Auto-generated i18n initialization
+│   ├── .linguirc                  # Generated Lingui configuration
+│   └── domain-spec.ts             # Generated code that loads and merges the catalogs
 └── package.json
 ```
 
 **Key directories:**
 
-- `src/locales/<lang>/` - Auto-generated `.po` files for translators, compiled `.ts` files
-- `.phoenix/i18n.ts` - Auto-generated i18n initialization with catalog merging
+- `src/locales/<lang>/` - Generated `.po` files for translators, compiled `.ts` files
+- `.phoenix/domain-spec.ts` - Generated code that imports each locale's compiled catalog and merges it with the SDK's
 
-### Auto-Generated i18n Initialization
+### Generated i18n Initialization
 
-The `.phoenix/i18n.ts` file is auto-generated and handles catalog merging automatically:
+The generated `.phoenix/domain-spec.ts` imports the compiled catalog of every locale in `availableLocales` and merges it with the SDK catalog:
 
 ```typescript
-// .phoenix/i18n.ts (AUTO-GENERATED - DO NOT EDIT)
-import { mergeCatalogs, sdkCatalog } from '@salsita-ai/sdk/i18n'
-
+// .phoenix/domain-spec.ts (excerpt, generated - do not edit)
 import { messages as cs } from '../src/locales/cs/messages.js'
 import { messages as de } from '../src/locales/de/messages.js'
 import { messages as en } from '../src/locales/en/messages.js'
 
-export const catalog = { en, de, cs }
-export const availableLocales = Object.keys(catalog) as Array<keyof typeof catalog>
-
-// Automatically merges SDK and project catalogs
+const catalog = {
+  en,
+  de,
+  cs,
+}
+// Merges SDK and project catalogs
 const messages = mergeCatalogs([sdkCatalog, catalog])
 
-export const createI18n = () =>
-  setupI18n({
-    messages,
-    locale: 'en',
-  })
+export const createI18n = () => setupI18n({ messages, locale: 'en' })
+```
+
+### Choosing the Language
+
+`availableLocales` decides which catalogs the project compiles and ships. The language the configurator shows is chosen separately:
+
+- **Starting language.** The configurator starts in the host's `locale` property (the `locale` attribute of the web component), `en` by default. When there is no catalog for it, the configurator falls back as described in [Locale Fallback Configuration](#locale-fallback-configuration).
+- **Language switch.** The toolbar's language button and the menu's language action offer the locales in `applicationConfig.availableLocales` on the root entity (`['en']` without it). A project layout builds its own switch with `phx.frontend.useLocaleSwitch()`, see [Configurator Interface → Hooks for a Project Layout](?path=/docs/phoenix-configurator-interface--docs#hooks-for-a-project-layout).
+
+```yaml
+components:
+  Product: # the root entity type
+    applicationConfig:
+      default:
+        availableLocales:
+          - en
+          - de
+          - cs
 ```
 
 ### Overriding SDK Translations
 
 You can customize or override any SDK translation by adding the same message ID to your project's `.po` files. The `mergeCatalogs` function prioritizes project translations over SDK translations when merging.
 
-For example, to customize the finalize button text, add this to your `locales/en/messages.po`:
+The SDK's message IDs start with `sdk.`. For example, to customize the finalize button text and the save-template button, add this to your `src/locales/en/messages.po`:
 
 ```po
-#: src/configurator/ui/finalize/FinalizeButton.tsx:42
-#: src/configurator/ui/finalize/FinalizeButton.tsx:56
-msgid "Finalize"
+msgid "sdk.layout.sidebar.finalizePage.label"
 msgstr "Complete Order"
 
-#: src/configurator/ui/controls/save-configuration/SaveConfigurationButton.tsx:23
-msgid "Save Configuration"
+msgid "sdk.layout.button.saveTemplate.label"
 msgstr "Save My Design"
 ```
 
-After running `pnpm lingui:compile`, your custom translations will override the default SDK translations. This allows you to:
+Once the catalogs are compiled again, by `pnpm phoenix sync`, `pnpm phoenix build` or `pnpm phoenix dev --withLingui`, your custom translations override the default SDK translations. This allows you to:
 
 - Customize terminology to match your brand
 - Provide more context-specific wording
 - Adapt translations for your target audience
 - Maintain consistency with your existing product language
 
-**Frontend integration**: the generated `.phoenix` code creates the i18n service from `.phoenix/i18n.ts` and registers
-it with the application, so there is nothing to wire by hand. The languages come from `availableLocales` in
-`spec/application.yaml`.
+**Frontend integration**: the generated `.phoenix` code creates the i18n service from the catalogs in
+`.phoenix/domain-spec.ts` and registers it with the application, so there is nothing to wire by hand. The catalogs come
+from the top-level `availableLocales`.
 
 ## Working with YAML Domain Specifications
 
@@ -243,12 +254,11 @@ Admin users can switch between different languages to input translations for eac
 
 ```typescript
 import { Stack } from '@mui/material'
-import type { AdminModel } from 'project-domain'
 
 import { LanguageSwitcher, MultilingualTextValueInput, TextValueInput } from '@salsita-ai/sdk/react'
 import { PropertyContainer } from '@salsita-ai/sdk/ui'
 
-export const MaterialSidebar = (props: { id: AdminModel.Material['id'] }) => {
+export const MaterialSidebar = (props: { id: Phx['AdminModel']['Material']['id'] }) => {
   const { id } = props
 
   return (
@@ -329,11 +339,11 @@ publishedData: {
 
 ### Configurator Consumption
 
-In your configurator, use the `resolveLocalizable` function or `useLocalizable` hook to display the appropriate language:
+In your configurator, use the `phx.frontend.useLocalizable` hook or the resolver from `phx.frontend.useResolveLocalizable()` to display the appropriate language:
 
 ```typescript
 // In expressions
-const customExpressions = implementCustomExpressions({
+const customExpressions = phx.domain.implementCustomExpressions({
   Product: {
     $materialName: (product, state, ctx) => {
       const material = ctx.publishedData.materials.find(m => m.id === product.materialId)
@@ -344,7 +354,7 @@ const customExpressions = implementCustomExpressions({
 
 // In React components
 function MaterialDisplay({ materialData }) {
-  const name = useLocalizable(materialData.name)
+  const name = phx.frontend.useLocalizable(materialData.name)
   return <span>{name}</span>
 }
 ```
@@ -369,13 +379,11 @@ function ProductHeader({ product }) {
 }
 ```
 
-Sometimes you need the actual translated string for use in component logic or HTML attributes, rather than rendering it directly. That's where the `useLocalizable` hook comes in handy:
+Sometimes you need the actual translated string for use in component logic or HTML attributes, rather than rendering it directly. That's where the `phx.frontend.useLocalizable` hook comes in handy:
 
 ```tsx
-import { useLocalizable } from '@salsita-ai/sdk/react'
-
 function ValidationMessage({ invariant }) {
-  const message = useLocalizable(invariant.message)
+  const message = phx.frontend.useLocalizable(invariant.message)
 
   return (
     <div className="error" title={message}>
@@ -385,13 +393,13 @@ function ValidationMessage({ invariant }) {
 }
 ```
 
-For more complex scenarios where you need to resolve translations dynamically (like when sorting lists by translated names), there's `useResolveLocalizable`. This gives you a resolver function that you can use however you need:
+For more complex scenarios where you need to resolve translations dynamically (like when sorting lists by translated names), there's `phx.frontend.useResolveLocalizable`. This gives you a resolver function that you can use however you need:
 
 ```tsx
-import { useResolveLocalizable } from '@salsita-ai/sdk/react'
+import { LocalizableMessage } from '@salsita-ai/sdk/react'
 
 function EntityList({ entities }) {
-  const resolve = useResolveLocalizable()
+  const resolve = phx.frontend.useResolveLocalizable()
 
   const sortedEntities = entities.sort((a, b) => resolve(a.displayName).localeCompare(resolve(b.displayName)))
 
@@ -427,6 +435,8 @@ function WelcomeMessage({ userName, itemCount }) {
 
 The localization system isn't just for the frontend — it works in server-side webhook handlers too. PDF and email tasks render React templates with the same Lingui macros (`<Trans>` from `@lingui/react/macro`, `msg` from `@lingui/core/macro`) you already use in UI components. The task context exposes `ctx.resolveLocalizable` already bound to the request locale and domain fallback chain, and the React builders use it for localizable subjects, attachment filenames, bodies, headers, footers, and watermark text.
 
+The request locale is the one the frontend passes as the fourth argument of `apiClient.finalize(configurationId, finalizationId, finalizeData, locale, frontendData)`, where `apiClient` comes from `phx.frontend.useAuthorizedClient()`. Pass the active locale, for example `phx.frontend.useLocaleSwitch().locale`, so the webhook renders in the language the user sees. Without a locale the webhook renders in `en`.
+
 ### In the handler
 
 Use the `msg` template tag for one-off strings you pass into builder methods:
@@ -513,7 +523,7 @@ Legacy Handlebars PDF/email tasks remain supported for backwards compatibility,
 
 ## Your Day-to-Day Development Workflow
 
-The **phx-cli** handles most translation workflow automatically. The basic cycle is: sync to extract strings, translate `.po` files, build to compile.
+The Phoenix CLI handles most of the translation workflow. The basic cycle is: sync to extract and compile the strings, translate the `.po` files, then sync or build again to compile the translations.
 
 ### Development Workflow
 
@@ -521,7 +531,7 @@ For day-to-day development, opt into the Lingui watcher with `--withLingui` (or
 
 ```bash
 # Start development server with hot reload and i18n watch
-phx dev --withLingui
+pnpm phoenix dev --withLingui
 
 # This automatically:
 # - Watches for new translatable strings
@@ -529,27 +539,27 @@ phx dev --withLingui
 # - Compiles translations on change
 ```
 
-Lingui watching is disabled by default, and `phx dev` logs a warning when it is not enabled.
+Lingui watching is disabled by default: `phoenix dev` then only creates the catalogs that are missing at startup, leaves existing `.po` and compiled files as they are, and logs a warning.
 
-When you add new translatable content (using `$msg` in YAML or `msg()` in code), run `phx sync` to extract strings:
+When you add new translatable content (using `$msg` in YAML or `msg()` in code), run `phoenix sync` to extract and compile the strings:
 
 ```bash
-# Sync domain specs and extract i18n strings
-phx sync
+# Sync domain specs, extract and compile i18n strings
+pnpm phoenix sync
 ```
 
-This updates the `.po` files in `src/locales/<lang>/messages.po`. Translators fill in the `msgstr` values for each `msgid`.
+This updates the `.po` files in `src/locales/<lang>/messages.po` and the compiled `.ts` files beside them. Translators fill in the `msgstr` values for each `msgid`.
 
 ### Production Build
 
 When you're ready to ship:
 
 ```bash
-# Build for production (includes i18n compilation)
-phx build
+# Build for production (extracts and compiles the i18n catalogs)
+pnpm phoenix build
 ```
 
-With the application-spec pipeline, `phx dev` and `phx build` compile the Lingui macros in your frontend code with the SDK's own Lingui macro plugin and the configuration in `.phoenix/.linguirc`, so the project installs no Babel macro packages for them (see [Current and legacy project tooling](?path=/docs/phoenix-phoenix-cli--docs#current-and-legacy-project-tooling)).
+With the application-spec pipeline, `phoenix dev` and `phoenix build` compile the Lingui macros in your frontend code with the SDK's own Lingui macro plugin and the configuration in `.phoenix/.linguirc`, so the project installs no Babel macro packages for them (see [Current and legacy project tooling](?path=/docs/phoenix-phoenix-cli--docs#current-and-legacy-project-tooling)).
 
 ### Translation Files
 
@@ -599,7 +609,7 @@ User locale: de-AT (Austrian German)
 └─ Translation in en? → Use it (default fallback)
 ```
 
-The fallback configuration is generated by `phx sync` and stored in `.phoenix/.linguirc` (in the project root on the legacy pipeline; see [Current and legacy project tooling](?path=/docs/phoenix-phoenix-cli--docs#current-and-legacy-project-tooling)). You don't need to configure this manually - it's handled automatically based on your `availableLocales` in `spec/application.yaml`.
+The fallback configuration is generated by `phoenix sync` and stored in `.phoenix/.linguirc` (in the project root on the legacy pipeline; see [Current and legacy project tooling](?path=/docs/phoenix-phoenix-cli--docs#current-and-legacy-project-tooling)). You don't need to configure this manually - it's handled automatically based on your top-level `availableLocales`.
 
 ## What We Learned
 

package/dist/docs/phoenix/migration-guide.mdx

@@ -352,33 +352,32 @@ grep -r "from '\.\/" src/
 
 **Error:** Changes to `.phoenix/` files are overwritten
 
-**Solution:** Never commit `.phoenix/` contents. Add to `.gitignore`:
+**Solution:** Keep generated files out of version control. Application-spec projects can commit their project-owned `.phoenix/workspace/` records; sync writes the appropriate ignore rules. Remove any custom rule that ignores the entire `.phoenix/` directory if you want to version those records. See [Project Structure](?path=/docs/phoenix-project-structure--docs#markers-for-partial-auto-generation) for the managed block and ownership rules.
 
-```
-.phoenix/
-```
-
-If you accidentally modified generated files, delete and regenerate:
+If you accidentally modified generated files, clean and regenerate them with the CLI. In application-spec projects this preserves workspace records:
 
 ```bash
-rm -rf .phoenix/
+pnpm phoenix clean
 pnpm phoenix build
 ```
 
+The legacy pipeline has no workspace-preservation contract; see [Phoenix CLI](?path=/docs/phoenix-phoenix-cli--docs#phoenix-clean).
+
 **Note:** Mock templates are no longer auto-applied on Editor load. Users must manually select and apply templates (changed in v0.36.0).
 
 ### .gitignore Conflicts
 
 **Error:** Custom gitignore entries disappear after Phoenix update
 
-**Solution:** Place custom entries between Phoenix markers:
+**Solution:** Place custom entries outside the Phoenix markers. Sync replaces the generated block and preserves everything outside it:
 
 ```gitignore
-# phoenix-start
+# ===== BEGIN PHOENIX AUTO-GENERATED =====
 # Auto-generated by Phoenix - DO NOT EDIT
-.phoenix/
+**/.phoenix/*
+!**/.phoenix/workspace/
 .env.generated
-# phoenix-end
+# ===== END PHOENIX AUTO-GENERATED =====
 
 # Your custom entries below
 my-custom-folder/

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

@@ -40,7 +40,7 @@ pnpm phoenix dev
 3. Adds the `dev`, `build`, `deploy`, `check` and `fix` scripts to `package.json` (see [Project Scripts](#project-scripts)). A script the project already has under one of those names keeps its command.
 4. Writes a starter spec (`spec/application.yaml`, `spec/configurator.yaml`) with one resizable, recolorable box, and switches `package.json` to the application-spec pipeline.
 
-The next steps it prints use the package manager you ran it with, or name none when it cannot tell. It asks nothing, writes no `.env` and contacts no Phoenix server. It does send the operational telemetry described below unless telemetry is disabled. `phoenix sync` then generates every other project file, including the agent skills described in [Project Structure](?path=/docs/phoenix-project-structure--docs). The `.gitignore` is among them only when the folder is inside a git repository, so run `git init` before the first sync, or sync again after it.
+The next steps it prints use the package manager you ran it with, or name none when it cannot tell. It asks nothing, writes no `.env` and contacts no Phoenix server. It does send the operational telemetry described below unless telemetry is disabled. `phoenix sync` then generates every other project file, as described in [Project Structure](?path=/docs/phoenix-project-structure--docs). The `.gitignore` is among them only when the folder is inside a git repository, so run `git init` before the first sync, or sync again after it.
 
 ### CLI telemetry
 
@@ -187,7 +187,7 @@ A project has one generated env file. Phoenix keeps it in `.phoenix/`, as `.phoe
 - `phoenix dev` reads and writes `.phoenix/.env.generated` in a project without a root `.env.generated`, and creates no file in the project root. In a project that has a root `.env.generated`, it reads and writes that file and `.phoenix/.env.generated` is not used.
 - The deployment and environment commands (`deployment:prepare`, `deployment:prepare-dev`, `deployment:prepare-local`, `deployment:build-envs` and the others with an `--outFile` option) write `.env.generated` in the project root unless `--outFile` or `OUT_FILE` names another file. Deploy pipelines read it there. Once one of them has written it, `phoenix dev` and `phoenix build` use it.
 - Everything that reads environment variables follows the same rule: the root `.env.generated` when it exists, otherwise `.phoenix/.env.generated`. The two files are never merged.
-- `phoenix clean` removes `.phoenix/` and with it `.phoenix/.env.generated`; the next `phoenix dev` prepares the development deployment again. A root `.env.generated` stays.
+- `phoenix clean` removes the generated contents of `.phoenix/`, including `.phoenix/.env.generated`; the next `phoenix dev` prepares the development deployment again. A root `.env.generated` stays.
 - `phoenix dev` starts on the deployment the file names, and prepares a new one when the file was written for another project, environment or server, when the spec registers something on the server the deployment was not prepared with (the domain model, the published data schema, the auth hook, the roles that may create configurations, or the assistant), and on `--force`. A running `phoenix dev` does not prepare again after such a change: it logs an error that asks for a restart.
 - Asset contents do not trigger preparation. After changing uploaded assets, restart with `phoenix dev --force` to prepare and upload them again.
 
@@ -266,7 +266,7 @@ A build pipeline that receives the source archive of a [`phoenix deploy`](#phoen
 - it refuses an archive over 200 MB, one that extracts to more than 1 GB, or one with more than 100,000 files;
 - it refuses links, special files, absolute paths, paths that leave the folder, names with control characters, and entries that repeat or collide with an earlier one;
 - it refuses an archive it cannot read to the end, such as a truncated upload;
-- it extracts only project files and reports the entries it left out, including the optional `conversation.log` that deploy keeps in the private archive for review.
+- it extracts only project files and reports the entries it left out, including the optional `conversation.log`, the `.phoenix/workspace/` records and the `docs/` documents that deploy keeps in the private archive for review.
 
 `<folder>` must be new or empty. When the command refuses an archive, it removes the folder, so a partly extracted project is never built.
 
@@ -436,7 +436,7 @@ Set initial values from a local production build with roughly 5–10% headroom t
 
 ### `phoenix clean`
 
-Removes `.phoenix/` and regenerates all project files from scratch. It installs nothing and leaves `node_modules/` as it is; to reinstall too, delete `node_modules/` and install with your package manager. In a project on the legacy pipeline (see [Current and legacy project tooling](#current-and-legacy-project-tooling)), `phoenix clean` also removes `node_modules/` and runs `pnpm install`. Use this when:
+Removes generated output and regenerates the project files. In application-spec projects it preserves project-owned records under `.phoenix/workspace/`, installs nothing and leaves `node_modules/` as it is; to reinstall too, delete `node_modules/` and install with your package manager. In a project on the legacy pipeline (see [Current and legacy project tooling](#current-and-legacy-project-tooling)), `phoenix clean` removes the whole `.phoenix/` folder and `node_modules/` and runs `pnpm install`. Use this when:
 
 - Generated files are corrupted or out of sync
 - After major SDK version upgrades
@@ -567,7 +567,7 @@ phoenix screenshot -o preview.png -w 1920 --height 1080
 
 ### `phoenix variants`
 
-Show several options over the configurator and wait for your pick. It is built for coding agents: when a decision is a matter of taste, such as the edge of a table top, how glossy a finish is or where a control sits, the agent writes one file per option, you choose in the browser, and the command hands your answer back to the agent.
+Compare options such as a table-top edge, surface gloss or control placement in the configurator. Write one file per option, choose in the browser, and the command returns the selection.
 
 ```bash
 phoenix variants .phoenix/variants/table-edge --title 'Which edge suits the table?' --description 'Only the edge of the top differs.'
@@ -642,8 +642,6 @@ Known limits:
 - Binary assets, CSS files, locale catalog changes, dependency changes and edits requiring a full application restart are unsupported.
 - Storybook `story-dev` has no variant previews. A project on the legacy pipeline has no variant previews; the command says so and exits.
 
-Generated projects carry the `phoenix` agent skill, whose linked Variants guide tells coding agents when to offer options, how to write each kind and what to do with your answer.
-
 ## SDK Development
 
 ### `phoenix link`
@@ -758,7 +756,7 @@ 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 name the token and approve the sign-in (use `--no-open` to only print the link). Only a super admin of the workspace can open its Studio, so only a super admin can sign the CLI in. 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.
+1. Opens Studio, where you name the token and approve the sign-in (use `--no-open` to only print the link). Only a super admin of the workspace can open its Studio, so only a super admin can sign the CLI in. 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 sign-ins 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 with the name you approved, and sends the browser back to Studio, which confirms the sign-in.
 
@@ -783,11 +781,22 @@ Revokes the token on the server and removes it from the credentials file. `--reg
 
 ### `phoenix deploy`
 
-Validates the spec, packs and uploads the project, starts its build on the server and follows it until the configurator is live. 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. After `Your configurator is live at <url>` it prints one line for coding agents, which tells them to offer the run evaluation in the Feedback guide linked from the `phoenix` skill once you have nothing more to build; you can ignore it when you run the command yourself. `--region` or `--serverUrl` selects the server, as for `login`; `--no-wait` returns as soon as the build starts.
+Validates the spec, 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). Before packing, it also refuses a `pnpm-workspace.yaml` whose `allowBuilds` leaves a package undecided, an entry that is neither `true` nor `false`, such as the placeholder pnpm 11 writes for a build script it skipped, because the platform build stops on it; the message names the packages. 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. It prints `Your configurator is live at <url>` when deployment succeeds. `--region` or `--serverUrl` selects the server, as for `login`; `--no-wait` returns as soon as the build starts.
+
+A follow-up evaluation hint is addressed to coding agents; you can ignore it when running the command manually.
+
+Project-owned records under `.phoenix/workspace/` and client documents under `docs/`, such as the
+rendered specification PDFs, are included in the private source archive and can be downloaded with
+the build's sources; deploy reports how many `docs/` files it includes. Local sync, build and clean
+keep both. The build extractor leaves them out, so
+they are not application build inputs or public assets. They use the archive's existing size limits
+and exclusions for dependencies, generated files, environment files and macOS metadata. The
+`.phoenix`, `.phoenix/workspace` and `docs` paths must be real directories, and linked or special
+files are rejected. Keep their contents suitable for everyone authorized to download the sources.
 
 To keep the conversation that led to a build, place a reviewed UTF-8 transcript in `conversation.log` at the project root before deploying. Deploy automatically includes it in the private source archive. Download the build's sources from Studio to read it; access is the same as for the rest of that build's sources. The build extractor skips the log, so it is not an application build input or a public asset. Missing logs produce a warning and deployment continues. Directories, links and special files at that path are rejected.
 
-The Phoenix agent skill explains how to prepare the transcript: prefer a native session export; otherwise mark a reconstruction as incomplete. Preserve available user/assistant messages and tool calls, cap individual tool results at 16 KiB with explicit truncation markers, and reference images rather than embedding them. Include the agent, export time, source and known omissions. Review and redact credentials or unrelated sensitive content before approving upload. The CLI uploads the file as supplied; it does not collect agent history, redact content, check freshness or verify completeness. Remove the file from the project root to deploy without it. The log counts toward the source archive's existing size limits; there is no separate conversation upload or viewer.
+Review and redact credentials or unrelated sensitive content before uploading the transcript. The CLI uploads the file as supplied; it does not collect conversation history, redact content, check freshness or verify completeness. Remove the file from the project root to deploy without it. The log counts toward the source archive's existing size limits; there is no separate conversation upload or viewer.
 
 ### `phoenix feedback [message]`
 
@@ -805,14 +814,14 @@ Pass the message as the argument for a short note, or `--file` for a longer repo
 | `--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         |
+| `--agent`              | —              | —                             | Name of the coding agent submitting 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 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` agent skill. Its linked Feedback guide 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.
+Review the message before sending and omit secrets, credentials and personal data. 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