docs: document grouping the current view

Phase 5 of the interactive-grouping spec: a "Grouping the current view" subsection in the README, next to "Sorting the current view". It covers pearl-set-grouping's dimensions, the client-side regroup and its drawer-read labels, edit preservation through the level shift, the client-over-server precedence on a Custom View, and why cycle is deferred.

Closes the build. The test surface was written test-first across phases 1 through 4 (35 tests), so there's no separate test commit.

1 files changed, 6 insertions, 0 deletions

diff --git a/README.org b/README.org
index d9bd19b..12b28a9 100644
--- a/README.org
+++ b/README.org
@@ -301,6 +301,12 @@ Sorting is local and deterministic. Query filters are AND-only; use a Linear Cus
 
 Priority and title sort the fetched issues in place: whole subtrees move by id, so unsaved edits survive, and the order sticks across a refresh. Updated and created refetch with the new server ordering. A Custom View has no server-side order in Linear's API, so =updated= / =created= are refused on a view -- sort it by priority or title instead, which still reorders the issues it returned. Sorting a grouped view in place isn't supported yet. Both commands are =M-x= for now. A key binding lands once the menu layout settles.
 
+*** Grouping the current view
+
+=pearl-set-grouping= sections the active view on demand, without setting up grouping in Linear and re-fetching. It asks for a dimension: =status=, =project=, =assignee=, =priority=, or =none= to ungroup. The regroup is client-side over the issues already in the buffer, so it's instant and works offline. Each issue's group comes from its drawer, and an issue with no value for the dimension lands in a "No status" / "No project" / "No assignee" bucket. The choice sticks across a refresh.
+
+Like sorting, the regroup moves whole subtrees so unsaved edits survive. Only the heading levels shift, since a grouped issue sits one level deeper under its group heading. On a Custom View that already carries its own grouping from Linear, your choice takes over for display, and =none= restores the view's configured grouping on the next refresh. =cycle= isn't offered yet: it isn't stored in the issue drawer, so an offline regroup can't read it. The command is =M-x= for now, with a key binding to come.
+
 *** Editing issues
 
 Pearl has one write path. Edit an issue however you like in the buffer, then save it -- Pearl diffs each field against what it last fetched and pushes only what changed. Nothing pushes the moment you pick a value, and there is no per-field "push" command to remember. All issue commands work from anywhere inside an issue subtree.