@salsita-ai/sdk 0.50.0-develop.c33986dc44 → 0.50.0-develop.c402728d10

package/dist/docs/phoenix/phoenix-cli.mdx

@@ -40,7 +40,31 @@ pnpm phoenix dev
 3. Adds the `dev`, `build`, `deploy`, `check` and `fix` scripts to `package.json` (see [Project Scripts](#project-scripts)). A script the project already has under one of those names keeps its command.
 4. Writes a starter spec (`spec/application.yaml`, `spec/configurator.yaml`) with one resizable, recolorable box, and switches `package.json` to the application-spec pipeline.
 
-The next steps it prints use the package manager you ran it with, or name none when it cannot tell. It asks nothing, writes no `.env` and contacts no server. `phoenix sync` then generates every other project file, including the agent skills described in [Project Structure](?path=/docs/phoenix-project-structure--docs). The `.gitignore` is among them only when the folder is inside a git repository, so run `git init` before the first sync, or sync again after it.
+The next steps it prints use the package manager you ran it with, or name none when it cannot tell. It asks nothing, writes no `.env` and contacts no Phoenix server. It does send the operational telemetry described below unless telemetry is disabled. `phoenix sync` then generates every other project file, including the agent skills described in [Project Structure](?path=/docs/phoenix-project-structure--docs). The `.gitignore` is among them only when the folder is inside a git repository, so run `git init` before the first sync, or sync again after it.
+
+### CLI telemetry
+
+Operational CLI telemetry is enabled by default. Recognized top-level `phoenix` commands send lifecycle events directly to Amplitude's US ingestion endpoint. Current commands record both started and completed events. Legacy commands retain their existing exit behavior, so completion may be absent when they exit directly, including when legacy `dev` stops.
+
+For `phoenix dev`, `cli_dev_server_ready` records that startup finished and the server is listening; it does not prove that a browser connected or the application works. Its `duration_ms` measures startup time. With the current application-spec pipeline, the command stays open until its existing shutdown path emits completion, whose duration covers the whole run. A normal stop is not evidence of abandonment, and a missing completion (for example after a forced kill) means the outcome is unknown.
+
+Aliases are recorded as their canonical command names. Delivery failures never change the command result, and the CLI stops waiting for each delivery after one second.
+
+Before a successful `phoenix login`, telemetry uses only random anonymous identifiers. Failed login attempts remain anonymous. The CLI stores an installation UUID, work-session UUID and last activity time in `~/.phoenix/telemetry.json`; a work session continues while commands occur less than 30 minutes apart.
+
+After a successful login, the login completion and later commands from that installation include the stable authenticated builder user ID and the internal workspace UUID. Amplitude uses the unchanged installation ID to associate the earlier anonymous command path with that user. A later successful login replaces the stored user and workspace association. The state file never contains a login token, email address, machine fingerprint, project path or project content. Because the installation ID belongs to the operating-system user profile, people who share that profile also share its command history and latest association.
+
+The events contain only:
+
+- schema version, source (`cli`) and command name;
+- unique event and command-attempt IDs;
+- occurrence time, phase, safe outcome/failure category and duration;
+- SDK version, traffic classification (`unknown` before authentication, `general` after it) and work-session ID;
+- after successful login only, the authenticated builder user ID and workspace UUID.
+
+The CLI never sends raw arguments, local paths, environment values, credentials, source/specification content, URLs, free text or raw error messages. The shipped Amplitude ingestion API key is public and only selects the destination project; it grants no read or administrative access. Events sent by a public client can be forged and are observations, not authoritative proof of deployment or server state.
+
+Set `PHOENIX_TELEMETRY_DISABLED=1` to opt out. The opted-out CLI neither sends telemetry nor creates or updates the state file. `PHOENIX_TELEMETRY_FILE` overrides the state path for tests and other isolated environments.
 
 ### Which project `phoenix dev` develops in
 
@@ -164,6 +188,8 @@ A project has one generated env file. Phoenix keeps it in `.phoenix/`, as `.phoe
 - The deployment and environment commands (`deployment:prepare`, `deployment:prepare-dev`, `deployment:prepare-local`, `deployment:build-envs` and the others with an `--outFile` option) write `.env.generated` in the project root unless `--outFile` or `OUT_FILE` names another file. Deploy pipelines read it there. Once one of them has written it, `phoenix dev` and `phoenix build` use it.
 - Everything that reads environment variables follows the same rule: the root `.env.generated` when it exists, otherwise `.phoenix/.env.generated`. The two files are never merged.
 - `phoenix clean` removes `.phoenix/` and with it `.phoenix/.env.generated`; the next `phoenix dev` prepares the development deployment again. A root `.env.generated` stays.
+- `phoenix dev` starts on the deployment the file names, and prepares a new one when the file was written for another project, environment or server, when the spec registers something on the server the deployment was not prepared with (the domain model, the published data schema, the auth hook, the roles that may create configurations, or the assistant), and on `--force`. A running `phoenix dev` does not prepare again after such a change: it logs an error that asks for a restart.
+- Asset contents do not trigger preparation. After changing uploaded assets, restart with `phoenix dev --force` to prepare and upload them again.
 
 This holds for a project on the application-spec pipeline. In a project on the legacy pipeline (see [Current and legacy project tooling](#current-and-legacy-project-tooling)), `phoenix dev` always reads and writes `.env.generated` in the project root.
 
@@ -305,14 +331,16 @@ Starts the full development environment: Vite dev server, development webhook tu
 | `--environmentSlug`     | `ENVIRONMENT_SLUG` | package.json name    | Environment slug                                                                |
 | `--withLingui`          | `WITH_LINGUI`      | `false`              | Enable i18n extraction/compilation and watch i18n sources during dev            |
 | `--persistence`         | `PERSISTENCE_MODE` | `server`             | Persistence mode                                                                |
-| `--force` / `-f`        | `FORCE_REBUILD`    | `false`              | Force full rebuild, skip cache                                                  |
+| `--force` / `-f`        | `FORCE_REBUILD`    | `false`              | Force full rebuild, skip cache, and prepare the development deployment again    |
 | `--serverUrl`           | `SERVER_URL`       | the region's server  | Phoenix server URL                                                              |
 | `--region`              | `PHOENIX_REGION`   | `eu`                 | Region of the signed-in workspace, used when no server URL is set               |
 | `--skipUpload` / `--su` | `SKIP_UPLOAD`      | `false`              | Skip the S3 asset upload when the development deployment is prepared at startup |
 
 With the application-spec pipeline, `phoenix dev` creates an empty `src/` folder when the project has none, so that it rebuilds when the first source file, such as `src/webhooks/index.ts`, is added.
 
-With the application-spec pipeline, the SDK's own Lingui CLI runs with the configuration in `.phoenix/.linguirc`, both for `--withLingui` and when `phoenix sync` and `phoenix build` extract and compile the catalogs; see [Root Level Files](?path=/docs/phoenix-project-structure--docs#root-level-files). The dev server and `phoenix build` compile the Lingui macros (`msg`, `t`, `Trans` and the others, imported from `@lingui/core/macro`, `@lingui/react/macro` or `@lingui/macro`) with the SDK's own Lingui macro plugin and the same configuration, so the project needs neither `babel-plugin-macros` nor `@lingui/macro` for them. Babel macros of other packages are not compiled.
+By default, with the application-spec pipeline, `phoenix dev` bootstraps missing compiled catalogs for every configured locale at startup, so a fresh project can start without a prior sync. It compiles existing `.po` translations as they are and extracts a locale only when its `.po` source is also missing. Existing compiled catalogs and `.po` sources stay unchanged. New or changed messages still need `phoenix sync` or continuous updates enabled by `--withLingui` or `WITH_LINGUI=true`.
+
+The SDK's own Lingui CLI uses the configuration generated in `.phoenix/.linguirc`, both for `--withLingui` and when `phoenix sync` and `phoenix build` extract and compile the catalogs; see [Root Level Files](?path=/docs/phoenix-project-structure--docs#root-level-files). The dev server and `phoenix build` compile the Lingui macros (`msg`, `t`, `Trans` and the others, imported from `@lingui/core/macro`, `@lingui/react/macro` or `@lingui/macro`) with the SDK's own Lingui macro plugin and the same configuration, so the project needs neither `babel-plugin-macros` nor `@lingui/macro` for them. Babel macros of other packages are not compiled.
 
 In `server` persistence mode the project comes from `--projectSlug`, `PROJECT_SLUG` or `project` in the spec, and the credential from `DEVELOPMENT_KEY` or the `phoenix login` sign-in; see [Starting a New Project](#starting-a-new-project). When signed in, the environment is always your own development environment and `--environmentSlug` is ignored.
 
@@ -320,6 +348,7 @@ The dev server watches for changes in:
 
 - `spec/**/*.yaml` — Domain specification files
 - `src/**/*.{ts,tsx,yaml,yml,json,html,css}` — Source files
+- `package.json` — Root dependency declarations; changes recheck the SDK's peers. A mismatch is reported without stopping dev, and correcting the manifest triggers another rebuild. Install changed dependencies with your package manager; changes to installed packages can still require restarting dev.
 - `.env` — Environment file; a change restarts the Vite dev server
 - `.env.generated`, `.phoenix/.env.generated` — Generated env files; a change rebuilds the project files. Only a file that exists when `phoenix dev` starts is watched: a root `.env.generated` that a deployment command creates while dev runs is not watched; restart `phoenix dev` to use it.
 
@@ -336,7 +365,11 @@ Restart the application after fixing either failure; a subscriber or generation
 observed the attempted update.
 
 Domain-model changes are not applied live yet. Phoenix rejects them with a restart-required
-diagnostic so the mounted application cannot observe a new model with old configuration data. Other
+diagnostic so the mounted application cannot observe a new model with old configuration data. With
+server persistence, `phoenix dev` logs an error that asks for its own restart, because the
+development deployment keeps the schema it was prepared with until `phoenix dev` starts again and
+prepares it. After the restart, open the preview address it prints: a tab whose address has `?cid=`
+loads a configuration saved with the earlier model, which the new model rejects. Other
 generated bootstrap, admin, data, environment, and host-integration surfaces should also be treated
 as restart-required unless their feature documentation explicitly states live-update support.
 
@@ -609,7 +642,7 @@ Known limits:
 - Binary assets, CSS files, locale catalog changes, dependency changes and edits requiring a full application restart are unsupported.
 - Storybook `story-dev` has no variant previews. A project on the legacy pipeline has no variant previews; the command says so and exits.
 
-Generated projects carry the `phoenix-variants` agent skill, which tells coding agents when to offer options, how to write each kind and what to do with your answer.
+Generated projects carry the `phoenix` agent skill, whose linked Variants guide tells coding agents when to offer options, how to write each kind and what to do with your answer.
 
 ## SDK Development
 
@@ -750,7 +783,7 @@ Revokes the token on the server and removes it from the credentials file. `--reg
 
 ### `phoenix deploy`
 
-Validates the spec, packs and uploads the project, starts its build on the server and follows it until the configurator is live. Before the upload the server compares the domain model with the deployed one: a model that changed under an already deployed model version is refused with the reason, and needs a new model version and a [migration](?path=/docs/phoenix-migrations--docs). Once the build starts it prints `Follow the build in Studio: <url>`, the build's page in the Studio you signed in through; a sign-in stored by an older CLI has no Studio URL, so sign in again to get the link. After `Your configurator is live at <url>` it prints one line for coding agents, which tells them to offer the run evaluation of the `phoenix-feedback` skill once you have nothing more to build; you can ignore it when you run the command yourself. `--region` or `--serverUrl` selects the server, as for `login`; `--no-wait` returns as soon as the build starts.
+Validates the spec, packs and uploads the project, starts its build on the server and follows it until the configurator is live. Before the upload the server compares the domain model with the deployed one: a model that changed under an already deployed model version is refused with the reason, and needs a new model version and a [migration](?path=/docs/phoenix-migrations--docs). Once the build starts it prints `Follow the build in Studio: <url>`, the build's page in the Studio you signed in through; a sign-in stored by an older CLI has no Studio URL, so sign in again to get the link. After `Your configurator is live at <url>` it prints one line for coding agents, which tells them to offer the run evaluation in the Feedback guide linked from the `phoenix` skill once you have nothing more to build; you can ignore it when you run the command yourself. `--region` or `--serverUrl` selects the server, as for `login`; `--no-wait` returns as soon as the build starts.
 
 To keep the conversation that led to a build, place a reviewed UTF-8 transcript in `conversation.log` at the project root before deploying. Deploy automatically includes it in the private source archive. Download the build's sources from Studio to read it; access is the same as for the rest of that build's sources. The build extractor skips the log, so it is not an application build input or a public asset. Missing logs produce a warning and deployment continues. Directories, links and special files at that path are rejected.
 
@@ -779,7 +812,7 @@ Pass the message as the argument for a short note, or `--file` for a longer repo
 
 A message holds at most 100,000 characters, from the argument or from the file. Besides the message and the flags, the CLI sends only the SDK version, the operating system and the Node.js version; no file of the project is attached, and the Phoenix team reads a build's sources through the build's page in Studio. The project must belong to the signed-in workspace, otherwise the server refuses the feedback; without a project, the feedback is sent on its own.
 
-Generated projects carry the `phoenix-feedback` agent skill. It tells coding agents when to draft feedback, to show you the draft and send it only after you approve it, and how to write a report: the build id with its Studio page link, the live configurator link, what the agent was doing, what happened and what was expected, the exact error or output, the workaround and a condensed conversation log. When you say you are done, or a deploy went live and you confirm the run is finished, the agent asks you to evaluate the run, one question at a time: minutes spent, then a score from 0 to 10 for the agent's guidance, the configurator's functionality, its UX, the quality of the 3D, the UI visuals and the overall result, then your comments. It never picks a score for you and sends nothing when you decline. Secrets, credentials and personal data never go into a message; file paths, spec and code snippets and your own words may, once you approved the draft that contains them. The command needs a server with API 1.40.0 or newer; a message over 5000 characters needs API 1.43.0 or newer.
+Generated projects carry the `phoenix` agent skill. Its linked Feedback guide tells coding agents when to draft feedback, to show you the draft and send it only after you approve it, and how to write a report: the build id with its Studio page link, the live configurator link, what the agent was doing, what happened and what was expected, the exact error or output, the workaround and a condensed conversation log. When you say you are done, or a deploy went live and you confirm the run is finished, the agent asks you to evaluate the run, one question at a time: minutes spent, then a score from 0 to 10 for the agent's guidance, the configurator's functionality, its UX, the quality of the 3D, the UI visuals and the overall result, then your comments. It never picks a score for you and sends nothing when you decline. Secrets, credentials and personal data never go into a message; file paths, spec and code snippets and your own words may, once you approved the draft that contains them. The command needs a server with API 1.40.0 or newer; a message over 5000 characters needs API 1.43.0 or newer.
 
 ## Next Steps
 

package/dist/docs/phoenix/project-structure.mdx

@@ -199,23 +199,23 @@ type CustomMaterial = Phx['AdminModel']['CustomMaterial']
 
 ### Root Level Files
 
-| File                                                   | Auto-Generated? | Notes                                 |
-| ------------------------------------------------------ | --------------- | ------------------------------------- |
-| `package.json`                                         | No              | Yours; see Dependencies               |
-| `tsconfig.json`                                        | Once            | Yours; see below                      |
-| `eslint.config.js`                                     | Once            | Yours; see below                      |
-| `prettier.config.js`                                   | Once            | Yours; see below                      |
-| `.prettierignore`                                      | No              | Optional and your own; see below      |
-| `pnpm-workspace.yaml`                                  | No              | Only with pnpm; see Package manager   |
-| `.gitignore`                                           | Partially       | Only in a git repository; see Markers |
-| `.env`                                                 | No              | Git-ignored, local config             |
-| `.env.example`                                         | No              | Template for env vars                 |
-| `.env.generated`                                       | Yes             | Optional, git-ignored; see below      |
-| `README.md`                                            | No              | Project documentation                 |
-| `AGENTS.md`                                            | No              | Your own coding-agent instructions    |
-| `.claude/skills/phoenix*/`, `.agents/skills/phoenix*/` | Yes             | Phoenix agent skills                  |
-
-Sync does not write `README.md`, `AGENTS.md`, `.env.example`, `.env.ci` or the `README.md` files in `assets/public/` and `assets/private/`. Earlier SDK versions wrote them once; a project that has them keeps them, and they are yours to edit.
+| File                                                 | Auto-Generated? | Notes                                 |
+| ---------------------------------------------------- | --------------- | ------------------------------------- |
+| `package.json`                                       | No              | Yours; see Dependencies               |
+| `tsconfig.json`                                      | Once            | Yours; see below                      |
+| `eslint.config.js`                                   | Once            | Yours; see below                      |
+| `prettier.config.js`                                 | Once            | Yours; see below                      |
+| `.prettierignore`                                    | No              | Optional and your own; see below      |
+| `pnpm-workspace.yaml`                                | No              | Only with pnpm; see Package manager   |
+| `.gitignore`                                         | Partially       | Only in a git repository; see Markers |
+| `.env`                                               | No              | Git-ignored, local config             |
+| `.env.example`                                       | No              | Template for env vars                 |
+| `.env.generated`                                     | Yes             | Optional, git-ignored; see below      |
+| `README.md`                                          | No              | Project documentation                 |
+| `AGENTS.md`                                          | No              | Your own coding-agent instructions    |
+| `.claude/skills/phoenix/`, `.agents/skills/phoenix/` | Yes             | Phoenix agent skills                  |
+
+With the application-spec pipeline, sync does not write `README.md`, `AGENTS.md`, `.env.example`, `.env.ci` or the `README.md` files in `assets/public/` and `assets/private/`. These files are yours to create and edit; sync preserves them. The legacy pipeline writes `README.md`, `.env.example`, `.env.ci` and the asset-folder `README.md` files when they are missing.
 
 Phoenix keeps the generated env file, with the IDs and values of the prepared deployment, in `.phoenix/` unless the project has a `.env.generated` in its root, which then is the one that counts. `phoenix dev` creates no `.env.generated` in the project root; the deployment and environment commands write it there. See [The generated env file](?path=/docs/phoenix-phoenix-cli--docs#the-generated-env-file).
 
@@ -242,9 +242,13 @@ With the application-spec pipeline, the Lingui configuration is `.phoenix/.lingu
 
 ### Agent Guidance
 
-Coding agents (Claude Code, Codex, Cursor) read the Phoenix agent skills. An `AGENTS.md` is yours to add for your own instructions; sync does not write one. The `phoenix`, `phoenix-cli`, `phoenix-feedback` and `phoenix-review` skills carry the SDK conventions, CLI tooling and review checklist, and the `phoenix-create-configurator` skill walks the agent from your product documents and assets to a reviewed configurator in five stages. The `phoenix-variants` skill has the agent show you several options over the dev preview when a decision is a matter of taste, and build the one you pick. Phoenix keeps them in step with the installed SDK, including the reference files inside a skill folder. During the internal beta, a project created from a canary build of the SDK gets one more section in the `phoenix` skill: once per conversation the agent checks for a newer canary and, after telling you, updates the project's SDK, runs `phoenix deps`, installs, then runs `phoenix sync`. Other skill folders are never touched.
+Coding agents (Claude Code, Codex, Cursor) enter through the single `phoenix` skill under `.claude/skills/phoenix/` or `.agents/skills/phoenix/`. Its `SKILL.md` routes to the existing project, CLI, configurator workflow, code review, variants and feedback guides in `references/`. Agents read the guides for their task rather than the whole tree. The configurator workflow retains its five stages and supporting discovery, UX, asset-conversion and appearance-review references.
 
-Projects created by earlier SDK versions had this guidance in `CLAUDE.md`, `.cursor/rules/phoenix.mdc` and `commands/review.md`. Sync removes the SDK block from the first two, keeps your own text around it, deletes a file that held nothing else, and deletes the review commands; use the `phoenix-review` skill instead of `/review`.
+Phoenix keeps this guidance in step with the installed SDK. During the internal beta, a project created from a canary build gets the canary-update instructions in the linked project guide: once per conversation the agent checks for a newer canary and, after telling you, updates the SDK, runs `phoenix deps`, installs, then runs `phoenix sync`.
+
+An `AGENTS.md` is yours to add; sync does not write one. Sync removes retired `phoenix-*` skill folders but leaves unrelated skills alone. If your own instructions name an earlier separate skill such as `phoenix-review`, point them at `phoenix` and the same task instead.
+
+Projects created by earlier SDK versions had this guidance in `CLAUDE.md`, `.cursor/rules/phoenix.mdc` and `commands/review.md`. Sync removes the SDK block from the first two, keeps your own text around it, deletes a file that held nothing else, and deletes the review commands; ask `phoenix` to review instead of using `/review`.
 
 ### Markers for Partial Auto-Generation
 

package/dist/docs/phoenix/sdk-builder-workflow.mdx

@@ -65,7 +65,7 @@ Every user who signs the CLI in gets their own development environment, so a tea
 
 Coding agents follow the generated `phoenix` skill: before their first change they start `phoenix dev` and open the preview in your browser, and after `phoenix deploy` starts a build they open its page in Studio.
 
-To build the configurator with your coding agent, give it your product documents, prices, pictures, drawings or models and ask it to create the configurator. The generated `phoenix-create-configurator` skill guides it through five stages: a representative first slice you can try early, a plan of the whole configuration experience, options and features added in small increments, finalization, and a complete review. It studies the SDK documentation before building, keeps a `configurator-spec.md` in the project as the record of what is decided and what remains open, and asks you only for decisions it cannot derive from your materials.
+To build the configurator with your coding agent, give it your product documents, prices, pictures, drawings or models and ask it to create the configurator. The generated `phoenix` skill’s Configurator workflow guide takes it through five stages: a representative first slice you can try early, a plan of the whole configuration experience, options and features added in small increments, finalization, and a complete review. It studies the SDK documentation before building, keeps a `configurator-spec.md` in the project as the record of what is decided and what remains open, and asks you only for decisions it cannot derive from your materials.
 
 ## 4. Deploy
 
@@ -99,7 +99,7 @@ Tell us what is broken, confusing or missing, from wherever you are:
 - In the terminal, `pnpm phoenix feedback "<message>" --type bug|idea|other` sends it with your sign-in, and `--file <path>` sends a text file instead of the argument. See the [CLI reference](?path=/docs/phoenix-phoenix-cli--docs).
 - On a build's page in Studio, **Download** → **Sources** downloads the archive `phoenix deploy` uploaded for that build, so a report only needs to name the build.
 
-Coding agents working in your project use the same command, guided by the generated `phoenix-feedback` skill. They never send on their own: an agent shows you a draft, right away when the problem is crucial and otherwise at the end of the task, and sends it only after you approve it. A report names the build with its Studio page link and the live configurator, says what the agent was doing, what happened and what it expected, quotes the exact error and ends with a condensed conversation log. Agents are told never to include secrets, credentials or personal data; parts of your project and your own words go in only through a draft you approved. When you are done with the configurator, the agent also asks you, once per conversation, to evaluate the run: minutes spent, then scores from 0 to 10 for the agent's guidance, functionality, UX, 3D quality, UI visuals and the overall result, and your comments. It asks one question at a time, never picks a score for you, tells you the answers go to the Phoenix team, shows the message and sends it only after you approve it.
+Coding agents working in your project use the same command, guided by the generated `phoenix` skill’s Feedback guide. They never send on their own: an agent shows you a draft, right away when the problem is crucial and otherwise at the end of the task, and sends it only after you approve it. A report names the build with its Studio page link and the live configurator, says what the agent was doing, what happened and what it expected, quotes the exact error and ends with a condensed conversation log. Agents are told never to include secrets, credentials or personal data; parts of your project and your own words go in only through a draft you approved. When you are done with the configurator, the agent also asks you, once per conversation, to evaluate the run: minutes spent, then scores from 0 to 10 for the agent's guidance, functionality, UX, 3D quality, UI visuals and the overall result, and your comments. It asks one question at a time, never picks a score for you, tells you the answers go to the Phoenix team, shows the message and sends it only after you approve it.
 
 ## Known limits
 

package/dist/docs/phoenix/webhooks.mdx

@@ -36,7 +36,11 @@ Phoenix provides domain-aware builders through the global `phx.webhooks` namespa
 
 Your webhook is the default export of `src/webhooks/index.ts`. With the application-spec pipeline (see [Current and legacy project tooling](?path=/docs/phoenix-phoenix-cli--docs#current-and-legacy-project-tooling)), the file is yours to create; sync does not write it. A project without it gets a built-in webhook, so it builds and deploys with no webhook code. The built-in webhook has one handler, an anonymous auth handler, which the platform calls only when `spec/application.yaml` sets `useAuthHook`. The legacy pipeline writes the file with that webhook on the first sync.
 
-Create `src/webhooks/index.ts` when the project needs its own handlers: finalization, backend data, or an auth handler that does more than start an anonymous session. A project that sets `useAuthHook` or `useClerk` needs its own auth handler, because the built-in one answers only anonymous requests. The smallest file is the built-in webhook itself:
+Create `src/webhooks/index.ts` when the project needs its own handlers: finalization, backend data, or an auth handler that does more than start an anonymous session.
+
+If `useAuthHook` or `useClerk` is enabled without this file, sync, build, clean and dev report `AUTH_WITHOUT_PROJECT_WEBHOOK` and generation continues with the anonymous-only built-in webhook. This warning also applies when `useAuthHook: false` is explicit alongside `useClerk: true`. Add a default-exported webhook with the required Clerk or custom auth handlers, or disable the settings if they are unintended.
+
+The smallest file is the built-in webhook itself:
 
 ```ts
 // src/webhooks/index.ts
@@ -1374,6 +1378,10 @@ export const emailTask = phx.webhooks.taskFactory.createSendEmailTask((resources
 
 The Backend Data Handler allows you to fetch data on the server that will be automatically made available both in the domain (client-side) and in webhook contexts. Its main purpose is to securely fetch data using API keys or other sensitive credentials that cannot be exposed to the client, while making that data available throughout your application.
 
+Responses of at least 32 KiB are automatically gzip-compressed when the caller accepts gzip and the base64 representation is smaller. Project handlers return the same `backendData` object; the API and configurator receive decoded JSON. This also works through `phoenix dev` when both the server and CLI support gzip. Older tunnel clients keep plain JSON.
+
+Compression does not remove platform limits: the complete encoded development-tunnel request must fit within 5 MiB, and deployed webhooks remain subject to Lambda's buffered response limit. The tunnel accepts up to 100 MiB of decoded gzip data. Data that does not compress enough must be reduced or split. Binary responses appear as a byte-count placeholder in the development tunnel inspector.
+
 ### Defining a Backend Data Handler
 
 Backend data handlers are defined inline in the webhook builder:

package/dist/domain/application/application-config.d.ts

@@ -9,6 +9,7 @@ import type { AdminIntegrationService } from '#package/react-sdk';
 import type { $DomainEntity, DataCellValue, DataSchema, DomainEntity, DomainFactory, ProductPreset } from '../core/index.js';
 import type { AnalyticsSystem, RegistrableTransformer, TransformerFactory } from '../domain-context/index.js';
 import type { ElementRegistration, ProjectModule } from '../domain-runtime/index.js';
+import type { AdminPagesSection } from '../spec/index.js';
 import type { AssistantResolvedManifest } from './assistant/index.js';
 import type { WebComponentEventDescriptor } from './web-component-event.js';
 import type { WebComponentPropertyDescriptor } from './web-component-property.js';
@@ -55,30 +56,11 @@ export type DataSpec = {
 export type ChunksSpec = Readonly<Record<string, {
     readonly scope: string;
 }>>;
-export type AdminPagesSpec = {
-    readonly presets?: boolean | {
-        readonly categoryNavigationState?: string;
-        readonly presetNavigationState?: string;
-    };
-    readonly recipes?: ReadonlyArray<{
-        readonly name: string;
-        readonly navigationState?: string;
-    }>;
-    readonly pages?: ReadonlyArray<{
-        readonly key: string;
-        readonly title: string;
-        readonly icon?: string;
-        readonly navigationState?: string;
-        readonly entity?: string;
-        readonly component?: string;
-        readonly actionsComponent?: string;
-        readonly connectedDataEntry?: string;
-        readonly sidebar?: {
-            readonly title: string;
-            readonly component: string;
-        };
-    }>;
-};
+/**
+ * The admin pages of an application config: the `$adminPages` section of the application spec as
+ * written, which `createAdminPagesFromSpec` turns into admin pages; see {@link AdminPagesSection}.
+ */
+export type AdminPagesSpec = AdminPagesSection;
 type PersistenceConfig = {
     readonly type: 'server';
     /**

package/dist/domain/application/assistant/assistant-manifest.d.ts

@@ -8,18 +8,28 @@ export interface AssistantFieldSource {
     readonly source: string;
     readonly localized?: true;
 }
+/**
+ * What the integrator promises about a list of choices, so the agent can read it once and reuse it:
+ * `sameForAllInstances` when every entity of the type gets the same list, `constantDuringSession`
+ * when the list does not change during a session. A hint only adds a sentence to the description of
+ * the recipe group or options edge it is declared on; nothing verifies it.
+ */
+export declare const ASSISTANT_HINTS: readonly ['sameForAllInstances', 'constantDuringSession'];
+export type AssistantResolvedHint = (typeof ASSISTANT_HINTS)[number];
 /**
  * One recipe group the assistant manifest exposes on an entity type: a `childEntityRecipes` instance
  * under `childRecipes`, a `replaceEntityRecipes` instance under `replaceRecipes`. `groupId` is the
- * name the agent addresses the group by, `instanceName` the component instance it reads,
- * `description` the manifest's text replacing the component's group description, and `dryRuns`
- * whether the recipes of the group can be dry-run.
+ * name of its field on `<Type>ChildRecipes` or `<Type>ReplaceRecipes` and the id the agent passes to
+ * `addChild` or `replaceEntity`, `instanceName` the component instance it reads, `description` the
+ * manifest's text for that field, `dryRuns` whether the recipes of the group can be dry-run, and
+ * `hints` the sentences of the field's description saying when the agent can reuse what it read.
  */
 export interface AssistantRecipeGroup {
     readonly groupId: string;
     readonly instanceName: string;
     readonly description?: string;
     readonly dryRuns: boolean;
+    readonly hints: readonly AssistantResolvedHint[];
 }
 /**
  * The options edge of one writable field the assistant manifest links to its component. `field` is

package/dist/domain/application/assistant/assistant-manifest.js

@@ -1 +1 @@
-export{};
+export const ASSISTANT_HINTS=["sameForAllInstances","constantDuringSession"];

package/dist/domain/application/assistant/assistant-resolved-manifest.d.ts

@@ -1,4 +1,4 @@
-import type { AssistantFieldOptions, AssistantRecipeGroup, AssistantScreenshotView } from './assistant-manifest.js';
+import type { AssistantFieldOptions, AssistantRecipeGroup, AssistantResolvedHint, AssistantScreenshotView } from './assistant-manifest.js';
 import type { AssistantFormElementDescriptor } from './form/index.js';
 /** JSON description of a scalar or recursively nested list, including nullability at each level. */
 export type AssistantValueType = {
@@ -54,6 +54,8 @@ export interface AssistantResolvedManifest {
     /** The screenshot views of each entity type with at least one, aliases expanded, in manifest order. */
     readonly screenshots: Readonly<Record<string, readonly AssistantScreenshotView[]>>;
     readonly actionFields: readonly AssistantResolvedAction[];
+    /** The entity types that declare invariants, whose `meta` lists the warnings and notices they hold. */
+    readonly invariantTypes: readonly string[];
     /** The declared lenses by name: when to use each, and how many levels its tagged relations nest. */
     readonly lenses: Readonly<Record<string, {
         readonly description: string;
@@ -74,14 +76,8 @@ export interface AssistantWritableType {
     readonly entityType: string;
     readonly fields: readonly AssistantWritableField[];
 }
-/** Description hints resolved from recipe/option entries; no parse context is retained. */
-export declare const ASSISTANT_HINTS: readonly ['sameForAllInstances', 'constantDuringSession'];
-export type AssistantResolvedHint = (typeof ASSISTANT_HINTS)[number];
-/** Recipe groups and their description hints for one entity type. */
-export interface AssistantResolvedRecipes {
-    readonly groups: readonly AssistantRecipeGroup[];
-    readonly hints: readonly AssistantResolvedHint[];
-}
+/** The recipe groups of one kind on one entity type or alias key, in manifest order, each with its own hints. */
+export type AssistantResolvedRecipes = readonly AssistantRecipeGroup[];
 /** One options edge, carrying the write-validation contract and schema description hints. */
 export interface AssistantResolvedOptionsEdge {
     readonly options: AssistantFieldOptions;

package/dist/domain/application/assistant/assistant-resolved-manifest.js

@@ -1 +1 @@
-export const ASSISTANT_HINTS=["sameForAllInstances","constantDuringSession"];
+export{};

package/dist/domain/application/assistant/build-assistant-lenses.js

@@ -1,4 +1,4 @@
-import{NoUnusedFragmentsRule as e,parse as t,specifiedRules as i,validate as n}from"graphql";let s="AnyDomainEntity",r=[{name:"RecipeGroup",description:"A recipe group with its recipes, without their dry-runs.",selections:["groupId","name","description","recipes { ...Recipe }"]},{name:"Recipe",description:"A recipe without its dry-run.",selections:["key","name","description","imageUrl"]},{name:"FieldOption",description:"A value a field accepts, without its dry-run.",selections:["value","name","description","imageUrl","color"]},{name:"DryRun",description:"What a dry-run would do, with the ids of the entities it would change instead of the entities.",selections:["ok","deletedEntityIds","sideEffects","errors { type entityId message }","changedEntities { id }"]}],a=(e,t)=>0===t?e:`${e}__${t}`,l=e=>e.split("\n").map(e=>`# ${e}`.trimEnd()).join("\n"),o=(e,t,i)=>[`fragment ${e} on ${t} {`,...i.map(e=>`  ${e}`),"}"].join("\n"),p=(e,t,i)=>{let n=e=>"edge"===e.type.kind?`${e.name} { ${i} }`:e.name;return o(e,s,["id",...t.flatMap(({typeName:e,fields:t})=>e===s?t.map(n):[`... on ${e} {`,...t.map(e=>`  ${n(e)}`),"}"])])};export const buildAssistantLenses=(d,m)=>{let c=Object.entries(d.lenses).flatMap(([e,t])=>{let i=[s,...Object.keys(d.aliases).filter(e=>e!==s),...d.entityTypes].flatMap(t=>{let i=(d.fields[t]??[]).filter(t=>t.lenses?.includes(e));return i.length>0?[{typeName:t,fields:i}]:[]});return i.length>0?[{name:e,...t,conditions:i}]:[]}),$=r.filter(({name:e})=>void 0!==m.getType(e)),h=[...c.map(({name:e,description:t,maxDepth:i,conditions:n})=>{let s=n.some(({fields:e})=>e.some(e=>"edge"===e.type.kind));return`${l(s?`${t} ${`Nested relations carry the same selection up to ${i} ${1===i?"level":"levels"}, below that only \`id\`.`}`:t)}
+import{NoUnusedFragmentsRule as e,parse as t,specifiedRules as i,validate as n}from"graphql";let s="AnyDomainEntity",r=[{name:"RecipeGroup",description:"A recipe group with its recipes, without their dry-runs.",selections:["groupId","name","description","recipes { ...Recipe }"]},{name:"Recipe",description:"A recipe without its dry-run.",selections:["key","name","description","imageUrl"]},{name:"FieldOption",description:"A value a field accepts, without its dry-run.",selections:["value","name","description","imageUrl","color"]},{name:"DryRun",description:"What a dry-run would do, with the ids of the entities it would change instead of the entities.",selections:["ok","deletedEntityIds","sideEffects","warnings","errors { type entityId message }","changedEntities { id }"]}],a=(e,t)=>0===t?e:`${e}__${t}`,l=e=>e.split("\n").map(e=>`# ${e}`.trimEnd()).join("\n"),o=(e,t,i)=>[`fragment ${e} on ${t} {`,...i.map(e=>`  ${e}`),"}"].join("\n"),p=(e,t,i)=>{let n=e=>"edge"===e.type.kind?`${e.name} { ${i} }`:e.name;return o(e,s,["id",...t.flatMap(({typeName:e,fields:t})=>e===s?t.map(n):[`... on ${e} {`,...t.map(e=>`  ${n(e)}`),"}"])])};export const buildAssistantLenses=(d,m)=>{let c=Object.entries(d.lenses).flatMap(([e,t])=>{let i=[s,...Object.keys(d.aliases).filter(e=>e!==s),...d.entityTypes].flatMap(t=>{let i=(d.fields[t]??[]).filter(t=>t.lenses?.includes(e));return i.length>0?[{typeName:t,fields:i}]:[]});return i.length>0?[{name:e,...t,conditions:i}]:[]}),$=r.filter(({name:e})=>void 0!==m.getType(e)),h=[...c.map(({name:e,description:t,maxDepth:i,conditions:n})=>{let s=n.some(({fields:e})=>e.some(e=>"edge"===e.type.kind));return`${l(s?`${t} ${`Nested relations carry the same selection up to ${i} ${1===i?"level":"levels"}, below that only \`id\`.`}`:t)}
 ${p(e,n,`...${e}`)}`}),...$.map(({name:e,description:t,selections:i})=>`${l(t)}
 ${o(e,e,i)}`)].join("\n\n"),u=[...c.flatMap(({name:e,maxDepth:t,conditions:i})=>Array.from({length:t+1},(n,s)=>p(a(e,s),i,s<t?`...${a(e,s+1)}`:"id"))),...$.map(({name:e,selections:t})=>o(e,e,t))].join("\n\n");if(""!==u){let s=c.length>0?`entities { ${c.map(({name:e})=>`...${e}`).join(" ")} }`:"__typename",r=n(m,t(`${u}
 

package/dist/domain/application/assistant/build-assistant-manifest.js

@@ -1 +1 @@
-import{GraphQLBoolean as e,GraphQLEnumType as t,GraphQLID as n,GraphQLInputObjectType as i,GraphQLInterfaceType as s,GraphQLList as r,GraphQLNonNull as o,GraphQLObjectType as a,GraphQLSchema as p,GraphQLString as c,printSchema as d,validateSchema as l}from"graphql";import{GraphQLJSON as h,createAssistantValueType as w}from"./assistant-value-type.js";import{buildAssistantLenses as y}from"./build-assistant-lenses.js";import{createAssistantExecutionSchema as u}from"./create-assistant-execution-schema.js";let m="AnyDomainEntity",f="RootEntity",g=[["navigationState","Active navigation state.","navigationStates"],["viewState","Active view state.","viewStates"],["toolState","Active tool state.","toolStates"]],b={section:"childRecipes",mutation:"addChild"},v={section:"replaceRecipes",mutation:"replaceEntity"},j=(e,t)=>Object.entries(e).find(([e])=>e===t)?.[1],$=(e,t)=>{if(!t||0===t.length)return e;let n=`One of: ${t.map(e=>`"${e}"`).join(", ")}.`;return e?/[.!?]$/.test(e)?`${e} ${n}`:`${e}. ${n}`:n},O=({target:e,cardinality:t},n)=>{let i=n(e);switch(t){case"1-1":return new o(i);case"0-1":return i;case"0-N":case"1-N":return new o(new r(new o(i)))}},E=(e,t,i)=>{let s={id:{type:new o(n),description:i?`Unique id of the entity, assigned by the configurator, e.g. "${i}-1".`:void 0},type:{type:new o(c),description:i?`Entity type name, e.g. "${i}".`:void 0}};for(let n of e)s[n.name]={type:"edge"===n.type.kind?O(n.type,t):w(n.type.type),description:n.description};return s},R=e=>Object.fromEntries(e.map(({name:e,source:t,localized:n})=>[e,n?{source:t,localized:!0}:{source:t}])),k={sameForAllInstances:e=>`Same recipe groups and recipes for every ${e}.`,constantDuringSession:()=>"Fixed for the session."},T={sameForAllInstances:e=>`Same for every ${e}.`,constantDuringSession:()=>"Fixed for the session."},I=(e,t,n)=>e.map(e=>` ${t[e](n)}`).join(""),N=({section:e},{groups:t,hints:n},{entityType:i,purpose:s,recipeGroup:a})=>{let p=t.filter(({dryRuns:e})=>!e).map(({groupId:e})=>e);return 0===t.length?{}:{[e]:{type:new o(new r(new o(a))),description:`The recipe groups for ${s} this ${i}: ${t.map(({groupId:e})=>e).join(", ")}. A group is listed only while the configurator offers it on the entity.${p.length>0?` Recipes of these groups cannot be dry-run: ${p.join(", ")}.`:""}${I(n,k,i)}`}}},A=({entityType:e,childRecipes:n,replaceRecipes:i,optionsEdges:s,screenshots:p},{recipeGroup:c,fieldOption:d,screenshot:l})=>new a({name:`${e}Meta`,fields:Object.assign(N(b,n,{entityType:e,purpose:"adding children to",recipeGroup:c}),N(v,i,{entityType:e,purpose:"replacing",recipeGroup:c}),...s.map(({options:{edgeName:t,field:n,validate:i,dryRuns:s},hints:a})=>({[t]:{type:new r(new o(d)),description:`Values "${n}" accepts on this ${e}. Null when there is no choice to make.${i?"":" Not checked on write."}${s?"":" Cannot be dry-run."}${I(a,T,e)}`}})),0===p.length?{}:{screenshot:{type:l,args:{view:{type:new o(new t({name:`${e}ScreenshotView`,values:Object.fromEntries(p.map(({view:e,description:t})=>[e,{description:t}]))}))}},description:"Renders this entity from a predefined view. The picture follows the tool result as an image labelled with `image`. Each one costs tokens and blocks the user's configurator while it renders: ask only when seeing the design answers something the data cannot. The images of one call share a size budget; past it, further screenshots come back null. Null as well when the view does not apply to this entity right now."}})}),S=e=>Object.entries(e).map(([e,t])=>`${e} (${t.map(({groupId:e})=>e).join(", ")})`);export const buildAssistantManifest=t=>{var O,k,T,I,N;let M,D,F,W,{entityTypes:x,aliases:C,exampleType:q,fields:G,states:U,deletableTypes:K,writableTypes:V,actionFields:z,optionsEdges:P}=t,L=Object.fromEntries(Object.entries(t.childRecipes).map(([e,t])=>[e,t.groups])),Q=Object.fromEntries(Object.entries(t.replaceRecipes).map(([e,t])=>[e,t.groups])),B=new Map,H=new Map,J=new Map,X=e=>{let[t,...n]=Object.entries(C).find(([t])=>t===e)?.[1]??[];return(t&&0===n.length?H.get(t):void 0)??J.get(e)??Z},Y=e=>H.get(e)??X(e),Z=new s({name:m,description:"Every entity of the configuration.",fields:()=>E(G[m]??[],Y,q)});for(let e of(J.set(m,Z),Object.keys(C)))e!==m&&J.set(e,new s({name:e,interfaces:[Z],fields:()=>E(G[e]??[],Y)}));let _={};for(let e of x){let t=[m,...Object.entries(C).filter(([t,n])=>t!==m&&n.includes(e)).map(([e])=>e)],n=G[e]??[];_[e]=R(n),H.set(e,new a({name:e,interfaces:t.flatMap(e=>J.get(e)??[]),fields:()=>{let t=B.get(e);return{...E(n,Y),...t?{meta:{type:new o(t),description:"What can be done to this entity right now."}}:{}}}}))}let ee=(O=()=>X(J.has(f)?f:m),k=()=>X(m),M=new a({name:"DryRunError",description:"One reason a change cannot be made right now.",fields:{type:{type:new o(c),description:"Kind of the problem."},entityId:{type:n,description:"The entity the problem is on, when it is on one."},message:{type:c,description:"The problem as the user would be told it."}}}),new a({name:"DryRun",description:"What using a recipe or writing an option would do, tried out on the configuration the query reads. Nothing is changed.",fields:()=>({ok:{type:new o(e),description:"Whether the change would succeed on the configuration the query reads."},root:{type:O(),description:"The root entity of the configuration as it would be after the change; null when ok is false. Everything selected under it reads that configuration."},changedEntities:{type:new o(new r(new o(k()))),description:"Entities the change would add or modify; empty when ok is false. One whose id is not in the configuration would be added, and its real id may differ. An entity written to is listed even when its values stay the same."},deletedEntityIds:{type:new o(new r(new o(n))),description:"The ids of the entities the change would remove; empty when ok is false."},sideEffects:{type:new o(new r(new o(c))),description:"The major or unexpected things the configurator would change along with it; empty when ok is false."},errors:{type:new o(new r(new o(M))),description:"Why the change cannot be made; empty when ok is true."}})})),et={recipeGroup:(T=[...Object.keys(L).length>0?[b.mutation]:[],...Object.keys(Q).length>0?[v.mutation]:[]],D=T.join(" or "),F=new a({name:"Recipe",description:`${T.includes("addChild")?"One thing that can be added to the entity (under childRecipes)":"One thing the entity can be replaced with (under replaceRecipes)"}${T.length>1?" or that it can be replaced with (under replaceRecipes)":""}.`,fields:{key:{type:new o(c),description:`Pass to ${D} as recipeKey. Valid only for the listing it came from.`},name:{type:new o(c),description:"Name shown to the user."},description:{type:c},imageUrl:{type:c,description:"Thumbnail shown to the user."},dryRun:{type:ee,description:"What using this recipe would do. Null when it cannot be tried."}}}),new a({name:"RecipeGroup",description:"A group of recipes for this entity.",fields:{groupId:{type:new o(c),description:`Pass to ${D} as recipeGroupId.`},name:{type:new o(c),description:"Name shown to the user."},description:{type:c},recipes:{type:new o(new r(new o(F)))}}})),fieldOption:new a({name:"FieldOption",description:"One value a field accepts. Writing a value outside the list is rejected unless the field description says it is not checked.",fields:{value:{type:new o(h),description:"The value to write to the field."},name:{type:c,description:"Name shown to the user."},description:{type:c},imageUrl:{type:c,description:"Image shown to the user."},color:{type:c,description:'Color shown to the user, as "#rrggbb".'},dryRun:{type:ee,description:"What writing this value would do. Null when it cannot be tried."}}}),screenshot:new a({name:"Screenshot",description:"A screenshot of an entity. The picture itself follows the tool result.",fields:{image:{type:new o(n),description:"Label of the image that follows the tool result."}}})};for(let e of x){let n=j(t.childRecipes,e)??{groups:[],hints:[]},i=j(t.replaceRecipes,e)??{groups:[],hints:[]},s=j(P,e)??[],r=j(t.screenshots,e)??[];(n.groups.length>0||i.groups.length>0||s.length>0||r.length>0)&&B.set(e,A({entityType:e,childRecipes:n,replaceRecipes:i,optionsEdges:s.map(t=>({...t,hints:(C[f]??[]).includes(e)?t.hints.filter(e=>"sameForAllInstances"!==e):t.hints})),screenshots:r},et))}let en=new p({query:(I=X(J.has(f)?f:m),N=X(m),W=(e=>{let t={};for(let[n,i,s]of g){let r=e[s];r.length>1&&(t[n]={type:new o(c),description:$(i,r)})}if(0!==Object.keys(t).length)return new a({name:"Navigation",description:"The active UI states of the configurator.",fields:t})})(U),new a({name:"Query",fields:{root:{type:new o(I),description:"The root entity of the configuration."},entities:{type:new o(new r(N)),args:{ids:{type:new r(new o(n))}},description:"Every entity, or the given ids in order with null for an unknown id."},selectedEntity:{type:new o(N),description:"The selected entity, or the root entity when nothing is selected."},...W?{navigation:{type:new o(W)}}:{}}})),mutation:(({deletableTypes:e,writableTypes:t,childRecipes:s,replaceRecipes:p,actionFields:d,objectTypes:l,anyDomainEntity:h,targetOutputType:y})=>{let u,m;if(0!==e.length||0!==t.length||0!==Object.keys(s).length||0!==Object.keys(p).length||0!==d.length)return new a({name:"Mutation",fields:Object.assign(0===e.length?{}:{deleteEntity:{type:new o(new r(new o(n))),args:{id:{type:new o(n)}},description:`Deletes the entity and everything composed into it. Deletable types: ${e.join(", ")}. Returns the ids removed, the given one first.`}},0===(u=S(s)).length?{}:{addChild:{type:new o(new r(new o(h))),args:{parentId:{type:new o(n)},recipeGroupId:{type:new o(c)},recipeKey:{type:new o(c)}},description:`Adds a child to the entity parentId from a recipe listed under its meta { childRecipes }. Types with child recipes: ${u.join("; ")}. Returns the entities added, the recipe's own first; empty when they were removed again.`}},0===(m=S(p)).length?{}:{replaceEntity:{type:new o(new r(new o(h))),args:{entityId:{type:new o(n)},recipeGroupId:{type:new o(c)},recipeKey:{type:new o(c)}},description:`Replaces the entity entityId from a recipe listed under its meta { replaceRecipes }. Types with replace recipes: ${m.join("; ")}. The replacement is a new entity: it has a new id and the field values of its recipe, and entityId no longer exists. Returns the entities added, the replacement first; empty when they were removed again.`}},...t.flatMap(e=>{let t=l.get(e.entityType);return t?[(({entityType:e,fields:t},s)=>{let r=Object.fromEntries(t.map(({name:e,type:t,description:n})=>[e,{type:w(t),description:n}]));return{[`modify${e}`]:{type:s,args:{id:{type:new o(n)},delta:{type:new o(new i({name:`${e}Delta`,fields:r}))}},description:`Sets the fields named in delta on one ${e}. Returns the entity after the change, or null when the change removed it.`}}})(e,t)]:[]}),Object.fromEntries(d.map(e=>{var t;return[e.fieldName,{type:new o(new a({name:(t=e.fieldName,`${t.charAt(0).toUpperCase()+t.slice(1)}Result`),description:`What ${e.fieldName} returns, read from the configuration after the change.`,fields:()=>Object.fromEntries(Object.entries(e.result).map(([e,t])=>[e,{type:"edge"===t.kind?(({target:e,list:t,nullable:n},i)=>{let s=t?new r(new o(i(e))):i(e);return n?s:new o(s)})(t,y):w(t.type),description:t.description}]))})),args:Object.fromEntries(Object.entries(e.args).map(([e,t])=>[e,{type:w(t.type),description:t.description}])),description:e.description}]})))})})({deletableTypes:K,writableTypes:V,childRecipes:L,replaceRecipes:Q,actionFields:z,objectTypes:H,anyDomainEntity:X(m),targetOutputType:Y}),types:[...J.values(),...H.values()]}),ei=l(en);if(ei.length>0)throw Error(ei.map(e=>e.message).join(" "));let es=d(en);return{sdl:es,navigationFields:g.filter(([,,e])=>U[e].length>1).map(([e])=>e),fields:_,deletableTypes:K,writableFields:Object.fromEntries(V.map(({entityType:e,fields:t})=>[e,Object.fromEntries(t.map(({name:e,property:t})=>[e,t]))])),childRecipes:L,replaceRecipes:Q,fieldOptions:Object.fromEntries(x.flatMap(e=>{let t=j(P,e);return t?[[e,t.map(({options:e})=>e)]]:[]})),screenshots:Object.fromEntries(x.flatMap(e=>{let n=j(t.screenshots,e);return n?[[e,n]]:[]})),actions:Object.fromEntries(z.map(({fieldName:e,actionName:t})=>[e,t])),lenses:y(t,u(es)),formElements:t.formElements}};
+import{GraphQLBoolean as e,GraphQLEnumType as t,GraphQLID as n,GraphQLInputObjectType as i,GraphQLInterfaceType as s,GraphQLList as r,GraphQLNonNull as o,GraphQLObjectType as a,GraphQLSchema as p,GraphQLString as d,printSchema as c,validateSchema as l}from"graphql";import{GraphQLJSON as h,createAssistantValueType as w}from"./assistant-value-type.js";import{buildAssistantLenses as y}from"./build-assistant-lenses.js";import{createAssistantExecutionSchema as u}from"./create-assistant-execution-schema.js";let g="AnyDomainEntity",f="RootEntity",m=[["navigationState","Active navigation state.","navigationStates"],["viewState","Active view state.","viewStates"],["toolState","Active tool state.","toolStates"]],b={section:"childRecipes",mutation:"addChild",typeSuffix:"ChildRecipes"},v={section:"replaceRecipes",mutation:"replaceEntity",typeSuffix:"ReplaceRecipes"},$=(e,t)=>Object.entries(e).find(([e])=>e===t)?.[1],j=(e,t)=>{if(!t||0===t.length)return e;let n=`One of: ${t.map(e=>`"${e}"`).join(", ")}.`;return e?/[.!?]$/.test(e)?`${e} ${n}`:`${e}. ${n}`:n},O=({target:e,cardinality:t},n)=>{let i=n(e);switch(t){case"1-1":return new o(i);case"0-1":return i;case"0-N":case"1-N":return new o(new r(new o(i)))}},E=(e,t,i)=>{let s={id:{type:new o(n),description:i?`Unique id of the entity, assigned by the configurator, e.g. "${i}-1".`:void 0},type:{type:new o(d),description:i?`Entity type name, e.g. "${i}".`:void 0}};for(let n of e)s[n.name]={type:"edge"===n.type.kind?O(n.type,t):w(n.type.type),description:n.description};return s},R=e=>Object.fromEntries(e.map(({name:e,source:t,localized:n})=>[e,n?{source:t,localized:!0}:{source:t}])),k=new o(new r(new o(h))),T=' Each is { type, severity, entityId, message }: severity is "warning" or "notice", entityId the entity it is on or null, message the warning as the user would be told it or null.',I={sameForAllInstances:e=>`Same recipes for every ${e}.`,constantDuringSession:()=>"Fixed for the session."},N={sameForAllInstances:e=>`Same for every ${e}.`,constantDuringSession:()=>"Fixed for the session."},S=(e,t,n)=>e.map(e=>` ${t[e](n)}`).join(""),A=({section:e,typeSuffix:t},n,{entityType:i,purpose:s,recipeGroup:r})=>0===n.length?{}:{[e]:{type:new o(new a({name:`${i}${t}`,fields:Object.fromEntries(n.map(({groupId:e,description:t,dryRuns:n,hints:s})=>{let o;return[e,{type:r,description:`${!(o=t?.trim())?"":/[.!?]$/.test(o)?`${o} `:`${o}. `}Null while the configurator does not offer it on the entity.${n?"":" Cannot be dry-run."}${S(s,I,i)}`}]}))})),description:`The recipe groups for ${s} this ${i}, one field each.`}},M=({entityType:e,childRecipes:n,replaceRecipes:i,optionsEdges:s,screenshots:p,hasInvariants:d},{recipeGroup:c,fieldOption:l,screenshot:w})=>new a({name:`${e}Meta`,fields:Object.assign(A(b,n,{entityType:e,purpose:"adding children to",recipeGroup:c}),A(v,i,{entityType:e,purpose:"replacing",recipeGroup:c}),...s.map(({options:{edgeName:t,field:n,validate:i,dryRuns:s},hints:a})=>({[t]:{type:new r(new o(l)),args:{values:{type:new r(new o(h)),description:"Only the options with these values; values not listed are ignored."}},description:`Values "${n}" accepts on this ${e}. Null when there is no choice to make.${i?"":" Not checked on write."}${s?"":" Cannot be dry-run."}${S(a,N,e)}`}})),0===p.length?{}:{screenshot:{type:w,args:{view:{type:new o(new t({name:`${e}ScreenshotView`,values:Object.fromEntries(p.map(({view:e,description:t})=>[e,{description:t}]))}))}},description:"Renders this entity from a predefined view. The picture follows the tool result as an image labelled with `image`. Null when the view does not apply to this entity right now."}},d?{warnings:{type:k,description:`The warnings and notices this ${e} has right now.${T}`}}:{})}),D=(e,t)=>t?e?"What can be done to this entity right now, and its warnings.":"The warnings of this entity right now.":"What can be done to this entity right now.",W=e=>Object.entries(e).map(([e,t])=>`${e} (${t.map(({groupId:e})=>e).join(", ")})`);export const buildAssistantManifest=t=>{var O,I,N,S,A;let x,C,F,q,{entityTypes:G,aliases:U,exampleType:K,fields:P,states:V,deletableTypes:z,writableTypes:L,actionFields:Q,optionsEdges:B,invariantTypes:H}=t,{childRecipes:J,replaceRecipes:X}=t,Y=new Map,Z=new Map,_=new Map,ee=e=>{let[t,...n]=Object.entries(U).find(([t])=>t===e)?.[1]??[];return(t&&0===n.length?Z.get(t):void 0)??_.get(e)??en},et=e=>Z.get(e)??ee(e),en=new s({name:g,description:"Every entity of the configuration.",fields:()=>E(P[g]??[],et,K)});for(let e of(_.set(g,en),Object.keys(U)))e!==g&&_.set(e,new s({name:e,interfaces:[en],fields:()=>E(P[e]??[],et)}));let ei={};for(let e of G){let t=[g,...Object.entries(U).filter(([t,n])=>t!==g&&n.includes(e)).map(([e])=>e)],n=P[e]??[];ei[e]=R(n),Z.set(e,new a({name:e,interfaces:t.flatMap(e=>_.get(e)??[]),fields:()=>{let t=Y.get(e);return{...E(n,et),...t?{meta:{type:new o(t.type),description:t.description}}:{}}}}))}let es=(O=()=>ee(_.has(f)?f:g),I=()=>ee(g),x=new a({name:"DryRunError",description:"One reason a change cannot be made right now.",fields:{type:{type:new o(d),description:"Kind of the problem."},entityId:{type:n,description:"The entity the problem is on, when it is on one."},message:{type:d,description:"The problem as the user would be told it."}}}),new a({name:"DryRun",description:"What using a recipe or writing an option would do, tried out on the configuration the query reads. Nothing is changed.",fields:()=>({ok:{type:new o(e),description:"Whether the change would succeed on the configuration the query reads."},root:{type:O(),description:"The root entity of the configuration as it would be after the change; null when ok is false. Everything selected under it reads that configuration."},changedEntities:{type:new o(new r(new o(I()))),description:"Entities the change would add or modify; empty when ok is false. One whose id is not in the configuration would be added, and its real id may differ. An entity written to is listed even when its values stay the same."},deletedEntityIds:{type:new o(new r(new o(n))),description:"The ids of the entities the change would remove; empty when ok is false."},sideEffects:{type:new o(new r(new o(d))),description:"The major or unexpected things the configurator would change along with it; empty when ok is false."},warnings:{type:k,description:`The warnings and notices the change would newly cause, which do not stop it; empty when ok is false.${T}`},errors:{type:new o(new r(new o(x))),description:"Why the change cannot be made; empty when ok is true."}})})),er={recipeGroup:(N=[...Object.keys(J).length>0?[b.mutation]:[],...Object.keys(X).length>0?[v.mutation]:[]],C=N.join(" or "),F=new a({name:"Recipe",description:`${N.includes("addChild")?"One thing that can be added to the entity (under childRecipes)":"One thing the entity can be replaced with (under replaceRecipes)"}${N.length>1?" or that it can be replaced with (under replaceRecipes)":""}.`,fields:{key:{type:new o(d),description:`Pass to ${C} as recipeKey, or to recipes(keys:) to read this recipe again.`},name:{type:new o(d),description:"Name shown to the user."},description:{type:d},imageUrl:{type:d,description:"Thumbnail shown to the user."},dryRun:{type:es,description:"What using this recipe would do. Null when it cannot be tried."}}}),new a({name:"RecipeGroup",description:"A group of recipes for this entity.",fields:{groupId:{type:new o(d),description:`Pass to ${C} as recipeGroupId.`},name:{type:new o(d),description:"Name shown to the user."},description:{type:d},recipes:{type:new o(new r(new o(F))),args:{keys:{type:new r(new o(d)),description:"Only the recipes with these keys; keys not in the group are ignored."}}}}})),fieldOption:new a({name:"FieldOption",description:"One value a field accepts. Writing a value outside the list is rejected unless the field description says it is not checked.",fields:{value:{type:new o(h),description:"The value to write to the field."},name:{type:d,description:"Name shown to the user."},description:{type:d},imageUrl:{type:d,description:"Image shown to the user."},color:{type:d,description:'Color shown to the user, as "#rrggbb".'},dryRun:{type:es,description:"What writing this value would do. Null when it cannot be tried."}}}),screenshot:new a({name:"Screenshot",description:"A screenshot of an entity. The picture itself follows the tool result.",fields:{image:{type:new o(n),description:"Label of the image that follows the tool result."}}})};for(let e of G){let n=$(J,e)??[],i=$(X,e)??[],s=$(B,e)??[],r=$(t.screenshots,e)??[],o=H.includes(e),a=n.length>0||i.length>0||s.length>0||r.length>0;(a||o)&&Y.set(e,{description:D(a,o),type:M({entityType:e,childRecipes:n,replaceRecipes:i,optionsEdges:s,screenshots:r,hasInvariants:o},er)})}let eo=new p({query:(S=ee(_.has(f)?f:g),A=ee(g),q=(e=>{let t={};for(let[n,i,s]of m){let r=e[s];r.length>1&&(t[n]={type:new o(d),description:j(i,r)})}if(0!==Object.keys(t).length)return new a({name:"Navigation",description:"The active UI states of the configurator.",fields:t})})(V),new a({name:"Query",fields:{root:{type:new o(S),description:"The root entity of the configuration."},entities:{type:new o(new r(A)),args:{ids:{type:new r(new o(n))}},description:"Every entity, or the given ids in order with null for an unknown id."},selectedEntity:{type:new o(A),description:"The selected entity, or the root entity when nothing is selected."},...q?{navigation:{type:new o(q)}}:{},warnings:{type:k,description:`Every warning and notice of the configuration the query reads.${T}`}}})),mutation:(({deletableTypes:e,writableTypes:t,childRecipes:s,replaceRecipes:p,actionFields:c,objectTypes:l,anyDomainEntity:h,targetOutputType:y})=>{let u,g;if(0!==e.length||0!==t.length||0!==Object.keys(s).length||0!==Object.keys(p).length||0!==c.length)return new a({name:"Mutation",fields:Object.assign(0===e.length?{}:{deleteEntity:{type:new o(new r(new o(n))),args:{id:{type:new o(n)}},description:`Deletes the entity and everything composed into it. Deletable types: ${e.join(", ")}. Returns the ids removed, the given one first.`}},0===(u=W(s)).length?{}:{addChild:{type:new o(new r(new o(h))),args:{parentId:{type:new o(n)},recipeGroupId:{type:new o(d)},recipeKey:{type:new o(d)}},description:`Adds a child to the entity parentId from a recipe listed under its meta { childRecipes }. Types with child recipes: ${u.join("; ")}. Returns the entities added, the recipe's own first; empty when they were removed again.`}},0===(g=W(p)).length?{}:{replaceEntity:{type:new o(new r(new o(h))),args:{entityId:{type:new o(n)},recipeGroupId:{type:new o(d)},recipeKey:{type:new o(d)}},description:`Replaces the entity entityId from a recipe listed under its meta { replaceRecipes }. Types with replace recipes: ${g.join("; ")}. The replacement is a new entity: it has a new id and the field values of its recipe, and entityId no longer exists. Returns the entities added, the replacement first; empty when they were removed again.`}},...t.flatMap(e=>{let t=l.get(e.entityType);return t?[(({entityType:e,fields:t},s)=>{let r=Object.fromEntries(t.map(({name:e,type:t,description:n})=>[e,{type:w(t),description:n}]));return{[`modify${e}`]:{type:s,args:{id:{type:new o(n)},delta:{type:new o(new i({name:`${e}Delta`,fields:r}))}},description:`Sets the fields named in delta on one ${e}. Returns the entity after the change, or null when the change removed it.`}}})(e,t)]:[]}),Object.fromEntries(c.map(e=>{var t;return[e.fieldName,{type:new o(new a({name:(t=e.fieldName,`${t.charAt(0).toUpperCase()+t.slice(1)}Result`),description:`What ${e.fieldName} returns, read from the configuration after the change.`,fields:()=>Object.fromEntries(Object.entries(e.result).map(([e,t])=>[e,{type:"edge"===t.kind?(({target:e,list:t,nullable:n},i)=>{let s=t?new r(new o(i(e))):i(e);return n?s:new o(s)})(t,y):w(t.type),description:t.description}]))})),args:Object.fromEntries(Object.entries(e.args).map(([e,t])=>[e,{type:w(t.type),description:t.description}])),description:e.description}]})))})})({deletableTypes:z,writableTypes:L,childRecipes:J,replaceRecipes:X,actionFields:Q,objectTypes:Z,anyDomainEntity:ee(g),targetOutputType:et}),types:[..._.values(),...Z.values()]}),ea=l(eo);if(ea.length>0)throw Error(ea.map(e=>e.message).join(" "));let ep=c(eo);return{sdl:ep,navigationFields:m.filter(([,,e])=>V[e].length>1).map(([e])=>e),fields:ei,deletableTypes:z,writableFields:Object.fromEntries(L.map(({entityType:e,fields:t})=>[e,Object.fromEntries(t.map(({name:e,property:t})=>[e,t]))])),childRecipes:J,replaceRecipes:X,fieldOptions:Object.fromEntries(G.flatMap(e=>{let t=$(B,e);return t?[[e,t.map(({options:e})=>e)]]:[]})),screenshots:Object.fromEntries(G.flatMap(e=>{let n=$(t.screenshots,e);return n?[[e,n]]:[]})),actions:Object.fromEntries(Q.map(({fieldName:e,actionName:t})=>[e,t])),lenses:y(t,u(ep)),formElements:t.formElements}};

package/dist/domain/application/assistant/generate-assistant-prompt.js

@@ -1 +1 @@
-import{ASSISTANT_BUILT_IN_FORM_ELEMENTS as e}from"./form/index.js";let t=[["Containers",["group","choice","choices"]],["Options",["option"]],["Inputs",["input"]]];export const formElementSignature=({name:e,role:t,attributes:a})=>{let n=["label",...Object.entries(a).map(([e,t])=>((e,{type:t,enum:a})=>a?`${e}="${a.join("|")}"`:"string"===t?e:`${e}="<${t}>"`)(e,t))];return"option"===t||"input"===t?`<${e} ${n.join(" ")} />`:`<${e} ${n.join(" ")}>…</${e}>`};export const generateAssistantPrompt=a=>{let n,s=Object.values(a.childRecipes??{}).some(e=>e.length>0),i=Object.values(a.replaceRecipes??{}).some(e=>e.length>0),o=Object.values(a.fieldOptions??{}).some(e=>e.length>0),r=Object.keys(a.actions??{}).length>0,h=(a.deletableTypes?.length??0)>0||Object.values(a.writableFields??{}).some(e=>Object.keys(e).length>0)||s||i||r,l=s||i||o,d=[...s?["`childRecipes` is what can be added to it"]:[],...i?["`replaceRecipes` what it can be replaced with"]:[],...o?["`<field>Options` the values a field accepts"]:[]],c=["`selected`",...(a.navigationFields??[]).map(e=>`\`${e}\``)].join(", ");return[["Tools","- Put related operations in one call and select only the fields you need.",...h?[`- Use a mutation inside \`query\` to answer a what-if about a change ${l?"the lists under `meta` do not show":"before making it"}.`,"- Use `apply` only for what the user asked for."]:["- Nothing in this configurator can be changed through you. Say so when the user asks for a change."],"- When an operation fails, its `errors` say why and what to send instead."],...h?[["After a change","- A change is made only when the `apply` result has `committed: true`. Otherwise `errors` or `message` says what happened; without either, nothing changed. Never say a change was made when it was not.","- `sideEffects` names the major or unexpected things the configurator changed along with your change. Tell the user about them when committed; otherwise they describe what would happen. Smaller adjustments are not listed.","- A mutation returns the state after the change: use the ids and values it returned, not the ones you sent.",...r?["- When one mutation does the whole of what the user asked, use it instead of building the same change from several others."]:[]]]:[],...l?[["What can be done to an entity",`- \`meta\` lists what is possible right now: ${d.join(", ")}. Read the list before such a change and before telling the user what is available.`,`- You can select \`dryRun\` on ${[...s||i?["recipes"]:[],...o?["options"]:[]].join(" or ")} to look ahead and pick one that meets what the user asked for. It is optional before a change.`,"- Read the lists again after a change, unless their descriptions say they stay the same."]]:[],["The `[changes]` block","- Every user message starts with it: a glimpse of what the user did in the configurator since your last turn.",`- \`[changes: none]\`, or only ${c} lines: what you know still holds. Do not query it again.`,"- Other lines are a hint at what to read again: `A` added, `D` deleted, `M` modified with the fields. Text after `#` says what caused the line; `reset: undo/redo` says the user undid or redid changes.","- Read computed fields again when a listed change may affect them.","- `[changes: unavailable]` and `[changes: too many (n)]`: read again before relying on anything you read earlier.",...h?["- Your applied changes are not listed, except those waiting for user approval: they appear once approved."]:[]],["Reading the schema","- Take ids from results.",...(a.deletableTypes?.length??0)>0||i?["- The id of a deleted or replaced entity is gone and may later be given to another entity."]:[],`- A field whose name starts with \`_\` is computed: read it${h?", never write it":""}.`,"- Numbers are in the unit the field description names. Convert when the user uses another unit."],["Links","- You may link an entity of the current configuration when you speak about that very entity: `[the left burner](entity:CookingTop-1)`. It helps the user find it in the configurator.",...l?["- Whenever you name recipes or options you read from `meta`, in a list, a table or a sentence, link each one: `[Single gas burner](recipe:KitchenRange-1/top/gas_single)` or `[Oak](option:Cabinet-2/finishOptions/oak)`. The link shows the user its picture or color and its description, so never draw previews yourself. The target is the entity id, the recipe group id or the options field you read, and the key or value, each encoded as in a URL."]:[]],["Replies","- Write Markdown only, never HTML: the panel does not render it.","- An image, `![alt](path)`, is shown only when its path is relative.","- To make a warning or a key note stand out, write a GitHub alert: a blockquote whose first line is only `[!WARNING]` or `[!NOTE]`. Use it sparingly."],["Forms","- To ask the user something they answer by picking or typing, end your reply with a form: a fenced code block with the language `form`. It holds only elements, written as lowercase tags with string attributes, without Markdown or text.","- Every element takes `label`, the text the user sees; on a container or an input it also names the answer. An option or an input whose signature lists `value` takes it: an option sends it instead of its label, and an input starts with it.",'- A bare attribute in a signature takes any text, `name="<type>"` takes a value of that type written as text, such as `min="<number>"`, and `name="a|b"` takes one of the words listed.',"- Options can also stand on their own, outside a `choice` or `choices`.","- An element or attribute not listed here, or an element other than an option inside a `choice` or `choices`, makes the whole form fail.","- The answer is the user's next message. Each container or input gives a line `Label: value`, or the bare value without a label; the lines of a labelled container are indented by two spaces under it, a `choices` lists each picked option on its own line, and `—` marks what was left unanswered.",'- Example: `<choice label="Plinth"><reply label="Black" /><reply label="Oak" /></choice>` is answered with `Plinth: Oak`.',"- The chat shows the answer as the user's own message, so a `value` reads as natural words, never as an id, key or code. Give `value` only when the label alone would be unclear as an answer, and map the answer's labels back to ids yourself.",...(n=[...e,...a.formElements??[]],t.flatMap(([e,t])=>{let a=n.filter(({role:e})=>t.includes(e));return 0===a.length?[]:[`- ${e}:`,...a.map(e=>`  - \`${formElementSignature(e)}\`: ${(({description:e,required:t=[]})=>0===t.length?e:`${e} Requires ${t.map(e=>`\`${e}\``).join(", ")}.`)(e)}`)]}))],...a.lenses?.declarations?[["Built-in fragments","- These fragments are already defined for every operation. Spread one by name on a field of its type, as in `field { ...FragmentName }`, instead of listing its fields.","- A fragment is a starting selection: add the other fields you need next to the spread, by name from the schema.","- Never define a fragment with one of these names.","",a.lenses.declarations]]:[]].map(e=>e.join("\n")).join("\n\n")};
+import{ASSISTANT_BUILT_IN_FORM_ELEMENTS as e}from"./form/index.js";let t=[["Containers",["group","choice","choices"]],["Options",["option"]],["Inputs",["input"]]];export const formElementSignature=({name:e,role:t,attributes:a})=>{let n=["label",...Object.entries(a).map(([e,t])=>((e,{type:t,enum:a})=>a?`${e}="${a.join("|")}"`:"string"===t?e:`${e}="<${t}>"`)(e,t))];return"option"===t||"input"===t?`<${e} ${n.join(" ")} />`:`<${e} ${n.join(" ")}>…</${e}>`};export const generateAssistantPrompt=a=>{let n,s=Object.values(a.childRecipes??{}).some(e=>e.length>0),o=Object.values(a.replaceRecipes??{}).some(e=>e.length>0),i=Object.values(a.fieldOptions??{}).some(e=>e.length>0),r=Object.keys(a.actions??{}).length>0,h=Object.values(a.screenshots??{}).some(e=>e.length>0),l=(a.deletableTypes?.length??0)>0||Object.values(a.writableFields??{}).some(e=>Object.keys(e).length>0)||s||o||r,d=s||o||i,u=[...s?["`childRecipes` is what can be added to it"]:[],...o?["`replaceRecipes` what it can be replaced with"]:[],...i?["`<field>Options` the values a field accepts"]:[]],c=["`selected`",...(a.navigationFields??[]).map(e=>`\`${e}\``)].join(", ");return[["Tools","- Put related operations in one call and select only the fields you need.",`- Give every ${l?"`query` and `apply` call":"`query` call"} a \`title\` of two to five words in the user's language that says what it does for them, e.g. ${l?'"Add two drawers"':'"Compare drawer prices"'}.`,...l?[`- Use a mutation inside \`query\` to answer a what-if about a change ${d?"the lists under `meta` do not show":"before making it"}.`,"- Use `apply` only for what the user asked for."]:["- Nothing in this configurator can be changed through you. Say so when the user asks for a change."],"- When an operation fails, its `errors` say why and what to send instead. A change the configuration does not allow fails with one error per reason, as the user would be told it.","- Warnings and notices never make anything fail. The root `warnings` field lists every current one, and `meta { warnings }` those of one entity, where its type has them."],...l?[["After a change","- A change is made only when the `apply` result has `committed: true`. Otherwise `errors` or `message` says what happened; without either, nothing changed. Never say a change was made when it was not.","- `sideEffects` names the major or unexpected things the configurator changed along with your change. Tell the user about them when committed; otherwise they describe what would happen. Smaller adjustments are not listed.","- `warnings` lists the warnings and notices your change newly causes. They do not block it: tell the user about them, and offer a fix when one is clear.","- A mutation returns the state after the change: use the ids and values it returned, not the ones you sent.",...r?["- When one mutation does the whole of what the user asked, use it instead of building the same change from several others."]:[]]]:[],...d?[["What can be done to an entity",`- \`meta\` lists what is possible right now: ${u.join(", ")}. Read the list before such a change and before telling the user what is available.`,`- You can select \`dryRun\` on ${[...s||o?["recipes"]:[],...i?["options"]:[]].join(" or ")} to look ahead and pick one that meets what the user asked for. It is optional before a change.`,`- Select only the ${[...s||o?["recipe groups"]:[],...i?["options edges"]:[]].join(" and ")} you need. To read again only the ones you are deciding between, pass ${[...s||o?["their `key` to `recipes(keys:)`"]:[],...i?["their `value` to `<field>Options(values:)`"]:[]].join(" or ")}.`,"- Read the lists again after a change, unless their descriptions say they stay the same."]]:[],...h?[["Seeing the design","- `meta { screenshot(view: …) { image } }` renders an entity from one of the views its `<Type>ScreenshotView` lists. The picture follows the tool result.","- Take one when the user asks how the design looks, or when you are not sure something is laid out right: what sits where, what overlaps or lines up. Otherwise rely on the data.","- Each one costs tokens and blocks the user's configurator while it renders."]]:[],["Images from the user","- The user may attach photos or reference images to a message, such as their room or a design they like.","- Sizes you read from a photo are estimates: tell the user the values you read and confirm them before you apply them."],["The `[changes]` block","- Every user message starts with it: a glimpse of what the user did in the configurator since your last turn.",`- \`[changes: none]\`, or only ${c} lines: what you know still holds. Do not query it again.`,"- Other lines are a hint at what to read again: `A` added, `D` deleted, `M` modified with the fields. Text after `#` says what caused the line; `reset: undo/redo` says the user undid or redid changes.","- Read computed fields again when a listed change may affect them.","- `[changes: unavailable]` and `[changes: too many (n)]`: read again before relying on anything you read earlier.",...l?["- Your applied changes are not listed, except those waiting for user approval: they appear once approved."]:[]],["Reading the schema","- Take ids from results.",...(a.deletableTypes?.length??0)>0||o?["- The id of a deleted or replaced entity is gone and may later be given to another entity."]:[],`- A field whose name starts with \`_\` is computed: read it${l?", never write it":""}.`,"- Numbers are in the unit the field description names. Convert when the user uses another unit."],["Links","- You may link an entity of the current configuration when you speak about that very entity: `[the left burner](entity:CookingTop-1)`. It helps the user find it in the configurator.",...d?["- Whenever you name recipes or options you read from `meta`, in a list, a table or a sentence, link each one: `[Single gas burner](recipe:KitchenRange-1/top/gas_single)` or `[Oak](option:Cabinet-2/finishOptions/oak)`. The link shows the user its picture or color and its description, so never draw previews yourself. The target is the entity id, the recipe group id or the options field you read, and the key or value, each encoded as in a URL."]:[]],["Replies","- Write Markdown only, never HTML: the panel does not render it.","- An image, `![alt](path)`, is shown only when its path is relative.","- To make a warning or a key note stand out, write a GitHub alert: a blockquote whose first line is only `[!WARNING]` or `[!NOTE]`. Use it sparingly."],["Forms","- To ask the user something they answer by picking or typing, end your reply with a form: a fenced code block with the language `form`. It holds only elements, written as lowercase tags with string attributes, without Markdown or text.","- Every element takes `label`, the text the user sees; on a container or an input it also names the answer. An option or an input whose signature lists `value` takes it: an option sends it instead of its label, and an input starts with it.",'- A bare attribute in a signature takes any text, `name="<type>"` takes a value of that type written as text, such as `min="<number>"`, and `name="a|b"` takes one of the words listed.',"- Options can also stand on their own, outside a `choice` or `choices`.","- An element or attribute not listed here, or an element other than an option inside a `choice` or `choices`, makes the whole form fail.","- The answer is the user's next message. Each container or input gives a line `Label: value`, or the bare value without a label; the lines of a labelled container are indented by two spaces under it, a `choices` lists each picked option on its own line, and `—` marks what was left unanswered.",'- Example: `<choice label="Plinth"><reply label="Black" /><reply label="Oak" /></choice>` is answered with `Plinth: Oak`.',"- The chat shows the answer as the user's own message, so a `value` reads as natural words, never as an id, key or code. Give `value` only when the label alone would be unclear as an answer, and map the answer's labels back to ids yourself.",...(n=[...e,...a.formElements??[]],t.flatMap(([e,t])=>{let a=n.filter(({role:e})=>t.includes(e));return 0===a.length?[]:[`- ${e}:`,...a.map(e=>`  - \`${formElementSignature(e)}\`: ${(({description:e,required:t=[]})=>0===t.length?e:`${e} Requires ${t.map(e=>`\`${e}\``).join(", ")}.`)(e)}`)]}))],...a.lenses?.declarations?[["Built-in fragments","- These fragments are already defined for every operation. Spread one by name on a field of its type, as in `field { ...FragmentName }`, instead of listing its fields.","- A fragment is a starting selection: add the other fields you need next to the spread, by name from the schema.","- Never define a fragment with one of these names.","",a.lenses.declarations]]:[]].map(e=>e.join("\n")).join("\n\n")};

package/dist/domain/application/assistant/index.d.ts

@@ -1,9 +1,9 @@
-export { ASSISTANT_HINTS } from './assistant-resolved-manifest.js';
-export type { AssistantResolvedManifest, AssistantDeclaredField, AssistantDeclarations, AssistantDeclaredWrite, AssistantResolvedField, AssistantValueType, AssistantRelationType, AssistantStates, AssistantWritableType, AssistantWritableField, AssistantResolvedHint, AssistantResolvedRecipes, AssistantResolvedOptionsEdge, AssistantResolvedAction, AssistantResolvedActionResult, } from './assistant-resolved-manifest.js';
+export { ASSISTANT_HINTS } from './assistant-manifest.js';
+export type { AssistantResolvedManifest, AssistantDeclaredField, AssistantDeclarations, AssistantDeclaredWrite, AssistantResolvedField, AssistantValueType, AssistantRelationType, AssistantStates, AssistantWritableType, AssistantWritableField, AssistantResolvedRecipes, AssistantResolvedOptionsEdge, AssistantResolvedAction, AssistantResolvedActionResult, } from './assistant-resolved-manifest.js';
 export { buildAssistantManifest } from './build-assistant-manifest.js';
 export type { AssistantFieldExposure } from './create-assistant-execution-schema.js';
 export { AssistantFieldClashError, createAssistantExecutionSchema } from './create-assistant-execution-schema.js';
-export type { AssistantFieldSource, AssistantRecipeGroup, AssistantFieldOptions, AssistantScreenshotView, AssistantManifest, } from './assistant-manifest.js';
+export type { AssistantFieldSource, AssistantResolvedHint, AssistantRecipeGroup, AssistantFieldOptions, AssistantScreenshotView, AssistantManifest, } from './assistant-manifest.js';
 export { generateAssistantPrompt } from './generate-assistant-prompt.js';
 export * from './session-setup/index.js';
 export { describeAssistantValues, mergeAssistantFields, resolveAssistantField } from './assistant-fields.js';

package/dist/domain/application/assistant/index.js

@@ -1 +1 @@
-export{ASSISTANT_HINTS}from"./assistant-resolved-manifest.js";export{buildAssistantManifest}from"./build-assistant-manifest.js";export{AssistantFieldClashError,createAssistantExecutionSchema}from"./create-assistant-execution-schema.js";export{generateAssistantPrompt}from"./generate-assistant-prompt.js";export*from"./session-setup/index.js";export{describeAssistantValues,mergeAssistantFields,resolveAssistantField}from"./assistant-fields.js";export*from"./form/index.js";
+export{ASSISTANT_HINTS}from"./assistant-manifest.js";export{buildAssistantManifest}from"./build-assistant-manifest.js";export{AssistantFieldClashError,createAssistantExecutionSchema}from"./create-assistant-execution-schema.js";export{generateAssistantPrompt}from"./generate-assistant-prompt.js";export*from"./session-setup/index.js";export{describeAssistantValues,mergeAssistantFields,resolveAssistantField}from"./assistant-fields.js";export*from"./form/index.js";

package/dist/domain/application/assistant/session-setup/apply-assistant-setup.js

@@ -1 +1 @@
-import{ASSISTANT_AI_PROVIDERS as e,ASSISTANT_MODEL_TIERS as t,ASSISTANT_REASONING_LEVELS as s}from"@salsita-ai/contracts/assistant";import{describeAssistantValues as i,mergeAssistantFields as n,resolveAssistantField as o}from"../assistant-fields.js";import{ASSISTANT_HINTS as r}from"../assistant-resolved-manifest.js";import{projectAssistantSetupManifest as a}from"./assistant-setup-manifest.js";export class AssistantSetupError extends Error{constructor(e,t){super(`${e}: ${t}`),this.name="AssistantSetupError"}}let l=(e,t)=>{throw new AssistantSetupError(e,t)},p=(e,t,s)=>{for(let i of((null===t||"object"!=typeof t||Array.isArray(t))&&l(s,"expected an object; omit an entry to remove it"),Object.keys(t)))Object.hasOwn(e,i)||l(`${s}.${i}`,"not declared in the spec; remove this key")},c=(e,t)=>Object.hasOwn(e,t)?e[t]:void 0,d=(e,t,s)=>(void 0!==e&&"string"!=typeof e&&l(`${s}.description`,"expected a string"),e??t),u=(e,t,s)=>(void 0!==e&&!1!==e&&l(`${s}.allowDryRuns`,"can only disable dry-runs; omit this flag or set false"),!1!==e&&t);export const applyAssistantSetup=(f,m,b)=>{if(null===b)return null;let y=a(f,m),g=f.declarations;p({entities:{},deletable:{},writable:{},childRecipes:{},replaceRecipes:{},screenshots:{},actions:{},instructions:"",ai:{}},b,"assistant"),p(y.entities,b.entities,"assistant.entities"),p(y.deletable,b.deletable,"assistant.deletable"),p(y.writable,b.writable,"assistant.writable"),p(y.actions,b.actions,"assistant.actions"),p(y.screenshots,b.screenshots,"assistant.screenshots");let h=Object.fromEntries(Object.entries(b.entities).map(([e,t])=>{let s=`assistant.entities.${e}`;p(y.entities[e],t,s);let n=g.entities[e];return[e,Object.entries(t).map(([e,t])=>{p({description:""},t,`${s}.${e}`);let o=n.find(t=>t.source===e),r=d(t.description,o.valueDescription,`${s}.${e}`);return{...o,valueDescription:r,description:i(r,o.enumValues),describedByManifest:void 0!==t.description||o.describedByManifest}})]})),v=(e,t,s)=>l(`assistant.entities.${e}`,`conflicting sources ${t} and ${s}`),$=n([],c(h,"AnyDomainEntity")??[],()=>void 0,v),w=new Map([["AnyDomainEntity",$]]);for(let e of Object.keys(f.aliases))"AnyDomainEntity"!==e&&w.set(e,n([$],c(h,e)??[],()=>void 0,v));for(let e of f.entityTypes){let t=Object.entries(f.aliases).filter(([t,s])=>"AnyDomainEntity"!==t&&s.includes(e));w.set(e,n([$,...t.map(([e])=>w.get(e)??[])],c(h,e)??[],t=>g.enumValues[e]?.[t],v))}let j=Object.fromEntries([...w].map(([e,t])=>[e,t.map(t=>o(t,c(h,e)??[]))])),O=new Map,T=new Map;for(let[e,t]of Object.entries(b.writable)){let s=`assistant.writable.${e}`;for(let[i,n]of(p(y.writable[e],t,s),Object.entries(t))){let t=`${s}.${i}`,o=g.writable[e][i];for(let[e,{field:s,options:r,exposedDescription:a}]of(p(Object.values(o.members).some(e=>e.options)?{options:{}}:{},n,t),void 0!==n.options&&(p({validate:!0,allowDryRuns:!1},n.options,`${t}.options`),void 0!==n.options.validate&&!0!==n.options.validate&&l(`${t}.options.validate`,"can only enable validation; omit this flag or set true"),u(n.options.allowDryRuns,!0,`${t}.options`)),Object.entries(o.members))){let p=c(h,e)?.find(e=>e.source===i)?.name??w.get(e)?.find(e=>e.source===i)?.name,d=p??i;void 0===p&&w.get(e)?.some(e=>e.name===i&&e.source!==i)&&l(t,`narrowing leaves ${e}.${i} bound to another read field; retain its original exposure or remove this writable property`);let f=O.get(e)??new Map;if([...f.values()].some(e=>e.name===d&&e.property!==i)&&l(t,`narrowing maps multiple writable properties to ${e}.${d}; retain their original exposures or remove the conflicting property`),f.has(i)||f.set(i,{...s,name:d,...void 0===p?{}:{description:a}}),O.set(e,f),r){let s=o.defaultOptionsName?`${d}Options`:r.options.edgeName;T.get(e)?.some(e=>e.options.edgeName===s||e.options.field===d)&&l(`${t}.options`,`narrowing duplicates options edge ${e}.${s}; retain the original field exposures or remove the conflicting writable declaration`),T.set(e,[...T.get(e)??[],{hints:r.hints,options:{...r.options,field:d,edgeName:s,validate:n.options?.validate??r.options.validate,dryRuns:u(n.options?.allowDryRuns,r.options.dryRuns,`${t}.options`)}}])}}}}for(let[e,t]of Object.entries(f.optionsEdges))for(let s of t){let t=f.writableTypes.find(t=>t.entityType===e)?.fields.find(e=>e.name===s.options.field)?.property;if(s.options.validate&&t&&O.get(e)?.has(t)&&!T.get(e)?.some(s=>s.options.field===O.get(e)?.get(t)?.name&&s.options.validate)){let s=Object.keys(b.writable).find(s=>Object.hasOwn(b.writable[s],t)&&g.writable[s]?.[t]?.members[e]);l(`assistant.writable.${s}.${t}`,`cannot remove declared validation while another declaration keeps ${e}.${t} writable; remove all writable declarations for it`)}}let x=e=>{p(y[e],b[e],`assistant.${e}`);let t=new Map;for(let[s,i]of Object.entries(b[e])){let n=`assistant.${e}.${s}`;p({groups:{}},i,n),p(y[e][s].groups,i.groups,`${n}.groups`);let o=g[e][s],a=Object.entries(i.groups).map(([e,t])=>{let s=`${n}.groups.${e}`;p({description:"",allowDryRuns:!1},t,s);let i=o.groups.find(t=>t.instanceName===e);return{...i,description:d(t.description,i.description,s),dryRuns:u(t.allowDryRuns,i.dryRuns,s)}});for(let e of f.entityTypes.includes(s)?[s]:f.aliases[s]??[]){let s=t.get(e);t.set(e,{groups:[...s?.groups??[],...a],hints:r.filter(e=>o.hints.includes(e)||s?.hints.includes(e))})}}return Object.fromEntries(f.entityTypes.flatMap(e=>{let s=t.get(e);return s?.groups.length?[[e,s]]:[]}))},E=new Map;for(let[e,t]of Object.entries(b.screenshots)){let s=`assistant.screenshots.${e}`;p(y.screenshots[e],t,s);let i=f.entityTypes.includes(e)?[e]:f.aliases[e]??[];for(let[n,o]of Object.entries(t)){let t=`${s}.${n}`;p({description:""},o,t);let r=g.screenshots[e].find(e=>e.instanceName===n),a={...r,description:d(o.description,r.description,t)??r.description};for(let e of i)E.set(e,[...E.get(e)??[],a])}}for(let[e,t]of Object.entries(b.deletable))p({},t,`assistant.deletable.${e}`);let R=new Set(Object.keys(b.deletable).flatMap(e=>f.entityTypes.includes(e)?[e]:f.aliases[e]??[])),M=f.actionFields.flatMap(e=>{let t=c(b.actions,e.actionName);if(void 0===t)return[];let s=`assistant.actions.${e.actionName}`;return p({description:""},t,s),[{...e,description:d(t.description,e.description,s)}]}),D=m;if(m){void 0!==b.ai&&p({...m.ai,maxThreadSize:void 0},b.ai,"assistant.ai");let i={...m.ai,...Object.fromEntries(Object.entries(b.ai??{}).filter(([,e])=>void 0!==e))};e.includes(i.provider)&&t.includes(i.model)&&s.includes(i.reasoning)||l("assistant.ai","expected a supported provider, model and reasoning level"),void 0!==i.maxThreadSize&&(!Number.isInteger(i.maxThreadSize)||i.maxThreadSize<=0)&&l("assistant.ai.maxThreadSize","expected a positive whole number of input tokens"),void 0!==b.instructions&&"string"!=typeof b.instructions&&l("assistant.instructions","expected a string"),D={instructions:""===b.instructions?null:b.instructions??m.instructions,ai:i}}return{resolved:{...f,fields:j,deletableTypes:f.entityTypes.filter(e=>R.has(e)),writableTypes:f.entityTypes.flatMap(e=>{let t=[...O.get(e)?.values()??[]];return t.length?[{entityType:e,fields:t}]:[]}),optionsEdges:Object.fromEntries(T),childRecipes:x("childRecipes"),replaceRecipes:x("replaceRecipes"),screenshots:Object.fromEntries(f.entityTypes.flatMap(e=>{let t=E.get(e);return t?[[e,t]]:[]})),actionFields:M},settings:D}};
+import{ASSISTANT_AI_PROVIDERS as e,ASSISTANT_MODEL_TIERS as t,ASSISTANT_REASONING_LEVELS as i}from"@salsita-ai/contracts/assistant";import{describeAssistantValues as s,mergeAssistantFields as n,resolveAssistantField as o}from"../assistant-fields.js";import{projectAssistantSetupManifest as a}from"./assistant-setup-manifest.js";export class AssistantSetupError extends Error{constructor(e,t){super(`${e}: ${t}`),this.name="AssistantSetupError"}}let r=(e,t)=>{throw new AssistantSetupError(e,t)},l=(e,t,i)=>{for(let s of((null===t||"object"!=typeof t||Array.isArray(t))&&r(i,"expected an object; omit an entry to remove it"),Object.keys(t)))Object.hasOwn(e,s)||r(`${i}.${s}`,"not declared in the spec; remove this key")},p=(e,t)=>Object.hasOwn(e,t)?e[t]:void 0,c=(e,t,i)=>(void 0!==e&&"string"!=typeof e&&r(`${i}.description`,"expected a string"),e??t),d=(e,t,i)=>(void 0!==e&&!1!==e&&r(`${i}.allowDryRuns`,"can only disable dry-runs; omit this flag or set false"),!1!==e&&t);export const applyAssistantSetup=(f,u,m)=>{if(null===m)return null;let b=a(f,u),y=f.declarations;l({entities:{},deletable:{},writable:{},childRecipes:{},replaceRecipes:{},screenshots:{},actions:{},instructions:"",ai:{}},m,"assistant"),l(b.entities,m.entities,"assistant.entities"),l(b.deletable,m.deletable,"assistant.deletable"),l(b.writable,m.writable,"assistant.writable"),l(b.actions,m.actions,"assistant.actions"),l(b.screenshots,m.screenshots,"assistant.screenshots");let v=Object.fromEntries(Object.entries(m.entities).map(([e,t])=>{let i=`assistant.entities.${e}`;l(b.entities[e],t,i);let n=y.entities[e];return[e,Object.entries(t).map(([e,t])=>{l({description:""},t,`${i}.${e}`);let o=n.find(t=>t.source===e),a=c(t.description,o.valueDescription,`${i}.${e}`);return{...o,valueDescription:a,description:s(a,o.enumValues),describedByManifest:void 0!==t.description||o.describedByManifest}})]})),$=(e,t,i)=>r(`assistant.entities.${e}`,`conflicting sources ${t} and ${i}`),h=n([],p(v,"AnyDomainEntity")??[],()=>void 0,$),w=new Map([["AnyDomainEntity",h]]);for(let e of Object.keys(f.aliases))"AnyDomainEntity"!==e&&w.set(e,n([h],p(v,e)??[],()=>void 0,$));for(let e of f.entityTypes){let t=Object.entries(f.aliases).filter(([t,i])=>"AnyDomainEntity"!==t&&i.includes(e));w.set(e,n([h,...t.map(([e])=>w.get(e)??[])],p(v,e)??[],t=>y.enumValues[e]?.[t],$))}let g=Object.fromEntries([...w].map(([e,t])=>[e,t.map(t=>o(t,p(v,e)??[]))])),O=new Map,j=new Map;for(let[e,t]of Object.entries(m.writable)){let i=`assistant.writable.${e}`;for(let[s,n]of(l(b.writable[e],t,i),Object.entries(t))){let t=`${i}.${s}`,o=y.writable[e][s];for(let[e,{field:i,options:a,exposedDescription:c}]of(l(Object.values(o.members).some(e=>e.options)?{options:{}}:{},n,t),void 0!==n.options&&(l({validate:!0,allowDryRuns:!1},n.options,`${t}.options`),void 0!==n.options.validate&&!0!==n.options.validate&&r(`${t}.options.validate`,"can only enable validation; omit this flag or set true"),d(n.options.allowDryRuns,!0,`${t}.options`)),Object.entries(o.members))){let l=p(v,e)?.find(e=>e.source===s)?.name??w.get(e)?.find(e=>e.source===s)?.name,f=l??s;void 0===l&&w.get(e)?.some(e=>e.name===s&&e.source!==s)&&r(t,`narrowing leaves ${e}.${s} bound to another read field; retain its original exposure or remove this writable property`);let u=O.get(e)??new Map;if([...u.values()].some(e=>e.name===f&&e.property!==s)&&r(t,`narrowing maps multiple writable properties to ${e}.${f}; retain their original exposures or remove the conflicting property`),u.has(s)||u.set(s,{...i,name:f,...void 0===l?{}:{description:c}}),O.set(e,u),a){let i=o.defaultOptionsName?`${f}Options`:a.options.edgeName;j.get(e)?.some(e=>e.options.edgeName===i||e.options.field===f)&&r(`${t}.options`,`narrowing duplicates options edge ${e}.${i}; retain the original field exposures or remove the conflicting writable declaration`),j.set(e,[...j.get(e)??[],{hints:a.hints,options:{...a.options,field:f,edgeName:i,validate:n.options?.validate??a.options.validate,dryRuns:d(n.options?.allowDryRuns,a.options.dryRuns,`${t}.options`)}}])}}}}for(let[e,t]of Object.entries(f.optionsEdges))for(let i of t){let t=f.writableTypes.find(t=>t.entityType===e)?.fields.find(e=>e.name===i.options.field)?.property;if(i.options.validate&&t&&O.get(e)?.has(t)&&!j.get(e)?.some(i=>i.options.field===O.get(e)?.get(t)?.name&&i.options.validate)){let i=Object.keys(m.writable).find(i=>Object.hasOwn(m.writable[i],t)&&y.writable[i]?.[t]?.members[e]);r(`assistant.writable.${i}.${t}`,`cannot remove declared validation while another declaration keeps ${e}.${t} writable; remove all writable declarations for it`)}}let T=e=>{l(b[e],m[e],`assistant.${e}`);let t=new Map;for(let[i,s]of Object.entries(m[e])){let n=`assistant.${e}.${i}`;l(b[e][i],s,n);let o=y[e][i],a=Object.entries(s).map(([e,t])=>{let i=`${n}.${e}`;l({description:"",allowDryRuns:!1},t,i);let s=o.find(t=>t.instanceName===e);return{...s,description:c(t.description,s.description,i),dryRuns:d(t.allowDryRuns,s.dryRuns,i)}});for(let e of f.entityTypes.includes(i)?[i]:f.aliases[i]??[])t.set(e,[...t.get(e)??[],...a])}return Object.fromEntries(f.entityTypes.flatMap(e=>{let i=t.get(e);return i?.length?[[e,i]]:[]}))},x=new Map;for(let[e,t]of Object.entries(m.screenshots)){let i=`assistant.screenshots.${e}`;l(b.screenshots[e],t,i);let s=f.entityTypes.includes(e)?[e]:f.aliases[e]??[];for(let[n,o]of Object.entries(t)){let t=`${i}.${n}`;l({description:""},o,t);let a=y.screenshots[e].find(e=>e.instanceName===n),r={...a,description:c(o.description,a.description,t)??a.description};for(let e of s)x.set(e,[...x.get(e)??[],r])}}for(let[e,t]of Object.entries(m.deletable))l({},t,`assistant.deletable.${e}`);let E=new Set(Object.keys(m.deletable).flatMap(e=>f.entityTypes.includes(e)?[e]:f.aliases[e]??[])),R=f.actionFields.flatMap(e=>{let t=p(m.actions,e.actionName);if(void 0===t)return[];let i=`assistant.actions.${e.actionName}`;return l({description:""},t,i),[{...e,description:c(t.description,e.description,i)}]}),M=u;if(u){void 0!==m.ai&&l({...u.ai,maxThreadSize:void 0},m.ai,"assistant.ai");let s={...u.ai,...Object.fromEntries(Object.entries(m.ai??{}).filter(([,e])=>void 0!==e))};e.includes(s.provider)&&t.includes(s.model)&&i.includes(s.reasoning)||r("assistant.ai","expected a supported provider, model and reasoning level"),void 0!==s.maxThreadSize&&(!Number.isInteger(s.maxThreadSize)||s.maxThreadSize<=0)&&r("assistant.ai.maxThreadSize","expected a positive whole number of input tokens"),void 0!==m.instructions&&"string"!=typeof m.instructions&&r("assistant.instructions","expected a string"),M={instructions:""===m.instructions?null:m.instructions??u.instructions,ai:s}}return{resolved:{...f,fields:g,deletableTypes:f.entityTypes.filter(e=>E.has(e)),writableTypes:f.entityTypes.flatMap(e=>{let t=[...O.get(e)?.values()??[]];return t.length?[{entityType:e,fields:t}]:[]}),optionsEdges:Object.fromEntries(j),childRecipes:T("childRecipes"),replaceRecipes:T("replaceRecipes"),screenshots:Object.fromEntries(f.entityTypes.flatMap(e=>{let t=x.get(e);return t?[[e,t]]:[]})),actionFields:R},settings:M}};

package/dist/domain/application/assistant/session-setup/assistant-setup-manifest.d.ts

@@ -38,10 +38,8 @@ export interface AssistantSetupRecipeGroup {
     readonly description?: string;
     readonly allowDryRuns?: false;
 }
-/** Only explicitly declared groups appear, under their original entity or alias key. */
-export interface AssistantSetupRecipes {
-    readonly groups: Readonly<Record<string, AssistantSetupRecipeGroup>>;
-}
+/** Only explicitly declared groups appear, under their original entity or alias key, keyed by instance name. */
+export type AssistantSetupRecipes = Readonly<Record<string, AssistantSetupRecipeGroup>>;
 /** Server settings baseline, kept out of the browser spec. */
 export interface AssistantSetupSettings {
     readonly instructions?: string | null;

package/dist/domain/application/assistant/session-setup/assistant-setup-manifest.js

@@ -1 +1 @@
-export const projectAssistantSetupManifest=(e,t)=>{let i=e=>Object.fromEntries(Object.entries(e).map(([e,t])=>[e,{groups:Object.fromEntries(t.groups.map(e=>[e.instanceName,{...void 0===e.description?{}:{description:e.description},...!e.dryRuns?{allowDryRuns:!1}:{}}]))}])),s=e.declarations;return{entities:Object.fromEntries(Object.entries(s.entities).map(([e,t])=>[e,Object.fromEntries(t.map(e=>[e.source,{...!e.describedByManifest||void 0===e.valueDescription?{}:{description:e.valueDescription}}]))])),deletable:Object.fromEntries(s.deletable.map(e=>[e,{}])),writable:Object.fromEntries(Object.entries(s.writable).map(([e,t])=>[e,Object.fromEntries(Object.entries(t).map(([e,t])=>{let i=Object.values(t.members).find(e=>e.options)?.options?.options;return[e,i?{options:{...i.validate?{validate:!0}:{},...!i.dryRuns?{allowDryRuns:!1}:{}}}:{}]}))])),childRecipes:i(s.childRecipes),replaceRecipes:i(s.replaceRecipes),screenshots:Object.fromEntries(Object.entries(s.screenshots).map(([e,t])=>[e,Object.fromEntries(t.map(({instanceName:e,description:t})=>[e,{description:t}]))])),actions:Object.fromEntries(e.actionFields.map(e=>[e.actionName,void 0===e.description?{}:{description:e.description}])),...t?{instructions:t.instructions??void 0,ai:{...t.ai}}:{}}};
+export const projectAssistantSetupManifest=(e,t)=>{let i=e=>Object.fromEntries(Object.entries(e).map(([e,t])=>[e,Object.fromEntries(t.map(e=>[e.instanceName,{...void 0===e.description?{}:{description:e.description},...!e.dryRuns?{allowDryRuns:!1}:{}}]))])),s=e.declarations;return{entities:Object.fromEntries(Object.entries(s.entities).map(([e,t])=>[e,Object.fromEntries(t.map(e=>[e.source,{...!e.describedByManifest||void 0===e.valueDescription?{}:{description:e.valueDescription}}]))])),deletable:Object.fromEntries(s.deletable.map(e=>[e,{}])),writable:Object.fromEntries(Object.entries(s.writable).map(([e,t])=>[e,Object.fromEntries(Object.entries(t).map(([e,t])=>{let i=Object.values(t.members).find(e=>e.options)?.options?.options;return[e,i?{options:{...i.validate?{validate:!0}:{},...!i.dryRuns?{allowDryRuns:!1}:{}}}:{}]}))])),childRecipes:i(s.childRecipes),replaceRecipes:i(s.replaceRecipes),screenshots:Object.fromEntries(Object.entries(s.screenshots).map(([e,t])=>[e,Object.fromEntries(t.map(({instanceName:e,description:t})=>[e,{description:t}]))])),actions:Object.fromEntries(e.actionFields.map(e=>[e.actionName,void 0===e.description?{}:{description:e.description}])),...t?{instructions:t.instructions??void 0,ai:{...t.ai}}:{}}};