docs(api): note that shuffle_context before play starts on a random track

The HTTP API did not document how to start a context shuffled (on a random
first track). Document it on /player/play and /player/shuffle_context:
enabling shuffle_context before /player/play starts playback on a random
track, while enabling it after play only reshuffles the upcoming queue and
keeps the current (first) track.

Verified at runtime: three consecutive shuffle_context-then-play calls each
started on a different track.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: 2 people

api-spec.yml

@@ -127,7 +127,12 @@ paths:
           description: Successful response
   /player/play:
     post:
-      description: Starts playing new content
+      description: >-
+        Starts playing new content. To start a context shuffled (on a random
+        track), enable shuffle first via /player/shuffle_context and then call
+        this. Calling /player/shuffle_context after play only shuffles the
+        upcoming queue and keeps the current (first) track, so play alone (or
+        shuffle after play) always begins on the context's first track.
       requestBody:
         $ref: '#/components/schemas/play'
       responses:
@@ -268,7 +273,10 @@ paths:
           description: Successful response
   /player/shuffle_context:
     post:
-      description: Toggle shuffling context
+      description: >-
+        Toggle shuffling the context. Enabling it BEFORE /player/play makes
+        playback start on a random track; enabling it after play only reshuffles
+        the upcoming queue and keeps the current (first) track.
       requestBody:
         content:
           application/json: