From e9d86b35f8a82a854d66dce0cccd0d6e370cfdc6 Mon Sep 17 00:00:00 2001
From: Levi Neely <lneely@pascom.net>
Date: Thu, 8 Oct 2026 20:05:02 +0200
Subject: [PATCH] docs(README): add per-plugin descriptions and usage guides

Add a 'The plugins' section with a short description and a defaults-based usage
guide for each of the six plugins: palette (M-x + the :-verb table + frecency),
switch (Go to File/Symbol, ctags, project scoping, cache), radial (open/choose
gestures + radials.json config), acme (line keys, pair select, mouse chords),
sam (tool view, Run, X/Y multi-file), and plumb (F2 send, edit port, fallback).
Trim the now-redundant usage prose from the install section and point it at the
new section.
---
 README.md | 107 +++++++++++++++++++++++++++++++++++++++++++++++++++---
 1 file changed, 101 insertions(+), 6 deletions(-)

diff --git a/README.md b/README.md
index c814a27..c9bf34a 100644
--- a/README.md
+++ b/README.md
@@ -75,18 +75,113 @@ done
 ```
 
 Then in Kate: Settings → Configure Kate → Plugins → enable each **`[deft:…]`**
-plugin you installed. Press **Alt+X** (M-x) to open the command palette; type to
-filter, Enter or click to run. Open the editing **radial menu** either by
-pressing **Alt+R** (opens at the caret) or by **pressing the right mouse button**
-in the editor (opens at the pointer; the normal context menu is suppressed while
-this is enabled). Move toward a slice and release — or click; a branch slice
-(marked ▸) opens a submenu, the centre hub goes back/cancels.
+plugin you installed. See [The plugins](#the-plugins) below for what each one
+does and how to drive it.
 
 The plugins cooperate but do not depend on one another: palette's "Go to
 File/Symbol" entries and radial's launcher slices resolve `switch`'s actions by
 object name at runtime, so each `.so` works on its own and simply gains those
 entry points when its sibling is also enabled.
 
+## The plugins
+
+Each plugin is independent — enable only what you want. Keys shown below are the
+defaults.
+
+### `[deft:util] palette` — command palette (M-x)
+
+A Sublime/Emacs-style launcher over **every action currently offered by the
+window**, matched with the orderless `FuzzyRanker` (space-separated tokens in
+any order, with typo tolerance) and ranked by *frecency* (frequency + recency of
+your past choices).
+
+- **Open:** `Alt+X`. Type to filter, `Enter` or click to run, `Esc` to dismiss.
+- Entries include all live menu/toolbar actions, the `:`-verbs below, and — when
+  `switch` is enabled — **Go to File** and **Go to Symbol**.
+- Usage is remembered in `~/.config/deft/palette.frecency.json`.
+
+It also registers a small pack of **`:` command-line verbs** (type `:` in Kate,
+or pick them from the palette). Each transforms the selection in place, or the
+whole document when nothing is selected:
+
+| Verb | Effect |
+|------|--------|
+| `osort [u] [i]` | sort selected lines (`u` = unique, `i` = case-insensitive) |
+| `rsort` | reverse the order of selected lines |
+| `case <style>` | recase: `upper` / `lower` / `title` / `snake` / `camel` / `kebab` |
+| `b64enc` / `b64dec` | Base64 encode / decode |
+| `rot13` | ROT13 |
+| `uuid` | insert a random UUID at the cursor |
+| `pipe <shell>` | replace the selection with the output of `sh -c <shell>` (selection on stdin) |
+
+> `sort` is registered as `osort` because Kate already ships a built-in `sort`;
+> the KTextEditor registry drops a whole command object if any one name
+> collides.
+
+### `[deft:util] switch` — project file & symbol switchers
+
+Jump within the active project without the file tree. The project scope is
+Kate's loaded project when present (via the Project plugin), otherwise it is
+discovered from the active document (VCS root, else its directory).
+
+- **Go to File** — `Alt+P`. Fuzzy-match the full project-relative path (files
+  come from VCS/discovery). `Enter`/click opens.
+- **Go to Symbol** — `Alt+G`. Fuzzy-match symbols indexed with **ctags**
+  (requires `ctags` on `PATH`); jumps to the definition.
+- The index is built asynchronously and cached; the palette opens instantly and
+  fills in (showing "Indexing…" on a cold project). It is invalidated when Kate
+  switches projects.
+- Rankings are remembered in `~/.config/deft/switch.frecency.json`.
+
+### `[deft:util] radial` — radial caret menu (mouse)
+
+A multi-level pie menu for actions that **complete in place** (cut, copy, paste,
+comment, case changes…), so the mouse stays at the text.
+
+- **Open:** `Alt+R` (at the caret) **or press the right mouse button** in the
+  editor (at the pointer; the normal context menu is suppressed while enabled).
+- **Choose:** move toward a slice and release, or click it. A branch slice
+  (marked ▸) opens a submenu; the centre hub goes back / cancels.
+- Slices can trigger any action by name, including `palette`/`switch` doors.
+- **Configure:** drop a `radials.json` at `~/.config/deft/radials.json` to
+  replace the built-in tree; when it is absent, empty, or invalid, the built-in
+  default is used.
+
+### `[deft:nineify] acme` — acme editing gestures
+
+Plan 9 *acme* muscle memory inside Kate. Installed as a filter so it never
+clashes with Kate's own bindings.
+
+- **Line keys:** `Ctrl+A` beginning of line, `Ctrl+E` end of line, `Ctrl+H`
+  erase char, `Ctrl+U` erase to line start, `Ctrl+W` erase previous word.
+- **Double-click** inside a bracket/quote pair selects the enclosed text.
+- **Mouse chords** (hold left, tap the other): left+middle = **Cut**,
+  left+right = **Paste**. X11 middle-click primary-paste is suppressed.
+
+### `[deft:nineify] sam` — structural regular expressions
+
+Run Plan 9 *sam* structural-regexp programs against your text — the expressive
+`x/re/`, `g/re/`, `s/re/txt/`, `,` dot-addressing model, not line-at-a-time
+find/replace.
+
+- Opens a dockable **Sam** tool view: a program editor, a **Run** button
+  (`Ctrl+Return`), and an output log.
+- Runs against the **active document**, or across open buffers with the
+  multi-file `X`/`Y` loop commands.
+- Edits are applied in a single undo transaction.
+
+### `[deft:nineify] plumb` — Plan 9 plumber
+
+Make Kate a first-class *plumb* client.
+
+- **Plumb under the caret:** `F2`. Sends the file-path token under the cursor
+  (or the selection, so `foo.cpp:42` works) through the plumber's **send** port,
+  resolved relative to the active document's directory.
+- Kate also holds the **edit** port open, so files/addresses plumbed from
+  elsewhere open here.
+- If no plumber is running, it falls back to opening the target directly (URLs
+  via the system handler, `path[:line]` in Kate).
+
 ## Status
 
 See [docs/PLAN.md](docs/PLAN.md) for the full roadmap.