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

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

@@ -1,4 +1,4 @@
-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 h=[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 {
+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}`)}
   }
 
@@ -38,13 +38,12 @@ ${y([...s,...p],e=>`readonly $${e}: Admin.$${e}`)}
     readonly ApplicationTypes: ApplicationTypes
   }`)].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="vite/client" />
 /// <reference types="@salsita-ai/sdk/globals" />
 
 ${f.toTypeOnlyString(".phoenix/globals.d.ts")}
 
 declare global {
-${h}
+${u}
 
   interface PhxGlobal {
     readonly frontendEnv: import('./frontend.config.js').RuntimeConfig
@@ -74,6 +73,7 @@ ${h}
       readonly implementCustomExpressions: typeof import('./domain-spec.js').implementCustomExpressions
       readonly implementCustomInvariants: typeof import('./domain-spec.js').implementCustomInvariants
       readonly implementActions: typeof import('./domain-spec.js').implementActions
+      readonly createAssistantSetupHandler: typeof import('./domain-spec.js').createAssistantSetupHandler
       readonly attachComponent: typeof import('./domain-spec.js').attachComponent
       readonly createRecipe: typeof import('./domain-spec.js').createRecipe
 

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

@@ -47,9 +47,9 @@ export { type PhoenixSkillOptions, followsCanaryBuilds, generatePhoenixSkill } f
 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 { generateApplicationSpecWebhookImplementation } from './webhook-implementation.js';
 export { generateApplicationSpecWebhookIndex } from './webhook-index.js';
 export { generateApplicationSpecWebhooksConfig } from './webhooks-config.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{generateApplicationSpecStoryDevDeclaration,generateApplicationSpecStoryPhxModule,generateApplicationSpecStoryRawProjectFiles,generateApplicationSpecStoryWrapper}from"./story/index.js";export{generateApplicationSpecTsconfig}from"./tsconfig.js";export{generateApplicationSpecWebhookBuilders}from"./webhook-builders.js";export{generateApplicationSpecWebhookImplementation}from"./webhook-implementation.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{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";

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

@@ -1 +1 @@
-let e=["@salsita-ai/platform-project-sdk","@salsita-ai/platform-common","@salsita-ai/platform-contracts","@salsita-ai/common","@salsita-ai/contracts"],t={private:!0,type:"module",packageManager:"pnpm@11.1.3",engines:{node:"24.14.1",pnpm:"11.1.3"}},r={"babel-plugin-macros":"3.1.0",vite:"6.4.3","@vitejs/plugin-react":"5.2.0","@swc/cli":"0.8.1","@swc/core":"1.15.40",typescript:"npm:@typescript/typescript6@6.0.2","@lingui/cli":"5.9.5","@types/lodash-es":"4.17.12","@lingui/macro":"5.9.5","@lingui/swc-plugin":"5.11.0","@types/node":"24.12.2","@types/react":"18.3.8","@types/react-dom":"18.3.0","@types/three":"0.160.0","@typescript/native":"npm:typescript@7.0.2",envalid:"8.1.1",eslint:"9.39.4",prettier:"3.8.3",vitest:"4.1.11"},i=e=>"object"==typeof e&&null!==e&&!Array.isArray(e),a=e=>{if(!i(e))return;let t=[];for(let[r,i]of Object.entries(e)){if("string"!=typeof i)return;t.push([r,i])}return Object.fromEntries(t)},s=e=>e.replace(/^[\^~]/,""),n=(t,r)=>{let i={};for(let[e,r]of Object.entries(t))i[e]=s(r);if(r)for(let[e,t]of Object.entries(r))e in i||(i[e]=s(t));return Object.fromEntries(Object.entries(i).filter(([t])=>!e.includes(t)).sort(([e],[t])=>e>t?1:e<t?-1:0))};export const generateApplicationSpecPackageJson=e=>{let{sdkVersion:s,useWorkspace:c,useClerk:o=!1,name:p,description:l,existingContent:m}=e,u=(e=>{if(!e)return{};try{let t=JSON.parse(e);if(i(t))return t}catch{}return{}})(m),f=n({...o?{"@clerk/clerk-react":"5.61.8"}:{},"camera-controls":"2.4.2","lodash-es":"4.18.1",react:"18.3.1","react-dom":"18.3.1","@emotion/react":"11.11.3","@emotion/styled":"11.11.0","@mui/material":"5.15.5","@mui/system":"5.16.7","@lingui/core":"5.9.5","@lingui/react":"5.9.5",three:"0.160.1","@react-three/fiber":"8.15.16","@react-three/drei":"9.97.6","@react-three/postprocessing":"2.16.3",motion:"12.34.0","@tanstack/react-query":"5.100.14",rxjs:"7.8.2",uuid:"14.0.0","ts-pattern":"5.9.0","@salsita-ai/sdk":c?"workspace:^":s,zod:"3.25.76"},a(u.dependencies)),d=n(r,a(u.devDependencies)),y=u.name,g=p?p.toLowerCase().replace(/[^a-z0-9-]/g,"-"):"string"==typeof y?y:"project-name",j={...u,name:g,...t,dependencies:f,devDependencies:d};return void 0!==l&&(j.description=l),JSON.stringify(j,null,2)+"\n"};
+let e=["@salsita-ai/platform-project-sdk","@salsita-ai/platform-common","@salsita-ai/platform-contracts","@salsita-ai/common","@salsita-ai/contracts"],t={private:!0,type:"module",packageManager:"pnpm@11.1.3",engines:{node:"24.14.1",pnpm:"11.1.3"}},r={"babel-plugin-macros":"3.1.0",vite:"6.4.3","@vitejs/plugin-react":"5.2.0","@swc/cli":"0.8.1","@swc/core":"1.15.40",typescript:"npm:@typescript/typescript6@6.0.2","@lingui/cli":"5.9.5","@types/lodash-es":"4.17.12","@lingui/macro":"5.9.5","@lingui/swc-plugin":"5.11.0","@types/node":"24.12.2","@types/react":"18.3.8","@types/react-dom":"18.3.0","@types/three":"0.160.0","@typescript/native":"npm:typescript@7.0.2",envalid:"8.1.1",eslint:"9.39.4",prettier:"3.8.3",vitest:"4.1.11"},i=e=>"object"==typeof e&&null!==e&&!Array.isArray(e),s=e=>{if(!i(e))return;let t=[];for(let[r,i]of Object.entries(e)){if("string"!=typeof i)return;t.push([r,i])}return Object.fromEntries(t)},a=e=>e.replace(/^[\^~]/,""),n=(t,r)=>{let i={};for(let[e,r]of Object.entries(t))i[e]=a(r);if(r)for(let[e,t]of Object.entries(r))e in i||(i[e]=a(t));return Object.fromEntries(Object.entries(i).filter(([t])=>!e.includes(t)).sort(([e],[t])=>e>t?1:e<t?-1:0))};export const generateApplicationSpecPackageJson=e=>{let{sdkVersion:a,useWorkspace:c,useClerk:o=!1,name:p,description:l,existingContent:m}=e,u=(e=>{if(!e)return{};try{let t=JSON.parse(e);if(i(t))return t}catch{}return{}})(m),f=n({...o?{"@clerk/clerk-react":"5.61.8"}:{},"camera-controls":"2.4.2","lodash-es":"4.18.1",react:"18.3.1","react-dom":"18.3.1","@emotion/react":"11.11.3","@emotion/styled":"11.11.0","@mui/material":"5.15.5","@mui/system":"5.16.7","@lingui/core":"5.9.5","@lingui/react":"5.9.5",three:"0.160.1","@react-three/fiber":"8.15.16","@react-three/drei":"9.97.6","@react-three/postprocessing":"2.16.3",postprocessing:"6.36.3",motion:"12.34.0","@tanstack/react-query":"5.100.14",rxjs:"7.8.2",uuid:"14.0.0","ts-pattern":"5.9.0","@salsita-ai/sdk":c?"workspace:^":a,zod:"3.25.76"},s(u.dependencies)),d=n(r,s(u.devDependencies)),y=u.name,g=p?p.toLowerCase().replace(/[^a-z0-9-]/g,"-"):"string"==typeof y?y:"project-name",j={...u,name:g,...t,dependencies:f,devDependencies:d};return void 0!==l&&(j.description=l),JSON.stringify(j,null,2)+"\n"};

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

@@ -0,0 +1,6 @@
+/**
+ * The project's root `tsconfig.json`, written once when the project has none: it extends the
+ * generated settings in `.phoenix/tsconfig.json`, so editors and tools that look for a
+ * `tsconfig.json` in the project root find them. It is the project's afterwards, to add to.
+ */
+export declare const generateApplicationSpecRootTsconfig: () => string;

package/dist/application-spec/generate-application/code/templates/root-tsconfig.js

@@ -0,0 +1,2 @@
+export const generateApplicationSpecRootTsconfig=()=>`{ "extends": "./.phoenix/tsconfig.json" }
+`;

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 and sync 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.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-review-skill.js

@@ -1,4 +1,4 @@
-import{renderAgentSkill as e}from"./agent-skill.js";let i=`Review all current git changes for correctness, Phoenix pattern violations, and security issues.
+import{renderAgentSkill as e}from"./agent-skill.js";let s=`Review all current git changes for correctness, Phoenix pattern violations, and security issues.
 
 ## Phoenix-Specific Review
 
@@ -28,6 +28,12 @@ import{renderAgentSkill as e}from"./agent-skill.js";let i=`Review all current gi
 - [ ] No unnecessary React re-renders (stable object references via memoEval)
 - [ ] Export pattern correct: default export of single component or array
 
+### Assistant setup (src/handlers/)
+
+- [ ] At most one phx.domain.createAssistantSetupHandler, synchronous, pure and deterministic over manifest and session inputs
+- [ ] Only removes original declaration entries, exposes descriptions and restriction flags, and rejects immutable keys
+- [ ] Narrows fields on the declaring alias before expansion; runs in browser execution and the webhook; browser GraphQL, tools and change recording use session narrowing while UI retains pure spec selectors; empty server instructions clear the baseline
+
 ### Webhooks (src/webhooks/)
 
 - [ ] Use phx.webhooks.\\*Builder pattern (finalizeHandlerBuilder, authHandlerBuilder)
@@ -60,7 +66,7 @@ import{renderAgentSkill as e}from"./agent-skill.js";let i=`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), tsconfig.json, eslint.config.js, prettier.config.js
+- .phoenix/ directory (except the option files in .phoenix/variants/, which the phoenix-variants skill writes), eslint.config.js, prettier.config.js
 - src/locales/\\*.ts files
 
 ### Runtime Verification
@@ -106,4 +112,4 @@ import{renderAgentSkill as e}from"./agent-skill.js";let i=`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:[i]});
+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]});

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 in 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\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:[...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]});

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

@@ -6,11 +6,12 @@
  * only in which sections they carry.
  */
 export declare const sdkGuidanceSections: {
-    /** The three everyday `phoenix` package scripts. */
+    /** 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 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`;
     /** 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\`
@@ -26,9 +27,15 @@ export declare const sdkGuidanceSections: {
 - \`src/transformers/\` — Automatic state fixers (\`phx.frontend.transformerBuilder\`)
 - \`src/components/\` — ECS system components (\`phx.domain.attachComponent.withEntity()\`)
 - \`src/elements/\` — Page-level React components (\`phx.frontend.createCustomPhoenixLayoutElement()\`)
-  - A layout element named \`ConfiguratorLayout\` replaces everything the built-in layout renders for a loaded configuration, the finalize page included, so prefer arranging the layout in the spec; when you register it, mount \`LayoutSlots.SharedCanvas\` (from \`@salsita-ai/sdk/configurator\`) in it, or the app loader stays on screen, and call \`useSceneSafeArea()\` (same import) with its \`containerRef\` on the element covering the whole canvas and its \`safeAreaRef\` on the region the layout's UI leaves free, so the camera frames the scene there
+  - \`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
+    - 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
+    - Sidebar moved, contents as the spec configures them: mount \`LayoutSlots.DesktopSidebar\` in a positioned container that sets its size, with \`side="start"\` on the left; \`docs/layouts/sidebar/in-a-custom-layout.mdx\` is the whole layout
+    - Your own UI: "Hooks for a Project Layout" in \`docs/phoenix/configurator-interface.mdx\` lists the hooks with what each returns (\`pnpm phoenix docs -r docs/phoenix/configurator-interface.mdx\`), \`docs/phoenix/layout-slots.mdx\` the built-in pieces you can still mount, and \`docs/layouts/custom-layout.mdx\` is a worked example
+    - 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
+    - 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
+    - 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
 - \`src/handlers/\` — Event & lifecycle handlers
-- \`src/webhooks/\` — Server-side webhook handlers (\`phx.webhooks.*Builder\`)
+- \`src/webhooks/\` — Server-side webhook handlers (\`phx.webhooks.*Builder\`); the webhook is the default export of \`src/webhooks/index.ts\`, which you create when the project needs its own handlers — without it the build uses a built-in inert webhook that answers only anonymous auth, so create the file before setting \`useAuthHook\` or \`useClerk\`
 - \`src/migrations/\` — Schema version migrations (v*.ts)
 - \`src/locales/\` — Locale catalogs (authored .po sources; compiled .ts, do not edit)
 - \`src/admin/\` — Admin interface (mirrors main src/ structure)
@@ -67,14 +74,15 @@ The default export must be what the folder's phx factory returns (for example \`
     /** Which components and handlers are bundled into the webhook. */
     readonly webhookMembership: `## Webhook Membership
 - User-authored components, admin components, and handlers are frontend-only by default.
-- A handler that registers \`createMapPublishedRevisionDataHandler\`, \`createMapPublishedChunkedDataHandler\`, \`createDataRowValidatorHandler\`, or \`createSheetValidatorHandler\` is included in the webhook automatically.
+- A handler that registers \`phx.domain.createAssistantSetupHandler\`, \`createMapPublishedRevisionDataHandler\`, \`createMapPublishedChunkedDataHandler\`, \`createDataRowValidatorHandler\`, or \`createSheetValidatorHandler\` is included in the webhook automatically.
+- An assistant setup handler receives the declaration-shaped whitelist and { role, sessionData, access }. Keep the exact entity/alias split from YAML; inherited fields and expanded member entries are absent. Narrow original declarations, then the SDK expands them. Use project-defined role/session data for per-user customization. Keep the handler synchronous, pure and deterministic. The handler runs in the browser and webhook. Return null to disable assistant execution, or omit whitelist entries to restrict them. Button and panel visibility use spec presence; project developers own dynamic UI filtering through normal layout mechanics such as $filter. Leaves expose optional descriptions; writable options allow only validate: true and allowDryRuns: false; recipe groups allow descriptions and allowDryRuns: false. Deletable entries are {}. Names, component bindings, hints and types are internal. Omitted overrides retain baseline values. Existing entity, enhanced-entity and action types constrain the handler; no separate generated manifest types. Browser GraphQL, tools and change recording use the session-derived manifest; rejected setup fails closed. UI reads the pure spec selector. Omitted server instructions or AI fields preserve the baseline. An empty server instructions string clears it.
 - To include another component or handler in the webhook, put \`'use webhook'\` as its first statement (leading comments are allowed).
 - A webhook-included file and its runtime local-import closure must not import browser SDK entrypoints (\`application\`, \`admin\`, \`configurator\`, \`editor\`, \`react\`, \`ui\`) or style/font/image assets. Spec parsing reports the unsafe import and inclusion reason as a diagnostic.
 - Keep browser rendering in an unpinned file. Move shared server-safe logic into a separate module when both frontend and webhook code need it.`;
     /** Generated files a project must not edit. */
     readonly doNotEdit: `## Do Not Edit
-- \`.phoenix/\` directory — completely regenerated on each build. The one exception is \`.phoenix/variants/\`, where the \`phoenix-variants\` skill has you write option files; a rebuild keeps it
-- \`tsconfig.json\`, \`eslint.config.js\`, \`prettier.config.js\`, \`.linguirc\`, \`.nvmrc\`
+- \`.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",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  - A layout element named `ConfiguratorLayout` replaces everything the built-in layout renders for a loaded configuration, the finalize page included, so prefer arranging the layout in the spec; when you register it, mount `LayoutSlots.SharedCanvas` (from `@salsita-ai/sdk/configurator`) in it, or the app loader stays on screen, and call `useSceneSafeArea()` (same import) with its `containerRef` on the element covering the whole canvas and its `safeAreaRef` on the region the layout's UI leaves free, so the camera frames the scene there\n- `src/handlers/` — Event & lifecycle handlers\n- `src/webhooks/` — Server-side webhook handlers (`phx.webhooks.*Builder`)\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={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
 - 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 `createMapPublishedRevisionDataHandler`, `createMapPublishedChunkedDataHandler`, `createDataRowValidatorHandler`, or `createSheetValidatorHandler` is included in the webhook automatically.\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\n- `tsconfig.json`, `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- `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
 
 Get the current editor context data as JSON via \`pnpm phoenix inspect:data\`.
 

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

@@ -1 +1,6 @@
+/**
+ * The project's TypeScript settings, generated to `.phoenix/tsconfig.json` and rewritten whenever they
+ * differ. Paths are relative to `.phoenix/`. The project's root `tsconfig.json` extends this file, and
+ * `phoenix check` uses it directly when the project has no root `tsconfig.json`.
+ */
 export declare const generateApplicationSpecTsconfig: () => string;

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

@@ -31,6 +31,6 @@ export const generateApplicationSpecTsconfig=()=>`{
 
     "paths": {}
   },
-  "include": ["src", ".phoenix", "prettier.config.js", "eslint.config.js", "./.phoenix/globals.d.ts"]
+  "include": ["../src", ".", "../prettier.config.js", "../eslint.config.js", "./globals.d.ts"]
 }
 `;

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

@@ -1 +1,6 @@
-export declare const generateApplicationSpecWebhookIndex: () => string;
+/** Where the generated webhook entry takes its handler from. */
+export interface WebhookIndexOptions {
+    /** Whether the project has `src/webhooks/index.ts`; without it the entry holds the built-in webhook. */
+    readonly hasWebhookEntry: boolean;
+}
+export declare const generateApplicationSpecWebhookIndex: ({ hasWebhookEntry }: WebhookIndexOptions) => string;

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

@@ -1,7 +1,16 @@
-import{autoHeader as e}from"../common/file-headers.js";export const generateApplicationSpecWebhookIndex=()=>`${e("webhook.ts","Webhook entry point — imports builders (sets globalThis.phx.webhooks) then re-exports user handler.")}
+import{autoHeader as e}from"../common/file-headers.js";export const generateApplicationSpecWebhookIndex=({hasWebhookEntry:o})=>o?`${e("webhook.ts","Webhook entry point — imports builders (sets globalThis.phx.webhooks) then re-exports user handler.")}
 export * as builders from './webhook-builders.js'
 
 import implementation from '../src/webhooks/index.js'
 
 export const handler = implementation
+`:`${e("webhook.ts","Webhook entry point — imports builders (sets globalThis.phx.webhooks) then exports the built-in handler, because the project has no src/webhooks/index.ts.")}
+export * as builders from './webhook-builders.js'
+
+// A webhook needs at least one handler; anonymous auth stays inert until spec/application.yaml sets useAuthHook
+const authHandler = phx.webhooks.authHandlerBuilder
+  .withAnonymousHandler(async () => ({ success: true, data: {}, role: 'anonymous' }))
+  .build()
+
+export const handler = phx.webhooks.webhookBuilder.withAuthHook(authHandler).build()
 `;

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

@@ -1,6 +1,5 @@
-import{generateEnvReader as e}from"../common/env-reader.js";import{autoHeader as r}from"../common/file-headers.js";let t={IS_DEV:{type:"bool",default:!1,devDefault:!0},ASSISTANT_STRICT_THREADS:{type:"bool",default:!1},AWS_S3_PUBLIC_RESOURCES_BUCKET:{type:"str",required:!0},AWS_S3_RESOURCES_REGION:{type:"str",required:!0},DEPLOYMENT_RESOURCES_PATH:{type:"str",default:"deployment-resources"}},o={CLERK_API_KEY:{type:"str",required:!0},FRONTEND_URL:{type:"str",required:!0},JWT_SECRET_BASE64:{type:"str",required:!0},OAUTH_PROVIDER_CLIENT_ID:{type:"str",required:!0},OAUTH_PROVIDER_CLIENT_SECRET:{type:"str",required:!0},OAUTH_PROVIDER_BASE_URL:{type:"str",required:!0},RESOURCES_URL:{type:"str",required:!0}};export const generateApplicationSpecWebhooksConfig=i=>{let n=i.infra.env?.webhook??{},R=i.appMetadata.useClerk?o:{},{imports:E,config:p}=e({...t,...R,...n}),_=E.length>0?`import { ${E.join(", ")} } from 'envalid'
-`:"";return`${r("webhooks.config.ts","Runtime environment config for the webhook server.")}
-${_}import { createEnvReader } from '@salsita-ai/sdk/common/env'
+import{generateEnvReader as e}from"../common/env-reader.js";import{autoHeader as r}from"../common/file-headers.js";let t={IS_DEV:{type:"bool",default:!1,devDefault:!0},ASSISTANT_STRICT_THREADS:{type:"bool",default:!1},AWS_S3_PUBLIC_RESOURCES_BUCKET:{type:"str",required:!0},AWS_S3_RESOURCES_REGION:{type:"str",required:!0},DEPLOYMENT_RESOURCES_PATH:{type:"str",default:"deployment-resources"}},o={CLERK_API_KEY:{type:"str",required:!0},FRONTEND_URL:{type:"str",required:!0},JWT_SECRET_BASE64:{type:"str",required:!0},OAUTH_PROVIDER_CLIENT_ID:{type:"str",required:!0},OAUTH_PROVIDER_CLIENT_SECRET:{type:"str",required:!0},OAUTH_PROVIDER_BASE_URL:{type:"str",required:!0},RESOURCES_URL:{type:"str",required:!0}};export const generateApplicationSpecWebhooksConfig=i=>{let n=i.infra.env?.webhook??{},R=i.appMetadata.useClerk?o:{},{imports:E,config:p}=e({...t,...R,...n}),_=[...E,"createEnvReader"].sort();return`${r("webhooks.config.ts","Runtime environment config for the webhook server.")}
+import { ${_.join(", ")} } from '@salsita-ai/sdk/common/env'
 
 const readRuntimeConfig = createEnvReader(${p})
 

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

@@ -1,5 +1,7 @@
 export * from './runtime/sections/index.js';
 export * from './runtime/application-runtime.js';
+export * from './runtime/factory-data/index.js';
+export * from './runtime/migrations/index.js';
 export { isConfiguratorModelSchemaCompatible } from './runtime/configurator-runtime/configurator-model-runtime.js';
 export * from './code/index.js';
 export { generateRuntimeInstance } from './runtime/generate-runtime-instance.js';

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

@@ -1 +1 @@
-export*from"./runtime/sections/index.js";export*from"./runtime/application-runtime.js";export{isConfiguratorModelSchemaCompatible}from"./runtime/configurator-runtime/configurator-model-runtime.js";export*from"./code/index.js";export{generateRuntimeInstance}from"./runtime/generate-runtime-instance.js";
+export*from"./runtime/sections/index.js";export*from"./runtime/application-runtime.js";export*from"./runtime/factory-data/index.js";export*from"./runtime/migrations/index.js";export{isConfiguratorModelSchemaCompatible}from"./runtime/configurator-runtime/configurator-model-runtime.js";export*from"./code/index.js";export{generateRuntimeInstance}from"./runtime/generate-runtime-instance.js";

package/dist/application-spec/generate-application/runtime/admin-runtime/admin-runtime.d.ts

@@ -1,8 +1,10 @@
 import { Branded } from '@salsita-ai/common/utils';
 import type { RuntimeReferenceStore } from '../../../caching/index.js';
 import type { ApplicationSpec } from '../../../parse-application-files/index.js';
+import { FactoryDataRuntime } from '../factory-data/index.js';
+import { type MigrationModules, MigrationRuntime } from '../migrations/index.js';
 import { ComponentOptics } from '../sections/component-optic.js';
-import { type ExpressionImplementations, ExpressionRuntime, type MissingExpression } from '../sections/expression-runtime.js';
+import { type ExpressionImplementations, ExpressionRuntime, type InvariantImplementations, type MissingExpression } from '../sections/expression-runtime.js';
 import { PresetRuntime } from '../sections/preset-runtime.js';
 import { AdminModelRuntime } from './admin-model-runtime.js';
 import { AdminStatesRuntime } from './states-runtime.js';
@@ -12,6 +14,8 @@ export type AdminRuntime = Branded<'AdminRuntime', {
     readonly expressionRuntime: ExpressionRuntime;
     readonly presetRuntime: PresetRuntime;
     readonly statesRuntime: AdminStatesRuntime;
+    readonly migrationRuntime: MigrationRuntime;
+    readonly factoryDataRuntime: FactoryDataRuntime;
 }>;
 export type AdminRuntimeResult = {
     readonly ok: true;
@@ -20,4 +24,4 @@ export type AdminRuntimeResult = {
     readonly ok: false;
     readonly missingExpressions: readonly MissingExpression[];
 };
-export declare const AdminRuntime: (spec: ApplicationSpec, referenceStore: RuntimeReferenceStore, implementations?: ExpressionImplementations) => AdminRuntimeResult;
+export declare const AdminRuntime: (spec: ApplicationSpec, referenceStore: RuntimeReferenceStore, implementations: ExpressionImplementations, invariantImplementations: InvariantImplementations, migrationModules: MigrationModules) => AdminRuntimeResult;

package/dist/application-spec/generate-application/runtime/admin-runtime/admin-runtime.js

@@ -1 +1 @@
-import{Branded as e}from"@salsita-ai/common/utils";import{Preset as t,PresetCategory as i,commonAdminCustomExpressions as r,commonAdminViolationExpressions as s}from"#package/domain";import{ComponentOptics as n}from"../sections/component-optic.js";import{ExpressionRuntime as m}from"../sections/expression-runtime.js";import{PresetRuntime as o}from"../sections/preset-runtime.js";import{AdminModelRuntime as a}from"./admin-model-runtime.js";import{AdminStatesRuntime as p}from"./states-runtime.js";let c={Preset:[{evaluate:(e,i,r)=>{let n=r.domain.get$Entity(e,i);return t.assert(n),s.Preset.nameNotEmpty(n)}}]},u={PresetCategory:{$isDraft:{origin:{name:"$isDraft",typeOrAlias:"PresetCategory"},evaluate:(e,t,s)=>{let n=s.domain.get$Entity(e,t);return i.assert(n),r.PresetCategory.$isDraft(n)},meta:{}}}};export const AdminRuntime=(t,i,r={})=>{let s={...u};for(let[e,t]of Object.entries(r))s[e]={...s[e],...t};let f=a(t.admin,t.configurator.dataSchemas,i),d=m(t.admin,i,s,"adminExpressionRuntime",c);return d.ok?{ok:!0,runtime:e({modelRuntime:f,componentOptics:n(i,{components:t.admin.components,referenceScope:"adminRuntime/componentOptics",modelRuntime:f}),expressionRuntime:d.runtime,presetRuntime:o(i,{referenceScope:"adminRuntime/presetRuntime",presets:t.admin.presets.presets}),statesRuntime:p(t,i)})}:{ok:!1,missingExpressions:d.missing}};
+import{Branded as e}from"@salsita-ai/common/utils";import{Preset as t,PresetCategory as i,commonAdminCustomExpressions as n,commonAdminViolationExpressions as r}from"#package/domain";import{FactoryDataRuntime as s}from"../factory-data/index.js";import{MigrationRuntime as o}from"../migrations/index.js";import{ComponentOptics as m}from"../sections/component-optic.js";import{ExpressionRuntime as a}from"../sections/expression-runtime.js";import{PresetRuntime as p}from"../sections/preset-runtime.js";import{AdminModelRuntime as f}from"./admin-model-runtime.js";import{AdminStatesRuntime as u}from"./states-runtime.js";let c={Preset:[{evaluate:(e,i,n)=>{let s=n.domain.get$Entity(e,i);return t.assert(s),r.Preset.nameNotEmpty(s)}}]},l={PresetCategory:{$isDraft:{origin:{name:"$isDraft",typeOrAlias:"PresetCategory"},evaluate:(e,t,r)=>{let s=r.domain.get$Entity(e,t);return i.assert(s),n.PresetCategory.$isDraft(s)},meta:{}}}},d=new WeakMap;export const AdminRuntime=(t,i,n,r,g)=>{let R={...l};for(let[e,t]of Object.entries(n))R[e]={...R[e],...t};let y=f(t.admin,t.configurator.dataSchemas,i),j=a(t.admin,i,R,"adminExpressionRuntime",((e,t)=>{if(0===Object.keys(e).length)return c;let i=d.get(t)??new WeakMap;d.set(t,i);let n=i.get(e);if(n)return n;let r={};for(let i of[c,e])for(let[e,n]of Object.entries(i))for(let i of t[e]??[e])r[i]=[...r[i]??[],...n];return i.set(e,r),r})(r,y.aliases));return j.ok?{ok:!0,runtime:e({modelRuntime:y,componentOptics:m(i,{components:t.admin.components,referenceScope:"adminRuntime/componentOptics",modelRuntime:y}),expressionRuntime:j.runtime,presetRuntime:p(i,{referenceScope:"adminRuntime/presetRuntime",presets:t.admin.presets.presets}),statesRuntime:u(t,i),migrationRuntime:o(i,{referenceScope:"adminRuntime/migrationRuntime",resolvedVersions:t.admin.resolvedVersions,latestEntities:y.entities,migrationModules:g}),factoryDataRuntime:s(i,{referenceScope:"adminRuntime/factoryDataRuntime",invariants:t.admin.invariants,defaults:t.admin.defaults,aliases:y.aliases,entities:y.entities})})}:{ok:!1,missingExpressions:j.missing}};

package/dist/application-spec/generate-application/runtime/application-runtime.d.ts

@@ -4,6 +4,7 @@ import type { RuntimeReferenceStore } from '../../caching/index.js';
 import type { ApplicationSpec } from '../../parse-application-files/index.js';
 import { AdminRuntime } from './admin-runtime/admin-runtime.js';
 import { ConfiguratorRuntime } from './configurator-runtime/configurator-runtime.js';
+import type { MigrationModules } from './migrations/index.js';
 import { DataRuntime } from './sections/data-runtime.js';
 import type { ExpressionImplementations, InvariantImplementations, MissingExpression } from './sections/expression-runtime.js';
 /**
@@ -28,6 +29,12 @@ export type ApplicationRuntimeResult = {
  * section-level changes across rebuilds.
  * Each field on the result carries its own `changed` flag.
  *
+ * `adminInvariantImplementations` are the project's admin invariants (`src/admin/invariants/`); the
+ * admin domain checks them after the invariants every admin domain has. `migrationModules` are the
+ * project's migration modules of both domains (`src/migrations/`, `src/admin/migrations/`), keyed by
+ * project path; a migration they do not provide is listed in `missingMigrations` of the domain's
+ * `migrationRuntime`.
+ *
  * Returns an error result when declared expressions are missing implementations.
  */
-export declare const ApplicationRuntime: (spec: ApplicationSpec, referenceStore: RuntimeReferenceStore, implementations: ExpressionImplementations, importedTransformers: readonly ImportedTransformer[], invariantImplementations?: InvariantImplementations, adminImplementations?: ExpressionImplementations) => ApplicationRuntimeResult;
+export declare const ApplicationRuntime: (spec: ApplicationSpec, referenceStore: RuntimeReferenceStore, implementations: ExpressionImplementations, importedTransformers: readonly ImportedTransformer[], invariantImplementations?: InvariantImplementations, adminImplementations?: ExpressionImplementations, adminInvariantImplementations?: InvariantImplementations, migrationModules?: MigrationModules) => ApplicationRuntimeResult;

package/dist/application-spec/generate-application/runtime/application-runtime.js

@@ -1 +1 @@
-import{Branded as i}from"@salsita-ai/common/utils";import{AdminRuntime as r}from"./admin-runtime/admin-runtime.js";import{ConfiguratorRuntime as n}from"./configurator-runtime/configurator-runtime.js";import{DataRuntime as o}from"./sections/data-runtime.js";export const ApplicationRuntime=(s,t,m,e,u,a)=>{let p=n(s,t,m,e,u);if(!p.ok)return{ok:!1,missingExpressions:p.missingExpressions};let f=r(s,t,a);return f.ok?{ok:!0,runtime:i({configurator:p.runtime,admin:f.runtime,data:o(s,t)})}:{ok:!1,missingExpressions:f.missingExpressions}};
+import{Branded as i}from"@salsita-ai/common/utils";import{AdminRuntime as r}from"./admin-runtime/admin-runtime.js";import{ConfiguratorRuntime as n}from"./configurator-runtime/configurator-runtime.js";import{DataRuntime as o}from"./sections/data-runtime.js";export const ApplicationRuntime=(s,t,m,e,u,a={},p={},f={})=>{let c=n(s,t,m,e,u,f);if(!c.ok)return{ok:!1,missingExpressions:c.missingExpressions};let g=r(s,t,a,p,f);return g.ok?{ok:!0,runtime:i({configurator:c.runtime,admin:g.runtime,data:o(s,t)})}:{ok:!1,missingExpressions:g.missingExpressions}};

package/dist/application-spec/generate-application/runtime/configurator-runtime/configurator-runtime.d.ts

@@ -2,6 +2,8 @@ import { Branded } from '@salsita-ai/common/utils';
 import type { ImportedTransformer } from '#package/domain';
 import type { RuntimeReferenceStore } from '../../../caching/index.js';
 import type { ApplicationSpec } from '../../../parse-application-files/index.js';
+import { FactoryDataRuntime } from '../factory-data/index.js';
+import { type MigrationModules, MigrationRuntime } from '../migrations/index.js';
 import { ActionsRuntime } from '../sections/actions-runtime.js';
 import { AssistantRuntime } from '../sections/assistant-runtime.js';
 import { ComponentOptics } from '../sections/component-optic.js';
@@ -21,6 +23,8 @@ export type ConfiguratorRuntime = Branded<'ConfiguratorRuntime', {
     readonly transformersRuntime: TransformersRuntime;
     readonly assistantRuntime: AssistantRuntime;
     readonly actionsRuntime: ActionsRuntime;
+    readonly migrationRuntime: MigrationRuntime;
+    readonly factoryDataRuntime: FactoryDataRuntime;
 }>;
 export type ConfiguratorRuntimeResult = {
     readonly ok: true;
@@ -29,4 +33,4 @@ export type ConfiguratorRuntimeResult = {
     readonly ok: false;
     readonly missingExpressions: readonly MissingExpression[];
 };
-export declare const ConfiguratorRuntime: (spec: ApplicationSpec, referenceStore: RuntimeReferenceStore, implementations: ExpressionImplementations, importedTransformers: readonly ImportedTransformer[], invariantImplementations?: InvariantImplementations) => ConfiguratorRuntimeResult;
+export declare const ConfiguratorRuntime: (spec: ApplicationSpec, referenceStore: RuntimeReferenceStore, implementations: ExpressionImplementations, importedTransformers: readonly ImportedTransformer[], invariantImplementations: InvariantImplementations | undefined, migrationModules: MigrationModules) => ConfiguratorRuntimeResult;

package/dist/application-spec/generate-application/runtime/configurator-runtime/configurator-runtime.js

@@ -1 +1 @@
-import{Branded as t}from"@salsita-ai/common/utils";import{ActionsRuntime as o}from"../sections/actions-runtime.js";import{AssistantRuntime as e}from"../sections/assistant-runtime.js";import{ComponentOptics as r}from"../sections/component-optic.js";import{ExpressionRuntime as s}from"../sections/expression-runtime.js";import{PresetRuntime as i}from"../sections/preset-runtime.js";import{ThemeRuntime as n}from"../sections/theme-runtime.js";import{TransformersRuntime as m}from"../sections/transformers-runtime.js";import{ConfiguratorModelRuntime as u}from"./configurator-model-runtime.js";import{ConfiguratorStatesRuntime as c}from"./states-runtime.js";export const ConfiguratorRuntime=(p,a,f,g,R)=>{let j=u(p.configurator,a),x=s(p.configurator,a,f,"configuratorExpressionRuntime",R);return x.ok?{ok:!0,runtime:t({modelRuntime:j,componentOptics:r(a,{components:p.configurator.components,referenceScope:"configuratorRuntime/componentOptics",modelRuntime:j}),presetRuntime:i(a,{referenceScope:"configuratorRuntime/presetRuntime",presets:p.configurator.presets.presets}),statesRuntime:c(p,a),expressionRuntime:x.runtime,themeRuntime:n(p,a),transformersRuntime:m(p,a,g),assistantRuntime:e(p,a),actionsRuntime:o(p.configurator.actions,a)})}:{ok:!1,missingExpressions:x.missing}};
+import{Branded as t}from"@salsita-ai/common/utils";import{FactoryDataRuntime as e}from"../factory-data/index.js";import{MigrationRuntime as i}from"../migrations/index.js";import{ActionsRuntime as o}from"../sections/actions-runtime.js";import{AssistantRuntime as r}from"../sections/assistant-runtime.js";import{ComponentOptics as n}from"../sections/component-optic.js";import{ExpressionRuntime as s}from"../sections/expression-runtime.js";import{PresetRuntime as m}from"../sections/preset-runtime.js";import{ThemeRuntime as a}from"../sections/theme-runtime.js";import{TransformersRuntime as u}from"../sections/transformers-runtime.js";import{ConfiguratorModelRuntime as c}from"./configurator-model-runtime.js";import{ConfiguratorStatesRuntime as f}from"./states-runtime.js";export const ConfiguratorRuntime=(p,g,R,j,l,d)=>{let x=c(p.configurator,g),v=s(p.configurator,g,R,"configuratorExpressionRuntime",l);return v.ok?{ok:!0,runtime:t({modelRuntime:x,componentOptics:n(g,{components:p.configurator.components,referenceScope:"configuratorRuntime/componentOptics",modelRuntime:x}),presetRuntime:m(g,{referenceScope:"configuratorRuntime/presetRuntime",presets:p.configurator.presets.presets}),statesRuntime:f(p,g),expressionRuntime:v.runtime,themeRuntime:a(p,g),transformersRuntime:u(p,g,j),assistantRuntime:r(p,g),actionsRuntime:o(p.configurator.actions,g),migrationRuntime:i(g,{referenceScope:"configuratorRuntime/migrationRuntime",resolvedVersions:p.configurator.resolvedVersions,latestEntities:x.entities,migrationModules:d}),factoryDataRuntime:e(g,{referenceScope:"configuratorRuntime/factoryDataRuntime",invariants:p.configurator.invariants,defaults:p.configurator.defaults,aliases:x.aliases,entities:x.entities})})}:{ok:!1,missingExpressions:v.missing}};

package/dist/application-spec/generate-application/runtime/factory-data/factory-data-runtime.d.ts

@@ -0,0 +1,43 @@
+import { Branded } from '@salsita-ai/common/utils';
+import type { AnyEntityReflections, DomainEntity, DomainEntityReflection } from '#package/domain';
+import type { RuntimeReferenceStore } from '../../../caching/index.js';
+import type { Defaults, Invariants } from '../../../parse-application-files/index.js';
+import { type RecipeDefaults } from './recipe-defaults.js';
+import { type StaticViolations } from './static-violations.js';
+interface FactoryDataRuntimeFields {
+    /**
+     * The member types of each alias: what `phx.domain.attachComponent` expands an alias with, and
+     * what `phx.domain.createRecipe` expands alias defaults with.
+     */
+    readonly aliases: Readonly<Record<string, readonly string[]>>;
+    /** The entity reflections `phx.domain.createRecipe` validates the defaults with. */
+    readonly entityReflections: ReadonlyArray<DomainEntityReflection<DomainEntity<string>>>;
+    /** The violations `phx.domain.implementCustomInvariants` reports for a static invariant that fails. */
+    readonly staticViolations: StaticViolations;
+    /** The defaults `phx.domain.createRecipe` puts into a new recipe. */
+    readonly defaults: RecipeDefaults;
+    readonly changed: boolean;
+}
+/**
+ * The data the `phx.domain` factories of one domain carry, built from the parsed spec: the static
+ * violations of `implementCustomInvariants`, the aliases of `attachComponent`, and the aliases,
+ * entity reflections and defaults of `createRecipe`. Generated `domain-spec.ts` passes the same
+ * values to those factories as literals; with this section the factories can be built from the
+ * spec instead. The configurator and the admin domain each have one.
+ */
+export type FactoryDataRuntime = Branded<'FactoryDataRuntime', FactoryDataRuntimeFields>;
+interface FactoryDataRuntimeInput {
+    readonly invariants: Invariants;
+    readonly defaults: Defaults;
+    readonly aliases: Readonly<Record<string, readonly string[]>>;
+    readonly entities: AnyEntityReflections;
+}
+interface FactoryDataRuntimeProps extends FactoryDataRuntimeInput {
+    readonly referenceScope: string;
+}
+/**
+ * Builds the factory data of one domain. The result keeps its reference while the invariants and
+ * defaults are equal and the model runtime's aliases and entity reflections are the same objects.
+ */
+export declare const FactoryDataRuntime: (referenceStore: RuntimeReferenceStore, props: FactoryDataRuntimeProps) => FactoryDataRuntime;
+export {};

package/dist/application-spec/generate-application/runtime/factory-data/factory-data-runtime.js

@@ -0,0 +1 @@
+import e from"lodash-es/isEqual.js";import{Branded as t}from"@salsita-ai/common/utils";import{createRecipeDefaults as i}from"./recipe-defaults.js";import{createStaticViolations as s}from"./static-violations.js";let a=e=>({aliases:e.aliases,entityReflections:Object.values(e.entities),staticViolations:s(e.invariants),defaults:i(e.defaults)});export const FactoryDataRuntime=(i,s)=>{let n=i.createBuilder(s.referenceScope,{build:a,getKey:()=>"singleton",compare:(t,i)=>t.aliases===i.aliases&&t.entities===i.entities&&e(t.invariants.entries,i.invariants.entries)&&e(t.defaults.entries,i.defaults.entries)}).build({invariants:s.invariants,defaults:s.defaults,aliases:s.aliases,entities:s.entities});return t({...n.output,changed:n.changed})};

package/dist/application-spec/generate-application/runtime/factory-data/index.d.ts

@@ -0,0 +1,3 @@
+export { FactoryDataRuntime } from './factory-data-runtime.js';
+export type { RecipeDefaults } from './recipe-defaults.js';
+export type { StaticViolations } from './static-violations.js';

package/dist/application-spec/generate-application/runtime/factory-data/index.js

@@ -0,0 +1 @@
+export{FactoryDataRuntime}from"./factory-data-runtime.js";

package/dist/application-spec/generate-application/runtime/factory-data/recipe-defaults.d.ts

@@ -0,0 +1,13 @@
+import type { Defaults } from '../../../parse-application-files/index.js';
+/**
+ * The default property values of each entity type, keyed by entity type: what
+ * `phx.domain.createRecipe` puts into a new recipe before the caller's overrides. Alias entries are
+ * already expanded to their member types by the parser.
+ */
+export type RecipeDefaults = Readonly<Record<string, Readonly<Record<string, unknown>>>>;
+/**
+ * The runtime counterpart of the `defaults` literal the generated `domain-spec.ts` passes to
+ * `createRecipeFactory`: the parsed per-entity defaults with every `$msg` lowered to the descriptor
+ * the `msg` macro produces.
+ */
+export declare const createRecipeDefaults: (defaults: Defaults) => RecipeDefaults;

package/dist/application-spec/generate-application/runtime/factory-data/recipe-defaults.js

@@ -0,0 +1 @@
+import{createMessageDescriptor as e,isEvalMarker as t,isMsgMarker as r}from"../../../core/index.js";let s=(a,i)=>{if(null===a||"object"!=typeof a)return a;if(r(a))return e(a);if(t(a))throw Error(`The default at ${i} is an $eval expression. Defaults are static values; the parser rejects $eval in them, so the spec given to the runtime was not produced by it. Parse the spec again and pass the result.`);return Array.isArray(a)?a.map((e,t)=>s(e,`${i}[${t}]`)):Object.fromEntries(Object.entries(a).map(([e,t])=>[e,s(t,`${i}.${e}`)]))};export const createRecipeDefaults=e=>Object.fromEntries(Object.entries(e.entries).map(([e,t])=>[e,Object.fromEntries(Object.entries(t).map(([t,r])=>[t,s(r,`${e}.${t}`)]))]));