@salsita-ai/sdk 0.50.0-develop.ed1806b910 → 0.50.0-develop.eeaf6c4605

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

@@ -1,282 +1,112 @@
 /**
- * Documented Phoenix SDK guidance, one Markdown section per entry.
+ * Documented Phoenix SDK capability text that the feature guides of the Phoenix skill carry.
  *
- * The agent guidance shipped into generated projects — the Phoenix-owned agent skills — is composed
- * from these sections, so each documented fact has exactly one home and the generated files differ
- * only in which sections they carry.
+ * Each entry is the body of one capability, with H3 topic headings, so a feature guide places it under its
+ * "Capabilities and constraints" section and every documented fact has exactly one home.
  */
 export declare const sdkGuidanceSections: {
-    /**
-     * How to run the commands the skills write for pnpm through the package manager the project uses. Every skill
-     * that names a command carries it, because an agent loads each skill on its own.
-     */
-    readonly packageManager: `## Package Manager
-The project installs with its own package manager, and the commands in this skill are written for pnpm. Run them through the package manager the project uses, which the lockfile in the project root names:
-- \`pnpm-lock.yaml\`: \`pnpm phoenix <command>\`, \`pnpm install\`, \`pnpm add <package>\`
-- \`package-lock.json\`: \`npx phoenix <command>\`, \`npm install\`, \`npm install <package>\`
-- \`yarn.lock\`: \`yarn phoenix <command>\`, \`yarn install\`, \`yarn add <package>\`
-- \`bun.lock\` or \`bun.lockb\`: \`bunx phoenix <command>\`, \`bun install\`, \`bun add <package>\`
+    /** Supported custom UI composition and element registration contracts. */
+    readonly customLayout: `### ConfiguratorLayout
 
-Without a lockfile, use the package manager the \`packageManager\` field of \`package.json\` names, or ask the user.`;
-    /** The everyday `phoenix` commands, and the one that brings `package.json` in line with the SDK. */
-    readonly buildCommands: `## Build Commands
-- \`pnpm phoenix build\` — Full production build
-- \`pnpm phoenix dev\` — Development mode with hot reload
-- \`pnpm phoenix sync\` — Sync generated files without full build
-- \`pnpm phoenix deps\` — Add the SDK's missing peer dependencies to \`package.json\` and move out-of-range ones into the SDK's range; it installs nothing, so install after it`;
-    /** Where `phoenix dev` writes its log and how to read it. */
-    readonly devLogs: `## Dev Logs
-- \`pnpm phoenix dev\` writes all logs to \`.phoenix/phoenix-dev.log\`
-- Contains: spec parse errors, build errors, browser runtime errors, file watcher events
-- After making changes, always check the log for errors: \`tail -50 .phoenix/phoenix-dev.log\` or \`grep ERROR .phoenix/phoenix-dev.log\`
-- Rotated automatically at 10MB (\`.log.1\`, \`.log.2\` are older rotations)`;
-    /** What each top-level project folder holds. */
-    readonly projectStructure: `## Project Structure
-- \`spec/\` — Domain YAML specs (entities, relations, expressions, invariants, components, application config)
-- \`src/expressions/\` — Computed/derived entity properties (\`phx.domain.implementCustomExpressions()\`)
-- \`src/actions/\` — Domain operations declared under \`actions:\` in the spec (\`phx.domain.implementActions()\`), run by controls and exposed to the assistant
-- \`src/invariants/\` — Business rule constraints (\`phx.domain.implementCustomInvariants()\`)
-- \`src/transformers/\` — Automatic state fixers (\`phx.frontend.transformerBuilder\`)
-- \`src/components/\` — ECS system components (\`phx.domain.attachComponent.withEntity()\`)
-- \`src/elements/\` — Page-level React components (\`phx.frontend.createCustomPhoenixLayoutElement()\`)
-  - \`ConfiguratorLayout\`: a layout element with this name replaces everything the built-in layout renders for a loaded configuration, in owner and read mode, finalization included. Prefer arranging the spec's layout components; write one for shell-level changes, such as moving the sidebar or adding an area the built-in layout has no place for
+- \`ConfiguratorLayout\`: a layout element with this name replaces everything the built-in layout renders for a loaded configuration, in owner and read mode, finalization included. Prefer this supported extension for composing the project's UI, reusing Phoenix layout slots, controls and hooks while keeping domain and component behavior in the spec
     - Mount \`LayoutSlots.SharedCanvas\` (from \`@salsita-ai/sdk/configurator\`) in a positioned root covering the page; put the UI above it, positioned and after it in the markup. With the canvas mounted the app loader waits until the scene has loaded; a layout without a canvas is not held by the loader. Call \`phx.frontend.useSceneSafeArea()\` and put \`containerRef\` on the element covering the whole canvas and \`safeAreaRef\` on the region the UI leaves free, with \`pointerEvents: 'none'\`, so the camera frames the scene there
     - Sidebar moved, contents as the spec configures them: mount \`LayoutSlots.DesktopSidebar\` in a positioned container that sets its size, with \`side="start"\` on the left; \`docs/layouts/sidebar/in-a-custom-layout.mdx\` is the whole layout
-    - Your own UI: "Hooks for a Project Layout" in \`docs/phoenix/configurator-interface.mdx\` lists the hooks with what each returns (\`pnpm phoenix docs -r docs/phoenix/configurator-interface.mdx\`), \`docs/phoenix/layout-slots.mdx\` the built-in pieces you can still mount, and \`docs/layouts/custom-layout.mdx\` is a worked example. Call the hooks as \`phx.frontend.useX()\`; besides those below, these are often needed: \`usePreview()\` (\`isPreview\` while the preview start screen shows), \`useCloseAction()\` (the host's close action or \`null\`), \`useActiveViewports()\` (the container's breakpoints, \`null\` until measured, \`desktop\` above 768 px: the desktop/phone switch), \`useResolveLocalizable()\` and \`useLocalizable(text)\` (spec texts to strings), \`useIsCloningAllowed()\` (a read-mode "edit a copy" action with \`LayoutSlots.CloneToEditDialog\`)
+    - Project UI: "Hooks for a Project Layout" in \`docs/phoenix/configurator-interface.mdx\` lists the hooks with what each returns (\`pnpm phoenix docs -r docs/phoenix/configurator-interface.mdx\`), \`docs/phoenix/layout-slots.mdx\` the built-in pieces you can still mount, and \`docs/layouts/custom-layout.mdx\` is a worked example. Call the hooks as \`phx.frontend.useX()\`; besides those below, these are often needed: \`usePreview()\` (\`isPreview\` while the preview start screen shows), \`useCloseAction()\` (the host's close action or \`null\`), \`useActiveViewports()\` (the container's breakpoints, \`null\` until measured, \`desktop\` above 768 px: the desktop/phone switch), \`useResolveLocalizable()\` and \`useLocalizable(text)\` (spec texts to strings), \`useIsCloningAllowed()\` (a read-mode "edit a copy" action with \`LayoutSlots.CloneToEditDialog\`)
     - Undo and redo: \`phx.frontend.useUndoRedo()\` returns \`{ canUndo, canRedo, undo, redo }\`; disable each button from \`canUndo\`/\`canRedo\`
     - Tabs: \`phx.frontend.useTabNavigation()\` returns \`{ source, tabs, activeTab, select }\` for the spec's \`sidebarTabs\` (of the selected entity) or \`horizontalTabs\`; render \`tabs\` (each \`{ index, label, icon, state, isActive }\`, \`icon\` a PhxIcon name) and call \`select(tab.index)\` on click. Pass \`{ source: 'sidebarTabs' }\` or \`{ source: 'horizontalTabs' }\` when the layout shows one kind only. Not \`LayoutSlots.useSidebarTabs()\`: it serves the built-in sidebar and returns no tabs while its summary shows
     - Steps: \`phx.frontend.useStepNavigation()\` returns \`{ steps, activeStep, activeIndex, isFirst, isLast, canGoNext, canGoPrevious, next, previous, goTo }\` for the spec's \`navigationSteps\`; render \`steps\` (each \`{ index, label, state, status }\`, \`status\` \`'complete' | 'active' | 'upcoming'\`), call \`next()\`/\`previous()\` for Back and Next and \`goTo(step.index)\` from a stepper. It enforces no order and no validity: enable only \`'complete'\` steps for an "earlier steps only" stepper, and to block moving on while the configuration has a problem, require \`phx.frontend.useStateValidity().severity !== 'warning'\` besides \`canGoNext\`: a change with a \`fixable\` or \`fatal\` violation is rejected, so the configuration is never invalid, and a \`warning\` is the problem that stays (it blocks finalizing too). \`useSteps\` and \`useHasSteps\` from \`@salsita-ai/sdk/configurator\` are deprecated
     - Messages: mount \`LayoutSlots.Services\` for the built-in snackbars, or show violations, side-effect hints, errors and failed saves yourself with \`phx.frontend.useConfiguratorMessages(onMessage)\`, not both. A failed save arrives as \`saveError\`, the next successful save as \`saveRecovery\`; a layout that mounts neither shows no sign of a failed save. Either way mount a snackbar root (\`LayoutSlots.DesktopSnackbarsRoot\` or \`LayoutSlots.MobileSnackbarsRoot\`): errors of the built-in actions are always snackbars
     - Finalize over the spec's \`finalizeAction\` components, each naming a handler registered with \`phx.frontend.createPhoenixHandler\`: \`phx.frontend.useFinalizeActions()\` returns \`{ actions, primary, secondary, disabled, hints }\`; render \`primary\` (and \`secondary\` in a menu or list) in a loop, each action \`{ key, label, title, icon, run, isPending, error, disabled }\`, and call \`action.run()\` on click (its promise never rejects; show \`action.error\` on failure). The configurator runs the handlers itself, outside the layout, so a handler must not rely on a provider the layout adds. For one known handler, \`phx.frontend.useFinalizeAction(handler)\` in a component wrapped in \`PhoenixHandlerBoundary\` (from \`@salsita-ai/sdk/react\`) works too; \`FinalizeActions\` (from \`@salsita-ai/sdk/configurator\`) mounts the built-in buttons. \`finalizePage\` and \`finalizeButton\` are legacy
     - Read mode and fullscreen are the layout's job, no hook enforces them (\`useUndoRedo\`, \`useFinalizeActions\` and \`useStepNavigation\` included): hide undo, redo, finalization and whatever else a viewer must not change while \`phx.frontend.useAccessService().accessInfo.viewMode\` is \`true\` (tabs are navigation, so a viewer may switch them), and remove panels while \`phx.frontend.useIsFullscreenActive()\` is set; \`phx.frontend.useSetFullscreen()\` returns its setter
-  - \`ConfigurationNotFoundPage\`: \`phx.frontend.createConfigurationNotFoundPage(({ onBack }) => …)\` replaces the "configuration not accessible" page; show a way back only when the optional \`onBack\` is set. The not-authenticated page's default renders it too; only the admin's not-authorized page keeps the built-in page
-  - \`ConfiguratorErrorPage\`: \`phx.frontend.createConfiguratorErrorPage(({ reason, onRetry }) => …)\` replaces the production error page; \`reason\` is \`uncaughtError\` or \`presetCreationFailed\`. A page that throws falls back to the built-in one, and development keeps the detailed error pages, so the project page shows only in a production build. Register both pages with these helpers: \`createCustomPhoenixLayoutElement\` with the name works too, but types the component as taking only \`children\`, so the typed props do not compile there in a strict project
-  - \`AppLoaderContent\`: \`phx.frontend.createAppLoader(({ phases }) => …)\` replaces what the loading overlay shows (each phase \`{ id, label?, progress? }\`, the list possibly empty); Phoenix keeps the overlay itself
-  - Assistant form elements: an element declared under \`assistant.formElements\` (\`description\`, \`role\`, scalar \`attributes\` beside the built-in \`label\`, a \`value\` included, \`required\`) is the default export \`phx.frontend.createAssistantFormElement('name', Component)\` of one file; the name types the component's props by its role (\`AssistantFormElementProps<'name'>\`): an option reports its answer with \`onSelect(answer)\`, an input with \`onChange(state, answer)\`; and the application does not start while a declared element has no registration or a registration no declaration
-- \`src/handlers/\` — Event & lifecycle handlers
-- \`src/webhooks/\` — Server-side webhook handlers (\`phx.webhooks.*Builder\`); the webhook is the default export of \`src/webhooks/index.ts\`, which you create when the project needs its own handlers — without it the build uses a built-in inert webhook that answers only anonymous auth, so create the file before setting \`useAuthHook\` or \`useClerk\`
-- \`src/migrations/\` — Schema version migrations (v*.ts)
-- \`src/locales/\` — Locale catalogs (authored .po sources; compiled .ts, do not edit)
-- \`src/admin/\` — Admin interface (mirrors main src/ structure)
-- \`src/_shared/\` — Shared utilities (NOT auto-imported, requires explicit imports)
-- \`.phoenix/\` — Auto-generated files (DO NOT EDIT, except the option files in \`.phoenix/variants/\`)
-- \`public/\` — Static assets (3D models, textures, images, HDRI maps, fonts)
-- \`assets/\` — Uploadable resources (PDF templates, email assets)`;
-    /** The YAML-first, ECS, reactive-state principles a project follows. */
-    readonly architecturePrinciples: `## Architecture Principles
-- YAML-first: 99% of configuration in spec/*.yaml, custom code is last resort
-- ECS pattern: entities (domain objects) + components (behavior/UI) + systems (SDK runtime)
-- Reactive state: immutable domain state flows through RxJS pipelines
-- Data binding: \`$read\` (read-only), \`$write\` (write-only), \`$bind\` (bidirectional) connect components to domain
-- memoEval: all component implementations must use memoEval for stable object references`;
-    /** Expressions, invariants, transformers, components, webhooks, and filters at a glance. */
-    readonly keyPatterns: `## Key Patterns
-- Expressions = computed properties on entities (prefix: \`$\`), implemented per-entity in src/expressions/
-- Actions = named domain operations (\`actions:\` in YAML with \`params\` and \`result\` schemas), implemented in src/actions/, prepared through \`actionSystem.prepareAction()\` and exposed as assistant mutations through \`assistant.actions\`
-- Invariants = validation rules returning violations, static or dynamic
-- Transformers = auto-fixers maintaining consistency after state changes
-- Components defined in YAML with \`$read\`/\`$bind\` bindings, or custom in src/components/ using attachComponent builder
-- Webhooks = server-side finalization tasks (PDF, email, CSV, image rendering)
-- Filters = contextual component activation via navigationStates, viewStates, modes, selectedEntityIds`;
-    /** File and folder naming rules. */
-    readonly fileConventions: `## File Conventions
-- Components: PascalCase (.tsx)
-- Utilities: kebab-case (.ts)
-- Expressions: entity-name.ts
-- Migrations: v*.ts (sequential)
-- Specs: kebab-case.yaml
-- Underscore folders (_shared/, _utils/) are NOT auto-imported`;
-    /** The default-export rule of the SDK auto-import system. */
-    readonly exportRules: `## Export Rules
-All files in src/expressions/, src/actions/, src/invariants/, src/transformers/, src/components/, src/handlers/, src/elements/, src/webhooks/ MUST use default exports. Can be a single item or an array. Named exports are ignored by the SDK auto-import system.
-The default export must be what the folder's phx factory returns (for example \`phx.frontend.createCustomPhoenixLayoutElement()\` in src/elements/). Any other value, such as a plain React component, stops the application at start with an "Invalid default export in <file>" error. Put plain components and helpers in an underscore folder.`;
+
+### Other project elements
+
+- \`ConfigurationNotFoundPage\`: \`phx.frontend.createConfigurationNotFoundPage(({ onBack }) => …)\` replaces the "configuration not accessible" page; show a way back only when the optional \`onBack\` is set. The not-authenticated page's default renders it too; only the admin's not-authorized page keeps the built-in page
+- \`ConfiguratorErrorPage\`: \`phx.frontend.createConfiguratorErrorPage(({ reason, onRetry }) => …)\` replaces the production error page; \`reason\` is \`uncaughtError\` or \`presetCreationFailed\`. A page that throws falls back to the built-in one, and development keeps the detailed error pages, so the project page shows only in a production build. Register both pages with these helpers: \`createCustomPhoenixLayoutElement\` with the name works too, but types the component as taking only \`children\`, so the typed props do not compile there in a strict project
+- Preset screen: \`phx.frontend.createPresetUi(Component)\` replaces the preset screen; inside it, \`phx.frontend.usePresetSelection()\` returns \`{ presetCategories, selectPreset, creatingPresetId, selectionError }\`. Keep the \`phx.frontend.usePreview().isPreview\` branch that renders \`PresetPreviewLayout\`, or an embedded configurator in preview mode never expands; \`docs/layouts/presets/custom.mdx\` is the complete screen
+- \`AppLoaderContent\`: \`phx.frontend.createAppLoader(({ phases }) => …)\` replaces what the loading overlay shows (each phase \`{ id, label?, progress? }\`, the list possibly empty); Phoenix keeps the overlay itself
+- Assistant form elements: an element declared under \`assistant.formElements\` (\`description\`, \`role\`, scalar \`attributes\` beside the built-in \`label\`, a \`value\` included, \`required\`) is the default export \`phx.frontend.createAssistantFormElement('name', Component)\` of one file; the name types the component's props by its role (\`AssistantFormElementProps<'name'>\`): an option reports its answer with \`onSelect(answer)\`, an input with \`onChange(state, answer)\`; and the application does not start while a declared element has no registration or a registration no declaration`;
     /** Which components and handlers are bundled into the webhook. */
-    readonly webhookMembership: `## Webhook Membership
-- User-authored components, admin components, and handlers are frontend-only by default.
+    readonly webhookMembership: `- Project components, admin components, and handlers are frontend-only by default.
 - A handler that registers \`phx.domain.createAssistantSetupHandler\`, \`createMapPublishedRevisionDataHandler\`, \`createMapPublishedChunkedDataHandler\`, \`createDataRowValidatorHandler\`, or \`createSheetValidatorHandler\` is included in the webhook automatically.
-- An assistant setup handler receives the declaration-shaped whitelist and { role, sessionData, access }. Keep the exact entity/alias split from YAML; inherited fields and expanded member entries are absent. Narrow original declarations, then the SDK expands them. Use project-defined role/session data for per-user customization. Keep the handler synchronous, pure and deterministic. The handler runs in the browser and webhook. Return null to disable assistant execution, or omit whitelist entries to restrict them. Button and panel visibility use spec presence; project developers own dynamic UI filtering through normal layout mechanics such as $filter. Leaves expose optional descriptions; writable options allow only validate: true and allowDryRuns: false; recipe groups allow descriptions and allowDryRuns: false; screenshot views allow descriptions. Deletable entries are {}. Names, component bindings, hints and types are internal. Omitted overrides retain baseline values. Existing entity, enhanced-entity and action types constrain the handler; no separate generated manifest types. Browser GraphQL, tools and change recording use the session-derived manifest; rejected setup fails closed. UI reads the pure spec selector. Omitted server instructions or AI fields preserve the baseline. An empty server instructions string clears it.
+- An assistant setup handler receives the declaration-shaped whitelist and { role, sessionData, access }. Keep the exact entity/alias split from YAML; inherited fields and expanded member entries are absent. Narrow original declarations, then the SDK expands them. Use project-defined role/session data for per-user customization. Keep the handler synchronous, pure and deterministic. The handler runs in the browser and webhook. In the browser its manifest has no instructions or ai, and what it returns for them is ignored, so never narrow the whitelist by manifest.ai: the browser schema would differ from the server's. Return null to disable assistant execution, or omit whitelist entries to restrict them. Button and panel visibility use spec presence; project developers own dynamic UI filtering through normal layout mechanics such as $filter. Leaves expose optional descriptions; writable options allow only validate: true and allowDryRuns: false; recipe groups allow descriptions and allowDryRuns: false; screenshot views allow descriptions. Deletable entries are {}. Names, component bindings, hints and types are internal. Omitted overrides retain baseline values. Existing entity, enhanced-entity and action types constrain the handler; no separate generated manifest types. Browser GraphQL, tools and change recording use the session-derived manifest; rejected setup fails closed. UI reads the pure spec selector. Omitted server instructions or AI fields preserve the baseline. An empty server instructions string clears it.
 - To include another component or handler in the webhook, put \`'use webhook'\` as its first statement (leading comments are allowed).
 - A webhook-included file and its runtime local-import closure must not import browser SDK entrypoints (\`application\`, \`admin\`, \`configurator\`, \`editor\`, \`react\`, \`ui\`) or style/font/image assets. Spec parsing reports the unsafe import and inclusion reason as a diagnostic.
 - Keep browser rendering in an unpinned file. Move shared server-safe logic into a separate module when both frontend and webhook code need it.`;
-    /** Generated files a project must not edit. */
-    readonly doNotEdit: `## Do Not Edit
-- \`.phoenix/\` directory — completely regenerated on each build. The one exception is \`.phoenix/variants/\`, where the \`phoenix-variants\` skill has you write option files; a rebuild keeps it. The project's TypeScript settings come from \`.phoenix/tsconfig.json\`; the root \`tsconfig.json\` is the project's and extends it. \`phoenix dev\`, \`phoenix build\` and the webhook bundle do not resolve \`paths\` aliases, so an alias added to the root file passes \`phoenix check\` and fails the build; use relative imports
-- \`src/locales/\` .ts files — compiled from .po files
-- \`phoenix\` and \`phoenix-*\` folders under \`.claude/skills/\` and \`.agents/skills/\` — Phoenix rewrites its skills on every sync, removes anything else inside their folders and removes any other \`phoenix-*\` skill folder. To customise a skill, copy it to a folder whose name does not start with \`phoenix\``;
-    /** When and how a deployed domain model gets a new version and a migration, with the recipe for replacing the starter. */
-    readonly modelVersioning: `## Version the Domain Model Once It Is Deployed
-A deployed model version cannot change, because saved configurations depend on it. \`pnpm phoenix deploy\` is refused, before anything is uploaded, when the model differs from the one already deployed under the same version. The version is not written anywhere: \`model.latest\` is always the highest numbered version plus one, so a spec with only \`latest\` is v1, and \`applicationVersion\` plays no part. \`pnpm phoenix dev\` accepts every model change, so a working preview does not show that the deploy will pass.
-
-To change a model that has been deployed as v<N>:
-1. Keep the deployed model, unchanged, as \`model.v<N>\` in the spec. A file of its own, such as \`spec/model-v<N>.yaml\`, keeps \`latest\` readable.
-2. Make the change in \`model.latest\`, which is now v<N+1>.
-3. Add \`src/migrations/v<N+1>.ts\` exporting \`migrateToV<N+1>\`. It receives the saved entities of v<N> and returns entities that are valid in v<N+1>; \`ModelV<N>\` and \`ModelV<N+1>\` are generated global namespaces.
-
-The admin model is versioned on its own, under \`src/admin/migrations/\`, with its types in \`AdminV<N>\`.
-
-**Replacing the starter.** When the first deployment of the workspace was the starter, its \`Box\` model is v1 in production. When the real model replaces it, keep the starter's model as \`model.v1\` and define the real model in \`latest\`. Configurations saved from the starter are not worth converting, so the migration returns the starting state of the new model, the \`initialDomainEntities\` of its preset, and drops the boxes:
-\`\`\`typescript
-// src/migrations/v2.ts
-import type { Migration } from '@salsita-ai/sdk/domain'
-
-export const migrateToV2: Migration<ModelV1.AnyDomainEntity, ModelV2.AnyDomainEntity> = () => [
-  // the entities of the new model's preset
-]
-\`\`\`
-An entity of a type the new version no longer has must not stay in the returned state. An entity id starts with its type (\`Box-1\`), so an entity that keeps its data under a new type name needs a new id and every relation pointing at it rewritten. Read \`docs/phoenix/migrations.mdx\` before writing any other migration.`;
-    /** How to find and read SDK documentation from the CLI. */
-    readonly sdkDocumentation: `## SDK Documentation
-
-Always search SDK docs for relevant examples before implementing Phoenix features.
-
-### Commands
-- \`pnpm phoenix docs\` — Full documentation index with descriptions
-- \`pnpm phoenix docs -s <term>\` — Search all doc content and metadata (case-insensitive)
-- \`pnpm phoenix docs --dir\` — Print the absolute docs directory for grep or ripgrep
-- \`pnpm phoenix docs -r <path>\` — Read specific doc (raw text to stdout)
-- \`pnpm phoenix docs -c <category>\` — List docs in a category
-- \`pnpm phoenix docs -l\` — List all doc paths with titles
-
-### Key Docs
-- \`docs/phoenix/getting-started.mdx\` — Setup, prerequisites, first project
-- \`docs/phoenix/quickstart.mdx\` — End-to-end tutorial building a configurator
-- \`docs/phoenix/domain-model.mdx\` — Entities, attributes, relations, specs
-- \`docs/phoenix/components.mdx\` — ECS pattern, YAML components, custom components
-- \`docs/phoenix/project-structure.mdx\` — Files, folders, conventions
-- \`docs/phoenix/best-practices.mdx\` — YAML-first, code patterns, common pitfalls
-- \`docs/phoenix/state-management.mdx\` — Reactive state, RxJS pipelines, data flow
-- \`docs/phoenix/expression-context.mdx\` — Expression API, context object, helpers
-- \`docs/phoenix/webhooks.mdx\` — Server-side finalization workflows
-- \`docs/phoenix/finalization.mdx\` — Finalization system, PDF/email/CSV generation
-- \`docs/phoenix/migrations.mdx\` — Schema versioning, migration files
-
-### Agent Workflow
-1. Find relevant docs by content: \`pnpm phoenix docs -s 'camera'\`
-2. Read matching doc: \`pnpm phoenix docs -r docs/3d-scene/cameras/transitions.mdx\`
-3. Search within a doc: \`pnpm phoenix docs -r <path> | grep "example"\`
-4. Search titles only as a fallback: \`pnpm phoenix docs -l | grep "camera"\`
-5. Search generated files directly when needed: \`grep -rn "camera" "$(pnpm phoenix docs --dir)"\`
-6. Browse a topic area: \`pnpm phoenix docs -c "Layouts"\``;
     /** The `inspect:assets` glTF inspection command. */
-    readonly assetInspection: `## 3D Asset Inspection
+    readonly assetInspection: `### 3D asset inspection
 
-Run \`pnpm phoenix inspect:assets\` to discover all glTF/GLB files in \`public/\` and get a summary table. Use \`--file <path>\` for detailed single-file inspection.
+Run \`pnpm phoenix inspect:assets\` to list every glTF or GLB file in \`public/\` in a summary table, and add \`--file <path>\` to inspect one file in detail. Run it before writing YAML or code that references \`objectName\`, \`materialsToOverride\`, \`morphTargetInfluences\` or object positions.
 
-**When to use:** before writing YAML/code that references objectName, materialsToOverride, morphTargetInfluences, or object positioning.
+For each node it shows:
 
-**What it shows per node:**
-- Name, type (Mesh/Light/Camera/Empty), children
-- Transform: \`pos=\`, \`rot=\`, \`scale=\` (only non-default values shown)
-- Per-node morph targets: \`morphs=Width,Height\`
-- Bounding box: \`bounds=WxHxD\` (width x height x depth in meters)
-- Origin placement: \`origin=center\`, \`bottom-center\`, \`top-center\`, \`bottom-corner\`, etc. with numerical offset
+- the name, the type (Mesh, Light, Camera or Empty) and the children;
+- the transform as \`pos=\`, \`rot=\` and \`scale=\`, with only non-default values;
+- morph targets, such as \`morphs=Width,Height\`;
+- the bounding box as \`bounds=WxHxD\`, width by height by depth in meters;
+- the origin placement, such as \`origin=center\`, \`bottom-center\`, \`top-center\` or \`bottom-corner\`, with its numerical offset.
 
-**Use cases:**
-- Find exact node names for \`objectName\` in scene entity components
-- Find material names for \`materialsToOverride\`
-- Find morph target names for \`morphTargetInfluences\`
-- Check model dimensions (bounds) for positioning, dimension indicators, or invariants
-- Check origin placement to understand how models anchor (center vs bottom-center)
-- Use \`--json\` for programmatic access to all data
-
-**Flags:** \`--objects\`, \`--materials\`, \`--morphs\`, \`--animations\`, \`--json\``;
-    /** The `screenshot` command. */
-    readonly screenshotCli: `## Screenshot CLI
+Use it to:
 
-Capture 3D canvas screenshots from a running dev server via \`pnpm phoenix screenshot\`.
+- find exact node names for \`objectName\` in scene entity components;
+- find material names for \`materialsToOverride\` and morph target names for \`morphTargetInfluences\`;
+- check model dimensions for positioning, dimension indicators or invariants;
+- check the origin placement to see how a model anchors, such as center or bottom-center.
 
-**Prerequisites:**
-1. \`phoenix dev\` must be running (starts the WebSocket server on port 3020)
-2. Configurator must be open in a browser (the browser does the actual rendering)
+Its flags are \`--objects\`, \`--materials\`, \`--morphs\`, \`--animations\`, and \`--json\` for programmatic access to all data.`;
+    /** The `screenshot` command. */
+    readonly screenshotCli: `### Screenshots
 
-**Options:**
-- \`--output, -o\` — Output file path (default: \`./screenshot.png\`)
-- \`--width, -w\` — Width in pixels (default: 1920)
-- \`--height\` — Height in pixels (default: 1080)
-- \`--format, -f\` — Image format: PNG or JPEG (default: PNG)
-- \`--port\` — WebSocket server port (default: 3020)
+\`pnpm phoenix screenshot\` captures the 3D canvas from the running preview, in the state the preview currently shows. It needs \`phoenix dev\` running, which starts the WebSocket server on port 3020, and the configurator open in a browser, which does the rendering.
 
-**Example workflow:**
-1. Start dev server: \`pnpm phoenix dev\`
-2. Open configurator in browser (or via Playwright MCP)
-3. Take screenshot: \`pnpm phoenix screenshot -o ./render.png -w 2560 --height 1440\`
+- \`--output\`, \`-o\` — output file path (default \`./screenshot.png\`)
+- \`--width\`, \`-w\` — width in pixels (default 1920)
+- \`--height\` — height in pixels (default 1080)
+- \`--format\`, \`-f\` — image format, PNG or JPEG (default PNG)
+- \`--port\` — WebSocket server port (default 3020)
 
-**Use cases:** visual regression testing, generating product images, debugging 3D renders`;
+For example, with \`pnpm phoenix dev\` running and the configurator open in a browser or through Playwright MCP, run \`pnpm phoenix screenshot -o ./render.png -w 2560 --height 1440\`. Use it for visual regression checks, product images and debugging 3D renders.`;
     /** The `inspect:state` command. */
-    readonly inspectState: `## Inspect: State
-
-Get the current editor runtime state as JSON via \`pnpm phoenix inspect:state\`.
+    readonly inspectState: `### Inspect state
 
-**Prerequisites:** same as screenshot (dev server running + browser open)
+\`pnpm phoenix inspect:state\` prints the current editor runtime state as JSON. Like screenshots, it needs dev running and the configurator open in a browser.
 
-**Options:**
-- \`--output, -o\` — Output file path (prints to stdout if omitted)
-- \`--sections, -s\` — Comma-separated: entities, navigation, validation (default: all)
-- \`--pretty\` — Pretty-print JSON (default: true)
-- \`--port\` — WebSocket server port (default: 3020)
+- \`--output\`, \`-o\` — output file path; prints to stdout when omitted
+- \`--sections\`, \`-s\` — comma-separated \`entities\`, \`navigation\` and \`validation\` (default all)
+- \`--pretty\` — pretty-print the JSON (default true)
+- \`--port\` — WebSocket server port (default 3020)
 
-**Example:** \`pnpm phoenix inspect:state -o ./state.json -s entities,navigation\`
+Every response includes the lifecycle status, which shows the systems that are ready:
 
-**Lifecycle status:** Always included in response. Shows which systems are ready:
 - \`domainLoaded\` — domain data loaded
-- \`domainContextReady\` — domain context initialized (entities available)
+- \`domainContextReady\` — domain context initialized, entities available
 - \`configuratorReady\` — 3D configurator initialized
 - \`sessionAuthenticated\` — session service active
 - \`editorMode\` — editor mode enabled
 
-**Tips:** Use \`--sections\` to limit payload size. Pipe through \`head\`/\`tail\` for partial output (e.g., \`pnpm phoenix inspect:state | head -50\`).
-
-**Use cases:** AI agent context, debugging entity state, inspecting navigation/validation`;
+For example, run \`pnpm phoenix inspect:state -o ./state.json -s entities,navigation\`. Limit the payload with \`--sections\`, or pipe through \`head\` or \`tail\` for partial output, such as \`pnpm phoenix inspect:state | head -50\`. Use it for agent context and for debugging entity state, navigation and validation.`;
     /** The `inspect:data` command. */
-    readonly inspectData: `## Inspect: Data
-
-Get the current editor context data as JSON via \`pnpm phoenix inspect:data\`.
+    readonly inspectData: `### Inspect data
 
-**Prerequisites:** same as screenshot (dev server running + browser open)
+\`pnpm phoenix inspect:data\` prints the current editor context data as JSON: \`publishedData\`, \`frontendData\`, \`backendData\`, \`sessionData\`, \`accessData\` and \`webComponentProperties\`. Like screenshots, it needs dev running and the configurator open in a browser.
 
-**Options:**
-- \`--output, -o\` — Output file path (prints to stdout if omitted)
-- \`--pretty\` — Pretty-print JSON (default: true)
-- \`--port\` — WebSocket server port (default: 3020)
+- \`--output\`, \`-o\` — output file path; prints to stdout when omitted
+- \`--pretty\` — pretty-print the JSON (default true)
+- \`--port\` — WebSocket server port (default 3020)
 
-**Returns:** publishedData, frontendData, backendData, sessionData, accessData, webComponentProperties
-
-**Example:** \`pnpm phoenix inspect:data -o ./data.json\`
-
-**Tips:** Pipe through \`head\`/\`tail\` for partial output (e.g., \`pnpm phoenix inspect:data | head -30\`).
-
-**Use cases:** AI agent context, debugging published/session/access data`;
+For example, run \`pnpm phoenix inspect:data -o ./data.json\`, or pipe through \`head\` or \`tail\` for partial output, such as \`pnpm phoenix inspect:data | head -30\`. Use it for agent context and for debugging published, session and access data.`;
     /** The `inspect:scene` command. */
-    readonly inspectScene: `## Inspect: Scene
-
-Get the current Three.js scene graph as JSON via \`pnpm phoenix inspect:scene\`.
-
-**Prerequisites:** same as screenshot (dev server running + browser open)
-
-**Options:**
-- \`--output, -o\` — Output file path (prints to stdout if omitted)
-- \`--pretty\` — Pretty-print JSON (default: true)
-- \`--port\` — WebSocket server port (default: 3020)
-
-**Returns:** Recursive scene tree with per-node: name, type, visible, position, rotation, scale, userData (entityId), and for meshes: geometry name, bounding box, material properties (color, metalness, roughness, opacity, textures), morph target influences. Lights include color, intensity, and type-specific properties.
-
-**Example:** \`pnpm phoenix inspect:scene -o ./scene.json\`
-
-**Tips:** Scene graphs can be large. Pipe through \`head\`/\`tail\` for partial output.
+    readonly inspectScene: `### Inspect scene
 
-**Use cases:** AI agent context, debugging 3D scene layout, inspecting materials and lighting`;
-    /** The `variants` command; the `phoenix-variants` skill holds the workflow and the options. */
-    readonly variantPreviews: `## Variant Previews
+\`pnpm phoenix inspect:scene\` prints the current Three.js scene graph as JSON: a recursive tree with each node's name, type, visibility, position, rotation, scale and \`userData\` (\`entityId\`). Meshes add the geometry name, bounding box, material properties (color, metalness, roughness, opacity, textures) and morph target influences; lights add color, intensity and type-specific properties. Like screenshots, it needs dev running and the configurator open in a browser.
 
-Show the user several options over the configurator and get their pick back via \`pnpm phoenix variants .phoenix/variants/<name>\`. Use it when a visual or interaction decision is a matter of the user's taste. Load the \`phoenix-variants\` skill first: it says when to offer options, how to write them and which flags the command takes.
+- \`--output\`, \`-o\` — output file path; prints to stdout when omitted
+- \`--pretty\` — pretty-print the JSON (default true)
+- \`--port\` — WebSocket server port (default 3020)
 
-**Prerequisites:** same as screenshot (dev server running + browser open)
-
-**Input:** a folder below \`.phoenix/variants/\` with one file per option: \`<id>.variant.js\` for a script that edits frontend files from a captured baseline, or \`<id>.html\` for a standalone iframe proposal. A selected HTML proposal is returned for you to implement. Options run one at a time through normal hot reload; Original always restores the baseline; picking an option keeps its edits, and the agent can use \`--close\` to restore the baseline without an answer.
-
-**Returns:** JSON with \`status\`: \`chosen\` (with \`choice\`, or \`null\` for Original, and \`label\`), \`waiting\` (the wait ran out and the preview stays open; run the same command again) or \`closed\`.`;
+For example, run \`pnpm phoenix inspect:scene -o ./scene.json\`. Scene graphs can be large, so pipe through \`head\` or \`tail\` for partial output. Use it for agent context and for debugging scene layout, materials and lighting.`;
     /** Browser automation setup for agents driving the 3D configurator. */
-    readonly playwrightMcpSetup: `## Playwright MCP Setup (for AI agents)
+    readonly playwrightMcpSetup: `### Playwright MCP setup
 
 To interact with the 3D configurator in a browser, Playwright MCP needs GPU-enabled flags for WebGL rendering. Add to \`~/.claude/.mcp.json\`:
 
@@ -296,24 +126,8 @@ To interact with the 3D configurator in a browser, Playwright MCP needs GPU-enab
 }
 \`\`\`
 
-Key flags:
+These flags make WebGL rendering work:
 - \`--headed\` — visible browser (required for GPU rendering)
 - \`--use-gl=swiftshader\` — software GPU fallback for environments without a physical GPU
 - \`--enable-webgl\` + \`--ignore-gpu-blocklist\` — ensure WebGL is available`;
-    readonly visualInspection: `## Visual inspection
-Apply this whenever a change can alter what the canvas or the interface shows: geometry, materials, scene, layout, controls, or the data behind any of them. When a change cannot affect the rendered result, say so rather than passing over this silently.
-
-Rendered appearance is a deliverable, not a side effect. Before presenting any preview, and before reporting work as complete, open the configuration that best represents the product at desktop width, wait for it to finish loading, look at it, and report what you found. Report what you saw, not whether it passed. State the observation each judgement rests on: “nothing floats” is a verdict, “the casters meet the floor and the shadow lies under them” is an observation. A result you have not looked at is unverified, whatever the automated checks say.
-
-Inspect and report:
-
-1. Geometry. Every part rests on its support. Name where the product meets the ground and confirm its shadow and any selection indicator sit there too. Nothing floats, intersects, or protrudes. Scale and orientation are consistent between parts and match the stated dimensions. Each part is complete and present.
-2. Response. Every configurable surface of every part reacts to its control, not only the parts you just changed.
-3. Loading. How long until a meaningful first frame, and whether anything indicates progress meanwhile.
-
-This covers what follows from the change you just made, in the state you are already in. Fidelity against the client's own material, the density of the controls, and every state you did not open belong to an independent reviewer, which the \`phoenix-create-configurator\` skill's Appearance review covers.
-
-Report defects you are deferring as defects. Do not call work done, verified, or complete while any of the above is unchecked or failing: say which, and recommend fixing now or later.
-
-Record the result of each point above in the specification alongside the increment it belongs to, with the viewport you used. An inspection nobody can read afterwards is indistinguishable from one that never happened.`;
 };

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

@@ -1,44 +1,4 @@
-export const sdkGuidanceSections={packageManager:"## Package Manager\nThe project installs with its own package manager, and the commands in this skill are written for pnpm. Run them through the package manager the project uses, which the lockfile in the project root names:\n- `pnpm-lock.yaml`: `pnpm phoenix <command>`, `pnpm install`, `pnpm add <package>`\n- `package-lock.json`: `npx phoenix <command>`, `npm install`, `npm install <package>`\n- `yarn.lock`: `yarn phoenix <command>`, `yarn install`, `yarn add <package>`\n- `bun.lock` or `bun.lockb`: `bunx phoenix <command>`, `bun install`, `bun add <package>`\n\nWithout a lockfile, use the package manager the `packageManager` field of `package.json` names, or ask the user.",buildCommands:"## Build Commands\n- `pnpm phoenix build` — Full production build\n- `pnpm phoenix dev` — Development mode with hot reload\n- `pnpm phoenix sync` — Sync generated files without full build\n- `pnpm phoenix deps` — Add the SDK's missing peer dependencies to `package.json` and move out-of-range ones into the SDK's range; it installs nothing, so install after it",devLogs:"## Dev Logs\n- `pnpm phoenix dev` writes all logs to `.phoenix/phoenix-dev.log`\n- Contains: spec parse errors, build errors, browser runtime errors, file watcher events\n- After making changes, always check the log for errors: `tail -50 .phoenix/phoenix-dev.log` or `grep ERROR .phoenix/phoenix-dev.log`\n- Rotated automatically at 10MB (`.log.1`, `.log.2` are older rotations)",projectStructure:"## Project Structure\n- `spec/` — Domain YAML specs (entities, relations, expressions, invariants, components, application config)\n- `src/expressions/` — Computed/derived entity properties (`phx.domain.implementCustomExpressions()`)\n- `src/actions/` — Domain operations declared under `actions:` in the spec (`phx.domain.implementActions()`), run by controls and exposed to the assistant\n- `src/invariants/` — Business rule constraints (`phx.domain.implementCustomInvariants()`)\n- `src/transformers/` — Automatic state fixers (`phx.frontend.transformerBuilder`)\n- `src/components/` — ECS system components (`phx.domain.attachComponent.withEntity()`)\n- `src/elements/` — Page-level React components (`phx.frontend.createCustomPhoenixLayoutElement()`)\n  - `ConfiguratorLayout`: a layout element with this name replaces everything the built-in layout renders for a loaded configuration, in owner and read mode, finalization included. Prefer arranging the spec's layout components; write one for shell-level changes, such as moving the sidebar or adding an area the built-in layout has no place for\n    - Mount `LayoutSlots.SharedCanvas` (from `@salsita-ai/sdk/configurator`) in a positioned root covering the page; put the UI above it, positioned and after it in the markup. With the canvas mounted the app loader waits until the scene has loaded; a layout without a canvas is not held by the loader. Call `phx.frontend.useSceneSafeArea()` and put `containerRef` on the element covering the whole canvas and `safeAreaRef` on the region the UI leaves free, with `pointerEvents: 'none'`, so the camera frames the scene there\n    - Sidebar moved, contents as the spec configures them: mount `LayoutSlots.DesktopSidebar` in a positioned container that sets its size, with `side=\"start\"` on the left; `docs/layouts/sidebar/in-a-custom-layout.mdx` is the whole layout\n    - Your own UI: \"Hooks for a Project Layout\" in `docs/phoenix/configurator-interface.mdx` lists the hooks with what each returns (`pnpm phoenix docs -r docs/phoenix/configurator-interface.mdx`), `docs/phoenix/layout-slots.mdx` the built-in pieces you can still mount, and `docs/layouts/custom-layout.mdx` is a worked example. Call the hooks as `phx.frontend.useX()`; besides those below, these are often needed: `usePreview()` (`isPreview` while the preview start screen shows), `useCloseAction()` (the host's close action or `null`), `useActiveViewports()` (the container's breakpoints, `null` until measured, `desktop` above 768 px: the desktop/phone switch), `useResolveLocalizable()` and `useLocalizable(text)` (spec texts to strings), `useIsCloningAllowed()` (a read-mode \"edit a copy\" action with `LayoutSlots.CloneToEditDialog`)\n    - Undo and redo: `phx.frontend.useUndoRedo()` returns `{ canUndo, canRedo, undo, redo }`; disable each button from `canUndo`/`canRedo`\n    - Tabs: `phx.frontend.useTabNavigation()` returns `{ source, tabs, activeTab, select }` for the spec's `sidebarTabs` (of the selected entity) or `horizontalTabs`; render `tabs` (each `{ index, label, icon, state, isActive }`, `icon` a PhxIcon name) and call `select(tab.index)` on click. Pass `{ source: 'sidebarTabs' }` or `{ source: 'horizontalTabs' }` when the layout shows one kind only. Not `LayoutSlots.useSidebarTabs()`: it serves the built-in sidebar and returns no tabs while its summary shows\n    - Steps: `phx.frontend.useStepNavigation()` returns `{ steps, activeStep, activeIndex, isFirst, isLast, canGoNext, canGoPrevious, next, previous, goTo }` for the spec's `navigationSteps`; render `steps` (each `{ index, label, state, status }`, `status` `'complete' | 'active' | 'upcoming'`), call `next()`/`previous()` for Back and Next and `goTo(step.index)` from a stepper. It enforces no order and no validity: enable only `'complete'` steps for an \"earlier steps only\" stepper, and to block moving on while the configuration has a problem, require `phx.frontend.useStateValidity().severity !== 'warning'` besides `canGoNext`: a change with a `fixable` or `fatal` violation is rejected, so the configuration is never invalid, and a `warning` is the problem that stays (it blocks finalizing too). `useSteps` and `useHasSteps` from `@salsita-ai/sdk/configurator` are deprecated\n    - Messages: mount `LayoutSlots.Services` for the built-in snackbars, or show violations, side-effect hints, errors and failed saves yourself with `phx.frontend.useConfiguratorMessages(onMessage)`, not both. A failed save arrives as `saveError`, the next successful save as `saveRecovery`; a layout that mounts neither shows no sign of a failed save. Either way mount a snackbar root (`LayoutSlots.DesktopSnackbarsRoot` or `LayoutSlots.MobileSnackbarsRoot`): errors of the built-in actions are always snackbars\n    - Finalize over the spec's `finalizeAction` components, each naming a handler registered with `phx.frontend.createPhoenixHandler`: `phx.frontend.useFinalizeActions()` returns `{ actions, primary, secondary, disabled, hints }`; render `primary` (and `secondary` in a menu or list) in a loop, each action `{ key, label, title, icon, run, isPending, error, disabled }`, and call `action.run()` on click (its promise never rejects; show `action.error` on failure). The configurator runs the handlers itself, outside the layout, so a handler must not rely on a provider the layout adds. For one known handler, `phx.frontend.useFinalizeAction(handler)` in a component wrapped in `PhoenixHandlerBoundary` (from `@salsita-ai/sdk/react`) works too; `FinalizeActions` (from `@salsita-ai/sdk/configurator`) mounts the built-in buttons. `finalizePage` and `finalizeButton` are legacy\n    - Read mode and fullscreen are the layout's job, no hook enforces them (`useUndoRedo`, `useFinalizeActions` and `useStepNavigation` included): hide undo, redo, finalization and whatever else a viewer must not change while `phx.frontend.useAccessService().accessInfo.viewMode` is `true` (tabs are navigation, so a viewer may switch them), and remove panels while `phx.frontend.useIsFullscreenActive()` is set; `phx.frontend.useSetFullscreen()` returns its setter\n  - `ConfigurationNotFoundPage`: `phx.frontend.createConfigurationNotFoundPage(({ onBack }) => …)` replaces the \"configuration not accessible\" page; show a way back only when the optional `onBack` is set. The not-authenticated page's default renders it too; only the admin's not-authorized page keeps the built-in page\n  - `ConfiguratorErrorPage`: `phx.frontend.createConfiguratorErrorPage(({ reason, onRetry }) => …)` replaces the production error page; `reason` is `uncaughtError` or `presetCreationFailed`. A page that throws falls back to the built-in one, and development keeps the detailed error pages, so the project page shows only in a production build. Register both pages with these helpers: `createCustomPhoenixLayoutElement` with the name works too, but types the component as taking only `children`, so the typed props do not compile there in a strict project\n  - `AppLoaderContent`: `phx.frontend.createAppLoader(({ phases }) => …)` replaces what the loading overlay shows (each phase `{ id, label?, progress? }`, the list possibly empty); Phoenix keeps the overlay itself\n  - Assistant form elements: an element declared under `assistant.formElements` (`description`, `role`, scalar `attributes` beside the built-in `label`, a `value` included, `required`) is the default export `phx.frontend.createAssistantFormElement('name', Component)` of one file; the name types the component's props by its role (`AssistantFormElementProps<'name'>`): an option reports its answer with `onSelect(answer)`, an input with `onChange(state, answer)`; and the application does not start while a declared element has no registration or a registration no declaration\n- `src/handlers/` — Event & lifecycle handlers\n- `src/webhooks/` — Server-side webhook handlers (`phx.webhooks.*Builder`); the webhook is the default export of `src/webhooks/index.ts`, which you create when the project needs its own handlers — without it the build uses a built-in inert webhook that answers only anonymous auth, so create the file before setting `useAuthHook` or `useClerk`\n- `src/migrations/` — Schema version migrations (v*.ts)\n- `src/locales/` — Locale catalogs (authored .po sources; compiled .ts, do not edit)\n- `src/admin/` — Admin interface (mirrors main src/ structure)\n- `src/_shared/` — Shared utilities (NOT auto-imported, requires explicit imports)\n- `.phoenix/` — Auto-generated files (DO NOT EDIT, except the option files in `.phoenix/variants/`)\n- `public/` — Static assets (3D models, textures, images, HDRI maps, fonts)\n- `assets/` — Uploadable resources (PDF templates, email assets)",architecturePrinciples:"## Architecture Principles\n- YAML-first: 99% of configuration in spec/*.yaml, custom code is last resort\n- ECS pattern: entities (domain objects) + components (behavior/UI) + systems (SDK runtime)\n- Reactive state: immutable domain state flows through RxJS pipelines\n- Data binding: `$read` (read-only), `$write` (write-only), `$bind` (bidirectional) connect components to domain\n- memoEval: all component implementations must use memoEval for stable object references",keyPatterns:"## Key Patterns\n- Expressions = computed properties on entities (prefix: `$`), implemented per-entity in src/expressions/\n- Actions = named domain operations (`actions:` in YAML with `params` and `result` schemas), implemented in src/actions/, prepared through `actionSystem.prepareAction()` and exposed as assistant mutations through `assistant.actions`\n- Invariants = validation rules returning violations, static or dynamic\n- Transformers = auto-fixers maintaining consistency after state changes\n- Components defined in YAML with `$read`/`$bind` bindings, or custom in src/components/ using attachComponent builder\n- Webhooks = server-side finalization tasks (PDF, email, CSV, image rendering)\n- Filters = contextual component activation via navigationStates, viewStates, modes, selectedEntityIds",fileConventions:`## File Conventions
-- Components: PascalCase (.tsx)
-- Utilities: kebab-case (.ts)
-- Expressions: entity-name.ts
-- Migrations: v*.ts (sequential)
-- Specs: kebab-case.yaml
-- Underscore folders (_shared/, _utils/) are NOT auto-imported`,exportRules:'## Export Rules\nAll files in src/expressions/, src/actions/, src/invariants/, src/transformers/, src/components/, src/handlers/, src/elements/, src/webhooks/ MUST use default exports. Can be a single item or an array. Named exports are ignored by the SDK auto-import system.\nThe default export must be what the folder\'s phx factory returns (for example `phx.frontend.createCustomPhoenixLayoutElement()` in src/elements/). Any other value, such as a plain React component, stops the application at start with an "Invalid default export in <file>" error. Put plain components and helpers in an underscore folder.',webhookMembership:"## Webhook Membership\n- User-authored components, admin components, and handlers are frontend-only by default.\n- A handler that registers `phx.domain.createAssistantSetupHandler`, `createMapPublishedRevisionDataHandler`, `createMapPublishedChunkedDataHandler`, `createDataRowValidatorHandler`, or `createSheetValidatorHandler` is included in the webhook automatically.\n- An assistant setup handler receives the declaration-shaped whitelist and { role, sessionData, access }. Keep the exact entity/alias split from YAML; inherited fields and expanded member entries are absent. Narrow original declarations, then the SDK expands them. Use project-defined role/session data for per-user customization. Keep the handler synchronous, pure and deterministic. The handler runs in the browser and webhook. Return null to disable assistant execution, or omit whitelist entries to restrict them. Button and panel visibility use spec presence; project developers own dynamic UI filtering through normal layout mechanics such as $filter. Leaves expose optional descriptions; writable options allow only validate: true and allowDryRuns: false; recipe groups allow descriptions and allowDryRuns: false; screenshot views allow descriptions. Deletable entries are {}. Names, component bindings, hints and types are internal. Omitted overrides retain baseline values. Existing entity, enhanced-entity and action types constrain the handler; no separate generated manifest types. Browser GraphQL, tools and change recording use the session-derived manifest; rejected setup fails closed. UI reads the pure spec selector. Omitted server instructions or AI fields preserve the baseline. An empty server instructions string clears it.\n- To include another component or handler in the webhook, put `'use webhook'` as its first statement (leading comments are allowed).\n- A webhook-included file and its runtime local-import closure must not import browser SDK entrypoints (`application`, `admin`, `configurator`, `editor`, `react`, `ui`) or style/font/image assets. Spec parsing reports the unsafe import and inclusion reason as a diagnostic.\n- Keep browser rendering in an unpinned file. Move shared server-safe logic into a separate module when both frontend and webhook code need it.",doNotEdit:"## Do Not Edit\n- `.phoenix/` directory — completely regenerated on each build. The one exception is `.phoenix/variants/`, where the `phoenix-variants` skill has you write option files; a rebuild keeps it. The project's TypeScript settings come from `.phoenix/tsconfig.json`; the root `tsconfig.json` is the project's and extends it. `phoenix dev`, `phoenix build` and the webhook bundle do not resolve `paths` aliases, so an alias added to the root file passes `phoenix check` and fails the build; use relative imports\n- `src/locales/` .ts files — compiled from .po files\n- `phoenix` and `phoenix-*` folders under `.claude/skills/` and `.agents/skills/` — Phoenix rewrites its skills on every sync, removes anything else inside their folders and removes any other `phoenix-*` skill folder. To customise a skill, copy it to a folder whose name does not start with `phoenix`",modelVersioning:"## Version the Domain Model Once It Is Deployed\nA deployed model version cannot change, because saved configurations depend on it. `pnpm phoenix deploy` is refused, before anything is uploaded, when the model differs from the one already deployed under the same version. The version is not written anywhere: `model.latest` is always the highest numbered version plus one, so a spec with only `latest` is v1, and `applicationVersion` plays no part. `pnpm phoenix dev` accepts every model change, so a working preview does not show that the deploy will pass.\n\nTo change a model that has been deployed as v<N>:\n1. Keep the deployed model, unchanged, as `model.v<N>` in the spec. A file of its own, such as `spec/model-v<N>.yaml`, keeps `latest` readable.\n2. Make the change in `model.latest`, which is now v<N+1>.\n3. Add `src/migrations/v<N+1>.ts` exporting `migrateToV<N+1>`. It receives the saved entities of v<N> and returns entities that are valid in v<N+1>; `ModelV<N>` and `ModelV<N+1>` are generated global namespaces.\n\nThe admin model is versioned on its own, under `src/admin/migrations/`, with its types in `AdminV<N>`.\n\n**Replacing the starter.** When the first deployment of the workspace was the starter, its `Box` model is v1 in production. When the real model replaces it, keep the starter's model as `model.v1` and define the real model in `latest`. Configurations saved from the starter are not worth converting, so the migration returns the starting state of the new model, the `initialDomainEntities` of its preset, and drops the boxes:\n```typescript\n// src/migrations/v2.ts\nimport type { Migration } from '@salsita-ai/sdk/domain'\n\nexport const migrateToV2: Migration<ModelV1.AnyDomainEntity, ModelV2.AnyDomainEntity> = () => [\n  // the entities of the new model's preset\n]\n```\nAn entity of a type the new version no longer has must not stay in the returned state. An entity id starts with its type (`Box-1`), so an entity that keeps its data under a new type name needs a new id and every relation pointing at it rewritten. Read `docs/phoenix/migrations.mdx` before writing any other migration.",sdkDocumentation:'## SDK Documentation\n\nAlways search SDK docs for relevant examples before implementing Phoenix features.\n\n### Commands\n- `pnpm phoenix docs` — Full documentation index with descriptions\n- `pnpm phoenix docs -s <term>` — Search all doc content and metadata (case-insensitive)\n- `pnpm phoenix docs --dir` — Print the absolute docs directory for grep or ripgrep\n- `pnpm phoenix docs -r <path>` — Read specific doc (raw text to stdout)\n- `pnpm phoenix docs -c <category>` — List docs in a category\n- `pnpm phoenix docs -l` — List all doc paths with titles\n\n### Key Docs\n- `docs/phoenix/getting-started.mdx` — Setup, prerequisites, first project\n- `docs/phoenix/quickstart.mdx` — End-to-end tutorial building a configurator\n- `docs/phoenix/domain-model.mdx` — Entities, attributes, relations, specs\n- `docs/phoenix/components.mdx` — ECS pattern, YAML components, custom components\n- `docs/phoenix/project-structure.mdx` — Files, folders, conventions\n- `docs/phoenix/best-practices.mdx` — YAML-first, code patterns, common pitfalls\n- `docs/phoenix/state-management.mdx` — Reactive state, RxJS pipelines, data flow\n- `docs/phoenix/expression-context.mdx` — Expression API, context object, helpers\n- `docs/phoenix/webhooks.mdx` — Server-side finalization workflows\n- `docs/phoenix/finalization.mdx` — Finalization system, PDF/email/CSV generation\n- `docs/phoenix/migrations.mdx` — Schema versioning, migration files\n\n### Agent Workflow\n1. Find relevant docs by content: `pnpm phoenix docs -s \'camera\'`\n2. Read matching doc: `pnpm phoenix docs -r docs/3d-scene/cameras/transitions.mdx`\n3. Search within a doc: `pnpm phoenix docs -r <path> | grep "example"`\n4. Search titles only as a fallback: `pnpm phoenix docs -l | grep "camera"`\n5. Search generated files directly when needed: `grep -rn "camera" "$(pnpm phoenix docs --dir)"`\n6. Browse a topic area: `pnpm phoenix docs -c "Layouts"`',assetInspection:"## 3D Asset Inspection\n\nRun `pnpm phoenix inspect:assets` to discover all glTF/GLB files in `public/` and get a summary table. Use `--file <path>` for detailed single-file inspection.\n\n**When to use:** before writing YAML/code that references objectName, materialsToOverride, morphTargetInfluences, or object positioning.\n\n**What it shows per node:**\n- Name, type (Mesh/Light/Camera/Empty), children\n- Transform: `pos=`, `rot=`, `scale=` (only non-default values shown)\n- Per-node morph targets: `morphs=Width,Height`\n- Bounding box: `bounds=WxHxD` (width x height x depth in meters)\n- Origin placement: `origin=center`, `bottom-center`, `top-center`, `bottom-corner`, etc. with numerical offset\n\n**Use cases:**\n- Find exact node names for `objectName` in scene entity components\n- Find material names for `materialsToOverride`\n- Find morph target names for `morphTargetInfluences`\n- Check model dimensions (bounds) for positioning, dimension indicators, or invariants\n- Check origin placement to understand how models anchor (center vs bottom-center)\n- Use `--json` for programmatic access to all data\n\n**Flags:** `--objects`, `--materials`, `--morphs`, `--animations`, `--json`",screenshotCli:"## Screenshot CLI\n\nCapture 3D canvas screenshots from a running dev server via `pnpm phoenix screenshot`.\n\n**Prerequisites:**\n1. `phoenix dev` must be running (starts the WebSocket server on port 3020)\n2. Configurator must be open in a browser (the browser does the actual rendering)\n\n**Options:**\n- `--output, -o` — Output file path (default: `./screenshot.png`)\n- `--width, -w` — Width in pixels (default: 1920)\n- `--height` — Height in pixels (default: 1080)\n- `--format, -f` — Image format: PNG or JPEG (default: PNG)\n- `--port` — WebSocket server port (default: 3020)\n\n**Example workflow:**\n1. Start dev server: `pnpm phoenix dev`\n2. Open configurator in browser (or via Playwright MCP)\n3. Take screenshot: `pnpm phoenix screenshot -o ./render.png -w 2560 --height 1440`\n\n**Use cases:** visual regression testing, generating product images, debugging 3D renders",inspectState:"## Inspect: State\n\nGet the current editor runtime state as JSON via `pnpm phoenix inspect:state`.\n\n**Prerequisites:** same as screenshot (dev server running + browser open)\n\n**Options:**\n- `--output, -o` — Output file path (prints to stdout if omitted)\n- `--sections, -s` — Comma-separated: entities, navigation, validation (default: all)\n- `--pretty` — Pretty-print JSON (default: true)\n- `--port` — WebSocket server port (default: 3020)\n\n**Example:** `pnpm phoenix inspect:state -o ./state.json -s entities,navigation`\n\n**Lifecycle status:** Always included in response. Shows which systems are ready:\n- `domainLoaded` — domain data loaded\n- `domainContextReady` — domain context initialized (entities available)\n- `configuratorReady` — 3D configurator initialized\n- `sessionAuthenticated` — session service active\n- `editorMode` — editor mode enabled\n\n**Tips:** Use `--sections` to limit payload size. Pipe through `head`/`tail` for partial output (e.g., `pnpm phoenix inspect:state | head -50`).\n\n**Use cases:** AI agent context, debugging entity state, inspecting navigation/validation",inspectData:`## Inspect: Data
-
-Get the current editor context data as JSON via \`pnpm phoenix inspect:data\`.
-
-**Prerequisites:** same as screenshot (dev server running + browser open)
-
-**Options:**
-- \`--output, -o\` — Output file path (prints to stdout if omitted)
-- \`--pretty\` — Pretty-print JSON (default: true)
-- \`--port\` — WebSocket server port (default: 3020)
-
-**Returns:** publishedData, frontendData, backendData, sessionData, accessData, webComponentProperties
-
-**Example:** \`pnpm phoenix inspect:data -o ./data.json\`
-
-**Tips:** Pipe through \`head\`/\`tail\` for partial output (e.g., \`pnpm phoenix inspect:data | head -30\`).
-
-**Use cases:** AI agent context, debugging published/session/access data`,inspectScene:`## Inspect: Scene
-
-Get the current Three.js scene graph as JSON via \`pnpm phoenix inspect:scene\`.
-
-**Prerequisites:** same as screenshot (dev server running + browser open)
-
-**Options:**
-- \`--output, -o\` — Output file path (prints to stdout if omitted)
-- \`--pretty\` — Pretty-print JSON (default: true)
-- \`--port\` — WebSocket server port (default: 3020)
-
-**Returns:** Recursive scene tree with per-node: name, type, visible, position, rotation, scale, userData (entityId), and for meshes: geometry name, bounding box, material properties (color, metalness, roughness, opacity, textures), morph target influences. Lights include color, intensity, and type-specific properties.
-
-**Example:** \`pnpm phoenix inspect:scene -o ./scene.json\`
-
-**Tips:** Scene graphs can be large. Pipe through \`head\`/\`tail\` for partial output.
-
-**Use cases:** AI agent context, debugging 3D scene layout, inspecting materials and lighting`,variantPreviews:"## Variant Previews\n\nShow the user several options over the configurator and get their pick back via `pnpm phoenix variants .phoenix/variants/<name>`. Use it when a visual or interaction decision is a matter of the user's taste. Load the `phoenix-variants` skill first: it says when to offer options, how to write them and which flags the command takes.\n\n**Prerequisites:** same as screenshot (dev server running + browser open)\n\n**Input:** a folder below `.phoenix/variants/` with one file per option: `<id>.variant.js` for a script that edits frontend files from a captured baseline, or `<id>.html` for a standalone iframe proposal. A selected HTML proposal is returned for you to implement. Options run one at a time through normal hot reload; Original always restores the baseline; picking an option keeps its edits, and the agent can use `--close` to restore the baseline without an answer.\n\n**Returns:** JSON with `status`: `chosen` (with `choice`, or `null` for Original, and `label`), `waiting` (the wait ran out and the preview stays open; run the same command again) or `closed`.",playwrightMcpSetup:`## Playwright MCP Setup (for AI agents)
+export const sdkGuidanceSections={customLayout:"### ConfiguratorLayout\n\n- `ConfiguratorLayout`: a layout element with this name replaces everything the built-in layout renders for a loaded configuration, in owner and read mode, finalization included. Prefer this supported extension for composing the project's UI, reusing Phoenix layout slots, controls and hooks while keeping domain and component behavior in the spec\n    - Mount `LayoutSlots.SharedCanvas` (from `@salsita-ai/sdk/configurator`) in a positioned root covering the page; put the UI above it, positioned and after it in the markup. With the canvas mounted the app loader waits until the scene has loaded; a layout without a canvas is not held by the loader. Call `phx.frontend.useSceneSafeArea()` and put `containerRef` on the element covering the whole canvas and `safeAreaRef` on the region the UI leaves free, with `pointerEvents: 'none'`, so the camera frames the scene there\n    - Sidebar moved, contents as the spec configures them: mount `LayoutSlots.DesktopSidebar` in a positioned container that sets its size, with `side=\"start\"` on the left; `docs/layouts/sidebar/in-a-custom-layout.mdx` is the whole layout\n    - Project UI: \"Hooks for a Project Layout\" in `docs/phoenix/configurator-interface.mdx` lists the hooks with what each returns (`pnpm phoenix docs -r docs/phoenix/configurator-interface.mdx`), `docs/phoenix/layout-slots.mdx` the built-in pieces you can still mount, and `docs/layouts/custom-layout.mdx` is a worked example. Call the hooks as `phx.frontend.useX()`; besides those below, these are often needed: `usePreview()` (`isPreview` while the preview start screen shows), `useCloseAction()` (the host's close action or `null`), `useActiveViewports()` (the container's breakpoints, `null` until measured, `desktop` above 768 px: the desktop/phone switch), `useResolveLocalizable()` and `useLocalizable(text)` (spec texts to strings), `useIsCloningAllowed()` (a read-mode \"edit a copy\" action with `LayoutSlots.CloneToEditDialog`)\n    - Undo and redo: `phx.frontend.useUndoRedo()` returns `{ canUndo, canRedo, undo, redo }`; disable each button from `canUndo`/`canRedo`\n    - Tabs: `phx.frontend.useTabNavigation()` returns `{ source, tabs, activeTab, select }` for the spec's `sidebarTabs` (of the selected entity) or `horizontalTabs`; render `tabs` (each `{ index, label, icon, state, isActive }`, `icon` a PhxIcon name) and call `select(tab.index)` on click. Pass `{ source: 'sidebarTabs' }` or `{ source: 'horizontalTabs' }` when the layout shows one kind only. Not `LayoutSlots.useSidebarTabs()`: it serves the built-in sidebar and returns no tabs while its summary shows\n    - Steps: `phx.frontend.useStepNavigation()` returns `{ steps, activeStep, activeIndex, isFirst, isLast, canGoNext, canGoPrevious, next, previous, goTo }` for the spec's `navigationSteps`; render `steps` (each `{ index, label, state, status }`, `status` `'complete' | 'active' | 'upcoming'`), call `next()`/`previous()` for Back and Next and `goTo(step.index)` from a stepper. It enforces no order and no validity: enable only `'complete'` steps for an \"earlier steps only\" stepper, and to block moving on while the configuration has a problem, require `phx.frontend.useStateValidity().severity !== 'warning'` besides `canGoNext`: a change with a `fixable` or `fatal` violation is rejected, so the configuration is never invalid, and a `warning` is the problem that stays (it blocks finalizing too). `useSteps` and `useHasSteps` from `@salsita-ai/sdk/configurator` are deprecated\n    - Messages: mount `LayoutSlots.Services` for the built-in snackbars, or show violations, side-effect hints, errors and failed saves yourself with `phx.frontend.useConfiguratorMessages(onMessage)`, not both. A failed save arrives as `saveError`, the next successful save as `saveRecovery`; a layout that mounts neither shows no sign of a failed save. Either way mount a snackbar root (`LayoutSlots.DesktopSnackbarsRoot` or `LayoutSlots.MobileSnackbarsRoot`): errors of the built-in actions are always snackbars\n    - Finalize over the spec's `finalizeAction` components, each naming a handler registered with `phx.frontend.createPhoenixHandler`: `phx.frontend.useFinalizeActions()` returns `{ actions, primary, secondary, disabled, hints }`; render `primary` (and `secondary` in a menu or list) in a loop, each action `{ key, label, title, icon, run, isPending, error, disabled }`, and call `action.run()` on click (its promise never rejects; show `action.error` on failure). The configurator runs the handlers itself, outside the layout, so a handler must not rely on a provider the layout adds. For one known handler, `phx.frontend.useFinalizeAction(handler)` in a component wrapped in `PhoenixHandlerBoundary` (from `@salsita-ai/sdk/react`) works too; `FinalizeActions` (from `@salsita-ai/sdk/configurator`) mounts the built-in buttons. `finalizePage` and `finalizeButton` are legacy\n    - Read mode and fullscreen are the layout's job, no hook enforces them (`useUndoRedo`, `useFinalizeActions` and `useStepNavigation` included): hide undo, redo, finalization and whatever else a viewer must not change while `phx.frontend.useAccessService().accessInfo.viewMode` is `true` (tabs are navigation, so a viewer may switch them), and remove panels while `phx.frontend.useIsFullscreenActive()` is set; `phx.frontend.useSetFullscreen()` returns its setter\n\n### Other project elements\n\n- `ConfigurationNotFoundPage`: `phx.frontend.createConfigurationNotFoundPage(({ onBack }) => …)` replaces the \"configuration not accessible\" page; show a way back only when the optional `onBack` is set. The not-authenticated page's default renders it too; only the admin's not-authorized page keeps the built-in page\n- `ConfiguratorErrorPage`: `phx.frontend.createConfiguratorErrorPage(({ reason, onRetry }) => …)` replaces the production error page; `reason` is `uncaughtError` or `presetCreationFailed`. A page that throws falls back to the built-in one, and development keeps the detailed error pages, so the project page shows only in a production build. Register both pages with these helpers: `createCustomPhoenixLayoutElement` with the name works too, but types the component as taking only `children`, so the typed props do not compile there in a strict project\n- Preset screen: `phx.frontend.createPresetUi(Component)` replaces the preset screen; inside it, `phx.frontend.usePresetSelection()` returns `{ presetCategories, selectPreset, creatingPresetId, selectionError }`. Keep the `phx.frontend.usePreview().isPreview` branch that renders `PresetPreviewLayout`, or an embedded configurator in preview mode never expands; `docs/layouts/presets/custom.mdx` is the complete screen\n- `AppLoaderContent`: `phx.frontend.createAppLoader(({ phases }) => …)` replaces what the loading overlay shows (each phase `{ id, label?, progress? }`, the list possibly empty); Phoenix keeps the overlay itself\n- Assistant form elements: an element declared under `assistant.formElements` (`description`, `role`, scalar `attributes` beside the built-in `label`, a `value` included, `required`) is the default export `phx.frontend.createAssistantFormElement('name', Component)` of one file; the name types the component's props by its role (`AssistantFormElementProps<'name'>`): an option reports its answer with `onSelect(answer)`, an input with `onChange(state, answer)`; and the application does not start while a declared element has no registration or a registration no declaration",webhookMembership:"- Project components, admin components, and handlers are frontend-only by default.\n- A handler that registers `phx.domain.createAssistantSetupHandler`, `createMapPublishedRevisionDataHandler`, `createMapPublishedChunkedDataHandler`, `createDataRowValidatorHandler`, or `createSheetValidatorHandler` is included in the webhook automatically.\n- An assistant setup handler receives the declaration-shaped whitelist and { role, sessionData, access }. Keep the exact entity/alias split from YAML; inherited fields and expanded member entries are absent. Narrow original declarations, then the SDK expands them. Use project-defined role/session data for per-user customization. Keep the handler synchronous, pure and deterministic. The handler runs in the browser and webhook. In the browser its manifest has no instructions or ai, and what it returns for them is ignored, so never narrow the whitelist by manifest.ai: the browser schema would differ from the server's. Return null to disable assistant execution, or omit whitelist entries to restrict them. Button and panel visibility use spec presence; project developers own dynamic UI filtering through normal layout mechanics such as $filter. Leaves expose optional descriptions; writable options allow only validate: true and allowDryRuns: false; recipe groups allow descriptions and allowDryRuns: false; screenshot views allow descriptions. Deletable entries are {}. Names, component bindings, hints and types are internal. Omitted overrides retain baseline values. Existing entity, enhanced-entity and action types constrain the handler; no separate generated manifest types. Browser GraphQL, tools and change recording use the session-derived manifest; rejected setup fails closed. UI reads the pure spec selector. Omitted server instructions or AI fields preserve the baseline. An empty server instructions string clears it.\n- To include another component or handler in the webhook, put `'use webhook'` as its first statement (leading comments are allowed).\n- A webhook-included file and its runtime local-import closure must not import browser SDK entrypoints (`application`, `admin`, `configurator`, `editor`, `react`, `ui`) or style/font/image assets. Spec parsing reports the unsafe import and inclusion reason as a diagnostic.\n- Keep browser rendering in an unpinned file. Move shared server-safe logic into a separate module when both frontend and webhook code need it.",assetInspection:"### 3D asset inspection\n\nRun `pnpm phoenix inspect:assets` to list every glTF or GLB file in `public/` in a summary table, and add `--file <path>` to inspect one file in detail. Run it before writing YAML or code that references `objectName`, `materialsToOverride`, `morphTargetInfluences` or object positions.\n\nFor each node it shows:\n\n- the name, the type (Mesh, Light, Camera or Empty) and the children;\n- the transform as `pos=`, `rot=` and `scale=`, with only non-default values;\n- morph targets, such as `morphs=Width,Height`;\n- the bounding box as `bounds=WxHxD`, width by height by depth in meters;\n- the origin placement, such as `origin=center`, `bottom-center`, `top-center` or `bottom-corner`, with its numerical offset.\n\nUse it to:\n\n- find exact node names for `objectName` in scene entity components;\n- find material names for `materialsToOverride` and morph target names for `morphTargetInfluences`;\n- check model dimensions for positioning, dimension indicators or invariants;\n- check the origin placement to see how a model anchors, such as center or bottom-center.\n\nIts flags are `--objects`, `--materials`, `--morphs`, `--animations`, and `--json` for programmatic access to all data.",screenshotCli:"### Screenshots\n\n`pnpm phoenix screenshot` captures the 3D canvas from the running preview, in the state the preview currently shows. It needs `phoenix dev` running, which starts the WebSocket server on port 3020, and the configurator open in a browser, which does the rendering.\n\n- `--output`, `-o` — output file path (default `./screenshot.png`)\n- `--width`, `-w` — width in pixels (default 1920)\n- `--height` — height in pixels (default 1080)\n- `--format`, `-f` — image format, PNG or JPEG (default PNG)\n- `--port` — WebSocket server port (default 3020)\n\nFor example, with `pnpm phoenix dev` running and the configurator open in a browser or through Playwright MCP, run `pnpm phoenix screenshot -o ./render.png -w 2560 --height 1440`. Use it for visual regression checks, product images and debugging 3D renders.",inspectState:"### Inspect state\n\n`pnpm phoenix inspect:state` prints the current editor runtime state as JSON. Like screenshots, it needs dev running and the configurator open in a browser.\n\n- `--output`, `-o` — output file path; prints to stdout when omitted\n- `--sections`, `-s` — comma-separated `entities`, `navigation` and `validation` (default all)\n- `--pretty` — pretty-print the JSON (default true)\n- `--port` — WebSocket server port (default 3020)\n\nEvery response includes the lifecycle status, which shows the systems that are ready:\n\n- `domainLoaded` — domain data loaded\n- `domainContextReady` — domain context initialized, entities available\n- `configuratorReady` — 3D configurator initialized\n- `sessionAuthenticated` — session service active\n- `editorMode` — editor mode enabled\n\nFor example, run `pnpm phoenix inspect:state -o ./state.json -s entities,navigation`. Limit the payload with `--sections`, or pipe through `head` or `tail` for partial output, such as `pnpm phoenix inspect:state | head -50`. Use it for agent context and for debugging entity state, navigation and validation.",inspectData:"### Inspect data\n\n`pnpm phoenix inspect:data` prints the current editor context data as JSON: `publishedData`, `frontendData`, `backendData`, `sessionData`, `accessData` and `webComponentProperties`. Like screenshots, it needs dev running and the configurator open in a browser.\n\n- `--output`, `-o` — output file path; prints to stdout when omitted\n- `--pretty` — pretty-print the JSON (default true)\n- `--port` — WebSocket server port (default 3020)\n\nFor example, run `pnpm phoenix inspect:data -o ./data.json`, or pipe through `head` or `tail` for partial output, such as `pnpm phoenix inspect:data | head -30`. Use it for agent context and for debugging published, session and access data.",inspectScene:"### Inspect scene\n\n`pnpm phoenix inspect:scene` prints the current Three.js scene graph as JSON: a recursive tree with each node's name, type, visibility, position, rotation, scale and `userData` (`entityId`). Meshes add the geometry name, bounding box, material properties (color, metalness, roughness, opacity, textures) and morph target influences; lights add color, intensity and type-specific properties. Like screenshots, it needs dev running and the configurator open in a browser.\n\n- `--output`, `-o` — output file path; prints to stdout when omitted\n- `--pretty` — pretty-print the JSON (default true)\n- `--port` — WebSocket server port (default 3020)\n\nFor example, run `pnpm phoenix inspect:scene -o ./scene.json`. Scene graphs can be large, so pipe through `head` or `tail` for partial output. Use it for agent context and for debugging scene layout, materials and lighting.",playwrightMcpSetup:`### Playwright MCP setup
 
 To interact with the 3D configurator in a browser, Playwright MCP needs GPU-enabled flags for WebGL rendering. Add to \`~/.claude/.mcp.json\`:
 
@@ -58,22 +18,7 @@ To interact with the 3D configurator in a browser, Playwright MCP needs GPU-enab
 }
 \`\`\`
 
-Key flags:
+These flags make WebGL rendering work:
 - \`--headed\` — visible browser (required for GPU rendering)
 - \`--use-gl=swiftshader\` — software GPU fallback for environments without a physical GPU
-- \`--enable-webgl\` + \`--ignore-gpu-blocklist\` — ensure WebGL is available`,visualInspection:`## Visual inspection
-Apply this whenever a change can alter what the canvas or the interface shows: geometry, materials, scene, layout, controls, or the data behind any of them. When a change cannot affect the rendered result, say so rather than passing over this silently.
-
-Rendered appearance is a deliverable, not a side effect. Before presenting any preview, and before reporting work as complete, open the configuration that best represents the product at desktop width, wait for it to finish loading, look at it, and report what you found. Report what you saw, not whether it passed. State the observation each judgement rests on: “nothing floats” is a verdict, “the casters meet the floor and the shadow lies under them” is an observation. A result you have not looked at is unverified, whatever the automated checks say.
-
-Inspect and report:
-
-1. Geometry. Every part rests on its support. Name where the product meets the ground and confirm its shadow and any selection indicator sit there too. Nothing floats, intersects, or protrudes. Scale and orientation are consistent between parts and match the stated dimensions. Each part is complete and present.
-2. Response. Every configurable surface of every part reacts to its control, not only the parts you just changed.
-3. Loading. How long until a meaningful first frame, and whether anything indicates progress meanwhile.
-
-This covers what follows from the change you just made, in the state you are already in. Fidelity against the client's own material, the density of the controls, and every state you did not open belong to an independent reviewer, which the \`phoenix-create-configurator\` skill's Appearance review covers.
-
-Report defects you are deferring as defects. Do not call work done, verified, or complete while any of the above is unchecked or failing: say which, and recommend fixing now or later.
-
-Record the result of each point above in the specification alongside the increment it belongs to, with the viewport you used. An inspection nobody can read afterwards is indistinguishable from one that never happened.`};
+- \`--enable-webgl\` + \`--ignore-gpu-blocklist\` — ensure WebGL is available`};

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

@@ -1,5 +1,5 @@
+import { type SpecCodeId } from '#package/domain';
 import type { ComponentEntry, Expressions } from '../../../../parse-application-files/index.js';
-import { type SpecCodeId } from '../../../runtime-spec/index.js';
 /**
  * Where a value sits inside its target: object keys, and `0` for any item of an array (the
  * generated type reads the array's item type). An empty path is the target itself.

package/dist/application-spec/generate-application/code/templates/spec-code/collect-spec-code.js

@@ -1 +1 @@
-import{FILTER_CRITERION_KEYS as e}from"../../../../core/index.js";import{evalCodeUsesSelf as t}from"../../../../enhanced-json/eval-code-uses-self.js";import{specCodeComponentKey as n,specCodeEvalIds as i,specCodeExpressionKey as r,specCodeFilterId as o}from"../../../runtime-spec/index.js";let l=(e,t,n)=>{if("slot"===e.kind){let i=n.get(e.depIndex)??[];i.push(t),n.set(e.depIndex,i);return}if("array"===e.kind){for(let i of e.items)l(i,[...t,0],n);return}if("object"===e.kind)for(let[i,r]of e.entries)l(r,[...t,i],n)},a=(e,n,r,o)=>{let a=new Map;l(e.template,[],a);let s=i(e,n);return e.deps.flatMap((e,n)=>{let i=s[n];return"eval"!==e.kind||void 0===i?[]:[{id:i,owner:r,code:e.code,usesSelf:t(e.code),target:o(a.get(n)??[])}]})},s=i=>{let r,l=String(i.typeOrAlias),s=n(l,String(i.instanceName),i.componentName),d=(r=String(i.typeOrAlias),i.implementation.filters.items.flatMap((n,i)=>"gradual"!==n.kind?[]:e.flatMap(e=>{let l=n[e];return l?.kind!=="eval"?[]:[{id:o(s,i,e,l.code),owner:r,code:l.code,usesSelf:t(l.code),target:{kind:"filter",criterion:e}}]})));if("userBound"!==i.implementation.kind)return d;let{componentName:p}=i;return[...a(i.implementation.plan,s,l,e=>({kind:"component",componentName:p,paths:e})),...d]},d=(e,t)=>JSON.stringify(e)===JSON.stringify(t);export const collectSpecCode=e=>{let t=new Map;for(let n of[...[...e.expressions.expressions].flatMap(([e,t])=>[...t.values()].flatMap(t=>{if("value"!==t.implementation.kind)return[];let n=String(t.name),i=r(String(e),n);return a(t.implementation.plan,i,String(e),e=>({kind:"expression",name:n,paths:e}))})),...e.components.flatMap(s)]){let e=t.get(n.id);if(void 0===e)t.set(n.id,n);else if(!d(e,n))throw Error(`Two pieces of YAML code share the spec code id "${n.id}". This is a bug in the application-spec generator.`)}return[...t.values()]};
+import{specCodeComponentKey as e,specCodeEvalIds as t,specCodeExpressionKey as n,specCodeFilterId as i}from"#package/domain";import{FILTER_CRITERION_KEYS as r}from"../../../../core/index.js";import{evalCodeUsesSelf as o}from"../../../../enhanced-json/eval-code-uses-self.js";let a=(e,t,n)=>{if("slot"===e.kind){let i=n.get(e.depIndex)??[];i.push(t),n.set(e.depIndex,i);return}if("array"===e.kind){for(let i of e.items)a(i,[...t,0],n);return}if("object"===e.kind)for(let[i,r]of e.entries)a(r,[...t,i],n)},l=(e,n,i,r)=>{let l=new Map;a(e.template,[],l);let s=t(e,n);return e.deps.flatMap((e,t)=>{let n=s[t];return"eval"!==e.kind||void 0===n?[]:[{id:n,owner:i,code:e.code,usesSelf:o(e.code),target:r(l.get(t)??[])}]})},s=t=>{let n,a=String(t.typeOrAlias),s=e(a,String(t.instanceName),t.componentName),d=(n=String(t.typeOrAlias),t.implementation.filters.items.flatMap((e,t)=>"gradual"!==e.kind?[]:r.flatMap(r=>{let a=e[r];return a?.kind!=="eval"?[]:[{id:i(s,t,r,a.code),owner:n,code:a.code,usesSelf:o(a.code),target:{kind:"filter",criterion:r}}]})));if("userBound"!==t.implementation.kind)return d;let{componentName:p}=t;return[...l(t.implementation.plan,s,a,e=>({kind:"component",componentName:p,paths:e})),...d]},d=(e,t)=>JSON.stringify(e)===JSON.stringify(t);export const collectSpecCode=e=>{let t=new Map;for(let i of[...[...e.expressions.expressions].flatMap(([e,t])=>[...t.values()].flatMap(t=>{if("value"!==t.implementation.kind)return[];let i=String(t.name),r=n(String(e),i);return l(t.implementation.plan,r,String(e),e=>({kind:"expression",name:i,paths:e}))})),...e.components.flatMap(s)]){let e=t.get(i.id);if(void 0===e)t.set(i.id,i);else if(!d(e,i))throw Error(`Two pieces of YAML code share the spec code id "${i.id}". This is a bug in the application-spec generator.`)}return[...t.values()]};