From a6a106f763cdd2fa62d7698c1228a5dcb67aecc9 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Marc-Andr=C3=A9=20Bombeck?= <mbombeck@gmail.com>
Date: Tue, 20 Oct 2026 05:14:07 +0200
Subject: [PATCH] docs(api): regenerate the OpenAPI contract

---
 docs/api/openapi.yaml | 32 ++++++++++++++++++++++----------
 1 file changed, 22 insertions(+), 10 deletions(-)

diff --git a/docs/api/openapi.yaml b/docs/api/openapi.yaml
index eabd0e3e3..96b25bd4f 100644
--- a/docs/api/openapi.yaml
+++ b/docs/api/openapi.yaml
@@ -4203,10 +4203,13 @@ paths:
 
 
         With `groupBy=day` on a cumulative type the rows are one sum per local day, and `limit` / `offset` page over
-        those days; every returned day is complete. `type=SLEEP_DURATION` returns one row per night, paged the same way
-        over nights. On both, `meta.total` counts the days or nights in the filtered window. A day-sum page takes
-        `limit` as asked (up to the list's 5000); a sleep page holds at most 1000 nights, and `meta.limit` echoes the
-        value applied.
+        those days; every returned day is complete, which is why `valueMin` / `valueMax` (a filter on single readings)
+        are refused with 422 beside `groupBy=day`. `type=SLEEP_DURATION` returns one row per night, paged the same way
+        over nights; every night of the page has a row, and a day whose only sleep is daytime naps carries `value` 0
+        with its naps in `napCount` / `napAsleepMinutes`. Its `dayKey` is the same day `/api/sleep/night?date=` answers
+        for. On both, `meta.total` counts the days or nights in the filtered window. A day-sum page takes `limit` as
+        asked (up to the list's 5000); a sleep page holds at most 1000 nights, and `meta.limit` echoes the value
+        applied.
       parameters:
         - in: query
           name: type
@@ -4727,8 +4730,8 @@ paths:
         source's stage segments (each with an absolute start/end), the per-stage breakdown, asleep/in-bed/awake totals,
         the mid-sleep awakenings count, and same-wake-day naps surfaced separately. Session-clustered, keyed by the
         local wake day, collapsed to one source via the sleep priority ladder so two sources never overlay. `date`
-        omitted returns the most recent night. A read-only view over existing per-stage SLEEP_DURATION rows — no schema,
-        no new measurement type."
+        omitted returns the most recent night holding sleep, however old. Any past date is answered, with no window cut.
+        A read-only view over existing per-stage SLEEP_DURATION rows — no schema, no new measurement type."
       parameters:
         - in: query
           name: date
@@ -47890,7 +47893,9 @@ components:
         - naps
       additionalProperties: false
       description: "One reconstructed sleep night: the main session's hypnogram segments + breakdown, plus same-wake-day naps
-        surfaced separately."
+        surfaced separately. A session is a nap when it holds under three hours asleep centred between 10:00 and 20:00
+        local time; the main session is the longest session that is not a nap. A day whose only sleep is naps has `main:
+        null` and its naps."
     SleepRhythmResponse:
       type: object
       properties:
@@ -88254,9 +88259,9 @@ components:
                 type: number
                 description: Effective weight after redistributing missing sub-scores.
               gap:
-                description: "Only on a null `consistency` / `timing`: why it is withheld. `few_nights` — fewer than three nights in the
-                  window have a main sleep on the clock (count in `rhythmNights`); `no_main_sleep` — the latest day had
-                  only a daytime nap. Absent otherwise."
+                description: "Only on a null `consistency` / `timing`: why it is withheld. `few_nights` — fewer than `rhythmMinNights`
+                  nights in the window have a main sleep on the clock (count in `rhythmNights`); `no_main_sleep` — the
+                  latest day had only a daytime nap. Absent otherwise."
                 type: string
                 enum:
                   - few_nights
@@ -88278,6 +88283,12 @@ components:
           maximum: 9007199254740991
           description: Nights in the window with a main sleep placed on the clock — what consistency and timing are computed from.
             A daytime nap is not one; a short night is.
+        rhythmMinNights:
+          type: integer
+          minimum: -9007199254740991
+          maximum: 9007199254740991
+          description: 'How many `rhythmNights` consistency and timing need before they are scored; below it they carry `gap:
+            "few_nights"`.'
         series:
           type: array
           items:
@@ -88292,6 +88303,7 @@ components:
         - subScores
         - windowNights
         - rhythmNights
+        - rhythmMinNights
         - series
       additionalProperties: false
   parameters: