# Alarm-driven circadian sleep lifecycle

Home Assistant sleep routines should be driven by Edmund's next Eight Sleep smart alarm when Edmund is home, rather than by a fixed bedtime or purely manual scenes, because the goal is to support a consistent circadian rhythm around the actual next wake window. The Eight Sleep alarm represents the **latest** acceptable wake time for a smart-alarm window; the scheduler targets the **start** of that window by subtracting 30 minutes, then targets six 90-minute sleep cycles ending at that ideal wake time.

The canonical lifecycle is **Winding Down → Get Ready for Bed → Good Night → Sleep**: a five-minute homeostasis check runs between 8 PM and midnight, applies each phase once per alarm schedule, skips only the soft Winding Down phase when already late, and preserves the 10-minute get-ready and 15-minute fall-asleep buffers once the active sequence starts. For example, a 7:45 AM Eight Sleep smart alarm yields a 7:15 AM ideal wake target, 10:15 PM sleep target, 10:00 PM Good Night target, 9:50 PM Get Ready for Bed target, and 9:15 PM Winding Down target.

Consequences: **Get Ready for Bed**, **Good Night**, and **Good Morning** are the only HomeKit-facing manual routines; **Winding Down** and **Sleep** stay internal automation phases. The old **In Bed** / **Ignite** path and the voice-facing Sleep webhook are retired to avoid ambiguous voice routing. Phase helpers track which phases have run for the current alarm schedule, manual Get Ready for Bed / Good Night update those helpers, and Good Morning resets the schedule state. Notifications happen only at Get Ready for Bed and Good Night, initially to Edmund's phone when home; Monica notification/fallback alarm driving remains future work.

The earlier iPhone-alarm source is not currently viable on iOS because Home Assistant Companion does not expose a passive `sensor.<iphone>_next_alarm` entity like Android does. The iPhone → 8Sleep sync automation remains declaratively disabled until an explicit source of truth exists, such as a Home Assistant helper or iOS Shortcut bridge. To reduce Eight Sleep integration lag during the bedtime decision window without polling all day, Home Assistant refreshes the Eight Sleep next-alarm entity every two minutes from 7:30 PM to 11:00 PM while Edmund is home.
