document shell completion for bash and zsh

Add a Shell Completion section to the README with the user-scoped
install paths that need no sudo, plus a CLI reference row. The
generated scripts are installed on this machine.

README.md

@@ -26,6 +26,35 @@ And, to run it from anywhere, install globally (run from the repo root, installs
 go install ./cmd/qmk-rgb-tool/
 ```
 
+## Shell Completion
+
+`completion` writes an autocompletion script to stdout for `bash`, `zsh`,
+`fish` or `powershell`. Each of those subcommands also accepts
+`--no-descriptions` to complete without description text. Run
+`qmk-rgb-tool completion <shell> --help` for the path your platform expects;
+for bash and zsh on Linux:
+
+```bash
+# bash: bash-completion 2.x loads this directory, so no sudo is needed
+mkdir -p ~/.local/share/bash-completion/completions
+qmk-rgb-tool completion bash > ~/.local/share/bash-completion/completions/qmk-rgb-tool
+
+# zsh: the file name must start with an underscore
+mkdir -p ~/.zsh/completions
+qmk-rgb-tool completion zsh > ~/.zsh/completions/_qmk-rgb-tool
+```
+
+zsh does not include that directory in `$fpath` by default, so add it and
+re-run `compinit` in `~/.zshrc`:
+
+```zsh
+fpath=("$HOME/.zsh/completions" $fpath)
+autoload -Uz compinit && compinit
+```
+
+Open a new shell afterwards. The script is generated from the command tree, so
+re-run the command whenever commands or flags change.
+
 ## Usage
 
 ```bash
@@ -305,6 +334,7 @@ Two models are listed in `keyboards.json`:
 | `qmk-rgb-tool load [name]`            | Load and apply a profile from `profiles/` |
 | `qmk-rgb-tool list`                   | List saved profiles                        |
 | `qmk-rgb-tool delete [name]`          | Delete a saved profile                     |
+| `qmk-rgb-tool completion <shell>`     | Write an autocompletion script for `bash`, `zsh`, `fish` or `powershell` to stdout |
 
 `enable`, `disable`, `info` and `list` take no arguments and reject a stray
 token. `effect`, `load`, `save` and `delete` accept an optional name.

graphify-out/.graphify_labels.json

@@ -1,20 +1,20 @@
 {
   "0": "device.go",
-  "1": "impact80.go",
+  "1": "impact80_test.go",
   "2": "LEDType",
   "3": "Zone",
   "4": "profile.go",
   "5": "hid.go",
-  "6": "effects.go",
+  "6": "selectedZones",
   "7": "What You Must Do When Invoked",
   "8": "testing.T",
-  "9": "info.go",
+  "9": "protocol.go",
   "10": "graphify.js",
   "11": "opencode.json",
   "12": "netdome.biz/paul/qmk-rgb",
   "13": "Agent Guidelines — QMK RGB Tool",
   "14": "QMK RGB Tool",
-  "15": "profile_list_test.go",
+  "15": "fakeTransport",
   "16": "/qmk-rgb",
   "18": "Wobkey RGB CLI — Implementation Plan",
   "19": "graphify reference: extra exports and benchmark",

graphify-out/.graphify_labels.json.sig

@@ -1 +1 @@
-{"0": "5eb2aee84ae41281", "1": "55cd28c722b74dd2", "2": "36064429c53b3c7b", "3": "d3cb1ed145106986", "4": "590768dab907717e", "5": "ff52ca60688da8f3", "6": "11d9edfc3cac9a3a", "7": "62ad613386e8444e", "8": "6e5ececc80511dd7", "9": "8442965ea1d80930", "10": "d71acd1404975569", "11": "72bfef5ec64c0453", "12": "b02bb4f6a81f508d", "13": "0d6a073c9d58dc6a", "14": "b2c5b9e711ad4492", "15": "408fe73755518abb", "16": "dd6301fddcde8ab6", "18": "90bf6b690d2e10c9", "19": "c4abf0eb38ef740d", "20": "75efc6457f7fce22", "21": "be62daa7d5bc336a", "22": "47c3e1a9d4bb7e67", "23": "82ff39c105ae3090", "25": "54f53e5e0cc8c385", "26": "821696b1ff49347b", "27": "6e7b82d0387bf16d", "28": "2eef246ebb269184", "29": "f5edd0761d024ff0"}
+{"0": "c878defc3e224436", "1": "e61d292d563a81be", "2": "1d628118ca997411", "3": "b4ac981a03641832", "4": "b781f0b5c26b207b", "5": "ff52ca60688da8f3", "6": "b3a02b33643d9ecb", "7": "62ad613386e8444e", "8": "6851484a2fd1132b", "9": "40162314560b5b0a", "10": "d71acd1404975569", "11": "72bfef5ec64c0453", "12": "b02bb4f6a81f508d", "13": "0d6a073c9d58dc6a", "14": "8308ceec7056561d", "15": "4e14c482a212286a", "16": "dd6301fddcde8ab6", "18": "90bf6b690d2e10c9", "19": "c4abf0eb38ef740d", "20": "75efc6457f7fce22", "21": "be62daa7d5bc336a", "22": "47c3e1a9d4bb7e67", "23": "82ff39c105ae3090", "25": "54f53e5e0cc8c385", "26": "821696b1ff49347b", "27": "6e7b82d0387bf16d", "28": "2eef246ebb269184", "29": "f5edd0761d024ff0"}

graphify-out/GRAPH_REPORT.md

@@ -1,37 +1,37 @@
 # Graph Report - qmk-rgb  (2026-09-27)
 
 ## Corpus Check
-- 63 files · ~33,138 words
+- 63 files · ~33,290 words
 - Verdict: corpus is large enough that graph structure adds value.
 - Unclassified: 3 file(s) not represented in the graph (top: (none) 3)
 
 ## Summary
-- 468 nodes · 1112 edges · 28 communities (21 shown, 7 thin omitted)
+- 469 nodes · 1113 edges · 28 communities (20 shown, 8 thin omitted)
 - Extraction: 87% EXTRACTED · 13% INFERRED · 0% AMBIGUOUS · INFERRED: 142 edges (avg confidence: 0.85)
 - Token cost: 0 input · 0 output
 
 ## Graph Freshness
-- Built from commit: `407d52b7`
+- Built from commit: `664037b6`
 - Run `git rev-parse HEAD` and compare to check if the graph is stale.
 - Run `graphify update .` after code changes (no API cost).
 
 ## Community Hubs (Navigation)
 - device.go
-- impact80.go
+- impact80_test.go
 - LEDType
 - Zone
 - profile.go
 - hid.go
-- effects.go
+- selectedZones
 - What You Must Do When Invoked
 - testing.T
-- info.go
+- protocol.go
 - graphify.js
 - opencode.json
 - netdome.biz/paul/qmk-rgb
 - Agent Guidelines — QMK RGB Tool
 - QMK RGB Tool
-- profile_list_test.go
+- fakeTransport
 - /qmk-rgb
 - Wobkey RGB CLI — Implementation Plan
 - graphify reference: extra exports and benchmark
@@ -50,14 +50,16 @@
 2. `LEDType` - 31 edges
 3. `selectedZones()` - 22 edges
 4. `AllZones()` - 17 edges
-5. `ResolveEffect()` - 15 edges
-6. `QMK RGB Tool` - 15 edges
+5. `QMK RGB Tool` - 16 edges
+6. `ResolveEffect()` - 15 edges
 7. `init()` - 13 edges
 8. `NewBrightnessCmd()` - 12 edges
 9. `OpenDevice()` - 12 edges
 10. `selectDevice()` - 12 edges
 
 ## Surprising Connections (you probably didn't know these)
+- `deviceInfoOutput` --references--> `Device`  [EXTRACTED]
+  cmd/qmk-rgb-tool/keyboard_info_test.go → internal/device/device.go
 - `runBrightness()` --references--> `LEDType`  [EXTRACTED]
   cmd/qmk-rgb-tool/brightness_summary_test.go → internal/via/protocol.go
 - `appliedFor()` --references--> `LEDType`  [EXTRACTED]
@@ -66,41 +68,39 @@
   cmd/qmk-rgb-tool/brightness_verify_test.go → internal/rgb/impact80.go
 - `NewColorCmd()` --calls--> `ParseHexColor()`  [EXTRACTED]
   cmd/qmk-rgb-tool/color.go → internal/rgb/effects.go
-- `TestSelectedChannelStopsOnFirstError()` --calls--> `AllZones()`  [EXTRACTED]
-  cmd/qmk-rgb-tool/commands_test.go → internal/rgb/impact80.go
 
 ## Import Cycles
 - None detected.
 
-## Communities (28 total, 7 thin omitted)
+## Communities (28 total, 8 thin omitted)
 
 ### Community 0 - "device.go"
-Cohesion: 0.10
-Nodes (38): runRealKeyboardInfo(), stubDiscovery(), TestKeyboardInfoEmitsEmptyArrayNotNull(), TestKeyboardInfoEmitsIndentedJSON(), TestKeyboardInfoPropagatesDiscoveryError(), TestKeyboardInfoWritesOnlyJSON(), formatDeviceList(), selectDevice() (+30 more)
+Cohesion: 0.13
+Nodes (30): formatDeviceList(), selectDevice(), testDevices(), TestFormatDeviceList(), TestSelectDeviceByIndex(), TestSelectDeviceEmptySelectorRejectsMultiple(), TestSelectDeviceEmptySelectorRejectsNone(), TestSelectDeviceEmptySelectorRequiresSingle() (+22 more)
 
-### Community 1 - "impact80.go"
-Cohesion: 0.10
-Nodes (35): listAllEffects(), NewEffectCmd(), resolveEffectTargets(), runEffectSet(), executeEffectCommand(), TestEffectCommandRejectsBeforeOpeningProtocol(), TestEffectCommandSuppressesSuccessAfterLaterWriteFailure(), TestEffectCommandWarnsForSkippedZones() (+27 more)
+### Community 1 - "impact80_test.go"
+Cohesion: 0.15
+Nodes (24): TestSelectedChannelStopsOnFirstError(), resolveEffectTargets(), executeEffectCommand(), TestEffectCommandRejectsBeforeOpeningProtocol(), TestEffectCommandSuppressesSuccessAfterLaterWriteFailure(), TestEffectCommandWarnsForSkippedZones(), TestResolveEffectTargetsBacklightOnly(), TestResolveEffectTargetsBreathing() (+16 more)
 
 ### Community 2 - "LEDType"
-Cohesion: 0.10
-Nodes (11): TestSelectedChannelStopsOnFirstError(), LEDType, Protocol, New(), commandReport, fakeInfoProtocol, fakeZoneProtocol, infoKey (+3 more)
+Cohesion: 0.11
+Nodes (18): getInfoValue(), readInfo(), readZoneInfo(), TestInfoCommandPrintsJSONBeforeReturningError(), TestInfoErrorRecord(), TestInfoSuccessfulRecord(), lightingEnabled(), TestLightingEnabledRequiresActiveEffectAndBrightness() (+10 more)
 
 ### Community 3 - "Zone"
-Cohesion: 0.21
-Nodes (20): TestSelectedChannelOperations(), anyMismatch(), disableLightingOnZones(), enableLightingOnZones(), forEachSelectedZone(), setBrightnessOnZones(), setBrightnessVerified(), setColorOnZones() (+12 more)
+Cohesion: 0.11
+Nodes (36): TestOneArgCommandsKeepTheirArity(), NewBrightnessCmd(), TestSelectedChannelOperations(), NewModeCmd(), anyMismatch(), disableLightingOnZones(), enableLightingOnZones(), forEachSelectedZone() (+28 more)
 
 ### Community 4 - "profile.go"
 Cohesion: 0.10
-Nodes (39): TestOneArgCommandsKeepTheirArity(), TestZeroArgCommandsAcceptNoArgs(), TestZeroArgCommandsRejectStrayTokens(), NewBrightnessCmd(), NewColorCmd(), NewDisableCmd(), NewEnableCmd(), NewInfoCmd() (+31 more)
+Nodes (34): TestZeroArgCommandsAcceptNoArgs(), TestZeroArgCommandsRejectStrayTokens(), NewColorCmd(), NewDisableCmd(), listAllEffects(), NewEffectCmd(), runEffectSet(), NewEnableCmd() (+26 more)
 
 ### Community 5 - "hid.go"
 Cohesion: 0.18
 Nodes (12): go_pkg_github_com_sstallion_go_hid, go_pkg_sync, go_pkg_time, Device, DeviceInfo, DevicesInfo, DiscoverAll(), ensureInit() (+4 more)
 
-### Community 6 - "effects.go"
-Cohesion: 0.19
-Nodes (12): sameZones(), TestFilterZonesDoesNotAddMissingZones(), TestFilterZonesDoesNotMutateInput(), TestFilterZonesKeepsOnlyTheSelection(), filterZones(), go_pkg_math, ParseEffect(), ParseHexColor() (+4 more)
+### Community 6 - "selectedZones"
+Cohesion: 0.11
+Nodes (24): sameZones(), TestFilterZonesDoesNotAddMissingZones(), TestFilterZonesDoesNotMutateInput(), TestFilterZonesKeepsOnlyTheSelection(), TestDeviceFlagIsInheritedByCommands(), TestSelectedZonesDefaultsToAll(), TestSelectedZonesExplicitZones(), TestSelectedZonesRejectsUnknownZone() (+16 more)
 
 ### Community 7 - "What You Must Do When Invoked"
 Cohesion: 0.08
@@ -108,11 +108,11 @@ Nodes (24): For /graphify add and --watch, For /graphify query, For the commit h
 
 ### Community 8 - "testing.T"
 Cohesion: 0.06
-Nodes (60): TestAgentsDocDoesNotDuplicateTheCommandTable(), TestAgentsDocDoesNotDuplicateTheEffectCatalog(), TestAgentsDocTellsAgentsToReadTheReadme(), runBrightness(), TestBrightnessReportsPlainMessageWhenAllZonesMatch(), TestBrightnessSummarisesAppliedValuesOnMismatch(), TestBrightnessSummarisesASingleMismatchingZone(), TestBrightnessSummaryNamesOnlySelectedZones() (+52 more)
+Nodes (57): TestAgentsDocDoesNotDuplicateTheCommandTable(), TestAgentsDocDoesNotDuplicateTheEffectCatalog(), TestAgentsDocTellsAgentsToReadTheReadme(), runBrightness(), TestBrightnessReportsPlainMessageWhenAllZonesMatch(), TestBrightnessSummarisesAppliedValuesOnMismatch(), TestBrightnessSummarisesASingleMismatchingZone(), TestBrightnessSummaryNamesOnlySelectedZones() (+49 more)
 
-### Community 9 - "info.go"
-Cohesion: 0.36
-Nodes (9): getInfoValue(), readInfo(), readZoneInfo(), lightingEnabled(), TestLightingEnabledRequiresActiveEffectAndBrightness(), infoColor, infoGetter, infoOutput (+1 more)
+### Community 9 - "protocol.go"
+Cohesion: 0.19
+Nodes (7): OpenDevice(), TestZoneValidationPrecedesDeviceOpening(), TestZoneValidationRunsBeforeCommandOpener(), Protocol, New(), Message, transport
 
 ### Community 10 - "graphify.js"
 Cohesion: 0.40
@@ -123,12 +123,8 @@ Cohesion: 0.10
 Nodes (19): Agent Guidelines — QMK RGB Tool, Architecture, Code vs Documentation, Concurrency, Consistency, Constraints, Device Selection, Error Handling (+11 more)
 
 ### Community 14 - "QMK RGB Tool"
-Cohesion: 0.10
-Nodes (20): Architecture, Brightness and Speed Are Not Applied Verbatim, CLI Reference, Compatibility Aliases, Effect Behavior, Features, Impact 80 Zones and Effects, Installation (+12 more)
-
-### Community 15 - "profile_list_test.go"
-Cohesion: 0.46
-Nodes (7): runProfileList(), TestProfileListEmitsJSONWithoutProfiles(), TestProfileListEmitsJSONWithProfiles(), TestProfileListUsesTheSharedJSONShape(), withProfilesDir(), go_pkg_path_filepath, profileListOutput
+Cohesion: 0.09
+Nodes (21): Architecture, Brightness and Speed Are Not Applied Verbatim, CLI Reference, Compatibility Aliases, Effect Behavior, Features, Impact 80 Zones and Effects, Installation (+13 more)
 
 ### Community 16 - "/qmk-rgb"
 Cohesion: 0.15
@@ -159,24 +155,24 @@ Cohesion: 0.50
 Nodes (3): For --cluster-only, For --update (incremental re-extraction), graphify reference: incremental update and cluster-only
 
 ## Knowledge Gaps
-- **99 isolated node(s):** `$schema`, `plugin`, `profileListOutput`, `netdome.biz/paul/qmk-rgb`, `LEDParam` (+94 more)
-  These have ≤1 connection - possible missing edges or undocumented components. (Counts symbols only; 144 node(s) total have ≤1 connection when file, concept and rationale nodes are included.)
-- **7 thin communities (<3 nodes) omitted from report** — run `graphify query` to explore isolated nodes.
+- **100 isolated node(s):** `$schema`, `plugin`, `profileListOutput`, `netdome.biz/paul/qmk-rgb`, `LEDParam` (+95 more)
+  These have ≤1 connection - possible missing edges or undocumented components. (Counts symbols only; 145 node(s) total have ≤1 connection when file, concept and rationale nodes are included.)
+- **8 thin communities (<3 nodes) omitted from report** — run `graphify query` to explore isolated nodes.
 
 ## Suggested Questions
 _Questions this graph is uniquely positioned to answer:_
 
-- **Why does `LEDType` connect `LEDType` to `impact80.go`, `Zone`, `profile.go`, `testing.T`, `info.go`?**
+- **Why does `LEDType` connect `LEDType` to `testing.T`, `protocol.go`, `Zone`, `profile.go`?**
   _High betweenness centrality (0.049) - this node is a cross-community bridge._
-- **Why does `Zone` connect `Zone` to `impact80.go`, `profile.go`, `info.go`, `effects.go`?**
+- **Why does `Zone` connect `Zone` to `impact80_test.go`, `LEDType`, `profile.go`, `selectedZones`?**
   _High betweenness centrality (0.022) - this node is a cross-community bridge._
 - **Are the 3 inferred relationships involving `Zone` (e.g. with `TestImpact80DefaultEffects()` and `TestImpact80LogoAndSideCatalog()`) actually correct?**
   _`Zone` has 3 INFERRED edges - model-reasoned connections that need verification._
 - **Are the 18 inferred relationships involving `selectedZones()` (e.g. with `NewBrightnessCmd()` and `NewColorCmd()`) actually correct?**
   _`selectedZones()` has 18 INFERRED edges - model-reasoned connections that need verification._
 - **What connects `$schema`, `plugin`, `profileListOutput` to the rest of the system?**
-  _99 weakly-connected nodes found - possible documentation gaps or missing edges._
+  _100 weakly-connected nodes found - possible documentation gaps or missing edges._
 - **Should `device.go` be split into smaller, more focused modules?**
-  _Cohesion score 0.10077519379844961 - nodes in this community are weakly interconnected._
-- **Should `impact80.go` be split into smaller, more focused modules?**
-  _Cohesion score 0.09872241579558652 - nodes in this community are weakly interconnected._
+  _Cohesion score 0.1265597147950089 - nodes in this community are weakly interconnected._
+- **Should `impact80_test.go` be split into smaller, more focused modules?**
+  _Cohesion score 0.1452991452991453 - nodes in this community are weakly interconnected._

graphify-out/manifest.json

@@ -150,9 +150,9 @@
     "semantic_hash": ""
   },
   "README.md": {
-    "mtime": 1790471954.528755,
-    "seen": 1790471972.4078789,
-    "ast_hash": "c1acc99622a49cc32bb4c46578688d4e",
+    "mtime": 1790473278.901612,
+    "seen": 1790473285.1040707,
+    "ast_hash": "eb9b8b8e7cbcb6ee26fd19e868e00f16",
     "semantic_hash": ""
   },
   "internal/via/protocol_test.go": {