@salsita-ai/sdk 0.50.0-develop.bb71259564 → 0.50.0-develop.bc204720a8

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

@@ -0,0 +1,92 @@
+import{createPhoenixFeatureGuide as e}from"../../guide.js";let t=`A quote request declares what the configurator sends, the quote number computed once, the callback's data and result, and the resources the tasks produce:
+
+\`\`\`yaml
+# spec/finalization.yaml
+finalizeData:
+  type: object
+  properties:
+    email:
+      type: string
+    views:
+      type: array
+      items:
+        type: string
+    cartSession:
+      type: string
+    addToCartUrl:
+      type: string
+  additionalProperties: false
+prefetchedFinalizeData:
+  type: object
+  properties:
+    quoteNumber:
+      type: string
+  required:
+    - quoteNumber
+  additionalProperties: false
+callbackData:
+  type: object
+  properties:
+    quoteNumber:
+      type: string
+  required:
+    - quoteNumber
+  additionalProperties: false
+finalizeResult:
+  type: object
+  properties:
+    quoteNumber:
+      type: string
+    pdfUrl:
+      type: string
+    shareUrl:
+      type: string
+  required:
+    - quoteNumber
+    - pdfUrl
+    - shareUrl
+  additionalProperties: false
+resources:
+  - type: ConfigurationLink
+    name: shareLink
+  - type: Image
+    name: studioRender
+    s3Key: studio-render.png
+  - type: Pdf
+    name: quotePdf
+    s3Key: quote.pdf
+  - type: Csv
+    name: quoteCsv
+    s3Key: quote.csv
+\`\`\`
+
+\`\`\`ts
+// src/webhooks/finalization.ts
+import { quoteCallback } from './tasks/callback.js'
+import { quoteCsvTask, quotePdfTask } from './tasks/documents.js'
+import { quoteEmailTask } from './tasks/email.js'
+import { cartTask, crmQuoteTask, quoteSheetTask } from './tasks/integrations.js'
+import { shareLinkTask, studioRenderTask } from './tasks/links-and-images.js'
+import { viewRenderResources, viewRendersTask } from './tasks/view-renders.js'
+
+const quoteNumber = phx.webhooks.prefetchBuilder
+  .withPrefetchHandler(data => ({ quoteNumber: \`Q-\${data.revisionId}\` }))
+  .build()
+
+export const quoteFinalization = phx.webhooks.finalizeHandlerBuilder
+  .withPrefetch(quoteNumber)
+  .withResources(viewRenderResources)
+  .withTask(shareLinkTask)
+  .withTask(studioRenderTask)
+  .withTask(viewRendersTask)
+  .withTask(quotePdfTask)
+  .withTask(quoteCsvTask)
+  .withTask(quoteEmailTask)
+  .withTask(crmQuoteTask)
+  .withTask(cartTask)
+  .withTask(quoteSheetTask)
+  .withCallback(quoteCallback)
+  .build()
+\`\`\`
+
+The quote number derives from the revision, so a retried request produces the same number. The view renders, the cart and the spreadsheet row skip themselves when their input or credentials are missing, so one handler serves every finalize action.`;export const generatePhoenixWebhookFinalizationFeature=()=>e({path:"features/webhooks/finalization.md",title:"Finalization",summary:"The finalize handler: how tasks are built and connected through resources, what each task receives, prefetch, the order the platform runs tasks in and what happens when one fails; read when implementing what happens after the configurator finalizes.",whenToUse:"Read when a finalize action has to produce something on the server — a link, a render, a PDF, an email, an order — or when a finalization fails.",capabilities:"### The pipeline\n\n- The configurator saves the configuration, uploads its configurator-rendered images and asks the platform to finalize the latest saved revision. Its handler then waits with `waitForFinalizationToComplete`, whose default timeout of 30 seconds is too short for a server render: pass a longer `pollingTimeout`. [Finalization actions](../custom-layout/finalization-actions.md) owns that side.\n- The webhook runs [backend data](backend-data.md) again, rebuilds the domain from the saved state and refuses to finalize while a `warning` violation remains. It then runs the prefetch, collects the tasks and resources and hands them to the platform, which runs them. Under `phoenix dev` this part has 60 seconds.\n- Build it with `phx.webhooks.finalizeHandlerBuilder`: `withPrefetch` once, `withTask` per task, `withResources` for resources known only at runtime, `withCallback` once, then `build()`. Register the result with `withConfiguratorFinalize` in the [entry](entry-and-environment.md).\n\n### Tasks\n\n- Build each task with `phx.webhooks.taskFactory.create<Type>Task((resources, data, ctx) => task)`, one factory per task type in [Finalization tasks](tasks/index.md). Return the task, several tasks, or `null` to skip it for this request.\n- `resources` holds the names declared under `resources:`, typed, so a misspelled name does not compile.\n- `data` holds `configurationId`, `revisionId`, `deploymentId`, `frontendUrl`, `state`, `finalizeData` (what the configurator sent, validated against the `finalizeData` schema), `sessionRole`, `sessionPayload`, `publishedData`, `frontendData`, `backendData` and `prefetchedData`.\n- `ctx` holds `domain` (`ctx.domain.getRoot$Entity(data.state)` reads the configured product), `resolveLocalizable` and `i18n` in the request's locale, `getPublicAssetUrl` for files under `assets/public/`, `blenderProjections`, the `pdfTaskBuilder` and `emailTaskBuilder`, and `logger`.\n- `phx.webhooks.prefetchBuilder.withPrefetchHandler((data, ctx) => values)` computes once what several tasks need, such as a quote number. The `prefetchedFinalizeData` schema types it, and tasks read it as `data.prefetchedData`.\n\n### Resources\n\n- Tasks connect through named resources: one task produces a resource under its name, others include it. Declare them under `resources:` as `ConfigurationLink`, `Pdf`, `Csv` or `Image`; an `Image` is rendered on the server (`s3Key`), rendered by the configurator (`clientGenerated: true` with `s3Key`) or an existing file (`exists: true` with `url`).\n- Finalization fails when a declared resource has no task producing it, a name repeats or a task includes an undeclared resource.\n- Images of `clientSideImage` components are declared automatically; tasks name them by entity id and instance name.\n\n### Order and failure\n\n- The platform runs tasks by type, not in `withTask` order: links and server renders first, then CSVs, PDFs, emails, HTTP requests, WooCommerce and Google Sheets, and the [callback](tasks/callback.md) last. Tasks of one type run in parallel, except server renders, which queue one at a time. A PDF or email can use the links and renders, and an email can attach the PDFs and CSVs.\n- A generated PDF or CSV is stored, and so reachable by a link, only when the same finalization has a callback or WooCommerce task.\n- Nothing is retried or rolled back. When a task fails the finalization fails, and what already ran stays done. The configurator learns only that it failed; the cause is in the platform's logs, out of the project's reach. Try each task with test data first.\n- Tasks run on the platform even under `phoenix dev`: emails are sent and requests made. Use test recipients and endpoints until the client authorizes real ones.\n- The configurator receives the callback's result; without a callback it receives nothing.",example:t,documentation:"Read with `pnpm phoenix docs -r <path>`:\n\n- `docs/phoenix/finalization.mdx` — the finalization flow, its data schemas and the configurator side.\n- `docs/phoenix/webhooks.mdx` — the finalize payload, task context and every task type.\n\nThe [Finalization](../../processes/finalization.md) process covers agreeing the journey with the client.",phxMembers:["webhooks.finalizeHandlerBuilder","webhooks.prefetchBuilder","webhooks.taskFactory"]});

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

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

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

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

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

@@ -0,0 +1,3 @@
+import { type PhoenixGuide } from '../../guide.js';
+/** Admin publishing: the SDK-built Admin finalization, the publish tasks and the project's mapping and validation handlers. */
+export declare const generatePhoenixPublishingFeature: () => PhoenixGuide;

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

@@ -0,0 +1 @@
+import{createPhoenixFeatureGuide as e}from"../../guide.js";export const generatePhoenixPublishingFeature=()=>e({path:"features/webhooks/publishing.md",title:"Admin publishing",summary:"What publishing in Project Admin runs in the webhook: the `PublishRevision` tasks, mapping admin entities to published data and validating data rows and sheets; read when admin content has to reach the configurator.",whenToUse:"Read when the project has Project Admin content to publish, maps its own admin entities into published data, or validates manual or connected data before publishing.",capabilities:"### What publishing runs\n\n- Publishing in Project Admin runs the webhook's Admin finalization, which the SDK builds itself: `phx.webhooks` has no builder for it and the [entry](entry-and-environment.md) registers nothing.\n- Without published-data chunks it produces one `PublishRevision` task with the whole published data. With chunks it produces `PublishRevisionChunksStaged`, which uploads the chunks first and takes up to 100 MiB, or `PublishRevisionChunks` with the chunks inline where the platform offers no upload.\n- Presets, preset categories, recipes and swatch options are published without project code. A project maps its own admin entities with a handler.\n\n### Project handlers\n\nDefault-export each from a file in `src/handlers/`. These files join the webhook automatically, so they import only server-safe modules. Only the first handler of each kind counts.\n\n- `phx.domain.admin.createMapPublishedRevisionDataHandler(({ entities, adminEntity }) => data)` — the published data, without chunks.\n- `phx.domain.admin.createMapPublishedChunkedDataHandler(({ entities, adminEntity, connectedSheetData }) => chunks)` — per-chunk data spread over what the SDK generates; `connectedSheetData` holds the rows of connected spreadsheets during publishing.\n- `phx.domain.admin.createDataRowValidatorHandler` and `createSheetValidatorHandler` — business rules for manual and connected data, returning messages with `severity` `error` or `warning`. They run in Admin's verify dialog and again when publishing, where an `error` stops the publish and a `warning` does not. Keep them synchronous and pure.\n\n### Reaching the configurator\n\n- The configurator reads published data as `publishedData` in expressions and tasks. A session reads the `public` chunk and the scopes [authentication](authentication.md) grants with `withPublishedChunkScopes`.\n- Published data belongs to the environment and outlives deploys. Check the configurator against freshly published data after a deploy that changes the published-data schema.",example:'A catalogue maps its visible custom materials into the `catalog` chunk, and a row validator rejects a material without a price before it is published. The complete handler is the "Custom Mapping Handler" of `docs/phoenix/publishing.mdx`, and the validators are under "Custom Validation Handlers" in `docs/phoenix/connected-data-sources.mdx`; both depend on the project\'s admin model and data entries, so start from them rather than a copy.',documentation:"Read with `pnpm phoenix docs -r <path>`:\n\n- `docs/phoenix/publishing.mdx` — chunks, scopes, the publish flow and the mapping handler.\n- `docs/phoenix/connected-data-sources.mdx` — connected spreadsheets and the validators.\n- `docs/phoenix/admin.mdx` — Project Admin and its model.",phxMembers:[]});

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

@@ -0,0 +1,3 @@
+import { type PhoenixGuide } from '../../../guide.js';
+/** The finalization callback: the CallLambdaBack task and the result the configurator receives. */
+export declare const generatePhoenixCallbackFeature: () => PhoenixGuide;

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

@@ -0,0 +1,26 @@
+import{createPhoenixFeatureGuide as e}from"../../../guide.js";let a=`The quote result gives the configurator the quote number, the PDF to download and the share link:
+
+\`\`\`ts
+// src/webhooks/tasks/callback.ts
+export const quoteCallback = phx.webhooks.callbackBuilder
+  .withCallbackData((resources, data) => ({
+    replayData: { quoteNumber: data.prefetchedData.quoteNumber },
+    resources: {
+      [resources.quotePdf]: { embeddingType: 'Link' },
+      [resources.shareLink]: { embeddingType: 'Link' },
+    },
+  }))
+  .withCallbackHandler(async ({ replayData, resources }) => {
+    const pdfUrl = resources.quotePdf?.link
+    const shareUrl = resources.shareLink?.link
+
+    if (pdfUrl === undefined || shareUrl === undefined) {
+      throw new Error(
+        \`Quote \${replayData.quoteNumber} finished without its PDF or share link. Check the PDF and link tasks of this finalization.\`
+      )
+    }
+
+    return { quoteNumber: replayData.quoteNumber, pdfUrl, shareUrl }
+  })
+  .build()
+\`\`\``;export const generatePhoenixCallbackFeature=()=>e({path:"features/webhooks/tasks/callback.md",title:"Callback and result",summary:"`callbackBuilder` and its `CallLambdaBack` task: links to the generated files and the result the configurator receives; read when the configurator shows, downloads or forwards what finalization produced.",whenToUse:"Read when the configurator needs something back from finalization — a download, a quote number, a link to redirect to — or when the produced files must reach another system.",capabilities:"### How it works\n\n- Build the callback with `phx.webhooks.callbackBuilder`: `withCallbackData` chooses what to carry over and which resources to receive, `withCallbackHandler` turns them into the result, then `build()`. Register it with `withCallback` on the [finalize handler](../finalization.md), once.\n- `withCallbackData((resources, data, ctx) => ({ replayData, resources }))` runs with the other tasks. `replayData` follows the `callbackData` schema; `resources` maps each resource to receive to `{ embeddingType: 'Link' }`. It adds a `CallLambdaBack` task, which the platform runs last.\n- The platform then calls the webhook again with `{ replayData, resources }`, where each resource is `{ type: 'Link', link }`. The handler's return value is the finalization result, typed by the `finalizeResult` schema but not checked at runtime.\n- The configurator receives that result from `waitForFinalizationToComplete`. Without a callback it receives nothing, so a download or a redirect needs one.\n\n### Links and limits\n\n- File links are signed and expire after 30 minutes: hand them to the configurator user to open now, not to keep. A configuration link stays valid for its own `expiration`.\n- Only resources stored by the platform can be passed: generated PDFs, CSVs and images with an `s3Key`, and configuration links. An `exists` image with a `url` cannot.\n- The callback runs after everything else, so a throw fails a finalization whose emails and requests already went out. Check what the handler needs and fail with a message saying which resource is missing.\n- The handler is the place to send the links to another system, for example posting the PDF link to a partner's endpoint with a credential from `phx.webhooksEnv`.\n- Under `phoenix dev` the callback returns through the development tunnel, so `phoenix dev` must still be running when the tasks finish.",example:a,documentation:"Read `docs/phoenix/finalization.mdx` with `pnpm phoenix docs -r docs/phoenix/finalization.mdx` for the callback and result schemas and the configurator side. `docs/phoenix/integration/finalization-internal.mdx` sends a partner the links from the callback.",phxMembers:["webhooks.callbackBuilder"]});

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

@@ -0,0 +1,3 @@
+import { type PhoenixGuide } from '../../../guide.js';
+/** Generated PDF and CSV documents. */
+export declare const generatePhoenixDocumentsFeature: () => PhoenixGuide;

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

@@ -0,0 +1,51 @@
+import{createPhoenixFeatureGuide as e}from"../../../guide.js";let t=`A quote PDF with the share link and the studio render, numbered pages and a draft watermark, and a one-row CSV for the sales team:
+
+\`\`\`tsx
+// src/webhooks/tasks/documents.tsx
+import { PdfHelpers, ResourceHelpers } from '@salsita-ai/sdk/webhook'
+
+export const quotePdfTask = phx.webhooks.taskFactory.createGeneratePdfTask((resources, data, ctx) => {
+  const chair = ctx.domain.getRoot$Entity(data.state)
+
+  return ctx.pdfTaskBuilder
+    .withResourceName(resources.quotePdf)
+    .withFormat('A4')
+    .withMargin({ top: '24mm', bottom: '20mm', left: '16mm', right: '16mm' })
+    .withIncludedResources({
+      other: [
+        { type: 'ConfigurationLink', name: resources.shareLink },
+        { type: 'Image', name: resources.studioRender, embeddingType: 'Link' },
+      ],
+    })
+    .withReactBody(
+      <main style={{ fontFamily: 'Georgia, serif' }}>
+        <img src={ctx.getPublicAssetUrl('pdf/logo.png')} alt="" width={96} />
+        <h1>Quote {data.prefetchedData.quoteNumber}</h1>
+        <ResourceHelpers.Image resource={resources.studioRender} alt={chair.label} style={{ width: '100%' }} />
+        <p>
+          {chair.label}, {chair.finish}, {chair.width} cm wide
+        </p>
+        <ResourceHelpers.Link resource={resources.shareLink}>Open your configuration</ResourceHelpers.Link>
+      </main>
+    )
+    .withReactFooter(
+      <div style={{ fontSize: '8pt', textAlign: 'center', width: '100%' }}>
+        <PdfHelpers.PageNumber /> / <PdfHelpers.TotalPages />
+      </div>,
+      { height: '12mm', startAt: 1 }
+    )
+    .withWatermarkText('DRAFT')
+    .build()
+})
+
+export const quoteCsvTask = phx.webhooks.taskFactory.createGenerateCsvTask((resources, data, ctx) => {
+  const chair = ctx.domain.getRoot$Entity(data.state)
+
+  return {
+    type: 'GenerateCsv',
+    name: resources.quoteCsv,
+    columns: ['quote', 'model', 'finish', 'width'],
+    data: [{ quote: data.prefetchedData.quoteNumber, model: chair.label, finish: chair.finish, width: chair.width }],
+  }
+})
+\`\`\``;export const generatePhoenixDocumentsFeature=()=>e({path:"features/webhooks/tasks/documents.md",title:"PDF and CSV documents",summary:"`GenerateStaticPdf` through `ctx.pdfTaskBuilder` with React templates, headers, footers and watermarks, legacy `GeneratePdf`, and `GenerateCsv`; read when finalization produces a document.",whenToUse:"Read when finalization produces a summary, quote or specification PDF, or a CSV for a spreadsheet or another system.",capabilities:"### PDF\n\n- Build a PDF with `ctx.pdfTaskBuilder` inside `createGeneratePdfTask`, in this order: `withResourceName` with a declared `Pdf` resource, then optionally `withLocale`, `withFormat` (A4 by default), `withMargin` and `withIncludedResources`, an optional header, `withReactBody` or `withHtmlBody`, an optional footer and an optional watermark, then `build()`. It produces a `GenerateStaticPdf` task, rendered from the HTML by the platform's print engine.\n- Show included resources with `ResourceHelpers.Link`, `ResourceHelpers.Image` and `ResourceHelpers.ClientSideImage` from `@salsita-ai/sdk/webhook`. Declare each with `withIncludedResources` first, or rendering throws. An image declared with `embeddingType: 'Link'` loads from a signed URL valid for 30 minutes; `'Embedded'` inlines it.\n- `withReactHeader` and `withReactFooter` take the band's `height` and the page it `startAt`. `PdfHelpers.PageNumber`, `TotalPages`, `Date`, `Title` and `Url` work only there and throw in the body.\n- Load logos, fonts and other files under `assets/public/` with `ctx.getPublicAssetUrl(path)`.\n- `withWatermarkText`, `withWatermarkImage` and `withWatermarkResourceImage` mark every page, such as a draft whose prices are still provisional.\n- `GeneratePdf` is the legacy form: a Handlebars template with `{{resource-<name>}}` placeholders. New projects use the builder.\n\n### CSV\n\n- `GenerateCsv` writes `columns` and `data` rows, objects keyed by column, under a declared `Csv` resource. `header` defaults to true, `delimiter` to a comma and `bom` to true, so spreadsheet applications detect UTF-8.\n- Resolve localizable text with `ctx.resolveLocalizable` before it becomes a cell.\n\n### Using the files\n\n- An email attaches the PDFs and CSVs of the same finalization ([Email](email.md)). A link to one, in a callback result or another document, works only when the finalization has a callback or WooCommerce task ([Finalization](../finalization.md)).",example:t,documentation:"Read `docs/phoenix/webhooks.mdx` with `pnpm phoenix docs -r docs/phoenix/webhooks.mdx` for the complete PDF template and every builder method. `docs/phoenix/localization.mdx` covers translated PDF text.",phxMembers:[]});

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

@@ -0,0 +1,3 @@
+import { type PhoenixGuide } from '../../../guide.js';
+/** Emails sent by finalization. */
+export declare const generatePhoenixEmailFeature: () => PhoenixGuide;

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

@@ -0,0 +1,38 @@
+import{createPhoenixFeatureGuide as e}from"../../../guide.js";let t=`The quote email, sent only when the configurator user entered an address, with the PDF and the render attached:
+
+\`\`\`tsx
+// src/webhooks/tasks/email.tsx
+import { ResourceHelpers } from '@salsita-ai/sdk/webhook'
+
+const EMAIL_ADDRESS = /^[^@\\s]+@[^@\\s]+\\.[^@\\s]+$/
+
+export const quoteEmailTask = phx.webhooks.taskFactory.createSendEmailTask((resources, data, ctx) => {
+  const { email } = data.finalizeData
+
+  if (email === undefined || !EMAIL_ADDRESS.test(email)) {
+    return null
+  }
+
+  const { quoteNumber } = data.prefetchedData
+
+  return ctx.emailTaskBuilder
+    .withSender({ from: phx.webhooksEnv.QUOTE_SENDER })
+    .withRecipients({ to: email })
+    .withSubject(\`Your quote \${quoteNumber}\`)
+    .withBodyResources({ other: [{ type: 'ConfigurationLink', name: resources.shareLink }] })
+    .withReactBody(
+      <div style={{ fontFamily: 'Arial, sans-serif', maxWidth: 600 }}>
+        <img src={ctx.getPublicAssetUrl('email/logo.png')} alt="" width={120} />
+        <p>Your quote {quoteNumber} and a picture of your chair are attached.</p>
+        <ResourceHelpers.Link resource={resources.shareLink}>Open your configuration</ResourceHelpers.Link>
+      </div>
+    )
+    .withAttachments({
+      other: [
+        { type: 'resource', filename: \`\${quoteNumber}.pdf\`, resource: resources.quotePdf },
+        { type: 'resource', filename: 'chair.png', resource: resources.studioRender },
+      ],
+    })
+    .build()
+})
+\`\`\``;export const generatePhoenixEmailFeature=()=>e({path:"features/webhooks/tasks/email.md",title:"Email",summary:"`SendStaticEmail` through `ctx.emailTaskBuilder` with React bodies, links and attachments, images that survive mail clients, and legacy `SendEmail`; read when finalization sends an email.",whenToUse:"Read when finalization sends the configurator user, the client or a sales team an email.",capabilities:"### Building an email\n\n- Build an email with `ctx.emailTaskBuilder` inside `createSendEmailTask`, in this order: `withSender({ from, replyTo? })`, `withRecipients({ to, cc?, bcc? })` with comma-separated addresses, an optional `withLocale`, `withSubject`, an optional `withBodyResources`, `withReactBody` or `withHtmlBody`, an optional `withPlainTextBody` and `withAttachments`, then `build()`. It produces a `SendStaticEmail` task; a React body also yields its plain-text part.\n- Return `null` when this request sends nothing, such as a download without an email address. Check an address from `data.finalizeData` before sending to it.\n- Links and images in the body use `ResourceHelpers` from `@salsita-ai/sdk/webhook` and must be declared with `withBodyResources` first. `EmailHelpers.HtmlOnly` and `EmailHelpers.TextOnly` show content in only one of the two parts.\n- `withAttachments` attaches the PDFs, CSVs and images of the same finalization by resource name, configurator-rendered images by entity id and instance name, and any file as base64.\n- `SendEmail` is the legacy form with a Handlebars template. New projects use the builder.\n\n### Images in the body\n\n- Mail clients drop `data:` images, and a configurator-rendered image in the body is inlined as one. A rendered resource shown by link loads from a signed URL that expires after 30 minutes.\n- So attach the product images and the PDF, and load the logo and other fixed images from `assets/public/` with `ctx.getPublicAssetUrl(path)`, in versions made for the email's background.\n\n### Sending\n\n- The platform's mail service sends from `from`. Agree the sender address with the client and confirm a test email arrives before relying on it.\n- Emails go out even under `phoenix dev`. Send to the client's own address, and to configurator users only once the client authorizes it.",example:t,documentation:"Read `docs/phoenix/webhooks.mdx` with `pnpm phoenix docs -r docs/phoenix/webhooks.mdx` for the complete email template and every builder method. `docs/phoenix/localization.mdx` covers translated subjects and bodies.",phxMembers:[]});

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

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

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

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

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

@@ -0,0 +1,3 @@
+import { type PhoenixGuide } from '../../../guide.js';
+/** Finalization tasks that reach other systems: HTTP requests, WooCommerce carts and Google Sheets. */
+export declare const generatePhoenixIntegrationsFeature: () => PhoenixGuide;

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

@@ -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,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
 
-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:
+
+${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>>>;