adaptive-lighting/openspec/changes/cdit-config-redesign/design.md

## Context

Upstream `basnijholt/adaptive-lighting` is a mature HA custom component (~10k LOC, 800+ stars). Its options flow is built by iterating over `VALIDATION_TUPLES` in `const.py` — 39 entries, each a `(key, default, voluptuous_validator)` tuple. The result is one flat `vol.Schema` rendered as a single tall form with no grouping, no conditional visibility, custom `int_between` validators (no slider UI), and silent no-op behavior when the entry was YAML-configured.

CDiT's install is one household, opinionated about scenes and house modes, and uses Sun2 for precise twilight events. Half of upstream's options are dead weight in that context (sleep mode, take-over-control, manual sun-time math). The other half is hard to find because nothing is grouped.

This change resets the dialog. It also removes the sleep-mode switch entity from the switch platform — sleep mode is dropped wholesale, not just hidden.

## Goals / Non-Goals

**Goals:**
- 18-field dialog that fits on one screen via collapsible sections.
- Sun curve driven by HA entities, so Sun2 (or any other twilight source) plugs in via the existing entity selector.
- Native HA selectors for everything (sliders, dropdowns, entity pickers) instead of voluptuous `int_between` wrappers.
- Reload-on-save without manual `async_unload_entry` / `async_setup_entry` plumbing.
- Honest message when the entry is YAML-managed (currently silently no-ops).
- One-shot break: no migration code, manifest version bump, clear "recreate your entry" message.

**Non-Goals:**
- Multi-step wizard. Editing dominates over setup in this integration's lifetime; sections beat steps.
- Backwards compatibility with upstream config entries.
- Translations beyond `en.json`. Other locales are out of scope; upstream's translations can be culled in a follow-up.
- Replacing the simulator webapp at `webapp/`. It targets the upstream curve model and is decoupled from the HA integration. Out of scope.
- Removing `astral` as a transitive dep. It's still imported elsewhere; pruning it is a follow-up.
- Touching `tests/` for unaffected features (color helpers, light state diffing, etc.). Only config-flow, sleep-mode, and take-over-control tests get rewritten.

## Decisions

### Decision 1: Collapsible sections via HA's `section()` helper, not a multi-step flow

**What we chose:** One `async_step_init` that returns a single schema with grouped sections built via the HA Frontend `section()` helper. All fields visible (or conditionally visible) on one screen.

**Why:** Setup happens once per AL config; editing happens dozens of times over the install's lifetime. Wizards optimize for first-run cost (guidance) at the expense of every subsequent edit (clicks). Sections give us guidance through grouping while keeping editing fast.

**Alternatives considered:**
- **Multi-step flow** (`async_step_basics` → `async_step_curve` → ...). Rejected — every edit becomes a click-through. Also, conditional visibility across steps is messier than within a single section-grouped form.
- **One flat dialog with field-order reshuffling.** Rejected — without visual grouping, ordering alone doesn't communicate which fields belong together.

### Decision 2: Entity-driven sun timing, no `astral` in the curve path

**What we chose:** Two entity selectors (`sunrise_entity`, `sunset_entity`) of `domain: sensor, device_class: timestamp`. Defaults to built-in `sensor.sun_next_rising` / `sensor.sun_next_setting`. The curve math reads `hass.states.get(<entity_id>)` for the timestamps, not `astral`.

**Why:** Lets Sun2 (or any custom sun source) plug in without a code change. Matches HA convention ("everything is an entity"). Decouples us from `astral`'s quirks at high latitudes (irrelevant to Germany, but it's free elegance). Single source of truth — your `sensor.sun_next_rising` is also what every other automation in the house reads.

**Alternatives considered:**
- **Keep `astral` and offer a "sun source" toggle.** Rejected — code path bifurcation, two implementations to test, defeats the simplification goal.
- **Hardcode `sun.sun` and drop the selector.** Rejected — explicitly precludes Sun2, which is the whole reason to refactor sun timing.

### Decision 3: Hardcoded tanh curve with 30-minute half-width

**What we chose:** `brightness_mode` field is deleted. Curve is always tanh. The half-width (`brightness_mode_time_dark` / `_time_light` upstream) is hardcoded as a single constant `RAMP_HALF_WIDTH_SECONDS = 1800` in `const.py`.

**Why:** Three modes (default / linear / tanh) were a research-era artifact; tanh is the eye-friendly choice for any household use case. The half-width sweet spot (30 min) is well-studied for circadian-friendly transitions and looks reasonable from solstice (sunrise 04:30) to equinox (sunrise 06:00). Removing the knob removes a UX maze.

**Alternatives considered:**
- **Keep `brightness_mode` as a hidden constant, expose half-width.** Rejected — same maintenance cost as keeping both, with no real win.
- **Expose half-width as one Advanced slider.** Rejected (initially considered). One less knob is genuinely better than one customizable knob — advanced fields rot when unused.

### Decision 4: Strict break, no migration code

**What we chose:** Bump `manifest.json` major version (1.x → 2.0.0-cdit.1). On upgrade, HA fails to load old config entries with a "this version is incompatible" toast. User recreates the entry manually.

**Why:** Single-household fork. The cost of one manual re-setup is ~5 minutes. Migration code that strips removed keys and silently translates old values would be ~50 LOC, would carry across the next two breaks, and is the kind of code that hides edge-case bugs.

**Alternatives considered:**
- **Silent strip on `async_setup_entry`.** Rejected — looks magical, hides which fields the user thought were configured.
- **`async_migrate_entry` with explicit version bump.** Rejected — correct for a public fork, overkill for one user. Re-evaluate if anyone outside CDiT installs this.

### Decision 5: Native HA selectors instead of voluptuous `int_between`

**What we chose:** `NumberSelector` with `min`, `max`, `step`, `unit_of_measurement`, `mode=NumberSelectorMode.SLIDER` (or `BOX` for fine-grained); `EntitySelector` with domain/device_class filters; `BooleanSelector`; `DurationSelector` for time intervals. All in `homeassistant.helpers.selector`.

**Why:** Selectors render as proper UI (sliders, dropdowns, color pickers, entity pickers). `int_between(1, 100)` validates correctly but renders as a plain text field — same UX whether the range is brightness, color temp, or seconds. Selectors are the direction HA core is moving; staying on voluptuous custom validators means re-implementing this every minor HA release.

**Alternatives considered:**
- **Keep voluptuous wrappers, restyle via custom frontend card.** Rejected — explicitly pulls us into frontend territory, which is out of scope for this change.

### Decision 6: `OptionsFlowWithReload` instead of manual reload

**What we chose:** Subclass `homeassistant.config_entries.OptionsFlowWithReload` (added to HA core in 2024.10). Override `async_step_init` only. No `async_unload_entry` / `async_setup_entry` reload plumbing.

**Why:** The documented, supported path. Manual reload has subtle bugs around entity registry stale state and listener leakage. `OptionsFlowWithReload` handles them by tearing down and rebuilding the entry atomically.

**Alternatives considered:**
- **Stay on `OptionsFlow` and call `hass.config_entries.async_reload(...)` manually after save.** Rejected — duplicates HA framework code, easy to forget on edge paths.

### Decision 7: Delete the sleep mode switch entity, don't hide it

**What we chose:** Remove the sleep-mode switch class from `switch.py` entirely. Each AL config now creates 3 switches (master, adapt_brightness, adapt_color), not 4. Sleep-mode state machine is also stripped from the master switch class.

**Why:** Keeping unused entities pollutes the device page, accumulates state, and creates ambiguity ("will this wake up if I flip it?"). Hiding from UI but keeping the code path means the state machine still runs, just invisibly — worst of both worlds.

**Alternatives considered:**
- **Keep the entity, hide from UI.** Rejected — see above.
- **Keep the class, gate behind a feature flag.** Rejected — dead code with a flag is still dead code.

### Decision 8: Delete take-over-control, don't gate it

**What we chose:** Remove `take_over_control`, `take_over_control_mode`, `detect_non_ha_changes`, `autoreset_control`, `only_once`, `adapt_only_on_bare_turn_on`. Strip the take-over-control state machine from `switch.py`.

**Why:** Manual-override semantics live at the scene/automation layer in CDiT's house. The take-over-control code threads through every adapter call in `switch.py` — making it conditional via a feature flag doesn't reduce complexity, just relocates it. Delete is the only honest option.

**Alternatives considered:**
- **Gate behind `enable_legacy_overrides` flag.** Rejected — preserves the code, defeats the simplification goal, accumulates "advanced settings" that nobody ever turns on.
- **Keep `intercept` and `multi_light_intercept`** — these *are* kept. They're transport behavior (hooking `light.turn_on` to merge adaptive values), not manual-override semantics. Different concern.

### Decision 9: Conditional visibility costs one submit cycle

**What we chose:** Fields with drivers (`send_split_delay` driven by `separate_turn_on_commands`; sun-time min/max pairs driven by whether the sun-entity is set) are conditionally included in the schema. When the driver changes, the user submits the form and HA re-renders with the new fields.

**Why:** HA's config flow can't re-render a single step dynamically when a field changes within that step. The supported path is to submit and let the next render reflect the new state. This costs one extra submit when a driver changes — accepted because driver changes are rare (you set `separate_turn_on_commands` once and forget).

**Alternatives considered:**
- **Always show all fields.** Rejected — the whole point is to hide noise.
- **Split into multiple steps when a driver changes.** Rejected — back to the wizard problem.

### Decision 10: Capability slug is `options-flow`, scoped tight

**What we chose:** This change defines one capability, `options-flow`, covering the integration's setup/reconfigure UI. Future changes get their own capabilities (`runtime-controls` for the number entities, `house-mode-binding` for the per-mode matrix).

**Why:** Keeps each spec testable and each requirement focused. A single `integration-configuration` umbrella would collect every config-related requirement across multiple changes — hard to read, hard to maintain.

### Decision 11: Sun curve math — max brightness lives strictly between the two entities

**What we chose:** Given `t_sunrise` and `t_sunset` from the entities, the brightness curve is:

```
       t < t_sunrise - 1800s :  brightness = min
       t in [t_sunrise - 1800s, t_sunrise + 1800s] : tanh ramp from min → max
       t in [t_sunrise + 1800s, t_sunset - 1800s]  : brightness = max
       t in [t_sunset - 1800s, t_sunset + 1800s]   : tanh ramp from max → min
       t > t_sunset + 1800s :   brightness = min
```

Same shape applied to color temperature, scaled between `min_color_temp` and `max_color_temp`.

**Why:** Symmetric, deterministic, easy to test. The user's pick of entity is the semantic anchor — pick `sun2_dawn` and full brightness arrives 30 min after civil dawn.

**Alternatives considered:**
- **Treat the entities as ramp midpoints.** Rejected — less intuitive; "when does the day start" should map to "when does max brightness start," not "when am I halfway to max."
- **Sun-elevation-style curve interpolated between events.** Rejected — adds astral-style math complexity without proportional benefit. The user picked entity-driven explicitly to avoid that.

### Decision 12: Auto-remove leftover sleep-mode switch entities on first load

**What we chose:** In `async_setup_entry`, scan the entity registry for any `switch.adaptive_lighting_sleep_mode_*` entries tied to this integration's config entry, remove them via `entity_registry.async_remove(entity_id)`, and log each removal at INFO level.

**Why:** Without this, upgrading users see orphan switches in Settings → Entities forever. The cleanup is bounded (only entities this integration created, identifiable by `unique_id` prefix), idempotent (runs every setup, no-op after the first), and small (~10 LOC). The log line gives auditability.

**Alternatives considered:**
- **Log + leave for manual cleanup.** Rejected — pollutes the device page; CDiT install has half a dozen AL configs, that's half a dozen orphans.
- **One-time cleanup script.** Rejected — extra step the user has to run.

### Decision 13: Pin `homeassistant` minimum version to 2025.1.0

**What we chose:** `manifest.json` declares `"homeassistant": "2025.1.0"` as the minimum supported HA version.

**Why:** Lets us use the latest stable selector API (`NumberSelector` with `BOX_OR_SLIDER` mode, `EntitySelector` with multi-domain filtering), `section()` helper with no rendering quirks, and `OptionsFlowWithReload` with all 2024.x bug fixes applied. Excludes pre-2025.1 installs intentionally — running HA more than ~6 months behind is its own problem.

**Alternatives considered:**
- **Pin 2024.10.** Rejected (initially recommended) — gives back the headroom for no clear benefit; user explicitly chose to go bolder.
- **No pin (`"homeassistant"` absent).** Rejected — silently runs on incompatible versions, fails confusingly when `section()` doesn't render right.

### Decision 14: Sun-entity selectors are strictly typed

**What we chose:** Both `sunrise_entity` and `sunset_entity` use `EntitySelector(EntitySelectorConfig(domain="sensor", device_class="timestamp"))`. Only sensors with `device_class: timestamp` show up in the picker.

**Why:** Covers all real use cases (built-in `sensor.sun_next_rising`, Sun2's `sensor.sun2_*`, any custom timestamp sensor) while preventing foot-guns — `input_datetime` entities don't auto-update for next sunrise, and picking one would silently produce wrong curves. Strict typing makes the wrong choice impossible.

**Alternatives considered:**
- **Loose typing (any datetime entity).** Rejected — invites the `input_datetime` foot-gun.
- **Strict + escape hatch constant.** Rejected — no real use case for loose mode; adding the knob now is YAGNI.

### Decision 15: `RAMP_HALF_WIDTH_SECONDS` lives in `const.py`

**What we chose:** Define `RAMP_HALF_WIDTH_SECONDS = 1800` in `const.py` near the other tuning defaults, with an inline comment explaining the 30-minute choice (eye-friendly circadian transition, robust across solstice-to-equinox sunrise drift).

**Why:** `const.py` is the canonical "knobs you might tweak" location in HA custom components. Discoverable to anyone reading the integration. The comment captures the rationale so future-CDiT doesn't relitigate.

**Alternatives considered:**
- **`__init__.py` near curve math.** Rejected — cohesive but harder to find when you want to tune.
- **Buried in `config_flow.py`.** Rejected — treats the constant as flow-private, but the curve math is the actual consumer.

## Risks / Trade-offs

- **[Sun2 isn't installed in HA]** → Defaults work fine — built-in `sensor.sun_next_*` is always present. Mitigation: README mentions Sun2 as a recommended-but-not-required HACS install.
- **[`sensor.sun_next_rising` flips to tomorrow's date the moment sunrise passes]** → The curve math must handle this: after `t_sunrise` has passed, read `sun.sun.last_changed`/historical state, or anchor today's curve from `t_sunset` and the implicit "today is between yesterday's sunset and tomorrow's sunrise." Mitigation: write a small helper `today_sun_events()` that returns `(today_sunrise_dt, today_sunset_dt)` based on current time vs entity values; specs/tasks will cover this explicitly.
- **[Removed sleep-mode switch entity lingers in HA's entity registry after upgrade]** → Old `switch.adaptive_lighting_sleep_mode_<name>` entries remain in `core.entity_registry` until manually deleted. Mitigation: document in CHANGELOG; provide a one-line `hass.config_entries.async_remove(...)` snippet for cleanup, or accept manual deletion via UI.
- **[Strict break inconveniences any non-CDiT installer]** → Anyone forking the CDiT fork to use upstream config entries will hit the break. Mitigation: explicit "this fork is opinionated; existing AL entries will not load" notice in README and on the fork's GitHub description.
- **[HA `section()` API is relatively young (added 2024.5)]** → Risk of styling/render quirks on older HA versions. Mitigation: bump `manifest.json` `homeassistant` minimum version to ≥ 2024.10 (when `OptionsFlowWithReload` also landed, so we're pinning both together).
- **[The synthetic tanh curve drifts from astronomical reality near solstices]** → Won't perfectly match astral-computed elevation. Mitigation: this is by design — the user picked Sun2 entities for accuracy at the *endpoints*; smooth dimming between them is what matters, not physical accuracy.
- **[`include_config_in_attributes` buried in Diagnostics could trip debug-time users]** → Mitigation: section is collapsed by default but not hidden; surfaces on expand. Mention in README's "Debugging" subsection.

## Migration Plan

This change is delivered as a single PR on the fork's `main` branch. No phased rollout; CDiT-dev is the only consumer.

1. Land the PR.
2. Tag the release (`v2.0.0-cdit.1`).
3. On the running HA install:
   - Snapshot current AL config (Settings → Integrations → Adaptive Lighting → ⋮ → Download Diagnostics, or just screenshot the options dialog).
   - Update via HACS or manual copy of `custom_components/adaptive_lighting/`.
   - Restart HA.
   - Old config entry shows as "failed to load."
   - Delete the failed entry.
   - Recreate via Settings → Add Integration → Adaptive Lighting, copying the snapshot's values into the new section layout.
4. Manually delete leftover `switch.adaptive_lighting_sleep_mode_<name>` entries via Settings → Devices → Entities (filter by integration, sort by "missing").

**Rollback:** `git revert` the PR merge commit. Old upstream config entries do *not* auto-recover — you'd reinstall upstream AL from HACS and re-create the entry there.

## Open Questions

None — all resolved and folded into Decisions 12–15.