From 7080ddea44719df7366269d801a64d1c59cee595 Mon Sep 17 00:00:00 2001
From: Antiheld86 <4201585+Antiheld86@users.noreply.github.com>
Date: Thu, 3 Sep 2026 10:30:03 +0200
Subject: [PATCH] docs(api): regenerate the spec for unavailableWidgetIds

---
 docs/api/openapi.yaml | 273 +++++++++++++++++++++++++++++++++++++++---
 1 file changed, 254 insertions(+), 19 deletions(-)

diff --git a/docs/api/openapi.yaml b/docs/api/openapi.yaml
index 511396968..106b98de1 100644
--- a/docs/api/openapi.yaml
+++ b/docs/api/openapi.yaml
@@ -18061,8 +18061,9 @@ paths:
       tags:
         - Dashboard
       summary: Read the calling user's dashboard widget layout
-      description: Returns the resolved effective layout (defaults merged in if the user has not customised it) plus the
-        optimistic-concurrency `updatedAt` token.
+      description: Returns the resolved effective layout (defaults merged in if the user has not customised it), the
+        optimistic-concurrency `updatedAt` token, and `unavailableWidgetIds` — any widget whose toggle cannot do
+        anything for this account, which a settings UI should not offer.
       responses:
         "200":
           description: The resolved layout (custom or default) plus its token.
@@ -65069,6 +65070,257 @@ components:
         - mood
         - bmi
     DashboardLayout:
+      type: object
+      properties:
+        data:
+          $ref: "#/components/schemas/DashboardLayoutReadResult"
+        error:
+          type: "null"
+        meta:
+          type: object
+          properties:
+            requestId:
+              type: string
+          additionalProperties: false
+      required:
+        - data
+        - error
+      additionalProperties: false
+    DashboardLayoutReadResult:
+      type: object
+      properties:
+        version:
+          type: number
+          const: 1
+        widgets:
+          minItems: 1
+          maxItems: 50
+          type: array
+          items:
+            type: object
+            properties:
+              id:
+                type: string
+                enum:
+                  - weight
+                  - bp
+                  - pulse
+                  - bodyFat
+                  - mood
+                  - medications
+                  - sleep
+                  - steps
+                  - glucose
+                  - totalBodyWater
+                  - boneMass
+                  - muscleMass
+                  - bpInTarget
+                  - oxygenSaturation
+                  - hrv
+                  - respiratoryRate
+                  - achievements
+                  - vo2Max
+                  - recentWorkouts
+                  - cardioRecovery
+                  - sixMinuteWalk
+                  - stairAscentSpeed
+                  - stairDescentSpeed
+                  - breathingDisturbances
+                  - wristTemperature
+                  - falls
+                  - walkingSteadiness
+                  - vorsorge
+                  - waterIntake
+                  - restingHeartRate
+                  - walkingSpeed
+                  - walkingAsymmetry
+                  - walkingStepLength
+                  - bmi
+                  - bodyTemperature
+                  - walkingDoubleSupport
+                  - audioExposureEnvironment
+                  - audioExposureHeadphone
+                  - gripStrength
+                  - painNRS
+                  - waistCircumference
+                  - waistToHeight
+              visible:
+                type: boolean
+              tileVisible:
+                type: boolean
+              order:
+                type: integer
+                minimum: 0
+                maximum: 99
+            required:
+              - id
+              - visible
+              - order
+            additionalProperties: false
+        comparisonBaseline:
+          type: string
+          enum:
+            - none
+            - lastMonth
+            - lastYear
+        chartOverlayPrefs:
+          type: object
+          propertyNames:
+            type: string
+            enum:
+              - bp
+              - weight
+              - bmi
+              - pulse
+              - bodyFat
+              - mood
+              - medications
+              - sleep
+              - steps
+              - vo2Max
+              - hrv
+              - restingHr
+              - oxygenSaturation
+              - bodyTemperature
+              - activeEnergy
+              - bloodGlucose
+              - totalBodyWater
+              - boneMass
+              - flightsClimbed
+              - walkingRunningDistance
+              - fatFreeMass
+              - fatMass
+              - muscleMass
+              - skinTemperature
+              - pulseWaveVelocity
+              - vascularAge
+              - visceralFat
+              - audioExposureEnv
+              - audioExposureHeadphone
+              - timeInDaylight
+              - walkingSteadiness
+              - audioExposureEvent
+              - respiratoryRate
+              - leanBodyMass
+              - walkingHeartRateAverage
+              - walkingAsymmetry
+              - walkingDoubleSupport
+              - walkingStepLength
+              - walkingSpeed
+              - cardioRecovery
+              - wristTemperature
+              - fallCount
+              - sixMinuteWalkDistance
+              - stairAscentSpeed
+              - stairDescentSpeed
+              - breathingDisturbances
+              - ansCharge
+              - dayStrain
+              - workoutStrain
+              - cardioLoad
+              - averageHeartRate
+              - maxHeartRate
+              - energyExpenditureKj
+              - gripStrength
+              - painNrs
+              - waistCircumference
+              - waistToHeight
+          additionalProperties:
+            type: object
+            properties:
+              showTrendIndicator:
+                type: boolean
+              showTrendArrow:
+                type: boolean
+              showTargetRange:
+                type: boolean
+              comparisonBaseline:
+                type: string
+                enum:
+                  - none
+                  - lastMonth
+                  - lastYear
+              rangePoints:
+                anyOf:
+                  - type: number
+                    const: 0
+                  - type: number
+                    const: 7
+                  - type: number
+                    const: 30
+                  - type: number
+                    const: 90
+            required:
+              - showTrendIndicator
+              - showTrendArrow
+              - showTargetRange
+            additionalProperties: false
+        selectedScoreRings:
+          maxItems: 3
+          type: array
+          items:
+            type: string
+            enum:
+              - READINESS
+              - RECOVERY_SCORE
+              - SLEEP_SCORE
+              - MED_COMPLIANCE
+        heroRingOrder:
+          maxItems: 4
+          type: array
+          items:
+            type: string
+            enum:
+              - HEALTH_SCORE
+              - READINESS
+              - RECOVERY_SCORE
+              - SLEEP_SCORE
+              - MED_COMPLIANCE
+        enabledHeroItemKinds:
+          description: Today-highlight item kinds in catalogue order. Missing means every current kind is enabled; an empty array
+            disables all kinds.
+          maxItems: 9
+          type: array
+          items:
+            type: string
+            enum:
+              - coach_checkin
+              - dose_window
+              - preventive_care
+              - sync_issue
+              - milestone
+              - ecg_new_recording
+              - tension_window
+              - same_time_baseline
+              - upcoming_visit
+        hero:
+          description: 'Primary hero-card content on the dashboard: "score" (the health-score read, default) or "reminders" (the
+            Today-highlight rail promoted into the hero slot). Missing resolves to "score"; the stored default is
+            omitted from responses.'
+          type: string
+          enum:
+            - score
+            - reminders
+        updatedAt:
+          description: "Optimistic-concurrency token: the stored row's `updatedAt` at read/write time. Echo it back as
+            `baseUpdatedAt` on the next write. Opaque."
+          type: string
+          format: date-time
+          pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
+        unavailableWidgetIds:
+          description: "Widget ids whose toggle cannot do anything for this account, and which a settings UI should therefore not
+            offer — a switch over a tile that can never paint. Resolved per request from the caller's enabled modules
+            and the data they actually have: `hrv` appears here when the Recovery module is off and the account has no
+            SDNN series, because its only remaining HRV source (nightly RMSSD) is recovery-owned and withheld. Absent
+            when nothing is unavailable. Additive: a client that ignores it behaves exactly as before."
+          type: array
+          items:
+            type: string
+      required:
+        - version
+      additionalProperties: false
+      description: Resolved dashboard layout, its `updatedAt` token, and any widget toggles that are unavailable for this account.
+    DashboardLayoutSaved:
       type: object
       properties:
         data:
@@ -65310,23 +65562,6 @@ components:
         - version
       additionalProperties: false
       description: Resolved dashboard layout plus the optimistic-concurrency `updatedAt` token.
-    DashboardLayoutSaved:
-      type: object
-      properties:
-        data:
-          $ref: "#/components/schemas/DashboardLayoutResult"
-        error:
-          type: "null"
-        meta:
-          type: object
-          properties:
-            requestId:
-              type: string
-          additionalProperties: false
-      required:
-        - data
-        - error
-      additionalProperties: false
     DashboardLayoutReset:
       type: object
       properties: