@enyo-energy/energy-app-sdk 1.12.0 → 1.13.0

package/README.md

@@ -85,6 +85,7 @@ The official TypeScript SDK for building Energy Apps on the enyo platform. Creat
   - [Device Integration](#device-integration)
   - [Data Bus Messaging](#data-bus-messaging)
     - [Announcing Appliance Flexibility](#announcing-appliance-flexibility)
+    - [Explaining Why a Command Was Issued](#explaining-why-a-command-was-issued)
   - [Settings Management](#settings-management)
 - [Troubleshooting](#troubleshooting)
 - [External Libraries](#external-libraries)
@@ -1680,9 +1681,27 @@ await energyApp.useOnboardingV2().registerAdditionalSetupHandler(async (request)
 
 Every such block must declare a `failed` outcome — it absorbs a rejection, a timeout, a missing handler, and an outcome value matching no branch (guide and handler are linked only by strings). Secrets are never logged, never prefilled, and not kept in run state. See [ONBOARDING.md](./ONBOARDING.md#app-defined-setups-additional-setup).
 
+Guides pick the device on a screen of their own. `device-select` lists the network devices the run found; `eebus-device-select` lists the discovered EEBUS peers, filtered by the SHIP device type they announce (`EnyoEebusDeviceTypeEnum`). Both carry their own `headline`/`description`, and both **skip the screen entirely** when exactly one candidate matches the filter — the handler still runs and the run is still bound, with `autoSelected: true` on the request. Register one handler per kind; a network device and an EEBUS peer are different things and neither handler is a fallback for the other:
+
+```typescript
+const onboarding = energyApp.useOnboardingV2();
+
+await onboarding.registerDeviceSelectHandler(async (request) => ({
+    requestId: request.requestId,
+    applianceIds: await adoptDevices(request.devices, request.applianceId),
+}));
+
+await onboarding.registerEebusDeviceSelectHandler(async (request) => ({
+    requestId: request.requestId,   // request.peer.ski identifies the paired device
+    applianceIds: await adoptEebusPeer(request.peer, request.applianceId),
+}));
+```
+
+On an `offline-reconnect` run the request carries the appliance that went offline — re-point it and answer with the same `applianceId` rather than creating a second one. See [ONBOARDING.md](./ONBOARDING.md#picking-the-device-device-select).
+
 Your answer wins over the host's own resolution, so a wrong value is worse than none — the installer pastes it into a charger and it fails minutes later as an `ocpp-connect` timeout. `validateOnboardingV2DynamicResult()` catches the copy-target mistakes (whitespace, a non-absolute URL, a plaintext scheme).
 
-Each guide must carry the `vendorId`, `modelIds` and `startVariant` it applies to — that is how the host selects one for a run, and there is no publish step left to bind them. See [ONBOARDING.md](./ONBOARDING.md#serving-guides-the-host-pulls-the-app-never-publishes) for the full v2 model.
+Each guide declares the `startVariant` it applies to (`device-not-found`, `device-found-config`, `manual-setup`, `maintenance`, `offline-reconnect`). It must **not** declare `vendorId` or `modelIds`: enyo attaches those bindings when the guide is registered, an app-supplied value is overwritten, and `validateOnboardingGuideV2()` warns about it. See [ONBOARDING.md](./ONBOARDING.md#serving-guides-the-host-pulls-the-app-never-publishes) for the full v2 model.
 
 Not permission-gated.
 
@@ -3603,6 +3622,112 @@ Notes:
   grant can be read against the announcement it answers. It is advisory — the
   command's `powerW` remains the only limit.
 
+#### Explaining Why a Command Was Issued
+
+Every data bus command can carry an `EnyoDataBusCommandReason`. Its `type`
+(`EnyoDataBusCommandReasonTypeEnum`) and `category` are **closed, coarse
+vocabularies** — they exist for filtering, iconography and analytics, not for
+narrating a decision. There is no "thermal cost" or "efficiency" member, and you
+must not synthesize one: pick the honest type and attach the numbers.
+
+The prose for the end user lives in `translation` (per language). The numbers
+behind that prose live in the optional `context`
+(`EnyoDataBusCommandReasonContext`), so a consumer can verify, re-render or audit
+the explanation instead of taking it on trust:
+
+| Section | Answers | Key fields |
+| --- | --- | --- |
+| `proactive` | Did we act on a forecast rather than a measurement? | `boolean` |
+| `forecast` | What did we see coming? | `outdoorTemperatureC`, `thresholdTemperatureC`, `windowStartIso`/`windowEndIso`, `triggerTimestampIso` |
+| `placement` | When does the block run, and by when must it be done? | `startIso`, `endIso`, `durationMinutes`, `deadlineIso` |
+| `efficiency` | Why this slot and not the cheaper-looking one? | `coefficientOfPerformance`, `effectiveCostPerKwhThermal`, `compared*` |
+| `thermalStorage` | What ends the block? | `target`, `energyPerKelvinKwh`, `overheatKelvin`, `plannedEnergyKwh`, `absorbableEnergyKwh` |
+
+Worked example — a buffer tank charged ahead of a cold front. The command is
+`ScheduledOptimization` (category `Schedule`), which is the honest type for a
+block an optimizer placed in advance:
+
+```typescript
+import {
+    EnyoCurrencyEnum,
+    EnyoDataBusCommandReason,
+    EnyoDataBusCommandReasonCategoryEnum,
+    EnyoDataBusCommandReasonTypeEnum,
+    EnyoFlexibilityTargetEnum,
+} from '@enyo-energy/energy-app-sdk';
+
+const reason: EnyoDataBusCommandReason = {
+    type: EnyoDataBusCommandReasonTypeEnum.ScheduledOptimization,
+    category: EnyoDataBusCommandReasonCategoryEnum.Schedule,
+    translation: [
+        {
+            language: 'en',
+            value:
+                'Banking 2 hours of cheap heat into the buffer tank before tonight\'s cold front, ' +
+                'so the compressor can coast through the expensive hours.',
+        },
+    ],
+    // Per kWh of *electricity* — the raw price of the chosen slot.
+    electricityPricePerKwh: 0.30,
+    currency: EnyoCurrencyEnum.EUR,
+    context: {
+        // We watch the weather, not the tank.
+        proactive: true,
+        forecast: {
+            outdoorTemperatureC: 6.5,
+            thresholdTemperatureC: 10,
+            windowStartIso: '2026-01-14T12:00:00Z',
+            windowEndIso: '2026-01-15T12:00:00Z',
+            triggerTimestampIso: '2026-01-14T21:00:00Z',
+        },
+        // A 120-minute block, finished before that cold front arrives.
+        placement: {
+            startIso: '2026-01-14T12:00:00Z',
+            endIso: '2026-01-14T14:00:00Z',
+            durationMinutes: 120,
+            deadlineIso: '2026-01-14T21:00:00Z',
+        },
+        // Placed by price ÷ COP, not price alone: a warm midday hour at 30 ct
+        // delivers cheaper heat than a cold night hour at 20 ct.
+        efficiency: {
+            coefficientOfPerformance: 4.2,
+            effectiveCostPerKwhThermal: 0.0714,
+            comparedElectricityPricePerKwh: 0.20,
+            comparedCoefficientOfPerformance: 2.4,
+            comparedEffectiveCostPerKwhThermal: 0.0833,
+            comparedStartIso: '2026-01-14T02:00:00Z',
+        },
+        // And it stops once the store is physically full: the pump tells us one
+        // Kelvin of overheat absorbs 1.2 kWh, so 5 K of headroom is 6.1 kWh.
+        thermalStorage: {
+            target: EnyoFlexibilityTargetEnum.BufferTank,
+            energyPerKelvinKwh: 1.2,
+            overheatKelvin: 5,
+            plannedEnergyKwh: 6.0,
+            absorbableEnergyKwh: 6.1,
+        },
+    },
+};
+```
+
+Notes:
+
+- **`context` is entirely optional and additive.** A reason that sets none of it
+  behaves exactly as before; consumers must tolerate every section being absent.
+- **Costs are not all per kWh of electricity.** `electricityPricePerKwh` is per
+  kWh drawn; `effectiveCostPerKwhThermal` is per kWh *delivered*, in the same
+  `currency`. Mixing the two is what makes an efficiency-placed command look like
+  a mistake.
+- **One rejected alternative, not a solver dump.** The `compared*` fields describe
+  the single best slot that lost, because that is what explains the choice to a
+  person.
+- **Nothing in a reason controls anything.** It explains a command; the command's
+  own fields stay authoritative.
+- **`thermalStorage.target` reuses `EnyoFlexibilityTargetEnum`**, the same
+  vocabulary as flexibility announcements and the `targets` breakdown on
+  available-power commands — so a grant and its justification name the same
+  physical sink without a mapping table.
+
 ### Settings Management
 
 Dynamic configuration with user interface:

package/dist/cjs/implementations/onboarding-v2/define-onboarding-guide-v2.cjs

@@ -243,69 +243,111 @@ exports.onboardingV2Block = {
         outcomes,
     }),
     /**
-     * An EEBUS-pair action block: the installer picks one of the discovered
-     * EEBUS peers and the host trusts its SKI.
+     * A device-select picker: its own screen listing the network devices the run
+     * has found, so the installer can say which one is being onboarded.
      *
-     * A convenience wrapper over {@link onboardingV2Block.action} that pins the
-     * action kind. The picker is drawn from what mDNS discovery found, so the
-     * guide must have scanned — keep
-     * {@link EnyoOnboardingV2Guide.requiresNetworkScan} at its default or place
-     * a {@link EnyoOnboardingV2ActionKind.NetworkScan} block ahead of this one.
+     * Use it whenever a scan can turn up more than one candidate. A
+     * {@link onboardingV2Block.networkScan} branches on found/not-found but binds
+     * nothing, so without this the run does not know *which* device it is working
+     * on — and {@link EnyoOnboardingV2DeviceSelection.Current} and
+     * {@link EnyoOnboardingV2DynamicKind.DeviceIp} have nothing to resolve
+     * against.
      *
-     * Most EEBUS devices only announce themselves once pairing is enabled in
-     * their own menu or portal, and many ask for a confirmation there while the
-     * handshake runs, so put that instruction in a text/hint block on the
-     * preceding step — the app cannot do it for the installer.
+     * The block owns the step: give it one of its own, put the screen's wording
+     * in `headline`/`description` rather than in neighbouring blocks, and let it
+     * disappear when it has nothing to ask — with `autoSelectSingleMatch` left at
+     * its default, a single matching device is bound without rendering anything.
      *
-     * Outcome `value`s must be {@link EnyoOnboardingV2EebusPairOutcome} members;
-     * route `not-found` to troubleshooting and `failure` to a step describing
-     * the confirmation on the device. A retry must lead into a *second* pairing
-     * step: a back-edge onto the same step reads as a loop and ends the run.
+     * The list is what discovery found, so the guide must have scanned: keep
+     * {@link EnyoOnboardingV2Guide.requiresNetworkScan} at its default, or place a
+     * {@link onboardingV2Block.networkScan} ahead of this one.
+     *
+     * Outcome `value`s must be {@link EnyoOnboardingV2DeviceSelectOutcome}
+     * members; route `not-found` to troubleshooting rather than to a step that
+     * assumes a device exists.
+     *
+     * Register an {@link EnyoOnboardingV2DeviceSelectHandler}
+     * ({@link EnergyAppOnboardingV2.registerDeviceSelectHandler}) to turn the pick
+     * into appliances — the host awaits it and binds the run to the ids it
+     * returns, whether or not the screen was shown. Without one the pick binds an
+     * address and nothing more.
      *
      * @param id - Stable block id, unique within the guide.
-     * @param label - Translated trigger button text (de/en).
-     * @param outcomes - The `paired` / `not-found` / `failure` results; each is a routing handle.
+     * @param options - Screen wording, optional `detectedAt` filter, skip
+     *   behaviour, and the `selected` / `not-found` routing handles.
+     * @returns The device-select block.
+     *
+     * @example
+     * ```ts
+     * onboardingV2Block.deviceSelect('pick', {
+     *     headline: t('Gerät auswählen', 'Select the device'),
+     *     description: t(
+     *         'Vergleichen Sie die Seriennummer auf dem Typenschild.',
+     *         'Compare the serial number on the type plate.',
+     *     ),
+     *     detectedAt: [EnyoNetworkDeviceDetectedAtEnum.Modbus],
+     *     outcomes: [
+     *         {id: 'ok',   value: EnyoOnboardingV2DeviceSelectOutcome.Selected, label: t('Ausgewählt', 'Selected')},
+     *         {id: 'none', value: EnyoOnboardingV2DeviceSelectOutcome.NotFound, label: t('Nicht dabei', 'Not listed')},
+     *     ],
+     * });
+     * ```
      */
-    eebusPair: (id, label, outcomes) => ({
+    deviceSelect: (id, options) => ({
         id,
-        type: enyo_onboarding_v2_js_1.EnyoOnboardingV2BlockType.Action,
-        action: enyo_onboarding_v2_js_1.EnyoOnboardingV2ActionKind.EebusPair,
-        label,
-        outcomes,
+        type: enyo_onboarding_v2_js_1.EnyoOnboardingV2BlockType.DeviceSelect,
+        ...options,
     }),
     /**
-     * A device-select block: the installer picks the device being onboarded from
-     * everything the run has found.
+     * An EEBUS device-select picker: its own screen listing the discovered EEBUS
+     * peers, so the installer can pick the one to trust — the host pairs it and
+     * records its SKI.
      *
-     * Use it whenever a scan can turn up more than one candidate. A
-     * {@link block.networkScan} branches on found/not-found but binds nothing,
-     * so without this the run does not know *which* device it is working on —
-     * and {@link EnyoOnboardingV2DeviceSelection.Current} and
-     * {@link EnyoOnboardingV2DynamicKind.DeviceIp} have nothing to resolve
-     * against.
+     * Filter it. `deviceTypes` is what turns this from "here are the six EEBUS
+     * devices in the house" into "here is your heat pump", and with one match it
+     * skips the screen entirely instead of asking a question with one possible
+     * answer.
      *
-     * The picker renders what discovery found, so the guide must have scanned:
-     * keep {@link EnyoOnboardingV2Guide.requiresNetworkScan} at its default, or
-     * place a {@link block.networkScan} ahead of this one.
+     * The picker is drawn from what mDNS discovery found, so the guide must have
+     * scanned — keep {@link EnyoOnboardingV2Guide.requiresNetworkScan} at its
+     * default or place a {@link onboardingV2Block.networkScan} ahead of this one.
      *
-     * Outcome `value`s must be {@link EnyoOnboardingV2DeviceSelectOutcome}
-     * members; route `not-found` to troubleshooting rather than to a step that
-     * assumes a device exists.
+     * Most EEBUS devices only announce themselves once pairing is enabled in
+     * their own menu or portal, and many ask for a confirmation there while the
+     * handshake runs, so put that instruction in a text/hint block on the
+     * preceding step — the app cannot do it for the installer.
      *
-     * Register an {@link EnyoOnboardingV2DeviceSelectHandler} to turn the pick
-     * into appliances — the host awaits it and binds the run to the ids it
-     * returns. Without one the pick binds an address and nothing more.
+     * Outcome `value`s must be {@link EnyoOnboardingV2EebusPairOutcome} members;
+     * route `not-found` to troubleshooting and `failure` to a step describing the
+     * confirmation on the device. A retry must lead into a *second* picker step:
+     * a back-edge onto the same step reads as a loop and ends the run.
+     *
+     * Register an {@link EnyoOnboardingV2EebusDeviceSelectHandler}
+     * ({@link EnergyAppOnboardingV2.registerEebusDeviceSelectHandler}) to turn the
+     * paired peer into appliances.
      *
      * @param id - Stable block id, unique within the guide.
-     * @param label - Translated trigger button text (de/en).
-     * @param outcomes - The `selected` / `not-found` results; each is a routing handle.
+     * @param options - Screen wording, optional `deviceTypes` filter, skip
+     *   behaviour, and the `paired` / `not-found` / `failure` routing handles.
+     * @returns The EEBUS device-select block.
+     *
+     * @example
+     * ```ts
+     * onboardingV2Block.eebusDeviceSelect('pair', {
+     *     headline: t('Wärmepumpe auswählen', 'Select the heat pump'),
+     *     deviceTypes: [EnyoEebusDeviceTypeEnum.HeatPumpAppliance],
+     *     outcomes: [
+     *         {id: 'ok',    value: EnyoOnboardingV2EebusPairOutcome.Paired,   label: t('Gekoppelt', 'Paired')},
+     *         {id: 'none',  value: EnyoOnboardingV2EebusPairOutcome.NotFound, label: t('Nichts gefunden', 'Nothing found')},
+     *         {id: 'error', value: EnyoOnboardingV2EebusPairOutcome.Failure,  label: t('Kopplung fehlgeschlagen', 'Pairing failed')},
+     *     ],
+     * });
+     * ```
      */
-    deviceSelect: (id, label, outcomes) => ({
+    eebusDeviceSelect: (id, options) => ({
         id,
-        type: enyo_onboarding_v2_js_1.EnyoOnboardingV2BlockType.Action,
-        action: enyo_onboarding_v2_js_1.EnyoOnboardingV2ActionKind.DeviceSelect,
-        label,
-        outcomes,
+        type: enyo_onboarding_v2_js_1.EnyoOnboardingV2BlockType.EebusDeviceSelect,
+        ...options,
     }),
     /**
      * An auth block: the installer signs into the energy app's own account

package/dist/cjs/implementations/onboarding-v2/define-onboarding-guide-v2.d.cts

@@ -11,7 +11,7 @@
  */
 import type { EnyoOnboardingTranslatedContent } from '../../types/enyo-onboarding.cjs';
 import { EnyoOnboardingV2ActionKind, EnyoOnboardingV2Credential, EnyoOnboardingV2SelectOption, EnyoOnboardingV2ChoiceLayout, EnyoOnboardingV2DeviceSelection, EnyoOnboardingV2PauseReason } from '../../types/enyo-onboarding-v2.cjs';
-import type { EnyoOnboardingV2ActionOutcome, EnyoOnboardingV2AuthOutcome, EnyoOnboardingV2SetupField, EnyoOnboardingV2SetupOutcome, EnyoOnboardingV2SetupSkipHandle, EnyoOnboardingV2Block, EnyoOnboardingV2ChoiceOption, EnyoOnboardingV2DynamicKind, EnyoOnboardingV2Guide, EnyoOnboardingV2HintVariant, EnyoOnboardingV2InputOutcome, EnyoOnboardingV2InputValueType, EnyoOnboardingV2StartVariant, EnyoOnboardingV2Target, EnyoOnboardingV2Transition } from '../../types/enyo-onboarding-v2.cjs';
+import type { EnyoOnboardingV2ActionOutcome, EnyoOnboardingV2AuthOutcome, EnyoOnboardingV2SetupField, EnyoOnboardingV2SetupOutcome, EnyoOnboardingV2SetupSkipHandle, EnyoOnboardingV2Block, EnyoOnboardingV2ChoiceOption, EnyoOnboardingV2DeviceSelectBlock, EnyoOnboardingV2EebusDeviceSelectBlock, EnyoOnboardingV2DynamicKind, EnyoOnboardingV2Guide, EnyoOnboardingV2HintVariant, EnyoOnboardingV2InputOutcome, EnyoOnboardingV2InputValueType, EnyoOnboardingV2StartVariant, EnyoOnboardingV2Target, EnyoOnboardingV2Transition } from '../../types/enyo-onboarding-v2.cjs';
 /**
  * Identity helper that type-checks a v2 guide literal at definition time
  * (mirrors `defineEnergyAppPackage`). Prefer this over a bare object literal so
@@ -194,58 +194,104 @@ export declare const onboardingV2Block: {
      */
     ocppConnect: (id: string, label: EnyoOnboardingTranslatedContent[], outcomes: EnyoOnboardingV2ActionOutcome[]) => EnyoOnboardingV2Block;
     /**
-     * An EEBUS-pair action block: the installer picks one of the discovered
-     * EEBUS peers and the host trusts its SKI.
-     *
-     * A convenience wrapper over {@link onboardingV2Block.action} that pins the
-     * action kind. The picker is drawn from what mDNS discovery found, so the
-     * guide must have scanned — keep
-     * {@link EnyoOnboardingV2Guide.requiresNetworkScan} at its default or place
-     * a {@link EnyoOnboardingV2ActionKind.NetworkScan} block ahead of this one.
-     *
-     * Most EEBUS devices only announce themselves once pairing is enabled in
-     * their own menu or portal, and many ask for a confirmation there while the
-     * handshake runs, so put that instruction in a text/hint block on the
-     * preceding step — the app cannot do it for the installer.
-     *
-     * Outcome `value`s must be {@link EnyoOnboardingV2EebusPairOutcome} members;
-     * route `not-found` to troubleshooting and `failure` to a step describing
-     * the confirmation on the device. A retry must lead into a *second* pairing
-     * step: a back-edge onto the same step reads as a loop and ends the run.
-     *
-     * @param id - Stable block id, unique within the guide.
-     * @param label - Translated trigger button text (de/en).
-     * @param outcomes - The `paired` / `not-found` / `failure` results; each is a routing handle.
-     */
-    eebusPair: (id: string, label: EnyoOnboardingTranslatedContent[], outcomes: EnyoOnboardingV2ActionOutcome[]) => EnyoOnboardingV2Block;
-    /**
-     * A device-select block: the installer picks the device being onboarded from
-     * everything the run has found.
+     * A device-select picker: its own screen listing the network devices the run
+     * has found, so the installer can say which one is being onboarded.
      *
      * Use it whenever a scan can turn up more than one candidate. A
-     * {@link block.networkScan} branches on found/not-found but binds nothing,
-     * so without this the run does not know *which* device it is working on —
-     * and {@link EnyoOnboardingV2DeviceSelection.Current} and
+     * {@link onboardingV2Block.networkScan} branches on found/not-found but binds
+     * nothing, so without this the run does not know *which* device it is working
+     * on — and {@link EnyoOnboardingV2DeviceSelection.Current} and
      * {@link EnyoOnboardingV2DynamicKind.DeviceIp} have nothing to resolve
      * against.
      *
-     * The picker renders what discovery found, so the guide must have scanned:
-     * keep {@link EnyoOnboardingV2Guide.requiresNetworkScan} at its default, or
-     * place a {@link block.networkScan} ahead of this one.
+     * The block owns the step: give it one of its own, put the screen's wording
+     * in `headline`/`description` rather than in neighbouring blocks, and let it
+     * disappear when it has nothing to ask — with `autoSelectSingleMatch` left at
+     * its default, a single matching device is bound without rendering anything.
+     *
+     * The list is what discovery found, so the guide must have scanned: keep
+     * {@link EnyoOnboardingV2Guide.requiresNetworkScan} at its default, or place a
+     * {@link onboardingV2Block.networkScan} ahead of this one.
      *
      * Outcome `value`s must be {@link EnyoOnboardingV2DeviceSelectOutcome}
      * members; route `not-found` to troubleshooting rather than to a step that
      * assumes a device exists.
      *
-     * Register an {@link EnyoOnboardingV2DeviceSelectHandler} to turn the pick
+     * Register an {@link EnyoOnboardingV2DeviceSelectHandler}
+     * ({@link EnergyAppOnboardingV2.registerDeviceSelectHandler}) to turn the pick
      * into appliances — the host awaits it and binds the run to the ids it
-     * returns. Without one the pick binds an address and nothing more.
+     * returns, whether or not the screen was shown. Without one the pick binds an
+     * address and nothing more.
      *
      * @param id - Stable block id, unique within the guide.
-     * @param label - Translated trigger button text (de/en).
-     * @param outcomes - The `selected` / `not-found` results; each is a routing handle.
+     * @param options - Screen wording, optional `detectedAt` filter, skip
+     *   behaviour, and the `selected` / `not-found` routing handles.
+     * @returns The device-select block.
+     *
+     * @example
+     * ```ts
+     * onboardingV2Block.deviceSelect('pick', {
+     *     headline: t('Gerät auswählen', 'Select the device'),
+     *     description: t(
+     *         'Vergleichen Sie die Seriennummer auf dem Typenschild.',
+     *         'Compare the serial number on the type plate.',
+     *     ),
+     *     detectedAt: [EnyoNetworkDeviceDetectedAtEnum.Modbus],
+     *     outcomes: [
+     *         {id: 'ok',   value: EnyoOnboardingV2DeviceSelectOutcome.Selected, label: t('Ausgewählt', 'Selected')},
+     *         {id: 'none', value: EnyoOnboardingV2DeviceSelectOutcome.NotFound, label: t('Nicht dabei', 'Not listed')},
+     *     ],
+     * });
+     * ```
+     */
+    deviceSelect: (id: string, options: Omit<EnyoOnboardingV2DeviceSelectBlock, "id" | "type">) => EnyoOnboardingV2Block;
+    /**
+     * An EEBUS device-select picker: its own screen listing the discovered EEBUS
+     * peers, so the installer can pick the one to trust — the host pairs it and
+     * records its SKI.
+     *
+     * Filter it. `deviceTypes` is what turns this from "here are the six EEBUS
+     * devices in the house" into "here is your heat pump", and with one match it
+     * skips the screen entirely instead of asking a question with one possible
+     * answer.
+     *
+     * The picker is drawn from what mDNS discovery found, so the guide must have
+     * scanned — keep {@link EnyoOnboardingV2Guide.requiresNetworkScan} at its
+     * default or place a {@link onboardingV2Block.networkScan} ahead of this one.
+     *
+     * Most EEBUS devices only announce themselves once pairing is enabled in
+     * their own menu or portal, and many ask for a confirmation there while the
+     * handshake runs, so put that instruction in a text/hint block on the
+     * preceding step — the app cannot do it for the installer.
+     *
+     * Outcome `value`s must be {@link EnyoOnboardingV2EebusPairOutcome} members;
+     * route `not-found` to troubleshooting and `failure` to a step describing the
+     * confirmation on the device. A retry must lead into a *second* picker step:
+     * a back-edge onto the same step reads as a loop and ends the run.
+     *
+     * Register an {@link EnyoOnboardingV2EebusDeviceSelectHandler}
+     * ({@link EnergyAppOnboardingV2.registerEebusDeviceSelectHandler}) to turn the
+     * paired peer into appliances.
+     *
+     * @param id - Stable block id, unique within the guide.
+     * @param options - Screen wording, optional `deviceTypes` filter, skip
+     *   behaviour, and the `paired` / `not-found` / `failure` routing handles.
+     * @returns The EEBUS device-select block.
+     *
+     * @example
+     * ```ts
+     * onboardingV2Block.eebusDeviceSelect('pair', {
+     *     headline: t('Wärmepumpe auswählen', 'Select the heat pump'),
+     *     deviceTypes: [EnyoEebusDeviceTypeEnum.HeatPumpAppliance],
+     *     outcomes: [
+     *         {id: 'ok',    value: EnyoOnboardingV2EebusPairOutcome.Paired,   label: t('Gekoppelt', 'Paired')},
+     *         {id: 'none',  value: EnyoOnboardingV2EebusPairOutcome.NotFound, label: t('Nichts gefunden', 'Nothing found')},
+     *         {id: 'error', value: EnyoOnboardingV2EebusPairOutcome.Failure,  label: t('Kopplung fehlgeschlagen', 'Pairing failed')},
+     *     ],
+     * });
+     * ```
      */
-    deviceSelect: (id: string, label: EnyoOnboardingTranslatedContent[], outcomes: EnyoOnboardingV2ActionOutcome[]) => EnyoOnboardingV2Block;
+    eebusDeviceSelect: (id: string, options: Omit<EnyoOnboardingV2EebusDeviceSelectBlock, "id" | "type">) => EnyoOnboardingV2Block;
     /**
      * An auth block: the installer signs into the energy app's own account
      * system (OAuth / vendor portal).

package/dist/cjs/implementations/onboarding-v2/onboarding-v2-provider-validators.cjs

@@ -4,12 +4,15 @@
  * answer an app hands back when the host asks for its v2 onboarding guides.
  *
  * {@link validateOnboardingGuideV2} checks one guide's graph. This checks the
- * *set*: that every guide in it is publishable, that each one says which
- * vendor/model/start-variant it applies to, and that no two of them claim the
- * same one. Those last two only become checkable here, because a guide is now
- * selected out of an app's own answer rather than bound to a catalog entry at
- * publish time — a guide with no binding can never be chosen for a device, and
- * two guides with the same binding leave the host with no way to pick.
+ * *set*: that every guide in it is publishable and that no two of them use the
+ * same `name`, which is the handle an app addresses one specific guide by.
+ *
+ * It deliberately says nothing about vendor and model bindings. Those are
+ * enyo's — attached when a guide is registered, derived from the package serving
+ * it and the vendor catalog — so an app's answer cannot claim one, cannot
+ * collide on one, and should not carry one
+ * ({@link EnyoOnboardingV2Guide.vendorId}). A guide that sets them anyway is
+ * warned about by {@link validateOnboardingGuideV2}.
  *
  * `errors` mean the answer is not fit to return; `warnings` are advisory. Use
  * {@link validateOnboardingV2GuidesResult} for the non-throwing result, or
@@ -38,12 +41,6 @@ class OnboardingV2GuidesValidationError extends Error {
     }
 }
 exports.OnboardingV2GuidesValidationError = OnboardingV2GuidesValidationError;
-/**
- * Placeholder used in a binding key for a guide that names no model — it applies
- * to every model of its vendor, and therefore collides with any other such guide
- * for the same vendor and start variant.
- */
-const ANY_MODEL = '*';
 /**
  * A short human-readable label for a guide, for use in messages.
  *
@@ -62,25 +59,9 @@ function guideLabel(guide, index) {
     const title = guide.title?.[0]?.value;
     return `guides[${index}] (${title ? `"${title}"` : (guide.startVariant ?? '?')})`;
 }
-/**
- * Every (vendor, model, start variant) binding a guide claims.
- *
- * A guide with several `modelIds` claims one binding per model, so two guides
- * that overlap on a single model collide even when the rest of their model lists
- * differ.
- *
- * @param guide - The guide to derive bindings for.
- * @returns The binding keys, or an empty array when the guide names no vendor.
- */
-function bindingKeys(guide) {
-    if (!guide.vendorId)
-        return [];
-    const models = guide.modelIds?.length ? guide.modelIds : [ANY_MODEL];
-    return models.map((modelId) => `${guide.vendorId}|${modelId}|${guide.startVariant}`);
-}
 /**
  * Validates a complete guides answer: the envelope, every guide in it, and the
- * bindings across them.
+ * `name` handles across them.
  *
  * Each guide is run through {@link validateOnboardingGuideV2}, and its errors
  * and warnings are surfaced here prefixed with the guide's position — pass the
@@ -124,23 +105,14 @@ function validateOnboardingV2GuidesResult(result, context) {
         warnings.push('Empty `guides` retires every guide the host cached for this app. ' +
             'Resolve the handler with `null` instead if the intent was "no answer right now".');
     }
-    // Which guide(s) claimed each binding, so a collision can name both sides.
-    const claimedBy = new Map();
-    // Same, for the explicit `name` handles — a duplicate makes an app unable to
-    // say which of the two it means.
+    // The explicit `name` handles — a duplicate makes an app unable to say which
+    // of the two guides it means.
     const namedBy = new Map();
     for (const [i, guide] of result.guides.entries()) {
         const at = guideLabel(guide, i);
         const guideResult = (0, onboarding_v2_validators_js_1.validateOnboardingGuideV2)(guide, context);
         errors.push(...guideResult.errors.map((e) => `${at}: ${e}`));
         warnings.push(...guideResult.warnings.map((w) => `${at}: ${w}`));
-        if (!guide.vendorId) {
-            warnings.push(`${at}: no vendorId — the host matches a run by vendor, model and start variant, ` +
-                'so an unbound guide can never be selected.');
-        }
-        else if (!guide.modelIds?.length) {
-            warnings.push(`${at}: no modelIds — this guide applies to every model of "${guide.vendorId}".`);
-        }
         const name = guide.name?.trim();
         if (name) {
             const previouslyNamed = namedBy.get(name);
@@ -152,16 +124,6 @@ function validateOnboardingV2GuidesResult(result, context) {
                 namedBy.set(name, at);
             }
         }
-        for (const key of bindingKeys(guide)) {
-            const previous = claimedBy.get(key);
-            if (previous) {
-                errors.push(`${at}: binding "${key}" is already claimed by ${previous} — ` +
-                    'the host cannot choose between two guides for the same vendor, model and start variant.');
-            }
-            else {
-                claimedBy.set(key, at);
-            }
-        }
     }
     return { ok: errors.length === 0, errors, warnings };
 }

package/dist/cjs/implementations/onboarding-v2/onboarding-v2-provider-validators.d.cts

@@ -3,12 +3,15 @@
  * answer an app hands back when the host asks for its v2 onboarding guides.
  *
  * {@link validateOnboardingGuideV2} checks one guide's graph. This checks the
- * *set*: that every guide in it is publishable, that each one says which
- * vendor/model/start-variant it applies to, and that no two of them claim the
- * same one. Those last two only become checkable here, because a guide is now
- * selected out of an app's own answer rather than bound to a catalog entry at
- * publish time — a guide with no binding can never be chosen for a device, and
- * two guides with the same binding leave the host with no way to pick.
+ * *set*: that every guide in it is publishable and that no two of them use the
+ * same `name`, which is the handle an app addresses one specific guide by.
+ *
+ * It deliberately says nothing about vendor and model bindings. Those are
+ * enyo's — attached when a guide is registered, derived from the package serving
+ * it and the vendor catalog — so an app's answer cannot claim one, cannot
+ * collide on one, and should not carry one
+ * ({@link EnyoOnboardingV2Guide.vendorId}). A guide that sets them anyway is
+ * warned about by {@link validateOnboardingGuideV2}.
  *
  * `errors` mean the answer is not fit to return; `warnings` are advisory. Use
  * {@link validateOnboardingV2GuidesResult} for the non-throwing result, or
@@ -40,7 +43,7 @@ export interface OnboardingV2GuidesValidationResult {
 }
 /**
  * Validates a complete guides answer: the envelope, every guide in it, and the
- * bindings across them.
+ * `name` handles across them.
  *
  * Each guide is run through {@link validateOnboardingGuideV2}, and its errors
  * and warnings are surfaced here prefixed with the guide's position — pass the