@salsita-ai/sdk 0.50.0-develop.ae9a830ef0 → 0.50.0-develop.afbc5157e1

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

@@ -0,0 +1,88 @@
+import{createPhoenixFeatureGuide as e}from"../../../guide.js";let t=`The quote goes to the CRM, a cart when the configurator runs in the shop, and a row in the sales spreadsheet, each skipped when it does not apply:
+
+\`\`\`ts
+// src/webhooks/tasks/integrations.ts
+export const crmQuoteTask = phx.webhooks.taskFactory.createSendHttpRequestTask((_resources, data, ctx) => {
+  const chair = ctx.domain.getRoot$Entity(data.state)
+
+  return {
+    type: 'SendHttpRequest',
+    url: \`\${phx.webhooksEnv.CRM_API_URL}/quotes\`,
+    method: 'POST',
+    headers: { authorization: \`Bearer \${phx.webhooksEnv.CRM_API_TOKEN}\`, 'content-type': 'application/json' },
+    body: JSON.stringify({
+      quoteNumber: data.prefetchedData.quoteNumber,
+      configurationId: data.configurationId,
+      model: chair.label,
+      finish: chair.finish,
+    }),
+  }
+})
+
+export const cartTask = phx.webhooks.taskFactory.createWooCommerceAddToCartTask((resources, data, ctx) => {
+  const { cartSession, addToCartUrl } = data.finalizeData
+  const shopUrl = phx.webhooksEnv.WOOCOMMERCE_SHOP_URL
+  const apiKey = phx.webhooksEnv.WOOCOMMERCE_API_KEY
+
+  if (cartSession === undefined || addToCartUrl === undefined || shopUrl === undefined || apiKey === undefined) {
+    return null
+  }
+
+  // The platform sends the API key to this URL, so it may only point at the shop
+  const cartEndpoint = new URL(addToCartUrl, shopUrl)
+
+  if (cartEndpoint.origin !== new URL(shopUrl).origin) {
+    throw new Error(
+      \`The add-to-cart URL \${addToCartUrl} is not on the shop \${shopUrl}. Pass the plugin's add-to-cart-url unchanged.\`
+    )
+  }
+
+  const chair = ctx.domain.getRoot$Entity(data.state)
+
+  return {
+    type: 'WooCommerceAddToCart',
+    session: cartSession,
+    addToCartUrl: cartEndpoint.href,
+    apiKey,
+    items: [
+      {
+        product: 'custom-chair',
+        productName: chair.label,
+        productDescription: \`\${chair.finish}, \${chair.width} cm\`,
+        quantity: 1,
+        image: resources.studioRender,
+        resources: [{ type: 'Pdf', name: resources.quotePdf, label: 'Quote' }],
+      },
+    ],
+  }
+})
+
+export const quoteSheetTask = phx.webhooks.taskFactory.createEditGoogleSpreadsheetTask((resources, data, ctx) => {
+  const spreadsheetId = phx.webhooksEnv.QUOTES_SPREADSHEET_ID
+  const serviceAccount = phx.webhooksEnv.GOOGLE_SERVICE_ACCOUNT_JSON
+
+  if (spreadsheetId === undefined || serviceAccount === undefined) {
+    return null
+  }
+
+  const chair = ctx.domain.getRoot$Entity(data.state)
+
+  return {
+    type: 'EditGoogleSpreadsheet',
+    credentials: JSON.parse(serviceAccount),
+    spreadsheetId,
+    edits: [
+      {
+        mode: 'append',
+        ranges: {
+          'Quotes!A:D': [
+            [data.prefetchedData.quoteNumber, chair.label, chair.width, { type: 'ConfigurationLink', name: resources.shareLink }],
+          ],
+        },
+      },
+    ],
+  }
+})
+\`\`\`
+
+The [finalize handler](../finalization.md) registers each with \`.withTask\`.`;export const generatePhoenixIntegrationsFeature=()=>e({path:"features/webhooks/tasks/integrations.md",title:"HTTP, WooCommerce and Google Sheets",summary:"`SendHttpRequest`, `WooCommerceAddToCart`, `EditGoogleSpreadsheet` and the generic `createTask`; read when finalization sends the configuration to another system.",whenToUse:"Read when finalization posts to a CRM or ERP, adds the configuration to a WooCommerce cart or records it in a Google spreadsheet. Agree with the client before connecting a live system.",capabilities:"### HTTP request\n\n- `SendHttpRequest` sends `url` with `method` (`GET` by default), `headers` and a string `body` from the platform, after the emails. A body needs a method other than `GET`.\n- An answer outside 2xx fails the finalization. There is no timeout and no retry, and a request already sent is not undone, so make the receiving endpoint tolerate a repeated quote number.\n- The request carries no generated files. When the other system needs the PDF or a link, send it from the [callback](callback.md) handler, which receives their links, or let the other system fetch them.\n\n### WooCommerce cart\n\n- `WooCommerceAddToCart` adds `items` and optional `fees` to the shopper's cart through the Phoenix WordPress plugin. An item has a `product`, and optionally `productName`, `productDescription`, `price`, `quantity`, `customData`, an `image` given as the name of a declared `Image` resource, and `resources` listed in the order as `{ type, name, label }`.\n- The plugin gives the configurator tag an encrypted `session` and an `add-to-cart-url` relative to the shop; pass both unchanged in the finalize data. `apiKey` is the key configured in the plugin, kept in a webhook variable.\n- The platform sends the API key to `addToCartUrl`, and the finalize data comes from the browser. Build the absolute URL in the webhook from the shop's URL in a webhook variable, and refuse any other origin, or anyone could have the key sent to a server of their choosing.\n\n### Google Sheets\n\n- `EditGoogleSpreadsheet` appends rows to, or overwrites, ranges of a spreadsheet with a service account: `credentials` is the parsed service-account key, `spreadsheetId` the id from its URL, and each edit maps A1 ranges to rows with `mode` `append` or `overwrite`.\n- Share the spreadsheet with the service account's email. Cells take strings, numbers, booleans and `{ type: 'ConfigurationLink', name }`, and are written exactly as given.\n\n### Any task\n\n- `phx.webhooks.taskFactory.createTask` accepts a handler returning any task type the project can build, for one handler that returns different kinds of tasks.\n- Keep each credential in a webhook variable ([Webhook entry and environment](../entry-and-environment.md)). The platform keeps a task's fields with its job record, also after the job finishes, so prefer keys scoped to the one integration.",example:t,documentation:"Read with `pnpm phoenix docs -r <path>`:\n\n- `docs/phoenix/webhooks.mdx` — the task fields of each integration.\n- `docs/integrations/woocommerce/overview.mdx` — the WordPress plugin, the attributes it passes and its API key.",phxMembers:[]});

package/dist/application-spec/generate-application/code/templates/skills/features/webhooks/tasks/links-and-images.d.ts

@@ -0,0 +1,3 @@
+import { type PhoenixGuide } from '../../../guide.js';
+/** Configuration links, server-rendered images and resources declared at runtime. */
+export declare const generatePhoenixLinksAndImagesFeature: () => PhoenixGuide;

package/dist/application-spec/generate-application/code/templates/skills/features/webhooks/tasks/links-and-images.js

@@ -0,0 +1,68 @@
+import{createPhoenixFeatureGuide as e}from"../../../guide.js";let t=`A share link frozen at the finalized revision, valid for 30 days, and a studio render of the configured chair:
+
+\`\`\`ts
+// src/webhooks/tasks/links-and-images.ts
+export const shareLinkTask = phx.webhooks.taskFactory.createGenerateConfigurationLinkTask((resources, data) => ({
+  type: 'GenerateConfigurationLink',
+  name: resources.shareLink,
+  frontendUrl: data.frontendUrl,
+  configurationId: data.configurationId,
+  revisionId: data.revisionId,
+  access: 'rr',
+  expiration: 30 * 24,
+}))
+
+export const studioRenderTask = phx.webhooks.taskFactory.createGenerateImagesTask((resources, data, ctx) => {
+  const view = ctx.blenderProjections.getBlenderImageConfig(data.state, 'Studio', data.state.rootEntityId, {
+    width: 1600,
+    height: 1200,
+  })
+
+  return {
+    type: 'GenerateImages',
+    deploymentId: data.deploymentId,
+    blenderSetupTemplate: 'blender/studio.blend',
+    templateFiles: ['models/chair.glb'],
+    images: [{ name: resources.studioRender, fileFormat: 'PNG', ...view }],
+  }
+})
+\`\`\`
+
+One render per view ticked in the finalize form, each view an export state, declared at runtime and produced by one task:
+
+\`\`\`ts
+// src/webhooks/tasks/view-renders.ts
+// The views the finalize form offers, each an export state; finalize data comes from the browser, so keep only these
+const VIEWS = ['Front', 'Side', 'Top']
+const renderName = (view: string) => \`view-\${view}\`
+const selectedViews = (views: readonly string[] | undefined) => VIEWS.filter(view => views?.includes(view))
+
+export const viewRenderResources = phx.webhooks.dynamicResourcesFactory.createGeneratedImage((_resources, data) =>
+  selectedViews(data.finalizeData.views).map(view => ({ type: 'Image', name: renderName(view), s3Key: \`\${renderName(view)}.jpg\` }))
+)
+
+export const viewRendersTask = phx.webhooks.taskFactory.createGenerateImagesTask((_resources, data, ctx) => {
+  const views = selectedViews(data.finalizeData.views)
+
+  if (views.length === 0) {
+    return null
+  }
+
+  return {
+    type: 'GenerateImages',
+    deploymentId: data.deploymentId,
+    blenderSetupTemplate: 'blender/studio.blend',
+    templateFiles: ['models/chair.glb'],
+    images: views.map(view => ({
+      name: renderName(view),
+      fileFormat: 'JPEG',
+      ...ctx.blenderProjections.getBlenderImageConfig(data.state, view, data.state.rootEntityId, {
+        width: 800,
+        height: 800,
+      }),
+    })),
+  }
+})
+\`\`\`
+
+The [finalize handler](../finalization.md) registers them with \`.withResources(viewRenderResources)\` and \`.withTask(viewRendersTask)\`.`;export const generatePhoenixLinksAndImagesFeature=()=>e({path:"features/webhooks/tasks/links-and-images.md",title:"Links and images",summary:"`GenerateConfigurationLink`, `GenerateImages` with Blender, configurator-rendered images and resources declared at runtime; read when finalization shares the configuration or shows it in a picture.",whenToUse:"Read when finalization produces a link to the configuration or an image of it, or when the number of produced files depends on the configuration.",capabilities:"### Configuration links\n\n- `GenerateConfigurationLink` produces a link to the saved configuration under a declared `ConfigurationLink` resource, which PDFs, emails, spreadsheets and the callback include.\n- `access` decides what the link opens: `o` the configuration itself with edit rights, permanently; `rr` the finalized revision in read mode, unaffected by later edits; `r` the latest revision, refused on save but with the editing interface still shown. Pass `revisionId` for `rr` and `r`.\n- `expiration` is in hours; without it a link never expires, and an `o` link never does.\n\n### Server-rendered images\n\n- `GenerateImages` renders one or more images in Blender from the configured state, each under a declared `Image` resource with an `s3Key`. [Scene objects](../../scene-objects.md) and the 3D components decide what the scene holds.\n- `ctx.blenderProjections.getBlenderImageConfig(data.state, exportState, entityId, { width, height })` returns the camera, rendered entities and lights of an export state; spread it into the image.\n- `blenderSetupTemplate`, `templateFiles` and an optional `blenderPythonScriptName` are paths under `assets/private/`, uploaded with the deploy. The engine saved in the template renders the image, so choose it there: EEVEE renders faster, Cycles more realistically.\n- Renders queue one after another across the platform and can take minutes. The configurator waits with a `pollingTimeout` long enough for them ([Finalization](../finalization.md)).\n- Images the configurator renders itself, described in `docs/other-features/client-side-rendering/declarative.mdx`, need no server render and suit PDFs and email attachments that only show the current view.\n\n### Resources declared at runtime\n\n- When the number of resources depends on the configuration, return them from a `phx.webhooks.dynamicResourcesFactory` handler registered with `withResources`: `createGeneratedImage`, `createClientGeneratedImage`, `createExistingImage`, `createLink`, `createPdf`, `createCsv` or `createResource`. Their names are plain strings, unchecked until finalization runs.\n- `getClientSideImageResourceName(entityId, instanceName)` names the resource of a configurator-rendered image.",example:t,documentation:"Read with `pnpm phoenix docs -r <path>`:\n\n- `docs/phoenix/sharing.mdx` — access levels and link generation.\n- `docs/phoenix/blender-rendering.mdx` — the Blender template, materials, lights, cameras, render settings and assets.\n- `docs/other-features/client-side-rendering/declarative.mdx` — configurator-rendered images in PDFs and emails.",phxMembers:["webhooks.dynamicResourcesFactory"]});

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

@@ -0,0 +1,3 @@
+import { type PhoenixGuide } from '../../../guide.js';
+/** The finalization tasks index followed by its guides, grouped by what the tasks produce. */
+export declare const generatePhoenixTaskGuides: () => readonly PhoenixGuide[];

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

@@ -0,0 +1 @@
+import{createPhoenixIndexGuide as e}from"../../../guide.js";import{generatePhoenixCallbackFeature as t}from"./callback.js";import{generatePhoenixDocumentsFeature as a}from"./documents.js";import{generatePhoenixEmailFeature as i}from"./email.js";import{generatePhoenixIntegrationsFeature as n}from"./integrations.js";import{generatePhoenixLinksAndImagesFeature as s}from"./links-and-images.js";export const generatePhoenixTaskGuides=()=>{let o=[s(),a(),i(),n(),t()];return[e({path:"features/webhooks/tasks/index.md",title:"Finalization tasks",summary:"Every task type finalization can run — links, images, PDFs, CSVs, emails, HTTP requests, WooCommerce, Google Sheets and the callback — grouped by what they produce; read when choosing or building a task.",intro:"A task is one thing the platform does after a finalization. The [finalize handler](../finalization.md) builds tasks with `phx.webhooks.taskFactory`, connects them through named resources and leaves their order to the platform, which runs them by type. Read only the guide for the task at hand.\n\n- Built by the project: `GenerateConfigurationLink` and `GenerateImages` (links and images), `GenerateStaticPdf`, `GeneratePdf` and `GenerateCsv` (documents), `SendStaticEmail` and `SendEmail` (email), `SendHttpRequest`, `WooCommerceAddToCart` and `EditGoogleSpreadsheet` (integrations), and `CallLambdaBack` (callback).\n- Built by the SDK when Project Admin publishes: `PublishRevision`, `PublishRevisionChunks` and `PublishRevisionChunksStaged` ([Admin publishing](../publishing.md)).",guides:o,notes:[]}),...o]};

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

@@ -0,0 +1,3 @@
+import { type PhoenixGuide } from '../../guide.js';
+/** The webhooks index followed by its guides: the entry, one guide per hook and the finalization tasks. */
+export declare const generatePhoenixWebhooksGuides: () => readonly PhoenixGuide[];

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

@@ -0,0 +1 @@
+import{createPhoenixIndexGuide as e}from"../../guide.js";import{generatePhoenixAssistantSetupFeature as t}from"./assistant-setup.js";import{generatePhoenixWebhookAuthenticationFeature as n}from"./authentication.js";import{generatePhoenixWebhookBackendDataFeature as o}from"./backend-data.js";import{generatePhoenixWebhookEntryFeature as i}from"./entry-and-environment.js";import{generatePhoenixWebhookFinalizationFeature as a}from"./finalization.js";import{generatePhoenixPublishingFeature as r}from"./publishing.js";import{generatePhoenixTaskGuides as s}from"./tasks/index.js";export const generatePhoenixWebhooksGuides=()=>{let h=s(),d=[i(),n(),o(),a(),...h.slice(0,1),r(),t()];return[e({path:"features/webhooks/index.md",title:"Webhooks",summary:"Server-side project code: the webhook entry and environment, sign-in, backend data, finalization and its tasks, Admin publishing and assistant setup; read when the configurator needs the server.",intro:"The webhook is the project's server side: `src/webhooks/index.ts` and the handler modules that join it run on the platform and hold the project's credentials, which never reach the browser. The platform calls it to sign configurator users in, to fetch backend data, to finalize a configuration and return its result, to publish Admin content and to set up the assistant. Start from [Webhook entry and environment](entry-and-environment.md), then read only the guide for the hook at hand.",guides:d,notes:["## The examples\n\nThe guides build one quote configurator for a `Chair` with a `label`, a `finish` and a `width`: each example is a file of that project, and the files fit together. Take the pattern, not the names."]}),...d,...h.slice(1)]};

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

@@ -0,0 +1,68 @@
+/**
+ * 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;
+    /** The `phx` members this document is the home of; only feature guides teach members, every other document none. */
+    readonly phxMembers: readonly PhxMemberName[];
+}
+/**
+ * A member of the `phx` global a generated project declares, named by its namespace and member, such as
+ * `frontend.useTabNavigation` or `domain.implementActions`.
+ *
+ * The `phx` global is the public interface the guidance teaches. Every member has exactly one feature guide as its
+ * home, which teaches it as `phx.<namespace>.<member>`, or a recorded reason why no guide teaches it yet.
+ */
+export type PhxMemberName = `${PhxNamespace}.${string}`;
+/** The namespaces of the `phx` global. */
+export type PhxNamespace = 'frontend' | 'domain' | 'webhooks' | 'applicationTypes';
+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;
+    /** The `phx` members this guide is the home of; its content teaches each as `phx.<namespace>.<member>`. */
+    readonly phxMembers: readonly PhxMemberName[];
+}
+/** 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 e=(e,t)=>`${[`# ${e}`,...t.map(e=>e.trim())].join("\n\n")}
+`;export const createPhoenixTopicGuide=t=>{let{path:n,title:r,summary:i,sections:o}=t;return{path:n,title:r,summary:i,content:e(r,o),phxMembers:[]}};export const createPhoenixProcessGuide=t=>{let{path:n,title:r,summary:i,whenToUse:o,steps:s,doneWhen:a,example:c}=t;return{path:n,title:r,summary:i,phxMembers:[],content:e(r,[`## When to use
+
+${o.trim()}`,`## Steps
+
+${s.trim()}`,`## Done when
+
+${a.trim()}`,`## Example
+
+${c.trim()}`])}};export const createPhoenixFeatureGuide=t=>{let{path:n,title:r,summary:i,whenToUse:o,capabilities:s,example:a,documentation:c,phxMembers:m}=t;return{path:n,title:r,summary:i,phxMembers:m,content:e(r,[`## When to use
+
+${o.trim()}`,`## Capabilities and constraints
+
+${s.trim()}`,`## Example
+
+${a.trim()}`,`## Documentation
+
+${c.trim()}`])}};export const createPhoenixIndexGuide=t=>{let{path:n,title:r,summary:i,intro:o,guides:s,notes:a}=t,c=s.map(e=>`| [${e.title}](${((e,t)=>{let n=e.split("/").slice(0,-1),r=t.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,e.path)}) | ${e.summary} |`);return{path:n,title:r,summary:i,phxMembers:[],content:e(r,[o,["| Document | What it covers and when to read it |","| --- | --- |",...c].join("\n"),...a])}};

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

@@ -0,0 +1,10 @@
+import { type AgentSkillReference } from './agent-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[];
+}
+/** 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

@@ -0,0 +1,14 @@
+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,generatePhoenixBeta as a,generatePhoenixFeedbackGuides as d,generatePhoenixFinalization as c,generatePhoenixFirstDraftGuides as h,generatePhoenixModelMigration as l,generatePhoenixReviewGuides as u,generatePhoenixSpecificationGuides as p}from"./processes/index.js";export const generatePhoenixSkillBundle=m=>{let f=[r(),t(),o()],w=[h(),p(),[c()],[i()],[l()],u(),d(),[a(m)]],g=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:w.flatMap(e=>e.slice(0,1)),notes:[]}),x=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
+
+Use the required core to choose how to work, then load task details only when they apply.`,`## Required reading
+
+Before Phoenix work, read these three core guides in order:
+
+${f.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:[...f,g,...w.flat(),...x].map(({path:e,content:o})=>({path:e,content:o}))}};

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

@@ -0,0 +1,9 @@
+import { type PhxMemberName } from './guide.js';
+/**
+ * The `phx` members no feature guide teaches yet, each with the reason.
+ *
+ * Every other member that is not deprecated has exactly one feature guide as its home, which declares it in its
+ * `phxMembers`; deprecated members are never mentioned. The list only shrinks: a new member gets a home or an entry
+ * here with its reason, and a guide that starts teaching a member removes its entry.
+ */
+export declare const phxMembersWithoutGuide: Readonly<Partial<Record<PhxMemberName, string>>>;

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

@@ -0,0 +1 @@
+let e="Planned guide: lifecycle providers, handlers and runtime services.",n="Planned guide: integration modes and embedding.",t="Planned guide: theming and icon sets.",a="Planned guide: Admin.",i="Planned guide: data sources and finalization data types.";export const phxMembersWithoutGuide={"frontend.usePropertyPageStack":"Not taught: guidance renders controls from the project layout, not YAML property pages.","frontend.usePropertyPageState":"Not taught: guidance renders controls from the project layout, not YAML property pages.","frontend.useSessionService":"Internal: the session service for initialization code.","frontend.createOnApplicationStartProvider":e,"frontend.createOnSessionReadyProvider":e,"frontend.createOnPublishedDataReadyProvider":e,"frontend.createOnFrontendDataReadyProvider":e,"frontend.createOnBackendDataReadyProvider":e,"frontend.createOnRoutingReadyProvider":e,"frontend.createOnConfiguratorReadyProvider":`${e} Navigation states mentions it for mounting listeners.`,"frontend.createCollectFrontendDataHandler":e,"frontend.createFilterPublishedChunksHandler":e,"frontend.createGetTextureProcessingMapHandler":e,"frontend.useAnalytics":e,"frontend.useAuthenticatedClient":e,"frontend.useAuthorizedClient":`${e} Finalization actions mentions its finalize call.`,"frontend.useCreateAuthorizedClient":e,"frontend.useSession":`${e} Presets mentions it for reading the session role.`,"frontend.useDomainApplication":`${e} Presets mentions it for saving before leaving.`,"frontend.useConfigurator":e,"frontend.useDomainApplicationProps":e,"frontend.createGetWebComponentOptionsHandler":n,"frontend.useIntegrationService":n,"frontend.useIntegrationState":n,"frontend.useRecipeEmbeddedState":n,"frontend.usePresetEmbeddedState":n,"frontend.createGetThemeHandler":t,"frontend.createPhoenixIconSet":t,"frontend.useEntityPrice":"Planned guides: specific component kinds, such as the price component.","frontend.admin":a,"domain.admin":`${a} Admin publishing teaches its publishing and validation handlers.`,"applicationTypes.ApplicationVersion":i,"applicationTypes.PublishedDataHash":i,"applicationTypes.PublishedData":i,"applicationTypes.SessionData":i,"applicationTypes.FrontendData":i,"applicationTypes.BackendData":i,"applicationTypes.FinalizeData":i,"applicationTypes.PrefetchedFinalizeData":i,"applicationTypes.FinalizeResult":i,"applicationTypes.CallbackData":i,"applicationTypes.ExportState":"Planned guide: the 3D scene and image export.","applicationTypes.AdminNavigationState":a};

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;

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

@@ -0,0 +1,23 @@
+import{createPhoenixProcessGuide as e}from"../guide.js";let t=`Conversion is part of the product's appearance, not a preliminary chore: a converted model that is misplaced, incomplete or stripped of its detail is a visible defect, and the client sees it before anything else.
+
+### Write a script, not a sequence of one-off fixes
+
+Convert every model with one re-runnable script, committed to the project and parameterized per model. Do not repair a file by hand. A correction discovered on the first model must be in the script before the next model is converted, or it is lost: repairs made interactively do not survive the batch that follows. Record in the project record which tool chain the script uses and what each step does, so the conversion can be rerun when a source file changes.
+
+### What a converted model must satisfy
+
+- **Ground contact** — the model's lowest geometry is where the product touches the floor, and it sits at the scene's floor height without a hand-computed vertical offset. A constant that has to agree with a separately placed floor eventually disagrees with it.
+- **Completeness** — every sub-assembly that belongs to the product is present, and nothing else is: no detached fragments, no parts protruding through an outer surface, no leftover rig or construction geometry.
+- **Assembly** — parts that belong together are positioned together. Source files often store sub-assemblies at their own offsets; re-seat them against the part they attach to, not against the file's origin.
+- **Scale and orientation** — dimensions match the published figures for that product, and the model faces the same way as every other model in the set. Report any divergence from the published figures rather than silently adopting the model's.
+- **Separable materials** — parts users can configure independently carry their own materials, so a control can reach them.
+- **Material class** — a part the project gives a clearcoat needs one in the converted model already. Phoenix's clearcoat overrides act on \`MeshPhysicalMaterial\`, and three.js creates that class only when the glTF declares \`KHR_materials_clearcoat\`; on a plain \`MeshStandardMaterial\` the overrides are accepted and silently do nothing. Export painted and lacquered parts with a clearcoat value, however small, so the extension is present for the override to act on.
+
+### Detail budget
+
+Reduce geometry per part, never uniformly across a model. A single ratio removes almost nothing from large flat panels and destroys small curved parts, which are usually the ones nearest the camera. Keep full detail on parts that are small, curved and always visible, such as castors, handles, pulls and hinges, and spend the budget on large simple surfaces instead. After reducing, look at the affected parts at the default camera distance, not only at a distance that flatters them.
+
+### Verify every model, not the first one
+
+Inspect each converted model with the [asset inspection](../features/inspection.md) tooling, and check every requirement above for every model in the set. A batch that reuses a script verified on one file still needs each result looked at: source files in one delivery frequently differ in origin, scale and structure.`,r=`- Every model in scope is converted by the committed script and inspected against each requirement.
+- Divergences from published figures are reported to the client, not silently adopted.`;export const generatePhoenixAssetConversion=()=>e({path:"processes/asset-conversion.md",title:"Asset conversion",summary:"Convert and verify supplied 3D models with a reproducible script; read when supplied models need conversion or repair before configuration.",whenToUse:"When supplied models need conversion or repair before they can be configured. A [first draft](first-draft/direction.md) converts only its representative model, or builds a labeled stand-in when no model is supplied.",steps:t,doneWhen:r,example:"For a set of chairs, parameterize the conversion for the source units, the ground contact and separately configurable upholstery and frame materials. Run the same script for every supplied chair and inspect each output; a valid first model does not validate the rest."});

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

@@ -0,0 +1,14 @@
+import { type PhoenixGuide } from '../guide.js';
+export interface PhoenixSkillOptions {
+    readonly checkLatestCanary: boolean;
+}
+/**
+ * Whether a project follows the canary builds: it installs the SDK from npm, and the build it was generated by is
+ * itself a canary. A workspace project follows the local SDK, a stable release stays on releases, and a PR beta
+ * (`<version>-pr-<n>.<sha>`) is the build under test, so none of them may be moved onto canary.
+ */
+export declare const followsCanaryBuilds: (project: {
+    readonly useWorkspace: boolean;
+    readonly sdkVersion: string;
+}) => boolean;
+export declare const generatePhoenixBeta: ({ checkLatestCanary }: PhoenixSkillOptions) => PhoenixGuide;

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

@@ -0,0 +1,4 @@
+import{createPhoenixProcessGuide as e}from"../guide.js";let t=`### Ask for the run evaluation
+
+The Phoenix team relies on clients' evaluations during the beta. When a deploy reports the configurator live and the client has nothing more to build, ask whether they will rate the run, and follow [Evaluate the run](feedback/evaluate.md) when they agree. Ask once per conversation, not after a deploy that failed and not while the client wants to continue; a later deploy in the same conversation does not ask again.`;export const followsCanaryBuilds=e=>!e.useWorkspace&&e.sdkVersion.includes("-develop.");export const generatePhoenixBeta=({checkLatestCanary:n})=>e({path:"processes/beta.md",title:"Beta",summary:`What the internal beta adds: ${n?"keeping this canary project on the newest SDK build, ":""}the conversation log that goes with each deploy and asking for the run evaluation; read ${n?"once per conversation before changing anything, ":""}before each deploy and when a deploy goes live.`,whenToUse:`Phoenix is in an internal beta, so this applies to every project: ${n?"once per conversation before changing anything, ":""}before each \`phoenix deploy\` and when a deploy goes live. Everything here ends with the beta.`,steps:[...n?["### Stay on the latest canary\n\nThis project uses the `canary` build of the SDK, which is published from every change to the platform. Once per conversation, before changing anything, compare the installed version, the `version` in `node_modules/@salsita-ai/sdk/package.json`, with the newest canary:\n\n```bash\nnpm view @salsita-ai/sdk@canary version\n```\n\nWhen they differ, tell the client which version the project moves to, then install that exact version, bring the packages it needs in line and regenerate the project files:\n\n```bash\npnpm add @salsita-ai/sdk@<version> && pnpm phoenix deps && pnpm install && pnpm phoenix sync\n```\n\nInstall the version npm reported rather than the `@canary` tag: a package manager's cached registry data can keep the old build while reporting success. Sync rewrites the Phoenix skills, so read the guides in use again afterwards. When the client runs a globally installed `phoenix`, update it too with `npm install -g @salsita-ai/sdk@<version>`. When the project no longer builds after the update, tell the client and report it with [Feedback](feedback/index.md)."]:[],"### Share the conversation log\n\nDuring the beta each deploy carries the conversation, so the Phoenix team can learn from the run. Immediately before running `pnpm phoenix deploy`, refresh `conversation.log` in the project root with the current conversation. Prefer the agent application's native session export when available; do not invent an export command or scan unrelated sessions. Otherwise write the messages still available in context and label the log `reconstructed; incomplete`. Never present a compaction summary as verbatim earlier messages.\n\nUse UTF-8 text with a header naming the agent, export time, source (native export or reconstructed), covered session and known omissions. Preserve the client's and the agent's messages in chronological order, plus tool names, arguments and results when available; label text the agent application injected, such as loaded skills or task notifications, as what it is rather than as the client's. Keep each tool result to at most 16 KiB of text and mark truncation explicitly; describe image attachments by reference rather than embedding binary or base64 data. Exclude internal instructions, hidden reasoning, credentials and unrelated sensitive content; mark redactions without repeating the removed content. Refresh the current session's log rather than appending duplicate copies or carrying over a previous session.\n\nShow the client the exact file to review or redact, and get their approval to include it before the deploy that sends it. A log refreshed for a later deploy is a new file and needs a new yes; showing only what was added since the approved version keeps that quick. When they decline, move it out of the project root before deploying so it cannot be collected, and keep it out for the rest of the conversation unless they change their mind. Deploy includes the file in the build's private source archive, downloadable by those authorized to download that build's sources, and leaves it out of build inputs. A missing log warns but does not block deployment.",t].join("\n\n"),doneWhen:`${n?"- The project is on the newest canary build, or the client knows why it is not.\n":""}- Each deploy carried a conversation log the client approved in that version, or none.
+- After a live deploy with nothing more to build, the client was asked once for the run evaluation.`,example:'Before the first deploy, refresh `conversation.log` and show it to the client: "This log of our conversation goes with the build, visible only to people who can download its sources. Shall I include it?" After the deploy goes live and the client says they are done for now, ask whether they will rate the run.'});

package/dist/application-spec/generate-application/code/templates/skills/processes/feedback/evaluate.d.ts

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

package/dist/application-spec/generate-application/code/templates/skills/processes/feedback/evaluate.js

@@ -0,0 +1,38 @@
+import{createPhoenixProcessGuide as e}from"../../guide.js";let t=`### Interview the client
+
+Say first that the answers go to the Phoenix team as feedback, and that the client can decline. Then ask one question at a time, in this order, and wait for each answer before asking the next. Give the short explanation with each question. Every score is a whole number from 0 to 10, where 0 is catastrophic, 5 is passable and 10 is amazing:
+
+1. **Minutes spent** — roughly how many minutes the client spent on the run, from the first prompt to now. This one is a number of minutes, not a score.
+2. **Agent guidance** — how clear it was what to expect and what to do, how clearly the agent explained itself, and how well the client understood the consequences of their choices.
+3. **Functionality** — how complete the configurator is: whether it configures the full product with all its options, keeps users from creating or submitting a wrong configuration, and offers a way to finalize one.
+4. **UX** — how easy the configurator is to understand and operate, how clear the choices are, and how understandable incompatibilities and the ways to resolve them are.
+5. **3D quality** — how realistic and attractive the configured object and its scene are: shapes, textures, surroundings, lighting and shadows.
+6. **UI visuals** — how good the user interface looks.
+7. **Overall** — the client's subjective verdict on the configurator as a whole.
+8. **Comments** — anything else about the experience, in their own words. This one is free text and may be empty.
+
+Rules of the interview:
+
+- Never choose, guess or adjust a score, and never answer a question for the client. When they skip one, write \`skipped\` for it.
+- When the client declines the evaluation, send nothing and do not ask again.
+
+### Compose the evaluation
+
+Compose the evaluation from the answers with exactly these labels, one per line, in this order. Write \`none\` when there are no comments, and fill \`Build\` and \`Configurator\` as [Report a problem](report.md) describes:
+
+\`\`\`text
+Evaluation
+Minutes spent: <minutes>
+Agent guidance: <score>/10
+Functionality: <score>/10
+UX: <score>/10
+3D quality: <score>/10
+UI visuals: <score>/10
+Overall: <score>/10
+Comments: <their comments, or none>
+Build: <build id> <Studio build page link>
+Configurator: <live configurator link>
+\`\`\`
+
+Keep the labels and their order, so the scores can be read out of the feedback list and its export. Send it with \`--type other\` through [Approve and send](send.md). An evaluation is not a bug report: when a comment names a concrete problem, offer to draft it as its own report.`,n=`- The client answered or skipped every question, or declined the evaluation.
+- An accepted evaluation went through [Approve and send](send.md) with every label in order.`;export const generatePhoenixFeedbackEvaluation=()=>e({path:"processes/feedback/evaluate.md",title:"Evaluate the run",summary:"An interview of the client about the run, recorded without invented scores; read when the client wants to rate the run.",whenToUse:"When the client wants to tell the Phoenix team how the run went, usually once their work on the configurator is finished. Not while they want to continue building.",steps:t,doneWhen:n,example:"When the client skips the UX score, record `UX: skipped`; when they decline the evaluation, send nothing. Use [Approve and send](send.md) only for an evaluation they accepted."});

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

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

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

@@ -0,0 +1 @@
+import{createPhoenixIndexGuide as e}from"../../guide.js";import{generatePhoenixFeedbackEvaluation as o}from"./evaluate.js";import{generatePhoenixFeedbackReport as r}from"./report.js";import{generatePhoenixFeedbackSending as t}from"./send.js";export const generatePhoenixFeedbackGuides=()=>{let n=[r(),o(),t()];return[e({path:"processes/feedback/index.md",title:"Feedback",summary:"Run evaluations and verified Phoenix problem reports, sent only with approval; read when the client wants to rate the run, or for SDK bugs, misleading guidance and missing capabilities.",intro:"Choose the outcome and load only its procedure. Sending always goes through [Approve and send](send.md).",guides:n,notes:[]}),...n]};

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

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

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

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

package/dist/application-spec/generate-application/code/templates/skills/processes/feedback/report.d.ts

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

package/dist/application-spec/generate-application/code/templates/skills/processes/feedback/report.js

@@ -0,0 +1,7 @@
+import{createPhoenixProcessGuide as e}from"../../guide.js";let t=`Draft feedback for the Phoenix team when one of these happens while working in this project:
+
+- **Bug** — the SDK, the \`phoenix\` CLI or generated code crashes, produces wrong output or behaves differently from its documentation, and the cause is not in this project's own code.
+- **Misleading guidance** — a doc page, a Phoenix guide or an error message pointed the wrong way, or did not say what was needed.
+- **Missing feature** — something the SDK does not support forced a workaround, or a routine task took far more steps than it should.
+
+Do not draft feedback for problems in this project's own specs or code, for a suspicion that is not checked, or twice for the same problem. For a finished run, use [Evaluate the run](evaluate.md) instead.`;export const generatePhoenixFeedbackReport=()=>e({path:"processes/feedback/report.md",title:"Report a problem",summary:"A verified SDK bug, misleading guidance or missing capability, drafted for the Phoenix team; read when such a problem affects the work.",whenToUse:t,steps:"Write one draft per distinct problem, as plain text with the labels below, in this order, so the Phoenix team reads every report the same way. Keep every label; write `none` or `not deployed yet` where there is nothing to put.\n\n```text\nBuild: <build id> <Studio build page link>\nConfigurator: <live configurator link>\n\nWhat I was doing:\n<the task and the step you were on>\n\nWhat happened and what I expected:\n<what you ran or called, the result you got, and the result you expected>\n\nExact error or agent output:\n<the error text or the output, copied unchanged>\n\nWorkaround:\n<what you did instead, or none>\n\nConversation log:\n<the conversation condensed to the turns that matter: what the client asked, what you tried, what failed>\n```\n\n- **Build** is the latest build of this project, whose sources show the problem. `pnpm phoenix deploy` prints its id as `Build <id> started` and its page as `Follow the build in Studio: <url>`. When that line is missing, compose the link as `https://<workspace>.<studio host>/builder/deployments/<build id>`: the workspace is the one named at `phoenix login`, and the host is `studio.eu.salsita.ai` for the `eu` region, `studio.salsita.ai` for `us` and `studio-staging.salsita.app` for staging. A Studio address passed to login with `--studioUrl` replaces the workspace and host. Never invent a build id: when the project was not deployed, write `not deployed yet`.\n- **Configurator** is the live address `pnpm phoenix deploy` prints once the build is live.\n- The team downloads the build's sources from its Studio page, so do not paste whole files; quote only the lines that show the problem.\n- Quote errors and output exactly. A report that paraphrases an error cannot be searched for.\n- Condense the conversation log rather than dumping it: keep the client's requests, the decisions and the failures, and leave out tool output the other sections already carry.\n\nThen follow [Approve and send](send.md).",doneWhen:"- Each distinct, verified problem has one draft with every label filled or marked `none`.\n- The drafts went through [Approve and send](send.md).",example:"When `pnpm phoenix variants` rejects a script that only edits `src/elements/`, confirm the script follows the documented contract, then draft a bug with the exact rejection message, the script's relevant lines and `not deployed yet` for the build."});

package/dist/application-spec/generate-application/code/templates/skills/processes/feedback/send.d.ts

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

package/dist/application-spec/generate-application/code/templates/skills/processes/feedback/send.js

@@ -0,0 +1,2 @@
+import{createPhoenixProcessGuide as e}from"../../guide.js";let n=`- The client saw the exact text and approved it, and it was sent from a file or as a short argument; or the client declined and nothing was sent.
+- The sending is confirmed to the client in one line.`;export const generatePhoenixFeedbackSending=()=>e({path:"processes/feedback/send.md",title:"Approve and send",summary:"Showing the exact payload, redacting excluded data and sending only after approval; read before sending any feedback.",whenToUse:"Before sending any feedback: a [problem report](report.md) or an [evaluation](evaluate.md).",steps:"### Ask before sending\n\nNever send feedback on your own. Show the client a draft and send it only after they approve it. When to ask is a judgement:\n\n- **Right away** — the problem is crucial: it blocks the task or forces a workaround the client should know about now. Interrupt the work, show the draft and continue once the client has answered.\n- **At the end of the task** — everything else. Collect the details while working and show all drafts together in the final message.\n- **When the client asks** to send feedback — draft it and show it before sending.\n\nThe draft is exactly what would be sent: the type, the full message, the project if `--projectSlug` names one, and the contact if the client gave one. Send it unchanged after a yes; when the client edits it, send their version. When they decline, drop it and do not raise that problem again.\n\n### Send it\n\nWrite a report or an evaluation to a text file and send the file, so the shell changes nothing in it:\n\n```bash\npnpm phoenix feedback --file <path> --type bug --agent '<your agent name>'\n```\n\nPut the file outside the project, in the system's temporary folder, and delete it after sending. A note of a line or two can go in as an argument instead:\n\n```bash\npnpm phoenix feedback '<message>' --type idea --agent '<your agent name>'\n```\n\n- Give either `--file` or the message argument, never both.\n- Put a message argument in single quotes, so the shell passes backticks, `$` and double quotes through unchanged. In bash or zsh, write a single quote inside the message as `'\\''`; in PowerShell, double it instead.\n- `--type` is `bug`, `idea` or `other` (default `other`). Use `idea` for a missing feature or an improvement, and `other` for an evaluation.\n- `--agent` names the coding agent, so the team can tell agent feedback from a person's.\n- `--contact '<email>'` only when the client wants a reply and gave the contact to use.\n- The workspace, user, SDK version and the spec's `project` are attached automatically. `--projectSlug <slug>` names another project of the workspace.\n- A message holds at most 100,000 characters. Shorten the conversation log first when a report is longer.\n\nThe command needs `phoenix login`. When it answers that the CLI is not signed in, tell the client once and continue; do not sign in on their behalf, because the sign-in is approved in a browser. After sending, confirm it to the client in one line.\n\n### What never goes into feedback\n\nThe message leaves this project and is read by the Phoenix team. Never include:\n\n- secrets and credentials: API tokens, keys, passwords or `.env` values, also when they appear inside a quoted error or log. Replace each with `<redacted>`;\n- personal data, or data of the project's customers and end users, such as names, email addresses and orders, other than a contact the client asked to add.\n\nParts of this project may go into a message: file names and paths, snippets of its specs and code, and the client's own words. They are sent only as part of a draft the client saw and approved, which is why the draft shown is always the full text.",doneWhen:n,example:"At the end of a task, show the client two drafted reports in the final message. They approve the first and decline the second; send the first from a temporary file with `--type bug`, delete the file, confirm in one line, and never raise the second problem again."});

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

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

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

@@ -0,0 +1,2 @@
+import{createPhoenixProcessGuide as e}from"../guide.js";let a=`- Each agreed action works end to end in the preview, and its success and failure paths are visible.
+- Real messages or orders were sent only with the client's authorization.`;export const generatePhoenixFinalization=()=>e({path:"processes/finalization.md",title:"Finalization",summary:"Implement the agreed completion journey: summary PDFs, emails, sharing, quotes, orders or other integrations; read when a configuration needs an ending or an integration.",whenToUse:"When the configuration journey needs an ending: saving, sharing, a summary PDF, an email, a quote, an order or another integration. A [first draft](first-draft/build.md) uses it for its summary PDF and email.",steps:"1. Agree what completing means: what is collected, what is submitted and where, what the configurator user receives, and how progress, success, failure and recovery look. Discover requirements early when they affect earlier design decisions, and implement them here.\n2. Declare each completion as a `finalizeAction` component with `variant` `primary` or `secondary` and a handler registered with `phx.frontend.createPhoenixHandler`. Render the actions in the project layout with `phx.frontend.useFinalizeActions()`, as [Finalization actions](../features/custom-layout/finalization-actions.md) describes.\n3. Implement the server side in the project webhook as [Finalization](../features/webhooks/finalization.md) describes: a finalize handler registered with `withConfiguratorFinalize`, the [tasks](../features/webhooks/tasks/index.md) the journey needs, such as a configuration link, a PDF and an email, and a callback that returns the result. Images rendered by the configurator, described in `docs/other-features/client-side-rendering/declarative.mdx`, embed in PDFs without server rendering. Mail clients drop `data:` images and CSS filters, and signed file links expire after 30 minutes, so an email attaches its product images and loads its logo from `assets/public/` in a version made for the background it sits on ([Email](../features/webhooks/tasks/email.md)).\n4. Test payloads and outcomes, including a failed delivery, without sending real messages or creating real orders unless the client authorizes it. Keep unfinished rules and provisional prices identifiable, so nothing produces a misleading real quote or order.",doneWhen:a,example:"For a summary with email: the primary action generates a configuration link and two configurator renders, builds a branded PDF and offers it for download; the secondary action opens a form for an email address and sends the same PDF and images. Test the email with the client's own address after they agree, and a failed delivery with an invalid one."});

package/dist/application-spec/generate-application/code/templates/skills/processes/first-draft/build.d.ts

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

package/dist/application-spec/generate-application/code/templates/skills/processes/first-draft/build.js

@@ -0,0 +1,25 @@
+import{createPhoenixProcessGuide as e}from"../../guide.js";let t=`### Keep the scope small
+
+Implement one representative product with a few options, for example three finishes and one size choice, working end to end in the chosen layout and branding. Prefer one working path to a screen of inactive controls. Keep everything else in the product definition as remaining scope, and keep unconfirmed prices visibly provisional. Use reversible defaults and keep going; record them in the product definition rather than asking now.
+
+### Brand the first moments
+
+- **Preset screen** — the first screen users see and the easiest place to impress, so it deserves real design effort. Replace it with \`phx.frontend.createPresetUi()\` in the chosen branding, offering two or three meaningful starting configurations as large, well-lit renders, with the brand's typography, a deliberate composition and a little motion. \`pnpm phoenix screenshot\` captures only the state the preview shows, so open each preset in the preview with browser automation before capturing it; without automation, use a branded placeholder and say so at the handoff. Keep the preview-mode branch of the SDK example \`docs/layouts/presets/custom.mdx\`, read with \`pnpm phoenix docs -r <path>\`.
+- **App loader** — replace the loading overlay's content with \`phx.frontend.createAppLoader()\`: the logo, a short brand animation and progress from the loading phases.
+
+[Project pages](../../features/custom-layout/pages.md) has the contracts of both, and [Presets](../../features/application-states/presets.md) how the starting configurations are defined.
+
+### Add finalization
+
+Add two \`finalizeAction\` components with their handlers, following [Finalization](../finalization.md):
+
+- **Primary** — download a branded summary PDF of the configuration with images rendered from the configurator, the chosen options and the price, marked provisional while it is.
+- **Secondary** — an email form that sends the same PDF and images to the address the configurator user enters.
+
+Test the PDF in the running preview. Send a test email only to an address the client gives, after their yes; until then, report the email action as untested.
+
+### Check before presenting
+
+Exercise the representative path once in the preview: the preset screen, the loader, every option and both finalization actions, at desktop and phone width. Look at the framing beside the panel, at whether the camera holds still while options change and at whether the materials read as what they are. Fix what is broken. This is the quick look of the first draft, not a review process.`,n=`- The preset screen, loader, options and both finalization actions work in the running preview, in the chosen branding and layout.
+- The summary PDF downloads with configuration images; the email action is tested or explicitly waiting for an address.
+- Remaining scope and provisional items are recorded in the product definition and the project record.`;export const generatePhoenixFirstDraftBuild=()=>e({path:"processes/first-draft/build.md",title:"Build",summary:"A limited end-to-end configurator in the chosen branding and UX, with a branded preset screen, app loader, summary PDF and email; read once the layout is chosen.",whenToUse:"After [Direction](direction.md), once the client chose the branding and the layout. It ends with a working draft ready to present.",steps:t,doneWhen:n,example:"For the lounge chair: three upholstery colors and two leg finishes in the bottom-sheet layout, a preset screen with large renders of a classic, a bold and a quiet starting chair, a loader that draws the logo, a branded PDF with a front and a side render, and an email form. The client's own address receives the test email after they agree."});

package/dist/application-spec/generate-application/code/templates/skills/processes/first-draft/direction.d.ts

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

package/dist/application-spec/generate-application/code/templates/skills/processes/first-draft/direction.js

@@ -0,0 +1,35 @@
+import{createPhoenixProcessGuide as e}from"../../guide.js";let t=`### Intake
+
+Use what the client already supplied. When it is enough to start, there is nothing to ask: summarize the product as you understood it in two or three sentences and continue. When nothing was supplied, one compact message asking for whatever exists usually works, all optional: what the product is, who will use the configurator, the brand's website, logo or colors, and any 3D models, photos or drawings. Continue with whatever arrives; a second round of questions rarely helps.
+
+When a website is given, take the colors, typography, logo and tone from it instead of asking the client to describe their brand. Write what is known into a first [product definition](../specification/product-definition.md) and mark what is provisional; its PDF is rendered once, at the handoff. Prices, rules and the full product range wait for normal mode.
+
+### Branding options
+
+Prepare three branding options as standalone HTML pages in one [Variants](../../features/variants.md) set, each a one-page brand sheet with the content [Branding](../specification/branding.md) lists. Make them three different concepts rather than variations of one sheet: different composition, type pairing, color emphasis and mood, each designed on its own and finished as a brand designer would present it, so the client sees real alternatives and new ideas. With an existing brand, every option stays recognizably the client's, keeping its logo and core colors while the concept around them changes. Without one, make three directions that suit the product and its users. Run the set with \`--keep\`, so the chosen page remains to build from.
+
+Save the chosen page as the branding source, render its PDF, apply the brand to the Phoenix theme and remove the variants folder.
+
+### Sample scene
+
+Show the representative product with a minimal domain: its entity and one or two real options, enough for the layout options to show working controls.
+
+- **Supplied model** — convert only the representative model now, following [Asset conversion](../asset-conversion.md); the rest waits for normal mode.
+- **No model** — build a stand-in with three.js primitives exported to glTF, or with Blender when it is installed. Match the proportions of any photo or drawing, give each configurable part its own material, rest it on the floor and tell the client it is a stand-in.
+
+### Scene and camera
+
+The scene sells the product, and a little care here shows in every later screenshot. Set it in the chosen brand and look at the result in the preview before moving on:
+
+- **Setting** — a simple environment: a floor or plinth the product rests on and a soft backdrop or room in the brand's scene colors, rather than an empty void or a busy interior.
+- **Light** — an environment map gives materials their reflections; when it washes the product out, lower its intensity or the exposure rather than removing it. Add a key light with soft shadows, so the product sits on the floor. A custom environment component replaces the default lighting entirely.
+- **Materials** — each surface should read as what it is made of, such as stone, wood, lacquer or fabric. Flat plastic usually means missing reflections or a texture at the wrong scale.
+- **Camera** — fit the product when the configuration loads or a preset opens, not on every change: a camera that refits on mesh changes jumps on every option, slider step and drag, and throws away the view the configurator user chose. Set distance and angle limits and a comfortable default distance; a separate phone camera helps when one framing does not suit both.
+
+Read with \`pnpm phoenix docs -r <path>\`: \`docs/3d-scene/cameras/fit-root.mdx\`, \`docs/3d-scene/cameras/locks.mdx\`, the pages in \`docs/3d-scene/rendering/lights/\` and \`docs/3d-scene/rendering/soft-shadows.mdx\`; the gallery layouts below show complete scenes.
+
+### Layout options
+
+Prepare three distinct custom layouts as variant scripts over the live scene, each writing a complete \`ConfiguratorLayout\` as [Custom project layout](../../features/custom-layout/index.md) describes. Make them differ in structure, not only in color: for example a side panel, a bottom sheet with in-scene controls and a guided stepper. Start from the layout gallery in the SDK documentation rather than from scratch: \`pnpm phoenix docs -l\` lists its \`docs/layouts/gallery/\` pages and \`pnpm phoenix docs -r <path>\` reads one. Keep the canvas, safe-area, message and read-mode wiring of its examples, and frame the product in the free area as [Scene and safe area](../../features/custom-layout/scene-and-safe-area.md) describes; check the framing at desktop width with the panel open and on a phone. Every option uses the chosen branding and the same working controls, and each is finished like a real product rather than a wireframe.
+
+Run the set; the chosen script's edits stay in the project. Write the [UX guidelines](../specification/ux-guidelines.md) from the chosen layout and render their PDF.`;export const generatePhoenixFirstDraftDirection=()=>e({path:"processes/first-draft/direction.md",title:"Direction",summary:"Intake, three branding options, a sample scene and three layout options, ending with the chosen branding and UX guidelines; read at the start of a first draft.",whenToUse:"At the start of a first draft, once the preview is running and open for the client, as [Local development](../../core/cli.md#keep-the-preview-in-front-of-the-client) describes. It ends when the client has chosen a branding and a layout and the UX guidelines record the choice.",steps:t,doneWhen:"- The client chose a branding option and a layout option, and both are applied in the running preview.\n- The branding and UX guideline sources are in `.phoenix/workspace/specification/`, with their PDFs in `docs/`.\n- The sample scene shows the representative product, or a labeled stand-in, responding to at least one real option.\n- A first product definition records what is known and what is provisional.",example:"A client sends the website of their furniture brand and a photo of a lounge chair, without a model. Summarize the chair, offer three brand sheets that keep their logo and green but differ in concept, an editorial, a playful and a crafted one, build a stand-in chair from primitives with separate seat and frame materials, and offer a side-panel, a bottom-sheet and a stepper layout over it. The client picks the editorial sheet and the bottom sheet; the UX guidelines then describe the bottom-sheet patterns."});

package/dist/application-spec/generate-application/code/templates/skills/processes/first-draft/first-draft.d.ts

@@ -0,0 +1,3 @@
+import { type PhoenixGuide } from '../../guide.js';
+/** The first-draft index followed by its stages, in the order they run. */
+export declare const generatePhoenixFirstDraftGuides: () => readonly PhoenixGuide[];