document channel discovery and the per-board effect catalog

AGENTS.md

@@ -39,8 +39,9 @@ keyboards.json          # Optional name/metadata lookup for known keyboards
 
 Discovery matches every connected keyboard exposing the QMK Raw HID signature
 (Usage Page `0xFF60`, Usage `0x61`) — the same check `qmk/qmk_udev` performs.
-`keyboards.json` is only consulted to attach a name to a recognized model; an
-absent or malformed file costs names, not the ability to drive the keyboard.
+`keyboards.json` is only consulted to attach a name to a recognized model and to
+name its channels; an absent or malformed file costs names, not the ability to
+drive the keyboard.
 
 `keyboard info` numbers the connected keyboards from 1 in a stable order
 (vendor ID, product ID, path). `--device` accepts that number, never a HID path.
@@ -49,14 +50,16 @@ otherwise they fail and list the selectable numbers, so a command never targets
 an unintended keyboard. Device numbers are stable for the current session only —
 HID paths are reassigned on reboot and most keyboards report no serial number.
 
-`--zone` accepts `logo`, `backlight`, or `side` and may be given on any
-subcommand. It is a persistent flag in cobra's sense only — accepted on the
+`--zone` takes a VIA lighting channel, named by its QMK subsystem, and a board
+in `keyboards.json` may give a channel a display name. README.md carries the
+vocabulary. It is a persistent flag in cobra's sense only — accepted on the
 root and inherited by subcommands — and nothing is remembered between runs, so
-it must be repeated on every invocation. Without `--zone`, commands target
-Logo, Backlight, and Side in that order.
-With `--zone`, commands target exactly one zone. Unsupported default targets
-are skipped with a stderr warning; unsupported explicit-zone effects and
-unknown names fail before the device is opened.
+it must be repeated on every invocation. Without `--zone`, commands target every
+channel the keyboard reports, in channel order; the channels are discovered by
+asking the keyboard, not assumed. With `--zone`, commands target exactly one
+channel. A default command skips a target that does not support an effect and
+warns on stderr; an explicitly named channel that does not support it, and an
+unknown name, fail before the device is opened.
 
 ## Stack
 
@@ -104,6 +107,10 @@ each zone's real value and the request. Never let a command report success for a
 value the keyboard did not accept. Both read back through the shared
 `setValueVerified`, so a future parameter needs no new read-back path.
 
+The effect names are a board's catalog in `internal/rgb/catalog.go`, transcribed
+from the two sources its comment names. They look like data the tool invented and
+are not; do not edit a list on a hunch, and do not add a second one.
+
 When you see a name or a behavior in one file, grep for it across the whole repo before deciding if a change is consistent.
 
 ## Read the Firmware When Something Is Unclear

README.md

@@ -88,12 +88,25 @@ re-run the command whenever commands or flags change.
 ./qmk-rgb-tool --device 1 enable
 ```
 
-`--zone` accepts `logo`, `backlight`, or `side` and may be given on any
-subcommand. It is not remembered between runs: repeat it on every invocation.
-Without `--zone`, commands target Logo, Backlight, and Side in that order.
-With `--zone`, commands target exactly the selected zone. An unsupported
-name for an explicit zone fails before the device is opened; a default
-command skips unsupported zones and prints a warning on stderr.
+`--zone` accepts a VIA lighting channel: `backlight`, `rgblight`, `rgb_matrix`,
+`audio` or `led_matrix`, and may be given on any subcommand. The name follows
+from the channel number, so it works on every QMK keyboard. A board listed in
+`keyboards.json` may give a channel a display name, and that name is accepted
+too — the Impact 80 calls channels 2, 3 and 4 `logo`, `backlight` and `side`.
+Where a display name would be the subsystem name of a different channel the
+keyboard has, the board is refused rather than a command being sent to the wrong
+channel.
+
+`--zone` is not remembered between runs: repeat it on every invocation. Without
+`--zone`, commands target every channel the keyboard reports, in channel order.
+With `--zone`, commands target exactly the named channel. An unknown name fails
+before the device is opened; an effect a named channel does not have fails
+rather than being skipped, while a default command skips it and prints a
+warning on stderr.
+
+The keyboard is asked which channels it has: one read per channel, and a channel
+its firmware does not implement answers as unhandled. `keyboard info` does not
+report them, because it never opens the keyboard.
 
 All output is machine-parseable JSON when applicable.
 
@@ -151,6 +164,22 @@ Hex is the wider of the two: at full brightness it reaches 195,841 colors, a pai
 of 8-bit hue and saturation values 56,654. They cover the same colors, and `hsv:`
 trades some of that range for direct addressing.
 
+## Effect Names Are Per Board
+
+The keyboard holds effect numbers, not names, so `effect <name>` needs a catalog
+and the tool has one for the Impact 80. Its 46 backlight names are QMK's
+`rgb_matrix_effects.inc` in order, verified against the keyboard's register; the
+7 `logo` and 7 `side` names are that board's vendor VIA definition, whose
+dropdowns read `fixed wave` and `breathe`; the compatibility aliases are the
+tool's own.
+
+A keyboard without a catalog is still driven: `brightness`, `speed`, `color`,
+`mode <index>` and `info` all work, because none of them needs a name. Only
+`effect <name>` and `effect --list` need the catalog, and they say so rather than
+guessing. `enable` is the third command that needs one, because it has to choose
+an effect to turn a channel on, and it refuses without a catalog rather than
+picking an ID blind.
+
 ## Brightness and Speed Are Not Applied Verbatim
 
 The keyboard's firmware transforms these values per channel, so the accepted
@@ -383,7 +412,7 @@ Two models are listed in `keyboards.json`:
 | `qmk-rgb-tool color rgb:<hex>`        | The same hex color, written out |
 | `qmk-rgb-tool color hsv:<h>,<s>,<v>`  | Set hue and saturation (0–255) and write `v` to the brightness of the same zones |
 | `qmk-rgb-tool mode <index>`           | Set a raw zone-specific effect ID         |
-| `qmk-rgb-tool --zone <zone> ...`      | Target `logo`, `backlight`, or `side`     |
+| `qmk-rgb-tool --zone <channel> ...`   | Target one channel: `backlight`, `rgblight`, `rgb_matrix`, `audio` or `led_matrix`, or a name from `keyboards.json` |
 | `qmk-rgb-tool --device <n> ...`      | Target keyboard by number (see `keyboard info`) |
 | `qmk-rgb-tool save [name]`            | Save current RGB state to `profiles/<name>.json` (name lowercased, non-`[a-z0-9-_]` mapped to `-`) |
 | `qmk-rgb-tool load [name]`            | Load and apply a profile from `profiles/` |
@@ -419,8 +448,14 @@ Communicates via the QMK Raw HID interface (`Usage Page 0xFF60`, `Usage 0x61`) w
 
 - `0x07` — Custom set value
 - `0x08` — Custom get value
-- Lighting channels: `0x02` logo, `0x03` backlight, `0x04` side lighting
-- RGB values: brightness `0x01`, effect `0x02`, speed `0x03`, color `0x04`
+- Lighting channels are QMK's `id_qmk_*_channel` values: `0x01` backlight,
+  `0x02` rgblight, `0x03` rgb_matrix, `0x04` audio, `0x05` led_matrix. A
+  channel the firmware does not compile in answers a get with `0xFF`, which is
+  how the tool discovers what a keyboard has. The Impact 80 uses `0x02` for its
+  logo, `0x03` for its backlight and `0x04` for its side lighting.
+- RGB values are identical for every lighting subsystem: brightness `0x01`,
+  effect `0x02`, speed `0x03`, color `0x04`. That uniformity is why the tool has
+  no per-subsystem code path.
 
 `enable` and `disable` use no separate handshake: they set the effect ID and
 brightness, and nothing else.