@@ -1,76 +1,7 @@
 # xx-hotkey
 
-A revision of [`vicinae-hotkey`](../../staging/vicinae-hotkey/) prepared for the
-`experimental/` track of wayland-protocols. Same goal — an application binds its
-own global hotkeys — with a different shape.
+A reworked [`vicinae-hotkey`](../../staging/vicinae-hotkey/) aimed at the
+`experimental/` track of wayland-protocols.
 
-The two are **parallel, not sequential**. `vicinae-hotkey-v1` is what Hyprland,
-Ghostty and Vicinae ship today and cannot change without breaking them.
-`xx-hotkey-v1` is the upstream proposal. They are not wire-compatible.
-
-## At a glance
-
-```c
-xx_hotkey_manager_v1_set_app_id(manager, "com.example.app");
-
-struct xx_hotkey_v1 *hotkey =
-    xx_hotkey_manager_v1_create_hotkey(manager, "toggle-launcher");
-xx_hotkey_v1_add_listener(hotkey, &listener, NULL);
-
-xx_hotkey_v1_set_description(hotkey, "Toggle the launcher");
-xx_hotkey_v1_set_key_trigger(hotkey, XKB_KEY_space,
-                             XX_HOTKEY_MANAGER_V1_MODIFIERS_SUPER);
-xx_hotkey_v1_commit(hotkey);
-```
-
-Runnable client in [`../../examples/xx-hotkey-demo.c`](../../examples/xx-hotkey-demo.c).
-
-## What changed, and why
-
-**A builder instead of one `bind` call.** With three trigger kinds and a name to
-carry, a single request would take seven arguments and grow one more each time a
-trigger kind is added. Building state and applying it with `commit` also gives
-somewhere for protocol errors to live.
-
-**`commit` is repeatable.** Committing again changes the trigger while keeping
-the binding's identity, so reconfiguring no longer means destroying and
-recreating the object. A denied commit leaves the previous binding active, so a
-rejected reconfiguration never leaves the user with no hotkey.
-
-**A stable `name`.** A machine-readable identifier distinct from the localized
-description, so a client can correlate a binding with its own configuration. It
-is a `create_hotkey` argument rather than a setter, being mandatory and
-immutable.
-
-**Pointer buttons and modifier-only taps.** A key was the only possible trigger
-before. Buttons use the `wl_pointer.button` code space. A modifier-only trigger
-fires on release, and only if nothing else was pressed, which is the
-tap-Super-to-launch idiom; for press-and-hold on a modifier, bind its keysym as
-a key trigger instead.
-
-**`app_id` moved to the manager.** It identifies the connection, not each
-binding. Setting it per hotkey meant repeating one string, and let a client
-claim two identities.
-
-**Protocol errors.** `invalid_trigger` and `no_trigger` on the hotkey,
-`invalid_app_id` and `invalid_name` on the manager. The builder makes illegal
-orderings expressible, so they need to be defined.
-
-**RFC 2119 boilerplate**, lowercase keywords, and the `experimental/` disclaimer
-rather than the `staging/` one.
-
-## Boundaries
-
-Two things this deliberately does not do, both because they would require the
-compositor to store the user's trigger assignments:
-
-- **The compositor never originates or reassigns a binding.** It answers a
-  commit with `bound` or `denied` and may later `revoke`, but never substitutes
-  a trigger of its own. Compositor-assigned, persisted shortcuts are what the
-  desktop portal's GlobalShortcuts interface is for.
-- **Nothing is persisted.** A binding lives as long as its object and the client
-  connection. Compositor state is limited to policy, which it may persist freely.
-
-There is also no request to refuse a client outright: a compositor that does not
-want a client to have hotkeys should not advertise the global to it, as with
-other restricted protocols.
+See [`xx-hotkey-v1.xml`](xx-hotkey-v1.xml) and the client in
+[`../../examples/xx-hotkey-demo.c`](../../examples/xx-hotkey-demo.c).