say what a board naming VIA's built-in menu gets, and record the references

The README claimed a board whose definition names VIA's built-in
`qmk_rgb_matrix` menu needs no work, because the names and IDs are the
built-in ones. That describes the data, not the tool: the file carries
the name of the menu and not the names in it, so the fetch succeeds,
every channel reports `0 effects`, and the effect is set by number. The
Glorious GMMK Pro is the board that shows it. The section now says that,
with the fetch output and the error, and says why no fallback to those
45 names is built in: a transcribed list is the second copy of a name
a per-board file exists to be, and `All Off` and `Band Sat.` do not
reach `none` and `band_sat` the way `Solid Color` and `Breathing` do.

AGENTS.md gains the references for that question, measured rather than
recalled. The 45 names are in `the-via/reader`, in TypeScript, at the
positions of the dropdown. The three tools that drive the same raw HID
from a terminal take effect IDs and none reads a definition file, which
is the gap this tool's catalog sits in; they are recorded with their
flags, licences and last pushes, as a source of features worth having
and code worth not taking. The `qmk` CLI had no lighting command to
remove: no `led`, `rgblight` or `hid` module at any tag from 0.6 to
master, and the commits path filter that does report deletions proves
the absence is an absence.

AGENTS.md

@@ -326,6 +326,64 @@ but keeps its device data in C++ controllers, so it settles VID/PID, not effects
 README.md carries the details; the conclusion for code here is that a catalog is
 transcribed per board and cannot be generated from a common source.
 
+**The names for VIA's built-in menu are in no definition file at all.** A
+definition that writes `"menus": ["qmk_rgb_matrix"]` — a string, not a menu object —
+refers to the menu VIA's own app carries, and those names live in `the-via/reader`
+(the `@the-via/reader` package), in `src/common-menus/qmk_rgb_matrix.ts`: the
+`options` array of the `id_qmk_rgb_matrix_effect` dropdown, where position equals
+effect ID 0 to 44. It is TypeScript with nested `content`, `showIf` and range
+constraints, so nothing here can read it at runtime, and the spellings are VIA
+display labels rather than QMK enum identifiers — `Solid Color` and `Breathing`
+reach `solid_color` and `breathing` through `byName`'s space/underscore rule,
+while `All Off` and `Band Sat.` reach nothing the tool spells today. The GMMK Pro
+(0x320F/0x5044) is one of these boards: `keyboard fetch` succeeds, stores the file,
+and the catalog comes out empty, so no effect name resolves. Whether to fall back
+to those 45 names, and where such a fallback's list would come from, is still open
+— a list typed into this repository is the drift these rules forbid, so do not add
+one without asking.
+
+**Nobody ships names over the wire, which is the reason this tool exists.** These
+projects drive the same raw HID interface from a terminal, and each of them takes
+an effect **ID**:
+
+- <https://github.com/FrameworkComputer/qmk_hid> — Rust CLI, plus a Python GUI in
+  `python/`; BSD-3-Clause. `qmk_hid via --rgb-effect 38`, plus `--rgb-brightness`,
+  `--rgb-hue`, `--rgb-saturation`, `--rgb-color`, `--rgb-effect-speed`,
+  `--backlight`, `--backlight-breathing`, `--save`, `--device-indication`,
+  `--eeprom-reset`, `--bootloader`, and `-l`/`--vid`/`--pid`. Its README states
+  the reason out loud: "the effect numbers can be different per keyboard", and it
+  says the tool "will soon be superceded by QMK XAP".
+- <https://github.com/njkevlani/qmk-light> — C++ against hidapi, one `qmk-light.cpp`;
+  **no licence file**, so nothing may be taken from it. `--list`, `--get-brightness`,
+  `--set-brightness` (absolute or `+5`/`-10`), `--list-effects`, `--get-effect`,
+  `--set-effect`, `--get-effect-speed`, `--set-effect-speed`, `--get-color`,
+  `--set-color h,s`, `--device <index|path>`, `--first-device`, `--quiet`.
+- <https://github.com/Drugantibus/qmk-hid-rgb> — Python, GPL-3.0, untouched since
+  2021; a proof of concept that needs a keymap of its own with `RAW_ENABLE = yes`
+  and the board's VID/PID written into the source.
+
+None of them reads a definition file, so none can name an effect. That is the gap
+this tool's catalog and `keyboard fetch` sit in.
+
+Read them for that gap, and for anything this tool does not do yet: they are the
+three live implementations of the same wire protocol, and their flag surfaces are
+where a gap in ours shows up first — persistence (`--save`, `--eeprom-reset`),
+device indication, effect speed as its own parameter, colour by name, jumping to
+the bootloader, and explicit device selection where more than one board is
+attached (`--first-device`). Any of those is a candidate feature here, not a
+duplicate to reimplement badly. Check a project's licence before taking code from
+it, and check whether it has moved on before treating its behaviour as current.
+
+**The `qmk` CLI has never had a lighting command.** Do not explain a missing
+feature by saying QMK removed one. Measured on `qmk_firmware`: `lib/python/qmk/cli/`
+carries no `led`, `rgblight` or `hid` module at tags 0.6, 0.9, 0.10, 0.15 through
+0.21, 0.24 or on master, the commits API returns zero commits for those paths, and
+`docs/cli_commands.md` documents none at any of those tags. The path filter does
+report deletions — `lib/python/qmk/cli/cformat.py` and `multibuild.py` both end at
+`4723f308a`, *"Remove CLI commands: `multibuild`, `cformat`, `fileformat`,
+`pyformat`"*, 2023-01-18 — so an empty result means the file was never there, not
+that it was removed.
+
 ## Output Shape
 
 `keyboard info`, `info`, `list`, the effect list and `keyboard definitions` print text,

README.md

@@ -455,8 +455,39 @@ the collection:
 
 The built-in list lives in
 [`the-via/reader/src/common-menus/qmk_rgb_matrix.ts`](https://github.com/the-via/reader/blob/master/src/common-menus/qmk_rgb_matrix.ts)
-and has 45 names, `All Off` through `Solid Multi Splash`, at IDs 0 to 44. A board
-that uses it needs no work at all: the names and the IDs are the built-in ones.
+and has 45 names, `All Off` through `Solid Multi Splash`, at IDs 0 to 44.
+
+**A board that names the built-in menu has no effect names in this tool.** Its
+definition file carries the name of VIA's own menu, not the names inside it, so
+there is nothing in the file to read and nothing is invented. The fetch succeeds
+and the file is stored, the channel list comes back with `0 effects` on every
+channel, and an effect is set by number. The Glorious GMMK Pro (0x320F/0x5044) is
+one of these boards, and so is every GMMK V2:
+
+```console
+$ qmk-rgb-tool keyboard fetch
+Saved definition for GMMK Pro (0x320F/0x5044) to …/definitions/gmmk_pro_0x320F_0x5044.json
+  backlight   0 effects
+  rgblight    0 effects
+  rgb_matrix  0 effects
+  audio       0 effects
+  led_matrix  0 effects
+
+$ qmk-rgb-tool effect rgb_matrix breathing
+Error: the VIA definition for GMMK Pro names no effects, so no effect name can be resolved; this board's
+names are not in the file, and an effect is set by number with `effect <zone> <index>`
+```
+
+`0 effects` next to a saved definition is that answer, not a failed fetch. The 45
+names are public, and for a board like this the IDs are their positions, so
+nothing would have to be measured. This tool does not fall back to them, for two
+reasons. A list transcribed into the source is the second copy of a name that a
+per-board file exists to be, and the spellings do not line up anyway: `All Off`
+and `Band Sat.` are display labels that do not reach `none` and `band_sat` the way
+`Solid Color` and `Breathing` do. A board in this group is driven by number until a
+definition spells its effects out — see
+[Compatibility Aliases](#compatibility-aliases) for what the tool accepts for a
+board that does.
 
 The other 153 deviate, and not only in how many effects they compile in. MonsGeek's
 M1 uses QMK's enum identifiers and its own 19: `SOLID_COLOR`, `BREATHING`,