diff --git a/openspec/changes/scoped-beer-override/.openspec.yaml b/openspec/changes/archive/2026-09-16-scoped-beer-override/.openspec.yaml similarity index 100% rename from openspec/changes/scoped-beer-override/.openspec.yaml rename to openspec/changes/archive/2026-09-16-scoped-beer-override/.openspec.yaml diff --git a/openspec/changes/scoped-beer-override/design.md b/openspec/changes/archive/2026-09-16-scoped-beer-override/design.md similarity index 100% rename from openspec/changes/scoped-beer-override/design.md rename to openspec/changes/archive/2026-09-16-scoped-beer-override/design.md diff --git a/openspec/changes/scoped-beer-override/proposal.md b/openspec/changes/archive/2026-09-16-scoped-beer-override/proposal.md similarity index 100% rename from openspec/changes/scoped-beer-override/proposal.md rename to openspec/changes/archive/2026-09-16-scoped-beer-override/proposal.md diff --git a/openspec/changes/scoped-beer-override/specs/card-config/spec.md b/openspec/changes/archive/2026-09-16-scoped-beer-override/specs/card-config/spec.md similarity index 100% rename from openspec/changes/scoped-beer-override/specs/card-config/spec.md rename to openspec/changes/archive/2026-09-16-scoped-beer-override/specs/card-config/spec.md diff --git a/openspec/changes/scoped-beer-override/specs/keg-auto-detection/spec.md b/openspec/changes/archive/2026-09-16-scoped-beer-override/specs/keg-auto-detection/spec.md similarity index 100% rename from openspec/changes/scoped-beer-override/specs/keg-auto-detection/spec.md rename to openspec/changes/archive/2026-09-16-scoped-beer-override/specs/keg-auto-detection/spec.md diff --git a/openspec/changes/scoped-beer-override/tasks.md b/openspec/changes/archive/2026-09-16-scoped-beer-override/tasks.md similarity index 100% rename from openspec/changes/scoped-beer-override/tasks.md rename to openspec/changes/archive/2026-09-16-scoped-beer-override/tasks.md diff --git a/openspec/specs/beer-catalog/spec.md b/openspec/specs/beer-catalog/spec.md index 3781fb6..6323c0f 100644 --- a/openspec/specs/beer-catalog/spec.md +++ b/openspec/specs/beer-catalog/spec.md @@ -28,11 +28,11 @@ The card SHALL include static logo images for beers in the built-in catalog. - **THEN** the card SHALL display the beer's brand color palette as the visual background instead of an image ### Requirement: Custom beer entries via configuration -The card SHALL support user-defined beer entries that extend or override the built-in catalog, reachable through the `beer_name` override. +The card SHALL support user-defined beer entries that extend or override the built-in catalog, reachable through a `beer_overrides` entry. #### Scenario: Custom beer defined in config - **WHEN** the card config includes a `custom_beers` array with entries containing at minimum a `name` field -- **THEN** those beers SHALL be resolvable by the `beer_name` override alongside built-in entries +- **THEN** those beers SHALL be resolvable by a `beer_overrides` entry alongside built-in entries - **THEN** custom entries SHALL support optional fields: `color_primary`, `color_secondary`, `color_text`, `image_url`, `brewery`, `style`, `abv` #### Scenario: Custom beer overrides built-in diff --git a/openspec/specs/beer-label/spec.md b/openspec/specs/beer-label/spec.md index 4783671..5b98a67 100644 --- a/openspec/specs/beer-label/spec.md +++ b/openspec/specs/beer-label/spec.md @@ -31,7 +31,7 @@ The card SHALL display the current beer temperature prominently in the left zone The card SHALL display the detected beer's name in the label zone below the temperature, using the card's own curated name where it has one. #### Scenario: Beer detected -- **WHEN** a beer has been determined by detection or by the `beer_name` override +- **WHEN** a beer has been determined by detection or by a `beer_overrides` entry - **THEN** the card SHALL display that beer's full name as text in the label zone #### Scenario: Detected by product ID diff --git a/openspec/specs/card-config/spec.md b/openspec/specs/card-config/spec.md index 1da0aec..ffea211 100644 --- a/openspec/specs/card-config/spec.md +++ b/openspec/specs/card-config/spec.md @@ -50,14 +50,20 @@ The card SHALL validate its configuration and display clear errors for invalid c - **WHEN** the card config specifies a `glass_size` that is not one of the supported values (250, 330, 500, 568, 473) - **THEN** the card SHALL fall back to the default of 330 mL -#### Scenario: Unknown beer_name override -- **WHEN** the card config specifies a `beer_name` that does not match any beer in the catalog (built-in or custom) +#### Scenario: Unknown beer name in an override entry +- **WHEN** a `beer_overrides` entry whose key matches the reported product ID names a beer that matches nothing in the catalog (built-in or custom) - **THEN** the card SHALL treat it as a custom beer with that name and use a generic color palette -- **THEN** the card SHALL NOT fall back to auto-detection, since an explicit override signals the user's intent +- **THEN** the card SHALL NOT fall back to auto-detection, since a matching override signals the user's intent + +#### Scenario: Override entry with a malformed key +- **WHEN** a `beer_overrides` key does not correspond to any product ID the machine reports +- **THEN** the card SHALL ignore that entry without throwing +- **THEN** the card SHALL resolve the beer by detection #### Scenario: Removed configuration keys ignored -- **WHEN** the card config contains `beer_entity`, which is no longer supported -- **THEN** the card SHALL ignore it without throwing +- **WHEN** the card config contains `beer_entity` or `beer_name`, neither of which is supported +- **THEN** the card SHALL ignore them without throwing +- **THEN** the card SHALL resolve the beer by detection as though the key were absent ### Requirement: Visual card editor The card SHALL provide a graphical configuration editor as the primary means of configuration. @@ -69,9 +75,10 @@ The card SHALL provide a graphical configuration editor as the primary means of #### Scenario: Editor fields - **WHEN** the visual editor is displayed -- **THEN** it SHALL provide: a device picker (dropdown of discovered PerfectDraft devices), glass size (dropdown of five options), layout selection, and an optional beer override -- **THEN** all fields SHALL be UI controls — no freeform text input for entity IDs +- **THEN** it SHALL provide: a device picker (dropdown of discovered PerfectDraft devices), glass size (dropdown of five options), layout selection, and a correction control scoped to the currently detected keg +- **THEN** all fields SHALL be UI controls — no freeform text input for entity IDs or product IDs - **THEN** the editor SHALL NOT present beer selection as a required or default setting +- **THEN** the editor SHALL NOT offer a beer setting that applies regardless of which keg is tapped #### Scenario: Editor fires config-changed events - **WHEN** the user changes any editor field @@ -79,15 +86,15 @@ The card SHALL provide a graphical configuration editor as the primary means of - **THEN** the card preview SHALL update to reflect the change ### Requirement: Custom beers configuration -The card SHALL support extending the beer catalog via the `custom_beers` config array, reachable through the `beer_name` override. +The card SHALL support extending the beer catalog via the `custom_beers` config array, reachable through a `beer_overrides` entry. #### Scenario: Custom beer entry structure - **WHEN** a `custom_beers` array entry is provided in config - **THEN** it SHALL require at minimum a `name` field (string) - **THEN** it SHALL accept optional fields: `color_primary` (CSS color), `color_secondary` (CSS color), `color_text` (CSS color), `image_url` (URL string), `brewery` (string), `style` (string), `abv` (number) -#### Scenario: Custom beer selected by override -- **WHEN** `beer_name` matches the `name` of a `custom_beers` entry +#### Scenario: Custom beer selected by a matching override +- **WHEN** a `beer_overrides` entry matching the reported product ID names the same string as the `name` of a `custom_beers` entry - **THEN** the card SHALL display that custom beer using its configured colors and image ### Requirement: YAML remains valid for power users @@ -98,20 +105,32 @@ While not required, the YAML config SHALL remain a valid and complete representa - **THEN** the resulting YAML SHALL contain all settings as readable key-value pairs - **THEN** editing that YAML directly and saving SHALL produce the same card behaviour as the editor -### Requirement: Optional manual beer override -The card SHALL accept an optional `beer_name` config value that overrides auto-detection, so a user is never stuck with a wrong or unrecognised beer. +### Requirement: Keg-scoped beer overrides configuration +The card SHALL accept an optional `beer_overrides` config map, keyed by the product ID the integration reports, so a correction is bound to the keg it corrects. -#### Scenario: Override absent -- **WHEN** the card config has no `beer_name` +#### Scenario: Map shape +- **WHEN** a `beer_overrides` value is provided in config +- **THEN** each key SHALL be the product ID string as reported by the `keg_product_id` sensor +- **THEN** each value SHALL be a beer name resolvable against the catalog, a catalog slug, or the `name` of a `custom_beers` entry + +#### Scenario: Overrides absent +- **WHEN** the card config has no `beer_overrides` - **THEN** the card SHALL rely entirely on auto-detection -- **THEN** `getStubConfig()` SHALL NOT populate `beer_name`, so newly created cards start with detection only +- **THEN** `getStubConfig()` SHALL NOT populate `beer_overrides`, so newly created cards start with detection only -#### Scenario: Override set -- **WHEN** the card config sets `beer_name` -- **THEN** the card SHALL display the beer resolved from that value regardless of what the keg sensors report +#### Scenario: Entry recorded against the currently tapped keg +- **WHEN** the user corrects the detected beer from the visual editor +- **THEN** the editor SHALL write a single `beer_overrides` entry keyed by the product ID currently reported for the configured device +- **THEN** the editor SHALL NOT write an entry that is not keyed by a reported product ID -#### Scenario: Override presented as optional in the editor -- **WHEN** the visual editor is displayed -- **THEN** the beer override field SHALL be empty by default and SHALL be labelled as an override for when detection is wrong -- **THEN** clearing the field SHALL remove `beer_name` from the config and return the card to detection +#### Scenario: No product ID currently reported +- **WHEN** the visual editor is displayed AND the configured device reports no usable `keg_product_id` state +- **THEN** the correction control SHALL be shown in a disabled state with an explanation that a keg must be detected first +- **THEN** the editor SHALL NOT be prevented from displaying or removing existing entries + +#### Scenario: Existing entries are reviewable and removable +- **WHEN** the visual editor is displayed AND `beer_overrides` contains entries +- **THEN** the editor SHALL list each entry with the product ID and the beer it names +- **THEN** the editor SHALL provide a control to remove an individual entry +- **THEN** removing the last entry SHALL remove `beer_overrides` from the config diff --git a/openspec/specs/keg-auto-detection/spec.md b/openspec/specs/keg-auto-detection/spec.md index 7785207..cbaf04d 100644 --- a/openspec/specs/keg-auto-detection/spec.md +++ b/openspec/specs/keg-auto-detection/spec.md @@ -25,13 +25,18 @@ The card SHALL apply a single, defined precedence order when determining which b #### Scenario: Precedence order - **WHEN** the card determines the beer to display -- **THEN** it SHALL apply the first applicable source in this order: (1) the `beer_name` config override, (2) a catalog entry matched by reported product ID, (3) a beer resolved from the reported keg name, (4) the no-keg-detected state +- **THEN** it SHALL apply the first applicable source in this order: (1) a `beer_overrides` entry whose key matches the reported product ID, (2) a catalog entry matched by reported product ID, (3) a beer resolved from the reported keg name, (4) the no-keg-detected state - **THEN** no later source SHALL override an earlier one -#### Scenario: Override wins over successful detection -- **WHEN** `beer_name` is set in config AND the product ID resolves to a different catalog entry -- **THEN** the card SHALL display the beer named by `beer_name` -- **THEN** the card SHALL NOT silently substitute the detected beer +#### Scenario: Matching override wins over successful detection +- **WHEN** a `beer_overrides` entry matches the reported product ID AND that same product ID also resolves to a different catalog entry +- **THEN** the card SHALL display the beer named by the override entry +- **THEN** the card SHALL indicate that an override is in effect rather than substituting silently + +#### Scenario: No configured value can precede detection unconditionally +- **WHEN** the card determines the beer to display +- **THEN** no config value SHALL take precedence over detection except by matching the currently reported product ID +- **THEN** a config value that names a beer without reference to a product ID SHALL NOT affect the displayed beer ### Requirement: Curated name preferred for the label When the card recognises the reported product ID, it SHALL use its own catalog name for display rather than the name reported by the integration. @@ -91,3 +96,47 @@ The card SHALL continue attempting entity resolution until the expected sensors - **THEN** the card SHALL resolve entities afresh for the newly configured device - **THEN** the card SHALL NOT display values read from the previous device +### Requirement: Manual override scoped to the reported keg +A manual override SHALL apply only while the machine reports the product ID that override was recorded against, so that a correction cannot outlive the keg it corrects. + +#### Scenario: Override applies to the keg it was recorded for +- **WHEN** `beer_overrides` contains an entry whose key equals the state of the `keg_product_id` sensor +- **THEN** the card SHALL display the beer resolved from that entry's value, resolved by catalog name, slug, or matching `custom_beers` entry +- **THEN** the card SHALL use that beer for the name, brand colors, style, ABV, and artwork + +#### Scenario: Override does not apply to a different keg +- **WHEN** `beer_overrides` contains entries AND none of their keys equals the reported `keg_product_id` state +- **THEN** the card SHALL ignore every entry and resolve the beer by detection +- **THEN** the card SHALL NOT display any beer named by a non-matching entry + +#### Scenario: Override for an unrecognised product ID +- **WHEN** the reported `keg_product_id` matches no catalog entry's `kegId` AND `beer_overrides` contains an entry for that ID +- **THEN** the card SHALL display the beer named by that entry +- **THEN** the card SHALL NOT fall back to the integration-reported keg name + +#### Scenario: No override applies when no keg is reported +- **WHEN** the `keg_product_id` sensor reports no usable state AND `beer_overrides` contains entries +- **THEN** the card SHALL enter the no-keg-detected state +- **THEN** the card SHALL NOT display any beer named by `beer_overrides` + +#### Scenario: Override entry naming an unknown beer +- **WHEN** a matching `beer_overrides` entry names a beer present in neither the catalog nor `custom_beers` +- **THEN** the card SHALL display that name against the generic color palette +- **THEN** the card SHALL NOT fall back to detection, since a matching override signals the user's intent for this keg + +### Requirement: Active override is visible +When the card displays a beer because of an override rather than detection, it SHALL make that visible, so a user can tell an override from a detection result without reading config. + +#### Scenario: Override applied +- **WHEN** the card displays a beer resolved from a matching `beer_overrides` entry +- **THEN** the card SHALL render an indication that an override is in effect + +#### Scenario: Override contradicts detection +- **WHEN** an override is applied AND detection would have resolved a different beer for the same keg +- **THEN** the indication SHALL identify the beer that detection resolved +- **THEN** the card SHALL NOT silently present the override as a detection result + +#### Scenario: No override applied +- **WHEN** the card displays a beer resolved by detection with no matching override +- **THEN** the card SHALL NOT render an override indication +