feat(render): foldable Pearl help header, dropping the # comments

The preamble carried two raw "# ..." affordance comment lines on every Linear file. Those move into a folded "* Pearl" heading, gated by a new pearl-help-header defcustom (default t). It collapses on open via a :VISIBILITY: folded property and carries the edit-then-save reminder, a note that the section is never sent to Linear, the key cues (derived from pearl-keymap-prefix, falling back to M-x when no prefix is bound), the priority-cookie legend, and how to hide it. Set the defcustom to nil for a minimal preamble of just the machine keywords. The heading also doubles as the "you're in Pearl" marker at the top of the buffer.

The heading has no LINEAR-ID, so save and merge skip it for free: they walk only LINEAR-ID-bearing subtrees. A forward declaration of pearl-keymap-prefix keeps the byte-compiler happy, since its defcustom lives later in the file than the renderer.

This is the human-content half of the preamble work. The machine #+ keyword lines (title, STARTUP, TODO, LINEAR-SOURCE, the provenance fields) are still visible. Hiding those is the remaining part of the task.

1 files changed, 48 insertions, 3 deletions

diff --git a/tests/test-pearl-output.el b/tests/test-pearl-output.el
index e3208e3..7edc29d 100644
--- a/tests/test-pearl-output.el
+++ b/tests/test-pearl-output.el
@@ -51,9 +51,10 @@
     (should (string-match-p "^#\\+title: Linear — My open issues$" out))
     (should (string-match-p "^#\\+LINEAR-SOURCE: " out))
     (should (string-match-p "^#\\+LINEAR-COUNT: 0$" out))
-    ;; affordance preamble is present as org comments, not content -- match
-    ;; the save cue loosely so a future rephrase doesn't break the test
-    (should (string-match-p "^# .*save" out))))
+    ;; the help header (default on) carries the cues now; the raw `#' affordance
+    ;; comments are gone
+    (should (string-match-p "^\\* Pearl$" out))
+    (should-not (string-match-p "^# " out))))
 
 (ert-deftest test-pearl-build-org-content-source-roundtrips ()
   "The serialized source in the header reads back to the original plist."
@@ -81,6 +82,50 @@ independent of `pearl-title-case-headings' (which governs issue headings only)."
       (should (string-match-p "^#\\+title: Linear — my open bugs$"
                               (pearl--build-org-content '() source))))))
 
+;;; --build-org-content help header (`pearl-help-header')
+
+(ert-deftest test-pearl-help-header-string-content ()
+  "The help header is a folded \"* Pearl\" heading carrying the
+edit-then-save reminder, key cues, the priority legend, and how to hide it.
+It has no LINEAR-ID, so save and merge skip it."
+  (let ((s (pearl--help-header-string)))
+    (should (string-match-p "^\\* Pearl$" s))
+    (should (string-match-p "^:VISIBILITY: folded$" s))
+    (should (string-match-p "save" s))                ; edit-then-save / key cue
+    (should (string-match-p "\\[#A\\] Urgent" s))     ; priority legend ends...
+    (should (string-match-p "\\[#D\\] Low" s))        ; ...A through D
+    (should (string-match-p "never sent to Linear" s)) ; local-only note
+    (should (string-match-p "pearl-help-header" s))   ; how to turn it off
+    (should-not (string-match-p "LINEAR-ID" s))))
+
+(ert-deftest test-pearl-help-header-reflects-prefix ()
+  "The key cues use the live `pearl-keymap-prefix'; a nil prefix points at M-x
+instead of printing a bogus chord."
+  (let ((pearl-keymap-prefix "C-c l"))
+    (should (string-match-p "C-c l s" (pearl--help-header-string))))
+  (let* ((pearl-keymap-prefix nil)
+         (s (pearl--help-header-string)))
+    (should (string-match-p "M-x" s))
+    (should-not (string-match-p "nil s" s))))
+
+(ert-deftest test-pearl-build-org-content-help-header-on ()
+  "With `pearl-help-header' non-nil, the folded help heading is emitted and the
+raw `#' affordance comments are not."
+  (let* ((pearl-help-header t)
+         (out (pearl--build-org-content '() '(:type filter :name "X" :filter nil))))
+    (should (string-match-p "^\\* Pearl$" out))
+    (should (string-match-p "^:VISIBILITY: folded$" out))
+    (should-not (string-match-p "^# " out))))
+
+(ert-deftest test-pearl-build-org-content-help-header-off ()
+  "With `pearl-help-header' nil, neither the help heading nor the `#' comments
+appear -- a minimal preamble of just the machine keywords."
+  (let* ((pearl-help-header nil)
+         (out (pearl--build-org-content '() '(:type filter :name "X" :filter nil))))
+    (should-not (string-match-p "Pearl" out))
+    (should-not (string-match-p "^# " out))
+    (should (string-match-p "^#\\+title:" out))))
+
 ;;; --read-active-source
 
 (ert-deftest test-pearl-read-active-source-absent ()