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, 44 insertions, 6 deletions

diff --git a/pearl.el b/pearl.el
index ae02f1f..95856ca 100644
--- a/pearl.el
+++ b/pearl.el
@@ -228,6 +228,16 @@ leave the buffer expanded after updates."
   :type 'boolean
   :group 'pearl)
 
+(defcustom pearl-help-header t
+  "When non-nil, render a folded \"* Pearl\" heading atop each Linear file.
+The heading collapses on open (via a `:VISIBILITY: folded' property) and carries
+the edit-then-save reminder, the keymap cues, and the priority-cookie legend, so
+the help is discoverable without a dozen lines of `#' preamble cluttering the
+buffer.  It has no `LINEAR-ID', so save and merge ignore it.  Set to nil to omit
+it entirely, leaving just the machine `#+' keywords."
+  :type 'boolean
+  :group 'pearl)
+
 (defcustom pearl-title-case-headings nil
   "When non-nil, render issue titles in the heading in smart title case.
 The default is nil: titles render verbatim, exactly as Linear stores them, so
@@ -3603,6 +3613,35 @@ only add the ones a failed team fetch left out."
                          issues))))
       (append team-states issue-states))))
 
+;; Forward declaration: `pearl-keymap-prefix' is a defcustom in the keymap
+;; section below, but the help header (rendered here) reads it for the key cues.
+(defvar pearl-keymap-prefix)
+
+(defun pearl--help-header-string ()
+  "Return the folded \"* Pearl\" heading shown atop a Linear file.
+A collapsible section (`:VISIBILITY: folded') carrying the edit-then-save
+reminder, a note that the section is local-only, the keymap cues, the
+priority-cookie legend, and how to hide it.  The cues reflect the live
+`pearl-keymap-prefix' so a customized prefix shows the right chords; a nil
+prefix (no binding) points at \\[execute-extended-command] instead.  The
+heading carries no `LINEAR-ID', so save and merge skip it (they walk only
+`LINEAR-ID'-bearing subtrees -- see `pearl--issue-subtree-markers')."
+  (let ((p pearl-keymap-prefix))
+    (concat
+     "* Pearl\n"
+     ":PROPERTIES:\n"
+     ":VISIBILITY: folded\n"
+     ":END:\n"
+     "Edit issues in this buffer, then save to push your changes to Linear.\n"
+     "This section is never sent to Linear. It is local help text only.\n"
+     (if p
+         (concat
+          (format "Inline edits (title, body, comments, [#A] cookie) save with %s s.  %s S saves all.\n" p p)
+          (format "State / assignee / labels: %s e s / e a / e l.  %s g refreshes; %s m menu; %s f s pick source.\n" p p p p))
+       "No prefix is bound (pearl-keymap-prefix is nil); reach commands via M-x (e.g. M-x pearl-save-issue, M-x pearl-menu).\n")
+     "Priority cookies: [#A] Urgent, [#B] High, [#C] Medium, [#D] Low, no cookie = None.\n"
+     "Hide this section: set pearl-help-header to nil (M-x customize-variable RET pearl-help-header).\n")))
+
 (defun pearl--build-org-content (issues &optional source truncated states account)
   "Build the Org content string for the linear org file from ISSUES.
 SOURCE is the active-source descriptor recorded in the header so a later
@@ -3631,13 +3670,12 @@ no side effects."
       (insert (format "#+LINEAR-FILTER: %s\n" (pearl--summarize-filter filter)))
       (insert (format "#+LINEAR-COUNT: %d\n" (length issues)))
       (insert (format "#+LINEAR-TRUNCATED: %s\n" (if truncated "yes" "no")))
-      ;; Affordance preamble (org comments -- not rendered content).  Keys
-      ;; reference the live `pearl-mode' keymap so the cues match what the
-      ;; user actually types, not the M-x longhand.
-      (insert "#\n")
-      (insert "# Inline edits (title, body, comments, [#A] cookie) save with C-; L s.  C-; L S saves all.\n")
-      (insert "# State / assignee / labels: C-; L e s / e a / e l.  C-; L g refreshes; C-; L m menu; C-; L f s pick source.\n")
+      ;; Optional folded help heading carries the cues + priority legend in a
+      ;; collapsible section (`pearl-help-header'), replacing the raw `#'
+      ;; affordance comments.  It has no `LINEAR-ID', so sync/merge skip it.
       (insert "\n")
+      (when pearl-help-header
+        (insert (pearl--help-header-string)))
 
       ;; Single top-level parent so the issues are sortable as a group
       ;; (org-sort on this heading) instead of orphan headings, and so a