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

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

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

package/dist/application-spec/generate-application/code/templates/global-definition/generate-action-types.js

@@ -1,8 +1,8 @@
-import{schemaToTypeString as e}from"../common/schema-to-type-string.js";let t=(e,t)=>{let n=(e??"").trim().replaceAll("*/","*\\/").split("\n").map(e=>e.trim());return""===n[0]||void 0===n[0]?[]:1===n.length?[`${t}/** ${n[0]} */`]:[`${t}/**`,...n.map(e=>`${t} * ${e}`.trimEnd()),`${t} */`]};export const generateActionTypeDecls=(n,r,o,a,p,s=!1)=>{let i=" ".repeat(p),$=" ".repeat(p+2),c=" ".repeat(p+4),l=" ".repeat(p+6),m={phxDefinitions:o,commonTypeNames:new Set(r.commonTypes.keys()),imports:a,typeOnlyImports:s},y=[...n.values()].map(n=>{let r=Object.entries(n.params).flatMap(([n,{schema:r,required:o}])=>[...t(r.description,l),`${l}readonly ${n}${o?"":"?"}: ${e(r,m)}`]),o=Object.entries(n.result).flatMap(([n,r])=>[...t(r.description,l),`${l}readonly ${n}: ${e(r,m)}`]),a=e=>e.length>0?`{
+import{docComment as e}from"../common/doc-comment.js";import{schemaToTypeString as t}from"../common/schema-to-type-string.js";export const generateActionTypeDecls=(n,o,r,a,s,p=!1)=>{let c=" ".repeat(s),i=" ".repeat(s+2),m=" ".repeat(s+4),$=" ".repeat(s+6),y={phxDefinitions:r,commonTypeNames:new Set(o.commonTypes.keys()),imports:a,typeOnlyImports:p},l=[...n.values()].map(n=>{let o=Object.entries(n.params).flatMap(([n,{schema:o,required:r}])=>[...e(o.description,$),`${$}readonly ${n}${r?"":"?"}: ${t(o,y)}`]),r=Object.entries(n.result).flatMap(([n,o])=>[...e(o.description,$),`${$}readonly ${n}: ${t(o,y)}`]),a=e=>e.length>0?`{
 ${e.join("\n")}
-${c}}`:"Record<string, never>";return[...t(n.description,$),`${$}readonly ${n.name}: {`,`${c}readonly params: ${a(r)}`,`${c}readonly result: ${a(o)}`,`${$}}`].join("\n")}),A=y.length>0?`{
-${y.join("\n")}
-${i}}`:"Record<never, never>";return`${i}type ActionTypes = ${A}
-${i}type ActionName = keyof ActionTypes
-${i}type ActionParams<NAME extends ActionName> = ActionTypes[NAME]['params']
-${i}type ActionResult<NAME extends ActionName> = ActionTypes[NAME]['result']`};
+${m}}`:"Record<string, never>";return[...e(n.description,i),`${i}readonly ${n.name}: {`,`${m}readonly params: ${a(o)}`,`${m}readonly result: ${a(r)}`,`${i}}`].join("\n")}),A=l.length>0?`{
+${l.join("\n")}
+${c}}`:"Record<never, never>";return`${c}type ActionTypes = ${A}
+${c}type ActionName = keyof ActionTypes
+${c}type ActionParams<NAME extends ActionName> = ActionTypes[NAME]['params']
+${c}type ActionResult<NAME extends ActionName> = ActionTypes[NAME]['result']`};

package/dist/application-spec/generate-application/code/templates/global-definition/generate-assistant-form-element-types.d.ts

@@ -0,0 +1,12 @@
+import type { AssistantFormElementDescriptor } from '#package/domain';
+import type { PhoenixDefinitions } from '../../../../core/phoenix-definitions.js';
+import type { CodeImports } from '../../common/code-imports.js';
+/**
+ * Generates the `AssistantFormElementTypes` map of the project's own assistant form elements (name →
+ * `{ role, attributes }`), and the `AssistantFormElementName` and `AssistantFormElementProps<NAME>`
+ * types derived from it, which `phx.frontend.createAssistantFormElement` is typed by. An attribute
+ * outside `required` is optional and an enum is a union of its values. The `description` of an element becomes the doc
+ * comment of its property. Without elements the map is empty, so `AssistantFormElementName` is
+ * `never`.
+ */
+export declare const generateAssistantFormElementTypeDecls: (formElements: readonly AssistantFormElementDescriptor[], phxDefinitions: PhoenixDefinitions, imports: CodeImports, indent: number) => string;

package/dist/application-spec/generate-application/code/templates/global-definition/generate-assistant-form-element-types.js

@@ -0,0 +1,7 @@
+import{docComment as e}from"../common/doc-comment.js";import{formatPropertyKey as t}from"../common/format-property-key.js";import{schemaToTypeString as n}from"../common/schema-to-type-string.js";export const generateAssistantFormElementTypeDecls=(o,r,s,m)=>{let a=" ".repeat(m),p=" ".repeat(m+2),l=" ".repeat(m+4),i=" ".repeat(m+6),$={phxDefinitions:r,commonTypeNames:new Set,imports:s},y=o.map(({name:o,role:r,description:s,attributes:m,required:a=[]})=>{let y=Object.entries(m).map(([e,o])=>`${i}readonly ${t(e)}${a.includes(e)?"":"?"}: ${n({...o},$)}`);return[...e(s,p),`${p}readonly ${t(o)}: {`,`${l}readonly role: '${r}'`,`${l}readonly attributes: ${y.length>0?`{
+${y.join("\n")}
+${l}}`:"Record<never, never>"}`,`${p}}`].join("\n")});s.addTypeImport("@salsita-ai/sdk/configurator","AssistantFormElementRoleProps");let c=y.length>0?`{
+${y.join("\n")}
+${a}}`:"Record<never, never>";return`${a}type AssistantFormElementTypes = ${c}
+${a}type AssistantFormElementName = keyof AssistantFormElementTypes
+${a}type AssistantFormElementProps<NAME extends AssistantFormElementName, STATE = unknown> = AssistantFormElementRoleProps<AssistantFormElementTypes[NAME], STATE>`};

package/dist/application-spec/generate-application/code/templates/global-definition/generate-phx-types.d.ts

@@ -0,0 +1,43 @@
+import type { ApplicationSpec } from '../../../../parse-application-files/index.js';
+import type { CodeImports } from '../../common/index.js';
+/**
+ * The types of the `phx` members, stated from SDK types and the project's generated types alone.
+ *
+ * Each member that the generated code builds with an SDK factory is declared as that factory's
+ * result for the type arguments the generated call states (`ReturnType<typeof factory<…>>`), so the
+ * declared type is the very type of the generated value; each member that is an SDK function as is
+ * is declared as that function's type; the model reflections are declared member by member.
+ *
+ * The factory results are named by type aliases local to the declaring file, and the members refer
+ * to those names. An editor cannot name a local alias where `phx` is used, so it shows the type
+ * itself, as it did when the members referred to the generated values; a member written as
+ * `ReturnType<typeof factory<…>>` in place would be shown as written, and printing it overflows the
+ * stack of the TypeScript 6 type printer.
+ */
+export interface PhxTypes {
+    /** Declarations the member types refer to, to emit once beside them, outside `declare global`. */
+    readonly declarations: string;
+    /** `phx.domain`, its admin part included. */
+    readonly domainType: string;
+    /** `phx.frontend` without its admin part. */
+    readonly configuratorInterfaceType: string;
+    /** The generated application types the member types refer to. */
+    readonly applicationTypeNames: readonly string[];
+}
+/** The types of a generated project's global `phx`, which also has `phx.frontend.admin` and `phx.webhooks`. */
+export interface GlobalPhxTypes extends PhxTypes {
+    /** `phx.frontend.admin`. */
+    readonly adminInterfaceType: string;
+    /** `phx.webhooks`. */
+    readonly webhooksType: string;
+}
+/**
+ * Generates the types of the `phx` members a story's module binding has (`domain` and
+ * `frontend`) and registers the SDK imports they need.
+ */
+export declare const generatePhxTypes: (spec: ApplicationSpec, imports: CodeImports) => PhxTypes;
+/**
+ * Generates the types of the members of a generated project's global `phx`, `phx.frontend.admin` and
+ * `phx.webhooks` included, and registers the SDK imports they need.
+ */
+export declare const generateGlobalPhxTypes: (spec: ApplicationSpec, imports: CodeImports) => GlobalPhxTypes;

package/dist/application-spec/generate-application/code/templates/global-definition/generate-phx-types.js

@@ -0,0 +1,33 @@
+import{generateInvariantBlueprintMembers as e,getDomainFactoryTypes as t}from"../domain-spec/index.js";let a="@salsita-ai/sdk/configurator",n="CustomInvariantBlueprints",o="AdminCustomInvariantBlueprints",i=["authHandlerBuilder","webhookBuilder","taskFactory","finalizeHandlerBuilder","callbackBuilder","prefetchBuilder","dynamicResourcesFactory"],r=(e,t)=>e.replaceAll("\n",`
+${t}`),s=e=>{let t=(e.infra.resources??[]).map(e=>JSON.stringify(e.name));return["AnyDomainEntity","RootEntity","$Map","NavigationState","ViewState","ToolState","ExportState","PublishedData","SessionData","FrontendData","Admin.AnyDomainEntity","Admin.RootEntity","Admin.$Map","AdminNavigationState","never","FinalizeData","PrefetchedFinalizeData","FinalizeResult","CallbackData",t.length>0?[...new Set(t)].join(" | "):"never"].join(", ")},l=()=>{let e=new Map;return{member:(t,a)=>(e.set(t,a),t),declarations:()=>[...e].map(([e,t])=>`type ${e} = ${t}`).join("\n")}},d=(i,l,d)=>{for(let e of["$DomainEntityReflection","DomainComponentOpticBuilder","DomainContextSystems","DomainEntityReflection","EnhancedAliasReflection","EnumLike","RawAliasReflection","RuntimeExpressionContext","SchemaReflection","createActionFactory","createAssistantSetupHandlerFactory","createCustomExpressionFactory","createCustomInvariantFactory","createDataRowValidatorHandler","createMapPublishedChunkedDataHandlerFactory","createMapPublishedRevisionDataHandlerFactory","createRecipeFactory","createSheetValidatorHandler"])l.addTypeImport("@salsita-ai/sdk/domain",e);l.addTypeImport(a,"createConfiguratorInterface"),l.addTypeImport(a,"CreateAssistantFormElement");let p=t(i.configurator,""),m=t(i.admin,"Admin"),y=s(i),c=(e,t)=>t?`interface ${e} {
+${t}
+}`:`interface ${e} {}`,{member:u}=d,$=`{
+  readonly model: ${r(p.modelType,"  ")}
+  readonly enhancedModel: ${r(p.enhancedModelType,"  ")}
+  readonly implementCustomExpressions: ${u("PhxImplementCustomExpressions",`ReturnType<typeof createCustomExpressionFactory<${p.typeArguments}, ${p.contextExtension}>>`)}
+  readonly implementCustomInvariants: ${u("PhxImplementCustomInvariants",`ReturnType<ReturnType<typeof createCustomInvariantFactory<${p.typeArguments}, ${n}, ${p.contextExtension}>>>`)}
+  readonly implementActions: ${u("PhxImplementActions",`ReturnType<typeof createActionFactory<AnyDomainEntity, RootEntity, PublishedData, SessionData, FrontendData, ActionTypes, ${p.contextExtension}, ${p.systems}>>`)}
+  readonly createAssistantSetupHandler: ${u("PhxCreateAssistantSetupHandler","ReturnType<typeof createAssistantSetupHandlerFactory<SessionData, AnyDomainEntity, $Map, ActionTypes>>")}
+  readonly attachComponent: ${u("PhxAttachComponent",`ReturnType<typeof DomainComponentOpticBuilder.from<${p.typeArguments}, ${p.contextExtension}>>`)}
+  readonly createRecipe: ${u("PhxCreateRecipe","ReturnType<typeof createRecipeFactory<AnyDomainEntity>>")}
+  readonly admin: {
+    readonly model: ${r(m.modelType,"    ")}
+    readonly enhancedModel: ${r(m.enhancedModelType,"    ")}
+    readonly implementCustomExpressions: ${u("PhxAdminImplementCustomExpressions",`ReturnType<typeof createCustomExpressionFactory<${m.typeArguments}, ${m.contextExtension}>>`)}
+    readonly implementCustomInvariants: ${u("PhxAdminImplementCustomInvariants",`ReturnType<ReturnType<typeof createCustomInvariantFactory<${m.typeArguments}, ${o}, ${m.contextExtension}>>>`)}
+    readonly attachComponent: ${u("PhxAdminAttachComponent",`ReturnType<typeof DomainComponentOpticBuilder.from<${m.typeArguments}, ${m.contextExtension}>>`)}
+    readonly createMapPublishedRevisionDataHandler: ${u("PhxAdminCreateMapPublishedRevisionDataHandler","ReturnType<typeof createMapPublishedRevisionDataHandlerFactory<Admin.AnyDomainEntity, Admin.RootEntity, Admin.$Map, PublishedData>>")}
+    readonly createMapPublishedChunkedDataHandler: ${u("PhxAdminCreateMapPublishedChunkedDataHandler","ReturnType<typeof createMapPublishedChunkedDataHandlerFactory<Admin.AnyDomainEntity, Admin.RootEntity, Admin.$Map>>")}
+    readonly createDataRowValidatorHandler: typeof createDataRowValidatorHandler
+    readonly createSheetValidatorHandler: typeof createSheetValidatorHandler
+    readonly createRecipe: ${u("PhxAdminCreateRecipe","ReturnType<typeof createRecipeFactory<Admin.AnyDomainEntity>>")}
+  }
+}`,A=u("PhxFrontend",`ReturnType<typeof createConfiguratorInterface<${y}>> & {
+  readonly createAssistantFormElement: CreateAssistantFormElement<AssistantFormElementTypes>
+}`),{latestModel:h}=i.configurator;return{declarations:[c(n,e(i.configurator.invariants,"  ")),c(o,e(i.admin.invariants,"  "))].join("\n\n"),domainType:$,configuratorInterfaceType:A,applicationTypeNames:[...h.entityTypes.map(String),...[...h.aliases].map(([e])=>String(e)),...[...h.commonTypes].map(([e])=>String(e)),...h.entityTypes.map(e=>`$${String(e)}`),...[...h.aliases].map(([e])=>`$${String(e)}`),"Aliases","$Map","ActionTypes","AssistantFormElementTypes","Admin","PublishedData","SessionData","FrontendData","BackendData","FinalizeData","PrefetchedFinalizeData","FinalizeResult","CallbackData","NavigationState","ViewState","ToolState","ExportState","AdminNavigationState"]}};export const generatePhxTypes=(e,t)=>{let a=l(),n=d(e,t,a);return{...n,declarations:`${n.declarations}
+
+${a.declarations()}`}};export const generateGlobalPhxTypes=(e,t)=>{let a=l(),{member:n}=a,o=d(e,t,a);t.addTypeImport("@salsita-ai/sdk/admin","createAdminInterface"),t.addTypeImport("@salsita-ai/sdk/webhook","createDomainWebhook");let r=s(e),p=n("PhxFrontendAdmin",`ReturnType<typeof createAdminInterface<${r}>>`),m=n("PhxWebhookBuilders",`ReturnType<typeof createDomainWebhook<${r}>>`),y=i.map(e=>`  readonly ${e}: ${n(`PhxWebhooks${e.charAt(0).toUpperCase()}${e.slice(1)}`,`${m}['${e}']`)}`);return{...o,declarations:`${o.declarations}
+
+${a.declarations()}`,adminInterfaceType:p,webhooksType:`{
+${y.join("\n")}
+}`}};

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

@@ -1,4 +1,6 @@
 export { generateActionTypeDecls } from './generate-action-types.js';
+export { generateAssistantFormElementTypeDecls } from './generate-assistant-form-element-types.js';
 export { generateModelTypeDecls } from './generate-model-types.js';
 export { generateExpressionTypeDecls, generateEntityExpressionComposites } from './generate-expression-types.js';
 export { generateDataSchemaTypeDecls } from './generate-data-schema-types.js';
+export { generateGlobalPhxTypes, generatePhxTypes, type GlobalPhxTypes, type PhxTypes } from './generate-phx-types.js';

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

@@ -1 +1 @@
-export{generateActionTypeDecls}from"./generate-action-types.js";export{generateModelTypeDecls}from"./generate-model-types.js";export{generateExpressionTypeDecls,generateEntityExpressionComposites}from"./generate-expression-types.js";export{generateDataSchemaTypeDecls}from"./generate-data-schema-types.js";
+export{generateActionTypeDecls}from"./generate-action-types.js";export{generateAssistantFormElementTypeDecls}from"./generate-assistant-form-element-types.js";export{generateModelTypeDecls}from"./generate-model-types.js";export{generateExpressionTypeDecls,generateEntityExpressionComposites}from"./generate-expression-types.js";export{generateDataSchemaTypeDecls}from"./generate-data-schema-types.js";export{generateGlobalPhxTypes,generatePhxTypes}from"./generate-phx-types.js";

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

@@ -1,17 +1,17 @@
-import{autoHeader as e}from"../common/file-headers.js";import{generateApplicationSpecTypeDeclarations as a}from"./application-types.js";export const generateApplicationSpecGlobals=(o,n)=>{let t,i,l,r,d,s,p,m,y,{declarations:c,imports:f}=a(o,n,2);f.addTypeImport("@salsita-ai/sdk/domain","EnumLike");let u=[c,(t=o.configurator.latestModel,i=o.admin.latestModel,l=t.entityTypes.map(String),r=[...t.aliases].map(([e])=>String(e)),d=[...t.commonTypes].map(([e])=>String(e)),s=i.entityTypes.map(String),p=[...i.aliases].map(([e])=>String(e)),m=[...i.commonTypes].map(([e])=>String(e)),y=(e,a)=>e.map(e=>`    ${a(e)}`).join("\n"),`  interface Model {
-${y([...l,...d,...r],e=>`readonly ${e}: ${e}`)}
+import{autoHeader as e}from"../common/file-headers.js";import{generateApplicationSpecTypeDeclarations as a}from"./application-types.js";import{generateGlobalPhxTypes as n}from"./global-definition/index.js";export const generateApplicationSpecGlobals=(t,o)=>{let i,l,d,r,s,p,c,y,m,{declarations:h,imports:f}=a(t,o,2);f.addTypeImport("@salsita-ai/sdk/domain","EnumLike");let g=n(t,f),S=[h,(i=t.configurator.latestModel,l=t.admin.latestModel,d=i.entityTypes.map(String),r=[...i.aliases].map(([e])=>String(e)),s=[...i.commonTypes].map(([e])=>String(e)),p=l.entityTypes.map(String),c=[...l.aliases].map(([e])=>String(e)),y=[...l.commonTypes].map(([e])=>String(e)),m=(e,a)=>e.map(e=>`    ${a(e)}`).join("\n"),`  interface Model {
+${m([...d,...s,...r],e=>`readonly ${e}: ${e}`)}
   }
 
   interface EnhancedModel {
-${y([...l,...r],e=>`readonly $${e}: $${e}`)}
+${m([...d,...r],e=>`readonly $${e}: $${e}`)}
   }
 
   interface AdminModel {
-${y([...s,...m,...p],e=>`readonly ${e}: Admin.${e}`)}
+${m([...p,...y,...c],e=>`readonly ${e}: Admin.${e}`)}
   }
 
   interface AdminEnhancedModel {
-${y([...s,...p],e=>`readonly $${e}: Admin.$${e}`)}
+${m([...p,...c],e=>`readonly $${e}: Admin.$${e}`)}
   }
 
   interface ApplicationTypes {
@@ -36,22 +36,33 @@ ${y([...s,...p],e=>`readonly $${e}: Admin.$${e}`)}
     readonly AdminModel: AdminModel
     readonly AdminEnhancedModel: AdminEnhancedModel
     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.")}
+  }`)].filter(Boolean).join("\n\n"),D=(e,a)=>e.replaceAll("\n",`
+${a}`);return`${e("globals.d.ts","Global type declarations for the phx namespace, env configs and domain types.")}
 /* eslint-disable @typescript-eslint/triple-slash-reference, @typescript-eslint/consistent-type-imports */
 /// <reference types="@salsita-ai/sdk/globals" />
+// The project's tsconfig includes \`.phoenix\`, but TypeScript checks a file under a dot folder only
+// when it is named or imported. These declarations import none of the generated modules, and the
+// project's own code need not either, so the modules are named here to keep them type-checked.
+/// <reference path="./spec-code.ts" />
+/// <reference path="./domain-spec.ts" />
+/// <reference path="./configurator-globals.ts" />
+/// <reference path="./admin-globals.ts" />
+/// <reference path="./webhook-builders.ts" />
 
 ${f.toTypeOnlyString(".phoenix/globals.d.ts")}
 
+${g.declarations}
+
 declare global {
-${u}
+${S}
 
   interface PhxGlobal {
     readonly frontendEnv: import('./frontend.config.js').RuntimeConfig
     readonly webhooksEnv: import('./webhooks.config.js').RuntimeConfig
 
     readonly applicationTypes: {
-      readonly ApplicationVersion: typeof import('./domain-spec.js').ApplicationVersion
-      readonly PublishedDataHash: typeof import('./domain-spec.js').PublishedDataHash
+      readonly ApplicationVersion: ${JSON.stringify(t.appMetadata.applicationVersion)}
+      readonly PublishedDataHash: ${JSON.stringify(t.configurator.dataSchemas.publishedDataHash)}
       readonly PublishedData: PublishedData
       readonly SessionData: SessionData
       readonly FrontendData: FrontendData
@@ -67,43 +78,13 @@ ${u}
       readonly AdminNavigationState: EnumLike<AdminNavigationState>
     }
 
-    readonly domain: {
-      readonly model: typeof import('./domain-spec.js').model
-      readonly enhancedModel: typeof import('./domain-spec.js').enhancedModel
-      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
-
-      readonly admin: {
-        readonly model: typeof import('./domain-spec.js').adminModel
-        readonly enhancedModel: typeof import('./domain-spec.js').adminEnhancedModel
-        readonly implementCustomExpressions: typeof import('./domain-spec.js').implementAdminCustomExpressions
-        readonly implementCustomInvariants: typeof import('./domain-spec.js').implementCustomAdminInvariants
-        readonly attachComponent: typeof import('./domain-spec.js').attachAdminComponent
-        readonly createMapPublishedRevisionDataHandler: typeof import('./domain-spec.js').createMapPublishedRevisionDataHandler
-        readonly createMapPublishedChunkedDataHandler: typeof import('./domain-spec.js').createMapPublishedChunkedDataHandler
-        readonly createDataRowValidatorHandler: typeof import('./domain-spec.js').createDataRowValidatorHandler
-        readonly createSheetValidatorHandler: typeof import('./domain-spec.js').createSheetValidatorHandler
-        readonly createRecipe: typeof import('./domain-spec.js').createAdminRecipe
-      }
-    }
+    readonly domain: ${D(g.domainType,"    ")}
 
-    readonly frontend: typeof import('./configurator-globals.js').configuratorInterface & {
-      readonly admin: typeof import('./admin-globals.js').adminInterface
+    readonly frontend: ${g.configuratorInterfaceType} & {
+      readonly admin: ${g.adminInterfaceType}
     }
 
-    readonly webhooks: {
-      readonly authHandlerBuilder: typeof import('./webhook-builders.js').authHandlerBuilder
-      readonly webhookBuilder: typeof import('./webhook-builders.js').webhookBuilder
-      readonly taskFactory: typeof import('./webhook-builders.js').taskFactory
-      readonly finalizeHandlerBuilder: typeof import('./webhook-builders.js').finalizeHandlerBuilder
-      readonly callbackBuilder: typeof import('./webhook-builders.js').callbackBuilder
-      readonly prefetchBuilder: typeof import('./webhook-builders.js').prefetchBuilder
-      readonly dynamicResourcesFactory: typeof import('./webhook-builders.js').dynamicResourcesFactory
-    }
+    readonly webhooks: ${D(g.webhooksType,"    ")}
   }
 }
 `};

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

@@ -37,18 +37,14 @@ 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 { type PhoenixSkillOptions, followsCanaryBuilds, generatePhoenixSkill } from './skills/phoenix-skill.js';
-export { generatePhoenixVariantsSkill } from './skills/phoenix-variants-skill.js';
+export { generatePhoenixSkillBundle } from './skills/phoenix-skill-bundle.js';
+export { type PhoenixSkillOptions, followsCanaryBuilds } from './skills/processes/index.js';
 export { generateApplicationSpecPrettierConfig } from './prettier-config.js';
 export { generateApplicationSpecRobotsTxt } from './robots-txt.js';
 export { generateApplicationSpecRootTsconfig } from './root-tsconfig.js';
 export { generateApplicationSpecStoryDevDeclaration, generateApplicationSpecStoryPhxModule, generateApplicationSpecStoryRawProjectFiles, generateApplicationSpecStoryWrapper, } from './story/index.js';
+export { generateApplicationSpecCodeFile } from './spec-code/index.js';
+export { generateApplicationSpecMessagesFile } from './spec-messages/index.js';
 export { generateApplicationSpecTsconfig } from './tsconfig.js';
 export { generateApplicationSpecWebhookBuilders } from './webhook-builders.js';
 export { generateApplicationSpecWebhookIndex } from './webhook-index.js';

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

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

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

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

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

@@ -6,14 +6,15 @@ ${(s=Object.entries(a).map(([e,a])=>{let o=Array.isArray(a)?`[${a.map(e=>`"${e}"
   },
   "catalogs": [
     {
-      "path": "<rootDir>/src/locales/{locale}/messages",
+      "path": "./src/locales/{locale}/messages",
       "include": [
         "./src",
         "./.phoenix"
       ],
       "exclude": [
         "**/node_modules/**",
-        "**/dist/**"
+        "**/dist/**",
+        "**/.phoenix/workspace/**"
       ]
     }
   ],

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

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

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

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

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

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

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

@@ -0,0 +1 @@
+import{createPhoenixTopicGuide as e}from"../guide.js";export const generatePhoenixCliCore=()=>e({path:"core/cli.md",title:"CLI",summary:"tooling, identity, project structure and ownership, local development and deployment",sections:["## Tooling and dependencies\n\nCommands use pnpm notation; use the project's package manager identified by its lockfile or `packageManager` in `package.json`, and ask when neither identifies it. Keep the SDK on its intended release channel: stable, PR beta and workspace-linked projects must not be moved to canary.\n\n`phoenix deps` aligns missing or out-of-range peer dependencies in `package.json` but installs nothing. Install with the project's package manager, then `phoenix sync` regenerates project files and guidance. Refresh changed guidance after sync. An install with pnpm 11 that skips build scripts leaves placeholder entries under `allowBuilds` in `pnpm-workspace.yaml`; decide them, `true` for `@swc/core` and `esbuild` and `false` for `es5-ext`, because the platform build stops on a placeholder and `phoenix deploy` refuses one. [CLI and setup documentation](../features/index.md#cli-access-and-deployment) owns flags and installation details.\n\n## Identity and authentication\n\nA workspace contains projects, and a project has target environments and deployments. Confirm ambiguous identity before mutations or deploys. `phoenix login <workspace>` authorizes the CLI; local dev and deploy use that identity. Consult [project and authentication documentation](../features/index.md#cli-access-and-deployment) for local versus remote setup.\n\n## Project structure\n\n- `spec/` — domain, relations, expressions, invariants, components and application YAML.\n- `src/expressions/`, `actions/`, `invariants/`, `transformers/` — typed implementations of domain behavior and consistency rules.\n- `src/components/`, `elements/`, `handlers/` — runtime components, custom UI and layout elements, event and lifecycle handlers. See [Custom project layout](../features/custom-layout/index.md) and [Domain controls](../features/domain-controls/index.md).\n- `src/webhooks/` — server handlers. A project entry is the default export of `index.ts`; without it the SDK supplies anonymous auth only. Enabling custom or Clerk auth without the entry reports `AUTH_WITHOUT_PROJECT_WEBHOOK`; add the required auth handlers or disable unintended auth settings.\n- `src/migrations/` — versioned model migrations; `src/admin/` mirrors the main source structure for Admin.\n- `src/locales/` — authored PO catalogs and generated TS catalogs.\n- `src/_shared/`, `src/_utils/` and other `_`-prefixed folders — helpers and supporting modules. Phoenix skips these folders during auto-import; import their modules explicitly.\n- `public/` — static models, textures, images and fonts; `assets/` — uploadable resources such as templates and email assets.\n- `docs/` — rendered specification PDFs for the client.\n- `tools/` — reproducible project scripts, such as model conversion or rendering the specification PDFs. One-off scripts, screenshots and downloads stay in the agent's scratch space outside the project.\n- `.phoenix/` — generated files, with the project-owned exceptions below. The root `tsconfig.json` belongs to the project and extends `.phoenix/tsconfig.json`.\n\nDo not edit generated output or compiled locale TS. `.phoenix/workspace/` holds the specification sources and project records; application-spec sync, build and clean preserve it, and the generated Git ignore rules leave it available for version control. Deploy includes `.phoenix/workspace/` and `docs/` in the private deployment sources, outside application inputs and public assets. `.phoenix/variants/` option files survive rebuilds. Legacy tooling has a separate lifecycle.\n\nSync rewrites and prunes Phoenix's `phoenix` and `phoenix-*` skill folders under `.claude/skills/` and `.agents/skills/`; keep custom skills under another name. Root `AGENTS.md` and client source documents are client-owned. Components use PascalCase TSX, utilities kebab-case TS, expressions entity-name TS, migrations sequential `v*.ts` and specs kebab-case YAML. `docs/phoenix/project-structure.mdx` has the full reference; the [capability index](../features/index.md#project-and-customization) lists it.\n\n### Source conventions\n\n- Auto-imported expressions, actions, invariants, transformers, components, handlers, elements and webhooks must default-export their folder's phx factory result, as one item or an array. Named exports are ignored.\n- `phx` is a global in every project: use it without importing it.\n- Keep plain helpers in underscore folders and import them explicitly.\n- Use relative imports: dev, build and webhook bundling do not resolve tsconfig `paths` aliases.\n\n## Local development\n\n`phoenix dev` runs the live preview, `sync` regenerates without bundling, `build` produces the production build, and `check` checks project quality.\n\n### Keep the preview in front of the client\n\nThe client should see the configurator change while it is built. Before the first change in a conversation, make sure `pnpm phoenix dev` is running, starting it in the background when it is not, and wait for the `Preview: <url>` line it prints and writes to `.phoenix/phoenix-dev.log`. The log keeps the lines of earlier runs, so use the last one written after the start.\n\nOpen the address where the client can see it: in the agent application's built-in browser when it has one the client sees, otherwise in the client's browser with `open '<url>'` on macOS, `xdg-open '<url>'` on Linux or `Start-Process '<url>'` in PowerShell. Keep the quotes; the shell would otherwise read a `?` in the address as a pattern. Then tell the client in one line where the preview is and that it updates by itself as the work goes on. Variant comparisons open in the same preview, so say there what to compare and how to choose.\n\nOpen it once: the preview reloads on every change. A domain model change is the exception. Dev registers the model with the server only when it starts and logs an error asking for a restart; restart it, wait for the new `Preview:` line and open that address in place of the old tab, whose `?cid=` names a configuration of the earlier model.\n\n### Logs and inspection\n\nLogs in `.phoenix/phoenix-dev.log` contain spec, build and runtime errors and watcher events; check them after changes. [Inspection tools](../features/inspection.md) cover assets, state, data, scene and screenshots. Runtime inspection needs dev running and the preview open in a browser; a screenshot of the canvas does not verify the surrounding interface.\n\n## Deployment\n\n`pnpm phoenix deploy` sends the project sources for a server build and waits for the target environment to go live. Run it so its output can be read while it runs: right after `Build <id> started` it prints `Follow the build in Studio: <url>`. Open that link where the client sees it, as with the preview, so they can follow the build. When the line is missing, the sign-in predates the link: the build is listed under Deployments in Studio, and `pnpm phoenix login <workspace>` brings the link back.\n\nA successful local preview does not establish deployed model compatibility. The deploy is refused before the upload when the domain model changed under a version that is already deployed, such as a starter deployed before the first draft; [Model migration](../processes/model-migration.md) handles that. When the build fails, tell the client the cause and the next step. Record each deploy and its outcome in the project record. [Deployment documentation](../features/index.md#cli-access-and-deployment) covers status and environment details.\n\n## Internal beta\n\nPhoenix is in an internal beta. Read [Beta](../processes/beta.md) before each deploy and when a deploy goes live; a project on the `canary` SDK build also reads it once per conversation before changing anything.\n\n## Interactive and support tools\n\n[Variants](../features/variants.md) compares frontend alternatives over the live preview and applies the choice. [Feedback](../processes/feedback/index.md) submits an approved issue or evaluation. The [workflow](workflow.md) owns when either is useful and how much client interaction fits the task."]});

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

@@ -0,0 +1,3 @@
+export * from './workflow.js';
+export * from './sdk.js';
+export * from './cli.js';

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

@@ -0,0 +1 @@
+export*from"./workflow.js";export*from"./sdk.js";export*from"./cli.js";

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

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

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

@@ -0,0 +1,118 @@
+import{createPhoenixTopicGuide as e}from"../guide.js";let t=`## Project and customization
+
+Phoenix turns YAML in \`spec/\` into a typed domain, configured components and a running configurator.
+
+- Define domain and component behavior in YAML first.
+- Compose the UI through a custom project layout, using Phoenix elements, slots and hooks.
+- For other custom implementations, verify an SDK capability gap and explain the proposed approach. Missing documentation does not establish a missing capability.
+
+### The \`phx\` global
+
+Project code reaches the SDK through the \`phx\` global: \`phx.domain\` for model reflections and the implementations of expressions, invariants and actions, \`phx.frontend\` for elements, handlers, hooks, updates and transformers, and \`phx.webhooks\` for server builders and tasks. Each [feature guide](../features/index.md) teaches its part as \`phx.<namespace>.<member>\`; a few things \`phx\` does not carry, such as \`memoEval\`, are SDK subpath imports.
+
+### Entity-component-system model
+
+- **Entities** store product state, such as a cabinet and its width.
+- **Components** attach configurable data or behavior definitions, such as a scene object or width control, to entities or aliases.
+- **Systems** consume those components to apply domain or UI behavior, such as rendering the scene.
+
+Stable references drive change detection. Use memoEval to reuse result objects and arrays while inputs are unchanged; return new references for changed outputs. Mutating results in place can hide changes; recreating equivalent results causes unnecessary updates.
+
+[Capability index](../features/index.md#project-and-customization) \xb7 [Project structure](cli.md#project-structure)
+
+## Model
+
+| Concept | Responsibility | Guide |
+| --- | --- | --- |
+| Entity, alias, relation | Saved product state and choices, shared views over entity types, and ownership, such as a cabinet's width and its shelves | [Entities and relations](../features/domain-model/entities-and-relations.md) |
+| Component | Configured data or behavior bound to an entity or alias, shown by filters | [Components](../features/domain-model/components.md) |
+| Expression | Pure derived value with a \`$\` prefix, such as \`$price\` | [Expressions](../features/domain-model/expressions.md) |
+| Invariant, transformer | Validation and violations, such as an unsupported width and finish, and repair after a change | [Validation and repair](../features/domain-model/validation-and-repair.md), [Transformers](../features/domain-model/transformers.md) |
+| Action | Prepared named domain operation, such as adding a shelf | [Actions](../features/domain-model/actions.md) |
+
+Keep a deployed model unchanged under its version. When it changes, retain the old version and migrate saved configurations with [Model migration](../processes/model-migration.md).
+
+## Runtime state
+
+- **Store** — every change is a set of updates. Transformers run first, then validation; a change with a \`fatal\` or \`fixable\` violation is rejected, and controls dry-run their options the same way to disable those that would fail: [State](../features/state/index.md).
+- **Application states** — presets, navigation, view and tool states and the selection decide what the configurator shows and which filtered components apply: [Application states](../features/application-states/index.md).
+
+## Frontend runtime
+
+Build the interface from elements and handlers, connected through \`phx.frontend\`.
+
+| Surface | Use for | Guide |
+| --- | --- | --- |
+| Layout elements | The project layout, loading and error pages, preset screen, assistant forms | [Custom project layout](../features/custom-layout/index.md) |
+| Entity elements and control hooks | Controls the layout renders or anchors in the scene | [Domain controls](../features/domain-controls/index.md) |
+| Handlers | Event and lifecycle behavior, registered finalization actions | [Finalization actions](../features/custom-layout/finalization-actions.md) |
+| Spec texts | Translated texts and the language switch | [Localization](../features/localization.md) |
+| Scene objects built in code | Geometry a loaded model cannot express, such as a worktop with cut-outs | [Scene objects built in code](../features/scene-objects.md) |
+
+Prefer a custom \`ConfiguratorLayout\` composed from Phoenix controls, slots and hooks; it owns the canvas, messages, read mode and finalization. Register the React component with the supported factory:
+
+\`\`\`tsx
+export default phx.frontend.createCustomPhoenixLayoutElement('ConfiguratorLayout', ConfiguratorLayout)
+\`\`\`
+
+[Scene and safe area](../features/custom-layout/scene-and-safe-area.md) has the minimal complete layout.
+
+## Webhooks and finalization
+
+Webhooks run server-side integrations. Keep credentials there and browser-only imports out. Frontend components and handlers stay excluded unless explicitly included or automatically required.
+
+### Hooks and stages
+
+| Hook / stage | Purpose / registration |
+| --- | --- |
+| Authentication | \`withAuthHook\`; code, refresh, anonymous flows and Clerk code/session/refresh handlers |
+| Backend data | \`withFetchBackendData\`; server-fetched data for the configuration |
+| Configurator finalization | \`withConfiguratorFinalize\`; validate/prepare the agreed completion journey |
+| Prefetch | Finalization's \`withPrefetch\`; data preparation before tasks |
+| Callback | Finalization's \`withCallback\`; consume task resources and return the final result |
+| Admin finalization | Generated Admin publishing handler; map and publish content |
+| Assistant setup | Generated from assistant settings; optional \`createAssistantSetupHandler\` narrows session capabilities |
+
+### Tasks
+
+| Task types | Purpose |
+| --- | --- |
+| \`GenerateConfigurationLink\` | Shareable configuration link |
+| \`GenerateImages\` | Server-rendered images |
+| \`GenerateCsv\` | CSV export |
+| \`GeneratePdf\`, \`GenerateStaticPdf\` | Template-based or prepared HTML/React PDF |
+| \`SendEmail\`, \`SendStaticEmail\` | Template-based or prepared HTML/React email |
+| \`SendHttpRequest\` | External HTTP integration |
+| \`WooCommerceAddToCart\` | WooCommerce cart integration |
+| \`EditGoogleSpreadsheet\` | Spreadsheet updates |
+| \`PublishRevision\` | Admin content revision |
+| \`PublishRevisionChunks\`, \`PublishRevisionChunksStaged\` | Chunked publication, including staged uploads |
+| \`CallLambdaBack\` | Callback with generated resources |
+
+- Use \`phx.webhooks\` builders and task factories. Named resources connect the tasks that produce them to their consumers.
+- Execution proceeds from backend data and prefetch through ordered tasks to the callback/result. Resource dependencies must follow the platform task order.
+- For a quote, generate a configuration link and render, include them in a PDF, then send the email and return the callback result. Test without real messages or orders until authorized.
+
+[Webhooks](../features/webhooks.md) \xb7 [Hooks/tasks, complete examples and order](../features/index.md#webhooks-and-finalization) \xb7 [Finalization process](../processes/finalization.md)
+
+## Data sources
+
+Choose data by ownership and lifetime.
+
+| Source | Ownership / lifetime |
+| --- | --- |
+| Entity state | Saved configuration choices |
+| Published data | Released catalogue/content revision |
+| Frontend data | Values from the embedding frontend |
+| Session data | Authentication/session context |
+| Backend data | Values fetched through the webhook |
+
+[Expressions](../features/domain-model/expressions.md) shows how expressions and elements read these sources \xb7 [Data sources and connected data](../features/index.md#data-sources)
+
+## Admin and Studio
+
+- Use **Project Admin** to manage domain content and publish it for configurators.
+- Use **Studio** to manage platform workspaces, projects, environments and deployments.
+
+[Admin and Studio documentation](../features/index.md#admin-and-studio)
+`;export const generatePhoenixSdkCore=()=>e({path:"core/sdk.md",title:"SDK",summary:"the SDK mental model, capabilities, invariants and supported customization",sections:[t]});

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

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

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

@@ -0,0 +1,44 @@
+import{createPhoenixTopicGuide as e}from"../guide.js";let t=`The client creates the configurator; its users may be buyers, salespeople or designers. The aim is a useful, polished product that fits the client's purpose, preferences and agreed effort.
+
+These practices usually lead there; adapt them to the client, the product and the task rather than following a script.`,n=`## Where to start
+
+- **A new project** — nothing in \`.phoenix/workspace/specification/\` and still the starter spec, or a first draft the project record shows in progress — usually starts with a [First draft](../processes/first-draft/index.md): a convincing first version, quickly.
+- **Normal mode** — everything after that, and every existing project — builds on the specification and the next increments in the project record. A small fix usually goes straight to the affected behavior.
+
+The client can always redirect; follow their lead without nagging or repeated approval requests.`,a=`## Working with the client
+
+Be a warm, direct expert who listens, recommends an approach and takes responsibility for SDK and tooling choices. Look at supplied materials before asking, and keep the conversation about the product rather than setup questionnaires or jargon. When uncertainty affects the next result, such as a blocking ambiguity, a business decision needed now or a departure from accepted design, ask with a recommendation; otherwise state reversible defaults and keep going. Keep facts, explicit preferences and provisional assumptions distinct.
+
+Talk about the client's product: what they can try, see or decide. Modes, processes, stages, records and guide names are internal and mean nothing to the client. Say "next, I'll add the desk range", not "switching to normal mode and starting an increment".
+
+Small problems met along the way, such as a type error, a misaligned part or a font that did not load, are usually best fixed quietly; mention one only when it changes what the client sees or decides. Messages land better when they stay light: one decision at a time is easier to answer than a list of questions, and a long list, such as provisional defaults, reads better as a link to the document that holds it. When you create or change a client document, open it or link it in the message that announces it.`,i=`## Preferences
+
+Preferences shape how much effort and autonomy fit the work; note them in the project record as they emerge:
+
+- **Cost** — token and money sensitivity: subagent reviews, parallel agents, heavy rendering.
+- **Time** — fast feedback in small steps, or thorough and slower increments.
+- **Autonomy** — decide and report, or check in before choices; how large an autonomous batch may be.
+- **Quality bar** — demo grade or ready for real users; it sets review depth.
+- **Communication** — detail, technical depth and update frequency.
+
+A first draft runs no reviews or parallel agents, so it needs none of these answers. Ask once, briefly and with a recommendation, at a natural pause after the first draft or when work on an existing project starts without them. With a cost- or time-sensitive client, offer an expensive action with what it would add and wait for a yes rather than starting it.`,s=`## Keeping the client oriented
+
+Clients do best when they know what is happening, what comes next and whether anything is blocked. Share the next steps before longer work, update briefly during long builds, and when stuck, name the dependency and what can continue. Records do not replace these updates.
+
+Reports work best at a high level: what the client can now try, what is still open and what comes next. The details of what was changed belong in the changelog. A good handoff separates what is done, what is unverified and what remains, and usually ends with a recommended next step, sometimes with an alternative such as a [Phoenix capability](../features/index.md) the client may not know about. Note declined suggestions so they do not come back.`,r=`## Building in increments
+
+After the first draft, a short **Next increments** list in the project record keeps the way ahead visible: one line per increment saying what the client will be able to do and what it waits on, such as a model, a price list or a business answer, with postponed scope below it. Ordering by what users decide first and by real product dependencies usually works, with core interactions before more options and finalization once the configuration it submits is stable. Present it in product language with a recommended next increment; the client agrees on the next step, not on the whole list. Keep it current as increments land or the scope changes; an existing project without one writes it when its work goes beyond a single fix.
+
+Work then goes best in small, useful increments: choose an outcome with observable checks; extend the [specification](../processes/specification/index.md) only as far as the increment needs; build it within the branding and UX guidelines, where they exist, using the [SDK guidance](sdk.md); exercise the changed interaction and what it affects, such as control targets, selection context and global versus per-part behavior; review it as the [review strategy](#review-strategy) suggests; then show the client what to try and fold their feedback into the specification and the next increments.
+
+Habits that help: wait for feedback before expanding an increment unless the client asked for a larger batch; settle core interactions before multiplying options; keep agreed scope visible until it is built or deferred; preserve selections and accepted behavior; and when rules change, keep model, scene, controls, dimensions, pricing and checks consistent.`,o=`## Visual choices
+
+When taste, branding or interaction has several reasonable answers that the client's materials do not settle, alternatives usually help: explain the tradeoffs and recommend one. They help most when they really differ and each is finished as well as it can be, so the client chooses between good options rather than between variations. Accepted choices stay settled, facts are not the client's to pick, and routine reversible details need no approval. [Variants](../features/variants.md) shows alternatives in the live preview.`,c=`## Review strategy
+
+The first draft skips review processes; a quick look at the running preview before showing each result keeps broken work away from the client.
+
+Later, review changed work before committing or handing it over with the [review processes](../processes/review/index.md), scaled to impact, uncertainty, the quality bar and the cost preference. A self-review is usually enough; an independent subagent adds a fresh view of visual fidelity, complex rules or broad interactions when the preferences allow it. Note whether review was independent and what remains unverified; a passing build does not prove product quality.`,d=`## Feedback and completion
+
+Client feedback shapes the direction and the records; confirm material departures. Phoenix feedback is a separate, external report: [Feedback](../processes/feedback/index.md) covers SDK problems and the client's evaluation of the run, and only approved content is sent.
+
+Some lines stay firm: publishing, real orders, real messages and connecting live systems need the client's authorization against the concrete result. [Deployment](cli.md#deployment) covers running a deploy.`;export const generatePhoenixWorkflowCore=()=>e({path:"core/workflow.md",title:"Workflow",summary:"where to start, working with the client, preferences, increments, records and review strategy",sections:[t,n,a,i,s,r,o,"## Records\n\n- **Specification** — client-facing documents: branding, UX guidelines, product definition and catalogs, with sources in `.phoenix/workspace/specification/` and rendered PDFs in `docs/`. [Specification](../processes/specification/index.md) describes them; later work follows them, and changing an accepted rule is the client's call.\n- **Project record** — `.phoenix/workspace/project.md` is the current snapshot: preferences, approach, decisions with rationale, declined suggestions, progress, deploys and their outcome, next increments, open questions and SDK problems worth reporting, rewritten as they change. `.phoenix/workspace/changelog/` keeps the history: append a dated entry for each meaningful change, decision, verification, deploy or piece of client feedback, and continue in a new numbered file when the current one gets long.\n\nReuse records when resuming; they are not a client task or an approval gate. Leave out secrets, unrelated personal information and raw transcripts; [project structure](cli.md#project-structure) describes how records are kept and deployed.",c,d]});

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

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

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

@@ -0,0 +1,3 @@
+import{createPhoenixIndexGuide as e}from"../../guide.js";import{generatePhoenixNavigationFeature as t}from"./navigation.js";import{generatePhoenixPresetsFeature as o}from"./presets.js";import{generatePhoenixSelectionFeature as s}from"./selection.js";import{generatePhoenixViewsAndToolsFeature as n}from"./views-and-tools.js";export const generatePhoenixApplicationStatesGuides=()=>{let i=[o(),t(),n(),s()];return[e({path:"features/application-states/index.md",title:"Application states",summary:"Presets, navigation, view and tool states, selection and hover; read when choosing how a configuration starts, how users move through it, or what the scene and UI follow.",intro:`Application states are the configurator's context beside the product's entities: the preset a configuration starts from, the stage users are at (navigation state), how the scene is shown (view state), what users are doing in it (tool state), and which entity is selected or hovered. Navigation, view and tool states are independent lists declared in YAML; their active values, the selection and the hover feed component filters, whose mechanism [Components](../domain-model/components.md) owns.
+
+Only the entities are saved with a configuration: it opens at the first declared value of each list, with the root entity selected. Changing them alone is not an undo step, but undoing a change restores them as they were just before it, with the hover cleared; [Updates and dry runs](../state/updates.md) owns undo.`,guides:i,notes:[]}),...i]};