correct the color and speed behaviour the docs claimed

breathing does honor the color: it holds hue and saturation and pulses the
color's value, and hue_breathing swings the hue narrowly around the hue that
was set rather than running through the full range. Both were wrong in the
effect catalogue.

On logo and side only three speeds are reachable: 0 freezes the animation,
1 is the slowest movement, and 2 and above are stored as 4. The freeze was
observed on logo; the collapse to 4 on both channels is measured.

AGENTS.md gains the discipline that produced those corrections: unclear
firmware behaviour is settled by reading the QMK upstream and the vendor's
VIA definition, naming which subsystem the reading was for, because a formula
from the wrong subsystem is what made the wrong claim look right.

AGENTS.md

@@ -91,10 +91,11 @@ Documented behavior must also match the code:
 
 The Impact 80 firmware rescales or clamps brightness and speed per channel, so
 an accepted 0–255 request is not the value the keyboard holds. `logo` and `side`
-cap brightness at 160 and collapse any speed above 0 to 4, while `backlight`
-scales brightness up to 255 and applies speed as given. README.md tabulates the
-per-channel behaviour; the rule that follows from it is the part that matters
-when you write code here:
+cap brightness at 160 and have only three reachable speeds — 0 freezes the
+animation, 1 is the slowest movement, anything above 1 becomes 4 — while
+`backlight` scales brightness up to 255 and applies speed as given. README.md
+tabulates the per-channel behaviour; the rule that follows from it is the part
+that matters when you write code here:
 
 `brightness` and `speed` read every selected zone back and print what was
 actually applied; where all zones match they print `Brightness set to N` or
@@ -105,6 +106,31 @@ value the keyboard did not accept. Both read back through the shared
 
 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
+
+Unclear firmware behaviour is answered by reading source, not by inferring it
+from names, from a general QMK assumption, or from a doc line that nobody has
+checked. Two sources settle nearly everything, and both are cheap to reach.
+
+Upstream QMK is public: `quantum/rgb_matrix/rgb_matrix.h` for the value API,
+`quantum/rgb_matrix/animations/` for what an effect actually does to hue,
+saturation and value. The vendor's VIA definition JSON for the board settles
+what the interface exposes at all — which custom value IDs exist, which ranges
+they take, and for which effects a color control is offered. It is the authority
+on the wire format, more than upstream is, because the ID mapping is the
+vendor's.
+
+The board's own firmware is a vendor binary with no public source, so both
+sources describe the family, not the unit on the desk. Confirm against the
+hardware where that is cheap, then put the observation in README.md.
+
+One trap this session paid for: the vendor channels are not all the same QMK
+subsystem. One is `rgb_matrix`, one is the lightweight `rgblight`, and one is
+the audio effect subsystem. An upstream file that governs one channel does not
+govern another, so "the QMK source says" has to name the channel it was read
+for. A formula from the wrong subsystem is how this repo ended up claiming that
+speed 0 and 1 behaved identically.
+
 ## Code vs Documentation
 
 All documentation (README.md, comments, AGENTS.md) must stay in sync with the code.

README.md

@@ -173,9 +173,22 @@ Observed on the Impact 80:
 
 | Zone | Channel | Brightness | Speed |
 |---|---|---|---|
-| `logo` | `0x02` | clamps at 160 | any value above 0 becomes 4 |
+| `logo` | `0x02` | clamps at 160 | `0` stops the animation, `1` is the slowest movement, above 1 becomes 4 |
 | `backlight` | `0x03` | scales up, saturating at 255 | applied as given |
-| `side` | `0x04` | clamps at 160 | any value above 0 becomes 4 |
+| `side` | `0x04` | clamps at 160 | `0` stops the animation, `1` is the slowest movement, above 1 becomes 4 |
+
+Speed is not a smooth dial on `logo` and `side`. Only three outcomes are
+reachable there, and the value range the vendor's own VIA definition offers for
+those two channels is `[0, 4]`, not 0–255:
+
+| Requested | Stored | Effect |
+|---:|---:|---|
+| `0` | `0` | the animation is frozen, the color stands still |
+| `1` | `1` | the slowest movement |
+| `2` and above | `4` | twice as fast; this is where every larger request lands |
+
+The freeze at `0` was observed on `logo`; `side` reports the same range and the
+same collapse to 4. `backlight` is the only channel with a usable 0–255 range.
 
 The command exits 0 either way: a value the firmware cannot represent is not a
 failure, but the summary line always states the value that was actually applied.
@@ -246,14 +259,19 @@ Effects fall into categories that behave differently:
 
 - **Static** effects (`solid_color`, `none`) display a steady output. The color is set by `color` and is constant.
 - **Reactive** effects (`solid_reactive*`) light up on key press. They honor the color set by `color` — the pressed key's LEDs flash in the configured color. Use `speed` to adjust how long the illumination lasts.
-- **Breathing** effects (`breathing`, `hue_breathing`) slowly fade in and out. They do not honor `color` directly; `hue_breathing` cycles through the full hue range.
-- **Dynamic/stream** effects (`band_*`, `cycle_*`, `rainbow_*`, `starlight*`, `raindrops`, `jellybean_raindrops`, `flower_blooming`, `pixel_flow`, `riverflow`) animate independently. Most ignore `color` and use their own color palettes. `hue_breathing`, `hue_pendulum`, and `hue_wave` cycle through hues.
+- **Breathing** effects (`breathing`, `hue_breathing`) slowly fade in and out, and both honor `color`. `breathing` keeps the hue and saturation and pulses the brightness of that color; `hue_breathing` swings the hue around the hue you set by a narrow amount instead of running through the full range.
+- **Dynamic/stream** effects (`band_*`, `cycle_*`, `rainbow_*`, `starlight*`, `raindrops`, `jellybean_raindrops`, `flower_blooming`, `pixel_flow`, `riverflow`) animate independently. Most ignore `color` and use their own color palettes. `hue_pendulum` and `hue_wave` cycle through hues.
 - **Splash** effects (`splash`, `multisplash`, `solid_splash`, `solid_multisplash`) react to key presses like reactive effects but with a splash pattern. `solid_splash` and `solid_multisplash` honor `color`.
 - **Gradient** effects (`gradient_up_down`, `gradient_left_right`) create a color gradient across the keyboard. They do not honor `color`.
 - **Alphas mods** (`alphas_mods`) colors modifier keys differently from alphanumeric keys. The colors are built-in and cannot be changed.
 
 To set a permanent color, use `solid_color` and then `color <hex>`.
 
+The `logo` and `side` catalogs hold only seven effects each, and the color you
+set is shown by three of them: `fixed_wave`, `breathing` and `light`. `wave`,
+`spectrum` and `shutdown` run their own color sequence, so a color set on them is
+stored but not displayed.
+
 ## Compatibility Aliases
 Effect names are resolved independently for each target zone. Compatibility
 aliases are `off` → `none`, `breathe` → `breathing`, `rainbow` → `spectrum`
@@ -360,7 +378,7 @@ Two models are listed in `keyboards.json`:
 | `qmk-rgb-tool effect <name>`          | Set a zone-aware effect by name           |
 | `qmk-rgb-tool effect --list`          | List every effect per zone (JSON)         |
 | `qmk-rgb-tool brightness <val>`       | Set brightness (0–255) on selected zones, verified by read-back |
-| `qmk-rgb-tool speed <val>`            | Set effect speed (0–255) on selected zones, verified by read-back |
+| `qmk-rgb-tool speed <val>`            | Set effect speed (0–255) on selected zones, verified by read-back; on `logo` and `side` only 0, 1 and 4 are reachable |
 | `qmk-rgb-tool color <hex>`            | Set color (e.g. `ff0000`) on selected zones |
 | `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 |