Easy way to make desktop shortcuts to almost anything added.

README.md

@@ -126,6 +126,18 @@ Press the configured desktop shortcut, Mod+Control+D (Super+Control+D or Alt+Con
 
 Quick-launch shortcut entries come from `~/.config/i3/desktop_shortcuts`. They are not deleted from disk by the desktop dialog.
 
+### Creating desktop shortcuts
+
+Enter Ratpoison Mode, then press Control+Alt+D to open **I38 Create Desktop Shortcut**. Choose **Add from Clipboard**, **Browse for File**, **Browse for Folder**, or **Search for Application**. You can also type an absolute path such as `/usr/bin/firefox`, a home-relative path such as `~/Documents`, a program name on PATH, or a complete HTTP/HTTPS URL in the Target field, then press Enter. Copy one item at a time; copying a file in a file manager and copying its path as text both work. Copied files are left in place, including files marked for cutting.
+
+Review the suggested shortcut name, edit it if desired, then choose **Create Shortcut**. Web links use the page title when available, with the site hostname as a fallback. The title lookup runs in the background with a size limit and short network timeouts, without browser cookies or JavaScript. It never replaces a name you have edited. Files open in their default application, folders open in I38's selected file manager, and executable programs run directly. For command-line programs, select **Run program in a terminal**. Target accepts a program or path, rather than a shell command with arguments.
+
+Application search lists registered visible applications, including user and system application launchers, with case-insensitive name-prefix filtering like the desktop dialog. Type to search and press Down to move into the list; press Enter to select an application. The shortcut launches the original `.desktop` entry, preserving its terminal, working-directory, D-Bus, and launch options. Keep that original entry available. You can also browse to or paste a `.desktop` file directly.
+
+Shortcuts are ordinary `.desktop` files in the XDG desktop directory (normally `~/Desktop`). Existing items are never overwritten; repeated names get numbered filenames. Tab and Shift+Tab move between controls, and Escape closes the dialog. Deleting a created shortcut through I38 Desktop removes only the shortcut file.
+
+After updating an existing installation, regenerate your I38 configuration to add the new Ratpoison binding; `./i38.sh -u` copies scripts but does not add bindings. Review your configuration preferences before regeneration. Then reload i3 with `i3-msg reload`, or enter Ratpoison Mode and press Control+semicolon, to activate the new binding in the running session.
+
 ## Dependency Helpers
 
 Distro-specific dependency helpers live in `extra/`. On Arch Linux, run:
@@ -150,6 +162,14 @@ git config --local core.hooksPath .githooks
 The pre-commit hook rejects staged Python cache files. The I38 script installer
 also excludes and removes Python cache artifacts when copying `scripts/`.
 
+Shortcut regression tests use Python's unittest, PyGObject, and `desktop-file-validate` (desktop-file-utils). Run `python3 -B -m unittest discover -s tests -v`; its page-title tests start a temporary localhost HTTP server. For native GTK and clipboard checks, also install Xvfb and xclip, then run:
+
+```bash
+xvfb-run -a dbus-run-session -- env -u AT_SPI_BUS_ADDRESS I38_PRIVATE_GUI_TEST=1 PYTHONDONTWRITEBYTECODE=1 python3 tests/native_shortcut_gui.py -v
+```
+
+The GUI test uses a separate display and session bus. It does not prove live speech or Braille. After reviewing the diff and regenerating your configuration, test the new Ratpoison binding, clipboard and browse sources, application search, edited names, and opening each shortcut type through I38 Desktop. Confirm that normal desktop prefix search and existing launchers still work, that repeated names preserve previous shortcuts, and that deleting a generated shortcut leaves its original target intact.
+
 ### AI-assisted contributions
 
 AI-assisted contributions are welcome.