readme

README.org

@@ -44,6 +44,84 @@
 - automatically appears in profiles; set it as default and you should be going
 - TODO - table of defined keys
 
+** BetterTouchTool
+
+Presets are stored as uncompressed JSON exports in
+=~/.config/bettertouchtool/=. Ansible installs BetterTouchTool and checks out
+dotfiles on initial setup; it does not import or continuously synchronize BTT
+settings. BTT continues to own its live configuration.
+
+*** Restore on a new Mac
+
+1. Install and start BetterTouchTool, activate your licence separately, and
+   grant the macOS permissions requested by BTT.
+2. If BTT already has configuration you want to keep, export those presets
+   before importing anything from dotfiles.
+3. Open the Presets interface (top-right preset button) and import
+   =Default.bttpreset= from =~/.config/bettertouchtool/=. Use Cmd+Shift+G in the
+   file picker to enter this hidden directory. This export includes BTT's
+   exportable general settings, including window move/resize preferences.
+   Allow importing these settings when prompted.
+4. Import =clipboard.bttpreset=, =BTT Clipboard Manager.bttpreset= and
+   =btt-mobile-example.bttpreset= from the same directory. These exports do not
+   include general settings.
+5. Select the imported =Default= as the master preset and enable all four
+   imported presets to reproduce the source setup. Avoid keeping duplicate
+   copies enabled; if a preset with the same name already exists, review the
+   import/replacement prompt rather than blindly adding another copy.
+6. Check the window move/resize preferences and test them on an ordinary
+   window. Test a configured browser gesture (for example, a Firefox TipTap
+   gesture), and check the clipboard manager and mobile menus if you use them.
+   Clipboard history is not restored.
+
+The snapshot was exported from BTT 5.750 on 2026-09-25. The source master is
+=Default= (activation state 2); =clipboard=, =BTT Clipboard Manager= and
+=btt-mobile-example= have activation state 1. The =clipboard= preset currently
+contains app scopes but no triggers; it is retained to preserve the setup.
+
+*** Update the exports
+
+After changing BTT settings, export the affected presets again from BTT's
+Presets interface to the same filenames. Choose uncompressed JSON; include
+general settings only in =Default.bttpreset=. Re-export =Default= when changing
+general preferences, even if no shortcuts changed. Preserve the names above
+and update this section if the master or enabled presets change.
+
+Before adding exports to Git, review the diff for passwords, API keys, private
+paths, typed-text actions and scripts. Remove =BTTFloatingMenuRenderedPreview=
+fields from JSON exports: these are cached menu snapshots, not configuration.
+Validate the resulting JSON, for example:
+
+#+begin_src sh
+  python3 -m json.tool ~/.config/bettertouchtool/Default.bttpreset >/dev/null
+  config diff -- .config/bettertouchtool README.org
+#+end_src
+
+New files must be added explicitly with the existing =config= Git alias.
+Exports may receive new preset UUIDs, so inspect import prompts on subsequent
+restores and ensure only one intended copy of each preset is enabled.
+Do not add BTT's Application Support directory, preferences plist, clipboard
+database, licences, automatic backups or user-variable stores to Git.
+
+*** Portability notes
+
+- App-specific bindings target iTerm2, Finder, Firefox and Microsoft Edge;
+  install the relevant apps before testing those bindings. The mobile example
+  also includes Safari actions. Hardware-specific gestures and window geometry
+  may need adjustment for a different keyboard, pointing device or display.
+- No user-specific absolute paths were found in these exports. The mobile
+  example contains JavaScript menu widgets and a =say hello= shell action;
+  import only trusted presets and review scripts before enabling them.
+- Two custom mobile-menu images are already absent from the source Mac:
+  =AE909FCE-DACE-4774-823D-36F7C2864EB5-BTTMenuItemImage.png= and
+  =ED4B7AB4-D7E6-474C-B4A4-7BDCA93F25DB-BTTMenuItemImage.png=.
+  Their =BTT_PRESET_PATH= references remain in the export, but those icons
+  cannot be restored from this snapshot. Re-select images in BTT if needed.
+- Cached rendered menu previews are intentionally omitted. The clipboard
+  presets contain configuration only, not copied text or clipboard history.
+
+See [[https://docs.folivora.ai/docs/configuration/presets][BTT's preset documentation]] for export/import behaviour.
+
 ** fonts
 For iTerm on mac, the preferred fonts are installed automatically.
 You can also download fonts like this: