@salsita-ai/sdk 0.50.0-develop.ca72986c39 → 0.50.0-develop.d0eaeed131

package/dist/application-spec/generate-application/code/templates/common/schema-to-type-string.js

@@ -1,3 +1,3 @@
-import{COMMON_SHORT_PREFIX as e,INTERNAL_REF_PATTERN as r,extractPhxDefName as n}from"../../../../core/index.js";let t=(e,r,n)=>{let t=e.importModuleOverrides?.[n]??r;e.typeOnlyImports?e.imports?.addTypeImport(t,n):e.imports?.addImport(t,n)},i={string:"string",number:"number",integer:"number",boolean:"boolean",null:"null",object:"Record<string, unknown>",array:"readonly unknown[]"},o=e=>null===e?"null":"string"==typeof e?`'${e}'`:"number"==typeof e||"boolean"==typeof e?String(e):"unknown",a=(e,r)=>{if("object"==typeof e.additionalProperties){let n=schemaToTypeString(e.additionalProperties,r);return`Readonly<Record<string, ${n}>>`}if(!e.properties)return"Record<string, unknown>";let n=new Set(e.required??[]),t=Object.entries(e.properties);if(0===t.length)return"Record<string, never>";let i=t.map(([e,t])=>{let i=schemaToTypeString(t,r),o=n.has(e)?"":"?";return`  readonly ${e}${o}: ${i}`});return`{
-${i.join("\n")}
-}`},p=(e,r)=>{let{items:n}=e;if(Array.isArray(n)){let e=n.map(e=>schemaToTypeString(e,r)).join(", ");return`readonly [${e}]`}let t=schemaToTypeString(n,r);return t.includes(" | ")||t.includes(" & ")?`readonly (${t})[]`:`readonly ${t}[]`};export const schemaToTypeString=(l,m)=>{if(l.tsType){if(m.imports&&l.import)for(let e of l.import)t(m,e.module,e.member);return l.tsType}if(l.$ref){let e=n(l.$ref);if(void 0!==e){var s;let r,n,i=m.phxDefinitions[e];if(m.imports&&i?.import)for(let e of i.import)t(m,e.module,e.member);return s=l.references,r=m.phxDefinitions[e],"DomainEntityId"===(n=r?.tsType)?s?`${s}['id']`:"DomainEntityId<string>":"DomainEntity"===n?s??"DomainEntity<string>":"$DomainEntity"===n?s?`$${s}`:"$DomainEntity<string>":n||"unknown"}}if(l.$ref){if(l.$ref.startsWith(e))return l.$ref.slice(e.length);let n=r.exec(l.$ref);return n?n[2]??"unknown":"unknown"}if(l.enum)return l.enum.map(o).join(" | ");if(l.anyOf)return l.anyOf.map(e=>schemaToTypeString(e,m)).join(" | ");if(l.oneOf)return l.oneOf.map(e=>schemaToTypeString(e,m)).join(" | ");if(l.allOf)return l.allOf.map(e=>{let r=schemaToTypeString(e,m);return r.includes("|")?`(${r})`:r}).join(" & ");if("array"===l.type&&l.items)return p(l,m);if("object"===l.type)return a(l,m);if("string"==typeof l.type)return i[l.type]??"unknown";if(Array.isArray(l.type)){let e;return e=l.type,e.map(e=>"array"===e&&l.items?p(l,m):"object"===e?a(l,m):i[e]??"unknown").join(" | ")}return"unknown"};
+import{COMMON_SHORT_PREFIX as e,INTERNAL_REF_PATTERN as r,extractPhxDefName as n}from"../../../../core/index.js";import{formatPropertyKey as t}from"./format-property-key.js";let i=(e,r,n)=>{let t=e.importModuleOverrides?.[n]??r;e.typeOnlyImports?e.imports?.addTypeImport(t,n):e.imports?.addImport(t,n)},o={string:"string",number:"number",integer:"number",boolean:"boolean",null:"null",object:"Record<string, unknown>",array:"readonly unknown[]"},l=e=>null===e?"null":"string"==typeof e?`'${e.replaceAll("\\","\\\\").replaceAll("'","\\'").replaceAll("\n","\\n").replaceAll("\r","\\r")}'`:"number"==typeof e||"boolean"==typeof e?String(e):"unknown",p=(e,r)=>{if("object"==typeof e.additionalProperties){let n=schemaToTypeString(e.additionalProperties,r);return`Readonly<Record<string, ${n}>>`}if(!e.properties)return"Record<string, unknown>";let n=new Set(e.required??[]),i=Object.entries(e.properties);if(0===i.length)return"Record<string, never>";let o=i.map(([e,i])=>{let o=schemaToTypeString(i,r),l=n.has(e)?"":"?";return`  readonly ${t(e)}${l}: ${o}`});return`{
+${o.join("\n")}
+}`},a=(e,r)=>{let{items:n}=e;if(Array.isArray(n)){let e=n.map(e=>schemaToTypeString(e,r)).join(", ");return`readonly [${e}]`}let t=schemaToTypeString(n,r);return t.includes(" | ")||t.includes(" & ")?`readonly (${t})[]`:`readonly ${t}[]`};export const schemaToTypeString=(t,m)=>{if(t.tsType){if(m.imports&&t.import)for(let e of t.import)i(m,e.module,e.member);return t.tsType}if(t.$ref){let e=n(t.$ref);if(void 0!==e){var s;let r,n,o=m.phxDefinitions[e];if(m.imports&&o?.import)for(let e of o.import)i(m,e.module,e.member);return s=t.references,r=m.phxDefinitions[e],"DomainEntityId"===(n=r?.tsType)?s?`${s}['id']`:"DomainEntityId<string>":"DomainEntity"===n?s??"DomainEntity<string>":"$DomainEntity"===n?s?`$${s}`:"$DomainEntity<string>":n||"unknown"}}if(t.$ref){if(t.$ref.startsWith(e))return t.$ref.slice(e.length);let n=r.exec(t.$ref);return n?n[2]??"unknown":"unknown"}if(t.enum)return t.enum.map(l).join(" | ");if(t.anyOf)return t.anyOf.map(e=>schemaToTypeString(e,m)).join(" | ");if(t.oneOf)return t.oneOf.map(e=>schemaToTypeString(e,m)).join(" | ");if(t.allOf)return t.allOf.map(e=>{let r=schemaToTypeString(e,m);return r.includes("|")?`(${r})`:r}).join(" & ");if("array"===t.type&&t.items)return a(t,m);if("object"===t.type)return p(t,m);if("string"==typeof t.type)return o[t.type]??"unknown";if(Array.isArray(t.type)){let e;return e=t.type,e.map(e=>"array"===e&&t.items?a(t,m):"object"===e?p(t,m):o[e]??"unknown").join(" | ")}return"unknown"};

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

@@ -1 +1,6 @@
+/**
+ * The project's `eslint.config.js`, written once when the project has none. It re-exports the SDK's
+ * shared ESLint configuration so editors find it in the project root; the project may change it
+ * afterwards. `phoenix check` and `phoenix fix` use the SDK's configuration when the file is missing.
+ */
 export declare const generateApplicationSpecEslintConfig: () => string;

package/dist/application-spec/generate-application/code/templates/eslint-config.js

@@ -1,8 +1,7 @@
-let e=`/**
- * Auto-generated file.
- * Do not modify this file manually.
- * Version: 1
- */`;export const generateApplicationSpecEslintConfig=()=>`${e}
+export const generateApplicationSpecEslintConfig=()=>`/**
+ * The project's ESLint configuration. It re-exports the shared configuration of the Phoenix SDK;
+ * change it to adjust the rules for this project.
+ */
 import { eslintrc } from '@salsita-ai/sdk/common/eslint'
 
 export default eslintrc

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

@@ -51,10 +51,8 @@ phoenix-api.yaml
 .phoenix
 **/locales/*/*.ts
 phoenix.config.ts
-prettier.config.js
-eslint.config.js
 .prettierignore
 .linguirc
 public/robots.txt
 ${gitignoreEndMarker}
-`;export const generateApplicationSpecGitignore=t=>{if(!t)return e;let i=t.includes("\r\n")?"\r\n":"\n",n=t.replace(/\r?\n/g,i),r=e.replace(/\r?\n/g,i),o=n.indexOf(gitignoreStartMarker),s=n.indexOf(gitignoreEndMarker);if(-1!==o&&-1!==s&&s>o){let e=n.substring(0,o),t=n.substring(s+gitignoreEndMarker.length);return(t=t.replace(/^(?:\r?\n)+/,"")).trim().length>0?e+r+i+t:e+r}return n.trim()?r+`${i}# Custom entries${i}`+n:r};
+`;export const generateApplicationSpecGitignore=t=>{if(!t)return e;let n=t.includes("\r\n")?"\r\n":"\n",i=t.replace(/\r?\n/g,n),r=e.replace(/\r?\n/g,n),o=i.indexOf(gitignoreStartMarker),s=i.indexOf(gitignoreEndMarker);if(-1!==o&&-1!==s&&s>o){let e=i.substring(0,o),t=i.substring(s+gitignoreEndMarker.length);return(t=t.replace(/^(?:\r?\n)+/,"")).trim().length>0?e+r+n+t:e+r}return i.trim()?r+`${n}# Custom entries${n}`+i:r};

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

@@ -1,9 +1,9 @@
-import{autoHeader as e}from"../common/file-headers.js";import{generateApplicationSpecTypeDeclarations as a}from"./application-types.js";export const generateApplicationSpecGlobals=(o,n)=>{let t,i,l,r,d,s,p,m,y,{declarations:c,imports:f}=a(o,n,2);f.addTypeImport("@salsita-ai/sdk/domain","EnumLike");let u=[c,(t=o.configurator.latestModel,i=o.admin.latestModel,l=t.entityTypes.map(String),r=[...t.aliases].map(([e])=>String(e)),d=[...t.commonTypes].map(([e])=>String(e)),s=i.entityTypes.map(String),p=[...i.aliases].map(([e])=>String(e)),m=[...i.commonTypes].map(([e])=>String(e)),y=(e,a)=>e.map(e=>`    ${a(e)}`).join("\n"),`  interface Model {
-${y([...l,...d,...r],e=>`readonly ${e}: ${e}`)}
+import{autoHeader as e}from"../common/file-headers.js";import{generateApplicationSpecTypeDeclarations as a}from"./application-types.js";export const generateApplicationSpecGlobals=(o,t)=>{let n,i,r,d,l,s,p,m,y,{declarations:c,imports:f}=a(o,t,2);f.addTypeImport("@salsita-ai/sdk/domain","EnumLike");let h=[c,(n=o.configurator.latestModel,i=o.admin.latestModel,r=n.entityTypes.map(String),d=[...n.aliases].map(([e])=>String(e)),l=[...n.commonTypes].map(([e])=>String(e)),s=i.entityTypes.map(String),p=[...i.aliases].map(([e])=>String(e)),m=[...i.commonTypes].map(([e])=>String(e)),y=(e,a)=>e.map(e=>`    ${a(e)}`).join("\n"),`  interface Model {
+${y([...r,...l,...d],e=>`readonly ${e}: ${e}`)}
   }
 
   interface EnhancedModel {
-${y([...l,...r],e=>`readonly $${e}: $${e}`)}
+${y([...r,...d],e=>`readonly $${e}: $${e}`)}
   }
 
   interface AdminModel {
@@ -39,11 +39,14 @@ ${y([...s,...p],e=>`readonly $${e}: Admin.$${e}`)}
   }`)].filter(Boolean).join("\n\n");return`${e("globals.d.ts","Global type declarations for the phx namespace, env configs and domain types.")}
 /* eslint-disable @typescript-eslint/triple-slash-reference, @typescript-eslint/consistent-type-imports */
 /// <reference types="@salsita-ai/sdk/globals" />
+// The project's tsconfig includes \`.phoenix\`, but TypeScript checks a file under a dot folder only
+// when it is named or imported. Nothing imports the module of YAML code yet, so it is named here.
+/// <reference path="./spec-code.ts" />
 
 ${f.toTypeOnlyString(".phoenix/globals.d.ts")}
 
 declare global {
-${u}
+${h}
 
   interface PhxGlobal {
     readonly frontendEnv: import('./frontend.config.js').RuntimeConfig

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

@@ -37,8 +37,6 @@ export { generateApplicationSpecGlobals } from './globals.js';
 export { generateApplicationSpecHtmlAdminIndex } from './html-admin-index.js';
 export { generateApplicationSpecHtmlIndex } from './html-index.js';
 export { generateLinguiRcFile } from './lingui-rc.js';
-export { generateApplicationSpecNvmrc } from './nvmrc.js';
-export { generateApplicationSpecPackageJson } from './package-json.js';
 export { generatePhoenixCliSkill } from './skills/phoenix-cli-skill.js';
 export { generatePhoenixCreateConfiguratorSkill, generatePhoenixCreateConfiguratorSkillReferences, } from './skills/phoenix-create-configurator-skill.js';
 export { generatePhoenixFeedbackSkill } from './skills/phoenix-feedback-skill.js';
@@ -49,6 +47,8 @@ export { generateApplicationSpecPrettierConfig } from './prettier-config.js';
 export { generateApplicationSpecRobotsTxt } from './robots-txt.js';
 export { generateApplicationSpecRootTsconfig } from './root-tsconfig.js';
 export { generateApplicationSpecStoryDevDeclaration, generateApplicationSpecStoryPhxModule, generateApplicationSpecStoryRawProjectFiles, generateApplicationSpecStoryWrapper, } from './story/index.js';
+export { generateApplicationSpecCodeFile } from './spec-code/index.js';
+export { generateApplicationSpecMessagesFile } from './spec-messages/index.js';
 export { generateApplicationSpecTsconfig } from './tsconfig.js';
 export { generateApplicationSpecWebhookBuilders } from './webhook-builders.js';
 export { generateApplicationSpecWebhookIndex } from './webhook-index.js';

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

@@ -1 +1 @@
-export{stripSdkMarkerContent}from"./common/strip-sdk-marker-content.js";export{generateApplicationSpecAdminConfig}from"./admin-config.js";export{generateApplicationSpecAdminCode}from"./admin-domain-code.js";export{generateApplicationSpecAdminFrontendCode}from"./admin-frontend-code.js";export{generateAdminGlobalBindingBlock,generateApplicationSpecAdminGlobals}from"./admin-globals.js";export{generateApplicationSpecTypesModule}from"./application-types.js";export{generateApplicationSpecAdminFile}from"./admin.js";export{generateApplicationSpecConfiguratorConfig}from"./configurator-config.js";export{generateApplicationSpecConfiguratorCode}from"./configurator-domain-code.js";export{generateApplicationSpecConfiguratorFrontendCode}from"./configurator-frontend-code.js";export{generateApplicationSpecConfiguratorGlobals,generateConfiguratorGlobalBindingBlock}from"./configurator-globals.js";export{generateApplicationSpecConfiguratorFile}from"./configurator.js";export{generateApplicationSpecDomainSpecFile}from"./domain-spec.js";export{generateImportedStateConstants,generatePhxExportsBlock,generatePhxGlobalsBlock,generateStateConstants}from"./domain-spec/index.js";export{generateApplicationSpecDomainFile}from"./domain.js";export{generateApplicationSpecEditorFile}from"./editor.js";export{generateApplicationSpecEmbeddedAdmin}from"./embedded-admin.js";export{generateApplicationSpecEmbeddedConfigurator}from"./embedded-configurator.js";export{generateApplicationSpecEslintConfig}from"./eslint-config.js";export{generateApplicationSpecFavicon}from"./favicon.js";export{generateApplicationSpecFrontendConfig}from"./frontend-config.js";export{generateApplicationSpecGitignore}from"./gitignore.js";export{generateApplicationSpecGlobals}from"./globals.js";export{generateApplicationSpecHtmlAdminIndex}from"./html-admin-index.js";export{generateApplicationSpecHtmlIndex}from"./html-index.js";export{generateLinguiRcFile}from"./lingui-rc.js";export{generateApplicationSpecNvmrc}from"./nvmrc.js";export{generateApplicationSpecPackageJson}from"./package-json.js";export{generatePhoenixCliSkill}from"./skills/phoenix-cli-skill.js";export{generatePhoenixCreateConfiguratorSkill,generatePhoenixCreateConfiguratorSkillReferences}from"./skills/phoenix-create-configurator-skill.js";export{generatePhoenixFeedbackSkill}from"./skills/phoenix-feedback-skill.js";export{generatePhoenixReviewSkill}from"./skills/phoenix-review-skill.js";export{followsCanaryBuilds,generatePhoenixSkill}from"./skills/phoenix-skill.js";export{generatePhoenixVariantsSkill}from"./skills/phoenix-variants-skill.js";export{generateApplicationSpecPrettierConfig}from"./prettier-config.js";export{generateApplicationSpecRobotsTxt}from"./robots-txt.js";export{generateApplicationSpecRootTsconfig}from"./root-tsconfig.js";export{generateApplicationSpecStoryDevDeclaration,generateApplicationSpecStoryPhxModule,generateApplicationSpecStoryRawProjectFiles,generateApplicationSpecStoryWrapper}from"./story/index.js";export{generateApplicationSpecTsconfig}from"./tsconfig.js";export{generateApplicationSpecWebhookBuilders}from"./webhook-builders.js";export{generateApplicationSpecWebhookIndex}from"./webhook-index.js";export{generateApplicationSpecWebhooksConfig}from"./webhooks-config.js";
+export{stripSdkMarkerContent}from"./common/strip-sdk-marker-content.js";export{generateApplicationSpecAdminConfig}from"./admin-config.js";export{generateApplicationSpecAdminCode}from"./admin-domain-code.js";export{generateApplicationSpecAdminFrontendCode}from"./admin-frontend-code.js";export{generateAdminGlobalBindingBlock,generateApplicationSpecAdminGlobals}from"./admin-globals.js";export{generateApplicationSpecTypesModule}from"./application-types.js";export{generateApplicationSpecAdminFile}from"./admin.js";export{generateApplicationSpecConfiguratorConfig}from"./configurator-config.js";export{generateApplicationSpecConfiguratorCode}from"./configurator-domain-code.js";export{generateApplicationSpecConfiguratorFrontendCode}from"./configurator-frontend-code.js";export{generateApplicationSpecConfiguratorGlobals,generateConfiguratorGlobalBindingBlock}from"./configurator-globals.js";export{generateApplicationSpecConfiguratorFile}from"./configurator.js";export{generateApplicationSpecDomainSpecFile}from"./domain-spec.js";export{generateImportedStateConstants,generatePhxExportsBlock,generatePhxGlobalsBlock,generateStateConstants}from"./domain-spec/index.js";export{generateApplicationSpecDomainFile}from"./domain.js";export{generateApplicationSpecEditorFile}from"./editor.js";export{generateApplicationSpecEmbeddedAdmin}from"./embedded-admin.js";export{generateApplicationSpecEmbeddedConfigurator}from"./embedded-configurator.js";export{generateApplicationSpecEslintConfig}from"./eslint-config.js";export{generateApplicationSpecFavicon}from"./favicon.js";export{generateApplicationSpecFrontendConfig}from"./frontend-config.js";export{generateApplicationSpecGitignore}from"./gitignore.js";export{generateApplicationSpecGlobals}from"./globals.js";export{generateApplicationSpecHtmlAdminIndex}from"./html-admin-index.js";export{generateApplicationSpecHtmlIndex}from"./html-index.js";export{generateLinguiRcFile}from"./lingui-rc.js";export{generatePhoenixCliSkill}from"./skills/phoenix-cli-skill.js";export{generatePhoenixCreateConfiguratorSkill,generatePhoenixCreateConfiguratorSkillReferences}from"./skills/phoenix-create-configurator-skill.js";export{generatePhoenixFeedbackSkill}from"./skills/phoenix-feedback-skill.js";export{generatePhoenixReviewSkill}from"./skills/phoenix-review-skill.js";export{followsCanaryBuilds,generatePhoenixSkill}from"./skills/phoenix-skill.js";export{generatePhoenixVariantsSkill}from"./skills/phoenix-variants-skill.js";export{generateApplicationSpecPrettierConfig}from"./prettier-config.js";export{generateApplicationSpecRobotsTxt}from"./robots-txt.js";export{generateApplicationSpecRootTsconfig}from"./root-tsconfig.js";export{generateApplicationSpecStoryDevDeclaration,generateApplicationSpecStoryPhxModule,generateApplicationSpecStoryRawProjectFiles,generateApplicationSpecStoryWrapper}from"./story/index.js";export{generateApplicationSpecCodeFile}from"./spec-code/index.js";export{generateApplicationSpecMessagesFile}from"./spec-messages/index.js";export{generateApplicationSpecTsconfig}from"./tsconfig.js";export{generateApplicationSpecWebhookBuilders}from"./webhook-builders.js";export{generateApplicationSpecWebhookIndex}from"./webhook-index.js";export{generateApplicationSpecWebhooksConfig}from"./webhooks-config.js";

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

@@ -1 +1,6 @@
+/**
+ * The project's Lingui configuration, generated to `.phoenix/.linguirc` and, for a Storybook story, to
+ * the story's root. Lingui resolves its paths against the directory it runs in, the project or story
+ * root, so they hold in either place; `<rootDir>` would be the folder that holds the file.
+ */
 export declare const generateLinguiRcFile: (availableLocales: readonly string[]) => string;

package/dist/application-spec/generate-application/code/templates/lingui-rc.js

@@ -1,12 +1,12 @@
-import{DEFAULT_FALLBACK_LOCALE as e,LOCALE_FALLBACK_MAP as a}from"#package/i18n";export const generateLinguiRcFile=o=>{let s;return`{
+import{DEFAULT_FALLBACK_LOCALE as e,LOCALE_FALLBACK_MAP as a}from"#package/i18n";export const generateLinguiRcFile=s=>{let o;return`{
   "sourceLocale": "en",
-  "locales": [${o.map(e=>`"${e}"`).join(", ")}],
+  "locales": [${s.map(e=>`"${e}"`).join(", ")}],
   "fallbackLocales": {
-${(s=Object.entries(a).map(([e,a])=>{let o=Array.isArray(a)?`[${a.map(e=>`"${e}"`).join(", ")}]`:`"${a}"`;return`    "${e}": ${o}`})).push(`    "default": "${e}"`),s.join(",\n")}
+${(o=Object.entries(a).map(([e,a])=>{let s=Array.isArray(a)?`[${a.map(e=>`"${e}"`).join(", ")}]`:`"${a}"`;return`    "${e}": ${s}`})).push(`    "default": "${e}"`),o.join(",\n")}
   },
   "catalogs": [
     {
-      "path": "<rootDir>/src/locales/{locale}/messages",
+      "path": "./src/locales/{locale}/messages",
       "include": [
         "./src",
         "./.phoenix"

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

@@ -1 +1,6 @@
+/**
+ * The project's `prettier.config.js`, written once when the project has none. It re-exports the SDK's
+ * shared Prettier configuration so editors find it in the project root; the project may change it
+ * afterwards. `phoenix check` and `phoenix fix` use the SDK's configuration when the file is missing.
+ */
 export declare const generateApplicationSpecPrettierConfig: () => string;

package/dist/application-spec/generate-application/code/templates/prettier-config.js

@@ -1,8 +1,7 @@
-let e=`/**
- * Auto-generated file.
- * Do not modify this file manually.
- * Version: 1
- */`;export const generateApplicationSpecPrettierConfig=()=>`${e}
+export const generateApplicationSpecPrettierConfig=()=>`/**
+ * The project's Prettier configuration. It re-exports the shared configuration of the Phoenix SDK;
+ * change it to adjust the formatting of this project.
+ */
 import { prettierrc } from '@salsita-ai/sdk/common/prettier'
 
 export default prettierrc

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

@@ -1 +1 @@
-import{renderAgentSkill as e}from"./agent-skill.js";import{sdkGuidanceSections as n}from"./sdk-content.js";export const generatePhoenixCliSkill=()=>e({name:"phoenix-cli",description:"Phoenix CLI tooling for building and inspecting this configurator, covering build, dev, sync and deps commands, dev logs, glTF asset inspection, screenshots, runtime state, data and scene inspection, variant previews, and Playwright MCP setup. Use when building, debugging build or runtime errors, checking 3D assets, or inspecting the running configurator.",sections:[n.buildCommands,n.devLogs,n.assetInspection,n.screenshotCli,n.inspectState,n.inspectData,n.inspectScene,n.variantPreviews,n.playwrightMcpSetup]});
+import{renderAgentSkill as e}from"./agent-skill.js";import{sdkGuidanceSections as n}from"./sdk-content.js";export const generatePhoenixCliSkill=()=>e({name:"phoenix-cli",description:"Phoenix CLI tooling for building and inspecting this configurator, covering build, dev, sync and deps commands, dev logs, glTF asset inspection, screenshots, runtime state, data and scene inspection, variant previews, and Playwright MCP setup. Use when building, debugging build or runtime errors, checking 3D assets, or inspecting the running configurator.",sections:[n.packageManager,n.buildCommands,n.devLogs,n.assetInspection,n.screenshotCli,n.inspectState,n.inspectData,n.inspectScene,n.variantPreviews,n.playwrightMcpSetup]});

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

@@ -163,4 +163,4 @@ Keep facts traceable to sources. Geometry proves shape, not commercial availabil
 Extract available facts now; unresolved entries are not a queue of questions to ask next. Follow the skill's question threshold and defer unknowns that do not block the current work. Use reversible experience defaults without inventing business facts. When a business rule is needed now, explain the consequence and ask for the fact or an explicitly agreed provisional assumption. Continue independent work within the agreed increment; elapsed time is not agreement. For example, resolve whether a shelf is included or charged separately when implementing its pricing, not before a finish-only preview.
 
 Translate confirmed rules into representative allowed/disallowed combinations, boundary checks, and hand-calculated totals as their features are implemented.
-`;export const generatePhoenixCreateConfiguratorSkill=()=>e({name:"phoenix-create-configurator",description:"Guide a client from product documents and assets to a reviewed Phoenix configurator through a representative first slice, an overall experience plan, iterative implementation, and finalization. Use when creating a configurator, and for every later change that adds or reworks products, options, features or finalization, however small the increment; not for an isolated code fix.",sections:[n,"## Foundations\n\n### Communicate the journey and expectations\n\nExplain all five stages at the start in plain language. Before each stage or increment, say what you will work on, what the client will be able to try, what remains for later, and when you will return for feedback. During longer work, give meaningful progress updates, including what is already usable.\n\nRead supplied information before asking questions. Treat an interview request as permission to gather necessary information throughout the work, not a requirement to ask about every decision before building. Use source-backed facts directly. Choose reversible design defaults yourself, state them briefly, and proceed; do not ask permission to use an illustrated starting configuration, follow supplied branding, or choose a standard Phoenix control.\n\nBefore asking, decide whether the answer would materially change the work due now and whether a useful slice can proceed without it. Ask only for a blocking ambiguity, a consequential business decision needed now, or a material departure from the accepted design. Otherwise record the open issue for the relevant stage. When a question is necessary, explain its consequence and recommend an answer; keep it focused. A client's agreement should lead to the promised work, not another routine approval question. Teach relevant Phoenix approaches through the client's product, without asking them to choose SDK components or operate developer tools.\n\nAt each preview, explain what changed, give a focused action to try, and recommend the next step conditional on feedback. End the turn and wait before expanding the agreed increment unless the client requested a larger autonomous batch. Let them redirect, revisit decisions, or pause; overall scope approval does not remove these feedback points.\n\n### Study Phoenix and use its intended patterns\n\nStudy the documentation in two parts: a core before the first slice, and the rest keyed to what you are about to build. Take the inventory first with `pnpm phoenix docs -l`, which prints every path and title; browse one area with `pnpm phoenix docs -c '<category>'`, read a document with `pnpm phoenix docs -r <returned-path>`, and locate material again with `pnpm phoenix docs -s '<topic>'`. In hosted environments, use the available documentation list/search/read tools instead.\n\nRead the core in full before the first slice: the documents listed as Key Docs in the `phoenix` skill's SDK Documentation section, which carry getting started, the domain model, components, project structure, state, expressions, webhooks, finalization, and migrations, together with the `UX Guidelines` category. That list is maintained there; do not keep a second copy of it here.\n\nRead the rest when an increment reaches it, and before implementing that increment: the remaining `Phoenix` documents for what the increment touches, such as theming and localization when you brand or translate the interface, sharing and sessions when its users receive links, and deployments before going live; `Layouts` and `Controls` for the interface; `3d scene` for the scene; `Relations`, `Recipes & Delete`, `Fabs`, `Drag & Drop`, and `Selection & Highlight` for a product assembled from parts; `Other features` and `Integrations` for finalization and external data; `Performance` before hand-over; and `Complex Use Cases` and `Demos` as worked examples. Take the names from the inventory you listed; this version may group its documentation differently. Judge a category you are deferring by what its documents say they are for, which `pnpm phoenix docs -c '<category>'` prints, not by its name or by how many documents it holds: a small category can hold the one control the product needs.\n\nRecord in the specification which categories you have read and which ones the remaining plan still needs, so a later turn resumes instead of starting again. An index or a search result alone is not a completed study, and reading the core is not permission to skip a category when the increment that needs it arrives.\n\nUse Phoenix's existing components, features, and supported workflows whenever they provide the required capability. Guide the client toward those approaches and explain their benefits. Use custom implementations only when the required capability is unavailable: verify the gap in the documentation, explain it and the proposed approach to the client, and keep the solution compatible with Phoenix's architecture. Missing documentation is not proof that a feature is unavailable.\n\nRevisit the relevant implementation examples as you build. [Phoenix UX guidance](references/phoenix-ux.md) provides navigation back to common topics; platform usage belongs in Phoenix docs rather than a parallel manual in this skill. Disclose inaccessible documentation and the resulting uncertainty instead of claiming full coverage or inventing APIs. Do not assume access to Phoenix's source repository or internal processes.\n\n### Maintain a living Markdown specification\n\nAfter inspecting the materials, create `configurator-spec.md` in the intended project, or update its existing equivalent. Keep it outside public/user-facing assets and use it as the single record of:\n\n- Product scope, intended users, source materials, assets, and confirmed product facts.\n- Configurable options, dependencies, compatibility rules, dimensions, and commercial rules.\n- Unknowns, conflicting information, proposals, agent-chosen design defaults, and explicitly agreed provisional business assumptions, distinguished from confirmed facts and client-approved decisions.\n- Accepted visual direction, navigation, interaction patterns, and finalization decisions, with their rationale.\n- The five-stage plan, current stage, implemented and remaining scope, documentation coverage, verification results, and next increment.\n\nUpdate it whenever new information, a decision, or completed work changes the plan. Keep it concise and current, not a conversation transcript. Read it when resuming, inspect the existing draft, and briefly remind the client where things stand. Preserve accepted behavior and styling; explain and agree on material departures before applying them. The specification supports collaboration without making every edit an approval step.",i,a,o,s,r,t.visualInspection,d]});export const generatePhoenixCreateConfiguratorSkillReferences=()=>[{path:"references/phoenix-ux.md",content:h},{path:"references/product-discovery.md",content:p},{path:"references/asset-conversion.md",content:c},{path:"references/appearance-review.md",content:l}];
+`;export const generatePhoenixCreateConfiguratorSkill=()=>e({name:"phoenix-create-configurator",description:"Guide a client from product documents and assets to a reviewed Phoenix configurator through a representative first slice, an overall experience plan, iterative implementation, and finalization. Use when creating a configurator, and for every later change that adds or reworks products, options, features or finalization, however small the increment; not for an isolated code fix.",sections:[n,t.packageManager,"## Foundations\n\n### Communicate the journey and expectations\n\nExplain all five stages at the start in plain language. Before each stage or increment, say what you will work on, what the client will be able to try, what remains for later, and when you will return for feedback. During longer work, give meaningful progress updates, including what is already usable.\n\nRead supplied information before asking questions. Treat an interview request as permission to gather necessary information throughout the work, not a requirement to ask about every decision before building. Use source-backed facts directly. Choose reversible design defaults yourself, state them briefly, and proceed; do not ask permission to use an illustrated starting configuration, follow supplied branding, or choose a standard Phoenix control.\n\nBefore asking, decide whether the answer would materially change the work due now and whether a useful slice can proceed without it. Ask only for a blocking ambiguity, a consequential business decision needed now, or a material departure from the accepted design. Otherwise record the open issue for the relevant stage. When a question is necessary, explain its consequence and recommend an answer; keep it focused. A client's agreement should lead to the promised work, not another routine approval question. Teach relevant Phoenix approaches through the client's product, without asking them to choose SDK components or operate developer tools.\n\nAt each preview, explain what changed, give a focused action to try, and recommend the next step conditional on feedback. End the turn and wait before expanding the agreed increment unless the client requested a larger autonomous batch. Let them redirect, revisit decisions, or pause; overall scope approval does not remove these feedback points.\n\n### Study Phoenix and use its intended patterns\n\nStudy the documentation in two parts: a core before the first slice, and the rest keyed to what you are about to build. Take the inventory first with `pnpm phoenix docs -l`, which prints every path and title; browse one area with `pnpm phoenix docs -c '<category>'`, read a document with `pnpm phoenix docs -r <returned-path>`, and locate material again with `pnpm phoenix docs -s '<topic>'`. In hosted environments, use the available documentation list/search/read tools instead.\n\nRead the core in full before the first slice: the documents listed as Key Docs in the `phoenix` skill's SDK Documentation section, which carry getting started, the domain model, components, project structure, state, expressions, webhooks, finalization, and migrations, together with the `UX Guidelines` category. That list is maintained there; do not keep a second copy of it here.\n\nRead the rest when an increment reaches it, and before implementing that increment: the remaining `Phoenix` documents for what the increment touches, such as theming and localization when you brand or translate the interface, sharing and sessions when its users receive links, and deployments before going live; `Layouts` and `Controls` for the interface; `3d scene` for the scene; `Relations`, `Recipes & Delete`, `Fabs`, `Drag & Drop`, and `Selection & Highlight` for a product assembled from parts; `Other features` and `Integrations` for finalization and external data; `Performance` before hand-over; and `Complex Use Cases` and `Demos` as worked examples. Take the names from the inventory you listed; this version may group its documentation differently. Judge a category you are deferring by what its documents say they are for, which `pnpm phoenix docs -c '<category>'` prints, not by its name or by how many documents it holds: a small category can hold the one control the product needs.\n\nRecord in the specification which categories you have read and which ones the remaining plan still needs, so a later turn resumes instead of starting again. An index or a search result alone is not a completed study, and reading the core is not permission to skip a category when the increment that needs it arrives.\n\nUse Phoenix's existing components, features, and supported workflows whenever they provide the required capability. Guide the client toward those approaches and explain their benefits. Use custom implementations only when the required capability is unavailable: verify the gap in the documentation, explain it and the proposed approach to the client, and keep the solution compatible with Phoenix's architecture. Missing documentation is not proof that a feature is unavailable.\n\nRevisit the relevant implementation examples as you build. [Phoenix UX guidance](references/phoenix-ux.md) provides navigation back to common topics; platform usage belongs in Phoenix docs rather than a parallel manual in this skill. Disclose inaccessible documentation and the resulting uncertainty instead of claiming full coverage or inventing APIs. Do not assume access to Phoenix's source repository or internal processes.\n\n### Maintain a living Markdown specification\n\nAfter inspecting the materials, create `configurator-spec.md` in the intended project, or update its existing equivalent. Keep it outside public/user-facing assets and use it as the single record of:\n\n- Product scope, intended users, source materials, assets, and confirmed product facts.\n- Configurable options, dependencies, compatibility rules, dimensions, and commercial rules.\n- Unknowns, conflicting information, proposals, agent-chosen design defaults, and explicitly agreed provisional business assumptions, distinguished from confirmed facts and client-approved decisions.\n- Accepted visual direction, navigation, interaction patterns, and finalization decisions, with their rationale.\n- The five-stage plan, current stage, implemented and remaining scope, documentation coverage, verification results, and next increment.\n\nUpdate it whenever new information, a decision, or completed work changes the plan. Keep it concise and current, not a conversation transcript. Read it when resuming, inspect the existing draft, and briefly remind the client where things stand. Preserve accepted behavior and styling; explain and agree on material departures before applying them. The specification supports collaboration without making every edit an approval step.",i,a,o,s,r,t.visualInspection,d]});export const generatePhoenixCreateConfiguratorSkillReferences=()=>[{path:"references/phoenix-ux.md",content:h},{path:"references/product-discovery.md",content:p},{path:"references/asset-conversion.md",content:c},{path:"references/appearance-review.md",content:l}];

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

@@ -1,4 +1,4 @@
-import{renderAgentSkill as e}from"./agent-skill.js";let t=`## When to Raise Feedback
+import{renderAgentSkill as e}from"./agent-skill.js";import{sdkGuidanceSections as t}from"./sdk-content.js";let o=`## When to Raise Feedback
 Draft feedback for the Phoenix team when one of these happens while you work 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 skill or an error message sent you the wrong way, or did not say what you needed.
@@ -6,7 +6,7 @@ Draft feedback for the Phoenix team when one of these happens while you work in
 
 Do not draft feedback for problems in this project's own specs or code, for a suspicion you have not checked, or twice for the same problem. Write one draft per distinct problem.
 
-The evaluation of a finished run is feedback too; the section "Evaluate the Run" says when to ask for it.`,o=`## Ask Before You Send
+The evaluation of a finished run is feedback too; the section "Evaluate the Run" says when to ask for it.`,n=`## Ask Before You Send
 Never send feedback on your own. Show the user a draft and send it only after they approve it.
 
 When to ask is your judgement:
@@ -14,7 +14,7 @@ When to ask is your judgement:
 - **At the end of the task** — everything else. Collect the details while you work and show all drafts together in your final message.
 - **When the user asks** you to send feedback — draft it and show it before sending.
 
-The draft is exactly what would be sent: the type, the full message, the project if you name one with \`--projectSlug\`, and the contact if the user gave one. Send it unchanged after a yes; if the user edits it, send their version. If they decline, drop it and do not raise that problem again.`,n=`## Evaluate the Run
+The draft is exactly what would be sent: the type, the full message, the project if you name one with \`--projectSlug\`, and the contact if the user gave one. Send it unchanged after a yes; if the user edits it, send their version. If they decline, drop it and do not raise that problem again.`,a=`## Evaluate the Run
 When the work on the configurator is finished, interview the user for an evaluation of the run and send it as feedback. The run is finished when the user says they are done, or when \`phoenix deploy\` reported the configurator live and the user 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.
 
 Say first that the answers are sent to the Phoenix team as feedback, and that the user 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:
@@ -46,9 +46,9 @@ 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. Show the user the text exactly as it would be sent, and send it with \`--type other\` only after a yes; if they edit it, send their version. An evaluation is not a bug report: when a comment names a concrete problem, offer to draft it as its own report.`,a=`## What Never Goes Into Feedback
+Keep the labels and their order, so the scores can be read out of the feedback list and its export. Show the user the text exactly as it would be sent, and send it with \`--type other\` only after a yes; if they edit it, send their version. An evaluation is not a bug report: when a comment names a concrete problem, offer to draft it as its own report.`,s=`## What Never Goes Into Feedback
 The message leaves this project and is read by the Phoenix team. Never include:
 - secrets and credentials: API tokens, keys, passwords or \`.env\` values, also when they appear inside an error or a log you quote. Replace each with \`<redacted>\`;
 - personal data, or data of the project's customers and end users, such as names, email addresses and orders, other than a contact the user asked you to add.
 
-Parts of this project may go into a message: file names and paths, snippets of its specs and code, and the user's own words. They are sent only as part of a draft the user saw and approved, which is why the draft you show is always the full text.`;export const generatePhoenixFeedbackSkill=()=>e({name:"phoenix-feedback",description:"Evaluating a finished run and drafting feedback about the Phoenix SDK, CLI, documentation or Studio for the Phoenix team, sent with the phoenix feedback command once the user approves the draft. Use right after phoenix deploy reports the configurator live or when the user says they are done, to offer the evaluation of the run, and when the SDK or CLI misbehaves, a doc or skill misled you, a missing feature forced a workaround or the user asks to send feedback.",sections:[t,o,"## Report Template\nWrite a report 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 you have nothing to put.\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 user asked, what you tried, what failed>\n```\n- **Build** is the latest build of this project, the one 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 sources of the build 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, do not dump it: keep the user's requests, your decisions and the failures, and leave out tool output that the other sections already carry.",n,"## How to Send It\nWrite a report or an evaluation to a text file and send the file, so the shell changes nothing in it:\n```bash\npnpm phoenix feedback --file <path> --type bug --agent '<your agent name>'\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```bash\npnpm phoenix feedback '<message>' --type idea --agent '<your agent name>'\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 you, the coding agent, so the team can tell agent feedback from a person's.\n- `--contact '<email>'` only when the user wants a reply and gave you 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`. If it answers that you are not signed in, tell the user once and continue; do not sign in yourself, because the sign-in is approved in a browser.\n\nAfter sending, confirm it to the user in one line.",a]});
+Parts of this project may go into a message: file names and paths, snippets of its specs and code, and the user's own words. They are sent only as part of a draft the user saw and approved, which is why the draft you show is always the full text.`;export const generatePhoenixFeedbackSkill=()=>e({name:"phoenix-feedback",description:"Evaluating a finished run and drafting feedback about the Phoenix SDK, CLI, documentation or Studio for the Phoenix team, sent with the phoenix feedback command once the user approves the draft. Use right after phoenix deploy reports the configurator live or when the user says they are done, to offer the evaluation of the run, and when the SDK or CLI misbehaves, a doc or skill misled you, a missing feature forced a workaround or the user asks to send feedback.",sections:[t.packageManager,o,n,"## Report Template\nWrite a report 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 you have nothing to put.\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 user asked, what you tried, what failed>\n```\n- **Build** is the latest build of this project, the one 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 sources of the build 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, do not dump it: keep the user's requests, your decisions and the failures, and leave out tool output that the other sections already carry.",a,"## How to Send It\nWrite a report or an evaluation to a text file and send the file, so the shell changes nothing in it:\n```bash\npnpm phoenix feedback --file <path> --type bug --agent '<your agent name>'\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```bash\npnpm phoenix feedback '<message>' --type idea --agent '<your agent name>'\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 you, the coding agent, so the team can tell agent feedback from a person's.\n- `--contact '<email>'` only when the user wants a reply and gave you 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`. If it answers that you are not signed in, tell the user once and continue; do not sign in yourself, because the sign-in is approved in a browser.\n\nAfter sending, confirm it to the user in one line.",s]});

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

@@ -1,4 +1,4 @@
-import{renderAgentSkill as e}from"./agent-skill.js";let s=`Review all current git changes for correctness, Phoenix pattern violations, and security issues.
+import{renderAgentSkill as e}from"./agent-skill.js";import{sdkGuidanceSections as s}from"./sdk-content.js";let i=`Review all current git changes for correctness, Phoenix pattern violations, and security issues.
 
 ## Phoenix-Specific Review
 
@@ -66,7 +66,7 @@ import{renderAgentSkill as e}from"./agent-skill.js";let s=`Review all current gi
 
 ## Auto-Generated Files — DO NOT modify
 
-- .phoenix/ directory (except the option files in .phoenix/variants/, which the phoenix-variants skill writes), eslint.config.js, prettier.config.js
+- .phoenix/ directory (except the option files in .phoenix/variants/, which the phoenix-variants skill writes)
 - src/locales/\\*.ts files
 
 ### Runtime Verification
@@ -112,4 +112,4 @@ import{renderAgentSkill as e}from"./agent-skill.js";let s=`Review all current gi
 - **Overall assessment**: <1-2 sentence summary>
 \`\`\`
 
-If no findings at a severity level, omit that section. If no findings at all, state "No issues found" with a brief note on what was checked.`;export const generatePhoenixReviewSkill=()=>e({name:"phoenix-review",description:"Phoenix-specific code review checklist and report format for specs, expressions, invariants, components, webhooks, TypeScript and React code. Use when reviewing changes in this Phoenix configurator project, before committing or when asked for a code review.",sections:[s]});
+If no findings at a severity level, omit that section. If no findings at all, state "No issues found" with a brief note on what was checked.`;export const generatePhoenixReviewSkill=()=>e({name:"phoenix-review",description:"Phoenix-specific code review checklist and report format for specs, expressions, invariants, components, webhooks, TypeScript and React code. Use when reviewing changes in this Phoenix configurator project, before committing or when asked for a code review.",sections:[s.packageManager,i]});

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

@@ -1 +1 @@
-import{renderAgentSkill as e}from"./agent-skill.js";import{sdkGuidanceSections as t}from"./sdk-content.js";export const followsCanaryBuilds=e=>!e.useWorkspace&&e.sdkVersion.includes("-develop.");export const generatePhoenixSkill=({checkLatestCanary:n})=>e({name:"phoenix",description:`Phoenix SDK project conventions, covering project structure, architecture principles, key patterns, file and export rules, webhook membership, versioning the domain model once it is deployed, showing the user the dev preview and the build of a deploy, the run evaluation that follows a live deploy, inspecting the rendered result, and how to search the SDK documentation${n?", and the internal-beta check for the latest canary SDK build":""}. Use before writing or changing specs or source code, or deploying this Phoenix configurator project.`,sections:[...n?["## Stay on the Latest Canary\nDuring the internal beta this project uses the `canary` build of the SDK, which is published from every change to the platform. Once per conversation, before you change anything, compare the installed version with the newest canary:\n```bash\npnpm list @salsita-ai/sdk --depth 0\nnpm view @salsita-ai/sdk@canary version\n```\nWhen they differ, tell the user which version you are moving to, then update the project and regenerate its files:\n```bash\npnpm add @salsita-ai/sdk@canary\npnpm phoenix sync\n```\n`sync` rewrites the Phoenix skills, so read the ones you use again after it. When the user runs a globally installed `phoenix`, update that too with `npm install -g @salsita-ai/sdk@canary`. If the project no longer builds after the update, stop and tell the user; the `phoenix-feedback` skill covers reporting it."]:[],t.projectStructure,t.architecturePrinciples,t.keyPatterns,t.fileConventions,t.exportRules,t.webhookMembership,t.doNotEdit,t.modelVersioning,"## Show the Preview While You Work\nThe user should see the configurator change as you build it. Before your first change in a conversation, make sure `pnpm phoenix dev` is running (start it in the background when it is not) and open the address it prints as `Preview: <url>` (also written to `.phoenix/phoenix-dev.log`) in the user's browser: `open '<url>'` on macOS, `xdg-open '<url>'` on Linux, `Start-Process '<url>'` in PowerShell, `start \"\" \"<url>\"` in cmd. Keep the quotes, the shell would otherwise read a `?` in the address as a pattern. The log keeps the lines of earlier runs, so when you have just started dev, wait for the `Preview:` line written after your start and use the last one. Open it once; the preview reloads on every change, so tell the user to keep that tab open instead of opening it again.",t.visualInspection,"## Show the Build After a Deploy\nImmediately before invoking `pnpm phoenix deploy`, refresh `conversation.log` in the project root with the current conversation. Prefer the agent application's native session export when available; do not invent an export command or scan unrelated sessions. Otherwise write the messages still available in context and label the log `reconstructed; incomplete`. Never present a compaction summary as verbatim earlier messages.\n\nUse UTF-8 text with a header naming the agent, export time, source (native export or reconstructed), covered session and known omissions. Preserve user and assistant messages in chronological order, plus tool names, arguments and results when available. Keep each tool result to at most 16 KiB of text, marking truncation explicitly; describe image attachments by reference rather than embedding binary/base64 data, and mark references whose files are not uploaded. Exclude internal instructions, hidden reasoning, credentials and unrelated sensitive content; mark redactions without repeating the removed content. Refresh the current session's log rather than appending duplicate copies or silently carrying over a previous session.\n\nShow the user the exact file to review or redact and obtain approval to include it before deploying; do not ask again when they have already approved that file. If they decline, move it out of the project root before deployment so it cannot be collected. Deploy includes the file in the build's private source archive, downloadable by those authorized to download that build's sources, and leaves it out when extracting build inputs. A missing log warns but does not block deployment. The CLI does not export, redact or validate the transcript's completeness for you.\n\n`pnpm phoenix deploy` starts a build on the server and waits for it to go live. Right after `Build <id> started` it prints `Follow the build in Studio: <url>`. Run the deploy so that you can read its output while it runs, and open that link in the user's browser, quoted as above, as soon as it appears, so they can follow the build they just triggered. When the line is missing, the sign-in is older than the link: tell the user the build is listed under Deployments in Studio, and that `pnpm phoenix login <workspace>` brings the link back.\n\nWhen the deploy reports the configurator live, load the `phoenix-feedback` skill before you write your final message and follow its \"Evaluate the Run\" section, so the user is asked about the run while they are still there. It is asked once per conversation, and only once the user has nothing more to build.","## Code Review\nUse the `phoenix-review` skill to review code changes before committing.",t.sdkDocumentation]});
+import{renderAgentSkill as e}from"./agent-skill.js";import{sdkGuidanceSections as t}from"./sdk-content.js";export const followsCanaryBuilds=e=>!e.useWorkspace&&e.sdkVersion.includes("-develop.");export const generatePhoenixSkill=({checkLatestCanary:n})=>e({name:"phoenix",description:`Phoenix SDK project conventions, covering project structure, architecture principles, key patterns, file and export rules, webhook membership, versioning the domain model once it is deployed, showing the user the dev preview and the build of a deploy, the run evaluation that follows a live deploy, inspecting the rendered result, and how to search the SDK documentation${n?", and the internal-beta check for the latest canary SDK build":""}. Use before writing or changing specs or source code, or deploying this Phoenix configurator project.`,sections:[t.packageManager,...n?["## Stay on the Latest Canary\nDuring the internal beta this project uses the `canary` build of the SDK, which is published from every change to the platform. Once per conversation, before you change anything, compare the installed version, the `version` in `node_modules/@salsita-ai/sdk/package.json`, with the newest canary:\n```bash\nnpm view @salsita-ai/sdk@canary version\n```\nWhen they differ, tell the user which version you are moving to, then update the SDK, bring the packages it needs next to it in line, and regenerate the project's files:\n```bash\npnpm add @salsita-ai/sdk@canary && pnpm phoenix deps && pnpm install && pnpm phoenix sync\n```\n`sync` rewrites the Phoenix skills, so read the ones you use again after it. When the user runs a globally installed `phoenix`, update that too with `npm install -g @salsita-ai/sdk@canary`. If the project no longer builds after the update, stop and tell the user; the `phoenix-feedback` skill covers reporting it."]:[],t.projectStructure,t.architecturePrinciples,t.keyPatterns,t.fileConventions,t.exportRules,t.webhookMembership,t.doNotEdit,t.modelVersioning,"## Show the Preview While You Work\nThe user should see the configurator change as you build it. Before your first change in a conversation, make sure `pnpm phoenix dev` is running (start it in the background when it is not) and open the address it prints as `Preview: <url>` (also written to `.phoenix/phoenix-dev.log`) in the user's browser: `open '<url>'` on macOS, `xdg-open '<url>'` on Linux, `Start-Process '<url>'` in PowerShell, `start \"\" \"<url>\"` in cmd. Keep the quotes, the shell would otherwise read a `?` in the address as a pattern. The log keeps the lines of earlier runs, so when you have just started dev, wait for the `Preview:` line written after your start and use the last one. Open it once; the preview reloads on every change, so tell the user to keep that tab open instead of opening it again.",t.visualInspection,"## Show the Build After a Deploy\nImmediately before invoking `pnpm phoenix deploy`, refresh `conversation.log` in the project root with the current conversation. Prefer the agent application's native session export when available; do not invent an export command or scan unrelated sessions. Otherwise write the messages still available in context and label the log `reconstructed; incomplete`. Never present a compaction summary as verbatim earlier messages.\n\nUse UTF-8 text with a header naming the agent, export time, source (native export or reconstructed), covered session and known omissions. Preserve user and assistant messages in chronological order, plus tool names, arguments and results when available. Keep each tool result to at most 16 KiB of text, marking truncation explicitly; describe image attachments by reference rather than embedding binary/base64 data, and mark references whose files are not uploaded. Exclude internal instructions, hidden reasoning, credentials and unrelated sensitive content; mark redactions without repeating the removed content. Refresh the current session's log rather than appending duplicate copies or silently carrying over a previous session.\n\nShow the user the exact file to review or redact and obtain approval to include it before deploying; do not ask again when they have already approved that file. If they decline, move it out of the project root before deployment so it cannot be collected. Deploy includes the file in the build's private source archive, downloadable by those authorized to download that build's sources, and leaves it out when extracting build inputs. A missing log warns but does not block deployment. The CLI does not export, redact or validate the transcript's completeness for you.\n\n`pnpm phoenix deploy` starts a build on the server and waits for it to go live. Right after `Build <id> started` it prints `Follow the build in Studio: <url>`. Run the deploy so that you can read its output while it runs, and open that link in the user's browser, quoted as above, as soon as it appears, so they can follow the build they just triggered. When the line is missing, the sign-in is older than the link: tell the user the build is listed under Deployments in Studio, and that `pnpm phoenix login <workspace>` brings the link back.\n\nWhen the deploy reports the configurator live, load the `phoenix-feedback` skill before you write your final message and follow its \"Evaluate the Run\" section, so the user is asked about the run while they are still there. It is asked once per conversation, and only once the user has nothing more to build.","## Code Review\nUse the `phoenix-review` skill to review code changes before committing.",t.sdkDocumentation]});

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

@@ -1,6 +1,6 @@
-import{renderAgentSkill as e}from"./agent-skill.js";let t=`## When to Offer Options
+import{renderAgentSkill as e}from"./agent-skill.js";import{sdkGuidanceSections as t}from"./sdk-content.js";let n=`## When to Offer Options
 - Offer options when the answer is a matter of taste or brand and the supplied materials do not settle it.
 - Do not offer options for facts (dimensions, prices, rules), for something the user already decided, or to avoid a decision you can make yourself and state.
 - One decision per set, one set open at a time. Vary one thing and keep everything else identical.
 - Usually offer two to four options; the system has no fixed option limit. Original is always available as the captured baseline.
-- Make the options differ in a way the UI or scene can show. Three sheens of one matte wood in soft light look the same.`;export const generatePhoenixVariantsSkill=()=>e({name:"phoenix-variants",description:"Showing the user a few options over the dev preview and getting their pick back, with the phoenix variants command. Use when a visual or interaction decision has several reasonable answers and the taste of the user decides it, such as a shape, a material setting, lighting, an environment, a control or a flow.",sections:[t,"## Choose the Kind of Option\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 file-watcher debounce; hot reload still takes time to apply, without a special wait for rendering to settle.",'## Write the Options\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; it 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 files the previous option alone 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- Name options in the user\'s product language; explain what changes in one line.','## Run It and Wait\n```bash\npnpm phoenix variants .phoenix/variants/<name> --title \'<the question>\' --description \'<what differs between the options>\'\n```\n- `pnpm phoenix dev` must be running with the preview open in a browser. Tell the user 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 your turn and run it when the user 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 you give up on it.\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.',"## Use the Answer\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 user chose Original and the baseline remains. Verify the result using `pnpm phoenix inspect:scene` and `pnpm phoenix screenshot`, and tell the user anything that came out differently.\n- Record the decision and its reason where the project keeps its decisions, such as `configurator-spec.md`.\n- The user confirms Original or another option; Escape and the backdrop do not close the comparison. The agent can use `--close` to restore baseline source files without an answer. The folder is removed once the user answers. Pass `--keep` when you still need the files to build from, and remove the folder yourself afterwards."]});
+- Make the options differ in a way the UI or scene can show. Three sheens of one matte wood in soft light look the same.`;export const generatePhoenixVariantsSkill=()=>e({name:"phoenix-variants",description:"Showing the user a few options over the dev preview and getting their pick back, with the phoenix variants command. Use when a visual or interaction decision has several reasonable answers and the taste of the user decides it, such as a shape, a material setting, lighting, an environment, a control or a flow.",sections:[t.packageManager,n,"## Choose the Kind of Option\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 file-watcher debounce; hot reload still takes time to apply, without a special wait for rendering to settle.",'## Write the Options\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; it 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 files the previous option alone 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- Name options in the user\'s product language; explain what changes in one line.','## Run It and Wait\n```bash\npnpm phoenix variants .phoenix/variants/<name> --title \'<the question>\' --description \'<what differs between the options>\'\n```\n- `pnpm phoenix dev` must be running with the preview open in a browser. Tell the user 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 your turn and run it when the user 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 you give up on it.\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.',"## Use the Answer\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 user chose Original and the baseline remains. Verify the result using `pnpm phoenix inspect:scene` and `pnpm phoenix screenshot`, and tell the user anything that came out differently.\n- Record the decision and its reason where the project keeps its decisions, such as `configurator-spec.md`.\n- The user confirms Original or another option; Escape and the backdrop do not close the comparison. The agent can use `--close` to restore baseline source files without an answer. The folder is removed once the user answers. Pass `--keep` when you still need the files to build from, and remove the folder yourself afterwards."]});

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

@@ -6,12 +6,24 @@
  * only in which sections they carry.
  */
 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>\`
+
+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 run \`pnpm install\` after it`;
+- \`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\`
@@ -82,7 +94,6 @@ The default export must be what the folder's phx factory returns (for example \`
     /** 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
-- \`eslint.config.js\`, \`prettier.config.js\`, \`.linguirc\`, \`.nvmrc\`
 - \`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. */

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

@@ -1,10 +1,10 @@
-export const sdkGuidanceSections={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 run `pnpm 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, or the app loader stays on screen; put the UI above it, positioned and after it in the markup. Call `useSceneSafeArea()` (same import) 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\n    - Messages: mount `LayoutSlots.Services` for the built-in snackbars, or show violations, side-effect hints and errors yourself with `phx.frontend.useConfiguratorMessages(onMessage)`, not both. Either way mount a snackbar root (`LayoutSlots.DesktopSnackbarsRoot` or `LayoutSlots.MobileSnackbarsRoot`): save and built-in action errors are always snackbars\n    - Finalize over the spec's `finalizeAction` components, each naming a handler registered with `phx.frontend.createPhoenixHandler`: run each with `phx.frontend.useFinalizeAction(handler)` in a component of its own wrapped in `PhoenixHandlerBoundary` (from `@salsita-ai/sdk/react`), or mount `FinalizeActions` (from `@salsita-ai/sdk/configurator`) for the built-in buttons. `finalizePage` and `finalizeButton` are legacy\n    - Read mode and fullscreen are the layout's job, no hook enforces them: hide what a viewer must not change while `phx.frontend.useAccessService().accessInfo.viewMode` is `true`, and remove panels while `phx.frontend.useIsFullscreenActive()` is set; `phx.frontend.useSetFullscreen()` returns its setter\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
+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, or the app loader stays on screen; put the UI above it, positioned and after it in the markup. Call `useSceneSafeArea()` (same import) 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\n    - Messages: mount `LayoutSlots.Services` for the built-in snackbars, or show violations, side-effect hints and errors yourself with `phx.frontend.useConfiguratorMessages(onMessage)`, not both. Either way mount a snackbar root (`LayoutSlots.DesktopSnackbarsRoot` or `LayoutSlots.MobileSnackbarsRoot`): save and built-in action errors are always snackbars\n    - Finalize over the spec's `finalizeAction` components, each naming a handler registered with `phx.frontend.createPhoenixHandler`: run each with `phx.frontend.useFinalizeAction(handler)` in a component of its own wrapped in `PhoenixHandlerBoundary` (from `@salsita-ai/sdk/react`), or mount `FinalizeActions` (from `@salsita-ai/sdk/configurator`) for the built-in buttons. `finalizePage` and `finalizeButton` are legacy\n    - Read mode and fullscreen are the layout's job, no hook enforces them: hide what a viewer must not change while `phx.frontend.useAccessService().accessInfo.viewMode` is `true`, and remove panels while `phx.frontend.useIsFullscreenActive()` is set; `phx.frontend.useSetFullscreen()` returns its setter\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. 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- `eslint.config.js`, `prettier.config.js`, `.linguirc`, `.nvmrc`\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
+- 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. 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\`.
 

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

@@ -0,0 +1,58 @@
+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.
+ */
+export type SpecCodePath = ReadonlyArray<string | number>;
+/**
+ * What one piece of YAML code produces, which the generated closure is typed by.
+ *
+ * - `expression`: the value of the value expression `name` of `owner`, at each of `paths`.
+ * - `component`: the state of the component `componentName`, at each of `paths` (one per prop the
+ *   code fills).
+ * - `filter`: the value of the filter criterion `criterion`.
+ *
+ * A `$eval` that appears more than once in one value is one dependency of its plan, so it has one
+ * closure, which must fit every place it fills.
+ */
+export type SpecCodeTarget = {
+    readonly kind: 'expression';
+    readonly name: string;
+    readonly paths: readonly SpecCodePath[];
+} | {
+    readonly kind: 'component';
+    readonly componentName: string;
+    readonly paths: readonly SpecCodePath[];
+} | {
+    readonly kind: 'filter';
+    readonly criterion: string;
+};
+/** One piece of code written in YAML, as the generated code module holds it. */
+export interface SpecCodeEntry {
+    readonly id: SpecCodeId;
+    /** The entity or alias the code runs on: `self` is its `$` view. */
+    readonly owner: string;
+    readonly code: string;
+    /**
+     * Whether the code reads `self`. A closure that does not gets no parameter, because the projects'
+     * `noUnusedParameters` would reject an unused `self`.
+     */
+    readonly usesSelf: boolean;
+    readonly target: SpecCodeTarget;
+}
+/** The sections of one domain (configurator or admin) that hold code written in YAML. */
+export interface SpecCodeDomain {
+    readonly expressions: Expressions;
+    readonly components: readonly ComponentEntry[];
+}
+/**
+ * Lists every piece of code written in YAML in one domain: the `$eval` of value expressions
+ * (constants share the plan of their expression), of component props and of filter criteria,
+ * including the filters the SDK adds to the admin pages. Each comes with its id, the entity or alias
+ * it runs on and the target that types its closure.
+ *
+ * Throws when one id names two different pieces of code: ids are built from names the parser keeps
+ * unique, so that is a bug.
+ */
+export declare const collectSpecCode: (domain: SpecCodeDomain) => readonly SpecCodeEntry[];

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

@@ -0,0 +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()]};

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

@@ -0,0 +1,2 @@
+export { generateApplicationSpecCodeFile } from './spec-code.js';
+export { collectSpecCode } from './collect-spec-code.js';

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

@@ -0,0 +1 @@
+export{generateApplicationSpecCodeFile}from"./spec-code.js";export{collectSpecCode}from"./collect-spec-code.js";