1 files changed, 24 insertions, 1 deletions

diff --git a/desktop/island/README.md b/desktop/island/README.md
index 2b2c9fe..8f70506 100644
--- a/desktop/island/README.md
+++ b/desktop/island/README.md
@@ -46,8 +46,9 @@ is open or not.
 
 ## Status pill
 
-Left to right: volume icon, tray, layout flag.
+Left to right: controls icon, volume icon, tray, layout flag.
 
+- **Controls icon** opens the controls panel, see below.
 - **Volume icon** shows the default sink (muted, low, medium, high). Click
   opens the sound panel.
 - **Tray** shows `SystemTray` items. Left click activates, right click opens
@@ -58,6 +59,28 @@ Left to right: volume icon, tray, layout flag.
   `activelayout` event. Scroll switches layout with
   `hyprctl switchxkblayout current next|prev`.
 
+## Controls panel
+
+Opened by the status pill's controls icon, or by SUPER pressed and released
+alone (`qs -p desktop ipc call island controls`, a Hyprland release bind;
+any key or mouse bind pressed in between cancels it). Seven tiles: wifi,
+bluetooth, DND, presentation, auto-lock, output, mic.
+
+- Click toggles. Right-click closes the panel and opens the tile's drawer
+  page.
+- Output and mic fill to their volume, clamped at 100%; muted greys the bar
+  instead of emptying it. Scroll steps 5%, output capped at 150%.
+- A tile whose backing object has not arrived (the first two seconds, no
+  adapter, no sink) is dimmed and ignores input.
+- The pencil enters edit mode: drag a tile to another slot, × hides it, the
+  strip below lists hidden tiles with a + each. Closing the panel ends it.
+
+The visible tiles and their order live in
+`$XDG_STATE_HOME/quickshell/desktop.json` (`../Prefs.qml`), written only when
+they change and keeping keys it does not know. A tile added to the code
+later starts hidden. Pure helpers in `Controls.js`, tested with
+`node island/test_controls.js`.
+
 ## Privacy
 
 `privacy.sh` prints `mic cam loc scr`, each 0 or 1, and `Privacy.qml` polls it