feat: resolve a cycled TODO keyword to its Linear state at save

Cycling a ticket's TODO keyword (C-c C-t) now counts as a state edit. The dirty scan gains a keyword-cycle arm: state is dirty when the explicit id moved off its baseline (the picker arm, as before) or when the keyword diverged from the synced state name's slug. At save, the picker arm pushes the explicit id; the keyword-cycle arm resolves the keyword to a team state id by slug match, first by position, and pushes that. A keyword no team state matches is reported skipped rather than guessed.

set-heading-state now slugifies the keyword instead of the static-map lookup, so the picker writes the same keyword the renderer derives. Without that, a picker edit to a non-standard state would read as permanently cycled. That retires pearl--map-linear-state-to-org, whose only caller this was, and its tests.

1 files changed, 4 insertions, 11 deletions

diff --git a/README.org b/README.org
index 1ae0131..860d41a 100644
--- a/README.org
+++ b/README.org
@@ -221,19 +221,12 @@ Only comments you authored are editable or deletable. Pearl refuses edits and de
 
 *** State and the TODO keyword
 
-=pearl-state-to-todo-mapping= maps Linear state names to Org TODO keywords, so a fetched issue renders with a keyword you recognize:
+A fetched issue renders with a TODO keyword derived from its Linear state name: the name is slugified (upcased, non-alphanumeric runs collapsed to hyphens), so "In Progress" becomes =IN-PROGRESS= and "Dev Review" becomes =DEV-REVIEW=. The buffer's =#+TODO= line is built from the real workflow states of the teams on display, so every keyword you see is a state that team actually has, partitioned active / done by Linear's state type.
 
-#+begin_src emacs-lisp
-  (setq pearl-state-to-todo-mapping
-        '(("Todo" . "TODO")
-          ("In Progress" . "IN-PROGRESS")
-          ("In Review" . "IN-REVIEW")
-          ("Backlog" . "BACKLOG")
-          ("Blocked" . "BLOCKED")
-          ("Done" . "DONE")))
-#+end_src
+You change a ticket's state two ways, both reconciled and pushed at the next save:
 
-Make sure your =org-todo-keywords= include every keyword you map to. Change a ticket's state with =pearl-edit-state=, which reaches every state on the team -- including ones the keyword set doesn't cover. (Cycling the keyword to drive the state change directly, and deriving the keyword set from the team's real states, are planned follow-ups.)
+- Cycle the keyword with =C-c C-t= (or =S-<right>= / =S-<left>=). The keyword you cycle to is matched back to a team state by the same slug rule, so cycling =TODO= → =IN-PROGRESS= moves the ticket to the "In Progress" state. A keyword no team state slugifies to can't be resolved, so that save is reported skipped.
+- =pearl-edit-state= completes over every state on the team and writes the keyword for you. Use it to reach a state whose keyword you don't remember, or one the visible keyword set doesn't cover.
 
 ** The Org File
 :PROPERTIES: