add gui_brightness tool (percentage-based brightness control)

Makefile

@@ -188,9 +188,9 @@ data:
 
 # --- GUI Tools (standalone install) ---
 
-GUI_TOOLS := gui_accessibility gui_activities gui_apps gui_clipboard \
-             gui_files gui_input gui_notify gui_screenshot \
-             gui_shortcuts gui_windows
+GUI_TOOLS := gui_accessibility gui_activities gui_apps gui_brightness \
+             gui_clipboard gui_files gui_input gui_notify \
+             gui_screenshot gui_shortcuts gui_windows
 
 tools-install:
 	@echo "=== Installing GUI automation tools ==="

prompts/tools-gui.md

@@ -211,3 +211,22 @@ call_tool: calls=[{tool: "gui_accessibility", args: ["tree", "Dolphin", "3"]}]
 **Workflow**: Use `apps` → `inspect` → `find` to locate elements, then `click`/`type`/`action` to interact.
 
 **Requires**: `python3-gobject` and AT-SPI2 typelib (`dev-libs/at-spi2-core` on Gentoo).
+
+---
+
+## gui_brightness
+
+Get/set screen brightness via PowerDevil. Accepts **percentages** (0–100), not raw hardware values.
+
+**Args**: `[command]` or `[command, value]`
+
+Commands: `get`, `set <percent>`, `up [step]`, `down [step]`
+
+```
+call_tool: calls=[{tool: "gui_brightness", args: ["get"]}]
+call_tool: calls=[{tool: "gui_brightness", args: ["set", "50"]}]
+call_tool: calls=[{tool: "gui_brightness", args: ["up", "10"]}]
+call_tool: calls=[{tool: "gui_brightness", args: ["down", "25"]}]
+```
+
+**Note**: The underlying PowerDevil API uses absolute values (0 to ~10000). This tool handles the conversion — always pass percentages.

tools/gui_brightness

@@ -0,0 +1,84 @@
+#!/usr/bin/env bash
+# description: Get/set screen brightness via PowerDevil D-Bus. Args: [get|set <percent>|up|down]
+# NOTE: PowerDevil uses absolute values (0 to brightnessMax, typically 10000).
+# This tool accepts PERCENTAGES (0-100) and converts internally.
+set -euo pipefail
+
+SERVICE="org.kde.Solid.PowerManagement"
+OBJ_PATH="/org/kde/Solid/PowerManagement/Actions/BrightnessControl"
+IFACE="org.kde.Solid.PowerManagement.Actions.BrightnessControl"
+
+cmd="${1:-get}"
+
+# Get max brightness (needed for percentage conversion)
+get_max() {
+    gdbus call --session --dest "$SERVICE" \
+        --object-path "$OBJ_PATH" \
+        --method "$IFACE.brightnessMax" | \
+        sed 's/(//;s/,)//'
+}
+
+# Get current brightness (absolute)
+get_current() {
+    gdbus call --session --dest "$SERVICE" \
+        --object-path "$OBJ_PATH" \
+        --method "$IFACE.brightness" | \
+        sed 's/(//;s/,)//'
+}
+
+case "$cmd" in
+    get)
+        max=$(get_max)
+        current=$(get_current)
+        percent=$(( current * 100 / max ))
+        echo "${percent}% ($current/$max)"
+        ;;
+    set)
+        percent="${2:?usage: gui_brightness set <percent 0-100>}"
+        if [ "$percent" -lt 0 ] || [ "$percent" -gt 100 ]; then
+            echo "ERROR: percent must be 0-100" >&2
+            exit 1
+        fi
+        max=$(get_max)
+        value=$(( percent * max / 100 ))
+        gdbus call --session --dest "$SERVICE" \
+            --object-path "$OBJ_PATH" \
+            --method "$IFACE.setBrightness" "$value" >/dev/null
+        echo "brightness: ${percent}% ($value/$max)"
+        ;;
+    up)
+        step="${2:-10}"
+        max=$(get_max)
+        current=$(get_current)
+        current_pct=$(( current * 100 / max ))
+        new_pct=$(( current_pct + step ))
+        [ "$new_pct" -gt 100 ] && new_pct=100
+        value=$(( new_pct * max / 100 ))
+        gdbus call --session --dest "$SERVICE" \
+            --object-path "$OBJ_PATH" \
+            --method "$IFACE.setBrightness" "$value" >/dev/null
+        echo "brightness: ${new_pct}% ($value/$max)"
+        ;;
+    down)
+        step="${2:-10}"
+        max=$(get_max)
+        current=$(get_current)
+        current_pct=$(( current * 100 / max ))
+        new_pct=$(( current_pct - step ))
+        [ "$new_pct" -lt 0 ] && new_pct=0
+        value=$(( new_pct * max / 100 ))
+        gdbus call --session --dest "$SERVICE" \
+            --object-path "$OBJ_PATH" \
+            --method "$IFACE.setBrightness" "$value" >/dev/null
+        echo "brightness: ${new_pct}% ($value/$max)"
+        ;;
+    *)
+        echo "usage: gui_brightness [get|set <percent>|up [step]|down [step]]" >&2
+        echo "" >&2
+        echo "  get           - show current brightness as percentage" >&2
+        echo "  set <0-100>   - set brightness to percentage" >&2
+        echo "  up [step]     - increase by step% (default 10)" >&2
+        echo "  down [step]   - decrease by step% (default 10)" >&2
+        exit 1
+        ;;
+esac