# 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
- ⚠️ Automated implementation is complete; hardware smoke acceptance is pending. The last observed raw device was `/dev/hidraw7` (`root:root`, mode `600`); it later disappeared, so use the currently discovered path.

## 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.

## Handoff Status

Implementation is complete on `feature/impact80-effects` at commit `62852e7`.
All task reviews and the final whole-branch code review passed. Automated
checks pass:

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

The only open acceptance item is the live hardware smoke sequence. At the last
attempt, discovery found the Impact 80 but HID access was denied; the device
then disappeared. Do not assume `/dev/hidraw7`; run `keyboard info` after
connecting the keyboard and use the path it reports.

### Continue With Hardware

1. Check out `feature/impact80-effects` and build `/tmp/wobkey`.
2. Connect the Impact 80 and run `/tmp/wobkey keyboard info`.
3. Verify the current hidraw path and grant access using the system’s existing
   device-permission policy. If temporary access is explicitly chosen, record
   the original mode and restore it after testing.
4. Run the smoke commands in the Verification section above.
5. Confirm the default unsupported-zone warning, explicit Backlight effect,
   three-zone `rgb info` JSON, and final enabled state.
6. Record the hardware result here, rerun the automated checks, and only then
   merge the feature branch into `main`.

Do not stage `graphify-out/` unless explicitly requested.