Likely cause, next action, and a link to the detailed guide when recovery needs more than a short answer.
Keyboard Helper needs Input Monitoring to observe keys globally; Accessibility alone is not enough. Quit the app, remove stale Keyboard Layout or Keyboard Helper entries in System Settings > Privacy & Security > Input Monitoring, add the current app from /Applications, enable it, and restart.
The preview builds are ad-hoc-signed and unnotarized. Open the app once, then use System Settings > Privacy & Security > Open Anyway. Follow the complete first-launch flow.
Closing the overlay hides it to the system tray instead of quitting. Restore it from the tray menu, use the configured show/hide hotkey, or launch the executable with --toggle.
Open Settings, enable the layouts you want, and use Add layout file... for an external JSON definition. See desktop layout configuration for examples.
The active layout needs valid bleLayerSource metadata and the desktop app needs Bluetooth access. Wake the keyboard, verify the UUIDs and permission, then choose Connection > Reconnect BLE. See BLE layer-sync setup.
The likely cause is a signer mismatch between a local debug build and the signed preview. Uninstall the debug app once, then install the verified release; private imports and permission state may reset. Follow Android installation and signature recovery.
Nearby devices permission, Android pairing, or an available ZMK Bluetooth profile is probably missing. Grant permission, pair in system Settings, wake the keyboard, and retry. For PIN, security, capacity, and reconnect branches, use Android troubleshooting.
Stock firmware does not provide Live telemetry. With compatible enhanced firmware, press a key or change a physical layer and reconnect if waiting persists; select a matching layout after a mismatch. Live is read-only and never changes the remote layer. See the Live contract.
The JSON or one of its embedded images failed validation, or a stored record became unavailable. Check the document version and resource limits; the companion keeps the current catalog on rejection and repairs invalid selection to the bundled default. See custom-layout format, storage, replacement, and recovery.
This feature is macOS-only and requires valid inputSourceSync.macos metadata, installed input-source IDs, and a compatible writable BLE layer characteristic. An unavailable source is disabled instead of guessed. See macOS language-sync setup.
Use the Restore full size arrow in the mini overlay. Mini Mode is temporary, so a fresh launch starts in full mode.
Self-test verifies configured HID output for one layout layer in the global event stream. It cannot identify the physical keyboard, activate firmware layers, or diagnose raw matrix wiring, combos, macros, or hold-tap timing.
The game uses focused window input and accepts plain English letters. It intentionally ignores modifiers, repeats, composition input, releases, and unsupported printable characters; global overlay highlighting may continue independently.
No. Bundled layouts include standard and ergonomic keyboards. Desktop can load an external JSON file; Android can copy a validated compatible JSON definition into private app storage. The two products do not synchronize layouts through desktop or cloud services.