PR comment: move docs from root folder

old_cloud_2_doc/FEATURE_CAPABILITIES.md

@@ -0,0 +1,107 @@
+# HyperX Headset Feature Capabilities
+
+This document summarizes which features can be controlled vs only monitored for each headset model.
+
+## Cloud II Wireless (Non-DTS)
+
+### Writable Features (Can be SET via HID commands)
+
+- ✅ **Auto Power Off** - Can set automatic shutdown timer (0-30 minutes)
+- ✅ **Sidetone** - Can enable/disable sidetone (on/off only, no volume control)
+
+### Read-Only Features (Can only monitor, not control)
+
+- ❌ **Microphone Mute** - Hardware button only, cannot be controlled via HID
+- ❌ **Surround Sound (7.1)** - Controlled via Windows DTS APO or physical button, not HID
+- ❌ **Battery Level** - Read-only status
+- ❌ **Charging Status** - Read-only status
+- ❌ **Connection Status** - Read-only status
+- ❌ **Firmware Version** - Read-only information
+
+## Cloud II Wireless DTS
+
+### Writable Features
+
+- ✅ **Auto Power Off**
+- ✅ **Sidetone** - With volume control (0-100)
+- ✅ **Surround Sound** - Via Windows DTS APO system calls (not direct HID)
+
+### Read-Only Features
+
+- ❌ **Microphone Mute** - Hardware button only
+- ❌ **Battery Level**
+- ❌ **Charging Status**
+- ❌ **Connection Status**
+
+## Cloud III Wireless
+
+### Writable Features
+
+- ✅ **Auto Power Off**
+- ✅ **Sidetone** - With volume control (0-100)
+- ✅ **Microphone Mute** - Can be controlled programmatically
+- ✅ **Voice Prompt** - Can enable/disable voice prompts
+- ✅ **Playback Mute (Silent Mode)** - Can mute headphone output
+
+### Read-Only Features
+
+- ❌ **Surround Sound** - Not supported via HID
+- ❌ **Battery Level**
+- ❌ **Charging Status**
+- ❌ **Connection Status**
+- ❌ **Product Color**
+
+## CLI Error Handling
+
+The CLI application now provides clear error messages when attempting to use unsupported features:
+
+```bash
+# Example: Trying to control surround sound on Cloud II Wireless
+$ ./hyper_headset_cli --surround_sound true
+ERROR: Surround sound control is not supported on this device
+       Use the physical headset button or Windows audio settings to toggle surround sound.
+
+# Example: Trying to mute on Cloud II Wireless
+$ ./hyper_headset_cli --mute true
+ERROR: Microphone mute control is not supported on this device (hardware button only)
+```
+
+## Tray Application UI
+
+The system tray application now displays "(read-only)" markers next to features that cannot be controlled:
+
+```
+Battery level:            92%
+Charging status:          Not charging
+Muted:                    false (read-only)
+Automatic shutdown after: 20min
+Side tone:                false
+Surround sound:           true (read-only)
+Connected:                true
+```
+
+## Implementation Details
+
+- Feature capabilities are checked once during device initialization via `init_capabilities()`
+- Capability flags are stored in `DeviceState` structure
+- CLI flags for unsupported features are hidden in the help menu
+- CLI exits with error code 1 when attempting to use unsupported features
+- Tray UI shows read-only markers based on device capabilities
+
+## Protocol Notes
+
+### Undocumented Commands
+
+**Command 4 (Cloud II Wireless)**: An undocumented HID command that occasionally appears as an asynchronous notification from the headset. This command is **not handled** by the official HyperX NGenuity2 software, which simply logs it to debug traces.
+
+- **Appearance**: Sporadic, trigger conditions unknown
+- **Official behavior**: Ignored by NGenuity2
+- **HyperHeadset behavior**: Logged for debugging purposes
+- **Investigation findings**:
+  - Does NOT trigger on charging cable connect/disconnect
+  - Does NOT trigger on battery level changes
+  - Not related to any user-controllable feature
+  - May be firmware artifact from Cloud Flight S (which uses cmd 4 for button presses)
+  - Cloud II Wireless and Cloud II Wireless DTS both ignore this command
+
+This is documented for transparency but can be safely ignored during normal operation.