docs: document pearl-mode and the completed keymap

I replaced the old save/edit/new/delete prefix writeup with pearl-mode, which auto-enables in Linear buffers, and the full scheme: the hot keys directly under the prefix plus the fetch, edit, new, delete, and url groups.

1 files changed, 26 insertions, 7 deletions

diff --git a/README.org b/README.org
index 6dd3b92..cb3802e 100644
--- a/README.org
+++ b/README.org
@@ -150,19 +150,38 @@ Pearl writes one active Org file. Running a different query or view replaces tha
   (global-set-key (kbd "C-c L") #'pearl-menu)
 #+end_src
 
-*** Prefix keymap
+*** Prefix keymap and pearl-mode
 
-For muscle memory, Pearl also defines an opt-in prefix keymap, =pearl-prefix-map=, organized as save / edit / new / delete. It is not bound at load -- a global multi-key prefix isn't reliably free across terminals and GUIs, so you bind it to a prefix that suits your setup. A suggested binding:
+Pearl is fully keyboard-drivable. =pearl-mode=, a minor mode, turns on automatically in any buffer Pearl renders (it detects the =#+LINEAR-SOURCE= header) and binds the command keymap under =pearl-keymap-prefix= (default =C-; L=). So in a fetched buffer the keys are live with no setup. Change the prefix, or turn it off, with:
 
 #+begin_src emacs-lisp
-  (global-set-key (kbd "C-; L") pearl-prefix-map)
-  ;; or, with use-package:
-  ;; :bind-keymap ("C-; L" . pearl-prefix-map)
+  (setq pearl-keymap-prefix "C-c l")   ; or nil to bind nothing
 #+end_src
 
-With that prefix, =C-; L s s= saves the ticket at point, =C-; L s a= saves every ticket in the file, =C-; L e s= picks its state, =C-; L n t= creates a ticket, and =C-; L m= opens the full transient. If you use =which-key=, each step shows a labeled menu.
+The hot-path commands sit one key under the prefix; the rest are grouped into category sub-maps. The common ones appear in both places, so =d= and =e d= both edit the description.
+
+| Key       | Command                                                              |
+|-----------+----------------------------------------------------------------------|
+| =l=         | list my open issues                                                  |
+| =g=         | refresh the view                                                     |
+| =r=         | refresh the issue at point                                           |
+| =s= / =S=     | save the ticket at point / save every ticket in the file             |
+| =d=         | edit the description                                                  |
+| =c=         | add a comment                                                        |
+| =m=         | open the full transient menu                                         |
+| =f= ...     | fetch: =o= open issues, =p= by project, =f= filter, =v= view, =q= saved query  |
+| =e= ...     | edit: =d= description, =s= state, =a= assignee, =l= labels, =c= comment         |
+| =n= ...     | new: =t= ticket, =c= comment                                             |
+| =k= ...     | delete: =t= ticket, =c= comment                                          |
+| =u= ...     | url: =o= open issue in browser, =v= open view in Linear                  |
+
+To reach the map outside a Pearl buffer, bind it globally as well:
+
+#+begin_src emacs-lisp
+  (global-set-key (kbd "C-; L") pearl-prefix-map)
+#+end_src
 
-Every command is also available directly through =M-x=.
+With =which-key=, each step shows a labeled menu. Every command is also available through =M-x=.
 
 *** Fetching and refreshing