docs(ApiReference): align V2 command reference with actual firmware

playback namespace: replaced stale root-level 'playback' command with
proper playback.play / playback.stop split. playback.play now documents
all firmware attributes: pid, uid, name, url, speed, note_assignments,
mode (single/timed/interval/infinite), duration, pause_duration,
total_duration.

clock namespace: filled in previously empty contents for set_timings
(pulse_duration, pause_duration), set_alerts (alert_type, alert_interval,
hour/half/quarter_bell outputs), set_backlight (backlight, backlight_output,
backlight_on/off), set_silence (daytime and nighttime windows with HH:MM
strings). Fixed clock.get_timezone returns (ntp_server field, removed
non-existent timezone_name). Added exact returns shape for clock.get_face
and full field list for clock.get_config matching handler output.

system namespace: added exact returns shapes for system.status
(player_status, time_elapsed_ms, projected_run_time, strike_counters)
and system.health (critical_count, warning_count, firmware_stable,
subsystems array).

Legacy map: updated playback row to show play→playback.play and
stop→playback.stop. UART whitelist updated to playback.play/stop.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

frontend/src/pages/engineering/developer/ApiReferencePage.jsx

@@ -23,7 +23,7 @@ const TRANSPORTS = [
   { transport: 'UDP', address: 'Port 32101', direction: 'Discovery', notes: 'Passive — device announces itself' },
 ]
 
-const UART_WHITELIST = ['ping', 'playback', 'clock.pause', 'clock.resume', 'system.get_time']
+const UART_WHITELIST = ['ping', 'playback.play', 'playback.stop', 'clock.pause', 'clock.resume', 'system.get_time']
 
 const NAMESPACES = [
   {
@@ -33,7 +33,44 @@ const NAMESPACES = [
     commands: [
       { cmd: 'ping', handler: 'SystemHandler', transports: ['All'], description: 'Connectivity check. No contents required.', contents: null, returns: '{ "status": "SUCCESS", "type": "pong" }', example: '{ "v": 2, "cmd": "ping" }', warning: null },
       { cmd: 'identify', handler: 'SystemHandler', transports: ['WebSocket'], description: 'Register client type with the device. Must be sent immediately after connecting on WebSocket or targeted responses will not be received.', contents: [{ field: 'device_type', type: 'string', required: true, notes: '"master" (app/console) or "secondary" (slave board)' }], returns: null, example: '{ "v": 2, "cmd": "identify", "contents": { "device_type": "master" } }', warning: null },
-      { cmd: 'playback', handler: 'PlaybackHandler', transports: ['All'], description: 'Control melody playback. The action field is always required.', contents: [{ field: 'action', type: 'string', required: true, notes: '"play" | "stop" | "pause" | "unpause"' }, { field: 'melody_uid', type: 'string', required: false, notes: 'Required when action is play' }], returns: null, example: '{ "v": 2, "cmd": "playback", "contents": { "action": "play", "melody_uid": "ABC123" } }\n{ "v": 2, "cmd": "playback", "contents": { "action": "stop" } }', warning: null },
+    ],
+  },
+  {
+    id: 'playback',
+    label: 'playback',
+    description: 'Melody playback control. Handler: PlaybackHandler.',
+    commands: [
+      {
+        cmd: 'playback.play',
+        handler: 'PlaybackHandler',
+        transports: ['All'],
+        description: 'Load and play a melody. All attributes except pid are optional — omitted values carry over from the previous command. Rejected if playback is already active (send playback.stop first).',
+        contents: [
+          { field: 'pid', type: 'string', required: true, notes: 'Melody UID — matched against built-in library first, then /melodies/ on SD card.' },
+          { field: 'uid', type: 'string', required: false, notes: 'Alias for pid. Use pid in new code.' },
+          { field: 'name', type: 'string', required: false, notes: 'Human-readable label, used in status broadcasts.' },
+          { field: 'url', type: 'string', required: false, notes: 'Download URL. Required only if the melody is not yet on the SD card and is not a built-in.' },
+          { field: 'speed', type: 'int', required: false, notes: 'Inter-note delay in ms. Default 300. Controls overall tempo.' },
+          { field: 'note_assignments', type: 'int[]', required: false, notes: 'Array of up to 16 relay output indices, mapping melody note 1–16 → physical output. E.g. [1,2,3,4,5,6,0,0,…]' },
+          { field: 'mode', type: 'string', required: false, notes: '"single" (default) — play one loop and stop. "timed" — loop for duration ms. "interval" — timed segments with pauses between. "infinite" — loop until explicitly stopped.' },
+          { field: 'duration', type: 'int', required: false, notes: 'Segment duration in ms. Required when mode is "timed" or "interval".' },
+          { field: 'pause_duration', type: 'int', required: false, notes: 'Pause between segments in ms. Used only with mode "interval".' },
+          { field: 'total_duration', type: 'int', required: false, notes: 'Total playback time in ms. Used only with mode "interval" to cap the overall run.' },
+        ],
+        returns: null,
+        example: '// Single play\n{ "v": 2, "cmd": "playback.play", "contents": { "pid": "westminster", "speed": 400, "mode": "single" } }\n\n// Timed loop for 2 minutes\n{ "v": 2, "cmd": "playback.play", "contents": { "pid": "ABC123", "mode": "timed", "duration": 120000 } }\n\n// Interval: play 15 s, pause 5 s, repeat for 3 min total\n{ "v": 2, "cmd": "playback.play", "contents": { "pid": "ABC123", "mode": "interval", "duration": 15000, "pause_duration": 5000, "total_duration": 180000 } }',
+        warning: null,
+      },
+      {
+        cmd: 'playback.stop',
+        handler: 'PlaybackHandler',
+        transports: ['All'],
+        description: 'Stop playback immediately. Safe to call even when player is already stopped.',
+        contents: null,
+        returns: null,
+        example: '{ "v": 2, "cmd": "playback.stop" }',
+        warning: null,
+      },
     ],
   },
   {
@@ -53,21 +90,21 @@ const NAMESPACES = [
     description: 'Clock strike configuration, RTC time, face position, timezone, and silence periods. Handler: ClockHandler.',
     commands: [
       { cmd: 'clock.set_outputs', handler: 'ClockHandler', transports: ['All'], description: 'Set which relay outputs the clock strikes use. Partial updates accepted.', contents: [{ field: 'c1', type: 'int', required: false, notes: 'Relay output for the first clock channel' }, { field: 'c2', type: 'int', required: false, notes: 'Relay output for the second clock channel. At least one of c1/c2 required.' }], returns: null, example: '{ "v": 2, "cmd": "clock.set_outputs", "contents": { "c1": 4, "c2": 5 } }', warning: null },
-      { cmd: 'clock.set_timings', handler: 'ClockHandler', transports: ['All'], description: 'Set clock strike timing configuration. Partial updates accepted.', contents: null, returns: null, example: '{ "v": 2, "cmd": "clock.set_timings", "contents": { ... } }', warning: null },
+      { cmd: 'clock.set_timings', handler: 'ClockHandler', transports: ['All'], description: 'Set clock strike timing configuration. At least one field required.', contents: [{ field: 'pulse_duration', type: 'int', required: false, notes: 'Duration of each clock output pulse in ms. Typical: 80–150 ms.' }, { field: 'pause_duration', type: 'int', required: false, notes: 'Pause between consecutive pulses (e.g. hour chimes) in ms.' }], returns: null, example: '{ "v": 2, "cmd": "clock.set_timings", "contents": { "pulse_duration": 100, "pause_duration": 500 } }', warning: null },
-      { cmd: 'clock.set_alerts', handler: 'ClockHandler', transports: ['All'], description: 'Configure hourly/quarter alert behavior. Partial updates accepted.', contents: null, returns: null, example: '{ "v": 2, "cmd": "clock.set_alerts", "contents": { ... } }', warning: null },
+      { cmd: 'clock.set_alerts', handler: 'ClockHandler', transports: ['All'], description: 'Configure hourly/quarter alert behavior. Partial updates accepted — omitted fields are unchanged.', contents: [{ field: 'alert_type', type: 'string', required: false, notes: '"none" | "hour" | "quarter" | "half" — which strikes trigger the alert.' }, { field: 'alert_interval', type: 'int', required: false, notes: 'Number of times the alert bell rings per trigger.' }, { field: 'hour_bell', type: 'int', required: false, notes: 'Output index for the hour bell. 255 = disabled.' }, { field: 'half_bell', type: 'int', required: false, notes: 'Output index for the half-hour bell. 255 = disabled.' }, { field: 'quarter_bell', type: 'int', required: false, notes: 'Output index for the quarter-hour bell. 255 = disabled.' }], returns: null, example: '{ "v": 2, "cmd": "clock.set_alerts", "contents": { "alert_type": "hour", "alert_interval": 1, "hour_bell": 5 } }', warning: null },
-      { cmd: 'clock.set_backlight', handler: 'ClockHandler', transports: ['All'], description: 'Configure LCD backlight behavior. Partial updates accepted.', contents: null, returns: null, example: '{ "v": 2, "cmd": "clock.set_backlight", "contents": { ... } }', warning: null },
+      { cmd: 'clock.set_backlight', handler: 'ClockHandler', transports: ['All'], description: 'Configure LCD backlight behavior. Partial updates accepted.', contents: [{ field: 'backlight', type: 'bool', required: false, notes: 'Enable or disable automatic backlight control.' }, { field: 'backlight_output', type: 'int', required: false, notes: 'Relay output index used for the backlight.' }, { field: 'backlight_on', type: 'string', required: false, notes: 'Time to turn backlight on, format "HH:MM".' }, { field: 'backlight_off', type: 'string', required: false, notes: 'Time to turn backlight off, format "HH:MM".' }], returns: null, example: '{ "v": 2, "cmd": "clock.set_backlight", "contents": { "backlight": true, "backlight_output": 6, "backlight_on": "07:00", "backlight_off": "22:00" } }', warning: null },
-      { cmd: 'clock.set_silence', handler: 'ClockHandler', transports: ['All'], description: 'Configure silence period (quiet hours). Partial updates accepted.', contents: null, returns: null, example: '{ "v": 2, "cmd": "clock.set_silence", "contents": { ... } }', warning: null },
+      { cmd: 'clock.set_silence', handler: 'ClockHandler', transports: ['All'], description: 'Configure silence periods (quiet hours). Daytime and nighttime windows are independent. Partial updates accepted.', contents: [{ field: 'daytime_silence', type: 'bool', required: false, notes: 'Enable daytime silence window.' }, { field: 'daytime_on', type: 'string', required: false, notes: 'Start of daytime silence, format "HH:MM".' }, { field: 'daytime_off', type: 'string', required: false, notes: 'End of daytime silence, format "HH:MM".' }, { field: 'night_silence', type: 'bool', required: false, notes: 'Enable nighttime silence window.' }, { field: 'night_on', type: 'string', required: false, notes: 'Start of nighttime silence, format "HH:MM".' }, { field: 'night_off', type: 'string', required: false, notes: 'End of nighttime silence, format "HH:MM".' }], returns: null, example: '{ "v": 2, "cmd": "clock.set_silence", "contents": { "night_silence": true, "night_on": "22:00", "night_off": "07:00" } }', warning: null },
       { cmd: 'clock.set_time', handler: 'ClockHandler', transports: ['All'], description: 'Set the RTC time.', contents: [{ field: 'timestamp', type: 'int', required: true, notes: 'Unix epoch timestamp' }, { field: 'timezone_offset', type: 'int', required: false, notes: 'Offset in seconds (e.g. 7200 for UTC+2)' }, { field: 'dst_offset', type: 'int', required: false, notes: 'DST offset in seconds' }], returns: null, example: '{\n  "v": 2,\n  "cmd": "clock.set_time",\n  "contents": { "timestamp": 1740000000, "timezone_offset": 7200 }\n}', warning: null },
       { cmd: 'clock.set_face', handler: 'ClockHandler', transports: ['All'], description: 'Set the physical analog clock face position.', contents: [{ field: 'hour', type: 'int', required: true, notes: 'Hour hand position (0–11)' }, { field: 'minute', type: 'int', required: true, notes: 'Minute hand position (0–59)' }], returns: null, example: '{ "v": 2, "cmd": "clock.set_face", "contents": { "hour": 10, "minute": 10 } }', warning: null },
       { cmd: 'clock.set_timezone', handler: 'ClockHandler', transports: ['All'], description: 'Set timezone independently of RTC time.', contents: [{ field: 'gmt_offset_sec', type: 'int', required: true, notes: 'GMT offset in seconds (e.g. 7200 for UTC+2)' }, { field: 'dst_offset_sec', type: 'int', required: false, notes: 'DST offset in seconds' }, { field: 'timezone_name', type: 'string', required: false, notes: 'IANA timezone name, e.g. "Europe/Athens"' }], returns: null, example: '{\n  "v": 2,\n  "cmd": "clock.set_timezone",\n  "contents": { "gmt_offset_sec": 7200, "dst_offset_sec": 3600, "timezone_name": "Europe/Athens" }\n}', warning: null },
-      { cmd: 'clock.get_timezone', handler: 'ClockHandler', transports: ['All'], description: 'Read current timezone settings.', contents: null, returns: '{ "gmt_offset_sec": 7200, "dst_offset_sec": 3600, "timezone_name": "..." }', example: '{ "v": 2, "cmd": "clock.get_timezone" }', warning: null },
+      { cmd: 'clock.get_timezone', handler: 'ClockHandler', transports: ['All'], description: 'Read current timezone settings.', contents: null, returns: '{ "gmt_offset_sec": 7200, "dst_offset_sec": 3600, "ntp_server": "pool.ntp.org" }', example: '{ "v": 2, "cmd": "clock.get_timezone" }', warning: null },
       { cmd: 'clock.sync_ntp', handler: 'ClockHandler', transports: ['All'], description: 'Force an immediate NTP time sync.', contents: null, returns: null, example: '{ "v": 2, "cmd": "clock.sync_ntp" }', warning: null },
       { cmd: 'clock.enable', handler: 'ClockHandler', transports: ['All'], description: 'Enable clock strike output.', contents: null, returns: null, example: '{ "v": 2, "cmd": "clock.enable" }', warning: null },
       { cmd: 'clock.disable', handler: 'ClockHandler', transports: ['All'], description: 'Disable clock strike output.', contents: null, returns: null, example: '{ "v": 2, "cmd": "clock.disable" }', warning: null },
       { cmd: 'clock.pause', handler: 'ClockHandler', transports: ['All'], description: 'Pause clock updates.', contents: null, returns: null, example: '{ "v": 2, "cmd": "clock.pause" }', warning: null },
       { cmd: 'clock.resume', handler: 'ClockHandler', transports: ['All'], description: 'Resume clock updates.', contents: null, returns: null, example: '{ "v": 2, "cmd": "clock.resume" }', warning: null },
-      { cmd: 'clock.get_face', handler: 'ClockHandler', transports: ['All'], description: 'Read current analog clock face position.', contents: null, returns: '{ "clock_hour", "clock_minute", "last_sync_time", "next_output_is_c1" }', example: '{ "v": 2, "cmd": "clock.get_face" }', warning: null },
+      { cmd: 'clock.get_face', handler: 'ClockHandler', transports: ['All'], description: 'Read current analog clock face position.', contents: null, returns: '{ "clock_hour": 10, "clock_minute": 30, "last_sync_time": 1740000000, "next_output_is_c1": true }', example: '{ "v": 2, "cmd": "clock.get_face" }', warning: null },
-      { cmd: 'clock.get_config', handler: 'ClockHandler', transports: ['All'], description: 'Read full clock configuration — outputs, timings, alerts, backlight, silence, enabled state.', contents: null, returns: null, example: '{ "v": 2, "cmd": "clock.get_config" }', warning: null },
+      { cmd: 'clock.get_config', handler: 'ClockHandler', transports: ['All'], description: 'Read full clock configuration — outputs, timings, alerts, backlight, silence, enabled state.', contents: null, returns: '{ "enabled", "c1output", "c2output", "pulse_duration", "pause_duration", "physical_hour", "physical_minute", "next_is_c1", "last_sync_time", "alert_type", "alert_interval", "hour_bell", "half_bell", "quarter_bell", "backlight", "backlight_output", "backlight_on", "backlight_off", "daytime_silence", "daytime_on", "daytime_off", "night_silence", "night_on", "night_off" }', example: '{ "v": 2, "cmd": "clock.get_config" }', warning: null },
     ],
   },
   {
@@ -75,11 +112,11 @@ const NAMESPACES = [
     label: 'system',
     description: 'Device status, settings, health, and control. Handler: SystemHandler.',
     commands: [
-      { cmd: 'system.status', handler: 'SystemHandler', transports: ['All'], description: 'Get current device status: player state, strike counters, projected run time.', contents: null, returns: null, example: '{ "v": 2, "cmd": "system.status" }', warning: null },
+      { cmd: 'system.status', handler: 'SystemHandler', transports: ['All'], description: 'Get current device status: player state, strike counters, projected run time.', contents: null, returns: '{ "player_status": "STOPPED|PLAYING|PAUSED|STOPPING", "time_elapsed_ms": 0, "projected_run_time": 0, "strike_counters": { "0": 1234, ... } }', example: '{ "v": 2, "cmd": "system.status" }', warning: null },
       { cmd: 'system.get_time', handler: 'SystemHandler', transports: ['All'], description: 'Get current RTC time.', contents: null, returns: '{ "local_timestamp", "utc_timestamp", "year", "month", "day", "hour", "minute", "second", "rtc_available" }', example: '{ "v": 2, "cmd": "system.get_time" }', warning: null },
       { cmd: 'system.get_settings', handler: 'SystemHandler', transports: ['All'], description: 'Get full ConfigManager JSON dump (all saved settings).', contents: null, returns: null, example: '{ "v": 2, "cmd": "system.get_settings" }', warning: null },
       { cmd: 'system.get_device_info', handler: 'SystemHandler', transports: ['All'], description: 'Get device identity and runtime stats.', contents: null, returns: '{ "uid", "hw_type", "hw_version", "fw_version", "uptime_ms", "free_heap", "min_free_heap" }', example: '{ "v": 2, "cmd": "system.get_device_info" }', warning: null },
-      { cmd: 'system.health', handler: 'SystemHandler', transports: ['All'], description: 'Get full HealthMonitor report — all subsystem states, warnings, and critical failures.', contents: null, returns: null, example: '{ "v": 2, "cmd": "system.health" }', warning: null },
+      { cmd: 'system.health', handler: 'SystemHandler', transports: ['All'], description: 'Get full HealthMonitor report — all subsystem states, warnings, and critical failures.', contents: null, returns: '{ "critical_count": 0, "warning_count": 0, "firmware_stable": true, "subsystems": [{ "name": "BellEngine", "status": "HEALTHY|WARNING|CRITICAL|FAILED", "error": "..." }] }', example: '{ "v": 2, "cmd": "system.health" }', warning: null },
       { cmd: 'system.factory_reset', handler: 'SystemHandler', transports: ['All'], description: 'Reset all settings to factory defaults.', contents: null, returns: null, example: '{ "v": 2, "cmd": "system.factory_reset" }', warning: 'Non-reversible. All saved configuration is permanently wiped.' },
       { cmd: 'system.restart', handler: 'SystemHandler', transports: ['All'], description: 'Reboot the device. Response is sent before reboot (2 s delay).', contents: null, returns: null, example: '{ "v": 2, "cmd": "system.restart" }', warning: null },
     ],
@@ -160,7 +197,8 @@ const NAMESPACES = [
 const LEGACY_MAP = [
   { v1_cmd: 'ping', v1_action: '—', v2: 'ping' },
   { v1_cmd: 'identify', v1_action: '—', v2: 'identify' },
-  { v1_cmd: 'playback', v1_action: '—', v2: 'playback' },
+  { v1_cmd: 'playback', v1_action: 'play', v2: 'playback.play' },
+  { v1_cmd: 'playback', v1_action: 'stop', v2: 'playback.stop' },
   { v1_cmd: 'file_manager', v1_action: 'list_melodies', v2: 'files.list' },
   { v1_cmd: 'file_manager', v1_action: 'download_melody', v2: 'files.download' },
   { v1_cmd: 'file_manager', v1_action: 'delete_melody', v2: 'files.delete' },