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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

@@ -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,generatePhoenixFeedbackGuides as a,generatePhoenixFinalization as d,generatePhoenixFirstDraftGuides as c,generatePhoenixModelMigration as h,generatePhoenixOperations as l,generatePhoenixPlanning as u,generatePhoenixReviewGuides as p,generatePhoenixSpecificationGuides as m}from"./processes/index.js";export const generatePhoenixSkillBundle=f=>{let w=[r(),t(),o()],g=[c(),m(),[u()],[l(f)],[d()],[i()],[h()],p(),a()],x=s({path:"processes/index.md",title:"Processes",summary:"Procedures summarized by outcome and when to use them.",intro:"Read the procedure or section whose outcome the task needs. The [workflow](../core/workflow.md) owns strategy, preferences and effort; processes supply the execution.",guides:g.flatMap(e=>e.slice(0,1)),notes:[]}),k=n();return{content:e({name:"phoenix",description:"Build, change, inspect, deploy or review a Phoenix configurator project. Use for all Phoenix project work, including a first draft of a new project, visual alternatives and platform feedback.",sections:[`# Phoenix
+
+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:
+
+${w.map((e,o)=>`${o+1}. [${e.title}](${e.path}) — ${e.summary}.`).join("\n")}
+
+The core governs every task; reading the workflow does not mean executing every stage. Reuse the core while it remains in context and unchanged, and read it again when context is lost or sync or an SDK update changes it.`,`## Optional guidance
+
+- [Processes](processes/index.md) — procedures summarized by outcome and when to use them.
+- [Features](features/index.md) — what Phoenix capabilities support, their constraints and canonical SDK documentation.
+
+Follow only the destinations the task needs; a link does not require reading its whole subtree.`]}),references:[...w,x,...g.flat(),...k].map(({path:e,content:o})=>({path:e,content:o}))}};

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

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

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/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,39 @@
+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:
+
+- Ask once per conversation. Do not run it again after a later deploy, and do not run it after a deploy that failed.
+- 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 once the client has finished.",whenToUse:"When the work on the configurator is finished: the client says they are done, or `phoenix deploy` reported the configurator live and the client confirms they have nothing more to build. Ask that once after a deploy goes live, and do not start the interview while they want to continue.",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 i}from"./send.js";export const generatePhoenixFeedbackGuides=()=>{let t=[r(),o(),i()];return[e({path:"processes/feedback/index.md",title:"Feedback",summary:"Run evaluations and verified Phoenix problem reports, sent only with approval; read right after `phoenix deploy` reports the configurator live, when the client finishes, 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:t,notes:[]}),...t]};

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 [Custom project layout](../features/custom-layout.md) describes.\n3. Implement the server side in the project webhook with `withConfiguratorFinalize`, chaining the tasks the [SDK core](../core/sdk.md#webhooks-and-finalization) lists, such as `GenerateConfigurationLink`, `GeneratePdf` or `GenerateStaticPdf`, and `SendEmail`, and return the result in the callback. Images rendered by the configurator, described in `docs/other-features/client-side-rendering/declarative.mdx`, embed in PDFs and emails without server rendering.\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,23 @@
+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; list them at the handoff instead of asking now.
+
+### Brand the first moments
+
+- **Preset screen** — replace it with \`phx.frontend.createPresetUi()\` in the chosen branding, offering two or three meaningful starting configurations with thumbnails. \`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.
+
+### 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. 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 offering 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,26 @@
+import{createPhoenixProcessGuide as e}from"../../guide.js";let t=`### Intake
+
+Use what the client already supplied. When it is enough to start, ask nothing: summarize the product as you understood it in two or three sentences and continue. When nothing was supplied, send one compact message asking for whatever exists, 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; do not start a second round of questions.
+
+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. With an existing brand, the options interpret it for a configurator, for example faithful, bolder and quieter; they never replace it. Without one, make three genuinely different 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.
+
+Set materials, lighting, background and camera framing in the chosen brand, and look at the result in the preview before moving on.
+
+### 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.md) describes. Make them differ in structure, not only in color: for example a sidebar, 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. Every option uses the chosen branding and the same working controls.
+
+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 [Project operations](../operations.md) has the preview running. 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 interpret their site, build a stand-in chair from primitives with separate seat and frame materials, and offer a sidebar, a bottom-sheet and a stepper layout over it. The client picks the bolder brand 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[];

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

@@ -0,0 +1,3 @@
+import{createPhoenixIndexGuide as e}from"../../guide.js";import{generatePhoenixFirstDraftBuild as t}from"./build.js";import{generatePhoenixFirstDraftDirection as o}from"./direction.js";import{generatePhoenixFirstDraftHandoff as n}from"./handoff.js";export const generatePhoenixFirstDraftGuides=()=>{let r=[o(),t(),n()];return[e({path:"processes/first-draft/index.md",title:"First draft",summary:"A fast, convincing first version of a new project: chosen branding and UX, a sample product, real finalization and an offer to deploy; read only for a new project, never for an existing one.",intro:`The first thing a new client sees. In one short sitting, deliver a branded, working configurator with a chosen look and UX, a sample of the product and real finalization, ready to deploy as a first live version. Use it only for a new project; an existing project continues in normal mode.
+
+Speed is part of the quality. Run no review processes, and ask the client to choose only three things: a branding option, a layout option and whether to deploy. Everything else uses reversible defaults, stated at the handoff. Read the stages in order, and note in the project record which stage the draft reached, so a resumed session continues the draft instead of switching to normal mode; the handoff marks the draft complete.`,guides:r,notes:[]}),...r]};

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

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

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

@@ -0,0 +1,7 @@
+import{createPhoenixProcessGuide as e}from"../../guide.js";let t=`1. Render the product definition PDF from its current source, then present the draft in the preview: what the client can try, what is provisional, such as a stand-in model or prices, and which documents are in \`docs/\`. List the reversible defaults chosen while building.
+2. Ask whether they like it and what they would change first. Fix small requests now; record larger ones for the plan.
+3. Offer to deploy it as a first live version with [Project operations](../operations.md), and deploy only after a yes and its transcript consent. When this workspace deployed the starter model before, follow [Model migration](../model-migration.md) first.
+4. Ask once about the [preferences](../../core/workflow.md#preferences), with a recommendation, and record the answers.
+5. Recommend the next step in terms of the client's product, usually bringing in the rest of the range or the rules that [Planning](../planning.md) prepares, with one or two alternatives.`,r=`- The client has seen the draft and answered whether to deploy; the deploy went live or was declined.
+- The client's reactions and preferences are recorded in the project record, which marks the first draft complete.
+- The client knows the recommended next step, and the project continues in normal mode.`;export const generatePhoenixFirstDraftHandoff=()=>e({path:"processes/first-draft/handoff.md",title:"Handoff",summary:"Present the draft, offer a first live deployment, agree preferences and move to normal mode; read when the build works.",whenToUse:"When the first-draft [Build](build.md) works. The handoff ends the first draft; the project continues in normal mode, deployed or not.",steps:t,doneWhen:r,example:'"Here is your first draft: try the presets, change the upholstery and download the summary PDF. The chair is a stand-in until we have your model. Do you like the direction? I can deploy it now as your first live version. From here on, should I favor fast, lean steps or more thorough checks that take longer and cost more?"'});

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

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

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

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

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

@@ -0,0 +1,9 @@
+export * from './first-draft/index.js';
+export * from './specification/index.js';
+export * from './planning.js';
+export * from './operations.js';
+export * from './finalization.js';
+export * from './asset-conversion.js';
+export * from './model-migration.js';
+export * from './review/index.js';
+export * from './feedback/index.js';

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

@@ -0,0 +1 @@
+export*from"./first-draft/index.js";export*from"./specification/index.js";export*from"./planning.js";export*from"./operations.js";export*from"./finalization.js";export*from"./asset-conversion.js";export*from"./model-migration.js";export*from"./review/index.js";export*from"./feedback/index.js";

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

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

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

@@ -0,0 +1 @@
+import{createPhoenixProcessGuide as e}from"../guide.js";export const generatePhoenixModelMigration=()=>e({path:"processes/model-migration.md",title:"Model migration",summary:"Preserve deployed model versions and migrate saved configurations; read when changing a domain model that has already been deployed.",whenToUse:"When changing a domain model that has already been deployed, including replacing a deployed starter model after a [first draft](first-draft/handoff.md).",steps:"A deployed model version cannot change, because saved configurations depend on it. `pnpm phoenix deploy` is refused, before anything is uploaded, when the model differs from the one already deployed under the same version. The version is not written anywhere: `model.latest` is always the highest numbered version plus one, so a spec with only `latest` is v1, and `applicationVersion` plays no part. `pnpm phoenix dev` accepts every model change, so a working preview does not show that the deploy will pass.\n\n### Change a deployed model\n\nTo change a model that has been deployed as v<N>:\n\n1. Keep the deployed model, unchanged, as `model.v<N>` in the spec. A file of its own, such as `spec/model-v<N>.yaml`, keeps `latest` readable.\n2. Make the change in `model.latest`, which is now v<N+1>.\n3. Add `src/migrations/v<N+1>.ts` exporting `migrateToV<N+1>`. It receives the saved entities of v<N> and returns entities that are valid in v<N+1>; `ModelV<N>` and `ModelV<N+1>` are generated global namespaces.\n\nThe admin model is versioned on its own, under `src/admin/migrations/`, with its types in `AdminV<N>`.\n\n### Replace the starter\n\nWhen the first deployment of the workspace was the starter, its `Box` model is v1 in production. When the real model replaces it, keep the starter's model as `model.v1` and define the real model in `latest`. Configurations saved from the starter are not worth converting, so the migration returns the starting state of the new model, the `initialDomainEntities` of its preset, and drops the boxes:\n\n```typescript\n// src/migrations/v2.ts\nimport type { Migration } from '@salsita-ai/sdk/domain'\n\nexport const migrateToV2: Migration<ModelV1.AnyDomainEntity, ModelV2.AnyDomainEntity> = () => [\n  // the entities of the new model's preset\n]\n```\n\nAn entity of a type the new version no longer has must not stay in the returned state. An entity id starts with its type (`Box-1`), so an entity that keeps its data under a new type name needs a new id, and every relation pointing at it rewritten. Read `docs/phoenix/migrations.mdx` with `pnpm phoenix docs -r docs/phoenix/migrations.mdx` before writing any other migration.",doneWhen:"- The deployed model is kept unchanged under its version, the change is in `model.latest`, and a migration converts saved configurations.\n- A configuration saved with the previous version loads after the change.",example:"When a deployed starter `Box` model is replaced by a chair, keep the starter as `model.v1`, make the chair model `latest` (v2) and implement `migrateToV2` returning the chair preset's entities. Load a configuration saved from the starter to verify that it opens as the default chair."});

package/dist/application-spec/generate-application/code/templates/skills/{phoenix-skill.d.ts → processes/operations.d.ts}

@@ -1,3 +1,4 @@
+import { type PhoenixGuide } from '../guide.js';
 export interface PhoenixSkillOptions {
     readonly checkLatestCanary: boolean;
 }
@@ -10,4 +11,4 @@ export declare const followsCanaryBuilds: (project: {
     readonly useWorkspace: boolean;
     readonly sdkVersion: string;
 }) => boolean;
-export declare const generatePhoenixSkill: ({ checkLatestCanary }: PhoenixSkillOptions) => string;
+export declare const generatePhoenixOperations: ({ checkLatestCanary }: PhoenixSkillOptions) => PhoenixGuide;

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

@@ -0,0 +1,2 @@
+import{createPhoenixProcessGuide as e}from"../guide.js";export const followsCanaryBuilds=e=>!e.useWorkspace&&e.sdkVersion.includes("-develop.");export const generatePhoenixOperations=({checkLatestCanary:t})=>e({path:"processes/operations.md",title:"Project operations",summary:`Keep the live preview open and deploy with transcript consent and a Studio link${t?", and keep this canary project on the newest SDK build":""}; read before the first change in a conversation and when deploying.`,whenToUse:`Before the first change in a conversation, to keep the preview in front of the client, and whenever the project is deployed.${t?" This canary project also checks for a newer SDK build once per conversation.":""}`,steps:[...t?["### Stay on the latest canary\n\nDuring the internal beta this project uses the `canary` build of the SDK, which is published from every change to the platform. Once per conversation, before 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 update the SDK, bring the packages it needs in line and regenerate the project files:\n\n```bash\npnpm add @salsita-ai/sdk@canary && pnpm phoenix deps && pnpm install && pnpm phoenix sync\n```\n\nSync 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@canary`. When the project no longer builds after the update, stop, tell the client and report it with [Feedback](feedback/index.md)."]:[],"### Keep the preview open\n\nThe client should see the configurator change while it is built. Before the first change in a conversation, make sure `pnpm phoenix dev` is running, starting it in the background when it is not, and open the address it prints as `Preview: <url>`, also written to `.phoenix/phoenix-dev.log`, in the client's browser: `open '<url>'` on macOS, `xdg-open '<url>'` on Linux, `Start-Process '<url>'` in PowerShell, `start \"\" \"<url>\"` in cmd. Keep the quotes; the shell would otherwise read a `?` in the address as a pattern. The log keeps the lines of earlier runs, so after starting dev, wait for the `Preview:` line written after the start and use the last one.\n\nOpen it once: the preview reloads on every change, so tell the client to keep that tab open instead of opening it again. A domain model change is the exception. `pnpm phoenix dev` registers the model with the server only when it starts, and after the change it logs an error that asks for a restart. Restart it, wait for the new `Preview:` line and open that address in place of the old tab, whose `?cid=` names a configuration saved with the earlier model, which the new model rejects.","### Prepare the transcript\n\nImmediately 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. 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, and mark references whose files are not uploaded. Exclude internal instructions, hidden reasoning, credentials and unrelated sensitive content; mark redactions without repeating the removed content. Refresh the current session's log rather than appending duplicate copies or silently carrying over a previous session.\n\nShow the client the exact file to review or redact, and get their approval to include it before deploying; do not ask again once they approved that file. When they decline, move it out of the project root before deploying so it cannot be collected. Deploy includes the file in the build's private source archive, downloadable by those authorized to download that build's sources, and leaves it out of build inputs. A missing log warns but does not block deployment. The CLI does not export, redact or check the completeness of the transcript.","### Deploy and follow the build\n\n`pnpm phoenix deploy` starts a build on the server and waits for it to go live. Right after `Build <id> started` it prints `Follow the build in Studio: <url>`. Run the deploy so its output can be read while it runs, and open that link in the client's browser, quoted as above, as soon as it appears, so they can follow the build. When the line is missing, the sign-in predates the link: tell the client the build is listed under Deployments in Studio, and that `pnpm phoenix login <workspace>` brings the link back.\n\nWhen the deploy reports the configurator live, read [Feedback](feedback/index.md) before writing the final message and follow its evaluation procedure, so the client is asked about the run while they are still there. It is asked once per conversation, and only once the client has nothing more to build."].join("\n\n"),doneWhen:`- The preview runs and is open in the client's browser while work continues.
+- A deploy went live with its Studio link shown, or its failure is reported with the next step.`,example:"Before changing a finish, start `pnpm phoenix dev` in the background and open the printed preview address once. To deploy, refresh `conversation.log`, show it to the client for approval, run `pnpm phoenix deploy` and open the Studio link as soon as it is printed."});

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

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

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

@@ -0,0 +1,5 @@
+import{createPhoenixProcessGuide as e}from"../guide.js";let t=`1. Complete the specification for the full agreed scope: extend the [product definition](specification/product-definition.md), add [catalogs](specification/catalog.md) when components are numerous, and add the experience structure to the [UX guidelines](specification/ux-guidelines.md). An existing project without a specification derives its product definition from the implemented configurator and the client's materials; write branding and UX guidelines from the existing implementation only when the client agrees or the planned work needs them.
+2. Write \`.phoenix/workspace/plan.md\`: ordered increments, each with its outcome, acceptance checks and dependencies; deferred scope; and each open business question beside the increment that needs its answer.
+3. Order the increments by what users decide first and by real product dependencies. Put core interactions before more options, and finalization after the configuration it submits is stable.
+4. Present the plan in product language with a recommended first increment, and agree it before building out. Unanswered business questions do not block the plan; they wait at the increment that needs them.
+5. Keep the plan current as increments land, feedback arrives or the scope changes.`;export const generatePhoenixPlanning=()=>e({path:"processes/planning.md",title:"Planning",summary:"Complete the specification for the full scope and agree an ordered implementation plan; read when normal mode starts without an agreed plan or the scope changes substantially.",whenToUse:"When normal mode starts without an agreed plan, usually right after a first draft, and when the client changes the scope substantially. An isolated fix needs no plan.",steps:t,doneWhen:"- The specification covers the full agreed scope, with unknowns marked.\n- `.phoenix/workspace/plan.md` lists ordered increments with acceptance checks, and the client agreed the first one.",example:"For an office furniture range after its first draft: increment 1 adds the remaining chair models, 2 adds desks with width and height rules, 3 adds pricing once the price list arrives, and 4 replaces the first-draft email with the quote request the sales team needs. The plan notes that desk-leg compatibility is unknown and needed by increment 2."});

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

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