@salsita-ai/sdk 0.50.0-develop.b5468d6828 → 0.50.0-develop.b929a82a82

package/dist/application-spec/generate-application/code/templates/skills/features/state/slices.js

@@ -0,0 +1,48 @@
+import{createPhoenixFeatureGuide as e}from"../../guide.js";let t=`A cabinet label follows a drag frame by frame, while the order summary ignores previews and rejected changes. The label returns a tuple of numbers, so it re-renders only when one changes; returning \`cabinet.$shelves\` would re-render it on every pointer move.
+
+\`\`\`tsx
+// src/elements/CabinetWidthLabel.tsx
+import { Trans } from '@lingui/react/macro'
+import { Typography } from '@mui/material'
+
+export default phx.frontend.createCustomPhoenixEntityElement('CabinetWidthLabel', ({ entityId }) => {
+  if (!phx.domain.model.Cabinet.isId(entityId)) {
+    throw new Error('CabinetWidthLabel is attached to a Cabinet only.')
+  }
+
+  const [width, shelves] = phx.frontend.useRenderedEntitySelector(
+    entityId,
+    cabinet => [cabinet.width, cabinet.$shelves.length] as const,
+    []
+  )
+
+  return (
+    <Typography variant="caption">
+      <Trans>
+        {width} mm, {shelves} shelves
+      </Trans>
+    </Typography>
+  )
+})
+\`\`\`
+
+\`\`\`tsx
+// src/_shared/OrderSummary.tsx: committed only, so a dragged-across position never shows a price
+import { Trans } from '@lingui/react/macro'
+import { Typography } from '@mui/material'
+
+export const OrderSummary = () => {
+  const [cabinets, total] = phx.frontend.useRootEntitySelector(
+    kitchen => [kitchen.$cabinets.length, kitchen.$totalPrice] as const,
+    []
+  )
+
+  return (
+    <Typography>
+      <Trans>
+        {cabinets} cabinets, {total}
+      </Trans>
+    </Typography>
+  )
+}
+\`\`\``;export const generatePhoenixStateSlicesFeature=()=>e({path:"features/state/slices.md",title:"State slices",summary:"The rendered, committed and potentially invalid slices and the hooks that read them; read when UI shows configuration state, such as a live label during a drag or a price summary.",whenToUse:"Read when UI shows configuration state: choosing between a live preview and the committed configuration, picking a reading hook, or keeping an element from re-rendering on every drag frame. Writing changes belongs to [Updates and dry runs](updates.md).",capabilities:"### The three slices\n\nThe store keeps three slices. Each emits a state emission `{ kind, state, validity }`; an update emission adds `previousState` and `updates`.\n\n- **`rendered`** — every valid state, committed or staged: gesture previews and hover included. The scene renders from it. An invalid staged state is not emitted, so the preview stays at the last valid one.\n- **`committed`** — every valid committed state: what is saved, what undo records and what finalizing checks.\n- **`potentiallyInvalid`** — every attempted commit, rejected ones included. No reading hook targets it; configurator messages report its rejections ([Messages](../custom-layout/messages.md)).\n\n`state` is `{ rootEntityId, rootEntityType, entities, ephemeralRecords }`:\n\n- `entities` are raw entities: own fields only, no `$` expressions or relations. Read the `$` entity through the entity hooks below.\n- `ephemeralRecords` hold navigation, view, tool, selection, hover and drag state. They are never saved, and a commit that changes only them makes no undo step. Read them with the hooks of [Application states](../application-states/index.md), not by scanning records.\n\n### Choose a slice\n\n- **Rendered** — what must follow a gesture while it happens: a dimension label during a drag, an in-scene overlay, a live preview of the value being changed.\n- **Committed** — what must not flicker with previews or show a state nobody accepted: price, summaries, step completion, enabling Next or Finalize, analytics, data sent to a server.\n- Never mix them in one value: a price computed from rendered state shows prices of positions a drag only passed through.\n\n### Reading hooks\n\nEach pair reads the committed slice first, the rendered slice second:\n\n- `phx.frontend.useStoreSelector(select, deps)` \xb7 `phx.frontend.useRenderedSelector(select, deps)` — `select(emission)` returns any value. An optional third argument `false` pauses updates, for hidden UI.\n- `phx.frontend.useEntitySelector(id, select, deps)` \xb7 `phx.frontend.useRenderedEntitySelector(id, select, deps)` — `select($entity, emission)` for one entity.\n- `phx.frontend.useRootEntitySelector(select, deps)` \xb7 `phx.frontend.useRenderedRootEntitySelector(select, deps)` — the same for the root entity.\n- `phx.frontend.useEntityState(id)` — the committed `$` entity. It takes the id only and has no rendered twin on `phx.frontend`; use `useRenderedEntitySelector`.\n- `phx.frontend.useRootEntityState()` \xb7 `phx.frontend.useRootEntityRenderedState()` — the root `$` entity.\n- `phx.frontend.useRootEntityId()` \xb7 `phx.frontend.useRootEntityRenderedId()` — the root entity's id.\n- `phx.frontend.useCommittedState()` \xb7 `phx.frontend.useRenderedState()` — the whole `state`.\n- `phx.frontend.useCommittedSlice()` \xb7 `phx.frontend.useRenderedSlice()` — the whole emission, `validity` included. Neither takes an argument.\n- `phx.frontend.useStoreSelector$(select, deps)` \xb7 `phx.frontend.useRenderedSelector$(select, deps)` — an RxJS observable of the selected value, for work outside rendering such as a debounced request in an effect. It replays the current value and emits for every emission, equal or not: add `distinctUntilChanged()`.\n\nThe entity hooks throw for an id the state does not contain: take ids from the slice you read, and drop an id once its entity is deleted. In event handlers and async flows, read `storeSystem.stateSlices.committed.value.state` from `phx.frontend.useDomain()` when the code runs; a value captured during render may be stale by then.\n\n### Keep re-renders narrow\n\n- A selector runs for every emission of its slice; the component re-renders only when the result changes. Results compare shallowly: a primitive by value, an object or array member by member, each member by reference.\n- Return primitives, ids, counts or tuples of them. A relation such as `$shelves`, and anything built from it, is a new array on every state, so returning it re-renders every time: return its `length` or its ids.\n- The whole-object hooks (`useEntityState`, `useRootEntityState`, `useRootEntityRenderedState`, the state and slice hooks) return a new object for every state. Their component re-renders on every commit, and on every drag frame for the rendered ones. Keep them for small panels; use a selector in elements mounted per entity or shown during gestures.\n- List in `deps` every component value the selector reads, as for `useMemo`; the entity selectors add the id themselves. A missing dependency keeps a stale selector.\n- Treat every returned value as immutable. Move expensive derivations into [expressions](../domain-model/expressions.md), which are cached per state, rather than computing them in selectors.",example:t,documentation:'Read each with `pnpm phoenix docs -r <path>`:\n\n- `docs/performance/render-isolation.mdx` — rendered entity selectors that keep a large scene smooth while dragging, and why their results must compare equal.\n- `docs/phoenix/state-management.mdx` — slices, the emission lifecycle, validity results and the selector hooks.\n- `docs/phoenix/configurator-interface.mdx` — "Core Hooks": the slice, selector and entity hooks with a sample call each.',phxMembers:["frontend.useStoreSelector","frontend.useRenderedSelector","frontend.useStoreSelector$","frontend.useRenderedSelector$","frontend.useEntitySelector","frontend.useRenderedEntitySelector","frontend.useRootEntitySelector","frontend.useRenderedRootEntitySelector","frontend.useEntityState","frontend.useRootEntityState","frontend.useRootEntityRenderedState","frontend.useRootEntityId","frontend.useRootEntityRenderedId","frontend.useCommittedState","frontend.useRenderedState","frontend.useCommittedSlice","frontend.useRenderedSlice"]});

package/dist/application-spec/generate-application/code/templates/skills/features/state/state.d.ts

@@ -0,0 +1,3 @@
+import { type PhoenixGuide } from '../../guide.js';
+/** The state index followed by its guides: reading the store, writing it, and how violations surface. */
+export declare const generatePhoenixStateGuides: () => readonly PhoenixGuide[];

package/dist/application-spec/generate-application/code/templates/skills/features/state/state.js

@@ -0,0 +1 @@
+import{createPhoenixIndexGuide as t}from"../../guide.js";import{generatePhoenixStateSlicesFeature as e}from"./slices.js";import{generatePhoenixUpdatesFeature as o}from"./updates.js";import{generatePhoenixViolationsFeature as a}from"./violations.js";export const generatePhoenixStateGuides=()=>{let n=[e(),o(),a()];return[t({path:"features/state/index.md",title:"State",summary:"Reading and writing the configuration at runtime and how violations surface; read when UI or a handler reads or changes the configuration, or must reflect what a change breaks.",intro:"The configurator keeps the configuration in a store. The slices hold the states UI can read; updates stage and commit changes, and dry runs test them first; the violations of those states disable control options, become hints and block finalizing. Read only the guide for the task. Declaring invariants belongs to [Validation and repair](../domain-model/validation-and-repair.md), transformers to [Transformers](../domain-model/transformers.md), and the controls that write for you to [Domain controls](../domain-controls/index.md).",guides:n,notes:[]}),...n]};

package/dist/application-spec/generate-application/code/templates/skills/features/state/updates.d.ts

@@ -0,0 +1,3 @@
+import { type PhoenixGuide } from '../../guide.js';
+/** Writing the configuration: update kinds, the stage and commit cycle, dry runs, undo steps and update guards. */
+export declare const generatePhoenixUpdatesFeature: () => PhoenixGuide;

package/dist/application-spec/generate-application/code/templates/skills/features/state/updates.js

@@ -0,0 +1,39 @@
+import{createPhoenixFeatureGuide as e}from"../../guide.js";let t=`A width scrubber no configured control covers: every position is previewed, the release commits once, and the drag is one undo step. A width that breaks an invariant is not previewed, so the cabinet stays at the last valid width; a rejected release reverts the preview and becomes a message.
+
+\`\`\`tsx
+// src/_shared/WidthScrubber.tsx
+import { Slider } from '@mui/material'
+
+export const WidthScrubber = ({ cabinetId }: { readonly cabinetId: Cabinet['id'] }) => {
+  const { storeSystem } = phx.frontend.useDomain()
+  const width = phx.frontend.useRenderedEntitySelector(cabinetId, cabinet => cabinet.width, [])
+
+  const preview = (value: number | number[]) => {
+    if (typeof value !== 'number') {
+      return
+    }
+
+    // Replaces the previous preview: the whole change from the committed state
+    storeSystem.stage([
+      phx.frontend.updates.DomainEntityModification({
+        entityId: cabinetId,
+        stateDelta: { width: value },
+        updateTag: 'cabinet.scrubWidth',
+      }),
+    ])
+  }
+
+  return (
+    <Slider
+      value={width}
+      min={400}
+      max={1200}
+      step={10}
+      onChange={(_event, value) => preview(value)}
+      onChangeCommitted={() => storeSystem.commit()}
+    />
+  )
+}
+\`\`\`
+
+A discrete action is one call, such as \`storeSystem.stageAndCommit([phx.frontend.updates.EntityDeletion({ entityId, updateTag: 'cabinet.remove' })])\`. When configurator users pick it among options, a control with a dry run is the better home.`;export const generatePhoenixUpdatesFeature=()=>e({path:"features/state/updates.md",title:"Updates and dry runs",summary:"Update kinds, the stage, commit and rollback cycle, dry runs and undo steps; read when code writes the configuration or a transformer must stay cheap.",whenToUse:"Read when code writes the configuration outside a configured control, previews a change during a gesture, dry-runs a change to decide whether to offer it, needs ids for new entities, or narrows updates in a transformer.",capabilities:"### Choose the write path\n\n- Write through the control hooks of [Custom controls](../domain-controls/custom-controls.md) first: they build updates, dry-run options, stage gestures and commit. `phx.frontend.useUpdateControl(fixableViolations)` returns `prepare(updates)`, which dry-runs any updates and returns `{ disabled, hints, update, stage, trace }`.\n- Use the store system only when no control hook fits: a gesture you drive yourself, a write from a toolbar action, dialog or handler, a confirmation before a commit, or work that waits for a gesture to end.\n- `phx.frontend.useDomain()` returns the stable domain systems (`storeSystem`, `domain`, `undoSystem`, `navigationSystem`, `componentReader`, the projections), safe in dependency arrays. Navigation and selection changes belong to [Application states](../application-states/index.md).\n- Transformers return update arrays and never write to the store ([Transformers](../domain-model/transformers.md)).\n\n### Build updates\n\nEach `phx.frontend.updates` factory takes one object with an `updateTag` naming the change, such as `'cabinet.scrubWidth'`; `withTag` filters, the guards below and analytics read it. An optional localizable `hint` reaches configurator users as a side-effect message on commit: set it when a transformer changes something they did not touch.\n\n- `DomainEntityModification({ entityId, stateDelta, updateTag })` — sets some of the entity's own fields, never `id` or `type`.\n- `DomainEntityCreation({ entity, parentId, updateTag })` — adds a complete entity, optionally to the reference component instance named by `collection`. Build it with `phx.domain.createRecipe({ type, … })`, which fills the spec defaults, and replace its placeholder id. For children from recipes, prefer `phx.frontend.useCookRecipes`, which assigns ids.\n- `DomainEntityReplacement({ entityId, replacementEntity, keepChildren, updateTag })` — swaps in a new entity with a new id; `keepChildren: false` deletes its composed children.\n- `EntityDeletion({ entityId, updateTag })` — removes an entity; built-in transformers delete its composed children and prune references to it.\n- `ComponentModification({ componentInstance, writableState, updateTag })` — writes a component's writable state, as built-in controls do; it throws for a state the component rejects.\n\n`phx.frontend.getIdSequence(entities, pendingUpdates)` returns `{ nextId(type) }`, above every existing id and every id created or replaced in `pendingUpdates`. Draw a batch's ids from one sequence: two sequences from one state return the same id. In a transformer, use the context's `getIdSequence()`.\n\n### Stage, commit and roll back\n\n- `storeSystem.stage(updates)` runs transformers and invariants against the committed state and previews a valid result in the rendered slice; an invalid stage previews nothing. Each call replaces the staged updates: stage the whole change from the committed state, never a delta.\n- `storeSystem.commit()` prepares the staged updates again, runs the `onBeforeCommit` hooks and commits a valid result. A rejected commit keeps the committed state, resets the preview and reaches configurator messages through the potentially invalid slice.\n- `storeSystem.rollback()` drops the staged updates and their preview.\n- `storeSystem.stageAndCommit(updates)` writes a discrete action in one step: a click, a toggle, an add.\n- `storeSystem.hasStagedUpdates` is `true` while a staged change is pending; a hover stages nothing. It is a getter, not a subscription: check it before snapshotting the committed state, such as for an export.\n- `storeSystem.onBeforeCommit((emission, emit) => …)` runs before every commit and returns its unregister function; register it in an effect. Returning `false` holds the commit, such as to confirm a destructive change: the preview rolls back, and `emit()` commits that emission later. The hooks run again then, so let it through.\n- Leave `storeSystem.commitPrepared` to the SDK's own operations.\n\n### Dry runs\n\n- `storeSystem.prepareStateEmission(updates, storeSystem.stateSlices.committed.value.state, 'committed')` returns the emission a commit would produce, `{ state, validity, updates, … }`, without emitting it. Controls dry-run every option this way ([Violations](violations.md)).\n- Transformers and invariants run in a dry run exactly as in a commit, with the kind `'committed'`, so a transformer cannot tell them apart: `onEmissionsOfKind(['committed'])` skips staged previews but not dry runs.\n- Every mounted control dry-runs each option after every commit: ten options run the transformer pipeline and every invariant ten times per change. Staging runs them on every frame of a gesture.\n- Keep transformers pure and cheap: no requests, storage, analytics or React state.\n\n### Undo steps\n\n- One commit that changes entities is one undo step, transformer updates included, so a transformer's repair undoes with the change that caused it.\n- A commit that changes only navigation, view, tool or selection state makes no step.\n- Staged frames make no steps, but `stageAndCommit` on every keystroke or slider tick makes one each: stage while the value changes and commit once, on release or blur. [Toolbar actions](../custom-layout/toolbar-actions.md) covers the undo and redo buttons.\n\n### Update guards\n\nNarrow updates in a transformer (`ctx.updates`, `overrideAllUpdates`) or in an `onBeforeCommit` emission:\n\n- `phx.frontend.isCreateEntityUpdate(update, types)`, `phx.frontend.isReplaceEntityUpdate(update, types)` and `phx.frontend.isDeleteEntityUpdate(update, types)` — an entity of `types` added or replaced from a recipe, or removed by a built-in delete control. They check the SDK's own tags, so your own `EntityDeletion` does not match.\n- `(update, types, instanceName)` guards — the write of one built-in control on one component instance: `phx.frontend.isAttributeSelectionUpdate`, `phx.frontend.isAttributeSwitchUpdate`, `phx.frontend.isTextValueUpdate`, `phx.frontend.isSwatchSelectionUpdate`, `phx.frontend.isGenericDimensionUpdate`, `phx.frontend.isDistanceDimensionUpdate`, `phx.frontend.isAngleDimensionUpdate`.\n- A built-in step at priority `Infinity` turns component writes into entity modifications. Transformers default to that priority and run after it, and `onBeforeCommit` sees its result, so the control guards never match there. Give such a transformer a finite `priority` in its `transformers:` entry, or filter with `when.entity([...]).modified({ atFields })`.",example:t,documentation:'Read each with `pnpm phoenix docs -r <path>`:\n\n- `docs/other-features/transformers.mdx` — the transformer guide, including a component trigger registered with a finite priority.\n- `docs/complex-use-cases/navigation-guard.mdx` — an `onBeforeCommit` hook that holds a commit until configurator users confirm.\n- `docs/phoenix/state-management.mdx` — the stage, commit and rollback cycle and the emission kinds.\n- `docs/phoenix/configurator-interface.mdx` — "Updates Factory" and "Update Type Guards": every factory member, a control that dry-runs its updates, and the guards.',phxMembers:["frontend.updates","frontend.getIdSequence","frontend.useDomain","frontend.isCreateEntityUpdate","frontend.isReplaceEntityUpdate","frontend.isDeleteEntityUpdate","frontend.isAngleDimensionUpdate","frontend.isDistanceDimensionUpdate","frontend.isGenericDimensionUpdate","frontend.isAttributeSelectionUpdate","frontend.isAttributeSwitchUpdate","frontend.isTextValueUpdate","frontend.isSwatchSelectionUpdate"]});

package/dist/application-spec/generate-application/code/templates/skills/features/state/violations.d.ts

@@ -0,0 +1,3 @@
+import { type PhoenixGuide } from '../../guide.js';
+/** How violations disable control options, become hint text and gate Next and Finalize at runtime. */
+export declare const generatePhoenixViolationsFeature: () => PhoenixGuide;

package/dist/application-spec/generate-application/code/templates/skills/features/state/violations.js

@@ -0,0 +1,36 @@
+import{createPhoenixFeatureGuide as t}from"../../guide.js";let e=`A missing purpose is a \`warning\`: the change stays, the purpose step's Next waits for it, and finalizing waits for it like for every other warning. Its priority puts its text alone in the finalize hint while lower-ranked warnings also hold.
+
+\`\`\`yaml
+# spec/invariants.yaml
+invariants:
+  KitchenRange:
+    purposeRequired:
+      type: purpose-required
+      severity: warning
+      message:
+        $msg: Choose a purpose before continuing
+      controlViolationPriority: 10
+\`\`\`
+
+\`\`\`tsx
+// src/_shared/PurposeNextButton.tsx
+import { Trans } from '@lingui/react/macro'
+import { Button, Tooltip } from '@mui/material'
+
+export const PurposeNextButton = () => {
+  const { canGoNext, next } = phx.frontend.useStepNavigation()
+  const { violations } = phx.frontend.useFinalizeViolations()
+  const resolve = phx.frontend.useResolveLocalizable()
+  const missing = violations?.find(({ violation }) => violation.type === 'purpose-required')
+
+  return (
+    <Tooltip title={missing ? resolve(missing.violation.message ?? missing.violation.type) : ''}>
+      <span>
+        <Button variant="contained" disabled={!canGoNext || missing !== undefined} onClick={() => next()}>
+          <Trans>Next</Trans>
+        </Button>
+      </span>
+    </Tooltip>
+  )
+}
+\`\`\``;export const generatePhoenixViolationsFeature=()=>t({path:"features/state/violations.md",title:"Violations",summary:"How violations disable control options, become hints and gate finalizing; read when a control or button must reflect what a change would break or what still blocks the configuration.",whenToUse:"Read when a control must show what an option would break, when hint text needs ranking or custom wording, or when Next or Finalize must wait for the configuration's problems. Declaring invariants, choosing a severity and repairing with transformers belong to [Validation and repair](../domain-model/validation-and-repair.md).",capabilities:"### Where violations surface\n\n- **Controls** — every option is dry-run ([Updates and dry runs](updates.md#dry-runs)). An option is `disabled` when its dry run, after transformers, still has a `fatal` or `fixable` violation or an invariant throws; its hint is the text of those violations. A `warning` or `notice` never disables an option.\n- **Messages** — a rejected commit reaches the potentially invalid slice, and its violations become configurator messages. They include every violation of that state, notices and warnings too, so check `violation.severity`. [Messages](../custom-layout/messages.md) owns showing them.\n- **Finalizing** — reads the committed state: a `warning` or a failed save blocks it, a `notice` only adds text.\n\n### Control violations\n\n`phx.frontend.useControlViolations(ignoredTypes)` returns a function from a prepared emission to `{ disabled, hints, violations }`:\n\n- no violation — enabled, no hint;\n- `notice` or `warning` — enabled, no hint, `violations` listed;\n- `fatal` or `fixable` — disabled, `hints` from those violations, `violations` all of them;\n- an invariant that throws — disabled, no hint. A transformer that throws is not caught: the control's render throws.\n\nPrefer `phx.frontend.useUpdateControl` from [Custom controls](../domain-controls/custom-controls.md), which prepares the emission and applies this mapping. Call `useControlViolations` yourself only for an emission you prepared, such as a dialog listing from `violations` what an option would break.\n\n`fixableViolations`, an argument of every control hook and of both update hooks, only removes those violation types from the hint text: the option stays disabled. List a type when another part of the UI explains it. To keep an option enabled, repair the violation in a transformer, so its dry run ends valid.\n\n### Hint text\n\n- Hints keep only the violations with the highest `controlViolationPriority` (default 0), drop duplicates and join several as sentences. Rank a root cause above its consequences, such as size above color.\n- The highest priority is found before ignored types are removed, so ignoring the top-ranked violation leaves no hint rather than the next one.\n- Set `controlViolationPriority` on a YAML invariant or on a violation returned from TypeScript. The finalize hint applies the same ranking.\n- A TypeScript violation may add `formatControlViolationMessage(emission, { i18n })`: a hint naming the attempted value, or `null` to drop this hint, such as for all but one of identical violations. Messages keep using `message`.\n- `message` is optional on a TypeScript violation, and messages fall back to its type. In YAML it is a string or `$msg`; [Localization](../localization.md) covers the catalogs.\n- `phx.frontend.useMapViolationHints(ignoreTypes?)` returns `(violations, emission) => string`, the hint text these rules make from any violations. For the committed state, take the emission from `phx.frontend.useCommittedSlice()`.\n\n### Finalize and step gating\n\n`phx.frontend.useFinalizeViolations()` returns `{ disabled, hints, violations }` for the committed state:\n\n- `disabled` while a `warning` holds or the last save failed; `hints` then says why, and `violations` is `undefined` for a failed save;\n- a `notice` leaves it enabled, with its text in `hints`;\n- `violations` lists the committed state's violations, `undefined` when there are none.\n\n`phx.frontend.useStateValidity()` returns the validity of the last committed emission: `{ valid: true, severity: null }`, or `{ valid: true, severity: 'warning' | 'notice', entityViolations }`. A `fatal` or `fixable` violation is never committed, so a `warning` is the problem the committed state can still have. Its type also lists the rejected results: narrow on `severity` before reading `entityViolations`.\n\n- Gate Finalize with `disabled` and show `hints` beside it; `useFinalizeActions` already returns both ([Finalization actions](../custom-layout/finalization-actions.md)).\n- Next enforces nothing by itself ([Tabs and steps](../custom-layout/tabs-and-steps.md)). Gate it with `disabled` and show `hints`. `useStateValidity().severity === 'warning'` holds it for the configuration alone, ignoring a failed save, and gives no text.\n- When a step waits only for its own problems, filter `violations` by their types and word them with `useMapViolationHints`.",example:e,documentation:'Read each with `pnpm phoenix docs -r <path>`:\n\n- `docs/other-features/violation-messages.mdx` — `controlViolationPriority` and `formatControlViolationMessage` worked through four ranked violations, with localized hint text.\n- `docs/other-features/violation-severity.mdx` — what each severity does to controls and finalizing; [Validation and repair](../domain-model/validation-and-repair.md) owns choosing one.\n- `docs/complex-use-cases/filtered-controls-with-fix-dialog.mdx` — controls ordered so transformers repair lower choices, with `fixableViolations` shortening each hint.\n- `docs/phoenix/configurator-interface.mdx` — "Violations" lists the violation hooks with what each returns.',phxMembers:["frontend.useControlViolations","frontend.useFinalizeViolations","frontend.useStateValidity","frontend.useMapViolationHints"]});

package/dist/application-spec/generate-application/code/templates/skills/features/variants.d.ts

@@ -0,0 +1,2 @@
+import { type PhoenixGuide } from '../guide.js';
+export declare const generatePhoenixVariantsFeature: () => PhoenixGuide;

package/dist/application-spec/generate-application/code/templates/skills/features/variants.js

@@ -0,0 +1 @@
+import{createPhoenixFeatureGuide as e}from"../guide.js";export const generatePhoenixVariantsFeature=()=>e({path:"features/variants.md",title:"Variants",summary:"Supported alternative types, preview constraints and usage; read when preparing a comparison in the live preview and applying the choice.",whenToUse:"Read when preparing a visual or interaction comparison in the running preview. The [workflow](../core/workflow.md#visual-choices) owns whether alternatives would help; this guide covers the supported options and how to collect and apply a choice.",capabilities:'### Option types\n\n- Use `<id>.variant.js` to edit real frontend project files on top of one captured baseline. Use `<id>.html` for a standalone branding, layout or flow proposal rendered in an iframe.\n- Use the same mechanism for controls, layout, brand, lights, visuals, materials, positions, components, elements and transformers.\n- Keep the model, schemas, data, assistant server settings, webhooks and code shared with them, dependencies, environment and uploaded assets unchanged. The preview rejects changes needing server preparation.\n- Options reuse the already loaded configurator, one at a time. Variant transactions bypass the file-watcher debounce; hot reload still takes time to apply, without a special wait for rendering to settle.\n\n### Design the comparison\n\n- One decision per set, one set open at a time. Vary the decision being compared and keep unrelated details identical.\n- Make the difference visible in the UI or the scene; similar materials in flat light may not distinguish the alternatives.\n- Choose the number of options that clarifies the decision; no fixed count is required.\n- Name options in the client\'s product language and explain what changes in one line.\n\n### Write the options\n\n- One folder per set: `.phoenix/variants/<name>/`, one script or HTML file per option. HTML and scripts can share a set, but option ids must be unique. Keep HTML self-contained. This folder survives rebuilds and is never committed.\n- For HTML, set `<title>` and `<meta name="description" content="...">`; choosing a page changes no source files.\n- For scripts, export `title` and `description` as plain string literals, and a default function `({ read, write, remove }) => {}`; it may be async.\n- `read(path)` returns the original baseline file contents. `write(path, contents)` replaces or creates a file; `remove(path)` deletes it. Paths are relative to the project root.\n- Scripts run once per selection in the browser and collect edits. Phoenix validates and writes the whole batch locally and owns backups and undo. Do not perform your own filesystem or network operations.\n- Supported edits are YAML in `spec/` outside `spec/admin/`, and TypeScript under `src/components`, `transformers`, `handlers`, `elements` and `_`-prefixed shared folders. Expressions, actions and invariants run on the server too, so they cannot be edited.\n- Every option starts from the same baseline. Original restores it; switching restores the files only the previous option changed.\n- Keep the working tree untouched while comparing. Phoenix never overwrites an edit made outside the preview: it refuses to switch options over one, and when the comparison ends it leaves that file as it is and warns in the dev log.\n\n### Run it and wait\n\n```bash\npnpm phoenix variants .phoenix/variants/<name> --title \'<the question>\' --description \'<what differs between the options>\'\n```\n\n- `pnpm phoenix dev` must be running with the preview open in a browser. Tell the client the options are open there.\n- Put the title and the description in single quotes, so the shell passes backticks, `$` and double quotes through unchanged. In bash or zsh, write a single quote inside them as `\'\\\'\'`; in PowerShell, double it instead.\n- The command waits for the answer, 540 seconds unless `--timeout <seconds>` says otherwise, so give it a command timeout longer than that. It prints JSON:\n  - `"status": "chosen"` with `choice` (the option id, or `null` for Original) and `label`;\n  - `"status": "waiting"` when the wait ran out. The options stay open: run the same command again, or end the turn and run it when the client is back. An answer given in between is returned by the next run;\n  - `"status": "closed"` when the preview was closed without an answer.\n- `pnpm phoenix variants --close` closes the open set when the comparison is abandoned.\n- `--port <port>` names the editor WebSocket port when `phoenix dev` does not use 3020.\n- The live configurator keeps its current configuration. Interactions still change it; restoring source files does not undo configuration changes.\n\n### Use the answer\n\n- **Chosen** — a script\'s exact file edits remain in the project. For an HTML choice, implement the selected proposal using the SDK and compare the result with the page. With `choice: null`, the client chose Original and the baseline remains. Verify the result with `pnpm phoenix inspect:scene` and `pnpm phoenix screenshot`, and tell the client anything that came out differently.\n- Record the decision and its reason in the [project record](../core/workflow.md#records).\n- The client confirms Original or another option; Escape and the backdrop do not close the comparison. `--close` restores the baseline source files without an answer. The folder is removed once the client answers; pass `--keep` while its files are still needed to build from, and remove the folder afterwards.',example:"Compare warm and neutral lighting with two variant scripts while keeping the product and camera unchanged. Use HTML proposals instead when comparing standalone pages, such as branding sheets, then implement the selected proposal in the project. Original remains available as the captured baseline.",documentation:"Read `docs/phoenix/phoenix-cli.mdx` with `pnpm phoenix docs -r docs/phoenix/phoenix-cli.mdx` for the CLI contract. Use the [review index](../processes/review/index.md) to select evidence for the applied result.",phxMembers:[]});

package/dist/application-spec/generate-application/code/templates/skills/features/webhooks.d.ts

@@ -0,0 +1,2 @@
+import { type PhoenixGuide } from '../guide.js';
+export declare const generatePhoenixWebhooksFeature: () => PhoenixGuide;

package/dist/application-spec/generate-application/code/templates/skills/features/webhooks.js

@@ -0,0 +1 @@
+import{createPhoenixFeatureGuide as e}from"../guide.js";import{sdkGuidanceSections as o}from"../sdk-content.js";export const generatePhoenixWebhooksFeature=()=>e({path:"features/webhooks.md",title:"Webhooks",summary:"Frontend and server inclusion and import boundaries; read when adding handlers, assistant setup or shared webhook code.",whenToUse:"Read when deciding which handlers and shared modules belong in the webhook, including authentication, publication and assistant setup.",capabilities:o.webhookMembership,example:"When a pricing helper is shared by the browser and a quote webhook, keep its module server-safe. A handler that also imports a React layout cannot be included; split the shared calculation from the browser presentation.",documentation:"Read `docs/phoenix/webhook-membership.mdx` for inclusion rules and `docs/phoenix/webhooks.mdx` for worked handler and task examples, using `pnpm phoenix docs -r <path>`. The [SDK core](../core/sdk.md#webhooks-and-finalization) maps the available hooks and tasks.",phxMembers:["domain.createAssistantSetupHandler"]});

package/dist/application-spec/generate-application/code/templates/skills/guide.d.ts

@@ -0,0 +1,68 @@
+/**
+ * A Markdown document of the Phoenix skill, shipped beside its `SKILL.md`.
+ *
+ * Every document opens with its title as the only H1, and its parent index lists it by `title` and `summary`, so an
+ * agent decides from the index alone whether to read it. The factories below render the shared document shapes, so
+ * a guide follows the structure the skills architecture prescribes by construction rather than by review.
+ */
+export interface PhoenixGuide {
+    /** Path inside the skill folder, `/`-separated, such as `processes/review/code.md`. */
+    readonly path: string;
+    /** The document's name: its H1 and its entry in the parent index. */
+    readonly title: string;
+    /** What the document covers and when to read it, as one cell of the parent index. */
+    readonly summary: string;
+    readonly content: string;
+    /** The `phx` members this document is the home of; only feature guides teach members, every other document none. */
+    readonly phxMembers: readonly PhxMemberName[];
+}
+/**
+ * A member of the `phx` global a generated project declares, named by its namespace and member, such as
+ * `frontend.useTabNavigation` or `domain.implementActions`.
+ *
+ * The `phx` global is the public interface the guidance teaches. Every member has exactly one feature guide as its
+ * home, which teaches it as `phx.<namespace>.<member>`, or a recorded reason why no guide teaches it yet.
+ */
+export type PhxMemberName = `${PhxNamespace}.${string}`;
+/** The namespaces of the `phx` global. */
+export type PhxNamespace = 'frontend' | 'domain' | 'webhooks' | 'applicationTypes';
+interface PhoenixGuideHeader {
+    readonly path: string;
+    readonly title: string;
+    readonly summary: string;
+}
+/** A document organized by topic, such as a required core guide. */
+export interface PhoenixTopicGuideProps extends PhoenixGuideHeader {
+    /** Markdown sections after the H1, each usually opening with an H2. */
+    readonly sections: readonly string[];
+}
+/** A reusable procedure: its trigger, its steps, its completion boundary and one focused example. */
+export interface PhoenixProcessGuideProps extends PhoenixGuideHeader {
+    readonly whenToUse: string;
+    /** The procedure itself; topic subsections use H3. */
+    readonly steps: string;
+    readonly doneWhen: string;
+    readonly example: string;
+}
+/** What a Phoenix capability supports, when it fits, one focused example and its canonical documentation. */
+export interface PhoenixFeatureGuideProps extends PhoenixGuideHeader {
+    readonly whenToUse: string;
+    /** Supported usage and limits; topic subsections use H3. */
+    readonly capabilities: string;
+    readonly example: string;
+    readonly documentation: string;
+    /** The `phx` members this guide is the home of; its content teaches each as `phx.<namespace>.<member>`. */
+    readonly phxMembers: readonly PhxMemberName[];
+}
+/** A routing document: a short introduction and a table of its children with their summaries. */
+export interface PhoenixIndexGuideProps extends PhoenixGuideHeader {
+    readonly intro: string;
+    readonly guides: readonly PhoenixGuide[];
+    /** Markdown after the table, such as rules shared by every child or a topic map; empty when there is none. */
+    readonly notes: readonly string[];
+}
+export declare const createPhoenixTopicGuide: (props: PhoenixTopicGuideProps) => PhoenixGuide;
+export declare const createPhoenixProcessGuide: (props: PhoenixProcessGuideProps) => PhoenixGuide;
+export declare const createPhoenixFeatureGuide: (props: PhoenixFeatureGuideProps) => PhoenixGuide;
+export declare const createPhoenixIndexGuide: (props: PhoenixIndexGuideProps) => PhoenixGuide;
+export {};

package/dist/application-spec/generate-application/code/templates/skills/guide.js

@@ -0,0 +1,18 @@
+let e=(e,t)=>`${[`# ${e}`,...t.map(e=>e.trim())].join("\n\n")}
+`;export const createPhoenixTopicGuide=t=>{let{path:n,title:r,summary:i,sections:o}=t;return{path:n,title:r,summary:i,content:e(r,o),phxMembers:[]}};export const createPhoenixProcessGuide=t=>{let{path:n,title:r,summary:i,whenToUse:o,steps:s,doneWhen:a,example:c}=t;return{path:n,title:r,summary:i,phxMembers:[],content:e(r,[`## When to use
+
+${o.trim()}`,`## Steps
+
+${s.trim()}`,`## Done when
+
+${a.trim()}`,`## Example
+
+${c.trim()}`])}};export const createPhoenixFeatureGuide=t=>{let{path:n,title:r,summary:i,whenToUse:o,capabilities:s,example:a,documentation:c,phxMembers:m}=t;return{path:n,title:r,summary:i,phxMembers:m,content:e(r,[`## When to use
+
+${o.trim()}`,`## Capabilities and constraints
+
+${s.trim()}`,`## Example
+
+${a.trim()}`,`## Documentation
+
+${c.trim()}`])}};export const createPhoenixIndexGuide=t=>{let{path:n,title:r,summary:i,intro:o,guides:s,notes:a}=t,c=s.map(e=>`| [${e.title}](${((e,t)=>{let n=e.split("/").slice(0,-1),r=t.split("/"),i=0;for(;i<n.length&&i<r.length-1&&n[i]===r[i];)i+=1;return`${"../".repeat(n.length-i)}${r.slice(i).join("/")}`})(n,e.path)}) | ${e.summary} |`);return{path:n,title:r,summary:i,phxMembers:[],content:e(r,[o,["| Document | What it covers and when to read it |","| --- | --- |",...c].join("\n"),...a])}};

package/dist/application-spec/generate-application/code/templates/skills/phoenix-skill-bundle.d.ts

@@ -0,0 +1,10 @@
+import { type AgentSkillReference } from './agent-skill.js';
+import { type PhoenixSkillOptions } from './processes/index.js';
+/** The discoverable entry point and the documents it ships beside it. */
+interface PhoenixSkillBundle {
+    readonly content: string;
+    readonly references: readonly AgentSkillReference[];
+}
+/** Composes the required core, the processes and the feature guides into one discoverable Phoenix skill. */
+export declare const generatePhoenixSkillBundle: (options: PhoenixSkillOptions) => PhoenixSkillBundle;
+export {};

package/dist/application-spec/generate-application/code/templates/skills/phoenix-skill-bundle.js

@@ -0,0 +1,14 @@
+import{renderAgentSkill as e}from"./agent-skill.js";import{generatePhoenixCliCore as o,generatePhoenixSdkCore as t,generatePhoenixWorkflowCore as r}from"./core/index.js";import{generatePhoenixFeatureGuides as n}from"./features/index.js";import{createPhoenixIndexGuide as s}from"./guide.js";import{generatePhoenixAssetConversion as i,generatePhoenixFeedbackGuides as a,generatePhoenixFinalization as d,generatePhoenixFirstDraftGuides as c,generatePhoenixModelMigration as h,generatePhoenixOperations as l,generatePhoenixPlanning as u,generatePhoenixReviewGuides as p,generatePhoenixSpecificationGuides as m}from"./processes/index.js";export const generatePhoenixSkillBundle=f=>{let w=[r(),t(),o()],g=[c(),m(),[u()],[l(f)],[d()],[i()],[h()],p(),a()],x=s({path:"processes/index.md",title:"Processes",summary:"Procedures summarized by outcome and when to use them.",intro:"Read the procedure or section whose outcome the task needs. The [workflow](../core/workflow.md) owns strategy, preferences and effort; processes supply the execution.",guides:g.flatMap(e=>e.slice(0,1)),notes:[]}),k=n();return{content:e({name:"phoenix",description:"Build, change, inspect, deploy or review a Phoenix configurator project. Use for all Phoenix project work, including a first draft of a new project, visual alternatives and platform feedback.",sections:[`# Phoenix
+
+Use the required core to choose how to work, then load task details only when they apply.`,`## Required reading
+
+Before Phoenix work, read these three core guides in order:
+
+${w.map((e,o)=>`${o+1}. [${e.title}](${e.path}) — ${e.summary}.`).join("\n")}
+
+The core governs every task; reading the workflow does not mean executing every stage. Reuse the core while it remains in context and unchanged, and read it again when context is lost or sync or an SDK update changes it.`,`## Optional guidance
+
+- [Processes](processes/index.md) — procedures summarized by outcome and when to use them.
+- [Features](features/index.md) — what Phoenix capabilities support, their constraints and canonical SDK documentation.
+
+Follow only the destinations the task needs; a link does not require reading its whole subtree.`]}),references:[...w,x,...g.flat(),...k].map(({path:e,content:o})=>({path:e,content:o}))}};

package/dist/application-spec/generate-application/code/templates/skills/phx-members-without-guide.d.ts

@@ -0,0 +1,9 @@
+import { type PhxMemberName } from './guide.js';
+/**
+ * The `phx` members no feature guide teaches yet, each with the reason.
+ *
+ * Every other member that is not deprecated has exactly one feature guide as its home, which declares it in its
+ * `phxMembers`; deprecated members are never mentioned. The list only shrinks: a new member gets a home or an entry
+ * here with its reason, and a guide that starts teaching a member removes its entry.
+ */
+export declare const phxMembersWithoutGuide: Readonly<Partial<Record<PhxMemberName, string>>>;

package/dist/application-spec/generate-application/code/templates/skills/phx-members-without-guide.js

@@ -0,0 +1 @@
+let e="Planned guide: lifecycle providers, handlers and runtime services.",n="Planned guide: integration modes and embedding.",t="Planned guide: theming and icon sets.",a="Planned guide: Admin.",i="Planned guide: webhook builders and finalization tasks; the SDK core lists them meanwhile.",o="Planned guide: data sources and finalization data types.";export const phxMembersWithoutGuide={"frontend.usePropertyPageStack":"Not taught: guidance renders controls from the project layout, not YAML property pages.","frontend.usePropertyPageState":"Not taught: guidance renders controls from the project layout, not YAML property pages.","frontend.useSessionService":"Internal: the session service for initialization code.","frontend.createOnApplicationStartProvider":e,"frontend.createOnSessionReadyProvider":e,"frontend.createOnPublishedDataReadyProvider":e,"frontend.createOnFrontendDataReadyProvider":e,"frontend.createOnBackendDataReadyProvider":e,"frontend.createOnRoutingReadyProvider":e,"frontend.createOnConfiguratorReadyProvider":`${e} Navigation states mentions it for mounting listeners.`,"frontend.createCollectFrontendDataHandler":e,"frontend.createFilterPublishedChunksHandler":e,"frontend.createGetTextureProcessingMapHandler":e,"frontend.useAnalytics":e,"frontend.useAuthenticatedClient":e,"frontend.useAuthorizedClient":`${e} Finalization actions mentions its finalize call.`,"frontend.useCreateAuthorizedClient":e,"frontend.useSession":`${e} Presets mentions it for reading the session role.`,"frontend.useDomainApplication":`${e} Presets mentions it for saving before leaving.`,"frontend.useConfigurator":e,"frontend.useDomainApplicationProps":e,"frontend.createGetWebComponentOptionsHandler":n,"frontend.useIntegrationService":n,"frontend.useIntegrationState":n,"frontend.useRecipeEmbeddedState":n,"frontend.usePresetEmbeddedState":n,"frontend.createGetThemeHandler":t,"frontend.createPhoenixIconSet":t,"frontend.useEntityPrice":"Planned guides: specific component kinds, such as the price component.","frontend.admin":a,"domain.admin":a,"webhooks.authHandlerBuilder":i,"webhooks.webhookBuilder":i,"webhooks.taskFactory":i,"webhooks.finalizeHandlerBuilder":i,"webhooks.callbackBuilder":i,"webhooks.prefetchBuilder":i,"webhooks.dynamicResourcesFactory":i,"applicationTypes.ApplicationVersion":o,"applicationTypes.PublishedDataHash":o,"applicationTypes.PublishedData":o,"applicationTypes.SessionData":o,"applicationTypes.FrontendData":o,"applicationTypes.BackendData":o,"applicationTypes.FinalizeData":o,"applicationTypes.PrefetchedFinalizeData":o,"applicationTypes.FinalizeResult":o,"applicationTypes.CallbackData":o,"applicationTypes.ExportState":"Planned guide: the 3D scene and image export.","applicationTypes.AdminNavigationState":a};

package/dist/application-spec/generate-application/code/templates/skills/processes/asset-conversion.d.ts

@@ -0,0 +1,2 @@
+import { type PhoenixGuide } from '../guide.js';
+export declare const generatePhoenixAssetConversion: () => PhoenixGuide;

package/dist/application-spec/generate-application/code/templates/skills/processes/asset-conversion.js

@@ -0,0 +1,23 @@
+import{createPhoenixProcessGuide as e}from"../guide.js";let t=`Conversion is part of the product's appearance, not a preliminary chore: a converted model that is misplaced, incomplete or stripped of its detail is a visible defect, and the client sees it before anything else.
+
+### Write a script, not a sequence of one-off fixes
+
+Convert every model with one re-runnable script, committed to the project and parameterized per model. Do not repair a file by hand. A correction discovered on the first model must be in the script before the next model is converted, or it is lost: repairs made interactively do not survive the batch that follows. Record in the project record which tool chain the script uses and what each step does, so the conversion can be rerun when a source file changes.
+
+### What a converted model must satisfy
+
+- **Ground contact** — the model's lowest geometry is where the product touches the floor, and it sits at the scene's floor height without a hand-computed vertical offset. A constant that has to agree with a separately placed floor eventually disagrees with it.
+- **Completeness** — every sub-assembly that belongs to the product is present, and nothing else is: no detached fragments, no parts protruding through an outer surface, no leftover rig or construction geometry.
+- **Assembly** — parts that belong together are positioned together. Source files often store sub-assemblies at their own offsets; re-seat them against the part they attach to, not against the file's origin.
+- **Scale and orientation** — dimensions match the published figures for that product, and the model faces the same way as every other model in the set. Report any divergence from the published figures rather than silently adopting the model's.
+- **Separable materials** — parts users can configure independently carry their own materials, so a control can reach them.
+- **Material class** — a part the project gives a clearcoat needs one in the converted model already. Phoenix's clearcoat overrides act on \`MeshPhysicalMaterial\`, and three.js creates that class only when the glTF declares \`KHR_materials_clearcoat\`; on a plain \`MeshStandardMaterial\` the overrides are accepted and silently do nothing. Export painted and lacquered parts with a clearcoat value, however small, so the extension is present for the override to act on.
+
+### Detail budget
+
+Reduce geometry per part, never uniformly across a model. A single ratio removes almost nothing from large flat panels and destroys small curved parts, which are usually the ones nearest the camera. Keep full detail on parts that are small, curved and always visible, such as castors, handles, pulls and hinges, and spend the budget on large simple surfaces instead. After reducing, look at the affected parts at the default camera distance, not only at a distance that flatters them.
+
+### Verify every model, not the first one
+
+Inspect each converted model with the [asset inspection](../features/inspection.md) tooling, and check every requirement above for every model in the set. A batch that reuses a script verified on one file still needs each result looked at: source files in one delivery frequently differ in origin, scale and structure.`,r=`- Every model in scope is converted by the committed script and inspected against each requirement.
+- Divergences from published figures are reported to the client, not silently adopted.`;export const generatePhoenixAssetConversion=()=>e({path:"processes/asset-conversion.md",title:"Asset conversion",summary:"Convert and verify supplied 3D models with a reproducible script; read when supplied models need conversion or repair before configuration.",whenToUse:"When supplied models need conversion or repair before they can be configured. A [first draft](first-draft/direction.md) converts only its representative model, or builds a labeled stand-in when no model is supplied.",steps:t,doneWhen:r,example:"For a set of chairs, parameterize the conversion for the source units, the ground contact and separately configurable upholstery and frame materials. Run the same script for every supplied chair and inspect each output; a valid first model does not validate the rest."});

package/dist/application-spec/generate-application/code/templates/skills/processes/feedback/evaluate.d.ts

@@ -0,0 +1,2 @@
+import { type PhoenixGuide } from '../../guide.js';
+export declare const generatePhoenixFeedbackEvaluation: () => PhoenixGuide;

package/dist/application-spec/generate-application/code/templates/skills/processes/feedback/evaluate.js

@@ -0,0 +1,39 @@
+import{createPhoenixProcessGuide as e}from"../../guide.js";let t=`### Interview the client
+
+Say first that the answers go to the Phoenix team as feedback, and that the client can decline. Then ask one question at a time, in this order, and wait for each answer before asking the next. Give the short explanation with each question. Every score is a whole number from 0 to 10, where 0 is catastrophic, 5 is passable and 10 is amazing:
+
+1. **Minutes spent** — roughly how many minutes the client spent on the run, from the first prompt to now. This one is a number of minutes, not a score.
+2. **Agent guidance** — how clear it was what to expect and what to do, how clearly the agent explained itself, and how well the client understood the consequences of their choices.
+3. **Functionality** — how complete the configurator is: whether it configures the full product with all its options, keeps users from creating or submitting a wrong configuration, and offers a way to finalize one.
+4. **UX** — how easy the configurator is to understand and operate, how clear the choices are, and how understandable incompatibilities and the ways to resolve them are.
+5. **3D quality** — how realistic and attractive the configured object and its scene are: shapes, textures, surroundings, lighting and shadows.
+6. **UI visuals** — how good the user interface looks.
+7. **Overall** — the client's subjective verdict on the configurator as a whole.
+8. **Comments** — anything else about the experience, in their own words. This one is free text and may be empty.
+
+Rules of the interview:
+
+- Ask once per conversation. Do not run it again after a later deploy, and do not run it after a deploy that failed.
+- Never choose, guess or adjust a score, and never answer a question for the client. When they skip one, write \`skipped\` for it.
+- When the client declines the evaluation, send nothing and do not ask again.
+
+### Compose the evaluation
+
+Compose the evaluation from the answers with exactly these labels, one per line, in this order. Write \`none\` when there are no comments, and fill \`Build\` and \`Configurator\` as [Report a problem](report.md) describes:
+
+\`\`\`text
+Evaluation
+Minutes spent: <minutes>
+Agent guidance: <score>/10
+Functionality: <score>/10
+UX: <score>/10
+3D quality: <score>/10
+UI visuals: <score>/10
+Overall: <score>/10
+Comments: <their comments, or none>
+Build: <build id> <Studio build page link>
+Configurator: <live configurator link>
+\`\`\`
+
+Keep the labels and their order, so the scores can be read out of the feedback list and its export. Send it with \`--type other\` through [Approve and send](send.md). An evaluation is not a bug report: when a comment names a concrete problem, offer to draft it as its own report.`,n=`- The client answered or skipped every question, or declined the evaluation.
+- An accepted evaluation went through [Approve and send](send.md) with every label in order.`;export const generatePhoenixFeedbackEvaluation=()=>e({path:"processes/feedback/evaluate.md",title:"Evaluate the run",summary:"An interview of the client about the run, recorded without invented scores; read once the client has finished.",whenToUse:"When the work on the configurator is finished: the client says they are done, or `phoenix deploy` reported the configurator live and the client confirms they have nothing more to build. Ask that once after a deploy goes live, and do not start the interview while they want to continue.",steps:t,doneWhen:n,example:"When the client skips the UX score, record `UX: skipped`; when they decline the evaluation, send nothing. Use [Approve and send](send.md) only for an evaluation they accepted."});

package/dist/application-spec/generate-application/code/templates/skills/processes/feedback/feedback.d.ts

@@ -0,0 +1,3 @@
+import { type PhoenixGuide } from '../../guide.js';
+/** The feedback index followed by its procedures. */
+export declare const generatePhoenixFeedbackGuides: () => readonly PhoenixGuide[];

package/dist/application-spec/generate-application/code/templates/skills/processes/feedback/feedback.js

@@ -0,0 +1 @@
+import{createPhoenixIndexGuide as e}from"../../guide.js";import{generatePhoenixFeedbackEvaluation as o}from"./evaluate.js";import{generatePhoenixFeedbackReport as r}from"./report.js";import{generatePhoenixFeedbackSending as i}from"./send.js";export const generatePhoenixFeedbackGuides=()=>{let t=[r(),o(),i()];return[e({path:"processes/feedback/index.md",title:"Feedback",summary:"Run evaluations and verified Phoenix problem reports, sent only with approval; read right after `phoenix deploy` reports the configurator live, when the client finishes, or for SDK bugs, misleading guidance and missing capabilities.",intro:"Choose the outcome and load only its procedure. Sending always goes through [Approve and send](send.md).",guides:t,notes:[]}),...t]};

package/dist/application-spec/generate-application/code/templates/skills/processes/feedback/index.d.ts

@@ -0,0 +1 @@
+export * from './feedback.js';

package/dist/application-spec/generate-application/code/templates/skills/processes/feedback/index.js

@@ -0,0 +1 @@
+export*from"./feedback.js";

package/dist/application-spec/generate-application/code/templates/skills/processes/feedback/report.d.ts

@@ -0,0 +1,2 @@
+import { type PhoenixGuide } from '../../guide.js';
+export declare const generatePhoenixFeedbackReport: () => PhoenixGuide;

package/dist/application-spec/generate-application/code/templates/skills/processes/feedback/report.js

@@ -0,0 +1,7 @@
+import{createPhoenixProcessGuide as e}from"../../guide.js";let t=`Draft feedback for the Phoenix team when one of these happens while working in this project:
+
+- **Bug** — the SDK, the \`phoenix\` CLI or generated code crashes, produces wrong output or behaves differently from its documentation, and the cause is not in this project's own code.
+- **Misleading guidance** — a doc page, a Phoenix guide or an error message pointed the wrong way, or did not say what was needed.
+- **Missing feature** — something the SDK does not support forced a workaround, or a routine task took far more steps than it should.
+
+Do not draft feedback for problems in this project's own specs or code, for a suspicion that is not checked, or twice for the same problem. For a finished run, use [Evaluate the run](evaluate.md) instead.`;export const generatePhoenixFeedbackReport=()=>e({path:"processes/feedback/report.md",title:"Report a problem",summary:"A verified SDK bug, misleading guidance or missing capability, drafted for the Phoenix team; read when such a problem affects the work.",whenToUse:t,steps:"Write one draft per distinct problem, as plain text with the labels below, in this order, so the Phoenix team reads every report the same way. Keep every label; write `none` or `not deployed yet` where there is nothing to put.\n\n```text\nBuild: <build id> <Studio build page link>\nConfigurator: <live configurator link>\n\nWhat I was doing:\n<the task and the step you were on>\n\nWhat happened and what I expected:\n<what you ran or called, the result you got, and the result you expected>\n\nExact error or agent output:\n<the error text or the output, copied unchanged>\n\nWorkaround:\n<what you did instead, or none>\n\nConversation log:\n<the conversation condensed to the turns that matter: what the client asked, what you tried, what failed>\n```\n\n- **Build** is the latest build of this project, whose sources show the problem. `pnpm phoenix deploy` prints its id as `Build <id> started` and its page as `Follow the build in Studio: <url>`. When that line is missing, compose the link as `https://<workspace>.<studio host>/builder/deployments/<build id>`: the workspace is the one named at `phoenix login`, and the host is `studio.eu.salsita.ai` for the `eu` region, `studio.salsita.ai` for `us` and `studio-staging.salsita.app` for staging. A Studio address passed to login with `--studioUrl` replaces the workspace and host. Never invent a build id: when the project was not deployed, write `not deployed yet`.\n- **Configurator** is the live address `pnpm phoenix deploy` prints once the build is live.\n- The team downloads the build's sources from its Studio page, so do not paste whole files; quote only the lines that show the problem.\n- Quote errors and output exactly. A report that paraphrases an error cannot be searched for.\n- Condense the conversation log rather than dumping it: keep the client's requests, the decisions and the failures, and leave out tool output the other sections already carry.\n\nThen follow [Approve and send](send.md).",doneWhen:"- Each distinct, verified problem has one draft with every label filled or marked `none`.\n- The drafts went through [Approve and send](send.md).",example:"When `pnpm phoenix variants` rejects a script that only edits `src/elements/`, confirm the script follows the documented contract, then draft a bug with the exact rejection message, the script's relevant lines and `not deployed yet` for the build."});

package/dist/application-spec/generate-application/code/templates/skills/processes/feedback/send.d.ts

@@ -0,0 +1,2 @@
+import { type PhoenixGuide } from '../../guide.js';
+export declare const generatePhoenixFeedbackSending: () => PhoenixGuide;

package/dist/application-spec/generate-application/code/templates/skills/processes/feedback/send.js

@@ -0,0 +1,2 @@
+import{createPhoenixProcessGuide as e}from"../../guide.js";let n=`- The client saw the exact text and approved it, and it was sent from a file or as a short argument; or the client declined and nothing was sent.
+- The sending is confirmed to the client in one line.`;export const generatePhoenixFeedbackSending=()=>e({path:"processes/feedback/send.md",title:"Approve and send",summary:"Showing the exact payload, redacting excluded data and sending only after approval; read before sending any feedback.",whenToUse:"Before sending any feedback: a [problem report](report.md) or an [evaluation](evaluate.md).",steps:"### Ask before sending\n\nNever send feedback on your own. Show the client a draft and send it only after they approve it. When to ask is a judgement:\n\n- **Right away** — the problem is crucial: it blocks the task or forces a workaround the client should know about now. Interrupt the work, show the draft and continue once the client has answered.\n- **At the end of the task** — everything else. Collect the details while working and show all drafts together in the final message.\n- **When the client asks** to send feedback — draft it and show it before sending.\n\nThe draft is exactly what would be sent: the type, the full message, the project if `--projectSlug` names one, and the contact if the client gave one. Send it unchanged after a yes; when the client edits it, send their version. When they decline, drop it and do not raise that problem again.\n\n### Send it\n\nWrite a report or an evaluation to a text file and send the file, so the shell changes nothing in it:\n\n```bash\npnpm phoenix feedback --file <path> --type bug --agent '<your agent name>'\n```\n\nPut the file outside the project, in the system's temporary folder, and delete it after sending. A note of a line or two can go in as an argument instead:\n\n```bash\npnpm phoenix feedback '<message>' --type idea --agent '<your agent name>'\n```\n\n- Give either `--file` or the message argument, never both.\n- Put a message argument in single quotes, so the shell passes backticks, `$` and double quotes through unchanged. In bash or zsh, write a single quote inside the message as `'\\''`; in PowerShell, double it instead.\n- `--type` is `bug`, `idea` or `other` (default `other`). Use `idea` for a missing feature or an improvement, and `other` for an evaluation.\n- `--agent` names the coding agent, so the team can tell agent feedback from a person's.\n- `--contact '<email>'` only when the client wants a reply and gave the contact to use.\n- The workspace, user, SDK version and the spec's `project` are attached automatically. `--projectSlug <slug>` names another project of the workspace.\n- A message holds at most 100,000 characters. Shorten the conversation log first when a report is longer.\n\nThe command needs `phoenix login`. When it answers that the CLI is not signed in, tell the client once and continue; do not sign in on their behalf, because the sign-in is approved in a browser. After sending, confirm it to the client in one line.\n\n### What never goes into feedback\n\nThe message leaves this project and is read by the Phoenix team. Never include:\n\n- secrets and credentials: API tokens, keys, passwords or `.env` values, also when they appear inside a quoted error or log. Replace each with `<redacted>`;\n- personal data, or data of the project's customers and end users, such as names, email addresses and orders, other than a contact the client asked to add.\n\nParts of this project may go into a message: file names and paths, snippets of its specs and code, and the client's own words. They are sent only as part of a draft the client saw and approved, which is why the draft shown is always the full text.",doneWhen:n,example:"At the end of a task, show the client two drafted reports in the final message. They approve the first and decline the second; send the first from a temporary file with `--type bug`, delete the file, confirm in one line, and never raise the second problem again."});

package/dist/application-spec/generate-application/code/templates/skills/processes/finalization.d.ts

@@ -0,0 +1,2 @@
+import { type PhoenixGuide } from '../guide.js';
+export declare const generatePhoenixFinalization: () => PhoenixGuide;

package/dist/application-spec/generate-application/code/templates/skills/processes/finalization.js

@@ -0,0 +1,2 @@
+import{createPhoenixProcessGuide as e}from"../guide.js";let a=`- Each agreed action works end to end in the preview, and its success and failure paths are visible.
+- Real messages or orders were sent only with the client's authorization.`;export const generatePhoenixFinalization=()=>e({path:"processes/finalization.md",title:"Finalization",summary:"Implement the agreed completion journey: summary PDFs, emails, sharing, quotes, orders or other integrations; read when a configuration needs an ending or an integration.",whenToUse:"When the configuration journey needs an ending: saving, sharing, a summary PDF, an email, a quote, an order or another integration. A [first draft](first-draft/build.md) uses it for its summary PDF and email.",steps:"1. Agree what completing means: what is collected, what is submitted and where, what the configurator user receives, and how progress, success, failure and recovery look. Discover requirements early when they affect earlier design decisions, and implement them here.\n2. Declare each completion as a `finalizeAction` component with `variant` `primary` or `secondary` and a handler registered with `phx.frontend.createPhoenixHandler`. Render the actions in the project layout with `phx.frontend.useFinalizeActions()`, as [Finalization actions](../features/custom-layout/finalization-actions.md) describes.\n3. Implement the server side in the project webhook with `withConfiguratorFinalize`, chaining the tasks the [SDK core](../core/sdk.md#webhooks-and-finalization) lists, such as `GenerateConfigurationLink`, `GeneratePdf` or `GenerateStaticPdf`, and `SendEmail`, and return the result in the callback. Images rendered by the configurator, described in `docs/other-features/client-side-rendering/declarative.mdx`, embed in PDFs and emails without server rendering.\n4. Test payloads and outcomes, including a failed delivery, without sending real messages or creating real orders unless the client authorizes it. Keep unfinished rules and provisional prices identifiable, so nothing produces a misleading real quote or order.",doneWhen:a,example:"For a summary with email: the primary action generates a configuration link and two configurator renders, builds a branded PDF and offers it for download; the secondary action opens a form for an email address and sends the same PDF and images. Test the email with the client's own address after they agree, and a failed delivery with an invalid one."});

package/dist/application-spec/generate-application/code/templates/skills/processes/first-draft/build.d.ts

@@ -0,0 +1,2 @@
+import { type PhoenixGuide } from '../../guide.js';
+export declare const generatePhoenixFirstDraftBuild: () => PhoenixGuide;

package/dist/application-spec/generate-application/code/templates/skills/processes/first-draft/build.js

@@ -0,0 +1,25 @@
+import{createPhoenixProcessGuide as e}from"../../guide.js";let t=`### Keep the scope small
+
+Implement one representative product with a few options, for example three finishes and one size choice, working end to end in the chosen layout and branding. Prefer one working path to a screen of inactive controls. Keep everything else in the product definition as remaining scope, and keep unconfirmed prices visibly provisional. Use reversible defaults and keep going; list them at the handoff instead of asking now.
+
+### Brand the first moments
+
+- **Preset screen** — replace it with \`phx.frontend.createPresetUi()\` in the chosen branding, offering two or three meaningful starting configurations with thumbnails. \`pnpm phoenix screenshot\` captures only the state the preview shows, so open each preset in the preview with browser automation before capturing it; without automation, use a branded placeholder and say so at the handoff. Keep the preview-mode branch of the SDK example \`docs/layouts/presets/custom.mdx\`, read with \`pnpm phoenix docs -r <path>\`.
+- **App loader** — replace the loading overlay's content with \`phx.frontend.createAppLoader()\`: the logo, a short brand animation and progress from the loading phases.
+
+[Project pages](../../features/custom-layout/pages.md) has the contracts of both, and [Presets](../../features/application-states/presets.md) how the starting configurations are defined.
+
+### Add finalization
+
+Add two \`finalizeAction\` components with their handlers, following [Finalization](../finalization.md):
+
+- **Primary** — download a branded summary PDF of the configuration with images rendered from the configurator, the chosen options and the price, marked provisional while it is.
+- **Secondary** — an email form that sends the same PDF and images to the address the configurator user enters.
+
+Test the PDF in the running preview. Send a test email only to an address the client gives, after their yes; until then, report the email action as untested.
+
+### Check before presenting
+
+Exercise the representative path once in the preview: the preset screen, the loader, every option and both finalization actions, at desktop and phone width. Fix what is broken. This is the quick look of the first draft, not a review process.`,n=`- The preset screen, loader, options and both finalization actions work in the running preview, in the chosen branding and layout.
+- The summary PDF downloads with configuration images; the email action is tested or explicitly waiting for an address.
+- Remaining scope and provisional items are recorded in the product definition and the project record.`;export const generatePhoenixFirstDraftBuild=()=>e({path:"processes/first-draft/build.md",title:"Build",summary:"A limited end-to-end configurator in the chosen branding and UX, with a branded preset screen, app loader, summary PDF and email; read once the layout is chosen.",whenToUse:"After [Direction](direction.md), once the client chose the branding and the layout. It ends with a working draft ready to present.",steps:t,doneWhen:n,example:"For the lounge chair: three upholstery colors and two leg finishes in the bottom-sheet layout, a preset screen offering a classic, a bold and a quiet starting chair, a loader that draws the logo, a branded PDF with a front and a side render, and an email form. The client's own address receives the test email after they agree."});

package/dist/application-spec/generate-application/code/templates/skills/processes/first-draft/direction.d.ts

@@ -0,0 +1,2 @@
+import { type PhoenixGuide } from '../../guide.js';
+export declare const generatePhoenixFirstDraftDirection: () => PhoenixGuide;

package/dist/application-spec/generate-application/code/templates/skills/processes/first-draft/direction.js

@@ -0,0 +1,26 @@
+import{createPhoenixProcessGuide as e}from"../../guide.js";let t=`### Intake
+
+Use what the client already supplied. When it is enough to start, ask nothing: summarize the product as you understood it in two or three sentences and continue. When nothing was supplied, send one compact message asking for whatever exists, all optional: what the product is, who will use the configurator, the brand's website, logo or colors, and any 3D models, photos or drawings. Continue with whatever arrives; do not start a second round of questions.
+
+When a website is given, take the colors, typography, logo and tone from it instead of asking the client to describe their brand. Write what is known into a first [product definition](../specification/product-definition.md) and mark what is provisional; its PDF is rendered once, at the handoff. Prices, rules and the full product range wait for normal mode.
+
+### Branding options
+
+Prepare three branding options as standalone HTML pages in one [Variants](../../features/variants.md) set, each a one-page brand sheet with the content [Branding](../specification/branding.md) lists. With an existing brand, the options interpret it for a configurator, for example faithful, bolder and quieter; they never replace it. Without one, make three genuinely different directions that suit the product and its users. Run the set with \`--keep\`, so the chosen page remains to build from.
+
+Save the chosen page as the branding source, render its PDF, apply the brand to the Phoenix theme and remove the variants folder.
+
+### Sample scene
+
+Show the representative product with a minimal domain: its entity and one or two real options, enough for the layout options to show working controls.
+
+- **Supplied model** — convert only the representative model now, following [Asset conversion](../asset-conversion.md); the rest waits for normal mode.
+- **No model** — build a stand-in with three.js primitives exported to glTF, or with Blender when it is installed. Match the proportions of any photo or drawing, give each configurable part its own material, rest it on the floor and tell the client it is a stand-in.
+
+Set materials, lighting, background and camera framing in the chosen brand, and look at the result in the preview before moving on.
+
+### Layout options
+
+Prepare three distinct custom layouts as variant scripts over the live scene, each writing a complete \`ConfiguratorLayout\` as [Custom project layout](../../features/custom-layout/index.md) describes. Make them differ in structure, not only in color: for example a side panel, a bottom sheet with in-scene controls and a guided stepper. Start from the layout gallery in the SDK documentation rather than from scratch: \`pnpm phoenix docs -l\` lists its \`docs/layouts/gallery/\` pages and \`pnpm phoenix docs -r <path>\` reads one. Keep the canvas, safe-area, message and read-mode wiring of its examples. Every option uses the chosen branding and the same working controls.
+
+Run the set; the chosen script's edits stay in the project. Write the [UX guidelines](../specification/ux-guidelines.md) from the chosen layout and render their PDF.`;export const generatePhoenixFirstDraftDirection=()=>e({path:"processes/first-draft/direction.md",title:"Direction",summary:"Intake, three branding options, a sample scene and three layout options, ending with the chosen branding and UX guidelines; read at the start of a first draft.",whenToUse:"At the start of a first draft, once [Project operations](../operations.md) has the preview running. It ends when the client has chosen a branding and a layout and the UX guidelines record the choice.",steps:t,doneWhen:"- The client chose a branding option and a layout option, and both are applied in the running preview.\n- The branding and UX guideline sources are in `.phoenix/workspace/specification/`, with their PDFs in `docs/`.\n- The sample scene shows the representative product, or a labeled stand-in, responding to at least one real option.\n- A first product definition records what is known and what is provisional.",example:"A client sends the website of their furniture brand and a photo of a lounge chair, without a model. Summarize the chair, offer three brand sheets that interpret their site, build a stand-in chair from primitives with separate seat and frame materials, and offer a side-panel, a bottom-sheet and a stepper layout over it. The client picks the bolder brand sheet and the bottom sheet; the UX guidelines then describe the bottom-sheet patterns."});

package/dist/application-spec/generate-application/code/templates/skills/processes/first-draft/first-draft.d.ts

@@ -0,0 +1,3 @@
+import { type PhoenixGuide } from '../../guide.js';
+/** The first-draft index followed by its stages, in the order they run. */
+export declare const generatePhoenixFirstDraftGuides: () => readonly PhoenixGuide[];

package/dist/application-spec/generate-application/code/templates/skills/processes/first-draft/first-draft.js

@@ -0,0 +1,3 @@
+import{createPhoenixIndexGuide as e}from"../../guide.js";import{generatePhoenixFirstDraftBuild as t}from"./build.js";import{generatePhoenixFirstDraftDirection as o}from"./direction.js";import{generatePhoenixFirstDraftHandoff as n}from"./handoff.js";export const generatePhoenixFirstDraftGuides=()=>{let r=[o(),t(),n()];return[e({path:"processes/first-draft/index.md",title:"First draft",summary:"A fast, convincing first version of a new project: chosen branding and UX, a sample product, real finalization and an offer to deploy; read only for a new project, never for an existing one.",intro:`The first thing a new client sees. In one short sitting, deliver a branded, working configurator with a chosen look and UX, a sample of the product and real finalization, ready to deploy as a first live version. Use it only for a new project; an existing project continues in normal mode.
+
+Speed is part of the quality. Run no review processes, and ask the client to choose only three things: a branding option, a layout option and whether to deploy. Everything else uses reversible defaults, stated at the handoff. Read the stages in order, and note in the project record which stage the draft reached, so a resumed session continues the draft instead of switching to normal mode; the handoff marks the draft complete.`,guides:r,notes:[]}),...r]};

package/dist/application-spec/generate-application/code/templates/skills/processes/first-draft/handoff.d.ts

@@ -0,0 +1,2 @@
+import { type PhoenixGuide } from '../../guide.js';
+export declare const generatePhoenixFirstDraftHandoff: () => PhoenixGuide;