# Wobkey RGB CLI — Implementation Plan

## Status

- ✅ Go module initialized (`github.com/wobkey/rgb`)
- ✅ HID discovery and QMK v12 Raw HID transport implemented
- ✅ Impact 80 three-zone lighting control (Logo, Backlight, Side) implemented
- ✅ Zone selection with default-all and explicit `--zone` behavior implemented
- ✅ Zone-aware effect names, aliases, and target resolution implemented
- ✅ Per-zone `rgb info` JSON implemented
- ✅ All RGB subcommands implemented (effect, brightness, speed, color, mode, enable, disable, info)
- ✅ Automated tests, vet, formatting, and build verification
- ⚠️ Hardware smoke discovery succeeds, but the connected Impact 80 is blocked by root-only `/dev/hidraw7` permissions

## Zone-Aware Lighting Semantics

The `rgb` command has a persistent `--zone` flag with the values `logo`,
`backlight`, and `side`. Without the flag, commands target Logo, Backlight,
and Side in that order. With the flag, commands target exactly one zone.

An unknown effect name fails before the device is opened. An effect that is
unsupported by an explicitly selected zone also fails before the device is
opened. For a default all-zone request, supported zones receive the command
and unsupported zones are skipped with a warning on stderr.

The exact effect examples are:

```bash
wobkey rgb effect breathing
wobkey rgb effect rainbow_moving_chevron
wobkey rgb effect rainbow_moving_chevron --zone backlight
wobkey rgb brightness 160
wobkey rgb speed 2
wobkey rgb color 00ff00
```

## Effect Families

Logo and Side share the complete seven-name family:

```text
none, wave, fixed_wave, spectrum, breathing, light, shutdown
```

Backlight uses these complete 46 names, with IDs 0–45:

```text
none, solid_color, alphas_mods, gradient_up_down, gradient_left_right,
breathing, band_sat, band_val, band_pinwheel_sat, band_pinwheel_val,
band_spiral_sat, band_spiral_val, cycle_all, cycle_left_right,
cycle_up_down, cycle_out_in, cycle_out_in_dual, rainbow_moving_chevron,
cycle_pinwheel, cycle_spiral, dual_beacon, rainbow_beacon,
rainbow_pinwheels, flower_blooming, raindrops, jellybean_raindrops,
hue_breathing, hue_pendulum, hue_wave, pixel_flow, digital_rain,
solid_reactive, solid_reactive_wide, solid_reactive_multiwide,
solid_reactive_cross, solid_reactive_multicross, solid_reactive_nexus,
solid_reactive_multinexus, splash, multisplash, solid_splash,
solid_multisplash, starlight, starlight_dual_hue, starlight_dual_sat,
riverflow
```

Backlight ID 39 is `multisplash`; ID 41 is the distinct
`solid_multisplash` name. Compatibility aliases are `off`, `breathe`,
`rainbow`, `rainbow_wave`, `solid`, and the legacy `static` alias; aliases
resolve independently for each zone.

## Verification

Run the complete automated check set from the repository root:

```bash
gofmt -w .
go test -count=1 ./...
go vet ./...
go build -o /tmp/wobkey ./cmd/wobkey/
git diff --check
```

Run the hardware smoke sequence when the Impact 80 is available:

```bash
/tmp/wobkey keyboard info
/tmp/wobkey rgb effect breathing
/tmp/wobkey rgb effect rainbow_moving_chevron
/tmp/wobkey rgb effect rainbow_moving_chevron --zone backlight
/tmp/wobkey rgb info
/tmp/wobkey rgb color 00ff00
/tmp/wobkey rgb disable
/tmp/wobkey rgb enable
```

The expected result is three selected zones, warnings only for unsupported
default targets, a working explicit Backlight command, per-zone JSON from
`rgb info`, and a final enabled state. Record device or permission failures
without changing unrelated code.

## Open Issues

### Cross-Platform HID Backends

The current transport is Linux-specific (`/dev/hidraw*` and Linux syscalls).
macOS and Windows require platform-specific HID backends or a shared library.

### Hardware Environment

Hardware smoke tests require the Impact 80 to be connected and the user to
have permission to access its hidraw device. In the acceptance environment,
`/dev/hidraw7` is `root:root` with mode `600`, so discovery succeeds but all
HID opens fail with `permission denied`. No persistent profile storage or
EEPROM save command is included.