Document dynamic audio and add a schedule response example

docs/ai/api.md

@@ -107,10 +107,12 @@ Authenticates with the paired `email` + `licenseKey` query parameters and
 validates only that the key belongs to the account (not that the license is
 active/entitled). Returns the user's Blocks with start/end times and the IDs of
 the selected Proclamations (content is fetched separately via
-`/api/v2/proclamations`). Overnight blocks (end clock time before start) are
+`/api/v2/proclamations`). Each block also carries `dynamicAudio`; when true, the
-supported and flagged with `overnight: true` plus a wrapping `durationMinutes`.
+kiosk enables dynamic audio for the block's duration, overriding any audio
-Rate limited to 10 requests per minute per IP. Failure messages follow the
+selections made on the device while the block is active. Overnight blocks (end
-existing v2 shape:
+clock time before start) are supported and flagged with `overnight: true` plus a
+wrapping `durationMinutes`. Rate limited to 10 requests per minute per IP.
+Failure messages follow the existing v2 shape:
 `not-authorized` or `this key doesn't appear to belong to you`.
 
 ---

docs/openapi.yaml

@@ -247,8 +247,11 @@ paths:
         Returns every Block with its start/end times and the ordered list of
         selected Proclamation IDs. Overnight blocks (an end clock time before
         the start) are supported and flagged with `overnight: true` and a
-        wrapping `durationMinutes`. Proclamation content is not included; the
+        wrapping `durationMinutes`. Each block also carries `dynamicAudio`;
-        kiosk fetches it separately via `/api/v2/proclamations`.
+        when true, the kiosk enables dynamic audio for the block's duration,
+        overriding any audio selections made on the device. Proclamation
+        content is not included; the kiosk fetches it separately via
+        `/api/v2/proclamations`.
       operationId: getSchedule
       parameters:
         - in: query
@@ -272,6 +275,20 @@ paths:
             application/json:
               schema:
                 $ref: '#/components/schemas/ScheduleResponse'
+              example:
+                email: jane@example.com
+                blocks:
+                  - id: 3f1c2b7a-9d4e-4c8a-b2f6-1a2b3c4d5e6f
+                    startTime: '21:00'
+                    startMinutes: 1260
+                    endTime: '09:00'
+                    endMinutes: 540
+                    overnight: true
+                    durationMinutes: 720
+                    dynamicAudio: true
+                    proclamationIds:
+                      - b40fdcb9-703c-420e-af32-a081964c6f08
+                      - 7c9e1a2b-3d4e-5f60-8a9b-0c1d2e3f4a5b
         '400':
           description: |
             Missing/invalid parameters, unknown key or user, or the key does not