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

package/README.md

@@ -37,7 +37,9 @@ src/invariants/       validation rules
 src/elements/         custom React elements for the configurator and admin UI
 src/handlers/         actions, themes and other handlers
 src/webhooks/         server-side finalization and integration handlers
-.phoenix/             generated code, rebuilt by `phoenix sync`; never edit by hand
+.phoenix/             generated code, rebuilt by `phoenix sync`; never edit generated files
+.phoenix/workspace/   project-owned records in application-spec projects; safe to edit and commit
+docs/                 client documents, such as rendered specification PDFs; deployed with the private sources
 ```
 
 Generated code exposes the `phx` global in project files: `phx.domain` for the model and expressions, `phx.frontend` for elements and handlers, `phx.webhooks` for webhook builders, and the `Phx` type namespace for the generated types.
@@ -107,7 +109,7 @@ The `package.json` `exports` map is the machine-readable list, and the TypeScrip
 ## Documentation and support
 
 - `pnpm phoenix docs -s "<topic>"` searches the bundled documentation; `phoenix docs -r <path>` reads a page.
-- `phoenix sync` generates one `phoenix` skill under `.claude/skills/` and `.agents/skills/`, with task-specific project, CLI, workflow, review, variants and feedback guides linked from its entry point.
+- `phoenix sync` generates one `phoenix` skill under `.claude/skills/` and `.agents/skills/`, and rewrites these SDK-owned files on every sync. Keep custom skills in folders whose names do not start with `phoenix`.
 - The builder docs at [docs.salsita.ai](https://docs.salsita.ai) have the guides for getting started and the CLI reference; Studio is where you sign in and manage projects.
 - `pnpm phoenix feedback "<message>"` reaches the team directly.
 

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

@@ -1,4 +1,9 @@
+export { RuntimeReferenceStore, type ScopedBuilder } from '#package/domain';
+/**
+ * @deprecated Use {@link RuntimeReferenceStore}. This compatibility alias will be removed in a
+ * future breaking project-sdk release.
+ */
+export { RuntimeReferenceStore as ApplicationSpecCache } from '#package/domain';
 export * from './file-hash.js';
 export * from './content-diff.js';
-export * from './runtime-reference-store.js';
 export * from './file-dep-hash.js';

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

@@ -1 +1 @@
-export*from"./file-hash.js";export*from"./content-diff.js";export*from"./runtime-reference-store.js";export*from"./file-dep-hash.js";
+export{RuntimeReferenceStore,RuntimeReferenceStore as ApplicationSpecCache}from"#package/domain";export*from"./file-hash.js";export*from"./content-diff.js";export*from"./file-dep-hash.js";

package/dist/application-spec/generate-application/code/domain-runtime-files.d.ts

@@ -1,22 +1,3 @@
-/**
- * Generates the application files that a running configurator imports.
- *
- * Membership criterion: a file belongs to this group when the configurator or admin runtime imports
- * it in order to execute the parsed application domain — the domain model, its globals, and the
- * code that binds authored project files into runtime sections. A file that only exists so a
- * standalone application can boot, render, or deploy belongs to the standalone-application group,
- * and a file that configures the generated project itself belongs to the project-scaffolding group.
- *
- * This is the group a host embedding an already-built runtime needs on its own, which is why it is
- * callable without also generating a complete standalone application.
- *
- * How the generated files reach the `phx` API is this group's own decision, expressed as a
- * `PhxBindingStrategy` the caller selects. The strategy is chosen once, here at the group boundary,
- * rather than threaded as a mode flag through the individual templates: every template stays
- * unaware of which binding is in effect and simply renders the blocks the strategy supplies.
- *
- * @module
- */
 import { GeneratedApplicationFile } from '../../core/index.js';
 import type { PhoenixDefinitions } from '../../core/index.js';
 import type { ApplicationSpec, CategorizedFiles } from '../../parse-application-files/index.js';

package/dist/application-spec/generate-application/code/domain-runtime-files.js

@@ -1 +1 @@
-import{GeneratedApplicationFile as n}from"../../core/index.js";import{encodeRuntimeSpec as e,toRuntimeSpec as i}from"../runtime-spec/index.js";import{createApplicationTypeImportRegistrar as o}from"./common/index.js";import{generateAdminGlobalBindingBlock as t,generateApplicationSpecAdminCode as a,generateApplicationSpecAdminFrontendCode as r,generateApplicationSpecAdminGlobals as s,generateApplicationSpecCodeFile as d,generateApplicationSpecConfiguratorCode as c,generateApplicationSpecConfiguratorConfig as p,generateApplicationSpecConfiguratorFrontendCode as m,generateApplicationSpecConfiguratorGlobals as g,generateApplicationSpecDomainFile as l,generateApplicationSpecDomainSpecFile as f,generateApplicationSpecGlobals as u,generateApplicationSpecMessagesFile as B,generateApplicationSpecTypesModule as x,generateConfiguratorGlobalBindingBlock as h,generateImportedStateConstants as k,generatePhxExportsBlock as y,generatePhxGlobalsBlock as C,generateStateConstants as b}from"./templates/index.js";import{splitWebhookMembership as D}from"./webhook-safe-files.js";let j=()=>"";export const globalPhxBindingStrategy={generateApplicationTypesFile:(e,i)=>n("globals.d.ts",u(e,i)),generateDomainBindingBlock:C,generateStateConstants:b,generateConfiguratorBindingBlock:h,configuratorBindingDescription:"Creates the configurator interface and sets phx.frontend — must run before any user code imports.",generateAdminBindingBlock:t,adminBindingDescription:"Creates the admin interface and sets phx.frontend.admin — must run before admin user code imports."};export const modulePhxBindingStrategy={applicationTypeImportSource:"./application-types.js",generateApplicationTypesFile:(e,i)=>n("application-types.ts",x(e,i)),generateDomainBindingBlock:y,generateStateConstants:k,generateConfiguratorBindingBlock:j,configuratorBindingDescription:"Creates and exports the configurator interface for a module-scoped phx binding.",generateAdminBindingBlock:j,adminBindingDescription:"Creates and exports the admin interface for a module-scoped phx binding."};let S=n=>n.map(n=>n.file.name);export const generateDomainRuntimeFiles=(t,u)=>{let{applicationSpec:x,categorizedFiles:h,phxDefinitions:k,includeDefaultEnvs:y}=t,C=o(u.applicationTypeImportSource),b=S(h.expressions),j=S(h.actions),A=S(h.handlers),F=S(h.elements),I=S(h.transformers),T=S(h.invariants),w=S(h.adminInvariants),v=S(h.adminExpressions),E=S(h.adminElements),O=D(h.components),P=S(O.webhookIncluded),R=S(O.frontendOnly),q=D(h.adminComponents),z=S(q.webhookIncluded),G=S(q.frontendOnly);return[n("domain-spec.ts",f(x,{generateBindingBlock:u.generateDomainBindingBlock,generateStateConstants:u.generateStateConstants,registerApplicationTypeImports:C})),n("configurator-globals.ts",g(u.generateConfiguratorBindingBlock,u.configuratorBindingDescription,C)),n("configurator-domain-code.ts",c({expressionFiles:b,actionFiles:j,invariantFiles:T,componentFiles:P})),n("configurator-frontend-code.ts",m({transformerFiles:I,handlerFiles:A,elementFiles:F,componentFiles:R})),n("admin-domain-code.ts",a({adminExpressionFiles:v,adminInvariantFiles:w,adminComponentFiles:z})),n("admin-frontend-code.ts",r({adminElementFiles:E,adminComponentFiles:G})),n("spec-code.ts",d(x,C)),n("spec-messages.ts",B(x)),n("domain.ts",l(x)),n("configurator-config.ts",p(x,{includeDefaultEnvs:y})),u.generateApplicationTypesFile(x,k),n("admin-globals.ts",s(u.generateAdminBindingBlock,u.adminBindingDescription)),n("application-spec.json",e(i(x)),{format:!1})]};
+import{encodeRuntimeSpec as n,toRuntimeSpec as e}from"#package/domain";import{GeneratedApplicationFile as i}from"../../core/index.js";import{createApplicationTypeImportRegistrar as o}from"./common/index.js";import{generateAdminGlobalBindingBlock as t,generateApplicationSpecAdminCode as a,generateApplicationSpecAdminFrontendCode as r,generateApplicationSpecAdminGlobals as s,generateApplicationSpecCodeFile as d,generateApplicationSpecConfiguratorCode as c,generateApplicationSpecConfiguratorConfig as p,generateApplicationSpecConfiguratorFrontendCode as m,generateApplicationSpecConfiguratorGlobals as g,generateApplicationSpecDomainFile as l,generateApplicationSpecDomainSpecFile as f,generateApplicationSpecGlobals as B,generateApplicationSpecMessagesFile as u,generateApplicationSpecTypesModule as x,generateConfiguratorGlobalBindingBlock as h,generateImportedStateConstants as k,generatePhxExportsBlock as y,generatePhxGlobalsBlock as C,generateStateConstants as b}from"./templates/index.js";import{splitWebhookMembership as D}from"./webhook-safe-files.js";let S=()=>"";export const globalPhxBindingStrategy={generateApplicationTypesFile:(n,e)=>i("globals.d.ts",B(n,e)),generateDomainBindingBlock:C,generateStateConstants:b,generateConfiguratorBindingBlock:h,configuratorBindingDescription:"Creates the configurator interface and sets phx.frontend — must run before any user code imports.",generateAdminBindingBlock:t,adminBindingDescription:"Creates the admin interface and sets phx.frontend.admin — must run before admin user code imports."};export const modulePhxBindingStrategy={applicationTypeImportSource:"./application-types.js",generateApplicationTypesFile:(n,e)=>i("application-types.ts",x(n,e)),generateDomainBindingBlock:y,generateStateConstants:k,generateConfiguratorBindingBlock:S,configuratorBindingDescription:"Creates and exports the configurator interface for a module-scoped phx binding.",generateAdminBindingBlock:S,adminBindingDescription:"Creates and exports the admin interface for a module-scoped phx binding."};let j=n=>n.map(n=>n.file.name);export const generateDomainRuntimeFiles=(t,B)=>{let{applicationSpec:x,categorizedFiles:h,phxDefinitions:k,includeDefaultEnvs:y}=t,C=o(B.applicationTypeImportSource),b=j(h.expressions),S=j(h.actions),A=j(h.handlers),F=j(h.elements),I=j(h.transformers),T=j(h.invariants),w=j(h.adminInvariants),v=j(h.adminExpressions),E=j(h.adminElements),O=D(h.components),P=j(O.webhookIncluded),R=j(O.frontendOnly),q=D(h.adminComponents),z=j(q.webhookIncluded),G=j(q.frontendOnly);return[i("domain-spec.ts",f(x,{generateBindingBlock:B.generateDomainBindingBlock,generateStateConstants:B.generateStateConstants,registerApplicationTypeImports:C})),i("configurator-globals.ts",g(B.generateConfiguratorBindingBlock,B.configuratorBindingDescription,C)),i("configurator-domain-code.ts",c({expressionFiles:b,actionFiles:S,invariantFiles:T,componentFiles:P})),i("configurator-frontend-code.ts",m({transformerFiles:I,handlerFiles:A,elementFiles:F,componentFiles:R})),i("admin-domain-code.ts",a({adminExpressionFiles:v,adminInvariantFiles:w,adminComponentFiles:z})),i("admin-frontend-code.ts",r({adminElementFiles:E,adminComponentFiles:G})),i("spec-code.ts",d(x,C)),i("spec-messages.ts",u(x)),i("domain.ts",l(x)),i("configurator-config.ts",p(x,{includeDefaultEnvs:y})),B.generateApplicationTypesFile(x,k),i("admin-globals.ts",s(B.generateAdminBindingBlock,B.adminBindingDescription)),i("application-spec.json",n(e(x)),{format:!1})]};

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

@@ -48,7 +48,8 @@ phoenix-api.yaml
 *.blend1
 
 # Auto-generated files
-.phoenix
+**/.phoenix/*
+!**/.phoenix/workspace/
 **/locales/*/*.ts
 phoenix.config.ts
 .prettierignore

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

@@ -38,7 +38,7 @@ 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 { type PhoenixSkillOptions, followsCanaryBuilds } from './skills/phoenix-skill.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';

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{generatePhoenixSkillBundle}from"./skills/phoenix-skill-bundle.js";export{followsCanaryBuilds}from"./skills/phoenix-skill.js";export{generateApplicationSpecPrettierConfig}from"./prettier-config.js";export{generateApplicationSpecRobotsTxt}from"./robots-txt.js";export{generateApplicationSpecRootTsconfig}from"./root-tsconfig.js";export{generateApplicationSpecStoryDevDeclaration,generateApplicationSpecStoryPhxModule,generateApplicationSpecStoryRawProjectFiles,generateApplicationSpecStoryWrapper}from"./story/index.js";export{generateApplicationSpecCodeFile}from"./spec-code/index.js";export{generateApplicationSpecMessagesFile}from"./spec-messages/index.js";export{generateApplicationSpecTsconfig}from"./tsconfig.js";export{generateApplicationSpecWebhookBuilders}from"./webhook-builders.js";export{generateApplicationSpecWebhookIndex}from"./webhook-index.js";export{generateApplicationSpecWebhooksConfig}from"./webhooks-config.js";
+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.js

@@ -1,8 +1,8 @@
-import{DEFAULT_FALLBACK_LOCALE as e,LOCALE_FALLBACK_MAP as a}from"#package/i18n";export const generateLinguiRcFile=s=>{let o;return`{
+import{DEFAULT_FALLBACK_LOCALE as e,LOCALE_FALLBACK_MAP as a}from"#package/i18n";export const generateLinguiRcFile=o=>{let s;return`{
   "sourceLocale": "en",
-  "locales": [${s.map(e=>`"${e}"`).join(", ")}],
+  "locales": [${o.map(e=>`"${e}"`).join(", ")}],
   "fallbackLocales": {
-${(o=Object.entries(a).map(([e,a])=>{let s=Array.isArray(a)?`[${a.map(e=>`"${e}"`).join(", ")}]`:`"${a}"`;return`    "${e}": ${s}`})).push(`    "default": "${e}"`),o.join(",\n")}
+${(s=Object.entries(a).map(([e,a])=>{let o=Array.isArray(a)?`[${a.map(e=>`"${e}"`).join(", ")}]`:`"${a}"`;return`    "${e}": ${o}`})).push(`    "default": "${e}"`),s.join(",\n")}
   },
   "catalogs": [
     {
@@ -13,7 +13,8 @@ ${(o=Object.entries(a).map(([e,a])=>{let s=Array.isArray(a)?`[${a.map(e=>`"${e}"
       ],
       "exclude": [
         "**/node_modules/**",
-        "**/dist/**"
+        "**/dist/**",
+        "**/.phoenix/workspace/**"
       ]
     }
   ],

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. For a canary project, follow the canary section of [Project operations](../processes/operations.md) when it has one.\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. [CLI and setup documentation](../features/index.md#cli-and-project-identity) 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-and-project-identity) 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 the [custom layout contract](../features/custom-layout.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- `.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. See `docs/phoenix/project-structure.mdx` through the [capability index](../features/index.md#project-and-customization).\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- 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. Start and keep the preview with [Project operations](../processes/operations.md); a model change needs a dev restart and a new preview address.\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`phoenix deploy` sends project sources for a server build and waits for the target environment to go live. Use [Project operations](../processes/operations.md) for preparation, transcript consent, Studio progress and completion. A successful local preview does not establish deployed model compatibility; use [Model migration](../processes/model-migration.md) when needed. [Deployment documentation](../features/index.md#deployment) covers status and environment details.\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,150 @@
+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.
+
+### 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 | Example |
+| --- | --- | --- |
+| Entity / attribute | Saved product state and choices | Cabinet width, finish |
+| Alias | Shared view over entity types | Furniture covering Chair and Table |
+| Relation | Connections and ownership | Cabinet containing shelves |
+| Expression | Pure derived value, \`$\` prefix | \`$price\`, \`$area\` |
+| Action | Prepared named domain operation | Add a shelf |
+| Invariant | Validation and violations | Unsupported width/finish combination |
+| Transformer | Automatic consistency repair | Adjust dependent state after a change |
+
+- Keep a deployed model unchanged under its version. When it changes, retain the old version and migrate saved configurations.
+- Bindings connect component state to the domain: \`$read\` reads, \`$write\` writes, and \`$bind\` does both.
+- Use filters for the relevant navigation, view or selection context.
+
+[Model documentation](../features/index.md#model) \xb7 [Model migration](../processes/model-migration.md)
+
+## Frontend runtime
+
+Build the interface from elements and handlers, connected through \`phx.frontend\`.
+
+| Surface | Use for |
+| --- | --- |
+| Elements | React UI, custom project layout, loading/error pages, assistant forms |
+| Handlers | Event/lifecycle behavior and registered finalization actions |
+| Configurator interface | Typed \`phx.frontend\` hooks for state, navigation, selection, messages, access, finalization |
+| Layout slots | Reusable Phoenix canvas, panels, actions and services within your layout |
+| Components / transformers | Domain-bound runtime behavior and consistency, separate from UI composition |
+
+Prefer a custom \`ConfiguratorLayout\` composed from Phoenix controls, slots and hooks.
+
+- The layout owns canvas and safe-area wiring, messages, read mode, fullscreen and finalization.
+- After defining the React component \`ConfiguratorLayout\`, register it with the supported factory:
+
+\`\`\`tsx
+export default phx.frontend.createCustomPhoenixLayoutElement('ConfiguratorLayout', ConfiguratorLayout)
+\`\`\`
+
+[Custom layout contract and complete examples](../features/custom-layout.md) \xb7 [Configurator interface and frontend docs](../features/index.md#frontend-runtime)
+
+## 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 |
+
+
+### Example: a memoized expression
+
+Assume YAML declares \`Cabinet.finish\`, its \`$summary\` object, and required published/frontend/session fields below. The result has availability, currency, customer group and nullable delivery days.
+
+\`\`\`ts
+// src/expressions/cabinet.ts
+import { memoEval } from '@salsita-ai/sdk/domain'
+
+export default phx.domain.implementCustomExpressions({
+  Cabinet: {
+    $summary: memoEval(
+      (self, _state, ctx) => [
+        self.finish,
+        ctx.publishedData.finishes,
+        ctx.frontendData.currency,
+        ctx.sessionData.customerGroup,
+        ctx.backendData?.['deliveryDays'],
+      ],
+      (finish, finishes, currency, customerGroup, deliveryDays) => ({
+        available: finishes.includes(finish),
+        currency,
+        customerGroup,
+        deliveryDays: typeof deliveryDays === 'number' ? deliveryDays : null,
+      })
+    ),
+  },
+})
+\`\`\`
+
+Use string \`finish\`/\`currency\`/\`customerGroup\` fields and a string-array \`finishes\`. The selector lists every dependency; memoEval reuses the same result object while they stay unchanged. Backend data is optional and untyped here, so narrow its value before using it.
+
+[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,40 @@
+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 plan. A small fix 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 never come up with the client. Say "next, I'll add the desk range", not "switching to normal mode and running Planning".`,r=`## 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 its handoff 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.`,i=`## Keeping the client oriented
+
+Clients do best when they know what is happening, what comes next and whether anything is blocked. Share the plan before longer work, update briefly during long builds, and when stuck, name the dependency and what can continue. Records do not replace these updates.
+
+A good handoff separates what is done, what is unverified and what remains. After the first draft, end every handoff with a recommended next step and one or two alternatives, often a [Phoenix capability](../features/index.md) the client may not know about. Note declined suggestions so they do not come back.`,s=`## Building in increments
+
+After the first draft, [Planning](../processes/planning.md) establishes the full specification and an ordered plan. Work then goes best in small, useful increments: choose an outcome with observable checks; build it within the [branding and UX guidelines](../processes/specification/index.md), 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 plan.
+
+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. 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 end-of-run evaluation, 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, and deploys go through [Project operations](../processes/operations.md), including its transcript consent.`;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,r,i,s,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 and open questions, rewritten as they change. `.phoenix/workspace/changelog/` keeps the history: append a dated entry for each meaningful change, decision, verification or piece of client feedback, and continue in a new numbered file when the current one gets long. Normal mode adds `.phoenix/workspace/plan.md`.\n\nReuse records when resuming; they are never 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/custom-layout.d.ts

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

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

@@ -0,0 +1 @@
+import{createPhoenixFeatureGuide as o}from"../guide.js";import{sdkGuidanceSections as e}from"../sdk-content.js";export const generatePhoenixCustomLayoutFeature=()=>o({path:"features/custom-layout.md",title:"Custom project layout",summary:"Supported UI composition, slots, hooks, preset screen, app loader and page responsibilities; read when creating or changing a project layout or custom element.",whenToUse:"Read when composing a project layout or replacing a supported page element, such as the preset screen or the app loader.\n\nCompose project UI through a default-exported `phx.frontend.createCustomPhoenixLayoutElement()` in `src/elements/`. Reuse Phoenix layout slots, controls and typed hooks; YAML remains the owner of domain and component behavior.",capabilities:e.customLayout,example:"For a relocated sidebar with the usual configured controls, use the complete layout in `docs/layouts/sidebar/in-a-custom-layout.mdx`. For a custom panel and responsive shell, use `docs/layouts/custom-layout.mdx`; both show the required canvas and safe-area wiring. The layout gallery in `docs/layouts/gallery/` shows complete, distinct layouts for real products.",documentation:"Canonical examples and APIs: `docs/layouts/custom-layout.mdx`, `docs/layouts/sidebar/in-a-custom-layout.mdx`, `docs/layouts/presets/custom.mdx`, `docs/phoenix/configurator-interface.mdx` and `docs/phoenix/layout-slots.mdx`, read with `pnpm phoenix docs -r <path>`."});

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

@@ -0,0 +1,3 @@
+import { type PhoenixGuide } from '../guide.js';
+/** The capability index followed by the feature guides it lists. */
+export declare const generatePhoenixFeatureGuides: () => readonly PhoenixGuide[];

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

@@ -0,0 +1 @@
+import{createPhoenixIndexGuide as e}from"../guide.js";import{generatePhoenixCustomLayoutFeature as n}from"./custom-layout.js";import{generatePhoenixInspectionFeature as o}from"./inspection.js";import{generatePhoenixVariantsFeature as i}from"./variants.js";import{generatePhoenixWebhooksFeature as t}from"./webhooks.js";export const generatePhoenixFeatureGuides=()=>{let s=[n(),t(),o(),i()];return[e({path:"features/index.md",title:"Features",summary:"What Phoenix capabilities support, their constraints and the canonical SDK documentation.",intro:"Use only the topic the task needs. Paths below are documents shipped with the installed SDK: read one with `pnpm phoenix docs -r <path>`; `pnpm phoenix docs -s '<topic>'` finds more examples. These links do not make their destinations required reading.",guides:s,notes:["## Topic map\n\nThese topics point directly to canonical SDK docs when no extra agent-facing explanation is needed.\n\n### Project and customization\n\n- `docs/phoenix/getting-started.mdx`, `docs/phoenix/quickstart.mdx` — setup and a complete worked configurator.\n- `docs/phoenix/best-practices.mdx` — supported composition and extension patterns.\n- [Project structure](../core/cli.md#project-structure) — authored folders and generated boundaries; canonical reference: `docs/phoenix/project-structure.mdx`.\n\n### Model\n\n- `docs/phoenix/domain-model.mdx` — entities, attributes, relations, expressions, actions and invariants.\n- `docs/phoenix/expression-context.mdx` — computed values and data available to expressions.\n- [Model migration](../processes/model-migration.md) — preserve a deployed model and migrate saved configurations; `docs/phoenix/migrations.mdx` has the full examples.\n\n### Frontend runtime\n\n- `docs/phoenix/components.mdx` — configured versus custom components and bindings.\n- `docs/phoenix/state-management.mdx`, `docs/phoenix/application-states.mdx` — state flow, transformers and application context.\n- `docs/phoenix/configurator-interface.mdx`, `docs/phoenix/layout-slots.mdx` — custom elements, layouts and supported hooks.\n- `docs/phoenix/theming.mdx`, `docs/ux-guidelines/overview.mdx` — branding and interaction principles.\n- `docs/layouts/gallery/` — complete custom layouts for real products.\n\n### Webhooks and finalization\n\n- `docs/phoenix/webhooks.mdx`, `docs/phoenix/webhook-membership.mdx` — execution and registration.\n- `docs/phoenix/finalization.mdx`, `docs/phoenix/blender-rendering.mdx` — finalization tasks, PDF, email and CSV, and generated images.\n- `docs/other-features/client-side-rendering/declarative.mdx` — configurator-rendered images in PDFs and emails.\n- [Finalization](../processes/finalization.md) — agree and implement the completion journey.\n\n### Data sources\n\n- `docs/phoenix/data-sources.mdx` — published, frontend, session and backend data and their lifetimes.\n- `docs/phoenix/connected-data-sources.mdx` — connected sheets and external data.\n- [Data inspection](inspection.md#inspect-data) — examine the data the preview actually received.\n\n### Admin and Studio\n\n- `docs/phoenix/admin.mdx`, `docs/phoenix/publishing.mdx` — project content administration and published revisions.\n- `docs/phoenix/sdk-builder-workflow.mdx` — Studio workspaces, projects, environments and builds.\n\n### CLI and project identity\n\n- `docs/phoenix/phoenix-cli.mdx` — login, project selection, dependencies, sync, dev, build and check, flags and troubleshooting.\n- `docs/phoenix/sessions-and-access.mdx`, `docs/phoenix/clerk-sign-in.mdx` — configurator access and project authentication.\n- [Project operations](../processes/operations.md) — preview, SDK updates when applicable, and deployment.\n\n### Deployment\n\n- `docs/phoenix/deployments.mdx`, `docs/phoenix/sdk-builder-workflow.mdx` — environments and server builds.\n- [Project operations](../processes/operations.md) — transcript handling and following the build.\n- [Feedback](../processes/feedback/index.md) — approved platform reports and run evaluations."]}),...s]};

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

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

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

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

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

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

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

@@ -0,0 +1 @@
+import{createPhoenixFeatureGuide as e}from"../guide.js";import{sdkGuidanceSections as n}from"../sdk-content.js";export const generatePhoenixInspectionFeature=()=>e({path:"features/inspection.md",title:"Inspection",summary:"Asset and live runtime inspection commands; read when checking models, scene, state, data or rendered output.",whenToUse:"Read when checking imported assets or investigating the running configurator. Runtime inspection needs dev running and the preview open in a browser.",capabilities:[n.assetInspection,n.screenshotCli,n.inspectState,n.inspectData,n.inspectScene,n.playwrightMcpSetup].join("\n\n"),example:"After changing a material, run `pnpm phoenix inspect:scene` to inspect the assigned material, then `pnpm phoenix screenshot -o ./render.png` to compare the rendered result. A canvas screenshot does not cover the surrounding interface.",documentation:"Read `docs/phoenix/phoenix-cli.mdx` with `pnpm phoenix docs -r docs/phoenix/phoenix-cli.mdx` for command flags and output contracts. Use the [review index](../processes/review/index.md) when deciding which evidence the change needs."});

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

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

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

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

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

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

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

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

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

@@ -0,0 +1,54 @@
+/**
+ * A Markdown document of the Phoenix skill, shipped beside its `SKILL.md`.
+ *
+ * Every document opens with its title as the only H1, and its parent index lists it by `title` and `summary`, so an
+ * agent decides from the index alone whether to read it. The factories below render the shared document shapes, so
+ * a guide follows the structure the skills architecture prescribes by construction rather than by review.
+ */
+export interface PhoenixGuide {
+    /** Path inside the skill folder, `/`-separated, such as `processes/review/code.md`. */
+    readonly path: string;
+    /** The document's name: its H1 and its entry in the parent index. */
+    readonly title: string;
+    /** What the document covers and when to read it, as one cell of the parent index. */
+    readonly summary: string;
+    readonly content: string;
+}
+interface PhoenixGuideHeader {
+    readonly path: string;
+    readonly title: string;
+    readonly summary: string;
+}
+/** A document organized by topic, such as a required core guide. */
+export interface PhoenixTopicGuideProps extends PhoenixGuideHeader {
+    /** Markdown sections after the H1, each usually opening with an H2. */
+    readonly sections: readonly string[];
+}
+/** A reusable procedure: its trigger, its steps, its completion boundary and one focused example. */
+export interface PhoenixProcessGuideProps extends PhoenixGuideHeader {
+    readonly whenToUse: string;
+    /** The procedure itself; topic subsections use H3. */
+    readonly steps: string;
+    readonly doneWhen: string;
+    readonly example: string;
+}
+/** What a Phoenix capability supports, when it fits, one focused example and its canonical documentation. */
+export interface PhoenixFeatureGuideProps extends PhoenixGuideHeader {
+    readonly whenToUse: string;
+    /** Supported usage and limits; topic subsections use H3. */
+    readonly capabilities: string;
+    readonly example: string;
+    readonly documentation: string;
+}
+/** A routing document: a short introduction and a table of its children with their summaries. */
+export interface PhoenixIndexGuideProps extends PhoenixGuideHeader {
+    readonly intro: string;
+    readonly guides: readonly PhoenixGuide[];
+    /** Markdown after the table, such as rules shared by every child or a topic map; empty when there is none. */
+    readonly notes: readonly string[];
+}
+export declare const createPhoenixTopicGuide: (props: PhoenixTopicGuideProps) => PhoenixGuide;
+export declare const createPhoenixProcessGuide: (props: PhoenixProcessGuideProps) => PhoenixGuide;
+export declare const createPhoenixFeatureGuide: (props: PhoenixFeatureGuideProps) => PhoenixGuide;
+export declare const createPhoenixIndexGuide: (props: PhoenixIndexGuideProps) => PhoenixGuide;
+export {};

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

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

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

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

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

@@ -1,7 +1,14 @@
-import{renderAgentSkill as e}from"./agent-skill.js";import{generatePhoenixCliSkill as t}from"./phoenix-cli-skill.js";import{generatePhoenixCreateConfiguratorSkill as n,generatePhoenixCreateConfiguratorSkillReferences as r}from"./phoenix-create-configurator-skill.js";import{generatePhoenixFeedbackSkill as i}from"./phoenix-feedback-skill.js";import{generatePhoenixReviewSkill as o}from"./phoenix-review-skill.js";import{generatePhoenixSkill as a}from"./phoenix-skill.js";import{generatePhoenixVariantsSkill as s}from"./phoenix-variants-skill.js";let l=(e,t,n)=>n.reduce((e,n)=>{let r="../".repeat(t.split("/").length-2),i=`[${n.title}](${r}${n.path.slice(11)})`;return e.replaceAll(`\`${n.name}\` skill`,i).replaceAll(`${n.name} skill`,i)},e),c=e=>{let t="\n---\n\n",n=e.content.indexOf(t),r=e.content.slice(0,n).split("\n").find(e=>e.startsWith("description: "));if(-1===n||void 0===r)throw Error(`Cannot emit the ${e.name} guide: its skill frontmatter is missing. Render it with renderAgentSkill.`);return{description:r.slice(13),body:e.content.slice(n+t.length)}};export const generatePhoenixSkillBundle=h=>{let p=[{name:"phoenix",title:"Project guidance",path:"references/project.md",content:a(h),references:[]},{name:"phoenix-create-configurator",title:"Configurator workflow",path:"references/create-configurator/guide.md",content:n(),references:r()},{name:"phoenix-cli",title:"CLI guide",path:"references/cli.md",content:t(),references:[]},{name:"phoenix-review",title:"Code review guide",path:"references/review.md",content:o(),references:[]},{name:"phoenix-variants",title:"Variants guide",path:"references/variants.md",content:s(),references:[]},{name:"phoenix-feedback",title:"Feedback guide",path:"references/feedback.md",content:i(),references:[]}];return{content:e({name:"phoenix",description:"Build, change, inspect, deploy or review a Phoenix configurator project. Use for Phoenix project work, visual alternatives, and platform feedback.",sections:[`# Phoenix
+import{renderAgentSkill as e}from"./agent-skill.js";import{generatePhoenixCliCore as o,generatePhoenixSdkCore as t,generatePhoenixWorkflowCore as r}from"./core/index.js";import{generatePhoenixFeatureGuides as n}from"./features/index.js";import{createPhoenixIndexGuide as s}from"./guide.js";import{generatePhoenixAssetConversion as i,generatePhoenixFeedbackGuides as a,generatePhoenixFinalization as d,generatePhoenixFirstDraftGuides as c,generatePhoenixModelMigration as h,generatePhoenixOperations as l,generatePhoenixPlanning as u,generatePhoenixReviewGuides as p,generatePhoenixSpecificationGuides as m}from"./processes/index.js";export const generatePhoenixSkillBundle=f=>{let w=[r(),t(),o()],g=[c(),m(),[u()],[l(f)],[d()],[i()],[h()],p(),a()],x=s({path:"processes/index.md",title:"Processes",summary:"Procedures summarized by outcome and when to use them.",intro:"Read the procedure or section whose outcome the task needs. The [workflow](../core/workflow.md) owns strategy, preferences and effort; processes supply the execution.",guides:g.flatMap(e=>e.slice(0,1)),notes:[]}),k=n();return{content:e({name:"phoenix",description:"Build, change, inspect, deploy or review a Phoenix configurator project. Use for all Phoenix project work, including a first draft of a new project, visual alternatives and platform feedback.",sections:[`# Phoenix
 
-Load the guides for the work in hand before doing that work. Several may apply. Follow their existing instructions; this entry point only routes to them. Reuse guidance already read in the conversation unless sync or an SDK update changed it.`,`## Choose the relevant guidance
+Use the required core to choose how to work, then load task details only when they apply.`,`## Required reading
 
-| When | Read |
-| --- | --- |
-${p.map(e=>`| ${c(e).description} | [${e.title}](${e.path}) |`).join("\n")}`,"The workflow guide links to product discovery, asset conversion, UX guidance and appearance review at the stages that use them. An isolated code fix needs project guidance and the applicable CLI/review guides; it does not restart the configurator workflow.\n\nEarlier Phoenix skill names refer to these guides: ask for the same task through `phoenix`. Read linked documents when their task applies, not the whole reference tree."]}),references:p.flatMap(e=>[{path:e.path,content:l(c(e).body,e.path,p)},...e.references.map(t=>{let n=`${e.path.slice(0,e.path.lastIndexOf("/")+1)}${t.path}`;return{path:n,content:l(t.content,n,p)}})])}};
+Before Phoenix work, read these three core guides in order:
+
+${w.map((e,o)=>`${o+1}. [${e.title}](${e.path}) — ${e.summary}.`).join("\n")}
+
+The core governs every task; reading the workflow does not mean executing every stage. Reuse the core while it remains in context and unchanged, and read it again when context is lost or sync or an SDK update changes it.`,`## Optional guidance
+
+- [Processes](processes/index.md) — procedures summarized by outcome and when to use them.
+- [Features](features/index.md) — what Phoenix capabilities support, their constraints and canonical SDK documentation.
+
+Follow only the destinations the task needs; a link does not require reading its whole subtree.`]}),references:[...w,x,...g.flat(),...k].map(({path:e,content:o})=>({path:e,content:o}))}};

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

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