docs: add webcam compatibility matrix

CONTRIBUTING.md

@@ -21,6 +21,13 @@ python -m unittest discover -s tests -v
 
 Create a branch, keep commits scoped and open a pull request against `main`.
 
+## Manual webcam compatibility testing
+
+Use the [webcam compatibility matrix](docs/WEBCAM_COMPATIBILITY_MATRIX.md) to
+test camera detection, preview, hand tracking, reconnection and shutdown on
+Windows. Submit only the completed text fields; do not attach camera captures,
+serial numbers or personal imagery.
+
 ## Architecture rules
 
 - Communicate across modules through the `EventBus`.

docs/WEBCAM_COMPATIBILITY_MATRIX.md

@@ -0,0 +1,226 @@
+# Webcam compatibility matrix
+
+Use this template to test one webcam with Room OS on Windows. Repeat the full
+matrix for every camera, Windows version or Room OS version being reported.
+
+## Privacy rules
+
+Submit text results only. Do not submit camera captures, screenshots of the
+preview, serial numbers, device IDs, full logs or personal imagery. Keep faces,
+documents, addresses and other identifying items outside the camera view. If a
+log helps diagnose a failure, copy only the relevant non-personal error text
+into Notes after removing usernames and file paths.
+
+## Test record
+
+| Field | Value |
+| --- | --- |
+| Windows edition and version | |
+| Room OS version or commit | |
+| Camera manufacturer and model | |
+| Connection type (built-in or USB) | |
+| Test date | |
+
+Use only a public camera model name. Do not record a serial number, device ID or
+asset tag.
+
+### Result summary
+
+Enter `Pass`, `Fail` or `Not tested` for each behavior. Add only text notes.
+
+| Behavior | Result | Notes |
+| --- | --- | --- |
+| Windows camera detection | | |
+| 720p/30 FPS fallback | | |
+| Mirrored preview | | |
+| Hand tracking at multiple distances | | |
+| Disconnect and reconnect | | |
+| Close to tray (when enabled) | | |
+| True application exit and webcam release | | |
+
+## Test setup
+
+1. Use Windows 10 or 11 with Room OS installed from a release or the
+   [development setup](../README.md#development-setup).
+2. Close Windows Camera, meeting software and any other application that may be
+   using the webcam.
+3. Place the webcam in a stable position with even lighting and a plain,
+   non-personal background.
+4. Connect only the camera being tested. For a built-in camera, disconnect other
+   webcams.
+5. Start Room OS, finish first-run setup if necessary and open **Cámara**.
+
+## 1. Windows camera detection
+
+### Detection steps
+
+1. Confirm the webcam appears and produces a live preview in the Windows Camera
+   app, then close Windows Camera completely.
+2. Start Room OS and open **Cámara**.
+3. Wait up to 10 seconds for the preview.
+4. Move a hand through the frame to confirm that the image is live rather than a
+   frozen frame.
+
+### Detection expected result
+
+Room OS opens the available webcam without a camera error, displays a live
+preview and updates the FPS value.
+
+**Result (Pass/Fail):**
+
+**Notes:**
+
+## 2. 720p/30 FPS fallback
+
+### Fallback steps
+
+1. Use a webcam whose Windows or manufacturer settings expose 1280x720 at 30
+   FPS. If the camera defaults to a higher mode, select or limit it to 720p/30
+   in the manufacturer's utility when that option is available.
+2. Close the camera utility and any other application using the webcam.
+3. Start Room OS, open **Cámara** and leave the preview running for 10 seconds.
+4. Record the settled FPS value shown in Room OS. When testing from source, also
+   record only the numeric width, height and FPS from the
+   `Configuración activa de cámara` log line; do not attach the log.
+
+### Fallback expected result
+
+Room OS keeps a live 1280x720 stream instead of failing when a higher camera
+mode is unavailable. The displayed rate settles near 30 FPS; small fluctuations
+are acceptable, but repeated freezes or loss of the stream are a failure.
+
+**Observed width x height:**
+
+**Observed FPS:**
+
+**Result (Pass/Fail):**
+
+**Notes:**
+
+## 3. Mirrored preview
+
+### Mirroring steps
+
+1. Open **Cámara** and stand centered in the frame.
+2. Raise your right hand, then lower it and raise your left hand.
+3. Move one hand slowly to your right and then to your left while watching the
+   preview.
+
+### Mirroring expected result
+
+The preview behaves like a mirror: the raised hand appears on the same side of
+the preview as the tester, and horizontal movement follows the tester's
+direction without reversing unexpectedly.
+
+**Result (Pass/Fail):**
+
+**Notes:**
+
+## 4. Hand tracking at multiple distances
+
+### Tracking steps
+
+1. In **Cámara**, enable **Puntos de manos**.
+2. Hold one open hand fully inside the frame at approximately 0.5 m from the
+   webcam for five seconds.
+3. Repeat at approximately 1.0 m and 1.5 m, keeping the complete hand visible
+   and using the same lighting.
+4. At each distance, rotate the wrist slowly and move the hand across the center
+   of the frame.
+
+### Tracking expected result
+
+Hand landmarks appear and continue following the visible hand at all three
+distances without persistent loss or attaching to the background. Brief loss
+during a fast movement is acceptable if tracking recovers when the hand stops.
+
+| Distance | Result (Pass/Fail) | Notes |
+| --- | --- | --- |
+| Approximately 0.5 m | | |
+| Approximately 1.0 m | | |
+| Approximately 1.5 m | | |
+
+## 5. Disconnect and reconnect
+
+Skip this check for a built-in camera that cannot be safely disconnected.
+
+### Reconnection steps
+
+1. With a stable live preview open, unplug the USB webcam.
+2. Confirm Room OS reports the camera problem or a reconnecting state; wait at
+   least five seconds.
+3. Reconnect the same webcam to the same USB port.
+4. Wait up to 15 seconds without restarting Room OS, then move a hand through
+   the frame.
+
+### Reconnection expected result
+
+Room OS remains open after disconnection, reports that the camera is unavailable
+and automatically restores a live preview after reconnection. The FPS value and
+hand tracking resume without restarting the application.
+
+**Reconnect time in seconds:**
+
+**Result (Pass/Fail/Not tested):**
+
+**Notes:**
+
+## 6. Close to tray and true application exit
+
+Room OS can remain running in the Windows notification area after its window is
+closed. Test that behavior separately from a true application exit; a hidden
+window does not demonstrate that Room OS released the webcam. This section does
+not test the Windows system shutdown action.
+
+### Close-to-tray steps
+
+1. In **Configuración**, enable **Mantener Room OS en la bandeja al cerrar** and
+   save the setting.
+2. With the preview and hand tracking active, close the Room OS window using the
+   standard Windows close button.
+3. Confirm the window and taskbar entry disappear, but the Room OS notification
+   area icon and process remain available.
+4. Open Room OS from its notification area icon and confirm the window and live
+   preview return.
+
+### Close-to-tray expected result
+
+Closing the window hides Room OS without terminating it. The notification area
+icon remains available, and reopening Room OS restores the live preview without
+starting a second process.
+
+**Result (Pass/Fail/Not tested):**
+
+**Notes:**
+
+### True-exit steps
+
+1. With the preview and hand tracking active, perform a true exit by selecting
+   **Salir** from the Room OS notification area menu. Alternatively, disable
+   **Mantener Room OS en la bandeja al cerrar**, save the setting and close the
+   window with the standard Windows close button.
+2. Wait five seconds and confirm the Room OS window, taskbar entry and
+   notification area icon are gone.
+3. Check Task Manager for `Room OS.exe` or the Python process used to start Room
+   OS.
+4. Open Windows Camera and confirm it can immediately use the webcam, then close
+   it.
+
+### True-exit expected result
+
+Room OS exits without an error dialog, leaves no Room OS process running and
+releases the webcam so another application can open it. A camera activity light,
+when present, turns off after Room OS closes.
+
+**Result (Pass/Fail):**
+
+**Notes:**
+
+## Submission checklist
+
+- [ ] Every summary result is `Pass`, `Fail` or `Not tested`.
+- [ ] Failures include reproducible text notes.
+- [ ] The record contains no camera captures, serial numbers, device IDs, full
+      logs or personal imagery.
+- [ ] Only the Windows version, Room OS version, public camera model, connection
+      type, date and test results are submitted.